# Mosaic Console Piece 4, #1507. The control board is the first and only WebUI screen. ## Run Start the existing board in one terminal, then the WebUI in another: ```sh node packages/control-board/src/cli.mjs serve node packages/webui/src/cli.mjs serve ``` Open http://127.0.0.1:7330/. Optional `--port N` and `--board http://127.0.0.1:7331` select another port or loopback board origin. `--business ID` picks the business the bus views read; without it they read the running bus host's business (`mosaic bus start `). Port 0 picks a free port. Ctrl-C stops each foreground server. No daemon, installation, account, login or deployment is added. The preview mode below checks one header a sign-in proxy sets; it signs nobody in itself. Only HTTP loopback board origins are accepted. The WebUI binds to IPv4 loopback by default, rejects a repeated Host (400), nonlocal Host and cross-origin requests, sends no CORS headers, refuses redirects and accepts only JSON object POST bodies up to 4096 bytes. Do not put the board behind a public proxy. Put the Console behind one only in the preview mode below, with a proxy that meets its contract. ## Preview behind a sign-in proxy (row 74, #1568) ```sh node packages/webui/src/cli.mjs serve --port 7332 \ --public-host NAME --auth-header HEADER --allow-user ID ``` The three flags go together; one or two refuse at start, before any config is read. NAME is a DNS name, no scheme or port. HEADER is a header name other than Host or Origin; Node lowercases incoming header names, so it matches without regard to case (`X-Example-Uid` on the flag finds `x-example-uid`). ID is the one user id, 1 to 256 visible ASCII characters without a comma, and the value compare is exact. The Console still binds to loopback only. It names no identity provider and has no login code: the proxy signs the user in and limits sign-in to the right group. In preview mode: - A request whose Host is exactly NAME must carry HEADER once, with a value equal to ID. Missing, different or repeated answers 401 `sign-in required` before any route runs, so no bus read or board call is made. An Origin, when sent, must be `https://NAME`. - A request whose Host is loopback on the Console's port (`127.x`, `localhost` or `[::1]`) is checked as before and needs no HEADER, so the operator's browser on the host still works. Any other Host is 403. - A request that carries HEADER with any Host but NAME answers 403 `proxy Host refused`. The operator's browser never sends HEADER; a proxy that rewrote Host does, and it fails on its first request instead of reaching the loopback path unchecked. - More than one Host header answers 400 before any other check, in this mode or not. Node keeps the first, so a loopback Host followed by `Host: NAME` would otherwise skip the sign-in check. - Every method other than GET and HEAD answers 403 `read-only`, whatever the Host. `/api/seen` and `/api/reply` never reach the board, so Seen and Reply fail in the page with that refusal. - The GET routes are unchanged: the bus views, the Queue, Business and Settings reads, the board panel and the assets. If the board is down, its panel shows the existing error and the bus views still answer. What the proxy must do. The Console trusts HEADER only because the proxy controls it: - It terminates TLS for NAME and is the only thing that reaches the port from off the host. - It strips HEADER from every client request and sets it only after the identity provider signs the user in. - It forwards only requests whose Host is NAME, and forwards that Host unchanged. nginx rewrites Host to the upstream by default; set `proxy_set_header Host $host;` (or the literal NAME). Caddy and Traefik keep the client's Host by default. - Any loopback Host on the Console's port, `localhost` included, is the operator's path and skips the header check, so a proxy that forwarded a client's `Host: 127.0.0.1:7332` would let anyone through without signing in. A tunnel whose local end uses the same port number sends such a Host and reaches the Console unchecked. - Every hop on this host that reaches the loopback port is bound by this contract too, not only the edge. The local exposure doesn't change ("Data and boundaries"): any process on the host can still connect to the port and send `Host: NAME` with HEADER and ID, or just a loopback Host, and read what a reader capability reads. The user id is not a secret; the sign-in at the edge is what keeps others out. ## Use - Waiting on you uses the board's `waitingOnYou` flag across all projects. - Select a project on the left to filter the session table. Counts show visible rows out of the total when Hide offline or Hide seen hides anything. - Select an agent to open its inspector. Arrow keys move between table agent buttons, Enter opens, and Close or Escape in the inspector returns focus. - Seen clears the row from Waiting on you until the board detects new activity. The collapsed Seen section keeps those rows available; Unsee returns them. - Reply appears only where the board's registration permits it. A failure shows the board's stderr and keeps the draft. Transport success is the board's `delivered` receipt, not proof that the seat processed the message. - Refresh runs the existing board scan. Automatic refresh uses the board page's ten-second interval; Pause stops it. Failed refreshes keep the last snapshot with a warning. There are no automatic action retries. - Palette and appearance come from `tokens.css` (see "Shell" below) and persist in this browser when local storage is available. Appearance defaults to System. Settings (row 54) shows the same control and nothing else that changes. - History opens a read-only conversation view for a seat, from its Waiting card, its table row or its inspector (#1507, CHAT-02). It shows the whole branch with nothing clipped. Tool calls, tool results and thinking start collapsed. Session text is always shown as text: Markdown stays as source, and terminal controls, bidi controls and marks show as visible symbols. Reply in the view uses the same board reply path as the inspector. - The view checks for new entries on the same ten-second refresh, and Pause stops it. It never switches on its own. A fork, a newer session for the seat or a rewritten file each shows a marker with a button to open the other history. Reloading after a rewrite keeps the branch the view was on; if that branch is gone, the view opens the latest one and says so. Session lists older sessions for the seat, and is empty while the list is read or when that read fails. Only repository Pi seats have history; other harnesses say so. Drafts and receipts stay in page memory, including across refresh, inspector changes and a stale registration. Reloading or closing the page loses them. A pending send stays disabled across refresh; new text typed during a send is not cleared by the earlier send's success. If the proxy loses the response, delivery may be unknown: inspect the seat before sending again. ## Inbox, tasks, agents and trails (slice 1 S5, #1522) The Console sidebar adds Inbox, Tasks and Agents next to the control board, which stays at `#/`. Routes: `#/inbox`, `#/inbox/`, `#/tasks`, `#/tasks/`, `#/agents`, `#/trail/task/` and `#/trail/decision/`, with `?kind=` filters on a trail. The design note is `agents/dewey/work/wui/SLICE1-VIEWS.md`. - Every view reads the four verbs of the Q1 module (`packages/bus/src/views.mjs`, lead decision 56): `inbox`, `tasks`, `agents` and `trail`. The CLI reads the same functions, so both show the same broker data. - Nothing writes. A decision shows `mosaic decide ` for each choice, with Copy, which only puts the command on the clipboard. It is answered in a terminal (REQ-DEC-3, Q4). Seen is not set from the browser either. The command has no `--business`, so `mosaic decide` uses the running bus host's business, as the Console does by default. From a Console started with `--business` for another business the copied command refuses (no bus host, or no such decision) rather than answering elsewhere. - What no Q1 verb returns is labelled where it would show, for example "Bot names: not in the Q1 module" (lead decision 63). Nothing is guessed. - A task's list row can only say its current state came from a Vikunja read, since the list has no trail. The task page reads the trail and tells a task the stack never created from one changed in Vikunja after the stack wrote it. A stale poll read is shown in the snapshots and never as current. - The Tasks table has Requirement and Priority columns, from the `tasks` row's `requirement` and `priority` (row 58, #1547). Either one shows "none" when the row has none. A tombstone's page shows the priority of the last snapshot that read the task. - All bus- and agent-authored text is rendered inert: controls show as control pictures or `[U+XXXX]`, and Markdown stays as source. - Views refresh on the board's ten-second interval and stop on Pause. Focus, open sections and the copy status survive a refresh. - A failed read keeps the last good answer for that read and says it is old, with the time it was read. A refusal (403, `not-configured`, `no-bus-host`, or row 54's `queue-refused`) never shows kept rows (row 53), and it drops every kept read: the Inbox count and the palette's decisions, tasks and queue rows go too, until a read succeeds. A page never read, or refused, shows the failure instead, titled "Bus refused the read" (403: the bus refused the Console's read, for example `human-required` from a Console started inside an agent run), "No bus to read" (no system config, or no bus host and no `--business`) or "The read failed". ## Shell (row 53, #1542) The Console is restyled to `docs/design` (`IMPLEMENTING.md`). It is a restyle only: no new data, route or write. - `src/public/tokens.css` and `src/public/icons.svg` are byte copies of `docs/design/tokens.css` and `docs/design/icons.svg`; `tests/shell.test.mjs` fails if either differs. Edit `docs/design`, rebuild there, then copy. - Colours come only from `tokens.css`, selected by `data-palette` and `data-mode` on ``. The page sets no colour inline. Appearance System removes `data-mode`, so the OS light or dark setting applies; it is the default, with Harbor. The choice is kept under `mosaic-console-appearance`. - `shell.css` loads last and holds the restyle: radii `--r` 6px and `--r-lg` 10px, the type scale, tabular numbers, the command bar, section list, dense table, inspector, status marks, class chips, toast, command palette and not-found page. The earlier CSS files are unchanged. - JetBrains Mono 400, 500 and 700 come from the official JetBrains release (v2.304); `assets/fonts/jetbrains-mono-sources.txt` has the URL and sha256 of the archive and each file, and `jetbrains-mono-OFL.txt` the licence. Manrope has no 800 file here, so 800 headings render at 700. - Ctrl+K (or the search field) opens the palette over views, inbox decisions, tasks and (row 54) queue rows from the last queue read; arrows move, Enter opens, Esc closes and returns focus. Arrow keys also move between task links in the bus tables. - Copy reports in a toast. If the clipboard is unavailable, the toast stays until dismissed and the command is selected for Ctrl+C. When no toast shows, the toast is an empty live region, visually hidden but still in the accessibility tree, so the first copy is announced. - The command bar shows, in UTC, when the board was scanned and the bus read, and says when the last attempt failed. A board refusal drops the last scan and everything drawn from it: the cards, the table, the inspector, the project filter and tree, the counts, the footer and the scan line all say the board was not read. A failed read with no scan held, after a refusal or before the first scan, shows the board empty and says the read failed; it never brings back rows from a refused scan. A refusal also closes an open conversation and clears its history. If that removes what had focus, focus moves to the page. - From 760px the footer is a one-line status bar and the side column fits between it and the command bar. Below 760px the section list is one strip that scrolls inside itself. ## Queue, Business and Settings (row 54, #1543) Three read-only views, in the section list and the palette. Each has the same five states as the bus views: loading (the skeleton names the source), normal, empty, a failed read over kept data (labelled stale, with its time), and a refusal that shows nothing kept. The command bar names the source: "Queue read …", "Business not read: refused". A refusal shows the code in mono and the module's own message, redacted by the server. - `#/queue` lists every row with its state, owner, reviewers, brief and last update, filterable by state. `#/queue/` adds the gate, issues, claim, `after`, note and review rounds. Rows move only with `scripts/mosaic queue move` in a terminal; the row page shows that command with a Copy button and has no button that moves a row. The brief is shown as its path and anchor, because Console serves no repository files. - `#/business` shows the business named by `--business`, else the running bus host's business: the human, the arbiters as instance and kind ("pm (delivery), cto (technical)"), projects, launch rules, the vars on an allowlist, each role instance with its holder and harness, the authority of each instance for each action as the business package classifies it (`resolveInstance`, `classify`), and credentials as metadata only: service, account, role, expiry or rotate-by date, and a state worked out from the date alone. A missing or invalid business file is a `not-configured` refusal with the business module's own text. - `#/settings` shows appearance (the row 53 control, kept in this browser), the notifier binding by name only, and about: the Console's loopback address, `RELEASE`, the business and the board URL. A Settings refusal still shows appearance, because it needs no read. Console never reads a token, a token file or a credential variable, and no response, page or log carries one, a file path or a Discord channel, guild or user id. The server redacts every message and string field before it answers (`redactor` in `src/reads.mjs`): the config directory becomes ``, the data root ``, any other absolute or `~/` path ``, a 17 to 20 digit run ``, and a JSON parse error's quote of the file is dropped. The startup log goes through the same redactor. A path starts at the beginning of the text or after a space, an opening bracket, a quote, `=`, `,`, `<` or `:`, so `file:/x` and `file:///x` are redacted and `https://host/x` is not. Known gap: a path stops at the first space, so a path containing a space is redacted only up to that space and the rest shows. A bare `~` or `~user/` is not treated as a path, and neither is a relative path. ## Data and boundaries GET `/api/board`, `/api/conversations` and `/api/conversation`, and POST `/api/seen` and `/api/reply` proxy only those board paths. Only the two conversation routes carry their query string; the board validates it. POST bytes and upstream status/JSON are preserved. GET `/api/config` returns the configured board URL for the page's error message. No scanner, registration, session reader or transport is implemented here. The session reader is `packages/conversation`, served by the board. GET `/api/bus/inbox`, `/api/bus/tasks`, `/api/bus/agents`, `/api/bus/trail?subject=`, `/api/bus/decisions?list=roles|recent` and `/api/bus/credentials` are the bus reads (`src/bus.mjs`). Any other method is 405. The subject must match the broker's identifier rule, and the list must be `roles` or `recent`, else 400. `decisions` (row 57, #1546) is for the Inbox tabs "Routed to roles" and "Recent"; "Human and reader paths" in `packages/bus/README.md` has what each list holds. `credentials` (row 60, #1549) is the bus host's credential status: service, account, role, date and state for each credential it loaded, never a token, file path or variable name. No page uses it yet; the Business view still shows the business file's metadata. Each read runs the S4 human transport (`packages/bus/src/human-cli.mjs`) as a child process, so a slow read doesn't stall the server. The bus checks that child's ancestry, which ends at the Console process; it never sees the browser or any other client of the port. So while the Console runs, anything that can connect to its port (7330 by default) reads what a reader capability reads ("Human and reader paths" in `packages/bus/README.md`): the inbox, tasks, agents, trails, the two decision lists and the credential status. That includes a T3 seat using `curl` and a managed S6 session, since S6 doesn't confine the network. No route writes (Q4), so the exposure is reads only. Slice 1 doesn't change this (Filbert F1 on #1522). Answers are `{ rows, at }`; failures are `{ error, message }` with 403 for a refusal, 503 for no bus or no answer, and 502 for an answer that can't be used. The bus needs the system config (`~/.config/mosaic-dev/config.json`); without it the board still serves and the bus routes answer `not-configured`. GET `/api/queue`, `/api/queue/`, `/api/business` and `/api/settings` are row 54's reads (`src/reads.mjs`), under the same Host, Origin and CSP rules. Any other method is 405, and a queue id that is not a positive integer is 400. The queue is read in a child process (`src/queue-read.mjs`) through `rows()` from `packages/queue/src/store.mjs` (lead decision 83): the same read as `queue list`, with no write and no network. Like `list`, it takes the queue lock only to recheck a disagreement before reporting it. The child imports the store inside its `try`, so a store that fails to load reports "the queue read failed". Only the store's exit 2 (invalid data or refused) forwards the child's text, as `queue-refused`; any other exit is the fixed `read-failed` message "the queue read failed (exit N)", because that stderr may be Node's own, with a `file://` path and a stack. The business read uses `packages/business` in process. No read writes, calls out or adds a dependency. Answers carry `at`; failures are `{ error, message }` with 503 for `not-configured`, `no-bus-host`, `queue-refused` and `read-failed`, 404 for a row that isn't there, 400 for a bad address and 502 otherwise. Settings answers 200 even without a system config, so appearance always works; its notifier part then says `not-configured`. Console's shared CSS, Console CSS, brand.js and local Manrope fonts were copied unchanged from `agents/dewey/work/wui/`. Font license and source URLs accompany the files under `src/public/assets/fonts/`. `live.css` contains the live-page adaptations; original mockups and unrelated pending design work stay untouched. Unsupported mockup fields and controls are listed in `docs/plans/DEFERRED.md`. The source tree is a project filter; no invented workspace registration tree or mockup session hierarchy is presented as live data. ## Verify ```sh node --test packages/webui/tests/ node --test packages/control-board/tests/ packages/seat/tests/ packages/ledger/tests/ packages/mosaic/tests/ WEBUI_EVIDENCE=/tmp/webui-evidence node --test packages/webui/tests/browser.test.mjs WEBUI_EVIDENCE=/tmp/webui-evidence node --test packages/webui/tests/conversation.test.mjs WEBUI_EVIDENCE=/tmp/webui-evidence node --test packages/webui/tests/bus-browser.test.mjs WEBUI_EVIDENCE=/tmp/webui-evidence node --test packages/webui/tests/shell.test.mjs node --test packages/webui/tests/reads.test.mjs packages/webui/tests/views.test.mjs ``` Node's test runner and installed `/usr/bin/chromium` are required. Set `CHROMIUM` to another installed Chromium path. No npm download is needed. The copied CDP helper starts a separate temporary browser profile and removes it on exit. Tests use temporary board session/registration files and stub the board's transport. They never send to real seats or read real session logs. Browser tests exercise the rendered real board fixture, exact counts, project filtering, keyboard return focus, Seen/Unsee, success/failure receipts, draft and caret preservation, pending-send exclusion, storage denial, stale registration, loading/empty/malformed/unreachable states and hostile text. Contrast is measured on 330 rendered samples across ten palettes and three modes. Layouts are checked at 320, 390, 768, 1440 and 2560px. Horizontal scrolling is intentional within the dense table; the page itself must not overflow. Conversation tests run the real board routes over temporary repository-layout session files. They cover full-length answers, collapsed tools and thinking, hostile content rendered inert, malformed-line and reconcile markers, forks, and the return flow: a send from the view, a tool call and a delayed result while a draft is typed, a peer message, a 4.5-million-character answer split into continuation parts, and a relaunch mid-turn. Bus tests (`bus.test.mjs`, `bus-browser.test.mjs`) run the routes and the views against an in-process broker read through its reader session, so every row has the broker's own shape. `humanCall` runs against a stub CLI script. They cover each view, the gap labels, inert hostile text, Copy, the stale fallback and each failure title, and that no route writes. They never start the human CLI against a live bus. Shell tests (`shell.test.mjs`) check the copies, the font hashes and the kept strings, and in the browser at 400px: System mode under an emulated dark and light OS, the empty, stale and refused states of the board and the bus views (a failed first read drawn empty, a board refusal with the inspector open and a project picked, then a failed read, a failed session list, and a refusal with a conversation open and where focus lands after it), not found, the palette, the toast, keyboard and visible focus, the section strip at 360 and 400px, no sideways scroll, no script error and no request other than GET. A second test walks the Board, Inbox, Tasks, Agents and a decision trail through loading (a held read), normal, a failed read over kept rows, and a refusal by the bus (`human-required`) and for want of one (`no-bus-host`). It then checks that a refusal empties the palette and the Inbox count, from a view, from the palette's own reads and from the board page, and that palette labels are text. Row 54's tests share the seeded fixture in `reads-fixture.mjs`: a scratch queue whose row note names an id and token paths shaped like real notes (absolute, `~/` and after `file:`; the store refuses `<` in a note, so the `<…>` case is in the redactor test), and a business, notifier config and Discord binding that hold token files, an environment variable name, an agent `model` var holding a path, and guild, channel, bot and user ids. Row 9's After entry has the `{id, when}` shape the real queue stores. `reads.test.mjs` checks each route's body and status, the redactor, the credential state, methods and Origin, and that no body carries any seeded value or the temporary directory; that a `store.mjs` with a syntax error, or none, gives the fixed message with no path; and that the child's timeout, output cap and non-2 exits hold, over a fake child script. `views.test.mjs` walks Queue, a queue row, Business and Settings through the five states over a stub read, with each refusal code the view can meet, at 400px; checks that a refusal leaves no queue row in the palette, that no view has a control but Copy and Read again, and that the row page shows the `queue move` command, that the 10 s refresh keeps focus on a Settings mirror select, and that the palette keeps its queue rows after its own inbox and tasks reads answer; then, over the seeded fixture, that the Arbiters line reads the business file's object, that neither the page nor any response it read carries a seeded value, that a missing or invalid business file shows the module's text, and that the startup log names no config path. No root CI workflow is configured for this package. These local tests are not a claim of CI, deployment, live-seat delivery or user acceptance. ## User test and rollback Gate E belongs to Jason on Monday 2026-09-14. Use Console to find who is waiting, open a registered repo seat, reply and see its next answer after a scan. Mark a completion Seen and find it again in Seen. Record any reason to open the board's own page or a repo seat terminal in DEFERRED.md. Pass is Jason's end-of-day say-so, not a test result. Keep #1507 open pending that ruling. Rollback requires only stopping the WebUI and using the unchanged board at 7331. Revert the scoped WebUI commit to remove it; there is no data migration to undo. Seen and reply actions already taken belong to the board and are not rolled back.