@lmzhen/dsh-evolution-merge 0.30.23 → 0.30.25

package/lib/types/kernel/recovery.d.ts

@@ -0,0 +1,31 @@
+/** Pure recovery planner and timeout decision. No IO. */
+import type { CommitReceipt } from './model.ts';
+export type RecoveryDecision = {
+    readonly kind: 'retry';
+    readonly reason: 'no-intent';
+} | {
+    readonly kind: 'committed';
+    readonly receipt: CommitReceipt;
+} | {
+    readonly kind: 'roll-forward';
+    readonly reason: 'effects-complete' | 'after-hash-matches';
+} | {
+    readonly kind: 'abort';
+    readonly reason: 'no-effects' | 'before-hash-matches';
+} | {
+    readonly kind: 'blocked';
+    readonly reason: 'partial-effects';
+};
+export interface RecoveryObservation {
+    readonly hasIntent: boolean;
+    readonly hasReceipt: boolean;
+    readonly receipt?: CommitReceipt;
+    readonly beforeMatches: boolean;
+    readonly afterMatches: boolean;
+    readonly effects: 'none' | 'partial' | 'complete';
+}
+export declare function planRecovery(observation: RecoveryObservation): RecoveryDecision;
+export type TimeoutDecision = 'failed' | 'unknown';
+/** Before a durable intent, timeout is a normal failed run; after it, only recovery may decide. */
+export declare function timeoutDecision(unitPrepared: boolean): TimeoutDecision;
+//# sourceMappingURL=recovery.d.ts.map

package/lib/types/kernel/recovery.js

@@ -0,0 +1,19 @@
+export function planRecovery(observation) {
+    if (observation.hasReceipt) {
+        if (observation.receipt === undefined)
+            return { kind: 'blocked', reason: 'partial-effects' };
+        return { kind: 'committed', receipt: observation.receipt };
+    }
+    if (!observation.hasIntent)
+        return { kind: 'retry', reason: 'no-intent' };
+    if (observation.effects === 'complete' || observation.afterMatches)
+        return { kind: 'roll-forward', reason: observation.effects === 'complete' ? 'effects-complete' : 'after-hash-matches' };
+    if (observation.effects === 'none' || observation.beforeMatches)
+        return { kind: 'abort', reason: observation.effects === 'none' ? 'no-effects' : 'before-hash-matches' };
+    return { kind: 'blocked', reason: 'partial-effects' };
+}
+/** Before a durable intent, timeout is a normal failed run; after it, only recovery may decide. */
+export function timeoutDecision(unitPrepared) {
+    return unitPrepared ? 'unknown' : 'failed';
+}
+//# sourceMappingURL=recovery.js.map

package/lib/types/kernel/unit.d.ts

@@ -0,0 +1,43 @@
+/** Pure unit-of-work protocol: intent -> applied -> committed, with recovery states. */
+import type { CommitReceipt } from './model.ts';
+export type UnitState = 'planned' | 'prepared' | 'applied' | 'committed' | 'aborted' | 'blocked';
+export interface UnitSnapshot {
+    readonly unitId: string;
+    readonly state: UnitState;
+    readonly version: number;
+    readonly planHash: string;
+    readonly receipt?: CommitReceipt;
+    readonly reason?: string;
+}
+export type UnitEvent = {
+    readonly type: 'prepare';
+    readonly planHash: string;
+} | {
+    readonly type: 'applied';
+} | {
+    readonly type: 'commit';
+    readonly receipt: CommitReceipt;
+} | {
+    readonly type: 'abort';
+    readonly reason: string;
+} | {
+    readonly type: 'block';
+    readonly reason: string;
+} | {
+    readonly type: 'recover-commit';
+    readonly receipt: CommitReceipt;
+} | {
+    readonly type: 'recover-abort';
+    readonly reason: string;
+};
+export type UnitTransition = {
+    readonly ok: true;
+    readonly snapshot: UnitSnapshot;
+} | {
+    readonly ok: false;
+    readonly code: 'illegal-transition' | 'version-conflict' | 'invalid-event';
+    readonly message: string;
+};
+export declare function transitionUnit(snapshot: UnitSnapshot, event: UnitEvent, expectedVersion: number): UnitTransition;
+export declare function checkUnit(snapshot: UnitSnapshot): string[];
+//# sourceMappingURL=unit.d.ts.map

package/lib/types/kernel/unit.js

