akm-cli 0.9.8-beta.1 → 0.9.8-beta.3

package/dist/indexer/indexer.js

@@ -30,7 +30,7 @@ import { deleteStoredGraph } from "./db/graph-db.js";
 import { deriveEntryProvenance, deriveInstallations } from "./installations.js";
 import { indexedPathMatchesOwner, resolveAdapterConceptOwner, } from "./lookup/adapter-concept-owner.js";
 import { generateEmbeddingsForDb } from "./materialize-embeddings.js";
-import { canUseIncrementalSkip, computeDirFingerprint, getCachedZeroRowDirState, getDirIndexState, inferZeroRowReason, } from "./passes/dir-staleness.js";
+import { canUseIncrementalSkip, computeDirFingerprint, getCachedDirState, getDirIndexState, inferZeroRowReason, } from "./passes/dir-staleness.js";
 import { isEnrichmentComplete, isWorkflowSkipWarning } from "./passes/metadata.js";
 import { drainDirDocuments } from "./scan/drain-dir.js";
 import { buildSearchText } from "./search/search-fields.js";
@@ -360,6 +360,19 @@ export function _setIndexTransactionHookForTests(hook) {
 function indexTransactionHook(point) {
     indexTransactionHookForTests?.(point);
 }
+let drainObserverForTests;
+/**
+ * TEST-ONLY. Observe every directory that actually reaches
+ * `drainDirDocuments` — the per-file read/sha256-hash/frontmatter-parse step
+ * (#900) — with the directory path and its walked file count. `undefined`
+ * restores. A directory the pre-drain gate (`getCachedDirState`) skips never
+ * fires this observer, so it is the
+ * seam #900's own tests use to assert an unchanged directory's files are
+ * never read on a no-op incremental run.
+ */
+export function _setDrainObserverForTests(observer) {
+    drainObserverForTests = observer;
+}
 /**
  * Detect an adapter for every resolvable source that does not declare one, and
  * persist each detection into `config.json`.
@@ -883,17 +896,19 @@ async function scanSourceDirs(db, allSourceEntries, isIncremental, builtAtMs, ha
     // Incremental freshness gate shared by both branches: consult the persisted
     // dir state and record either a skip (unchanged + eligible for incremental
     // skip) or a scan record carrying the candidate stash.
-    const recordFreshnessDecision = (dirPath, currentStashDir, stateFiles, stash, hashByFile, conceptIdByFile, indexVariant, forceScan, pruneMissing) => {
-        const previousState = getDirIndexState(db, dirPath, stateFiles, builtAtMs, indexVariant);
+    const recordFreshnessDecision = (dirPath, currentStashDir, stateFiles, fingerprint, stash, hashByFile, conceptIdByFile, indexVariant, forceScan, pruneMissing) => {
+        const previousState = getDirIndexState(db, dirPath, stateFiles, builtAtMs, indexVariant, fingerprint);
         if (isIncremental && !forceScan && !previousState.stale && canUseIncrementalSkip(previousState, priorDirsChanged)) {
             skippedDirs++;
             dirRecords.push({
                 dirPath,
                 currentStashDir,
                 files: stateFiles,
+                fingerprint,
                 stash: null,
                 skip: true,
                 reason: previousState.reason,
+                persistedRowCount: previousState.persistedRowCount,
                 indexVariant,
             });
             reportDirDecision("skip", dirPath, currentStashDir, previousState.reason, previousState.persistedRowCount);
@@ -906,6 +921,7 @@ async function scanSourceDirs(db, allSourceEntries, isIncremental, builtAtMs, ha
             dirPath,
             currentStashDir,
             files: stateFiles,
+            fingerprint,
             stash,
             skip: false,
             reason,
@@ -959,10 +975,13 @@ async function scanSourceDirs(db, allSourceEntries, isIncremental, builtAtMs, ha
                 reportDirDecision("skip", dirPath, currentStashDir, reason);
                 continue;
             }
-            const cachedZeroRowState = isIncremental &&
+            // #900: decide from stat data alone whether the directory can be skipped,
+            // before drainDirDocuments reads, hashes, and parses every file.
+            const fingerprint = computeDirFingerprint(dirPath, indexableFiles, indexVariant);
+            const cachedState = isIncremental &&
                 !forceScan &&
-                getCachedZeroRowDirState(db, dirPath, indexableFiles, builtAtMs, priorDirsChanged, indexVariant);
-            if (cachedZeroRowState) {
+                getCachedDirState(db, dirPath, indexableFiles, builtAtMs, priorDirsChanged, indexVariant, fingerprint);
+            if (cachedState) {
                 skippedDirs++;
                 dirRecords.push({
                     dirPath,
@@ -970,15 +989,16 @@ async function scanSourceDirs(db, allSourceEntries, isIncremental, builtAtMs, ha
                     files: indexableFiles,
                     stash: null,
                     skip: true,
-                    reason: cachedZeroRowState.reason,
+                    reason: cachedState.reason,
                     indexVariant,
                 });
-                reportDirDecision("skip", dirPath, currentStashDir, cachedZeroRowState.reason, cachedZeroRowState.persistedRowCount);
+                reportDirDecision("skip", dirPath, currentStashDir, cachedState.reason, cachedState.persistedRowCount);
                 continue;
             }
             // F4a M-core-2 (the flip): drain the dir's `IndexDocument` stream via the
             // component's dispatched `adapter.recognize` (broken workflows dropped-with-
             // warning at the drain layer) and reconstruct the durable `IndexDocument`s.
+            drainObserverForTests?.(dirPath, ctxs.length);
             const drained = drainDirDocuments(adapter, component, ctxs);
             if (drained.warnings.length)
                 warnings.push(...drained.warnings);
@@ -992,7 +1012,7 @@ async function scanSourceDirs(db, allSourceEntries, isIncremental, builtAtMs, ha
             if (generated.entries.length > 0) {
                 generatedCount += generated.entries.length;
             }
-            recordFreshnessDecision(dirPath, currentStashDir, staleFiles, stash, drained.hashByFile, drained.conceptIdByFile, indexVariant, forceScan, walkComplete);
+            recordFreshnessDecision(dirPath, currentStashDir, staleFiles, fingerprint, stash, drained.hashByFile, drained.conceptIdByFile, indexVariant, forceScan, walkComplete);
         }
     }
     return {
@@ -1089,7 +1109,7 @@ function persistDirRecords(db, dirRecords, doFullDelete, warnings, sourceRoots,
             // tests/integration/indexer/reindex-generation-atomicity.test.ts.
             indexTransactionHook("full-delete-applied");
         }
-        for (const { dirPath, currentStashDir, files, stash, skip, reason, hashByFile, conceptIdByFile, indexVariant, remove, pruneMissing, } of dirRecords) {
+        for (const { dirPath, currentStashDir, files, fingerprint, stash, skip, reason, persistedRowCount, hashByFile, conceptIdByFile, indexVariant, remove, pruneMissing, } of dirRecords) {
             const bundle = bundleByRoot.get(path.resolve(currentStashDir));
             if (!bundle)
                 throw new Error(`Missing bundle provenance for indexed source ${currentStashDir}`);
@@ -1102,14 +1122,11 @@ function persistDirRecords(db, dirRecords, doFullDelete, warnings, sourceRoots,
                 continue;
             }
             if (skip) {
-                if (reason?.kind === "unchanged") {
-                    const fingerprint = computeDirFingerprint(dirPath, files, indexVariant);
-                    upsertIndexDirState(db, {
-                        dirPath,
-                        fileSetHash: fingerprint.fileSetHash,
-                        fileMtimeMaxMs: fingerprint.fileMtimeMaxMs,
-                        reason: reason.kind,
-                    });
+                // "unchanged" is the post-drain verdict: re-persist so the row carries
+                // row_count and the gate skips this directory before draining next
+                // time. "unchanged-precheck" already matched the stored row.
+                if (reason?.kind === "unchanged" && fingerprint) {
+                    upsertIndexDirState(db, { dirPath, ...fingerprint, reason: reason.kind, rowCount: persistedRowCount });
                 }
                 continue;
             }
@@ -1165,7 +1182,7 @@ function persistDirRecords(db, dirRecords, doFullDelete, warnings, sourceRoots,
             if (pruneMissing !== false) {
                 addEntryIds(deletedUsageEntryIds, deleteEntriesByDirExceptRefs(db, dirPath, bundle.bundleId, keptItemRefs, { cleanupUsageEvents: false }));
             }
-            const fingerprint = computeDirFingerprint(dirPath, files, indexVariant);
+            const persistedFingerprint = fingerprint ?? computeDirFingerprint(dirPath, files, indexVariant);
             const persistedReason = persistedRows === 0
                 ? inferZeroRowReason(stash, reason, warnings, dirPath, dedupedRows)
                 : reason?.kind === "full-rebuild"
@@ -1173,9 +1190,13 @@ function persistDirRecords(db, dirRecords, doFullDelete, warnings, sourceRoots,
                     : (reason?.kind ?? "updated");
             upsertIndexDirState(db, {
                 dirPath,
-                fileSetHash: fingerprint.fileSetHash,
-                fileMtimeMaxMs: fingerprint.fileMtimeMaxMs,
+                ...persistedFingerprint,
                 reason: persistedReason,
+                // A directory that lost rows to per-source dedup depends on the
+                // directories persisted before it, not only on its own files, so it
+                // must keep draining every run (as it did before the gate) until a
+                // drain persists it without dedup. NULL keeps the gate closed.
+                rowCount: dedupedRows === 0 ? persistedRows : undefined,
             });
             if (persistedRows === 0) {
                 // Warn only when the dir had files that *could* produce entries (.md or

package/dist/indexer/passes/dir-staleness.js

@@ -10,20 +10,27 @@
  *
  * Two persisted signals back the decision:
  *   1. The `entries` rows already indexed for the directory (`getEntriesByDir`).
- *   2. The `index_dir_state` fingerprint row (`getIndexDirState`), which caches
- *      the file-set hash + max mtime for directories that legitimately produced
- *      zero rows, so they are not rescanned every run.
+ *   2. The `index_dir_state` row (`getIndexDirState`): the fingerprint of the
+ *      directory's walked file set (basename set + max mtime, `computeDirFingerprint`)
+ *      as of its last drain, plus the row count that drain persisted.
  *
- * `computeDirFingerprint` derives the fingerprint (basename set + max mtime)
- * that both the freshness check and the persisted `index_dir_state` row use.
+ * `getCachedDirState` is the pre-drain gate (#900): a directory whose walked
+ * fingerprint still matches its row is skipped before any file is read.
  */
+import { createHash } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
+import { compareCodePoints } from "../../core/common.js";
 import { getEntriesByDir } from "../../storage/repositories/index-entries-repository.js";
 import { getIndexDirState } from "../../storage/repositories/index-meta-repository.js";
-export function getDirIndexState(db, dirPath, files, builtAtMs, indexVariant = "") {
+/**
+ * Post-drain freshness verdict. `files` is the recognized file set the drain
+ * produced (compared against the persisted entries); `fingerprint` is the
+ * walked-set fingerprint compared against the persisted row and defaults to
+ * one computed over `files`.
+ */
+export function getDirIndexState(db, dirPath, files, builtAtMs, indexVariant = "", fingerprint = computeDirFingerprint(dirPath, files, indexVariant)) {
     const prevEntries = getEntriesByDir(db, dirPath);
-    const fingerprint = computeDirFingerprint(dirPath, files, indexVariant);
     if (prevEntries.length > 0) {
         const staleReason = getDirStaleReason(dirPath, files, prevEntries, builtAtMs);
         if (staleReason)
@@ -39,9 +46,7 @@ export function getDirIndexState(db, dirPath, files, builtAtMs, indexVariant = "
         return { stale: false, reason: { kind: "unchanged" }, persistedRowCount: prevEntries.length };
     }
     const cachedState = getIndexDirState(db, dirPath);
-    if (cachedState &&
-        cachedState.fileSetHash === fingerprint.fileSetHash &&
-        cachedState.fileMtimeMaxMs === fingerprint.fileMtimeMaxMs) {
+    if (cachedState && cachedState.fileSetHash === fingerprint.fileSetHash) {
         return {
             stale: false,
             reason: { kind: "cached-zero-row-state", detail: cachedState.reason },
@@ -54,8 +59,21 @@ export function getDirIndexState(db, dirPath, files, builtAtMs, indexVariant = "
         persistedRowCount: 0,
     };
 }
-export function getCachedZeroRowDirState(db, dirPath, files, builtAtMs, priorDirsChanged, indexVariant = "") {
-    const state = getDirIndexState(db, dirPath, files, builtAtMs, indexVariant);
+/**
+ * Pre-drain gate (#900). A directory whose walked-set fingerprint matches its
+ * persisted row cannot recognize differently than last time, so it is skipped
+ * before `drainDirDocuments` reads a single file. A row that recorded a real
+ * generation (`rowCount > 0`) is skipped outright; a zero-row or pre-#900 row
+ * goes through the entries-aware check so the dedup-order guard still applies.
+ */
+export function getCachedDirState(db, dirPath, files, builtAtMs, priorDirsChanged, indexVariant, fingerprint) {
+    const cached = getIndexDirState(db, dirPath);
+    if (!cached || cached.fileSetHash !== fingerprint.fileSetHash)
+        return undefined;
+    if (cached.rowCount !== undefined && cached.rowCount > 0) {
+        return { stale: false, reason: { kind: "unchanged-precheck" }, persistedRowCount: cached.rowCount };
+    }
+    const state = getDirIndexState(db, dirPath, files, builtAtMs, indexVariant, fingerprint);
     if (state.stale || state.reason.kind !== "cached-zero-row-state")
         return undefined;
     if (!canUseIncrementalSkip(state, priorDirsChanged))
@@ -68,21 +86,42 @@ export function canUseIncrementalSkip(state, priorDirsChanged) {
         state.reason.detail === "deduped-zero-row");
 }
 export function computeDirFingerprint(_dirPath, files, indexVariant = "") {
-    const normalizedFiles = [...new Set(files.map((file) => path.basename(file)))].sort();
+    // One `statSync` per file — the same call this function has always made — but
+    // every field it returns that can witness a change is kept, per file, instead
+    // of being collapsed into a single max.
+    //
+    // `Math.max` over mtimes discarded everything except the newest file, so an
+    // edit to any other file landed below the max and was invisible; and mtime
+    // alone is writable by ordinary tooling (`touch -r`, `rsync --times`,
+    // `cp -p`, archive extraction), so a restored timestamp hid an edit outright.
+    // Size catches any length-changing edit; ctime catches the rest, because
+    // utimes(2) cannot hold the inode's change time back.
+    //
+    // This is still a heuristic: ctime also moves on metadata-only changes
+    // (chmod/chown) and after copying a tree, which costs an unnecessary rescan.
+    // That direction is safe — extra work, never stale content.
+    const entries = [];
     let fileMtimeMaxMs = 0;
-    for (const file of files) {
+    for (const file of [...new Set(files)].sort(compareCodePoints)) {
+        const name = path.basename(file);
         try {
-            fileMtimeMaxMs = Math.max(fileMtimeMaxMs, fs.statSync(file).mtimeMs);
+            // `bigint: true` is the same syscall but reports nanoseconds. Millisecond
+            // floats would let an edit made inside the same millisecond as the last
+            // run's stat land on an identical digest.
+            const stat = fs.statSync(file, { bigint: true });
+            fileMtimeMaxMs = Math.max(fileMtimeMaxMs, Number(stat.mtimeMs));
+            entries.push(`${name}\0${stat.size}\0${stat.mtimeNs}\0${stat.ctimeNs}`);
         }
         catch {
-            fileMtimeMaxMs = Number.POSITIVE_INFINITY;
-            break;
+            // Unreadable or vanished: record it as such so the digest differs from
+            // any run where the file could be read, forcing a rescan.
+            entries.push(`${name}\0unreadable`);
         }
     }
-    return {
-        fileSetHash: [indexVariant, ...normalizedFiles].join("\0"),
-        fileMtimeMaxMs,
-    };
+    const digest = createHash("sha256")
+        .update([indexVariant, ...entries].join("\n"), "utf8")
+        .digest("hex");
+    return { fileSetHash: digest, fileMtimeMaxMs };
 }
 function getDirStaleReason(_dirPath, currentFiles, previousEntries, builtAtMs) {
     const prevFileNames = new Set(previousEntries

package/dist/scripts/akm-migrate-node.js

@@ -13104,6 +13104,7 @@ function warn(...args) {
     console.warn(...args);
   }
 }
+var warnedOnceKeys = new Set;
 function warnVerbose(...args) {
   if (sinkOverride) {
     sinkOverride("warnVerbose", args);
@@ -16855,6 +16856,7 @@ function base(input) {
     ...input.containmentRoot ? { containmentRoot: input.containmentRoot } : {}
   };
 }
+var ARGV_ARRAY_BLOCK_DETAIL = "Manual conversion required: an array `command:` has no safe v3 `run:` string. Rewrite it by hand as " + "`run:` (string) plus `shell:` — see docs/migration/v0.9.1-to-v0.9.2.md for the full v2 to v4 field mapping.";
 function blocked(input, reason, detail) {
   return Object.freeze({ status: "blocked", ...base(input), reason, ...detail ? { detail } : {} });
 }
@@ -17117,8 +17119,10 @@ function planLegacyTaskDataToV3(input, data) {
   } catch (cause) {
     return blocked(input, "invalid-v2-task", cause instanceof Error ? cause.message : String(cause));
   }
-  if (isReason(migrated))
-    return blocked(input, migrated);
+  if (isReason(migrated)) {
+    const detail = migrated === "argv-array-has-no-portable-shell-string" ? ARGV_ARRAY_BLOCK_DETAIL : undefined;
+    return blocked(input, migrated, detail);
+  }
   const after = Buffer.from($stringify(migrated), "utf8");
   try {
     parseTaskV3Yaml({
@@ -23871,6 +23875,27 @@ function describeJsonRoot(value) {
     return "a boolean";
   return typeof value;
 }
+function pruneToNewest(dir, keep, select) {
+  let entries;
+  try {
+    entries = fs18.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  const candidates = entries.filter(select).map((entry) => {
+    const full = path27.join(dir, entry.name);
+    let mtime = 0;
+    try {
+      mtime = fs18.statSync(full).mtimeMs;
+    } catch {}
+    return { path: full, mtime };
+  }).sort((a, b) => b.mtime - a.mtime);
+  for (const stale of candidates.slice(keep)) {
+    try {
+      fs18.rmSync(stale.path, { recursive: true, force: true });
+    } catch {}
+  }
+}
 function getConfigLockPath() {
   return path27.join(getConfigDir(), "config.json.lck");
 }
@@ -29844,6 +29869,10 @@ function inspectCurrentTaskPlan() {
 function inspectMigrationPlan() {
   return inspectCurrentTaskPlan().result;
 }
+var MAX_TASK_MIGRATION_BACKUPS = 5;
+function pruneTaskMigrationBackups(generationBackupDir) {
+  pruneToNewest(generationBackupDir, MAX_TASK_MIGRATION_BACKUPS, (entry) => entry.isDirectory());
+}
 function printPlan(plan) {
   console.log(JSON.stringify(plan));
   if (plan.status === "blocked")
@@ -29861,12 +29890,14 @@ async function runMigrationApply(options = {}) {
     const before = inspectCurrentTaskPlan();
     if (before.result.taskV3Migration.changed === 0)
       return before.result;
-    const backupPath = path33.join(getDataDir(), "backups", "task-v3", `${Date.now()}-${randomUUID2()}`);
+    const backupRoot = path33.join(getDataDir(), "backups", "task-v3");
+    const backupPath = path33.join(backupRoot, `${Date.now()}-${randomUUID2()}`);
     const applied = applyTaskToV3MigrationPlan(before.plan, { backupRoot: backupPath });
     const after = inspectCurrentTaskPlan().result;
     if (after.taskV3Migration.changed > 0) {
       throw new ConfigError("Task migration did not converge to task v3.", "INVALID_CONFIG_FILE");
     }
+    pruneTaskMigrationBackups(backupRoot);
     return { ...after, backupPath, applied: applied.changed.length };
   }));
   printPlan(result);
@@ -29924,12 +29955,14 @@ async function runTaskV4MigrationApply(options = {}) {
     const before = inspectCurrentTaskV4Plan();
     if (before.result.taskV4Migration.changed === 0)
       return before.result;
-    const backupPath = path33.join(getDataDir(), "backups", "task-v4", `${Date.now()}-${randomUUID2()}`);
+    const backupRoot = path33.join(getDataDir(), "backups", "task-v4");
+    const backupPath = path33.join(backupRoot, `${Date.now()}-${randomUUID2()}`);
     const applied = applyTaskToV4MigrationPlan(before.plan, { backupRoot: backupPath });
     const after = inspectCurrentTaskV4Plan().result;
     if (after.taskV4Migration.changed > 0) {
       throw new ConfigError("Task migration did not converge to task source v4.", "INVALID_CONFIG_FILE");
     }
+    pruneTaskMigrationBackups(backupRoot);
     return { ...after, backupPath, applied: applied.changed.length };
   }));
   printPlan(result);

package/dist/scripts/akm-migrate.js

@@ -13026,6 +13026,7 @@ function warn(...args) {
     console.warn(...args);
   }
 }
+var warnedOnceKeys = new Set;
 function warnVerbose(...args) {
   if (sinkOverride) {
     sinkOverride("warnVerbose", args);
@@ -16777,6 +16778,7 @@ function base(input) {
     ...input.containmentRoot ? { containmentRoot: input.containmentRoot } : {}
   };
 }
+var ARGV_ARRAY_BLOCK_DETAIL = "Manual conversion required: an array `command:` has no safe v3 `run:` string. Rewrite it by hand as " + "`run:` (string) plus `shell:` \u2014 see docs/migration/v0.9.1-to-v0.9.2.md for the full v2 to v4 field mapping.";
 function blocked(input, reason, detail) {
   return Object.freeze({ status: "blocked", ...base(input), reason, ...detail ? { detail } : {} });
 }
@@ -17039,8 +17041,10 @@ function planLegacyTaskDataToV3(input, data) {
   } catch (cause) {
     return blocked(input, "invalid-v2-task", cause instanceof Error ? cause.message : String(cause));
   }
-  if (isReason(migrated))
-    return blocked(input, migrated);
+  if (isReason(migrated)) {
+    const detail = migrated === "argv-array-has-no-portable-shell-string" ? ARGV_ARRAY_BLOCK_DETAIL : undefined;
+    return blocked(input, migrated, detail);
+  }
   const after = Buffer.from($stringify(migrated), "utf8");
   try {
     parseTaskV3Yaml({
@@ -23793,6 +23797,27 @@ function describeJsonRoot(value) {
     return "a boolean";
   return typeof value;
 }
+function pruneToNewest(dir, keep, select) {
+  let entries;
+  try {
+    entries = fs18.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  const candidates = entries.filter(select).map((entry) => {
+    const full = path27.join(dir, entry.name);
+    let mtime = 0;
+    try {
+      mtime = fs18.statSync(full).mtimeMs;
+    } catch {}
+    return { path: full, mtime };
+  }).sort((a, b) => b.mtime - a.mtime);
+  for (const stale of candidates.slice(keep)) {
+    try {
+      fs18.rmSync(stale.path, { recursive: true, force: true });
+    } catch {}
+  }
+}
 function getConfigLockPath() {
   return path27.join(getConfigDir(), "config.json.lck");
 }
@@ -29766,6 +29791,10 @@ function inspectCurrentTaskPlan() {
 function inspectMigrationPlan() {
   return inspectCurrentTaskPlan().result;
 }
+var MAX_TASK_MIGRATION_BACKUPS = 5;
+function pruneTaskMigrationBackups(generationBackupDir) {
+  pruneToNewest(generationBackupDir, MAX_TASK_MIGRATION_BACKUPS, (entry) => entry.isDirectory());
+}
 function printPlan(plan) {
   console.log(JSON.stringify(plan));
   if (plan.status === "blocked")
@@ -29783,12 +29812,14 @@ async function runMigrationApply(options = {}) {
     const before = inspectCurrentTaskPlan();
     if (before.result.taskV3Migration.changed === 0)
       return before.result;
-    const backupPath = path33.join(getDataDir(), "backups", "task-v3", `${Date.now()}-${randomUUID2()}`);
+    const backupRoot = path33.join(getDataDir(), "backups", "task-v3");
+    const backupPath = path33.join(backupRoot, `${Date.now()}-${randomUUID2()}`);
     const applied = applyTaskToV3MigrationPlan(before.plan, { backupRoot: backupPath });
     const after = inspectCurrentTaskPlan().result;
     if (after.taskV3Migration.changed > 0) {
       throw new ConfigError("Task migration did not converge to task v3.", "INVALID_CONFIG_FILE");
     }
+    pruneTaskMigrationBackups(backupRoot);
     return { ...after, backupPath, applied: applied.changed.length };
   }));
   printPlan(result);
@@ -29846,12 +29877,14 @@ async function runTaskV4MigrationApply(options = {}) {
     const before = inspectCurrentTaskV4Plan();
     if (before.result.taskV4Migration.changed === 0)
       return before.result;
-    const backupPath = path33.join(getDataDir(), "backups", "task-v4", `${Date.now()}-${randomUUID2()}`);
+    const backupRoot = path33.join(getDataDir(), "backups", "task-v4");
+    const backupPath = path33.join(backupRoot, `${Date.now()}-${randomUUID2()}`);
     const applied = applyTaskToV4MigrationPlan(before.plan, { backupRoot: backupPath });
     const after = inspectCurrentTaskV4Plan().result;
     if (after.taskV4Migration.changed > 0) {
       throw new ConfigError("Task migration did not converge to task source v4.", "INVALID_CONFIG_FILE");
     }
+    pruneTaskMigrationBackups(backupRoot);
     return { ...after, backupPath, applied: applied.changed.length };
   }));
   printPlan(result);

package/dist/storage/repositories/index-entries-repository.js

@@ -336,12 +336,28 @@ export function getPositiveFeedbackCountsByIds(ids) {
     }, "positive feedback counts are best-effort");
     return result;
 }
-function rowsInDirectory(db, dirPath, bundleId) {
-    const rows = db
-        .prepare(`SELECT id, item_ref, file_path FROM entries${bundleId ? " WHERE bundle_id = ?" : ""}`)
-        .all(...(bundleId ? [bundleId] : []));
+/**
+ * Rows whose `file_path` sits directly in `dirPath`. A half-open byte range
+ * over `idx_entries_file_path` (`[dir + sep, dir + sep + 1)`) turns the lookup
+ * into an index seek; the range is exact for "starts with `dir/`" but also
+ * admits nested subdirectories (`/a/b/c/x.md` for `/a/b`), so the dirname
+ * post-filter stays.
+ */
+function selectRowsInDirectory(db, dirPath, columns, bundleId) {
     const resolvedDir = path.resolve(dirPath);
-    return rows.filter((row) => path.dirname(path.resolve(row.file_path)) === resolvedDir);
+    const prefix = resolvedDir + path.sep;
+    const upperBound = resolvedDir + String.fromCharCode(path.sep.charCodeAt(0) + 1);
+    const params = [prefix, upperBound];
+    let sql = `SELECT ${columns} FROM entries WHERE file_path >= ? AND file_path < ?`;
+    if (bundleId) {
+        sql += " AND bundle_id = ?";
+        params.push(bundleId);
+    }
+    const rows = db.prepare(sql).all(...params);
+    return rows.filter((row) => path.dirname(row.file_path) === resolvedDir);
+}
+function rowsInDirectory(db, dirPath, bundleId) {
+    return selectRowsInDirectory(db, dirPath, "id, item_ref, file_path", bundleId);
 }
 function deleteEntryRows(db, rows, options = {}) {
     if (rows.length === 0)
@@ -629,9 +645,7 @@ export function getEntryById(db, id) {
     };
 }
 export function getEntriesByDir(db, dirPath) {
-    const ids = new Set(rowsInDirectory(db, dirPath).map((row) => row.id));
-    const rows = db.prepare(`SELECT ${ENTRY_COLUMNS} FROM entries`).all().filter((row) => ids.has(row.id));
-    return parseEntryRows(rows, "getEntriesByDir");
+    return parseEntryRows(selectRowsInDirectory(db, dirPath, ENTRY_COLUMNS), "getEntriesByDir");
 }
 /** Return every directory previously indexed for one canonical bundle. */
 export function getIndexedDirPathsByBundleId(db, bundleId) {
@@ -640,9 +654,8 @@ export function getIndexedDirPathsByBundleId(db, bundleId) {
 }
 /** Return every persisted bundle owner for one physical directory. */
 export function getIndexedBundleIdsByDir(db, dirPath) {
-    const ids = new Set(rowsInDirectory(db, dirPath).map((row) => row.id));
-    const rows = db.prepare("SELECT id, bundle_id FROM entries").all();
-    return [...new Set(rows.filter((row) => ids.has(row.id)).map((row) => row.bundle_id))];
+    const rows = selectRowsInDirectory(db, dirPath, "bundle_id, file_path");
+    return [...new Set(rows.map((row) => row.bundle_id))];
 }
 /**
  * Resolve a single `entries.id` by exact `file_path` (the canonical on-disk

package/dist/storage/repositories/index-meta-repository.js

@@ -23,7 +23,7 @@ export function deleteMeta(db, key) {
 // ── Per-directory index state ───────────────────────────────────────────────
 export function getIndexDirState(db, dirPath) {
     const row = db
-        .prepare("SELECT dir_path, file_set_hash, file_mtime_max_ms, reason, updated_at FROM index_dir_state WHERE dir_path = ?")
+        .prepare("SELECT dir_path, file_set_hash, file_mtime_max_ms, reason, updated_at, row_count FROM index_dir_state WHERE dir_path = ?")
         .get(dirPath);
     if (!row)
         return undefined;
@@ -33,16 +33,18 @@ export function getIndexDirState(db, dirPath) {
         fileMtimeMaxMs: row.file_mtime_max_ms,
         reason: row.reason,
         updatedAt: row.updated_at,
+        rowCount: row.row_count ?? undefined,
     };
 }
 export function upsertIndexDirState(db, state) {
-    db.prepare(`INSERT INTO index_dir_state (dir_path, file_set_hash, file_mtime_max_ms, reason, updated_at)
-     VALUES (?, ?, ?, ?, ?)
+    db.prepare(`INSERT INTO index_dir_state (dir_path, file_set_hash, file_mtime_max_ms, reason, updated_at, row_count)
+     VALUES (?, ?, ?, ?, ?, ?)
      ON CONFLICT(dir_path) DO UPDATE SET
        file_set_hash = excluded.file_set_hash,
        file_mtime_max_ms = excluded.file_mtime_max_ms,
        reason = excluded.reason,
-       updated_at = excluded.updated_at`).run(state.dirPath, state.fileSetHash, state.fileMtimeMaxMs, state.reason, new Date().toISOString());
+       updated_at = excluded.updated_at,
+       row_count = excluded.row_count`).run(state.dirPath, state.fileSetHash, state.fileMtimeMaxMs, state.reason, new Date().toISOString(), state.rowCount ?? null);
 }
 export function deleteIndexDirState(db, dirPath) {
     db.prepare("DELETE FROM index_dir_state WHERE dir_path = ?").run(dirPath);

package/dist/storage/repositories/index-schema.js

@@ -268,9 +268,11 @@ export function ensureSchema(db, embeddingDim) {
       file_set_hash     TEXT NOT NULL,
       file_mtime_max_ms REAL NOT NULL,
       reason            TEXT NOT NULL,
-      updated_at        TEXT NOT NULL
+      updated_at        TEXT NOT NULL,
+      row_count         INTEGER
     );
   `);
+    ensureIndexDirStateRowCountColumn(db);
     // LLM enrichment result cache. Stores a SHA-256 body hash and the JSON
     // result for each asset so that subsequent `akm index --enrich` runs can
     // skip the LLM call when the body hasn't changed. The cache is keyed by
@@ -379,3 +381,16 @@ function tableExists(db, name) {
     const row = db.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name=? LIMIT 1").get(name);
     return row !== undefined && row !== null;
 }
+/**
+ * #900: `row_count` was added after the table's first release, so a database
+ * created before it needs an `ALTER TABLE` (`CREATE TABLE IF NOT EXISTS` only
+ * shapes a fresh table). Idempotent. Pre-existing rows keep NULL until their
+ * directory is next drained; index.db is a regenerable cache, so nothing is
+ * backfilled.
+ */
+function ensureIndexDirStateRowCountColumn(db) {
+    const columns = db.prepare("PRAGMA table_info(index_dir_state)").all();
+    if (!columns.some((column) => column.name === "row_count")) {
+        db.exec("ALTER TABLE index_dir_state ADD COLUMN row_count INTEGER");
+    }
+}

package/dist/storage/repositories/proposals-repository.js

@@ -12,6 +12,7 @@
 import path from "node:path";
 import { stashDirFor } from "../../core/asset/asset-placement.js";
 import { bundleRefToString, isBundleSlug, parseBundleRef } from "../../core/asset/asset-ref.js";
+import { warnOnce } from "../../core/warn.js";
 /** Serialize `Proposal.changes` for `metadata_json` (see {@link StoredFileChange}). */
 function changesToStored(changes) {
     return changes.map((c, i) => ({
@@ -361,8 +362,10 @@ export function listStateProposals(db, options = {}) {
             proposals.push(proposalRowToProposal(row));
         }
         catch (error) {
+            // Once per row per process (#898): health alone reads this table several
+            // times per invocation.
             const message = error instanceof Error ? error.message : String(error);
-            console.warn(`[akm] Skipping unparseable proposal row (id=${row.id}, ref=${row.ref}): ${message}`);
+            warnOnce(`unparseable-proposal-row:${row.id}`, `[akm] Skipping unparseable proposal row (id=${row.id}, ref=${row.ref}): ${message}`);
         }
     }
     return proposals;

package/dist/tasks/resolve-akm-bin.js

@@ -152,7 +152,22 @@ function samePath(left, right) {
     };
     return normalize(left) === normalize(right);
 }
+// #901: the global root can't change within a process lifetime, and every
+// `resolveAkmInvocation()` call in a scheduler-sync process re-derives the
+// same `nodePath` — so this spawns `npm root --global` at most once per
+// process instead of once per call. Keyed by nodePath (rather than a bare
+// once-only flag) so a differently-invoked probe later in the same process
+// still gets its own answer instead of a stale one.
+let cachedNpmGlobalRoot;
 function resolveNpmGlobalRoot(nodePath, env) {
+    if (cachedNpmGlobalRoot && cachedNpmGlobalRoot.nodePath === nodePath) {
+        return cachedNpmGlobalRoot.value;
+    }
+    const value = resolveNpmGlobalRootUncached(nodePath, env);
+    cachedNpmGlobalRoot = { nodePath, value };
+    return value;
+}
+function resolveNpmGlobalRootUncached(nodePath, env) {
     const npmCli = resolveAssociatedNpmCli(nodePath);
     if (!npmCli)
         return undefined;