codecartographer-pi 0.24.0 → 0.24.1

package/.codecarto/broadside/SKILL.md

@@ -50,7 +50,11 @@ not replace any phase; it tells phases where to look.
    - `architecture-*.json` → the architecture phase's seed of prior knowledge
    - `api-*.json` → endpoints and data types (contracts/protocols phases)
    - `security-*.json` → auth, trust boundaries (defect-scan-semantic pass 5)
-   - `defect-*.json` → mechanical defect leads (defect-scan-mechanical)
+   - `defect-*.json` → mechanical defect leads (defect-scan-mechanical). The
+     scan is asked to name the input, call site, or sequence that reaches
+     each failure, and to file a cast, assertion, or style observation that
+     every caller satisfies at severity low under the pattern `type-hygiene`
+     — read those as notes, not defects.
    - `conventions-*.json` → naming/idiom candidates for CONVENTIONS.md
    - `porting-*.json` → platform coupling (porting phase)
 4. `run-meta.json` records scope: which lenses ran, at what cost, with what
@@ -108,14 +112,16 @@ every source file; the **security** and **API** lenses target where the
 trust boundary usually lives — `server/**`, `**/auth*`, `**/middleware/**`,
 `SECURITY.md` (security) and `server/**`, `api/**`, `src/server/**`,
 `src/api/**`, `**/*routes*`, `**/*router*`, `**/*handler*`, `**/*endpoint*`
-(API). A repository whose server is `src/server.js` matches none of those, so
-when the targeted patterns find nothing those two lenses **fall back to every
-source file** — priced as such, chunked at the lens's slice size rather than
-truncated, and said so on the lens line of the estimate, the submit report,
-`status`, and the prompt the model receives. A lens whose targeted patterns
-and fallback both find nothing (only test files, say) is skipped with a line
-naming both. `max_cost` is the guard against a fallback scan on a large
-repository being more than you meant to spend.
+(API). A repository whose server is `src/server.js` matches none of those,
+and one whose only match is `SECURITY.md` has given the lens a policy to read
+and no code to check it against; so when the targeted patterns find **no
+source file** those two lenses **fall back to every source file**, on top of
+whatever did match — priced as such, chunked at the lens's slice size rather
+than truncated, and said so on the lens line of the estimate, the submit
+report, `status`, and the prompt the model receives. A lens whose targeted
+patterns and fallback both find nothing (only test files, say) is skipped
+with a line naming both. `max_cost` is the guard against a fallback scan on
+a large repository being more than you meant to spend.
 
 Collect runs two cross-lens post-passes by default: **synthesis** (the
 executive report) and **triage** (the prioritized work order). Pass

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.24.0
+scaffold_version: 0.24.1

package/README.md