@@ -0,0 +1,63 @@
+function fail(code, message) {
+    return { ok: false, code, message };
+}
+function next(snapshot, state, patch = {}) {
+    return { ...snapshot, state, version: snapshot.version + 1, ...patch };
+}
+export function transitionUnit(snapshot, event, expectedVersion) {
+    if (snapshot.version !== expectedVersion)
+        return fail('version-conflict', 'expected ' + String(expectedVersion) + ', got ' + String(snapshot.version));
+    switch (event.type) {
+        case 'prepare':
+            if (snapshot.state !== 'planned')
+                return fail('illegal-transition', 'prepare from ' + snapshot.state);
+            if (event.planHash.length === 0)
+                return fail('invalid-event', 'planHash is required');
+            return { ok: true, snapshot: next(snapshot, 'prepared', { planHash: event.planHash }) };
+        case 'applied':
+            return snapshot.state === 'prepared' ? { ok: true, snapshot: next(snapshot, 'applied') } : fail('illegal-transition', 'applied from ' + snapshot.state);
+        case 'commit':
+            if (snapshot.state !== 'applied')
+                return fail('illegal-transition', 'commit from ' + snapshot.state);
+            if (event.receipt.unitId.length === 0)
+                return fail('invalid-event', 'receipt.unitId is required');
+            return { ok: true, snapshot: next(snapshot, 'committed', { receipt: event.receipt }) };
+        case 'abort':
+            return snapshot.state === 'planned' || snapshot.state === 'prepared' || snapshot.state === 'applied'
+                ? { ok: true, snapshot: next(snapshot, 'aborted', { reason: event.reason }) }
+                : fail('illegal-transition', 'abort from ' + snapshot.state);
+        case 'block':
+            return snapshot.state === 'prepared' || snapshot.state === 'applied'
+                ? { ok: true, snapshot: next(snapshot, 'blocked', { reason: event.reason }) }
+                : fail('illegal-transition', 'block from ' + snapshot.state);
+        case 'recover-commit':
+            if (snapshot.state !== 'blocked')
+                return fail('illegal-transition', 'recover-commit from ' + snapshot.state);
+            return { ok: true, snapshot: next(snapshot, 'committed', { receipt: event.receipt }) };
+        case 'recover-abort':
+            return snapshot.state === 'blocked'
+                ? { ok: true, snapshot: next(snapshot, 'aborted', { reason: event.reason }) }
+                : fail('illegal-transition', 'recover-abort from ' + snapshot.state);
+        default:
+            return fail('invalid-event', 'unknown unit event');
+    }
+}
+export function checkUnit(snapshot) {
+    const problems = [];
+    if (snapshot.unitId.length === 0)
+        problems.push('unitId is empty');
+    if (snapshot.planHash.length === 0)
+        problems.push('planHash is empty');
+    if (!Number.isInteger(snapshot.version) || snapshot.version < 0)
+        problems.push('version must be a non-negative integer');
+    if (snapshot.state === 'committed' && snapshot.receipt === undefined)
+        problems.push('committed requires a receipt');
+    if (snapshot.state === 'blocked' && snapshot.reason === undefined)
+        problems.push('blocked requires a reason');
+    if (snapshot.state === 'aborted' && snapshot.reason === undefined)
+        problems.push('aborted requires a reason');
+    if (snapshot.receipt !== undefined && snapshot.receipt.unitId !== snapshot.unitId)
+        problems.push('receipt.unitId must equal unitId');
+    return problems;
+}
+//# sourceMappingURL=unit.js.map

package/lib/types/merge-routes.js

