codecartographer-pi 0.19.5 → 0.19.6

package/dist/core/usage.js

@@ -7,9 +7,10 @@
 // running, and phases run sequentially against this file, so a plain
 // read-modify-write is safe enough. If parallel-phase dispatch ever ships,
 // switch this to atomic-rename (see core/workspace.ts for the pattern).
-import { readFile, rename, writeFile } from "node:fs/promises";
+import { readFile } from "node:fs/promises";
 import { join } from "node:path";
-import { pathExists } from "./utils.js";
+import { acquireLock } from "./status.js";
+import { atomicWriteFile, pathExists } from "./utils.js";
 import { parseSimpleYaml, stringifySimpleYaml } from "./yaml.js";
 export const USAGE_RELATIVE_PATH = "workflow/.usage.local.yaml";
 const SCHEMA_VERSION = 1;
@@ -29,13 +30,40 @@ export async function loadUsage(workspaceDir) {
         return emptyUsage();
     }
 }
+/**
+ * Append one run. The read-modify-write runs under the file's lock and lands
+ * through an atomic write, so concurrent appends (a Pi runner and an MCP host
+ * on one workspace, two phases finishing together) each keep their record
+ * (#226, #238). A log that exists but does not parse is never rewritten: the
+ * lenient {@link loadUsage} is for display, and appending over its empty
+ * fallback destroyed every record the file still held.
+ */
 export async function appendUsageRun(workspaceDir, run) {
-    const current = await loadUsage(workspaceDir);
-    current.runs.push(run);
     const path = join(workspaceDir, USAGE_RELATIVE_PATH);
-    const tempPath = `${path}.${process.pid}.${Date.now()}.tmp`;
-    await writeFile(tempPath, `${stringifySimpleYaml(current)}\n`, "utf8");
-    await rename(tempPath, path);
+    const lock = await acquireLock(`${path}.lock`);
+    try {
+        const current = await loadUsageForAppend(path);
+        current.runs.push(run);
+        await atomicWriteFile(path, `${stringifySimpleYaml(current)}\n`);
+    }
+    finally {
+        await lock.release();
+    }
+}
+async function loadUsageForAppend(path) {
+    if (!(await pathExists(path)))
+        return emptyUsage();
+    const raw = await readFile(path, "utf8");
+    let parsed;
+    try {
+        parsed = parseSimpleYaml(raw);
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new Error(`Refusing to append to ${USAGE_RELATIVE_PATH}: the existing file does not parse (${reason}). ` +
+            "Its records are still in it — move the file aside to start a new log.");
+    }
+    return normalize(parsed);
 }
 export function computeTotals(file) {
     const totals = emptyTotals();

package/dist/core/utils.d.ts

@@ -1,15 +1,42 @@
 export declare function sleep(ms: number): Promise<void>;
 export declare function pathExists(path: string): Promise<boolean>;
+/**
+ * A temp-file suffix that is unique within and across processes: pid, a
+ * per-process sequence number, and random bytes. `<pid>.<Date.now()>` alone
+ * collides whenever two writers hit one target inside a millisecond, and the
+ * loser's rename then either fails with ENOENT or clobbers the winner (#226).
+ */
+export declare function uniqueTempSuffix(): string;
+/**
+ * Write `content` to `path` atomically: a uniquely named sibling temp file,
+ * then a rename over the target. Readers see the old bytes or the new bytes,
+ * never a truncated file. On failure the temp file is removed best-effort and
+ * the error propagates. Every framework file that is rewritten in place goes
+ * through this so no caller hand-rolls the temp name.
+ */
+export declare function atomicWriteFile(path: string, content: string): Promise<void>;
 export declare function canonicalPath(path: string): Promise<string>;
 export declare function normalizeForComparison(path: string): string;
 export declare function isWithinPath(path: string, root: string): boolean;
 /**
- * Symlink-aware version of isWithinPath. Resolves symlinks on both the path
- * and root before comparing, preventing bypass via symlinks inside the
- * allowed root that point outside it.
+ * Resolve a path the way the kernel will when something is written to it:
+ * every component that already exists is followed through symlinks
+ * (`realpath`), and the not-yet-existing tail is appended lexically. A `..`
+ * is applied to the *resolved* prefix, not the spelled one, because
+ * `link/..` means the link target's parent on disk. A relative `path` is
+ * taken against `base` without normalisation for the same reason.
  *
- * Falls back to lexical isWithinPath if realpath fails (e.g., path does not
- * exist yet), which is safe for write targets that haven't been created.
+ * `realpath` alone throws for a file that does not exist yet, and a lexical
+ * fallback let `.codecarto/link/new.md` through when `link` was a symlink to
+ * somewhere outside the workspace — the file landed outside (#223).
+ */
+export declare function resolveExistingPrefix(path: string, base?: string): Promise<string>;
+/**
+ * Symlink-aware version of isWithinPath for paths that may not exist yet:
+ * the existing prefix of `path` is resolved through symlinks
+ * ({@link resolveExistingPrefix}), the root through `realpath`, and the two
+ * are compared lexically. A symlinked ancestor that points outside the root
+ * fails whether or not the target file exists.
  */
 export declare function isWithinPathResolved(path: string, root: string): Promise<boolean>;
 export declare function isPlainObject(value: unknown): value is Record<string, unknown>;

package/dist/core/utils.js

@@ -1,10 +1,10 @@
 // General-purpose helpers used by yaml/status/prompts and by wrapper-specific
 // path-boundary enforcement (Pi tool interception, MCP cwd validation).
-import { access } from "node:fs/promises";
+import { randomBytes } from "node:crypto";
+import { access, realpath, rename, rm, writeFile } from "node:fs/promises";
 import { constants } from "node:fs";
 import { homedir } from "node:os";
-import { join, normalize, resolve } from "node:path";
-import { realpath } from "node:fs/promises";
+import { dirname, isAbsolute, join, normalize, parse, resolve, sep } from "node:path";
 export function sleep(ms) {
     return new Promise((resolvePromise) => setTimeout(resolvePromise, ms));
 }
@@ -17,6 +17,35 @@ export async function pathExists(path) {
         return false;
     }
 }
