projmux 0.15.3 → 0.16.1

package/docs/cli-guide.md

@@ -20,8 +20,18 @@ Exit codes:
 
 - `0` — success.
 - `1` — runtime failure.
-- `2` — usage error (unknown flag, bad enum, missing required flag) or a
-  deterministic semantic exit (e.g. `focus` cannot resolve the target).
+- `2` — usage error (unknown flag, bad enum, missing required flag, a
+  positional argument the route does not accept, or an unknown or missing
+  subcommand) or a deterministic semantic exit (e.g. `focus` cannot resolve
+  the target).
+- A flag parse failure on a public route (an unknown flag, a missing flag
+  value, or a malformed boolean) prints the reason line first and then the
+  route's `Usage:` block, byte-identical to the one `projmux <route> --help`
+  prints, on stderr; stdout stays empty and the exit code is `2`. The Go flag
+  package's own `Usage of <route>:` flag listing is never printed.
+- The hidden `projmux internal …` plumbing is outside this table: it follows
+  its caller's contract (generated tmux config, provider hooks, supervisors),
+  so a flag error there keeps its existing exit code and output.
 
 ## Help boundary
 
@@ -48,8 +58,12 @@ with it keeps one notion of help; the boundary never interprets a flag value:
   unchanged.
 - An unknown command keeps its `unknown command: <token>` error and exit `1`
   even with `--help`, and `projmux help` / bare `projmux` keep printing the
-  top-level list. A bare `help` word nested under a command
-  (`projmux pin help`) still reaches that command's own handler.
+  top-level list.
+- On a command that has sub-commands, a bare `help` word right after it (before
+  any `--`) prints that command's help, whatever follows it: `projmux agent help`
+  and `projmux agent help instructions` both print `projmux agent --help`. A
+  command without sub-commands receives `help` as an ordinary argument, and a
+  `help` after `--` is payload.
 - Because a help invocation runs no handler, it is never recorded as a state
   change in the operations journal, at any depth — `projmux agent topic set --help`
   logs neither an error nor a state-changing success.
