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

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,

package/dist/commands/sources/self-update.js

@@ -7,10 +7,11 @@ import fs from "node:fs";
 import path from "node:path";
 import { fetchWithRetry, IS_WINDOWS, ResponseTooLargeError, readBodyWithByteCap, readChunkWithDeadline, } from "../../core/common.js";
 import { ConfigError } from "../../core/errors.js";
-import { upgradeHistoricalStateDatabase } from "../../core/state-db.js";
 import { warn } from "../../core/warn.js";
 import { githubHeaders } from "../../integrations/github.js";
 import { getDirname, mainPath, semverOrder } from "../../runtime.js";
+import { resolveNpmGlobalRoot } from "../../tasks/resolve-akm-bin.js";
+import { runMigrationTool } from "../migration-tool.js";
 const REPO = "itlackey/akm";
 const DEFAULT_PACKAGE_NAME = "akm-cli";
 const NODE_MODULES_SEGMENT = "/node_modules/";
@@ -91,8 +92,37 @@ export function getInstallSignals() {
         bunMain: mainPath,
         importMetaDir: getDirname(import.meta.url),
         hasAkmVersion: typeof AKM_VERSION !== "undefined",
+        npmGlobalRoot: resolveNpmGlobalRootForThisProcess(),
     };
 }
+function resolveNpmGlobalRootForThisProcess() {
+    const nodePath = process.env.AKM_LAUNCHER_NODE?.trim() || (process.versions.bun ? undefined : process.execPath);
+    if (!nodePath)
+        return undefined;
+    try {
+        return resolveNpmGlobalRoot(nodePath, process.env);
+    }
+    catch {
+        return undefined;
+    }
+}
+function isUnderDirectory(dir, root) {
+    const real = (value) => {
+        try {
+            return fs.realpathSync(value);
+        }
+        catch {
+            return path.resolve(value);
+        }
+    };
+    const relative = path.relative(real(root), real(dir));
+    return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+/** The package that depends on this akm: the directory holding the `node_modules` it lives in. */
+function packageLocalRoot(importMetaDir) {
+    const index = normalizePathSeparators(importMetaDir).lastIndexOf(NODE_MODULES_SEGMENT);
+    return index < 0 ? importMetaDir : importMetaDir.slice(0, index);
+}
 // AKM_VERSION ambient type is declared in globals.d.ts
 export function detectInstallMethod(signals) {
     const s = signals ?? getInstallSignals();
@@ -104,6 +134,14 @@ export function detectInstallMethod(signals) {
         if (PNPM_GLOBAL_INSTALL_PATTERN.test(normalizedImportMetaDir)) {
             return "pnpm";
         }
+        // A node_modules install outside the npm global root is a DEPENDENCY of
+        // some other package (an image's tools dir, a plugin's node_modules):
+        // it moves when that package does, and an `npm install -g` here would
+        // "succeed" while the parent kept executing its own copy. Only a proven
+        // global root can make that call; without one this stays "npm".
+        if (s.npmGlobalRoot && s.importMetaDir && !isUnderDirectory(s.importMetaDir, s.npmGlobalRoot)) {
+            return "package-local";
+        }
         return "npm";
     }
     // Bun-compiled binaries: mainPath points to a virtual /$bunfs/
@@ -172,7 +210,23 @@ export async function performUpgrade(check, opts, dependencies) {
     const { currentVersion, latestVersion, installMethod } = check;
     const force = opts?.force === true;
     const skipPostUpgrade = opts?.skipPostUpgrade === true;
-    // All install methods can short-circuit here unless the user explicitly forces an upgrade.
+    const runTool = dependencies?.runMigrationTool ?? runMigrationTool;
+    // Every `akm upgrade` ends by running `akm-migrate apply`, install or no
+    // install: the migrator on disk after the install step is the one whose
+    // migrations the installed akm needs, and an image that ships akm has
+    // nothing to install and nobody to run a migration by hand (#895). The two
+    // no-install cases return here.
+    if (installMethod === "package-local") {
+        const parent = packageLocalRoot(getInstallSignals().importMetaDir ?? "");
+        return {
+            currentVersion,
+            newVersion: latestVersion,
+            upgraded: false,
+            installMethod,
+            message: `akm runs as a dependency of the package at ${parent}; upgrade that package to move akm.`,
+            migration: await runMigrationStep(runTool),
+        };
+    }
     if (!check.updateAvailable && !force) {
         return {
             currentVersion,
@@ -180,6 +234,7 @@ export async function performUpgrade(check, opts, dependencies) {
             upgraded: false,
             installMethod,
             message: `akm v${currentVersion} is already the latest version`,
+            migration: await runMigrationStep(runTool),
         };
     }
     const packageManagerCommand = getPackageManagerUpgradeCommand(installMethod);
@@ -190,7 +245,7 @@ export async function performUpgrade(check, opts, dependencies) {
             latestVersion,
             installMethod,
             skipPostUpgrade,
-            upgradeState: dependencies?.upgradeHistoricalStateDatabase ?? upgradeHistoricalStateDatabase,
+            runTool,
         });
     }
     if (installMethod === "unknown") {
@@ -200,6 +255,7 @@ export async function performUpgrade(check, opts, dependencies) {
             upgraded: false,
             installMethod,
             message: `Unable to detect install method. Upgrade manually from https://github.com/${REPO}/releases`,
+            migration: await runMigrationStep(runTool),
         };
     }
     // Binary install
@@ -309,6 +365,8 @@ export async function performUpgrade(check, opts, dependencies) {
     }
     // The replacement completed; the temporary rollback copy is no longer needed.
     removeFileBestEffort(backupPath);
+    // The new binary is at execPath now, so this re-execs the NEW migrator.
+    const migration = await runMigrationStep(runTool);
     return {
         currentVersion,
         newVersion: latestVersion,
@@ -316,32 +374,46 @@ export async function performUpgrade(check, opts, dependencies) {
         installMethod,
         binaryPath: execPath,
         checksumVerified,
-        postUpgrade: runPostUpgradeTasks(execPath, { skip: skipPostUpgrade }, dependencies?.upgradeHistoricalStateDatabase ?? upgradeHistoricalStateDatabase),
+        migration,
+        postUpgrade: runPostUpgradeTasks(execPath, { skip: skipPostUpgrade }),
     };
 }
 /**
- * Rebuild the derived index after a successful upgrade.
+ * `akm-migrate apply`, spawned so it is whichever migrator is on disk NOW:
+ * after a successful install, the new one. Its JSON plan becomes the
+ * response's `migration`. A migrator that could not run or print a plan
+ * reports `failed` with its error text instead of throwing, so the install
+ * outcome the caller is about to report is never lost behind it.
  */
-function runPostUpgradeTasks(akmBin, opts, upgradeState) {
-    let stateUpgrade;
+async function runMigrationStep(runTool) {
+    let result;
     try {
-        stateUpgrade = upgradeState();
+        result = await runTool(["apply"]);
     }
     catch (error) {
-        const detail = error instanceof Error ? error.message : String(error);
-        return {
-            ok: false,
-            skipped: opts.skip,
-            message: `Upgrade completed, but the state schema was not prepared (${detail}). ` +
-                "Preserve state.db and run `akm upgrade --state-only` before other AKM commands (the binary is already current).",
-        };
+        return { status: "failed", error: error instanceof Error ? error.message : String(error) };
+    }
+    const line = result.stdout.trim();
+    try {
+        const plan = JSON.parse(line);
+        if (plan.status === "current" || plan.status === "ready" || plan.status === "blocked") {
+            return plan;
+        }
     }
-    const stateNote = stateUpgrade.safetyCopyPath ? ` Historical state safety copy: ${stateUpgrade.safetyCopyPath}.` : "";
+    catch {
+        // Not a plan; reported below with whatever the migrator did say.
+    }
+    return { status: "failed", error: result.stderr.trim() || line || `akm-migrate exited ${result.status}` };
+}
+/**
+ * Rebuild the derived index after a successful upgrade.
+ */
+function runPostUpgradeTasks(akmBin, opts) {
     if (opts.skip) {
         return {
             ok: true,
             skipped: true,
-            message: `Upgrade completed.${stateNote} Skipped the index rebuild. Run \`akm index\` manually to rebuild the index.`,
+            message: "Upgrade completed. Skipped the index rebuild. Run `akm index` manually to rebuild the index.",
         };
     }
     try {
@@ -354,7 +426,7 @@ function runPostUpgradeTasks(akmBin, opts, upgradeState) {
             return {
                 ok: false,
                 skipped: false,
-                message: `Upgrade completed.${stateNote} The index rebuild could not start: ${result.error.message}. Run \`akm index\` manually.`,
+                message: `Upgrade completed. The index rebuild could not start: ${result.error.message}. Run \`akm index\` manually.`,
             };
         }
         if (result.status !== 0) {
@@ -363,14 +435,14 @@ function runPostUpgradeTasks(akmBin, opts, upgradeState) {
                 ok: false,
                 skipped: false,
                 exitCode: result.status,
-                message: `Upgrade completed.${stateNote} Post-upgrade \`akm index\` failed (${detail}). Run \`akm index\` manually.`,
+                message: `Upgrade completed. Post-upgrade \`akm index\` failed (${detail}). Run \`akm index\` manually.`,
             };
         }
         return {
             ok: true,
             skipped: false,
             exitCode: 0,
-            message: `Upgrade completed and the index was rebuilt against the new binary.${stateNote}`,
+            message: "Upgrade completed and the index was rebuilt against the new binary.",
         };
     }
     catch (err) {
@@ -378,7 +450,7 @@ function runPostUpgradeTasks(akmBin, opts, upgradeState) {
         return {
             ok: false,
             skipped: false,
-            message: `Upgrade completed.${stateNote} The index rebuild failed: ${detail}. Run \`akm index\` manually.`,
+            message: `Upgrade completed. The index rebuild failed: ${detail}. Run \`akm index\` manually.`,
         };
     }
 }
@@ -387,8 +459,8 @@ function runPostUpgradeTasks(akmBin, opts, upgradeState) {
  * version verification → post-upgrade tasks.
  * Extracted whole so performUpgrade stays under its fn-size baseline.
  */
-function runPackageManagerUpgrade(input) {
-    const { packageManagerCommand, currentVersion, latestVersion, installMethod, skipPostUpgrade, upgradeState } = input;
+async function runPackageManagerUpgrade(input) {
+    const { packageManagerCommand, currentVersion, latestVersion, installMethod, skipPostUpgrade, runTool } = input;
     if (!latestVersion) {
         throw new Error("Unable to determine latest version from GitHub releases. Check https://github.com/itlackey/akm/releases");
     }
@@ -402,7 +474,12 @@ function runPackageManagerUpgrade(input) {
     }
     if (result.status !== 0) {
         const details = (result.stderr ?? "").trim() || (result.stdout ?? "").trim() || `exit code ${result.status}`;
-        throw new Error(`Failed to upgrade akm via ${installMethod}: ${details}\nRun manually: ${packageManagerCommand.displayCommand}`);
+        // The install could not change what runs, so the migrator on disk is
+        // still the right one: run it, then say so, or an operator reading the
+        // EACCES will assume the migration is stuck behind it (#895).
+        const migration = await runMigrationStep(runTool);
+        throw new Error(`Failed to upgrade akm via ${installMethod}: ${details}\nRun manually: ${packageManagerCommand.displayCommand}\n` +
+            `Pending migrations ran anyway (status: ${migration.status}).`);
     }
     // The package manager exiting 0 does not prove it delivered
     // `latestVersion`: a lagging `@latest` dist-tag (partial publish,
@@ -420,6 +497,7 @@ function runPackageManagerUpgrade(input) {
                 `v${installedVersion} (expected v${latestVersion}). The ${installMethod} registry's @latest tag ` +
                 `may be lagging the GitHub release — try again shortly, or install the exact version: ` +
                 `${packageManagerCommand.displayCommand.replace(/@latest\b/, `@${latestVersion}`)}`,
+            migration: await runMigrationStep(runTool),
         };
     }
     return {
@@ -430,7 +508,8 @@ function runPackageManagerUpgrade(input) {
         message: installedVersion === latestVersion
             ? `akm upgraded via ${installMethod} (verified: akm --version reports v${installedVersion})`
             : `akm upgraded via ${installMethod} (installed version could not be verified)`,
-        postUpgrade: runPostUpgradeTasks("akm", { skip: skipPostUpgrade }, upgradeState),
+        migration: await runMigrationStep(runTool),
+        postUpgrade: runPostUpgradeTasks("akm", { skip: skipPostUpgrade }),
     };
 }
 /**
@@ -520,40 +599,3 @@ export function getPackageManagerUpgradeCommand(installMethod, packageName = get
     }
     return undefined;
 }
-/**
- * Apply pending historical destructive state.db migrations WITHOUT installing a
- * new akm — the body of `akm upgrade --state-only`.
- *
- * Migrations flagged `historical-destructive` are refused during an ordinary
- * managed open: they need a verified sibling safety copy taken under the
- * migration writer lock, and that is deliberate, so an unattended `akm index`
- * can never quietly drop operator state.
- *
- * The bug this fixes is not the guard but its reachability (#895). The only
- * code path that set `allowHistoricalDestructiveStateUpgrade` ran as a
- * POST-INSTALL step of a real upgrade, so it sat behind an npm install. Where
- * akm is installed globally by an image and the runtime user is unprivileged,
- * that install fails EACCES and throws long before the migration is reached —
- * leaving the documented remedy impossible to run and `akm index --full`
- * permanently blocked. Nothing about the migration itself needs the network,
- * root, or a new binary; it is local, offline, and already verified.
- *
- * The safety copy is NOT skipped here. This changes only who may ask for the
- * migration, never what it does.
- */
-export function upgradeStateOnly(currentVersion, dependencies) {
-    const upgradeState = dependencies?.upgradeHistoricalStateDatabase ?? upgradeHistoricalStateDatabase;
-    const result = upgradeState();
-    return {
-        currentVersion,
-        newVersion: currentVersion,
-        upgraded: false,
-        installMethod: detectInstallMethod(),
-        message: result.upgraded
-            ? `Applied pending state.db migrations. Safety copy: ${result.safetyCopyPath}`
-            : "state.db is already current; no migration was needed",
-        stateUpgrade: result.safetyCopyPath
-            ? { applied: result.upgraded, safetyCopyPath: result.safetyCopyPath }
-            : { applied: result.upgraded },
-    };
-}