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.