projmux 0.16.0 → 0.16.1

package/docs/agent-message-replies.md

@@ -1,10 +1,24 @@
 # Explicit reply recovery
 
 An explicit Claude reply names the original request with `--reply-to`. The
-broker preserves that request's `conversationRef`, reverses its exact source
-and target routes, and retains peer, untrusted, coordination-only authority.
-Both activations and the original deadline must still be current. A reply
-cannot extend that deadline. Source metadata remains an unverified routing
+broker preserves that request's `conversationRef`, reverses its source and
+target Agents, and retains peer, untrusted, coordination-only authority. The
+reply goes to each Agent's current activation, and the original deadline must
+still be current. A reply cannot extend that deadline.
+
+Correlation follows the Agent and its provider conversation, not one
+activation. Either Agent may have been relaunched into the same conversation
+since the original, for example by `agent relaunch`: it now runs in a new Pane
+under a new activation, and a reply to the earlier message still commits and
+is delivered there. A reply to another Agent or on another provider is still
+refused as `invalid-explicit-reply-correlation`. When one of the original's
+Agents is now in another provider conversation (another Claude session), the
+reply is refused with `explicit-reply-conversation-changed` and stores
+nothing; the original cannot be answered there, so send a new message without
+`--reply-to`. A `--dialogue-reply-only` Agent's reply tool follows the same
+rule for the original's sender: it still permits a reply to a sender
+relaunched into the same conversation, and denies one to a sender now in
+another conversation. Source metadata remains an unverified routing
 claim; an explicit reply also requires the registered provider's descendant
 caller and any existing qualification and execution guard.
 
@@ -33,7 +47,7 @@ execution guard, use the existing bounded command without that flag:
 projmux agent message send uid:<original-source-agent> --reply-to <original-request-ref> -- '<corrected reply>'
 ```
 
-Operator input from the web client has no Agent route to reverse, so a reply
+Operator input from an operator client has no Agent route to reverse, so a reply
 to it is refused with `explicit-reply-operator-origin` and stores nothing.
 
 Within the same provider session, a reply also commits after the Claude lease
@@ -41,10 +55,52 @@ helper was replaced, for example by compact. The new helper did not push the
 original, so it reads the original from the durable store and judges it by the
 same checks. It reads the store only while its own route is the Registry's
 current authority for the Agent; a replaced or unregistered helper reads and
-writes nothing. `broker-reply-original-not-found` means the original is in
-neither the helper nor the store. `invalid-explicit-reply-correlation` means the
-reply's route or conversation does not match the original, or the helper is not
-the current one.
+writes nothing, and is refused with `broker-reply-helper-not-current`.
+`broker-reply-original-not-found` means the original is in neither the helper
+nor the store.
+
+## Reply refusal tokens
+
+Each refusal names its cause with one token. The CLI prints it after
+`replyTo=<ref>:`, the Claude helper returns it as the `reply-refused` reason,
+and the store returns it as the reply conflict reason. A token asks for one
+action, so two causes that need different actions never share one.
+`invalid-explicit-reply-correlation` is kept for a reply that does not match
+its original. Every refusal here except `broker-reply-outcome-unknown` comes
+before the reply is written anywhere: no provider saw it, so following the
+action cannot duplicate it. The retry rules below govern an attempt that was
+stored.
+
+| Token | Cause | Action |
+| --- | --- | --- |
+| `invalid-explicit-reply-correlation` | The reply's Agents, providers, or `conversationRef` do not match the original. | Check that `--reply-to` names a message you received and that the positional Agent is its sender. |
+| `explicit-reply-conversation-changed` | One of the original's Agents is now in another provider conversation. | Send a new message without `--reply-to`. |
+| `invalid-explicit-reply-envelope` | The reply itself is not a valid envelope, for example a payload over the limit. | Correct the reply, for example shorten it, and send it with a fresh ref. |
+| `explicit-reply-operator-origin` | The original is operator input from an operator client. | There is no Agent to answer; do not reply to it. |
+| `explicit-reply-deadline-expired` | The original's deadline has passed. | Send a new message without `--reply-to`. |
+| `explicit-reply-deadline-extended` | The reply's deadline is later than the original's. | Send the reply without a longer `--ttl`. |
+| `explicit-reply-source-route-stale`, `explicit-reply-target-route-stale` | The replying or the answered Agent's route is not its current one, for example during a relaunch, or the helper serving the reply is not the replying Agent's. | Wait until the Agent is registered again, then send the reply. |
+| `explicit-reply-route-stale` | The helper found a route no longer current at the moment it committed. | As above. |
+| `broker-reply-original-not-found` | The original is in neither the helper nor the store, for example because it was reclaimed. | Send a new message without `--reply-to`. |
+| `broker-reply-original-not-delivered` | The original never reached its target, so there is nothing to answer. | Inspect the original with `agent message status`; do not reply to it. |
+| `broker-reply-original-without-envelope` | The helper holds the ref, but not as an Agent message it can answer. | Send a new message without `--reply-to`. |
+| `broker-reply-helper-closed` | The replying Agent's Claude helper is shutting down, for example for a restart. | Wait for the new helper to register, then send the reply. |
+| `broker-reply-helper-not-current` | The Registry no longer names this helper as the Agent's current one; it was replaced. | Wait for the current helper to register, then send the reply. |
+| `broker-reply-unavailable` | The helper runs without a message broker and can commit no reply. | Relaunch the Agent so it starts a helper with one. |
+| `broker-reply-store-unavailable` | The helper could not use the durable message store. | Check the state directory, then send the reply. |
+| `broker-reply-store-busy` | Another writer held the message store. | Send the reply again. |
+| `broker-reply-store-malformed` | The message store file could not be read as a store. | Inspect the store; do not resend until it reads. |
+| `broker-reply-store-capacity` | The store is full and nothing can be reclaimed; see below. | Wait for records to be reclaimed. |
+| `reply-already-committed` | Another reply to the original was already committed. | Inspect it with `previousRef`; do not resend. |
+| `reply-ref-envelope-mismatch` | The same reply ref was used before with different content. | Use a fresh ref. |
+| `broker-reply-outcome-unknown` | A commit was attempted and its result is not known. | Inspect the reply status; do not resend. |
+
+A Claude helper that started before a build keeps that build's tokens until it
+is replaced. An older helper therefore still reports most of these causes as
+`invalid-explicit-reply-correlation`, and the CLI prints whichever token the
+helper sent.
+
+## Retries
 
 A same-ref call returns the original immutable receipt and never pushes again.
 Changing its payload is refused with the earlier ref and cause. A fresh ref
@@ -92,7 +148,7 @@ Each line carries the envelope's own key names:
 {"schemaVersion":1,"evictedAt":"…","reason":"retention","adapter":"claude-coordination",
  "messageRef":"…","conversationRef":"…","replyTo":"…",
  "state":"delivered","deliveryReason":"unspecified","handoffObserved":false,
- "acceptedAt":"…","terminalAt":"…","payloadBytes":466,
+ "acceptedAt":"…","terminalAt":"…","payloadBytes":466,"payloadSHA256":"…",
  "source":{"agentUID":"…","provider":"…"},
  "target":{"agentUID":"…","provider":"…"}}
 ```
