codecartographer-pi 0.19.5 → 0.19.6

package/.codecarto/templates/gitignore

@@ -0,0 +1,55 @@
+# Analysis outputs (generated per-project, can be large)
+findings/architecture/architecture-map.md
+findings/defect-scan/defect-report.md
+findings/defect-scan-mechanical/mechanical-defects.md
+findings/defect-scan-semantic/semantic-defects.md
+findings/contracts/behavioral-contracts.md
+findings/protocols/protocols-and-state.md
+findings/porting/reverse-engineering-bundle.md
+findings/reimplementation-spec/reimplementation-spec.md
+findings/broadside-scout/scout-brief.md
+
+# Secondary / optional outputs
+findings/public-surfaces/public-surfaces.md
+findings/runtime-lifecycle/runtime-lifecycle.md
+findings/state-and-storage/state-and-storage.md
+findings/build-and-deploy/build-and-deploy.md
+findings/config-model/config-model.md
+
+# Scratch working notes
+scratch/*
+!scratch/.gitkeep
+
+# Broad-Side machine-local state and generated results (batch ids, run
+# directories, costs). The SKILL.md guidance and the config template are
+# tracked; the API key inside config.yaml is your own risk to commit.
+broadside/*
+!broadside/SKILL.md
+!broadside/config.yaml
+
+# Orchestrator session pointer (machine-local, written by /codecarto-init
+# when run from the Pi extension; the MCP path doesn't write it). Contains
+# absolute paths into the user's Pi session storage, so it must never be
+# committed.
+workflow/.orchestrator.local.yaml
+
+# Phase-run usage log (machine-local, written by /codecarto-next on each
+# phase completion; consumed by /codecarto-usage). Holds timestamps, token
+# counts, and absolute Pi session-file paths; useless to share, includes
+# local cwd metadata, must never be committed.
+workflow/.usage.local.yaml
+
+# Generated HTML dashboard (machine-local; regenerated by /codecarto-init,
+# /codecarto-next, /codecarto-complete, and /codecarto-dashboard). Surfaces
+# data from workflow/.usage.local.yaml which holds absolute Pi session
+# paths; committing the dashboard would transitively leak those.
+dashboard.html
+
+# LLM-narrated executive summary cache (produced by
+# /codecarto-dashboard --narrate; preserved across deterministic re-renders
+# until the next --narrate).
+.dashboard-narration.local.md
+
+# OS artifacts
+.DS_Store
+Thumbs.db

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.19.5
+scaffold_version: 0.19.6

package/dist/core/amendment.js

@@ -134,29 +134,34 @@ export async function applyAmendment(cwd, name) {
         // carry (issue #114); rebuild them so status never shows stale numbers.
         nextStatus.next_actions = buildTerminalNextActions(nextStatus);
         nextStatus.last_updated = timestamp;
-        // Amendment closeout + THREAD_LOG entry, same idempotence rule as
-        // completion: the closeout link appears in THREAD_LOG at most once.
-        const closeoutFile = `${dateOnly(timestamp)}-amendment-${amendment.slug}.md`;
-        const closeoutsDir = join(lockedState.workspaceDir, "closeouts");
-        await mkdir(closeoutsDir, { recursive: true });
-        const body = amendment.closeout_content.trim() || renderAmendmentCloseout(amendment, applied, timestamp);
-        await writeFile(join(closeoutsDir, closeoutFile), `${body}\n`, "utf8");
-        const summary = amendment.closeout_summary.trim()
-            || `Amendment applied: ${applied.openQuestionsClosed.length} open question(s) and ${applied.postPipelineClosed.length} post-pipeline item(s) closed.`;
-        const entry = `- ${dateOnly(timestamp)} — amendment:${amendment.slug} — ${summary} — [closeout](closeouts/${closeoutFile})`;
-        const threadLogPath = join(lockedState.workspaceDir, "THREAD_LOG.md");
-        let current = "";
-        try {
-            current = await readFile(threadLogPath, "utf8");
-        }
-        catch {
-            // Created below when absent.
-        }
-        if (!current.split(/\r?\n/).some((line) => line.includes(`[closeout](closeouts/${closeoutFile})`))) {
-            await appendFile(threadLogPath, `${newlineIfUnterminated(current)}${entry}\n`, "utf8");
-        }
-        closeoutNotice = `Closeout: .codecarto/closeouts/${closeoutFile}`;
-        return { state: { ...lockedState, status: nextStatus } };
+        return {
+            state: { ...lockedState, status: nextStatus },
+            // Amendment closeout + THREAD_LOG entry, written after the status
+            // commit (#234) under the same idempotence rule as completion: the
+            // closeout link appears in THREAD_LOG at most once.
+            afterCommit: async () => {
+                const closeoutFile = `${dateOnly(timestamp)}-amendment-${amendment.slug}.md`;
+                const closeoutsDir = join(lockedState.workspaceDir, "closeouts");
+                await mkdir(closeoutsDir, { recursive: true });
+                const body = amendment.closeout_content.trim() || renderAmendmentCloseout(amendment, applied, timestamp);
+                await writeFile(join(closeoutsDir, closeoutFile), `${body}\n`, "utf8");
+                const summary = amendment.closeout_summary.trim()
+                    || `Amendment applied: ${applied.openQuestionsClosed.length} open question(s) and ${applied.postPipelineClosed.length} post-pipeline item(s) closed.`;
+                const entry = `- ${dateOnly(timestamp)} — amendment:${amendment.slug} — ${summary} — [closeout](closeouts/${closeoutFile})`;
+                const threadLogPath = join(lockedState.workspaceDir, "THREAD_LOG.md");
+                let current = "";
+                try {
+                    current = await readFile(threadLogPath, "utf8");
+                }
+                catch {
+                    // Created below when absent.
+                }
+                if (!current.split(/\r?\n/).some((line) => line.includes(`[closeout](closeouts/${closeoutFile})`))) {
+                    await appendFile(threadLogPath, `${newlineIfUnterminated(current)}${entry}\n`, "utf8");
+                }
+                closeoutNotice = `Closeout: .codecarto/closeouts/${closeoutFile}`;
+            },
+        };
     });
     return { updatedState, closeoutNotice, applied };
 }

package/dist/core/broadside.js

@@ -31,11 +31,11 @@
 // executable surfaces (Pi and MCP), not the pure template. What the template does
 // carry is the reading guide for its output — `.codecarto/broadside/SKILL.md`,
 // served by codecarto_skill under the name `broadside` (see readBroadsideSkill).
-import { mkdir, readFile, readdir, rename, stat, writeFile } from "node:fs/promises";
+import { mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { join, relative } from "node:path";
-import { pathExists, sleep } from "./utils.js";
+import { atomicWriteFile, pathExists, sleep } from "./utils.js";
 import { acquireLock } from "./status.js";
 import { loadYamlFile } from "./yaml.js";
 import { packagedWorkspaceDir } from "./workspace.js";
@@ -1279,9 +1279,7 @@ export async function saveBroadsideState(broadsideDir, state) {
 }
 /** Serialize through a temp file so a crash mid-write cannot truncate state.json. */
 async function writeBroadsideStateFile(statePath, state) {
-    const tempPath = `${statePath}.${process.pid}.${Date.now()}.tmp`;
-    await writeFile(tempPath, `${JSON.stringify(state, null, "\t")}\n`, "utf8");
-    await rename(tempPath, statePath);
+    await atomicWriteFile(statePath, `${JSON.stringify(state, null, "\t")}\n`);
 }
 /**
  * Read-modify-write `state.json` under a lock.

package/dist/core/completion.js

@@ -426,10 +426,20 @@ export async function completeValidatedPhase(cwd, validation, sourceLabel) {
         nextStatus.next_actions = nextEligible
             ? [`Begin ${nextEligible.id} phase by producing ${nextEligible.primary_output ?? `findings/${nextEligible.id}/`}`]
             : buildTerminalNextActions(nextStatus);
-        const artifacts = await writeCompletionArtifacts(lockedState.workspaceDir, validation.phaseId, lockedValidation, completionTimestamp, handoff);
-        closeoutPath = artifacts.closeoutPath;
-        orchestratorCheckpoint = buildOrchestratorCheckpoint(artifacts.decisionsAppended, artifacts.totalPendingProposals, nextStatus);
-        return { state: { ...nextWorkspace, status: nextStatus } };
+        return {
+            state: { ...nextWorkspace, status: nextStatus },
+            // The closeout, THREAD_LOG line, decision rows, and staged proposals
+            // all assert that the phase is complete, so they are written only
+            // after status.yaml has landed (#234). Each writer is idempotent
+            // (canonical closeout name, link-deduped index line, text-deduped
+            // rows), so re-running completion regenerates whatever a failure
+            // here left out.
+            afterCommit: async () => {
+                const artifacts = await writeCompletionArtifacts(lockedState.workspaceDir, validation.phaseId, lockedValidation, completionTimestamp, handoff);
+                closeoutPath = artifacts.closeoutPath;
+                orchestratorCheckpoint = buildOrchestratorCheckpoint(artifacts.decisionsAppended, artifacts.totalPendingProposals, nextStatus);
+            },
+        };
     });
     return {
         updatedState,

package/dist/core/library.js

@@ -32,10 +32,13 @@ import { createHash } from "node:crypto";
 import { spawn } from "node:child_process";
 import { mkdir, readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
 import { basename, join, resolve } from "node:path";
-import { canonicalPath, isPlainObject, normalizeForComparison, pathExists } from "./utils.js";
+import { acquireLock } from "./status.js";
+import { atomicWriteFile, canonicalPath, isPlainObject, normalizeForComparison, pathExists, uniqueTempSuffix } from "./utils.js";
 import { parseSimpleYaml, stringifySimpleYaml } from "./yaml.js";
 // ─── Constants ──────────────────────────────────────────────────────────────
 export const LIBRARY_MARKER_FILE = ".codecarto-library";
+/** Transient lock taken for the duration of one publish (see publishEntry). */
+const PUBLISH_LOCK_FILE = ".publish.lock";
 export const LIBRARY_INDEX_FILE = "index.yaml";
 export const LIBRARY_INDEX_MD_FILE = "INDEX.md";
 export const ENTRIES_DIR = "entries";
