@lmzhen/dsh-evolution-merge 0.30.17 → 0.30.19

package/lib/types/propose.js

@@ -0,0 +1,69 @@
+const SYSTEM = 'You propose skill pairs that may be merged. Return only a JSON object: {"pairs":[{"a":"skill-a","b":"skill-b","reason":"one sentence"}]}. Use only supplied skill names. Do not decide whether a merge is good.';
+function parsePairs(raw, known, cap) {
+    let value = raw;
+    if (typeof raw === 'string') {
+        try {
+            value = JSON.parse(raw);
+        }
+        catch {
+            return [];
+        }
+    }
+    if (typeof value !== 'object' || value === null)
+        return [];
+    const pairs = value.pairs;
+    if (!Array.isArray(pairs))
+        return [];
+    const out = [];
+    const seen = new Set();
+    for (const item of pairs) {
+        if (out.length >= cap)
+            break;
+        const pair = item;
+        if (typeof pair.a !== 'string' || typeof pair.b !== 'string')
+            continue;
+        const a = pair.a.trim();
+        const b = pair.b.trim();
+        if (a === b || !known.has(a) || !known.has(b))
+            continue;
+        const [first, second] = a < b ? [a, b] : [b, a];
+        const key = first + '\u0000' + second;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push({ a: first, b: second, source: 'proposed', ...(typeof pair.reason === 'string' && pair.reason.trim() !== '' ? { reason: pair.reason.trim() } : {}) });
+    }
+    return out;
+}
+export async function proposePairs(cards, port, options) {
+    const shardSize = Math.max(2, options.shardSize ?? 60);
+    const cap = Math.max(0, options.maxPairs ?? 200);
+    const known = new Set(cards.map(card => card.name));
+    const candidates = [];
+    const degraded = [];
+    let shards = 0;
+    for (let start = 0; start < cards.length && candidates.length < cap; start += shardSize) {
+        const shard = cards.slice(start, start + shardSize);
+        if (shard.length < 2)
+            continue;
+        shards += 1;
+        try {
+            const raw = await port.callJson({
+                system: SYSTEM,
+                user: JSON.stringify(shard.map(card => ({
+                    name: card.name,
+                    description: card.description.slice(0, 400),
+                    body: card.body.slice(0, 600),
+                }))),
+                maxTokens: 1200,
+                signal: options.signal,
+            });
+            candidates.push(...parsePairs(raw, known, cap - candidates.length));
+        }
+        catch (error) {
+            degraded.push('proposal shard failed: ' + (error instanceof Error ? error.message : String(error)));
+        }
+    }
+    return { candidates, shards, degraded };
+}
+//# sourceMappingURL=propose.js.map

package/lib/types/read-commands.d.ts

@@ -1,11 +1,11 @@
 /**
- * Read-only command handlers: status/pending/skipped are served from merge-state.
- * Mutating verbs return null so the host shell can route them to the run engine.
+ * Read-only command handlers: all served from one MergeSnapshot; never writes.
  */
-import type { EvolutionIoLike } from '@lmzhen/dsh-evolution-core';
+import type { EvolutionIoLike, RunRecord } from '@lmzhen/dsh-evolution-core';
 import type { MergeCliCommand } from './commands.ts';
+import type { LiveRowFacts } from './domain/live-facts.ts';
 export declare function handleReadOnlyMergeCommand(command: MergeCliCommand, io: EvolutionIoLike, home: string, cards?: readonly {
     readonly name: string;
-}[]): Promise<string | null>;
+}[], runs?: readonly RunRecord[], approval?: boolean, live?: () => Promise<LiveRowFacts | undefined>): Promise<string | null>;
 export declare function mergeCommandHelp(): string;
 //# sourceMappingURL=read-commands.d.ts.map

package/lib/types/read-commands.js

@@ -1,38 +1,31 @@
-import { loadMergeState } from "./state.js";
-import { formatQueue, formatStatus } from "./status.js";
+import { readMergeSnapshot } from "./domain/merge-snapshot.js";
+import { buildFacts, toRowFact } from "./surface/merge-view.js";
+import { formatFacts, formatSnapshotQueue, formatSnapshotStatus } from "./status.js";
 import { mergeUsage } from "./commands.js";
