@bridge_gpt/mcp-server 0.2.59 → 0.2.62

package/build/executor/integration-job.js

@@ -0,0 +1,759 @@
+/**
+ * Local and durable executors consume durable integration actions (BAPI-1259).
+ *
+ * The BAPI-1248 run finished every child and then blocked, because the only
+ * actor that tried to take the integration pull request out of draft was the
+ * reconciler, holding the GitHub App's read-only token. This module is the
+ * LOCAL half of the replacement: an executor — scoped to one run or
+ * repository-wide — claims a run-level integration action from Bridge, performs
+ * it under the customer's explicitly configured credential, and reports facts.
+ *
+ * ## What it does
+ *
+ * * `sync_base` — merges the EXACT expected base SHA into the EXACT run-bound
+ *   epic branch through the provider's merge API. No checkout, no force.
+ * * `mark_ready` — finds the ONE open pull request from the epic branch to the
+ *   base (creating it only after conclusive absence), confirms its head is the
+ *   expected epic head, and takes it out of draft.
+ * * `correct` — runs ONE worker through the executor's existing locked spawn
+ *   path under a driver that prepares the epic branch, verifies the worker's
+ *   edits, makes the one commit, and performs the one push. The worker has no
+ *   push authority and no operational database.
+ *
+ * None of them merges a pull request.
+ *
+ * ## Authority
+ *
+ * Every provider write runs with the child environment
+ * {@link buildLocalMergeChildEnv} builds from the credential
+ * {@link resolveLocalMergeCredential} resolves (`BAPI_LOCAL_MERGE_TOKEN`, or
+ * `BAPI_MACHINE_MERGE_TOKEN` for a machine-token run). Inherited `GH_TOKEN`,
+ * `GITHUB_TOKEN`, and an ambient `gh` login are stripped from that environment,
+ * so they cannot rescue a missing configured credential: a missing credential is
+ * reported as `authority_unavailable` and nothing is written. The credential
+ * never reaches argv, a report, or a log line; every captured output passes
+ * through {@link sanitizeLocalMergeOutput}.
+ *
+ * ## Revalidation and facts
+ *
+ * Immediately before any write the executor re-fetches the action under its
+ * lease (so a superseded action, a changed policy generation, or a stopped run
+ * stops it) and re-reads the live epic head (so a moved branch is never
+ * written). A lost response is resolved by reading the provider back and
+ * matching the result to THIS action — never by repeating the write. The
+ * report carries only closed-vocabulary facts. The reconciler re-observes the
+ * repository itself; nothing reported here completes a run or passes a gate,
+ * and this module chooses no next ticket and no gate.
+ */
+import { buildLocalMergeChildEnv, resolveLocalMergeCredential, sanitizeLocalMergeOutput, } from "../conductor/local-merge.js";
+import { createProductionEpicIntegrationGhRunner, ensureEpicIntegrationPullRequest, } from "../epic-integration-pr.js";
+import { INTEGRATION_ACTION_OPERATIONS, INTEGRATION_ACTION_OUTCOMES, INTEGRATION_ACTION_PROTOCOL_VERSION, } from "./types.js";
+/** The route prefix, mirrored from `api/routes/__init__.py`. */
+export const INTEGRATION_ACTION_ROUTE_PREFIX = "/epic-integration-actions";
+/** Heartbeat cadence. The server lease is three minutes. */
+export const INTEGRATION_ACTION_HEARTBEAT_INTERVAL_MS = 45_000;
+const READ_TIMEOUT_MS = 20_000;
+const WRITE_TIMEOUT_MS = 60_000;
+const GIT_TIMEOUT_MS = 120_000;
+const PUSH_TIMEOUT_MS = 120_000;
+const SHA_RE = /^[0-9a-f]{40}$/;
+const DETAIL_CODE_RE = /^[a-z0-9_]{1,64}$/;
+const PROVIDER_REPOSITORY_RE = /^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/;
+const MAX_DECLARED_FILES = 500;
+/**
+ * The integration-action transport. Separate from the `/executor/jobs` client:
+ * an integration action is not an ordinary job, and sharing the client would
+ * invite sharing its job-type vocabulary. The API key is chosen per repository
+ * and never appears in an error string.
+ */
+export function createIntegrationActionHttpClient(config) {
+    const base = config.baseUrl.replace(/\/+$/, "") + INTEGRATION_ACTION_ROUTE_PREFIX;
+    async function post(path, body, repoName) {
+        const res = await config.fetch(`${base}${path}`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "X-API-Key": config.apiKeyByRepo?.[repoName] ?? config.apiKey,
+                "X-Bridge-MCP-Version": config.mcpVersion,
+            },
+            body: JSON.stringify(body),
+        });
+        return { status: res.status, text: await res.text() };
+    }
+    const authority = (action) => ({
+        protocol_version: INTEGRATION_ACTION_PROTOCOL_VERSION,
+        repo_name: action.repo_name,
+        action_id: action.action_id,
+        claim_token: action.claim_token,
+    });
+    return {
+        async claim(request) {
+            let res;
+            try {
+                res = await post("/claim", request, request.repo_name);
+            }
+            catch {
+                return { kind: "retryable", error: "integration action claim network error" };
+            }
+            if (res.status === 204)
+                return { kind: "none" };
+            if (res.status === 200) {
+                try {
+                    const parsed = JSON.parse(res.text);
+                    if (!parsed || typeof parsed.claim_token !== "string") {
+                        return { kind: "fatal", error: "integration action claim returned a malformed body" };
+                    }
+                    return { kind: "claimed", action: parsed };
+                }
+                catch {
+                    return { kind: "fatal", error: "integration action claim returned invalid JSON" };
+                }
+            }
+            if (res.status === 401 || res.status === 403) {
+                return {
+                    kind: "fatal",
+                    error: `integration action claim rejected (HTTP ${res.status})`,
+                    authHttpStatus: res.status,
+                };
+            }
+            if (res.status === 404 || res.status === 422) {
+                // An older server without the route, or a contract it refuses.
+                return { kind: "fatal", error: `integration action claim rejected (HTTP ${res.status})` };
+            }
+            return { kind: "retryable", error: `integration action claim failed (HTTP ${res.status})` };
+        },
+        async fetch(action) {
+            try {
+                const res = await post("/fetch", authority(action), action.repo_name);
+                if (res.status === 200) {
+                    return { kind: "ok", work: JSON.parse(res.text) };
+                }
+                if (res.status >= 500)
+                    return { kind: "retryable" };
+                return { kind: "unavailable" };
+            }
+            catch {
+                return { kind: "retryable" };
+            }
+        },
+        async heartbeat(action) {
+            try {
+                const res = await post("/heartbeat", authority(action), action.repo_name);
+                if (res.status === 200)
+                    return "renewed";
+                if (res.status === 409 || res.status === 404 || res.status === 401 || res.status === 403) {
+                    return "lost";
+                }
+                return "retryable";
+            }
+            catch {
+                return "retryable";
+            }
+        },
+        async report(action, report) {
+            try {
+                const res = await post("/report", {
+                    ...authority(action),
+                    outcome: report.outcome,
+                    result_epic_head_sha: report.result_epic_head_sha ?? null,
+                    pr_number: report.pr_number ?? null,
+                    detail_code: report.detail_code ?? null,
+                }, action.repo_name);
+                if (res.status === 200) {
+                    try {
+                        const recorded = JSON.parse(res.text).recorded;
+                        return recorded === "stale_fact" ? "stale_fact" : "report";
+                    }
+                    catch {
+                        return "report";
+                    }
+                }
+                if (res.status >= 500)
+                    return "retryable";
+                return "unavailable";
+            }
+            catch {
+                return "retryable";
+            }
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Validation
+// ---------------------------------------------------------------------------
+/** Reject an action this executor must not perform, before any side effect. */
+export function validateIntegrationAction(action) {
+    if (action.protocol_version !== INTEGRATION_ACTION_PROTOCOL_VERSION) {
+        return { ok: false, reason: "protocol_version_unsupported" };
+    }
+    if (action.actor !== "local")
+        return { ok: false, reason: "actor_not_local" };
+    if (!INTEGRATION_ACTION_OPERATIONS.includes(action.operation)) {
+        return { ok: false, reason: "operation_unsupported" };
+    }
+    if (typeof action.epic_branch !== "string" || !action.epic_branch.startsWith("epic/")) {
+        return { ok: false, reason: "epic_branch_invalid" };
+    }
+    if (typeof action.base_branch !== "string" || action.base_branch.trim() === "") {
+        return { ok: false, reason: "base_branch_invalid" };
+    }
+    if (action.base_branch === action.epic_branch) {
+        return { ok: false, reason: "base_branch_invalid" };
+    }
+    if (!SHA_RE.test(action.expected_epic_head_sha) || !SHA_RE.test(action.expected_base_sha)) {
+        return { ok: false, reason: "expected_head_invalid" };
+    }
+    if (!PROVIDER_REPOSITORY_RE.test(action.provider_repository)) {
+        return { ok: false, reason: "provider_repository_invalid" };
+    }
+    if (action.operation === "correct") {
+        if (action.correction_kind !== "base_conflict" && action.correction_kind !== "ci_failure") {
+            return { ok: false, reason: "correction_kind_invalid" };
+        }
+        if (typeof action.correction_prompt !== "string" || action.correction_prompt.trim() === "") {
+            return { ok: false, reason: "correction_prompt_missing" };
+        }
+    }
+    return { ok: true };
+}
+/** The work fields that must be byte-identical between the claim and a refetch. */
+const IMMUTABLE_WORK_FIELDS = [
+    "action_id",
+    "operation",
+    "repo_name",
+    "provider_repository",
+    "epic_run_id",
+    "epic_branch",
+    "base_branch",
+    "expected_epic_head_sha",
+    "expected_base_sha",
+    "correction_kind",
+];
+function sameWork(a, b) {
+    return IMMUTABLE_WORK_FIELDS.every((field) => (a[field] ?? null) === (b[field] ?? null));
+}
+function safeDetail(code) {
+    return DETAIL_CODE_RE.test(code) ? code : "detail_unavailable";
+}
+/** Run a credentialed command; the captured text is sanitized before anything reads it. */
+async function runCredentialed(deps, credential, env, file, args, options) {
+    try {
+        const result = await deps.runCommand(file, args, {
+            cwd: options.cwd ?? deps.cwd,
+            timeoutMs: options.timeoutMs,
+            env,
+        });
+        return {
+            exitCode: result.exitCode,
+            stdout: sanitizeLocalMergeOutput(result.stdout ?? "", [credential.token]),
+            stderr: sanitizeLocalMergeOutput(result.stderr ?? "", [credential.token]),
+        };
+    }
+    catch {
+        return { exitCode: -1, stdout: "", stderr: "" };
+    }
+}
+/** The first HTTP status in `gh api --include` output (or a `gh` error line). */
+export function parseGhHttpStatus(stdout, stderr) {
+    const head = stdout.match(/^HTTP\/[\d.]+\s+(\d{3})/m);
+    if (head)
+        return Number(head[1]);
+    const err = `${stderr}\n${stdout}`.match(/\(HTTP (\d{3})\)|HTTP (\d{3}):/);
+    if (err)
+        return Number(err[1] ?? err[2]);
+    return null;
+}
+/** The JSON body after the header block of `gh api --include` output. */
+function parseIncludedBody(stdout) {
+    const split = stdout.split(/\r?\n\r?\n/);
+    if (split.length < 2)
+        return null;
+    try {
+        return JSON.parse(split.slice(1).join("\n\n"));
+    }
+    catch {
+        return null;
+    }
+}
+function providerReads(deps, credential, env, repository) {
+    return {
+        async branchHead(branch) {
+            const r = await runCredentialed(deps, credential, env, "gh", ["api", `repos/${repository}/branches/${branch}`, "--jq", ".commit.sha"], { timeoutMs: READ_TIMEOUT_MS });
+            const sha = r.stdout.trim().toLowerCase();
+            return r.exitCode === 0 && SHA_RE.test(sha) ? sha : null;
+        },
+        async parents(sha) {
+            const r = await runCredentialed(deps, credential, env, "gh", ["api", `repos/${repository}/commits/${sha}`, "--jq", "[.parents[].sha] | join(\" \")"], { timeoutMs: READ_TIMEOUT_MS });
+            if (r.exitCode !== 0)
+                return null;
+            const list = r.stdout.trim().toLowerCase().split(/\s+/).filter((p) => p.length > 0);
+            return list.every((p) => SHA_RE.test(p)) ? list : null;
+        },
+    };
+}
+function startLeaseHeartbeat(client, action, deps, intervalMs) {
+    let lost = false;
+    let stopped = false;
+    const beat = async () => {
+        const result = await client.heartbeat(action);
+        if (result === "lost")
+            lost = true;
+        return result;
+    };
+    const loop = (async () => {
+        while (!stopped && !lost) {
+            await deps.sleep(intervalMs);
+            if (stopped || lost)
+                break;
+            await beat();
+        }
+    })();
+    return {
+        lost: () => lost,
+        beat,
+        async stop() {
+            stopped = true;
+            // Never block shutdown on a sleeping beat: the loop exits on its next wake.
+            await Promise.race([loop, Promise.resolve()]);
+        },
+    };
+}
+async function performSyncBase(action, deps, credential, env, reads) {
+    const message = `Merge ${action.base_branch} into ${action.epic_branch} ` +
+        `(${action.epic_key} integration preparation)`;
+    const r = await runCredentialed(deps, credential, env, "gh", [
+        "api", "--include", "--method", "POST", `repos/${action.provider_repository}/merges`,
+        "-f", `base=${action.epic_branch}`,
+        "-f", `head=${action.expected_base_sha}`,
+        "-f", `commit_message=${message}`,
+    ], { timeoutMs: WRITE_TIMEOUT_MS });
+    const status = parseGhHttpStatus(r.stdout, r.stderr);
+    const expectedParents = [action.expected_epic_head_sha, action.expected_base_sha];
+    const matches = (parents) => parents !== null && parents.length === 2 &&
+        parents[0] === expectedParents[0] && parents[1] === expectedParents[1];
+    if (status === 201) {
+        const body = parseIncludedBody(r.stdout);
+        const sha = typeof body?.sha === "string" ? body.sha.toLowerCase() : "";
+        if (SHA_RE.test(sha) && matches(await reads.parents(sha))) {
+            return { outcome: "applied", result_epic_head_sha: sha };
+        }
+        return { outcome: "head_drift", detail_code: "merge_parents_unexpected" };
+    }
+    if (status === 204) {
+        return { outcome: "already_satisfied", result_epic_head_sha: action.expected_epic_head_sha };
+    }
+    if (status === 409)
+        return { outcome: "conflict", detail_code: "base_merge_conflict" };
+    if (status === 401 || status === 403 || status === 404) {
+        // The provider refused the configured credential: missing authority, which
+        // blocks with its own reason. `authority_lost` is reserved for a lease or
+        // approved work that changed under this actor.
+        return { outcome: "authority_unavailable", detail_code: `provider_http_${status}` };
+    }
+    // A lost or unrecognized response: read the branch back and match it to THIS
+    // action. Never repeat the write.
+    const live = await reads.branchHead(action.epic_branch);
+    if (live !== null && live !== action.expected_epic_head_sha && matches(await reads.parents(live))) {
+        return { outcome: "applied", result_epic_head_sha: live, detail_code: "read_back_confirmed" };
+    }
+    return { outcome: "indeterminate", detail_code: "merge_response_lost" };
+}
+function mapPullRequestOutcome(outcome) {
+    if (outcome.kind === "already_open" || outcome.kind === "created") {
+        const pr = outcome.prNumber ?? null;
+        switch (outcome.readiness) {
+            case "made_ready":
+                return { outcome: "applied", pr_number: pr };
+            case "already_ready":
+                return { outcome: "already_satisfied", pr_number: pr };
+            case "ready_refused_head_drift":
+                return { outcome: "head_drift", pr_number: pr, detail_code: "pr_head_moved" };
+            default:
+                return { outcome: "failed", pr_number: pr, detail_code: "ready_failed" };
+        }
+    }
+    if (outcome.kind === "deferred") {
+        return { outcome: "failed", detail_code: "no_commits_between_branches" };
+    }
+    switch (outcome.reason) {
+        case "probe_ambiguous":
+            return { outcome: "pr_ambiguous", detail_code: "probe_ambiguous" };
+        case "gh_unauthenticated":
+            return { outcome: "authority_unavailable", detail_code: "gh_unauthenticated" };
+        case "gh_unavailable":
+            return { outcome: "authority_unavailable", detail_code: "local_gh_unavailable" };
+        default:
+            return { outcome: "indeterminate", detail_code: safeDetail(outcome.reason) };
+    }
+}
+async function performMarkReady(action, deps, env, seams) {
+    const createGh = seams.createGhRunner ?? ((e) => createProductionEpicIntegrationGhRunner(undefined, e));
+    const outcome = await ensureEpicIntegrationPullRequest({
+        epicKey: action.epic_key,
+        epicBranch: action.epic_branch,
+        baseBranch: action.base_branch,
+        command: "executor integration",
+        gh: createGh(env),
+        cwd: deps.cwd,
+        requestReady: true,
+        expectedHeadSha: action.expected_epic_head_sha,
+        repo: action.provider_repository,
+    });
+    return mapPullRequestOutcome(outcome);
+}
+/**
+ * Perform one claimed integration action and report its facts.
+ *
+ * Never throws. Every refusal is reported (a report on a lease that is already
+ * gone is recorded by the server as a stale fact, which is still useful to the
+ * reconciler's re-observation).
+ */
+export async function runIntegrationAction(action, client, deps, seams = {}) {
+    const finish = async (report) => {
+        const bounded = {
+            outcome: INTEGRATION_ACTION_OUTCOMES.includes(report.outcome)
+                ? report.outcome
+                : "failed",
+            result_epic_head_sha: report.result_epic_head_sha && SHA_RE.test(report.result_epic_head_sha)
+                ? report.result_epic_head_sha
+                : null,
+            pr_number: typeof report.pr_number === "number" && Number.isInteger(report.pr_number) && report.pr_number > 0
+                ? report.pr_number
+                : null,
+            detail_code: report.detail_code ? safeDetail(report.detail_code) : null,
+        };
+        const reported = await client.report(action, bounded);
+        deps.errorLog(`executor: integration action ${action.operation} for ${action.epic_key}: ` +
+            `outcome=${bounded.outcome}` +
+            (bounded.detail_code ? ` detail=${bounded.detail_code}` : "") +
+            ` reported=${reported}`);
+        return { report: bounded, reported };
+    };
+    const valid = validateIntegrationAction(action);
+    if (!valid.ok)
+        return finish({ outcome: "failed", detail_code: valid.reason });
+    const kind = action.credential_kind === "machine_token" ? "machine_token" : "local";
+    const credential = resolveLocalMergeCredential(deps.env, kind);
+    if (credential === null) {
+        // An ambient gh login, GH_TOKEN, or GITHUB_TOKEN does NOT substitute.
+        return finish({ outcome: "authority_unavailable", detail_code: `${kind}_merge_credential_missing` });
+    }
+    const env = buildLocalMergeChildEnv(deps.env, credential, { GIT_TERMINAL_PROMPT: "0" });
+    const reads = providerReads(deps, credential, env, action.provider_repository);
+    const lease = startLeaseHeartbeat(client, action, deps, seams.heartbeatIntervalMs ?? INTEGRATION_ACTION_HEARTBEAT_INTERVAL_MS);
+    let report;
+    try {
+        // --- Revalidate immediately before any write ------------------------
+        const refetched = await client.fetch(action);
+        if (refetched.kind !== "ok") {
+            report = {
+                outcome: refetched.kind === "unavailable" ? "authority_lost" : "indeterminate",
+                detail_code: refetched.kind === "unavailable" ? "lease_not_held" : "fetch_unavailable",
+            };
+        }
+        else if (!sameWork(action, refetched.work)) {
+            report = { outcome: "authority_lost", detail_code: "work_changed" };
+        }
+        else {
+            const live = await reads.branchHead(action.epic_branch);
+            if (live === null) {
+                report = { outcome: "indeterminate", detail_code: "epic_head_unreadable" };
+            }
+            else if (live !== action.expected_epic_head_sha) {
+                report = { outcome: "head_drift", detail_code: "epic_head_moved" };
+            }
+            else if (lease.lost()) {
+                report = { outcome: "authority_lost", detail_code: "lease_lost" };
+            }
+            else if (action.operation === "sync_base") {
+                report = await performSyncBase(action, deps, credential, env, reads);
+            }
+            else if (action.operation === "mark_ready") {
+                report = await performMarkReady(action, deps, env, seams);
+            }
+            else if (seams.runCorrection === undefined) {
+                report = { outcome: "failed", detail_code: "correction_unsupported" };
+            }
+            else {
+                const driver = createIntegrationCorrectionDriver(action, {
+                    runCommand: deps.runCommand,
+                    credential,
+                    env,
+                    errorLog: deps.errorLog,
+                });
+                const corrected = await seams.runCorrection(action, driver, () => lease.beat());
+                report = {
+                    outcome: corrected.outcome,
+                    result_epic_head_sha: corrected.resultSha ?? null,
+                    detail_code: corrected.detailCode ?? null,
+                };
+            }
+        }
+    }
+    catch {
+        report = { outcome: "indeterminate", detail_code: "executor_error" };
+    }
+    finally {
+        await lease.stop();
+    }
+    return finish(report);
+}
+/**
+ * The driver for ONE `correct` action. Mirrors `reconcile_overlap`'s driver
+ * (BAPI-1152): it prepares the worktree before the worker, and afterwards it
+ * alone verifies, commits, and pushes. The worker is launched without a
+ * worker-branch identity, so the deterministic guard denies every push it
+ * attempts.
+ */
+export function createIntegrationCorrectionDriver(action, deps) {
+    const isConflict = action.correction_kind === "base_conflict";
+    const expected = action.expected_epic_head_sha;
+    const baseSha = action.expected_base_sha;
+    const remoteUrl = `https://github.com/${action.provider_repository}.git`;
+    const destination = `refs/heads/${action.epic_branch}`;
+    const git = async (ctx, args, timeoutMs = GIT_TIMEOUT_MS, env) => {
+        try {
+            const r = await deps.runCommand("git", args, {
+                cwd: ctx.worktreePath,
+                timeoutMs,
+                ...(env ? { env } : {}),
+            });
+            return {
+                exitCode: r.exitCode,
+                stdout: sanitizeLocalMergeOutput(r.stdout ?? "", [deps.credential.token]),
+                stderr: sanitizeLocalMergeOutput(r.stderr ?? "", [deps.credential.token]),
+            };
+        }
+        catch {
+            return { exitCode: -1, stdout: "", stderr: "" };
+        }
+    };
+    const revParse = async (ctx, ref) => {
+        const r = await git(ctx, ["rev-parse", "-q", "--verify", `${ref}^{commit}`]);
+        const sha = r.stdout.trim().toLowerCase();
+        return r.exitCode === 0 && SHA_RE.test(sha) ? sha : null;
+    };
+    const complete = (result) => ({
+        kind: "complete",
+        result: {
+            outcome: result.outcome,
+            ...(result.resultSha ? { result_sha: result.resultSha } : {}),
+            ...(result.detailCode ? { detail_code: result.detailCode } : {}),
+        },
+        ...(result.resultSha ? { lastCommitSha: result.resultSha } : {}),
+    });
+    const restore = async (ctx) => {
+        await git(ctx, ["merge", "--abort"]);
+        await git(ctx, ["reset", "--hard", expected]);
+    };
+    /** The ONE push: a plain fast-forward, never forced, under the configured credential. */
+    const push = async (ctx, candidate) => {
+        const pushed = await git(ctx, [
+            "-c", "credential.helper=",
+            "-c", "credential.helper=!gh auth git-credential",
+            "push", "--no-verify", "--porcelain", remoteUrl, `HEAD:${destination}`,
+        ], PUSH_TIMEOUT_MS, deps.env);
+        if (pushed.exitCode === 0) {
+            return complete({ outcome: "applied", resultSha: candidate });
+        }
+        const text = `${pushed.stdout}\n${pushed.stderr}`;
+        if (/non-fast-forward|fetch first|\[rejected\]/i.test(text)) {
+            await restore(ctx);
+            return complete({ outcome: "head_drift", detailCode: "push_rejected_non_fast_forward" });
+        }
+        if (/403|denied|Authentication failed|could not read Username/i.test(text)) {
+            await restore(ctx);
+            return complete({ outcome: "authority_unavailable", detailCode: "push_unauthorized" });
+        }
+        // Unknown result: read the remote back and match it to THIS commit.
+        const remote = await git(ctx, ["ls-remote", remoteUrl, destination], GIT_TIMEOUT_MS, deps.env);
+        const remoteHead = remote.stdout.trim().split(/\s+/)[0]?.toLowerCase() ?? "";
+        if (remote.exitCode === 0 && remoteHead === candidate) {
+            return complete({ outcome: "applied", resultSha: candidate, detailCode: "read_back_confirmed" });
+        }
+        await restore(ctx);
+        return complete({ outcome: "indeterminate", detailCode: "push_result_unknown" });
+    };
+    const declaredFiles = async (ctx) => {
+        const args = isConflict
+            ? ["diff", "--name-only", "--diff-filter=U", "-z"]
+            : ["diff", "--name-only", "-z", `${baseSha}...${expected}`];
+        const r = await git(ctx, args);
+        if (r.exitCode !== 0)
+            return [];
+        return r.stdout.split("\0").filter((p) => p.length > 0).slice(0, MAX_DECLARED_FILES);
+    };
+    return {
+        omitWorkerBranch: true,
+        async beforeWorker(ctx) {
+            const finish = (outcome) => ({ kind: "finish", outcome });
+            if (ctx.branch !== action.epic_branch) {
+                return finish(complete({ outcome: "failed", detailCode: "worktree_branch_mismatch" }));
+            }
+            const head = await revParse(ctx, "HEAD");
+            if (head !== expected) {
+                await restore(ctx);
+                return finish(complete({ outcome: "head_drift", detailCode: "epic_head_moved" }));
+            }
+            await git(ctx, ["fetch", "--no-tags", "origin", action.base_branch], GIT_TIMEOUT_MS);
+            if ((await git(ctx, ["cat-file", "-e", `${baseSha}^{commit}`])).exitCode !== 0) {
+                return finish(complete({ outcome: "indeterminate", detailCode: "base_commit_unavailable" }));
+            }
+            if (isConflict) {
+                const merge = await git(ctx, ["merge", "--no-ff", "--no-commit", "--no-edit", baseSha], GIT_TIMEOUT_MS, { ...deps.env, GIT_MERGE_AUTOEDIT: "no" });
+                if (merge.exitCode === 0) {
+                    // The base merged cleanly here after all: commit it, no worker needed.
+                    const committed = await git(ctx, [
+                        "commit", "--no-verify", "--no-edit", "-m",
+                        `Merge ${action.base_branch} into ${action.epic_branch}`,
+                    ]);
+                    const candidate = await revParse(ctx, "HEAD");
+                    if (committed.exitCode !== 0 || candidate === null) {
+                        await restore(ctx);
+                        return finish(complete({ outcome: "failed", detailCode: "merge_commit_failed" }));
+                    }
+                    return finish(await push(ctx, candidate));
+                }
+                if (merge.exitCode !== 1 || (await revParse(ctx, "MERGE_HEAD")) !== baseSha) {
+                    await restore(ctx);
+                    return finish(complete({ outcome: "failed", detailCode: "merge_start_failed" }));
+                }
+            }
+            return {
+                kind: "spawn_worker",
+                prompt: action.correction_prompt ?? "",
+                // Stricter than the generic check: HEAD is the expected epic head and,
+                // for a conflict, the merge of the expected base SHA is in progress.
+                preSpawnVerification: { ok: true, observedSha: expected },
+                declaredTouchedFiles: await declaredFiles(ctx),
+            };
+        },
+        async afterWorker(ctx) {
+            // The worker may edit the working tree and nothing else.
+            const head = await revParse(ctx, "HEAD");
+            const mergeHead = await revParse(ctx, "MERGE_HEAD");
+            if (head !== expected || mergeHead !== (isConflict ? baseSha : null)) {
+                await restore(ctx);
+                return complete({ outcome: "failed", detailCode: "worker_rewrote_history" });
+            }
+            await git(ctx, ["add", "-A", "--", "."]);
+            if (isConflict) {
+                const unmerged = await git(ctx, ["ls-files", "-u"]);
+                const markers = await git(ctx, ["grep", "--cached", "-n", "-I", "-E", "^(<{7}|>{7})( |$)"]);
+                if (unmerged.exitCode !== 0 || unmerged.stdout.trim().length > 0 || markers.exitCode === 0) {
+                    await restore(ctx);
+                    return complete({ outcome: "failed", detailCode: "conflicts_unresolved" });
+                }
+            }
+            else {
+                const staged = await git(ctx, ["diff", "--cached", "--quiet"]);
+                if (staged.exitCode === 0) {
+                    await restore(ctx);
+                    return complete({ outcome: "failed", detailCode: "correction_no_change" });
+                }
+            }
+            const message = isConflict
+                ? `Merge ${action.base_branch} into ${action.epic_branch}`
+                : `${action.epic_key}: fix failing required checks on the integration branch`;
+            const committed = await git(ctx, ["commit", "--no-verify", "--no-edit", "-m", message]);
+            const candidate = await revParse(ctx, "HEAD");
+            if (committed.exitCode !== 0 || candidate === null) {
+                await restore(ctx);
+                return complete({ outcome: "failed", detailCode: "commit_failed" });
+            }
+            // The commit's shape is the authority: exactly the two authorized parents
+            // for a conflict merge, exactly the expected head for a CI fix.
+            const parents = await git(ctx, ["rev-parse", `${candidate}^@`]);
+            const parentList = parents.stdout.trim().toLowerCase().split(/\s+/).filter((p) => p);
+            const shapeOk = isConflict
+                ? parentList.length === 2 && parentList[0] === expected && parentList[1] === baseSha
+                : parentList.length === 1 && parentList[0] === expected;
+            if (parents.exitCode !== 0 || !shapeOk) {
+                await restore(ctx);
+                return complete({ outcome: "failed", detailCode: "correction_shape_invalid" });
+            }
+            return push(ctx, candidate);
+        },
+        async abandon(ctx) {
+            try {
+                await restore(ctx);
+            }
+            catch {
+                /* must never throw */
+            }
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Correction: the synthetic job and its lease adapter
+// ---------------------------------------------------------------------------
+/**
+ * The synthetic recovery job a correction runs as inside the locked spawn path.
+ *
+ * `rebase` is the recovery type whose worktree continues from the pushed
+ * `origin/<branch>` head — here the epic branch — with the stale-branch guard
+ * off. The job never reaches `/executor/jobs`: its `httpClient` is the lease
+ * adapter below, and `id` 0 is never a server row id.
+ */
+export function buildIntegrationCorrectionJob(action, timeoutSeconds) {
+    return {
+        id: 0,
+        claim_token: action.claim_token,
+        repo_name: action.repo_name,
+        job_type: "rebase",
+        ticket_key: action.epic_key,
+        epic_run_id: action.epic_run_id,
+        payload: { prompt: action.correction_prompt ?? "", base_branch: action.base_branch },
+        expected_branch: action.epic_branch,
+        expected_head_sha: action.expected_epic_head_sha,
+        lease_expires_at: action.lease_expires_at,
+        attempt_count: 1,
+        max_attempts: 1,
+        timeout_seconds: timeoutSeconds,
+    };
+}
+/**
+ * An `ExecutorHttpClient` whose heartbeats renew the integration action's lease
+ * and whose terminal mutations are CAPTURED rather than sent: the correction
+ * reports through the integration action's own report, once, after the spawn.
+ */
+export function createIntegrationCorrectionLeaseAdapter(heartbeat) {
+    let completion = null;
+    let failure = null;
+    const client = {
+        async claim() {
+            return { kind: "none", reconcilerLiveness: "unknown" };
+        },
+        async heartbeat(_job, _payload) {
+            const result = await heartbeat();
+            if (result === "renewed")
+                return "updated";
+            if (result === "lost")
+                return "stale_claim";
+            return "retry_later";
+        },
+        async complete(_job, c) {
+            completion = c;
+            return "updated";
+        },
+        async fail(_job, f) {
+            failure = f;
+            return "updated";
+        },
+    };
+    const captured = () => {
+        const result = completion?.result;
+        const outcome = result?.outcome;
+        if (typeof outcome === "string" && INTEGRATION_ACTION_OUTCOMES.includes(outcome)) {
+            const sha = typeof result?.result_sha === "string" ? result.result_sha : undefined;
+            const detail = typeof result?.detail_code === "string" ? result.detail_code : undefined;
+            return { outcome: outcome, resultSha: sha, detailCode: detail };
+        }
+        if (failure !== null) {
+            const kind = failure.classification === "timeout" ? "correction_timeout" : "correction_failed";
+            return { outcome: "failed", detailCode: kind };
+        }
+        return { outcome: "indeterminate", detailCode: "correction_unreported" };
+    };
+    return { client, captured };
+}