@fonlan/dsh-gitmemo 0.3.0 → 0.3.2

package/README.md

@@ -103,7 +103,9 @@ git -C .mem show <commit-hash>
    `mem_write` every completed repo-related task that still lacks a memory and whose outcome is
    **valuable/reusable** (or was explicitly asked to be remembered). Never duplicate an
    already-written entry. Never write for pure Q&A, incomplete tasks, non-repo work, or purely
-   operational git actions.
+   operational git actions. `keywords` should be task-related words NOT already present in
+   `title` / `summary` (中英文同义词 both fine) — words already there are searchable via
+   `title` / `summary` themselves, so repeating them does not improve recall.
 4. **User correction.** If a stored conclusion is outdated and a replacement exists →
    `mem_replace` (never delete-then-write). If it is obsolete with no replacement →
    `mem_delete` with a `reason`.

package/README.zh.md

@@ -94,7 +94,7 @@ git -C .mem show <commit-hash>
    `mem_read` 5 条最相关记忆；用 `skip` + 返回的 `snapshot` 翻页。
 3. **会话结束检查点 —— 唯一的写入路径。** 对话即将结束时，`mem_write` **每一条**已完成、与仓库
    相关、且结论**有价值/可复用**（或用户明确要求记住）但还没有记忆的任务。绝不重复写已存在的条目。
-   纯问答、未完成任务、与仓库无关的工作、纯操作性的 git 动作一律不写。
+   纯问答、未完成任务、与仓库无关的工作、纯操作性的 git 动作一律不写。`keywords` 应选用与任务相关但未出现在 `title` / `summary` 中的词（中英文同义词皆可）——`title` / `summary` 已有的词本身就能被检索到，重复它们不会提高召回率。
 4. **用户更正。** 已存结论过时且有替代结论 → `mem_replace`（禁止先 delete 再 write）；结论作废且无
    替代 → 带 `reason` 的 `mem_delete`。
 5. **子代理结果。** 是否形成一条会话级记忆，由根 Agent 汇总后决定。

package/lib/cli.js

@@ -5,6 +5,11 @@
  *   dsh-gitmemo migrate --project-root <path> [--dry-run|--apply]
  *     [--source <legacy-mem-dir>] [--out <baseline-file>] [--baseline <file>]
  *
+ * Migration is AUTOMATIC inside the engine (the first operation on a legacy
+ * `.mem` repo migrates it in place). This CLI remains for explicit control:
+ * non-default --source directories, baseline review, and repos where
+ * automatic migration is blocked (conflicts, dirty worktree, ...).
+ *
  * Dry-run scans the legacy `.mem` repo without touching any ref/index/work
  * tree state and prints the plan (dedupe, conflicts, estimated commits).
  * `--apply` re-verifies the baseline refs, then migrates inside the

package/lib/index.js

