codecartographer-pi 0.19.0 → 0.19.1

package/.codecarto/broadside/SKILL.md

@@ -125,6 +125,13 @@ from OpenRouter's runtime cost tracking: it predicts from file sizes before
 spend, it does not stop a batch mid-flight. Actual spend appears in
 `run-meta.json` after collect.
 
+Budget for the **ceiling, not the estimate**. OpenRouter charges the worst
+case when it accepts a batch — every request's full `max_tokens` — and
+refunds the unused output as each request settles. A six-lens scan of this
+repository held $0.6972 and settled at $0.3806, so the balance a run needs to
+*start* is roughly double what it ends up costing. The submit estimate sits
+between the two: above what the run should settle at, below what it can hold.
+
 ## Resilience notes
 
 - **Truncation is spoken.** A lens output whose JSON does not parse — even

package/.codecarto/broadside/config.yaml

@@ -68,8 +68,8 @@
 # lookup fails (offline, private model) or you want to assert a ceiling.
 #
 # pricing:
-#   input_per_m: 0.1875
-#   output_per_m: 0.9375
+#   input_per_m: 0.375
+#   output_per_m: 1.875
 # ---------------------------------------------------------------------------
 # Run defaults. Each key below mirrors a codecarto_broadside parameter of the
 # same name and sets this repository's default for it; an explicit parameter on

package/.codecarto/workflow/scaffold-version.yaml

@@ -3,4 +3,4 @@
 # workspace's framework-owned files (GUIDE.md, templates/, workflow/ pipelines
 # and VALIDATE.md) predate the running release. Written at release time and
 # copied verbatim by init — never edit by hand.
-scaffold_version: 0.19.0
+scaffold_version: 0.19.1

package/dist/core/broadside.d.ts

@@ -6,8 +6,8 @@ export declare const BROADSIDE_SKILL_NAME = "broadside";
 export declare const BROADSIDE_STATE_FILE = "state.json";
 export declare const BROADSIDE_CONFIG_FILE = "config.yaml";
 export declare const BROADSIDE_STATE_SCHEMA_VERSION = 1;
-export declare const BROADSIDE_INPUT_PRICE_PER_M = 0.1875;
-export declare const BROADSIDE_OUTPUT_PRICE_PER_M = 0.9375;
+export declare const BROADSIDE_INPUT_PRICE_PER_M = 0.375;
+export declare const BROADSIDE_OUTPUT_PRICE_PER_M = 1.875;
 export declare const BROADSIDE_MODELS_URL = "https://openrouter.ai/api/v1/models";
 export declare const BROADSIDE_BENCHMARKS_URL = "https://openrouter.ai/api/v1/benchmarks";
 export declare const BROADSIDE_CATALOG_CACHE_FILE = "model-catalog.json";
