Finish a review's life: resume it, notice it merged, delete it, tune it

Work item V6 of the M3 plan. A review could be started and decided, and after
that the app had nothing to say about it: no way to resume one that paused, no
sign that its branch had since merged, no way to delete it, and no way to
change any setting that governs how it runs.

Merged detection reads the refs the clone already has rather than fetching. It
is a convenience, not something the app owes the network on every page load, so
a merge is noticed at the next fetch, which is what someone does anyway when
they open a branch list. Nothing is deleted automatically: a merged review is
the record of how something got merged, and deciding that history is disposable
is not the app's call.

Writing its test changed the design. The first version checked only finished
reviews and missed the clearest case there is: a draft of a branch that has
since merged is stale before it ever ran, and is exactly what someone would
want to delete. Everything except a review in flight is checked now.

Settings are editable, and only the catalogued keys are accepted, each
validated by its own schema and refused by name otherwise. A settings table
that accepts whatever it is handed is where typos live silently.

Model probing is a button and never a background task, which is the policy V1
set after the incident on this machine: a probe is a real call, and an app that
probed on a timer would spend someone's usage while they were not looking. The
sign-in card runs the CLI's own status check locally and says plainly when a
login bills per token rather than drawing on a subscription.

Driving it live found a shipped bug. readAuthStatus parsed the CLI's output
without a guard, so any binary printing something unexpected threw out of a
status check whose whole job is to answer a question calmly; pointing
TRYSQUARE_CLAUDE_PATH at the fake returned a JSON syntax error instead of "not
signed in". Guarded, tested, and the mutation is caught.

Three other mutations checked and caught: recording a merge without checking
ancestry, writing uncatalogued settings keys, and the unguarded parse.

Author: Poolchaos

docs/DECISIONS.md

@@ -742,3 +742,22 @@ verified evidence, in writing, here.
   the sentence explaining the problem. A report cannot make prose out of a
   comment full of code, so the instruction belongs where the comment is
   written rather than where it is rendered.
+- 2026-07-31 DECIDED (V6, D-41): merged detection reads the refs the clone
+  already has rather than fetching, and runs when a review is opened or listed.
+  It is a convenience, not a fact the app owes the network on every page load,
+  so a branch that merged is noticed at the next fetch, which is what someone
+  does anyway when they open a branch list.
+- 2026-07-31 DECIDED (V6): every review except one that is mid-run is checked
+  for a merge. The first version checked only finished reviews and missed the
+  clearest case there is: a draft of a branch that has since merged is stale
+  before it ever ran, and is exactly what someone would want to delete. A
+  review in flight is the only one where the answer is noise.
+- 2026-07-31 DECIDED (V6, D-43): the settings API accepts only catalogued
+  keys, each validated by its own schema, and refuses anything else by name. A
+  settings table that accepts whatever it is handed is where typos live
+  silently, and a reader cannot tell which keys are real.
+- 2026-07-31 FIXED (V6): `readAuthStatus` parsed the CLI's output without a
+  guard, so any binary that printed something unexpected threw out of a status
+  check whose whole job is to answer a question calmly. Found by pointing
+  TRYSQUARE_CLAUDE_PATH at the fake and watching the route return a JSON
+  syntax error instead of "not signed in".

docs/plans/M3-FINISH-PLAN.md

@@ -348,7 +348,7 @@ confirms the wiring.
 | V3 | project detail page, fetch-now, links CRUD, project delete    | V1         | DONE   |
 | V4 | preflight route and panel, linked toggle with suggestion      | V3         | DONE   |
 | V5 | report renderer, report/export routes, report UI              | V2         | DONE   |
-| V6 | resume/queued/merged/delete UI, settings editor, probe buttons | V2         |        |
+| V6 | resume/queued/merged/delete UI, settings editor, probe buttons | V2         | DONE   |
 | V7 | rulesets detail, enable toggle, snapshot filter, export       | V1         |        |
 | V8 | e2e journey, theme screenshots, design audit, CI --e2e        | V2-V7      |        |
 | V9 | PROJECT-STATE, indexes, FG-2 checklist and evidence, G1 row   | V8         |        |

src/app/api/auth/route.ts

