codecartographer-pi 0.24.0 → 0.25.0

package/dist/core/broadside.js

@@ -749,7 +749,19 @@ const LENSES = {
                 "Return a JSON object following the defect_scan_report schema. " +
                 "Cite file:line for every finding. List which patterns you checked. " +
                 "If the code looks clean for a pattern, say so rather than staying silent. " +
-                "Prefer precision over volume — 3 solid findings beat 15 vague ones.");
+                "Prefer precision over volume — 3 solid findings beat 15 vague ones.\n\n" +
+                // The verification pass (#143) confirmed 2 of the 12 top findings a
+                // scan produced with the paragraph above alone; the other ten were
+                // casts and assertions every caller satisfied, guards that lived one
+                // call away, or environments the project does not target. The rubric
+                // the verifier applies is asked of the scan itself, up front.
+                "A finding is a reachable failure: name in the description the concrete input, call site, or sequence " +
+                "that reaches it and what then goes wrong. A cast, assertion, `any`, or non-null `!` that every caller " +
+                "you can see satisfies, a hypothetical about a runtime or environment the project does not target, or a " +
+                "style or type-hygiene observation is not a defect — leave it out, or if it is worth a note, report it " +
+                "at severity low under the pattern name `type-hygiene` so it ranks apart from reachable failures. " +
+                "When the guard you looked for may live in another module, say which check you could not find " +
+                "rather than asserting it is absent; severity high or medium is for failures you traced to a trigger.");
         },
         userPrompt: (info, source, moduleName) => `Scan this ${info.language} module for mechanical defects.\n\n` +
             `Module: ${moduleName}\n\n` +
@@ -1254,25 +1266,51 @@ function collectFilesMatching(allFiles, lens, globs) {
     }
     return out;
 }
+/** Code in any language Broad-Side scans as, whatever this repo's is. */
+const SOURCE_EXTENSIONS = new Set(Object.values(SOURCE_SPECS).flatMap((spec) => spec.exts));
+function isSourceFile(relPath) {
+    const dot = relPath.lastIndexOf(".");
+    return dot > relPath.lastIndexOf("/") && SOURCE_EXTENSIONS.has(relPath.slice(dot).toLowerCase());
+}
+/** `a, b, c and 4 more` — a matched-file list short enough for a status line. */
+function listSome(paths, max = 3) {
+    if (paths.length <= max)
+        return paths.join(", ");
+    return `${paths.slice(0, max).join(", ")} and ${paths.length - max} more`;
+}
 /**
- * The files a lens will read: its targeted globs, or — when those match
- * nothing and the lens declares a fallback — the fallback globs, with a
- * sentence saying so (#319). The sentence travels to the estimate, the
- * batch entry, and the prompt, so a fallback scan is never a silent one.
+ * The files a lens will read: its targeted globs, or — when those match no
+ * source file and the lens declares a fallback — the fallback globs on top
+ * of whatever did match, with a sentence saying so (#319). The sentence
+ * travels to the estimate, the batch entry, and the prompt, so a fallback
+ * scan is never a silent one.
+ *
+ * "No source file" rather than "no file": a policy document or a config
+ * file under a targeted path satisfies the globs and leaves the lens with
+ * nothing to review, and the coverage note it writes back is the only sign.
  */
 export function selectLensFiles(allFiles, lens, info) {
     const globs = lens.globsFor(info).filter(Boolean);
     const targeted = collectFilesMatching(allFiles, lens, globs);
-    if (targeted.length > 0 || globs.length === 0 || !lens.fallbackGlobsFor)
+    if (globs.length === 0 || !lens.fallbackGlobsFor)
+        return { files: targeted };
+    if (targeted.some((f) => isSourceFile(f.relPath)))
         return { files: targeted };
     const fallbackGlobs = lens.fallbackGlobsFor(info).filter(Boolean);
-    const files = collectFilesMatching(allFiles, lens, fallbackGlobs);
-    if (files.length === 0)
-        return { files };
+    const matched = new Set(targeted.map((f) => f.relPath));
+    const sources = collectFilesMatching(allFiles, lens, fallbackGlobs).filter((f) => !matched.has(f.relPath));
+    if (sources.length === 0)
+        return { files: targeted };
+    const excluded = lens.skipTestFiles ? "test files excluded" : "";
+    const scanned = `scanned all ${info.language} sources (${fallbackGlobs.join(", ")})`;
     return {
-        files,
-        fallback: `no files matched ${globs.join(", ")}${lens.skipTestFiles ? " (test files excluded)" : ""}; ` +
-            `scanned all ${info.language} sources (${fallbackGlobs.join(", ")}) instead`,
+        // What did match rides first: the policy the model is about to check
+        // the code against, ahead of the code.
+        files: [...targeted, ...sources],
+        fallback: targeted.length === 0
+            ? `no files matched ${globs.join(", ")}${excluded ? ` (${excluded})` : ""}; ${scanned} instead`
+            : `no source files matched ${globs.join(", ")} (only ${listSome(targeted.map((f) => f.relPath))}` +
+                `${excluded ? `; ${excluded}` : ""}); ${scanned} as well`,
     };
 }
 function collectLensFiles(allFiles, lens, info) {
@@ -1396,8 +1434,8 @@ export function buildBatchRequest(lens, info, slice, index, sliceCount, model =
                     // so the model judges the trust boundary wherever it appears
                     // and does not report the missing server/ as a finding (#319).
                     (slice.fallback
-                        ? `NOTE: this repository has no files under the paths this lens usually reads (${slice.fallback}). ` +
-                            "What follows is every source file it has; locate the trust boundary and the request-handling code wherever they live.\n\n"
+                        ? `NOTE: this repository has no source files under the paths this lens usually reads (${slice.fallback}). ` +
+                            "What follows is every source file it has, after anything those paths did match; locate the trust boundary and the request-handling code wherever they live.\n\n"
                         : "") + lens.userPrompt(info, slice.content, slice.moduleName),
                 },
             ],
