@lmzhen/dsh-evolution-merge 0.30.18 → 0.30.20

package/lib/types/facts.js

@@ -1,5 +1,6 @@
-import { loadMergeState } from "./state.js";
 import { MERGE_COMMAND_SURFACE } from "./command-surface.js";
+import { readMergeSnapshot } from "./domain/merge-snapshot.js";
+import { buildFacts as buildSnapshotFacts } from "./surface/merge-view.js";
 const queueOf = (row) => row.state === 'approved' ? 'fuse' : row.queue;
 const isExpired = (row) => row.expired !== undefined;
 export function countsOf(rows) {
@@ -14,8 +15,9 @@ export function countsOf(rows) {
     }
     return { active, expired };
 }
-export function toRunView(record, readAt) {
-    const state = (record.mergeStatus ?? record.state);
+export function toRunView(record, readAt, meta = null) {
+    const state = record.state;
+    void meta;
     return {
         wireVersion: 1,
         readAt,
@@ -28,7 +30,6 @@ export function toRunView(record, readAt) {
         ...(record.endedAt === undefined ? {} : { endedAt: record.endedAt }),
         ...(record.failure === undefined ? {} : { failure: { stage: 'settle', code: 'run-failed', retryable: false, retryFrom: 'none', detail: record.failure } }),
         ...(record.parentRunId === undefined ? {} : { parentRunId: record.parentRunId }),
-        ...(record.pairKey === undefined ? {} : { currentPairKey: record.pairKey }),
         actions: [
             { id: 'status', command: '/evolution merge status ' + record.id, confirm: false, enabled: true },
             { id: 'report', command: '/evolution merge report ' + record.id, confirm: false, enabled: record.resultRef !== undefined },
@@ -38,27 +39,23 @@ export function toRunView(record, readAt) {
 }
 /** GET projection: reads state + runs; never writes. */
 export async function readFacts(options) {
-    const loaded = await loadMergeState(options.io, options.home);
-    return buildFacts({
-        rows: loaded.state.rows,
-        runs: options.runs,
-        approval: options.approval,
-        readAt: options.readAt,
-        notes: loaded.ok ? [] : [loaded.note ?? 'state-unreadable'],
-    });
+    const snapshot = await readMergeSnapshot({ io: options.io, home: options.home, runs: options.runs, approval: options.approval, now: () => options.readAt });
+    if (snapshot.blocked !== undefined)
+        throw new Error(snapshot.blocked.code + ': ' + snapshot.blocked.message);
+    return buildSnapshotFacts(snapshot);
 }
 export function buildFacts(input) {
     const ordered = [...input.runs].sort((a, b) => b.startedAt - a.startedAt);
-    const active = ordered.find(run => (run.mergeStatus ?? run.state) === 'running');
-    const last = ordered.find(run => (run.mergeStatus ?? run.state) !== 'running');
+    const active = ordered.find(run => run.state === 'running');
+    const last = ordered.find(run => run.state !== 'running');
     const notes = input.notes ?? [];
     return {
         wireVersion: 1,
         readAt: input.readAt,
         approval: { mergeApproval: input.approval },
         counts: countsOf(input.rows),
-        active: active === undefined ? null : toRunView(active, input.readAt),
-        last: last === undefined ? null : toRunView(last, input.readAt),
+        active: active === undefined ? null : toRunView(active, input.readAt, input.runMeta?.get(active.id) ?? null),
+        last: last === undefined ? null : toRunView(last, input.readAt, input.runMeta?.get(last.id) ?? null),
         startCommands: { scan: '/evolution merge scan', pair: '/evolution merge pair <a> <b>' },
         fallback: MERGE_COMMAND_SURFACE.fallback,
         notes,

package/lib/types/index.d.ts

@@ -70,6 +70,8 @@ export * from './merge-tool.ts';
 export * from './commands.ts';
 export * from './scan-ports.ts';
 export * from './new-child-authoring.ts';
+export * from './domain/authoring-manifest.ts';
+export * from './domain/live-facts.ts';
 export * from './status.ts';
 export * from './skipped.ts';
 export * from './read-commands.ts';

package/lib/types/index.js

@@ -4,12 +4,29 @@ import { screen as engineScreen } from '@lmzhen/dsh-evolution-merge-engine';
 import { selectWithErrors } from "./adapters/select.js";
 import { createEngineScreening } from "./adapters/engine-screen.js";
 import { createEngineRunner } from "./adapters/model-runner.js";
-import { authorityFrom, createSubagentChannel, DEFAULT_SKILL_LIMITS, evolutionHome, evolutionIoAdapter, newRunRegistry, newSkillLibrary, policyStageLimits } from '@lmzhen/dsh-evolution-core';
+import { authorityFrom, createSubagentChannel, evolutionHome, evolutionIoAdapter, newRunRegistry, newSkillLibrary, reportsSweepLockTarget, sweepReports, transactIo } from '@lmzhen/dsh-evolution-core';
 import { registerHostRoutes } from '@lmzhen/dsh-evolution-core/http-routes';
-import { loadMergeState, transactRows } from "./state.js";
-import { cleanupExpiredStaging } from "./staging.js";
-import { recoverCommitJournals } from "./commit-recovery.js";
+import { loadMergeState } from "./state.js";
+import { pairLedger, normalizePairLedger } from "./domain/pair-ledger.js";
+import { legacyToV3 } from "./domain/row-v3-bridge.js";
+import { readV4Readiness } from "./domain/schema4.js";
+import { readMergeSnapshot } from "./domain/merge-snapshot.js";
 import { readCommitReceipts } from "./commit-receipt.js";
+import { UnitTransactions, skillLibraryUnitBackend } from '@lmzhen/dsh-evolution-core';
+import { targetClaimUnitPort } from "./unit-claim.js";
+import { resolveLimitsSnapshot } from "./domain/merge-limits.js";
+import { resolveEngineInput } from "./domain/engine-input.js";
+import { readReconcileReport, reconcileMergeState } from "./domain/reconcile.js";
+import { readRunMeta, writeRunMeta } from "./domain/run-coordinator.js";
+import { liveRowFactsOf } from "./domain/live-facts.js";
+import { filterSelection } from "./domain/selection-policy.js";
+import { cleanupStage } from "./domain/stage-aggregate.js";
+import { buildDoctorView } from "./surface/merge-view.js";
+import { mergeDoctorFact } from "./doctor.js";
+import { commandError, formatMergeError } from "./domain/errors.js";
+import { resolveBody } from "./surface/body.js";
+import { ensureMergeStateReady } from "./domain/state-bootstrap.js";
+import { recoverCommitUnits } from "./recovery-coordinator.js";
 import { pairKey, rowIdOf } from "./contracts.js";
 import { makeMergeRoutes } from "./merge-routes.js";
 import { createMergeCommand, runMergeCommand } from "./merge-command.js";
@@ -19,6 +36,21 @@ import { subagentChannelAdapter } from "./adapters/channel.js";
 import { StageToolRegistry } from "./stage-tool-registry.js";
 import { createMergeStageTool } from "./merge-tool.js";
 import { supersedeMergeRuns } from "./supersede.js";
+/**
+ * One library read used by both the runtime card port and the read-time convergence
+ * facts. Read-only: the snapshot/doctor consumers must never write.
+ * @param skills - the mounted skill store.
+ * @returns every live skill as a merge card (body + support files).
+ */
+async function readSkillCards(skills) {
+    const listed = await skills.list({ withContent: true });
+    return await Promise.all(listed.map(async (item) => {
+        const probe = await skills.listSupportFiles(item.name);
+        const paths = probe.kind === 'present' ? probe.value : [];
+        const files = await Promise.all(paths.map(async (path) => ({ path, content: await skills.readSupportFile(item.name, path) ?? '' })));
+        return { name: item.name, description: item.description, body: item.content ?? '', files, protectedBy: item.protectedBy, protectionUnknown: item.protectionUnknown, managed: item.managed };
+    }));
+}
 /** E3 knobs are volatile (user layer); the E2 pair timeout is deployment-only. */
 export const Config = z.object({
     mergeApproval: z.boolean().default(false).volatile(),
@@ -84,6 +116,8 @@ export * from "./merge-tool.js";
 export * from "./commands.js";
 export * from "./scan-ports.js";
 export * from "./new-child-authoring.js";
+export * from "./domain/authoring-manifest.js";
+export * from "./domain/live-facts.js";
 export * from "./status.js";
 export * from "./skipped.js";
 export * from "./read-commands.js";
@@ -93,14 +127,26 @@ export * from "./params.js";
 export * from "./doctor.js";
 export * from "./supersede.js";
 export * from "./runtime.js";
+/** Not-yet-mounted command face: three lines so a script can read code/hint/next. */
+function formatUnreadyError() {
+    return formatMergeError(commandError('merge', 'merge-not-ready', 'evolutionIo 尚未挂载', '等待插件加载完成后重试；运行 /evolution doctor 查看挂载状态'));
+}
 export const inject = [];
 export function apply(ctx, rawConfig = {}) {
     configureMergePresentation(ctx);
-    const params = resolveMergeParams(rawConfig);
+    let params = resolveMergeParams(rawConfig);
     let mergeRun;
+    let source;
+    let doctorFact;
     const mergeService = {
         async run(rawInput, invocation) {
-            return mergeRun === undefined ? { ok: false, text: 'merge 未就绪：evolutionIo 尚未挂载' } : mergeRun(rawInput, invocation);
+            return mergeRun === undefined ? { ok: false, text: formatUnreadyError() } : mergeRun(rawInput, invocation);
+        },
+        /** Global-doctor consumer: merges buildDoctorView over the shared snapshot with the reconcile report. */
+        async doctorFact() {
+            if (doctorFact === undefined)
+                return { status: 'unknown', detail: '合并服务尚未完成挂载', remedy: '稍后重新运行 /evolution doctor' };
+            return await doctorFact();
         },
     };
     const mergeContext = ctx;
@@ -108,7 +154,6 @@ export function apply(ctx, rawConfig = {}) {
         ;
         mergeContext.provide('evolutionMerge', mergeService);
     }
-    let source;
     registerHostRoutes(ctx, audit => makeMergeRoutes({ getSource: () => source }, audit));
     ctx.inject(['commands', 'evolutionIo'], (scope) => {
         const registry = scope.get('evolutionIo');
@@ -116,7 +161,18 @@ export function apply(ctx, rawConfig = {}) {
             return;
         const io = evolutionIoAdapter(() => registry.provider());
         const home = evolutionHome();
-        void loadMergeState(io, home).then(loaded => cleanupExpiredStaging(io, home, Date.now(), new Set(loaded.state.rows.map(row => row.runId).filter((id) => id !== undefined)))).catch((error) => { ctx.logger.warn('merge staging cleanup failed: ' + (error instanceof Error ? error.message : String(error))); });
+        const ready = (async () => {
+            const v4 = await readV4Readiness(io, home);
+            if (v4.ok) {
+                const loaded = await loadMergeState(io, home);
+                return { ok: true, schema: 3, migrated: false, state: { schemaVersion: 3, rows: loaded.state.rows.map(legacyToV3).filter((row) => row !== null) }, quarantine: [], report: null };
+            }
+            const state = await ensureMergeStateReady(io, home);
+            if (!state.ok)
+                return v4.code === 'merge-state-forward-only' || v4.code === 'merge-state-needs-repair' ? { ok: false, code: v4.code, message: v4.message } : state;
+            const normalized = await normalizePairLedger(io, home);
+            return normalized.ok ? state : { ok: false, code: 'merge-state-needs-repair', message: normalized.message ?? 'v4 normalize failed' };
+        })().catch(error => ({ ok: false, code: 'merge-state-migration-blocked', message: error instanceof Error ? error.message : String(error) }));
         const runs = newRunRegistry({ io, home, warn: (message) => { ctx.logger.warn(message); } });
         ctx.effect(() => {
             const host = ctx;
@@ -128,18 +184,56 @@ export function apply(ctx, rawConfig = {}) {
             });
         }, 'evolution-merge: restore supersede');
         const policySnapshot = ctx.get('evolutionPolicy');
+        const limitsSnapshot = resolveLimitsSnapshot(policySnapshot?.get?.());
+        const hostApproval = ctx.get('evolutionApproval');
+        const platformWrite = typeof hostApproval?.platformWrite === 'boolean' ? hostApproval.platformWrite : (params.platformWrite ?? false);
+        params = { ...params, limitsSnapshot, platformWrite };
         const skills = newSkillLibrary({
             io, ctx, authority: authorityFrom({ origin: 'subagent' }),
-            limits: { ...DEFAULT_SKILL_LIMITS, ...policyStageLimits(policySnapshot?.get?.()) },
+            limits: limitsSnapshot.skillLimits,
         });
-        void runs.load().then(() => recoverCommitJournals(io, home, Date.now(), (runId) => {
-            const run = runs.find(runId);
-            return run !== undefined && run.state === 'running';
-        })).then((reports) => { if (reports.length > 0)
-            ctx.logger.info('merge commit recovery: ' + reports.map(report => report.runId + '=' + report.action).join(', ')); }).catch((error) => { ctx.logger.warn('merge commit recovery failed: ' + (error instanceof Error ? error.message : String(error))); });
+        void ready.then(value => {
+            if (!value.ok) {
+                ctx.logger.warn('merge state is not ready: ' + value.code + ': ' + value.message);
+                return;
+            }
+            const unit = new UnitTransactions({ io, home, backend: skillLibraryUnitBackend(skills), claim: targetClaimUnitPort(io, home, () => Date.now()), now: () => Date.now() });
+            const cards = async () => await readSkillCards(skills);
+            void (async () => {
+                // NFR-05: load the shared run index BEFORE recovery. Recovery settles through the
+                // registry's controlled orphan upgrade (settleRecovered), which is the only way a
+                // committed unit can turn an orphan-stamped run back into succeeded.
+                const loaded = await runs.load();
+                if (!loaded.ok)
+                    ctx.logger.warn('merge run index: ' + (loaded.note ?? 'unreadable'));
+                const reports = await recoverCommitUnits({ io, home, unit, now: () => Date.now(), isActive: () => false, runs });
+                if (reports.length > 0)
+                    ctx.logger.info('merge unit recovery: ' + reports.map(report => report.runId + '/' + report.unitId + '=' + report.action).join(', '));
+                const v4 = await readV4Readiness(io, home);
+                if (v4.ok) {
+                    const cleanup = await cleanupStage(io, home, Date.now(), new Map(v4.state.rows.map(row => [row.id, { state: row.state }])));
+                    if (cleanup.expired.length > 0 || cleanup.removed.length > 0)
+                        ctx.logger.info('merge stage cleanup: ' + String(cleanup.expired.length) + ' expired, ' + String(cleanup.removed.length) + ' removed, ' + String(cleanup.orphans.length) + ' orphan(s)');
+                    // Reconcile is the one row-state convergence writer; startup simply invokes it.
+                    // A live library is only supplied when it is non-empty (an empty/unreadable list
+                    // must never authorize source-gone removal).
+                    const pending = v4.state.rows.some(row => row.state === 'pending');
+                    const library = pending ? await cards().catch(() => []) : [];
+                    const live = library.length === 0 ? undefined : liveRowFactsOf(library);
+                    const reconciled = await reconcileMergeState({ io, home, now: () => Date.now(), ttlDays: params.mergeSkippedTtlDays, ...(live === undefined ? {} : { live }) });
+                    if (reconciled.actions.length > 0)
+                        ctx.logger?.info?.('merge reconcile: ' + String(reconciled.actions.length) + ' action(s)');
+                    await transactIo(io, reportsSweepLockTarget(), async () => {
+                        await sweepReports({ io, dir: join(home, 'reports'), buckets: [{ prefix: 'merge-', keep: 20 }], owner: 'evolution-merge', warn: message => ctx.logger.warn(message) });
+                        return null;
+                    });
+                }
+            })().catch((error) => { ctx.logger.warn('merge recovery failed: ' + (error instanceof Error ? error.message : String(error))); });
+        }).catch((error) => { ctx.logger.warn('merge state readiness failed: ' + (error instanceof Error ? error.message : String(error))); });
         const channel = subagentChannelAdapter(createSubagentChannel(ctx));
         const stage = new StageToolRegistry();
-        const engineConfig = engineConfigFromRoot(params.mergeModelsRoot);
+        const engineInput = resolveEngineInput({ modelsRoot: params.mergeModelsRoot });
+        const engineConfig = engineConfigFromRoot(engineInput.modelsRoot);
         const llm = ctx.get('llm');
         const defaultModel = ctx.get('agentDefaultModel');
         const runner = llm === undefined || defaultModel === undefined
@@ -150,63 +244,80 @@ export function apply(ctx, rawConfig = {}) {
             home,
             engine: { screen: engineScreen },
             select: selectWithErrors,
-            cfg: { ...engineConfig, judge: 'deepseek' },
+            cfg: { ...engineConfig, judge: runner === undefined ? 'stub' : 'deepseek', ...(engineInput.maxTokens === 0 ? {} : { maxTokens: engineInput.maxTokens }), ...(engineInput.timeoutMs === 0 ? {} : { timeoutMs: engineInput.timeoutMs }) },
             ...(runner === undefined ? {} : { runner }),
-            async onSelection(selection) {
-                const loaded = await loadMergeState(io, home);
-                const at = new Date().toISOString();
-                for (const skipped of selection.skipped) {
-                    if (loaded.state.rows.some(row => row.pairKey === skipped.pairKey))
-                        continue;
-                    const key = pairKey(skipped.a, skipped.b);
-                    await transactRows(io, home, tx => tx.createSkipped({
-                        id: rowIdOf(key), pairKey: key, a: skipped.a, b: skipped.b, version: 0,
-                        createdAt: at, updatedAt: at, origin: 'agent',
-                        state: 'skipped', reason: skipped.reason ?? 'gate-keep', attempts: 0,
-                    }).ok);
-                }
-            },
-        });
-        source = {
-            rows() { return loadMergeState(io, home).then(loaded => loaded.state.rows); },
-            run(id) { return Promise.resolve(runs.runs().find(record => record.id === id)); },
-            runs() { return Promise.resolve(runs.runs()); },
-            async body(id, side) {
-                const row = (await loadMergeState(io, home)).state.rows.find(item => item.id === id);
-                if (row === undefined)
-                    return null;
-                return await skills.read(side === 'a' ? row.a : row.b);
-            },
-            async history() {
-                const receipts = await readCommitReceipts(io, home);
-                const items = new Map();
-                for (const receipt of receipts) {
-                    for (const source of receipt.sources) {
-                        const key = source + ':' + receipt.runId;
-                        if (items.has(key))
+            async onSelection(selection, _runId, cards) {
+                try {
+                    const byName = new Map(cards.map(card => [card.name, card]));
+                    const filtered = filterSelection(selection, name => byName.get(name)?.managed === true, name => { const card = byName.get(name); return card?.protectionUnknown === true || card?.protectedBy != null; });
+                    const loaded = await loadMergeState(io, home);
+                    const at = new Date().toISOString();
+                    for (const skipped of filtered.skipped) {
+                        if (loaded.state.rows.some(row => row.pairKey === skipped.pairKey))
                             continue;
-                        items.set(key, { name: source, kind: 'merged', reason: 'Merged into ' + receipt.target, lastVersion: 1, archivedAt: new Date(receipt.at).toISOString(), sourceRunId: receipt.runId });
+                        const key = pairKey(skipped.a, skipped.b);
+                        await pairLedger(io, home).transact(tx => tx.createSkipped({
+                            id: rowIdOf(key), pairKey: key, a: skipped.a, b: skipped.b, version: 0,
+                            createdAt: at, updatedAt: at, origin: 'agent',
+                            state: 'skipped', reason: skipped.reason ?? 'gate-keep', attempts: 0,
+                        }).ok);
                     }
                 }
-                const archived = await skills.archivedNames?.() ?? [];
-                const seen = new Set([...items.values()].map(item => item.name));
-                for (const name of archived) {
-                    if (seen.has(name))
-                        continue;
-                    items.set('archived:' + name, { name, kind: 'other', reason: 'archived', lastVersion: 1, archivedAt: new Date(Date.now()).toISOString() });
+                catch (error) {
+                    const meta = await readRunMeta(io, home, _runId);
+                    if (meta !== null)
+                        await writeRunMeta(io, home, { ...meta, degraded: true, updatedAt: new Date().toISOString() });
+                    ctx.logger.warn('merge selection reportOnly write failed (degraded): ' + (error instanceof Error ? error.message : String(error)));
                 }
-                return [...items.values()];
             },
+        });
+        source = {
+            async snapshot() {
+                return await readMergeSnapshot({ io, home, runs: runs.runs('merge'), approval: params.mergeApproval, live: async () => liveRowFactsOf(await readSkillCards(skills)), history: async () => {
+                        const items = new Map();
+                        const receipts = [...await readCommitReceipts(io, home)].sort((a, b) => a.at - b.at);
+                        const generationOf = new Map(receipts.map((receipt, index) => [receipt.runId, index + 1]));
+                        for (const receipt of receipts)
+                            for (const name of receipt.sources)
+                                items.set(name, { name, kind: 'merged', reason: '已合并进「' + receipt.target + '」，最后一版保留可查。', reasonCode: 'merged', lastVersion: 1, archivedAt: receipt.at, sourceRunId: receipt.runId, runId: receipt.runId, absorbedInto: receipt.target, generation: generationOf.get(receipt.runId) ?? 1 });
+                        const archived = await skills.archivedNames?.() ?? [];
+                        const reasonOf = skills.readArchiveReason;
+                        for (const name of archived) {
+                            if (items.has(name))
+                                continue;
+                            const rawReason = reasonOf === undefined ? null : await reasonOf.call(skills, name).catch(() => null);
+                            const lower = (rawReason ?? '').toLowerCase();
+                            const kind = lower.includes('split') ? 'split' : lower.includes('delet') || lower.includes('remove') ? 'deleted' : 'other';
+                            items.set(name, { name, kind, reason: rawReason ?? '技能已归档，最后一版保留可查。', reasonCode: kind === 'other' ? 'archived' : kind, lastVersion: 1, archivedAt: Date.now() });
+                        }
+                        const out = [];
+                        for (const item of items.values()) {
+                            const versions = await skills.listVersions(item.name).catch(() => []);
+                            const lastVersion = versions.at(-1)?.v ?? item.lastVersion;
+                            out.push({ ...item, lastVersion, generation: item.generation ?? lastVersion });
+                        }
+                        return out;
+                    } });
+            },
+            async bodyRef(ref) { return await resolveBody(io, home, ref, async () => ref.side === 'archive' ? await skills.readArchived(ref.name) : await skills.read(ref.name)); },
             approval() { return params.mergeApproval; },
+            readiness() { return ready; },
             commands() {
-                return ['merge scan', 'merge doctor', 'merge status', 'merge pending', 'merge skipped', 'merge report', 'merge runs', 'merge cancel'];
+                return ['merge scan', 'merge doctor', 'merge status', 'merge pending', 'merge skipped', 'merge report', 'merge runs', 'merge cancel', 'merge reconcile'];
             },
         };
+        doctorFact = async () => {
+            const current = source;
+            if (current?.snapshot === undefined)
+                return { status: 'unknown', detail: '合并快照来源尚未挂载', remedy: '稍后重新运行 /evolution doctor' };
+            const view = buildDoctorView(await current.snapshot());
+            return mergeDoctorFact(view, await readReconcileReport(io, home));
+        };
         const commands = scope.get('commands');
         if (commands === undefined)
             return;
         const runtime = createMergeRuntime({
-            io, home, registry: runs, skills, now: () => Date.now(), params, platformWrite: true,
+            io, home, registry: runs, skills, now: () => Date.now(), params, platformWrite,
             channel, parent: undefined, allow: ['merge_stage'], timeoutMinutes: params.mergeRunTimeoutMinutes,
             isBlocked: async (name) => {
                 const curator = ctx.get('evolutionCurator');
@@ -217,15 +328,9 @@ export function apply(ctx, rawConfig = {}) {
                 return run !== undefined && run.state === 'running';
             },
             async cards(signal) {
-                const listed = await skills.list({ withContent: true });
                 if (signal.aborted)
                     return [];
-                return Promise.all(listed.map(async (item) => {
-                    const probe = await skills.listSupportFiles(item.name);
-                    const paths = probe.kind === 'present' ? probe.value : [];
-                    const files = await Promise.all(paths.map(async (path) => ({ path, content: await skills.readSupportFile(item.name, path) ?? '' })));
-                    return { name: item.name, description: item.description, body: item.content ?? '', files, protectedBy: item.protectedBy, protectionUnknown: item.protectionUnknown, managed: item.managed };
-                }));
+                return await readSkillCards(skills);
             },
             screeningForRun: engineScreening,
             stage: {
@@ -233,14 +338,22 @@ export function apply(ctx, rawConfig = {}) {
                 unbind: (childId) => { stage.unbind(childId); },
             },
         });
-        mergeRun = (rawInput, invocation) => runMergeCommand(runtime, rawInput, invocation);
+        mergeRun = async (rawInput, invocation) => {
+            const state = await ready;
+            // These verbs answer usefully on a blocked state; reconcile reports the block without writing.
+            const allowedWhenBlocked = /(?:^|\s)(doctor|status|pending|skipped|report|runs|reconcile)(?:\s|$)/.test(rawInput);
+            if (!state.ok && !allowedWhenBlocked)
+                return { ok: false, text: formatMergeError(commandError('merge', state.code, state.message, '先修复合并状态（/evolution merge doctor），再重试')) };
+            return runMergeCommand(runtime, rawInput, invocation);
+        };
         const command = createMergeCommand(runtime);
-        scope.effect(() => commands.register(command), 'evolution-merge: command');
+        if (command !== null)
+            scope.effect(() => commands.register(command), 'evolution-merge: command');
         ctx.inject(['tools'], (toolScope) => {
             const tools = toolScope.get('tools');
             if (tools === undefined)
                 return;
-            const tool = createMergeStageTool(io, home, exec => stage.resolve(exec));
+            const tool = createMergeStageTool(io, home, exec => stage.resolve(exec), exec => stage.snapshot(exec));
             toolScope.effect(() => tools.register(tool), 'evolution-merge: merge_stage');
         });
         scope.effect(() => () => { runs.cancelAll(); }, 'evolution-merge: runs');

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

@@ -11,6 +11,8 @@ export interface MergeCommandResult {
 export interface MergeCommandContext {
     /** The invoking agent, when a command (not a route) initiated the run. */
     readonly parent?: unknown;
+    /** True when the invocation carried no agent at all (the E-305 shape). */
+    readonly agentless?: boolean;
 }
 export interface MergeCommandService {
     execute(command: MergeCliCommand, context?: MergeCommandContext): Promise<MergeCommandResult>;
@@ -35,5 +37,5 @@ export declare function createReadOnlyMergeService(io: EvolutionIoLike, home: st
 export declare function runMergeCommand(service: MergeCommandService, rawInput: string, invocation?: {
     readonly agent?: unknown;
 }): Promise<MergeCommandResult>;
-export declare function createMergeCommand(service: MergeCommandService): MergeCommandDefinitionLike;
+export declare function createMergeCommand(service: MergeCommandService, version?: string): MergeCommandDefinitionLike | null;
 //# sourceMappingURL=merge-command.d.ts.map

package/lib/types/merge-command.js

@@ -1,12 +1,14 @@
 import { parseMergeCommand, mergeUsage } from "./commands.js";
+import { aliasRegistration } from '@lmzhen/dsh-evolution-commands';
+import { MERGE_ALIAS_DEF, MERGE_PACKAGE_VERSION } from "./command-defs.js";
 import { handleReadOnlyMergeCommand } from "./read-commands.js";
-import { formatMergeError } from "./domain/errors.js";
+import { commandError, formatMergeError } from "./domain/errors.js";
 export function createReadOnlyMergeService(io, home) {
     return {
         async execute(command) {
             const text = await handleReadOnlyMergeCommand(command, io, home);
             return text === null
-                ? { ok: false, text: 'merge ' + command.verb + ' 需要运行引擎（当前只挂载了只读命令）' }
+                ? { ok: false, text: formatMergeError(commandError(command.verb, 'merge-engine-required', '该命令需要合并运行时（当前只挂载了只读命令）', '安装 evolution-merge 完整行后重试；只读队列见 /evolution merge status')) }
                 : { ok: true, text };
         },
     };
@@ -23,16 +25,18 @@ export async function runMergeCommand(service, rawInput, invocation) {
     if (parsed.help === true)
         return { ok: true, text: mergeUsage() };
     try {
-        return await service.execute(parsed.command, invocation?.agent === undefined ? {} : { parent: invocation.agent });
+        return await service.execute(parsed.command, invocation?.agent === undefined ? { agentless: true } : { parent: invocation.agent });
     }
     catch (error) {
-        return { ok: false, text: formatMergeError({ kind: 'runtime', code: 'merge-command-failed', message: error instanceof Error ? error.message : String(error) }) };
+        return { ok: false, text: formatMergeError(commandError('command', 'merge-command-failed', error instanceof Error ? error.message : String(error), '重试；若持续失败，运行 /evolution merge doctor 查看状态')) };
     }
 }
-export function createMergeCommand(service) {
+export function createMergeCommand(service, version = MERGE_PACKAGE_VERSION) {
+    if (aliasRegistration(version, MERGE_ALIAS_DEF) === 'removed')
+        return null;
     return {
         name: 'merge',
-        description: '技能自动合并：扫描、待批准、重跑、报告与 undo（兼容别名；请用 /evolution merge）',
+        description: (aliasRegistration(version, MERGE_ALIAS_DEF) === 'deprecated' ? '已弃用，请用 /evolution merge。' : '') + '技能自动合并：扫描、待批准、重跑、报告与 undo（兼容别名；请用 /evolution merge）',
         input: { hint: mergeUsage() },
         async handler(invocation) {
             const result = await runMergeCommand(service, invocation.rawInput, invocation);

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

@@ -5,6 +5,8 @@
 import type { RunRecord } from '@lmzhen/dsh-evolution-core';
 import { type ConnectionFetchRouteLike, type DecisionAudit } from '@lmzhen/dsh-evolution-core/http-routes';
 import type { MergeRow } from './contracts.ts';
+import type { StateReadiness } from './domain/state-bootstrap.ts';
+import type { MergeSnapshot, BodyRef } from './domain/merge-snapshot.ts';
 export declare const MERGE_ROUTES: {
     view: `/api/dsh-evolution/${string}`;
     rows: `/api/dsh-evolution/${string}`;
@@ -20,13 +22,16 @@ export interface MergeHistoryItem {
     readonly sourceRunId?: string;
 }
 export interface MergeRouteSource {
-    rows(): Promise<readonly MergeRow[]>;
-    run(id: string): Promise<RunRecord | undefined>;
-    runs(cursor?: string, limit?: number): Promise<readonly RunRecord[]>;
-    body(id: string, side: 'a' | 'b'): Promise<string | null>;
-    history(): Promise<readonly MergeHistoryItem[]>;
+    snapshot?(): Promise<MergeSnapshot>;
+    bodyRef?(ref: BodyRef): Promise<string | null>;
+    rows?(): Promise<readonly MergeRow[]>;
+    run?(id: string): Promise<RunRecord | undefined>;
+    runs?(cursor?: string, limit?: number): Promise<readonly RunRecord[]>;
+    body?(id: string, side: 'a' | 'b'): Promise<string | null>;
+    history?(): Promise<readonly MergeHistoryItem[]>;
     commands(): readonly string[];
     approval?(): boolean;
+    readiness?(): Promise<StateReadiness>;
 }
 export declare function makeMergeRoutes(deps: {
     getSource: () => MergeRouteSource | undefined;