@lmzhen/dsh-evolution-merge 0.29.0 → 0.30.0

package/lib/types/routes.js

@@ -0,0 +1,75 @@
+import { queueOf, stageOf } from "./contracts.js";
+import { countRows } from "./status.js";
+export function toRowView(row) {
+    return {
+        id: row.id,
+        pairKey: row.pairKey,
+        a: row.a,
+        b: row.b,
+        state: row.state,
+        queue: queueOf(row.state),
+        stage: stageOf(row.state),
+        label: row.a + ' + ' + row.b,
+        updatedAt: row.updatedAt,
+        createdAt: row.createdAt,
+        ...(row.decision?.target === undefined ? {} : { target: row.decision.target }),
+        ...(row.decision?.confidence === undefined ? {} : { confidence: row.decision.confidence }),
+        ...(row.failure === undefined ? {} : {
+            failure: { stage: row.failure.stage, code: row.failure.code, message: row.failure.message, retryable: row.failure.retryable },
+        }),
+        ...(row.attempts === undefined ? {} : { attempts: row.attempts }),
+        ...(row.origin === undefined ? {} : { origin: row.origin }),
+        ...(row.stagingExpiresAt === undefined ? {} : { stagingExpiresAt: row.stagingExpiresAt }),
+        ...(row.expired === undefined ? {} : { expired: row.expired }),
+        ...(row.reason === undefined ? {} : { reason: row.reason }),
+        summary: [
+            row.a + ' + ' + row.b,
+            row.decision?.rationale ?? row.reason ?? '',
+            row.failure?.message ?? '',
+        ],
+        actions: row.state === 'pending'
+            ? ['/evolution merge approve ' + row.id, '/evolution merge reject ' + row.id]
+            : row.state === 'skipped'
+                ? ['/evolution merge skipped --restore ' + row.id]
+                : ['/evolution merge resume ' + row.id],
+    };
+}
+export function buildMergeView(rows, commands, latestRun, approval) {
+    const counts = countRows(rows);
+    return {
+        schemaVersion: 2,
+        counts,
+        tabs: [
+            { queue: 'verify', count: counts.verify },
+            { queue: 'pending', count: counts.pending },
+            { queue: 'fuse', count: counts.fuse },
+            { queue: 'skipped', count: counts.skipped },
+        ],
+        commands,
+        ...(latestRun === undefined ? {} : { latestRun }),
+        ...(approval === undefined ? {} : { approval }),
+    };
+}
+export function pageQueue(rows, queue, cursor = 0, limit = 50) {
+    const filtered = rows.filter(row => queueOf(row.state) === queue);
+    const size = Math.max(1, Math.min(200, limit));
+    const start = Math.max(0, cursor);
+    const items = filtered.slice(start, start + size).map(toRowView);
+    const next = start + size < filtered.length ? String(start + size) : undefined;
+    return { queue, items, ...(next === undefined ? {} : { nextCursor: next }) };
+}
+export function toRunFact(run) {
+    return {
+        id: run.id,
+        state: run.state,
+        ...(run.command === undefined ? {} : { command: run.command }),
+        ...(run.stage === undefined ? {} : { stage: run.stage }),
+        ...(run.progress === undefined ? {} : { progress: run.progress }),
+        startedAt: run.startedAt,
+        ...(run.endedAt === undefined ? {} : { endedAt: run.endedAt }),
+        ...(run.resultRef === undefined ? {} : { resultRef: run.resultRef }),
+        ...(run.failure === undefined ? {} : { failure: run.failure }),
+        ...(run.supersededAt === undefined ? {} : { supersededAt: run.supersededAt }),
+    };
+}
+//# sourceMappingURL=routes.js.map

package/lib/types/rules.js

