review-council 4.4.15 → 4.4.17

package/README.md

@@ -111,7 +111,8 @@ Review a PR, a local diff, or uncommitted work.
 | `--retry-reason <reason>` | Explicit bounded recovery decision for a failed/unknown launch; preserves spent attempts |
 | `--retry-report <path>` | Bind an original legacy report to an inconclusive retry; new inputs may differ; requires `--retry-reason` |
 | `--resume-pending` / `--resume-async-sha256 <hashes>` | Recover one proven dead-owner pending launch while retaining exact async artifacts and treating unknown blocking work as failed |
-| `--ordinary-pending-package <path>` / `--preview-pending` | Authenticate a sealed ordinary pending recovery package without mutation, then apply it under an explicit retry reason |
+| `--ordinary-pending-package <path>` / `--preview-pending` | Authenticate a sealed ordinary pending recovery package without mutation before choosing a recovery operation |
+| `--finalize-pending-only` / `--pending-native-sha256 <digest>` / `--pending-attempt-sha256 <digest>` | Finalize the previewed ordinary pending attempt as failed/unknown without claiming or dispatching its successor |
 | `--max-attempts <n>` / `--max-rounds <n>` | Guarded launch only: explicitly authorized caps; omission preserves native caps |
 | `--attest` | GitHub Actions gate workflow only: exchange the job's OIDC token for a run-bound Harness credential and record the review as attested (see below) |
 | `--config <path>` | Path to a config file |
@@ -236,7 +237,9 @@ new claim retains the source bytes and binding; no history or budget is reset.
 
 For an ordinary pending launch whose coordinator is provably dead, supply an independently reconstructed immutable package that binds the original target, head, base, guarded input, attempt, round, PID and retained async artifact descriptors. RCL recomputes its production guarded-input digest and checks every binding under the target lock before it mutates native state.
 
-Use `--preview-pending` with `--resume-pending --ordinary-pending-package <path>` to authenticate that package with zero state, output or provider writes. The normal invocation repeats the checks, marks the spent attempt failed with blocking outcome unknown, archives the exact retained async artifacts, and claims exactly the next checkpointed attempt without resetting either cap.
+Use `--preview-pending` with either `--resume-pending` or `--finalize-pending-only` and `--ordinary-pending-package <path>` to authenticate that package with zero state, output or provider writes. Combined `--resume-pending` repeats the checks, marks the spent attempt failed with blocking outcome unknown, archives the exact retained async artifacts, and claims exactly the next checkpointed attempt under its explicitly bounded cap.
+
+Use `--finalize-pending-only` when recovery must stop at that failed/unknown finalization. Pass the unchanged cap plus the exact `nativeStateSha256` and `attemptStateSha256` returned by its preview as `--pending-native-sha256` and `--pending-attempt-sha256`. Apply archives the retained async artifacts idempotently and returns a source-bound receipt while leaving the attempt counter, cap, round history and next-free ordinal unchanged. Repeating the command reads back the same receipt; it never creates a successor claim, checkpoint, reviewer callback or provider call. Receipt readback validates either the exact finalized state or a monotonic successor against retained source snapshots. An exact legacy receipt without those snapshots is upgraded idempotently before a successor proceeds, without changing native state or accounting. A later guarded convergence process may claim the next attempt independently.
 
 When native triage reports `converged-dismissal-only` but Harness still reports
 `fixes_pending` with no actionable findings, an explicit recovery can authorize

package/dist/converge/correction-anchors.d.ts

@@ -0,0 +1 @@
+export * from '../evidence/claim-recovery/validation/anchors.js';

package/dist/converge/correction-anchors.js

@@ -0,0 +1,2 @@
+export * from '../evidence/claim-recovery/validation/anchors.js';
+//# sourceMappingURL=correction-anchors.js.map

package/dist/converge/correction-anchors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"correction-anchors.js","sourceRoot":"","sources":["../../src/converge/correction-anchors.ts"],"names":[],"mappings":"AAAA,cAAc,kDAAkD,CAAC"}

package/dist/converge/ordinary-pending-package.js

@@ -1,6 +1,9 @@
 import { guardedInputSha256, stableStringify } from '../report/run-header.js';
 export function validateOrdinaryPendingPackage(value, expected) {
-    const input = value?.guardedInput, keys = ['asyncRoles', 'config', 'diff', 'head', 'kind', 'pr', 'prompts', 'repo', 'roster', 'spec'];
+    const input = value?.guardedInput;
+    const specPresent = !!input && Object.hasOwn(input, 'spec');
+    const keys = ['asyncRoles', 'config', 'diff', 'head', 'kind', 'pr', 'prompts', 'repo', 'roster',
+        ...(specPresent ? ['spec'] : [])];
     const digest = (candidate) => typeof candidate === 'string' && /^[a-f0-9]{64}$/.test(candidate);
     const structuredInput = input && input.kind === 'patch' && typeof input.repo === 'string' && /^[^/\s]+\/[^/\s]+$/.test(input.repo) &&
         Number.isSafeInteger(input.pr) && input.pr > 0 && digest(input.diff) && digest(input.config) &&
@@ -11,7 +14,7 @@ export function validateOrdinaryPendingPackage(value, expected) {
             const role = item;
             return item && typeof item === 'object' && typeof role.name === 'string' && role.name.length > 0;
         }) &&
