projmux 0.15.2 → 0.16.0

package/docs/cli-guide.md

@@ -97,8 +97,9 @@ invocation context. Mixed Registry/Runtime pickers keep KIND in both profiles.
 Wide stdout preserves full values at every terminal width. See [Column profiles](column-profiles.md)
 for the exact per-kind matrix and migration from the previous default output.
 
-The resource routes (`get`, `describe`, `create`, `rename`, `rebind`, `delete`,
-`agent resume`) address stored resources through one shared selector grammar.
+The resource routes (`get`, `describe`, `create`, `rename`, `label`, `rebind`,
+`delete`, `agent resume`) address stored resources through one shared selector
+grammar.
 
 The grammar in one paragraph: a value is either `uid:<uid>` or a bare
 `metadata.name`. There is no bare-uid form, values are never split on commas,
@@ -201,7 +202,7 @@ the item: only an exact UID-bound live Window name or Pane title sets
 `observed: true`; Project and Agent context, Registry fallbacks, and unmatched
 runtime objects remain unobserved. This is a read projection, not stored
 resource state or selector authority. It does not change `-o metadata`, the
-Registry or snapshot schema, singular `describe ... -o json`, or `get pane -o
+Registry schema, singular `describe ... -o json`, or `get pane -o
 json`; an empty plural result remains one List document with `"items": []`.
 
 ### Reference scope: the active Project namespace
@@ -252,8 +253,27 @@ The contract:
 `create window|pane|agent|<provider>` is resource-backed on every spelling.
 There is no mode flag and no second parser: the same argv means the same thing
 whether or not `--project` is present, and `-w`, `--create-window`, `--pane`,
-`--selector`, `--placement`, `--name`, `--label`, `--cwd`, `--add-dir`, `-o`,
-and the `--` payload all reach the same parser either way.
+`--selector`, `--placement`, `--cwd-from`, `--name`, `--label`, `-o`, and the
+`--` payload all reach the same parser either way. `--cwd` and `--add-dir` are
+provider create flags: they are defined on `create agent` and the three provider
+shortcuts, not on `create window` or `create pane`.
+
+`--cwd-from project|pane` selects where the new split starts. `project` (the
+default) starts it in the owner Project root. `pane` starts it in the active
+Pane's live directory while that directory is inside the owner Project root, and
+otherwise starts it in the root and says so in one stderr line; it never
+refuses. The flag cannot be combined with `--cwd`, which names an Agent working
+directory outright.
+
+On the CLI the flag is the only input: `create pane`, `create agent`, and the
+provider shortcuts never read `[ai] split_cwd_from`, so with no `--cwd-from`
+they always start in the owner Project root, whatever the global or project
+config says. A CLI result is determined by its arguments, and scripts must not
+change behavior because someone changed a Settings value. That config (and the
+`AI > New splits start in` Settings row that writes it) only decides splits
+started from the UI -- keybinding splits, the launcher, the resume picker's new
+row, and the Pane menu -- in the order flag > project config > global config >
+default. See [configuration.md](configuration.md).
 
 The scope resolves in two branches:
 
@@ -339,12 +359,22 @@ they name `--project` as the fix:
   gone — a `recoverable` runtime is reported, never adopted.
 
 Every create is **detached**: no create moves the client. Use `focus pane` or
-`-o pane-id` when you want to end up in the new pane. A natural create validates
+`-o pane-id` when you want to end up in the new pane. One exception: the human
+intent route `internal tmux window-create` (the `window.create` key and the
+Window menu New At End) moves the pressing client to the new Window after its
+create commits and then opens that Window's first Pane with the saved launch
+default; public `create` stays detached and never reads that saved default. A natural create validates
 the inherited exact route and Pane containment. An explicit resource scope
 binds the selected app resource route without letting unrelated inherited
 `TMUX`/`TMUX_PANE` choose or change the resource target; exact Project plus
 `--create-window` therefore uses the validated app logical `-L` route on its
-first attempt, with no `env -u` workaround. Runtime safety remains independent
+first attempt, with no `env -u` workaround. `agent resume` binds the same way,
+and for the same reason: the Agent it rebinds is one exact reference and the
+Pane it splits is that Agent's Window's stored `spec.anchorPaneRef`, so no
+anchor Pane has to be typed or inherited to name a target that is already
+named. Unsetting `TMUX` is not a substitute for either — it selects the
+detached branch, which asks for an explicit `--anchor %N` instead of asking for
+less. Runtime safety remains independent
 and may refuse before mutation. An inherited app-owned `TMUX` socket/PID stays
 route evidence: projmux validates its exact `-S` path, ownership/logical
 markers, logical `-L` alias, and PID while ignoring unrelated `TMUX_PANE`
@@ -415,12 +445,20 @@ disabling the keys.
 ### Rename and rebind live convergence
 
 `rename project|window|pane` commits the selected Registry `metadata.name` and
-then updates only its exact UID-bound live transport field:
+then updates only its exact UID-bound live transport fields:
 
 - Project: `@projmux_project_name` (never the tmux session name)
-- Window: `@projmux_window_name` (never tmux `window_name`)
+- Window: `@projmux_window_name` and the tmux tab `window_name` (never
+  `displayName`)
 - Pane: `@projmux_pane_label` (never raw `pane_title`)
 
+The Window tab converges only when the invocation has a proven runtime route,
+which is what running inside the projmux tmux runtime gives it. Outside one the
+rename is Registry-only: it exits zero and prints one line on stderr saying the
+tab still shows the old name until a rename runs inside that runtime. There is
+no flag for either behavior; the next time that Window is materialized from the
+Registry, the tab carries the committed name.
+
 `rename agent` changes only the Agent's stable root-scoped `metadata.name`.
 It does not change the Agent topic, provider, lifecycle state, or managed Pane
 name/title. `create agent` derives the managed Pane's name from the Agent's
@@ -442,6 +480,42 @@ already committed, and names the same public reconcile route as the retry. A
 valid unique Project UID wins over the old path after rebind; unknown and
 duplicate UID claims remain fail-closed.
 
+### Labels after creation
+
+`projmux label project|window|pane|agent` writes `metadata.labels` on exactly
+one resolved resource. It is the post-creation half of `create --label`, which
+keeps its exact behavior: the same field, written by two routes at two moments.
+A label change has no live projection at all -- no tmux option, no tab, no pane
+title -- so the Registry commit is the whole operation and there is nothing to
+converge afterwards.
+
+The operand grammar is Kubernetes': `key=value` sets a label, `key=` sets it to
+the empty string, and `key-` removes it. Set and remove operands may be mixed in
+one invocation, and a key named twice is refused rather than resolved by argv
+order.
+
+Two properties follow from that grammar and are worth stating outright:
+
+- **Shape decides what a positional token is, never the Registry.** A token
+  carrying `=` is always a label operand, and it can never be a resource name
+  anyway, because `=` is not a legal name rune. A token ending in `-` is always
+  a removal. A resource whose `metadata.name` happens to end in `-` is therefore
+  addressed by `uid:<uid>` or by its scope flag rather than positionally.
+- **There is no `--overwrite` guard and no value policy.** Setting a key that
+  already holds a value overwrites it, and removing a key that is absent
+  succeeds and changes nothing; both report the resulting label set. A label
+  value has no length or character-set rule here, unlike in Kubernetes. The
+  syntax is borrowed; the value constraints deliberately are not, because
+  `create --label` has never had them and one field must not have two contracts
+  depending on which route wrote it.
+
+What belongs in a label is decided by one question: is this a value you will
+ever filter on? `--selector key=value` reads labels and only labels, so
+classification that selects (`role=epic-owner`, `phase=task-0`) belongs there.
+A value that is unique per resource -- a link, an artifact path -- fills the
+selector space with keys nothing will ever match and belongs in an annotation
+instead.
+
 ### Agent topic, interaction, activation, and workspace
 
 `projmux agent capabilities --provider <codex|claude|antigravity>` prints the
@@ -503,7 +577,8 @@ id and one text input. Immediately before that write it reads one bounded,
 content-free lifecycle snapshot: fresh active/in-progress returns
 `turn-in-progress`, fresh idle/terminal repairs stale cached state and starts
 once, and an unavailable or inconsistent snapshot returns
-`turn-state-unavailable` with no turn mutation. `steer` also reads that
+`turn-state-unavailable` with no turn mutation. Broker read admission refusals
+remain visible as `lifecycle-retry` or `lifecycle-busy`. `steer` also reads that
 content-free snapshot before any write and submits exactly once only when it
 still proves the same exact active turn. Fresh idle, terminal, or different-turn
 state returns `no-active-turn`; an unavailable or inconsistent read, including
@@ -516,6 +591,12 @@ supplies the cached exact turn id without adopting the steer preflight in this
 phase. These commands never install sticky model, effort, cwd, sandbox,
 permission, or collaboration overrides.
 
+Codex coordination delivery chooses start or steer inside one native control
+operation from one lifecycle snapshot. If that read returns `lifecycle-retry`,
+it waits through the fixed retry window and reads once more before any write;
+no provider write is ever retried.
+An older observer that refuses this operation with `invalid-operation` gets one legacy start attempt, followed by steer only for `turn-in-progress`.
+
 Approval review shows only the safe one-shot intersection supplied by the
 exact pending request. Command, file, and network requests are limited to
 `accept`, `decline`, and `cancel`; permission grants echo the received supported
@@ -566,7 +647,7 @@ with its live `$N/@N` in the same commit. A non-last Pane is removed while its d
 Agent is retained Offline with its conversation identity. For a last Pane, that evidence is retained until a
 matching `window-unlinked` hook removes the Window; a final Project Window also
 removes its Window descendants while retaining the exact Project uid, root,
-reservation, pins, snapshots, and external assets as a valid zero-Window
+reservation, pins, and external assets as a valid zero-Window
 Project. Managed runtime Stop is different: it stops only the exact runtime and
 keeps the complete desired Project/Window/Pane graph closed for a same-UID
 Continue. Shell and Claude/Codex clean exit have the same result; `/exit`, pane
@@ -616,19 +697,31 @@ owner Project root from `get`/`describe`, and a successful resume persists that
 normalized effective workspace without changing Window Project ownership.
 
 When `create agent -- <initial-prompt>` is used, normal resource creation and
-provider activation are distinct. Projmux first waits up to five seconds for an
-exact provider `SessionStart`; that readiness evidence leaves activation
-`pending` and opens an independent five-second initial-task acknowledgement
+provider activation are distinct. Projmux first waits up to thirty-five seconds
+for an exact provider `SessionStart`; that readiness evidence leaves activation
+`pending` and opens an independent twelve-second initial-task acknowledgement
 window. A `UserPromptSubmit` acknowledgement may also arrive directly before
 the readiness observer sees `SessionStart`. The two stages are independently
-bounded, so provider startup plus an acknowledgement later than two seconds may
-take more than five but never more than ten seconds. Neither stage captures pane
-content or stores the prompt. Acknowledgement returns success and the requested
-exact `%N` output. If
-activation cannot be confirmed, the command exits nonzero while naming the
-exact Agent UID and Pane plus safe provider retry and `delete agent ... --yes`
-cleanup options. The live resources remain explicit and retryable rather than
-being reported as an ordinary success.
+bounded, so provider startup plus a late acknowledgement may take more than
+either bound alone but never more than forty-seven seconds. Both bounds are
+sized from measured provider startup on a loaded machine, with headroom past
+the measured peak, because a provider that is merely slow is not a failed one;
+they are not sized for a dead provider, which is why exceeding them still
+reports failure. Neither stage captures pane content or stores the prompt.
+Acknowledgement returns success and the requested exact `%N` output.
+
+If activation still cannot be confirmed, the command exits nonzero. A nonzero
+exit here does not mean the Agent is gone or unusable: the Agent and its
+managed Pane were created and are still live, and nothing is rolled back. The
+diagnostic therefore names the exact Agent UID and Pane first and orders the
+remediation cheapest-first — re-read the committed activation with `projmux get
+agent uid:<uid>`, since a provider hook that arrives after the bound still
+refines the activation to `acknowledged`; then look at the Pane or the provider
+transcript for the initial task and retry it through the provider if it never
+arrived; and only when neither read shows activation evidence, clean up with
+`projmux delete agent uid:<uid> --yes`. Deletion is the last option rather than
+the first, because a caller that acts on the exit code alone would otherwise
+remove an Agent that is already working.
 
 Activation metadata is bounded to provider-hook provenance and fixed
 acknowledged/timed-out/failed diagnostics. Provider error strings and initial
@@ -734,17 +827,16 @@ client only after it converges; a refusal, a failed preflight, or a rolled-back
 partial leaves the client where it was and reports the exact stage. The
 activation is pinned to the session the open targets, so a Project whose
 Registry projects a different session name is refused instead of populating a
-session the open never reaches. With no saved `sidebar-startup-picker`
-preference, the closed-Project startup screen has exactly two neutral actions;
-the missing-file default is read-only and does not create a config file. Saved
-`on` retains that explicit choice, while saved `off` skips the screen and keeps
-the registered-Continue/unregistered-Fresh automatic decision. `Continue
+session the open never reaches. A registered closed Project always gets the
+startup screen, which has exactly two neutral actions; a root that is not a
+registered Project never gets it and opens fresh. There is no setting that
+skips the screen. `Continue
 project` materializes current Registry desired state with the same Project UID.
 A retained graph keeps descendant UIDs; a
 zero-Window Project atomically receives a new canonical Window/shell UID chain.
