projmux 0.15.3 → 0.16.1

package/docs/architecture.md

@@ -131,7 +131,7 @@ procfs collector supplies PID+starttime identity, SID, CPU ticks, RSS, and host
 capacity. Pure aggregation builds pane, unique-window, and project rows without
 using labels, topics, titles, or cwd-derived names as ownership keys.
 
-Resource snapshots are not Session State and are never saved or restored. See
+Resource snapshots are in-memory only and are never saved or restored. See
 [resource-attribution.md](resource-attribution.md) for metric, partial-state,
 host-remainder, privacy, and measurement contracts.
 
@@ -144,7 +144,7 @@ CLI information architecture v2 resource routes.
 Packages:
 
 - `internal/core/metadata` is pure: the resource model, validation, name
-  allocation, schema migration, snapshot reconciliation, and the operation
+  allocation, schema migration, and the operation
   transaction. It performs no I/O; the clock, uid source, and root-directory
   probe are injected through `Mutator`.
 - `internal/core/resourcegraph` is pure: the resolved resource graph that joins
@@ -171,7 +171,7 @@ Packages:
   fills a `resourcegraph.Inventory` from one exact server.
 - `internal/integrations/tmuxopts` is a dependency-free leaf holding the
   canonical spelling of every projmux-owned tmux option name, so the generated
-  tmux config, session-state replay, and the resource mirror cannot drift.
+  tmux config and the resource mirror cannot drift.
 
 Resources and ownership:
 
@@ -216,6 +216,50 @@ Resources and ownership:
   live only in runtime inventory, outside the Project hierarchy. A
   ControlSession is not a counter-example: it is a root resource that *names* a
   session, and the session still carries no identity of its own.
+- `Project.status.session` is the **last recorded** projection, not a live
+  read. It holds `name`, `live`, and `socketPath`: the exact absolute socket
+  path of the tmux server the session was last created or observed live on,
+  as the writing route verified it against the server's own `#{socket_path}`
+  (never derived from a socket name; empty when that route had no verified
+  path). Registration records the name with `live=false` and no path. Create,
+  materialize, Project startup, and legacy import write `live=true` with the
+  path of their route. A successful managed Project stop writes `live=false`
+  only after the exact Session is observed absent, keeping the name and
+  `socketPath`; deleting a Project's last valid primary Window lowers `live`
+  the same way. The full reconciler pass (`refreshSessionProjections`, run by
+  the create routes and by controller convergence) records `live=true` with
+  this pass's path for every Project whose session is on the server it
+  observed. It lowers by absence only a projection recorded on that server or
+  on no server, keeping its name and path; a projection recorded on another
+  server is left as it is, and a pass without a verified path lowers none that
+  record a path. The rule is `SessionAbsenceAttributableTo`.
+  `reconcile resources` scopes that pass to Projects with an observed
+  live Session, and outside that scope it lowers a `live=true` projection
+  whose `socketPath` is exactly the reconciled server's path and whose session
+  is absent there, keeping its name and `socketPath`; Projects with another or
+  no `socketPath` are untouched, because absence from one server is not
+  evidence about a session recorded on another. The one judgement is
+  `Mutator.LowerProjectSessionsEndedOnServer`.
+  The `window-unlinked` hook, which a raw `kill-session` fires, applies the
+  same judgement on its fast path: once its lifecycle stage has observed the
+  host, it lowers a live projection recorded on the hook's exact verified
+  server whose session is gone there, re-reading that server's sessions under
+  the Registry lock. It does not run the full pass, and when no live
+  projection records that server it costs the hook no extra tmux call.
+- When the exact server `reconcile resources` targets is not running (its
+  runtime authority read fails with a missing-server signature, and only
+  then), the same judgement runs with an empty present set against the exact
+  target path: the `--socket-path` or inherited `$TMUX` path itself, or for
+  `--socket <name>` the path tmux would use for that label (the first existing
+  `tmux-<uid>` directory under `$TMUX_TMPDIR`, then `/tmp`, resolved through
+  symlinks). Every projection recorded `live=true` on exactly that path is
+  lowered in one Registry commit, keeping its name and `socketPath`, and the
+  receipt states the absent server and the lowered count; nothing else is
+  planned, written, or reobserved, and `--dry-run` previews the same items.
+  When nothing is left to lower, or the path cannot be resolved, the command
+  fails at the runtime authority stage exactly as before and writes nothing.
+  Any other authority failure (a refused or unreadable socket, a timeout, a
+  server that is not app-owned) never lowers anything.
 - `Window` and `Pane` carry **no stored liveness field**, deliberately. Their
   `status` block holds observed conditions only; live/offline is derived from a
   live tmux observation at read time. See *Runtime observation and resource
