fix(task-board): a review cycle always ends in a verdict or a person

apps/api/migrations/192-task-board-verdict-nudge-activity.ts

@@ -0,0 +1,52 @@
+import { type Kysely, sql } from "kysely";
+
+/** Migration 180's action list, plus `review_verdict_requested` — recorded when
+ *  a reviewer run that ended without a decision is asked for one. Frozen
+ *  snapshot: the constraint is replaced wholesale because 180 may already be
+ *  live, so editing its list in place wouldn't reach a deployed database.
+ *  `activity-actions.test.ts` reads this one (the newest) to prove SQL and
+ *  TypeScript agree. */
+export const ACTIONS = [
+  "created",
+  "status_changed",
+  "assignee_changed",
+  "priority_changed",
+  "due_date_changed",
+  "title_changed",
+  "description_changed",
+  "tags_changed",
+  "review_requested",
+  "review_approved",
+  "review_changes_requested",
+  "review_verdict_requested",
+  "merge_conflict_resolution",
+  "merge_failed",
+  "type_changed",
+] as const;
+
+const NEW_ACTIONS = new Set(["review_verdict_requested"]);
+
+export async function up(db: Kysely<unknown>): Promise<void> {
+  await replaceActivityActionCheck(db, ACTIONS);
+}
+
+export async function down(db: Kysely<unknown>): Promise<void> {
+  await replaceActivityActionCheck(
+    db,
+    ACTIONS.filter((a) => !NEW_ACTIONS.has(a)),
+  );
+}
+
+/** Swap `task_board_activity`'s action CHECK constraint for one allowing
+ *  exactly `actions`. */
+async function replaceActivityActionCheck(
+  db: Kysely<unknown>,
+  actions: readonly string[],
+): Promise<void> {
+  await sql`ALTER TABLE task_board_activity DROP CONSTRAINT chk_task_board_activity_action`.execute(
+    db,
+  );
+  await sql`ALTER TABLE task_board_activity ADD CONSTRAINT chk_task_board_activity_action CHECK (action IN (${sql.join(
+    actions.map((a) => sql.lit(a)),
+  )}))`.execute(db);
+}

apps/api/migrations/index.ts

@@ -190,6 +190,7 @@ import * as migration188invitationautoaccept from "./188-invitation-auto-accept.
 import * as migration189taskboardcolumnautomations from "./189-task-board-column-automations.ts";
 import * as migration190taskboardreviewcyclestartedat from "./190-task-board-review-cycle-started-at.ts";
 import * as migration191taskboardcolumns from "./191-task-board-columns.ts";
+import * as migration192taskboardverdictnudgeactivity from "./192-task-board-verdict-nudge-activity.ts";
 
 /**
  * Core migrations for the Studio application.
@@ -412,6 +413,8 @@ const migrations: Record<string, Migration> = {
   "190-task-board-review-cycle-started-at":
     migration190taskboardreviewcyclestartedat,
   "191-task-board-columns": migration191taskboardcolumns,
+  "192-task-board-verdict-nudge-activity":
+    migration192taskboardverdictnudgeactivity,
 };
 
 export default migrations;

apps/api/src/tools/task-board/activity-actions.test.ts

@@ -10,7 +10,7 @@
  */
 
 import { expect, test } from "bun:test";
-import { ACTIONS as MIGRATION_ACTIONS } from "../../../migrations/180-task-board-item-type";
+import { ACTIONS as MIGRATION_ACTIONS } from "../../../migrations/192-task-board-verdict-nudge-activity";
 import { TASK_BOARD_ACTIVITY_ACTIONS } from "./schema";
 
 test("the DB CHECK constraint allows exactly the actions TypeScript declares", () => {

apps/api/src/tools/task-board/enqueue-reviewer.test.ts

@@ -15,6 +15,9 @@ import {
   reviewerHandledThisCycle,
   spentAttemptsThisCycle,
   stalePreviewHandoffDue,
+  undecidedReviewerThread,
+  verdictNudgedThreads,
+  awaitingVerdictNudge,
 } from "./enqueue-reviewer";
 
 /** Cycle start (the task last entered In Review) at 10:00. */
@@ -256,6 +259,138 @@ describe("reviewerHandledThisCycle", () => {
   });
 });
 
