stack/agents/researcher/work/queue-120/build.md

Row 120 (#1614): the broker limits who the assistant sends to and hears from

Researcher, 2026-10-15. Brief: docs/plans/2026-10-14_prd-1.2-build.md, "The broker limits who the assistant sends to and hears from". Requirement: REQ-ASSIST-2 (docs/prd/mosaic-stack.md:170). Reviewer: Filbert. Gate owner: Sage. Gate text: "Filbert approves on #1614 naming the candidate manifest; Sage's full gate rerun at the landing target; both directions refused and logged, a role without the field unchanged".

Round 2 (2026-10-15)

Base: 66ea40580e3090674100292497a01f7c75c15ef3 (refactor tip, includes row 122 at 7b5b682ae). row120.patch is the candidate diff against it, 6 files; git apply --check passes at the canonical HEAD (66ea40580), and no commit from 66ea40580 to HEAD touches a candidate path. Candidate manifest digest: ae7515b97bb92fdde63e9d2e6fd8473700d3e0c12d9e70fff67e06129fbac1a9. The Round 1 text below is kept; where it says 85540a74e, 9 tests, 19 mutants or the Round 1 gate counts, this section supersedes it. The Round 1 patch and outputs are in commit 07a967aec.

Filbert F1 (comment 28539). #reviewMessage, reached by review.request and review.verdict, stored a message to a role without meeting the assistant's lists, even after a human approved the gating decision. Ruling (comment 28540), option (a): widen the row to the review paths. Done by calling the existing #checkMessaging in each case before anything is recorded; no new code path, #reviewMessage itself is untouched, nothing else in broker.mjs widens.

Where	Check	Refusal
review.request, after the stale/unknown-commit block, before the message id	#checkMessaging(s, a.to)	message-recipient-refused when the sender's sendTo omits the reviewer; message-sender-refused when the reviewer's receiveFrom omits the sender
review.verdict, after verdict-exists, before the message id	#checkMessaging(s, r.from) (the verdict is a message to the role that asked)	same two codes

A refusal throws inside the request transaction, so no REVIEW-REQUEST or REVIEW-RESULT message, no review.requested or review.verdict event and no authority is consumed. The catch writes action.refused with the code and the actor role.

Tests added to messaging.test.mjs (now 12).

1. The assistant's review.request to a reviewer outside its sendTo is refused as message-recipient-refused and logged, even after a human resolves the review.request decision yes. Run twice: the decision is unconsumed, no message, no event, action.allowed count unchanged.
2. A review.verdict to the assistant from a role outside its receiveFrom is refused as message-sender-refused and logged, with no REVIEW-RESULT, no review.verdict event and no authority consumed. The request is made by a first broker on the same store with permissive definitions (a request that predates the lists); the reviewer releases the role; a second broker with the real definitions takes the verdict.
3. A coder-to-reviewer request and the verdict back are unchanged (roles without the field), no refusals.

Mutants added. m16 removes the review.request check (caught by test 1). m17 removes the review.verdict check (caught by test 2). m1, m2, m3, m7, m8 and m15a also fail the new tests. Total now 21 mutants plus 3 controls; all 21 are caught, none survived. Names and per-mutant output, return code and patch are in mutants/; mutants-run.txt is the run log. Controls: messaging 12/12, role 14/14, assistant 8/8.

Gate on the rebased tree (slot sage-0284, decision 136, suites.sh; outputs in suites/):

Run	Result
business	88 / 88
bus	171 / 171
harness	84 / 84
cli	195 / 195
webui	112 / 112
tasks	92 / 92
conversation	182 / 182
seat	132 / 132
scripts/test-task.sh	98 passed, 0 failed

No flake from #258, #261, #262 or #263 occurred. (My first gate launch stopped at the busy check: it flagged my own shell, whose cwd was the bare scratch directory. Nothing ran; I reran from inside the worktree.)

Merge with row 122, checked by hand. 122 added the organization constructor argument and a limits/limits.set block before the store transaction. This row's constructor loop, #checkMessaging and the three call sites sit beside those hunks with no overlap. 122's one-line change to assistant.test.mjs merged cleanly. The five touched single files passed on the rebased tree before the full gate.

Noted follow-up, not gated here (comment 28540). The DECISION message that decision.resolve inserts to the raising role still doesn't go through #checkMessaging. Today the assistant holds no decision authority and its crossRole is [], so it can't be the raiser or the target of one. If a role with a receiveFrom list ever gains decision authority, gate that insert too.

Files. row120.patch, candidate-manifest.sha256, build.md, suites.sh, suites/, mutants.sh, mutants-run.txt, mutants/, packet-manifest.sha256.

Round 1

Base: 85540a74e. row120.patch applies to it by git apply --cached --check, and to the canonical checkout's HEAD at packet time (9f1c14e57, git apply --check passes). No commit between 85540a74e and 9f1c14e57 touches a candidate path.

Row 122 also edits packages/bus/src/broker.mjs (constructor organization argument, a limits block before #store.transaction). It lands first (sage-0270). This row's constructor check sits after the existing assignments inside the per-business loop, and its message.send edit stays inside that case. After 122 lands I rebase, rerun the full gate and report; expect at most a textual neighbourhood conflict in the constructor.

What changes

A role file may carry an optional messaging object: sendTo and receiveFrom, each a list of role definition names plus human for the user. The broker enforces whatever the role file says and hard-codes no role name. Only roles/assistant.json carries the field today:

"messaging": { "sendTo": ["human", "chief-of-staff"], "receiveFrom": ["human", "chief-of-staff"] }

File	Change
packages/business/src/role.mjs	V2_KEYS gains messaging (optional; V2_REQUIRED keeps the presence check). New checkMessaging: object, only sendTo and receiveFrom, each a distinct list of ids, tester refused (never a role). The loaded role gains messaging (null when absent; v1 files stay null and reject the key).
packages/bus/src/broker.mjs	Constructor refuses a malformed definitions[*].messaging with invalid-messaging. New #checkMessaging(s, to), called in message.send after the unknown-role check. Sender side first (message-recipient-refused), then target side (message-sender-refused).
roles/assistant.json	adds the messaging object above.
packages/business/tests/role.test.mjs	v1 role has messaging === null; new test for the field's shape, the refusals, and tester.
packages/business/tests/assistant.test.mjs	APPROVED gains the frozen lists; new test that the assistant is limited and no other shipped role is.
packages/bus/tests/messaging.test.mjs (new)	9 broker tests (below).

Why the broker reads business.definitions

Broker "roles" are business instance names (chief, assistant); each has roles[x].definition, the role definition name. A role file can't know a business's instance names, so the lists name definitions and the broker maps an instance to its definition. The business record handed to the broker is a structured clone of the loaded business and already carries definitions, so busBusiness, resolve.mjs, the digests and the launcher are untouched. No re-pin and no digest change come from this row. A business record with no definitions is unlimited; test 8 pins that.

Alternative rejected: have busBusiness copy the field onto roles[x]. It works, but business.mjs is outside the row's path list.

Rules, as tested

• Sender with a sendTo list: the recipient's definition must be listed, human for the user. The tester is not a definition, so a limited role can't send to tester (a reply to the tester is blocked the same way).
• Recipient with a receiveFrom list: the sender's definition must be listed; human for the user. The tester is never listed, so the tester's send to the assistant is refused. This is the tester default in the packet.
• The sender check runs before the target check, with separate codes.
• The human and the tester are checked on the target side only.
• A role with no messaging is unchanged on both sides.
• A refusal throws inside the request transaction: no message is stored, no action.allowed is consumed, and the catch writes action.refused {code} with the actor role and no request content.

Filbert carry-in

"The broker must refuse an assistant send to any role other than the user and the chief of staff, with both directions tested as refused and logged, and a role without the field unchanged." Read as: enforce what roles/assistant.json lists, hard-code no name (Sage accepted this in sage-0270). Sender direction: the assistant to pm, coder, scribe, warden and the tester, each refused and logged. Target direction: pm, coder and the tester to the assistant, each refused and logged. Allowed: assistant to human and chief, and human and chief to the assistant.

Tests (messaging.test.mjs, 9)

Reads the shipped roles/assistant.json. Fixture instances: chief, assistant, pm, coder, scribe (send list only), warden (receive list only); bus.tester: true.

1. The assistant sends to the user and to the chief of staff only (allowed sends, both ways).
2. An assistant send to any other role, or to the tester, is refused and logged (nothing stored, nothing consumed).
3. Only the user and the chief of staff may send to the assistant; the tester is refused by default.
4. A sender-side list alone refuses a send to a role that has no list.
5. A target-side list alone refuses a send from a role that has no list.
6. The sender list is checked before the target list.
7. Roles without the field behave exactly as before.
8. A business with no role definitions at all is unlimited.
9. A malformed messaging field refuses at boot (invalid-messaging).

Gate (decision 136, targeted; slot held per sage-0272)

Worktree /mnt/storage/scratch/researcher/q120 at 85540a74e plus row120.patch. Outputs are in suites/.

Run	Result
business	80 / 80
bus	165 / 165
harness	84 / 84
cli	191 / 191
webui	108 / 108
tasks	92 / 92
conversation	182 / 182
seat	132 / 132
scripts/test-task.sh	98 passed, 0 failed

No flake from #258, #261, #262 or #263 recurred.

Mutants (mutants.sh, mutants-run.txt, mutants/)

Three controls pass (messaging 9/9, role 14/14, assistant 8/8). 19 mutants, each one exact-once edit, each run against the named test files. All 19 are caught; none survived. Per-mutant output, return code and patch are in mutants/.

Mutant	Edit	Caught by
m1	drop the sender-side check	messaging (3 tests)
m2	drop the target-side check	messaging (2 tests)
m3	drop the refusal log	messaging (5 tests)
m4	sender reads receiveFrom	messaging (2 tests)
m5	target reads sendTo	messaging (1 test)
m6	tester exempt from the target list	messaging (2 tests)
m7	role with no field refused on the sender side	messaging (4 tests)
m8	role with no field refused on the target side	messaging (5 tests)
m9	target matched by instance name	messaging (1 test)
m10	constructor shape unchecked	messaging (boot test)
m11	validator accepts tester	role test
m12a, m12b	loader drops the field	role test; assistant test
m13a, m13b	assistant sendTo widened with pm	messaging; assistant
m14a, m14b	assistant receiveFrom widened with coder	messaging; assistant
m15a, m15b	assistant file unlimited	messaging; assistant

Assumptions

• Entries are role definition names, not instance names. An org that renames the instance chief still limits the assistant to the instance whose definition is chief-of-staff. The caveat: two instances of one definition are treated alike.
• tester can't be listed in a role file; it is refused by default wherever a list exists.
• Limiting any other shipped role is a policy change of its own. The chief of staff and PM stay open, and assistant.test.mjs pins that.

Out of scope and follow-ups

• "In the thread" (the assistant sends in the user's thread) lands in row 121.
• A DECISION message that decision.resolve posts to the raising role doesn't go through message.send, so this row doesn't gate it. The assistant holds no decision authority, so it can't be the target of one today. If a role ever gains a receiveFrom list and decision authority, revisit.
• Row 122's limits block and this row's checks are independent (limits count, messaging filters).

Files in this packet

row120.patch, candidate-manifest.sha256 (the 6 candidate files), build.md, suites.sh, suites/, mutants.sh, mutants-run.txt, mutants/, packet-manifest.sha256 (digests of the packet files).