@allocator-one/rcl 4.5.4 → 4.5.6

package/dist/evidence/original-run/lock-scope.js.map

@@ -1 +1 @@
-{"version":3,"file":"lock-scope.js","sourceRoot":"","sources":["../../../src/evidence/original-run/lock-scope.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEtC,MAAM,IAAI,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;AACjC,MAAM,CAAC,MAAM,SAAS,GAAG,gEAAgE,CAAC;AAG1F,wFAAwF;AACxF,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,IAAY,EAAE,IAAc;IAClE,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE;QACxC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,GAAG,IAAI;QACvD,GAAG,EAAE,EAAE,IAAI,EAAE,+BAA+B,EAAE,MAAM,EAAE,GAAG,EAAE;KAC5D,CAAC,CAAC;IACH,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,KAAK,UAAU,SAAS;IACtB,2EAA2E;IAC3E,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,iCAAiC,EAAE,GAAG,CAAC,CAAC;IAClE,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAAC,MAAM,EAAE,SAAS,EAAE,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;QACpG,OAAO,KAAK,CAAC,QAAQ,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IACvD,CAAC;YAAS,CAAC;QAAC,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;IAAC,CAAC;AACrC,CAAC;AAQD,MAAM,UAAU,cAAc,CAAC,KAAc;IAC3C,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IACtD,MAAM,KAAK,GAAG,KAAkB,CAAC;IACjC,OAAO,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ,IAAI,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;QACjE,CAAC,CAAC,KAAK,CAAC,QAAQ,KAAK,QAAQ,IAAI,KAAK,CAAC,SAAS,KAAK,QAAQ,CAAC;YAC5D,CAAC,KAAK,CAAC,QAAQ,KAAK,OAAO,IAAI,OAAO,KAAK,CAAC,SAAS,KAAK,QAAQ,IAAI,gBAAgB,CAAC,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;AACrH,CAAC;AAED,2EAA2E;AAC3E,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,YAA8B,EAAE;IACnE,MAAM,EAAE,GAAY;QAClB,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,OAAO,EAAE,iBAAiB,EAAE,IAAI,EAAE,SAAS;QACvE,SAAS,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,mBAAmB,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,GAAG,SAAS;KAC3E,CAAC;IACF,IAAI,CAAC;QACH,IAAI,MAAiB,CAAC;QACtB,IAAI,EAAE,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;YAC7B,MAAM,IAAI,GAAG,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,kBAAkB,EAAE,CAAC,IAAI,EAAE,sBAAsB,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;YACzG,MAAM,GAAG,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC;QAC7D,CAAC;aAAM,IAAI,EAAE,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;YACnC,MAAM,IAAI,GAAG,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;YAAC,MAAM,EAAE,GAAG,MAAM,EAAE,CAAC,SAAS,EAAE,CAAC;YACrF,MAAM,GAAG,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,GAAG,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC;QACzE,CAAC;;YAAM,MAAM,IAAI,KAAK,CAAC,aAAa,CAAC,CAAC;QACtC,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,SAAS,CAAC,CAAC;QACxD,OAAO,MAAM,CAAC;IAChB,CAAC;IAAC,MAAM,CAAC;QAAC,MAAM,IAAI,KAAK,CAAC,iCAAiC,CAAC,CAAC;IAAC,CAAC;AACjE,CAAC"}
+{"version":3,"file":"lock-scope.js","sourceRoot":"","sources":["../../../src/evidence/original-run/lock-scope.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,IAAI,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;AACjC,MAAM,CAAC,MAAM,SAAS,GAAG,gEAAgE,CAAC;AAC1F,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC,kBAAkB,CAAC,UAAU,EAAE;IAC9D,CAAC,CAAC,MAAM,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,SAAS,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE;IACvH,CAAC,CAAC,MAAM,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,SAAS,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,gBAAgB,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE;CACtI,CAAC,CAAC;AAGH,wFAAwF;AACxF,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,IAAY,EAAE,IAAc,EAAE,SAAS,GAAG,KAAK;IACrF,MAAM,GAAG,GAAG,OAAO,CAAC,QAAQ,KAAK,OAAO,IAAI,OAAO,CAAC,GAAG,CAAC,UAAU;QAChE,CAAC,CAAC,EAAE,UAAU,EAAE,OAAO,CAAC,GAAG,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,UAAU,EAAE;QACxE,CAAC,CAAC,EAAE,IAAI,EAAE,+BAA+B,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC;IAC3D,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE;QACxC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,IAAI,GAAG,IAAI;QAC5D,GAAG;KACJ,CAAC,CAAC;IACH,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,KAAK,UAAU,SAAS;IACtB,2EAA2E;IAC3E,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,iCAAiC,EAAE,GAAG,CAAC,CAAC;IAClE,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAAC,MAAM,EAAE,SAAS,EAAE,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;QACpG,OAAO,KAAK,CAAC,QAAQ,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IACvD,CAAC;YAAS,CAAC;QAAC,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;IAAC,CAAC;AACrC,CAAC;AAQD,MAAM,UAAU,cAAc,CAAC,KAAc;IAC3C,OAAO,eAAe,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC;AAClD,CAAC;AAED,2EAA2E;AAC3E,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,YAA8B,EAAE;IACnE,MAAM,EAAE,GAAY;QAClB,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,OAAO,EAAE,iBAAiB,EAAE,IAAI,EAAE,SAAS;QACvE,SAAS,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,mBAAmB,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,GAAG,SAAS;KAC3E,CAAC;IACF,IAAI,CAAC;QACH,IAAI,MAAiB,CAAC;QACtB,IAAI,EAAE,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;YAC7B,MAAM,IAAI,GAAG,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,kBAAkB,EAAE,CAAC,IAAI,EAAE,sBAAsB,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;YACzG,MAAM,GAAG,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC;QAC7D,CAAC;aAAM,IAAI,EAAE,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;YACnC,MAAM,IAAI,GAAG,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;YAAC,MAAM,EAAE,GAAG,MAAM,EAAE,CAAC,SAAS,EAAE,CAAC;YACrF,MAAM,GAAG,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,GAAG,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC;QACzE,CAAC;;YAAM,MAAM,IAAI,KAAK,CAAC,aAAa,CAAC,CAAC;QACtC,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,SAAS,CAAC,CAAC;QACxD,OAAO,MAAM,CAAC;IAChB,CAAC;IAAC,MAAM,CAAC;QAAC,MAAM,IAAI,KAAK,CAAC,iCAAiC,CAAC,CAAC;IAAC,CAAC;AACjE,CAAC"}

package/dist/index.js

@@ -33,7 +33,7 @@ import { originalRunReportSchema } from './telemetry/recovery/source.js';
 import { buildAssignments, detectProvider } from './roles/dispatcher.js';
 import { defaultAdapterFactory, runReviews } from './dispatch/runner.js';
 import { mergeChunkReviews } from './dispatch/merge.js';
-import { partitionAsyncAssignments, asyncTargetKey, resolveAsyncStoreDir, resolveExistingAsyncStoreDir, spoolAsyncCalls, launchAsyncWorkers, runAsyncWorker, collectAsyncResults, currentBranchLabel, MAX_ASYNC_CALLS_PER_ROUND, snapshotAsyncResults, consumeBoundAsyncResults, } from './dispatch/async-lane.js';
+import { partitionAsyncAssignments, asyncTargetKey, resolveAsyncStoreDir, resolveExistingAsyncStoreDir, spoolAsyncCalls, launchAsyncWorkers, runAsyncWorker, collectAsyncResults, currentBranchLabel, MAX_ASYNC_CALLS_PER_ROUND, snapshotAsyncResults, snapshotAsyncHistory, consumeBoundAsyncResults, } from './dispatch/async-lane.js';
 import { evaluateCiGate } from './ci.js';
 import { resolveQuorumPolicy } from './dispatch/quorum.js';
 import { assertAdmissibleReportHealth, deriveBlockingHealth, describeBlockingHealth, ReportHealthError } from './report/blocking-health.js';
@@ -226,6 +226,7 @@ program
     .option('--head-sha <sha>', 'Exact head commit a patch file was taken from (patch files only)')
     .option('--base-sha <sha>', 'Exact base commit a patch file was taken from (patch files only)')
     .option('--expect-head-sha <sha>', 'Fail fast unless the resolved head commit equals this SHA')
+    .option('--expect-pr-head-sha <sha>', 'Finalize-only cycle recovery: fail unless the live pull request remains open at this current head')
     .option('--spec-source <source>', 'Where --spec came from: flag | repo_file | harness_issue:<ID>')
     .option('--converge-target <key>', 'Converge target this round belongs to (or RCL_CONVERGE_TARGET)')
     .option('--for-pr <owner/repo#N>', 'The pull request a patch-file review is evidence for (or RCL_FOR_PR): Harness verifies its head against that pull request')
@@ -237,12 +238,13 @@ program
     .option('--launch-intent <intent>', 'Guarded intent: review, stop-upstream, stop-review, or retry-delivery')
     .option('--retry-report <path>', 'Original legacy report proving an inconclusive launch; the new inputs may differ; requires --retry-reason')
     .option('--resume-pending', 'Finalize an unobservable pending legacy dispatch, then claim one fresh checkpointed retry under its target lock')
-    .option('--finalize-pending-only', 'Finalize one authenticated ordinary pending launch without claiming or dispatching its successor')
+    .option('--finalize-pending-only', 'Finalize one authenticated pending launch without claiming or dispatching its successor')
     .option('--pending-native-sha256 <digest>', 'Finalize-only: exact native state digest returned by --preview-pending')
     .option('--pending-attempt-sha256 <digest>', 'Finalize-only: exact attempt state digest returned by --preview-pending')
-    .option('--export-pending-package <path>', 'Export authenticated ordinary pending inputs to an exclusive private file without provider calls or native writes')
+    .option('--pending-preview-sha256 <digest>', 'Changed-head cycle finalize-only: exact preview binding returned by --preview-pending')
+    .option('--export-pending-package <path>', 'Export authenticated pending inputs to an exclusive private file without provider calls or native writes')
     .option('--expect-base-sha <sha>', 'Pending package export: require the resolved current base to equal this SHA')
-    .option('--ordinary-pending-package <path>', 'Immutable ordinary pending-launch package; requires --resume-pending or --finalize-pending-only and replaces --retry-report')
+    .option('--ordinary-pending-package <path>', 'Immutable pending-launch package; requires --resume-pending or --finalize-pending-only and replaces --retry-report')
     .option('--preview-pending', 'Authenticate pending recovery or preview a pending package export without provider calls')
     .option('--resume-async-sha256 <hashes>', 'Comma-separated SHA-256 bindings for every legacy async result retained as historical evidence')
     .option('--retry-reason <reason>', 'Explicit bounded recovery decision for a previous failed or unknown launch; never resets caps')
@@ -1627,7 +1629,7 @@ async function runReview(target, opts) {
         const finalizeOnlyIgnoredReviewFlags = opts.retryReason !== undefined || opts.maxRounds !== undefined ||
             opts.round !== undefined || opts.attempt !== undefined || opts.post || opts.json ||
             opts.jsonFile !== undefined || opts.markdown !== undefined || opts.ci || opts.evidenceRequired ||
-            opts.forPr !== undefined || opts.role !== undefined || opts.roles !== undefined ||
+            opts.role !== undefined || opts.roles !== undefined ||
             opts.models !== undefined || opts.secondaryModels !== undefined || opts.asyncModels !== undefined ||
             (opts.reviewer?.length ?? 0) > 0 || (opts.context?.length ?? 0) > 0 ||
             opts.spec !== undefined || opts.focus !== undefined;
@@ -1636,12 +1638,17 @@ async function runReview(target, opts) {
             opts.retryReport !== undefined || !opts.resumeAsyncSha256 || opts.maxAttempts === undefined ||
             (!opts.previewPending && (!opts.pendingNativeSha256 || !opts.pendingAttemptSha256)) ||
             (opts.previewPending && (opts.pendingNativeSha256 !== undefined || opts.pendingAttemptSha256 !== undefined)) ||
+            (opts.expectPrHeadSha !== undefined && !opts.previewPending && !opts.pendingPreviewSha256) ||
+            (opts.pendingPreviewSha256 !== undefined && opts.expectPrHeadSha === undefined) ||
+            (opts.expectPrHeadSha !== undefined && opts.forPr === undefined) ||
+            (opts.previewPending && opts.pendingPreviewSha256 !== undefined) ||
             opts.startOver || opts.boundFixRecovery || opts.attest || opts.launchIntent !== undefined ||
             finalizeOnlyIgnoredReviewFlags || finalizeOnlySourceFlags)) {
             throw new ReviewLaunchRefused('pending_finalize_incompatible', '--finalize-pending-only accepts only guarded target/head/base/config bindings, one ordinary pending package, an explicit unchanged attempt cap, retained async result digests and, for apply, both exact state digests from preview; do not combine it with review, output, evidence or retry flags.');
         }
         if (!opts.finalizePendingOnly &&
-            (opts.pendingNativeSha256 !== undefined || opts.pendingAttemptSha256 !== undefined)) {
+            (opts.pendingNativeSha256 !== undefined || opts.pendingAttemptSha256 !== undefined ||
+                opts.pendingPreviewSha256 !== undefined || opts.expectPrHeadSha !== undefined)) {
             throw new ReviewLaunchRefused('pending_finalize_incompatible', 'Pending native and attempt state digests apply only to --finalize-pending-only.');
         }
         if (!opts.resumePending && !opts.finalizePendingOnly &&
@@ -1704,6 +1711,14 @@ async function runReview(target, opts) {
             validateSha(opts.baseSha, '--base-sha');
         if (opts.expectHeadSha !== undefined)
             validateSha(opts.expectHeadSha, '--expect-head-sha');
+        if (opts.expectPrHeadSha !== undefined)
+            validateSha(opts.expectPrHeadSha, '--expect-pr-head-sha');
+        if (opts.pendingPreviewSha256 !== undefined && !/^[a-f0-9]{64}$/.test(opts.pendingPreviewSha256)) {
+            throw new ReviewLaunchRefused('pending_finalize_incompatible', '--pending-preview-sha256 must be a lowercase SHA-256 digest.');
+        }
+        if (opts.expectPrHeadSha !== undefined && !opts.finalizePendingOnly) {
+            throw new ReviewLaunchRefused('pending_finalize_incompatible', '--expect-pr-head-sha applies only to cycle-backed --finalize-pending-only recovery.');
+        }
         if (opts.evidenceRequired && patchTarget && opts.headSha === undefined) {
             throw new Error('--evidence-required needs --head-sha for a patch file: evidence must bind to the commit it reviewed.');
         }
@@ -1851,12 +1866,13 @@ async function executeCouncil(spinner, prepared, diff, opts, extra, preparedWork
         let completion;
         const common = await resolveGitCommonDir();
         if (opts.exportPendingPackage) {
+            const pendingNative = await loadConvergeRunState(common, prepared.converge.target);
             const receipt = await exportOrdinaryPendingPackage({ gitCommonDir: common,
                 target: prepared.converge.target, headSha: extra.target.headSha ?? '', baseSha: extra.target.baseSha ?? '',
                 expectedBaseSha: opts.expectBaseSha, expectedRound: prepared.converge.round,
                 guardedInput, path: opts.exportPendingPackage,
                 preview: opts.previewPending === true, asyncStoreDir: await resolveExistingAsyncStoreDir(),
-                asyncTargetKey: asyncTargetKey(extra.asyncTargetLabel ?? prepared.converge.target, extra.target.kind === 'patch' ? prepared.converge.target : undefined),
+                asyncTargetKey: asyncTargetKey(extra.asyncTargetLabel ?? prepared.converge.target, extra.target.kind === 'patch' ? prepared.converge.target : undefined, pendingNative?.cycle?.id),
                 asyncDescriptors: ordinaryAsyncDescriptors });
             spinner.stop();
             console.log(JSON.stringify(receipt));
@@ -1880,19 +1896,38 @@ async function executeCouncil(spinner, prepared, diff, opts, extra, preparedWork
             const runtime = await createTelemetryRuntime({ rclVersion: RCL_VERSION, config, noTelemetry: opts.telemetry === false });
             if (!runtime.sink || runtime.level !== 'full')
                 throw new Error('Fresh review cycles require full Harness evidence and an actor credential');
-            cycleRemote = createReviewCycleRemote(runtime.sink, extra.target.repo, extra.target.prNumber, extra.target.headSha ?? '');
+            cycleRemote = createReviewCycleRemote(runtime.sink, extra.target.repo, extra.target.prNumber, opts.expectPrHeadSha ?? extra.target.headSha ?? '');
         }
         if (opts.resumePending || opts.finalizePendingOnly) {
-            const expectedAsyncSha256 = opts.resumeAsyncSha256.split(',').map(value => value.trim());
-            if (expectedAsyncSha256.length === 0 || expectedAsyncSha256.some(value => !/^[a-f0-9]{64}$/.test(value)) ||
-                new Set(expectedAsyncSha256).size !== expectedAsyncSha256.length) {
-                throw new ReviewLaunchRefused('pending_async_binding_invalid', 'Retained async SHA-256 bindings must be unique lowercase 64-character digests.');
+            const asyncBinding = opts.resumeAsyncSha256.trim();
+            const expectedAsyncSha256 = asyncBinding === 'none'
+                ? [] : asyncBinding.split(',').map(value => value.trim());
+            if (expectedAsyncSha256.some(value => !/^[a-f0-9]{64}$/.test(value))) {
+                throw new ReviewLaunchRefused('pending_async_binding_invalid', 'Retained async bindings must be comma-separated lowercase SHA-256 digests, or "none" for an empty cycle history.');
             }
             const migrationPackage = opts.ordinaryPendingPackage === undefined ? undefined : JSON.parse((await readStable(opts.ordinaryPendingPackage)).text);
+            if (opts.expectPrHeadSha !== undefined && migrationPackage?.version !== 2) {
+                throw new ReviewLaunchRefused('pending_finalize_incompatible', '--expect-pr-head-sha requires a cycle-backed version-2 pending package.');
+            }
+            if (opts.finalizePendingOnly && opts.forPr !== undefined && migrationPackage?.version !== 2) {
+                throw new ReviewLaunchRefused('pending_finalize_incompatible', '--for-pr finalize-only recovery requires a cycle-backed version-2 pending package.');
+            }
+            if (migrationPackage?.version !== 2 && (expectedAsyncSha256.length === 0 ||
+                new Set(expectedAsyncSha256).size !== expectedAsyncSha256.length)) {
+                throw new ReviewLaunchRefused('pending_async_binding_invalid', 'Ordinary retained async SHA-256 bindings must be non-empty and unique.');
+            }
+            if (migrationPackage?.version === 2 && opts.resumePending) {
+                throw new ReviewLaunchRefused('cycle_pending_finalize_only', 'Cycle-backed packages can only terminalize the unknown original attempt. Launch a later successor normally after its terminal receipt verifies.');
+            }
             const loadMigrationRetainedAsync = async () => {
                 if (!migrationPackage)
                     throw new ReviewLaunchRefused('pending_async_missing', 'An ordinary package is required.');
                 const store = await resolveExistingAsyncStoreDir();
+                if (migrationPackage.version === 2) {
+                    const key = asyncTargetKey(extra.asyncTargetLabel ?? prepared.converge.target, extra.target.kind === 'patch' ? prepared.converge.target : undefined, migrationPackage.cycle.id);
+                    const snapshot = await snapshotAsyncHistory(store, key, (migrationPackage.attemptsUsed + 1) * MAX_ASYNC_CALLS_PER_ROUND, expectedAsyncSha256);
+                    return snapshot.artifacts;
+                }
                 const wanted = new Map(migrationPackage.retainedAsync.map(item => [item.sha256, item]));
                 const found = new Map();
                 for (const name of await readdir(store)) {
@@ -1929,6 +1964,8 @@ async function executeCouncil(spinner, prepared, diff, opts, extra, preparedWork
                     migrationPackage, maxAttempts: Number(opts.maxAttempts), maxPhysicalCalls: 1, maxAttemptsPerCell: 1,
                     maxDurationMs: 1, validate: async () => { }, loadRetainedAsync: loadMigrationRetainedAsync,
                     run: async () => { throw new Error('preview_must_not_run'); }, preview: true,
+                    cycleRemote,
+                    ...(opts.expectPrHeadSha === undefined ? {} : { currentPrHeadSha: opts.expectPrHeadSha }),
                     previewMode: opts.finalizePendingOnly ? 'finalize-only' : 'combined' });
                 spinner.stop();
                 console.log(JSON.stringify({
@@ -1943,7 +1980,16 @@ async function executeCouncil(spinner, prepared, diff, opts, extra, preparedWork
                     baseSha: extra.target.baseSha ?? '', pendingInputSha256: inputSha256,
                     nativeStateSha256: opts.pendingNativeSha256, attemptStateSha256: opts.pendingAttemptSha256,
                     retainedAsyncSha256: expectedAsyncSha256, migrationPackage,
-                    maxAttempts: Number(opts.maxAttempts), loadRetainedAsync: loadMigrationRetainedAsync });
+                    maxAttempts: Number(opts.maxAttempts), cycleRemote,
+                    ...(opts.expectPrHeadSha === undefined ? {} : {
+                        currentPrHeadSha: opts.expectPrHeadSha, previewSha256: opts.pendingPreviewSha256,
+                    }),
+                    loadRetainedAsync: loadMigrationRetainedAsync,
+                    ...(migrationPackage.version === 2 ? { cycleHistory: {
+                            resolveStoreDir: resolveExistingAsyncStoreDir,
+                            targetKey: asyncTargetKey(extra.asyncTargetLabel ?? prepared.converge.target, extra.target.kind === 'patch' ? prepared.converge.target : undefined, migrationPackage.cycle.id),
+                            maxResults: (migrationPackage.attemptsUsed + 1) * MAX_ASYNC_CALLS_PER_ROUND,
+                        } } : {}) });
                 spinner.stop();
                 console.log(JSON.stringify({ mode: 'finalize-only', ...result }));
                 return undefined;