akm-cli 0.9.0 → 0.9.1-beta.2

package/dist/core/subprocess.js

@@ -12,8 +12,10 @@
  *     kill reaps the whole descendant tree — no orphaned children.
  *   • A SIGTERM→SIGKILL kill ladder on timeout/abort — a child that ignores
  *     SIGTERM is force-killed after a grace period instead of wedging forever.
- *   • Bounded output capture ({@link readStream}) that cannot block past the
- *     wall budget even when the child leaves a pipe endpoint open.
+ *   • Time-bounded output capture ({@link readStream}) that cannot block past
+ *     the wall budget even when the child leaves a pipe endpoint open, plus an
+ *     OPT-IN RETENTION cap (`maxOutputBytes`); see {@link readStream} for what
+ *     the cap does and does not bound.
  *   • Injectable `spawnFn`/`setTimeoutFn`/`clearTimeoutFn` seams so callers
  *     can drive the machinery deterministically in tests.
  *
@@ -70,33 +72,115 @@ export function scheduleKillLadder(proc, opts) {
     if (typeof sigkillTimer !== "number")
         sigkillTimer.unref?.();
 }
+/**
+ * The joined, human-readable reason ONE managed run's capture is incomplete, or
+ * `undefined` when both pipes drained cleanly.
+ *
+ * Shared so every caller that promotes captured output treats an incomplete
+ * capture the same way. A pipe that errored, or that hit the stream-drain
+ * timeout because a background descendant kept the fd open after the leader
+ * exited 0, yields a PARTIAL string — and a caller that reads only `exitCode`
+ * would promote that partial as if it were the command's whole output.
+ * `maxBytes` overflow is deliberately NOT reported here: it is a distinct,
+ * caller-classified condition (see {@link StreamReadResult.overflowed}), not a
+ * drain malfunction.
+ */
+export function streamCaptureFailure(stdout, stderr) {
+    const failures = [];
+    if (stdout.error)
+        failures.push(`stdout read failed: ${errorText(stdout.error)}`);
+    if (stderr.error)
+        failures.push(`stderr read failed: ${errorText(stderr.error)}`);
+    if (stdout.timedOut)
+        failures.push("stdout drain timed out");
+    if (stderr.timedOut)
+        failures.push("stderr drain timed out");
+    return failures.length === 0 ? undefined : failures.join("; ");
+}
+function errorText(error) {
+    return error instanceof Error ? error.message : String(error);
+}
 const STREAM_READ_TIMEOUT = Symbol("stream-read-timeout");
