feat: expose last heartbeat timestamp on /status endpoint

[nathanclevenger]

Summary

The /status endpoint should include the lastHeartbeat timestamp so that consumers (monitoring tools, dashboards, other services) can verify the agent is alive and determine how recently it checked in — without needing a separate endpoint or internal access.

---

Problem

Currently, /status returns basic health info but omits heartbeat timing. This means:

• External monitors can't detect a "running but stale" agent (process up, heartbeat stopped)
• Dashboards have no single source of truth for liveness

---

Acceptance Criteria

• GET /status response includes a lastHeartbeat field
• lastHeartbeat is an ISO 8601 UTC timestamp (e.g. "2026-02-23T13:00:00.000Z")
• If no heartbeat has ever fired, lastHeartbeat is null
• The value updates correctly after each heartbeat cycle
• No breaking changes to existing /status response fields
• Unit test covers: first run (null), after one beat, after multiple beats

---

Response Shape (target)

{
  "status": "ok",
  "uptime": 3600,
  "lastHeartbeat": "2026-02-23T13:00:00.000Z"
}

---

Out of Scope

• Heartbeat history / log
• Alerting or thresholds
• Changes to heartbeat frequency

---

Labels: enhancement, observability
Estimate: TBD — pending technical assessment from Cody

[nathanclevenger]

🔍 Technical Assessment (via Cody)

Current State

/status endpoint (src/channels/server.ts, lines 34–41) returns:

{ "agent", "status", "pendingMessages", "uptime", "dailyLog" }

No heartbeat timestamp today.

heartbeat.ts has no persistent lastHeartbeat state. A local tickStart is captured inside tick() for logging only — it's discarded after each tick. No DB column tracks this either.

---

What Needs to Change

File	Change
src/daemon/heartbeat.ts	Add let _lastHeartbeatAt: number | null = null, assign it at end of successful tick(), export a getLastHeartbeatAt() getter
src/channels/server.ts	Import getLastHeartbeatAt, add lastHeartbeat field to /status response (ISO 8601 or null)
New test file	Unit test for null state + post-tick state (mock heartbeat.ts)

No circular import risk — server.ts already imports from heartbeat.ts.

---

One Open Question

Persist across restarts? If lastHeartbeat must survive a process restart, a DB column or KV entry is needed (would push this to M). The current request doesn't specify this — assuming in-memory is fine for now. @nathanclevenger — worth confirming.

---

Estimate: 🟢 S (< 1 hour)

The core change is ~4 lines across 2 files. The only real work is writing a focused unit test (~20–30 min). Nothing structural changes.

Scope creep risk: persisting across restarts would bump to M.

[nathanclevenger]

Addressing doctrine ruled (founder, 2026-08-24): apis.ax has NO subdomains — it is the one agent-first everything API; capabilities are paths/operations on the single surface. ledger.apis.ax was an agent coinage, never ruled — corrected to apis.ax/ledger. By contrast *.api.ht is the subdomain grammar (one linked tool per subdomain) — that pattern is api.ht's identity, not a general estate convention. Re-address sweep dispatched: worker route, LEDGER.md convention, and every row's railLedger pointer move to https://apis.ax/ledger/faces?face=.

[nathanclevenger]

Identity ruling (founder, 2026-08-24), supersedes the ledger-as-service framing: the ledger is the payment mechanism of the apis.ax experience, not a property — no separate site, no own card/brand. An agent without x402 or card access answers questions / generates objects / does tasks to EARN credits and use the APIs — balance and earning are part of the agent's apis.ax ACCOUNT. The worker/package ('rail-ledger') is implementation only and never appears on a public face; its operations are operations of apis.ax (account/balance/credits paths). The 402 OFFER estate-wide presents the earn path in exactly that framing, verification-gated as ruled.