[marcusrbrown]

Closes #729.

Adopts operator contract 1.14.0. A draining run's status frame can now say why the run hasn't finished yet, and the expanded card shows that reason on a quiet line under the repo name.

What changes

• Contract pin 1.14.0 on the server and in the browser. The new waitReason wire type is vendored without the gateway-only helpers.
• Parsing. Both parsers keep waitReason only on a running status frame with a known value. Unknown values, or a reason on any other status, are dropped, and the frame itself is still kept.
• Live state only. The reason lives on the live run entry. Every status frame sets it or removes it. A terminal no-snapshot reset drops it, and a live one keeps it, because the gateway doesn't re-send an unchanged status. The reason never reaches run summaries, the finished-run cache or the list.
• Label. "Agent still working", "Finishing its reply", "Waiting on a background task" or "Confirming it has finished", shown on the expanded card while the stream is live and the run is plainly running. It is hidden while an approval or question is open, a cancel is in flight, checkout preparation is showing, or the connection isn't live. A failure reason and the preparation headline take priority over it.
• List refresh. The stream marks the reason line as its own (data-reason-owner="stream"), and a list refresh leaves that line alone. This also fixes a refresh wiping the checkout preparation headline.
• Fixtures. Three new scenarios: wait_reason_draining, wait_reason_with_approval and wait_reason_unknown.

Rollout

The contract version is an exact match, so this release only works against a gateway on contract 1.14.0. That means fro-bot/agent v0.128.0 or later. Deploy the dashboard and the gateway pin bump in the same window, and roll them back together.

Screenshots (fixture harness)

State
Agent still working
Finishing its reply
Waiting on a background task
Confirming it has finished
Narrow screen, light
Finished: no label
Failure layout unchanged

Verified

• bun run check-types and bun run lint pass, along with the web suite and the root suite.
• Browser pass on the fixture harness, in light and dark at desktop width and 390 px. All four labels were checked, plus approval precedence, re-expand replay, an unknown reason showing no label, and the label clearing on terminal.

Not verified

• Not run against a real 1.14.0 gateway. The dashboard's tests check the fixture's frames against the vendored contract, not against what the live gateway emits. After the paired deploy, check /operator/health for contractVersion: "1.14.0" and watch a draining run, including a reconnect during the drain. The label should keep showing the last reason.

[fro-bot]

Verdict: PASS

I reviewed the full diff for src/, public/ and the CSS, and skimmed the test additions. I did not run the test suite, so the PR description's passing-checks claim is untested by me.

Blocking issues

None

Non-blocking concerns

• Exact-match contract pin (src/gateway/operator-contract/version.ts, PINNED_CONTRACT_VERSION in public/operator-stream.js). The bump from 1.13.0 to 1.14.0 is a hard cutover. A gateway older than fro-bot/agent v0.128.0 will fail the ready-frame version check. The PR description already says to deploy and roll back the dashboard and gateway together. This is an operational risk, not a code defect. Confirm the gateway pin bump is ready to land in the same window before merging.
• Stale waitReason after a reconnect. nextStreamState keeps waitReason through a live no-snapshot reset. getWaitReasonLabel only requires connection === 'live'. The design assumes the gateway re-sends current status on (re)connect, so a stale reason would be replaced. That assumption sits in the gateway, so no test in this repo can confirm it. The PR's "Not verified" section already covers this. The post-deploy check on a real draining run should include a reconnect.
• Security. No findings.
  • Both parsers check the wire value against an allowlist (a Set guard behind a typeof check) and accept it only on running frames.
  • The browser renders a dashboard-owned Map label via textContent, never the wire value.
  • The reason stays out of RunSummary, the finished-run cache and the list.
  • The fixture harness additions (approvalSettleHooks, pacedThenHeldStream) are dev-only. They clean up on abort, cancel and resetFixtureHarnessForTesting.

Missing tests

None. Coverage looks proportionate:

• the conformance, SSE reader and stream-core tests cover parsing, transient-state semantics and label precedence;
• the fixture-harness tests cover the three new scenarios;
• a run-index test covers the data-reason-owner="stream" guard.

The one untested path is real-gateway emission, which the PR already calls out.

Risk assessment: LOW

The change is additive. Input goes through allowlists, rendering is textContent only, and there are no new credential, auth or write paths. The main exposure is the exact-match version coupling to the gateway, which is documented and handled by a paired deploy. The data-reason-owner change touches DOM shared between the list and the stream. Its release logic is centralized in releaseReasonLine and has dedicated tests.

---

Run Summary

Field	Value
Event	pull_request
Repository	fro-bot/dashboard
Run ID	40985646720
Cache	hit
Session	ses_e75973d17ffeVRzQald5KOM2c6

[fro-bot]

Verdict: PASS

This is a re-review. The only new commit since my last review is 3bcec03, a merge of main into the branch. Between 072800c and 3bcec03 it changes one line, in .github/workflows/main.yaml. That line bumps the pinned npx impeccable from 4.7.0 to 4.8.0 in the Design Check step, and it comes from main, not from this PR. None of the files under src/, public/, web/src or test/ changed. The PR description also gained a sentence asking for a reconnect-during-drain check after deploy, which covers my earlier reconnect concern.

My earlier assessment still holds. I did not run the test suite.

Blocking issues

None

Non-blocking concerns

• Exact-match contract pin (src/gateway/operator-contract/version.ts, PINNED_CONTRACT_VERSION in public/operator-stream.js). A gateway older than fro-bot/agent v0.128.0 will fail the ready-frame version check. The PR documents the paired deploy and rollback. Confirm the gateway pin bump lands in the same window.
• Reconnect behaviour depends on the gateway re-sending current status. No test in this repo can confirm that. The updated "Not verified" section now asks for a reconnect check during a real draining run, which is the right post-deploy check.
• Security: no findings. The wire value is checked against an allowlist in both parsers and accepted only on running frames. The browser renders a fixed label via textContent and never the wire value.

Missing tests

None. The only untested path is emission from a real gateway, which the PR calls out.

Risk assessment: LOW

The change is additive. Input goes through allowlists, rendering is textContent only, and there are no new credential, auth or write paths. The main exposure is the exact-match gateway version coupling, which is documented and handled by a paired deploy.

---

Run Summary

Field	Value
Event	pull_request
Repository	fro-bot/dashboard
Run ID	40988971696
Cache	hit
Session	ses_e75973d17ffeVRzQald5KOM2c6