@lmzhen/dsh-evolution-merge 0.44.0 → 0.45.0

package/lib/index.js

@@ -2,7 +2,7 @@ import { dirname, isAbsolute, join } from "node:path";
 import z from "@deepseek-ai/schemastery";
 import { pairKeyOf, screen, selectCandidates } from "@lmzhen/dsh-evolution-merge-engine";
 import { createUserMessage, defineTool } from "@lmzhen/dsh-evolution-core/platform";
-import { DEFAULT_SKILL_LIMITS, LeaseStore, acquireTreeWriteLock, authorityFrom, contentHash, createSubagentChannel, errorText, evolutionHome, evolutionIoAdapter, isPresent, isProcessAlive, newRunRegistry, policyStageLimits, probeAbsent, probeList, probePresent, probeText, probeUnknown, readTreeLock, registerOwnerSettings, reportsSweepLockTarget, runsFile, scanContentThreats, supportRefs, sweepReports, transactIo } from "@lmzhen/dsh-evolution-core";
+import { DEFAULT_SKILL_LIMITS, HomeAuthority, LeaseStore, authorityFrom, authorityHolder, contentHash, createSubagentChannel, errorText, evolutionHome, evolutionIoAdapter, isPresent, isProcessAlive, leaseAsTreeLock, newRunRegistry, policyStageLimits, probeAbsent, probeList, probePresent, probeText, probeUnknown, reportsSweepLockTarget, runsFile, scanContentThreats, supportRefs, sweepReports, transactIo } from "@lmzhen/dsh-evolution-core";
 import { SkillLibrary, newSkillLibrary, parseFrontmatter, revisionAnchorOf, revisionFingerprint, revisionSupportDigest, validateFrontmatter, validateSupportPath } from "@lmzhen/dsh-evolution-core/skills";
 import { HOST_ROUTES, json, methodNotAllowed, registerHostRoutes } from "@lmzhen/dsh-evolution-core/http-routes";
 import { createHash, randomUUID } from "node:crypto";