-A deleted Project may use only the exact usable snapshot compatibility path;
-an unavailable Continue is an explicit zero-write refusal with no Fresh
-fallback. `Recreate Project` is the one startup row that replaces identity, and it asks
+A root that is not a registered Project cannot be continued: Continue is an
+explicit zero-write refusal that points to `Clear layout and open`, with no Fresh
+fallback. `Clear layout and open` is the one startup row that replaces identity, and it asks
 before it does. Choosing it opens a confirmation naming the exact old Project
 UID and its Window/Pane/Agent counts; declining returns to the startup rows
 with zero Registry writes, and an unreadable confirmation declines rather than
@@ -752,7 +844,7 @@ proceeds. An unregistered root has no identity to replace and is not asked.
 Confirmed, it atomically replaces the same-root graph with a new Project UID
 and new canonical Window/shell UIDs, then hands off only after ordinary
 materialization. A repeat replaces identity again. The root, git/worktrees,
-trust decision, unrelated roots, and snapshot bytes remain unchanged.
+trust decision, and unrelated roots remain unchanged.
 
 Materialization launches or resumes declared Agents through the canonical
 provider/trust path and creates their managed Agent-owned Panes. An individual
@@ -780,9 +872,12 @@ report a final-window cascade with its actual root kind.
 Pane and Agent Registry-only deletion is deliberately narrower. It accepts
 only an explicit exact `uid:` selector: a Pane must carry durable
 `MissingRuntime=True/RuntimeUnbound` evidence, and an Agent must be `Offline`
