codecartographer-pi 0.24.1 → 0.26.0

package/dist/core/status.js

@@ -1,19 +1,18 @@
 // Status normalization, atomic writes, and file-lock primitives. Pure
 // framework logic shared by every wrapper.
 import { randomBytes } from "node:crypto";
-import { open, readFile, rm, stat } from "node:fs/promises";
-import { basename, join } from "node:path";
+import { open, readdir, readFile, rm, stat, unlink, utimes } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
 import { pathExists, sleep } from "./utils.js";
 import { loadYamlFile } from "./yaml.js";
 export const LOCK_RETRY_MS = 125;
 export const LOCK_TIMEOUT_MS = 5000;
-export const STALE_LOCK_MS = 60_000;
 /**
- * How old the removal lock (`<lock>.break`, see {@link withRemovalLock}) may
- * be before it is treated as left behind by a crashed process. It is held
- * across one stat and one rm, so anything this old was abandoned.
+ * How long a lock ticket may go unrefreshed before its owner is presumed
+ * hung. Owners refresh every quarter of this while they wait or hold, so a
+ * live holder is never broken by age; a dead one is removed at once.
  */
-export const BREAK_LOCK_STALE_MS = LOCK_TIMEOUT_MS;
+export const STALE_LOCK_MS = 60_000;
 export function assertSafePhaseId(phaseId) {
     if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(phaseId)) {
         throw new Error(`Invalid phase id: ${phaseId}`);
@@ -432,161 +431,188 @@ export function applyHandoff(status, handoff) {
     return status;
 }
 /**
- * Take the O_EXCL lock at `lockPath`, waiting up to {@link LOCK_TIMEOUT_MS}
- * and breaking a lock older than {@link STALE_LOCK_MS}.
+ * Take the lock named by `lockPath`, waiting up to `timeoutMs`.
  *
- * The lock file records `pid`, timestamp, and a per-acquisition token, and
- * release removes the file only while it still carries that token. Without
- * the token, release removed whoever's lock was there: after a stale break
- * the previous holder's release deleted the new holder's lock, and a third
- * writer walked straight in (#227).
+ * The lock is a queue of **tickets**: files beside `lockPath` named
+ * `<lock>.t.<order>-<pid>-<token>`, one per waiter, each written by its
+ * owner alone. The holder is the owner of the first ticket in name order
+ * whose process is alive and whose ticket has been refreshed within
+ * `staleMs`; every owner refreshes its ticket on a timer while it waits and
+ * while it holds, so a live holder is never broken however long it holds
+ * (#355 — a publish across a full reindex used to lose its lock at 60 s).
+ * A ticket whose owner is dead, or has not refreshed it in `staleMs`, is
+ * removed by whoever notices — by its own unique name, so two waiters
+ * removing the same dead ticket remove the same inode and nothing else.
+ * No shared path is ever removed and re-created, which is the race every
+ * `rm`-then-recreate stale break carries (#342, #344, #355).
  *
- * Every removal — a release or a stale break — happens under the removal
- * lock (`<lock>.break`) and re-checks what it is about to remove there.
- * Two waiters that both saw a stale lock used to both `rm` it: the second
- * `rm` landed after the first waiter had re-created the file, so both held
- * the lock (#342). A file can only be created while the path is free, and
- * only a removal-lock holder removes, so what a holder verified is what it
- * removes.
+ * Ordering follows Lamport's bakery: a waiter announces it is *choosing*
+ * (`<lock>.c.<token>`), takes a number one larger than any ticket it can
+ * see, writes its ticket, and withdraws the marker; nobody concludes it
+ * holds the lock while a marker it does not own exists — so a waiter that
+ * took its number but has not yet written its ticket cannot be overtaken.
+ * Two tickets with the same number (chosen at the same moment) break the
+ * tie on the rest of the name, which every observer sorts the same way.
+ *
+ * A plain `lockPath` file left by a pre-#355 process is honoured while it is
+ * younger than `staleMs` and removed once it is not, so an upgrade under a
+ * live older process does not let two writers in.
  */
-export async function acquireLock(lockPath) {
+export async function acquireLock(lockPath, options = {}) {
+    const timeoutMs = options.timeoutMs ?? LOCK_TIMEOUT_MS;
+    const staleMs = options.staleMs ?? STALE_LOCK_MS;
     const startedAt = Date.now();
-    const token = `${process.pid}.${randomBytes(8).toString("hex")}`;
+    const dir = dirname(lockPath);
+    const base = basename(lockPath);
+    const token = randomBytes(8).toString("hex");
+    const choosingPath = join(dir, `${base}.c.${token}`);
     let brokeStale;
+    // The doorway: announce, take a number, write the ticket, withdraw. The
+    // number is one more than the largest ticket number on the floor, taken
+    // while the marker is up — so a waiter that arrives after us reads our
+    // ticket and takes a larger number, and two that choose at once get the
+    // same number and settle it on the token. A wall-clock number would let
+    // a later arrival in the same millisecond sort ahead of a holder.
+    await writeExclusive(choosingPath, `${process.pid}\n${new Date().toISOString()}\n${token}\n`);
+    const numbered = (await readdir(dir).catch(() => []))
+        .filter((name) => name.startsWith(`${base}.t.`))
+        .map((name) => Number.parseInt(name.slice(`${base}.t.`.length), 10))
+        .filter((n) => Number.isFinite(n));
+    const order = String(Math.max(0, ...numbered) + 1).padStart(15, "0");
+    const ticketPath = join(dir, `${base}.t.${order}-${process.pid}-${token}`);
+    const ticketName = basename(ticketPath);
+    try {
+        await writeExclusive(ticketPath, `${process.pid}\n${new Date().toISOString()}\n${token}\n`);
+    }
+    finally {
+        await rm(choosingPath, { force: true }).catch(() => undefined);
+    }
+    // The heartbeat: a ticket that keeps being touched is a live owner's.
+    const heartbeat = setInterval(() => {
+        const now = new Date();
+        void utimes(ticketPath, now, now).catch(() => undefined);
+    }, Math.max(50, Math.floor(staleMs / 4)));
+    heartbeat.unref?.();
+    const giveUp = async () => {
+        clearInterval(heartbeat);
+        await rm(ticketPath, { force: true }).catch(() => undefined);
+        throw new Error(`Timed out waiting for lock: ${lockPath}`);
+    };
     while (true) {
-        try {
-            const handle = await open(lockPath, "wx");
-            try {
-                await handle.writeFile(`${process.pid}\n${new Date().toISOString()}\n${token}\n`, "utf8");
+        const names = await readdir(dir).catch(() => []);
+        let blocked = false;
+        // A pre-#355 lock file: honour it while fresh, remove it when stale.
+        if (names.includes(base)) {
+            const legacyStat = await stat(lockPath).catch(() => null);
+            if (legacyStat && Date.now() - legacyStat.mtimeMs <= staleMs)
+                blocked = true;
+            else if (legacyStat) {
+                const holder = await describeLockHolder(lockPath);
+                if (await removeIfPresent(lockPath))
+                    brokeStale = holder;
             }
-            catch (error) {
-                // A non-EEXIST write failure must not leak the descriptor the
-                // open just created (#131); close best-effort, then rethrow.
-                await handle.close().catch(() => undefined);
-                throw error;
-            }
-            await handle.close();
-            return {
-                release: () => releaseOwnedLock(lockPath, token),
-                ...(brokeStale && { brokeStale }),
-            };
         }
-        catch (error) {
-            const nodeError = error;
-            if (nodeError.code !== "EEXIST")
-                throw error;
-            try {
-                const lockStat = await stat(lockPath);
-                if (Date.now() - lockStat.mtimeMs > STALE_LOCK_MS) {
-                    const broken = await breakStaleLock(lockPath);
-                    if (broken) {
-                        brokeStale = broken;
-                        continue;
-                    }
-                    // Another waiter is breaking it, or already has: fall
-                    // through to a wait and try the open again.
-                }
-            }
-            catch {
+        // Someone is between taking a number and writing their ticket: their
+        // number may be earlier than ours. Wait, unless they died in the door.
+        for (const name of names) {
+            if (!name.startsWith(`${base}.c.`) || name === basename(choosingPath))
+                continue;
+            const path = join(dir, name);
+            if (await ownerIsGone(path, staleMs)) {
+                await rm(path, { force: true }).catch(() => undefined);
                 continue;
             }
-            if (Date.now() - startedAt > LOCK_TIMEOUT_MS) {
-                throw new Error(`Timed out waiting for lock: ${lockPath}`);
+            blocked = true;
+        }
+        // Every ticket ahead of ours whose owner is alive blocks us; a dead or
+        // hung owner's ticket is removed by its own name.
+        if (!blocked) {
+            const ahead = names.filter((name) => name.startsWith(`${base}.t.`) && name < ticketName).sort();
+            for (const name of ahead) {
+                const path = join(dir, name);
+                if (await ownerIsGone(path, staleMs)) {
+                    // Recorded only by the waiter whose rm actually removed it; the
+                    // others saw the same dead ticket and removed nothing.
+                    const holder = await describeLockHolder(path);
+                    if (await removeIfPresent(path))
+                        brokeStale = holder;
+                    continue;
+                }
+                blocked = true;
+                break;
             }
-            await sleep(LOCK_RETRY_MS);
         }
+        if (!blocked) {
+            // Our own ticket must still be there: a waiter that judged us hung
+            // (the machine slept past staleMs) has already let someone in.
+            if (!(await pathExists(ticketPath)))
+                return giveUp();
+            return {
+                release: async () => {
+                    clearInterval(heartbeat);
+                    await rm(ticketPath, { force: true }).catch(() => undefined);
+                },
+                ...(brokeStale && { brokeStale }),
+            };
+        }
+        if (Date.now() - startedAt > timeoutMs)
+            return giveUp();
+        await sleep(LOCK_RETRY_MS);
     }
 }
 /**
- * Run `remove` while holding `<lockPath>.break`, the lock that serializes
- * removals of `lockPath`. Waits up to {@link LOCK_TIMEOUT_MS}; a removal lock
- * older than {@link BREAK_LOCK_STALE_MS} is a crashed remover's and is
- * cleared. Resolves to `undefined` when the removal lock could not be had
- * in time — the caller decides what that means.
+ * Remove `path`; true when this call removed it, false when it was already
+ * gone. `unlink`, not `rm`: `fs.promises.rm` reports success to every one
+ * of several concurrent callers, and the point here is to know which one
+ * actually took the file away.
  */
-async function withRemovalLock(lockPath, remove) {
-    const breakPath = `${lockPath}.break`;
-    const startedAt = Date.now();
-    while (true) {
-        try {
-            const handle = await open(breakPath, "wx");
-            await handle.close();
-            break;
-        }
-        catch (error) {
-            if (error.code !== "EEXIST")
-                throw error;
-            try {
-                const breakStat = await stat(breakPath);
-                if (Date.now() - breakStat.mtimeMs > BREAK_LOCK_STALE_MS) {
-                    await rm(breakPath, { force: true }).catch(() => undefined);
-                    continue;
-                }
-            }
-            catch {
-                continue;
-            }
-            if (Date.now() - startedAt > LOCK_TIMEOUT_MS)
-                return undefined;
-            await sleep(LOCK_RETRY_MS);
-        }
+async function removeIfPresent(path) {
+    try {
+        await unlink(path);
+        return true;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
     }
+}
+/** Create `path` exclusively with `content`; the descriptor is closed either way (#131). */
+async function writeExclusive(path, content) {
+    const handle = await open(path, "wx");
     try {
-        return await remove();
+        await handle.writeFile(content, "utf8");
     }
     finally {
-        await rm(breakPath, { force: true }).catch(() => undefined);
+        await handle.close().catch(() => undefined);
     }
 }
 /**
- * Remove a lock older than {@link STALE_LOCK_MS}, under the removal lock and
- * only if it is still that old there: the holder may have released and a
- * new one acquired between the caller's stat and this one. Resolves to the
- * broken lock's holder, or null when nothing was removed.
- */
-async function breakStaleLock(lockPath) {
-    const broken = await withRemovalLock(lockPath, async () => {
-        let lockStat;
-        try {
-            lockStat = await stat(lockPath);
-        }
-        catch {
-            return null;
-        }
-        if (Date.now() - lockStat.mtimeMs <= STALE_LOCK_MS)
-            return null;
-        const holder = await describeLockHolder(lockPath);
-        await rm(lockPath, { force: true }).catch(() => undefined);
-        return holder;
-    });
-    return broken ?? null;
-}
-/**
- * Remove the lock at `lockPath` only if it is still ours. A lock that vanished
- * (someone broke it as stale) or that now carries another holder's token is
- * left alone; one whose content cannot be read is left to go stale rather
- * than removed unverified.
+ * Whether the owner of a ticket or marker is dead (its pid no longer
+ * exists) or has stopped refreshing it for `staleMs`. A pid that exists but
+ * cannot be signalled (another user's process) counts as alive. A file that
+ * vanished while we looked is gone, and so is its owner's claim.
  */
-async function releaseOwnedLock(lockPath, token) {
-    const removeIfOwned = async () => {
-        let content;
-        try {
-            content = await readFile(lockPath, "utf8");
-        }
-        catch {
-            return true;
-        }
-        if (content.split(/\r?\n/)[2] !== token)
-            return true;
-        await rm(lockPath, { force: true }).catch(() => undefined);
+async function ownerIsGone(path, staleMs) {
+    let fileStat;
+    try {
+        fileStat = await stat(path);
+    }
+    catch {
         return true;
-    };
-    // Serialized with stale breaks so a break in progress cannot land on a
-    // lock this release has already replaced (#342). A removal lock that
-    // cannot be had in time falls back to the token-checked removal alone —
-    // the guarantee before #342, never less.
-    if ((await withRemovalLock(lockPath, removeIfOwned)) === undefined)
-        await removeIfOwned();
+    }
+    if (Date.now() - fileStat.mtimeMs > staleMs)
+        return true;
+    const { pid } = await describeLockHolder(path);
+    if (pid === null || pid === process.pid)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return false;
+    }
+    catch (error) {
+        return error.code === "ESRCH";
+    }
 }
 async function describeLockHolder(lockPath) {
     try {

package/dist/core/workspace.d.ts

@@ -99,6 +99,8 @@ export type RefreshScaffoldResult = {
     scaffoldVersionBefore?: string;
     /** The running framework version the scaffold now matches. */
     scaffoldVersionAfter: string;
+    /** False when THREAD_LOG already carried this version transition's line (#356). */
+    threadLogEntryAppended: boolean;
 };
 /**
  * The workspace-relative paths a scaffold refresh would write, sorted — the

package/dist/core/workspace.js

@@ -414,38 +414,62 @@ export async function listScaffoldRefreshFiles(sourceWorkspaceDir = packagedWork
  * version transition.
  */
 export async function refreshScaffold(cwd) {
-    const state = await getWorkspaceState(cwd);
-    if (!state)
+    const located = await getWorkspaceState(cwd);
+    if (!located)
         throw new Error("CodeCartographer workspace not found. Run /codecarto-init first.");
     if (!existsSync(packagedWorkspaceDir)) {
         throw new Error("Packaged .codecarto template is missing. Reinstall codecartographer-pi.");
     }
-    const scaffoldVersionBefore = state.scaffoldVersion;
-    const files = await listScaffoldRefreshFiles();
-    for (const relativePath of files) {
-        const target = join(state.workspaceDir, relativePath);
-        await mkdir(dirname(target), { recursive: true });
-        await copyFile(join(packagedWorkspaceDir, relativePath), target);
-    }
-    // Workspaces initialised from an npm install before the rules shipped as a
-    // template have no .gitignore at all; give them one without touching an
-    // existing (user-owned) file.
-    await ensureWorkspaceGitignore(state.workspaceDir);
-    const entry = `- ${new Date().toISOString().slice(0, 10)} — scaffold-refresh — Refreshed ${files.length} framework-owned file(s) from the packaged template (${scaffoldVersionBefore ?? "unversioned"} → ${PACKAGE_VERSION}); project state, user config, and session outputs untouched.`;
-    const threadLogPath = join(state.workspaceDir, "THREAD_LOG.md");
-    let currentLog = "";
+    // Under the status lock: a completion in flight re-reads the active
+    // pipeline inside it, and this rewrites every pipeline (#356). Everything
+    // is read before anything is written, so a template that cannot be read
+    // leaves the scaffold as it was; each file then lands atomically, and a
+    // failure between two files leaves a partial refresh that re-running
+    // completes — the copy is idempotent.
+    const lock = await acquireLock(join(located.workspaceDir, "workflow", "status.yaml.lock"));
     try {
-        currentLog = await readFile(threadLogPath, "utf8");
+        const state = (await getWorkspaceState(cwd)) ?? located;
+        const scaffoldVersionBefore = state.scaffoldVersion;
+        const files = await listScaffoldRefreshFiles();
+        const staged = new Map();
+        for (const relativePath of files) {
+            staged.set(relativePath, await readFile(join(packagedWorkspaceDir, relativePath), "utf8"));
+        }
+        for (const [relativePath, content] of staged) {
+            const target = join(state.workspaceDir, relativePath);
+            await mkdir(dirname(target), { recursive: true });
+            await atomicWriteFile(target, content);
+        }
+        // Workspaces initialised from an npm install before the rules shipped as a
+        // template have no .gitignore at all; give them one without touching an
+        // existing (user-owned) file.
+        await ensureWorkspaceGitignore(state.workspaceDir);
+        // One THREAD_LOG line per version change, like completion's and
+        // amendment's link-deduped entries: re-running the refresh at the same
+        // version regenerates the files and adds nothing to the index.
+        const transition = `(${scaffoldVersionBefore ?? "unversioned"} → ${PACKAGE_VERSION})`;
+        const entry = `- ${new Date().toISOString().slice(0, 10)} — scaffold-refresh — Refreshed ${files.length} framework-owned file(s) from the packaged template ${transition}; project state, user config, and session outputs untouched.`;
+        const threadLogPath = join(state.workspaceDir, "THREAD_LOG.md");
+        let currentLog = "";
+        try {
+            currentLog = await readFile(threadLogPath, "utf8");
+        }
+        catch {
+            // Created by the append when absent (pre-template scaffolds).
+        }
+        const alreadyLogged = currentLog.split(/\r?\n/).some((line) => line.includes("— scaffold-refresh —") && line.includes(transition));
+        if (!alreadyLogged)
+            await appendFile(threadLogPath, `${newlineIfUnterminated(currentLog)}${entry}\n`, "utf8");
+        return {
+            written: files,
+            ...(scaffoldVersionBefore !== undefined && { scaffoldVersionBefore }),
+            scaffoldVersionAfter: PACKAGE_VERSION,
+            threadLogEntryAppended: !alreadyLogged,
+        };
     }
-    catch {
-        // Created by the append when absent (pre-template scaffolds).
+    finally {
+        await lock.release();
     }
-    await appendFile(threadLogPath, `${newlineIfUnterminated(currentLog)}${entry}\n`, "utf8");
-    return {
-        written: files,
-        ...(scaffoldVersionBefore !== undefined && { scaffoldVersionBefore }),
-        scaffoldVersionAfter: PACKAGE_VERSION,
-    };
 }
 // Numeric x.y.z comparison; null when either side is not a plain dotted triple.
 /**

package/dist/core/yaml.js

@@ -455,15 +455,21 @@ export function parseSimpleYaml(raw) {
                 const key = rawItem.slice(0, separator).trim();
                 const rawValue = rawItem.slice(separator + 1).trim();
                 const item = {};
-                item[key] = rawValue === "" ? null : parseScalarWithContinuation(rawValue, indent);
+                // Through defineProperty for the same reason the mapping parser
+                // does it (#365): `item["__proto__"] = …` would set the item's
+                // prototype and drop the key from its own entries.
+                const assignItem = (k, v) => {
+                    Object.defineProperty(item, k, { value: v, writable: true, enumerable: true, configurable: true });
+                };
+                assignItem(key, rawValue === "" ? null : parseScalarWithContinuation(rawValue, indent));
                 skipBlank();
                 if (rawValue === "" && index < lines.length && countIndent(lines[index] ?? "") > indent + 1) {
-                    item[key] = parseBlock(countIndent(lines[index] ?? ""));
+                    assignItem(key, parseBlock(countIndent(lines[index] ?? "")));
                 }
                 if (index < lines.length && countIndent(lines[index] ?? "") > indent) {
                     const nested = parseMapping(itemIndent);
                     for (const [nestedKey, nestedValue] of Object.entries(nested))
-                        item[nestedKey] = nestedValue;
+                        assignItem(nestedKey, nestedValue);
                 }
                 result.push(item);
                 continue;

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

@@ -97,4 +97,11 @@ export type AutoDecision = {
 };
 export declare function decideAfterPhase(phaseStatus: SinglePhaseResult["status"], phaseError: string | undefined, validation: ValidationResult | null, strict: boolean): AutoDecision;
 export declare function runAuto(ctx: ExtensionContext, pi: ExtensionAPI, initialState: WorkspaceState, options: AutoRunOptions): Promise<AutoRunResult>;
+/**
+ * The one-line notification for an auto run's end. A run that stopped short
+ * carries its reason: the auto-summary message and the widget carry it too,
+ * but under `pi -p` neither is rendered, and "stopped: 0/1 phases" alone
+ * sent a reader back to the code to find out why (#347).
+ */
+export declare function describeAutoOutcome(result: AutoRunResult): string;
 export declare function buildAutoSummary(result: AutoRunResult, availableSkills?: string[]): string;

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

@@ -29,31 +29,49 @@ import { appendUsageRun, buildPhasePrompt, buildValidationSummary, completeValid
  * getPhaseActivity) and attached the agents widget if it wanted live progress.
  */
 export async function runSinglePhase(ctx, pi, state, phase, options) {
-    let prompt = await buildPhasePrompt(state, phase, false, {
-        auto: options.auto === true,
-        preflight: options.preflight,
-    });
-    if (options.llmSteerEnabled) {
-        notifyCtx(ctx, `Customizing ${phase.id} prompt via LLM rewriter…`, "info");
-        const rewrite = await rewritePhasePrompt({ ctx, state, originalPrompt: prompt, nextPhaseId: phase.id });
-        if (rewrite.used) {
-            prompt = rewrite.prompt;
-            notifyCtx(ctx, `LLM rewriter customized ${phase.id} seed prompt.`, "info");
-            pi.sendMessage({
-                customType: "codecarto-steering",
-                content: buildSteeringMessage({
-                    nextPhaseId: phase.id,
-                    prevPhaseId: rewrite.prevPhaseId,
-                    rewrittenPrompt: rewrite.prompt,
-                }),
-                display: true,
-            });
-        }
-        else {
-            notifyCtx(ctx, `LLM rewriter skipped (${rewrite.skipReason}); using stock prompt.`, "warning");
-        }
+    // Reserve the phase before the first await. The callers check
+    // isPhaseRunning and then call in, but the prompt build and the LLM-steer
+    // rewrite below are awaits, and a second call during them used to find
+    // the phase unregistered and spawn a second sub-agent for it (#359).
+    // The check and the reservation are synchronous, so they are one step.
+    if (isPhaseRunning(phase.id)) {
+        return { status: "error", activity: getPhaseActivity(phase.id), error: `Phase ${phase.id} is already running.` };
     }
     const activity = startPhase(phase.id);
+    let prompt;
+    try {
+        prompt = await buildPhasePrompt(state, phase, false, {
+            auto: options.auto === true,
+            preflight: options.preflight,
+        });
+        if (options.llmSteerEnabled) {
+            notifyCtx(ctx, `Customizing ${phase.id} prompt via LLM rewriter…`, "info");
+            const rewrite = await rewritePhasePrompt({ ctx, state, originalPrompt: prompt, nextPhaseId: phase.id });
+            if (rewrite.used) {
+                prompt = rewrite.prompt;
+                notifyCtx(ctx, `LLM rewriter customized ${phase.id} seed prompt.`, "info");
+                pi.sendMessage({
+                    customType: "codecarto-steering",
+                    content: buildSteeringMessage({
+                        nextPhaseId: phase.id,
+                        prevPhaseId: rewrite.prevPhaseId,
+                        rewrittenPrompt: rewrite.prompt,
+                    }),
+                    display: true,
+                });
+            }
+            else {
+                notifyCtx(ctx, `LLM rewriter skipped (${rewrite.skipReason}); using stock prompt.`, "warning");
+            }
+        }
+    }
+    catch (error) {
+        // A prelude that fails releases the reservation the way a failed
+        // phase does, so the next attempt is not told the phase is running.
+        finishPhase(phase.id, { status: "error", error: error instanceof Error ? error.message : String(error) });
+        setTimeout(() => clearPhase(phase.id, activity), 30_000).unref?.();
+        throw error;
+    }
     notifyCtx(ctx, `CodeCartographer phase: ${phase.id} (sub-agent running)`, "info");
     if (ctx.hasUI)
         getAgentsWidget().attach(ctx.ui);
@@ -305,6 +323,19 @@ export async function runAuto(ctx, pi, initialState, options) {
 // ----------------------------------------------------------------------------
 // buildAutoSummary — the codecarto-auto-summary message body
 // ----------------------------------------------------------------------------
+/**
+ * The one-line notification for an auto run's end. A run that stopped short
+ * carries its reason: the auto-summary message and the widget carry it too,
+ * but under `pi -p` neither is rendered, and "stopped: 0/1 phases" alone
+ * sent a reader back to the code to find out why (#347).
+ */
+export function describeAutoOutcome(result) {
+    const line = `Auto pipeline ${result.outcome}: ${result.phasesRun.length}/${result.totalPhases} phases.`;
+    if (result.outcome === "complete")
+        return line;
+    const reason = result.reason.trim();
+    return reason ? `${line.replace(/\.$/, "")} — ${reason}` : line;
+}
 export function buildAutoSummary(result, availableSkills = []) {
     const totalTokens = result.totalTokens.input + result.totalTokens.output;
     const wallTime = formatMillis(result.endedAt - result.startedAt);

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

@@ -24,11 +24,13 @@ export interface BroadsideFlags {
     lensModels?: Partial<Record<BroadsideLensId, string>>;
     /** For verify: how many findings to read (#143). */
     top?: number;
+    /** For collect: reset the settled post-passes and run them again (#338). */
+    regeneratePostPasses?: boolean;
     benchmarks: boolean;
     unknown: string[];
     /** Set on an invalid combination. The caller surfaces it as an error. */
     error?: string;
 }
 /** Every token the completer offers, in the order it offers them. */
-export declare const KNOWN_BROADSIDE_TOKENS: readonly ["submit", "collect", "status", "models", "verify", "architecture", "api", "security", "defect", "conventions", "porting", "--incremental", "--no-incremental", "--max-cost=", "--wait=", "--run=", "--model=", "--lens-model=", "--top=", "--no-synthesis", "--no-triage", "--no-retry-truncated", "--benchmarks"];
+export declare const KNOWN_BROADSIDE_TOKENS: readonly ["submit", "collect", "status", "models", "verify", "architecture", "api", "security", "defect", "conventions", "porting", "--incremental", "--no-incremental", "--max-cost=", "--wait=", "--run=", "--model=", "--lens-model=", "--top=", "--regenerate", "--no-synthesis", "--no-triage", "--no-retry-truncated", "--benchmarks"];
 export declare function parseBroadsideFlags(args: string): BroadsideFlags;

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

@@ -7,6 +7,7 @@
 //   /codecarto-broadside status
 //   /codecarto-broadside models --benchmarks
 //   /codecarto-broadside verify --top=10       → read the top findings against the source
+//   /codecarto-broadside collect --regenerate  → rebuild synthesis and triage from the verdicts
 //
 // Flags mirror the codecarto_broadside tool parameters, with the negative
 // forms spelled out because a slash command has no place to pass `false`:
@@ -18,6 +19,7 @@
 //   --model=ID (submit: the run's batch model, as listed by models; verify: the sync model to read with)
 //   --lens-model=LENS:ID (submit only, repeatable: one lens on its own model)
 //   --top=N (verify only: how many findings to read, most severe first)
+//   --regenerate (collect only: reset the settled post-passes and run them again, verdicts included)
 //
 // A model id itself contains a colon (`vendor/name:batch`), so --lens-model
 // splits on the first colon only: `security:deepseek/deepseek-v4-pro:batch`.
@@ -47,6 +49,7 @@ export const KNOWN_BROADSIDE_TOKENS = [
     "--model=",
     "--lens-model=",
     "--top=",
+    "--regenerate",
     "--no-synthesis",
     "--no-triage",
     "--no-retry-truncated",
@@ -107,6 +110,10 @@ export function parseBroadsideFlags(args) {
             result.retryTruncated = false;
             continue;
         }
+        if (token === "--regenerate") {
+            result.regeneratePostPasses = true;
+            continue;
+        }
         if (token === "--benchmarks") {
             result.benchmarks = true;
             continue;
@@ -188,6 +195,12 @@ export function parseBroadsideFlags(args) {
     if (result.top !== undefined && result.action !== "verify") {
         result.error ??= `--top is only meaningful for verify (got action "${result.action}").`;
     }
+    if (result.regeneratePostPasses && result.action !== "collect") {
+        result.error ??= `--regenerate is only meaningful for collect (got action "${result.action}").`;
+    }
+    if (result.regeneratePostPasses && result.includeSynthesis === false && result.includeTriage === false) {
+        result.error ??= "--regenerate with both --no-synthesis and --no-triage leaves nothing to regenerate.";
+    }
     if (result.action === "verify" && result.waitSeconds !== undefined) {
         result.error ??= "--wait is only meaningful for submit and collect; verify runs to completion.";
     }