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

package/CHANGELOG.md

@@ -4,115 +4,82 @@ 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
+## [0.9.9-beta.1] - 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
+### Changed
 
-> **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.
+- **`akm-migrate` is the one migration tool, and `akm upgrade` runs it**
+  (#895 follow-up, #901). The standalone `akm-migrate` executable now runs
+  every migration step in one plan — the legacy config `extraParams` lift,
+  pending `state.db` migrations (historical-destructive ones included, with
+  the verified safety copy), task v2 → v3, task v3 → task source v4, and the
+  residue sweeps — as `akm-migrate status` / `apply [--dry-run]`; its
+  per-generation verbs (`task-v4-status`, `task-v4-apply`) are gone.
+  `akm migrate status|apply` is now a thin wrapper over that executable, and
+  every historical shape (`scripts/akm-migrate/`) lives outside the CLI
+  proper. `akm upgrade` runs `akm-migrate apply` **after** its install step —
+  the migrator that shipped with whatever is now installed — on every run,
+  install or no install, and reports the plan under `migration`; a blocked or
+  failed migration exits 1. A package-manager install that fails (EACCES on a
+  root-owned global directory) still runs the migrator and says so. An akm
+  installed as a dependency of another package is now detected
+  (`installMethod: "package-local"`) and never reinstalled — an
+  `npm install -g` there "succeeded" while the parent kept executing its own
+  copy — but its migrations still run. `akm upgrade --state-only` and the
+  `stateUpgrade` response field are removed; `akm migrate apply` is the
+  offline path. An ordinary managed open still refuses a historical-
+  destructive migration, and its message names these two commands.
+  A container that ships akm can put `akm upgrade` (or `akm migrate apply`)
+  in its entrypoint: on a current installation it is a no-op.
 
 ### 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
+- **`akm task sync` reports failed sources under `failures` on both the live
+  and `--dry-run` shapes** (#906). Live sync used to report them under
+  `failed` while `--dry-run` already used `failures`. No alias; both paths
+  now agree.
+- **`akm task sync` no longer misdiagnoses a supercronic-managed container as
+  missing the `crontab` binary** (#910). `crontab -l` exiting non-zero with
+  no output, or with stderr saying "no crontab", is cron's own way of saying
+  "empty crontab" (BSD's `no crontab for <user>`, or a PATH shim like
+  OpenPalm's before any spool exists). Only a spawn that cannot find the
+  binary (ENOENT) is reported as missing; any other failure is reported as
+  what it said.
+- **`akm task sync --rebind` no longer warns on every run of an image-baked
+  install** (#868 residue). The warning about binding scheduled tasks to a
+  mutable, unproven binary fires only when a rebind actually changes an
+  entry's bound invocation.
+- **A mixed-layout bundle no longer auto-detects as a narrow tool-dir adapter
+  and silently drops the rest** (#908). A root that a tool-dir-shaped adapter
+  (`agent-skills`, `claude`, `opencode`) claims but that also carries ordinary
+  akm content detects as `akm`, the superset. `akm bundle list` now reports
+  each component's effective `adapter` and whether it was `detected`, and
+  indexing under an explicitly narrow adapter warns once with the count of
+  files and directories it skipped.
+- **An unrecognised `components.*.adapter` is rejected** (#909) with
+  `INVALID_CONFIG_FILE` listing the accepted names instead of silently
+  falling back to `akm`. `akm bundle add --adapter <name>` overrides
+  auto-detection for a local directory; its `--help` lists the registry.
+
+## [0.9.8] - 2026-09-02
 
 A cleanup and stabilization release: deletion of machinery that policed the
 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
+sitting on top of. 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.
+
+Then a second round, from verifying the release against a real 23,865-entry
+environment: a no-op incremental index costing ~21 CPU-minutes, legacy proposal
+rows that could not be repaired, an npm probe spawning on every scheduler tick,
+a blocked task migration that named no remedy, and a data directory that could
+reach 74 GB with nothing reporting it.
+
+> **Upgrading is one-way for `state.db`.** This release adds two migrations,
+> `025-task-history-vocabulary-backfill` and
+> `026-proposals-strip-legacy-fragment-refs`. Once any 0.9.8 command opens
+> `state.db`, its ledger contains IDs 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`.
 >
@@ -127,12 +94,22 @@ sitting on top of.
 >
 > ```sh
 > akm info --format json    # confirm your data dir
-> sqlite3 "$DATA_DIR/state.db" "VACUUM INTO '''state.db.pre-0.9.8.bak'''"
+> 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.
+> **`index.db` rescans once.** The per-directory freshness fingerprint changed
+> shape, so the first `akm index` after upgrading re-reads every directory and
+> then returns to the fast path. Nothing is lost; the index is derived.
+
+### 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.
 
 ### Changed
 
@@ -149,6 +126,39 @@ with a confident wrong answer instead of an error.
   ~60 lines of comment justifying it. `--format text` still renders the same
   summary through the same formatter; it is simply no longer the default.
 
+
+- **Search no longer truncates long queries (#892).** `MAX_LEXICAL_QUERY_TOKENS
+  = 16` silently dropped every token past the sixteenth, and tokens are
+  collected in order, so the discarded half was the tail — for
+  natural-language input, usually where the discriminating words are. It also
+  fed ranking, so token-overlap scoring ran on the truncated set too. It was
+  unexplained in the code and in the commit that introduced it, and unreachable
+  from any flag, config key, or environment variable. Removed: the planner
+  handles 10,000 tokens in 9ms, so no performance cliff was being protected.
+
+- **Content and memory bodies are no longer silently truncated.**
+  `MAX_CONTENT_CHARS` (100k, duplicated across 8 adapters) cut indexed content
+  so the tail of a long document was unsearchable; `MAX_BODY_CHARS` (4000) cut
+  the text sent for memory inference, so on a large-context engine the model
+  saw a fraction of the input while the derived memory looked complete. Both
+  removed.
+
+- **GitHub Actions are pinned to commit SHAs (#768).** All 29 `uses:` steps
+  across every workflow, with the tag preserved in a trailing comment.
+
+- **Gated CI runs on schedule, dispatch, and candidate tags only.** The
+  `detect-changes` job that selected suites by regex-matching a PR diff is
+  gone — its path patterns had gone stale and still named test files this
+  release moved or deleted, so it was silently under-selecting suites. Release
+  evidence is unchanged; the checklist always required an exact-SHA dispatch.
+
+- **`akm-eval` in CI is now a determinism check only.** Its score gates are
+  removed. Measured before cutting: the baseline scored a perfect 1.0 against
+  a 0.75 gate, and seven of nine case types never ran — CI has no LLM and no
+  run history, so everything the eval exists to measure was skipped while the
+  job reported green. The harness itself is unchanged and remains a genuine
+  quality signal when run against a real bundle.
+
 ### Fixed
 
 - **Historical state migrations are reachable where akm cannot reinstall
@@ -264,39 +274,83 @@ with a confident wrong answer instead of an error.
   `bun run lint` failed locally while CI, which never has those files, stayed
   green.
 
-### Changed
 
-- **Search no longer truncates long queries (#892).** `MAX_LEXICAL_QUERY_TOKENS
-  = 16` silently dropped every token past the sixteenth, and tokens are
-  collected in order, so the discarded half was the tail — for
-  natural-language input, usually where the discriminating words are. It also
-  fed ranking, so token-overlap scoring ran on the truncated set too. It was
-  unexplained in the code and in the commit that introduced it, and unreachable
-  from any flag, config key, or environment variable. Removed: the planner
-  handles 10,000 tokens in 9ms, so no performance cliff was being protected.
+- **`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).
 
-- **Content and memory bodies are no longer silently truncated.**
-  `MAX_CONTENT_CHARS` (100k, duplicated across 8 adapters) cut indexed content
-  so the tail of a long document was unsearchable; `MAX_BODY_CHARS` (4000) cut
-  the text sent for memory inference, so on a large-context engine the model
-  saw a fraction of the input while the derived memory looked complete. Both
-  removed.
+- **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.
 
-- **GitHub Actions are pinned to commit SHAs (#768).** All 29 `uses:` steps
-  across every workflow, with the tag preserved in a trailing comment.
+- **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.
 
-- **Gated CI runs on schedule, dispatch, and candidate tags only.** The
-  `detect-changes` job that selected suites by regex-matching a PR diff is
-  gone — its path patterns had gone stale and still named test files this
-  release moved or deleted, so it was silently under-selecting suites. Release
-  evidence is unchanged; the checklist always required an exact-SHA dispatch.
 
-- **`akm-eval` in CI is now a determinism check only.** Its score gates are
-  removed. Measured before cutting: the baseline scored a perfect 1.0 against
-  a 0.75 gate, and seven of nine case types never ran — CI has no LLM and no
-  run history, so everything the eval exists to measure was skipped while the
-  job reported green. The harness itself is unchanged and remains a genuine
-  quality signal when run against a real bundle.
+- **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.
 
 ### Removed
 

package/dist/commands/health/checks.js

@@ -4,6 +4,7 @@
 import { spawnSync } from "node:child_process";
 import { loadConfig } from "../../core/config/config.js";
 import { ConfigError } from "../../core/errors.js";
+import { listPendingStateMigrations } from "../../core/state-db.js";
 import { withEngineFallback } from "../../integrations/agent/engine-fallback.js";
 import { resolveEngine } from "../../integrations/agent/engine-resolution.js";
 import { executionEngineDefinitionsFromConfig } from "../../integrations/agent/execution-definitions.js";
@@ -441,6 +442,40 @@ export function runSelectedModelAliasesProbe(deps = {}) {
         evidence: { checked, missing },
     };
 }
+/**
+ * Hard check: state.db's migration ledger has no pending entries.
+ *
+ * Read-only via `listPendingStateMigrations` (a preflight open, never a
+ * managed one), so running this check is always safe — even when the
+ * corresponding managed open would refuse outright because a pending
+ * migration is historical-destructive (see `beforeMigrationLocked` in
+ * `src/core/state/migrations.ts`). This is what lets `akm health` report that
+ * refusal as an ordinary `fail` check instead of crashing the whole command —
+ * and what replaces a bundler grepping akm's refusal error text
+ * to detect the same case.
+ */
+export function runPendingStateMigrationsCheck(stateDbPath, deps = {}) {
+    const pending = (deps.listPendingStateMigrations ?? listPendingStateMigrations)(stateDbPath);
+    if (pending.length === 0) {
+        return {
+            name: "state-db-migrations",
+            kind: "deterministic",
+            status: "pass",
+            confidence: "high",
+            message: "state.db has no pending migrations.",
+            evidence: { path: stateDbPath, pending: [] },
+        };
+    }
+    const range = pending.length > 1 ? `${pending[0]} … ${pending[pending.length - 1]}` : pending[0];
+    return {
+        name: "state-db-migrations",
+        kind: "deterministic",
+        status: "fail",
+        confidence: "high",
+        message: `${pending.length} pending state.db migration(s) (${range}); run \`akm migrate apply\`.`,
+        evidence: { path: stateDbPath, pending },
+    };
+}
 /**
  * The ordered health-check registry. ORDER IS LOAD-BEARING: `akmHealth`
  * iterates this array and appends to hardChecks/advisories in sequence, so the
@@ -477,6 +512,11 @@ export const HEALTH_CHECKS = [
             evidence: { path: ctx.stateDbPath, durationMs: ctx.probe.durationMs },
         }),
     },
+    {
+        name: "state-db-migrations",
+        channel: "hard",
+        run: (ctx) => runPendingStateMigrationsCheck(ctx.stateDbPath),
+    },
     {
         name: "task-history-read",
         channel: "hard",

package/dist/commands/health.js

@@ -10,14 +10,14 @@ import { readEvents } from "../core/events.js";
 import { openLogsDatabase } from "../core/logs-db.js";
 import { classifyPathAccess, describeInaccessiblePath } from "../core/path-access.js";
 import { getConfigPath, getDataDir, getDbPath, getStateDbPathInDataDir } from "../core/paths.js";
-import { listExistingTableNames, openStateDatabase } from "../core/state-db.js";
+import { listExistingTableNames, listPendingStateMigrations, openStateDatabase } from "../core/state-db.js";
 import { DURATION_UNITS, parseDuration, parseSinceToIso } from "../core/time.js";
 import { closeDatabase, openReadonlyExistingDatabase } from "../storage/repositories/index-connection.js";
 import { getAllEntries } from "../storage/repositories/index-entries-repository.js";
 import { queryTaskHistory } from "../storage/repositories/task-history-repository.js";
 import { pkgVersion } from "../version.js";
 import { collectImproveAdvisories } from "./health/advisories.js";
-import { HEALTH_CHECKS, runHealthEngineProbes } from "./health/checks.js";
+import { HEALTH_CHECKS, runHealthEngineProbes, runPendingStateMigrationsCheck, } 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";
@@ -414,37 +414,32 @@ function resolveWindowComparePhase(options, db, stateDbPath, now, logsDb) {
     return { windowResults, deltas };
 }
 /**
- * The health report for a state.db this process cannot read (#791).
+ * The health report for a state.db a managed open cannot reach at all: either
+ * the file is not readable (#791), or — the same shape, a different cause —
+ * it holds a pending migration the managed open refuses to apply without
+ * deliberate consent (`akm upgrade` / `akm migrate apply` are the
+ * only two callers allowed to admit a historical-destructive migration; see
+ * `beforeMigrationLocked` in `src/core/state/migrations.ts`).
  *
- * `akm health` is what an operator runs when other commands are misbehaving, so
- * it must survive the permission problem long enough to NAME it. Previously it
- * threw `ConfigError` (exit 78) on the state.db open, which meant the one
- * command able to explain a data-directory permission fault died before
- * reaching any of its advisories.
+ * `akm health` is what an operator (or a bundler's boot check) runs when
+ * something else is misbehaving, so it must survive either problem long
+ * enough to NAME it. Previously an unreadable file was already handled this
+ * way, but a pending migration was not: the managed open's refusal escaped as
+ * a thrown `ConfigError` (exit 78) and crashed the whole command before any
+ * check — including this one — could report anything.
  *
- * Reported as a hard-channel `fail` — the run genuinely could not assess the
- * install — with the path, errno, mode/owner and running uid in the message. It
- * exits non-zero either way; the difference is that the operator is now told
- * WHY instead of being handed a bare "unable to open database file".
+ * Reported as a single hard-channel `fail` check — the run genuinely could
+ * not open state.db, so every check that depends on it is skipped rather than
+ * attempted — and it still exits non-zero, just through health's normal
+ * `fail` path instead of a thrown config-error exit.
  */
-function unreadableStateDbReport(detail, options) {
+function degradedStateDbReport(hardCheck, options) {
     return {
         schemaVersion: 3,
         ok: false,
         status: "fail",
         since: parseHealthSince(options.since),
-        hardChecks: [
-            {
-                name: "state-db-readable",
-                kind: "deterministic",
-                status: "fail",
-                confidence: "high",
-                message: `state.db exists but is not readable: ${detail}. Every other health check is skipped because ` +
-                    "none of them can read it. Check the owner and mode of the data directory, or point " +
-                    "AKM_DATA_DIR / XDG_DATA_HOME at a location this user owns.",
-                evidence: { detail },
-            },
-        ],
+        hardChecks: [hardCheck],
         advisories: [],
         metrics: {
             taskFailRate: 0,
@@ -459,6 +454,18 @@ function unreadableStateDbReport(detail, options) {
         improve: summarizeImproveCompleted([]),
     };
 }
+function unreadableStateDbCheck(detail) {
+    return {
+        name: "state-db-readable",
+        kind: "deterministic",
+        status: "fail",
+        confidence: "high",
+        message: `state.db exists but is not readable: ${detail}. Every other health check is skipped because ` +
+            "none of them can read it. Check the owner and mode of the data directory, or point " +
+            "AKM_DATA_DIR / XDG_DATA_HOME at a location this user owns.",
+        evidence: { detail },
+    };
+}
 export function akmHealth(options = {}) {
     validateAkmHealthOptions(options);
     const now = options.now ?? (() => Date.now());
@@ -466,11 +473,13 @@ export function akmHealth(options = {}) {
     const stateDbPath = options.stateDbPath ?? getStateDbPathInDataDir();
     const hardChecks = [];
     const advisories = [];
-    // #791: an UNREADABLE state.db is the one failure `akm health` most needs to
-    // be able to report, because it is the command an operator runs to find out
-    // why everything else is behaving oddly. Dying here with exit 78 meant health
-    // could not diagnose that state at all — not even the checks that never touch
-    // state.db got to run. Report it as a finding instead.
+    // #791: an UNREADABLE state.db, or one with a pending migration the
+    // managed open refuses to apply, are the two failures `akm health` most
+    // needs to be able to report, because this is the command an operator (or a
+    // bundler's boot check) runs to find out why everything else is behaving
+    // oddly. Dying here meant health could not diagnose that state at all — not
+    // even the checks that never touch state.db got to run. Report it as a
+    // finding instead.
     let db;
     try {
         db = openStateDatabase(stateDbPath);
@@ -478,7 +487,24 @@ export function akmHealth(options = {}) {
     catch (error) {
         const { access, code } = classifyPathAccess(stateDbPath);
         if (access === "inaccessible") {
-            return unreadableStateDbReport(describeInaccessiblePath(stateDbPath, code), options);
+            return degradedStateDbReport(unreadableStateDbCheck(describeInaccessiblePath(stateDbPath, code)), options);
+        }
+        // The managed open's refusal of a pending historical-destructive
+        // migration is a plain `Error`, not a distinguishable error class — so
+        // confirm the cause via the read-only preflight (`listPendingStateMigrations`,
+        // which never applies anything) rather than pattern-matching the message.
+        // A ledger too broken to enumerate at all throws here too; in that case
+        // fall through to the generic config-error report below, since it is a
+        // genuinely different, rarer failure this check cannot explain.
+        let pendingMigrationsCheck;
+        try {
+            pendingMigrationsCheck = runPendingStateMigrationsCheck(stateDbPath, { listPendingStateMigrations });
+        }
+        catch {
+            pendingMigrationsCheck = undefined;
+        }
+        if (pendingMigrationsCheck?.status === "fail") {
+            return degradedStateDbReport(pendingMigrationsCheck, options);
         }
         throw new ConfigError(`Unable to open state.db: ${error instanceof Error ? error.message : String(error)}`, "INVALID_CONFIG_FILE");
     }