-with no `paneRef` (with every retained descendant Pane also marked
-`MissingRuntime`). The exact routed server must answer with a non-empty socket
-identity and a non-empty Pane inventory that proves the target has zero mirrors.
+or `Failed` with no `paneRef` (with every retained descendant Pane also marked
+`MissingRuntime`). Both phases are accepted under the same authority; the
+reported evidence names the phase, such as `Failed` or
+`Offline+MissingRuntime`. The exact routed server must answer with a non-empty
+socket identity and a non-empty Pane inventory that proves the target has zero
+mirrors.
 A missing server, empty or failed inventory, unavailable or permission-denied
 transport, implicit/name/scope/`--all` selection, and duplicate or foreign
 mirrors are not absence authority and make zero writes. Dry-run and apply sign
@@ -799,7 +894,7 @@ typed resource's exact form to run instead —
 `projmux delete pane|agent uid:<uid> --socket-path <server> --dry-run`, then the
 same command with `--yes` — and says which evidence qualifies it. A target the
 `uid:` form would refuse too, such as a Pane without `MissingRuntime` or a
-`Running` or `Failed` Agent, gets no such pointer.
+`Running` Agent, gets no such pointer.
 
 `delete window|pane|agent` names the server its live half addresses the same
 way `reconcile resources` does: `--socket <name>`, `--socket-path <absolute>`,
@@ -982,7 +1077,7 @@ hook payload, or a `make install` log.
 
 | Route | Purpose |
 | --- | --- |
-| `internal tmux` | Generated config render/install/apply, popup entry helpers, pane rebalance/rename, snapshot autosave. |
+| `internal tmux` | Generated config render/install/apply, popup entry helpers, pane rebalance/rename, and the retained no-op `autosave-session-state`. |
 | `internal status` | Status bar segment renderers (`git`, `project`, `usage`, `notify`, `resources`). |
 | `internal statusbar` | Status bar click and shortcut dispatch (`click`, `usage-refresh`). |
 | `internal preview` | Persisted preview cursor (`cycle-pane`, `cycle-window`, `select`). |
