akm-cli 0.9.8 → 0.9.9

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.9] - 2026-09-02
+
+### Changed
+
+- **`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` 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

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

package/dist/commands/migrate-cli.js

@@ -2,207 +2,50 @@
 // 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 { defineGroupCommand, defineJsonCommand, EXIT_CODES, output } from "../cli/shared.js";
-import { resolveStashDir } from "../core/common.js";
-import { resetConfigCache } from "../core/config/config.js";
-import { ConfigError } from "../core/errors.js";
-import { getConfigPath } from "../core/paths.js";
-import { applyConfigExtraParamsLift, findConfigExtraParamsLift } from "./migrate/config-extra-params.js";
-import { findDeadResidueEntries, removeDeadResidue } from "./migrate/dead-residue.js";
-import { findStaleTxnEntries, recoverStaleTxns } from "./migrate/stale-txn.js";
 import { runMigrationTool } from "./migration-tool.js";
-async function callMigrateTool(args, runTool) {
+/**
+ * `akm migrate` is a thin wrapper over the standalone `akm-migrate`
+ * executable, which owns every migration step and every historical shape
+ * (`scripts/akm-migrate/`). This module only spawns it, re-emits its one JSON
+ * plan through the normal output pipeline so `--format` applies, and mirrors
+ * its exit code. `akm upgrade` calls the same executable after an install.
+ * Passed the runner as a parameter so a test can hand it a stand-in.
+ */
+export async function runMigrateSubcommand(command, args, runTool = runMigrationTool) {
     const result = await runTool(args);
     if (result.stderr)
         process.stderr.write(result.stderr);
-    const resultLine = result.stdout.trim();
-    if (!resultLine)
-        return { status: result.status };
+    const line = result.stdout.trim();
+    let plan;
     try {
-        return { status: result.status, plan: JSON.parse(resultLine) };
+        plan = line ? JSON.parse(line) : undefined;
     }
     catch {
-        console.log(resultLine);
-        return { status: result.status };
+        plan = undefined;
     }
-}
-function worstStatus(left, right) {
-    if (left === "blocked" || right === "blocked")
-        return "blocked";
-    if (left === "ready" || right === "ready")
-        return "ready";
-    return "current";
-}
-/**
- * Resolve one generation's contribution to the combined status — fail
- * CLOSED, never open (code-review finding: this tool advertises itself as
- * "blocked-not-guessed").
- *
- * A generation that exited SUCCESS with no plan on stdout legitimately means
- * "nothing to report" and defaults to `"current"`. A generation that exited
- * NON-SUCCESS (by the caller's own guard, this can only be `EXIT_CODES.
- * GENERAL` — the "blocked" code) with a parsed `plan.status` reports that
- * status verbatim, same as before.
- *
- * The gap this closes: NON-SUCCESS with NO parseable plan at all —
- * `runMigrationTool` coerces a `spawnSync` `status` of `null` (the child was
- * killed by a signal — OOM, a timeout, a manual kill — never scheduled to
- * exit) to `1`, indistinguishable from the migrator's own legitimate
- * "blocked" exit code, and truncated/malformed stdout hits the same
- * `JSON.parse` catch in `callMigrateTool`. Previously `?? "current"` silently
- * read a crashed generation as "nothing to migrate"; this reports it as
- * `"blocked"` with an explanatory blocker instead, so the combined exit code
- * (`EXIT_CODES.GENERAL` below) actually reflects that the generation's real
- * state is unknown, rather than reporting success at exit 0.
- */
-export function resolveGenerationStatus(call, label) {
-    const planStatus = call.plan?.status;
-    if (planStatus !== undefined)
-        return { status: planStatus };
-    if (call.status !== EXIT_CODES.SUCCESS) {
-        return {
-            status: "blocked",
-            error: `${label}: the child process exited without printing a plan (exit status ${call.status}) — its real migration state is unknown.`,
-        };
-    }
-    return { status: "current" };
-}
-/**
- * Run BOTH migration generations — task-v2-to-v3, then task-v3-to-task-
- * source-v4 — and print one combined plan (spec
- * docs/plans/specs/p4-deletions-closeout.md §3.2.5, rows B-31/B-32).
- *
- * Each generation is its OWN subprocess call into the standalone migrator
- * (`scripts/akm-migrate.ts`'s `status`/`apply` and `task-v4-status`/
- * `task-v4-apply` verbs, UNCHANGED — row B-33), so each keeps its own
- * `withConfigLock` + `O_EXCL` backup root + prevalidate + TOCTOU recheck +
- * atomic replace + reverse rollback + convergence check, and the two are
- * NEVER interleaved. The two calls are unconditional and independent of
- * each other's outcome: a blocked (or otherwise incomplete) generation-1
- * result does not stop generation 2 from running against whatever is
- * already task source v4 — exactly `akm-migrate status`/`task-v4-status`
- * (or `apply`/`task-v4-apply`) run back to back by hand. Only a genuine
- * hard failure (a status neither SUCCESS nor the "blocked" GENERAL code —
- * a config error, a crash) aborts the second call, since generation 1 never
- * got to look at a stable tree in that case.
- */
-export async function runMigrateSubcommand(command, genOneArgs, genTwoArgs, runTool = runMigrationTool) {
-    // Superseded pre-0.9.0 .akm layouts are a migration concern like any other:
-    // status names them, apply removes them. (First shipped as a bolted-on
-    // `health --clean-dead-residue` flag; folded here where it belongs.) The
-    // legacy extraParams -> first-class-field config lift (#852) is the same
-    // shape: status names it, apply persists it once instead of the old
-    // permanent silent lift on every config load.
-    // No configured bundle means there is no stash to scan — an empty domain,
-    // not an error — so migrate still works before `akm bundle create`. Any
-    // OTHER ConfigError propagates.
-    const configPath = getConfigPath();
-    const applyResidue = command === "migrate-apply" && !genOneArgs.includes("--dry-run");
-    // The config lift runs BEFORE anything that loads config. A config still
-    // carrying legacy extraParams keys fails `loadConfig` closed, and the error
-    // it fails with names `akm migrate apply` as the remedy -- but both
-    // `resolveStashDir` below and the task migrator itself load config, so that
-    // remedy could never reach the lift that fixes it. Applying it first is what
-    // makes the advice true. `resetConfigCache` so every load below sees the
-    // rewritten file rather than the rejected one.
-    const configExtraParams = applyResidue
-        ? applyConfigExtraParamsLift(configPath)
-        : { pending: findConfigExtraParamsLift(configPath) };
-    if (applyResidue && configExtraParams.applied)
-        resetConfigCache();
-    // status and --dry-run cannot rewrite the file, so a pending lift still
-    // blocks every config load below. Report it as the blocker rather than
-    // letting the operator hit the same circular error again.
-    const pendingLift = applyResidue ? undefined : configExtraParams.pending;
-    if (pendingLift && pendingLift.lifted.length > 0) {
-        output(command, { status: "blocked", blockers: pendingLift.lifted, configExtraParams });
-        process.exitCode = EXIT_CODES.GENERAL;
-        return;
-    }
-    let stashDir;
-    try {
-        stashDir = resolveStashDir();
-    }
-    catch (error) {
-        if (!(error instanceof ConfigError) || error.code !== "STASH_DIR_NOT_FOUND")
-            throw error;
-    }
-    const first = await callMigrateTool(genOneArgs, runTool);
-    if (first.status !== EXIT_CODES.SUCCESS && first.status !== EXIT_CODES.GENERAL) {
-        process.exitCode = first.status;
-        return;
-    }
-    const second = await callMigrateTool(genTwoArgs, runTool);
-    if (second.status !== EXIT_CODES.SUCCESS && second.status !== EXIT_CODES.GENERAL) {
-        process.exitCode = second.status;
-        return;
-    }
-    if (!first.plan && !second.plan) {
-        if (first.status !== EXIT_CODES.SUCCESS)
-            process.exitCode = first.status;
-        return;
-    }
-    const combined = combineMigrationPlans(first, second);
-    // The stash-scoped sections need a bundle to scan; no configured bundle is
-    // an empty domain, not an error, so migrate still works before
-    // `akm bundle create`. The config lift is config-scoped and always runs.
-    const stashSections = stashDir === undefined
-        ? {}
-        : {
-            deadResidue: applyResidue
-                ? { removed: removeDeadResidue(stashDir) }
-                : { pending: findDeadResidueEntries(stashDir) },
-            staleTxns: applyResidue
-                ? { recovered: await recoverStaleTxns(stashDir) }
-                : { pending: findStaleTxnEntries(stashDir) },
-        };
-    output(command, { ...combined, ...stashSections, configExtraParams });
-    if (combined.status === "blocked")
-        process.exitCode = EXIT_CODES.GENERAL;
-}
-/**
- * Merge both generations' plans into the one combined envelope the command
- * prints. Deliberately PURE — every rule the combined plan encodes (the
- * {@link worstStatus} rollup, the fail-closed
- * {@link resolveGenerationStatus} contribution, and the blockers merge, which
- * orders generation 1's own blockers after its resolution error and before
- * generation 2's) is decided here from two plain values, so it is provable
- * without a subprocess, a CLI dispatch, or an output-mode singleton. The
- * caller keeps the only two effectful decisions: whether generation 2 runs at
- * all, and the process exit code.
- */
-export function combineMigrationPlans(first, second) {
-    const firstResolved = resolveGenerationStatus(first, "task-v2-to-v3");
-    const secondResolved = resolveGenerationStatus(second, "task-v3-to-task-source-v4");
-    return {
-        schemaVersion: 1,
-        status: worstStatus(firstResolved.status, secondResolved.status),
-        blockers: [
-            ...(firstResolved.error ? [firstResolved.error] : []),
-            ...(first.plan?.blockers ?? []),
-            ...(secondResolved.error ? [secondResolved.error] : []),
-            ...(second.plan?.blockers ?? []),
-        ],
-        taskV3Migration: first.plan?.taskV3Migration,
-        taskV4Migration: second.plan?.taskV4Migration,
-        ...(first.plan?.backupPath !== undefined ? { backupPath: first.plan.backupPath } : {}),
-        ...(first.plan?.applied !== undefined ? { applied: first.plan.applied } : {}),
-        ...(second.plan?.backupPath !== undefined ? { taskV4BackupPath: second.plan.backupPath } : {}),
-        ...(second.plan?.applied !== undefined ? { taskV4Applied: second.plan.applied } : {}),
-    };
+    if (plan)
+        output(command, plan);
+    else if (line)
+        console.log(line);
+    if (result.status !== EXIT_CODES.SUCCESS)
+        process.exitCode = result.status;
 }
 export const migrateCommand = defineGroupCommand({
-    meta: { name: "migrate", description: "Inspect or apply task-v2 and task-v3 sources to task source v4" },
+    meta: {
+        name: "migrate",
+        description: "Inspect or apply pending migrations: legacy config, state.db, and task-v2/v3 sources to v4",
+    },
     subCommands: {
         status: defineJsonCommand({
-            meta: { name: "status", description: "Read-only task-v2 and task-v3 migration check" },
+            meta: { name: "status", description: "Read-only check of every pending migration" },
             run() {
-                return runMigrateSubcommand("migrate-status", ["status"], ["task-v4-status"]);
+                return runMigrateSubcommand("migrate-status", ["status"]);
             },
         }),
         apply: defineJsonCommand({
             meta: {
                 name: "apply",
-                description: "Back up and atomically convert task-v2 and task-v3 files to task source v4",
+                description: "Back up and apply every pending migration (`akm upgrade` runs this after an install)",
             },
             args: {
                 "dry-run": {
@@ -212,13 +55,10 @@ export const migrateCommand = defineGroupCommand({
                 },
             },
             run({ args }) {
-                const dryRunFlag = args.dryRun ? ["--dry-run"] : [];
-                return runMigrateSubcommand("migrate-apply", ["apply", ...dryRunFlag], ["task-v4-apply", ...dryRunFlag]);
+                return runMigrateSubcommand("migrate-apply", args.dryRun ? ["apply", "--dry-run"] : ["apply"]);
             },
         }),
     },
-    // No `defaultRun`: bare `akm migrate` is a usage error (exit 2). This group
-    // already threw its own hand-rolled UsageError; it now shares the canonical
-    // one from `defineGroupCommand` so the message and hint match every other
-    // group — owner ruling 12.
+    // No `defaultRun`: bare `akm migrate` is a usage error (exit 2), the
+    // canonical bare-group behavior shared with every other group.
 });

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

@@ -3,6 +3,7 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import { getStringArg, parsePositiveIntFlag } from "../../cli/parse-args.js";
 import { defineJsonCommand, output } from "../../cli/shared.js";
+import { VALID_ADAPTER_IDS } from "../../core/adapter/adapter-ids.js";
 import { UsageError } from "../../core/errors.js";
 import { appendEvent } from "../../core/events.js";
 import { warn } from "../../core/warn.js";
@@ -75,6 +76,11 @@ export const addCommand = defineJsonCommand({
         provider: { type: "string", description: "Provider type (e.g. website, npm). Required for URL sources." },
         options: { type: "string", description: 'Provider options as JSON (e.g. \'{"apiKey":"key"}\').' },
         name: { type: "string", description: "Human-friendly name for the source" },
+        adapter: {
+            type: "string",
+            description: "Override the auto-detected component adapter for a local directory (#909). One of: " +
+                `${VALID_ADAPTER_IDS.join(", ")}.`,
+        },
         writable: {
             type: "boolean",
             description: "Mark a git bundle as writable so changes can be pushed back",
@@ -145,6 +151,7 @@ export const addCommand = defineJsonCommand({
             name: args.name,
             options: Object.keys(websiteOptions).length > 0 ? websiteOptions : undefined,
             writable: args.writable,
+            adapter: args.adapter,
         });
         appendEvent({
             eventType: "add",

package/dist/commands/sources/installed-stashes.js

@@ -16,6 +16,7 @@
 import { createHash } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
+import { detectAdapterId } from "../../core/adapter/detect-adapter.js";
 import { isWithin, resolveStashDir } from "../../core/common.js";
 import { acquireConfigReadFence, bundleComponentConfig, getSources, loadConfig } from "../../core/config/config.js";
 import { AkmError, ConfigError, NotFoundError, UsageError } from "../../core/errors.js";
@@ -150,13 +151,40 @@ function describeBundleSource(entry) {
     }
     return { kind: "npm", locator: entry.npm ?? "" };
 }
-function describeComponents(entry) {
-    return Object.entries(entry.components ?? {}).map(([name, component]) => ({
-        name,
-        ...(component.root !== undefined ? { root: component.root } : {}),
-        ...(component.adapter !== undefined ? { adapter: component.adapter } : {}),
-        ...(component.writable !== undefined ? { writable: component.writable } : {}),
-    }));
+/**
+ * Per-component `{ adapter, detected }` disclosure (#908/#909): `adapter` is
+ * the EFFECTIVE adapter (explicit config, or auto-detected via the same
+ * ordered probe `akm index` uses) and `detected` is `true` exactly when no
+ * explicit `adapter` was configured. Before this, an auto-detected adapter
+ * was invisible on `akm bundle list` — a mixed-layout bundle silently
+ * shadowed by a narrower adapter (#908) gave no sign a choice had even been
+ * made. `bundleRoot` is the bundle's resolved content root (lock `localRoot`
+ * or its plain `path`), or `undefined` when neither is known yet (an
+ * unresolved registry/website source) — detection is skipped in that case
+ * rather than probing a path that may not exist.
+ */
+function describeComponents(entry, bundleRoot) {
+    const configuredComponents = entry.components ?? {};
+    const names = Object.keys(configuredComponents);
+    if (names.length === 0) {
+        // No explicit component at all — the implicit single component every
+        // bundle gets (spec §1.2 rule 5; `deriveInstallations`/`componentForSource`
+        // apply the same "main"-shaped default at index time).
+        const adapter = bundleRoot !== undefined ? detectAdapterId(bundleRoot) : "akm";
+        return [{ name: "main", adapter, detected: true }];
+    }
+    return names.map((name) => {
+        const component = configuredComponents[name];
+        const componentRoot = bundleRoot !== undefined ? path.resolve(bundleRoot, component.root ?? ".") : undefined;
+        const adapter = component.adapter ?? (componentRoot !== undefined ? detectAdapterId(componentRoot) : "akm");
+        return {
+            name,
+            ...(component.root !== undefined ? { root: component.root } : {}),
+            adapter,
+            detected: component.adapter === undefined,
+            ...(component.writable !== undefined ? { writable: component.writable } : {}),
+        };
+    });
 }
 function describeLock(entry) {
     if (!entry)
@@ -241,7 +269,7 @@ export async function akmListSources(input) {
             ...(lock?.resolvedVersion !== undefined ? { version: lock.resolvedVersion } : {}),
             writable: componentWritable ?? bundle.writable ?? kind === "filesystem",
             ...(configured.registryId !== undefined ? { registryId: configured.registryId } : {}),
-            components: describeComponents(configured),
+            components: describeComponents(configured, root || undefined),
             lock: describeLock(lock),
             itemCount: bundleCounts.itemCount,
             byType: bundleCounts.byType,