codecartographer-pi 0.16.0 → 0.17.0

package/dist/core/broadside.js

@@ -0,0 +1,2349 @@
+// Broad-Side: cheap batch reconnaissance over the OpenRouter Batch API.
+//
+// Broad-Side fires every analysis lens at a repository at once. Each lens is a
+// single-turn prompt with a structured-output JSON schema, submitted as an
+// asynchronous batch job (Google Gemini's batch endpoint, ~50% of sync pricing)
+// and polled to completion. Results land in `.codecarto/broadside/<run>/` as
+// JSON plus rendered markdown, and an optional synthesis pass cross-references
+// every lens into one executive report.
+//
+// This is deliberately NOT the interactive CodeCartographer pipeline. The batch
+// API is text-in/text-out: no filesystem access, no multi-turn exploration, no
+// runtime verification. Broad-Side findings are unverified scouting signals —
+// file:line leads that a real analysis (or a human) must confirm. That division
+// of labor is the point: a ~$0.50 unattended sweep that tells the expensive
+// interactive run where to look.
+//
+// Field shapes for the model catalog and benchmarks endpoints follow the
+// official OpenRouter skills (OpenRouterTeam/skills: openrouter-models,
+// openrouter-benchmarks).
+//
+// RESUBMISSION INVARIANT: batch requests are pure functions of their input —
+// no tools, no filesystem, no side effects — so resubmitting a failed or
+// truncated slice is always safe. This is the retry rule OpenRouter's own
+// headless-agent scaffold states the hard way (retry only before tool calls,
+// because replaying a mutating tool would double-execute it); here the rule is
+// satisfied by construction. If Broad-Side ever gains server tools
+// (openrouter:web_search etc.), this invariant becomes load-bearing and the
+// resubmit path must gate on whether any tool executed.
+//
+// Broad-Side requires runtime code, so the feature itself lives on the
+// executable surfaces (Pi and MCP), not the pure template. What the template does
+// carry is the reading guide for its output — `.codecarto/broadside/SKILL.md`,
+// served by codecarto_skill under the name `broadside` (see readBroadsideSkill).
+import { mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { join } from "node:path";
+import { pathExists, sleep } from "./utils.js";
+import { loadYamlFile } from "./yaml.js";
+import { packagedWorkspaceDir } from "./workspace.js";
+const execFileAsync = promisify(execFile);
+// ---------- constants ----------
+export const BROADSIDE_MODEL = "google/gemini-3.7-flash:batch";
+export const BROADSIDE_BATCH_URL = "https://openrouter.ai/api/beta/batches";
+export const BROADSIDE_DIR = "broadside"; // relative to .codecarto/
+/** Name Broad-Side answers to on the skill surfaces. Not a post-pipeline skill — see readBroadsideSkill. */
+export const BROADSIDE_SKILL_NAME = "broadside";
+export const BROADSIDE_STATE_FILE = "state.json";
+export const BROADSIDE_CONFIG_FILE = "config.yaml";
+export const BROADSIDE_STATE_SCHEMA_VERSION = 1;
+// Per-token pricing in USD (OpenRouter, google/gemini-3.7-flash:batch).
+export const BROADSIDE_INPUT_PRICE_PER_M = 0.1875;
+export const BROADSIDE_OUTPUT_PRICE_PER_M = 0.9375;
+// OpenRouter's public model catalog; pricing, context, and capabilities live
+// per model id. The benchmarks endpoint adds coding/intelligence indices.
+export const BROADSIDE_MODELS_URL = "https://openrouter.ai/api/v1/models";
+export const BROADSIDE_BENCHMARKS_URL = "https://openrouter.ai/api/v1/benchmarks";
+export const BROADSIDE_CATALOG_CACHE_FILE = "model-catalog.json";
+export const BROADSIDE_CATALOG_CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+export const BROADSIDE_LENS_IDS = [
+    "architecture",
+    "api",
+    "security",
+    "defect",
+    "conventions",
+    "porting",
+];
+export const BROADSIDE_POLL_INTERVAL_MS = 15_000;
+export const BROADSIDE_DEFAULT_POLL_BUDGET_MS = 25 * 60 * 1000;
+/** 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.") {
+        super(message);
+        this.name = "BroadsideCancelledError";
+    }
+}
+// ---------- JSON schemas (one per lens, plus synthesis) ----------
+const SCHEMAS = {
+    architecture: {
+        name: "architecture_report",
+        strict: true,
+        schema: {
+            type: "object",
+            properties: {
+                tech_stack: {
+                    type: "object",
+                    properties: {
+                        language: { type: "string" },
+                        version: { type: "string" },
+                        build_system: { type: "string" },
+                        key_dependencies: { type: "array", items: { type: "string" } },
+                    },
+                    required: ["language", "build_system"],
+                    additionalProperties: false,
+                },
+                module_architecture: {
+                    type: "array",
+                    items: {
+                        type: "object",
+                        properties: {
+                            name: { type: "string" },
+                            role: { type: "string" },
+                            file_count: { type: "integer" },
+                            depends_on: { type: "array", items: { type: "string" } },
+                        },
+                        required: ["name", "role"],
+                        additionalProperties: false,
+                    },
+                },
+                data_flow: { type: "string" },
+                entry_points: { type: "array", items: { type: "string" } },
+                notable_patterns: { type: "array", items: { type: "string" } },
+            },
+            required: ["tech_stack", "module_architecture", "data_flow", "entry_points"],
+            additionalProperties: false,
+        },
+    },
+    api_surface: {
+        name: "api_surface_report",
+        strict: true,
+        schema: {
+            type: "object",
+            properties: {
+                endpoints: {
+                    type: "array",
+                    items: {
+                        type: "object",
+                        properties: {
+                            method: { type: "string" },
+                            path: { type: "string" },
+                            handler: { type: "string" },
+                            auth_required: { type: "boolean" },
+                            description: { type: "string" },
+                        },
+                        required: ["method", "path", "handler", "auth_required"],
+                        additionalProperties: false,
+                    },
+                },
+                data_types: {
+                    type: "array",
+                    items: {
+                        type: "object",
+                        properties: {
+                            name: { type: "string" },
+                            kind: { type: "string" },
+                            fields_summary: { type: "string" },
+                        },
+                        required: ["name", "kind"],
+                        additionalProperties: false,
+                    },
+                },
+                authentication_flow: { type: "string" },
+                error_handling: { type: "string" },
+            },
+            required: ["endpoints"],
+            additionalProperties: false,
+        },
+    },
+    security: {
+        name: "security_review_report",
+        strict: true,
+        schema: {
+            type: "object",
+            properties: {
+                findings: {
+                    type: "array",
+                    items: {
+                        type: "object",
+                        properties: {
+                            severity: { type: "string", enum: ["critical", "high", "medium", "low"] },
+                            category: { type: "string" },
+                            title: { type: "string" },
+                            location: { type: "string" },
+                            description: { type: "string" },
+                        },
+                        required: ["severity", "title", "description"],
+                        additionalProperties: false,
+                    },
+                },
+                overall_assessment: { type: "string" },
+                coverage_note: { type: "string" },
+            },
+            required: ["findings", "overall_assessment"],
+            additionalProperties: false,
+        },
+    },
+    defect_mechanical: {
+        name: "defect_scan_report",
+        strict: true,
+        schema: {
+            type: "object",
+            properties: {
+                module: { type: "string" },
+                findings: {
+                    type: "array",
+                    items: {
+                        type: "object",
+                        properties: {
+                            severity: { type: "string", enum: ["high", "medium", "low"] },
+                            pattern: { type: "string" },
+                            title: { type: "string" },
+                            location: { type: "string" },
+                            description: { type: "string" },
+                            suggestion: { type: "string" },
+                        },
+                        required: ["severity", "pattern", "title", "description"],
+                        additionalProperties: false,
+                    },
+                },
+                patterns_checked: { type: "array", items: { type: "string" } },
+                files_scanned: { type: "integer" },
+                overall_notes: { type: "string" },
+            },
+            required: ["module", "findings", "patterns_checked", "files_scanned"],
+            additionalProperties: false,
+        },
+    },
+    conventions: {
+        name: "conventions_report",
+        strict: true,
+        schema: {
+            type: "object",
+            properties: {
+                module: { type: "string" },
+                naming_conventions: {
+                    type: "object",
+                    properties: {
+                        packages: { type: "string" },
+                        types: { type: "string" },
+                        functions: { type: "string" },
+                        variables: { type: "string" },
+                        files: { type: "string" },
+                        tests: { type: "string" },
+                    },
+                    additionalProperties: false,
+                },
+                error_handling_pattern: { type: "string" },
+                logging_approach: { type: "string" },
+                test_patterns: { type: "string" },
+                code_organization: { type: "string" },
+                idioms: { type: "array", items: { type: "string" } },
+                inconsistencies: {
+                    type: "array",
+                    items: {
+                        type: "object",
+                        properties: {
+                            description: { type: "string" },
+                            locations: { type: "array", items: { type: "string" } },
+                        },
+                        required: ["description"],
+                        additionalProperties: false,
+                    },
+                },
+                promotable_conventions: {
+                    type: "array",
+                    items: {
+                        type: "object",
+                        properties: {
+                            title: { type: "string" },
+                            rule: { type: "string" },
+                            evidence: { type: "string" },
+                        },
+                        required: ["title", "rule"],
+                        additionalProperties: false,
+                    },
+                },
+                files_scanned: { type: "integer" },
+            },
+            required: ["module", "naming_conventions", "files_scanned"],
+            additionalProperties: false,
+        },
+    },
+    porting: {
+        name: "porting_surface_report",
+        strict: true,
+        schema: {
+            type: "object",
+            properties: {
+                module: { type: "string" },
+                platform_coupling: {
+                    type: "array",
+                    items: {
+                        type: "object",
+                        properties: {
+                            platform: { type: "string" },
+                            mechanisms: { type: "array", items: { type: "string" } },
+                            files: { type: "array", items: { type: "string" } },
+                        },
+                        required: ["platform", "mechanisms"],
+                        additionalProperties: false,
+                    },
+                },
+                external_dependencies: {
+                    type: "array",
+                    items: {
+                        type: "object",
+                        properties: {
+                            name: { type: "string" },
+                            role: { type: "string" },
+                            replaceability: { type: "string" },
+                        },
+                        required: ["name"],
+                        additionalProperties: false,
+                    },
+                },
+                build_system_complexity: { type: "string" },
+                porting_risk_areas: {
+                    type: "array",
+                    items: {
+                        type: "object",
+                        properties: {
+                            area: { type: "string" },
+                            risk: { type: "string", enum: ["low", "medium", "high"] },
+                            notes: { type: "string" },
+                        },
+                        required: ["area", "risk"],
+                        additionalProperties: false,
+                    },
+                },
+                files_scanned: { type: "integer" },
+            },
+            required: ["module", "platform_coupling", "files_scanned"],
+            additionalProperties: false,
+        },
+    },
+    synthesis: {
+        name: "synthesis_report",
+        strict: true,
+        schema: {
+            type: "object",
+            properties: {
+                executive_summary: { type: "string" },
+                severity_summary: {
+                    type: "object",
+                    properties: {
+                        critical: { type: "integer" },
+                        high: { type: "integer" },
+                        medium: { type: "integer" },
+                        low: { type: "integer" },
+                    },
+                    required: ["critical", "high", "medium", "low"],
+                    additionalProperties: false,
+                },
+                top_findings: {
+                    type: "array",
+                    items: {
+                        type: "object",
+                        properties: {
+                            title: { type: "string" },
+                            severity: { type: "string" },
+                            source_lens: { type: "string" },
+                            summary: { type: "string" },
+                        },
+                        required: ["title", "severity", "source_lens", "summary"],
+                        additionalProperties: false,
+                    },
+                },
+                module_assessments: {
+                    type: "array",
+                    items: {
+                        type: "object",
+                        properties: {
+                            module: { type: "string" },
+                            quality_notes: { type: "string" },
+                            risk_level: { type: "string", enum: ["low", "medium", "high"] },
+                        },
+                        required: ["module", "risk_level"],
+                        additionalProperties: false,
+                    },
+                },
+                porting_readiness: { type: "string" },
+                gaps_and_unknowns: { type: "array", items: { type: "string" } },
+                coverage: { type: "string" },
+            },
+            required: ["executive_summary", "severity_summary", "top_findings"],
+            additionalProperties: false,
+        },
+    },
+    triage: {
+        name: "triage_report",
+        strict: true,
+        schema: {
+            type: "object",
+            properties: {
+                summary: { type: "string" },
+                items: {
+                    type: "array",
+                    items: {
+                        type: "object",
+                        properties: {
+                            title: { type: "string" },
+                            severity: { type: "string" },
+                            module: { type: "string" },
+                            impact: { type: "string", enum: ["high", "medium", "low"] },
+                            difficulty: { type: "string", enum: ["high", "medium", "low"] },
+                            priority: { type: "string" },
+                            effort_estimate: { type: "string" },
+                            rationale: { type: "string" },
+                        },
+                        required: ["title", "severity", "module", "impact", "difficulty", "priority", "rationale"],
+                        additionalProperties: false,
+                    },
+                },
+                omitted: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Leads deliberately dropped from the queue and why (duplicates, too vague, out of scope)",
+                },
+            },
+            required: ["summary", "items"],
+            additionalProperties: false,
+        },
+    },
+};
+const TS_PROFILE = {
+    defectPatterns: [
+        "Null/undefined dereference risks (unchecked optional access)",
+        "Error handling gaps (unhandled promise rejections, swallowed catches)",
+        "Resource leaks (unclosed handles, missing cleanup, dangling timers/listeners)",
+        "Race conditions (shared mutable state, async interleavings without guards)",
+        "Integer/precision assumptions in arithmetic",
+        "Unsafe type assumptions (as-casts, any leaks, non-null assertions)",
+        "Panic-prone code (out-of-bounds access, runtime TypeError paths)",
+        "Timezone/locale assumptions",
+    ],
+    conventionCategories: [
+        { key: "packages", label: "modules and imports" },
+        { key: "types", label: "interfaces and type aliases" },
+        { key: "functions", label: "functions (camelCase), components (PascalCase)" },
+        { key: "variables", label: "variables and constants (camelCase)" },
+        { key: "files", label: "file naming (kebab vs camel) and folder organization" },
+        { key: "tests", label: "test files (*.test.ts, describe/it patterns)" },
+    ],
+    idiomHints: ["strict null checks usage", "async/await vs promise chains", "dependency injection patterns"],
+};
+const LANGUAGE_PROFILES = {
+    go: {
+        defectPatterns: [
+            "Nil pointer dereference risks (unchecked returns, missing nil guards)",
+            "Error handling gaps (ignored errors, deferred errors unchecked)",
+            "Resource leaks (unclosed files, connections, goroutines without ctx)",
+            "Race conditions (shared state without sync, channel misuse)",
+            "Integer overflow/underflow in arithmetic or bounds",
+            "Unsafe type assertions without ok check",
+            "Panic-prone code (slice out of bounds, map access without ok)",
+            "Timezone/locale assumptions",
+        ],
+        conventionCategories: [
+            { key: "packages", label: "packages" },
+            { key: "types", label: "types and interfaces" },
+            { key: "functions", label: "functions and methods" },
+            { key: "variables", label: "variables and fields" },
+            { key: "files", label: "file and directory organization" },
+            { key: "tests", label: "test files and table-driven tests" },
+        ],
+        idiomHints: ["error wrapping with %w", "zero-value construction"],
+    },
+    python: {
+        defectPatterns: [
+            "None dereference risks (unchecked optional returns, AttributeError paths)",
+            "Exception handling gaps (bare except, swallowed exceptions, broad catch-all)",
+            "Resource leaks (unclosed files, sockets, connections, context managers)",
+            "Race conditions (shared mutable state, threading without locks, async pitfalls)",
+            "Integer/float precision assumptions in arithmetic",
+            "Unsafe type assumptions (unpacking mismatches, isinstance without fallback)",
+            "Panic-prone code (IndexError/KeyError paths, unbounded slicing)",
+            "Timezone/locale assumptions (naive datetimes)",
+        ],
+        conventionCategories: [
+            { key: "packages", label: "modules and packages" },
+            { key: "types", label: "classes and type hints" },
+            { key: "functions", label: "functions and methods (snake_case vs camelCase)" },
+            { key: "variables", label: "variables and constants" },
+            { key: "files", label: "file and module organization" },
+            { key: "tests", label: "test files (pytest fixtures, naming)" },
+        ],
+        idiomHints: ["dunder method usage", "context manager idioms", "dataclass/pydantic models"],
+    },
+    rust: {
+        defectPatterns: [
+            "Unwrap/expect panics on fallible paths",
+            "Error handling gaps (swallowed Results, lossy conversions)",
+            "Resource leaks (unclosed handles, drop order assumptions)",
+            "Data races and Send/Sync violations (unsafe blocks, interior mutability misuse)",
+            "Integer overflow/underflow (arithmetic, casting)",
+            "Unsafe type assumptions (transmute/casts without invariants)",
+            "Panic-prone code (indexing, slicing, unreachable! in library paths)",
+            "Timezone/locale assumptions",
+        ],
+        conventionCategories: [
+            { key: "packages", label: "crates and modules" },
+            { key: "types", label: "structs, enums, and traits" },
+            { key: "functions", label: "functions and methods (snake_case)" },
+            { key: "variables", label: "variables and constants (SCREAMING_SNAKE)" },
+            { key: "files", label: "module file organization" },
+            { key: "tests", label: "test modules and #[cfg(test)] patterns" },
+        ],
+        idiomHints: ["Result/Option handling with ?", "builder patterns", "trait-based extension"],
+    },
+    typescript: TS_PROFILE,
+    javascript: TS_PROFILE,
+    default: {
+        defectPatterns: [
+            "Null/undefined dereference risks (unchecked optional access)",
+            "Error handling gaps (ignored or swallowed errors)",
+            "Resource leaks (unclosed files, connections, handles)",
+            "Race conditions (shared mutable state without synchronization)",
+            "Integer overflow/underflow in arithmetic or bounds",
+            "Unsafe type assumptions and unchecked casts",
+            "Panic-prone code (out-of-bounds access, missing keys)",
+            "Timezone/locale assumptions",
+        ],
+        conventionCategories: [
+            { key: "packages", label: "modules, packages, or namespaces" },
+            { key: "types", label: "types, classes, and interfaces" },
+            { key: "functions", label: "functions and methods" },
+            { key: "variables", label: "variables and constants" },
+            { key: "files", label: "file and directory organization" },
+            { key: "tests", label: "test files and test organization" },
+        ],
+        idiomHints: [],
+    },
+};
+function languageProfile(language) {
+    return LANGUAGE_PROFILES[language] ?? LANGUAGE_PROFILES.default;
+}
+const LENSES = {
+    architecture: {
+        id: "architecture",
+        name: "Architecture, tech stack & module map",
+        description: "Repo-wide structural analysis from the manifest, entry point, README, and file tree.",
+        schemaName: "architecture",
+        sliceBy: "none",
+        maxChars: 0, // repo-info lens; no file slurping
+        maxTokens: 8000,
+        globsFor: () => [],
+        systemPrompt: () => "You are a senior software architect performing a structural analysis of a " +
+            "codebase. You receive the project manifest, entry point, README excerpt, and " +
+            "file tree. Return a JSON object following the architecture_report schema " +
+            "exactly. All findings must be traceable to the provided files — cite file " +
+            "paths. If you can't determine something, say so rather than guessing.",
+        userPrompt: (info) => {
+            const manifest = info.manifest
+                ? `## ${info.manifest.path}\n\`\`\`\n${info.manifest.content}\n\`\`\`\n\n`
+                : "## Manifest\n[no manifest found]\n\n";
+            return ("Analyze the architecture of this project.\n\n" +
+                manifest +
+                `## Entry point\n\`\`\`\n${info.mainFile || "[missing]"}\n\`\`\`\n\n` +
+                `## README (first 4000 chars)\n${info.readmeFirst || "[missing]"}\n\n` +
+                `## File tree (depth 3, capped)\n${info.fileTree || "[missing]"}\n\n` +
+                "## File counts by extension\n```json\n" +
+                JSON.stringify(info.fileCounts) +
+                "\n```\n\n" +
+                "Return the architecture_report JSON schema.");
+        },
+    },
+    api: {
+        id: "api",
+        name: "API surface audit",
+        description: "Endpoint catalog, request/response types, auth flow, error handling.",
+        schemaName: "api_surface",
+        sliceBy: "none",
+        maxChars: 70_000,
+        maxTokens: 8000,
+        skipTestFiles: true,
+        globsFor: (info) => info.language === "go"
+            ? ["server/**/*.go", "server/*.go", "api/**/*.go", "api/*.go"]
+            : [
+                "server/**",
+                "api/**",
+                "src/server/**",
+                "src/api/**",
+                "mcp-server/**",
+                "**/*routes*",
+                "**/*router*",
+                "**/*handler*",
+                "**/*endpoint*",
+            ],
+        systemPrompt: () => "You are a senior API auditor. Given source files from an HTTP server, " +
+            "extract every HTTP endpoint (method, path, handler function, auth requirement) " +
+            "and every key request/response data type. Return a JSON object following the " +
+            "api_surface_report schema exactly. Cite specific file:line locations.",
+        userPrompt: (info, source, moduleName) => "Extract the full API surface from these server source files:\n\n" +
+            source +
+            "\n\nReturn the api_surface_report JSON schema.",
+    },
+    security: {
+        id: "security",
+        name: "Security review",
+        description: "Auth, authorization, input validation, TLS, secrets, trust boundaries.",
+        schemaName: "security",
+        sliceBy: "none",
+        maxChars: 70_000,
+        maxTokens: 8000,
+        skipTestFiles: true,
+        globsFor: (info) => info.language === "go"
+            ? ["server/**/*.go", "server/*.go", "**/auth*.go", "**/middleware/**/*.go", "SECURITY.md"]
+            : ["server/**", "**/auth*", "**/middleware/**", "SECURITY.md"],
+        systemPrompt: () => "You are a security engineer performing a first-pass review of a codebase. " +
+            "Given source files, identify potential security issues — focusing on " +
+            "authentication, authorization, input validation, TLS, secrets handling, " +
+            "and trust boundaries. Return a JSON object following the security_review_report " +
+            "schema. Rate severity as critical/high/medium/low. Be specific: cite file:line. " +
+            "If the provided files don't cover an area, state the gap in coverage_note.",
+        userPrompt: (info, source, moduleName) => "Review these server source files for security issues:\n\n" +
+            source +
+            "\n\nReturn the security_review_report JSON schema.",
+    },
+    defect: {
+        id: "defect",
+        name: "Mechanical defect scan",
+        description: "Nil derefs, error gaps, leaks, races, panics — pattern-based, sliced per module.",
+        schemaName: "defect_mechanical",
+        sliceBy: "auto",
+        maxChars: 60_000,
+        maxTokens: 6000,
+        globsFor: (info) => [info.sourceGlob],
+        systemPrompt: (info) => {
+            const profile = languageProfile(info.language);
+            const patterns = profile.defectPatterns.map((p, i) => `  ${i + 1}. ${p}`).join("\n");
+            return (`You are a senior code reviewer performing an automated defect scan on ${info.language} ` +
+                "source files. Look for these specific patterns:\n" +
+                patterns +
+                "\n\n" +
+                "Return a JSON object following the defect_scan_report schema. " +
+                "Cite file:line for every finding. List which patterns you checked. " +
+                "If the code looks clean for a pattern, say so rather than staying silent. " +
+                "Prefer precision over volume — 3 solid findings beat 15 vague ones.");
+        },
+        userPrompt: (info, source, moduleName) => `Scan this ${info.language} module for mechanical defects.\n\n` +
+            `Module: ${moduleName}\n\n` +
+            "## Source files\n\n" +
+            source +
+            "\n\nReturn the defect_scan_report JSON schema.",
+    },
+    conventions: {
+        id: "conventions",
+        name: "Convention extraction",
+        description: "Naming, error handling, idioms, inconsistencies, promotable conventions.",
+        schemaName: "conventions",
+        sliceBy: "auto",
+        maxChars: 60_000,
+        maxTokens: 6000,
+        globsFor: (info) => [info.sourceGlob],
+        systemPrompt: (info) => {
+            const profile = languageProfile(info.language);
+            const categories = profile.conventionCategories.map((c) => `${c.key} (${c.label})`).join(", ");
+            const idiomHint = profile.idiomHints.length > 0
+                ? ` Keep an eye out for ${info.language} idioms such as ${profile.idiomHints.join(", ")}.`
+                : "";
+            return (`You are a code style analyst extracting conventions from ${info.language} source files. ` +
+                "Catalog naming conventions per category — " + categories + " — plus the dominant " +
+                "error-handling pattern, logging approach, test organization patterns, file/package " +
+                "organization rules, and recurring idioms." + idiomHint +
+                " Also flag inconsistencies — places where the same convention is violated. " +
+                "If you find well-established conventions worth formalizing, list them as " +
+                "promotable_conventions with a title, rule, and evidence from the code. " +
+                "Return a JSON object following the conventions_report schema.");
+        },
+        userPrompt: (info, source, moduleName) => "Extract coding conventions from this module.\n\n" +
+            `Module: ${moduleName}\n\n` +
+            "## Source files\n\n" +
+            source +
+            "\n\nReturn the conventions_report JSON schema.",
+    },
+    porting: {
+        id: "porting",
+        name: "Porting surface assessment",
+        description: "Platform coupling, external deps, build complexity, porting risk areas.",
+        schemaName: "porting",
+        sliceBy: "auto",
+        maxChars: 60_000,
+        maxTokens: 6000,
+        skipTestFiles: true,
+        globsFor: (info) => [
+            info.sourceGlob,
+            "**/*.c",
+            "**/*.h",
+            "**/*.cpp",
+            "**/*.cc",
+            "**/*.m",
+            "**/*.mm",
+            "**/CMakeLists.txt",
+            "**/*.cmake",
+            "go.mod",
+        ],
+        systemPrompt: () => "You are a software portability analyst. Examine source files and " +
+            "identify everything that ties this codebase to a specific platform, OS, " +
+            "architecture, or external dependency. Catalog: platform-specific build tags, " +
+            "FFI usage, OS-specific syscalls, external library bindings, and " +
+            "compile-time constants that encode platform assumptions. " +
+            "For each external dependency, note whether it could be replaced by a " +
+            "cross-platform alternative. Assess the build system complexity. " +
+            "Return a JSON object following the porting_surface_report schema.",
+        userPrompt: (info, source, moduleName) => "Assess porting surface for this module.\n\n" +
+            `Module: ${moduleName}\n\n` +
+            "## Source files\n\n" +
+            source +
+            "\n\nReturn the porting_surface_report JSON schema.",
+    },
+};
+export function getLens(lensId) {
+    return LENSES[lensId];
+}
+export function listLenses() {
+    return BROADSIDE_LENS_IDS.map((id) => LENSES[id]);
+}
+// ---------- repo info ----------
+const SKIP_DIR_NAMES = new Set([
+    ".git",
+    ".github",
+    ".claude",
+    ".opencode",
+    ".codecarto",
+    "node_modules",
+    "vendor",
+    "dist",
+    "build",
+    "target",
+    "testdata",
+    "__pycache__",
+]);
+const SKIP_FILE_EXTENSIONS = new Set([
+    ".png",
+    ".jpg",
+    ".jpeg",
+    ".gif",
+    ".svg",
+    ".ico",
+    ".icns",
+    ".bmp",
+    ".webp",
+    ".mp3",
+    ".mp4",
+    ".mov",
+    ".avi",
+    ".wav",
+    ".ogg",
+    ".zip",
+    ".gz",
+    ".tar",
+    ".bz2",
+    ".xz",
+    ".7z",
+    ".pdf",
+    ".woff",
+    ".woff2",
+    ".ttf",
+    ".eot",
+    ".otf",
+    ".bin",
+    ".exe",
+    ".dll",
+    ".so",
+    ".dylib",
+    ".a",
+    ".o",
+    ".obj",
+    ".class",
+    ".jar",
+    ".war",
+    ".pyc",
+    ".wasm",
+    ".model",
+    ".bpe",
+]);
+const MANIFEST_CANDIDATES = [
+    ["go.mod", "go"],
+    ["package.json", "typescript"],
+    ["Cargo.toml", "rust"],
+    ["pyproject.toml", "python"],
+    ["setup.py", "python"],
+    ["requirements.txt", "python"],
+];
+const SOURCE_SPECS = {
+    go: { glob: "**/*.go", exts: [".go"] },
+    python: { glob: "**/*.py", exts: [".py"] },
+    rust: { glob: "**/*.rs", exts: [".rs"] },
+    typescript: { glob: "**/*.ts", exts: [".ts", ".tsx"] },
+    javascript: { glob: "**/*.js", exts: [".js", ".jsx"] },
+};
+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"], {
+            maxBuffer: 64 * 1024 * 1024,
+        });
+        return stdout.split("\n").filter(Boolean);
+    }
+    catch {
+        return walkFiles(targetDir, targetDir, 0, 30_000);
+    }
+}
+async function gitHead(targetDir) {
+    try {
+        const { stdout } = await execFileAsync("git", ["-C", targetDir, "rev-parse", "HEAD"], { maxBuffer: 1024 * 1024 });
+        return stdout.trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+async function gitDirty(targetDir) {
+    try {
+        const { stdout } = await execFileAsync("git", ["-C", targetDir, "status", "--porcelain"], { maxBuffer: 1024 * 1024 });
+        return stdout.trim().length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Repo-relative paths changed since `baseHead` (or all files when there is
+ * no base). Returns null when the diff cannot be computed (non-git tree,
+ * missing base commit) so callers fall back to a full scan.
+ */
+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 });
+        return new Set(stdout.split("\n").filter(Boolean));
+    }
+    catch {
+        return null;
+    }
+}
+async function walkFiles(rootDir, dir, depth, remaining) {
+    if (remaining <= 0)
+        return [];
+    let out = [];
+    let entries = [];
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return out;
+    }
+    for (const entry of entries) {
+        if (entry.name.startsWith(".") && entry.name !== ".github")
+            continue;
+        if (entry.isDirectory()) {
+            if (SKIP_DIR_NAMES.has(entry.name))
+                continue;
+            if (depth > 8)
+                continue;
+            const children = await walkFiles(rootDir, join(dir, entry.name), depth + 1, remaining - out.length);
+            out = out.concat(children);
+        }
+        else if (entry.isFile()) {
+            const rel = join(dir, entry.name).slice(rootDir.length + 1).split("\\").join("/");
+            out.push(rel);
+        }
+    }
+    return out;
+}
+function detectLanguage(fileCounts, manifestPath) {
+    if (manifestPath) {
+        for (const [candidate, lang] of MANIFEST_CANDIDATES) {
+            if (manifestPath === candidate)
+                return lang;
+        }
+    }
+    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";
+}
+export async function collectRepoInfo(targetDir) {
+    const allFiles = await listRepoFiles(targetDir);
+    const fileCounts = {};
+    for (const f of allFiles) {
+        const slash = f.lastIndexOf("/");
+        const base = slash >= 0 ? f.slice(slash + 1) : f;
+        const dot = base.lastIndexOf(".");
+        const ext = dot > 0 ? base.slice(dot).toLowerCase() : "(no ext)";
+        fileCounts[ext] = (fileCounts[ext] ?? 0) + 1;
+    }
+    const sortedCounts = {};
+    for (const [ext, n] of Object.entries(fileCounts).sort((a, b) => b[1] - a[1])) {
+        sortedCounts[ext] = n;
+    }
+    let manifest = null;
+    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;
+        }
+    }
+    let mainFile = "";
+    for (const candidate of ["main.go", "main.py", "src/main.rs", "src/index.ts", "index.ts"]) {
+        const p = join(targetDir, candidate);
+        if (await pathExists(p)) {
+            try {
+                mainFile = await readFile(p, "utf8");
+            }
+            catch {
+                mainFile = "";
+            }
+            break;
+        }
+    }
+    let readmeFirst = "";
+    const readmePath = join(targetDir, "README.md");
+    if (await pathExists(readmePath)) {
+        try {
+            readmeFirst = (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;
+    const name = targetDir.split(/[\\/]/).filter(Boolean).pop() ?? "repo";
+    return {
+        name,
+        path: targetDir,
+        language,
+        manifest,
+        mainFile,
+        readmeFirst,
+        fileTree,
+        fileCounts: sortedCounts,
+        sourceGlob: sourceSpec.glob,
+        sourceExts: sourceSpec.exts,
+    };
+}
+function buildFileTree(allFiles, maxDepth = 3, maxLines = 200) {
+    const lines = [];
+    let count = 0;
+    for (const f of allFiles) {
+        if (f.split("/").length - 1 > maxDepth)
+            continue;
+        if (f.startsWith(".git/") || f.startsWith(".github/"))
+            continue;
+        if (f.endsWith(".sum") || f.endsWith(".lock"))
+            continue;
+        lines.push(f);
+        count += 1;
+        if (count >= maxLines) {
+            lines.push(`... (${allFiles.length} total files, showing first ${maxLines})`);
+            break;
+        }
+    }
+    return lines.join("\n");
+}
+// ---------- glob matching & file slurping ----------
+function globToRegExp(glob) {
+    let re = "";
+    for (let i = 0; i < glob.length; i++) {
+        const c = glob[i];
+        if (c === "*") {
+            if (glob[i + 1] === "*") {
+                // `**/` matches zero or more directories; a trailing `**`
+                // matches anything including slashes.
+                if (glob[i + 2] === "/") {
+                    re += "(?:.*/)?";
+                    i += 2;
+                }
+                else {
+                    re += ".*";
+                    i += 1;
+                }
+            }
+            else {
+                re += "[^/]*";
+            }
+        }
+        else if (c === "?") {
+            re += "[^/]";
+        }
+        else {
+            re += c.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+        }
+    }
+    return new RegExp(`^${re}$`);
+}
+function matchesAnyGlob(path, globs) {
+    for (const glob of globs) {
+        if (globToRegExp(glob).test(path))
+            return true;
+    }
+    return false;
+}
+function isSlurpable(relPath) {
+    const segments = relPath.split("/");
+    for (const seg of segments) {
+        if (SKIP_DIR_NAMES.has(seg))
+            return false;
+    }
+    const slash = relPath.lastIndexOf("/");
+    const base = slash >= 0 ? relPath.slice(slash + 1) : relPath;
+    const dot = base.lastIndexOf(".");
+    if (dot > 0 && SKIP_FILE_EXTENSIONS.has(base.slice(dot).toLowerCase()))
+        return false;
+    return true;
+}
+function sanitizeId(segment) {
+    return segment.replace(/[^a-zA-Z0-9_-]+/g, "-").replace(/^-+|-+$/g, "") || "root";
+}
+function topLevelModule(relPath) {
+    const slash = relPath.indexOf("/");
+    return slash >= 0 ? relPath.slice(0, slash) : "root";
+}
+function isTestFile(relPath) {
+    const base = relPath.slice(relPath.lastIndexOf("/") + 1);
+    return /[._](test|spec)\.[a-z]+$/i.test(base) || base.includes("_test.");
+}
+/**
+ * "auto" slicing: directory-slice when the repo is large enough that a
+ * single whole-repo slice would overflow the lens's char cap, otherwise a
+ * single slice. The threshold is the lens's own cap — a repo whose matching
+ * files fit in one slice gains nothing from per-module splitting, and a
+ * small repo pays for it in extra requests.
+ */
+function resolveSliceMode(lens, files, totalChars) {
+    if (lens.sliceBy !== "auto")
+        return lens.sliceBy;
+    return totalChars > lens.maxChars ? "directory" : "none";
+}
+function collectLensFiles(allFiles, lens, info) {
+    const globs = lens.globsFor(info);
+    if (globs.length === 0)
+        return [];
+    const out = [];
+    for (const f of allFiles) {
+        if (!isSlurpable(f))
+            continue;
+        if (lens.skipTestFiles && isTestFile(f))
+            continue;
+        if (!matchesAnyGlob(f, globs))
+            continue;
+        out.push({ relPath: f, moduleName: topLevelModule(f) });
+    }
+    return out;
+}
+async function slurpFileList(targetDir, files, maxChars) {
+    const slices = [];
+    let currentModule = "";
+    let parts = [];
+    let running = 0;
+    let fileCount = 0;
+    let filePaths = [];
+    const flush = () => {
+        if (parts.length === 0)
+            return;
+        slices.push({
+            moduleName: currentModule,
+            content: parts.join("\n"),
+            fileCount,
+            chars: running,
+            files: filePaths,
+        });
+        parts = [];
+        running = 0;
+        fileCount = 0;
+        filePaths = [];
+    };
+    for (const file of files) {
+        let content = "";
+        try {
+            content = await readFile(join(targetDir, file.relPath), "utf8");
+        }
+        catch {
+            content = "[BINARY or UNREADABLE]";
+        }
+        const block = `=== ${file.relPath} ===\n${content}\n`;
+        if (file.moduleName !== currentModule && parts.length > 0) {
+            flush();
+        }
+        currentModule = file.moduleName;
+        if (running + block.length > maxChars && parts.length > 0) {
+            // Slice is full: flush it and start another slice for the same module
+            // rather than truncating, so big modules get full coverage.
+            flush();
+            currentModule = file.moduleName;
+        }
+        parts.push(block);
+        running += block.length;
+        fileCount += 1;
+        filePaths.push(file.relPath);
+    }
+    flush();
+    return slices;
+}
+export async function gatherSlices(targetDir, lens, info) {
+    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 = collectLensFiles(allFiles, lens, info);
+    const totalChars = await sumFileSizes(targetDir, files);
+    const mode = resolveSliceMode(lens, files, totalChars);
+    if (mode === "none") {
+        // 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, files, lens.maxChars);
+}
+async function sumFileSizes(targetDir, files) {
+    let total = 0;
+    for (const f of files) {
+        try {
+            total += (await stat(join(targetDir, f.relPath))).size;
+        }
+        catch {
+            // Unreadable file — slurpFileList substitutes a placeholder.
+        }
+    }
+    return total;
+}
+// ---------- request building ----------
+export function buildBatchRequest(lens, info, slice, index, sliceCount, model = BROADSIDE_MODEL, maxTokensOverride) {
+    const moduleTag = sanitizeId(slice.moduleName);
+    const customId = sliceCount > 1 ? `${lens.id}-${moduleTag}-${index + 1}` : `${lens.id}-${moduleTag}`;
+    return {
+        custom_id: customId,
+        body: {
+            model,
+            messages: [
+                { role: "system", content: lens.systemPrompt(info) },
+                { role: "user", content: lens.userPrompt(info, slice.content, slice.moduleName) },
+            ],
+            response_format: { type: "json_schema", json_schema: SCHEMAS[lens.schemaName] },
+            max_tokens: maxTokensOverride ?? lens.maxTokens,
+        },
+    };
+}
+export function estimateCost(lens, slices, pricing, maxTokensOverride) {
+    const inputTokens = Math.ceil(slices.reduce((sum, s) => sum + (lens.maxChars === 0 ? 6000 : s.chars), 0) / 4);
+    const outputTokens = Math.ceil((maxTokensOverride ?? lens.maxTokens) * 0.75);
+    const cost = (inputTokens / 1_000_000) * pricing.inputPerM +
+        (outputTokens / 1_000_000) * pricing.outputPerM;
+    return { inputTokens, outputTokens, cost };
+}
+// ---------- state & config ----------
+export function broadsideDirFor(cwd) {
+    return join(cwd, ".codecarto", BROADSIDE_DIR);
+}
+/**
+ * Read the Broad-Side reading guide.
+ *
+ * It is deliberately not a post-pipeline skill under `.codecarto/skills/`: a
+ * scout run is read *before* or *during* the interactive pipeline, and the
+ * post-pipeline machinery gates on a completed run and wraps its prompt in
+ * post-pipeline framing that would be false here. It is also readable on a
+ * repository that has scout state and no workspace at all, which is why this
+ * falls back to the packaged copy.
+ *
+ * @param cwd - Absolute path to the target repository.
+ * @returns the skill text and the path it came from.
+ * @throws when neither the workspace copy nor the packaged copy exists.
+ */
+export async function readBroadsideSkill(cwd) {
+    const candidates = [
+        join(broadsideDirFor(cwd), "SKILL.md"),
+        join(packagedWorkspaceDir, BROADSIDE_DIR, "SKILL.md"),
+    ];
+    for (const path of candidates) {
+        if (await pathExists(path))
+            return { path, content: await readFile(path, "utf8") };
+    }
+    throw new Error(`Broad-Side skill not found at ${candidates.join(" or ")}. Reinstall codecartographer-pi.`);
+}
+export function defaultBroadsideState() {
+    return { schema_version: BROADSIDE_STATE_SCHEMA_VERSION, runs: [] };
+}
+export async function loadBroadsideState(broadsideDir) {
+    const statePath = join(broadsideDir, BROADSIDE_STATE_FILE);
+    if (!(await pathExists(statePath)))
+        return defaultBroadsideState();
+    try {
+        const raw = JSON.parse(await readFile(statePath, "utf8"));
+        if (!raw || typeof raw !== "object" || !Array.isArray(raw.runs))
+            return defaultBroadsideState();
+        return raw;
+    }
+    catch {
+        return defaultBroadsideState();
+    }
+}
+export async function saveBroadsideState(broadsideDir, state) {
+    await mkdir(broadsideDir, { recursive: true });
+    await writeFile(join(broadsideDir, BROADSIDE_STATE_FILE), `${JSON.stringify(state, null, "\t")}\n`, "utf8");
+}
+export async function loadBroadsideConfig(broadsideDir) {
+    const configPath = join(broadsideDir, BROADSIDE_CONFIG_FILE);
+    let raw = {};
+    if (await pathExists(configPath)) {
+        try {
+            raw = (await loadYamlFile(configPath)) ?? {};
+        }
+        catch {
+            raw = {};
+        }
+    }
+    const lenses = Array.isArray(raw.default_lenses)
+        ? (raw.default_lenses.filter((l) => BROADSIDE_LENS_IDS.includes(l)))
+        : [];
+    const rawPricing = (raw.pricing ?? {});
+    const inputOverride = typeof rawPricing.input_per_m === "number" ? rawPricing.input_per_m : undefined;
+    const outputOverride = typeof rawPricing.output_per_m === "number" ? rawPricing.output_per_m : undefined;
+    // A malformed value falls back to the shipped default rather than failing
+    // the run: config.yaml is hand-edited, and a typo in a poll budget must not
+    // cost a user their batches.
+    const flag = (key, fallback) => typeof raw[key] === "boolean" ? raw[key] : fallback;
+    // An override for an unknown lens id is dropped rather than carried: it can
+    // only be a typo, and a silently-ignored key that looks applied is worse
+    // than one that never appears.
+    const lensModels = {};
+    const rawLensModels = (raw.lens_models ?? {});
+    for (const lensId of BROADSIDE_LENS_IDS) {
+        const value = rawLensModels[lensId];
+        if (typeof value === "string" && value.trim())
+            lensModels[lensId] = value.trim();
+    }
+    return {
+        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,
+        pricing: inputOverride !== undefined && outputOverride !== undefined
+            ? { inputPerM: inputOverride, outputPerM: outputOverride }
+            : null,
+        lensModels,
+        incremental: flag("incremental", false),
+        retryTruncated: flag("retry_truncated", true),
+        includeSynthesis: flag("include_synthesis", true),
+        includeTriage: flag("include_triage", true),
+        waitSeconds: typeof raw.wait_seconds === "number" && raw.wait_seconds > 0 ? raw.wait_seconds : 0,
+    };
+}
+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")
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+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");
+}
+function parseCatalogEntry(raw) {
+    const id = String(raw.id ?? "");
+    if (!id)
+        return null;
+    const p = (raw.pricing ?? {});
+    const input = typeof p.prompt === "string" ? Number(p.prompt) : NaN;
+    const output = typeof p.completion === "string" ? Number(p.completion) : NaN;
+    if (!Number.isFinite(input) || !Number.isFinite(output))
+        return null;
+    const cached = typeof p.cached_input === "string" ? Number(p.cached_input) : NaN;
+    const topProvider = (raw.top_provider ?? {});
+    const contextLength = typeof raw.context_length === "number" ? raw.context_length : undefined;
+    const maxCompletion = typeof topProvider.max_completion_tokens === "number" ? topProvider.max_completion_tokens : undefined;
+    return {
+        id,
+        name: String(raw.name ?? id),
+        inputPerM: input * 1_000_000,
+        outputPerM: output * 1_000_000,
+        cachedInputPerM: Number.isFinite(cached) ? cached * 1_000_000 : undefined,
+        contextLength,
+        maxCompletionTokens: maxCompletion,
+        supportedParameters: Array.isArray(raw.supported_parameters)
+            ? raw.supported_parameters.map((entry) => String(entry))
+            : [],
+        expirationDate: typeof raw.expiration_date === "string" ? raw.expiration_date : null,
+    };
+}
+export function builtInCatalogEntry(model) {
+    // The default model's rates are compile-time constants; its capabilities
+    // are asserted from the shipped configuration (1M context, 64K output,
+    // structured outputs used by every lens).
+    if (model !== BROADSIDE_MODEL)
+        return null;
+    return {
+        id: BROADSIDE_MODEL,
+        name: "Google: Gemini 3.7 Flash (batch)",
+        inputPerM: BROADSIDE_INPUT_PRICE_PER_M,
+        outputPerM: BROADSIDE_OUTPUT_PRICE_PER_M,
+        contextLength: 1_048_576,
+        maxCompletionTokens: 65_536,
+        supportedParameters: ["tools", "structured_outputs", "json_schema", "response_format"],
+        expirationDate: null,
+    };
+}
+export function builtInPricing(model) {
+    const entry = builtInCatalogEntry(model);
+    if (!entry)
+        return null;
+    return { inputPerM: entry.inputPerM, outputPerM: entry.outputPerM, source: "built-in" };
+}
+export async function resolveCatalogEntry(broadsideDir, config, model, apiKey, fetcher = fetch) {
+    // Manual overrides always win for pricing — the user is asserting a rate,
+    // and a config assertion is cheaper to respect than to second-guess.
+    // Capabilities stay unknown in that case: nothing is refused, nothing
+    // is clamped, and the submit text says the pricing came from config.
+    if (config.pricing) {
+        return {
+            model,
+            source: "config",
+            entry: {
+                id: model,
+                name: model,
+                inputPerM: config.pricing.inputPerM,
+                outputPerM: config.pricing.outputPerM,
+                supportedParameters: [],
+            },
+        };
+    }
+    const builtIn = builtInCatalogEntry(model);
+    if (builtIn)
+        return { model, source: "built-in", entry: builtIn };
+    // Unknown model: on-disk cache first, then the live catalog.
+    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) {
+        return { model, source: "cache", entry: cached };
+    }
+    let live = 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);
+    }
+    catch {
+        live = null;
+    }
+    if (live) {
+        const updated = {
+            schema_version: 2,
+            fetched_at: new Date().toISOString(),
+            models: { ...(cache?.models ?? {}) },
+        };
+        updated.models[model] = live;
+        await writeCatalogCache(broadsideDir, updated);
+        return { model, source: "live", entry: live };
+    }
+    throw new Error(`Could not resolve per-token pricing for batch model "${model}". ` +
+        "Set pricing.input_per_m and pricing.output_per_m in .codecarto/broadside/config.yaml " +
+        "(USD per million tokens), or check the model id against https://openrouter.ai/models?variant=batch.");
+}
+export async function resolveModelPricing(broadsideDir, config, model, apiKey, fetcher = fetch) {
+    const { source, entry } = await resolveCatalogEntry(broadsideDir, config, model, apiKey, fetcher);
+    if (!entry)
+        throw new Error(`No pricing resolved for ${model}.`);
+    return { inputPerM: entry.inputPerM, outputPerM: entry.outputPerM, source };
+}
+/** Base slug with the OpenRouter variant suffix (e.g. `:batch`) stripped. */
+function baseSlug(modelId) {
+    const idx = modelId.indexOf(":");
+    return idx >= 0 ? modelId.slice(0, idx) : modelId;
+}
+export async function fetchCodingBenchmarks(apiKey, fetcher = fetch) {
+    try {
+        const resp = await fetcher(`${BROADSIDE_BENCHMARKS_URL}?source=artificial-analysis&task_type=coding`, {
+            method: "GET",
+            headers: { Authorization: `Bearer ${apiKey}` },
+            signal: AbortSignal.timeout(30_000),
+        });
+        const data = (await resp.json());
+        const byBaseSlug = {};
+        for (const row of data.data ?? []) {
+            const slug = baseSlug(String(row.model_permaslug ?? ""));
+            if (!slug)
+                continue;
+            const toIndex = (v) => (typeof v === "number" && Number.isFinite(v) ? v : undefined);
+            byBaseSlug[slug] = {
+                codingIndex: toIndex(row.coding_index),
+                intelligenceIndex: toIndex(row.intelligence_index),
+            };
+        }
+        return { byBaseSlug, meta: data.meta ?? {} };
+    }
+    catch {
+        return null;
+    }
+}
+export async function listBatchModels(broadsideDir, config, apiKey, opts = {}) {
+    const fetcher = opts.fetcher ?? fetch;
+    const resp = await fetcher(BROADSIDE_MODELS_URL, {
+        method: "GET",
+        headers: { Authorization: `Bearer ${apiKey}` },
+        signal: AbortSignal.timeout(30_000),
+    });
+    const data = (await resp.json());
+    const entries = [];
+    const seen = new Set();
+    for (const raw of data.data ?? []) {
+        const entry = parseCatalogEntry(raw);
+        if (!entry || seen.has(entry.id))
+            continue;
+        seen.add(entry.id);
+        if (!entry.id.endsWith(":batch"))
+            continue;
+        entries.push(entry);
+    }
+    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: {} };
+    for (const entry of entries)
+        cache.models[entry.id] = entry;
+    await writeCatalogCache(broadsideDir, cache);
+    const benchmarks = opts.includeBenchmarks ? await fetchCodingBenchmarks(apiKey, fetcher) : null;
+    return { entries, source: "live", benchmarks, defaultModel: config.model };
+}
+export async function submitBatch(batchRequests, apiKey, fetcher = fetch, model = BROADSIDE_MODEL) {
+    // The OpenRouter batch endpoint stream-parses the body and requires
+    // `endpoint` and `model` to serialize before `requests` — key order matters.
+    const payload = {
+        endpoint: "/v1/chat/completions",
+        model,
+        requests: batchRequests,
+    };
+    const resp = await fetcher(BROADSIDE_BATCH_URL, {
+        method: "POST",
+        headers: {
+            Authorization: `Bearer ${apiKey}`,
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify(payload),
+        signal: AbortSignal.timeout(30_000),
+    });
+    const data = (await resp.json());
+    if (resp.status !== 202) {
+        return { batchId: "", status: "rejected", error: data };
+    }
+    return { batchId: String(data.id), status: String(data.status) };
+}
+export async function fetchBatch(batchId, apiKey, fetcher = fetch) {
+    const resp = await fetcher(`${BROADSIDE_BATCH_URL}/${batchId}`, {
+        method: "GET",
+        headers: { Authorization: `Bearer ${apiKey}` },
+        signal: AbortSignal.timeout(30_000),
+    });
+    const data = (await resp.json());
+    // 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;
+    return data;
+}
+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;
+    for (;;) {
+        let batch;
+        try {
+            batch = await fetchBatch(batchId, apiKey, fetcher);
+        }
+        catch {
+            if (Date.now() >= deadline)
+                return { id: batchId, status: "timeout" };
+            await sleep(intervalMs);
+            continue;
+        }
+        const httpStatus = Number(batch.http_status ?? 200);
+        if (httpStatus === 401 || httpStatus === 403) {
+            return { id: batchId, status: "auth-failed", error: batch.error ?? batch };
+        }
+        const status = String(batch.status ?? "unknown");
+        const counts = (batch.request_counts ?? {});
+        opts.onStatus?.(status, counts);
+        if (["completed", "failed", "expired", "cancelled", "auth-failed"].includes(status))
+            return batch;
+        if (Date.now() >= deadline)
+            return { id: batchId, status: "timeout" };
+        await sleep(intervalMs);
+    }
+}
+/**
+ * Poll several batch ids in parallel against one shared deadline. Collect
+ * previously polled one lens at a time, so a slow first lens serialized the
+ * wall clock for lenses that had already finished server-side (#136). The
+ * onStatus callback identifies the lens so progress output stays readable
+ * even while the polls interleave.
+ */
+export async function pollBatchesConcurrently(entries, apiKey, opts = {}) {
+    const results = new Map();
+    const deadlineMs = opts.deadlineMs ?? BROADSIDE_DEFAULT_POLL_BUDGET_MS;
+    await Promise.all(entries.map(async ({ lensId, batchId }) => {
+        const batch = await pollBatchUntilTerminal(batchId, apiKey, {
+            deadlineMs,
+            fetcher: opts.fetcher,
+            pollIntervalMs: opts.pollIntervalMs,
+            onStatus: (status, counts) => opts.onStatus?.(lensId, status, counts),
+        });
+        results.set(batchId, batch);
+    }));
+    return results;
+}
+// ---------- 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;
+    // Resolve a catalog entry per distinct model before anything is submitted:
+    // the guardrail must know real per-token rates, and every lens requires
+    // 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 modelForLens = (lensId) => config.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);
+        const entry = catalog.entry;
+        const supportsStructuredOutputs = entry.supportedParameters.length === 0 ||
+            entry.supportedParameters.some((p) => ["structured_outputs", "json_schema", "response_format", "structuredoutputs"].includes(p.toLowerCase()));
+        if (!supportsStructuredOutputs) {
+            throw new Error(`Batch model "${candidate}" does not advertise structured-output support ` +
+                `(supported_parameters: ${entry.supportedParameters.join(", ") || "unknown"}), but every ` +
+                "Broad-Side lens requires json_schema response_format. Choose another batch model " +
+                "(codecarto_broadside action 'models') or pass a pricing override only if you know it works.");
+        }
+        resolved.set(candidate, {
+            entry,
+            supportsStructuredOutputs,
+            pricing: { inputPerM: entry.inputPerM, outputPerM: entry.outputPerM, source: catalog.source },
+            // Respect the provider's completion ceiling: a request asking for more
+            // output than the model can produce fails the whole batch.
+            ...(entry.maxCompletionTokens !== undefined && { outputCap: entry.maxCompletionTokens }),
+        });
+    }
+    const pricing = resolved.get(model).pricing;
+    const outputCap = resolved.get(model).outputCap;
+    const defaultEntry = resolved.get(model).entry;
+    const limit = opts.maxCost ?? config.maxCost;
+    // Incremental re-scouting (#142): diff against the previous run's HEAD
+    // and scan only the modules whose files changed. Falls back to a full
+    // scan when there is no prior run, the tree is dirty, or the diff fails.
+    const sourceHead = await gitHead(cwd);
+    const sourceDirty = await gitDirty(cwd);
+    let baseHead = null;
+    let changed = null;
+    if (opts.incremental) {
+        const state = await loadBroadsideState(broadsideDir);
+        // The baseline is the most recent run that recorded a HEAD — a
+        // submit-only run (never collected) is still a valid committed base.
+        const previous = [...state.runs].reverse().find((r) => r.sourceHead);
+        if (previous?.sourceHead && !sourceDirty) {
+            baseHead = previous.sourceHead;
+            changed = await changedFilesSince(cwd, baseHead);
+        }
+    }
+    // Slice offline first so the estimate covers every request we would send.
+    const slicesByLens = new Map();
+    let estimatedInputTokens = 0;
+    let estimatedOutputTokens = 0;
+    let estimatedTotalCost = 0;
+    const perLensEstimate = [];
+    for (const lensId of lensIds) {
+        const lens = getLens(lensId);
+        let slices = await gatherSlices(cwd, lens, info);
+        if (changed) {
+            // Repo-info slices (empty files, e.g. architecture) always run;
+            // file-backed slices run only when one of their files changed.
+            slices = slices.filter((s) => s.files.length === 0 || s.files.some((f) => changed.has(f)));
+        }
+        slicesByLens.set(lensId, slices);
+        const lensModel = modelForLens(lensId);
+        const { pricing: lensPricing, outputCap: lensOutputCap } = resolved.get(lensModel);
+        const maxTokens = lensOutputCap ? Math.min(lens.maxTokens, lensOutputCap) : lens.maxTokens;
+        const estimate = estimateCost(lens, slices, lensPricing, maxTokens);
+        estimatedInputTokens += estimate.inputTokens;
+        estimatedOutputTokens += estimate.outputTokens;
+        estimatedTotalCost += estimate.cost;
+        perLensEstimate.push({
+            lens,
+            cost: estimate.cost,
+            maxTokens,
+            lensModel,
+            lensPricing,
+            ...(lensOutputCap !== undefined && { lensOutputCap }),
+        });
+    }
+    const exceedsLimit = limit > 0 && estimatedTotalCost > limit;
+    if (opts.confirm) {
+        const approved = await opts.confirm({
+            model,
+            pricing,
+            lenses: perLensEstimate.map(({ lens, cost, maxTokens, lensModel, lensPricing }) => ({
+                lensId: lens.id,
+                name: lens.name,
+                slices: (slicesByLens.get(lens.id) ?? []).length,
+                maxTokens,
+                cost,
+                model: lensModel,
+                pricing: lensPricing,
+            })),
+            mixedModels: perLensEstimate.some(({ lensModel }) => lensModel !== model),
+            totalCost: estimatedTotalCost,
+            inputTokens: estimatedInputTokens,
+            outputTokens: estimatedOutputTokens,
+            maxCost: limit,
+            exceedsLimit,
+            baseHead,
+            sourceDirty,
+            ...(outputCap !== undefined && { outputCap }),
+        });
+        if (!approved)
+            throw new BroadsideCancelledError();
+    }
+    else if (exceedsLimit && !opts.force) {
+        const breakdown = perLensEstimate
+            .map(({ lens, cost, lensModel }) => `  ${lens.name}: ~$${cost.toFixed(4)}${lensModel === model ? "" : ` (${lensModel})`}`)
+            .join("\n");
+        throw new Error(`Estimated Broad-Side cost ~$${estimatedTotalCost.toFixed(4)} exceeds the run limit ` +
+            `$${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);
+    const runId = new Date().toISOString().replace(/[:.]/g, "-");
+    const run = {
+        id: runId,
+        createdAt: new Date().toISOString(),
+        model,
+        lenses: [...lensIds],
+        status: "in-flight",
+        outputDir: runId,
+        batches: {},
+        synthesis: { status: "pending" },
+        triage: { status: "pending" },
+        pricing,
+        maxCost: limit > 0 ? limit : undefined,
+        outputCap,
+        sourceHead,
+        sourceDirty,
+        baseHead,
+    };
+    state.runs.push(run);
+    await saveBroadsideState(broadsideDir, state);
+    const requestsByCustomId = {};
+    const submissions = [];
+    // Submit from the estimate rather than recomputing: the user approved that
+    // breakdown, so the request that fires must be the one that was priced.
+    for (const priced of perLensEstimate) {
+        const { lens, maxTokens, lensModel, lensOutputCap } = priced;
+        const lensId = lens.id;
+        const slices = slicesByLens.get(lensId) ?? [];
+        const requests = slices.map((sl, i) => buildBatchRequest(lens, info, sl, i, slices.length, lensModel, maxTokens));
+        for (const request of requests)
+            requestsByCustomId[request.custom_id] = request;
+        const entry = {
+            batchId: "",
+            requests: requests.length,
+            status: "submitting",
+            submittedAt: new Date().toISOString(),
+            estimatedCost: priced.cost,
+            // Recorded per lens so collect's truncation retry re-submits against
+            // the model and ceiling this lens actually used, not the run default.
+            ...(lensModel !== model && { model: lensModel }),
+            ...(lensOutputCap !== undefined && { outputCap: lensOutputCap }),
+        };
+        run.batches[lensId] = entry;
+        if (requests.length === 0) {
+            // No files matched the lens's globs. That is a coverage gap to
+            // report, not a batch to submit — the API rejects empty batches.
+            entry.status = "skipped";
+            continue;
+        }
+        submissions.push((async () => {
+            // A network-level throw (DNS, abort, TLS) must not strand the
+            // entry in "submitting" forever — allSettled would swallow the
+            // rejection and collect would never see a terminal status.
+            try {
+                const { batchId, status, error } = await submitBatch(requests, apiKey, opts.fetcher, lensModel);
+                entry.batchId = batchId;
+                entry.status = status;
+                if (error)
+                    entry.error = error;
+            }
+            catch (error) {
+                entry.status = "rejected";
+                entry.error = error instanceof Error ? error.message : String(error);
+            }
+        })());
+    }
+    await Promise.allSettled(submissions);
+    await saveBroadsideState(broadsideDir, state);
+    // 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
+    // submit and collect still leaves the retry input on disk.
+    const runDir = join(broadsideDir, runId);
+    await mkdir(runDir, { recursive: true });
+    await writeFile(join(runDir, "requests.json"), `${JSON.stringify(requestsByCustomId, null, "\t")}\n`, "utf8");
+    return {
+        runId,
+        outputDir: join(".codecarto", BROADSIDE_DIR, runId),
+        batches: run.batches,
+        estimatedTotalCost,
+        estimatedInputTokens,
+        estimatedOutputTokens,
+        pricing,
+        maxCost: limit > 0 ? limit : undefined,
+        // modelInfo describes the run's default model. Per-lens overrides are
+        // recorded on their own batch entries.
+        modelInfo: {
+            contextLength: defaultEntry.contextLength,
+            maxCompletionTokens: defaultEntry.maxCompletionTokens,
+            supportsStructuredOutputs: defaultEntry.supportedParameters.length === 0
+                ? undefined
+                : resolved.get(model).supportsStructuredOutputs,
+            expirationDate: defaultEntry.expirationDate ?? null,
+        },
+    };
+}
+function extractContent(result) {
+    const response = result.response;
+    if (!response?.body)
+        return null;
+    const body = response.body;
+    const choices = body.choices;
+    const message = choices?.[0]?.message;
+    return typeof message?.content === "string" ? message.content : null;
+}
+/**
+ * Parse lens content as JSON, tolerating the markdown code fences some models
+ * wrap structured output in (the same tolerance OpenRouter's headless-agent
+ * scaffold ships for --output-schema). Returns null when the content is not
+ * JSON at all — which for a strict json_schema request means the output was
+ * truncated at max_tokens, not that the model chose prose.
+ */
+export function parseLensJson(content) {
+    const trimmed = content.trim();
+    const fenced = /^```(?:json)?\s*\n?([\s\S]*?)\n?```\s*$/.exec(trimmed);
+    const candidate = fenced ? fenced[1].trim() : trimmed;
+    if (!candidate.startsWith("{") && !candidate.startsWith("["))
+        return null;
+    try {
+        return JSON.parse(candidate);
+    }
+    catch {
+        return null;
+    }
+}
+export async function saveLensResults(runDir, lensId, batch) {
+    const results = Array.isArray(batch.results) ? batch.results : [];
+    const out = [];
+    for (const result of results) {
+        const customId = String(result.custom_id ?? "unknown");
+        const content = extractContent(result);
+        if (content === null) {
+            if (result.error) {
+                await writeFile(join(runDir, `${sanitizeId(customId)}.error.json`), `${JSON.stringify(result.error, null, "\t")}\n`, "utf8");
+            }
+            continue;
+        }
+        const parsed = parseLensJson(content);
+        const truncated = parsed === null;
+        if (parsed !== null) {
+            await writeFile(join(runDir, `${sanitizeId(customId)}.json`), `${JSON.stringify(parsed, null, "\t")}\n`, "utf8");
+        }
+        else {
+            // Save the raw bytes verbatim so nothing is lost, but name the
+            // gap: an unparseable strict-schema response is a truncation.
+            await writeFile(join(runDir, `${sanitizeId(customId)}.json`), `${content}\n`, "utf8");
+        }
+        await writeFile(join(runDir, `${sanitizeId(customId)}.md`), renderFindingsMarkdown(content), "utf8");
+        out.push({
+            lensId,
+            customId,
+            moduleName: String(customId).replace(/^[a-z]+-/, ""),
+            content,
+            raw: result,
+            truncated,
+        });
+    }
+    return out;
+}
+async function loadStoredRequests(runDir) {
+    const path = join(runDir, "requests.json");
+    if (!(await pathExists(path)))
+        return {};
+    try {
+        const parsed = JSON.parse(await readFile(path, "utf8"));
+        return parsed && typeof parsed === "object" ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+// ---------- post-lens passes: synthesis + triage ----------
+function buildSynthesisRequest(findingsText, truncatedNote, model) {
+    return {
+        custom_id: "synthesis",
+        body: {
+            model,
+            messages: [
+                {
+                    role: "system",
+                    content: "You are a technical editor synthesizing multiple analysis reports about a single " +
+                        "codebase into one coherent summary. The reports come from different lenses — " +
+                        "architecture, API surface, security review, defect scanning, convention extraction, " +
+                        "and porting assessment. Cross-reference findings across lenses: if a security issue " +
+                        "also appears as a defect, merge them. Produce a JSON object following the " +
+                        "synthesis_report schema. Prioritize the most actionable findings. " +
+                        "Be honest about gaps — if a lens found nothing, say 'no issues found' rather than " +
+                        "inventing problems. These are scouting signals from a batch model, not verified " +
+                        "claims; note that in the summary.",
+                },
+                {
+                    role: "user",
+                    content: "Synthesize these analysis reports into a single summary.\n\n" +
+                        findingsText +
+                        truncatedNote +
+                        "\nReturn the synthesis_report JSON schema.",
+                },
+            ],
+            response_format: { type: "json_schema", json_schema: SCHEMAS.synthesis },
+            max_tokens: 12_000,
+        },
+    };
+}
+function buildTriageRequest(findingsText, truncatedNote, model) {
+    return {
+        custom_id: "triage",
+        body: {
+            model,
+            messages: [
+                {
+                    role: "system",
+                    content: "You are a senior engineering lead turning unverified scouting findings into a " +
+                        "prioritized work order. Given the findings below, produce a JSON object following " +
+                        "the triage_report schema. Score every lead by impact and fix difficulty, assign a " +
+                        "priority (P0 urgent/safety-critical to P3 nice-to-have), give a rough effort " +
+                        "estimate, group the queue by module where sensible, and justify each call in the " +
+                        "rationale. Merge duplicate leads instead of listing them twice. Drop leads that are " +
+                        "too vague to act on and record each drop in omitted with the reason. These findings " +
+                        "are UNVERIFIED scouting signals from a cheap batch model: the queue is a starting " +
+                        "point for re-verification, not a commitment — say so in the summary, and never " +
+                        "inflate a severity you cannot see evidence for.",
+                },
+                {
+                    role: "user",
+                    content: "Triage these scouting findings into a prioritized work order.\n\n" +
+                        findingsText +
+                        truncatedNote +
+                        "\nReturn the triage_report JSON schema.",
+                },
+            ],
+            response_format: { type: "json_schema", json_schema: SCHEMAS.triage },
+            max_tokens: 10_000,
+        },
+    };
+}
+function parseTriageItems(content) {
+    try {
+        const parsed = JSON.parse(content);
+        const items = Array.isArray(parsed.items) ? parsed.items : [];
+        return items
+            .filter((item) => typeof item.title === "string")
+            .map((item) => ({
+            title: String(item.title),
+            severity: String(item.severity ?? "unknown"),
+            module: String(item.module ?? "unknown"),
+            impact: (["high", "medium", "low"].includes(String(item.impact)) ? String(item.impact) : "medium"),
+            difficulty: (["high", "medium", "low"].includes(String(item.difficulty)) ? String(item.difficulty) : "medium"),
+            priority: String(item.priority ?? "?"),
+            effort_estimate: String(item.effort_estimate ?? ""),
+            rationale: String(item.rationale ?? ""),
+        }));
+    }
+    catch {
+        return [];
+    }
+}
+export async function runBroadsideCollect(cwd, apiKey, opts = {}) {
+    const broadsideDir = broadsideDirFor(cwd);
+    const state = await loadBroadsideState(broadsideDir);
+    const run = state.runs[state.runs.length - 1];
+    if (!run) {
+        throw new Error("No Broad-Side run recorded. Call codecarto_broadside with action 'submit' first.");
+    }
+    const runDir = join(broadsideDir, run.outputDir);
+    await mkdir(runDir, { recursive: true });
+    const deadline = Date.now() + (opts.waitMs ?? BROADSIDE_DEFAULT_POLL_BUDGET_MS);
+    let totalCost = 0;
+    let resultCount = 0;
+    let truncatedCount = 0;
+    const lensOutcomes = {};
+    const allLensResults = [];
+    // Terminal entries are settled already; everything else polls in parallel
+    // against one shared deadline (#136), then results save in lens order so
+    // output layout stays deterministic.
+    const inFlight = [];
+    for (const lensId of run.lenses) {
+        const entry = run.batches[lensId];
+        if (!entry || !entry.batchId) {
+            lensOutcomes[lensId] = { status: entry?.status ?? "failed", resultCount: 0 };
+            continue;
+        }
+        if (["completed", "failed", "expired", "cancelled", "auth-failed", "skipped", "rejected"].includes(entry.status)) {
+            totalCost += entry.cost ?? 0;
+            resultCount += entry.resultCount ?? 0;
+            lensOutcomes[lensId] = { status: entry.status, cost: entry.cost, resultCount: entry.resultCount };
+            continue;
+        }
+        inFlight.push({ lensId, batchId: entry.batchId });
+    }
+    const polled = await pollBatchesConcurrently(inFlight, apiKey, {
+        deadlineMs: Math.max(0, deadline - Date.now()),
+        fetcher: opts.fetcher,
+        onStatus: opts.onStatus,
+    });
+    for (const { lensId } of inFlight) {
+        const entry = run.batches[lensId];
+        if (!entry)
+            continue;
+        const batch = polled.get(entry.batchId) ?? { id: entry.batchId, status: "timeout" };
+        const status = String(batch.status ?? "unknown");
+        entry.status = status;
+        if (status === "completed") {
+            const usage = (batch.usage ?? {});
+            const cost = typeof usage.cost === "number" ? usage.cost : undefined;
+            entry.cost = cost;
+            entry.completedAt = new Date().toISOString();
+            const stored = await saveLensResults(runDir, lensId, batch);
+            entry.resultCount = stored.length;
+            const truncated = stored.filter((s) => s.truncated).length;
+            allLensResults.push(...stored);
+            resultCount += stored.length;
+            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 };
+        }
+        else if (batch.error) {
+            entry.error = batch.error;
+            lensOutcomes[lensId] = { status, cost: entry.cost, resultCount: entry.resultCount };
+        }
+        await saveBroadsideState(broadsideDir, state);
+    }
+    // #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.
+    let retriedCount = 0;
+    if (opts.retryTruncated !== false && truncatedCount > 0) {
+        const requestsByCustomId = await loadStoredRequests(runDir);
+        for (const stored of allLensResults) {
+            if (!stored.truncated)
+                continue;
+            const original = requestsByCustomId[stored.customId];
+            if (!original)
+                continue;
+            const lensEntry = run.batches[stored.lensId];
+            // A lens may have run on its own model (config `lens_models`), with its
+            // own completion ceiling. Re-submitting against the run default would
+            // change the model mid-run and could exceed that lens's real ceiling.
+            const lensModel = lensEntry?.model ?? run.model;
+            const lensCap = lensEntry?.outputCap ?? run.outputCap;
+            const previousMax = original.body.max_tokens ?? getLens(stored.lensId).maxTokens;
+            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 },
+            };
+            try {
+                const { batchId, error } = await submitBatch([bumped], apiKey, opts.fetcher, lensModel);
+                if (error)
+                    continue;
+                const batch = await pollBatchUntilTerminal(batchId, apiKey, {
+                    deadlineMs: BROADSIDE_DEFAULT_POLL_BUDGET_MS,
+                    onStatus: (status, counts) => opts.onStatus?.(`${stored.lensId}:retry`, status, counts),
+                    fetcher: opts.fetcher,
+                });
+                if (batch.status !== "completed")
+                    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);
+                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)) {
+            if (outcome.truncated !== undefined) {
+                outcome.truncated = allLensResults.filter((s) => s.lensId === lensId && s.truncated).length;
+            }
+        }
+        await saveBroadsideState(broadsideDir, state);
+    }
+    // Synthesis + triage: cross-lens post-passes, only after every lens batch
+    // is terminal. Triage turns the leads into a prioritized work order.
+    run.triage ??= { status: "pending" };
+    let topFindings = [];
+    let topTriageItems = [];
+    const wantSynthesis = opts.includeSynthesis !== false;
+    const wantTriage = opts.includeTriage !== false;
+    if ((wantSynthesis || wantTriage) && allLensResults.length > 0) {
+        const allTerminal = run.lenses.every((lensId) => {
+            const entry = run.batches[lensId];
+            return entry && ["completed", "failed", "expired", "cancelled", "auth-failed", "skipped", "rejected"].includes(entry.status);
+        });
+        if (allTerminal && (run.synthesis.status === "pending" || run.triage.status === "pending")) {
+            const findingsText = allLensResults
+                .map((r) => `## ${r.lensId} — ${r.customId}\n\n${r.content}\n`)
+                .join("\n");
+            const truncatedNote = truncatedCount > 0
+                ? `\n\nNOTE: ${truncatedCount} lens result(s) were truncated at the output token limit and are ` +
+                    "not included above. Any gap they would have covered is unrepresented — do not treat " +
+                    "silence on a module as a clean bill.\n"
+                : "";
+            // Both post-passes consume the same findings; they run as two
+            // batches (different response_format schemas cannot share one)
+            // submitted together and polled in turn.
+            const passes = [
+                ...(wantSynthesis && run.synthesis.status === "pending"
+                    ? [{
+                            kind: "synthesis",
+                            request: buildSynthesisRequest(findingsText, truncatedNote, run.model),
+                            entry: run.synthesis,
+                        }]
+                    : []),
+                ...(wantTriage && run.triage.status === "pending"
+                    ? [{
+                            kind: "triage",
+                            request: buildTriageRequest(findingsText, truncatedNote, run.model),
+                            entry: run.triage,
+                        }]
+                    : []),
+            ];
+            const submitted = new Map();
+            await Promise.allSettled(passes.map(async (pass) => {
+                pass.entry.status = "submitted";
+                try {
+                    const { batchId, error } = await submitBatch([pass.request], apiKey, opts.fetcher, run.model);
+                    if (error) {
+                        pass.entry.status = "failed";
+                        return;
+                    }
+                    pass.entry.batchId = batchId;
+                    submitted.set(batchId, { batchId, pass });
+                }
+                catch {
+                    pass.entry.status = "failed";
+                }
+            }));
+            await saveBroadsideState(broadsideDir, state);
+            for (const { batchId, pass } of submitted.values()) {
+                const batch = await pollBatchUntilTerminal(batchId, apiKey, {
+                    deadlineMs: BROADSIDE_DEFAULT_POLL_BUDGET_MS,
+                    onStatus: (status, counts) => opts.onStatus?.(pass.kind, status, counts),
+                    fetcher: opts.fetcher,
+                });
+                if (batch.status === "completed") {
+                    const usage = (batch.usage ?? {});
+                    const cost = typeof usage.cost === "number" ? usage.cost : undefined;
+                    pass.entry.status = "completed";
+                    pass.entry.cost = cost;
+                    totalCost += cost ?? 0;
+                    const results = Array.isArray(batch.results) ? batch.results : [];
+                    const content = results.length > 0 ? extractContent(results[0]) : null;
+                    if (content !== null) {
+                        await writeFile(join(runDir, `${pass.kind}.json`), `${content}\n`, "utf8");
+                        await writeFile(join(runDir, `${pass.kind}.md`), renderFindingsMarkdown(content), "utf8");
+                        if (pass.kind === "synthesis") {
+                            topFindings = parseSynthesisTopFindings(content);
+                        }
+                        else {
+                            topTriageItems = parseTriageItems(content);
+                        }
+                    }
+                }
+                else if (batch.error) {
+                    pass.entry.status = "failed";
+                }
+                await saveBroadsideState(broadsideDir, state);
+            }
+        }
+    }
+    const terminal = run.lenses.every((lensId) => {
+        const entry = run.batches[lensId];
+        return entry && ["completed", "failed", "expired", "cancelled", "auth-failed", "skipped", "rejected"].includes(entry.status);
+    });
+    run.status = terminal ? (resultCount > 0 ? "completed" : "failed") : "partial";
+    run.totalCost = totalCost;
+    await saveBroadsideState(broadsideDir, state);
+    await writeFile(join(runDir, "run-meta.json"), `${JSON.stringify({
+        experimental: true,
+        method: "Broad-Side (OpenRouter Batch API)",
+        model: run.model,
+        pricing: run.pricing,
+        max_cost: run.maxCost,
+        run_id: run.id,
+        created_at: run.createdAt,
+        status: run.status,
+        total_cost: totalCost,
+        result_count: resultCount,
+        truncated_count: truncatedCount,
+        retried_count: retriedCount,
+        synthesis: run.synthesis,
+        triage: run.triage,
+        lenses: run.lenses,
+        // Which lens ran on which model. Absent means the run default —
+        // a reader comparing two runs needs to know a lens changed model.
+        lens_models: Object.fromEntries(Object.entries(run.batches)
+            .filter(([, batch]) => batch?.model)
+            .map(([lensId, batch]) => [lensId, batch.model])),
+        disclaimer: "Findings are unverified scouting signals from a batch model, not validated claims. " +
+            "Re-verify every file:line lead with the interactive pipeline or by hand.",
+    }, null, "\t")}\n`, "utf8");
+    return {
+        runId: run.id,
+        status: run.status,
+        totalCost,
+        resultCount,
+        truncatedCount,
+        retriedCount,
+        lensOutcomes,
+        synthesis: run.synthesis,
+        triage: run.triage,
+        topFindings,
+        topTriageItems,
+    };
+}
+export async function runBroadsideStatus(cwd) {
+    const broadsideDir = broadsideDirFor(cwd);
+    const state = await loadBroadsideState(broadsideDir);
+    return { state };
+}
+// ---------- rendering ----------
+export function renderFindingsMarkdown(content) {
+    const parsed = parseLensJson(content);
+    if (parsed === null)
+        return content;
+    return formatAsMarkdown(parsed);
+}
+function formatAsMarkdown(value, depth = 0) {
+    const indent = "\t".repeat(depth);
+    if (Array.isArray(value)) {
+        const lines = [];
+        for (let i = 0; i < value.length; i++) {
+            const item = value[i];
+            if (item && typeof item === "object") {
+                const title = (item.title ?? item.name ?? item.module ?? item.area ?? item.platform ?? "");
+                lines.push(`${indent}${i + 1}. ${title}`);
+                lines.push(formatAsMarkdown(item, depth + 1));
+            }
+            else {
+                lines.push(`${indent}- ${String(item)}`);
+            }
+        }
+        return lines.join("\n");
+    }
+    if (value && typeof value === "object") {
+        const lines = [];
+        for (const [key, entryValue] of Object.entries(value)) {
+            if (entryValue && typeof entryValue === "object") {
+                lines.push(`${indent}**${key}**:`);
+                lines.push(formatAsMarkdown(entryValue, depth + 1));
+            }
+            else {
+                lines.push(`${indent}- **${key}**: ${String(entryValue)}`);
+            }
+        }
+        return lines.join("\n");
+    }
+    return `${indent}${String(value)}`;
+}
+function parseSynthesisTopFindings(content) {
+    try {
+        const parsed = JSON.parse(content);
+        const findings = Array.isArray(parsed.top_findings)
+            ? parsed.top_findings
+            : [];
+        return findings
+            .filter((f) => typeof f.title === "string")
+            .map((f) => ({
+            title: String(f.title),
+            severity: String(f.severity ?? "unknown"),
+            sourceLens: String(f.source_lens ?? "unknown"),
+            summary: String(f.summary ?? ""),
+        }));
+    }
+    catch {
+        return [];
+    }
+}
+// ---------- formatting helpers for tool output ----------
+export function estimateSubmitText(result, lenses) {
+    const lines = [
+        `Broad-Side submitted ${result.batches ? Object.keys(result.batches).length : 0} batch(es).`,
+    ];
+    for (const lens of lenses) {
+        const entry = result.batches[lens.id];
+        if (!entry)
+            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}`);
+    }
+    lines.push(`Estimated total: ~$${result.estimatedTotalCost.toFixed(4)}`, `Pricing: $${result.pricing.inputPerM.toFixed(4)}/M in, $${result.pricing.outputPerM.toFixed(4)}/M out (${result.pricing.source})`);
+    if (result.modelInfo.contextLength) {
+        lines.push(`Model: ${result.modelInfo.contextLength.toLocaleString()} context, ${result.modelInfo.maxCompletionTokens?.toLocaleString() ?? "?"} max output`);
+    }
+    if (result.modelInfo.supportsStructuredOutputs === false) {
+        lines.push("Warning: model does not advertise structured-output support; lens JSON may be unreliable.");
+    }
+    if (result.modelInfo.expirationDate) {
+        lines.push(`Warning: this model is deprecated (expires ${result.modelInfo.expirationDate}).`);
+    }
+    if (result.maxCost) {
+        lines.push(`Run limit: $${result.maxCost.toFixed(2)} (enforced on estimate; pass force to override)`);
+    }
+    lines.push(`Results will land in ${result.outputDir}/`, "Call codecarto_broadside with action 'collect' once batches finish, or pass wait_seconds on submit to block.", "Disclaimer: Broad-Side findings are unverified scouting signals from a batch model, not validated claims.");
+    return lines.join("\n");
+}
+export function modelsText(entries, opts) {
+    const lines = [
+        `Batch models on OpenRouter (${entries.length}, cheapest first).`,
+        "",
+        "id | $/M in | $/M out | ctx | max out | structured | coding idx",
+    ];
+    for (const entry of entries) {
+        const bench = opts.benchmarks?.byBaseSlug[baseSlug(entry.id)];
+        const structured = entry.supportedParameters.length === 0
+            ? "?"
+            : entry.supportedParameters.some((p) => ["structured_outputs", "json_schema", "response_format", "structuredoutputs"].includes(p.toLowerCase()))
+                ? "yes"
+                : "no";
+        const coding = bench?.codingIndex !== undefined ? bench.codingIndex.toFixed(1) : "-";
+        const ctx = entry.contextLength
+            ? entry.contextLength >= 1_000_000
+                ? `${(entry.contextLength / 1_000_000).toFixed(1)}M`
+                : `${(entry.contextLength / 1024).toFixed(0)}k`
+            : "?";
+        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}`);
+    }
+    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.");
+    return lines.join("\n");
+}
+export function collectResultText(result) {
+    const lines = [
+        `Broad-Side run ${result.runId}: ${result.status}`,
+        `  Results: ${result.resultCount} | Total cost: $${result.totalCost.toFixed(6)}`,
+    ];
+    for (const lensId of BROADSIDE_LENS_IDS) {
+        const outcome = result.lensOutcomes[lensId];
+        if (!outcome)
+            continue;
+        const truncation = outcome.truncated ? `, ${outcome.truncated} truncated` : "";
+        lines.push(`  ${lensId}: ${outcome.status}` +
+            (outcome.cost !== undefined ? `, $${outcome.cost.toFixed(6)}` : "") +
+            (outcome.resultCount !== undefined ? `, ${outcome.resultCount} result(s)` : "") +
+            truncation);
+    }
+    if (result.retriedCount > 0) {
+        lines.push(`  ↻ ${result.retriedCount} truncated result(s) recovered by re-submission with a doubled output cap.`);
+    }
+    if (result.truncatedCount > 0) {
+        lines.push(`  ⚠ ${result.truncatedCount} result(s) still truncated after retry — their modules are unscouted, not clean.`);
+    }
+    if (result.synthesis.status === "completed") {
+        lines.push(`  synthesis: completed, $${(result.synthesis.cost ?? 0).toFixed(6)}`);
+        if (result.topFindings.length > 0) {
+            lines.push("", "Top findings (unverified leads):");
+            for (const f of result.topFindings.slice(0, 10)) {
+                lines.push(`  [${f.severity}] ${f.title}`);
+            }
+        }
+    }
+    if (result.triage.status === "completed") {
+        lines.push(`  triage: completed, $${(result.triage.cost ?? 0).toFixed(6)}`);
+        if (result.topTriageItems.length > 0) {
+            lines.push("", "Triage — prioritized work order (re-verify before acting):");
+            for (const item of result.topTriageItems.slice(0, 10)) {
+                lines.push(`  ${item.priority} [${item.severity}/${item.module}] ${item.title}` +
+                    (item.effort_estimate ? ` (${item.effort_estimate})` : ""));
+            }
+        }
+    }
+    else if (result.triage.status === "failed") {
+        lines.push("  triage: failed");
+    }
+    lines.push("", "Disclaimer: Broad-Side findings are unverified scouting signals from a batch model, not validated claims.");
+    return lines.join("\n");
+}
+export function statusText(state) {
+    if (state.runs.length === 0) {
+        return "No Broad-Side runs recorded. Call codecarto_broadside with action 'submit' first.";
+    }
+    const lines = [];
+    for (const run of [...state.runs].reverse().slice(0, 3)) {
+        lines.push(`Run ${run.id} — ${run.status}`);
+        for (const lensId of BROADSIDE_LENS_IDS) {
+            const entry = run.batches[lensId];
+            if (!entry)
+                continue;
+            lines.push(`  ${lensId}: ${entry.status}${entry.batchId ? ` (${entry.batchId})` : ""}${entry.cost !== undefined ? `, $${entry.cost.toFixed(6)}` : ""}`);
+        }
+        lines.push(`  synthesis: ${run.synthesis.status}`);
+        lines.push(`  triage: ${run.triage?.status ?? "pending"}`);
+        if (run.totalCost !== undefined)
+            lines.push(`  total cost: $${run.totalCost.toFixed(6)}`);
+    }
+    return lines.join("\n");
+}