+describe("a reviewer that completed without recording a verdict", () => {
+  // OS-303 (osklen): the run finished while it was still "standing by" for a
+  // background task, so it never called the decision tool. The card sat In
+  // Review at 0/1 with nothing to move it — no re-dispatch, no hand-off.
+  const completed = taskWith([
+    thread({
+      title: "Reviewer: fix",
+      status: "completed",
+      createdAt: "2026-01-01T10:05:00Z",
+    }),
+  ]);
+
+  it("is not handled, and its attempt is spent, so it re-dispatches", () => {
+    expect(
+      reviewerHandledThisCycle(completed, "reviewer", CYCLE_START, NOW, false),
+    ).toBe(false);
+    expect(
+      spentAttemptsThisCycle(completed, "reviewer", CYCLE_START, NOW, false),
+    ).toBe(1);
+    expect(
+      reviewerAttemptsExhausted(completed, "reviewer", CYCLE_START, NOW, false),
+    ).toBe(false);
+  });
+
+  it("is handled once the verdict is on the cycle's timeline", () => {
+    expect(
+      reviewerHandledThisCycle(completed, "reviewer", CYCLE_START, NOW, true),
+    ).toBe(true);
+    expect(
+      spentAttemptsThisCycle(completed, "reviewer", CYCLE_START, NOW, true),
+    ).toBe(0);
+  });
+
+  it("hands the card over once the budget is gone", () => {
+    const twice = taskWith([
+      thread({
+        title: "Reviewer: fix",
+        status: "completed",
+        createdAt: "2026-01-01T10:05:00Z",
+      }),
+      thread({
+        title: "Reviewer: fix",
+        status: "completed",
+        createdAt: "2026-01-01T10:07:00Z",
+      }),
+    ]);
+    expect(
+      reviewerAttemptsExhausted(twice, "reviewer", CYCLE_START, NOW, false),
+    ).toBe(true);
+  });
+});
+
+describe("the ask for a missing verdict", () => {
+  const completed = taskWith([
+    thread({
+      title: "Reviewer: fix",
+      status: "completed",
+      createdAt: "2026-01-01T10:05:00Z",
+    }),
+  ]);
+  const owedThreadId = completed.threads[0]!.threadId;
+
+  it("names the completed thread that owes a verdict", () => {
+    expect(
+      undecidedReviewerThread(
+        completed,
+        "reviewer",
+        CYCLE_START,
+        new Map(),
+        NOW,
+      )?.threadId,
+    ).toBe(owedThreadId);
+  });
+
+  it("asks each thread at most once", () => {
+    const asked = new Map([[owedThreadId, NOW]]);
+    expect(
+      undecidedReviewerThread(completed, "reviewer", CYCLE_START, asked, NOW),
+    ).toBeNull();
+  });
+
+  it("does not ask a failed or still-live run", () => {
+    const dead = taskWith([
+      thread({
+        title: "Reviewer: fix",
+        status: "failed",
+        createdAt: "2026-01-01T10:05:00Z",
+      }),
+      thread({
+        title: "Reviewer: fix",
+        status: "in_progress",
+        createdAt: "2026-01-01T10:06:00Z",
+      }),
+    ]);
+    expect(
+      undecidedReviewerThread(dead, "reviewer", CYCLE_START, new Map(), NOW),
+    ).toBeNull();
+  });
+
+  it("reads the asks off the cycle's timeline, ignoring older ones", () => {
+    const asked = verdictNudgedThreads(
+      [
+        {
+          action: "review_verdict_requested",
+          data: { threadId: "stale" },
+          occurredAt: "2026-01-01T09:00:00Z",
+        },
+        {
+          action: "review_verdict_requested",
+          data: { threadId: owedThreadId },
+          occurredAt: "2026-01-01T10:06:00Z",
+        },
+        {
+          action: "status_changed",
+          data: { to: "in_review" },
+          occurredAt: "2026-01-01T10:00:00Z",
+        },
+      ],
+      CYCLE_START,
+    );
+    expect([...asked.keys()]).toEqual([owedThreadId]);
+  });
+
+  it("holds the reviewer's attempts back only while an ask is fresh", () => {
+    const at = new Date("2026-01-01T10:06:00Z").getTime();
+    expect(awaitingVerdictNudge(new Map([["t", at]]), NOW)).toBe(true);
+    expect(
+      awaitingVerdictNudge(new Map([["t", at]]), at + 11 * 60 * 1000),
+    ).toBe(false);
+  });
+});
+
 describe("reviewerAttemptsExhausted", () => {
   const failed = (createdAt: string) =>
     thread({ title: "Reviewer: fix", status: "failed", createdAt });