projmux 0.13.0 → 0.14.0

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`,
@@ -215,7 +237,7 @@ 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**:
+- **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.
 
@@ -224,7 +246,7 @@ 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 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
 ```
@@ -237,6 +259,11 @@ 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:
 
@@ -248,9 +275,19 @@ they name `--project` as the fix:
   gone — a `recoverable` runtime is reported, never adopted.
 
 Every create is **detached**: no create moves the client. Use `focus pane` or
-`-o pane-id` when you want to end up in the new pane. Creates run against the
-inherited exact socket inside tmux; outside tmux an explicit `--project` is
-required before anything live is touched.
+`-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
 
@@ -887,10 +924,11 @@ lifetime total; `logs.recent-errors.bounded` means older errors were omitted.
 The probe captures at most 4 KiB, generated config inspection reads at most
 1 MiB, and the journal seam reads at most 5 MiB.
 Symlinks and non-regular inputs are rejected without following or blocking on
-them. On Windows, POSIX mode bits cannot establish ACL privacy, so otherwise
-valid paths report the closed `privacy-unverified` warning rather than a false
-private/insecure classification, followed by a separate metadata-only `ready`
-or `not-writable` finding; Doctor never changes ACLs.
+them. The closed `privacy-unverified` warning stays in the finding schema for
+a path whose privacy cannot be established from its mode bits, but no supported
+platform reports it: Linux and macOS are the only build targets and POSIX mode
+bits are authoritative on both, so a readable path always resolves to a
+private or insecure classification. Doctor never changes permissions.
 
 JSON reports have integer `schema_version: 2`. An unfiltered report retains the
 existing typed `dependencies`, `ai_notify_integrations`,
@@ -1269,6 +1307,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
@@ -1322,6 +1367,17 @@ the resolved `claude`, `codex`, or `agy` executable inside the managed wrapper;
 projmux still sets the context directory, tmux title, AI pane metadata, and
 split layout.
 
+A prompted Codex create — provider `codex` with exactly one non-empty payload
+operand — requires native authority. If the app-server endpoint is not ready or
+attachable, if `--add-dir` roots cannot be negotiated, or if the selector
+resolves several Windows, the create refuses with zero Registry and zero tmux
+mutations instead of silently producing a plain-CLI Agent with no native turn
+control. `--interactive-only` is the one public spelling that asks for that
+plain Agent on purpose; it is Codex-only and equivalent on `create agent
+--provider codex` and the `create codex` shortcut. Empty-prompt creates,
+multi-operand payloads, `agent resume`, Claude, and Antigravity are unaffected.
+See [Codex Native-Required Create Migration](codex-native-required-migration.md).
+
 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
@@ -1722,8 +1778,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
@@ -1812,15 +1868,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`.
 
@@ -1867,12 +1929,23 @@ human configuration work should prefer `config render` and `config apply`.
   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,
-  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.
+- `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