codecartographer-pi 0.18.0 → 0.19.1

package/dist/core/broadside.js

@@ -31,11 +31,12 @@
 // executable surfaces (Pi and MCP), not the pure template. What the template does
 // carry is the reading guide for its output — `.codecarto/broadside/SKILL.md`,
 // served by codecarto_skill under the name `broadside` (see readBroadsideSkill).
-import { mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
+import { mkdir, readFile, readdir, rename, stat, writeFile } from "node:fs/promises";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
-import { join } from "node:path";
+import { join, relative } from "node:path";
 import { pathExists, sleep } from "./utils.js";
+import { acquireLock } from "./status.js";
 import { loadYamlFile } from "./yaml.js";
 import { packagedWorkspaceDir } from "./workspace.js";
 const execFileAsync = promisify(execFile);
@@ -49,8 +50,14 @@ export const BROADSIDE_STATE_FILE = "state.json";
 export const BROADSIDE_CONFIG_FILE = "config.yaml";
 export const BROADSIDE_STATE_SCHEMA_VERSION = 1;
 // Per-token pricing in USD (OpenRouter, google/gemini-3.7-flash:batch).
-export const BROADSIDE_INPUT_PRICE_PER_M = 0.1875;
-export const BROADSIDE_OUTPUT_PRICE_PER_M = 0.9375;
+// OpenRouter's listed rates for the `:batch` variant, which already carry the
+// batch discount — the sync model is $0.75/$3.75. These were half these values
+// until a live run compared them against the catalog: the batch discount had
+// been applied a second time by hand, so every estimate for the default model
+// came out at half its true cost and `max_cost` bound at twice what the user
+// asked for. They are the offline fallback only; the live catalog wins.
+export const BROADSIDE_INPUT_PRICE_PER_M = 0.375;
+export const BROADSIDE_OUTPUT_PRICE_PER_M = 1.875;
 // OpenRouter's public model catalog; pricing, context, and capabilities live
 // per model id. The benchmarks endpoint adds coding/intelligence indices.
 export const BROADSIDE_MODELS_URL = "https://openrouter.ai/api/v1/models";
@@ -848,7 +855,10 @@ async function walkFiles(rootDir, dir, depth, remaining) {
             out = out.concat(children);
         }
         else if (entry.isFile()) {
-            const rel = join(dir, entry.name).slice(rootDir.length + 1).split("\\").join("/");
+            // relative() rather than slice(rootDir.length + 1): the hand-rolled
+            // slice cut one character too many whenever rootDir carried a trailing
+            // separator, and mangled every path outright when rootDir was "/".
+            const rel = relative(rootDir, join(dir, entry.name)).split("\\").join("/");
             out.push(rel);
         }
     }
@@ -1142,9 +1152,30 @@ export function buildBatchRequest(lens, info, slice, index, sliceCount, model =
         },
     };
 }
