Redesign Merge Queue page — split into Needs Attention + Refinery Activity Log

[jrf0110]

Parent

Part of #204 (Phase 4: Hardening)

Problem

The Merge Queue page (/gastown/[townId]/merges) is effectively useless. It renders a flat list of review_submitted and review_completed bead events with minimal context — just an icon, a one-line status, and a rig name. There's no queue state, no PR URLs, no agent information, no convoy grouping, no actions, no links to source beads, and no way to understand what's happening or what's blocked on you.

The page is a filtered event log pretending to be a queue view. Rich data exists in the database (pr_url, convoy_id, convoy_feature_branch, source_bead_id, source_agent_id, branch, target_branch, retry_count, merge_commit) but none of it is surfaced.

Solution

Redesign the page into two sections: Needs Your Attention (human-blocking items) and Refinery Activity Log (what the bots have been doing). Each element links to the relevant bead chain via the stackable drawer UI. Convoy reviews are grouped.

Section 1: Needs Your Attention

Items where the bots are blocked on a human action. These are the things the user should act on:

• Open PRs awaiting merge/close — The refinery created a PR (merge strategy = pr) and it's waiting for a human to review, approve, merge, or close it. Shows: PR title, PR URL (clickable), rig name, how long it's been waiting, which bead it's for (clickable → drawer), which agent submitted it.
• Failed reviews — A merge or review failed and the system couldn't auto-recover. Shows: failure reason (from Bead failure reasons — explain why beads failed, not just that they failed #1172), source bead (clickable → drawer), retry count, last error.
• Merge conflicts on open PRs — PR has conflicts and the auto-resolver (Automatic merge conflict resolution on open PRs #1004) isn't enabled or failed. Shows: PR URL, conflicting files (if available from the API), source bead.
• Stale PRs — PRs open for more than a configurable threshold (e.g., 24 hours) with no activity.

Each item has actions: "Open PR" (external link), "Retry Review" (re-queue), "Fail Bead" (give up), "View Bead" (open drawer).

Section 2: Refinery Activity Log

A human-readable activity feed of what the refinery has been doing. Not a table — a timeline of events written in natural language:

Rig 1 · 5 minutes ago
  Refinery merged Toast's "UI updates to login flow" into main
  3 files changed · 0 gate failures · Commit abc1234

Rig 1 · 12 minutes ago
  Refinery requested changes from Shadow on "Add rate limiting to API"
  Reason: Test suite failing — 2 tests broke in auth.test.ts

Rig 2 · 20 minutes ago
  Refinery created PR #42 for Maple's "Database migration for user roles"
  Waiting for human review → github.com/org/repo/pull/42

Rig 1 · 1 hour ago
  Refinery merged Toast's "Fix header alignment" into feature/auth-refactor (convoy: Auth Refactor)
  Intermediate merge — 2/5 convoy beads reviewed

Each entry:

• Names the rig and agent involved
• Describes the action in plain language (merged, requested changes, created PR, failed)
• Links to the source bead (clickable → stackable drawer showing the full bead chain)
• Shows relevant metadata: files changed, gate results, commit SHA, PR URL
• Timestamps with relative time

Convoy Grouping

Reviews within a convoy should be visually grouped:

• A convoy header card shows: convoy name, progress (e.g., "3/5 beads reviewed"), feature branch name, merge mode
• Under the header, individual reviews for that convoy are listed chronologically
• The convoy header links to the convoy detail drawer
• Standalone (non-convoy) reviews appear outside any group

In the "Needs Your Attention" section, convoy items are grouped the same way — if a convoy has 2 PRs waiting, they appear under the convoy header, not as disconnected items.

Data Requirements

All the data needed already exists but isn't queried by the user-facing page:

Data point	Source	Currently surfaced?
PR URL	review_metadata.pr_url / beads.metadata.pr_url	Admin only
PR status	Polled by pollPendingPRs() in alarm	Not stored for UI
Source bead	beads.metadata.source_bead_id	No
Source agent	beads.metadata.source_agent_id	No
Convoy ID	beads.metadata.convoy_id	No
Feature branch	beads.metadata.convoy_feature_branch	No
Target branch	review_metadata.target_branch	No
Branch name	review_metadata.branch	Partially (in event new_value)
Retry count	review_metadata.retry_count	No
Merge commit	review_metadata.merge_commit	No
Failure reason	bead_event metadata (after #1172)	No
Files changed	Not currently stored	No — would need to be captured
Gate results	Not currently stored	No — would need to be captured

A new tRPC procedure (or enhancement of existing ones) should return merge_request beads with their full metadata, review_metadata satellite data, convoy associations, and source bead info — not just event log entries.

Stackable Drawer Integration

Every bead reference in the merge queue should open the stackable drawer UI:

• Click a source bead → drawer shows bead detail (status, body, assigned agent, commit history from Track commits in bead history with SCM links #1003, failure reason from Bead failure reasons — explain why beads failed, not just that they failed #1172)
• Click "View Convoy" → drawer shows convoy progress, all tracked beads, dependency graph
• Drawers stack — user can drill from merge queue → source bead → convoy → another bead without losing context

Acceptance Criteria

• "Needs Your Attention" section showing human-blocking items (open PRs, failed reviews, merge conflicts, stale PRs)
• "Refinery Activity Log" section with human-readable timeline entries
• Each activity entry names the rig, agent, and action in natural language
• Every bead reference links to the stackable drawer
• Convoy reviews visually grouped under convoy header cards with progress indicators
• New tRPC procedure returning merge_request beads with full metadata (PR URL, source bead, convoy, review_metadata)
• Action buttons on attention items: Open PR, Retry Review, Fail Bead
• Per-rig filtering option

Notes

• No data migration needed
• The admin ReviewQueueTab has a proper table with some of this data — it can inform the new design, but the user-facing page should be a timeline/feed, not a table
• Depends on Bead failure reasons — explain why beads failed, not just that they failed #1172 (Bead Failure Reasons) for rendering failure context on failed reviews
• The "files changed" and "gate results" data points would be new additions — the refinery currently doesn't report these back. Could be a stretch goal or captured as part of Track commits in bead history with SCM links #1003 (Track Commits in Bead History).
• Consider whether this page should auto-scroll to new activity or show a "N new events" toast