@uchibeke/gallivant 0.0.0-stage → 0.2.1

package/lib/codex_cloud.mjs

@@ -0,0 +1,160 @@
+// Supported CLI only. There is no private Cloud HTTP client or review engine.
+import { join } from "node:path";
+import { execFileAsync, repositoryMatches } from "./gh.mjs";
+import { ensureDir, readJson, writeJsonAtomic } from "./fs.mjs";
+import { executionError, dispatchNotSentError, redact, accessProbeFailure } from "./execution_io.mjs";
+import { validateCloudConfig, CLOUD_VERSION, CLOUD_DISPATCH_UNAVAILABLE } from "./codex_cloud_config.mjs";
+import { contentHash } from "./openai_agents_sources.mjs";
+import { cloudDiffResult, CLOUD_RESULT_PATH } from "./codex_cloud_result.mjs";
+import { requireVerificationSandbox } from "./execution_result.mjs";
+const taskIdFor = value => {
+  if (typeof value !== "string" || !/^task_[a-zA-Z0-9_-]{1,200}$/.test(value)) throw executionError("CLOUD_PROTOCOL", "unsupported Cloud task ID; preserve acknowledgement for operator reconciliation");
+  return value;
+};
+const taskUrl = id => `https://chatgpt.com/codex/tasks/${taskIdFor(id)}`;
+const stateFor = status => ({ pending: "queued", ready: "succeeded", applied: "succeeded", error: "failed" })[status];
+export function cloudCli(config, exec = execFileAsync) {
+  return async (args, signal) => {
+    // The shared request signal owns the deadline, including submission's
+    // acknowledgement window. Keep a bound only for standalone diagnostic calls.
+    const { stdout, stderr } = await exec(config.bin, args, { signal, timeout: signal ? 0 : 10_000, maxBuffer: 1_048_576,
+      // No GitHub/API credentials or model overrides travel to the CLI. Its own
+      // operator sign-in store stays native, outside generated source/prompts.
+      env: Object.fromEntries(["PATH", "HOME", "CODEX_HOME", "LANG", "LC_ALL", "TMPDIR", "XDG_CONFIG_HOME", "XDG_DATA_HOME"].filter(key => typeof process.env[key] === "string").map(key => [key, process.env[key]])) });
+    return args[0] === "login" ? `${stdout}${stderr || ""}` : stdout;
+  };
+}
+async function listPage(cli, config, signal, cursor = null) {
+  const args = ["cloud", "list", "--json", "--env", config.environment, "--limit", "20"];
+  if (cursor !== null) args.push("--cursor", cursor);
+  let page;
+  try { page = JSON.parse(await cli(args, signal)); } catch (error) { if (signal?.aborted) throw error; throw executionError("CLOUD_LIST", "Cloud listing failed; check the authorized account/environment using the configured CLI"); }
+  if (!Array.isArray(page.tasks) || page.tasks.length > 20 || page.cursor != null && (typeof page.cursor !== "string" || !page.cursor || page.cursor.length > 4096)) throw executionError("CLOUD_PROTOCOL", "invalid Cloud listing page/cursor");
+  return page;
+}
+async function checkCloudVersion(cli, signal) {
+  // Experimental output formats are pinned, rather than assuming a future
+  // CLI has the same semantics. Recheck every operation, including recovery:
+  // the configured executable may have changed since acknowledgement.
+  const version = (await cli(["--version"], signal)).trim();
+  if (version !== `codex-cli ${CLOUD_VERSION}`) throw executionError("CLOUD_VERSION", `install the qualified Codex ${CLOUD_VERSION} at the configured bin; requalify before changing versions`);
+  return version;
+}
+export async function checkCloudAccess(config, { signal, cli = null } = {}) {
+  try {
+    validateCloudConfig(config); signal ||= AbortSignal.timeout(10_000); cli ||= cloudCli(config);
+    const version = await checkCloudVersion(cli, signal);
+    if (!(await cli(["login", "status"], signal)).includes("Logged in using ChatGPT")) throw executionError("CLOUD_AUTH", "sign in with the authorized operator's ChatGPT account using the configured Codex login; API-key login is unsupported");
+    for (const [command, flags] of [["exec", ["--env", "--branch", "--attempts"]], ["list", ["--env", "--json", "--cursor", "--limit"]], ["diff", ["--attempt"]]]) {
+      const help = await cli(["cloud", command, "--help"], signal);
+      if (flags.some(flag => !help.includes(flag))) throw executionError("CLOUD_VERSION", "required documented Cloud command capability missing");
+    }
+    await listPage(cli, config, signal);
+    signal.throwIfAborted();
+    // Listing proves read access to --env, never its connected repository. The
+    // pinned documented CLI has no mapping query, and exec accepts no repo.
+    // Keep diagnostics and owned-task recovery, but do not authorize paid work.
+    return { ok: false, detail: CLOUD_DISPATCH_UNAVAILABLE.detail, fix: CLOUD_DISPATCH_UNAVAILABLE.fix,
+      diagnostics: `${version}; ChatGPT sign-in and selected environment listing authorized; repository mapping and inference unverified`,
+      effective: { account: config.account, environment: config.environment, repository: null, continuation: "successor-task", costSource: config.billing_source, hardSpendCap: false, nativeCancel: false, providerAttemptId: null } };
+  } catch (error) { return accessProbeFailure(error,signal,"CLOUD_ACCESS",typeof error.code==='string'?redact(error.message):"Check the configured executable, authorized ChatGPT login and published Cloud environment; see docs/codex-cloud.md"); }
+}
+export function makeCloudTransport({ root, taskId, account, config, cli = cloudCli(config), clock = Date, verification = requireVerificationSandbox, verifyRemote = null, checkAccess = checkCloudAccess }) {
+  const path = join(root, "cloud.json");
+  const read = () => {
+    const s = readJson(path, { version: 1, taskId, account, environment: config.environment, repository: config.repository, operations: {} });
+    if (s.version !== 1 || s.taskId !== taskId || s.account !== account || s.environment !== config.environment || !repositoryMatches(s.repository, config.repository)) throw executionError("EXECUTION_OWNERSHIP", "Cloud task/account/environment ownership changed; restore recorded configuration");
+    return s;
+  };
+  const save = s => { ensureDir(root); writeJsonAtomic(path, s); };
+  const ack = op => ({ providerJobId: op.taskId, sessionId: op.logicalSessionId, turnId: op.taskId, environment: config.environment,
+    effective: { taskUrl: op.url, continuity: op.continuity, parentTaskId: op.parentTaskId, attemptSelector: 1, providerAttemptId: null, rootIdentity: "cloud-task", costSource: config.billing_source, tokenToolLogs: "unavailable" } });
+  const owned = (s, req) => {
+    const op = Object.values(s.operations).find(op => op.taskId === req.providerJobId);
+    if (!op || op.logicalSessionId !== req.sessionId || req.turnId !== op.taskId) throw executionError("EXECUTION_OWNERSHIP", "Cloud request does not own the exact saved task and single-attempt selector");
+    return op;
+  };
+  async function prepare(req) {
+    validateCloudConfig(config);
+    if (!repositoryMatches(req.repo, config.repository) || req.environment !== config.environment || req.mandatoryPolicy?.length) throw executionError("CLOUD_SOURCE", "selected repository/environment or policy differs");
+    const source = req.sources;
+    if (!source || !/^[a-f0-9]{40,64}$/.test(req.inputHead || "") || source.inputHead !== req.inputHead || source.repo !== req.repo || source.branch !== req.branch || source.inputBranch !== `${req.branch}-cloud-${req.inputHead}` || contentHash(Buffer.from(source.data || "", "base64")) !== source.hash) throw executionError("CLOUD_SOURCE", "Cloud needs an exact verified pushed snapshot and immutable input branch");
+    if (typeof req.prompt !== "string" || Buffer.byteLength(req.prompt) > 65_536 || /(?:\/Users\/|\/home\/|file:\/\/|[A-Z]:\\)/.test(req.prompt)) throw executionError("CLOUD_SOURCE", "Cloud input contains oversized context or absolute local paths; deliver approved repository snapshots");
+    await verification({ signal: req.signal });
+    const access = await checkAccess(config, { cli, signal: req.signal });
+    if (!access.ok) throw executionError(access.detail, access.fix);
+    if (!repositoryMatches(access.effective?.repository, req.repo) || access.effective.environment !== config.environment) throw executionError(CLOUD_DISPATCH_UNAVAILABLE.detail, CLOUD_DISPATCH_UNAVAILABLE.fix);
+    if (typeof verifyRemote !== "function") throw executionError("CLOUD_SOURCE", "Cloud dispatch requires the coordinator's remote revision/hash verifier");
+    await verifyRemote(req);
+    return { effective: access.effective };
+  }
+  async function dispatch(req, continuing = false) {
+    const s = read(), prior = s.operations[req.idempotencyKey];
+    if (prior) {
+      if (prior.taskId) return ack(prior);
+      throw executionError("EXECUTION_UNKNOWN", "Cloud acknowledgement unknown; inspect saved dispatch, never resubmit");
+    }
+    let previous;
+    try {
+      await prepare(req);
+      if (continuing) {
+        previous = Object.values(s.operations).findLast(op => op.logicalSessionId === req.sessionId && op.taskId);
+        if (!previous || !["succeeded", "failed"].includes(previous.state)) throw executionError("EXECUTION_CONTINUATION", "successor requires the same logical session and settled owned predecessor");
+      }
+    } catch (error) { throw dispatchNotSentError(error); }
+    const op = { runId: req.runId, name: req.name, key: req.idempotencyKey, inputHead: req.inputHead, repo: req.repo, branch: req.branch, base: req.base, sources: req.sources,
+      taskId: null, logicalSessionId: req.sessionId || null, parentTaskId: previous?.taskId || null, continuity: continuing ? "successor-task" : "initial-task", state: "status-unknown", at: clock.now(), acceptance: "unknown" };
+    const envelope = { version: 1, inputHead: op.inputHead, repo: op.repo, branch: op.branch, runId: op.runId, sourceHashes: op.sources.hashes, pr: { title: "<neutral change title>", body: "<complete approved completion receipt>" }, tests: [] };
+    const prompt = `${req.prompt}\n\nCloud delivery contract: the coordinator is the only PR writer. Do not push, open/update a PR or contact reviewers. Verify git rev-parse HEAD equals ${op.inputHead} BEFORE making changes; stop on mismatch. Verify approved source SHA-256 hashes: ${JSON.stringify(op.sources.hashes)}. Read the approved brief and sources on this revision; local paths are not delivery.\nContinuity: ${op.continuity}; predecessor: ${op.parentTaskId || "none"}. No native session memory is transferred; the supplied current code, requirements, feedback and decisions are authoritative.\nWrite ${CLOUD_RESULT_PATH} as JSON following this exact identity envelope: ${JSON.stringify(envelope)}. Replace title/body with the actual neutral change and truthful criterion receipt. Record each actual test in tests using command (string), inputHead (exactly ${op.inputHead}), exit (integer), and output (actual output); absent tests stay an empty list. Include this file in the returned diff with all implementation changes. An approved successor may return only this envelope when source changes are unnecessary, including receipt/public-text corrections or their explicit resume; do not invent unrelated edits. The coordinator excludes the envelope from the PR, executes approved Verify commands, and publishes exactly one PR.`;
+    if (Buffer.byteLength(prompt) > 100_000) throw dispatchNotSentError(executionError("CLOUD_SIZE", "serialized Cloud delivery contract too large; reduce approved context before dispatch"));
+    s.operations[req.idempotencyKey] = op; save(s);
+    const output = (await cli(["cloud", "exec", "--env", config.environment, "--branch", op.sources.inputBranch, "--attempts", "1", prompt], req.signal)).trim();
+    const urls = output.split(/\s+/).filter(value => /^https:\/\/chatgpt\.com\/codex\/tasks\/task_[A-Za-z0-9_-]+$/.test(value));
+    if (urls.length !== 1) throw executionError("EXECUTION_UNKNOWN", "Cloud submission finished without an exact task URL; preserve intent for manual reconciliation");
+    op.taskId = taskIdFor(urls[0].split("/").at(-1)); op.url = urls[0]; op.logicalSessionId ||= op.taskId; op.acceptance = "accepted"; op.state = "queued"; op.acknowledgedAt = clock.now(); save(s);
+    return ack(op);
+  }
+  async function observe(req) {
+    const s = read(), op = owned(s, req); let cursor = null, totalBytes = 0; const seen = new Set();
+    await checkCloudVersion(cli, req.signal);
+    for (let n = 0; n < 20; n++) {
+      const page = await listPage(cli, config, req.signal, cursor); totalBytes += Buffer.byteLength(JSON.stringify(page));
+      if (totalBytes > 1_048_576) throw executionError("CLOUD_SIZE", "Cloud recovery listing exceeds 1 MiB; narrow environment or recover manually");
+      const matches = page.tasks.filter(task => task.id === op.taskId);
+      if (matches.length > 1) throw executionError("CLOUD_PROTOCOL", "duplicate Cloud listing identity");
+      if (matches.length === 1) {
+        const task = matches[0], state = stateFor(task.status);
+        // 0.160.0 resolves --env before listing, but its list mapper leaves the
+        // row's environment_id null. Every page is scoped by listPage; reject
+        // contradictory metadata when supplied without requiring that field.
+        // Missing sibling metadata cannot contradict our owned --attempts 1
+        // dispatch; an explicit non-single count still refuses collection.
+        if (!state || (task.environment_id != null && task.environment_id !== config.environment) || task.url !== taskUrl(op.taskId) || (task.attempt_total != null && task.attempt_total !== 1)) throw executionError("CLOUD_PROTOCOL", "Cloud task environment/status/attempt ownership cannot be proven; best-of-N results are not selected implicitly");
+        const observedAt = clock.now(); op.state = state; op.observedAt = observedAt; op.summary = task.summary; op.updatedAt = task.updated_at; save(s);
+        const data = { state, providerStatus: task.status, environment: config.environment, environmentSource: "filtered-listing", summary: task.summary, providerUpdatedAt: task.updated_at, taskUrl: op.url, attemptSelector: 1, providerAttemptTotal: task.attempt_total ?? null, providerAttemptId: null, diffAvailable: state === "succeeded" && task.summary?.files_changed > 0, error: state === "failed" ? "provider reports error; detailed tool/token logs unavailable" : null, tokenToolLogs: "unavailable" };
+        return { ...ack(op), state, observedAt, costUsd: null, events: [{ eventId: `cloud:${op.taskId}:${contentHash(JSON.stringify(data))}`, timestamp: observedAt, type: "status", provenance: "provider-listing", data }] };
+      }
+      if (page.cursor == null) throw executionError("CLOUD_NOT_FOUND", "exact saved Cloud task absent; retain unknown status and task link, never adopt newest task");
+      if (seen.has(page.cursor)) throw executionError("CLOUD_PROTOCOL", "repeated Cloud pagination cursor");
+      seen.add(page.cursor); cursor = page.cursor;
+    }
+    throw executionError("CLOUD_SIZE", "Cloud listing exceeds bounded 20-page recovery; no implicit task adoption");
+  }
+  async function inspect(req) {
+    try { return await observe(req); }
+    catch (error) { error.providerObservationError = true; throw error; }
+  }
+  async function collect(req) {
+    const s = read(), op = owned(s, req);
+    if (req.inputHead !== op.inputHead || !["succeeded", "failed"].includes(op.state)) throw executionError("EXECUTION_RESULT", "Cloud task/base has not authoritatively completed");
+    await checkCloudVersion(cli, req.signal);
+    const outcome = { ok: op.state === "succeeded", finished: true, cost: null, lastMessage: null, denials: [], error: op.state === "failed" ? "Cloud task failed; inspect retained native task link" : null };
+    if (!outcome.ok) return { ...ack(op), inputHead: op.inputHead, outcome };
+    const diff = await cli(["cloud", "diff", op.taskId, "--attempt", "1"], req.signal);
+    const result = await cloudDiffResult(diff, op, { signal: req.signal });
+    return { ...result, ...ack(op), inputHead: op.inputHead, outcome };
+  }
+  return { prepare, submit: req => dispatch(req), continue: req => dispatch(req, true), inspect, collect,
+    lookup: async req => { const op = read().operations[req.intent.idempotencyKey]; return op?.taskId ? inspect({ ...req, ...ack(op) }) : null; },
+    cancel: async () => ({ confirmed: false, unsupported: true }) };
+}