@@ -3300,17 +3300,22 @@ var MergeUnitTransactions = class {
 				lock = fenceLease.lock;
 				this.options.onLock?.("tree");
 			} else {
-				const acquired = await acquireTreeWriteLock({
-					io: this.options.io,
+				const fallbackLease = await new HomeAuthority({
 					home: this.options.home,
 					waitMs: this.options.waitMs ?? 5e3
-				});
-				if (!acquired.ok) return {
+				}).lease("tree").catch(() => void 0);
+				if (fallbackLease === void 0) return {
 					ok: false,
 					code: "unit-fence-failed",
-					message: acquired.message ?? acquired.reason
+					message: "tree lock unavailable"
+				};
+				fenceLease = {
+					lock: leaseAsTreeLock(fallbackLease),
+					release: async () => {
+						await fallbackLease.release();
+					}
 				};
-				lock = acquired.lock;
+				lock = fenceLease.lock;
 				this.options.onLock?.("tree");
 			}
 			if (!await lock.assertHeld()) return {
@@ -3691,17 +3696,22 @@ var MergeUnitTransactions = class {
 				fenceLease = await this.options.fence.acquire();
 				lock = fenceLease.lock;
 			} else {
-				const acquired = await acquireTreeWriteLock({
-					io: this.options.io,
+				const fallbackLease = await new HomeAuthority({
 					home: this.options.home,
 					waitMs: this.options.waitMs ?? 5e3
-				});
-				if (!acquired.ok) return {
+				}).lease("tree").catch(() => void 0);
+				if (fallbackLease === void 0) return {
 					ok: false,
 					code: "unit-fence-failed",
-					message: acquired.message ?? acquired.reason
+					message: "tree lock unavailable"
 				};
-				lock = acquired.lock;
+				fenceLease = {
+					lock: leaseAsTreeLock(fallbackLease),
+					release: async () => {
+						await fallbackLease.release();
+					}
+				};
+				lock = fenceLease.lock;
 			}
 			this.options.onLock?.("tree");
 			if (!await lock.assertHeld()) return {
@@ -5025,12 +5035,12 @@ async function mergeDoctor(io, home, configuredRoot) {
 		status: quarantineCount < 0 ? "unknown" : quarantineCount === 0 ? "ok" : "warn",
 		detail: quarantineCount < 0 ? "quarantine 不可读" : quarantineCount + " 行待人工检查"
 	});
-	const holder = await readTreeLock(io, home).catch(() => null);
+	const holder = await authorityHolder(home).catch(() => null);
 	rows.push({
 		key: "tree-lock",
 		label: "tree lock",
 		status: holder == null ? "ok" : "warn",
-		detail: holder == null ? "free" : "holder pid=" + String(holder.pid) + " epoch=" + String(holder.epoch) + " token=" + holder.token.slice(0, 8)
+		detail: holder == null ? "free" : "holder pid=" + String(holder.pid)
 	});
 	const backupPath = v2BackupPath(home);
 	const backupRaw = await readTextOrNull(io, backupPath);
@@ -7860,20 +7870,23 @@ async function runResumeCommand(options) {
 }
 //#endregion
 //#region lib/types/undo-merge.js
-async function undoMergeReceipt(receipt, port) {
-	const targetVersions = (await port.listVersions(receipt.target)).filter((entry) => entry.unitId === receipt.unitId);
-	if (targetVersions.length === 0) return {
-		ok: false,
-		message: "unit " + receipt.unitId + " is not in the target history; refusing to guess",
-		reverted: []
-	};
-	const members = [{
-		skill: receipt.target,
-		entries: targetVersions,
-		status: "live",
-		...receipt.create ? { createdInUnit: true } : {}
-	}];
-	for (const source of receipt.sources) {
+async function undoMergeReceipt(receipt, port, options = {}) {
+	const members = [];
+	if (options.skipTarget !== true) {
+		const targetVersions = (await port.listVersions(receipt.target)).filter((entry) => entry.unitId === receipt.unitId);
+		if (targetVersions.length === 0) return {
+			ok: false,
+			message: "unit " + receipt.unitId + " is not in the target history; refusing to guess",
+			reverted: []
+		};
+		members.push({
+			skill: receipt.target,
+			entries: targetVersions,
+			status: "live",
+			...receipt.create ? { createdInUnit: true } : {}
+		});
+	}
+	if (options.skipSources !== true) for (const source of receipt.sources) {
 		const live = await port.readSkill(source);
 		members.push({
 			skill: source,
@@ -7882,6 +7895,11 @@ async function undoMergeReceipt(receipt, port) {
 			...live === null ? { archivedPath: "archive" } : {}
 		});
 	}
+	if (members.length === 0) return {
+		ok: true,
+		message: "nothing left to restore",
+		reverted: []
+	};
 	const plan = planUnitUndoAcross(members);
 	if (plan.refusals.length > 0) return {
 		ok: false,
@@ -7896,6 +7914,15 @@ async function undoMergeReceipt(receipt, port) {
 function undoJournalPath(home, runId) {
 	return join(home, "merge", "undo-journal", encodeURIComponent(runId) + ".json");
 }
+async function readUndoJournal(io, home, runId) {
+	const raw = await readTextOrNull(io, undoJournalPath(home, runId));
+	if (raw === null) return null;
+	try {
+		return JSON.parse(raw);
+	} catch {
+		return null;
+	}
+}
 async function writeUndoJournal(io, home, journal) {
 	await transactIo(io, undoJournalPath(home, journal.runId), () => JSON.stringify(journal, null, 2) + "\n");
 }
@@ -7990,7 +8017,20 @@ async function settleRun(io, home, runId, pairKey, allPairs, at) {
 		updatedAt: new Date(at).toISOString()
 	});
 }
+/**
+* Run one merge-undo pass.
+*
+* The fence, when the caller supplies one, covers the WHOLE pass: undo writes the skill tree, the
+* undo receipt, the pair index and run metadata, so a pass that lost exclusion halfway would
+* interleave with the commit it is undoing (W9-commit-protocol §3.2). A partially applied pair is
+* reported as `resumable` rather than refused: the journal records the phase, and
+* `resumeUndo` continues from it.
+*/
 async function runUndoOperation(options) {
+	const run = async () => await runUndoSteps(options);
+	return options.fence === void 0 ? await run() : await options.fence.run(run);
+}
+async function runUndoSteps(options) {
 	const runReceipts = (await readCommitReceipts(options.io, options.home)).filter((receipt) => (receipt.parentRunId ?? receipt.runId) === options.runId);
 	const allPairKeys = runReceipts.map((receipt) => receipt.pairKey ?? receipt.unitId);
 	const allReceipts = runReceipts.filter((receipt) => options.target === void 0 || receipt.target === options.target);
@@ -8015,6 +8055,20 @@ async function runUndoOperation(options) {
 	const undone = [];
 	for (const receipt of sortReceipts(receipts)) {
 		const pairKey = receipt.pairKey ?? receipt.unitId;
+		/** Record the durable phase before the step it names (W9-commit-protocol §3.1). */
+		const markPhase = async (next) => {
+			const current = await readUndoJournal(options.io, options.home, options.runId);
+			if (current === null) return;
+			await writeUndoJournal(options.io, options.home, {
+				...current,
+				phase: "running",
+				pairs: current.pairs.map((pair) => pair.pairKey === pairKey ? {
+					...pair,
+					phase: next
+				} : pair),
+				updatedAt: new Date(options.now()).toISOString()
+			});
+		};
 		if (options.finalizeUnit !== void 0) {
 			const finalized = await options.finalizeUnit(receipt.unitId);
 			if (!finalized.ok) return {
@@ -8024,6 +8078,7 @@ async function runUndoOperation(options) {
 			};
 		}
 		if (await readUndoReceipt(options.io, options.home, options.runId, pairKey) !== null) {
+			await markPhase("pair-index");
 			await options.onPhase?.("pair-index", pairKey);
 			await recordPair(options.io, options.home, {
 				pairKey,
@@ -8031,6 +8086,7 @@ async function runUndoOperation(options) {
 				result: "undone",
 				target: receipt.target
 			});
+			await markPhase("run-meta");
 			await options.onPhase?.("run-meta", pairKey);
 			await settleRun(options.io, options.home, options.runId, pairKey, allPairKeys, options.now());
 			undone.push(pairKey);
@@ -8056,6 +8112,7 @@ async function runUndoOperation(options) {
 				restoredSourceHashes: Object.fromEntries(checked.evidence.sources.map((source) => [source.name, contentHash(source.before)])),
 				at: options.now()
 			});
+			await markPhase("pair-index");
 			await options.onPhase?.("pair-index", pairKey);
 			await recordPair(options.io, options.home, {
 				pairKey,
@@ -8063,21 +8120,15 @@ async function runUndoOperation(options) {
 				result: "undone",
 				target: receipt.target
 			});
+			await markPhase("run-meta");
 			await options.onPhase?.("run-meta", pairKey);
 			await settleRun(options.io, options.home, options.runId, pairKey, allPairKeys, options.now());
 			undone.push(pairKey);
 			continue;
 		}
-		if (!checked.targetDone || !checked.sourcesDone) {
-			const targetStage = checked.targetDone ? "skip" : "restore";
-			const sourceStage = checked.sourcesDone ? "skip" : "restore";
-			if (targetStage === "skip" && sourceStage === "skip") {}
-		}
-		if (checked.targetDone !== checked.sourcesDone && (checked.targetDone || checked.sourcesDone)) return {
-			ok: false,
-			code: "undo-partial-state",
-			message: "undo is partially applied; manual retry required",
-			undone
+		const skip = {
+			...checked.targetDone ? { skipTarget: true } : {},
+			...checked.sourcesDone ? { skipSources: true } : {}
 		};
 		const phase = (next) => ({
 			pairKey,
@@ -8092,11 +8143,12 @@ async function runUndoOperation(options) {
 			updatedAt: new Date(options.now()).toISOString()
 		});
 		await options.onPhase?.("restore-target", pairKey);
-		const executed = await undoMergeReceipt(receipt, options.port);
+		const executed = await undoMergeReceipt(receipt, options.port, skip);
 		if (!executed.ok) return {
 			ok: false,
 			message: executed.message,
-			undone
+			undone,
+			resumable: true
 		};
 		await writeUndoJournal(options.io, options.home, {
 			version: 1,
@@ -11325,7 +11377,6 @@ function formatUnreadyError() {
 }
 const inject = [];
 function apply(ctx, rawConfig = {}) {
-	registerOwnerSettings(ctx, "evolution-merge", Config);
 	configureMergePresentation(ctx);
 	const startupParams = resolveMergeParams(rawConfig);
 	let mergeRun;

package/lib/types/doctor.js

@@ -7,7 +7,7 @@ import { readTextOrNull } from "./domain/read-probe.js";
 import { createHash } from 'node:crypto';
 import { stat } from 'node:fs/promises';
 import { join } from 'node:path';
-import { probeList, readTreeLock, runsFile } from '@lmzhen/dsh-evolution-core';
+import { authorityHolder, probeList, runsFile } from '@lmzhen/dsh-evolution-core';
 import { readUnitJournal } from '@lmzhen/dsh-evolution-core/write';
 import { migrationJournalPath, migrationReportPath, v2BackupPath } from "./domain/state-bootstrap.js";
 import { readMergeSnapshot } from "./domain/merge-snapshot.js";
@@ -104,8 +104,8 @@ export async function mergeDoctor(io, home, configuredRoot) {
         quarantineCount = -1;
     }
     rows.push({ key: 'quarantine', label: 'quarantine', status: quarantineCount < 0 ? 'unknown' : quarantineCount === 0 ? 'ok' : 'warn', detail: quarantineCount < 0 ? 'quarantine 不可读' : quarantineCount + ' 行待人工检查' });
-    const holder = await readTreeLock(io, home).catch(() => null);
-    rows.push({ key: 'tree-lock', label: 'tree lock', status: holder == null ? 'ok' : 'warn', detail: holder == null ? 'free' : 'holder pid=' + String(holder.pid) + ' epoch=' + String(holder.epoch) + ' token=' + holder.token.slice(0, 8) });
+    const holder = await authorityHolder(home).catch(() => null);
+    rows.push({ key: 'tree-lock', label: 'tree lock', status: holder == null ? 'ok' : 'warn', detail: holder == null ? 'free' : 'holder pid=' + String(holder.pid) });
     const backupPath = v2BackupPath(home);
     const backupRaw = await readTextOrNull(io, backupPath);
     const backupMode = await stat(backupPath).then(value => value.mode).catch(() => null);

package/lib/types/domain/undo-journal.d.ts

@@ -1,5 +1,6 @@
 import { type EvolutionIoLike } from '@lmzhen/dsh-evolution-core';
-export type UndoPairPhase = 'pending' | 'restore-target' | 'restore-source' | 'receipt' | 'done';
+import type { JournalProtocol } from '@lmzhen/dsh-evolution-core';
+export type UndoPairPhase = 'pending' | 'restore-target' | 'restore-source' | 'receipt' | 'pair-index' | 'run-meta' | 'done';
 export interface UndoPairState {
     readonly pairKey: string;
     readonly unitId: string;
@@ -13,6 +14,12 @@ export interface UndoJournal {
     readonly pairs: readonly UndoPairState[];
     readonly updatedAt: string;
 }
+/**
+ * The undo journal's protocol (W9-commit-protocol §3.1): `pair-index` and `run-meta` are explicit
+ * phases, because "the receipt was written but the pair index was not" is exactly the state a
+ * restart has to recognise.
+ */
+export declare const UNDO_PAIR_PROTOCOL: JournalProtocol<UndoPairPhase>;
 export declare function undoJournalPath(home: string, runId: string): string;
 export declare function readUndoJournal(io: EvolutionIoLike, home: string, runId: string): Promise<UndoJournal | null>;
 export declare function writeUndoJournal(io: EvolutionIoLike, home: string, journal: UndoJournal): Promise<void>;

package/lib/types/domain/undo-journal.js

@@ -2,6 +2,35 @@ import { readTextOrNull } from "./read-probe.js";
 /** Per-run undo journal: one pair at a time, durable phase before each write. */
 import { join } from 'node:path';
 import { transactIo } from '@lmzhen/dsh-evolution-core';
+/**
+ * The undo journal's protocol (W9-commit-protocol §3.1): `pair-index` and `run-meta` are explicit
+ * phases, because "the receipt was written but the pair index was not" is exactly the state a
+ * restart has to recognise.
+ */
+export const UNDO_PAIR_PROTOCOL = {
+    phases: ['pending', 'restore-target', 'restore-source', 'receipt', 'pair-index', 'run-meta', 'done'],
+    next: {
+        pending: ['restore-target', 'receipt', 'done'],
+        'restore-target': ['restore-source', 'receipt'],
+        'restore-source': ['receipt'],
+        receipt: ['pair-index'],
+        'pair-index': ['run-meta'],
+        'run-meta': ['done'],
+        done: [],
+    },
+    recoveryOf(phase) {
+        switch (phase) {
+            case 'done': return 'done';
+            case 'pending': return 'retry';
+            case 'restore-target':
+            case 'restore-source':
+            case 'receipt':
+            case 'pair-index':
+            case 'run-meta': return 'continue';
+            default: return 'refuse';
+        }
+    },
+};
 export function undoJournalPath(home, runId) { return join(home, 'merge', 'undo-journal', encodeURIComponent(runId) + '.json'); }
 export async function readUndoJournal(io, home, runId) {
     const raw = await readTextOrNull(io, undoJournalPath(home, runId));

package/lib/types/index.js

@@ -5,7 +5,6 @@ import { selectWithErrors } from "./adapters/select.js";
 import { createEngineScreening } from "./adapters/engine-screen.js";
 import { createEngineRunner } from "./adapters/model-runner.js";
 import { authorityFrom, createSubagentChannel, evolutionHome, evolutionIoAdapter, newRunRegistry, reportsSweepLockTarget, sweepReports, transactIo } from '@lmzhen/dsh-evolution-core';
-import { registerOwnerSettings } from '@lmzhen/dsh-evolution-core';
 import { newSkillLibrary } from '@lmzhen/dsh-evolution-core/skills';
 import { registerHostRoutes } from '@lmzhen/dsh-evolution-core/http-routes';
 import { loadMergeState } from "./state.js";
@@ -137,7 +136,6 @@ function formatUnreadyError() {
 }
 export const inject = [];
 export function apply(ctx, rawConfig = {}) {
-    registerOwnerSettings(ctx, 'evolution-merge', Config);
     configureMergePresentation(ctx);
     const startupParams = resolveMergeParams(rawConfig);
     let mergeRun;

package/lib/types/undo-merge.d.ts

@@ -9,5 +9,11 @@ import type { CommitReceipt } from './commit-receipt.ts';
 export interface MergeUndoPort extends UnitUndoSink {
     listVersions(skill: string): Promise<readonly SkillVersion[]>;
 }
-export declare function undoMergeReceipt(receipt: CommitReceipt, port: MergeUndoPort): Promise<UnitUndoExecution>;
+export interface UndoMergeOptions {
+    /** The target already holds its pre-commit content (a resumed pass). */
+    readonly skipTarget?: boolean;
+    /** Every source already holds its pre-commit content (a resumed pass). */
+    readonly skipSources?: boolean;
+}
+export declare function undoMergeReceipt(receipt: CommitReceipt, port: MergeUndoPort, options?: UndoMergeOptions): Promise<UnitUndoExecution>;
 //# sourceMappingURL=undo-merge.d.ts.map

package/lib/types/undo-merge.js

@@ -1,19 +1,26 @@
 import { executeUnitUndo, planUnitUndoAcross } from '@lmzhen/dsh-evolution-core/write';
-export async function undoMergeReceipt(receipt, port) {
-    const targetVersions = (await port.listVersions(receipt.target)).filter(entry => entry.unitId === receipt.unitId);
-    if (targetVersions.length === 0) {
-        return { ok: false, message: 'unit ' + receipt.unitId + ' is not in the target history; refusing to guess', reverted: [] };
+export async function undoMergeReceipt(receipt, port, options = {}) {
+    const members = [];
+    if (options.skipTarget !== true) {
+        const targetVersions = (await port.listVersions(receipt.target)).filter(entry => entry.unitId === receipt.unitId);
+        if (targetVersions.length === 0) {
+            return { ok: false, message: 'unit ' + receipt.unitId + ' is not in the target history; refusing to guess', reverted: [] };
+        }
+        members.push({ skill: receipt.target, entries: targetVersions, status: 'live', ...(receipt.create ? { createdInUnit: true } : {}) });
     }
-    const members = [{ skill: receipt.target, entries: targetVersions, status: 'live', ...(receipt.create ? { createdInUnit: true } : {}) }];
-    for (const source of receipt.sources) {
-        const live = await port.readSkill(source);
-        members.push({
-            skill: source,
-            entries: (await port.listVersions(source)).filter(entry => entry.unitId === receipt.unitId),
-            status: live === null ? 'archived' : 'live',
-            ...(live === null ? { archivedPath: 'archive' } : {}),
-        });
+    if (options.skipSources !== true) {
+        for (const source of receipt.sources) {
+            const live = await port.readSkill(source);
+            members.push({
+                skill: source,
+                entries: (await port.listVersions(source)).filter(entry => entry.unitId === receipt.unitId),
+                status: live === null ? 'archived' : 'live',
+                ...(live === null ? { archivedPath: 'archive' } : {}),
+            });
+        }
     }
+    if (members.length === 0)
+        return { ok: true, message: 'nothing left to restore', reverted: [] };
     const plan = planUnitUndoAcross(members);
     if (plan.refusals.length > 0) {
         return { ok: false, message: 'merge undo preflight refused: ' + plan.refusals.join('; '), reverted: [] };

package/lib/types/undo-operation.d.ts

@@ -6,9 +6,10 @@ export interface UndoResult {
     readonly ok: boolean;
     readonly code?: UndoErrorCode;
     readonly message: string;
-    readonly undone: readonly string[];
+    readonly undone: readonly string[]; /** True when a journal phase remains and `resumeUndo` can continue. */
+    readonly resumable?: boolean;
 }
-export declare function runUndoOperation(options: {
+type UndoOperationOptions = {
     readonly io: EvolutionIoLike;
     readonly home: string;
     readonly runId: string;
@@ -24,5 +25,16 @@ export declare function runUndoOperation(options: {
     readonly fence?: {
         run<T>(body: () => Promise<T>): Promise<T>;
     };
-}): Promise<UndoResult>;
+};
+/**
+ * Run one merge-undo pass.
+ *
+ * The fence, when the caller supplies one, covers the WHOLE pass: undo writes the skill tree, the
+ * undo receipt, the pair index and run metadata, so a pass that lost exclusion halfway would
+ * interleave with the commit it is undoing (W9-commit-protocol §3.2). A partially applied pair is
+ * reported as `resumable` rather than refused: the journal records the phase, and
+ * `resumeUndo` continues from it.
+ */
+export declare function runUndoOperation(options: UndoOperationOptions): Promise<UndoResult>;
+export {};
 //# sourceMappingURL=undo-operation.d.ts.map

package/lib/types/undo-operation.js

@@ -1,7 +1,7 @@
 import { contentHash } from '@lmzhen/dsh-evolution-core';
 import { readCommitReceipts } from "./commit-receipt.js";
 import { undoMergeReceipt } from "./undo-merge.js";
-import { writeUndoJournal } from "./domain/undo-journal.js";
+import { readUndoJournal, writeUndoJournal } from "./domain/undo-journal.js";
 import { readUndoReceipt, writeUndoReceipt } from "./domain/undo-receipt.js";
 import { recordPair } from "./domain/pair-index-store.js";
 import { readRunMeta, writeRunMeta } from "./domain/run-coordinator.js";
@@ -71,7 +71,20 @@ async function settleRun(io, home, runId, pairKey, allPairs, at) {
         createdAt: current?.createdAt ?? new Date(at).toISOString(), updatedAt: new Date(at).toISOString(),
     });
 }
+/**
+ * Run one merge-undo pass.
+ *
+ * The fence, when the caller supplies one, covers the WHOLE pass: undo writes the skill tree, the
+ * undo receipt, the pair index and run metadata, so a pass that lost exclusion halfway would
+ * interleave with the commit it is undoing (W9-commit-protocol §3.2). A partially applied pair is
+ * reported as `resumable` rather than refused: the journal records the phase, and
+ * `resumeUndo` continues from it.
+ */
 export async function runUndoOperation(options) {
+    const run = async () => await runUndoSteps(options);
+    return options.fence === undefined ? await run() : await options.fence.run(run);
+}
+async function runUndoSteps(options) {
     const runReceipts = (await readCommitReceipts(options.io, options.home)).filter(receipt => (receipt.parentRunId ?? receipt.runId) === options.runId);
     const allPairKeys = runReceipts.map(receipt => receipt.pairKey ?? receipt.unitId);
     const allReceipts = runReceipts.filter(receipt => options.target === undefined || receipt.target === options.target);
@@ -83,6 +96,18 @@ export async function runUndoOperation(options) {
     const undone = [];
     for (const receipt of sortReceipts(receipts)) {
         const pairKey = receipt.pairKey ?? receipt.unitId;
+        /** Record the durable phase before the step it names (W9-commit-protocol §3.1). */
+        const markPhase = async (next) => {
+            const current = await readUndoJournal(options.io, options.home, options.runId);
+            if (current === null)
+                return;
+            await writeUndoJournal(options.io, options.home, {
+                ...current,
+                phase: 'running',
+                pairs: current.pairs.map(pair => (pair.pairKey === pairKey ? { ...pair, phase: next } : pair)),
+                updatedAt: new Date(options.now()).toISOString(),
+            });
+        };
         if (options.finalizeUnit !== undefined) {
             const finalized = await options.finalizeUnit(receipt.unitId);
             if (!finalized.ok)
@@ -90,8 +115,10 @@ export async function runUndoOperation(options) {
         }
         const existing = await readUndoReceipt(options.io, options.home, options.runId, pairKey);
         if (existing !== null) {
+            await markPhase('pair-index');
             await options.onPhase?.('pair-index', pairKey);
             await recordPair(options.io, options.home, { pairKey, runId: options.runId, result: 'undone', target: receipt.target });
+            await markPhase('run-meta');
             await options.onPhase?.('run-meta', pairKey);
             await settleRun(options.io, options.home, options.runId, pairKey, allPairKeys, options.now());
             undone.push(pairKey);
@@ -103,27 +130,27 @@ export async function runUndoOperation(options) {
         if (checked.done) {
             await options.onPhase?.('receipt', pairKey);
             await writeUndoReceipt(options.io, options.home, { version: 1, runId: options.runId, ...(receipt.parentRunId === undefined ? {} : { parentRunId: receipt.parentRunId }), pairKey, unitId: receipt.unitId, evidenceSha256: receipt.evidenceSha256 ?? unitEvidenceDigest(checked.evidence), target: receipt.target, sources: checked.evidence.sources.map(source => source.name), restoredTargetHash: receipt.create ? null : digest(checked.evidence.target.before), restoredSourceHashes: Object.fromEntries(checked.evidence.sources.map(source => [source.name, contentHash(source.before)])), at: options.now() });
+            await markPhase('pair-index');
             await options.onPhase?.('pair-index', pairKey);
             await recordPair(options.io, options.home, { pairKey, runId: options.runId, result: 'undone', target: receipt.target });
+            await markPhase('run-meta');
             await options.onPhase?.('run-meta', pairKey);
             await settleRun(options.io, options.home, options.runId, pairKey, allPairKeys, options.now());
             undone.push(pairKey);
             continue;
         }
-        if (!checked.targetDone || !checked.sourcesDone) {
-            const targetStage = checked.targetDone ? 'skip' : 'restore';
-            const sourceStage = checked.sourcesDone ? 'skip' : 'restore';
-            if (targetStage === 'skip' && sourceStage === 'skip') { /* unreachable, done */ }
-        }
-        if (checked.targetDone !== checked.sourcesDone && (checked.targetDone || checked.sourcesDone)) {
-            return { ok: false, code: 'undo-partial-state', message: 'undo is partially applied; manual retry required', undone };
-        }
+        // A resumed pass continues from what the previous attempt already restored: the plan is built
+        // from the missing side only, so re-running the pass is idempotent instead of refused.
+        const skip = {
+            ...(checked.targetDone ? { skipTarget: true } : {}),
+            ...(checked.sourcesDone ? { skipSources: true } : {}),
+        };
         const phase = (next) => ({ pairKey, unitId: receipt.unitId, phase: next });
         await writeUndoJournal(options.io, options.home, { version: 1, runId: options.runId, phase: 'running', pairs: pairs.map(pair => pair.pairKey === pairKey ? phase('restore-target') : pair), updatedAt: new Date(options.now()).toISOString() });
         await options.onPhase?.('restore-target', pairKey);
-        const executed = await undoMergeReceipt(receipt, options.port);
+        const executed = await undoMergeReceipt(receipt, options.port, skip);
         if (!executed.ok)
-            return { ok: false, message: executed.message, undone };
+            return { ok: false, message: executed.message, undone, resumable: true };
         await writeUndoJournal(options.io, options.home, { version: 1, runId: options.runId, phase: 'running', pairs: pairs.map(pair => pair.pairKey === pairKey ? phase('restore-source') : pair), updatedAt: new Date(options.now()).toISOString() });
         await options.onPhase?.('restore-source', pairKey);
         await writeUndoJournal(options.io, options.home, { version: 1, runId: options.runId, phase: 'running', pairs: pairs.map(pair => pair.pairKey === pairKey ? phase('receipt') : pair), updatedAt: new Date(options.now()).toISOString() });

package/lib/types/undo-resume.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Resume an interrupted merge undo from its journal (W9-commit-protocol §3.2).
+ *
+ * The pass itself is idempotent: a pair whose target or sources already hold their pre-commit
+ * content is planned from the missing side only. What a resume needs from the journal is therefore
+ * not step replay but a decision — is there anything left, and may it continue? That is what this
+ * entry point answers before delegating to the same pass.
+ * @module @lmzhen/dsh-evolution-merge/undo-resume
+ */
+import type { EvolutionIoLike } from '@lmzhen/dsh-evolution-core';
+import { type UndoResult } from './undo-operation.ts';
+import type { MergeUndoPort } from './undo-merge.ts';
+export interface ResumeUndoOptions {
+    readonly io: EvolutionIoLike;
+    readonly home: string;
+    readonly runId: string;
+    readonly port: MergeUndoPort;
+    readonly now: () => number;
+    readonly pairKey?: string;
+    readonly target?: string;
+    readonly finalizeUnit?: (unitId: string) => Promise<{
+        readonly ok: boolean;
+        readonly message?: string;
+    }>;
+    readonly onPhase?: (phase: string, pairKey: string) => void | Promise<void>;
+    readonly fence?: {
+        run<T>(body: () => Promise<T>): Promise<T>;
+    };
+}
+/**
+ * Continue an undo that stopped in a non-terminal phase.
+ * @param options - the same inputs the original pass took.
+ * @returns the pass result, or a refusal when there is nothing to resume.
+ */
+export declare function resumeUndo(options: ResumeUndoOptions): Promise<UndoResult>;
+//# sourceMappingURL=undo-resume.d.ts.map

package/lib/types/undo-resume.js

@@ -0,0 +1,18 @@
+import { readUndoJournal } from "./domain/undo-journal.js";
+import { runUndoOperation } from "./undo-operation.js";
+/**
+ * Continue an undo that stopped in a non-terminal phase.
+ * @param options - the same inputs the original pass took.
+ * @returns the pass result, or a refusal when there is nothing to resume.
+ */
+export async function resumeUndo(options) {
+    const journal = await readUndoJournal(options.io, options.home, options.runId);
+    if (journal === null) {
+        return { ok: false, code: 'undo-partial-state', message: 'no readable undo journal for run ' + options.runId + '; nothing to resume', undone: [] };
+    }
+    if (journal.pairs.every(pair => pair.phase === 'done')) {
+        return { ok: true, message: 'undo already settled: ' + options.runId, undone: [] };
+    }
+    return await runUndoOperation(options);
+}
+//# sourceMappingURL=undo-resume.js.map

package/lib/types/unit-protocol.js

@@ -1,6 +1,6 @@
 /** G2 opaque UnitTransaction. Core owns prepare/commit/verify/rollback lifecycle. */
 import { createHash } from "node:crypto";
-import { acquireTreeWriteLock } from '@lmzhen/dsh-evolution-core';
+import { HomeAuthority, leaseAsTreeLock } from '@lmzhen/dsh-evolution-core';
 import { readUnitEvidence, readUnitReceipt, readUnitIndex, readUnitSnapshot, unitStorageKey, writeUnitEvidence, writeUnitReceipt, writeUnitSnapshot, } from '@lmzhen/dsh-evolution-core/write';
 import { readUnitJournal, writeUnitJournal } from '@lmzhen/dsh-evolution-core/write';
 function canonicalJson(value) {
@@ -163,10 +163,12 @@ export class MergeUnitTransactions {
                 this.options.onLock?.("tree");
             }
             else {
-                const acquired = await acquireTreeWriteLock({ io: this.options.io, home: this.options.home, waitMs: this.options.waitMs ?? 5000 });
-                if (!acquired.ok)
-                    return { ok: false, code: "unit-fence-failed", message: acquired.message ?? acquired.reason };
-                lock = acquired.lock;
+                const fallback = new HomeAuthority({ home: this.options.home, waitMs: this.options.waitMs ?? 5000 });
+                const fallbackLease = await fallback.lease("tree").catch(() => undefined);
+                if (fallbackLease === undefined)
+                    return { ok: false, code: "unit-fence-failed", message: "tree lock unavailable" };
+                fenceLease = { lock: leaseAsTreeLock(fallbackLease), release: async () => { await fallbackLease.release(); } };
+                lock = fenceLease.lock;
                 this.options.onLock?.("tree");
             }
             if (!(await lock.assertHeld()))
@@ -476,10 +478,12 @@ export class MergeUnitTransactions {
                 lock = fenceLease.lock;
             }
             else {
-                const acquired = await acquireTreeWriteLock({ io: this.options.io, home: this.options.home, waitMs: this.options.waitMs ?? 5000 });
-                if (!acquired.ok)
-                    return { ok: false, code: "unit-fence-failed", message: acquired.message ?? acquired.reason };
-                lock = acquired.lock;
+                const fallback = new HomeAuthority({ home: this.options.home, waitMs: this.options.waitMs ?? 5000 });
+                const fallbackLease = await fallback.lease("tree").catch(() => undefined);
+                if (fallbackLease === undefined)
+                    return { ok: false, code: "unit-fence-failed", message: "tree lock unavailable" };
+                fenceLease = { lock: leaseAsTreeLock(fallbackLease), release: async () => { await fallbackLease.release(); } };
+                lock = fenceLease.lock;
             }
             this.options.onLock?.("tree");
             if (!(await lock.assertHeld()))

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lmzhen/dsh-evolution-merge",
   "description": "Skill auto-merge domain: screening, two-round authoring, queues and commit orchestration (community build)",
-  "version": "0.44.0",
+  "version": "0.45.0",
   "publishConfig": {
     "access": "public"
   },
@@ -34,9 +34,9 @@
   },
   "dependencies": {
     "@deepseek-ai/schemastery": "^3.18.5",
-    "@lmzhen/dsh-evolution-core": "^0.44.0",
-    "@lmzhen/dsh-evolution-commands": "^0.44.0",
-    "@lmzhen/dsh-evolution-merge-engine": "0.44.0"
+    "@lmzhen/dsh-evolution-core": "^0.45.0",
+    "@lmzhen/dsh-evolution-commands": "^0.45.0",
+    "@lmzhen/dsh-evolution-merge-engine": "0.45.0"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.5"