docs: brief for the decision-close message to the raising role (#1609)

Co-Authored-By: Claude Opus 5.5 <[email protected]>
2026-10-14 11:25:09 -05:00
parent ce8669219d
commit 2b8abe11ac
1 changed files with 131 additions and 0 deletions
@@ -0,0 +1,131 @@
 # A closed decision reaches the role that raised it (2026-10-14)
 Filed by Sage on Mos's report of 2026-10-14. Gitea #1609, Vikunja #205.
 ## A closed decision sends the raising role a message
 ### Problem
 Jason resolved decision 03130d08-ddce-480d-a601-e59f64744fc3 (the PM's
 `prd.approve` for Q139/Q140, gated, routed to human) `yes` from the CLI at
 2026-10-14T16:15:35.512Z. The bus db has the `decision_events` row (op
 resolved, by jason, via cli) and event 346, its `human.input` answer. No
 message cites the decision, and the PM had no turn after it: the newest
 message was still 75 (pm to human, 16:12:19Z) when Sage read the db at
 16:23Z.
 The cause is in `packages/bus/src/broker.mjs` (cc48b124f, live; refactor is
 the same):
 - `decision.resolve` and `decision.withdraw` write the `decision_events`
  row and, for a human, a `human.input` event `{kind:'answer'}`. They write
  no message.
 - `message.receive` reads only `messages` addressed to the role.
 - `packages/harness/src/runner.mjs` takes a turn only for a message that
  `message.receive` returns.
 So a role learns an answer only when some unrelated message gives it a
 turn. `raise_decision`'s tool text (`packages/harness/src/tools.mjs:135`)
 already says "The answer arrives as a message." This row makes the broker
 keep that promise, for every routed decision.
 The fix goes in the broker, not the runner. A message is what every
 transport already receives, routes to the role's current holder, and
 strands visibly in `agents` when nobody reads it. A second wake path in the
 runner would need its own delivery record.
 ### Owner and reviewer
 - Owner: darkwing, after row 113.
 - Reviewers: filbert (decision 130, not a sandbox row) and sage.
 ### Files owned
 - `packages/bus/src/broker.mjs`
 - `packages/bus/tests/` (a new `decision-close.test.mjs`, or changes to
  `decisions.test.mjs` and `messages.test.mjs`)
 - `packages/bus/README.md`, the `decision.resolve`, `decision.withdraw` and
  `message.receive` rows and the decision section
 - `packages/harness/tests/`, only for the runner case in item 4
 - `agents/darkwing/work/queue-115/`
 ### What ships
 1. `decision.resolve` and `decision.withdraw` send the raising role a
   message when someone other than the raising run closes the decision:
   - It's written in the same transaction as the `decision_events` row, so
     a refused or rolled-back close writes no message.
   - `to_role` is the decision's `raised_by_role`. It's the role, not the
     run, because runs end. When no run holds the role, the message waits
     for the next claim like any other.
   - Class `DECISION`, `decision` set to the decision id, `in_reply_to`
     null.
   - Sender: a human close is stored `from_role 'human'`, `from_run
     'human-cli'`. A role close is stored as that role and run. The sender
     must be a real address, because the runner sends its answer to
     `from_role` and a refused send leaves the message unread.
   - Routed with a `routed` delivery like `message.send`'s.
   - Body, one fixed form the broker writes:
     `Decision <id> on <action> was resolved by <by>: <choice> (<option text>).`
     or `Decision <id> on <action> was withdrawn by <by>.`, then
     `Note: <note>` on its own line when the close had one. `<by>` is what
     `decision_events.by` holds. Nothing else from the request goes in.
 2. No message in these cases:
   - `decision.seen`. It's an acknowledgement, not a close.
   - A withdraw by the raising run itself, including the withdraw that
     `supersedes` writes.
   - A within-role decision, which `decision.raise` resolves itself.
 3. `message.receive` returns `request` for a human close's message: the id
   of that close's `human.input` answer event. That event keeps its subject
   (the decision id), so `trail` on the decision is unchanged. This adds no
   authority. The event is already a human input that `task_create` can
   cite; the role just learns its id. A role close's message has
   `request` null.
 4. The runner needs no change. `turnRequest` already prints `citing
   decision <id>` and `request <id>`. The role's answer to the DECISION
   message goes back to its sender as RESULT, so Jason sees what the role
   did with their answer, and a resolving role gets one RESULT and sends
   none back. One harness test shows a DECISION message from `human` gets a
   turn whose header cites the decision and the request.
 5. README: the `decision.resolve` and `decision.withdraw` rows say who gets
   the message and when none is sent. The `message.receive` row says where
   a DECISION message's `request` comes from.
 6. Tests, offline as today:
   - Human resolve: exactly one message to the raising role, class
     DECISION, the decision id, from `human`/`human-cli`, the choice and
     option text in the body; `message.receive` gives `request` equal to
     the answer event's id.
   - A cross-role decision resolved by its arbiter role: from that role and
     run, `request` null.
   - Human withdraw: one message, saying withdrawn, with the note.
   - Raising run's withdraw, a supersede, a within-role raise and
     `decision.seen`: no message.
   - Refused closes (`invalid-choice`, `decision-closed`, `not-resolver`):
     no message.
   - Raising role unheld at close: the message is routed with no holder and
     delivered to the next claim's `message.receive`.
   - Mutants, each recorded in the packet: drop the message insert; address
     it to `route_to` instead of `raised_by_role`; send one on the raising
     run's own withdraw. Each must fail a test.
 7. Suites: every package suite (`node --test tests/*.test.mjs` in each
   `packages/*/`) and every `scripts/test-*.sh`, on the packet gate.
 ### Out of scope
 - Backfill. On 2026-10-14 decision 03130d08 was the only closed decision
  in the live db, and Mos unblocks it by hand. The broker writes messages
  only for closes after this lands.
 - The runner, the notifier, the Console Inbox and the Discord connector.
 - The `raise_decision` tool text. It's accurate once this lands.
 - A push wake for the runner. It polls `message.receive` every
  `pollInterval` (2 s by default), which is soon enough.
 - Decision 104, `bus.tester` and the C-suite rows, held for Q135.
 ### Gate
 Filbert and Sage approve on #1609 naming the candidate manifest. Sage
 reruns the full gate at the landing target. Mos gets notices before and
 after the landing (decision 109). It goes live only through
 `stack-copy.sh copy`, a re-pin and a bus restart on Mos's go. After the
 restart, the next human close of a PM decision should show the DECISION
 message in `messages` and a PM turn after it.