+/**
+ * Index at or before `limit` where a UTF-8 CHARACTER starts, so a retention cut
+ * never lands inside a multi-byte sequence. Continuation bytes are `10xxxxxx`;
+ * a well-formed sequence has at most three of them, so this walks back at most
+ * three positions.
+ */
+function utf8BoundaryAtOrBefore(value, limit) {
+    let cut = limit;
+    while (cut > 0 && (value[cut] & 0xc0) === 0x80)
+        cut--;
+    return cut;
+}
 /**
  * Drain a readable stream to text, optionally racing each read against a
  * timeout so a process that is killed via SIGTERM/SIGKILL but whose pipe
  * endpoints stay open (e.g. background threads still holding the fd) cannot
  * block the caller indefinitely. On timeout we return whatever was decoded
  * before the pipe stopped draining.
+ *
+ * ## The `maxBytes` cap bounds MEMORY, not the child
+ *
+ * The drain ALWAYS runs to the end of the stream. `maxBytes` caps only what is
+ * RETAINED: once the cap is reached the loop keeps calling `reader.read()` and
+ * throws the bytes away. That is what makes the cap safe to impose on a
+ * process that is still running — a reader that stopped pulling would fill the
+ * pipe buffer and BLOCK the child on its next write, turning "the output got
+ * long" into "the command hangs until the wall timeout". Draining and
+ * discarding costs nothing but the reads, and the child finishes normally.
  */
 export async function readStream(stream, opts) {
     if (!stream)
-        return { text: "", timedOut: false };
+        return { text: "", timedOut: false, overflowed: false, bytesRead: 0, retainedBytes: 0 };
     const reader = stream.getReader();
     const decoder = new TextDecoder();
+    const maxBytes = opts?.maxBytes;
     let text = "";
+    let bytesRead = 0;
+    let retainedBytes = 0;
+    let overflowed = false;
+    /**
+     * Common per-chunk accumulate. Uncapped it appends everything. Capped, it
+     * appends until the cap and then only COUNTS — the caller's loop keeps reading
+     * either way, which is the whole point.
+     */
+    const absorb = (value) => {
+        bytesRead += value.byteLength;
+        if (maxBytes === undefined) {
+            retainedBytes += value.byteLength;
+            text += decoder.decode(value, { stream: true });
+            return;
+        }
+        // Already past the cap: discard. Never resume retaining — a gap in the
+        // middle would splice two disjoint regions into one string.
+        if (overflowed)
+            return;
+        if (retainedBytes + value.byteLength <= maxBytes) {
+            retainedBytes += value.byteLength;
+            text += decoder.decode(value, { stream: true });
+            return;
+        }
+        overflowed = true;
+        const keep = utf8BoundaryAtOrBefore(value, maxBytes - retainedBytes);
+        if (keep > 0) {
+            retainedBytes += keep;
+            text += decoder.decode(value.subarray(0, keep), { stream: true });
+        }
+    };
     if (!opts?.timeoutMs) {
         try {
             while (true) {
                 const chunk = await reader.read();
                 if (chunk.done)
                     break;
-                text += decoder.decode(chunk.value, { stream: true });
+                absorb(chunk.value);
             }
             text += decoder.decode();
-            return { text, timedOut: false };
+            return { text, timedOut: false, overflowed, bytesRead, retainedBytes };
         }
         catch (error) {
-            return { text, timedOut: false, error };
+            return { text, timedOut: false, error, overflowed, bytesRead, retainedBytes };
         }
         finally {
             try {
@@ -109,33 +193,46 @@ export async function readStream(stream, opts) {
     }
     const setTimeoutImpl = opts.setTimeoutFn ?? setTimeout;
     const clearTimeoutImpl = opts.clearTimeoutFn ?? clearTimeout;
+    const timeoutMs = opts.timeoutMs;
     let timer;
+    let drained = false;
     const timeoutPromise = new Promise((resolve) => {
-        timer = setTimeoutImpl(() => {
-            timer = undefined;
-            resolve(STREAM_READ_TIMEOUT);
-        }, opts.timeoutMs);
-        if (typeof timer !== "number")
-            timer.unref?.();
+        const arm = () => {
+            // The drain already finished while the deadline was still waiting to be
+            // armed; a timer started now would belong to nobody.
+            if (drained)
+                return;
+            timer = setTimeoutImpl(() => {
+                timer = undefined;
+                resolve(STREAM_READ_TIMEOUT);
+            }, timeoutMs);
+            if (typeof timer !== "number")
+                timer.unref?.();
+        };
+        if (opts.armTimeoutAfter)
+            void opts.armTimeoutAfter.then(arm, arm);
+        else
+            arm();
     });
     try {
         while (true) {
             const chunk = await Promise.race([reader.read(), timeoutPromise]);
             if (chunk === STREAM_READ_TIMEOUT) {
                 void reader.cancel().catch(() => { });
-                return { text, timedOut: true };
+                return { text, timedOut: true, overflowed, bytesRead, retainedBytes };
             }
             if (chunk.done)
                 break;
-            text += decoder.decode(chunk.value, { stream: true });
+            absorb(chunk.value);
         }
         text += decoder.decode();
-        return { text, timedOut: false };
+        return { text, timedOut: false, overflowed, bytesRead, retainedBytes };
     }
     catch (error) {
-        return { text, timedOut: false, error };
+        return { text, timedOut: false, error, overflowed, bytesRead, retainedBytes };
     }
     finally {
+        drained = true;
         if (timer !== undefined) {
             clearTimeoutImpl(timer);
         }
@@ -147,8 +244,29 @@ export async function readStream(stream, opts) {
         }
     }
 }
-const EMPTY_READ = { text: "", timedOut: false };
+const EMPTY_READ = {
+    text: "",
+    timedOut: false,
+    overflowed: false,
+    bytesRead: 0,
+    retainedBytes: 0,
+};
+/**
+ * Drain deadline for a run with no wall budget, counted from the child's EXIT
+ * (never from capture — see {@link runManagedSubprocess}). It bounds only the
+ * window in which a descendant can keep an inherited pipe open after the leader
+ * is gone, so it can be generous without ever capping the run itself.
+ */
 const UNBOUNDED_STREAM_READ_SAFETY_MS = 60 * 60 * 1000;
+/**
+ * Drain deadline for a run WITH a wall budget, counted from the moment the
+ * pipe's owner left — the child exited, or (a child that survived its own kill
+ * ladder) the budget expired. Anything still holding the fd open then is a
+ * background descendant, not the command, so this is the same 2 s the old
+ * capture-anchored deadline allowed past the budget; only its starting point
+ * moved earlier.
+ */
+const POST_EXIT_STREAM_DRAIN_GRACE_MS = 2_000;
 function toError(err) {
     return err instanceof Error ? err : new Error(String(err));
 }
@@ -207,8 +325,18 @@ export async function runManagedSubprocess(cmd, opts) {
     // Skipped entirely when timeoutMs is null.
     let timedOut = false;
     let timer;
+    // Settles when a bounded run's wall budget expires — the second way (after
+    // the child's own exit) a captured pipe can stop belonging to a live command.
+    // See the drain-deadline note below.
+    let onBudgetExpiry;
+    const budgetExpired = capture && timeoutMs !== null
+        ? new Promise((resolve) => {
+            onBudgetExpiry = resolve;
+        })
+        : undefined;
     if (timeoutMs !== null) {
         timer = setTimeoutImpl(() => {
+            onBudgetExpiry?.();
             scheduleKillLadder(proc, {
                 onKill: () => {
                     timedOut = true;
@@ -239,25 +367,33 @@ export async function runManagedSubprocess(cmd, opts) {
         else
             abortSignal.addEventListener("abort", onAbort, { once: true });
     }
-    // Stream-drain timeout: the wall budget plus a 2 s grace, or a one-hour
-    // safety bound when execution itself is unbounded. This timer starts with
-    // capture, so the null-timeout path must not impose a short hidden deadline
-    // on an otherwise healthy long-running process.
-    const streamDrainTimeoutMs = timeoutMs !== null ? timeoutMs + 2_000 : UNBOUNDED_STREAM_READ_SAFETY_MS;
-    const stdoutPromise = capture
-        ? readStream(proc.stdout ?? null, {
-            timeoutMs: streamDrainTimeoutMs,
-            setTimeoutFn: setTimeoutImpl,
-            clearTimeoutFn: clearTimeoutImpl,
-        })
-        : Promise.resolve(EMPTY_READ);
-    const stderrPromise = capture
-        ? readStream(proc.stderr ?? null, {
-            timeoutMs: streamDrainTimeoutMs,
-            setTimeoutFn: setTimeoutImpl,
-            clearTimeoutFn: clearTimeoutImpl,
-        })
-        : Promise.resolve(EMPTY_READ);
+    // Stream-drain timeout: a short grace once nothing living owns the pipe any
+    // more, or a one-hour safety bound when execution itself is unbounded.
+    //
+    // Neither is armed while the command is still running: every byte up to then
+    // is a live process's, and cancelling the reader would discard the output of
+    // work that is still going. What ends that ownership is where the two cases
+    // differ. Unbounded, the caller asked for NO cap on the run, so only the
+    // child's own exit can end it. Bounded, the wall budget ends it too — a child
+    // that outlived its own kill ladder is not something akm can keep waiting on
+    // — which leaves the SAME budget + grace ceiling as before for a command that
+    // really did spend its whole budget, and cuts the common case that used to
+    // stall: a leader exiting in milliseconds no longer holds the drain (and with
+    // it the unit, and with it a fan-out slot) open for a budget it never came
+    // close to spending.
+    const streamDrainTimeoutMs = timeoutMs !== null ? POST_EXIT_STREAM_DRAIN_GRACE_MS : UNBOUNDED_STREAM_READ_SAFETY_MS;
+    // Settles on a rejected `proc.exited` too: either way the child is gone.
+    const childSettled = capture ? proc.exited.catch(() => undefined) : undefined;
+    const pipeOwnerGone = childSettled && budgetExpired ? Promise.race([childSettled, budgetExpired]) : childSettled;
+    const readOpts = {
+        timeoutMs: streamDrainTimeoutMs,
+        setTimeoutFn: setTimeoutImpl,
+        clearTimeoutFn: clearTimeoutImpl,
+        ...(pipeOwnerGone ? { armTimeoutAfter: pipeOwnerGone } : {}),
+        ...(opts.maxOutputBytes !== undefined ? { maxBytes: opts.maxOutputBytes } : {}),
+    };
+    const stdoutPromise = capture ? readStream(proc.stdout ?? null, readOpts) : Promise.resolve(EMPTY_READ);
+    const stderrPromise = capture ? readStream(proc.stderr ?? null, readOpts) : Promise.resolve(EMPTY_READ);
     // Optional stdin payload (captured mode only). Race the write/close against
     // proc.exited so a child that never drains stdin cannot pin us past the
     // timeout.
@@ -301,5 +437,13 @@ export async function runManagedSubprocess(cmd, opts) {
     clearTimeoutImpl(timer);
     abortSignal?.removeEventListener("abort", onAbort);
     const [stdoutRead, stderrRead] = await Promise.all([stdoutPromise, stderrPromise]);
-    return { exitCode, stdout: stdoutRead.text, stderr: stderrRead.text, timedOut, aborted, stdoutRead, stderrRead };
+    return {
+        exitCode,
+        stdout: stdoutRead.text,
+        stderr: stderrRead.text,
+        timedOut,
+        aborted,
+        stdoutRead,
+        stderrRead,
+    };
 }

package/dist/core/write-provenance.js

@@ -0,0 +1,85 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * Run-scoped write provenance (#652).
+ *
+ * # Why this exists
+ *
+ * `akm improve`'s end-of-run auto-sync used to infer "what did this run write?"
+ * by diffing two Git dirty-path snapshots: everything dirty at end-of-run minus
+ * everything dirty when the run acquired its lock. That inference is wrong in
+ * both directions:
+ *
+ *   - an unrelated managed-dir edit made by a human DURING a long run appears in
+ *     the end-of-run diff and gets swept into akm's commit;
+ *   - a path that was ALREADY dirty when the run started and is then rewritten by
+ *     the run is subtracted out and never committed.
+ *
+ * The journal below replaces the inference with a record. Every akm write path
+ * that mutates a file on disk calls {@link recordWrittenPath}; a run opens a
+ * journal for its duration and reads back the exact set of paths it touched.
+ *
+ * # Contract
+ *
+ *   - A *write* and a *removal* are recorded identically — the journal records
+ *     "this run mutated this path", not what the mutation was. The final on-disk
+ *     state is what gets staged (`git add -A -- <path>` stages a deletion just as
+ *     happily as a modification), so a path written and then reverted, purged, or
+ *     rolled back needs no special handling: it is journaled once and the stager
+ *     sees whatever survived.
+ *   - Recording is a no-op when no journal is open, so non-improve command paths
+ *     pay nothing but a `Set.size` check.
+ *   - Journals nest: every open journal observes every recorded path. Concurrent
+ *     in-process runs (tests) therefore over-report rather than cross-attribute
+ *     writes to the wrong run, which is the safe direction — over-reporting stages
+ *     a path that has no diff, under-reporting loses a write.
+ *   - Nothing here throws. A provenance failure must never break a write.
+ */
+import path from "node:path";
+const activeJournals = new Set();
+/** Open a journal. The caller MUST close it (`end()`) in a `finally`. */
+export function beginWriteProvenance() {
+    const state = { touched: new Set() };
+    activeJournals.add(state);
+    const snapshot = () => [...state.touched].sort();
+    return {
+        writtenPaths: snapshot,
+        end: () => {
+            activeJournals.delete(state);
+            return snapshot();
+        },
+    };
+}
+/** True while at least one journal is open. */
+export function isWriteProvenanceActive() {
+    return activeJournals.size > 0;
+}
+/**
+ * Record that the current run mutated `filePath` (write, create, rename, or
+ * delete). No-op when no journal is open. Never throws.
+ */
+export function recordWrittenPath(filePath) {
+    if (activeJournals.size === 0 || !filePath)
+        return;
+    let absolute;
+    try {
+        absolute = path.resolve(filePath);
+    }
+    catch {
+        return;
+    }
+    for (const journal of activeJournals)
+        journal.touched.add(absolute);
+}
+/**
+ * Normalize an absolute journaled path against `root`: POSIX-relative when the
+ * path is inside `root`, `undefined` otherwise (the caller decides whether an
+ * out-of-root write is reportable or, for staging, simply out of scope).
+ */
+export function relativeWrittenPath(root, absolutePath) {
+    const relative = path.relative(root, absolutePath).replaceAll(path.sep, "/");
+    if (!relative || relative === ".." || relative.startsWith("../") || path.isAbsolute(relative))
+        return undefined;
+    return relative;
+}

package/dist/core/write-source.js

@@ -33,11 +33,12 @@ import { ensureAkmMarkdownType } from "./asset/akm-markdown.js";
 import { assetPathForName, stashDirFor } from "./asset/asset-placement.js";
 import { conceptIdFromTypeName, displayRef } from "./asset/resolve-ref.js";
 import { deriveBundleId } from "./bundle-id.js";
-import { isWithin, resolveStashDir } from "./common.js";
+import { existingFileMode, isWithin, resolveStashDir, writeFileAtomic } from "./common.js";
 import { resolveConfiguredSources } from "./config/config.js";
 import { ConfigError, UsageError } from "./errors.js";
 import { sanitizeCommitMessage } from "./git-message.js";
 import { warn } from "./warn.js";
+import { recordWrittenPath } from "./write-provenance.js";
 /**
  * Source kinds that the loader is allowed to mark `writable: true`. Anything
  * else is rejected at config load (per locked decision 4) — see
@@ -332,8 +333,15 @@ export async function writeAssetToSource(source, config, ref, content) {
     const preflight = preflightGitPathMutation(source, filePath);
     try {
         fs.mkdirSync(path.dirname(filePath), { recursive: true });
-        fs.writeFileSync(filePath, normalized, "utf8");
+        // Atomic: truncate-and-rewrite left a window in which a crash, a full disk,
+        // or a concurrent reader saw a half-written or empty asset — destroying user
+        // content that was fine a moment earlier. writeFileAtomic writes a sibling
+        // temp file, fdatasyncs it, and renames over the target.
+        writeFileAtomic(filePath, normalized, existingFileMode(filePath));
         recordWriteTargetPath(source, filePath);
+        // #652: run-scoped write provenance — the canonical asset write is the
+        // single largest contributor to an improve run's written-path set.
+        recordWrittenPath(filePath);
     }
     catch (error) {
         discardEmptyGitPreflight(preflight);
@@ -367,6 +375,9 @@ export async function deleteAssetFromSource(source, config, ref) {
     try {
         fs.unlinkSync(filePath);
         recordWriteTargetPath(source, filePath);
+        // #652: a removal is journaled exactly like a write — the stager stages the
+        // final on-disk state, so a deleted path lands as a staged deletion.
+        recordWrittenPath(filePath);
     }
     catch (error) {
         discardEmptyGitPreflight(preflight);
@@ -996,11 +1007,31 @@ function ensureWritable(source, config) {
         throw new UsageError(`Source "${source.name}" is not writable. Set \`writable: true\` on the source config entry to enable writes.`, "INVALID_FLAG_VALUE");
     }
 }
+/**
+ * MS-DOS device names Windows still reserves in every directory, with or
+ * without an extension (CON, PRN, AUX, NUL, COM1-9, LPT1-9).
+ */
+const WINDOWS_RESERVED_DEVICE_NAMES = new Set([
+    "con",
+    "prn",
+    "aux",
+    "nul",
+    ...Array.from({ length: 9 }, (_, i) => `com${i + 1}`),
+    ...Array.from({ length: 9 }, (_, i) => `lpt${i + 1}`),
+]);
 function resolveAssetFilePath(source, ref) {
     const basename = path.posix.basename(ref.name.replaceAll("\\", "/")).replace(/\.md$/i, "").toLowerCase();
     if (basename === "index" || basename === "log") {
         throw new UsageError(`Reserved concept name "${basename}" cannot be written.`, "INVALID_FLAG_VALUE");
     }
+    // Windows resolves these names as DEVICES no matter the directory or the
+    // extension, so `CON.md` is not a file — a write goes to the console and a
+    // read blocks on console input. Rejected on every platform so a stash stays
+    // portable: an asset authored on Linux must not become unopenable when the
+    // same bundle is used on Windows.
+    if (WINDOWS_RESERVED_DEVICE_NAMES.has(basename)) {
+        throw new UsageError(`Asset name "${basename}" is a reserved Windows device name and cannot be written.`, "INVALID_FLAG_VALUE");
+    }
     const typeDir = stashDirFor(ref.type);
     if (!typeDir) {
         throw new UsageError(`Unknown asset type "${ref.type}". Cannot resolve a write path.`, "INVALID_FLAG_VALUE");

package/dist/indexer/db/graph-db.js

@@ -1,15 +1,19 @@
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
-import fs from "node:fs";
-import { rethrowIfTestIsolationError } from "../../core/errors.js";
+import { rethrowIfDataDirUnreadable, rethrowIfTestIsolationError } from "../../core/errors.js";
+import { isPathAbsent } from "../../core/path-access.js";
 import { getDbPath } from "../../core/paths.js";
 import { closeDatabase, openExistingDatabase } from "../../storage/repositories/index-connection.js";
 function withReadableGraphDb(db, fn) {
     if (db)
         return fn(db);
     const dbPath = getDbPath();
-    if (!fs.existsSync(dbPath))
+    // `GRAPH_DB_MISSING` is the loaders' "nothing extracted yet" sentinel — every
+    // caller below turns it into `null`/`[]`. Reserve it for a genuinely ABSENT
+    // index: an index that exists and cannot be read must reach the caller as the
+    // ConfigError `openExistingDatabase` raises, not as "no graph data" (#791).
+    if (isPathAbsent(dbPath))
         throw new Error("GRAPH_DB_MISSING");
     const opened = openExistingDatabase(dbPath);
     try {
@@ -244,8 +248,11 @@ export function loadGraphFilesOnly(stashPath, db) {
         });
     }
     catch (err) {
-        // Never mask the bun-test isolation guard as "no stored graph files".
+        // Never mask the bun-test isolation guard as "no stored graph files",
+        // and never mask an index we are not allowed to read as one with no
+        // graph in it (#791) — `GRAPH_DB_MISSING` above is the only "absent".
         rethrowIfTestIsolationError(err);
+        rethrowIfDataDirUnreadable(err);
         return [];
     }
 }
@@ -315,8 +322,10 @@ export function loadStoredGraphMeta(stashPath, db) {
         });
     }
     catch (err) {
-        // Never mask the bun-test isolation guard as "no stored graph meta".
+        // Never mask the bun-test isolation guard as "no stored graph meta",
+        // nor an unreadable index as one that simply has no graph (#791).
         rethrowIfTestIsolationError(err);
+        rethrowIfDataDirUnreadable(err);
         return null;
     }
 }
@@ -408,8 +417,10 @@ export function loadStoredGraphSnapshot(stashPath, db) {
         });
     }
     catch (err) {
-        // Never mask the bun-test isolation guard as "no stored graph snapshot".
+        // Never mask the bun-test isolation guard as "no stored graph snapshot",
+        // nor an unreadable index as one that simply has no graph (#791).
         rethrowIfTestIsolationError(err);
+        rethrowIfDataDirUnreadable(err);
         return null;
     }
 }

package/dist/indexer/ensure-index.js

@@ -22,9 +22,10 @@
 import fs from "node:fs";
 import path from "node:path";
 import { placementSpecList } from "../core/asset/asset-placement.js";
+import { classifyPathAccess } from "../core/path-access.js";
 import { getDbPath } from "../core/paths.js";
 import { warn } from "../core/warn.js";
-import { closeDatabase, openExistingDatabase } from "../storage/repositories/index-connection.js";
+import { assertIndexPathReadable, closeDatabase, openExistingDatabase } from "../storage/repositories/index-connection.js";
 import { getEntryCount, getIndexedFilePaths } from "../storage/repositories/index-entries-repository.js";
 import { getMeta } from "../storage/repositories/index-meta-repository.js";
 import { warnOnBundleRenameDrift } from "./bundle-identity-guard.js";
@@ -109,7 +110,11 @@ function hasNewerIndexableFiles(stashDir, builtAt, indexedPaths) {
  */
 export function isIndexStale(stashDir) {
     const dbPath = getDbPath();
-    if (!fs.existsSync(dbPath))
+    // Raises on an index we cannot READ rather than calling it stale — "stale"
+    // sends us into an inline reindex that will fail anyway, and whose failure is
+    // reported as the misleading "proceeding with existing index" (#791).
+    assertIndexPathReadable(dbPath);
+    if (classifyPathAccess(dbPath).access === "absent")
         return true;
     let db;
     try {
@@ -152,8 +157,10 @@ export function isIndexStale(stashDir) {
  * or built for a different stash), so those cases must rebuild inline.
  */
 function indexCanServeStash(stashDir) {
+    // Same rule as isIndexStale: unreadable is an error, not "cannot serve" (#791).
     const dbPath = getDbPath();
-    if (!fs.existsSync(dbPath))
+    assertIndexPathReadable(dbPath);
+    if (classifyPathAccess(dbPath).access === "absent")
         return false;
     let db;
     try {

package/dist/indexer/index-written-assets.js

@@ -22,8 +22,10 @@
 import fs from "node:fs";
 import path from "node:path";
 import { akmAdapter } from "../core/adapter/adapters/akm-adapter.js";
+import { isDataDirUnreadableError } from "../core/errors.js";
+import { isPathAbsent } from "../core/path-access.js";
 import { getDbPath } from "../core/paths.js";
-import { warnVerbose } from "../core/warn.js";
+import { warn, warnVerbose } from "../core/warn.js";
 import { closeDatabase, openExistingDatabase } from "../storage/repositories/index-connection.js";
 import { deleteEntriesByIds, getEntryCount, upsertEntry, upsertWorkflowDocument, } from "../storage/repositories/index-entries-repository.js";
 import { rebuildFts } from "../storage/repositories/index-fts-repository.js";
@@ -57,7 +59,12 @@ export async function indexWrittenAssets(stashDir, filePaths, options = {}) {
     try {
         return await withIndexWriterLease({ purpose: "index-written-assets" }, async () => {
             const dbPath = getDbPath();
-            if (!fs.existsSync(dbPath))
+            // `true` here means "the index is in the state the caller expects" — and
+            // `acceptProposal` advances its journal to `index-finalized` on the
+            // strength of it. Only a genuinely ABSENT index earns that answer: an
+            // index we cannot read has NOT been updated, so it falls through to
+            // `openExistingDatabase` and surfaces as the honest `false` (#791).
+            if (isPathAbsent(dbPath))
                 return true;
             // The full walk never descends into dot-directories (for example `.meta/`)
             // — mirror that dot-segment skip here so this fast path indexes exactly
@@ -146,6 +153,14 @@ export async function indexWrittenAssets(stashDir, filePaths, options = {}) {
         });
     }
     catch (error) {
+        // A permission fault is the one failure the next full index will NOT heal,
+        // so it does not get the verbose-only treatment the other skips do: fail
+        // open (the caller's write still stands) but say so where an operator can
+        // see it (#791).
+        if (isDataDirUnreadableError(error)) {
+            warn(`Write-path index update skipped — ${error.message} The asset will not appear in search until that is fixed.`);
+            return false;
+        }
         warnVerbose("Write-path index update skipped (asset appears after the next full index):", error instanceof Error ? error.message : String(error));
         return false;
     }