stack/docs/plans/2026-10-10_design-implementation.md

Design implementation: console and terminal rows (2026-10-10)

Status: written by Sage, lead. It follows docs/plans/BRIEF-TEMPLATE.md. Jason accepted the design direction and handed the queue to Sage (Mos relay, DECISIONS 1a312ff: "That design can be immediately implemented by the Mosaic Stack agents ... I am going to leave this in your power"). Lead decision 81 records the shape. The design package is docs/design/ at 811e7ba5. Every row below reads docs/design/IMPLEMENTING.md first; its sections "Strings to keep exactly", "Boundaries" and "Acceptance" apply to every row and are not repeated here.

Two rules apply to every row in this file.

• The Q14 freeze holds packages/bus, packages/tasks, packages/cli, scripts/bus-service.sh and scripts/mosaic until ops-01 reports the Q14 hold ended. A row that needs one of those paths doesn't start before then. Importing from them is fine; changing them is not.
• No commit to the checkout, queue moves included, from 2026-10-11T15:00Z until ops-01 reports the hold ended. Work in your own scratch tree during that window and commit nothing.

Design questions go to Sage, who relays them to the design session (tmux mosaic-design) and back.

Console tokens and shell restyle

Problem

The console in packages/webui sets its colours inline: theme() in packages/webui/src/public/app.js loops setProperty over brand.js values. It has no shared component set and no loading, empty, error or refusal states. The design (docs/design/tokens.css, icons.svg, mosaic-stack-design.html) defines the tokens, icons, components and five view states, and IMPLEMENTING.md sections "Tokens", "Icons and the mark" and "Components" give the adoption steps.

Owner and reviewer

• Owner: Dewey.
• Reviewers: Darkwing and Filbert.

Files owned

• packages/webui/src/public/ (not shared/, which other packages read)
• packages/webui/src/serve.mjs, only to add the new static files to the files map
• packages/webui/tests/
• packages/webui/README.md
• agents/dewey/work/queue-53/ for evidence

docs/design/ is read-only for this row. Copy tokens.css and icons.svg into src/public/, and add a test that fails when the copy differs from docs/design/.

What ships

• tokens.css served through the files map; theme() stops setting properties inline. data-palette and data-mode stay. Add a System choice that removes data-mode. The localStorage key stays mosaic-console-appearance. Harbor following the system setting is the default (decision 81).
• --r 6px and --r-lg 10px, the type scale from "Tokens", and tabular numbers in tables.
• JetBrains Mono 400, 500 and 700 self-hosted, from the official JetBrains release only, with each file's sha256 and the OFL text committed beside it. If the seat can't fetch the release, ship the system monospace stack and say so in the packet. Sage files the font as a follow-up.
• The icon sprite, with the mark in one component and the placeholder Relay mark.
• The command bar, section list, dense table, inspector, status mark, class chip, copy command, toast, command palette (Ctrl+K) and not found.
• Five states (normal, loading, empty, error with stale data, refusal) on Board, Inbox, Tasks, Agents and Trail. Restyle only. No new data, endpoints or writes.
• Tests: node --test tests/ in packages/webui green, the browser checks from "Acceptance" (no script errors, no sideways scroll at 400px, keyboard path, visible focus), seeded empty, stale-error and refusal states, and the string grep test.

Out of scope

New views (row 54), the terminal app (row 55), any backend read (rows 56 to 61), Decision Seen from the web (decision 81: not in v1), and the control board's own page on port 7331.

Gate

Darkwing and Filbert approve on the row's issue, each naming the candidate manifest. On Sage's gate rerun, packages/webui tests, node docs/design/tools/build-tokens.mjs --check and every scripts/test-*.sh are green.

Read-only console views: Queue, Business and Settings

Problem

The console can't show the queue, the business file or settings. The data exists in modules with no endpoint: list and show in packages/queue/src/store.mjs, loadBusiness in packages/business/src/business.mjs, loadRole and resolveInstance in packages/business/src, and readNotifyConfig in packages/cli/src/cli.mjs.

Owner and reviewer

