Skip to content

ADR-129: Instance suffix and heartbeat liveness for attend identity

Summary

  • Decided: attend handles naming and liveness with two separate mechanisms. For naming, a registry file per working directory gives each session an instance suffix, Greek letters spelled in ASCII and then numbers past 24, so two sessions in one directory show as Jovan-alpha and Jovan-beta. A session keeps its suffix for its whole life and gets it back on resume, entries unused for 7 days are reclaimed, and the suffix always shows, even for a session alone in its directory. For liveness, each session's attend touches a heartbeat file on every tick, and a session counts as alive when its Claude process runs and its heartbeat is under 90 seconds old. A stale heartbeat never frees a name. An addendum of 2026-10-13 adds a 30-second beat from the attend mod and counts a session alive while the Claude Code process its enrollment record names still runs on this host.
  • Trades away: Every display of a nickname changes at once, and agents see their own names change. attend gains two new state directories to debug, a resume after more than 7 days may get a different suffix, and each tick writes one file per session. The record rejected sequential numbers, hex suffixes from the session ID, having a resumed session give up its letter, assigning letters at render time, a suffix only on collision, SQLite, and storing assignments in _groups.yaml.
  • One-way? No. The record does not discuss reversal. Both mechanisms are flat files under ~/.cache/attend/, and make purge-attend-state wipes them.
  • Probes: Not confident (always-suffix): Should a session alone in its directory still show its suffix? Yes or no. Not confident (gc-window): Is seven days the right time before an unused suffix is reclaimed? Yes or no.
  • Inversion: At one end, names are computed from the live sessions each time they are shown, with no stored state. At the other, a stored registry fixes each session's name for its life. This record sits at the second end and keeps liveness in a separate file so a quiet session keeps its name.

Context

attend's identity and liveness systems each have a corner case that has surfaced in real use. The two cases are independent in cause but adjacent in effect — both produce a wrong picture of "who is here" — and they should be addressed in one decision so the design boundary between them is explicit.

1. Same-cwd identity collision. agent_identity::Identity::for_cwd(cwd) (tools/agent-identity/src/identity.rs) is a pure function of the cwd path: an FNV-1a hash of the canonical path indexes into the nickname pool. The original design comment justifies this — "a claude restarting in the same cwd keeps the same name" — and it does that job correctly when there is at most one session per cwd. It does not cover concurrent invocations: two claude processes started in the same directory hash to the same index and present as the same Jovan (myproj), with the same color and style. The user has reproduced this by launching claude twice in the same directory; both render identically in attend peers, in chat, and in any signal authored by either side.