@@ -0,0 +1,55 @@
+/**
+ * Deterministic gate for a staged merge tree. No io, no model.
+ *
+ * block = commit must not proceed; warn = report only. The path and reference checks reuse
+ * the skill-store's own `validateSupportPath` / `supportRefs`, so there is one whitelist.
+ */
+import { DEFAULT_SKILL_LIMITS, parseFrontmatter, scanContentThreats, supportRefs, validateFrontmatter, validateSupportPath, } from '@lmzhen/dsh-evolution-core';
+const PLACEHOLDER = /\bTODO\b|\bxxx\b|\{\{[^}]*\}\}/i;
+const DESC_WARN_LENGTH = 60;
+export function validateStagedTree(tree, limits = DEFAULT_SKILL_LIMITS) {
+    const findings = [];
+    const block = (rule, path, message) => { findings.push({ rule, path, severity: 'block', message }); };
+    const warn = (rule, path, message) => { findings.push({ rule, path, severity: 'warn', message }); };
+    const parsed = parseFrontmatter(tree.body);
+    if (parsed === null)
+        block('frontmatter', 'SKILL.md', 'SKILL.md has no valid frontmatter');
+    else {
+        const invalid = validateFrontmatter(tree.body, tree.target, limits);
+        if (invalid !== null)
+            block('frontmatter', 'SKILL.md', invalid);
+        const description = parsed.frontmatter.description ?? '';
+        if (description.length > DESC_WARN_LENGTH)
+            warn('desc-length', 'SKILL.md', 'description is longer than ' + String(DESC_WARN_LENGTH) + ' characters');
+    }
+    if (Buffer.byteLength(tree.body, 'utf8') > limits.maxSkillFileBytes)
+        block('bytes', 'SKILL.md', 'SKILL.md exceeds maxSkillFileBytes');
+    if (scanContentThreats(tree.body) !== null)
+        block('threat', 'SKILL.md', 'SKILL.md tripped the content threat scanner');
+    if (PLACEHOLDER.test(tree.body))
+        warn('placeholder', 'SKILL.md', 'SKILL.md contains a TODO/xxx/{{...}} placeholder');
+    const paths = new Set();
+    for (const file of tree.files) {
+        const badPath = validateSupportPath(file.path);
+        if (badPath !== null) {
+            block('path', file.path, badPath);
+            continue;
+        }
+        paths.add(file.path);
+        if (Buffer.byteLength(file.content, 'utf8') > limits.maxSkillFileBytes)
+            block('bytes', file.path, 'file exceeds maxSkillFileBytes');
+        if (scanContentThreats(file.content) !== null)
+            block('threat', file.path, 'file tripped the content threat scanner');
+        if (PLACEHOLDER.test(file.content))
+            warn('placeholder', file.path, 'file contains a TODO/xxx/{{...}} placeholder');
+    }
+    for (const ref of supportRefs(tree.body)) {
+        if (!paths.has(ref))
+            block('refs-pair', ref, 'body references a support file that is not staged');
+    }
+    return findings;
+}
+export function hasBlockingFinding(findings) {
+    return findings.some(finding => finding.severity === 'block');
+}
+//# sourceMappingURL=rules.js.map

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