@@ -383,7 +383,7 @@ Each workflow tool accepts an absolute `cwd` for the target repository. `codecar
 
 ## Broad-Side (batch reconnaissance)
 
-Broad-Side is the cheap sweep you run *before* the expensive interactive run. It fires six analysis lenses — architecture, API surface, security, mechanical defect scan, convention extraction, porting — at a repository as single-turn prompts over the [OpenRouter Batch API](https://openrouter.ai/docs), then cross-references them into one executive report (`synthesis.md`) and a prioritized P0–P3 work order (`triage.md`). The security and API lenses target the paths where a trust boundary usually lives (`server/`, `auth*`, `middleware/`, routers and handlers) and fall back to every source file when a repository has none of them — priced as such, and said so on the estimate — so a service whose server is `src/server.js` still gets its security review.
+Broad-Side is the cheap sweep you run *before* the expensive interactive run. It fires six analysis lenses — architecture, API surface, security, mechanical defect scan, convention extraction, porting — at a repository as single-turn prompts over the [OpenRouter Batch API](https://openrouter.ai/docs), then cross-references them into one executive report (`synthesis.md`) and a prioritized P0–P3 work order (`triage.md`). The security and API lenses target the paths where a trust boundary usually lives (`server/`, `auth*`, `middleware/`, routers and handlers) and fall back to every source file when a repository has no code under them — priced as such, and said so on the estimate — so a service whose server is `src/server.js`, or one whose only match is its `SECURITY.md`, still gets its security review.
 
 **Broad-Side findings are unverified scouting leads, not evidence.** Each lens is one shot: no cross-file traversal, no runtime verification, no builds, no tests. Every finding is a `file:line` pointer that the interactive pipeline — or you — must confirm before it is a fact. That division of labor is the point: a sub-dollar unattended sweep that tells the expensive run where to look. Nothing downstream may cite a Broad-Side report as a source.
 

package/dist/core/amendment.d.ts

@@ -39,8 +39,11 @@ export declare function listAmendmentNames(workspaceDir: string): Promise<string
 export declare function loadAmendmentFile(name: string, workspaceDir: string): Promise<Amendment>;
 /**
  * Apply one amendment to canonical state under the completion lock. Refuses
- * while the pipeline is incomplete — mid-pipeline resolutions belong in the
- * phase handoff, and allowing both channels at once would race them.
- * Idempotent: ids that no longer match anything are reported, not fatal.
+ * while the pipeline is incomplete, judged on the state read under the lock:
+ * the check used to run on a read taken before the lock, so a status change
+ * that landed in between — a pipeline switch, a re-init, a rolled-back
+ * completion — was amended over as if the pipeline were still complete
+ * (Broad-Side verify, 2026-09-13 run). Idempotent: ids that no longer match
+ * anything are reported, not fatal.
  */
 export declare function applyAmendment(cwd: string, name: string): Promise<AmendmentResult>;

package/dist/core/amendment.js

@@ -91,17 +91,12 @@ function renderAmendmentCloseout(amendment, applied, timestamp) {
     return lines.join("\n");
 }
 /**
- * Apply one amendment to canonical state under the completion lock. Refuses
- * while the pipeline is incomplete — mid-pipeline resolutions belong in the
- * phase handoff, and allowing both channels at once would race them.
- * Idempotent: ids that no longer match anything are reported, not fatal.
+ * The refusal an amendment gets while the pipeline is incomplete —
+ * mid-pipeline resolutions belong in the phase handoff, and allowing both
+ * channels at once would race them.
  */
-export async function applyAmendment(cwd, name) {
-    const initialState = await getWorkspaceState(cwd);
-    if (!initialState)
-        throw new Error("CodeCartographer workspace not found. Run /codecarto-init first.");
-    const amendment = await loadAmendmentFile(name, initialState.workspaceDir);
-    const outcome = resolvePipelineOutcome(initialState);
+function refuseUnlessComplete(state) {
+    const outcome = resolvePipelineOutcome(state);
     if (outcome.kind === "eligible") {
         throw new Error(`Cannot amend: the pipeline is not complete (next phase: ${outcome.phase.id}). `
             + `Resolve open questions and routed items through that phase's handoff (open_question_closures / carry_forward_closures) instead.`);
@@ -111,10 +106,26 @@ export async function applyAmendment(cwd, name) {
         // finish is not there yet (#228).
         throw new Error(`Cannot amend: the pipeline is not complete. ${describeStuckPipeline(outcome.blocked)}`);
     }
