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

package/dist/scripts/migrations/import-fs-improve-runs-to-db.js

@@ -171,13 +171,6 @@ function statfsType(path) {
     return;
   }
 }
-function sleepSync(ms) {
-  if (isBun2) {
-    bunGlobal().sleepSync(ms);
-    return;
-  }
-  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
-}
 function bunGlobal() {
   return globalThis.Bun;
 }
@@ -252,7 +245,7 @@ var require_main = __commonJS((exports, module) => {
   var fs3 = __require("fs");
   var path2 = __require("path");
   var os = __require("os");
-  var crypto = __require("crypto");
+  var crypto2 = __require("crypto");
   var TIPS = [
     "◈ encrypted .env [www.dotenvx.com]",
     "◈ secrets for agents [www.dotenvx.com]",
@@ -498,7 +491,7 @@ var require_main = __commonJS((exports, module) => {
     const authTag = ciphertext.subarray(-16);
     ciphertext = ciphertext.subarray(12, -16);
     try {
-      const aesgcm = crypto.createDecipheriv("aes-256-gcm", key, nonce);
+      const aesgcm = crypto2.createDecipheriv("aes-256-gcm", key, nonce);
       aesgcm.setAuthTag(authTag);
       return `${aesgcm.update(ciphertext)}${aesgcm.final()}`;
     } catch (error) {
@@ -7740,38 +7733,6 @@ function getConfigDir(env = process.env, platform = process.platform) {
 function getConfigPath(env = process.env) {
   return path2.join(getConfigDir(env), "config.json");
 }
-function getCacheDir(env = process.env) {
-  const override = env.AKM_CACHE_DIR?.trim();
-  if (override)
-    return override;
-  if (IS_WINDOWS) {
-    const localAppData = env.LOCALAPPDATA?.trim();
-    if (localAppData)
-      return path2.join(localAppData, "akm");
-    const userProfile = env.USERPROFILE?.trim();
-    if (userProfile)
-      return path2.join(userProfile, "AppData", "Local", "akm");
-    const appData = env.APPDATA?.trim();
-    if (appData) {
-      return path2.join(appData, "..", "Local", "akm");
-    }
-  } else {
-    const xdgCacheHome = env.XDG_CACHE_HOME?.trim();
-    if (xdgCacheHome)
-      return path2.join(xdgCacheHome, "akm");
-  }
-  const stashOverride = env.AKM_STASH_DIR?.trim();
-  if (stashOverride && isTransientStashPath(stashOverride)) {
-    return path2.join(stashOverride, ".akm", "cache");
-  }
-  if (IS_WINDOWS) {
-    throw new ConfigError("Unable to determine cache directory. Set LOCALAPPDATA, USERPROFILE, or APPDATA.", "CONFIG_DIR_UNRESOLVABLE");
-  }
-  const home = env.HOME?.trim();
-  if (!home)
-    return path2.join("/tmp", "akm-cache");
-  return path2.join(home, ".cache", "akm");
-}
 function getDataDir(env = process.env, platform = process.platform) {
   const override = env.AKM_DATA_DIR?.trim();
   if (override)
@@ -7803,129 +7764,47 @@ function getDataDir(env = process.env, platform = process.platform) {
 function getMaintenanceBarrierPath() {
   return path2.join(getDataDir(), "maintenance.barrier.lock");
 }
-function getWorkflowDbPath() {
-  return path2.join(getDataDir(), "workflow.db");
-}
-function getStateDbPathInDataDir() {
-  return path2.join(getDataDir(), "state.db");
-}
 var init_paths = __esm(() => {
   init_common();
   init_errors();
 });
 
-// src/core/config/config-io.ts
+// src/core/migration-operation.ts
+import crypto2 from "node:crypto";
 import fs4 from "node:fs";
 import path3 from "node:path";
-function parseConfigText(text, sourcePath) {
-  const stripped = stripJsonComments(text);
-  const where = sourcePath ? ` at ${sourcePath}` : "";
-  let parsed;
-  try {
-    parsed = JSON.parse(stripped);
-  } catch (err) {
-    const detail = err instanceof Error ? err.message : String(err);
-    throw new ConfigError(`Failed to parse config JSON${where}: ${detail}`, "INVALID_CONFIG_FILE", "Edit the file to fix the JSON syntax error. Comments (// and /* */) are allowed; trailing commas are not.");
-  }
-  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
-    throw new ConfigError(`Config file${where} must contain a JSON object at the root, got ${describeJsonRoot(parsed)}.`, "INVALID_CONFIG_FILE");
-  }
-  return parsed;
+function installationId() {
+  return crypto2.createHash("sha256").update(path3.resolve(path3.dirname(getConfigPath()))).update("\x00").update(path3.resolve(getDataDir())).digest("hex").slice(0, 24);
 }
-function describeJsonRoot(value) {
-  if (value === null)
-    return "null";
-  if (Array.isArray(value))
-    return "an array";
-  if (typeof value === "string")
-    return "a string";
-  if (typeof value === "number")
-    return "a number";
-  if (typeof value === "boolean")
-    return "a boolean";
-  return typeof value;
+function getMigrationOperationRoot() {
+  return path3.join(getDataDir(), "backups", "migrations", installationId());
 }
-function getConfigLockPath() {
-  return path3.join(getConfigDir(), "config.json.lck");
+function getMigrationRestoreJournalPath() {
+  return path3.join(getMigrationOperationRoot(), "restore-active.json");
 }
-function sleepSyncMs(ms) {
-  sleepSync(ms);
+function getMigrationApplyJournalPath() {
+  return path3.join(getMigrationOperationRoot(), "apply-active.json");
 }
-function acquireConfigLock() {
-  const lockPath = getConfigLockPath();
-  try {
-    fs4.mkdirSync(path3.dirname(lockPath), { recursive: true });
-  } catch {}
-  for (let attempt = 0;attempt < CONFIG_LOCK_MAX_RETRIES; attempt++) {
-    try {
-      const ownership = tryAcquireLockSync(lockPath, createLockPayload());
-      if (ownership) {
-        return () => releaseLock(ownership);
-      }
-    } catch (error) {
-      throw new ConfigError(`Unable to acquire config lock at ${lockPath}: ${error instanceof Error ? error.message : String(error)}`, "INVALID_CONFIG_FILE");
-    }
-    const probe = probeLock(lockPath);
-    if (probe.state === "stale" && reclaimStaleLock(lockPath, probe)) {
-      continue;
-    }
-    if (attempt < CONFIG_LOCK_MAX_RETRIES - 1) {
-      sleepSyncMs(CONFIG_LOCK_RETRY_DELAY_MS);
-    }
-  }
-  throw new ConfigError(`Timed out waiting for config lock at ${lockPath}. Another AKM process may be updating config.`, "INVALID_CONFIG_FILE");
-}
-function withConfigLock(fn) {
-  const release = acquireConfigLock();
-  try {
-    return fn();
-  } finally {
-    release();
-  }
-}
-function stripJsonComments(text) {
-  let result = "";
-  let i = 0;
-  let inString = false;
-  while (i < text.length) {
-    if (inString) {
-      if (text[i] === "\\") {
-        result += text[i] + (text[i + 1] ?? "");
-        i += 2;
-        continue;
-      }
-      if (text[i] === '"') {
-        inString = false;
-      }
-      result += text[i];
-      i++;
-      continue;
-    }
-    if (text[i] === '"') {
-      inString = true;
-      result += text[i];
-      i++;
-      continue;
-    }
-    if (text[i] === "/" && text[i + 1] === "/") {
-      while (i < text.length && text[i] !== `
-`)
-        i++;
-      continue;
-    }
-    if (text[i] === "/" && text[i + 1] === "*") {
-      i += 2;
-      while (i < text.length && !(text[i] === "*" && text[i + 1] === "/"))
-        i++;
-      i += 2;
-      continue;
+function assertNoPendingMigrationOperation() {
+  for (const [kind, journalPath] of [
+    ["restore", getMigrationRestoreJournalPath()],
+    ["migration apply", getMigrationApplyJournalPath()]
+  ]) {
+    if (fs4.existsSync(journalPath)) {
+      throw new ConfigError(`AKM ${kind} recovery is pending at ${journalPath}; refusing canonical config/database access until recovery completes.`, "INVALID_CONFIG_FILE");
     }
-    result += text[i];
-    i++;
   }
-  return result;
+  const hook = afterPendingCheckHook;
+  afterPendingCheckHook = undefined;
+  hook?.();
 }
-var CONFIG_LOCK_MAX_RETRIES = 10, CONFIG_LOCK_RETRY_DELAY_MS = 50;
+var afterPendingCheckHook;
+var init_migration_operation = __esm(() => {
+  init_errors();
+  init_paths();
+});
+
+// src/core/config/config-io.ts
 var init_config_io = __esm(() => {
   init_runtime();
   init_common();
@@ -14282,6 +14161,15 @@ var init_config_schema = __esm(() => {
         message: "feedbackDistillation was removed in 0.8.0 — use processes.distill.enabled instead. " + "It now controls both the orchestration gate and the LLM-call gate."
       });
     }
+    for (const [name, process2] of Object.entries(val)) {
+      if (!(name in IMPROVE_PROCESS_ENGINE_CAPABILITIES) && process2 !== null && typeof process2 === "object" && process2.enabled === true) {
+        ctx.addIssue({
+          code: exports_external.ZodIssueCode.custom,
+          path: [name],
+          message: `Unknown enabled improve process "${name}"`
+        });
+      }
+    }
   });
   ImproveProfileConfigSchema = exports_external.object({
     engine: engineName.optional(),
@@ -14713,263 +14601,6 @@ var init_config_schema = __esm(() => {
   });
 });
 
-// src/core/migration-backup.ts
-import crypto from "node:crypto";
-import fs7 from "node:fs";
-import path6 from "node:path";
-function getMigrationBackupDir() {
-  return path6.join(getCacheDir(), "migration-backups", MIGRATION_BACKUP_VERSION);
-}
-function migrationBackupLockPath() {
-  return path6.join(getCacheDir(), "migration-backups", `${MIGRATION_BACKUP_VERSION}.lock`);
-}
-function expectedSourcePaths() {
-  return {
-    "config.json": getConfigPath(),
-    "state.db": getStateDbPathInDataDir(),
-    "workflow.db": getWorkflowDbPath()
-  };
-}
-function sha256File(filePath) {
-  return crypto.createHash("sha256").update(fs7.readFileSync(filePath)).digest("hex");
-}
-function ownerOnlyMode(filePath, directory) {
-  if (process.platform === "win32")
-    return true;
-  const mode = fs7.statSync(filePath).mode & 511;
-  return mode === (directory ? 448 : 384);
-}
-function fsyncDirectory(directory) {
-  try {
-    const fd = fs7.openSync(directory, "r");
-    try {
-      fs7.fsyncSync(fd);
-    } finally {
-      fs7.closeSync(fd);
-    }
-  } catch (error) {
-    const code = error.code;
-    if (code !== "EINVAL" && code !== "ENOTSUP" && code !== "EISDIR" && code !== "EPERM")
-      throw error;
-  }
-}
-function parseManifest(bundlePath) {
-  const manifestPath = path6.join(bundlePath, "manifest.json");
-  let value;
-  try {
-    value = JSON.parse(fs7.readFileSync(manifestPath, "utf8"));
-  } catch (error) {
-    throw new ConfigError(`Migration backup at ${bundlePath} is incomplete or unreadable: ${error instanceof Error ? error.message : String(error)}. Remove it only after preserving any recoverable files, then retry backup creation.`, "INVALID_CONFIG_FILE");
-  }
-  if (!value || typeof value !== "object" || Array.isArray(value)) {
-    throw new ConfigError(`Migration backup manifest at ${manifestPath} is invalid.`, "INVALID_CONFIG_FILE");
-  }
-  const manifest = value;
-  if (manifest.version !== MIGRATION_BACKUP_VERSION || typeof manifest.createdAt !== "string") {
-    throw new ConfigError(`Migration backup manifest at ${manifestPath} has an unsupported version.`, "INVALID_CONFIG_FILE");
-  }
-  const expected = expectedSourcePaths();
-  for (const name of ARTIFACT_NAMES) {
-    const artifact = manifest.artifacts?.[name];
-    if (!artifact || artifact.sourcePath !== expected[name] || typeof artifact.present !== "boolean" || !Number.isSafeInteger(artifact.byteSize) || artifact.byteSize < 0 || typeof artifact.createdAt !== "string" || (artifact.present ? typeof artifact.sha256 !== "string" || artifact.sha256.length !== 64 : artifact.sha256 !== null)) {
-      throw new ConfigError(`Migration backup manifest has an invalid ${name} entry.`, "INVALID_CONFIG_FILE");
-    }
-  }
-  return manifest;
-}
-function verifyMigrationBackup(bundlePath = getMigrationBackupDir()) {
-  if (!fs7.existsSync(bundlePath) || !fs7.statSync(bundlePath).isDirectory()) {
-    throw new ConfigError(`Migration backup does not exist at ${bundlePath}.`, "INVALID_CONFIG_FILE");
-  }
-  if (!ownerOnlyMode(bundlePath, true)) {
-    throw new ConfigError(`Migration backup directory ${bundlePath} must have mode 0700.`, "INVALID_CONFIG_FILE");
-  }
-  const manifest = parseManifest(bundlePath);
-  const expectedFiles = new Set(["manifest.json"]);
-  for (const name of ARTIFACT_NAMES) {
-    const artifact = manifest.artifacts[name];
-    const artifactPath = path6.join(bundlePath, name);
-    if (!artifact.present) {
-      if (fs7.existsSync(artifactPath)) {
-        throw new ConfigError(`Migration backup contains ${name}, but its manifest records it absent.`, "INVALID_CONFIG_FILE");
-      }
-      continue;
-    }
-    expectedFiles.add(name);
-    if (!fs7.existsSync(artifactPath) || !fs7.statSync(artifactPath).isFile()) {
-      throw new ConfigError(`Migration backup is missing ${artifactPath}.`, "INVALID_CONFIG_FILE");
-    }
-    if (!ownerOnlyMode(artifactPath, false)) {
-      throw new ConfigError(`Migration backup artifact ${artifactPath} must have mode 0600.`, "INVALID_CONFIG_FILE");
-    }
-    const stat = fs7.statSync(artifactPath);
-    if (stat.size !== artifact.byteSize || sha256File(artifactPath) !== artifact.sha256) {
-      throw new ConfigError(`Migration backup artifact ${artifactPath} failed checksum verification.`, "INVALID_CONFIG_FILE");
-    }
-  }
-  if (!ownerOnlyMode(path6.join(bundlePath, "manifest.json"), false)) {
-    throw new ConfigError(`Migration backup manifest must have mode 0600.`, "INVALID_CONFIG_FILE");
-  }
-  const extras = fs7.readdirSync(bundlePath).filter((name) => !expectedFiles.has(name));
-  if (extras.length > 0) {
-    throw new ConfigError(`Migration backup contains unexpected files: ${extras.join(", ")}.`, "INVALID_CONFIG_FILE");
-  }
-  return manifest;
-}
-function acquireMigrationBackupLock() {
-  const lockPath = migrationBackupLockPath();
-  fs7.mkdirSync(path6.dirname(lockPath), { recursive: true, mode: 448 });
-  fs7.chmodSync(path6.dirname(lockPath), 448);
-  for (let attempt = 0;attempt < 50; attempt += 1) {
-    const ownership = tryAcquireLockSync(lockPath, createLockPayload());
-    if (ownership)
-      return () => releaseLock(ownership);
-    const probe = probeLock(lockPath);
-    if (probe.state === "stale" && reclaimStaleLock(lockPath, probe)) {
-      continue;
-    }
-    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 50);
-  }
-  throw new ConfigError(`Timed out waiting for migration backup lock at ${lockPath}.`, "INVALID_CONFIG_FILE");
-}
-function assertNotAlreadyCutOver() {
-  const configPath = getConfigPath();
-  let text;
-  try {
-    text = fs7.readFileSync(configPath, "utf8");
-  } catch (error) {
-    if (error.code === "ENOENT")
-      return;
-    throw error;
-  }
-  const raw = parseConfigText(text, configPath);
-  if (raw.configVersion === CURRENT_CONFIG_VERSION) {
-    throw new ConfigError(`Refusing to create a pre-0.9 migration backup from an existing ${CURRENT_CONFIG_VERSION} config at ${configPath}. Restore the original migration bundle or pre-cutover config before retrying.`, "INVALID_CONFIG_FILE");
-  }
-}
-function copyRegularArtifact(source, destination) {
-  const stat = fs7.statSync(source);
-  if (!stat.isFile())
-    throw new ConfigError(`Backup source is not a regular file: ${source}`, "INVALID_CONFIG_FILE");
-  writeFileAtomic(destination, fs7.readFileSync(source), 384);
-  fs7.chmodSync(destination, 384);
-}
-function sqliteQuote(value) {
-  return `'${value.replaceAll("'", "''")}'`;
-}
-function backupSqlite(source, destination) {
-  const stat = fs7.statSync(source);
-  if (!stat.isFile())
-    throw new ConfigError(`SQLite backup source is not a regular file: ${source}`, "INVALID_CONFIG_FILE");
-  const resolvedSource = path6.resolve(source);
-  const activityName = resolvedSource === path6.resolve(getWorkflowDbPath()) ? "workflow-db" : resolvedSource === path6.resolve(getStateDbPathInDataDir()) ? "state-db" : undefined;
-  const releaseActivity = activityName ? acquireMaintenanceActivitySync(activityName) : undefined;
-  let db;
-  try {
-    db = openDatabase(source);
-    db.exec("PRAGMA busy_timeout = 10000");
-    db.exec("PRAGMA wal_checkpoint(FULL)");
-    db.exec(`VACUUM INTO ${sqliteQuote(destination)}`);
-  } finally {
-    try {
-      db?.close();
-    } finally {
-      releaseActivity?.();
-    }
-  }
-  fs7.chmodSync(destination, 384);
-  const fd = fs7.openSync(destination, "r");
-  try {
-    fs7.fsyncSync(fd);
-  } finally {
-    fs7.closeSync(fd);
-  }
-}
-function createMigrationBackupUnlocked() {
-  const bundlePath = getMigrationBackupDir();
-  if (fs7.existsSync(bundlePath)) {
-    return { path: bundlePath, created: false, manifest: verifyMigrationBackup(bundlePath) };
-  }
-  assertNotAlreadyCutOver();
-  const parent = path6.dirname(bundlePath);
-  fs7.mkdirSync(parent, { recursive: true, mode: 448 });
-  fs7.chmodSync(parent, 448);
-  const temporary = path6.join(parent, `.0.9.0.tmp.${process.pid}.${crypto.randomBytes(8).toString("hex")}`);
-  fs7.mkdirSync(temporary, { mode: 448 });
-  const createdAt = new Date().toISOString();
-  const sources = expectedSourcePaths();
-  const artifacts = {};
-  try {
-    for (const name of ARTIFACT_NAMES) {
-      const sourcePath = sources[name];
-      const destination = path6.join(temporary, name);
-      let present = true;
-      try {
-        fs7.statSync(sourcePath);
-      } catch (error) {
-        if (error.code === "ENOENT")
-          present = false;
-        else
-          throw error;
-      }
-      if (present) {
-        if (name === "config.json")
-          copyRegularArtifact(sourcePath, destination);
-        else
-          backupSqlite(sourcePath, destination);
-      }
-      const byteSize = present ? fs7.statSync(destination).size : 0;
-      artifacts[name] = {
-        sourcePath,
-        present,
-        byteSize,
-        sha256: present ? sha256File(destination) : null,
-        createdAt
-      };
-    }
-    const manifest = { version: MIGRATION_BACKUP_VERSION, createdAt, artifacts };
-    writeFileAtomic(path6.join(temporary, "manifest.json"), `${JSON.stringify(manifest, null, 2)}
-`, 384);
-    fs7.chmodSync(path6.join(temporary, "manifest.json"), 384);
-    fsyncDirectory(temporary);
-    fs7.renameSync(temporary, bundlePath);
-    fsyncDirectory(parent);
-    return { path: bundlePath, created: true, manifest: verifyMigrationBackup(bundlePath) };
-  } catch (error) {
-    fs7.rmSync(temporary, { recursive: true, force: true });
-    if (fs7.existsSync(bundlePath)) {
-      throw new ConfigError(`Migration backup creation raced with another writer and left ${bundlePath}. Verify or preserve it before retrying.`, "INVALID_CONFIG_FILE");
-    }
-    throw error;
-  }
-}
-function withMigrationBackupLock(fn) {
-  const release = acquireMigrationBackupLock();
-  try {
-    return fn();
-  } finally {
-    release();
-  }
-}
-function createMigrationBackup() {
-  return withConfigLock(() => withMigrationBackupLock(createMigrationBackupUnlocked));
-}
-function ensureMigrationBackup() {
-  return createMigrationBackup();
-}
-var MIGRATION_BACKUP_VERSION = "0.9.0", ARTIFACT_NAMES;
-var init_migration_backup = __esm(() => {
-  init_database();
-  init_common();
-  init_config_io();
-  init_config_schema();
-  init_errors();
-  init_file_lock();
-  init_maintenance_barrier();
-  init_paths();
-  ARTIFACT_NAMES = ["config.json", "state.db", "workflow.db"];
-});
-
 // src/core/config/deep-merge.ts
 var UNSAFE_KEYS;
 var init_deep_merge = __esm(() => {
@@ -15150,11 +14781,11 @@ var init_engine_resolution = __esm(() => {
 var init_config_sources = () => {};
 
 // src/core/config/config.ts
-import path7 from "node:path";
+import path6 from "node:path";
 var PROJECT_CONFIG_RELATIVE_PATH, INDEX_RESERVED_KEYS, PROJECT_CONFIG_DEPRECATION_WARNED;
 var init_config = __esm(() => {
   init_errors();
-  init_migration_backup();
+  init_migration_operation();
   init_config_io();
   init_config_schema();
   init_deep_merge();
@@ -15165,7 +14796,7 @@ var init_config = __esm(() => {
   init_config_types();
   init_config_schema();
   init_config_sources();
-  PROJECT_CONFIG_RELATIVE_PATH = path7.join(".akm", "config.json");
+  PROJECT_CONFIG_RELATIVE_PATH = path6.join(".akm", "config.json");
   INDEX_RESERVED_KEYS = new Set(["metadataEnhance", "stalenessDetection", "indexBodyOpening"]);
   PROJECT_CONFIG_DEPRECATION_WARNED = new Set;
 });
@@ -15188,11 +14819,11 @@ var init_metadata_contributors = __esm(() => {
 });
 
 // src/indexer/passes/metadata.ts
-import fs8 from "node:fs";
+import fs7 from "node:fs";
 function extractDescriptionFromComments(filePath) {
   let content;
   try {
-    content = fs8.readFileSync(filePath, "utf8");
+    content = fs7.readFileSync(filePath, "utf8");
   } catch {
     return null;
   }
@@ -15242,9 +14873,76 @@ var init_metadata = __esm(() => {
 });
 
 // src/core/asset/asset-ref.ts
+import path7 from "node:path";
+function makeAssetRef(type, name, origin) {
+  validateName(name);
+  const normalized = normalizeName(name);
+  const asset = `${type}:${normalized}`;
+  if (!origin)
+    return asset;
+  return `${origin}//${asset}`;
+}
+function refToString(ref) {
+  return makeAssetRef(ref.type, ref.name, ref.origin);
+}
+function parseAssetRef(ref) {
+  const trimmed = ref.trim();
+  if (!trimmed)
+    throw new UsageError("Empty ref.", "MISSING_REQUIRED_ARGUMENT");
+  let origin;
+  let body = trimmed;
+  const boundary = trimmed.indexOf("//");
+  if (boundary >= 0) {
+    origin = trimmed.slice(0, boundary);
+    body = trimmed.slice(boundary + 2);
+    if (!origin)
+      throw new UsageError("Empty origin in ref.", "MISSING_REQUIRED_ARGUMENT");
+  }
+  const colon = body.indexOf(":");
+  if (colon <= 0) {
+    throw new UsageError(`Invalid ref "${trimmed}". Expected [origin//]type:name, e.g. skill:deploy or knowledge:guide.md`, "MISSING_REQUIRED_ARGUMENT");
+  }
+  const rawType = body.slice(0, colon);
+  const rawName = body.slice(colon + 1);
+  if (rawType === "vault") {
+    throw new UsageError("The `vault` asset type was removed in 0.9.0 — use `env:` (whole .env config) or `secret:` (a single value).", "MISSING_REQUIRED_ARGUMENT");
+  }
+  const resolvedType = TYPE_ALIASES[rawType] ?? rawType;
+  if (!isAssetType(resolvedType)) {
+    throw new UsageError(`Invalid asset type: "${rawType}".`, "MISSING_REQUIRED_ARGUMENT");
+  }
+  validateName(rawName);
+  const name = normalizeName(rawName);
+  return { type: resolvedType, name, origin: origin || undefined };
+}
+function validateName(name) {
+  if (!name)
+    throw new UsageError("Empty asset name.", "MISSING_REQUIRED_ARGUMENT");
+  if (name.includes("\x00"))
+    throw new UsageError("Null byte in asset name.", "MISSING_REQUIRED_ARGUMENT");
+  if (/^[A-Za-z]:/.test(name))
+    throw new UsageError("Windows drive path in asset name.", "MISSING_REQUIRED_ARGUMENT");
+  const normalized = path7.posix.normalize(name.replace(/\\/g, "/"));
+  if (path7.posix.isAbsolute(normalized))
+    throw new UsageError("Absolute path in asset name.", "MISSING_REQUIRED_ARGUMENT");
+  if (normalized === ".." || normalized.startsWith("../")) {
+    throw new UsageError("Path traversal in asset name.", "MISSING_REQUIRED_ARGUMENT");
+  }
+  const segments = normalized.split("/");
+  if (segments.some((seg) => seg === "." || seg === "..")) {
+    throw new UsageError("Asset name cannot contain relative path segments.", "MISSING_REQUIRED_ARGUMENT");
+  }
+}
+function normalizeName(name) {
+  return path7.posix.normalize(name.replace(/\\/g, "/"));
+}
+var TYPE_ALIASES;
 var init_asset_ref = __esm(() => {
   init_common();
   init_errors();
+  TYPE_ALIASES = {
+    environment: "env"
+  };
 });
 
 // src/workflows/resource-limits.ts
@@ -15269,10 +14967,30 @@ var WORKFLOW_SCHEMA_VERSION = 1;
 // src/workflows/validator.ts
 function runSemanticChecks(draft, frontmatterData, frontmatterEndLine, errors3) {
   checkFrontmatterKeys(frontmatterData, frontmatterEndLine, errors3);
+  checkXrefs(frontmatterData.xrefs, frontmatterEndLine, errors3);
   checkStepIdFormat(draft, errors3);
   checkDuplicateStepIds(draft, errors3);
   checkResourceLimits(draft, errors3);
 }
+function checkXrefs(value, line, errors3) {
+  if (value === undefined)
+    return;
+  if (!Array.isArray(value)) {
+    errors3.push({ line, message: 'Workflow frontmatter "xrefs" must be an array of canonical asset refs.' });
+    return;
+  }
+  for (const ref of value) {
+    try {
+      if (typeof ref !== "string" || refToString(parseAssetRef(ref)) !== ref)
+        throw new Error("non-canonical ref");
+    } catch {
+      errors3.push({
+        line,
+        message: `Workflow frontmatter "xrefs" contains an invalid or non-canonical ref: ${String(ref)}.`
+      });
+    }
+  }
+}
 function checkResourceLimits(draft, errors3) {
   if (draft.steps.length > WORKFLOW_MAX_STEPS) {
     errors3.push({ line: 1, message: `Workflow must contain at most ${WORKFLOW_MAX_STEPS} steps.` });
@@ -15295,7 +15013,7 @@ function checkFrontmatterKeys(data, fmEndLine, errors3) {
       continue;
     errors3.push({
       line: fmEndLine,
-      message: `Workflow frontmatter "${key}" is not supported. Use only: description, tags, params, name, updated, when_to_use.`
+      message: `Workflow frontmatter "${key}" is not supported. Use only: description, tags, params, name, updated, when_to_use, xrefs.`
     });
   }
 }
@@ -15325,9 +15043,10 @@ function checkDuplicateStepIds(draft, errors3) {
 }
 var STEP_ID_REGEX, ALLOWED_FRONTMATTER_KEYS;
 var init_validator = __esm(() => {
+  init_asset_ref();
   init_resource_limits();
   STEP_ID_REGEX = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
-  ALLOWED_FRONTMATTER_KEYS = new Set(["description", "tags", "params", "name", "updated", "when_to_use"]);
+  ALLOWED_FRONTMATTER_KEYS = new Set(["description", "tags", "params", "name", "updated", "when_to_use", "xrefs"]);
 });
 
 // src/workflows/parser.ts
@@ -16778,7 +16497,7 @@ var init_asset_registry = __esm(() => {
 });
 
 // src/core/asset/asset-spec.ts
-import fs9 from "node:fs";
+import fs8 from "node:fs";
 import path8 from "node:path";
 function toPosix2(input) {
   return input.replace(/\\/g, "/");
@@ -16809,7 +16528,7 @@ var init_asset_spec = __esm(() => {
       }
       for (const ext of WORKFLOW_EXTENSIONS) {
         const candidate = path8.join(typeRoot, `${name}${ext}`);
-        if (fs9.existsSync(candidate))
+        if (fs8.existsSync(candidate))
           return candidate;
       }
       return path8.join(typeRoot, `${name}.md`);
@@ -16944,29 +16663,29 @@ var init_asset_spec = __esm(() => {
 });
 
 // src/core/common.ts
-import crypto2 from "node:crypto";
-import fs10 from "node:fs";
-import path9 from "node:path";
-function writeFileAtomic(target, content, mode) {
-  const tmp = `${target}.tmp.${process.pid}.${crypto2.randomBytes(8).toString("hex")}`;
-  const fd = fs10.openSync(tmp, "w", mode ?? 384);
-  try {
-    fs10.writeSync(fd, typeof content === "string" ? Buffer.from(content) : content);
-    try {
-      fs10.fdatasyncSync(fd);
-    } catch {}
-  } finally {
-    fs10.closeSync(fd);
+import fs9 from "node:fs";
+function isAssetType(type) {
+  return Object.hasOwn(TYPE_DIRS, type);
+}
+function readTextFileDescriptorWithLimit(fd, maxBytes, label = "File", displayPath = "(open file)") {
+  const stat = fs9.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 = fs9.readSync(fd, buffer, total, maxBytes + 1 - total, null);
+    if (bytesRead === 0)
+      break;
+    total += bytesRead;
   }
-  fs10.renameSync(tmp, target);
-  try {
-    const dirFd = fs10.openSync(path9.dirname(target), "r");
-    try {
-      fs10.fsyncSync(dirFd);
-    } finally {
-      fs10.closeSync(dirFd);
-    }
-  } catch {}
+  if (total > maxBytes) {
+    throw new ConfigError(`${label} exceeds the ${maxBytes}-byte limit: ${displayPath}.`, "INVALID_CONFIG_FILE");
+  }
+  return buffer.subarray(0, total).toString("utf8");
 }
 function asNonEmptyString3(value) {
   if (typeof value !== "string")
@@ -16982,7 +16701,7 @@ function isProcessAlive(pid) {
     return false;
   }
 }
-var ASSET_TYPES, ASSET_TYPE_SET, IS_WINDOWS, DEFAULT_RESPONSE_BYTE_CAP;
+var ASSET_TYPES, ASSET_TYPE_SET, IS_WINDOWS, MAX_CONFIG_FILE_BYTES, MAX_LOCAL_METADATA_BYTES, MAX_LOCK_METADATA_BYTES, DEFAULT_RESPONSE_BYTE_CAP;
 var init_common = __esm(() => {
   init_asset_spec();
   init_errors();
@@ -16990,38 +16709,41 @@ var init_common = __esm(() => {
   ASSET_TYPES = Object.freeze([...getAssetTypes()]);
   ASSET_TYPE_SET = new Set(ASSET_TYPES);
   IS_WINDOWS = process.platform === "win32";
+  MAX_CONFIG_FILE_BYTES = 1024 * 1024;
+  MAX_LOCAL_METADATA_BYTES = 1024 * 1024;
+  MAX_LOCK_METADATA_BYTES = 64 * 1024;
   DEFAULT_RESPONSE_BYTE_CAP = 10 * 1024 * 1024;
 });
 
 // src/core/file-lock.ts
 import { randomUUID } from "node:crypto";
-import fs11 from "node:fs";
-import path10 from "node:path";
+import fs10 from "node:fs";
+import path9 from "node:path";
 function readLockSnapshot(lockPath) {
   let fd;
   try {
-    fd = fs11.openSync(lockPath, "r");
+    fd = fs10.openSync(lockPath, "r");
   } catch (err) {
     if (err.code === "ENOENT")
       return;
     throw err;
   }
   try {
-    const rawContent = fs11.readFileSync(fd, "utf8");
-    const stat = fs11.fstatSync(fd);
+    const rawContent = readTextFileDescriptorWithLimit(fd, MAX_LOCK_METADATA_BYTES, "Lock metadata", lockPath);
+    const stat = fs10.fstatSync(fd);
     return {
       rawContent,
       identity: { dev: stat.dev, ino: stat.ino, size: stat.size, mtimeMs: stat.mtimeMs }
     };
   } finally {
-    fs11.closeSync(fd);
+    fs10.closeSync(fd);
   }
 }
 function sameIdentity(left, right) {
   return left.dev === right.dev && left.ino === right.ino && left.size === right.size && left.mtimeMs === right.mtimeMs;
 }
 function operationMutexPath(lockPath) {
-  return path10.join(path10.dirname(lockPath), `.${path10.basename(lockPath)}.operations.sensitive`);
+  return path9.join(path9.dirname(lockPath), `.${path9.basename(lockPath)}.operations.sensitive`);
 }
 function withLockOperationMutex(lockPath, run) {
   const db = openDatabase(operationMutexPath(lockPath));
@@ -17053,7 +16775,7 @@ function withLockOperationMutex(lockPath, run) {
 }
 function tryAcquireLockRaw(lockPath, payload) {
   try {
-    fs11.writeFileSync(lockPath, payload, { flag: "wx" });
+    fs10.writeFileSync(lockPath, payload, { flag: "wx" });
   } catch (err) {
     if (err.code === "EEXIST")
       return;
@@ -17074,7 +16796,7 @@ function tryAcquireLockRaw(lockPath, payload) {
 }
 function releaseLockRaw(lockPath) {
   try {
-    fs11.unlinkSync(lockPath);
+    fs10.unlinkSync(lockPath);
   } catch {}
 }
 function tryAcquireLockSync(lockPath, payload) {
@@ -17123,7 +16845,7 @@ function reclaimStaleLock(lockPath, probe, options) {
     }
     const quarantinePath = `${lockPath}.stale-${process.pid}-${randomUUID()}`;
     try {
-      fs11.renameSync(lockPath, quarantinePath);
+      fs10.renameSync(lockPath, quarantinePath);
     } catch (err) {
       if (err.code === "ENOENT")
         return false;
@@ -17137,7 +16859,7 @@ function reclaimStaleLock(lockPath, probe, options) {
     }
     if (!quarantined || quarantined.rawContent !== expectedContent || !sameIdentity(quarantined.identity, expectedIdentity)) {
       try {
-        fs11.linkSync(quarantinePath, lockPath);
+        fs10.linkSync(quarantinePath, lockPath);
       } catch (err) {
         if (err.code !== "EEXIST")
           throw err;
@@ -17147,7 +16869,7 @@ function reclaimStaleLock(lockPath, probe, options) {
     }
     options?.afterQuarantineVerified?.();
     try {
-      fs11.unlinkSync(quarantinePath);
+      fs10.unlinkSync(quarantinePath);
       return true;
     } catch (err) {
       if (err.code === "ENOENT")
@@ -17158,7 +16880,7 @@ function reclaimStaleLock(lockPath, probe, options) {
 }
 function releaseLock(ownership) {
   const { lockPath } = ownership;
-  if (!fs11.existsSync(lockPath) && !fs11.existsSync(operationMutexPath(lockPath)))
+  if (!fs10.existsSync(lockPath) && !fs10.existsSync(operationMutexPath(lockPath)))
     return;
   withLockOperationMutex(lockPath, () => {
     let current;
@@ -17193,73 +16915,9 @@ var init_file_lock = __esm(() => {
   init_common();
 });
 
-// src/core/maintenance-barrier.ts
-import { AsyncLocalStorage } from "node:async_hooks";
-import { randomUUID as randomUUID2 } from "node:crypto";
-import fs12 from "node:fs";
-import path11 from "node:path";
-function tryAcquireMaintenanceBarrier() {
-  const lockPath = getMaintenanceBarrierPath();
-  fs12.mkdirSync(path11.dirname(lockPath), { recursive: true });
-  for (let attempt = 0;attempt < 2; attempt += 1) {
-    const ownership = tryAcquireLockSync(lockPath, createLockPayload({ purpose: "maintenance-start" }));
-    if (ownership) {
-      return () => releaseLock(ownership);
-    }
-    const probe = probeLock(lockPath);
-    if (probe.state !== "stale" || !reclaimStaleLock(lockPath, probe))
-      return;
-  }
-  return;
-}
-function acquireMaintenanceBarrier() {
-  const release = tryAcquireMaintenanceBarrier();
-  if (release)
-    return release;
-  throw new ConfigError(`AKM maintenance is in progress (barrier ${getMaintenanceBarrierPath()}); retry after it completes.`, "INVALID_CONFIG_FILE");
-}
-function withMaintenanceStartBarrierSyncWait(run) {
-  if (heldBarrierContext.getStore()?.active)
-    return run();
-  const deadline = Date.now() + 5000;
-  let release = tryAcquireMaintenanceBarrier();
-  while (!release && Date.now() < deadline) {
-    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 5);
-    release = tryAcquireMaintenanceBarrier();
-  }
-  if (!release)
-    release = acquireMaintenanceBarrier();
-  const ownership = { active: true };
-  try {
-    return heldBarrierContext.run(ownership, run);
-  } finally {
-    ownership.active = false;
-    release();
-  }
-}
-function acquireMaintenanceActivitySync(name) {
-  return withMaintenanceStartBarrierSyncWait(() => {
-    const directory = path11.join(path11.dirname(getMaintenanceBarrierPath()), "maintenance-activities");
-    fs12.mkdirSync(directory, { recursive: true, mode: 448 });
-    const lockPath = path11.join(directory, `${name}-${process.pid}-${randomUUID2()}.lock`);
-    const ownership = tryAcquireLockSync(lockPath, createLockPayload({ purpose: name }));
-    if (!ownership) {
-      throw new ConfigError(`Could not register AKM maintenance activity at ${lockPath}.`, "INVALID_CONFIG_FILE");
-    }
-    return () => releaseLock(ownership);
-  });
-}
-var heldBarrierContext;
-var init_maintenance_barrier = __esm(() => {
-  init_errors();
-  init_file_lock();
-  init_paths();
-  heldBarrierContext = new AsyncLocalStorage;
-});
-
 // scripts/migrations/import-fs-improve-runs-to-db.ts
-import fs14 from "fs";
-import path13 from "path";
+import fs13 from "fs";
+import path12 from "path";
 
 // src/core/improve-result.ts
 var COMMON_FIELDS = [
@@ -17437,8 +17095,143 @@ function decodeImproveResult(input) {
 }
 
 // src/core/state-db.ts
-import fs13 from "node:fs";
-import path12 from "node:path";
+init_database();
+import fs12 from "node:fs";
+import path11 from "node:path";
+
+// src/storage/engines/sqlite-migrations.ts
+import crypto from "node:crypto";
+function migrationChecksum(migration) {
+  return crypto.createHash("sha256").update(migration.id).update("\x00").update(migration.up).digest("hex");
+}
+function migrationsTableExists(db) {
+  return !!db.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'schema_migrations'").get();
+}
+function ledgerHasChecksum(db) {
+  return db.prepare("PRAGMA table_info(schema_migrations)").all().some((column) => column.name === "checksum");
+}
+function inspectMigrationLedger(db, migrations) {
+  const registryIds = migrations.map((migration) => migration.id);
+  if (new Set(registryIds).size !== registryIds.length) {
+    return {
+      status: "inconsistent",
+      migrationIds: [],
+      checksums: [],
+      detail: "migration registry contains duplicate IDs"
+    };
+  }
+  if (!migrationsTableExists(db))
+    return { status: registryIds.length === 0 ? "current" : "old", migrationIds: [], checksums: [] };
+  const hasChecksum = ledgerHasChecksum(db);
+  const rows = db.prepare(`SELECT id${hasChecksum ? ", checksum" : ""} FROM schema_migrations ORDER BY rowid`).all();
+  const migrationIds = rows.map((row) => row.id);
+  const checksums = rows.map((row) => row.checksum ?? null);
+  for (let index = 0;index < rows.length; index += 1) {
+    const expected = migrations[index];
+    const row = rows[index];
+    if (!expected) {
+      return { status: "newer", migrationIds, checksums, detail: `unknown migration ID ${row.id}` };
+    }
+    if (row.id !== expected.id) {
+      const knownLater = registryIds.includes(row.id);
+      return {
+        status: knownLater ? "inconsistent" : "newer",
+        migrationIds,
+        checksums,
+        detail: knownLater ? `migration ledger is not an exact ordered prefix at position ${index + 1}` : `unknown migration ID ${row.id}`
+      };
+    }
+    const expectedChecksum = migrationChecksum(expected);
+    if (row.checksum && row.checksum !== expectedChecksum) {
+      return {
+        status: "inconsistent",
+        migrationIds,
+        checksums,
+        detail: `migration ${row.id} checksum does not match the released migration body`
+      };
+    }
+  }
+  const missingChecksum = checksums.indexOf(null);
+  if (missingChecksum >= 0) {
+    return {
+      status: "old",
+      migrationIds,
+      checksums,
+      detail: `migration ${migrationIds[missingChecksum]} has not been sealed with a checksum`
+    };
+  }
+  return {
+    status: rows.length === migrations.length ? "current" : "old",
+    migrationIds,
+    checksums
+  };
+}
+function assertMigrationLedger(db, migrations) {
+  const state = inspectMigrationLedger(db, migrations);
+  if (state.status === "newer") {
+    throw new Error(`Refusing to open a database with a newer migration ledger: ${state.detail}.`);
+  }
+  if (state.status === "inconsistent") {
+    throw new Error(`Refusing a database whose migrations are not an exact ordered prefix: ${state.detail}.`);
+  }
+  return state;
+}
+function assertCurrentMigrationLedger(db, migrations) {
+  const state = assertMigrationLedger(db, migrations);
+  if (state.status !== "current") {
+    throw new Error(`Refusing to open an obsolete writable schema; run \`akm migrate apply\`: ${state.detail ?? "pending migrations"}.`);
+  }
+  return state;
+}
+function ensureMigrationsTable(db) {
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS schema_migrations (
+      id         TEXT    PRIMARY KEY,
+      applied_at TEXT    NOT NULL DEFAULT (datetime('now')),
+      checksum   TEXT
+    );
+  `);
+  if (!ledgerHasChecksum(db))
+    db.exec("ALTER TABLE schema_migrations ADD COLUMN checksum TEXT");
+}
+function runMigrations(db, migrations, opts) {
+  if (opts?.applyPending === false) {
+    assertMigrationLedger(db, migrations);
+    return;
+  }
+  if (migrationsTableExists(db))
+    assertMigrationLedger(db, migrations);
+  ensureMigrationsTable(db);
+  opts?.bootstrap?.(db);
+  const ledger = assertMigrationLedger(db, migrations);
+  db.transaction(() => {
+    const update = db.prepare("UPDATE schema_migrations SET checksum = ? WHERE id = ? AND checksum IS NULL");
+    for (let index = 0;index < ledger.migrationIds.length; index += 1) {
+      update.run(migrationChecksum(migrations[index]), ledger.migrationIds[index]);
+    }
+    if (opts?.generationMarker) {
+      db.exec(`
+        CREATE TABLE IF NOT EXISTS akm_migration_generation (
+          singleton INTEGER PRIMARY KEY CHECK (singleton = 1),
+          operation_id TEXT NOT NULL,
+          phase TEXT NOT NULL
+        )
+      `);
+      db.prepare("INSERT INTO akm_migration_generation(singleton, operation_id, phase) VALUES (1, ?, ?) ON CONFLICT(singleton) DO UPDATE SET operation_id=excluded.operation_id, phase=excluded.phase").run(opts.generationMarker.operationId, opts.generationMarker.phase);
+    }
+  })();
+  const appliedRows = db.prepare("SELECT id FROM schema_migrations ORDER BY rowid").all();
+  const applied = new Set(appliedRows.map((r) => r.id));
+  for (const migration of migrations) {
+    if (applied.has(migration.id))
+      continue;
+    opts?.beforeMigration?.(migration);
+    db.transaction(() => {
+      db.exec(migration.up);
+      db.prepare("INSERT INTO schema_migrations (id, checksum) VALUES (?, ?)").run(migration.id, migrationChecksum(migration));
+    })();
+  }
+}
 
 // src/storage/managed-db.ts
 init_database();
@@ -17527,39 +17320,73 @@ function openManagedDatabase(spec) {
   return db;
 }
 
-// src/core/state-db.ts
-init_maintenance_barrier();
-init_migration_backup();
+// src/core/maintenance-barrier.ts
+init_errors();
+init_file_lock();
 init_paths();
-
-// src/storage/engines/sqlite-migrations.ts
-function ensureMigrationsTable(db) {
-  db.exec(`
-    CREATE TABLE IF NOT EXISTS schema_migrations (
-      id         TEXT    PRIMARY KEY,
-      applied_at TEXT    NOT NULL DEFAULT (datetime('now'))
-    );
-  `);
+import { AsyncLocalStorage } from "node:async_hooks";
+import { randomUUID as randomUUID2 } from "node:crypto";
+import fs11 from "node:fs";
+import path10 from "node:path";
+var heldBarrierContext = new AsyncLocalStorage;
+function tryAcquireMaintenanceBarrier() {
+  const lockPath = getMaintenanceBarrierPath();
+  fs11.mkdirSync(path10.dirname(lockPath), { recursive: true });
+  for (let attempt = 0;attempt < 2; attempt += 1) {
+    const ownership = tryAcquireLockSync(lockPath, createLockPayload({ purpose: "maintenance-start" }));
+    if (ownership) {
+      return () => releaseLock(ownership);
+    }
+    const probe = probeLock(lockPath);
+    if (probe.state !== "stale" || !reclaimStaleLock(lockPath, probe))
+      return;
+  }
+  return;
 }
-function runMigrations(db, migrations, opts) {
-  ensureMigrationsTable(db);
-  opts?.bootstrap?.(db);
-  const appliedRows = db.prepare("SELECT id FROM schema_migrations").all();
-  const applied = new Set(appliedRows.map((r) => r.id));
-  for (const migration of migrations) {
-    if (applied.has(migration.id))
-      continue;
-    opts?.beforeMigration?.(migration);
-    db.transaction(() => {
-      db.exec(migration.up);
-      db.prepare("INSERT INTO schema_migrations (id) VALUES (?)").run(migration.id);
-    })();
+function acquireMaintenanceBarrier() {
+  const release = tryAcquireMaintenanceBarrier();
+  if (release)
+    return release;
+  throw new ConfigError(`AKM maintenance is in progress (barrier ${getMaintenanceBarrierPath()}); retry after it completes.`, "INVALID_CONFIG_FILE");
+}
+function withMaintenanceStartBarrierSyncWait(run) {
+  if (heldBarrierContext.getStore()?.active)
+    return run();
+  const deadline = Date.now() + 5000;
+  let release = tryAcquireMaintenanceBarrier();
+  while (!release && Date.now() < deadline) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 5);
+    release = tryAcquireMaintenanceBarrier();
+  }
+  if (!release)
+    release = acquireMaintenanceBarrier();
+  const ownership = { active: true };
+  try {
+    return heldBarrierContext.run(ownership, run);
+  } finally {
+    ownership.active = false;
+    release();
   }
 }
+function acquireMaintenanceActivitySync(name) {
+  return withMaintenanceStartBarrierSyncWait(() => {
+    const directory = path10.join(path10.dirname(getMaintenanceBarrierPath()), "maintenance-activities");
+    fs11.mkdirSync(directory, { recursive: true, mode: 448 });
+    const lockPath = path10.join(directory, `${name}-${process.pid}-${randomUUID2()}.lock`);
+    const ownership = tryAcquireLockSync(lockPath, createLockPayload({ purpose: name }));
+    if (!ownership) {
+      throw new ConfigError(`Could not register AKM maintenance activity at ${lockPath}.`, "INVALID_CONFIG_FILE");
+    }
+    return () => releaseLock(ownership);
+  });
+}
+
+// src/core/state-db.ts
+init_migration_operation();
+init_paths();
 
 // src/core/state/migrations.ts
-init_migration_backup();
-var MIGRATIONS = [
+var STATE_MIGRATIONS = [
   {
     id: "001-initial-schema",
     up: `
@@ -17994,29 +17821,41 @@ var MIGRATIONS = [
   }
 ];
 function runMigrations2(db, options) {
-  runMigrations(db, MIGRATIONS, {
-    beforeMigration(migration) {
-      if (options?.ensureCutoverBackup && migration.id === "017-improve-run-strategy")
-        ensureMigrationBackup();
-    }
+  runMigrations(db, STATE_MIGRATIONS, {
+    applyPending: options?.applyPending,
+    generationMarker: options?.generationMarker
   });
 }
 
 // src/core/state-db.ts
 function getStateDbPath() {
-  return path12.join(getDataDir(), "state.db");
+  return path11.join(getDataDir(), "state.db");
 }
 function openStateDatabase(dbPath) {
   const canonicalPath = getStateDbPath();
   const resolvedPath = dbPath ?? canonicalPath;
-  const isCanonical = path12.resolve(resolvedPath) === path12.resolve(canonicalPath);
+  const isCanonical = path11.resolve(resolvedPath) === path11.resolve(canonicalPath);
+  if (isCanonical)
+    assertNoPendingMigrationOperation();
   const releaseActivity = isCanonical ? acquireMaintenanceActivitySync("state-db") : undefined;
   try {
-    if (isCanonical && !fs13.existsSync(getMigrationBackupDir()))
-      ensureMigrationBackup();
+    if (isCanonical)
+      assertNoPendingMigrationOperation();
+    const existed = fs12.existsSync(resolvedPath);
+    if (existed) {
+      const preflight = openDatabase(resolvedPath, { readonly: true });
+      try {
+        if (isCanonical)
+          assertCurrentMigrationLedger(preflight, STATE_MIGRATIONS);
+        else
+          assertMigrationLedger(preflight, STATE_MIGRATIONS);
+      } finally {
+        preflight.close();
+      }
+    }
     const db = openManagedDatabase({
       path: resolvedPath,
-      init: (db2) => runMigrations2(db2, { ensureCutoverBackup: isCanonical })
+      init: (db2) => runMigrations2(db2, { applyPending: !(isCanonical && existed) })
     });
     if (!releaseActivity)
       return db;
@@ -18143,7 +17982,7 @@ function recordImproveRun(db, input) {
 function parseArgs(argv) {
   const stashFromEnv = process.env.AKM_STASH_DIR;
   const out = {
-    stashDir: stashFromEnv ?? path13.join(process.env.HOME ?? "", "akm"),
+    stashDir: stashFromEnv ?? path12.join(process.env.HOME ?? "", "akm"),
     dryRun: false,
     archive: true
   };
@@ -18202,12 +18041,12 @@ function inferScope(envelope) {
 }
 async function main() {
   const args = parseArgs(process.argv.slice(2));
-  const runsRoot = path13.join(args.stashDir, ".akm", "runs");
-  if (!fs14.existsSync(runsRoot)) {
+  const runsRoot = path12.join(args.stashDir, ".akm", "runs");
+  if (!fs13.existsSync(runsRoot)) {
     console.log(`[import] no legacy runs directory at ${runsRoot}; nothing to do`);
     return;
   }
-  const entries = fs14.readdirSync(runsRoot, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name).sort();
+  const entries = fs13.readdirSync(runsRoot, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name).sort();
   if (entries.length === 0) {
     console.log(`[import] ${runsRoot} is empty; nothing to do`);
     return;
@@ -18221,8 +18060,8 @@ async function main() {
   let skippedParseFailed = 0;
   let skippedNoTimestamp = 0;
   for (const id of entries) {
-    const resultPath = path13.join(runsRoot, id, "improve-result.json");
-    if (!fs14.existsSync(resultPath)) {
+    const resultPath = path12.join(runsRoot, id, "improve-result.json");
+    if (!fs13.existsSync(resultPath)) {
       skippedNoResult++;
       continue;
     }
@@ -18232,7 +18071,7 @@ async function main() {
     }
     let decoded;
     try {
-      decoded = decodeImproveResult(fs14.readFileSync(resultPath, "utf8"));
+      decoded = decodeImproveResult(fs13.readFileSync(resultPath, "utf8"));
     } catch (err) {
       console.warn(`[import] skipping ${id}: parse failed (${err instanceof Error ? err.message : String(err)})`);
       skippedParseFailed++;
@@ -18298,8 +18137,8 @@ async function main() {
     return;
   }
   const ts = new Date().toISOString().replace(/[:.]/g, "-");
-  const archiveTarget = path13.join(args.stashDir, ".akm", `runs.archived-${ts}`);
-  fs14.renameSync(runsRoot, archiveTarget);
+  const archiveTarget = path12.join(args.stashDir, ".akm", `runs.archived-${ts}`);
+  fs13.renameSync(runsRoot, archiveTarget);
   console.log(`[import] archived ${runsRoot} \u2192 ${archiveTarget}`);
 }
 main().catch((err) => {