-        input.spec && typeof input.spec === 'object';
+        (!specPresent || (input.spec && typeof input.spec === 'object'));
     if (!value || value.target !== expected.target || value.headSha !== expected.headSha || value.baseSha !== expected.baseSha || value.attempt !== expected.attempt || value.round !== expected.round || value.pid !== expected.pid || !/^[a-f0-9]{40}$/.test(value.baseSha) ||
         !Number.isSafeInteger(value.attempt) || value.attempt < 1 || !Number.isSafeInteger(value.round) || value.round < 1 ||
         !Number.isSafeInteger(value.pid) || value.pid < 1 || !input || Object.keys(input).sort().join(',') !== keys.join(',') ||

package/dist/converge/ordinary-pending-package.js.map

@@ -1 +1 @@
-{"version":3,"file":"ordinary-pending-package.js","sourceRoot":"","sources":["../../src/converge/ordinary-pending-package.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAK9E,MAAM,UAAU,8BAA8B,CAAC,KAA6B,EAAE,QAA+B;IAC3G,MAAM,KAAK,GAAG,KAAK,EAAE,YAAY,EAAE,IAAI,GAAG,CAAC,YAAY,EAAC,QAAQ,EAAC,MAAM,EAAC,MAAM,EAAC,MAAM,EAAC,IAAI,EAAC,SAAS,EAAC,MAAM,EAAC,QAAQ,EAAC,MAAM,CAAC,CAAC;IAC7H,MAAM,MAAM,GAAG,CAAC,SAAkB,EAAuB,EAAE,CAAC,OAAO,SAAS,KAAK,QAAQ,IAAI,gBAAgB,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IAC9H,MAAM,eAAe,GAAG,KAAK,IAAI,KAAK,CAAC,IAAI,KAAK,OAAO,IAAI,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ,IAAI,oBAAoB,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;QAChI,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,EAAE,CAAC,IAAK,KAAK,CAAC,EAAa,GAAG,CAAC,IAAI,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC;QACxG,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,UAAU,CAAC;QAC9F,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,CAAC;QAC5D,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,CAAC;QAC7D,KAAK,CAAC,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE;YAC5B,MAAM,IAAI,GAAG,IAA+B,CAAC;YAC7C,OAAO,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC;QACnG,CAAC,CAAC;QACF,KAAK,CAAC,IAAI,IAAI,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ,CAAC;IAC/C,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,MAAM,KAAK,QAAQ,CAAC,MAAM,IAAI,KAAK,CAAC,OAAO,KAAK,QAAQ,CAAC,OAAO,IAAI,KAAK,CAAC,OAAO,KAAK,QAAQ,CAAC,OAAO,IAAI,KAAK,CAAC,OAAO,KAAK,QAAQ,CAAC,OAAO,IAAI,KAAK,CAAC,KAAK,KAAK,QAAQ,CAAC,KAAK,IAAI,KAAK,CAAC,GAAG,KAAK,QAAQ,CAAC,GAAG,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC;QACvQ,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,KAAK,CAAC,OAAO,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,KAAK,GAAG,CAAC;QAClH,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,GAAG,GAAG,CAAC,IAAI,CAAC,KAAK,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC;QACrH,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,mBAAmB,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,mBAAmB,CAAC,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,QAAQ,CAAC,mBAAmB,CAAC,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,IAAI,KAAK,KAAK,CAAC,OAAO,IAAI,kBAAkB,CAAC,KAAK,CAAC,KAAK,QAAQ,CAAC,WAAW;QAAE,MAAM,IAAI,KAAK,CAAC,mCAAmC,CAAC,CAAC;IAClS,IAAI,CAAC,eAAe,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,KAAK,CAAC,mBAAmB,CAAC,CAAC,IAAI;QACrG,IAAI,GAAG,CAAC,KAAK,CAAC,mBAAmB,CAAC,CAAC,IAAI,KAAK,KAAK,CAAC,mBAAmB,CAAC,MAAM;QAC5E,KAAK,CAAC,mBAAmB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,aAAa,CAAC;QAC5F,KAAK,CAAC,aAAa,CAAC,MAAM,KAAK,KAAK,CAAC,mBAAmB,CAAC,MAAM;QAC/D,IAAI,GAAG,CAAC,KAAK,CAAC,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,IAAI,KAAK,KAAK,CAAC,aAAa,CAAC,MAAM;QAC1F,KAAK,CAAC,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAC9B,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,mBAAmB,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC;YACjF,OAAO,IAAI,CAAC,KAAK,KAAK,QAAQ,IAAI,CAAC,IAAI,CAAC,KAAK,IAAI,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,IAAI,CAAC,IAAI,CAAC,IAAI;YAC5F,OAAO,IAAI,CAAC,QAAQ,KAAK,QAAQ,IAAI,CAAC,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,IAAI,KAAK,OAAO;YAC5E,CAAE,KAAK,CAAC,MAAoC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,KAAK,KAAK,IAAI,CAAC,KAAK;gBAClF,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,QAAQ,KAAK,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,IAAI,KAAK,OAAO,CAAC,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,mCAAmC,CAAC,CAAC;IACpJ,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,eAAe,CAAC,KAAK,CAAC,CAA2B,CAAC,CAAC;AACrF,CAAC"}
+{"version":3,"file":"ordinary-pending-package.js","sourceRoot":"","sources":["../../src/converge/ordinary-pending-package.ts"],"names":[],"mappings":"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"}

package/dist/converge/pending-legacy-resume.d.ts

@@ -1,5 +1,7 @@
+import { z } from 'zod';
 import { type LegacyRetrySelection } from './legacy-launch-health.js';
 import { type GuardedLaunchCompletion } from './launch-record.js';
+import { writeState } from './run-state.js';
 import { type ConvergeAttemptClaim } from './attempt-budget.js';
 import { type NativeTargetOwnership } from './target-ownership.js';
 import { type OriginalLaunch } from '../dispatch/original-launch.js';
@@ -43,6 +45,7 @@ export interface PendingLegacyResumeOptions {
     /** Required for recovering an ordinary dead-owner launch without a legacy report. */
     migrationPackage?: OrdinaryPendingPackage;
     preview?: boolean;
+    previewMode?: 'combined' | 'finalize-only';
 }
 export interface PendingLegacyResumeResult {
     claim: ConvergeAttemptClaim;
@@ -57,6 +60,52 @@ export interface OrdinaryPendingPreview {
     cap: number;
     nextAttempt: number;
 }
+export interface OrdinaryPendingFinalizeOptions {
+    gitCommonDir: string;
+    target: string;
+    headSha: string;
+    baseSha: string;
+    pendingInputSha256: string;
+    nativeStateSha256: string;
+    attemptStateSha256: string;
+    retainedAsyncSha256: readonly string[];
+    maxAttempts: number;
+    migrationPackage: OrdinaryPendingPackage;
+    ownerAlive?: (pid: number) => boolean;
+    loadRetainedAsync: () => Promise<AsyncResultReference[]>;
+    /** Fault-injection boundary for proving archive-complete/native-write recovery. */
+    writeFinalizedState?: typeof writeState;
+}
+declare const ordinaryPendingFinalizationReceiptSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    operation: z.ZodLiteral<"ordinary-pending-finalize-only">;
+    target: z.ZodString;
+    headSha: z.ZodString;
+    baseSha: z.ZodString;
+    inputSha256: z.ZodString;
+    sourceDigest: z.ZodString;
+    migrationPackageSha256: z.ZodString;
+    finalizedAttempt: z.ZodNumber;
+    round: z.ZodNumber;
+    originalPid: z.ZodNumber;
+    attemptsUsed: z.ZodNumber;
+    cap: z.ZodNumber;
+    nextFreeAttempt: z.ZodNumber;
+    blockingOutcome: z.ZodLiteral<"unknown">;
+    retainedAsyncSha256: z.ZodArray<z.ZodString>;
+    sourceNativeStateSha256: z.ZodString;
+    sourceAttemptStateSha256: z.ZodString;
+    finalizedNativeStateSha256: z.ZodString;
+    receiptDigest: z.ZodString;
+}, z.core.$strict>;
+export type OrdinaryPendingFinalizationReceipt = z.infer<typeof ordinaryPendingFinalizationReceiptSchema>;
+export interface OrdinaryPendingFinalizeResult {
+    receipt: OrdinaryPendingFinalizationReceipt;
+    reusedReceipt: boolean;
+    snapshotBindingUpgraded: boolean;
+}
+/** Finalize one authenticated ordinary pending launch without claiming or dispatching its successor. */
+export declare function finalizeOrdinaryPendingLaunch(input: OrdinaryPendingFinalizeOptions): Promise<OrdinaryPendingFinalizeResult>;
 /** Authenticate an ordinary dead-owner recovery under its target lock without mutating native state. */
 export declare function previewOrdinaryPendingLaunch(input: PendingLegacyResumeOptions): Promise<OrdinaryPendingPreview>;
 /** Finalize unknown A34 evidence, then claim one fresh checkpointed A35. */
@@ -67,3 +116,4 @@ export declare function resumePendingLegacyLaunch(input: PendingLegacyResumeOpti
     preview?: false;
 }): Promise<PendingLegacyResumeResult>;
 export declare function resumePendingLegacyLaunch(input: PendingLegacyResumeOptions): Promise<PendingLegacyResumeResult | OrdinaryPendingPreview>;
+export {};

package/dist/converge/pending-legacy-resume.js

@@ -1,9 +1,11 @@
 import { createHash } from 'node:crypto';
 import { realpath } from 'node:fs/promises';
 import { join, resolve } from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+import { z } from 'zod';
 import { inspectPendingLegacyRetry } from './legacy-launch-health.js';
 import { completionSchema, launchSchema } from './launch-record.js';
-import { convergeRunStatePath, loadConvergeRunState, writeState } from './run-state.js';
+import { convergeRunStatePath, loadConvergeRunState, preflightConvergeRunStateWrite, writeState } from './run-state.js';
 import { claimConvergeAttempt, convergeAttemptStatePath, previewConvergeAttemptState } from './attempt-budget.js';
 import { withRecoveryTarget } from './target-ownership.js';
 import { bindOriginalCouncil } from '../dispatch/original-execution.js';
@@ -12,10 +14,46 @@ import { uuidv7 } from '../report/uuid.js';
 import { captureSupplementalAsync } from '../report/supplemental-async.js';
 import { stableStringify } from '../report/run-header.js';
 import { readStable } from '../telemetry/recovery/files.js';
+import { serializeRecoveryDocument } from '../evidence/original-run/journal.js';
 import { prepareLockRoot } from '../evidence/original-run/lock-path.js';
 import { retainStaleFile } from './stale-report-storage.js';
 import { createPendingRecoverySource, createOrdinaryMigrationSource, pendingRecoverySourceSchema } from './pending-recovery-source.js';
 import { validateOrdinaryPendingPackage } from './ordinary-pending-package.js';
+const digestSchema = z.string().regex(/^[a-f0-9]{64}$/);
+const ordinaryPendingFinalizationReceiptBodySchema = z.object({
+    version: z.literal(1),
+    operation: z.literal('ordinary-pending-finalize-only'),
+    target: z.string().min(1),
+    headSha: z.string().regex(/^[a-f0-9]{40}$/),
+    baseSha: z.string().regex(/^[a-f0-9]{40}$/),
+    inputSha256: digestSchema,
+    sourceDigest: digestSchema,
+    migrationPackageSha256: digestSchema,
+    finalizedAttempt: z.number().int().positive().safe(),
+    round: z.number().int().positive().safe(),
+    originalPid: z.number().int().positive().safe(),
+    attemptsUsed: z.number().int().positive().safe(),
+    cap: z.number().int().positive().safe(),
+    nextFreeAttempt: z.number().int().positive().safe(),
+    blockingOutcome: z.literal('unknown'),
+    retainedAsyncSha256: z.array(digestSchema).min(1),
+    sourceNativeStateSha256: digestSchema,
+    sourceAttemptStateSha256: digestSchema,
+    finalizedNativeStateSha256: digestSchema,
+}).strict();
+const ordinaryPendingFinalizationReceiptSchema = ordinaryPendingFinalizationReceiptBodySchema.extend({
+    receiptDigest: digestSchema,
+}).strict().superRefine((receipt, context) => {
+    const { receiptDigest, ...body } = receipt;
+    if (receiptDigest !== createHash('sha256').update(stableStringify(body)).digest('hex')) {
+        context.addIssue({ code: 'custom', message: 'Pending finalization receipt digest is invalid' });
+    }
+    if (receipt.nextFreeAttempt !== receipt.finalizedAttempt + 1 ||
+        receipt.attemptsUsed !== receipt.finalizedAttempt || receipt.attemptsUsed > receipt.cap ||
+        new Set(receipt.retainedAsyncSha256).size !== receipt.retainedAsyncSha256.length) {
+        context.addIssue({ code: 'custom', message: 'Pending finalization accounting is inconsistent' });
+    }
+});
 function fail(code) { throw new Error(`pending_legacy_resume_${code}`); }
 function defaultOwnerAlive(pid) {
     try {
@@ -89,7 +127,22 @@ function validateOptions(input) {
         !Number.isSafeInteger(input.maxAttempts) || input.maxAttempts < 1 ||
         !Number.isSafeInteger(input.maxPhysicalCalls) || input.maxPhysicalCalls < 1 ||
         !Number.isSafeInteger(input.maxAttemptsPerCell) || input.maxAttemptsPerCell < 1 ||
-        !Number.isSafeInteger(input.maxDurationMs) || input.maxDurationMs < 1 || input.maxDurationMs > 2_147_483_647) {
+        !Number.isSafeInteger(input.maxDurationMs) || input.maxDurationMs < 1 || input.maxDurationMs > 2_147_483_647 ||
+        (input.previewMode !== undefined && !['combined', 'finalize-only'].includes(input.previewMode))) {
+        fail('invalid_input');
+    }
+}
+function validateFinalizeOptions(input) {
+    const hashes = input?.retainedAsyncSha256;
+    if (!input || typeof input.gitCommonDir !== 'string' || typeof input.target !== 'string' || !input.target.trim() ||
+        !/^[a-f0-9]{40}$/.test(input.headSha ?? '') || !/^[a-f0-9]{40}$/.test(input.baseSha ?? '') ||
+        !/^[a-f0-9]{64}$/.test(input.pendingInputSha256 ?? '') ||
+        !/^[a-f0-9]{64}$/.test(input.nativeStateSha256 ?? '') ||
+        !/^[a-f0-9]{64}$/.test(input.attemptStateSha256 ?? '') ||
+        !Array.isArray(hashes) || hashes.length === 0 || hashes.some(value => !/^[a-f0-9]{64}$/.test(value)) ||
+        new Set(hashes).size !== hashes.length || typeof input.loadRetainedAsync !== 'function' ||
+        (input.writeFinalizedState !== undefined && typeof input.writeFinalizedState !== 'function') ||
+        !input.migrationPackage || !Number.isSafeInteger(input.maxAttempts) || input.maxAttempts < 1) {
         fail('invalid_input');
     }
 }
@@ -104,6 +157,277 @@ async function archiveAsync(common, source, artifacts, packet) {
         blockingOutcome: 'unknown', artifacts: artifacts.map(item => ({ sha256: item.sha256 })).sort((a, b) => a.sha256.localeCompare(b.sha256)) }));
     await retainStaleFile(join(directory, 'manifest.json'), manifest);
 }