@@ -321,7 +365,7 @@ support reports expose those counts but redact item reasons and identifiers.
 Identity and naming:
 
 - `metadata.uid` is opaque, immutable, and independent of tmux lifecycle. It
-  survives snapshot/restore, runtime creation, and root rebind.
+  survives runtime stop/Continue, runtime creation, and root rebind.
 - `metadata.name` is the stable unique-within-scope query key. Project names
   and ControlSession names are unique within their own root kind across the
   registry. Window, Pane, and Agent names are unique by
@@ -335,6 +379,21 @@ Identity and naming:
   or numeric suffix allocator. An explicit `--name` keeps its original spelling
   after validation; explicit create and rename collisions fail with exit code 2
   and zero Registry, tmux, or provider writes.
+- A newly registered Project is the one exception. `create project` without
+  `--name`, and every implicit registration (first open of a directory,
+  `projmux shell`, Open fresh), name the Project after its root directory: the
+  root basename run through the same sanitizer as any name seed (`my repo`
+  becomes `my-repo`). If that basename sanitizes to nothing (the filesystem
+  root) or another Project already holds it, the Project falls back to the
+  exact-UID rule above -- never a numbered variant, never a `project`
+  placeholder. Legacy/orphan import and every Window, Pane, Agent, and
+  ControlSession keep exact-UID automatic names, and no stored name is ever
+  rewritten.
+- Open fresh replaces the Project and carries its name over only when that
+  name is not shaped like a minted Project UID (`proj-` plus a full canonical
+  UID payload). An operator-chosen name such as `proj-front` survives; a
+  UID-shaped name -- the old exact-UID automatic name, or one copied from a
+  predecessor -- is dropped so the replacement is named after its root.
 - `create agent` supplies an **explicit** name for the Pane its Agent owns:
   `<agent-name>-pane`, derived from the Agent's own name. That used to be a
   documented follow-up `rename pane` a launcher had to remember, so a caller
@@ -359,6 +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: 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. 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:
 
@@ -452,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
@@ -519,7 +679,8 @@ Exit reconciliation and lifecycle projection:
 - Abnormal, killed, unknown, whole-host absence, missing/empty server inventory,
   permission failure, foreign Window observation, stale generation, and an
   Agent that now binds a resumed Pane all produce delete-plan zero. They keep the
-  retained lifecycle projection and canonical explicit Offline delete recovery.
+  retained lifecycle projection and the canonical exact-uid Registry-only
+  delete recovery of a paneless Offline or Failed Agent.
 - The closed Agent transition table stays the authority. An Agent that may not
   reach the implied phase keeps its phase, its `paneRef`, and its managed Pane;
   only the evidence is recorded. A refused transition is not a reason to discard
@@ -582,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
@@ -606,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
@@ -736,9 +1117,8 @@ Registry file and schema:
   directory-existence and uid adapters.
 - The canonical anchor is a schema-v2 write invariant. Until the separately
   planned Project-start projection lands, the legacy `New` startup path's
