docs(plans): brief for releasing the cohort scope after a force stop

Dewey's row 47 finding: forceStopCohort and controller close never send release, so each force stop leaves a mosaic-chat scope with an idle shim. Co-Authored-By: Claude Opus 5.5 <[email protected]>
2026-10-09 22:49:45 -05:00
parent 10351f6a6d
commit d378a445d9
1 changed files with 61 additions and 0 deletions
@@ -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.