@allocator-one/rcl 4.5.21 → 4.5.22

package/dist/converge/pr-snapshot.js

@@ -0,0 +1,76 @@
+import { constants } from 'node:fs';
+import { lstat, open } from 'node:fs/promises';
+import { z } from 'zod';
+import { readStable, sha256 } from '../telemetry/recovery/files.js';
+/**
+ * A pull request's live state, read once by a parent process that holds
+ * GitHub credentials and handed to a review process that holds none (RCL-216).
+ *
+ * Grid hosts strip GitHub credentials from every reviewer process on purpose,
+ * yet a review cycle must confirm that the pull request is still open at the
+ * head under review. The parent captures that state with `rcl pr-snapshot`
+ * shortly before launching, and the review reads it with `--pr-snapshot`
+ * instead of calling GitHub. Harness still verifies the reviewed head against
+ * the pull request when the evidence arrives; this snapshot only replaces the
+ * reviewer's own pre-launch read.
+ */
+export const PR_SNAPSHOT_MAX_AGE_MS = 15 * 60 * 1000;
+const MAX_FUTURE_SKEW_MS = 60 * 1000;
+const MAX_SNAPSHOT_BYTES = 16 * 1024;
+export const prSnapshotSchema = z.object({
+    kind: z.literal('rcl-pr-snapshot'),
+    version: z.literal(1),
+    repo: z.string().regex(/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/),
+    prNumber: z.number().int().positive().safe(),
+    headSha: z.string().regex(/^[a-f0-9]{40}$/),
+    baseSha: z.string().regex(/^[a-f0-9]{40}$/),
+    baseRef: z.string().min(1).max(255),
+    merged: z.boolean(),
+    state: z.string().min(1).max(32),
+    fetchedAt: z.string().datetime({ offset: true }),
+}).strict();
+/** The fields a snapshot keeps from GitHub's pull request object. */
+export function prSnapshotFrom(repo, prNumber, pr, now = new Date()) {
+    return prSnapshotSchema.parse({ kind: 'rcl-pr-snapshot', version: 1, repo: repo.toLowerCase(), prNumber,
+        headSha: pr.head.sha, baseSha: pr.base.sha, baseRef: pr.base.ref, merged: pr.merged === true, state: pr.state,
+        fetchedAt: now.toISOString() });
+}
+/** Write a new snapshot exclusively, readable by its owner only; answer its SHA-256. */
+export async function writePrSnapshot(path, snapshot) {
+    const bytes = Buffer.from(`${JSON.stringify(prSnapshotSchema.parse(snapshot), null, 2)}\n`);
+    const handle = await open(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+    try {
+        await handle.writeFile(bytes);
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+    return sha256(bytes);
+}
+/**
+ * Read a snapshot for `repo#prNumber` and answer the live state it records.
+ * Refuses a file another user could have written, one for another pull
+ * request, and one older than {@link PR_SNAPSHOT_MAX_AGE_MS}: an old reading
+ * cannot stand in for the live check.
+ */
+export async function readPrSnapshot(path, repo, prNumber, now = Date.now()) {
+    const stat = await lstat(path);
+    if (!stat.isFile() || stat.isSymbolicLink() || (process.platform !== 'win32' &&
+        (stat.uid !== process.geteuid?.() || (stat.mode & 0o022) !== 0)))
+        throw new Error('pr_snapshot_unsafe_file');
+    let snapshot;
+    try {
+        snapshot = prSnapshotSchema.parse(JSON.parse((await readStable(path, MAX_SNAPSHOT_BYTES)).text));
+    }
+    catch {
+        throw new Error('pr_snapshot_invalid');
+    }
+    if (snapshot.repo.toLowerCase() !== repo.toLowerCase() || snapshot.prNumber !== prNumber)
+        throw new Error('pr_snapshot_pull_request_mismatch');
+    const age = now - Date.parse(snapshot.fetchedAt);
+    if (age > PR_SNAPSHOT_MAX_AGE_MS || age < -MAX_FUTURE_SKEW_MS)
+        throw new Error('pr_snapshot_stale');
+    return { headSha: snapshot.headSha, merged: snapshot.merged, state: snapshot.state };
+}
+//# sourceMappingURL=pr-snapshot.js.map

package/dist/converge/pr-snapshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pr-snapshot.js","sourceRoot":"","sources":["../../src/converge/pr-snapshot.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -4,6 +4,8 @@ import { guardedDeliveryState } from './telemetry/deliver.js';
 import { AmbiguousReviewerIdentityError, assertUnambiguousReviewerIdentities } from './dispatch/reviewer-identity.js';
 import { retainAssemblyRefusal } from './output/assembly-refusal.js';
 import { createReviewCycleRemote } from './converge/cycle-remote.js';
+import { prSnapshotFrom, readPrSnapshot, writePrSnapshot } from './converge/pr-snapshot.js';
+import { applyFreshReviewClose, previewFreshReviewClose } from './converge/fresh-review-close.js';
 import { assertNoPendingFreshReview, freshReviewOutputPaths } from './converge/fresh-review.js';
 import { previewStaleReport, applyStaleReport } from './converge/stale-report.js';
 import { previewHistoricalDeliveryReconciliation, applyHistoricalDeliveryReconciliation } from './converge/historical-delivery-reconciliation.js';
@@ -239,6 +241,7 @@ program
     .option('--round <n>', 'Converge round number (or RCL_CONVERGE_ROUND)')
     .option('--attempt <n>', 'Converge attempt number (or RCL_CONVERGE_ATTEMPT)')
     .option('--start-over', 'Start an explicitly requested fresh review with a new normal budget; retain all prior evidence and spending')
+    .option('--pr-snapshot <path>', 'Live pull request state from `rcl pr-snapshot`, captured by a parent that holds GitHub credentials; review cycles read it instead of GitHub (RCL-216)')
     .option('--guarded-converge', 'Validate and claim inside this review process, or consume an exact recovered-v3 --attempt; derive the round from native state')
     .option('--bound-fix-recovery <run-id>', 'Review unchanged inputs once live Harness evidence proves a retained bound fix obligation after this native dismissal-only run')
     .option('--launch-intent <intent>', 'Guarded intent: review, stop-upstream, stop-review, or retry-delivery')
@@ -519,6 +522,71 @@ program
         process.exitCode = 3;
     }
 });
