fix(cleanup): withhold a pre-upgrade control session's command when a run may own it

CHANGELOG.md

@@ -88,6 +88,20 @@ breaking changes may land in a minor release.
 - Refuse psmux option values shaped `-X=value`, `-t…` or `--`: psmux 3.4.0 rewrites the
   first silently and rejects the others, so the value is now warned about and its key freed
   (#905).
+- Stop `cleanup` and the TUI from calling the sessions in a displaced registry `not migrated`
+  when it is another project's derived `PSMUX_DATA_DIR` (or this project's from before a
+  rename): name it as such and say its control session and untagged sessions most likely
+  belong to that project, while a session tagged as this project's is yours; the stderr
+  note names it too (#906).
+- Report a pre-upgrade `bmad-loop-ctl-<16 hex>` control session left in the project's own
+  psmux registry: `cleanup` names it on stderr and in `sessions.legacy_leftovers` with the
+  command that ends it (`sessions.legacy_kill_commands`), and `attach` names it when it finds
+  nothing to attach (#733).
+- Print no kill or attach command for a pre-upgrade control-session name that may be a run's
+  own session (a run of this project has that id, or the session carries a run's project tag,
+  as a neighbour's run can in a shared registry), still check the project's own registry
+  when legacy-registry discovery fails, and have `attach` name the pre-upgrade control session
+  when it finds no run at all (#915).
 - Fire the TUI's stale state-root note on psmux too: the psmux backend now answers which
   value a new pane inherits through psmux 3.4.0's named `show-environment` (#660).
 - Fix the OpenCode V2 SSE-reconnect end-to-end test failing on slow runners (Windows): the

docs/multiplexer-backends.md

@@ -136,8 +136,17 @@ named `bmad-loop-ctl-<16 hex>` is also a control session to bmad-loop, so `clean
 prunes it. Nothing launches into it, though, so the TUI's attach and stop keys and the
 parked-window sweep do not reach its windows. To end one, let its runs finish
 (`bmad-loop stop` reaches a live engine wherever it runs) and check that every window shows
-the exit banner (see `capture-pane` below). Then run
-`psmux kill-session -t bmad-loop-ctl-<16 hex>`.
+the exit banner (see `capture-pane` below). Then, unless the name may be a run's own session
+(below), run `psmux kill-session -t bmad-loop-ctl-<16 hex>`.
+
+`cleanup` names the one an earlier release started for this project in its registry
+(matched by that exact name, since a run id `ctl-<16 hex>` gives an agent session the same
+shape) on stderr and in `sessions.legacy_leftovers`, with that command ready to paste
+(`sessions.legacy_kill_commands` in `--json`). `attach` names it when it finds no run or nothing to
+attach, with `switch-client` instead of `attach` when run inside a psmux pane. A name that
+may be a run's own session (a run of this project has that id, or the session carries a run's
+project tag, as a neighbour's run can in a shared registry) is named with no command; do not
+end it by hand until you know which it is.
 
 **If the state root cannot be derived** (for example, `BMAD_LOOP_STATE_DIR` is a relative
 path), bmad-loop says so and leaves whatever `PSMUX_DATA_DIR` was in force. `cleanup` then
@@ -202,9 +211,11 @@ repeats the warning. A server already running with it on is not detected. Unset
 before the per-project root: psmux's default registry, and any `PSMUX_DATA_DIR` root
 bmad-loop displaced. It kills only sessions that carry this project's ownership tag and
 whose run is not still going. Whatever it leaves is named on stderr as
-`left in <registry> (not migrated): …` and in `cleanup --json` at
+`left in <registry> (<label>): …` and in `cleanup --json` at
 `sessions.legacy_leftovers`; a registry that could not be asked at all is named as
 `legacy registry not checked …` (`sessions.legacy_unverified`, a toast in the TUI).
+The label is `not migrated`, except for a registry derived from another project path,
+which gets its own label (below).
 
 Three kinds stay behind by design:
 
@@ -213,6 +224,17 @@ Three kinds stay behind by design:
 - **A live session of your own.** Cleanup never kills a run whose engine is still going.
 - The shared **`bmad-loop-ctl` control session** in that registry.
 
+**Sessions in another registry.** A displaced root shaped like one bmad-loop derived
+(`<project tag>/_mux`) under a tag that is not this project's is reported in full like any
+other, but its line reads `left in <registry> (another project's derived registry, or this
+project's from before a rename): …` instead of `(not migrated)`. That is the root
+`bmad-loop mux` printed for another project, or for this one before it was renamed or moved,
+still exported in the shell. Its control session and untagged sessions most likely belong to
+that project: do not remove them from here. A session tagged as this project's is yours. A
+derived-shaped root whose tag cannot be compared gets the same wording. The
+`note: using bmad-loop's own psmux registry …` line that names the displaced root says it is
+such a registry, and `cleanup --json` is unchanged.
+
 To inspect one, put the shell on the registry the message named:
 
 ```powershell

docs/reference/cli.md

@@ -546,7 +546,7 @@ The `--dry-run` plan and the outcome share this shape.
 | `sessions`    | object | agent sessions (below)         |
 | `ctl_windows` | object | control windows (below)        |
 
-`sessions`: `removed` (run ids whose session kill was attempted), `live` (left alone), `unverifiable_pid` (subset of `removed` whose engine liveness could not be proven), `legacy_leftovers`, `legacy_unverified`, and `scan_error` (present only when the scan failed).
+`sessions`: `removed` (run ids whose session kill was attempted), `live` (left alone), `unverifiable_pid` (subset of `removed` whose engine liveness could not be proven), `legacy_leftovers`, `legacy_kill_commands` (a pre-upgrade control session in this project's registry mapped to the command that ends it, `null` when the backend is not psmux; a session a run may own is left out), `legacy_unverified`, `superseded_ctl_unverified` (a check on this project's own registry for such a session, or one that withholds its command, could not be made), and `scan_error` (present only when the scan failed).
 
 `ctl_windows`: `removed` (verified gone, or would close under `--dry-run`), `survived`, `unverifiable` (kill outcome could not be checked), `undetermined` (kept because the window's state could not be read), `scan_error` (str or null; when set, the other lists mean "no answer").