akm-cli 0.9.0-rc.8 → 0.9.0-rc.9

package/dist/cli/config-migrate.js

@@ -7,13 +7,13 @@ import os from "node:os";
 import path from "node:path";
 import { MAX_CONFIG_FILE_BYTES, MAX_LOCAL_METADATA_BYTES, readTextFileWithLimit, writeFileAtomic, } from "../core/common.js";
 import { parseAndValidateConfigText, resetConfigCache, sanitizeConfigForWrite, } from "../core/config/config.js";
-import { backupExistingConfig, parseConfigText, readConfigText, withConfigLock, writeConfigAtomic, } from "../core/config/config-io.js";
+import { backupExistingConfig, parseConfigText, withConfigLock, writeConfigAtomic } from "../core/config/config-io.js";
 import { ConfigError } from "../core/errors.js";
 import { withMaintenanceStartBarrier } from "../core/maintenance-barrier.js";
 import { assertNoArtifactReplacementBlockers, ensureMigrationBackupWithConfigLockHeld, fingerprintMigrationGeneration, getMigrationApplyJournalPath, getMigrationBackupDir, getMigrationBackupRoot, getMigrationRestoreJournalPath, inspectMigrationState, MIGRATION_BACKUP_VERSION, recoverInterruptedRestoreWithLocksHeld, restoreMigrationBackupWithLocksHeld, sameMigrationGeneration, verifyMigrationBackup, } from "../core/migration-backup.js";
 import { getConfigPath, getDbPath, getStateDbPathInDataDir } from "../core/paths.js";
 import { runMigrations as runStateMigrations } from "../core/state/migrations.js";
-import { mergeLockEntriesSync } from "../integrations/lockfile.js";
+import { isValidLockfileEntry, mergeLockEntriesSync, readLockfile } from "../integrations/lockfile.js";
 import { migrateConfigSourcesToBundles, migratedLockEntries } from "../migrate/legacy/config-source-migration.js";
 import { runContentMigration } from "../migrate/legacy/content-migration.js";
 import { getLegacyWorkflowDbPath } from "../migrate/legacy/legacy-paths.js";
