projmux 0.12.2 → 0.13.1

package/docs/configuration.md

@@ -56,10 +56,46 @@ The saved workdir file is:
 It stores one absolute path per line. Lines beginning with `#` are comments.
 The file is read only when no env root list is set.
 
-## Project Named Snapshots
+Workdirs are a **scan source and nothing else**. Adding a root, and scanning one,
+never registers a Registry Project: a discovered child is an unregistered
+candidate until `projmux create project --root <path>` or opening it once from the
+Projects sidebar registers that exact path. See
+[upgrading.md](upgrading.md#discovery-no-longer-registers-projects).
 
-Project open exposes reusable restore choices as named snapshots. Older
-checkouts may already have named snapshots in the legacy storage directory:
+## Project pins
+
+Pins are presentation preferences, stored typed:
+
+```text
+~/.config/projmux/pins
+```
+
+```text
+projmux-pins v2
+project proj-kwo4qozry2sr2ycij2g45zyvam
+candidate /home/dev/src/scratch
+```
+
+A `project` pin references a Registry Project uid, so its displayed root and name
+come from the Registry and the pin survives a rebind, a rename, and a missing
+root. A `candidate` pin references a path no Project claims. Neither kind is a
+discovery source and neither is managed identity.
+
+`projmux pin project list [--kind project|candidate]` prints both collections with
+their kind. `pin project add|remove|toggle <dir>` accepts the same directory
+argument it always has and resolves it to a typed pin — exactly one Project with
+that root makes the pin managed, none makes it a candidate, more than one is
+refused — with `uid:<uid>` available to name a Project directly.
+
+A pre-v2 file of bare paths is read without being rewritten and migrated only on
+request with `projmux pin project migrate`; see
+[upgrading.md](upgrading.md#pins-are-typed-and-migrate-on-request) for the
+per-line outcomes and the ambiguity refusal.
+
+## Legacy Project Layout Snapshots
+
+Older checkouts may already have named layout snapshots in the legacy storage
+directory:
 
 ```text
 <project>/.projmux/layouts/<name>.toml
@@ -68,9 +104,9 @@ checkouts may already have named snapshots in the legacy storage directory:
 The project context comes from `PROJMUX_CWD` when set, otherwise projmux walks
 upward from the current directory to the nearest `.projmux` or `.git` marker.
 Files outside that project tree are not discovered. This storage is treated as
-legacy import data for the `Named snapshot` row in Project open. New primary
-user-facing surfaces describe the restore unit as a snapshot, not as a separate
-layout or preset feature.
+legacy import data for explicit conversion and preview. Closed-Project startup
+does not expose legacy snapshot choices; current user-facing surfaces describe
+the restore unit as a snapshot, not as a separate layout or preset feature.
 
 The legacy schema is intentionally close to the session-state snapshot shape:
 
@@ -159,9 +195,12 @@ marker-only edit with a digest-named pre-v2 backup. [docs/keybindings.md](keybin
 table, the upgrade ordering and the downgrade procedure.
 
 This marker is a separate version domain from the CLI resource registry's
-`apiVersion: projmux.io/v1alpha1` / camelCase `schemaVersion: 1` envelope. The
+`apiVersion: projmux.io/v1alpha1` / camelCase `schemaVersion: 2` envelope. The
 two have separate markers, separate backups and separate rollbacks; neither one
-failing affects the other.
+failing affects the other. A successful Registry v1 → v2 migration keeps its
+private repair/loss evidence at `<exact-versioned-backup>.migration-report.json`,
+including that backup's absolute path and SHA-256; failed or repeated passes
+publish no report.
 
 Legacy `prefix = ...` entries still parse during migration so existing files
 do not break. Settings preserves existing prefix entries when rewriting the
@@ -380,6 +419,104 @@ warning with the unsupported value and source.
 Project-local locale override is not part of the runtime policy. Locale is a
 user/global preference in this release.
 
+## Codex app-server health
+
+Settings > AI includes a read-only `Codex control plane` row. It reports one of
+`App Server`, `Hook fallback`, or `Unavailable`, together with the existing
+effective reason. Endpoint readiness, running executable/version, official
+daemon-manager ownership, and remote-control capability are separate closed
+axes. Separate `probe_reason` and `install_capability` fields preserve the
+app-server root cause and bounded PATH/managed-payload topology. Lifecycle
+outcome/reason and sanitized CLI, managed, and running versions remain
+independent. Read-only surfaces report `not-attempted/read-only`.
+`projmux doctor --section integrations` and explicit support reports expose the
+same bounded fields without executable/socket paths, prompts, tokens, process
+output, or response payloads.
+
+There is no app-server source setting or environment override. Authority is a
+capability result, not a preference: Projmux probes the existing local control
+socket through `codex app-server proxy`, reads official manager evidence through
+`codex app-server daemon version`, and reads remote-control state through
+`remoteControl/status/read`, all with short timeouts. An older endpoint that
+does not expose the last method reports `unsupported` on that axis without
+hiding endpoint readiness. Doctor, Settings, and support reports never start or
+otherwise mutate the daemon, configuration, login state, or control socket.
+
+An `external-cli-only` install capability acknowledges that the ordinary CLI
+exists while the canonical managed daemon payload was not observed. It does
+not identify a package manager. Install topology is not manager ownership:
+only the official daemon response's backend field proves a managed process.
+
+The Codex integration has a lifecycle seam for later native features. Only an
+actual native user action may use it. A ready unmanaged, version-skewed, or
+ownership/version-unknown endpoint is refused without mutation and reports the
+shared-client interruption risk plus bounded operator recovery. Only an exact
+missing or connection-refused default control socket is start-eligible. That path invokes the
+official idempotent `codex app-server daemon start` command at most once per
+in-flight process decision, then retries proxy initialization with a bounded
+backoff. Projmux never automatically stops, kills, restarts, adopts, or enables
+remote control on the shared app server.
+
+The default `Codex` row in the provider picker launches immediately through the
+canonical create route. It does not start or probe the app-server, call
+`model/list`, or add `--model` or `model_reasoning_effort`; the Codex process
+therefore keeps its own configured defaults.
+
+The separate `Codex advanced launch` action uses the readiness path to read
+every page of the current app-server `model/list`. Its second picker shows only
+visible models and their advertised reasoning efforts. The display also carries
+the advertised default, supported input modalities, and whether personality is
+supported; the boolean personality capability is not expanded into invented
+personality choices. The selected model and effort are launch-only CLI
+overrides (`--model` and `--config model_reasoning_effort=...`); Projmux never
+writes a Codex configuration file. Each normalized catalog is tied to its live
+connection and negotiated-version epoch. Projmux retains that connection from
+picker render through pre-create validation and refreshes `model/list` before
+building argv, so a disconnect or removed option invalidates the selection. If
+advanced discovery fails, is empty, or comes from an older Codex, that action
+reports the exact unavailable reason and creates nothing; the separate default
+`Codex` row remains available.
+
+Picker chrome and semantic annotations such as default, unspecified modality,
+and personality support use the Projmux message catalog. Model display names,
+effort identifiers, and advertised modality tags remain exact provider data and
+are not translated.
+
+`projmux agent review` starts `review/start` only for a Running Codex Agent whose
+Registry Agent, owned Pane, activation generation, stored thread, and live Pane
+thread all match exactly. Review availability is based on the negotiated
+app-server version for that connection and is confirmed by the method call;
+Codex 0.149 does not advertise a separate review capability bit. Older versions
+or a method-not-found response are reported explicitly as unavailable. The
+initial `review/start` response is projected into Agent interaction lifecycle;
+the lifecycle observer described below owns later app-server terminal events.
+
+A natively created or resumed Codex Agent keeps a content-free lifecycle
+observer on its exact Agent UID, Pane UID/runtime handle, activation generation,
+and thread ID. While its initialized proxy connection and snapshot are current,
+the app server is the only attention authority: active, idle, waiting for input,
+and exact unresolved approval requests project the Agent interaction and badge.
+Only an exact successful `turn/completed` projects response-complete and queues a
+completion notification; failed and interrupted turns become idle. Disconnect
+and thread unload first invalidate the epoch and clear stale attention, then
+enable hook fallback. A reconnect starts a new epoch from `thread/read`; events
+from older epochs or other identities are ignored.
+
+`describe agent` and the Codex Agent event Settings page report the effective
+lifecycle source, a closed reason, and active/pending/inactive epoch status.
+These diagnostics never retain prompts, reasoning, output, approval reasons, or
+diff content. Settings aggregates multiple live Codex Panes as counts and says
+`mixed` when native and fallback authority coexist.
+
+Projmux does not install, bootstrap, restart, stop, or reconfigure the Codex
+daemon, does not stop the shared daemon when Projmux exits, and does not manage
+Codex authentication. There is no custom socket or remote-control setting.
+The semantic approval/completion policy below drives the same badge, queue, and
+desktop intent for both app-server and hook-fallback authority. Existing
+`ai-hook-actions.json` values remain byte-for-byte unchanged and, when an exact
+runtime override exists, take precedence only while hook fallback is current;
+they are never inferred or copied into the semantic policy store.
+
 ## AI Resume Picker
 
 The Agent resume picker lists the most recent
@@ -424,6 +561,19 @@ column (`./`, `./web`, `./api`) so child-directory sessions are easy to tell
 apart. A missing or zero depth is identical to the historical behavior. Settings
 edits write the global config.
 
+Codex uses the local app-server conversation catalog as its primary source.
+Each picker invocation follows opaque `thread/list` cursors to completion with
+explicit `cli`, `vscode`, and `appServer` source kinds, non-archived filtering,
+provider recency ordering, and exact-cwd filtering at depth 0. Wider depth is a
+bounded client-side path-tree filter. Native rows use the exact thread id, the
+provider-owned name (or only a short id when unnamed), git branch, and runtime
+status; prompt preview and transcript turns are never read for titles. If the
+native catalog is unavailable, unsupported, malformed, or returns invalid
+pagination, that invocation discards all native rows and performs one rollout
+fallback. The picker annotates Codex rows with source, confidence, runtime
+status, and a closed fallback reason, so native and rollout rows are never
+silently merged.
+
 Antigravity uses the upstream v1.1.12 current-storage boundary before its
 legacy history fallback. `cache/last_conversations.json` contributes the latest
 UUID mapped to a matching workspace; `cache/conversation_metadata.json`
@@ -439,6 +589,13 @@ is not a disk-picker candidate. When a disk picker selection creates a pane,
 its source is persisted so Session State preview and doctor can report medium
 confidence for DB-validated cache sources or low confidence for legacy history.
 
+Session State saves the exact bound Codex session/thread id before considering
+discovery. An existing bound session id or persisted resume id is replayed
+without an app-server read. Only a thread-only candidate is validated with
+`thread/read` and `includeTurns=false`; this validation is probe-only and never
+starts the shared daemon. Failure retains the persisted id or uses the current
+rollout fallback, and a read response can never substitute a different id.
+
 ## Environment Variables
 
 | Variable | Purpose |
@@ -589,6 +746,21 @@ overrides catalog `action` values during ingest, including known Codex and
 Claude events. It does not change hook installation; `projmux agent integrate`
 continues to use the embedded/local catalog `install` fields.
 
+Codex native lifecycle semantics are stored separately at:
+
+```text
+${XDG_CONFIG_HOME:-$HOME/.config}/projmux/ai-semantic-policies.json
+```
+
+The two closed events are `approval_required` and `response_complete`. Each can
+be `notify` (badge + queue + desktop), `state` (badge only), or `quiet` (no
+badge, queue, or desktop). Settings labels these choices `Notify`, `State only`,
+and `Quiet`. The selected intent applies to both the app-server epoch and hook
+fallback. An explicit raw `PermissionRequest` or `Stop` runtime override takes
+precedence only during hook fallback; catalog defaults do not override this
+semantic store. Saving this file does not infer from, rewrite, or normalize the
+raw hook override file.
+
 Delivery depends on the event handler. Specialized notify handlers, such as
 Codex `PermissionRequest` and `Stop`, can write the in-app notify queue and use
 the configured OS desktop notification path. Known Codex events without a
@@ -699,33 +871,31 @@ override with `inherit`, `on`, and `off`; `inherit` follows the global value,
 while `on` and `off` take precedence. Auto-save only updates the latest
 snapshot. Named snapshots are manual and are never updated by auto-save.
 
-Project open from the Alt-1 sidebar defaults to opening a closed project as its
-`Project topology`, which materializes every Registry Window and Window-owned
-shell Pane of that project before the client moves. The optional `Settings >
-Session State > Sidebar startup picker` toggle enables the native sidebar `Start
-project` step. Rows appear as `Latest snapshot`, named snapshot rows, `Project
-topology`, and `Back`. `Latest snapshot`
-is the snapshot auto-save that changes as auto-save runs; named snapshots are
-fixed snapshots. Rows include saved-at date/time metadata when projmux can
-determine it. `Back` returns to the project list without creating, replaying, or
-opening a session. After the startup mode is selected, project automation trust
-is evaluated if needed. A named snapshot containing a startup `command` must
-authorize the SHA-256 of the exact layout bytes used for parse/restore, even
-when project hooks are disabled or `.projmux/config.toml` is absent. Approval
-continues the selected path and deny/cancel aborts without session create,
-snapshot replay, or startup command. The Alt-1 sidebar opens trust as the shared
-client-scoped `Trust project automation` popup
-instead of inline sidebar rows. The selected open continuation runs in a
-detached tmux job that can close the sidebar before trust without depending on
-the self-closing sidebar process to keep running. Deny/cancel refreshes the
-original sidebar query/selection context with a visible status message. Existing
-sessions switch directly without a startup picker.
+Project open from the Alt-1 sidebar defaults to `Continue project`, which
+materializes the closed Project's current Registry desired state before moving
+the client. The optional `Settings > Session State > Sidebar startup picker`
+toggle enables a native `Start project` step with exactly `Continue project` and
+`Open fresh`. `Open fresh` confirms exact `Window n / Pane n / Agent n` counts
+and conversation-pointer loss, then atomically replaces the old Project graph
+with a new Project UID and a new canonical Window/shell UID pair. Exactly one
+same-root Project claimant remains. Snapshot bytes, the root directory,
+Git/worktree data, and the trust decision remain unchanged. Esc returns to
+Projects with zero writes. After
+the startup mode is selected, project automation trust is evaluated if needed.
+The Alt-1 sidebar opens trust as the shared client-scoped `Trust project
+automation` popup instead of inline sidebar rows. The selected open
+continuation runs in a detached tmux job that can close the sidebar before trust
+without depending on the self-closing sidebar process to keep running.
+Deny/cancel refreshes the original sidebar query/selection context with a
+visible status message. Existing sessions switch directly without a startup
+picker.
 
 Default `projmux shell` no longer opens a startup picker or replays session-state
 snapshots before attach. It still derives the default app session identity and
 startup directory from the current project context when available; otherwise it
-uses the `home` target and home directory. Session-state restore selection is
-limited to the Session State sidebar startup picker.
+uses the `home` target and home directory. Snapshot restore is an explicit CLI
+operation that requires both the source session and the exact target Project;
+it is not a Project-startup choice.
 
 Settings > Session State is global settings only: global auto-save, auto-save
 interval, and storage/retention policy. Settings > Project > Session State
@@ -749,7 +919,8 @@ Manual snapshot actions are available from the CLI:
 projmux get snapshots
 projmux create snapshot
 projmux delete snapshot [--session <name>]
-projmux restore snapshot --dry-run [--session <name>]
+projmux restore snapshot --session <snapshot-session> [--project <ref> | -p <ref>] --dry-run
+projmux restore snapshot --session <snapshot-session> [--project <ref> | -p <ref>] --yes [--client <tmux-client>]
 ```
 
 `status` prints the source label (`autosave`, `layout(<name>)`, or `fresh`), the
@@ -758,8 +929,21 @@ target session. Older snapshots without a source field display as `autosave`.
 `save` captures the current tmux session immediately and intentionally bypasses
 the autosave debounce and disabled-autosave gate; it still requires a current
 tmux session. `delete` removes the target snapshot without an interactive
-confirmation. `restore --dry-run` is preview-only in this release and does not
-create sessions or send tmux commands.
+confirmation. Restore treats the snapshot as desired-state input for one exact
+closed Project, never as a global Registry replacement or tmux replay.
+`--dry-run` prints scoped projection counts with zero writes. `--yes` commits
+that target subtree atomically, runs the ordinary materializer, and performs an
+explicit client handoff last when `--client` is present. Restore never modifies
+or deletes the source snapshot.
+
+Interactive `projmux quit` also offers `Save Project snapshots and quit`. It
+recaptures the latest snapshot for every live Registry-bound Project on the
+exact app server, regardless of the global or Project auto-save toggle, and
+stops the server only after all captures succeed. A partial failure keeps the
+server running and keeps each successful atomic snapshot for inspection or
+retry. Control/Home, ephemeral, unmanaged, conflicted, and sibling-server
+sessions are never promoted into Project snapshots. `Quit without saving`,
+`quit --yes`, and `quit --force` perform no snapshot inventory or store I/O.
 
 ## Decoration Mode
 
@@ -807,7 +991,8 @@ The saved values are `on` or `off` in these files:
 ~/.config/projmux/statusbar-visibility-agent-usage-window-antigravity-weekly
 ```
 
-Missing, empty, and invalid values resolve to the compatibility default `on`;
+Missing, empty, and invalid values resolve to `on` except the Codex `5h`
+window, whose ambient HUD default is `off`; an explicit saved `on` restores it.
 Settings shows whether the effective value came from `saved` or `default` and
 marks an invalid saved value as ignored. Saving a toggle regenerates the app
 and standalone tmux output, and Settings source-reloads the generated app config

package/docs/hooks.md

@@ -239,6 +239,17 @@ notify, including unmanaged hooks/conflict details and the relevant
 hooks-engine events. It reads a single JSON payload from stdin. The embedded
 default install catalog is based on Codex CLI 0.130.0:
 
+For an exact native app-server Agent, this raw hook path is fallback-only. The
+pane is marked `pending` before its lifecycle observer starts; `pending`,
+`provider-control-plane`, and `invalidating` authority suppress every Codex hook
+event before any badge, queue, desktop, or Registry interaction write. Only
+after the native epoch is invalidated may `provider-hook` become current and the
+table below apply. Existing hook installation and runtime overrides are kept
+byte-for-byte. `PermissionRequest` and `Stop` use the same semantic policy as
+native lifecycle events unless an explicit raw runtime override exists; that
+override regains its existing meaning only in fallback. Catalog defaults are
+not semantic overrides.
+
 | Event | Behavior |
 | --- | --- |
 | `PreToolUse` | marks the matched pane hook-active and writes a quiet ingest diagnostic; no notify queue entry is pushed |
@@ -247,7 +258,7 @@ default install catalog is based on Codex CLI 0.130.0:
 | `PostToolUse` | marks the matched pane hook-active and writes a quiet ingest diagnostic; no notify queue entry is pushed |
 | `PreCompact` | marks the matched pane hook-active and writes a quiet ingest diagnostic; no notify queue entry is pushed |
 | `PostCompact` | marks the matched pane hook-active and writes a quiet ingest diagnostic; no notify queue entry is pushed |
-| `SessionStart` | marks the matched pane hook-active and writes a quiet ingest diagnostic; no notify queue entry is pushed |
+| `SessionStart` | marks the matched pane hook-active and writes a quiet ingest diagnostic; for an exact managed initial-task binding it records `pending` startup readiness and opens the separately bounded acknowledgement window, but never acknowledges the task; no notify queue entry is pushed |
 | `Stop` | pushes an info Codex completion row |
 
 Codex hook payload parsing accepts the common fields
@@ -366,7 +377,10 @@ runtime file only changes ingest behavior (`notify`, `state`, or `quiet`);
 `projmux agent integrate codex` still uses the catalog `install` field to decide
 which hooks to write. Runtime overrides also apply to known specialized
 events, so `Stop` or `PermissionRequest` can be made state-only or quiet
-without changing which hook commands are installed. When a known Codex event
+without changing which hook commands are installed while hook fallback is
+current. Without such an explicit override, app-server and hook-fallback
+approval/completion use the same semantic policy described in
+[Configuration](configuration.md#notifications). When a known Codex event
 without a specialized handler, such as `PreToolUse` or `PostToolUse`, is set to
 runtime `notify`, projmux pushes a generic in-app notify row such as
 `PreToolUse · Bash` with agent/category metadata. That generic path is
@@ -437,7 +451,7 @@ default install catalog is based on Claude Code 2.1.140 and represents the
 | `Notification` | pushes a Claude notify row for response-ready, approval-required, or input-ready based on `notification_type` |
 | `UserPromptSubmit` | marks the matched pane hook-active and sets AI state to thinking/busy; no notify queue entry is pushed |
 | `UserPromptExpansion` | marks the matched pane hook-active and writes a quiet ingest diagnostic; no notify queue entry is pushed |
-| `SessionStart` | marks the matched pane hook-active and writes a quiet ingest diagnostic; no notify queue entry is pushed |
+| `SessionStart` | marks the matched pane hook-active and writes a quiet ingest diagnostic; for an exact managed initial-task binding it records `pending` startup readiness and opens the separately bounded acknowledgement window, but never acknowledges the task; no notify queue entry is pushed |
 | `Stop` | pushes a Claude completion row, using the last assistant transcript text when `transcript_path` is readable |
 | `StopFailure` | pushes a critical Claude error row with error type/message metadata when present |
 | `SubagentStart` | marks the matched pane hook-active and writes a quiet ingest diagnostic; no notify queue entry is pushed |

package/docs/install.md

@@ -21,6 +21,11 @@ projmux doctor
 `doctor` performs read-only diagnostics for runtime tools such as `tmux`,
 `git`, and `stty`.
 
+If the npm shim reports `unsupported or incomplete npm install`, or a live
+pre-0.13 app server is missing its logical socket marker, use the canonical
+[Troubleshooting](troubleshooting.md) diagnosis and recovery steps. Doctor is
+read-only; its displayed remediation is never executed automatically.
+
 Provider integrations are opt-in and use the canonical installer spelling:
 
 ```sh
@@ -100,10 +105,15 @@ cd projmux
 make install
 ```
 
-`make install` builds the binary, atomically replaces
-`$(go env GOPATH)/bin/projmux`, runs `projmux config apply`, and reconciles the
-notify queue through `projmux notification reconcile`. Override the destination
-with `INSTALL_DIR=/usr/local/bin`.
+`make install` builds the candidate, uses that candidate to run
+`config apply --bin <install-target>` before publication, atomically replaces
+`$(go env GOPATH)/bin/projmux`, and runs the installed binary's `config apply`
+again as post-publication verification. This ordering migrates a pre-0.13 live
+server's exact logical socket marker before a consumer that requires it becomes
+reachable. A convergence or publication failure is non-zero and prints the
+exact `projmux config apply --socket <name>` recovery. Successful installs then
+reconcile the notify queue through `projmux notification reconcile`. Override
+the destination with `INSTALL_DIR=/usr/local/bin`.
 
 Update source checkouts with the repository workflow:
 
@@ -121,11 +131,14 @@ marked as release-managed:
 export PROJMUX_INSTALLER=github-release
 ```
 
-With that set, `projmux update apply` downloads the latest matching release
-asset, replaces the current executable, and reapplies the live tmux config.
+With that set, `projmux update apply` downloads and verifies the latest matching
+release asset, converges the exact live route before replacement, atomically
+replaces the current executable, and reapplies the live tmux config as
+post-publication verification.
 `--no-apply` skips the live reload only — the new binary still migrates the
 keymap schema and marker-owned provider files, then writes the generated
-config. It does not touch a live tmux bell hook. See
+config. It prints the exact explicit apply required before ordinary mutation
+and does not touch a live tmux bell hook. See
 [Upgrading](upgrading.md#managed-agent-hook-producer-migration).
 
 ## npm Packaging Details
@@ -133,3 +146,6 @@ config. It does not touch a live tmux bell hook. See
 Repository packaging and publish details are maintained in
 [npm Distribution](npm-distribution.md). That document is for maintainers; end
 users should not need it for installation.
+
+For incomplete optional dependencies, Doctor findings, and live app socket
+marker recovery, see [Troubleshooting](troubleshooting.md).

package/docs/keybindings.md

@@ -239,9 +239,9 @@ by different picker surfaces, while conflicts inside one surface are rejected.
 
 | Surface action | Meaning |
 | --- | --- |
-| `Sidebar:KillSession` | Kill the focused existing session |
+| `Sidebar:KillSession` | Stop only the focused Project runtime; preserve its Project UID and desired Window/Pane topology |
 | `Sidebar:PinProject` | Pin or unpin the focused directory |
-| `SessionPopup:KillSession` | Kill the focused session |
+| `SessionPopup:KillSession` | Stop only the focused runtime Session; preserve managed Registry identity and desired topology |
 | `SessionPopup:CyclePreviewWindowPrev` / `SessionPopup:CyclePreviewWindowNext` | Preview windows |
 | `SessionPopup:CyclePreviewPanePrev` / `SessionPopup:CyclePreviewPaneNext` | Preview panes |
 | `NotifySidebar:Ack` / `NotifySidebar:AckGroup` / `NotifySidebar:ClearNonCritical` / `NotifySidebar:ClearAll` | Manage notifications |
@@ -406,7 +406,9 @@ installed yet, and only it knows its own canonical ids.
 
 `--no-apply` suppresses the live tmux reload, not the migration. Installer paths
 still invoke the new binary as `config apply --no-reload` so the schema does not
-fall behind the binary that writes it.
+fall behind the binary that writes it. They omit pre-publication live
+convergence entirely and print the exact explicit `config apply --socket`
+still required before ordinary mutation.
 
 ### Downgrading or rolling back
 

package/docs/legacy-cli-retirement.md

@@ -1,16 +1,21 @@
 # Legacy CLI Retirement Ledger
 
-Phase 2 removed the human-facing compatibility argv below. Those non-AI
-tombstones return exit 2, write no stdout, perform no command or pre-dispatch
-migration side effect, and print their replacement on stderr. Phase 3 removes
-the final hidden `ai` producer dispatcher and catalog node: every `projmux ai
-...` invocation now follows the root unknown-command contract (exit 1, no
-stdout or side effect, and root help plus `unknown command: ai` on stderr).
-The seven removed old internal top-level aliases use the same root contract.
+Phase 2 removed the human-facing compatibility argv below. The mixed roots
+retain only their canonical children: rejected `attach`, `focus`, `pin`, and
+`prune` compatibility shapes return exit 2 with exact replacement guidance and
+no stdout, handler reach, or pre-dispatch migration. The fully removed roots
+`current`, `kill`, `notify`, `sessions`, `session-state`, `tag`, `upgrade`, and
+`usage` are absent from the catalog and handler map, so every argv under them
+uses the ordinary root unknown-command contract (exit 1, no stdout or side
+effect, and root help plus `unknown command: <root>` on stderr).
+
+Phase 3 removed the final hidden `ai` producer dispatcher and catalog node.
+The `ai` root and the seven removed old internal top-level aliases use that same
+unknown-command contract.
 
 | Removed argv | Replacement |
 | --- | --- |
-| `ai split`, `ai picker` | `create agent`, `create pane`, or a provider shortcut |
+| `ai split`, `ai picker` | `create agent`, `create pane`, or a provider shortcut. The `split` handler itself is now gone: the hidden `internal agent-pane launch-default|picker` bridge produces canonical create intents, so `--agent`, `--force-agent`, and `--print-pane-id` have no implementation left. Use `-o pane-id` on a canonical create for the pane handle |
 | `ai settings` | `config edit` |
 | `ai status`, `ai topic`, `ai integrate` | `agent status`, `agent topic`, `agent integrate` |
 | `ai notify [notify] [pane]` | `create notification --text ... --target ...`; translate the old pane/payload because the input and semantics changed |
@@ -84,3 +89,27 @@ The old notify action drove an immediate desktop-notification path from pane
 state; `create notification` creates a queue row and therefore requires an
 explicit `--text` and `--target`. The old reset action cleared transient
 desktop dedupe state, which the public queue commands do not reproduce.
+
+## Post-retirement invariants
+
+This breaking boundary removes only the compatibility argv listed above. It
+does not narrow the canonical resource model that shipped after the retirement
+work began. In particular:
+
+- Resource Project and Window scope keeps the paired `--project` / `-p` and
+  `--window` / `-w` options. Plural Window, Pane, and Agent reads keep
+  `--all-projects` / `-A`.
+- Registry-first startup and explicit reconciliation keep materializing the
+  recorded Project, Window, and Pane topology without adopting a foreign tmux
+  identity.
+- An explicitly selected Offline Window remains canonically deletable from the
+  Registry, cascading through its descendant Agent and Pane records without
+  issuing a tmux `kill-window` for a mirror that does not exist.
+- Root help and `docs/cli.md` remain generated from the current command
+  manifest. They advertise the canonical resource routes and their current
+  scope options, never the retired roots.
+
+These are preservation constraints for the retirement release, not aliases
+for the removed commands. A future change to one of these contracts needs its
+own feature or fix decision and must not be smuggled into compatibility
+cleanup.

package/docs/operational-diagnostics.md

@@ -36,6 +36,14 @@ operation instead of recording nested outcomes. Lifecycle ownership replaces
 the generic top-level `command.outcome`; it never duplicates it. Start/outcome
 append failures are ignored and do not change the command result.
 
+Project lifecycle operator diagnostics also keep plans mutually exclusive:
+`stop`, `close-window`, `delete-project`, and `fresh` are distinct operation
+classes. Startup and unregister failures print the closed action, failing
+stage, old Project UID, and new Project UID (or `-` when absent). These opaque
+UIDs and stage labels are bounded control data; root paths, pane content,
+history, prompts, transcripts, and snapshot contents are never identity or
+intent authority.
+
 Session State mutations use one outcome-only `session-state.outcome` record
 per selected attempt. The closed operations are `session-state.save`,
 `session-state.autosave`, `session-state.restore`, and `session-state.delete`;
@@ -198,6 +206,53 @@ the source. Windows ACL privacy is reported as unverified because `os.FileMode`
 cannot prove it; a separate finding preserves the metadata-only writability
 result, and Doctor does not modify ACLs.
 
+### Registry materialization invariant audit
+
+`projmux doctor --section registry` reports the admission difference between
+what the Registry writer accepts and what activation can rebuild.
+`Registry.Validate` and the materialization planner now share the final-v2
+Window contract. Validation allows a same-Window managed Agent
+`spec.anchorPaneRef` with an empty optional `spec.defaultShellPaneRef`; the
+materializer classifies that shape as convergent and plans an explicit
+`allocate default shell` stage before Window/Agent activation. A repeated
+successful materialization is write-free. The audit remains useful for damaged
+or stale refs, but an intentional offline Agent-only Window is not a finding.
+
+The verdict is the consumer predicate itself, not a maintained list of suspect
+shapes. Every Registry Project is planned through the shipped topology planner
+with no observed sessions, and the refusals that offline plan records *are* the
+difference. Nothing in the audit re-decides which stored topology can be
+materialized, so the section cannot drift away from the route it describes.
+
+The section is read-only in the strongest available sense. The Registry read is
+the zero-write snapshot read, so running diagnostics on a machine that never
+created a Project neither creates nor repairs the state directory, and the tmux
+runner handed to the planner refuses every call instead of reaching a server.
+The audit never writes, repairs, or migrates a Registry; repairing a stored
+topology the materializer cannot build is a separate, explicitly requested
+operation.
+
+Findings use the shared severity/code/remediation/count shape:
+
+| Code | Severity | Meaning |
+| --- | --- | --- |
+| `registry.materialize.audited` | info | `count` is the number of Projects planned. Always emitted. |
+| `registry.materialize.clean` | info | The difference set is empty. Emitted explicitly, and printed without `--verbose`, because a silent clean audit is indistinguishable from a section that never ran. |
+| `registry.materialize.unavailable` | warning | The Registry could not be read; nothing was planned. |
+| `registry.materialize.fatal.<kind>` | error | `count` stored resources of that kind are refused in a way that stops the whole Project from activating. |
+| `registry.materialize.skipped.<kind>` | warning | `count` stored resources of that kind are refused as single items; the Project still opens without them. |
+
+`<kind>` is one of `project`, `window`, `pane`, `agent`, or `other`.
+`fatal` and `skipped` are read off the planner's own refusal split rather than
+re-decided here.
+
+The refusal reasons are the planner's own wording and are rendered only under
+`--verbose`, following the report's rule that path-bearing detail is opt-in: a
+stale-cwd reason quotes a stored absolute path. Those reasons are never
+serialized in any format. The support report therefore carries the same codes,
+kinds, and counts as the text report and no reason wording at all, rather than
+relying on the redaction allowlist to hash a private path out of an archive.
+
 ## Storage and retention
 
 The path is
@@ -227,8 +282,9 @@ arm`, `attention clear`, `attention window`, `internal tmux autosave-session-sta
 to the journal; an error from any of them still records exactly one safe error
 outcome. Explicit user mutations such as `attention toggle` retain their
 state-changing success record. Direct top-level help and explicit preview-only intents (`update
-apply --dry-run`, AI integration dry-runs, and the
-currently preview-only session restore) are also read-only. Doctor is a stricter
+apply --dry-run`, AI integration dry-runs, and snapshot projection restore with
+`--dry-run`) are also read-only. Approved snapshot projection restore is a
+state-changing operation. Doctor is a stricter
 boundary: successes and errors never append to this journal, so diagnostics do
 not make its filesystem contract self-defeating. Support report success and
 errors likewise never append; its strict reader shares the viewer's tolerant