+}
+/**
+ * Apply one amendment to canonical state under the completion lock. Refuses
+ * while the pipeline is incomplete, judged on the state read under the lock:
+ * the check used to run on a read taken before the lock, so a status change
+ * that landed in between — a pipeline switch, a re-init, a rolled-back
+ * completion — was amended over as if the pipeline were still complete
+ * (Broad-Side verify, 2026-09-13 run). Idempotent: ids that no longer match
+ * anything are reported, not fatal.
+ */
+export async function applyAmendment(cwd, name) {
+    const initialState = await getWorkspaceState(cwd);
+    if (!initialState)
+        throw new Error("CodeCartographer workspace not found. Run /codecarto-init first.");
+    const amendment = await loadAmendmentFile(name, initialState.workspaceDir);
     const timestamp = new Date().toISOString();
     const applied = { openQuestionsClosed: [], postPipelineClosed: [], unknownIds: [] };
     let closeoutNotice = "";
     const updatedState = await updateStatusAtomically(cwd, async (lockedState) => {
+        refuseUnlessComplete(lockedState);
         const nextStatus = normalizeStatus(lockedState.status, lockedState.pipeline, lockedState.status.pipeline, lockedState.cwd);
         for (const closureId of amendment.open_question_closures) {
             if (!closureId)

package/dist/core/broadside.d.ts

@@ -518,12 +518,16 @@ type LensDefinition = {
     skipTestFiles?: boolean;
     globsFor: (info: RepoInfo) => string[];
     /**
-     * Where to look when `globsFor` matches nothing (#319). The security and
-     * api lenses target server/, auth, and middleware paths because that is
-     * where the trust boundary usually lives; a service whose server is
-     * `src/server.js` matched none of them and got no security review at all.
-     * The fallback is the language's whole source set — priced as such, and
-     * said so in the estimate, the run record, and the prompt.
+     * Where to look when `globsFor` matches no source file (#319). The
+     * security and api lenses target server/, auth, and middleware paths
+     * because that is where the trust boundary usually lives; a service whose
+     * server is `src/server.js` matched none of them and got no security
+     * review at all. A match that is only documents is the same starvation:
+     * `SECURITY.md` satisfied the security lens on CodeCartographer itself,
+     * which then reviewed a policy and reported zero findings. The fallback
+     * is the language's whole source set, added to whatever did match —
+     * priced as such, and said so in the estimate, the run record, and the
+     * prompt.
      */
     fallbackGlobsFor?: (info: RepoInfo) => string[];
     systemPrompt: (info: RepoInfo) => string;
@@ -554,10 +558,15 @@ type CollectedFile = {
     moduleName: string;
 };
 /**
- * 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 declare function selectLensFiles(allFiles: string[], lens: LensDefinition, info: RepoInfo): {
     files: CollectedFile[];

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),
                 },
             ],

package/dist/core/status.d.ts

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

package/dist/core/status.js

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

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

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

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

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

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

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

package/dist/extensions/codecarto/index.js

@@ -11,7 +11,7 @@ import { buildPiGuideMessage } from "./guide-framing.js";
 import { isCtxLive, notifyCtx } from "./notify.js";
 import { phaseCompactionExtension } from "./phase-compaction.js";
 import { applyAmendment, buildPhasePrompt, buildSkillPrompt, buildValidationSummary, backupWorkspaceState, canonicalPath, copyPackagedWorkspace, computePerPhaseTotals, computeTotals, ConfidentialityMismatchError, createEmptyStatus, DEFAULT_PIPELINE_PATH, describeScaffoldStaleness, deriveSlug, discoverLibrary, describeDanglingCarryForward, describeMissingCompletedOutputs, describeStuckPipeline, expandTilde, getPipelineLabel, getWorkspaceState, isWithinPath, resolveExistingPrefix, BROADSIDE_LENS_IDS, BROADSIDE_SKILL_NAME, BroadsideConfigError, defaultBroadsideConfig, BroadsideCancelledError, broadsideDirFor, collectResultText, estimateSubmitText, getLens, listAmendmentNames, listBatchModels, listGuideTopics, listScaffoldRefreshFiles, listMissingCompletedOutputs, listSkillNames, resolvePipelineOutcome, resolveSkillName, loadAmendmentFile, loadBroadsideConfig, modelsText, runBroadsideCollect, runBroadsideStatus, runBroadsideSubmit, runBroadsideVerify, verifyResultText, statusText, describeConfigProblems, describeIncrementalFallback, loadCodecartoConfig, loadUsage, loadYamlFile, normalizeForComparison, packagedWorkspaceDir, pathExists, PACKAGE_VERSION, readBroadsideSkill, readGuide, refreshScaffold, PhasePreflightError, PIPELINE_ALIASES, publishEntry, resolvePhase, resolvePipelineChoice, resolvePublishSourceRepo, SourceRepoMismatchError, runPhasePreflight, SCAFFOLD_REFRESH_PROTECTED, seedOrchestratorFiles, stringifySimpleYaml, switchPipeline, validatePhaseOutput, writeLibraryConfig, writeDashboard, } from "../../core/index.js";
-import { initLibrary } from "../../core/library.js";
+import { initLibrary, isValidSlug } from "../../core/library.js";
 import { resolveUserConfigPath } from "../../core/orchestrator-config.js";
 const STATUS_WIDGET_ID = "codecarto-widget";
 // Broad-Side gets its own widget id: a scout run is legal on a repository with
@@ -1354,12 +1354,41 @@ export default function codeCartographerExtension(pi) {
     pi.registerCommand("codecarto-library-init", {
         description: "Initialize a CodeCartographer library and configure it: /codecarto-library-init <path> [--namespace <name>]",
         handler: async (args, ctx) => {
-            const parts = args.trim().split(/\s+/);
-            const pathArg = parts[0];
+            const usage = "Usage: /codecarto-library-init <path> [--namespace <name>]";
+            const parts = args.trim() === "" ? [] : args.trim().split(/\s+/);
+            // `--namespace` with nothing after it used to read as "no namespace"
+            // and initialize an unnamespaced library without a word (Broad-Side
+            // verify, 2026-09-13 run): the flag is either complete or refused.
             const namespaceIdx = parts.indexOf("--namespace");
-            const namespace = namespaceIdx >= 0 ? parts[namespaceIdx + 1] : null;
+            let namespace = null;
+            if (namespaceIdx >= 0) {
+                const value = parts[namespaceIdx + 1];
+                if (value === undefined || value.startsWith("--")) {
+                    notifyCtx(ctx, `--namespace needs a name. ${usage}`, "warning");
+                    return;
+                }
+                // The rule publish applies to it later, applied before it is
+                // written into the config: lowercase ASCII, starts with a
+                // letter, at most 64 characters.
+                if (!isValidSlug(value)) {
+                    notifyCtx(ctx, `Invalid namespace "${value}" (lowercase ASCII, starts with a letter, max 64 chars). ${usage}`, "warning");
+                    return;
+                }
+                namespace = value;
+                parts.splice(namespaceIdx, 2);
+            }
+            const stray = parts.find((part) => part.startsWith("--"));
+            if (stray) {
+                notifyCtx(ctx, `Unknown flag ${stray}. ${usage}`, "warning");
+                return;
+            }
+            const [pathArg, ...extra] = parts;
             if (!pathArg) {
-                notifyCtx(ctx, "Usage: /codecarto-library-init <path> [--namespace <name>]", "warning");
+                notifyCtx(ctx, usage, "warning");
+                return;
+            }
+            if (extra.length > 0) {
+                notifyCtx(ctx, `One path, please — got ${parts.length}. ${usage}`, "warning");
                 return;
             }
             // The same expansion the config loader applies, so `~user/x` and a

package/dist/mcp-server/server.js

@@ -808,6 +808,11 @@ export async function handleLibraryInit(args) {
     }
     const libraryPath = args.library_path;
     const namespaced = !!args.namespace;
+    // The rule codecarto_publish applies to the namespace later, applied
+    // before it is written into the config.
+    if (namespaced && !isValidSlug(args.namespace)) {
+        throw new McpError(ErrorCode.InvalidParams, `Invalid namespace "${args.namespace}" (lowercase ASCII, starts with a letter, max 64 chars).`);
+    }
     const result = await initLibrary(libraryPath, {
         name: args.name,
         namespaced,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codecartographer-pi",
-  "version": "0.24.0",
+  "version": "0.24.1",
   "mcpName": "io.github.HuginnIndustries/codecartographer",
   "description": "Turn an unfamiliar codebase into a validated reimplementation spec, then synthesize confirmed specs and a product vision into a traceable plan.",
   "type": "module",