projmux 0.12.2 → 0.13.1

package/docs/cli-guide.md

@@ -63,6 +63,28 @@ rendered from the same command manifest the binary renders `projmux help`
 from and is verified against it on every `make test`, so it cannot drift.
 Nothing in this guide restates it.
 
+Every executable route and root-level parser bridge in that same graph has one
+**selectorless authority** class. The label describes what omission means; it
+does not prevent a route from accepting an explicit selector:
+
+- `natural-omitted` — omission resolves one predictable current resource or a
+  documented contextual read/scope, such as an active-root inventory or picker;
+  supplying any selector replaces that natural target or scope instead of
+  blending with it. Current Pane/Window mutations still require one exact
+  resource.
+- `explicit-target` — the route or its generated caller must name the exact
+  target; ambient tmux context cannot supply or narrow it.
+- `refusal` — the node has no safe selectorless action, so omission refuses
+  before output or mutation. Namespace nodes use this class when only a child
+  route is executable.
+- `explicit-fan-out` — the route spelling is an intentional global or
+  whole-set operation. Resource mutations never enter this class merely
+  because a selector happened to match several rows.
+
+The generated reference and `projmux <route> --help` print the class projected
+from the graph. Completeness tests census every graph node plus bare/help/version
+root bridges and reject missing, duplicate, conflicting, or unknown rows.
+
 ## Resource selectors and the active target
 
 The resource routes (`get`, `describe`, `create`, `rename`, `rebind`, `delete`,
@@ -111,13 +133,16 @@ The contract:
   --name current` succeeds — so a sentinel token would silently shadow a real
   resource.
 - **"No selector at all" means exactly that.** Any positional `<ref>`, any
-  `--project`/`-p`, `--window`/`-w`, `--pane`, or any `--selector` label keeps the
-  pre-existing behavior unchanged. The fallback is never blended into a
-  partially specified selector.
-- **Only the singular routes.** The plural reads (`get projects|windows|panes|
-  agents`) stay 0..N inventories over their whole scope. `delete` and `create`
-  are unchanged: `create`'s omitted `--pane` selects a split anchor inside an
-  already-chosen Window, which is not the same question.
+  `--project`/`-p`, `--window`/`-w`, `--pane`, or any `--selector` label keeps
+  picking the target itself. The active *target* is never blended into a
+  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 --
+  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
   server answers. A bare `display-message` from outside a client still succeeds
   and answers for the most-recently-used session; projmux never uses that.
@@ -136,6 +161,170 @@ and `@projmux_window_uid` on its window — and derives every ancestor from
 registry `ownerRef`. The session-scoped `@projmux_project_uid` is deliberately
 not consulted.
 
+### Plural read scope: the active managed root
+
+Inside tmux, selector-omitted `get windows|panes|agents` derives one exact
+managed root from the active Window's Registry `ownerRef`:
+
+- a Project-owned Window lists only that Project's descendants;
+- a ControlSession-owned Window, including Home, lists only that
+  ControlSession's descendants;
+- a missing Window mirror, a foreign Window uid, or a Window without one exact
+  existing Project or ControlSession owner is exit `2` with zero stdout. It
+  never falls through to the whole Registry.
+
+The default narrows the Window universe and does not pick a target. Name and
+label selectors keep their existing meaning inside that root. An applicable
+explicit `uid:` occurrence is opaque Registry-global authority: like explicit
+`--project`/`-p` and `--all-projects`/`-A`, it bypasses active-target observation
+entirely, including from a foreign tmux Pane. The two whole-set spellings retain
+their existing meaning and include ControlSession descendants. Outside tmux, an
+omitted root keeps the historical whole-Registry inventory without probing a
+default server.
+
+### Reference scope: the active Project namespace
+
+A `metadata.name` is unique inside its owner scope, never across the registry: a
+Window name is unique inside its Project, a Pane name inside its Window or
+Agent, an Agent name inside its Window. So inside a managed Project a reference
+is resolved inside the Project that owns the active Window, which is the same
+universe the plural reads use in that context:
+
+```
+projmux describe window zsh    # the Window named zsh in *this* Project
+projmux describe pane log      # the Pane named log in this Project
+projmux describe agent codex   # the Agent named codex in this Project
+projmux rename window zsh --name review
+projmux rename pane log --name build
+```
+
+The Project-only read matrix is `describe window|pane|agent`. Generic
+`rename window|pane|agent` uses the same narrowing rule but accepts either the
+active Project or ControlSession as the exact owner root. `describe project`
+and `rename project` are not in either matrix — a Project has no enclosing
+root — and `delete`, `rebind`, and `agent resume` keep their selector meaning.
+
+The contract:
+
+- **It narrows the search, it does not pick the target.** The Project fixes the
+  universe and nothing else. The active Window and the active Pane are not used
+  to break a tie, so two same-named resources inside the one Project stay the
+  ordinary bounded `matched N ..., want exactly one` ambiguity. Resolving that
+  is what `--window`/`--pane` and a `uid:` reference are for.
+- **Explicit `--project`/`-p` wins, with zero observations.** Naming a Project
+  never costs a tmux round trip and never depends on the pane you are sitting
+  in.
+- **A `uid:` reference is scoped too.** A uid that belongs to another Project is
+  a no-match, not a cross-Project hit. Pass `--project` to address it.
+- **Outside tmux nothing changes.** The whole registry is searched and the
+  previous `matched N ..., want exactly one` ambiguity is unchanged. No default
+  tmux server is probed.
+- **Inside tmux a broken owner chain refuses.** A pane carrying no
+  `@projmux_window_uid`, a mirrored Window uid the registry does not hold, or a
+  Window with no exact existing Project or ControlSession owner is exit `2`
+  with zero bytes on stdout and zero mutations for generic rename. It is never
+  a silent fallback to the whole registry.
+
+### Create scope
+
+`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.
+
+The scope resolves in two branches:
+
+- **Explicit `--project`/`-p` wins**, inside tmux and outside it. The active
+  tmux target is not consulted at all.
+- **With no explicit scope occurrence, the Project comes from the active managed runtime**:
+  the `@projmux_window_uid` mirrored on the pane you are in, and that Window's
+  registry `ownerRef`. This is the same seam the empty-selector reads use.
+
+The Window and the anchor Pane follow the *whole* scope rather than the Project
+flag alone:
+
+```
+projmux create codex                       # active Project, active Window, split from the active Pane
+projmux create codex -p alpha -w hi --create-window  # exact Project, new Window "hi"
+projmux create codex -p beta -w main        # everything explicit
+projmux create pane -p alpha                # every Window of alpha; a deliberate fan-out
+```
+
+One explicit scope occurrence (`--project`, `--window`, `--pane`, or
+`--selector`) makes the whole scope explicit, so naming a Window never picks up
+an anchor from somewhere you did not address. With a scope but no `--pane`, the
+split anchor is the target Window's role-agnostic `spec.anchorPaneRef`. A
+shell-required offline operation may plan a lazy direct
+`spec.defaultShellPaneRef` without replacing an Agent anchor. A missing or stale
+anchor is exit `2` rather than a silent alternate-Pane repair.
+
+An exact existing Window or Pane can reveal its owner Project through Registry
+`ownerRef`. A Window named with `--create-window` does not exist yet and cannot;
+without `--project` that spelling refuses and names `--project <ref>` as the
+remedy, even when the invocation happens inside a managed Pane.
+
+Refusals are exit `2` with zero Registry writes and zero tmux mutations, and
+they name `--project` as the fix:
+
+- outside tmux with no `--project` — no default server is probed;
+- inside Home, a control session, an unattributed pane, or a foreign pane —
+  none of those carry a managed identity, and projmux never invents a Project
+  from `$HOME`, a session name, or a cwd;
+- a mirrored uid the Registry does not hold, or a Window whose owning Project is
+  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
+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
+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`
+containment. Outside tmux it validates the default app `-L` route. Marker,
+physical-socket, server-PID, generation, and owner reobservation remain
+mandatory. Commands that explicitly select an existing live `--socket-path`
+keep that exact `-S` route unchanged.
+
+#### Splits started from a popup
+
+The split UI's own pickers (`M-7`, `M-4`/`C-r`, the pane context menu, and the
+default split key when the saved mode is `selective` or `resume`) run inside a
+`display-popup`. tmux exports `$TMUX` to a popup job and deliberately exports no
+`$TMUX_PANE`, because a popup is not a pane — so the picker has no inherited
+target of its own while still knowing, from the keypress that opened it, which
+pane the operator was in. That pane travels on the create intent as an explicit
+anchor and resolves Project, Window and split anchor through the same identity
+mirror a pane-hosted invocation reads.
+
+The anchor is something the split UI hands to `create`, never something `create`
+reads from the environment. `$TMUX_SPLIT_TARGET_PANE` is not a scope override:
+typing `projmux create pane --placement right` inside a popup is still an
+invocation with no target and still refuses with the `--project` usage error
+above, and no read, rename, or delete verb consults it.
+
+#### Managed pane context menu
+
+The generated `MouseDown3Pane` menu treats its Horizontal Split, Vertical
+Split, and Kill entries as Projmux resource actions. Both splits pass the exact
+clicked pane through the popup-origin anchor above and reach the same canonical
+`create pane` materializer as the CLI, so the new pane receives a Registry uid.
+Kill resolves that anchor's mirrored uid and reaches canonical `delete pane`,
+including its printed delete result. The menu never falls back to a raw tmux
+mutation when either route refuses. The reason is displayed on the exact client
+that opened the menu instead of being lost as a `run-shell` exit code.
+
+tmux Respawn has no equivalent in the current resource model: it preserves the
+same pane handle, layout, Registry uid, and original command, while canonical
+delete plus create removes that identity and creates another one (and may end
+the Window or Project session when it deletes the last pane). The generated
+menu therefore omits Respawn entirely and does not expose a refusal handler or
+invent a replace operation. User-authored tmux bindings remain outside this
+managed-menu contract.
+
 ### Rename and rebind live convergence
 
 `rename project|window|pane` commits the selected Registry `metadata.name` and
@@ -166,6 +355,26 @@ duplicate UID claims remain fail-closed.
 
 ### Agent topic, interaction, activation, and workspace
 
+`agent turn start`, `agent turn steer`, `agent turn interrupt`, and
+`agent approval review` use the live Codex app-server connection only when the
+selected Agent, its owned Pane, activation generation, thread, current turn,
+and connection epoch still match exactly. `start` sends only the exact thread
+id and one text input; `steer` supplies the current expected turn id; and
+`interrupt` supplies that exact turn id. These commands never install sticky
+model, effort, cwd, sandbox, permission, or collaboration overrides.
+
+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
+profile with `scope=turn` and `strictAutoReview=null`. Session grants, policy or
+network amendments, unstable root grants, legacy approval mutations, and
+automatic approval are unavailable. The request envelope and raw JSON-RPC id
+remain only in connection memory; reconnect, resolution, ambiguity, or any
+identity mismatch produces no provider write. Approval queue rows advertise
+`Review pending approval` only while that responder exists, otherwise they
+advertise the exact-Agent `Open Codex` focus fallback; resolution removes the
+row. Neither route stores prompt, command, path, permission, or request content.
+
 `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
@@ -193,6 +402,40 @@ and shell Pane manual attention share the existing priority reducer, while
 `dot`/`emoji`/`off`, glyphs, colors, and the Window aggregate are never stored
 in resource metadata.
 
+A clean managed process exit is topology authority only through the exact
+generated `pane-exited` hook. The supervisor must have durably journaled a
+same-generation `normal` receipt, the hook must name the exact `%N` Pane and
+the owner Window must carry its exact last-positive `$N/@N` binding on the same
+socket, and fresh preflight plus locked observations must still resolve the
+same Registry owner chain. A non-last Pane is removed while its directly owning
+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
+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
+content, prompt, history, and transcript are never parsed. `abnormal`,
+`killed`, `unknown`, stale/resumed bindings, empty or unavailable inventory,
+permission failure, and foreign-host/window observations keep their diagnostic
+rows and produce no automatic delete plan.
+
+For `pane-exited`, tmux supplies `%N` as `#{hook_pane}`. Its current-context
+session/window formats may already name a surviving client Window, so the owner
+pair comes from the Window's last live Registry observation. The separate
+`window-unlinked` hook supplies exact `#{hook_session}` and `#{hook_window}`;
+only a matching causal pair authorizes last-Pane Window deletion.
+
+An offline historical Window with no stored causal last-Pane receipt is not
+absence-only migration authority and is never auto-deleted. Recover it with the
+canonical exact route, `projmux delete window uid:<window-uid> --socket <name>
+--yes` (or the corresponding `--socket-path`/inherited absolute `$TMUX` route).
+Deleting a Project's last exact Window retains the Project with zero Windows;
+within the runtime/startup lifecycle table, explicit `delete project --yes` is
+the unregister operation. Runtime absence, managed Stop, ordinary Window close,
+and Fresh never invoke the separately scoped filesystem-missing `prune project`
+administrative policy.
+
 Resource-backed Agent create accepts provider-neutral `--cwd <absolute>` and
 repeatable `--add-dir <absolute>`. Explicit paths must exist, resolve without a
 symlink escape, and remain inside a registered Project tree; only Codex and
@@ -210,8 +453,15 @@ 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 waits for bounded hook/lifecycle
-metadata only; it never captures pane content or stores the prompt. If
+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
+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
@@ -219,7 +469,13 @@ being reported as an ordinary success.
 
 Activation metadata is bounded to provider-hook provenance and fixed
 acknowledged/timed-out/failed diagnostics. Provider error strings and initial
-prompt text are never stored. Resource-backed Agent create and resume do not
+prompt text are never stored. `pending` can become `unconfirmed` and a later
+exact hook can refine either state to `acknowledged`; acknowledged never moves
+backward. Late refinement must quote the same Agent, Pane uid, activation
+generation, and recorded live `%N`, so a hook from a replaced materialization
+cannot acknowledge its replacement. Codex and Claude initial payloads use the
+same acknowledgement and result contract; provider-specific prompt content is
+not evidence. Resource-backed Agent create and resume do not
 start the legacy title/content watcher; that watcher remains only for legacy
 non-resource panes and exits before reading title or capture content if resource
 identity appears.
@@ -315,14 +571,23 @@ 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. Choosing `Latest snapshot` or `Named snapshot`
-instead stays entirely on the Session State snapshot engine. Reading whether a
-Project declares topology is a zero-write snapshot read, so opening a directory
-that was never registered still creates no Registry state.
-
-Materialization never starts or resumes an Agent, creates an Agent-owned Pane,
-or executes `Pane.spec.command`; that field remains a one-time name seed. A
-new Window binds only its own tmux-created primary Pane. On an existing Window,
+session the open never reaches. The closed-Project startup screen has exactly
+two neutral actions. `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. `Open fresh` is one step with no danger styling, confirmation, or
+delete counts: 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.
+
+Materialization launches or resumes declared Agents through the canonical
+provider/trust path and creates their managed Agent-owned Panes. An individual
+Agent refusal preserves the committed desired Registry and emits an item notice
+for retry. It never directly executes `Pane.spec.command`; that field remains a
+one-time name seed. A new Window binds only its own tmux-created primary Pane. On an existing Window,
 every pre-existing uid-less Pane is refused rather than adopted; foreign,
 duplicate, wrong-owner, or otherwise ambiguous UID state is refused before the
 first create. Layout uses the existing deterministic right-axis equalizer and does
@@ -334,6 +599,193 @@ Registry-only: its complete Agent/Pane cascade is shown under `--dry-run`, no
 tmux object is killed, and unrelated live objects and sockets are untouched. A
 unique live mirror keeps the exact-kill path, while duplicate, foreign,
 stale-owner, inventory-failure, and revalidation-race states are refused.
+The selected Window's Registry `ownerRef` is authoritative in that preflight:
+a Project uses its `status.session` plus the optional matching Project uid
+mirror, while a ControlSession uses its exact `spec.session` and requires that
+no Project uid mirror contaminate the control session. Window, Pane, and Agent
+deletes preserve that `(root kind, root uid)` chain in the signed live plan and
+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.
+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
+the same socket, owner/root chain, lifecycle evidence, Pane activation
+generation, and Agent binding; locked revalidation refuses zero-to-live,
+live-to-zero, owner, generation, duplicate, or foreign changes. A successful
+Registry-only result reports that no tmux Pane was killed, preserves the owning
+Window/root/socket and all siblings, and repeating the exact apply returns the
+ordinary no-match result.
+
+`delete window|pane|agent` names the server its live half addresses the same
+way `reconcile resources` does: `--socket <name>`, `--socket-path <absolute>`,
+or the inherited absolute `$TMUX`. Outside tmux with neither flag it refuses
+rather than reaching for the app's own socket, so a delete issued against an
+isolated server can never inventory one host and kill objects on another.
+
+Before it kills anything, a delete commits an intentional termination receipt
+against every Pane whose process it is about to end, in its own Registry
+transaction. If that write fails, nothing live is touched; if the delete then
+refuses for any other reason, the receipt is withdrawn again. The receipt is
+what tells a later reader that a process disappeared because someone asked for
+it, rather than because it crashed.
+
+## get runtime
+
+```text
+projmux get runtime sessions|windows|panes [--socket <name> | --socket-path <absolute>] [-o json|none]
+```
+
+`get runtime` is the read-only escape hatch onto one exact tmux server. The
+resource reads (`get projects|windows|panes|agents`) enumerate the Registry;
+this one enumerates the machine, including everything projmux does not own, and
+it accepts no selector because most of what it reports has no name to resolve.
+Its kinds are tmux object kinds, not resource kinds, and they have no singular
+spelling for the same reason.
+
+Every row carries the attribution the resolved resource graph decided from exact
+evidence -- `managed`, `recoverable`, `control`, `ephemeral`, `unattributed`,
+`foreign`, `conflict` -- the reason for it, the stable tmux id, the fully
+qualified coordinate (`<session>`, `<session>:@N`, `<session>:@N.%N`), and, for a
+managed object, the Registry resource it is bound to. A refused object is named
+and explained and is never handed a resource identity.
+
+Socket selection is the same fail-closed rule `reconcile resources` uses, with
+one difference at the end:
+
+- `--socket <name>` means exactly `tmux -L <name>`.
+- `--socket-path <absolute>` means exactly `tmux -S <absolute>`.
+- The two flags are mutually exclusive.
+- With neither flag, an invocation inside tmux inherits only the absolute socket
+  path from `$TMUX` and uses `-S`.
+- With neither flag outside tmux the read still succeeds. It returns the
+  unavailable projection: no items, every scope reported unobservable with a
+  reason, and zero tmux calls. There is no default-socket guess, and a sibling
+  socket is never read.
+
+The default projection is a table preceded by a header line naming the host mode
+and the exact transport, plus one line per scope that could not be observed. The
+header is always printed, even when the table is empty: "no sessions" is only
+trustworthy next to which server was asked and whether the answer could be taken
+at all. `-o json` emits the same data as a stable `Runtime{Session,Window,Pane}List`
+envelope; `-o none` prints nothing. The Registry projections (`uid`, `name`,
+`ref`, `metadata`) are deliberately not offered, because most of what this route
+returns has none of them.
+
+The read writes nothing: the Registry is opened without being created, the
+observation issues one option probe and three list queries whatever the size of
+the server, and no write verb is ever sent.
+
+## runtime diagnostics
+
+```text
+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
+server in containment order with an attribution tally, and it is deliberately
+separate from `projmux runtime sessions`: that picker lists recent sessions so
+you can open one, this one lists everything so you can understand it.
+
+Selecting a row opens its action menu, which offers only routes that already
+exist:
+
+- **Focus** hands `projmux focus` the row's exact coordinate and the server's own
+  `#{socket_path}`. It moves a client and never materializes anything.
+- **Attach** forwards to `projmux attach project uid:<uid>`, and is offered only
+  for a session bound to a Registry Project while you are outside tmux.
+- **Open Resource Inspector** opens `projmux resources` unchanged.
+
+An action that does not apply is listed with the reason instead of being hidden:
+"no Registry Project claims this session; diagnostics never adopts one" is the
+diagnostic. There is no adopt, import, rename, or kill action, and opening the
+surface writes nothing.
+
+## reconcile registry
+
+```text
+projmux reconcile registry [--dry-run] [--source <name|absolute-path>] [--expect-source-checksum <sha256:hex>] [--expect-current-checksum <sha256:hex>] [--socket <name> | --socket-path <absolute>] [-o json]
+```
+
+`reconcile registry` is the recovery boundary for the Registry itself. It is a
+sibling of `reconcile resources`, not a stronger version of it: `reconcile
+resources` converges a Registry that loads, and this route runs when the
+Registry is the thing that is wrong.
+
+Planning writes nothing. With no `--source` — and with `--dry-run` at any time —
+the command reads the current `registry.json`, the `registry.initialized`
+marker, and the bounded copies under `recovery/`, then reports:
+
+- the current state as `valid`, `first-use`, `missing`, `empty`, `malformed`,
+  `schema-too-new`, `invalid`, or `unreadable`, with a `sha256:` digest of the
+  exact bytes;
+- every candidate newest first, each marked `eligible` or `rejected` with the
+  reason, its digest, size, mtime, schema version, and the
+  projects/windows/panes/agents/reservations it holds;
+- the exact guarded command that would restore the candidate it suggests.
+
+No lock is taken, no permission is repaired, and `<state>/projmux/metadata/` is
+not created — a preview is safe against a first-use state directory and against
+one nobody should be writing to yet.
+
+Restoring requires `--source`. There is no "restore the newest" mode: which copy
+is the truth is a judgment about which mutations were wanted. A source is an
+exact copy name, a unique fragment of one, or an absolute path to a copy carried
+from elsewhere; a fragment matching several copies is refused rather than ranked.
+An explicit path gets exactly the same verification as a bounded copy.
+
+Verification is fail closed. Malformed JSON, an empty file, an envelope newer
+than this build, and a graph with a duplicate uid, a dangling `ownerRef`, or a
+broken name reservation are all refused with the current Registry byte-identical.
+The verified bytes are then published **verbatim**, so uids, owner relations, and
+name reservations are preserved exactly rather than re-encoded, and a
+known-older-but-valid envelope stays readable through the normal safe read and
+migrates on the next semantic write.
+
+The bytes being replaced are kept first, at
+`recovery/replaced-<stamp>-<seq>.json`. Unlike the write-side copies this keeps
+content that does not verify: a damaged Registry is the only remaining evidence
+if the restore turns out to be the wrong call, and the preserved copy is offered
+back as a candidate. Replaced copies are their own bounded family, so a restore
+never consumes the automatic write history.
+
+Race guards are the operator's tie to the plan they read:
+
+- `--expect-source-checksum <sha256:hex>` refuses unless the source still hashes
+  to that digest.
+- `--expect-current-checksum <sha256:hex>` refuses unless the current Registry
+  still does.
+- Both are what the printed `next:` command already carries, so copy-pasting the
+  preview's suggestion is guarded by construction.
+
+Underneath, the source is re-read and re-verified under the store lock, the
+staged copy is re-validated, and both inputs are re-hashed immediately before the
+single atomic rename. Anything that moved refuses with nothing published, no
+preserved copy, and no staged file left behind, and says to re-run the preview. A
+repeat restore is a byte no-op: no rename, no preserved copy, no marker write.
+Restoring into a state directory with no marker publishes one, so a later loss on
+that machine reads as state loss rather than as a fresh first use.
+
+When recovery is needed and no verified copy exists, the report adds a mirror
+diagnostic — and it is **only** a diagnostic. It reports the Projmux identity the
+one exact tmux server still carries (Project/Window/Pane uids, mirrored names,
+the Project root, and containment resolved from stable tmux ids) beside a fixed
+statement of what no mirror can return: offline resources, every Agent (no tmux
+option carries an Agent uid), an Agent-owned Pane's `ownerRef`, the name
+reservation table, `spec.anchorPaneRef`, `spec.defaultShellPaneRef`, and labels/annotations/timestamps/
+status. Panes carrying a provider option are counted as proof that Agents existed
+whose uids are nowhere on the server. Nothing is imported and no Registry is
+generated from fragments. Socket selection follows the same `--socket` /
+`--socket-path` / inherited-`$TMUX` rule as `reconcile resources`, except that
+having no exact target is reported as a reason rather than being a usage error:
+a restore is a filesystem operation, so recovery must work on a machine with no
+tmux server. The diagnostic is skipped entirely when a verified copy exists or
+the Registry is healthy.
 
 ## Internal plumbing (`projmux internal ...`)
 
@@ -854,6 +1306,13 @@ projmux attention window [window]
 Toggles the `✳` pane title prefix and the `@projmux_attention_state` pane
 option. `toggle` flips between cleared and `reply`; `clear` always
 clears; `arm` sets a pre-reply armed state used by the AI flow. The
+optional pane is the exact pane invoking the command: when it is omitted,
+Projmux requires inherited `$TMUX` plus an exact `$TMUX_PANE=%N` and verifies
+that same pane with a targeted tmux read before changing attention state. From
+outside tmux, or when that evidence is missing, malformed, or stale, pass an
+explicit pane target instead; the command fails without writing attention
+state. Explicit targets used by generated focus hooks keep their existing
+meaning.
 producer side pushes the matching entry into the notify queue when the pane
 has an associated AI agent option; clearing attention does not ack the queue
 row (manual toggles on shell panes do not push). `list` reads `tmux list-panes -a` and shows live pane
@@ -865,8 +1324,8 @@ supplied window.
 ## Agent creation and hook ingress
 
 ```
-projmux create agent --provider <claude|codex|antigravity> [--placement right|down] ...
-projmux create pane [--placement right|down] ...
+projmux create agent --provider <claude|codex|antigravity> [--project <ref>] [--window <ref>]... [--create-window] [--placement right|down] ...
+projmux create pane [--project <ref>] [--window <ref>]... [--create-window] [--placement right|down] ...
 projmux config edit [--get|--set <mode>]
 projmux agent status set <thinking|waiting|idle> [pane]
 projmux agent topic ...
@@ -897,34 +1356,60 @@ yellow respectively. That palette is independent from notify queue
 can still render a non-red action-required status badge.
 
 `create agent --provider ...` selects a provider without changing the saved
-default. Concrete provider invocations create a new managed
-agent pane every time; existing managed AI panes in the same project/session are
-not selected or reused.
-The provider picker and plain Pane creation remain available through the
-canonical create workflow. Arguments after `--` are extra arguments appended to
+default. Concrete provider invocations create a new Agent and a new managed
+Pane every time; existing managed AI panes in the same project/session are
+not selected or reused, and rebinding an existing conversation is `agent
+resume`, a different verb. The scope of the new resources follows
+[Create scope](#create-scope). The provider picker remains available through
+`internal agent-pane picker`. Arguments after `--` are extra arguments appended to
 the resolved `claude`, `codex`, or `agy` executable inside the managed wrapper;
-projmux still sets the context directory, tmux title, AI pane metadata, title
-watcher, and split layout.
-
-Automation callers can add `--print-pane-id` to an explicit direct
-`--agent claude|codex|antigravity|shell` launch. On success, stdout contains
-exactly the new `%N` pane id followed by one newline. The value comes directly
-from tmux's existing
-`split-window -P -F '#{pane_id}'` result. If tmux returns no valid pane id, the
-command fails non-zero with tmux-specific guidance and writes no
-success value. Without `--print-pane-id`, successful split invocations keep the
-existing empty-stdout behavior.
-
-`--print-pane-id` is not available for the saved default mode or for
-`--agent selective|resume`, because those paths may open a picker and launch
-only after a later user selection. Those combinations fail before opening a
-picker or creating a pane. Arguments after `--` keep their existing argv-tail
-meaning when the flag is used with a concrete AI agent.
+projmux still sets the context directory, tmux title, AI pane metadata, and
+split layout.
+
+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
+managed Pane's `%N` followed by one newline. See
+[AI Agent Shortcuts](ai-agent-shortcuts.md) for the shortcut spellings.
+
+Every Projmux split surface produces the same canonical create intent. The
+default `ai-split-right/down` binding reads the saved split mode and turns it
+into one intent -- a provider Agent, a shell Pane, or one of the two pickers --
+and the `Alt-7` picker and the resume picker do the same with what the operator
+selected. Only the create route's materializer runs tmux's `split-window`, so a
+pane opened from the UI is a Registry resource on the same terms as one asked for
+by name, and a failed launch leaves zero Registry and zero tmux mutations. A raw
+unmanaged split exists only where you make one yourself.
+
 The resume picker lists the newest deduplicated Claude, Codex, and Antigravity
 resume sessions for the current project, with `[+ New Session]` pinned first.
 If there are no resume sessions it goes straight to the existing selective
-picker. Selecting a row directly starts `claude --resume <id>`,
-`codex resume <id>`, or `agy --conversation <uuid>`.
+picker. Selecting a row creates a managed Agent whose pane joins that
+conversation -- `claude --resume <id>`, `codex resume <id>`, or
+`agy --conversation <uuid>`. Rebinding an Agent the Registry already has is
+`projmux agent resume`, a different verb that never falls back to a fresh
+conversation.
+
+Codex rows come from one source per picker invocation. A healthy app-server is
+primary: `thread/list` is paged with opaque cursors, non-archived and explicit
+`cli`/`vscode`/`appServer` source filters, provider recency ordering, and exact
+cwd/depth filtering. Rows preserve the exact thread id plus provider name,
+branch, and runtime status; an unnamed thread uses only its short id, never its
+prompt preview. The row suffix displays native or rollout source, confidence,
+status, and any closed fallback reason. Unsupported, unavailable, protocol, or
+malformed-pagination results discard the native partial result and run the
+existing rollout scan once. Selecting a native row resumes that same thread id
+through the native lane; selecting a fallback row keeps the current CLI lane.
+Claude and Antigravity discovery and launch semantics are unchanged.
+
+`projmux agent review [<agent-ref>]` starts a native Codex review for
+uncommitted changes by default. Use exactly one of `--base <branch>`, `--commit
+<sha>`, or `--instructions <text>` to choose another review target. The action
+is available only when the selected Running Codex Agent still has an exact live
+Pane/thread binding and the current app-server supports `review/start`; every
+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,
 high-confidence lane; it is not enumerated from disk by the picker. Within the
@@ -944,10 +1429,8 @@ Settings > AI Settings > Enabled agents controls Claude/Codex/Antigravity launch
 visibility. Disabled agents 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
-`--agent claude|codex|antigravity` launches also fail when disabled, including
-shortcuts that call the same command. For a deliberate one-shot direct CLI
-launch, pass `--force-agent`; picker and saved default paths do not use this
-override. If all AI agents are disabled, the selective picker still offers the
+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.
 For user-level skill, slash-command, editor, or launcher registrations that
 call this contract, see [AI Agent Shortcuts](ai-agent-shortcuts.md).
@@ -1283,8 +1766,8 @@ keymap action is no longer accepted: replace a stale
 The `projmux agent topic set/clear` commands keep
 AI topic ownership separate from the user pane label and raw pane title.
 `apply` regenerates the app tmux config and reloads the live `-L projmux`
-server without restarting it. `make install` and `projmux update apply` invoke it
-after replacing the binary. Settings > Keybindings normally runs the same
+server without restarting it. `make install` and `projmux update apply` invoke
+it before binary publication and again afterward for verification. Settings > Keybindings normally runs the same
 save/config/reload flow automatically; use `projmux config apply` (or its
 hidden equivalent `projmux internal tmux apply`) as the CLI recovery or sync path after
 hand-editing `keymap.toml`, after saving Settings outside tmux, or after
@@ -1373,15 +1856,21 @@ binary in `$GOBIN`/`$GOPATH/bin`/`~/go/bin` as `go`, and a local `go build`
 still require an explicit `PROJMUX_INSTALLER=github-release`. Anything else is
 reported as `unknown` with guidance.
 `apply` is installer-aware and only runs after explicit user selection.
-For npm installs, it runs `npm install -g projmux@latest` (which reliably
+For npm installs, the current binary first runs `config apply --bin` with the
+exact published target. Only after that succeeds does it run
+`npm install -g projmux@latest` (which reliably
 crosses minor/major versions where `npm update -g` does not, and re-resolves
 the per-platform optional dependency) and then runs the new binary's
-`projmux config apply`. With `--no-apply`, that convergence step uses
+`projmux config apply` as post-publication verification. A failed preparation
+does not invoke the installer; later failures are non-zero and print the exact
+`projmux config apply --socket projmux` recovery. With `--no-apply`, the
+pre-publication live convergence is omitted and the post-update step uses
 `--no-reload`: it still migrates marker-owned files and writes generated
-configuration without accessing live tmux. For Go installs, it uses the existing atomic
+configuration without accessing live tmux, then explicitly reports that live
+apply remains required. For Go installs, it uses the same ordering around the existing atomic
 replacement implementation. For `github-release` installs, it downloads the latest
 matching `projmux_<version>_<goos>_<goarch>.tar.gz` release asset, extracts the
-binary, atomically replaces the current executable, then performs the same
+binary, pre-converges, atomically replaces the current executable, then performs the same
 apply/`--no-reload` convergence. `source` installs report an
 actionable error to update the checkout with `git pull --ff-only && make install`.
 
@@ -1403,7 +1892,8 @@ returns a usage error.
 
 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`. Resource retention uses `prune
+`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`.
 
 Popup-marker, preview, status, and tmux configuration plumbing is hidden under
@@ -1417,20 +1907,33 @@ 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. Alt-1 sidebar project open defaults to `Project topology`,
-  which materializes the Project's Registry Windows and Window-owned shell Panes
-  before the client moves; the Session State `Sidebar startup picker` opt-in
-  shows `Latest snapshot`, `Named snapshot`, and `Project topology` before
-  starting a closed project session. `Latest snapshot` is auto-saved; named
-  snapshots are fixed until the user saves or replaces them. A directory with no
-  Registry Project, and a Project with no Registry Window, still start as a
-  single default session.
-- `quit` — open an action picker with `Quit projmux` and `Cancel`. Selecting
-  `Quit projmux` terminates only a `tmux -L projmux` runtime whose global
-  `@projmux_app` option is set by the generated app config. Missing servers,
-  default tmux servers, embedded tmux servers, and other tmux runtimes without
-  that marker are no-ops. Non-interactive callers must pass `--yes` or
-  `--force`; the default command always goes through the action picker.
+  startup directory. Alt-1 sidebar project open defaults to `Continue project`,
+  which materializes the Project's Registry Windows, shell Panes, and Agents
+  before the client moves. When the startup picker is enabled it contains exactly
+  `Continue project` and `Open fresh`; Esc returns to Projects. `Continue
+  project` restores a deleted Project only from its usable exact snapshot and
+  otherwise refuses with zero Registry writes. `Open fresh` is a neutral,
+  confirmation-free one-step action that atomically replaces the Project with
+  a new Project/Window/shell UID chain and one same-root claimant. 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.
 - `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