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

8.6 KiB

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)

  • webui/tests/shell.test.mjs, write-boundary test. Gating done waits on Mos's ruling.
    • 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.

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.