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

package/CHANGELOG.md

@@ -4,6 +4,63 @@ 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.2] - 2026-09-02
+
+> **Adds state migration `026-proposals-strip-legacy-fragment-refs`.** The
+> one-way caveat below applies to it as well: once this build opens
+> `state.db`, 0.9.8-beta.1 and earlier refuse it with `unknown migration ID
+> 026-proposals-strip-legacy-fragment-refs`.
+
+### Added
+
+- **`akm health` reports data-dir disk usage** (#896). A `data-dir-usage`
+  advisory sums the data directory with a stat-only walk and warns when it is
+  more than 3× the three live databases (state.db, index.db, logs.db) or when
+  one top-level subdirectory holds more than half of it, naming that
+  subdirectory with its size and share (for example `backups/ is 70G (94% of
+  data dir)`). The walk stops after 100,000 entries and says so. Silent when
+  nothing looks wrong.
+
+### Fixed
+
+- **`akm task sync` no longer spawns `npm root --global` on every call** (#901).
+  The npm-global-root probe behind `resolveAkmInvocation` is memoized for the
+  process, so a `task sync --rebind` cycle spawns npm at most once instead of
+  twice, and an installation that loops it every minute stops accumulating an
+  npm debug log per spawn.
+- **A blocked v2 task now says how to convert it** (#902, #899). The
+  `argv-array-has-no-portable-shell-string` blocker printed by `akm migrate`
+  and the `TASK_SCHEMA_VERSION_UNSUPPORTED` read error now state that manual
+  conversion is required and name the rewrite (`command:` argv array →
+  `run:` string plus `shell:`). The full v2 → v4 field mapping is documented in
+  `docs/migration/v0.9.1-to-v0.9.2.md`.
+- **Legacy `#fragment` proposal rows are repaired instead of warned about
+  forever** (#898). State migration 026 strips the retired export-fragment
+  selector from `proposals.ref` in place so the rows parse again, and an
+  unparseable proposal row now warns once per process instead of once per
+  read (`akm health --report` read the table seven times).
+
+- **A no-op incremental `akm index` no longer costs minutes of CPU** (#900).
+  Two causes: the per-directory freshness check ran two full scans of the
+  `entries` table for every directory (O(directories × entries)), and every
+  file was read, hashed, and parsed before the freshness check decided the
+  directory was unchanged. The directory lookup now uses the existing
+  `file_path` index, and a stat-based gate over each directory's walked file
+  set skips unchanged directories before any file is read. On a synthetic
+  800-directory, 4,000-entry corpus a no-op pass fell from ~37 s to under 1 s
+  of CPU with identical entries and search results. The persisted directory
+  fingerprint now covers every walked file and `index_dir_state` gains a
+  `row_count` column; an existing index.db drains each directory once more
+  after upgrading, then takes the fast path.
+
+- **Task-migration snapshots are capped at the five most recent** (#897).
+  `akm migrate apply` writes one snapshot directory per run under
+  `backups/task-v3` and `backups/task-v4` and never pruned them; each apply
+  now keeps the five newest and removes the rest, the same policy config
+  backups already use. Nothing in the current code writes the legacy
+  `backups/migrations`, `manual`, `releases`, or `operations` directories,
+  so they are left alone; the new health advisory is what surfaces them.
+
 ## [0.9.8-beta.1] - 2026-09-01
 
 A cleanup and stabilization release: deletion of machinery that policed the
@@ -11,10 +68,45 @@ codebase's shape rather than its behaviour, and — because auditing for that
 machinery meant reading the code closely — a run of real defects it had been
 sitting on top of.
 
+> **Upgrading is one-way for `state.db`.** This release adds migration
+> `025-task-history-vocabulary-backfill`. Once any 0.9.8 command opens
+> `state.db`, the ledger contains an ID that 0.9.7 does not know, and 0.9.7
+> refuses to open it: `Refusing to open a database with a newer migration
+> ledger: unknown migration ID 025-task-history-vocabulary-backfill`.
+>
+> The refusal is deliberate — an older binary must not write a database whose
+> schema it cannot reason about — but the practical effect is that
+> **downgrading to 0.9.7 requires restoring a `state.db` backup.** Commands
+> that only read the derived index (`akm info`, `akm search`) keep working on
+> 0.9.7; everything that touches `state.db` (`akm health`, `akm task`,
+> `akm improve`, proposals) does not.
+>
+> Snapshot `state.db` before upgrading if you may need to go back:
+>
+> ```sh
+> akm info --format json    # confirm your data dir
+> sqlite3 "$DATA_DIR/state.db" "VACUUM INTO '''state.db.pre-0.9.8.bak'''"
+> ```
+
 Two security holes, two search-correctness bugs, a locale-dependent hash, a
 deletion shield that failed open, and sixteen places that answered a failure
 with a confident wrong answer instead of an error.
 
+### Changed
+
+- **`akm workflow plan` returns JSON by default**, like every other command
+  (#903). It was the one verb whose unmarked default was a human summary. That
+  exception cost a bespoke branch which could not reliably distinguish "no
+  format named" from "`--format json` named globally before the subcommand" —
+  citty parses each command level against its own argv, so the leaf read
+  `undefined` in both cases. Working around that meant reading the invocation
+  singleton, folding in a persisted `output.format`, and finally leaving a
+  resolved `"json"` on the text branch because it was indistinguishable from
+  "nothing configured" — which meant an explicit `--format json` silently did
+  nothing for anyone whose config already resolved to json. Deleted, along with
+  ~60 lines of comment justifying it. `--format text` still renders the same
+  summary through the same formatter; it is simply no longer the default.
+
 ### Fixed
 
 - **Historical state migrations are reachable where akm cannot reinstall

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

@@ -0,0 +1,165 @@
+// 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/.
+/**
+ * `data-dir-usage` advisory for `akm health` (#896).
+ *
+ * A real environment's `$XDG_DATA_HOME/akm` grew to 74 GB with none of the
+ * ~20 health checks saying a word about disk. 70 of the 74 GB turned out to
+ * be `backups/` (unpruned migration snapshots, see #897); the live working
+ * set (state.db + index.db + logs.db) was ~4.2 GB. Naming the largest
+ * top-level contributor and its share of the total is most of the value —
+ * `backups/ is 70G (94% of data dir)` is self-diagnosing where "akm health
+ * says nothing" is not.
+ *
+ * Best-effort and read-only: a plain recursive `fs` stat walk over the data
+ * dir, no `du` shell-out. Silent (returns `undefined`) whenever nothing
+ * looks wrong, matching the stash-exposure/type-directory-check house
+ * pattern — this is not a "always show a pass line" check.
+ */
+import fs from "node:fs";
+import path from "node:path";
+/**
+ * Warn when the data dir's total size is more than this many times the
+ * combined size of the three live databases (state.db + index.db +
+ * logs.db). Chosen so a healthy install (backups roughly comparable to the
+ * live working set) stays quiet, while an order-of-magnitude blowup like
+ * the 74 GB/4.2 GB (~17x) incident trips it.
+ */
+const DATA_DIR_BLOAT_RATIO_THRESHOLD = 3;
+/**
+ * Warn when a single top-level subdirectory accounts for more than this
+ * percentage of the data dir's total size — the "one thing ate the disk"
+ * signal (94% for `backups/` in the incident).
+ */
+const DOMINANT_SUBDIR_PERCENT_THRESHOLD = 50;
+/**
+ * Cap on the number of filesystem entries the recursive size walk will
+ * `stat`. A 70 GB tree of a few thousand backup copies is cheap to walk
+ * (stat-only), but a data dir polluted with hundreds of thousands of small
+ * files (task logs, npm logs) must not make `akm health` slow. Past this
+ * cap the walk stops descending further and the advisory says its size
+ * figures are a lower bound.
+ */
+const MAX_WALK_ENTRIES = 100_000;
+const LIVE_DB_FILES = ["state.db", "index.db", "logs.db"];
+/**
+ * Recursively sum file sizes under `root` (stat-only, symlinks not
+ * followed so a cyclic or huge-target symlink can't blow up the walk).
+ * `budget` is a shared mutable counter across the whole tree so the
+ * `MAX_WALK_ENTRIES` cap applies to the walk as a whole, not per-branch.
+ */
+function sizeOfPath(root, budget) {
+    let stat;
+    try {
+        stat = fs.lstatSync(root);
+    }
+    catch {
+        return { bytes: 0, truncated: false };
+    }
+    if (stat.isSymbolicLink())
+        return { bytes: 0, truncated: false };
+    if (!stat.isDirectory())
+        return { bytes: stat.size, truncated: false };
+    let entries;
+    try {
+        entries = fs.readdirSync(root, { withFileTypes: true });
+    }
+    catch {
+        return { bytes: 0, truncated: false };
+    }
+    let bytes = 0;
+    let truncated = false;
+    for (const entry of entries) {
+        if (budget.remaining <= 0) {
+            truncated = true;
+            break;
+        }
+        budget.remaining--;
+        const sub = sizeOfPath(path.join(root, entry.name), budget);
+        bytes += sub.bytes;
+        if (sub.truncated)
+            truncated = true;
+    }
+    return { bytes, truncated };
+}
+/** `1610612736` -> `"1.5G"`. Values under 10 in a unit keep one decimal; 10+ round to an integer. */
+function formatBytes(bytes) {
+    const units = ["B", "K", "M", "G", "T"];
+    let value = bytes;
+    let unit = 0;
+    while (value >= 1024 && unit < units.length - 1) {
+        value /= 1024;
+        unit++;
+    }
+    const rendered = unit === 0 ? String(Math.round(value)) : value < 10 ? value.toFixed(1) : String(Math.round(value));
+    return `${rendered}${units[unit]}`;
+}
+/**
+ * Build the `data-dir-usage` advisory, or `undefined` when the data dir is
+ * missing/empty/unreadable or its size looks unremarkable (neither
+ * threshold trips). `dataDir` is the caller-resolved `getDataDir()` path —
+ * this module never resolves paths or reads env itself.
+ */
+export function collectDataDirUsageAdvisory(dataDir) {
+    let topEntries;
+    try {
+        topEntries = fs.readdirSync(dataDir, { withFileTypes: true });
+    }
+    catch {
+        return undefined; // no data dir yet — nothing to report.
+    }
+    const budget = { remaining: MAX_WALK_ENTRIES };
+    let totalBytes = 0;
+    let truncated = false;
+    const sizes = new Map();
+    for (const entry of topEntries) {
+        const size = sizeOfPath(path.join(dataDir, entry.name), budget);
+        totalBytes += size.bytes;
+        if (size.truncated)
+            truncated = true;
+        sizes.set(entry.name, { bytes: size.bytes, isDirectory: entry.isDirectory() });
+    }
+    if (totalBytes === 0)
+        return undefined;
+    const subdirs = [...sizes]
+        .filter(([, size]) => size.isDirectory)
+        .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 liveDbBytes = Object.values(liveDbBreakdown).reduce((a, b) => a + b, 0);
+    const ratio = liveDbBytes > 0 ? totalBytes / liveDbBytes : undefined;
+    const bloatWarn = ratio !== undefined && ratio > DATA_DIR_BLOAT_RATIO_THRESHOLD;
+    const dominantWarn = largest !== undefined && largest.percent > DOMINANT_SUBDIR_PERCENT_THRESHOLD;
+    if (!bloatWarn && !dominantWarn)
+        return undefined;
+    const parts = [`data dir is ${formatBytes(totalBytes)} at ${dataDir}`];
+    if (largest) {
+        parts.push(`${largest.name}/ is ${formatBytes(largest.bytes)} (${Math.round(largest.percent)}% of data dir)`);
+    }
+    if (ratio !== undefined) {
+        parts.push(`live databases (${LIVE_DB_FILES.join("+")}) total ${formatBytes(liveDbBytes)}, ~${ratio.toFixed(1)}x smaller`);
+    }
+    if (truncated) {
+        parts.push(`size figures are a lower bound — the walk stopped after ${MAX_WALK_ENTRIES} entries`);
+    }
+    const message = `${parts.join("; ")}.`;
+    return {
+        name: "data-dir-usage",
+        kind: "deterministic",
+        status: "warn",
+        confidence: "medium",
+        message,
+        evidence: {
+            dataDir,
+            totalBytes,
+            liveDbBytes,
+            liveDbBreakdown,
+            largestSubdir: largest,
+            ratio,
+            walkBounded: truncated,
+            maxWalkEntries: MAX_WALK_ENTRIES,
+        },
+    };
+}

package/dist/commands/health.js

@@ -9,7 +9,7 @@ import { ConfigError, UsageError } from "../core/errors.js";
 import { readEvents } from "../core/events.js";
 import { openLogsDatabase } from "../core/logs-db.js";
 import { classifyPathAccess, describeInaccessiblePath } from "../core/path-access.js";
-import { getConfigPath, getDbPath, getStateDbPathInDataDir } from "../core/paths.js";
+import { getConfigPath, getDataDir, getDbPath, getStateDbPathInDataDir } from "../core/paths.js";
 import { listExistingTableNames, openStateDatabase } from "../core/state-db.js";
 import { DURATION_UNITS, parseDuration, parseSinceToIso } from "../core/time.js";
 import { closeDatabase, openReadonlyExistingDatabase } from "../storage/repositories/index-connection.js";
@@ -18,6 +18,7 @@ import { queryTaskHistory } from "../storage/repositories/task-history-repositor
 import { pkgVersion } from "../version.js";
 import { collectImproveAdvisories } from "./health/advisories.js";
 import { HEALTH_CHECKS, runHealthEngineProbes } from "./health/checks.js";
+import { collectDataDirUsageAdvisory } from "./health/data-dir-usage.js";
 import { buildImproveSkipSummary, computeWallTimeStats, isAgentTaskHistoryRow, roundRate, summarizeImproveCompleted, summarizeImproveRuns, taskFailureDetail, } from "./health/improve-metrics.js";
 import { emptyLlmUsageAggregate, readLlmUsageAggregate } from "./health/llm-usage.js";
 import { computeDegradationMetrics, computeDenominatorFixedCoverage, computeEnrichmentMintingRollup, probeStateDbRoundTrip, } from "./health/metrics.js";
@@ -197,9 +198,10 @@ function gatherImproveSummaryPhase(db, stateDbPath, since, now) {
     return { improveSummary, perRunSummaries };
 }
 /**
- * The four best-effort advisory groups beyond the health-check registry:
- * improve advisories, the `stash-git-exposure` probe, the 08 surfaces group
- * (binary-config-skew, egress-endpoints), and `plugin-version` (itlackey/akm#832).
+ * The best-effort advisory groups beyond the health-check registry: improve
+ * advisories, the `stash-git-exposure` probe, the 08 surfaces group
+ * (binary-config-skew, egress-endpoints), `type-directory-disagreement`
+ * (#831), `data-dir-usage` (#896), and `plugin-version` (itlackey/akm#832).
  * Order matches emission order in the returned array. A probe/filesystem
  * failure in any try/catch must not abort the health report — each group
  * degrades to "no advisory" independently.
@@ -251,6 +253,19 @@ function gatherAncillaryAdvisories(db, stateDbPath, since, improveSummary, optio
     catch {
         // Non-fatal.
     }
+    // #896: report the data dir's total size and its largest top-level
+    // subdirectory, so a disk-usage blowup (e.g. unpruned migration snapshot
+    // backups, #897) is self-diagnosing instead of requiring `du` archaeology.
+    // Best-effort — an unreadable/missing data dir must not abort the health
+    // report.
+    try {
+        const dataDirUsage = collectDataDirUsageAdvisory(getDataDir());
+        if (dataDirUsage)
+            advisories.push(dataDirUsage);
+    }
+    catch {
+        // Non-fatal.
+    }
     // itlackey/akm#832: report installed Claude Code harness plugin version(s)
     // and warn when stale or when the plugin's own akm-cli version range no
     // longer admits this CLI. Best-effort — no plugin installed, an unreadable

package/dist/commands/workflow-cli.js

@@ -7,18 +7,12 @@
  * `create --print` emits Markdown; execution accepts peer `.md` and
  * GitHub-shaped `.yml` workflow sources. Validate with `akm lint --type workflows`.
  */
-import { getParsedInvocation } from "../cli/invocation.js";
 import { getStringArg } from "../cli/parse-args.js";
 import { defineGroupCommand, defineJsonCommand, EXIT_CODES, output } from "../cli/shared.js";
 import { armAbortDeadline } from "../core/abort-deadline.js";
 import { assertFlatAssetName, combineCreatePath, normalizeCreateSubPath } from "../core/asset/asset-create.js";
 import { NotFoundError, UsageError } from "../core/errors.js";
 import { akmIndex } from "../indexer/indexer.js";
-import { getOutputMode } from "../output/context.js";
-import { renderGenericText } from "../output/generic-render.js";
-import { deliverRendered } from "../output/html-render.js";
-import { shapeForCommand } from "../output/shapes.js";
-import { formatPlain } from "../output/text.js";
 import { assertWorkflowMarkdownName, createWorkflowAsset, getWorkflowTemplate } from "../workflows/authoring/authoring.js";
 import { WORKFLOW_MAX_TIMEOUT_MS } from "../workflows/ir/schema.js";
 import { abandonWorkflowRun, getWorkflowStatus, hasWorkflowRun, listWorkflowRuns, resumeWorkflowRun, } from "../workflows/runtime/runs.js";
@@ -319,61 +313,17 @@ const workflowPlanCommand = defineJsonCommand({
     },
     async run({ args }) {
         const result = await akmWorkflowPlan(args.ref);
-        // B-46/B-57: `akm workflow plan` is read-only introspection whose UNMARKED
-        // default is a human summary — `--format json` (B-N9) is the opt-in for
-        // the full structure, the mirror image of every other verb's json-by-
-        // default (DEFAULT_CONFIG.output.format).
-        //
-        // Detecting "the caller named no format at all" MUST NOT read
-        // `args.format` (code-review round 4, finding 3 / Review log R3):
-        // citty's one-parse rule (GLOBAL_OUTPUT_ARGS's own doc comment, "no
-        // command body may read these args") isn't just style here — reading it
-        // is actively wrong. citty parses each command level against only that
-        // level's own remaining argv, so a GLOBAL, pre-subcommand `--format json`
-        // (e.g. `akm --format json workflow plan <ref>`) is consumed by the ROOT
-        // command's own declared `format` arg before the `workflow`/`plan`
-        // subcommand tokens are even resolved — this LEAF's `args.format` reads
-        // `undefined` in exactly that case too, indistinguishable from "no
-        // format was named anywhere". Reproduced live: that invocation printed
-        // the human TEXT summary at exit 0 even though `getOutputMode().format`
-        // was already `"json"` (the control, `akm --format json workflow list`,
-        // correctly emitted JSON — only this leaf's own arg-read was wrong).
-        // Detect it instead off the process-wide invocation singleton
-        // (`getParsedInvocation`, src/cli/invocation.ts) — the same canonical,
-        // position-independent argv parse `src/cli.ts` mints ONCE at startup
-        // (`setParsedInvocation`, immediately before `initOutputMode` builds the
-        // `getOutputMode()` singleton from that identical argv), so this agrees
-        // with `getOutputMode()` regardless of where `--format` appeared. A bare
-        // `process.argv` read is reserved for `src/cli.ts`/`cli/invocation.ts`
-        // themselves (`lint-process-argv.ts`); every other module reads through
-        // this singleton instead. When explicit, this defers to the normal
-        // `output()` path (json/yaml/text/md/html/jsonl, `--output <path>`)
-        // unchanged; when absent, it reproduces `output()`'s OWN "text" branch
-        // verbatim (same shape/detail projection, same registered-formatter-or-
-        // generic-fallback, same `--output <path>` handling) without touching
-        // the shared dispatcher other commands rely on.
-        //
-        // "No format named anywhere" also has to check the RESOLVED mode, not
-        // just argv: `getOutputMode().format` already folds a persisted
-        // `output.format` config default in ahead of the hardcoded "json"
-        // fallback (`resolveOutputMode`, src/output/context.ts — argv ?? config
-        // default ?? "json"). A user who has configured e.g. `output.format:
-        // "yaml"` gets yaml from every other command with no `--format` on the
-        // line; `workflow plan` must honor that too instead of forcing its
-        // human-text branch over a real persisted default. A resolved format of
-        // exactly "json" is deliberately left on the text branch below: it's
-        // indistinguishable from "nothing configured" (DEFAULT_CONFIG.output.format
-        // is also "json" — OutputConfigSchema's `format` carries no independent
-        // zod default, so the merge is the only source), and collapsing that case
-        // onto the JSON envelope would erase the documented unmarked-default text
-        // summary for the overwhelmingly common "user configured nothing" case.
-        const mode = getOutputMode();
-        if (getParsedInvocation().getFlagValue("--format") === undefined && mode.format === "json") {
-            const shaped = shapeForCommand("workflow-plan", result, mode.detail, mode.shape);
-            const plain = formatPlain("workflow-plan", shaped, mode.detail);
-            deliverRendered(plain ?? renderGenericText("workflow-plan", shaped), mode.outputPath);
-            return;
-        }
+        // json-by-default, like every other verb (#903). This used to default to
+        // the human summary, which cost ~60 lines of branch: `args.format` cannot
+        // detect "no format named" (citty parses per level, so a global
+        // pre-subcommand `--format json` is eaten by the ROOT command and the leaf
+        // reads undefined), so it had to route through `getParsedInvocation()`,
+        // then fold in a persisted `output.format`, and then still leave a
+        // resolved "json" on the text branch because that is indistinguishable
+        // from "nothing configured". The last compromise meant an explicit
+        // `--format json` silently did nothing for anyone whose config already
+        // resolved to json. `--format text` still renders the summary through the
+        // registered formatter; it is just no longer the unmarked default.
         output("workflow-plan", result);
     },
 });

package/dist/core/config/config-io.js

@@ -115,17 +115,30 @@ export function backupExistingConfig(configPath, now = new Date()) {
     return { timestamped, latest };
 }
 function pruneOldBackups(backupDir) {
+    pruneToNewest(backupDir, MAX_CONFIG_BACKUPS, (entry) => entry.isFile() && isTimestampedConfigBackup(entry.name));
+}
+function isTimestampedConfigBackup(name) {
+    return name.startsWith("config-") && name.endsWith(".json") && name !== "config.latest.json";
+}
+/**
+ * Keep the `keep` most-recently-modified entries of `dir` that `select`
+ * admits and remove the rest. Best-effort: an unreadable dir is a no-op, an
+ * unreadable entry sorts oldest (pruned first), and a failed removal is
+ * retried by the next call. Shared by the config backups above and the task
+ * migration snapshots (#897).
+ */
+export function pruneToNewest(dir, keep, select) {
     let entries;
     try {
-        entries = fs.readdirSync(backupDir);
+        entries = fs.readdirSync(dir, { withFileTypes: true });
     }
     catch {
         return;
     }
-    const timestamped = entries
-        .filter((n) => n.startsWith("config-") && n.endsWith(".json") && n !== "config.latest.json")
-        .map((name) => {
-        const full = path.join(backupDir, name);
+    const candidates = entries
+        .filter(select)
+        .map((entry) => {
+        const full = path.join(dir, entry.name);
         let mtime = 0;
         try {
             mtime = fs.statSync(full).mtimeMs;
@@ -136,12 +149,12 @@ function pruneOldBackups(backupDir) {
         return { path: full, mtime };
     })
         .sort((a, b) => b.mtime - a.mtime);
-    for (const stale of timestamped.slice(MAX_CONFIG_BACKUPS)) {
+    for (const stale of candidates.slice(keep)) {
         try {
-            fs.unlinkSync(stale.path);
+            fs.rmSync(stale.path, { recursive: true, force: true });
         }
         catch {
-            // Best-effort prune; next save will retry.
+            // Best-effort prune; the next call will retry.
         }
     }
 }

package/dist/core/state/migrations.js

@@ -36,6 +36,7 @@ export const STATE_MIGRATION_SAFETY_BY_ID = Object.freeze({
     "023-child-workflow-runs": "additive",
     "024-workflow-run-outputs": "additive",
     "025-task-history-vocabulary-backfill": "data-preserving-rebuild",
+    "026-proposals-strip-legacy-fragment-refs": "data-preserving-rebuild",
 });
 export const STATE_MIGRATIONS = [
     // ── Migration 001 — initial schema ──────────────────────────────────────────
@@ -1127,6 +1128,27 @@ export const STATE_MIGRATIONS = [
         AND json_extract(metadata_json, '$.targetVocab') IS NULL;
     `,
     },
+    // ── Migration 026 — strip the retired proposal-ref export fragment (#898) ──
+    //
+    // Older releases could write a proposal `ref` carrying the export-fragment
+    // selector (`[bundle//]conceptId#fragment`, see src/core/asset/asset-ref.ts).
+    // `currentProposalRef` (proposals-repository.ts) now rejects any fragment, so
+    // those rows failed to parse on every read and could not be listed, repaired,
+    // or deleted through the CLI. Every surface that still reads an archived row
+    // is concept-scoped, so the fragment carries nothing they use.
+    //
+    // `#` is legal in a ref only as the fragment separator, so truncating at the
+    // first `#` is exactly the split `parseBundleRef` performs. `ref` has no
+    // UNIQUE constraint, and no writer ever produced an empty concept id, so
+    // every legacy row normalizes without a drop path.
+    {
+        id: "026-proposals-strip-legacy-fragment-refs",
+        up: `
+      UPDATE proposals
+      SET ref = substr(ref, 1, instr(ref, '#') - 1)
+      WHERE ref LIKE '%#%';
+    `,
+    },
 ];
 assertMigrationRegistry(STATE_MIGRATIONS);
 function assertStateMigrationSafetyRegistry() {

package/dist/core/warn.js

@@ -122,6 +122,21 @@ export function warn(...args) {
         console.warn(...args);
     }
 }
+const warnedOnceKeys = new Set();
+/**
+ * `warn()` at most once per process for a given `key`. For diagnostics that
+ * would otherwise repeat on every read of the same bad row or value.
+ */
+export function warnOnce(key, ...args) {
+    if (warnedOnceKeys.has(key))
+        return;
+    warnedOnceKeys.add(key);
+    warn(...args);
+}
+/** TEST-ONLY. Forget every `warnOnce` key so a test can re-trigger a warning. */
+export function _resetWarnOnceForTests() {
+    warnedOnceKeys.clear();
+}
 /**
  * Emit an error to stderr unless --quiet is active.
  * Always written to the log file if one is active.

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,25 @@
  *
  * 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 fs from "node:fs";
 import path from "node:path";
 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)
@@ -54,8 +59,24 @@ 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 ||
+        cached.fileMtimeMaxMs !== fingerprint.fileMtimeMaxMs) {
+        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))

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;

package/dist/tasks/source/task-to-v3.js

@@ -112,6 +112,12 @@ function base(input) {
         ...(input.containmentRoot ? { containmentRoot: input.containmentRoot } : {}),
     };
 }
+/**
+ * #902: the one blocker with an unambiguous remedy. The sibling shell-safety
+ * reasons need a case-by-case judgement and stay reason-only.
+ */
+const 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 } : {}) });
 }
@@ -389,8 +395,10 @@ export 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(stringifyYaml(migrated), "utf8");
     try {
         parseTaskV3Yaml({

package/docs/migration/v0.9.1-to-v0.9.2.md

@@ -212,10 +212,24 @@ command: [node, scripts/release.js, "--exact value"]
 
 Shell-sensitive strings — assignments, shell builtins, reserved words, and
 similar constructs — are also blocked when translating them would invent
-shell semantics. The original bytes remain untouched. Author a v3 `run`
-string or a script/command asset deliberately, validate it, and rerun the
-preview. (This step still produces v3 output, which the second generation
-then carries the rest of the way to v4 in the same `akm migrate apply` run.)
+shell semantics. The original bytes remain untouched, and `akm migrate
+status`/`apply` names the block as `argv-array-has-no-portable-shell-string`
+(or a sibling shell-safety reason) rather than guessing: this is manual
+conversion, not a case the migrator can be re-run to fix. Rewrite the file
+by hand using this field mapping:
+
+| v2 | v4 |
+|---|---|
+| `command:` (array, argv style) | `run:` (string) plus `shell:` |
+| `timeoutMs:` | `timeout:` |
+| `enabled:` (document level) | removed — use `schedule:` as a list of `{cron, enabled}` entries |
+| `schedule:` (cron string) | still accepted as a bare string, or as the list form above |
+
+validate it, and rerun the preview. You can either write the replacement
+directly as `version: 4` (generation 1 then reports it `already-v4` and
+leaves it alone) or as a `version: 3` `run:` string, letting the second
+generation carry it the rest of the way to v4 in the same `akm migrate
+apply` run.
 
 ### Migrating task v3 to task source v4
 

package/docs/reference/cli.md

@@ -582,7 +582,7 @@ Subcommands:
 | `list` | List workflow runs (optionally filtered by `--ref`; `--active` shows only `status=active` runs, excluding `blocked`/`failed`/`completed`). Child workflow runs are excluded unless `--children` is passed |
 | `resume <run-id>` | Flip a `blocked` or `failed` run back to `active`. Completed runs cannot be resumed |
 | `abandon <run-id>` | Mark a run failed so it stops counting as active (`resume` can reopen it) |
-| `plan <ref>` | **Evolving.** Compile and freeze a workflow WITHOUT publishing a run: the canonical step graph, per-step frozen target kinds, task/child expansion, input bindings, source read set, and lowering notices — zero durable writes. Defaults to a human-readable summary; pass `--format json` for the full envelope |
+| `plan <ref>` | **Evolving.** Compile and freeze a workflow WITHOUT publishing a run: the canonical step graph, per-step frozen target kinds, task/child expansion, input bindings, source read set, and lowering notices — zero durable writes. Returns the full JSON envelope by default, like every other command; pass `--format text` for a human-readable summary |
 
 The public `workflow start`, `next`, and `complete` lifecycle was removed in
 0.9, along with the experimental `brief`/`report` external-driver protocol.

package/docs/reference/data-and-telemetry.md

@@ -60,6 +60,7 @@ Override: set `AKM_CONFIG_DIR` or `XDG_CONFIG_HOME`.
 | `state.db` | Events, local usage telemetry, proposals, task history, improve run results, and workflow run state/history (the former `workflow.db` was folded in during the 0.9.0 cutover) | **No** — deletes event/usage logs, proposal queue, improve history, and workflow run history |
 | `logs.db` | Structured, high-volume task/run log lines (`{ts, task_id, run_id, stream, level, line}`), joined to `state.db`'s `task_history` rows by `task_id@started_at`. Kept separate from `state.db` because log lines are append-only and freely purgeable, unlike durable state | Yes — log lines are regenerable per run; deleting loses historical run output only |
 | `akm.lock` | Inter-process write lock | Yes — recreated automatically |
+| `backups/task-v3/`, `backups/task-v4/` | Copies of task files taken by `akm migrate apply` before it rewrites them, one timestamped directory per run; the five most recent per generation are kept (#897) | Yes — once the migrated tasks are verified |
 | `akm.lock.lck` | Lock write sentinel | Yes — recreated automatically |
 
 Override: set `AKM_DATA_DIR` or `XDG_DATA_HOME`.

package/docs/reference/tasks.md

@@ -325,6 +325,17 @@ for both generations combined. Resolve every blocked file manually, then
 preview again. Apply validates a complete replacement before writing and
 backs up each original immediately before replacement.
 
+Common v2 → v3 blocked reasons and what to do about each — these need a
+hand-authored replacement, not a re-run; see [the 0.9.1 to 0.9.2 migration
+guide](../migration/v0.9.1-to-v0.9.2.md#v2--v3-blocked-cases) for the full v2
+to v4 field mapping (`command:` array → `run:` + `shell:`, `timeoutMs:` →
+`timeout:`, document-level `enabled:` → per-`schedule:`-entry `enabled`):
+
+| Reason | Meaning | Fix |
+|---|---|---|
+| `argv-array-has-no-portable-shell-string` | The task's `command:` is an argv array; no single shell string is provably equivalent. | Rewrite the file by hand — a `run:` string plus `shell:` — using the field mapping above. |
+| `shell-quoting-changes-v2-whitespace-split-semantics`, `shell-operators-change-v2-literal-argv-semantics`, `shell-command-resolution-changes-v2-literal-argv-semantics` | The `command:` string contains quoting, shell operators, or a bare executable name whose v2 argv-exec behavior a v3 `run:` (host-shell) invocation cannot reproduce unambiguously. | Review the command's intended shell semantics and author the v3/v4 `run:`/`shell:` fields by hand. |
+
 Common v3 → v4 blocked reasons and what to do about each:
 
 | Reason | Meaning | Fix |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.9.8-beta.1",
+  "version": "0.9.8-beta.2",
   "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": [
@@ -77,14 +77,10 @@
     "test:integration": "bash scripts/test-integration.sh",
     "test:node-smoke": "bun scripts/node-smoke.ts",
     "test:node-compat": "AKM_NODE_COMPAT_TESTS=1 bun test --timeout=120000 tests/integration/node-compat.test.ts",
-    "lint:isolation": "bun scripts/lint-tests-isolation.ts",
     "lint:doc-examples": "bun scripts/lint-doc-examples.ts",
-    "lint:active-docs-terminology": "bun scripts/lint-active-docs-terminology.ts",
     "publish:devto": "npx -y @sinedied/devto-cli push \"docs/posts/**/*.md\" --token \"$DEVTO_TOKEN\" --repo \"$GITHUB_REPOSITORY\" --branch \"${GITHUB_REF_NAME:-main}\" --reconcile",
     "release:check": "./tests/release-check.sh",
     "lint": "bunx biome check src/ tests/ scripts/ && bun scripts/lint-secret-resolver-boundary.ts && bun scripts/lint-shipped-assets.ts && bun scripts/lint-doc-examples.ts",
-    "lint:runtime-boundary": "bun scripts/lint-runtime-boundary.ts",
-    "lint:tests-isolation": "bun scripts/lint-tests-isolation.ts",
     "lint:fix": "bunx biome check --write src/ tests/ scripts/",
     "format": "bunx biome format --write src/ tests/ scripts/",
     "prepublishOnly": "cp .github/README.npm.md README.md && bun run build",