akm-cli 0.9.17-alpha.9 → 0.9.18

package/dist/commands/sources/info.js

@@ -1,30 +1,87 @@
 // 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 path from "node:path";
 import { placementTypes } from "../../core/asset/asset-placement.js";
 import { resolveStashDir } from "../../core/common.js";
-import { getSources, loadConfig } from "../../core/config/config.js";
+import { DEFAULT_CONFIG, getSources, loadConfig } from "../../core/config/config.js";
+import { ConfigError } from "../../core/errors.js";
 import { classifyPathAccess, describeInaccessiblePath } from "../../core/path-access.js";
-import { getCacheDir, getConfigDir, getDataDir, getDbPath, getStateDir } from "../../core/paths.js";
+import { getCacheDir, getConfigDir, getDataDir, getDefaultStashDir, getStateDir } from "../../core/paths.js";
 import { formatRegistryUrl } from "../../core/registry-url.js";
 import { error } from "../../core/warn.js";
-import { closeDatabase, openExistingDatabase } from "../../storage/repositories/index-connection.js";
+import { closeDatabase, openReadonlyExistingDatabase } from "../../storage/repositories/index-connection.js";
 import { getEntryCount, getEntryCountByType } from "../../storage/repositories/index-entries-repository.js";
 import { countLinksByKind } from "../../storage/repositories/index-links-repository.js";
 import { getMeta } from "../../storage/repositories/index-meta-repository.js";
+import { isSqliteContentionError } from "../../storage/sqlite-transaction.js";
 import { pkgVersion } from "../../version.js";
+/**
+ * Bound for `akm info`'s diagnostic index.db read — short enough that a
+ * locked database never stalls the command, unlike the shared 30s
+ * `SQLITE_BUSY_TIMEOUT_MS` every write-capable opener uses. The opener's own
+ * layout check (`checkIndexLayout`) swallows a busy error on its one SELECT
+ * rather than surfacing it, so a genuinely locked database costs this
+ * timeout TWICE before the first real query here (`countLinksByKind`)
+ * throws for real — 750ms keeps that ~1.5s worst case well clear of the 3s
+ * bound integration tests hold this to, on a loaded CI box.
+ */
+const INFO_INDEX_BUSY_TIMEOUT_MS = 750;
 /**
  * Assemble system info describing the current capabilities, configuration,
- * and index state. Used by `akm info`.
+ * and index state. Used by `akm info`, which must behave like a help
+ * command (owner ruling): always print a report and exit 0, whatever else
+ * is happening. Every section below is read best-effort, so one failing
+ * lookup degrades only its own field(s) instead of the whole report;
+ * `infoCommand` itself (stash-cli.ts) wraps this whole call as the final
+ * backstop for anything left over — e.g. a path resolver that needs an
+ * environment variable nothing here sets, such as `HOME`.
  *
  * @param options.dbPath - Override the database path (useful for testing)
  */
 export function assembleInfo(options) {
-    const config = loadConfig();
+    let config;
+    let configError;
+    try {
+        config = loadConfig();
+    }
+    catch (err) {
+        config = DEFAULT_CONFIG;
+        configError = err instanceof Error ? err.message : String(err);
+    }
     // Primary stash directory + default bundle name — same resolution
     // `akm sources list` uses (R-057), so `akm info` and `akm sources list`
-    // agree on which stash is primary.
-    const stashDir = resolveStashDir();
+    // agree on which stash is primary. No bundle created yet
+    // (STASH_DIR_NOT_FOUND, the ordinary fresh-install state) reports where a
+    // fresh `akm setup`/`akm bundle create` would put it, same as "report the
+    // defaults" for a missing config — no error needed, nothing is actually
+    // wrong. A bundle that WAS configured (an env override or `bundles.*` in
+    // config) but doesn't resolve (STASH_DIR_UNREADABLE/STASH_DIR_NOT_A_DIRECTORY)
+    // is different: the fallback path is a courtesy, not a way to hide a
+    // genuine misconfiguration, so that reason is kept in `bundleDirError`.
+    let stashDir;
+    let bundleDirError;
+    try {
+        stashDir = resolveStashDir();
+    }
+    catch (err) {
+        if (!(err instanceof ConfigError) || err.code !== "STASH_DIR_NOT_FOUND") {
+            bundleDirError = err instanceof Error ? err.message : String(err);
+        }
+        // The fallback itself resolves purely from `HOME` (or its platform
+        // equivalent) and can throw the exact same way `resolveStashDir()` can
+        // (e.g. HOME entirely unset) — guarded so a blank `bundleDir` (never a
+        // throw) still always carries a reason, reusing the one above when the
+        // outer catch already set it (a configured-but-broken path takes
+        // precedence over restating "and the default isn't resolvable either").
+        try {
+            stashDir = getDefaultStashDir();
+        }
+        catch (fallbackErr) {
+            stashDir = "";
+            bundleDirError ??= fallbackErr instanceof Error ? fallbackErr.message : String(fallbackErr);
+        }
+    }
     const defaultBundle = config.defaultBundle ?? null;
     // Asset types (copy into a mutable array — `placementTypes()` returns readonly)
     const assetTypes = [...placementTypes()];
@@ -45,11 +102,29 @@ export function assembleInfo(options) {
         ...(s.url ? { url: s.url } : {}),
         ...(s.enabled !== undefined ? { enabled: s.enabled } : {}),
     }));