@@ -97,8 +111,24 @@ 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.
+STATUS in `get` and `describe` is observed on the tmux server the caller is
+attached to (`$TMUX`). Outside tmux -- another terminal, an IDE, a script --
+they observe the app server `-L projmux`, so a live Window reads `live` there
+too; with no app server running, rows read `offline`.
+
+STATUS is one of `live`, `offline`, `unknown`, or `missing-root`. `offline`
+means the server was read and no runtime object mirrors the resource.
+`unknown` means the server could not be read, so the resource was neither seen
+running nor seen absent. An `unknown` row offers only `delete` in ACTIONS -- no
+`start`, `resume`, or `open` -- because starting something that may already be
+running is not safe. A Project's STATUS and ACTIONS both come from the same
+observation of its session, not from the stored session projection. `-o json`
+is unchanged: it carries no STATUS, and `context.observed` still reports
+whether the context was observed.
+
+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,
@@ -148,9 +178,12 @@ The contract:
   partially specified selector. The active *Project* is a separate rule and does
   apply to a reference -- see [Reference scope](#reference-scope-the-active-project-namespace)
   below.
-- **Only the singular routes and `create`.** The plural reads (`get
-  projects|windows|panes|agents`) stay 0..N inventories over their whole scope,
-  and `delete` is unchanged. `create` has its own spelling of the same rule --
+- **Only the singular routes, `delete`, and `create`.** The plural reads (`get
+  projects|windows|panes|agents`) stay 0..N inventories over their whole scope.
+  `delete window|pane|agent` with neither a selector nor `--all` targets the
+  active Window, Pane, or Agent and asks before removing it -- see
+  [Delete confirmation](#delete-confirmation); `--all` still means every one in
+  the registry. `create` has its own spelling of the same rule --
   see [Create scope](#create-scope) -- because a create resolves a scope to put
   something *into* rather than a target to act *on*.
 - **Inside tmux is decided by `$TMUX_PANE` plus `$TMUX`**, not by whether a tmux
@@ -171,6 +204,28 @@ and `@projmux_window_uid` on its window — and derives every ancestor from
 registry `ownerRef`. The session-scoped `@projmux_project_uid` is deliberately
 not consulted.
 
+### Delete confirmation
+
+`delete window|pane|agent` and `unregister project` ask before they remove
+anything, with one exception: a `delete pane` whose selector resolves to
+exactly one Pane deletes it without asking. The selector is anything the
+operator typed -- a positional `<ref>`, a `--project`/`-p`,
+`--window`/`-w`, or `--pane` scope, or a `--selector` label. The argv already
+names the one resource that goes away, and a Pane is a leaf: it cascades to
+nothing, an Agent that owned it stays as an Offline resource, and deleting a
+Window's last Pane starts a replacement shell first, so the Window and its
+session stay.
+
+Everything else asks: `delete pane` with no selector (the active Pane inside
+tmux), `--all`, a selector that matches several Panes, and every `delete
+window`, `delete agent`, and `unregister project`. Asking means `--yes`
+proceeds; without it, a terminal prompts and a declined answer exits `2`, and
+a caller with no terminal is refused with exit `2` and a `needs confirmation`
+message. Either way the answer is settled before anything is deleted.
+`--dry-run` prints the full target and cascade plan and deletes nothing, with
+or without `--yes`. To preview a single named Pane, pass `--dry-run`: without
+it the Pane is already gone.
+
 ### Plural read scope: the active managed root
 
 Inside tmux, selector-omitted `get windows|panes|agents` derives one exact
@@ -201,7 +256,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
@@ -361,12 +416,19 @@ 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. 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; public `create` stays detached. A natural create validates
+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`
@@ -472,6 +534,54 @@ 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.
+
+Because nothing constrains the characters of a key or value, the human-readable
+lines that print a metadata map quote the ones that would break them. The
+`label` result line and the `Labels:` and `Annotations:` rows of `describe`
+spell each pair as `key=value` on one line, and a key or value renders in Go
+`strconv.Quote` form when it holds a character `strconv.IsPrint` rejects (a
+newline, tab, CR, ESC, or other control or format character; the ASCII space
+is printable), is not valid UTF-8, or starts with `"`. So a value written as
+`$'line1\nline2'` prints as `k="line1\nline2"`, and a key written as
+`$'bad\nkey'` prints as `"bad\nkey"=v`. Every other key and value, including
+printable non-ASCII text, prints exactly as stored. Quoting is display only:
+the stored value, `--selector`, and `-o json` keep the original bytes.
+
+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
@@ -486,6 +596,15 @@ current Registry-backed `available`, and
 `completionPrecision` are separate fields. Use `-o json` for the stable machine
 projection.
 
+`projmux agent models [--provider claude] [-o json]` lists, in order, the
+Claude model names projmux suggests for `create --model` and a Profile `model`:
+one name per line, or `{"provider","models","acceptsUnlisted":true}` with
+`-o json`. It reads a fixed list without opening the Registry, tmux, a provider
+process, or the network. The list is a suggestion, not an allowlist: any other
+well-formed model name is still accepted. `--provider codex` (or any other
+provider projmux does not apply a model to) is a usage error rather than an
+empty list.
+
 The closed static modes are `generic-registry`, `provider-resume`,
 `native-exact-control`, `provider-hook`, `read-only-adapter`, and
 `unsupported`. `message.send`, `message.status`, and `wait.idle` are provider-neutral commands whose availability is decided from
@@ -513,6 +632,20 @@ correlated model reply is a separate envelope with the original
 self-claims that envelope. Message lifecycle updates neither Agent interaction
 state nor tmux badges.
 
+`--source` names the source Agent; it does not prove the caller is that Agent.
+When the source is a Claude Agent with a registered Claude process and the
+sending process does not descend from that process, the send still proceeds
+exactly as before (same receipt, delivery, and exit status), but it prints one
+`agent message send: warning:` line on stderr naming the source Agent UID, its
+registered Claude session, the caller pid, and `CLAUDE_CODE_SESSION_ID` when
+set, and records one `agent.message.foreign-source` event readable with
+`projmux diagnostics log --component agent`. It usually means another Claude
+session, such as a `claude --resume` in another terminal or a background
+session left by `/exit` "Move to background", is sending as that Agent: end
+that session, or send from the registered one. Nothing is judged when the
+process lineage cannot be read, and a Claude `--reply-to` is already refused
+for such a caller.
+
 Claude messaging is opt-in through `projmux agent integrate claude`. The
 integration installs no receiver waiter or `asyncRewake`; ingress is immediate
 through the exact registered provider socket. Capability JSON keeps Claude
@@ -532,8 +665,12 @@ and connection epoch still match exactly. `start` sends only the exact thread
 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
+once, and so does a fresh system-error thread (left by a provider error) whose
+latest turn is not in progress. An unavailable or inconsistent snapshot returns
+`turn-state-unavailable` with no turn mutation; its line says the read failed,
+returned a different thread, or names the observed thread and turn state
+(for example `thread=system-error turn=in-progress`). 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
@@ -546,6 +683,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
@@ -558,6 +701,39 @@ identity mismatch produces no provider write. Approval queue rows advertise
 advertise the exact-Agent `Open Codex` focus fallback; resolution removes the
 row. Neither route stores prompt, command, path, permission, or request content.
 
+`agent approval list` and `agent approval answer` read and settle the same
+pending Codex approvals without a picker, over the same exact binding:
+
+```sh
+projmux agent approval list <agent-ref> [-o json]
+projmux agent approval answer <agent-ref> <request-id> --allow|--deny [--via popup|cli|<client>]
+```
+
+`list` works whatever `agent-approval-answering` says and prints it. Each
+request shows its normalized id, `waiting`, the approval kind as `toolName`
+(`command`, `file-change`, `permissions`), its full details as `toolInput`,
+which of `allow` and `deny` `answer` can send (`answers`), and what `--deny`
+would send (`denyDecision`; in text `deny(decline: the turn continues)` or
+`deny(cancel: the turn stops)`). A request whose id is ambiguous across raw
+JSON-RPC ids, or that offers neither, is marked for `agent approval review`.
+`answer` needs `projmux config agent-approvals --answering projmux` (otherwise
+`permission-answering-off`, with no broker call). It sends exactly one
+decision: `accept` for `--allow`, never a widened grant or exec-policy
+amendment; for `--deny`, `decline` when the request offers it, so the turn
+continues, and otherwise `cancel`, which also interrupts the turn. Real Codex
+command approvals may offer `accept` and `cancel` without `decline`, so a deny
+there stops the turn. Nothing runs either way. A request offering no fitting
+decision (a permission grant for both flags, or `--allow` on a file change with
+a root grant) is refused as `permission-decision-unavailable`, and an unknown
+or ambiguous id as `permission-not-pending`. The result line names the
+decision sent, for example `7 denied for agent/codex (decision cancel; the turn
+stops)`. `review` keeps the picker, the grant decision, and `Open Codex`. The Codex TUI, `review`, and `answer`
+all stay usable, and the first answer wins: a later one is refused by the
+provider or finds the request gone. Before sending, `answer` appends an
+`allowed` or `denied` line to the agent approval audit log (see
+[hooks.md](hooks.md#answering-claude-permission-requests-in-projmux)); if that
+line cannot be written nothing is sent.
+
 `agent topic get|set|clear` and `agent status get|set` resolve exactly one
 Agent, either from an explicit Agent reference or from the Agent-owned active
 managed Pane. Topic is a non-identifying Registry annotation. Interaction is a
@@ -596,7 +772,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
@@ -646,19 +822,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
@@ -764,17 +952,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
@@ -782,7 +969,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
@@ -810,9 +997,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
@@ -829,7 +1019,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>`,
@@ -896,7 +1086,7 @@ the server, and no write verb is ever sent.
 ## runtime diagnostics
 
 ```text
-projmux runtime diagnostics [--socket <name> | --socket-path <absolute>] [--ui=popup|sidebar]
+projmux runtime diagnostics [--socket <name> | --socket-path <absolute>] [--ui popup|sidebar]
 ```
 
 The interactive half of the same read. It lists every tmux object on the exact
@@ -1012,7 +1202,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`). |
@@ -1050,10 +1240,17 @@ operator's question, so they stay reachable only as `projmux internal tmux ...`.
 ## switch
 
 ```
-projmux switch [--ui=popup|sidebar]
+projmux switch [--ui popup|sidebar] [--anchor <pane>]
 projmux switch open <path>
-projmux switch toggle-tag | toggle-pin | kill | settings | preview
-projmux switch cycle-pane | cycle-window | sidebar-focus
+projmux switch toggle-tag [path]
+projmux switch toggle-pin [path]
+projmux switch kill [path]
+projmux switch preview [--ui popup|sidebar] [path]
+projmux switch settings
+projmux switch cycle-pane <path> <next|prev>
+projmux switch cycle-window <path> <next|prev>
+projmux switch sidebar-focus <path>
+projmux switch sidebar-open --path <path> --anchor <pane> [--session <name>] [--mode <mode>] [--query <text>] [--client <client>]
 ```
 
 Project picker. With no positional argument, opens the configured picker popup
@@ -1108,31 +1305,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
@@ -1156,8 +1343,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).
@@ -1180,8 +1366,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.
 
@@ -1197,7 +1384,7 @@ than a standalone Settings row.
 
 ```
 projmux diagnostics log [--tail N] [--json]
-                        [--level info|error] [--component NAME] [--path]
+                        [--level info|warn|error] [--component NAME] [--path]
 projmux diagnostics report [--output <path>]
 ```
 
@@ -1290,22 +1477,22 @@ which of them a command had touched.
 | `create project` | creates or reuses the Project, its canonical Window, and its shell | not started | not moved |
 | `start project` | unchanged | materialized when offline | not moved |
 | `open project` | unchanged | materialized when offline | moved to the Project |
-| `attach project` | unchanged | materialized when offline | the outside caller attaches |
+| `attach project` | unchanged; an absolute root no Project claims is registered as a new Project | materialized when offline | the outside caller attaches |
 | `focus project` | unchanged | never materialized | moved to the Project |
 | `stop project` | unchanged | the exact session ends | existing safe fallback |
 | `unregister project` | the Project subtree is removed | **preserved** | not moved |
 
 `open project` and `attach project` are the same operation seen from the two
 sides of a tmux client. Inside tmux, `open` moves the client you are in and
-`attach` refuses with a pointer at `open`; outside tmux, `attach` attaches the
-caller and `open` refuses with a pointer at `attach`. Both refusals happen
-before anything is materialized.
+`attach` refuses with a pointer at `focus project`; outside tmux, `attach`
+attaches the caller and `open` refuses with a pointer at `attach`. Both
+refusals happen before anything is materialized.
 
 `stop project` refuses an offline target rather than succeeding silently: it
 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
@@ -1313,7 +1500,22 @@ one `compatibilityWarnings` entry in the receipt. It is not scheduled for
 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.
+absolute root path the Project claims. `start`, `open`, `attach`, and `stop
+project` resolve these forms with one resolver, and a `uid:` or name that
+matches no Project is refused with exit 2 before anything is written or
+started. `attach project` also accepts an
+absolute path no Project claims yet: it registers that root as a new Project
+and then attaches, where `open project` refuses the same path and points at
+`projmux create project --root`.
+
+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
 
@@ -1407,8 +1609,8 @@ projmux notification reconcile [--json]
   `get notifications` and is considered only by reconcile together with a gone
   target. Reconcile also retains only the newest 256 rows. `--text` is hard-capped to 80 runes (longer text is
   truncated server-side). After a successful queue write, projmux sends a
-  best-effort refresh event to open native notify sidebars and fires
-  declarative `[hooks.send-noti]` asynchronously if configured. Event delivery
+  best-effort refresh event to open native notify sidebars and, if configured,
+  runs declarative `[hooks.send-noti]` and waits until it exits or its timeout. Event delivery
   failure does not fail the queue write; reopening the sidebar still shows the
   latest queue. The hook gets a JSON payload on stdin plus
   `PROJMUX_NOTIFY_*` env vars, and it does not replace the normal desktop
@@ -1450,7 +1652,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]
 ```
 
@@ -1508,7 +1710,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.
 
@@ -1541,9 +1743,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.
@@ -1566,19 +1767,21 @@ projmux internal status resources
 ## internal statusbar
 
 ```
-projmux internal statusbar click <range-id> [--socket <s>] [--mouse-window <id>]
-                                            [--client <tty>] [--mouse-x N] [--mouse-y N]
+projmux internal statusbar click <range-id> [--socket <s>] [--client <tty>]
+                                            [--mouse-x N] [--mouse-y N]
 projmux internal statusbar usage-refresh
 ```
 
 Click/keyboard dispatcher for the two-line status bar. Implemented range ids:
-`session pwd git resources usage notify settings`. The bare `window` /
-`window|<idx>` token (tmux's built-in window-list range) and the empty
-range fall through to `select-window -t @<mouse_window>` so the native
-click-to-switch tab affordance is preserved on row 1. Unknown range ids are
-non-specialized placeholders and no-op. `session` opens the existing-session
-popup; `pwd` shows the current pane path in a native-framed display-only
-popup; `git` opens the project switcher popup;
+`session pwd git resources usage notify settings`. Window-list clicks on
+row 1 are handled natively by the binding (`if-shell -F` on the bare `window`
+range runs `select-window -t =`); if a `window|<idx>` token reaches the
+dispatcher it selects `:<idx>`, and a bare `window` token is a no-op. The
+empty range and unknown range ids are no-ops. The binding passes only
+`#{mouse_status_range}` and `#{client_tty}`; `--mouse-window <v>` is accepted
+for compatibility with bindings from older releases and ignored. `session`
+opens the existing-session popup; `pwd` shows the current pane path in a
+native-framed display-only popup; `git` opens the project switcher popup;
 `settings` toggles the settings popup for the tmux client; `usage` opens the
 detailed cached account-usage popup. Legacy context rows are suppressed and
 named quotas retain exact identity/reset/freshness values. Claude model-scoped
@@ -1601,7 +1804,7 @@ projmux attention toggle [pane]
 projmux attention clear  [pane]
 projmux attention arm    [pane]
 projmux attention list   [--json] [--all]
-projmux attention window [window]
+projmux attention window [window] [style]
 ```
 
 Toggles the `✳` pane title prefix and the `@projmux_attention_state` pane
@@ -1632,10 +1835,11 @@ projmux agent status [get [<agent-ref>] | set <unknown|idle|in_progress|approval
 projmux agent topic get|clear [<agent-ref>] [--agent <ref>]
 projmux agent topic set <text> [<agent-ref>] [--agent <ref>]
 projmux agent capabilities [<agent-ref> | --provider <codex|claude|antigravity>] [-o json]
+projmux agent models [--provider claude] [-o json]
 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]
@@ -1698,6 +1902,511 @@ 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 named instructions: `create agent --provider claude
+--instructions <name>` (and `create claude --instructions <name>`) appends the
+stored content 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. Manage the files with `projmux instructions
+list|show|edit|set|delete` (`edit` opens `$EDITOR`, then `$VISUAL`; `set
+<name> --file <path>` or `-` writes without an editor). The files are
+`<config dir>/personas/<name>.md` (by default
+`${XDG_CONFIG_HOME:-$HOME/.config}/projmux/personas/`), with a 64 KiB limit.
+The directory keeps its older name; no `instructions/` directory is created.
+The older command and flag names are listed under
+[Deprecated instruction spellings](#deprecated-instruction-spellings).
+`delete` refuses, with exit 2
+and `profile-instructions-in-use`, instructions that a stored
+[profile](configuration.md#agent-profiles) names -- valid or not -- lists
+each such profile, and deletes nothing; change or delete those profiles
+first. Instructions no profile names delete as before.
+
+The content is copied when an Agent starts: create copies it to the existing
+content-addressed snapshot `<state dir>/personas/sha256-<hex>.md`, passes only
+that path on the Claude command line, and records the existing
+`projmux.io/persona` and `projmux.io/persona-digest` keys on the Agent; the
+keys, too, keep their older name. `agent resume`,
+`agent relaunch`, Continue/topology replay, and a resume-picker create compare
+the current content of the instructions the Agent's
+[settings layers](#settings-layers) name with the recorded digest: when the
+file was edited, or the layers name other instructions, they pass a snapshot
+of the current content, record its digest and
+`projmux.io/system-prompt-snapshot=off`, and the Claude launch passes
+`--system-prompt-snapshot off`; when nothing changed they pass the recorded
+snapshot again. Instructions that cannot be read now keep the recorded
+snapshot, with one `persona-unavailable` line (on stderr for `agent resume`,
+among the replay notices for Continue; a resume-picker create, which already
+discloses what of the inherited snapshot it cannot re-pass, adds no line).
+An Agent with the old keys and snapshot resumes
+without migration. If the snapshot is gone, resume proceeds without the
+instructions and discloses one `persona-unavailable` line (on stderr for
+`agent resume`, among the replay notices for Continue). Missing, oversized,
+or badly named files refuse with the stable `persona-not-found`,
+`persona-too-large`, or `persona-name-invalid` reason and write no Registry,
+tmux, or snapshot state.
+
+A Codex Agent can be given named instructions directly or through a Profile
+when created with a prompt
+(`create agent --provider codex --instructions <name> -- <prompt>`, or
+`create codex --instructions <name> -- <prompt>`). This lane opens a thread of
+its own. Codex accepts the instructions when that thread starts: 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 instructions: `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 stored
+instruction keys from Agents that already record it, so the new Agent reports
+the instructions its thread is running; it inherits no other launch value. A
+Codex Agent's instructions cannot be changed afterwards: the instructions are fixed when the
+thread starts. `agent relaunch` refuses a change of them with
+`codex-instructions-immutable` before writing a snapshot or Registry state or
+stopping a Pane. Codex resume replays the original developer message, even
+when a new instruction is supplied to its CLI or app server. Start a new Agent
+with a prompt to use different instructions.
+
+Every other `--instructions` 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
+cannot carry private developer instructions without exposing their body in
+the process arguments), `--dialogue-reply-only`, and any other provider. The
+refusal tells the operator to create a new Agent with `-- <prompt>` and omit
+`--interactive-only`.
+
+An existing Claude Agent's named instructions are changed with
+`projmux agent relaunch <agent-ref> --instructions <name>` and removed with
+`--instructions none`, both described below. A change of instructions after the
+conversation started records `projmux.io/system-prompt-snapshot=off`. The 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
+instructions given 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 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 relaunch`. 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`
+(or filled in by a profile) is recorded as `projmux.io/model`, exactly as it
+was passed, but never 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. The record is the requested model, not
+necessarily the one the provider runs now. A create without `--model` records
+no model.
+
+`projmux agent resume <ref> [--model <model>] [--effort <level>]` resumes an
+Offline or Failed Claude or Codex Agent on the same UID and conversation with
+another model or effort. `--model` is passed on that launch only and recorded
+as `projmux.io/model`; the provider's conversation keeps the model on later
+resumes, which do not pass it again. `--effort` is recorded as
+`projmux.io/effort`, so later plain resumes pass it again. Both are recorded in
+the resume's own transaction, so a resume that fails rolls back and records
+neither. A resume without `--model` leaves a recorded model as it was. Both flags take create's values and refusals: any
+other provider, an invalid model or effort, and `--dialogue-reply-only` are
+refused before anything changes (`nothing was changed`).
+
+`--dialogue-reply-only` on `create agent` or `agent resume` launches a Claude
+Agent into the reply-only activation and records that on the Agent as
+`projmux.io/dialogue-reply-only=on`, in the transaction of that launch. From
+then on every resume of the Agent is the reply-only activation again:
+`agent resume` without the flag, `agent relaunch`, and the restart of
+`agent instructions attach|detach`, whether the Agent is Running or Offline
+with no managed Pane left. Nothing removes the record; an Agent that should
+run without it is a new Agent. Because that launch is fixed, a request it
+cannot carry is refused before anything changes (`nothing was changed`):
+`--profile`, `none` included (`profile-lane-unsupported`); `--instructions`,
+a `--reset` of the instructions, and `agent instructions attach|detach`
+(`persona-provider-unsupported`); and `--model`, `--effort`, or any other
+`--reset` (`reply-only-launch-fixed`), on `agent resume` too. A plain
+`agent relaunch` of a Running reply-only Agent compares only what that launch
+carries -- not the agent guidance or the Project's label link rules -- so it
+reports `unchanged`. An Agent made reply-only before the record existed
+carries none and is resumed as an ordinary Agent unless the flag is given
+again.
+
+`projmux agent relaunch <agent-ref> [--profile <name>|none] [--instructions
+<name>|none] [--model <model>] [--effort <level>] [--reset <item>[,...]|all]
+[--project <ref>] [--window <ref>] [--yes] [--dry-run] [--socket <name> |
+--socket-path <absolute>] [-o json]` restarts one existing Claude or Codex
+Agent on the same UID and the same provider conversation with other settings,
+all in one restart. It is the one way to change an Agent's
+[settings layers](#settings-layers):
+
+- `--profile <name>` switches the Agent to that profile (`none`: to no
+  profile). A switch clears every override: the instructions, model, and
+  effort take the new profile's values (none where it sets none), its
+  permissions apply, and only the overrides given with it (`--instructions`,
+  `--model`, `--effort`) are overrides again. The profile is recorded with
+  `projmux.io/profile-source=relaunch`. Naming the profile the Agent already
+  has is no switch: its overrides stay. This is how an Agent created before
+  profiles, or created without one, gets a profile; a `role` label is read
+  only when an Agent is created, never by a relaunch.
+- `--instructions <name>` overrides the instructions (`none`: explicitly no
+  instructions), `--model` and `--effort` override the model and the effort.
+- `--reset <item>[,...]` removes the override of `instructions`, `model`, or
+  `effort` (`all`: of every item), so the item takes the profile's current
+  value again, or none where the profile sets none or there is no profile. A
+  model left without a value is not passed and its recorded value is removed.
+  Giving an item a value and resetting it in the same command is a usage
+  error.
+
+Without any of them it restarts the Agent with the settings its layers resolve
+to now -- after a profile edit, for example -- and reports `unchanged` when
+they are what the Agent runs already. A Running Agent's managed
+Pane is closed through `delete pane`, and the Agent is brought back through the
+`agent resume` rebind with the overrides (outcome `restarted`, with the new
+Pane in `newPaneUID`); an Offline or Failed Agent is only resumed (outcome
+`resumed`). The new Pane carries the closed Pane's name unless that name was
+its own uid; when the name cannot be carried (another Pane took it), the new
+Pane keeps its automatic name and stderr says why in one `projmux: agent/<name>
+new Pane keeps an automatic name: <reason>` line. An Offline or Failed Agent,
+here and on `agent resume`, carries the name of its old Pane row instead; when
+no such row is left -- `delete pane` removed it -- the new Pane is named
+`<agent-name>-pane`, as `create agent` names it. That name falls back to the
+automatic one the same way: with the same stderr line when another resource
+holds it, and silently when it is too long to be a name. A name given with
+`rename pane` is not remembered once its row is gone. The settings are recorded by the rebind transaction -- the profile,
+`projmux.io/model`, `projmux.io/effort`, the instructions, and their sources --
+so a failed launch records none of them; later plain resumes pass the effort
+again but not the model. Nothing is written before the stop. On a Codex Agent the model and effort ride the
+native resume as `-m <model>` and `-c model_reasoning_effort=<level>`.
+
+The refusals all happen before any Registry, tmux, or Pane change, ending with
+`nothing was changed`: a provider other than Claude or Codex
+(`relaunch-provider-unsupported`); an invalid model or effort (create's
+refusal); an Agent with no stored conversation, one that is not Running,
+Offline, or Failed, or one whose final resume would be refused (a Codex thread
+with no durable endpoint included) (`relaunch-no-conversation`); the Agent
+whose managed Pane the command runs in (`relaunch-self-target`) -- an
+environment inherited from that Pane is not enough on its own, the command must
+be one of that Pane's processes, and when that cannot be determined the refusal
+says so; and a Running Agent whose interaction is not `idle` or
+`response_complete` -- `unknown` included -- without `--yes`
+(`relaunch-agent-busy`). An Agent that records the reply-only activation
+refuses every `--profile`, `--instructions`, `--model`, `--effort`, and
+`--reset` with the reasons given for it above. A change to the layers
+adds its own: a profile that does not exist or that `profile list` marks
+invalid (the store's reason, such as `profile-not-found`) or that names another
+provider (`profile-provider-mismatch`); instructions that cannot be read
+(`persona-not-found`), named or brought by a profile or a reset; on a Codex
+Agent, any change of its instructions -- `--instructions`, a profile with other
+instructions, or a reset of them (`codex-instructions-immutable`: its thread
+keeps the developer message it started with) -- and a profile switch that
+would leave the thread on the old profile's sandbox or approval, because the
+new profile sets none where the old one set one or cannot be read
+(`relaunch-codex-permissions-kept`: a Codex resume can set a sandbox or an
+approval but not remove one). A Codex switch to a profile with the same
+instructions and both permissions, and any model or effort, is allowed.
+Outside tmux the stop needs `--socket <name>` or `--socket-path <absolute>`,
+exactly as `delete pane` does. A Running Agent without `--model` whose
+settings, `--effort` included, resolve to exactly what it was launched with,
+whose agent guidance and Project label link rules are the ones it recorded,
+and whose `--profile`, `--instructions`, or `--reset` changes no recorded value,
+source, or profile, reports `unchanged` and restarts nothing; `--model` always restarts, because the
+recorded model is the last one requested, not necessarily the one the provider
+runs now (a `/model` switch in the session is not observed). `--dry-run` changes nothing and
+reports `would-restart` or `would-resume`.
+
+`-o json` prints exactly one object with `action` (`relaunch`), `dryRun`,
+`outcome` (`unchanged`, `restarted`, `resumed`, `would-restart`, or
+`would-resume`), `agentUID`, `agentName`, `provider`, `phase`, `interaction`,
+`paneUID`, `newPaneUID`, `currentEffort` (the recorded effort),
+`currentModel` (the recorded model, the last one requested), `newEffort`
+(the requested effort; empty when only `--model` is given, and the recorded
+effort carries on), `newModel`, `restart`, `confirmationRequired`,
+`unchanged`, `currentSettings` and `newSettings` (the settings as the Agent
+recorded them and as the relaunch runs them: `profile` with `name`, `digest`,
+and `source`, and `instructions`, `model`, and `effort` each with `value`,
+`source` -- empty when not known -- `profileValue`, and `override`), and
+`relaunchReasons` (why the relaunch would launch something other than what the
+Agent recorded, in this order: `profile-changed`, `instructions-changed`,
+`instructions-content-changed`, `model-changed`, `effort-changed`,
+`guidance-changed` (the current agent guidance digest differs from the
+recorded `projmux.io/agent-guidance-digest`: guidance added, edited, or turned
+off), `link-rules-changed` (the Project's current label link rules digest
+differs from the recorded `projmux.io/project-link-rules-digest`); empty when
+it would not. The last two are Claude only, like the guidance and the rules
+themselves, and change no setting); the empty string fields before
+`currentSettings` are omitted. A switched profile, overridden or reset items,
+and their sources show on the `newSettings` side. Without `-o json` the output
+of the stop and the resume is followed by one result line, which also names
+the profile and the instructions when their names change (`profile=role
+instructions=lead`, `none` for none).
+
+If closing the managed Pane reports an error, the command checks whether that
+Pane is still alive: if it is, the old session keeps running and the command
+fails with the Registry unchanged; if it is already closed, the resume proceeds
+with a warning on stderr; if it cannot tell, stderr prints the same
+`projmux agent relaunch` command to re-run. If the resume fails after the stop,
+the Agent stays Offline with its previous settings and stderr prints the
+`projmux agent resume uid:<agent> --project uid:<project> --window
+uid:<window> --model <model> --effort <level>` command, with the flags that
+were given, that finishes the job; after `--profile`, `--instructions`, or
+`--reset`, which `agent resume` cannot carry, it prints the same
+`projmux agent relaunch` command instead, which only resumes the Offline Agent.
+
+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 named
+instructions and their 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 stored
+instruction 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 instructions. Antigravity picker selections inherit nothing.
+
+### Deprecated instruction spellings
+
+These spellings are no longer in `projmux help`, in any route's help listing or
+synopsis, or in the [CLI reference](cli.md). Each still runs with the stdout,
+`-o json`, exit code, and reason tokens it had and still answers `--help`; it
+adds one line on stderr that names its replacement:
+
+```text
+projmux: persona list is deprecated; use `projmux instructions list` instead.
+```
+
+None is scheduled for removal in this release.
+
+| Deprecated | Use |
+| --- | --- |
+| `projmux persona list\|show\|edit\|set\|delete` | `projmux instructions list\|show\|edit\|set\|delete` |
+| `--persona <name>` on `create agent`, `create claude`, and `create codex` | `--instructions <name>` |
+| `projmux agent instructions attach <agent-ref> <name>`, `projmux agent persona attach <agent-ref> <persona>` | `projmux agent relaunch <agent-ref> --instructions <name>` |
+| `projmux agent instructions detach <agent-ref>`, `projmux agent persona detach <agent-ref>` | `projmux agent relaunch <agent-ref> --instructions none` |
+
+`projmux persona` and `--persona` read and write the same files and record
+the same keys as `projmux instructions` and `--instructions`; their output says
+`persona` where the replacement says `instructions`. A create given both
+`--instructions` and `--persona` is refused.
+
+An attach (`projmux agent instructions attach <agent-ref> <name>`) or a detach
+(`projmux agent instructions detach <agent-ref>`, both with `[--project <ref>]
+[--window <ref>] [--yes] [--dry-run] [-o json]`) is the relaunch in the table
+above, recorded with the source `attach` and printed in the attach's own output: the same
+restart, the same [settings layers](#settings-layers), and the same launch.
+`agent persona attach|detach` is the same command and says `persona` where
+`agent instructions attach|detach` says `instructions`. Both names operate on
+the same Agent keys, snapshot, and digest. The Agent keeps its uid and 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). 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 instructions, and whether that confirmation is required without changing
+anything. The Agent whose managed Pane the command runs in is refused with
+`persona-self-target`: an environment inherited from that Pane is not enough on
+its own, the command must be one of that Pane's processes, and when that cannot
+be determined the refusal says so. An Agent with no stored conversation is
+refused with `persona-no-conversation`. Attaching the instructions an Agent already runs with,
+same name and same content digest, with the snapshot mode off, reports
+`unchanged` and restarts nothing, unless the Agent's other settings resolve to
+something else (a profile edit, for example); after the instructions file is
+edited the digest differs and the attach restarts with the new snapshot. Unlike
+`agent relaunch`, which writes nothing before the stop, an attach records the
+instructions before it, so a plain `agent resume` finishes an attach whose
+resume failed. 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 instructions. 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.
+
+### Agent profiles at create
+
+`create agent --profile <name>` (and the provider shortcuts) starts the Agent
+from a [profile](configuration.md#agent-profiles). Without `--profile`, a
+`--label role=<role>` selects the one profile whose `roles` lists that role; a
+role no profile lists selects none. A role that several profiles list
+(`profile-role-claimed`) refuses the create: remove the role from all but one
+of the listed profiles, or pass `--profile none`. A role whose one listing
+profile is invalid (`profile-role-profile-invalid`, naming the profile and its
+own reason) refuses too, rather than create the Agent without that profile's
+permissions: fix the profile, or pass `--profile none`. `--profile none`
+applies no profile and does no role mapping. The label is read only at
+creation. A profile that is missing, or that `profile list` marks invalid --
+including `profile-role-claimed` -- refuses the create with exit 2 and its
+reason token, whether it is named with `--profile` or selected by a role.
+
+A profile that names a `provider` applies only to Agents of that provider. Any
+other provider refuses the create with exit 2 (`profile-provider-mismatch`,
+naming both providers) before anything is written or launched, on every lane:
+`create agent --provider <p>`, the `create <provider>` shortcuts, a role label,
+and a create from the UI. A profile without `provider` applies to every
+provider.
+
+`create agent` may omit `--provider` when the profile it selects -- by
+`--profile` or by a role label -- names one; the Agent is then created with
+that provider, exactly as if `--provider` had spelled it. With a profile
+`reviewer` that sets `provider = "codex"`:
+
+```sh
+projmux create agent --profile reviewer --project alpha --window main -- "review the diff"
+```
+
+An explicit `--provider` still wins and is still refused when it differs from
+the profile's. A profile that cannot be resolved refuses with its own reason.
+Without a profile, with `--profile none`, or with a profile that names no
+provider, `create agent` still requires `--provider`.
+
+An explicit flag wins over the profile item it overlaps: `--instructions` over
+`instructions`, `--model` over `model`, `--effort` over `effort`. The profile's instructions go through the same path as
+`--instructions` (snapshot and `projmux.io/persona*` annotations, and the same
+Codex lane rule), its effort is recorded as `projmux.io/effort`, and its model
+as `projmux.io/model`. On
+Claude, `allow` and `deny` are passed as `--settings <snapshot>`. Claude does
+not get `sandbox` (`claude-sandbox-bash-only`: its sandbox confines only Bash)
+or `approval` (`claude-no-matching-permission-mode`).
+
+Codex applies `sandbox` and `approval` on every create and resume lane. A
+prompted native create sends them on `thread/start`, and a native resume sends
+them on `thread/resume`; a policy mismatch refuses the operation
+(`codex-thread-policy-mismatch`). Promptless and `--interactive-only` creates
+and CLI resumes pass `-s <sandbox>` and `-a <approval>` before the workspace
+and resume arguments. `full-access` is spelled `danger-full-access` for Codex.
+The CLI accepts `approval = "on-request"` or `"never"`. It refuses a profile
+with `approval = "untrusted"` before launch
+(`codex-cli-untrusted-approval-unsupported`); the native lane still accepts it.
+Codex does not get `allow` or `deny` (`codex-command-rules-unsupported`),
+which remain visible as skipped items. Codex applies Profile `model` and
+`effort`. Any other provider refuses a profile with permissions
+(`profile-permissions-unsupported-provider`) and skips `model` and `effort`
+(`provider-option-unsupported`). The reply-only activation refuses a profile
+(`profile-lane-unsupported`).
+
+The Agent records `projmux.io/profile` and `projmux.io/profile-digest`. The
+result names the profile and each item that was not applied, with its reason:
+`profile name=<name> digest=<digest>` and `profile-not-applied item=<item>
+provider=<provider> reason=<token>` lines after the receipt line, a `profile`
+object (`name`, `digest`, `notApplied`) in `-o receipt`, and the same lines on
+stderr for the other projections. Items replaced by a flag are disclosed as
+`overridden-by-flag`. A create that applies no profile prints exactly what it
+printed before.
+
+Every Claude resume of such an Agent -- `agent resume`, Continue/topology
+replay, and the resume picker -- re-reads the profile by name, passes its
+current rules as `--settings`, and records the new digest. A profile that is
+gone or invalid -- including one now marked `profile-role-claimed` -- refuses
+the resume (`profile-resume-unavailable`, naming the underlying reason); there is no
+resume without its permissions. `agent resume`, `agent relaunch`, and
+Continue/topology replay also take the profile's current instructions, model,
+and effort for the items the Agent does not override
+([settings layers](#settings-layers)); the resume picker resolves the values it
+inherits the same way, each an override of the new Agent. A resume
+picker selection inherits the profile when every Agent recording the
+conversation records the same one, and refuses when they disagree.
+
+A native Codex resume of such an Agent -- `agent resume`, and a resume picker
+selection of an app-server thread -- re-reads the profile by name the same
+way, sends its current `sandbox` and `approval` on `thread/resume`, and
+records the new digest. A thread that is already loaded keeps the policy it
+runs with, so a resume whose answer reports another policy is refused
+(`codex-thread-policy-mismatch`) and nothing is committed. Continue/topology
+replay and a resume picker rollout row resume Codex as `codex resume <id>`,
+which cannot carry a policy: when the Agent's profile now sets any permission
+they refuse (`profile-resume-unavailable`, `profile-lane-unsupported`), and a
+profile without permissions resumes as before. An Agent without a profile
+sends exactly the request it sent before.
+
+Each of those settings records where it came from, beside its value, so
+`describe agent -o json` tells a profile item apart from an override. The
+keys are `projmux.io/profile-source`, `projmux.io/instructions-source`,
+`projmux.io/model-source`, and `projmux.io/effort-source`; the values keep
+their own keys (`projmux.io/profile`, `projmux.io/persona`, `projmux.io/model`,
+`projmux.io/effort`), whose meaning does not change.
+
+| Source | Written by |
+| --- | --- |
+| `flag` | `create agent` (and a UI create) for `--profile`, `--instructions`, `--model`, and `--effort` |
+| `role` | `projmux.io/profile-source` only: the profile a `role` label selected |
+| `profile` | item sources only: the item the create's profile filled in, or that a resume, a relaunch `--reset`, or a relaunch `--profile` switch put in the profile layer |
+| `inherited` | a resume picker selection, for the profile, instructions, and effort it inherited |
+| `resume` | `agent resume --model/--effort` |
+| `relaunch` | `agent relaunch`: `--profile` (for `projmux.io/profile-source`), `--instructions`, `--model`, and `--effort` |
+| `attach` | `projmux.io/instructions-source` only: the deprecated attach and detach ([Deprecated instruction spellings](#deprecated-instruction-spellings)) |
+
+An item source other than `profile` means the value overrides the profile.
+After a detach the Agent records `projmux.io/instructions-source=attach`
+without `projmux.io/persona`: it was explicitly given no instructions. Every
+source is written in the same transaction as its value, so a launch that fails
+rolls back both, a restored attach or detach restores both, and a command that
+writes no value writes no source. An Agent without a source key recorded its
+value before sources were, and the source is unknown. The source keys are not
+part of the resume picker's inheritance agreement: Agents that record the same
+values with different sources still agree.
+
+<a id="settings-layers"></a>
+**Settings layers.** `agent resume`, `agent relaunch`, Continue (the topology
+replay that brings a Project's Agents back), and a resume-picker create launch
+an Agent with its settings resolved from two layers: an item the Agent overrides keeps the
+recorded value, and an item it does not override takes the profile's value as
+the profile is now (none when the profile sets none). The items are the
+instructions, the model, and the effort; permissions come only from the
+profile. So an edit to a profile reaches every Agent that uses it on its next
+`agent resume`, plain `agent relaunch`, or Continue, except for the items that
+Agent overrides, and each of those launches of one Agent passes the same
+model, effort, and instructions:
+
+- The effort is passed on every launch, as before.
+- The model is passed only when the resolved model differs from the recorded
+  `projmux.io/model` (a profile whose model changed); an unchanged model is not
+  passed, so the provider restores the conversation's own, a `/model` switch
+  included.
+- The instructions are passed as a snapshot of their current content, with
+  the system prompt snapshot off, when their name or content changed, as
+  described above. A Codex thread keeps the developer instructions it started
+  with: its resume passes the rest and discloses the instructions it did not
+  apply (`codex-instructions-immutable`), recording nothing for them.
+
+The launch records each value and source it ran with in its own transaction.
+An item without a source key predates sources; its layer is decided from its
+value: equal to the profile's current value means the profile layer, which the
+launch then records as `profile`, and anything else -- a value the profile does
+not set, or no value where the profile sets one -- is an override of unknown
+source that keeps no source key. An Agent without a profile overrides every
+item. So the first resume after the upgrade launches exactly what the Agent
+launched before.
+
+A resume-picker create resolves the Agent it records the same way: the
+values and the profile it inherits from the Agents that already hold the
+conversation are that Agent's record, where each inherited value is an
+override (source `inherited`) and an item nothing inherited follows the
+profile. Inherited instructions whose file was edited therefore launch as a
+snapshot of the new content with the system prompt snapshot off, exactly as
+`agent resume` of the new Agent would. No model is inherited, so none is
+passed. Which values are inherited, and when holders disagree, is unchanged.
+
+The layers change only through `agent relaunch` (and the deprecated attach and
+detach, which run the same restart): `--profile` switches the profile
+layer and clears the overrides, `--instructions`, `--model`, and `--effort`
+add overrides, and `--reset` removes them. An item with neither a profile nor
+an override has no value and no source.
+
 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
@@ -1743,7 +2452,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
@@ -1757,13 +2466,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).
 
@@ -1823,22 +2537,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`
@@ -1849,8 +2562,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
@@ -1858,13 +2571,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
@@ -1880,19 +2589,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.
@@ -2119,6 +2820,40 @@ servers before installing current bindings. If the current keymap assigns `C-t`
 to another action, that current action is bound after cleanup and remains the
 owner.
 
+## profile
+
+```
+projmux profile list
+projmux profile show <name>
+projmux profile set <name> [--file <path> | -]
+projmux profile delete <name> --yes
+```
+
+A profile is a named set of Agent start settings -- provider, instructions,
+model, effort, roles, and permissions -- kept in `<config dir>/profiles/<name>.toml`.
+The file format and vocabulary are in
+[Configuration](configuration.md#agent-profiles). These commands store and
+validate profiles; `create agent --profile <name>` applies one (see
+[Agent profiles at create](#agent-profiles-at-create)).
+
+- `list` prints `NAME SOURCE PROVIDER INSTRUCTIONS MODEL EFFORT ROLES DIGEST
+  VALID` for every profile. `SOURCE` is `user`, and `DIGEST` is
+  `sha256:<hex>` over the file bytes. An item the profile does not name is
+  `-`; so is `PROVIDER` for a provider-neutral profile. A file that fails
+  validation stays listed as `no (<reason>)` and does not hide the others;
+  when it still parses, it shows what it names, roles included, and a file
+  that does not parse shows `-` for each item.
+- `show` prints the stored bytes exactly.
+- `set` validates the whole file first and writes it atomically (0600) only
+  when it is valid; `-` or no `--file` reads stdin. A refusal exits 2, prints
+  one stable reason (`profile-syntax-invalid`, `profile-key-unknown`,
+  `profile-table-unknown`, `profile-value-invalid`, `profile-provider-unknown`,
+  `profile-instructions-not-found`, `profile-role-duplicate`,
+  `profile-role-claimed`, `profile-name-invalid`, `profile-name-reserved`, or
+  `profile-too-large`), and leaves any existing file unchanged.
+- `delete` removes a user file. A missing profile is `profile-not-found` (exit
+  1).
+
 ## config
 
 ```
@@ -2236,7 +2971,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
@@ -2249,35 +2984,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
@@ -2296,8 +3020,8 @@ human configuration work should prefer `config render` and `config apply`.
   diagnostics guides: use `projmux setup` for key-delivery diagnosis,
   `projmux setup terminal` for supported terminal remediation, and the
   read-only `projmux doctor` report for dependency/runtime diagnostics. In Project
-  Picker, `Project Root` manages the saved
-  primary root (`~/.config/projmux/projdir`) and displays whether the effective
+  Picker, `Project Root` manages the saved primary root
+  (`$HOME/.config/projmux/projdir`) and displays whether the effective
   value comes from `PROJMUX_PROJDIR`, tmux `@projmux_projdir`, saved config, or
   no configured source. When no source is configured, the direct-set prompt
   starts with `$HOME` as an editable fallback, but `$HOME` is not used as the