feat(peer): follow supersession + name hint when session citations go stale

[heavygee]

Field report

An agent received a standard nametag citation [Antevorta setup](/sessions/36985b00-e7ba-448c-812c-9eb4f611ff6e).

1. inspect_peer on that id worked (5 messages, plausible transcript).
2. A few turns later ping_peer on the same id failed: Session not found.
3. Immediate retry of inspect_peer on the same id also failed: no session matching prefix.
4. Recovery: list_peers showed Antevorta setup under a different id (0b350082-d60d-4705-b0ab-d0d80a861660).

Root cause (code)

Peer tools (inspect_peer, ping_peer, hapi inspect-peer, hapi ping-peer) resolve targets only via GET /api/sessions list + prefix match (cli/src/modules/pingPeer/pingPeer.ts). They do not:

• follow metadata.supersededBySessionId (web already does — web/src/routes/sessions/followSupersedingSession.ts; REST contract warns resume/reopen may return a different id — docs/api/client-contract/rest.md), or
• suggest name-based fallback when an id vanishes.

When a session is superseded and the old row is deleted (sessionCache.mergeSessionData with deleteOldSession: true), the cited id disappears entirely from the namespace. A successor with the same display name may exist — silent failure with no hint to try list_peers.

This is not the tiann#1618 soft-nametag trust model; it is citation durability / session identity continuity for Layer 0 peer tools.

Proposed fix (pick phased)

P0 — supersession chain: when resolving by id, if row exists with supersededBySessionId, follow to successor (same as web navigation). Also try direct GET /api/sessions/:id before list-only lookup for exact UUIDs.

P1 — helpful not-found: when prefix/id misses, parse citation title if present ([title](/sessions/id)) and list same-name candidates from list_peers; error text should mention supersession and list_peers, not bare "not found".

P2 — tombstones (product policy): consider keeping superseded rows as non-deletable aliases instead of deleteOldSession: true merges, so old ids keep redirect metadata.

Related

• feat(peer): make ping_peer handoffs reply-addressable tiann/hapi#1203 (reply-addressable peer handoffs — nametag shipped in feat(peer): nametag-only ping_peer reply attribution tiann/hapi#1618)
• feat(a2a): steer agents from session citations to inspect_peer tiann/hapi#1370 (session citation steer in prompts)
• Reporter session: /sessions/1904a934-8dc4-467e-b56c-28a121a0262b

Acceptance

Stale [title](/sessions/old-id) citations either land on the successor session or return an actionable error naming the likely replacement id.

[heavygee]

Server-side corroboration (oos-linux /var/lib/hapi/hapi.db, 2026-08-27 ~10:59 UTC)

Queried live hub SQLite after field repro:

id	status
36985b00-e7ba-448c-812c-9eb4f611ff6e	No row — fully gone (0 messages on old id)
0b350082-d60d-4705-b0ab-d0d80a861660	Present — name=Antevorta setup, path=/home/heavygee/coding/janus-oos, flavor=claude, 766 messages

Timestamps (hub ms → UTC):

• Old id updatedAt from successful inspect: 2026-08-26 09:00:00 (matches reporter — ~26h stale dormant row)
• New id created_at: 2026-08-27 10:51:52
• New id updated_at: 2026-08-27 10:56:41
• Oldest message on new id: 2026-08-17 11:00:46 → history migrated wholesale

No supersededBySessionId on the surviving row. This was mergeSessions(..., { deleteOldSession: true }) (hard delete), not OpenCode supersession tombstone.

Likely trigger: resume/spawn returned a new session id and hub merged+deleted the old row (syncEngine.ts ~3146–3150: when spawnResult.sessionId !== access.sessionId → mergeSessions). Dedup merge path (sessionCache.ts ~1589) is another candidate for inactive duplicates.

Reporter observation stands: no overlap window in list_peers — delete is atomic from client view once merge completes. The gap between step-1 inspect (stale but present) and step-3 ping (gone) is consistent with merge completing in that window (~10:51 UTC today).

Fix implication: P0 should cover merge/delete redirects, not only supersededBySessionId. Options: tombstone old ids with redirect metadata, or teach inspect_peer/ping_peer to follow merge target when old id 404s + name/path match.