feat(gastown): add in_review bead state, fix triage auth and scheduling guards (#1028)

* feat(gastown): add in_review bead state between in_progress and closed

Beads now transition to in_review when a polecat calls gt_done, rather
than going straight to closed. The refinery review then closes the bead
on merge or returns it to in_progress for rework. This prevents the bead
board from showing beads as done before the refinery has actioned them.

Changes:
- Add in_review to BeadStatus enum (schema + types)
- gt_done transitions source bead to in_review instead of closed
- Review failure/conflict returns bead to in_progress and re-dispatches
  the original polecat for rework
- Mayor and polecat prompts updated to reflect the new lifecycle
- BeadBoard UI adds In Review column with purple styling
- Dashboard badge styling for in_review state

Closes #895

* fix(gastown): add in_review to tRPC bead schemas and rig-beads table

The listBeads tRPC route was returning 500 (output validation failed)
because beads with in_review status didn't pass the output schema.
Add in_review to BeadOutput, the listBeads input filter, the rig-beads
table Zod enum + SQL CHECK constraint, and the generated router types.

* fix(gastown): triage handler 401 in dev mode — fall back to identity header

In development, authMiddleware is skipped so agentJWT is never set on
the Hono context. The triage handler used getEnforcedAgentId() as a
hard requirement (returning 401 on null), unlike other handlers which
treat it as optional. Fall back to the X-Gastown-Agent-Id header that
the container client sends with every request.

* feat(gastown): add triage_resolved events to activity feed and encourage gt_status in triage prompt

Triage actions (RESTART, CLOSE_BEAD, ESCALATE, etc.) now emit a
triage_resolved bead event on the target bead, making them visible in
the activity feed. Previously only a status_changed event was logged on
the triage request bead itself, which doesn't appear in the affected
bead's timeline.

- Add triage_resolved to BeadEventType enum
- Log triage_resolved on the target bead in resolveTriage with action
  and resolution notes in metadata
- Add ShieldCheck icon (amber) and description formatting in ActivityFeed
- Update triage system prompt to instruct agents to call gt_status at
  the start and end of their batch for dashboard visibility

* fix(gastown): prevent hooking agents to escalation and triage-request beads

hookBead had no bead-type validation — any agent could be hooked to any
bead, including system-managed types like escalation, convoy, agent, and
message beads. Triage-request beads (type='issue' with gt:triage-request
label) were also unguarded, letting polecats accidentally pick them up.

Add two guards in hookBead:
- Reject beads with system-managed types (escalation, convoy, agent,
  message) since no agent should work on these directly
- Reject beads with the gt:triage-request label since those are resolved
  via gt_triage_resolve, not by hooking an agent

* fix(gastown): address PR review comments — in_review gaps, rework stranding, responsive layout

Address all four review comments and four code review observations:

- Wire in_review through container plugin types, mayor gt_list_beads
  tool, rig detail stats, town overview stats, healthCheck pending count,
  and getAlarmStatus bead counts
- Fix rework stranding: use getOrCreateAgent instead of re-hooking the
  original polecat (which may already be working on something else)
- Fix BeadBoard loading skeleton to use responsive grid-cols-1/sm:4
  matching the loaded layout
- Add In Review stat cell to both rig detail and town overview pages

* fix(gastown): use inline grid-template-columns for 5-col stats strip

Tailwind's grid-cols-5 was being purged or not applying correctly.
Use an inline style to guarantee the 5-column layout.

* fix(gastown): gate triage header fallback on dev, wire inReview through alarm status

- Gate X-Gastown-Agent-Id header fallback in handleResolveTriage on
  ENVIRONMENT === 'development' to prevent header spoofing in production
- Add inReview to AlarmStatusOutput tRPC schema, router.d.ts types,
  and TerminalBar UI so the new bead count is visible in the status pane

Author: jrf0110

cloudflare-gastown/container/plugin/mayor-tools.ts

@@ -78,12 +78,12 @@ export function createMayorTools(client: MayorGastownClient) {
     gt_list_beads: tool({
       description:
         'List beads (work items) in a specific rig. ' +
-        'Optionally filter by status (open, in_progress, closed, failed) or type (issue, message, escalation, merge_request). ' +
+        'Optionally filter by status (open, in_progress, in_review, closed, failed) or type (issue, message, escalation, merge_request). ' +
         'Use this to check what work exists in a rig, what is in progress, and what has been completed.',
       args: {
         rig_id: tool.schema.string().describe('The UUID of the rig to list beads from'),
         status: tool.schema
-          .enum(['open', 'in_progress', 'closed', 'failed'])
+          .enum(['open', 'in_progress', 'in_review', 'closed', 'failed'])
           .describe('Filter by bead status')
           .optional(),
         type: tool.schema

cloudflare-gastown/container/plugin/types.ts

@@ -1,7 +1,7 @@
 // Types mirroring the Town DO domain model.
 // These are the API response shapes — the plugin never touches SQLite directly.
 
-export type BeadStatus = 'open' | 'in_progress' | 'closed' | 'failed';
+export type BeadStatus = 'open' | 'in_progress' | 'in_review' | 'closed' | 'failed';
 export type BeadType =
   | 'issue'
   | 'message'

cloudflare-gastown/src/db/tables/bead-events.table.ts

@@ -18,6 +18,7 @@ export const BeadEventType = z.enum([
   'pr_created',
   'pr_creation_failed',
   'agent_status',
+  'triage_resolved',
 ]);
 
 export type BeadEventType = z.infer<typeof BeadEventType>;

cloudflare-gastown/src/db/tables/beads.table.ts

@@ -15,7 +15,7 @@ export const BeadType = z.enum([
   'agent',
 ]);
 
-export const BeadStatus = z.enum(['open', 'in_progress', 'closed', 'failed']);
+export const BeadStatus = z.enum(['open', 'in_progress', 'in_review', 'closed', 'failed']);
 export const BeadPriority = z.enum(['low', 'medium', 'high', 'critical']);
 
 export const BeadRecord = z.object({

cloudflare-gastown/src/db/tables/rig-beads.table.ts

@@ -2,7 +2,7 @@ import { z } from 'zod';
 import { getTableFromZodSchema, getCreateTableQueryFromTable } from '../../util/table';
 
 const BeadType = z.enum(['issue', 'message', 'escalation', 'merge_request']);
-const BeadStatus = z.enum(['open', 'in_progress', 'closed', 'failed']);
+const BeadStatus = z.enum(['open', 'in_progress', 'in_review', 'closed', 'failed']);
 const BeadPriority = z.enum(['low', 'medium', 'high', 'critical']);
 
 export const RigBeadRecord = z.object({
@@ -32,7 +32,7 @@ export function createTableRigBeads(): string {
     id: `text primary key`,
     rig_id: `text`,
     type: `text not null check(type in ('issue', 'message', 'escalation', 'merge_request'))`,
-    status: `text not null default 'open' check(status in ('open', 'in_progress', 'closed', 'failed'))`,
+    status: `text not null default 'open' check(status in ('open', 'in_progress', 'in_review', 'closed', 'failed'))`,
     title: `text not null`,
     body: `text`,
     assignee_agent_id: `text`,

cloudflare-gastown/src/dos/Town.do.ts

@@ -757,6 +757,36 @@ export class TownDO extends DurableObject<Env> {
     if (input.status === 'merged' && sourceBeadId) {
       this.dispatchUnblockedBeads(sourceBeadId);
     }
+
+    // When a review fails or conflicts (rework), the source bead was
+    // returned to in_progress. Re-hook a polecat and re-dispatch so the
+    // rework starts automatically. The original polecat may already be
+    // working on something else, so fall back to getOrCreateAgent.
+    if ((input.status === 'failed' || input.status === 'conflict') && sourceBeadId) {
+      const sourceBead = beadOps.getBead(this.sql, sourceBeadId);
+      if (sourceBead?.rig_id) {
+        try {
+          const reworkAgent = agents.getOrCreateAgent(
+            this.sql,
+            'polecat',
+            sourceBead.rig_id,
+            this.townId
+          );
+          agents.hookBead(this.sql, reworkAgent.id, sourceBeadId);
+          this.dispatchAgent(reworkAgent, sourceBead).catch(err =>
+            console.error(
+              `${TOWN_LOG} completeReviewWithResult: fire-and-forget rework dispatch failed for bead=${sourceBeadId}`,
+              err
+            )
+          );
+        } catch (err) {
+          console.warn(
+            `${TOWN_LOG} completeReviewWithResult: could not dispatch rework for bead=${sourceBeadId}:`,
+            err
+          );
+        }
+      }
+    }
   }
 
   async agentDone(agentId: string, input: AgentDoneInput): Promise<void> {
@@ -966,6 +996,24 @@ export class TownDO extends DurableObject<Env> {
       },
     });
 
+    // Log a triage_resolved event on the target bead so the action shows
+    // up in the activity feed for the bead that was actually affected.
+    const targetBeadId = snapshotHookedBeadId ?? targetAgentId;
+    if (targetBeadId && targetBeadId !== input.triage_request_bead_id) {
+      beadOps.logBeadEvent(this.sql, {
+        beadId: targetBeadId,
+        agentId: input.agent_id,
+        eventType: 'triage_resolved',
+        newValue: action,
+        metadata: {
+          action,
+          resolution_notes: input.resolution_notes,
+          triage_request_bead_id: input.triage_request_bead_id,
+          target_agent_id: targetAgentId,
+        },
+      });
+    }
+
     // If this triage request was created for an escalation, close the
     // linked escalation bead too so it doesn't sit open indefinitely.
     // The escalation_bead_id is nested under metadata.context (set by
@@ -3245,7 +3293,7 @@ export class TownDO extends DurableObject<Env> {
       [
         ...query(
           this.sql,
-          /* sql */ `SELECT COUNT(*) AS cnt FROM ${beads} WHERE ${beads.status} IN ('open', 'in_progress') AND ${beads.type} NOT IN ('agent', 'message')`,
+          /* sql */ `SELECT COUNT(*) AS cnt FROM ${beads} WHERE ${beads.status} IN ('open', 'in_progress', 'in_review') AND ${beads.type} NOT IN ('agent', 'message')`,
           []
         ),
       ][0]?.cnt ?? 0
@@ -3274,6 +3322,7 @@ export class TownDO extends DurableObject<Env> {
     beads: {
       open: number;
       inProgress: number;
+      inReview: number;
       failed: number;
       triageRequests: number;
     };
@@ -3328,12 +3377,13 @@ export class TownDO extends DurableObject<Env> {
         []
       ),
     ];
-    const beadCounts = { open: 0, inProgress: 0, failed: 0, triageRequests: 0 };
+    const beadCounts = { open: 0, inProgress: 0, inReview: 0, failed: 0, triageRequests: 0 };
     for (const row of beadRows) {
       const s = `${row.status as string}`;
       const c = Number(row.cnt);
       if (s === 'open') beadCounts.open = c;
       else if (s === 'in_progress') beadCounts.inProgress = c;
+      else if (s === 'in_review') beadCounts.inReview = c;
       else if (s === 'failed') beadCounts.failed = c;
     }
 

cloudflare-gastown/src/dos/town/agents.ts

@@ -220,13 +220,32 @@ export function deleteAgent(sql: SqlStorage, agentId: string): void {
 
 // ── Hooks (GUPP) ────────────────────────────────────────────────────
 
+/** Bead types that are system-managed and should never be hooked to an agent. */
+const UNHOOKABLE_BEAD_TYPES = new Set(['escalation', 'convoy', 'agent', 'message']);
+
 export function hookBead(sql: SqlStorage, agentId: string, beadId: string): void {
   const agent = getAgent(sql, agentId);
   if (!agent) throw new Error(`Agent ${agentId} not found`);
 
   const bead = getBead(sql, beadId);
   if (!bead) throw new Error(`Bead ${beadId} not found`);
 
+  // Prevent hooking to system-managed bead types that no agent should
+  // work on directly. Escalation beads are resolved by triage, convoy
+  // beads are containers, agent/message beads are metadata records.
+  if (UNHOOKABLE_BEAD_TYPES.has(bead.type)) {
+    throw new Error(`Cannot hook agent to bead ${beadId}: type '${bead.type}' is not workable`);
+  }
+
+  // Triage request beads are resolved by the triage agent via
+  // gt_triage_resolve, not by hooking. Prevent polecats from
+  // accidentally picking these up.
+  if (bead.labels.includes('gt:triage-request')) {
+    throw new Error(
+      `Cannot hook agent to bead ${beadId}: triage requests are resolved via gt_triage_resolve`
+    );
+  }
+
   // Already hooked to this bead — idempotent
   if (agent.current_hook_bead_id === beadId) return;
 

cloudflare-gastown/src/dos/town/review-queue.ts

@@ -313,6 +313,13 @@ export function completeReviewWithResult(
         conflict: true,
       },
     });
+    // Return source bead to in_progress so the polecat can be re-dispatched
+    // to resolve the conflict (in_review → in_progress rework flow).
+    updateBeadStatus(sql, entry.bead_id, 'in_progress', entry.agent_id);
+  } else if (input.status === 'failed') {
+    // Review failed (rework requested): return source bead to in_progress
+    // so it can be re-dispatched (in_review → in_progress rework flow).
+    updateBeadStatus(sql, entry.bead_id, 'in_progress', entry.agent_id);
   }
 }
 
@@ -556,11 +563,13 @@ export function agentDone(sql: SqlStorage, agentId: string, input: AgentDoneInpu
     default_branch: rig?.default_branch,
   });
 
-  // Close the source bead (matches upstream gt done behavior). The polecat's
-  // work is done — the MR bead now tracks the merge lifecycle. The source
-  // bead retains its assignee so we know which agent worked on it.
+  // Transition the source bead to in_review — the polecat's work is done
+  // but the refinery hasn't reviewed it yet. The MR bead tracks the merge
+  // lifecycle. The source bead retains its assignee so we know which agent
+  // worked on it. It will be closed (or returned to in_progress) by the
+  // refinery after review.
   unhookBead(sql, agentId);
-  closeBead(sql, sourceBead, agentId);
+  updateBeadStatus(sql, sourceBead, 'in_review', agentId);
 }
 
 /**

cloudflare-gastown/src/handlers/rig-triage.handler.ts

@@ -29,7 +29,13 @@ const ResolveTriageBody = z.object({
 });
 
 export async function handleResolveTriage(c: Context<GastownEnv>, _params: { rigId: string }) {
-  const agentId = getEnforcedAgentId(c);
+  // In production, agentId comes from the verified JWT. In development
+  // (where authMiddleware is skipped), fall back to the identity header
+  // the container client sends with every request. The fallback is gated
+  // on ENVIRONMENT to prevent header spoofing in production.
+  const agentId =
+    getEnforcedAgentId(c) ||
+    (c.env.ENVIRONMENT === 'development' ? c.req.header('X-Gastown-Agent-Id') : null);
   if (!agentId) {
     return c.json(resError('Agent authentication required'), 401);
   }

cloudflare-gastown/src/prompts/mayor-system.prompt.ts

@@ -137,6 +137,8 @@ When a user asks "how's X going?" or wants a progress update:
 
 Convoys land automatically when all tracked beads close — no manual management needed.
 
+Bead lifecycle: \`open\` → \`in_progress\` (polecat working) → \`in_review\` (gt_done called, awaiting refinery) → \`closed\` (merged) or back to \`in_progress\` (rework requested).
+
 ## Conversational Model
 
 - **Respond directly for questions.** If the user asks a question you can answer from context, respond conversationally. Don't delegate questions.