@@ -12,6 +12,7 @@ export interface MergeRegistryPort {
         command?: MergeRunCommand;
         total?: number;
         parentRunId?: string;
+        mergeStatus?: 'running' | 'succeeded' | 'failed' | 'cancelled' | 'awaiting-approval' | 'undone' | 'superseded' | 'interrupted' | 'orphan';
     }): Promise<Pick<RunHandle, 'id' | 'signal' | 'startedAt'>>;
     stage(id: string, stage: RunStage, progress?: {
         done: number;
@@ -21,6 +22,7 @@ export interface MergeRegistryPort {
         state: 'succeeded' | 'failed' | 'cancelled';
         resultRef?: string;
         failure?: string;
+        mergeStatus?: 'running' | 'succeeded' | 'failed' | 'cancelled' | 'awaiting-approval' | 'undone' | 'superseded' | 'interrupted' | 'orphan';
     }): Promise<void>;
 }
 export interface MergeRunBodyContext {
@@ -48,6 +50,7 @@ export interface WithMergeRunOptions {
     readonly approval: MergeReport['approval'];
     readonly now: () => number;
     readonly total?: number;
+    readonly detached?: boolean;
     readonly body: (ctx: MergeRunBodyContext) => Promise<MergeRunReportDraft>;
 }
 export type WithMergeRunResult = {
@@ -55,6 +58,10 @@ export type WithMergeRunResult = {
     readonly runId: string;
     readonly reportPath: string;
     readonly report: MergeReport;
+} | {
+    readonly ok: true;
+    readonly accepted: true;
+    readonly runId: string;
 } | {
     readonly ok: false;
     readonly runId?: string;

package/lib/types/run-shell.js

@@ -0,0 +1,69 @@
+import { writeMergeReport } from "./report.js";
+function emptyDraft(reason) {
+    return {
+        stopReason: 'failed',
+        scope: { candidatePairs: 0, queueBefore: { verify: 0, pending: 0, fuse: 0, skipped: 0 } },
+        pairs: [],
+        totals: { merged: 0, kept: 0, pending: 0, failed: 0 },
+        notes: [reason],
+    };
+}
+export async function withMergeRun(options) {
+    const handle = await options.registry.begin('merge', {
+        command: options.command,
+        mergeStatus: 'running',
+        ...(options.total === undefined ? {} : { total: options.total }),
+    });
+    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 });
+    const finish = async () => {
+        let draft;
+        try {
+            draft = await options.body({ runId: handle.id, startedAt, signal: handle.signal, stage });
+        }
+        catch (error) {
+            draft = emptyDraft('run body failed: ' + (error instanceof Error ? error.message : String(error)));
+        }
+        const report = {
+            schemaVersion: 2,
+            runId: handle.id,
+            kind: 'merge',
+            command: options.command,
+            startedAt,
+            endedAt: options.now(),
+            stopReason: draft.stopReason,
+            approval: options.approval,
+            scope: draft.scope,
+            pairs: draft.pairs,
+            totals: draft.totals,
+            notes: draft.notes,
+            ...(draft.remaining === undefined ? {} : { remaining: draft.remaining }),
+        };
+        let reportPath;
+        try {
+            reportPath = await writeMergeReport(options.io, options.home, report);
+        }
+        catch (error) {
+            await options.registry.settle(handle.id, { state: 'failed', failure: 'report write failed: ' + (error instanceof Error ? error.message : String(error)) });
+            return { ok: false, runId: handle.id, message: 'report write failed' };
+        }
+        const runState = report.stopReason === 'completed'
+            ? 'succeeded'
+            : report.stopReason === 'cancelled'
+                ? 'cancelled'
+                : 'failed';
+        const awaiting = report.pairs.some(pair => pair.outcome === 'pending');
+        const mergeStatus = awaiting ? 'awaiting-approval' : runState;
+        await options.registry.settle(handle.id, { state: runState, resultRef: reportPath, mergeStatus, ...(runState === 'failed' ? { failure: 'merge ' + report.stopReason } : {}) });
+        if (report.stopReason === 'completed')
+            return { ok: true, runId: handle.id, reportPath, report };
+        return { ok: false, runId: handle.id, message: 'merge ' + report.stopReason, reportPath };
+    };
+    if (options.detached === true) {
+        void finish().catch(() => { });
+        return { ok: true, accepted: true, runId: handle.id };
+    }
+    return await finish();
+}
+//# sourceMappingURL=run-shell.js.map

package/lib/types/runtime.d.ts

@@ -28,6 +28,8 @@ export interface MergeRuntimeDeps {
     readonly allow: readonly string[];
     readonly cwd?: string;
     readonly timeoutMinutes: number;
+    /** Start scan/pair in the background and return the run id immediately. */
+    readonly detached?: boolean;
     readonly cards: (signal: AbortSignal) => Promise<readonly SkillCard[]>;
     /** Run-scoped engine screening. */
     readonly screeningForRun: (cards: readonly SkillCard[], runId: string, signal: AbortSignal) => Promise<readonly MergeCandidate[]>;

package/lib/types/runtime.js

@@ -0,0 +1,269 @@
+/**
+ * The merge command runtime: cards -> screening -> channel ports -> scan/approve.
+ * Plugin wiring supplies the channel, model and library; this module keeps the orchestration
+ * out of apply() and makes the mutating verbs testable with fakes.
+ */
+import { probeText } from '@lmzhen/dsh-evolution-core';
+import { canRetry, pairKey } from "./contracts.js";
+import { skippedPairKeys } from "./skipped.js";
+import { createReadOnlyMergeService } from "./merge-command.js";
+import { handleReadOnlyMergeCommand } from "./read-commands.js";
+import { runScanCommand } from "./scan-command.js";
+import { runApproveCommand } from "./approve-command.js";
+import { runResumeCommand } from "./resume-command.js";
+import { dropRow, loadMergeState, upsertRow } from "./state.js";
+import { transition } from "./coordinator.js";
+import { readCommitReceipt } from "./commit-receipt.js";
+import { undoMergeReceipt } from "./undo-merge.js";
+import { recordPair } from "./domain/pair-index-store.js";
+import { skillLibraryUndoPort } from "./adapters/undo.js";
+import { mergeDoctor } from "./doctor.js";
+import { createChannelScanPorts } from "./scan-ports.js";
+import { createNewChildRound2 } from "./new-child-authoring.js";
+import { skillLibraryPort } from "./adapters/library.js";
+export function createMergeRuntime(deps) {
+    const readOnly = createReadOnlyMergeService(deps.io, deps.home);
+    const timeout = deps.timeoutMinutes > 0 ? deps.timeoutMinutes : undefined;
+    const common = {
+        io: deps.io, home: deps.home, registry: deps.registry,
+        platformWrite: deps.platformWrite, now: deps.now,
+        ...(timeout === undefined ? {} : { timeoutMinutes: timeout }),
+    };
+    const stage = deps.stage;
+    const stageHooks = stage === undefined ? {} : {
+        onChild: (context) => { stage.bind(context); },
+        onChildClosed: (childId) => { stage.unbind(childId); },
+    };
+    return {
+        async execute(command, context) {
+            const parent = context?.parent ?? deps.parent;
+            const detached = deps.detached !== false;
+            if (command.verb === 'pair') {
+                const signal = new AbortController().signal;
+                const cards = await deps.cards(signal);
+                const pair = [{ a: command.a, b: command.b }];
+                let forced;
+                if (command.force === true) {
+                    const key = pairKey(command.a, command.b);
+                    forced = (await loadMergeState(deps.io, deps.home)).state.rows.find(row => row.pairKey === key);
+                    if (forced === undefined || forced.decision === undefined) {
+                        return { ok: false, text: 'pair --force 需要已有决策，找不到该 pair 的 decision: ' + key };
+                    }
+                }
+                const approval = command.force === true ? false : deps.params.mergeApproval;
+                const result = await runScanCommand({
+                    ...common,
+                    approval,
+                    ...(detached ? { detached: true } : {}),
+                    makePorts: (runId) => {
+                        const ports = createChannelScanPorts({
+                            io: deps.io, home: deps.home, runId, cards,
+                            screening: () => Promise.resolve(pair),
+                            channel: deps.channel, parent, allow: deps.allow,
+                            ...(deps.cwd === undefined ? {} : { cwd: deps.cwd }),
+                            timeoutMs: deps.params.mergePairTimeoutMinutes * 60_000,
+                            approval,
+                            commitPort: skillLibraryPort(deps.skills), now: deps.now,
+                            ...stageHooks,
+                        });
+                        return forced === undefined ? ports : { ...ports, round1: () => Promise.resolve({ kind: 'merge', decision: forced.decision }) };
+                    },
+                });
+                if (!result.ok)
+                    return { ok: false, text: result.message };
+                if ('accepted' in result)
+                    return { ok: true, text: 'merge pair 已启动：' + result.runId };
+                if (!('report' in result))
+                    return { ok: false, text: 'merge pair started without a report' };
+                return { ok: true, text: 'merge pair 完成：merged ' + String(result.report.totals.merged) + ' / pending ' + String(result.report.totals.pending) + ' / failed ' + String(result.report.totals.failed) };
+            }
+            if (command.verb === 'scan') {
+                const signal = new AbortController().signal;
+                const cards = await deps.cards(signal);
+                const loadedState = await loadMergeState(deps.io, deps.home);
+                const skipped = skippedPairKeys(loadedState.state.rows, deps.params.mergeSkippedTtlDays, deps.now());
+                const held = new Set(loadedState.state.rows.filter(row => row.queue === 'pending' || !canRetry(row)).map(row => row.pairKey));
+                const result = await runScanCommand({
+                    ...common,
+                    approval: deps.params.mergeApproval,
+                    ...(detached ? { detached: true } : {}),
+                    makePorts: runId => createChannelScanPorts({
+                        io: deps.io, home: deps.home, runId, cards,
+                        screening: async (turnSignal) => {
+                            const raw = await deps.screeningForRun(cards, runId, turnSignal);
+                            const filtered = raw.filter((candidate) => {
+                                const key = pairKey(candidate.a, candidate.b);
+                                return !skipped.has(key) && !held.has(key);
+                            });
+                            const candidatePairs = raw.candidatePairs;
+                            return candidatePairs === undefined ? filtered : Object.assign(filtered, { candidatePairs });
+                        },
+                        channel: deps.channel, parent, allow: deps.allow,
+                        ...(deps.cwd === undefined ? {} : { cwd: deps.cwd }),
+                        timeoutMs: deps.params.mergePairTimeoutMinutes * 60_000,
+                        approval: deps.params.mergeApproval,
+                        commitPort: skillLibraryPort(deps.skills), now: deps.now,
+                        ...stageHooks,
+                    }),
+                });
+                if (!result.ok)
+                    return { ok: false, text: result.message };
+                if ('accepted' in result)
+                    return { ok: true, text: 'merge scan 已启动：' + result.runId };
+                if (!('report' in result))
+                    return { ok: false, text: 'merge scan started without a report' };
+                return { ok: true, text: 'merge scan 完成：merged ' + String(result.report.totals.merged) + ' / pending ' + String(result.report.totals.pending) + ' / failed ' + String(result.report.totals.failed) };
+            }
+            if (command.verb === 'reject') {
+                const loaded = await loadMergeState(deps.io, deps.home);
+                const row = loaded.state.rows.find(item => item.id === command.id);
+                if (row === undefined)
+                    return { ok: false, text: 'merge row not found: ' + command.id };
+                const next = transition(row, { type: 'reject', at: new Date(deps.now()).toISOString() });
+                if (!next.ok || next.row === null)
+                    return { ok: false, text: 'merge row is not pending: ' + command.id };
+                await upsertRow(deps.io, deps.home, deps.now, next.row);
+                return { ok: true, text: '已拒绝合并：' + command.id };
+            }
+            if (command.verb === 'doctor') {
+                const rows = await mergeDoctor(deps.io, deps.home, deps.params.mergeModelsRoot);
+                return { ok: true, text: rows.map(row => row.key + ' [' + row.status + '] ' + row.label + '：' + row.detail).join('\n') };
+            }
+            if (command.verb === 'report' || command.verb === 'runs' || command.verb === 'cancel') {
+                const registry = deps.registry;
+                if (command.verb === 'runs') {
+                    const mergeRuns = registry.runs('merge');
+                    return { ok: true, text: mergeRuns.length === 0 ? 'merge runs: empty' : ['merge runs: ' + String(mergeRuns.length)].concat(mergeRuns.map(run => '- ' + run.id + ' [' + run.state + ']' + (run.resultRef === undefined ? '' : ' ' + run.resultRef))).join('\n') };
+                }
+                if (command.verb === 'cancel') {
+                    if (command.id !== undefined) {
+                        const cancelled = registry.cancel(command.id);
+                        return { ok: cancelled, text: cancelled ? '已请求取消 ' + command.id : '没有可取消的 run: ' + command.id };
+                    }
+                    const count = registry.cancelAll();
+                    return { ok: true, text: '已请求取消 ' + String(count) + ' 个运行' };
+                }
+                const run = command.id === undefined ? registry.runs('merge')[0] : registry.find(command.id);
+                if (run === undefined)
+                    return { ok: false, text: 'merge run not found: ' + (command.id ?? '(latest)') };
+                if (run.resultRef === undefined)
+                    return { ok: false, text: 'merge run has no report yet: ' + run.id };
+                const report = await probeText(deps.io, run.resultRef);
+                if (report.kind === 'unknown')
+                    return { ok: false, text: 'report is unreadable: ' + run.resultRef + '：' + report.reason };
+                return report.kind === 'absent'
+                    ? { ok: false, text: 'report is missing: ' + run.resultRef }
+                    : { ok: true, text: report.value.slice(0, 12000) };
+            }
+            if (command.verb === 'discard') {
+                const loaded = await loadMergeState(deps.io, deps.home);
+                const row = loaded.state.rows.find(item => item.id === command.id);
+                if (row === undefined)
+                    return { ok: false, text: 'merge row not found: ' + command.id };
+                if (row.state !== 'pending' && row.state !== 'approved' && row.state !== 'fuse')
+                    return { ok: false, text: 'merge row is not discardable: ' + command.id };
+                await dropRow(deps.io, deps.home, deps.now, row.id);
+                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 { ok: false, text: 'merge run has no commit receipt: ' + command.run };
+                if (receipt.target !== command.target)
+                    return { ok: false, text: 'receipt target is ' + receipt.target + ', not ' + command.target };
+                const result = await undoMergeReceipt(receipt, skillLibraryUndoPort(deps.skills));
+                if (result.ok && receipt.pairKey !== undefined) {
+                    await recordPair(deps.io, deps.home, { pairKey: receipt.pairKey, runId: receipt.parentRunId ?? receipt.runId, result: 'undone', target: receipt.target });
+                }
+                return { ok: result.ok, text: result.message };
+            }
+            if (command.verb === 'skipped' && command.restore !== undefined) {
+                const loaded = await loadMergeState(deps.io, deps.home);
+                const row = loaded.state.rows.find(item => item.id === command.restore);
+                if (row === undefined || row.state !== 'skipped')
+                    return { ok: false, text: 'skipped row not found: ' + command.restore };
+                await dropRow(deps.io, deps.home, deps.now, row.id);
+                return { ok: true, text: '已恢复参与筛选：' + row.id };
+            }
+            if (command.verb === 'resume') {
+                if (command.clear !== undefined) {
+                    const cleared = (await loadMergeState(deps.io, deps.home)).state.rows.find(item => item.id === command.clear);
+                    if (cleared === undefined)
+                        return { ok: false, text: 'merge row not found: ' + command.clear };
+                    await dropRow(deps.io, deps.home, deps.now, cleared.id);
+                    return { ok: true, text: '已清除合并行：' + cleared.id };
+                }
+                const loaded = await loadMergeState(deps.io, deps.home);
+                const row = command.id === undefined
+                    ? loaded.state.rows.find(item => item.state === 'fuse' || item.state === 'verify' || (command.retry === true && item.state === 'approved'))
+                    : loaded.state.rows.find(item => item.id === command.id);
+                if (row === undefined)
+                    return { ok: false, text: 'merge row not found: ' + (command.id ?? '(auto)') };
+                const signal = new AbortController().signal;
+                const cards = await deps.cards(signal);
+                const pair = () => Promise.resolve([{ a: row.a, b: row.b }]);
+                const failed = (stage, code, message) => Promise.resolve({
+                    kind: 'failed',
+                    failure: { stage, code, message, retryable: false, retryFrom: 'none' },
+                });
+                const basePorts = {
+                    screening: pair,
+                    round1: () => failed('decide', 'resume-needs-ports', 'verify resume needs makePorts'),
+                    round2: () => failed('author', 'resume-needs-child', 'fuse resume needs a new child'),
+                };
+                const result = await runResumeCommand({
+                    ...common, rowId: row.id, ports: basePorts,
+                    makePorts: runId => createChannelScanPorts({
+                        io: deps.io, home: deps.home, runId, cards, screening: pair,
+                        channel: deps.channel, parent, allow: deps.allow,
+                        ...(deps.cwd === undefined ? {} : { cwd: deps.cwd }),
+                        timeoutMs: deps.params.mergePairTimeoutMinutes * 60_000,
+                        approval: deps.params.mergeApproval, commitPort: skillLibraryPort(deps.skills), now: deps.now,
+                    }),
+                    round2WithRun: createNewChildRound2({
+                        io: deps.io, home: deps.home, cards, channel: deps.channel, parent,
+                        allow: deps.allow, ...(deps.cwd === undefined ? {} : { cwd: deps.cwd }),
+                        timeoutMs: deps.params.mergePairTimeoutMinutes * 60_000,
+                        commitPort: skillLibraryPort(deps.skills), now: deps.now,
+                        ...stageHooks,
+                    }),
+                });
+                if (!result.ok)
+                    return { ok: false, text: result.message };
+                if ('accepted' in result)
+                    return { ok: true, text: 'merge resume 已启动：' + result.runId };
+                if (!('report' in result))
+                    return { ok: false, text: 'merge resume started without a report' };
+                return { ok: true, text: 'merge resume 完成：merged ' + String(result.report.totals.merged) };
+            }
+            if (command.verb === 'approve') {
+                const signal = new AbortController().signal;
+                const cards = await deps.cards(signal);
+                const result = await runApproveCommand({
+                    ...common,
+                    rowId: command.id,
+                    ports: {
+                        round2: createNewChildRound2({
+                            io: deps.io, home: deps.home, cards, channel: deps.channel, parent,
+                            allow: deps.allow, ...(deps.cwd === undefined ? {} : { cwd: deps.cwd }),
+                            timeoutMs: deps.params.mergePairTimeoutMinutes * 60_000,
+                            commitPort: skillLibraryPort(deps.skills), now: deps.now,
+                        }),
+                    },
+                });
+                if (!result.ok)
+                    return { ok: false, text: result.message };
+                if ('accepted' in result)
+                    return { ok: true, text: 'merge approve 已启动：' + result.runId };
+                if (!('report' in result))
+                    return { ok: false, text: 'merge approve started without a report' };
+                return { ok: true, text: 'merge approve 完成：merged ' + String(result.report.totals.merged) };
+            }
+            const text = await handleReadOnlyMergeCommand(command, deps.io, deps.home);
+            if (text !== null)
+                return { ok: true, text };
+            return readOnly.execute(command);
+        },
+    };
+}
+//# sourceMappingURL=runtime.js.map

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

@@ -16,6 +16,7 @@ export interface RunScanCommandOptions {
     readonly platformWrite: boolean;
     readonly timeoutMinutes?: number;
     readonly now: () => number;
+    readonly detached?: boolean;
 }
 export declare function runScanCommand(options: RunScanCommandOptions): Promise<WithMergeRunResult>;
 //# sourceMappingURL=scan-command.d.ts.map

package/lib/types/scan-command.js

@@ -0,0 +1,30 @@
+import { runScan } from "./scan-run.js";
+import { withMergeRun } from "./run-shell.js";
+export async function runScanCommand(options) {
+    return await withMergeRun({
+        io: options.io,
+        home: options.home,
+        registry: options.registry,
+        command: 'scan',
+        approval: { platformWrite: options.platformWrite, mergeApproval: options.approval },
+        now: options.now,
+        ...(options.detached === undefined ? {} : { detached: options.detached }),
+        async body(ctx) {
+            const ports = options.makePorts === undefined ? options.ports : options.makePorts(ctx.runId);
+            if (ports === undefined)
+                throw new Error('scan requires ports or makePorts');
+            return await runScan({
+                io: options.io,
+                home: options.home,
+                now: options.now,
+                signal: ctx.signal,
+                approval: options.approval,
+                ports,
+                stage: ctx.stage,
+                startedAt: ctx.startedAt,
+                ...(options.timeoutMinutes === undefined ? {} : { timeoutMinutes: options.timeoutMinutes }),
+            });
+        },
+    });
+}
+//# sourceMappingURL=scan-command.js.map

package/lib/types/scan-ports.js

@@ -0,0 +1,93 @@
+import { pairKey } from "./contracts.js";
+import { runRound1OverChannel } from "./channel-port.js";
+import { runAuthoring } from "./authoring-flow.js";
+import { dropStaging, ensureStaging, stageKeyOf, stagingRoot } from "./staging.js";
+export function createChannelScanPorts(options) {
+    const sessions = new Map();
+    return {
+        screening: options.screening,
+        async round1(candidate, signal) {
+            const stageKey = stageKeyOf(options.runId, pairKey(candidate.a, candidate.b));
+            const staged = await ensureStaging(options.io, options.home, {
+                runId: stageKey,
+                target: candidate.a + '-' + candidate.b,
+                sources: options.cards
+                    .filter(card => card.name === candidate.a || card.name === candidate.b)
+                    .map(card => ({ name: card.name, body: card.body, files: card.files ?? [] })),
+                promptVersion: 'merge-b/v1',
+                ttlDays: 7,
+                now: options.now,
+            });
+            if (!staged.ok)
+                return { kind: 'failed', failure: { stage: 'decide', code: 'staging-create', message: staged.message, retryable: true, retryFrom: 'agent1' } };
+            const result = await runRound1OverChannel({
+                channel: options.channel,
+                parent: options.parent,
+                cards: options.cards,
+                allow: options.allow,
+                cwd: stagingRoot(options.home, stageKey),
+                timeoutMs: options.timeoutMs,
+                onChildOpened: childId => options.onChild?.({ runId: stageKey, childId, expectedChildId: childId, phase: 'decide' }),
+            }, candidate, signal);
+            if (result.outcome.kind !== 'merge') {
+                await dropStaging(options.io, options.home, stageKey);
+            }
+            else {
+                if (options.approval)
+                    await result.dispose();
+                else {
+                    sessions.set(pairKey(candidate.a, candidate.b), { result, stageKey });
+                    if (result.childId !== undefined) {
+                        options.onChild?.({ runId: stageKey, childId: result.childId, expectedChildId: result.childId, phase: 'author' });
+                    }
+                }
+            }
+            return result.outcome.kind === 'merge'
+                ? { ...result.outcome, stagingRef: stageKey, stagingExpiresAt: options.now() + 7 * 86_400_000 }
+                : result.outcome;
+        },
+        async round2(row, decision, signal) {
+            const key = pairKey(row.a, row.b);
+            const entry = sessions.get(key);
+            if (entry === undefined) {
+                return { kind: 'failed', failure: { stage: 'author', code: 'no-session', message: 'no same-child round2 session; approve must open a new child', retryable: false, retryFrom: 'none' } };
+            }
+            sessions.delete(key);
+            try {
+                const authored = await runAuthoring({
+                    io: options.io,
+                    home: options.home,
+                    runId: options.runId,
+                    stageKey: entry.stageKey,
+                    reuseStaging: true,
+                    target: decision.target,
+                    mode: decision.mode,
+                    cards: options.cards,
+                    commitPort: options.commitPort,
+                    now: options.now,
+                    summary: 'merge ' + row.a + ' + ' + row.b,
+                    author: async () => {
+                        await entry.result.author?.(row, decision, signal);
+                        return 'authored';
+                    },
+                });
+                if (!authored.ok) {
+                    return { kind: 'failed', failure: { stage: 'author', code: 'authoring-failed', message: authored.message, retryable: true, retryFrom: 'agent2' } };
+                }
+                const receipt = authored.commit.receipt;
+                return {
+                    kind: 'merged',
+                    ...(receipt?.unitId === undefined ? {} : { unitId: receipt.unitId }),
+                    archived: receipt?.archived ?? [],
+                    target: { requested: decision.target, actual: authored.commit.plan.target, created: receipt?.create ?? false },
+                };
+            }
+            finally {
+                await entry.result.dispose();
+                if (entry.result.childId !== undefined)
+                    options.onChildClosed?.(entry.result.childId);
+            }
+        },
+    };
+}
+//# sourceMappingURL=scan-ports.js.map

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

@@ -11,6 +11,8 @@ export interface ScanRound1Outcome {
     readonly failure?: MergeFailure;
     readonly stagingRef?: string;
     readonly stagingExpiresAt?: number;
+    readonly sourceRevision?: string;
+    readonly targetRevision?: string;
 }
 export interface ScanRound2Outcome {
     readonly kind: 'merged' | 'failed';