stack/agents/scrooge/work/queue-252/BUILD.md

Row 252 build notes: Console inbox Approve and Deny for grant requests

Seat: Scrooge. Reviewer: Webby. Issue #1753, Vikunja #435 (J2). Brief: docs/plans/2026-10-21_console-inbox-approve.md (blob b41676d06). Design: Gander's DESIGN.md at d218e14bd, approved by Webby at 5d8f0f4b5 (webby-0082) with manifest checks N1-N5. Base: aca16404c on branch scrooge/row252. Rebase onto the row 253 tip under a new branch name once 253 lands.

Status

• Code, tests and docs are written. No test has been run yet, because Gander holds the gate slot for row 253 run 5 and Sage ruled no node until a CLEAR.
• Everything in the Results section is empty until that run. Nothing below claims a pass.

Q188

No agent creates a grant. Approve and Deny are human-only Console actions.

• Only a console cap reaches decision.preview.console and decision.resolve.console. A console cap reaches nothing else (console-decide J1, Q188).
• The socket refuses a console proof for any other verb before the proof check (server.mjs).
• A console cap binds only through authenticateConsole, which needs the console proof (section 2): the same-tree console-cli.mjs wrapper, its own nonce, a direct same-tree serve parent, and a configured owner subject from the spawn environment.
• recordEvent keeps human.input reserved, so no agent writes the record that lets a console close start the executor (console-decide recordEvent keeps human.input reserved).
• A via console close without its matching human.input approves nothing (console-decide J14).

Manifest checks N1-N5

• N1. Every console.sso subject is an owner of the business. Name is display only.
  • cli/src/config.mjs carries {provider, iss, sub} per subject into the boot as consoleOwners. No sso means no key.
  • bus/src/runtime.mjs validates the list (array, at most 512, exactly three non-empty strings each) and passes it to verifyPrincipal.
  • Tests: cli config.test Row 252 (Webby N1) and principal.test.
• N2. human.input is written in the same transaction, before #approvedGrant. The executor starts once, and a deny starts none.
  • Tests: console-decide N2, J13 checks the order by seq and that the grant runs once. J15 checks that a deny starts nothing.
• N3. The close notice comes from from_run 'human-console', and public/bus.js shows "via console". landing and #protectedEnd stay CLI-only.
  • Tests: console-decide N2, J13 checks the notice. decide-browser J17 checks the close-elsewhere line.
• N4. decision.resolve is not a Console verb.
  • CONSOLE_VERBS is exactly the two console verbs. The webui serve BUS_VERBS read list has no decision verb, and webui cli.mjs has no decision. string. consoleCall refuses anything outside CONSOLE_VERBS.
  • Tests: console-decide N4, and decide-sso N4, which hits /api/bus/decision.* for 404 and covers the cli.mjs scan and the consoleCall refusals.
• N5. readProcess keeps the five MOSAIC_BUS_CONSOLE_* keys in the env allowlist (bus/src/human.mjs). The human proof and its spawn are unchanged.

Design choices and tradeoffs

• Webui imports from the broker. webui/src/bus.mjs imports CONSOLE_VERBS from bus/src/broker.mjs, which loads the broker module into the Console at import.
  • I chose one source for the verb list over a second copy that could drift.
  • If Webby prefers the copy, the alternative is a literal list plus a test pinning it equal to CONSOLE_VERBS.
• The Console transport shares humanCall's spawn. consoleCall and humanCall share it as transport(), so webui/src/bus.mjs changed. The busCaller business default keeps || (the old falsy semantics), not ??.
• Confirmations are held in memory in the serve process. Their lifetime is 2 minutes, they are single use, and they bind the session, decision, choice and digest. The cap is a limit that never drops a live confirmation.
  • A restart loses all held confirmations. The user clicks again and gets a new preview. Nothing is written until the resolve.
• No retry anywhere. A resolve whose bus reply is lost answers outcome-unknown, the confirmation is spent, and the page says "Nothing was sent again."

Old tests changed (for Mos, per mos-1272)

Mos ruled both changes allowed in mos-1321 (17:12:28Z), each with one condition.

• shell.test condition: reword the comment that opened "No Resolve control", since it is false once the row lands. It now says row 252's Approve and Deny is the one decision control, that its labels come from ACTIONS, and that the doesNotMatch keeps any literal label out of the markup. Webby checks the wording in review.

