Show what a review will examine before anyone pays for it

Work item V4 of the M3 plan: the pre-flight panel and the linked-project
toggle, the two things the new-review screen was missing.

The pre-flight endpoint is read-only and free. Git and arithmetic only: it
fetches, diffs, parses, runs the mechanical sweep and estimates the heaviest
prompt the run would send. No model is called and nothing is written. A review
is expensive enough that seeing its size first, and noticing that a branch pair
is empty or enormous, is worth a round trip. Its pins are advisory and the
panel says so, because creating the review fetches and pins again.

Sweep problems are reported separately from sweep hits. A pattern that could
not run means an incomplete sweep, which the pipeline refuses outright, and
seeing that before paying is worth more than the hit count. The panel also says
plainly when a model has not been probed, so its context window is unknown and
the review will run unsplit, rather than quietly guessing at a limit.

The dependency toggle is never on by default. When the dependency has a branch
of the same name as the one being reviewed it is preselected and labelled
suggested, because that is almost always the other half of the change, and
almost always is not always.

Driven against a running server: primary alone reported ten files, ten hunks,
one request; including the dependency reported eleven files and the two changed
exported symbols the fixture plants, and creating the linked review pinned both
sides. Asking for a dependency that is not registered as one is refused by
name.

Two corrections the work forced. A test asserting the fixture produces sweep
hits failed, and measuring showed it genuinely produces none: six patterns run
and none match, so the test now asserts that every pattern ran, which is the
part that matters. And the screen server-rendered a blank page, because its
Suspense boundary had a null fallback; it now falls back to the header it is
about to show anyway.

Author: Poolchaos

docs/DECISIONS.md

@@ -691,3 +691,21 @@ verified evidence, in writing, here.
   the branch already chosen. Arriving at a form that has forgotten the choice
   just made is the kind of small friction that makes a tool feel like
   paperwork.
+- 2026-07-31 DECIDED (V4, D-37): the pre-flight endpoint is read-only and free.
+  Git and arithmetic only: it fetches, diffs, parses, runs the sweep and
+  estimates tokens, and writes nothing except the fetch timestamp. Its pins are
+  advisory and the screen says so, because creating the review fetches and pins
+  again (D-27); the numbers are a preview rather than a promise.
+- 2026-07-31 DECIDED (V4): the pre-flight reports sweep problems separately
+  from sweep hits. A pattern that could not run means an incomplete sweep,
+  which the pipeline refuses outright, and seeing that before paying is worth
+  more than the hit count itself.
+- 2026-07-31 NOTED (V4): the seeded fixture produces zero sweep hits against
+  the example protocol. Six patterns run and none match its changed lines.
+  Measured rather than assumed: a test asserting hits were non-zero failed, and
+  the expectation was wrong rather than the code. What the test asserts now is
+  that every pattern ran.
+- 2026-07-31 DECIDED (V4): a dependency is never included in a review
+  automatically. When the dependency has a branch of the same name as the one
+  being reviewed it is preselected and labelled as suggested, because that is
+  almost always the other half of the change, and almost always is not always.

docs/plans/M3-FINISH-PLAN.md

@@ -346,7 +346,7 @@ confirms the wiring.
 | 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         | DONE   |
 | V3 | project detail page, fetch-now, links CRUD, project delete    | V1         | DONE   |
-| V4 | preflight route and panel, linked toggle with suggestion      | V3         |        |
+| V4 | preflight route and panel, linked toggle with suggestion      | V3         | DONE   |
 | V5 | report renderer, report/export routes, report UI              | V2         |        |
 | V6 | resume/queued/merged/delete UI, settings editor, probe buttons | V2         |        |
 | V7 | rulesets detail, enable toggle, snapshot filter, export       | V1         |        |

src/app/api/reviews/preflight/route.ts