@@ -79,6 +79,54 @@ function isGenerationFingerprint(value) {
 function sameArtifactFingerprint(left, right) {
     return JSON.stringify(left) === JSON.stringify(right);
 }
+function isEmptyFileFingerprint(value) {
+    return value?.byteSize === 0 && value.sha256 === createHash("sha256").digest("hex");
+}
+function sameWorkflowWal(current, expected) {
+    return JSON.stringify(current) === JSON.stringify(expected) || (expected === null && isEmptyFileFingerprint(current));
+}
+function sameApplyJournalGeneration(current, journal) {
+    if (sameMigrationGeneration(current, journal.generation))
+        return true;
+    if (journal.phase !== "workflow-applied")
+        return false;
+    return (sameArtifactFingerprint(current.config, journal.generation.config) &&
+        sameArtifactFingerprint(current.state, journal.generation.state) &&
+        JSON.stringify(current.workflow.main) === JSON.stringify(journal.generation.workflow.main) &&
+        sameWorkflowWal(current.workflow.wal, journal.generation.workflow.wal));
+}
+function isMigrationLockEntries(value) {
+    return (Array.isArray(value) &&
+        value.every((entry) => isValidLockfileEntry(entry) && typeof entry.localRoot === "string" && entry.localRoot.length > 0));
+}
+function recoverV2MigrationLockEntries(journal) {
+    const configBackupPath = path.join(journal.backupPath, "config.json");
+    const backupEntries = fs.existsSync(configBackupPath)
+        ? migratedLockEntries(parseConfigText(readTextFileWithLimit(configBackupPath, MAX_CONFIG_FILE_BYTES, "Migration backup config"), configBackupPath))
+        : [];
+    const bundles = journal.targetConfig.bundles;
+    if (!bundles || typeof bundles !== "object" || Array.isArray(bundles))
+        return [];
+    const managedBundleIds = new Set(Object.entries(bundles)
+        .filter(([, entry]) => {
+        if (!entry || typeof entry !== "object" || Array.isArray(entry))
+            return false;
+        return "git" in entry || "npm" in entry;
+    })
+        .map(([id]) => id));
+    const candidates = [...backupEntries, ...readLockfile()];
+    const byId = new Map();
+    for (const entry of candidates) {
+        if (managedBundleIds.has(entry.id) && entry.localRoot)
+            byId.set(entry.id, entry);
+    }
+    const missing = [...managedBundleIds].filter((id) => !byId.has(id));
+    if (missing.length > 0) {
+        throw new ConfigError(`Cannot recover materialized roots for format-2 migration journal bundle(s): ${missing.join(", ")}. ` +
+            "Restore the journal's verified backup or supply the missing lock roots before resuming.", "INVALID_CONFIG_FILE");
+    }
+    return [...byId.values()];
+}
 /**
  * Collapse state.db to a SINGLE FILE (DELETE journal) for the rest of the
  * apply. A WAL-mode state.db carries `-wal`/`-shm` sidecars that the migration
@@ -602,7 +650,7 @@ function inspectExactApplyJournalGeneration(journal) {
     applyPreflightHookForTests?.(journal.phase);
     const capture = captureMigrationInspection(journal.phase);
     try {
-        if (!sameMigrationGeneration(capture.generation, journal.generation)) {
+        if (!sameApplyJournalGeneration(capture.generation, journal)) {
             throw new MigrationPreflightGenerationError(`Migration apply journal phase ${journal.phase} changed before its next mutation; the external generation was preserved.`, "INVALID_CONFIG_FILE");
         }
         return capture.artifacts;
@@ -763,6 +811,7 @@ function readApplyJournalMetadata() {
     if (!fs.existsSync(journalPath))
         return {};
     let journal;
+    let wasFormat2 = false;
     try {
         const value = JSON.parse(readTextFileWithLimit(journalPath, MAX_LOCAL_METADATA_BYTES, "Migration apply journal"));
         const phases = [
@@ -780,27 +829,29 @@ function readApplyJournalMetadata() {
             "rollback-prepared",
             "committed",
         ];
+        const formatVersion = typeof value === "object" && value !== null && !Array.isArray(value)
+            ? value.formatVersion
+            : undefined;
+        const requiredKeys = [
+            "backupPath",
+            "backupRunId",
+            "formatVersion",
+            "generation",
+            "installationId",
+            ...(formatVersion === 3 ? ["migrationLockEntries"] : []),
+            "operationId",
+            "phase",
+            "targetConfig",
+            "version",
+        ];
         if (typeof value !== "object" ||
             value === null ||
             Array.isArray(value) ||
-            Object.keys(value).sort().join(",") !==
-                [
-                    "backupPath",
-                    "backupRunId",
-                    "formatVersion",
-                    "generation",
-                    "installationId",
-                    "operationId",
-                    "phase",
-                    "targetConfig",
-                    "version",
-                ]
-                    .sort()
-                    .join(",")) {
+            Object.keys(value).sort().join(",") !== requiredKeys.sort().join(",")) {
             return { error: `Invalid migration apply journal at ${journalPath}.` };
         }
         const candidate = value;
-        if (candidate.formatVersion !== 2 ||
+        if ((candidate.formatVersion !== 2 && candidate.formatVersion !== 3) ||
             candidate.version !== MIGRATION_BACKUP_VERSION ||
             typeof candidate.operationId !== "string" ||
             !/^[A-Za-z0-9._-]+$/.test(candidate.operationId) ||
@@ -812,10 +863,16 @@ function readApplyJournalMetadata() {
             !candidate.targetConfig ||
             typeof candidate.targetConfig !== "object" ||
             Array.isArray(candidate.targetConfig) ||
-            !phases.includes(candidate.phase)) {
+            !phases.includes(candidate.phase) ||
+            (candidate.formatVersion === 3 && !isMigrationLockEntries(candidate.migrationLockEntries))) {
             return { error: `Invalid or foreign migration apply journal at ${journalPath}.` };
         }
-        journal = candidate;
+        wasFormat2 = candidate.formatVersion === 2;
+        journal = {
+            ...candidate,
+            formatVersion: 3,
+            migrationLockEntries: candidate.formatVersion === 3 ? (candidate.migrationLockEntries ?? []) : [],
+        };
     }
     catch (error) {
         return {
@@ -834,6 +891,8 @@ function readApplyJournalMetadata() {
         if (manifest.runId !== journal.backupRunId || manifest.installationId !== journal.installationId) {
             throw new ConfigError(`Migration apply journal backup provenance does not match its manifest.`, "INVALID_CONFIG_FILE");
         }
+        if (wasFormat2)
+            journal.migrationLockEntries = recoverV2MigrationLockEntries(journal);
         return { journal, config, manifest };
     }
     catch (error) {
@@ -897,6 +956,10 @@ function isAuthenticatedCutoverAdjacent(journal, current, stateSnapshotPath) {
 function workflowArtifactIsDeletionSubset(expected, current) {
     return ["main", "wal", "shm"].every((component) => {
         const actual = current.workflow[component];
+        if (component === "shm" && expected.workflow.shm === null)
+            return true;
+        if (component === "wal" && sameWorkflowWal(actual, expected.workflow.wal))
+            return true;
         return actual === null || JSON.stringify(actual) === JSON.stringify(expected.workflow[component]);
     });
 }
@@ -927,7 +990,7 @@ function readApplyJournal() {
         if (isPostCutoverPhase(journal.phase)) {
             if (isTaskOnlyRepair(manifest)) {
                 const artifacts = validateApplyPhase(journal, manifest, capture.paths, inspectedArtifacts);
-                if (!sameMigrationGeneration(rawGeneration, journal.generation)) {
+                if (!sameApplyJournalGeneration(rawGeneration, journal)) {
                     throw new ConfigError(`Migration apply journal phase ${journal.phase} does not match the exact live artifact generation.`, "INVALID_CONFIG_FILE");
                 }
                 return { journal, config, artifacts };
@@ -938,7 +1001,7 @@ function readApplyJournal() {
                 artifacts: postCutoverArtifacts(journal, manifest, rawGeneration, capture.paths, inspectedArtifacts),
             };
         }
-        if (!sameMigrationGeneration(rawGeneration, journal.generation) &&
+        if (!sameApplyJournalGeneration(rawGeneration, journal) &&
             isAuthenticatedCutoverAdjacent(journal, rawGeneration, capture.paths.stateDbPath)) {
             const artifacts = postCutoverArtifacts({ ...journal, phase: "cutover-applied" }, manifest, rawGeneration, capture.paths, inspectedArtifacts);
             return {
@@ -955,7 +1018,7 @@ function readApplyJournal() {
         if (isPreConversionCompatiblePhase(journal.phase)) {
             const stateMarker = readSingleFileBoundStateMarker(journal, capture.paths.stateDbPath);
             if (stateMarker?.phase === "state-applied") {
-                if (sameMigrationGeneration(rawGeneration, journal.generation)) {
+                if (sameApplyJournalGeneration(rawGeneration, journal)) {
                     return { journal, config, artifacts: inspectedArtifacts };
                 }
                 if (isAuthenticatedWorkflowAdjacent(journal, rawGeneration, capture.paths.workflowDbPath)) {
@@ -974,7 +1037,7 @@ function readApplyJournal() {
             }
         }
         if (isPreConversionCompatiblePhase(journal.phase)) {
-            if (sameMigrationGeneration(rawGeneration, journal.generation)) {
+            if (sameApplyJournalGeneration(rawGeneration, journal)) {
                 return {
                     journal,
                     config,
@@ -998,7 +1061,7 @@ function readApplyJournal() {
             throw new ConfigError(`Migration apply journal phase ${journal.phase} does not match the exact live artifact generation.`, "INVALID_CONFIG_FILE");
         }
         if (journal.phase === "state-converting") {
-            if (sameMigrationGeneration(rawGeneration, journal.generation)) {
+            if (sameApplyJournalGeneration(rawGeneration, journal)) {
                 return {
                     journal,
                     config,
@@ -1023,7 +1086,7 @@ function readApplyJournal() {
             throw new ConfigError("Migration apply journal phase state-converting does not match its exact marker-bound generation.", "INVALID_CONFIG_FILE");
         }
         if (journal.phase === "state-collapsing") {
-            if (sameMigrationGeneration(rawGeneration, journal.generation)) {
+            if (sameApplyJournalGeneration(rawGeneration, journal)) {
                 return {
                     journal,
                     config,
@@ -1048,7 +1111,7 @@ function readApplyJournal() {
             throw new ConfigError("Migration apply journal phase state-collapsing does not match its exact marker-bound generation.", "INVALID_CONFIG_FILE");
         }
         validateApplyPhase(journal, manifest, capture.paths, inspectedArtifacts);
-        if (!sameMigrationGeneration(rawGeneration, journal.generation)) {
+        if (!sameApplyJournalGeneration(rawGeneration, journal)) {
             const adjacent = detectAdjacentGeneration(journal, manifest, inspectedArtifacts, rawGeneration, capture.paths.workflowDbPath);
             if (adjacent.adjacent || adjacent.rollbackCompleted) {
                 return { journal, config, artifacts: inspectedArtifacts, ...adjacent };
@@ -1087,14 +1150,14 @@ function authenticatePreConversionJournalForApply() {
     if (isAuthenticatedCutoverAdjacent(journal, current))
         return;
     if (readSingleFileBoundStateMarker(journal)?.phase === "state-applied") {
-        if (sameMigrationGeneration(current, journal.generation) ||
+        if (sameApplyJournalGeneration(current, journal) ||
             isAuthenticatedWorkflowAdjacent(journal, current) ||
             isAuthenticatedCutoverAdjacent(journal, current)) {
             return;
         }
         throw new ConfigError(`Migration apply journal phase ${journal.phase} does not match the exact live artifact generation.`, "INVALID_CONFIG_FILE");
     }
-    if (!sameMigrationGeneration(current, journal.generation) &&
+    if (!sameApplyJournalGeneration(current, journal) &&
         !isAuthenticatedWorkflowAdjacent(journal, current) &&
         !isAuthenticatedCutoverAdjacent(journal, current)) {
         throw new ConfigError(`Migration apply journal phase ${journal.phase} does not match the exact live artifact generation.`, "INVALID_CONFIG_FILE");
@@ -1112,7 +1175,7 @@ function preparePreConversionJournalForApply() {
         return;
     if (readSingleFileBoundStateMarker(journal)?.phase === "state-applied")
         return;
-    if (!sameMigrationGeneration(current, journal.generation)) {
+    if (!sameApplyJournalGeneration(current, journal)) {
         if (!isAuthenticatedWorkflowAdjacent(journal, current)) {
             throw new ConfigError(`Migration apply journal phase ${journal.phase} does not match the exact live artifact generation.`, "INVALID_CONFIG_FILE");
         }
@@ -1221,7 +1284,7 @@ function runStateMigrationStep(journal) {
         crashAfterForTests("state-marker");
     }
     if (journal.phase === "state-collapsing") {
-        if (!sameMigrationGeneration(fingerprintMigrationGeneration(), journal.generation)) {
+        if (!sameApplyJournalGeneration(fingerprintMigrationGeneration(), journal)) {
             const marker = readBoundStateGenerationMarkerFromDisk(journal.operationId);
             if (!marker) {
                 throw new ConfigError("state.db does not match the exact marker-bound generation recorded before conversion.", "INVALID_CONFIG_FILE");
@@ -1322,7 +1385,7 @@ function expandTilde(p) {
  * Source (a) (the index `item_ref` join) is authoritative, so an unresolved root
  * only costs a few origin aliases.
  */
-function cutoverStashRootsFromConfig(config) {
+function cutoverStashRootsFromConfig(config, migrationLockEntries = []) {
     const roots = [];
     const bundles = config.bundles;
     if (bundles && typeof bundles === "object") {
@@ -1333,10 +1396,23 @@ function cutoverStashRootsFromConfig(config) {
             const registryId = entry.registryId ?? id;
             roots.push({
                 path: path.resolve(expandTilde(bundlePath)),
+                bundleId: id,
                 registryId,
                 primary: config.defaultBundle === id,
             });
         }
+        for (const lock of migrationLockEntries) {
+            const localRoot = lock.localRoot;
+            if (!localRoot || roots.some((root) => path.resolve(root.path) === path.resolve(localRoot)))
+                continue;
+            const entry = bundles[lock.id];
+            roots.push({
+                path: path.resolve(expandTilde(localRoot)),
+                bundleId: lock.id,
+                registryId: entry?.registryId ?? lock.id,
+                primary: config.defaultBundle === lock.id,
+            });
+        }
     }
     return roots;
 }
@@ -1388,7 +1464,7 @@ function runCutoverStep(journal, target) {
     const statePath = getStateDbPathInDataDir();
     const workflowPath = getLegacyWorkflowDbPath();
     const indexPath = getDbPath();
-    const stashRoots = cutoverStashRootsFromConfig(target);
+    const stashRoots = cutoverStashRootsFromConfig(target, journal.migrationLockEntries);
     if (!cutoverMergeCommitted(statePath, journal.operationId)) {
         const refMap = buildCutoverRefMap({
             oldIndexDbPath: indexPath,
@@ -1405,9 +1481,8 @@ function runCutoverStep(journal, target) {
     else {
         assertPostCutoverWorkflowAuthenticated(journal, fingerprintMigrationGeneration());
     }
-    // Boundary ops run AFTER the committed state txn, OUTSIDE the fail-closed gate
-    // (cutover-design.md §2 step 5/6). Idempotent + best-effort — they log and
-    // return, never throw, so a rename/unlink hiccup never rolls back the merge.
+    // Boundary ops run AFTER the committed state txn. Index quarantine remains
+    // best-effort; workflow deletion must complete before the journal advances.
     quarantineIndexDb(journal.operationId, indexPath);
     deleteWorkflowDb(workflowPath);
     // WI-8.5d: the content migration (`.stash.json` fold + delete, D-R6 reserved-
@@ -1527,6 +1602,7 @@ function loadTargetConfig(preparedConfigPath, artifacts) {
                 path: targetPath,
             },
             config: parseMigrationTargetConfig(text, targetPath),
+            migrationLockEntries: migratedLockEntries(parseConfigText(text, targetPath)),
         };
     }
     catch (error) {
@@ -1558,6 +1634,7 @@ function buildMigrationPlan(preparedConfigPath, activeApply) {
         unsafeArtifact("config.json", artifacts.config),
         unsafeArtifact("state.db", artifacts.state),
         unsafeArtifact("workflow.db", artifacts.workflow),
+        unsafeArtifact("index.db", artifacts.index),
     ].filter((blocker) => blocker !== undefined);
     if (target.state.status !== "current")
         blockers.push(target.state.detail ?? "A current target config is required.");
@@ -1617,11 +1694,13 @@ export async function runMigrationStatus(options = {}) {
 }
 function requireEligiblePlan(preparedConfigPath, active = readApplyJournal()) {
     const plan = buildMigrationPlan(preparedConfigPath, active);
-    const loaded = active.journal ? { config: active.config } : loadTargetConfig(preparedConfigPath, plan.artifacts);
+    const loaded = active.journal
+        ? { config: active.config, migrationLockEntries: active.journal.migrationLockEntries }
+        : loadTargetConfig(preparedConfigPath, plan.artifacts);
     if (plan.status === "blocked" || !loaded.config) {
         throw new ConfigError(`Migration is blocked: ${plan.blockers.join("; ")}`, "INVALID_CONFIG_FILE");
     }
-    return { plan, target: loaded.config };
+    return { plan, target: loaded.config, migrationLockEntries: loaded.migrationLockEntries ?? [] };
 }
 export async function runMigrationApply(options = {}) {
     if (options.dryRun) {
@@ -1656,14 +1735,14 @@ export async function runMigrationApply(options = {}) {
                 active.journal.phase = active.adjacent.phase;
             writeApplyJournal(active.journal);
         }
-        const { plan, target } = requireEligiblePlan(options.preparedConfigPath, active);
+        const { plan, target, migrationLockEntries } = requireEligiblePlan(options.preparedConfigPath, active);
         if (plan.status === "current")
             return { plan };
         const backup = active.journal
             ? { path: active.journal.backupPath, manifest: verifyMigrationBackup(active.journal.backupPath) }
             : ensureMigrationBackupWithConfigLockHeld();
         const journal = active.journal ?? {
-            formatVersion: 2,
+            formatVersion: 3,
             version: MIGRATION_BACKUP_VERSION,
             operationId: `${process.pid}-${randomUUID()}`,
             installationId: backup.manifest.installationId,
@@ -1671,6 +1750,7 @@ export async function runMigrationApply(options = {}) {
             phase: "prepared",
             backupPath: backup.path,
             targetConfig: sanitizeConfigForWrite(target),
+            migrationLockEntries,
             generation: fingerprintMigrationGeneration(),
         };
         if (!active.journal)
@@ -1721,15 +1801,7 @@ export async function runMigrationApply(options = {}) {
             }
             if (journal.phase === "cutover-applied") {
                 // The cutover is committed, so all remaining work is forward-only.
-                try {
-                    const preCutoverText = readConfigText(getConfigPath());
-                    if (preCutoverText !== undefined) {
-                        mergeLockEntriesSync(migratedLockEntries(parseConfigText(preCutoverText, getConfigPath())));
-                    }
-                }
-                catch {
-                    // Advisory lock re-key only; the committed cutover is unaffected.
-                }
+                mergeLockEntriesSync(journal.migrationLockEntries);
                 backupExistingConfig(getConfigPath());
                 writeConfigAtomic(getConfigPath(), sanitizeConfigForWrite(target));
                 resetConfigCache();
@@ -1778,7 +1850,7 @@ export async function runMigrationApply(options = {}) {
                 journal.phase = "rollback-prepared";
                 journal.generation = rollbackGeneration;
                 writeApplyJournal(journal);
-                if (!sameMigrationGeneration(fingerprintMigrationGeneration(), journal.generation)) {
+                if (!sameApplyJournalGeneration(fingerprintMigrationGeneration(), journal)) {
                     throw new ConfigError(`Refusing migration rollback because live artifacts no longer match journal phase ${journal.phase}.`, "INVALID_CONFIG_FILE");
                 }
                 restoreMigrationBackupWithLocksHeld(backup.path);

package/dist/commands/improve/eligibility.js

@@ -136,6 +136,14 @@ async function collectEligibleRefsFromIndex(scope, stashDir, improveProfile, rea
             // xrefs, and `displayRef` output spelling. `.itemRef` below stays the
             // fully-qualified durable key.
             const ref = conceptIdFromTypeName(indexed.entry.type, indexed.entry.name);
+            try {
+                parseRefInput(ref);
+            }
+            catch (error) {
+                if (error instanceof UsageError || error instanceof NotFoundError)
+                    continue;
+                throw error;
+            }
             // Chunk-5 flip F5d (Step 4): the durable `item_ref` (`<bundle>//<concept-id>`),
             // reconstructed from the mapper-unlocked provenance columns with ZERO extra
             // queries (D-R3 — derived from the resolved index entry, never raw input).
@@ -188,9 +196,9 @@ async function collectEligibleRefsFromIndex(scope, stashDir, improveProfile, rea
         };
     }
     catch (error) {
-        // The bun-test isolation guard must never be downgraded to "empty plan".
+        // Empty-stash setup paths can open index.db before its schema exists.
         rethrowIfTestIsolationError(error);
-        if (error instanceof NotFoundError || error instanceof Error) {
+        if (error instanceof Error && /no such table:\s*entries/i.test(error.message)) {
             return { plannedRefs: [], memorySummary: { eligible: 0, derived: 0 }, strategyFilteredRefs: [] };
         }
         throw error;

package/dist/core/asset/frontmatter.js

@@ -130,6 +130,18 @@ function parseFrontmatterLenient(frontmatter) {
 export function mutateFrontmatter(filePath, mutator) {
     const raw = fs.readFileSync(filePath, "utf8");
     const parsed = parseFrontmatter(raw);
+    if (parsed.frontmatter?.trim()) {
+        let strict;
+        try {
+            strict = yamlParse(parsed.frontmatter);
+        }
+        catch {
+            throw new Error(`Cannot mutate malformed YAML frontmatter in ${filePath}.`);
+        }
+        if (strict === null || typeof strict !== "object" || Array.isArray(strict)) {
+            throw new Error(`Cannot mutate non-mapping YAML frontmatter in ${filePath}.`);
+        }
+    }
     const nextFrontmatter = mutator(parsed);
     if (nextFrontmatter === null)
         return false;

package/dist/core/migration-backup.js

@@ -279,16 +279,15 @@ export function inspectMigrationState(paths = {}) {
         index: inspectIndexDbArtifact(paths.indexDbPath ?? getDbPath()),
     };
 }
-function assertBackupEligible(state) {
-    // index.db is deliberately absent here: an unreadable index.db is excluded
-    // from the backup (regenerable cache; the cutover's usage_events rescue
-    // reports an empty result) rather than blocking migration entirely.
+function assertBackupEligible(state, allowCorruptIndex = false) {
     const entries = [
         ["config.json", state.config],
         ["state.db", state.state],
         ["workflow.db", state.workflow],
+        ["index.db", state.index],
     ];
-    const unsafe = entries.filter(([, artifact]) => ["newer", "inconsistent", "corrupt"].includes(artifact.status));
+    const unsafe = entries.filter(([name, artifact]) => ["newer", "inconsistent", "corrupt"].includes(artifact.status) &&
+        !(allowCorruptIndex && name === "index.db" && artifact.status === "corrupt"));
     if (unsafe.length > 0) {
         throw new ConfigError(`Refusing migration backup because artifact state is unsafe: ${unsafe
             .map(([name, artifact]) => `${name}=${artifact.status}${artifact.detail ? ` (${artifact.detail})` : ""}`)
@@ -322,7 +321,7 @@ function parseManifest(bundlePath) {
     for (const name of artifactNamesFor(manifest.formatVersion)) {
         const artifact = manifest.artifacts?.[name];
         // index.db is never ledger-classified: "current" (readable) or "missing" only.
-        const allowedStatuses = name === "index.db" ? ["current", "missing"] : ["old", "current", "missing"];
+        const allowedStatuses = name === "index.db" ? ["current", "missing", "corrupt"] : ["old", "current", "missing"];
         if (!artifact ||
             artifact.sourcePath !== expected[name] ||
             typeof artifact.present !== "boolean" ||
@@ -460,9 +459,9 @@ function stateForName(state, name) {
         return state.workflow;
     return state.index;
 }
-function createMigrationBackupUnlocked() {
+function createMigrationBackupUnlocked(options = {}) {
     const state = inspectMigrationState();
-    assertBackupEligible(state);
+    assertBackupEligible(state, options.allowCorruptIndex);
     const root = getMigrationBackupRoot();
     fs.mkdirSync(root, { recursive: true, mode: 0o700 });
     fs.chmodSync(root, 0o700);
@@ -477,25 +476,23 @@ function createMigrationBackupUnlocked() {
         for (const name of ARTIFACT_NAMES) {
             const sourcePath = sources[name];
             const sourceState = stateForName(state, name);
-            // index.db never blocks a backup: anything short of a clean read
-            // (corrupt cache) is recorded as absent — it is regenerable, and the
-            // cutover's usage_events rescue reports the empty result.
-            const effectiveState = name === "index.db" && sourceState.status !== "current" ? { status: "missing" } : sourceState;
             const destination = path.join(temporary, name);
-            const present = effectiveState.status !== "missing";
+            const present = sourceState.status !== "missing";
             if (present) {
                 if (name === "config.json")
                     copyFileDurable(sourcePath, destination);
+                else if (name === "index.db" && sourceState.status === "corrupt")
+                    copyFileDurable(sourcePath, destination);
                 else
                     backupSqlite(sourcePath, destination);
             }
             const inspected = present ? inspectArtifactAt(name, destination) : { status: "missing" };
-            const expectedArtifact = { ...effectiveState, sourcePath, present, byteSize: 0, sha256: null, createdAt };
+            const expectedArtifact = { ...sourceState, sourcePath, present, byteSize: 0, sha256: null, createdAt };
             if (!sameState(inspected, expectedArtifact)) {
                 throw new ConfigError(`Snapshot ${name} does not match its source migration state.`, "INVALID_CONFIG_FILE");
             }
             artifacts[name] = {
-                ...effectiveState,
+                ...sourceState,
                 sourcePath,
                 present,
                 byteSize: present ? fs.statSync(destination).size : 0,
@@ -1227,7 +1224,7 @@ export function restoreMigrationBackup(confirm, runId) {
         assertNoArtifactReplacementBlockers(bundlePath);
         recoverInterruptedRestore();
         const manifest = verifyMigrationBackup(bundlePath);
-        const rescue = createMigrationBackupUnlocked();
+        const rescue = createMigrationBackupUnlocked({ allowCorruptIndex: true });
         replaceArtifactsFromBundle(bundlePath, manifest, rescue.manifest.runId);
         return { path: bundlePath, created: false, manifest, rescuePath: rescue.path };
     })));

package/dist/integrations/lockfile.js

@@ -113,7 +113,21 @@ export async function upsertLockEntry(entry) {
 export function mergeLockEntriesSync(entries) {
     if (entries.length === 0)
         return;
-    const existing = readLockfile();
+    let existing = [];
+    const lockfilePath = getLockfilePath();
+    if (fs.existsSync(lockfilePath)) {
+        let raw;
+        try {
+            raw = JSON.parse(fs.readFileSync(lockfilePath, "utf8"));
+        }
+        catch (error) {
+            throw new ConfigError(`Cannot merge migration lock entries into unreadable lockfile ${lockfilePath}: ${error instanceof Error ? error.message : String(error)}.`, "INVALID_CONFIG_FILE");
+        }
+        if (!Array.isArray(raw) || !raw.every(isValidLockfileEntry)) {
+            throw new ConfigError(`Cannot merge migration lock entries into malformed lockfile ${lockfilePath}.`, "INVALID_CONFIG_FILE");
+        }
+        existing = raw;
+    }
     const incoming = new Set(entries.map((e) => e.id));
     writeLockfileUnlocked([...existing.filter((e) => !incoming.has(e.id)), ...entries]);
 }
@@ -130,7 +144,7 @@ export async function removeLockEntry(id) {
     }
 }
 // ── Helpers ─────────────────────────────────────────────────────────────────
-function isValidLockfileEntry(value) {
+export function isValidLockfileEntry(value) {
     if (typeof value !== "object" || value === null || Array.isArray(value))
         return false;
     const obj = value;

package/dist/migrate/legacy/config-source-migration.js

@@ -31,6 +31,7 @@
  * original registry id is preserved in the entry's `registryId` locator so
  * nothing is lost.
  */
+import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { installedSourceDescriptor } from "../../core/config/config-sources.js";
@@ -99,7 +100,7 @@ export function oldConfigMigratableSources(raw) {
             });
         }
     }
-    else if (stashDir) {
+    if (!out.some((source) => source.primary) && stashDir) {
         out.push({
             derivationPath: path.resolve(expandTilde(stashDir)),
             writable: true,
@@ -143,7 +144,33 @@ export function oldConfigMigratableSources(raw) {
             ...(needsLock ? { lock: { source: source, ref: ref, localRoot: resolvedRoot } } : {}),
         });
     }
-    return out;
+    const deduplicated = [];
+    const byPath = new Map();
+    for (const source of out) {
+        let pathIdentity;
+        if (path.isAbsolute(source.derivationPath)) {
+            const resolved = path.resolve(source.derivationPath);
+            try {
+                pathIdentity = fs.realpathSync(resolved);
+            }
+            catch {
+                pathIdentity = resolved;
+            }
+            if (process.platform === "win32")
+                pathIdentity = pathIdentity.toLowerCase();
+        }
+        const prior = pathIdentity ? byPath.get(pathIdentity) : undefined;
+        if (!prior) {
+            deduplicated.push(source);
+            if (pathIdentity)
+                byPath.set(pathIdentity, source);
+            continue;
+        }
+        prior.registryId ??= source.registryId;
+        prior.writable ||= source.writable;
+        prior.primary ||= source.primary;
+    }
+    return deduplicated;
 }
 /**
  * Derive the §10.2 lock entries the config-shape migration produces for
@@ -197,6 +224,7 @@ export function migrateConfigSourcesToBundles(raw) {
     const migratable = oldConfigMigratableSources(raw);
     const usedIds = new Set();
     const bundles = {};
+    const selectorToBundle = new Map();
     let defaultBundle;
     for (const src of migratable) {
         // The ONE shared derivation, so the emitted key equals the runtime
@@ -210,6 +238,8 @@ export function migrateConfigSourcesToBundles(raw) {
         if (src.registryId && src.registryId !== id)
             entry.registryId = src.registryId;
         bundles[id] = entry;
+        if (src.registryId)
+            selectorToBundle.set(src.registryId, id);
         if (src.primary)
             defaultBundle = id;
     }
@@ -219,5 +249,9 @@ export function migrateConfigSourcesToBundles(raw) {
     out.bundles = bundles;
     if (defaultBundle !== undefined)
         out.defaultBundle = defaultBundle;
+    const defaultWriteTarget = readString(raw.defaultWriteTarget);
+    const migratedWriteTarget = defaultWriteTarget ? selectorToBundle.get(defaultWriteTarget) : undefined;
+    if (migratedWriteTarget)
+        out.defaultWriteTarget = migratedWriteTarget;
     return out;
 }

package/dist/migrate/legacy/content-migration.js

@@ -17,12 +17,13 @@
  *     the indexer reads curated frontmatter for `.md` files only
  *     ({@link applyCuratedFrontmatter} runs on `ext === ".md"`), and prepending a
  *     `---` block to a shell/script/env asset would corrupt it — non-markdown
- *     entries are counted + logged, never rewritten.
+ *     entries are counted + logged, never rewritten. A sidecar is deleted only
+ *     after every entry folds successfully; otherwise its source bytes remain.
  *  2. **D-R6 reserved-filename conformance.** OKF reserves `index.md`/`log.md` as
  *     bundle structure at every depth (never concept documents). A pre-existing
- *     stash file so named that actually carries akm ASSET frontmatter (a
- *     `description`/`when_to_use`-bearing concept mis-placed under a reserved
- *     name) is renamed to a collision-safe reported name (`index-content.md`,
+ *     stash file so named that the frozen layout treated as an asset (or that
+ *     carries explicit asset frontmatter outside a canonical type root) is
+ *     renamed to a collision-safe reported name (`index-content.md`,
  *     `log-content.md`, appending `-2`/`-3`/… on collision) so the akm adapter's
  *     new reserved-file exclusion never silently drops it. A structural
  *     `index.md`/`log.md` (no asset frontmatter) is left in place.
@@ -52,7 +53,8 @@ import path from "node:path";
 import { mutateFrontmatter, parseFrontmatter } from "../../core/asset/frontmatter.js";
 import { asNonEmptyString } from "../../core/common.js";
 import { warn } from "../../core/warn.js";
-import { legacyStashFilePath, readLegacyStashOverrides } from "./legacy-stash-json.js";
+import { isRelevantAssetFile, TYPE_DIRS } from "./legacy-layout.js";
+import { inspectLegacyStashOverrides, legacyStashFilePath } from "./legacy-stash-json.js";
 /** OKF reserved structural filenames (case-insensitive, any depth). */
 const RESERVED_BASENAMES = new Set(["index.md", "log.md"]);
 /**
@@ -148,7 +150,7 @@ export function runContentMigration(stashRoots) {
         for (const dir of dirs)
             foldSidecarInDir(dir, report);
         for (const dir of dirs)
-            renameReservedConceptsInDir(dir, report);
+            renameReservedConceptsInDir(resolved, dir, report);
         for (const dir of dirs)
             rewriteSourceBackrefsInDir(dir, report);
     }
@@ -208,9 +210,18 @@ function foldSidecarInDir(dir, report) {
     if (!fs.existsSync(sidecarPath))
         return;
     try {
-        const overrides = readLegacyStashOverrides(dir);
-        for (const entry of overrides?.entries ?? [])
-            foldEntry(dir, entry, report);
+        const inspected = inspectLegacyStashOverrides(dir);
+        if (inspected.status !== "valid") {
+            warn(`[akm] content-migration: retained unreadable sidecar ${sidecarPath}.`);
+            return;
+        }
+        let complete = inspected.complete;
+        for (const entry of inspected.stash.entries)
+            complete = foldEntry(dir, entry, report) && complete;
+        if (!complete) {
+            warn(`[akm] content-migration: retained partially migrated sidecar ${sidecarPath}.`);
+            return;
+        }
         fs.rmSync(sidecarPath, { force: true });
         report.sidecarsFolded++;
     }
@@ -222,20 +233,32 @@ function foldSidecarInDir(dir, report) {
 function foldEntry(dir, entry, report) {
     if (!entry.filename) {
         report.entriesSkipped++;
-        return;
+        return false;
+    }
+    const target = path.resolve(dir, entry.filename);
+    const relative = path.relative(path.resolve(dir), target);
+    if (relative.startsWith("..") || path.isAbsolute(relative)) {
+        report.entriesSkipped++;
+        return false;
     }
-    const target = path.join(dir, entry.filename);
     if (!fs.existsSync(target) || path.extname(target).toLowerCase() !== ".md") {
         report.entriesSkipped++;
-        return;
+        return false;
     }
     try {
+        const realRelative = path.relative(fs.realpathSync(dir), fs.realpathSync(target));
+        if (realRelative.startsWith("..") || path.isAbsolute(realRelative)) {
+            report.entriesSkipped++;
+            return false;
+        }
         mutateFrontmatter(target, (parsed) => foldCuratedFields(parsed.data, entry));
         report.entriesFolded++;
+        return true;
     }
     catch (error) {
         report.entriesSkipped++;
         warn(`[akm] content-migration: could not fold entry into ${target}: ${errMsg(error)}`);
+        return false;
     }
 }
 /** Merge the sidecar entry's curated fields onto the existing frontmatter (sidecar wins). */
@@ -250,7 +273,7 @@ function foldCuratedFields(existing, entry) {
     return next;
 }
 /** D-R6: rename any mis-named reserved-filename concept in `dir` to a collision-safe name. */
-function renameReservedConceptsInDir(dir, report) {
+function renameReservedConceptsInDir(root, dir, report) {
     let entries;
     try {
         entries = fs.readdirSync(dir, { withFileTypes: true });
@@ -263,7 +286,10 @@ function renameReservedConceptsInDir(dir, report) {
             continue;
         const filePath = path.join(dir, entry.name);
         try {
-            if (!carriesAssetFrontmatter(filePath))
+            const legacyType = legacyTypeForDirectory(root, dir);
+            if (legacyType === "wiki")
+                continue;
+            if (!carriesAssetFrontmatter(filePath) && !(legacyType && isRelevantAssetFile(legacyType, entry.name)))
                 continue;
             const target = collisionSafeTarget(dir, entry.name);
             fs.renameSync(filePath, target);
@@ -274,6 +300,25 @@ function renameReservedConceptsInDir(dir, report) {
         }
     }
 }
+function legacyTypeForDirectory(root, dir) {
+    const [top] = path.relative(root, dir).split(path.sep);
+    if (!top || top === "..")
+        return undefined;
+    const exact = Object.entries(TYPE_DIRS).find(([, typeDir]) => typeDir === top)?.[0];
+    if (exact)
+        return exact;
+    const actualRoot = path.join(root, top);
+    try {
+        const actualIdentity = fs.realpathSync(actualRoot);
+        return Object.entries(TYPE_DIRS).find(([, typeDir]) => {
+            const canonicalRoot = path.join(root, typeDir);
+            return fs.existsSync(canonicalRoot) && fs.realpathSync(canonicalRoot) === actualIdentity;
+        })?.[0];
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * True when a reserved-name file actually holds akm ASSET frontmatter (a
  * concept mis-placed under a reserved name), keyed on the D-R6 example markers

package/dist/migrate/legacy/legacy-stash-json.js

@@ -36,35 +36,43 @@ export function legacyStashFilePath(dirPath) {
  * or `null` when absent/empty/corrupt. Was `loadStashFile` in `metadata.ts`;
  * relocated verbatim to the migrator home (scope-B ruling) — behavior unchanged.
  */
-export function readLegacyStashOverrides(dirPath, options) {
+export function inspectLegacyStashOverrides(dirPath, options) {
     const filePath = legacyStashFilePath(dirPath);
     if (!fs.existsSync(filePath))
-        return null;
+        return { status: "missing" };
     try {
         const raw = JSON.parse(fs.readFileSync(filePath, "utf8"));
         if (!raw || !Array.isArray(raw.entries))
-            return null;
+            return { status: "invalid" };
         const entries = [];
+        let complete = true;
         for (const e of raw.entries) {
             const validated = validateStashEntry(e);
             if (validated) {
-                if (options?.requireFilename && !validated.filename)
+                if (options?.requireFilename && !validated.filename) {
+                    complete = false;
                     continue;
+                }
                 entries.push(validated);
             }
             else {
+                complete = false;
                 const name = typeof e === "object" && e !== null && typeof e.name === "string"
                     ? e.name
                     : "(unknown)";
                 warn(`Warning: Skipping invalid entry "${name}" in ${filePath}`);
             }
         }
-        return entries.length > 0 ? { entries } : null;
+        return { status: "valid", stash: { entries }, complete };
     }
     catch {
-        return null;
+        return { status: "invalid" };
     }
 }
+export function readLegacyStashOverrides(dirPath, options) {
+    const result = inspectLegacyStashOverrides(dirPath, options);
+    return result.status === "valid" && result.stash.entries.length > 0 ? result.stash : null;
+}
 /** Write a legacy metadata sidecar (test/migrator fixtures). Was `writeStashFile`. */
 export function writeLegacyStashFile(dirPath, stash) {
     const filePath = legacyStashFilePath(dirPath);

package/dist/migrate/legacy/task-target-ref-migration.js

@@ -97,11 +97,14 @@ function resolveOrigin(origin, bundles, filePath) {
         throw migrationError(filePath, `legacy workflow origin "${origin}" did not resolve.`);
     return candidate;
 }
-function assertWorkflowExists(bundle, name, rawRef, filePath) {
+function assertWorkflowPathSafe(bundle, name, rawRef, filePath) {
     const candidate = resolveAssetPathFromName("workflow", path.join(bundle.root, "workflows"), name);
-    if (!fs.existsSync(candidate) || !fs.statSync(candidate).isFile()) {
-        throw migrationError(filePath, `legacy target "${rawRef}" was not found in bundle "${bundle.id}" at ${bundle.root}.`);
-    }
+    // A stale task is valid persisted state. Rewrite its deterministic ref and let
+    // task sync/run continue to report the missing workflow per task.
+    if (!fs.existsSync(candidate))
+        return;
+    if (!fs.statSync(candidate).isFile())
+        throw migrationError(filePath, `legacy target "${rawRef}" is not a file in bundle "${bundle.id}".`);
     const realRoot = fs.realpathSync(bundle.root);
     const realCandidate = fs.realpathSync(candidate);
     const relative = path.relative(realRoot, realCandidate);
@@ -120,7 +123,10 @@ function renderScalarLike(sourceToken, replacement, filePath) {
     }
     if (sourceToken.startsWith('"') && sourceToken.endsWith('"'))
         return JSON.stringify(replacement);
-    if (/^[^\s#[\]{},&*!|>'"%@`]+$/.test(sourceToken))
+    // parseDocument already proved this source range is one valid string scalar.
+    // Canonical replacements contain only slug/path characters, so any one-line
+    // plain legacy scalar can be replaced plainly even when its origin had @/#.
+    if (!sourceToken.includes("\n") && !sourceToken.includes("\r"))
         return replacement;
     throw migrationError(filePath, "the legacy workflow target uses an unsupported YAML scalar style.");
 }
@@ -165,7 +171,7 @@ function planTaskFile(filePath, containing, bundles, durabilityPaths) {
     }
     const name = canonicalizeWorkflowName(parsed.name);
     const targetBundle = parsed.origin ? resolveOrigin(parsed.origin, bundles, filePath) : containing;
-    assertWorkflowExists(targetBundle, name, from, filePath);
+    assertWorkflowPathSafe(targetBundle, name, from, filePath);
     const conceptId = legacyConceptId("workflow", name);
     const to = parsed.origin ? `${targetBundle.id}//${conceptId}` : conceptId;
     const range = node.range;

package/dist/migrate/legacy/three-db-cutover.js

@@ -137,7 +137,9 @@ function addIndexEntryMappings(map, row, stashRoots) {
  */
 function walkLegacyLayoutInto(map, root) {
     let bundle;
-    if (root.registryId && root.registryId.length > 0)
+    if (root.bundleId && root.bundleId.length > 0)
+        bundle = root.bundleId;
+    else if (root.registryId && root.registryId.length > 0)
         bundle = root.registryId;
     else if (root.primary)
         bundle = basenameSlug(root.path);
@@ -157,8 +159,6 @@ function walkLegacyLayoutInto(map, root) {
             if (name === undefined)
                 continue;
             const bareTail = `${type}:${name}`;
-            if (map.has(bareTail))
-                continue; // source (a) already covers it
             const conceptId = `${dirName}/${name}`;
             const itemRef = `${bundle}//${conceptId}`;
             setMapping(map, bareTail, itemRef);
@@ -613,6 +613,11 @@ export function runThreeDbCutover(opts) {
             db.exec(`ATTACH DATABASE '${sqliteQuote(opts.workflowPath)}' AS wf`);
         if (oldIndexExists)
             db.exec(`ATTACH DATABASE '${sqliteQuote(opts.oldIndexPath)}' AS oldidx`);
+        if (process.env.AKM_TEST_MIGRATION_CRASH_GAP === "cutover-attach") {
+            if (workflowExists)
+                db.prepare("SELECT COUNT(*) FROM wf.sqlite_master").get();
+            process.kill(process.pid, "SIGKILL");
+        }
         let rekey = emptyReport();
         try {
             db.exec("BEGIN IMMEDIATE");
@@ -807,23 +812,22 @@ export function quarantineIndexDb(runId, indexPath) {
 /**
  * Journaled, idempotent unlink of workflow.db + its `-wal`/`-shm` sidecars, keyed
  * on the committed cutover marker (the caller passes it only once the merge has
- * committed). Best-effort: a failure is logged, never thrown.
+ * committed). A failure throws so the operation-bound journal remains available
+ * and the same cutover operation retries this boundary step.
  */
 export function deleteWorkflowDb(workflowPath) {
+    if (process.env.AKM_TEST_MIGRATION_FAIL_WORKFLOW_DELETE === "1") {
+        throw new Error("injected workflow.db unlink failure");
+    }
     let deleted = false;
-    try {
-        for (const suffix of ["-shm", "-wal", ""]) {
-            const target = `${workflowPath}${suffix}`;
-            if (fs.existsSync(target)) {
-                fs.rmSync(target, { force: true });
-                if (suffix === "")
-                    deleted = true;
-            }
+    for (const suffix of ["-shm", "-wal", ""]) {
+        const target = `${workflowPath}${suffix}`;
+        if (fs.existsSync(target)) {
+            fs.rmSync(target, { force: true });
+            if (suffix === "")
+                deleted = true;
         }
     }
-    catch (error) {
-        warn(`[akm] three-DB cutover: workflow.db unlink failed (${error instanceof Error ? error.message : String(error)}); it is retried on the next migrate apply.`);
-    }
     return { deleted };
 }
 // ═══════════════════════════════════════════════════════════════════════

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.9.0-rc.8",
+  "version": "0.9.0-rc.9",
   "type": "module",
   "description": "akm (Agent Knowledge Management) — A package manager for AI agent skills, commands, tools, and knowledge. Works with Claude Code, OpenCode, Cursor, and any AI coding assistant.",
   "keywords": [