+function finalizationReceiptPath(common, migrationPackageSha256) {
+    return join(common, 'rcl-converge-pending-finalizations', migrationPackageSha256, 'receipt.json');
+}
+function finalizationSnapshotPath(common, migrationPackageSha256, name) {
+    return join(common, 'rcl-converge-pending-finalizations', migrationPackageSha256, name);
+}
+async function readFinalizationReceipt(common, migrationPackageSha256) {
+    try {
+        const stored = await readStable(finalizationReceiptPath(common, migrationPackageSha256));
+        return ordinaryPendingFinalizationReceiptSchema.parse(JSON.parse(stored.text));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+}
+async function retainFinalizationReceipt(common, receipt) {
+    const directory = await prepareLockRoot(join(common, 'rcl-converge-pending-finalizations', receipt.migrationPackageSha256));
+    await retainStaleFile(join(directory, 'receipt.json'), Buffer.from(stableStringify(receipt)));
+}
+async function retainFinalizationSnapshots(common, receipt, sourceAttemptState, finalizedNativeState) {
+    if (createHash('sha256').update(sourceAttemptState).digest('hex') !== receipt.sourceAttemptStateSha256 ||
+        createHash('sha256').update(finalizedNativeState).digest('hex') !== receipt.finalizedNativeStateSha256) {
+        fail('finalization_snapshot_mismatch');
+    }
+    const directory = await prepareLockRoot(join(common, 'rcl-converge-pending-finalizations', receipt.migrationPackageSha256));
+    await retainStaleFile(join(directory, 'source-attempt-state.json'), sourceAttemptState);
+    await retainStaleFile(join(directory, 'finalized-native-state.json'), finalizedNativeState);
+}
+async function readFinalizationSnapshot(common, receipt, name, digest) {
+    const snapshot = await readStable(finalizationSnapshotPath(common, receipt.migrationPackageSha256, name));
+    if (snapshot.sha256 !== digest)
+        fail('finalization_snapshot_mismatch');
+    return snapshot.raw;
+}
+function isPrefix(before, after) {
+    return before.length <= after.length && before.every((value, index) => isDeepStrictEqual(value, after[index]));
+}
+async function finalizationSnapshotsPresent(common, receipt) {
+    try {
+        await Promise.all([
+            readFinalizationSnapshot(common, receipt, 'source-attempt-state.json', receipt.sourceAttemptStateSha256),
+            readFinalizationSnapshot(common, receipt, 'finalized-native-state.json', receipt.finalizedNativeStateSha256),
+        ]);
+        return true;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+}
+async function assertFinalizedStateMatchesReceipt(common, receipt) {
+    const [native, attempts] = await Promise.all([
+        readStable(convergeRunStatePath(common, receipt.target)),
+        readStable(convergeAttemptStatePath(common, receipt.target)),
+    ]);
+    if (native.sha256 === receipt.finalizedNativeStateSha256 &&
+        attempts.sha256 === receipt.sourceAttemptStateSha256) {
+        return { native: native.raw, attempts: attempts.raw, exact: true };
+    }
+    let originalAttemptsBytes, finalizedNativeBytes;
+    try {
+        [originalAttemptsBytes, finalizedNativeBytes] = await Promise.all([
+            readFinalizationSnapshot(common, receipt, 'source-attempt-state.json', receipt.sourceAttemptStateSha256),
+            readFinalizationSnapshot(common, receipt, 'finalized-native-state.json', receipt.finalizedNativeStateSha256),
+        ]);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            fail('finalization_receipt_state_mismatch');
+        throw error;
+    }
+    const [currentNative, currentAttempts] = await Promise.all([
+        loadConvergeRunState(common, receipt.target),
+        previewConvergeAttemptState(common, receipt.target),
+    ]);
+    if (!currentNative || !currentAttempts)
+        fail('finalization_receipt_state_mismatch');
+    const originalAttempts = JSON.parse(originalAttemptsBytes.toString('utf8'));
+    const finalizedNative = JSON.parse(finalizedNativeBytes.toString('utf8'));
+    const finalizedLaunch = launchSchema.safeParse(finalizedNative.lastLaunch);
+    const currentLaunch = launchSchema.safeParse(currentNative.lastLaunch);
+    const priorStale = finalizedNative.staleReportAudit ?? [], currentStale = currentNative.staleReportAudit ?? [];
+    const priorGaps = finalizedNative.roundGapAudit?.entries ?? [], currentGaps = currentNative.roundGapAudit?.entries ?? [];
+    if (originalAttempts.target !== receipt.target || currentAttempts.target !== receipt.target ||
+        originalAttempts.attemptsUsed !== receipt.attemptsUsed || originalAttempts.cap !== receipt.cap ||
+        originalAttempts.migratedAttempts !== currentAttempts.migratedAttempts ||
+        currentAttempts.attemptsUsed <= receipt.attemptsUsed ||
+        currentAttempts.cap < currentAttempts.attemptsUsed || currentAttempts.cap > receipt.cap ||
+        !isDeepStrictEqual(currentAttempts.cycle, originalAttempts.cycle) ||
+        !isPrefix(originalAttempts.attempts, currentAttempts.attempts) ||
+        currentAttempts.attempts.at(originalAttempts.attempts.length)?.attempt !== receipt.nextFreeAttempt ||
+        finalizedNative.target !== receipt.target || currentNative.target !== receipt.target ||
+        !finalizedLaunch.success || finalizedLaunch.data.status !== 'failed' ||
+        finalizedLaunch.data.attempt !== receipt.finalizedAttempt ||
+        finalizedLaunch.data.round !== receipt.round ||
+        finalizedLaunch.data.pendingRecovery?.sourceDigest !== receipt.sourceDigest ||
+        !isDeepStrictEqual(currentNative.cycle, finalizedNative.cycle) ||
+        currentNative.roundCap < finalizedNative.roundCap ||
+        !isPrefix(finalizedNative.rounds, currentNative.rounds) ||
+        !isPrefix(priorStale, currentStale) || !isPrefix(priorGaps, currentGaps) ||
+        Object.entries(finalizedNative.findings)
+            .some(([key, value]) => !isDeepStrictEqual(value, currentNative.findings[key])) ||
+        !currentLaunch.success || currentLaunch.data.attempt <= receipt.finalizedAttempt ||
+        currentLaunch.data.attempt !== currentAttempts.attemptsUsed) {
+        fail('finalization_receipt_state_mismatch');
+    }
+    return { native: native.raw, attempts: attempts.raw, exact: false };
+}
+function createFinalizationReceipt(input) {
+    const body = ordinaryPendingFinalizationReceiptBodySchema.parse(input);
+    return ordinaryPendingFinalizationReceiptSchema.parse({
+        ...body,
+        receiptDigest: createHash('sha256').update(stableStringify(body)).digest('hex'),
+    });
+}
+function assertReceiptMatchesInput(receipt, input, migrationPackageSha256) {
+    if (receipt.target !== input.target || receipt.headSha !== input.headSha || receipt.baseSha !== input.baseSha ||
+        receipt.inputSha256 !== input.pendingInputSha256 || receipt.migrationPackageSha256 !== migrationPackageSha256 ||
+        receipt.sourceNativeStateSha256 !== input.nativeStateSha256 ||
+        receipt.sourceAttemptStateSha256 !== input.attemptStateSha256 ||
+        receipt.cap !== input.maxAttempts ||
+        receipt.retainedAsyncSha256.join(',') !== [...input.retainedAsyncSha256].sort().join(',')) {
+        fail('finalization_receipt_mismatch');
+    }
+    return validateOrdinaryPendingPackage(input.migrationPackage, {
+        target: receipt.target, headSha: receipt.headSha, inputSha256: receipt.inputSha256,
+        baseSha: receipt.baseSha, attempt: receipt.finalizedAttempt, round: receipt.round,
+        pid: receipt.originalPid, retainedAsyncSha256: receipt.retainedAsyncSha256,
+    });
+}
+async function readArchivedAsync(common, sourceDigest, retainedAsyncSha256) {
+    const directory = join(common, 'rcl-converge-pending-recovery', sourceDigest);
+    const artifacts = await Promise.all(retainedAsyncSha256.map(async (digest) => {
+        const file = await readStable(join(directory, digest));
+        if (file.sha256 !== digest)
+            fail('async_binding_mismatch');
+        return { path: join(directory, digest), sha256: digest, bytesBase64: file.raw.toString('base64') };
+    }));
+    const expectedManifest = stableStringify({ version: 1, sourceDigest,
+        blockingOutcome: 'unknown', artifacts: [...retainedAsyncSha256].sort().map(sha256 => ({ sha256 })) });
+    if ((await readStable(join(directory, 'manifest.json'))).text !== expectedManifest) {
+        fail('async_binding_mismatch');
+    }
+    return artifacts;
+}
+async function loadOriginalOrArchivedAsync(options, source) {
+    try {
+        return await readArchivedAsync(options.gitCommonDir, source.digest, source.retainedAsyncSha256);
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+        return options.loadRetainedAsync();
+    }
+}
+/** Finalize one authenticated ordinary pending launch without claiming or dispatching its successor. */
+export async function finalizeOrdinaryPendingLaunch(input) {
+    validateFinalizeOptions(input);
+    const options = { ...input, target: input.target.trim(),
+        retainedAsyncSha256: [...input.retainedAsyncSha256].sort(),
+        gitCommonDir: await realpath(resolve(input.gitCommonDir)) };
+    const migrationPackageSha256 = createHash('sha256')
+        .update(stableStringify(options.migrationPackage)).digest('hex');
+    return withRecoveryTarget(options.gitCommonDir, options.target, async (ownership) => {
+        const existingReceipt = await readFinalizationReceipt(options.gitCommonDir, migrationPackageSha256);
+        if (existingReceipt) {
+            const packet = assertReceiptMatchesInput(existingReceipt, options, migrationPackageSha256);
+            const state = await assertFinalizedStateMatchesReceipt(options.gitCommonDir, existingReceipt);
+            validateAsyncArtifacts({ retainedAsyncSha256: existingReceipt.retainedAsyncSha256 }, await readArchivedAsync(options.gitCommonDir, existingReceipt.sourceDigest, existingReceipt.retainedAsyncSha256), packet);
+            const snapshotsPresent = await finalizationSnapshotsPresent(options.gitCommonDir, existingReceipt);
+            if (!snapshotsPresent) {
+                if (!state.exact)
+                    fail('finalization_receipt_state_mismatch');
+                await retainFinalizationSnapshots(options.gitCommonDir, existingReceipt, state.attempts, state.native);
+            }
+            return { receipt: existingReceipt, reusedReceipt: true,
+                snapshotBindingUpgraded: !snapshotsPresent };
+        }
+        const [state, attempts] = await Promise.all([
+            loadConvergeRunState(options.gitCommonDir, options.target),
+            previewConvergeAttemptState(options.gitCommonDir, options.target),
+        ]);
+        if (!state || !attempts || !state.lastLaunch)
+            fail('missing_launch');
+        if (attempts.cap !== options.maxAttempts)
+            fail('attempt_cap_mismatch');
+        const current = launchSchema.parse(state.lastLaunch);
+        if (current.attempt !== attempts.attemptsUsed || current.headSha !== options.headSha ||
+            current.inputSha256 !== options.pendingInputSha256 || !['pending', 'failed'].includes(current.status)) {
+            fail('launch_mismatch');
+        }
+        const packet = validateOrdinaryPendingPackage(options.migrationPackage, {
+            target: options.target, headSha: current.headSha, inputSha256: current.inputSha256,
+            baseSha: options.baseSha, attempt: current.attempt, round: current.round, pid: current.pid,
+            retainedAsyncSha256: options.retainedAsyncSha256,
+        });
+        let source;
+        let sourceAttemptStateBytes;
+        if (current.status === 'pending') {
+            if ((options.ownerAlive ?? defaultOwnerAlive)(current.pid))
+                fail('owner_alive');
+            const [nativeBytes, attemptBytes] = await Promise.all([
+                readStable(convergeRunStatePath(options.gitCommonDir, options.target)),
+                readStable(convergeAttemptStatePath(options.gitCommonDir, options.target)),
+            ]);
+            sourceAttemptStateBytes = attemptBytes.raw;
+            source = createOrdinaryMigrationSource({ version: 1, target: options.target,
+                headSha: current.headSha, inputSha256: current.inputSha256, pendingAttempt: current.attempt,
+                round: current.round, originalPid: current.pid, startedAt: current.startedAt,
+                blockingOutcome: 'unknown', reason: 'coordinator_exited_without_durable_blocking_receipts',
+                nativeStateSha256: nativeBytes.sha256, attemptStateSha256: attemptBytes.sha256,
+                retainedAsyncSha256: options.retainedAsyncSha256, migrationPackageSha256 });
+        }
+        else {
+            source = sourceFromFinalized(options.target, current, attempts, packet);
+        }
+        if (source.nativeStateSha256 !== options.nativeStateSha256 ||
+            source.attemptStateSha256 !== options.attemptStateSha256)
+            fail('source_digest_mismatch');
+        // Once the failed/unknown native state exists, archive publication already
+        // completed. Resume from those immutable bytes so a lost acknowledgment
+        // does not depend on the original async store still being available.
+        const artifacts = current.status === 'pending'
+            ? await loadOriginalOrArchivedAsync(options, source)
+            : await readArchivedAsync(options.gitCommonDir, source.digest, source.retainedAsyncSha256);
+        validateAsyncArtifacts(source, artifacts, packet);
+        let finalizedNativeStateSha256;
+        if (current.status === 'pending') {
+            state.lastLaunch = { ...current, status: 'failed', pendingRecovery: descriptor(source) };
+            state.updatedAt = new Date().toISOString();
+            finalizedNativeStateSha256 = createHash('sha256')
+                .update(serializeRecoveryDocument(state)).digest('hex');
+        }
+        else {
+            finalizedNativeStateSha256 = (await readStable(convergeRunStatePath(options.gitCommonDir, options.target))).sha256;
+        }
+        // Construct and validate the exact receipt before the first write. The
+        // native serializer is shared with writeState, so its post-state digest is
+        // known without publishing a partially validated operation.
+        const receipt = createFinalizationReceipt({ version: 1, operation: 'ordinary-pending-finalize-only',
+            target: options.target, headSha: current.headSha, baseSha: options.baseSha,
+            inputSha256: current.inputSha256, sourceDigest: source.digest, migrationPackageSha256,
+            finalizedAttempt: current.attempt, round: current.round, originalPid: current.pid,
+            attemptsUsed: attempts.attemptsUsed, cap: attempts.cap, nextFreeAttempt: current.attempt + 1,
+            blockingOutcome: 'unknown', retainedAsyncSha256: options.retainedAsyncSha256,
+            sourceNativeStateSha256: source.nativeStateSha256,
+            sourceAttemptStateSha256: source.attemptStateSha256,
+            finalizedNativeStateSha256 });
+        if (current.status === 'pending') {
+            await preflightConvergeRunStateWrite(options.gitCommonDir, state, ownership);
+        }
+        // Every fallible authentication and accounting check above precedes the
+        // first durable write. Archive publication is idempotent if this process
+        // stops before the native failed/unknown state or receipt is published.
+        await archiveAsync(options.gitCommonDir, source, artifacts, packet);
+        if (current.status === 'pending') {
+            await (options.writeFinalizedState ?? writeState)(options.gitCommonDir, state, ownership);
+        }
+        const finalizedNative = await readStable(convergeRunStatePath(options.gitCommonDir, options.target));
+        if (finalizedNative.sha256 !== finalizedNativeStateSha256)
+            fail('finalization_write_mismatch');
+        const finalizedAttempts = await readStable(convergeAttemptStatePath(options.gitCommonDir, options.target));
+        sourceAttemptStateBytes ??= finalizedAttempts.raw;
+        await retainFinalizationSnapshots(options.gitCommonDir, receipt, sourceAttemptStateBytes, finalizedNative.raw);
+        await retainFinalizationReceipt(options.gitCommonDir, receipt);
+        return { receipt, reusedReceipt: false, snapshotBindingUpgraded: false };
+    });
+}
 function validateAsyncArtifacts(source, artifacts, packet) {
     const expected = [...source.retainedAsyncSha256].sort();
     const actual = artifacts.map(item => item.sha256).sort();
@@ -148,8 +472,13 @@ export async function previewOrdinaryPendingLaunch(input) {
         if (!record || current.status !== 'pending' || current.attempt !== attempts.attemptsUsed ||
             current.headSha !== options.headSha || current.inputSha256 !== options.pendingInputSha256)
             fail('launch_mismatch');
-        if (attempts.attemptsUsed >= attempts.cap)
+        if (options.previewMode === 'finalize-only'
+            ? attempts.cap !== options.maxAttempts
+            : options.maxAttempts > current.attempt + 1)
+            fail('attempt_cap_mismatch');
+        if (options.previewMode !== 'finalize-only' && attempts.attemptsUsed >= attempts.cap) {
             fail('attempt_cap_exhausted');
+        }
         if ((options.ownerAlive ?? defaultOwnerAlive)(current.pid))
             fail('owner_alive');
         const packet = validateOrdinaryPendingPackage(options.migrationPackage, {
@@ -336,6 +665,11 @@ export async function resumePendingLegacyLaunch(input) {
             baseSha: options.baseSha, attempt: originalAttempt, round: original.round, pid: originalPid,
             retainedAsyncSha256: options.retainedAsyncSha256,
         });
+        // Combined finalize-and-successor recovery is explicit one-attempt
+        // authority. Refuse a broader cap before archiving evidence or changing
+        // the pending launch to failed/unknown.
+        if (options.maxAttempts > originalAttempt + 1)
+            fail('attempt_cap_mismatch');
         if (persistedSource) {
             return resumeFresh(options, ownership, state, attempts, current);
         }