akm-cli 0.9.7 → 0.9.8-beta.1

package/dist/commands/improve/memory/memory-improve.js

@@ -9,7 +9,9 @@ import { MEMORY_ARCHIVE_REL } from "../../../core/asset/memory-archive.js";
 import { conceptIdFromTypeName } from "../../../core/asset/resolve-ref.js";
 import { asNonEmptyString, groupBy, stringArray } from "../../../core/common.js";
 import { DERIVED_SUFFIX } from "../../../core/recognition-util.js";
+import { warn } from "../../../core/warn.js";
 import { recordWrittenPath } from "../../../core/write-provenance.js";
+import { walkMarkdownFiles } from "../../../indexer/walk/walker.js";
 import { isDerivedMemory, memoryIdentityRef, parseMemoryName, resolveParentRef } from "./derived-ref.js";
 export function analyzeMemoryCleanup(stashDir, options = {}) {
     const records = collectDerivedMemories(stashDir, options.parentRef);
@@ -574,7 +576,11 @@ function collectDerivedMemories(stashDir, parentRefFilter) {
     if (!fs.existsSync(memoriesDir))
         return [];
     const records = [];
-    for (const filePath of walkMarkdownFiles(memoriesDir)) {
+    const walked = walkMarkdownFiles(memoriesDir);
+    if (!walked.complete) {
+        warn(`memory improve: directory scan under ${memoriesDir} is incomplete — some derived memories may be missing`);
+    }
+    for (const filePath of walked.files) {
         const name = toMemoryName(memoriesDir, filePath);
         if (!name)
             continue;
@@ -778,24 +784,6 @@ function firstNonEmpty(values) {
     }
     return undefined;
 }
-function* walkMarkdownFiles(root) {
-    let entries;
-    try {
-        entries = fs.readdirSync(root, { withFileTypes: true });
-    }
-    catch {
-        return;
-    }
-    for (const entry of entries) {
-        const full = path.join(root, entry.name);
-        if (entry.isDirectory()) {
-            yield* walkMarkdownFiles(full);
-        }
-        else if (entry.isFile() && entry.name.toLowerCase().endsWith(".md")) {
-            yield full;
-        }
-    }
-}
 function toMemoryName(memoriesDir, filePath) {
     const rel = path.relative(memoriesDir, filePath);
     if (!rel || rel.startsWith(".."))

package/dist/commands/improve/preparation.js

@@ -789,6 +789,14 @@ export async function runImprovePreparationStage(args) {
         snapshot,
         persist: !planOnly,
     });
+    const eligibilitySourceByRef = stampEligibilitySource({
+        scope,
+        processableRefs: gathered.processableRefs,
+        mergedRefs: gathered.mergedRefs,
+        signalFiltered: gathered.signalFiltered,
+        proactiveRefs: gathered.proactiveRefs,
+        highSalienceRefs: gathered.highSalienceRefs,
+    });
     // Shared admission boundary for every synthetic fallback lane. Cleanup and
     // structural validation are exclusive selectors: no later rank/replay state
     // may re-create a candidate they removed. Keep the exact surviving objects
@@ -800,7 +808,7 @@ export async function runImprovePreparationStage(args) {
         primaryStashDir,
         eventsCtx,
         mergedRefs: gathered.mergedRefs,
-        eligibilitySourceByRef: gathered.eligibilitySourceByRef,
+        eligibilitySourceByRef,
         feedbackSummary: gathered.feedbackSummary,
         retrievalCounts: gathered.retrievalCounts,
         signalFiltered: gathered.signalFiltered,
@@ -820,7 +828,7 @@ export async function runImprovePreparationStage(args) {
         eventsCtx,
         mergedRefs: scored.mergedRefs,
         salienceMap: scored.salienceMap,
-        eligibilitySourceByRef: gathered.eligibilitySourceByRef,
+        eligibilitySourceByRef,
         distillOnlyRefs: gathered.distillOnlyRefs,
         validationFailureRefs,
         summary: {
@@ -1054,7 +1062,9 @@ export function buildSnapshotManifest(args) {
 /**
  * Pass: candidate-gather — the signal-delta partition, the bulk feedback
  * summary, retrieval signals, the Layer-2 proactive and Layer-3 high-salience
- * rescue lanes, the merged candidate set, and lane attribution stamping.
+ * rescue lanes, and the merged candidate set. Lane attribution stamping is a
+ * separate pass — see `stampEligibilitySource` — run by the caller once
+ * `mergedRefs` is known.
  */
 function gatherCandidates(args) {
     const { scope, options, primaryStashDir, eventsCtx, improveProfile, resolvedPlan, postCleanupRefs, persist } = args;
@@ -1152,23 +1162,44 @@ function gatherCandidates(args) {
     // that want feedback-only runs.
     const signalAndRetrievalRefs = dedupeRefs([...signalFiltered, ...proactiveRefs, ...highSalienceRefs]);
     const mergedRefs = scope.mode === "ref" ? processableRefs : options.requireFeedbackSignal ? signalFiltered : signalAndRetrievalRefs;
-    // ── Attribution tagging: stamp each ref with the eligibility lane that
-    // selected it ──────────────────────────────────────────────────────────────
-    // Every reflect/distill proposal must record WHICH lane chose its source asset
-    // so downstream accept/reject/revert/retrieval outcomes can be sliced by lane
-    // (does the PROACTIVE lane produce value vs the reactive lanes?). We build the
-    // lane map here — the one place all three lanes are known — and stamp it onto
-    // each ImproveEligibleRef object. Because the ref objects are shared by
-    // reference across buckets, the stamp travels with the ref through the sort,
-    // disk-check, and loop stages down to the reflect/distill event emit sites and
-    // createProposal calls. See EligibilitySource for the lane vocabulary.
-    //
-    // Precedence (prefer the most specific reactive signal):
-    //   scope > signal-delta > proactive > high-salience
-    // A ref with real feedback is attributed to feedback even if it was also due
-    // for proactive maintenance or had high encoding salience. We apply lanes
-    // weakest-first so the strongest overwrites; the explicit --scope <ref> bypass
-    // wins outright (user intent).
+    return {
+        distillCooledRefs,
+        preCooldownCount,
+        distillOnlyRefs,
+        feedbackSummary,
+        signalFiltered,
+        signalBearingSet,
+        retrievalCounts,
+        proactiveRefs,
+        proactiveMaintenanceSummary,
+        proactivePlan: proactive.proactivePlan,
+        highSalienceRefs,
+        signalAndRetrievalRefs,
+        mergedRefs,
+        processableRefs,
+    };
+}
+/**
+ * Attribution tagging: stamp each ref with the eligibility lane that selected
+ * it. Every reflect/distill proposal must record WHICH lane chose its source
+ * asset so downstream accept/reject/revert/retrieval outcomes can be sliced by
+ * lane (does the PROACTIVE lane produce value vs the reactive lanes?). We
+ * build the lane map here — the one place all three lanes are known — and
+ * stamp it onto each ImproveEligibleRef object. Because the ref objects are
+ * shared by reference across buckets, the stamp travels with the ref through
+ * the sort, disk-check, and loop stages down to the reflect/distill event
+ * emit sites and createProposal calls. See EligibilitySource for the lane
+ * vocabulary.
+ *
+ * Precedence (prefer the most specific reactive signal):
+ *   scope > signal-delta > proactive > high-salience
+ * A ref with real feedback is attributed to feedback even if it was also due
+ * for proactive maintenance or had high encoding salience. We apply lanes
+ * weakest-first so the strongest overwrites; the explicit --scope <ref> bypass
+ * wins outright (user intent).
+ */
+function stampEligibilitySource(args) {
+    const { scope, processableRefs, mergedRefs, signalFiltered, proactiveRefs, highSalienceRefs } = args;
     const eligibilitySourceByRef = new Map();
     for (const r of highSalienceRefs)
         eligibilitySourceByRef.set(r.ref, "high-salience");
@@ -1188,22 +1219,7 @@ function gatherCandidates(args) {
         // mergedRefs is always a subset of the four lanes above).
         r.eligibilitySource = eligibilitySourceByRef.get(r.ref) ?? "unknown";
     }
-    return {
-        distillCooledRefs,
-        preCooldownCount,
-        distillOnlyRefs,
-        feedbackSummary,
-        signalFiltered,
-        signalBearingSet,
-        retrievalCounts,
-        proactiveRefs,
-        proactiveMaintenanceSummary,
-        proactivePlan: proactive.proactivePlan,
-        highSalienceRefs,
-        signalAndRetrievalRefs,
-        mergedRefs,
-        eligibilitySourceByRef,
-    };
+    return eligibilitySourceByRef;
 }
 /**
  * The signal-delta partition of postCleanupRefs into the four buckets (pass:

package/dist/commands/improve/reflect.js

@@ -133,27 +133,23 @@ export const REFLECT_ALLOWED_TYPES = new Set([
 const PROTECTED_FRONTMATTER_FIELDS = new Set(["name", "ref", "id", "slug", "type"]);
 /**
  * Read the last 1–3 archived rejected proposals for a given ref from the
- * proposal store. Best-effort — returns `[]` when the proposals dir is absent
- * or the ref is undefined. Used to inject Reflexion-style verbal-RL context
- * into the reflect prompt so the agent avoids re-proposing already-refused
- * content (arXiv:2303.11366).
+ * proposal store. Returns `[]` when the proposals store is absent (not yet
+ * created) or the ref is undefined — `listProposalsReadOnly` already handles
+ * that case; a genuine read failure propagates instead of being swallowed,
+ * since silently dropping this Reflexion-style context risks re-proposing
+ * content that was already rejected (arXiv:2303.11366).
  */
 function readRejectedProposals(stash, ref, proposalsCtx) {
     if (!ref)
         return [];
-    try {
-        return listProposalsReadOnly(stash, { ref, status: "rejected", includeArchive: true }, proposalsCtx)
-            .sort((a, b) => new Date(b.updatedAt ?? 0).getTime() - new Date(a.updatedAt ?? 0).getTime())
-            .slice(0, MAX_REJECTED_PROPOSALS)
-            .map((p) => ({
-            ref: p.ref,
-            reason: p.review?.reason ?? "no reason given",
-            contentPreview: proposalContent(p).slice(0, 500),
-        }));
-    }
-    catch {
-        return [];
-    }
+    return listProposalsReadOnly(stash, { ref, status: "rejected", includeArchive: true }, proposalsCtx)
+        .sort((a, b) => new Date(b.updatedAt ?? 0).getTime() - new Date(a.updatedAt ?? 0).getTime())
+        .slice(0, MAX_REJECTED_PROPOSALS)
+        .map((p) => ({
+        ref: p.ref,
+        reason: p.review?.reason ?? "no reason given",
+        contentPreview: proposalContent(p).slice(0, 500),
+    }));
 }
 /**
  * Synthesize a tmp draft-file path for the agent/sdk file-write contract.

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

@@ -36,10 +36,10 @@ import path from "node:path";
 import { isScalar, parseDocument } from "yaml";
 import { assetPathCandidatesForName, assetPathForName, stashDirFor } from "../../core/asset/asset-placement.js";
 import { BUNDLE_REF_RE } from "../../core/asset/asset-ref.js";
-import { removeFrontmatterListValues, spliceFrontmatterLine } from "../../core/asset/frontmatter.js";
+import { removeFrontmatterListValues, rewriteFrontmatterListValue, spliceFrontmatterLine, } from "../../core/asset/frontmatter.js";
 import { checkUnquotedDescriptionColon } from "../../core/asset/frontmatter-lint.js";
 import { isArchivedRelPath } from "../../core/asset/memory-archive.js";
-import { typeNameFromConceptId } from "../../core/asset/resolve-ref.js";
+import { conceptIdFromTypeName, typeNameFromConceptId } from "../../core/asset/resolve-ref.js";
 import { localDateStamp } from "../../core/common.js";
 import { findFenceRegions } from "./markdown-insertion.js";
 // ── Helpers ───────────────────────────────────────────────────────────────────
@@ -786,6 +786,46 @@ function runMissingRefChecks(ctx, raw, shouldRun, pendingFixes) {
                 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

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) ──
 //

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;
 }

package/dist/commands/proposal/proposal.js

@@ -15,7 +15,7 @@ import { resolveStashDir } from "../../core/common.js";
 import { loadConfig } from "../../core/config/config.js";
 import { resolveWriteTarget } from "../../core/write-source.js";
 import { withAssetMutationLease } from "../../indexer/index-writer-lock.js";
-import { createProposal, diffProposal, isProposalSkipped, listProposals, preflightProposalPromotion, promoteProposal, proposalContent, recoverProposalTransactionsForStash, rejectProposalDurably, resolveProposalId, revertProposal, } from "./repository.js";
+import { diffProposal, listProposals, preflightProposalPromotion, promoteProposal, proposalContent, recoverProposalTransactionsForStash, rejectProposalDurably, resolveProposalId, revertProposal, } from "./repository.js";
 import { validateProposal } from "./validators/proposals.js";
 // ── Shared helpers ──────────────────────────────────────────────────────────
 function resolveStash(stashDir) {
@@ -131,26 +131,6 @@ export function akmProposalDiff(options) {
         ...(diff.targetPath ? { targetPath: diff.targetPath } : {}),
     };
 }
-export function akmProposalCreate(options) {
-    const queue = resolveProposalQueue(options.stashDir, options.queue, options.config);
-    const stash = queue.stashDir;
-    const target = options.target ?? (queue.target ? { source: queue.target.source.name, root: queue.target.source.path } : undefined);
-    // Manual proposal creation (via `akm proposal create`) always bypasses
-    // dedup/cooldown guards — the operator is explicitly requesting a proposal.
-    const result = createProposal(stash, {
-        ref: options.ref,
-        source: options.source,
-        ...(target !== undefined ? { target } : {}),
-        ...(options.sourceRun !== undefined ? { sourceRun: options.sourceRun } : {}),
-        payload: options.payload,
-        force: true,
-    }, options.ctx);
-    if (isProposalSkipped(result)) {
-        // Should never happen with force:true — defensive only.
-        throw new Error(`Unexpected proposal skip: ${result.message}`);
-    }
-    return { schemaVersion: 1, ok: true, proposal: result };
-}
 /**
  * Restore an accepted proposal's prior content from the backup captured at
  * promotion time (Advantage D6c / Phase 6C).