truecourse 0.7.0-next.1 → 0.7.0-next.2

package/cli.mjs

@@ -105218,7 +105218,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";
@@ -105271,6 +105271,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()
@@ -105316,7 +105324,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();
   }
 });
@@ -170270,7 +170284,7 @@ function readToolVersion() {
   if (cachedVersion)
     return cachedVersion;
   if (true) {
-    cachedVersion = "0.7.0-next.1";
+    cachedVersion = "0.7.0-next.2";
     return cachedVersion;
   }
   try {
@@ -197480,35 +197494,49 @@ function prefilterDocs(docs, manualIncludes = []) {
     skipped: [...reasons].map(([path79, reason]) => ({ path: path79, reason }))
   };
 }
+async function planRelevanceWork(repoRoot5, 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(repoRoot5, computeCacheKey5(doc));
+    if (cached)
+      known.set(doc.path, cached);
+    else
+      needsCall.push(doc);
+  }));
+  return { toClassify, prefilterSkipped: skipped, needsCall, known };
+}
 async function filterByRelevance(repoRoot5, docs, opts = {}) {
   if (opts.enabled === false || docs.length === 0) {
     return { included: docs, skipped: [] };
   }
-  const manualSet = new Set(opts.manualIncludes ?? []);
   const runner = 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(repoRoot5, 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 active11 = 0;
   await new Promise((resolve12) => {
+    if (pending.length === 0)
+      return resolve12();
     const launch = () => {
-      while (active11 < 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 && active11 === 0)
-            resolve12();
-          continue;
-        }
+      while (active11 < concurrency && cursor < pending.length) {
+        const doc = pending[cursor++];
         active11++;
         classifyOne(repoRoot5, doc, runner).then((verdict) => {
           verdicts.set(doc.path, verdict);
@@ -197521,14 +197549,12 @@ async function filterByRelevance(repoRoot5, docs, opts = {}) {
         }).finally(() => {
           markDone();
           active11--;
-          if (cursor >= toClassify.length && active11 === 0)
+          if (cursor >= pending.length && active11 === 0)
             resolve12();
           else
             launch();
         });
       }
-      if (cursor >= toClassify.length && active11 === 0)
-        resolve12();
     };
     launch();
   });
@@ -197725,9 +197751,6 @@ async function readCache4(scope, cacheKey) {
 async function writeCache4(scope, cacheKey, verdict) {
   await setCacheEntry(scope, CACHE_NAME5, cacheKey, verdict);
 }
-async function readRelevanceCache(repoRoot5, doc) {
-  return readCache4(repoRoot5, computeCacheKey5(doc));
-}
 
 // packages/spec-consolidator/dist/curate.js
 async function curate(repoRoot5, opts = {}) {
@@ -201835,6 +201858,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"
@@ -205125,6 +205151,129 @@ function listSandboxFiles(dir) {
   return out.sort();
 }
 
+// packages/guard-runner/dist/executor.js
+import { spawn as spawn9 } 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((resolve12) => {
+    const child = spawn9(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);
+      resolve12(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 exec3 = 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 exec3([...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((p2) => startedCleanly(p2.capture)))
+    return true;
+  const shapes = probes.map((p2) => failureShape(p2.capture));
+  return shapes.some((s) => s !== shapes[0]);
+}
+function startedCleanly(c2) {
+  return !c2.spawnError && !c2.timedOut && c2.signal === null && c2.exitCode === 0;
+}
+function failureShape(c2) {
+  return JSON.stringify({
+    spawnError: c2.spawnError ?? null,
+    signal: c2.signal ?? null,
+    timedOut: c2.timedOut,
+    exitCode: c2.exitCode,
+    stdout: c2.stdout,
+    stderr: c2.stderr
+  });
+}
+function startupOutput(c2, timeoutMs) {
+  const parts = [];
+  const primary = c2.stderr || c2.stdout;
+  if (primary)
+    parts.push(primary.trimEnd());
+  if (c2.spawnError)
+    parts.push(`failed to spawn: ${c2.spawnError}`);
+  if (c2.timedOut)
+    parts.push(`(the entry produced no output within ${timeoutMs}ms and was killed)`);
+  if (parts.length === 0) {
+    parts.push(c2.exitCode !== null ? `(the entry exited ${c2.exitCode} with no output)` : `(the entry was killed by ${c2.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 as spawnSync2 } from "node:child_process";
 import fs51 from "node:fs";
@@ -205205,67 +205354,6 @@ function applyCapabilities(setup, ctx) {
   }
 }
 
-// packages/guard-runner/dist/executor.js
-import { spawn as spawn9 } 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((resolve12) => {
-    const child = spawn9(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);
-      resolve12(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",
@@ -205896,16 +205984,27 @@ async function runGuard(opts) {
   }));
   const executable = planned.filter((p2) => p2.resolution.kind === "match" || p2.resolution.kind === "remap");
   const nonExecutable = planned.filter((p2) => p2.resolution.kind === "stale" || p2.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(repoRoot5, loaded.recipe.build, loaded.recipe.env);
     if (!build8.ok)
       return { status: "build-failed", build: build8, loadErrors };
   }
+  const resolvedEntry = resolveEntry(repoRoot5, 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(repoRoot5, loaded.recipe.entry);
   const stepTimeoutMs = opts.stepTimeoutMs ?? DEFAULT_STEP_TIMEOUT_MS;
   const concurrency = opts.concurrency ?? defaultRunConcurrency();
   const results = [];
@@ -206450,11 +206549,11 @@ function spawnGenerateRunner2(opts = {}) {
   return async (ctx) => {
     const refs = ctx.claims.map((c2) => c2.ref).join(",");
     const isRetry = ctx.claims.some((c2) => c2.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),
@@ -206766,12 +206865,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 exec3([...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;
   }));
 }
@@ -207036,6 +207138,7 @@ function deleteScenarioFiles(repoRoot5, 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) {
@@ -207105,7 +207208,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 = [];
@@ -207176,11 +207284,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(repoRoot5, recipe.entry);
     return captureProbes({
       repoRoot: repoRoot5,
@@ -207188,9 +207300,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(repoRoot5, recipe.entry);
+      return preflightEntry({ resolvedEntry: resolvedEntryMemo, displayEntry: recipe.entry, recipeEnv: recipe.env });
+    })();
+    return entryPreflightMemo;
+  };
   const priorSections = readPriorManifest(repoRoot5);
   const manifestByKey = new Map(priorSections.map((e) => [`${e.doc}\0${e.anchor}`, e]));
   const usedIds = existingScenarioIds(repoRoot5);
@@ -207214,9 +207338,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;
@@ -207263,6 +207389,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))
@@ -207297,6 +207437,8 @@ async function generateGuards(options) {
         const message = `build failed (\`${build8.command}\`)${build8.timedOut ? " \u2014 timed out" : ""}`;
         for (const c2 of round1)
           localErrors.push(errorFrom({ candidate: c2, result: { failure: { actual: message } } }));
+      } else if (await deadEntry()) {
+        return;
       } else {
         birthTotal += round1.length;
         const r1 = await birthValidate(repoRoot5, round1, { skipBuild: true, onPhase: options.onBirthPhase, onScenarioSettled: bumpBirth });
@@ -207373,6 +207515,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 t2 of authTasks) {
     const cached = await readAuthorCache(repoRoot5, t2.claim, t2.section, recipeFingerprint);
@@ -207444,7 +207588,8 @@ async function generateGuards(options) {
     extractionFailures,
     orphaned,
     birthPassed,
-    manifestPath: manifestPath2(repoRoot5)
+    manifestPath: manifestPath2(repoRoot5),
+    ...entryPreflightFailure ? { entryPreflight: entryPreflightFailure } : {}
   };
 }
 var key2 = (s) => `${s.doc}\0${s.anchor}`;
@@ -207833,12 +207978,14 @@ function previewChars() {
   return 60 * 50;
 }
 async function estimateScanTokens(repoRoot5, prices) {
+  const decisions = readCorpusDecisions(repoRoot5);
+  const manualIncludes = decisions.manualIncludes ?? [];
+  const manualExcludes = new Set(decisions.manualExcludes ?? []);
   const docs = discoverDocs(repoRoot5);
-  const { toClassify } = prefilterDocs(docs);
-  const nClassify = toClassify.length;
-  const relevance = await Promise.all(toClassify.map((d3) => readRelevanceCache(repoRoot5, d3)));
-  const relevanceMissDocs = toClassify.filter((_2, i) => relevance[i] === null);
-  const cachedKeptDocs = toClassify.filter((_2, i) => relevance[i]?.include === true);
+  const plan = await planRelevanceWork(repoRoot5, docs, manualIncludes);
+  const nClassify = plan.toClassify.length;
+  const relevanceMissDocs = plan.needsCall;
+  const cachedKeptDocs = plan.toClassify.filter((d3) => plan.known.get(d3.path)?.include === true && !manualExcludes.has(d3.path));
   const cachedKeptTagged = await Promise.all(cachedKeptDocs.map((d3) => isAreaTagCached(repoRoot5, d3)));
   const cachedKeptTagMisses = cachedKeptTagged.filter((cached) => !cached).length;
   const estChangedKept = Math.round(relevanceMissDocs.length * KEEP_RATE);
@@ -210240,12 +210387,14 @@ var GUARD_GENERATE_STEPS = [
 var GUARD_STEP_STAGES = {
   index: ["guard.recipe"],
   extract: ["guard.extract"],
-  author: ["guard.generate"]
+  author: ["guard.generate"],
+  validate: ["guard.retry"]
 };
 function resolveGuardModels(repoRoot5) {
   return {
     extract: resolveModel("guard.extract", void 0, repoRoot5),
     generate: resolveModel("guard.generate", void 0, repoRoot5),
+    retry: resolveModel("guard.retry", void 0, repoRoot5),
     recipe: resolveModel("guard.recipe", void 0, repoRoot5),
     fallback: resolveFallbackModel(repoRoot5) ?? void 0
   };
@@ -210287,10 +210436,20 @@ async function guardGenerateInProcess(repoRoot5, options = {}) {
     cur = ni;
   };
   const withUsage = (key4, base2) => `${base2}${stageUsageTag(GUARD_STEP_STAGES[key4] ?? [], repoRoot5)}`;
+  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 base2 = groundPlanned > 0 ? `grounding probes ${groundCaptured}/${groundPlanned} \xB7 authoring ${claims}` : claims;
+    return withUsage("author", base2);
+  };
   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;
@@ -210301,10 +210460,10 @@ async function guardGenerateInProcess(repoRoot5, 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 {
@@ -210316,6 +210475,7 @@ async function guardGenerateInProcess(repoRoot5, 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`);
@@ -210332,27 +210492,30 @@ async function guardGenerateInProcess(repoRoot5, 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) => {
@@ -210360,6 +210523,12 @@ async function guardGenerateInProcess(repoRoot5, options = {}) {
         retryDone = done;
         retryTotal = total;
         renderValidate();
+      },
+      onSectionSettled: (settled, total) => {
+        sectionsDone = settled;
+        sectionsTotal = total;
+        if (validateStarted)
+          renderValidate();
       }
     });
     for (let i = cur; i < STEPS.length; i++)
@@ -210383,7 +210552,7 @@ async function guardGenerateInProcess(repoRoot5, 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;
@@ -210431,6 +210600,8 @@ async function guardRunInProcess(repoRoot5, 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;
 }
@@ -210494,6 +210665,15 @@ async function runGuardRun(opts = {}) {
       process.exit(1);
       return;
     }
+    case "entry-preflight-failed": {
+      O2.error(`The recipe entry \`${result.preflight.entry}\` failed to start \u2014 every scenario would fail identically.`);
+      for (const line of result.preflight.stderr.trimEnd().split("\n")) console.log(`  ${line}`);
+      O2.step(`Rebuild it with \`${result.buildCommand}\` (its build output is likely stale or incomplete), then re-run \`truecourse guard run\`.`);
+      printLoadErrors(result.loadErrors);
+      gt("Aborted \u2014 the entry could not start; no scenarios ran.");
+      process.exit(1);
+      return;
+    }
     case "ok":
       break;
   }
@@ -210576,6 +210756,13 @@ async function runGuardGenerate(opts = {}) {
     gt("Add or fix `.truecourse/scenarios/recipe.json` and retry.");
     process.exit(1);
   }
+  if (guard.entryPreflight) {
+    O2.error(`The recipe entry \`${guard.entryPreflight.entry}\` failed to start \u2014 every scenario would fail identically, so nothing was validated.`);
+    for (const line of guard.entryPreflight.stderr.trimEnd().split("\n")) console.log(`  ${line}`);
+    O2.step(`Rebuild it with \`${guard.entryPreflight.buildCommand}\` (its build output is likely stale or incomplete), then re-run \`truecourse guard generate\`.`);
+    gt("Aborted \u2014 the entry could not start; no scenarios were validated.");
+    process.exit(1);
+  }
   if (guard.recipe?.status === "discovered") {
     O2.step(`recipe      wrote ${guard.recipe.wrotePath} \u2014 review and commit it`);
   }
@@ -210799,6 +210986,7 @@ var STAGE_LABEL = {
   "contract.gapJudge": "Contract \xB7 gap judge",
   "guard.extract": "Guard  \xB7 claim extract",
   "guard.generate": "Guard  \xB7 scenario gen",
+  "guard.retry": "Guard  \xB7 scenario retry",
   "guard.recipe": "Guard  \xB7 recipe discover",
   "rules.violationGen": "Rules  \xB7 violation gen"
 };
@@ -211107,7 +211295,7 @@ async function runHooksRun() {
 
 // tools/cli/src/index.ts
 var program2 = new Command();
-program2.name("truecourse").version("0.7.0-next.1").description("TrueCourse CLI \u2014 analyze your repository and open the dashboard");
+program2.name("truecourse").version("0.7.0-next.2").description("TrueCourse CLI \u2014 analyze your repository and open the dashboard");
 var dashboardCmd = program2.command("dashboard").description("Start the TrueCourse dashboard and open it in your browser").option("--reconfigure", "Re-prompt for console vs background service mode").option("--service", "Run as a background service (skips mode prompt)").option("--console", "Run in this terminal (skips mode prompt)").action(async (options) => {
   if (options.service && options.console) {
     console.error("error: --service and --console are mutually exclusive");