codecartographer-pi 0.20.0 → 0.22.0

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 { createHash } from "node:crypto";
 import { mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { join, relative } from "node:path";
-import { atomicWriteFile, pathExists, sleep } from "./utils.js";
+import { atomicWriteFile, GIT_TIMEOUT_MS, pathExists, sleep } from "./utils.js";
 import { describeRedactions, isSecretFile, redactSecrets } from "./secrets.js";
 import { acquireLock } from "./status.js";
 import { loadYamlFile } from "./yaml.js";
@@ -64,6 +65,13 @@ export const BROADSIDE_OUTPUT_PRICE_PER_M = 1.875;
 export const BROADSIDE_MODELS_URL = "https://openrouter.ai/api/v1/models";
 export const BROADSIDE_BENCHMARKS_URL = "https://openrouter.ai/api/v1/benchmarks";
 export const BROADSIDE_CATALOG_CACHE_FILE = "model-catalog.json";
+/**
+ * What this repository's own submits learned about batch endpoints: which
+ * `:batch` ids OpenRouter accepted a job for and which it refused with
+ * "does not have a :batch endpoint". The catalog cannot tell the two apart
+ * (#141), so the `models` action annotates its rows from this file.
+ */
+export const BROADSIDE_ENDPOINTS_FILE = "batch-endpoints.json";
 export const BROADSIDE_CATALOG_CACHE_TTL_MS = 24 * 60 * 60 * 1000;
 export const BROADSIDE_LENS_IDS = [
     "architecture",
@@ -75,6 +83,16 @@ export const BROADSIDE_LENS_IDS = [
 ];
 export const BROADSIDE_POLL_INTERVAL_MS = 15_000;
 export const BROADSIDE_DEFAULT_POLL_BUDGET_MS = 25 * 60 * 1000;
+/**
+ * The run expense limit in USD a repository gets before it configures one.
+ * Pi asks a human before submitting over the estimate; the MCP surface cannot,
+ * and shipped with no limit at all, so a host calling submit with the stock
+ * config spent whatever the estimate came to (#231). One dollar covers a
+ * six-lens run of a repository this size with room to spare; a larger one
+ * raises `max_cost` in config.yaml, passes `max_cost` on the call, or sets it
+ * to 0 for no limit.
+ */
+export const BROADSIDE_DEFAULT_MAX_COST = 1;
 /**
  * The share of a lens's output budget reasoning may spend.
  *
@@ -120,6 +138,37 @@ export class BroadsideAuthError extends Error {
         this.detail = detail;
     }
 }
+/**
+ * `broadside/config.yaml` exists but cannot be used. A file that failed to
+ * parse used to be treated exactly like an absent one — defaults, including
+ * no spend cap and no lens routing, with no message — so a typo removed the
+ * user's own guard (#232). Only an absent file yields defaults now.
+ */
+export class BroadsideConfigError extends Error {
+    path;
+    constructor(path, detail) {
+        super(`Broad-Side config ${path} ${detail}. Fix or remove the file; nothing runs on defaults while it is unreadable.`);
+        this.name = "BroadsideConfigError";
+        this.path = path;
+    }
+}
+/**
+ * `broadside/state.json` exists but cannot be read. It used to be read as
+ * empty and the next checkpoint wrote that empty state over it, losing the
+ * batch ids of every in-flight, already-paid run (#233). The corrupt file is
+ * preserved beside itself and nothing writes over it until someone looks.
+ */
+export class BroadsideStateError extends Error {
+    path;
+    backupPath;
+    constructor(path, backupPath, detail) {
+        super(`Broad-Side state ${path} ${detail}. A copy is preserved at ${backupPath}; the file is not overwritten. ` +
+            "Repair state.json from the copy (each run's batch ids are what collect needs), or move it aside to start fresh.");
+        this.name = "BroadsideStateError";
+        this.path = path;
+        this.backupPath = backupPath;
+    }
+}
 /** 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.") {
@@ -851,9 +900,10 @@ const SOURCE_SPECS = {
  */
 async function listRepoFiles(targetDir) {
     try {
-        const listed = await execFileAsync("git", ["-C", targetDir, "ls-files", "-z", "--cached", "--others", "--exclude-standard"], { maxBuffer: 64 * 1024 * 1024 });
+        const listed = await execFileAsync("git", ["-C", targetDir, "ls-files", "-z", "--cached", "--others", "--exclude-standard"], { maxBuffer: 64 * 1024 * 1024, timeout: GIT_TIMEOUT_MS });
         const deleted = await execFileAsync("git", ["-C", targetDir, "ls-files", "-z", "--deleted"], {
             maxBuffer: 64 * 1024 * 1024,
+            timeout: GIT_TIMEOUT_MS,
         });
         const gone = new Set(deleted.stdout.split("\0").filter(Boolean));
         const files = listed.stdout.split("\0").filter((path) => path && !gone.has(path));
@@ -865,7 +915,7 @@ async function listRepoFiles(targetDir) {
 }
 async function gitHead(targetDir) {
     try {
-        const { stdout } = await execFileAsync("git", ["-C", targetDir, "rev-parse", "HEAD"], { maxBuffer: 1024 * 1024 });
+        const { stdout } = await execFileAsync("git", ["-C", targetDir, "rev-parse", "HEAD"], { maxBuffer: 1024 * 1024, timeout: GIT_TIMEOUT_MS });
         return stdout.trim() || null;
     }
     catch {
@@ -874,7 +924,7 @@ async function gitHead(targetDir) {
 }
 async function gitDirty(targetDir) {
     try {
-        const { stdout } = await execFileAsync("git", ["-C", targetDir, "status", "--porcelain"], { maxBuffer: 1024 * 1024 });
+        const { stdout } = await execFileAsync("git", ["-C", targetDir, "status", "--porcelain"], { maxBuffer: 1024 * 1024, timeout: GIT_TIMEOUT_MS });
         return stdout.trim().length > 0;
     }
     catch {
@@ -890,7 +940,7 @@ async function changedFilesSince(targetDir, baseHead) {
     if (!baseHead)
         return null;
     try {
-        const { stdout } = await execFileAsync("git", ["-C", targetDir, "diff", "--name-only", baseHead, "HEAD"], { maxBuffer: 64 * 1024 * 1024 });
+        const { stdout } = await execFileAsync("git", ["-C", targetDir, "diff", "--name-only", baseHead, "HEAD"], { maxBuffer: 64 * 1024 * 1024, timeout: GIT_TIMEOUT_MS });
         return new Set(stdout.split("\n").filter(Boolean));
     }
     catch {
@@ -909,7 +959,7 @@ async function walkFiles(rootDir, dir, depth, remaining) {
         return out;
     }
     for (const entry of entries) {
-        if (entry.name.startsWith(".") && entry.name !== ".github")
+        if (entry.name.startsWith("."))
             continue;
         if (entry.isDirectory()) {
             if (SKIP_DIR_NAMES.has(entry.name))
@@ -1371,15 +1421,30 @@ export async function loadBroadsideState(broadsideDir) {
     const statePath = join(broadsideDir, BROADSIDE_STATE_FILE);
     if (!(await pathExists(statePath)))
         return defaultBroadsideState();
+    const text = await readFile(statePath, "utf8");
+    let raw;
     try {
-        const raw = JSON.parse(await readFile(statePath, "utf8"));
-        if (!raw || typeof raw !== "object" || !Array.isArray(raw.runs))
-            return defaultBroadsideState();
-        return raw;
+        raw = JSON.parse(text);
     }
-    catch {
-        return defaultBroadsideState();
+    catch (error) {
+        throw new BroadsideStateError(statePath, await preserveCorruptState(statePath, text), `could not be parsed (${error instanceof Error ? error.message : String(error)})`);
+    }
+    if (!raw || typeof raw !== "object" || !Array.isArray(raw.runs)) {
+        throw new BroadsideStateError(statePath, await preserveCorruptState(statePath, text), "is not a state file (expected an object with a runs array)");
     }
+    return raw;
+}
+/**
+ * Copy an unreadable state file to `state.json.corrupt-<hash>` beside it,
+ * named by content so repeated loads do not multiply copies. Returns the
+ * copy's path (the existing one, when the same content was preserved before).
+ */
+async function preserveCorruptState(statePath, text) {
+    const digest = createHash("sha1").update(text).digest("hex").slice(0, 8);
+    const backupPath = `${statePath}.corrupt-${digest}`;
+    if (!(await pathExists(backupPath)))
+        await writeFile(backupPath, text, "utf8");
+    return backupPath;
 }
 /**
  * Overwrite `state.json` wholesale with `state`.
@@ -1472,13 +1537,26 @@ export async function loadBroadsideConfig(broadsideDir) {
     const configPath = join(broadsideDir, BROADSIDE_CONFIG_FILE);
     let raw = {};
     if (await pathExists(configPath)) {
+        let parsed;
         try {
-            raw = (await loadYamlFile(configPath)) ?? {};
+            parsed = await loadYamlFile(configPath);
         }
-        catch {
-            raw = {};
+        catch (error) {
+            throw new BroadsideConfigError(configPath, `could not be parsed (${error instanceof Error ? error.message : String(error)})`);
+        }
+        if (parsed !== null && parsed !== undefined) {
+            if (typeof parsed !== "object" || Array.isArray(parsed))
+                throw new BroadsideConfigError(configPath, "is not a YAML mapping");
+            raw = parsed;
         }
     }
+    return buildBroadsideConfig(raw);
+}
+/** The shipped defaults: what an absent config.yaml means. */
+export function defaultBroadsideConfig() {
+    return buildBroadsideConfig({});
+}
+function buildBroadsideConfig(raw) {
     const lenses = Array.isArray(raw.default_lenses)
         ? (raw.default_lenses.filter((l) => BROADSIDE_LENS_IDS.includes(l)))
         : [];
@@ -1503,7 +1581,9 @@ export async function loadBroadsideConfig(broadsideDir) {
         model: typeof raw.model === "string" && raw.model.trim() ? raw.model.trim() : BROADSIDE_MODEL,
         apiKey: typeof raw.api_key === "string" ? raw.api_key.trim() : "",
         defaultLenses: lenses.length > 0 ? lenses : [...BROADSIDE_LENS_IDS],
-        maxCost: typeof raw.max_cost === "number" && raw.max_cost > 0 ? raw.max_cost : 0,
+        // Absent: the shipped default. An explicit 0 is "no limit", spelled out
+        // on purpose; a negative or non-numeric value is not a limit at all.
+        maxCost: typeof raw.max_cost === "number" && raw.max_cost >= 0 ? raw.max_cost : BROADSIDE_DEFAULT_MAX_COST,
         pricing: inputOverride !== undefined && outputOverride !== undefined
             ? { inputPerM: inputOverride, outputPerM: outputOverride }
             : null,
@@ -1520,13 +1600,18 @@ export async function loadBroadsideConfig(broadsideDir) {
         redactSecrets: flag("redact_secrets", true),
     };
 }
+// ---------- model catalog, pricing, benchmarks ----------
+/** The catalog cache schema this build writes; a file from another is not read. */
+export const BROADSIDE_CATALOG_CACHE_SCHEMA = 3;
 async function readCatalogCache(broadsideDir) {
     const cachePath = join(broadsideDir, BROADSIDE_CATALOG_CACHE_FILE);
     if (!(await pathExists(cachePath)))
         return null;
     try {
         const parsed = JSON.parse(await readFile(cachePath, "utf8"));
-        if (!parsed || typeof parsed !== "object" || typeof parsed.models !== "object")
+        if (!parsed || typeof parsed !== "object" || !parsed.models || typeof parsed.models !== "object")
+            return null;
+        if (parsed.schema_version !== BROADSIDE_CATALOG_CACHE_SCHEMA && parsed.schema_version !== 2)
             return null;
         return parsed;
     }
@@ -1534,10 +1619,76 @@ async function readCatalogCache(broadsideDir) {
         return null;
     }
 }
+/** When a cached entry was fetched: its own stamp, or the file's for a schema-2 cache. */
+function catalogEntryFetchedAt(cache, model) {
+    const stamp = cache.models[model]?.fetched_at ?? cache.fetched_at;
+    return new Date(stamp).getTime();
+}
 async function writeCatalogCache(broadsideDir, cache) {
     await mkdir(broadsideDir, { recursive: true });
     await writeFile(join(broadsideDir, BROADSIDE_CATALOG_CACHE_FILE), `${JSON.stringify(cache, null, "\t")}\n`, "utf8");
 }
+const BROADSIDE_ENDPOINTS_SCHEMA = 1;
+export async function readBatchEndpoints(broadsideDir) {
+    const path = join(broadsideDir, BROADSIDE_ENDPOINTS_FILE);
+    if (!(await pathExists(path)))
+        return {};
+    try {
+        const parsed = JSON.parse(await readFile(path, "utf8"));
+        if (!parsed || typeof parsed !== "object" || parsed.schema_version !== BROADSIDE_ENDPOINTS_SCHEMA)
+            return {};
+        if (!parsed.models || typeof parsed.models !== "object")
+            return {};
+        const out = {};
+        for (const [model, record] of Object.entries(parsed.models)) {
+            if (!record || typeof record !== "object")
+                continue;
+            if (record.status !== "accepted" && record.status !== "rejected")
+                continue;
+            if (typeof record.at !== "string")
+                continue;
+            out[model] = { status: record.status, at: record.at, ...(typeof record.error === "string" && { error: record.error }) };
+        }
+        return out;
+    }
+    catch {
+        // An unreadable memory is an empty one: it only annotates a listing.
+        return {};
+    }
+}
+/**
+ * The refusal OpenRouter returns for a catalog id that has no batch endpoint
+ * behind it. Matched loosely: the message is the only signal there is.
+ */
+const NO_BATCH_ENDPOINT_RE = /does not have a :batch endpoint/i;
+/** The refusal for a full per-account concurrent batch-job quota. */
+const BATCH_QUOTA_RE = /job-submission-count/i;
+/**
+ * Remember what a submit learned about each model it posted to. An accepted
+ * job proves the endpoint exists; a "does not have a :batch endpoint"
+ * refusal proves it does not. Any other rejection (quota, malformed request,
+ * auth) says nothing about the endpoint and leaves the record alone.
+ */
+export async function recordBatchEndpoints(broadsideDir, outcomes) {
+    const at = new Date().toISOString();
+    const updates = {};
+    for (const { model, batchId, error } of outcomes) {
+        if (batchId) {
+            updates[model] = { status: "accepted", at };
+            continue;
+        }
+        const message = describeBatchError(error);
+        if (message && NO_BATCH_ENDPOINT_RE.test(message)) {
+            updates[model] = { status: "rejected", at, error: message };
+        }
+    }
+    if (Object.keys(updates).length === 0)
+        return;
+    const models = { ...(await readBatchEndpoints(broadsideDir)), ...updates };
+    await mkdir(broadsideDir, { recursive: true });
+    const file = { schema_version: BROADSIDE_ENDPOINTS_SCHEMA, models };
+    await atomicWriteFile(join(broadsideDir, BROADSIDE_ENDPOINTS_FILE), `${JSON.stringify(file, null, "\t")}\n`);
+}
 function parseCatalogEntry(raw) {
     const id = String(raw.id ?? "");
     if (!id)
@@ -1613,7 +1764,7 @@ export async function resolveCatalogEntry(broadsideDir, config, model, apiKey, f
     // 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) {
+    if (cache && cached && Date.now() - catalogEntryFetchedAt(cache, model) < BROADSIDE_CATALOG_CACHE_TTL_MS) {
         return { model, source: "cache", entry: cached };
     }
     // What went wrong when the live lookup produced nothing, for the error
@@ -1649,12 +1800,15 @@ export async function resolveCatalogEntry(broadsideDir, config, model, apiKey, f
         catalogFailure = `the model catalog could not be fetched (${error instanceof Error ? error.message : String(error)})`;
     }
     if (live) {
+        const now = new Date().toISOString();
         const updated = {
-            schema_version: 2,
-            fetched_at: new Date().toISOString(),
-            models: { ...(cache?.models ?? {}) },
+            schema_version: BROADSIDE_CATALOG_CACHE_SCHEMA,
+            fetched_at: now,
+            // Other entries keep their own stamps (a schema-2 file's entries
+            // inherit the file's, once, on this upgrade); only this model is fresh.
+            models: Object.fromEntries(Object.entries(cache?.models ?? {}).map(([id, entry]) => [id, { ...entry, fetched_at: entry.fetched_at ?? cache.fetched_at }])),
         };
-        updated.models[model] = live;
+        updated.models[model] = { ...live, fetched_at: now };
         await writeCatalogCache(broadsideDir, updated);
         return { model, source: "live", entry: live };
     }
@@ -1751,12 +1905,14 @@ export async function listBatchModels(broadsideDir, config, apiKey, opts = {}) {
     }
     entries.sort((a, b) => a.inputPerM + a.outputPerM - (b.inputPerM + b.outputPerM));
     // Persist the catalog so the next submit's pricing resolution hits cache.
-    const cache = { schema_version: 2, fetched_at: new Date().toISOString(), models: {} };
+    const fetchedAt = new Date().toISOString();
+    const cache = { schema_version: BROADSIDE_CATALOG_CACHE_SCHEMA, fetched_at: fetchedAt, models: {} };
     for (const entry of entries)
-        cache.models[entry.id] = entry;
+        cache.models[entry.id] = { ...entry, fetched_at: fetchedAt };
     await writeCatalogCache(broadsideDir, cache);
     const benchmarks = opts.includeBenchmarks ? await fetchCodingBenchmarks(apiKey, fetcher) : null;
-    return { entries, source: "live", benchmarks, defaultModel: config.model };
+    const endpoints = await readBatchEndpoints(broadsideDir);
+    return { entries, source: "live", benchmarks, defaultModel: config.model, endpoints };
 }
 export async function submitBatch(batchRequests, apiKey, fetcher = fetch, model = BROADSIDE_MODEL) {
     // The OpenRouter batch endpoint stream-parses the body and requires
@@ -1811,6 +1967,14 @@ export async function fetchBatch(batchId, apiKey, fetcher = fetch) {
  * charged, so callers must come back for it rather than retire it.
  */
 export const BROADSIDE_DEAD_BATCH_STATUSES = ["failed", "expired", "cancelled", "auth-failed"];
+/**
+ * Batch entry statuses collect never polls again: the dead ones above, plus
+ * `completed`, plus the two a submit assigns without a batch (`skipped`: no
+ * matching files; `rejected`: the provider refused it). The 0.19.1 changelog
+ * called the dead set "a named constant rather than two hand-maintained
+ * lists"; this set was still three literal copies (self-audit sem 5.8).
+ */
+export const BROADSIDE_TERMINAL_ENTRY_STATUSES = ["completed", ...BROADSIDE_DEAD_BATCH_STATUSES, "skipped", "rejected"];
 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;
@@ -1906,7 +2070,8 @@ export async function runBroadsideSubmit(cwd, apiKey, opts = {}) {
         throw new Error(`Broad-Side found no ${info.language} source files to scan (detected from ${info.manifest?.path ?? "the file counts"}; ` +
             `the lenses look for ${info.sourceExts.join(", ")}). Nothing was submitted.`);
     }
-    const modelForLens = (lensId) => config.lensModels[lensId] ?? model;
+    const lensModels = { ...config.lensModels, ...opts.lensModels };
+    const modelForLens = (lensId) => lensModels[lensId] ?? model;
     const resolved = new Map();
     for (const candidate of new Set([model, ...lensIds.map(modelForLens)])) {
         const catalog = await resolveCatalogEntry(broadsideDir, config, candidate, apiKey, opts.fetcher);
@@ -2042,7 +2207,9 @@ export async function runBroadsideSubmit(cwd, apiKey, opts = {}) {
             `$${limit.toFixed(2)}. Nothing was submitted.\nBreakdown:\n${breakdown}\n` +
             `Pass force: true to submit anyway, or raise max_cost in .codecarto/broadside/config.yaml.`);
     }
-    const state = await loadBroadsideState(broadsideDir);
+    // Read before anything is posted: a state.json that cannot be read refuses
+    // the run here (#233), while persistBroadsideRun below merges by run id.
+    await loadBroadsideState(broadsideDir);
     const runId = new Date().toISOString().replace(/[:.]/g, "-");
     const run = {
         id: runId,
@@ -2069,7 +2236,6 @@ export async function runBroadsideSubmit(cwd, apiKey, opts = {}) {
             skippedFiles: info.secretFilesSkipped.length,
         },
     };
-    state.runs.push(run);
     await persistBroadsideRun(broadsideDir, run);
     const requestsByCustomId = {};
     const submissions = [];
@@ -2119,6 +2285,12 @@ export async function runBroadsideSubmit(cwd, apiKey, opts = {}) {
     }
     await Promise.allSettled(submissions);
     await persistBroadsideRun(broadsideDir, run);
+    // What the provider just said about each model's batch endpoint outlives
+    // the run: the `models` action reads it back (#141).
+    await recordBatchEndpoints(broadsideDir, lensIds
+        .map((lensId) => run.batches[lensId])
+        .filter((entry) => Boolean(entry) && entry.status !== "skipped")
+        .map((entry) => ({ model: entry.model ?? model, batchId: entry.batchId, error: entry.error })));
     // 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
@@ -2364,8 +2536,13 @@ function parseTriageItems(content) {
 export async function runBroadsideCollect(cwd, apiKey, opts = {}) {
     const broadsideDir = broadsideDirFor(cwd);
     const state = await loadBroadsideState(broadsideDir);
-    const run = state.runs[state.runs.length - 1];
+    const run = opts.runId ? state.runs.find((candidate) => candidate.id === opts.runId) : state.runs[state.runs.length - 1];
     if (!run) {
+        if (opts.runId) {
+            const known = state.runs.map((candidate) => candidate.id);
+            throw new Error(`No Broad-Side run with id ${opts.runId}. ` +
+                (known.length > 0 ? `Recorded runs: ${known.join(", ")}.` : "No runs are recorded; call codecarto_broadside with action 'submit' first."));
+        }
         throw new Error("No Broad-Side run recorded. Call codecarto_broadside with action 'submit' first.");
     }
     const runDir = join(broadsideDir, run.outputDir);
@@ -2386,7 +2563,7 @@ export async function runBroadsideCollect(cwd, apiKey, opts = {}) {
             lensOutcomes[lensId] = { status: entry?.status ?? "failed", resultCount: 0 };
             continue;
         }
-        if (["completed", "failed", "expired", "cancelled", "auth-failed", "skipped", "rejected"].includes(entry.status)) {
+        if (BROADSIDE_TERMINAL_ENTRY_STATUSES.includes(entry.status)) {
             totalCost += entry.cost ?? 0;
             resultCount += entry.resultCount ?? 0;
             lensOutcomes[lensId] = { status: entry.status, cost: entry.cost, resultCount: entry.resultCount };
@@ -2419,7 +2596,19 @@ export async function runBroadsideCollect(cwd, apiKey, opts = {}) {
             truncatedCount += truncated;
             totalCost += cost ?? 0;
             await writeFile(join(runDir, `raw-${lensId}.json`), `${JSON.stringify(batch, null, "\t")}\n`, "utf8");
-            lensOutcomes[lensId] = { status, cost: entry.cost, resultCount: entry.resultCount, truncated };
+            // A batch can complete with every request failed — the account's
+            // concurrent-job quota filling after acceptance does exactly this.
+            // The per-request errors are on disk as `<id>.error.json`, but a
+            // lens reporting "completed, 0 result(s)" with the reason buried
+            // there read as an empty repository rather than a refused run.
+            const results = Array.isArray(batch.results) ? batch.results : [];
+            const failed = results.filter((r) => r.error && extractContent(r) === null);
+            const allFailed = stored.length === 0 && failed.length > 0
+                ? `all ${failed.length} request(s) failed: ${explainBatchError(failed[0].error)}`
+                : null;
+            if (allFailed)
+                entry.error = allFailed;
+            lensOutcomes[lensId] = { status, cost: entry.cost, resultCount: entry.resultCount, truncated, ...(allFailed && { error: allFailed }) };
         }
         else {
             // Every non-completed outcome still has to reach the report.
@@ -2431,7 +2620,7 @@ export async function runBroadsideCollect(cwd, apiKey, opts = {}) {
             // indistinguishable in the output from one that was never requested.
             if (batch.error)
                 entry.error = batch.error;
-            const error = describeBatchError(batch.error);
+            const error = explainBatchError(batch.error);
             lensOutcomes[lensId] = { status, cost: entry.cost, resultCount: entry.resultCount, ...(error && { error }) };
         }
         await persistBroadsideRun(broadsideDir, run);
@@ -2439,9 +2628,19 @@ export async function runBroadsideCollect(cwd, apiKey, opts = {}) {
     // #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
     // coverage the first pass lost to a max_tokens cutoff, not to loop forever.
+    //
+    // All bumped requests for one model go out as ONE batch, and the batches
+    // (one per model, since a batch carries a single model) are polled
+    // together against the shared deadline. Each truncated slice used to be
+    // submitted and polled to terminal before the next was submitted, so a
+    // model that truncated 11 of 13 slices turned a five-minute collect into
+    // eleven sequential round trips — the serialization #136 removed from the
+    // lens pass, still present here (#206). Grouping also keeps the retry to
+    // one job per model against OpenRouter's 16-concurrent-job quota.
     let retriedCount = 0;
     if (opts.retryTruncated !== false && truncatedCount > 0) {
         const requestsByCustomId = await loadStoredRequests(runDir);
+        const byModel = new Map();
         for (const stored of allLensResults) {
             if (!stored.truncated)
                 continue;
@@ -2458,42 +2657,57 @@ export async function runBroadsideCollect(cwd, apiKey, opts = {}) {
             const bumpedMax = lensCap ? Math.min(previousMax * 2, lensCap) : previousMax * 2;
             if (bumpedMax <= previousMax)
                 continue; // already at the ceiling
-            const bumped = {
-                ...original,
-                body: { ...original.body, max_tokens: bumpedMax },
-            };
+            const group = byModel.get(lensModel) ?? { requests: [], slices: new Map() };
+            group.requests.push({ ...original, body: { ...original.body, max_tokens: bumpedMax } });
+            group.slices.set(stored.customId, stored);
+            byModel.set(lensModel, group);
+        }
+        // Submit every group, then poll whatever was accepted, together.
+        const submitted = [];
+        for (const [model, group] of byModel) {
             try {
-                const { batchId, error } = await submitBatch([bumped], apiKey, opts.fetcher, lensModel);
-                if (error)
+                const { batchId, error } = await submitBatch(group.requests, apiKey, opts.fetcher, model);
+                if (!error && batchId)
+                    submitted.push({ model, batchId });
+            }
+            catch {
+                // A retry batch that fails to submit leaves its slices' original
+                // truncated results in place — nothing is lost.
+            }
+        }
+        const polled = await pollBatchesConcurrently(submitted.map(({ model, batchId }) => ({ lensId: `retry:${model}`, batchId })), apiKey, {
+            // 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()),
+            fetcher: opts.fetcher,
+            onStatus: opts.onStatus,
+        });
+        for (const { model, batchId } of submitted) {
+            const batch = polled.get(batchId);
+            if (!batch || batch.status !== "completed")
+                continue;
+            const group = byModel.get(model);
+            const usage = (batch.usage ?? {});
+            totalCost += typeof usage.cost === "number" ? usage.cost : 0;
+            const results = Array.isArray(batch.results) ? batch.results : [];
+            for (const result of results) {
+                const stored = group.slices.get(String(result.custom_id ?? ""));
+                if (!stored)
                     continue;
-                const batch = await pollBatchUntilTerminal(batchId, apiKey, {
-                    // 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,
-                });
-                if (batch.status !== "completed")
+                const content = extractContent(result);
+                if (content === null)
                     continue;
-                const results = Array.isArray(batch.results) ? batch.results : [];
-                const content = results.length > 0 ? extractContent(results[0]) : null;
-                if (content === null || parseLensJson(content) === null)
-                    continue; // still no good
-                const usage = (batch.usage ?? {});
-                totalCost += typeof usage.cost === "number" ? usage.cost : 0;
                 const parsed = parseLensJson(content);
+                if (parsed === null)
+                    continue; // still no good
                 await writeFile(join(runDir, `${sanitizeId(stored.customId)}.json`), `${JSON.stringify(parsed, null, "\t")}\n`, "utf8");
                 await writeFile(join(runDir, `${sanitizeId(stored.customId)}.md`), renderFindingsMarkdown(content), "utf8");
                 stored.content = content;
                 stored.truncated = false;
                 retriedCount += 1;
             }
-            catch {
-                // A retry that fails to submit/poll leaves the original
-                // truncated result in place — nothing is lost.
-            }
         }
         truncatedCount = allLensResults.filter((s) => s.truncated).length;
         for (const [lensId, outcome] of Object.entries(lensOutcomes)) {
@@ -2526,7 +2740,7 @@ export async function runBroadsideCollect(cwd, apiKey, opts = {}) {
     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);
+            return entry && BROADSIDE_TERMINAL_ENTRY_STATUSES.includes(entry.status);
         });
         if (allTerminal && (postPassUnfinished(run.synthesis) || postPassUnfinished(run.triage))) {
             const findingsText = allLensResults
@@ -2638,7 +2852,7 @@ export async function runBroadsideCollect(cwd, apiKey, opts = {}) {
     }
     const terminal = run.lenses.every((lensId) => {
         const entry = run.batches[lensId];
-        return entry && ["completed", "failed", "expired", "cancelled", "auth-failed", "skipped", "rejected"].includes(entry.status);
+        return entry && BROADSIDE_TERMINAL_ENTRY_STATUSES.includes(entry.status);
     });
     run.status = terminal ? (resultCount > 0 ? "completed" : "failed") : "partial";
     run.totalCost = totalCost;
@@ -2777,7 +2991,11 @@ export function estimateSubmitText(result, lenses) {
             continue;
         const status = entry.batchId ? `batch ${entry.batchId}` : entry.status;
         const override = entry.model ? ` on ${entry.model}` : "";
-        lines.push(`  ${lens.name}: ${status} (${entry.requests} request(s), ~$${entry.estimatedCost.toFixed(4)})${override}`);
+        // A rejected lens says why: the message is the only way to tell a
+        // catalog id with no batch endpoint from a full job quota, and both
+        // used to read as a bare "rejected".
+        const reason = !entry.batchId && entry.error ? ` — ${explainBatchError(entry.error)}` : "";
+        lines.push(`  ${lens.name}: ${status} (${entry.requests} request(s), ~$${entry.estimatedCost.toFixed(4)})${override}${reason}`);
     }
     if (result.repo) {
         const head = result.repo.sourceHead ? ` at ${result.repo.sourceHead.slice(0, 8)}${result.repo.sourceDirty ? " (dirty)" : ""}` : "";
@@ -2814,8 +3032,15 @@ export function estimateSubmitText(result, lenses) {
     return lines.join("\n");
 }
 export function modelsText(entries, opts) {
+    const endpoints = opts.endpoints ?? {};
     const lines = [
         `Batch models on OpenRouter (${entries.length}, cheapest first).`,
+        // The catalog over-reports: it returns a `:batch` id for models whose
+        // Batch API refuses the job, with nothing in the entry to tell them
+        // apart (#141). Say so before the table, not after it.
+        "Advisory: this is the catalog's list of :batch ids, not a list of working batch endpoints. Some ids are refused at submit " +
+            "(\"does not have a :batch endpoint\"), at no cost. Rows tagged [no batch endpoint …] or [batch OK …] carry what this " +
+            "repository's own submits found; an untagged row has not been tried here.",
         "",
         "id | $/M in | $/M out | ctx | max out | structured | coding idx",
     ];
@@ -2835,12 +3060,21 @@ export function modelsText(entries, opts) {
         const out = entry.maxCompletionTokens ? `${(entry.maxCompletionTokens / 1024).toFixed(0)}k` : "?";
         const tag = entry.id === opts.defaultModel ? "  (default)" : "";
         const exp = entry.expirationDate ? "  [deprecated]" : "";
-        lines.push(`${entry.id}${tag}${exp} | ${entry.inputPerM.toFixed(3)} | ${entry.outputPerM.toFixed(3)} | ${ctx} | ${out} | ${structured} | ${coding}`);
+        const record = endpoints[entry.id];
+        const seen = record
+            ? record.status === "rejected"
+                ? `  [no batch endpoint, refused ${record.at.slice(0, 10)}]`
+                : `  [batch OK ${record.at.slice(0, 10)}]`
+            : "";
+        lines.push(`${entry.id}${tag}${exp}${seen} | ${entry.inputPerM.toFixed(3)} | ${entry.outputPerM.toFixed(3)} | ${ctx} | ${out} | ${structured} | ${coding}`);
     }
     if (opts.benchmarks?.meta.as_of) {
         lines.push("", `Benchmarks: Artificial Analysis coding index (as of ${String(opts.benchmarks.meta.as_of)}).`);
     }
-    lines.push("", "Set the batch model in .codecarto/broadside/config.yaml (model key). Higher coding index ≠ better scout: precision, context, and structured-output support matter most here.");
+    lines.push("", "Choose with the model parameter (--model= on Pi) for one run, lens_models (--lens-model=LENS:ID) per lens, or the model key in " +
+        ".codecarto/broadside/config.yaml for the repository. Higher coding index ≠ better scout: precision, context, structured-output " +
+        "support, and whether the model spends its output budget reasoning (see reasoning: in config.yaml) matter most here. " +
+        "A refused submit costs nothing, so probe an untried model on one lens first.");
     return lines.join("\n");
 }
 /** One line of a batch's error field, whatever shape the provider gave it. */
@@ -2853,6 +3087,15 @@ function describeBatchError(error) {
         const message = error.message;
         if (typeof message === "string" && message)
             return message.slice(0, 300);
+        // OpenRouter wraps a submit refusal as `{ error: { message } }`.
+        const nested = error.error;
+        if (nested && typeof nested === "object") {
+            const inner = nested.message;
+            if (typeof inner === "string" && inner)
+                return inner.slice(0, 300);
+        }
+        if (typeof nested === "string" && nested)
+            return nested.slice(0, 300);
         try {
             return JSON.stringify(error).slice(0, 300);
         }
@@ -2862,6 +3105,30 @@ function describeBatchError(error) {
     }
     return String(error);
 }
+/**
+ * A provider refusal plus what to do about it, for the two refusals a batch
+ * run meets in practice and cannot fix by itself (#141):
+ *
+ * - `Model '<id>' does not have a :batch endpoint.` — the catalog advertises a
+ *   `:batch` id that OpenRouter runs no batch endpoint for. Nothing in the
+ *   catalog distinguishes these; the `models` action marks ids this
+ *   repository has seen refused.
+ * - `job-submission-count … in use: 16, quota: 16` — the per-account limit
+ *   on concurrent batch jobs. Broad-Side submits one job per lens, so a few
+ *   runs in flight on the same key fill it; the refusal costs nothing.
+ */
+export function explainBatchError(error) {
+    const message = describeBatchError(error);
+    if (!message)
+        return null;
+    if (NO_BATCH_ENDPOINT_RE.test(message)) {
+        return `${message} — the catalog lists this id, but OpenRouter runs no batch endpoint for it. Nothing was charged; pick another model (the models action marks ids this repository has seen refused).`;
+    }
+    if (BATCH_QUOTA_RE.test(message)) {
+        return `${message} — OpenRouter's per-account limit on concurrent batch jobs is full. Broad-Side submits one job per lens, so a few runs in flight on this key (in any repository) fill it. Nothing was charged; collect or wait out the runs in flight, then re-submit.`;
+    }
+    return message;
+}
 export function collectResultText(result) {
     const lines = [
         `Broad-Side run ${result.runId}: ${result.status}`,