# Row 76 (#1570): Console sends a human message to a role, round 1 Owner: Dewey. Reviewers: Darkwing and Filbert. Brief: `docs/plans/2026-10-11_dogfood-cutover.md` ยง "Console sends a message to a role", blob `f5d56554` (rev 552). Jason's Q95 answer is lead decision 95; the reply view question is lead decision 97, option (a). Base `3d298920` (row 60 landed). None of the candidate's paths changed between `3d298920` and `refactor` HEAD (`3d298920`) when the packet was built. `build.patch` is `git diff --binary 3d298920 -- packages/webui`, the two new test files included. Apply it with `git apply --index` to a detached worktree of the base; `candidate-manifest.sha256` then checks 9/9 OK. ## What ships `serve --public-host NAME --auth-header HEADER --allow-user ID --send`. `--send` is off by default; without it the Console behaves as after row 74 (`preview.test.mjs` and `serve.test.mjs` unchanged and green). **Start (`cli.mjs`, `serve.mjs`).** `--send` is the one flag without a value. Without all three preview flags the CLI exits 2 with `refused: --send needs the preview mode (...)`, and `startServer` throws the same for a direct caller, or for a `send` that isn't a function. With `--send` and no system config the start refuses (`--send needs the bus configured (...)`, the reason redacted as before) instead of serving a box that can't send; a read-only Console still serves without the config. The `Preview:` line says reads and human messages to roles, one line per send below. `busReader` is split into `busCaller` (the human transport call, the business resolved per request as before) and `views` over it, so the reads and the send use the same transport. **The route.** With `--send`, `POST /api/bus/message` is the one write preview mode lets past its read-only check; any other method on that path is 405, and every other write is still 403 `read-only`. Order, each on every request: 1. The shared checks from row 74 run first: repeated Host 400, HEADER with a Host other than NAME 403 `proxy Host refused`, a NAME request without HEADER = ID once 401, a sent Origin other than `https://NAME` 403. These write no log line. 2. `busSend` checks HEADER = ID once again itself (401), so the route never runs on a loopback Host: a loopback request without HEADER is 401, with it 403 `proxy Host refused`. There is no loopback send. 3. Origin sent once and exactly `https://NAME` (a missing Origin passes the shared check and stops here), else 403 `cross-origin request refused`. 4. `Sec-Fetch-Site` sent once and exactly `same-origin`, else 403 `cross-site request refused`. 5. `Content-Type: application/json`, at most 16384 bytes, a JSON object with `to` and `body`, optionally `in_reply_to`, no other key; else 400 `invalid-request`. 6. `message.send` with exactly those keys. The broker judges `to` and the body. Its limit, 32768 characters, is past the request limit, so 16 KiB binds first. Every answer after step 2 carries `sent`: `false` for a refusal, `"unknown"` when the message may exist. Success is 200 `{id, at}`. **Outcomes (`bus.mjs` `sendOutcome`).** The broker writes in one transaction, so any code it returns means nothing was written: `{error: code, sent: false}` at the read routes' statuses (`busStatus`), with `unknown-role`, `message-not-found` and `request-too-large` added as 400. `outcome-unknown`, `invalid-response` and `response-too-large` from the transport, any error that isn't a `BusReadError`, and an answer without a valid message id leave it open: 503 `outcome-unknown` with `sent: "unknown"`. Nothing retries. **Log.** One stdout line per request that gets past step 2: the time, `send`, `user=` (JSON-quoted), `to=` (JSON-quoted, cut to 64 characters, or `none`), then `id=` or `error=`. Never the body. A test shows a `to` with a newline can't forge a second line. **`/api/config`** gains `send`: true only with `--send` on a NAME request, so the operator's loopback page never shows a box that would get 401. **The page (`public/bus.js`).** With `send` true the Inbox has "Message a role": a picker of held roles from the agents read, a text box and Send. - The draft (role and text) lives in page memory, so the ten-second refresh redraws the form without losing it; focus and the caret are kept. A reload loses it. A role no longer held stays selected, marked "(not held now)". - Send is disabled while a send is pending; a second press sends nothing. An empty role or text is refused in the page without a request. - One POST per Send, `redirect: 'manual'`. Sent: an id came back; the receipt shows it and links `#/trail/message/` (a new trail kind: the message and its deliveries, back link to the Inbox, not-found for an id the trail doesn't hold). The text is cleared unless it was edited during the send. - Not sent: a 4xx, or the server's `sent: false` (a 503 `no-bus-host` too), or a redirect. Only the sign-in proxy redirects, when its session has expired, so the request never reached the Console; the receipt asks for a reload. The draft is kept. - Anything else, a lost answer included: outcome unknown. The receipt says the message may have been sent, that nothing was sent again, and that there is no trail to link without an id; the draft is kept. - The box says a reply comes back as a message the Console doesn't show yet, and the next `mosaic talk` prints it after sending its own message (decision 97). **Reply in the board (`public/app.js`).** A refused Reply said "Delivery may be unknown; check the seat before sending again" for a 403. A 4xx now says "Not sent."; no answer, an unreadable one or a 5xx keeps the old text. Row 74 left this for this row. **README.** A "Message a role" section: the command, what `--send` grants (anyone the proxy lets through as ID, and any local process that reaches the port and sets HEADER with `Host: NAME`; decisions 62 and 95), the request and each check, the broker's refusals and their statuses, the unknown outcome, the log line, the page's three receipts, and the reply path with `mosaic talk`'s limits (decision 97). The routes list gains the message trail; the "nothing writes" lines name the exception. Folded in from row 74 per the row note: Filbert N1 ("its first signed-in request"), Darkwing's tunnel sentence (anything reaching a tunnel's local end can send a loopback Host without HEADER, so bind it to loopback), and a pointer to `scripts/webui-service.sh`, which takes no `--send`. ## Decisions and tradeoffs 1. **No loopback send.** The brief asks for the header on every request, loopback included. A loopback request can't carry it (row 74 refuses HEADER with a loopback Host), so the operator's browser on `127.0.0.1` reads but can't send. `/api/config` hides the box there. 2. **The route checks the header itself** even though the shared check already did for NAME requests. It costs one line and keeps the route closed if the shared check changes. 3. **A missing Origin is refused on the send** (the shared check allows a missing one for reads). The brief asks for the request's own origin, and browsers send Origin on a POST. 4. **`Sec-Fetch-Site` is compared exactly**, so `Same-Origin` and a repeated header are refused. Browsers send the lowercase value once. 5. **Which errors mean "not sent".** The brief maps broker codes like the reads'. I treat every coded broker answer as definite, since the broker writes in one transaction, and only the transport's three lost-answer codes, an uncoded error or a missing id as unknown. The page adds 4xx and the redirect as definite. A proxy 4xx means the request wasn't accepted for forwarding; a proxy 5xx (502, 504) can come after the Console got it, so it stays unknown. 6. **The draft is in page memory, not storage.** The brief asks for it to survive the periodic refresh. Keeping it out of `localStorage` keeps a message body off disk on a shared browser profile. 7. **`--send` without the bus refuses to start.** The brief doesn't say. Serving a box that can only answer `not-configured` seemed worse than a refusal at start. ## Where the brief and the code differ (for Sage) - "Replies show in the inbox as today": they don't; the inbox shows decisions. Decision 97 settled it: the README and the box give `mosaic talk`'s limits, and the reply view is row 81 (#1575). - "Points at the trail" on an unknown outcome: there's no id to link, so the receipt points at the role's side and the bus trail from a terminal. - The log's `error=` value is the code as answered, unquoted; for the 403s it has spaces (`error=cross-origin request refused`). It is always last on the line. ## Rebase on row 60 I built this row on `bbd22f1b`. Row 60 landed first (`1771bf98`), so I applied my patch to `3d298920` with `git apply --3way`. Row 60's hunks in this row's files, and how each merged: - `packages/webui/src/serve.mjs`: row 60's `BUS_VERBS` line (adds `credentials`). It merged cleanly; my changes there are elsewhere in the file. - `packages/webui/README.md`: row 60's credentials read and its line in the exposure list. Merged cleanly, in different paragraphs from my "Message a role" section and the "nothing writes" lines. - `packages/webui/src/bus.mjs`: the header comment, the one conflict. Row 60 named its `credentials` read and I named the one write. The merged comment says both: ``` // Only the four verbs of the Q1 module (lead decision 56), row 57's // `decisions` and row 60's `credentials` reads are reachable as reads: no // read writes, not even seen (Q4). The one write is row 76's human // `message.send` (lead decision 95), built by the CLI only with --send. The // bus does the proof; a server started inside an agent run gets // `human-required` from the broker. ``` Row 60's `tests/bus.test.mjs` change isn't in a file this row touches. The mutants, the suites and the demonstration below ran on the rebased tree. ## Files | File | Change | |---|---| | `packages/webui/src/serve.mjs` | `busSend`, the route under `send`, `body()` limit parameter, `send`/`log` options, `/api/config` `send` | | `packages/webui/src/bus.mjs` | `busCaller` split out of `busReader`; `sendOutcome`; three codes added to the status map | | `packages/webui/src/cli.mjs` | `--send`, refused without the preview flags or the bus; the `Preview:` line | | `packages/webui/src/public/bus.js` | the "Message a role" box, the message trail kind, focus and caret kept across a refresh | | `packages/webui/src/public/app.js` | the Reply 4xx text | | `packages/webui/README.md` | the "Message a role" section and the folded-in row 74 notes | | `packages/webui/tests/send.test.mjs` | new, 13 tests | | `packages/webui/tests/send-browser.test.mjs` | new, 1 browser test | | `packages/webui/tests/shell.test.mjs` | the pinned write boundary: bus.js has exactly one write, this one | ## Tests `send.test.mjs` (13): `startServer` refuses `send` without the preview mode or as a non-function; the CLI refuses `--send` without the flags and without a configured bus (exit 2, nothing on stdout, the config path not named); the CLI with `--send` and a configured bus but no bus host running prints the `Preview:` line, answers a send 503 `no-bus-host` with `sent: false` through the real human transport, and logs one line without the body; without `--send` the route is 403 `read-only` and config says no send; with `--send` every other write (POST, PUT, DELETE, PATCH on the board, bus and page routes) is still 403 `read-only` and nothing reaches the board or bus; config says send only on NAME; 401 for no header, another user, a suffix, two values, loopback without the header and `localhost` with no Origin, and 403 `proxy Host refused` for loopback with it, none sent or logged; each request check (no Origin, no or wrong or repeated `Sec-Fetch-Site`, no or wrong Content-Type, a form, 16385 bytes, extra keys, `business`, missing `to` or `body`, not JSON, null, an array, a string) refused with `sent: false`, logged without the body, and 16384 bytes accepted; wrong Origins refused by the shared check; GET and PUT 405; exactly `to`, `body` and `in_reply_to` passed on; a crafted `to` can't forge a log line; each bus refusal with its status and `sent: false`, each open outcome 503 `unknown`, a missing id unknown, and one call each (no retry); the human transport request is exactly the business, `message.send` and the keys; against a real broker the message is written once as a human send (`from_role` human, `from_run` human-cli, class INFO) and `unknown-role`, `invalid-request` and `message-not-found` map to 400. `send-browser.test.mjs` drives the page in Chrome with an in-process broker for the roles and the trail and a stub for the POST (a send passes only with the proxy's https Origin, which a loopback page can't have): no box without `send`; the held roles; empty role and text refused without a request; the draft across a refresh; a 400 and a 503 `sent: false` refused with the draft kept; a redirect refused as `sign-in`; an unknown outcome, a network failure and a 200 without an id each unknown, with no trail link and no resend; one POST per Send, pinned as `{method, headers, body, redirect: 'manual'}`; Send disabled while pending and a second press ignored; text typed during a send kept; a plain success clears the text and keeps the role; the receipt's trail link opens the message's trail; an unknown message id is not found. ## Mutants `mutants.py` makes 21 single-site edits, one at a time, in a separate worktree of the rebased candidate (never the build tree). Each mutant runs against the whole webui suite, and the file is restored from the copy read before the edit. The baseline passed, the worktree was unchanged afterwards, and **21 of 21 were killed** (2026-10-12T00:40:39Z to 01:02:24Z). `mutants.txt` lists each mutant with the tests that killed it. - Route (`serve.mjs`): the route's own header check removed; Origin unchecked; `Sec-Fetch-Site` unchecked, or `same-site` let through; the limit raised to 64 KiB; extra keys allowed; `in_reply_to` dropped; the id check removed; the log's `to` unquoted and uncut; `/api/config` `send` true on loopback; the route open without `--send`; every write opened by `--send` (`send-opens-writes`, killed by the new "every other write is still 403" test). - Outcomes (`bus.mjs`): only `outcome-unknown` left open; `unknown-role` dropped from the status map. - Page (`bus.js`): no pending guard; the text cleared though edited during the send; a 5xx `sent: false` treated as unknown; an unknown outcome resent; a redirect treated as unknown; redirects followed; the message trail shown for any id. I ran 20 of these on the `bbd22f1b` build before the rebase. The 18 that finished there were killed too; the run was stopped for the rebase and its log is not in the packet. ## Demonstration `demo.mjs` runs the candidate's `startServer` with `--send`'s options against a real in-process broker (pm, cto and coder; coder claimed), driven over `node:http` on loopback with the headers the proxy and the browser send (`Host: NAME`, `x-authentik-uid: jason`, Origin, `Sec-Fetch-Site`). Three servers: `send`, `lost` (the broker writes, then the call throws `outcome-unknown`, as when the transport loses the answer) and `readonly` (no `--send`). `demo.txt` is its output on the gate worktree: ```text == a send, and a reply to the coder to coder 200 {"id":"8f66630d-cb38-4879-8119-fb3defd532c8","at":"2026-10-12T00:40:48.392Z"} to coder, in_reply_to the coder's message 200 {"id":"3a35d7b4-2020-464e-9bc3-5ee870c8b53f","at":"2026-10-12T00:40:49.041Z"} == refused before the bus no sign-in header (401, no log line) 401 {"error":"sign-in required"} loopback Host with the header 403 {"error":"proxy Host refused","message":"the proxy must forward Host unchanged"} another Origin (shared check, no log line) 403 {"error":"cross-origin request refused"} no Origin 403 {"error":"cross-origin request refused","message":"a send needs the Console's own Origin","sent":false} Sec-Fetch-Site: same-site 403 {"error":"cross-site request refused","message":"a send needs Sec-Fetch-Site: same-origin","sent":false} Content-Type: text/plain 400 {"error":"invalid-request","message":"Content-Type must be application/json","sent":false} 16385 bytes 400 {"error":"invalid-request","message":"body larger than 16384 bytes","sent":false} an extra key 400 {"error":"invalid-request","message":"a send takes to, body and an optional in_reply_to, nothing else","sent":false} GET 405 {"error":"method not allowed"} == refused by the broker a role the business lacks 400 {"error":"unknown-role","message":"not sent: the bus refused it (unknown-role)","sent":false} an empty body 400 {"error":"invalid-request","message":"not sent: the bus refused it (invalid-request)","sent":false} in_reply_to a missing message 400 {"error":"message-not-found","message":"not sent: the bus refused it (message-not-found)","sent":false} == the answer lost after the broker wrote unknown, not retried 503 {"error":"outcome-unknown","message":"the message may have been sent; nothing was retried. Check the trail before sending again","sent":"unknown"} == without --send POST is read-only 403 {"error":"read-only","message":"the Console preview is read-only"} == what the broker holds 8f66630d from=human/human-cli to=coder class=INFO in_reply_to=- body="Please look at row 76 before the cutover." 3a35d7b4 from=human/human-cli to=coder class=INFO in_reply_to=0536126f-c54a-40a5-999d-c7fe1c01d9a2 body="refactor" pm receives 1 message(s) from the lost-answer send: ["Lost answer test"] == the Console log, one line per send past sign-in 2026-10-12T00:40:48.392Z send user="jason" to="coder" id=8f66630d-cb38-4879-8119-fb3defd532c8 2026-10-12T00:40:49.041Z send user="jason" to="coder" id=3a35d7b4-2020-464e-9bc3-5ee870c8b53f 2026-10-12T00:40:49.057Z send user="jason" to=none error=cross-origin request refused 2026-10-12T00:40:49.058Z send user="jason" to=none error=cross-site request refused 2026-10-12T00:40:49.061Z send user="jason" to=none error=invalid-request 2026-10-12T00:40:49.066Z send user="jason" to=none error=invalid-request 2026-10-12T00:40:49.072Z send user="jason" to=none error=invalid-request 2026-10-12T00:40:49.281Z send user="jason" to="auditor" error=unknown-role 2026-10-12T00:40:49.535Z send user="jason" to="coder" error=invalid-request 2026-10-12T00:40:49.802Z send user="jason" to="coder" error=message-not-found 2026-10-12T00:40:50.173Z send user="jason" to="pm" error=outcome-unknown a body in the log: false ``` ## Gate (my run on the candidate) Detached worktree of `3d298920`, `build.patch` applied with `git apply --index`, the manifest 9/9 OK before and after. Suites one after another, `TMPDIR` in my scratch, Docker on, 2026-10-12T01:02:24Z to 01:09:40Z: | Suite | Result | |---|---| | `packages/webui` | 76 pass, 0 fail, 0 skipped, the browser tests included (14 new) | | `packages/bus` | 88 pass, 0 fail | | `packages/cli` | 114 pass, 0 fail | | `packages/control-board` | 124 pass, 0 fail | | business, conversation, discord, harness, ledger, mosaic, queue, runs, seat, tasks | all 0 fail (60, 182, 178, 59, 78, 69, 150, 41, 27, 71 pass) | | build-tokens `--check` | exit 0 | | test-auth, test-conductor, test-config, test-discord, test-extension-package, test-foundation | exit 0 (15, 17, 24, 66, 18, 44 passed) | | test-queue | 27 passed, 0 failed; its `verify`/`render --check` case skips outside the canonical checkout | | test-release | 14 passed, 0 failed (Docker, nothing skipped) | | test-task | 98 passed, 0 failed (Docker, nothing skipped) | `git status` afterwards shows only the patch's 9 staged files and the `node_modules` link. `core.hooksPath` stayed unset. ## Questions for reviewers 1. Decision 5: is a proxy 4xx safe to show as "not sent"? I think so for the proxies we'd use, but a reviewer who knows one that answers 4xx after forwarding should say. 2. Decision 7: refusing `--send` at start without the bus config, rather than serving reads and answering `not-configured` on each send.