• channel-proof condition: a header comment is not enough, because human.mjs changes what readProcess keeps. In the review, Webby reads the human.mjs and webui bus.mjs diffs and states two things:

  • the human proof's checks are unchanged
  • only the console verifier reads the five MOSAIC_BUS_CONSOLE_* keys, and each case is covered by a named test in console-decide or decide-sso

• Second row to land (252 or 239): it recomputes the webui bus.mjs hash, adds its own header line, and its reviewer re-reads bus.mjs from the base to the combined tip.

• webui/tests/shell.test.mjs, write-boundary test. Allowed under mos-1321, with the comment reworded.

  • The writes list gains the new fetch(url, ...) in decidePost. It is first in file order (bus.js:362).
  • The method: count goes from 7 to 8.
  • A new assertion pins decidePost's callers to url plus the two literal /api/decisions/${enc(a.id)}/... routes.
  • No existing entry was loosened.

• bus/tests/channel-proof.test.mjs, sha256 re-pins with a header comment:

  • bus/src/human.mjs (N5 env keys) to bb13c146…c885.
  • webui/src/bus.mjs (consoleCall and transport()) to 701f009e…5272.
  • Any later edit to either file needs a re-pin.

• bus/tests/principal.test.mjs, webui/tests/tester-listener.test.mjs and cli/tests/config.test.mjs have new tests appended only.

Overlap with row 239 (Honker, b0c28366f, sage-2835)

• Row 239 also re-pins channel-proof.test.mjs:
  • packages/webui/src/bus.mjs, to 1eba9774…e5cf. That is the pin both rows change.
  • packages/cli/src/transport.mjs, which is 239 only.
  • packages/bus/src/human.mjs is a 252-only pin.
• The two rows also share source files: bus/src/broker.mjs, bus/src/runtime.mjs, webui/src/bus.mjs and webui/src/serve.mjs.
• Whichever row lands second rebases onto the first and recomputes the webui bus.mjs pin from the merged file. Both header comments are kept. It then reruns every touched test file whole.
• Mos needs to see that re-pin (re-pins need Mos).

Mutant plan (design section 6, J1-J17)

Each mutant is one edit to the named source. Run the killing test, then restore and compare the sha256 against the pre-mutant hash with git status clean apart from the build. Kill rules are written before the runs.

J	Mutant	Source	Expected kill
J1	eligibility from the request, #consoleResolution returns non-null for any decision	broker.mjs	console-decide J1, J2 (ineligible)
J2	hardcode approve = yes, deny = no	broker.mjs	console-decide J2 (go/stop, deny listed first)
J3	owner from name or header, skip the owner match in verifyPrincipal	principal.mjs	principal.test console requires…
J4	skip the serve-parent walk	principal.mjs	principal.test console requires…
J5	accept the human nonce namespace	principal.mjs	principal.test console requires…
J6	reuse the session from the confirmation, skip the live session check at resolve	decision-http.mjs	decision-http session that ends, decide-sso listener gates (new session)
J7	keep the console cap bound after the call (skip release for kind console)	server.mjs	open: no new test pins release for a console proof. Before the run, check whether an existing server test kills it. If not, add one and name it in the report.
J8	skip the same-origin check	decision-http.mjs	decision-http gates, decide-sso listener gates
J9	resolve without a confirmation token	decision-http.mjs	decision-http a confirmation then a resolve, bad body
J10	drop the choice, decision or session binding	decision-http.mjs	decision-http binds the session, decision and choice
J11	skip the digest, closed or business check	broker.mjs	console-decide J11, N2, J13 (second answer closed)
J12	do not spend the confirmation	decision-http.mjs	decision-http a second resolve refuses, confirmations… one use
J13	write via cli, or omit the subject in human.input	broker.mjs	console-decide N2, J13
J14	#approvedGrant accepts via console without the human.input	broker.mjs	console-decide J14
J15	start the executor on any resolved choice	broker.mjs	console-decide J15 and J2 (stop starts nothing)
J16	decide true without sso or send	serve.mjs, public/bus.js	decide-sso J16, decide-browser J16
J17	retry on outcome-unknown or auto-submit after preview	public/bus.js	decide-browser J17 (post count stays at 7)

Manifest

Source:

