8.6 KiB
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.consoleanddecision.resolve.console. A console cap reaches nothing else (console-decideJ1, 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-treeconsole-cli.mjswrapper, its own nonce, a direct same-treeserveparent, and a configured owner subject from the spawn environment. recordEventkeepshuman.inputreserved, so no agent writes the record that lets a console close start the executor (console-deciderecordEvent keeps human.input reserved).- A
via consoleclose without its matchinghuman.inputapproves nothing (console-decideJ14).
Manifest checks N1-N5
- N1. Every
console.ssosubject is an owner of the business. Name is display only.cli/src/config.mjscarries{provider, iss, sub}per subject into the boot asconsoleOwners. No sso means no key.bus/src/runtime.mjsvalidates the list (array, at most 512, exactly three non-empty strings each) and passes it toverifyPrincipal.- Tests: cli config.test
Row 252 (Webby N1)and principal.test.
- N2.
human.inputis written in the same transaction, before#approvedGrant. The executor starts once, and a deny starts none.- Tests: console-decide
N2, J13checks the order by seq and that the grant runs once.J15checks that a deny starts nothing.
- Tests: console-decide
- N3. The close notice comes from
from_run 'human-console', andpublic/bus.jsshows "via console".landingand#protectedEndstay CLI-only.- Tests: console-decide
N2, J13checks the notice. decide-browserJ17checks the close-elsewhere line.
- Tests: console-decide
- N4.
decision.resolveis not a Console verb.CONSOLE_VERBSis exactly the two console verbs. The webui serveBUS_VERBSread list has no decision verb, and webuicli.mjshas nodecision.string.consoleCallrefuses anything outsideCONSOLE_VERBS.- Tests: console-decide
N4, and decide-ssoN4, which hits/api/bus/decision.*for 404 and covers the cli.mjs scan and the consoleCall refusals.
- N5.
readProcesskeeps the fiveMOSAIC_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.mjsimportsCONSOLE_VERBSfrombus/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.
consoleCallandhumanCallshare it astransport(), sowebui/src/bus.mjschanged. The busCallerbusinessdefault 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. Gatingdonewaits on Mos's ruling.- The
writeslist gains the newfetch(url, ...)indecidePost. It is first in file order (bus.js:362). - The
method:count goes from 7 to 8. - A new assertion pins
decidePost's callers tourlplus the two literal/api/decisions/${enc(a.id)}/...routes. - No existing entry was loosened.
- The
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 andtransport()) to 701f009e…5272.- Any later edit to either file needs a re-pin.
bus/tests/principal.test.mjs,webui/tests/tester-listener.test.mjsandcli/tests/config.test.mjshave 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:
- Run each touched test file whole, with TMPDIR under /mnt/storage/scratch/tmp.
- Run the bus, webui and cli suites.
- Run the mutants above, then the drift check against refactor.