akm-cli 0.9.17-alpha.9 → 0.9.17

package/dist/cli/unknown-flags.js

@@ -26,8 +26,17 @@
  * validation) — conservative by design.
  */
 import { UsageError } from "../core/errors.js";
+import { warn } from "../core/warn.js";
 import { cittyComparableName, findCittyTopLevelCommandIndex, toAliasArray, } from "./invocation.js";
 import { retiredFlagHint } from "./retired-commands.js";
+/**
+ * Commands that must never refuse on an unrecognized flag — `akm info` warns
+ * and continues instead of exiting 2, the same tolerance a bare `akm help
+ * --whatever` already gets for free from its group-command fallback (no
+ * resolved subcommand, so this gate stands down entirely). `info` is a leaf
+ * command, so it needs an explicit opt-in here instead.
+ */
+const UNKNOWN_FLAG_TOLERANT_COMMANDS = new Set(["info"]);
 /** Flags citty implements itself, which no command declares. */
 const IMPLICIT_FLAGS = ["help", "h", "version", "v"];
 /**
@@ -172,6 +181,10 @@ function throwUnknownFlag(shown, attempted, known) {
         ? `Did you mean \`${suggestion}\`? Run the command with \`--help\` to see its accepted flags.`
         : undefined);
 }
+/** The {@link UNKNOWN_FLAG_TOLERANT_COMMANDS} counterpart to {@link throwUnknownFlag}: report, don't refuse. */
+function warnUnknownFlag(shown, known) {
+    warn(`[akm ${known.path.join(" ")}] ignoring unknown flag "${shown}" — run with --help to see its accepted flags.`);
+}
 /**
  * Throw a {@link UsageError} naming the first flag the resolved command does
  * not declare. Returns silently when every flag is known.
@@ -195,6 +208,7 @@ export function assertKnownFlags(root, rawArgs) {
     const dynamicNamedFlagCommands = new Set(["workflow run", "task run", "task explain"]);
     const dynamicWorkflowParams = dynamicNamedFlagCommands.has(known.path.join(" "));
     const selfDiagnosed = SELF_DIAGNOSED_FLAGS.get(known.path.join(" "));
+    const tolerant = UNKNOWN_FLAG_TOLERANT_COMMANDS.has(known.path.join(" "));
     for (let i = 0; i < ownArgs.length; i += 1) {
         const token = ownArgs[i];
         // Not a flag: positional, a bare `-` (stdin), or a negative number.
@@ -209,8 +223,13 @@ export function assertKnownFlags(root, rawArgs) {
             for (let offset = 0; offset < shortFlags.length; offset += 1) {
                 const rawName = shortFlags[offset];
                 const candidate = cittyComparableName(rawName);
-                if (!known.names.has(candidate))
+                if (!known.names.has(candidate)) {
+                    if (tolerant) {
+                        warnUnknownFlag(token, known);
+                        break;
+                    }
                     throwUnknownFlag(token, `-${rawName}`, known);
+                }
                 if (known.valueFlags.has(candidate)) {
                     if (offset === shortFlags.length - 1)
                         i += 1;
@@ -239,6 +258,10 @@ export function assertKnownFlags(root, rawArgs) {
             // frozen plan before a run is inserted. Short flags remain strict.
             if (dynamicWorkflowParams)
                 continue;
+            if (tolerant) {
+                warnUnknownFlag(token.split("=")[0], known);
+                continue;
+            }
             throwUnknownFlag(token.split("=")[0], `--${rawName}`, known);
         }
         // Skip a declared value flag's value so `--reason "--x"` is not scanned.

package/dist/cli.js

@@ -645,6 +645,24 @@ export function shouldBypassConfigStartup(argv) {
     const subcommand = args.slice(configIndex + 1).find((arg) => !arg.startsWith("-"));
     return subcommand === "path";
 }
+/**
+ * Whether `argv` resolves to the top-level `info` command — used by
+ * `runCli` (and mirrored in `tests/_helpers/cli.ts`) to scope the startup
+ * config read's best-effort fallback to `info` alone. `info` is NOT on
+ * {@link shouldBypassConfigStartup}'s allowlist: unlike a bare bypass, it
+ * still reads a valid config's `output.format`/`output.detail` like any
+ * other command, it just must not be aborted by one it cannot read (see
+ * `assembleInfo`'s doc comment, src/commands/sources/info.ts, for why).
+ * Every other command reads config exactly as before — a broken config
+ * throws here and the command never runs.
+ */
+export function isInfoCommand(argv) {
+    const userArgs = argv.slice(2);
+    const separator = userArgs.indexOf("--");
+    const args = separator === -1 ? userArgs : userArgs.slice(0, separator);
+    const commandIndex = findCittyTopLevelCommandIndex(args, MAIN_TOP_LEVEL_ARGS);
+    return (commandIndex >= 0 ? args[commandIndex] : undefined) === "info";
+}
 // ── Exit codes ──────────────────────────────────────────────────────────────
 // Canonical table lives in `src/cli/shared.ts` (EXIT_CODES). These aliases keep
 // the local call sites terse. EXIT_HEALTH_WARN (4) is the `akm health` "warn"
