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

package/CHANGELOG.md

@@ -4,6 +4,48 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [0.9.8-beta.3] - 2026-09-02
+
+### Fixed
+
+- **The incremental index no longer misses an edit whose timestamp did not move
+  forward.** The per-directory freshness check summarised a directory as its
+  file-name set plus the single newest mtime, which lost two kinds of change.
+  An edit to any file other than the newest one landed below that maximum and
+  was invisible even though its own mtime changed — so a restore, checkout, or
+  archive extraction that stamped a plausible older date left stale content in
+  the index. And because mtime is writable by ordinary tooling (`touch -r`,
+  `rsync --times`, `cp -p`), an edit with a restored timestamp was invisible
+  outright. The directory is now digested per file over
+  `(basename, size, mtime, ctime)` at nanosecond resolution. It is the same one
+  `stat` call per file, so the incremental fast path costs what it did before.
+  Both gaps predate 0.9.8 and applied to every earlier release.
+
+  Trade-off worth knowing: `ctime` also moves on metadata-only changes such as
+  `chmod`, and after copying a tree, so those now cost one extra rescan. That
+  direction is deliberate — extra work, never stale content. Existing indexes
+  rescan once as the digest changes shape, then return to the fast path.
+
+- **`akm migrate apply` can now clear a legacy `extraParams` config.** A config
+  still carrying a liftable key such as `extraParams.temperature` fails config
+  load closed, and that error names `akm migrate apply` as the fix — but the
+  migrate command resolved the stash directory and ran the task migrator, both
+  of which load config, so it died on the very error it exists to clear. An
+  operator hitting this had no reachable way forward. The config lift now runs
+  before anything that loads config, and `akm migrate status` reports the
+  pending lift as its blocker instead of re-raising the same error. A genuine
+  conflict, where an `extraParams` key and its first-class field disagree, still
+  hard-rejects and names both values rather than guessing.
+
+- **`akm health` no longer warns about disk usage on a fresh install.** The
+  `data-dir-usage` advisory added earlier in 0.9.8 counted SQLite's `-wal` and
+  `-shm` sidecars toward the data directory's total but not toward the live
+  databases they belong to. On an untouched install the write-ahead log is most
+  of the directory, so the very first `akm health` reported a ~126x ratio and
+  exited `warn` with no user data present. Sidecars now count as part of their
+  database, and the advisory stays quiet below 1 GB, where a ratio says nothing
+  useful about disk pressure.
+
 ## [0.9.8-beta.2] - 2026-09-02
 
 > **Adds state migration `026-proposals-strip-legacy-fragment-refs`.** The

package/dist/commands/health/data-dir-usage.js

@@ -42,7 +42,22 @@ const DOMINANT_SUBDIR_PERCENT_THRESHOLD = 50;
  * figures are a lower bound.
  */
 const MAX_WALK_ENTRIES = 100_000;
+/**
+ * Below this the data dir is not worth an opinion. The advisory exists for
+ * disk blowups (74 GB in the incident); on a small directory a ratio is
+ * arithmetic noise, and akm's own housekeeping can dominate it outright.
+ */
+const MIN_TOTAL_BYTES_TO_REPORT = 1_000_000_000;
 const LIVE_DB_FILES = ["state.db", "index.db", "logs.db"];