@@ -0,0 +1,22 @@
+/**
+ * Whether the CLI is logged in, and whether runs draw on a subscription.
+ *
+ * Worth surfacing because the difference is money: an API-key login bills per
+ * token, and someone who set one up for something else would otherwise not
+ * find out until a bill arrived. Runs `claude auth status` locally and spends
+ * nothing.
+ */
+
+import { readAuthStatus } from "@/server/engine/probe";
+import { handler, ok } from "@/server/api/respond";
+
+export const dynamic = "force-dynamic";
+
+export function GET(): Promise<Response> {
+  return handler(async () => {
+    const claudePath = process.env.TRYSQUARE_CLAUDE_PATH;
+    return ok({
+      auth: await readAuthStatus(claudePath === undefined ? {} : { claudePath }),
+    });
+  });
+}

src/app/api/models/[id]/probe/route.ts

@@ -0,0 +1,47 @@
+/**
+ * Asking the CLI whether one model is actually usable.
+ *
+ * Only ever from an explicit click (D-31). A probe is a real call that spends
+ * a fraction of a cent, and an app that probed on a timer would spend the
+ * user's usage while they were not looking. The prompt and toolset are minimal
+ * so the cost is as small as a real call can be.
+ */
+
+import {
+  recordProbeFailure,
+  recordProbeSuccess,
+  requireModel,
+} from "@/server/db/repositories/models";
+import { probeModel } from "@/server/engine/probe";
+import { handler, ok } from "@/server/api/respond";
+import { runtime } from "@/server/runtime";
+
+export const dynamic = "force-dynamic";
+
+export async function POST(
+  _request: Request,
+  context: { params: Promise<{ id: string }> },
+): Promise<Response> {
+  return handler(async () => {
+    const { db } = runtime();
+    const { id } = await context.params;
+    const model = requireModel(db, id);
+
+    const claudePath = process.env.TRYSQUARE_CLAUDE_PATH;
+    const outcome = await probeModel(model.id, claudePath === undefined ? {} : { claudePath });
+
+    if (outcome.status === "available") {
+      recordProbeSuccess(db, model.id, {
+        resolvedId: outcome.resolvedId,
+        contextWindow: outcome.contextWindow,
+      });
+    } else {
+      // Indeterminate is recorded as a failure with its own message rather
+      // than left as unknown: "we asked and could not tell" is more useful
+      // than "we never asked".
+      recordProbeFailure(db, model.id, outcome.error);
+    }
+
+    return ok({ outcome, model: requireModel(db, model.id) });
+  });
+}

src/app/api/reviews/[id]/route.ts

@@ -1,7 +1,10 @@
 /** Everything a review page needs in one read. */
 
 import { listFindings } from "@/server/db/repositories/findings";
-import { handler, ok } from "@/server/api/respond";
+import { requireReview } from "@/server/db/repositories/reviews";
+import { deleteReviewEntirely } from "@/server/review/service";
+import { detectMerged } from "@/server/review/merged";
+import { failed, handler, ok } from "@/server/api/respond";
 import { runtime } from "@/server/runtime";
 
 export const dynamic = "force-dynamic";
@@ -13,6 +16,31 @@ export async function GET(
   return handler(async () => {
     const { db, manager } = runtime();
     const { id } = await context.params;
+    await detectMerged(db, [requireReview(db, id)]);
     return ok({ ...manager.snapshot(id), findings: listFindings(db, id) });
   });
 }
+
+/**
+ * Removes a review and everything it produced except its exports.
+ *
+ * Refused while it is running, because a review with a live subprocess needs
+ * cancelling first: deleting the row would orphan the process rather than stop
+ * it.
+ */
+export async function DELETE(
+  _request: Request,
+  context: { params: Promise<{ id: string }> },
+): Promise<Response> {
+  return handler(async () => {
+    const { db, dataDir } = runtime();
+    const { id } = await context.params;
+
+    try {
+      await deleteReviewEntirely(db, id, dataDir);
+    } catch (error) {
+      return failed(error, 409);
+    }
+    return ok({ removed: id });
+  });
+}

src/app/api/reviews/route.ts