@@ -13,6 +13,7 @@ export const MERGE_ROUTES = {
 export function makeMergeRoutes(deps, _audit) {
     const absent = () => json(404, { wireVersion: 1, code: 'E-325', message: 'merge service is not mounted' });
     const blocked = (readiness) => json(503, { wireVersion: 1, code: 'merge-state-blocked', readiness });
+    const hostOnly = (snapshot) => snapshot.hostOnly === undefined ? null : json(503, { wireVersion: 1, code: 'E-323', message: snapshot.hostOnly.detail ?? 'host data plane unavailable' });
     const notReady = async (source) => {
         if (source.readiness === undefined)
             return null;
@@ -38,6 +39,9 @@ export function makeMergeRoutes(deps, _audit) {
                     const snapshot = await source.snapshot();
                     if (snapshot.blocked !== undefined)
                         return json(503, { wireVersion: 1, code: 'merge-state-blocked', readiness: snapshot.blocked.readiness });
+                    const capability = hostOnly(snapshot);
+                    if (capability !== null)
+                        return capability;
                     return json(200, buildSnapshotFacts(snapshot));
                 }
                 const readiness = await notReady(source);
@@ -72,6 +76,9 @@ export function makeMergeRoutes(deps, _audit) {
                     const snapshot = await source.snapshot();
                     if (snapshot.blocked !== undefined)
                         return json(503, { wireVersion: 1, code: 'merge-state-blocked', readiness: snapshot.blocked.readiness });
+                    const capability = hostOnly(snapshot);
+                    if (capability !== null)
+                        return capability;
                     try {
                         return json(200, buildQueuePage(snapshot, queue, expiredOnly, query.get('cursor') ?? undefined, Number.isFinite(limit) ? limit : 50));
                     }
@@ -111,6 +118,8 @@ export function makeMergeRoutes(deps, _audit) {
                     const snapshot = await source.snapshot();
                     if (snapshot.blocked !== undefined)
                         return json(503, { wireVersion: 1, code: 'merge-state-blocked', readiness: snapshot.blocked.readiness });
+                    // Body/history are read-only projections of already-written files; a host without
+                    // the live agent data plane can still read past reports and archived bodies.
                     const refs = id !== null && id !== '' ? snapshot.bodyRefs.filter(ref => ref.rowId === id) : snapshot.bodyRefs.filter(ref => ref.name === name);
                     if (refs.length === 0)
                         return json(404, { wireVersion: 1, code: 'merge-body-not-found', message: 'merge body not found' });

package/lib/types/new-child-authoring.d.ts

@@ -26,6 +26,7 @@ export interface NewChildAuthoringOptions {
     readonly onChildClosed?: (childId: string) => void;
     readonly unit?: UnitTransaction | undefined;
     readonly limits?: import('@lmzhen/dsh-evolution-core').SkillLimits;
+    readonly parentRunId?: string | ((runId: string) => string | undefined);
 }
 export declare function runNewChildAuthoring(options: NewChildAuthoringOptions, row: MergeRow, decision: MergeDecision, signal: AbortSignal): Promise<ScanRound2Outcome>;
 /** Bind the round-2 port to one run: approve/resume open a NEW child per run. */

package/lib/types/new-child-authoring.js

@@ -90,23 +90,26 @@ export async function runNewChildAuthoring(options, row, decision, signal) {
         if (missing !== null)
             return { kind: 'failed', failure: { stage: 'author', code: 'merge-manifest-missing', message: 'manifest file missing from staged tree: ' + missing, retryable: true, retryFrom: 'agent2' } };
         const limitsSnapshot = limitsSnapshotOf(options.limits ?? DEFAULT_SKILL_LIMITS);
-        const validationPlan = buildValidationPlan({ tree: tree.value, target: decision.target, limits: limitsSnapshot, cards: options.cards, promptVersion: MERGE_PROMPT_VERSION, promptHash: promptHashOf(buildRound2Prompt(row, decision)), supportFiles: tree.value.files.map(file => ({ path: file.path, content: file.content, source: 'staged' })), manifestFiles, existingSupport: (options.cards.find(card => card.name === decision.target)?.files ?? []).map(file => file.path), 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: decision.target, limits: limitsSnapshot, cards: options.cards, promptVersion: MERGE_PROMPT_VERSION, promptHash: promptHashOf(buildRound2Prompt(row, decision)), supportFiles: tree.value.files.map(file => ({ path: file.path, content: file.content, source: 'staged' })), manifestFiles, existingSupport: (options.cards.find(card => card.name === decision.target)?.files ?? []).map(file => file.path), supportSources: options.cards.filter(card => card.name === row.a || card.name === row.b).flatMap(card => (card.files ?? []).map(file => ({ path: file.path, content: file.content, source: card.name }))) });
         const findings = [...validateStagedTree(tree.value, limitsSnapshot.skillLimits), ...validationPlan.findings];
         if (hasBlockingFinding(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) };
-            // FR-EXEC-11/14: only a LIMIT finding is over-limit; every other blocking rule
-            // (manifest mismatch, support conflict, validation plan) is a validation block and
-            // must land in skipped, not bounce back to fuse as a retryable generic failure.
+            // FR-EXEC-11/14: only a LIMIT finding is over-limit (a policy close); every other
+            // blocking rule (manifest mismatch, support conflict, validation plan) is a
+            // validation failure that goes to the report as failed, never to skipped.
             const limit = findings.find(finding => finding.rule === 'limit');
+            const plan = { planVersion: validationPlan.planVersion, stageDigest: validationPlan.stageDigest, revision: validationPlan.revision, manifestFiles: validationPlan.manifestFiles };
             return limit === undefined
-                ? { kind: 'failed', failure: { stage: 'validate', code: 'merge-validation', message: 'staged tree failed the rule gate', retryable: false, retryFrom: 'none' } }
-                : { kind: 'failed', failure: { stage: 'validate', code: 'merge-over-limit', message: limit.message, retryable: false, retryFrom: 'none', lengths } };
+                ? { kind: 'failed', failure: { stage: 'validate', code: 'merge-validation', message: 'staged tree failed the rule gate', retryable: false, retryFrom: 'none' }, validationPlan: plan, manifestFiles: validationPlan.manifestFiles, validationIssues: findings, criteria: { decision: 'merge', validation: 'required', commit: 'never', archive: 'none', evidence: 'none' } }
+                : { kind: 'failed', failure: { stage: 'validate', code: 'merge-over-limit', message: limit.message, retryable: false, retryFrom: 'none', lengths }, validationPlan: plan, manifestFiles: validationPlan.manifestFiles, validationIssues: findings, criteria: { decision: 'merge', validation: 'required', commit: 'never', archive: 'none', evidence: 'none' } };
         }
+        const parentRunId = typeof options.parentRunId === 'function' ? options.parentRunId(options.runId) : options.parentRunId;
         const commit = await commitStagedRun(options.io, options.home, stageKey, options.commitPort, {
-            origin: 'foreground', summary: 'merge ' + row.a + ' + ' + row.b, now: options.now,
+            origin: 'foreground', summary: 'merge ' + row.a + ' + ' + row.b, now: options.now, signal,
             ...(options.isBlocked === undefined ? {} : { isBlocked: options.isBlocked }),
             ...(options.unit === undefined ? {} : { unit: options.unit }),
             ...(options.limits === undefined ? {} : { limits: options.limits }),
+            ...(parentRunId === undefined ? {} : { parentRunId }),
             validationPlan: { planVersion: validationPlan.planVersion, stageDigest: validationPlan.stageDigest, revision: validationPlan.revision },
             ...(decision.targetRevisionRef === undefined ? {} : { targetRevision: decision.targetRevisionRef }),
             ...(decision.sourceRevisions === undefined ? {} : { sourceRevisions: decision.sourceRevisions }),
@@ -123,6 +126,11 @@ export async function runNewChildAuthoring(options, row, decision, signal) {
             ...(receipt?.unitId === undefined ? {} : { unitId: receipt.unitId }),
             archived: receipt?.archived ?? [],
             lengths,
+            validationPlan: { planVersion: validationPlan.planVersion, stageDigest: validationPlan.stageDigest, revision: validationPlan.revision, manifestFiles: validationPlan.manifestFiles },
+            ...(parentRunId === undefined ? {} : { parentRunId }),
+            manifestFiles: validationPlan.manifestFiles,
+            validationIssues: findings,
+            criteria: { decision: 'merge', validation: 'required', commit: 'required', archive: 'sources', evidence: 'receipt' },
             target: { requested: decision.target, actual: commit.plan.target, created: receipt?.create ?? false },
         };
     }

package/lib/types/pending-actions.d.ts

@@ -9,7 +9,7 @@ export type PendingActionResult = {
     readonly row: MergeRow;
 } | {
     readonly ok: false;
-    readonly reason: 'not-found' | 'not-pending' | 'invalid';
+    readonly reason: 'not-found' | 'not-pending' | 'invalid' | 'expired';
     readonly message: string;
 };
 export declare function approvePending(io: EvolutionIoLike, home: string, now: () => number, id: string): Promise<PendingActionResult>;

package/lib/types/pending-actions.js

@@ -8,6 +8,10 @@ async function act(io, home, now, id, type) {
             return { ok: false, reason: 'not-found', message: 'pending row not found: ' + id };
         if (row.state !== 'pending')
             return { ok: false, reason: 'not-pending', message: 'row is not pending: ' + row.state };
+        // Expired pending rows are read-only until discarded or re-paired; approve/reject would
+        // resurrect a target/source decision that reconcile already invalidated.
+        if (row.expired !== undefined)
+            return { ok: false, reason: 'expired', message: 'pending row expired (' + row.expired + '): only discard or re-pair' };
         const event = type === 'approve'
             ? { type: 'approved', runId: row.runId ?? 'approve:' + id }
             : { type: 'skipped', reason: 'rejected', origin: 'human' };

package/lib/types/recovery-coordinator.d.ts

@@ -6,6 +6,8 @@ export interface RecoveryReport {
     readonly phase: string;
     readonly branch: RecoveryBranch;
     readonly action: 'rollback' | 'rollForward' | 'finalize' | 'blocked' | 'none';
+    /** Branch D proves the unit committed after the process died; the run was interrupted, not cleanly completed. */
+    readonly state?: 'interrupted';
     readonly ok: boolean;
     readonly code?: string | undefined;
     readonly message?: string | undefined;

package/lib/types/recovery-coordinator.js

@@ -3,6 +3,8 @@ import { join } from 'node:path';
 import { probeList, readUnitEvidence } from '@lmzhen/dsh-evolution-core';
 import { evidenceSha256 } from "./domain/evidence-hash.js";
 import { projectRecoveredUnit } from "./recovery-projection.js";
+import { readCommitReceipts } from "./commit-receipt.js";
+import { readUndoReceipt } from "./domain/undo-receipt.js";
 const branchOf = (phase) => {
     if (phase === 'prepared' || phase === 'target-pending')
         return 'A';
@@ -36,24 +38,32 @@ export async function recoverCommitUnits(options) {
             continue;
         }
         const evidence = await readUnitEvidence(options.io, options.home, journal.unitId);
+        // An undo is the newest durable fact. Recovery must not re-project a committed unit
+        // over an undo receipt (that would re-archive the source and reset pair-index to merged).
+        const receipt = (await readCommitReceipts(options.io, options.home)).find(item => item.unitId === journal.unitId);
+        const undoRunId = receipt?.parentRunId ?? journal.runId;
+        if (receipt?.pairKey !== undefined && await readUndoReceipt(options.io, options.home, undoRunId, receipt.pairKey) !== null) {
+            reports.push({ unitId: journal.unitId, runId: journal.runId, phase: journal.phase, branch: branchOf(journal.phase), action: 'none', ok: true, code: 'undo-recorded' });
+            continue;
+        }
         const branch = branchOf(journal.phase);
         if (journal.phase === 'committed' || evidence !== null || journal.phase === 'unit-written' || journal.phase === 'sources-archived') {
             const result = await options.unit.finalize(journal.unitId);
             if (result.ok) {
                 let projection;
                 try {
-                    projection = await projectRecoveredUnit({ io: options.io, home: options.home, runId: journal.runId, unitId: journal.unitId, evidence: result.evidence, now: options.now, ...(options.runs === undefined ? {} : { runs: options.runs }), ...(options.onProjectionPhase === undefined ? {} : { onPhase: options.onProjectionPhase }) });
+                    projection = await projectRecoveredUnit({ io: options.io, home: options.home, runId: journal.runId, unitId: journal.unitId, evidence: result.evidence, now: options.now, ...(branch === 'D' ? { interrupted: true } : {}), ...(options.runs === undefined ? {} : { runs: options.runs }), ...(options.onProjectionPhase === undefined ? {} : { onPhase: options.onProjectionPhase }) });
                 }
                 catch (error) {
                     projection = { ok: false, action: 'projection-threw', message: error instanceof Error ? error.message : String(error) };
                 }
                 if (!projection.ok)
-                    reports.push({ unitId: journal.unitId, runId: journal.runId, phase: journal.phase, branch, action: 'blocked', ok: false, code: 'projection-failed', message: projection.message });
+                    reports.push({ unitId: journal.unitId, runId: journal.runId, phase: journal.phase, branch, action: 'blocked', ok: false, code: 'projection-failed', message: projection.message, ...(branch === 'D' ? { state: 'interrupted' } : {}) });
                 else
-                    reports.push({ unitId: journal.unitId, runId: journal.runId, phase: journal.phase, branch, action: 'finalize', ok: true, evidenceSha256: evidenceSha256(result.evidence) });
+                    reports.push({ unitId: journal.unitId, runId: journal.runId, phase: journal.phase, branch, action: 'finalize', ok: true, evidenceSha256: evidenceSha256(result.evidence), ...(branch === 'D' ? { state: 'interrupted' } : {}) });
                 continue;
             }
-            reports.push({ unitId: journal.unitId, runId: journal.runId, phase: journal.phase, branch, action: 'finalize', ok: false, code: result.code, message: result.message });
+            reports.push({ unitId: journal.unitId, runId: journal.runId, phase: journal.phase, branch, action: 'finalize', ok: false, code: result.code, message: result.message, ...(branch === 'D' ? { state: 'interrupted' } : {}) });
             continue;
         }
         if (branch === 'A') {

package/lib/types/recovery-projection.d.ts

@@ -13,15 +13,17 @@ export declare function projectRecoveredUnit(options: {
     readonly unitId: string;
     readonly evidence: UnitEvidenceRecord;
     readonly now: () => number;
+    /** Branch D: the unit committed, but the run was interrupted by process death. */
+    readonly interrupted?: boolean;
     readonly runs?: {
         settle(id: string, outcome: {
-            state: 'succeeded' | 'failed' | 'cancelled';
+            state: 'succeeded' | 'failed' | 'cancelled' | 'interrupted';
             resultRef?: string;
             failure?: string;
         }): Promise<void>;
         /** Controlled orphan upgrade: lets a committed unit turn failed(orphan) back into succeeded. */
         settleRecovered?(id: string, outcome: {
-            state: 'succeeded' | 'failed' | 'cancelled';
+            state: 'succeeded' | 'failed' | 'cancelled' | 'interrupted';
             resultRef?: string;
             failure?: string;
         }): Promise<boolean>;

package/lib/types/recovery-projection.js

@@ -51,7 +51,7 @@ export async function projectRecoveredUnit(options) {
     else {
         const report = {
             schemaVersion: 2, runId: options.runId, kind: 'merge', command: 'approve', startedAt: at, endedAt: at,
-            stopReason: 'completed', approval: { platformWrite: false, mergeApproval: true },
+            stopReason: options.interrupted === true ? 'interrupted' : 'completed', approval: { platformWrite: false, mergeApproval: true },
             scope: { candidatePairs: 1, queueBefore: { verify: 0, pending: 0, fuse: 0, skipped: 0 } },
             pairs: [{ id: row?.id ?? options.unitId, pairKey, a: row?.a ?? target, b: row?.b ?? options.evidence.sources[0]?.name ?? '', queue: 'fuse', outcome: 'merged', archived: options.evidence.sources.filter(source => source.archived).map(source => source.name), unitId: options.unitId, ...(validationPlan === undefined ? {} : { validationPlan }) }],
             totals: { merged: 1, kept: 0, pending: 0, failed: 0 }, notes: ['recovered from unit journal'],
@@ -83,10 +83,10 @@ export async function projectRecoveredUnit(options) {
     await recordPair(options.io, options.home, { pairKey, runId: options.runId, result: 'merged', target });
     await options.onPhase?.('run-meta');
     const meta = await readRunMeta(options.io, options.home, options.runId);
-    await writeRunMeta(options.io, options.home, { version: 1, runId: options.runId, phase: 'settled', reportRef: reportPath, pairCount: 1, ...(meta?.parentRunId === undefined ? {} : { parentRunId: meta.parentRunId }), createdAt: meta?.createdAt ?? new Date(at).toISOString(), updatedAt: new Date(at).toISOString() });
+    await writeRunMeta(options.io, options.home, { version: 1, runId: options.runId, ...(meta?.pid === undefined ? {} : { pid: meta.pid }), phase: 'settled', ...(options.interrupted === true ? { stopReason: 'interrupted' } : {}), reportRef: reportPath, pairCount: 1, ...(meta?.parentRunId === undefined ? {} : { parentRunId: meta.parentRunId }), ...(meta?.stagingRef === undefined ? {} : { stagingRef: meta.stagingRef }), ...(meta?.pairs === undefined ? {} : { pairs: meta.pairs }), createdAt: meta?.createdAt ?? new Date(at).toISOString(), updatedAt: new Date(at).toISOString() });
     await options.onPhase?.('settle');
     if (options.runs !== undefined) {
-        const outcome = { state: 'succeeded', resultRef: reportPath };
+        const outcome = { state: options.interrupted === true ? 'interrupted' : 'succeeded', resultRef: reportPath };
         const upgraded = options.runs.settleRecovered === undefined ? false : await options.runs.settleRecovered(options.runId, outcome);
         if (!upgraded)
             await options.runs.settle(options.runId, outcome);

package/lib/types/resume-command.js

@@ -60,7 +60,7 @@ export async function runResumeCommand(options) {
             const current = tx.rows().find(item => item.id === selected.id);
             if (current === undefined)
                 return null;
-            const moved = tx.transition(selected.id, { type: 'staged' }, current.version);
+            const moved = tx.transition(selected.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)
@@ -71,6 +71,7 @@ export async function runResumeCommand(options) {
     const result = await withMergeRun({
         io: options.io, home: options.home, registry: options.registry,
         command: 'resume', approval: { platformWrite: options.platformWrite, mergeApproval: options.approval }, pairKey: row.pairKey,
+        ...(row.stagingRef === undefined ? {} : { stagingRef: row.stagingRef }),
         parentRunId, now: options.now,
         ...(options.detached === true ? { detached: true } : {}),
         async body(ctx) {

package/lib/types/round2-outcome.js

@@ -5,6 +5,11 @@ import { casExpiredHook } from "./domain/failure-route.js";
 import { recordPair } from "./domain/run-coordinator.js";
 export async function recordRound2Outcome(io, home, now, row, outcome, deferProjection = false) {
     void now;
+    const reportExtra = {
+        ...(outcome.manifestFiles === undefined ? {} : { manifestFiles: outcome.manifestFiles }),
+        ...(outcome.criteria === undefined ? {} : { criteria: outcome.criteria }),
+        ...(outcome.validationIssues === undefined ? {} : { validation: { issues: outcome.validationIssues } }),
+    };
     if (outcome.kind === 'merged') {
         const unitRef = { unitId: outcome.unitId ?? 'unknown', evidenceSha256: outcome.evidenceSha256 ?? 'unknown' };
         const target = outcome.target?.actual ?? outcome.target?.requested ?? row.decision?.target;
@@ -25,7 +30,7 @@ export async function recordRound2Outcome(io, home, now, row, outcome, deferProj
             });
         };
         if (deferProjection)
-            return { merged: true, finalize, pair: { id: row.id, pairKey: row.pairKey, a: row.a, b: row.b, queue: row.queue, ...(row.decision === undefined ? {} : { decision: row.decision }), outcome: 'merged', archived: outcome.archived ?? [], ...(outcome.unitId === undefined ? {} : { unitId: outcome.unitId }), ...(outcome.target === undefined ? {} : { target: outcome.target }) } };
+            return { merged: true, finalize, pair: { id: row.id, pairKey: row.pairKey, a: row.a, b: row.b, queue: row.queue, ...(row.decision === undefined ? {} : { decision: row.decision }), outcome: 'merged', archived: outcome.archived ?? [], ...(outcome.lengths === undefined ? {} : { lengths: outcome.lengths }), ...(outcome.unitId === undefined ? {} : { unitId: outcome.unitId }), ...(outcome.target === undefined ? {} : { target: outcome.target }), ...reportExtra } };
         {
             await finalize();
         }
@@ -35,6 +40,8 @@ export async function recordRound2Outcome(io, home, now, row, outcome, deferProj
                 id: row.id, pairKey: row.pairKey, a: row.a, b: row.b, queue: row.queue,
                 ...(row.decision === undefined ? {} : { decision: row.decision }),
                 outcome: 'merged', archived: outcome.archived ?? [],
+                ...(outcome.lengths === undefined ? {} : { lengths: outcome.lengths }),
+                ...reportExtra,
                 ...(outcome.unitId === undefined ? {} : { unitId: outcome.unitId }),
                 ...(outcome.target === undefined ? {} : { target: outcome.target }),
                 ...(outcome.validationPlan === undefined ? {} : { validationPlan: outcome.validationPlan }),
@@ -42,39 +49,48 @@ export async function recordRound2Outcome(io, home, now, row, outcome, deferProj
         };
     }
     const failure = outcome.failure ?? { stage: 'author', code: 'merge-failed', message: 'round2 failed', retryable: true, retryFrom: 'agent2' };
-    if (failure.code === 'merge-over-limit' || failure.code === 'limit' || failure.code === 'merge-validation') {
-        const reason = failure.code === 'merge-validation' ? 'validation-failed' : 'merge-over-limit';
+    if (failure.code === 'merge-over-limit' || failure.code === 'limit') {
+        const reason = 'merge-over-limit';
         const skipped = await pairLedger(io, home).transact(tx => {
             const current = tx.rows().find(item => item.id === row.id);
             return current === undefined ? false : tx.transition(row.id, { type: 'skipped', reason, origin: 'system', skipSource: 'system' }, current.version).ok;
         });
         if (skipped)
             await dropStage(io, home, row.id);
-        return { merged: false, pair: { id: row.id, pairKey: row.pairKey, a: row.a, b: row.b, queue: row.queue, ...(row.decision === undefined ? {} : { decision: row.decision }), outcome: 'failed', archived: [], failure } };
+        return { merged: false, pair: { id: row.id, pairKey: row.pairKey, a: row.a, b: row.b, queue: row.queue, ...(row.decision === undefined ? {} : { decision: row.decision }), outcome: 'failed', archived: [], failure, ...reportExtra } };
     }
     const cas = casExpiredHook(failure.code);
     if (cas !== null) {
+        const terminalFailure = { ...failure, code: cas.reason, retryable: false, retryFrom: 'none' };
         await pairLedger(io, home).transact(tx => {
             const current = tx.rows().find(item => item.id === row.id);
             if (current === undefined)
                 return false;
-            const moved = tx.transition(row.id, { type: 'skipped', reason: cas.reason, origin: 'system', skipSource: 'system' }, current.version);
+            const moved = tx.transition(row.id, { type: 'failed', failure: terminalFailure }, current.version);
             return moved.ok;
         });
         await dropStage(io, home, row.id);
-        return { merged: false, pair: { id: row.id, pairKey: row.pairKey, a: row.a, b: row.b, queue: row.queue, ...(row.decision === undefined ? {} : { decision: row.decision }), outcome: 'failed', archived: [], failure: { ...failure, code: cas.reason, retryable: false, retryFrom: 'none' } } };
+        return { merged: false, pair: { id: row.id, pairKey: row.pairKey, a: row.a, b: row.b, queue: row.queue, ...(row.decision === undefined ? {} : { decision: row.decision }), outcome: 'failed', archived: [], failure: terminalFailure, ...reportExtra } };
     }
     if (failure.code === 'commit-failed' || failure.code === 'validation-failed') {
-        await pairLedger(io, home).transact(tx => {
+        // FR-EXEC-11/14: report-only failure. The pair leaves the active queue (so a later scan
+        // can evaluate it again); it is NOT written to skipped.
+        const dropped = await pairLedger(io, home).transact(tx => {
             const current = tx.rows().find(item => item.id === row.id);
             return current === undefined ? false : tx.remove(row.id, 'superseded', undefined, current.version).ok;
         });
+        if (dropped) {
+            await dropStage(io, home, row.id, row.stagingRef);
+            await recordPair(io, home, { pairKey: row.pairKey, runId: row.runId ?? 'merge', result: 'failed', ...(row.decision?.target === undefined ? {} : { target: row.decision.target }) });
+        }
     }
     if (failure.code === 'source-gone') {
-        await pairLedger(io, home).transact(tx => {
+        const dropped = await pairLedger(io, home).transact(tx => {
             const current = tx.rows().find(item => item.id === row.id);
             return current === undefined ? false : tx.remove(row.id, 'superseded', undefined, current.version).ok;
         });
+        if (dropped)
+            await dropStage(io, home, row.id, row.stagingRef);
         return { merged: false, pair: { id: row.id, pairKey: row.pairKey, a: row.a, b: row.b, queue: row.queue, outcome: 'failed', archived: [], failure } };
     }
     const projected = await pairLedger(io, home).transact(tx => {
@@ -85,7 +101,7 @@ export async function recordRound2Outcome(io, home, now, row, outcome, deferProj
         return moved.ok && moved.row !== null ? v4ToLegacy(moved.row) : null;
     });
     if (projected === null)
-        return { merged: false, pair: { id: row.id, pairKey: row.pairKey, a: row.a, b: row.b, queue: row.queue, outcome: 'failed', archived: [], failure: { ...failure, code: 'row-changed', message: 'row changed before failure record' } } };
+        return { merged: false, pair: { id: row.id, pairKey: row.pairKey, a: row.a, b: row.b, queue: row.queue, outcome: 'failed', archived: [], failure: { ...failure, code: 'row-changed', message: 'row changed before failure record' }, ...reportExtra } };
     {
         await recordPair(io, home, {
             pairKey: row.pairKey,
@@ -100,6 +116,7 @@ export async function recordRound2Outcome(io, home, now, row, outcome, deferProj
             id: row.id, pairKey: row.pairKey, a: row.a, b: row.b, queue: row.queue,
             ...(row.decision === undefined ? {} : { decision: row.decision }),
             outcome: 'failed', archived: [], failure,
+            ...reportExtra,
         },
     };
 }

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

@@ -60,6 +60,7 @@ export interface WithMergeRunOptions {
     readonly total?: number;
     readonly pairKey?: string;
     readonly pairCount?: number;
+    readonly stagingRef?: string;
     readonly parentRunId?: string;
     readonly detached?: boolean;
     readonly timeoutMinutes?: number;