codecartographer-pi 0.25.0 → 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.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);

package/dist/extensions/codecarto/index.js

@@ -1507,10 +1507,15 @@ export default function codeCartographerExtension(pi) {
                     notifyCtx(ctx, `LLM narration skipped (${result.skipReason}); rendering deterministic dashboard.`, "warning");
                 }
             }
-            await writeDashboard(ctx.cwd, PACKAGE_VERSION);
-            lastFeedbackLines = ["Dashboard regenerated: .codecarto/dashboard.html"];
+            // writeDashboard is best-effort and says so with its result: a
+            // swallowed write failure used to be reported as success (#369).
+            const written = await writeDashboard(ctx.cwd, PACKAGE_VERSION);
+            const line = written
+                ? "Dashboard regenerated: .codecarto/dashboard.html"
+                : "Dashboard not regenerated: the write to .codecarto/dashboard.html failed (permissions or disk?); the previous file, if any, stands.";
+            lastFeedbackLines = [line];
             setUiState(ctx, state, lastFeedbackLines);
-            notifyCtx(ctx, "Dashboard regenerated: .codecarto/dashboard.html", "info");
+            notifyCtx(ctx, line, written ? "info" : "error");
         },
     });
     pi.registerCommand("codecarto-refresh-scaffold", {
@@ -1540,7 +1545,7 @@ export default function codeCartographerExtension(pi) {
                 lastFeedbackLines = [
                     `Refreshed ${result.written.length} framework-owned file(s) from the packaged template (${transition}).`,
                     "Project state, user config, findings outputs, scratch, closeouts, and orchestrator files were not touched.",
-                    "THREAD_LOG.md: one scaffold-refresh entry appended.",
+                    result.threadLogEntryAppended ? "THREAD_LOG.md: one scaffold-refresh entry appended." : "THREAD_LOG.md: already carries this refresh; nothing appended.",
                 ];
                 // Re-read state so the widget's staleness line clears with the marker.
                 await refreshWorkspaceUi(ctx, lastFeedbackLines);

package/dist/extensions/codecarto/phase-compaction.js

@@ -66,8 +66,12 @@ export function phaseCompactionExtension(pi) {
         if (event.toolName === "edit" || event.toolName === "write") {
             const inputPath = typeof event.input.path === "string" ? event.input.path : "";
             const strippedPath = inputPath.startsWith("@") ? inputPath.slice(1) : inputPath;
-            // Same containment as the parent extension's hook (#223): follow the
-            // existing prefix through symlinks, then append the unborn tail.
+            // The same symlink-aware containment as the parent extension's hook
+            // (#223) — follow the existing prefix through symlinks, then append
+            // the unborn tail — over a narrower root on purpose: a phase writes
+            // findings, handoffs, and checkpoints under .codecarto/ and never
+            // publishes, so the configured library the orchestrator's hook admits
+            // is not admitted here (#364).
             const targetPath = await resolveExistingPrefix(strippedPath, ctx.cwd);
             const allowedRoot = await canonicalPath(join(ctx.cwd, ".codecarto"));
             if (!isWithinPath(targetPath, allowedRoot)) {