projmux 0.15.2 → 0.16.0

package/docs/heterogeneous-dialogue-canary.md

@@ -348,14 +348,19 @@ a recorded verdict moves. Neither it nor L20 proves:
 - acceptance of unknown frames or fields, which the closed vocabulary rejects
   by design.
 
-The L20 fixture emits none of the corpus's dropped side frames. Recorded real
-shapes the validator rejects today:
+L20 replays every corpus item whose verdict is `drop` through the production
+reply-only validator. Its Claude fixture reads the corpus at run time, emits each
+dropped side frame with its key set unchanged after init and before its startup
+result, and the scenario requires the emitted names to equal the corpus drop
+set. Those frames are key-shape placeholders, not model output. L20 does not
+emit the recorded real shapes the validator rejects today:
 
 - `result-success-25-keys`: the result allowlist lacks `origin`;
 - `system-init-allowlist-diff`: the init allowlist lacks `memory_paths` and
   `terminal_slash_commands`.
 
-Shapes without preserved evidence are gaps, not corpus items: `command_lifecycle`
+Shapes without preserved evidence are gaps, not corpus items, so neither the
+corpus nor L20 exercises them: `command_lifecycle`
 keys and values; a non-null assistant `context_management` value; `system`
 `thinking_tokens` frames; hook and user `tool_result` frames; the exact real init
 key set; nested values of every frame; `rate_limit_event` envelope keys beyond

package/docs/hooks.md

@@ -117,10 +117,8 @@ special fields—`[env]` preserves any valid user-supplied key verbatim and no
 Global hooks under `$XDG_CONFIG_HOME` are prompt-free.
 
 Project-local executable automation is gated by trust-on-first-use. This
-includes `.projmux/config.toml` before projmux runs hooks or applies
-startup/session environment settings, and a selected
-`.projmux/layouts/*.toml` named snapshot before projmux replays any declared
-`command`.
+covers `.projmux/config.toml` before projmux runs hooks or applies
+startup/session environment settings.
 Approving "always"
 records the file content hash in:
 
@@ -131,19 +129,13 @@ ${XDG_STATE_HOME:-$HOME/.local/state}/projmux/trusted-projects.json
 The trust key is the absolute repository path and each artifact path is stored
 relative to that repository. Each project entry has a
 `trusted_at` timestamp and a `files` map of relative paths to SHA-256 hashes.
-When file content changes or the layout path is replaced, projmux asks again
-and shows the old and new SHA-256 hashes. Layout symlinks, including symlinked
-`.projmux` or `layouts` path components, are rejected. The selected layout is
-read once; those exact bytes are both hashed and parsed, and the resulting
-in-memory snapshot is what restore uses. In non-interactive contexts such as
-tmux run-shell or CI, untrusted or changed project-local executable files fail
-closed with a warning.
+When file content changes, projmux asks again and shows the old and new
+SHA-256 hashes. In non-interactive contexts such as tmux run-shell or CI,
+untrusted or changed project-local executable files fail closed with a warning.
 
 Set `PROJMUX_PROJECT_HOOKS=off` to disable project-local hook discovery
 entirely. Project-local hooks can also be disabled from `projmux settings`
-under Labs. The global hook still runs either way. This setting does not trust
-or bypass executable named-snapshot commands. A layout without a startup
-`command` does not require executable-artifact approval.
+under Labs. The global hook still runs either way.
 
 ## Startup Commands
 
@@ -531,6 +523,16 @@ default install catalog is based on Claude Code 2.1.140 and represents the
 | `CwdChanged` | marks the matched pane hook-active and writes a quiet ingest diagnostic; no notify queue entry is pushed |
 | `FileChanged` | marks the matched pane hook-active and writes a quiet ingest diagnostic; no notify queue entry is pushed |
 