-export function estimateCost(lens, slices, pricing, maxTokensOverride) {
-    const inputTokens = Math.ceil(slices.reduce((sum, s) => sum + (lens.maxChars === 0 ? 6000 : s.chars), 0) / 4);
-    const outputTokens = Math.ceil((maxTokensOverride ?? lens.maxTokens) * 0.75);
+/**
+ * Pre-flight cost estimate for one lens.
+ *
+ * Every slice is its own batch request, so both halves scale with the slice
+ * count. The output half used to be a single `maxTokens * 0.75` for the whole
+ * lens no matter how many requests it sent — on a repository that sliced into
+ * 13 modules that budgeted one request's output and shipped thirteen, and a
+ * live run came in at roughly 3x its estimate. Since this number is what
+ * `max_cost` binds against, under-counting it lets a run outspend the cap the
+ * user set.
+ *
+ * @param info - Repo info, when the caller has it: lets the estimate include
+ *   the system prompt and JSON schema each request carries. Omitted, the
+ *   estimate covers slice content only, which is what the old signature did.
+ */
+export function estimateCost(lens, slices, pricing, maxTokensOverride, info) {
+    const sliceChars = slices.reduce((sum, s) => sum + (lens.maxChars === 0 ? 6000 : s.chars), 0);
+    // The system prompt and the response schema ride on every request, so they
+    // are paid once per slice rather than once per lens.
+    const perRequestOverhead = info
+        ? (lens.systemPrompt(info)?.length ?? 0) + JSON.stringify(SCHEMAS[lens.schemaName] ?? {}).length
+        : 0;
+    const inputTokens = Math.ceil((sliceChars + perRequestOverhead * slices.length) / 4);
+    const outputTokens = slices.length * Math.ceil((maxTokensOverride ?? lens.maxTokens) * 0.75);
     const cost = (inputTokens / 1_000_000) * pricing.inputPerM +
         (outputTokens / 1_000_000) * pricing.outputPerM;
     return { inputTokens, outputTokens, cost };
@@ -1195,9 +1226,76 @@ export async function loadBroadsideState(broadsideDir) {
         return defaultBroadsideState();
     }
 }
+/**
+ * Overwrite `state.json` wholesale with `state`.
+ *
+ * Prefer {@link persistBroadsideRun} anywhere a live operation is recording its
+ * own progress — this entry point replaces the file, so any run a concurrent
+ * process recorded in the meantime is erased. It remains the right call for
+ * seeding a fresh workspace and for test fixtures, where "make the file exactly
+ * this" is the intent.
+ */
 export async function saveBroadsideState(broadsideDir, state) {
     await mkdir(broadsideDir, { recursive: true });
-    await writeFile(join(broadsideDir, BROADSIDE_STATE_FILE), `${JSON.stringify(state, null, "\t")}\n`, "utf8");
+    const statePath = join(broadsideDir, BROADSIDE_STATE_FILE);
+    const lock = await acquireLock(`${statePath}.lock`);
+    try {
+        await writeBroadsideStateFile(statePath, state);
+    }
+    finally {
+        await lock.release();
+    }
+}
+/** Serialize through a temp file so a crash mid-write cannot truncate state.json. */
+async function writeBroadsideStateFile(statePath, state) {
+    const tempPath = `${statePath}.${process.pid}.${Date.now()}.tmp`;
+    await writeFile(tempPath, `${JSON.stringify(state, null, "\t")}\n`, "utf8");
+    await rename(tempPath, statePath);
+}
+/**
+ * Read-modify-write `state.json` under a lock.
+ *
+ * The lock is held only for the read-modify-write, never for the surrounding
+ * operation: a `collect` can poll for the better part of an hour, and holding
+ * the lock across that would push every concurrent caller past the 5s lock
+ * timeout.
+ */
+export async function updateBroadsideStateAtomically(broadsideDir, mutate) {
+    await mkdir(broadsideDir, { recursive: true });
+    const statePath = join(broadsideDir, BROADSIDE_STATE_FILE);
+    const lock = await acquireLock(`${statePath}.lock`);
+    try {
+        const state = await loadBroadsideState(broadsideDir);
+        await mutate(state);
+        await writeBroadsideStateFile(statePath, state);
+        return state;
+    }
+    finally {
+        await lock.release();
+    }
+}
+/**
+ * Record one run's current shape, merged into whatever is on disk *now*.
+ *
+ * Broad-Side operations are long-lived and hold their state in memory while
+ * they poll. Writing that snapshot back wholesale silently erased any run a
+ * concurrent operation had recorded since it was loaded, orphaning that run's
+ * paid results on disk — present as files, invisible to `list`, and unreachable
+ * by `collect`, which finds its run by position in `state.runs`. Observed live:
+ * a submit at 23:35 was erased by a collect that had loaded state before it and
+ * wrote back at 00:08.
+ *
+ * Merging by run id also self-heals: a run erased by an older writer is
+ * restored the next time its own operation checkpoints.
+ */
+export async function persistBroadsideRun(broadsideDir, run) {
+    return updateBroadsideStateAtomically(broadsideDir, (state) => {
+        const index = state.runs.findIndex((candidate) => candidate.id === run.id);
+        if (index === -1)
+            state.runs.push(run);
+        else
+            state.runs[index] = run;
+    });
 }
 export async function loadBroadsideConfig(broadsideDir) {
     const configPath = join(broadsideDir, BROADSIDE_CONFIG_FILE);
@@ -1332,10 +1430,11 @@ export async function resolveCatalogEntry(broadsideDir, config, model, apiKey, f
             },
         };
     }
