@cruxy/cli 1.11.4 → 1.11.6

package/dist/errors/constructors.js

@@ -1247,6 +1247,70 @@ export function memoryInvalid(detail) {
         ],
     });
 }
+/**
+ * A memory write was refused because the scope's existing store could not be
+ * loaded, so the write would have replaced everything it held with the one
+ * new note and reported success (cli#327). The same shape as
+ * {@link credentialsUnprotected}: nothing is written, the file is named, and
+ * the next step depends on WHICH state the file is in —
+ *
+ *  - `unreadable`: the bytes could not be read at all (permissions, a
+ *    directory at the path). Fix the path; the content is presumably intact.
+ *  - `invalid`: the bytes were read but are not a memory document — a
+ *    half-written file (a crash or a concurrent writer mid-write) or a hand
+ *    edit that broke the JSON or the shape. Repair or clear it.
+ *
+ * An ABSENT file is not this error: it is the one state where starting empty
+ * is correct, and conflating it with these two is what caused the wipe.
+ */
+export function memoryStoreUnloadable(scope, state, path, detail, underlying) {
+    const title = state === "unreadable"
+        ? `refusing to write memory over a store that could not be read: ${path}`
+        : `refusing to write memory over a store that is not a valid memory file: ${path}`;
+    const nextSteps = state === "unreadable"
+        ? [
+            "nothing was written — the existing notes are presumably intact, but they could not be read",
+            `make ${path} a regular file readable and writable by you, then retry`,
+        ]
+        : [
+            "nothing was written — saving would have replaced every note the file holds",
+            `inspect ${path}: a half-written or hand-edited file; restore it from a backup or your editor, then retry`,
+            `or start the scope empty with \`cruxy memory clear --scope ${scope}\` (this discards whatever the file held)`,
+        ];
+    return new CruxyError({
+        code: ErrorCode.MemoryStoreUnloadable,
+        title,
+        cause: detail,
+        nextSteps,
+        underlying,
+        meta: { path, scope, state },
+    });
+}
+/**
+ * A store write waited {@link STORE_LOCK_WAIT_MS}-ish for the cross-process
+ * lock and a live process still held it (cli#304). Nothing was written. The
+ * holder is named when its stamp could be read; an unreadable stamp (a holder
+ * killed between creating and writing the lock file, microseconds apart) is
+ * the one case the user may need to remove the file by hand — so the path is
+ * in the message.
+ */
+export function storeLocked(file, lockFile, holder) {
+    const who = holder
+        ? `held by pid ${holder.pid}, started ${holder.startedAt}`
+        : `held by a process whose stamp could not be read (${lockFile})`;
+    return new CruxyError({
+        code: ErrorCode.StoreLocked,
+        title: `another cruxy is writing ${file}`,
+        cause: who,
+        nextSteps: holder
+            ? ["retry in a moment — the other write takes milliseconds"]
+            : [
+                `if no other cruxy is running, remove ${lockFile} and retry`,
+                "retry in a moment otherwise",
+            ],
+        meta: { path: file, lockFile, holderPid: holder?.pid },
+    });
+}
 // ── usage telemetry (exit 2) — C.22 ───────────────────────────────────────────
 /**
  * The local usage store (`~/.cruxy/usage/runs.json`) is corrupt or unreadable

package/dist/errors/types.js

@@ -172,6 +172,16 @@ export const ErrorCode = {
     /** A memory write was refused because the content matched a secret shape —
      * secrets are never persisted (defense in depth over C.17). */
     MemorySecret: "CRUXY_E_MEMORY_SECRET",
+    /** A memory write was refused because the scope's existing store could not
+     * be loaded — unreadable, or readable but not a valid memory document (a
+     * torn or hand-broken file). Writing would replace everything it held with
+     * the one new note and report success (cli#327). Nothing is written. */
+    MemoryStoreUnloadable: "CRUXY_E_MEMORY_STORE_UNLOADABLE",
+    /** A store write (memory, usage, trust) waited its bounded time for the
+     * cross-process store lock and another LIVE cruxy still held it (cli#304).
+     * Nothing was written; the holder is named. A stale lock never produces
+     * this — a dead holder's lock is taken, not waited on. */
+    StoreLocked: "CRUXY_E_STORE_LOCKED",
     // usage telemetry (exit 2) — C.22
     /** The local usage store is corrupt/unreadable — the read is SKIPPED and this
      * is surfaced; never fatal to a run (usage display is best-effort). */