-    // Index stats — `options.dbPath` is a test-only override (see the param
-    // doc above); real callers fall through to the same `getDbPath()` that
-    // health and search use, so info reads the same database they do.
-    const resolvedDbPath = options?.dbPath ?? getDbPath();
-    const indexStats = readIndexStats(resolvedDbPath);
+    // Data directory. `getDataDir()` can itself throw (e.g. TEST_ISOLATION_MISSING
+    // when NODE_ENV=test leaks into a real invocation — a JS test runner's
+    // child process — with no XDG_DATA_HOME/AKM_DATA_DIR override), caught
+    // here so that failure degrades only `dataDir`/`indexStats` rather than
+    // the whole report. Always attempted, even when `options.dbPath` (a
+    // test-only override, see the param doc above) means it is not needed to
+    // resolve the index path below — `dataDir` is its own reported field.
+    let dataDir = "";
+    let dataDirError;
+    try {
+        dataDir = getDataDir();
+    }
+    catch (err) {
+        dataDirError = err instanceof Error ? err.message : String(err);
+    }
+    // Index stats. `options.dbPath` overrides the resolved path outright;
+    // otherwise it is derived from `dataDir` above, so a data dir that failed
+    // to resolve degrades index stats the same way rather than retrying (and
+    // re-throwing) `getDataDir()` a second time.
+    const resolvedDbPath = options?.dbPath ?? (dataDir ? path.join(dataDir, "index.db") : undefined);
+    const indexStats = resolvedDbPath
+        ? readIndexStats(resolvedDbPath)
+        : { entryCount: 0, byType: {}, lastBuiltAt: null, hasEmbeddings: false, unavailable: dataDirError };
     // Semantic status is read live from the index's own state, not a cached
     // verdict — a failed embed attempt at search time falls back to FTS and
     // reports that in the search response, it never disables the mode here.
