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)

[dracic]

Split out of #320 (PR #418) by review, deliberately not folded into that fix: the resolution needs an intent decision, not a wider diff.

The gap

#418 gates the psmux session project tag on _transportable(): a value that cannot survive psmux's CLI→server control line is refused rather than stored corrupted, leaving the option unset. That is the correct degradation, because runs.prunable_sessions falls back to the run dir for an untagged session — it claims our own dead runs and skips foreign ones.

That fallback holds only while the run dir exists. delete_run (runs.py:512) and archive_run (runs.py:526) both rmtree it, and neither kills an already-orphaned session. So for a project whose tag is untransportable:

1. every agent session is created untagged;
2. a crash (or any run whose session outlives its engine) leaves the session behind;
3. the operator runs clean / archives the run, removing the directory;
4. every later prune reads the session as untagged with no run dir under this project, hits runs.py:351-352's elif not is_run(run_dir): continue, and skips it — from every project, including its own.

Result: one leaked psmux session, and its server, per run, for the life of the machine.

Note the asymmetry this exposes. A tagged orphan whose run dir is gone is prunable — that is the orphan-1 case in test_prunable_sessions_partitions. The tag is the only ownership proof that survives run-dir removal, so the untagged branch is strictly weaker by design.

Why this is not just theoretical, and not just a psmux problem

The refusal shapes look exotic until you filter them through Path.resolve() on Windows:

• " is illegal in Windows filenames — unreachable in a resolved project path.
• A mid-path \\ and a trailing \ are normalized away by resolve().
• A standalone ; token needs a directory literally named ;.

The one shape that survives all of that is a spaced UNC path — \\srv\share name\proj. That is an ordinary corporate setup, not a corner case, and there every session for the project goes untagged.

Worth stating plainly: this is not a regression from #418. Before the gate, the same path stored a corrupted tag, which prunable_sessions skipped for exactly as long. #418 does not make it worse; it just makes the ceiling visible and worth naming.

Candidate directions

1. Transportable surrogate tag. Store a digest of the resolved path instead of the path itself, so every project identity is transportable by construction and the refusal path stops being reachable for ordinary paths. Both sides already route through runs.project_tag, so the change is centralized — but it is shared with the tmux backend, changes a persisted value's shape, and needs a read-side transition for sessions tagged the old way. This is the direction I would take, and it is why the work did not ride fix(adapters): gate the psmux session project tag on transportability (#320) #418.
2. Second ownership proof that outlives the run dir — e.g. have the prune consult a durable record keyed by session name. Larger, and it touches cleanup semantics rather than the tag.
3. Accept and document the ceiling, and have delete_run / archive_run refuse (or warn) while a matching session is still live, so the evidence is never removed out from under an orphan. Smallest, and it closes the sequence rather than the underlying weakness.

(1) and (3) are not exclusive; (3) is a cheap backstop for whatever happens to (1).

The fallback's other edge: ownership by run-id collision, not by identity

Split out of the #418 review alongside the lifecycle ceiling above. Same fallback, same root cause, same preferred remedy — recorded here rather than as a second issue because direction (1) closes both at once.

The lifecycle ceiling is about an untagged session that can never be pruned. The mirror failure is an untagged session pruned by the wrong project. prunable_sessions proves ownership for an untagged session by run-id collision on the filesystem, not by identity (runs.py:344-352):

run_dir = run_dir_for(project, run_id)   # run_id parsed out of the SESSION NAME
tag = tags.get(name, "")
if tag:
    if tag != mine:
        continue
elif not is_run(run_dir):
    continue

If project A's session bmad-loop-<id> is untagged and project B holds a run dir with that same <id> whose engine reads dead, B's prune classifies A's session as prunable and kills it. B also reads B's pid file to make that call.

Two things bound it, neither of which closes it:

• new_run_id() (runs.py:59) is %Y%m%d-%H%M%S plus two random bytes, so a natural cross-project collision is remote.
• But --run-id is an accepted CLI flag (cli.py:2993, cli.py:3018) validated only for shape (cli.py:158-164), and the TUI pre-assigns ids. A script reusing a fixed --run-id across two projects reproduces it deterministically.

Two notes on how this interacts with #418:

• It is not a regression, but it is not a wash either. Before the gate, an untransportable path stored a corrupted tag, which is non-empty and so was skipped unconditionally. Refusing moves those sessions from always skipped into a bucket that is only usually skipped. The trade is still right — a corrupted tag is unprunable forever, which is the defect psmux: the session-level project tag may bleed the same way the window tag did (#310) #320 was filed for — but "the untagged path skips foreign ones" is true only under the collision proviso, and fix(adapters): gate the psmux session project tag on transportability (#320) #418's own comment now says so.
• No test covers it. test_prunable_sessions_partitions (tests/test_runs.py:626) pins untagged-with-our-own-dead-run-dir → prunable and untagged-with-no-dir-here → skipped. There is no case for untagged, a run dir with the same id exists here, but the session belongs to another project — because the fixture cannot tell those apart, which is exactly the point. tests/test_tui_launch.py:391-409 covers the analogous window case only for a path-traversal id.

Direction (1) — a transportable surrogate tag — removes the reachable refusal shapes for ordinary paths, so sessions stay tagged and neither edge is reachable. Direction (3) does nothing for this edge.

Verification notes

Measured on Windows 11, psmux 3.3.7 (05cc5d4) — the round-trip table and the one-server-per-session finding are in #320 (comment). Nothing in this issue depends on a psmux release: the transport behavior is the documented model, not a bug awaiting a tag.

Refs: #320, #418

[coderabbitai]

🔗 Related PRs

#110 - fix(runs): validate run ids and stop a run ref escaping the runs dir [merged]
#175 - fix(adapters,engine): timely + observable session-timeout teardown [merged]
#298 - fix(adapters,engine): pin the read-back to the spec the session owes (#261) [merged]
#418 - fix(adapters): gate the psmux session project tag on transportability (#320) [open]
#434 - fix(adapters): seam-owned psmux option-key namespace, kill-order containment [open]

---

📝 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!

[pbean]

Two increments from the #518 review gate, where codex raised this same fallback against ctl_window_id.

(Rewriting this comment — my first post was mangled by shell quoting and lost most of the table.)

1. A reachable refusal shape missing from the list above: non-ASCII whitespace.

The reachability section rules out " (illegal in a Windows name), mid-path/trailing backslash (normalized by resolve()), and a standalone ; (needs a directory literally named ;), leaving a spaced UNC path as the one survivor. NBSP belongs on that list too: _transportable refuses any(c.isspace() and c != " "), "\u00a0".isspace() is True, and U+00A0 is perfectly legal in a Windows filename — the forbidden set is <>:"/\|?* plus control characters.

Measured against the real predicate rather than read off the comment:

PASSES   apostrophe            C:\Users\O'Brien Files\proj
PASSES   mid-token semicolon   C:\Users\a; b\proj
REFUSED  NBSP                  C:\Users\a\xa0b\proj
REFUSED  standalone ; token    C:\Users\a ; b\proj
REFUSED  spaced UNC            \\srv\share name\proj
PASSES   ordinary path         C:\Users\me\proj

So the reachable set is two ordinary shapes, not one: a spaced UNC path, and any path carrying NBSP — a real hazard, since an NBSP is easy to paste in from a document and invisible afterwards. The apostrophe and mid-token ; cases pass, exactly as _transportable's own comment says.

2. The fallback now has a second consumer, and it is a targeting one.

ctl_window_id in #518 consults the per-window PROJECT_OPTION. When psmux refuses the tag the window is untagged, so the lookup falls back to ownership-by-run-dir — the same weak proof this issue is about, but feeding attach and stop rather than pruning. Two projects sharing an explicit --run-id can therefore resolve to each other's control window.

Not a regression: before #518, ctl_window_id took no project argument at all, so it had no tag, no run-dir gate, and answered the first name match from any project. The point is only that direction (1) now closes a targeting edge as well as a pruning one.

On direction (1). #518 has taken the first step of it. runs.project_tag now percent-encodes a resolved path behind a %enc% prefix when the value cannot ride the listing — that is, when it holds a str.splitlines() separator, or a surrogateescaped byte that would make the listing decode raise. The encoding is conditional, so a transportable path is tagged byte-identically and nothing already stored is stranded; that sidesteps the read-side transition this issue names as a cost of direction (1).

What remains for this issue is the psmux control-line predicate specifically: project_tag asks the listing's questions, not PsmuxMultiplexer._transportable's. Closing that needs either a seam method the backend answers — project_tag cannot import a backend without inverting the dependency — or the digest originally proposed. Left here deliberately rather than folded into #518: psmux_backend.py is untouched by that PR, and the remainder is a seam change.