-export async function handleReadOnlyMergeCommand(command, io, home, cards) {
-    const withNote = (text, note) => note === undefined ? text : 'note: ' + note + '\n' + text;
-    const load = async () => {
-        const result = await loadMergeState(io, home);
-        if (result.note === 'merge-state-forward-only')
-            throw new Error('merge-state-forward-only');
-        return result;
-    };
+export async function handleReadOnlyMergeCommand(command, io, home, cards, runs, approval = false, live) {
+    if (!['status', 'pending', 'candidates', 'skipped'].includes(command.verb))
+        return null;
+    const snapshot = await readMergeSnapshot({ io, home, runs: runs ?? [], approval, ...(live === undefined ? {} : { live }) });
+    if (snapshot.blocked !== undefined)
+        throw new Error(snapshot.blocked.code + ': ' + snapshot.blocked.message);
+    const rows = snapshot.rows.map(toRowFact);
     if (command.verb === 'status') {
-        const loaded = await load();
         if (command.id !== undefined) {
-            const row = loaded.state.rows.find(item => item.id === command.id);
-            return withNote(row === undefined ? 'merge row not found: ' + command.id : formatStatus([row]), loaded.note);
+            const row = rows.find(item => item.id === command.id);
+            return row === undefined ? 'merge row not found: ' + command.id : formatSnapshotStatus([row]);
         }
-        return withNote(formatStatus(loaded.state.rows), loaded.note);
+        return formatFacts(buildFacts(snapshot));
     }
     if (command.verb === 'pending') {
-        const loaded = await load();
-        const rows = command.expired === true ? loaded.state.rows.filter(row => row.expired !== undefined) : loaded.state.rows;
-        const live = cards === undefined ? rows : rows.filter(row => cards.some(card => card.name === row.a) && cards.some(card => card.name === row.b));
-        return withNote(command.expired === true ? formatStatus(live) : formatQueue(live, 'pending'), loaded.note);
+        const live = command.expired === true ? rows.filter(row => row.expired !== undefined) : rows.filter(row => row.queue === 'pending' && row.expired === undefined);
+        const filtered = cards === undefined ? live : live.filter(row => cards.some(card => card.name === row.a) && cards.some(card => card.name === row.b));
+        return command.expired === true ? formatSnapshotStatus(filtered) : formatSnapshotQueue(filtered, 'pending');
     }
     if (command.verb === 'candidates') {
-        const loaded = await load();
-        const rows = command.retry === true ? loaded.state.rows.filter(row => row.state === 'approved') : loaded.state.rows;
-        return withNote(formatQueue(rows, command.retry === true ? 'fuse' : 'verify'), loaded.note);
+        const queue = command.retry === true ? 'fuse' : 'verify';
+        return formatSnapshotQueue(rows.filter(row => row.queue === queue && (command.id === undefined || row.id === command.id)), queue);
     }
-    if (command.verb === 'skipped') {
-        const loaded = await load();
-        return withNote(formatQueue(loaded.state.rows, 'skipped'), loaded.note);
-    }
-    return null;
+    return formatSnapshotQueue(rows.filter(row => row.queue === 'skipped'), 'skipped');
 }
 export function mergeCommandHelp() {
     return mergeUsage();

package/lib/types/recovery-coordinator.d.ts

@@ -0,0 +1,34 @@
+import type { EvolutionIoLike, UnitTransaction } from '@lmzhen/dsh-evolution-core';
+export type RecoveryBranch = 'A' | 'B' | 'C' | 'D';
+export interface RecoveryReport {
+    readonly unitId: string;
+    readonly runId: string;
+    readonly phase: string;
+    readonly branch: RecoveryBranch;
+    readonly action: 'rollback' | 'rollForward' | 'finalize' | 'blocked' | 'none';
+    readonly ok: boolean;
+    readonly code?: string | undefined;
+    readonly message?: string | undefined;
+    readonly evidenceSha256?: string;
+}
+export declare function recoverCommitUnits(options: {
+    readonly io: EvolutionIoLike;
+    readonly home: string;
+    readonly unit: UnitTransaction;
+    readonly now: () => number;
+    readonly isActive?: (runId: string) => boolean;
+    readonly runs?: {
+        settle(id: string, outcome: {
+            state: 'succeeded' | 'failed' | 'cancelled';
+            resultRef?: string;
+            failure?: string;
+        }): Promise<void>;
+        settleRecovered?(id: string, outcome: {
+            state: 'succeeded' | 'failed' | 'cancelled';
+            resultRef?: string;
+            failure?: string;
+        }): Promise<boolean>;
+    };
+    readonly onProjectionPhase?: (phase: string) => void | Promise<void>;
+}): Promise<readonly RecoveryReport[]>;
+//# sourceMappingURL=recovery-coordinator.d.ts.map

package/lib/types/recovery-coordinator.js

@@ -0,0 +1,84 @@
+/** Batch 2c unit-journal recovery coordinator. UnitTransaction remains the only skill writer. */
+import { join } from 'node:path';
+import { probeList, readUnitEvidence } from '@lmzhen/dsh-evolution-core';
+import { evidenceSha256 } from "./domain/evidence-hash.js";
+import { projectRecoveredUnit } from "./recovery-projection.js";
+const branchOf = (phase) => {
+    if (phase === 'prepared' || phase === 'target-pending')
+        return 'A';
+    if (phase === 'target-written' || phase === 'support-pending' || phase === 'source-archiving')
+        return 'B';
+    if (phase === 'sources-archived' || phase === 'unit-written')
+        return 'C';
+    if (phase === 'committed')
+        return 'D';
+    return 'A';
+};
+export async function recoverCommitUnits(options) {
+    const dir = join(options.home, 'merge', 'unit-journals');
+    const listed = await probeList(options.io, dir);
+    if (listed.kind !== 'present')
+        return [];
+    const files = listed.value.filter(name => name.endsWith('.json'));
+    const reports = [];
+    for (const file of files.sort()) {
+        let journal = null;
+        try {
+            journal = JSON.parse(await options.io.readText(join(dir, file)) ?? '');
+        }
+        catch {
+            journal = null;
+        }
+        if (journal === null || typeof journal.unitId !== 'string')
+            continue;
+        if (options.isActive?.(journal.runId) === true) {
+            reports.push({ unitId: journal.unitId, runId: journal.runId, phase: journal.phase, branch: branchOf(journal.phase), action: 'none', ok: true, code: 'skipped-active-run' });
+            continue;
+        }
+        const evidence = await readUnitEvidence(options.io, options.home, journal.unitId);
+        const branch = branchOf(journal.phase);
+        if (journal.phase === 'committed' || evidence !== null || journal.phase === 'unit-written' || journal.phase === 'sources-archived') {
+            const result = await options.unit.finalize(journal.unitId);
+            if (result.ok) {
+                let projection;
+                try {
+                    projection = await projectRecoveredUnit({ io: options.io, home: options.home, runId: journal.runId, unitId: journal.unitId, evidence: result.evidence, now: options.now, ...(options.runs === undefined ? {} : { runs: options.runs }), ...(options.onProjectionPhase === undefined ? {} : { onPhase: options.onProjectionPhase }) });
+                }
+                catch (error) {
+                    projection = { ok: false, action: 'projection-threw', message: error instanceof Error ? error.message : String(error) };
+                }
+                if (!projection.ok)
+                    reports.push({ unitId: journal.unitId, runId: journal.runId, phase: journal.phase, branch, action: 'blocked', ok: false, code: 'projection-failed', message: projection.message });
+                else
+                    reports.push({ unitId: journal.unitId, runId: journal.runId, phase: journal.phase, branch, action: 'finalize', ok: true, evidenceSha256: evidenceSha256(result.evidence) });
+                continue;
+            }
+            reports.push({ unitId: journal.unitId, runId: journal.runId, phase: journal.phase, branch, action: 'finalize', ok: false, code: result.code, message: result.message });
+            continue;
+        }
+        if (branch === 'A') {
+            const result = await options.unit.rollback({ unitId: journal.unitId, reason: 'startup recovery branch A' });
+            reports.push({ unitId: journal.unitId, runId: journal.runId, phase: journal.phase, branch, action: 'rollback', ok: result.ok, ...(result.ok ? {} : { code: result.code, message: result.message }) });
+            continue;
+        }
+        if (branch === 'B') {
+            const result = await options.unit.rollForward(journal.unitId);
+            if (result.ok) {
+                let projection;
+                try {
+                    projection = await projectRecoveredUnit({ io: options.io, home: options.home, runId: journal.runId, unitId: journal.unitId, evidence: result.evidence, now: options.now, ...(options.runs === undefined ? {} : { runs: options.runs }), ...(options.onProjectionPhase === undefined ? {} : { onPhase: options.onProjectionPhase }) });
+                }
+                catch (error) {
+                    projection = { ok: false, action: 'projection-threw', message: error instanceof Error ? error.message : String(error) };
+                }
+                reports.push({ unitId: journal.unitId, runId: journal.runId, phase: journal.phase, branch, action: projection.ok ? 'rollForward' : 'blocked', ok: projection.ok, ...(projection.ok ? { evidenceSha256: evidenceSha256(result.evidence) } : { code: 'projection-failed', message: projection.message }) });
+            }
+            else
+                reports.push({ unitId: journal.unitId, runId: journal.runId, phase: journal.phase, branch, action: 'rollForward', ok: false, code: result.code, message: result.message });
+            continue;
+        }
+        reports.push({ unitId: journal.unitId, runId: journal.runId, phase: journal.phase, branch, action: 'blocked', ok: false, code: 'unit-recovery-blocked' });
+    }
+    return reports;
+}
+//# sourceMappingURL=recovery-coordinator.js.map

package/lib/types/recovery-projection.d.ts

@@ -0,0 +1,31 @@
+/** Post-recovery projection: evidence -> report -> row remove -> stage drop -> settle/meta. */
+import type { EvolutionIoLike, UnitEvidenceRecord } from '@lmzhen/dsh-evolution-core';
+export interface ProjectionResult {
+    readonly ok: boolean;
+    readonly action: string;
+    readonly message?: string;
+    readonly reportPath?: string;
+}
+export declare function projectRecoveredUnit(options: {
+    readonly io: EvolutionIoLike;
+    readonly home: string;
+    readonly runId: string;
+    readonly unitId: string;
+    readonly evidence: UnitEvidenceRecord;
+    readonly now: () => number;
+    readonly runs?: {
+        settle(id: string, outcome: {
+            state: 'succeeded' | 'failed' | 'cancelled';
+            resultRef?: string;
+            failure?: string;
+        }): Promise<void>;
+        /** Controlled orphan upgrade: lets a committed unit turn failed(orphan) back into succeeded. */
+        settleRecovered?(id: string, outcome: {
+            state: 'succeeded' | 'failed' | 'cancelled';
+            resultRef?: string;
+            failure?: string;
+        }): Promise<boolean>;
+    };
+    readonly onPhase?: (phase: string) => void | Promise<void>;
+}): Promise<ProjectionResult>;
+//# sourceMappingURL=recovery-projection.d.ts.map

package/lib/types/recovery-projection.js

@@ -0,0 +1,96 @@
+import { readCommitReceipts, writeCommitReceipt } from "./commit-receipt.js";
+import { mergeReportPath, readMergeReport, writeMergeReport } from "./report.js";
+import { pairLedger, readPairLedgerV4 } from "./domain/pair-ledger.js";
+import { readAllStages, readStageTree, writeStageIndex } from "./domain/stage-aggregate.js";
+import { dropStage } from "./domain/stage-aggregate.js";
+import { recordPair } from "./domain/pair-index-store.js";
+import { readRunMeta, writeRunMeta } from "./domain/run-coordinator.js";
+import { evidenceSha256 } from "./domain/evidence-hash.js";
+export async function projectRecoveredUnit(options) {
+    const evidenceSha = evidenceSha256(options.evidence);
+    const ledger = await readPairLedgerV4(options.io, options.home).catch(() => null);
+    const row = ledger?.rows.find(item => item.runId === options.runId && (item.state === 'fuse' || item.state === 'approved'));
+    const rowTarget = row !== undefined && 'target' in row && typeof row.target === 'string' ? row.target : undefined;
+    const rowDecisionTarget = row !== undefined && 'decision' in row ? row.decision.target : undefined;
+    const target = rowTarget ?? rowDecisionTarget ?? options.evidence.sources[0]?.absorbedInto ?? options.evidence.target.after;
+    const pairKey = row?.pairKey ?? target + '\u0000' + (options.evidence.sources[0]?.name ?? '');
+    const expectedPairKey = pairKey;
+    const stageEntry = (await readAllStages(options.io, options.home)).find(item => item.rowId === row?.id || item.pairKey === expectedPairKey);
+    const stageRowId = row?.id ?? stageEntry?.rowId;
+    if (row?.state === 'approved' && stageEntry?.state === 'reserved') {
+        const tree = await readStageTree(options.io, options.home, stageEntry.ref);
+        if (tree.kind !== 'present') {
+            await writeStageIndex(options.io, options.home, { ...stageEntry, state: 'lost' });
+            return { ok: false, action: 'stage-lost', message: 'approved+reserved has no stage tree' };
+        }
+    }
+    const receipts = await readCommitReceipts(options.io, options.home);
+    const receipt = receipts.find(item => item.unitId === options.unitId);
+    const evidencePlan = options.evidence.validationPlan;
+    const validationPlan = receipt?.validationPlan ?? evidencePlan;
+    if (receipt === undefined) {
+        await options.onPhase?.('merge-receipt');
+        await writeCommitReceipt(options.io, options.home, {
+            runId: options.runId, unitId: options.unitId, evidenceSha256: evidenceSha,
+            target, create: options.evidence.target.created,
+            sources: options.evidence.sources.map(source => source.name),
+            archived: options.evidence.sources.filter(source => source.archived).map(source => source.name),
+            pairKey, at: options.now(),
+            ...(validationPlan === undefined ? {} : { validationPlan }),
+        });
+    }
+    const at = options.now();
+    let reportPath;
+    const existing = await readMergeReport(options.io, options.home, options.runId);
+    if (existing.kind === 'present') {
+        reportPath = mergeReportPath(options.home, options.runId);
+        if (validationPlan !== undefined && existing.value.pairs.every(pair => pair.validationPlan === undefined)) {
+            await writeMergeReport(options.io, options.home, { ...existing.value, pairs: existing.value.pairs.map(pair => ({ ...pair, validationPlan })) });
+        }
+    }
+    else {
+        const report = {
+            schemaVersion: 2, runId: options.runId, kind: 'merge', command: 'approve', startedAt: at, endedAt: at,
+            stopReason: 'completed', approval: { platformWrite: false, mergeApproval: true },
+            scope: { candidatePairs: 1, queueBefore: { verify: 0, pending: 0, fuse: 0, skipped: 0 } },
+            pairs: [{ id: row?.id ?? options.unitId, pairKey, a: row?.a ?? target, b: row?.b ?? options.evidence.sources[0]?.name ?? '', queue: 'fuse', outcome: 'merged', archived: options.evidence.sources.filter(source => source.archived).map(source => source.name), unitId: options.unitId, ...(validationPlan === undefined ? {} : { validationPlan }) }],
+            totals: { merged: 1, kept: 0, pending: 0, failed: 0 }, notes: ['recovered from unit journal'],
+        };
+        await options.onPhase?.('report');
+        try {
+            reportPath = await writeMergeReport(options.io, options.home, report);
+        }
+        catch (error) {
+            return { ok: false, action: 'report-write-failed', message: error instanceof Error ? error.message : String(error) };
+        }
+    }
+    if (row !== undefined) {
+        await options.onPhase?.('row-remove');
+        const removed = await pairLedger(options.io, options.home).transact(tx => {
+            const current = tx.rows().find(item => item.id === row.id);
+            return current === undefined ? true : tx.remove(row.id, 'committed', { unitId: options.unitId, evidenceSha256: evidenceSha }, current.version).ok;
+        });
+        if (!removed)
+            return { ok: false, action: 'row-remove-failed' };
+        await options.onPhase?.('stage-drop');
+        await dropStage(options.io, options.home, row.id);
+    }
+    else if (stageRowId !== undefined) {
+        await options.onPhase?.('stage-drop');
+        await dropStage(options.io, options.home, stageRowId);
+    }
+    await options.onPhase?.('pair-index');
+    await recordPair(options.io, options.home, { pairKey, runId: options.runId, result: 'merged', target });
+    await options.onPhase?.('run-meta');
+    const meta = await readRunMeta(options.io, options.home, options.runId);
+    await writeRunMeta(options.io, options.home, { version: 1, runId: options.runId, phase: 'settled', reportRef: reportPath, pairCount: 1, ...(meta?.parentRunId === undefined ? {} : { parentRunId: meta.parentRunId }), createdAt: meta?.createdAt ?? new Date(at).toISOString(), updatedAt: new Date(at).toISOString() });
+    await options.onPhase?.('settle');
+    if (options.runs !== undefined) {
+        const outcome = { state: 'succeeded', resultRef: reportPath };
+        const upgraded = options.runs.settleRecovered === undefined ? false : await options.runs.settleRecovered(options.runId, outcome);
+        if (!upgraded)
+            await options.runs.settle(options.runId, outcome);
+    }
+    return { ok: true, action: 'projected', reportPath };
+}
+//# sourceMappingURL=recovery-projection.js.map

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

@@ -2,7 +2,7 @@
  * resume command: verify rows re-enter round1; fuse rows re-enter round2 with the persisted
  * decision. pending/skipped rows are not resumable.
  */
-import type { EvolutionIoLike } from '@lmzhen/dsh-evolution-core';
+import { type EvolutionIoLike } from '@lmzhen/dsh-evolution-core';
 import { type MergeRegistryPort, type WithMergeRunResult } from './run-shell.ts';
 import type { ScanPorts, ScanRound2Outcome } from './scan-run.ts';
 import type { MergeDecision, MergeRow } from './contracts.ts';
@@ -17,9 +17,15 @@ export interface RunResumeCommandOptions {
     readonly round2WithRun?: (row: MergeRow, decision: MergeDecision, signal: AbortSignal, runId: string) => Promise<ScanRound2Outcome>;
     readonly rowId: string;
     readonly platformWrite: boolean;
+    readonly approval: boolean;
+    readonly parentRunId?: string;
+    readonly detached?: boolean;
+    readonly pairTimeoutMinutes?: number;
     readonly timeoutMinutes?: number;
     readonly now: () => number;
     readonly isOwnerActive?: (runId: string) => boolean | Promise<boolean>;
+    /** The invocation carried no agent at all (E-305), as opposed to an agent with no parent run. */
+    readonly agentless?: boolean;
 }
 export declare function runResumeCommand(options: RunResumeCommandOptions): Promise<WithMergeRunResult>;
 //# sourceMappingURL=resume-command.d.ts.map

package/lib/types/resume-command.js

@@ -1,27 +1,38 @@
+/**
+ * resume command: verify rows re-enter round1; fuse rows re-enter round2 with the persisted
+ * decision. pending/skipped rows are not resumable.
+ */
+import { errorText } from '@lmzhen/dsh-evolution-core';
 import { loadMergeState } from "./state.js";
 import { runScanCommand } from "./scan-command.js";
 import { withMergeRun } from "./run-shell.js";
 import { recordRound2Outcome } from "./round2-outcome.js";
+import { pairLedger } from "./domain/pair-ledger.js";
+import { presentStage } from "./domain/stage-aggregate.js";
+import { v4ToLegacy } from "./domain/row-v4.js";
+import { failure } from "./domain/errors.js";
 export async function runResumeCommand(options) {
     const loaded = await loadMergeState(options.io, options.home);
-    const row = loaded.state.rows.find(item => item.id === options.rowId);
+    let row = loaded.state.rows.find(item => item.id === options.rowId);
     if (row === undefined)
-        return { ok: false, message: 'merge row not found: ' + options.rowId };
-    if (row.state === 'verify') {
+        return failure('resume', 'row-not-found', '找不到可恢复行 ' + options.rowId, '运行 /evolution merge candidates 查看可恢复行');
+    const selected = row;
+    if (selected.state === 'verify') {
         if (row.runId !== undefined && (await options.isOwnerActive?.(row.runId)) === true) {
-            return { ok: false, message: 'merge run still owns this verify row: ' + row.runId };
+            return failure('resume', 'run-owns-row', '该 verify 行仍由运行中的 run 持有：' + row.runId, '等待该 run 结束，或运行 /evolution merge cancel ' + row.runId, row.runId);
         }
         return await runScanCommand({
             io: options.io, home: options.home, registry: options.registry,
-            approval: true, platformWrite: options.platformWrite, now: options.now,
+            approval: options.approval, platformWrite: options.platformWrite, now: options.now,
+            ...(options.detached === true ? { detached: true } : {}),
             ...(options.makePorts === undefined
-                ? { ports: { ...options.ports, screening: () => Promise.resolve([{ a: row.a, b: row.b }]) } }
+                ? { ports: { ...options.ports, screening: () => Promise.resolve([{ a: selected.a, b: selected.b }]) } }
                 : {
                     makePorts: (runId) => {
                         const makePorts = options.makePorts;
                         if (makePorts === undefined)
                             throw new Error('resume makePorts disappeared');
-                        return { ...makePorts(runId), screening: () => Promise.resolve([{ a: row.a, b: row.b }]) };
+                        return { ...makePorts(runId), screening: () => Promise.resolve([{ a: selected.a, b: selected.b }]) };
                     },
                 }),
             ...(options.timeoutMinutes === undefined ? {} : { timeoutMinutes: options.timeoutMinutes }),
@@ -29,16 +40,39 @@ export async function runResumeCommand(options) {
         });
     }
     if (row.state !== 'fuse' && row.state !== 'approved')
-        return { ok: false, message: 'row is not resumable from state ' + row.state };
+        return failure('resume', 'row-not-resumable', '该行状态是 ' + row.state + '，不可恢复', '只有 approved/fuse 行可恢复；运行 /evolution merge status 查看队列', row.runId);
     if (row.runId !== undefined && (await options.isOwnerActive?.(row.runId)) === true) {
-        return { ok: false, message: 'merge run still owns this fuse row: ' + row.runId };
+        return failure('resume', 'run-owns-row', '该 fuse 行仍由运行中的 run 持有：' + row.runId, '等待该 run 结束，或运行 /evolution merge cancel ' + row.runId, row.runId);
     }
-    const decision = row.decision;
+    if (options.agentless === true)
+        return failure('resume', 'e-305', errorText('e-305-this-invocation-carries-no', { a1: 'resume' }), '在 GUI 或 CLI 的会话里运行 /evolution merge resume --retry ' + row.id);
+    const parentRunId = options.parentRunId ?? row.runId;
+    if (parentRunId === undefined)
+        return failure('resume', 'merge-parent-required', '缺 parent run id（E-305 提示：该行可能由无会话调用创建，或父 run 已丢失）', '在 agent 会话中执行 /evolution merge resume --retry ' + row.id, row.runId);
+    const decision = selected.decision;
     if (decision === undefined)
-        return { ok: false, message: 'fuse row has no decision' };
-    return await withMergeRun({
+        return failure('resume', 'row-invalid', '该 fuse 行没有持久化决策', '重新 pair 该技能对后再次恢复', row.runId);
+    if (selected.state === 'approved' && options.ports.stage !== undefined) {
+        const staged = await options.ports.stage(selected, decision);
+        if (!staged.ok)
+            return failure('resume', 'stage-failed', staged.message, '检查暂存目录后重试；不影响已记录的决策', selected.runId);
+        const fused = await pairLedger(options.io, options.home).transact(tx => {
+            const current = tx.rows().find(item => item.id === selected.id);
+            if (current === undefined)
+                return null;
+            const moved = tx.transition(selected.id, { type: 'staged' }, current.version);
+            return moved.ok && moved.row !== null ? v4ToLegacy(moved.row) : null;
+        });
+        if (fused === null)
+            return failure('resume', 'row-changed', '行在暂存完成前被并发修改：' + selected.id, '运行 /evolution merge status ' + selected.id + ' 后重试', selected.runId);
+        await presentStage(options.io, options.home, staged.entry);
+        row = fused;
+    }
+    const result = await withMergeRun({
         io: options.io, home: options.home, registry: options.registry,
-        command: 'resume', approval: { platformWrite: options.platformWrite, mergeApproval: true }, now: options.now,
+        command: 'resume', approval: { platformWrite: options.platformWrite, mergeApproval: options.approval }, pairKey: row.pairKey,
+        parentRunId, now: options.now,
+        ...(options.detached === true ? { detached: true } : {}),
         async body(ctx) {
             await ctx.stage('author', { done: 0, total: 1 });
             let outcome;
@@ -50,15 +84,17 @@ export async function runResumeCommand(options) {
             catch (error) {
                 outcome = { kind: 'failed', failure: { stage: 'author', code: 'merge-failed', message: error instanceof Error ? error.message : String(error), retryable: true, retryFrom: 'agent2' } };
             }
-            const record = await recordRound2Outcome(options.io, options.home, options.now, row, outcome);
+            const record = await recordRound2Outcome(options.io, options.home, options.now, row, outcome, true);
             return {
                 stopReason: record.merged ? 'completed' : 'failed',
                 scope: { candidatePairs: 1, queueBefore: { verify: 0, pending: 0, fuse: 1, skipped: 0 } },
                 pairs: [record.pair],
                 totals: record.merged ? { merged: 1, kept: 0, pending: 0, failed: 0 } : { merged: 0, kept: 0, pending: 0, failed: 1 },
                 notes: [],
+                ...(record.finalize === undefined ? {} : { finalize: record.finalize }),
             };
         },
     });
+    return result;
 }
 //# sourceMappingURL=resume-command.js.map

package/lib/types/revision.d.ts

@@ -1,6 +1,23 @@
 import type { SkillCard } from './skill-card.ts';
+import type { RevisionRef } from './contracts.ts';
 /** Stable source revision for a pair: names sorted, body+support hashed in that order. */
 export declare function sourceRevisionOf(cards: readonly SkillCard[], a: string, b: string): string | undefined;
 /** Revision of the merge target; undefined when the target is not a live card. */
 export declare function targetRevisionOf(cards: readonly SkillCard[], target: string): string | undefined;
+export declare function targetRevisionRefOf(cards: readonly SkillCard[], target: string): RevisionRef;
+/** Per-skill anchors for a set of names; absent names stay `kind: 'absent'` so a
+ *  later commit can tell "was not there" from "was not checked". */
+export declare function sourceRevisionRefsOf(cards: readonly SkillCard[], names: readonly string[]): Readonly<Record<string, RevisionRef>>;
+export declare function sourceRevisionRefOf(cards: readonly SkillCard[], a: string, b: string): RevisionRef;
+/** Record the round-1 anchors a later commit re-checks (target/source/support). */
+export declare function withDecisionRevisions<T extends {
+    readonly target: string;
+}>(decision: T, cards: readonly SkillCard[], a: string, b: string): T & {
+    readonly targetRevisionRef: RevisionRef;
+    readonly sourceRevisionRef: RevisionRef;
+    readonly sourceRevisions: Readonly<Record<string, RevisionRef>>;
+    readonly supportDigest: string;
+};
+export declare function supportDigestOf(cards: readonly SkillCard[], names: readonly string[]): string;
+export declare function revisionMismatch(expected: RevisionRef | undefined, current: RevisionRef): 'target-taken' | 'source-changed' | null;
 //# sourceMappingURL=revision.d.ts.map

package/lib/types/revision.js

@@ -1,7 +1,6 @@
-import { contentHash } from '@lmzhen/dsh-evolution-core';
+import { contentHash, revisionFingerprint, revisionSupportDigest } from '@lmzhen/dsh-evolution-core';
 function fingerprint(card) {
-    const files = [...(card.files ?? [])].sort((left, right) => left.path.localeCompare(right.path));
-    return card.name + '\u0000' + card.body + '\u0000' + files.map(file => file.path + '\u0000' + file.content).join('\u0000');
+    return revisionFingerprint(card.name, card.body, card.files ?? []);
 }
 /** Stable source revision for a pair: names sorted, body+support hashed in that order. */
 export function sourceRevisionOf(cards, a, b) {
@@ -18,4 +17,41 @@ export function targetRevisionOf(cards, target) {
     const card = cards.find(item => item.name === target);
     return card === undefined ? undefined : contentHash(fingerprint(card));
 }
+export function targetRevisionRefOf(cards, target) {
+    const revision = targetRevisionOf(cards, target);
+    return revision === undefined ? { kind: 'absent' } : { kind: 'present', sha256: revision };
+}
+/** Per-skill anchors for a set of names; absent names stay `kind: 'absent'` so a
+ *  later commit can tell "was not there" from "was not checked". */
+export function sourceRevisionRefsOf(cards, names) {
+    const byName = new Map(cards.map(card => [card.name, card]));
+    const out = {};
+    for (const name of [...new Set(names)].sort()) {
+        const card = byName.get(name);
+        out[name] = card === undefined ? { kind: 'absent' } : { kind: 'present', sha256: contentHash(fingerprint(card)) };
+    }
+    return out;
+}
+export function sourceRevisionRefOf(cards, a, b) {
+    const revision = sourceRevisionOf(cards, a, b);
+    return revision === undefined ? { kind: 'absent' } : { kind: 'present', sha256: revision };
+}
+/** Record the round-1 anchors a later commit re-checks (target/source/support). */
+export function withDecisionRevisions(decision, cards, a, b) {
+    return { ...decision, targetRevisionRef: targetRevisionRefOf(cards, decision.target), sourceRevisionRef: sourceRevisionRefOf(cards, a, b), sourceRevisions: sourceRevisionRefsOf(cards, [a, b]), supportDigest: supportDigestOf(cards, [decision.target, a, b]) };
+}
+export function supportDigestOf(cards, names) {
+    const byName = new Map(cards.map(card => [card.name, card]));
+    const involved = [...new Set(names)].map(name => byName.get(name)).filter((card) => card !== undefined);
+    return revisionSupportDigest(involved.map(fingerprint));
+}
+export function revisionMismatch(expected, current) {
+    if (expected === undefined)
+        return null;
+    if (expected.kind !== current.kind)
+        return 'target-taken';
+    if (expected.kind === 'absent')
+        return null;
+    return current.kind === 'present' && expected.sha256 === current.sha256 ? null : 'target-taken';
+}
 //# sourceMappingURL=revision.js.map

package/lib/types/round2-outcome.d.ts

@@ -8,6 +8,7 @@ import type { ScanRound2Outcome } from './scan-run.ts';
 export interface Round2Record {
     readonly pair: MergeReportPair;
     readonly merged: boolean;
+    readonly finalize?: () => Promise<void>;
 }
-export declare function recordRound2Outcome(io: EvolutionIoLike, home: string, now: () => number, row: MergeRow, outcome: ScanRound2Outcome): Promise<Round2Record>;
+export declare function recordRound2Outcome(io: EvolutionIoLike, home: string, now: () => number, row: MergeRow, outcome: ScanRound2Outcome, deferProjection?: boolean): Promise<Round2Record>;
 //# sourceMappingURL=round2-outcome.d.ts.map