@@ -63,10 +138,12 @@ export function assembleInfo(options) {
         version: pkgVersion,
         bundleDir: stashDir,
         defaultBundle,
-        dataDir: getDataDir(),
-        configDir: getConfigDir(),
-        cacheDir: getCacheDir(),
-        stateDir: getStateDir(),
+        ...(configError ? { configError } : {}),
+        ...(bundleDirError ? { bundleDirError } : {}),
+        dataDir,
+        configDir: safePath(getConfigDir),
+        cacheDir: safePath(getCacheDir),
+        stateDir: safePath(getStateDir),
         assetTypes,
         searchModes,
         semanticSearch: {
@@ -78,6 +155,15 @@ export function assembleInfo(options) {
         indexStats,
     };
 }
+/** Best-effort path resolution for a section that must degrade, not throw: an empty string in place of an exception. */
+function safePath(fn) {
+    try {
+        return fn();
+    }
+    catch {
+        return "";
+    }
+}
 function readIndexStats(resolvedPath) {
     const EMPTY = {
         entryCount: 0,
@@ -99,7 +185,15 @@ function readIndexStats(resolvedPath) {
     }
     let db;
     try {
-        db = openExistingDatabase(resolvedPath);
+        // Never writes the index — no schema or journal-mode change — and
+        // bounded to INFO_INDEX_BUSY_TIMEOUT_MS rather than the shared 30s
+        // busy_timeout every write-capable opener uses. A newer index layout is
+        // reported below rather than refused (checkIndexLayout throws); an
+        // older layout just warns and is served as-is, never migrated — both
+        // already true of this opener.
+        db = openReadonlyExistingDatabase(resolvedPath, { busyTimeoutMs: INFO_INDEX_BUSY_TIMEOUT_MS });
+        if (!db)
+            return EMPTY; // raced away (deleted) between the access check above and here
         const links = countLinksByKind(db);
         return {
             entryCount: getEntryCount(db),
@@ -115,7 +209,7 @@ function readIndexStats(resolvedPath) {
         // Routed through core/warn's `error()` (not a raw process.stderr.write)
         // so `--quiet`/`setQuiet()` actually gate this line (R-057).
         error(`[akm info] failed to read index stats from ${resolvedPath}: ${String(err)}`);
-        return EMPTY;
+        return { ...EMPTY, unavailable: describeIndexReadFailure(err) };
     }
     finally {
         if (db) {
@@ -128,3 +222,13 @@ function readIndexStats(resolvedPath) {
         }
     }
 }
+/**
+ * Reason for `indexStats.unavailable`. Contention gets its own clear
+ * wording; everything else (a too-new layout, on-disk corruption, ...) is
+ * already descriptive as the driver/opener's own message.
+ */
+function describeIndexReadFailure(err) {
+    if (isSqliteContentionError(err))
+        return "index.db is locked by another akm process";
+    return err instanceof Error ? err.message : String(err);
+}

package/dist/commands/sources/stash-cli.js

@@ -33,6 +33,7 @@ import * as p from "../../cli/clack.js";
 import { getParsedInvocation } from "../../cli/invocation.js";
 import { defineJsonCommand, GLOBAL_OUTPUT_ARGS, output, parseAllFlagValues, runWithJsonErrors } from "../../cli/shared.js";
 import { assertFlatAssetName } from "../../core/asset/asset-create.js";
+import { placementTypes } from "../../core/asset/asset-placement.js";
 import { parseFrontmatter } from "../../core/asset/frontmatter.js";
 import { isHttpUrl, resolveStashDir } from "../../core/common.js";
 import { loadConfig } from "../../core/config/config.js";
@@ -45,6 +46,7 @@ import { resolveWriteTarget } from "../../core/write-source.js";
 import { releaseIndexRebuildLock, tryAcquireIndexRebuildLock } from "../../indexer/index-rebuild-lock.js";
 import { akmIndex } from "../../indexer/indexer.js";
 import { getHyphenatedBoolean, getOutputMode } from "../../output/context.js";
+import { pkgVersion } from "../../version.js";
 import { inferAssetName, mergeXrefsIntoContent, readKnowledgeInput, resolveSupersedesForWrite, resolveSupersedesWriteTarget, resolveXrefsForWrite, writeMarkdownAsset, } from "../read/knowledge.js";
 import { assembleInfo } from "./info.js";
 /** Matches the high-frequency per-committed-batch progress line (#954), excluded from non-verbose JSON-mode stderr. */
@@ -181,7 +183,25 @@ export const indexCommand = defineCommand({
 export const infoCommand = defineJsonCommand({
     meta: { name: "info", description: "Show system capabilities, configuration, and index stats" },
     run() {
-        const result = assembleInfo();
+        // `akm info` must behave like a help command: always exit 0 with a
+        // report. `assembleInfo()` already degrades what it reasonably can
+        // per-section; this is the final backstop for whatever it can't (e.g.
+        // every path resolver needs an environment variable, such as `HOME`,
+        // that this process genuinely does not have) — still a report, with
+        // whatever is cheap and safe enough to never itself throw.
+        let result;
+        try {
+            result = assembleInfo();
+        }
+        catch (err) {
+            result = {
+                schemaVersion: 1,
+                version: pkgVersion,
+                error: err instanceof Error ? err.message : String(err),
+                assetTypes: [...placementTypes()],
+                searchModes: ["fts"],
+            };
+        }
         output("info", result);
     },
 });

package/dist/core/improve-result.js

@@ -393,7 +393,12 @@ function validateImprovePlan(value, dryRun, plannedRefNames) {
     if (value.limits.totalCeiling !== undefined && value.effectiveRefs.length > value.limits.totalCeiling) {
         fail("plan.effectiveRefs cannot exceed plan.limits.totalCeiling");
     }
-    validateProcessRoutingRows(value.processes);
+    // #947 added plan.processes (2026-09-09T09:03:19Z); every run recorded
+    // before it legitimately stored `plan` with no `processes` key at all —
+    // validate the rows only when present, same as `proactive` below, so a
+    // pre-#947 envelope still decodes (AGENTS.md "Reading persisted data").
+    if (value.processes !== undefined)
+        validateProcessRoutingRows(value.processes);
     if (value.proactive !== undefined)
         validateProactivePlan(value.proactive);
     validateConsolidationPlan(value.consolidation);

package/dist/output/text/command-format.js

@@ -20,11 +20,20 @@ export function formatInfoPlain(r) {
     const lines = [];
     if (r.version)
         lines.push(`version: ${String(r.version)}`);
+    // Only present in infoCommand's own last-resort fallback (stash-cli.ts),
+    // when assembleInfo() itself threw — every field below it belongs to the
+    // normal shape and is absent there.
+    if (typeof r.error === "string")
+        lines.push(`error: ${r.error}`);
     if (r.bundleDir)
         lines.push(`bundleDir: ${String(r.bundleDir)}`);
     if (r.defaultBundle !== undefined) {
         lines.push(`defaultBundle: ${r.defaultBundle === null ? "(none)" : String(r.defaultBundle)}`);
     }
+    if (typeof r.configError === "string")
+        lines.push(`configError: ${r.configError}`);
+    if (typeof r.bundleDirError === "string")
+        lines.push(`bundleDirError: ${r.bundleDirError}`);
     if (Array.isArray(r.assetTypes) && r.assetTypes.length > 0) {
         lines.push(`assetTypes: ${r.assetTypes.join(", ")}`);
     }

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

@@ -29609,11 +29609,17 @@ function formatInfoPlain(r) {
   const lines = [];
   if (r.version)
     lines.push(`version: ${String(r.version)}`);
+  if (typeof r.error === "string")
+    lines.push(`error: ${r.error}`);
   if (r.bundleDir)
     lines.push(`bundleDir: ${String(r.bundleDir)}`);
   if (r.defaultBundle !== undefined) {
     lines.push(`defaultBundle: ${r.defaultBundle === null ? "(none)" : String(r.defaultBundle)}`);
   }
+  if (typeof r.configError === "string")
+    lines.push(`configError: ${r.configError}`);
+  if (typeof r.bundleDirError === "string")
+    lines.push(`bundleDirError: ${r.bundleDirError}`);
   if (Array.isArray(r.assetTypes) && r.assetTypes.length > 0) {
     lines.push(`assetTypes: ${r.assetTypes.join(", ")}`);
   }
@@ -52058,6 +52064,7 @@ import os6 from "node:os";
 import path44 from "node:path";
 
 // src/storage/sqlite-read-snapshot.ts
+import { spawnSync as spawnSync5 } from "node:child_process";
 import fs36 from "node:fs";
 import os5 from "node:os";
 import path43 from "node:path";
@@ -52102,6 +52109,26 @@ function fingerprintsEqual(left, right) {
   const sameFile = (a, b) => a?.size === b?.size && a?.mtimeNs === b?.mtimeNs && a?.ctimeNs === b?.ctimeNs;
   return sameFile(left.main, right.main) && sameFile(left.wal, right.wal);
 }
+function copyFileOutsideThisProcess(source, destination) {
+  if (process.platform === "win32") {
+    fs36.copyFileSync(source, destination);
+    return;
+  }
+  const result = spawnSync5("cp", ["--", source, destination], {
+    encoding: "utf8",
+    stdio: ["ignore", "ignore", "pipe"]
+  });
+  if (result.error) {
+    throw new SqliteReadSnapshotUnavailableError(`cannot run cp to copy ${source}: ${result.error.message}`);
+  }
+  if (result.status === 0)
+    return;
+  if (fileFingerprint(source) === undefined) {
+    throw Object.assign(new Error(`${source} disappeared while it was being copied`), { code: "ENOENT" });
+  }
+  const reason = result.stderr.trim() || (result.signal ? `killed by ${result.signal}` : `exit status ${result.status}`);
+  throw new Error(`cp could not copy ${source}: ${reason}`);
+}
 function openSqliteReadSnapshot(dbPath) {
   if (!pathExists(dbPath))
     return;
@@ -52117,9 +52144,9 @@ function openSqliteReadSnapshot(dbPath) {
         if (pathExists(`${dbPath}-journal`))
           continue;
         const before = databaseFingerprint(dbPath);
-        fs36.copyFileSync(dbPath, snapshotPath);
+        copyFileOutsideThisProcess(dbPath, snapshotPath);
         if (before.wal)
-          fs36.copyFileSync(`${dbPath}-wal`, `${snapshotPath}-wal`);
+          copyFileOutsideThisProcess(`${dbPath}-wal`, `${snapshotPath}-wal`);
         else
           fs36.rmSync(`${snapshotPath}-wal`, { force: true });
         const after = databaseFingerprint(dbPath);

package/dist/scripts/akm-migrate.js

@@ -28937,11 +28937,17 @@ function formatInfoPlain(r) {
   const lines = [];
   if (r.version)
     lines.push(`version: ${String(r.version)}`);
+  if (typeof r.error === "string")
+    lines.push(`error: ${r.error}`);
   if (r.bundleDir)
     lines.push(`bundleDir: ${String(r.bundleDir)}`);
   if (r.defaultBundle !== undefined) {
     lines.push(`defaultBundle: ${r.defaultBundle === null ? "(none)" : String(r.defaultBundle)}`);
   }
+  if (typeof r.configError === "string")
+    lines.push(`configError: ${r.configError}`);
+  if (typeof r.bundleDirError === "string")
+    lines.push(`bundleDirError: ${r.bundleDirError}`);
   if (Array.isArray(r.assetTypes) && r.assetTypes.length > 0) {
     lines.push(`assetTypes: ${r.assetTypes.join(", ")}`);
   }
@@ -52053,6 +52059,7 @@ import os6 from "os";
 import path44 from "path";
 
 // src/storage/sqlite-read-snapshot.ts
+import { spawnSync as spawnSync5 } from "child_process";
 import fs36 from "fs";
 import os5 from "os";
 import path43 from "path";
@@ -52097,6 +52104,26 @@ function fingerprintsEqual(left, right) {
   const sameFile = (a, b) => a?.size === b?.size && a?.mtimeNs === b?.mtimeNs && a?.ctimeNs === b?.ctimeNs;
   return sameFile(left.main, right.main) && sameFile(left.wal, right.wal);
 }
+function copyFileOutsideThisProcess(source, destination) {
+  if (process.platform === "win32") {
+    fs36.copyFileSync(source, destination);
+    return;
+  }
+  const result = spawnSync5("cp", ["--", source, destination], {
+    encoding: "utf8",
+    stdio: ["ignore", "ignore", "pipe"]
+  });
+  if (result.error) {
+    throw new SqliteReadSnapshotUnavailableError(`cannot run cp to copy ${source}: ${result.error.message}`);
+  }
+  if (result.status === 0)
+    return;
+  if (fileFingerprint(source) === undefined) {
+    throw Object.assign(new Error(`${source} disappeared while it was being copied`), { code: "ENOENT" });
+  }
+  const reason = result.stderr.trim() || (result.signal ? `killed by ${result.signal}` : `exit status ${result.status}`);
+  throw new Error(`cp could not copy ${source}: ${reason}`);
+}
 function openSqliteReadSnapshot(dbPath) {
   if (!pathExists(dbPath))
     return;
@@ -52112,9 +52139,9 @@ function openSqliteReadSnapshot(dbPath) {
         if (pathExists(`${dbPath}-journal`))
           continue;
         const before = databaseFingerprint(dbPath);
-        fs36.copyFileSync(dbPath, snapshotPath);
+        copyFileOutsideThisProcess(dbPath, snapshotPath);
         if (before.wal)
-          fs36.copyFileSync(`${dbPath}-wal`, `${snapshotPath}-wal`);
+          copyFileOutsideThisProcess(`${dbPath}-wal`, `${snapshotPath}-wal`);
         else
           fs36.rmSync(`${snapshotPath}-wal`, { force: true });
         const after = databaseFingerprint(dbPath);

package/dist/sources/providers/git-stash.js

@@ -97,6 +97,34 @@ export function tryListGitUnverifiablePaths(repoDir, pathspec) {
     }
     return { paths, ok: true };
 }
+/**
+ * The three-part git cleanliness check shared by the archive purge sweep
+ * (`purgeGracedArchive` in `commands/improve/memory/memory-improve.ts`) and
+ * the `memory-cleanup-archive` health advisory (`collectArchiveUsageAdvisory`
+ * in `commands/health/archive-usage.ts`): a path is safe to treat as
+ * committed only if it is tracked ({@link tryListGitTrackedPaths}), not dirty
+ * ({@link tryListGitChangedPaths}), and not assume-unchanged/skip-worktree
+ * ({@link tryListGitUnverifiablePaths} — those hide their own edits from
+ * `git status`, so an unverifiable file is never trusted as clean either).
+ *
+ * Each of the three git calls can fail independently (a broken submodule, or
+ * git missing from `PATH`); `ok` is `false` if any one does, and `isSafe`
+ * then returns `false` for every path rather than guessing — callers that
+ * need to short-circuit before doing other work still check `ok` themselves.
+ */
+export function checkGitPathSafety(repoDir, pathspec) {
+    const dirtyQuery = tryListGitChangedPaths(repoDir);
+    const trackedQuery = tryListGitTrackedPaths(repoDir, pathspec);
+    const unverifiableQuery = tryListGitUnverifiablePaths(repoDir, pathspec);
+    const ok = dirtyQuery.ok && trackedQuery.ok && unverifiableQuery.ok;
+    const dirty = new Set(dirtyQuery.paths);
+    const tracked = new Set(trackedQuery.paths);
+    const unverifiable = new Set(unverifiableQuery.paths);
+    return {
+        ok,
+        isSafe: (repoRelativePath) => ok && tracked.has(repoRelativePath) && !dirty.has(repoRelativePath) && !unverifiable.has(repoRelativePath),
+    };
+}
 export class GitStashPushError extends Error {
     commit;
     constructor(message, commit) {

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

@@ -180,9 +180,12 @@ export function openReadonlyExistingDatabase(dbPath, options) {
     // never block — but in the DELETE/TRUNCATE modes the network-FS fallback and
     // AKM_SQLITE_JOURNAL_MODE can select, a concurrent writer makes every read
     // fail instantly with SQLITE_BUSY. busy_timeout is legal on a read-only
-    // connection, so apply just that one.
+    // connection, so apply just that one. `busyTimeoutMs` defaults to the
+    // shared 30s constant; a caller that must never sit behind another akm
+    // process's write lock for long (e.g. `akm info`) can pass a much shorter
+    // bound instead.
     try {
-        db.exec(`PRAGMA busy_timeout = ${SQLITE_BUSY_TIMEOUT_MS}`);
+        db.exec(`PRAGMA busy_timeout = ${options?.busyTimeoutMs ?? SQLITE_BUSY_TIMEOUT_MS}`);
         checkIndexLayout(db, resolvedPath);
         return db;
     }

package/dist/storage/sqlite-read-snapshot.js

@@ -9,7 +9,12 @@
  * must not do that. This helper copies a stable main/WAL pair and opens that
  * private copy, so SQLite never attaches to the operator's original
  * main/WAL/SHM files.
+ *
+ * The copy itself is made by a child process, never by this one: see
+ * {@link copyFileOutsideThisProcess} for why an in-process read of a live
+ * database is unsafe.
  */
+import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -57,6 +62,45 @@ function fingerprintsEqual(left, right) {
     const sameFile = (a, b) => a?.size === b?.size && a?.mtimeNs === b?.mtimeNs && a?.ctimeNs === b?.ctimeNs;
     return sameFile(left.main, right.main) && sameFile(left.wal, right.wal);
 }
+/**
+ * Copy `source` to `destination` without opening `source` in THIS process.
+ *
+ * POSIX advisory locks belong to the process, not to the descriptor: when a
+ * process closes ANY descriptor for a file, the kernel drops every lock that
+ * process holds on it, including the SHARED lock a live SQLite connection in
+ * this same process (`akm improve` keeps one on state.db for the whole run)
+ * holds. A peer using an older SQLite (< 3.51) read-write would then see no
+ * reader, take EXCLUSIVE when it closes, and delete the `-wal`/`-shm` this
+ * process is still using. The read therefore happens in a child `cp`, whose
+ * descriptors and locks are its own. Windows locks belong to the handle, so
+ * an in-process copy cannot release another handle's lock there (and there is
+ * no `cp`).
+ *
+ * A source that vanished (a WAL checkpointed away mid-copy) throws an
+ * `ENOENT` error, which {@link openSqliteReadSnapshot} retries.
+ */
+function copyFileOutsideThisProcess(source, destination) {
+    if (process.platform === "win32") {
+        fs.copyFileSync(source, destination);
+        return;
+    }
+    const result = spawnSync("cp", ["--", source, destination], {
+        encoding: "utf8",
+        stdio: ["ignore", "ignore", "pipe"],
+    });
+    if (result.error) {
+        throw new SqliteReadSnapshotUnavailableError(`cannot run cp to copy ${source}: ${result.error.message}`);
+    }
+    if (result.status === 0)
+        return;
+    // `cp` reports its errors as text, so the vanished-source case is recognised
+    // by looking at the source itself.
+    if (fileFingerprint(source) === undefined) {
+        throw Object.assign(new Error(`${source} disappeared while it was being copied`), { code: "ENOENT" });
+    }
+    const reason = result.stderr.trim() || (result.signal ? `killed by ${result.signal}` : `exit status ${result.status}`);
+    throw new Error(`cp could not copy ${source}: ${reason}`);
+}
 /**
  * Open an isolated copy of an existing SQLite database.
  *
@@ -82,9 +126,9 @@ export function openSqliteReadSnapshot(dbPath) {
                 if (pathExists(`${dbPath}-journal`))
                     continue;
                 const before = databaseFingerprint(dbPath);
-                fs.copyFileSync(dbPath, snapshotPath);
+                copyFileOutsideThisProcess(dbPath, snapshotPath);
                 if (before.wal)
-                    fs.copyFileSync(`${dbPath}-wal`, `${snapshotPath}-wal`);
+                    copyFileOutsideThisProcess(`${dbPath}-wal`, `${snapshotPath}-wal`);
                 else
                     fs.rmSync(`${snapshotPath}-wal`, { force: true });
                 const after = databaseFingerprint(dbPath);

package/dist/storage/state-db-integrity.js

@@ -7,7 +7,7 @@
  *
  * `akm health`'s `state-db-integrity` check (src/commands/health/checks.ts)
  * is a pure projection like every other check, so the actual IO lives here:
- * a read-only `PRAGMA quick_check` and a read-only freelist/page-count read.
+ * a read-only `PRAGMA integrity_check` and a read-only freelist/page-count read.
  * Both open their own short-lived read-only connection via the plain
  * {@link openDatabase} opener rather than `openStateDatabase`
  * (src/core/state-db.ts), since a corrupt database must not need a clean
@@ -27,8 +27,8 @@
 import { appendEvent } from "../core/events.js";
 import { openDatabase } from "./database.js";
 import { applyReadonlyPragmas } from "./sqlite-pragmas.js";
-/** How many corruption errors `PRAGMA quick_check` collects before it stops scanning and returns. */
-const QUICK_CHECK_ERROR_LIMIT = 10;
+/** How many corruption errors `PRAGMA integrity_check` collects before it stops scanning and returns. */
+const INTEGRITY_CHECK_ERROR_LIMIT = 10;
 /**
  * Above this fraction of free pages, `state-db-integrity` warns, and
  * {@link vacuumIfReclaimable} compacts state.db (after improve's retention
@@ -48,16 +48,19 @@ function openReadonlyStateDb(dbPath) {
     return db;
 }
 /**
- * Run `PRAGMA quick_check(N)` against `dbPath` read-only. Sub-second on a
- * healthy multi-hundred-MB file; on a corrupt one, `N` bounds how many errors
- * SQLite collects before it stops scanning, which keeps the check's runtime
- * bounded even against a badly corrupt file.
+ * Run `PRAGMA integrity_check(N)` against `dbPath` read-only. Unlike
+ * `quick_check`, it also verifies every index against its table ("row N
+ * missing from index", "wrong # of entries in index"): the damage a WAL
+ * deleted under a live connection leaves behind, which `quick_check` reports
+ * as `ok`. Sub-second on a healthy state.db of a few hundred MB; on a corrupt
+ * one, `N` bounds how many errors SQLite collects before it stops scanning,
+ * which keeps the check's runtime bounded even against a badly corrupt file.
  */
-export function runStateDbQuickCheck(dbPath) {
+export function runStateDbIntegrityCheck(dbPath) {
     let db;
     try {
         db = openReadonlyStateDb(dbPath);
-        const rows = db.prepare(`PRAGMA quick_check(${QUICK_CHECK_ERROR_LIMIT})`).all();
+        const rows = db.prepare(`PRAGMA integrity_check(${INTEGRITY_CHECK_ERROR_LIMIT})`).all();
         const lines = rows.map((row) => String(firstColumn(row)));
         const ok = lines.length === 1 && lines[0] === "ok";
         return { ok, lines };

package/docs/migration/README.md

@@ -5,7 +5,7 @@ Upgrade guides and per-release migration notes.
 - [v0.9.1 -> v0.9.2 migration guide](v0.9.1-to-v0.9.2.md) -- Task-v2/task-v3 to task source v4 conversion, the durable-v4-family workflow boundary at executable `irVersion: 5`, and release behavior changes
 - [v0.9.2 release note](release-notes/0.9.2.md) -- Self-contained terminal upgrade summary shipped for `akm help migrate 0.9.2`
 - [v0.9.16 release note](release-notes/0.9.16.md) -- Source-bound scheduler grants, local execution authority, and split unsafe overrides
-- [v0.9.17 release note](release-notes/0.9.17.md) -- Tolerant readers, one config migration step, a plain scheduler list, less machinery, and the upgrade rehearsal gate
+- [v0.9.17 release note](release-notes/0.9.17.md) -- Consolidate's retire proposals and index layout 26, replacing the LLM entity graph with declared links, and `akm improve` scoped to what retrieval actually returns
 - [v0.8 -> current v0.9 migration guide](v0.8-to-v0.9.md) -- Package upgrade with fresh current config/state and explicit task conversion
 - [v0.7 -> v0.8 migration guide](v0.7-to-v0.8.md) -- Task schema and 0.8-era changes
 - [v0.5 -> v0.6 migration guide](https://github.com/itlackey/akm/blob/main/docs/migration/v0.5-to-v0.6.md) -- Terminology cut, registry schema v3, publisher changes