@@ -73,9 +76,7 @@ export async function writeMarker(libraryRoot, marker) {
     await mkdir(libraryRoot, { recursive: true });
     const markerPath = join(libraryRoot, LIBRARY_MARKER_FILE);
     const normalized = normalizeMarker(marker);
-    const tempPath = `${markerPath}.${process.pid}.${Date.now()}.tmp`;
-    await writeFile(tempPath, `${JSON.stringify(normalized, null, 2)}\n`, "utf8");
-    await rename(tempPath, markerPath);
+    await atomicWriteFile(markerPath, `${JSON.stringify(normalized, null, 2)}\n`);
 }
 function normalizeMarker(raw) {
     const r = raw;
@@ -285,9 +286,7 @@ async function listVersionDirs(entryDir) {
 }
 async function writeLatestPointer(entryDir, versionDirName) {
     const latestPath = join(entryDir, LATEST_POINTER_FILE);
-    const tempPath = `${latestPath}.${process.pid}.${Date.now()}.tmp`;
-    await writeFile(tempPath, `${versionDirName}\n`, "utf8");
-    await rename(tempPath, latestPath);
+    await atomicWriteFile(latestPath, `${versionDirName}\n`);
 }
 async function readLatestPointer(entryDir) {
     const latestPath = join(entryDir, LATEST_POINTER_FILE);
@@ -379,108 +378,120 @@ export async function publishEntry(libraryRoot, spec, input, opts = {}) {
     }
     const namespace = input.namespace;
     const entryDir = entryRoot(libraryRoot, namespace, input.slug);
-    const preview = await previewPublishVersion(libraryRoot, spec, { slug: input.slug, namespace }, opts);
-    const latestVersion = preview.latestVersion;
-    // Collision guard. Slugs derive from the trailing path segment of the source
-    // repo, so two unrelated projects (acme/whisper and openai/whisper) collapse
-    // onto one slug. Without this check the second publish would append its spec
-    // to the first project's version history, and the index would then report the
-    // newcomer's source_repo as though it owned every prior version. Checked
-    // before the idempotence branch below, because a metadata-only update would
-    // overwrite the wrong entry just as silently.
-    if (latestVersion > 0 && !opts.allowSourceRepoChange) {
-        const recorded = await readRecordedSourceRepo(libraryRoot, namespace, input.slug, latestVersion);
-        if (recorded !== null && !sameSourceRepo(recorded, input.source_repo)) {
+    // One publisher at a time. Version assignment reads the entry directory
+    // and then creates v<N+1>; two publishes of one slug in the same window
+    // both picked the same N, so the loser died on a raw rename error and the
+    // winner's latest pointer could be overwritten (#240). The lock lives in
+    // the library root, which exists before any entry does, so a refused
+    // publish still writes nothing.
+    const lock = await acquireLock(join(libraryRoot, PUBLISH_LOCK_FILE));
+    try {
+        const preview = await previewPublishVersion(libraryRoot, spec, { slug: input.slug, namespace }, opts);
+        const latestVersion = preview.latestVersion;
+        // Collision guard. Slugs derive from the trailing path segment of the source
+        // repo, so two unrelated projects (acme/whisper and openai/whisper) collapse
+        // onto one slug. Without this check the second publish would append its spec
+        // to the first project's version history, and the index would then report the
+        // newcomer's source_repo as though it owned every prior version. Checked
+        // before the idempotence branch below, because a metadata-only update would
+        // overwrite the wrong entry just as silently.
+        if (latestVersion > 0 && !opts.allowSourceRepoChange) {
+            const recorded = await readRecordedSourceRepo(libraryRoot, namespace, input.slug, latestVersion);
+            if (recorded !== null && !sameSourceRepo(recorded, input.source_repo)) {
+                const label = namespace ? `${namespace}/${input.slug}` : input.slug;
+                throw new SourceRepoMismatchError(`Refusing to publish: entry "${label}" v${latestVersion} records source_repo ` +
+                    `"${recorded}", but this publish carries "${input.source_repo}". Publishing would ` +
+                    `append this spec to a different project's version history. Publish this project ` +
+                    `under a distinct slug to shelve it separately, or — if the repository itself ` +
+                    `moved (rename, org transfer, host change) — re-publish with the source-repo ` +
+                    `change allowed: allow_source_repo_change on codecarto_publish, ` +
+                    `allowSourceRepoChange in PublishOptions.`, recorded, input.source_repo);
+            }
+        }
+        // Confidentiality guard. Levels are ordered internal < shared < public. An
+        // entry may sit in a library at or below its own level, but one more
+        // restricted than its library would be exposed to everyone the library
+        // reaches: an internal spec in a public library is a leak. Either side that
+        // declares nothing counts as internal — the marker default initLibrary
+        // writes, and the entry default docs/library-format.md documents — so a
+        // library with no visibility field accepts everything it did before. Like
+        // the collision guard this runs ahead of the idempotence branch, so a
+        // metadata-only update cannot reclassify an entry past it, and it fails
+        // before anything is written.
+        const entryConfidentiality = input.confidentiality ?? DEFAULT_VISIBILITY;
+        const libraryVisibility = marker.visibility ?? DEFAULT_VISIBILITY;
+        if (!opts.allowConfidentialityMismatch && VISIBILITY_RANK[entryConfidentiality] < VISIBILITY_RANK[libraryVisibility]) {
             const label = namespace ? `${namespace}/${input.slug}` : input.slug;
-            throw new SourceRepoMismatchError(`Refusing to publish: entry "${label}" v${latestVersion} records source_repo ` +
-                `"${recorded}", but this publish carries "${input.source_repo}". Publishing would ` +
-                `append this spec to a different project's version history. Publish this project ` +
-                `under a distinct slug to shelve it separately, or — if the repository itself ` +
-                `moved (rename, org transfer, host change) — re-publish with the source-repo ` +
-                `change allowed: allow_source_repo_change on codecarto_publish, ` +
-                `allowSourceRepoChange in PublishOptions.`, recorded, input.source_repo);
+            const declared = input.confidentiality ? "" : " (the default when none is declared)";
+            throw new ConfidentialityMismatchError(`Refusing to publish: entry "${label}" has confidentiality "${entryConfidentiality}"${declared}, ` +
+                `but library "${marker.name}" has visibility "${libraryVisibility}". Publishing would expose a ` +
+                `spec classified "${entryConfidentiality}" to everyone the "${libraryVisibility}" library reaches. ` +
+                `Publish it to a library whose visibility is "${entryConfidentiality}" or narrower, declare a ` +
+                `confidentiality of "${libraryVisibility}" or wider if the spec may travel that far, or — if ` +
+                `this exposure is intended — re-publish with the mismatch allowed: ` +
+                `allow_confidentiality_mismatch on codecarto_publish, allowConfidentialityMismatch in PublishOptions.`, entryConfidentiality, libraryVisibility);
         }
-    }
-    // Confidentiality guard. Levels are ordered internal < shared < public. An
-    // entry may sit in a library at or below its own level, but one more
-    // restricted than its library would be exposed to everyone the library
-    // reaches: an internal spec in a public library is a leak. Either side that
-    // declares nothing counts as internal — the marker default initLibrary
-    // writes, and the entry default docs/library-format.md documents — so a
-    // library with no visibility field accepts everything it did before. Like
-    // the collision guard this runs ahead of the idempotence branch, so a
-    // metadata-only update cannot reclassify an entry past it, and it fails
-    // before anything is written.
-    const entryConfidentiality = input.confidentiality ?? DEFAULT_VISIBILITY;
-    const libraryVisibility = marker.visibility ?? DEFAULT_VISIBILITY;
-    if (!opts.allowConfidentialityMismatch && VISIBILITY_RANK[entryConfidentiality] < VISIBILITY_RANK[libraryVisibility]) {
-        const label = namespace ? `${namespace}/${input.slug}` : input.slug;
-        const declared = input.confidentiality ? "" : " (the default when none is declared)";
-        throw new ConfidentialityMismatchError(`Refusing to publish: entry "${label}" has confidentiality "${entryConfidentiality}"${declared}, ` +
-            `but library "${marker.name}" has visibility "${libraryVisibility}". Publishing would expose a ` +
-            `spec classified "${entryConfidentiality}" to everyone the "${libraryVisibility}" library reaches. ` +
-            `Publish it to a library whose visibility is "${entryConfidentiality}" or narrower, declare a ` +
-            `confidentiality of "${libraryVisibility}" or wider if the spec may travel that far, or — if ` +
-            `this exposure is intended — re-publish with the mismatch allowed: ` +
-            `allow_confidentiality_mismatch on codecarto_publish, allowConfidentialityMismatch in PublishOptions.`, entryConfidentiality, libraryVisibility);
-    }
-    // Content-hash idempotence: if the latest version's spec matches bytes-for-bytes
-    // (decided by previewPublishVersion above), update metadata in place and
-    // return without bumping the version.
-    if (!preview.isNewVersion) {
-        const latestVersionDir = versionDir(libraryRoot, namespace, input.slug, latestVersion);
-        // buildMetadata writes provenance only when the input carries it, and
-        // neither surface sends it on publish — so without this the rewrite
-        // would drop the block the version's original publish recorded.
-        const provenance = input.provenance ?? (await readRecordedProvenance(libraryRoot, namespace, input.slug, latestVersion));
-        const metadata = buildMetadata({ ...input, provenance }, latestVersion);
-        await atomicWriteYaml(join(latestVersionDir, METADATA_FILE), metadata);
+        // Content-hash idempotence: if the latest version's spec matches bytes-for-bytes
+        // (decided by previewPublishVersion above), update metadata in place and
+        // return without bumping the version.
+        if (!preview.isNewVersion) {
+            const latestVersionDir = versionDir(libraryRoot, namespace, input.slug, latestVersion);
+            // buildMetadata writes provenance only when the input carries it, and
+            // neither surface sends it on publish — so without this the rewrite
+            // would drop the block the version's original publish recorded.
+            const provenance = input.provenance ?? (await readRecordedProvenance(libraryRoot, namespace, input.slug, latestVersion));
+            const metadata = buildMetadata({ ...input, provenance }, latestVersion);
+            await atomicWriteYaml(join(latestVersionDir, METADATA_FILE), metadata);
+            if (!opts.skipReindex)
+                await reindex(libraryRoot);
+            return {
+                slug: input.slug,
+                namespace,
+                version: latestVersion,
+                isNewVersion: false,
+                entryDir,
+                versionDir: latestVersionDir,
+            };
+        }
+        const nextVersion = preview.version;
+        const finalVersionDir = versionDir(libraryRoot, namespace, input.slug, nextVersion);
+        const stagingDir = `${entryDir}.publish.${uniqueTempSuffix()}`;
+        // Stage all files under a sibling directory, then atomically rename it
+        // into place as v<N>. If the rename fails partway, the staging dir is
+        // left for the user to inspect or remove.
+        await mkdir(stagingDir, { recursive: true });
+        try {
+            const metadata = buildMetadata({ ...input, provenance: input.provenance ?? { prior_version: latestVersion === 0 ? null : latestVersion, mutation_source: null } }, nextVersion);
+            await writeFile(join(stagingDir, SPEC_FILE), spec, "utf8");
+            await atomicWriteYaml(join(stagingDir, METADATA_FILE), metadata);
+            await mkdir(entryDir, { recursive: true });
+            await rename(stagingDir, finalVersionDir);
+        }
+        catch (err) {
+            // Best-effort cleanup of the staging directory.
+            try {
+                await rm(stagingDir, { recursive: true, force: true });
+            }
+            catch {
+                // swallow — leave the staging dir for diagnostics
+            }
+            throw err;
+        }
+        await writeLatestPointer(entryDir, `v${nextVersion}`);
         if (!opts.skipReindex)
             await reindex(libraryRoot);
         return {
             slug: input.slug,
             namespace,
-            version: latestVersion,
-            isNewVersion: false,
+            version: nextVersion,
+            isNewVersion: true,
             entryDir,
-            versionDir: latestVersionDir,
+            versionDir: finalVersionDir,
         };
     }
-    const nextVersion = preview.version;
-    const finalVersionDir = versionDir(libraryRoot, namespace, input.slug, nextVersion);
-    const stagingDir = `${entryDir}.publish.${process.pid}.${Date.now()}`;
-    // Stage all files under a sibling directory, then atomically rename it
-    // into place as v<N>. If the rename fails partway, the staging dir is
-    // left for the user to inspect or remove.
-    await mkdir(stagingDir, { recursive: true });
-    try {
-        const metadata = buildMetadata({ ...input, provenance: input.provenance ?? { prior_version: latestVersion === 0 ? null : latestVersion, mutation_source: null } }, nextVersion);
-        await writeFile(join(stagingDir, SPEC_FILE), spec, "utf8");
-        await atomicWriteYaml(join(stagingDir, METADATA_FILE), metadata);
-        await mkdir(entryDir, { recursive: true });
-        await rename(stagingDir, finalVersionDir);
-    }
-    catch (err) {
-        // Best-effort cleanup of the staging directory.
-        try {
-            await rm(stagingDir, { recursive: true, force: true });
-        }
-        catch {
-            // swallow — leave the staging dir for diagnostics
-        }
-        throw err;
+    finally {
+        await lock.release();
     }
-    await writeLatestPointer(entryDir, `v${nextVersion}`);
-    if (!opts.skipReindex)
-        await reindex(libraryRoot);
-    return {
-        slug: input.slug,
-        namespace,
-        version: nextVersion,
-        isNewVersion: true,
-        entryDir,
-        versionDir: finalVersionDir,
-    };
 }
 function buildMetadata(input, version) {
     const out = {
@@ -853,10 +864,7 @@ async function writeIndexMarkdown(libraryRoot, index, marker) {
         lines.push("");
     }
     const content = lines.join("\n");
-    const path = join(libraryRoot, LIBRARY_INDEX_MD_FILE);
-    const tempPath = `${path}.${process.pid}.${Date.now()}.tmp`;
-    await writeFile(tempPath, content, "utf8");
-    await rename(tempPath, path);
+    await atomicWriteFile(join(libraryRoot, LIBRARY_INDEX_MD_FILE), content);
 }
 function formatIndexRow(e, namespaced) {
     // Link to the newest version directory, not `latest/`: the pointer is a
@@ -941,10 +949,7 @@ async function findProvenanceConflict(libraryRoot, namespace, slug) {
 }
 // ─── Atomic YAML write ──────────────────────────────────────────────────────
 async function atomicWriteYaml(path, value) {
-    const serialized = `${stringifySimpleYaml(value)}\n`;
-    const tempPath = `${path}.${process.pid}.${Date.now()}.tmp`;
-    await writeFile(tempPath, serialized, "utf8");
-    await rename(tempPath, path);
+    await atomicWriteFile(path, `${stringifySimpleYaml(value)}\n`);
 }
 // ─── Hash ───────────────────────────────────────────────────────────────────
 function sha256(content) {

package/dist/core/status.d.ts

@@ -36,6 +36,26 @@ export declare function parseHandoff(value: unknown): PhaseHandoff;
 export declare function ensureProposedConventionArray(value: unknown): ProposedConventionEntry[];
 export declare function loadHandoffFile(phaseId: string, workspaceDir: string): Promise<PhaseHandoff | null>;
 export declare function applyHandoff(status: NormalizedStatus, handoff: PhaseHandoff): NormalizedStatus;
-export declare function acquireLock(lockPath: string): Promise<{
+/** What {@link acquireLock} hands back: a release that only ever removes its own lock. */
+export interface LockHandle {
     release: () => Promise<void>;
-}>;
+    /**
+     * Set when acquiring meant breaking a lock older than {@link STALE_LOCK_MS}:
+     * the previous holder as its lock file recorded it, for callers that log.
+     */
+    brokeStale?: {
+        pid: number | null;
+        since: string | null;
+    };
+}
+/**
+ * Take the O_EXCL lock at `lockPath`, waiting up to {@link LOCK_TIMEOUT_MS}
+ * and breaking a lock older than {@link STALE_LOCK_MS}.
+ *
+ * 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).
+ */
+export declare function acquireLock(lockPath: string): Promise<LockHandle>;

package/dist/core/status.js

@@ -1,6 +1,7 @@
 // Status normalization, atomic writes, and file-lock primitives. Pure
 // framework logic shared by every wrapper.
-import { open, rm, stat } from "node:fs/promises";
+import { randomBytes } from "node:crypto";
+import { open, readFile, rm, stat } from "node:fs/promises";
 import { basename, join } from "node:path";
 import { pathExists, sleep } from "./utils.js";
 import { loadYamlFile } from "./yaml.js";
@@ -397,13 +398,25 @@ export function applyHandoff(status, handoff) {
     status.post_pipeline = [...legacyPostPipeline, ...postPipeline.values()];
     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}.
+ *
+ * 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).
+ */
 export async function acquireLock(lockPath) {
     const startedAt = Date.now();
+    const token = `${process.pid}.${randomBytes(8).toString("hex")}`;
+    let brokeStale;
     while (true) {
         try {
             const handle = await open(lockPath, "wx");
             try {
-                await handle.writeFile(`${process.pid}\n${new Date().toISOString()}\n`, "utf8");
+                await handle.writeFile(`${process.pid}\n${new Date().toISOString()}\n${token}\n`, "utf8");
             }
             catch (error) {
                 // A non-EEXIST write failure must not leak the descriptor the
@@ -413,9 +426,8 @@ export async function acquireLock(lockPath) {
             }
             await handle.close();
             return {
-                release: async () => {
-                    await rm(lockPath, { force: true }).catch(() => undefined);
-                },
+                release: () => releaseOwnedLock(lockPath, token),
+                ...(brokeStale && { brokeStale }),
             };
         }
         catch (error) {
@@ -425,6 +437,7 @@ 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;
                 }
@@ -439,3 +452,31 @@ export async function acquireLock(lockPath) {
         }
     }
 }
+/**
+ * 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.
+ */
+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);
+}
+async function describeLockHolder(lockPath) {
+    try {
+        const [pidLine, sinceLine] = (await readFile(lockPath, "utf8")).split(/\r?\n/);
+        const pid = Number.parseInt(pidLine ?? "", 10);
+        return { pid: Number.isFinite(pid) ? pid : null, since: sinceLine?.trim() || null };
+    }
+    catch {
+        return { pid: null, since: null };
+    }
+}

package/dist/core/usage.d.ts

@@ -44,6 +44,14 @@ export interface UsageTotals {
     compactions: CompactionTelemetry;
 }
 export declare function loadUsage(workspaceDir: string): Promise<UsageFile>;
+/**
+ * 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 declare function appendUsageRun(workspaceDir: string, run: UsageRun): Promise<void>;
 export declare function computeTotals(file: UsageFile): UsageTotals;
 export declare function computePerPhaseTotals(file: UsageFile): Map<string, UsageTotals>;