@lmzhen/dsh-evolution-merge 0.39.1 → 0.40.0

package/lib/types/approve-command.d.ts

@@ -19,6 +19,9 @@ export interface ApprovePorts {
 }
 export interface RunApproveCommandOptions {
     readonly io: EvolutionIoLike;
+    readonly fence?: {
+        run<T>(body: () => Promise<T>): Promise<T>;
+    };
     readonly home: string;
     readonly registry: MergeRegistryPort;
     readonly ports: ApprovePorts;
@@ -30,6 +33,7 @@ export interface RunApproveCommandOptions {
     readonly now: () => number;
     /** The invocation carried no agent at all (E-305), as opposed to an agent with no parent run. */
     readonly agentless?: boolean;
+    readonly isOwnerActive?: (runId: string) => boolean | Promise<boolean>;
 }
 export declare function runApproveCommand(options: RunApproveCommandOptions): Promise<WithMergeRunResult>;
 //# sourceMappingURL=approve-command.d.ts.map

package/lib/types/approve-command.js

@@ -24,7 +24,7 @@ export async function runApproveCommand(options) {
     const parentRunId = options.parentRunId ?? before.runId;
     if (parentRunId === undefined)
         return failure('approve', 'merge-parent-required', '缺 parent run id（E-305 提示：该行可能由无会话调用创建，或父 run 已丢失）', '在 agent 会话中执行 /evolution merge approve ' + before.id, before.runId);
-    const taken = await approvePending(options.io, options.home, options.now, options.rowId);
+    const taken = await approvePending(options.io, options.home, options.now, options.rowId, options.fence);
     if (!taken.ok)
         return failure('approve', 'approve-' + taken.reason, taken.message, '重试；若行状态已变化，运行 /evolution merge status ' + options.rowId, before.runId);
     let row = taken.row;
@@ -35,7 +35,7 @@ export async function runApproveCommand(options) {
         const staged = await options.ports.stage(row, decision);
         if (!staged.ok)
             return failure('approve', 'stage-failed', staged.message, '检查暂存目录后重试；不影响已记录的决策', row.runId);
-        const fused = await pairLedger(options.io, options.home).transact(tx => {
+        const fused = await pairLedger(options.io, options.home, options.fence).transact(tx => {
             const current = tx.rows().find(item => item.id === row.id);
             if (current === undefined)
                 return null;
@@ -51,6 +51,7 @@ export async function runApproveCommand(options) {
         io: options.io,
         home: options.home,
         registry: options.registry,
+        ...(options.fence === undefined ? {} : { fence: options.fence }),
         command: 'approve',
         approval: { platformWrite: options.platformWrite, mergeApproval: true },
         pairKey: row.pairKey,
@@ -59,7 +60,7 @@ export async function runApproveCommand(options) {
         now: options.now,
         ...(options.detached === true ? { detached: true } : {}),
         async body(ctx) {
-            await attachRunToRow(options.io, options.home, row.id, ctx.runId);
+            await attachRunToRow(options.io, options.home, row.id, ctx.runId, options.isOwnerActive, options.fence);
             const stage = (name) => ctx.stage(name, { done: 0, total: 1 });
             await stage('author');
             let outcome;
@@ -70,7 +71,7 @@ export async function runApproveCommand(options) {
                 outcome = { kind: 'failed', failure: { stage: 'author', code: 'merge-failed', message: error instanceof Error ? error.message : String(error), retryable: true, retryFrom: 'agent2' } };
             }
             const base = { scope: { candidatePairs: 1, queueBefore: { verify: 0, pending: 0, fuse: 1, skipped: 0 } }, notes: [] };
-            const record = await recordRound2Outcome(options.io, options.home, options.now, row, outcome, true);
+            const record = await recordRound2Outcome(options.io, options.home, options.now, row, outcome, true, options.fence);
             return {
                 ...base,
                 stopReason: record.merged ? 'completed' : 'failed',

package/lib/types/domain/pair-ledger.d.ts

@@ -23,7 +23,9 @@ export interface NormalizeResult {
 /** Read-only 1b-1 bypass. It does not normalize, back up, or write state. */
 export declare function readPairLedger(io: EvolutionIoLike, home: string): Promise<PairLedgerRead>;
 /** 1b-2a write skeleton. Production stays on the v3 gate until 1b-2b. */
-export declare function pairLedger(io: EvolutionIoLike, home: string): PairLedger;
+export declare function pairLedger(io: EvolutionIoLike, home: string, fence?: {
+    run<T>(body: () => Promise<T>): Promise<T>;
+}): PairLedger;
 /** v3-to-v4 normalize: backup -> production stage adopt -> v4 state. Not called in 1b-2a. */
 export declare function normalizePairLedger(io: EvolutionIoLike, home: string): Promise<NormalizeResult>;
 /** Read schema4 rows only; no legacy projection. */

package/lib/types/domain/pair-ledger.js

@@ -31,7 +31,7 @@ export async function readPairLedger(io, home) {
     };
 }
 /** 1b-2a write skeleton. Production stays on the v3 gate until 1b-2b. */
-export function pairLedger(io, home) {
+export function pairLedger(io, home, fence) {
     return {
         read: () => readPairLedger(io, home),
         transact: async (fn) => {
@@ -41,7 +41,7 @@ export function pairLedger(io, home) {
                 if (!normalized.ok)
                     throw new Error(normalized.message ?? 'normalize failed');
             }
-            return await transactMergeState(io, home, fn);
+            return await transactMergeState(io, home, fn, fence);
         },
         normalize: () => normalizePairLedger(io, home),
     };

package/lib/types/domain/row-run.d.ts

@@ -1,4 +1,6 @@
-import type { EvolutionIoLike } from '@lmzhen/dsh-evolution-core';
+import { type EvolutionIoLike } from '@lmzhen/dsh-evolution-core';
 /** Attach the in-flight child run to a row before its round2 starts (P1-8). */
-export declare function attachRunToRow(io: EvolutionIoLike, home: string, rowId: string, runId: string): Promise<void>;
+export declare function attachRunToRow(io: EvolutionIoLike, home: string, rowId: string, runId: string, isActive?: (id: string) => boolean | Promise<boolean>, fence?: {
+    run<T>(body: () => Promise<T>): Promise<T>;
+}): Promise<void>;
 //# sourceMappingURL=row-run.d.ts.map

package/lib/types/domain/row-run.js

@@ -1,14 +1,26 @@
+import { LeaseStore } from '@lmzhen/dsh-evolution-core';
 import { pairLedger } from "./pair-ledger.js";
 /** Attach the in-flight child run to a row before its round2 starts (P1-8). */
-export async function attachRunToRow(io, home, rowId, runId) {
-    const attached = await pairLedger(io, home).transact(tx => {
-        const current = tx.rows().find(row => row.id === rowId);
-        if (current === undefined)
-            return false;
-        const moved = tx.transition(rowId, { type: 'run-attached', runId }, current.version);
-        return moved.ok;
-    });
-    if (!attached)
-        throw new Error('row is not attachable to run: ' + rowId);
+export async function attachRunToRow(io, home, rowId, runId, isActive, fence) {
+    const leaseStore = new LeaseStore({ io, home, ttlMs: 30_000 });
+    const lease = await leaseStore.acquire('foreground', 'row-attach:' + rowId);
+    if (!lease.ok)
+        throw new Error('row attach is busy: ' + rowId);
+    try {
+        const attached = await pairLedger(io, home, fence).transact(async (tx) => {
+            const current = tx.rows().find(row => row.id === rowId);
+            if (current === undefined)
+                return false;
+            if (current.runId !== undefined && current.runId !== runId && (await isActive?.(current.runId)) === true)
+                return false;
+            const moved = tx.transition(rowId, { type: 'run-attached', runId }, current.version);
+            return moved.ok;
+        });
+        if (!attached)
+            throw new Error('row is not attachable to run: ' + rowId);
+    }
+    finally {
+        await leaseStore.release(lease.token);
+    }
 }
 //# sourceMappingURL=row-run.js.map

package/lib/types/domain/run-coordinator.d.ts

@@ -23,6 +23,8 @@ export interface MergeRunMeta {
     readonly undonePairs?: readonly string[];
     readonly undoneAt?: string;
     readonly degraded?: boolean;
+    /** Monotone run-meta revision; callers pass the current value for CAS. */
+    readonly revision?: number;
     readonly createdAt: string;
     readonly updatedAt: string;
 }
@@ -50,7 +52,9 @@ export interface RunCoordinator {
     read(runId: string): Promise<RunCoordinatorRead>;
 }
 export declare function runMetaPath(home: string, runId: string): string;
-export declare function writeRunMeta(io: EvolutionIoLike, home: string, meta: MergeRunMeta): Promise<void>;
+export declare function writeRunMeta(io: EvolutionIoLike, home: string, meta: MergeRunMeta, fence?: {
+    run<T>(body: () => Promise<T>): Promise<T>;
+}): Promise<void>;
 export declare function readRunMeta(io: EvolutionIoLike, home: string, runId: string): Promise<MergeRunMeta | null>;
 /** Every run-meta record on disk (the in-flight index for pair/target serialisation). */
 export declare function readRunMetas(io: EvolutionIoLike, home: string): Promise<readonly MergeRunMeta[]>;

package/lib/types/domain/run-coordinator.js

@@ -3,8 +3,41 @@ import { readTextOrNull, listOrEmpty } from "./read-probe.js";
 import { join } from 'node:path';
 import { transactIo } from '@lmzhen/dsh-evolution-core';
 export function runMetaPath(home, runId) { return join(home, 'merge', 'run-meta', encodeURIComponent(runId) + '.json'); }
-export async function writeRunMeta(io, home, meta) {
-    await transactIo(io, runMetaPath(home, meta.runId), () => JSON.stringify(meta, null, 2) + '\n');
+export async function writeRunMeta(io, home, meta, fence) {
+    if (meta.revision !== undefined) {
+        const current = await readRunMeta(io, home, meta.runId);
+        const currentRevision = current?.revision ?? 0;
+        if (currentRevision !== meta.revision)
+            throw new Error('run-meta revision conflict: expected ' + String(meta.revision) + ', found ' + String(currentRevision));
+    }
+    const write = async () => {
+        await transactIo(io, runMetaPath(home, meta.runId), current => {
+            let next = meta;
+            let previousRevision = 0;
+            if (current !== null) {
+                try {
+                    const prev = JSON.parse(current);
+                    previousRevision = typeof prev.revision === 'number' ? prev.revision : 0;
+                    if (meta.revision !== undefined && meta.revision !== previousRevision)
+                        throw new Error('run-meta revision conflict: expected ' + String(meta.revision) + ', found ' + String(previousRevision));
+                    if (prev.degraded === true)
+                        next = { ...next, degraded: true };
+                    const terminal = prev.phase === 'settled' || prev.phase === 'cancelled' || prev.phase === 'undone';
+                    // Undo is the one allowed transition out of a settled record; every other
+                    // terminal phase is immutable (a late body write must not reopen a run).
+                    const undoFromSettled = prev.phase === 'settled' && next.phase === 'undone';
+                    if (terminal && next.phase !== prev.phase && !undoFromSettled)
+                        next = { ...next, phase: prev.phase, ...(prev.stopReason === undefined ? {} : { stopReason: prev.stopReason }) };
+                }
+                catch { /* unreadable old meta is replaced by the caller's record */ }
+            }
+            return JSON.stringify({ ...next, revision: previousRevision + 1 }, null, 2) + '\n';
+        });
+    };
+    if (fence !== undefined)
+        await fence.run(write);
+    else
+        await write();
 }
 export async function readRunMeta(io, home, runId) {
     const raw = await readTextOrNull(io, runMetaPath(home, runId));

package/lib/types/domain/schema4.d.ts

@@ -39,7 +39,9 @@ export interface V4RowTx {
     remove(id: string, terminal: 'committed' | 'superseded' | 'restored', unit: CommitUnitRef | undefined, expectedVersion: number): V4WriteResult;
 }
 /** Atomic readiness + V4 row write under one state-file lock. No production caller in 1b-2a. */
-export declare function transactMergeState<T>(io: EvolutionIoLike, home: string, fn: (tx: V4RowTx) => T | Promise<T>): Promise<T>;
+export declare function transactMergeState<T>(io: EvolutionIoLike, home: string, fn: (tx: V4RowTx) => T | Promise<T>, fence?: {
+    run<T>(body: () => Promise<T>): Promise<T>;
+}): Promise<T>;
 /** Pure v3-to-v4 projection for fixtures; 1b-2b wires it to the production normalize. */
 export declare function normalizeV3State(state: {
     readonly schemaVersion: 3;

package/lib/types/domain/schema4.js

@@ -69,49 +69,55 @@ export async function readV4Readiness(io, home) {
     return await inspect(io, home, parsed.body, parsed.rows);
 }
 /** Atomic readiness + V4 row write under one state-file lock. No production caller in 1b-2a. */
-export async function transactMergeState(io, home, fn) {
+export async function transactMergeState(io, home, fn, fence) {
     let result;
-    await transactIo(io, schema4StatePath(home), async (current) => {
-        if (current === null)
-            throw new V4BlockedError(blocked('merge-state-v4-required', 'schema4 state is missing'));
-        let value;
-        try {
-            value = JSON.parse(current);
-        }
-        catch {
-            throw new V4BlockedError(blocked('merge-state-needs-repair', 'merge state is not JSON'));
-        }
-        if (!object(value))
-            throw new V4BlockedError(blocked('merge-state-needs-repair', 'merge state is not an object'));
-        if (typeof value.schemaVersion === 'number' && value.schemaVersion > 4)
-            throw new V4BlockedError(blocked('merge-state-forward-only', 'state schema ' + String(value.schemaVersion) + ' is newer than this build'));
-        if (value.schemaVersion === 3)
-            throw new V4BlockedError(blocked('merge-state-normalize-required', 'schema3 state requires v4 normalize'));
-        if (value.schemaVersion !== 4)
-            throw new V4BlockedError(blocked('merge-state-needs-repair', 'merge state is not schema4'));
-        const parsed = parse(current);
-        if (parsed === null)
-            throw new V4BlockedError(blocked('merge-state-needs-repair', 'schema4 state has an invalid row'));
-        const ready = await inspect(io, home, parsed.body, parsed.rows);
-        if (!ready.ok)
-            throw new V4BlockedError(ready);
-        let rows = parsed.rows;
-        const apply = (write) => {
-            const next = applyV4Write(rows, write, new Date().toISOString());
-            if (next.ok)
-                rows = next.rows;
-            return next;
-        };
-        const tx = {
-            rows: () => rows,
-            createVerify: row => apply({ kind: 'createVerify', row }),
-            createSkipped: row => apply({ kind: 'createSkipped', row }),
-            transition: (id, event, expectedVersion) => apply({ kind: 'transition', id, event, expectedVersion }),
-            remove: (id, terminal, unit, expectedVersion) => apply({ kind: 'remove', id, terminal, ...(unit === undefined ? {} : { unit }), expectedVersion }),
-        };
-        result = await fn(tx);
-        return JSON.stringify({ ...parsed.body, schemaVersion: 4, rows }, null, 2) + '\n';
-    });
+    const run = async () => {
+        await transactIo(io, schema4StatePath(home), async (current) => {
+            if (current === null)
+                throw new V4BlockedError(blocked('merge-state-v4-required', 'schema4 state is missing'));
+            let value;
+            try {
+                value = JSON.parse(current);
+            }
+            catch {
+                throw new V4BlockedError(blocked('merge-state-needs-repair', 'merge state is not JSON'));
+            }
+            if (!object(value))
+                throw new V4BlockedError(blocked('merge-state-needs-repair', 'merge state is not an object'));
+            if (typeof value.schemaVersion === 'number' && value.schemaVersion > 4)
+                throw new V4BlockedError(blocked('merge-state-forward-only', 'state schema ' + String(value.schemaVersion) + ' is newer than this build'));
+            if (value.schemaVersion === 3)
+                throw new V4BlockedError(blocked('merge-state-normalize-required', 'schema3 state requires v4 normalize'));
+            if (value.schemaVersion !== 4)
+                throw new V4BlockedError(blocked('merge-state-needs-repair', 'merge state is not schema4'));
+            const parsed = parse(current);
+            if (parsed === null)
+                throw new V4BlockedError(blocked('merge-state-needs-repair', 'schema4 state has an invalid row'));
+            const ready = await inspect(io, home, parsed.body, parsed.rows);
+            if (!ready.ok)
+                throw new V4BlockedError(ready);
+            let rows = parsed.rows;
+            const apply = (write) => {
+                const next = applyV4Write(rows, write, new Date().toISOString());
+                if (next.ok)
+                    rows = next.rows;
+                return next;
+            };
+            const tx = {
+                rows: () => rows,
+                createVerify: row => apply({ kind: 'createVerify', row }),
+                createSkipped: row => apply({ kind: 'createSkipped', row }),
+                transition: (id, event, expectedVersion) => apply({ kind: 'transition', id, event, expectedVersion }),
+                remove: (id, terminal, unit, expectedVersion) => apply({ kind: 'remove', id, terminal, ...(unit === undefined ? {} : { unit }), expectedVersion }),
+            };
+            result = await fn(tx);
+            return JSON.stringify({ ...parsed.body, schemaVersion: 4, rows }, null, 2) + '\n';
+        });
+    };
+    if (fence !== undefined)
+        await fence.run(run);
+    else
+        await run();
     if (result === undefined)
         throw new V4BlockedError(blocked('merge-state-needs-repair', 'v4 transaction did not produce a result'));
     return result;

package/lib/types/domain/stage-aggregate.js

@@ -1,6 +1,6 @@
 import { readTextOrNull, listOrEmpty } from "./read-probe.js";
 /** 1b-1 shadow staging adoption. Production staging is still owned by the old staged writers. */
-import { join } from 'node:path';
+import { isAbsolute, join } from 'node:path';
 import { readPairLedger } from "./pair-ledger.js";
 import { readStagingIndex, writeStagingIndex } from "./staging-index.js";
 import { createStaging, dropStaging, ensureStaging, readStaging, setStagingTarget } from "../staging.js";
@@ -205,11 +205,24 @@ export async function reserveStage(io, home, entry) {
 export async function presentStage(io, home, entry) {
     await writeStageIndex(io, home, { rowId: entry.rowId, pairKey: entry.pairKey, ref: entry.ref, expiresAt: entry.expiresAt, ...(entry.runId === undefined ? {} : { runId: entry.runId }), createdAt: entry.createdAt, state: 'present' });
 }
+function safeRunTree(home, ref) {
+    const name = ref.trim();
+    if (name === '' || name.includes('\\') || isAbsolute(name))
+        return null;
+    const parts = name.split('/');
+    if (parts.some(part => part === '' || part === '.' || part === '..'))
+        return null;
+    return join(home, 'merge', 'runs', ...parts);
+}
 export async function dropStage(io, home, rowId, ref, onError) {
     const index = join(home, 'merge', 'staging-index', encodeURIComponent(rowId) + '.json');
     await io.remove(index).catch(error => onError?.(index, error));
     if (ref !== undefined && ref !== '') {
-        const tree = join(home, 'merge', 'runs', ref);
+        const tree = safeRunTree(home, ref);
+        if (tree === null) {
+            onError?.(join(home, 'merge', 'runs'), new Error('invalid staging ref: ' + JSON.stringify(ref)));
+            return;
+        }
         await io.remove(tree).catch(error => onError?.(tree, error));
     }
 }
@@ -275,7 +288,12 @@ export async function cleanupStage(io, home, now, rows, limit = 100) {
         const prefix = run + '/';
         if ([...refs].some(ref => ref === run || ref.startsWith(prefix)))
             continue;
-        await io.remove(join(runRoot, run)).catch(error => fail(join(runRoot, run), error));
+        const tree = safeRunTree(home, run);
+        if (tree === null) {
+            fail(join(runRoot, run), new Error('invalid run dir name: ' + JSON.stringify(run)));
+            continue;
+        }
+        await io.remove(tree).catch(error => fail(tree, error));
         orphans.push(run);
     }
     return { removed, expired, kept, orphans, failures };

package/lib/types/domain/state-bootstrap.d.ts

@@ -39,5 +39,7 @@ export declare function readStateReadiness(io: EvolutionIoLike, home: string): P
 /** Compatibility name for the v3 gate; 1b-2b switches the lifecycle to v4. */
 export declare const ensureV3Ready: typeof ensureMergeStateReady;
 /** One readiness/migration gate; used by startup and every write entry. */
-export declare function ensureMergeStateReady(io: EvolutionIoLike, home: string): Promise<StateReadiness>;
+export declare function ensureMergeStateReady(io: EvolutionIoLike, home: string, fence?: {
+    run<T>(body: () => Promise<T>): Promise<T>;
+}): Promise<StateReadiness>;
 //# sourceMappingURL=state-bootstrap.d.ts.map

package/lib/types/domain/state-bootstrap.js

@@ -144,107 +144,113 @@ export async function readStateReadiness(io, home) {
 /** Compatibility name for the v3 gate; 1b-2b switches the lifecycle to v4. */
 export const ensureV3Ready = ensureMergeStateReady;
 /** One readiness/migration gate; used by startup and every write entry. */
-export async function ensureMergeStateReady(io, home) {
+export async function ensureMergeStateReady(io, home, fence) {
     let outcome;
     let migrated = false;
     try {
-        await transactIo(io, mergeStatePath(home), async (current) => {
-            if (current === null) {
-                outcome = { ok: true, schema: 3, migrated: false, state: { schemaVersion: 3, rows: [] }, quarantine: [], report: await readReport(io, home) };
-                return null;
-            }
-            const body = parseBody(current);
-            if (body === null) {
-                outcome = blocked('merge-state-needs-repair', 'state file is not a JSON object');
-                return current;
-            }
-            const version = body.schemaVersion;
-            if (typeof version === 'number' && version > 3) {
-                outcome = blocked('merge-state-forward-only', 'state schema ' + String(version) + ' is newer than this build');
-                return current;
-            }
-            if (version === 3) {
-                const state = v3State(body);
-                if (state === null) {
-                    outcome = blocked('merge-state-needs-repair', 'v3 state has an invalid row');
+        const run = async () => {
+            await transactIo(io, mergeStatePath(home), async (current) => {
+                if (current === null) {
+                    outcome = { ok: true, schema: 3, migrated: false, state: { schemaVersion: 3, rows: [] }, quarantine: [], report: await readReport(io, home) };
+                    return null;
+                }
+                const body = parseBody(current);
+                if (body === null) {
+                    outcome = blocked('merge-state-needs-repair', 'state file is not a JSON object');
                     return current;
                 }
-                const journal = await readJournal(io, home);
-                if (journal !== null) {
-                    outcome = await completeJournal(io, home, journal, current);
+                const version = body.schemaVersion;
+                if (typeof version === 'number' && version > 3) {
+                    outcome = blocked('merge-state-forward-only', 'state schema ' + String(version) + ' is newer than this build');
                     return current;
                 }
-                const report = await readReport(io, home);
-                const marker = readMarker(body);
-                if (body.migration !== undefined && marker === null) {
-                    outcome = blocked('merge-state-needs-repair', 'migration marker is invalid');
+                if (version === 3) {
+                    const state = v3State(body);
+                    if (state === null) {
+                        outcome = blocked('merge-state-needs-repair', 'v3 state has an invalid row');
+                        return current;
+                    }
+                    const journal = await readJournal(io, home);
+                    if (journal !== null) {
+                        outcome = await completeJournal(io, home, journal, current);
+                        return current;
+                    }
+                    const report = await readReport(io, home);
+                    const marker = readMarker(body);
+                    if (body.migration !== undefined && marker === null) {
+                        outcome = blocked('merge-state-needs-repair', 'migration marker is invalid');
+                        return current;
+                    }
+                    if (report !== null && report.ready !== true) {
+                        outcome = blocked('merge-state-migration-blocked', 'migration report is not ready');
+                        return current;
+                    }
+                    if (marker !== null && rowsSha(state.rows) === marker.targetSha256) {
+                        if (report === null) {
+                            outcome = blocked('merge-state-migration-blocked', 'migration report is missing');
+                            return current;
+                        }
+                        for (const entry of marker.staging)
+                            if (!(await io.exists(stagingIndexPath(home, entry.rowId))))
+                                await writeStagingIndex(io, home, entry);
+                    }
+                    outcome = { ok: true, schema: 3, migrated: false, state, quarantine: [], report };
                     return current;
                 }
-                if (report !== null && report.ready !== true) {
-                    outcome = blocked('merge-state-migration-blocked', 'migration report is not ready');
+                const mapped = migrateV2ToV3(body);
+                if (!mapped.ok) {
+                    outcome = blocked('merge-state-migration-blocked', mapped.message);
                     return current;
                 }
-                if (marker !== null && rowsSha(state.rows) === marker.targetSha256) {
-                    if (report === null) {
-                        outcome = blocked('merge-state-migration-blocked', 'migration report is missing');
-                        return current;
-                    }
-                    for (const entry of marker.staging)
-                        if (!(await io.exists(stagingIndexPath(home, entry.rowId))))
-                            await writeStagingIndex(io, home, entry);
+                const sourceSha256 = hash(current);
+                const backup = v2BackupPath(home);
+                const existingBackup = await readTextOrNull(io, backup);
+                if (existingBackup !== null && existingBackup !== current) {
+                    outcome = blocked('merge-state-migration-blocked', 'v2 backup exists with different bytes');
+                    return current;
+                }
+                if (existingBackup === null)
+                    await transactIo(io, backup, () => current);
+                try {
+                    await chmod(backup, 0o444);
+                }
+                catch {
+                    outcome = blocked('merge-state-migration-blocked', 'v2 backup is not read-only');
+                    return current;
+                }
+                const staging = [];
+                for (const row of body.rows) {
+                    if (typeof row.id !== 'string' || typeof row.pairKey !== 'string' || typeof row.stagingRef !== 'string')
+                        continue;
+                    if (row.state !== 'pending' && row.state !== 'approved')
+                        continue;
+                    staging.push({
+                        rowId: row.id, pairKey: row.pairKey, ref: row.stagingRef,
+                        expiresAt: typeof row.stagingExpiresAt === 'number' ? row.stagingExpiresAt : Date.now() + 7 * 86_400_000,
+                        ...(typeof row.runId === 'string' ? { runId: row.runId } : {}),
+                        createdAt: typeof row.updatedAt === 'string' && !Number.isNaN(Date.parse(row.updatedAt)) ? Date.parse(row.updatedAt) : Date.now(),
+                    });
                 }
-                outcome = { ok: true, schema: 3, migrated: false, state, quarantine: [], report };
-                return current;
-            }
-            const mapped = migrateV2ToV3(body);
-            if (!mapped.ok) {
-                outcome = blocked('merge-state-migration-blocked', mapped.message);
-                return current;
-            }
-            const sourceSha256 = hash(current);
-            const backup = v2BackupPath(home);
-            const existingBackup = await readTextOrNull(io, backup);
-            if (existingBackup !== null && existingBackup !== current) {
-                outcome = blocked('merge-state-migration-blocked', 'v2 backup exists with different bytes');
-                return current;
-            }
-            if (existingBackup === null)
-                await transactIo(io, backup, () => current);
-            try {
-                await chmod(backup, 0o444);
-            }
-            catch {
-                outcome = blocked('merge-state-migration-blocked', 'v2 backup is not read-only');
-                return current;
-            }
-            const staging = [];
-            for (const row of body.rows) {
-                if (typeof row.id !== 'string' || typeof row.pairKey !== 'string' || typeof row.stagingRef !== 'string')
-                    continue;
-                if (row.state !== 'pending' && row.state !== 'approved')
-                    continue;
-                staging.push({
-                    rowId: row.id, pairKey: row.pairKey, ref: row.stagingRef,
-                    expiresAt: typeof row.stagingExpiresAt === 'number' ? row.stagingExpiresAt : Date.now() + 7 * 86_400_000,
-                    ...(typeof row.runId === 'string' ? { runId: row.runId } : {}),
-                    createdAt: typeof row.updatedAt === 'string' && !Number.isNaN(Date.parse(row.updatedAt)) ? Date.parse(row.updatedAt) : Date.now(),
-                });
-            }
-            const marker = { migratedFromV2: true, sourceSha256, targetSha256: rowsSha(mapped.state.rows), staging, at: now() };
-            const targetText = json({ ...mapped.state, migration: marker });
-            const targetSha256 = hash(targetText);
-            const journal = { version: 1, sourceSha256, targetSha256, rows: mapped.state.rows.length, quarantine: mapped.quarantine, staging, backupPath: backup, at: now() };
-            await transactIo(io, migrationJournalPath(home), () => json(journal));
-            for (const entry of staging)
-                await writeStagingIndex(io, home, entry);
-            if (mapped.quarantine.length > 0)
-                await transactIo(io, quarantinePath(home), () => json(mapped.quarantine));
-            const prepared = { version: 1, ready: false, migrated: true, sourceSha256, targetSha256, rows: mapped.state.rows.length, quarantined: mapped.quarantine.length, backupReadOnly: true, at: now(), steps: ['backup', 'journal', 'staging-index', 'quarantine', 'v3-write'] };
-            await writeReport(io, home, prepared);
-            migrated = true;
-            outcome = { ok: true, schema: 3, migrated: true, state: mapped.state, quarantine: mapped.quarantine, report: prepared };
-            return targetText;
-        });
+                const marker = { migratedFromV2: true, sourceSha256, targetSha256: rowsSha(mapped.state.rows), staging, at: now() };
+                const targetText = json({ ...mapped.state, migration: marker });
+                const targetSha256 = hash(targetText);
+                const journal = { version: 1, sourceSha256, targetSha256, rows: mapped.state.rows.length, quarantine: mapped.quarantine, staging, backupPath: backup, at: now() };
+                await transactIo(io, migrationJournalPath(home), () => json(journal));
+                for (const entry of staging)
+                    await writeStagingIndex(io, home, entry);
+                if (mapped.quarantine.length > 0)
+                    await transactIo(io, quarantinePath(home), () => json(mapped.quarantine));
+                const prepared = { version: 1, ready: false, migrated: true, sourceSha256, targetSha256, rows: mapped.state.rows.length, quarantined: mapped.quarantine.length, backupReadOnly: true, at: now(), steps: ['backup', 'journal', 'staging-index', 'quarantine', 'v3-write'] };
+                await writeReport(io, home, prepared);
+                migrated = true;
+                outcome = { ok: true, schema: 3, migrated: true, state: mapped.state, quarantine: mapped.quarantine, report: prepared };
+                return targetText;
+            });
+        };
+        if (fence !== undefined)
+            await fence.run(run);
+        else
+            await run();
     }
     catch (error) {
         return blocked('merge-state-migration-blocked', 'state migration failed: ' + (error instanceof Error ? error.message : String(error)));