@cruxy/cli 1.11.4 → 1.11.5

package/dist/errors/constructors.js

@@ -1247,6 +1247,45 @@ 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 },
+    });
+}
 // ── 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,11 @@ 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",
     // 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 +393,7 @@ const EXIT_CODES = {
     [ErrorCode.MemoryInvalid]: 14,
     [ErrorCode.MemoryUntrusted]: 14,
     [ErrorCode.MemorySecret]: 14,
+    [ErrorCode.MemoryStoreUnloadable]: 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,6 @@
 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 { buildRecallBlock } from "./recall.js";
 import { containsSecret } from "./secrets.js";
 import { defaultMemorySources, loadScope, saveScope, } from "./store.js";
@@ -78,7 +78,7 @@ export class MemoryService {
             createdAt: this.now(),
         };
         const file = this.sources[scope];
-        const existing = loadScope(file, scope).entries;
+        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);
@@ -113,7 +113,7 @@ export class MemoryService {
     forget(id) {
         for (const scope of ["user", "project"]) {
             const file = this.sources[scope];
-            const entries = loadScope(file, scope).entries;
+            const entries = this.loadForWrite(file, scope).entries;
             const kept = entries.filter((e) => e.id !== id);
             if (kept.length === entries.length)
                 continue;
@@ -131,6 +131,10 @@ export class MemoryService {
         let removed = 0;
         for (const s of scopes) {
             const file = this.sources[s];
+            // 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);
@@ -150,10 +154,29 @@ export class MemoryService {
      * become recallable.
      */
     trustProject() {
-        const entries = loadScope(this.sources.project, "project").entries;
+        // 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.
+        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({
             root: this.cwd,

package/dist/memory/store.js

@@ -1,4 +1,4 @@
-import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { chmodSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
 import path from "node:path";
 import { globalDir } from "../config/paths.js";
 import { GLOBAL_DIR_NAME, MEMORY_DIR_NAME, MEMORY_FILE_NAME, } from "../constants.js";
@@ -13,46 +13,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 +100,72 @@ 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), the `credentials.ts`
+ * pattern. 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);
+    const tmp = `${file}.tmp-${process.pid}`;
+    try {
+        writeFileSync(tmp, body, mode !== undefined ? { mode } : undefined);
+        // `writeFileSync`'s mode is masked by the umask and applies only on create;
+        // chmod pins the exact bits on the temp BEFORE it becomes the file.
+        if (mode !== undefined)
+            chmodSync(tmp, mode);
+        renameSync(tmp, file); // atomic replace; the mode moves with the inode
+    }
+    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 umask, as before). */
+function existingMode(file) {
+    try {
+        return statSync(file).mode & 0o777;
+    }
+    catch {
+        return undefined;
+    }
 }

package/package.json

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