stack/agents/filbert/work/queue-59/build.md

Row 59 (#1548): bus read, agent state per role, round 1

Filbert, 2026-10-11. Brief: docs/plans/2026-10-10_design-implementation.md, "Bus read: agent state per role" (blob a360554c). Darkwing and Dewey review. Sage commits after the gate; nothing is committed, staged or pushed yet.

Base f2f2861b. build.patch applies there with git apply --index; candidate-manifest.sha256 pins all 8 files after the patch.

Which: state on the bus

The brief allows either a seat-to-role mapping read from committed data or state on the bus. I chose state on the bus, because no committed data joins a seat to a role:

• The business file's holder for a role instance is a display name. It isn't a seat id the control board knows.
• The bus's claim names a run (holder_run), not a seat. A run is one launch; the next launch of the same role is a different run.

So a mapping would be a new hand-kept file that goes stale on each launch. The bus already records everything the state needs: the claim, message deliveries and decisions. The state is derived at read time. Nothing new is written and the schema is unchanged.

The derivation

agents for a human or reader session returns each held claim row plus:

• working: {messages, since} or null. Messages to the role, in the business, that the current holder received (delivered) and hasn't marked read; since is the oldest delivery. The runner (packages/harness/src/runner.mjs) receives a batch, takes one turn per message, replies, then marks each read, so this is "a turn is under way or queued".
• inputNeeded: the role's open decisions routed to the human (raised_by_role is the role, route_to is human, no resolved, withdrawn or expired event), gated first and then oldest, the Inbox's order. Each item is {id, question, class, blocking, task_ref, at}; options and the rest of the decision stay in the Inbox. Seen is still open.
• state: working if working is set, else waiting if inputNeeded is nonempty, else idle. Working wins, as on the control board (scan.mjs).

A role session gets the claim rows unchanged, so a role can't read another role's decisions through agents. The CLI's formatAgents prints only role, holder, harness and time, so mosaic agents is unchanged; --json carries the new fields. The webui server passes agents rows through, so it has no change.

Limits, in the bus README:

• A message routed but not yet received shows idle.
• A reply that fails for a reason other than a gone session leaves its message unread, so the role stays working. since shows for how long.
• No error or offline state is derived. The control board has both; the bus has no record to derive them from.
• A new holder doesn't inherit the last holder's unread deliveries. Decisions stay with the role across holders.
• Unheld and released roles aren't listed, as before.

The Agents view

#/agents gets State and Attention columns, between Role and Holder:

• State: the board's mark (.st-* from shell.css: ● working, ◐ waiting, – idle) with the word, plus "N messages since " when working.
• Attention: "Input needed:", then the first line of the first open decision, linked to #/inbox/<id>, then its short id and a blocking chip, plus "+N more" linking to the Inbox. Otherwise "none".
• The page says what each state means. The table's minimum width goes from 820 to 1000px inside its scroll region; the page doesn't scroll sideways at 320 or 1440px.

Read-only: no new route, verb, write or button.

Files

• packages/bus/src/broker.mjs: #agentState, and the agents branch maps it for human and reader sessions.
• packages/bus/tests/agents.test.mjs (new, 6 tests): idle and the role session's plain rows; working counts received and unread, not routed, and since moves as messages are read; Input needed order, the arbiter's own cross-role decision routed to the human, supersede, resolve and seen; working wins over waiting; a new holder; business isolation with one run name in both businesses.
• packages/bus/README.md: the agents row of the verb table and an "Agent state" section with the reasoning and limits.
• packages/webui/src/public/bus.js: the Agents view only. Row 58 edits the Tasks view in the same file and the tasks branch next to the agents branch in broker.mjs; the hunks touch, so whichever lands second rebases.
• packages/webui/src/public/bus.css: the table's minimum width.
• packages/webui/tests/bus.test.mjs: the reader route carries state, working and inputNeeded.
• packages/webui/tests/bus-browser.test.mjs: the seed makes CTO working (PM sends, CTO receives); the page shows the headers, each role's state and mark glyph, Coder's Input needed with only the first line, the link and the blocking chip, "+1 more" while a second decision is open, and stays inert.
• packages/webui/README.md: an "Agent state" section.

packages/control-board/ is unchanged: the view reuses its mark through shell.css, which is already served.

Mutants

29 mutants (run.mjs, kept in my scratch). Each edits one file, runs the tests that own it, and restores the file:

• broker: the bus suite;
• bus.js: bus.test.mjs and bus-browser.test.mjs.

The diff is unchanged afterwards. 28 are killed:

• broker, 18 mutants, 17 killed. The killed ones:
  • working: any holder, no read check, any delivery op, max for since, any business, working when nothing is unread.
  • Input needed: any business, any raiser, any route, closed kept, seq order only, newest first, blocking left as 0/1, the whole decision row.
  • state and access: waiting wins, a role session widened, a reader getting the plain rows.
• bus.js, 11 mutants, all killed: no mark, a fixed mark class, no working note, no Attention, the whole question, the question unescaped, the link to the Inbox instead of the decision, no blocking chip, "+N more" always, the count off by one, and the old column order.

The survivor is b-msg-any-role (m.to_role dropped from the working count). It's equivalent: a run is bound to one role in a business (bindLaunch refuses a second record for the run), and deliveries carry the holder's run, so the business and holder already pick the role. I kept the filter because it states what is counted.

The first pass had four more survivors, and one mutant killed only by unrelated tests. I fixed each and reran it:

• b-msg-any-business: test 6 used different run names per business, so the holder alone separated them. Run names are unique per business only, so test 6 now uses one run name in both.
• w-more-count-off: nothing showed a second decision. The browser test now raises one on the Agents page, checks "+1 more" and its link, withdraws it, and checks the count goes.
• w-link-inbox and w-no-blocking first edited the same text in the Tasks view, and b-blocking-raw the same line in #decisionView, where other tests caught it. I narrowed their targets.

Gate (my run on the candidate)

Worktree at f2f2861b with the patch, run in sequence with TMPDIR in my scratch and DOCKER_HOST pointed at a missing socket:

Suite	Result
packages/bus	86/0 (80 before; 6 new)
packages/control-board	124/0
packages/webui	40/0, the browser tests included
packages/cli	110/0, since it reads agents
scripts/test-*.sh	all nine exit 0: auth 15, conductor 17, config 24, discord 66, extension-package 18, foundation 44, queue 27, release 4, task 26

test-release and test-task skipped their Docker cases without a daemon; Sage's gate rerun covers those. No test calls a model. Logs are in my scratch (r59/gate/), not kept in the repository.

HEAD moved to b31cc8a9 while I packaged, with docs and Sage's row 68 packet only. None of the eight files changed, so the patch applies there too.

Questions for reviewers

1. Is "received and not read" the right working signal? The other choice is the claim's own activity, which the bus doesn't record per turn.
2. Should Attention list every open decision instead of the first and a count? The Inbox already lists them all; I kept one line per role.