projmux 0.11.0 → 0.12.0

package/docs/agent-workflow.md

@@ -54,6 +54,7 @@
 - `make test`: CLI information architecture v2 Phase 7 Agent create composition: `create agent` and the `codex`/`claude`/`antigravity` shortcuts gain a resource-backed detached route behind the same `--project` dispatch discriminator `create pane` uses, so the `--project`-less invocation stays the byte-identical `ai split` bridge while the canonical route allocates a Window-owned Agent plus its Agent-owned `<agent-name>-pane` managed Pane, reuses the Phase 6 anchor resolution, `--create-window` ensure, operation ledger and rollback, and enforces a new `{create, Agent} = 1..N` fan-out cell that four tests falsify when it is weakened; a matrix covers provider-required refusals on every canonical spelling, shortcut-to-canonical registry-snapshot equivalence, non-reuse against a Window that already owns a running Agent of the same provider (`codex` → `codex-1` → `codex-2`, first Agent's `status.paneRef` untouched), Window-scoped explicit `--name` (legal across two Windows, exit 2 with zero mutations inside one), payload-after-`--` reaching the provider launch but never the Agent or Pane name, all seven shared `-o` modes end to end with `AgentList`/`AgentMetadataList` envelopes for a single result and `-o pane-id` resolving to the managed Pane rather than the anchor, multi-window fan-out hitting each Window's own anchor exactly once, four failure stages each leaving the registry byte-identical with no `Failed` Agent behind, six racers converging on one ensured Window uid under the real on-disk lock with `-race -count=10`, the Settings enabled-agents gate applying to the canonical route as a plain error without promoting `--force-agent`, and a help-honesty audit that runs every advertised `-o` token and every advertised `--flag` of the Agent node and all three shortcuts; the identity projections of the compatibility bridge become exit 2 naming `--project` as the fix instead of exit 1 claiming the composition is unwired.
 - `make test-e2e`: CLI information architecture v2 Phase 7 Agent create against a real tmux server on the same dedicated exact socket under the smoke root, with inherited `TMUX`/`TMUX_PANE` stripped from every call and only the verified `#{socket_path}` killed: a stub provider binary proves the launch actually ran in the created pane with the project root as its cwd, the managed pane carries both the Projmux Pane uid mirror and the `@projmux_ai_managed`/`@projmux_ai_agent` options, the active window and pane are unchanged and the new pane is not active, the `codex` shortcut allocates `codex-1` instead of reusing the first Agent, a `--` payload reaches the provider argv while the name stays `codex-2`, a missing `--provider` and an explicit name collision are each exit 2 with zero stdout and an unchanged registry md5, and the `--project`-less bridge still refuses its identity projections with a message naming `--project`.
 - `make test` / `make test-e2e`: canonical create even-axis parity shares the legacy AI split geometry parser, row/column peer selector, and deterministic remainder distributor across `create pane`, `create agent`, and every provider shortcut; route tests pin split → Window-local geometry read → axis-only resize ordering for explicit/default anchors, right/down placement, fan-out, ensured Windows, one-pane no-op, malformed/unreadable topology, unrelated rows/columns, and silent post-split observation/resize failures with zero false rollback. The shared geometry format carries the materializer's escaped `\037` row separator rather than a raw tab, and a dedicated test pins both that the format holds no raw tab and that a `_`-sanitized row parses as no geometry: tmux 3.5a rewrites a raw tab in list output to `_` while 3.6 emits it verbatim, so the tab spelling parsed every row as a single field and made equalization a silent no-op on 3.5a — the version the e2e image runs. The isolated real-tmux create smoke repeats horizontal and vertical canonical creates to four panes, measures a maximum one-cell size difference, preserves raw pane IDs, Registry mirrors, focus, and an unrelated Window's exact geometry, and retains exact socket-contained cleanup.
+- `make test` / `make test-e2e`: Registry–tmux Phase 6 Agent interaction and launch-readiness coverage pins exact active/explicit Agent topic and semantic-status resolution, Registry-first commit plus exact live projection and public reconcile retry, Offline topic resume mirroring, lifecycle-separated closed interaction kinds with restart/stale/Offline current-`unknown` invalidation, and Agent-owned Pane plus shell-manual-attention Window badge priority without durable glyph/color/aggregate state. Provider hooks coalesce session-ref and semantic observations into one Registry transaction when both occur and never synthesize an Agent for a shell Pane. Initial-prompt create distinguishes `Running` resource creation from bounded provider activation, returns an exact Agent/Pane retry-and-cleanup diagnostic when unconfirmed, and proves prompt non-persistence plus zero pane capture. Provider-neutral `--cwd`/repeatable `--add-dir` validation rejects nonexistent, traversal/symlink escape, unauthorized sibling, duplicate, and provider-unsupported paths before runtime mutation; preserves the Window's Project owner; stores effective Agent/Pane workspace; and forwards only caller-explicit additional roots through Codex/Claude argv. The isolated real-tmux slice uses exact primary/foreign sockets to cover immediate topic/status projection, Offline topic-to-resume mirroring, committed projection failure plus public reconcile retry/no-op, raw title/topic non-identity, foreign-socket containment, and explicit cross-Project workspace with unchanged owner Project. Compatibility `ai topic|status` keeps its stdout/stderr/exit surface while forwarding managed Pane changes through Agent authority, and notify queue acknowledgement/TTL/severity plus shell manual attention remain unchanged.
 - `make docs`: regenerates `docs/cli.md` from the `internal/cli` command manifest through `go run ./internal/tools/gendocs`. The render goes to stdout and is captured through a temp file, so a failed generator cannot truncate the checked-in page. Run it whenever a route, summary, usage synopsis, output mode, or field projection changes; `make test` fails until the checked-in page matches.
 - `make test`: CLI information architecture v2 Phase 8 generated CLI reference: `docs/cli.md` is rendered from the command tree in `internal/cli/catalog.go` -- the same manifest the binary renders `projmux help` from -- and the hand-maintained prose it used to hold moved to `docs/cli-guide.md`, which the generated page, `README.md`, and `README-ko.md` all link. The drift gate compares the checked-in page byte for byte against a fresh render and names `make docs` in its failure, so the CI `Unit Tests` job catches a stale page; a determinism test renders twice and rejects an embedded repository or temp path, which is what makes regeneration on an unchanged tree a guaranteed no-op. Coverage is a two-way diff rather than a count: every public route and sub-route in the tree has a section and every section in the document is a real node, with a non-vacuity guard that both a canonical and a shortcut route exist to cover. The internal boundary is held on the published page as well as in the primary listing -- no hidden route gets a section, and no `Canonical spelling:` line may point at an executable path absent from the manifest. The generator reads the command tree and never `canonical.go`; canonical-only summaries are therefore checked as an explicit divergent set rather than leaking into command help. Advertisement-honesty checks keep registry reads aligned with the outputs their handlers implement and keep restore limited to its shipped dry-run preview contract.
 - `make test`: Agent provider session binding Phase 0 persists a validated provider-discriminated `sessionRef` for Claude, Codex, and Antigravity without coupling lifecycle phase or Pane ownership to conversation identity. Metadata/store tests cover structural refusal, deep clones, pre-field byte-compatible reads, exact provider folding, and durable observation timestamps. `internal/app` drives canonical `internal agent-hook ingest` payloads for all providers against an in-memory Registry and proves correct provider-member population, option preservation, zero-write negative cases, conversation retention after Pane release, and stable `describe agent`, `get agents`, and `agent resume` behavior.
@@ -137,7 +138,7 @@
 - `make test` also covers the Globalization Phase 5 locale settings surface: `PROJMUX_LOCALE` > global `[ui].locale` > `LC_ALL` > `LC_MESSAGES` > `LANG` > `en-US` priority, Settings > Appearance > Language / Locale row/detail visibility, `auto` current-locale/source display, unsupported locale fallback warnings, global config writes, and preserved command/config/env/path literals.
 - `make test` also covers the Globalization Phase 6 governance guard: Go string-literal audit classification for hardcoded Korean candidates, English user-facing candidates, and ignored literal/data/debug examples; no unapproved runtime Korean literals outside catalog/formatter/test fixtures; `en-US` coverage for every embedded default catalog key; and required `ko-KR` coverage for migrated notify, Settings, picker, welcome, update, and help surfaces.
 - `make test` also covers `projmux agent integrate tmux-bell` dry-run/install/remove tmux command planning, managed `alert-bell` hook append/idempotence/removal, preservation of unmanaged bell hooks, and canonical `projmux internal agent-hook ingest bell --pane` queue push/metadata/dedupe behavior for non-AI-managed panes.
-- `make test` also covers upgrade-safe managed ingest producer convergence: fresh Codex/Claude/Antigravity hooks, Antigravity Statusline, and tmux bell writers use `projmux internal agent-hook ingest`; marker-owned 0.10.1 fixtures migrate transactionally while missing and unmanaged providers remain untouched; dry-runs show every target and old→canonical command; repeats perform zero file/tmux mutations; later-provider conflicts preflight before any write; injected Antigravity second-file and tmux Nth-command failures restore original bytes, options, and unrelated hooks; `config apply --no-reload` migrates files without live calls; and normal apply targets the requested exact `-L` socket.
+- `make test` also covers upgrade-safe managed ingest producer convergence: fresh Codex/Claude/Antigravity hooks, Antigravity Statusline, and tmux bell writers use `projmux internal agent-hook ingest`; marker-owned 0.10.1 fixtures migrate transactionally while missing and unmanaged providers remain untouched; dry-runs show every target and old→canonical command; repeats perform zero file/tmux mutations; later-provider conflicts preflight before any write; injected Antigravity second-file and tmux Nth-command failures restore original bytes, options, and unrelated hooks; `config apply --no-reload` migrates files without live calls; and normal apply targets the requested exact `-L` socket. The pinned v0.10.1 GitHub Release post-replace fixture additionally proves that normal update executes exact `tmux apply` against the candidate and converges all four managed files plus the exact bell hook through the hidden current-apply handoff, while old `--no-apply` executes the candidate zero times and requires the documented explicit candidate `config apply --no-reload` split stage; current updater `--no-apply` continues to invoke the new binary automatically.
 - `make test` also covers `projmux diagnostics agent-hook` tail/path rendering and bounded JSONL log trimming for ingest diagnostics.
 - `make test` also covers the Phase 0 operational diagnostics foundation: closed safe-event schema, control/length/home sanitization, lossy stable top-level error messages with dynamic pane/title/body/transcript/config-value exclusion, exhaustive allowlisted top-level/multi-mode command classification including direct-help and explicit dry-run success exclusion with boolean `=false` safeguards, exactly-once state-changing/error outcomes with explicit zero-success/error-one coverage for the six automatic `internal agent-hook ingest`, attention arm/clear/window, session-state autosave, and recent-window record paths plus an explicit-mutation success regression, private permission repair, platform replace-existing bounded complete-record retention, corrupt-tail recovery, OS-owned inter-process lock identity/crash recovery and explicit 200 ms budget, concurrent short-process rotation, common text/JSON/tail/filter reader fixtures, and unchanged top-level runtime/usage/exitCoder output and exit semantics.
 - `make test` also covers Operational diagnostics Phase 2 lifecycle adoption: the maintained explicit-mutation inventory (attach/current/kill/sessions/switch plus session-popup open, window recent, runtime prune, focus session switching, shell open-app, snapshot replay creation, popup-toggle cancel restore, and config apply); session create/attach/switch/kill and `config apply` start/outcome success/error tables; composite create-then-attach and prune-kill-then-attach failure-stage attribution while preserving one outer pair; shared run IDs and no duplicate top-level outcome; best-effort store/write failure injection; closed operation/code pairing; apply typed no-server versus generic runner failure classification; focus success sealing at the actual switch-client boundary; unchanged read-only/hot-path zero-success recording; typed no-write runtime health projection with latest-state and bounded failure-code semantics; Doctor runtime/log typed consumer reuse; and support-report raw socket/path/session/window/pane/name negative fixtures. `make test-integration` additionally runs real create/attach/switch/kill success/failure routing against a run-unique `-L` socket, validates exact lifecycle pairs and apply classifications without raw routing, and guards cleanup with the queried actual socket path beneath the run-unique smoke root.
@@ -179,7 +180,7 @@
 - Shell focused unit coverage includes `projmux shell` routing to `tmux -L projmux -f <generated config> new-session -A -s <session> [-c <cwd>]`, generated tmux config callbacks, native key-broker platform policy, runtime overrides, and nested-socket guards.
 - `make test` also covers npm retire/staging path canonicalization for the resolved projmux executable so generated tmux config and hooks never embed a `node_modules/.projmux-<hash>` directory, plus error-suppressed attention and rebalance-panes hooks.
 - `make test` also covers the public config spelling: `projmux config edit [--get|--set <mode>]`, `config render standalone|app`, and `config apply` forward raw argv to their manual leaf handlers; flags, unknown tokens, streams, handler errors, and side effects stay on those handlers. `make install` and every update path emit `projmux config apply`, while generated plumbing uses only the hidden `internal` namespace.
-- `make test` also covers Legacy CLI retirement Phase 2: the exact removed-public argv matrix returns action-aware replacement guidance with stdout/handler/pre-dispatch mutation zero; `attach project`, `focus project|window|pane`, `pin project`, and `prune project|snapshot` remain exact raw-argv forwards; removed pre-namespace internal tokens have no catalog or top-level handler and use root unknown-command exit 1. The hidden producer compatibility gate admits only the exact byte allowlist recorded in the retirement ledger; missing/future/custom events, different flag order, extras, the removed detailed-log route, and every other legacy AI argv are denied before handler reach, stdout, or migration. The maintained-doc scan rejects executable recommendations for every retired route outside explicit retirement/upgrading/historical records. Catalog/canonical/handler two-way audits, root/command-tree/reference goldens, the exact retired route set, preserved Shortcut/kind aliases, and generated producer scans close the topology and drift contracts.
+- `make test` also covers Legacy CLI retirement Phase 2/3: the remaining removed-public argv matrix returns exact replacement guidance with stdout/handler/pre-dispatch mutation zero; `attach project`, `focus project|window|pane`, `pin project`, and `prune project|snapshot` remain exact raw-argv forwards; removed pre-namespace internal tokens and the final `ai` root have no catalog or top-level handler and use root unknown-command exit 1 for every argv. Canonical `internal agent-hook ingest` forwards all provider event shapes to the unchanged handler, while stale unmanaged legacy-hook fixtures remain byte-preserved and require the documented manual canonical-prefix remediation. The repository literal audit permits the retired producer spelling only in test fixtures and explicit retirement/upgrade history. Maintained-doc scans, catalog/canonical/handler two-way audits, root/command-tree/reference goldens, the exact retired route set, preserved Shortcut/kind aliases, and generated producer scans close the topology and drift contracts.
 - `make test` also covers the canonical manifest honesty audit: every canonical spelling resolves to a full executable path in the command tree, no canonical summary carries forward-looking vocabulary or any adjudicated-and-retired string, the two remaining target-state summaries (`delete pane`, `restore snapshot`) are pinned verbatim with a named owning track and must stay absent from every command-tree node, and the separate shortcut gaps are enumerated as a two-way diff so a future change cannot drop a mapping unadjudicated; config and workflow routes are also asserted to have no cardinality-matrix row because they resolve no resource set.
 - `make test` also covers singular and plural kind spellings on the four resource verbs: `Route.Aliases` in `internal/cli/catalog.go` is the single declaration, `cli.CanonicalChildToken` normalizes an alias to its canonical token before `get`/`describe`/`delete`/`rename` dispatch, and the unknown-kind refusals are rendered from `cli.ChildSpellings` so an accepted spelling can never be missing from the list they print. `TestKindSpellingAliasesAreByteIdenticalToTheCanonicalSpelling` runs all 17 canonical/alias pairs -- including the two forwarded parity kinds per verb, whose forwarded argv is compared as well -- and requires identical stdout, identical stderr, and an identical error, with the canonical run required to succeed so an all-failing pair cannot satisfy byte-equality vacuously; `TestEveryManifestKindHasAParityCase` derives the matrix from the manifest so a kind added later cannot escape coverage, and `TestKindSpellingAliasesNeverReachAnotherRoute` proves each singular `get` alias answers its own inventory and is distinguishable from every sibling kind. On the manifest side `TestCanonicalKindSpellingsSurviveTheAliasContract` pins the canonical kind token of every resource-verb child so an alias can never replace a shipped spelling, `TestNoChildAliasShadowsACanonicalSpelling` walks the whole tree for alias/name collisions and duplicate aliases, and `TestResourceVerbsAcceptBothFormsOfEveryKind` asserts zero missing singular/plural combinations with `get pane`/`get panes` as the one enumerated divergent pair. That exception is the product decision the track recorded and is held by `TestGetPaneKeepsItsOwnRouteUnderBothSpellings` and `TestGetPaneSpellingIsUnchanged`: `get pane` stays the exact-one Pane read that owns `--current -o cwd`, `get panes` stays the 0..N inventory, and neither aliases onto the other. `rename` no longer special-cases the `agent` token by hand -- the manifest has no Agent child, so `agent` and `agents` both reach the ordinary refusal.
 - `make test-integration` / `make test-e2e` / `make test-install-smoke`: suite containers still run with `--network none`, so `scripts/test-docker-run.sh` prefetches the checked-in module graph once per `go.sum` into a host-side Go module cache outside the repository and mounts it into the isolated run; `test/lib/smoke.sh` honors that inherited `GOMODCACHE` instead of forcing an empty run-local one.

package/docs/cli-guide.md

@@ -153,6 +153,66 @@ already committed, and names the same public reconcile route as the retry. A
 valid unique Project UID wins over the old path after rebind; unknown and
 duplicate UID claims remain fail-closed.
 
+### Agent topic, interaction, activation, and workspace
+
+`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
+separate semantic field with the closed values `unknown`, `idle`,
+`in_progress`, `approval_required`, `input_required`, and
+`response_complete`; it never changes the Agent lifecycle
+`Pending`/`Running`/`Offline`/`Failed`. Offline, Failed, unbound, and stale
+observations read as current `unknown`, so a completed badge cannot survive as
+current state after its Pane is gone.
+
+`agent status set` always records the closed `manual` source; there is no public
+free-form source flag. Compatibility `ai status` and provider hooks forward to
+the same Agent authority with the closed `compatibility-ai` and `provider-hook`
+sources. Registries written before this field existed may still be read with an
+empty source, but new mutations cannot persist arbitrary prompt, credential, or
+operator text as provenance.
+
+For a Running Agent, the exact pane's topic and
+`@projmux_ai_state`/`@projmux_ai_badge_kind`/`@projmux_attention_state` are live
+projections of Registry authority. A failed exact write exits nonzero after the
+Registry commit and names `projmux reconcile resources` as the retry. An
+Offline topic stays stored and is projected when `agent resume` creates the new
+managed Pane. Window badges remain derived presentation: Agent semantic badges
+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.
+
+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
+Claude accept additional writable roots. These flags change the Agent's
+effective launch workspace, not the Window's owning Project. The Agent stores
+the effective cwd and exact caller-provided additional roots, while its managed
+Pane stores the effective cwd. Provider argv translation (`-C`/`--add-dir`) is
+an implementation detail rather than roadmap prompt knowledge.
+
+The default owner Project root is subject to the same existing-directory and
+canonical-path validation before create performs any Registry or tmux mutation.
+Resume revalidates the persisted workspace against the current registered-root
+and provider rules before creating a Pane. A pre-workspace Agent projects its
+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
+activation cannot be confirmed, the command exits nonzero while naming the
+exact Agent UID and Pane plus safe provider retry and `delete agent ... --yes`
+cleanup options. The live resources remain explicit and retryable rather than
+being reported as an ordinary success.
+
+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
+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.
+
 ### When the active target is not a Projmux resource
 
 A pane created outside the registry-backed routes carries no
@@ -244,7 +304,7 @@ hook payload, or a `make install` log.
 | `internal statusbar` | Status bar click and shortcut dispatch (`click`, `usage-refresh`). |
 | `internal preview` | Persisted preview cursor (`cycle-pane`, `cycle-window`, `select`). |
 | `internal session-popup` | Session popup preview/open and popup cursor movement. |
-| `internal agent-hook` | Provider hook ingest (`ingest`) and the Agent pane title watcher (`watch-title`). |
+| `internal agent-hook` | Provider hook ingest (`ingest`) and the legacy non-resource pane title watcher (`watch-title`). |
 | `internal focus` | Machine focus ingress used by statusbar and notification-sidebar actions. |
 | `internal key-broker` | Darwin physical key transport. |
 | `internal popup-wait-key` | Single-key reader that closes a display-only popup. |

package/docs/cli.md

@@ -61,8 +61,9 @@ projmux <command> [args...]
 Manage Agent state, topic, integrations, and account usage
 
 ```
-projmux agent status [set <state> [pane]]
-projmux agent topic [set|clear] ...
+projmux agent status [get [<agent-ref>] | set <unknown|idle|in_progress|approval_required|input_required|response_complete> [<agent-ref>]] [--agent <ref>]
+projmux agent topic get|clear [<agent-ref>] [--agent <ref>]
+projmux agent topic set <text> [<agent-ref>] [--agent <ref>]
 projmux agent resume <ref> [--project <ref>] [--window <ref>]...
 projmux agent integrate <provider> [--dry-run]
 projmux agent usage [--model <name>] [--window <name>] [--json] [--force]
@@ -72,8 +73,8 @@ Subcommands:
 
 | Route | Summary |
 | --- | --- |
-| [`projmux agent status`](#projmux-agent-status) | Read or set the Agent status state |
-| [`projmux agent topic`](#projmux-agent-topic) | Read, set, or clear the Agent topic annotation |
+| [`projmux agent status`](#projmux-agent-status) | Read or set semantic Agent interaction independently of lifecycle |
+| [`projmux agent topic`](#projmux-agent-topic) | Read, set, or clear one exact Agent topic annotation |
 | [`projmux agent resume`](#projmux-agent-resume) | Rebind an Offline or Failed Agent to a new managed Pane |
 | [`projmux agent integrate`](#projmux-agent-integrate) | Install or remove provider hook integrations |
 | [`projmux agent usage`](#projmux-agent-usage) | Read provider account usage quota snapshots |
@@ -82,18 +83,19 @@ Canonical spelling: `projmux agent status`, `projmux agent topic`, `projmux agen
 
 ### `projmux agent status`
 
-Read or set the Agent status state
+Read or set semantic Agent interaction independently of lifecycle
 
 ```
-projmux agent status [set <state> [pane]]
+projmux agent status [get [<agent-ref>] | set <unknown|idle|in_progress|approval_required|input_required|response_complete> [<agent-ref>]] [--agent <ref>]
 ```
 
 ### `projmux agent topic`
 
-Read, set, or clear the Agent topic annotation
+Read, set, or clear one exact Agent topic annotation
 
 ```
-projmux agent topic [set|clear] ...
+projmux agent topic get|clear [<agent-ref>] [--agent <ref>]
+projmux agent topic set <text> [<agent-ref>] [--agent <ref>]
 ```
 
 ### `projmux agent resume`
@@ -283,8 +285,8 @@ Create Projmux resources
 ```
 projmux create window --project <ref> [--name <name>] [--label key=value]... [-o <mode>] [-- <payload>]
 projmux create pane --project <ref> [--window <ref>]... [--pane <ref>]... [--create-window] [--placement right|down] [-o <mode>] [-- <payload>]
-projmux create agent --provider <provider> --project <ref> [--window <ref>]... [--pane <ref>]... [--create-window] [--placement right|down] [-o <mode>] [-- <payload>]
-projmux create codex|claude|antigravity --project <ref> [--window <ref>]... [--create-window] [--placement right|down] [-o <mode>] [-- <payload>]
+projmux create agent --provider <provider> --project <ref> [--cwd <path>] [--add-dir <path>]... [--window <ref>]... [--pane <ref>]... [--create-window] [--placement right|down] [-o <mode>] [-- <payload>]
+projmux create codex|claude|antigravity --project <ref> [--cwd <path>] [--add-dir <path>]... [--window <ref>]... [--create-window] [--placement right|down] [-o <mode>] [-- <payload>]
 projmux create notification --text <s> --target <SESSION[:WINDOW[.PANE]]> [--socket <s>]
 projmux create snapshot
 ```
@@ -335,7 +337,7 @@ Output modes (`-o`): `uid`, `name`, `ref`, `metadata`, `json`, `pane-id`, `none`
 Create an Agent and its managed Pane; --provider is required, and --project splits the resolved Windows detached
 
 ```
-projmux create agent --provider <provider> --project <ref> [--window <ref>]... [--pane <ref>]... [--selector key=value]... [--create-window] [--name <name>] [--label key=value]... [--placement right|down] [-o <mode>] [-- <payload>]
+projmux create agent --provider <provider> --project <ref> [--cwd <path>] [--add-dir <path>]... [--window <ref>]... [--pane <ref>]... [--selector key=value]... [--create-window] [--name <name>] [--label key=value]... [--placement right|down] [-o <mode>] [-- <payload>]
 projmux create agent --provider <provider> [--placement right|down] [-o pane-id|none] [-- <payload>]
 ```
 
@@ -362,7 +364,7 @@ projmux create snapshot
 Provider shortcut for create agent --provider codex
 
 ```
-projmux create codex --project <ref> [--window <ref>]... [--pane <ref>]... [--selector key=value]... [--create-window] [--name <name>] [--label key=value]... [--placement right|down] [-o <mode>] [-- <payload>]
+projmux create codex --project <ref> [--cwd <path>] [--add-dir <path>]... [--window <ref>]... [--pane <ref>]... [--selector key=value]... [--create-window] [--name <name>] [--label key=value]... [--placement right|down] [-o <mode>] [-- <payload>]
 projmux create codex [--placement right|down] [-o pane-id|none] [-- <payload>]
 ```
 
@@ -373,7 +375,7 @@ Output modes (`-o`): `uid`, `name`, `ref`, `metadata`, `json`, `pane-id`, `none`
 Provider shortcut for create agent --provider claude
 
 ```
-projmux create claude --project <ref> [--window <ref>]... [--pane <ref>]... [--selector key=value]... [--create-window] [--name <name>] [--label key=value]... [--placement right|down] [-o <mode>] [-- <payload>]
+projmux create claude --project <ref> [--cwd <path>] [--add-dir <path>]... [--window <ref>]... [--pane <ref>]... [--selector key=value]... [--create-window] [--name <name>] [--label key=value]... [--placement right|down] [-o <mode>] [-- <payload>]
 projmux create claude [--placement right|down] [-o pane-id|none] [-- <payload>]
 ```
 
@@ -384,7 +386,7 @@ Output modes (`-o`): `uid`, `name`, `ref`, `metadata`, `json`, `pane-id`, `none`
 Provider shortcut for create agent --provider antigravity
 
 ```
-projmux create antigravity --project <ref> [--window <ref>]... [--pane <ref>]... [--selector key=value]... [--create-window] [--name <name>] [--label key=value]... [--placement right|down] [-o <mode>] [-- <payload>]
+projmux create antigravity --project <ref> [--cwd <path>] [--add-dir <path>]... [--window <ref>]... [--pane <ref>]... [--selector key=value]... [--create-window] [--name <name>] [--label key=value]... [--placement right|down] [-o <mode>] [-- <payload>]
 projmux create antigravity [--placement right|down] [-o pane-id|none] [-- <payload>]
 ```
 

package/docs/legacy-cli-retirement.md

@@ -1,11 +1,12 @@
 # Legacy CLI Retirement Ledger
 
-Phase 2 is a breaking CLI release. Removed human-facing compatibility argv
-returns exit 2, writes no stdout, performs no command or pre-dispatch migration
-side effect, and prints the replacement below on stderr. The seven removed old
-internal top-level aliases instead follow the root unknown-command contract:
-exit 1, no stdout or side effect, and root help plus `unknown command: <token>`
-on stderr.
+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.
 
 | Removed argv | Replacement |
 | --- | --- |
@@ -37,25 +38,46 @@ routes `doctor`, `quit`, `resources`, `settings`, `shell`, `switch`, and
 
 The removed pre-namespace internal aliases are `key-broker`, `popup-wait-key`,
 `preview`, `session-popup`, `status`, `statusbar`, and `tmux`. Their only
-remaining entrypoints are the corresponding `internal ...` routes. Public
-configuration work uses `config render` and `config apply`.
+remaining entrypoints are the corresponding `internal ...` routes, subject to
+the exact updater handoff exception below. Public configuration work uses
+`config render` and `config apply`.
 
-## Internal migration exception
+## Updater handoff exception
 
-Phase 2 intentionally retains one hidden compatibility dispatcher until the
-next release gate: exact old managed-producer argv only. The accepted bytes are
+The immutable v0.10.1 GitHub Release updater replaces its own executable and
+then invokes the replacement with exact argv `tmux apply`. The replacement
+accepts only those two tokens as a hidden handoff and routes them through the
+current `config apply` convergence path. Exit status, stdout, stderr, managed
+producer migration, generated-config writes, rollback, and live tmux mutation
+are therefore the current apply contract rather than a second implementation.
+
+This exception does not restore a `tmux` catalog node or top-level handler and
+is absent from root help and generated CLI documentation. Bare `tmux`, every
+other old tmux subcommand, and `tmux apply` with any extra argv still use the
+removed-root contract: exit 1, no stdout or side effect, and root help plus
+`unknown command: tmux` on stderr.
+
+## Final ingest compatibility removal
+
+Phase 2 temporarily retained one hidden compatibility dispatcher for exact old
+managed-producer argv. The accepted historical bytes were
 `ai ingest codex-hook`, `ai ingest claude-hook`, `ai ingest antigravity-hook
 --event <event>` where `<event>` is exactly `PreInvocation`, `PostInvocation`,
 `PostToolUse`, `Stop`, or `Statusline`, and `ai ingest bell --pane <pane-id>`.
-The flag order is fixed and no extra argv is accepted. Human and machine callers
-with identical argv cannot be distinguished.
+The v0.11.1 `R_migrate` release migrated marker-owned Codex, Claude,
+Antigravity/Statusline, and tmux-bell producers to `internal agent-hook ingest`
+before this dispatcher was removed. The old bytes are now history, not an
+executable alias; every `ai` argv is rejected at the root before stdin, tmux,
+diagnostics, or automatic migration is touched.
 
-Every other `ai` argv, including `ai ingest log`, a missing/future/custom
-Antigravity event, reordered flags, or extra argv, returns the public retirement
-usage error before stdin, tmux, diagnostics, or stdout is touched. Managed
-producers already emit `internal agent-hook ingest`; this exception exists only
-for the binary-replacement-before-migration window. Do not remove it until the
-post-release `R_migrate` evidence gate is closed.
+A markerless or otherwise unmanaged hook is intentionally never rewritten.
+If one still invokes the old spelling, decide that the hook is yours, preserve
+its provider arguments, redirection, and fallback, and manually replace only
+the command prefix with `projmux internal agent-hook ingest`. For example, the
+historical `projmux ai ingest claude-hook` prefix becomes `projmux internal
+agent-hook ingest claude-hook`. Run `projmux agent integrate <provider>
+--dry-run` afterward; a remaining conflict must be resolved by the owner, not
+by projmux taking ownership of the entry.
 
 The `ai notify` split is intentional parity guidance, not an alias mapping.
 The old notify action drove an immediate desktop-notification path from pane

package/docs/upgrading.md

@@ -73,12 +73,14 @@ Statusline, and the tmux bell fallback with the canonical
 `projmux internal agent-hook ingest ...` entrypoint. Copyable integration
 commands use `projmux agent integrate <provider>`.
 
-Update ordering is hook-first and lossless: the new binary is atomically
-installed while the exact old managed-producer argv described in the ledger's
-internal migration note still dispatches to the same handler; the new binary then migrates every
-marker-owned producer; only after that does it generate and apply tmux config.
-An old managed hook that fires between binary replacement and migration is
-therefore handled before its command is rewritten.
+The v0.11.1 migration release used hook-first ordering: the new binary was
+atomically installed while the exact old managed-producer argv described in the
+ledger still dispatched to the same handler; it then migrated every
+marker-owned producer before generating and applying tmux config. Phase 3's
+next breaking release removes that temporary dispatcher after the public
+fresh/upgrade/`--no-apply` migration evidence gate. Upgrade an old installation
+through v0.11.1 before the next release when you need the migration-window
+event guarantee.
 
 Migration is ownership- and transaction-aware. Codex managed blocks and the
 Claude, Antigravity, Statusline, and tmux-bell markers are the only ownership
@@ -104,11 +106,44 @@ files, but they neither inspect nor modify a live tmux server. A later normal
 `projmux config apply --socket <name>` converges a marker-owned bell hook only on
 that exact `-L <name>` socket.
 
+**Upgrading directly from v0.10.1:** its GitHub Release updater predates the
+current post-update argv. A normal
+`PROJMUX_INSTALLER=github-release projmux update apply` replaces the executable
+and then calls exact legacy `tmux apply`; the replacement accepts that hidden
+handoff and performs the same managed-producer migration, generated-config
+write, and live reload as current `config apply`. The old route is not restored
+in help or the command catalog, and no other `tmux` argv is accepted.
+
+The v0.10.1 updater's own `--no-apply` behavior is historically different: it
+returns immediately after binary replacement and never executes the new
+binary. Treat that invocation as replace-only, verify that the executable is
+the intended new version, and then run the replacement explicitly:
+
+```sh
+PROJMUX_INSTALLER=github-release projmux update apply --no-apply
+projmux version
+projmux config apply --no-reload
+```
+
+The explicit last step migrates marker-owned provider files and writes the
+generated config without inspecting or mutating live tmux. This split-stage
+recovery applies only when the command that started the update was v0.10.1;
+current `update apply --no-apply` already executes the new binary's
+`config apply --no-reload` automatically.
+
 If a conflict is reported, keep the unmanaged entry unchanged while deciding
 which tool owns it; remove or rewrite it manually only after that decision,
 then rerun the dry-run and installer. A failed transaction is safe to retry
 because it restores its starting state.
 
+**Stale unmanaged legacy hooks after the final removal:** projmux does not take
+ownership of markerless hooks and does not rewrite them automatically. Such a
+hook now fails with `unknown command: ai`. After confirming that you own the
+entry, preserve its provider/event arguments, redirection, and fallback and
+manually replace the old `projmux ai ingest` prefix with `projmux internal
+agent-hook ingest`. Then run `projmux agent integrate <provider> --dry-run` and
+resolve any reported ownership conflict before installing a managed entry.
+
 **Downgrading to 0.10.1 or older:** those binaries do not expose the canonical
 internal ingress. Before replacing the current binary, remove each managed
 integration with `projmux agent integrate <provider> --remove`. After the old

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "projmux",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "tmux project session manager",
   "license": "MIT",
   "homepage": "https://github.com/crevissepartners/projmux#readme",
@@ -28,9 +28,9 @@
     "package:npm:pack": "scripts/package-npm.sh --pack"
   },
   "optionalDependencies": {
-    "@projmux/linux-x64": "0.11.0",
-    "@projmux/linux-arm64": "0.11.0",
-    "@projmux/darwin-x64": "0.11.0",
-    "@projmux/darwin-arm64": "0.11.0"
+    "@projmux/linux-x64": "0.12.0",
+    "@projmux/linux-arm64": "0.12.0",
+    "@projmux/darwin-x64": "0.12.0",
+    "@projmux/darwin-arm64": "0.12.0"
   }
 }