projmux 0.15.0 → 0.15.2

package/docs/session-restore.md

@@ -2,7 +2,11 @@
 
 Session snapshots are explicit desired-state inputs for one Project. They are
 not tmux replay scripts and they are not Registry backups. Snapshot save keeps
-the existing v1 schema and storage behavior.
+the existing v1 schema and storage behavior. In snapshot save's runtime id
+duplicate check, a Window or Pane recorded as `MissingRuntime`/`RuntimeUnbound`
+does not claim its retained runtime id, so a tmux id reused after a server
+restart does not refuse the save; two live Windows or two live Panes sharing an
+id are still refused.
 
 ```sh
 projmux get snapshots [--session <snapshot-session>]
@@ -42,10 +46,11 @@ same-kind collision is rejected as damaged before trust authorization,
 Registry/tmux/provider mutation, or any snapshot write.
 
 The committed Registry is then converged by the ordinary Project materializer.
-For a restored offline Agent-anchor Window, `Continue project` visibly plans a
+For a restored offline Agent-anchor Window, snapshot materialization visibly plans a
 lazy default shell, creates the Window from that shell, and stages the Agent on
 its retained anchor Pane UID. A successful repeat writes neither Registry nor
-topology. Agent recipes use the canonical provider launch/resume path. Stored startup
+topology. Snapshot Agent recipes use the canonical provider launch/resume path,
+including their existing fresh-conversation fallback. Stored startup
 commands are not directly executed by snapshot restore. A runtime item refusal
 does not roll the Registry back: desired state and the source snapshot remain
 available for another `Continue project`, and the refusal is reported as an
@@ -70,6 +75,41 @@ A closed Project has exactly two actions:
 Esc/cancel returns to Projects; it is not an action row. Picker failure falls
 back to the non-destructive `Continue project` action.
 
+Continue resumes an Agent's exact recorded conversation after interrupted,
+killed, abnormal, unknown, or unrecorded termination. Intentional and normal
+termination remain excluded. A recorded receipt must agree on the Agent and
+its retained Pane's current managed activation. Without a receipt, Running
+requires its exact paneRef; Offline or Failed requires one unambiguous retained
+Agent-owned Pane activation. Pending Agents are skipped. Live Agents are not
+launched again.
+
+A missing, blank, malformed, or mismatched conversation ref, a disabled provider,
+a missing workspace, or a resume preparation failure skips the Agent with a
+reason. Continue never substitutes a new conversation. Shells and other
+recoverable Agents still converge; an unrecoverable Agent that is itself a
+Window's required anchor keeps the existing Window refusal. Explicit snapshot
+restore and `agent resume` retain their separate authority.
+
+After Continue commits, its startup summary shows the resumed and skipped Agent
+totals and `projmux diagnostics log --component topology`. The same counts are
+available in the public materialize-project JSON result's `recovery` field.
+Already-live Agents count in neither total. Full per-Agent explanations remain
+on stderr; the transient summary stays within 220 UTF-8 bytes, including any
+ellipsis, independently of Agent names or how many were skipped.
+
+The private operations journal stores one `topology.outcome` and one
+`topology.agent.skipped` row per reason in the same invocation `run_id`. Reason
+counts sum to the committed skipped total. The ten codes use `topology.agent.`
+followed by `termination-excluded`, `phase-ineligible`, `activation-unproven`,
+`termination-invalid`, `session-ref-missing`, `session-ref-invalid`,
+`session-ref-mismatch`, `provider-unavailable`, `workspace-unavailable`, or
+`resume-prepare-failed`. `diagnostics report` includes recent closed recovery
+events in `topology-recovery.json`, including successful partial and 0/0 results.
+Journal rows contain no resource IDs/names, conversation IDs, payloads, or raw
+errors. Dry-run writes no execution event; failed or rolled-back execution
+records an error with zero committed counts. Journal and display failures are
+best effort and never change the topology result.
+
 `Recreate Project` never deletes or overwrites autosave or named snapshot files. It
 preserves the root, Git/worktrees, trust decision, and all unrelated Registry
 graphs while changing the Project identity. A rejected commit retains the

package/docs/troubleshooting.md

@@ -111,6 +111,32 @@ The `Codex app-server` result keeps four readiness axes separate:
 remain separate supporting fields. A ready endpoint therefore does not hide an
 unmanaged process or version skew.
 
+When a current Codex activation records a different endpoint generation from
+the running default endpoint, `Codex endpoint generation comparison` lists each
+affected Agent by exact `uid:` selector. The comparison uses the activation's
+`endpointGenerationID` and the observed running version, independently of the
+installed CLI version. It reports an observed interruption risk during endpoint
+replacement (2026-09-09, n=1), with causality undetermined; interruption is not
+certain. This is a snapshot valid before the next replacement, and performs no
+recovery or process mutation.
+
+The census includes bound Codex activations across every Project and Window in
+the managed Registry, even if their Agent phase is stale. Offline conversation
+history without a current activation is excluded. A complete comparison with no
+mismatches emits no comparison block. An unreadable Registry or missing,
+inconsistent, orphaned, or unobservable activation produces an `unavailable` or
+`incomplete` enumeration signal; confirmed mismatches remain visible alongside
+those gaps. A foreign Codex state domain, opaque generation, or a present or
+unreadable generation pool is unobservable from the default daemon probe.
+Private pool generations can also have version-shaped IDs, so Doctor does not
+infer their running endpoint from that spelling or from admission-current.
+
+The additive `codex_endpoint_mismatch` JSON field carries the same mismatch set,
+enumeration gaps, and evidence strength without changing the schema version.
+Support report `doctor.json` preserves those counts and closed evidence fields;
+Agent and generation IDs retain the support report's normal deterministic
+hashes. Exact Agent selectors are available in ordinary Doctor text and JSON.
+
 `external-cli-only` states only two observed facts: the ordinary Codex CLI
 exists, and the managed standalone payload was not observed. It does not mean
 the ordinary CLI is unsupported, identify how that CLI was installed, or prove
@@ -120,9 +146,12 @@ 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.
+endpoint, close every sharing Codex client, run
+`codex app-server daemon bootstrap`, then rerun diagnostics. The observed `pid`
+backend requires bootstrap again after reboot; this observation does not
+establish boot persistence for other backends. The unmanaged bootstrap
+prescription is absent for managed or unknown ownership. Projmux reports this
+operator-owned guidance without executing the recovery commands.
 
 A prompted managed Codex create also requires that endpoint. When it is not
 ready or not attachable, `projmux create codex -- "<prompt>"` refuses instead of
@@ -159,6 +188,38 @@ method, 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.
 
+The read-only manager observation is recorded separately as `manager_evidence`:
+`status`, `backend`, `result`, `agreement`, and the manager's reported `version`.
+`running_version` describes the independently initialized endpoint. A version or
+running/stopped contradiction yields `manager_ownership=unknown`,
+`native_action_refusal=evidence-contradictory`, and inspection guidance. A ready
+endpoint with insufficient manager evidence also refuses mutation. Running/PID
+or a managed-looking path alone does not prove ownership. The existing exact
+cold-start rule remains separate; a contradictory running-manager observation
+cannot authorize it.
+
+Observer `ai-ingest.log` fallback rows keep the existing `reason` and add a
+`failure` object: allowlisted request `method`, nullable original `rpc_code`, and
+closed `cause`. For example, an unsupported request and a catalog rejection can
+share `reason=unsupported` while retaining different original methods/codes.
+Transport and local protocol failures have `rpc_code=null`. Read-only preflight
+refusals also carry the same `recovery` evidence and operator decision Doctor
+reports. These fields are appended only after the exact authority write succeeds;
+the existing startup handshake and reason consumers are unchanged.
+`projmux diagnostics agent-hook` displays the same safe `failure=` and `recovery=`
+JSON objects in its default text output; `--json` retains the original JSONL
+records. Older rows keep their existing text format.
+
+Diagnostic bounds are 32 bytes per method/cause/evidence token or version,
+20 decimal bytes for an RPC integer, 64 bytes per recovery decision token,
+160 bytes for `failure` JSON, 256 for `manager_evidence`, and 768 for `recovery`.
+The Codex health JSON/text section and enriched observer row each fit within
+4096 bytes (the row reserves space for its timestamp). Public journal text adds
+at most 947 bytes for both diagnostic objects, labels and separators; an enriched
+observer line remains within the same 4096-byte row bound. The existing journal file
+retention bound remains 1 MiB. Provider messages, payloads, prompts, auth, paths,
+and raw PIDs are excluded; unknown strings are replaced by closed unknown values.
+
 ## Incomplete npm install
 
 If the npm shim exits before Projmux starts with:

package/package.json

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