+let tempSequence = 0;
+/**
+ * A temp-file suffix that is unique within and across processes: pid, a
+ * per-process sequence number, and random bytes. `<pid>.<Date.now()>` alone
+ * collides whenever two writers hit one target inside a millisecond, and the
+ * loser's rename then either fails with ENOENT or clobbers the winner (#226).
+ */
+export function uniqueTempSuffix() {
+    tempSequence = (tempSequence + 1) % 0x7fffffff;
+    return `${process.pid}.${tempSequence}.${randomBytes(4).toString("hex")}`;
+}
+/**
+ * Write `content` to `path` atomically: a uniquely named sibling temp file,
+ * then a rename over the target. Readers see the old bytes or the new bytes,
+ * never a truncated file. On failure the temp file is removed best-effort and
+ * the error propagates. Every framework file that is rewritten in place goes
+ * through this so no caller hand-rolls the temp name.
+ */
+export async function atomicWriteFile(path, content) {
+    const tempPath = `${path}.${uniqueTempSuffix()}.tmp`;
+    try {
+        await writeFile(tempPath, content, "utf8");
+        await rename(tempPath, path);
+    }
+    catch (error) {
+        await rm(tempPath, { force: true }).catch(() => undefined);
+        throw error;
+    }
+}
 export async function canonicalPath(path) {
     try {
         return await realpath(path);
@@ -43,25 +72,58 @@ export function isWithinPath(path, root) {
     return normalizedPath.startsWith(prefix);
 }
 /**
- * Symlink-aware version of isWithinPath. Resolves symlinks on both the path
- * and root before comparing, preventing bypass via symlinks inside the
- * allowed root that point outside it.
+ * Resolve a path the way the kernel will when something is written to it:
+ * every component that already exists is followed through symlinks
+ * (`realpath`), and the not-yet-existing tail is appended lexically. A `..`
+ * is applied to the *resolved* prefix, not the spelled one, because
+ * `link/..` means the link target's parent on disk. A relative `path` is
+ * taken against `base` without normalisation for the same reason.
  *
- * Falls back to lexical isWithinPath if realpath fails (e.g., path does not
- * exist yet), which is safe for write targets that haven't been created.
+ * `realpath` alone throws for a file that does not exist yet, and a lexical
+ * fallback let `.codecarto/link/new.md` through when `link` was a symlink to
+ * somewhere outside the workspace — the file landed outside (#223).
  */
-export async function isWithinPathResolved(path, root) {
-    try {
-        const resolvedPath = await realpath(path);
-        const resolvedRoot = await realpath(root);
-        return isWithinPath(resolvedPath, resolvedRoot);
-    }
-    catch {
-        // If realpath fails (path doesn't exist yet, broken symlink, etc.),
-        // fall back to lexical check. For write targets this is safe because
-        // the parent directory should already be within the root.
-        return isWithinPath(path, root);
+export async function resolveExistingPrefix(path, base = process.cwd()) {
+    const raw = isAbsolute(path) ? path : `${base}${sep}${path}`;
+    const { root } = parse(raw);
+    const segments = raw
+        .slice(root.length)
+        .split(/[\\/]+/)
+        .filter((segment) => segment !== "" && segment !== ".");
+    let current = await canonicalPath(root || sep);
+    const tail = [];
+    for (const segment of segments) {
+        if (segment === "..") {
+            if (tail.length > 0)
+                tail.pop();
+            else
+                current = dirname(current);
+            continue;
+        }
+        if (tail.length > 0) {
+            // Once one component is missing, nothing below it can exist either.
+            tail.push(segment);
+            continue;
+        }
+        try {
+            current = await realpath(join(current, segment));
+        }
+        catch {
+            tail.push(segment);
+        }
     }
+    return tail.length === 0 ? current : join(current, ...tail);
+}
+/**
+ * Symlink-aware version of isWithinPath for paths that may not exist yet:
+ * the existing prefix of `path` is resolved through symlinks
+ * ({@link resolveExistingPrefix}), the root through `realpath`, and the two
+ * are compared lexically. A symlinked ancestor that points outside the root
+ * fails whether or not the target file exists.
+ */
+export async function isWithinPathResolved(path, root) {
+    const [resolvedPath, resolvedRoot] = await Promise.all([resolveExistingPrefix(path), canonicalPath(root)]);
+    return isWithinPath(resolvedPath, resolvedRoot);
 }
 export function isPlainObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);

package/dist/core/workspace.d.ts

@@ -19,9 +19,24 @@ export declare const ORCHESTRATOR_FILES: readonly [{
     readonly template: "thread-log.md";
 }];
 /**
- * Copy the packaged template into a target workspace, skipping this
- * repository's own project state. Directories are still created, so a fresh
- * workspace has an empty `closeouts/` rather than no `closeouts/`.
+ * Every workspace-relative path a packaged pipeline declares as a phase output,
+ * primary or secondary. Findings directories ship README and SKILL stubs
+ * beside the reports sessions write, so the reports have to be excluded by
+ * name rather than by directory, and the pipelines are the source of truth
+ * for those names. A pipeline file that fails to load contributes nothing.
+ */
+export declare function listDeclaredOutputs(sourceWorkspaceDir?: string): Promise<Set<string>>;
+/**
+ * Copy the packaged template into a target workspace, skipping everything a
+ * session wrote into it. Directories are still created, so a fresh workspace
+ * has an empty `closeouts/` rather than no `closeouts/`.
+ *
+ * This repository's `.codecarto/` is the template *and* CodeCartographer's own
+ * live workspace, so a checkout install's template can hold finished phase
+ * reports, handoffs, and a dashboard. Copying those seeded every new workspace
+ * with another project's findings, and validation then passed on them (#224).
+ * The exclusion is by declared output path ({@link listDeclaredOutputs}), so a
+ * new phase's report is covered the moment its pipeline names it.
  *
  * @param targetWorkspaceDir - Absolute path to the `.codecarto/` to create or merge into.
  * @param sourceWorkspaceDir - The template to copy from. Defaults to the packaged
@@ -29,6 +44,17 @@ export declare const ORCHESTRATOR_FILES: readonly [{
  *   without mutating the repository's own live workspace mid-suite.
  */
 export declare function copyPackagedWorkspace(targetWorkspaceDir: string, sourceWorkspaceDir?: string): Promise<void>;
+/**
+ * Give the workspace its ignore rules when it has none. npm never packs a file
+ * named `.gitignore`, so an npm-installed template carried no rules and the
+ * workspaces initialised from it committed the dashboard, the usage log with
+ * its absolute session paths, and the Broad-Side config with any API key in
+ * it (#229). The rules ship as `templates/gitignore` instead and are copied
+ * to `.gitignore` here; an existing `.gitignore` is the user's and is left
+ * alone.
+ * @returns whether a file was written.
+ */
+export declare function ensureWorkspaceGitignore(workspaceDir: string): Promise<boolean>;
 /**
  * Seed the orchestrator-maintained files from the workspace's templates
  * (issue #98): orchestration is on by default, so a fresh workspace starts
@@ -62,7 +88,7 @@ export type RefreshScaffoldResult = {
  * exact set {@link refreshScaffold} copies, computed without writing anything.
  * A wrapper that asks before refreshing shows this.
  */
-export declare function listScaffoldRefreshFiles(): Promise<string[]>;
+export declare function listScaffoldRefreshFiles(sourceWorkspaceDir?: string): Promise<string[]>;
 /**
  * Refresh a workspace's framework-owned files from the packaged template
  * (issue #102): both staleness notices instruct exactly this, and the only
@@ -85,15 +111,23 @@ export declare function refreshScaffold(cwd: string): Promise<RefreshScaffoldRes
  * fail: unversioned workspaces must keep working.
  */
 export declare function describeScaffoldStaleness(state: WorkspaceState): string | null;
-export declare function updateStatusAtomically(cwd: string, updater: (state: WorkspaceState) => Promise<{
-    state: WorkspaceState;
-    handoff?: PhaseHandoff;
-    threadLogEntry?: string;
-}> | {
+/** What an {@link updateStatusAtomically} updater returns. */
+export interface StatusUpdate {
     state: WorkspaceState;
     handoff?: PhaseHandoff;
     threadLogEntry?: string;
-}): Promise<WorkspaceState>;
+    /**
+     * Runs under the lock only after status.yaml has been renamed into place —
+     * the commit point. Closeouts, index lines, decision rows, and anything
+     * else that asserts "this phase is complete" belong here rather than in
+     * the updater, so a failed commit leaves none of them behind (#234). A
+     * step that fails here surfaces as an error, but the status change stands;
+     * steps must therefore be idempotent so re-running the operation
+     * regenerates what they write.
+     */
+    afterCommit?: (committed: WorkspaceState) => Promise<void> | void;
+}
+export declare function updateStatusAtomically(cwd: string, updater: (state: WorkspaceState) => Promise<StatusUpdate> | StatusUpdate): Promise<WorkspaceState>;
 /**
  * Switch the active pipeline in-place without deleting findings, handoffs,
  * usage data, closeouts, or checkpoints. Phases that exist in both the old

package/dist/core/workspace.js

@@ -3,11 +3,11 @@
 // + normalizes the per-project workspace state from disk, and provides the
 // atomic status-update primitive used by /codecarto-complete.
 import { existsSync, readFileSync } from "node:fs";
-import { appendFile, copyFile, cp, mkdir, readFile, readdir, rename, writeFile } from "node:fs/promises";
+import { appendFile, copyFile, cp, mkdir, readFile, readdir } from "node:fs/promises";
 import { basename, dirname, join, relative } from "node:path";
 import { fileURLToPath } from "node:url";
 import { acquireLock, applyHandoff, createEmptyStatus, normalizeStatus, parseHandoff } from "./status.js";
-import { compareDottedVersions, newlineIfUnterminated, pathExists } from "./utils.js";
+import { atomicWriteFile, compareDottedVersions, newlineIfUnterminated, pathExists } from "./utils.js";
 import { loadYamlFile, stringifySimpleYaml } from "./yaml.js";
 // Walk up from the current file to find the package root. Needed because the
 // source lives at <root>/core/workspace.ts (one level below the package root)
@@ -123,8 +123,25 @@ export const ORCHESTRATOR_FILES = [
  * The four top-level files are seeded fresh from templates instead
  * ({@link ORCHESTRATOR_FILES}); `closeouts/` is created empty.
  */
-const INIT_EXCLUDED_TOP_LEVEL = new Set(["BACKLOG.md", "THREAD_LOG.md", "CONVENTIONS.md", "DECISIONS.md"]);
-const INIT_EXCLUDED_DIR_CONTENTS = new Set(["closeouts"]);
+const INIT_EXCLUDED_TOP_LEVEL = new Set([
+    "BACKLOG.md",
+    "THREAD_LOG.md",
+    "CONVENTIONS.md",
+    "DECISIONS.md",
+    // Rendered from a workspace's own state; the narration cache holds an
+    // LLM summary of it.
+    "dashboard.html",
+    ".dashboard-narration.local.md",
+]);
+// Directories that exist in every workspace but whose contents are one
+// project's sessions: closeouts, and scratch (handoffs, checkpoints,
+// amendments) apart from its .gitkeep.
+const INIT_EXCLUDED_DIR_CONTENTS = new Set(["closeouts", "scratch"]);
+// Project state under workflow/: init writes a fresh status.yaml itself, and
+// the two dot-files hold one machine's usage log and session pointer.
+const INIT_EXCLUDED_WORKFLOW_FILES = new Set(["status.yaml", ".usage.local.yaml", ".orchestrator.local.yaml"]);
+// Where the workspace's ignore rules ship (see ensureWorkspaceGitignore).
+const GITIGNORE_TEMPLATE_RELATIVE_PATH = "templates/gitignore";
 // broadside/ is machine-local scan state (state.json, timestamped run dirs)
 // except for its two template files — the same carve-out .codecarto/.gitignore
 // makes for this repository itself. Without this, init from a local checkout
@@ -133,9 +150,83 @@ const INIT_EXCLUDED_DIR_CONTENTS = new Set(["closeouts"]);
 const BROADSIDE_DIR_NAME = "broadside";
 const INIT_BROADSIDE_TEMPLATE_FILES = new Set(["SKILL.md", "config.yaml"]);
 /**
- * Copy the packaged template into a target workspace, skipping this
- * repository's own project state. Directories are still created, so a fresh
- * workspace has an empty `closeouts/` rather than no `closeouts/`.
+ * Every workspace-relative path a packaged pipeline declares as a phase output,
+ * primary or secondary. Findings directories ship README and SKILL stubs
+ * beside the reports sessions write, so the reports have to be excluded by
+ * name rather than by directory, and the pipelines are the source of truth
+ * for those names. A pipeline file that fails to load contributes nothing.
+ */
+export async function listDeclaredOutputs(sourceWorkspaceDir = packagedWorkspaceDir) {
+    const outputs = new Set();
+    const workflowDir = join(sourceWorkspaceDir, "workflow");
+    let names;
+    try {
+        names = await readdir(workflowDir);
+    }
+    catch {
+        return outputs;
+    }
+    for (const name of names) {
+        if (!/^pipeline.*\.ya?ml$/.test(name))
+            continue;
+        let pipeline;
+        try {
+            pipeline = await loadYamlFile(join(workflowDir, name));
+        }
+        catch {
+            continue;
+        }
+        for (const phase of pipeline?.phases ?? []) {
+            if (typeof phase.primary_output === "string")
+                outputs.add(toPosixRelative(phase.primary_output));
+            for (const secondary of phase.secondary_outputs ?? []) {
+                const path = secondary.path;
+                if (typeof path === "string")
+                    outputs.add(toPosixRelative(path));
+            }
+        }
+    }
+    return outputs;
+}
+function toPosixRelative(path) {
+    return path.replace(/\\/g, "/").replace(/^\.\//, "");
+}
+/**
+ * Whether a template path (as segments) is framework-owned and travels into a
+ * new workspace. Everything a session produces stays behind: the declared
+ * phase outputs, handoffs and checkpoints, closeouts, the dashboard, usage,
+ * status, Broad-Side runs, and any lock or temp file a crashed process left.
+ * Directories pass so the workspace keeps its shape (an empty `closeouts/`,
+ * a `findings/<phase>/` for every phase).
+ */
+function isTemplatePath(segments, declaredOutputs) {
+    const posixPath = segments.join("/");
+    if (declaredOutputs.has(posixPath))
+        return false;
+    if (/\.(lock|tmp)$/.test(posixPath))
+        return false;
+    if (segments.length === 1)
+        return !INIT_EXCLUDED_TOP_LEVEL.has(segments[0]);
+    const [top, second] = segments;
+    if (top === BROADSIDE_DIR_NAME)
+        return segments.length === 2 && INIT_BROADSIDE_TEMPLATE_FILES.has(second);
+    if (top === "scratch")
+        return segments.length === 2 && second === ".gitkeep";
+    if (top === "workflow")
+        return !(segments.length === 2 && INIT_EXCLUDED_WORKFLOW_FILES.has(second));
+    return !INIT_EXCLUDED_DIR_CONTENTS.has(top);
+}
+/**
+ * Copy the packaged template into a target workspace, skipping everything a
+ * session wrote into it. Directories are still created, so a fresh workspace
+ * has an empty `closeouts/` rather than no `closeouts/`.
+ *
+ * This repository's `.codecarto/` is the template *and* CodeCartographer's own
+ * live workspace, so a checkout install's template can hold finished phase
+ * reports, handoffs, and a dashboard. Copying those seeded every new workspace
+ * with another project's findings, and validation then passed on them (#224).
+ * The exclusion is by declared output path ({@link listDeclaredOutputs}), so a
+ * new phase's report is covered the moment its pipeline names it.
  *
  * @param targetWorkspaceDir - Absolute path to the `.codecarto/` to create or merge into.
  * @param sourceWorkspaceDir - The template to copy from. Defaults to the packaged
@@ -143,20 +234,14 @@ const INIT_BROADSIDE_TEMPLATE_FILES = new Set(["SKILL.md", "config.yaml"]);
  *   without mutating the repository's own live workspace mid-suite.
  */
 export async function copyPackagedWorkspace(targetWorkspaceDir, sourceWorkspaceDir = packagedWorkspaceDir) {
+    const declaredOutputs = await listDeclaredOutputs(sourceWorkspaceDir);
     await cp(sourceWorkspaceDir, targetWorkspaceDir, {
         recursive: true,
         filter: (source) => {
             const relativePath = relative(sourceWorkspaceDir, source);
             if (!relativePath)
                 return true; // the workspace root itself
-            const segments = relativePath.split(/[\\/]/);
-            if (segments.length === 1)
-                return !INIT_EXCLUDED_TOP_LEVEL.has(segments[0]);
-            if (segments[0] === BROADSIDE_DIR_NAME) {
-                return segments.length === 2 && INIT_BROADSIDE_TEMPLATE_FILES.has(segments[1]);
-            }
-            // Keep the directory, drop what this repository wrote inside it.
-            return !INIT_EXCLUDED_DIR_CONTENTS.has(segments[0]);
+            return isTemplatePath(relativePath.split(/[\\/]/), declaredOutputs);
         },
     });
     // The published tarball carries no empty directories, so an excluded-contents
@@ -166,6 +251,27 @@ export async function copyPackagedWorkspace(targetWorkspaceDir, sourceWorkspaceD
     for (const name of INIT_EXCLUDED_DIR_CONTENTS) {
         await mkdir(join(targetWorkspaceDir, name), { recursive: true });
     }
+    await ensureWorkspaceGitignore(targetWorkspaceDir);
+}
+/**
+ * Give the workspace its ignore rules when it has none. npm never packs a file
+ * named `.gitignore`, so an npm-installed template carried no rules and the
+ * workspaces initialised from it committed the dashboard, the usage log with
+ * its absolute session paths, and the Broad-Side config with any API key in
+ * it (#229). The rules ship as `templates/gitignore` instead and are copied
+ * to `.gitignore` here; an existing `.gitignore` is the user's and is left
+ * alone.
+ * @returns whether a file was written.
+ */
+export async function ensureWorkspaceGitignore(workspaceDir) {
+    const target = join(workspaceDir, ".gitignore");
+    if (await pathExists(target))
+        return false;
+    const template = join(workspaceDir, GITIGNORE_TEMPLATE_RELATIVE_PATH);
+    if (!(await pathExists(template)))
+        return false;
+    await copyFile(template, target);
+    return true;
 }
 /**
  * Seed the orchestrator-maintained files from the workspace's templates
@@ -194,11 +300,20 @@ export async function seedOrchestratorFiles(workspaceDir) {
  * user-owned top-level files, and the directories sessions write into.
  * Everything else present in the packaged template is framework-owned.
  */
-const REFRESH_EXCLUDED_TOP_LEVEL = new Set(["BACKLOG.md", "THREAD_LOG.md", "CONVENTIONS.md", "DECISIONS.md"]);
+const REFRESH_EXCLUDED_TOP_LEVEL = new Set([
+    "BACKLOG.md",
+    "THREAD_LOG.md",
+    "CONVENTIONS.md",
+    "DECISIONS.md",
+    "dashboard.html",
+    ".dashboard-narration.local.md",
+    // The user's ignore rules; created from templates/gitignore when absent.
+    ".gitignore",
+]);
 // broadside/ holds machine-local scout state (batch ids, API key config,
 // generated results) — refresh must never overwrite it.
 const REFRESH_EXCLUDED_DIRS = new Set(["scratch", "inputs", "closeouts", "broadside"]);
-const REFRESH_EXCLUDED_WORKFLOW_FILES = new Set(["status.yaml", "config.yaml", ".usage.local.yaml"]);
+const REFRESH_EXCLUDED_WORKFLOW_FILES = new Set(["status.yaml", "config.yaml", ".usage.local.yaml", ".orchestrator.local.yaml"]);
 /**
  * What a scaffold refresh never touches, for a wrapper that asks before
  * refreshing to show. The same sets drive {@link refreshScaffold}, so the
@@ -209,7 +324,7 @@ export const SCAFFOLD_REFRESH_PROTECTED = Object.freeze({
     dirs: Object.freeze([...REFRESH_EXCLUDED_DIRS]),
     workflowFiles: Object.freeze([...REFRESH_EXCLUDED_WORKFLOW_FILES]),
 });
-async function listTemplateFiles(dir, relativeDir = "") {
+async function listTemplateFiles(dir, declaredOutputs, relativeDir = "") {
     const entries = await readdir(dir, { withFileTypes: true });
     const files = [];
     for (const entry of entries) {
@@ -217,13 +332,20 @@ async function listTemplateFiles(dir, relativeDir = "") {
         if (entry.isDirectory()) {
             if (!relativeDir && REFRESH_EXCLUDED_DIRS.has(entry.name))
                 continue;
-            files.push(...await listTemplateFiles(join(dir, entry.name), relativePath));
+            files.push(...await listTemplateFiles(join(dir, entry.name), declaredOutputs, relativePath));
             continue;
         }
         if (!relativeDir && REFRESH_EXCLUDED_TOP_LEVEL.has(entry.name))
             continue;
         if (relativeDir === "workflow" && REFRESH_EXCLUDED_WORKFLOW_FILES.has(entry.name))
             continue;
+        // A checkout install's template can hold finished reports (the repository
+        // analyses itself); refreshing those over a user's own would be worse
+        // than init copying them (#224).
+        if (declaredOutputs.has(relativePath))
+            continue;
+        if (/\.(lock|tmp)$/.test(entry.name))
+            continue;
         files.push(relativePath);
     }
     return files;
@@ -233,11 +355,12 @@ async function listTemplateFiles(dir, relativeDir = "") {
  * exact set {@link refreshScaffold} copies, computed without writing anything.
  * A wrapper that asks before refreshing shows this.
  */
-export async function listScaffoldRefreshFiles() {
-    if (!existsSync(packagedWorkspaceDir)) {
+export async function listScaffoldRefreshFiles(sourceWorkspaceDir = packagedWorkspaceDir) {
+    if (!existsSync(sourceWorkspaceDir)) {
         throw new Error("Packaged .codecarto template is missing. Reinstall codecartographer-pi.");
     }
-    return (await listTemplateFiles(packagedWorkspaceDir)).sort();
+    const declaredOutputs = await listDeclaredOutputs(sourceWorkspaceDir);
+    return (await listTemplateFiles(sourceWorkspaceDir, declaredOutputs)).sort();
 }
 /**
  * Refresh a workspace's framework-owned files from the packaged template
@@ -265,6 +388,10 @@ export async function refreshScaffold(cwd) {
         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 = "";
@@ -332,10 +459,17 @@ export async function updateStatusAtomically(cwd, updater) {
             applyHandoff(nextState.status, handoff);
         }
         assertCanonicalStatus(nextState.status);
-        const serialized = `${stringifySimpleYaml(nextState.status)}\n`;
-        const tempPath = `${statusPath}.${process.pid}.${Date.now()}.tmp`;
-        await writeFile(tempPath, serialized, "utf8");
-        await rename(tempPath, statusPath);
+        await atomicWriteFile(statusPath, `${stringifySimpleYaml(nextState.status)}\n`);
+        if (result.afterCommit) {
+            try {
+                await result.afterCommit(nextState);
+            }
+            catch (error) {
+                const reason = error instanceof Error ? error.message : String(error);
+                throw new Error(`status.yaml was updated, but a step that runs after the update failed: ${reason} ` +
+                    "The status change stands; re-run the same operation to regenerate what that step writes.", { cause: error });
+            }
+        }
         if (result.threadLogEntry) {
             const threadLogPath = join(workspaceDir, "THREAD_LOG.md");
             let currentLog = "";
@@ -400,10 +534,7 @@ export async function switchPipeline(cwd, newPipelinePath) {
         freshStatus.post_pipeline = currentState.status.post_pipeline;
         freshStatus.last_updated = new Date().toISOString();
         assertCanonicalStatus(freshStatus);
-        const serialized = `${stringifySimpleYaml(freshStatus)}\n`;
-        const tempPath = `${statusPath}.${process.pid}.${Date.now()}.tmp`;
-        await writeFile(tempPath, serialized, "utf8");
-        await rename(tempPath, statusPath);
+        await atomicWriteFile(statusPath, `${stringifySimpleYaml(freshStatus)}\n`);
         const state = await getWorkspaceState(cwd);
         if (!state)
             throw new Error("Failed to reload workspace state after pipeline switch.");

package/dist/extensions/codecarto/dashboard-narrator.js

@@ -10,10 +10,10 @@
 //
 // Same one-shot pattern as agent-rewriter.ts:runRewriterOnce — different
 // system prompt, different output target. Never throws.
-import { readFile, readdir, rename, writeFile } from "node:fs/promises";
+import { readFile, readdir } from "node:fs/promises";
 import { join } from "node:path";
 import { createAgentSession, DefaultResourceLoader, getAgentDir, SessionManager, SettingsManager, } from "@earendil-works/pi-coding-agent";
-import { computeTotals, NARRATION_CACHE_RELATIVE_PATH, loadUsage, pathExists, stringifySimpleYaml, } from "../../core/index.js";
+import { atomicWriteFile, computeTotals, NARRATION_CACHE_RELATIVE_PATH, loadUsage, pathExists, stringifySimpleYaml, } from "../../core/index.js";
 import { createChildModelRuntime } from "./child-model-runtime.js";
 // Per-closeout byte budget when stuffing the narrator's input. Three
 // closeouts × 4 KB each ≈ 12 KB of prompt context, which is well under any
@@ -133,10 +133,7 @@ async function writeNarrationCache(workspaceDir, content, phaseCount) {
     const generatedAt = new Date().toISOString();
     const frontmatter = stringifySimpleYaml({ generatedAt, phaseCountAtGeneration: phaseCount });
     const body = `---\n${frontmatter}\n---\n${content}\n`;
-    const path = join(workspaceDir, NARRATION_CACHE_RELATIVE_PATH);
-    const tempPath = `${path}.${process.pid}.${Date.now()}.tmp`;
-    await writeFile(tempPath, body, "utf8");
-    await rename(tempPath, path);
+    await atomicWriteFile(join(workspaceDir, NARRATION_CACHE_RELATIVE_PATH), body);
 }
 async function runNarratorOnce(ctx, prompt) {
     const cwd = ctx.cwd;