+Current Claude Code (2.1.277) sends no hook when the operator denies a
+permission dialog, so neither `PermissionDenied` nor `Stop` closes it and the
+Agent keeps its `approval_required` observation. The held coordination message
+release is therefore a second transcript tail reader besides `Stop`: while a
+held message waits on that Agent, it reads the tail (at most 256 KiB) of the
+`transcript_path` recorded in the Agent's own Registry binding, and looks only
+at each line's type, subtype, and timestamp and whether an assistant line has a
+`tool_use` item. Nothing it reads is stored, logged, or forwarded. See
+[held messages](claude-coordination-endpoints.md#held-while-the-target-awaits-its-operator).
+
 Hook-generated queue rows use the same compact body catalog: agent label,
 event category, then the best available summary (Codex assistant text, Claude
 tool/action summary, transcript summary, error, or teammate labels). Structured
@@ -695,6 +697,53 @@ Codex and are managed from `Settings > Notifications > Agent event behavior`.
 They only affect ingest delivery; `projmux agent integrate claude` still uses the
 catalog `install` field for installed hook events.
 
+### Answering AskUserQuestion From The Command Line
+
+`projmux agent integrate claude` also installs one `PreToolUse` entry with
+`"matcher": "AskUserQuestion"` that runs
+`projmux internal claude-question-hook` (marker
+`projmux-managed:claude-question:v1`, `"timeout": 315`). Unlike the ingest
+command its stdout is not discarded, because that is where an answer is handed
+to Claude Code. Re-running the integration keeps exactly one such entry,
+`--remove` deletes it, and `config apply` never adds or changes it.
+
+The hook does nothing unless the Claude Agent that asks was opted in:
+
+```sh
+projmux agent question enable <agent-ref>
+projmux agent question disable <agent-ref>
+```
+
+For every other Agent, and for a subagent's question, the hook prints nothing
+and exits at once, so Claude Code shows its usual question prompt.
+
+For an opted-in Agent the hook records the question and holds the tool call
+open for up to 300 seconds. While it waits, Claude Code shows the hook's status
+message instead of the question prompt; pressing Esc cancels the wait and
+declines the question. Answer it from any shell:
+
+```sh
+projmux agent question list <agent-ref> [-o json]
+projmux agent question answer <agent-ref> <question-id> --option 1=<label> --index 2=<n> --text 3=<free text>
+```
+
+Questions are numbered from 1 in the order Claude asked them, and so are the
+options of each question. `--option <n>=<label>` picks an option by its exact
+label, `--index <n>=<k>` by its number, and `--text <n>=<text>` answers with
+free text; a label that is not one of the options is refused rather than taken
+as free text. A multi-select question takes several `--option`/`--index`
+occurrences, which are joined with `", "` in option order; a single-select
+question takes exactly one. Every question needs an answer. A refused answer
+changes nothing and names one reason token: `question-not-found`,
+`question-not-pending` (already answered), `question-expired`,
+`question-closed`, `question-invalid-answer`, `question-channel-off`, or
+`question-provider-unsupported`.
+
+If nobody answers within 300 seconds, the question expires and Claude Code
+shows its own prompt as usual. `agent question disable` also hands every
+question the Agent is still holding back to that prompt immediately. Records
+live in `<state dir>/agent-questions/` and settled ones are kept for a day.
+
 ## Antigravity Hook Ingest
 
 `projmux internal agent-hook ingest antigravity-hook --event <event> < payload.json` accepts
@@ -702,19 +751,24 @@ Antigravity CLI `agy` hook payloads. Antigravity v1.1.12 stdin does
 not include the event name, so the command's `--event` value is authoritative.
 Payload event aliases remain a compatibility fallback when `--event` is
 omitted. `projmux agent integrate antigravity [--dry-run|--remove]` owns exactly
-the named `projmux` entry in `~/.gemini/config/hooks.json` and separately owns
-only `statusLine` in `~/.gemini/antigravity-cli/settings.json`. Other named hooks,
-their fields, and unknown JSON values remain untouched. The generated commands
+the named `projmux` entry in `~/.gemini/config/hooks.json`. Other named hooks,
+their fields, and unknown JSON values remain untouched. projmux does not
+install, read, or judge the Antigravity `statusLine` in
+`~/.gemini/antigravity-cli/settings.json`, and never creates that file. The generated commands
 use the stable absolute projmux executable because Antigravity runs handlers
 with the config directory as cwd. The command refuses unmanaged name/command
 conflicts, malformed JSON, symlink paths, and permission failures with an
 actionable diagnostic. Doctor/Settings distinguish installed, missing,
 conflicting, and stale managed entries; stale covers executable, event/schema,
 or stdout-fallback drift and is refreshed by the install command.
-The statusline object uses the official v1.1.12 command shape with
-`enabled=true` and `stack_with_default=true`. Its direct explicit `Statusline`
-ingest command emits empty stdout, preserving the built-in line. Existing
-custom statusline commands are conflicts and are never wrapped or chained.
+
+Older releases also installed a `statusLine` bridge. `projmux config apply`
+(and so `make install`) removes only a `statusLine` whose `command` carries the
+`projmux-managed:antigravity-statusline:v1` marker, byte-preserving the rest of
+the file; `agent integrate antigravity --remove` removes it too. Any other
+`statusLine` value is left untouched and never produces a conflict. Until that
+removal runs, the leftover bridge's `--event Statusline` call exits 0 with
+empty stdout and changes nothing.
 
 The default Antigravity catalog records the five official v1.1.12 events and
 installs four non-permission events:
@@ -726,18 +780,16 @@ installs four non-permission events:
 | `PostInvocation` | marks the matched pane hook-active and writes a quiet bookkeeping diagnostic; no notify queue entry is pushed |
 | `PostToolUse` | marks the matched pane hook-active, retains tool error metadata in quiet diagnostics, and pushes no notify queue entry |
 | `Stop` | pushes an info completion unless an explicit error signal requires a critical error row |
-| `Statusline` with `tool_confirmation_pending=true` | pushes/replaces a deduped critical approval-required row outside the hook catalog |
-| `Statusline` with `agent_state=thinking|working|tool_use` | moves the matched pane to thinking/busy without notifying, unless a terminal completion/approval state must be preserved from a late refresh; a new `PreInvocation` resets the next generation to busy |
-| `Statusline` with `agent_state=idle` or `tool_confirmation_pending=false` | quiet update; does not clear completion/approval attention and creates no notification |
 | unknown events | mark the matched pane hook-active and write quiet ingest diagnostics only |
 
-Antigravity notify rows use `agent=antigravity` metadata. The v1.1.12 parser
+Antigravity has no official approval-required or mid-turn busy event, so
+projmux shows neither for Antigravity. Antigravity notify rows use
+`agent=antigravity` metadata. The v1.1.12 parser
 retains common camelCase `conversationId`, `workspacePaths`, `transcriptPath`,
 `artifactDirectoryPath`, and `modelName`; invocation `invocationNum` and
 `initialNumSteps`; post-tool `toolCall`, `stepIdx`, and `error`; and Stop
 `executionNum`, `terminationReason`, `error`, and `fullyIdle`. Existing aliases
-such as `conversation_id`, `cwd`, `workspace.path`, `agent_state`, and nested
-`statusline.tool_confirmation_pending` remain accepted. The first non-empty
+such as `conversation_id`, `cwd`, and `workspace.path` remain accepted. The first non-empty
 `workspacePaths` value is only a cwd fallback candidate; empty/absent arrays do
 not become the process cwd, and inherited `$TMUX_PANE` still wins attribution.
 `NO_TOOL_CALL`, `MODEL_STOP`, and known normal reasons are info completions.
@@ -756,9 +808,9 @@ The named entry in `hooks.json` remains the install source of truth. Use
 `agy -p '/hooks' --output-format json` only as a read-only runtime diagnosis of
 loaded sources/events; its result is never used to generate or rewrite config.
 Antigravity ingest uses `conversationId` as pane thread metadata for matching
-and as session-state resume metadata. Session restore uses
+and as Agent resume metadata. Resume uses
 `agy --conversation <uuid>` only when that id is present and UUID-shaped;
-otherwise preview and doctor render `resume unavailable`. Official snake_case
+otherwise the resume is refused rather than starting a fresh Agent. Official snake_case
 `cwd`, `conversation_id`, `transcript_path`, `agent_state`,
 `tool_confirmation_pending`, and structured `context_window.used_percentage`
 plus token fields are parsed directly. The structured percentage is persisted
@@ -824,13 +876,12 @@ empty.
 | `PROJMUX_SESSION_KIND` | `persistent` or `ephemeral` | `persistent` or `ephemeral` | empty | empty |
 | `PROJMUX_VERSION` | projmux version | projmux version | projmux version | projmux version |
 | `PROJMUX_SOCKET` | app socket metadata (`projmux`) | app socket metadata (`projmux`) | app socket metadata (`projmux`) | queue-entry socket when known; otherwise omitted |
-| `PROJMUX_PANE` | omitted: no pane exists yet | exact id returned by standard persistent/ephemeral `tmux new-session`, such as `%7`; omitted for snapshot replay | omitted | target pane when known; otherwise omitted |
+| `PROJMUX_PANE` | omitted: no pane exists yet | exact id returned by standard persistent/ephemeral `tmux new-session`, such as `%7` | omitted | target pane when known; otherwise omitted |
 
 `pre-create` intentionally has no `PROJMUX_PANE`: it runs before
 `tmux new-session` creates the first pane. Standard persistent and ephemeral
 `post-create` paths run after creation and therefore receive that exact pane
-id. Snapshot replay can restore multiple panes and does not expose a single
-returned pane at its lifecycle boundary, so it omits `PROJMUX_PANE`.
+id.
 `PROJMUX_SOCKET` is routing metadata for hook commands; it does not imply that
 the tmux client itself adds `-L` to its commands. The `post-attach` and
 `send-noti` cells describe their existing contexts; this contract adds no pane

package/docs/keybindings.md

@@ -194,8 +194,9 @@ Optional direct keys can be added for actions such as:
 | `AIResumePickerToggle` | AI resume session picker; default `Alt-4`; pressing again closes the picker popup |
 | `ai-split-right` | Open a new direct AI split to the right |
 | `ai-split-down` | Open a new direct AI split below |
-| `new-window` | New tmux window in the current pane directory |
-| `rename-window` | Rename the current tmux window |
+| `new-window` | New tmux window in the current pane directory, opened with the saved launch default |
+| `rename-window` | Rename the current Window in the Registry; see [Rename keys](#rename-keys) |
+| `rename-pane-label` | Rename the current Pane in the Registry; see [Rename keys](#rename-keys) |
 
 `AISplitPickerToggle` is the `Alt-7` popup picker toggle. It opens or closes
 the picker UI where the user chooses the AI split mode. It is separate from
@@ -205,6 +206,70 @@ The direct AI split actions create a new managed AI pane each time they run.
 Existing AI panes are left in place; the requested direction controls where the
 new pane is created.
 
+A UI split focuses the new Pane. This covers the saved-default split key, the
+provider and shell direct keys, a selection in the `Alt-7` picker or the resume
+picker (including its `new` row), and the Pane menu's Horizontal Split /
+Vertical Split. Once the create commits, the new Pane becomes the Window's
+active Pane, but only when the client that pressed the key or clicked the menu
+is still attached and still showing that Window. If that client has detached
+or moved to another Window, focus is left alone and the new Pane stays. The
+client is never moved to the Window. If the focus step itself fails, the Pane
+is kept and that client sees one line:
+`Created Pane, but projmux could not focus it: <reason>`. The public
+`projmux create pane` and `create agent` commands never change focus.
+
+A selection in the `Alt-7` picker or the resume picker closes its popup at
+once. The picker hands the selection to a detached job on the same tmux server
+and exits, and that job runs the same create the picker used to run while the
+popup stayed up as an empty frame. The new Pane therefore appears a moment
+after the popup closes. A successful split still shows nothing else; a refused
+create, a failed focus, or a split start notice reaches the client that pressed
+the key as one line. Every picker row travels this way: a selection is a plain
+value -- a provider, and for a resume the conversation it names. The provider
+picker offers one row per enabled provider plus the shell row; it has no
+per-launch model or effort row.
+
+### The new Window's first Pane
+
+`window.create` (v0 id `new-window`) and the Window menu's New At End decide the
+new Window's first Pane before the Window exists, following the saved launch
+default -- the same setting the saved-default split key reads (Settings > AI
+Settings, stored in `$XDG_CONFIG_HOME/projmux/tmux-ai-split-mode`). The order is:
+
+1. Ask. A picker mode opens its picker on the Pane the key was pressed in; a
+   provider mode and `shell` are already the answer and open nothing.
+2. Create the Window with one shell Pane.
+3. Fill it: an Agent answer is created in that Window first, and the shell is
+   then removed through the canonical Pane delete.
+4. Move the pressing client onto the finished Window.
+
+The client therefore never sees a shell Pane that is about to be replaced.
+
+| Saved default | The new Window ends up with |
+| --- | --- |
+| `shell` | the shell Pane the create made; nothing else runs |
+| `claude`, `codex`, `antigravity` | exactly that Agent Pane, with no picker |
+| `selective` (also the unset default) | whatever the `Alt-7` picker chose: that Agent Pane, or the shell Pane for the shell row; its `resume` row opens the resume session list in the same popup |
+| `resume` | whatever the resume picker chose, on the same terms |
+
+Cancelling the picker creates nothing: no Window, and the client stays where it
+was. If the picker cannot be opened, nothing is created either. An Agent answer
+is committed with its Window in one transaction, so a provider that Settings has
+since disabled or an Agent that could not be created leaves no Window behind.
+Both report one line on the pressing client instead of the usual
+`Created Window`:
+`projmux Create Window failed; no Window was created: <reason>`. The line is
+fitted to that client's width (80 cells when the width cannot be read). The
+outcome is never cut; a reason too long to fit keeps its front, which names the
+step that failed, and its end, where tmux's own cause is, and loses its middle
+to one `…`. A create whose pressing client could not be moved still fills the
+Window with what was chosen and shows the existing `Created Window, but
+projmux could not move this client to it` line.
+
+The typed `projmux create window` and `projmux create agent --create-window`
+are unchanged and never read the saved default: a typed command's outcome
+stays visible in its own argv.
+
 Pane switching is catalogued as transport-dependent and the generated app tmux
 config binds `M-Left`, `M-Right`, `M-Up`, and `M-Down` to `select-pane`
 movement. Previous/next window remain transport-dependent and the generated app
@@ -295,7 +360,47 @@ write; the projmux process never issues `kill-pane` or `kill-window`.
 
 A mouse menu acts on what was clicked, not on what is focused: Kill, Rename, and
 New At End in the status-line Window menu act on the clicked Window, and the
-Rename prompt starts with that Window's name.
+Rename prompt starts with that Window's name. New At End opens the new Window's
+first Pane with the saved launch default; see
+[The new Window's first Pane](#the-new-windows-first-pane).
+
+## Rename keys
+
+`rename-window` (`window.rename`) and the Window menu Rename item run
+`internal tmux window-rename`; `rename-pane-label` (`pane.rename`) runs
+`internal tmux pane-rename`. Neither has a default key. Both are Registry
+renames through the same owner as `projmux rename window` and
+`projmux rename pane`: the Pane the key was pressed in, or the menu target,
+resolves to its exact Registry Window or Pane, its `metadata.name` changes, and
+its mirror converges with it. A Window rename writes `@projmux_window_name`
+and, after the Registry commit, the tmux `window_name`; a Pane rename writes
+`@projmux_pane_label`. A Continue that rebuilds the session from the Registry
+therefore keeps the new name, including for the first Window of a session.
+
+The prompt response is used exactly as typed:
+
+- An empty or whitespace-only response changes nothing, not even the label,
+  and the client is told nothing was changed.
+- A response that is not a valid name, such as one with a space, leading or
+  trailing whitespace, or a character like `'`, `"`, `$`, `;`, `%`, or `#`, is
+  refused with the reason and the usable spelling projmux would accept, for
+  example `a-b` for `a b`. Nothing is written.
+- A name already used by another Window of the same Project or ControlSession,
+  or by another Pane of the same root, is refused. No suffix is added.
+- A Pane with no Registry identity, such as one on a server projmux does not
+  manage, is refused with no write.
+- A name a launcher chose, such as an Agent Pane's, renames like any other.
+
+Every result is one line on the client that pressed the key. The response
+reaches projmux on stdin inside a quoted here-document, so no shell parses it.
+tmux still format-expands the `run-shell` command before any shell runs, as it
+does at its own `:` prompt: a `#{...}` sequence in a response is substituted and
+a `#(...)` sequence is run by tmux as a format job. Names cannot contain `#`, so
+a response that still holds one is refused.
+
+`internal tmux rename-pane <pane> <label>` is a separate label-only helper with
+no generated binding. It writes `@projmux_pane_label` without touching the
+Registry, so the next Continue restores the Registry name.
 
 The standalone `~/.tmux.conf` snippet keeps tmux's stock `prefix <`, `prefix >`,
 `MouseDown3Status`, `M-MouseDown3Status`, and `M-MouseDown3Pane` menus; it

package/docs/legacy-cli-retirement.md

@@ -32,12 +32,12 @@ unknown-command contract.
 | `notify push`, `notify list`, `notify ack`, `notify reconcile` | `create notification`, `get notifications`, `notification ack`, `notification reconcile` |
 | direct `pin list|add|remove|toggle|clear` | `pin project ...` |
 | `prune ephemeral` | `runtime prune` |
-| `prune session-state ...` | `prune snapshot ...` or `delete snapshot ...` |
-| `session-state status|save|delete|restore|preview|popup` | `get snapshots`, `create snapshot`, `delete snapshot`, `restore snapshot` |
+| `prune session-state ...` | None. Project snapshots were removed; `registry.json` is the only saved Project state |
+| `session-state status|save|delete|restore|preview|popup` | None. The interim `create|get|delete|restore|prune snapshot` replacements were removed with Project snapshots; Continue project and Clear layout and open start closed Projects from the Registry |
 | direct `tag list|toggle|clear`, `tag project ...` | `runtime tag ...` |
 
 The surviving mixed-root commands are exactly `attach project`, `focus
-project|window|pane`, `pin project`, and `prune project|snapshot`. The Shortcut
+project|window|pane`, `pin project`, and `prune agent|project`. The Shortcut
 routes `doctor`, `quit`, `resources`, `settings`, `shell`, `switch`, and
 `welcome` remain. Singular/plural resource-kind aliases remain.
 

package/docs/legacy-diagnostics-inventory.md

@@ -7,11 +7,11 @@ CLI, config action, output format, permission, or retention contract.
 
 | Surface | Producer / reader files | Current consumer and data boundary | Candidate and rationale | Separate follow-up |
 | --- | --- | --- | --- | --- |
-| `PROJMUX_USAGE_DEBUG` | `internal/app/usagecmd/usage.go`; adapter contract in `internal/core/usage/registry.go` and safe token helper in `internal/core/usage/adapters/claude/claude.go` | `projmux internal status usage` operator stderr; documented by `AGENTS.md`, `docs/configuration.md`, and `docs/usage-tracking.md`; `internal/app/usagecmd/usage_test.go` fixes the opt-in behavior; adapter errors are otherwise swallowed on the status hot path | **Keep.** Usage adapters are not adopted by the common journal and this opt-in stderr is the only immediate adapter failure consumer. | No removal follow-up. Re-evaluate only with a separately scoped usage diagnostics adoption. |
-| `PROJMUX_SESSIONSTATE_DEBUG` | read/output gate in `internal/app/tmux.go` | Operator/automation stderr for a quiet autosave error; documented in `docs/configuration.md`; tests in `internal/app/tmux_test.go` cover popup environment propagation | **Deprecate candidate.** Phase 3 already records the same quiet autosave failure as a closed common error, but scripts may consume stderr. | Yes: announce deprecation, audit scripts, and remove only in a breaking PR after a compatibility window. |
-| `PROJMUX_FOCUS_DEBUG` | read/output gate in `internal/app/focus.go` | Operator stderr one-line raw target/session/window/pane/socket/client/source/kind; documented in `AGENTS.md`, `docs/cli.md`, `docs/configuration.md`, `docs/operational-diagnostics.md`, and the maintained test list in `docs/agent-workflow.md`; `internal/app/focus_test.go` fixes the byte contract | **Deprecate candidate.** Phase 4 common focus events are safer for support, but the raw routing line remains a distinct local troubleshooting consumer. | Yes: publish safe replacement guidance and remove only through a breaking deprecation roadmap. |
+| `PROJMUX_USAGE_DEBUG` | `internal/app/usagecmd/usage.go`; adapter contract in `internal/core/usage/registry.go` and safe token helper in `internal/core/usage/adapters/claude/claude.go` | `projmux internal status usage` operator stderr; documented by `docs/configuration.md` and `docs/usage-tracking.md`; `internal/app/usagecmd/usage_test.go` fixes the opt-in behavior; adapter errors are otherwise swallowed on the status hot path | **Keep.** Usage adapters are not adopted by the common journal and this opt-in stderr is the only immediate adapter failure consumer. | No removal follow-up. Re-evaluate only with a separately scoped usage diagnostics adoption. |
+| `PROJMUX_SESSIONSTATE_DEBUG` | none; the autosave route that read it is now a no-op | Ignored; `docs/configuration.md` lists it as ignored | **Removed.** Autosave no longer exists, so there is no quiet error left to surface. The variable was dropped in the breaking change that removed autosave. | No. |
+| `PROJMUX_FOCUS_DEBUG` | read/output gate in `internal/app/focus.go` | Operator stderr one-line raw target/session/window/pane/socket/client/source/kind; documented in `docs/cli.md`, `docs/configuration.md`, and `docs/operational-diagnostics.md`; `internal/app/focus_test.go` fixes the byte contract | **Deprecate candidate.** Phase 4 common focus events are safer for support, but the raw routing line remains a distinct local troubleshooting consumer. | Yes: publish safe replacement guidance and remove only through a breaking deprecation roadmap. |
 | `PROJMUX_NATIVE_DEBUG_LOG` | `internal/ui/picker/backend.go` and `colorgrid.go` append native picker actions/query/value/errors; `internal/app/tmux.go` inherits it into popup environments | Developer-selected file path; popup inheritance is covered in `internal/app/tmux_test.go`; no public CLI/support reader, retention bound, or privacy redaction | **Remove candidate.** The opt-in trace can contain user query/value/error text and is not bounded. Current behavior remains intact because a safe bounded replacement and migration notice are outside Phase 6. | Yes: design a bounded private picker trace or common closed events, document migration, then ship removal as breaking. |
-| bounded `ai-ingest.log` | Codex producer `internal/app/ai_ingest_codex.go`; Claude producer `internal/app/ai_ingest_claude.go`; Antigravity producer `internal/app/ai_ingest_antigravity.go`; tmux-bell producer plus shared `appendAIIngestLog`, path, cap, and trim in `internal/app/ai_ingest.go`; common projection in `internal/app/ai_ingest_diagnostics.go` | Canonical reader `projmux diagnostics agent-hook`; count-only support reader `internal/app/diagnostics_report.go`; docs consumers `docs/cli.md`, `docs/hooks.md`, `docs/configuration.md`, `docs/operational-diagnostics.md`, and the maintained test list in `docs/agent-workflow.md`; `internal/app/ai_ingest_test.go`, `internal/app/ai_ingest_diagnostics_test.go`, `internal/app/diagnostics_report_test.go`, and `test/integration/linux-smoke.sh` cover retention/consumer/corrupt/permission behavior | **Keep behind canonical diagnostics.** Phase 5 common events cover anomalous classification but intentionally omit normal state/notify/quiet/dedupe detail and all identity. | Re-evaluate only if the detailed local diagnostic requirement changes. |
+| bounded `ai-ingest.log` | Codex producer `internal/app/ai_ingest_codex.go`; Claude producer `internal/app/ai_ingest_claude.go`; Antigravity producer `internal/app/ai_ingest_antigravity.go`; tmux-bell producer plus shared `appendAIIngestLog`, path, cap, and trim in `internal/app/ai_ingest.go`; common projection in `internal/app/ai_ingest_diagnostics.go` | Canonical reader `projmux diagnostics agent-hook`; count-only support reader `internal/app/diagnostics_report.go`; docs consumers `docs/cli.md`, `docs/hooks.md`, `docs/configuration.md`, and `docs/operational-diagnostics.md`; `internal/app/ai_ingest_test.go`, `internal/app/ai_ingest_diagnostics_test.go`, `internal/app/diagnostics_report_test.go`, and `test/integration/linux-smoke.sh` cover retention/consumer/corrupt/permission behavior | **Keep behind canonical diagnostics.** Phase 5 common events cover anomalous classification but intentionally omit normal state/notify/quiet/dedupe detail and all identity. | Re-evaluate only if the detailed local diagnostic requirement changes. |
 
 The separate host resource status path is not a legacy debug surface:
 `internal/app/status.go` invokes `internal/systemstatus.Sampler` for

package/docs/native-picker.md

@@ -17,7 +17,7 @@ picker process. `internal/ui/picker` owns the interaction contract and
 | Deferred state | Deferred and event-triggered updates preserve query and selection by value, can repeat, and may explicitly choose a new focus value. | `TestNativeInteractiveDeferredUpdateTriggerRefreshesRepeatedly`; switch and notify sidebar mutable-refresh app tests |
 | Preview | Popup previews use a right split, sidebar previews use a bottom split, control bytes and tabs are normalized before clipping, and preview scrolling/cycling rerenders in place. | `TestNativeInteractiveRendersWidePreviewBesideList`; `TestNativeInteractiveRendersDownPreviewBelowList`; `TestRenderSplitPreviewRowsNormalizesPreviewTabsBeforeTruncating`; `TestNativeInteractiveRendersPreviewOffset` |
 | Mouse | SGR mouse input focuses on primary down, follows drag, accepts on matching release, and scrolls with the wheel. | `TestNativeInteractiveSelectsOnMouseRelease`; `TestNativeInteractiveMouseDragFollowsSelection`; `TestNativeInteractiveSupportsMouseWheelSelection` |
-| Lifecycle | Interactive runs use the alternate screen, synchronized/coalesced frame updates, controlling-TTY fallback, and deterministic reader cleanup. | `TestNativeInteractiveUsesAlternateScreen`; `TestNativeInteractiveWrapsRedrawsInSynchronizedUpdates`; picker/setup lifecycle tests in `docs/agent-workflow.md` |
+| Lifecycle | Interactive runs use the alternate screen, synchronized/coalesced frame updates, controlling-TTY fallback, and deterministic reader cleanup. | `TestNativeInteractiveUsesAlternateScreen`; `TestNativeInteractiveWrapsRedrawsInSynchronizedUpdates`; picker/setup lifecycle tests in `internal/ui/picker/backend_test.go` and `internal/app/native_picker_test.go` |
 
 ## Rendering And Popup Chrome
 
@@ -97,7 +97,5 @@ saved-selector access, propagation, or external picker launch path.
 
 ## Maintenance
 
-Update this document and the maintained list in
-[`docs/agent-workflow.md`](agent-workflow.md) whenever picker behavior changes
-coverage level, gains a new product flow, or changes input/render/action
-semantics.
+Update this document whenever picker behavior changes coverage level, gains a
+new product flow, or changes input/render/action semantics.

package/docs/notify-queue.md

@@ -73,7 +73,7 @@ routing/debug context such as `agent`, `thread_id`, `turn_id`, `cwd`,
 `teammate_name`. Antigravity hook rows carry `agent=antigravity`,
 `conversation_id`, `termination_reason`, `fully_idle`,
 `tool_confirmation_pending`, `agent_state`, and `context_window` when present.
-The same `conversation_id` can seed session-state restore via
+The same `conversation_id` can seed an Agent resume via
 `agy --conversation <uuid>` when it is UUID-shaped. Antigravity
 account quota remains outside notify attention semantics: `context_window` is a
 separate conversation-local gauge and is never treated as quota data.

package/docs/operational-diagnostics.md

@@ -41,7 +41,7 @@ Project lifecycle operator diagnostics also keep plans mutually exclusive:
 classes. Startup and unregister failures print the closed action, failing
 stage, old Project UID, and new Project UID (or `-` when absent). These opaque
 UIDs and stage labels are bounded control data; root paths, pane content,
-history, prompts, transcripts, and snapshot contents are never identity or
+history, prompts, and transcripts are never identity or
 intent authority.
 
 Automatic Window teardown decisions use `component=topology` and
@@ -58,29 +58,52 @@ optional opaque `window_uid` (`win-…`) and `pane_uid` (`pane-…`) Registry UI
 tmux `%N`/`@N`/`$N` handles, socket paths, session names, cwd, argv, and free
 text are never recorded, and every other event family rejects these fields.
 
-Session State mutations use one outcome-only `session-state.outcome` record
-per selected attempt. The closed operations are `session-state.save`,
-`session-state.autosave`, `session-state.restore`, and `session-state.delete`;
-an error uses only the matching `.failed` code, `kind=runtime`, and an empty
-message. Optional sources are limited to `manual`, `settings-latest`,
-`settings-named`, `autosave`, `startup-latest`, `startup-named`, and `prune`.
-Successful save and actual startup restore outcomes contain only exact
-non-negative `window_count`, `pane_count`, `shell_recipe_count`,
-`agent_recipe_count`, and `startup_recipe_count` aggregates. Successful delete
-contains only `item_count`; errors contain no counts. Snapshot paths/content,
-project paths, pane cwd/commands, snapshot names, and agent or conversation
-identifiers are never projected.
-
-Direct and popup save, Settings latest/named save, direct and Settings delete,
-deduplicated prune delete, and actual latest/named project-startup replay own
-these outcomes. Preview, dry-run, and nested store/replay calls do not.
-Autosave success and disabled, not-due, or fresh no-ops always write zero
-records; a real autosave failure writes exactly one error even when `--quiet`
-preserves its historical successful exit. Session State logical ownership
-suppresses a generic top-level outcome even when journal append fails. An
-actual restore may also produce its runtime lifecycle pair with the same run
-ID; the lifecycle pair and Session State terminal outcome describe different
-contracts and are not duplicates.
+Create transactions use `component=create` and `event=create.outcome`: one
+record per create transaction, written under the process `run_id`. It is
+measurement only and changes nothing about the create itself. The kind of the
+create is carried in the closed `operation` field: `window` (`create window`
+and the UI new Window, including one whose answer is an Agent), `pane`
+(`create pane`, the split UI's shell Pane, and the pane-menu split), `agent`
+(`create agent` and the split UI's Agent Pane, including a resume-picker
+pick, which creates a new Agent), or `resume` (`agent resume`, including the
+resume `agent persona` runs). A successful transaction is `info`/`success`;
+a failed one, including one that was rolled back, is `error`/`error` with
+`kind=runtime`, so the support report's existing error-only projection
+carries it. The record adds only two timings:
+
+- `duration_ms` runs from entering the create transaction to its return. It
+  includes the runtime route bind, the wait for the Registry lock, the time
+  the lock is held, and on failure the rollback, and in every case the
+  create-operation lease clear. It excludes everything outside the
+  transaction: process start and exit, argument parsing, scope and selector
+  resolution, the Settings enabled-agents gate, the time a picker or prompt
+  waits for the operator, the result line printed after the commit, and
+  Agent activation observed after the transaction returns.
+- `lock_held_ms` runs from entering the Registry mutation to the Registry
+  update returning. It includes the create's guards, reconciliation, Registry
+  and tmux mutations, the store's own validate and write, and the unlock. It
+  excludes the wait for the lock and the Registry read before the mutation
+  starts. It is absent when the transaction failed before it entered the
+  mutation, and `0 <= lock_held_ms <= duration_ms` always holds.
+
+The record is appended after the transaction returns, so never while the
+Registry lock is held, and a journal failure never changes the create's
+result, exit status, stdout, or stderr. It does not replace the invocation's
+`command.outcome`, and it does not count guard reads or time individual
+guards. The generated Window rename also runs through the same transaction
+and is not recorded, because it is not a create. Every other event family
+rejects `lock_held_ms` and the `create` component.
+
+projmux no longer emits `session-state.outcome` records. Project snapshots
+were removed, and the retained `internal tmux autosave-session-state` route is
+a no-op that writes nothing. Records written by older versions keep their
+closed vocabulary: the `session-state.outcome` event, the
+`session-state.save`, `session-state.autosave`, `session-state.restore`, and
+`session-state.delete` operations with their `.failed` codes, the sources
+`manual`, `settings-latest`, `settings-named`, `autosave`, `startup-latest`,
+`startup-named`, and `prune`, and the aggregate `window_count`, `pane_count`,
+`shell_recipe_count`, `agent_recipe_count`, `startup_recipe_count`, and
+`item_count` fields still validate and parse when the journal is read.
 
 Notify and focus transitions use the same process `run_id` and add only closed
 `transition`, `disposition`, `provider`, `category`, and `route` enums. Notify
@@ -119,8 +142,9 @@ is the generic `ai`; ingest providers are `codex`, `claude`, `antigravity`, or
 for example, `tmux-bell` can only emit `bell`, while watcher events can only use
 the generic `ai` provider and `watcher` kind. Provider event names are projected
 into semantic kinds such as `prompt`, `permission`, `stop`, `notification`,
-`tool`, `session`, `compact`, `subagent`, `teammate`, `statusline`, `invocation`,
-`lifecycle`, `bell`, `payload`, or `unknown`. A raw or future event name can
+`tool`, `session`, `compact`, `subagent`, `teammate`, `invocation`,
+`lifecycle`, `bell`, `payload`, or `unknown`. `statusline` is still accepted
+when reading older records but is no longer written. A raw or future event name can
 therefore be diagnosed as `unknown` but can never extend the journal schema.
 
 One watcher process emits at most one `started` transition, one terminal
@@ -288,22 +312,20 @@ before the next append, and the reader skips malformed or truncated records.
 Classification is intentionally conservative for mutation-capable interactive
 commands: opening session/project/settings/popup flows is treated as changing
 even when a user cancels. Explicit read variants (`internal status`, `list`,
-`get`, read-only restore preview, config rendering, plain welcome, and the diagnostics viewer) remain
+`get`, config rendering, plain welcome, and the diagnostics viewer) remain
 read-only. The successful automatic hook/poll paths `internal agent-hook ingest`, `attention
 arm`, `attention clear`, `attention window`, `internal tmux autosave-session-state`, and
 `window record` are also read-only so high-frequency operation does not append
 to the journal; an error from any of them still records exactly one safe error
 outcome. Explicit user mutations such as `attention toggle` retain their
 state-changing success record. Direct top-level help and explicit preview-only intents (`update
-apply --dry-run`, AI integration dry-runs, and snapshot projection restore with
-`--dry-run`) are also read-only. Approved snapshot projection restore is a
-state-changing operation. Doctor is a stricter
+apply --dry-run` and AI integration dry-runs) are also read-only. Doctor is a stricter
 boundary: successes and errors never append to this journal, so diagnostics do
 not make its filesystem contract self-defeating. Support report success and
 errors likewise never append; its strict reader shares the viewer's tolerant
 decoder but never creates/locks/chmods/repairs/truncates the source journal.
 Multi-mode commands such as AI status/topic,
-terminal apply, snapshot delete, update check, and welcome popup inspect only
+terminal apply, update check, and welcome popup inspect only
 allowlisted mode/flag names; boolean `=false` values retain mutation-capable
 classification, and no flag values are ever recorded. Help-looking tokens
 after the direct command position stay conservatively mutation-capable because