codecartographer-pi 0.21.0 → 0.22.0

package/.codecarto/broadside/SKILL.md

@@ -108,7 +108,14 @@ architecture map. Each override is priced, capability-checked, and clamped like
 the default, the submit estimate breaks cost out per lens, and `run-meta.json`
 records which lens ran on what. No stronger default is shipped: which model is
 worth the money depends on the repository and the budget, so compare with the
-`models` action and decide.
+`models` action and decide — for one run with the `model` and `lens_models`
+parameters (Pi: `--model=ID`, `--lens-model=LENS:ID`), or here for the
+repository. The `models` listing is advisory: OpenRouter's catalog returns a
+`:batch` id for some models its Batch API refuses (`does not have a :batch
+endpoint`), at no cost, and nothing in the catalog tells them apart. The
+listing tags the ids this repository's own submits have seen accepted or
+refused (`broadside/batch-endpoints.json`), and a refused lens says why in the
+submit report.
 
 Every run knob — `incremental`, `retry_truncated`, `include_synthesis`,
 `include_triage`, `wait_seconds` — also has a repository default under the same

package/.codecarto/broadside/config.yaml

@@ -54,10 +54,18 @@
 #      Nothing in the catalog distinguishes them. Every Anthropic and OpenAI
 #      batch id tried so far is rejected this way; Google and DeepSeek work.
 #      A rejected batch costs nothing, so probe a candidate on one lens before
-#      relying on it.
+#      relying on it: `codecarto_broadside {action: "submit", lenses:
+#      ["architecture"], model: "<id>"}` (Pi: `/codecarto-broadside architecture
+#      --model=<id>`). Submits remember the answer in batch-endpoints.json next
+#      to this file, and the `models` listing tags each id accordingly.
 #   2. A reasoning-capable model spends its output budget thinking, and the
 #      thinking is billed at the full output rate. See `reasoning:` below.
 #
+# The same two keys are submit parameters for one run — `model` and
+# `lens_models` on codecarto_broadside, `--model=ID` and `--lens-model=LENS:ID`
+# on /codecarto-broadside — and a lens set both there and here takes the
+# parameter's.
+#
 # lens_models:
 #   security: deepseek/deepseek-v4-pro-0813:batch
 #   defect: deepseek/deepseek-v4-pro-0813:batch

package/.codecarto/workflow/scaffold-version.yaml

@@ -3,4 +3,4 @@
 # workspace's framework-owned files (GUIDE.md, templates/, workflow/ pipelines
 # and VALIDATE.md) predate the running release. Written at release time and
 # copied verbatim by init — never edit by hand.
-scaffold_version: 0.21.0
+scaffold_version: 0.22.0

package/README.md

@@ -398,9 +398,9 @@ codecarto_broadside {cwd, action: "collect"}                  # poll, save, synt
 
 Submit and collect are separate because batch jobs routinely take tens of minutes; collect is resumable and picks up whatever is still in flight (`wait_seconds: 0`, the default, polls once and returns). Submit prices the run from the collected file sizes against the model's live per-token pricing (cached 24h) and refuses when the estimate exceeds `max_cost` — $1.00 unless the config or the call sets another value, `0` for no limit — unless `force: true` is passed — a pre-flight estimate, not a runtime stop. Actual spend lands in each run's `run-meta.json`.
 
