Bead failure reasons — explain why beads failed, not just that they failed #1172

Parent

Part of #204 (Phase 4: Hardening)

Problem

When beads transition to failed, users often have no idea why. Of the 16 code paths that can fail a bead, 8 record no reason or message — the bead silently goes to failed with zero diagnostic context. Even when the container provides a reason parameter (e.g., agent crash details), it's discarded and never persisted.

This makes failed beads opaque and unrecoverable. Users can't distinguish "dispatch timed out 5 times" from "agent crashed" from "merge conflict" from "missing rig config." The only option is to delete the bead and try again, losing any context about what went wrong.

Current State: Every Failure Path

Good visibility (reason recorded)

Poor or no visibility (no reason recorded)

Additional problems

• completeReview() bypasses updateBeadStatus(): Paths App Builder - Add preview URL tracking with navigation controls #8, feat(share): implement shared session page with database integration #9, feat(models): add kilo/auto model with centralized configuration #10 use raw SQL to set status = 'failed', which means no status_changed bead_event is logged and no convoy progress update is triggered. These beads fail silently with zero audit trail.
• agentCompleted() discards the reason parameter: The container sends crash/failure details but review-queue.ts:624 only uses reason for refinery rework messages, not for polecat failures. The reason is lost.

Solution

Two-part fix: (1) persist a structured failure reason on every bead failure, and (2) render failure reasons in the UI with rich context.

1. Add failure_reason to bead events

Every status_changed event that transitions to failed should include a structured failure_reason in the event metadata:

type FailureReason = {
  code: string;           // machine-readable: 'dispatch_exhausted', 'agent_crashed', 'timeout', 'merge_conflict', etc.
  message: string;        // human-readable summary
  details?: string;       // optional: stack trace, error output, container logs
  source: string;         // what triggered it: 'scheduler', 'patrol', 'refinery', 'triage', 'admin', 'container'
};

Each failure path gets a specific code and message:

2. Fix completeReview() callers to use updateBeadStatus()

The three paths that use raw SQL (Town.do.ts:3284, 3289, 3406) should use updateBeadStatus() instead, so that:

• A status_changed bead_event is logged with the failure reason
• Convoy progress is updated
• The audit trail is complete

3. Persist reason from agentCompleted()

In review-queue.ts:624, when a polecat agent completes with status: 'failed', write input.reason into the bead_event metadata. Currently only the refinery path uses the reason.

4. Render failure reasons in the UI

The bead detail panel should display failure reasons prominently:

• A red banner at the top of a failed bead showing the human-readable message
• Expandable details section with the failure code, source, and any additional context (error output, container logs)
• Timeline entry in the bead events with the full failure context

5. LLM-written failure summaries (stretch)

For complex failures (agent crashes with long error output, repeated dispatch failures with different errors each time), dispatch a short LLM call to summarize the failure in plain language. Store the summary alongside the raw failure data. This turns "agent_crashed: Error: Cannot find module '@/lib/auth' at Object. (/workspace/rigs/abc/...)" into "The agent crashed because it couldn't find the auth module — this usually means the dependency wasn't installed or the import path is wrong."

This could piggyback on the triage agent infrastructure (#442) or be a dedicated lightweight call.

Acceptance Criteria

• Every code path that transitions a bead to failed includes a structured failure_reason in the bead_event metadata
• completeReview() raw SQL paths replaced with updateBeadStatus() for proper event logging
• agentCompleted() persists the container's reason parameter for polecat failures (not just refinery)
• Bead detail panel renders failure reason prominently (banner + expandable details)
• Failure reasons visible in the activity feed timeline
• Dispatch exhaustion captures the last dispatch error for context

Notes

• No data migration needed — cloud Gastown hasn't deployed to production
• The bead_events table already supports a metadata JSON column — the failure reason fits naturally there
• The LLM summary (stretch goal) should only fire for failures with complex error output, not for simple cases like "dispatch exhausted" or "admin force-fail" where the message is already clear
• This overlaps with [Gastown] PR 22: Observability #228 (Observability) — structured failure reasons are a form of structured logging that both the admin panel (Gastown User-Scoped Admin Panel — Inspect & Intervene via GastownUserDO → TownDO #897) and the user dashboard can consume