package/lib/codex_cloud_config.mjs

@@ -0,0 +1,20 @@
+import { isAbsolute } from "node:path";
+import { executionError } from "./execution_io.mjs";
+
+export const CLOUD_VERSION = "0.160.0";
+export const CLOUD_DISPATCH_UNAVAILABLE = Object.freeze({
+  detail: "CLOUD_ENVIRONMENT_REPOSITORY",
+  reason: `Codex Cloud ${CLOUD_VERSION} cannot verify the selected environment's connected repository; new dispatch is unavailable`,
+  fix: "Qualify and implement a supported documented environment-to-repository check before enabling Cloud dispatch; see docs/codex-cloud.md",
+});
+export function validateCloudConfig(config) {
+  const fail = message => { throw executionError("CLOUD_CONFIG", message); };
+  if (!config || typeof config.bin !== "string" || !isAbsolute(config.bin) || /[\x00-\x1f]/.test(config.bin)) fail("codex-cloud requires an explicit absolute Codex executable path");
+  if (config.account !== "operator" || config.authentication !== "operator-chatgpt" || config.mode !== "trusted-worker") fail("Cloud supports the authorized operator ChatGPT identity on a trusted worker; delegated public authentication is unqualified");
+  if (!/^[A-Za-z0-9_-]{1,128}$/.test(config.environment || "") || !/^[\w.-]+\/[\w.-]+$/.test(config.repository || "")) fail("select a published Cloud environment ID and its connected repository explicitly");
+  if (config.continuation !== "successor-task" || config.billing_source !== "chatgpt-account") fail("configure successor-task continuity and chatgpt-account billing; native resume/cancel and per-task spend are unavailable");
+  if (config.model != null || config.attempts != null && config.attempts !== 1) fail("Cloud preserves account model defaults and supports exactly one attempt; model overrides and best-of-N are unsupported");
+  if (!Number.isFinite(config.allowance?.remainingUsd) || !Number.isFinite(config.allowance?.reservedUsd) || config.allowance.reservedUsd <= 0 || config.allowance.remainingUsd < config.allowance.reservedUsd) throw executionError("EXECUTION_ALLOWANCE", "Cloud requires a positive reservation and remaining account allowance; this is not a provider billing cap");
+  if (config.mandatory_policy?.length || config.context_paths?.length) throw executionError("EXECUTION_POLICY", "Cloud cannot enforce mandatory local policy or private read-only context; use a capable backend");
+  return config;
+}

