psmux can destroy a live session out from under a run (psmux#546) — decide the exposure and whether the reconcile can tell

[dracic]

Summary

psmux/psmux#546 (filed from the pre-3.3.8 hunt, present on 3.3.7 and on master): the pre-boot
mtime guard in cleanup_stale_port_files() deletes a live session's whole registry set and
continues above the authoritative PID-anchor check (session.rs:1199-1212), after which the
orphan reaper terminates the still-running server. It runs on every psmux invocation, before
argument parsing — psmux -V is enough. Trigger is a forward wall-clock step with uptime unchanged
(VM save/restore, NTP step after booting with a slow RTC, mtime-preserving restore), not idleness.

So on Windows an orchestrated session can be destroyed mid-run by an unrelated psmux call, and the
destroying invocation exits 0 with nothing on stderr.

What this repo needs to decide

The upstream fix is a one-line reorder and will presumably land, but it is not in 3.3.8 as of
6ebc629, and the exposure exists on every release we admit today. Two questions, neither answered
anywhere in the codebase:

1. Can a run tell? Session completion is hook-Stop-or-window-death by design. An externally
   reaped session presents as window death, so the engine would complete the session and hand it to
   the deterministic post-session verify — which finds no work done and escalates. That is a safe
   degradation but a misleading diagnosis: the operator is told the session finished and produced
   nothing. Worth deciding whether the reconcile can distinguish "the mux destroyed it" from "the CLI
   exited", e.g. by noticing the session vanished rather than just the window.
2. What happens to the shared ctl session? tui/launch.py assumes the ctl session outlives every
   run (parked windows never self-close, pruning is manual). A reap takes the ctl session and every
   parked window's option keys with it, so the project tag map disappears and the untagged-session
   fallback behind Untagged sessions are weak ownership: they leak once their run dir is gone, and can be pruned by the wrong project on a run-id collision (the fallback behind #320) #419 becomes the only ownership signal.

Also worth re-verifying on the 3.3.8 admission

The delta reworks this whole area — d7d5b50 (#510 reaper scope), fef2217/6d8bc4b (#530 orphan
prune), e66b80d/cb098c0 (bounded sweep), 8cf3b1f (single warm server per namespace). Measured
baseline on a dev machine: 38 stale .sid files dated over three weeks, while a clean kill-session
leaves zero net files — i.e. the residue comes from sessions ending without kill-session
(window-death and crash paths), which is exactly the path #530's fix must be checked against.

Cheap mitigation available regardless: PSMUX_DATA_DIR (upstream 5152a2c, in 3.3.8) can point a
run's registry at a per-project root, which also bounds the blast radius of any cross-project reap.

Surfaced by the pre-3.3.8 bughunt

Refs: psmux/psmux#546, #222, #419

[coderabbitai]

🔗 Related PRs

#175 - fix(adapters,engine): timely + observable session-timeout teardown [merged]
#184 - fix(teardown): wait for the session's process tree before worktree teardown (#183) [merged]
#290 - fix(adapters): session-qualify psmux window ids [merged]
#418 - fix(adapters): gate the psmux session project tag on transportability (#320) [merged]
#434 - fix(adapters): seam-owned psmux option-key namespace, kill-order containment [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[dracic]

Upstream fixed the trigger: psmux/psmux#546 is CLOSED, fix 4743273 ("fix(session): PID anchor vetoes
the pre-boot mtime guard") on psmux master 9bdafcb, with a regression suite
(tests/test_issue546_preboot_reap_repro.ps1).

That does not close this issue, for two reasons:

1. No release carries it. The newest tag is still v3.3.7 (2026-07-20) and the installed binary here
   is 3.3.7 (05cc5d4), so every psmux we admit today still reaps live sessions on a wall-clock step.
2. The question this issue asks is about us, not psmux. A session can vanish under a run for other
   reasons (an operator kill-session, a server crash, a machine sleep). The open half stands: an
   externally destroyed session presents as window death, so the engine completes it and the
   deterministic verify reports "finished, produced nothing" — a safe degradation with a misleading
   diagnosis. Deciding whether the reconcile can distinguish "the mux destroyed it" from "the CLI
   exited" is independent of any upstream fix.

The re-verification items in the body (crash-path .sid residue, __warm__.* scope, reaper vs an
idle-but-live session) also stay — they now need re-running against 9bdafcb's reworked
session.rs, not against 6ebc629.

[dracic]

Q1 answered: yes, and the ambiguity was structural

_window_alive is handle.native_id in mux.list_window_ids(session), and list-windows returns
[] both when the window died inside a live session and when the session no longer exists
(rc != 0 → [], no exception). So window death — the only completion signal besides a Stop hook
— collapsed "the CLI exited" and "something destroyed the session" into one verdict. has_session
separates them; nothing was asking.

The probe sits in _ResultFileMixin._final, the single chokepoint all five crash sites funnel
through, gated on status == "crashed". Safe to ask that late: run()'s teardown kills the
window, never the session, so our own kill cannot fake a vanishing.

Diagnosis only — routing is unchanged, because _ensure_session re-creates the session and a retry
self-heals. The reason is worded as the observation rather than the conclusion (the multiplexer no longer reports the session (lost mid-run, not a CLI exit)), since the probe cannot tell who
destroyed it — and the suspect list is wider than the issue body assumed: an external reaper, a
concurrent runs.kill_session from this tool's own prune/stop/crash paths or the TUI, an operator
kill-session, a server crash, the host sleeping.

Correction to this issue's framing

The body says an externally reaped session is "handed to the deterministic post-session verify —
which finds no work done and escalates". That is not what happens. engine.py gates the entire
dev-verify block on if result.status == "completed":, so a crashed session never reaches verify
at all; outcome stays None and decide_dev short-circuits above the assert. What the
operator actually saw was the bare retry/defer reason dev session crashed — misleading in the
same direction, but by omission rather than by a false verify report. (The first draft of the
changelog inherited the issue's wording and had to be corrected.)

The one variant that does reach verify is a session reaped after flushing its result.json:
that upgrades to completed on read-back and is deliberately left undiagnosed, because a session
that wrote a result did produce something.

Coverage limits, recorded deliberately

• A vanished session that also matches an env_fault pattern. crashed is in
  ENV_FAULT_STATUSES and both deciders test env_fault first, so the two diagnoses would have
  cancelled out. env_fault_pause_reason is now composed over session_failure_reason so both
  facts survive — a lost session is not evidence about the API, and a log pattern is not evidence
  the session survived.
• A persistently raising liveness probe. If the transport keeps failing, the session ends
  timeout rather than crashed, and _final never asks. Coverage is "the session was destroyed
  while the backend still answers", which is narrower than the whole class.
• The inconclusive probe leaves no trace. Filed against engine: the reconcile's unknown-status refusal leaves no journal entry #370, which is the same shape.
• On psmux the probe is itself a psmux invocation, so under the (upstream-fixed, unreleased)
  psmux#546 trigger it could in principle be the reaper it reports. Marginal: _window_alive polls
  the same binary every tick, so a reap almost always precedes the verdict.

Still open

Q2 (the shared ctl session, and the untagged-session fallback behind #419) is untouched and stays
with the next item, along with the 3.3.8 re-verification list in the body. Deferred repair-loop gap
found alongside this: #521.

[dracic]

Q2, decided while closing #419 (PR #523): the premise does not hold — no reachable state loses ownership metadata while the thing it describes is still alive.

Parked ctl windows are windows of the ctl session and die with it. On psmux a window option is a session-scoped key (@bmad_project__blw@3) on that session's own server, and psmux runs one server per session — so an external reap removes the tag map and the tagged windows in the same act. Agent sessions it could also reap carry their own tag on their own server and simply cease to exist, which the prune handles by not seeing them.

What a reap actually costs: the parked windows and their return targets, which _ensure_ctl_session re-creates on the next launch, plus the misleading crash diagnosis — that is Q1, shipped in #522.