-Repository defaults live in `.codecarto/broadside/config.yaml` (`model`, `api_key`, `default_lenses`, `max_cost`, `pricing` overrides, `lens_models`, `incremental`, `retry_truncated`, `include_synthesis`, `include_triage`, `wait_seconds`); an explicit tool parameter always wins. `lens_models` routes individual lenses to their own batch model — a stronger model changes security and defect findings far more than it changes an architecture map — and each override is priced, capability-checked, and clamped exactly like the default, with the estimate broken out per lens so a mixed-model run cannot be approved without seeing which lens costs what. CodeCartographer ships no stronger default: which model earns its price depends on your repository and budget, so compare candidates with the `models` action and choose. `codecarto_skill {cwd, name: "broadside"}` returns the reading guide for a completed run, and unlike post-pipeline skills it is not gated on a finished pipeline.
+Repository defaults live in `.codecarto/broadside/config.yaml` (`model`, `api_key`, `default_lenses`, `max_cost`, `pricing` overrides, `lens_models`, `incremental`, `retry_truncated`, `include_synthesis`, `include_triage`, `wait_seconds`); an explicit tool parameter always wins. `lens_models` routes individual lenses to their own batch model — a stronger model changes security and defect findings far more than it changes an architecture map — and each override is priced, capability-checked, and clamped exactly like the default, with the estimate broken out per lens so a mixed-model run cannot be approved without seeing which lens costs what. CodeCartographer ships no stronger default: which model earns its price depends on your repository and budget, so compare candidates with the `models` action and choose — for one run with the `model` and `lens_models` parameters (Pi: `--model=ID`, `--lens-model=LENS:ID`), or for the repository in `config.yaml`. The `models` listing is advisory: OpenRouter's catalog returns a `:batch` id for some models its Batch API then refuses (`does not have a :batch endpoint`), at no cost, and nothing in the catalog tells them apart — so the listing tags the ids this repository's own submits have seen accepted or refused, and a refused lens says why in the submit report. `codecarto_skill {cwd, name: "broadside"}` returns the reading guide for a completed run, and unlike post-pipeline skills it is not gated on a finished pipeline.
 
-On the Pi extension the same run is `/codecarto-broadside [submit|collect|status|models] [lenses…]`, with tab-completion for actions and lens names and live per-lens progress while batches poll. The two surfaces differ in one deliberate place: MCP cannot ask a human, so it refuses a run over `max_cost` until you pass `force`; Pi shows the per-lens breakdown and asks, and your approval *is* the force flag. Neither surface takes an API key as a command argument — a key typed into a slash command lands in the session transcript.
+On the Pi extension the same run is `/codecarto-broadside [submit|collect|status|models] [lenses…] [--model=ID] [--lens-model=LENS:ID]`, with tab-completion for actions, lens names, and flags and live per-lens progress while batches poll. The two surfaces differ in one deliberate place: MCP cannot ask a human, so it refuses a run over `max_cost` until you pass `force`; Pi shows the per-lens breakdown and asks, and your approval *is* the force flag. Neither surface takes an API key as a command argument — a key typed into a slash command lands in the session transcript.
 
 Broad-Side needs runtime code, so firing a run is an executable-surface feature: Pi and MCP have it, the pure drop-in template does not (it carries only the reading guide).
 

package/agent-skill/codecartographer/references/broadside.md

@@ -82,6 +82,16 @@ Two more economies worth knowing:
   conventions is usually a better trade than raising the model for everything.
   Overrides are priced and capability-checked individually, and the estimate
   breaks cost out per lens.
+- `model` and `lens_models` are also submit parameters (Pi: `--model=ID`,
+  `--lens-model=LENS:ID`), for one run without editing the file. Choose from
+  `action: "models"`, and read that listing as advisory: OpenRouter's catalog
+  returns a `:batch` id for some models its Batch API then refuses (`does not
+  have a :batch endpoint`) — free, reported on the lens with the reason, and
+  remembered, so the listing tags ids this repository has seen accepted or
+  refused. Probe an untried model on one lens before a six-lens run. A
+  `job-submission-count` refusal is the account's concurrent-job quota (one
+  job per lens fills it fast across runs); collect or wait out what is in
+  flight, then re-submit.
 
 ## Reading a run
 

package/dist/core/broadside.d.ts

@@ -11,6 +11,13 @@ export declare const BROADSIDE_OUTPUT_PRICE_PER_M = 1.875;
 export declare const BROADSIDE_MODELS_URL = "https://openrouter.ai/api/v1/models";
 export declare const BROADSIDE_BENCHMARKS_URL = "https://openrouter.ai/api/v1/benchmarks";
 export declare 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 declare const BROADSIDE_ENDPOINTS_FILE = "batch-endpoints.json";
 export declare const BROADSIDE_CATALOG_CACHE_TTL_MS: number;
 export declare const BROADSIDE_LENS_IDS: readonly ["architecture", "api", "security", "defect", "conventions", "porting"];
 export type BroadsideLensId = (typeof BROADSIDE_LENS_IDS)[number];
