@lmzhen/dsh-evolution-merge 0.30.17 → 0.30.19

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/library.js

@@ -8,7 +8,10 @@ export function skillLibraryPort(skills) {
             const names = await archivedNames.call(skills);
             return names === null ? true : names.includes(name);
         },
-        commitMerge: plan => skills.commitMerge(plan),
+        isNameOccupied: async (name) => {
+            const probe = skills.skillDirExists;
+            return typeof probe === 'function' ? await probe.call(skills, name) : false;
+        },
         async readSupportFiles(name) {
             if (typeof skills.listSupportFiles !== 'function')
                 return [];

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.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Structural ModelPort adapter over the platform llm service. The platform exposes either
+ * `stream()` (the current shape) or the older prepareCall()/stream pair; both return raw text
+ * because the gate and proposer own JSON extraction.
+ */
+import type { ModelPort } from '../propose.ts';
+export interface ModelRoute {
+    readonly provider: string;
+    readonly model: string;
+}
+export interface LlmChunkLike {
+    readonly type: string;
+    readonly text?: string;
+    readonly usage?: unknown;
+    readonly reason?: {
+        readonly kind?: string;
+        readonly failure?: {
+            readonly message?: string;
+        };
+    };
+}
+export interface LlmCallLike {
+    readonly config: Record<string, unknown>;
+    stream(input: Record<string, unknown>): AsyncIterable<LlmChunkLike>;
+}
+export interface LlmServiceLike {
+    prepareCall?(config: Record<string, unknown>, signal?: AbortSignal): Promise<LlmCallLike>;
+    stream?(options: Record<string, unknown>): AsyncIterable<LlmChunkLike>;
+}
+export declare function createModelPort(llm: LlmServiceLike, route: () => ModelRoute): ModelPort;
+//# sourceMappingURL=model.d.ts.map

package/lib/types/adapters/model.js

@@ -0,0 +1,47 @@
+import { normalizeProviderKey } from "../domain/provider-key.js";
+function append(chunk, text) {
+    if (chunk.type === 'text-delta' || chunk.type === 'text')
+        return text + (chunk.text ?? '');
+    if (chunk.type === 'finish' && chunk.reason?.kind === 'error') {
+        throw new Error('model call failed: ' + (chunk.reason.failure?.message ?? 'unknown'));
+    }
+    return text;
+}
+export function createModelPort(llm, route) {
+    return {
+        async callJson(request) {
+            const selection = route();
+            let text = '';
+            if (llm.stream !== undefined) {
+                for await (const chunk of llm.stream({
+                    provider: normalizeProviderKey(selection.provider),
+                    model: selection.model,
+                    system: request.system,
+                    messages: [{ role: 'user', content: [{ type: 'text', text: request.user }] }],
+                    maxTokens: request.maxTokens,
+                    temperature: 0,
+                    signal: request.signal,
+                }))
+                    text = append(chunk, text);
+                return text;
+            }
+            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,
+                maxTokens: request.maxTokens,
+                temperature: 0,
+            }, request.signal);
+            for await (const chunk of call.stream({
+                ...call.config,
+                system: request.system,
+                messages: [{ role: 'user', content: [{ type: 'text', text: request.user }] }],
+                signal: request.signal,
+            }))
+                text = append(chunk, text);
+            return text;
+        },
+    };
+}
+//# sourceMappingURL=model.js.map

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,7 +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,55 +1,83 @@
+/**
+ * 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 { acquireTargetClaim } from "./target-claim.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);
-    const target = before?.decision?.target;
-    const claim = target === undefined ? null : await acquireTargetClaim(options.io, options.home, target, options.now());
-    if (target !== undefined && claim === null)
-        return { ok: false, message: 'target already claimed by another approve: ' + target };
-    try {
-        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;
-        const decision = row.decision;
-        if (decision === undefined)
-            return { ok: false, message: 'pending row has no decision' };
-        return await withMergeRun({
-            io: options.io,
-            home: options.home,
-            registry: options.registry,
-            command: 'approve',
-            approval: { platformWrite: options.platformWrite, mergeApproval: true },
-            now: options.now,
-            async body(ctx) {
-                const stage = (name) => ctx.stage(name, { done: 0, total: 1 });
-                await stage('author');
-                let outcome;
-                try {
-                    outcome = await options.ports.round2(row, decision, ctx.signal, ctx.runId);
-                }
-                catch (error) {
-                    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);
-                return {
-                    ...base,
-                    stopReason: record.merged ? 'completed' : 'failed',
-                    pairs: [record.pair],
-                    totals: record.merged
-                        ? { merged: 1, kept: 0, pending: 0, failed: 0 }
-                        : { merged: 0, kept: 0, pending: 0, failed: 1 },
-                };
-            },
+    if (before === undefined)
+        return failure('approve', 'row-not-found', '找不到待批准行 ' + options.rowId, '运行 /evolution merge pending 查看当前待批准行');
+    if (before.state !== 'pending')
+        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 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 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;
     }
-    finally {
-        await claim?.release();
-    }
+    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) {
+            const stage = (name) => ctx.stage(name, { done: 0, total: 1 });
+            await stage('author');
+            let outcome;
+            try {
+                outcome = await options.ports.round2(row, decision, ctx.signal, ctx.runId);
+            }
+            catch (error) {
+                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, true);
+            return {
+                ...base,
+                stopReason: record.merged ? 'completed' : 'failed',
+                pairs: [record.pair],
+                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 }),
+            };
+        },
+    });
 }
 //# sourceMappingURL=approve-command.js.map

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

@@ -3,11 +3,19 @@
  * rule gate, then commit through the injected CommitPort. The channel adapter and the
  * author tool live outside; this is the seam they share.
  */
-import type { EvolutionIoLike } from '@lmzhen/dsh-evolution-core';
+import type { EvolutionIoLike, UnitTransaction } from '@lmzhen/dsh-evolution-core';
 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;
@@ -24,17 +32,27 @@ export interface RunAuthoringOptions {
     readonly commitPort: CommitPort;
     readonly now: () => number;
     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,47 +2,81 @@ 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);
-    if (targetCard?.protectionUnknown === true || targetCard?.protectedBy === 'pinned')
-        return { ok: false, message: 'target is pinned: ' + 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, code: 'target-not-managed', message: 'target is not family-managed: ' + options.target };
+        if (targetCard.protectionUnknown === true || targetCard.protectedBy != null)
+            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, 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, options.mode))
-            return { ok: false, message: 'staging missing or unreadable: ' + stageKey };
+        if (!await setStagingTarget(options.io, options.home, stageKey, options.target, mode))
+            return { ok: false, code: 'staging-missing', message: 'staging missing or unreadable: ' + stageKey };
     }
     else {
         const created = await createStaging(options.io, options.home, {
             runId: stageKey,
             target: options.target,
-            ...(options.mode === undefined ? {} : { mode: options.mode }),
+            mode,
             sources: options.cards.map(card => ({ name: card.name, body: card.body, files: card.files ?? [] })),
             promptVersion: 'merge-b/v1',
             ttlDays: 7,
             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: 'subagent',
+        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