@@ -49,7 +49,13 @@ export type CodingBenchmarks = {
 export type BroadsideCatalogResult = {
     model: string;
     source: "built-in" | "config" | "live" | "cache";
-    entry: CatalogEntry | null;
+    /**
+     * Always resolved. `resolveCatalogEntry` either returns an entry — from
+     * config, cache, the live catalog, or the compile-time fallback — or throws
+     * naming the model it could not price. This was declared nullable, which is
+     * the only reason the single consumer needed a non-null assertion to read it.
+     */
+    entry: CatalogEntry;
     benchmarks?: CodingBenchmarks;
 };
 export type JsonSchemaDef = {
@@ -115,6 +121,8 @@ export type BroadsideSynthesisEntry = {
     batchId?: string;
     status: "pending" | "submitted" | "completed" | "failed";
     cost?: number;
+    /** Why the pass was retired, when the batch reported one. */
+    error?: string;
 };
 /** One triage item — a scouting lead turned into a work-order entry. */
 export type TriageItem = {
@@ -220,6 +228,8 @@ export type BroadsideEstimate = {
     /** Set when incremental scouting found a baseline to diff against. */
     baseHead: string | null;
     sourceDirty: boolean;
+    /** Whether a requested incremental run actually narrowed this estimate. */
+    incremental: BroadsideIncrementalOutcome;
     /** The provider's completion ceiling, when the catalog advertises one. */
     outputCap?: number;
 };
@@ -227,6 +237,22 @@ export type BroadsideEstimate = {
 export declare class BroadsideCancelledError extends Error {
     constructor(message?: string);
 }
+/**
+ * Whether incremental scouting actually narrowed the run.
+ *
+ * A request for incremental falls back to a full scan whenever there is nothing
+ * to diff against, and that fallback costs real money — the caller asked for the
+ * cheap mode and gets the expensive one. It must be reported, not inferred from
+ * the request counts.
+ */
+export type BroadsideIncrementalOutcome = {
+    requested: boolean;
+    applied: boolean;
+    /** The commit the run diffed against, when one was found. */
+    baseHead: string | null;
+    /** Why a requested incremental run did not apply. */
+    reason?: "dirty-worktree" | "no-baseline" | "diff-failed";
+};
 export type BroadsideSubmitResult = {
     runId: string;
     outputDir: string;
@@ -242,6 +268,7 @@ export type BroadsideSubmitResult = {
         supportsStructuredOutputs?: boolean;
         expirationDate?: string | null;
     };
+    incremental: BroadsideIncrementalOutcome;
 };
 export type BroadsideCollectResult = {
     runId: string;
@@ -287,7 +314,22 @@ export declare function listLenses(): LensDefinition[];
 export declare function collectRepoInfo(targetDir: string): Promise<RepoInfo>;
 export declare function gatherSlices(targetDir: string, lens: LensDefinition, info: RepoInfo): Promise<FileSlice[]>;
 export declare function buildBatchRequest(lens: LensDefinition, info: RepoInfo, slice: FileSlice, index: number, sliceCount: number, model?: string, maxTokensOverride?: number): BatchRequest;
-export declare function estimateCost(lens: LensDefinition, slices: FileSlice[], pricing: ModelPricing, maxTokensOverride?: number): {
+/**
+ * Pre-flight cost estimate for one lens.
+ *
+ * Every slice is its own batch request, so both halves scale with the slice
+ * count. The output half used to be a single `maxTokens * 0.75` for the whole
+ * lens no matter how many requests it sent — on a repository that sliced into
+ * 13 modules that budgeted one request's output and shipped thirteen, and a
+ * live run came in at roughly 3x its estimate. Since this number is what
+ * `max_cost` binds against, under-counting it lets a run outspend the cap the
+ * user set.
+ *
+ * @param info - Repo info, when the caller has it: lets the estimate include
+ *   the system prompt and JSON schema each request carries. Omitted, the
+ *   estimate covers slice content only, which is what the old signature did.
+ */
+export declare function estimateCost(lens: LensDefinition, slices: FileSlice[], pricing: ModelPricing, maxTokensOverride?: number, info?: RepoInfo): {
     inputTokens: number;
     outputTokens: number;
     cost: number;
@@ -313,7 +355,40 @@ export declare function readBroadsideSkill(cwd: string): Promise<{
 }>;
 export declare function defaultBroadsideState(): BroadsideStateFile;
 export declare function loadBroadsideState(broadsideDir: string): Promise<BroadsideStateFile>;
+/**
+ * Overwrite `state.json` wholesale with `state`.
+ *
+ * Prefer {@link persistBroadsideRun} anywhere a live operation is recording its
+ * own progress — this entry point replaces the file, so any run a concurrent
+ * process recorded in the meantime is erased. It remains the right call for
+ * seeding a fresh workspace and for test fixtures, where "make the file exactly
+ * this" is the intent.
+ */
 export declare function saveBroadsideState(broadsideDir: string, state: BroadsideStateFile): Promise<void>;
+/**
+ * Read-modify-write `state.json` under a lock.
+ *
+ * The lock is held only for the read-modify-write, never for the surrounding
+ * operation: a `collect` can poll for the better part of an hour, and holding
+ * the lock across that would push every concurrent caller past the 5s lock
+ * timeout.
+ */
+export declare function updateBroadsideStateAtomically(broadsideDir: string, mutate: (state: BroadsideStateFile) => void | Promise<void>): Promise<BroadsideStateFile>;
+/**
+ * Record one run's current shape, merged into whatever is on disk *now*.
+ *
+ * Broad-Side operations are long-lived and hold their state in memory while
+ * they poll. Writing that snapshot back wholesale silently erased any run a
+ * concurrent operation had recorded since it was loaded, orphaning that run's
+ * paid results on disk — present as files, invisible to `list`, and unreachable
+ * by `collect`, which finds its run by position in `state.runs`. Observed live:
+ * a submit at 23:35 was erased by a collect that had loaded state before it and
+ * wrote back at 00:08.
+ *
+ * Merging by run id also self-heals: a run erased by an older writer is
+ * restored the next time its own operation checkpoints.
+ */
+export declare function persistBroadsideRun(broadsideDir: string, run: BroadsideRun): Promise<BroadsideStateFile>;
 export declare function loadBroadsideConfig(broadsideDir: string): Promise<BroadsideConfig>;
 export declare function builtInCatalogEntry(model: string): CatalogEntry | null;
 export declare function builtInPricing(model: string): ModelPricing | null;
@@ -336,6 +411,14 @@ export declare function submitBatch(batchRequests: BatchRequest[], apiKey: strin
     error?: unknown;
 }>;
 export declare function fetchBatch(batchId: string, apiKey: string, fetcher?: FetchLike): Promise<Record<string, unknown>>;
+/**
+ * Batch statuses that will never produce a result.
+ *
+ * Deliberately excludes the synthetic `timeout` this module returns when a poll
+ * budget expires: that batch is still running server-side and has already been
+ * charged, so callers must come back for it rather than retire it.
+ */
+export declare const BROADSIDE_DEAD_BATCH_STATUSES: string[];
 export declare function pollBatchUntilTerminal(batchId: string, apiKey: string, opts?: {
     deadlineMs?: number;
     onStatus?: (status: string, counts: Record<string, unknown>) => void;
@@ -398,6 +481,18 @@ export type StoredLensResult = {
  */
 export declare function parseLensJson(content: string): unknown | null;
 export declare function saveLensResults(runDir: string, lensId: BroadsideLensId, batch: Record<string, unknown>): Promise<StoredLensResult[]>;
+/**
+ * Rebuild lens results from what a previous collect already wrote to disk.
+ *
+ * The post-passes are gated on having lens findings in hand, and a collect
+ * only holds the ones *it* polled. When an earlier collect saved every lens
+ * and then died before synthesis and triage ran — the batch window is long
+ * and a poll can easily be interrupted — the next collect finds every lens
+ * already terminal, skips them all, and would otherwise reach the post-pass
+ * gate with nothing to hand it. Reading the saved results back is what makes
+ * "a resumed collect can finish whichever is still pending" true.
+ */
+export declare function loadSavedLensResults(runDir: string, lenses: BroadsideLensId[]): Promise<StoredLensResult[]>;
 export declare function runBroadsideCollect(cwd: string, apiKey: string, opts?: {
     waitMs?: number;
     includeSynthesis?: boolean;

package/dist/core/broadside.js

@@ -31,11 +31,12 @@
 // executable surfaces (Pi and MCP), not the pure template. What the template does
 // carry is the reading guide for its output — `.codecarto/broadside/SKILL.md`,
 // served by codecarto_skill under the name `broadside` (see readBroadsideSkill).
-import { mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
+import { mkdir, readFile, readdir, rename, stat, writeFile } from "node:fs/promises";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
-import { join } from "node:path";
+import { join, relative } from "node:path";
 import { pathExists, sleep } from "./utils.js";
+import { acquireLock } from "./status.js";
 import { loadYamlFile } from "./yaml.js";
 import { packagedWorkspaceDir } from "./workspace.js";
 const execFileAsync = promisify(execFile);
@@ -49,8 +50,14 @@ 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 listed rates for the `:batch` variant, which already carry the
+// batch discount — the sync model is $0.75/$3.75. These were half these values
+// until a live run compared them against the catalog: the batch discount had
+// been applied a second time by hand, so every estimate for the default model
+// came out at half its true cost and `max_cost` bound at twice what the user
+// asked for. They are the offline fallback only; the live catalog wins.
+export const BROADSIDE_INPUT_PRICE_PER_M = 0.375;
+export const BROADSIDE_OUTPUT_PRICE_PER_M = 1.875;
 // 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";
@@ -848,7 +855,10 @@ async function walkFiles(rootDir, dir, depth, remaining) {
             out = out.concat(children);
         }
         else if (entry.isFile()) {
-            const rel = join(dir, entry.name).slice(rootDir.length + 1).split("\\").join("/");
+            // relative() rather than slice(rootDir.length + 1): the hand-rolled
+            // slice cut one character too many whenever rootDir carried a trailing
+            // separator, and mangled every path outright when rootDir was "/".
+            const rel = relative(rootDir, join(dir, entry.name)).split("\\").join("/");
             out.push(rel);
         }
     }
@@ -1142,9 +1152,30 @@ export function buildBatchRequest(lens, info, slice, index, sliceCount, model =
         },
     };
 }
-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);
+/**
+ * Pre-flight cost estimate for one lens.
+ *
+ * Every slice is its own batch request, so both halves scale with the slice
+ * count. The output half used to be a single `maxTokens * 0.75` for the whole
+ * lens no matter how many requests it sent — on a repository that sliced into
+ * 13 modules that budgeted one request's output and shipped thirteen, and a
+ * live run came in at roughly 3x its estimate. Since this number is what
+ * `max_cost` binds against, under-counting it lets a run outspend the cap the
+ * user set.
+ *
+ * @param info - Repo info, when the caller has it: lets the estimate include
+ *   the system prompt and JSON schema each request carries. Omitted, the
+ *   estimate covers slice content only, which is what the old signature did.
+ */
+export function estimateCost(lens, slices, pricing, maxTokensOverride, info) {
+    const sliceChars = slices.reduce((sum, s) => sum + (lens.maxChars === 0 ? 6000 : s.chars), 0);
+    // The system prompt and the response schema ride on every request, so they
+    // are paid once per slice rather than once per lens.
+    const perRequestOverhead = info
+        ? (lens.systemPrompt(info)?.length ?? 0) + JSON.stringify(SCHEMAS[lens.schemaName] ?? {}).length
+        : 0;
+    const inputTokens = Math.ceil((sliceChars + perRequestOverhead * slices.length) / 4);
+    const outputTokens = slices.length * 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 };
@@ -1195,9 +1226,76 @@ export async function loadBroadsideState(broadsideDir) {
         return defaultBroadsideState();
     }
 }
+/**
+ * Overwrite `state.json` wholesale with `state`.
+ *
+ * Prefer {@link persistBroadsideRun} anywhere a live operation is recording its
+ * own progress — this entry point replaces the file, so any run a concurrent
+ * process recorded in the meantime is erased. It remains the right call for
+ * seeding a fresh workspace and for test fixtures, where "make the file exactly
+ * this" is the intent.
+ */
 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");
+    const statePath = join(broadsideDir, BROADSIDE_STATE_FILE);
+    const lock = await acquireLock(`${statePath}.lock`);
+    try {
+        await writeBroadsideStateFile(statePath, state);
+    }
+    finally {
+        await lock.release();
+    }
+}
+/** Serialize through a temp file so a crash mid-write cannot truncate state.json. */
+async function writeBroadsideStateFile(statePath, state) {
+    const tempPath = `${statePath}.${process.pid}.${Date.now()}.tmp`;
+    await writeFile(tempPath, `${JSON.stringify(state, null, "\t")}\n`, "utf8");
+    await rename(tempPath, statePath);
+}
+/**
+ * Read-modify-write `state.json` under a lock.
+ *
+ * The lock is held only for the read-modify-write, never for the surrounding
+ * operation: a `collect` can poll for the better part of an hour, and holding
+ * the lock across that would push every concurrent caller past the 5s lock
+ * timeout.
+ */
+export async function updateBroadsideStateAtomically(broadsideDir, mutate) {
+    await mkdir(broadsideDir, { recursive: true });
+    const statePath = join(broadsideDir, BROADSIDE_STATE_FILE);
+    const lock = await acquireLock(`${statePath}.lock`);
+    try {
+        const state = await loadBroadsideState(broadsideDir);
+        await mutate(state);
+        await writeBroadsideStateFile(statePath, state);
+        return state;
+    }
+    finally {
+        await lock.release();
+    }
+}
+/**
+ * Record one run's current shape, merged into whatever is on disk *now*.
+ *
+ * Broad-Side operations are long-lived and hold their state in memory while
+ * they poll. Writing that snapshot back wholesale silently erased any run a
+ * concurrent operation had recorded since it was loaded, orphaning that run's
+ * paid results on disk — present as files, invisible to `list`, and unreachable
+ * by `collect`, which finds its run by position in `state.runs`. Observed live:
+ * a submit at 23:35 was erased by a collect that had loaded state before it and
+ * wrote back at 00:08.
+ *
+ * Merging by run id also self-heals: a run erased by an older writer is
+ * restored the next time its own operation checkpoints.
+ */
+export async function persistBroadsideRun(broadsideDir, run) {
+    return updateBroadsideStateAtomically(broadsideDir, (state) => {
+        const index = state.runs.findIndex((candidate) => candidate.id === run.id);
+        if (index === -1)
+            state.runs.push(run);
+        else
+            state.runs[index] = run;
+    });
 }
 export async function loadBroadsideConfig(broadsideDir) {
     const configPath = join(broadsideDir, BROADSIDE_CONFIG_FILE);
@@ -1332,10 +1430,11 @@ export async function resolveCatalogEntry(broadsideDir, config, model, apiKey, f
             },
         };
     }
-    const builtIn = builtInCatalogEntry(model);
-    if (builtIn)
-        return { model, source: "built-in", entry: builtIn };
-    // Unknown model: on-disk cache first, then the live catalog.
+    // On-disk cache first, then the live catalog — for the default model too.
+    // Hardcoded rates used to short-circuit here, which meant a stale constant
+    // could never self-correct even though the catalog was already being
+    // fetched for every other model. The authoritative source wins; the
+    // constants below are what we fall back to when the network is unavailable.
     const cache = await readCatalogCache(broadsideDir);
     const cached = cache?.models[model];
     if (cached && Date.now() - new Date(cache.fetched_at).getTime() < BROADSIDE_CATALOG_CACHE_TTL_MS) {
@@ -1366,6 +1465,11 @@ export async function resolveCatalogEntry(broadsideDir, config, model, apiKey, f
         await writeCatalogCache(broadsideDir, updated);
         return { model, source: "live", entry: live };
     }
+    // Offline fallback: the default model's rates and capabilities are known at
+    // compile time, so a network failure does not have to stop a run.
+    const builtIn = builtInCatalogEntry(model);
+    if (builtIn)
+        return { model, source: "built-in", entry: builtIn };
     throw new Error(`Could not resolve per-token pricing for batch model "${model}". ` +
         "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.");
@@ -1469,6 +1573,14 @@ export async function fetchBatch(batchId, apiKey, fetcher = fetch) {
     data.http_status = resp.status;
     return data;
 }
+/**
+ * Batch statuses that will never produce a result.
+ *
+ * Deliberately excludes the synthetic `timeout` this module returns when a poll
+ * budget expires: that batch is still running server-side and has already been
+ * charged, so callers must come back for it rather than retire it.
+ */
+export const BROADSIDE_DEAD_BATCH_STATUSES = ["failed", "expired", "cancelled", "auth-failed"];
 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;
@@ -1491,7 +1603,7 @@ export async function pollBatchUntilTerminal(batchId, apiKey, opts = {}) {
         const status = String(batch.status ?? "unknown");
         const counts = (batch.request_counts ?? {});
         opts.onStatus?.(status, counts);
-        if (["completed", "failed", "expired", "cancelled", "auth-failed"].includes(status))
+        if (status === "completed" || BROADSIDE_DEAD_BATCH_STATUSES.includes(status))
             return batch;
         if (Date.now() >= deadline)
             return { id: batchId, status: "timeout" };
@@ -1563,14 +1675,30 @@ export async function runBroadsideSubmit(cwd, apiKey, opts = {}) {
     const sourceDirty = await gitDirty(cwd);
     let baseHead = null;
     let changed = null;
+    const incrementalOutcome = {
+        requested: opts.incremental === true,
+        applied: false,
+        baseHead: 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) {
+        if (sourceDirty) {
+            incrementalOutcome.reason = "dirty-worktree";
+        }
+        else if (!previous?.sourceHead) {
+            incrementalOutcome.reason = "no-baseline";
+        }
+        else {
             baseHead = previous.sourceHead;
             changed = await changedFilesSince(cwd, baseHead);
+            incrementalOutcome.baseHead = baseHead;
+            if (changed)
+                incrementalOutcome.applied = true;
+            else
+                incrementalOutcome.reason = "diff-failed";
         }
     }
     // Slice offline first so the estimate covers every request we would send.
@@ -1591,7 +1719,7 @@ export async function runBroadsideSubmit(cwd, apiKey, opts = {}) {
         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);
+        const estimate = estimateCost(lens, slices, lensPricing, maxTokens, info);
         estimatedInputTokens += estimate.inputTokens;
         estimatedOutputTokens += estimate.outputTokens;
         estimatedTotalCost += estimate.cost;
@@ -1626,6 +1754,7 @@ export async function runBroadsideSubmit(cwd, apiKey, opts = {}) {
             exceedsLimit,
             baseHead,
             sourceDirty,
+            incremental: incrementalOutcome,
             ...(outputCap !== undefined && { outputCap }),
         });
         if (!approved)
@@ -1659,7 +1788,7 @@ export async function runBroadsideSubmit(cwd, apiKey, opts = {}) {
         baseHead,
     };
     state.runs.push(run);
-    await saveBroadsideState(broadsideDir, state);
+    await persistBroadsideRun(broadsideDir, run);
     const requestsByCustomId = {};
     const submissions = [];
     // Submit from the estimate rather than recomputing: the user approved that
@@ -1707,7 +1836,7 @@ export async function runBroadsideSubmit(cwd, apiKey, opts = {}) {
         })());
     }
     await Promise.allSettled(submissions);
-    await saveBroadsideState(broadsideDir, state);
+    await persistBroadsideRun(broadsideDir, run);
     // 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
@@ -1734,6 +1863,7 @@ export async function runBroadsideSubmit(cwd, apiKey, opts = {}) {
                 : resolved.get(model).supportsStructuredOutputs,
             expirationDate: defaultEntry.expirationDate ?? null,
         },
+        incremental: incrementalOutcome,
     };
 }
 function extractContent(result) {
@@ -1799,6 +1929,46 @@ export async function saveLensResults(runDir, lensId, batch) {
     }
     return out;
 }
+/**
+ * Rebuild lens results from what a previous collect already wrote to disk.
+ *
+ * The post-passes are gated on having lens findings in hand, and a collect
+ * only holds the ones *it* polled. When an earlier collect saved every lens
+ * and then died before synthesis and triage ran — the batch window is long
+ * and a poll can easily be interrupted — the next collect finds every lens
+ * already terminal, skips them all, and would otherwise reach the post-pass
+ * gate with nothing to hand it. Reading the saved results back is what makes
+ * "a resumed collect can finish whichever is still pending" true.
+ */
+export async function loadSavedLensResults(runDir, lenses) {
+    if (!(await pathExists(runDir)))
+        return [];
+    const reserved = new Set(["requests.json", "run-meta.json", "synthesis.json", "triage.json"]);
+    const out = [];
+    // Longest lens id first: no id is a prefix of another today, but ordering
+    // keeps that from becoming a silent misattribution if one ever is.
+    const ordered = [...lenses].sort((a, b) => b.length - a.length);
+    for (const name of (await readdir(runDir)).sort()) {
+        if (!name.endsWith(".json") || name.endsWith(".error.json") || reserved.has(name) || name.startsWith("raw-"))
+            continue;
+        const customId = name.slice(0, -".json".length);
+        const lensId = ordered.find((id) => customId === id || customId.startsWith(`${id}-`));
+        if (!lensId)
+            continue;
+        const content = await readFile(join(runDir, name), "utf8").catch(() => null);
+        if (content === null)
+            continue;
+        out.push({
+            lensId,
+            customId,
+            moduleName: customId.replace(/^[a-z]+-/, ""),
+            content,
+            raw: {},
+            truncated: parseLensJson(content) === null,
+        });
+    }
+    return out;
+}
 async function loadStoredRequests(runDir) {
     const path = join(runDir, "requests.json");
     if (!(await pathExists(path)))
@@ -1956,11 +2126,19 @@ export async function runBroadsideCollect(cwd, apiKey, opts = {}) {
             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;
+        else {
+            // Every non-completed outcome still has to reach the report.
+            // `lensOutcomes` is what the caller renders, and this branch used to
+            // require `batch.error` — but the commonest failure here is the
+            // synthetic `{ status: "timeout" }` the poll returns when its budget
+            // expires with the batch still in flight, and that carries no error.
+            // A lens that never came back was therefore omitted entirely,
+            // indistinguishable in the output from one that was never requested.
+            if (batch.error)
+                entry.error = batch.error;
             lensOutcomes[lensId] = { status, cost: entry.cost, resultCount: entry.resultCount };
         }
-        await saveBroadsideState(broadsideDir, state);
+        await persistBroadsideRun(broadsideDir, run);
     }
     // #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
@@ -1993,7 +2171,11 @@ export async function runBroadsideCollect(cwd, apiKey, opts = {}) {
                 if (error)
                     continue;
                 const batch = await pollBatchUntilTerminal(batchId, apiKey, {
-                    deadlineMs: BROADSIDE_DEFAULT_POLL_BUDGET_MS,
+                    // Share the caller's deadline. Each of these polls used to
+                    // start a fresh 25-minute budget, so `wait_seconds` bounded
+                    // only the lens poll and a collect could run for the caller's
+                    // budget plus fifty minutes.
+                    deadlineMs: Math.max(0, deadline - Date.now()),
                     onStatus: (status, counts) => opts.onStatus?.(`${stored.lensId}:retry`, status, counts),
                     fetcher: opts.fetcher,
                 });
@@ -2023,7 +2205,7 @@ export async function runBroadsideCollect(cwd, apiKey, opts = {}) {
                 outcome.truncated = allLensResults.filter((s) => s.lensId === lensId && s.truncated).length;
             }
         }
-        await saveBroadsideState(broadsideDir, state);
+        await persistBroadsideRun(broadsideDir, run);
     }
     // Synthesis + triage: cross-lens post-passes, only after every lens batch
     // is terminal. Triage turns the leads into a prioritized work order.
@@ -2032,12 +2214,25 @@ export async function runBroadsideCollect(cwd, apiKey, opts = {}) {
     let topTriageItems = [];
     const wantSynthesis = opts.includeSynthesis !== false;
     const wantTriage = opts.includeTriage !== false;
+    // A resumed collect polls nothing — every lens is already terminal — so the
+    // findings the post-passes need have to come back off disk, or a run whose
+    // first collect was interrupted could never produce its executive report
+    // and work order, however many times it was re-run.
+    const postPassUnfinished = (entry) => entry.status === "pending" || entry.status === "submitted";
+    if ((wantSynthesis || wantTriage) && allLensResults.length === 0
+        && (postPassUnfinished(run.synthesis) || postPassUnfinished(run.triage))) {
+        const restored = await loadSavedLensResults(runDir, run.lenses);
+        if (restored.length > 0) {
+            allLensResults.push(...restored);
+            truncatedCount = restored.filter((s) => s.truncated).length;
+        }
+    }
     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")) {
+        if (allTerminal && (postPassUnfinished(run.synthesis) || postPassUnfinished(run.triage))) {
             const findingsText = allLensResults
                 .map((r) => `## ${r.lensId} — ${r.customId}\n\n${r.content}\n`)
                 .join("\n");
@@ -2066,6 +2261,24 @@ export async function runBroadsideCollect(cwd, apiKey, opts = {}) {
                     : []),
             ];
             const submitted = new Map();
+            // A pass can be left at "submitted" when an earlier collect returned
+            // before its batch reached a terminal status — the batch still runs
+            // and is still charged, so the result exists and is simply unclaimed.
+            // Nothing above would ever look at it again: the pass list is built
+            // from "pending" entries only. Poll those regardless of the want
+            // flags, because the spend already happened and discarding a
+            // finished result is worse than saving one the caller opted out of.
+            for (const kind of ["synthesis", "triage"]) {
+                const entry = kind === "synthesis" ? run.synthesis : run.triage;
+                if (entry.status !== "submitted" || !entry.batchId)
+                    continue;
+                if (submitted.has(entry.batchId))
+                    continue;
+                submitted.set(entry.batchId, {
+                    batchId: entry.batchId,
+                    pass: { kind, request: undefined, entry },
+                });
+            }
             await Promise.allSettled(passes.map(async (pass) => {
                 pass.entry.status = "submitted";
                 try {
@@ -2081,10 +2294,13 @@ export async function runBroadsideCollect(cwd, apiKey, opts = {}) {
                     pass.entry.status = "failed";
                 }
             }));
-            await saveBroadsideState(broadsideDir, state);
+            await persistBroadsideRun(broadsideDir, run);
             for (const { batchId, pass } of submitted.values()) {
                 const batch = await pollBatchUntilTerminal(batchId, apiKey, {
-                    deadlineMs: BROADSIDE_DEFAULT_POLL_BUDGET_MS,
+                    // Shares the caller's deadline, as the retry poll above does.
+                    // A pass whose poll runs out stays `submitted`, so the batch
+                    // is already paid for and a later collect claims its result.
+                    deadlineMs: Math.max(0, deadline - Date.now()),
                     onStatus: (status, counts) => opts.onStatus?.(pass.kind, status, counts),
                     fetcher: opts.fetcher,
                 });
@@ -2107,10 +2323,20 @@ export async function runBroadsideCollect(cwd, apiKey, opts = {}) {
                         }
                     }
                 }
-                else if (batch.error) {
+                else if (BROADSIDE_DEAD_BATCH_STATUSES.includes(String(batch.status))) {
+                    // The batch will never produce a result, so retire the pass.
+                    // This used to require `batch.error`, leaving an expired or
+                    // cancelled batch parked at "submitted" forever — and since a
+                    // resumed collect re-polls anything still "submitted", it
+                    // would re-poll a dead batch on every future run.
                     pass.entry.status = "failed";
+                    if (batch.error)
+                        pass.entry.error = batch.error instanceof Error ? batch.error.message : String(batch.error);
                 }
-                await saveBroadsideState(broadsideDir, state);
+                // A "timeout" is deliberately left at "submitted": the batch is
+                // still running server-side and has already been paid for, so a
+                // later collect should claim its result rather than discard it.
+                await persistBroadsideRun(broadsideDir, run);
             }
         }
     }
@@ -2120,7 +2346,7 @@ export async function runBroadsideCollect(cwd, apiKey, opts = {}) {
     });
     run.status = terminal ? (resultCount > 0 ? "completed" : "failed") : "partial";
     run.totalCost = totalCost;
-    await saveBroadsideState(broadsideDir, state);
+    await persistBroadsideRun(broadsideDir, run);
     await writeFile(join(runDir, "run-meta.json"), `${JSON.stringify({
         experimental: true,
         method: "Broad-Side (OpenRouter Batch API)",
@@ -2223,9 +2449,31 @@ function parseSynthesisTopFindings(content) {
     }
 }
 // ---------- formatting helpers for tool output ----------
+function describeIncrementalFallback(reason) {
+    switch (reason) {
+        case "dirty-worktree":
+            return "the working tree has uncommitted changes, so there is no committed state to diff against";
+        case "no-baseline":
+            return "no earlier run recorded a commit to diff against";
+        case "diff-failed":
+            return "the diff against the previous run's commit could not be read";
+        default:
+            return "no baseline was available";
+    }
+}
 export function estimateSubmitText(result, lenses) {
+    // Count the lenses that actually got a batch, not every lens considered. A
+    // lens with nothing to scan is reported as `skipped (0 request(s))` two
+    // lines below, so counting it here made the header contradict its own body:
+    // a Rust CLI with no server surface reported "submitted 6 batch(es)" over a
+    // list showing four batches and two skips.
+    const entries = Object.values(result.batches ?? {});
+    const submittedCount = entries.filter((entry) => entry.batchId).length;
+    const withoutBatch = entries.length - submittedCount;
     const lines = [
-        `Broad-Side submitted ${result.batches ? Object.keys(result.batches).length : 0} batch(es).`,
+        withoutBatch > 0
+            ? `Broad-Side submitted ${submittedCount} batch(es); ${withoutBatch} lens(es) produced none (see below).`
+            : `Broad-Side submitted ${submittedCount} batch(es).`,
     ];
     for (const lens of lenses) {
         const entry = result.batches[lens.id];
@@ -2235,6 +2483,12 @@ export function estimateSubmitText(result, lenses) {
         const override = entry.model ? ` on ${entry.model}` : "";
         lines.push(`  ${lens.name}: ${status} (${entry.requests} request(s), ~$${entry.estimatedCost.toFixed(4)})${override}`);
     }
+    const incremental = result.incremental;
+    if (incremental?.requested) {
+        lines.push(incremental.applied
+            ? `Incremental: scanning only what changed since ${(incremental.baseHead ?? "").slice(0, 8)}.`
+            : `Incremental: requested but NOT applied — ${describeIncrementalFallback(incremental.reason)}. Every module was scanned, at full cost.`);
+    }
     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`);

package/dist/core/dashboard.d.ts

@@ -39,4 +39,17 @@ export interface DashboardInputs {
     narration?: DashboardNarration;
 }
 export declare function renderDashboard(inputs: DashboardInputs): string;
+/**
+ * A dashboard link target, or undefined when the path is not a safe relative
+ * reference. Absolute paths, scheme-bearing URLs and `.`/`..` segments are
+ * refused outright.
+ *
+ * Percent-encoding each segment is load-bearing, not cosmetic: a Windows-style
+ * `dir\..\secret` survives the segment scan, because that scan splits on `/`
+ * — but `encodeURIComponent` turns the separators into `%5C`, which no URL
+ * parser treats as a path separator, so the traversal cannot resolve. Removing
+ * the encoding, or "simplifying" it to a raw join, reopens it. Exported so
+ * that property has a test.
+ */
+export declare function safeRelativeHref(path: string): string | undefined;
 export declare function escapeHtml(input: string): string;

package/dist/core/dashboard.js

@@ -660,7 +660,19 @@ function renderSafeLink(path, label, className) {
     const classAttr = className ? ` class="${escapeAttr(className)}"` : "";
     return `<a${classAttr} href="${escapeAttr(href)}">${escapeHtml(label)}</a>`;
 }
-function safeRelativeHref(path) {
+/**
+ * A dashboard link target, or undefined when the path is not a safe relative
+ * reference. Absolute paths, scheme-bearing URLs and `.`/`..` segments are
+ * refused outright.
+ *
+ * Percent-encoding each segment is load-bearing, not cosmetic: a Windows-style
+ * `dir\..\secret` survives the segment scan, because that scan splits on `/`
+ * — but `encodeURIComponent` turns the separators into `%5C`, which no URL
+ * parser treats as a path separator, so the traversal cannot resolve. Removing
+ * the encoding, or "simplifying" it to a raw join, reopens it. Exported so
+ * that property has a test.
+ */
+export function safeRelativeHref(path) {
     if (!path || path.startsWith("/") || path.startsWith("\\") || /^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(path))
         return undefined;
     const parts = path.split("/");

package/dist/core/yaml.js

@@ -126,6 +126,19 @@ export function parseSimpleYaml(raw) {
     };
     const parseMapping = (indent) => {
         const result = {};
+        // Duplicate detection tracks keys explicitly rather than testing
+        // `key in result`. A bare object inherits from Object.prototype, so
+        // `"constructor" in result` is already true before anything is parsed —
+        // a document whose key is `constructor`, `toString`, `valueOf` or any
+        // other prototype member was rejected as a duplicate on first sight.
+        const seen = new Set();
+        // Assignment goes through defineProperty for the same reason: plain
+        // `result[key] = value` with the key `__proto__` invokes the prototype
+        // setter instead of creating an entry, so a hand-edited YAML file could
+        // change the shape of every object in the process rather than parse.
+        const assign = (key, value) => {
+            Object.defineProperty(result, key, { value, writable: true, enumerable: true, configurable: true });
+        };
         while (index < lines.length) {
             skipBlank();
             if (index >= lines.length)
@@ -147,9 +160,10 @@ export function parseSimpleYaml(raw) {
             const key = trimmed.slice(0, separator).trim();
             const rawValue = trimmed.slice(separator + 1).trim();
             index++;
-            if (key in result) {
+            if (seen.has(key)) {
                 throw new Error(`Duplicate YAML key: ${key} near line: ${line.trim()}`);
             }
+            seen.add(key);
             if (rawValue === "|" || rawValue === "|-") {
                 const blockLines = [];
                 let contentIndent = null;
@@ -168,19 +182,19 @@ export function parseSimpleYaml(raw) {
                     index++;
                 }
                 const content = blockLines.join("\n").replace(/\n+$/, "");
-                result[key] = rawValue === "|" ? `${content}\n` : content;
+                assign(key, rawValue === "|" ? `${content}\n` : content);
                 continue;
             }
             if (rawValue !== "") {
-                result[key] = parseYamlScalar(rawValue);
+                assign(key, parseYamlScalar(rawValue));
                 continue;
             }
             skipBlank();
             if (index < lines.length && countIndent(lines[index] ?? "") > indent) {
-                result[key] = parseBlock(countIndent(lines[index] ?? ""));
+                assign(key, parseBlock(countIndent(lines[index] ?? "")));
             }
             else {
-                result[key] = null;
+                assign(key, null);
             }
         }
         return result;
@@ -198,7 +212,13 @@ export function parseSimpleYaml(raw) {
             const trimmed = line.slice(lineIndent);
             if (lineIndent !== indent || (!trimmed.startsWith("- ") && trimmed !== "-"))
                 break;
-            const rawItem = trimmed === "-" ? "" : trimmed.slice(2).trim();
+            const afterDash = trimmed === "-" ? "" : trimmed.slice(2);
+            const rawItem = afterDash.trim();
+            // A sequence item's mapping continues at the column where its own
+            // content starts, which is not always two past the dash: `-   id: x`
+            // aligns its siblings under the `i`, four columns in. Hardcoding two
+            // rejected that valid layout as bad indentation.
+            const itemIndent = indent + 2 + (afterDash.length - afterDash.trimStart().length);
             index++;
             if (rawItem === "") {
                 skipBlank();
@@ -221,7 +241,7 @@ export function parseSimpleYaml(raw) {
                     item[key] = parseBlock(countIndent(lines[index] ?? ""));
                 }
                 if (index < lines.length && countIndent(lines[index] ?? "") > indent) {
-                    const nested = parseMapping(indent + 2);
+                    const nested = parseMapping(itemIndent);
                     for (const [nestedKey, nestedValue] of Object.entries(nested))
                         item[nestedKey] = nestedValue;
                 }

package/dist/extensions/codecarto/auto-runner.d.ts

@@ -44,7 +44,7 @@ export interface AutoCompleteResult {
     /** Non-gating closure-integrity notes from completion (#122). */
     warnings: string[];
 }
-export declare function autoCompletePhase(ctx: ExtensionContext, validation: ValidationResult): Promise<AutoCompleteResult>;
+export declare function autoCompletePhase(cwd: string, validation: ValidationResult): Promise<AutoCompleteResult>;
 export type AutoOutcome = "complete" | "stopped" | "aborted";
 export interface AutoRunOptions {
     strict: boolean;

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

@@ -151,9 +151,13 @@ export function isPhaseRunning(phaseId) {
     const existing = getPhaseActivity(phaseId);
     return existing?.status === "running";
 }
-export async function autoCompletePhase(ctx, validation) {
-    const result = await completeValidatedPhase(ctx.cwd, validation, "/codecarto-complete");
-    void writeDashboard(ctx.cwd, PACKAGE_VERSION);
+export async function autoCompletePhase(
+// A directory, not a ctx: this only ever needed `ctx.cwd`, and its callers
+// run after a sub-agent has invalidated the ctx they captured, where every
+// property access throws.
+cwd, validation) {
+    const result = await completeValidatedPhase(cwd, validation, "/codecarto-complete");
+    void writeDashboard(cwd, PACKAGE_VERSION);
     return result;
 }
 export function decideAfterPhase(phaseStatus, phaseError, validation, strict) {
@@ -185,6 +189,9 @@ export function decideAfterPhase(phaseStatus, phaseError, validation, strict) {
 }
 export async function runAuto(ctx, pi, initialState, options) {
     const startedAt = Date.now();
+    // Captured once: the loop below spawns a sub-agent per phase, and each one
+    // invalidates this ctx, after which reading `ctx.cwd` throws.
+    const autoCwd = ctx.cwd;
     const phasesRun = [];
     const totalTokens = { input: 0, output: 0, cacheWrite: 0 };
     const totalPhases = initialState.pipeline.phase_order.length;
@@ -262,7 +269,7 @@ export async function runAuto(ctx, pi, initialState, options) {
         // decision.action === "continue" → auto-complete and loop.
         // validation is guaranteed non-null on the continue branch.
         try {
-            const { updatedState } = await autoCompletePhase(ctx, validation);
+            const { updatedState } = await autoCompletePhase(autoCwd, validation);
             state = updatedState;
             phasesRun.push(phase.id);
             options.onPhaseAdvanced?.(state);

package/dist/extensions/codecarto/index.js

@@ -83,8 +83,42 @@ function buildStatusLines(state, extraLines = []) {
     }
     return lines;
 }
+/**
+ * Whether `ctx` still belongs to the live session.
+ *
+ * Pi invalidates an extension ctx when the session is replaced, and from then
+ * on *every* property access on it throws — `ctx.cwd` and `ctx.hasUI` included.
+ * A phase runs as a sub-agent, so by the time post-phase work fires, the ctx
+ * captured when the command started may already be dead. That is an ordinary
+ * outcome rather than an error: the UI it would have refreshed is gone with the
+ * session. Callers skip their UI work instead of throwing into a `void` call
+ * that nothing is waiting on.
+ */
+function isCtxLive(ctx) {
+    try {
+        return typeof ctx.cwd === "string";
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Notify through `ctx`, dropping the message if the session it belonged to is
+ * gone.
+ *
+ * `ctx.hasUI` throws on a stale ctx rather than returning false, so the usual
+ * `if (ctx.hasUI) ctx.ui.notify(...)` guard was itself a throw site. Inside a
+ * promise chain that was worse than a lost message: the `.catch` handler threw
+ * while reporting the original failure, and that second rejection had nothing
+ * left to catch it.
+ */
+function notifyCtx(ctx, message, level) {
+    if (!isCtxLive(ctx) || !ctx.hasUI)
+        return;
+    ctx.ui.notify(message, level);
+}
 function setUiState(ctx, state, extraLines = []) {
-    if (!ctx.hasUI)
+    if (!isCtxLive(ctx) || !ctx.hasUI)
         return;
     if (!state) {
         ctx.ui.setStatus(STATUS_LINE_ID, undefined);
@@ -260,6 +294,11 @@ export default function codeCartographerExtension(pi) {
     // remembered here for the completers that list files under .codecarto/.
     let sessionCwd;
     const readWorkspaceState = async (ctx, notifyOnError = true) => {
+        // `ctx.cwd` was read before the try, so a stale ctx made this reject
+        // rather than return null as its signature promises — and the callers
+        // that fire it without awaiting turned that into an unhandled rejection.
+        if (!isCtxLive(ctx))
+            return null;
         sessionCwd = ctx.cwd;
         try {
             return await getWorkspaceState(ctx.cwd);
@@ -268,12 +307,16 @@ export default function codeCartographerExtension(pi) {
             const message = error instanceof Error ? error.message : String(error);
             lastFeedbackLines = [message];
             setUiState(ctx, null);
-            if (notifyOnError && ctx.hasUI)
+            // The ctx can die between the read above and here, so the error
+            // path must not assume it is still usable either.
+            if (notifyOnError && isCtxLive(ctx) && ctx.hasUI)
                 ctx.ui.notify(message, "error");
             return null;
         }
     };
     const refreshWorkspaceUi = async (ctx, extraLines) => {
+        if (!isCtxLive(ctx))
+            return null;
         if (!codecartoModeActive) {
             setUiState(ctx, null);
             return null;
@@ -290,15 +333,19 @@ export default function codeCartographerExtension(pi) {
     const ensureWorkspaceState = async (ctx) => {
         if (!codecartoModeActive) {
             setUiState(ctx, null);
-            ctx.ui.notify("CodeCartographer is not active in this session. Run /codecarto-init first.", "warning");
+            notifyCtx(ctx, "CodeCartographer is not active in this session. Run /codecarto-init first.", "warning");
             return null;
         }
         const state = await readWorkspaceState(ctx);
         if (state)
             return state;
+        // Reached when the ctx is stale as well as when there is no workspace,
+        // so neither `ctx.cwd` nor the notify below may assume a live ctx.
+        if (!isCtxLive(ctx))
+            return null;
         const hasWorkspace = await pathExists(join(ctx.cwd, ".codecarto", "workflow", "status.yaml"));
         if (!hasWorkspace)
-            ctx.ui.notify("No .codecarto/ workspace found. Run /codecarto-init first.", "warning");
+            notifyCtx(ctx, "No .codecarto/ workspace found. Run /codecarto-init first.", "warning");
         return null;
     };
     pi.on("session_start", async (_event, ctx) => {
@@ -607,34 +654,36 @@ export default function codeCartographerExtension(pi) {
             // phase so status.yaml advances without requiring the user to manually
             // run /codecarto-validate then /codecarto-complete. This mirrors what
             // the auto loop (runAuto) does after each phase.
+            // The sub-agent replaces the session, which invalidates this ctx —
+            // every later property access on it throws. Capture the directory
+            // now so the post-phase work below does not depend on the ctx
+            // surviving, and route UI updates through notifyCtx, which drops
+            // them if it has not.
+            const phaseCwd = ctx.cwd;
             void runSinglePhase(ctx, pi, state, phase, { llmSteerEnabled, signal: ctx.signal, preflight })
                 .then(async (result) => {
                 if (result.status !== "completed")
                     return;
                 // Refresh state from disk — the sub-agent may have written
                 // findings that the validator needs to read.
-                const stateForValidation = (await getWorkspaceState(ctx.cwd)) ?? state;
+                const stateForValidation = (await getWorkspaceState(phaseCwd)) ?? state;
                 const validation = await validatePhaseOutput(stateForValidation, phase.id).catch((error) => (error instanceof Error ? error : new Error(String(error))));
                 if (validation instanceof Error) {
-                    if (ctx.hasUI)
-                        ctx.ui.notify(`Auto-validation error for ${phase.id}: ${validation.message}`, "warning");
+                    notifyCtx(ctx, `Auto-validation error for ${phase.id}: ${validation.message}`, "warning");
                     lastFeedbackLines = [`Validation error: ${validation.message}`, "Run `/codecarto-validate` then `/codecarto-complete` manually."];
                     return;
                 }
                 if (validation.overall === "FAIL" || validation.overall === "MISSING") {
-                    if (ctx.hasUI)
-                        ctx.ui.notify(`Phase ${phase.id} validation: ${validation.overall}. Fix the output, then re-run /codecarto-next.`, "warning");
+                    notifyCtx(ctx, `Phase ${phase.id} validation: ${validation.overall}. Fix the output, then re-run /codecarto-next.`, "warning");
                     lastFeedbackLines = buildValidationSummary(validation);
                     return;
                 }
                 // PASS or PASS WITH GAPS — auto-complete the phase.
                 try {
-                    const { updatedState, closeoutNotice } = await autoCompletePhase(ctx, validation);
-                    if (ctx.hasUI) {
-                        ctx.ui.notify(`Phase ${phase.id} auto-completed (validation: ${validation.overall}).`, validation.overall === "PASS WITH GAPS" ? "warning" : "info");
-                        if (closeoutNotice)
-                            ctx.ui.notify(closeoutNotice, "info");
-                    }
+                    const { updatedState, closeoutNotice } = await autoCompletePhase(phaseCwd, validation);
+                    notifyCtx(ctx, `Phase ${phase.id} auto-completed (validation: ${validation.overall}).`, validation.overall === "PASS WITH GAPS" ? "warning" : "info");
+                    if (closeoutNotice)
+                        notifyCtx(ctx, closeoutNotice, "info");
                     lastFeedbackLines = [
                         `Completed phase: ${validation.phaseId}`,
                         `Validation: ${validation.overall}`,
@@ -645,22 +694,20 @@ export default function codeCartographerExtension(pi) {
                 }
                 catch (error) {
                     const message = error instanceof Error ? error.message : String(error);
-                    if (ctx.hasUI)
-                        ctx.ui.notify(`Auto-completion failed for ${phase.id}: ${message}. Run /codecarto-complete manually.`, "warning");
+                    notifyCtx(ctx, `Auto-completion failed for ${phase.id}: ${message}. Run /codecarto-complete manually.`, "warning");
                     lastFeedbackLines = [`Auto-completion failed: ${message}`, "Run `/codecarto-complete` manually."];
                 }
             })
                 .catch((error) => {
                 const message = error instanceof Error ? error.message : String(error);
-                if (ctx.hasUI)
-                    ctx.ui.notify(`Post-phase processing error for ${phase.id}: ${message}`, "warning");
+                notifyCtx(ctx, `Post-phase processing error for ${phase.id}: ${message}`, "warning");
                 lastFeedbackLines = [`Post-phase error: ${message}`];
             })
                 .finally(() => {
                 // Refresh the status widget after the phase resolves so the
                 // "Open questions / Carry-forward / Next" lines reflect any
                 // owner_notes the sub-agent wrote to status.yaml.
-                void refreshWorkspaceUi(ctx);
+                void refreshWorkspaceUi(ctx).catch(() => undefined);
             });
         },
     });
@@ -738,7 +785,7 @@ export default function codeCartographerExtension(pi) {
                 ctx.ui.notify(`Cannot complete ${validation.phaseId}: ${validation.overall}`, "error");
                 return;
             }
-            const { updatedState, closeoutNotice, warnings } = await autoCompletePhase(ctx, validation);
+            const { updatedState, closeoutNotice, warnings } = await autoCompletePhase(ctx.cwd, validation);
             lastFeedbackLines = [
                 `Completed phase: ${validation.phaseId}`,
                 `Validation: ${validation.overall}`,
@@ -884,7 +931,7 @@ export default function codeCartographerExtension(pi) {
             }
             lastFeedbackLines = [`Queued the CodeCartographer guide: ${document.topic}`];
             if (codecartoModeActive)
-                void refreshWorkspaceUi(ctx, lastFeedbackLines);
+                void refreshWorkspaceUi(ctx, lastFeedbackLines).catch(() => undefined);
             ctx.ui.notify(`Queued the CodeCartographer guide (${document.topic})`, "info");
         },
     });
@@ -917,7 +964,7 @@ export default function codeCartographerExtension(pi) {
                     // A workspace session already has a widget; fold the result into it.
                     if (ctx.hasUI)
                         ctx.ui.setWidget(BROADSIDE_WIDGET_ID, undefined);
-                    void refreshWorkspaceUi(ctx, lines);
+                    void refreshWorkspaceUi(ctx, lines).catch(() => undefined);
                 }
                 else if (ctx.hasUI) {
                     // Scout-only repository: the Broad-Side widget is the only place

package/dist/mcp-server/server.js

@@ -24,6 +24,20 @@ import { initLibrary } from "../core/library.js";
 import { loadUserConfig, resolveUserConfigPath } from "../core/orchestrator-config.js";
 import { writeDashboard } from "../extensions/codecarto/dashboard-writer.js";
 // ---------- input helpers ----------
+/**
+ * Normalize an optional `phase` argument. A client can send any JSON, and
+ * `args.phase?.trim()` throws a bare TypeError on a number or an object —
+ * surfacing as an opaque InternalError rather than telling the caller which
+ * argument was wrong. Sibling handlers already guard the required case.
+ */
+function requireOptionalPhase(phase) {
+    if (phase === undefined || phase === null)
+        return undefined;
+    if (typeof phase !== "string") {
+        throw new McpError(ErrorCode.InvalidParams, `phase must be a string when provided, got ${typeof phase}`);
+    }
+    return phase.trim() || undefined;
+}
 async function validateCwd(cwd) {
     if (typeof cwd !== "string" || !cwd.trim()) {
         throw new McpError(ErrorCode.InvalidParams, "cwd is required");
@@ -148,7 +162,7 @@ export async function handleStatus(args) {
     const currentPhase = nextPhase?.id ?? state.status.current_phase ?? "complete";
     const completed = state.pipeline.phase_order.filter((id) => state.status.phases[id]?.status === "complete").length;
     const totalCarryForward = Object.values(state.status.phases).reduce((sum, phase) => sum + (phase.carry_forward?.length ?? 0), 0);
-    const currentOpenQuestions = currentPhase === "complete" ? 0 : state.status.phases[currentPhase]?.open_questions.length ?? 0;
+    const currentOpenQuestions = currentPhase === "complete" ? 0 : state.status.phases[currentPhase]?.open_questions?.length ?? 0;
     const terminalOpenQuestions = Object.values(state.status.phases).reduce((sum, phase) => sum + (phase.open_questions?.length ?? 0), 0);
     const postPipelinePending = state.status.post_pipeline.filter((entry) => entry.status !== "resolved").length;
     const scaffoldNotice = describeScaffoldStaleness(state);
@@ -237,7 +251,7 @@ export async function handlePhase(args) {
 export async function handleValidate(args) {
     const cwd = await validateCwd(args.cwd);
     const state = await requireWorkspace(cwd);
-    const validation = await validatePhaseOutput(state, args.phase?.trim() || undefined).catch((error) => {
+    const validation = await validatePhaseOutput(state, requireOptionalPhase(args.phase)).catch((error) => {
         throw new McpError(ErrorCode.InvalidParams, error instanceof Error ? error.message : String(error));
     });
     const summary = buildValidationSummary(validation).join("\n");
@@ -256,7 +270,7 @@ export async function handleValidate(args) {
 export async function handleComplete(args) {
     const cwd = await validateCwd(args.cwd);
     const initialState = await requireWorkspace(cwd);
-    const validation = await validatePhaseOutput(initialState, args.phase?.trim() || undefined).catch((error) => {
+    const validation = await validatePhaseOutput(initialState, requireOptionalPhase(args.phase)).catch((error) => {
         throw new McpError(ErrorCode.InvalidParams, error instanceof Error ? error.message : String(error));
     });
     if (validation.overall === "FAIL" || validation.overall === "MISSING") {
@@ -377,9 +391,17 @@ async function resolveLibraryPath(args) {
  * the publish tool enforces.
  */
 async function loadEffectiveConfig(cwd) {
-    return typeof cwd === "string" && cwd.trim() !== ""
-        ? loadCodecartoConfig(join(cwd.trim(), ".codecarto"))
-        : loadUserConfig();
+    if (typeof cwd !== "string" || cwd.trim() === "")
+        return loadUserConfig();
+    // A relative path here resolves against the server process's working
+    // directory, not the caller's, so it would quietly read some other
+    // workspace's config — and this config decides whether publish_confirm
+    // gates the write. Refuse rather than answer from the wrong file.
+    const trimmed = cwd.trim();
+    if (!isAbsolute(trimmed)) {
+        throw new McpError(ErrorCode.InvalidParams, `cwd must be an absolute path, got: ${trimmed}`);
+    }
+    return loadCodecartoConfig(join(trimmed, ".codecarto"));
 }
 function asStringArray(value, fieldName) {
     if (!Array.isArray(value)) {
@@ -731,6 +753,13 @@ export async function handleLibraryInit(args) {
 }
 export async function handleVision(args) {
     const cwd = await validateCwd(args.cwd);
+    // raw_text is interpolated straight into the returned prompt, so an absent
+    // value silently becomes the literal string "undefined" for the agent to
+    // synthesize a vision brief from. Every sibling handler validates its
+    // required string argument; this one did not.
+    if (typeof args.raw_text !== "string" || !args.raw_text.trim()) {
+        throw new McpError(ErrorCode.InvalidParams, "raw_text is required (the user's raw product description)");
+    }
     const workspaceDir = join(cwd, ".codecarto");
     const interviewPath = join(workspaceDir, "findings", "vision-capture", "INTERVIEW.md");
     const visionPath = join(workspaceDir, "inputs", "vision.md");
@@ -757,8 +786,8 @@ export async function handleVision(args) {
     });
 }
 export async function handleConfig(args) {
-    const config = args.cwd
-        ? await loadCodecartoConfig(join(args.cwd, ".codecarto"))
+    const config = args.cwd !== undefined && args.cwd !== null
+        ? await loadCodecartoConfig(join(await validateCwd(args.cwd), ".codecarto"))
         : await loadUserConfig();
     const userConfigPath = resolveUserConfigPath();
     const workspaceConfigPath = args.cwd ? join(args.cwd, ".codecarto", "workflow", "config.yaml") : null;
@@ -976,6 +1005,11 @@ export async function handleBroadside(args) {
                 includeTriage,
                 retryTruncated,
                 onStatus: (lensId, status, counts) => lines.push(`  ${lensId}: ${status} (${counts.completed ?? 0}/${counts.total ?? "?"})`),
+            }).catch((error) => {
+                // The `collect` action normalizes this same call; without it here,
+                // a failure during submit-with-wait reached the client as an
+                // opaque InternalError instead of naming its cause.
+                throw new McpError(ErrorCode.InvalidRequest, error instanceof Error ? error.message : String(error));
             });
             lines.push("", collectResultText(collect));
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codecartographer-pi",
-  "version": "0.19.0",
+  "version": "0.19.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",