+/**
+ * SQLite writes `-wal` and `-shm` beside each database. They are part of the
+ * live working set, not overhead sitting next to it, so they must count as
+ * live: on a fresh install the WAL is most of the data dir, and leaving it
+ * out of the denominator made an empty install report a ~126x ratio.
+ */
+function liveDbBytesFor(name, sizes) {
+    return ((sizes.get(name)?.bytes ?? 0) + (sizes.get(`${name}-wal`)?.bytes ?? 0) + (sizes.get(`${name}-shm`)?.bytes ?? 0));
+}
 /**
  * Recursively sum file sizes under `root` (stat-only, symlinks not
  * followed so a cyclic or huge-target symlink can't blow up the walk).
@@ -127,9 +142,11 @@ export function collectDataDirUsageAdvisory(dataDir) {
         .map(([name, size]) => ({ name, bytes: size.bytes, percent: (size.bytes / totalBytes) * 100 }))
         .sort((a, b) => b.bytes - a.bytes);
     const largest = subdirs[0];
-    const liveDbBreakdown = Object.fromEntries(LIVE_DB_FILES.map((f) => [f, sizes.get(f)?.bytes ?? 0]));
+    const liveDbBreakdown = Object.fromEntries(LIVE_DB_FILES.map((f) => [f, liveDbBytesFor(f, sizes)]));
     const liveDbBytes = Object.values(liveDbBreakdown).reduce((a, b) => a + b, 0);
     const ratio = liveDbBytes > 0 ? totalBytes / liveDbBytes : undefined;
+    if (totalBytes < MIN_TOTAL_BYTES_TO_REPORT)
+        return undefined;
     const bloatWarn = ratio !== undefined && ratio > DATA_DIR_BLOAT_RATIO_THRESHOLD;
     const dominantWarn = largest !== undefined && largest.percent > DOMINANT_SUBDIR_PERCENT_THRESHOLD;
     if (!bloatWarn && !dominantWarn)

package/dist/commands/migrate-cli.js

@@ -3,6 +3,7 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import { defineGroupCommand, defineJsonCommand, EXIT_CODES, output } from "../cli/shared.js";
 import { resolveStashDir } from "../core/common.js";
+import { resetConfigCache } from "../core/config/config.js";
 import { ConfigError } from "../core/errors.js";
 import { getConfigPath } from "../core/paths.js";
 import { applyConfigExtraParamsLift, findConfigExtraParamsLift } from "./migrate/config-extra-params.js";
@@ -94,6 +95,29 @@ export async function runMigrateSubcommand(command, genOneArgs, genTwoArgs, runT
     // No configured bundle means there is no stash to scan — an empty domain,
     // not an error — so migrate still works before `akm bundle create`. Any
     // OTHER ConfigError propagates.
+    const configPath = getConfigPath();
+    const applyResidue = command === "migrate-apply" && !genOneArgs.includes("--dry-run");
+    // The config lift runs BEFORE anything that loads config. A config still
+    // carrying legacy extraParams keys fails `loadConfig` closed, and the error
+    // it fails with names `akm migrate apply` as the remedy -- but both
+    // `resolveStashDir` below and the task migrator itself load config, so that
+    // remedy could never reach the lift that fixes it. Applying it first is what
+    // makes the advice true. `resetConfigCache` so every load below sees the
+    // rewritten file rather than the rejected one.
+    const configExtraParams = applyResidue
+        ? applyConfigExtraParamsLift(configPath)
+        : { pending: findConfigExtraParamsLift(configPath) };
+    if (applyResidue && configExtraParams.applied)
+        resetConfigCache();
+    // status and --dry-run cannot rewrite the file, so a pending lift still
+    // blocks every config load below. Report it as the blocker rather than
+    // letting the operator hit the same circular error again.
+    const pendingLift = applyResidue ? undefined : configExtraParams.pending;
+    if (pendingLift && pendingLift.lifted.length > 0) {
+        output(command, { status: "blocked", blockers: pendingLift.lifted, configExtraParams });
+        process.exitCode = EXIT_CODES.GENERAL;
+        return;
+    }
     let stashDir;
     try {
         stashDir = resolveStashDir();
@@ -102,8 +126,6 @@ export async function runMigrateSubcommand(command, genOneArgs, genTwoArgs, runT
         if (!(error instanceof ConfigError) || error.code !== "STASH_DIR_NOT_FOUND")
             throw error;
     }
-    const configPath = getConfigPath();
-    const applyResidue = command === "migrate-apply" && !genOneArgs.includes("--dry-run");
     const first = await callMigrateTool(genOneArgs, runTool);
     if (first.status !== EXIT_CODES.SUCCESS && first.status !== EXIT_CODES.GENERAL) {
         process.exitCode = first.status;
@@ -133,9 +155,6 @@ export async function runMigrateSubcommand(command, genOneArgs, genTwoArgs, runT
                 ? { recovered: await recoverStaleTxns(stashDir) }
                 : { pending: findStaleTxnEntries(stashDir) },
         };
-    const configExtraParams = applyResidue
-        ? applyConfigExtraParamsLift(configPath)
-        : { pending: findConfigExtraParamsLift(configPath) };
     output(command, { ...combined, ...stashSections, configExtraParams });
     if (combined.status === "blocked")
         process.exitCode = EXIT_CODES.GENERAL;

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

@@ -17,8 +17,10 @@
  * `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";
 /**
@@ -44,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 },
@@ -68,11 +68,8 @@ export function getDirIndexState(db, dirPath, files, builtAtMs, indexVariant = "
  */
 export function getCachedDirState(db, dirPath, files, builtAtMs, priorDirsChanged, indexVariant, fingerprint) {
     const cached = getIndexDirState(db, dirPath);
-    if (!cached ||
-        cached.fileSetHash !== fingerprint.fileSetHash ||
-        cached.fileMtimeMaxMs !== fingerprint.fileMtimeMaxMs) {
+    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 };
     }
@@ -89,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.9.8-beta.2",
+  "version": "0.9.8-beta.3",
   "type": "module",
   "description": "akm (Agent Knowledge Manager) — a portable, local-first capability library for AI agents. Discover, load, share, and improve reusable skills, scripts, workflows, and knowledge across any shell-capable coding agent, including Claude Code, OpenCode, and Cursor.",
   "keywords": [