Put a ceiling on what a stage can spend, and say which engine answered

Work item V1 of the M3 plan: spend safety first, before any more surface area.

Every engine call now carries --max-budget-usd from a new stageMaxBudgetUsd
setting, default 15 USD-equivalent. The flag was already plumbed through the
command builder and nothing had ever set it, so a runaway stage was bounded by
nothing at all. Per call rather than per review, because that is what the CLI
flag means. Zero disables it, which is a choice someone makes on purpose
rather than a default they fall into.

Every run also opens with a note naming the engine binary, the model and the
effort. That comes straight from the incident on this machine: a manual UI
test spent about 0.50 USD-equivalent because TRYSQUARE_CLAUDE_PATH did not
reach the server process, and the only way I noticed was that the token counts
looked like a real model rather than the fake's fixed numbers. A fake-versus-
real mixup should be readable from the run, not deduced afterwards.

Worktrees are now removed when a run settles cancelled or failed, which
nothing did before, so they accumulated. They stay while a run is paused,
interrupted or awaiting confirmation, because those will be read again: the
confirmation screen reads file context from the worktree. Cleanup is best
effort, and a failure to remove becomes a note rather than masking the outcome
that actually matters.

Two smaller defects from the shipped UI slice: the project name linked to
/projects/[id], which is an empty directory and a 404, so it is plain text
until V3 builds that page; and the review page grew its activity list without
bound, so it keeps the last two hundred lines and leaves the archive to the
event log.

Three mutations checked and all caught: dropping the budget pass-through,
keeping worktrees on cancel, and never writing the engine note.

Author: Poolchaos

docs/DECISIONS.md

@@ -637,3 +637,22 @@ verified evidence, in writing, here.
   and is fixed with the documented turbopackIgnore comment. Re-check
   trigger: if the app ever adopts output "standalone", this acceptance is
   void and the warning must be resolved.
+- 2026-07-31 DECIDED (V1, D-30): every engine call carries --max-budget-usd
+  from the stageMaxBudgetUsd setting, default 15 USD-equivalent. Zero
+  disables the flag, which is a choice someone makes on purpose rather than
+  a default they fell into. Per call rather than per review, because the CLI
+  flag is per call; a runaway stage is bounded even when nothing else goes
+  wrong.
+- 2026-07-31 DECIDED (V1, D-31): nothing spends model usage without an
+  explicit user action: starting a review, pressing a probe button, or
+  running the demo without --fake. There is no automatic probing at startup
+  or anywhere else. Reason: the 2026-07-31 incident where a manual test
+  silently used the real CLI and spent about 0.50 USD-equivalent.
+- 2026-07-31 DECIDED (V1, D-32): every run opens with a run note naming the
+  engine binary it will use, the model and the effort, so a fake-versus-real
+  mixup is readable from the run itself instead of deduced from token counts.
+- 2026-07-31 DECIDED (V1, D-33): worktrees are removed when a run settles
+  cancelled or failed, and kept while it is paused, interrupted or awaiting
+  confirmation; complete joins the cleanup list when the confirmation flow
+  lands (D-12 as implemented). Cleanup is best effort: a failure to remove
+  becomes a run note, never a mask over the outcome that matters.

docs/plans/M3-FINISH-PLAN.md

@@ -343,7 +343,7 @@ confirms the wiring.
 
 | V  | Contents                                                     | Depends on | Status |
 | -- | ------------------------------------------------------------ | ---------- | ------ |
-| V1 | budget cap, engine note, no-auto-probe, worktree cleanup, 404 unlink, activity cap | -          |        |
+| V1 | budget cap, engine note, no-auto-probe, worktree cleanup, 404 unlink, activity cap | -          | DONE   |
 | V2 | confirm/dismiss/complete/context routes, confirmation UI, keyboard map | V1         |        |
 | V3 | project detail page, fetch-now, links CRUD, project delete    | V1         |        |
 | V4 | preflight route and panel, linked toggle with suggestion      | V3         |        |

src/app/projects/page.tsx

