diff --git a/docs/plans/2026-10-10_cohort-scope-release.md b/docs/plans/2026-10-10_cohort-scope-release.md new file mode 100644 index 00000000..f0b82ada --- /dev/null +++ b/docs/plans/2026-10-10_cohort-scope-release.md @@ -0,0 +1,61 @@ +# Conversation cohort: release the scope after a force stop (2026-10-10) + +Status: written by Sage, lead. It follows `docs/plans/BRIEF-TEMPLATE.md` +and amends no section of the slice 1 brief. One row. + +## Cohort scope release after a force stop + +### Problem + +Dewey found this while working on row 47 (#1533, round 1 notes, comment +27037). In a running controller, each force stop leaves a +`mosaic-chat-*.scope` unit with an idle node `shim.mjs` in it, until +something else kills the unit. + +- `shim.mjs` ignores SIGTERM by design (README, file table) and exits only + on the `release` op. +- `forceStopCohort` (`packages/conversation/src/cohort.mjs`, near line + 150) ends after `kill` and never sends `release`. +- Controller close doesn't send `release` for a stopped binding either. + +Row 47 fixed the test-side leaks. This row is the src side. + +### Owner and reviewer + +Owner: Dewey. Reviewers: Darkwing and Filbert. + +### Files owned + +- `packages/conversation/src/cohort.mjs` +- `packages/conversation/src/controller.mjs`, only the force-stop and close + paths +- `packages/conversation/src/shim.mjs`, only if `release` needs a change +- `packages/conversation/tests/` and `packages/conversation/README.md` + +### What ships + +- After a force stop whose outcome is `proven`, the cohort sends `release` + to the shim. The scope unit is gone afterwards. +- Controller close sends `release` for a binding whose engine is proven + stopped. +- No `release` after an `unavailable` outcome. Releasing a scope whose + members weren't proven gone would drop the evidence. The README states + this. +- First check whether a normal engine exit (no force stop) also leaves the + shim. If it does, fix that path in the same row; if it doesn't, say why + in the packet. +- Tests: after a proven force stop the unit is absent (`systemctl show` + reports it inactive or not found), after close the unit is absent, and + after an `unavailable` outcome nothing is released. A mutant that drops + the new `release` must fail a test. + +### Out of scope + +The force-stop phases themselves, the claim protocol, and the pgroup +fallback. + +### Gate + +Darkwing and Filbert approve on the row's issue. The conversation and +webui node suites and every `scripts/test-*.sh` green on Sage's gate rerun. +No `mosaic-chat-*.scope` left after the suites.