@lmzhen/dsh-evolution-merge 0.30.23 → 0.30.25

package/lib/types/run-shell.js

@@ -1,5 +1,7 @@
 import { writeMergeReport } from "./report.js";
 import { writeRunMeta } from "./domain/run-coordinator.js";
+/** Bounded wait for a detached body before the run is reported as timed out. */
+const DETACHED_DRAIN_MS = 30_000;
 function emptyDraft(reason) {
     return {
         stopReason: 'failed',
@@ -21,7 +23,16 @@ export async function withMergeRun(options) {
     const startedAt = handle.startedAt;
     const stage = (name, progress) => options.registry.stage(handle.id, name, progress);
     await stage('screening', options.total === undefined ? undefined : { done: 0, total: options.total });
-    await writeRunMeta(options.io, options.home, { version: 1, runId: handle.id, ...(options.parentRunId === undefined ? {} : { parentRunId: options.parentRunId }), ...(options.pairKey === undefined ? {} : { pairKey: options.pairKey }), pairCount: options.pairCount ?? (options.pairKey === undefined ? 0 : 1), phase: 'running', approval: options.approval.mergeApproval ? 'pending' : 'approved', createdAt: new Date(startedAt).toISOString(), updatedAt: new Date(options.now()).toISOString() });
+    await writeRunMeta(options.io, options.home, {
+        version: 1, runId: handle.id, pid: process.pid,
+        ...(options.parentRunId === undefined ? {} : { parentRunId: options.parentRunId }),
+        ...(options.pairKey === undefined ? {} : { pairKey: options.pairKey }),
+        ...(options.stagingRef === undefined ? {} : { stagingRef: options.stagingRef }),
+        ...(options.pairKey === undefined ? {} : { pairs: [{ pairKey: options.pairKey, state: 'pending' }] }),
+        pairCount: options.pairCount ?? (options.pairKey === undefined ? 0 : 1),
+        phase: 'running', approval: options.approval.mergeApproval ? 'pending' : 'approved',
+        createdAt: new Date(startedAt).toISOString(), updatedAt: new Date(options.now()).toISOString(),
+    });
     const finish = async () => {
         let draft;
         const runController = new AbortController();
@@ -29,19 +40,46 @@ export async function withMergeRun(options) {
         handle.signal.addEventListener('abort', onAbort, { once: true });
         let timer;
         const timeoutMinutes = options.timeoutMinutes;
-        const timeout = timeoutMinutes === undefined || timeoutMinutes <= 0 ? undefined : new Promise((_, reject) => {
-            timer = setTimeout(() => {
-                runController.abort();
-                reject(new Error('merge run timed out after ' + String(timeoutMinutes) + ' minutes'));
-            }, timeoutMinutes * 60_000);
-        });
+        const bodyOutcome = options.body({ runId: handle.id, startedAt, signal: runController.signal, stage })
+            .then(value => ({ kind: 'draft', value }))
+            .catch(error => ({ kind: 'error', error }));
+        let outcome;
+        let timedOut = false;
         try {
-            draft = timeout === undefined
-                ? await options.body({ runId: handle.id, startedAt, signal: runController.signal, stage })
-                : await Promise.race([options.body({ runId: handle.id, startedAt, signal: runController.signal, stage }), timeout]);
-        }
-        catch (error) {
-            draft = emptyDraft('run body failed: ' + (error instanceof Error ? error.message : String(error)));
+            if (timeoutMinutes === undefined || timeoutMinutes <= 0) {
+                outcome = await bodyOutcome;
+            }
+            else {
+                const timeout = new Promise(resolve => {
+                    timer = setTimeout(() => {
+                        // Abort first, then wait for the body, but never without a second bound: a body
+                        // that ignores the signal must not leave the run open forever.
+                        runController.abort();
+                        resolve({ kind: 'timeout' });
+                    }, timeoutMinutes * 60_000);
+                });
+                const raced = await Promise.race([bodyOutcome, timeout]);
+                if (raced.kind !== 'timeout')
+                    outcome = raced;
+                else {
+                    timedOut = true;
+                    let drainTimer;
+                    const drained = await Promise.race([
+                        bodyOutcome,
+                        new Promise(resolve => { drainTimer = setTimeout(() => resolve({ kind: 'drain-timeout' }), DETACHED_DRAIN_MS); }),
+                    ]);
+                    if (drainTimer !== undefined)
+                        clearTimeout(drainTimer);
+                    outcome = drained.kind === 'drain-timeout'
+                        ? { kind: 'error', error: new Error('timeout: body did not stop within 30s drain window') }
+                        : drained;
+                }
+            }
+            draft = outcome.kind === 'draft'
+                ? outcome.value
+                : emptyDraft('run body failed: ' + (outcome.error instanceof Error ? outcome.error.message : String(outcome.error)));
+            if (timedOut)
+                draft = { ...draft, stopReason: 'timeout', notes: [...draft.notes, 'merge run timeout reached; body aborted'] };
         }
         finally {
             if (timer !== undefined)
@@ -59,9 +97,10 @@ export async function withMergeRun(options) {
             approval: options.approval,
             scope: draft.scope,
             pairs: draft.pairs,
+            processedPairs: draft.pairs,
             totals: draft.totals,
             notes: draft.notes,
-            ...(draft.remaining === undefined ? {} : { remaining: draft.remaining }),
+            ...(draft.remaining === undefined ? {} : { remaining: draft.remaining, remainingPairs: draft.remaining }),
             ...(draft.reportOnly === undefined ? {} : { reportOnly: draft.reportOnly }),
             ...(draft.validationFailures === undefined ? {} : { validationFailures: draft.validationFailures }),
             ...(draft.archived === undefined ? {} : { archived: draft.archived }),
@@ -99,7 +138,10 @@ export async function withMergeRun(options) {
             && (options.command === 'scan' || options.command === 'pair')
             && report.stopReason === 'completed'
             && report.totals.pending > 0;
-        await writeRunMeta(options.io, options.home, { version: 1, runId: handle.id, ...(options.parentRunId === undefined ? {} : { parentRunId: options.parentRunId }), ...(options.pairKey === undefined ? {} : { pairKey: options.pairKey }), pairCount: options.pairCount ?? (options.pairKey === undefined ? 0 : 1), phase: awaiting ? 'awaiting-approval' : 'settled', approval: awaiting ? 'pending' : 'approved', stopReason: report.stopReason, reportRef: reportPath, createdAt: new Date(startedAt).toISOString(), updatedAt: new Date(options.now()).toISOString() });
+        const finalPairs = draft.pairs.length > 0
+            ? draft.pairs.map(pair => ({ pairKey: pair.pairKey, state: pair.outcome === 'merged' ? 'fused' : pair.outcome === 'pending' ? 'pending' : 'skipped' }))
+            : options.pairKey === undefined ? [] : [{ pairKey: options.pairKey, state: 'pending' }];
+        await writeRunMeta(options.io, options.home, { version: 1, runId: handle.id, pid: process.pid, ...(options.parentRunId === undefined ? {} : { parentRunId: options.parentRunId }), ...(options.pairKey === undefined ? {} : { pairKey: options.pairKey }), ...(options.stagingRef === undefined ? {} : { stagingRef: options.stagingRef }), ...(finalPairs.length === 0 ? {} : { pairs: finalPairs }), pairCount: options.pairCount ?? (options.pairKey === undefined ? 0 : 1), phase: awaiting ? 'awaiting-approval' : 'settled', approval: awaiting ? 'pending' : 'approved', stopReason: report.stopReason, reportRef: reportPath, createdAt: new Date(startedAt).toISOString(), updatedAt: new Date(options.now()).toISOString() });
         if (report.stopReason === 'completed')
             return { ok: true, runId: handle.id, reportPath, report };
         return { ok: false, runId: handle.id, message: 'merge ' + report.stopReason, reportPath };

package/lib/types/runtime.d.ts

@@ -1,11 +1,12 @@
 import { SkillLibrary, type EvolutionIoLike, type UnitTransaction } from '@lmzhen/dsh-evolution-core';
-import { type MergeCandidate } from './contracts.ts';
+import { type MergeCandidate, type MergeDecision } from './contracts.ts';
 import type { MergeParams } from './params.ts';
 import type { SkillCard } from './skill-card.ts';
 import type { MergeRegistryPort } from './run-shell.ts';
 import type { MergeCommandService } from './merge-command.ts';
 import type { StageToolContext } from './stage-tool.ts';
 import type { ConversationChannelLike } from './channel-port.ts';
+export declare function forcedDecisionFor(a: string, b: string): MergeDecision;
 export interface MergeStageBindingPort {
     bind(context: StageToolContext): void;
     unbind(childId: string): void;
@@ -29,6 +30,8 @@ export interface MergeRuntimeDeps {
     /** Curator gate set: excluded/referenced/suppressed/protected builtins. */
     readonly isBlocked?: (name: string) => boolean | Promise<boolean>;
     readonly isOwnerActive?: (runId: string) => boolean | Promise<boolean>;
+    /** The host's current model identity, recorded on pending decisions. */
+    readonly model?: string;
     /** Run-scoped engine screening. */
     readonly screeningForRun: (cards: readonly SkillCard[], runId: string, signal: AbortSignal) => Promise<readonly MergeCandidate[]>;
     readonly stage?: MergeStageBindingPort;

package/lib/types/runtime.js

@@ -4,7 +4,7 @@
  * out of apply() and makes the mutating verbs testable with fakes.
  */
 import { createHash } from 'node:crypto';
-import { errorText, probeText, SkillLibrary, UnitTransactions, skillLibraryUnitBackend } from '@lmzhen/dsh-evolution-core';
+import { errorText, isProcessAlive, probeText, SkillLibrary, UnitTransactions, skillLibraryUnitBackend } from '@lmzhen/dsh-evolution-core';
 import { targetClaimUnitPort } from "./unit-claim.js";
 import { canRetry, pairKey } from "./contracts.js";
 import { skippedPairKeys } from "./skipped.js";
@@ -18,7 +18,7 @@ import { runApproveCommand } from "./approve-command.js";
 import { runResumeCommand } from "./resume-command.js";
 import { loadMergeState } from "./state.js";
 import { pairLedger } from "./domain/pair-ledger.js";
-import { readCommitReceipt } from "./commit-receipt.js";
+import { readCommitReceipts } from "./commit-receipt.js";
 import { runUndoOperation } from "./undo-operation.js";
 import { readStageIndex } from "./domain/stage-aggregate.js";
 import { skillLibraryUndoPort } from "./adapters/undo.js";
@@ -47,7 +47,7 @@ function busyTarget(rows, target, excludeRowId) {
     const row = rows.find(item => item.id !== excludeRowId && (item.state === 'approved' || item.state === 'fuse') && item.decision?.target === target);
     return row === undefined ? undefined : { id: row.id, ...(row.runId === undefined ? {} : { runId: row.runId }) };
 }
-function forcedDecisionFor(a, b) {
+export function forcedDecisionFor(a, b) {
     const sorted = [a, b].sort();
     const raw = ('merge-' + sorted.join('-')).replace(/[^a-zA-Z0-9._-]+/g, '-').replace(/^-+|-+$/g, '');
     const target = raw.length <= 64 ? raw : raw.slice(0, 55) + '-' + createHash('sha256').update(raw).digest('hex').slice(0, 8);
@@ -75,6 +75,7 @@ export function createMergeRuntime(deps) {
     const common = {
         io: deps.io, home: deps.home, registry: deps.registry,
         platformWrite: deps.platformWrite, now: deps.now,
+        ...(deps.model === undefined ? {} : { model: deps.model }),
         ...(deps.isOwnerActive === undefined ? {} : { isOwnerActive: deps.isOwnerActive }),
         ...(timeout === undefined ? {} : { timeoutMinutes: timeout }),
     };
@@ -92,8 +93,9 @@ export function createMergeRuntime(deps) {
                 const signal = new AbortController().signal;
                 if (command.a === command.b)
                     return fail('pair', 'pair-same-source', 'merge pair 需要两个不同技能源：' + command.a, '重新指定两个不同的 family-managed 技能');
-                if ([command.a, command.b].some(name => name.includes('/') || name.includes(':')))
-                    return fail('pair', 'target-invalid', '技能名不能包含 provider/name 或 provider:name 语法：' + command.a + ' / ' + command.b, '使用裸技能名重新 pair');
+                if ([command.a, command.b].some(name => name.includes('/') || name.includes(':'))) {
+                    return { ok: false, text: 'merge: 技能名不能包含 provider/name 或 provider:name 语法：' + command.a + ' / ' + command.b + ' (provider-conflict)\nusage: /evolution merge pair <a> <b>' };
+                }
                 // FR-RUN-03: a session-less invocation cannot host a merge child. Answer E-305 in
                 // the three-line shape instead of opening a run that is guaranteed to fail.
                 if (agentless)
@@ -101,8 +103,16 @@ export function createMergeRuntime(deps) {
                 // FR-EXEC-17/NFR-04: two pair runs for one pair must not race for the same row.
                 const pairKeyValue = pairKey(command.a, command.b);
                 const inFlight = inFlightPairRun(await readRunMetas(deps.io, deps.home), pairKeyValue);
-                if (inFlight !== undefined && (deps.isOwnerActive === undefined || (await deps.isOwnerActive(inFlight.runId)) === true)) {
-                    return fail('pair', 'merge-pair-in-flight', '同一 pair 已在运行 ' + inFlight.runId, '等待该 run 结束，或运行 /evolution merge status ' + inFlight.runId, inFlight.runId);
+                let ownerActive = false;
+                if (inFlight !== undefined) {
+                    if (deps.isOwnerActive !== undefined)
+                        ownerActive = await deps.isOwnerActive(inFlight.runId);
+                    else
+                        ownerActive = inFlight.pid === undefined ? true : isProcessAlive(inFlight.pid);
+                }
+                if (inFlight !== undefined && ownerActive) {
+                    // NFR-04: the same pair is idempotent, not an error — answer the run that already owns it.
+                    return { ok: true, text: 'merge pair 已在运行：' + inFlight.runId + '；作用域：family-managed 技能对，1 对，无 per-run 上限' };
                 }
                 const cards = await deps.cards(signal);
                 const cardA = cards.find(card => card.name === command.a);
@@ -119,10 +129,12 @@ export function createMergeRuntime(deps) {
                 }
                 const pair = [{ a: command.a, b: command.b }];
                 const existing = (await loadMergeState(deps.io, deps.home)).state.rows.find(row => row.pairKey === pairKey(command.a, command.b));
-                if (existing?.state === 'skipped') {
+                let cleared = false;
+                if (existing?.state === 'skipped' || (existing?.state === 'fuse' && existing.failure?.retryable === false)) {
                     const dropped = await removeRuntimeRow(deps.io, deps.home, existing.id, 'superseded');
                     if (!dropped)
-                        return fail('pair', 'row-changed', '清理 skipped 行时发现并发修改：' + existing.id, '运行 /evolution merge status 后重试');
+                        return fail('pair', 'row-changed', '清理可替换行时发现并发修改：' + existing.id, '运行 /evolution merge status 后重试');
+                    cleared = true;
                 }
                 if (existing?.state === 'verify' && existing.runId !== undefined && (await deps.isOwnerActive?.(existing.runId)) === true) {
                     return fail('pair', 'merge-pair-in-flight', '同一 pair 已在运行 ' + existing.runId, '等待该 run 结束，或运行 /evolution merge status ' + existing.runId, existing.runId);
@@ -130,7 +142,7 @@ export function createMergeRuntime(deps) {
                 if (existing?.state === 'pending') {
                     return fail('pair', 'pair-pending', '该 pair 已在待批准队列：' + existing.id, '先运行 /evolution merge approve/reject/discard ' + existing.id, existing.runId);
                 }
-                if (existing?.state === 'approved' || existing?.state === 'fuse') {
+                if (!cleared && (existing?.state === 'approved' || existing?.state === 'fuse')) {
                     return fail('pair', 'pair-fuse', '该 pair 已在待合并队列，可复用决策重跑', '运行 /evolution merge resume --retry ' + (existing.runId ?? existing.id), existing.runId);
                 }
                 const forced = command.force === true ? forcedDecisionFor(command.a, command.b) : undefined;
@@ -159,7 +171,7 @@ export function createMergeRuntime(deps) {
                 if (!result.ok)
                     return failRun('pair', result.message, '修复后重新发起 pair；run 报告见 /evolution merge report', result);
                 if ('accepted' in result)
-                    return { ok: true, text: 'merge pair 已启动：' + result.runId };
+                    return { ok: true, text: 'merge pair 已启动：' + result.runId + '；作用域：family-managed 技能对，1 对，无 per-run 上限' };
                 if (!('report' in result))
                     return fail('pair', 'report-missing', 'merge pair 已结束但没有写报告', '重新运行 pair，或运行 /evolution merge runs 查看运行');
                 return { ok: true, text: 'merge pair 完成：merged ' + String(result.report.totals.merged) + ' / pending ' + String(result.report.totals.pending) + ' / failed ' + String(result.report.totals.failed) };
@@ -225,7 +237,7 @@ export function createMergeRuntime(deps) {
                 if (!result.ok)
                     return failRun('scan', result.message, '修复后重新 scan；run 报告见 /evolution merge report', result);
                 if ('accepted' in result)
-                    return { ok: true, text: 'merge scan 已启动：' + result.runId };
+                    return { ok: true, text: 'merge scan 已启动：' + result.runId + '；作用域：family-managed 技能库，候选来源 engine screening，无 per-run 上限' };
                 if (!('report' in result))
                     return fail('scan', 'report-missing', 'merge scan 已结束但没有写报告', '重新运行 scan，或运行 /evolution merge runs 查看运行');
                 return { ok: true, text: 'merge scan 完成：merged ' + String(result.report.totals.merged) + ' / pending ' + String(result.report.totals.pending) + ' / failed ' + String(result.report.totals.failed) };
@@ -267,7 +279,7 @@ export function createMergeRuntime(deps) {
                 if (!result.ok)
                     return failRun('candidates', result.message, '修复后重试 candidates --retry', result);
                 if ('accepted' in result)
-                    return { ok: true, text: 'candidates --retry 已启动：' + result.runId };
+                    return { ok: true, text: 'candidates --retry 已启动：' + result.runId + '；作用域：单条 verify 行重跑，无 per-run 上限' };
                 if (!('report' in result))
                     return fail('candidates', 'report-missing', 'candidates --retry 已结束但没有写报告', '运行 /evolution merge runs 查看运行');
                 return { ok: true, text: 'candidates --retry 完成：merged ' + String(result.report.totals.merged) + ' / pending ' + String(result.report.totals.pending) + ' / failed ' + String(result.report.totals.failed) };
@@ -351,17 +363,15 @@ export function createMergeRuntime(deps) {
                 return { ok: true, text: '已丢弃合并行：' + command.id };
             }
             if (command.verb === 'undo') {
-                const receipt = await readCommitReceipt(deps.io, deps.home, command.run, command.target);
-                if (receipt === null)
-                    return fail('undo', 'receipt-not-found', '该 run 没有提交回执：' + command.run, '只有已提交的 run 可 undo；运行 /evolution merge runs 查看');
-                if (receipt.target !== command.target)
-                    return fail('undo', 'receipt-target-mismatch', '回执目标是 ' + receipt.target + '，不是 ' + command.target, '按回执目标重新运行 undo');
-                const undoRunId = receipt.parentRunId ?? receipt.runId;
+                const receipts = (await readCommitReceipts(deps.io, deps.home)).filter(receipt => (receipt.parentRunId ?? receipt.runId) === command.run && receipt.target === command.target);
+                if (receipts.length === 0)
+                    return fail('undo', 'receipt-not-found', '该 run 没有目标回执：' + command.run + ' / ' + command.target, '只有已提交的 run 可 undo；运行 /evolution merge runs 查看');
+                const undoRunId = receipts[0].parentRunId ?? receipts[0].runId;
                 const undoRegistry = deps.registry;
                 if (undoRegistry.runs('merge').some(run => run.id === undoRunId && run.supersededAt !== undefined))
                     return fail('undo', 'run-superseded', '该 run 已因技能树 restore 失效，不能再 undo：' + undoRunId, '运行 /evolution merge runs 查看失效标记');
                 const unit = unitFor(deps);
-                const result = await runUndoOperation({ io: deps.io, home: deps.home, runId: undoRunId, port: skillLibraryUndoPort(deps.skills), now: deps.now, ...(receipt.pairKey === undefined ? {} : { pairKey: receipt.pairKey }), ...(unit === undefined ? {} : { finalizeUnit: id => unit.finalize.call(unit, id) }) });
+                const result = await runUndoOperation({ io: deps.io, home: deps.home, runId: undoRunId, port: skillLibraryUndoPort(deps.skills), now: deps.now, target: command.target, ...(unit === undefined ? {} : { finalizeUnit: id => unit.finalize.call(unit, id) }) });
                 return result.ok ? { ok: true, text: result.message } : fail('undo', 'undo-failed', result.message, '检查回执与暂存后重试');
             }
             if (command.verb === 'skipped' && command.restore !== undefined) {
@@ -437,6 +447,7 @@ export function createMergeRuntime(deps) {
                     }),
                     round2WithRun: createNewChildRound2({
                         io: deps.io, home: deps.home, cards, channel: deps.channel, parent,
+                        parentRunId: (runId) => runId,
                         allow: deps.allow, ...(deps.cwd === undefined ? {} : { cwd: deps.cwd }),
                         timeoutMs: deps.params.mergePairTimeoutMinutes * 60_000,
                         commitPort: skillLibraryPort(deps.skills), now: deps.now, ...(unitFor(deps) === undefined ? {} : { unit: unitFor(deps) }),
@@ -448,7 +459,7 @@ export function createMergeRuntime(deps) {
                 if (!result.ok)
                     return failRun('resume', result.message, '修复后重新 resume；run 报告见 /evolution merge report', result);
                 if ('accepted' in result)
-                    return { ok: true, text: 'merge resume 已启动：' + result.runId };
+                    return { ok: true, text: 'merge resume 已启动：' + result.runId + '；作用域：单条待合并行重跑 agent2，无 per-run 上限' };
                 if (!('report' in result))
                     return fail('resume', 'report-missing', 'merge resume 已结束但没有写报告', '重新运行 resume，或运行 /evolution merge runs 查看运行');
                 return { ok: true, text: 'merge resume 完成：merged ' + String(result.report.totals.merged) };
@@ -549,6 +560,7 @@ export function createMergeRuntime(deps) {
                         stage: createStageForCards({ io: deps.io, home: deps.home, runId: command.id, cards, now: deps.now }),
                         round2: createNewChildRound2({
                             io: deps.io, home: deps.home, cards, channel: deps.channel, parent,
+                            parentRunId: (runId) => runId,
                             allow: deps.allow, ...(deps.cwd === undefined ? {} : { cwd: deps.cwd }),
                             timeoutMs: deps.params.mergePairTimeoutMinutes * 60_000,
                             commitPort: skillLibraryPort(deps.skills), now: deps.now, ...(unitFor(deps) === undefined ? {} : { unit: unitFor(deps) }),
@@ -561,7 +573,7 @@ export function createMergeRuntime(deps) {
                 if (!result.ok)
                     return failRun('approve', result.message, '修复后重新 approve；run 报告见 /evolution merge report', result);
                 if ('accepted' in result)
-                    return { ok: true, text: 'merge approve 已启动：' + result.runId };
+                    return { ok: true, text: 'merge approve 已启动：' + result.runId + '；作用域：单条 pending 行批准后重跑 agent2，无 per-run 上限' };
                 if (!('report' in result))
                     return fail('approve', 'report-missing', 'merge approve 已结束但没有写报告', '重新运行 approve，或运行 /evolution merge runs 查看运行');
                 return { ok: true, text: 'merge approve 完成：merged ' + String(result.report.totals.merged) };

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

@@ -20,6 +20,7 @@ export interface RunScanCommandOptions {
     readonly notes?: readonly string[];
     readonly isOwnerActive?: (runId: string) => boolean | Promise<boolean>;
     readonly cards?: readonly import('./skill-card.ts').SkillCard[];
+    readonly model?: string;
 }
 export declare function runScanCommand(options: RunScanCommandOptions): Promise<WithMergeRunResult>;
 //# sourceMappingURL=scan-command.d.ts.map

package/lib/types/scan-command.js

@@ -28,6 +28,7 @@ export async function runScanCommand(options) {
                 ...(options.notes === undefined ? {} : { notes: options.notes }),
                 ...(options.isOwnerActive === undefined ? {} : { isOwnerActive: options.isOwnerActive }),
                 ...(options.cards === undefined ? {} : { cards: options.cards }),
+                ...(options.model === undefined ? {} : { model: options.model }),
             });
         },
     });

package/lib/types/scan-ports.js

@@ -85,6 +85,7 @@ export function createChannelScanPorts(options) {
                     reuseStaging: true,
                     target: decision.target,
                     mode: decision.mode,
+                    sources: [row.a, row.b],
                     cards: options.cards,
                     commitPort: options.commitPort,
                     ...(options.unit === undefined ? {} : { unit: options.unit }),
@@ -94,6 +95,7 @@ export function createChannelScanPorts(options) {
                     ...(options.limits === undefined ? {} : { limits: options.limits }),
                     promptVersion: MERGE_PROMPT_VERSION,
                     promptHash: promptHashOf(buildRound2Prompt(row, decision)),
+                    signal,
                     revisions: {
                         ...(decision.targetRevisionRef === undefined ? {} : { targetRevision: decision.targetRevisionRef }),
                         ...(decision.sourceRevisions === undefined ? {} : { sourceRevisions: decision.sourceRevisions }),
@@ -113,6 +115,7 @@ export function createChannelScanPorts(options) {
                     ...(receipt?.unitId === undefined ? {} : { unitId: receipt.unitId }),
                     ...(receipt?.evidenceSha256 === undefined ? {} : { evidenceSha256: receipt.evidenceSha256 }),
                     ...(receipt?.validationPlan === undefined ? {} : { validationPlan: receipt.validationPlan }),
+                    ...(authored.lengths === undefined ? {} : { lengths: authored.lengths }),
                     ...(usage === undefined ? {} : { usage }),
                     archived: receipt?.archived ?? [],
                     target: { requested: decision.target, actual: authored.commit.plan.target, created: receipt?.create ?? false },

package/lib/types/scan-run.d.ts

@@ -2,7 +2,7 @@
  * The scan pair loop. Registry/report lifecycle stays in withMergeRun; this module owns
  * candidate → round1 → pending/fuse → commit transitions and returns the report draft.
  */
-import { type MergeCandidate, type MergeDecision, type MergeFailure, type MergeRow } from './contracts.ts';
+import { type MergeCandidate, type MergeDecision, type MergeFailure, type MergeValidationIssue, type MergeRow } from './contracts.ts';
 import { type StageEntry } from './domain/stage-aggregate.ts';
 import type { EvolutionIoLike, RunStage } from '@lmzhen/dsh-evolution-core';
 import type { SkillCard } from './skill-card.ts';
@@ -23,6 +23,9 @@ export interface ScanRound2Outcome {
     readonly unitId?: string;
     readonly evidenceSha256?: string;
     readonly validationPlan?: import('./contracts.ts').MergeValidationPlanRef;
+    readonly manifestFiles?: readonly string[];
+    readonly criteria?: import('./contracts.ts').MergeCriteria;
+    readonly validationIssues?: readonly MergeValidationIssue[];
     readonly archived?: readonly string[];
     readonly target?: {
         readonly requested: string;
@@ -63,6 +66,8 @@ export interface RunScanOptions {
     readonly runId?: string;
     readonly isOwnerActive?: (runId: string) => boolean | Promise<boolean>;
     readonly cards?: readonly SkillCard[];
+    /** The model identity recorded on pending decisions/summary; absent when the host has none. */
+    readonly model?: string;
 }
 export declare function runScan(options: RunScanOptions): Promise<MergeRunReportDraft>;
 //# sourceMappingURL=scan-run.d.ts.map

package/lib/types/scan-run.js

@@ -23,6 +23,15 @@ function failureOf(stage, error) {
         retryFrom: stage === 'decide' ? 'agent1' : 'agent2',
     };
 }
+function pairCriteria(outcome) {
+    if (outcome === 'merged')
+        return { decision: 'merge', validation: 'required', commit: 'required', archive: 'sources', evidence: 'receipt' };
+    if (outcome === 'kept')
+        return { decision: 'keep', validation: 'report-only', commit: 'never', archive: 'none', evidence: 'none' };
+    if (outcome === 'pending')
+        return { decision: 'merge', validation: 'required', commit: 'if-approved', archive: 'none', evidence: 'none' };
+    return { decision: 'merge', validation: 'required', commit: 'never', archive: 'none', evidence: 'none' };
+}
 function pairOf(row, candidate, outcome, extra = {}) {
     return {
         id: row.id,
@@ -34,6 +43,7 @@ function pairOf(row, candidate, outcome, extra = {}) {
         ...(candidate.gate === undefined ? {} : { gate: candidate.gate }),
         outcome,
         archived: [],
+        criteria: pairCriteria(outcome),
         ...extra,
     };
 }
@@ -176,7 +186,8 @@ export async function runScan(options) {
             totals.failed += 1;
             continue;
         }
-        const mergeDecision = options.cards !== undefined ? withDecisionRevisions(round1.decision, options.cards, row.a, row.b) : round1.decision;
+        const decided = options.model === undefined || round1.decision.model !== undefined ? round1.decision : { ...round1.decision, model: options.model };
+        const mergeDecision = options.cards !== undefined ? withDecisionRevisions(decided, options.cards, row.a, row.b) : decided;
         if (options.approval) {
             const event = { type: 'verify-passed', decision: mergeDecision, target: mergeDecision.target, ...(round1.sourceRevision === undefined ? {} : { sourceRevision: round1.sourceRevision }), ...(mergeDecision.promptVersion === undefined ? {} : { promptVersion: mergeDecision.promptVersion }), ...(mergeDecision.promptHash === undefined ? {} : { promptHash: mergeDecision.promptHash }) };
             const projected = await pairLedger(options.io, options.home).transact(tx => {
@@ -223,7 +234,7 @@ export async function runScan(options) {
             const current = tx.rows().find(item => item.id === row.id);
             if (current === undefined)
                 return null;
-            const moved = tx.transition(row.id, { type: 'staged' }, current.version);
+            const moved = tx.transition(row.id, { type: 'staged', ...(stageEntry === undefined ? {} : { stagingRef: stageEntry.ref, stagingExpiresAt: stageEntry.expiresAt }) }, current.version);
             return moved.ok && moved.row !== null ? v4ToLegacy(moved.row) : null;
         });
         if (fused === null) {
@@ -235,17 +246,15 @@ export async function runScan(options) {
         if (stageEntry !== undefined)
             await presentStage(options.io, options.home, stageEntry);
         if (isAborted(options.signal)) {
-            const projected = await pairLedger(options.io, options.home).transact(tx => {
+            // Cancel/timeout after staging is not a policy close: remove the in-flight row (so the
+            // next scan can re-evaluate it) and drop its stage tree. Never write skipped here.
+            await pairLedger(options.io, options.home).transact(tx => {
                 const current = tx.rows().find(item => item.id === row.id);
-                if (current === undefined)
-                    return null;
-                const moved = tx.transition(row.id, { type: 'skipped', reason: 'cancelled' }, current.version);
-                return moved.ok && moved.row !== null ? v4ToLegacy(moved.row) : null;
+                return current === undefined ? false : tx.remove(row.id, 'superseded', undefined, current.version).ok;
             });
-            if (projected !== null)
-                row = projected;
+            await dropStage(options.io, options.home, row.id, row.stagingRef);
             stopReason = 'cancelled';
-            remaining.push(...candidates.slice(index).map(candidate => ({ pairKey: pairKey(candidate.a, candidate.b), queue: 'fuse' })));
+            remaining.push(...candidates.slice(index).map(candidate => ({ pairKey: pairKey(candidate.a, candidate.b), queue: 'verify' })));
             break;
         }
         await stage('author', { done: index, total: candidates.length });
@@ -260,6 +269,8 @@ export async function runScan(options) {
             finalizeRows.push({ id: row.id, unitId: round2.unitId ?? 'unknown', evidenceSha256: round2.evidenceSha256 ?? 'unknown' });
             pairs.push({ ...pairOf(row, candidate, 'merged', {
                     decision: mergeDecision,
+                    ...(round2.manifestFiles === undefined ? {} : { manifestFiles: round2.manifestFiles }),
+                    ...(round2.validationIssues === undefined ? {} : { validation: { issues: round2.validationIssues } }),
                     ...(round2.unitId === undefined ? {} : { unitId: round2.unitId }),
                     ...(round2.target === undefined ? {} : { target: round2.target }),
                     ...(round2.usage === undefined ? {} : { usage: round2.usage }),
@@ -270,30 +281,31 @@ export async function runScan(options) {
             continue;
         }
         const failed = round2.failure ?? failureOf('author', 'round2 failed');
-        if (failed.code === 'merge-over-limit' || failed.code === 'limit' || failed.code === 'merge-validation') {
-            const reason = failed.code === 'merge-validation' ? 'validation-failed' : 'merge-over-limit';
+        if (failed.code === 'merge-over-limit' || failed.code === 'limit') {
+            const reason = 'merge-over-limit';
             const skipped = await pairLedger(options.io, options.home).transact(tx => {
                 const current = tx.rows().find(item => item.id === row.id);
                 return current === undefined ? false : tx.transition(row.id, { type: 'skipped', reason, origin: 'system', skipSource: 'system' }, current.version).ok;
             });
             if (skipped)
                 await dropStage(options.io, options.home, row.id);
-            pairs.push(pairOf(row, candidate, 'failed', { decision: mergeDecision, failure: failed }));
+            pairs.push(pairOf(row, candidate, 'failed', { decision: mergeDecision, failure: failed, ...(round2.manifestFiles === undefined ? {} : { manifestFiles: round2.manifestFiles }), ...(round2.criteria === undefined ? {} : { criteria: round2.criteria }), ...(round2.validationIssues === undefined ? {} : { validation: { issues: round2.validationIssues } }) }));
             totals.failed += 1;
             continue;
         }
         if (failed.code === 'target-changed' || failed.code === 'target-taken' || failed.code === 'source-changed' || failed.code === 'support-changed' || failed.code === 'source-gone') {
             const code = failed.code === 'target-changed' ? 'target-taken' : failed.code === 'support-changed' ? 'source-changed' : failed.code;
+            const terminalFailure = { ...failed, code, retryable: false, retryFrom: 'none' };
             await pairLedger(options.io, options.home).transact(tx => {
                 const current = tx.rows().find(item => item.id === row.id);
                 if (current === undefined)
                     return false;
                 if (code === 'source-gone')
                     return tx.remove(row.id, 'superseded', undefined, current.version).ok;
-                return tx.transition(row.id, { type: 'skipped', reason: code, origin: 'system', skipSource: 'system' }, current.version).ok;
+                return tx.transition(row.id, { type: 'failed', failure: terminalFailure }, current.version).ok;
             });
             await dropStage(options.io, options.home, row.id);
-            pairs.push(pairOf(row, candidate, 'failed', { decision: mergeDecision, failure: { ...failed, code, retryable: false, retryFrom: 'none' } }));
+            pairs.push(pairOf(row, candidate, 'failed', { decision: mergeDecision, failure: terminalFailure }));
             totals.failed += 1;
             continue;
         }
@@ -306,11 +318,15 @@ export async function runScan(options) {
             return moved.ok && moved.row !== null ? v4ToLegacy(moved.row) : null;
         });
         if (projected === null && terminal) {
-            await pairLedger(options.io, options.home).transact(tx => {
+            const dropped = await pairLedger(options.io, options.home).transact(tx => {
                 const current = tx.rows().find(item => item.id === row.id);
                 return current === undefined ? false : tx.remove(row.id, 'superseded', undefined, current.version).ok;
             });
-            pairs.push(pairOf(row, candidate, 'failed', { decision: mergeDecision, failure: failed }));
+            if (dropped) {
+                await dropStage(options.io, options.home, row.id, row.stagingRef);
+                await recordPair(options.io, options.home, { pairKey: row.pairKey, runId: row.runId ?? 'merge', result: 'failed', ...(row.decision?.target === undefined ? {} : { target: row.decision.target }) });
+            }
+            pairs.push(pairOf(row, candidate, 'failed', { decision: mergeDecision, failure: failed, ...(round2.manifestFiles === undefined ? {} : { manifestFiles: round2.manifestFiles }), ...(round2.criteria === undefined ? {} : { criteria: round2.criteria }), ...(round2.validationIssues === undefined ? {} : { validation: { issues: round2.validationIssues } }) }));
             totals.failed += 1;
             continue;
         }
@@ -320,7 +336,7 @@ export async function runScan(options) {
             continue;
         }
         row = projected;
-        pairs.push(pairOf(row, candidate, 'failed', { decision: mergeDecision, failure: failed }));
+        pairs.push(pairOf(row, candidate, 'failed', { decision: mergeDecision, failure: failed, ...(round2.manifestFiles === undefined ? {} : { manifestFiles: round2.manifestFiles }), ...(round2.criteria === undefined ? {} : { criteria: round2.criteria }), ...(round2.validationIssues === undefined ? {} : { validation: { issues: round2.validationIssues } }) }));
         totals.failed += 1;
     }
     const selectionReportOnly = candidates.reportOnly ?? [];

package/lib/types/surface/merge-view.js

@@ -26,10 +26,15 @@ function actions(row) {
         return [renderAction('discard', context, true, true), renderAction('pair', context, true, true)];
     if (row.row.state === 'pending')
         return [renderAction('approve', context), renderAction('reject', context, true, true), renderAction('discard', context, true, true)];
-    if (row.row.state === 'approved' || row.row.state === 'fuse')
+    if (row.row.state === 'approved' || row.row.state === 'fuse') {
+        if (row.row.failure !== undefined && row.row.failure.retryable === false)
+            return [renderAction('pair', context, true, true), renderAction('discard', context, true, true)];
         return [renderAction('retry-resume', context, true, true), renderAction('discard', context, true, true), renderAction('status', context)];
+    }
     if (row.row.state === 'skipped')
         return [renderAction('restore', context, true, true)];
+    if (row.row.state === 'verify')
+        return [renderAction('retry-candidates', context)];
     return [renderAction('pair', context)];
 }
 function verifyState(row) {
@@ -59,7 +64,7 @@ export function toRowFact(row) {
         a: state.a, b: state.b,
         ...(target === undefined ? {} : { target }),
         ...(summary === undefined ? {} : { summary }),
-        ...(state.state === 'skipped' ? { reason: state.reason } : {}),
+        ...(state.state === 'skipped' ? { reason: state.reason, reasonCode: state.reason } : {}),
         ...(state.origin === undefined ? {} : { origin: state.origin }),
         ...(state.failure === undefined ? {} : { failure: { stage: state.failure.stage, code: state.failure.code, retryable: state.failure.retryable, retryFrom: state.failure.retryFrom, detail: state.failure.message } }),
         ...(staging === undefined ? {} : { staging }),
@@ -76,7 +81,10 @@ function runView(run, readAt, includeResultRef = false) {
     void includeResultRef;
     const record = run.record;
     const metaPhase = run.meta?.phase;
-    const state = metaPhase === 'undone' ? 'undone' : run.meta?.approval === 'pending' ? 'awaiting-approval' : record.state;
+    const state = metaPhase === 'undone' ? 'undone'
+        : run.meta?.stopReason === 'interrupted' ? 'interrupted'
+            : run.meta?.approval === 'pending' ? 'awaiting-approval'
+                : record.state;
     const stopReason = run.meta?.stopReason ?? (record.state === 'cancelled' ? 'cancelled' : record.state === 'failed' ? 'failed' : record.state === 'succeeded' ? 'completed' : undefined);
     return { wireVersion: 1, readAt, id: record.id, state, command: record.command ?? 'scan', ...(record.stage === undefined ? {} : { stage: record.stage }), progress: record.progress === undefined ? null : { done: record.progress.done, total: record.progress.total }, startedAt: record.startedAt, ...(record.endedAt === undefined ? {} : { endedAt: record.endedAt }), ...(stopReason === undefined ? {} : { stopReason }), ...(record.failure === undefined ? {} : { failure: { stage: 'settle', code: 'run-failed', retryable: false, retryFrom: 'none', detail: record.failure } }), ...(record.parentRunId === undefined ? {} : { parentRunId: record.parentRunId }), ...(run.pairs[0]?.pairKey === undefined ? {} : { currentPairKey: run.pairs[0].pairKey }), ...(record.resultRef === undefined ? {} : { resultRef: record.resultRef }), actions: [{ id: 'status', command: base + 'status ' + record.id, confirm: false, enabled: true }, { id: 'report', command: base + 'report ' + record.id, confirm: false, enabled: record.resultRef !== undefined }, { id: 'cancel', command: base + 'cancel ' + record.id, confirm: false, enabled: record.state === 'running' }] };
 }
@@ -121,6 +129,6 @@ export function buildRunDetail(snapshot, runId) {
 }
 export function buildRunsView(snapshot) { return { wireVersion: 1, readAt: snapshot.readAt, runs: [...snapshot.runs].sort((a, b) => b.record.startedAt - a.record.startedAt).map(run => runView(run, snapshot.readAt, true)) }; }
 export function buildDoctorView(snapshot) {
-    return { wireVersion: 1, readAt: snapshot.readAt, counts: snapshot.doctor.counts, ...(snapshot.runs[0] === undefined ? {} : { latestRun: runView(snapshot.runs[0], snapshot.readAt) }), staging: snapshot.doctor.staging, approval: snapshot.approval, ...(snapshot.blocked === undefined ? {} : { blocked: { code: snapshot.blocked.code, message: snapshot.blocked.message } }), rows: snapshot.doctor.rows };
+    return { wireVersion: 1, readAt: snapshot.readAt, counts: snapshot.doctor.counts, ...(snapshot.runs[0] === undefined ? {} : { latestRun: runView(snapshot.runs[0], snapshot.readAt) }), staging: snapshot.doctor.staging, approval: snapshot.approval, ...(snapshot.hostOnly === undefined ? {} : { hostOnly: snapshot.hostOnly }), ...(snapshot.blocked === undefined ? {} : { blocked: { code: snapshot.blocked.code, message: snapshot.blocked.message } }), rows: snapshot.doctor.rows };
 }
 //# sourceMappingURL=merge-view.js.map

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

@@ -1,7 +1,7 @@
 /** Batch 2b undo operation: per-pair preflight, journal, restore, receipt and settlement. */
 import type { EvolutionIoLike } from '@lmzhen/dsh-evolution-core';
 import { type MergeUndoPort } from './undo-merge.ts';
-export type UndoErrorCode = 'undo-unavailable-legacy-receipt' | 'undo-evidence-hash-mismatch' | 'undo-target-drift' | 'undo-source-drift' | 'undo-partial-state' | 'undo-unit-not-committed';
+export type UndoErrorCode = 'undo-unavailable-legacy-receipt' | 'undo-evidence-expired' | 'undo-evidence-hash-mismatch' | 'undo-target-drift' | 'undo-source-drift' | 'undo-partial-state' | 'undo-unit-not-committed';
 export interface UndoResult {
     readonly ok: boolean;
     readonly code?: UndoErrorCode;
@@ -15,6 +15,7 @@ export declare function runUndoOperation(options: {
     readonly port: MergeUndoPort;
     readonly now: () => number;
     readonly pairKey?: string;
+    readonly target?: string;
     readonly finalizeUnit?: (unitId: string) => Promise<{
         readonly ok: boolean;
         readonly message?: string;

package/lib/types/undo-operation.js

@@ -28,8 +28,13 @@ function sortReceipts(receipts) {
 }
 async function preflight(io, home, port, receipt) {
     const evidence = await readUnitEvidence(io, home, receipt.unitId);
-    if (evidence === null)
-        return { ok: false, code: 'undo-unavailable-legacy-receipt', message: 'commit evidence is missing; undo unavailable for legacy receipt', undone: [] };
+    if (evidence === null) {
+        // A legacy receipt never had evidence to hash. A receipt WITH evidenceSha256 whose unit is
+        // gone aged out of the retention window; undo must refuse, never guess (DEC-D11).
+        return receipt.evidenceSha256 === undefined
+            ? { ok: false, code: 'undo-unavailable-legacy-receipt', message: 'commit evidence is missing; undo unavailable for legacy receipt', undone: [] }
+            : { ok: false, code: 'undo-evidence-expired', message: 'commit evidence aged out of the retention window; undo unavailable (fail-closed)', undone: [] };
+    }
     const expectedSha = receipt.evidenceSha256 ?? unitEvidenceDigest(evidence);
     if (unitEvidenceDigest(evidence) !== expectedSha)
         return { ok: false, code: 'undo-evidence-hash-mismatch', message: 'commit receipt evidence hash does not match evidence', undone: [] };
@@ -67,8 +72,9 @@ async function settleRun(io, home, runId, pairKey, allPairs, at) {
     });
 }
 export async function runUndoOperation(options) {
-    const allReceipts = (await readCommitReceipts(options.io, options.home)).filter(receipt => (receipt.parentRunId ?? receipt.runId) === options.runId);
-    const allPairKeys = allReceipts.map(receipt => receipt.pairKey ?? receipt.unitId);
+    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);
     const receipts = options.pairKey === undefined ? allReceipts : allReceipts.filter(receipt => receipt.pairKey === options.pairKey);
     if (receipts.length === 0)
         return { ok: false, message: 'merge run has no commit receipt: ' + options.runId, undone: [] };