akm-cli 0.9.6 → 0.9.8-beta.1

package/dist/commands/lint/base-linter.js

@@ -34,11 +34,12 @@
 import fs from "node:fs";
 import path from "node:path";
 import { isScalar, parseDocument } from "yaml";
-import { assetPathForName, stashDirFor } from "../../core/asset/asset-placement.js";
+import { assetPathCandidatesForName, assetPathForName, stashDirFor } from "../../core/asset/asset-placement.js";
 import { BUNDLE_REF_RE } from "../../core/asset/asset-ref.js";
-import { spliceFrontmatterLine } from "../../core/asset/frontmatter.js";
+import { removeFrontmatterListValues, rewriteFrontmatterListValue, spliceFrontmatterLine, } from "../../core/asset/frontmatter.js";
 import { checkUnquotedDescriptionColon } from "../../core/asset/frontmatter-lint.js";
-import { typeNameFromConceptId } from "../../core/asset/resolve-ref.js";
+import { isArchivedRelPath } from "../../core/asset/memory-archive.js";
+import { conceptIdFromTypeName, typeNameFromConceptId } from "../../core/asset/resolve-ref.js";
 import { localDateStamp } from "../../core/common.js";
 import { findFenceRegions } from "./markdown-insertion.js";
 // ── Helpers ───────────────────────────────────────────────────────────────────
@@ -191,6 +192,37 @@ export function refExistsInAnyStash(relPath, refType, refName, stashRoots) {
         if (resolveRefPathInStash(relPath, refType, refName, root) !== null)
             return true;
     }
+    // #884: a memory pruned by `analyzeMemoryCleanup` was ARCHIVED, not deleted —
+    // its bytes and identity live on under `.akm/memory-cleanup/archive`. Inbound
+    // belief edges to it are satisfied, not dangling, so resolve the tombstone
+    // rather than reporting `missing-ref`. Checked only after every live location
+    // misses: a tombstone must never shadow a real file, and the scan then costs
+    // one directory read per root instead of one per ref.
+    //
+    // Existence ONLY. `resolveRefPathInStash` deliberately does NOT consult the
+    // archive: it hands back a path callers MUTATE (SPEC-5 `--supersedes`
+    // demotion), and writing into an archived tombstone would corrupt the audit
+    // record while leaving the live stash untouched.
+    return memoryArchiveHasRef(refType, refName, stashRoots);
+}
+/**
+ * True when `(refType, refName)` names a memory that prune archived in any
+ * root. Mirrors `resolveRefPathInStash`'s candidate set so a ref that resolved
+ * through the `.derived.md` twin (#882) still resolves once archived.
+ */
+function memoryArchiveHasRef(refType, refName, stashRoots) {
+    if (refType !== "memory")
+        return false; // only memories are ever archived
+    const typeDir = stashDirFor(refType);
+    if (typeDir === undefined)
+        return false;
+    const candidates = assetPathCandidatesForName(refType, typeDir, refName);
+    for (const root of stashRoots) {
+        for (const candidate of candidates) {
+            if (isArchivedRelPath(candidate, root))
+                return true;
+        }
+    }
     return false;
 }
 /**
@@ -198,8 +230,9 @@ export function refExistsInAnyStash(relPath, refType, refName, stashRoots) {
  * the same reachability rules (in the same order) as
  * {@link refExistsInAnyStash}, which delegates here. Returns the absolute path
  * of the file that makes the ref "exist" — for a multi-file skill directory
- * that is its `SKILL.md` primary — or `null` when the ref does not resolve in
- * this root.
+ * that is its `SKILL.md` primary, for a `memory` ref its `.derived.md` twin
+ * when the plain `.md` is absent (#882, see `assetPathCandidatesForName`) —
+ * or `null` when the ref does not resolve in this root.
  *
  * Extracted for SPEC-5 (`--supersedes` demotion): write commands need the
  * superseded asset's actual file to mutate, and forking a second resolver
@@ -207,10 +240,14 @@ export function refExistsInAnyStash(relPath, refType, refName, stashRoots) {
  * (the contract pins `refToRelPath` + `refExistsInAnyStash`; this is the
  * shared internal both build on).
  */
