codecartographer-pi 0.19.6 → 0.21.0

package/dist/core/broadside.js

@@ -31,11 +31,13 @@
 // 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";
 import { packagedWorkspaceDir } from "./workspace.js";
@@ -74,6 +76,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.
  *
@@ -102,6 +114,54 @@ export const BROADSIDE_MIN_REASONING_TOKENS = 512;
 export function defaultReasoningFor(maxTokens) {
     return { max_tokens: Math.max(BROADSIDE_MIN_REASONING_TOKENS, Math.floor(maxTokens * BROADSIDE_REASONING_BUDGET_FRACTION)) };
 }
+/**
+ * OpenRouter rejected the API key (HTTP 401/403). Thrown from the catalog
+ * lookup rather than swallowed into "could not price" or a silent built-in
+ * fallback: a run that cannot authenticate cannot submit either, and the
+ * message that reaches the user has to say so (#251).
+ */
+export class BroadsideAuthError extends Error {
+    httpStatus;
+    detail;
+    constructor(httpStatus, detail) {
+        super(`OpenRouter rejected the API key (HTTP ${httpStatus}${detail ? `: ${detail}` : ""}). ` +
+            "Check OPENROUTER_API_KEY, the api_key parameter, or api_key in .codecarto/broadside/config.yaml. Nothing was submitted.");
+        this.name = "BroadsideAuthError";
+        this.httpStatus = httpStatus;
+        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.") {
@@ -799,14 +859,23 @@ const SKIP_FILE_EXTENSIONS = new Set([
     ".model",
     ".bpe",
 ]);
+/**
+ * Manifest files and the languages each one can mean. `package.json` covers
+ * both TypeScript and JavaScript; which of the two a repository is comes from
+ * counting its source files, not from the manifest.
+ */
 const MANIFEST_CANDIDATES = [
-    ["go.mod", "go"],
-    ["package.json", "typescript"],
-    ["Cargo.toml", "rust"],
-    ["pyproject.toml", "python"],
-    ["setup.py", "python"],
-    ["requirements.txt", "python"],
+    ["go.mod", ["go"]],
+    ["package.json", ["typescript", "javascript"]],
+    ["Cargo.toml", ["rust"]],
+    ["pyproject.toml", ["python"]],
+    ["setup.py", ["python"]],
+    ["requirements.txt", ["python"]],
 ];
+/** The languages Broad-Side can scan; anything else is refused at submit. */
+export const BROADSIDE_LANGUAGES = ["go", "python", "rust", "typescript", "javascript"];
+/** Chars of the entry-point file and the manifest that ride in the architecture prompt (#249). */
+const REPO_INFO_FILE_CAP = 20_000;
 const SOURCE_SPECS = {
     go: { glob: "**/*.go", exts: [".go"] },
     python: { glob: "**/*.py", exts: [".py"] },
@@ -814,21 +883,32 @@ const SOURCE_SPECS = {
     typescript: { glob: "**/*.ts", exts: [".ts", ".tsx"] },
     javascript: { glob: "**/*.js", exts: [".js", ".jsx"] },
 };
+/**
+ * The files a run scans, and where they came from. Contents are always read
+ * from the working tree, so the list is the working tree's too: tracked files
+ * plus untracked ones git does not ignore, minus files deleted on disk. The
+ * list used to come from `git ls-tree HEAD`, so a run mixed the committed
+ * file list with uncommitted contents and never saw an untracked file (#248).
+ * A target that is not a git repository gets a bounded walk.
+ */
 async function listRepoFiles(targetDir) {
-    // git ls-tree is the fast path; fall back to a bounded walk for non-git trees.
     try {
-        const { stdout } = await execFileAsync("git", ["-C", targetDir, "ls-tree", "-r", "--name-only", "HEAD"], {
+        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,
         });
-        return stdout.split("\n").filter(Boolean);
+        const gone = new Set(deleted.stdout.split("\0").filter(Boolean));
+        const files = listed.stdout.split("\0").filter((path) => path && !gone.has(path));
+        return { files, snapshot: "working-tree" };
     }
     catch {
-        return walkFiles(targetDir, targetDir, 0, 30_000);
+        return { files: await walkFiles(targetDir, targetDir, 0, 30_000), snapshot: "walk" };
     }
 }
 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 {
@@ -837,7 +917,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 {
@@ -853,7 +933,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 {
@@ -872,7 +952,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))
@@ -892,25 +972,65 @@ async function walkFiles(rootDir, dir, depth, remaining) {
     }
     return out;
 }
-function detectLanguage(fileCounts, manifestPath) {
-    if (manifestPath) {
-        for (const [candidate, lang] of MANIFEST_CANDIDATES) {
-            if (manifestPath === candidate)
-                return lang;
+function sourceFileCount(language, fileCounts) {
+    return (SOURCE_SPECS[language]?.exts ?? []).reduce((sum, ext) => sum + (fileCounts[ext] ?? 0), 0);
+}
+/**
+ * The language the lenses scan as. The manifests present name the candidates
+ * (all of them, not the first one found: a Python service with a
+ * `package.json` for its docs tooling is not a TypeScript repository), and
+ * among candidates the one with the most source files wins; without a
+ * manifest, the language with the most source files; without any source
+ * file, `unknown` — which submit refuses rather than scanning nothing and
+ * paying for it (#250). Ties keep manifest order.
+ */
+function detectLanguage(fileCounts, manifestPaths) {
+    const candidates = [];
+    for (const [candidate, languages] of MANIFEST_CANDIDATES) {
+        if (!manifestPaths.includes(candidate))
+            continue;
+        for (const language of languages)
+            if (!candidates.includes(language))
+                candidates.push(language);
+    }
+    const pool = candidates.length > 0 ? candidates : [...BROADSIDE_LANGUAGES];
+    let best = null;
+    let bestCount = -1;
+    for (const language of pool) {
+        const count = sourceFileCount(language, fileCounts);
+        if (count > bestCount) {
+            best = language;
+            bestCount = count;
         }
     }
-    const counts = {
-        go: fileCounts[".go"] ?? 0,
-        python: fileCounts[".py"] ?? 0,
-        rust: fileCounts[".rs"] ?? 0,
-        typescript: (fileCounts[".ts"] ?? 0) + (fileCounts[".tsx"] ?? 0),
-        javascript: fileCounts[".js"] ?? 0,
-    };
-    const best = Object.entries(counts).sort((a, b) => b[1] - a[1])[0];
-    return best && best[1] > 0 ? best[0] : "unknown";
+    if (bestCount > 0)
+        return best;
+    // A manifest with no source files behind it still names the language;
+    // submit reports the empty count. No manifest and no source: unknown.
+    return candidates[0] ?? "unknown";
 }
-export async function collectRepoInfo(targetDir) {
-    const allFiles = await listRepoFiles(targetDir);
+/** Cut a file that rides whole in a prompt down to the cap, saying so (#249). */
+function capForPrompt(content, cap) {
+    if (content.length <= cap)
+        return content;
+    return `${content.slice(0, cap)}\n… [truncated: ${cap.toLocaleString()} of ${content.length.toLocaleString()} chars shown]\n`;
+}
+export async function collectRepoInfo(targetDir, opts = {}) {
+    const redact = opts.redact ?? true;
+    const { files: allFiles, snapshot } = await listRepoFiles(targetDir);
+    // Named credential stores are out of every lens (isSlurpable); listed here
+    // so the submit report can say so.
+    const secretFilesSkipped = allFiles.filter((path) => isSecretFile(path)).sort();
+    let redactedValues = 0;
+    // The entry point, manifest, and README ride in the architecture prompt
+    // as text, so they get the same pass the slices do (#252).
+    const clean = (text) => {
+        if (!redact)
+            return text;
+        const redaction = redactSecrets(text);
+        redactedValues += redaction.count;
+        return redaction.text;
+    };
     const fileCounts = {};
     for (const f of allFiles) {
         const slash = f.lastIndexOf("/");
@@ -923,25 +1043,37 @@ export async function collectRepoInfo(targetDir) {
     for (const [ext, n] of Object.entries(fileCounts).sort((a, b) => b[1] - a[1])) {
         sortedCounts[ext] = n;
     }
-    let manifest = null;
+    // Every manifest present counts toward language detection; the first one
+    // found is the one the architecture prompt shows.
+    const manifestPaths = [];
     for (const [candidate] of MANIFEST_CANDIDATES) {
-        const p = join(targetDir, candidate);
-        if (await pathExists(p)) {
-            try {
-                manifest = { path: candidate, content: await readFile(p, "utf8") };
-            }
-            catch {
-                manifest = null;
-            }
-            break;
+        if (await pathExists(join(targetDir, candidate)))
+            manifestPaths.push(candidate);
+    }
+    const language = detectLanguage(sortedCounts, manifestPaths);
+    // Show the manifest that belongs to the detected language when there is
+    // one, so a polyglot repo's prompt does not open with the other stack's file.
+    const manifestPath = manifestPaths.find((path) => MANIFEST_CANDIDATES.find(([candidate]) => candidate === path)?.[1].includes(language))
+        ?? manifestPaths[0]
+        ?? null;
+    let manifest = null;
+    if (manifestPath) {
+        try {
+            manifest = { path: manifestPath, content: capForPrompt(clean(await readFile(join(targetDir, manifestPath), "utf8")), REPO_INFO_FILE_CAP) };
+        }
+        catch {
+            manifest = null;
         }
     }
+    // Read whole and unbounded before, and then estimated at a flat 6,000
+    // chars: a large entry point shipped in full while the cap was checked
+    // against a number that had nothing to do with it (#249).
     let mainFile = "";
-    for (const candidate of ["main.go", "main.py", "src/main.rs", "src/index.ts", "index.ts"]) {
+    for (const candidate of ["main.go", "main.py", "src/main.rs", "src/index.ts", "index.ts", "src/index.js", "index.js"]) {
         const p = join(targetDir, candidate);
         if (await pathExists(p)) {
             try {
-                mainFile = await readFile(p, "utf8");
+                mainFile = capForPrompt(clean(await readFile(p, "utf8")), REPO_INFO_FILE_CAP);
             }
             catch {
                 mainFile = "";
@@ -953,16 +1085,18 @@ export async function collectRepoInfo(targetDir) {
     const readmePath = join(targetDir, "README.md");
     if (await pathExists(readmePath)) {
         try {
-            readmeFirst = (await readFile(readmePath, "utf8")).slice(0, 4000);
+            readmeFirst = clean((await readFile(readmePath, "utf8")).slice(0, 4000));
         }
         catch {
             readmeFirst = "";
         }
     }
     const fileTree = buildFileTree(allFiles);
-    const language = detectLanguage(sortedCounts, manifest?.path ?? null);
-    const sourceSpec = SOURCE_SPECS[language] ?? SOURCE_SPECS.go;
+    // An unknown language used to fall through to Go's globs, so the code
+    // lenses matched nothing and the run paid for empty batches (#250).
+    const sourceSpec = SOURCE_SPECS[language] ?? { glob: "", exts: [] };
     const name = targetDir.split(/[\\/]/).filter(Boolean).pop() ?? "repo";
+    const sourceFiles = allFiles.filter((path) => isSlurpable(path) && sourceSpec.exts.some((ext) => path.toLowerCase().endsWith(ext))).length;
     return {
         name,
         path: targetDir,
@@ -974,6 +1108,10 @@ export async function collectRepoInfo(targetDir) {
         fileCounts: sortedCounts,
         sourceGlob: sourceSpec.glob,
         sourceExts: sourceSpec.exts,
+        sourceFileCount: sourceFiles,
+        snapshot,
+        secretFilesSkipped,
+        redactedValues,
     };
 }
 function buildFileTree(allFiles, maxDepth = 3, maxLines = 200) {
@@ -1034,6 +1172,9 @@ function matchesAnyGlob(path, globs) {
     return false;
 }
 function isSlurpable(relPath) {
+    // A credential store is never a lens input, whatever its globs say (#252).
+    if (isSecretFile(relPath))
+        return false;
     const segments = relPath.split("/");
     for (const seg of segments) {
         if (SKIP_DIR_NAMES.has(seg))
@@ -1070,7 +1211,7 @@ function resolveSliceMode(lens, files, totalChars) {
     return totalChars > lens.maxChars ? "directory" : "none";
 }
 function collectLensFiles(allFiles, lens, info) {
-    const globs = lens.globsFor(info);
+    const globs = lens.globsFor(info).filter(Boolean);
     if (globs.length === 0)
         return [];
     const out = [];
@@ -1085,13 +1226,15 @@ function collectLensFiles(allFiles, lens, info) {
     }
     return out;
 }
-async function slurpFileList(targetDir, files, maxChars) {
+async function slurpFileList(targetDir, files, maxChars, redact = true) {
     const slices = [];
     let currentModule = "";
     let parts = [];
     let running = 0;
     let fileCount = 0;
     let filePaths = [];
+    let redactedValues = 0;
+    let redactedFiles = [];
     const flush = () => {
         if (parts.length === 0)
             return;
@@ -1101,20 +1244,38 @@ async function slurpFileList(targetDir, files, maxChars) {
             fileCount,
             chars: running,
             files: filePaths,
+            redactedValues,
+            redactedFiles,
         });
         parts = [];
         running = 0;
         fileCount = 0;
         filePaths = [];
+        redactedValues = 0;
+        redactedFiles = [];
     };
     for (const file of files) {
         let content = "";
         try {
             content = await readFile(join(targetDir, file.relPath), "utf8");
         }
-        catch {
+        catch (error) {
+            // The listing is the working tree's, so this is a race with a
+            // concurrent delete rather than a listed-but-deleted file; skip it.
+            if (error.code === "ENOENT")
+                continue;
             content = "[BINARY or UNREADABLE]";
         }
+        if (redact) {
+            // Before the slice is built, so the count and the chars the estimate
+            // sees are of what is actually sent (#252).
+            const redaction = redactSecrets(content);
+            if (redaction.count > 0) {
+                content = redaction.text;
+                redactedValues += redaction.count;
+                redactedFiles.push(file.relPath);
+            }
+        }
         const block = `=== ${file.relPath} ===\n${content}\n`;
         if (file.moduleName !== currentModule && parts.length > 0) {
             flush();
@@ -1134,12 +1295,13 @@ async function slurpFileList(targetDir, files, maxChars) {
     flush();
     return slices;
 }
-export async function gatherSlices(targetDir, lens, info) {
+export async function gatherSlices(targetDir, lens, info, opts = {}) {
+    const redact = opts.redact ?? true;
     if (lens.sliceBy === "none" && lens.globsFor(info).length === 0) {
         // Repo-info lens (architecture): the prompt is built from info alone.
         return [{ moduleName: "root", content: "", fileCount: 0, chars: 0, files: [] }];
     }
-    const allFiles = await listRepoFiles(targetDir);
+    const { files: allFiles } = await listRepoFiles(targetDir);
     const files = collectLensFiles(allFiles, lens, info);
     const totalChars = await sumFileSizes(targetDir, files);
     const mode = resolveSliceMode(lens, files, totalChars);
@@ -1147,9 +1309,9 @@ export async function gatherSlices(targetDir, lens, info) {
         // Whole-repo slice: one module named after the repo, so a small
         // repo produces a single request instead of one per directory.
         const single = files.map((f) => ({ ...f, moduleName: info.name }));
-        return slurpFileList(targetDir, single, lens.maxChars);
+        return slurpFileList(targetDir, single, lens.maxChars, redact);
     }
-    return slurpFileList(targetDir, files, lens.maxChars);
+    return slurpFileList(targetDir, files, lens.maxChars, redact);
 }
 async function sumFileSizes(targetDir, files) {
     let total = 0;
@@ -1199,7 +1361,12 @@ export function buildBatchRequest(lens, info, slice, index, sliceCount, model =
  *   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);
+    // With repo info, size each request from the user prompt that would be
+    // sent, which is what the architecture lens is made of: it used to be
+    // estimated at a flat 6,000 chars while the entry point, manifest, README
+    // excerpt and file tree it carries ran to whatever they ran to (#249).
+    // Without info, the slice content alone is what the old signature covered.
+    const sliceChars = slices.reduce((sum, s) => sum + (info ? lens.userPrompt(info, s.content, s.moduleName).length : 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
@@ -1247,15 +1414,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`.
@@ -1348,13 +1530,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)))
         : [];
@@ -1379,7 +1574,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,
@@ -1393,15 +1590,21 @@ export async function loadBroadsideConfig(broadsideDir) {
         includeSynthesis: flag("include_synthesis", true),
         includeTriage: flag("include_triage", true),
         waitSeconds: typeof raw.wait_seconds === "number" && raw.wait_seconds > 0 ? raw.wait_seconds : 0,
+        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;
     }
@@ -1409,6 +1612,11 @@ 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");
@@ -1488,31 +1696,51 @@ 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
+    // below: a 401 and a dead network used to read the same — "could not
+    // resolve per-token pricing" — or, for the default model, nothing at all.
     let live = null;
+    let catalogFailure = null;
     try {
         const resp = await fetcher(BROADSIDE_MODELS_URL, {
             method: "GET",
             headers: { Authorization: `Bearer ${apiKey}` },
             signal: AbortSignal.timeout(30_000),
         });
-        const data = (await resp.json());
-        const hit = (data.data ?? []).find((m) => String(m.id) === model);
-        if (hit)
-            live = parseCatalogEntry(hit);
+        if (resp.status === 401 || resp.status === 403) {
+            throw new BroadsideAuthError(resp.status, await responseDetail(resp));
+        }
+        if (resp.ok === false) {
+            catalogFailure = `the model catalog request failed (HTTP ${resp.status}${await responseDetail(resp).then((d) => (d ? `: ${d}` : ""))})`;
+        }
+        else {
+            const data = (await resp.json());
+            const hit = (data.data ?? []).find((m) => String(m.id) === model);
+            if (hit)
+                live = parseCatalogEntry(hit);
+            else
+                catalogFailure = `the model catalog has no entry for "${model}"`;
+        }
     }
-    catch {
+    catch (error) {
+        if (error instanceof BroadsideAuthError)
+            throw error;
         live = null;
+        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 };
     }
@@ -1521,10 +1749,37 @@ export async function resolveCatalogEntry(broadsideDir, config, model, apiKey, f
     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}". ` +
+    throw new Error(`Could not resolve per-token pricing for batch model "${model}": ${catalogFailure ?? "no catalog entry"}. ` +
         "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.");
 }
+/** A short, safe excerpt of an error response body for a message. */
+async function responseDetail(resp) {
+    try {
+        if (typeof resp.text === "function") {
+            const text = (await resp.text()).trim();
+            try {
+                const parsed = JSON.parse(text);
+                const message = typeof parsed?.error === "string" ? parsed.error : parsed?.error?.message;
+                if (typeof message === "string" && message)
+                    return message.slice(0, 200);
+            }
+            catch {
+                // not JSON; fall through to the raw excerpt
+            }
+            return text.replace(/\s+/g, " ").slice(0, 200);
+        }
+        if (typeof resp.json === "function") {
+            const parsed = (await resp.json());
+            const message = typeof parsed?.error === "string" ? parsed.error : parsed?.error?.message;
+            return typeof message === "string" ? message.slice(0, 200) : "";
+        }
+    }
+    catch {
+        // an unreadable body adds nothing to the message
+    }
+    return "";
+}
 export async function resolveModelPricing(broadsideDir, config, model, apiKey, fetcher = fetch) {
     const { source, entry } = await resolveCatalogEntry(broadsideDir, config, model, apiKey, fetcher);
     if (!entry)
@@ -1582,9 +1837,10 @@ 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 };
@@ -1618,7 +1874,17 @@ export async function fetchBatch(batchId, apiKey, fetcher = fetch) {
         headers: { Authorization: `Bearer ${apiKey}` },
         signal: AbortSignal.timeout(30_000),
     });
-    const data = (await resp.json());
+    let data;
+    try {
+        data = (await resp.json());
+    }
+    catch (error) {
+        // A gateway error page is not JSON. It used to throw out of here and
+        // be retried as if the network were down; keep the status instead.
+        data = { error: `non-JSON response (${error instanceof Error ? error.message : String(error)})` };
+    }
+    if (!data || typeof data !== "object")
+        data = { error: "empty response" };
     // Surface the HTTP status so the poller can bail fast on auth expiry
     // instead of retrying a dead key for the whole budget.
     data.http_status = resp.status;
@@ -1632,18 +1898,38 @@ 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;
     const fetcher = opts.fetcher ?? fetch;
+    // A poll that runs out of budget without one good response is not a slow
+    // batch. The last thing that went wrong rides on the timeout so the report
+    // can tell a dead network or a failing gateway from a batch still running.
+    let lastError = null;
+    let sawBatch = false;
+    const timedOut = () => ({
+        id: batchId,
+        status: "timeout",
+        ...(lastError && !sawBatch && { error: `no successful poll response; last error: ${lastError}` }),
+        ...(lastError && sawBatch && { last_error: lastError }),
+    });
     for (;;) {
         let batch;
         try {
             batch = await fetchBatch(batchId, apiKey, fetcher);
         }
-        catch {
+        catch (error) {
+            lastError = `fetch failed (${error instanceof Error ? error.message : String(error)})`;
             if (Date.now() >= deadline)
-                return { id: batchId, status: "timeout" };
+                return timedOut();
             await sleep(intervalMs);
             continue;
         }
@@ -1651,13 +1937,23 @@ export async function pollBatchUntilTerminal(batchId, apiKey, opts = {}) {
         if (httpStatus === 401 || httpStatus === 403) {
             return { id: batchId, status: "auth-failed", error: batch.error ?? batch };
         }
+        if (httpStatus >= 400) {
+            // A gateway or server error: retry within the budget, remembered.
+            const detail = typeof batch.error === "string" ? batch.error : JSON.stringify(batch.error ?? "");
+            lastError = `HTTP ${httpStatus}${detail ? ` (${detail.slice(0, 200)})` : ""}`;
+            if (Date.now() >= deadline)
+                return timedOut();
+            await sleep(intervalMs);
+            continue;
+        }
+        sawBatch = true;
         const status = String(batch.status ?? "unknown");
         const counts = (batch.request_counts ?? {});
         opts.onStatus?.(status, counts);
         if (status === "completed" || BROADSIDE_DEAD_BATCH_STATUSES.includes(status))
             return batch;
         if (Date.now() >= deadline)
-            return { id: batchId, status: "timeout" };
+            return timedOut();
         await sleep(intervalMs);
     }
 }
@@ -1684,7 +1980,6 @@ export async function pollBatchesConcurrently(entries, apiKey, opts = {}) {
 }
 // ---------- run orchestration ----------
 export async function runBroadsideSubmit(cwd, apiKey, opts = {}) {
-    const info = await collectRepoInfo(cwd);
     const lensIds = opts.lenses ?? BROADSIDE_LENS_IDS;
     const broadsideDir = broadsideDirFor(cwd);
     const model = opts.model ?? BROADSIDE_MODEL;
@@ -1693,6 +1988,19 @@ export async function runBroadsideSubmit(cwd, apiKey, opts = {}) {
     // structured-output support that not all batch models offer. Lenses may run
     // on different models (config `lens_models`), so each one is pre-flighted.
     const config = await loadBroadsideConfig(broadsideDir);
+    const redact = config.redactSecrets;
+    const info = await collectRepoInfo(cwd, { redact });
+    // Before pricing, before the network, before any state write: a run on a
+    // language the lenses cannot scan used to submit empty batches and pay for
+    // them (#250).
+    if (info.language === "unknown") {
+        throw new Error(`Broad-Side could not tell what language this repository is: no ${MANIFEST_CANDIDATES.map(([candidate]) => candidate).join(", ")} ` +
+            `and no source files in a language the lenses can scan (${BROADSIDE_LANGUAGES.join(", ")}). Nothing was submitted.`);
+    }
+    if (info.sourceFileCount === 0) {
+        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 resolved = new Map();
     for (const candidate of new Set([model, ...lensIds.map(modelForLens)])) {
@@ -1758,9 +2066,19 @@ export async function runBroadsideSubmit(cwd, apiKey, opts = {}) {
     let estimatedOutputTokens = 0;
     let estimatedTotalCost = 0;
     const perLensEstimate = [];
+    // What the redaction pass did across every lens's slices, for the run
+    // record and the report: a value in a file shared by two lenses counts
+    // once per lens it was sent in, files once each.
+    let redactedValues = info.redactedValues;
+    const redactedFiles = new Set();
     for (const lensId of lensIds) {
         const lens = getLens(lensId);
-        let slices = await gatherSlices(cwd, lens, info);
+        let slices = await gatherSlices(cwd, lens, info, { redact });
+        for (const slice of slices) {
+            redactedValues += slice.redactedValues ?? 0;
+            for (const file of slice.redactedFiles ?? [])
+                redactedFiles.add(file);
+        }
         if (changed) {
             // Repo-info slices (empty files, e.g. architecture) always run;
             // file-backed slices run only when one of their files changed.
@@ -1819,7 +2137,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,
@@ -1837,8 +2157,15 @@ export async function runBroadsideSubmit(cwd, apiKey, opts = {}) {
         sourceHead,
         sourceDirty,
         baseHead,
+        snapshot: info.snapshot,
+        language: info.language,
+        redaction: {
+            enabled: redact,
+            values: redactedValues,
+            files: redactedFiles.size,
+            skippedFiles: info.secretFilesSkipped.length,
+        },
     };
-    state.runs.push(run);
     await persistBroadsideRun(broadsideDir, run);
     const requestsByCustomId = {};
     const submissions = [];
@@ -1915,6 +2242,19 @@ export async function runBroadsideSubmit(cwd, apiKey, opts = {}) {
             expirationDate: defaultEntry.expirationDate ?? null,
         },
         incremental: incrementalOutcome,
+        repo: {
+            language: info.language,
+            sourceFiles: info.sourceFileCount,
+            snapshot: info.snapshot,
+            sourceHead,
+            sourceDirty,
+        },
+        redaction: {
+            enabled: redact,
+            values: redactedValues,
+            files: redactedFiles.size,
+            skippedFiles: info.secretFilesSkipped,
+        },
     };
 }
 function extractContent(result) {
@@ -2120,8 +2460,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);
@@ -2142,7 +2487,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 };
@@ -2187,7 +2532,8 @@ export async function runBroadsideCollect(cwd, apiKey, opts = {}) {
             // 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 };
+            const error = describeBatchError(batch.error);
+            lensOutcomes[lensId] = { status, cost: entry.cost, resultCount: entry.resultCount, ...(error && { error }) };
         }
         await persistBroadsideRun(broadsideDir, run);
     }
@@ -2281,7 +2627,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
@@ -2393,7 +2739,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;
@@ -2534,6 +2880,18 @@ 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}`);
     }
+    if (result.repo) {
+        const head = result.repo.sourceHead ? ` at ${result.repo.sourceHead.slice(0, 8)}${result.repo.sourceDirty ? " (dirty)" : ""}` : "";
+        const source = result.repo.snapshot === "working-tree" ? `working tree${head}` : "directory walk (not a git repository)";
+        lines.push(`Scanned as ${result.repo.language}: ${result.repo.sourceFiles} source file(s) from the ${source}.`);
+    }
+    if (result.redaction) {
+        const line = result.redaction.enabled
+            ? describeRedactions(result.redaction.values, result.redaction.files, result.redaction.skippedFiles)
+            : "Before upload: secret redaction is OFF (redact_secrets: false in config.yaml); files were sent as they are.";
+        if (line)
+            lines.push(line);
+    }
     const incremental = result.incremental;
     if (incremental?.requested) {
         lines.push(incremental.applied
@@ -2586,6 +2944,25 @@ export function modelsText(entries, opts) {
     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.");
     return lines.join("\n");
 }
+/** One line of a batch's error field, whatever shape the provider gave it. */
+function describeBatchError(error) {
+    if (error === undefined || error === null || error === "")
+        return null;
+    if (typeof error === "string")
+        return error.slice(0, 300);
+    if (typeof error === "object") {
+        const message = error.message;
+        if (typeof message === "string" && message)
+            return message.slice(0, 300);
+        try {
+            return JSON.stringify(error).slice(0, 300);
+        }
+        catch {
+            return String(error);
+        }
+    }
+    return String(error);
+}
 export function collectResultText(result) {
     const lines = [
         `Broad-Side run ${result.runId}: ${result.status}`,
@@ -2599,7 +2976,10 @@ export function collectResultText(result) {
         lines.push(`  ${lensId}: ${outcome.status}` +
             (outcome.cost !== undefined ? `, $${outcome.cost.toFixed(6)}` : "") +
             (outcome.resultCount !== undefined ? `, ${outcome.resultCount} result(s)` : "") +
-            truncation);
+            truncation +
+            // The reason a lens did not complete, when the poll recorded one:
+            // an auth failure or a dead network used to read as a slow batch.
+            (outcome.error ? ` — ${outcome.error}` : ""));
     }
     if (result.retriedCount > 0) {
         lines.push(`  ↻ ${result.retriedCount} truncated result(s) recovered by re-submission with a doubled output cap.`);
@@ -2639,6 +3019,12 @@ export function statusText(state) {
     const lines = [];
     for (const run of [...state.runs].reverse().slice(0, 3)) {
         lines.push(`Run ${run.id} — ${run.status}`);
+        // Recorded since #248; a run from an older version has neither field.
+        if (run.language || run.snapshot) {
+            const head = run.sourceHead ? ` at ${run.sourceHead.slice(0, 8)}${run.sourceDirty ? " (dirty)" : ""}` : "";
+            const source = run.snapshot === "walk" ? "directory walk" : run.snapshot ? `working tree${head}` : "unknown source";
+            lines.push(`  scanned as ${run.language ?? "unknown"} from the ${source}`);
+        }
         for (const lensId of BROADSIDE_LENS_IDS) {
             const entry = run.batches[lensId];
             if (!entry)