projmux 0.11.1 → 0.12.0

package/docs/agent-workflow.md

@@ -180,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/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 |
 | --- | --- |
@@ -56,22 +57,27 @@ 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.
 
-## Internal migration exception
+## Final ingest compatibility removal
 
-Phase 2 intentionally retains one hidden compatibility dispatcher until the
-next release gate: exact old managed-producer argv only. The accepted bytes are
+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
@@ -134,6 +136,14 @@ 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.1",
+  "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.1",
-    "@projmux/linux-arm64": "0.11.1",
-    "@projmux/darwin-x64": "0.11.1",
-    "@projmux/darwin-arm64": "0.11.1"
+    "@projmux/linux-x64": "0.12.0",
+    "@projmux/linux-arm64": "0.12.0",
+    "@projmux/darwin-x64": "0.12.0",
+    "@projmux/darwin-arm64": "0.12.0"
   }
 }