projmux 0.12.1 → 0.13.0

package/docs/cli-guide.md

@@ -71,13 +71,24 @@ The resource routes (`get`, `describe`, `create`, `rename`, `rebind`, `delete`,
 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,
 and a `displayName`, a `spec.root` path, or a raw tmux `%N`/`@N`/`$N` handle
-never resolves anything. `--project` occurs at most once and fixes the scope;
-`--window` and `--pane` repeat and union in argv order; `--selector key=value`
+never resolves anything. `--project`/`-p` occurs at most once and fixes the
+Project scope; `--window`/`-w` and `--pane` repeat and union in argv order;
+`--selector key=value`
 repeats and ANDs. A singular route also accepts the target as a positional
 `<ref>`, which may appear before or after the flags. How many resolved targets
 each `<verb, kind>` pair accepts is a declared matrix, not a per-route rule, and
 a violation is exit `2` with a candidate listing bounded to five rows.
 
+`-p` always means Project, never Pane; Pane has no shorthand. The three plural
+reads `get windows|panes|agents` also accept `-A` as the exact alias of
+`--all-projects`. That escape is mutually exclusive with either spelling of the
+Project selector and is not registered on any other route. Long-only,
+short-only, and mixed scope occurrences share the same value sinks, so repeated
+Window order, cardinality, output, and mutation plans do not depend on spelling.
+For resource-backed `create pane|agent|<provider>`, only aliases before the
+first `--` are Projmux scope flags; every token after it, including `-p`, `-w`,
+`--project`, and `--window`, remains opaque payload in its original order.
+
 ### Empty selector: the active tmux target
 
 Inside tmux, an invocation that carries **no selector at all** addresses the
@@ -100,13 +111,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`/`--window`/`--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.
@@ -125,6 +139,155 @@ 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 `--project`, 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 -w hi --create-window  # active 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.
+
+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. Creates run against the
+inherited exact socket inside tmux; outside tmux an explicit `--project` is
+required before anything live is touched.
+
+#### 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
@@ -155,6 +318,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
@@ -182,6 +365,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
@@ -199,8 +416,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
@@ -208,7 +432,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.
@@ -246,7 +476,7 @@ source, different output, different failure surface — both stay.
 ## reconcile resources
 
 ```text
-projmux reconcile resources [--dry-run] [--socket <name> | --socket-path <absolute>] [-o json]
+projmux reconcile resources [--dry-run] [--materialize-project <name|uid:uid>] [--socket <name> | --socket-path <absolute>] [-o json]
 ```
 
 `reconcile resources` is the explicit repair boundary for drift between the
@@ -288,6 +518,238 @@ It does not run `config apply`, reload unrelated configuration, reconstruct a
 missing Registry, heuristically merge identities, or turn a read verb into a
 write transaction.
 
+`--materialize-project <name|uid:uid>` is the explicit activation opt-in for
+one exact Registry Project. Its separate pure plan treats Registry insertion
+order as desired topology and reports a missing persistent session, each
+missing Window, and each missing Window-owned `role=shell` Pane. Execute creates
+only that missing subset on the selected socket, mirrors the existing Registry
+UID/name/owner graph, preserves each Pane's stored CWD, and is a true no-op when
+the graph is already live. The option is exact-one: repeating it is a usage
+error, and the reported retry preserves both the selector and socket route.
+
+Opening a closed Project is the other activation authority for that same
+engine. The Alt-1 sidebar/`switch open` path materializes the selected Project's
+declared shell topology on the app's own `-L projmux` socket and moves the
+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. 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
+not promise historic geometry. Canonical Registry deletion removes desired
+topology, so a deleted Window or Pane is not recreated; raw runtime loss while
+the resource remains is drift and is materialized. A non-implicit offline
+Window target (an explicit reference or `--all`) can be canonically deleted
+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 ...`)
 
 `internal` is a hidden namespace for the routes generated tmux config, tmux
@@ -545,8 +1007,8 @@ back into the unredacted Doctor Go types.
 
 ```
 projmux focus project <ref> [--socket <path>] [--client <tty>] [--json]
-projmux focus window <ref> --project <ref> [--socket <path>] [--client <tty>] [--json]
-projmux focus pane <ref> --project <ref> --window <ref> [--socket <path>] [--json]
+projmux focus window <ref> -p <project-ref> [--socket <path>] [--client <tty>] [--json]
+projmux focus pane <ref> -p <project-ref> -w <window-ref> [--socket <path>] [--json]
 ```
 
 Moves one attached client to an exact live Project, Window, or Pane. It never
@@ -702,10 +1164,12 @@ core-equivalent CPU. Project and window rows count panes, while pane rows count
 the attributed processes. Pane rows and detail share the resolved pane identity
 and label the tmux current command, PID/SID, pane id, and TTY separately. Memory
 is explicitly an RSS sum (shared pages can be counted more than once) plus its
-host ratio. `No project match`, `Multiple project matches`, and non-drillable
-`Other / unattributed` remain explicit. The first two are display labels over
-stable internal attribution keys. Warming, partial, unavailable, unknown, and
-overage states also remain explicit. No process
+host ratio. Concrete projects and `No project match` are the only project
+drill-down groups; non-drillable `Other / unattributed` remains explicit.
+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
 telemetry is created. Linux/tmux provides attribution; unsupported platforms
 show an unavailable reason rather than zero metrics.
@@ -816,8 +1280,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 ...
@@ -848,34 +1312,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
@@ -895,10 +1385,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).
@@ -1354,7 +1842,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
@@ -1368,11 +1857,16 @@ 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 `Empty session`; the
-  Session State `Sidebar startup picker` opt-in shows `Latest snapshot`, `Named
-  snapshot`, and `Empty session` before creating a closed project session.
-  `Latest snapshot` is auto-saved; named snapshots are fixed until the user
-  saves or replaces them.
+  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 `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,