-  prune-to-zero transaction fails validation and commits zero Registry bytes.
-  The Registry verdict precedes snapshot deletion, so that rejection also
-  preserves the latest snapshot byte-for-byte and performs no tmux mutation.
+  prune-to-zero transaction fails validation and commits zero Registry bytes
+  and performs no tmux mutation.
   This fail-closed ordering is not Phase 3 authority to redesign Project start.
 - Downgrade writes remain unsupported. Unversioned, malformed, and future
   envelopes still fail closed before backup, staging, or replace.
@@ -960,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
@@ -967,21 +1351,11 @@ Resolved resource graph (`internal/core/resourcegraph`):
   process, and no tmux, so the same inputs always produce byte-identical output
   and a read can never materialize state.
 
-Session State interoperability:
-
-- Session snapshots carry resource identity through additive `omitempty`
-  `metadata` blocks at the unchanged snapshot `version: 1` — one for the owning
-  Project at the top level, one per Window, and one per Pane, each with
-  `uid`, `name`, `labels`, `owner_kind`, and `owner_uid` in the snapshot's own
-  snake_case spelling. No schema bump was needed, and a snapshot written
-  without resource metadata still serializes byte-identically to the older form.
-- Snapshots written before resource metadata existed still project
-  deterministically into an explicitly selected, closed Registry Project:
-  existing Windows and Panes are reused positionally in Registry order and any
-  additional descendants receive new stable identities. Restore validates a
-  pure Project-scoped plan, atomically commits that desired subtree, and only
-  then invokes the ordinary Project materializer. It never directly replays
-  snapshot topology into tmux and never replaces the global Registry.
+Saved Project state:
+
+- The Registry is the only saved Project state. projmux keeps no separate
+  Project snapshot store, and a closed Project starts only from its Registry
+  desired state through the ordinary Project materializer.
 
 tmux transport mirror:
 
@@ -1000,7 +1374,7 @@ tmux transport mirror:
   every other mirror goes through, on the same plain `tmux` transport the session
   was created on. The write is gated strictly on "this open registered the
   Project": every already-registered Project converges through the Registry
-  topology engine, including desired state previously committed from a snapshot,
+  topology engine,
   and opening `$HOME` mints no managed identity at all, so neither writes a mirror
   option through this first-open gate. That gate is also what makes repeating an
   open write nothing. Repairing a session that is already live without its
@@ -1062,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
-  `status.session` as refreshed by the reconciler.
+  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
@@ -1096,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
@@ -1284,7 +1678,7 @@ Lifecycle trigger convergence:
   transaction deletes exactly that Window, its Panes, its owned Agents, and
   their reservations. A non-last Project Window reanchors to its existing
   sibling. The last Project Window leaves the exact Project uid, root,
-  reservation, pins, and snapshot bytes in the valid zero-Window state. A
+  reservation, and pins in the valid zero-Window state. A
   ControlSession likewise loses only the Window and keeps its root uid.
   Abnormal/killed/unknown exits, stale generations, unpaired or foreign handles,
   unavailable/empty observations, and missing-server or permission failures
@@ -1298,11 +1692,9 @@ Lifecycle trigger convergence:
   managed runtime and preserves every desired UID. Continue on retained-window
   writes only runtime and materializes the same descendant UIDs; Continue on
   zero-window atomically allocates one canonical Window/shell below the same
-  Project UID before runtime materialization. The deleted+Continue cell accepts
-  only a usable-snapshot precondition, then atomically creates a new Project UID
-  and restores new descendant UIDs from that snapshot; without the precondition
-  the same cell is an unavailable zero-write refusal and never falls back to
-  Fresh. Fresh atomically replaces either
+  Project UID before runtime materialization. The deleted+Continue cell is
+  always an unavailable zero-write `project-is-not-registered` refusal that
+  points to Fresh and never falls back to it. Fresh atomically replaces either
   registered state with a new Project/Window/shell UID chain and exactly one
   same-root claimant. Within this runtime/startup lifecycle table, canonical
   `delete project --yes` alone unregisters the Project graph; the separately
