codecartographer-pi 0.22.1 → 0.22.3

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.22.1
+scaffold_version: 0.22.3

package/README.md

@@ -396,7 +396,7 @@ codecarto_broadside {cwd, action: "status"}                   # what is in fligh
 codecarto_broadside {cwd, action: "collect"}                  # poll, save, synthesize, triage
 ```
 
-Submit and collect are separate because batch jobs routinely take tens of minutes; collect is resumable and picks up whatever is still in flight (`wait_seconds: 0`, the default, polls once and returns). Submit prices the run from the collected file sizes against the model's live per-token pricing (cached 24h) and refuses when the estimate exceeds `max_cost` — $1.00 unless the config or the call sets another value, `0` for no limit — unless `force: true` is passed — a pre-flight estimate, not a runtime stop. Actual spend lands in each run's `run-meta.json`.
+Submit and collect are separate because batch jobs routinely take tens of minutes; collect is resumable and picks up whatever is still in flight (`wait_seconds: 0`, the default, polls once and returns), and two collects on one run — a retried tool call, a second session — never pay for the synthesis, triage, or truncation retry twice: each is claimed in the run's state before it is submitted, and a collect whose client has gone away stops polling and submits nothing further. Submit prices the run from the collected file sizes against the model's live per-token pricing (cached 24h) and refuses when the estimate exceeds `max_cost` — $1.00 unless the config or the call sets another value, `0` for no limit — unless `force: true` is passed — a pre-flight estimate, not a runtime stop. Actual spend lands in each run's `run-meta.json`.
 
 Repository defaults live in `.codecarto/broadside/config.yaml` (`model`, `api_key`, `default_lenses`, `max_cost`, `pricing` overrides, `lens_models`, `incremental`, `retry_truncated`, `include_synthesis`, `include_triage`, `wait_seconds`); an explicit tool parameter always wins. `lens_models` routes individual lenses to their own batch model — a stronger model changes security and defect findings far more than it changes an architecture map — and each override is priced, capability-checked, and clamped exactly like the default, with the estimate broken out per lens so a mixed-model run cannot be approved without seeing which lens costs what. CodeCartographer ships no stronger default: which model earns its price depends on your repository and budget, so compare candidates with the `models` action and choose — for one run with the `model` and `lens_models` parameters (Pi: `--model=ID`, `--lens-model=LENS:ID`), or for the repository in `config.yaml`. The `models` listing is advisory: OpenRouter's catalog returns a `:batch` id for some models its Batch API then refuses (`does not have a :batch endpoint`), at no cost, and nothing in the catalog tells them apart — so the listing tags the ids this repository's own submits have seen accepted or refused, and a refused lens says why in the submit report. `codecarto_skill {cwd, name: "broadside"}` returns the reading guide for a completed run, and unlike post-pipeline skills it is not gated on a finished pipeline.
 

package/dist/core/broadside.d.ts

@@ -230,7 +230,24 @@ export type BroadsideTriageEntry = {
     batchId?: string;
     status: "pending" | "submitted" | "completed" | "failed";
     cost?: number;
+    error?: string;
 };
+/** The truncation retry pass of one run: one batch per model (#206). */
+export type BroadsideRetryEntry = {
+    status: "submitted" | "completed" | "failed";
+    batches: Array<{
+        model: string;
+        batchId: string;
+    }>;
+    /** When the owning collect claimed the pass (#322). */
+    claimedAt: string;
+};
+/**
+ * The parts of a run that cost money to submit and that exactly one collect
+ * may own: the two post-passes and the truncation retry (#322).
+ */
+export type BroadsideRunSlot = "synthesis" | "triage" | "retry";
+export declare const BROADSIDE_RUN_SLOTS: readonly BroadsideRunSlot[];
 export type BroadsideRun = {
     id: string;
     createdAt: string;
@@ -241,6 +258,11 @@ export type BroadsideRun = {
     batches: Partial<Record<BroadsideLensId, BroadsideBatchEntry>>;
     synthesis: BroadsideSynthesisEntry;
     triage: BroadsideTriageEntry;
+    /**
+     * The truncation retry pass (#133), recorded so that two collects on one
+     * run cannot both submit it (#322). Absent until a collect claims it.
+     */
+    retry?: BroadsideRetryEntry;
     totalCost?: number;
     pricing?: ModelPricing;
     maxCost?: number;
@@ -438,6 +460,8 @@ export type BroadsideCollectResult = {
     truncatedCount: number;
     /** Truncated slices recovered by the automatic re-submit pass (#133). */
     retriedCount: number;
+    /** Another collect on this run owns the retry pass; its result lands on a later collect (#322). */
+    retryElsewhere?: boolean;
     lensOutcomes: Partial<Record<BroadsideLensId, {
         status: string;
         cost?: number;
@@ -555,6 +579,35 @@ export declare function updateBroadsideStateAtomically(broadsideDir: string, mut
  * restored the next time its own operation checkpoints.
  */
 export declare function persistBroadsideRun(broadsideDir: string, run: BroadsideRun): Promise<BroadsideStateFile>;
+/**
+ * Record a collect's view of its run, keeping whatever is further along on
+ * disk (#322).
+ *
+ * Two collects on one run each hold the run in memory and each used to write
+ * the whole thing back, so the last writer replaced the other's post-pass
+ * entries with its own — and both had submitted their own post-passes, since
+ * each decided from the copy it loaded at entry. This writer merges slot by
+ * slot: a post-pass or retry entry that is further along on disk (claimed
+ * over pending, submitted over claimed, settled over submitted) wins and is
+ * copied into `run`, so the caller reports what is true; a lens entry never
+ * goes backwards from terminal to polling. A tie keeps this collect's copy,
+ * so the collect that settled a pass records its cost. Submitting is guarded
+ * separately by {@link claimRunSlot}.
+ */
+export declare function persistBroadsideRunMerging(broadsideDir: string, run: BroadsideRun): Promise<BroadsideStateFile>;
+/**
+ * Claim one spending slot of a run for this collect (#322).
+ *
+ * Read-modify-write under the state lock: if the slot on disk is still
+ * unclaimed (`pending`, or absent for the retry), it is marked `submitted`
+ * with no batch id *before* any network call and `true` comes back — this
+ * collect owns it and may submit. Otherwise another collect got there first:
+ * its entry is copied into `run` and `false` comes back. An adopted entry
+ * with a batch id can be polled (polling is idempotent); one without an id
+ * is a claim whose owner has not recorded the id yet, and is reported as in
+ * flight elsewhere.
+ */
+export declare function claimRunSlot(broadsideDir: string, run: BroadsideRun, slot: BroadsideRunSlot): Promise<boolean>;
 export declare function loadBroadsideConfig(broadsideDir: string): Promise<BroadsideConfig>;
 /** The shipped defaults: what an absent config.yaml means. */
 export declare function defaultBroadsideConfig(): BroadsideConfig;
@@ -624,6 +677,12 @@ export declare function pollBatchUntilTerminal(batchId: string, apiKey: string,
     onStatus?: (status: string, counts: Record<string, unknown>) => void;
     fetcher?: FetchLike;
     pollIntervalMs?: number;
+    /**
+     * Stops polling early with the same synthetic `timeout` a spent budget
+     * returns: the batch keeps running server-side and a later collect
+     * claims it. The MCP server aborts when its client disconnects (#322).
+     */
+    signal?: AbortSignal;
 }): Promise<Record<string, unknown>>;
 /**
  * Poll several batch ids in parallel against one shared deadline. Collect
@@ -639,6 +698,7 @@ export declare function pollBatchesConcurrently(entries: Array<{
     deadlineMs?: number;
     fetcher?: FetchLike;
     pollIntervalMs?: number;
+    signal?: AbortSignal;
     onStatus?: (lensId: string, status: string, counts: Record<string, unknown>) => void;
 }): Promise<Map<string, Record<string, unknown>>>;
 export declare function runBroadsideSubmit(cwd: string, apiKey: string, opts?: {
@@ -713,6 +773,14 @@ export declare function runBroadsideCollect(cwd: string, apiKey: string, opts?:
      * once a newer submit existed (#268). `status` lists the ids.
      */
     runId?: string;
+    /**
+     * Stops polling and submits nothing further once fired; what was
+     * already submitted keeps running server-side for a later collect to
+     * claim. The MCP server fires it when its client disconnects (#322).
+     */
+    signal?: AbortSignal;
+    /** Poll cadence override; tests drive the loop faster than 15 s. */
+    pollIntervalMs?: number;
 }): Promise<BroadsideCollectResult>;
 export declare function runBroadsideStatus(cwd: string): Promise<{
     state: BroadsideStateFile;

package/dist/core/broadside.js

@@ -140,6 +140,7 @@ export function retryReasoningFor(original) {
     const { max_tokens: _cap, effort: _effort, ...rest } = original ?? {};
     return { ...rest, effort: "low" };
 }
+export const BROADSIDE_RUN_SLOTS = ["synthesis", "triage", "retry"];
 /**
  * OpenRouter rejected the API key (HTTP 401/403). Thrown from the catalog
  * lookup rather than swallowed into "could not price" or a silent built-in
@@ -1534,6 +1535,110 @@ export async function persistBroadsideRun(broadsideDir, run) {
             state.runs[index] = run;
     });
 }
+/** Where a lens batch entry stands, for keeping the more advanced of two. */
+function batchEntryRank(entry) {
+    if (!entry)
+        return -1;
+    if (BROADSIDE_TERMINAL_ENTRY_STATUSES.includes(entry.status))
+        return 2;
+    if (entry.batchId)
+        return 1;
+    return 0;
+}
+/** Where a post-pass entry stands: unclaimed, claimed, submitted, settled. */
+function passEntryRank(entry) {
+    if (!entry || entry.status === "pending")
+        return 0;
+    if (entry.status === "submitted")
+        return entry.batchId ? 2 : 1;
+    return 3;
+}
+/** Where the retry pass stands: absent, claimed, submitted, settled. */
+function retryEntryRank(entry) {
+    if (!entry)
+        return 0;
+    if (entry.status === "submitted")
+        return entry.batches.length > 0 ? 2 : 1;
+    return 3;
+}
+/**
+ * Record a collect's view of its run, keeping whatever is further along on
+ * disk (#322).
+ *
+ * Two collects on one run each hold the run in memory and each used to write
+ * the whole thing back, so the last writer replaced the other's post-pass
+ * entries with its own — and both had submitted their own post-passes, since
+ * each decided from the copy it loaded at entry. This writer merges slot by
+ * slot: a post-pass or retry entry that is further along on disk (claimed
+ * over pending, submitted over claimed, settled over submitted) wins and is
+ * copied into `run`, so the caller reports what is true; a lens entry never
+ * goes backwards from terminal to polling. A tie keeps this collect's copy,
+ * so the collect that settled a pass records its cost. Submitting is guarded
+ * separately by {@link claimRunSlot}.
+ */
+export async function persistBroadsideRunMerging(broadsideDir, run) {
+    return updateBroadsideStateAtomically(broadsideDir, (state) => {
+        const index = state.runs.findIndex((candidate) => candidate.id === run.id);
+        const onDisk = index === -1 ? undefined : state.runs[index];
+        if (onDisk) {
+            if (passEntryRank(onDisk.synthesis) > passEntryRank(run.synthesis))
+                run.synthesis = onDisk.synthesis;
+            if (passEntryRank(onDisk.triage) > passEntryRank(run.triage))
+                run.triage = onDisk.triage;
+            if (retryEntryRank(onDisk.retry) > retryEntryRank(run.retry))
+                run.retry = onDisk.retry;
+            for (const [lensId, theirs] of Object.entries(onDisk.batches)) {
+                if (theirs && batchEntryRank(theirs) > batchEntryRank(run.batches[lensId]))
+                    run.batches[lensId] = theirs;
+            }
+        }
+        if (index === -1)
+            state.runs.push(run);
+        else
+            state.runs[index] = run;
+    });
+}
+/**
+ * Claim one spending slot of a run for this collect (#322).
+ *
+ * Read-modify-write under the state lock: if the slot on disk is still
+ * unclaimed (`pending`, or absent for the retry), it is marked `submitted`
+ * with no batch id *before* any network call and `true` comes back — this
+ * collect owns it and may submit. Otherwise another collect got there first:
+ * its entry is copied into `run` and `false` comes back. An adopted entry
+ * with a batch id can be polled (polling is idempotent); one without an id
+ * is a claim whose owner has not recorded the id yet, and is reported as in
+ * flight elsewhere.
+ */
+export async function claimRunSlot(broadsideDir, run, slot) {
+    let owned = false;
+    const claimedAt = new Date().toISOString();
+    await updateBroadsideStateAtomically(broadsideDir, (state) => {
+        const index = state.runs.findIndex((candidate) => candidate.id === run.id);
+        const onDisk = index === -1 ? undefined : state.runs[index];
+        const theirs = onDisk?.[slot];
+        const unclaimed = slot === "retry" ? theirs === undefined : theirs?.status === "pending";
+        if (onDisk && !unclaimed) {
+            run[slot] = theirs;
+            owned = false;
+            return;
+        }
+        owned = true;
+        if (slot === "retry") {
+            run.retry = { status: "submitted", batches: [], claimedAt };
+        }
+        else {
+            run[slot] = { ...run[slot], status: "submitted", batchId: undefined };
+        }
+        if (!onDisk) {
+            state.runs.push(run);
+        }
+        else {
+            onDisk[slot] = run[slot];
+        }
+    });
+    return owned;
+}
 /** Read a `reasoning:` block from config.yaml, ignoring anything malformed. */
 function parseReasoningConfig(raw) {
     if (raw === false)
@@ -2025,6 +2130,8 @@ export async function pollBatchUntilTerminal(batchId, apiKey, opts = {}) {
         ...(lastError && sawBatch && { last_error: lastError }),
     });
     for (;;) {
+        if (opts.signal?.aborted)
+            return { ...timedOut(), aborted: true };
         let batch;
         try {
             batch = await fetchBatch(batchId, apiKey, fetcher);
@@ -2057,8 +2164,26 @@ export async function pollBatchUntilTerminal(batchId, apiKey, opts = {}) {
             return batch;
         if (Date.now() >= deadline)
             return timedOut();
-        await sleep(intervalMs);
-    }
+        await sleepUnlessAborted(intervalMs, opts.signal);
+    }
+}
+/** Sleep, but wake at once when the signal fires so an abort is not a poll interval late. */
+function sleepUnlessAborted(ms, signal) {
+    if (!signal)
+        return sleep(ms);
+    if (signal.aborted)
+        return Promise.resolve();
+    return new Promise((resolve) => {
+        const timer = setTimeout(() => {
+            signal.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            resolve();
+        };
+        signal.addEventListener("abort", onAbort, { once: true });
+    });
 }
 /**
  * Poll several batch ids in parallel against one shared deadline. Collect
@@ -2075,6 +2200,7 @@ export async function pollBatchesConcurrently(entries, apiKey, opts = {}) {
             deadlineMs,
             fetcher: opts.fetcher,
             pollIntervalMs: opts.pollIntervalMs,
+            signal: opts.signal,
             onStatus: (status, counts) => opts.onStatus?.(lensId, status, counts),
         });
         results.set(batchId, batch);
@@ -2606,6 +2732,12 @@ export async function runBroadsideCollect(cwd, apiKey, opts = {}) {
     }
     const runDir = join(broadsideDir, run.outputDir);
     await mkdir(runDir, { recursive: true });
+    // The spending slots this collect has claimed (#322); only a claimed slot
+    // is ever submitted from here. Every write-back merges with the file, so a
+    // slot another collect has moved further along is never overwritten.
+    const owned = new Set();
+    const persist = () => persistBroadsideRunMerging(broadsideDir, run);
+    const aborted = () => opts.signal?.aborted === true;
     const deadline = Date.now() + (opts.waitMs ?? BROADSIDE_DEFAULT_POLL_BUDGET_MS);
     let totalCost = 0;
     let resultCount = 0;
@@ -2633,6 +2765,8 @@ export async function runBroadsideCollect(cwd, apiKey, opts = {}) {
     const polled = await pollBatchesConcurrently(inFlight, apiKey, {
         deadlineMs: Math.max(0, deadline - Date.now()),
         fetcher: opts.fetcher,
+        pollIntervalMs: opts.pollIntervalMs,
+        signal: opts.signal,
         onStatus: opts.onStatus,
     });
     for (const { lensId } of inFlight) {
@@ -2682,7 +2816,7 @@ export async function runBroadsideCollect(cwd, apiKey, opts = {}) {
             const error = explainBatchError(batch.error);
             lensOutcomes[lensId] = { status, cost: entry.cost, resultCount: entry.resultCount, ...(error && { error }) };
         }
-        await persistBroadsideRun(broadsideDir, run);
+        await persist();
     }
     // #133: re-submit truncated slices once with a bumped output cap and low
     // reasoning effort. Batch requests are pure, so re-running is always safe;
@@ -2700,7 +2834,36 @@ export async function runBroadsideCollect(cwd, apiKey, opts = {}) {
     // lens pass, still present here (#206). Grouping also keeps the retry to
     // one job per model against OpenRouter's 16-concurrent-job quota.
     let retriedCount = 0;
-    if (opts.retryTruncated !== false && truncatedCount > 0) {
+    let retryElsewhere = false;
+    // A collect that polled nothing — every lens already terminal — still owes
+    // the retry if the collect that saved the results never got to it (it
+    // died, or its client did: #322). Read the saved results back and let the
+    // claim decide; a recovered slice re-parses clean, so this costs nothing
+    // once the retry has run.
+    if (opts.retryTruncated !== false && allLensResults.length === 0 && !aborted()) {
+        const everyLensTerminal = run.lenses.every((lensId) => {
+            const entry = run.batches[lensId];
+            return entry && BROADSIDE_TERMINAL_ENTRY_STATUSES.includes(entry.status);
+        });
+        if (everyLensTerminal) {
+            const restored = await loadSavedLensResults(runDir, run.lenses);
+            if (restored.some((s) => s.truncated)) {
+                allLensResults.push(...restored);
+                truncatedCount = restored.filter((s) => s.truncated).length;
+            }
+        }
+    }
+    if (opts.retryTruncated !== false && truncatedCount > 0 && !aborted()) {
+        // Claim the pass before spending: a second collect on this run finds the
+        // claim and leaves the retry to the first (#322). A retry another
+        // collect has already settled is not run again — its truncation is
+        // what it is.
+        if (await claimRunSlot(broadsideDir, run, "retry"))
+            owned.add("retry");
+        else if (run.retry?.status === "submitted")
+            retryElsewhere = true;
+    }
+    if (opts.retryTruncated !== false && truncatedCount > 0 && owned.has("retry")) {
         const requestsByCustomId = await loadStoredRequests(runDir);
         const byModel = new Map();
         for (const stored of allLensResults) {
@@ -2730,6 +2893,8 @@ export async function runBroadsideCollect(cwd, apiKey, opts = {}) {
         // Submit every group, then poll whatever was accepted, together.
         const submitted = [];
         for (const [model, group] of byModel) {
+            if (aborted())
+                break;
             try {
                 const { batchId, error } = await submitBatch(group.requests, apiKey, opts.fetcher, model);
                 if (!error && batchId)
@@ -2740,6 +2905,15 @@ export async function runBroadsideCollect(cwd, apiKey, opts = {}) {
                 // truncated results in place — nothing is lost.
             }
         }
+        // Record the ids under the claim so a later collect can see what was
+        // paid for, even if this one never returns. No group at all means every
+        // truncated slice was already at its model's ceiling: nothing to retry.
+        run.retry = {
+            ...run.retry,
+            batches: submitted,
+            status: submitted.length > 0 ? "submitted" : byModel.size === 0 ? "completed" : "failed",
+        };
+        await persist();
         const polled = await pollBatchesConcurrently(submitted.map(({ model, batchId }) => ({ lensId: `retry:${model}`, batchId })), apiKey, {
             // Share the caller's deadline. Each of these polls used to start a
             // fresh 25-minute budget, so `wait_seconds` bounded only the lens
@@ -2747,6 +2921,8 @@ export async function runBroadsideCollect(cwd, apiKey, opts = {}) {
             // minutes.
             deadlineMs: Math.max(0, deadline - Date.now()),
             fetcher: opts.fetcher,
+            pollIntervalMs: opts.pollIntervalMs,
+            signal: opts.signal,
             onStatus: opts.onStatus,
         });
         for (const { model, batchId } of submitted) {
@@ -2774,13 +2950,17 @@ export async function runBroadsideCollect(cwd, apiKey, opts = {}) {
                 retriedCount += 1;
             }
         }
+        // Every retry batch reached a terminal status, or the poll ran out.
+        if (submitted.length > 0 && submitted.every(({ batchId }) => polled.get(batchId)?.status === "completed")) {
+            run.retry = { ...run.retry, status: "completed" };
+        }
         truncatedCount = allLensResults.filter((s) => s.truncated).length;
         for (const [lensId, outcome] of Object.entries(lensOutcomes)) {
             if (outcome.truncated !== undefined) {
                 outcome.truncated = allLensResults.filter((s) => s.lensId === lensId && s.truncated).length;
             }
         }
-        await persistBroadsideRun(broadsideDir, run);
+        await persist();
     }
     // Synthesis + triage: cross-lens post-passes, only after every lens batch
     // is terminal. Triage turns the leads into a prioritized work order.
@@ -2819,22 +2999,27 @@ export async function runBroadsideCollect(cwd, apiKey, opts = {}) {
             // Both post-passes consume the same findings; they run as two
             // batches (different response_format schemas cannot share one)
             // submitted together and polled in turn.
-            const passes = [
-                ...(wantSynthesis && run.synthesis.status === "pending"
-                    ? [{
-                            kind: "synthesis",
-                            request: buildSynthesisRequest(findingsText, truncatedNote, run.model),
-                            entry: run.synthesis,
-                        }]
-                    : []),
-                ...(wantTriage && run.triage.status === "pending"
-                    ? [{
-                            kind: "triage",
-                            request: buildTriageRequest(findingsText, truncatedNote, run.model),
-                            entry: run.triage,
-                        }]
-                    : []),
-            ];
+            // Claim each wanted, still-pending pass before building its request:
+            // a second collect on this run adopts the first one's entry instead
+            // of submitting its own (#322). An abort submits nothing further.
+            const passes = [];
+            for (const kind of ["synthesis", "triage"]) {
+                const want = kind === "synthesis" ? wantSynthesis : wantTriage;
+                if (!want || aborted())
+                    continue;
+                if ((kind === "synthesis" ? run.synthesis : run.triage).status !== "pending")
+                    continue;
+                if (!(await claimRunSlot(broadsideDir, run, kind)))
+                    continue;
+                owned.add(kind);
+                passes.push({
+                    kind,
+                    request: kind === "synthesis"
+                        ? buildSynthesisRequest(findingsText, truncatedNote, run.model)
+                        : buildTriageRequest(findingsText, truncatedNote, run.model),
+                    entry: kind === "synthesis" ? run.synthesis : run.triage,
+                });
+            }
             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
@@ -2869,16 +3054,22 @@ export async function runBroadsideCollect(cwd, apiKey, opts = {}) {
                     pass.entry.status = "failed";
                 }
             }));
-            await persistBroadsideRun(broadsideDir, run);
+            await persist();
+            // Poll both passes together against the shared deadline. Polled in
+            // turn, the first pass could spend the whole budget and leave the
+            // second a single poll (0.22.1 live run: triage settled, synthesis
+            // left running though it had been submitted at the same moment).
+            // A pass whose poll runs out stays `submitted`, so the batch is
+            // already paid for and a later collect claims its result.
+            const polledPasses = await pollBatchesConcurrently([...submitted.values()].map(({ batchId, pass }) => ({ lensId: pass.kind, batchId })), apiKey, {
+                deadlineMs: Math.max(0, deadline - Date.now()),
+                fetcher: opts.fetcher,
+                pollIntervalMs: opts.pollIntervalMs,
+                signal: opts.signal,
+                onStatus: opts.onStatus,
+            });
             for (const { batchId, pass } of submitted.values()) {
-                const batch = await pollBatchUntilTerminal(batchId, apiKey, {
-                    // 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,
-                });
+                const batch = polledPasses.get(batchId) ?? { id: batchId, status: "timeout" };
                 if (batch.status === "completed") {
                     const usage = (batch.usage ?? {});
                     const cost = typeof usage.cost === "number" ? usage.cost : undefined;
@@ -2911,7 +3102,7 @@ export async function runBroadsideCollect(cwd, apiKey, opts = {}) {
                 // 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);
+                await persist();
             }
         }
     }
@@ -2921,7 +3112,7 @@ export async function runBroadsideCollect(cwd, apiKey, opts = {}) {
     });
     run.status = terminal ? (resultCount > 0 ? "completed" : "failed") : "partial";
     run.totalCost = totalCost;
-    await persistBroadsideRun(broadsideDir, run);
+    await persist();
     await writeFile(join(runDir, "run-meta.json"), `${JSON.stringify({
         experimental: true,
         method: "Broad-Side (OpenRouter Batch API)",
@@ -2953,6 +3144,7 @@ export async function runBroadsideCollect(cwd, apiKey, opts = {}) {
         resultCount,
         truncatedCount,
         retriedCount,
+        ...(retryElsewhere && { retryElsewhere: true }),
         lensOutcomes,
         synthesis: run.synthesis,
         triage: run.triage,
@@ -3220,9 +3412,24 @@ export function collectResultText(result) {
     if (result.retriedCount > 0) {
         lines.push(`  ↻ ${result.retriedCount} truncated result(s) recovered by re-submission with a doubled output cap.`);
     }
+    if (result.retryElsewhere) {
+        lines.push("  ↻ The truncation retry is in flight in another collect on this run; collect again for its result.");
+    }
     if (result.truncatedCount > 0) {
         lines.push(`  ⚠ ${result.truncatedCount} result(s) still truncated after retry — their modules are unscouted, not clean.`);
     }
+    // A pass still in flight or retired must appear: a run reported
+    // "completed" with no synthesis line read as "no synthesis was run",
+    // when the batch was running and a later collect would have claimed it
+    // (0.22.1 live run — the collect's wait ran out during the pass).
+    const passInFlight = (kind, entry) => {
+        if (entry.status === "submitted") {
+            lines.push(`  ${kind}: ${entry.batchId ? "still running" : "in flight in another collect"} — collect again for its result.`);
+        }
+        else if (entry.status === "failed") {
+            lines.push(`  ${kind}: failed${entry.error ? ` — ${explainBatchError(entry.error)}` : ""}`);
+        }
+    };
     if (result.synthesis.status === "completed") {
         lines.push(`  synthesis: completed, $${(result.synthesis.cost ?? 0).toFixed(6)}`);
         if (result.topFindings.length > 0) {
@@ -3232,6 +3439,9 @@ export function collectResultText(result) {
             }
         }
     }
+    else {
+        passInFlight("synthesis", result.synthesis);
+    }
     if (result.triage.status === "completed") {
         lines.push(`  triage: completed, $${(result.triage.cost ?? 0).toFixed(6)}`);
         if (result.topTriageItems.length > 0) {
@@ -3242,8 +3452,8 @@ export function collectResultText(result) {
             }
         }
     }
-    else if (result.triage.status === "failed") {
-        lines.push("  triage: failed");
+    else {
+        passInFlight("triage", result.triage);
     }
     lines.push("", "Disclaimer: Broad-Side findings are unverified scouting signals from a batch model, not validated claims.");
     return lines.join("\n");

package/dist/extensions/codecarto/completions.d.ts

@@ -0,0 +1,18 @@
+export interface CompletionCandidate {
+    value: string;
+    label?: string;
+    description?: string;
+}
+export interface CompletionItem {
+    value: string;
+    label: string;
+    description?: string;
+}
+/**
+ * Complete the last whitespace-separated token of `prefix` from `candidates`,
+ * returning items whose `value` is the full argument text Pi should put in
+ * the line — every earlier token, then the candidate. A candidate already
+ * typed as an earlier token is not offered again. Returns null when nothing
+ * matches, which is what Pi expects for "no popup".
+ */
+export declare function completeLastToken(prefix: string, candidates: readonly CompletionCandidate[]): CompletionItem[] | null;

package/dist/extensions/codecarto/completions.js

@@ -0,0 +1,36 @@
+// Argument completion for the /codecarto-* slash commands.
+//
+// Pi hands `getArgumentCompletions` everything typed after the command name,
+// and when the user accepts an item it replaces all of that text with the
+// item's `value` (pi 0.85: `argumentText = textBeforeCursor.slice(spaceIndex
+// + 1)` on the way in, `applyCompletion` slicing `cursorCol - prefix.length`
+// on the way out). A completer that matches the *last* token but returns a
+// bare flag therefore erases every flag typed before it: with the popup open,
+// `/codecarto-next --auto --llm-steer` became `/codecarto-next --llm-steer` on
+// Enter, the steered phase ran alone, and the auto run never started. The
+// same shape turned `--auto --strict` into `--strict`, the one combination
+// the parser rejects.
+//
+// So: match the last token, but return the whole line.
+/**
+ * Complete the last whitespace-separated token of `prefix` from `candidates`,
+ * returning items whose `value` is the full argument text Pi should put in
+ * the line — every earlier token, then the candidate. A candidate already
+ * typed as an earlier token is not offered again. Returns null when nothing
+ * matches, which is what Pi expects for "no popup".
+ */
+export function completeLastToken(prefix, candidates) {
+    const tokens = prefix.split(/\s+/);
+    const last = tokens.pop() ?? "";
+    const earlier = tokens.filter((token) => token.length > 0);
+    const head = earlier.join(" ");
+    const typed = new Set(earlier);
+    const items = candidates
+        .filter((candidate) => candidate.value.startsWith(last) && !typed.has(candidate.value))
+        .map((candidate) => ({
+        value: head ? `${head} ${candidate.value}` : candidate.value,
+        label: candidate.label ?? candidate.value,
+        ...(candidate.description && { description: candidate.description }),
+    }));
+    return items.length > 0 ? items : null;
+}

package/dist/extensions/codecarto/index.js

@@ -6,6 +6,7 @@ import { parseDashboardFlags } from "./dashboard-flags.js";
 import { narrateDashboard } from "./dashboard-narrator.js";
 import { parseBroadsideFlags, KNOWN_BROADSIDE_TOKENS } from "./broadside-flags.js";
 import { parseNextFlags } from "./next-flags.js";
+import { completeLastToken } from "./completions.js";
 import { buildPiGuideMessage } from "./guide-framing.js";
 import { isCtxLive, notifyCtx } from "./notify.js";
 import { phaseCompactionExtension } from "./phase-compaction.js";
@@ -432,12 +433,7 @@ export default function codeCartographerExtension(pi) {
     });
     pi.registerCommand("codecarto-init", {
         description: "Initialize .codecarto/ in the current repository",
-        getArgumentCompletions: (prefix) => {
-            const items = Object.keys(PIPELINE_ALIASES)
-                .filter((value) => value.startsWith(prefix))
-                .map((value) => ({ value, label: value }));
-            return items.length > 0 ? items : null;
-        },
+        getArgumentCompletions: (prefix) => completeLastToken(prefix, Object.keys(PIPELINE_ALIASES).map((value) => ({ value }))),
         handler: async (args, ctx) => {
             const trimmedArgs = args.trim();
             const pipelineChoice = resolvePipelineChoice(trimmedArgs);
@@ -536,12 +532,7 @@ export default function codeCartographerExtension(pi) {
     });
     pi.registerCommand("codecarto-switch-pipeline", {
         description: "Switch the active pipeline without losing findings or progress: /codecarto-switch-pipeline <variant>",
-        getArgumentCompletions: (prefix) => {
-            const items = Object.keys(PIPELINE_ALIASES)
-                .filter((value) => value.startsWith(prefix))
-                .map((value) => ({ value, label: value }));
-            return items.length > 0 ? items : null;
-        },
+        getArgumentCompletions: (prefix) => completeLastToken(prefix, Object.keys(PIPELINE_ALIASES).map((value) => ({ value }))),
         handler: async (args, ctx) => {
             const trimmedArgs = args.trim();
             if (!trimmedArgs) {
@@ -595,16 +586,17 @@ export default function codeCartographerExtension(pi) {
             // --strict is offered only once --auto is present, because on its own
             // it is rejected — suggesting it standalone invites the one error the
             // parser has.
+            // Each item's value is the whole argument line (see completions.ts):
+            // accepting `--llm-steer` after `--auto ` keeps the `--auto`.
             const autoAlreadyTyped = prefix.includes("--auto");
-            const items = [
-                { value: "--auto", label: "--auto", description: "run every remaining phase back to back (recommended with --llm-steer)" },
-                { value: "--llm-steer", label: "--llm-steer", description: "seed each phase from the previous phase's closeout; no effect on the first phase" },
-                { value: "--no-llm-steer", label: "--no-llm-steer", description: "force steering off when the workspace config turns it on" },
+            return completeLastToken(prefix, [
+                { value: "--auto", description: "run every remaining phase back to back (recommended with --llm-steer)" },
+                { value: "--llm-steer", description: "seed each phase from the previous phase's closeout; no effect on the first phase" },
+                { value: "--no-llm-steer", description: "force steering off when the workspace config turns it on" },
                 ...(autoAlreadyTyped
-                    ? [{ value: "--strict", label: "--strict", description: "with --auto: stop on PASS WITH GAPS instead of advancing" }]
+                    ? [{ value: "--strict", description: "with --auto: stop on PASS WITH GAPS instead of advancing" }]
                     : []),
-            ].filter((item) => item.value.startsWith(prefix.split(/\s+/).pop() ?? prefix));
-            return items.length > 0 ? items : null;
+            ]);
         },
         handler: async (args, ctx) => {
             const flags = parseNextFlags(args);
@@ -967,10 +959,7 @@ export default function codeCartographerExtension(pi) {
         description: "Read the packaged CodeCartographer agent guide into the session: /codecarto-guide [topic]",
         getArgumentCompletions: async (prefix) => {
             const topics = await listGuideTopics().catch(() => ["overview"]);
-            const items = topics
-                .filter((value) => value.startsWith(prefix))
-                .map((value) => ({ value, label: value }));
-            return items.length > 0 ? items : null;
+            return completeLastToken(prefix, topics.map((value) => ({ value })));
         },
         handler: async (args, ctx) => {
             // The guide is packaged with the extension, not copied into a
@@ -1004,12 +993,9 @@ 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]",
-        getArgumentCompletions: (prefix) => {
-            const items = KNOWN_BROADSIDE_TOKENS
-                .filter((value) => value.startsWith(prefix))
-                .map((value) => ({ value, label: value }));
-            return items.length > 0 ? items : null;
-        },
+        // 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 }))),
         handler: async (args, ctx) => {
             const flags = parseBroadsideFlags(args);
             if (flags.unknown.length > 0) {
@@ -1439,12 +1425,7 @@ export default function codeCartographerExtension(pi) {
     });
     pi.registerCommand("codecarto-dashboard", {
         description: "Regenerate .codecarto/dashboard.html (use --narrate for an LLM executive summary)",
-        getArgumentCompletions: (prefix) => {
-            const items = ["--narrate"]
-                .filter((value) => value.startsWith(prefix))
-                .map((value) => ({ value, label: value }));
-            return items.length > 0 ? items : null;
-        },
+        getArgumentCompletions: (prefix) => completeLastToken(prefix, [{ value: "--narrate" }]),
         handler: async (args, ctx) => {
             const flags = parseDashboardFlags(args);
             if (flags.unknown.length > 0) {
@@ -1515,10 +1496,7 @@ export default function codeCartographerExtension(pi) {
         description: "Apply a post-pipeline amendment from .codecarto/scratch/amendments/, after a preview: /codecarto-amend <name | scratch/amendments/name.yaml>",
         getArgumentCompletions: async (prefix) => {
             const names = await listAmendmentNames(join(sessionCwd ?? process.cwd(), ".codecarto"));
-            const items = names
-                .filter((value) => value.startsWith(prefix))
-                .map((value) => ({ value, label: value }));
-            return items.length > 0 ? items : null;
+            return completeLastToken(prefix, names.map((value) => ({ value })));
         },
         handler: async (args, ctx) => {
             const state = await ensureWorkspaceState(ctx);

package/dist/mcp-server/server.js

@@ -1151,6 +1151,7 @@ export async function handleBroadside(args) {
                 includeSynthesis,
                 includeTriage,
                 retryTruncated,
+                signal: serverLifetime?.signal,
                 // One line per *change* of a lens's status. Every poll used to
                 // append a line, so a four-minute wait returned twenty-six
                 // "in_progress (0/1)" lines before the result (0.22.0 live run).
@@ -1179,6 +1180,7 @@ export async function handleBroadside(args) {
         includeSynthesis,
         includeTriage,
         retryTruncated,
+        signal: serverLifetime?.signal,
         ...(runId && { runId }),
     }).catch((error) => {
         throw new McpError(ErrorCode.InvalidRequest, error instanceof Error ? error.message : String(error));
@@ -1518,7 +1520,7 @@ const TOOLS = [
                 },
                 wait_seconds: {
                     type: "number",
-                    description: "For submit: after submitting, poll up to this many seconds before returning. For collect: poll up to this many seconds before returning with partial state. 0 polls each in-flight batch once and returns without waiting. Falls back to wait_seconds in .codecarto/broadside/config.yaml (default 0).",
+                    description: "For submit: after submitting, poll up to this many seconds before returning. For collect: poll up to this many seconds before returning with partial state. 0 polls each in-flight batch once and returns without waiting. Falls back to wait_seconds in .codecarto/broadside/config.yaml (default 0). The wait is also bounded by the host's own tool-call timeout: if the host gives up first, the server stops polling and submits nothing further, the batches keep running server-side, and the next collect claims them — so prefer submit, then collect later, over a wait longer than the host allows.",
                 },
                 include_synthesis: {
                     type: "boolean",
@@ -1617,8 +1619,27 @@ export function buildServer() {
     });
     return server;
 }
+/**
+ * Fires when the stdio client goes away, so a Broad-Side wait that outlived
+ * the request that asked for it stops polling and submits nothing further
+ * (#322). Batches already accepted keep running server-side; the next collect
+ * claims them. Set only by {@link startStdioServer}; handlers driven directly
+ * (tests, in-process callers) see no signal.
+ */
+let serverLifetime = null;
 export async function startStdioServer() {
     const server = buildServer();
     const transport = new StdioServerTransport();
+    serverLifetime = new AbortController();
+    const lifetime = serverLifetime;
+    server.onclose = () => lifetime.abort();
+    // The SDK's stdio transport listens for stdin `data` and `error` only — it
+    // never sees the end of the stream — so a client that exits mid-request
+    // leaves the server polling with nobody to answer to (#322, observed: a
+    // server outlived its client by fifteen minutes and submitted two paid
+    // post-passes on its own). End of stdin is the client going away.
+    const gone = () => lifetime.abort();
+    process.stdin.once("end", gone);
+    process.stdin.once("close", gone);
     await server.connect(transport);
 }

package/package.json

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