projmux 0.13.0 → 0.13.1

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/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/testing.md

@@ -15,8 +15,10 @@ 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`;
@@ -41,10 +43,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,157 @@
+# 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.
+
+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).

package/docs/upgrading.md

@@ -1,5 +1,11 @@
 # Upgrading
 
+If an older live app server refuses ordinary commands after upgrading, or npm
+cannot resolve the platform optional dependency, follow
+[Troubleshooting](troubleshooting.md). The canonical marker recovery is the
+exact `projmux config apply --socket <name>` printed by the refusal; ordinary
+runtime commands never backfill missing markers.
+
 projmux has two update surfaces:
 
 - `projmux shell` reads the cached release status before opening the app. When
@@ -25,7 +31,9 @@ projmux update apply
 Use `--dry-run` to see the planned action and `--no-apply` to skip reloading
 the live tmux config after the binary changes. `--no-apply` suppresses live
 tmux access only; the new binary still migrates the keymap schema and
-marker-owned provider files, then writes the generated config. See
+marker-owned provider files, then writes the generated config. It finishes by
+printing `projmux config apply --socket projmux` as the explicit live
+convergence still required before ordinary mutation. See
 [Keymap schema migration](#keymap-schema-migration) and
 [Managed Agent hook producer migration](#managed-agent-hook-producer-migration).
 
@@ -538,10 +546,17 @@ npm install -g projmux
 For npm-managed installs, `projmux update apply` runs:
 
 ```sh
+<current-projmux> config apply --bin <published-projmux> --socket projmux
 npm install -g projmux@latest
 projmux config apply
 ```
 
+The first apply must succeed before npm publication begins. The final apply is
+post-publication verification by the new binary. Go, GitHub Release, and source
+`make install` use the same pre-converge → publish → verify contract. A failed
+pre-apply prevents publication; a publication or verification failure returns
+non-zero and prints the exact `projmux config apply --socket projmux` recovery.
+
 `npm install -g projmux@latest` is used instead of `npm update -g projmux`
 because `npm update -g` honors the installed semver range and frequently
 refuses to move a global install across a newer minor/major release, leaving it
@@ -564,9 +579,10 @@ projmux update apply --no-apply  # migrate + write config, skip the live reload
 projmux update apply --dry-run   # print the steps only
 ```
 
-`projmux update apply` reinstalls via `go install`, atomically replaces the active
-file, and reapplies the live tmux config so a running `-L projmux` server picks
-up new bindings without a restart.
+`projmux update apply` first converges the live route with the current binary
+and exact eventual executable path, reinstalls via `go install`, then reapplies
+with the published binary so a running `-L projmux` server picks up new bindings
+without a restart.
 
 The command reads `PROJMUX_PROJDIR` from the calling shell and memoizes the
 primary path to `~/.config/projmux/projdir`, so the new binary keeps the same
@@ -585,8 +601,9 @@ PROJMUX_PROJDIR="/main/repos:/secondary/repos" projmux update apply
 
 When `PROJMUX_INSTALLER=github-release`, `projmux update apply` downloads the
 latest matching `projmux_<version>_<goos>_<goarch>.tar.gz` asset from GitHub
-Releases, extracts the binary, atomically replaces the current executable, and
-then runs the new binary's `projmux config apply` — or `config apply --no-reload`
+Releases, extracts the binary, converges the exact live route, atomically
+replaces the current executable, and then runs the new binary's
+`projmux config apply` — or `config apply --no-reload`
 when `--no-apply` is set, so the keymap schema migration still happens.
 
 Set the installer explicitly if you manage a release binary outside npm or Go:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "projmux",
-  "version": "0.13.0",
+  "version": "0.13.1",
   "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.13.0",
-    "@projmux/linux-arm64": "0.13.0",
-    "@projmux/darwin-x64": "0.13.0",
-    "@projmux/darwin-arm64": "0.13.0"
+    "@projmux/linux-x64": "0.13.1",
+    "@projmux/linux-arm64": "0.13.1",
+    "@projmux/darwin-x64": "0.13.1",
+    "@projmux/darwin-arm64": "0.13.1"
   }
 }