@@ -1680,6 +1718,39 @@ export async function claimRunSlot(broadsideDir, run, slot) {
     });
     return owned;
 }
+/**
+ * Put a run's settled post-passes back to `pending` on disk so the next
+ * claim re-runs them (#338). A pass another collect has in flight is left
+ * alone — its result is still coming. The replaced results' cost moves to
+ * `retiredCost`, so the run's total keeps counting money it spent. Returns
+ * the passes that were reset, in the order they will be re-run.
+ */
+export async function resetRunPostPasses(broadsideDir, run, wanted) {
+    const reset = [];
+    await updateBroadsideStateAtomically(broadsideDir, (state) => {
+        const index = state.runs.findIndex((candidate) => candidate.id === run.id);
+        const onDisk = index === -1 ? run : state.runs[index];
+        for (const kind of ["synthesis", "triage"]) {
+            if (!wanted[kind])
+                continue;
+            const theirs = onDisk[kind] ?? { status: "pending" };
+            if (theirs.status !== "completed" && theirs.status !== "failed") {
+                // pending: nothing to reset; submitted: in flight elsewhere.
+                run[kind] = theirs;
+                continue;
+            }
+            if (theirs.cost)
+                onDisk.retiredCost = (onDisk.retiredCost ?? 0) + theirs.cost;
+            onDisk[kind] = { status: "pending" };
+            run[kind] = onDisk[kind];
+            run.retiredCost = onDisk.retiredCost;
+            reset.push(kind);
+        }
+        if (index === -1)
+            state.runs.push(run);
+    });
+    return reset;
+}
 /** Read a `reasoning:` block from config.yaml, ignoring anything malformed. */
 function parseReasoningConfig(raw) {
     if (raw === false)
@@ -2684,8 +2755,86 @@ async function loadStoredRequests(runDir) {
         return {};
     }
 }