• Owner: Dewey, after row 53 (both change app.js and the shell).
• Reviewers: Darkwing and Filbert.

Files owned

• packages/webui/src/ (not public/shared/)
• packages/webui/tests/
• packages/webui/README.md
• agents/dewey/work/queue-54/

No change to packages/queue, packages/business or packages/cli. If a module lacks a read the view needs, stop and tell Sage.

What ships

• GET JSON endpoints /api/queue, /api/queue/<id>, /api/business and /api/settings. Keep the existing CSP, Host and Origin checks. No write, no network call, no new dependency.
• Views #/queue, #/business and #/settings, with all five states. A missing or invalid business file shows the refusal state with the module's own refusal text.
• Secrets as metadata only. Show service, account, role and expiry. No value, token or file path appears in any response or log. Notifier settings show binding names only, never a Discord channel, guild or user id. A test asserts each of these on a seeded fixture that holds such values.
• Settings: appearance (the row 53 control), notifications (names only) and about (loopback address, RELEASE). Read-only apart from appearance.
• Queue rows show state, owner, reviewers and the brief link. Rows move only through queue move; the view shows that command, not a button.
• Tests as in row 53.

Out of scope

The Ledger view: the ledger CLI calls Gitea and reads the T3 database, so it needs a cached report first and gets its own row later. Runs and releases (row 56). Any backend read for the bus (rows 57 to 61).

Gate

As row 53, plus the secret and id assertions above passing.

Full-screen terminal app

Problem

mosaic with no argument exits 4 with usage. The design specifies a full-screen terminal app (IMPLEMENTING.md "The full-screen terminal app") built on the conversation Terminal class (packages/conversation/src/terminal.mjs:54).

Owner and reviewer

• Owner: Darkwing.
• Reviewers: Dewey and Filbert.
• Starts after ops-01 reports the Q14 hold ended (packages/cli is frozen). Rebase on row 41 if it has landed by then.

Files owned

• packages/cli/src/ (new app modules, and the no-argument entry)
• packages/cli/tests/
• packages/cli/README.md
• docs/TOOLS.md, the mosaic entry
• agents/darkwing/work/queue-55/

What ships

• No-argument mosaic on a TTY opens the app (decision 81). Not on a TTY it keeps today's usage text and exit 4. In an agent run it exits 3 through transport.mjs.
• Screens Inbox, Tasks, Agents, Trail and Help, with keys c, i, t, a, r, j, k, :, ? and q. Decide shows and runs the existing mosaic decide flow with its strings unchanged.
• 16 ANSI colours, NO_COLOR honoured, fits 80x24, designed at 120x36.
• No new dependency.
• Tests: every screen fits 120 columns and 80x24, NO_COLOR output has no escape codes, an agent-run environment exits 3, a non-TTY exits 4 with the usage text, and the string grep test.

Out of scope

Talk and stop (after row 41), Decision Seen (needs its own CLI verb row), the web console.

Gate

Dewey and Filbert approve on the row's issue naming the candidate. packages/cli tests and every scripts/test-*.sh are green on Sage's gate rerun.

Runs and releases reader module

Problem

The run and release readers live inside scripts/mosaic-task.mjs and scripts/release.sh and aren't exported, so the console can't show runs or the active release.

Owner and reviewer

• Owner: Rocko.
• Reviewers: Darkwing and Filbert.

Files owned

• a new packages/runs/ (module, tests, README)
• scripts/mosaic-task.mjs, only to import the extracted readers
• agents/rocko/work/queue-56/

What ships

• A read-only module that lists runs under <dataRoot>/runs/, reads one run's result.json and reads the release pointer and activation log under <dataRoot>/state/. It never writes, prunes or follows a symlink out of the data root.
• mosaic-task.mjs list and show use it, and their output is byte-identical before and after on a seeded data root.
• Tests in packages/runs and scripts/test-task.sh green.

Out of scope

The #/runs view (a later row on this module), release.sh behaviour, and pruning.

Gate

Darkwing and Filbert approve naming the candidate. packages/runs tests and every scripts/test-*.sh are green on Sage's gate rerun, with the byte-identical output check in the packet.

