truecourse 0.7.0-next.0 → 0.7.0-next.2

package/server.mjs

@@ -28079,7 +28079,7 @@ function parseBlockedOnCapabilities(reason) {
     return [];
   return m[1].split(",").map((s) => s.trim()).filter(Boolean);
 }
-var GuardWrittenScenarioSchema, GuardCoverageGapKindSchema, GuardCoverageGapSchema, GuardBirthFindingSchema, GuardGenerateErrorSchema, GuardExtractionFailureSchema, GuardOrphanedSectionSchema, GuardRecipeReportSchema, GuardGenerateUsageSchema, GuardGenerateReportSchema;
+var GuardWrittenScenarioSchema, GuardCoverageGapKindSchema, GuardCoverageGapSchema, GuardBirthFindingSchema, GuardGenerateErrorSchema, GuardEntryPreflightSchema, GuardExtractionFailureSchema, GuardOrphanedSectionSchema, GuardRecipeReportSchema, GuardGenerateUsageSchema, GuardGenerateReportSchema;
 var init_report = __esm({
   "packages/shared/dist/guard/report.js"() {
     "use strict";
@@ -28132,6 +28132,14 @@ var init_report = __esm({
       anchor: external_exports.string(),
       message: external_exports.string()
     }).strict();
+    GuardEntryPreflightSchema = external_exports.object({
+      /** Display form of the entry argv, e.g. `node tools/cli/dist/index.js`. */
+      entry: external_exports.string(),
+      /** The recipe build command, for the rebuild hint. */
+      buildCommand: external_exports.string(),
+      /** The full, UNTRUNCATED startup output the dead entry produced. */
+      stderr: external_exports.string()
+    }).strict();
     GuardExtractionFailureSchema = external_exports.object({
       doc: external_exports.string(),
       reason: external_exports.string()
@@ -28177,7 +28185,13 @@ var init_report = __esm({
        */
       birthPassed: external_exports.number().int().nonnegative().optional(),
       manifestPath: external_exports.string().optional(),
-      usage: GuardGenerateUsageSchema.optional()
+      usage: GuardGenerateUsageSchema.optional(),
+      /**
+       * Present ONLY when the built entry failed to start — the whole birth phase was
+       * short-circuited, so every changed section stayed unsettled. Optional so older
+       * reports (written before this field existed) keep parsing.
+       */
+      entryPreflight: GuardEntryPreflightSchema.optional()
     }).strict();
   }
 });
@@ -194710,6 +194724,129 @@ function listSandboxFiles(dir) {
   return out.sort();
 }
 
+// packages/guard-runner/dist/executor.js
+import { spawn as spawn3 } from "node:child_process";
+var DEFAULT_STEP_TIMEOUT_MS = 3e4;
+function executeStep(opts) {
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_STEP_TIMEOUT_MS;
+  const [command, ...args] = opts.argv;
+  const start = Date.now();
+  return new Promise((resolve11) => {
+    const child = spawn3(command, args, {
+      cwd: opts.cwd,
+      env: opts.env,
+      stdio: ["pipe", "pipe", "pipe"]
+    });
+    let stdout = "";
+    let stderr = "";
+    let timedOut = false;
+    let settled = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      child.kill("SIGKILL");
+    }, timeoutMs);
+    const finish = (capture) => {
+      if (settled)
+        return;
+      settled = true;
+      clearTimeout(timer);
+      resolve11(capture);
+    };
+    child.stdout.on("data", (chunk3) => {
+      stdout += chunk3.toString("utf-8");
+    });
+    child.stderr.on("data", (chunk3) => {
+      stderr += chunk3.toString("utf-8");
+    });
+    child.on("error", (err) => {
+      finish({
+        exitCode: null,
+        signal: null,
+        stdout,
+        stderr,
+        timedOut,
+        spawnError: err.message,
+        durationMs: Date.now() - start
+      });
+    });
+    child.on("close", (code, signal) => {
+      finish({
+        exitCode: code,
+        signal,
+        stdout,
+        stderr,
+        timedOut,
+        durationMs: Date.now() - start
+      });
+    });
+    if (opts.stdin !== void 0)
+      child.stdin.write(opts.stdin);
+    child.stdin.end();
+  });
+}
+
+// packages/guard-runner/dist/preflight.js
+var ENTRY_PROBE_ARGVS = [[], ["--help"]];
+var ENTRY_PREFLIGHT_TIMEOUT_MS = 2e4;
+var defaultEntryProbeExecutor = async (fullArgv, recipeEnv, timeoutMs) => {
+  const sandbox = createSandbox({ recipeEnv });
+  try {
+    return await executeStep({ argv: fullArgv, cwd: sandbox.cwd, env: sandbox.env, timeoutMs });
+  } finally {
+    sandbox.cleanup();
+  }
+};
+async function preflightEntry(opts) {
+  const exec = opts.exec ?? defaultEntryProbeExecutor;
+  const timeoutMs = opts.timeoutMs ?? ENTRY_PREFLIGHT_TIMEOUT_MS;
+  const entry = opts.displayEntry.join(" ");
+  const probes = await Promise.all(ENTRY_PROBE_ARGVS.map(async (argv) => ({
+    argv: [...argv],
+    capture: await exec([...opts.resolvedEntry, ...argv], opts.recipeEnv, timeoutMs)
+  })));
+  const ok = entryStarts(probes);
+  return { ok, entry, stderr: ok ? "" : startupOutput(probes[0].capture, timeoutMs), probes };
+}
+function entryStarts(probes) {
+  if (probes.some((p) => startedCleanly(p.capture)))
+    return true;
+  const shapes = probes.map((p) => failureShape(p.capture));
+  return shapes.some((s) => s !== shapes[0]);
+}
+function startedCleanly(c) {
+  return !c.spawnError && !c.timedOut && c.signal === null && c.exitCode === 0;
+}
+function failureShape(c) {
+  return JSON.stringify({
+    spawnError: c.spawnError ?? null,
+    signal: c.signal ?? null,
+    timedOut: c.timedOut,
+    exitCode: c.exitCode,
+    stdout: c.stdout,
+    stderr: c.stderr
+  });
+}
+function startupOutput(c, timeoutMs) {
+  const parts = [];
+  const primary = c.stderr || c.stdout;
+  if (primary)
+    parts.push(primary.trimEnd());
+  if (c.spawnError)
+    parts.push(`failed to spawn: ${c.spawnError}`);
+  if (c.timedOut)
+    parts.push(`(the entry produced no output within ${timeoutMs}ms and was killed)`);
+  if (parts.length === 0) {
+    parts.push(c.exitCode !== null ? `(the entry exited ${c.exitCode} with no output)` : `(the entry was killed by ${c.signal})`);
+  }
+  return parts.join("\n");
+}
+function entryPreflightHeadline(entry, buildCommand) {
+  return `The recipe entry \`${entry}\` failed to start \u2014 it crashes before it runs, so every scenario would fail identically. Rebuild it with \`${buildCommand}\` (its build output is likely stale or incomplete), then retry.`;
+}
+function formatEntryPreflightError(opts) {
+  return [entryPreflightHeadline(opts.entry, opts.buildCommand), "", "Startup output:", opts.stderr].join("\n");
+}
+
 // packages/guard-runner/dist/capabilities/git.js
 import { spawnSync } from "node:child_process";
 import fs15 from "node:fs";