@@ -1370,6 +1762,25 @@ Projmux split UI:
   The provider and shell branches render the exact argv an operator would type,
   so a UI action and a typed command cannot disagree about what `--placement
   down` means.
+- A split picker running in a popup does not call that route itself. tmux
+  closes a popup only when the process inside it exits, so the picker hands its
+  intent to a detached `run-shell -b` continuation on the same server
+  (`internal agent-pane launch-selection`, carrying the origin Pane, client,
+  and context directory as env) and exits. The continuation
+  calls the same create funnel; a success writes nothing and anything else is
+  one bounded line on the pressing client. Every selection travels: it is a
+  plain value with no live handle left in the picker process.
+- A generated Window create asks before it commits. It opens the split picker in
+  answer mode (`internal tmux popup-toggle --answer <file>`) on the Pane the key
+  was pressed in; the picker writes the selection -- the same argv the
+  continuation carries, read back by the same parser -- to a 0600 file its
+  producer made, and creates nothing. The producer then commits the Window and
+  the answer in one Registry transaction -- for an Agent, the same shape
+  `create window --provider` commits: the Agent Pane splits off the new shell
+  and the shell is retired -- and moves the pressing client onto it last. An
+  Agent that cannot be opened rolls the whole Window back and leaves one line on
+  the pressing client. A cancelled picker leaves the file empty and nothing is
+  created.
 - Only the materializer runs `split-window`. Before this convergence the saved
   default and both pickers descended into a legacy split that called tmux
   directly, so a pane opened from the UI was a runtime object the Registry had
@@ -1564,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
@@ -1681,15 +2092,14 @@ Explicit Registry topology materialization:
   deletion removes that desire. Exact uid/name/owner mirrors are retained. Stored
   Pane CWD drives only that Pane's detached runtime cwd, while Project root
   remains the session path anchor and `PROJMUX_CWD` hook value.
-  `Pane.spec.command`, snapshot recipes, notifications, and ephemeral sessions
+  `Pane.spec.command`, notifications, and ephemeral sessions
   are never execution inputs.
 - An Agent whose managed Pane is not live is replayed into a new managed Pane on
   its Window's proven anchor, through the same allocation, activation ledger,
   ownership-checked adoption, and rollback the shell half uses. The **only**
   replay identifier is Registry `status.sessionRef`: no provider conversation
   store is read, `ClaudeSessionRef.TranscriptPath` in particular is never
-  consulted, and snapshot recipe `resumeID` is a separate value that never feeds
-  this path. The launch argv comes from the two seams `create agent` already
+  consulted. The launch argv comes from the two seams `create agent` already
   owns -- `PlanAgentResume` for a ref that names a conversation, `PlanAgentLaunch`
   with no payload otherwise -- so the topology engine holds no launch builder of
   its own and the Settings enabled-agents gate still applies. An Agent that
@@ -1703,14 +2113,7 @@ Explicit Registry topology materialization:
   the Window from it, and then replays the anchor Agent while preserving the
   Agent Pane uid. The default shell is bootstrap, not a replacement anchor. A
   successful repeat is a Registry-write-free and topology-write-free no-op.
-- Snapshot restore is a target-Project subtree projection, never a Registry
-  restore. Metadata-bearing v1 snapshots preserve surviving final-v2
-  anchor/default refs; metadata-free snapshots choose the first Window-local
-  Pane as anchor and the first direct shell as optional default. Agent-only
-  desired Windows remain Agent-anchored and acquire a shell only through the
-  ordinary materializer. Source snapshot bytes and unrelated roots are never
-  rewritten, and a second projection is byte-stable.
-- `Recreate Project` replaces the exact same-root Project graph, after an
+- `Clear layout and open` replaces the exact same-root Project graph, after an
   explicit confirmation, in one Registry
   commit. It always allocates a new Project UID plus one new canonical Window
   and direct shell UID, whether the old Project retained Windows or had zero.