+program
+    .command('pr-snapshot <pr>')
+    .description('Capture a pull request\'s live state (head, base, open/merged) for a review process that holds no GitHub ' +
+    'credentials: run it in the parent, then pass the file to `rcl review --pr-snapshot` within 15 minutes (RCL-216)')
+    .requiredOption('--out <path>', 'New file to write (refuses an existing one); readable by its owner only')
+    .option('--config <path>', 'Path to config file')
+    .option('--json')
+    .action(async (pr, opts) => {
+    try {
+        if (!isGitHubTarget(pr))
+            throw new Error('pr_snapshot_requires_pull_request');
+        const target = parseGitHubTarget(pr);
+        const config = await loadConfig(opts.config);
+        const { data } = await getGitHubPullRequest(await createGitHubClient(config.githubToken), target);
+        const snapshot = prSnapshotFrom(`${target.owner}/${target.repo}`, target.number, data);
+        const digest = await writePrSnapshot(opts.out, snapshot);
+        console.log(opts.json ? JSON.stringify({ snapshot, path: opts.out, sha256: digest })
+            : `Wrote ${opts.out}: ${snapshot.repo}#${snapshot.prNumber} ${snapshot.state} at ${snapshot.headSha} (sha256 ${digest})`);
+    }
+    catch (error) {
+        console.error(JSON.stringify({ error: { code: 'RCL_PR_SNAPSHOT', message: error instanceof Error ? error.message : String(error) } }));
+        process.exitCode = 3;
+    }
+});
+program
+    .command('converge-close-fresh')
+    .description('Preview or apply an audited close of a fresh-review operation whose launch died before writing any report; ' +
+    'never creates a round, finding, verdict or attempt (RCL-216)')
+    .option('--preview')
+    .option('--apply')
+    .option('--target <target>')
+    .option('--operation <uuid>', 'The fresh-review operation to close (its native current operation)')
+    .requiredOption('--manifest <path>', 'Exclusive preview manifest; the reviewed manifest for apply')
+    .option('--manifest-sha256 <sha256>', 'Exact reviewed manifest bytes; required for apply')
+    .option('--json')
+    .action(async (opts) => {
+    try {
+        if ([opts.preview, opts.apply].filter(Boolean).length !== 1)
+            throw new Error('choose_exactly_one_fresh_close_mode');
+        const gitCommonDir = await resolveGitCommonDir();
+        let result;
+        if (opts.preview) {
+            if (opts.manifestSha256 !== undefined)
+                throw new Error('preview_does_not_accept_manifest_digest');
+            if (typeof opts.target !== 'string' || typeof opts.operation !== 'string')
+                throw new Error('fresh_close_preview_arguments_required');
+            const manifest = await previewFreshReviewClose({ target: opts.target, operationId: opts.operation }, gitCommonDir);
+            await writeExclusive(opts.manifest, manifest, 256 * 1024);
+            result = { mode: 'preview', manifest, manifestSha256: sha256(serializeRecoveryDocument(manifest)), accounting: 'unchanged',
+                scope: 'local operation close; no admission or approval' };
+        }
+        else {
+            if (opts.target !== undefined || opts.operation !== undefined)
+                throw new Error('apply_uses_only_pinned_manifest');
+            result = { mode: 'apply', result: await applyFreshReviewClose({ manifest: opts.manifest,
+                    manifestSha256: opts.manifestSha256 }, gitCommonDir), accounting: 'unchanged',
+                scope: 'local operation close; no admission or approval' };
+        }
+        console.log(JSON.stringify(result));
+    }
+    catch (error) {
+        console.error(JSON.stringify({ error: { code: 'RCL_CONVERGE_CLOSE_FRESH', message: error instanceof Error ? error.message : String(error) } }));
+        process.exitCode = 3;
+    }
+});
 program
     .command('converge-gap')
     .description('Preview, apply or resume one evidenced missing-terminal-report audit gap; never creates a round, finding, verdict or attempt')
@@ -2022,6 +2090,10 @@ async function executeCouncil(spinner, prepared, diff, opts, extra, preparedWork
                 throw new Error('Fresh review cycles require full Harness evidence and an actor credential');
             const prTarget = parseGitHubTarget(`${extra.target.repo}#${extra.target.prNumber}`);
             cycleRemote = createReviewCycleRemote(runtime.sink, extra.target.repo, extra.target.prNumber, opts.expectPrHeadSha ?? extra.target.headSha ?? '', async () => {
+                // A parent with GitHub credentials hands the live state over, so this
+                // review process needs none (RCL-216).
+                if (opts.prSnapshot !== undefined)
+                    return readPrSnapshot(opts.prSnapshot, extra.target.repo, extra.target.prNumber);
                 const client = await createGitHubClient(config.githubToken);
                 const auth = await client.auth();
                 if (typeof auth !== 'object' || auth === null || !('type' in auth) || auth.type !== 'token') {