codecartographer-pi 0.19.5 → 0.20.0

package/dist/core/broadside.js

@@ -31,11 +31,12 @@
 // executable surfaces (Pi and MCP), not the pure template. What the template does
 // carry is the reading guide for its output — `.codecarto/broadside/SKILL.md`,
 // served by codecarto_skill under the name `broadside` (see readBroadsideSkill).
-import { mkdir, readFile, readdir, rename, stat, writeFile } from "node:fs/promises";
+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 { pathExists, sleep } from "./utils.js";
+import { atomicWriteFile, 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";
@@ -102,6 +103,23 @@ 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;
+    }
+}
 /** 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 +817,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,16 +841,26 @@ 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 });
+        const deleted = await execFileAsync("git", ["-C", targetDir, "ls-files", "-z", "--deleted"], {
             maxBuffer: 64 * 1024 * 1024,
         });
-        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) {
@@ -892,25 +929,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 +1000,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 +1042,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 +1065,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 +1129,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 +1168,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 +1183,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 +1201,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 +1252,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 +1266,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 +1318,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
@@ -1279,9 +1403,7 @@ export async function saveBroadsideState(broadsideDir, state) {
 }
 /** Serialize through a temp file so a crash mid-write cannot truncate state.json. */
 async function writeBroadsideStateFile(statePath, state) {
-    const tempPath = `${statePath}.${process.pid}.${Date.now()}.tmp`;
-    await writeFile(tempPath, `${JSON.stringify(state, null, "\t")}\n`, "utf8");
-    await rename(tempPath, statePath);
+    await atomicWriteFile(statePath, `${JSON.stringify(state, null, "\t")}\n`);
 }
 /**
  * Read-modify-write `state.json` under a lock.
@@ -1395,6 +1517,7 @@ 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),
     };
 }
 async function readCatalogCache(broadsideDir) {
@@ -1493,20 +1616,37 @@ export async function resolveCatalogEntry(broadsideDir, config, model, apiKey, f
     if (cached && Date.now() - new Date(cache.fetched_at).getTime() < 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 updated = {
@@ -1523,10 +1663,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)
@@ -1620,7 +1787,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;
@@ -1638,14 +1815,26 @@ 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;
         }
@@ -1653,13 +1842,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);
     }
 }
@@ -1686,7 +1885,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;
@@ -1695,6 +1893,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)])) {
@@ -1760,9 +1971,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.
@@ -1839,6 +2060,14 @@ 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);
@@ -1917,6 +2146,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) {
@@ -2189,7 +2431,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);
     }
@@ -2536,6 +2779,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
@@ -2588,6 +2843,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}`,
@@ -2601,7 +2875,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.`);
@@ -2641,6 +2918,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)