• packages/bus/src/broker.mjs
• packages/bus/src/client.mjs
• packages/bus/src/console-cli.mjs (new)
• packages/bus/src/human.mjs
• packages/bus/src/principal.mjs
• packages/bus/src/runtime.mjs
• packages/bus/src/server.mjs
• packages/cli/src/config.mjs
• packages/webui/src/bus.mjs
• packages/webui/src/cli.mjs
• packages/webui/src/decision-http.mjs (new)
• packages/webui/src/public/bus.js
• packages/webui/src/serve.mjs

Tests:

• packages/bus/tests/channel-proof.test.mjs (re-pins)
• packages/bus/tests/console-decide.test.mjs (new)
• packages/bus/tests/principal.test.mjs
• packages/cli/tests/config.test.mjs
• packages/webui/tests/decide-browser.test.mjs (new)
• packages/webui/tests/decide-sso.test.mjs (new)
• packages/webui/tests/decision-http.test.mjs (new)
• packages/webui/tests/shell.test.mjs (old test changed, see above)
• packages/webui/tests/tester-listener.test.mjs

Docs:

• packages/webui/README.md
• agents/scrooge/work/queue-252/BUILD.md (this file)

Results

Not run. At the first CLEAR:

1. Run each touched test file whole, with TMPDIR under /mnt/storage/scratch/tmp.
2. Run the bus, webui and cli suites.
3. Run the mutants above, then the drift check against refactor.

Rebase onto fe4ee8c7b (sage-3482, 2026-10-23)

The old base aca16404c had drifted. Since then refactor changed 8 of the row's 24 paths, across 15 commits. I made a new branch, scrooge/row252-fe4ee8c7b, so scrooge/row252 22cc74645 is untouched and nothing was force-pushed. I rebased with local git, -c core.hooksPath=/dev/null, and no stash.

Commit map:

• 4bd273bce -> 1891d36e4 (product and tests; six files conflicted)
• ca4537cc9 -> 9e5980acd (BUILD.md; clean)
• 22cc74645 -> 6fd206e80 (shell.test comment and BUILD.md; clean)

Conflicts, all in 4bd273bce, and how each was resolved:

1. packages/bus/src/broker.mjs, verb lists. On the base, row 206 added the share verbs to USER_VERBS, and row 275 added VIEWER_VERBS, userLevel and BOARD_VERBS and removed the USER_LEVEL const. I kept the base's lists and dropped USER_LEVEL, because nothing on the base reads it. CONSOLE_VERBS goes in after USER_VERBS with its comment unchanged. The request() gate (!!s.console !== CONSOLE_VERBS.includes(verb)) auto-merged after the FED R4 access sweep and the user check. Its order relative to the user gate is the same as on the old base.
2. packages/bus/src/runtime.mjs, startBroker. FED R4 (#1801) added access.intervalMs to the access check. I kept the consoleOwners validation and the frozen owners first, as in the row, and then the base's access check with intervalMs.
3. packages/cli/src/config.mjs. FED R6 (#1800) added accessFor and config.access. I kept both: accessFor and then consoleOwners, and in bootConfig config.access and then config.consoleOwners. process.mjs passes the boot config to startBroker whole, so both keys reach it.
4. packages/webui/src/cli.mjs. FED R6 moved the owner's bus options into consoleBus() (console-bus.mjs) and added userCaller and userOptions. I kept the base's form, added consoleCall to the bus.mjs import, and added decisionWrite to the declarations. I kept the row's if (ssoOn && sendOn) decisionWrite = consoleCall(...) after the consoleBus() call, and pass decisionWrite to startServer next to userOptions and federation.
5. packages/webui/src/serve.mjs. FED R6 added granted-user sessions: userRoute gates them, and userOptions rebinds the options per request.
   • The signature now has both decisionWrite and userOptions/federation.
   • The session hunk keeps the base's signer and granted-user block. ssoSession is set only for a session with no user, which is the owner's. A granted user is refused at userRoute before the decision route anyway, because /api/decisions/* is not on userRoute's list. Under the new base this keeps the design section 2 rule that only the owner answers a decision.
   • /api/config keeps the base's user and federation keys. decide gains !granted, matching how the base gates edit, so a granted user's config never offers Approve and Deny.
   • The decisionWrite startup check and createConfirmations() auto-merged unchanged.
6. packages/bus/tests/channel-proof.test.mjs, webui bus.mjs pin. Row 301 (#1808, mos-1449) moved the user transport into bus.mjs and re-pinned it to 39fcb27c. The row's consoleCall auto-merged on top. I kept row 301's comment and re-pinned to the merged blob's sha256, 604092cb706b152d458f299ff1071f6cd488774629012f96b672f7e9a16c0b2c. The human.mjs pin (bb13c146) auto-merged and matches the blob at the new tip. The row's existing header comment (Webby N5) still describes why bus.mjs is re-pinned. humanCall and transport() are unchanged.

Auto-merged without conflict: webui bus.mjs (consoleCall next to row 301's userCaller), webui README.md, bus client.mjs, human.mjs, principal.mjs, server.mjs and public/bus.js.

Two new-base reads I checked:

• granted-user.test.mjs reads /api/config key by key and has no deepEqual on the whole object, so the extra decide key doesn't break it.
• No other test pins one of the row's source files by sha256, apart from channel-proof.

Not run: no test, node or syntax check during this step. Sage's next CLEAR covers the push, the whole webui, bus and cli suites, every scripts/test-*.sh, and J1-J17. Plugins must show 0 failures (mos-1456/1462). J7 still needs a killer test. The serve.mjs !granted and ssoSession lines are new since the build, so they get mutants too. I'll add them to the J list at the run.

Runs (sage-3488 CLEAR, 2026-10-23)

Gate tree: detached worktree of 3e6de9807 with the canonical node_modules linked, so MOSAIC_REQUIRE_EDITOR_BUILD=1 is set (mos-1453). TMPDIR comes from mktemp under /mnt/storage/scratch/tmp. Each step runs under timeout -k 10 (mos-1275):

Step	Limit (s)
pkg bus, cli, plugins, webui, business (node --test tests/*.test.mjs)	1800 each
test-auth / conductor / config / discord / extension-package	126 / 145 / 130 / 147 / 130
test-foundation / land-work / queue / release / task	269 / 171 / 226 / 157 / 231
mutant single file	300, chat-browser 600

The script limits are 3x the longest runs recorded in queue-253 (receipt 3b91cfdaf).

First-run reds placed (mos-1272)

• pkg-bus at 3e6de9807: 902 pass, 1 fail. The failure is N2, J13 in console-decide.test.mjs:180, a new test (0 human.input rows found, 1 expected). The cause is in the test, not the product. events() spread the parsed body after the row's kind, so an answer body's own kind: 'answer' overwrote 'human.input' and the filter could never match. Three more filters on the same field had the same defect, :250 and :290 (count of human.input must be 0) and :252 (an action.refused exists). The two zero counts passed vacuously. Fix: the row's kind is also kept as event, set after the body, and all four filters read event. The deepEqual at :181 now names event: 'human.input'. The file then ran whole at 11 pass, 0 fail.
• J7 (open in the plan): no existing test bound a console proof over the socket. The new test J7: a console proof over the socket binds a cap for its one call and the reply releases it in console-decide.test.mjs serves a real socket with authenticateConsole, makes one console call that answers and one that refuses (decision-not-found), and checks that both caps are released (unauthenticated). J7 is applied as boundCap = kind === 'console' ? null : transient; in server.mjs, which skips every release path for a console cap (finish, the finally, and socket close). It ran at 11 pass, 1 fail, failing only the new J7 test. KILLED. The restored server.mjs matched its pre-mutant sha256.
• decide-sso.test.mjs (new) ran 2 pass, 2 fail before any mutant:
  • J16: its { send: null } case reached setup, and startServer refused it, because a decision transport without --send never starts (serve.mjs guard). That case now asserts the refusal, and the { decisionWrite: null } case still checks the read-only routes and decide: false.
  • N4: a POST to /api/bus/decision.* gets row 74's preview refusal (403 read-only, for every write without a route of its own) before any verb lookup. POST now asserts that refusal and GET still asserts 404. Either way the transport sees no call.
  • The file then ran whole at 4 pass, 0 fail.
• Old-test reds, sent to Sage before any fix (status 2):
  • cli access-boot.test.mjs R6 B1-B3 come from this row. The fixture's SSO provider has no issuer, so consoleOwners maps iss: undefined and startBroker refuses the owner list (invalid-host-request). The file is 4/0 on fe4ee8c7b.
  • cli compactions-launch.test.mjs REQ-THREAD-2 T3, 5 tests, each "timed out waiting". They also fail 0/5 on a fe4ee8c7b tree, so they are not this row's.
  • Correction (sage-3492): the compactions-launch reds were the environment, not a base red. The gate TMPDIR (<gate>/tmp) was long enough to break the launcher/bwrap paths. Alone in a short mktemp -d /mnt/storage/scratch/tmp/scrXXXXXX TMPDIR the file ran 5 pass, 0 fail, 0 skipped, and Sage's own gate ran it green. The file is unchanged.

Rulings and further placements (sage-3492 to sage-3496)

• access-boot (Mos GO mos-1464, relayed in sage-3494): access-boot.test.mjs:17's authentik provider gains issuer: "https://idp.test", and nothing else changes. numstat against fe4ee8c7b reads 1 1. It is committed alone (b316e0a55). access.test.mjs:273 uses the same fixture but never reaches bootConfig, so it is untouched. The file ran 4 pass, 0 fail.
• decide-browser.test.mjs (new) ran 0 pass, 3 fail before any mutant, then 1 pass, 2 fail after the first fix:
  • setup's UPDATE decisions SET question=? hit migration 3b's decisions_no_update trigger, because decisions is append-only. The test now writes its own open credential.mint grant decision, with the hostile question in the INSERT. It is the same two rows host-fixtures' grantDecision writes, and host-fixtures.mjs is unchanged.
  • page() visiting the URL it was already on was a same-document hash change, not a load. So J17's "closed elsewhere" step never re-read the bus, and the redirect test's second visit never redrew after signing out. page() now loads about:blank first, as editor-browser.test.mjs:216 does.
  • The file then ran whole at 3 pass, 0 fail (9e1601a20).
• decide-sso J16 (sage-3492): the startServer refusal stays. The one config that starts without send also lacks a decision transport, since startServer refuses a transport without --send. That config, { decisionWrite: null, send: null }, is now in the J16 loop and gets decide: false and the read-only routes. Webby rules in the manifest round.
• J19 killer (new test in decide-sso.test.mjs): an access document with one granted user (alice). The listener has --send, a decision transport and a user transport. The owner's config says decide: true. Alice's says user: true, send: true and decide: false. Her POSTs to both decision steps get 403 owner-only, and the transport sees no call.
• J18 is equivalent alone, because a granted session never reaches decisionHTTP. At serve.mjs:694 a session with user !== undefined meets userRoute before the decision branch. userRoute admits only /api/chat* and GETs of /api/config and the user files, never /api/decisions/*, so the 403 owner-only comes before ssoSession is read. The session.user === undefined guard is a second layer behind that. The J19 test's owner-only POSTs pin the first layer.
• J11c is equivalent. s.human !== b.human at broker.mjs:5604 can't hold for a console cap:
  • bindConsole (broker.mjs:1459) refuses record.human !== b.human with human-required.
  • Its cap carries human: b.human for its own business, and #cap freezes the session (:1094).
  • At resolve, b is this.#business(s.business) (:5324), the same business.
  • reloadBusiness refuses a document whose human differs (:517). So for any session with s.console set, the two humans are equal. Webby rules on it in the manifest round.
• Mutants, part 2, on the tip test files (decide-sso 5/0, decide-browser 3/0 as the baseline). Every restore matched its pre-mutant sha256.
  • J16a: KILLED by decide-sso J16.
  • J16b: KILLED by decide-browser J16.
  • J17a: KILLED by decide-browser J17 and the redirect test.
  • J17b: KILLED by decide-browser J17.
  • J19: KILLED by decide-sso J19. granted-user stays 19/0 under it.
  • J18: SURVIVED decide-sso 5/0 and granted-user 19/0. It is equivalent alone, for the reason above.
• Old webui stubs (Mos GO mos-1465, relayed in sage-3497): library-cli.test.mjs:17 and thread-claims.test.mjs:58 build a loader-hook stub of bus.mjs with no consoleCall export, and cli.mjs now imports it. Each busSource gains export const consoleCall=()=>{throw Error('consoleCall outside --sso')}; in the neighbours' throwing form, and nothing else changes. numstat against fe4ee8c7b is 1 1 for each. Alone they ran 1/0 and 4/0. No mos-1316 item for compactions-launch: the whole cli rerun is the evidence.