projmux 0.13.0 → 0.14.0

package/docs/codex-native-required-migration.md

@@ -0,0 +1,175 @@
+# Codex Native-Required Create Migration (0.14.0)
+
+0.14.0 makes native authority a requirement for a *prompted* managed Codex
+create instead of something projmux attempts and silently gives up on. Where an
+earlier release would quietly hand back a plain-CLI Codex Agent — one that looks
+managed, carries no app-server thread binding, and answers no native turn
+control — the create now refuses at the provider-mutation boundary and names the
+one explicit way to ask for that plain Agent.
+
+This note covers only that change. For update mechanics by installer type see
+[Upgrading](upgrading.md); for endpoint readiness diagnosis see
+[Troubleshooting](troubleshooting.md#codex-app-server-install-topology).
+
+## There is nothing to migrate
+
+Upgrading is the whole migration. Every existing resource keeps working as it
+is:
+
+| Surface | Change in 0.14.0 |
+| --- | --- |
+| Registry schema | none — `internal/core/metadata` is byte-identical across the release range |
+| Existing Agents and Panes | none — no stored field is added, read differently, or backfilled |
+| Configuration files | none — no key added, renamed, or removed |
+| Post-create and Agent hook contract | none — no `PROJMUX_*` env var added, renamed, or removed, and no payload schema change |
+
+No command has to be run before or after the upgrade for this change. What
+changes is the answer a *new* prompted Codex create gives when native authority
+cannot be proven.
+
+## The shape that is now gated
+
+Exactly one create shape is native-required. All five conditions must hold:
+
+- provider is `codex`, and
+- the payload is exactly one operand, and
+- that operand is non-empty, and
+- `--interactive-only` is not passed, and
+- the create is not carrying a capability selection from the split-UI picker.
+
+Anything outside that shape keeps its previous behavior unchanged. The closed
+outcome table lives in `internal/app/codex_native_thread.go`
+(`codexNativeLaunchOutcomeTable`) and is pinned by
+`TestCodexNativeLaunchOutcomeTableIsClosed`.
+
+## Calls that now refuse
+
+### 1. Prompted create against an endpoint that is not ready or not attachable
+
+```sh
+projmux create codex -- "review the diff"
+projmux create agent --provider codex -- "review the diff"
+```
+
+Before: native thread preparation failed as a safe fallback and the create
+silently continued on the plain CLI lane, producing a managed Agent with no
+native binding.
+
+Now: the create refuses before the split, before the hook probe, and before the
+Registry commit. Zero threads, zero Panes, zero Registry writes, zero tmux
+objects. The refusal carries the typed reason from the endpoint (for example
+`daemon-not-running`) and names `--interactive-only`. Exit code 1.
+
+Fix it by making the app-server endpoint available — start with
+`projmux doctor --section integrations --verbose` — or ask for the plain lane on
+purpose with `--interactive-only`.
+
+### 2. Prompted create with `--add-dir` against an endpoint that cannot negotiate roots
+
+```sh
+projmux create codex --add-dir /path/to/other-root -- "review the diff"
+```
+
+Additional writable roots travel on the upstream experimental API. Before, the
+create connection never negotiated that capability, so roots always failed the
+request; that failure was classified as a safe fallback and the create silently
+dropped to the plain CLI lane.
+
+Now a rooted create negotiates the capability on its own connection and delivers
+the exact cleaned list. An endpoint that cannot answer the negotiated form
+fails closed with reason `additional-writable-roots-unsupported` rather than
+creating an Agent whose writable workspace is narrower than what was asked for.
+Exit code 1.
+
+A create with no `--add-dir` keeps the plain, non-negotiated connection exactly
+as before.
+
+### 3. Prompted create whose selector resolves several Windows
+
+```sh
+projmux create codex --window main --window side -- "review the diff"
+```
+
+One create owns exactly one native thread, and a Registry rollback cannot delete
+an app-server thread, so a prompted native fan-out has no atomic shape. Before,
+every target dropped to the plain CLI lane. Now the fan-out is refused before
+the first allocation, as a usage error (exit code 2) naming how many Windows the
+selector resolved.
+
+Narrow the selector to one Window, or pass `--interactive-only` to keep the
+previous one-Agent-per-Window cardinality.
+
+### 4. Resume picker: selecting an app-server-sourced Codex row
+
+This is the split-UI resume picker (`Alt-7` / the resume selection surface), not
+the `projmux agent resume` command.
+
+When the picker's Codex rows come from a healthy app-server, selecting one of
+those native rows resumes that exact thread through the native lane. Before, a
+failed native resume preparation silently rebound the selection onto the rollout
+CLI lane — it reported a resume while answering no native turn control. Now it
+refuses. Exit code 1.
+
+There is no `--interactive-only` escape hatch here: the operator picked an
+existing conversation, not a launch mode. Rows that came from the rollout scan
+rather than the app-server are unaffected and keep the current CLI lane.
+
+## The escape hatch: `--interactive-only`
+
+`--interactive-only` is the only public spelling that asks for a plain
+interactive Codex Agent with no native thread binding, and it is the only way to
+reach the plain CLI lane on purpose.
+
+```sh
+projmux create codex --interactive-only -- "interactive task"
+projmux create agent --provider codex --interactive-only -- "interactive task"
+```
+
+- Both spellings are equivalent: identical flag acceptance, identical manifest
+  and rendered help, byte-equal stdout.
+- The native controller is not consulted at all. No thread is created, no native
+  Pane state is bound, and the Agent keeps the existing hook activation contract
+  (`provider-hook`).
+- The payload stays the provider's initial task on the CLI argv, exactly as
+  before.
+- It gives up native turn control for that Agent — start, steer, interrupt, and
+  approval routing through the app-server. That is a deliberate reduced
+  capability, not a defect.
+- It is Codex-only. Passing it to `--provider claude` or `--provider antigravity`,
+  or to the `create claude` / `create antigravity` shortcuts, is a usage error
+  (exit code 2) raised before any transaction opens, so nothing is created.
+- It is a create-time flag and is not stored on the Agent. `projmux agent resume`
+  has no way to tell an interactive-only Agent apart later and does not treat one
+  specially.
+
+## What did not change
+
+| Surface | Behavior |
+| --- | --- |
+| `projmux agent resume` | unchanged. A stored Agent whose native resume cannot be proven keeps its existing safe fallback to one provider resume of the stored conversation. `internal/app/agent_resume.go` has a net diff of zero lines in this release. |
+| Empty-prompt Codex create (`projmux create codex` with no payload) | unchanged byte-for-byte, including argv, hook acknowledgement, output, and late refinement. An empty prompt is not attachable native input, so it was never in the gated shape. |
+| Multi-operand payload (`projmux create codex -- a b`) | unchanged. The legacy CLI owns provider parsing for a multi-operand payload, so it is not a native create candidate and keeps the plain lane. |
+| Claude and Antigravity | unchanged lifecycle, fan-out, and hook activation contract. |
+| Public hook env and payload schema | unchanged. |
+| Post-thread-creation failures | unchanged. A native failure *after* `thread/start` returned still refuses without offering any second lane — including `--interactive-only` — because starting another Codex process could submit the same prompt twice. |
+
+## Verifying this yourself
+
+```sh
+go test ./internal/app/ -run 'TestInteractiveOnlyIsTheOnlyPlainCodexLaneAndBothSpellingsAreEquivalent|TestDefaultNativeCodexFanOutRefusesWithZeroMutationsAndInteractiveOnlyKeepsCardinality|TestEmptyPromptCodexCreateIsByteForByteUnchangedByTheNativeRequiredGate|TestClaudeAndAntigravityLifecycleAndHookContractAreUnchangedByTheNativeGate|TestUnavailableNative|TestCodexNativeLaunchOutcomeTableIsClosed'
+go test ./internal/integrations/agents/codexappserver/ -run TestStartDefaultThread
+```
+
+| Claim in this note | Test |
+| --- | --- |
+| Prompted create refuses instead of silently creating a plain Agent, for both the unavailable-endpoint and unsupported-roots rows | `TestUnavailableNativeCreateRefusesInsteadOfSilentlyCreatingAPlainAgent` |
+| Roots are delivered exactly on a negotiated connection, fail closed otherwise, and stay off the wire when empty | `TestStartDefaultThreadDeliversAdditionalRootsOrFailsClosed` |
+| Prompted fan-out refuses with zero mutations; `--interactive-only` keeps the old cardinality | `TestDefaultNativeCodexFanOutRefusesWithZeroMutationsAndInteractiveOnlyKeepsCardinality` |
+| Picker resume refuses instead of rebinding onto the rollout lane, and offers no launch-mode escape hatch | `TestUnavailableNativePickerResumeRefusesInsteadOfRebindingOntoTheRolloutLane` |
+| `agent resume` keeps its safe fallback to one provider resume | `TestUnavailableNativeResumeKeepsTheStoredConversationOnTheProviderResumeLane` |
+| Both `--interactive-only` spellings are equivalent, and non-Codex providers refuse it at zero transactions | `TestInteractiveOnlyIsTheOnlyPlainCodexLaneAndBothSpellingsAreEquivalent` |
+| Empty-prompt create is unchanged | `TestEmptyPromptCodexCreateIsByteForByteUnchangedByTheNativeRequiredGate` |
+| Claude and Antigravity are unchanged | `TestClaudeAndAntigravityLifecycleAndHookContractAreUnchangedByTheNativeGate` |
+| One payload sends exactly one `turn/start` and never repeats the prompt in Pane argv | `TestPromptedNativeCodexCreateIssuesOneTurnAndNeverRepeatsThePromptInPaneArgv` |
+| The post-mutation row still refuses a second lane | `TestIndeterminateNativeCreateRefusesASecondLaneAndWritesZero` |
+| The outcome table describes exactly these rows and no others | `TestCodexNativeLaunchOutcomeTableIsClosed` |

package/docs/configuration.md

@@ -422,26 +422,40 @@ 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 a closed reason,
-endpoint kind, connection state, lifecycle outcome/reason, and a sanitized
-version when initialization returned one. Read-only surfaces report
-`not-attempted/read-only`. `projmux doctor --section integrations` and explicit
-support reports expose the same bounded fields without socket paths, prompts,
-tokens, process output, or response payloads.
+`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` with a short timeout and otherwise keeps
-the current hook behavior. Doctor, Settings, and support reports never start or
-otherwise mutate the daemon.
+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, and only an exact missing or
-connection-refused default control socket is eligible. That path invokes the
+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. Phase 1 itself does not route Agent create/resume, usage, catalog,
-model, or review behavior through that seam.
+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
@@ -922,6 +936,15 @@ 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
 
 Settings > Appearance controls optional icon decoration per surface:

package/docs/hooks.md

@@ -328,10 +328,31 @@ command = "projmux internal agent-hook ingest codex-hook >/dev/null 2>&1 || true
 ```
 
 Repeated installs are idempotent and preserve unrelated Codex config, including
-unmanaged hook entries for the same events. If projmux sees an unmanaged
-`projmux internal agent-hook ingest codex-hook` command, it refuses to install over it rather
-than guessing ownership. `--dry-run` previews the TOML update. `--remove`
-removes projmux-managed Codex hooks wiring.
+unmanaged hook entries for the same events. If projmux sees a
+`projmux internal agent-hook ingest codex-hook` command it did not author —
+a different matcher, a wrapped command, or an extra key — it refuses to install
+over it rather than guessing ownership. `--dry-run` previews the TOML update.
+`--remove` removes projmux-managed Codex hooks wiring.
+
+The marker block is not a projmux-owned byte range. Projmux owns only the hook
+definitions it wrote and, inside the block, the `[features] hooks = true`
+toggle; everything else in the file belongs to Codex or to you and is handed
+back verbatim. That split is what keeps hook trust alive across convergence:
+Codex records the hooks you approved as `[hooks.state]` subtables holding a
+`trusted_hash`, and it can write them anywhere in the same file, including
+between the projmux markers. Convergence lifts that state back out of the block
+unchanged instead of rewriting the block wholesale, so `projmux agent integrate
+codex`, `projmux config apply`, and the `make install` convergence leave every
+approval you already made in place.
+
+A Codex TOML re-serialization can also drop the marker comments while leaving
+the hook wiring projmux wrote behind. Projmux recognizes that wiring as its own
+and restores the markers around the byte-identical definitions rather than
+refusing, so a marker-less config still converges and keeps its trust. Recovery
+stops where ownership does: hook entries you hand-wrote keep the refusal above,
+and so does any layout where re-adopting the projmux entries would renumber a
+hook entry projmux does not own, because Codex keys trust state by array
+position.
 
 The Codex hooks install list is catalog-driven. Projmux ships an embedded
 default catalog at `internal/app/ai_hook_catalogs/codex.json`, and merges an
@@ -392,7 +413,11 @@ not stored.
 
 Codex may require reviewing or trusting hooks through its `/hooks` flow before
 commands run. Projmux only writes the managed config block; it does not attempt
-to auto-trust hooks.
+to auto-trust hooks. It never computes, copies, moves, or deletes a
+`trusted_hash`, and it never carries an approval from one hook identity to
+another: if a hook's matcher, type, command, or event changes, Codex asks you to
+review that hook again while the other hooks keep the trust you already gave
+them.
 
 ## Tmux Bell Fallback
 

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

@@ -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/npm-distribution.md

@@ -96,6 +96,12 @@ scripts/package-npm.sh \
 This keeps the npm platform binaries byte-for-byte aligned with the GitHub
 Release binaries, including the `darwin && cgo` native key adapter, then
 publishes each staged package with `npm publish --access public`.
+
+The GitHub release itself stays a draft until that npm job succeeds. release-please
+creates the release with `draft` set, `release.yml` uploads archives to the drafted
+release, and only the final `publish-release` job flips it visible. So by the time a
+user can see release `vX.Y.Z`, npm `dist-tags.latest` already resolves to `X.Y.Z`;
+a failed npm publish keeps the release hidden and the workflow red.
 The npm publish job uses GitHub Actions OIDC (`id-token: write`) instead of a
 long-lived `NPM_TOKEN` secret. PR CI runs `make npm-pack` so package staging and
 dry-run packing fail before release.

package/docs/operational-diagnostics.md

@@ -202,9 +202,10 @@ Its captured output is capped at 4 KiB. Doctor reads only a pre-existing
 regular generated config (at most 1 MiB) without following symlinks, and the
 shared read-only journal seam rejects non-regular inputs and files above 5 MiB.
 These conditions degrade to typed findings rather than blocking or repairing
-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.
+the source. The `privacy-unverified` finding remains in the schema for a path
+whose privacy `os.FileMode` cannot prove, but no supported platform emits it:
+Linux and macOS are the only build targets and POSIX mode bits are
+authoritative on both. Doctor does not modify permissions.
 
 ### Registry materialization invariant audit
 
@@ -266,11 +267,9 @@ releases ownership when a process exits, so an orphaned lock path needs no
 path deletion or stale-owner reclamation and cannot race a successor owner.
 Lock acquisition has an explicit 200 ms total budget so this side channel
 cannot materially delay the original command result. When the file exceeds
-5 MiB, a platform-specific atomic replacement retains approximately the
-newest 2 MiB, beginning at a complete valid record; Windows uses replace-
-existing semantics rather than plain rename. A trailing partial record is
-discarded before the next append, and the reader skips malformed or truncated
-records.
+5 MiB, an atomic `rename` replacement retains approximately the newest 2 MiB,
+beginning at a complete valid record. A trailing partial record is discarded
+before the next append, and the reader skips malformed or truncated records.
 
 Classification is intentionally conservative for mutation-capable interactive
 commands: opening session/project/settings/popup flows is treated as changing

package/docs/testing.md

@@ -15,18 +15,39 @@ and humans run the same entrypoints.
   `tmux` server, and notify queue CRUD.
 - `make test-install-smoke` builds the same Docker image and runs
   `test/install/smoke.sh`. It validates `make install`, atomic binary
-  replacement into an isolated install dir, `tmux apply`, and post-install
-  `notify reconcile` initialization with a fresh HOME/XDG state tree.
+  replacement into an isolated install dir, pre-publication marker convergence,
+  concurrent legacy/candidate/installed shell and attach consumers, exact
+  server-generation/session preservation, `tmux apply`, and post-install notify
+  reconcile initialization with a fresh HOME/XDG state tree.
 - `make test-e2e` prepares one attempt-local immutable product binary, then
   runs four isolated Linux real-tmux fixtures plus the Codex lifecycle and npm
   staging fixtures. The required inventory is `L01`-`L19`, `C01`, and `N01`;
   every fixture has its own HOME/XDG/tmux/socket/evidence roots and every
   consumer records the same binary SHA. `E2E_SCENARIO=<ID>` selects one exact
   stable scenario for replay.
+- Three mutually exclusive selectors narrow one invocation. `E2E_SCENARIO=<ID>`
+  replays one scenario, `PROJMUX_E2E_LINUX_SHARD=<shard>` runs exactly one
+  Linux fixture with the terminal inventory its `linux-shards.tsv` row owns,
+  and `PROJMUX_E2E_SUITE=codex-lifecycle|npm-staging` runs one non-Linux suite.
+  Setting none keeps the default: four Linux shards in parallel plus both
+  suites. CI uses the shard/suite selectors to give every suite its own runner,
+  so container isolation and schedule isolation are the same unit there; local
+  `make test-e2e` still runs the whole matrix on one machine.
+- Every scenario wait states a budget in seconds rather than a loop count, and
+  `E2E_WAIT_SCALE=<factor>` multiplies all of them at once. Raise it when a
+  runner is slow or loaded; a wait that expires still fails with the description
+  of what it was waiting for, so a slow machine reports a timeout rather than
+  the regression message of the assertion that would have run next.
 - `make test-e2e-contract`, `make test-e2e-reliability`, and
   `make test-e2e-shards` validate typed attempt evidence, bounded semantic
   waits/owned cleanup, and exhaustive four-shard isolation without rerunning
-  the full product matrix.
+  the full product matrix. The shard target also pins the CI job list to the
+  manifest: one non-fail-fast job per shard and per suite, each with its own
+  runner, its own timeout and its own uniquely named evidence artifacts, all of
+  them required children of the aggregate `Test` gate. It also pins the thin
+  `E2E Tests` job, which exists because the branch ruleset requires a status
+  check under that exact name; a required context that is never reported stays
+  pending rather than failing, so dropping that job would deadlock merges.
 - `make test-e2e-coverage` validates
   `test/e2e/ags-oedr-manifest.json`: executable scenario markers and shard
   assignments must match all 21 rows with orphan count zero. A matrix may move
@@ -41,10 +62,15 @@ and humans run the same entrypoints.
   checks scanner/rule/baseline identity, PR-range/full-history secret scans,
   cache miss-to-hit convergence, privacy-safe artifacts, and the fail-closed
   aggregate. CI exposes their stable aggregate as `Test`.
-- `make deadcode` runs `go tool deadcode` (pinned via the go.mod tool
-  directive) over the module and reports unreachable functions, filtering out
-  the intentional/MUST-KEEP baseline in `.deadcode-allowlist.txt`; it fails
-  only on NEW dead code, and `make fix` runs it after `go fix`.
+- `make deadcode` runs the focused baseline-contract fixture, then runs
+  `go tool deadcode` (pinned via the go.mod tool directive) over the module.
+  `.deadcode-allowlist.txt` is exact to current findings: duplicate and stale
+  rows fail. `.deadcode-must-keep.txt` separately records proactive migration,
+  compatibility, and proof APIs as `symbol<TAB>non-empty reason`; duplicates
+  within either file, overlap across files, malformed reasons, and findings
+  outside the two-file union fail deterministically. `make test` also runs the
+  focused fixture, and `make fix` runs the complete deadcode gate after
+  `go fix`.
 
 ## Docker-Covered Checks
 

package/docs/troubleshooting.md

@@ -0,0 +1,164 @@
+# Troubleshooting
+
+Start with read-only diagnostics:
+
+```sh
+projmux doctor
+```
+
+`doctor` never installs packages, rewrites configuration, or changes a tmux
+server. Run a remediation command only after reviewing the finding that
+recommended it. For the operational journal's privacy and retention contract,
+see [Operational Diagnostics](operational-diagnostics.md).
+
+## App socket marker migration
+
+Projmux 0.13 and newer require two server-global markers before an ordinary
+command may mutate the app tmux server:
+
+- `@projmux_app=1` declares app ownership.
+- `@projmux_socket_name=<name>` declares the logical `-L <name>` route.
+
+An app server started by a pre-0.13 release can still be live with the first
+marker and no logical marker. In that partial state, `shell`, attach, and
+materialization commands fail closed and print the exact recovery command.
+For the default app socket, run:
+
+```sh
+projmux config apply --socket projmux
+```
+
+This explicit apply keeps the live server and its sessions, binds `-L projmux`
+to one absolute socket path and server PID, sources the generated config,
+writes the missing logical marker, and verifies both markers against the same
+server generation. Ordinary commands do not write the marker. Apply also
+refuses a foreign server, a different existing logical marker, an alias/path
+mismatch, or PID drift; do not replace the refusal with a raw `tmux set-option`
+command.
+
+For a non-default socket, use the exact name printed by the failing command:
+
+```sh
+projmux config apply --socket <name>
+```
+
+Then retry the original command.
+
+## Diagnostic sequence
+
+Use this order so each step remains read-only until you deliberately run the
+recovery command:
+
+```sh
+projmux doctor --section runtime --verbose
+projmux diagnostics log
+tmux -L projmux show-options -gqv @projmux_app
+tmux -L projmux show-options -gqv @projmux_socket_name
+tmux -L projmux display-message -p -F '#{socket_path} #{pid}'
+```
+
+Replace `projmux` in all three tmux commands with the exact logical socket name
+you are diagnosing. Expected healthy marker output is `1` and that same socket
+name. The final read records the physical socket/PID pair for comparison; it
+does not grant authority or repair anything.
+
+The marker-specific Doctor codes map to these actions:
+
+| Code | Meaning | Remediation |
+| --- | --- | --- |
+| `runtime.route-marker.missing` | App-owned live server has no logical marker, normally after a pre-0.13 live-server upgrade. | Run the exact `projmux config apply --socket <name>` printed by the failing ordinary command, then retry it. |
+| `runtime.route-marker.mismatch` | The app-owned server declares a different logical route. | Do not overwrite it. Inspect the diagnostic sequence and confirm which `-L` route owns the server. |
+| `runtime.route-marker.unreadable` | Doctor could reach the socket but could not read one or both ownership markers. | Inspect `projmux diagnostics log`, tmux/socket permissions, and the exact marker reads. Do not apply until the read failure is understood. |
+
+Other runtime Doctor codes use bounded remediation identifiers in text and
+JSON:
+
+| Code family | Remediation |
+| --- | --- |
+| `runtime.socket.unreachable` | Start the app with `projmux shell`; if a server should already exist, inspect the exact socket first. |
+| `runtime.socket.probe-failed`, `runtime.backend.unknown` | Inspect `projmux diagnostics log` and the operational journal. |
+| `runtime.config.generated-missing`, `runtime.config.generated-invalid` | Run `projmux config apply --socket <name>` after confirming the target server. |
+| `runtime.config.generated-unreadable` | Inspect config and directory permissions before applying. |
+| `runtime.config.applied-stale` | Run the exact config apply command to reload the generated config. |
+| `runtime.config.applied-unknown` | Start or identify the app runtime before attempting a reload. |
+| `logs.*` | Follow the finding's `inspect-state-permissions`, `inspect-log-permissions`, or `inspect-operational-journal` remediation. |
+| `registry.materialize.*` | Inspect the reported Registry topology. Doctor is read-only and does not repair it. |
+
+Informational `*.ready`, `*.current`, `*.reachable`, `*.none`, `*.clean`, and
+`*.audited` codes need no remediation. JSON exposes the same `code` and
+`remediation` values as verbose text.
+
+## Codex app-server install topology
+
+Start with the read-only integration report:
+
+```sh
+projmux doctor --section integrations --verbose
+```
+
+The `Codex app-server` result keeps four readiness axes separate:
+
+- `Endpoint readiness` says whether the existing endpoint is ready, dead, or
+  failed with a bounded reason.
+- `running executable` plus the sanitized version fields distinguish a proven
+  managed executable from unknown identity and current from skewed versions.
+- `manager ownership` comes only from the official daemon backend result; an
+  absent or unclear result is never guessed from endpoint health.
+- `remote control` independently reports disabled, connecting, connected,
+  errored, unsupported, unavailable, or unknown.
+
+`Source`/`reason`, `App-server probe`, `install capability`, and `lifecycle`
+remain separate supporting fields. A ready endpoint therefore does not hide an
+unmanaged process or version skew.
+
+`external-cli-only` means the ordinary Codex CLI executable is present, but
+the canonical managed payload needed by `codex app-server daemon start` was not
+observed. It does not mean the ordinary CLI is unsupported and does not prove
+who owns a running process.
+
+An explicit native action refuses a ready unmanaged or version-skewed endpoint.
+The refusal reports `shared-clients-disconnect`: replacing this shared process
+can interrupt every attached Codex client. For a managed skew, confirm the
+interruption and run `codex app-server daemon restart`. For an unmanaged
+endpoint, close every sharing client, stop the process through the operator
+that owns it, then run `codex app-server daemon start`. Projmux never performs
+those stop/restart steps or invents an ownership-specific kill command.
+
+A prompted managed Codex create also requires that endpoint. When it is not
+ready or not attachable, `projmux create codex -- "<prompt>"` refuses instead of
+silently creating a plain-CLI Agent, and the refusal carries the same typed
+reason Doctor reports. `--interactive-only` creates that plain Agent on purpose,
+without native turn control. See
+[Codex Native-Required Create Migration](codex-native-required-migration.md).
+
+If native app-server features are needed, review the
+[official Codex CLI installation options](https://learn.chatgpt.com/docs/codex/cli)
+and install or repair the managed standalone payload. Then rerun Doctor. Do not
+copy binaries, create symlinks in the Codex home, or edit the control socket as
+a diagnostic workaround. Doctor, Settings, and support-report collection never
+start the daemon or modify the installation.
+
+## Incomplete npm install
+
+If the npm shim exits before Projmux starts with:
+
+```text
+projmux: unsupported or incomplete npm install for <platform>/<arch>.
+Expected optional dependency @projmux/<platform>-<arch> to provide bin/projmux.
+```
+
+the platform-specific optional package is missing. This can happen when npm
+reuses stale package metadata or optional dependencies were disabled. Because
+the Go binary is absent, `projmux doctor` cannot run yet. Re-resolve the current
+release and its optional dependency:
+
+```sh
+npm cache verify
+npm install -g projmux@latest --include=optional
+projmux version
+projmux doctor
+```
+
+If the same error remains, remove the incomplete global package, refresh npm's
+package metadata, and reinstall. Do not copy a binary from another platform.
+GitHub Release and source alternatives are documented in [Install](install.md).