@@ -194790,67 +194927,6 @@ function applyCapabilities(setup, ctx) {
   }
 }
 
-// packages/guard-runner/dist/executor.js
-import { spawn as spawn3 } from "node:child_process";
-var DEFAULT_STEP_TIMEOUT_MS = 3e4;
-function executeStep(opts) {
-  const timeoutMs = opts.timeoutMs ?? DEFAULT_STEP_TIMEOUT_MS;
-  const [command, ...args] = opts.argv;
-  const start = Date.now();
-  return new Promise((resolve11) => {
-    const child = spawn3(command, args, {
-      cwd: opts.cwd,
-      env: opts.env,
-      stdio: ["pipe", "pipe", "pipe"]
-    });
-    let stdout = "";
-    let stderr = "";
-    let timedOut = false;
-    let settled = false;
-    const timer = setTimeout(() => {
-      timedOut = true;
-      child.kill("SIGKILL");
-    }, timeoutMs);
-    const finish = (capture) => {
-      if (settled)
-        return;
-      settled = true;
-      clearTimeout(timer);
-      resolve11(capture);
-    };
-    child.stdout.on("data", (chunk3) => {
-      stdout += chunk3.toString("utf-8");
-    });
-    child.stderr.on("data", (chunk3) => {
-      stderr += chunk3.toString("utf-8");
-    });
-    child.on("error", (err) => {
-      finish({
-        exitCode: null,
-        signal: null,
-        stdout,
-        stderr,
-        timedOut,
-        spawnError: err.message,
-        durationMs: Date.now() - start
-      });
-    });
-    child.on("close", (code, signal) => {
-      finish({
-        exitCode: code,
-        signal,
-        stdout,
-        stderr,
-        timedOut,
-        durationMs: Date.now() - start
-      });
-    });
-    if (opts.stdin !== void 0)
-      child.stdin.write(opts.stdin);
-    child.stdin.end();
-  });
-}
-
 // packages/guard-runner/dist/normalizers.js
 var CANONICAL_ORDER = [
   "abs-paths",
@@ -195481,16 +195557,27 @@ async function runGuard(opts) {
   }));
   const executable = planned.filter((p) => p.resolution.kind === "match" || p.resolution.kind === "remap");
   const nonExecutable = planned.filter((p) => p.resolution.kind === "stale" || p.resolution.kind === "orphaned");