package/lib/codex_cloud_input.mjs

@@ -0,0 +1,49 @@
+import { prepareAgentsSources, contentHash, portablePath } from "./openai_agents_sources.mjs";
+import { validateCloudConfig } from "./codex_cloud_config.mjs";
+import { executionError } from "./execution_io.mjs";
+import { isOurBranch } from "./git.mjs";
+import { remoteMatches, repositoryMatches } from "./gh.mjs";
+import { acquirePublicationLock } from "./execution_result.mjs";
+import { executionLive } from "./execution.mjs";
+import { CLOUD_RESULT_PATH } from "./codex_cloud_result.mjs";
+import { taskProviderAllowance } from "./task_allowance.mjs";
+
+// Called by the same initial/resume/review dispatch boundary as the API adapter.
+// Commit only the already approved overlays in the task's isolated checkout.
+export async function cloudInput(ctx, id, entry, input, contextPaths = []) {
+  const execution = ctx.executionFor?.(id, entry.harness);
+  const lock = ctx.home ? acquirePublicationLock(ctx, id, { execution, ownsExecution: true }) : null;
+  try {
+    const saved = execution?.state();
+    if (entry.dispatch_stopped || saved?.stopped || saved?.current && executionLive(saved.current)) throw executionError("BUSY", "Cloud input cannot mutate an active or stopped task checkout");
+    return await deliverCloudInput(ctx, id, entry, input, contextPaths);
+  } finally { lock?.release(); }
+}
+async function deliverCloudInput(ctx, id, entry, input, contextPaths) {
+  const config = validateCloudConfig(ctx.config.harness[entry.harness]);
+  if (contextPaths.length) throw executionError("EXECUTION_POLICY", "Cloud cannot deliver private absolute context paths");
+  if (!repositoryMatches(entry.repo, config.repository) || !isOurBranch(entry.branch) || entry.branch === entry.base || entry.worktree === entry.checkout ||
+      await ctx.git.currentBranch(entry.worktree) !== entry.branch || !remoteMatches(await ctx.git.originOf(entry.worktree), entry.repo)) throw executionError("CLOUD_SOURCE", "Cloud requires its configured repository and isolated owned task checkout");
+  const overlays = [entry.prd && { path: entry.prd, text: ctx.readPrd(id) }, ...(entry.sources || []).map(path => ({ path, text: ctx.readSource(id, path) }))].filter(Boolean);
+  const snapshot = await prepareAgentsSources({ worktree: entry.worktree, inputHead: input.inputHead, repo: entry.repo, branch: entry.branch, base: entry.base, overlays });
+  if (Object.hasOwn(snapshot.hashes, CLOUD_RESULT_PATH)) throw executionError("CLOUD_SOURCE", "reserved Cloud result envelope path exists in the approved input; choose another repository layout before dispatch");
+  if (!await ctx.git.resultModesMatch(entry.worktree, input.inputHead, overlays.map(item => item.path))) throw executionError("CLOUD_SOURCE", "approved snapshot mode changed; preserve the checkout and repair input before dispatch");
+  await ctx.git.commitResult(entry.worktree, overlays.map(item => portablePath(item.path)));
+  const inputHead = await ctx.git.head(entry.worktree);
+  await ctx.git.pushResult(entry.worktree, entry.branch);
+  if (await ctx.gh.refSha(entry.repo, entry.branch) !== inputHead) throw executionError("CLOUD_SOURCE", "remote task branch does not match the exact committed input head");
+  const hashes = {};
+  for (const item of overlays) {
+    const text = await ctx.gh.fileAtStrict(entry.repo, item.path, inputHead);
+    if (text !== item.text) throw executionError("CLOUD_SOURCE", "approved snapshot remote bytes differ; nothing dispatched");
+    hashes[item.path] = contentHash(text);
+  }
+  // A unique input ref is never advanced by the coordinator. Cloud reads this
+  // revision even if a reviewer/operator later advances the logical PR branch.
+  const inputBranch = `${entry.branch}-cloud-${inputHead}`;
+  await ctx.git.pushSnapshotRef(entry.worktree, inputBranch);
+  if (await ctx.gh.refSha(entry.repo, inputBranch) !== inputHead || await ctx.git.head(entry.worktree) !== inputHead) throw executionError("CLOUD_SOURCE", "Cloud input revision moved before dispatch");
+  const sources = await prepareAgentsSources({ worktree: entry.worktree, inputHead, repo: entry.repo, branch: entry.branch, base: entry.base, overlays: [] });
+  return { ...input, inputHead, repo: entry.repo, branch: entry.branch, base: entry.base, environment: config.environment, allowance: taskProviderAllowance(config.allowance, entry.task),
+    mandatoryPolicy: config.mandatory_policy || [], sources: { data: sources.bytes.toString("base64"), hash: sources.hash, hashes, inputHead, inputBranch, repo: entry.repo, branch: entry.branch, snapshotHash: snapshot.hash } };
+}