@@ -1078,31 +1173,21 @@ shows every key arriving, skip terminal remediation.
 ## doctor
 
 ```
-projmux doctor [--json] [--section deps|runtime|integrations|session-state|logs] [--verbose]
+projmux doctor [--json] [--section deps|runtime|integrations|logs] [--verbose]
 ```
 
 Runs read-only diagnostics, including a dependency check for `tmux ≥ 3.4`,
 `git`, and `stty` (POSIX only), then reports read-only AI notify integration diagnostics
-for Codex hooks, Claude Code hooks, Antigravity hooks/statusline, and the tmux bell
+for Codex hooks, Claude Code hooks, Antigravity hooks, and the tmux bell
 fallback. AI notify integration statuses are `installed`, `missing`, or
 `conflict`; missing or conflicting integrations are informational and do not
-make doctor fail. It also reports read-only Session State resume metadata
-diagnostics for saved agent panes, including `available`, `stale`, or
-`unavailable` status plus confidence, source, updated-at, and the affected
-snapshot/window/pane.
-
-Session State preview and doctor report the resume source captured on the pane.
-Live `hook`/`session-id` metadata is high confidence; DB-validated Antigravity
-`antigravity-last-conversation` and `antigravity-conversation-metadata` picker
-sources are medium confidence; legacy `antigravity-history` is low confidence.
-Disk discovery never lowers or overwrites an already captured live source.
+make doctor fail.
 
 The default text report shows per-section summaries plus failing or warning
 items. `--verbose` adds successful checks and complete typed detail, including
 versions, paths, confidence/source metadata, and displayed remediation.
 `--section` projects the same inventory used by text and JSON: `deps` selects
-dependencies, `integrations` selects AI notify integrations, and
-`session-state` selects resume metadata plus retention guidance. `runtime`
+dependencies, and `integrations` selects AI notify integrations. `runtime`
 selects the fixed `tmux` backend, an actual one-second read-only probe of the
 app socket, generated-versus-live config digest state, and a
 `projmux_process_vintage` census of this executable's live children by role and
@@ -1126,8 +1211,7 @@ bits are authoritative on both, so a readable path always resolves to a
 private or insecure classification. Doctor never changes permissions.
 
 JSON reports have integer `schema_version: 2`. An unfiltered report retains the
-existing typed `dependencies`, `ai_notify_integrations`,
-`session_state_resume`, and `session_state_prune` detail and adds ordered
+existing typed `dependencies` and `ai_notify_integrations` detail and adds ordered
 `runtime` and `logs` finding arrays. Every finding has closed `severity`,
 stable `code`, and closed `remediation`; bounded aggregates may add `count`
 and `safe_codes`. A filtered report contains only the selected typed field(s).
@@ -1150,8 +1234,9 @@ diagnose terminal key delivery; use `projmux setup` for that.
 
 JSON migration: consumers must switch on `schema_version` before decoding.
 Version 2 changes the previously empty/reserved `runtime` and `logs` arrays to
-the typed finding shape above; field meanings inside the version 1 dependency,
-integration, and Session State inventories are unchanged. Consumers that only
+the typed finding shape above; field meanings inside the version 1 dependency
+and integration inventories are unchanged. The former `session_state_resume`
+and `session_state_prune` fields are no longer emitted. Consumers that only
 understand version 1 must reject version 2 rather than decoding the new arrays
 as the old empty placeholder shape.
 
@@ -1275,7 +1360,7 @@ before anything is materialized.
 declares exactly one runtime outcome, and reporting `runtime=stopped` for a
 session that was never running would be false. `unregister project` is the
 inverse -- it removes the Registry graph and deliberately leaves the running
-session, the root, Git/worktrees, and snapshots exactly as they were.
+session, the root, and Git/worktrees exactly as they were.
 
 `delete project` is a deprecated alias of `unregister project`. It keeps its
 exact behavior and its exact stdout; it adds one deprecation line on stderr and
@@ -1285,6 +1370,15 @@ removal in this release.
 The reference for a Project can be `uid:<uid>`, a bare `metadata.name`, or the
 absolute root path the Project claims.
 
+A Project registered without `--name` -- by `create project`, by opening an
+unregistered directory, or by `Clear layout and open` -- is named after its root
+directory, sanitized into a valid name (`~/src/my repo` becomes `my-repo`). If
+that basename sanitizes to nothing or another Project already holds it, the new
+Project is named by its exact uid instead; a numbered variant is never invented.
+`Clear layout and open` keeps an operator-chosen name, but not a name shaped
+like a Project uid. Windows, Panes, and Agents keep their exact-uid automatic
+names.
+
 ### Operation receipts
 
 Every create, rename, delete, and Project lifecycle route reports what it did
@@ -1420,7 +1514,7 @@ Authoritative AI account usage. See [usage-tracking.md](usage-tracking.md)
 for adapter detail.
 
 ```
-projmux agent usage [--model codex|claude|antigravity|all] [--window 5h|weekly|context|quota|all]
+projmux agent usage [--model codex|claude|all] [--window 5h|weekly|context|quota|all]
                     [--json] [--force|-f]
 ```
 
@@ -1478,7 +1572,7 @@ Defensive ambiguous attribution stays in its stable internal bucket, is
 included in Attributed totals, and appears only as a bounded CPU/RSS/pane
 diagnostic rather than a project row. Warming, partial, unavailable, unknown,
 and overage states also remain explicit. No process
-command list, mutation, history, graph, daemon, persistence, or Session State
+command list, mutation, history, graph, daemon, or persistence
 telemetry is created. Linux/tmux provides attribution; unsupported platforms
 show an unavailable reason rather than zero metrics.
 
