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

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/core/common.js

@@ -27,6 +27,9 @@ export const ASSET_TYPES = Object.freeze([...getAssetTypes()]);
 export const ASSET_TYPE_SET = new Set(ASSET_TYPES);
 // ── Constants ───────────────────────────────────────────────────────────────
 export const IS_WINDOWS = process.platform === "win32";
+export const MAX_CONFIG_FILE_BYTES = 1024 * 1024;
+export const MAX_LOCAL_METADATA_BYTES = 1024 * 1024;
+export const MAX_LOCK_METADATA_BYTES = 64 * 1024;
 export function isHttpUrl(value) {
     return !!value && /^https?:\/\//.test(value);
 }
@@ -58,6 +61,35 @@ export function isAssetType(type) {
     return Object.hasOwn(TYPE_DIRS, type);
 }
 // ── Utilities ───────────────────────────────────────────────────────────────
+export function readTextFileDescriptorWithLimit(fd, maxBytes, label = "File", displayPath = "(open file)") {
+    const stat = fs.fstatSync(fd);
+    if (!stat.isFile())
+        throw new ConfigError(`${label} is not a regular file: ${displayPath}.`, "INVALID_CONFIG_FILE");
+    if (stat.size > maxBytes) {
+        throw new ConfigError(`${label} exceeds the ${maxBytes}-byte limit: ${displayPath}.`, "INVALID_CONFIG_FILE");
+    }
+    const buffer = Buffer.allocUnsafe(maxBytes + 1);
+    let total = 0;
+    while (total <= maxBytes) {
+        const bytesRead = fs.readSync(fd, buffer, total, maxBytes + 1 - total, null);
+        if (bytesRead === 0)
+            break;
+        total += bytesRead;
+    }
+    if (total > maxBytes) {
+        throw new ConfigError(`${label} exceeds the ${maxBytes}-byte limit: ${displayPath}.`, "INVALID_CONFIG_FILE");
+    }
+    return buffer.subarray(0, total).toString("utf8");
+}
+export function readTextFileWithLimit(filePath, maxBytes, label = "File") {
+    const fd = fs.openSync(filePath, "r");
+    try {
+        return readTextFileDescriptorWithLimit(fd, maxBytes, label, filePath);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
 /**
  * Write content to a file atomically via a temp file + rename.
  * Prevents partial-write corruption on crash.
@@ -172,7 +204,7 @@ function isValidDirectory(dir) {
 function readStashDirFromConfig() {
     try {
         const configPath = getConfigPath();
-        const text = fs.readFileSync(configPath, "utf8");
+        const text = readTextFileWithLimit(configPath, MAX_CONFIG_FILE_BYTES, "Config file");
         const raw = JSON.parse(text);
         if (typeof raw === "object" && raw !== null && typeof raw.stashDir === "string" && raw.stashDir.trim()) {
             return raw.stashDir.trim();
@@ -370,8 +402,9 @@ export async function readBodyWithByteCap(response, maxBytes = DEFAULT_RESPONSE_
         // No streaming body available (e.g., some mock environments). Fall
         // back to text() but still enforce the cap post-hoc.
         const text = await response.text();
-        if (text.length > maxBytes)
-            throw new ResponseTooLargeError(url, maxBytes, text.length);
+        const byteLength = Buffer.byteLength(text, "utf8");
+        if (byteLength > maxBytes)
+            throw new ResponseTooLargeError(url, maxBytes, byteLength);
         return text;
     }
     const reader = body.getReader();

package/dist/core/config/config-io.js

@@ -15,7 +15,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { sleepSync } from "../../runtime.js";
-import { writeFileAtomic } from "../common.js";
+import { MAX_CONFIG_FILE_BYTES, readTextFileWithLimit, writeFileAtomic } from "../common.js";
 import { ConfigError } from "../errors.js";
 import { createLockPayload, probeLock, reclaimStaleLock, releaseLock, tryAcquireLockSync } from "../file-lock.js";
 import { getCacheDir, getConfigDir } from "../paths.js";
@@ -25,7 +25,7 @@ import { getCacheDir, getConfigDir } from "../paths.js";
  */
 export function readConfigText(configPath) {
     try {
-        return fs.readFileSync(configPath, "utf8");
+        return readTextFileWithLimit(configPath, MAX_CONFIG_FILE_BYTES, "Config file");
     }
     catch (err) {
         if (err.code === "ENOENT")