-    const builtIn = builtInCatalogEntry(model);
-    if (builtIn)
-        return { model, source: "built-in", entry: builtIn };
-    // Unknown model: on-disk cache first, then the live catalog.
+    // On-disk cache first, then the live catalog — for the default model too.
+    // Hardcoded rates used to short-circuit here, which meant a stale constant
+    // could never self-correct even though the catalog was already being
+    // fetched for every other model. The authoritative source wins; the
+    // constants below are what we fall back to when the network is unavailable.
     const cache = await readCatalogCache(broadsideDir);
     const cached = cache?.models[model];
     if (cached && Date.now() - new Date(cache.fetched_at).getTime() < BROADSIDE_CATALOG_CACHE_TTL_MS) {
@@ -1366,6 +1465,11 @@ export async function resolveCatalogEntry(broadsideDir, config, model, apiKey, f
         await writeCatalogCache(broadsideDir, updated);
         return { model, source: "live", entry: live };
     }
+    // Offline fallback: the default model's rates and capabilities are known at
+    // compile time, so a network failure does not have to stop a run.
+    const builtIn = builtInCatalogEntry(model);
+    if (builtIn)
+        return { model, source: "built-in", entry: builtIn };
     throw new Error(`Could not resolve per-token pricing for batch model "${model}". ` +
         "Set pricing.input_per_m and pricing.output_per_m in .codecarto/broadside/config.yaml " +
         "(USD per million tokens), or check the model id against https://openrouter.ai/models?variant=batch.");
@@ -1469,6 +1573,14 @@ export async function fetchBatch(batchId, apiKey, fetcher = fetch) {
     data.http_status = resp.status;
     return data;
 }
+/**
+ * Batch statuses that will never produce a result.
+ *
+ * Deliberately excludes the synthetic `timeout` this module returns when a poll
+ * budget expires: that batch is still running server-side and has already been
+ * charged, so callers must come back for it rather than retire it.
+ */
+export const BROADSIDE_DEAD_BATCH_STATUSES = ["failed", "expired", "cancelled", "auth-failed"];
 export async function pollBatchUntilTerminal(batchId, apiKey, opts = {}) {
     const deadline = Date.now() + (opts.deadlineMs ?? BROADSIDE_DEFAULT_POLL_BUDGET_MS);
     const intervalMs = opts.pollIntervalMs ?? BROADSIDE_POLL_INTERVAL_MS;
@@ -1491,7 +1603,7 @@ export async function pollBatchUntilTerminal(batchId, apiKey, opts = {}) {
         const status = String(batch.status ?? "unknown");
         const counts = (batch.request_counts ?? {});
         opts.onStatus?.(status, counts);
-        if (["completed", "failed", "expired", "cancelled", "auth-failed"].includes(status))
+        if (status === "completed" || BROADSIDE_DEAD_BATCH_STATUSES.includes(status))
             return batch;
         if (Date.now() >= deadline)
             return { id: batchId, status: "timeout" };
@@ -1563,14 +1675,30 @@ export async function runBroadsideSubmit(cwd, apiKey, opts = {}) {
     const sourceDirty = await gitDirty(cwd);
     let baseHead = null;
     let changed = null;
+    const incrementalOutcome = {
+        requested: opts.incremental === true,
+        applied: false,
+        baseHead: null,
+    };
     if (opts.incremental) {
         const state = await loadBroadsideState(broadsideDir);
         // The baseline is the most recent run that recorded a HEAD — a
         // submit-only run (never collected) is still a valid committed base.
         const previous = [...state.runs].reverse().find((r) => r.sourceHead);
-        if (previous?.sourceHead && !sourceDirty) {
+        if (sourceDirty) {
+            incrementalOutcome.reason = "dirty-worktree";
+        }
+        else if (!previous?.sourceHead) {
+            incrementalOutcome.reason = "no-baseline";
+        }
+        else {
             baseHead = previous.sourceHead;
             changed = await changedFilesSince(cwd, baseHead);
+            incrementalOutcome.baseHead = baseHead;
+            if (changed)
+                incrementalOutcome.applied = true;
+            else
+                incrementalOutcome.reason = "diff-failed";
         }
     }
     // Slice offline first so the estimate covers every request we would send.
@@ -1591,7 +1719,7 @@ export async function runBroadsideSubmit(cwd, apiKey, opts = {}) {
         const lensModel = modelForLens(lensId);
         const { pricing: lensPricing, outputCap: lensOutputCap } = resolved.get(lensModel);
         const maxTokens = lensOutputCap ? Math.min(lens.maxTokens, lensOutputCap) : lens.maxTokens;
-        const estimate = estimateCost(lens, slices, lensPricing, maxTokens);
+        const estimate = estimateCost(lens, slices, lensPricing, maxTokens, info);
         estimatedInputTokens += estimate.inputTokens;
         estimatedOutputTokens += estimate.outputTokens;
         estimatedTotalCost += estimate.cost;
@@ -1626,6 +1754,7 @@ export async function runBroadsideSubmit(cwd, apiKey, opts = {}) {
             exceedsLimit,
             baseHead,
             sourceDirty,
+            incremental: incrementalOutcome,
             ...(outputCap !== undefined && { outputCap }),
         });
         if (!approved)
@@ -1659,7 +1788,7 @@ export async function runBroadsideSubmit(cwd, apiKey, opts = {}) {
         baseHead,
     };
     state.runs.push(run);
-    await saveBroadsideState(broadsideDir, state);
+    await persistBroadsideRun(broadsideDir, run);
     const requestsByCustomId = {};
     const submissions = [];
     // Submit from the estimate rather than recomputing: the user approved that
@@ -1707,7 +1836,7 @@ export async function runBroadsideSubmit(cwd, apiKey, opts = {}) {
         })());
     }
     await Promise.allSettled(submissions);
-    await saveBroadsideState(broadsideDir, state);
+    await persistBroadsideRun(broadsideDir, run);
     // Persist the exact request bodies so collect can re-submit a truncated
     // slice (bumped output cap) without re-walking the repo (#133). The run
     // dir is created here rather than waiting for collect so a crash between
@@ -1734,6 +1863,7 @@ export async function runBroadsideSubmit(cwd, apiKey, opts = {}) {
                 : resolved.get(model).supportsStructuredOutputs,
             expirationDate: defaultEntry.expirationDate ?? null,
         },
+        incremental: incrementalOutcome,
     };
 }
 function extractContent(result) {
@@ -1799,6 +1929,46 @@ export async function saveLensResults(runDir, lensId, batch) {
     }
     return out;
 }