@@ -0,0 +1,183 @@
+/**
+ * What a review would examine, before anyone pays for it.
+ *
+ * Read-only and free: git and arithmetic, no model calls, nothing written.
+ * That is the whole point. A review is expensive enough that being able to see
+ * the size of it beforehand, and to notice that a branch pair is empty or
+ * enormous, is worth a round trip.
+ *
+ * The pins here are advisory. Creating a review fetches and pins again (D-27),
+ * because the answer must be taken at the moment the review is made, not the
+ * moment someone looked at a panel. The screen says so.
+ */
+
+import { z } from "zod";
+import { reviewProfileSchema } from "@/lib/domain/enums";
+import { parseUnifiedDiff, type ParsedFile } from "@/lib/git/diff";
+import { changedExportedSymbols } from "@/lib/git/symbols";
+import { repoSlug } from "@/lib/git/url";
+import { estimateTokens, budgetFor } from "@/lib/review/budget";
+import { outputContractFor, stageSchemaFor } from "@/lib/review/stage-schemas";
+import { runSweeps } from "@/lib/review/sweep";
+import { composeSystemPrompt, planRuleBatches } from "@/lib/rulesets/compose";
+import { availabilityOf, getModel } from "@/server/db/repositories/models";
+import { recordFetch, requireProject } from "@/server/db/repositories/projects";
+import { loadRuleset } from "@/server/db/repositories/rulesets";
+import { diffText, fetchAll, mergeBase, resolveCommit } from "@/server/gitops/repo";
+import { git } from "@/server/gitops/run";
+import { renderAdversarialPrompt, type ChangedFileEntry } from "@/server/review/content";
+import { failed, handler, ok, readJson } from "@/server/api/respond";
+import { runtime } from "@/server/runtime";
+
+export const dynamic = "force-dynamic";
+
+const body = z.object({
+  projectId: z.string().min(1),
+  fromBranch: z.string().min(1),
+  intoBranch: z.string().min(1),
+  rulesetId: z.string().min(1),
+  model: z.string().min(1),
+  profileId: reviewProfileSchema.default("full-context"),
+  linked: z
+    .object({
+      projectId: z.string().min(1),
+      fromBranch: z.string().min(1),
+      intoBranch: z.string().min(1),
+    })
+    .optional(),
+});
+
+interface Side {
+  slug: string;
+  files: ParsedFile[];
+  fromCommit: string;
+  intoCommit: string;
+  mergeBaseCommit: string;
+  subject: string;
+  hunks: number;
+}
+
+export function POST(request: Request): Promise<Response> {
+  return handler(async () => {
+    const { db } = runtime();
+    const input = await readJson(request, body);
+    const project = requireProject(db, input.projectId);
+    const ruleset = loadRuleset(db, input.rulesetId);
+
+    let primary: Side;
+    let linkedSide: Side | undefined;
+    try {
+      primary = await inspect(project.clonePath, repoSlug(project.name), input);
+      recordFetch(db, project.id);
+
+      if (input.linked) {
+        const dependency = requireProject(db, input.linked.projectId);
+        const slug =
+          repoSlug(dependency.name) === primary.slug
+            ? `${repoSlug(dependency.name)}-dep`
+            : repoSlug(dependency.name);
+        linkedSide = await inspect(dependency.clonePath, slug, input.linked);
+        recordFetch(db, dependency.id);
+      }
+    } catch (error) {
+      // A branch that vanished, or a remote that will not answer. Git's own
+      // words, because they say which of those it was.
+      return failed(error, 400);
+    }
+
+    const entries: ChangedFileEntry[] = [
+      ...primary.files.map((file) => ({ repo: "primary" as const, slug: primary.slug, file })),
+      ...(linkedSide?.files ?? []).map((file) => ({
+        repo: "linked" as const,
+        slug: linkedSide!.slug,
+        file,
+      })),
+    ];
+
+    const sweep = runSweeps(
+      entries.map((entry) => ({ repo: entry.repo, file: entry.file })),
+      ruleset.rules,
+    );
+
+    const changedSymbols = linkedSide ? changedExportedSymbols(linkedSide.files) : [];
+    const plan = planRuleBatches(
+      ruleset.rules,
+      entries.map((entry) => `${entry.slug}/${entry.file.path}`),
+      input.profileId,
+    );
+
+    // The heaviest prompt the run would send, which is what decides whether it
+    // has to be split at all.
+    const systemPrompt = composeSystemPrompt({
+      directives: ruleset.directives,
+      rules: ruleset.rules,
+      stage: "s3_adversarial",
+      includeFullRules: true,
+      outputContract: outputContractFor(stageSchemaFor("s3_adversarial")),
+    });
+    const prompt = renderAdversarialPrompt({
+      files: entries,
+      sweepHits: sweep.hits.map((hit) => ({ ...hit, path: hit.path })),
+      ...(changedSymbols.length === 0 ? {} : { changedSymbols }),
+    });
+    const estimate = estimateTokens(systemPrompt) + estimateTokens(prompt);
+
+    const model = getModel(db, input.model);
+    const window =
+      model && availabilityOf(model) === "available" ? (model.contextWindow ?? null) : null;
+
+    return ok({
+      pins: {
+        primary: sidePins(primary),
+        ...(linkedSide ? { linked: sidePins(linkedSide) } : {}),
+      },
+      files: entries.length,
+      hunks: primary.hunks + (linkedSide?.hunks ?? 0),
+      sweepHits: sweep.hits.length,
+      // A pattern that could not be run means the sweep is incomplete, which
+      // the pipeline refuses outright. Better seen here than after paying.
+      sweepProblems: sweep.problems.map((problem) => problem.reason),
+      changedSymbols: changedSymbols.length,
+      estimatedTokens: estimate,
+      contextWindow: window,
+      withinWindow: window === null ? null : estimate <= budgetFor(window),
+      requests: plan.batches.length,
+      excludedPairs: plan.excluded.length,
+      profile: input.profileId,
+    });
+  });
+}
+
+function sidePins(side: Side) {
+  return {
+    slug: side.slug,
+    fromCommit: side.fromCommit,
+    intoCommit: side.intoCommit,
+    mergeBaseCommit: side.mergeBaseCommit,
+    subject: side.subject,
+    files: side.files.length,
+    hunks: side.hunks,
+  };
+}
+
+async function inspect(
+  repoDir: string,
+  slug: string,
+  branches: { fromBranch: string; intoBranch: string },
+): Promise<Side> {
+  await fetchAll(repoDir);
+  const fromCommit = await resolveCommit(repoDir, branches.fromBranch);
+  const intoCommit = await resolveCommit(repoDir, branches.intoBranch);
+  const mergeBaseCommit = await mergeBase(repoDir, branches.intoBranch, branches.fromBranch);
+  const files = parseUnifiedDiff(await diffText(repoDir, mergeBaseCommit, fromCommit));
+
+  return {
+    slug,
+    files,
+    fromCommit,
+    intoCommit,
+    mergeBaseCommit,
+    subject: (await git(["log", "-1", "--format=%s", fromCommit], { cwd: repoDir })).trim(),
+    hunks: files.reduce((total, file) => total + file.hunks.length, 0),
+  };
+}