Skip to content

fix(cleanup): report a pre-upgrade bmad-loop-ctl-<digest> control session - #912

Open
dracic wants to merge 5 commits into
bmad-code-org:mainfrom
dracic:fix/733-report-legacy-ctl
Open

dracic wants to merge 5 commits into
bmad-code-org:mainfrom
dracic:fix/733-report-legacy-ctl

Conversation

@dracic

@dracic dracic commented Oct 13, 2026 •

Copy link
Copy Markdown
Contributor

Stacked on #911 (#906). Merge #911 first; until then this diff also shows its commits.

After #900 the psmux control session went back to one fixed name, bmad-loop-ctl. A control session started under the old bmad-loop-ctl-<16 hex> name can keep running in the project's own registry and hold a parked run window. Nothing named it (reported on #733):

  • cleanup --dry-run printed nothing to clean up;
  • cleanup --json reported "legacy_leftovers": [];
  • attach <run> answered nothing to attach.

An operator who had not read the CHANGELOG had no trace of it.

Change

  • cleanup names a pre-upgrade bmad-loop-ctl-<16 hex> session in the project's own registry:
    • on stderr as left in <registry> (not migrated): …, followed by the command that ends it;
    • in --json under sessions.legacy_leftovers, with the command in the new sessions.legacy_kill_commands. The field is additive; existing fields are unchanged.
  • attach, when it finds nothing to attach, names the session and prints the command that attaches to it.
    • It deliberately does not adopt the session. stop, the parked-window sweep and the decision return path do not address it, so landing the operator there would half-adopt it. The reasoning is in _note_superseded_ctl_for_attach.
  • The docs (multiplexer-backends.md, reference/cli.md) and the CHANGELOG are updated.

Verification

Live, on psmux 3.4.0 from PowerShell 7 with SHELL unset, using the repro from the #733 comment. The legacy window was tagged through mux.set_window_option(wid, runs.PROJECT_OPTION, runs.project_tag(project)).

  • cleanup names the session on stderr. --json lists it in legacy_leftovers and maps it in legacy_kill_commands.
  • attach names it.
  • The JSON kill command, run as given, ends it: rc 0, and psmux ls then reports no server.
  • Positive control under the current name: unchanged.

Tests: tests/test_runs.py and tests/test_cli.py cover the report, the JSON field and the attach note.

Refs #733

Summary by CodeRabbit

  • Bug Fixes

    • Cleanup and attach now identify older control sessions in the project’s registry. Cleanup provides a command to end a session when supported; attach reports the session and provides an attach command when available.
    • Cleanup and the TUI distinguish registries associated with another project from other unmigrated registries, name the registry, and warn that its sessions may belong to that project.
    • Registry lookup issues are reported rather than silently obscuring results.
  • Documentation

    • Clarified how older sessions and displaced registries are identified, and documented cleanup JSON output and available session commands.

@dracic

dracic commented Oct 13, 2026

Copy link
Copy Markdown
Contributor Author

@codex review

@coderabbitai

coderabbitai Bot commented Oct 13, 2026 •

Copy link
Copy Markdown

Review in Change Stack →

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration
  • Configuration used: Organization UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 722e5bc3-69e4-4bc1-b4d0-5c69715ed75f
📥 Commits

Reviewing files that changed from the base of the PR and between 170c36e and bed31ee.

📒 Files selected for processing: 4
  • docs/reference/cli.md
  • src/bmad_loop/cli.py
  • src/bmad_loop/documents.py
  • tests/test_cli.py

Included review availability: This review used your included allowance. Your plan provides up to 2 included reviews per hour; 1 remain after this review.

Walkthrough

The changes distinguish displaced psmux registries derived from another project’s path and detect superseded control sessions in the project registry. Attach and cleanup report matching sessions. Cleanup can include session termination commands in text output and JSON.

Changes

psmux Registry and Session Reporting

Layer / File(s) Summary
Classify displaced registries
src/bmad_loop/runs.py, src/bmad_loop/cli.py, src/bmad_loop/tui/app.py, tests/test_runs.py, tests/test_cli.py, tests/test_tui_app.py, CHANGELOG.md, docs/multiplexer-backends.md
Derived registry roots are classified by project tag. Cleanup and the TUI identify registries attributed to another project and distinguish them from other displaced registries.
Detect superseded control sessions
src/bmad_loop/runs.py, tests/test_runs.py
The earlier project-specific control-session name is derived and matched in the project registry. Legacy leftover reporting includes matching sessions and listing or derivation faults.
Report sessions in attach and cleanup
src/bmad_loop/cli.py, src/bmad_loop/documents.py, tests/test_cli.py, CHANGELOG.md, docs/multiplexer-backends.md, docs/reference/cli.md
Attach reports matching sessions and provides a psmux attach command when available. Cleanup reports matching sessions and applicable kill commands. Cleanup JSON includes legacy_kill_commands.

Priority: ⬇️ Low

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Bug fix

Sequence Diagram(s)

sequenceDiagram
  participant cmd_attach
  participant superseded_ctl_sessions
  participant PsmuxMultiplexer
  participant cmd_cleanup
  participant cleanup_document
  cmd_attach->>superseded_ctl_sessions: find superseded session names
  superseded_ctl_sessions->>PsmuxMultiplexer: list sessions
  PsmuxMultiplexer-->>superseded_ctl_sessions: session names
  superseded_ctl_sessions-->>cmd_attach: matching session names
  cmd_cleanup->>cleanup_document: include legacy_kill_commands
Loading