@@ -1511,9 +1605,8 @@ projmux internal status resources
   local changes, `+N` staged entries, and `↑N`/`↓N` ahead/behind counts, with
   compact per-token colors in tmux output.
 - `usage` — HUD-style provider blocks containing only official `5h` and
-  `weekly` windows. Antigravity's exact `quota/gemini-weekly` snapshot is
-  projected as `weekly` without changing its cached identity; other named
-  quotas and context never consume status width. Claude typed `limits[]`
+  `weekly` windows from Claude and Codex; named quotas and context never
+  consume status width. Claude typed `limits[]`
   named/model rows are likewise excluded, so only its aggregate `5h` and
   `weekly` rows reach the status line. Narrow tiers keep one primary window per
   provider (`5h`, otherwise `weekly`) before hard truncation.
@@ -1605,7 +1698,7 @@ projmux agent capabilities [<agent-ref> | --provider <codex|claude|antigravity>]
 projmux internal agent-hook watch-title [pane]
 projmux internal agent-hook ingest codex-hook [--pane <pane_uid|pane_id>] < payload.json
 projmux internal agent-hook ingest claude-hook [--pane <pane_uid|pane_id>] < payload.json
-projmux internal agent-hook ingest antigravity-hook [--event <PreInvocation|PostInvocation|PostToolUse|Stop|Statusline>] [--pane <pane_uid|pane_id>] < payload.json
+projmux internal agent-hook ingest antigravity-hook [--event <PreInvocation|PostInvocation|PostToolUse|Stop>] [--pane <pane_uid|pane_id>] < payload.json
 projmux internal agent-hook ingest bell --pane <pane_id>
 projmux diagnostics agent-hook [--tail N] [--json] [--path]
 projmux agent integrate codex [--dry-run] [--remove]
