@lmzhen/dsh-evolution-merge 0.30.18 → 0.30.20

package/lib/types/adapters/channel.d.ts

@@ -8,6 +8,7 @@ interface PlatformTurn {
     readonly childId: unknown;
     readonly stopReason: string;
     readonly text: string;
+    readonly usage?: unknown;
 }
 type PlatformOutcome = {
     readonly kind: 'ok';

package/lib/types/adapters/channel.js

@@ -1,10 +1,24 @@
+function usageOf(value) {
+    if (value === null || typeof value !== 'object')
+        return undefined;
+    const raw = value;
+    const num = (input) => typeof input === 'number' && Number.isFinite(input) ? input : undefined;
+    const inputTokens = num(raw.inputTokens);
+    const outputTokens = num(raw.outputTokens);
+    const totalTokens = num(raw.totalTokens);
+    const costCny = num(raw.costCny);
+    if (inputTokens === undefined && outputTokens === undefined && totalTokens === undefined && costCny === undefined)
+        return undefined;
+    return { ...(inputTokens === undefined ? {} : { inputTokens }), ...(outputTokens === undefined ? {} : { outputTokens }), ...(totalTokens === undefined ? {} : { totalTokens }), ...(costCny === undefined ? {} : { costCny }) };
+}
 function convert(outcome) {
     if (outcome.kind !== 'ok')
         return outcome;
+    const usage = usageOf(outcome.turn.usage);
     return {
         kind: 'ok',
         childId: String(outcome.childId),
-        turn: { text: outcome.turn.text, stopReason: outcome.turn.stopReason },
+        turn: { text: outcome.turn.text, stopReason: outcome.turn.stopReason, ...(usage === undefined ? {} : { usage }) },
     };
 }
 export function subagentChannelAdapter(channel) {

package/lib/types/adapters/engine-screen.d.ts

@@ -47,7 +47,7 @@ export interface EngineScreeningDeps {
     readonly select: (report: Record<string, unknown>) => CandidateSelection;
     readonly cfg?: Record<string, unknown>;
     readonly runner?: (prompt: string, cfg?: Record<string, unknown>) => Promise<string>;
-    readonly onSelection?: (selection: CandidateSelection, runId: string) => Promise<void>;
+    readonly onSelection?: (selection: CandidateSelection, runId: string, cards: readonly SkillCard[]) => Promise<void>;
 }
 /** Write the exact card bodies as a support-free corpus snapshot and return its root. */
 export declare function snapshotCards(io: EvolutionIoLike, home: string, runId: string, cards: readonly SkillCard[]): Promise<string>;

package/lib/types/adapters/engine-screen.js

@@ -38,8 +38,11 @@ export function createEngineScreening(deps) {
         }
         const selection = deps.select(result.report);
         if (deps.onSelection !== undefined)
-            await deps.onSelection(selection, runId);
-        return Object.assign(selection.candidates.slice(), selection.candidatePairs === undefined ? {} : { candidatePairs: selection.candidatePairs });
+            await deps.onSelection(selection, runId, cards);
+        const degraded = selection.reportOnly
+            .filter(row => row.error === true)
+            .map(row => { const value = row; return 'gate error: ' + String(value.a ?? '?') + ' + ' + String(value.b ?? '?'); });
+        return Object.assign(selection.candidates.slice(), selection.candidatePairs === undefined ? {} : { candidatePairs: selection.candidatePairs }, degraded.length === 0 ? {} : { degraded }, selection.reportOnly.length === 0 ? {} : { reportOnly: selection.reportOnly });
     };
 }
 //# sourceMappingURL=engine-screen.js.map

package/lib/types/adapters/model-runner.d.ts

