codecartographer-pi 0.22.3 → 0.24.0

package/dist/core/broadside.js

@@ -698,6 +698,7 @@ const LENSES = {
                 "**/*handler*",
                 "**/*endpoint*",
             ],
+        fallbackGlobsFor: (info) => [info.sourceGlob],
         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 " +
@@ -718,6 +719,7 @@ const LENSES = {
         globsFor: (info) => info.language === "go"
             ? ["server/**/*.go", "server/*.go", "**/auth*.go", "**/middleware/**/*.go", "SECURITY.md"]
             : ["server/**", "**/auth*", "**/middleware/**", "SECURITY.md"],
+        fallbackGlobsFor: (info) => [info.sourceGlob],
         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, " +
@@ -918,7 +920,7 @@ const SOURCE_SPECS = {
  * file list with uncommitted contents and never saw an untracked file (#248).
  * A target that is not a git repository gets a bounded walk.
  */
-async function listRepoFiles(targetDir) {
+export async function listRepoFiles(targetDir) {
     try {
         const listed = await execFileAsync("git", ["-C", targetDir, "ls-files", "-z", "--cached", "--others", "--exclude-standard"], { maxBuffer: 64 * 1024 * 1024, timeout: GIT_TIMEOUT_MS });
         const deleted = await execFileAsync("git", ["-C", targetDir, "ls-files", "-z", "--deleted"], {
@@ -1198,7 +1200,7 @@ function matchesAnyGlob(path, globs) {
     }
     return false;
 }
-function isSlurpable(relPath) {
+export function isSlurpable(relPath) {
     // A credential store is never a lens input, whatever its globs say (#252).
     if (isSecretFile(relPath))
         return false;
@@ -1237,8 +1239,7 @@ function resolveSliceMode(lens, files, totalChars) {
         return lens.sliceBy;
     return totalChars > lens.maxChars ? "directory" : "none";
 }
-function collectLensFiles(allFiles, lens, info) {
-    const globs = lens.globsFor(info).filter(Boolean);
+function collectFilesMatching(allFiles, lens, globs) {
     if (globs.length === 0)
         return [];
     const out = [];
@@ -1253,6 +1254,30 @@ function collectLensFiles(allFiles, lens, info) {
     }
     return out;
 }
+/**
+ * The files a lens will read: its targeted globs, or — when those match
+ * nothing and the lens declares a fallback — the fallback globs, with a
+ * sentence saying so (#319). The sentence travels to the estimate, the
+ * batch entry, and the prompt, so a fallback scan is never a silent one.
+ */
+export function selectLensFiles(allFiles, lens, info) {
+    const globs = lens.globsFor(info).filter(Boolean);
+    const targeted = collectFilesMatching(allFiles, lens, globs);
+    if (targeted.length > 0 || globs.length === 0 || !lens.fallbackGlobsFor)
+        return { files: targeted };
+    const fallbackGlobs = lens.fallbackGlobsFor(info).filter(Boolean);
+    const files = collectFilesMatching(allFiles, lens, fallbackGlobs);
+    if (files.length === 0)
+        return { files };
+    return {
+        files,
+        fallback: `no files matched ${globs.join(", ")}${lens.skipTestFiles ? " (test files excluded)" : ""}; ` +
+            `scanned all ${info.language} sources (${fallbackGlobs.join(", ")}) instead`,
+    };
+}
+function collectLensFiles(allFiles, lens, info) {
+    return selectLensFiles(allFiles, lens, info).files;
+}
 async function slurpFileList(targetDir, files, maxChars, redact = true) {
     const slices = [];
     let currentModule = "";
@@ -1329,16 +1354,18 @@ export async function gatherSlices(targetDir, lens, info, opts = {}) {
         return [{ moduleName: "root", content: "", fileCount: 0, chars: 0, files: [] }];
     }
     const { files: allFiles } = await listRepoFiles(targetDir);
-    const files = collectLensFiles(allFiles, lens, info);
+    const { files, fallback } = selectLensFiles(allFiles, lens, info);
     const totalChars = await sumFileSizes(targetDir, files);
     const mode = resolveSliceMode(lens, files, totalChars);
-    if (mode === "none") {
+    const slices = 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, redact);
-    }
-    return slurpFileList(targetDir, files, lens.maxChars, redact);
+        ? await slurpFileList(targetDir, files.map((f) => ({ ...f, moduleName: info.name })), lens.maxChars, redact)
+        : await slurpFileList(targetDir, files, lens.maxChars, redact);
+    if (fallback)
+        for (const slice of slices)
+            slice.fallback = fallback;
+    return slices;
 }
 async function sumFileSizes(targetDir, files) {
     let total = 0;
@@ -1362,7 +1389,17 @@ export function buildBatchRequest(lens, info, slice, index, sliceCount, model =
             model,
             messages: [
                 { role: "system", content: lens.systemPrompt(info) },
-                { role: "user", content: lens.userPrompt(info, slice.content, slice.moduleName) },
+                {
+                    role: "user",
+                    content: 
+                    // A fallback scan is not "server source files": say what it is,
+                    // so the model judges the trust boundary wherever it appears
+                    // and does not report the missing server/ as a finding (#319).
+                    (slice.fallback
+                        ? `NOTE: this repository has no files under the paths this lens usually reads (${slice.fallback}). ` +
+                            "What follows is every source file it has; locate the trust boundary and the request-handling code wherever they live.\n\n"
+                        : "") + lens.userPrompt(info, slice.content, slice.moduleName),
+                },
             ],
             response_format: { type: "json_schema", json_schema: SCHEMAS[lens.schemaName] },
             max_tokens: maxTokensOverride ?? lens.maxTokens,
@@ -1587,6 +1624,10 @@ export async function persistBroadsideRunMerging(broadsideDir, run) {
                 run.triage = onDisk.triage;
             if (retryEntryRank(onDisk.retry) > retryEntryRank(run.retry))
                 run.retry = onDisk.retry;
+            // A verification pass another process recorded is never dropped by
+            // a collect that never knew about it; a newer pass replaces an older.
+            if (onDisk.verify && (!run.verify || onDisk.verify.at > run.verify.at))
+                run.verify = onDisk.verify;
             for (const [lensId, theirs] of Object.entries(onDisk.batches)) {
                 if (theirs && batchEntryRank(theirs) > batchEntryRank(run.batches[lensId]))
                     run.batches[lensId] = theirs;
@@ -2320,11 +2361,14 @@ export async function runBroadsideSubmit(cwd, apiKey, opts = {}) {
         slicesByLens.set(lensId, slices);
         if (slices.length === 0) {
             const globs = lens.globsFor(info).filter(Boolean);
+            const fallbackGlobs = lens.fallbackGlobsFor?.(info).filter(Boolean) ?? [];
             skipReasons.set(lensId, globs.length === 0
                 ? "the lens has no file patterns for this language"
                 : matchedBeforeIncremental > 0
                     ? "incremental: none of this lens's files changed since the previous run"
-                    : `no files matched ${globs.join(", ")}${lens.skipTestFiles ? " (test files excluded)" : ""}`);
+                    : `no files matched ${globs.join(", ")}` +
+                        (fallbackGlobs.length > 0 ? ` or the fallback ${fallbackGlobs.join(", ")}` : "") +
+                        (lens.skipTestFiles ? " (test files excluded)" : ""));
         }
         const lensModel = modelForLens(lensId);
         const { pricing: lensPricing, outputCap: lensOutputCap } = resolved.get(lensModel);
@@ -2347,15 +2391,19 @@ export async function runBroadsideSubmit(cwd, apiKey, opts = {}) {
         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,
-            })),
+            lenses: perLensEstimate.map(({ lens, cost, maxTokens, lensModel, lensPricing }) => {
+                const fallback = (slicesByLens.get(lens.id) ?? []).find((slice) => slice.fallback)?.fallback;
+                return {
+                    lensId: lens.id,
+                    name: lens.name,
+                    slices: (slicesByLens.get(lens.id) ?? []).length,
+                    maxTokens,
+                    cost,
+                    model: lensModel,
+                    pricing: lensPricing,
+                    ...(fallback && { fallback }),
+                };
+            }),
             mixedModels: perLensEstimate.some(({ lensModel }) => lensModel !== model),
             totalCost: estimatedTotalCost,
             inputTokens: estimatedInputTokens,
@@ -2419,12 +2467,15 @@ export async function runBroadsideSubmit(cwd, apiKey, opts = {}) {
         const requests = slices.map((sl, i) => buildBatchRequest(lens, info, sl, i, slices.length, lensModel, maxTokens, config.reasoning ?? undefined));
         for (const request of requests)
             requestsByCustomId[request.custom_id] = request;
+        const fallback = slices.find((slice) => slice.fallback)?.fallback;
         const entry = {
             batchId: "",
             requests: requests.length,
             status: "submitting",
             submittedAt: new Date().toISOString(),
             estimatedCost: priced.cost,
+            // A scan of the fallback scope is recorded as such (#319).
+            ...(fallback && { fallback }),
             // 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 }),
@@ -3256,7 +3307,9 @@ export function estimateSubmitText(result, lenses) {
             ? ` — ${explainBatchError(entry.error)}`
             : !entry.batchId && entry.reason
                 ? ` — ${entry.reason}`
-                : "";
+                : entry.fallback
+                    ? ` — ${entry.fallback}`
+                    : "";
         lines.push(`  ${lens.name}: ${status} (${entry.requests} request(s), ~$${entry.estimatedCost.toFixed(4)})${override}${reason}`);
     }
     if (result.repo) {
@@ -3492,10 +3545,13 @@ export function statusText(state) {
             if (!entry)
                 continue;
             lines.push(`  ${lensId}: ${entry.status}${entry.batchId ? ` (${entry.batchId})` : ""}${entry.cost !== undefined ? `, $${entry.cost.toFixed(6)}` : ""}` +
-                (entry.status === "skipped" && entry.reason ? ` — ${entry.reason}` : ""));
+                (entry.status === "skipped" && entry.reason ? ` — ${entry.reason}` : entry.fallback ? ` — ${entry.fallback}` : ""));
         }
         lines.push(`  synthesis: ${run.synthesis.status}`);
         lines.push(`  triage: ${run.triage?.status ?? "pending"}`);
+        if (run.verify) {
+            lines.push(`  verify: ${run.verify.status} — ${run.verify.confirmed} confirmed of ${run.verify.verified} read on ${run.verify.model}, $${run.verify.cost.toFixed(4)}`);
+        }
         if (run.totalCost !== undefined)
             lines.push(`  total cost: $${run.totalCost.toFixed(6)}`);
     }

package/dist/core/index.d.ts

@@ -16,5 +16,6 @@ export * from "./dashboard.ts";
 export * from "./library.ts";
 export * from "./synthesis.ts";
 export * from "./broadside.ts";
+export * from "./broadside-verify.ts";
 export * from "./secrets.ts";
 export * from "./dashboard-writer.ts";

package/dist/core/index.js

@@ -19,5 +19,6 @@ export * from "./dashboard.js";
 export * from "./library.js";
 export * from "./synthesis.js";
 export * from "./broadside.js";
+export * from "./broadside-verify.js";
 export * from "./secrets.js";
 export * from "./dashboard-writer.js";

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

@@ -1,5 +1,5 @@
 import { type BroadsideLensId } from "../../core/index.ts";
-export type BroadsideAction = "submit" | "collect" | "status" | "models";
+export type BroadsideAction = "submit" | "collect" | "status" | "models" | "verify";
 export interface BroadsideFlags {
     action: BroadsideAction;
     /** Empty means "the repository's default lens set". */
@@ -22,11 +22,13 @@ export interface BroadsideFlags {
     model?: string;
     /** For submit: per-lens model overrides, layered over config.yaml's (#141). */
     lensModels?: Partial<Record<BroadsideLensId, string>>;
+    /** For verify: how many findings to read (#143). */
+    top?: number;
     benchmarks: boolean;
     unknown: string[];
     /** Set on an invalid combination. The caller surfaces it as an error. */
     error?: string;
 }
 /** Every token the completer offers, in the order it offers them. */
-export declare const KNOWN_BROADSIDE_TOKENS: readonly ["submit", "collect", "status", "models", "architecture", "api", "security", "defect", "conventions", "porting", "--incremental", "--no-incremental", "--max-cost=", "--wait=", "--run=", "--model=", "--lens-model=", "--no-synthesis", "--no-triage", "--no-retry-truncated", "--benchmarks"];
+export declare const KNOWN_BROADSIDE_TOKENS: readonly ["submit", "collect", "status", "models", "verify", "architecture", "api", "security", "defect", "conventions", "porting", "--incremental", "--no-incremental", "--max-cost=", "--wait=", "--run=", "--model=", "--lens-model=", "--top=", "--no-synthesis", "--no-triage", "--no-retry-truncated", "--benchmarks"];
 export declare function parseBroadsideFlags(args: string): BroadsideFlags;

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

@@ -6,6 +6,7 @@
 //   /codecarto-broadside collect --wait=900
 //   /codecarto-broadside status
 //   /codecarto-broadside models --benchmarks
+//   /codecarto-broadside verify --top=10       → read the top findings against the source
 //
 // Flags mirror the codecarto_broadside tool parameters, with the negative
 // forms spelled out because a slash command has no place to pass `false`:
@@ -14,8 +15,9 @@
 //   --max-cost=N           --no-retry-truncated
 //   --wait=SECONDS         --benchmarks (models only)
 //   --run=ID (collect only: an older run, as listed by status)
-//   --model=ID (submit only: the run's batch model, as listed by models)
+//   --model=ID (submit: the run's batch model, as listed by models; verify: the sync model to read with)
 //   --lens-model=LENS:ID (submit only, repeatable: one lens on its own model)
+//   --top=N (verify only: how many findings to read, most severe first)
 //
 // A model id itself contains a colon (`vendor/name:batch`), so --lens-model
 // splits on the first colon only: `security:deepseek/deepseek-v4-pro:batch`.
@@ -28,13 +30,14 @@
 // The parser never throws. index.ts decides how to surface unknown tokens and
 // invalid combinations, matching parseNextFlags.
 import { BROADSIDE_LENS_IDS } from "../../core/index.js";
-const ACTIONS = new Set(["submit", "collect", "status", "models"]);
+const ACTIONS = new Set(["submit", "collect", "status", "models", "verify"]);
 /** Every token the completer offers, in the order it offers them. */
 export const KNOWN_BROADSIDE_TOKENS = [
     "submit",
     "collect",
     "status",
     "models",
+    "verify",
     ...BROADSIDE_LENS_IDS,
     "--incremental",
     "--no-incremental",
@@ -43,6 +46,7 @@ export const KNOWN_BROADSIDE_TOKENS = [
     "--run=",
     "--model=",
     "--lens-model=",
+    "--top=",
     "--no-synthesis",
     "--no-triage",
     "--no-retry-truncated",
@@ -122,6 +126,14 @@ export function parseBroadsideFlags(args) {
             result.runId = value || undefined;
             continue;
         }
+        if (token.startsWith("--top=")) {
+            const value = parseNumeric(token, "--top", result);
+            if (value !== undefined && (!Number.isInteger(value) || value < 1))
+                result.error ??= `--top needs a positive whole number (got "${token.slice("--top=".length)}").`;
+            else if (value !== undefined)
+                result.top = value;
+            continue;
+        }
         if (token.startsWith("--model=")) {
             const value = token.slice("--model=".length).trim();
             // An empty value is a mistyped selection, not "use the default":
@@ -167,11 +179,17 @@ export function parseBroadsideFlags(args) {
     if (result.action === "status" && result.waitSeconds !== undefined) {
         result.error ??= "--wait is only meaningful for submit and collect; status reads recorded state.";
     }
-    if (result.runId !== undefined && result.action !== "collect") {
-        result.error ??= `--run is only meaningful for collect (got action "${result.action}").`;
+    if (result.runId !== undefined && result.action !== "collect" && result.action !== "verify") {
+        result.error ??= `--run is only meaningful for collect and verify (got action "${result.action}").`;
+    }
+    if (result.model !== undefined && result.action !== "submit" && result.action !== "verify") {
+        result.error ??= `--model is only meaningful for submit and verify (got action "${result.action}").`;
+    }
+    if (result.top !== undefined && result.action !== "verify") {
+        result.error ??= `--top is only meaningful for verify (got action "${result.action}").`;
     }
-    if (result.model !== undefined && result.action !== "submit") {
-        result.error ??= `--model is only meaningful for submit (got action "${result.action}").`;
+    if (result.action === "verify" && result.waitSeconds !== undefined) {
+        result.error ??= "--wait is only meaningful for submit and collect; verify runs to completion.";
     }
     if (result.lensModels !== undefined && result.action !== "submit") {
         result.error ??= `--lens-model is only meaningful for submit (got action "${result.action}").`;

package/dist/extensions/codecarto/index.js

@@ -10,7 +10,7 @@ import { completeLastToken } from "./completions.js";
 import { buildPiGuideMessage } from "./guide-framing.js";
 import { isCtxLive, notifyCtx } from "./notify.js";
 import { phaseCompactionExtension } from "./phase-compaction.js";
-import { applyAmendment, buildPhasePrompt, buildSkillPrompt, buildValidationSummary, backupWorkspaceState, canonicalPath, copyPackagedWorkspace, computePerPhaseTotals, computeTotals, ConfidentialityMismatchError, createEmptyStatus, DEFAULT_PIPELINE_PATH, describeScaffoldStaleness, deriveSlug, discoverLibrary, describeDanglingCarryForward, describeMissingCompletedOutputs, describeStuckPipeline, expandTilde, getPipelineLabel, getWorkspaceState, isWithinPath, resolveExistingPrefix, BROADSIDE_LENS_IDS, BROADSIDE_SKILL_NAME, BroadsideConfigError, defaultBroadsideConfig, BroadsideCancelledError, broadsideDirFor, collectResultText, estimateSubmitText, getLens, listAmendmentNames, listBatchModels, listGuideTopics, listScaffoldRefreshFiles, listMissingCompletedOutputs, listSkillNames, resolvePipelineOutcome, resolveSkillName, loadAmendmentFile, loadBroadsideConfig, modelsText, runBroadsideCollect, runBroadsideStatus, runBroadsideSubmit, statusText, describeConfigProblems, describeIncrementalFallback, loadCodecartoConfig, loadUsage, loadYamlFile, normalizeForComparison, packagedWorkspaceDir, pathExists, PACKAGE_VERSION, readBroadsideSkill, readGuide, refreshScaffold, PhasePreflightError, PIPELINE_ALIASES, publishEntry, resolvePhase, resolvePipelineChoice, resolvePublishSourceRepo, SourceRepoMismatchError, runPhasePreflight, SCAFFOLD_REFRESH_PROTECTED, seedOrchestratorFiles, stringifySimpleYaml, switchPipeline, validatePhaseOutput, writeLibraryConfig, writeDashboard, } from "../../core/index.js";
+import { applyAmendment, buildPhasePrompt, buildSkillPrompt, buildValidationSummary, backupWorkspaceState, canonicalPath, copyPackagedWorkspace, computePerPhaseTotals, computeTotals, ConfidentialityMismatchError, createEmptyStatus, DEFAULT_PIPELINE_PATH, describeScaffoldStaleness, deriveSlug, discoverLibrary, describeDanglingCarryForward, describeMissingCompletedOutputs, describeStuckPipeline, expandTilde, getPipelineLabel, getWorkspaceState, isWithinPath, resolveExistingPrefix, BROADSIDE_LENS_IDS, BROADSIDE_SKILL_NAME, BroadsideConfigError, defaultBroadsideConfig, BroadsideCancelledError, broadsideDirFor, collectResultText, estimateSubmitText, getLens, listAmendmentNames, listBatchModels, listGuideTopics, listScaffoldRefreshFiles, listMissingCompletedOutputs, listSkillNames, resolvePipelineOutcome, resolveSkillName, loadAmendmentFile, loadBroadsideConfig, modelsText, runBroadsideCollect, runBroadsideStatus, runBroadsideSubmit, runBroadsideVerify, verifyResultText, statusText, describeConfigProblems, describeIncrementalFallback, loadCodecartoConfig, loadUsage, loadYamlFile, normalizeForComparison, packagedWorkspaceDir, pathExists, PACKAGE_VERSION, readBroadsideSkill, readGuide, refreshScaffold, PhasePreflightError, PIPELINE_ALIASES, publishEntry, resolvePhase, resolvePipelineChoice, resolvePublishSourceRepo, SourceRepoMismatchError, runPhasePreflight, SCAFFOLD_REFRESH_PROTECTED, seedOrchestratorFiles, stringifySimpleYaml, switchPipeline, validatePhaseOutput, writeLibraryConfig, writeDashboard, } from "../../core/index.js";
 import { initLibrary } from "../../core/library.js";
 import { resolveUserConfigPath } from "../../core/orchestrator-config.js";
 const STATUS_WIDGET_ID = "codecarto-widget";
@@ -130,11 +130,14 @@ function describeBroadsideEstimate(estimate) {
         `Rates: $${estimate.pricing.inputPerM.toFixed(4)}/M in · $${estimate.pricing.outputPerM.toFixed(4)}/M out`,
         "",
         "Per lens:",
-        ...estimate.lenses.map(({ name, slices, cost, model }) => {
+        ...estimate.lenses.map(({ name, slices, cost, model, fallback }) => {
             // Naming the model only when it differs keeps the common case quiet
             // and makes a mixed-model run impossible to approve without noticing.
             const override = estimate.mixedModels && model !== estimate.model ? ` on ${model}` : "";
-            return `  ${name}: ${slices} slice${slices === 1 ? "" : "s"} — ~$${cost.toFixed(4)}${override}`;
+            // A lens priced on its fallback scope says so here, where the
+            // spend is approved — every source file, not a server directory (#319).
+            const scope = fallback ? `\n    ↳ ${fallback}` : "";
+            return `  ${name}: ${slices} slice${slices === 1 ? "" : "s"} — ~$${cost.toFixed(4)}${override}${scope}`;
         }),
         "",
         `Estimated total: ~$${estimate.totalCost.toFixed(4)} ` +
@@ -992,7 +995,7 @@ export default function codeCartographerExtension(pi) {
         },
     });
     pi.registerCommand("codecarto-broadside", {
-        description: "Batch reconnaissance (Broad-Side): /codecarto-broadside [submit|collect|status|models] [lenses…] [--model=ID] [--lens-model=LENS:ID] [flags]",
+        description: "Batch reconnaissance (Broad-Side): /codecarto-broadside [submit|collect|status|models|verify] [lenses…] [--model=ID] [--lens-model=LENS:ID] [--top=N] [flags]",
         // Completes the token under the cursor, so lens names and flags are
         // offered after the action too, and keeps everything typed before it.
         getArgumentCompletions: (prefix) => completeLastToken(prefix, KNOWN_BROADSIDE_TOKENS.map((value) => ({ value }))),
@@ -1178,6 +1181,35 @@ export default function codeCartographerExtension(pi) {
                 }
                 return;
             }
+            if (flags.action === "verify") {
+                // The verification pass (#143): one sync call per finding with
+                // read-only tools; the widget counts verdicts as they land.
+                const tally = { done: 0 };
+                renderProgress("Reading the top findings against the source…");
+                try {
+                    const verified = await runBroadsideVerify(ctx.cwd, apiKey, {
+                        ...(flags.runId && { runId: flags.runId }),
+                        ...(flags.top !== undefined && { top: flags.top }),
+                        ...(flags.model && { model: flags.model }),
+                        maxCost: flags.maxCost ?? config.maxCost,
+                        signal: ctx.signal,
+                        onProgress: (finding) => {
+                            tally.done += 1;
+                            progress.set(`#${finding.index}`, `${finding.verdict} — ${finding.title}`);
+                            renderProgress(`Verifying findings… ${tally.done} read`);
+                        },
+                    });
+                    const lines = verifyResultText(verified).split("\n");
+                    const confirmed = verified.findings.filter((f) => f.verdict === "confirmed").length;
+                    finish(lines, `Broad-Side verify: ${confirmed} confirmed of ${verified.findings.length} read`, verified.status === "completed" ? "info" : "warning");
+                }
+                catch (error) {
+                    if (ctx.hasUI)
+                        ctx.ui.setWidget(BROADSIDE_WIDGET_ID, undefined);
+                    notifyCtx(ctx, `Broad-Side verify failed: ${error instanceof Error ? error.message : String(error)}`, "error");
+                }
+                return;
+            }
             // action === "collect"
             renderProgress("Polling batches…");
             try {

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

@@ -233,7 +233,7 @@ export declare function handleAmend(args: {
 }>;
 export declare function handleBroadside(args: {
     cwd: string;
-    action: "submit" | "collect" | "status" | "models";
+    action: "submit" | "collect" | "status" | "models" | "verify";
     lenses?: string[];
     api_key?: string;
     wait_seconds?: number;
@@ -247,6 +247,7 @@ export declare function handleBroadside(args: {
     incremental?: boolean;
     model?: string;
     lens_models?: Record<string, string>;
+    top?: number;
 }): Promise<{
     content: {
         type: "text";

package/dist/mcp-server/server.js

@@ -17,7 +17,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { CallToolRequestSchema, ErrorCode, ListToolsRequestSchema, McpError, } from "@modelcontextprotocol/sdk/types.js";
 import { mkdir, readFile, readdir, rename, writeFile } from "node:fs/promises";
 import { basename, isAbsolute, join } from "node:path";
-import { buildPhasePrompt, buildSkillPrompt, buildValidationSummary, BROADSIDE_DIR, broadsideDirFor, BROADSIDE_LENS_IDS, BROADSIDE_SKILL_NAME, BroadsideConfigError, defaultBroadsideConfig, backupWorkspaceState, canonicalPath, copyPackagedWorkspace, collectResultText, completeValidatedPhase, computePerPhaseTotals, computeTotals, createEmptyStatus, DEFAULT_PIPELINE_PATH, deriveSlug, discoverLibrary, describeScaffoldStaleness, detectProvenanceConflicts, estimateSubmitText, getLens, describeDanglingCarryForward, describeMissingCompletedOutputs, describeStuckPipeline, getPipelineLabel, getWorkspaceState, isValidSlug, isWithinPathResolved, listBatchModels, listEntries, listGuideTopics, loadBroadsideConfig, modelsText, readGuide, listMissingCompletedOutputs, listSkillNames, resolvePipelineOutcome, resolveSkillName, loadCodecartoConfig, loadUsage, loadYamlFile, normalizeForComparison, PACKAGE_VERSION, packagedWorkspaceDir, pathExists, PhasePreflightError, previewPublishVersion, publishEntry, reindex as libraryReindex, refreshScaffold, resolvePhase, resolvePipelineChoice, readBroadsideSkill, runBroadsideCollect, runBroadsideStatus, runBroadsideSubmit, seedOrchestratorFiles, statusLineWriter, statusText, stringifySimpleYaml, switchPipeline, validatePhaseOutput, writeLibraryConfig, writeDashboard, } from "../core/index.js";
+import { buildPhasePrompt, buildSkillPrompt, buildValidationSummary, BROADSIDE_DIR, broadsideDirFor, BROADSIDE_LENS_IDS, BROADSIDE_SKILL_NAME, BroadsideConfigError, defaultBroadsideConfig, backupWorkspaceState, canonicalPath, copyPackagedWorkspace, collectResultText, completeValidatedPhase, computePerPhaseTotals, computeTotals, createEmptyStatus, DEFAULT_PIPELINE_PATH, deriveSlug, discoverLibrary, describeScaffoldStaleness, detectProvenanceConflicts, estimateSubmitText, getLens, describeDanglingCarryForward, describeMissingCompletedOutputs, describeStuckPipeline, getPipelineLabel, getWorkspaceState, isValidSlug, isWithinPathResolved, listBatchModels, listEntries, listGuideTopics, loadBroadsideConfig, modelsText, readGuide, listMissingCompletedOutputs, listSkillNames, resolvePipelineOutcome, resolveSkillName, loadCodecartoConfig, loadUsage, loadYamlFile, normalizeForComparison, PACKAGE_VERSION, packagedWorkspaceDir, pathExists, PhasePreflightError, previewPublishVersion, publishEntry, reindex as libraryReindex, refreshScaffold, resolvePhase, resolvePipelineChoice, readBroadsideSkill, runBroadsideCollect, runBroadsideStatus, runBroadsideSubmit, runBroadsideVerify, verifyResultText, seedOrchestratorFiles, statusLineWriter, statusText, stringifySimpleYaml, switchPipeline, validatePhaseOutput, writeLibraryConfig, writeDashboard, } from "../core/index.js";
 import { applyAmendment } from "../core/amendment.js";
 import { appendUsageRun } from "../core/usage.js";
 import { initLibrary } from "../core/library.js";
@@ -1037,8 +1037,8 @@ function resolveBroadsideApiKey(explicit, config) {
 export async function handleBroadside(args) {
     const cwd = await validateCwd(args.cwd);
     const action = args.action ?? "submit";
-    if (!["submit", "collect", "status", "models"].includes(action)) {
-        throw new McpError(ErrorCode.InvalidParams, `Unknown action: ${action}. Valid actions: submit, collect, status, models.`);
+    if (!["submit", "collect", "status", "models", "verify"].includes(action)) {
+        throw new McpError(ErrorCode.InvalidParams, `Unknown action: ${action}. Valid actions: submit, collect, status, models, verify.`);
     }
     // A config.yaml that exists but cannot be read refuses every action that
     // would act on it (#232); status only reads recorded runs, so it answers
@@ -1173,8 +1173,40 @@ export async function handleBroadside(args) {
             maxCost: result.maxCost,
         });
     }
-    // action === "collect"
     const runId = typeof args.run_id === "string" && args.run_id.trim() ? args.run_id.trim() : undefined;
+    if (action === "verify") {
+        // The verification pass (#143): one sync call per finding with read-only
+        // tools, most severe first. `max_cost` is a running cap here — a sync
+        // call's cost is known only when it returns — so the pass stops before
+        // the next finding once reached; absent, config.yaml's cap applies.
+        if (args.top !== undefined && !(typeof args.top === "number" && Number.isInteger(args.top) && args.top >= 1)) {
+            throw new McpError(ErrorCode.InvalidParams, "top must be a positive integer.");
+        }
+        if (args.model !== undefined && !(typeof args.model === "string" && args.model.trim())) {
+            throw new McpError(ErrorCode.InvalidParams, "model must be a non-empty OpenRouter model id.");
+        }
+        const maxCost = typeof args.max_cost === "number" && args.max_cost >= 0 ? args.max_cost : config.maxCost;
+        const verified = await runBroadsideVerify(cwd, apiKey, {
+            ...(runId && { runId }),
+            ...(args.top !== undefined && { top: args.top }),
+            ...(typeof args.model === "string" && args.model.trim() && { model: args.model.trim() }),
+            maxCost,
+            signal: serverLifetime?.signal,
+        }).catch((error) => {
+            throw new McpError(ErrorCode.InvalidRequest, error instanceof Error ? error.message : String(error));
+        });
+        return textResult(verifyResultText(verified), {
+            runId: verified.runId,
+            outputDir: verified.outputDir,
+            status: verified.status,
+            model: verified.model,
+            candidates: verified.candidates,
+            totalCost: verified.totalCost,
+            ...(verified.stoppedByCost && { stoppedByCost: true }),
+            findings: verified.findings,
+        });
+    }
+    // action === "collect"
     const collect = await runBroadsideCollect(cwd, apiKey, {
         waitMs,
         includeSynthesis,
@@ -1502,8 +1534,8 @@ const TOOLS = [
                 cwd: { type: "string", description: "Absolute path to the target repository." },
                 action: {
                     type: "string",
-                    enum: ["submit", "collect", "status", "models"],
-                    description: "submit fires all lens batches and returns batch ids; collect polls submitted batches, saves results, and optionally runs the synthesis pass; status shows recorded runs; models lists batch-capable models with pricing and capabilities.",
+                    enum: ["submit", "collect", "status", "models", "verify"],
+                    description: "submit fires all lens batches and returns batch ids; collect polls submitted batches, saves results, and optionally runs the synthesis pass; status shows recorded runs; models lists batch-capable models with pricing and capabilities; verify reads a collected run's top defect and security findings against the repository with read-only tools (one sync-priced call each, about a cent on the default model) and writes verified.md/verified.json beside triage.md with a verdict per finding: confirmed (a reachable failure, with the trigger), not-a-defect, discarded, or unclear.",
                 },
                 lenses: {
                     type: "array",
@@ -1516,7 +1548,11 @@ const TOOLS = [
                 },
                 run_id: {
                     type: "string",
-                    description: "For collect: the run to collect, as listed by the status action. Defaults to the most recent run; pass this to collect an older run that is still in flight after a newer submit.",
+                    description: "For collect and verify: the run to act on, as listed by the status action. Defaults to the most recent run; pass this to collect an older run that is still in flight after a newer submit.",
+                },
+                top: {
+                    type: "integer",
+                    description: "For verify: how many findings to read, most severe first (default 10). Each costs one sync call; max_cost caps the pass as a running total.",
                 },
                 wait_seconds: {
                     type: "number",
@@ -1536,7 +1572,7 @@ const TOOLS = [
                 },
                 max_cost: {
                     type: "number",
-                    description: "Approximate run expense limit in USD. The submit action estimates the run cost from slice sizes and the configured model's per-token pricing (live OpenRouter lookup, cached 24h) and refuses to submit when the estimate exceeds the limit unless force is true. Falls back to max_cost in .codecarto/broadside/config.yaml, whose default is $1.00; pass 0 for no limit.",
+                    description: "Approximate run expense limit in USD. The submit action estimates the run cost from slice sizes and the configured model's per-token pricing (live OpenRouter lookup, cached 24h) and refuses to submit when the estimate exceeds the limit unless force is true. For verify it is a running cap: the pass stops before the next finding once the calls so far have reached it. Falls back to max_cost in .codecarto/broadside/config.yaml, whose default is $1.00; pass 0 for no limit.",
                 },
                 force: {
                     type: "boolean",
@@ -1552,7 +1588,7 @@ const TOOLS = [
                 },
                 model: {
                     type: "string",
-                    description: "For submit: the OpenRouter batch model for this run (an id ending in :batch, as listed by action 'models'). Falls back to model in .codecarto/broadside/config.yaml, then the shipped default. Pre-flighted like the configured model: priced from the live catalog, refused without structured-output support, clamped to its completion ceiling. The models listing is advisory — some catalog ids have no batch endpoint and are refused at submit, at no cost; the listing tags ids this repository has already seen accepted or refused.",
+                    description: "For verify: the sync (non-batch) OpenRouter model to read with; defaults to the run's model without its :batch suffix. For submit: the OpenRouter batch model for this run (an id ending in :batch, as listed by action 'models'). Falls back to model in .codecarto/broadside/config.yaml, then the shipped default. Pre-flighted like the configured model: priced from the live catalog, refused without structured-output support, clamped to its completion ceiling. The models listing is advisory — some catalog ids have no batch endpoint and are refused at submit, at no cost; the listing tags ids this repository has already seen accepted or refused.",
                 },
                 lens_models: {
                     type: "object",

package/package.json

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