@@ -105,14 +161,17 @@ the Pane and activation generation fence a live delivery, and the incarnation
 follows the provider conversation; all three mean nothing once the record has
 left the store. The envelope's `deadline` is not written. A line for operator
 input (see [Operator input](claude-coordination-endpoints.md#operator-input)) carries
-`"origin":{"kind":"operator","client":"web"}` in place of `source`; an Agent
+`"origin":{"kind":"operator","client":"<client>"}` in place of `source`; an Agent
 message's line has no `origin`. Every other key is always present.
 
 Lines written by earlier builds may still be in the same file. They carry full
 routes (`paneUID`, `activationGeneration`, `incarnation`), a `deadline`, and
 `outcomeUnknown` even when it is `false`, and they read the same way: a reader
 ignores keys it does not expect and reads an absent key as its zero value, so
-both shapes give the same edges, states and times. Both are `schemaVersion` 1.
+both shapes give the same edges, states and times. Lines written before the
+payload digest existed have no `payloadSHA256` key and read with an empty
+digest, which means "not recorded", not a mismatch; earlier lines are not
+backfilled. All of these are `schemaVersion` 1: every added key is additive.
 
 `schemaVersion` starts at 1 and follows the same rule as the
 coordination frame's field of that name: an absent or zero value reads as 1, and
@@ -121,8 +180,12 @@ discarding the line or failing. It is independent of the durable envelope
 version and of the store file version.
 
 The log does not keep the message body. It records `payloadBytes`, the original
-payload length, and has no `payload` key at all: the log is unbounded in time,
-and its intended consumers need the message graph, not its text.
+payload length, and `payloadSHA256`, the SHA-256 of the payload's exact bytes
+as 64 lowercase hex characters, and has no `payload` key at all: the log is
+unbounded in time, and its intended consumers need the message graph, not its
+text. The digest lets a consumer that holds the text elsewhere, such as a
+transcript, prove it is the same message; the reader and its consumers compute
+it with the same function (`PayloadSHA256` in `internal/core/agentmessage`).
 
 The active log rotates to `history.jsonl.1` once it would pass 8 MiB, replacing
 any earlier `history.jsonl.1`. At most two generations exist, so the log's disk

package/docs/architecture.md

@@ -418,27 +418,51 @@ Identity and naming:
   context may duplicate and is never a selector, reservation, ownerRef, or
   durable identity input. `metadata.labels` remains key/value classification;
   `metadata.annotations` remains non-identifying metadata such as an AI topic.
-- Creator provenance: when an explicit `create agent` (every spelling,
-  `--create-window`, and each Agent of a fan-out) or `create window --provider`
-  runs inside an Agent's managed Pane, the new Agent and its managed Pane carry
-  `projmux.io/creator-agent` (the creator Agent's bare UID),
-  `projmux.io/creator-pane` (that Agent's managed Pane's bare UID), and
-  `projmux.io/creator-basis: pane-chain`, written in the same transaction that
-  commits the Agent. They are recorded only when the unmasked ambient
-  `%N` (`__PROJMUX_RUNTIME_ANCHOR_PANE`, then `TMUX_PANE`) is exactly one live
-  Registry Pane, that Pane round-trips with its owning Agent's
-  `status.paneRef`, one `display-message` confirms it on the create's own
-  app-owned socket and server pid, and the create process descends from its
-  `#{pane_pid}`. Any failed check writes none of the keys and changes nothing
-  else about the create. Stderr gets one `creator not recorded: <reason>` line
-  only when the ambient Pane is a live Agent Pane but a later check fails; an
+- Creator provenance: every Agent create records on the new Agent and its
+  managed Pane, in the same transaction that commits the Agent, exactly one of
+  these, decided once per create (a fan-out records the same one on every
+  Agent). `projmux.io/creator-basis` names the kind of evidence, and only the
+  keys that evidence proves are written:
+  1. `pane-chain`, with `projmux.io/creator-agent` (the creator Agent's bare
+     UID) and `projmux.io/creator-pane` (that Agent's managed Pane's bare
+     UID): an explicit `create agent` (every spelling, `--create-window`, and
+     each Agent of a fan-out) or `create window --provider` ran inside an
+     Agent's managed Pane. It is recorded only when the unmasked ambient `%N`
+     (`__PROJMUX_RUNTIME_ANCHOR_PANE`, then `TMUX_PANE`) is exactly one live
+     Registry Pane, that Pane round-trips with its owning Agent's
+     `status.paneRef`, one `display-message` confirms it on the create's own
+     app-owned socket and server pid, and the create process descends from its
+     `#{pane_pid}`. It always wins.
+  2. `explicit`, with `projmux.io/creator-agent` only: the caller declared
+     `--creator uid:<agent>` and no pane chain was recorded. The declaration
+     must name an Agent in the Registry, or the create is refused before
+     anything changes. A declaration that disagrees with a recorded pane chain
+     is dropped, and stderr gets one `creator declaration not recorded:
+     pane-chain-disagrees (--creator uid:<agent>)` line.
+  3. `operator`, with `projmux.io/creator-client` only: the create ran in
+     process for a named operator client. The UI intent creates (picker, pane
+     menu, `ai split`, launch choice, the new-Window key) record the client
+     `ui`; a client layered on projmux that runs creates in process uses the
+     `recordOperatorCreator` seam. Such a create observes no pane chain,
+     because its process environment says nothing about who asked. A
+     `--creator` on it is dropped with the token `operator-client`. There is no
+     argv spelling of this basis; `TestNoArgvPathBuildsAnOperatorCreator`
+     holds its producers. Client names follow the one rule in
+     `internal/core/operatorclient`: 1-32 bytes of lowercase ASCII letters,
+     digits, and `-`, starting with a letter.
+  4. Nothing, when there is no evidence.
+
+  A failed pane-chain check changes nothing else about the create. When
+  nothing is recorded, stderr gets one `creator not recorded: <reason>` line
+  only if the ambient Pane is a live Agent Pane but a later check fails; an
   ambient Pane that is malformed, unregistered, or a Window-owned shell is
-  silent. These keys are provenance, not
-  authentication, like a message `--source`. An absent key does not mean a
-  human created the Agent: UI intent creates (picker, pane menu, `ai split`,
-  launch choice) and creates a Codex Agent issues (its
-  commands run under the app-server, not below the Pane's process) leave them
-  empty, and nothing backfills older Agents.
+  silent. The creator Agent is never the created Agent. These keys are
+  provenance, not authentication, like a message `--source`: no permission,
+  route, or selector reads them, and `explicit` can be forged, which is what
+  its basis says. An absent key does not mean a human created the Agent: a
+  Codex Agent's own commands run under the app-server, not below the Pane's
+  process, so they record nothing unless they declare `--creator`. Nothing
+  backfills older Agents.
 
 Root lifecycle:
 
@@ -532,6 +556,62 @@ Termination evidence transport:
   receipt is the post-delete diagnostic: source, classification, observed time,
   Pane/Agent uid, generation, and wait status only. No command, pane content,
   prompt, transcript, or provider payload is recorded.
+- Deletion records: every explicit deletion that commits its Registry
+  transaction appends exactly one JSON line to
+  `<state>/deletion-records.jsonl`, next to `termination-receipts.jsonl` and the
+  Registry it changed (`${XDG_STATE_HOME:-$HOME/.local/state}/projmux` by default). The writers are
+  `delete window|pane|agent`, `unregister project` and its deprecated alias
+  `delete project`, and `prune agent|project --yes`. The line is
+  `{"schemaVersion":1,"at","operation","operationID","via","actor":{"agentUID","paneUID","basis"},"targets":[{"kind","uid","name"}],"affected":[{"kind","uid","name","action"}]}`,
+  where `at` is RFC 3339 UTC; `operation` is one of `delete-window`,
+  `delete-pane`, `delete-agent`, `unregister-project`, `delete-project`,
+  `prune-agent`, `prune-project` (the record's own spelling; the receipt line a
+  delete prints spells it `delete.pane` and so on, a separate surface that is
+  not unified with it); `operationID` is the delete's intentional termination
+  receipt id, or one minted the same way for unregister and prune;
+  and `via` is `cli`, `ui` (the generated Pane and Window delete keys), or
+  `prune`. `targets` are what the operator named; `affected` is every
+  Project, ControlSession, Window, Agent, and Pane present before the commit
+  and absent after it (targets included), ordered by kind and then uid, each
+  with action `deleted`. No explicit deletion route removes a ControlSession
+  today (only a rolled-back transaction does, and that writes no record), so
+  that kind is listed for completeness of the two root kinds.
+- The actor is the same pane-chain judgment creator provenance uses, run
+  against the pre-commit Registry inside the delete's own transaction, so a
+  delete that removes its own Agent still names it. `basis` is `pane-chain`
+  when it succeeds, creation's skip token otherwise (`anchor-invalid`,
+  `anchor-pane-unregistered`, `anchor-pane-ambiguous`, `caller-pane-not-agent`,
+  `pane-ref-mismatch`, `anchor-server-unproven`, `anchor-query-failed`,
+  `anchor-server-mismatch`, `anchor-pane-mismatch`,
+  `process-chain-unobservable`, `not-pane-descendant`), and empty when there
+  was no ambient Pane. The server step is the delete's own: one
+  `display-message -t %N` through the route the delete addresses must answer
+  with the `$TMUX` socket and server pid, the same `%N`, and the Registry
+  Pane's mirrored uid. `prune` has no socket flags and judges on the inherited
+  `$TMUX`; `unregister project` judges on its `--socket`/`--socket-path` or
+  `$TMUX`. A `ui` deletion is never judged and records an empty actor.
+- A deletion a detached daemon runs (a Codex app-server command, say) is never
+  recorded as an Agent's. With no ambient Pane in its environment the actor is
+  empty with an empty basis; with an Agent Pane's inherited `TMUX`/`TMUX_PANE`
+  but a process that does not descend from that Pane, `basis` is
+  `not-pane-descendant` and both uids are empty.
+- **An empty actor does not mean a human ran the deletion.** The record is
+  provenance, not authentication.
+- The file is appended with one framed `O_APPEND` write and `fsync`, like the
+  termination journal, and is never truncated, rotated, or read back by
+  projmux. It is written after the commit and before the result is printed or
+  a self-targeted kill is queued. A record that cannot be written never fails
+  or changes the delete: stdout and the exit code are unchanged and stderr gets
+  exactly one `deletion not recorded: <token>` line, where token is
+  `state-dir-unavailable`, `append-failed`, or `operation-id-unavailable`.
+  `--dry-run`, a refusal, a declined confirmation, and a failed commit write
+  nothing.
+- Non-guarantees: automatic lifecycle teardown (exit reconciliation), internal
+  row cleanup (resume handoff, topology replay, initial shell retirement,
+  rollback, Project fresh start), and the supervisor's process-exit path write
+  no deletion record. A delete issued by a Codex Agent's command runs under the
+  app-server rather than below the Pane's process and records
+  `not-pane-descendant`. There is no retention policy and no reader CLI.
 - The supervisor resolves its state paths from the pane's own inherited
   environment, which is the tmux **server's** environment rather than the
   environment of the CLI call that created the pane. That is the correct
@@ -663,9 +743,21 @@ Agent provider session ref:
 - Codex's turn id is deliberately **not** stored. A turn addresses one turn
   inside the conversation and changes on every hook event, so it is not a
   pointer to the conversation.
-- Transcript **paths** are recorded as the hook reported them. Nothing reads
-  provider config files or transcript **contents**; that is permanently out of
-  scope.
+- Transcript **paths** are recorded as the hook reported them, and no
+  transcript content is read to fill the ref. The Registry, hook ingest, and
+  Agent resume paths (`agent resume`, `agent relaunch`, and the topology replay
+  below) never read provider config files, and they read transcript
+  **contents** only in these documented places:
+  - The three bounded tail readers that
+    [hooks.md](hooks.md#claude-code-hook-ingest) lists and scopes: `Stop` hook
+    ingest, the held coordination message release, and the Agent's pane
+    supervisor. Each reads at most the last 256 KiB of one Claude transcript,
+    and none writes what it read to the Registry. `Stop` keeps the last
+    assistant text as its notification row's text; hooks.md says where that
+    text goes.
+  - The explicit, user-run `agent sessions backfill` (see "Agent session
+    history (Claude)" below), which reads Claude transcript contents read-only
+    and only to attribute past sessions from delivered coordination frames.
 - The field is additive inside `schemaVersion: 1`. It is an optional pointer
   with `omitempty`, so a registry written before it existed decodes with a nil
   ref, validates, and re-encodes byte-identically. Bumping the envelope would
@@ -687,6 +779,214 @@ Agent provider session ref:
   hook whose provider contradicts the Agent's `spec.provider` is refused with
   zero mutations.
 
+Agent session history (Claude and Codex):
+
+- `status.sessionRef` holds one conversation and is overwritten when an Agent
+  moves to another one. The conversations a Claude or Codex Agent left are kept in
+  an append-only file outside the Registry,
+  `<state>/agent-session-history.jsonl` (next to `deletion-records.jsonl`;
+  `${XDG_STATE_HOME:-$HOME/.local/state}/projmux` by default). The Registry
+  schema and its version are unchanged.
+- One line is appended each time a committed Registry write binds or replaces
+  a Claude session id or Codex thread id. Re-observing the same conversation,
+  including a same-thread Codex resume or endpoint handover, appends nothing.
+  The writers are a closed set of four functions: `persistAgentSessionRef`
+  (hook ingest) and `persistManagedAgentInteractionWithActivationPolicy`
+  (managed-Agent interaction commit) in `internal/app/agent_session_ref.go`,
+  `openIntentAgent` (resume-picker create and intent native Codex create) in
+  `internal/app/create_intent.go`, and `createAgent` (native Codex fresh
+  create) in `internal/app/create_agent.go`.
+  `TestClaudeSessionRefWritersRecordHistory` pins the callers of
+  `RecordAgentSessionRef`, and
+  `TestSessionHistoryObservedRowWritersCarryAffiliation` pins the set of four,
+  that each builds its row with `sessionhistory.ObservedRecordFor` (directly or
+  through `claudeSessionHistoryRecord`) from its transaction's `working`
+  Registry, that each reaches a post-commit append helper, and that no other
+  code builds an `observed` row with `RecordFor`. The append runs after the
+  commit and never fails its caller: a hook logs one `session-history` line to
+  `ai-ingest.log`, a create prints one
+  `agent session history not recorded: append-failed` line on stderr.
+- Each line is `{"agentUID","provider","sessionId","transcriptPath","observedAt","source"}`:
+  `provider` is `claude` or `codex`, `observedAt` is the ref's RFC 3339 UTC observation
+  time, and `transcriptPath` is the path the Claude hook reported (empty for
+  Codex; never read by the
+  writers or by `agent sessions list`). `source` is `observed` for every line
+  a writer appends; the read side adds `current` for the Registry's ref; the
+  only producer of `estimated` is `agent sessions backfill` (below), whose
+  lines add one key, `lastRecordAt`. Lines are one framed `O_APPEND` write under an
+  exclusive `flock`, then `fsync`; the file is `0600` in a `0700` directory.
+  Readers skip and count an unparsable line.
+- An `observed` line also carries the Agent's affiliation in three trailing
+  keys, `projectUID`, `windowUID`, and `agentName`, so a session stays
+  attributable after its Agent is deleted from the Registry. The writer
+  resolves them inside the same transaction, from that transaction's working
+  Registry (`sessionhistory.ResolveAffiliation`), link by link: `agentName`
+  when the Agent exists, `windowUID` when its ownerRef is an existing Window,
+  `projectUID` when that Window's ownerRef is an existing Project. A key whose
+  link does not resolve is omitted; nothing is guessed, and a chain that does
+  not resolve never withholds the line or fails the writer. `current` and
+  `estimated` rows carry none of the three. When `agent sessions list` merges
+  a conversation seen more than once, each of the three is the non-empty value
+  of the latest row that carries one.
+- A line `agent sessions attribute` (below) writes adds a fourth key after
+  them, `affiliationBasis: "registry"`: its affiliation is the one the current
+  Registry gave the Agent when the user ran it, not its writer's transaction.
+  No other writer sets the key; an `observed` line without it is recorded at
+  write time. Merging carries `affiliationBasis` with `projectUID`: it is the
+  basis of the row that supplied the kept `projectUID`.
+- `projmux agent sessions list <agent-ref> [-o json]` and the Go read function
+  `sessionhistory.List(stateDir, agent)` return the same rows: history joined
+  with the Registry's current ref, one row per `(agentUID, provider, sessionId)` in
+  `observedAt` order. A conversation seen more than once keeps its latest
+  observation time and transcript path, and is `current` when the Registry
+  names it; otherwise it is `observed` if any of its rows is, and `estimated`
+  only when every row is, so a backfilled estimate never hides an observation.
+  The JSON envelope adds `agentName` and `corruptLines`.
+- `projmux agent sessions project <project-ref> [-o json]` and the Go read
+  function `sessionhistory.ListProject(stateDir, registry, projectUID)` list
+  the sessions attributed to one exact Project (resolved like any Project
+  ref). It is read-only. A Project no longer in the Registry is queried by its
+  exact `uid:<uid>` ref, where `<uid>` has exactly the shape projmux mints for
+  a Project: the listing then comes from the history rows alone,
+  `projectName` is `""`, and the table names the Project `project/uid:<uid>`.
+  A name ref, or a `uid:` ref of another kind or shape, resolves against the
+  Registry only and fails as before when it matches nothing.
+  - Input: every `claude` or `codex` line of the history file, plus one
+    `current` row for each Registry Agent with a supported provider.
+  - Attribution, per row: a row with a `projectUID` is attributed with its
+    own `projectUID`, `windowUID`, and `agentName`, never re-resolved, with
+    basis `registry` when its `affiliationBasis` is `registry` (it holds after
+    the Agent is deleted, with `inRegistry: false`) and `recorded` otherwise;
+    otherwise, a row whose Agent is in the current Registry with a complete
+    Agent -> Window -> Project chain is attributed with basis `registry`,
+    using the current values; any other row is unattributed. Rows are never
+    attributed from deletion records, Registry backups, a transcript's folder
+    or cwd, or time proximity.
+  - A session is `(provider, sessionId)`. A session none of whose rows is
+    attributed counts in `unattributed`; one whose attributed rows name two or
+    more Projects counts in `ambiguous` and is listed under none; one naming
+    exactly the requested Project is listed. Both counts, and `corruptLines`,
+    are over the whole history, not per Project.
+  - Each listed session has `provider`, `sessionId`, `transcriptPath`,
+    `observedAt`, `lastRecordAt` (when any row has one), and `source`, merged
+    over its attributed rows with the `agent sessions list` rules, and
+    `agents`: one entry per distinct Agent of those rows, in first-appearance
+    order (history file order, then the current rows), with `agentUID`,
+    `agentName`, `windowUID`, `inRegistry` (the Agent exists in the current
+    Registry), and `basis` (`recorded` wins when an Agent has both). Sessions
+    are ordered by `observedAt`.
+  - JSON: `{"projectUID","projectName","sessions","unattributed","ambiguous","corruptLines"}`;
+    `sessions` is `[]` when empty. The table prints
+    `project/<name> has no recorded sessions` when empty, marks an Agent no
+    longer in the Registry `(deleted)`, and prints one stderr line for each
+    non-zero `corruptLines`, `unattributed`, and `ambiguous` count.
+- `projmux agent sessions backfill [--dry-run] [-o json]` recovers a subset of
+  the conversations from before this history existed. It is the one explicit,
+  user-run reader of transcript contents. Apart from the bounded tail readers
+  that [hooks.md](hooks.md#claude-code-hook-ingest) lists (`Stop` hook ingest,
+  the held coordination message release, and the pane supervisor), the
+  Registry, hook ingest, Agent resume, and `agent sessions list` never read a
+  transcript, and none of those tail readers adds a row to this history.
+  - Input: the top-level Claude transcripts
+    `${CLAUDE_CONFIG_DIR:-$HOME/.claude}/projects/<project>/<session>.jsonl`
+    (a blank `CLAUDE_CONFIG_DIR` is unset). Only regular files exactly one
+    directory deep are scanned: symlinks, directories, and deeper files such
+    as `<session>/subagents/*.jsonl` are not. Files are opened read-only and
+    never written; a missing projects directory scans nothing.
+  - Attribution: only `type: "user"` records that are not `isSidechain: true`
+    count, and within them only a string `message.content` or its
+    `type: "text"` blocks; tool results, assistant records, attachments, and
+    queue operations can quote a frame and are ignored. At each occurrence of
+    `{"kind":"projmux-coordination"` in that text, one JSON value is decoded;
+    a frame with that `kind` and a non-empty `target.agentUID` names its
+    target, and an occurrence that does not decode is skipped and counted.
+    A transcript naming exactly one distinct target Agent is attributed to
+    it; none is `noFrame`, two or more is `ambiguous`, and neither is ever
+    resolved from the folder name, the working directory, or time proximity.
+  - Meaning of `estimated`: the session received a delivered projmux message
+    addressed to that Agent. It is a subset of past sessions -- a session that
+    never received a message is not recovered -- and an attribution, not an
+    observation. `sessionId` is the file name, `transcriptPath` the absolute
+    file path, `observedAt` the transcript's first record `timestamp`, and
+    `lastRecordAt` its last one (both over every parseable record, RFC 3339
+    UTC). A candidate with no parseable timestamp is `unreadable`.
+  - Precedence and idempotency: a session already `observed` in the history
+    or `current` in the Registry for any Agent is `skippedObserved`; one
+    already `estimated` is `alreadyEstimated`; only the rest are appended, as
+    framed lines like every other writer's. The run holds the history file's
+    exclusive `flock` across the read, the check, and the append (not the
+    transcript scan), so concurrent runs cannot add a session twice and a
+    second run appends nothing.
+  - Report: `scanned`, `attributed`, `alreadyEstimated`, `skippedObserved`,
+    `ambiguous`, `noFrame`, `unreadable` (each transcript lands in exactly one
+    of these six), `malformedLines` (transcript lines that are not JSON
+    objects, skipped), `malformedFrames`, plus `dryRun`, `projectsDir`,
+    `historyPath`, and `rows` (the attributed rows; `[]` when none).
+    `--dry-run` reports exactly what a real run would append and writes
+    nothing, not even the state directory.
+  - Removing the estimated rows: with no projmux command running that could
+    write the history, keep every other line and swap the file in atomically
+    (the blank lines of the framed format are simply dropped):
+
+    ```sh
+    h="${XDG_STATE_HOME:-$HOME/.local/state}/projmux/agent-session-history.jsonl"
+    jq -c 'select(.source != "estimated")' "$h" > "$h.tmp" && chmod 600 "$h.tmp" && mv "$h.tmp" "$h"
+    ```
+
+    A line `jq` cannot parse stops it with an error before the `mv`; readers
+    already skip such lines, so remove or repair it first.
+- `projmux agent sessions attribute [--dry-run] [-o json]` persists what the
+  current Registry proves about the conversations whose history carries no
+  Project, so `agent sessions project` keeps listing them after their Agent
+  is deleted. It reads only the history file and the current Registry: never
+  deletion records, Registry backups, or transcripts. It persists only what
+  the current Registry proves, and never restores an Agent that is no longer
+  in it.
+  - Input: every `(agentUID, provider, sessionId)` of the file's `claude` and
+    `codex` lines, in file order, then each Registry Agent's current ref
+    (supported providers only) whose key the file does not name.
+  - Precedence: a key with a line that has a `projectUID` is
+    `alreadyAttributed`; a key whose Agent is not in the Registry, or whose
+    Agent -> Window -> Project chain does not resolve, is `unresolved`; both
+    are left untouched. Every other key is `attributed`: one line is appended
+    for it, with `observedAt`, `transcriptPath`, and `lastRecordAt` merged
+    over its lines and its current ref with the `agent sessions list` rules;
+    `source` the highest-ranked source of its lines, or `observed` for a key
+    only the Registry names (`current` is never written); `projectUID`,
+    `windowUID`, and `agentName` from the current Registry; and
+    `affiliationBasis: "registry"`.
+  - Report: `scanned` (`attributed` + `alreadyAttributed` + `unresolved`),
+    `attributed`, `alreadyAttributed`, `unresolved`, `corruptLines`, plus
+    `dryRun`, `historyPath`, and `rows` (the attributed lines; `[]` when
+    none).
+  - Idempotency and locking: like backfill, a run holds the history file's
+    exclusive `flock` across the read, the classification, and one write of
+    every framed line, and releases it before the `fsync`. A second run
+    appends nothing, because every key it attributed now has a `projectUID`.
+    Existing lines are never rewritten. A run with nothing to append creates
+    nothing, and `--dry-run` reads without the lock, writes nothing, and
+    reports exactly what a real run would append.
+  - Undoing it, the same way as removing estimated rows:
+
+    ```sh
+    h="${XDG_STATE_HOME:-$HOME/.local/state}/projmux/agent-session-history.jsonl"
+    jq -c 'select(.affiliationBasis != "registry")' "$h" > "$h.tmp" && chmod 600 "$h.tmp" && mv "$h.tmp" "$h"
+    ```
+- Non-guarantees: no session end time is recorded for observed rows;
+  conversations from before this history existed appear only as the `current`
+  row unless `agent sessions backfill` attributes them; Claude and Codex
+  conversation changes are recorded, Antigravity's are not; a line edited or
+  deleted by hand is not recovered; the history is kept after the Agent is deleted; the Registry
+  commit and the append are not atomic, so a crash between them loses that one
+  line. There is no retention policy. Lines written before the affiliation
+  keys existed carry none, so once their Agent is deleted they count only in
+  `unattributed` unless `agent sessions attribute` persisted their
+  affiliation while the Agent was still in the Registry; `agentName` is a
+  write-time snapshot and does not follow a later rename; a deleted Project
+  can no longer be named by name, only by its exact `uid:` ref, and then only
+  the history rows that carry its `projectUID` are listed; `agent sessions
+  project` computes no token totals.
+
 Agent launch argv (workspace / task boundary):
 
 - One Agent launch hands the provider CLI two independent things in a single
@@ -1040,6 +1340,10 @@ Resolved resource graph (`internal/core/resourcegraph`):
   first and the inherited `$TMUX` socket path second. There is no implicit
   default-server probe: with no transport the graph is a Registry-only snapshot
   whose runtime answers are all `unknown`, and a sibling socket is never read.
+  The Registry views `get` and `describe` add one rung after `$TMUX`: they
+  have no socket flag, so outside tmux they observe the app socket
+  `-L projmux` (see *Runtime observation and resource status*). That is still
+  one exact server, never the default one.
 - **Bounded and pure.** One observation costs one option probe plus three list
   queries whatever the size of the server, is memoized for the invocation rather
   than cached with a TTL — closing a pane must make the *next* command report it
@@ -1132,14 +1436,25 @@ Runtime observation and resource status:
   live tmux object still mirrors its `@projmux_window_uid` /
   `@projmux_pane_uid`. A registry object bound to nothing live is an **orphan**,
   and an orphan is not live.
-- `selector.ObservedStatus(missingRoot, bound)` is the **single** derivation
-  rule in the codebase, and every kind goes through it. `missing-root` outranks
-  everything, then `bound` decides `live` vs `offline`. The MissingRoot
-  precedence contract is unchanged, and it now applies to a Window or Pane whose
-  owning Project lost its root even while tmux is still running them.
+- `selector.ObservedStatus(missingRoot, bound, unobserved)` is the **single**
+  derivation rule in the codebase, and every kind goes through it.
+  `missing-root` outranks everything, then `bound` is `live`, then a resource
+  whose observation could not be taken is `unknown`, and only a readable
+  observation with nothing bound is `offline` -- the same precedence the
+  resource graph applies. The MissingRoot precedence contract is unchanged, and
+  it now applies to a Window or Pane whose owning Project lost its root even
+  while tmux is still running them.
+- `get` and `describe` build their observation from the resolved resource
+  graph, so a row's STATUS and the ACTIONS `registryview` offers for it come
+  from one judgement. An `unknown` row offers only `delete`: it was not seen
+  live, so `open` has nothing to move to, and it was not seen absent, so
+  `start`/`resume` could target something already running.
 - A **Project** is the one kind whose runtime object is a tmux *session*, which
-  has no `@projmux` uid of its own, so Project status still reads the stored
-  `status.session` projection (see *Resource metadata model* for its writers).
+  has no `@projmux` uid of its own. On `get` and `describe` its status is the
+  graph's observation of that session; an identity-only resolver that took no
+  observation (`selector.New`) still reads the stored `status.session`
+  projection (see *Resource metadata model* for its writers) and never reports
+  `unknown`.
 - An **Agent** owns no tmux object of its own — there is no `@projmux_agent_uid`
   and there must not be one, because an Agent outlives the managed Pane it is
   bound to. Its runtime object is **that managed Pane**, named by
@@ -1166,6 +1481,15 @@ Runtime observation and resource status:
   exactly that. It is also not a per-route reconcile, because the read verbs
   load the registry read-only and must never materialize
   `<state>/projmux/metadata/`.
+- **The server a view observes** is the one its caller is attached to: the
+  inherited absolute `$TMUX` socket, even when that is not the app server.
+  With no `$TMUX` -- another terminal, an IDE, a script -- `get` and `describe`
+  observe the app socket `-L projmux`, the server `create` and
+  `start project` run resources on, so a view outside tmux renders the same
+  rows as the same view inside the app server. An app socket with no server
+  behind it is observed as an absent server: everything reads `offline`, which
+  is what is running there. `get runtime` and `reconcile resources` keep their
+  own rule (flag or `$TMUX`, otherwise no transport).
 - A failed inventory query yields an **empty** observation, never a fallback to
   a stored value. Empty can only downgrade a resource to offline; it can never
   invent a live one, and "nothing is live" is the truthful answer for a machine
@@ -1651,7 +1975,7 @@ a discovery input *and* the only record that a directory mattered. They are five
 separate authorities now, and the boundaries are the point.
 
 - **Workdirs and project roots are scan roots.** `PROJMUX_MANAGED_ROOTS`,
-  `PROJMUX_PROJDIR` and `~/.config/projmux/workdirs` name directories to look
+  `PROJMUX_PROJDIR` and `$HOME/.config/projmux/workdirs` name directories to look
   inside. Looking inside a directory registers nothing. On Windows they are
   OS-native paths and stay OS-native paths; nothing normalizes them into identity.
 - **A discovered child is an unregistered candidate.** It is a filesystem fact