-// ---------- post-lens passes: synthesis + triage ----------
-function buildSynthesisRequest(findingsText, truncatedNote, model) {
+/**
+ * The verdicts a verify pass left in the run directory, or null when none
+ * has run (#338). A file that does not parse is treated as absent: the
+ * post-passes then run from the findings alone, which is what they did
+ * before verdicts existed, and `status` shows the pass carried no verdicts.
+ */
+export async function loadPostPassVerdicts(runDir) {
+    const path = join(runDir, "verified.json");
+    if (!(await pathExists(path)))
+        return null;
+    try {
+        const parsed = JSON.parse(await readFile(path, "utf8"));
+        const findings = Array.isArray(parsed.findings) ? parsed.findings : [];
+        const verdicts = findings
+            .filter((f) => typeof f.title === "string" && typeof f.verdict === "string")
+            .map((f) => ({
+            lensId: String(f.lensId ?? ""),
+            customId: String(f.customId ?? ""),
+            severity: String(f.severity ?? ""),
+            title: String(f.title),
+            location: String(f.location ?? ""),
+            verdict: String(f.verdict),
+            confidence: String(f.confidence ?? ""),
+            evidence: Array.isArray(f.evidence)
+                ? f.evidence.map((e) => ({ file: String(e.file ?? ""), lines: String(e.lines ?? ""), note: String(e.note ?? "") }))
+                : [],
+            reasoning: String(f.reasoning ?? ""),
+        }));
+        return verdicts.length > 0 ? verdicts : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The verdicts as a section of the post-pass user message: one line per
+ * finding with the verdict, the evidence the verifier cited, and its
+ * reasoning, so the pass can rank on them rather than on the batch model's
+ * own severities (#338).
+ */
+export function renderPostPassVerdicts(verdicts) {
+    const counts = new Map();
+    for (const v of verdicts)
+        counts.set(v.verdict, (counts.get(v.verdict) ?? 0) + 1);
+    const tally = [...counts.entries()].map(([verdict, n]) => `${n} ${verdict}`).join(", ");
+    const lines = [
+        "",
+        `## Verification verdicts (${verdicts.length} finding(s) read against the source by a read-only-tools pass: ${tally})`,
+        "",
+        "A verdict outranks the batch severity of the finding it names. `confirmed` means the verifier found a reachable " +
+            "failure and named its trigger; `not-a-defect` means the claim is literally true of the code but nothing reaches the " +
+            "failure it describes; `discarded` means the claim is wrong about the code; `unclear` means the code alone could not " +
+            "settle it; `error` means the pass could not read it — treat that finding as unverified. Findings not listed here " +
+            "were not read and stay unverified leads.",
+        "",
+    ];
+    for (const v of verdicts) {
+        const evidence = v.evidence.map((e) => `${e.file}${e.lines ? `:${e.lines}` : ""}${e.note ? ` (${e.note})` : ""}`).join("; ");
+        lines.push(`- [${v.verdict}${v.confidence ? `, ${v.confidence} confidence` : ""}] ${v.lensId}/${v.customId} — [${v.severity}] ${v.title}` +
+            `${v.location ? ` @ ${v.location}` : ""}` +
+            `${v.reasoning ? `\n  Reasoning: ${v.reasoning.replace(/\s+/g, " ").trim()}` : ""}` +
+            `${evidence ? `\n  Evidence: ${evidence}` : ""}`);
+    }
+    lines.push("");
+    return lines.join("\n");
+}
+const SYNTHESIS_VERDICT_INSTRUCTIONS = " A verification pass has read some of the findings against the source; its verdicts follow the reports. " +
+    "Lead top_findings with the confirmed findings and begin each such summary with 'verified: confirmed — ' and the " +
+    "trigger the verifier named; keep an unclear one with 'verified: unclear — '. A discarded or not-a-defect finding " +
+    "does not appear in top_findings and is not counted in severity_summary. Say in the executive summary how many " +
+    "findings were verified and how the verdicts split; findings the pass did not read remain unverified, and the " +
+    "summary says so of them, not of the confirmed ones.";
+const TRIAGE_VERDICT_INSTRUCTIONS = " A verification pass has read some of the findings against the source; its verdicts follow the findings. " +
+    "A confirmed finding ranks above every unverified finding of the same or lower severity: put the confirmed " +
+    "findings at the top of the queue and begin each one's rationale with 'verified: confirmed — ' and the trigger " +
+    "the verifier named. Keep an unclear finding in the queue with 'verified: unclear — ' in its rationale. Do not " +
+    "queue a discarded or not-a-defect finding: list each in omitted, beginning with 'verified: discarded — ' or " +
+    "'verified: not a defect — ' and the reason the pass gave. Findings the pass did not read stay unverified leads, " +
+    "and the summary says how many verdicts the queue was built from.";
+function buildSynthesisRequest(findingsText, truncatedNote, model, verdicts = null) {
     return {
         custom_id: "synthesis",
         body: {
@@ -2701,13 +2850,15 @@ function buildSynthesisRequest(findingsText, truncatedNote, model) {
                         "synthesis_report schema. Prioritize the most actionable findings. " +
                         "Be honest about gaps — if a lens found nothing, say 'no issues found' rather than " +
                         "inventing problems. These are scouting signals from a batch model, not verified " +
-                        "claims; note that in the summary.",
+                        "claims; note that in the summary." +
+                        (verdicts ? SYNTHESIS_VERDICT_INSTRUCTIONS : ""),
                 },
                 {
                     role: "user",
                     content: "Synthesize these analysis reports into a single summary.\n\n" +
                         findingsText +
                         truncatedNote +
+                        (verdicts ? renderPostPassVerdicts(verdicts) : "") +
                         "\nReturn the synthesis_report JSON schema.",
                 },
             ],
@@ -2716,7 +2867,7 @@ function buildSynthesisRequest(findingsText, truncatedNote, model) {
         },
     };
 }
-function buildTriageRequest(findingsText, truncatedNote, model) {
+function buildTriageRequest(findingsText, truncatedNote, model, verdicts = null) {
     return {
         custom_id: "triage",
         body: {
@@ -2733,13 +2884,15 @@ function buildTriageRequest(findingsText, truncatedNote, model) {
                         "too vague to act on and record each drop in omitted with the reason. These findings " +
                         "are UNVERIFIED scouting signals from a cheap batch model: the queue is a starting " +
                         "point for re-verification, not a commitment — say so in the summary, and never " +
-                        "inflate a severity you cannot see evidence for.",
+                        "inflate a severity you cannot see evidence for." +
+                        (verdicts ? TRIAGE_VERDICT_INSTRUCTIONS : ""),
                 },
                 {
                     role: "user",
                     content: "Triage these scouting findings into a prioritized work order.\n\n" +
                         findingsText +
                         truncatedNote +
+                        (verdicts ? renderPostPassVerdicts(verdicts) : "") +
                         "\nReturn the triage_report JSON schema.",
                 },
             ],
@@ -2982,7 +3135,10 @@ export async function runBroadsideCollect(cwd, apiKey, opts = {}) {
                 continue;
             const group = byModel.get(model);
             const usage = (batch.usage ?? {});
-            totalCost += typeof usage.cost === "number" ? usage.cost : 0;
+            // Kept on the entry, not just added to this collect's running total:
+            // a later collect on the run used to report a total without it.
+            if (typeof usage.cost === "number")
+                run.retry = { ...run.retry, cost: (run.retry?.cost ?? 0) + usage.cost };
             const results = Array.isArray(batch.results) ? batch.results : [];
             for (const result of results) {
                 const stored = group.slices.get(String(result.custom_id ?? ""));
@@ -3020,6 +3176,23 @@ export async function runBroadsideCollect(cwd, apiKey, opts = {}) {
     let topTriageItems = [];
     const wantSynthesis = opts.includeSynthesis !== false;
     const wantTriage = opts.includeTriage !== false;
+    // A regenerate resets the wanted, settled passes to pending on disk first —
+    // the merging persist keeps whatever is further along on disk, so an
+    // in-memory reset alone would be undone by the next persist (#338).
+    let regenerated = [];
+    if (opts.regeneratePostPasses) {
+        if (!wantSynthesis && !wantTriage) {
+            throw new Error("Nothing to regenerate: both post-passes are disabled for this collect.");
+        }
+        const lensesSettled = run.lenses.every((lensId) => {
+            const entry = run.batches[lensId];
+            return entry && BROADSIDE_TERMINAL_ENTRY_STATUSES.includes(entry.status);
+        });
+        if (!lensesSettled) {
+            throw new Error(`Cannot regenerate the post-passes of run ${run.id}: its lens batches are still running — collect them first.`);
+        }
+        regenerated = await resetRunPostPasses(broadsideDir, run, { synthesis: wantSynthesis, triage: wantTriage });
+    }
     // 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
@@ -3042,6 +3215,9 @@ export async function runBroadsideCollect(cwd, apiKey, opts = {}) {
             const findingsText = allLensResults
                 .map((r) => `## ${r.lensId} — ${r.customId}\n\n${r.content}\n`)
                 .join("\n");
+            // A verify pass that ran before this point leaves its verdicts in the
+            // run directory; the post-passes rank on them when present (#338).
+            const verdicts = await loadPostPassVerdicts(runDir);
             const truncatedNote = truncatedCount > 0
                 ? `\n\nNOTE: ${truncatedCount} lens result(s) were truncated at the output token limit and are ` +
                     "not included above. Any gap they would have covered is unrepresented — do not treat " +
@@ -3063,12 +3239,17 @@ export async function runBroadsideCollect(cwd, apiKey, opts = {}) {
                 if (!(await claimRunSlot(broadsideDir, run, kind)))
                     continue;
                 owned.add(kind);
+                const entry = kind === "synthesis" ? run.synthesis : run.triage;
+                if (verdicts)
+                    entry.verdicts = verdicts.length;
+                else
+                    delete entry.verdicts;
                 passes.push({
                     kind,
                     request: kind === "synthesis"
-                        ? buildSynthesisRequest(findingsText, truncatedNote, run.model)
-                        : buildTriageRequest(findingsText, truncatedNote, run.model),
-                    entry: kind === "synthesis" ? run.synthesis : run.triage,
+                        ? buildSynthesisRequest(findingsText, truncatedNote, run.model, verdicts)
+                        : buildTriageRequest(findingsText, truncatedNote, run.model, verdicts),
+                    entry,
                 });
             }
             const submitted = new Map();
@@ -3126,7 +3307,6 @@ export async function runBroadsideCollect(cwd, apiKey, opts = {}) {
                     const cost = typeof usage.cost === "number" ? usage.cost : undefined;
                     pass.entry.status = "completed";
                     pass.entry.cost = cost;
-                    totalCost += cost ?? 0;
                     const results = Array.isArray(batch.results) ? batch.results : [];
                     const content = results.length > 0 ? extractContent(results[0]) : null;
                     if (content !== null) {
@@ -3162,6 +3342,11 @@ export async function runBroadsideCollect(cwd, apiKey, opts = {}) {
         return entry && BROADSIDE_TERMINAL_ENTRY_STATUSES.includes(entry.status);
     });
     run.status = terminal ? (resultCount > 0 ? "completed" : "failed") : "partial";
+    // The run's total is the sum of what its entries record, not of what this
+    // collect happened to poll: a repeat collect used to report — and persist
+    // — a total without the post-passes and the retry an earlier collect had
+    // settled, so the recorded cost of a run went down each time it was read.
+    totalCost += (run.retry?.cost ?? 0) + (run.synthesis.cost ?? 0) + (run.triage.cost ?? 0) + (run.retiredCost ?? 0);
     run.totalCost = totalCost;
     await persist();
     await writeFile(join(runDir, "run-meta.json"), `${JSON.stringify({
@@ -3201,6 +3386,7 @@ export async function runBroadsideCollect(cwd, apiKey, opts = {}) {
         triage: run.triage,
         topFindings,
         topTriageItems,
+        ...(regenerated.length > 0 && { regenerated }),
     };
 }
 export async function runBroadsideStatus(cwd) {
@@ -3483,10 +3669,17 @@ export function collectResultText(result) {
             lines.push(`  ${kind}: failed${entry.error ? ` — ${explainBatchError(entry.error)}` : ""}`);
         }
     };
+    // Whether a pass was built from a verify pass's verdicts is part of what
+    // it is: a work order that ranked on batch severities alone is the one
+    // that put two dismissed casts above the confirmed finding (#338).
+    const builtFrom = (entry) => entry.verdicts ? ` (built from ${entry.verdicts} verdict${entry.verdicts === 1 ? "" : "s"})` : " (no verdicts)";
+    if (result.regenerated && result.regenerated.length > 0) {
+        lines.push(`  regenerated: ${result.regenerated.join(", ")}`);
+    }
     if (result.synthesis.status === "completed") {
-        lines.push(`  synthesis: completed, $${(result.synthesis.cost ?? 0).toFixed(6)}`);
+        lines.push(`  synthesis: completed, $${(result.synthesis.cost ?? 0).toFixed(6)}${builtFrom(result.synthesis)}`);
         if (result.topFindings.length > 0) {
-            lines.push("", "Top findings (unverified leads):");
+            lines.push("", result.synthesis.verdicts ? "Top findings (verdicts applied; unread ones are unverified leads):" : "Top findings (unverified leads):");
             for (const f of result.topFindings.slice(0, 10)) {
                 lines.push(`  [${f.severity}] ${f.title}`);
             }
@@ -3496,9 +3689,11 @@ export function collectResultText(result) {
         passInFlight("synthesis", result.synthesis);
     }
     if (result.triage.status === "completed") {
-        lines.push(`  triage: completed, $${(result.triage.cost ?? 0).toFixed(6)}`);
+        lines.push(`  triage: completed, $${(result.triage.cost ?? 0).toFixed(6)}${builtFrom(result.triage)}`);
         if (result.topTriageItems.length > 0) {
-            lines.push("", "Triage — prioritized work order (re-verify before acting):");
+            lines.push("", result.triage.verdicts
+                ? "Triage — prioritized work order (confirmed findings first; re-verify the unread ones before acting):"
+                : "Triage — prioritized work order (re-verify before acting):");
             for (const item of result.topTriageItems.slice(0, 10)) {
                 lines.push(`  ${item.priority} [${item.severity}/${item.module}] ${item.title}` +
                     (item.effort_estimate ? ` (${item.effort_estimate})` : ""));
@@ -3508,6 +3703,10 @@ export function collectResultText(result) {
     else {
         passInFlight("triage", result.triage);
     }
+    if (result.status === "completed" && !result.synthesis.verdicts && !result.triage.verdicts
+        && (result.synthesis.status === "completed" || result.triage.status === "completed")) {
+        lines.push("", "Run verify, then collect --regenerate, to rebuild the report and the work order from verdicts.");
+    }
     lines.push("", "Disclaimer: Broad-Side findings are unverified scouting signals from a batch model, not validated claims.");
     return lines.join("\n");
 }
@@ -3547,8 +3746,9 @@ export function statusText(state) {
             lines.push(`  ${lensId}: ${entry.status}${entry.batchId ? ` (${entry.batchId})` : ""}${entry.cost !== undefined ? `, $${entry.cost.toFixed(6)}` : ""}` +
                 (entry.status === "skipped" && entry.reason ? ` — ${entry.reason}` : entry.fallback ? ` — ${entry.fallback}` : ""));
         }
-        lines.push(`  synthesis: ${run.synthesis.status}`);
-        lines.push(`  triage: ${run.triage?.status ?? "pending"}`);
+        const builtFrom = (entry) => entry?.status === "completed" ? (entry.verdicts ? ` (built from ${entry.verdicts} verdict${entry.verdicts === 1 ? "" : "s"})` : " (no verdicts)") : "";
+        lines.push(`  synthesis: ${run.synthesis.status}${builtFrom(run.synthesis)}`);
+        lines.push(`  triage: ${run.triage?.status ?? "pending"}${builtFrom(run.triage)}`);
         if (run.verify) {
             lines.push(`  verify: ${run.verify.status} — ${run.verify.confirmed} confirmed of ${run.verify.verified} read on ${run.verify.model}, $${run.verify.cost.toFixed(4)}`);
         }

package/dist/core/status.d.ts

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

package/dist/core/status.js

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

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

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

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

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

package/dist/extensions/codecarto/auto-runner.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;