@@ -388,6 +398,8 @@ const EXIT_CODES = {
     [ErrorCode.MemoryInvalid]: 14,
     [ErrorCode.MemoryUntrusted]: 14,
     [ErrorCode.MemorySecret]: 14,
+    [ErrorCode.MemoryStoreUnloadable]: 14,
+    [ErrorCode.StoreLocked]: 14,
     // Usage telemetry (C.22). A corrupt store is a usage/data problem the user can
     // fix (delete the file); it shares the usage exit code and is never fatal to a
     // run — the aggregation just skips it.

package/dist/memory/remember-tool.js

@@ -58,7 +58,11 @@ export const rememberTool = {
             // Fail loud to the model: a refused secret / invalid note is reported with
             // its stable code so the model knows it was NOT stored (never a silent no-op).
             if (CruxyError.is(err)) {
-                return { ok: false, error: `${err.code}: ${err.title}` };
+                // The next steps ride along so the model can tell the user what to do
+                // (cli#327: "refusing to write over a store that could not be read"
+                // is only actionable with the file and the fix named).
+                const steps = err.nextSteps.length > 0 ? ` — ${err.nextSteps.join("; ")}` : "";
+                return { ok: false, error: `${err.code}: ${err.title}${steps}` };
             }
             return { ok: false, error: err.message };
         }

package/dist/memory/service.js

@@ -1,6 +1,7 @@
 import path from "node:path";
 import { randomUUID } from "node:crypto";
-import { memoryInvalid, memorySecretRefused } from "../errors/index.js";
+import { memoryInvalid, memorySecretRefused, memoryStoreUnloadable, } from "../errors/index.js";
+import { withStoreLock } from "../utils/store-lock.js";
 import { buildRecallBlock } from "./recall.js";
 import { containsSecret } from "./secrets.js";
 import { defaultMemorySources, loadScope, saveScope, } from "./store.js";
@@ -78,20 +79,25 @@ export class MemoryService {
             createdAt: this.now(),
         };
         const file = this.sources[scope];
-        const existing = loadScope(file, scope).entries;
-        if (scope === "project") {
-            // Snapshot trust BEFORE the write — this is the launder guard.
-            const wasTrustedOrEmpty = existing.length === 0 || this.projectTrusted(existing);
-            const next = [...existing, entry];
-            saveScope(file, next, scope);
-            // Only extend trust when we started clean; never over foreign untrusted
-            // entries.
-            if (wasTrustedOrEmpty)
-                this.recordProjectTrust(next);
-        }
-        else {
-            saveScope(file, [...existing, entry], scope);
-        }
+        // The whole read-modify-write under the cross-process lock (cli#304): a
+        // second cruxy's `remember` on the same file waits for this one instead
+        // of loading a set this write is about to replace.
+        withStoreLock(file, () => {
+            const existing = this.loadForWrite(file, scope).entries;
+            if (scope === "project") {
+                // Snapshot trust BEFORE the write — this is the launder guard.
+                const wasTrustedOrEmpty = existing.length === 0 || this.projectTrusted(existing);
+                const next = [...existing, entry];
+                saveScope(file, next, scope);
+                // Only extend trust when we started clean; never over foreign untrusted
+                // entries.
+                if (wasTrustedOrEmpty)
+                    this.recordProjectTrust(next);
+            }
+            else {
+                saveScope(file, [...existing, entry], scope);
+            }
+        });
         return entry;
     }
     /** A snapshot of both scopes + project trust, for `cruxy memory list`. */
