[P1][Business Hub] Fix terminal completion, child-contract invalidation, and authoritative rollup freshness

[richard-devbot]

Parent: #476

Outcome

The Business Hub shows authoritative harness truth within a bounded delay, including terminal completion and background-worker writes. Cached rollups cannot remain active/stalled after the run is DONE.

Audit finding

The UI has polling/WebSocket mechanisms, but cache invalidation and terminal semantics are incomplete:

• The run signature covers selected top-level files/directories, but omits changing child contracts such as builder, validation, prompt, and stage artifact files.
• Once a run is cached as unchanged, terminal runs may not be reparsed unless a scoped request forces it.
• In-memory “events behind” repair is only attached in a narrow path, while the rollup index can preattach a pipeline rollup and bypass that fallback.
• The status path can stamp the manifest as DONE without persisting a reliable completed_at.
• Run-status derivation can ignore or underweight manifest terminal state, so a completed run becomes active and later stalled.
• Harness persistence/invalidation is coupled to successful tool-return paths. A background worker or direct control-plane write can complete a stage without emitting the same UI invalidation signal.

The dashboard is therefore not purely hallucinating from mission records, but it can display stale derived truth instead of current authoritative harness state.

Required design

Single authoritative change signal

Every committed harness transition must atomically increment a monotonically increasing state_generation and emit an outbox event. The dashboard signature should depend on that generation/event cursor rather than guessing which child files might have changed.

Terminal-state correctness

• Persist completed_at atomically with status: DONE.
• Derive terminal status directly from authoritative manifest/state-machine truth.
• Never apply generic staleness classification to a terminal run.
• Surface corruption or partial state as an explicit degraded/error state, not cached success.

Reactive delivery

• Publish committed transition events to all Business Hub instances.
• Retain bounded polling as reconciliation, not as the primary source of truth.
• Invalidate per-run and aggregate caches on the same transaction/outbox event.
• Reconcile event cursor against state generation after reconnect/restart.

Acceptance criteria

• Every committed transition changes the dashboard-observed generation.
• Builder/validator/stage artifact completion by a background worker refreshes the UI without a user click.
• DONE and completed_at are persisted in the same commit.
• A completed run remains completed indefinitely and never degrades to stalled.
• Aggregate and scoped run views converge to the same generation and status.
• WebSocket reconnect catches up from the last event cursor.
• Polling detects a missed event within the configured reconciliation interval.
• Partial/corrupt control-plane state is rendered as degraded/error with diagnostics.
• No mission-record heuristic can override a newer harness generation.

Required integration tests

• Complete a stage through the normal API path.
• Complete a stage through a background worker with no browser request.
• Modify a child validation contract and verify generation-driven refresh.
• Complete all 15 stages; verify terminal state before and after cache TTL/restart.
• Drop a WebSocket event, reconnect, and reconcile.
• Run two dashboard instances with independent caches.
• Inject malformed state and verify fail-visible behavior.

Likely implementation surface

• Business Hub rollup cache/signature
• server polling/WebSocket broadcaster
• harness state commit/outbox
• run status derivation and terminal timestamps
• pipeline-state/rollup adapters

Dependencies

Use the transactional transition/outbox foundation from #481.

[richard-devbot]

Shipped in PR #519: the two confirmed, fixable bugs from the audit finding.

Terminal completion persistence — `completed_at` was written nowhere in the codebase; only ever read by the dashboard's terminal-status derivation (`deriveRunStatus`/`statusFromEntry`), which keys `"done"` on it, not on `manifest.status`. `markRunCompleted()` now stamps both atomically, idempotently, at the actual moment of completion inside `sdlc_validate`.

Child-contract invalidation — `runSignature()` never covered `tasks//{builder,validation,prompt}` files, so an in-place retry rewrite could leave a stale cached index entry. `childContractsSignature()` closes this — and a Qodo review catch found the first version's path-join was itself wrong against the real `sdlc_plan` output_dir shape (would have been a silent no-op in production); fixed against the real writer, with traversal containment added as defense-in-depth.

Investigated, deliberately NOT changed: attempted to also make the rollup-index's general pipeline rollup rebuild on `pipelineStateEventsBehind` (a literal reading of the audit's "bypass" wording) — this regressed an existing, deliberate test (`dashboard-command-pages.test.js`) pinning the OPPOSITE contract: the general rollup must show honest staleness, not rebuild on every 3s poll for every active run. Caught by this PR's own verification pass and reverted; full reasoning in `computeRunPipelineRollup`'s doc comment and `docs/HARNESS.md`.

Deliberately deferred (documented in `docs/HARNESS.md`) — the issue's full "Required design" is a separate, much larger subsystem than this slice: the `state_generation`/outbox model (no monotonic run-level counter or outbox-event-cursor exists anywhere in this codebase — confirmed by direct inspection), multi-instance WebSocket delivery + reconnect-cursor reconciliation, and a degraded/error surface at the generation layer.

Closing per the Wave 1/Wave 2 precedent (#480–#483) — shipped slice + honestly-documented deferred scope. Reopen or file a follow-up for the deferred `state_generation`/outbox subsystem if it becomes priority.