@@ -968,7 +986,34 @@ async function runCli() {
     try {
         applyEarlyStderrFlags(process.argv);
         const bypassConfig = shouldBypassConfigStartup(process.argv);
-        initOutputMode(process.argv, bypassConfig ? (DEFAULT_CONFIG.output ?? {}) : (loadConfig().output ?? {}));
+        // Off the bypass allowlist, every command reads config here exactly as
+        // it always has: an invalid config.json throws, `emitJsonError` reports
+        // it, and the command never runs — no side effect of its own body ever
+        // happens (a lock taken, a network call made, a database opened
+        // read-write). `akm info` is the ONE exception (see `assembleInfo`'s
+        // doc comment, src/commands/sources/info.ts): only ITS read is
+        // best-effort, falling back to `DEFAULT_CONFIG.output` instead of
+        // throwing. Scoped narrowly on purpose — an earlier version of this fix
+        // made the read best-effort for every command, which silently changed
+        // outcomes across the CLI (some commands that should refuse at exit 78
+        // ran anyway; `health`/`index`/`config set`/`feedback` still failed,
+        // but only after already taking a lock, opening a database read-write,
+        // or making a network call).
+        let outputDefaults = DEFAULT_CONFIG.output ?? {};
+        if (!bypassConfig) {
+            if (isInfoCommand(process.argv)) {
+                try {
+                    outputDefaults = loadConfig().output ?? {};
+                }
+                catch {
+                    outputDefaults = DEFAULT_CONFIG.output ?? {};
+                }
+            }
+            else {
+                outputDefaults = loadConfig().output ?? {};
+            }
+        }
+        initOutputMode(process.argv, outputDefaults);
     }
     catch (error) {
         emitJsonError(error);

package/dist/commands/health/archive-usage.js

@@ -25,7 +25,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { MEMORY_ARCHIVE_REL } from "../../core/asset/memory-archive.js";
 import { toPosix } from "../../core/common.js";
-import { isGitBackedStash, tryListGitChangedPaths, tryListGitTrackedPaths, tryListGitUnverifiablePaths, } from "../../sources/providers/git-stash.js";
+import { checkGitPathSafety, isGitBackedStash } from "../../sources/providers/git-stash.js";
 import { MAX_WALK_ENTRIES, sizeOfPath } from "./data-dir-usage.js";
 /**
  * Build the `memory-cleanup-archive` advisory, or `undefined` when there is
@@ -52,23 +52,17 @@ export function collectArchiveUsageAdvisory(stashDir) {
     }
     // Git-backed: the SAME three checks purgeGracedArchive runs (B1, G10) —
     // computed once here, not per file, and reused via `onFile` below instead
-    // of a second walk of the same tree.
-    const dirtyQuery = tryListGitChangedPaths(stashDir);
-    const trackedQuery = tryListGitTrackedPaths(stashDir, MEMORY_ARCHIVE_REL);
-    const unverifiableQuery = tryListGitUnverifiablePaths(stashDir, MEMORY_ARCHIVE_REL);
-    // A failed git check here fails the same way purgeGracedArchive's own
-    // sweep would: nothing in the archive can be proven purgeable, so every
-    // byte counts as unpurgeable rather than guessing.
-    const gitStateKnown = dirtyQuery.ok && trackedQuery.ok && unverifiableQuery.ok;
-    const dirty = new Set(dirtyQuery.paths);
-    const tracked = new Set(trackedQuery.paths);
-    const unverifiable = new Set(unverifiableQuery.paths);
+    // of a second walk of the same tree. A failed git check here fails the
+    // same way purgeGracedArchive's own sweep would: nothing in the archive
+    // can be proven purgeable, so every byte counts as unpurgeable rather
+    // than guessing (`checkGitPathSafety`'s `isSafe` is always `false` when
+    // `ok` is `false`).
+    const gitSafety = checkGitPathSafety(stashDir, MEMORY_ARCHIVE_REL);
     let unpurgeableFiles = 0;
     let unpurgeableBytes = 0;
     const usage = sizeOfPath(archiveRoot, { remaining: MAX_WALK_ENTRIES }, (filePath, bytes) => {
         const key = toPosix(path.relative(stashDir, filePath));
-        const safe = gitStateKnown && tracked.has(key) && !dirty.has(key) && !unverifiable.has(key);
-        if (!safe) {
+        if (!gitSafety.isSafe(key)) {
             unpurgeableFiles++;
             unpurgeableBytes += bytes;
         }
@@ -92,7 +86,7 @@ export function collectArchiveUsageAdvisory(stashDir) {
             truncated: usage.truncated,
             unpurgeableFiles,
             unpurgeableBytes,
-            gitStateKnown,
+            gitStateKnown: gitSafety.ok,
         },
     };
 }

package/dist/commands/health/improve-metrics.js

@@ -53,6 +53,25 @@ export function countAgentFailureReasons(agentFailures) {
     }
     return counts;
 }
+/**
+ * Decode one `improve_runs.result_json` envelope, warning once per row on
+ * failure (mirrors {@link taskFailureDetail}'s handling of the analogous
+ * `task_history` case) and returning `undefined` instead of throwing.
+ * Callers count the `undefined` case themselves (`resultRows.skipped.invalid`
+ * / `resultStatus: "invalid"`) so a decode failure is never silent — the
+ * warning names *why* (corrupt data, or a decoder too strict for a shape an
+ * older release legitimately wrote), the counters say *how many*.
+ */
+function decodeImproveResultRow(row) {
+    try {
+        return decodeImproveResult(row.result_json).envelope;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.warn(`[akm] Skipping unparseable improve_runs row in health metrics (id=${row.id}, started_at=${row.started_at}): ${message}`);
+        return undefined;
+    }
+}
 /** A zeroed accumulator — also what health reports when it could not read state.db at all (#791). */
 export function emptyImproveMetrics() {
     return {
@@ -273,11 +292,8 @@ export function summarizeImproveRuns(db, since, until) {
     // newest complete run's snapshot (current state) — not a sum across runs.
     let latest;
     for (const row of rows) {
-        let result;
-        try {
-            result = decodeImproveResult(row.result_json).envelope;
-        }
-        catch {
+        const result = decodeImproveResultRow(row);
+        if (!result) {
             resultRows.skipped.invalid += 1;
             continue;
         }
@@ -298,13 +314,10 @@ export function summarizeImproveRuns(db, since, until) {
 }
 /** Project an improve_runs row + wall time + task attribution into one {@link ImproveRunSummary}. */
 export function projectImproveRunSummary(row, wallTimeMs, taskId) {
-    let result = {};
-    let resultStatus = "invalid";
-    try {
-        result = decodeImproveResult(row.result_json).envelope;
-        resultStatus = "valid";
-    }
-    catch {
+    const decoded = decodeImproveResultRow(row);
+    const result = decoded ?? {};
+    const resultStatus = decoded ? "valid" : "invalid";
+    if (!decoded) {
         // Keep the persisted row visible in per-run output, but do not project its
         // unknown payload or admit its duration to result-derived denominators.
         wallTimeMs = 0;

package/dist/commands/improve/memory/memory-improve.js

@@ -12,7 +12,7 @@ import { DERIVED_SUFFIX } from "../../../core/recognition-util.js";
 import { warn } from "../../../core/warn.js";
 import { recordWrittenPath } from "../../../core/write-provenance.js";
 import { walkMarkdownFiles } from "../../../indexer/walk/walker.js";
-import { isGitBackedStash, tryListGitChangedPaths, tryListGitTrackedPaths, tryListGitUnverifiablePaths, } from "../../../sources/providers/git-stash.js";
+import { checkGitPathSafety, isGitBackedStash } from "../../../sources/providers/git-stash.js";
 import { contentHash } from "../content-hash.js";
 import { isDerivedMemory, memoryIdentityRef, parseMemoryName, resolveParentRef } from "./derived-ref.js";
 export function analyzeMemoryCleanup(stashDir, options = {}) {
@@ -665,20 +665,16 @@ export function purgeGracedArchive(stashDir, now = new Date()) {
     // sweep rather than silently trusting whichever check happened to
     // succeed — a `dirty`/`unverifiable` set that came back empty ONLY
     // because the call failed must never read as "nothing to protect".
-    const dirtyQuery = tryListGitChangedPaths(stashDir);
-    const trackedQuery = tryListGitTrackedPaths(stashDir, MEMORY_ARCHIVE_REL);
-    const unverifiableQuery = tryListGitUnverifiablePaths(stashDir, MEMORY_ARCHIVE_REL);
-    if (!dirtyQuery.ok || !trackedQuery.ok || !unverifiableQuery.ok) {
+    // G10: assume-unchanged / skip-worktree files never show up as dirty even
+    // when genuinely modified — `checkGitPathSafety` treats them the same as
+    // "not tracked" below, so such a file (and its whole retirement) is left
+    // for a later sweep.
+    const gitSafety = checkGitPathSafety(stashDir, MEMORY_ARCHIVE_REL);
+    if (!gitSafety.ok) {
         warn(`[improve] archive purge: skipped this sweep — could not determine the archive's git state at ${stashDir} ` +
             "(git status/ls-files failed); nothing was purged.");
         return EMPTY_ARCHIVE_PURGE_RESULT;
     }
-    const dirty = new Set(dirtyQuery.paths);
-    const tracked = new Set(trackedQuery.paths);
-    // G10: assume-unchanged / skip-worktree files never show up as dirty even
-    // when genuinely modified — treated the same as "not tracked" below, so
-    // such a file (and its whole retirement) is left for a later sweep.
-    const unverifiable = new Set(unverifiableQuery.paths);
     let purgedDirs = 0;
     let purgedFiles = 0;
     for (const entry of entries) {
@@ -705,10 +701,7 @@ export function purgeGracedArchive(stashDir, now = new Date()) {
         if (!Number.isFinite(retiredMs) || retiredMs >= cutoffMs)
             continue; // "more than" the grace period — exactly at it is not enough
         const allFiles = listFilesRecursive(dir); // tombstone included — the whole entry must be a clean, committed unit
-        const isSafeToPurge = allFiles.every((filePath) => {
-            const key = toPosix(path.relative(stashDir, filePath));
-            return tracked.has(key) && !dirty.has(key) && !unverifiable.has(key);
-        });
+        const isSafeToPurge = allFiles.every((filePath) => gitSafety.isSafe(toPosix(path.relative(stashDir, filePath))));
         if (!isSafeToPurge)
             continue; // untracked, modified, or unverifiable entry — skip the whole directory this sweep (B1, G10)
         let children;

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(", ")}`);
   }

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(", ")}`);
   }

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) {