+/**
+ * Rebuild lens results from what a previous collect already wrote to disk.
+ *
+ * The post-passes are gated on having lens findings in hand, and a collect
+ * only holds the ones *it* polled. When an earlier collect saved every lens
+ * and then died before synthesis and triage ran — the batch window is long
+ * and a poll can easily be interrupted — the next collect finds every lens
+ * already terminal, skips them all, and would otherwise reach the post-pass
+ * gate with nothing to hand it. Reading the saved results back is what makes
+ * "a resumed collect can finish whichever is still pending" true.
+ */
+export async function loadSavedLensResults(runDir, lenses) {
+    if (!(await pathExists(runDir)))
+        return [];
+    const reserved = new Set(["requests.json", "run-meta.json", "synthesis.json", "triage.json"]);
+    const out = [];
+    // Longest lens id first: no id is a prefix of another today, but ordering
+    // keeps that from becoming a silent misattribution if one ever is.
+    const ordered = [...lenses].sort((a, b) => b.length - a.length);
+    for (const name of (await readdir(runDir)).sort()) {
+        if (!name.endsWith(".json") || name.endsWith(".error.json") || reserved.has(name) || name.startsWith("raw-"))
+            continue;
+        const customId = name.slice(0, -".json".length);
+        const lensId = ordered.find((id) => customId === id || customId.startsWith(`${id}-`));
+        if (!lensId)
+            continue;
+        const content = await readFile(join(runDir, name), "utf8").catch(() => null);
+        if (content === null)
+            continue;
+        out.push({
+            lensId,
+            customId,
+            moduleName: customId.replace(/^[a-z]+-/, ""),
+            content,
+            raw: {},
+            truncated: parseLensJson(content) === null,
+        });
+    }
+    return out;
+}
 async function loadStoredRequests(runDir) {
     const path = join(runDir, "requests.json");
     if (!(await pathExists(path)))
@@ -1956,11 +2126,19 @@ export async function runBroadsideCollect(cwd, apiKey, opts = {}) {
             await writeFile(join(runDir, `raw-${lensId}.json`), `${JSON.stringify(batch, null, "\t")}\n`, "utf8");
             lensOutcomes[lensId] = { status, cost: entry.cost, resultCount: entry.resultCount, truncated };
         }
-        else if (batch.error) {
-            entry.error = batch.error;
+        else {
+            // Every non-completed outcome still has to reach the report.
+            // `lensOutcomes` is what the caller renders, and this branch used to
+            // require `batch.error` — but the commonest failure here is the
+            // synthetic `{ status: "timeout" }` the poll returns when its budget
+            // expires with the batch still in flight, and that carries no error.
+            // A lens that never came back was therefore omitted entirely,
+            // indistinguishable in the output from one that was never requested.
+            if (batch.error)
+                entry.error = batch.error;
             lensOutcomes[lensId] = { status, cost: entry.cost, resultCount: entry.resultCount };
         }
-        await saveBroadsideState(broadsideDir, state);
+        await persistBroadsideRun(broadsideDir, run);
     }
     // #133: re-submit truncated slices once with a bumped output cap. Batch
     // requests are pure, so re-running is always safe; the aim is to recover
@@ -1993,7 +2171,11 @@ export async function runBroadsideCollect(cwd, apiKey, opts = {}) {
                 if (error)
                     continue;
                 const batch = await pollBatchUntilTerminal(batchId, apiKey, {
-                    deadlineMs: BROADSIDE_DEFAULT_POLL_BUDGET_MS,
+                    // Share the caller's deadline. Each of these polls used to
+                    // start a fresh 25-minute budget, so `wait_seconds` bounded
+                    // only the lens poll and a collect could run for the caller's
+                    // budget plus fifty minutes.
+                    deadlineMs: Math.max(0, deadline - Date.now()),
                     onStatus: (status, counts) => opts.onStatus?.(`${stored.lensId}:retry`, status, counts),
                     fetcher: opts.fetcher,
                 });
@@ -2023,7 +2205,7 @@ export async function runBroadsideCollect(cwd, apiKey, opts = {}) {
                 outcome.truncated = allLensResults.filter((s) => s.lensId === lensId && s.truncated).length;
             }
         }
-        await saveBroadsideState(broadsideDir, state);
+        await persistBroadsideRun(broadsideDir, run);
     }
     // Synthesis + triage: cross-lens post-passes, only after every lens batch
     // is terminal. Triage turns the leads into a prioritized work order.
@@ -2032,12 +2214,25 @@ export async function runBroadsideCollect(cwd, apiKey, opts = {}) {
     let topTriageItems = [];
     const wantSynthesis = opts.includeSynthesis !== false;
     const wantTriage = opts.includeTriage !== false;
+    // A resumed collect polls nothing — every lens is already terminal — so the
+    // findings the post-passes need have to come back off disk, or a run whose
+    // first collect was interrupted could never produce its executive report
+    // and work order, however many times it was re-run.
+    const postPassUnfinished = (entry) => entry.status === "pending" || entry.status === "submitted";
+    if ((wantSynthesis || wantTriage) && allLensResults.length === 0
+        && (postPassUnfinished(run.synthesis) || postPassUnfinished(run.triage))) {
+        const restored = await loadSavedLensResults(runDir, run.lenses);
+        if (restored.length > 0) {
+            allLensResults.push(...restored);
+            truncatedCount = restored.filter((s) => s.truncated).length;
+        }
+    }
     if ((wantSynthesis || wantTriage) && allLensResults.length > 0) {
         const allTerminal = run.lenses.every((lensId) => {
             const entry = run.batches[lensId];
             return entry && ["completed", "failed", "expired", "cancelled", "auth-failed", "skipped", "rejected"].includes(entry.status);
         });
-        if (allTerminal && (run.synthesis.status === "pending" || run.triage.status === "pending")) {
+        if (allTerminal && (postPassUnfinished(run.synthesis) || postPassUnfinished(run.triage))) {
             const findingsText = allLensResults
                 .map((r) => `## ${r.lensId} — ${r.customId}\n\n${r.content}\n`)
                 .join("\n");
@@ -2066,6 +2261,24 @@ export async function runBroadsideCollect(cwd, apiKey, opts = {}) {
                     : []),
             ];
             const submitted = new Map();
+            // A pass can be left at "submitted" when an earlier collect returned
+            // before its batch reached a terminal status — the batch still runs
+            // and is still charged, so the result exists and is simply unclaimed.
+            // Nothing above would ever look at it again: the pass list is built
+            // from "pending" entries only. Poll those regardless of the want
+            // flags, because the spend already happened and discarding a
+            // finished result is worse than saving one the caller opted out of.
+            for (const kind of ["synthesis", "triage"]) {
+                const entry = kind === "synthesis" ? run.synthesis : run.triage;
+                if (entry.status !== "submitted" || !entry.batchId)
+                    continue;
+                if (submitted.has(entry.batchId))
+                    continue;
+                submitted.set(entry.batchId, {
+                    batchId: entry.batchId,
+                    pass: { kind, request: undefined, entry },
+                });
+            }
             await Promise.allSettled(passes.map(async (pass) => {
                 pass.entry.status = "submitted";
                 try {
@@ -2081,10 +2294,13 @@ export async function runBroadsideCollect(cwd, apiKey, opts = {}) {
                     pass.entry.status = "failed";
                 }
             }));
-            await saveBroadsideState(broadsideDir, state);
+            await persistBroadsideRun(broadsideDir, run);
             for (const { batchId, pass } of submitted.values()) {
                 const batch = await pollBatchUntilTerminal(batchId, apiKey, {
-                    deadlineMs: BROADSIDE_DEFAULT_POLL_BUDGET_MS,
+                    // Shares the caller's deadline, as the retry poll above does.
+                    // A pass whose poll runs out stays `submitted`, so the batch
+                    // is already paid for and a later collect claims its result.
+                    deadlineMs: Math.max(0, deadline - Date.now()),
                     onStatus: (status, counts) => opts.onStatus?.(pass.kind, status, counts),
                     fetcher: opts.fetcher,
                 });
@@ -2107,10 +2323,20 @@ export async function runBroadsideCollect(cwd, apiKey, opts = {}) {
                         }
                     }
                 }
-                else if (batch.error) {
+                else if (BROADSIDE_DEAD_BATCH_STATUSES.includes(String(batch.status))) {
+                    // The batch will never produce a result, so retire the pass.
+                    // This used to require `batch.error`, leaving an expired or
+                    // cancelled batch parked at "submitted" forever — and since a
+                    // resumed collect re-polls anything still "submitted", it
+                    // would re-poll a dead batch on every future run.
                     pass.entry.status = "failed";
+                    if (batch.error)
+                        pass.entry.error = batch.error instanceof Error ? batch.error.message : String(batch.error);
                 }
-                await saveBroadsideState(broadsideDir, state);
+                // A "timeout" is deliberately left at "submitted": the batch is
+                // still running server-side and has already been paid for, so a
+                // later collect should claim its result rather than discard it.
+                await persistBroadsideRun(broadsideDir, run);
             }
         }
     }
@@ -2120,7 +2346,7 @@ export async function runBroadsideCollect(cwd, apiKey, opts = {}) {
     });
     run.status = terminal ? (resultCount > 0 ? "completed" : "failed") : "partial";
     run.totalCost = totalCost;
-    await saveBroadsideState(broadsideDir, state);
+    await persistBroadsideRun(broadsideDir, run);
     await writeFile(join(runDir, "run-meta.json"), `${JSON.stringify({
         experimental: true,
         method: "Broad-Side (OpenRouter Batch API)",
@@ -2223,9 +2449,31 @@ function parseSynthesisTopFindings(content) {
     }
 }
 // ---------- formatting helpers for tool output ----------
+function describeIncrementalFallback(reason) {
+    switch (reason) {
+        case "dirty-worktree":
+            return "the working tree has uncommitted changes, so there is no committed state to diff against";
+        case "no-baseline":
+            return "no earlier run recorded a commit to diff against";
+        case "diff-failed":
+            return "the diff against the previous run's commit could not be read";
+        default:
+            return "no baseline was available";
+    }
+}
 export function estimateSubmitText(result, lenses) {
+    // Count the lenses that actually got a batch, not every lens considered. A
+    // lens with nothing to scan is reported as `skipped (0 request(s))` two
+    // lines below, so counting it here made the header contradict its own body:
+    // a Rust CLI with no server surface reported "submitted 6 batch(es)" over a
+    // list showing four batches and two skips.
+    const entries = Object.values(result.batches ?? {});
+    const submittedCount = entries.filter((entry) => entry.batchId).length;
+    const withoutBatch = entries.length - submittedCount;
     const lines = [
-        `Broad-Side submitted ${result.batches ? Object.keys(result.batches).length : 0} batch(es).`,
+        withoutBatch > 0
+            ? `Broad-Side submitted ${submittedCount} batch(es); ${withoutBatch} lens(es) produced none (see below).`
+            : `Broad-Side submitted ${submittedCount} batch(es).`,
     ];
     for (const lens of lenses) {
         const entry = result.batches[lens.id];
@@ -2235,6 +2483,12 @@ export function estimateSubmitText(result, lenses) {
         const override = entry.model ? ` on ${entry.model}` : "";
         lines.push(`  ${lens.name}: ${status} (${entry.requests} request(s), ~$${entry.estimatedCost.toFixed(4)})${override}`);
     }
+    const incremental = result.incremental;
+    if (incremental?.requested) {
+        lines.push(incremental.applied
+            ? `Incremental: scanning only what changed since ${(incremental.baseHead ?? "").slice(0, 8)}.`
+            : `Incremental: requested but NOT applied — ${describeIncrementalFallback(incremental.reason)}. Every module was scanned, at full cost.`);
+    }
     lines.push(`Estimated total: ~$${result.estimatedTotalCost.toFixed(4)}`, `Pricing: $${result.pricing.inputPerM.toFixed(4)}/M in, $${result.pricing.outputPerM.toFixed(4)}/M out (${result.pricing.source})`);
     if (result.modelInfo.contextLength) {
         lines.push(`Model: ${result.modelInfo.contextLength.toLocaleString()} context, ${result.modelInfo.maxCompletionTokens?.toLocaleString() ?? "?"} max output`);

package/dist/core/completion.d.ts

@@ -24,4 +24,19 @@ export declare const CONVENTIONS_PENDING_HEADING = "## Pending proposals";
  * @param content - the file content, or null to read from disk (null when the file is absent).
  */
 export declare function countPendingProposals(workspaceDir: string, content?: string): Promise<number>;
+/**
+ * First scaffold version whose handoff template documents the `{id, evidence}`
+ * closure shape and the runtime-evidence rule (#122, #186).
+ *
+ * A workspace scaffolded before it was never told that closing a
+ * `needs-runtime-test` question requires evidence, so refusing its completion
+ * would apply a rule its own templates do not carry — and could stop an
+ * in-flight `--auto` run on a handoff written against the older contract.
+ * Those workspaces get a warning instead; refreshing the scaffold
+ * (`codecarto_refresh_scaffold` on MCP, `/codecarto-refresh-scaffold` on Pi)
+ * opts them in. Same treatment Stage 2's findings pairing check uses.
+ */
+export declare const CLOSURE_EVIDENCE_GATE_SCAFFOLD_VERSION = "0.19.0";
+/** Whether the runtime-evidence requirement refuses (current scaffold) or warns (older). */
+export declare function closureEvidenceGateActive(scaffoldVersion: string | undefined | null): boolean;
 export declare function completeValidatedPhase(cwd: string, validation: ValidationResult, sourceLabel: string): Promise<CompletionResult>;

package/dist/core/completion.js

@@ -2,7 +2,7 @@ import { appendFile, copyFile, mkdir, readFile, readdir, writeFile } from "node:
 import { join } from "node:path";
 import { getNextEligiblePhase, resolvePhase, validatePhaseOutput } from "./pipeline.js";
 import { applyHandoff, autoAssignIds, buildTerminalNextActions, loadHandoffFile, normalizeStatus } from "./status.js";
-import { dateOnly, newlineIfUnterminated, pathExists, uniqueStrings } from "./utils.js";
+import { compareDottedVersions, dateOnly, newlineIfUnterminated, pathExists, uniqueStrings } from "./utils.js";
 import { getWorkspaceState, updateStatusAtomically } from "./workspace.js";
 /**
  * The Markdown a reader sees: content inside `<!-- -->` blocks removed by a
@@ -233,6 +233,26 @@ async function writeCompletionArtifacts(workspaceDir, phaseId, validation, times
     const { totalPending: totalPendingProposals } = await stageProposedConventions(workspaceDir, phaseId, timestamp, handoff?.proposed_conventions ?? []);
     return { closeoutPath: `.codecarto/closeouts/${closeoutFile}`, decisionsAppended, totalPendingProposals };
 }
+/**
+ * First scaffold version whose handoff template documents the `{id, evidence}`
+ * closure shape and the runtime-evidence rule (#122, #186).
+ *
+ * A workspace scaffolded before it was never told that closing a
+ * `needs-runtime-test` question requires evidence, so refusing its completion
+ * would apply a rule its own templates do not carry — and could stop an
+ * in-flight `--auto` run on a handoff written against the older contract.
+ * Those workspaces get a warning instead; refreshing the scaffold
+ * (`codecarto_refresh_scaffold` on MCP, `/codecarto-refresh-scaffold` on Pi)
+ * opts them in. Same treatment Stage 2's findings pairing check uses.
+ */
+export const CLOSURE_EVIDENCE_GATE_SCAFFOLD_VERSION = "0.19.0";
+/** Whether the runtime-evidence requirement refuses (current scaffold) or warns (older). */
+export function closureEvidenceGateActive(scaffoldVersion) {
+    if (!scaffoldVersion)
+        return false;
+    const comparison = compareDottedVersions(scaffoldVersion, CLOSURE_EVIDENCE_GATE_SCAFFOLD_VERSION);
+    return comparison !== null && comparison >= 0;
+}
 export async function completeValidatedPhase(cwd, validation, sourceLabel) {
     const initialState = await getWorkspaceState(cwd);
     if (!initialState)
@@ -254,6 +274,7 @@ export async function completeValidatedPhase(cwd, validation, sourceLabel) {
                 + `plus closeout_summary and optional closeout_content. Then re-run completion.`);
         }
     }
+    const warnings = [];
     if (handoff) {
         const activePhases = new Set(initialState.pipeline.phase_order);
         const sourceIndex = initialState.pipeline.phase_order.indexOf(validation.phaseId);
@@ -267,14 +288,70 @@ export async function completeValidatedPhase(cwd, validation, sourceLabel) {
             if (!entry.id?.trim())
                 throw new Error("Invalid handoff: post_pipeline entries require a canonical id");
         }
+        // Closure integrity, gating (#122, #186). Both checks are deterministic
+        // reads of ids the model wrote itself, so neither can wedge an --auto run
+        // on a heuristic; both sit here, before the lock, alongside the
+        // target_phase check, so a refusal mutates nothing.
+        const questionsById = new Map();
+        const derivesFromById = new Map();
+        for (const phaseState of Object.values(initialState.status.phases)) {
+            for (const entry of phaseState.open_questions ?? []) {
+                if (entry.id)
+                    questionsById.set(entry.id, entry);
+            }
+            for (const entry of phaseState.carry_forward ?? []) {
+                if (entry.id && entry.derives_from)
+                    derivesFromById.set(entry.id, entry.derives_from);
+            }
+        }
+        const closingQuestionIds = new Set(handoff.open_question_closures.map((closure) => closure.id).filter(Boolean));
+        // D1: a routed item that declares `derives_from` is one candidate answer
+        // to that question. Closing it while the question stands is exactly the
+        // contradiction #122 reported — the routed candidate shipped as settled
+        // while the question that said "source alone cannot determine which" was
+        // still open. A derives_from naming an id that no longer exists is fine:
+        // the question was already resolved.
+        for (const closureId of handoff.carry_forward_closures) {
+            const questionId = derivesFromById.get(closureId);
+            if (!questionId || !questionsById.has(questionId))
+                continue;
+            if (closingQuestionIds.has(questionId))
+                continue;
+            throw new Error(`Refusing to complete ${validation.phaseId}: the handoff closes carry_forward ${closureId}, which derives_from open question ${questionId} — and ${questionId} is still unresolved and is not in this handoff's open_question_closures. `
+                + `A routed item is one candidate answer to the question it came from; closing it does not settle the question. `
+                + `Either close ${questionId} in this same handoff with the evidence that settles it, or leave ${closureId} routed and give the finding an unsettled action ("verify at runtime") instead.`);
+        }
+        // D3: a `needs-runtime-test` question closes on runtime evidence, not on
+        // another source read. Requiring the evidence string to be non-empty is
+        // the whole gate — judging what it says stays prose guidance.
+        //
+        // Unlike D1, this one can fire on a handoff that uses none of the new
+        // fields: a bare-string closure was the only shape before this release.
+        // Gating it unconditionally would apply a rule to workspaces whose own
+        // templates never state it, so it is version-gated exactly like Stage
+        // 2's pairing check — refuse on a scaffold that documents the rule, warn
+        // on one that predates it.
+        const evidenceGateActive = closureEvidenceGateActive(initialState.scaffoldVersion);
+        for (const closure of handoff.open_question_closures) {
+            if (questionsById.get(closure.id)?.kind !== "needs-runtime-test")
+                continue;
+            if (closure.evidence?.trim())
+                continue;
+            const detail = `open_question_closures closes ${closure.id}, whose kind is needs-runtime-test, without evidence. `
+                + `A runtime question closes on runtime evidence — a spike report or an observation against the running system — not on a source read. `
+                + `Write the closure as an object: { id: ${closure.id}, evidence: <where that evidence lives> }. If you do not have it, leave the question open.`;
+            if (evidenceGateActive)
+                throw new Error(`Refusing to complete ${validation.phaseId}: ${detail}`);
+            warnings.push(`${detail} Warning only: this workspace's scaffold predates the requirement — refresh it `
+                + `(codecarto_refresh_scaffold on MCP, /codecarto-refresh-scaffold on Pi) to make this gating.`);
+        }
     }
     // Closure integrity (#122, warning only): a handoff can close a carry-forward
     // or open question the report never addressed — "closed in the handoff,
     // resolved nowhere." The id of every claimed closure should appear somewhere
     // in the primary output that claims to resolve it.
-    const warnings = [];
     if (handoff && validation.outputPath) {
-        const closures = [...handoff.carry_forward_closures, ...handoff.open_question_closures].filter((id) => id?.trim());
+        const closures = [...handoff.carry_forward_closures, ...handoff.open_question_closures.map((closure) => closure.id)].filter((id) => id?.trim());
         if (closures.length > 0) {
             const output = await readFile(validation.outputPath, "utf8").catch(() => "");
             const unmentioned = closures.filter((id) => !output.includes(id));