@@ -1,8 +1,3 @@
-/**
- * DeepSeek judge runner over the platform llm service. The engine calls
- * runner(prompt, cfg) and expects raw model text; the platform owns provider
- * selection, usage accounting and transport.
- */
 export interface ModelRoute {
     readonly provider: string;
     readonly model: string;

package/lib/types/adapters/model-runner.js

@@ -1,3 +1,9 @@
+/**
+ * DeepSeek judge runner over the platform llm service. The engine calls
+ * runner(prompt, cfg) and expects raw model text; the platform owns provider
+ * selection, usage accounting and transport.
+ */
+import { normalizeProviderKey } from "../domain/provider-key.js";
 function append(chunk, text) {
     if (chunk.type === 'text-delta' || chunk.type === 'text')
         return text + (chunk.text ?? '');
@@ -12,7 +18,7 @@ export function createEngineRunner(llm, route) {
         let text = '';
         if (llm.stream !== undefined) {
             for await (const chunk of llm.stream({
-                provider: selection.provider,
+                provider: normalizeProviderKey(selection.provider),
                 model: selection.model,
                 messages: [{ role: 'user', content: [{ type: 'text', text: prompt }] }],
                 temperature: 0,
@@ -22,7 +28,7 @@ export function createEngineRunner(llm, route) {
         }
         if (llm.prepareCall === undefined)
             throw new Error('llm service has neither stream nor prepareCall');
-        const call = await llm.prepareCall({ provider: selection.provider, model: selection.model, temperature: 0 });
+        const call = await llm.prepareCall({ provider: normalizeProviderKey(selection.provider), model: selection.model, temperature: 0 });
         for await (const chunk of call.stream({
             ...call.config,
             messages: [{ role: 'user', content: [{ type: 'text', text: prompt }] }],

package/lib/types/adapters/model.js

@@ -1,3 +1,4 @@
+import { normalizeProviderKey } from "../domain/provider-key.js";
 function append(chunk, text) {
     if (chunk.type === 'text-delta' || chunk.type === 'text')
         return text + (chunk.text ?? '');
@@ -13,7 +14,7 @@ export function createModelPort(llm, route) {
             let text = '';
             if (llm.stream !== undefined) {
                 for await (const chunk of llm.stream({
-                    provider: selection.provider,
+                    provider: normalizeProviderKey(selection.provider),
                     model: selection.model,
                     system: request.system,
                     messages: [{ role: 'user', content: [{ type: 'text', text: request.user }] }],

package/lib/types/adapters/select.js

@@ -1,5 +1,5 @@
 /** Host selector correction: engine selector does not route judge errors to candidates. */
-import { pairKeyOf, selectCandidates, toEngineCandidate } from '@lmzhen/dsh-evolution-merge-engine';
+import { pairKeyOf, selectCandidates } from '@lmzhen/dsh-evolution-merge-engine';
 export function selectWithErrors(report) {
     const base = selectCandidates(report);
     const doc = (report.reportDoc ?? report);
@@ -13,22 +13,26 @@ export function selectWithErrors(report) {
         if (a !== '' && b !== '')
             errors.add(pairKeyOf(a, b));
     }
-    const candidates = base.candidates.filter(candidate => !errors.has(pairKeyOf(candidate.a, candidate.b)));
-    const skipped = base.skipped.filter(item => !errors.has(item.pairKey));
+    const candidates = base.candidates.filter(candidate => !errors.has(pairKeyOf(candidate.a, candidate.b))).filter(candidate => {
+        const gate = candidate.gate;
+        return gate?.level === 'L2' || gate?.verdict === 1;
+    });
     const reportOnly = base.reportOnly.filter((row) => {
         const value = row;
         if (typeof value.a !== 'string' || typeof value.b !== 'string')
             return true;
         return !errors.has(pairKeyOf(value.a, value.b));
     });
+    for (const candidate of base.candidates) {
+        const level = candidate.gate?.level;
+        if (level !== 'L2')
+            reportOnly.push(candidate);
+    }
+    const skipped = base.skipped.filter(item => !errors.has(item.pairKey));
     for (const row of rows) {
         if (row.error !== true)
             continue;
-        const a = typeof row.a === 'string' ? row.a : '';
-        const b = typeof row.b === 'string' ? row.b : '';
-        if (a === '' || b === '')
-            continue;
-        candidates.push(toEngineCandidate(row, typeof row.reason === 'string' ? row.reason : 'judge-error'));
+        reportOnly.push(row);
     }
     return { ...base, candidates, skipped, reportOnly };
 }

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

@@ -2,11 +2,19 @@
  * approve command: one pending row is atomically taken to fuse, then a new run executes
  * round2 with the persisted decision. A second approve loses at approvePending (not-pending).
  */
-import type { EvolutionIoLike } from '@lmzhen/dsh-evolution-core';
+import { type EvolutionIoLike } from '@lmzhen/dsh-evolution-core';
 import type { MergeDecision, MergeRow } from './contracts.ts';
+import { type StageEntry } from './domain/stage-aggregate.ts';
 import type { MergeRegistryPort, WithMergeRunResult } from './run-shell.ts';
 import type { ScanRound2Outcome } from './scan-run.ts';
 export interface ApprovePorts {
+    stage?(row: MergeRow, decision: MergeDecision): Promise<{
+        readonly ok: true;
+        readonly entry: StageEntry;
+    } | {
+        readonly ok: false;
+        readonly message: string;
+    }>;
     round2(row: MergeRow, decision: MergeDecision, signal: AbortSignal, runId: string): Promise<ScanRound2Outcome>;
 }
 export interface RunApproveCommandOptions {
@@ -16,9 +24,12 @@ export interface RunApproveCommandOptions {
     readonly ports: ApprovePorts;
     readonly rowId: string;
     readonly platformWrite: boolean;
+    readonly parentRunId?: string;
     readonly detached?: boolean;
     readonly pairTimeoutMinutes?: number;
     readonly now: () => number;
+    /** The invocation carried no agent at all (E-305), as opposed to an agent with no parent run. */
+    readonly agentless?: boolean;
 }
 export declare function runApproveCommand(options: RunApproveCommandOptions): Promise<WithMergeRunResult>;
 //# sourceMappingURL=approve-command.d.ts.map

package/lib/types/approve-command.js

@@ -1,27 +1,59 @@
+/**
+ * approve command: one pending row is atomically taken to fuse, then a new run executes
+ * round2 with the persisted decision. A second approve loses at approvePending (not-pending).
+ */
+import { errorText } from '@lmzhen/dsh-evolution-core';
 import { approvePending } from "./pending-actions.js";
+import { pairLedger } from "./domain/pair-ledger.js";
+import { presentStage } from "./domain/stage-aggregate.js";
+import { v4ToLegacy } from "./domain/row-v4.js";
 import { loadMergeState } from "./state.js";
 import { withMergeRun } from "./run-shell.js";
 import { recordRound2Outcome } from "./round2-outcome.js";
+import { failure } from "./domain/errors.js";
 export async function runApproveCommand(options) {
     const loaded = await loadMergeState(options.io, options.home);
     const before = loaded.state.rows.find(item => item.id === options.rowId);
     if (before === undefined)
-        return { ok: false, message: 'pending row not found: ' + options.rowId };
+        return failure('approve', 'row-not-found', '找不到待批准行 ' + options.rowId, '运行 /evolution merge pending 查看当前待批准行');
     if (before.state !== 'pending')
-        return { ok: false, message: 'row is not pending: ' + before.state };
+        return failure('approve', 'row-not-pending', '该行当前状态是 ' + before.state + '，不能批准', '运行 /evolution merge status ' + before.id + ' 查看行状态', before.runId);
+    if (options.agentless === true)
+        return failure('approve', 'e-305', errorText('e-305-this-invocation-carries-no', { a1: 'approve' }), '在 GUI 或 CLI 的会话里运行 /evolution merge approve ' + before.id);
+    const parentRunId = options.parentRunId ?? before.runId;
+    if (parentRunId === undefined)
+        return failure('approve', 'merge-parent-required', '缺 parent run id（E-305 提示：该行可能由无会话调用创建，或父 run 已丢失）', '在 agent 会话中执行 /evolution merge approve ' + before.id, before.runId);
     const taken = await approvePending(options.io, options.home, options.now, options.rowId);
     if (!taken.ok)
-        return { ok: false, message: taken.message };
-    const row = taken.row;
+        return failure('approve', 'approve-' + taken.reason, taken.message, '重试；若行状态已变化，运行 /evolution merge status ' + options.rowId, before.runId);
+    let row = taken.row;
     const decision = row.decision;
     if (decision === undefined)
-        return { ok: false, message: 'pending row has no decision' };
+        return failure('approve', 'row-invalid', '该待批准行没有持久化决策', '重新 pair 该技能对后再次批准', row.runId);
+    if (options.ports.stage !== undefined) {
+        const staged = await options.ports.stage(row, decision);
+        if (!staged.ok)
+            return failure('approve', 'stage-failed', staged.message, '检查暂存目录后重试；不影响已记录的决策', row.runId);
+        const fused = await pairLedger(options.io, options.home).transact(tx => {
+            const current = tx.rows().find(item => item.id === row.id);
+            if (current === undefined)
+                return null;
+            const moved = tx.transition(row.id, { type: 'staged' }, current.version);
+            return moved.ok && moved.row !== null ? v4ToLegacy(moved.row) : null;
+        });
+        if (fused === null)
+            return failure('approve', 'row-changed', '行在暂存完成前被并发修改：' + row.id, '运行 /evolution merge status ' + row.id + ' 后重试', row.runId);
+        await presentStage(options.io, options.home, staged.entry);
+        row = fused;
+    }
     return await withMergeRun({
         io: options.io,
         home: options.home,
         registry: options.registry,
         command: 'approve',
         approval: { platformWrite: options.platformWrite, mergeApproval: true },
+        pairKey: row.pairKey,
+        parentRunId,
         now: options.now,
         ...(options.detached === true ? { detached: true } : {}),
         async body(ctx) {
@@ -35,7 +67,7 @@ export async function runApproveCommand(options) {
                 outcome = { kind: 'failed', failure: { stage: 'author', code: 'merge-failed', message: error instanceof Error ? error.message : String(error), retryable: true, retryFrom: 'agent2' } };
             }
             const base = { scope: { candidatePairs: 1, queueBefore: { verify: 0, pending: 0, fuse: 1, skipped: 0 } }, notes: [] };
-            const record = await recordRound2Outcome(options.io, options.home, options.now, row, outcome);
+            const record = await recordRound2Outcome(options.io, options.home, options.now, row, outcome, true);
             return {
                 ...base,
                 stopReason: record.merged ? 'completed' : 'failed',
@@ -43,6 +75,7 @@ export async function runApproveCommand(options) {
                 totals: record.merged
                     ? { merged: 1, kept: 0, pending: 0, failed: 0 }
                     : { merged: 0, kept: 0, pending: 0, failed: 1 },
+                ...(record.finalize === undefined ? {} : { finalize: record.finalize }),
             };
         },
     });

package/lib/types/authoring-flow.d.ts

@@ -7,7 +7,15 @@ import type { EvolutionIoLike, UnitTransaction } from '@lmzhen/dsh-evolution-cor
 import { type RuleFinding } from './rules.ts';
 import { type CommitPort, type CommitStagedResult } from './commit-execute.ts';
 import type { StagedTree } from './rules.ts';
+import type { RevisionRef } from './contracts.ts';
 import type { SkillCard } from './skill-card.ts';
+import { type SkillLimits } from '@lmzhen/dsh-evolution-core';
+/** Decision-time anchors threaded from round 1 into the commit CAS. */
+export interface CommitRevisionRefs {
+    readonly targetRevision?: RevisionRef;
+    readonly sourceRevisions?: Readonly<Record<string, RevisionRef>>;
+    readonly supportDigest?: string;
+}
 export interface RunAuthoringOptions {
     readonly io: EvolutionIoLike;
     readonly home: string;
@@ -26,17 +34,25 @@ export interface RunAuthoringOptions {
     readonly summary: string;
     readonly isBlocked?: (name: string) => boolean | Promise<boolean>;
     readonly unit?: UnitTransaction | undefined;
+    readonly limits?: SkillLimits;
+    readonly promptVersion?: string;
+    readonly promptHash?: string;
+    /** Round-1 decision anchors; when absent the commit keeps the legacy body-only CAS. */
+    readonly revisions?: CommitRevisionRefs;
 }
 export type AuthoringResult = {
     readonly ok: true;
     readonly tree: StagedTree;
+    readonly validationPlan: import('./domain/validation-plan.ts').ValidationPlan;
     readonly commit: Extract<CommitStagedResult, {
         readonly ok: true;
     }>;
 } | {
     readonly ok: false;
+    readonly code?: string;
     readonly message: string;
     readonly findings?: readonly RuleFinding[];
+    readonly lengths?: Readonly<Record<string, number>>;
 };
 export declare function runAuthoring(options: RunAuthoringOptions): Promise<AuthoringResult>;
 //# sourceMappingURL=authoring-flow.d.ts.map

package/lib/types/authoring-flow.js

@@ -2,22 +2,28 @@ import { createStaging, setStagingTarget } from "./staging.js";
 import { readStagedTree } from "./staged-tree.js";
 import { validateStagedTree, hasBlockingFinding } from "./rules.js";
 import { commitStagedRun } from "./commit-execute.js";
+import { DEFAULT_SKILL_LIMITS } from '@lmzhen/dsh-evolution-core';
+import { limitsSnapshotOf } from "./domain/merge-limits.js";
+import { buildValidationPlan } from "./domain/validation-plan.js";
+import { manifestFilesOf, missingManifestFile, parseAuthoringManifest } from "./domain/authoring-manifest.js";
 export async function runAuthoring(options) {
+    if (options.target.includes('/') || options.target.includes(':'))
+        return { ok: false, code: 'target-invalid', message: 'target must be a bare skill name: ' + options.target };
     const targetCard = options.cards.find(card => card.name === options.target);
     const mode = options.mode ?? (targetCard === undefined ? 'create-umbrella' : 'merge-into-existing');
     const createMode = mode === 'create-umbrella';
     if (!createMode && targetCard !== undefined) {
         if (targetCard.managed !== true)
-            return { ok: false, message: 'target is not family-managed: ' + options.target };
+            return { ok: false, code: 'target-not-managed', message: 'target is not family-managed: ' + options.target };
         if (targetCard.protectionUnknown === true || targetCard.protectedBy != null)
-            return { ok: false, message: 'target is protected (' + (targetCard.protectedBy ?? 'unknown') + '): ' + options.target };
+            return { ok: false, code: 'target-protected', message: 'target is protected (' + (targetCard.protectedBy ?? 'unknown') + '): ' + options.target };
     }
     if (!createMode && await options.isBlocked?.(options.target) === true)
-        return { ok: false, message: 'target is blocked by curator: ' + options.target };
+        return { ok: false, code: 'target-blocked', message: 'target is blocked by curator: ' + options.target };
     const stageKey = options.stageKey ?? options.runId;
     if (options.reuseStaging === true) {
         if (!await setStagingTarget(options.io, options.home, stageKey, options.target, mode))
-            return { ok: false, message: 'staging missing or unreadable: ' + stageKey };
+            return { ok: false, code: 'staging-missing', message: 'staging missing or unreadable: ' + stageKey };
     }
     else {
         const created = await createStaging(options.io, options.home, {
@@ -30,29 +36,47 @@ export async function runAuthoring(options) {
             now: options.now,
         });
         if (!created.ok)
-            return { ok: false, message: created.message };
+            return { ok: false, code: 'staging-create', message: created.message };
     }
+    let authored;
     try {
-        await options.author({ home: options.home, runId: stageKey });
+        authored = await options.author({ home: options.home, runId: stageKey });
     }
     catch (error) {
-        return { ok: false, message: 'author failed: ' + (error instanceof Error ? error.message : String(error)) };
+        return { ok: false, code: 'author-failed', message: 'author failed: ' + (error instanceof Error ? error.message : String(error)) };
     }
     const tree = await readStagedTree(options.io, options.home, stageKey);
     if (tree.kind !== 'present')
-        return { ok: false, message: 'staged tree is not readable: ' + (tree.kind === 'unknown' ? tree.reason : 'absent') };
-    const findings = validateStagedTree(tree.value);
+        return { ok: false, code: 'staging-missing', message: 'staged tree is not readable: ' + (tree.kind === 'unknown' ? tree.reason : 'absent') };
+    // FR-VAL-03: the same-child path parses the child's files[] declaration too, so a
+    // manifest that promises a file the tree does not contain fails here — not only on the
+    // new-child approve path.
+    const manifest = parseAuthoringManifest(authored);
+    const stagedPaths = tree.value.files.map(file => file.path);
+    const manifestFiles = manifestFilesOf(manifest, stagedPaths);
+    const missing = missingManifestFile(manifestFiles, stagedPaths);
+    if (missing !== null)
+        return { ok: false, code: 'merge-manifest-missing', message: 'manifest file missing from staged tree: ' + missing };
+    const limitsSnapshot = limitsSnapshotOf(options.limits ?? DEFAULT_SKILL_LIMITS);
+    const supportSources = options.cards.flatMap(card => (card.files ?? []).map(file => ({ path: file.path, content: file.content, source: card.name })));
+    const validationPlan = buildValidationPlan({ tree: tree.value, target: options.target, limits: limitsSnapshot, cards: options.cards, supportSources, ...(options.promptVersion === undefined ? {} : { promptVersion: options.promptVersion }), ...(options.promptHash === undefined ? {} : { promptHash: options.promptHash }), supportFiles: tree.value.files.map(file => ({ path: file.path, content: file.content, source: 'staged' })), manifestFiles, existingSupport: (options.cards.find(card => card.name === options.target)?.files ?? []).map(file => file.path) });
+    const findings = [...validateStagedTree(tree.value, limitsSnapshot.skillLimits), ...validationPlan.findings];
     if (hasBlockingFinding(findings))
-        return { ok: false, message: 'staged tree failed the rule gate', findings };
+        return { ok: false, code: findings.some(finding => finding.rule === 'limit') ? 'merge-over-limit' : 'merge-validation', message: 'staged tree failed the rule gate', findings, lengths: { bodyBytes: Buffer.byteLength(tree.value.body, 'utf8'), fileBytes: tree.value.files.reduce((sum, file) => sum + Buffer.byteLength(file.content, 'utf8'), 0), totalBytes: Buffer.byteLength(tree.value.body, 'utf8') + tree.value.files.reduce((sum, file) => sum + Buffer.byteLength(file.content, 'utf8'), 0) } };
     const commit = await commitStagedRun(options.io, options.home, stageKey, options.commitPort, {
         origin: 'foreground',
         summary: options.summary,
         now: options.now,
         ...(options.isBlocked === undefined ? {} : { isBlocked: options.isBlocked }),
         ...(options.unit === undefined ? {} : { unit: options.unit }),
+        ...(options.limits === undefined ? {} : { limits: options.limits }),
+        validationPlan: { planVersion: validationPlan.planVersion, stageDigest: validationPlan.stageDigest, revision: validationPlan.revision },
+        ...(options.revisions?.targetRevision === undefined ? {} : { targetRevision: options.revisions.targetRevision }),
+        ...(options.revisions?.sourceRevisions === undefined ? {} : { sourceRevisions: options.revisions.sourceRevisions }),
+        ...(options.revisions?.supportDigest === undefined ? {} : { supportDigest: options.revisions.supportDigest }),
     });
-    if (!commit.ok)
-        return { ok: false, message: commit.message };
-    return { ok: true, tree: tree.value, commit };
+    if (commit.ok)
+        return { ok: true, tree: tree.value, validationPlan, commit };
+    return { ok: false, code: commit.code ?? 'commit-failed', message: commit.message };
 }
 //# sourceMappingURL=authoring-flow.js.map

package/lib/types/channel-port.d.ts

@@ -3,13 +3,14 @@
  * an author callback for round 2 when the same child continues. Commit is deliberately
  * outside this adapter: the caller owns staging -> commitStagedRun.
  */
-import type { MergeDecision, MergeRow } from './contracts.ts';
+import type { MergeDecision, MergeRow, MergeUsage } from './contracts.ts';
 import type { SkillCard } from './skill-card.ts';
 import type { ScanRound1Outcome } from './scan-run.ts';
 export interface ChannelTurnLike {
     readonly text: string;
     readonly stopReason: string;
     readonly cacheRead?: number;
+    readonly usage?: MergeUsage;
 }
 export type ChannelTurnOutcome = {
     readonly kind: 'ok';
@@ -51,6 +52,7 @@ export interface ChannelRound1Options {
 export interface ChannelRound1Result {
     readonly outcome: ScanRound1Outcome;
     readonly childId?: string;
+    readonly usage?: () => MergeUsage | undefined;
     /** Same-child round 2; absent for keep/fail/unavailable. */
     readonly author?: (row: MergeRow, decision: MergeDecision, signal: AbortSignal) => Promise<string>;
     readonly dispose: () => Promise<void>;

package/lib/types/channel-port.js

@@ -1,7 +1,8 @@
 import { parseDecision } from "./decision.js";
-import { buildRound1Prompt, buildRound2Prompt, STANDBY_PROMPT } from "./prompts.js";
+import { buildRound1Prompt, buildRound2Prompt, MERGE_PROMPT_VERSION, promptHashOf, STANDBY_PROMPT } from "./prompts.js";
 export async function runRound1OverChannel(options, candidate, signal) {
     let childId;
+    let lastUsage;
     const dispose = async () => {
         if (childId !== undefined) {
             const id = childId;
@@ -38,7 +39,8 @@ export async function runRound1OverChannel(options, candidate, signal) {
         await dispose();
         return { outcome: { kind: 'failed', failure: { stage: 'decide', code: 'child-bind', message: String(error), retryable: true, retryFrom: 'agent1' } }, dispose };
     }
-    const round1 = await options.channel.continueTurn(opened.childId, buildRound1Prompt(candidate, options.cards), { timeoutMs: options.timeoutMs, signal });
+    const prompt = buildRound1Prompt(candidate, options.cards);
+    const round1 = await options.channel.continueTurn(opened.childId, prompt, { timeoutMs: options.timeoutMs, signal });
     if (round1.kind !== 'ok') {
         await dispose();
         return { outcome: { kind: 'failed', failure: { stage: 'decide', code: round1.kind, message: round1.kind === 'unavailable' ? round1.reason : 'round1 aborted', retryable: round1.kind !== 'aborted', retryFrom: round1.kind === 'aborted' ? 'none' : 'agent1' } }, dispose };
@@ -52,7 +54,8 @@ export async function runRound1OverChannel(options, candidate, signal) {
         await dispose();
         return { outcome: { kind: 'failed', failure: { stage: 'decide', code: parsed.code, message: parsed.message, retryable: true, retryFrom: 'agent1' } }, dispose };
     }
-    const decision = round1.turn.cacheRead === undefined ? parsed.decision : { ...parsed.decision, cacheRead: round1.turn.cacheRead };
+    lastUsage = round1.turn.usage;
+    const decision = { ...parsed.decision, promptVersion: MERGE_PROMPT_VERSION, promptHash: promptHashOf(prompt), ...(round1.turn.cacheRead === undefined ? {} : { cacheRead: round1.turn.cacheRead }) };
     if (!decision.shouldMerge || decision.mode === 'keep') {
         await dispose();
         return { outcome: { kind: 'keep', decision }, dispose };
@@ -62,12 +65,14 @@ export async function runRound1OverChannel(options, candidate, signal) {
         outcome: { kind: 'merge', decision },
         childId: child,
         dispose,
+        usage: () => lastUsage,
         async author(row, decision, turnSignal) {
             const turn = await options.channel.continueTurn(child, buildRound2Prompt(row, decision), { timeoutMs: options.timeoutMs, signal: turnSignal });
             if (turn.kind !== 'ok')
                 throw new Error(turn.kind === 'unavailable' ? turn.reason : 'round2 aborted');
             if (turn.turn.stopReason !== 'completed')
                 throw new Error('round2 did not complete: ' + turn.turn.stopReason);
+            lastUsage = turn.turn.usage;
             return turn.turn.text;
         },
     };

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

@@ -0,0 +1,5 @@
+import type { CommandDef } from '@lmzhen/dsh-evolution-commands';
+export declare const MERGE_PACKAGE_VERSION: string;
+export declare const MERGE_ALIAS_DEF: CommandDef;
+export declare const MERGE_COMMAND_DEFS: readonly CommandDef[];
+//# sourceMappingURL=command-defs.d.ts.map

package/lib/types/command-defs.js

@@ -0,0 +1,33 @@
+/** Merge CommandDef data; parser/help/surface/fallback live in evolution-commands. */
+import { readFileSync } from 'node:fs';
+const manifest = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+export const MERGE_PACKAGE_VERSION = manifest.version ?? '0.30.18';
+export const MERGE_ALIAS_DEF = { id: 'merge.alias', words: ['merge'], summaryKey: 'merge.alias', helpKey: 'merge.alias.help', flags: [], positional: [], readOnly: false, needsRun: false, fallback: '/merge', deprecatedAt: '0.31' };
+const pos = (name, kind, required = true) => ({ name, kind, required });
+const flag = (name, kind, valueName, required = false) => ({ name, kind, ...(valueName === undefined ? {} : { valueName }), ...(required ? { required: true } : {}) });
+const action = (id, command, confirm = false) => ({ id, command, confirm });
+const cmd = (id, words, flags, positional, readOnly, needsRun, rowActions, fallback) => ({ id, words, summaryKey: id, helpKey: id + '.help', flags, positional, readOnly, needsRun, rowActions, fallback });
+export const MERGE_COMMAND_DEFS = [
+    ({ ...({ ...cmd('merge.doctor', ['doctor'], [], [], false, false, [], '/evolution merge doctor'), usage: false }), surface: false }),
+    ({ ...cmd('merge.reconcile', ['reconcile'], [], [], false, false, [], '/evolution merge reconcile'), surface: false }),
+    cmd('merge.scan', ['scan'], [], [], false, true, [], '/evolution merge scan'),
+    cmd('merge.pair', ['pair'], [], [pos('a', 'skill'), pos('b', 'skill')], false, true, [action('pair', '/evolution merge pair {a} {b}', true)], '/evolution merge pair <a> <b>'),
+    cmd('merge.pair.force', ['pair'], [flag('force', 'boolean')], [pos('a', 'skill'), pos('b', 'skill')], false, true, [action('pair', '/evolution merge pair {a} {b}', true)], '/evolution merge pair --force <a> <b>'),
+    cmd('merge.status', ['status'], [], [pos('id', 'id', false)], true, false, [action('status', '/evolution merge status {runId}')], '/evolution merge status'),
+    cmd('merge.report', ['report'], [], [pos('id', 'id', false)], true, false, [action('report', '/evolution merge report {runId}')], '/evolution merge report'),
+    cmd('merge.cancel', ['cancel'], [], [pos('id', 'id', false)], false, false, [action('cancel', '/evolution merge cancel {runId}')], '/evolution merge cancel <id>'),
+    cmd('merge.runs', ['runs'], [], [], true, false, [], '/evolution merge runs'),
+    cmd('merge.pending', ['pending'], [], [], true, false, [], '/evolution merge pending'),
+    cmd('merge.pending.expired', ['pending'], [flag('expired', 'boolean')], [], true, false, [], '/evolution merge pending --expired'),
+    cmd('merge.approve', ['approve'], [], [pos('id', 'id')], false, true, [action('approve', '/evolution merge approve {id}')], '/evolution merge approve <id>'),
+    cmd('merge.reject', ['reject'], [], [pos('id', 'id')], false, false, [action('reject', '/evolution merge reject {id}', true)], '/evolution merge reject <id>'),
+    cmd('merge.skipped', ['skipped'], [], [], true, false, [], '/evolution merge skipped'),
+    cmd('merge.skipped.restore', ['skipped'], [flag('restore', 'value', 'id')], [], false, false, [action('restore', '/evolution merge skipped --restore {id}', true)], '/evolution merge skipped --restore <id>'),
+    cmd('merge.candidates', ['candidates'], [], [], true, false, [], '/evolution merge candidates'),
+    cmd('merge.candidates.retry', ['candidates'], [flag('retry', 'boolean')], [pos('id', 'id', false)], false, true, [action('retry-candidates', '/evolution merge candidates --retry {id}')], '/evolution merge candidates --retry <id>'),
+    cmd('merge.resume', ['resume'], [flag('clear', 'value', 'id')], [pos('id', 'id', false)], true, false, [action('retry-resume', '/evolution merge resume --retry {id}')], '/evolution merge resume'),
+    cmd('merge.resume.retry', ['resume'], [flag('retry', 'boolean'), flag('clear', 'value', 'id')], [pos('id', 'id', false)], false, true, [action('retry-resume', '/evolution merge resume --retry {id}')], '/evolution merge resume --retry <id>'),
+    cmd('merge.discard', ['discard'], [], [pos('id', 'id')], false, false, [action('discard', '/evolution merge discard {id}', true)], '/evolution merge discard <id>'),
+    cmd('merge.undo', ['undo'], [flag('run', 'value', 'id', true)], [pos('target', 'target')], false, false, [], '/evolution merge undo <target> --run <id>'),
+];
+//# sourceMappingURL=command-defs.js.map

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

@@ -1,4 +1,4 @@
-/** Frozen merge CommandSurface v1: 19 commands, JSON-safe, no handlers. */
+/** Generated merge CommandSurface from command-defs; no handwritten table. */
 import type { CommandSpec, CommandSurface } from './wire.ts';
 export declare const MERGE_COMMANDS: readonly CommandSpec[];
 export declare const MERGE_COMMAND_SURFACE: CommandSurface;

package/lib/types/command-surface.js

@@ -1,44 +1,11 @@
-const flag = (name, kind = 'boolean', valueName) => ({ name, kind, ...(valueName === undefined ? {} : { valueName }) });
-const pos = (name, kind, required = true) => ({ name, kind, required });
-const action = (id, command, confirm = false) => ({ id, command, confirm });
-function spec(id, words, flags, positional, readOnly, needsRun, rowActions, fallback) {
-    return { id, words, flags, positional, summary: id, readOnly, needsRun, defaults: {}, rowActions, fallback };
-}
-export const MERGE_COMMANDS = [
-    spec('merge.scan', ['scan'], [], [], false, true, [], '/evolution merge scan'),
-    spec('merge.pair', ['pair'], [], [pos('a', 'skill'), pos('b', 'skill')], false, true, [action('pair', '/evolution merge pair', true)], '/evolution merge pair <a> <b>'),
-    spec('merge.pair.force', ['pair'], [flag('force')], [pos('a', 'skill'), pos('b', 'skill')], false, true, [], '/evolution merge pair --force <a> <b>'),
-    spec('merge.status', ['status'], [], [pos('id', 'id', false)], true, false, [action('status', '/evolution merge status')], '/evolution merge status'),
-    spec('merge.report', ['report'], [], [pos('id', 'id', false)], true, false, [action('report', '/evolution merge report')], '/evolution merge report'),
-    spec('merge.cancel', ['cancel'], [], [pos('id', 'id', false)], false, false, [action('cancel', '/evolution merge cancel')], '/evolution merge cancel <id>'),
-    spec('merge.runs', ['runs'], [], [], true, false, [], '/evolution merge runs'),
-    spec('merge.pending', ['pending'], [], [], true, false, [], '/evolution merge pending'),
-    spec('merge.pending.expired', ['pending'], [flag('expired')], [], true, false, [], '/evolution merge pending --expired'),
-    spec('merge.approve', ['approve'], [], [pos('id', 'id')], false, true, [action('approve', '/evolution merge approve <id>')], '/evolution merge approve <id>'),
-    spec('merge.reject', ['reject'], [], [pos('id', 'id')], false, false, [action('reject', '/evolution merge reject <id>', true)], '/evolution merge reject <id>'),
-    spec('merge.skipped', ['skipped'], [], [], true, false, [], '/evolution merge skipped'),
-    spec('merge.skipped.restore', ['skipped'], [flag('restore', 'value', 'id')], [], false, false, [action('restore', '/evolution merge skipped --restore <id>', true)], '/evolution merge skipped --restore <id>'),
-    spec('merge.candidates', ['candidates'], [], [], true, false, [], '/evolution merge candidates'),
-    spec('merge.candidates.retry', ['candidates'], [flag('retry', 'value', 'id')], [], false, true, [action('retry-candidates', '/evolution merge candidates --retry <id>')], '/evolution merge candidates --retry <id>'),
-    spec('merge.resume', ['resume'], [], [pos('id', 'id', false)], true, false, [], '/evolution merge resume'),
-    spec('merge.resume.retry', ['resume'], [flag('retry', 'value', 'id')], [], false, true, [action('retry-resume', '/evolution merge resume --retry <id>')], '/evolution merge resume --retry <id>'),
-    spec('merge.discard', ['discard'], [], [pos('id', 'id')], false, false, [action('discard', '/evolution merge discard <id>', true)], '/evolution merge discard <id>'),
-    spec('merge.undo', ['undo'], [flag('run', 'value', 'id')], [pos('target', 'target')], false, false, [], '/evolution merge undo <target> --run <id>'),
-];
-export const MERGE_COMMAND_SURFACE = {
-    wireVersion: 1,
-    prefix: '/evolution merge',
-    commands: MERGE_COMMANDS,
-    fallback: [
-        { id: 'scan', command: '/evolution merge scan' },
-        { id: 'pair', command: '/evolution merge pair <a> <b>' },
-        { id: 'candidates', command: '/evolution merge candidates' },
-        { id: 'pending', command: '/evolution merge pending' },
-        { id: 'skipped', command: '/evolution merge skipped' },
-        { id: 'resume', command: '/evolution merge resume' },
-        { id: 'status', command: '/evolution merge status' },
-        { id: 'report', command: '/evolution merge report' },
-        { id: 'doctor', command: '/evolution merge doctor' },
-    ],
-};
+import { buildSurface } from '@lmzhen/dsh-evolution-commands';
+import { MERGE_COMMAND_DEFS } from "./command-defs.js";
+const generated = buildSurface(MERGE_COMMAND_DEFS, '/evolution merge');
+export const MERGE_COMMANDS = generated.commands.map(command => ({
+    id: command.id, words: command.words, flags: command.flags, positional: command.positional,
+    summary: command.id, readOnly: command.readOnly, needsRun: command.needsRun, defaults: command.defaults,
+    rowActions: command.rowActions.map(action => ({ id: action.id, command: action.command, confirm: action.confirm })),
+    fallback: command.fallback,
+}));
+export const MERGE_COMMAND_SURFACE = { wireVersion: 1, prefix: '/evolution merge', commands: MERGE_COMMANDS, fallback: generated.fallback.map(item => ({ id: item.id, command: item.command })) };
 //# sourceMappingURL=command-surface.js.map

package/lib/types/commands.d.ts

@@ -1,7 +1,3 @@
-/**
- * Pure command-surface parser for the /evolution merge prefix. The command layer only
- * validates shape; run/state effects are injected by the host shell.
- */
 export type MergeCliCommand = {
     readonly verb: 'scan';
 } | {
@@ -22,12 +18,15 @@ export type MergeCliCommand = {
     readonly verb: 'runs';
 } | {
     readonly verb: 'doctor';
+} | {
+    readonly verb: 'reconcile';
 } | {
     readonly verb: 'pending';
     readonly expired?: true;
 } | {
     readonly verb: 'candidates';
     readonly retry?: true;
+    readonly id?: string;
 } | {
     readonly verb: 'approve';
     readonly id: string;