@@ -1784,7 +2187,10 @@ Plan-only runtime mutation boundary:
   arbitrary Pane as invocation evidence. Generated popup/menu producers pass an exact Pane anchor which is
   reobserved on that same socket rather than trusting a targetless current
   Pane. Before a stage writes, the same `-S` runner refuses path, generation,
-  class, or containment drift. Only a create-session
+  class, or containment drift, and names which of them happened: tmux answers a
+  `display-message -t %N` for a Pane that is gone with exit 0 and blank
+  `$N`/`@N`/`%N` columns, so an absent anchor Pane is reported as absent rather
+  than as drift on a socket and a server generation that both still match. Only a create-session
   stage may accept the typed no-server observation, because its explicit route
   and absent-session ownership preflight are the facts required to create the
   first server.
@@ -1912,8 +2318,11 @@ Resource-first create:
   `select-window`, `select-pane`, or `attach-session`. `focus pane` and
   `-o pane-id` are how a caller ends up in the new pane. One exception: the
   human intent route `internal tmux window-create` (`window.create` key, Window
-  menu New At End) moves exactly the pressing client to the new Window after
-  its create commits; public `create` stays detached.
+  menu New At End) asks for the saved launch default before its create
+  commits, fills the committed shell Pane with the answer -- an Agent through
+  the same canonical create funnel a split uses plus a canonical delete of the
+  shell -- and then moves exactly the pressing client to the new Window; public
+  `create` stays detached and never reads that saved default.
 - **Focus is navigation-only.** `focus project|window|pane` reads live tmux
   inventory and may move an existing client, but has no Registry store and
   issues no session/Window/Pane creation, identity-marker, rename, respawn, or
@@ -1955,8 +2364,8 @@ Selector and the implicit active target:
   hit. The describe family remains the intentional Project-only difference;
   Phase 14 extends only the generic rename family to ControlSession.
   `get projects`, `describe|rename project`, `delete`, `rebind`, and `agent
-  resume` are outside that reference scope, and notifications and snapshots
-  belong to separate stores. Delete's exact live preflight nevertheless follows
+  resume` are outside that reference scope, and notifications belong to a
+  separate store. Delete's exact live preflight nevertheless follows
   either root kind through the selected descendant's owner chain.
 - `--all-projects` is the explicit registry-wide escape for those three reads.
   It is deliberately different from destructive `delete --all`, whose existing
@@ -2033,14 +2442,6 @@ Projmux keeps visible naming separate from source metadata:
   user pane labels.
 - **Git branch** belongs in the statusbar git segment. Branch-based terminal
   title overwrites are not promoted to the primary Projmux pane or window name.
-- **Session snapshots** store source metadata separately: `window_name`, raw
-  `pane_title`, user `label`, `@projmux_ai_topic`, manual topic ownership, and
-  agent resume metadata. Old snapshots decode with an absent label and absent
-  ownership; title/topic equality never infers either. Replay writes each
-  semantic field to the exact pane id returned by tmux creation and restores
-  raw title from `Pane.Title` after launch/startup replay. Snapshots do not
-  store a resolved `display_label`; visible labels are recomputed by display
-  policy.
 
 ## Notify queue
 
@@ -2183,7 +2584,7 @@ The maintained product table in `internal/app/runtime_mutation_surface.go` maps
 generated catalog/menu producers, native provider/resume picker selections,
 sidebar/session-picker stops, and app lifecycle entrypoints in both directions
 to their handler and plan verb. It also records exact semantic exemptions for
-focus, labels, operator-requested layout, mouse forwarding, snapshot replay,
+focus, labels, operator-requested layout, mouse forwarding,
 ephemeral maintenance, app quit, and human runtime maintenance. Managed argv
 verbs are selected only by the typed executor seam; generated Window
 create/rename, Pane-menu create/delete, and automatic post-split layout writes