-export function resolveRefPathInStash(relPath, _refType, _refName, root) {
-    const absPath = path.join(root, relPath);
-    if (fs.existsSync(absPath))
-        return absPath;
+export function resolveRefPathInStash(relPath, refType, refName, root) {
+    const typeDir = stashDirFor(refType);
+    const candidates = typeDir === undefined ? [relPath] : assetPathCandidatesForName(refType, typeDir, refName);
+    for (const candidate of candidates) {
+        const absPath = path.join(root, candidate);
+        if (fs.existsSync(absPath))
+            return absPath;
+    }
     return null;
 }
 /**
@@ -281,11 +318,31 @@ function scanBundleRefs(scanBody, allRoots) {
  */
 function classifyConceptRef(rawConceptId, allRoots) {
     const conceptId = rawConceptId.split("#", 1)[0];
-    const parts = typeNameFromConceptId(conceptId);
+    const parts = typeNameFromConceptId(conceptId) ?? legacyTypeSlugParts(conceptId);
     if (parts === undefined)
         return null; // foreign type / not a local asset ref
     return localRefMissingRelPath(parts.type, parts.name, allRoots);
 }
+/**
+ * Read-only fallback for the retired `type:slug` xref grammar (see
+ * resolve-ref.ts Q-02 — the write boundary no longer emits or accepts it).
+ * Stash content written before that retirement still carries it in frontmatter
+ * `xrefs:` lists, and `typeNameFromConceptId` (conceptId-only) returns
+ * `undefined` for it, so without this it was silently skipped rather than
+ * validated (#882). `refToRelPath`/`refExistsInAnyStash` already key off a bare
+ * `(type, slug)` pair — the same shape `type:slug` already is — so this only
+ * needs to split the token; no new resolution logic.
+ */
+function legacyTypeSlugParts(rawConceptId) {
+    const colon = rawConceptId.indexOf(":");
+    if (colon <= 0)
+        return undefined;
+    const type = rawConceptId.slice(0, colon);
+    const name = rawConceptId.slice(colon + 1);
+    if (!name || name.includes("/") || name.includes(":"))
+        return undefined;
+    return stashDirFor(type) === undefined ? undefined : { type, name };
+}
 /**
  * Returns an array of {ref, resolvedRelPath} for every local AKM ref in the
  * PROSE body that does not resolve to a real file under any of the provided
@@ -364,6 +421,12 @@ function dedupeMissing(rows) {
  * excluded because it can point at merged-away or pruned assets.
  */
 const XREF_FRONTMATTER_KEYS = ["xrefs", "supersededBy", "contradictedBy"];
+/**
+ * The belief-graph subset of {@link XREF_FRONTMATTER_KEYS} — the only channels
+ * `--prune-dangling-edges` will repair (#884). Typed as `readonly string[]` so
+ * `.includes` accepts any xref key without a cast.
+ */
+const BELIEF_EDGE_KEYS = ["supersededBy", "contradictedBy"];
 /**
  * Return the `refs:` array from frontmatter when it is present and is an
  * array of strings; otherwise return `null` to signal the caller should
@@ -597,12 +660,22 @@ export function runBaseChecks(ctx) {
             });
         }
     }
-    if (modified) {
-        // Mirrors the two stub-delete call sites in `commands/lint/index.ts`
-        // (`appendMemoryStubIssue`/`appendWorkflowStubIssue`), which already report
-        // a failed mutation as `fixed: "failed"` instead of throwing. Without this
-        // the sweep aborted mid-run on the first unwritable file and the caller got
-        // an exception instead of a result naming the fixes that HAD landed.
+    /**
+     * Flush accumulated mutations to disk. Called after the fixable checks above
+     * AND again at the very end, because the `missing-ref` section below can also
+     * mutate (`--prune-dangling-edges`, #884) and used to run PAST this point —
+     * its edits were computed and then silently dropped.
+     *
+     * Mirrors the two stub-delete call sites in `commands/lint/index.ts`
+     * (`appendMemoryStubIssue`/`appendWorkflowStubIssue`), which already report
+     * a failed mutation as `fixed: "failed"` instead of throwing. Without this
+     * the sweep aborted mid-run on the first unwritable file and the caller got
+     * an exception instead of a result naming the fixes that HAD landed.
+     */
+    const flushIfModified = () => {
+        if (!modified)
+            return;
+        modified = false;
         try {
             fs.writeFileSync(ctx.filePath, currentRaw, "utf8");
             // Propagate the mutated raw back so subclasses can re-parse if needed
@@ -615,7 +688,8 @@ export function runBaseChecks(ctx) {
                 issue.detail = `${issue.detail} — could not write fix: ${reason}`;
             }
         }
-    }
+    };
+    flushIfModified();
     // ── 3. stale-path ──────────────────────────────────────────────────────
     // M3: checkStalePath returns all stale matches; push one issue per path.
     // M4: Also scan ctx.frontmatter for stale paths (absolute paths in frontmatter).