Suggested reviewers: pbean

Merge Risk: ⚪ Minimal · up to bed31

The reported legacy-session commands are scoped to the intended registry and session. No actionable merge-blocking issue remains after normal checks.

Pre-merge checks: Passed 4 · Inconclusive 1

Failed Failed checks: 1 inconclusive

Check name Status Explanation Resolution
Docstring Coverage Inconclusive Docstring coverage is 69.57% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 23 functions across 5 files. (2 skipped: … Write docstrings for the functions missing them to satisfy the coverage threshold.
Passed Passed checks: 4 passed
Check name Status Explanation
Description Check Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check Passed The title clearly identifies the primary change: cleanup now reports pre-upgrade bmad-loop-ctl control sessions.
Linked Issues check Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed Check skipped because no linked issues were found for this pull request.
Full details: Docstring Coverage

Explanation

Docstring coverage is 69.57% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 23 functions across 5 files. (2 skipped: 1 unsupported, 1 too large.)

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

A rabbit checks the registry rows,
Finds an old control session that glows.
“Here’s how to attach,” the notices say,
“And here’s the command to clear the way.”
Across project roots, names now show,
The rabbit hops on, pleased to know.

Comment @coderabbitai help to get the list of available commands.

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 13, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-10-14T08:53:56.087991Z bed31ee Manual request
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: cfed3f12ea

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread src/bmad_loop/runs.py Outdated
Comment thread src/bmad_loop/runs.py Outdated
Comment thread src/bmad_loop/cli.py Outdated
Comment thread src/bmad_loop/cli.py Outdated
…ved root

A displaced PSMUX_DATA_DIR shaped like a root bmad-loop derived for
another project path (or for this project before a rename) holds sessions
whose owner cannot be proven from here: the tag hashes a path and run ids
are caller-supplied. Report its sessions in full as before, but name the
registry for what it is instead of calling them "not migrated", in the
cleanup stderr line, the TUI toast and the displaced-root note. The
--json document is unchanged.

Closes bmad-code-org#906
…sion

After the control session went back to one fixed name, a session started
under the old bmad-loop-ctl-<16 hex> name could keep running in the project's
own registry, holding a parked run window, and nothing named it: cleanup said
nothing to clean up, --json reported no leftovers and attach found nothing.
cleanup now names it on stderr and in sessions.legacy_leftovers, with the
command that ends it in sessions.legacy_kill_commands, and attach names it
when it finds nothing to attach. attach does not adopt the session: stop, the
parked-window sweep and the decision return path do not address it.

Refs bmad-code-org#733
@dracic
dracic force-pushed the fix/733-report-legacy-ctl branch from cfed3f1 to b18bc67 Compare October 14, 2026 06:12
@dracic

dracic commented Oct 14, 2026

Copy link
Copy Markdown
Contributor Author

@codex review

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: b18bc67917

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread src/bmad_loop/runs.py Outdated
…the registry

The previous release minted the old control-session name from the resolved,
case-folded registry root, so an honoured PSMUX_DATA_DIR that is a symlink,
junction or other spelling of the project's derived registry held that
name. Compare the registry identities the same way instead of as spelled.
A root that cannot be resolved falls back to the as-spelled comparison and
reports the degrade through on_fault, which cleanup lists under
legacy_unverified and attach prints as a note.

Refs bmad-code-org#733
@dracic

dracic commented Oct 14, 2026

Copy link
Copy Markdown
Contributor Author

@codex review

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 5ddb8e8a29

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread src/bmad_loop/runs.py Outdated
Comment thread src/bmad_loop/runs.py Outdated
…try root

With [mux] honor_ambient_psmux_data_dir keeping an operator's own root,
the previous release salted the control-session digest with that root, so
the session there carries a name the derived registry's never matched.
Derive the name for the registry in force with that release's formula,
salt included, and match it there: either digest covers this project's
derived root, so the session is this project's wherever it stands.

A root that cannot be derived or resolved is no longer an empty answer:
the fault goes to on_fault, which cleanup lists under legacy_unverified and
attach prints as a note.

Refs bmad-code-org#733
@dracic

dracic commented Oct 14, 2026

Copy link
Copy Markdown
Contributor Author

@codex review

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 170c36e9cc

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread src/bmad_loop/cli.py
…smux

The recovery commands for a superseded control session were always spelled
as psmux PowerShell lines, so an out-of-tree registry-namespaced backend got
a command that fails there or reaches the wrong registry. Print the
paste-ready command only when the selected backend is psmux; on any other
backend name the session without one, in the cleanup text, as a null in
sessions.legacy_kill_commands, and in the attach note.

Refs bmad-code-org#733
@dracic

dracic commented Oct 14, 2026

Copy link
Copy Markdown
Contributor Author

@codex review

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: bed31eef9f

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread src/bmad_loop/runs.py
Comment thread src/bmad_loop/runs.py
@dracic

dracic commented Oct 14, 2026

Copy link
Copy Markdown
Contributor Author

Review status: rounds 1–4 of the automated review are fixed on this branch, each with a test, and CI is green on bed31eef. Round 5 raised two narrower edge cases. I have not fixed them here; they are tracked in #915 with a proposed fix for each:

  • a run whose hand-supplied --run-id equals the registry's old control-session digest would be offered a kill command;
  • an out-of-tree backend whose legacy_registries() raises skips the primary-registry scan.

Neither is reachable with the run ids and backends bmad-loop itself produces. Both threads are answered and link #915. This PR is stacked on #911, so please merge #911 first.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant