codecartographer-pi 0.19.0 → 0.19.2

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";
@@ -67,6 +74,34 @@ export const BROADSIDE_LENS_IDS = [
 ];
 export const BROADSIDE_POLL_INTERVAL_MS = 15_000;
 export const BROADSIDE_DEFAULT_POLL_BUDGET_MS = 25 * 60 * 1000;
+/**
+ * The share of a lens's output budget reasoning may spend.
+ *
+ * `estimateCost` already budgets output at 75% of `maxTokens`; capping thinking
+ * at the remaining quarter makes that assumption true by construction and
+ * guarantees the answer has room. A floor keeps the cap sane for a small lens.
+ */
+export const BROADSIDE_REASONING_BUDGET_FRACTION = 0.25;
+export const BROADSIDE_MIN_REASONING_TOKENS = 512;
+/**
+ * Cap reasoning for a lens request — deliberately a cap, not an off switch.
+ *
+ * Disabling outright is not portable: `google/gemini-3.8-flash:batch` refuses
+ * the whole batch with *"Reasoning is mandatory for this endpoint and cannot be
+ * disabled"*, turning a partial result into none at all. Capping works whether
+ * or not a provider allows reasoning to be switched off.
+ *
+ * The failure this prevents is the budget being spent thinking rather than
+ * answering. Measured on one run: 5,758 of a 6,000-token budget went to
+ * reasoning, leaving ~230 tokens for JSON that truncated mid-structure — and
+ * those tokens bill at the full output rate. The shipped default model does the
+ * same thing less consistently (reasoning tokens from 0 to 5,757 across 13
+ * slices, three of them cut off at `finish_reason: length`), so this is not a
+ * multi-model concern.
+ */
+export function defaultReasoningFor(maxTokens) {
+    return { max_tokens: Math.max(BROADSIDE_MIN_REASONING_TOKENS, Math.floor(maxTokens * BROADSIDE_REASONING_BUDGET_FRACTION)) };
+}
 /** Thrown when a confirm hook declines a run. Nothing was submitted. */
 export class BroadsideCancelledError extends Error {
     constructor(message = "Broad-Side submission cancelled. Nothing was submitted.") {
@@ -848,7 +883,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);
         }
     }
@@ -1126,7 +1164,7 @@ async function sumFileSizes(targetDir, files) {
     return total;
 }
 // ---------- request building ----------
-export function buildBatchRequest(lens, info, slice, index, sliceCount, model = BROADSIDE_MODEL, maxTokensOverride) {
+export function buildBatchRequest(lens, info, slice, index, sliceCount, model = BROADSIDE_MODEL, maxTokensOverride, reasoningOverride) {
     const moduleTag = sanitizeId(slice.moduleName);
     const customId = sliceCount > 1 ? `${lens.id}-${moduleTag}-${index + 1}` : `${lens.id}-${moduleTag}`;
     return {
@@ -1139,12 +1177,36 @@ export function buildBatchRequest(lens, info, slice, index, sliceCount, model =
             ],
             response_format: { type: "json_schema", json_schema: SCHEMAS[lens.schemaName] },
             max_tokens: maxTokensOverride ?? lens.maxTokens,
+            // Always sent, never inherited: an absent field means the model's
+            // own default, and that default is what truncated the JSON.
+            reasoning: reasoningOverride ?? lens.reasoning ?? defaultReasoningFor(maxTokensOverride ?? lens.maxTokens),
         },
     };
 }
-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 +1257,94 @@ 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;
+    });
+}
+/** Read a `reasoning:` block from config.yaml, ignoring anything malformed. */
+function parseReasoningConfig(raw) {
+    if (raw === false)
+        return { enabled: false };
+    if (raw === true)
+        return { enabled: true };
+    if (!raw || typeof raw !== "object")
+        return null;
+    const value = raw;
+    const out = {};
+    if (typeof value.enabled === "boolean")
+        out.enabled = value.enabled;
+    if (value.effort === "minimal" || value.effort === "low" || value.effort === "medium" || value.effort === "high")
+        out.effort = value.effort;
+    if (typeof value.max_tokens === "number" && value.max_tokens > 0)
+        out.max_tokens = value.max_tokens;
+    return Object.keys(out).length > 0 ? out : null;
 }
 export async function loadBroadsideConfig(broadsideDir) {
     const configPath = join(broadsideDir, BROADSIDE_CONFIG_FILE);
@@ -1239,6 +1386,10 @@ export async function loadBroadsideConfig(broadsideDir) {
             ? { inputPerM: inputOverride, outputPerM: outputOverride }
             : null,
         lensModels,
+        // An escape hatch, not a knob to reach for: a model whose reasoning is
+        // worth paying for needs its lens maxTokens raised to cover both the
+        // thinking and the answer, or the JSON truncates exactly as before.
+        reasoning: parseReasoningConfig(raw.reasoning),
         incremental: flag("incremental", false),
         retryTruncated: flag("retry_truncated", true),
         includeSynthesis: flag("include_synthesis", true),
@@ -1332,10 +1483,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 +1518,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 +1626,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 +1656,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 +1728,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 +1772,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 +1807,7 @@ export async function runBroadsideSubmit(cwd, apiKey, opts = {}) {
             exceedsLimit,
             baseHead,
             sourceDirty,
+            incremental: incrementalOutcome,
             ...(outputCap !== undefined && { outputCap }),
         });
         if (!approved)
@@ -1659,7 +1841,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
@@ -1668,7 +1850,7 @@ export async function runBroadsideSubmit(cwd, apiKey, opts = {}) {
         const { lens, maxTokens, lensModel, lensOutputCap } = priced;
         const lensId = lens.id;
         const slices = slicesByLens.get(lensId) ?? [];
-        const requests = slices.map((sl, i) => buildBatchRequest(lens, info, sl, i, slices.length, lensModel, maxTokens));
+        const requests = slices.map((sl, i) => buildBatchRequest(lens, info, sl, i, slices.length, lensModel, maxTokens, config.reasoning ?? undefined));
         for (const request of requests)
             requestsByCustomId[request.custom_id] = request;
         const entry = {
@@ -1707,7 +1889,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 +1916,7 @@ export async function runBroadsideSubmit(cwd, apiKey, opts = {}) {
                 : resolved.get(model).supportsStructuredOutputs,
             expirationDate: defaultEntry.expirationDate ?? null,
         },
+        incremental: incrementalOutcome,
     };
 }
 function extractContent(result) {
@@ -1799,6 +1982,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 +2179,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 +2224,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 +2258,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 +2267,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 +2314,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 +2347,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 +2376,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 +2399,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 +2502,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 +2536,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/dashboard.d.ts

@@ -39,4 +39,17 @@ export interface DashboardInputs {
     narration?: DashboardNarration;
 }
 export declare function renderDashboard(inputs: DashboardInputs): string;
+/**
+ * A dashboard link target, or undefined when the path is not a safe relative
+ * reference. Absolute paths, scheme-bearing URLs and `.`/`..` segments are
+ * refused outright.
+ *
+ * Percent-encoding each segment is load-bearing, not cosmetic: a Windows-style
+ * `dir\..\secret` survives the segment scan, because that scan splits on `/`
+ * — but `encodeURIComponent` turns the separators into `%5C`, which no URL
+ * parser treats as a path separator, so the traversal cannot resolve. Removing
+ * the encoding, or "simplifying" it to a raw join, reopens it. Exported so
+ * that property has a test.
+ */
+export declare function safeRelativeHref(path: string): string | undefined;
 export declare function escapeHtml(input: string): string;

package/dist/core/dashboard.js

@@ -660,7 +660,19 @@ function renderSafeLink(path, label, className) {
     const classAttr = className ? ` class="${escapeAttr(className)}"` : "";
     return `<a${classAttr} href="${escapeAttr(href)}">${escapeHtml(label)}</a>`;
 }
-function safeRelativeHref(path) {
+/**
+ * A dashboard link target, or undefined when the path is not a safe relative
+ * reference. Absolute paths, scheme-bearing URLs and `.`/`..` segments are
+ * refused outright.
+ *
+ * Percent-encoding each segment is load-bearing, not cosmetic: a Windows-style
+ * `dir\..\secret` survives the segment scan, because that scan splits on `/`
+ * — but `encodeURIComponent` turns the separators into `%5C`, which no URL
+ * parser treats as a path separator, so the traversal cannot resolve. Removing
+ * the encoding, or "simplifying" it to a raw join, reopens it. Exported so
+ * that property has a test.
+ */
+export function safeRelativeHref(path) {
     if (!path || path.startsWith("/") || path.startsWith("\\") || /^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(path))
         return undefined;
     const parts = path.split("/");