@@ -113,15 +119,19 @@ export class MemoryService {
     forget(id) {
         for (const scope of ["user", "project"]) {
             const file = this.sources[scope];
-            const entries = loadScope(file, scope).entries;
-            const kept = entries.filter((e) => e.id !== id);
-            if (kept.length === entries.length)
-                continue;
-            const wasTrusted = scope === "project" && this.projectTrusted(entries);
-            saveScope(file, kept, scope);
-            if (wasTrusted)
-                this.recordProjectTrust(kept);
-            return true;
+            const removed = withStoreLock(file, () => {
+                const entries = this.loadForWrite(file, scope).entries;
+                const kept = entries.filter((e) => e.id !== id);
+                if (kept.length === entries.length)
+                    return false;
+                const wasTrusted = scope === "project" && this.projectTrusted(entries);
+                saveScope(file, kept, scope);
+                if (wasTrusted)
+                    this.recordProjectTrust(kept);
+                return true;
+            });
+            if (removed)
+                return true;
         }
         return false;
     }
@@ -131,15 +141,21 @@ export class MemoryService {
         let removed = 0;
         for (const s of scopes) {
             const file = this.sources[s];
-            const entries = loadScope(file, s).entries;
-            removed += entries.length;
-            saveScope(file, [], s);
-            // Clearing project memory to empty: re-anchor trust to the empty set so a
-            // later `remember` starts from a clean, trusted baseline (empty memory is
-            // never recalled anyway).
-            if (s === "project" && this.projectTrusted(entries)) {
-                this.recordProjectTrust([]);
-            }
+            withStoreLock(file, () => {
+                // Deliberately NOT `loadForWrite`: clearing is the documented recovery
+                // for a store that cannot be loaded (cli#327). Emptying it is the
+                // user's explicit intent here, so an unloadable file counts as 0
+                // removed and is replaced with an empty document.
+                const entries = loadScope(file, s).entries;
+                removed += entries.length;
+                saveScope(file, [], s);
+                // Clearing project memory to empty: re-anchor trust to the empty set
+                // so a later `remember` starts from a clean, trusted baseline (empty
+                // memory is never recalled anyway).
+                if (s === "project" && this.projectTrusted(entries)) {
+                    this.recordProjectTrust([]);
+                }
+            });
         }
         return removed;
     }
@@ -150,9 +166,30 @@ export class MemoryService {
      * become recallable.
      */
     trustProject() {
-        const entries = loadScope(this.sources.project, "project").entries;
-        this.recordProjectTrust(entries);
-        return entries.length;
+        // Trust is a fingerprint over the entry SET. Recording it for the empty
+        // set an unloadable file reads as would trust nothing and, once the file
+        // is repaired, mismatch its real content — so this refuses like a write.
+        return withStoreLock(this.sources.project, () => {
+            const entries = this.loadForWrite(this.sources.project, "project").entries;
+            this.recordProjectTrust(entries);
+            return entries.length;
+        });
+    }
+    /**
+     * Load a scope for a path that will WRITE the whole set back (cli#327).
+     * `absent` and `loaded` are fine; `unreadable` and `invalid` are refused
+     * with `CRUXY_E_MEMORY_STORE_UNLOADABLE`, because the "existing" set is
+     * empty only because the load failed, and saving it back would replace every
+     * note the file holds with whatever this call adds — while reporting success.
+     * A read-only path (`recall`, `status`) keeps using `loadScope` directly and
+     * surfaces the same condition as an error row instead.
+     */
+    loadForWrite(file, scope) {
+        const load = loadScope(file, scope);
+        if (load.file.kind === "unreadable" || load.file.kind === "invalid") {
+            throw memoryStoreUnloadable(scope, load.file.kind, file, load.file.message, load.file.underlying);
+        }
+        return load;
     }
     recordProjectTrust(entries) {
         this.trust.record({

package/dist/memory/store.js

@@ -1,6 +1,7 @@
-import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { mkdirSync, readFileSync } from "node:fs";
 import path from "node:path";
 import { globalDir } from "../config/paths.js";
+import { existingMode, replaceStoreFile } from "../utils/store-file.js";
 import { GLOBAL_DIR_NAME, MEMORY_DIR_NAME, MEMORY_FILE_NAME, } from "../constants.js";
 import { containsSecret } from "./secrets.js";
 import { MemoryEntrySchema, MemoryFileSchema, MEMORY_FILE_VERSION, } from "./types.js";
@@ -13,46 +14,60 @@ export function defaultMemorySources(cwd) {
     };
 }
 /**
- * Read and validate one scope's file. A missing file yields an empty result
- * (not an error). Each entry is (1) schema-validated and (2) scanned for secret
- * content; failures are excluded and collected. The returned `entries` all carry
- * the requested `scope` (the on-disk `scope` field is normalized to it, so a
- * mislabeled entry can't cross scopes).
+ * Read and validate one scope's file. Each entry is (1) schema-validated and
+ * (2) scanned for secret content; failures are excluded and collected. The
+ * returned `entries` all carry the requested `scope` (the on-disk `scope` field
+ * is normalized to it, so a mislabeled entry can't cross scopes).
+ *
+ * THE FILE-LEVEL STATE IS REPORTED SEPARATELY (`file`, cli#327), because three
+ * different situations used to collapse into "empty, carry on":
+ *
+ *  - a MISSING file (ENOENT) is `absent` — the one state where starting from
+ *    an empty set is right;
+ *  - any OTHER read failure (EACCES, EISDIR, ...) is `unreadable` — something
+ *    is there and we could not see it;
+ *  - bytes that are not a memory document (not JSON, or the wrong shape) are
+ *    `invalid` — something was there and it is damaged, or half-written.
+ *
+ * Readers (recall, `cruxy memory list`) still get `entries: []` plus an error
+ * row for the last two, so nothing that only READS changes behaviour. Writers
+ * must branch on `file.kind`: see {@link saveScope}'s contract and
+ * `MemoryService.remember`.
  */
 export function loadScope(file, scope) {
     let raw;
     try {
         raw = readFileSync(file, "utf8");
     }
-    catch {
-        // Missing / unreadable → nothing recalled from this scope (not an error).
-        return { entries: [], errors: [] };
+    catch (err) {
+        if (err.code === "ENOENT") {
+            // Missing → nothing recalled from this scope, and a write may create it.
+            return { entries: [], errors: [], file: { kind: "absent" } };
+        }
+        // Present but unreadable. NOT absent: a writer that treated it as absent
+        // would replace whatever is there.
+        const message = `unreadable: ${err.message}`;
+        return {
+            entries: [],
+            errors: [{ scope, reason: "unreadable", id: "(file)", message }],
+            file: { kind: "unreadable", message, underlying: err },
+        };
     }
     let parsedFile;
     try {
         parsedFile = JSON.parse(raw);
     }
-    catch {
-        return {
-            entries: [],
-            errors: [
-                { scope, reason: "invalid", id: "(file)", message: "not valid JSON" },
-            ],
-        };
+    catch (err) {
+        // Read fine, but not JSON: a half-written file (a crash or another
+        // writer mid-`writeFileSync`) or a hand edit. Either way it HELD something.
+        const message = raw.length === 0
+            ? "not valid JSON (the file is empty — a truncated or half-written store)"
+            : "not valid JSON (a half-written or hand-edited store)";
+        return invalidFile(scope, message, err);
     }
     const fileResult = MemoryFileSchema.safeParse(parsedFile);
     if (!fileResult.success) {
-        return {
-            entries: [],
-            errors: [
-                {
-                    scope,
-                    reason: "invalid",
-                    id: "(file)",
-                    message: `malformed memory file: ${fileResult.error.issues[0]?.message ?? "invalid shape"}`,
-                },
-            ],
-        };
+        return invalidFile(scope, `malformed memory file: ${fileResult.error.issues[0]?.message ?? "invalid shape"}`);
     }
     const entries = [];
     const errors = [];
@@ -86,15 +101,46 @@ export function loadScope(file, scope) {
         // move an entry across scopes).
         entries.push({ ...parsed.data, scope });
     });
-    return { entries, errors };
+    return { entries, errors, file: { kind: "loaded" } };
+}
+function invalidFile(scope, message, underlying) {
+    const file = { kind: "invalid", message, underlying };
+    return {
+        entries: [],
+        errors: [{ scope, reason: "invalid", id: "(file)", message }],
+        file,
+    };
 }
 /**
- * Persist a scope's entries, overwriting the file. Creates the memory dir if
- * needed. The user scope is written `0600` (it is personal, cross-project data);
- * the project scope inherits normal repo permissions (it may be committed).
+ * Persist a scope's entries, replacing the file. Creates the memory dir if
+ * needed. The user scope is written `0600` (it is personal, cross-project data).
+ * The project scope KEEPS THE MODE THE FILE ALREADY HAD, and takes the process
+ * umask only when creating it: a replace through rename is a new inode, and
+ * letting it land at whatever umask says would be a permission change the user
+ * never asked for, arriving through a write path — the same reason `api.env`'s
+ * mode has to survive a `sed`.
+ *
+ * WRITTEN TO A TEMP FILE AND RENAMED INTO PLACE (cli#327) through
+ * `utils/store-file.ts`, which also checks the cross-process store lock right
+ * before the rename (cli#304). A plain `writeFileSync` on an existing path truncates first and
+ * fills in after, so anything reading in between — recall in a second cruxy,
+ * `cruxy memory list`, or another writer's load — saw an empty or half-written
+ * file. `rename(2)` swaps the whole document in one step: a reader sees the
+ * old bytes or the new ones, never a prefix. It does NOT serialize two writers
+ * (that is #304, the read-modify-write race); it only guarantees that what
+ * either of them reads is a complete document.
+ *
+ * CONTRACT FOR CALLERS: this overwrites whatever is at `file`. It must only be
+ * called with a set derived from a load whose `file.kind` was `loaded` or
+ * `absent` — never `unreadable` or `invalid`, where the caller's "existing"
+ * set is empty only because the load failed. `MemoryService` enforces that;
+ * `clear` is the deliberate exception (it is the documented recovery).
  */
 export function saveScope(file, entries, scope) {
     mkdirSync(path.dirname(file), { recursive: true });
     const body = JSON.stringify({ version: MEMORY_FILE_VERSION, entries }, null, 2);
-    writeFileSync(file, body, scope === "user" ? { mode: 0o600 } : undefined);
+    // The mode the replacement must carry: explicit 0600 for the user scope;
+    // for the project scope, whatever the existing file has (absent → umask).
+    const mode = scope === "user" ? 0o600 : existingMode(file);
+    replaceStoreFile(file, body, mode);
 }

package/dist/memory/trust.js

@@ -1,5 +1,7 @@
 import { createHash } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { mkdirSync, readFileSync } from "node:fs";
+import { replaceStoreFile } from "../utils/store-file.js";
+import { withStoreLock } from "../utils/store-lock.js";
 import path from "node:path";
 import { globalDir } from "../config/paths.js";
 import { MEMORY_TRUST_FILE_NAME } from "../constants.js";
@@ -57,20 +59,21 @@ export function isMemoryTrusted(store, root, currentFingerprint) {
  */
 export function fileMemoryTrustStore(file = memoryTrustPath()) {
     let cache = null;
-    const load = () => {
-        if (cache)
-            return cache;
+    const readFresh = () => {
         try {
             const raw = JSON.parse(readFileSync(file, "utf8"));
-            cache =
-                raw && typeof raw === "object"
-                    ? raw
-                    : {};
+            return raw && typeof raw === "object"
+                ? raw
+                : {};
         }
         catch {
             // Missing or corrupt → no trust (fail-closed).
-            cache = {};
+            return {};
         }
+    };
+    const load = () => {
+        if (!cache)
+            cache = readFresh();
         return cache;
     };
     return {
@@ -78,16 +81,20 @@ export function fileMemoryTrustStore(file = memoryTrustPath()) {
             return load()[path.resolve(root)];
         },
         record(trust) {
-            const store = load();
-            store[path.resolve(trust.root)] = {
-                ...trust,
-                root: path.resolve(trust.root),
-            };
-            mkdirSync(path.dirname(file), { recursive: true });
-            // 0600: trust records name local paths; keep them owner-only.
-            writeFileSync(file, JSON.stringify(store, null, 2), { mode: 0o600 });
-            if (existsSync(file))
+            // Under the cross-process lock, from a FRESH read (cli#304): the cached
+            // document may predate another cruxy's record for a different root, and
+            // writing the cache back would drop that root's trust. Atomic replace,
+            // `0600`: trust records name local paths; keep them owner-only.
+            withStoreLock(file, () => {
+                const store = readFresh();
+                store[path.resolve(trust.root)] = {
+                    ...trust,
+                    root: path.resolve(trust.root),
+                };
+                mkdirSync(path.dirname(file), { recursive: true });
+                replaceStoreFile(file, JSON.stringify(store, null, 2), 0o600);
                 cache = store;
+            });
         },
     };
 }

package/dist/usage/store.js

@@ -1,8 +1,10 @@
-import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { mkdirSync, readFileSync } from "node:fs";
 import path from "node:path";
 import { globalDir } from "../config/paths.js";
 import { USAGE_DIR_NAME, USAGE_FILE_NAME } from "../constants.js";
-import { usageRead } from "../errors/index.js";
+import { CruxyError, usageRead } from "../errors/index.js";
+import { existingMode, replaceStoreFile } from "../utils/store-file.js";
+import { withStoreLock } from "../utils/store-lock.js";
 import { UsageFileSchema, USAGE_FILE_VERSION, } from "./types.js";
 /**
  * The usage store (C.22): a single JSON file under `~/.cruxy/usage`, holding a
@@ -62,6 +64,20 @@ export function loadUsage(file = usageStorePath()) {
  */
 export function appendRun(record, opts = { retention: 50 }) {
     const file = opts.file ?? usageStorePath();
+    // The whole read-modify-write under the cross-process lock (cli#304), so two
+    // runs finishing at once queue instead of one dropping the other's record.
+    // `never throws` still holds: a lock held past its deadline by a live cruxy
+    // comes back as the coded error for the caller to downgrade.
+    try {
+        return withStoreLock(file, () => appendRunLocked(record, opts, file));
+    }
+    catch (err) {
+        if (CruxyError.is(err))
+            return { error: err };
+        throw err;
+    }
+}
+function appendRunLocked(record, opts, file) {
     // A corrupt existing file is NOT overwritten — surface it and skip, rather
     // than silently destroying whatever the user has (or blindly appending to a
     // shape we couldn't validate).
@@ -80,7 +96,9 @@ export function appendRun(record, opts = { retention: 50 }) {
         // the data, just one write later. version/runs are re-stated after the
         // spread so this build's own values always win.
         const body = JSON.stringify({ ...loaded.data, version: USAGE_FILE_VERSION, runs: pruned }, null, 2);
-        writeFileSync(file, body, { mode: 0o600 });
+        // Atomic replace through the shared helper; `0600` on create, the file's
+        // own bits on a replace (a rename is a new inode; see store-file.ts).
+        replaceStoreFile(file, body, existingMode(file) ?? 0o600);
         return {};
     }
     catch (err) {

package/dist/utils/store-file.js

@@ -0,0 +1,51 @@
+import { chmodSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { assertStoreLockHeld } from "./store-lock.js";
+/**
+ * Replace a store document atomically (cli#304): write a temp file beside it,
+ * pin the mode, verify the store lock is still ours, rename into place. The
+ * one copy of the pattern `memory/store.ts`, `usage/store.ts` and
+ * `memory/trust.ts` share; `config/credentials.ts` keeps its own because it
+ * also enforces an owner-only ACL on the temp.
+ *
+ * `rename(2)` swaps a complete document in one step, so a reader — or another
+ * writer's load — sees the old bytes or the new ones, never a truncated or
+ * spliced file. The lock check sits immediately before the rename because the
+ * rename is the commit: if the lock was taken from under us, nothing lands
+ * and `withStoreLock` retries the whole read-modify-write from a fresh load.
+ *
+ * `mode` is chmod'd explicitly: `writeFileSync`'s mode is masked by the umask
+ * and applies only on create, and the temp IS a create. A rename is a new
+ * inode, so without this a replace would silently change the file's
+ * permission bits — a change the user never asked for, arriving through a
+ * write path. Callers decide the bits (explicit `0600` for personal data,
+ * {@link existingMode} to preserve what a file already has).
+ */
+export function replaceStoreFile(file, body, mode) {
+    const tmp = `${file}.tmp-${process.pid}`;
+    try {
+        writeFileSync(tmp, body, mode !== undefined ? { mode } : undefined);
+        if (mode !== undefined)
+            chmodSync(tmp, mode);
+        assertStoreLockHeld(file);
+        renameSync(tmp, file);
+    }
+    catch (err) {
+        try {
+            rmSync(tmp, { force: true });
+        }
+        catch {
+            // The temp may already be gone; the target file is untouched regardless.
+        }
+        throw err;
+    }
+}
+/** The permission bits of `file`, or `undefined` when there is nothing there
+ * to preserve (the create case takes the caller's default). */
+export function existingMode(file) {
+    try {
+        return statSync(file).mode & 0o777;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/utils/store-lock.js

@@ -0,0 +1,324 @@
+import { mkdirSync, readFileSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
+import path from "node:path";
+import { performance } from "node:perf_hooks";
+import { storeLocked } from "../errors/index.js";
+import { describeOwner, pidAlive, selfStamp, } from "./process-owner.js";
+/**
+ * An exclusive, cross-process lock around a store's read-modify-write span
+ * (cli#304).
+ *
+ * WHY A LOCK AND NOT A COMPARE. The memory, usage and trust stores are each
+ * one JSON document: load, mutate, replace. The span is synchronous, so
+ * nothing in one process can interleave it — but a second cruxy in the same
+ * project can, and when it does the later writer's load predates the earlier
+ * writer's rename and the earlier record is gone, while both callers were
+ * told it was saved. Measured: ~50 % of writes lost under a two-process tight
+ * loop, ~span ÷ gap otherwise. A compare-and-swap on the loaded bytes was
+ * measured too and still lost a third of them, because both writers pass the
+ * compare before either renames. Only mutual exclusion closed it: zero lost
+ * across every trial, at 0.5–2 ms per write.
+ *
+ * THE LOCK IS A FILE created with `wx` (`O_CREAT | O_EXCL`) beside the store,
+ * holding this process's {@link ProcessStamp}. Creation is the atomic step;
+ * whoever's `open` succeeds holds the lock. A contender spins for at most
+ * {@link STORE_LOCK_WAIT_MS} and then refuses with `CRUXY_E_STORE_LOCKED`
+ * naming the holder — never silently proceeds.
+ *
+ * STALENESS IS P1's RULE, NOT A NEW ONE. The stamp is a pid plus the start
+ * token `utils/process-owner.ts` reads from the OS for that pid, and
+ * {@link describeOwner} decides: a stamp whose process is gone, or whose pid
+ * was recycled onto a different start time, is `stale`, and a stale lock is
+ * not a holder — it is removed and taken. Nothing is cleaned up for
+ * correctness; a crash leaves a stamp that the next writer recognises as dead
+ * the moment it reads it. This is the same rule the session owner file uses,
+ * chosen in P1 because a lock that outlives its crash is worse than no lock.
+ *
+ * ONE RESIDUAL, AND THE CHECK THAT COVERS IT. Breaking a stale lock is
+ * read-then-unlink, two syscalls; two contenders that both read the same
+ * dead stamp can both unlink, and the second unlink can remove the first's
+ * freshly created lock. So a holder records its lock file's inode, and
+ * {@link assertStoreLockHeld} — called by the store right before its rename —
+ * re-stats the lock: a missing or different inode means the lock was taken
+ * from under us, and the write is NOT committed. The error is caught here
+ * and the whole read-modify-write is retried from a fresh load. Retried, not
+ * refused: there is no approval in a store write, the operation is a
+ * function of the current state, so a retry produces exactly the right
+ * result and a refusal would fail a valid append.
+ *
+ * A stamp that cannot be parsed (a holder killed between `open` and
+ * `write`, microseconds apart) has no pid to judge and is treated as held
+ * until the deadline, then refused with the path so the user can remove it.
+ * Inventing a second liveness rule (mtime, age) for that case would be worse
+ * than the refusal.
+ *
+ * WIN32 REPORTS CONTENTION AS EPERM, NOT EEXIST. Unlinking a file another
+ * process still has open does not remove it there; it becomes delete-pending
+ * until the last handle closes, and during that window a create on the same
+ * name fails with `EPERM` (ERROR_ACCESS_DENIED), as does opening it to read.
+ * A releasing holder and a contender mid-`readStamp` hit exactly that window
+ * on every burst. So `EPERM`, `EACCES` and `EBUSY` from the create or the
+ * read are the same event as `EEXIST` — someone else is at the lock — and
+ * are spun on, not thrown. A real permission problem still surfaces: if the
+ * deadline passes without a holder ever having been read, the last such
+ * error is thrown as itself rather than dressed up as `CRUXY_E_STORE_LOCKED`.
+ * Found by CI: the three contention tests passed on darwin and linux and
+ * failed on windows-latest with `EPERM open runs.json.lock`.
+ */
+/** Errors a create/read/unlink on the lock file can return while another
+ * process is at it (see WIN32 in the module comment). */
+const CONTENTION_CODES = new Set(["EEXIST", "EPERM", "EACCES", "EBUSY"]);
+function isContention(err) {
+    return CONTENTION_CODES.has(err.code ?? "");
+}
+/**
+ * How long a contender waits for a held lock before refusing.
+ *
+ * Measured spans are 0.5–3 ms, and 250 ms was the first figure: two orders
+ * of magnitude of headroom on an idle machine. On a SATURATED one it is not
+ * enough — a holder that is descheduled mid-span holds the lock for as long
+ * as the scheduler leaves it off-CPU, and with the full test suite running in
+ * parallel the two-process memory test refused writes at 250 ms in one of two
+ * runs. The budget bounds a wait, not a span; nothing on the success path
+ * costs more with a larger one. Two seconds is still a bounded, visible
+ * refusal, and it was not reached under that same load.
+ *
+ * Do not tighten this back toward the measured span for tidiness: a smaller
+ * figure buys nothing on the success path and turns scheduler jitter into a
+ * refused write. Only lower it with a new measurement under full-suite load.
+ */
+export const STORE_LOCK_WAIT_MS = 2000;
+/** How many times a lost-lock retry is attempted before the error propagates. */
+const MAX_LOST_LOCK_RETRIES = 3;
+const SPIN_MS = 1;
+/** How long a waiter polls without sleeping before it backs off to
+ * {@link SPIN_MS} sleeps. A holder in a burst releases and re-creates the lock
+ * microseconds apart; a sleeping poller misses that window almost every time,
+ * a busy poller catches it. Costs CPU only while contended. */
+const BUSY_POLL_MS = 3;
+/**
+ * FAIRNESS. A process writing the same store in a burst releases the lock and
+ * re-creates it microseconds later, while a contender polls once per
+ * {@link SPIN_MS}; measured, that starves the contender for the whole wait
+ * (1–2 refusals per 2000 writes under a two-process tight loop) even though
+ * every individual hold is a millisecond. So a process that released a lock
+ * within the last poll interval yields one interval before taking it again:
+ * an isolated write pays nothing, a burst pays a millisecond per write, and a
+ * waiter always gets a window. Polls are jittered so contenders do not
+ * phase-lock on the holder's cycle.
+ */
+const lastReleased = new Map();
+/**
+ * Liveness verdicts by the exact stamp bytes seen on disk. {@link describeOwner}
+ * reads the holder's start token from the OS — on darwin that is one `ps`
+ * subprocess (~10 ms), on win32 a PowerShell call — so it is asked ONCE per
+ * distinct stamp, not once per spin. Later spins on the same stamp re-check
+ * only the cheap `pidAlive` signal: a holder that exits mid-wait is noticed
+ * within a spin, and a recycled pid cannot fool this because the stamp bytes
+ * (pid + token) would differ and be judged afresh.
+ */
+const verdicts = new Map();
+/** The lock file beside a store file. */
+export function storeLockPath(file) {
+    return `${path.resolve(file)}.lock`;
+}
+/** Thrown by {@link assertStoreLockHeld} when the lock we hold is gone or is
+ * someone else's; caught by {@link withStoreLock}, which retries `fn`. */
+export class StoreLockLostError extends Error {
+    constructor(file) {
+        super(`store lock for ${file} was taken by another process before the write committed`);
+        this.name = "StoreLockLostError";
+    }
+}
+/** Locks this process currently holds, by resolved store path. */
+const held = new Map();
+/**
+ * Run `fn` holding the exclusive lock for `file`. Re-entrant within the
+ * process for the same file (a nested call runs inline). Throws
+ * `CRUXY_E_STORE_LOCKED` if another live process holds it past the deadline;
+ * everything `fn` throws propagates, after the lock is released.
+ */
+export function withStoreLock(file, fn) {
+    const key = path.resolve(file);
+    const nested = held.get(key);
+    if (nested) {
+        nested.depth++;
+        try {
+            return fn();
+        }
+        finally {
+            nested.depth--;
+        }
+    }
+    const lock = storeLockPath(key);
+    mkdirSync(path.dirname(key), { recursive: true });
+    for (let attempt = 0;; attempt++) {
+        const ino = acquire(lock, key);
+        held.set(key, { ino, depth: 1 });
+        try {
+            return fn();
+        }
+        catch (err) {
+            if (err instanceof StoreLockLostError &&
+                attempt < MAX_LOST_LOCK_RETRIES) {
+                continue; // nothing was committed; take the lock again and redo from a fresh load
+            }
+            throw err;
+        }
+        finally {
+            held.delete(key);
+            release(lock, ino);
+        }
+    }
+}
+/**
+ * For a store's write path: verify, right before the rename that commits the
+ * document, that the lock this process took for `file` is still the one on
+ * disk. No-op when the caller did not lock (a direct `saveScope` in a test,
+ * or `clear`'s deliberate recovery path).
+ */
+export function assertStoreLockHeld(file) {
+    const key = path.resolve(file);
+    const h = held.get(key);
+    if (!h)
+        return;
+    let ino;
+    try {
+        ino = statSync(storeLockPath(key), { bigint: true }).ino;
+    }
+    catch {
+        throw new StoreLockLostError(key);
+    }
+    if (ino !== h.ino)
+        throw new StoreLockLostError(key);
+}
+// ── internals ─────────────────────────────────────────────────────────────────
+function acquire(lock, file) {
+    const since = performance.now() - (lastReleased.get(lock) ?? -Infinity);
+    if (since < SPIN_MS * 2)
+        sleep(SPIN_MS);
+    const started = performance.now();
+    let deadline = started + STORE_LOCK_WAIT_MS;
+    let holder = null;
+    /** The last non-EEXIST create error, thrown as itself if nobody was ever
+     * seen holding the lock — a real permission problem, not contention. */
+    let lastDenied = null;
+    for (;;) {
+        try {
+            writeFileSync(lock, JSON.stringify(selfStamp()), {
+                flag: "wx",
+                mode: 0o600,
+            });
+            return statSync(lock, { bigint: true }).ino;
+        }
+        catch (err) {
+            if (!isContention(err))
+                throw err;
+            if (err.code !== "EEXIST")
+                lastDenied = err;
+        }
+        // "gone": released (or delete-pending) between our open and our read;
+        // retry the create, but through the deadline check below — a permanent
+        // EPERM must not spin forever.
+        const read = readStamp(lock);
+        if (read !== "gone" && read !== "unreadable") {
+            const { stamp, raw } = read;
+            // `self` here is our own pid and token with no entry in `held`: a lock
+            // this process created and lost track of (it cannot be a live holder —
+            // we are single-threaded and not inside `withStoreLock` for this file).
+            // Treated as stale, like any other dead stamp.
+            let verdict = verdicts.get(raw);
+            if (verdict === undefined) {
+                // The OS lookup behind `describeOwner` is not waiting time: it is one
+                // `ps` on darwin, and a PowerShell call on win32 that can itself
+                // outlast the whole budget. Push the deadline out by what it took.
+                const t0 = performance.now();
+                verdict = describeOwner(stamp);
+                deadline += performance.now() - t0;
+                verdicts.set(raw, verdict);
+            }
+            else if (verdict === "live" && !pidAlive(stamp.pid)) {
+                verdict = "stale";
+                verdicts.set(raw, verdict);
+            }
+            if (verdict !== "live") {
+                breakLock(lock);
+                continue;
+            }
+            holder = stamp;
+        }
+        const now = performance.now();
+        if (now >= deadline) {
+            if (holder === null && lastDenied !== null)
+                throw lastDenied;
+            throw storeLocked(file, lock, holder);
+        }
+        if (now - started >= BUSY_POLL_MS)
+            sleep(SPIN_MS * (0.5 + Math.random()));
+    }
+}
+/** How long {@link release} keeps retrying an unlink that win32 refuses
+ * while a contender holds the file open. A lock that a live holder failed to
+ * remove is refused by every other process for as long as this one runs, so
+ * the retry is worth far more than it costs. */
+const RELEASE_RETRY_MS = 100;
+function release(lock, ino) {
+    const until = performance.now() + RELEASE_RETRY_MS;
+    for (;;) {
+        try {
+            // Only remove the lock if it is still ours — never a successor's.
+            if (statSync(lock, { bigint: true }).ino === ino)
+                unlinkSync(lock);
+            break;
+        }
+        catch (err) {
+            // ENOENT: already gone (broken as stale by a contender, or never
+            // landed). A contention code: a reader has it open (win32); retry.
+            if (!isContention(err) || performance.now() >= until)
+                break;
+            sleep(SPIN_MS);
+        }
+    }
+    lastReleased.set(lock, performance.now());
+}
+function breakLock(lock) {
+    try {
+        unlinkSync(lock);
+    }
+    catch {
+        // Someone else broke it first; the next `wx` attempt decides.
+    }
+}
+function readStamp(lock) {
+    let raw;
+    try {
+        raw = readFileSync(lock, "utf8");
+    }
+    catch (err) {
+        // ENOENT: released before we read. A contention code: delete-pending on
+        // win32, which is the same thing a few microseconds earlier.
+        const code = err.code;
+        return code === "ENOENT" || isContention(err) ? "gone" : "unreadable";
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.pid !== "number" ||
+            typeof parsed.token !== "string" ||
+            typeof parsed.startedAt !== "string") {
+            return "unreadable";
+        }
+        return {
+            stamp: {
+                pid: parsed.pid,
+                token: parsed.token,
+                startedAt: parsed.startedAt,
+            },
+            raw,
+        };
+    }
+    catch {
+        return "unreadable";
+    }
+}
+function sleep(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cruxy/cli",
-  "version": "1.11.4",
+  "version": "1.11.6",
   "description": "an agentic coding CLI",
   "type": "module",
   "bin": {