@@ -122,16 +122,7 @@ export default function ProjectsPage() {
                   <div className="flex flex-wrap items-start justify-between gap-3">
                     <div className="min-w-0">
                       <div className="flex items-center gap-2">
-                        {project.cloneStatus === "ready" ? (
-                          <Link
-                            href={`/projects/${project.id}`}
-                            className="font-medium hover:underline"
-                          >
-                            {project.name}
-                          </Link>
-                        ) : (
-                          <span className="font-medium">{project.name}</span>
-                        )}
+                        <span className="font-medium">{project.name}</span>
                         {project.cloneStatus === "pending" ? (
                           <Badge tone="accent">cloning</Badge>
                         ) : project.cloneStatus === "failed" ? (

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

@@ -91,10 +91,13 @@ export default function ReviewPage({ params }: { params: Promise<{ id: string }>
         detail?: string;
       };
 
-      if (parsed.kind === "stage")
-        setLive((lines) => [...lines, `${parsed.stage} ${parsed.phase}`]);
-      if (parsed.kind === "engine") setLive((lines) => [...lines, `  ${parsed.detail}`]);
-      if (parsed.kind === "note") setLive((lines) => [...lines, `note: ${parsed.note?.message}`]);
+      // Kept as a bounded tail: a long run emits thousands of engine lines,
+      // and the page only ever shows the most recent of them. The archive is
+      // the event log, not component state.
+      const push = (line: string) => setLive((lines) => [...lines, line].slice(-200));
+      if (parsed.kind === "stage") push(`${parsed.stage} ${parsed.phase}`);
+      if (parsed.kind === "engine") push(`  ${parsed.detail}`);
+      if (parsed.kind === "note") push(`note: ${parsed.note?.message}`);
 
       // Durable facts are written before they are announced, so a read here
       // always finds the row already changed.

src/server/db/repositories/settings.ts

@@ -33,6 +33,8 @@ export function writeSetting(db: Db, key: string, value: unknown): void {
 export const SETTING_KEYS = {
   maxConcurrentReviews: "maxConcurrentReviews",
   stageTimeoutMinutes: "stageTimeoutMinutes",
+  /** USD-equivalent ceiling per engine call. Zero disables the ceiling. */
+  stageMaxBudgetUsd: "stageMaxBudgetUsd",
   defaultModel: "defaultModel",
   defaultEngineMode: "defaultEngineMode",
 } as const;

src/server/review/engine-runner.ts

@@ -130,6 +130,8 @@ export interface EngineRunnerOptions {
   timeoutMs: number;
   /** How hard the model is asked to think. Unset leaves it to the CLI. */
   effort?: string | undefined;
+  /** USD-equivalent ceiling per CLI call. Unset passes no flag. */
+  maxBudgetUsd?: number | undefined;
   directives: readonly ImportedDirective[];
   rules: readonly ImportedRule[];
   claudePath?: string | undefined;
@@ -182,6 +184,7 @@ export function createEngineRunner(options: EngineRunnerOptions): EngineRunner {
       model: options.model,
       outputFormat: "stream-json",
       ...(options.effort === undefined ? {} : { effort: options.effort }),
+      ...(options.maxBudgetUsd === undefined ? {} : { maxBudgetUsd: options.maxBudgetUsd }),
       cwd: options.worktreeRoot,
       timeoutMs: options.timeoutMs,
       logPath: join(options.logsDir, `${request.stage}.log`),
@@ -235,6 +238,7 @@ export function createEngineRunner(options: EngineRunnerOptions): EngineRunner {
       model: options.model,
       outputFormat: "stream-json",
       ...(options.effort === undefined ? {} : { effort: options.effort }),
+      ...(options.maxBudgetUsd === undefined ? {} : { maxBudgetUsd: options.maxBudgetUsd }),
       cwd: options.worktreeRoot,
       timeoutMs: options.timeoutMs,
       logPath: join(options.logsDir, `${request.stage}.repair.log`),

src/server/review/service.ts

@@ -87,6 +87,15 @@ import { runReviewPipeline, type PipelineResult, type StageRequest } from "./pip
 /** Twenty minutes. A stage that reads a large change set is not quick. */
 const DEFAULT_STAGE_TIMEOUT_MINUTES = 20;
 
+/**
+ * The default USD-equivalent ceiling per engine call.
+ *
+ * High enough that no honest stage on a large change set hits it, low enough
+ * that a runaway one is bounded. Zero in the setting disables the flag, which
+ * is a choice someone has to make on purpose.
+ */
+const DEFAULT_STAGE_BUDGET_USD = 15;
+
 export class ReviewNotRunnableError extends Error {
   constructor(
     readonly reviewId: string,
@@ -229,6 +238,16 @@ export async function prepareAndRun(
 
   transitionReview(db, reviewId, "running", { currentStage: null });
 
+  // Which binary answers matters as much as which model: a fake-versus-real
+  // mixup must be readable from the run itself, not deduced from token counts.
+  const enginePath = options.claudePath ?? process.env.TRYSQUARE_CLAUDE_PATH;
+  appendRunNote(db, reviewId, {
+    kind: "note",
+    message:
+      `Engine: ${enginePath ?? "claude on PATH"}, model ${review.model}, ` +
+      `effort ${review.effort}.`,
+  });
+
   try {
     const sides = sidesOf(review, project, linkedProject, dataDir, reviewId);
     if (sides.length === 2 && repoSlug(project.name) === repoSlug(linkedProject?.name ?? "")) {
@@ -337,7 +356,7 @@ export async function prepareAndRun(
     transitionReview(db, reviewId, "awaiting_confirmation", { currentStage: null });
     return { kind: "completed", result };
   } catch (error) {
-    return recordFailure(db, reviewId, error, options.signal);
+    return recordFailure(db, reviewId, dataDir, error, options.signal);
   }
 }
 
@@ -431,6 +450,12 @@ function buildRunner(
     z.number().int().positive(),
     DEFAULT_STAGE_TIMEOUT_MINUTES,
   );
+  const budget = readSettingOr(
+    db,
+    SETTING_KEYS.stageMaxBudgetUsd,
+    z.number().nonnegative(),
+    DEFAULT_STAGE_BUDGET_USD,
+  );
 
   const noteStage = (stage: ReviewStage, kind: "live" | "replayed"): void => {
     setCurrentStage(db, reviewId, stage);
@@ -452,6 +477,7 @@ function buildRunner(
     effort: reviewEffortSchema.parse(review.effort),
     directives: snapshot.directives,
     rules: snapshot.rules,
+    ...(budget > 0 ? { maxBudgetUsd: budget } : {}),
     ...((options.claudePath ?? process.env.TRYSQUARE_CLAUDE_PATH)
       ? { claudePath: options.claudePath ?? process.env.TRYSQUARE_CLAUDE_PATH }
       : {}),
@@ -500,12 +526,13 @@ function ensureVerifying(db: Db, reviewId: string): void {
   }
 }
 
-function recordFailure(
+async function recordFailure(
   db: Db,
   reviewId: string,
+  dataDir: string,
   error: unknown,
   signal: AbortSignal | undefined,
-): RunOutcome {
+): Promise<RunOutcome> {
   const message = error instanceof Error ? error.message : String(error);
   const errorClass = error instanceof StageFailedError ? error.errorClass : undefined;
   const logPath = error instanceof StageFailedError ? error.detail.logPath : undefined;
@@ -517,6 +544,7 @@ function recordFailure(
 
   if (errorClass === "cancelled" || signal?.aborted === true) {
     settle(db, reviewId, "cancelled");
+    await discardWorktrees(db, reviewId, dataDir);
     return { kind: "cancelled", reason: message };
   }
 
@@ -525,9 +553,27 @@ function recordFailure(
     message: logPath ? `${message} The stage log is at ${logPath}.` : message,
   });
   settle(db, reviewId, "failed");
+  await discardWorktrees(db, reviewId, dataDir);
   return { kind: "failed", reason: message, logPath };
 }
 
+/**
+ * Removes the checked-out copies after a run that will not resume (D-12:
+ * cancelled and failed here, complete when the confirmation flow lands).
+ * Best effort on purpose: a cleanup failure becomes a note, never a mask
+ * over the outcome that actually matters.
+ */
+async function discardWorktrees(db: Db, reviewId: string, dataDir: string): Promise<void> {
+  try {
+    await removeReviewWorktrees(db, reviewId, dataDir);
+  } catch (error) {
+    appendRunNote(db, reviewId, {
+      kind: "note",
+      message: `The worktrees could not be removed: ${error instanceof Error ? error.message : String(error)}`,
+    });
+  }
+}
+
 /**
  * Records how a run ended, without letting the recording throw.
  *

tests/server/review/service.test.ts

@@ -26,9 +26,11 @@ import {
   createReview,
   getReview,
   markOrphanedReviewsInterrupted,
+  readRunNotes,
   requireReview,
   transitionReview,
 } from "@/server/db/repositories/reviews";
+import { SETTING_KEYS, writeSetting } from "@/server/db/repositories/settings";
 import { models, reviews } from "@/server/db/schema";
 import { recordProbeSuccess, registerCandidate } from "@/server/db/repositories/models";
 import { listLedgerFiles } from "@/server/db/repositories/ledger";
@@ -857,3 +859,75 @@ describe("telling the reviewer what the change was for", () => {
     expect(hashes[1]).not.toBe(before);
   }, 180_000);
 });
+
+describe("what a run is allowed to spend", () => {
+  it("caps every engine call at the configured budget", async () => {
+    // The ceiling exists for the call nothing else bounds: a runaway stage.
+    // Per call rather than per review, because the CLI flag is per call.
+    const reviewId = seedReview();
+    writeIdealAnswers();
+    await run(reviewId);
+
+    const calls = recordedArgv();
+    expect(calls).toHaveLength(5);
+    for (const [index, args] of calls.entries()) {
+      expect(args[args.indexOf("--max-budget-usd") + 1], `call ${index + 1}`).toBe("15");
+    }
+  }, 120_000);
+
+  it("omits the ceiling only when someone set it to zero on purpose", async () => {
+    writeSetting(db, SETTING_KEYS.stageMaxBudgetUsd, 0);
+    const reviewId = seedReview();
+    writeIdealAnswers();
+    await run(reviewId);
+
+    for (const args of recordedArgv()) expect(args).not.toContain("--max-budget-usd");
+  }, 120_000);
+});
+
+describe("what the run says about itself", () => {
+  it("records which engine binary answered, with the model and effort", async () => {
+    // A fake-versus-real mixup must be readable from the run itself, not
+    // deduced from token counts afterwards.
+    const reviewId = seedReview();
+    writeIdealAnswers();
+    await run(reviewId);
+
+    const note = readRunNotes(requireReview(db, reviewId)).find((entry) =>
+      entry.message.startsWith("Engine:"),
+    );
+    expect(note?.message).toContain("fake-claude.mjs");
+    expect(note?.message).toContain("claude-fable-5[1m]");
+    expect(note?.message).toContain("effort high");
+  }, 120_000);
+});
+
+describe("what is left on disk after a run stops", () => {
+  it("removes the worktrees when a run is cancelled, and keeps the evidence", async () => {
+    // D-12: cancelled will not resume, so the checkout goes; the bundle and
+    // logs stay, because a stopped run is exactly when someone reads them.
+    const reviewId = seedReview();
+    writeIdealAnswers();
+    const controller = new AbortController();
+    await run(reviewId, {
+      signal: controller.signal,
+      onStageLifecycle: (event: StageLifecycleEvent) => {
+        if (event.stage === "s2_comprehension") controller.abort();
+      },
+    });
+
+    expect(requireReview(db, reviewId).status).toBe("cancelled");
+    expect(existsSync(worktreeRootDir(dataDir, reviewId))).toBe(false);
+    expect(existsSync(join(bundleDir(dataDir, reviewId), "inventory.json"))).toBe(true);
+  }, 120_000);
+
+  it("keeps the worktrees while a run is paused, because it will resume", async () => {
+    const reviewId = seedReview();
+    writeIdealAnswers();
+    process.env.FAKE_CLAUDE_FAIL_AT = "3";
+    await run(reviewId);
+
+    expect(requireReview(db, reviewId).status).toBe("paused_limit");
+    expect(existsSync(worktreeRootDir(dataDir, reviewId))).toBe(true);
+  }, 120_000);
+});