@cruxy/cli 1.11.3 → 1.11.5

package/dist/cli/commands/run.js

@@ -359,15 +359,16 @@ export async function executeRun(promptParts, opts) {
     }) ?? undefined;
     // The TUI sidebar lists the same tree the `--resume` picker reads (P2).
     //
-    // A FRESH SESSION IS NOT IN ITS OWN SIDEBAR UNTIL TURN 1 (#257). This used to
-    // be populated after the log was opened precisely so the running session
-    // listed itself; the meta line is buffered now, so there is nothing on disk
-    // to list until something is said. That is the more honest reading — the
-    // sidebar and the `--resume` picker show the same tree, and a session with no
-    // conversation in it is not one the picker would offer either. The active id
-    // is still passed, so the row marks itself the moment it appears.
+    // A PROBE, NOT A LIST (cli#300). A fresh session is not on disk until its
+    // first turn — the meta line is buffered (#257) — so a list read here could
+    // never contain the session the user is in, and with no later caller the
+    // sidebar stayed exactly as stale as that first read for the whole run. The
+    // renderer re-runs this probe after every turn, off its paint path, so the
+    // running session appears the moment it lands and the tree keeps following
+    // what this and any other cruxy write. The active id marks the row when it
+    // shows; the sidebar and the picker still read the same ten.
     if (renderer instanceof TuiRenderer) {
-        renderer.setSessions(listSessions(primaryRoot, SIDEBAR_SESSIONS), sessionId);
+        renderer.attachSessions(() => listSessions(primaryRoot, SIDEBAR_SESSIONS), sessionId);
     }
     // ONE key reader for the whole TUI session (P5): the input loop and the
     // approval prompt's modal both lease it, so the two can never be live on

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/dist/tui/renderer.js

@@ -219,14 +219,21 @@ export class TuiRenderer {
     /**
      * Saved sessions shown in the sidebar (P2), and which one is running.
      *
-     * Populated only by {@link setSessions}, never at construction. The running
-     * session has to be listed, and its meta line does not exist until the
-     * session log is open — which happens after the renderer is built. A
-     * constructor argument could therefore only ever carry the list from BEFORE
-     * this run, i.e. a sidebar missing the very session the user is in.
+     * Populated by {@link setSessions} or by the probe {@link attachSessions}
+     * installs, never at construction: the list is read from disk, the renderer
+     * is built before the session log exists, and a constructor argument could
+     * only ever carry the tree from BEFORE this run.
+     *
+     * THE LIST IS RE-READ AFTER EVERY TURN (cli#300). It used to be read once at
+     * startup, and since a fresh session's meta line is buffered until its first
+     * turn (#257), that one read could never include the session the user was
+     * in — the row the active id exists to mark. Re-probing on `endTurn`, the
+     * same trigger the git cache and the views use, is what lets it appear.
      */
     sessions = [];
     activeSessionId;
+    /** Re-reads the session tree; installed by {@link attachSessions}. */
+    sessionsProbe;
     constructor(caps, out, opts = {}) {
         this.caps = caps;
         this.out = out;
@@ -573,9 +580,9 @@ export class TuiRenderer {
     }
     // ── app-owned surfaces ────────────────────────────────────────────────────
     /**
-     * Replace the sidebar's session list (P2). Called once the session log is
-     * open, so the running session is itself listed; a live refresh later (P3)
-     * is the same call.
+     * Replace the sidebar's session list (P2) with one the caller already holds.
+     * The primitive {@link attachSessions} and {@link refreshSessions} both land
+     * on; a caller with no probe to install (tests, a static list) uses it alone.
      */
     setSessions(sessions, activeSessionId) {
         if (this.closed)
@@ -584,6 +591,46 @@ export class TuiRenderer {
         this.activeSessionId = activeSessionId;
         this.schedulePaint();
     }
+    /**
+     * Install the probe that reads the session tree, and read it once now
+     * (cli#300). From here on {@link endTurn} re-runs it, so the list follows the
+     * tree as this and other cruxys write to it — and so the running session
+     * shows up the moment its first turn puts it on disk.
+     *
+     * THE PROBE NEVER RUNS ON THE PAINT PATH. It reads one meta line per file
+     * for at most ten files, which is cheap, and cheap is not the discipline:
+     * `viewModel` reads `this.sessions` and nothing else, exactly as it reads
+     * the git cache's last answer rather than running `git status`. A paint
+     * that touched the disk would do so on every streaming frame.
+     */
+    attachSessions(probe, activeSessionId) {
+        if (this.closed)
+            return;
+        this.sessionsProbe = probe;
+        this.activeSessionId = activeSessionId;
+        this.refreshSessions();
+    }
+    /**
+     * Re-read the session tree through the installed probe, off the paint path,
+     * and repaint if it answered. A probe that throws leaves the last list
+     * standing: the sidebar is a status surface, and a transient read error must
+     * never blank it or take the shell down. No probe → nothing to do, and the
+     * list set by {@link setSessions} stays as it was.
+     */
+    refreshSessions() {
+        const probe = this.sessionsProbe;
+        if (probe === undefined || this.closed)
+            return;
+        let sessions;
+        try {
+            sessions = probe();
+        }
+        catch {
+            return;
+        }
+        this.sessions = sessions;
+        this.schedulePaint();
+    }
     /** Set the input line's rendered text (prompt + buffer + caret). */
     setInput(line) {
         if (this.closed)
@@ -865,6 +912,10 @@ export class TuiRenderer {
         this.refreshGit();
         this.refreshLimits();
         this.refreshViews();
+        // AFTER the turn's final paint, like the three above: the frame that
+        // closes the turn is composed from state already in hand, and the tree
+        // read lands in the next scheduled paint rather than delaying this one.
+        this.refreshSessions();
     }
     /**
      * REPAINT the headroom panel once the turn's reading lands (P9) — no longer

package/package.json

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