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

package/dist/commands/sources/source-add.js

@@ -31,7 +31,7 @@ export async function akmAdd(input) {
     try {
         const parsed = parseRegistryRef(ref);
         if (parsed.source === "local") {
-            return addLocalSource(ref, parsed.sourcePath, stashDir, input.name);
+            return addLocalSource(ref, parsed.sourcePath, stashDir, input.name, input.adapter);
         }
     }
     catch {
@@ -40,22 +40,23 @@ export async function akmAdd(input) {
     return addRegistryStash(ref, stashDir, input.writable);
 }
 /** Add a local directory as a filesystem bundle. */
-async function addLocalSource(ref, sourcePath, stashDir, explicitName) {
+async function addLocalSource(ref, sourcePath, stashDir, explicitName, explicitAdapter) {
     const stashRoot = detectStashRoot(sourcePath);
     const resolvedPath = path.resolve(stashRoot);
+    const adapter = explicitAdapter ?? detectAdapterId(resolvedPath);
     let bundleKey = explicitName ?? toReadableId(resolvedPath);
     mutateConfig((config) => {
         const existing = bundleKeyForPath(config, resolvedPath);
         if (existing) {
             bundleKey = existing;
             const current = config.bundles?.[existing];
-            if (current?.components)
+            if (current?.components && explicitAdapter === undefined)
                 return config;
             const bundles = { ...(config.bundles ?? {}) };
             bundles[existing] = {
                 ...current,
                 path: resolvedPath,
-                components: { main: { root: ".", adapter: detectAdapterId(resolvedPath) } },
+                components: { main: { root: ".", adapter } },
             };
             return { ...config, bundles };
         }
@@ -63,7 +64,7 @@ async function addLocalSource(ref, sourcePath, stashDir, explicitName) {
         bundleKey = nextBundleKey(bundles, explicitName, resolvedPath);
         bundles[bundleKey] = {
             path: resolvedPath,
-            components: { main: { root: ".", adapter: detectAdapterId(resolvedPath) } },
+            components: { main: { root: ".", adapter } },
         };
         return { ...config, bundles };
     });

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

@@ -27,13 +27,13 @@
  */
 import { defineCommand } from "citty";
 import { getParsedInvocation } from "../../cli/invocation.js";
-import { defineJsonCommand, GLOBAL_OUTPUT_ARGS, output, runWithJsonErrors } from "../../cli/shared.js";
+import { defineJsonCommand, EXIT_CODES, GLOBAL_OUTPUT_ARGS, output, runWithJsonErrors } from "../../cli/shared.js";
 import { loadConfig } from "../../core/config/config.js";
 import { UsageError } from "../../core/errors.js";
 import { appendEvent } from "../../core/events.js";
 import { resolveWritableOverride, saveGitStash } from "../../sources/providers/git.js";
 import { pkgVersion } from "../../version.js";
-import { checkForUpdate, performUpgrade, upgradeStateOnly } from "./self-update.js";
+import { checkForUpdate, performUpgrade } from "./self-update.js";
 import { akmClone } from "./source-clone.js";
 export const upgradeCommand = defineJsonCommand({
     meta: { name: "upgrade", description: "Upgrade akm to the latest release" },
@@ -45,24 +45,8 @@ export const upgradeCommand = defineJsonCommand({
             description: "Skip the post-upgrade index rebuild",
             default: false,
         },
-        "state-only": {
-            type: "boolean",
-            description: "Apply pending state.db migrations without installing a new akm",
-            default: false,
-        },
     },
     async run({ args }) {
-        // Applying a historical destructive state migration used to be reachable
-        // ONLY as a post-install step of a real upgrade, so an install akm cannot
-        // rewrite -- a global npm install owned by root, an image that ships the
-        // CLI -- had no route to it at all: the npm step fails EACCES and throws
-        // long before the migration runs (#895). The migration is a local,
-        // offline, already-verified operation; it does not need the network or a
-        // new binary, and coupling it to one was the bug.
-        if (args["state-only"]) {
-            output("upgrade", upgradeStateOnly(pkgVersion));
-            return;
-        }
         const check = await checkForUpdate(pkgVersion);
         if (args.check) {
             output("upgrade", check);
@@ -71,6 +55,11 @@ export const upgradeCommand = defineJsonCommand({
         const skipPostUpgrade = args["skip-post-upgrade"];
         const result = await performUpgrade(check, { force: args.force, skipPostUpgrade });
         output("upgrade", result);
+        // The install may have succeeded, but an upgrade whose migration is
+        // blocked or could not run is not done: exit like `akm migrate apply` does.
+        if (result.migration?.status === "blocked" || result.migration?.status === "failed") {
+            process.exitCode = EXIT_CODES.GENERAL;
+        }
     },
 });
 // `sync` body, standalone so the git-commit/push logic stays in one place.

package/dist/commands/tasks/tasks-cli.js

@@ -349,10 +349,11 @@ const tasksSyncCommand = defineJsonCommand({
         const result = await akmTasksSync({}, args.bundle, { rebind });
         output("task-sync", result);
         // #867: sync degrades — sources that failed to parse/prepare are
-        // excluded from reconciliation and reported in `result.failed` rather
+        // excluded from reconciliation and reported in `result.failures` rather
         // than poisoning the whole sync, but their presence must still fail
-        // the command's exit code so the breakage stays visible.
-        if (result.failed.length > 0)
+        // the command's exit code so the breakage stays visible. (#906: this key
+        // matches the `--dry-run` preview's `failures` field — no separate name.)
+        if (result.failures.length > 0)
             process.exitCode = EXIT_CODES.GENERAL;
     },
 });

package/dist/commands/tasks/tasks.js

@@ -391,7 +391,7 @@ async function buildSchedulerSyncPlan(deps, bundleTarget, options) {
     const expectedSignature = sched.expectedSignature?.bind(sched);
     const needsRuntime = preflight.operations.some((operation) => operation.kind !== "remove" && operation.options?.binding === undefined);
     const prepared = needsRuntime
-        ? prepareSchedulerSyncRuntime(syncTarget ? { target: syncTarget } : undefined, deps, options.rebind === true, "reconcile native scheduler bindings", warnings)
+        ? prepareSchedulerSyncRuntime(syncTarget ? { target: syncTarget } : undefined, deps, options.rebind === true, "reconcile native scheduler bindings", warnings, allEntries.map((entry) => entry.binding))
         : undefined;
     const plan = finalizeSchedulerSyncPlan({
         ...common,
@@ -416,7 +416,7 @@ export async function akmTasksSync(deps = {}, bundleTarget, options = {}) {
         unchanged: [...plan.unchanged],
         skipped: [],
         backend: sched.name,
-        failed: plan.failures.map((failure) => ({ ...failure })),
+        failures: plan.failures.map((failure) => ({ ...failure })),
         ...(warnings.length > 0 ? { warnings } : {}),
     };
 }
@@ -841,16 +841,16 @@ async function prepareTaskAddSchedulerTransaction(input) {
         publishOperationIndex: removals.length,
     });
 }
-function prepareSchedulerSyncRuntime(base, deps, explicitRebind, operation, warnings) {
+function prepareSchedulerSyncRuntime(base, deps, explicitRebind, operation, warnings, installedBindings = []) {
     if (deps.backend && !deps.schedulerRuntime)
         return base ? { options: base } : {};
     if (deps.schedulerRuntime) {
         const runtime = deps.schedulerRuntime();
-        warnIneligibleRebind(runtime, explicitRebind, warnings);
+        warnIneligibleRebind(runtime, explicitRebind, warnings, installedBindings);
         return { options: { ...base, binding: runtime.binding, contextPath: runtime.contextPath } };
     }
     const invocation = resolveAndValidateSchedulerInvocation(explicitRebind, operation);
-    warnIneligibleRebind(invocation, explicitRebind, warnings);
+    warnIneligibleRebind(invocation, explicitRebind, warnings, installedBindings);
     const descriptor = schedulerContextDescriptor();
     const contextPath = schedulerContextPath(descriptor);
     return {
@@ -870,9 +870,16 @@ function resolveAndValidateSchedulerInvocation(explicitRebind, operation) {
     }
     return { binding: invocation.argv, contextPath: "", eligible: invocation.eligible, kind: invocation.kind };
 }
-function warnIneligibleRebind(runtime, explicitRebind, warnings) {
+function warnIneligibleRebind(runtime, explicitRebind, warnings, installedBindings) {
     if (!explicitRebind || runtime.eligible !== false || warnings.length > 0)
         return;
+    // #868 residue: a `--rebind` that binds every currently-installed
+    // entry to the SAME invocation it already carries changes nothing — this
+    // is the steady state of an image-baked install re-running `task sync
+    // --rebind` on a timer. Only warn when the rebind actually moves an entry
+    // to a different invocation.
+    if (installedBindings.length > 0 && installedBindings.every((bound) => sameArgv(bound, runtime.binding)))
+        return;
     warnings.push(`--rebind bound scheduled tasks to an ineligible ${runtime.kind ?? "unknown"} invocation (${runtime.binding.join(" ")}); scheduled runs will invoke a mutable, unproven binary. Install akm via \`npm install --global akm-cli\` or a standalone release, then re-run \`akm task sync --rebind\`.`);
 }
 function groupInstalledBindings(entries, invocation) {

package/dist/core/adapter/adapter-ids.js

@@ -0,0 +1,35 @@
+// 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/.
+/**
+ * Dependency-free adapter-id table (#909) — mirrors
+ * `src/integrations/harnesses/ids.ts`'s split from its own heavy barrel.
+ *
+ * `core/config/schema/sources-bundles.ts` needs one small, DATA-shaped fact
+ * about the adapter registry: the canonical ordered id list, to validate
+ * `components.*.adapter` and to reject a typo instead of silently falling
+ * back to `akm` (#909). Importing `./registry.ts` (`BUILTIN_ADAPTERS`) for
+ * that would pull in all 11 concrete adapters and, transitively, the indexer
+ * modules they delegate to (`indexer/passes/metadata`, `core/asset/*`, …) —
+ * weight a config-schema module has no reason to carry just to validate one
+ * enum. This table is the canonical, dependency-free MIRROR of the id list;
+ * `./adapters/index.ts`'s `BUILTIN_ADAPTERS` construction asserts its ids
+ * match this table (order included) at module-load time, so the two can
+ * never silently drift without a loud failure.
+ */
+/** Canonical, ordered list of valid adapter ids (matches `BUILTIN_ADAPTERS` order). */
+export const ADAPTER_ID_TABLE = [
+    "website-snapshot",
+    "agent-skills",
+    "claude",
+    "opencode",
+    "dotenv",
+    "akm-workflow",
+    "akm-task",
+    "llm-wiki",
+    "akm",
+    "okf",
+    "generic-files",
+];
+/** The dependency-free counterpart of `./registry.ts`'s `getAdapters().map(a => a.id)`. */
+export const VALID_ADAPTER_IDS = ADAPTER_ID_TABLE;

package/dist/core/adapter/adapters/index.js

@@ -1,6 +1,21 @@
 // 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/.
+/**
+ * Built-in `BundleAdapter` barrel + the static, frozen `BUILTIN_ADAPTERS` list
+ * (normative §12.6) — akm 0.9.0 chunk-2 (WI-A) + the format-family work item
+ * (#46).
+ *
+ * `BUILTIN_ADAPTERS` is the ordered built-in adapter set the registry
+ * (`../registry`) exposes via `getAdapters()` / `adapterForId()`. It is a
+ * plain frozen array populated at MODULE LOAD — there is no mutable
+ * registration step and no load-order dependency, so no production call site
+ * (`installations.ts#detectAdapterId`, `provider-utils.ts#detectStashRoot`)
+ * depends on anyone first calling a registration function (normative §12.6 —
+ * "static frozen `BUILTIN_ADAPTERS` map"). The earlier mutable
+ * `registerAdapter` singleton that this replaced is retired.
+ */
+import { ADAPTER_ID_TABLE } from "../adapter-ids.js";
 import { agentSkillsAdapter } from "./agent-skills-adapter.js";
 import { akmAdapter } from "./akm-adapter.js";
 import { akmTaskAdapter } from "./akm-task-adapter.js";
@@ -69,3 +84,17 @@ export const BUILTIN_ADAPTERS = Object.freeze([
     // Explicit-config fallback (never auto-selected) — last.
     genericFilesAdapter,
 ]);
+// Construction-time drift guard (#909): ../adapter-ids.ts's ADAPTER_ID_TABLE
+// is config's dependency-free mirror of this list, kept out of core/config's
+// import graph so config doesn't have to import this (heavier) barrel. Assert
+// they match so the mirror can never silently drift — a new/reordered/renamed
+// adapter that forgets to update adapter-ids.ts fails loudly here instead of
+// quietly breaking config's `components.*.adapter` validation.
+{
+    const actualIds = BUILTIN_ADAPTERS.map((a) => a.id);
+    const expectedIds = [...ADAPTER_ID_TABLE];
+    if (actualIds.length !== expectedIds.length || actualIds.some((id, i) => id !== expectedIds[i])) {
+        throw new Error(`adapter-ids.ts ADAPTER_ID_TABLE (${expectedIds.join(", ")}) does not match ` +
+            `BUILTIN_ADAPTERS (${actualIds.join(", ")}) — update adapter-ids.ts to match.`);
+    }
+}

package/dist/core/adapter/detect-adapter.js

@@ -1,13 +1,101 @@
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
-import { getAdapters } from "./registry.js";
-/** Select the first built-in adapter whose ordered root probe claims `root`. */
+import fs from "node:fs";
+import path from "node:path";
+import { adapterForId, getAdapters } from "./registry.js";
+/**
+ * Tool-dir-shaped adapters (#908): their install-time probe recognizes only a
+ * BOUNDED slice of the root — `claude`/`opencode`'s own `commands`/`agents`/
+ * `skills` tool dirs, or `agent-skills`' own `<name>/SKILL.md` packages. A
+ * bundle that ALSO carries ordinary akm content (`knowledge/`, `workflows/`,
+ * a stray `content/` folder of Markdown, …) alongside one of these layouts had
+ * that content SILENTLY dropped: the narrow adapter won the ordered probe and
+ * indexed only its own three-dir slice, with no warning that anything else
+ * was there (issue #908 — 73 documents disappeared from one real bundle).
+ *
+ * `okf` / `llm-wiki` / `dotenv` / `website-snapshot` / `akm-workflow` /
+ * `akm-task` are deliberately NOT in this set: each carries its own tight,
+ * disjoint marker (a root index document, `schema.md`+`pages/`, an env/secrets-only
+ * layout, `manifest.json`, a workflow/task-shaped top-level file) that is not
+ * at risk of firing merely because a FEW directory names happen to overlap
+ * with akm's own stash subdirs — narrowing the fix to the three families the
+ * issue is actually about keeps this from touching adapters it was never
+ * about.
+ */
+const SHADOWABLE_ADAPTER_IDS = new Set(["agent-skills", "claude", "opencode"]);
+/**
+ * True when `root` — already claimed by `winnerId` (one of
+ * {@link SHADOWABLE_ADAPTER_IDS}) — ALSO carries a top-level directory the
+ * `akm` adapter's own probe recognizes as its workspace shape (spec §1.2) and
+ * that `winnerId` does not own (its `directoryList()`, or — for `agent-skills`,
+ * which owns no fixed directory names — a root-level `<name>/SKILL.md`
+ * package) but which holds at least one real file. Cheap by design: only
+ * shallow `readdirSync` calls, one level into each candidate top-level dir —
+ * no recursive walk, no file content read, no git spawn — so this never adds
+ * meaningful cost to the install-time probe it augments.
+ */
+function hasExtraAkmContent(root, winnerId) {
+    const akm = adapterForId("akm");
+    if (akm?.looksLikeRoot?.(root) !== true)
+        return false;
+    const winner = adapterForId(winnerId);
+    const stubComponent = { id: "detect", adapter: winnerId, root, writable: false };
+    const ownedDirs = new Set(winner?.directoryList?.(stubComponent) ?? []);
+    let entries;
+    try {
+        entries = fs.readdirSync(root, { withFileTypes: true });
+    }
+    catch {
+        return false;
+    }
+    for (const entry of entries) {
+        if (!entry.isDirectory() || entry.name.startsWith("."))
+            continue;
+        if (ownedDirs.has(entry.name))
+            continue;
+        if (winnerId === "agent-skills") {
+            // A root-level `<name>/SKILL.md` package IS agent-skills' own recognized
+            // surface even though it has no fixed directoryList — not "extra" content.
+            try {
+                if (fs.statSync(path.join(root, entry.name, "SKILL.md")).isFile())
+                    continue;
+            }
+            catch {
+                // Not a skill package — fall through to the candidate-file check below.
+            }
+        }
+        let children;
+        try {
+            children = fs.readdirSync(path.join(root, entry.name), { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        if (children.some((child) => child.isFile() && !child.name.startsWith(".")))
+            return true;
+    }
+    return false;
+}
+/**
+ * Select the first built-in adapter whose ordered root probe claims `root`.
+ *
+ * A mixed-layout bundle (#908) that both a tool-dir-shaped adapter AND the
+ * `akm` adapter would claim detects as `akm` — the superset, which still
+ * indexes the narrower layout's own files correctly (`agent-skills`'
+ * `<name>/SKILL.md` packages, `claude`/`opencode`'s `commands`/`agents`/
+ * `skills`) while also picking up whatever else is in the bundle. A bundle
+ * that carries ONLY the narrow layout (no extra content) is unaffected.
+ */
 export function detectAdapterId(root, fallback = "akm") {
     for (const adapter of getAdapters()) {
         try {
-            if (adapter.looksLikeRoot?.(root) === true)
+            if (adapter.looksLikeRoot?.(root) === true) {
+                if (SHADOWABLE_ADAPTER_IDS.has(adapter.id) && hasExtraAkmContent(root, adapter.id)) {
+                    return "akm";
+                }
                 return adapter.id;
+            }
         }
         catch {
             // An unreadable or racing probe does not claim the bundle.

package/dist/core/config/config.js

@@ -151,7 +151,7 @@ export function parseAndValidateConfigText(text, sourcePath) {
     // rewritten onto the first-class engine field they now shadow. This used
     // to happen silently, in memory, on every load; that ran forever and never
     // converged. The lift itself is now `akm migrate apply`'s job (see
-    // src/commands/migrate/config-extra-params.ts) and persists to disk, so a
+    // scripts/akm-migrate/migrate/config-extra-params.ts) and persists to disk, so a
     // config that has not been migrated yet fails closed here instead of
     // silently drifting from what's on disk.
     const where = sourcePath ? ` at ${sourcePath}` : "";

package/dist/core/config/schema/sources-bundles.js

@@ -7,9 +7,15 @@
  * change.
  */
 import { z } from "zod";
+// Dependency-free mirror of the adapter registry's id list (#909) — see
+// adapter-ids.ts's header for why config imports this leaf rather than
+// `core/adapter/registry.ts` (which would pull in all 11 concrete adapters
+// and, transitively, the indexer modules they delegate to).
+import { VALID_ADAPTER_IDS } from "../../adapter/adapter-ids.js";
 import { isBundleSlug } from "../../asset/asset-ref.js";
 import { hasRegistryUrlCredentials, REGISTRY_CREDENTIALS_UNSUPPORTED } from "../../registry-url.js";
 import { httpUrl, nonEmptyString, positiveInt } from "./primitives.js";
+const VALID_ADAPTER_IDS_SET = new Set(VALID_ADAPTER_IDS);
 // ── Sources / registries / installed ────────────────────────────────────────
 const SourceConfigEntryOptionsSchema = z.record(z.unknown());
 export const SourceConfigEntrySchema = z
@@ -165,6 +171,23 @@ export const BundleConfigEntrySchema = z
             message: "writable: true is only supported on path and git bundle sources",
         });
     }
+    // #909: an unrecognized `components.*.adapter` used to silently fall back
+    // to `akm` at detect-time with no error and no disclosure — a typo
+    // (`agent_skills`, `akm-native`, …) then silently changed which files got
+    // indexed. Reject it here instead, the same treatment other enum-valued
+    // config fields get, listing the accepted values (derived from the
+    // adapter registry, never hardcoded — see adapter-ids.ts).
+    if (componentEntry !== undefined) {
+        const [componentName, componentValue] = componentEntry;
+        const adapterValue = componentValue.adapter;
+        if (adapterValue !== undefined && !VALID_ADAPTER_IDS_SET.has(adapterValue)) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ["components", componentName, "adapter"],
+                message: `unrecognized adapter "${adapterValue}"; expected one of: ${VALID_ADAPTER_IDS.join(", ")}`,
+            });
+        }
+    }
 });
 /**
  * `bundles` map. Keys are workspace bundle slugs (spec §11.1 / D-R5 charset).

package/dist/core/extra-params.js

@@ -125,7 +125,7 @@ export function formatExtraParamsIssue(label, issue) {
  * (#852, following #815).
  *
  * Pure: never touches the filesystem. Two callers use this differently:
- * `akm migrate apply` (src/commands/migrate/config-extra-params.ts) uses the
+ * `akm migrate apply` (scripts/akm-migrate/migrate/config-extra-params.ts) uses the
  * returned `config` to persist the rewrite to disk, once; `parseAndValidateConfigText`
  * (src/core/config/config.ts) calls this only to detect whether a lift is
  * needed and discards `config` — an unmigrated config fails closed there

package/dist/core/state/migrations.js

@@ -1187,8 +1187,7 @@ export function runMigrations(db, options) {
         }
         if (!options.allowHistoricalDestructiveStateUpgrade) {
             throw new Error("Refusing to migrate an existing unversioned state.db during an ordinary managed open. " +
-                "Run `akm upgrade --force` to snapshot it before migration 001, " +
-                "or `akm upgrade --state-only` where akm cannot reinstall itself (container/global install).");
+                "Run `akm upgrade` (or `akm migrate apply`) to snapshot it before migration 001 and apply it deliberately.");
         }
         const ledger = assertMigrationLedger(lockedDb, STATE_MIGRATIONS);
         if (ledger.migrationIds.length !== 0) {
@@ -1218,8 +1217,7 @@ export function runMigrations(db, options) {
             assertMigrationLedger(lockedDb, STATE_MIGRATIONS);
             if (!options?.allowHistoricalDestructiveStateUpgrade) {
                 throw new Error(`Refusing to apply historical destructive state migration ${migration.id} during an ordinary managed open. ` +
-                    "Run `akm upgrade --force` to create a sibling state.db safety copy and apply it deliberately, " +
-                    "or `akm upgrade --state-only` where akm cannot reinstall itself (container/global install).");
+                    "Run `akm upgrade` (or `akm migrate apply`) to create a sibling state.db safety copy and apply it deliberately.");
             }
             if (!options.beforeHistoricalDestructiveMigration) {
                 throw new Error(`Historical destructive state migration ${migration.id} requires a verified safety-copy hook.`);

package/dist/core/state-db.js

@@ -407,8 +407,8 @@ export function openStateDatabase(dbPath, options) {
                 existingUnversionedDatabase = ledger.migrationIds.length === 0;
                 if (existingUnversionedDatabase && !options?.allowHistoricalDestructiveStateUpgrade) {
                     throw new Error("Refusing to migrate an existing unversioned state.db during an ordinary managed open. " +
-                        "Run `akm upgrade --force` to create a verified snapshot before migration 001, " +
-                        "or `akm upgrade --state-only` where akm cannot reinstall itself (container/global install).");
+                        "Run `akm upgrade` (or `akm migrate apply`) to create a verified snapshot before migration 001 " +
+                        "and apply it deliberately.");
                 }
             }
             finally {
@@ -499,13 +499,36 @@ export function openStateDatabase(dbPath, options) {
     }
 }
 /**
- * Narrow state-schema step owned by `akm upgrade` after executable replacement.
- * Missing/current databases are no-ops. A pre-018 exact ledger is snapshotted
- * beside state.db and verified before the immutable released migration runs.
+ * Read-only: the state migration IDs the running akm would apply to `dbPath`,
+ * in ledger order. Empty when the database is missing or current. Throws on a
+ * ledger this akm cannot own (newer, or not an exact ordered prefix) -- the
+ * same refusal a managed open makes.
  */
-export function upgradeHistoricalStateDatabase(dbPath = getStateDbPath()) {
+export function listPendingStateMigrations(dbPath = getStateDbPath()) {
     if (!fs.existsSync(dbPath))
-        return { upgraded: false };
+        return [];
+    const preflight = openDatabase(dbPath, { readonly: true });
+    try {
+        preflight.exec("PRAGMA busy_timeout = 30000");
+        const ledger = assertMigrationLedger(preflight, STATE_MIGRATIONS);
+        return STATE_MIGRATIONS.slice(ledger.migrationIds.length).map((migration) => migration.id);
+    }
+    finally {
+        preflight.close();
+    }
+}
+/**
+ * Apply every pending state migration, historical-destructive ones included:
+ * the one step `akm upgrade` and `akm migrate apply` share, and the only
+ * caller that may admit migration 018 (an ordinary managed open refuses it by
+ * design). Missing/current databases are no-ops. A pre-018 exact ledger, or an
+ * unversioned database, is snapshotted beside state.db and verified before the
+ * immutable released migration runs.
+ */
+export function upgradeHistoricalStateDatabase(dbPath = getStateDbPath()) {
+    const pending = listPendingStateMigrations(dbPath);
+    if (pending.length === 0)
+        return { upgraded: false, applied: [] };
     let safetyCopyPath;
     try {
         const db = openStateDatabase(dbPath, {
@@ -521,7 +544,7 @@ export function upgradeHistoricalStateDatabase(dbPath = getStateDbPath()) {
         const recovery = safetyCopyPath ? ` Verified safety copy: ${safetyCopyPath}.` : "";
         throw new Error(`${detail}${recovery}`);
     }
-    return safetyCopyPath ? { upgraded: true, safetyCopyPath } : { upgraded: false };
+    return safetyCopyPath ? { upgraded: true, applied: pending, safetyCopyPath } : { upgraded: true, applied: pending };
 }
 /**
  * Run `fn` against state.db, owning the handle unless one is borrowed. The loan

package/dist/indexer/indexer.js

@@ -13,7 +13,7 @@ import { classifyPathAccess, describeInaccessiblePath } from "../core/path-acces
 import { getDbPath } from "../core/paths.js";
 import { SCRIPT_EXTENSIONS } from "../core/recognition-util.js";
 import { withStateDb } from "../core/state-db.js";
-import { isVerbose, warn, warnVerbose } from "../core/warn.js";
+import { isVerbose, warn, warnOnce, warnVerbose } from "../core/warn.js";
 import { disposeLoweredExecutionDispatchLease, } from "../integrations/agent/execution-lowering.js";
 import { isLlmFeatureEnabled } from "../llm/feature-gate.js";
 import { resolveIndexPassExecution } from "../llm/index-passes.js";
@@ -750,6 +750,67 @@ function sourceSnapshotRemovals(db, currentStashDir, bundleId, currentDirs, allI
         reason: { kind: "not-in-source-snapshot" },
     }));
 }
+/**
+ * Warn ONCE per process (#908) when the chosen adapter for a component
+ * entirely skips a top-level directory that holds files the `akm` adapter —
+ * the format-neutral superset — would have indexed. `detectAdapterId` now
+ * corrects this for AUTO-DETECTION (a mixed layout detects as `akm`); this
+ * covers the case detection cannot see, an EXPLICITLY configured narrow
+ * adapter (`components.<name>.adapter: "agent-skills"`, say) sitting next to
+ * ordinary akm content. One line for the whole process — not one per bundle,
+ * not one per directory — naming the count and the directories is enough to
+ * point an operator at the fix.
+ */
+function warnIfAdapterSkipsAkmContent(component, files, adapter) {
+    if (adapter.id === "akm")
+        return;
+    const akm = adapterForId("akm");
+    if (!akm)
+        return;
+    const byTopDir = new Map();
+    for (const file of files) {
+        const top = file.ancestorDirs[0];
+        if (!top)
+            continue; // a root-level file is not a "skipped directory" concern
+        const group = byTopDir.get(top);
+        if (group)
+            group.push(file);
+        else
+            byTopDir.set(top, [file]);
+    }
+    const akmComponent = { ...component, adapter: "akm" };
+    let skippedCount = 0;
+    const skippedDirs = [];
+    for (const [dir, dirFiles] of byTopDir) {
+        const chosenRecognizesAny = dirFiles.some((file) => {
+            try {
+                return adapter.recognize(component, file) !== null;
+            }
+            catch {
+                return false;
+            }
+        });
+        if (chosenRecognizesAny)
+            continue; // the chosen adapter owns this dir; nothing skipped
+        const akmCandidates = dirFiles.filter((file) => {
+            try {
+                return akm.recognize(akmComponent, file) !== null;
+            }
+            catch {
+                return false;
+            }
+        });
+        if (akmCandidates.length === 0)
+            continue; // akm would drop it too — not a shadowing case
+        skippedCount += akmCandidates.length;
+        skippedDirs.push(dir);
+    }
+    if (skippedCount === 0)
+        return;
+    skippedDirs.sort();
+    warnOnce("adapter-skip-akm-content", `${adapter.id} adapter skipped ${skippedCount} file${skippedCount === 1 ? "" : "s"} in ` +
+        `${skippedDirs.map((dir) => `${dir}/`).join(", ")} — set components.<name>.adapter to "akm" to index them`);
+}
 function buildSourceScanPlans(db, allSourceEntries, isIncremental, reconcileMissingDirs) {
     const componentBySource = buildComponentBySource(allSourceEntries);
     const handoffDirs = new Set();
@@ -775,6 +836,8 @@ function buildSourceScanPlans(db, allSourceEntries, isIncremental, reconcileMiss
         });
         const dirGroups = groupFileContextsByDir(walked.files);
         const adapter = adapterForId(component.adapter);
+        if (adapter)
+            warnIfAdapterSkipsAkmContent(component, walked.files, adapter);
         return {
             currentStashDir,
             component,