2. Stale registration and ghost agents. tools/attend/src/groups.rs:347 defines session_alive(sid) as a stub that returns true unconditionally with a TODO comment. As a consequence, _groups.yaml accumulates dead members across sessions and is never cleaned by the liveness check that the rest of the codebase assumes is doing the job. The visible failure surfaces in attend-chat: when the chat TUI reloads, the chip legend (tools/attend-chat/src/chip.rs:142, known_identities) builds entries from buffered signals and does not filter by liveness — every agent that has ever sent a message in this cwd appears in the legend, including agents whose claude session has long exited. The existing liveness path through ~/.claude/sessions/*.json plus pid_is_claude catches "claude exited" but not "claude alive, attend not running" — the agent is unreachable, but the PID check passes because the claude process itself still exists.

The two problems are not the same problem. Collision is about naming: two real, alive sessions need distinguishable identities. Liveness is about display: the registry of who-has-spoken needs to be filtered against who-is-still-here. Conflating them — for example, by freeing a name when its session goes stale — would make names re-bind unpredictably and break peer references like @Jovan-alpha after a transient quiet period. Keeping them separated is load-bearing.

Both surfaces matter today because attend, chat, and the focus-groups model (ADR-118) increasingly assume legible peer identity: human steering decisions, peer-to-peer addressing, and the attend-chat legend (ADR-124) all rely on the displayed name being unambiguous and the displayed roster being live.

Decision

Adopt two independent mechanisms, one per concern.

Independence invariant: liveness display never touches name allocation. A heartbeat going stale does not free a registry slot. A registry slot expiring (under age-based GC) does not signal liveness. This separation is what keeps names stable across transient quiet periods — peer references like @Jovan-alpha survive a 30-second pause in the heartbeat without re-binding to someone else.

Instance registry — naming

A new persistent file per cwd records which session holds which instance discriminator.

  • Location: ~/.cache/attend/instances/<encoded-cwd>.yaml, parallel to the existing ~/.cache/attend/signals/<encoded-cwd>/ layout.
  • Schema: session_id → { instance: <string>, registered_at: <iso8601>, last_seen: <iso8601> }. The field is named instance, not letter. The file holds instance assignments; Greek letters are the current discriminator vocabulary, but the storage shape does not lock that in. Future allocators can swap their vocabulary without changing the on-disk format.
  • Allocator (current): Greek letters in ASCII spelling — alpha, beta, gamma, ..., omega (24 slots). ASCII spelling, not glyphs, matches the existing constraint at tools/agent-identity/src/names.rs:5 (ASCII only, no diacritics) so that @-completion remains keyboard-portable. Numeric fallback past 24: Jovan-25, Jovan-26, and so on.
  • Slot semantics: slots are session-bound. Once a session_id holds alpha, it holds alpha for the life of that session — no reclamation while the session is live. New sessions skip taken slots and take the next-free letter. Resume always reclaims the original assignment. This is the property that makes peer references stable.
  • Concurrency: read-modify-write under flock(LOCK_EX) on a sentinel <encoded-cwd>.yaml.lock file, not on the data file. Locking the data file does not serialize concurrent registers because flock state is keyed on the open-file-description — the kernel inode — not the path. The data file is renamed atomically (.tmp → .yaml) on every commit, so a fresh opener of the path after the rename gets a different inode and a different lock; the previous holder's lock no longer contends. The sentinel never moves, so its inode is the stable serializer. Two simultaneous fresh sessions racing for alpha: the lock orders them; the second writer reads after the first commits and takes beta.
  • Age-based GC: entries with last_seen older than 7 days are reclaimable. This handles unbounded registry growth on long-lived projects. Trade-off: a resume after more than 7 days of inactivity may receive a different letter, because the slot may already have been reclaimed by another session. This is acceptable — a week-stale resume is far from the "I just stepped away and came back" case where rename surprise actually matters.
  • Render: always emit the suffix, even when the session is solo. Jovan-alpha, never the conditional Jovan (solo) / Jovan-alpha (collision). Always-on is chosen over conditional for predictable pattern matching: every render site, every grep, every agent-self-reference produces a name with the same shape.
  • Render sites that must consume the registry:
  • tools/attend/src/identity_view.rs::render_sender_label
  • tools/attend/src/cmd/peers.rs (agent column)
  • tools/attend-chat/src/chip.rs (chip rendering, known_identities, and resolve_nickname)

Heartbeat sidecar — liveness display

A separate per-session file records that the session's attend is currently running.

  • Location: ~/.cache/attend/heartbeat/<session-id>, one file per session.
  • Encoding: mtime is last_seen. There is no body to parse. Each tick is a touch.
  • Touched per attend tick, in the existing tick loop in tools/attend/src/cmd/run.rs.
  • Liveness predicate: now - mtime < grace, with grace = 90s — three times the base sensor interval of 30s. Long enough to ride out a paused tick or a slow filesystem; short enough to drop a dead attend within a couple of minutes.
  • Consumers:
  • tools/attend/src/groups.rs:347 session_alive(sid): replace the return true stub with pid_is_claude(sid_owner) AND heartbeat_fresh(sid). This is the predicate the rest of the codebase already calls; fixing it propagates correctness through _groups.yaml cleanup and elsewhere. It also catches "claude alive, attend not running," which the PID-only check misses.
  • tools/attend-chat/src/chip.rs::known_identities: filter signal-derived identities by liveness so dead agents disappear from the chip legend. Historical messages stay in the buffer (the conversation record is not destructive), but their senders are rendered dimmed or muted when the sender's heartbeat is stale, so the buffer reads correctly without implying the speaker is still here.
  • No write contention: each session writes only its own file.

Operational

A new make purge-attend-state target wipes ~/.cache/attend/ for clean-base recovery. It is never invoked automatically. After the existing make attend, make attend-rebuild, make attend-chat, and make attend-chat-rebuild targets, an advisory hint is printed pointing at the purge target, so users with an inconsistent cache from an older binary know how to reset cleanly.

Consequences

Positive

  • Names disambiguate same-cwd peers. Two simultaneous claude sessions in ~/Projects/myproj render as Jovan-alpha and Jovan-beta, with stable colors and styles inherited from the base nickname.
  • Peer references survive quiet periods. Because liveness staleness never frees a registry slot, @Jovan-alpha continues to mean the same session even if its attend tick paused briefly. Agent self-model is preserved across resumes.
  • Ghost agents disappear from the chat legend. With the heartbeat predicate replacing the return true stub, known_identities no longer accumulates every agent that ever spoke in the cwd. The chip legend reflects who is currently reachable.
  • _groups.yaml self-cleans. The same predicate, fixed in one place, flows through to focus-group cleanup. Stale members drop on the next peer poll, restoring the cleanup behavior ADR-118 already assumed was working.
  • Catches "claude alive, attend not running." PID-only liveness misses the case where the claude process exists but its attend has exited or hung; the heartbeat catches it because the heartbeat file stops being touched regardless of process state.
  • Filesystem-as-state continuity. Both mechanisms fit attend's existing storage model — flat files under ~/.cache/attend/ — so they are debuggable with ls and cat, and require no new dependency.
  • Discriminator vocabulary is swappable. Storing instance: alpha (rather than letter: alpha) lets a future allocator change vocabulary without a file-format migration.

Negative

  • Identity contract change. Every existing display surface for nicknames now carries an instance suffix. Jovan becomes Jovan-alpha even for a solo session. Render sites listed under Decision (identity_view.rs, cmd/peers.rs, chip.rs) must be updated together — partial rollout will produce inconsistent legends. Agents will also see their own displayed name change, which they encounter in self-reference (I am Jovan-alpha) and in addressed peer references.
  • Two new state shapes. ~/.cache/attend/instances/ and ~/.cache/attend/heartbeat/ are added to attend's filesystem footprint. Recovery from corrupt state is the new make purge-attend-state target; absent that, debugging "why is my name wrong" requires inspecting two locations.
  • Resume-after-7-days renames. Age-based GC means a resume after a week of inactivity may receive a different instance letter than it had previously. Mitigation: the rename is far enough from active use that the surprise is small, and 7 days is a tunable upper bound on registry growth. Users with very long lived projects who still want stable names across very long pauses can lengthen the GC threshold.
  • Heartbeat I/O cost. Each attend tick writes one file. The cost is negligible per session, but on a multi-session host it adds up to N files touched per tick interval. Mitigated by the 30s base sensor cadence and the per-session file scoping.
  • Greek-letter pool exhaustion. 24 concurrent sessions in one cwd is unreachable in practice today, but the numeric fallback (Jovan-25) is intentionally ugly so that hitting it surfaces as a signal that the cwd is overloaded.

Neutral

  • Heartbeat staleness does not free a name. This is the explicit design boundary, not an emergent property. A session that is registered but unreachable continues to hold its instance letter until its registry entry GCs by age.
  • Heartbeat is mtime-only. No file body, no parser. Adding fields to the heartbeat in the future would require a real format; today there is intentionally none.
  • Always-on suffix. Solo sessions display Jovan-alpha rather than Jovan. The user-visible cost is a slightly longer name; the gain is that every render site can build the label from a single rule.

Alternatives Considered

  • Sequential numbering — Jovan2, Jovan3. Rejected. Order-dependent on registration race; observers would not agree on numbering without a registry; and it breaks "same name across restart" the moment a peer joins, because the restarting session would re-number.
  • Hex-suffix from session_id — Jovan-7c4a. Stable per session, zero coordination needed, no registry. Rejected because the suffix is unmemorable for both humans and agents in conversation. "Tell -7c4a to do X" is a worse UX than "tell beta to do X," and the value of the suffix is precisely that it surfaces in human and agent speech.
  • Resumer yields on conflict. Initial proposal: when a session resumes and finds its old letter held by a live session, it takes the next-free letter. Rejected. Name changes during resume break agent self-model and break references made by humans and peers (@Jovan-alpha please...). The current decision — slots are session-bound for the life of the session, no reclamation while live — is the property that makes references durable.
  • Stateless render-time computation. Sort same-cwd live sessions by mtime and assign letters in order at render time. Simpler, no registry, no GC. Rejected because letters drift when peers exit: the surviving sessions get re-lettered in place, which has the same self-model and reference-breaking problem as resumer-yields.
  • Conditional suffix — only on collision. Cleaner UX for solo sessions (plain Jovan) but every render site must consult the live-set count to know whether to append. Rejected in favor of always-on for predictable pattern matching: one rule, one shape, every site.
  • SQLite for state. Considered seriously. Three new state shapes, CAS semantics, and a growing YAML parser are real costs. Rejected because: the data is genuinely tiny (handfuls of rows per cwd); attend's whole architecture is filesystem-as-state already (signals, session.json, _groups.yaml, sensor checkpoints — all flat files); adding SQLite for part of state creates two consistency models inside attend; mtime-as-heartbeat is a perfect Unix-y fit that dies inside a database; and debuggability via cat and ls is load-bearing for users diagnosing identity problems. SQLite is reconsidered later if attend grows a real query surface — inbox search, threading analytics, cross-session aggregation — that flat files no longer serve.
  • Field on _groups.yaml for instance assignments. Rejected. _groups.yaml is scoped to named focus groups (ADR-118). Mixing implicit per-cwd identity assignments into it muddies the contract: that file is about named-group membership, not about identity. Keeping instance assignments in their own file preserves the separation.

Addendum, 2026-10-13: a listening session whose process runs is alive

Appended after acceptance; nothing above is changed. A session hosted by the attend mod (ADR-406) has no attend run, so no tick touches its heartbeat. The poll's drain and the Stop-hook drain touch it, and both run only between turns. The heartbeat therefore went stale during any turn longer than the grace, and at a slow poll interval longer than it. attend-chat then refused a direct message to the live head session: "@Chaucer-beta is quiet (no heartbeat) and would not read this". The message would have been delivered at the turn's end.

  • The mod beats on its own timer. attend listen beat touches a listening session's heartbeat and does nothing else; for a session that does not listen it writes nothing. The mod runs it every 30 seconds, a third of the grace, during turns and at the slow poll interval alike.
  • The liveness predicate gains a process arm. attend_presence::alive holds a member alive when it is in the caller's set of running sessions, when its heartbeat is within the grace, or when it is enrolled and the Claude Code process its enrollment record names still runs on this host: the pid is held by the process that started at the recorded start time. A recorded process that has exited, or a pid held by a later process, does not count, and neither does a session that stopped listening. The heartbeat still decides "claude alive, attend not running" for a session that never enrolled.
  • Another host is judged by its heartbeat. The process key records its host, <pid>-<start>@<host>. A key from another host, or one with no host, is unknown here: neither alive nor exited. A session there is alive by its heartbeat alone, as ADR-406 item 12 requires of a remote store, and is never judged to have exited.
  • A session record's pid is read with its start time. A record's process runs while a process holds its pid that started no later than the record's startedAt and a minute's slack; a later process holding the pid means the record's has exited.