@@ -539,6 +546,26 @@ export declare function loadBroadsideConfig(broadsideDir: string): Promise<Broad
 export declare function defaultBroadsideConfig(): BroadsideConfig;
 /** The catalog cache schema this build writes; a file from another is not read. */
 export declare const BROADSIDE_CATALOG_CACHE_SCHEMA = 3;
+/** One model's most recent submit outcome, as remembered in {@link BROADSIDE_ENDPOINTS_FILE}. */
+export type BatchEndpointRecord = {
+    status: "accepted" | "rejected";
+    /** ISO timestamp of the submit that produced this record. */
+    at: string;
+    /** The provider's refusal, for a rejected endpoint. */
+    error?: string;
+};
+export declare function readBatchEndpoints(broadsideDir: string): Promise<Record<string, BatchEndpointRecord>>;
+/**
+ * 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 declare function recordBatchEndpoints(broadsideDir: string, outcomes: Array<{
+    model: string;
+    batchId: string;
+    error?: unknown;
+}>): Promise<void>;
 export declare function builtInCatalogEntry(model: string): CatalogEntry | null;
 export declare function builtInPricing(model: string): ModelPricing | null;
 export declare function resolveCatalogEntry(broadsideDir: string, config: BroadsideConfig, model: string, apiKey: string, fetcher?: FetchLike): Promise<BroadsideCatalogResult>;
@@ -552,6 +579,8 @@ export declare function listBatchModels(broadsideDir: string, config: BroadsideC
     source: string;
     benchmarks: CodingBenchmarks | null;
     defaultModel: string;
+    /** This repository's remembered submit outcomes per model, from {@link BROADSIDE_ENDPOINTS_FILE}. */
+    endpoints: Record<string, BatchEndpointRecord>;
 }>;
 export type FetchLike = (url: string, init: Record<string, unknown>) => Promise<Response>;
 export declare function submitBatch(batchRequests: BatchRequest[], apiKey: string, fetcher?: FetchLike, model?: string): Promise<{
@@ -602,6 +631,12 @@ export declare function runBroadsideSubmit(cwd: string, apiKey: string, opts?: {
     lenses?: BroadsideLensId[];
     fetcher?: FetchLike;
     model?: string;
+    /**
+     * Per-lens model overrides for this run, layered over config.yaml's
+     * `lens_models`: a lens named here runs on this model, a lens named only
+     * in the file runs on the file's, and the rest run on `model` (#141).
+     */
+    lensModels?: Partial<Record<BroadsideLensId, string>>;
     /** Approximate run expense limit in USD; 0 means no limit. */
     maxCost?: number;
     /** Submit even when the estimate exceeds maxCost. */
@@ -673,7 +708,21 @@ export declare function estimateSubmitText(result: BroadsideSubmitResult, lenses
 export declare function modelsText(entries: CatalogEntry[], opts: {
     benchmarks: CodingBenchmarks | null;
     defaultModel: string;
+    endpoints?: Record<string, BatchEndpointRecord>;
 }): string;
+/**
+ * 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 declare function explainBatchError(error: unknown): string | null;
 export declare function collectResultText(result: BroadsideCollectResult): string;
 export declare function statusText(state: BroadsideStateFile): string;
 export {};

package/dist/core/broadside.js

@@ -65,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",
@@ -1621,6 +1628,67 @@ 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)
@@ -1843,7 +1911,8 @@ export async function listBatchModels(broadsideDir, config, apiKey, opts = {}) {
         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
@@ -2001,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);
@@ -2215,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
@@ -2520,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.
@@ -2532,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);
@@ -2540,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;
@@ -2559,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)) {
@@ -2878,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)" : ""}` : "";
@@ -2915,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",
     ];
@@ -2936,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. */
@@ -2954,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);
         }
@@ -2963,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}`,

package/dist/extensions/codecarto/broadside-flags.d.ts

@@ -18,11 +18,15 @@ export interface BroadsideFlags {
     waitSeconds?: number;
     /** For collect: the run to collect instead of the most recent (#268). */
     runId?: string;
+    /** For submit: the run's batch model, replacing config.yaml's (#141). */
+    model?: string;
+    /** For submit: per-lens model overrides, layered over config.yaml's (#141). */
+    lensModels?: Partial<Record<BroadsideLensId, string>>;
     benchmarks: boolean;
     unknown: string[];
     /** Set on an invalid combination. The caller surfaces it as an error. */
     error?: string;
 }
 /** Every token the completer offers, in the order it offers them. */
-export declare const KNOWN_BROADSIDE_TOKENS: readonly ["submit", "collect", "status", "models", "architecture", "api", "security", "defect", "conventions", "porting", "--incremental", "--no-incremental", "--max-cost=", "--wait=", "--run=", "--no-synthesis", "--no-triage", "--no-retry-truncated", "--benchmarks"];
+export declare const KNOWN_BROADSIDE_TOKENS: readonly ["submit", "collect", "status", "models", "architecture", "api", "security", "defect", "conventions", "porting", "--incremental", "--no-incremental", "--max-cost=", "--wait=", "--run=", "--model=", "--lens-model=", "--no-synthesis", "--no-triage", "--no-retry-truncated", "--benchmarks"];
 export declare function parseBroadsideFlags(args: string): BroadsideFlags;

package/dist/extensions/codecarto/broadside-flags.js

@@ -14,6 +14,11 @@
 //   --max-cost=N           --no-retry-truncated
 //   --wait=SECONDS         --benchmarks (models only)
 //   --run=ID (collect only: an older run, as listed by status)
+//   --model=ID (submit only: the run's batch model, as listed by models)
+//   --lens-model=LENS:ID (submit only, repeatable: one lens on its own model)
+//
+// A model id itself contains a colon (`vendor/name:batch`), so --lens-model
+// splits on the first colon only: `security:deepseek/deepseek-v4-pro:batch`.
 //
 // --incremental has a spelled-out negative because the value is tri-state:
 // absent defers to config.yaml, so a repository that set `incremental: true`
@@ -36,6 +41,8 @@ export const KNOWN_BROADSIDE_TOKENS = [
     "--max-cost=",
     "--wait=",
     "--run=",
+    "--model=",
+    "--lens-model=",
     "--no-synthesis",
     "--no-triage",
     "--no-retry-truncated",
@@ -115,6 +122,32 @@ export function parseBroadsideFlags(args) {
             result.runId = value || undefined;
             continue;
         }
+        if (token.startsWith("--model=")) {
+            const value = token.slice("--model=".length).trim();
+            // An empty value is a mistyped selection, not "use the default":
+            // the command is about to spend money on whichever model wins.
+            if (!value)
+                result.error ??= "--model= needs an OpenRouter batch model id (see /codecarto-broadside models).";
+            result.model = value || undefined;
+            continue;
+        }
+        if (token.startsWith("--lens-model=")) {
+            const value = token.slice("--lens-model=".length).trim();
+            const colon = value.indexOf(":");
+            const lensId = colon > 0 ? value.slice(0, colon).trim() : "";
+            const modelId = colon > 0 ? value.slice(colon + 1).trim() : "";
+            if (!lensId || !modelId) {
+                result.error ??= `--lens-model needs LENS:MODEL, e.g. --lens-model=security:vendor/name:batch (got "${value}").`;
+            }
+            else if (!BROADSIDE_LENS_IDS.includes(lensId)) {
+                result.error ??= `--lens-model: unknown lens "${lensId}". Lenses: ${BROADSIDE_LENS_IDS.join(", ")}.`;
+            }
+            else {
+                result.lensModels ??= {};
+                result.lensModels[lensId] = modelId;
+            }
+            continue;
+        }
         result.unknown.push(token);
     }
     // Flags that only mean something for one action are refused rather than
@@ -137,5 +170,11 @@ export function parseBroadsideFlags(args) {
     if (result.runId !== undefined && result.action !== "collect") {
         result.error ??= `--run is only meaningful for collect (got action "${result.action}").`;
     }
+    if (result.model !== undefined && result.action !== "submit") {
+        result.error ??= `--model is only meaningful for submit (got action "${result.action}").`;
+    }
+    if (result.lensModels !== undefined && result.action !== "submit") {
+        result.error ??= `--lens-model is only meaningful for submit (got action "${result.action}").`;
+    }
     return result;
 }

package/dist/extensions/codecarto/index.js

@@ -1000,7 +1000,7 @@ export default function codeCartographerExtension(pi) {
         },
     });
     pi.registerCommand("codecarto-broadside", {
-        description: "Batch reconnaissance (Broad-Side): /codecarto-broadside [submit|collect|status|models] [lenses…] [flags]",
+        description: "Batch reconnaissance (Broad-Side): /codecarto-broadside [submit|collect|status|models] [lenses…] [--model=ID] [--lens-model=LENS:ID] [flags]",
         getArgumentCompletions: (prefix) => {
             const items = KNOWN_BROADSIDE_TOKENS
                 .filter((value) => value.startsWith(prefix))
@@ -1077,10 +1077,10 @@ export default function codeCartographerExtension(pi) {
             if (flags.action === "models") {
                 notifyCtx(ctx, "Fetching the OpenRouter batch-model catalog…", "info");
                 try {
-                    const { entries, benchmarks } = await listBatchModels(broadsideDir, config, apiKey, {
+                    const { entries, benchmarks, endpoints } = await listBatchModels(broadsideDir, config, apiKey, {
                         includeBenchmarks: flags.benchmarks,
                     });
-                    finish(modelsText(entries, { benchmarks, defaultModel: config.model }).split("\n"), `Broad-Side: ${entries.length} batch model${entries.length === 1 ? "" : "s"} listed`);
+                    finish(modelsText(entries, { benchmarks, defaultModel: config.model, endpoints }).split("\n"), `Broad-Side: ${entries.length} batch model${entries.length === 1 ? "" : "s"} listed`);
                 }
                 catch (error) {
                     notifyCtx(ctx, `Model catalog lookup failed: ${error instanceof Error ? error.message : String(error)}`, "error");
@@ -1117,7 +1117,11 @@ export default function codeCartographerExtension(pi) {
                 try {
                     submit = await runBroadsideSubmit(ctx.cwd, apiKey, {
                         lenses,
-                        model: config.model,
+                        // --model= and --lens-model= select for this run; the file's
+                        // values are the fallback, and core pre-flights either the
+                        // same way (#141).
+                        model: flags.model ?? config.model,
+                        lensModels: flags.lensModels,
                         maxCost: flags.maxCost ?? config.maxCost,
                         // `??`, not `||`: --no-incremental parses to false and must beat a
                         // config-set true, exactly as MCP's `incremental: false` does (#163).

package/dist/mcp-server/server.d.ts

@@ -245,6 +245,8 @@ export declare function handleBroadside(args: {
     force?: boolean;
     include_benchmarks?: boolean;
     incremental?: boolean;
+    model?: string;
+    lens_models?: Record<string, string>;
 }): Promise<{
     content: {
         type: "text";

package/dist/mcp-server/server.js

@@ -1079,15 +1079,19 @@ export async function handleBroadside(args) {
     const retryTruncated = args.retry_truncated ?? config.retryTruncated;
     const incremental = args.incremental ?? config.incremental;
     if (action === "models") {
-        const { entries, benchmarks } = await listBatchModels(broadsideDirFor(cwd), config, apiKey, {
+        const { entries, benchmarks, endpoints } = await listBatchModels(broadsideDirFor(cwd), config, apiKey, {
             includeBenchmarks: args.include_benchmarks === true,
         }).catch((error) => {
             throw new McpError(ErrorCode.InvalidRequest, error instanceof Error ? error.message : String(error));
         });
-        return textResult(modelsText(entries, { benchmarks, defaultModel: config.model }), {
+        return textResult(modelsText(entries, { benchmarks, defaultModel: config.model, endpoints }), {
             models: entries,
             defaultModel: config.model,
             benchmarkMeta: benchmarks?.meta ?? null,
+            // The catalog is advisory (#141): what this repository's submits
+            // learned about each id's batch endpoint rides alongside it.
+            catalogAdvisory: true,
+            endpoints,
         });
     }
     if (action === "submit") {
@@ -1105,9 +1109,34 @@ export async function handleBroadside(args) {
         // An explicit 0 is "no limit" (#231); absent falls back to config.yaml,
         // whose own default is BROADSIDE_DEFAULT_MAX_COST.
         const maxCost = typeof args.max_cost === "number" && args.max_cost >= 0 ? args.max_cost : config.maxCost;
+        // Model selection for one run (#141): `model` replaces the run default,
+        // `lens_models` layers per-lens overrides over config.yaml's. Both are
+        // pre-flighted by core exactly like the file's values — priced from the
+        // catalog, refused without structured-output support, clamped to the
+        // model's ceiling — so a wrong id fails before anything is submitted.
+        const model = typeof args.model === "string" && args.model.trim() ? args.model.trim() : config.model;
+        if (args.model !== undefined && !(typeof args.model === "string" && args.model.trim())) {
+            throw new McpError(ErrorCode.InvalidParams, "model must be a non-empty OpenRouter batch model id (see action 'models').");
+        }
+        const lensModels = {};
+        if (args.lens_models !== undefined) {
+            if (!args.lens_models || typeof args.lens_models !== "object" || Array.isArray(args.lens_models)) {
+                throw new McpError(ErrorCode.InvalidParams, "lens_models must be an object mapping lens ids to batch model ids.");
+            }
+            for (const [lensId, value] of Object.entries(args.lens_models)) {
+                if (!BROADSIDE_LENS_IDS.includes(lensId)) {
+                    throw new McpError(ErrorCode.InvalidParams, `lens_models: unknown lens "${lensId}". Valid: ${BROADSIDE_LENS_IDS.join(", ")}`);
+                }
+                if (typeof value !== "string" || !value.trim()) {
+                    throw new McpError(ErrorCode.InvalidParams, `lens_models.${lensId} must be a non-empty OpenRouter batch model id.`);
+                }
+                lensModels[lensId] = value.trim();
+            }
+        }
         const result = await runBroadsideSubmit(cwd, apiKey, {
             lenses,
-            model: config.model,
+            model,
+            lensModels,
             maxCost,
             force: args.force === true,
             incremental,
@@ -1516,6 +1545,15 @@ const TOOLS = [
                     type: "boolean",
                     description: "For action 'models': annotate each model with its Artificial Analysis coding index (extra API call; default false).",
                 },
+                model: {
+                    type: "string",
+                    description: "For submit: the OpenRouter batch model for this run (an id ending in :batch, as listed by action 'models'). Falls back to model in .codecarto/broadside/config.yaml, then the shipped default. Pre-flighted like the configured model: priced from the live catalog, refused without structured-output support, clamped to its completion ceiling. The models listing is advisory — some catalog ids have no batch endpoint and are refused at submit, at no cost; the listing tags ids this repository has already seen accepted or refused.",
+                },
+                lens_models: {
+                    type: "object",
+                    additionalProperties: { type: "string" },
+                    description: "For submit: per-lens model overrides for this run, e.g. {\"security\": \"deepseek/deepseek-v4-pro-0813:batch\"}. Keys are lens ids; a lens named here runs on that model, others on `model`. Layered over lens_models in .codecarto/broadside/config.yaml (a lens set in both takes the parameter's). Each override is priced, capability-checked, and clamped individually, and the estimate breaks cost out per lens.",
+                },
             },
             required: ["cwd", "action"],
         },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codecartographer-pi",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "mcpName": "io.github.HuginnIndustries/codecartographer",
   "description": "Turn an unfamiliar codebase into a validated reimplementation spec, then synthesize confirmed specs and a product vision into a traceable plan.",
   "type": "module",