Bus read: decisions routed to roles and recent decisions

Problem

inbox returns open decisions for the caller's role only. The design's Inbox tabs "Routed to roles" and "Recent" need a reader op for decisions routed to other roles and for closed ones.

Owner and reviewer

• Owner: Filbert, after row 41 (S6 rewrites packages/bus).
• Reviewers: Darkwing and Dewey.

Files owned

packages/bus/, packages/webui/src/bus.mjs and its tests, and agents/filbert/work/queue-57/.

What ships

A reader op and its webui endpoint, read-only, with tests. The reader session's authority doesn't widen: it reads what a human reader may read today, and a test shows a role session can't use it to read another role's open decisions.

Out of scope

Decision Seen and any write.

Gate

Darkwing and Dewey approve naming the candidate; bus, webui and every scripts/test-*.sh green on Sage's gate rerun.

Bus read: task priority and requirement

Problem

Priority isn't in task_current.fields, and the requirement sits only in the task.created event body, so the Tasks table can't show either.

Owner and reviewer

• Owner: Darkwing, after row 41.
• Reviewers: Dewey and Filbert.

Files owned

packages/bus/, packages/tasks/, the webui Tasks endpoint and tests, and agents/darkwing/work/queue-58/.

What ships

Both fields in the task read model, with a projection rebuild test, and the two columns in the Tasks view.

Out of scope

Field writers (row 61).

Gate

Dewey and Filbert approve naming the candidate; bus, tasks, webui and every scripts/test-*.sh green on Sage's gate rerun.

Bus read: agent state per role

Problem

The control board has state and Input needed per seat; the bus has nothing per role. The Agents view needs both per role.

Owner and reviewer

• Owner: Filbert, after row 41.
• Reviewers: Darkwing and Dewey.

Files owned

packages/bus/, packages/control-board/ (read side only), the webui Agents endpoint and tests, and agents/filbert/work/queue-59/.

What ships

A seat-to-role mapping read from committed data, or state on the bus. The packet says which and why. The Agents view shows the state mark and Input needed per role. Read-only.

Out of scope

Launch budget and stop (after row 41, a later row).

Gate

Darkwing and Dewey approve naming the candidate; bus, control-board, webui and every scripts/test-*.sh green on Sage's gate rerun.

Bus read: credential status on the broker

Problem

Credentials.status() (packages/bus/src/credentials.mjs:118) isn't exposed on the broker, so the console can't show credential health.

Owner and reviewer

• Owner: Filbert, after row 41.
• Reviewers: Darkwing and Dewey.

Files owned

packages/bus/, the webui endpoint and tests, and agents/filbert/work/queue-60/.

What ships

A broker read op returning service, account, role and expiry only. A test on a seeded store holding a value, a token and a path shows none of them in the op's output or the host log.

Out of scope

Any credential write, rotation or new credential.

Gate

Darkwing and Dewey approve naming the candidate; bus, webui and every scripts/test-*.sh green on Sage's gate rerun.

Task field-writer table as data

Problem

Which actor may write which task field is prose in docs/plans/2026-10-04_slice-1.md lines 62-72. The task inspector needs it as data.

Owner and reviewer

• Owner: Darkwing, after row 41.
• Reviewers: Dewey and Filbert.

Files owned

packages/tasks/, the webui Tasks inspector and tests, and agents/darkwing/work/queue-61/.

What ships

The table as a committed data file with a schema, a test that the writers the code enforces match it, and the inspector showing who may write each field. The slice 1 prose stays the reviewed source; if the code and prose disagree, stop and tell Sage.

Out of scope

Changing who may write a field.

Gate

Dewey and Filbert approve naming the candidate; tasks, webui and every scripts/test-*.sh green on Sage's gate rerun.

After row 41: Talk, launch budget, stop and Library

Not a queue row yet. Sage briefs these when row 41 lands, because they read what S6 creates (packages/harness, session.launched, launch.revoke). The same goes for the Ledger view's cached report and a Decision Seen CLI verb.