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

# Row 60 (#1549): bus read, credential status on the broker, round 1

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

Base 4100fa68. `build.patch` applies there with `git apply --index`;
`candidate-manifest.sha256` pins all 9 files after the patch. HEAD is now
c949f9ef, with docs and queue commits only; no file under `packages/`
changed. I applied the patch there and all 9 manifest lines check OK.

## What the read is

A new socket verb, `credentials`. No args. Human and reader sessions only; a
role session gets `human-required`, as with `decisions`. It returns one row
per credential the running host loaded for the session's business:

```
{ service, account, role, dateKind, date, state }
```

- `service`: `gitea` or `vikunja`.
- `account`: the role's `tracker.bot` for Vikunja, the sync identity's `bot`
  for the `business/@sync` row, `null` for Gitea (the business file names no
  Gitea account).
- `role`: the instance, or `tracker sync` for `@sync`.
- `dateKind`, `date`: `rotateBy` for Gitea, `expires` for Vikunja.
- `state`: `Credentials.status()` against the host clock at the request:
  `valid`, `expiring` (under 7 days), `expired`, or `rotation-due` for Gitea.

The order is `status()` load order: role instances, then the sync identity.

The row shape is the one the WebUI's Business view already uses
(`credential()` in `packages/webui/src/reads.mjs`), so a page can use either.
The difference is the source. The Business view reads the business file: what
the host should load. This read asks the host: what it did load, checked
against its own clock. A token file rotated after startup isn't reread until
restart, and this read is how to see what the host is running with.

## How the broker gets it

The broker gets one new constructor option, `credentialStatus`, a function.
The runtime passes `() => credentials.status()`. The broker never gets the
`Credentials` object, so it can't reach `use()`. The default is `() => []`,
so a broker built without it (every existing test) lists none.

`status()` already returns metadata only (`instance`, `service`, `date`,
`state`). The broker filters it to `business + '/'`, drops `instance`, and
adds `account`, `role` and `dateKind` from the business config. The result
also goes through the known-token check every read goes through.

The existing trusted launch op `credentialStatus(business, role)` in the
runtime is unchanged.

## WebUI

GET `/api/bus/credentials` is a new bus route: `credentials` joins
`BUS_VERBS` in `serve.mjs`, and `views.mjs` gains `credentials()`. It runs
through the same human transport as the other bus reads, so the same 403,
503 and 502 mapping applies. GET only.

No page uses it yet. The brief names the endpoint and its tests, not a view
change. The Business view still shows the file's metadata. See question 1.

## Files

- `packages/bus/src/broker.mjs`: the `credentialStatus` option, the
  `credentials` case, and `credentials` in the reader allowlist.
- `packages/bus/src/runtime.mjs`: passes `credentialStatus`.
- `packages/bus/src/views.mjs`: `credentials()`.
- `packages/bus/tests/credential-status.test.mjs` (new, 4 tests):
  - Human and reader sessions get the exact rows and keys for `demo`, with
    every state (valid, expiring, expired, rotation-due), a file ref and an
    env ref, and the sync row. A second business, `demox`, shares the
    `demo` prefix without the slash and gets only its own row.
  - A role session gets `human-required`; any argument is
    `invalid-request`.
  - The status is read on each request (a changed state shows on the next
    one); a broker without the option lists none.
  - The brief's acceptance test: the real broker process (`process.mjs`,
    forked) boots on a seeded config with five token files and one env
    token. A reader calls `credentials`, a role session is refused, and the
    process closes. The rows, the host log (stdout and stderr) and the store
    files (`bus.sqlite*`) contain none of the six tokens, the token file
    paths, their directory, or the env variable name. The store check also
    confirms the refusal was written, so it read the right files.
- `packages/bus/README.md`: a verb table row and a `credentials` paragraph
  under "Human and reader paths".
- `packages/webui/src/serve.mjs`, `packages/webui/src/bus.mjs`: the verb and
  comments.
- `packages/webui/tests/bus.test.mjs`: the route returns the reader's rows
  only (one business of two), `{ rows, at }`, `no-store`; the route is
  GET-only; `busReader` sends `{verb:'credentials', args:{}}`.
- `packages/webui/README.md`: the route, and the exposure note now names
  the credential status.

## Mutants

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

- broker, runtime: the bus suite;
- views, serve: `packages/webui/tests/bus.test.mjs`.

All 16 are killed, and the diff is unchanged afterwards:

- broker, 12: role session allowed, reader refused, prefix without the
  slash, no business filter, arguments accepted, a Gitea account from
  `tracker.bot`, the sync account `null`, `@sync` as the role, a fixed
  `dateKind`, `instance` left in the row, a fixed state, the status read
  once at construction.
- runtime, 1: no `credentialStatus` passed (the process test).
- views, 2: the wrong verb, an extra argument.
- serve, 1: `credentials` missing from `BUS_VERBS`.

## Gate (my run on the candidate)

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

| Suite | Result |
|---|---|
| packages/bus | 84/0 (80 before; 4 new) |
| packages/control-board | 124/0 |
| packages/webui | 41/0 (40 before; 1 new), the browser tests included |
| packages/cli | 112/0, since it starts the runtime |
| scripts/test-*.sh | all nine exit 0: auth 15, conductor 17, config 24, discord 66 (see below), extension-package 18, foundation 44, queue 27, release 4, task 26 |

`test-discord` failed once in the sequential run, 65/1: the engine test
"when pi has not started a timed-out turn by the end of the abort grace…"
(`packages/discord`, a timing assertion). Load average was about 20 at the
time. This patch touches nothing under `packages/discord`. The rerun of the
whole script passed 66/0. Sage's gate rerun will show whether it recurs.

`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 (`r60/gate/`), not kept in the repository.

The mutants ran before one comment-only change: I rewrapped the header
comment of `packages/webui/src/bus.mjs`. The gate ran after it.

## Overlap

- Row 59 (#1548, in review) edits the `agents` branch of `broker.mjs`, adds
  `#agentState` after `#dispatch`, and replaces the `inbox, tasks, agents`
  row of the bus README verb table. With row 59's packet applied on 4100fa68
  first, plain `git apply` of this patch refuses on `packages/bus/README.md`
  (both add a line after the `trail` row); `git apply --3way` merges every
  file cleanly, with the `credentials` row after `trail` and the new case
  before `default:`.
  On that combined tree, the bus suite and the WebUI bus and browser tests
  pass, 100/0.
- Row 58 (Darkwing) edits the `tasks` branch, which this patch doesn't
  touch.

## Questions for reviewers

1. Should the Business view use this read, or show it next to the file's
   metadata (for example, flag a difference)? I left the view alone because
   the brief lists only the endpoint, and the Business view works without a
   bus host.
2. The bus README verb table has no `decisions` row (row 57 added the verb
   and a paragraph). I added a `credentials` row only. Should a follow-up
   add the missing row?