-  if (!opts.skipBuild && executable.length > 0) {
+  const buildsOwnEntry = !opts.skipBuild && executable.length > 0;
+  if (buildsOwnEntry) {
     opts.onPhase?.("build");
     const build8 = await runBuild(repoRoot, loaded.recipe.build, loaded.recipe.env);
     if (!build8.ok)
       return { status: "build-failed", build: build8, loadErrors };
   }
+  const resolvedEntry = resolveEntry(repoRoot, loaded.recipe.entry);
+  if (buildsOwnEntry) {
+    const preflight = await preflightEntry({
+      resolvedEntry,
+      displayEntry: loaded.recipe.entry,
+      recipeEnv: loaded.recipe.env
+    });
+    if (!preflight.ok) {
+      return { status: "entry-preflight-failed", preflight, buildCommand: loaded.recipe.build, loadErrors };
+    }
+  }
   opts.onPhase?.("run", selected.length);
   const runId = buildRunId();
   const ranAt = (/* @__PURE__ */ new Date()).toISOString();
-  const resolvedEntry = resolveEntry(repoRoot, loaded.recipe.entry);
   const stepTimeoutMs = opts.stepTimeoutMs ?? DEFAULT_STEP_TIMEOUT_MS;
   const concurrency = opts.concurrency ?? defaultRunConcurrency();
   const results = [];
@@ -196071,8 +196158,14 @@ var CorpusDocSchema = external_exports.object({
 var OverlapSectionSchema = external_exports.object({
   /** The doc this section lives in, by ref (one of the overlap's two docs). */
   doc: DocRefSchema,
-  /** The heading text of the conflicting section (verbatim from the doc). */
-  heading: external_exports.string()
+  /**
+   * The heading text of the conflicting section (verbatim from the doc), or
+   * `null` when the conflicting passage sits in the doc's PREAMBLE — the block
+   * before its first heading (README badges/tagline, intro line). A plain string
+   * from older corpora still parses; `null` is the preamble marker the viewer
+   * bands as the pre-first-heading block.
+   */
+  heading: external_exports.string().nullable()
 });
 var OverlapSchema = external_exports.object({
   /** The two docs that overlap, by ref. */
@@ -197009,7 +197102,9 @@ NOT a disagreement (do NOT flag):
 
 Bias: when there is a PLAUSIBLE contradiction a human should check, flag it. When the docs are clearly complementary or agree, do not.
 
-When you flag an overlap, also identify the SECTIONS that conflict: the nearest markdown heading (the \`#\`/\`##\`/\`###\` title, verbatim, WITHOUT the leading #s) above the conflicting text in EACH doc. List one entry per side; omit a side only if it genuinely has no heading.
+When you flag an overlap, also identify the SECTIONS that conflict: the nearest markdown heading (the \`#\`/\`##\`/\`###\` title, verbatim, WITHOUT the leading #s) above the conflicting text in EACH doc. List one entry per side; omit a side only when it genuinely has no conflicting passage.
+
+PREAMBLE: when a doc's conflicting passage sits ABOVE its first \`#\` heading \u2014 the preamble block (a README's badges, tagline, or the intro line before any heading) \u2014 there is no heading to name. Set that side's \`heading\` to the JSON literal \`null\` (not the string "null", not ""). Use \`null\` ONLY for that pre-first-heading block; whenever the passage is under a heading, name the heading verbatim.
 
 In the NOTE, refer to each doc by its FILENAME (the basename shown in the header, e.g. \`users.md\`) \u2014 NEVER "doc A" / "doc B", which mean nothing to the reader.
 
@@ -197019,6 +197114,12 @@ Output ONLY a JSON object, no prose, no code fences:
   "note": "users.md uses auth0_id; identity.md uses auth0_sub for the same user column",
   "sections": [ { "side": "A", "heading": "User model" }, { "side": "B", "heading": "Identity" } ] }
 
+Preamble example \u2014 doc A's claim is a README badge/tagline above any heading, so its side uses null:
+
+{ "overlap": true,
+  "note": "README.md lists C# as a supported language in the preamble; plan.md's Tech Stack omits it",
+  "sections": [ { "side": "A", "heading": null }, { "side": "B", "heading": "Tech Stack" } ] }
+
 Use { "overlap": false, "note": "", "sections": [] } when they are complementary or agree. The note is shown to the user \u2014 name the specific thing that differs.`;
 var OVERLAP_PREVIEW_LINES = 120;
 function docBody2(doc) {
@@ -197070,12 +197171,12 @@ function buildOverlapUserPrompt(areaId, a, b) {
 var LlmOverlapSchema = external_exports.object({
   overlap: external_exports.boolean(),
   note: external_exports.string().default(""),
-  sections: external_exports.array(external_exports.object({ side: external_exports.enum(["A", "B"]), heading: external_exports.string() })).default([])
+  sections: external_exports.array(external_exports.object({ side: external_exports.enum(["A", "B"]), heading: external_exports.string().nullable() })).default([])
 });
 var OverlapVerdictSchema = external_exports.object({
   overlap: external_exports.boolean(),
   note: external_exports.string().default(""),
-  sections: external_exports.array(external_exports.object({ doc: external_exports.string(), heading: external_exports.string() })).default([])
+  sections: external_exports.array(external_exports.object({ doc: external_exports.string(), heading: external_exports.string().nullable() })).default([])
 });
 function spawnOverlapRunner(opts = {}) {
   const transport = opts.transport ?? cliTransport({ bin: opts.bin });
@@ -197265,35 +197366,49 @@ function prefilterDocs(docs, manualIncludes = []) {
     skipped: [...reasons].map(([path73, reason]) => ({ path: path73, reason }))
   };
 }
+async function planRelevanceWork(repoRoot, docs, manualIncludes = []) {
+  const manualSet = new Set(manualIncludes);
+  const { toClassify, skipped } = prefilterDocs(docs, manualIncludes);
+  const needsCall = [];
+  const known = /* @__PURE__ */ new Map();
+  await Promise.all(toClassify.map(async (doc) => {
+    if (manualSet.has(doc.path)) {
+      known.set(doc.path, { path: doc.path, include: true, reason: "manual include" });
+      return;
+    }
+    const cached = await readCache4(repoRoot, computeCacheKey5(doc));
+    if (cached)
+      known.set(doc.path, cached);
+    else
+      needsCall.push(doc);
+  }));
+  return { toClassify, prefilterSkipped: skipped, needsCall, known };
+}
 async function filterByRelevance(repoRoot, docs, opts = {}) {
   if (opts.enabled === false || docs.length === 0) {
     return { included: docs, skipped: [] };
   }
-  const manualSet = new Set(opts.manualIncludes ?? []);
   const runner2 = opts.runner ?? spawnRelevanceRunner({ transport: opts.transport, model: opts.model, fallbackModel: opts.fallbackModel });
   const concurrency = opts.concurrency ?? defaultConcurrency();
-  const { toClassify, skipped: prefilterSkipped } = prefilterDocs(docs, opts.manualIncludes ?? []);
-  const prefilterReason = new Map(prefilterSkipped.map((s) => [s.path, s.reason]));
+  const plan = await planRelevanceWork(repoRoot, docs, opts.manualIncludes ?? []);
+  const prefilterReason = new Map(plan.prefilterSkipped.map((s) => [s.path, s.reason]));
   const total = docs.length;
   let done = 0;
   const markDone = () => opts.onProgress?.(++done, total);
   opts.onProgress?.(0, total);
-  for (let i = 0; i < prefilterReason.size; i++)
+  const resolvedUpfront = prefilterReason.size + plan.known.size;
+  for (let i = 0; i < resolvedUpfront; i++)
     markDone();
-  const verdicts = /* @__PURE__ */ new Map();
+  const verdicts = new Map(plan.known);
+  const pending = plan.needsCall;
   let cursor = 0;
   let active12 = 0;
   await new Promise((resolve11) => {
+    if (pending.length === 0)
+      return resolve11();
     const launch = () => {
-      while (active12 < concurrency && cursor < toClassify.length) {
-        const doc = toClassify[cursor++];
-        if (manualSet.has(doc.path)) {
-          verdicts.set(doc.path, { path: doc.path, include: true, reason: "manual include" });
-          markDone();
-          if (cursor >= toClassify.length && active12 === 0)
-            resolve11();
-          continue;
-        }
+      while (active12 < concurrency && cursor < pending.length) {
+        const doc = pending[cursor++];
         active12++;
         classifyOne(repoRoot, doc, runner2).then((verdict) => {
           verdicts.set(doc.path, verdict);
@@ -197306,14 +197421,12 @@ async function filterByRelevance(repoRoot, docs, opts = {}) {
         }).finally(() => {
           markDone();
           active12--;
-          if (cursor >= toClassify.length && active12 === 0)
+          if (cursor >= pending.length && active12 === 0)
             resolve11();
           else
             launch();
         });
       }
-      if (cursor >= toClassify.length && active12 === 0)
-        resolve11();
     };
     launch();
   });
@@ -197427,7 +197540,7 @@ async function classifyOne(repoRoot, doc, runner2) {
   await writeCache4(repoRoot, cacheKey, verdict);
   return verdict;
 }
-var RELEVANCE_SYSTEM_PROMPT = `You are a documentation relevance classifier. Classify by CONTENT, not by folder or filename: does this doc state durable, intended behavior or decisions about THE SYSTEM IN THIS REPOSITORY (its endpoints, data, auth, events, invariants, business rules, architecture)?
+var RELEVANCE_SYSTEM_PROMPT = `You are a documentation relevance classifier. Judge mainly by CONTENT \u2014 does this doc state durable, intended behavior or decisions about THE SYSTEM IN THIS REPOSITORY (its endpoints, data, auth, events, invariants, business rules, architecture)? The doc's PATH (given below) is evidence too, never an automatic verdict: weigh path and content together.
 
 ${OUTPUT_ONLY_GUARDRAIL}
 
@@ -197440,22 +197553,23 @@ INCLUDE (spec-source material):
 SKIP (not spec-source material):
   - Pure status / TODO checklists, kanban boards, release notes / changelog drafts
   - Docs about a THIRD-PARTY / external system (vendor API research, integration notes) \u2014 that is someone else's contract, not ours, and cannot be verified against this codebase
+  - TEST-DATA specs: a doc under a test / fixture / sample / example tree (PATH segments like tests/, fixtures/, __fixtures__/, examples/, sample-*) that describes a FICTIONAL or sample product used as test data for THIS repo's own tooling \u2014 that product is not this repository's system, so its "spec" is not ours. (The path is evidence, not proof: if the doc plainly describes THIS repository's real product or engineering, keep it.)
   - SUPERSEDED docs \u2014 an older version of a newer doc covering the same subject
   - Process / meta docs not about product behavior: contribution / onboarding guides, code-style guides, deployment runbooks (keep a deployment doc ONLY if it states our runtime contracts)
   - Exploratory scratch with no committed decisions (brain dumps, open-questions-only notes)
   - AI-agent instructions / prompt templates; personal engineering journals
 
-Distinguish "states a decision about our system" (INCLUDE) from "tracks status / describes an external system / is superseded / is process" (SKIP). The SKIP categories above are explicit \u2014 they are not "doubt." WHEN GENUINELY AMBIGUOUS: include (dropping a real spec doc costs more than keeping noise).
+Distinguish "states a decision about our system" (INCLUDE) from "tracks status / describes an external or test-data product / is superseded / is process" (SKIP). The SKIP categories above are explicit \u2014 they are not "doubt." WHEN GENUINELY AMBIGUOUS: include (dropping a real spec doc costs more than keeping noise).
 
 Output ONLY a JSON object:
 
   { "include": true|false, "reason": "short explanation" }
 
-The reason is shown to the user in the dashboard \u2014 be specific ("vendor API research (ServiceTitan)", "superseded by capacity-ml-plan-v3", "deployment runbook, no product contracts") so they can verify the call.`;
+The reason is shown to the user in the dashboard \u2014 be specific ("vendor API research (ServiceTitan)", "superseded by capacity-ml-plan-v3", "deployment runbook, no product contracts", "test-data spec for a sample product (tests/fixtures/\u2026)") so they can verify the call.`;
 function buildRelevanceUserPrompt(doc) {
   const preview = doc.preview.split("\n").slice(0, 60).join("\n");
   return [
-    `Path: ${doc.path}`,
+    `PATH (repo-relative): ${doc.path}`,
     `Detected kind: ${doc.kind}`,
     `Size: ${doc.size} bytes`,
     "",
@@ -197509,9 +197623,6 @@ async function readCache4(scope, cacheKey) {
 async function writeCache4(scope, cacheKey, verdict) {
   await setCacheEntry(scope, CACHE_NAME5, cacheKey, verdict);
 }
-async function readRelevanceCache(repoRoot, doc) {
-  return readCache4(repoRoot, computeCacheKey5(doc));
-}
 
 // packages/spec-consolidator/dist/curate.js
 async function curate(repoRoot, opts = {}) {
@@ -224308,6 +224419,9 @@ var STAGE_DEFAULTS = {
   // Authoring an executable scenario faithful to a spec claim is the hard,
   // load-bearing call (a weak scenario is false confidence) — opus.
   "guard.generate": "opus",
+  // The one evidence-retry per birth-failed claim — the same authoring task, so
+  // the same tier; a distinct stage so retry spend is attributed to the birth line.
+  "guard.retry": "opus",
   // Proposing a build/entry recipe is a modest structured task — sonnet.
   "guard.recipe": "sonnet",
   "rules.violationGen": "opus"
@@ -225009,11 +225123,11 @@ function spawnGenerateRunner2(opts = {}) {
   return async (ctx) => {
     const refs = ctx.claims.map((c) => c.ref).join(",");
     const isRetry = ctx.claims.some((c) => c.retry);
-    const suffix = `${isRetry ? ":retry" : ""}${ctx.correction ? ":correction" : ""}`;
+    const stage = isRetry ? "guard.retry" : "guard.generate";
     const raw = await transport({
-      id: `guard.generate:${ctx.doc}:${refs}${suffix}`,
-      stage: "guard.generate",
-      model: opts.model,
+      id: `${stage}:${ctx.doc}:${refs}${ctx.correction ? ":correction" : ""}`,
+      stage,
+      model: isRetry ? opts.retryModel ?? opts.model : opts.model,
       fallbackModel: opts.fallbackModel,
       system: GENERATE_SYSTEM_PROMPT,
       user: buildAuthorUserPrompt(ctx),
@@ -225325,12 +225439,15 @@ async function captureProbes(opts) {
     const cached = await getCacheEntry(opts.repoRoot, GROUND_CACHE_NAME, key4);
     if (cached) {
       const parsed = ProbeTranscriptSchema.safeParse(cached);
-      if (parsed.success)
+      if (parsed.success) {
+        opts.onProbeCaptured?.();
         return parsed.data;
+      }
     }
     const capture = await exec([...opts.resolvedEntry, ...argv], opts.recipeEnv);
     const transcript = toTranscript(argv, [...opts.displayEntry, ...argv], capture);
     await setCacheEntry(opts.repoRoot, GROUND_CACHE_NAME, key4, transcript);
+    opts.onProbeCaptured?.();
     return transcript;
   }));
 }
@@ -225595,6 +225712,7 @@ function deleteScenarioFiles(repoRoot, ids) {
 
 // packages/guard-generator/dist/generate.js
 var GENERATE_CACHE_NAME = "guard/generate";
+var ENTRY_PREFLIGHT_ANCHOR = "(entry preflight)";
 function defaultConcurrency3() {
   const env = process.env.TRUECOURSE_MAX_CONCURRENCY;
   if (env) {
@@ -225664,7 +225782,12 @@ async function generateGuards(options) {
   const limit = pLimit(Math.max(1, options.concurrency ?? defaultConcurrency3()));
   const batchSize = Math.max(1, options.batchSize ?? defaultGenerateBatch2());
   const extractRunner = options.extractRunner ?? spawnExtractRunner({ transport: options.transport, model: options.models?.extract, fallbackModel: options.models?.fallback });
-  const generateRunner = options.generateRunner ?? spawnGenerateRunner2({ transport: options.transport, model: options.models?.generate, fallbackModel: options.models?.fallback });
+  const generateRunner = options.generateRunner ?? spawnGenerateRunner2({
+    transport: options.transport,
+    model: options.models?.generate,
+    retryModel: options.models?.retry,
+    fallbackModel: options.models?.fallback
+  });
   const coverageGaps = [];
   const errors = [];
   const extractionFailures = [];
@@ -225735,11 +225858,15 @@ async function generateGuards(options) {
     return buildPromise;
   };
   let resolvedEntryMemo = null;
+  let groundPlanned = 0;
+  let groundCaptured = 0;
   const groundClaims = async (claimTexts) => {
     const probes = deriveProbes(claimTexts, recipe.entry);
     const build8 = await buildPromise;
-    if (!build8.ok)
+    if (!build8.ok || probes.length === 0)
       return [];
+    groundPlanned += probes.length;
+    options.onGroundProgress?.(groundCaptured, groundPlanned);
     resolvedEntryMemo ??= resolveEntry(repoRoot, recipe.entry);
     return captureProbes({
       repoRoot,
@@ -225747,9 +225874,21 @@ async function generateGuards(options) {
       resolvedEntry: resolvedEntryMemo,
       displayEntry: recipe.entry,
       recipeFingerprint,
-      recipeEnv: recipe.env
+      recipeEnv: recipe.env,
+      onProbeCaptured: () => options.onGroundProgress?.(++groundCaptured, groundPlanned)
     });
   };
+  let entryPreflightMemo = null;
+  const preflightEntryOnce = () => {
+    entryPreflightMemo ??= (async () => {
+      const build8 = await buildPromise;
+      if (!build8.ok)
+        return null;
+      resolvedEntryMemo ??= resolveEntry(repoRoot, recipe.entry);
+      return preflightEntry({ resolvedEntry: resolvedEntryMemo, displayEntry: recipe.entry, recipeEnv: recipe.env });
+    })();
+    return entryPreflightMemo;
+  };
   const priorSections = readPriorManifest(repoRoot);
   const manifestByKey = new Map(priorSections.map((e) => [`${e.doc}\0${e.anchor}`, e]));
   const usedIds = existingScenarioIds(repoRoot);
@@ -225773,9 +225912,11 @@ async function generateGuards(options) {
     });
     settledKeys.add(k);
     writeWorkingManifest();
+    options.onSectionSettled?.(settledKeys.size, plan.work.length);
   };
   const written = [];
   const birthFindings = [];
+  let entryPreflightFailure = null;
   let birthTotal = 0;
   let birthSettled = 0;
   let birthPassed = 0;
@@ -225822,6 +225963,20 @@ async function generateGuards(options) {
       return;
     settleChain = settleChain.then(() => settleCliSection(sectionByKey.get(k), refsBySection.get(k)));
   };
+  const deadEntry = async () => {
+    const preflight = await preflightEntryOnce();
+    if (!preflight || preflight.ok)
+      return false;
+    if (!entryPreflightFailure) {
+      entryPreflightFailure = { entry: preflight.entry, buildCommand: recipe.build, stderr: preflight.stderr };
+      errors.push({
+        doc: preflight.entry,
+        anchor: ENTRY_PREFLIGHT_ANCHOR,
+        message: formatEntryPreflightError(entryPreflightFailure)
+      });
+    }
+    return true;
+  };
   async function settleCliSection(section, refs) {
     const k = key2(section);
     for (const id of priorIdsOf(k))
@@ -225856,6 +226011,8 @@ async function generateGuards(options) {
         const message = `build failed (\`${build8.command}\`)${build8.timedOut ? " \u2014 timed out" : ""}`;
         for (const c of round1)
           localErrors.push(errorFrom({ candidate: c, result: { failure: { actual: message } } }));
+      } else if (await deadEntry()) {
+        return;
       } else {
         birthTotal += round1.length;
         const r1 = await birthValidate(repoRoot, round1, { skipBuild: true, onPhase: options.onBirthPhase, onScenarioSettled: bumpBirth });
@@ -225932,6 +226089,8 @@ async function generateGuards(options) {
   const authorTotal = authTasks.length;
   let authorDone = 0;
   const bumpAuthor = (n) => options.onAuthorProgress?.(authorDone += n, authorTotal);
+  if (authorTotal > 0)
+    options.onAuthorProgress?.(authorDone, authorTotal);
   const missTasks = [];
   for (const t of authTasks) {
     const cached = await readAuthorCache(repoRoot, t.claim, t.section, recipeFingerprint);
@@ -226003,7 +226162,8 @@ async function generateGuards(options) {
     extractionFailures,
     orphaned,
     birthPassed,
-    manifestPath: manifestPath(repoRoot)
+    manifestPath: manifestPath(repoRoot),
+    ...entryPreflightFailure ? { entryPreflight: entryPreflightFailure } : {}
   };
 }
 var key2 = (s) => `${s.doc}\0${s.anchor}`;
@@ -226814,12 +226974,14 @@ function previewChars() {
   return 60 * 50;
 }
 async function estimateScanTokens(repoRoot, prices) {
+  const decisions = readCorpusDecisions(repoRoot);
+  const manualIncludes = decisions.manualIncludes ?? [];
+  const manualExcludes = new Set(decisions.manualExcludes ?? []);
   const docs = discoverDocs(repoRoot);
-  const { toClassify } = prefilterDocs(docs);
-  const nClassify = toClassify.length;
-  const relevance = await Promise.all(toClassify.map((d) => readRelevanceCache(repoRoot, d)));
-  const relevanceMissDocs = toClassify.filter((_, i) => relevance[i] === null);
-  const cachedKeptDocs = toClassify.filter((_, i) => relevance[i]?.include === true);
+  const plan = await planRelevanceWork(repoRoot, docs, manualIncludes);
+  const nClassify = plan.toClassify.length;
+  const relevanceMissDocs = plan.needsCall;
+  const cachedKeptDocs = plan.toClassify.filter((d) => plan.known.get(d.path)?.include === true && !manualExcludes.has(d.path));
   const cachedKeptTagged = await Promise.all(cachedKeptDocs.map((d) => isAreaTagCached(repoRoot, d)));
   const cachedKeptTagMisses = cachedKeptTagged.filter((cached) => !cached).length;
   const estChangedKept = Math.round(relevanceMissDocs.length * KEEP_RATE);
@@ -231237,7 +231399,7 @@ function readToolVersion() {
   if (cachedVersion)
     return cachedVersion;
   if (true) {
-    cachedVersion = "0.7.0-next.0";
+    cachedVersion = "0.7.0-next.2";
     return cachedVersion;
   }
   try {
@@ -237598,32 +237760,20 @@ router10.delete(
     }
   }
 );
-async function mutateAndRecurate(repoPath, repoId, mutate) {
-  await mutate();
-  const tracker = createSocketSpecTracker(repoId, CURATE_STEPS.map((s) => ({ ...s })));
-  try {
-    await curateInProcess(repoPath, { tracker, source: "dashboard" });
-    emitSpecComplete(repoId, "scan");
-  } catch (e) {
-    emitSpecProgress(repoId, { step: "error", percent: 100, detail: e.message });
-    throw e;
-  }
-  return corpusPayload(repoPath);
-}
-async function mutateSpecDecision(repoPath, repoId, res, mutate) {
+async function mutateSpecDecision(repoPath, res, mutate) {
   if (!contractsMaterializeInPlace()) {
     await mutate();
     await recurateAndRegenIfResolved(repoPath);
     res.json(await corpusPayload(repoPath));
     return;
   }
-  if (!await isGitRepo(repoPath)) {
-    res.status(400).json({ error: NOT_A_GIT_REPO_MESSAGE });
-    return;
-  }
-  res.json(await mutateAndRecurate(repoPath, repoId, mutate));
+  const decisions = await mutate();
+  res.json({
+    manualIncludes: decisions.manualIncludes ?? [],
+    manualExcludes: decisions.manualExcludes ?? []
+  });
 }
-async function applySpecMutation(req, res, repoPath, repoId, mutate) {
+async function applySpecMutation(req, res, repoPath, mutate) {
   const parsed = parsePrScope(req);
   if ("error" in parsed) {
     res.status(400).json({ error: parsed.error });
@@ -237633,7 +237783,7 @@ async function applySpecMutation(req, res, repoPath, repoId, mutate) {
     await mutateSpecDecisionPr(repoPath, parsed.scope, res, mutate);
     return;
   }
-  await mutateSpecDecision(repoPath, repoId, res, () => mutate());
+  await mutateSpecDecision(repoPath, res, () => mutate());
 }
 router10.post(
   "/:id/spec/includes",
@@ -237650,7 +237800,6 @@ router10.post(
         req,
         res,
         repo.path,
-        req.params.id,
         (opts) => addManualInclude(repo.path, ref, opts)
       );
     } catch (e) {
@@ -237673,7 +237822,6 @@ router10.delete(
         req,
         res,
         repo.path,
-        req.params.id,
         (opts) => removeManualInclude(repo.path, ref, opts)
       );
     } catch (e) {
@@ -237696,7 +237844,6 @@ router10.post(
         req,
         res,
         repo.path,
-        req.params.id,
         (opts) => addManualExclude(repo.path, ref, opts)
       );
     } catch (e) {
@@ -237719,7 +237866,6 @@ router10.delete(
         req,
         res,
         repo.path,
-        req.params.id,
         (opts) => removeManualExclude(repo.path, ref, opts)
       );
     } catch (e) {
@@ -237741,6 +237887,8 @@ router10.get(
         res.json({
           contractsStale: false,
           verifyStale: false,
+          // EE re-curates on every decision, so decisions never outrun the corpus.
+          decisionsPending: false,
           hasCorpus: corpus !== null,
           hasGenerated: contractFiles.length > 0,
           hasVerified: verify2 !== null
@@ -237755,6 +237903,7 @@ router10.get(
       res.json({
         contractsStale,
         verifyStale,
+        decisionsPending: hasPendingDecisions(repo.path),
         hasCorpus: corpusMtime !== null,
         hasGenerated: generatedMtime !== null,
         hasVerified: verifiedMtime !== null
@@ -237771,6 +237920,18 @@ function mtimeIfExists(file) {
     return null;
   }
 }
+function hasPendingDecisions(repoPath) {
+  const decisionsMtime = mtimeIfExists(decisionsPath(repoPath));
+  if (decisionsMtime === null) return false;
+  try {
+    const corpus = JSON.parse(fs62.readFileSync(corpusFilePath(repoPath), "utf8"));
+    const generatedAt = Date.parse(corpus.generatedAt ?? "");
+    if (Number.isNaN(generatedAt)) return false;
+    return decisionsMtime > generatedAt;
+  } catch {
+    return false;
+  }
+}
 var spec_default = router10;
 
 // apps/dashboard/server/src/routes/contracts.ts
@@ -238862,7 +239023,8 @@ var GUARD_GENERATE_STEPS = [
 var GUARD_STEP_STAGES = {
   index: ["guard.recipe"],
   extract: ["guard.extract"],
-  author: ["guard.generate"]
+  author: ["guard.generate"],
+  validate: ["guard.retry"]
 };
 async function estimateGuard(repoRoot) {
   return estimateGuardTokens(repoRoot, await getModelPrices());
@@ -238871,6 +239033,7 @@ function resolveGuardModels(repoRoot) {
   return {
     extract: resolveModel("guard.extract", void 0, repoRoot),
     generate: resolveModel("guard.generate", void 0, repoRoot),
+    retry: resolveModel("guard.retry", void 0, repoRoot),
     recipe: resolveModel("guard.recipe", void 0, repoRoot),
     fallback: resolveFallbackModel(repoRoot) ?? void 0
   };
@@ -238912,10 +239075,20 @@ async function guardGenerateInProcess(repoRoot, options = {}) {
     cur = ni;
   };
   const withUsage = (key4, base) => `${base}${stageUsageTag(GUARD_STEP_STAGES[key4] ?? [], repoRoot)}`;
+  let authorDone = 0;
+  let authorTotal = 0;
+  let authorFinished = false;
+  let groundCaptured = 0;
+  let groundPlanned = 0;
+  const authorDetail = () => {
+    const claims = `${authorDone}/${authorTotal} claim${authorTotal === 1 ? "" : "s"}`;
+    const base = groundPlanned > 0 ? `grounding probes ${groundCaptured}/${groundPlanned} \xB7 authoring ${claims}` : claims;
+    return withUsage("author", base);
+  };
   let building = false;
-  let birthSeen = false;
   let birthDone = 0;
-  let birthTotal = 0;
+  let sectionsDone = 0;
+  let sectionsTotal = 0;
   let retrySeen = false;
   let retryDone = 0;
   let retryTotal = 0;
@@ -238926,10 +239099,10 @@ async function guardGenerateInProcess(repoRoot, options = {}) {
       tracker?.start("validate");
       validateStarted = true;
     }
-    const parts = [building ? "building\u2026" : `birth ${birthDone}/${birthTotal}`];
+    const parts = [`sections ${sectionsDone}/${sectionsTotal}`, building ? "building\u2026" : `birth ${birthDone}`];
     if (retrySeen)
-      parts.push(`retrying failed claims ${retryDone}/${retryTotal}`);
-    tracker?.detail("validate", parts.join(" \xB7 "));
+      parts.push(`retrying ${retryDone}/${retryTotal}`);
+    tracker?.detail("validate", withUsage("validate", parts.join(" \xB7 ")));
   };
   tracker?.start("index");
   try {
@@ -238941,6 +239114,7 @@ async function guardGenerateInProcess(repoRoot, options = {}) {
       generateRunner: options.generateRunner,
       recipeRunner: options.recipeRunner,
       onPlan: (total, work) => {
+        sectionsTotal = work;
         tracker?.done("index", withUsage("index", `${work} of ${total} section${total === 1 ? "" : "s"} changed`));
         cur = STEPS.indexOf("extract");
         tracker?.start("extract", `0 views`);
@@ -238957,27 +239131,30 @@ async function guardGenerateInProcess(repoRoot, options = {}) {
       },
       onAuthorProgress: (done, total) => {
         advanceTo("author");
-        const detail = withUsage("author", `${done}/${total} claim${total === 1 ? "" : "s"}`);
-        if (done >= total)
-          tracker?.done("author", detail);
-        else
-          tracker?.detail("author", detail);
-      },
-      onBirthPhase: (phase, total) => {
-        if (phase === "build") {
-          building = true;
+        authorDone = done;
+        authorTotal = total;
+        if (done >= total) {
+          authorFinished = true;
+          tracker?.done("author", withUsage("author", `${done}/${total} claim${total === 1 ? "" : "s"}`));
         } else {
-          building = false;
-          if (!birthSeen && total !== void 0)
-            birthTotal = total;
+          tracker?.detail("author", authorDetail());
         }
+      },
+      onGroundProgress: (captured, planned) => {
+        groundCaptured = captured;
+        groundPlanned = planned;
+        if (authorFinished)
+          return;
+        advanceTo("author");
+        tracker?.detail("author", authorDetail());
+      },
+      onBirthPhase: (phase) => {
+        building = phase === "build";
         renderValidate();
       },
-      onBirthProgress: (done, total) => {
+      onBirthProgress: (done) => {
         building = false;
-        birthSeen = true;
         birthDone = done;
-        birthTotal = total;
         renderValidate();
       },
       onRetryProgress: (done, total) => {
@@ -238985,6 +239162,12 @@ async function guardGenerateInProcess(repoRoot, options = {}) {
         retryDone = done;
         retryTotal = total;
         renderValidate();
+      },
+      onSectionSettled: (settled, total) => {
+        sectionsDone = settled;
+        sectionsTotal = total;
+        if (validateStarted)
+          renderValidate();
       }
     });
     for (let i = cur; i < STEPS.length; i++)
@@ -239008,7 +239191,7 @@ async function guardGenerateInProcess(repoRoot, options = {}) {
     }
   }
 }
-var GUARD_USAGE_STAGES = ["guard.recipe", "guard.extract", "guard.generate"];
+var GUARD_USAGE_STAGES = ["guard.recipe", "guard.extract", "guard.generate", "guard.retry"];
 function sumGuardUsage() {
   const usage = getStageUsage();
   let calls = 0;
@@ -239056,6 +239239,8 @@ async function guardRunInProcess(repoRoot, options = {}) {
     tracker?.done("run", `${n} scenario${n === 1 ? "" : "s"}`);
   } else if (result.status === "build-failed") {
     tracker?.error("build", `Build failed (\`${result.build.command}\`)${result.build.timedOut ? " \u2014 timed out" : ""}`);
+  } else if (result.status === "entry-preflight-failed") {
+    tracker?.error("build", `Entry failed to start: \`${result.preflight.entry}\` (rebuild via \`${result.buildCommand}\`)`);
   }
   return result;
 }
@@ -239136,7 +239321,9 @@ router14.post("/:id/guard/run", async (req, res, next) => {
       res.json({ status: "ok", summary: result.latest.summary });
       return;
     }
-    if (result.status !== "build-failed") emitSpecComplete(repoId, "guard-run");
+    if (result.status !== "build-failed" && result.status !== "entry-preflight-failed") {
+      emitSpecComplete(repoId, "guard-run");
+    }
     res.json({ status: result.status, message: runFailureMessage(result) });
   } catch (e) {
     emitSpecProgress(repoId, { step: "error", percent: 100, detail: e.message });
@@ -239155,6 +239342,12 @@ function runFailureMessage(result) {
       return "No scenarios found under .truecourse/scenarios/. Generate scenarios first.";
     case "build-failed":
       return `Build failed (\`${result.build.command}\`)${result.build.timedOut ? " \u2014 timed out" : ""}. No scenarios ran.`;
+    case "entry-preflight-failed":
+      return formatEntryPreflightError({
+        entry: result.preflight.entry,
+        buildCommand: result.buildCommand,
+        stderr: result.preflight.stderr
+      });
   }
 }
 var guard_actions_default = router14;