@@ -216,7 +216,7 @@ function registerMemTools(ctx, config) {
     }));
     ctx.tools.register(defineTool({
         name: "mem_write",
-        description: "Store a completed task outcome in the gitmemo long-term memory (.mem git repo). Write ONLY when the task is complete AND repo-related AND the outcome is valuable/reusable OR the user explicitly asked to remember. Entries are immutable: title (single line, ≤200 chars, \"[module] action + object\"), summary (≤4000 chars), keywords (2-12, include 中英文同义词) and content (markdown body; the engine generates front matter) are all required; related_branches/related_paths are optional. Corrections use mem_replace, withdrawal uses mem_delete — never rewrite in place.",
+        description: "Store a completed task outcome in the gitmemo long-term memory (.mem git repo). Write ONLY when the task is complete AND repo-related AND the outcome is valuable/reusable OR the user explicitly asked to remember. Entries are immutable: title (single line, ≤200 chars, \"[module] action + object\"), summary (≤4000 chars), keywords (2-12, include 中英文同义词) and content (markdown body; the engine generates front matter) are all required; related_branches/related_paths are optional. Keywords must ADD new search angles — pick task-related terms (中英文同义词 both fine) that are NOT already present in title/summary: words already in title/summary are searchable via those fields themselves, so repeating them does not improve recall. Corrections use mem_replace, withdrawal uses mem_delete — never rewrite in place.",
         parameters: {
             title: {
                 type: "string",
@@ -231,7 +231,7 @@ function registerMemTools(ctx, config) {
             keywords: {
                 ...KEYWORDS_ARRAY,
                 required: true,
-                description: "2-12 keywords (1-64 chars each); include 中英文同义词, e.g. [\"auth\", \"rate-limit\", \"登录\", \"限流\"]."
+                description: "2-12 keywords (1-64 chars each); task-related words NOT already present in title/summary (重复 title/summary 已有的词不会提高召回率); include 中英文同义词, e.g. [\"auth\", \"rate-limit\", \"登录\", \"限流\"]."
             },
             content: {
                 type: "string",
@@ -333,7 +333,7 @@ function registerMemTools(ctx, config) {
             keywords: {
                 ...KEYWORDS_ARRAY,
                 required: true,
-                description: "2-12 keywords (1-64 chars each); include 中英文同义词."
+                description: "2-12 keywords (1-64 chars each); task-related words NOT already present in title/summary; include 中英文同义词."
             },
             content: {
                 type: "string",
@@ -382,10 +382,11 @@ function registerPromptSection(ctx) {
         name: "memory:gitmemo",
         order: 150,
         text: [
-            "This deployment provides gitmemo long-term memory: a local .mem git repository at the project root stores past task outcomes as immutable markdown entries; git is the only dependency. Use the dedicated tools only (mem_search / mem_read / mem_write / mem_delete / mem_replace — all auto-initialize); never shell out to git or read .mem files directly.",
+            "This deployment provides gitmemo long-term memory: a local .mem git repository at the project root stores past task outcomes as immutable markdown entries; git is the only dependency. Use the dedicated tools only (mem_search / mem_read / mem_write / mem_delete / mem_replace — all auto-initialize, and legacy-format .mem repos migrate automatically on first use); never shell out to git or read .mem files directly.",
             "- BEFORE WORK — search: 仓库相关任务开始前提取 1–12 个中英文关键词调用 mem_search（含中英文同义词）；纯闲聊和通用问答无需搜索。",
             "- RESULT PRESELECT — 根据 title、summary、keywords、score 和 matched keywords 选择最多 5 条执行 mem_read，复用相关结论；无相关结果时用返回的 snapshot + skip 翻页。",
             "- END-OF-SESSION CHECKPOINT — the ONLY write path: 会话结束时回顾全程，仅当结论有价值、可复用或用户明确要求记住时 mem_write；纯问答、未完成任务、非仓库工作、纯操作类 git 动作（仅 commit/push）不写；避免语义重复。",
+            "- KEYWORD SELECTION — mem_write/mem_replace 的 keywords 应选择与任务相关但未出现在 title/summary 中的词（中英文同义词皆可）；title/summary 里已有的词本身就能被检索到，重复它们不会提高召回率。",
             "- USER CORRECTION — 用户更正已有结论：有替代结论时调用 mem_replace（不得先 delete 再 write）；结论作废且无替代时调用带 reason 的 mem_delete。",
             "- SUBAGENT RESULTS — 子代理结果由根 Agent 汇总后决定是否形成一条会话级记忆。"
         ].join("\n")

package/lib/mem.d.ts

@@ -262,16 +262,29 @@ export declare function rollbackJournal(memDir: string, journal: TransactionJour
 export declare function ensureInit(root: string, memDir: string, gitTimeoutMs: number): Promise<void>;
 /**
  * Git-backed long-term memory engine operating on one project root.
- * Every operation auto-initializes a new-format repo; legacy repos are
- * read-only for search/read until migrated via the CLI.
+ * Every operation auto-initializes a new-format repo; legacy `.mem` repos
+ * are migrated automatically on first use (no external CLI needed). Only
+ * when automatic migration is blocked (conflicts, dirty worktree, ...) do
+ * legacy repos stay read-only for search/read with a clear warning.
  */
 export declare class GitMemo {
     readonly root: string;
     readonly memDir: string;
     private readonly config;
     constructor(root: string, config?: GitMemoConfig);
-    /** Initialize the memory repo when missing (idempotent). */
+    /** Initialize the memory repo when missing (idempotent). Legacy repos are migrated automatically. */
     init(): Promise<string>;
+    /**
+     * Fully automatic legacy migration (no external CLI needed): when `.mem`
+     * exists in legacy format, rebuild it into the new format in place —
+     * dry-run + apply in one step. The caller must already hold the operation
+     * lock. Blocking conditions (conflicts, dirty worktree, interrupted legacy
+     * journal, ...) are returned, never thrown, so operations can fall back to
+     * legacy read-only behavior; the next operation retries automatically.
+     */
+    private autoMigrateIfNeeded;
+    /** Ensure the repo is initialized and writable (new format), migrating legacy repos automatically. */
+    private ensureWritable;
     /**
      * Search past memories (plan 6): fixed-string OR grep recall over commit
      * messages only, active-entry filtering, field-level matching and scoring,

package/lib/mem.js

@@ -717,9 +717,13 @@ export async function recoverMigrationSwap(root, gitTimeoutMs) {
 function sleep(ms) {
     return new Promise((resolvePromise) => setTimeout(resolvePromise, ms));
 }
-function legacyWarning(root) {
-    return ("gitmemo: .mem is in legacy format — search is read-only over the current branch. " +
-        `Run \`dsh-gitmemo migrate --project-root ${root} --dry-run\` to plan migration (then --apply).`);
+function legacyWarning() {
+    return ("gitmemo: .mem is in legacy format and automatic migration is blocked — search is read-only over the current branch");
+}
+/** Refusal message for write/delete/replace when automatic migration cannot run. */
+function legacyWriteRefusal(outcome) {
+    const detail = outcome.blocked?.detail ?? "unknown blocking condition";
+    return ("gitmemo: .mem exists in legacy format — write operations are disabled and automatic migration is blocked: " + detail);
 }
 /** Detect the repo format from `.gitmemo-format` at the given snapshot. */
 export async function repoFormat(memDir, gitTimeoutMs, snapshot = "HEAD") {
@@ -804,9 +808,9 @@ async function resolveSnapshot(memDir, gitTimeoutMs, root, input) {
             if (!(await gitOk(memDir, ["merge-base", "--is-ancestor", full, head], gitTimeoutMs))) {
                 throw new GitMemoError(`gitmemo: stale legacy snapshot ${input} is no longer part of the current HEAD history — restart pagination`);
             }
-            return { snapshot: full, legacy: true, warning: legacyWarning(root) };
+            return { snapshot: full, legacy: true, warning: legacyWarning() };
         }
-        return { snapshot: head, legacy: true, warning: legacyWarning(root) };
+        return { snapshot: head, legacy: true, warning: legacyWarning() };
     }
     const format = await repoFormat(memDir, gitTimeoutMs, main);
     if (format !== "new") {
@@ -815,9 +819,9 @@ async function resolveSnapshot(memDir, gitTimeoutMs, root, input) {
             if (!(await gitOk(memDir, ["merge-base", "--is-ancestor", full, main], gitTimeoutMs))) {
                 throw new GitMemoError(`gitmemo: stale legacy snapshot ${input} is no longer part of the current branch history — restart pagination`);
             }
-            return { snapshot: full, legacy: true, warning: legacyWarning(root) };
+            return { snapshot: full, legacy: true, warning: legacyWarning() };
         }
-        return { snapshot: main, legacy: true, warning: legacyWarning(root) };
+        return { snapshot: main, legacy: true, warning: legacyWarning() };
     }
     if (input !== undefined) {
         const full = await resolveCommit(memDir, input, gitTimeoutMs);
@@ -1059,14 +1063,6 @@ async function assertOnMain(memDir, gitTimeoutMs) {
         throw new GitMemoError(`gitmemo: .mem HEAD is not on refs/heads/main (${sym || "unborn HEAD"}) — gitmemo requires its single main branch`);
     }
 }
-/** Write/delete/replace must run on the new format; legacy repos need migration. */
-async function assertNewFormat(memDir, gitTimeoutMs, root) {
-    const format = await repoFormat(memDir, gitTimeoutMs);
-    if (format !== "new") {
-        throw new GitMemoError("gitmemo: .mem exists in legacy format — write operations are disabled. " +
-            `Run \`dsh-gitmemo migrate --project-root ${root} --dry-run\` to plan migration, then --apply.`);
-    }
-}
 /** Current code branch + HEAD SHA for entry metadata (plan 7.2/7.3). */
 async function codeContext(root, gitTimeoutMs) {
     try {
@@ -1190,8 +1186,10 @@ function cacheSearch(key, value) {
 // ---------------------------------------------------------------------------
 /**
  * Git-backed long-term memory engine operating on one project root.
- * Every operation auto-initializes a new-format repo; legacy repos are
- * read-only for search/read until migrated via the CLI.
+ * Every operation auto-initializes a new-format repo; legacy `.mem` repos
+ * are migrated automatically on first use (no external CLI needed). Only
+ * when automatic migration is blocked (conflicts, dirty worktree, ...) do
+ * legacy repos stay read-only for search/read with a clear warning.
  */
 export class GitMemo {
     root;
@@ -1214,13 +1212,45 @@ export class GitMemo {
         };
         this.memDir = join(this.root, ".mem");
     }
-    /** Initialize the memory repo when missing (idempotent). */
+    /** Initialize the memory repo when missing (idempotent). Legacy repos are migrated automatically. */
     async init() {
         await withLock(this.root, this.config, "init", async () => {
             await ensureInit(this.root, this.memDir, this.config.gitTimeoutMs);
+            await this.autoMigrateIfNeeded();
         });
         return this.memDir;
     }
+    /**
+     * Fully automatic legacy migration (no external CLI needed): when `.mem`
+     * exists in legacy format, rebuild it into the new format in place —
+     * dry-run + apply in one step. The caller must already hold the operation
+     * lock. Blocking conditions (conflicts, dirty worktree, interrupted legacy
+     * journal, ...) are returned, never thrown, so operations can fall back to
+     * legacy read-only behavior; the next operation retries automatically.
+     */
+    async autoMigrateIfNeeded() {
+        if (!(await pathExists(join(this.memDir, ".git")))) {
+            return { migrated: false, blocked: { code: "no-repo", detail: "no .mem repository" } };
+        }
+        if ((await repoFormat(this.memDir, this.config.gitTimeoutMs)) === "new") {
+            return { migrated: false, alreadyNewFormat: true };
+        }
+        const { migrateAutoUnlocked } = await import("./migrate.js");
+        return migrateAutoUnlocked(this.root, {
+            gitTimeoutMs: this.config.gitTimeoutMs,
+            lockTimeoutMs: this.config.lockTimeoutMs
+        });
+    }
+    /** Ensure the repo is initialized and writable (new format), migrating legacy repos automatically. */
+    async ensureWritable() {
+        await ensureInit(this.root, this.memDir, this.config.gitTimeoutMs);
+        const migration = await this.autoMigrateIfNeeded();
+        if (migration.alreadyNewFormat === true)
+            return; // fresh/new-format repo — nothing to migrate
+        if (!migration.migrated) {
+            throw new GitMemoError(legacyWriteRefusal(migration));
+        }
+    }
     /**
      * Search past memories (plan 6): fixed-string OR grep recall over commit
      * messages only, active-entry filtering, field-level matching and scoring,
@@ -1262,12 +1292,18 @@ export class GitMemo {
             ? options.snapshot.trim()
             : undefined;
         // Read barrier: resolve the immutable snapshot under the lock (creating
-        // the repo when missing), then scan without holding it.
-        const { snapshot, legacy, warning } = await withLock(this.root, this.config, "search", async () => {
+        // the repo when missing; legacy repos are migrated automatically when
+        // safe), then scan without holding it.
+        const { snapshot, legacy, warning, blockedNote } = await withLock(this.root, this.config, "search", async () => {
             if (!(await pathExists(join(this.memDir, ".git")))) {
                 await ensureInit(this.root, this.memDir, this.config.gitTimeoutMs);
             }
-            return resolveSnapshot(this.memDir, this.config.gitTimeoutMs, this.root, requestedSnapshot);
+            const migration = await this.autoMigrateIfNeeded();
+            const resolved = await resolveSnapshot(this.memDir, this.config.gitTimeoutMs, this.root, requestedSnapshot);
+            const note = !migration.migrated && migration.blocked !== undefined && resolved.legacy
+                ? " Automatic migration was attempted but blocked: " + migration.blocked.detail
+                : undefined;
+            return { ...resolved, blockedNote: note };
         });
         const cacheKey = this.memDir + "\x00" + snapshot + "\x00" + normalized.join("\x00");
         let computation = searchCache.get(cacheKey);
@@ -1277,7 +1313,7 @@ export class GitMemo {
         }
         const total = computation.hits.length;
         const next_skip = skip + limit < total ? skip + limit : null;
-        const allWarnings = [adapterWarning, warning].filter((w) => w !== undefined).join(" ");
+        const allWarnings = [adapterWarning, warning, blockedNote].filter((w) => w !== undefined).join(" ");
         return {
             snapshot,
             total,
@@ -1355,6 +1391,7 @@ export class GitMemo {
             if (!(await pathExists(join(this.memDir, ".git")))) {
                 await ensureInit(this.root, this.memDir, this.config.gitTimeoutMs);
             }
+            await this.autoMigrateIfNeeded();
             const full = await resolveCommit(this.memDir, commitHash, this.config.gitTimeoutMs);
             const added = await addedFilesOf(this.memDir, full, this.config.gitTimeoutMs);
             if (added.length !== 1) {
@@ -1378,8 +1415,7 @@ export class GitMemo {
         const validated = validateWriteInput(adapted, legacy);
         const digest = computeDigest(validated.title, validated.summary, validated.keywords, validated.content);
         return withLock(this.root, this.config, "write", async () => {
-            await ensureInit(this.root, this.memDir, this.config.gitTimeoutMs);
-            await assertNewFormat(this.memDir, this.config.gitTimeoutMs, this.root);
+            await this.ensureWritable();
             await recoverJournal(this.memDir, this.config.gitTimeoutMs);
             await assertClean(this.memDir, this.config.gitTimeoutMs);
             await assertOnMain(this.memDir, this.config.gitTimeoutMs);
@@ -1440,8 +1476,7 @@ export class GitMemo {
         assertNoControlChars(reason, "reason");
         assertNoTrailerInjection(reason, "reason");
         return withLock(this.root, this.config, "delete", async () => {
-            await ensureInit(this.root, this.memDir, this.config.gitTimeoutMs);
-            await assertNewFormat(this.memDir, this.config.gitTimeoutMs, this.root);
+            await this.ensureWritable();
             await recoverJournal(this.memDir, this.config.gitTimeoutMs);
             await assertClean(this.memDir, this.config.gitTimeoutMs);
             await assertOnMain(this.memDir, this.config.gitTimeoutMs);
@@ -1487,8 +1522,7 @@ export class GitMemo {
         const validated = validateWriteInput(input);
         const digest = computeDigest(validated.title, validated.summary, validated.keywords, validated.content);
         return withLock(this.root, this.config, "replace", async () => {
-            await ensureInit(this.root, this.memDir, this.config.gitTimeoutMs);
-            await assertNewFormat(this.memDir, this.config.gitTimeoutMs, this.root);
+            await this.ensureWritable();
             await recoverJournal(this.memDir, this.config.gitTimeoutMs);
             await assertClean(this.memDir, this.config.gitTimeoutMs);
             await assertOnMain(this.memDir, this.config.gitTimeoutMs);

package/lib/migrate.d.ts

@@ -60,6 +60,19 @@ export interface MigrationOptions {
     gitTimeoutMs?: number;
     lockTimeoutMs?: number;
 }
+/** Why automatic migration could not run (user-resolvable blocking conditions). */
+export interface AutoMigrateBlock {
+    code: "no-repo" | "no-branches" | "conflicts" | "dirty" | "legacy-journal" | "other";
+    /** Human-readable detail; safe to surface to the user. */
+    detail: string;
+}
+/** Outcome of an automatic migration attempt (never throws for blocking conditions). */
+export interface AutoMigrateOutcome {
+    migrated: boolean;
+    alreadyNewFormat?: boolean;
+    blocked?: AutoMigrateBlock;
+    report?: MigrationApplyReport;
+}
 /**
  * Scan a legacy `.mem` repo and produce the migration plan. Read-only: no
  * ref, index or worktree state is modified (the lock file is transient).
@@ -71,3 +84,12 @@ export declare function migrateDryRun(root: string, options?: MigrationOptions):
  * new canonical main in a temp repo, then swaps directories atomically.
  */
 export declare function migrateApply(root: string, baseline: MigrationBaseline, options?: MigrationOptions): Promise<MigrationApplyReport>;
+/**
+ * Fully automatic migration for engine use: dry-run + apply in one step,
+ * without taking the cross-process lock (the caller must already hold it).
+ *
+ * Never throws for user-resolvable blocking conditions — it returns
+ * `blocked` instead, so the caller can fall back to legacy read-only mode
+ * and retry automatically on a later operation.
+ */
+export declare function migrateAutoUnlocked(root: string, options?: MigrationOptions): Promise<AutoMigrateOutcome>;

package/lib/migrate.js

@@ -2,9 +2,14 @@
  * Legacy → new-format migration for dsh-gitmemo (plan 10).
  *
  * Legacy `.mem` repos (no `.gitmemo-format` marker, possibly multi-branch)
- * are migrated through an explicit CLI only: `dsh-gitmemo migrate
- * --project-root <path> --dry-run` plans the migration (no refs are
- * touched), `--apply` executes it inside the cross-process lock:
+ * are migrated fully automatically by the engine: the first operation on a
+ * legacy repo runs dry-run + apply in one step (no `dsh-gitmemo` command
+ * needed). The CLI (`dsh-gitmemo migrate --project-root <path>
+ * --dry-run|--apply`) remains for explicit control — non-default --source
+ * directories, baseline review, and repos where automatic migration is
+ * blocked (conflicts, dirty worktree, ...).
+ *
+ * Apply mechanics:
  *  1. backup refs for every old branch tip (`refs/gitmemo/backup/<ts>/<b>`);
  *  2. a brand-new canonical `main` is built in a sibling temp repo (init
  *     commit + one immutable ADD commit per unique active entry);
@@ -27,6 +32,15 @@ function safeLegacyDate(epochRaw) {
     const ms = Number(epochRaw ?? 0) * 1000;
     return Number.isFinite(ms) && Math.abs(ms) <= 8.64e15 ? new Date(ms) : new Date(0);
 }
+async function isGitRepo(dir, gitTimeoutMs) {
+    try {
+        await git(dir, ["rev-parse", "--git-dir"], gitTimeoutMs);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 async function listTips(memDir, gitTimeoutMs) {
     const out = (await git(memDir, ["for-each-ref", "--format=%(refname:short)\t%(objectname)", "refs/heads"], gitTimeoutMs)).trim();
     const branches = [];
@@ -191,136 +205,138 @@ async function buildPlanEntry(args) {
  * ref, index or worktree state is modified (the lock file is transient).
  */
 export async function migrateDryRun(root, options = {}) {
-    const gitTimeoutMs = options.gitTimeoutMs ?? 60000;
     const lockTimeoutMs = options.lockTimeoutMs ?? 30000;
+    return withLock(root, { lockTimeoutMs }, "migrate-dry-run", () => migrateDryRunUnlocked(root, options));
+}
+/** Unlocked core of {@link migrateDryRun}; the caller must hold the cross-process lock. */
+async function migrateDryRunUnlocked(root, options = {}) {
+    const gitTimeoutMs = options.gitTimeoutMs ?? 60000;
     const memDir = resolve(options.source ?? join(root, ".mem"));
-    return withLock(root, { lockTimeoutMs }, "migrate-dry-run", async () => {
-        try {
-            await git(memDir, ["rev-parse", "--git-dir"], gitTimeoutMs);
-        }
-        catch {
-            throw new GitMemoError("gitmemo: no .mem repository at " + memDir);
-        }
-        if ((await repoFormat(memDir, gitTimeoutMs)) === "new") {
-            return {
-                legacy: false,
-                alreadyNewFormat: true,
-                branches: [],
+    try {
+        await git(memDir, ["rev-parse", "--git-dir"], gitTimeoutMs);
+    }
+    catch {
+        throw new GitMemoError("gitmemo: no .mem repository at " + memDir);
+    }
+    if ((await repoFormat(memDir, gitTimeoutMs)) === "new") {
+        return {
+            legacy: false,
+            alreadyNewFormat: true,
+            branches: [],
+            tips: {},
+            oldEntryCount: 0,
+            uniqueEntryCount: 0,
+            conflictCount: 0,
+            estimatedMainCommits: 0,
+            baseline: {
+                format: "dsh-gitmemo-migration-baseline",
+                version: 1,
+                root: resolve(root),
+                memDir,
+                scannedAt: new Date().toISOString(),
                 tips: {},
-                oldEntryCount: 0,
-                uniqueEntryCount: 0,
-                conflictCount: 0,
-                estimatedMainCommits: 0,
-                baseline: {
-                    format: "dsh-gitmemo-migration-baseline",
-                    version: 1,
-                    root: resolve(root),
-                    memDir,
-                    scannedAt: new Date().toISOString(),
-                    tips: {},
-                    entries: [],
-                    conflicts: [],
-                    warnings: []
-                },
-                warnings: ["already in new format — nothing to migrate"]
-            };
-        }
-        const { branches, tips } = await listTips(memDir, gitTimeoutMs);
-        if (branches.length === 0) {
-            throw new GitMemoError("gitmemo: legacy .mem has no branches — nothing to migrate");
-        }
-        const warnings = [];
-        const variantsByPath = new Map();
-        const occurrences = new Map(); // content digest -> paths
-        const byDigest = new Map();
-        let oldEntryCount = 0;
-        for (const branch of branches.sort()) {
-            const tip = tips[branch];
-            const filesOut = (await git(memDir, ["ls-tree", "-r", "--name-only", tip, "--", ENTRY_DIR + "/"], gitTimeoutMs)).trim();
-            const files = filesOut.split("\n").filter((line) => line.startsWith(ENTRY_DIR + "/") && line.endsWith(".md"));
-            for (const file of files.sort()) {
-                oldEntryCount += 1;
-                const content = await git(memDir, ["show", tip + ":" + file], gitTimeoutMs);
-                const createOut = (await git(memDir, ["log", "-1", "--format=%ct%x00%H%x00%s%x00%B", tip, "--", file], gitTimeoutMs)).trim();
-                const [ctRaw, hash, subject, body] = createOut.split("\x00");
-                const contentDigest = createHash("sha256").update(content, "utf8").digest("hex");
-                let pathVariants = variantsByPath.get(file);
-                if (pathVariants === undefined) {
-                    pathVariants = new Map();
-                    variantsByPath.set(file, pathVariants);
-                }
-                pathVariants.set(branch, { branch, hash, digest: contentDigest });
-                let paths = occurrences.get(contentDigest);
-                if (paths === undefined) {
-                    paths = new Set();
-                    occurrences.set(contentDigest, paths);
-                }
-                paths.add(file);
-                if (!byDigest.has(contentDigest)) {
-                    const plan = await buildPlanEntry({
-                        memDir,
-                        gitTimeoutMs,
-                        branch,
-                        file,
-                        content,
-                        hash,
-                        date: safeLegacyDate(ctRaw),
-                        subject: subject ?? "",
-                        body: body ?? "",
-                        warnings
-                    });
-                    byDigest.set(contentDigest, plan);
-                }
+                entries: [],
+                conflicts: [],
+                warnings: []
+            },
+            warnings: ["already in new format — nothing to migrate"]
+        };
+    }
+    const { branches, tips } = await listTips(memDir, gitTimeoutMs);
+    if (branches.length === 0) {
+        throw new GitMemoError("gitmemo: legacy .mem has no branches — nothing to migrate");
+    }
+    const warnings = [];
+    const variantsByPath = new Map();
+    const occurrences = new Map(); // content digest -> paths
+    const byDigest = new Map();
+    let oldEntryCount = 0;
+    for (const branch of branches.sort()) {
+        const tip = tips[branch];
+        const filesOut = (await git(memDir, ["ls-tree", "-r", "--name-only", tip, "--", ENTRY_DIR + "/"], gitTimeoutMs)).trim();
+        const files = filesOut.split("\n").filter((line) => line.startsWith(ENTRY_DIR + "/") && line.endsWith(".md"));
+        for (const file of files.sort()) {
+            oldEntryCount += 1;
+            const content = await git(memDir, ["show", tip + ":" + file], gitTimeoutMs);
+            const createOut = (await git(memDir, ["log", "-1", "--format=%ct%x00%H%x00%s%x00%B", tip, "--", file], gitTimeoutMs)).trim();
+            const [ctRaw, hash, subject, body] = createOut.split("\x00");
+            const contentDigest = createHash("sha256").update(content, "utf8").digest("hex");
+            let pathVariants = variantsByPath.get(file);
+            if (pathVariants === undefined) {
+                pathVariants = new Map();
+                variantsByPath.set(file, pathVariants);
             }
-        }
-        // conflicts: same path, different content
-        const conflicts = [];
-        for (const [path, variants] of variantsByPath) {
-            const digests = new Set([...variants.values()].map((v) => v.digest));
-            if (digests.size > 1) {
-                conflicts.push({
-                    path,
-                    variants: [...variants.values()].sort((a, b) => a.branch.localeCompare(b.branch))
+            pathVariants.set(branch, { branch, hash, digest: contentDigest });
+            let paths = occurrences.get(contentDigest);
+            if (paths === undefined) {
+                paths = new Set();
+                occurrences.set(contentDigest, paths);
+            }
+            paths.add(file);
+            if (!byDigest.has(contentDigest)) {
+                const plan = await buildPlanEntry({
+                    memDir,
+                    gitTimeoutMs,
+                    branch,
+                    file,
+                    content,
+                    hash,
+                    date: safeLegacyDate(ctRaw),
+                    subject: subject ?? "",
+                    body: body ?? "",
+                    warnings
                 });
+                byDigest.set(contentDigest, plan);
             }
         }
-        // a content digest that occurs at a conflicted path is excluded from auto-migration
-        const conflictedPaths = new Set(conflicts.map((c) => c.path));
-        const conflictedDigests = new Set();
-        for (const [digest, paths] of occurrences) {
-            for (const path of paths) {
-                if (conflictedPaths.has(path))
-                    conflictedDigests.add(digest);
-            }
+    }
+    // conflicts: same path, different content
+    const conflicts = [];
+    for (const [path, variants] of variantsByPath) {
+        const digests = new Set([...variants.values()].map((v) => v.digest));
+        if (digests.size > 1) {
+            conflicts.push({
+                path,
+                variants: [...variants.values()].sort((a, b) => a.branch.localeCompare(b.branch))
+            });
         }
-        // NOTE: byDigest is keyed by the raw content digest (sha256 of content);
-        // the plan's `digest` field is the new canonical engine digest — filter by key.
-        const entries = [...byDigest.entries()]
-            .filter(([contentDigest]) => !conflictedDigests.has(contentDigest))
-            .map(([, plan]) => plan);
-        const baseline = {
-            format: "dsh-gitmemo-migration-baseline",
-            version: 1,
-            root: resolve(root),
-            memDir,
-            scannedAt: new Date().toISOString(),
-            tips,
-            entries,
-            conflicts,
-            warnings
-        };
-        return {
-            legacy: true,
-            branches,
-            tips,
-            oldEntryCount,
-            uniqueEntryCount: entries.length,
-            conflictCount: conflicts.length,
-            estimatedMainCommits: 1 + entries.length,
-            baseline,
-            warnings
-        };
-    });
+    }
+    // a content digest that occurs at a conflicted path is excluded from auto-migration
+    const conflictedPaths = new Set(conflicts.map((c) => c.path));
+    const conflictedDigests = new Set();
+    for (const [digest, paths] of occurrences) {
+        for (const path of paths) {
+            if (conflictedPaths.has(path))
+                conflictedDigests.add(digest);
+        }
+    }
+    // NOTE: byDigest is keyed by the raw content digest (sha256 of content);
+    // the plan's `digest` field is the new canonical engine digest — filter by key.
+    const entries = [...byDigest.entries()]
+        .filter(([contentDigest]) => !conflictedDigests.has(contentDigest))
+        .map(([, plan]) => plan);
+    const baseline = {
+        format: "dsh-gitmemo-migration-baseline",
+        version: 1,
+        root: resolve(root),
+        memDir,
+        scannedAt: new Date().toISOString(),
+        tips,
+        entries,
+        conflicts,
+        warnings
+    };
+    return {
+        legacy: true,
+        branches,
+        tips,
+        oldEntryCount,
+        uniqueEntryCount: entries.length,
+        conflictCount: conflicts.length,
+        estimatedMainCommits: 1 + entries.length,
+        baseline,
+        warnings
+    };
 }
 // ---------------------------------------------------------------------------
 // apply
@@ -370,8 +386,12 @@ async function excludeFromParent(root, gitTimeoutMs) {
  * new canonical main in a temp repo, then swaps directories atomically.
  */
 export async function migrateApply(root, baseline, options = {}) {
-    const gitTimeoutMs = options.gitTimeoutMs ?? 60000;
     const lockTimeoutMs = options.lockTimeoutMs ?? 30000;
+    return withLock(root, { lockTimeoutMs }, "migrate", () => migrateApplyUnlocked(root, baseline, options));
+}
+/** Unlocked core of {@link migrateApply}; the caller must hold the cross-process lock. */
+async function migrateApplyUnlocked(root, baseline, options = {}) {
+    const gitTimeoutMs = options.gitTimeoutMs ?? 60000;
     if (baseline === null ||
         typeof baseline !== "object" ||
         baseline.format !== "dsh-gitmemo-migration-baseline" ||
@@ -395,172 +415,236 @@ export async function migrateApply(root, baseline, options = {}) {
     if (resolve(baseline.memDir) !== memDir) {
         throw new GitMemoError("gitmemo: migration baseline source path is inconsistent — re-run --dry-run");
     }
-    return withLock(root, { lockTimeoutMs }, "migrate", async () => {
-        await recoverMigrationSwap(root, gitTimeoutMs);
-        if ((await repoFormat(memDir, gitTimeoutMs)) === "new") {
-            return { migrated: false, alreadyMigrated: true, entries: 0, newMain: "", backupRefPrefix: "", oldBranches: [] };
+    await recoverMigrationSwap(root, gitTimeoutMs);
+    if ((await repoFormat(memDir, gitTimeoutMs)) === "new") {
+        return { migrated: false, alreadyMigrated: true, entries: 0, newMain: "", backupRefPrefix: "", oldBranches: [] };
+    }
+    // 1. re-verify the dry-run baseline refs are unchanged
+    const current = await listTips(memDir, gitTimeoutMs);
+    const baselineBranches = Object.keys(baseline.tips).sort();
+    if (baselineBranches.length === 0) {
+        throw new GitMemoError("gitmemo: baseline contains no branches — re-run `dsh-gitmemo migrate --dry-run`");
+    }
+    for (const branch of baselineBranches) {
+        if (current.tips[branch] !== baseline.tips[branch]) {
+            throw new GitMemoError(`gitmemo: branch "${branch}" changed since the dry-run baseline (${current.tips[branch] ?? "gone"} ≠ ${baseline.tips[branch]}) — re-run --dry-run`);
         }
-        // 1. re-verify the dry-run baseline refs are unchanged
-        const current = await listTips(memDir, gitTimeoutMs);
-        const baselineBranches = Object.keys(baseline.tips).sort();
-        if (baselineBranches.length === 0) {
-            throw new GitMemoError("gitmemo: baseline contains no branches — re-run `dsh-gitmemo migrate --dry-run`");
+    }
+    if (current.branches.length !== baselineBranches.length) {
+        throw new GitMemoError("gitmemo: branch set changed since the dry-run baseline — re-run --dry-run");
+    }
+    // 2. conflicts must be resolved by the user first
+    if (baseline.conflicts.length > 0) {
+        throw new GitMemoError(`gitmemo: migration blocked by ${baseline.conflicts.length} conflict(s) (same entry path, different content across branches):\n` +
+            conflictManifest(baseline.conflicts) +
+            "\nResolve the conflicts, then re-run --dry-run to produce a clean baseline.");
+    }
+    const legacyStatus = (await git(memDir, ["status", "--porcelain"], gitTimeoutMs)).trim();
+    if (legacyStatus.length > 0) {
+        throw new GitMemoError("gitmemo: legacy memory repository is not clean — migration refuses to discard uncommitted/staged content. " +
+            `Inspect with: git -C ${memDir} status`);
+    }
+    const legacyJournal = join(memDir, ".git", "gitmemo-transaction.json");
+    try {
+        await readFile(legacyJournal, "utf8");
+        throw new GitMemoError(`gitmemo: legacy repository contains an interrupted transaction journal (${legacyJournal}); repair it before migration`);
+    }
+    catch (error) {
+        if (error instanceof GitMemoError)
+            throw error;
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    // 3. backup refs in the old repo (safety net; also fetched into the new repo)
+    const ts = new Date().toISOString().replace(/[:.]/g, "-");
+    for (const [branch, hash] of Object.entries(baseline.tips)) {
+        await git(memDir, ["update-ref", `refs/gitmemo/backup/${ts}/${branch}`, hash], gitTimeoutMs);
+    }
+    // 4. build the new canonical main in a sibling temp repo
+    const tmp = join(root, `.mem.gitmemo-tmp-${process.pid}-${randomBytes(4).toString("hex")}`);
+    try {
+        await mkdir(join(tmp, ENTRY_DIR), { recursive: true });
+        await gitInitMain(tmp, gitTimeoutMs);
+        await writeFile(join(tmp, FORMAT_FILE), GITMEMO_FORMAT_VERSION + "\n", "utf8");
+        await writeFile(join(tmp, ENTRY_DIR, ".gitkeep"), "", "utf8");
+        await git(tmp, ["add", "-A", "--", FORMAT_FILE, ENTRY_DIR + "/.gitkeep"], gitTimeoutMs);
+        await commitWithIdentity(tmp, "init: initialize memory repo (gitmemo format 2)", gitTimeoutMs);
+        // fetch old objects + backup refs into the new repo so old hashes stay readable
+        await git(tmp, ["fetch", "-q", memDir, `+refs/heads/*:refs/gitmemo/backup/${ts}/*`], gitTimeoutMs);
+        // 5. one immutable ADD commit per unique entry, preserving old dates
+        const entries = [...baseline.entries].sort((a, b) => a.date.localeCompare(b.date) || a.sourcePath.localeCompare(b.sourcePath));
+        const digests = new Set(entries.map((e) => e.digest));
+        if (digests.size !== entries.length) {
+            throw new GitMemoError("gitmemo: migration plan contains duplicate digests — re-run --dry-run");
         }
-        for (const branch of baselineBranches) {
-            if (current.tips[branch] !== baseline.tips[branch]) {
-                throw new GitMemoError(`gitmemo: branch "${branch}" changed since the dry-run baseline (${current.tips[branch] ?? "gone"} ≠ ${baseline.tips[branch]}) — re-run --dry-run`);
-            }
+        const created = [];
+        for (const entry of entries) {
+            const parsedMs = Date.parse(entry.date);
+            const epoch = Number.isFinite(parsedMs) ? Math.floor(parsedMs / 1000) : 0;
+            const env = { GIT_AUTHOR_DATE: "@" + epoch, GIT_COMMITTER_DATE: "@" + epoch };
+            const entryDate = safeLegacyDate(epoch);
+            const baseName = utcMs(entryDate) + "-" + entry.digest.slice(0, 8) + "-" + slugifyTitle(entry.title) + ".md";
+            const markdown = buildEntryMarkdown({
+                title: entry.title,
+                summary: entry.summary,
+                keywords: entry.keywords,
+                content: entry.content,
+                related_branches: entry.relatedBranches,
+                related_paths: entry.relatedPaths
+            }, { branch: entry.codeBranch, commit: entry.codeCommit, relatedBranches: entry.relatedBranches }, entry.digest, entryDate);
+            const file = await createEntryFile(tmp, baseName, markdown);
+            await git(tmp, ["add", "--", file], gitTimeoutMs);
+            const hash = await commitWithIdentity(tmp, buildAddMessage(entry.title, entry.summary, entry.keywords, entry.digest, true), gitTimeoutMs, { env });
+            created.push({ file, hash });
         }
-        if (current.branches.length !== baselineBranches.length) {
-            throw new GitMemoError("gitmemo: branch set changed since the dry-run baseline — re-run --dry-run");
+        // 6. verify the build before touching the original
+        if (created.length !== entries.length) {
+            throw new GitMemoError("gitmemo: migration entry count mismatch — aborting");
         }
-        // 2. conflicts must be resolved by the user first
-        if (baseline.conflicts.length > 0) {
-            throw new GitMemoError(`gitmemo: migration blocked by ${baseline.conflicts.length} conflict(s) (same entry path, different content across branches):\n` +
-                conflictManifest(baseline.conflicts) +
-                "\nResolve the conflicts, then re-run --dry-run to produce a clean baseline.");
+        const status = (await git(tmp, ["status", "--porcelain"], gitTimeoutMs)).trim();
+        if (status.length > 0) {
+            throw new GitMemoError("gitmemo: migration build tree is dirty: " + status);
         }
-        const legacyStatus = (await git(memDir, ["status", "--porcelain"], gitTimeoutMs)).trim();
-        if (legacyStatus.length > 0) {
-            throw new GitMemoError("gitmemo: legacy memory repository is not clean — migration refuses to discard uncommitted/staged content. " +
-                `Inspect with: git -C ${memDir} status`);
+        for (const createdEntry of created) {
+            const added = await git(tmp, ["diff-tree", "--root", "--no-commit-id", "--name-status", "-r", createdEntry.hash, "--", ENTRY_DIR + "/"], gitTimeoutMs);
+            const lines = added.split("\n").filter((l) => /^A\tentries\/.+\.md$/.test(l));
+            if (lines.length !== 1 || !lines[0].endsWith(createdEntry.file)) {
+                throw new GitMemoError("gitmemo: commit/file mapping mismatch at " + createdEntry.hash + " — aborting");
+            }
         }
-        const legacyJournal = join(memDir, ".git", "gitmemo-transaction.json");
-        try {
-            await readFile(legacyJournal, "utf8");
-            throw new GitMemoError(`gitmemo: legacy repository contains an interrupted transaction journal (${legacyJournal}); repair it before migration`);
+        for (const hash of Object.values(baseline.tips)) {
+            await resolveCommit(tmp, hash, gitTimeoutMs); // old tip must be reachable (via backup refs)
         }
-        catch (error) {
-            if (error instanceof GitMemoError)
-                throw error;
-            if (error.code !== "ENOENT")
-                throw error;
+        // 7. crash-recoverable compare-and-swap. A sibling journal is written
+        // before either rename so search/write never mistake the gap for a fresh
+        // project and initialize an empty `.mem`.
+        const oldDir = join(root, `.mem.gitmemo-old-${ts}`);
+        const targetDir = join(root, ".mem");
+        if (memDir !== targetDir && await access(targetDir).then(() => true).catch(() => false)) {
+            throw new GitMemoError(`gitmemo: migration target ${targetDir} already exists; move it away before migrating from ${memDir}`);
         }
-        // 3. backup refs in the old repo (safety net; also fetched into the new repo)
-        const ts = new Date().toISOString().replace(/[:.]/g, "-");
-        for (const [branch, hash] of Object.entries(baseline.tips)) {
-            await git(memDir, ["update-ref", `refs/gitmemo/backup/${ts}/${branch}`, hash], gitTimeoutMs);
+        const swapJournal = {
+            operationId: randomBytes(8).toString("hex"),
+            sourceDir: memDir,
+            targetDir,
+            oldDir,
+            tmpDir: tmp,
+            phase: "prepared",
+            createdAt: new Date().toISOString()
+        };
+        await writeMigrationSwapJournal(root, swapJournal);
+        if (memDir === targetDir) {
+            await rename(memDir, oldDir);
+            swapJournal.phase = "old-renamed";
+            await writeMigrationSwapJournal(root, swapJournal);
         }
-        // 4. build the new canonical main in a sibling temp repo
-        const tmp = join(root, `.mem.gitmemo-tmp-${process.pid}-${randomBytes(4).toString("hex")}`);
         try {
-            await mkdir(join(tmp, ENTRY_DIR), { recursive: true });
-            await gitInitMain(tmp, gitTimeoutMs);
-            await writeFile(join(tmp, FORMAT_FILE), GITMEMO_FORMAT_VERSION + "\n", "utf8");
-            await writeFile(join(tmp, ENTRY_DIR, ".gitkeep"), "", "utf8");
-            await git(tmp, ["add", "-A", "--", FORMAT_FILE, ENTRY_DIR + "/.gitkeep"], gitTimeoutMs);
-            await commitWithIdentity(tmp, "init: initialize memory repo (gitmemo format 2)", gitTimeoutMs);
-            // fetch old objects + backup refs into the new repo so old hashes stay readable
-            await git(tmp, ["fetch", "-q", memDir, `+refs/heads/*:refs/gitmemo/backup/${ts}/*`], gitTimeoutMs);
-            // 5. one immutable ADD commit per unique entry, preserving old dates
-            const entries = [...baseline.entries].sort((a, b) => a.date.localeCompare(b.date) || a.sourcePath.localeCompare(b.sourcePath));
-            const digests = new Set(entries.map((e) => e.digest));
-            if (digests.size !== entries.length) {
-                throw new GitMemoError("gitmemo: migration plan contains duplicate digests — re-run --dry-run");
-            }
-            const created = [];
-            for (const entry of entries) {
-                const parsedMs = Date.parse(entry.date);
-                const epoch = Number.isFinite(parsedMs) ? Math.floor(parsedMs / 1000) : 0;
-                const env = { GIT_AUTHOR_DATE: "@" + epoch, GIT_COMMITTER_DATE: "@" + epoch };
-                const entryDate = safeLegacyDate(epoch);
-                const baseName = utcMs(entryDate) + "-" + entry.digest.slice(0, 8) + "-" + slugifyTitle(entry.title) + ".md";
-                const markdown = buildEntryMarkdown({
-                    title: entry.title,
-                    summary: entry.summary,
-                    keywords: entry.keywords,
-                    content: entry.content,
-                    related_branches: entry.relatedBranches,
-                    related_paths: entry.relatedPaths
-                }, { branch: entry.codeBranch, commit: entry.codeCommit, relatedBranches: entry.relatedBranches }, entry.digest, entryDate);
-                const file = await createEntryFile(tmp, baseName, markdown);
-                await git(tmp, ["add", "--", file], gitTimeoutMs);
-                const hash = await commitWithIdentity(tmp, buildAddMessage(entry.title, entry.summary, entry.keywords, entry.digest, true), gitTimeoutMs, { env });
-                created.push({ file, hash });
-            }
-            // 6. verify the build before touching the original
-            if (created.length !== entries.length) {
-                throw new GitMemoError("gitmemo: migration entry count mismatch — aborting");
-            }
-            const status = (await git(tmp, ["status", "--porcelain"], gitTimeoutMs)).trim();
-            if (status.length > 0) {
-                throw new GitMemoError("gitmemo: migration build tree is dirty: " + status);
-            }
-            for (const createdEntry of created) {
-                const added = await git(tmp, ["diff-tree", "--root", "--no-commit-id", "--name-status", "-r", createdEntry.hash, "--", ENTRY_DIR + "/"], gitTimeoutMs);
-                const lines = added.split("\n").filter((l) => /^A\tentries\/.+\.md$/.test(l));
-                if (lines.length !== 1 || !lines[0].endsWith(createdEntry.file)) {
-                    throw new GitMemoError("gitmemo: commit/file mapping mismatch at " + createdEntry.hash + " — aborting");
-                }
-            }
-            for (const hash of Object.values(baseline.tips)) {
-                await resolveCommit(tmp, hash, gitTimeoutMs); // old tip must be reachable (via backup refs)
-            }
-            // 7. crash-recoverable compare-and-swap. A sibling journal is written
-            // before either rename so search/write never mistake the gap for a fresh
-            // project and initialize an empty `.mem`.
-            const oldDir = join(root, `.mem.gitmemo-old-${ts}`);
-            const targetDir = join(root, ".mem");
-            if (memDir !== targetDir && await access(targetDir).then(() => true).catch(() => false)) {
-                throw new GitMemoError(`gitmemo: migration target ${targetDir} already exists; move it away before migrating from ${memDir}`);
-            }
-            const swapJournal = {
-                operationId: randomBytes(8).toString("hex"),
-                sourceDir: memDir,
-                targetDir,
-                oldDir,
-                tmpDir: tmp,
-                phase: "prepared",
-                createdAt: new Date().toISOString()
-            };
+            await rename(tmp, targetDir);
+            swapJournal.phase = "new-installed";
             await writeMigrationSwapJournal(root, swapJournal);
-            if (memDir === targetDir) {
-                await rename(memDir, oldDir);
-                swapJournal.phase = "old-renamed";
-                await writeMigrationSwapJournal(root, swapJournal);
-            }
-            try {
-                await rename(tmp, targetDir);
-                swapJournal.phase = "new-installed";
-                await writeMigrationSwapJournal(root, swapJournal);
-            }
-            catch (error) {
-                try {
-                    await recoverMigrationSwap(root, gitTimeoutMs);
-                    if ((await repoFormat(targetDir, gitTimeoutMs)) !== "new")
-                        throw error;
-                }
-                catch (restoreError) {
-                    throw new GitMemoError(`gitmemo: migration swap failed and automatic restore also failed. Old repository remains at ${oldDir}; ` +
-                        `temporary repository is ${tmp}; recovery journal is ${join(root, MIGRATION_JOURNAL_NAME)}. ` +
-                        `Original error: ${String(error)}; restore error: ${String(restoreError)}`);
-                }
-                throw error;
-            }
-            // objects now live in the new repo via the fetch; drop the old directory
+        }
+        catch (error) {
             try {
-                if (memDir === targetDir)
-                    await rm(oldDir, { recursive: true, force: true });
-                await rm(join(root, MIGRATION_JOURNAL_NAME), { force: true });
-            }
-            catch {
-                // The canonical new repo is already installed. Re-run the idempotent
-                // recovery finalizer instead of reporting the migration itself failed.
                 await recoverMigrationSwap(root, gitTimeoutMs);
+                if ((await repoFormat(targetDir, gitTimeoutMs)) !== "new")
+                    throw error;
+            }
+            catch (restoreError) {
+                throw new GitMemoError(`gitmemo: migration swap failed and automatic restore also failed. Old repository remains at ${oldDir}; ` +
+                    `temporary repository is ${tmp}; recovery journal is ${join(root, MIGRATION_JOURNAL_NAME)}. ` +
+                    `Original error: ${String(error)}; restore error: ${String(restoreError)}`);
             }
-            await excludeFromParent(root, gitTimeoutMs);
-            const newMain = (await git(targetDir, ["rev-parse", "HEAD"], gitTimeoutMs)).trim();
-            return {
-                migrated: true,
-                entries: created.length,
-                newMain,
-                backupRefPrefix: `refs/gitmemo/backup/${ts}/`,
-                oldBranches: baselineBranches
-            };
-        }
-        catch (error) {
-            await rm(tmp, { recursive: true, force: true }).catch(() => { });
             throw error;
         }
-    });
+        // objects now live in the new repo via the fetch; drop the old directory
+        try {
+            if (memDir === targetDir)
+                await rm(oldDir, { recursive: true, force: true });
+            await rm(join(root, MIGRATION_JOURNAL_NAME), { force: true });
+        }
+        catch {
+            // The canonical new repo is already installed. Re-run the idempotent
+            // recovery finalizer instead of reporting the migration itself failed.
+            await recoverMigrationSwap(root, gitTimeoutMs);
+        }
+        await excludeFromParent(root, gitTimeoutMs);
+        const newMain = (await git(targetDir, ["rev-parse", "HEAD"], gitTimeoutMs)).trim();
+        return {
+            migrated: true,
+            entries: created.length,
+            newMain,
+            backupRefPrefix: `refs/gitmemo/backup/${ts}/`,
+            oldBranches: baselineBranches
+        };
+    }
+    catch (error) {
+        await rm(tmp, { recursive: true, force: true }).catch(() => { });
+        throw error;
+    }
+}
+/**
+ * Fully automatic migration for engine use: dry-run + apply in one step,
+ * without taking the cross-process lock (the caller must already hold it).
+ *
+ * Never throws for user-resolvable blocking conditions — it returns
+ * `blocked` instead, so the caller can fall back to legacy read-only mode
+ * and retry automatically on a later operation.
+ */
+export async function migrateAutoUnlocked(root, options = {}) {
+    const gitTimeoutMs = options.gitTimeoutMs ?? 60000;
+    const memDir = resolve(options.source ?? join(root, ".mem"));
+    await recoverMigrationSwap(root, gitTimeoutMs);
+    if (!(await isGitRepo(memDir, gitTimeoutMs))) {
+        return { migrated: false, blocked: { code: "no-repo", detail: "no .mem repository at " + memDir } };
+    }
+    if ((await repoFormat(memDir, gitTimeoutMs)) === "new") {
+        return { migrated: false, alreadyNewFormat: true };
+    }
+    let report;
+    try {
+        report = await migrateDryRunUnlocked(root, options);
+    }
+    catch (error) {
+        if (error instanceof GitMemoError) {
+            const code = /no branches/.test(error.message) ? "no-branches" : "other";
+            return { migrated: false, blocked: { code, detail: error.message } };
+        }
+        throw error;
+    }
+    if (!report.legacy)
+        return { migrated: false, alreadyNewFormat: true };
+    if (report.conflictCount > 0) {
+        return {
+            migrated: false,
+            blocked: {
+                code: "conflicts",
+                detail: `${report.conflictCount} conflict(s) (same entry path, different content across branches):\n` +
+                    conflictManifest(report.baseline.conflicts)
+            }
+        };
+    }
+    try {
+        const applied = await migrateApplyUnlocked(root, report.baseline, options);
+        return {
+            migrated: applied.migrated,
+            ...(applied.alreadyMigrated === true ? { alreadyNewFormat: true } : {}),
+            report: applied
+        };
+    }
+    catch (error) {
+        if (error instanceof GitMemoError) {
+            const message = error.message;
+            let code = "other";
+            if (/blocked by \d+ conflict/.test(message))
+                code = "conflicts";
+            else if (/not clean.*refuses to discard/.test(message))
+                code = "dirty";
+            else if (/interrupted transaction journal/.test(message))
+                code = "legacy-journal";
+            else if (/baseline contains no branches/.test(message))
+                code = "no-branches";
+            return { migrated: false, blocked: { code, detail: message } };
+        }
+        throw error;
+    }
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fonlan/dsh-gitmemo",
-  "version": "0.3.0",
-  "description": "Git-backed long-term memory for DeepSeek Harness: a local .mem git repo (single main branch, immutable entries, structured commit messages) with mem_search / mem_read / mem_write / mem_delete / mem_replace tools and an explicit legacy-migration CLI, auto-managed by the root agent with zero manual steps.",
+  "version": "0.3.2",
+  "description": "Git-backed long-term memory for DeepSeek Harness: a local .mem git repo (single main branch, immutable entries, structured commit messages) with mem_search / mem_read / mem_write / mem_delete / mem_replace tools and fully automatic legacy migration (no CLI needed; the CLI remains for explicit control), auto-managed by the root agent with zero manual steps.",
   "author": "fonlan",
   "publishConfig": {
     "access": "public"
@@ -49,8 +49,8 @@
     "release:major": "npm version major && git push && git push --tags"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-tools": "^0.1.0-rc.7",
-    "@deepseek-ai/schemastery": "^3.18.1",
+    "@deepseek-ai/dsh-tools": "^0.1.2-alpha.2",
+    "@deepseek-ai/schemastery": "^3.18.2",
     "@types/node": "^26.2.0",
     "typescript": "^5.5.0"
   },