@@ -636,6 +710,26 @@ export function runBaseChecks(ctx) {
         }
     }
     // ── 4. missing-ref ─────────────────────────────────────────────────────
+    const missingRefPass = runMissingRefChecks(ctx, currentRaw, shouldRun, pendingFixes);
+    issues.push(...missingRefPass.issues);
+    if (missingRefPass.modified) {
+        currentRaw = missingRefPass.raw;
+        modified = true;
+    }
+    flushIfModified();
+    return issues;
+}
+/**
+ * The `missing-ref` pass, extracted from {@link runBaseChecks} so that function
+ * stays under the src fn-size ratchet after #884 gave this pass its own
+ * (opt-in) mutation path. Pure move plus the explicit state hand-off: `raw` in,
+ * `{raw, modified}` out, `issues`/`pendingFixes` appended in place.
+ */
+function runMissingRefChecks(ctx, raw, shouldRun, pendingFixes) {
+    const issues = [];
+    let currentRaw = raw;
+    let modified = false;
+    // ── 4. missing-ref ─────────────────────────────────────────────────────
     // Carve-out for assets that declare an explicit `refs:` array in
     // frontmatter (e.g. session-checkpoint memories captured by the
     // claude-code hook). The frontmatter array is the *authoritative*
@@ -650,7 +744,9 @@ export function runBaseChecks(ctx) {
     // still run `checkMissingRefs` against the array itself to catch
     // refs that were valid at capture time but later removed from the
     // stash.
-    if (shouldRun("missing-ref")) {
+    if (!shouldRun("missing-ref"))
+        return { issues, raw, modified };
+    {
         const explicitRefs = extractFrontmatterRefs(ctx.data, ctx.body);
         // An explicit `refs:` array is a REF LIST (each value is a whole ref —
         // short conceptIds included); a bare body is PROSE (anchored refs only).
@@ -690,7 +786,74 @@ export function runBaseChecks(ctx) {
                 const values = readRefStringOrArray(ctx.data?.[key]);
                 if (values === null)
                     continue;
+                // `lint --fix` migration for the retired `type:slug` xref grammar
+                // (see legacyTypeSlugParts): rewrite a value to its conceptId form
+                // ONLY when the rewritten spelling still resolves to a real asset —
+                // a dangling legacy ref must stay reported as `missing-ref` in its
+                // original spelling, never rewritten into a differently-spelled
+                // dangling ref. Runs before the missing-ref scan below so a value
+                // this loop rewrites is checked (and reported, if still dangling)
+                // under its ORIGINAL spelling by that scan, and never double-fixed.
+                if (ctx.fix) {
+                    const legacyRewrites = new Map();
+                    for (const raw of values) {
+                        const value = raw.trim();
+                        const parts = legacyTypeSlugParts(value);
+                        if (parts === undefined)
+                            continue;
+                        const relPath = refToRelPath(parts.type, parts.name);
+                        if (relPath === null)
+                            continue;
+                        if (!refExistsInAnyStash(relPath, parts.type, parts.name, [ctx.stashRoot, ...(ctx.extraStashRoots ?? [])]))
+                            continue; // dangling — leave reported as missing-ref, unrewritten
+                        legacyRewrites.set(value, conceptIdFromTypeName(parts.type, parts.name));
+                    }
+                    if (legacyRewrites.size > 0) {
+                        const rewritten = rewriteFrontmatterListValue(currentRaw, key, legacyRewrites);
+                        if (rewritten !== null) {
+                            currentRaw = rewritten;
+                            modified = true;
+                            for (const [oldValue, newValue] of legacyRewrites) {
+                                const issue = {
+                                    file: ctx.relPath,
+                                    issue: "missing-ref",
+                                    detail: `legacy xref grammar migrated: ${key} ${oldValue} -> ${newValue}`,
+                                    fixed: true,
+                                };
+                                issues.push(issue);
+                                pendingFixes.push(issue);
+                            }
+                        }
+                    }
+                }
                 const missingXrefs = checkMissingRefsInList(values, ctx.stashRoot, ctx.extraStashRoots);
+                // #884 opt-in repair. Scoped to the BELIEF channels only: an edge whose
+                // target has neither a file nor a prune tombstone asserts a
+                // relationship to a memory that no longer exists in any form, and
+                // carrying it forward corrupts every belief-graph read. `xrefs` is
+                // excluded — a stale xref is an ordinary broken link (the 3 skill refs
+                // in #884), and repairing it by DELETION would throw away a pointer the
+                // author may simply need to re-target.
+                const repairable = ctx.pruneDanglingEdges === true && BELIEF_EDGE_KEYS.includes(key) && missingXrefs.length > 0;
+                if (repairable) {
+                    const dropped = missingXrefs.map(({ ref }) => ref);
+                    const rewritten = removeFrontmatterListValues(currentRaw, key, dropped);
+                    if (rewritten !== null) {
+                        currentRaw = rewritten;
+                        modified = true;
+                        for (const { ref, resolvedRelPath } of missingXrefs) {
+                            const issue = {
+                                file: ctx.relPath,
+                                issue: "missing-ref",
+                                detail: `dangling ${key} edge dropped: ${ref} (no file and no prune tombstone at ${resolvedRelPath})`,
+                                fixed: true,
+                            };
+                            issues.push(issue);
+                            pendingFixes.push(issue);
+                        }
+                        continue;
+                    }
+                }
                 for (const { ref, resolvedRelPath } of missingXrefs) {
                     issues.push({
                         file: ctx.relPath,
@@ -702,5 +865,5 @@ export function runBaseChecks(ctx) {
             }
         }
     }
-    return issues;
+    return { issues, raw: currentRaw, modified };
 }

package/dist/commands/lint/index.js

@@ -11,14 +11,13 @@ import { stashDirFor } from "../../core/asset/asset-placement.js";
 import { parseFrontmatter } from "../../core/asset/frontmatter.js";
 import { conceptIdForStashFile, displayRefForConceptId } from "../../core/asset/resolve-ref.js";
 import { deriveBundleIds } from "../../core/bundle-id.js";
-import { isAkmRegistryCachePath, resolveStashDir } from "../../core/common.js";
+import { compareCodePoints, isAkmRegistryCachePath, resolveStashDir } from "../../core/common.js";
 import { loadConfig, primaryBundlePath } from "../../core/config/config.js";
 import { UsageError } from "../../core/errors.js";
 import { warn } from "../../core/warn.js";
 import { resolveSourceEntries } from "../../indexer/search/search-source.js";
 import { TASK_EXTENSION, TASK_NEAR_MISS_EXTENSION, taskExtensionDetail } from "../../tasks/source-v3.js";
 import { resolveWorkflowSourceDomains } from "../../workflows/source-files.js";
-import { compareWorkflowSourceCodePoints } from "../../workflows/source-ir/compare.js";
 import { runBaseChecks } from "./base-linter.js";
 import { checkEnvForDangerousKeys } from "./env-key-rules.js";
 import { isAdvisoryLintIssue } from "./types.js";
@@ -87,7 +86,7 @@ function collectWorkflowFiles(dir) {
     const results = [];
     for (const entry of fs
         .readdirSync(dir, { withFileTypes: true })
-        .sort((left, right) => compareWorkflowSourceCodePoints(left.name, right.name))) {
+        .sort((left, right) => compareCodePoints(left.name, right.name))) {
         if (entry.name === ".git")
             continue;
         const full = path.join(dir, entry.name);
@@ -103,7 +102,7 @@ function collectWorkflowFiles(dir) {
         if (extension === ".md" || extension === ".yml")
             results.push(full);
     }
-    return results.sort(compareWorkflowSourceCodePoints);
+    return results.sort(compareCodePoints);
 }
 /**
  * Resolve the already-enumerated candidates through the same workflow-source
@@ -131,7 +130,7 @@ function resolveWorkflowLintOwnership(stashRoot, files) {
             fixed: false,
         });
     }
-    return { files: ownedFiles.sort(compareWorkflowSourceCodePoints), issues };
+    return { files: ownedFiles.sort(compareCodePoints), issues };
 }
 // ── Non-akm adapter dispatch (real `adapter.validate()`, not a re-implementation) ──
 //
@@ -385,8 +384,8 @@ function assertFixTargetWritable(stashRoot, sources) {
         return;
     // Same error kind and code `write-source.ts#ensureWritable` raises for the
     // identical refusal, so a scripted caller classifies both the same way.
-    throw new UsageError(`lint --fix: bundle "${stashRoot}" is configured \`writable: false\`; refusing to modify it. ` +
-        "Run `akm lint` without --fix to report findings, or set `writable: true` on the bundle.", "INVALID_FLAG_VALUE");
+    throw new UsageError(`lint: bundle "${stashRoot}" is configured \`writable: false\`; refusing to modify it. ` +
+        "Run `akm lint` without --fix / --prune-dangling-edges to report findings, or set `writable: true` on the bundle.", "INVALID_FLAG_VALUE");
 }
 /** True when the issue represents a file deletion that was successfully applied. */
 function isFileDeletion(issue) {
@@ -523,7 +522,9 @@ export function lintAssetFile(ctx, subdir) {
  */
 function lintAkmSweep(stashRoot, extraStashRoots, cfg, sources, options) {
     const fix = options.fix === true;
-    if (fix)
+    // #884: the dangling-edge repair writes too, so it clears the same
+    // read-only gate `--fix` does.
+    if (fix || options.pruneDanglingEdges === true)
         assertFixTargetWritable(stashRoot, sources);
     const fixed = [];
     const flagged = [];
@@ -627,7 +628,18 @@ function lintAkmSweep(stashRoot, extraStashRoots, cfg, sources, options) {
             try {
                 issues = [
                     ...fileIssues,
-                    ...lintAssetFile({ filePath, relPath, raw, data, body, frontmatter, fix, stashRoot, extraStashRoots }, subdir),
+                    ...lintAssetFile({
+                        filePath,
+                        relPath,
+                        raw,
+                        data,
+                        body,
+                        frontmatter,
+                        fix,
+                        pruneDanglingEdges: options.pruneDanglingEdges === true,
+                        stashRoot,
+                        extraStashRoots,
+                    }, subdir),
                 ];
             }
             catch (e) {

package/dist/commands/migrate/config-extra-params.js

@@ -0,0 +1,61 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * Legacy `extraParams` -> first-class-field lift (#852, following #815), as
+ * an `akm migrate` concern.
+ *
+ * This used to run silently, in memory, on every config load
+ * (`liftLegacyEngineExtraParams` called from `parseAndValidateConfigText`)
+ * and never wrote the result back — so the lift, and its warning, recurred
+ * forever. config.json is akm-owned plain JSON; the lift is deterministic
+ * and total, so — like the dead-residue cleanup in `./dead-residue.ts` —
+ * it belongs in `akm migrate`, run once, persisted. `parseAndValidateConfigText`
+ * now fails closed on an unmigrated config instead of lifting it.
+ */
+import { acquireConfigLock, backupExistingConfig, parseConfigText, readConfigText, writeConfigAtomic, } from "../../core/config/config-io.js";
+import { liftLegacyEngineExtraParams } from "../../core/extra-params.js";
+function readRawConfig(configPath) {
+    const text = readConfigText(configPath);
+    if (text === undefined)
+        return undefined;
+    return parseConfigText(text, configPath);
+}
+/**
+ * Read-only: what `akm migrate apply` would lift (or flag as conflicting) in
+ * `config.json`'s `extraParams`. Never touches disk. Returns an empty plan
+ * when the config file does not exist.
+ */
+export function findConfigExtraParamsLift(configPath) {
+    const raw = readRawConfig(configPath);
+    if (!raw)
+        return { lifted: [], conflicts: [] };
+    const { lifted, conflicts } = liftLegacyEngineExtraParams(raw);
+    return { lifted, conflicts };
+}
+/**
+ * Persist the legacy extraParams -> first-class field lift to `config.json`,
+ * once. Best-effort like `removeDeadResidue`: a genuine conflict (extraParams
+ * and the first-class field set to different values) is left untouched here
+ * — `parseAndValidateConfigText` already hard-rejects that config at every
+ * load with the exact mismatch, so a second, weaker error here would only be
+ * noise — and is reported back via `conflicts` instead.
+ */
+export function applyConfigExtraParamsLift(configPath) {
+    const raw = readRawConfig(configPath);
+    if (!raw)
+        return { applied: false, lifted: [], conflicts: [] };
+    const { config, lifted, conflicts } = liftLegacyEngineExtraParams(raw);
+    if (conflicts.length > 0 || lifted.length === 0) {
+        return { applied: false, lifted, conflicts };
+    }
+    const release = acquireConfigLock();
+    try {
+        backupExistingConfig(configPath);
+        writeConfigAtomic(configPath, config);
+    }
+    finally {
+        release();
+    }
+    return { applied: true, lifted, conflicts: [] };
+}

package/dist/commands/migrate/dead-residue.js

@@ -0,0 +1,113 @@
+/**
+ * Dead pre-0.9.0 `$STASH/.akm` residue: superseded filesystem layouts with no
+ * live reader or writer anywhere in src/ (each verified by grep before being
+ * listed — see #889 for the audit). The largest, `.akm/proposals/`, was
+ * replaced by the `proposals` table in state.db in 0.9.0 and measured 135 MB
+ * on a real bundle.
+ *
+ * This lives under `migrate/` because removing a superseded layout IS
+ * migration — the tail end of the moves that created these paths' replacements.
+ * It was first shipped as a bolted-on `akm health --clean-dead-residue` flag
+ * plus a health advisory; that was the wrong shape (a special-purpose switch
+ * apologizing for migrations that did not finish their own job) and was
+ * removed. `akm migrate status` reports what is here; `akm migrate apply`
+ * removes it, exactly as it applies every other pending migration.
+ */
+import fs from "node:fs";
+import path from "node:path";
+const DEAD_RESIDUE_PATHS = [
+    { name: "proposals", reason: "superseded by the `proposals` table in $DATA/state.db (0.9.0)" },
+    { prefix: "runs.archived-", reason: "orphaned archive of a directory that no longer exists" },
+    {
+        name: "archive",
+        reason: "legacy consolidation archive; current prune writes .akm/memory-cleanup/archive/ instead",
+    },
+    { name: "graph.json", reason: "superseded by the graph_* tables in $DATA/index.db" },
+    { name: "consolidate-journal.json", reason: "legacy consolidation journal; unused" },
+    { name: "proposals.db", reason: "empty legacy database file" },
+    { name: "mv-transactions", reason: "legacy fs-txn journal location; unused" },
+];
+function dirSizeBytes(target) {
+    let total = 0;
+    let entries;
+    try {
+        entries = fs.readdirSync(target, { withFileTypes: true });
+    }
+    catch {
+        return 0;
+    }
+    for (const entry of entries) {
+        const entryPath = path.join(target, entry.name);
+        if (entry.isDirectory()) {
+            total += dirSizeBytes(entryPath);
+        }
+        else if (entry.isFile()) {
+            try {
+                total += fs.statSync(entryPath).size;
+            }
+            catch {
+                // Skip files that vanish or are inaccessible between readdir and stat.
+            }
+        }
+    }
+    return total;
+}
+function sizeOf(target) {
+    const st = fs.statSync(target);
+    return st.isDirectory() ? dirSizeBytes(target) : st.size;
+}
+/**
+ * Find every Tier-1 dead-residue path that actually exists under
+ * `$STASH/.akm`, with its computed size. Read-only — never deletes.
+ */
+export function findDeadResidueEntries(stashDir) {
+    const akmDir = path.join(stashDir, ".akm");
+    let names;
+    try {
+        names = fs.readdirSync(akmDir);
+    }
+    catch {
+        return [];
+    }
+    const found = [];
+    for (const spec of DEAD_RESIDUE_PATHS) {
+        const matches = spec.name !== undefined ? [spec.name] : names.filter((n) => n.startsWith(spec.prefix ?? "\0"));
+        for (const name of matches) {
+            if (!names.includes(name))
+                continue;
+            const absolutePath = path.join(akmDir, name);
+            let sizeBytes;
+            try {
+                sizeBytes = sizeOf(absolutePath);
+            }
+            catch {
+                continue; // vanished between readdir and stat
+            }
+            found.push({ relativePath: path.join(".akm", name), absolutePath, sizeBytes, reason: spec.reason });
+        }
+    }
+    return found;
+}
+/**
+ * Delete every Tier-1 dead-residue path found under `$STASH/.akm`. Only
+ * invoked when the caller has explicitly opted in (`akm health
+ * --clean-dead-residue`) — never as a side effect of a plain `akm health`
+ * read. Best-effort per-path: one failure does not abort the rest.
+ */
+export function removeDeadResidue(stashDir) {
+    const entries = findDeadResidueEntries(stashDir);
+    return entries.map((entry) => {
+        try {
+            fs.rmSync(entry.absolutePath, { recursive: true, force: true });
+            return { relativePath: entry.relativePath, sizeBytes: entry.sizeBytes, removed: true };
+        }
+        catch (error) {
+            return {
+                relativePath: entry.relativePath,
+                sizeBytes: entry.sizeBytes,
+                removed: false,
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    });
+}

package/dist/commands/migrate/stale-txn.js

@@ -0,0 +1,49 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * Stale durable-transaction journals (`$DATA/txn/<rootNs24>/<id>/journal.json`,
+ * see `core/fs-txn.ts`) that never got recovered — a crash mid-transaction
+ * left a journal on disk with no process left to finish or roll it back.
+ * `akm health` used to only report these and point at a troubleshooting doc
+ * (issue: an advisory that tells the user to go read docs instead of the
+ * tool recovering its own interrupted state). Recovery IS a migration
+ * concern like dead `.akm/` residue: `akm migrate status` names what is
+ * here for the stash root, `akm migrate apply` recovers it, exactly like
+ * `dead-residue.ts`.
+ *
+ * Recovery goes through {@link recoverTxnsForRoot}, which requires every
+ * live kind's registrar to be IMPORTED first so its handler is registered
+ * (see fs-txn.ts's module docs). `proposal/repository.ts` registers the
+ * `proposal`/`proposal-reject` kinds specifically so "ANY recovery entry
+ * point ... can finish or roll back an interrupted proposal mutation for a
+ * root it touches" (its own comment on the registration) — this module is
+ * exactly that kind of entry point.
+ */
+import { canonicalTxnRoot, listTxnJournalsTolerant, recoverTxnsForRoot } from "../../core/fs-txn.js";
+// Side-effect import: registers the `proposal`/`proposal-reject` txn kinds
+// so recovery below can roll them forward/back for the stash root.
+import "../proposal/repository.js";
+/**
+ * Find every durable-transaction journal bound to `stashDir`'s namespace.
+ * Read-only, tolerant of a corrupt journal (counted, not thrown on) — mirrors
+ * `findDeadResidueEntries`'s read-only/never-mutates contract.
+ */
+export function findStaleTxnEntries(stashDir) {
+    const root = canonicalTxnRoot(stashDir);
+    const { matches } = listTxnJournalsTolerant((j) => canonicalTxnRoot(j.root) === root);
+    return matches.map(({ journal }) => journalToEntry(journal));
+}
+function journalToEntry(journal) {
+    return { transactionId: journal.transactionId, kind: journal.kind, phase: journal.phase, root: journal.root };
+}
+/**
+ * Recover every durable transaction bound to `stashDir`'s namespace: roll
+ * back journals before their kind's commit point, roll forward the rest.
+ * The counterpart to {@link findStaleTxnEntries}, invoked only from `akm
+ * migrate apply`.
+ */
+export async function recoverStaleTxns(stashDir) {
+    const recovered = await recoverTxnsForRoot(stashDir);
+    return recovered.map(journalToEntry);
+}

package/dist/commands/migrate-cli.js

@@ -2,6 +2,12 @@
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import { defineGroupCommand, defineJsonCommand, EXIT_CODES, output } from "../cli/shared.js";
+import { resolveStashDir } from "../core/common.js";
+import { ConfigError } from "../core/errors.js";
+import { getConfigPath } from "../core/paths.js";
+import { applyConfigExtraParamsLift, findConfigExtraParamsLift } from "./migrate/config-extra-params.js";
+import { findDeadResidueEntries, removeDeadResidue } from "./migrate/dead-residue.js";
+import { findStaleTxnEntries, recoverStaleTxns } from "./migrate/stale-txn.js";
 import { runMigrationTool } from "./migration-tool.js";
 async function callMigrateTool(args, runTool) {
     const result = await runTool(args);
@@ -79,6 +85,25 @@ export function resolveGenerationStatus(call, label) {
  * got to look at a stable tree in that case.
  */
 export async function runMigrateSubcommand(command, genOneArgs, genTwoArgs, runTool = runMigrationTool) {
+    // Superseded pre-0.9.0 .akm layouts are a migration concern like any other:
+    // status names them, apply removes them. (First shipped as a bolted-on
+    // `health --clean-dead-residue` flag; folded here where it belongs.) The
+    // legacy extraParams -> first-class-field config lift (#852) is the same
+    // shape: status names it, apply persists it once instead of the old
+    // permanent silent lift on every config load.
+    // No configured bundle means there is no stash to scan — an empty domain,
+    // not an error — so migrate still works before `akm bundle create`. Any
+    // OTHER ConfigError propagates.
+    let stashDir;
+    try {
+        stashDir = resolveStashDir();
+    }
+    catch (error) {
+        if (!(error instanceof ConfigError) || error.code !== "STASH_DIR_NOT_FOUND")
+            throw error;
+    }
+    const configPath = getConfigPath();
+    const applyResidue = command === "migrate-apply" && !genOneArgs.includes("--dry-run");
     const first = await callMigrateTool(genOneArgs, runTool);
     if (first.status !== EXIT_CODES.SUCCESS && first.status !== EXIT_CODES.GENERAL) {
         process.exitCode = first.status;
@@ -95,7 +120,23 @@ export async function runMigrateSubcommand(command, genOneArgs, genTwoArgs, runT
         return;
     }
     const combined = combineMigrationPlans(first, second);
-    output(command, combined);
+    // The stash-scoped sections need a bundle to scan; no configured bundle is
+    // an empty domain, not an error, so migrate still works before
+    // `akm bundle create`. The config lift is config-scoped and always runs.
+    const stashSections = stashDir === undefined
+        ? {}
+        : {
+            deadResidue: applyResidue
+                ? { removed: removeDeadResidue(stashDir) }
+                : { pending: findDeadResidueEntries(stashDir) },
+            staleTxns: applyResidue
+                ? { recovered: await recoverStaleTxns(stashDir) }
+                : { pending: findStaleTxnEntries(stashDir) },
+        };
+    const configExtraParams = applyResidue
+        ? applyConfigExtraParamsLift(configPath)
+        : { pending: findConfigExtraParamsLift(configPath) };
+    output(command, { ...combined, ...stashSections, configExtraParams });
     if (combined.status === "blocked")
         process.exitCode = EXIT_CODES.GENERAL;
 }