package/lib/codex_cloud_result.mjs

@@ -0,0 +1,74 @@
+// Cloud diff -> bounded text manifest. Never apply a provider patch in the
+// operator/task checkout; the shared result writer remains its only mutator.
+import { mkdtempSync, rmSync, writeFileSync, mkdirSync, chmodSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, dirname } from "node:path";
+import { gunzipSync } from "node:zlib";
+import { execFileAsync } from "./gh.mjs";
+import { runEnv } from "./git.mjs";
+import { contentHash, portablePath } from "./openai_agents_sources.mjs";
+import { assertRepositoryTargets, readRepositoryText } from "./repository_files.mjs";
+import { collectionValidationError, validProviderTestRecords } from "./execution_io.mjs";
+export const CLOUD_RESULT_PATH = ".codex-cloud-result.json";
+export async function cloudDiffResult(diff, op, { signal, exec = execFileAsync } = {}) {
+  const fail = message => { throw collectionValidationError(message); };
+  let root;
+  try {
+    if (typeof diff !== "string" || !diff.startsWith("diff --git ") || Buffer.byteLength(diff) > 1_048_576 || diff.includes("\0")) fail("missing, binary or oversized Cloud diff");
+    const paths = [], headers = [];
+    for (const block of diff.split(/^diff --git /m).slice(1)) {
+      const header = block.slice(0, block.indexOf("\n"));
+      const match = header.match(/^a\/(.+) b\/\1$/);
+      if (!match) fail("Cloud patch has a renamed, quoted or unsupported path; retain the diff for explicit recovery");
+      const path = portablePath(match[1]); paths.push(path);
+      const metadata = block.split(/^@@/m)[0];
+      if (/^(?:old mode|new mode|rename |copy |GIT binary|Binary files)/m.test(metadata) || /^new file mode (?!100644$)/m.test(metadata) || /^index [^\n]+ (?!100644|100755)\d{6}$/m.test(metadata) || /^deleted file mode (?!100644|100755)\d{6}$/m.test(metadata)) fail("unsupported Cloud file type/mode change");
+      const old = metadata.match(/^--- (.+)$/m)?.[1], next = metadata.match(/^\+\+\+ (.+)$/m)?.[1];
+      if (!old || !next || !["/dev/null", `a/${path}`].includes(old) || !["/dev/null", `b/${path}`].includes(next) || old === next) fail("Cloud diff header paths disagree");
+      headers.push({ path, creation: old === "/dev/null", mode: metadata.match(/^index [^\n]+ (\d{6})$/m)?.[1] || metadata.match(/^deleted file mode (\d{6})$/m)?.[1] });
+    }
+    if (!paths.length || paths.length > 101 || new Set(paths).size !== paths.length || !paths.includes(CLOUD_RESULT_PATH)) fail("duplicate, excessive or missing Cloud diff/envelope paths");
+    const raw = Buffer.from(op.sources.data, "base64");
+    if (contentHash(raw) !== op.sources.hash) fail("saved Cloud snapshot hash differs");
+    const source = JSON.parse(gunzipSync(raw, { maxOutputLength: 12 * 1024 * 1024 }).toString("utf8"));
+    if (source.inputHead !== op.inputHead || source.repo !== op.repo || source.branch !== op.branch) fail("Cloud snapshot base/ownership differs");
+    const before = new Map(source.files.map(file => [portablePath(file.path), file]));
+    for (const header of headers) {
+      const file = before.get(header.path);
+      if (header.creation === Boolean(file) || header.mode && header.mode !== `100${file?.mode.toString(8)}`) fail("Cloud diff base file presence/mode disagrees with the exact input snapshot");
+    }
+    if (before.has(CLOUD_RESULT_PATH)) fail("reserved Cloud result path already exists in source");
+    assertRepositoryTargets(paths, [...before.keys()]);
+    root = mkdtempSync(join(tmpdir(), "cloud-diff-"));
+    const checkout = join(root, "checkout"); mkdirSync(checkout);
+    for (const file of source.files) {
+      const path = portablePath(file.path), bytes = Buffer.from(file.data, "base64");
+      if (contentHash(bytes) !== file.hash || ![0o644, 0o755].includes(file.mode)) fail("saved Cloud source bytes/mode differ");
+      const target = join(checkout, path); mkdirSync(dirname(target), { recursive: true }); writeFileSync(target, bytes); chmodSync(target, file.mode);
+    }
+    const patch = join(root, "result.diff"); writeFileSync(patch, diff, { mode: 0o600 });
+    const options = { cwd: checkout, signal, env: { PATH: process.env.PATH, ...runEnv(), HOME: root }, timeout: 5000, maxBuffer: 65_536 };
+    try { await exec("git", ["apply", "--check", "--", patch], options); await exec("git", ["apply", "--", patch], options); }
+    catch (error) { if (signal?.aborted || typeof error.code !== "number" || error.killed) throw error; fail("Cloud diff does not apply to the exact saved input revision"); }
+    const receipt = JSON.parse(readRepositoryText(checkout, CLOUD_RESULT_PATH));
+    const sorted = hashes => hashes && typeof hashes === "object" && !Array.isArray(hashes) ? JSON.stringify(Object.entries(hashes).sort(([a], [b]) => a.localeCompare(b))) : null;
+    if (receipt.version !== 1 || receipt.inputHead !== op.inputHead || receipt.repo !== op.repo || receipt.branch !== op.branch || receipt.runId !== op.runId || sorted(receipt.sourceHashes) !== sorted(op.sources.hashes) || !receipt.pr || !validProviderTestRecords(receipt.tests, op.inputHead) || receipt.tests.length > 100) fail("Cloud result envelope does not own this run/base/source snapshot or has incomplete test records");
+    const files = paths.filter(path => path !== CLOUD_RESULT_PATH).map(path => {
+      let text = null;
+      try { text = readRepositoryText(checkout, path); } catch (error) { if (error.code !== "ENOENT") throw error; }
+      const bytes = text === null ? null : readFileSync(join(checkout, path));
+      if (text !== null && (text.includes("\0") || !Buffer.from(text).equals(bytes))) fail("Cloud text result is binary or invalid UTF-8");
+      return { path, beforeHash: before.get(path)?.hash ?? null, afterHash: contentHash(text), text };
+    });
+    const textOnly = !files.length && op.continuity === "successor-task";
+    if (!files.length && !textOnly) fail("Cloud diff has no deliverable file changes outside an approved successor");
+    return { repo: op.repo, branch: op.branch, files, pr: receipt.pr, tests: receipt.tests,
+      // Reuse the shared writer's exact pushed-revision path. It rechecks remote
+      // head/ancestry, clean checkout and Verify evidence before updating one PR.
+      ...(textOnly ? { pushedHead: op.inputHead } : {}),
+      artifact: { source: "codex cloud diff --attempt 1", hash: contentHash(diff), inputHead: op.inputHead } };
+  } catch (error) {
+    if (signal?.aborted || error.collectionValidation || error.killed || /^(?:ENOENT|EACCES|EPERM|EIO|ENOSPC|EROFS|EMFILE|ENFILE|ENOMEM|ETIMEDOUT|ABORT_ERR)$/.test(error.code || "")) throw error;
+    throw collectionValidationError("invalid Cloud result paths, snapshot or delivery envelope");
+  } finally { if (root) rmSync(root, { recursive: true, force: true }); }
+}