@@ -1668,6 +1761,120 @@ plain Agent on purpose; it is Codex-only and equivalent on `create agent
 multi-operand payloads, `agent resume`, Claude, and Antigravity are unaffected.
 See [Codex Native-Required Create Migration](codex-native-required-migration.md).
 
+An Agent can be given a persona: `create agent --provider claude
+--persona <name>` (and `create claude --persona <name>`) appends the stored
+persona to the new session's system prompt through Claude's
+`--append-system-prompt-file`; it never replaces the system prompt, so Claude
+Code's own tool instructions stay. Personas are files in
+`<config dir>/personas/<name>.md` (by default `~/.config/projmux/personas/`),
+at most 64 KiB each, managed with `projmux persona list|show|edit|set|delete`
+(`edit` opens `$EDITOR`, then `$VISUAL`; `set <name> --file <path>` or `-` is
+the non-interactive write). A persona's content is fixed when it is given: the create
+copies the content to a content-addressed snapshot
+`<state dir>/personas/sha256-<hex>.md`, passes only that path on the Claude
+command line, and records `projmux.io/persona` and `projmux.io/persona-digest`
+on the Agent. `agent resume` and Continue/topology replay pass that same
+snapshot again, found from the recorded digest and never from the persona file,
+so editing or deleting the persona file later never changes an existing Agent.
+If the snapshot is gone, the resume still proceeds without the persona and
+discloses one `persona-unavailable` line (on stderr for `agent resume`, among
+the replay notices for Continue). A missing, oversized, or badly named persona
+refuses with `persona-not-found`, `persona-too-large`, or
+`persona-name-invalid`, all with zero Registry, tmux, and snapshot writes.
+
+A Codex Agent can be given a persona too, on one lane: a create that carries a
+prompt (`create agent --provider codex --persona <name> -- <prompt>`, and
+`create codex --persona <name> -- <prompt>`). That is the lane that opens a
+thread of its own, and starting the thread is the only moment Codex accepts a
+persona: the create sends the snapshot content as the thread's
+`developerInstructions`, and the shared app server records it once as the
+thread's `developer` message. The content goes over that connection and
+nowhere else -- never onto a command line, where `ps` would publish it -- and
+the create records the same `projmux.io/persona` and `projmux.io/persona-digest`
+annotations Claude records. From then on the thread carries the persona
+itself: `agent resume`, Continue/topology replay, and a resume picked from the
+Codex catalog re-send nothing and disclose nothing, because nothing was lost.
+A conversation opened from the resume picker inherits the two persona keys
+from the Agents that already record it, so the new Agent reports the persona
+its thread is running; it inherits no other launch value. A Codex Agent's
+persona cannot be changed afterwards: the instructions are fixed when the
+thread starts, `agent persona attach|detach` stays Claude-only, and starting
+over means a new Agent.
+
+Every other `--persona` create refuses with `persona-provider-unsupported` and
+zero Registry, tmux, and snapshot writes: a Codex create with no prompt or with
+`--interactive-only` (its plain lane would have to spell the persona into
+argv), `--dialogue-reply-only`, and any other provider.
+
+An existing Claude Agent can take on a persona later, or drop it:
+`projmux agent persona attach <agent-ref> <persona>` and
+`projmux agent persona detach <agent-ref>` (both with `[--project <ref>]
+[--window <ref>] [--yes] [--dry-run] [-o json]`). The Agent keeps its uid and
+its provider conversation. A Running Agent's managed Pane is closed through
+`delete pane`, which leaves it Offline, and the Agent is resumed through the
+same rebind `agent resume` uses, on a new managed Pane; an Offline or Failed
+Agent is only resumed. Before that the command writes the snapshot and records
+`projmux.io/persona`, `projmux.io/persona-digest`, and
+`projmux.io/system-prompt-snapshot=off` in one Registry change (detach removes
+the first two). The last key is sticky and makes every later resume of that
+Agent pass `--system-prompt-snapshot off`: Claude records the system prompt of
+a conversation's first request and replays that record on resume, so without
+it a persona attached after the conversation started would be ignored on the
+next resume. In steady state that costs little: each resume re-creates a
+byte-identical system prompt, so the prompt cache still hits and the extra cost
+is a few dozen cache-creation tokens per resume (measured +4 to +45); after the
+environment context in the system prompt changes (date, git state, CLAUDE.md),
+the first resume can re-cache the prompt prefix once. A Running Agent whose
+interaction is not `idle` or
+`response_complete` -- `unknown` included -- is refused with
+`persona-agent-busy` unless `--yes` confirms cutting its turn, and `--dry-run`
+(`-o json` for scripts) reports the target, its interaction, the current and
+new persona, and whether that confirmation is required without changing
+anything. The Agent owning the Pane the command runs in is refused with
+`persona-self-target`; an Agent with no stored conversation is refused with
+`persona-no-conversation`. Attaching the persona an Agent already runs with,
+same name and same content digest, reports `unchanged` and restarts nothing;
+after the persona file is edited the digest differs and the attach restarts
+with the new snapshot. Outside tmux the stop needs `--socket <name>` or
+`--socket-path <absolute>`, exactly as `delete pane` does. Refusals leave no
+snapshot, Registry, or Pane change. If the resume fails after the stop, the
+Agent stays Offline with its new annotations and stderr prints the
+`projmux agent resume uid:<agent> --project uid:<project> --window uid:<window>`
+command that finishes the job with the persona. If closing the managed Pane
+reports an error, the command checks whether that Pane is still alive: if it
+is, the previous annotations are restored; if it is already closed, the new
+annotations are kept and the resume proceeds with a warning on stderr (a failed
+resume prints the recovery command above); if it cannot tell, the previous
+annotations are restored and stderr prints the command to re-run.
+
+A Claude Agent created with `--effort <level>` records it as `projmux.io/effort`
+on the Agent, because Claude does not restore a conversation's effort on
+resume. Every resume passes it again as `--effort <level>`: `agent resume`,
+Continue/topology replay, and the restart of `agent persona attach|detach`. A
+recorded value that is not one of `low`, `medium`, `high`, `xhigh`, or `max` is
+skipped, the resume still proceeds, and one `effort-invalid` line is disclosed
+where a `persona-unavailable` line would be. The model given with `--model` is
+not recorded or passed again: Claude restores the conversation's model itself
+on resume, and passing the create-time model would override a `/model` switch
+made in the session.
+
+A Claude conversation opened from the resume picker creates a new Agent, and
+when Agents in the Registry already record that conversation (in any Project or
+Window, live or not) the new Agent inherits their launch values: the persona
+and its snapshot (`projmux.io/persona`, `projmux.io/persona-digest`), the
+system prompt snapshot mode (`projmux.io/system-prompt-snapshot`), and the
+effort (`projmux.io/effort`). It launches with them and records them, so its own
+later resumes behave like theirs; a snapshot that is gone or an effort Claude
+would not take is disclosed with `persona-unavailable` or `effort-invalid`, as
+on `agent resume`. Inheritance happens only when every such Agent records the
+same values; if they disagree, nothing is inherited and one
+`launch-values-ambiguous` notice names them. The creator, topic, and
+labels of those Agents are never inherited, and they keep their conversation
+and annotations. A Codex picker selection inherits the two persona keys under
+the same agreement rule and nothing else -- the snapshot mode and the effort
+are Claude launch options -- and it changes no argv, because the thread
+already carries the persona. Antigravity picker selections inherit nothing.
+
 Automation callers get the new pane's handle from `-o pane-id` on the canonical
 create routes: `projmux create agent --provider <p> --placement right -o pane-id`
 and `projmux create pane --placement right -o pane-id` each print exactly the
@@ -1713,7 +1920,7 @@ other case reports review as unavailable without changing the Agent. This route
 projects only the initial response into interaction status. It does not claim
 the later notification-driven completion lifecycle.
 
-Live Antigravity hook/session-state resume metadata remains a separate,
+Live Antigravity hook resume metadata remains a separate,
 high-confidence lane; it is not enumerated from disk by the picker. Within the
 picker's disk discovery, source order is the workspace-to-latest-UUID mapping
 in `cache/last_conversations.json`, workspace-bearing summarized rows in
@@ -1727,13 +1934,18 @@ conversation history. Cache rows have medium confidence and blank turns;
 summary. Legacy history is low confidence. Missing/malformed cache, stale
 missing-DB mappings, workspace-less metadata, and unknown fields degrade
 without failing Claude/Codex or legacy discovery.
-Settings > AI Settings > Enabled agents controls Claude/Codex/Antigravity launch
-visibility. Disabled agents are hidden from the selective picker and from the
+`Settings > Global > AI > Enabled providers`, or
+`projmux config providers [--enable <id> | --disable <id>]` through the same
+writer, controls Claude/Codex/Antigravity launch visibility. Disabled
+providers are hidden from the selective picker and from the
 default-mode picker. A saved default that later becomes disabled fails clearly
 instead of falling back to another agent. Direct
 Canonical `create agent --provider <p>` launches and the provider shortcuts also
 fail when disabled. If all AI agents are disabled, the selective picker still offers the
 plain `shell` split and shows guidance to re-enable Claude/Codex/Antigravity.
+While at least one agent is enabled, the selective picker also offers a `resume`
+row between the agents and `shell`; it opens the resume session list in the
+same popup.
 For user-level skill, slash-command, editor, or launcher registrations that
 call this contract, see [AI Agent Shortcuts](ai-agent-shortcuts.md).
 
@@ -1793,22 +2005,21 @@ precedence over catalog `action` for known Claude events too; for example a
 noisy notify event can be made state-only or quiet without changing installed
 Claude hook commands.
 
-`ingest antigravity-hook` is the hook/statusline entrypoint for
+`ingest antigravity-hook` is the hook entrypoint for
 Antigravity CLI `agy` payloads. Official v1.1.12 hook commands must pass their
 event identity explicitly, for example
 `projmux internal agent-hook ingest antigravity-hook --event Stop`; the official stdin payload
 does not carry an event field. The explicit selector is authoritative, while
 payload `eventName` and its legacy aliases remain fallback inputs for existing
 manual wiring. `projmux agent integrate antigravity` manages exactly the named
-`projmux` entry in `~/.gemini/config/hooks.json` and, separately, exactly the
-`statusLine` member in `~/.gemini/antigravity-cli/settings.json`. The managed
-statusline uses the official v1.1.12 `{type:"command", enabled:true,
-stack_with_default:true}` shape and an absolute direct ingest command whose
-stdout is empty, so the built-in statusline remains visible. It preserves every
+`projmux` entry in `~/.gemini/config/hooks.json`. It never creates or writes
+`~/.gemini/antigravity-cli/settings.json` and does not judge its `statusLine`;
+only `--remove` also strips a `statusLine` that an older projmux installed
+(its command carries `projmux-managed:antigravity-statusline:v1`), and
+`projmux config apply` removes that legacy entry on upgrade. It preserves every
 other named entry and unknown JSON value, resolves the running projmux
 executable to a stable absolute path, and supports `--dry-run` and `--remove`.
-An existing unmanaged custom `statusLine` is an actionable conflict and is
-never chained, wrapped, or rewritten. An existing
+An existing
 unmanaged `projmux` entry, another Antigravity projmux ingest command, malformed
 JSON, symlinks, and read/write permission failures are reported without
 rewriting the file. Doctor and Settings also report a managed entry as `stale`
@@ -1819,8 +2030,8 @@ The embedded v1.1.12 catalog contains the five official events `PreToolUse`,
 `PostToolUse`, `PreInvocation`, `PostInvocation`, and `Stop`. The managed entry
 installs `PreInvocation`, `PostInvocation`, `PostToolUse`, and `Stop`, each with
 an explicit `--event`; `PreToolUse` remains disabled because its response can
-change permission policy. `Statusline` remains an explicit statusline selector
-outside that official hook catalog.
+change permission policy. A leftover `--event Statusline` call from an older
+statusLine bridge exits 0 with empty stdout and changes nothing.
 
 `PreInvocation` moves the matched pane to thinking/busy without notifying.
 `PostInvocation` and `PostToolUse` remain quiet bookkeeping paths, with tool
@@ -1828,13 +2039,9 @@ errors retained in ingest diagnostics. `Stop` keeps the completion/error notify
 classification. Hook stdout is `{}` for the three non-Stop managed events and
 `{"decision":"stop"}` for Stop, including a shell fallback if ingest fails, so
 the hook cannot force continuation or synthesize a permission decision.
-Official statusline `agent_state` values `thinking`, `working`, and `tool_use`
-map to thinking/busy unless the pane already holds a terminal completion or
-approval state; this prevents a late statusline refresh from regressing `Stop`.
 A new `PreInvocation` resets the pane to thinking for the next generation.
-`idle` is quiet and does not clear an existing completion or approval state.
-`tool_confirmation_pending=true` produces a stable-ID,
-deduped approval-required row; false never produces a notification.
+Antigravity has no official approval-required or mid-turn busy event, so
+projmux reports neither for Antigravity.
 
 The managed JSON is the install source of truth. The command
 `agy -p '/hooks' --output-format json` is a read-only runtime diagnostic for
@@ -1850,19 +2057,11 @@ unknown reasons remain info completions with diagnostic metadata rather than
 being promoted to critical. Official camelCase fields retained by the parser
 also include `artifactDirectoryPath`, `modelName`, `invocationNum`,
 `initialNumSteps`, `toolCall`, `stepIdx`, `executionNum`, and `fullyIdle`.
-Antigravity notify metadata uses `agent=antigravity`. Phase 3 session-state
-restore is included: Antigravity ingest stores `conversationId` as pane thread
-metadata for matching and as session-state resume metadata. Restore uses
-`agy --conversation <uuid>` when that id is present and UUID-shaped; otherwise
-session-state preview/doctor render `resume unavailable`. Structured statusline
-`context_window.used_percentage` is persisted with its conversation id as
-private hook/notify diagnostic metadata and is not surfaced as account usage.
-The official `quota` map is persisted independently and surfaces each valid entry as
-`quota/<exact bucket ID>` with independently retained absolute and relative
-reset values. Bucket IDs are never mapped to `5h`/`weekly`, and account quota
-is never inferred from the conversation-local gauge.
-The earlier string percentage form remains a compatibility fallback.
-Transcript contents are not read.
+Antigravity notify metadata uses `agent=antigravity`. Antigravity ingest stores
+`conversationId` as pane thread metadata for matching and as Agent resume
+metadata. Resume uses `agy --conversation <uuid>` when that id is present and
+UUID-shaped and is refused otherwise. projmux records no Antigravity usage,
+context, or quota. Transcript contents are not read.
 
 The canonical `internal agent-hook ingest bell --pane <pane_id>` route is the
 narrow tmux-bell fallback ingest path.
@@ -2046,6 +2245,8 @@ projmux internal tmux popup-sessions
 projmux internal tmux popup-preview <session>
 projmux internal tmux rebalance-panes
 projmux internal tmux rename-pane <pane> <label>
+projmux internal tmux window-rename --client <key> --anchor <%pane> (--name-stdin | -- <name>)
+projmux internal tmux pane-rename   --client <key> --anchor <%pane> (--name-stdin | -- <name>)
 projmux internal tmux print-config     [--bin <path>]
 projmux internal tmux print-app-config [--bin <path>]
 projmux internal tmux install     [--bin <path>] [--config <path>] [--include <path>]
@@ -2059,10 +2260,18 @@ accepted by `popup-toggle` mirror the historical sessionizer surface:
 `notify-sidebar`, `recent-windows`, `resource-inspector`, `ai-split-picker-right`,
 `ai-split-picker-down`, `ai-split-resume-right`, `ai-split-resume-down`,
 `ai-split-settings`.
-`rename-pane` sets only the pane-scoped user label
-`@projmux_pane_label`; an empty label clears the option. It does not change the
-raw tmux pane title, AI topic, or AI topic manual-ownership flag. The canonical
-keybinding action id is `rename-pane-label`. The retired `rename-pane-topic`
+`rename-pane` is a label-only helper: it sets only the pane-scoped
+`@projmux_pane_label`, and an empty label clears the option. It does not change
+the Registry Pane name, so the next Continue restores that name, and it does not
+change the raw tmux pane title, AI topic, or AI topic manual-ownership flag. No
+generated binding uses it.
+`window-rename` and `pane-rename` are the generated rename routes behind the
+`rename-window` and `rename-pane-label` keybinding actions and the Window menu
+Rename item. They resolve the anchor Pane to its exact Registry Window or Pane
+and rename it through the same owner as `projmux rename window|pane`, then
+report one line to the client. The generated bindings pass the prompt response
+with `--name-stdin` inside a quoted here-document; see
+[keybindings.md](keybindings.md#rename-keys) for the input rules. The retired `rename-pane-topic`
 keymap action is no longer accepted: replace a stale
 `[bindings.rename-pane-topic]` table with `[bindings.rename-pane-label]`.
 The `projmux agent topic set/clear` commands keep
@@ -2196,7 +2405,7 @@ The live tmux inventory is under `runtime`: `runtime sessions`, `runtime
 attach`, `runtime stop`, `runtime tag`, and `runtime prune`. Project pins use
 `pin project list|add|remove|toggle|clear|migrate`; `list` takes `--kind
 project|candidate` and `migrate` takes `--dry-run`. Resource retention uses `prune
