codecartographer-pi 0.23.0 → 0.24.1

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/core/status.d.ts

@@ -2,6 +2,12 @@ import type { ClosureEntry, NormalizedStatus, OpenQuestionEntry, PostPipelineEnt
 export declare const LOCK_RETRY_MS = 125;
 export declare const LOCK_TIMEOUT_MS = 5000;
 export declare const STALE_LOCK_MS = 60000;
+/**
+ * How old the removal lock (`<lock>.break`, see {@link withRemovalLock}) may
+ * be before it is treated as left behind by a crashed process. It is held
+ * across one stat and one rm, so anything this old was abandoned.
+ */
+export declare const BREAK_LOCK_STALE_MS = 5000;
 export declare function assertSafePhaseId(phaseId: string): void;
 /**
  * A YAML scalar as text: strings as written, numbers and booleans spelled
@@ -73,5 +79,13 @@ export interface LockHandle {
  * the token, release removed whoever's lock was there: after a stale break
  * the previous holder's release deleted the new holder's lock, and a third
  * writer walked straight in (#227).
+ *
+ * Every removal — a release or a stale break — happens under the removal
+ * lock (`<lock>.break`) and re-checks what it is about to remove there.
+ * Two waiters that both saw a stale lock used to both `rm` it: the second
+ * `rm` landed after the first waiter had re-created the file, so both held
+ * the lock (#342). A file can only be created while the path is free, and
+ * only a removal-lock holder removes, so what a holder verified is what it
+ * removes.
  */
 export declare function acquireLock(lockPath: string): Promise<LockHandle>;

package/dist/core/status.js

@@ -8,6 +8,12 @@ import { loadYamlFile } from "./yaml.js";
 export const LOCK_RETRY_MS = 125;
 export const LOCK_TIMEOUT_MS = 5000;
 export const STALE_LOCK_MS = 60_000;
+/**
+ * How old the removal lock (`<lock>.break`, see {@link withRemovalLock}) may
+ * be before it is treated as left behind by a crashed process. It is held
+ * across one stat and one rm, so anything this old was abandoned.
+ */
+export const BREAK_LOCK_STALE_MS = LOCK_TIMEOUT_MS;
 export function assertSafePhaseId(phaseId) {
     if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(phaseId)) {
         throw new Error(`Invalid phase id: ${phaseId}`);
@@ -434,6 +440,14 @@ export function applyHandoff(status, handoff) {
  * the token, release removed whoever's lock was there: after a stale break
  * the previous holder's release deleted the new holder's lock, and a third
  * writer walked straight in (#227).
+ *
+ * Every removal — a release or a stale break — happens under the removal
+ * lock (`<lock>.break`) and re-checks what it is about to remove there.
+ * Two waiters that both saw a stale lock used to both `rm` it: the second
+ * `rm` landed after the first waiter had re-created the file, so both held
+ * the lock (#342). A file can only be created while the path is free, and
+ * only a removal-lock holder removes, so what a holder verified is what it
+ * removes.
  */
 export async function acquireLock(lockPath) {
     const startedAt = Date.now();
@@ -464,9 +478,13 @@ export async function acquireLock(lockPath) {
             try {
                 const lockStat = await stat(lockPath);
                 if (Date.now() - lockStat.mtimeMs > STALE_LOCK_MS) {
-                    brokeStale = await describeLockHolder(lockPath);
-                    await rm(lockPath, { force: true }).catch(() => undefined);
-                    continue;
+                    const broken = await breakStaleLock(lockPath);
+                    if (broken) {
+                        brokeStale = broken;
+                        continue;
+                    }
+                    // Another waiter is breaking it, or already has: fall
+                    // through to a wait and try the open again.
                 }
             }
             catch {
@@ -479,6 +497,70 @@ export async function acquireLock(lockPath) {
         }
     }
 }
+/**
+ * Run `remove` while holding `<lockPath>.break`, the lock that serializes
+ * removals of `lockPath`. Waits up to {@link LOCK_TIMEOUT_MS}; a removal lock
+ * older than {@link BREAK_LOCK_STALE_MS} is a crashed remover's and is
+ * cleared. Resolves to `undefined` when the removal lock could not be had
+ * in time — the caller decides what that means.
+ */
+async function withRemovalLock(lockPath, remove) {
+    const breakPath = `${lockPath}.break`;
+    const startedAt = Date.now();
+    while (true) {
+        try {
+            const handle = await open(breakPath, "wx");
+            await handle.close();
+            break;
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            try {
+                const breakStat = await stat(breakPath);
+                if (Date.now() - breakStat.mtimeMs > BREAK_LOCK_STALE_MS) {
+                    await rm(breakPath, { force: true }).catch(() => undefined);
+                    continue;
+                }
+            }
+            catch {
+                continue;
+            }
+            if (Date.now() - startedAt > LOCK_TIMEOUT_MS)
+                return undefined;
+            await sleep(LOCK_RETRY_MS);
+        }
+    }
+    try {
+        return await remove();
+    }
+    finally {
+        await rm(breakPath, { force: true }).catch(() => undefined);
+    }
+}
+/**
+ * Remove a lock older than {@link STALE_LOCK_MS}, under the removal lock and
+ * only if it is still that old there: the holder may have released and a
+ * new one acquired between the caller's stat and this one. Resolves to the
+ * broken lock's holder, or null when nothing was removed.
+ */
+async function breakStaleLock(lockPath) {
+    const broken = await withRemovalLock(lockPath, async () => {
+        let lockStat;
+        try {
+            lockStat = await stat(lockPath);
+        }
+        catch {
+            return null;
+        }
+        if (Date.now() - lockStat.mtimeMs <= STALE_LOCK_MS)
+            return null;
+        const holder = await describeLockHolder(lockPath);
+        await rm(lockPath, { force: true }).catch(() => undefined);
+        return holder;
+    });
+    return broken ?? null;
+}
 /**
  * Remove the lock at `lockPath` only if it is still ours. A lock that vanished
  * (someone broke it as stale) or that now carries another holder's token is
@@ -486,16 +568,25 @@ export async function acquireLock(lockPath) {
  * than removed unverified.
  */
 async function releaseOwnedLock(lockPath, token) {
-    let content;
-    try {
-        content = await readFile(lockPath, "utf8");
-    }
-    catch {
-        return;
-    }
-    if (content.split(/\r?\n/)[2] !== token)
-        return;
-    await rm(lockPath, { force: true }).catch(() => undefined);
+    const removeIfOwned = async () => {
+        let content;
+        try {
+            content = await readFile(lockPath, "utf8");
+        }
+        catch {
+            return true;
+        }
+        if (content.split(/\r?\n/)[2] !== token)
+            return true;
+        await rm(lockPath, { force: true }).catch(() => undefined);
+        return true;
+    };
+    // Serialized with stale breaks so a break in progress cannot land on a
+    // lock this release has already replaced (#342). A removal lock that
+    // cannot be had in time falls back to the token-checked removal alone —
+    // the guarantee before #342, never less.
+    if ((await withRemovalLock(lockPath, removeIfOwned)) === undefined)
+        await removeIfOwned();
 }
 async function describeLockHolder(lockPath) {
     try {

package/dist/extensions/codecarto/agent-state.d.ts

@@ -32,5 +32,11 @@ export declare function finishPhase(phaseId: string, outcome: {
  * Clear a phase from the activity map. The widget (M2) will linger finished
  * phases for a turn or two before calling this; for now (M1) we clear after
  * a fixed timeout so the orchestrator notification stays meaningful.
+ *
+ * With `activity`, clear only while the map still holds that very entry.
+ * The runner's linger timer fires 30 s after a phase ends; a re-run of the
+ * same phase inside that window used to lose its live entry to the earlier
+ * run's timer — the widget dropped it and the re-entry guard let a second
+ * sub-agent start on the phase (#343).
  */
-export declare function clearPhase(phaseId: string): void;
+export declare function clearPhase(phaseId: string, activity?: PhaseActivity): void;

package/dist/extensions/codecarto/agent-state.js

@@ -42,7 +42,15 @@ export function finishPhase(phaseId, outcome) {
  * Clear a phase from the activity map. The widget (M2) will linger finished
  * phases for a turn or two before calling this; for now (M1) we clear after
  * a fixed timeout so the orchestrator notification stays meaningful.
+ *
+ * With `activity`, clear only while the map still holds that very entry.
+ * The runner's linger timer fires 30 s after a phase ends; a re-run of the
+ * same phase inside that window used to lose its live entry to the earlier
+ * run's timer — the widget dropped it and the re-entry guard let a second
+ * sub-agent start on the phase (#343).
  */
-export function clearPhase(phaseId) {
+export function clearPhase(phaseId, activity) {
+    if (activity && phaseActivity.get(phaseId) !== activity)
+        return;
     phaseActivity.delete(phaseId);
 }

package/dist/extensions/codecarto/auto-runner.js

@@ -132,8 +132,9 @@ export async function runSinglePhase(ctx, pi, state, phase, options) {
         return { status: "error", activity, error: message };
     }
     finally {
-        // Linger 30s so /codecarto-status can show that the phase ran.
-        setTimeout(() => clearPhase(phase.id), 30_000);
+        // Linger 30s so /codecarto-status can show that the phase ran. Tied
+        // to this run's entry: a re-run inside the window keeps its own (#343).
+        setTimeout(() => clearPhase(phase.id, activity), 30_000).unref?.();
     }
 }
 /**

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,8 +10,8 @@ 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 { initLibrary } from "../../core/library.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, isValidSlug } from "../../core/library.js";
 import { resolveUserConfigPath } from "../../core/orchestrator-config.js";
 const STATUS_WIDGET_ID = "codecarto-widget";
 // Broad-Side gets its own widget id: a scout run is legal on a repository with
@@ -995,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 }))),
@@ -1181,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 {
@@ -1325,12 +1354,41 @@ export default function codeCartographerExtension(pi) {
     pi.registerCommand("codecarto-library-init", {
         description: "Initialize a CodeCartographer library and configure it: /codecarto-library-init <path> [--namespace <name>]",
         handler: async (args, ctx) => {
-            const parts = args.trim().split(/\s+/);
-            const pathArg = parts[0];
+            const usage = "Usage: /codecarto-library-init <path> [--namespace <name>]";
+            const parts = args.trim() === "" ? [] : args.trim().split(/\s+/);
+            // `--namespace` with nothing after it used to read as "no namespace"
+            // and initialize an unnamespaced library without a word (Broad-Side
+            // verify, 2026-09-13 run): the flag is either complete or refused.
             const namespaceIdx = parts.indexOf("--namespace");
-            const namespace = namespaceIdx >= 0 ? parts[namespaceIdx + 1] : null;
+            let namespace = null;
+            if (namespaceIdx >= 0) {
+                const value = parts[namespaceIdx + 1];
+                if (value === undefined || value.startsWith("--")) {
+                    notifyCtx(ctx, `--namespace needs a name. ${usage}`, "warning");
+                    return;
+                }
+                // The rule publish applies to it later, applied before it is
+                // written into the config: lowercase ASCII, starts with a
+                // letter, at most 64 characters.
+                if (!isValidSlug(value)) {
+                    notifyCtx(ctx, `Invalid namespace "${value}" (lowercase ASCII, starts with a letter, max 64 chars). ${usage}`, "warning");
+                    return;
+                }
+                namespace = value;
+                parts.splice(namespaceIdx, 2);
+            }
+            const stray = parts.find((part) => part.startsWith("--"));
+            if (stray) {
+                notifyCtx(ctx, `Unknown flag ${stray}. ${usage}`, "warning");
+                return;
+            }
+            const [pathArg, ...extra] = parts;
             if (!pathArg) {
-                notifyCtx(ctx, "Usage: /codecarto-library-init <path> [--namespace <name>]", "warning");
+                notifyCtx(ctx, usage, "warning");
+                return;
+            }
+            if (extra.length > 0) {
+                notifyCtx(ctx, `One path, please — got ${parts.length}. ${usage}`, "warning");
                 return;
             }
             // The same expansion the config loader applies, so `~user/x` and a

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";
@@ -808,6 +808,11 @@ export async function handleLibraryInit(args) {
     }
     const libraryPath = args.library_path;
     const namespaced = !!args.namespace;
+    // The rule codecarto_publish applies to the namespace later, applied
+    // before it is written into the config.
+    if (namespaced && !isValidSlug(args.namespace)) {
+        throw new McpError(ErrorCode.InvalidParams, `Invalid namespace "${args.namespace}" (lowercase ASCII, starts with a letter, max 64 chars).`);
+    }
     const result = await initLibrary(libraryPath, {
         name: args.name,
         namespaced,
@@ -1037,8 +1042,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 +1178,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 +1539,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 +1553,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 +1577,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 +1593,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.23.0",
+  "version": "0.24.1",
   "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",