akm-cli 0.9.0-rc.2 → 0.9.0-rc.4

package/dist/commands/read/curate.js

@@ -14,7 +14,7 @@
  * `mergeCurateSearchResponses`) by importing them directly.
  */
 import fs from "node:fs";
-import { parseAssetRef } from "../../core/asset/asset-ref.js";
+import { parseAssetRef, refToString } from "../../core/asset/asset-ref.js";
 import { parseFrontmatter } from "../../core/asset/frontmatter.js";
 import { getIndexPassConfig, loadConfig } from "../../core/config/config.js";
 import { rethrowIfTestIsolationError, UsageError } from "../../core/errors.js";
@@ -78,10 +78,12 @@ function logCurateEvent(query, result, eventSource = "user") {
             for (const item of result.items) {
                 if (!("ref" in item) || typeof item.ref !== "string")
                     continue;
+                const parsed = parseAssetRef(item.ref);
+                const itemOrigin = "origin" in item && typeof item.origin === "string" ? item.origin : undefined;
                 insertUsageEvent(db, {
                     event_type: "curate",
                     query,
-                    entry_ref: item.ref,
+                    entry_ref: refToString({ ...parsed, ...(parsed.origin || !itemOrigin ? {} : { origin: itemOrigin }) }),
                     source: eventSource,
                 });
             }

package/dist/commands/read/knowledge.js

@@ -21,7 +21,7 @@ import { loadConfig } from "../../core/config/config.js";
 import { UsageError } from "../../core/errors.js";
 import { resolveStashStandards } from "../../core/standards/resolve-stash-standards.js";
 import { warn } from "../../core/warn.js";
-import { commitWriteTargetBoundary, formatRefForMessage, resolveWriteTarget, writeAssetToSource, } from "../../core/write-source.js";
+import { commitWriteTargetBoundary, formatRefForMessage, recordWriteTargetPath, resolveWriteTarget, writeAssetToSource, } from "../../core/write-source.js";
 import { indexWrittenAssets } from "../../indexer/index-written-assets.js";
 import { resolveSourceEntries } from "../../indexer/search/search-source.js";
 import { fetchWebsiteMarkdownSnapshot, shouldAllowPrivateWebsiteUrlForTests } from "../../sources/website-ingest.js";
@@ -528,6 +528,9 @@ export async function writeMarkdownAsset(options) {
         // Degrade to the same applied:false report the non-writable path uses.
         try {
             writeSupersededEdge(item.filePath, result.ref);
+            if (path.resolve(item.stashRoot) === path.resolve(source.path)) {
+                recordWriteTargetPath(source, item.filePath);
+            }
         }
         catch (error) {
             const reason = `demotion failed: ${error instanceof Error ? error.message : String(error)}`;

package/dist/commands/read/search.js

@@ -11,6 +11,7 @@
  * a registry search behind `--source registry|both`, and log a usage event.
  * Provider `search()` methods do not exist.
  */
+import { parseAssetRef, refToString } from "../../core/asset/asset-ref.js";
 import { loadConfig } from "../../core/config/config.js";
 import { rethrowIfTestIsolationError, UsageError } from "../../core/errors.js";
 import { appendEvent } from "../../core/events.js";
@@ -191,8 +192,11 @@ function resolveEntryIds(db, hits) {
     for (const hit of hits) {
         try {
             const entryId = getEntryIdByFilePath(db, hit.path);
-            if (entryId !== undefined)
-                results.push({ entryId, ref: hit.ref });
+            if (entryId !== undefined) {
+                const parsed = parseAssetRef(hit.ref);
+                const origin = parsed.origin ?? hit.origin ?? undefined;
+                results.push({ entryId, ref: refToString({ ...parsed, ...(origin ? { origin } : {}) }) });
+            }
         }
         catch {
             /* skip unresolvable */

package/dist/commands/read/show.js

@@ -19,14 +19,14 @@
 import fs from "node:fs";
 import path from "node:path";
 import { findCittyTopLevelCommandIndex } from "../../cli/parse-args.js";
-import { parseAssetRef } from "../../core/asset/asset-ref.js";
+import { parseAssetRef, refToString } from "../../core/asset/asset-ref.js";
 import { parseFrontmatter } from "../../core/asset/frontmatter.js";
 import { META_DIR, parseMetaRef, resolveMetaFilePath } from "../../core/asset/stash-meta.js";
 import { asNonEmptyString } from "../../core/common.js";
 import { getIndexPassConfig, loadConfig } from "../../core/config/config.js";
 import { NotFoundError, rethrowIfTestIsolationError, UsageError } from "../../core/errors.js";
 import { appendEvent, readEvents } from "../../core/events.js";
-import { closeDatabase, computeBodyHash, findEntryIdByRef, openExistingDatabase } from "../../indexer/db/db.js";
+import { closeDatabase, computeBodyHash, findEntryIdByRef, getEntryIdByFilePath, openExistingDatabase, } from "../../indexer/db/db.js";
 import { hasGraphData } from "../../indexer/db/graph-db.js";
 import { listRelatedPathsForFile } from "../../indexer/graph/graph-boost.js";
 import { extractGraphForSingleFile } from "../../indexer/graph/graph-extraction.js";
@@ -160,7 +160,7 @@ export async function akmShowUnified(input) {
     }
     // Count prior shows of this ref before logging the current one.
     const priorShowCount = recentShowCount(ref);
-    logShowEvent(ref, input.eventSource);
+    logShowEvent(ref, input.eventSource, result.path, result.origin);
     if (priorShowCount >= 2) {
         // Agent has shown this same asset 3+ times — inject a loop-break hint.
         result.showLoopWarning = priorShowCount + 1;
@@ -257,11 +257,12 @@ function recentShowCount(ref) {
         return 0;
     }
 }
-function logShowEvent(ref, eventSource = "user") {
+function logShowEvent(ref, eventSource = "user", filePath, origin) {
     // Emit a structured event to events.jsonl so workflow-trace consumers
     // detect akm show invocations without relying on stdout scraping.
     const parsed = parseAssetRef(ref);
-    appendEvent({ eventType: "show", ref, metadata: { type: parsed.type, name: parsed.name } });
+    const eventRef = refToString({ ...parsed, ...(parsed.origin || !origin ? {} : { origin }) });
+    appendEvent({ eventType: "show", ref: eventRef, metadata: { type: parsed.type, name: parsed.name } });
     // Detect if this show is a selection from a recent search result.
     try {
         // D7: bound the query to the last 60 s so we never scan unbounded history
@@ -295,8 +296,8 @@ function logShowEvent(ref, eventSource = "user") {
         withIndexDb((db) => {
             insertUsageEvent(db, {
                 event_type: "show",
-                entry_ref: ref,
-                entry_id: findEntryIdByRef(db, ref),
+                entry_ref: eventRef,
+                entry_id: filePath ? getEntryIdByFilePath(db, filePath) : findEntryIdByRef(db, eventRef),
                 source: eventSource,
             });
         }, { busyTimeoutMs: TELEMETRY_BUSY_TIMEOUT_MS });

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

@@ -5,7 +5,7 @@ import * as childProcess from "node:child_process";
 import { createHash } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
-import { fetchWithRetry, IS_WINDOWS } from "../../core/common.js";
+import { fetchWithRetry, IS_WINDOWS, ResponseTooLargeError, readBodyWithByteCap } from "../../core/common.js";
 import { warn } from "../../core/warn.js";
 import { githubHeaders } from "../../integrations/github.js";
 import { getDirname, mainPath, semverOrder } from "../../runtime.js";
@@ -14,6 +14,61 @@ const DEFAULT_PACKAGE_NAME = "akm-cli";
 const NODE_MODULES_SEGMENT = "/node_modules/";
 const BUN_GLOBAL_INSTALL_PATTERN = /(^|\/)\.bun\/(?:[^/]+\/)+node_modules\//;
 const PNPM_GLOBAL_INSTALL_PATTERN = /(^|\/)(?:pnpm\/global|\.pnpm-global)(?:\/\d+)?\/node_modules\//;
+const MIGRATION_CONTRACT_VERSION = "0.9.0-rc.0";
+const MAX_BINARY_DOWNLOAD_BYTES = 256 * 1024 * 1024;
+const MAX_CHECKSUM_METADATA_BYTES = 1024 * 1024;
+export function defaultMigrationCommand(preparedConfigPath) {
+    const configArgs = preparedConfigPath ? ["--config", preparedConfigPath] : [];
+    return {
+        preflight: (akmBin) => runRequiredCommand(akmBin, ["migrate", "status"], "Migration preflight"),
+        stagedPreflight: (akmBin) => runRequiredCommand(akmBin, ["migrate", "status", ...configArgs], "Staged migration preflight"),
+        apply: (akmBin) => runRequiredCommand(akmBin, ["migrate", "apply", ...configArgs], "Migration apply"),
+    };
+}
+async function streamResponseToFile(response, destination, maxBytes) {
+    const declaredText = response.headers.get("content-length");
+    if (declaredText) {
+        const declared = Number(declaredText);
+        if (Number.isFinite(declared) && declared > maxBytes) {
+            await response.body?.cancel().catch(() => undefined);
+            throw new ResponseTooLargeError(response.url || "binary download", maxBytes, declared);
+        }
+    }
+    if (!response.body)
+        throw new Error("Binary download response did not provide a streaming body.");
+    const fd = fs.openSync(destination, "w", 0o600);
+    const reader = response.body.getReader();
+    const hash = createHash("sha256");
+    let byteSize = 0;
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            if (!value)
+                continue;
+            byteSize += value.byteLength;
+            if (byteSize > maxBytes) {
+                await reader.cancel().catch(() => undefined);
+                throw new ResponseTooLargeError(response.url || "binary download", maxBytes, byteSize);
+            }
+            hash.update(value);
+            let written = 0;
+            while (written < value.byteLength)
+                written += fs.writeSync(fd, value, written, value.byteLength - written);
+        }
+        fs.fdatasyncSync(fd);
+        return { byteSize, sha256: hash.digest("hex") };
+    }
+    catch (error) {
+        removeFileBestEffort(destination);
+        throw error;
+    }
+    finally {
+        reader.releaseLock();
+        fs.closeSync(fd);
+    }
+}
 /** Read live runtime signals. */
 export function getInstallSignals() {
     return {
@@ -72,7 +127,7 @@ export async function checkForUpdate(currentVersion) {
     if (!response.ok) {
         throw new Error(`Failed to check for updates: ${response.status} ${response.statusText}`);
     }
-    const release = (await response.json());
+    const release = JSON.parse(await readBodyWithByteCap(response, MAX_CHECKSUM_METADATA_BYTES));
     const latestTag = release.tag_name ?? "";
     const latestVersion = latestTag.replace(/^v/, "");
     return {
@@ -82,10 +137,11 @@ export async function checkForUpdate(currentVersion) {
         installMethod,
     };
 }
-export async function performUpgrade(check, opts) {
+export async function performUpgrade(check, opts, dependencies) {
     const { currentVersion, latestVersion, installMethod } = check;
     const force = opts?.force === true;
     const skipPostUpgrade = opts?.skipPostUpgrade === true;
+    const migration = dependencies?.migration ?? defaultMigrationCommand(opts?.migrationConfig);
     // All install methods can short-circuit here unless the user explicitly forces an upgrade.
     if (!check.updateAvailable && !force) {
         return {
@@ -96,11 +152,19 @@ export async function performUpgrade(check, opts) {
             message: `akm v${currentVersion} is already the latest version`,
         };
     }
+    if (latestVersion &&
+        semverOrder(currentVersion, MIGRATION_CONTRACT_VERSION) < 0 &&
+        semverOrder(latestVersion, MIGRATION_CONTRACT_VERSION) >= 0) {
+        throw new Error("AKM 0.8 does not implement the migrate command or the --migration-config upgrade contract, so self-update cannot safely cross into 0.9. " +
+            "Prepare the 0.9 config and an independent backup, install or stage the 0.9 binary manually, then use the new binary to run: " +
+            "akm migrate apply --config <prepared-0.9.json>. See docs/migration/v0.8-to-v0.9.md.");
+    }
     const packageManagerCommand = getPackageManagerUpgradeCommand(installMethod);
     if (packageManagerCommand) {
         if (!latestVersion) {
             throw new Error("Unable to determine latest version from GitHub releases. Check https://github.com/itlackey/akm/releases");
         }
+        migration.preflight("akm");
         const result = childProcess.spawnSync(packageManagerCommand.command, packageManagerCommand.args, {
             encoding: "utf8",
             env: process.env,
@@ -113,6 +177,7 @@ export async function performUpgrade(check, opts) {
             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}`);
         }
+        migration.apply("akm");
         return {
             currentVersion,
             newVersion: latestVersion,
@@ -139,12 +204,34 @@ export async function performUpgrade(check, opts) {
     const binaryName = getAkmBinaryName();
     const binaryUrl = `https://github.com/${REPO}/releases/download/${tag}/${binaryName}`;
     const checksumsUrl = `https://github.com/${REPO}/releases/download/${tag}/checksums.txt`;
+    const execPath = dependencies?.execPath ?? process.execPath;
+    const execDir = path.dirname(execPath);
+    const execName = path.basename(execPath);
+    const stagedPath = IS_WINDOWS
+        ? path.join(execDir, `.${execName}.new.${process.pid}`)
+        : path.join(execDir, `.${execName}.tmp.${process.pid}`);
+    const backupPath = `${execPath}${IS_WINDOWS ? ".old" : ".bak"}`;
     // Download binary
     const binaryResponse = await fetchWithRetry(binaryUrl);
     if (!binaryResponse.ok) {
         throw new Error(`Failed to download binary: ${binaryResponse.status} ${binaryResponse.statusText}`);
     }
-    const binaryData = new Uint8Array(await binaryResponse.arrayBuffer());
+    let downloaded;
+    try {
+        downloaded = await streamResponseToFile(binaryResponse, stagedPath, MAX_BINARY_DOWNLOAD_BYTES);
+        if (!IS_WINDOWS)
+            fs.chmodSync(stagedPath, 0o755);
+    }
+    catch (err) {
+        removeFileBestEffort(stagedPath);
+        const code = err.code;
+        if (code === "EACCES" || code === "EPERM") {
+            throw new Error(`Permission denied writing to ${execDir}.\n` +
+                `${IS_WINDOWS ? "Try running as Administrator." : "Run: sudo akm upgrade"}\n` +
+                `Or re-run the install script: curl -fsSL https://raw.githubusercontent.com/${REPO}/main/install.sh | bash`);
+        }
+        throw err;
+    }
     // Download and verify checksum (mandatory — upgrade is blocked if checksums cannot be fetched)
     let checksumVerified = false;
     const skipChecksum = opts?.skipChecksum === true;
@@ -160,10 +247,10 @@ export async function performUpgrade(check, opts) {
             }
         }
         else {
-            const checksumsText = await checksumsResponse.text();
+            const checksumsText = await readBodyWithByteCap(checksumsResponse, MAX_CHECKSUM_METADATA_BYTES);
             const expectedHash = parseChecksumForFile(checksumsText, binaryName);
             if (expectedHash) {
-                const actualHash = createHash("sha256").update(binaryData).digest("hex");
+                const actualHash = downloaded.sha256;
                 if (actualHash !== expectedHash) {
                     throw new Error(`Checksum mismatch for ${binaryName}.\n` + `Expected: ${expectedHash}\n` + `Got:      ${actualHash}`);
                 }
@@ -183,6 +270,7 @@ export async function performUpgrade(check, opts) {
     catch (err) {
         if (err instanceof Error &&
             (err.message.includes("Checksum mismatch") || err.message.includes("Checksum verification failed"))) {
+            removeFileBestEffort(stagedPath);
             throw err;
         }
         // Network or parse failure
@@ -190,99 +278,46 @@ export async function performUpgrade(check, opts) {
             warn(`WARNING: Could not fetch or parse checksums: ${err instanceof Error ? err.message : String(err)}. Proceeding because --skip-checksum was provided.`);
         }
         else {
+            removeFileBestEffort(stagedPath);
             throw new Error(`Checksum verification failed: ${err instanceof Error ? err.message : String(err)}. ` +
                 `Use --skip-checksum to bypass (not recommended).`);
         }
     }
-    const execPath = process.execPath;
-    const execDir = path.dirname(execPath);
-    const execName = path.basename(execPath);
-    if (IS_WINDOWS) {
-        // Windows: rename running exe, write new one, clean up old on success
-        const oldPath = `${execPath}.old`;
-        try {
-            fs.renameSync(execPath, oldPath);
-        }
-        catch (err) {
-            const code = err.code;
-            if (code === "EPERM" || code === "EACCES") {
-                throw new Error(`Permission denied. Cannot rename ${execPath}.\n` +
-                    `Try running as Administrator, or re-download from https://github.com/${REPO}/releases`);
-            }
-            const detail = err instanceof Error ? err.message : String(err);
-            throw new Error(`Failed to rename ${execPath}: ${detail}`);
-        }
-        try {
-            fs.writeFileSync(execPath, binaryData);
-        }
-        catch (err) {
-            // Restore from old
-            fs.renameSync(oldPath, execPath);
-            throw err;
-        }
-        // Best-effort cleanup of .old
-        try {
-            fs.unlinkSync(oldPath);
-        }
-        catch {
-            // Windows may lock the old exe — it will be cleaned up on next startup or manually
-        }
+    try {
+        migration.preflight(execPath);
+        migration.stagedPreflight(stagedPath);
     }
-    else {
-        // Unix: write to temp file, chmod +x, atomic rename
-        const tmpPath = path.join(execDir, `.${execName}.tmp.${process.pid}`);
-        const bakPath = `${execPath}.bak`;
-        try {
-            fs.writeFileSync(tmpPath, binaryData);
-            fs.chmodSync(tmpPath, 0o755);
-        }
-        catch (err) {
-            // Clean up temp file on failure
-            try {
-                fs.unlinkSync(tmpPath);
-            }
-            catch {
-                /* ignore */
-            }
-            const code = err.code;
-            if (code === "EACCES" || code === "EPERM") {
-                throw new Error(`Permission denied writing to ${execDir}.\n` +
-                    `Run: sudo akm upgrade\n` +
-                    `Or re-run the install script: curl -fsSL https://raw.githubusercontent.com/${REPO}/main/install.sh | bash`);
-            }
-            throw err;
-        }
-        // Backup current, then atomic rename
-        try {
-            fs.copyFileSync(execPath, bakPath);
-            fs.renameSync(tmpPath, execPath);
-        }
-        catch (err) {
-            // Restore from backup if rename failed
-            try {
-                fs.unlinkSync(tmpPath);
-            }
-            catch {
-                /* ignore */
-            }
-            try {
-                if (fs.existsSync(bakPath) && !fs.existsSync(execPath)) {
-                    fs.renameSync(bakPath, execPath);
-                }
-            }
-            catch {
-                /* ignore */
-            }
-            throw err;
-        }
-        // Cleanup backup
-        try {
-            fs.unlinkSync(bakPath);
-        }
-        catch {
-            /* ignore */
+    catch (err) {
+        removeFileBestEffort(stagedPath);
+        throw err;
+    }
+    if (fs.existsSync(backupPath)) {
+        removeFileBestEffort(stagedPath);
+        throw new Error(`Refusing to overwrite retained previous binary at ${backupPath}.`);
+    }
+    try {
+        if (IS_WINDOWS)
+            fs.renameSync(execPath, backupPath);
+        else
+            fs.copyFileSync(execPath, backupPath);
+        fs.renameSync(stagedPath, execPath);
+    }
+    catch (err) {
+        removeFileBestEffort(stagedPath);
+        if (!fs.existsSync(execPath) && fs.existsSync(backupPath)) {
+            fs.renameSync(backupPath, execPath);
         }
+        throw err;
+    }
+    try {
+        migration.apply(execPath);
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        throw new Error(`Migration apply failed; the new binary remains installed and the previous binary retained at ${backupPath}: ${detail}`);
     }
+    // Keep the previous binary available until migration apply has completed.
+    removeFileBestEffort(backupPath);
     return {
         currentVersion,
         newVersion: latestVersion,
@@ -290,32 +325,19 @@ export async function performUpgrade(check, opts) {
         installMethod,
         binaryPath: execPath,
         checksumVerified,
-        // For binary installs, the new binary now lives at execPath; spawn it
-        // directly so the post-upgrade work runs against the new code.
         postUpgrade: runPostUpgradeTasks(execPath, { skip: skipPostUpgrade }),
     };
 }
 /**
- * Run the post-upgrade tasks against the *new* binary as a child process.
- *
- * Why a child process: the running akm process still has the old code in
- * memory. Calling loadConfig()/akmIndex() in-process would use the old
- * implementations and miss any DB_VERSION / config-key changes the new
- * release introduces.
- *
- * The new binary's `akm index` does the work for us:
- *   1. loadConfig() runs at startup — auto-migrates legacy `stashes` →
- *      `sources` if the on-disk config still uses the old key.
- *   2. ensureSchema() converges index.db forward via its idempotent baseline
- *      schema + additive migrations (no destructive rebuild).
- *   3. The full reindex repopulates entries + workflow_documents + FTS.
+ * Rebuild the derived index after the explicit migration command succeeds.
+ * Migration and indexing are intentionally separate lifecycle steps.
  */
 function runPostUpgradeTasks(akmBin, opts) {
     if (opts.skip) {
         return {
             ok: true,
             skipped: true,
-            message: "Skipped post-upgrade tasks. Run `akm index` manually to migrate config and rebuild the index.",
+            message: "Migration completed; skipped the index rebuild. Run `akm index` manually to rebuild the index.",
         };
     }
     try {
@@ -328,7 +350,7 @@ function runPostUpgradeTasks(akmBin, opts) {
             return {
                 ok: false,
                 skipped: false,
-                message: `Post-upgrade tasks could not start: ${result.error.message}. Run \`akm index\` manually.`,
+                message: `Migration completed, but the index rebuild could not start: ${result.error.message}. Run \`akm index\` manually.`,
             };
         }
         if (result.status !== 0) {
@@ -337,14 +359,14 @@ function runPostUpgradeTasks(akmBin, opts) {
                 ok: false,
                 skipped: false,
                 exitCode: result.status,
-                message: `Post-upgrade \`akm index\` failed (${detail}). Run \`akm index\` manually.`,
+                message: `Migration completed, but post-upgrade \`akm index\` failed (${detail}). Run \`akm index\` manually.`,
             };
         }
         return {
             ok: true,
             skipped: false,
             exitCode: 0,
-            message: "Config migrated (if needed) and index rebuilt against the new binary.",
+            message: "Migration completed and the index was rebuilt against the new binary.",
         };
     }
     catch (err) {
@@ -352,10 +374,32 @@ function runPostUpgradeTasks(akmBin, opts) {
         return {
             ok: false,
             skipped: false,
-            message: `Post-upgrade tasks failed: ${detail}. Run \`akm index\` manually.`,
+            message: `Migration completed, but the index rebuild failed: ${detail}. Run \`akm index\` manually.`,
         };
     }
 }
+function runRequiredCommand(akmBin, args, label) {
+    const result = childProcess.spawnSync(akmBin, args, {
+        encoding: "utf8",
+        env: process.env,
+        stdio: "pipe",
+    });
+    if (result.error) {
+        throw new Error(`${label} could not start: ${result.error.message}`);
+    }
+    if (result.status !== 0) {
+        const detail = (result.stderr ?? "").trim() || (result.stdout ?? "").trim() || `exit code ${result.status}`;
+        throw new Error(`${label} failed (${detail}).`);
+    }
+}
+function removeFileBestEffort(filePath) {
+    try {
+        fs.unlinkSync(filePath);
+    }
+    catch {
+        // Cleanup is best-effort; the primary operation determines success.
+    }
+}
 function parseChecksumForFile(checksumsText, filename) {
     for (const line of checksumsText.split("\n")) {
         const trimmed = line.trim();

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

@@ -115,9 +115,13 @@ export const upgradeCommand = defineJsonCommand({
         },
         "skip-post-upgrade": {
             type: "boolean",
-            description: "Skip the post-upgrade `akm index` rebuild (config auto-migration still runs on next `akm` invocation)",
+            description: "Skip the post-upgrade index rebuild (migration preflight and apply still run)",
             default: false,
         },
+        "migration-config": {
+            type: "string",
+            description: "For 0.9+ upgrades, pass an operator-prepared config only to the new binary's migration apply",
+        },
     },
     async run({ args }) {
         const check = await checkForUpdate(pkgVersion);
@@ -127,7 +131,8 @@ export const upgradeCommand = defineJsonCommand({
         }
         const skipChecksum = args["skip-checksum"];
         const skipPostUpgrade = args["skip-post-upgrade"];
-        const result = await performUpgrade(check, { force: args.force, skipChecksum, skipPostUpgrade });
+        const migrationConfig = args["migration-config"];
+        const result = await performUpgrade(check, { force: args.force, skipChecksum, skipPostUpgrade, migrationConfig });
         output("upgrade", result);
     },
 });

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

@@ -67,12 +67,12 @@ export const DEFAULT_IMPROVE_TASKS = [
     },
 ];
 /**
- * A schedule for the manual catch-up task. The scheduler requires a valid
- * cron expression even when the task is registered disabled, so we give the
- * unscheduled task a nominal far-future-ish cadence and leave it disabled —
- * the documented entry point is `akm tasks run akm-improve-catchup`.
+ * A schedule for the manual catch-up task. The scheduler requires a portable
+ * expression even when the task is registered disabled, so we give it a
+ * nominal daily cadence and leave it disabled. The documented entry point is
+ * `akm tasks run akm-improve-catchup`.
  */
-const MANUAL_TASK_NOMINAL_SCHEDULE = "0 4 1 1 *"; // 04:00 on Jan 1 — never effectively fires
+const MANUAL_TASK_NOMINAL_SCHEDULE = "0 4 * * *";
 const DEFAULT_DEPS = {
     list: akmTasksList,
     add: akmTasksAdd,

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

@@ -136,11 +136,15 @@ const tasksRunCommand = defineCommand({
         name: "run",
         description: "Execute a task now (this is what cron / launchd / schtasks invoke at the scheduled time)",
     },
-    args: { id: { type: "positional", description: "Task id", required: true } },
+    args: {
+        id: { type: "positional", description: "Task id", required: true },
+        scheduled: { type: "boolean", description: "Internal marker for scheduler-generated runs", default: false },
+    },
     async run({ args }) {
         await runWithJsonErrors(async () => {
-            const { id } = parseTaskRef(args.id);
-            const envelope = await akmTasksRun(id);
+            const envelope = await akmTasksRun(args.id, {
+                scheduled: args.scheduled === true,
+            });
             output("tasks-run", envelope);
             if (envelope.exitCode !== 0)
                 process.exit(envelope.exitCode);