-project|snapshot`, while explicit snapshot deletion uses `delete snapshot`.
+agent|project`.
 
 Popup-marker, preview, status, and tmux configuration plumbing is hidden under
 `internal session-popup`, `internal preview`, `internal status`, `internal
@@ -2209,35 +2418,24 @@ human configuration work should prefer `config render` and `config apply`.
   generated config. The generated app config uses absolute `$SHELL` as the
   tmux default shell when set, otherwise `/bin/sh`. `shell` starts or attaches
   the app session directly after resolving the target app session name and
-  startup directory. With no saved startup preference, Alt-1 sidebar project
-  open defaults to a two-action picker containing exactly `Continue project`
-  and `Recreate Project`; Esc returns to Projects without writing config. Saved `on`
-  keeps that picker, while saved `off` skips it and preserves the existing
-  automatic registered-Continue/unregistered-Fresh decision. `Continue
-  project` restores a deleted Project only from its usable exact snapshot and
-  otherwise refuses with zero Registry writes. `Recreate Project` confirms the
+  startup directory. Alt-1 sidebar open of a registered closed Project shows a
+  two-action picker containing exactly `Continue project` and
+  `Clear layout and open`; Esc returns to Projects without writing config. A
+  root that is not a registered Project skips the picker and opens fresh.
+  `Continue
+  project` on a root that is not a registered Project, including a deleted one,
+  refuses with zero Registry writes and points to `Clear layout and open`. `Clear layout and open` confirms the
   exact old Project UID and its counts, then atomically replaces the Project
   with a new Project/Window/shell UID chain and one same-root claimant. A
   declined confirmation returns to the startup rows and writes nothing.
-  Repeating it allocates another new identity. Neither action modifies snapshot
-  bytes, the project directory, git/worktrees, unrelated roots, or trust state.
-- `quit` — open an action picker with `Save Project snapshots and quit`, `Quit
-  without saving`, and `Cancel`. The safe first action takes one complete,
-  exact-socket Registry/resource-graph observation, freezes every live managed
-  Project session in Project UID/session order, and captures each latest
-  snapshot even when auto-save is off. Home/control, ephemeral, unattributed,
-  recoverable, foreign, and offline sessions are excluded and reported as
-  bounded class counts. Every target is attempted. A failed capture leaves the
-  successful per-session atomic files in place, reports the exact failed
-  session, and does not stop the app; retry captures every target again. Only an
-  all-success ledger reaches the existing physical-socket, app-marker, and
-  logical-route guarded shutdown. Named snapshots and Registry bytes are never
-  written, and the batch is not a multi-file transaction or topology freeze.
-  `Quit without saving` preserves the earlier guarded shutdown behavior:
-  missing servers and runtimes without the app marker are no-ops. Existing
-  non-interactive `--yes` and `--force` callers retain that same snapshot-free
-  behavior and exact shutdown route; the default command always uses the
-  action picker.
+  Repeating it allocates another new identity. Neither action modifies the
+  project directory, git/worktrees, unrelated roots, or trust state.
+- `quit` — open an action picker with `Quit projmux` and `Cancel`. `Quit
+  projmux` runs the physical-socket, app-marker, and logical-route guarded
+  shutdown; missing servers and runtimes without the app marker are no-ops.
+  Quit never saves Project state. Non-interactive `--yes` and
+  `--force` callers use the same shutdown route without the picker; the
+  default command always uses the action picker.
 - `attach project <ref>` — enter a Project runtime from outside tmux.
   Automatic live-runtime attachment is `runtime attach`.
 - `settings` — interactive configuration UI for the project picker, AI