@@ -18,6 +18,7 @@ import {
 import { createReview, listActiveReviews } from "@/server/db/repositories/reviews";
 import { fetchAll, mergeBase, resolveCommit } from "@/server/gitops/repo";
 import { created, handler, ok, readJson } from "@/server/api/respond";
+import { detectMerged } from "@/server/review/merged";
 import { runtime } from "@/server/runtime";
 import { listProjects } from "@/server/db/repositories/projects";
 import { listReviewsForProject } from "@/server/db/repositories/reviews";
@@ -44,6 +45,15 @@ const body = z.object({
 export function GET(): Promise<Response> {
   return handler(async () => {
     const { db } = runtime();
+
+    // Checked when the list is opened rather than on a timer: there is no
+    // moment a background poll would be right for, and a stale badge is worse
+    // than a late one (D-19).
+    await detectMerged(
+      db,
+      listProjects(db).flatMap((project) => listReviewsForProject(db, project.id)),
+    );
+
     const reviews = listProjects(db).flatMap((project) =>
       listReviewsForProject(db, project.id).map((review) => ({
         ...review,

src/app/api/settings/route.ts

@@ -0,0 +1,67 @@
+/**
+ * The handful of settings this app has.
+ *
+ * Only catalogued keys, each with its own schema. An unknown key is refused
+ * rather than written, because a settings table that accepts anything becomes
+ * a place where typos live silently and a reader cannot tell which keys are
+ * real.
+ */
+
+import { z } from "zod";
+import { SETTING_KEYS, readSettingOr, writeSetting } from "@/server/db/repositories/settings";
+import { handler, ok, readJson } from "@/server/api/respond";
+import { runtime } from "@/server/runtime";
+
+export const dynamic = "force-dynamic";
+
+/** Every setting, its schema, and what it means when nobody has set it. */
+const CATALOGUE = {
+  [SETTING_KEYS.maxConcurrentReviews]: { schema: z.number().int().positive(), fallback: 1 },
+  [SETTING_KEYS.stageTimeoutMinutes]: { schema: z.number().int().positive(), fallback: 20 },
+  [SETTING_KEYS.stageMaxBudgetUsd]: { schema: z.number().nonnegative(), fallback: 15 },
+} as const;
+
+type Key = keyof typeof CATALOGUE;
+
+export function GET(): Promise<Response> {
+  return handler(async () => {
+    const { db } = runtime();
+    const settings = Object.fromEntries(
+      (Object.keys(CATALOGUE) as Key[]).map((key) => [
+        key,
+        readSettingOr(db, key, CATALOGUE[key].schema, CATALOGUE[key].fallback),
+      ]),
+    );
+    return ok({ settings });
+  });
+}
+
+export function PUT(request: Request): Promise<Response> {
+  return handler(async () => {
+    const { db } = runtime();
+    const body = await readJson(request, z.record(z.string(), z.unknown()));
+
+    for (const [key, value] of Object.entries(body)) {
+      const entry = CATALOGUE[key as Key];
+      if (!entry) {
+        throw Response.json(
+          { error: `There is no setting called "${key}".`, code: "UnknownSetting" },
+          { status: 400 },
+        );
+      }
+      const parsed = entry.schema.safeParse(value);
+      if (!parsed.success) {
+        throw Response.json(
+          {
+            error: `${key}: ${parsed.error.issues[0]?.message ?? "is not valid"}`,
+            code: "Invalid",
+          },
+          { status: 400 },
+        );
+      }
+      writeSetting(db, key, parsed.data);
+    }
+
+    return (await GET()) as Response;
+  });
+}

src/app/reviews/[id]/page.tsx

@@ -43,6 +43,7 @@ interface Snapshot {
     effort: string;
     intent: string | null;
     pausedReason: string | null;
+    mergedDetectedAt: string | null;
     usageInputTokens: number;
     usageOutputTokens: number;
     usageCacheReadTokens: number;
@@ -52,6 +53,7 @@ interface Snapshot {
   notes: { kind: string; message: string; at: string }[];
   findings: Finding[];
   running: boolean;
+  queued: boolean;
 }
 
 export default function ReviewPage({ params }: { params: Promise<{ id: string }> }) {
@@ -60,6 +62,8 @@ export default function ReviewPage({ params }: { params: Promise<{ id: string }>
   const [live, setLive] = useState<string[]>([]);
   const [report, setReport] = useState<string | null>(null);
   const [exported, setExported] = useState("");
+  const [confirmingDelete, setConfirmingDelete] = useState(false);
+  const [actionError, setActionError] = useState("");
 
   async function reload() {
     const response = await fetch(`/api/reviews/${id}`);
@@ -174,27 +178,85 @@ export default function ReviewPage({ params }: { params: Promise<{ id: string }>
         }
         subtitle={
           <span className="flex flex-wrap items-center gap-2">
-            <Badge tone={statusTone(review.status)}>{review.status.replace(/_/g, " ")}</Badge>
+            <Badge tone={statusTone(review.status)}>
+              {snapshot.queued ? "queued" : review.status.replace(/_/g, " ")}
+            </Badge>
+            {review.mergedDetectedAt ? <Badge tone="good">merged</Badge> : null}
             <Sha value={review.fromCommit} />
             <span>{review.model}</span>
             <span>effort {review.effort}</span>
           </span>
         }
         actions={
-          snapshot.running ? (
-            <Button
-              onClick={async () => {
-                await fetch(`/api/reviews/${id}/cancel`, { method: "POST" });
-                await reload();
-              }}
-            >
-              Cancel
-            </Button>
-          ) : null
+          <>
+            {review.status === "paused_limit" || review.status === "interrupted" ? (
+              <Button
+                variant="primary"
+                onClick={async () => {
+                  // No ruleset needed: a resumed review already carries the
+                  // one it was frozen with.
+                  await fetch(`/api/reviews/${id}/start`, { method: "POST" });
+                  await reload();
+                }}
+              >
+                Resume
+              </Button>
+            ) : null}
+
+            {snapshot.running || snapshot.queued ? (
+              <Button
+                onClick={async () => {
+                  await fetch(`/api/reviews/${id}/cancel`, { method: "POST" });
+                  await reload();
+                }}
+              >
+                Cancel
+              </Button>
+            ) : null}
+
+            {!snapshot.running && !snapshot.queued ? (
+              confirmingDelete ? (
+                <>
+                  <Button
+                    variant="primary"
+                    onClick={async () => {
+                      const response = await fetch(`/api/reviews/${id}`, { method: "DELETE" });
+                      if (response.ok) window.location.href = "/reviews";
+                      else
+                        setActionError(
+                          ((await response.json()) as { error?: string }).error ??
+                            "The review could not be deleted.",
+                        );
+                    }}
+                  >
+                    Yes, delete
+                  </Button>
+                  <Button variant="quiet" onClick={() => setConfirmingDelete(false)}>
+                    Keep
+                  </Button>
+                </>
+              ) : (
+                <Button onClick={() => setConfirmingDelete(true)}>Delete</Button>
+              )
+            ) : null}
+          </>
         }
       />
       <PageBody>
+        {actionError ? <Problem>{actionError}</Problem> : null}
         {review.pausedReason ? <Problem>{review.pausedReason}</Problem> : null}
+        {review.mergedDetectedAt ? (
+          <p className="mb-4 text-sm text-[var(--color-ink-muted)]">
+            This branch has since merged into {review.intoBranch}. The review is kept until you
+            delete it.
+          </p>
+        ) : null}
+        {snapshot.queued ? (
+          <p className="mb-4 text-sm text-[var(--color-ink-muted)]">
+            Waiting for the running review to finish. One runs at a time, because two would race for
+            the same usage limit.
+          </p>
+        ) : null}
 
         <div className="grid gap-6 lg:grid-cols-[1fr_20rem]">
           <div className="min-w-0">

src/app/reviews/page.tsx

@@ -14,6 +14,7 @@ interface Row {
   intoBranch: string;
   status: string;
   createdAt: string;
+  mergedDetectedAt: string | null;
 }
 
 export default function ReviewsPage() {
@@ -48,6 +49,7 @@ export default function ReviewsPage() {
                       <Badge tone={statusTone(review.status)}>
                         {review.status.replace(/_/g, " ")}
                       </Badge>
+                      {review.mergedDetectedAt ? <Badge tone="good">merged</Badge> : null}
                       <span className="text-sm font-medium">{review.projectName}</span>
                       <Mono className="truncate text-xs text-[var(--color-ink-muted)]">
                         {review.fromBranch} into {review.intoBranch}