@lmzhen/dsh-evolution-merge 0.30.24 → 0.30.27

package/lib/types/approve-command.js

@@ -38,7 +38,7 @@ export async function runApproveCommand(options) {
             const current = tx.rows().find(item => item.id === row.id);
             if (current === undefined)
                 return null;
-            const moved = tx.transition(row.id, { type: 'staged' }, current.version);
+            const moved = tx.transition(row.id, { type: 'staged', stagingRef: staged.entry.ref, stagingExpiresAt: staged.entry.expiresAt }, current.version);
             return moved.ok && moved.row !== null ? v4ToLegacy(moved.row) : null;
         });
         if (fused === null)
@@ -53,6 +53,7 @@ export async function runApproveCommand(options) {
         command: 'approve',
         approval: { platformWrite: options.platformWrite, mergeApproval: true },
         pairKey: row.pairKey,
+        ...(row.stagingRef === undefined ? {} : { stagingRef: row.stagingRef }),
         parentRunId,
         now: options.now,
         ...(options.detached === true ? { detached: true } : {}),

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

@@ -23,6 +23,8 @@ export interface RunAuthoringOptions {
     readonly stageKey?: string;
     readonly reuseStaging?: boolean;
     readonly target: string;
+    /** The two participating source skills; conflict detection is limited to these. */
+    readonly sources?: readonly string[];
     readonly mode?: 'merge-into-existing' | 'create-umbrella' | 'keep';
     readonly cards: readonly SkillCard[];
     readonly author: (staging: {
@@ -37,6 +39,8 @@ export interface RunAuthoringOptions {
     readonly limits?: SkillLimits;
     readonly promptVersion?: string;
     readonly promptHash?: string;
+    /** Propagated to the commit; aborting before the durable point prevents a orphaned commit. */
+    readonly signal?: AbortSignal;
     /** Round-1 decision anchors; when absent the commit keeps the legacy body-only CAS. */
     readonly revisions?: CommitRevisionRefs;
 }
@@ -47,6 +51,7 @@ export type AuthoringResult = {
     readonly commit: Extract<CommitStagedResult, {
         readonly ok: true;
     }>;
+    readonly lengths: Readonly<Record<string, number>>;
 } | {
     readonly ok: false;
     readonly code?: string;

package/lib/types/authoring-flow.js

@@ -10,7 +10,12 @@ 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');
+    // A decision can name a fresh target yet say merge-into-existing (the model's vocabulary is
+    // about intent, not existence). The target card is the authoritative existence fact: when it is
+    // absent, the only safe mode is create-umbrella; otherwise commit-assembly correctly refuses to
+    // re-create a target that disappeared later.
+    const requestedMode = options.mode ?? (targetCard === undefined ? 'create-umbrella' : 'merge-into-existing');
+    const mode = requestedMode === 'merge-into-existing' && targetCard === undefined ? 'create-umbrella' : requestedMode;
     const createMode = mode === 'create-umbrella';
     if (!createMode && targetCard !== undefined) {
         if (targetCard.managed !== true)
@@ -58,25 +63,28 @@ export async function runAuthoring(options) {
     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 participants = new Set(options.sources ?? []);
+    const supportSources = options.cards.filter(card => participants.has(card.name)).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];
+    const 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) };
     if (hasBlockingFinding(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) } };
+        return { ok: false, code: findings.some(finding => finding.rule === 'limit') ? 'merge-over-limit' : 'merge-validation', message: 'staged tree failed the rule gate', findings, lengths };
     const commit = await commitStagedRun(options.io, options.home, stageKey, options.commitPort, {
         origin: 'foreground',
         summary: options.summary,
         now: options.now,
+        ...(options.signal === undefined ? {} : { signal: options.signal }),
         ...(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 },
+        limits: limitsSnapshot.skillLimits,
+        validationPlan: { planVersion: validationPlan.planVersion, stageDigest: validationPlan.stageDigest, revision: validationPlan.revision, manifestFiles: validationPlan.manifestFiles },
         ...(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: true, tree: tree.value, validationPlan, commit };
+        return { ok: true, tree: tree.value, validationPlan, commit, lengths };
     return { ok: false, code: commit.code ?? 'commit-failed', message: commit.message };
 }
 //# sourceMappingURL=authoring-flow.js.map

package/lib/types/commands.d.ts

@@ -59,5 +59,12 @@ export type ParseMergeCommandResult = {
     readonly message: string;
 };
 export declare function parseMergeCommand(argv: readonly string[]): ParseMergeCommandResult;
+export interface MergeLifecycleVerb {
+    readonly verb: string;
+    readonly appliesTo: string;
+    readonly excludes: readonly string[];
+}
+/** Machine-readable three-verb table: merge undo / skill undo / skill restore. */
+export declare const MERGE_LIFECYCLE_VERBS: readonly MergeLifecycleVerb[];
 export declare function mergeUsage(): string;
 //# sourceMappingURL=commands.d.ts.map

package/lib/types/commands.js

@@ -34,7 +34,14 @@ export function parseMergeCommand(argv) {
         default: return { ok: false, code: 'usage', message: 'unknown merge command: ' + parsed.id };
     }
 }
+/** Machine-readable three-verb table: merge undo / skill undo / skill restore. */
+export const MERGE_LIFECYCLE_VERBS = [
+    { verb: 'merge undo', appliesTo: '一次 merge run（按 run 反序撤销 unit）', excludes: ['skill undo', 'skill restore'] },
+    { verb: 'skill undo', appliesTo: '单个技能的一次 patch', excludes: ['merge undo'] },
+    { verb: 'skill restore', appliesTo: '从 .archive 恢复整棵技能树', excludes: ['merge undo'] },
+];
 export function mergeUsage() {
-    return 'usage: ' + MERGE_COMMAND_DEFS.filter(def => def.id !== 'merge.doctor' && def.usage !== false).map(def => def.fallback).join(' | ') + '\ndefaults: mergeApproval=false, mergeSkippedTtlDays=0, mergeRunTimeoutMinutes=0, mergePairTimeoutMinutes=15, mergeModelsRoot=""';
+    return 'usage: ' + MERGE_COMMAND_DEFS.filter(def => def.id !== 'merge.doctor' && def.usage !== false).map(def => def.fallback).join(' | ') + '\ndefaults: mergeApproval=false, mergeSkippedTtlDays=0, mergeRunTimeoutMinutes=0, mergePairTimeoutMinutes=15, mergeModelsRoot=""'
+        + '\nlifecycle: ' + MERGE_LIFECYCLE_VERBS.map(item => item.verb + '=' + item.appliesTo + '；互斥 ' + item.excludes.join('/')).join(' | ');
 }
 //# sourceMappingURL=commands.js.map

package/lib/types/commit-execute.d.ts

@@ -26,6 +26,10 @@ export interface CommitStagedOptions {
     readonly targetRevision?: import('./contracts.ts').RevisionRef;
     readonly sourceRevisions?: Readonly<Record<string, import('./contracts.ts').RevisionRef>>;
     readonly supportDigest?: string;
+    /** The run that started this child; absent means the receipt itself is the root run. */
+    readonly parentRunId?: string;
+    /** Aborts a commit before its durable point; a landed commit still gets a receipt. */
+    readonly signal?: AbortSignal;
     /** G2 transitional: when present, commit through core UnitTransaction. */
     readonly unit?: UnitTransaction;
 }

package/lib/types/commit-execute.js

@@ -21,6 +21,7 @@ export async function commitStagedRun(io, home, runId, port, options) {
     const journal = { runId, target: assembled.plan.target, create: !assembled.plan.targetExists, sources: assembled.plan.sources, phase: 'prepared', updatedAt: new Date(options.now()).toISOString() };
     let result;
     let evidenceSha256;
+    let warning;
     const transaction = options.unit ?? port.unit ?? legacyUnitAdapter(port, assembled.plan, options, runId);
     if (transaction === undefined)
         return { ok: false, message: 'commit port missing: UnitTransaction or commitMerge required', plan: assembled.plan };
@@ -34,7 +35,7 @@ export async function commitStagedRun(io, home, runId, port, options) {
         const prepared = await transaction.prepare(unitPlan);
         if (!prepared.ok)
             return { ok: false, message: prepared.message, plan: assembled.plan };
-        const committed = await transaction.commit(prepared.prepared);
+        const committed = await transaction.commit(prepared.prepared, options.signal === undefined ? undefined : { signal: options.signal });
         if (!committed.ok) {
             try {
                 await writeJournal(io, home, { ...journal, phase: 'failed', updatedAt: new Date(options.now()).toISOString() });
@@ -49,8 +50,10 @@ export async function commitStagedRun(io, home, runId, port, options) {
         const finalize = transaction.finalize;
         if (finalize !== undefined) {
             const finalized = await finalize.call(transaction, unitId);
+            // The tree is already committed. Finalize is post-commit bookkeeping; failing it must
+            // not turn a landed merge into a failed run. Keep the receipt path alive and warn.
             if (!finalized.ok)
-                return { ok: false, message: 'unit committed but finalize failed: ' + finalized.message, plan: assembled.plan };
+                warning = 'commit landed but finalize failed: ' + finalized.message;
         }
         evidenceSha256 = digestEvidence(committed.evidence);
         result = { ok: true, message: 'merged', unitId, archived: committed.evidence.sources.filter(source => source.archived).map(source => source.name), mutations: committed.evidence.mutations };
@@ -73,7 +76,7 @@ export async function commitStagedRun(io, home, runId, port, options) {
         runId,
         ...(evidenceSha256 === undefined ? {} : { evidenceSha256 }),
         ...(options.validationPlan === undefined ? {} : { validationPlan: options.validationPlan }),
-        parentRunId: runId.split('/pairs/')[0] ?? runId,
+        ...(options.parentRunId === undefined ? {} : { parentRunId: options.parentRunId }),
         unitId: result.unitId,
         target: assembled.plan.target,
         create: !assembled.plan.targetExists,
@@ -88,14 +91,14 @@ export async function commitStagedRun(io, home, runId, port, options) {
             await io.remove(snapshotPath(home, runId));
         }
         catch { /* committed journal is the record */ }
-        return { ok: true, plan: assembled.plan, result, receipt };
+        return { ok: true, plan: assembled.plan, result, receipt, ...(warning === undefined ? {} : { warning }) };
     }
     catch (error) {
         return {
             ok: true,
             plan: assembled.plan,
             result,
-            warning: 'commit landed but receipt write failed: ' + (error instanceof Error ? error.message : String(error)),
+            warning: (warning === undefined ? '' : warning + '; ') + 'commit landed but receipt write failed: ' + (error instanceof Error ? error.message : String(error)),
         };
     }
 }

package/lib/types/commit-receipt.js

@@ -35,7 +35,9 @@ export async function writeCommitReceipt(io, home, receipt) {
     const path = commitReceiptPath(home, receipt.runId);
     await io.writeText(path, JSON.stringify(receipt, null, 2) + '\n');
     const parent = receipt.parentRunId ?? receipt.runId.split('/pairs/')[0] ?? receipt.runId;
-    await io.writeText(durableReceiptPath(home, parent, receipt.runId), JSON.stringify({ ...receipt, parentRunId: parent }, null, 2) + '\n');
+    // One durable file per unit: two pairs of the same run/target must not overwrite each other.
+    const leaf = (receipt.runId + '-' + receipt.unitId).replace(/[^A-Za-z0-9._-]+/g, '-');
+    await io.writeText(durableReceiptPath(home, parent, leaf), JSON.stringify({ ...receipt, parentRunId: parent }, null, 2) + '\n');
     return path;
 }
 export async function readCommitReceipts(io, home) {

package/lib/types/contracts.d.ts

@@ -57,6 +57,7 @@ export interface MergeDecision {
     readonly sources: readonly string[];
     readonly rationale: string;
     readonly confidence?: number;
+    readonly model?: string;
     readonly promptVersion?: string;
     readonly promptHash?: string;
     readonly aSummary?: string;
@@ -72,6 +73,7 @@ export interface MergeValidationPlanRef {
     readonly planVersion: 1;
     readonly stageDigest: string;
     readonly revision: string;
+    readonly manifestFiles?: readonly string[];
 }
 export interface MergeUsage {
     readonly inputTokens?: number;
@@ -108,7 +110,11 @@ export interface MergeReportPair {
     readonly lengths?: Readonly<Record<string, number>>;
     readonly timing?: MergeTiming;
     readonly validationPlan?: MergeValidationPlanRef;
+    readonly manifestFiles?: readonly string[];
     readonly criteria?: MergeCriteria;
+    readonly validation?: {
+        readonly issues: readonly MergeValidationIssue[];
+    };
     readonly reportOnly?: boolean;
 }
 export interface MergeCriteria {
@@ -118,6 +124,12 @@ export interface MergeCriteria {
     readonly archive: 'none' | 'sources';
     readonly evidence: 'none' | 'receipt';
 }
+export interface MergeValidationIssue {
+    readonly rule: string;
+    readonly path: string;
+    readonly severity: 'block' | 'warn';
+    readonly message: string;
+}
 export interface MergeReport {
     readonly schemaVersion: 2;
     readonly runId: string;
@@ -125,7 +137,7 @@ export interface MergeReport {
     readonly command: MergeRunCommand;
     readonly startedAt: number;
     readonly endedAt: number;
-    readonly stopReason: 'completed' | 'failed' | 'cancelled' | 'timeout';
+    readonly stopReason: 'completed' | 'failed' | 'cancelled' | 'timeout' | 'interrupted';
     readonly approval: {
         readonly platformWrite: boolean;
         readonly mergeApproval: boolean;
@@ -135,12 +147,19 @@ export interface MergeReport {
         readonly queueBefore: Record<MergeQueue, number>;
     };
     readonly pairs: readonly MergeReportPair[];
+    /** Backward-compatible alias; same objects as pairs[]. */
+    readonly processedPairs?: readonly MergeReportPair[];
     readonly totals: Record<'merged' | 'kept' | 'pending' | 'failed', number>;
     readonly notes: readonly string[];
     readonly remaining?: readonly {
         readonly pairKey: string;
         readonly queue: MergeQueue;
     }[];
+    /** Backward-compatible alias; same objects as remaining[]. */
+    readonly remainingPairs?: readonly {
+        readonly pairKey: string;
+        readonly queue: MergeQueue;
+    }[];
     readonly reportOnly?: readonly MergeReportPair[];
     readonly validationFailures?: readonly MergeReportPair[];
     readonly archived?: readonly string[];

package/lib/types/doctor.js

@@ -61,7 +61,7 @@ export async function mergeDoctor(io, home, configuredRoot) {
         key: 'state',
         label: '合并状态',
         status: snapshot.blocked === undefined || !hasState ? 'ok' : 'warn',
-        detail: snapshot.blocked === undefined ? 'pairs ' + String(snapshot.rows.length) + '；verify ' + String(counts.verify) + ' / pending ' + String(counts.pending) + ' / fuse ' + String(counts.fuse) + ' / skipped ' + String(counts.skipped) : snapshot.blocked.code + ': ' + snapshot.blocked.message,
+        detail: snapshot.blocked === undefined ? 'pairs ' + String(snapshot.rows.length) + '；verify ' + String(counts.verify) + ' / pending ' + String(counts.pending) + ' / fuse ' + String(counts.fuse) + ' / skipped ' + String(counts.skipped) + ' / expired ' + String(snapshot.doctor.counts.expired) : snapshot.blocked.code + ': ' + snapshot.blocked.message,
     });
     const recoveryRuns = new Set();
     try {

package/lib/types/domain/errors.js

@@ -1,8 +1,12 @@
 function redact(text) {
     return text
         .replace(/sk-[A-Za-z0-9_-]{16,}/g, '[redacted]')
+        .replace(/ghp_[A-Za-z0-9]{20,}/g, '[redacted]')
+        .replace(/github_pat_[A-Za-z0-9_]{20,}/g, '[redacted]')
+        .replace(/xox[baprs]-[A-Za-z0-9-]{10,}/g, '[redacted]')
+        .replace(/AKIA[0-9A-Z]{16}/g, '[redacted]')
         .replace(/Bearer\s+\S+/gi, 'Bearer [redacted]')
-        .replace(/(api[_-]?key\s*[:=]\s*)\S+/gi, '$1[redacted]');
+        .replace(/((?:api[_-]?key|token|password|secret)\s*[:=]\s*)\S+/gi, '$1[redacted]');
 }
 /** Build the typed failure every command/CLI/runtime branch returns. */
 export function commandError(stage, code, hint, next, runId) {

package/lib/types/domain/merge-snapshot.d.ts

@@ -4,15 +4,15 @@ import { type StageEntry } from './stage-aggregate.ts';
 import { type MergeRunMeta } from './run-coordinator.ts';
 import type { MergeReport } from '../contracts.ts';
 import type { V4Row } from './row-v4.ts';
-import { type LiveRowFacts, type PendingExpiryKind } from './live-facts.ts';
-import type { QueueId, MergeCounts, DoctorFact } from '../wire.ts';
+import { type LiveRowFacts } from './live-facts.ts';
+import type { QueueId, MergeCounts, DoctorFact, ExpiredKind } from '../wire.ts';
 export interface SnapshotRow {
     readonly row: V4Row;
     readonly stage: StageEntry | null;
     readonly bodies: readonly BodyRef[];
     readonly queue: QueueId;
     readonly expired: boolean;
-    readonly expiredKind?: PendingExpiryKind;
+    readonly expiredKind?: ExpiredKind;
 }
 export interface BodyRef {
     readonly rowId: string;
@@ -76,6 +76,10 @@ export interface MergeSnapshot {
     readonly history: readonly HistoryItem[];
     readonly bodyRefs: readonly BodyRef[];
     readonly doctor: SnapshotDoctor;
+    readonly hostOnly?: {
+        readonly code: 'E-323';
+        readonly detail?: string;
+    };
     readonly approval: {
         readonly mergeApproval: boolean;
         readonly platformWrite?: boolean;
@@ -89,6 +93,11 @@ export interface ReadSnapshotOptions {
     readonly runs: readonly RunRecord[];
     readonly approval: boolean;
     readonly platformWrite?: boolean;
+    /** Host data-plane capability probe; absent means available/unknown. */
+    readonly hostOnly?: () => Promise<{
+        readonly code: 'E-323';
+        readonly detail?: string;
+    } | undefined>;
     readonly now?: () => number;
     readonly history?: () => Promise<readonly HistoryItem[]>;
     readonly notes?: readonly string[];

package/lib/types/domain/merge-snapshot.js

@@ -13,9 +13,10 @@ const queueOf = (state) => state === 'approved' || state === 'fuse' ? 'fuse' : s
 export async function readMergeSnapshot(options) {
     const now = options.now ?? (() => Date.now());
     const readAt = now();
+    const hostOnly = options.hostOnly === undefined ? undefined : await options.hostOnly().catch((error) => ({ code: 'E-323', detail: error instanceof Error ? error.message : String(error) }));
     const readiness = await readV4Readiness(options.io, options.home);
     if (!readiness.ok) {
-        return { wireVersion: 1, schemaVersion: 4, readAt, queueRevision: 'blocked', consistency: 'eventual', blocked: { code: readiness.code, message: readiness.message, readiness }, rows: [], stages: [], runs: [], reports: [], report: null, history: [], bodyRefs: [], doctor: { counts: emptyCounts, staging: { state: 'absent', dirs: 0 }, rows: [] }, approval: { mergeApproval: options.approval, ...(options.platformWrite === undefined ? {} : { platformWrite: options.platformWrite }) }, notes: options.notes ?? [], degraded: true };
+        return { wireVersion: 1, schemaVersion: 4, readAt, queueRevision: 'blocked', consistency: 'eventual', ...(hostOnly === undefined ? {} : { hostOnly }), blocked: { code: readiness.code, message: readiness.message, readiness }, rows: [], stages: [], runs: [], reports: [], report: null, history: [], bodyRefs: [], doctor: { counts: emptyCounts, staging: { state: 'absent', dirs: 0 }, rows: [] }, approval: { mergeApproval: options.approval, ...(options.platformWrite === undefined ? {} : { platformWrite: options.platformWrite }) }, notes: options.notes ?? [], degraded: true };
     }
     const ledger = await readPairLedgerV4(options.io, options.home);
     // Read-time derivation only: a stage past its TTL reads as expired even when the
@@ -31,8 +32,12 @@ export async function readMergeSnapshot(options) {
     for (const row of ledger?.rows ?? []) {
         const stage = stages.find(item => item.rowId === row.id) ?? null;
         const queue = queueOf(row.state);
-        const bodies = [{ rowId: row.id, name: row.a, side: 'live' }, { rowId: row.id, name: row.b, side: 'archive' }];
-        const expiredKind = persistedExpiry(row) ?? pendingExpiry(row, live);
+        // A row's b is a live source until it is actually archived; only then is the archive
+        // body the addressable one. Pending/fuse/verify rows therefore expose two live bodies.
+        const bSide = live !== undefined && live.managed(row.b) ? 'live' : 'archive';
+        const bodies = [{ rowId: row.id, name: row.a, side: 'live' }, { rowId: row.id, name: row.b, side: bSide }];
+        const skippedExpired = row.state === 'skipped' && row.expiredAt !== undefined;
+        const expiredKind = skippedExpired ? 'skipped-ttl' : persistedExpiry(row) ?? pendingExpiry(row, live);
         rows.push({ row, stage, bodies, queue, expired: expiredKind !== null, ...(expiredKind === null ? {} : { expiredKind }) });
         bodyRefs.push(...bodies);
     }
@@ -69,7 +74,7 @@ export async function readMergeSnapshot(options) {
         && rows.some(item => item.row.pairKey === entry.pairKey && (item.row.state === 'verify' || item.row.state === 'pending' || item.row.state === 'approved' || item.row.state === 'fuse')));
     if (ledgerConflicts.length > 0)
         notes.push('ledger-conflict: pair-index says completed but the ledger still has it active (' + String(ledgerConflicts.length) + ')');
-    return { wireVersion: 1, schemaVersion: 4, readAt, queueRevision, consistency: 'eventual', rows, stages, runs, reports, report: reports.at(-1)?.report ?? null, history, bodyRefs, doctor, approval: { mergeApproval: options.approval, ...(options.platformWrite === undefined ? {} : { platformWrite: options.platformWrite }) }, notes, degraded: notes.length > 0 };
+    return { wireVersion: 1, schemaVersion: 4, readAt, queueRevision, consistency: 'eventual', ...(hostOnly === undefined ? {} : { hostOnly }), rows, stages, runs, reports, report: reports.at(-1)?.report ?? null, history, bodyRefs, doctor, approval: { mergeApproval: options.approval, ...(options.platformWrite === undefined ? {} : { platformWrite: options.platformWrite }) }, notes, degraded: notes.length > 0 };
 }
 async function readHistory(io, home) {
     const receipts = await readCommitReceipts(io, home);

package/lib/types/domain/reconcile.js

@@ -106,7 +106,7 @@ export async function reconcileMergeState(options) {
                 continue;
             const entry = byRow.get(row.id);
             if (usable.get(row.id) === true) {
-                const moved = tx.transition(row.id, { type: 'staged' }, current.version);
+                const moved = tx.transition(row.id, { type: 'staged', ...(entry === undefined ? {} : { stagingRef: entry.ref, stagingExpiresAt: entry.expiresAt }) }, current.version);
                 if (moved.ok) {
                     actions.push({ kind: 'approved-fused', rowId: row.id, from: 'approved', to: 'fuse', code: 'stage-present' });
                     if (entry !== undefined && entry.state === 'reserved')

package/lib/types/domain/row-v4.d.ts

@@ -49,6 +49,8 @@ export interface FuseRowV4 extends RowBaseV4 {
     readonly sourceRevision?: string;
     readonly targetRevision?: string;
     readonly runId?: string;
+    readonly stagingRef?: string;
+    readonly stagingExpiresAt?: number;
     readonly attempts: number;
 }
 export interface SkippedRowV4 extends RowBaseV4 {
@@ -76,6 +78,8 @@ export type V4Event = {
     readonly runId?: string;
 } | {
     readonly type: 'staged';
+    readonly stagingRef?: string;
+    readonly stagingExpiresAt?: number;
 } | {
     readonly type: 'committed';
     readonly unitId: CommitUnitRef;

package/lib/types/domain/row-v4.js

@@ -24,7 +24,7 @@ export function transitionV4(row, event, expectedVersion, at = new Date().toISOS
             if (event.type === 'auto-approved')
                 return { ok: true, row: advance(row, at, { state: 'approved', ...(event.runId === undefined ? {} : { runId: event.runId }) }), version: expectedVersion + 1 };
             if (event.type === 'staged')
-                return { ok: true, row: advance(row, at, { state: 'fuse' }), version: expectedVersion + 1 };
+                return { ok: true, row: advance(row, at, { state: 'fuse', ...(event.stagingRef === undefined ? {} : { stagingRef: event.stagingRef }), ...(event.stagingExpiresAt === undefined ? {} : { stagingExpiresAt: event.stagingExpiresAt }) }), version: expectedVersion + 1 };
             if (event.type === 'skipped')
                 return { ok: true, row: advance(row, at, { state: 'skipped', reason: event.reason, ...(event.origin === undefined ? {} : { origin: event.origin }), ...(event.skipSource === undefined ? {} : { skipSource: event.skipSource }) }), version: expectedVersion + 1 };
             if (event.type === 'expired')
@@ -36,15 +36,15 @@ export function transitionV4(row, event, expectedVersion, at = new Date().toISOS
             return illegal('pending/' + event.type);
         case 'approved':
             if (event.type === 'staged')
-                return { ok: true, row: advance(row, at, { state: 'fuse' }), version: expectedVersion + 1 };
+                return { ok: true, row: advance(row, at, { state: 'fuse', ...(event.stagingRef === undefined ? {} : { stagingRef: event.stagingRef }), ...(event.stagingExpiresAt === undefined ? {} : { stagingExpiresAt: event.stagingExpiresAt }) }), version: expectedVersion + 1 };
             if (event.type === 'committed')
                 return { ok: true, row: null, version: expectedVersion + 1 };
             if (event.type === 'skipped')
                 return { ok: true, row: advance(row, at, { state: 'skipped', reason: event.reason, ...(event.skipSource === undefined ? {} : { skipSource: event.skipSource }) }), version: expectedVersion + 1 };
+            // A failure is never a "no merge" decision. Keep the row in fuse with the failure
+            // recorded; retryable is a property of the failure, not a different queue.
             if (event.type === 'failed')
-                return event.failure.retryable
-                    ? { ok: true, row: advance(row, at, { state: 'fuse', failure: event.failure, attempts: row.attempts + 1 }), version: expectedVersion + 1 }
-                    : { ok: true, row: advance(row, at, { state: 'skipped', reason: event.failure.code, failure: event.failure, attempts: row.attempts + 1 }), version: expectedVersion + 1 };
+                return { ok: true, row: advance(row, at, { state: 'fuse', failure: event.failure, attempts: row.attempts + 1 }), version: expectedVersion + 1 };
             if (event.type === 'superseded')
                 return { ok: true, row: null, version: expectedVersion + 1 };
             return illegal('approved/' + event.type);
@@ -54,9 +54,7 @@ export function transitionV4(row, event, expectedVersion, at = new Date().toISOS
             if (event.type === 'skipped')
                 return { ok: true, row: advance(row, at, { state: 'skipped', reason: event.reason, ...(event.skipSource === undefined ? {} : { skipSource: event.skipSource }) }), version: expectedVersion + 1 };
             if (event.type === 'failed')
-                return event.failure.retryable
-                    ? { ok: true, row: advance(row, at, { state: 'fuse', failure: event.failure, attempts: row.attempts + 1 }), version: expectedVersion + 1 }
-                    : { ok: true, row: advance(row, at, { state: 'skipped', reason: event.failure.code, failure: event.failure, attempts: row.attempts + 1 }), version: expectedVersion + 1 };
+                return { ok: true, row: advance(row, at, { state: 'fuse', failure: event.failure, attempts: row.attempts + 1 }), version: expectedVersion + 1 };
             if (event.type === 'superseded')
                 return { ok: true, row: null, version: expectedVersion + 1 };
             return illegal('fuse/' + event.type);
@@ -97,7 +95,7 @@ export function v3ToV4(row) {
     if (row.state === 'approved')
         return { ...base, state: 'approved', target: row.target, decision: row.decision, ...(row.sourceRevision === undefined ? {} : { sourceRevision: row.sourceRevision }), ...(row.runId === undefined ? {} : { runId: row.runId }) };
     if (row.state === 'fuse')
-        return { ...base, state: 'fuse', target: row.target, decision: row.decision, ...(row.sourceRevision === undefined ? {} : { sourceRevision: row.sourceRevision }), ...(row.runId === undefined ? {} : { runId: row.runId }) };
+        return { ...base, state: 'fuse', target: row.target, decision: row.decision, ...(row.sourceRevision === undefined ? {} : { sourceRevision: row.sourceRevision }), ...(row.runId === undefined ? {} : { runId: row.runId }), ...(row.staging?.kind === 'present' ? { stagingRef: row.staging.ref, stagingExpiresAt: row.staging.expiresAt } : row.staging?.kind === 'expired' && row.staging.ref !== undefined ? { stagingRef: row.staging.ref, stagingExpiresAt: row.staging.expiresAt } : {}) };
     return { ...base, state: 'skipped', reason: row.reason, ...(row.expiredAt === undefined ? {} : { expiredAt: row.expiredAt }) };
 }
 export function applyV4Write(rows, write, at) {
@@ -151,6 +149,8 @@ export function v4ToLegacy(row) {
         ...((row.state === 'pending' || row.state === 'approved' || row.state === 'fuse') && row.sourceRevision !== undefined ? { sourceRevision: row.sourceRevision } : {}),
         ...((row.state === 'pending' || row.state === 'approved' || row.state === 'fuse') && row.targetRevision !== undefined ? { targetRevision: row.targetRevision } : {}),
         ...(row.runId === undefined ? {} : { runId: row.runId }),
+        ...(row.state === 'fuse' && row.stagingRef !== undefined ? { stagingRef: row.stagingRef } : {}),
+        ...(row.state === 'fuse' && row.stagingExpiresAt !== undefined ? { stagingExpiresAt: row.stagingExpiresAt } : {}),
         ...(row.origin === undefined ? {} : { origin: row.origin }),
         ...(row.attempts === undefined ? {} : { attempts: row.attempts }),
         createdAt: row.createdAt, updatedAt: row.updatedAt,

package/lib/types/domain/run-coordinator.d.ts

@@ -6,7 +6,16 @@ export interface MergeRunMeta {
     readonly pairCount?: number;
     /** The pair a single-pair command (pair/approve/resume) is working on; absent for scan. */
     readonly pairKey?: string;
+    /** Staging tree this run authors/commits; absent for scan before staging. */
+    readonly stagingRef?: string;
+    /** Pair rows this run claims, when it is a single-pair command. */
+    readonly pairs?: readonly {
+        readonly pairKey: string;
+        readonly state: 'pending' | 'approved' | 'fused' | 'skipped';
+    }[];
     readonly parentRunId?: string;
+    /** Owner process; lets a shared run-meta distinguish a live foreign plane from a dead writer. */
+    readonly pid?: number;
     readonly phase: MergeRunPhase;
     readonly stopReason?: string;
     readonly approval?: 'pending' | 'approved' | 'rejected';

package/lib/types/domain/stage-aggregate.d.ts

@@ -80,12 +80,17 @@ export declare function readStageIndex(io: EvolutionIoLike, home: string, rowId:
 export declare function readStageEntry(io: EvolutionIoLike, home: string, rowId: string): Promise<StageEntry | null>;
 export declare function reserveStage(io: EvolutionIoLike, home: string, entry: StageEntry): Promise<void>;
 export declare function presentStage(io: EvolutionIoLike, home: string, entry: StageEntry): Promise<void>;
-export declare function dropStage(io: EvolutionIoLike, home: string, rowId: string, ref?: string): Promise<void>;
+export declare function dropStage(io: EvolutionIoLike, home: string, rowId: string, ref?: string, onError?: (path: string, error: unknown) => void): Promise<void>;
+export interface StageCleanupFailure {
+    readonly path: string;
+    readonly message: string;
+}
 export interface StageCleanupResult {
     readonly removed: readonly string[];
     readonly expired: readonly string[];
     readonly kept: readonly string[];
     readonly orphans: readonly string[];
+    readonly failures: readonly StageCleanupFailure[];
 }
 /** Bounded cleanup: reserved/present TTL, pending/verify stale index removal, terminal/absent rows, orphan trees. */
 export declare function cleanupStage(io: EvolutionIoLike, home: string, now: number, rows: ReadonlyMap<string, {

package/lib/types/domain/stage-aggregate.js

@@ -205,10 +205,13 @@ export async function reserveStage(io, home, entry) {
 export async function presentStage(io, home, entry) {
     await writeStageIndex(io, home, { rowId: entry.rowId, pairKey: entry.pairKey, ref: entry.ref, expiresAt: entry.expiresAt, ...(entry.runId === undefined ? {} : { runId: entry.runId }), createdAt: entry.createdAt, state: 'present' });
 }
-export async function dropStage(io, home, rowId, ref) {
-    await io.remove(join(home, 'merge', 'staging-index', encodeURIComponent(rowId) + '.json')).catch(() => { });
-    if (ref !== undefined && ref !== '')
-        await io.remove(join(home, 'merge', 'runs', ref)).catch(() => { });
+export async function dropStage(io, home, rowId, ref, onError) {
+    const index = join(home, 'merge', 'staging-index', encodeURIComponent(rowId) + '.json');
+    await io.remove(index).catch(error => onError?.(index, error));
+    if (ref !== undefined && ref !== '') {
+        const tree = join(home, 'merge', 'runs', ref);
+        await io.remove(tree).catch(error => onError?.(tree, error));
+    }
 }
 /** Bounded cleanup: reserved/present TTL, pending/verify stale index removal, terminal/absent rows, orphan trees. */
 export async function cleanupStage(io, home, now, rows, limit = 100) {
@@ -216,6 +219,8 @@ export async function cleanupStage(io, home, now, rows, limit = 100) {
     const expired = [];
     const kept = [];
     const orphans = [];
+    const failures = [];
+    const fail = (path, error) => { failures.push({ path, message: error instanceof Error ? error.message : String(error) }); };
     const refs = new Set();
     const indexRoot = join(home, 'merge', 'staging-index');
     const names = await io.exists(indexRoot) ? await listOrEmpty(io, indexRoot) : [];
@@ -239,7 +244,7 @@ export async function cleanupStage(io, home, now, rows, limit = 100) {
         const row = rows.get(entry.rowId);
         const terminal = row === undefined || row.state === 'skipped';
         if (terminal || row?.state === 'pending' || row?.state === 'verify') {
-            await dropStage(io, home, entry.rowId, entry.ref);
+            await dropStage(io, home, entry.rowId, entry.ref, fail);
             removed.push(entry.rowId);
             continue;
         }
@@ -250,11 +255,13 @@ export async function cleanupStage(io, home, now, rows, limit = 100) {
                 try {
                     await writeStagingIndex(io, home, { rowId: entry.rowId, pairKey: typeof entry.pairKey === 'string' ? entry.pairKey : '', ref: entry.ref, expiresAt: entry.expiresAt, createdAt: typeof entry.createdAt === 'number' ? entry.createdAt : now, state: 'expired' });
                 }
-                catch { /* the read face still derives expired */ }
+                catch (error) { /* the read face still derives expired; visibility is still required */
+                    fail(join(indexRoot, name), error);
+                }
                 expired.push(entry.rowId);
                 continue;
             }
-            await dropStage(io, home, entry.rowId, entry.ref);
+            await dropStage(io, home, entry.rowId, entry.ref, fail);
             removed.push(entry.rowId);
             continue;
         }
@@ -266,10 +273,10 @@ export async function cleanupStage(io, home, now, rows, limit = 100) {
         const prefix = run + '/';
         if ([...refs].some(ref => ref === run || ref.startsWith(prefix)))
             continue;
-        await io.remove(join(runRoot, run)).catch(() => { });
+        await io.remove(join(runRoot, run)).catch(error => fail(join(runRoot, run), error));
         orphans.push(run);
     }
-    return { removed, expired, kept, orphans };
+    return { removed, expired, kept, orphans, failures };
 }
 /** Read all production v2 stage entries. */
 export async function readAllStages(io, home) {

package/lib/types/domain/validation-plan.js

@@ -14,7 +14,11 @@ export function buildValidationPlan(input) {
     const existing = new Set(input.existingSupport ?? []);
     const orphanFiles = [...existing].filter(path => !staged.has(path)).sort();
     const byPath = new Map();
-    for (const file of input.supportSources ?? []) {
+    // Conflict means TWO SKILLS contributing different bytes at one path. Staged edits and
+    // the target's previous file are not conflicts: the target file is a CAS baseline that
+    // round 2 is expected to update, so including either here would block every support edit.
+    const supportSources = input.supportSources ?? [];
+    for (const file of supportSources) {
         const entry = byPath.get(file.path) ?? { contents: new Set(), sources: [] };
         entry.contents.add(file.content);
         entry.sources.push(file.source);

package/lib/types/host-capabilities.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The host's data-plane capability as ONE value shared by snapshot, doctor, HTTP and run preflight.
+ * The probe is injected so the Cordis wiring stays in index.ts; a rejected probe is the same E-323
+ * answer as an unavailable one, never an unhandled promise.
+ * @module @lmzhen/dsh-evolution-merge
+ */
+/** The one unavailable answer the merge surface understands. */
+export interface HostOnlyUnavailable {
+    readonly code: 'E-323';
+    readonly detail?: string;
+}
+/** A host capability probe; undefined means the data plane is usable. */
+export interface HostCapabilities {
+    readonly hostOnly: () => Promise<HostOnlyUnavailable | undefined>;
+}
+/**
+ * Wrap one probe with the shared error normalization.
+ * @param probe - the platform-specific availability check.
+ * @returns the capability value consumed by snapshot and runtime.
+ */
+export declare function createHostCapabilities(probe: () => Promise<HostOnlyUnavailable | undefined>): HostCapabilities;
+//# sourceMappingURL=host-capabilities.d.ts.map