@bridge_gpt/mcp-server 0.2.53 → 0.2.55

package/build/executor/reconcile-overlap-job.js

@@ -0,0 +1,989 @@
+/**
+ * The `reconcile_overlap` executor job (BAPI-1152).
+ *
+ * Two epic children that edit the same file can both reach merge. The server
+ * (BAPI-1151) detects that and dispatches this job for the held child. The job
+ * MERGES the required epic commit into the child — never a rebase, never a force
+ * push — so the recorded child head stays an ancestor of whatever it produces.
+ *
+ * The phases, in order (`ReconcileOverlapPhase`):
+ *
+ *   validated          the payload is proven well-formed before ANY subprocess;
+ *   classified         `git merge-tree --write-tree` decides clean vs conflicted
+ *                      against the object database, before the worktree moves;
+ *   merged             a real `git merge --no-ff --no-commit` of the epic commit;
+ *   checked            the union of both tickets' structured local verification
+ *                      commands runs, with no LLM at all;
+ *   worker-completed   ONLY when the merge conflicted or the checks were red:
+ *                      exactly one worker, holding both tickets' intents, edits
+ *                      the working tree — it never commits and never pushes;
+ *   governance-scanned the candidate is compared against the governance regions
+ *                      the server read at the INPUT epic head;
+ *   pushed             one fast-forward push, leased on the recorded child head;
+ *   cleaned            every exit that does not push resets the worktree to the
+ *                      recorded child head.
+ *
+ * Commits are the WRAPPER's in every flow. A clean merge is committed by the
+ * wrapper and any worker repair lands in a separate commit on top. A conflicted
+ * merge stays in progress (`MERGE_HEAD`) while the worker resolves it; the
+ * wrapper then commits the two-parent merge from the resolved conflict paths and
+ * commits any further repair separately. The merge commit is never amended.
+ *
+ * The job returns FACTS, never a verdict (R14 rule 3): the input heads, the
+ * classification, whether a worker ran, every edited path and why, the local
+ * checks observed, and either the pushed head or the reason nothing was pushed —
+ * a governance fact or an observed moved head. The server verifies all of it
+ * against the provider (`reconcile_overlap_completion_contract.py`).
+ *
+ * Runtime prerequisite: the push runs in the executor's OWN process under the
+ * machine's local git credential helper — the posture `merge-job.ts` uses for
+ * `gh pr merge`. The Bridge GitHub App stays `contents: read`. A helper that
+ * refuses the push is reported as `ReconcileOverlapPushUnauthorized`.
+ */
+import path from "node:path";
+import { pollCiChecksForCommit, resolveConductorBridgeApiAccess, } from "../conductor/bridge-api-client.js";
+import { normalizeRepoRelativePath } from "../conductor/file-scope-guard.js";
+import { allRequiredChecksGreen } from "../conductor/local-merge.js";
+import { buildExecutorBaseWorkerEnv } from "./env.js";
+import { ReconcileOverlapBranchMismatch, ReconcileOverlapConflictsUnresolved, ReconcileOverlapMergeFailed, ReconcileOverlapNothingToMerge, ReconcileOverlapPayload as ReconcileOverlapPayloadInvalid, ReconcileOverlapPushRejected, ReconcileOverlapPushUnauthorized, ReconcileOverlapTopologyRefused, ReconcileOverlapVerificationRed, ReconcileOverlapWorkerRewroteHistory, } from "./job-errors.js";
+import { classifyMergeTree } from "./merge-tree-classifier.js";
+import { scanGovernanceRegions } from "./reconcile-overlap-governance.js";
+import { RECONCILE_OVERLAP_PAYLOAD_SCHEMA_VERSION, } from "./reconcile-overlap-types.js";
+import { validateWorkerFinalization } from "./worker-finalization.js";
+export const RECONCILE_OVERLAP_JOB_TYPE = "reconcile_overlap";
+/** Result-envelope bounds, mirrored from the server's result model. */
+export const RECONCILE_EDITED_PATHS_MAX = 40;
+export const RECONCILE_CHECKS_OBSERVED_MAX = 40;
+export const RECONCILE_PATH_MAX_CHARS = 256;
+export const RECONCILE_REASON_MAX_CHARS = 240;
+export const RECONCILE_CHECK_NAME_MAX_CHARS = 200;
+export const RECONCILE_CHECK_CONCLUSION_MAX_CHARS = 32;
+const TRUNCATION_MARKER = "…[truncated]";
+/** Payload bounds (mirrors `reconcile_overlap_payload.py`). */
+const MAX_VERIFICATION_COMMANDS_PER_TICKET = 16;
+const MAX_ARGV = 32;
+const MAX_ARG_CHARS = 1024;
+const MAX_COMMAND_TIMEOUT_SECONDS = 30 * 60;
+const MAX_CHANGED_FILES = 1000;
+const MAX_GOVERNANCE_REGIONS = 64;
+const REF_NAME_MAX_CHARS = 255;
+const CONFLICT_REPORT_DIR = ".conductor/";
+/** The executor's per-worktree artifact directory, never part of a candidate. */
+const CONDUCTOR_ARTIFACT_DIR = ".conductor/";
+/** Command bounds. */
+const GIT_TIMEOUT_MS = 120_000;
+const PUSH_TIMEOUT_MS = 180_000;
+const COMMAND_OUTPUT_TAIL_CHARS = 4_000;
+/** Left in the job budget when the wrapper waits for provider checks. */
+const CI_WAIT_MARGIN_MS = 90_000;
+const CI_WAIT_POLL_INTERVAL_MS = 30_000;
+/** Finalization settling: GitHub updates a PR's head a moment after the push. */
+const FINALIZATION_ATTEMPTS = 6;
+const FINALIZATION_RETRY_DELAY_MS = 2_000;
+/**
+ * Paths the wrapper never stages: the executor's own per-worktree artifacts. They
+ * are also excluded through `.git/info/exclude`, but a foreign repository's
+ * `.gitignore` may not name `.mcp.json`, so the pathspec is the second line.
+ */
+const WRAPPER_STAGE_EXCLUDES = [
+    ":(exclude).conductor",
+    ":(exclude).mcp.json",
+    ":(exclude).cursor/mcp.json",
+    ":(exclude).claude/settings.local.json",
+];
+const SHA_RE = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
+const TAG_RE = /^[A-Z][A-Z0-9_]{0,31}$/;
+const SHA256_HEX_RE = /^[0-9a-f]{64}$/;
+const FAILED_CHECK_CONCLUSIONS = new Set([
+    "failure",
+    "cancelled",
+    "timed_out",
+    "action_required",
+    "startup_failure",
+    "stale",
+]);
+const PUSH_AUTH_FAILURE_RE = /authentication failed|could not read username|permission denied|terminal prompts disabled|invalid username or password|returned error: 403|requested url returned error: 401/i;
+const PUSH_LEASE_FAILURE_RE = /stale info|\[rejected\]|non-fast-forward|fetch first/i;
+class PayloadError extends Error {
+}
+function asRecord(value, field) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new PayloadError(`${field} must be an object`);
+    }
+    return value;
+}
+function requiredSha(value, field) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new PayloadError(`${field} is missing or blank`);
+    }
+    const sha = value.trim().toLowerCase();
+    if (!SHA_RE.test(sha))
+        throw new PayloadError(`${field} is not a full commit SHA`);
+    return sha;
+}
+function refName(value, field) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new PayloadError(`${field} is missing or blank`);
+    }
+    const ref = value.trim();
+    // A ref is an argv element and a push destination: whitespace, control
+    // characters, a leading dash (option injection), and `..` are all refused.
+    if (ref.length > REF_NAME_MAX_CHARS ||
+        /[\s\x00-\x1f\x7f~^:?*[\\]/.test(ref) ||
+        ref.startsWith("-") ||
+        ref.includes("..")) {
+        throw new PayloadError(`${field} is not a usable branch name`);
+    }
+    return ref;
+}
+function pathList(value, field, max) {
+    if (!Array.isArray(value))
+        throw new PayloadError(`${field} must be a list`);
+    if (value.length > max)
+        throw new PayloadError(`${field} exceeds ${max} entries`);
+    const out = new Set();
+    for (const item of value) {
+        const normalized = normalizeRepoRelativePath(item);
+        if (normalized === null)
+            throw new PayloadError(`${field} contains an unsafe path`);
+        out.add(normalized);
+    }
+    return Array.from(out).sort();
+}
+function verificationCommands(value, field) {
+    if (value === undefined || value === null)
+        return [];
+    if (!Array.isArray(value))
+        throw new PayloadError(`${field} must be a list`);
+    if (value.length > MAX_VERIFICATION_COMMANDS_PER_TICKET) {
+        throw new PayloadError(`${field} exceeds ${MAX_VERIFICATION_COMMANDS_PER_TICKET} commands`);
+    }
+    return value.map((raw, index) => {
+        const entry = asRecord(raw, `${field}[${index}]`);
+        const name = typeof entry.name === "string" ? entry.name.trim() : "";
+        if (!name)
+            throw new PayloadError(`${field}[${index}].name is blank`);
+        const argv = entry.argv;
+        if (!Array.isArray(argv) || argv.length === 0 || argv.length > MAX_ARGV) {
+            throw new PayloadError(`${field}[${index}].argv must be a non-empty argv list`);
+        }
+        for (const arg of argv) {
+            if (typeof arg !== "string" || arg.trim().length === 0 || arg.length > MAX_ARG_CHARS || arg.includes("\0")) {
+                throw new PayloadError(`${field}[${index}].argv holds an unusable argument`);
+            }
+        }
+        const timeout = entry.timeout_seconds;
+        if (typeof timeout !== "number" ||
+            !Number.isInteger(timeout) ||
+            timeout < 1 ||
+            timeout > MAX_COMMAND_TIMEOUT_SECONDS) {
+            throw new PayloadError(`${field}[${index}].timeout_seconds is out of range`);
+        }
+        return { name: name.slice(0, RECONCILE_CHECK_NAME_MAX_CHARS), argv: argv, timeoutSeconds: timeout };
+    });
+}
+function ticketContext(value, field) {
+    const entry = asRecord(value, field);
+    const ticketKey = typeof entry.ticket_key === "string" ? entry.ticket_key.trim() : "";
+    if (!ticketKey)
+        throw new PayloadError(`${field}.ticket_key is missing or blank`);
+    return {
+        ticketKey,
+        changedFiles: pathList(entry.changed_files, `${field}.changed_files`, MAX_CHANGED_FILES),
+        declaredTouchedFiles: pathList(entry.declared_touched_files ?? [], `${field}.declared_touched_files`, MAX_CHANGED_FILES),
+        verificationCommands: verificationCommands(entry.verification_commands, `${field}.verification_commands`),
+    };
+}
+function governanceRegions(value) {
+    if (!Array.isArray(value))
+        throw new PayloadError("governance.regions must be a list");
+    if (value.length > MAX_GOVERNANCE_REGIONS)
+        throw new PayloadError("governance.regions exceeds its bound");
+    return value.map((raw, index) => {
+        const entry = asRecord(raw, `governance.regions[${index}]`);
+        const tag = typeof entry.tag === "string" ? entry.tag : "";
+        const regionPath = normalizeRepoRelativePath(entry.path);
+        const begin = entry.begin_marker;
+        const end = entry.end_marker;
+        const sha = entry.content_sha256;
+        if (!TAG_RE.test(tag) ||
+            regionPath === null ||
+            typeof begin !== "string" ||
+            typeof end !== "string" ||
+            !begin.includes(tag) ||
+            !end.includes(tag) ||
+            typeof sha !== "string" ||
+            !SHA256_HEX_RE.test(sha) ||
+            !Number.isInteger(entry.begin_line) ||
+            !Number.isInteger(entry.end_line)) {
+            throw new PayloadError(`governance.regions[${index}] is malformed`);
+        }
+        return {
+            tag,
+            path: regionPath,
+            beginLine: entry.begin_line,
+            endLine: entry.end_line,
+            beginMarker: begin,
+            endMarker: end,
+            contentSha256: sha,
+        };
+    });
+}
+function governanceFindings(value) {
+    if (value === undefined || value === null)
+        return [];
+    if (!Array.isArray(value))
+        throw new PayloadError("governance.findings must be a list");
+    return value.map((raw, index) => {
+        const entry = asRecord(raw, `governance.findings[${index}]`);
+        const findingPath = normalizeRepoRelativePath(entry.path);
+        if (findingPath === null)
+            throw new PayloadError(`governance.findings[${index}].path is unsafe`);
+        return { path: findingPath, reason: typeof entry.reason === "string" ? entry.reason.slice(0, 300) : "" };
+    });
+}
+/**
+ * Validate the claimed job's payload. Pure — no subprocess, no filesystem. A
+ * payload missing either input SHA fails here, so the job never infers a head.
+ */
+export function validateReconcileOverlapPayload(job) {
+    try {
+        const payload = asRecord(job.payload, "payload");
+        if (payload.schema_version !== RECONCILE_OVERLAP_PAYLOAD_SCHEMA_VERSION) {
+            throw new PayloadError(`payload.schema_version must be ${RECONCILE_OVERLAP_PAYLOAD_SCHEMA_VERSION}`);
+        }
+        const childHead = requiredSha(payload.child_head, "payload.child_head");
+        const requiredEpicSha = requiredSha(payload.required_epic_sha, "payload.required_epic_sha");
+        const epicBranch = refName(payload.epic_branch, "payload.epic_branch");
+        // The push destination is the claimed job's TOP-LEVEL expected_branch — the
+        // server-bound identity — never a payload field.
+        const expectedBranch = refName(job.expected_branch, "expected_branch");
+        const prNumber = payload.pr_number;
+        if (typeof prNumber !== "number" || !Number.isInteger(prNumber) || prNumber <= 0) {
+            throw new PayloadError("payload.pr_number must be a positive integer");
+        }
+        const requiredChecksRaw = payload.required_checks ?? [];
+        if (!Array.isArray(requiredChecksRaw))
+            throw new PayloadError("payload.required_checks must be a list");
+        const requiredChecks = requiredChecksRaw
+            .filter((c) => typeof c === "string" && c.trim().length > 0)
+            .map((c) => c.trim());
+        const child = ticketContext(payload.child, "payload.child");
+        const peer = payload.peer === null || payload.peer === undefined ? null : ticketContext(payload.peer, "payload.peer");
+        const governanceRaw = asRecord(payload.governance, "payload.governance");
+        const conflictReportPath = normalizeRepoRelativePath(payload.conflict_report_path);
+        if (conflictReportPath === null || !conflictReportPath.startsWith(CONFLICT_REPORT_DIR)) {
+            throw new PayloadError("payload.conflict_report_path must name a file under .conductor/");
+        }
+        const prompt = payload.prompt;
+        if (typeof prompt !== "string" || prompt.trim().length === 0) {
+            throw new PayloadError("payload.prompt is missing or blank");
+        }
+        const generation = payload.reconcile_generation ?? 0;
+        if (typeof generation !== "number" || !Number.isInteger(generation) || generation < 0) {
+            throw new PayloadError("payload.reconcile_generation must be a non-negative integer");
+        }
+        return {
+            ok: true,
+            value: {
+                schemaVersion: RECONCILE_OVERLAP_PAYLOAD_SCHEMA_VERSION,
+                childHead,
+                requiredEpicSha,
+                epicBranch,
+                expectedBranch,
+                prNumber,
+                requiredChecks,
+                child,
+                peer,
+                governance: {
+                    regions: governanceRegions(governanceRaw.regions ?? []),
+                    findings: governanceFindings(governanceRaw.findings),
+                    scannedPaths: pathList(governanceRaw.scanned_paths ?? [], "governance.scanned_paths", MAX_CHANGED_FILES * 2),
+                },
+                declaredTouchedFilesUnion: pathList(payload.declared_touched_files_union ?? [], "payload.declared_touched_files_union", MAX_CHANGED_FILES * 4),
+                conflictReportPath,
+                prompt,
+                reconcileGeneration: generation,
+            },
+        };
+    }
+    catch (err) {
+        if (err instanceof PayloadError)
+            return { ok: false, error: err.message };
+        return { ok: false, error: "payload could not be validated" };
+    }
+}
+/** Thrown between steps when the supervising phase has been aborted. */
+export class ReconcileOverlapAborted extends Error {
+}
+/** Thrown by a provider-check poller that has no Bridge API access at all. */
+export class ProviderChecksUnobservable extends Error {
+}
+/**
+ * A provider-check poller that resolves Bridge API access once, on first use —
+ * the same read-only CI poll the `merge` job waits on. Without access it throws
+ * {@link ProviderChecksUnobservable}, and the wait ends immediately rather than
+ * sleeping out the job budget; the server's completion contract then reads the
+ * checks itself.
+ */
+export function lazyProviderCheckPoller(accessDeps) {
+    let access;
+    return async (sha) => {
+        if (access === undefined) {
+            const resolved = await resolveConductorBridgeApiAccess(accessDeps);
+            access = resolved.ok ? resolved.access : null;
+        }
+        if (access === null)
+            throw new ProviderChecksUnobservable("bridge api access unavailable");
+        return pollCiChecksForCommit(access, sha);
+    };
+}
+function bounded(text, max) {
+    if (text.length <= max)
+        return text;
+    const keep = max - TRUNCATION_MARKER.length;
+    return keep > 0 ? text.slice(0, keep) + TRUNCATION_MARKER : text.slice(0, max);
+}
+function tail(text) {
+    return text.length <= COMMAND_OUTPUT_TAIL_CHARS ? text : "…" + text.slice(-COMMAND_OUTPUT_TAIL_CHARS);
+}
+/** The deduplicated union of both tickets' commands, child first. */
+export function verificationCommandUnion(child, peer) {
+    const seen = new Set();
+    const out = [];
+    for (const command of [...child.verificationCommands, ...(peer?.verificationCommands ?? [])]) {
+        const key = JSON.stringify(command.argv);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(command);
+    }
+    return out;
+}
+/** Build the fact envelope, bounded before submission. */
+export function buildReconcileEnvelope(payload, facts, extra = {}) {
+    const edited = [...facts.editedPaths].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+    const checks = facts.checksObserved;
+    const envelope = {
+        child_head_in: payload.childHead,
+        required_epic_sha: payload.requiredEpicSha,
+        merge_classification: facts.classification,
+        worker_invoked: facts.workerInvoked,
+        edited_paths: edited.slice(0, RECONCILE_EDITED_PATHS_MAX).map((e) => ({
+            path: bounded(e.path, RECONCILE_PATH_MAX_CHARS),
+            reason: bounded(e.reason, RECONCILE_REASON_MAX_CHARS),
+        })),
+        checks_observed: checks.slice(0, RECONCILE_CHECKS_OBSERVED_MAX).map((c) => ({
+            name: bounded(c.name, RECONCILE_CHECK_NAME_MAX_CHARS),
+            conclusion: bounded(c.conclusion, RECONCILE_CHECK_CONCLUSION_MAX_CHARS),
+        })),
+        edited_paths_truncated: Math.max(0, edited.length - RECONCILE_EDITED_PATHS_MAX),
+        checks_observed_truncated: Math.max(0, checks.length - RECONCILE_CHECKS_OBSERVED_MAX),
+    };
+    for (const [key, value] of Object.entries(extra)) {
+        if (value !== undefined)
+            envelope[key] = value;
+    }
+    return envelope;
+}
+function anyRequiredCheckFailed(pollResponse, required) {
+    if (pollResponse === null || typeof pollResponse !== "object")
+        return false;
+    let obj = pollResponse;
+    const detail = obj.detail;
+    if (detail && typeof detail === "object" && Array.isArray(detail.checks)) {
+        obj = detail;
+    }
+    const checks = Array.isArray(obj.checks) ? obj.checks : [];
+    const wanted = new Set(required);
+    return checks.some((c) => {
+        if (!c || typeof c !== "object")
+            return false;
+        const name = typeof c.name === "string" ? c.name : "";
+        const conclusion = typeof c.conclusion === "string" ? c.conclusion.toLowerCase() : "";
+        return wanted.has(name) && FAILED_CHECK_CONCLUSIONS.has(conclusion);
+    });
+}
+// ---------------------------------------------------------------------------
+// The driver
+// ---------------------------------------------------------------------------
+/**
+ * Build the `reconcile_overlap` spawn driver for a validated payload.
+ *
+ * Exported so the state machine is unit-testable against a real temporary git
+ * repository without the job runner around it.
+ */
+export function createReconcileOverlapDriver(job, payload, seams) {
+    const facts = {
+        classification: null,
+        workerInvoked: false,
+        mode: null,
+        mergeCommitSha: null,
+        preWorkerHead: null,
+        checks: new Map(),
+        failingCommandNames: [],
+        editedReasons: new Map(),
+    };
+    const commands = verificationCommandUnion(payload.child, payload.peer);
+    const workerEnv = buildExecutorBaseWorkerEnv(seams.env);
+    const git = async (ctx, args, timeoutMs = GIT_TIMEOUT_MS, env) => {
+        if (ctx.signal?.aborted)
+            throw new ReconcileOverlapAborted("reconciliation phase aborted");
+        return seams.runCommand("git", args, {
+            cwd: ctx.worktreePath,
+            timeoutMs,
+            ...(env ? { env } : {}),
+        });
+    };
+    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 isAncestor = async (ctx, ancestor, head) => {
+        const r = await git(ctx, ["merge-base", "--is-ancestor", ancestor, head]);
+        return r.exitCode === 0;
+    };
+    const fail = (errorKind, phase, message) => ({
+        kind: "fail",
+        failure: {
+            error_kind: errorKind,
+            error_message: bounded(`reconcile_overlap [${phase}]: ${message}`, 500),
+            classification: "crashed",
+        },
+    });
+    const classificationKind = () => facts.classification?.kind === "conflicted" ? "conflicted" : "clean";
+    const envelope = (extra = {}) => buildReconcileEnvelope(payload, {
+        classification: classificationKind(),
+        workerInvoked: facts.workerInvoked,
+        editedPaths: Array.from(facts.editedReasons.entries()).map(([p, reason]) => ({ path: p, reason })),
+        checksObserved: Array.from(facts.checks.entries()).map(([name, conclusion]) => ({ name, conclusion })),
+    }, extra);
+    const complete = (extra = {}, lastCommitSha) => ({
+        kind: "complete",
+        result: envelope(extra),
+        ...(lastCommitSha ? { lastCommitSha } : {}),
+    });
+    /** Reset to the recorded child head. Never throws. */
+    const resetToChildHead = async (ctx) => {
+        try {
+            const mergeHead = await seams.runCommand("git", ["rev-parse", "-q", "--verify", "MERGE_HEAD"], {
+                cwd: ctx.worktreePath,
+                timeoutMs: GIT_TIMEOUT_MS,
+            });
+            if (mergeHead.exitCode === 0) {
+                await seams.runCommand("git", ["merge", "--abort"], { cwd: ctx.worktreePath, timeoutMs: GIT_TIMEOUT_MS });
+            }
+            await seams.runCommand("git", ["reset", "--hard", payload.childHead], {
+                cwd: ctx.worktreePath,
+                timeoutMs: GIT_TIMEOUT_MS,
+            });
+            // The existing safe worktree cleanup: removes untracked, non-ignored
+            // residue. `.conductor/` is excluded explicitly as well as through
+            // `.git/info/exclude`: on a freshly prepared worktree in a foreign
+            // repository the exclude line may not be provisioned yet, and the executor's
+            // own artifacts (the worker log among them) must survive the reset.
+            await seams.runCommand("git", ["clean", "-fd", "-e", CONDUCTOR_ARTIFACT_DIR], {
+                cwd: ctx.worktreePath,
+                timeoutMs: GIT_TIMEOUT_MS,
+            });
+        }
+        catch (err) {
+            seams.errorLog(`[executor] job ${job.id}: reconcile_overlap reset to the recorded child head failed (${err instanceof Error ? err.message.slice(0, 120) : "unknown error"})`);
+        }
+    };
+    const writeReport = async (ctx, body) => {
+        const target = path.join(ctx.worktreePath, ...payload.conflictReportPath.split("/"));
+        await seams.mkdir(path.dirname(target), { recursive: true });
+        await seams.writeFile(target, body);
+    };
+    const conflictReport = (failing) => {
+        const lines = [
+            "# reconcile_overlap report",
+            "",
+            `Merge classification: ${classificationKind()}`,
+            `Child head: ${payload.childHead}`,
+            `Required epic SHA: ${payload.requiredEpicSha}`,
+            "",
+        ];
+        if (facts.classification?.kind === "conflicted") {
+            lines.push("## Conflicts (from git merge-tree --write-tree)", "");
+            for (const conflict of facts.classification.conflicts) {
+                lines.push(`- ${conflict.path} — ${conflict.descriptor}`);
+                for (const message of conflict.messages)
+                    lines.push(`  - ${message}`);
+            }
+            lines.push("");
+        }
+        else {
+            lines.push("The merge was clean. The executor committed it; fix what the checks below report.", "");
+        }
+        if (failing.length > 0) {
+            lines.push("## Failing local verification commands", "");
+            for (const run of failing) {
+                lines.push(`### ${run.observation.name} (${run.observation.conclusion})`, "", "```", tail(run.output), "```", "");
+            }
+        }
+        return lines.join("\n");
+    };
+    /** Run the union of local verification commands. Never a provider check. */
+    const runVerification = async (ctx) => {
+        const runs = [];
+        for (const command of commands) {
+            if (ctx.signal.aborted)
+                throw new ReconcileOverlapAborted("reconciliation phase aborted");
+            const budget = Math.min(command.timeoutSeconds * 1000, ctx.remainingMs() - CI_WAIT_MARGIN_MS);
+            let conclusion;
+            let output = "";
+            if (budget <= 0) {
+                conclusion = "not_run";
+            }
+            else {
+                const started = seams.now();
+                try {
+                    const [file, ...args] = command.argv;
+                    const result = await seams.runCommand(file, args, {
+                        cwd: ctx.worktreePath,
+                        timeoutMs: budget,
+                        // The SAME secret-free environment a worker gets, including the
+                        // sentinel database target: a verification command can no more reach
+                        // the operator's real database than a worker can.
+                        env: workerEnv,
+                    });
+                    output = `${result.stdout}\n${result.stderr}`;
+                    if (result.exitCode === 0)
+                        conclusion = "success";
+                    else
+                        conclusion = seams.now() - started >= budget - 50 ? "timed_out" : "failure";
+                }
+                catch {
+                    conclusion = "error";
+                }
+            }
+            const observation = { name: command.name, conclusion };
+            facts.checks.set(command.name, conclusion);
+            runs.push({ observation, green: conclusion === "success", output });
+        }
+        return runs;
+    };
+    /** Paths the candidate changes relative to the input epic head. */
+    const changedPathsAgainstEpic = async (ctx, candidate) => {
+        const r = await git(ctx, ["diff", "--name-only", "-z", "--no-renames", payload.requiredEpicSha, candidate]);
+        if (r.exitCode !== 0)
+            return null;
+        return r.stdout
+            .split("\0")
+            .map((p) => normalizeRepoRelativePath(p))
+            .filter((p) => p !== null);
+    };
+    const readTreeFile = async (ctx, treeish, filePath) => {
+        const r = await git(ctx, ["cat-file", "blob", `${treeish}:${filePath}`]);
+        if (r.exitCode !== 0) {
+            const exists = await git(ctx, ["cat-file", "-e", `${treeish}:${filePath}`]);
+            return exists.exitCode === 0 ? { kind: "unreadable" } : { kind: "absent" };
+        }
+        return r.stdout.includes("\0") ? { kind: "binary" } : { kind: "text", text: r.stdout };
+    };
+    /** Governance scan of a candidate tree or commit against the input epic head. */
+    const scanCandidate = async (ctx, candidate) => {
+        const changed = await changedPathsAgainstEpic(ctx, candidate);
+        if (changed === null)
+            return "unprovable";
+        return scanGovernanceRegions({
+            snapshot: payload.governance,
+            changedPaths: changed,
+            readCandidate: (p) => readTreeFile(ctx, candidate, p),
+            readInput: (p) => readTreeFile(ctx, payload.requiredEpicSha, p),
+        });
+    };
+    const unprovableFact = () => ({
+        tag: "GOVERNANCE_MARKERS_UNPROVABLE",
+        paths: [],
+        findings: [{ tag: "GOVERNANCE_MARKERS_UNPROVABLE", paths: [] }],
+        truncated: false,
+    });
+    /** `git write-tree` of the index: the candidate BEFORE a commit exists. */
+    const indexTree = async (ctx) => {
+        const r = await git(ctx, ["write-tree"]);
+        const oid = r.stdout.trim().toLowerCase();
+        return r.exitCode === 0 && SHA_RE.test(oid) ? oid : null;
+    };
+    const governanceGate = async (ctx, candidate) => {
+        const scanned = candidate === null ? "unprovable" : await scanCandidate(ctx, candidate);
+        if (scanned === null)
+            return null;
+        await resetToChildHead(ctx);
+        return complete({ governance_guard_change_required: scanned === "unprovable" ? unprovableFact() : scanned });
+    };
+    const commitStaged = async (ctx, message) => {
+        const r = await git(ctx, ["commit", "--no-verify", "--no-edit", "-m", message]);
+        if (r.exitCode !== 0)
+            return null;
+        return revParse(ctx, "HEAD");
+    };
+    const stagedChanges = async (ctx) => {
+        const r = await git(ctx, ["diff", "--cached", "--quiet"]);
+        return r.exitCode === 1;
+    };
+    /** Read both remote heads immediately before the push. */
+    const readRemoteHeads = async (ctx) => {
+        const childRef = `refs/heads/${payload.expectedBranch}`;
+        const epicRef = `refs/heads/${payload.epicBranch}`;
+        const r = await git(ctx, ["ls-remote", "origin", childRef, epicRef], GIT_TIMEOUT_MS, {
+            ...seams.env,
+            GIT_TERMINAL_PROMPT: "0",
+        });
+        if (r.exitCode !== 0) {
+            await resetToChildHead(ctx);
+            return {
+                ok: false,
+                outcome: PUSH_AUTH_FAILURE_RE.test(r.stderr)
+                    ? fail(ReconcileOverlapPushUnauthorized, "pushed", "the executor's git credential helper refused the remote read")
+                    : fail(ReconcileOverlapPushRejected, "pushed", "the remote heads could not be read before the push"),
+            };
+        }
+        let child = null;
+        let epic = null;
+        for (const line of r.stdout.split("\n")) {
+            const [sha, ref] = line.trim().split(/\s+/);
+            if (!sha || !ref)
+                continue;
+            if (ref === childRef)
+                child = sha.toLowerCase();
+            if (ref === epicRef)
+                epic = sha.toLowerCase();
+        }
+        return { ok: true, child, epic };
+    };
+    /** Wait for provider checks on the pushed head. The SERVER decides; this only waits. */
+    const waitForProviderChecks = async (ctx, sha) => {
+        if (payload.requiredChecks.length === 0 || !seams.pollProviderChecks)
+            return;
+        while (ctx.remainingMs() > CI_WAIT_MARGIN_MS && !ctx.signal.aborted) {
+            let response;
+            try {
+                response = await seams.pollProviderChecks(sha);
+            }
+            catch (err) {
+                if (err instanceof ProviderChecksUnobservable)
+                    return;
+                response = undefined;
+            }
+            if (response !== undefined) {
+                if (allRequiredChecksGreen(response, payload.requiredChecks))
+                    return;
+                if (anyRequiredCheckFailed(response, payload.requiredChecks))
+                    return;
+            }
+            await seams.sleep(Math.min(CI_WAIT_POLL_INTERVAL_MS, Math.max(0, ctx.remainingMs() - CI_WAIT_MARGIN_MS)));
+        }
+    };
+    /** Drift check, final governance scan, guarded push, finalization, CI wait. */
+    const pushFlow = async (ctx) => {
+        const candidate = await revParse(ctx, "HEAD");
+        if (candidate === null) {
+            await resetToChildHead(ctx);
+            return fail(ReconcileOverlapTopologyRefused, "governance-scanned", "the candidate head could not be read");
+        }
+        // (1) Freshness: both remote heads must still be the dispatched ones. A moved
+        // head is an OBSERVATION the server re-dispatches on; it is not a failure.
+        const heads = await readRemoteHeads(ctx);
+        if (!heads.ok)
+            return heads.outcome;
+        if (heads.child !== payload.childHead) {
+            await resetToChildHead(ctx);
+            if (heads.child === null) {
+                return fail(ReconcileOverlapPushRejected, "pushed", "the child branch no longer exists on origin");
+            }
+            return complete({ observed_child_head: heads.child });
+        }
+        if (heads.epic !== payload.requiredEpicSha) {
+            // Includes an epic head that advanced to a descendant: the reconciliation
+            // was computed against a commit that is no longer the tip. The residual
+            // window between this read and the push is contained by the server, which
+            // re-verifies the pushed head's ancestry on the following tick.
+            await resetToChildHead(ctx);
+            if (heads.epic === null) {
+                return fail(ReconcileOverlapPushRejected, "pushed", "the epic branch no longer exists on origin");
+            }
+            return complete({ observed_epic_head: heads.epic });
+        }
+        // (2) Final governance scan of the exact tree about to be pushed.
+        const gated = await governanceGate(ctx, candidate);
+        if (gated !== null)
+            return gated;
+        // (3) The ONE push: a fast-forward of the child branch, leased on the
+        // recorded child head. Never plain --force, never a lease-less lease.
+        const destination = `refs/heads/${payload.expectedBranch}`;
+        const push = await git(ctx, [
+            "push",
+            "--no-verify",
+            "--porcelain",
+            `--force-with-lease=${destination}:${payload.childHead}`,
+            "origin",
+            `HEAD:${destination}`,
+        ], PUSH_TIMEOUT_MS, { ...seams.env, GIT_TERMINAL_PROMPT: "0" });
+        if (push.exitCode !== 0) {
+            const text = `${push.stdout}\n${push.stderr}`;
+            if (PUSH_AUTH_FAILURE_RE.test(text)) {
+                await resetToChildHead(ctx);
+                return fail(ReconcileOverlapPushUnauthorized, "pushed", "the executor's git credential helper refused the push");
+            }
+            if (PUSH_LEASE_FAILURE_RE.test(text)) {
+                const reread = await readRemoteHeads(ctx);
+                await resetToChildHead(ctx);
+                if (reread.ok && reread.child !== null && reread.child !== payload.childHead) {
+                    return complete({ observed_child_head: reread.child });
+                }
+            }
+            else {
+                await resetToChildHead(ctx);
+            }
+            return fail(ReconcileOverlapPushRejected, "pushed", "the remote refused the guarded push");
+        }
+        // (4) Finalization runs ONCE, after the wrapper's push, against the pushed
+        // head: origin must carry it and the PR must be attached at it.
+        const finalize = seams.finalize ?? validateWorkerFinalization;
+        const finalization = await finalize({
+            job,
+            branch: payload.expectedBranch,
+            worktreePath: ctx.worktreePath,
+            result: {},
+            runCommand: seams.runCommand,
+            headSha: candidate,
+            expectedBaseBranch: ctx.effectiveBaseBranch,
+            originResolveAttempts: FINALIZATION_ATTEMPTS,
+            originResolveRetryDelayMs: FINALIZATION_RETRY_DELAY_MS,
+            sleep: seams.sleep,
+        });
+        if (!finalization.ok)
+            return { kind: "fail", failure: finalization.failure };
+        // (5) Wait for provider checks at the pushed head, bounded by the job budget.
+        await waitForProviderChecks(ctx, candidate);
+        return complete({ resulting_head: candidate }, candidate);
+    };
+    const ensureCommit = async (ctx, sha) => {
+        if ((await git(ctx, ["cat-file", "-e", `${sha}^{commit}`])).exitCode === 0)
+            return true;
+        await git(ctx, ["fetch", "--no-tags", "origin", sha], GIT_TIMEOUT_MS, { ...seams.env, GIT_TERMINAL_PROMPT: "0" });
+        return (await git(ctx, ["cat-file", "-e", `${sha}^{commit}`])).exitCode === 0;
+    };
+    return {
+        omitWorkerBranch: true,
+        async beforeWorker(ctx) {
+            const finish = (outcome) => ({ kind: "finish", outcome });
+            if (ctx.branch !== payload.expectedBranch) {
+                return finish(fail(ReconcileOverlapBranchMismatch, "validated", "the prepared worktree is not on the job's expected branch"));
+            }
+            // Fetch the exact server-supplied inputs. The job never infers a head.
+            await git(ctx, ["fetch", "--no-tags", "origin", payload.epicBranch], GIT_TIMEOUT_MS, {
+                ...seams.env,
+                GIT_TERMINAL_PROMPT: "0",
+            });
+            for (const sha of [payload.childHead, payload.requiredEpicSha]) {
+                if (!(await ensureCommit(ctx, sha))) {
+                    return finish(fail(ReconcileOverlapMergeFailed, "classified", `commit ${sha.slice(0, 12)} could not be fetched`));
+                }
+            }
+            // Classify BEFORE anything moves.
+            const classification = await classifyMergeTree(seams.runCommand, ctx.worktreePath, payload.childHead, payload.requiredEpicSha);
+            if (classification.kind === "operational_error") {
+                return finish(fail(ReconcileOverlapMergeFailed, "classified", classification.reason));
+            }
+            facts.classification = classification;
+            if (classification.kind === "conflicted") {
+                for (const conflict of classification.conflicts) {
+                    facts.editedReasons.set(conflict.path, conflict.descriptor);
+                }
+            }
+            const head = await revParse(ctx, "HEAD");
+            if (head !== payload.childHead) {
+                // Worktree preparation reset to origin's branch tip, and that tip is not
+                // the head the server dispatched: the child moved. An observation.
+                await resetToChildHead(ctx);
+                if (head === null) {
+                    return finish(fail(ReconcileOverlapTopologyRefused, "classified", "the prepared worktree HEAD could not be read"));
+                }
+                return finish(complete({ observed_child_head: head }));
+            }
+            if (await isAncestor(ctx, payload.requiredEpicSha, payload.childHead)) {
+                return finish(fail(ReconcileOverlapNothingToMerge, "classified", "the child head already contains the required epic commit"));
+            }
+            // Materialize the real merge. Never a rebase.
+            const merge = await git(ctx, ["merge", "--no-ff", "--no-commit", "--no-edit", payload.requiredEpicSha], GIT_TIMEOUT_MS, { ...seams.env, GIT_MERGE_AUTOEDIT: "no" });
+            const mergedCleanly = merge.exitCode === 0;
+            if (mergedCleanly !== (classification.kind === "clean") || (merge.exitCode !== 0 && merge.exitCode !== 1)) {
+                await resetToChildHead(ctx);
+                return finish(fail(ReconcileOverlapMergeFailed, "merged", "the materialized merge disagreed with its merge-tree classification"));
+            }
+            const mergeHead = await revParse(ctx, "MERGE_HEAD");
+            if (mergeHead !== payload.requiredEpicSha) {
+                await resetToChildHead(ctx);
+                return finish(fail(ReconcileOverlapMergeFailed, "merged", "the merge did not record the required epic commit"));
+            }
+            if (classification.kind === "conflicted") {
+                facts.mode = "conflicted";
+                facts.workerInvoked = true;
+                facts.preWorkerHead = payload.childHead;
+                await writeReport(ctx, conflictReport([]));
+                return {
+                    kind: "spawn_worker",
+                    prompt: payload.prompt,
+                    // Stricter than the generic check: HEAD is the child head AND the merge
+                    // of the required epic commit is in progress.
+                    preSpawnVerification: { ok: true, observedSha: payload.childHead },
+                    declaredTouchedFiles: payload.declaredTouchedFilesUnion,
+                };
+            }
+            // Clean: scan the merged index BEFORE the wrapper creates the merge commit.
+            const gated = await governanceGate(ctx, await indexTree(ctx));
+            if (gated !== null)
+                return finish(gated);
+            const mergeCommit = await commitStaged(ctx, `Reconcile overlap: merge ${payload.requiredEpicSha.slice(0, 12)} into ${payload.expectedBranch}`);
+            if (mergeCommit === null) {
+                await resetToChildHead(ctx);
+                return finish(fail(ReconcileOverlapMergeFailed, "merged", "the wrapper could not create the merge commit"));
+            }
+            facts.mergeCommitSha = mergeCommit;
+            const runs = await runVerification(ctx);
+            const failing = runs.filter((r) => !r.green);
+            if (failing.length === 0) {
+                // Clean AND green: push with no LLM at all.
+                return finish(await pushFlow(ctx));
+            }
+            facts.failingCommandNames = failing.map((r) => r.observation.name);
+            facts.mode = "clean_red";
+            facts.workerInvoked = true;
+            facts.preWorkerHead = mergeCommit;
+            await writeReport(ctx, conflictReport(failing));
+            // `.conductor/` holds the executor's own report for the worker; it is not a
+            // change to the candidate.
+            const status = await git(ctx, ["status", "--porcelain", "--", ".", ...WRAPPER_STAGE_EXCLUDES]);
+            if (status.exitCode !== 0 || status.stdout.trim().length > 0) {
+                await resetToChildHead(ctx);
+                return finish(fail(ReconcileOverlapMergeFailed, "checked", "the worktree was not clean at the merge commit"));
+            }
+            return {
+                kind: "spawn_worker",
+                prompt: payload.prompt,
+                preSpawnVerification: { ok: true, observedSha: mergeCommit },
+                declaredTouchedFiles: payload.declaredTouchedFilesUnion,
+            };
+        },
+        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");
+            const expectedMergeHead = facts.mode === "conflicted" ? payload.requiredEpicSha : null;
+            if (head !== facts.preWorkerHead || mergeHead !== expectedMergeHead) {
+                await resetToChildHead(ctx);
+                return fail(ReconcileOverlapWorkerRewroteHistory, "worker-completed", "the worker moved HEAD, committed, or changed the in-progress merge; commits are the wrapper's alone");
+            }
+            if (facts.mode === "conflicted" && facts.classification?.kind === "conflicted") {
+                const conflictPaths = facts.classification.conflicts
+                    .map((c) => c.path)
+                    .filter((p) => p !== "(unreported)");
+                for (const conflictPath of conflictPaths) {
+                    const read = await readWorkingFile(ctx, conflictPath);
+                    if (read !== null && /^(<{7} |={7}$|>{7} )/m.test(read)) {
+                        await resetToChildHead(ctx);
+                        return fail(ReconcileOverlapConflictsUnresolved, "worker-completed", `conflict markers remain in ${conflictPath}`);
+                    }
+                }
+                // Stage ONLY the resolved conflict paths: the merge commit is the
+                // conflict resolution, and any other repair becomes its own commit.
+                if (conflictPaths.length > 0) {
+                    await git(ctx, ["add", "-A", "--", ...conflictPaths]);
+                }
+                const unmerged = await git(ctx, ["ls-files", "-u"]);
+                if (unmerged.exitCode !== 0 || unmerged.stdout.trim().length > 0) {
+                    await resetToChildHead(ctx);
+                    return fail(ReconcileOverlapConflictsUnresolved, "worker-completed", "unmerged index entries remain");
+                }
+                const gated = await governanceGate(ctx, await indexTree(ctx));
+                if (gated !== null)
+                    return gated;
+                const mergeCommit = await commitStaged(ctx, `Reconcile overlap: merge ${payload.requiredEpicSha.slice(0, 12)} into ${payload.expectedBranch}`);
+                if (mergeCommit === null) {
+                    await resetToChildHead(ctx);
+                    return fail(ReconcileOverlapMergeFailed, "worker-completed", "the wrapper could not create the merge commit");
+                }
+                facts.mergeCommitSha = mergeCommit;
+            }
+            // Any remaining worker repair: one ordinary commit ON TOP of the merge.
+            await git(ctx, ["add", "-A", "--", ".", ...WRAPPER_STAGE_EXCLUDES]);
+            if (await stagedChanges(ctx)) {
+                const gated = await governanceGate(ctx, await indexTree(ctx));
+                if (gated !== null)
+                    return gated;
+                const repairPaths = await git(ctx, ["diff", "--cached", "--name-only", "-z"]);
+                const repairReason = facts.failingCommandNames.length > 0
+                    ? `repair for failing check(s): ${facts.failingCommandNames.join(", ")}`
+                    : "repair after conflict resolution";
+                for (const repaired of repairPaths.stdout.split("\0")) {
+                    const normalized = normalizeRepoRelativePath(repaired);
+                    if (normalized && !facts.editedReasons.has(normalized))
+                        facts.editedReasons.set(normalized, repairReason);
+                }
+                const repair = await commitStaged(ctx, "Reconcile overlap: repair on top of the merge");
+                if (repair === null) {
+                    await resetToChildHead(ctx);
+                    return fail(ReconcileOverlapMergeFailed, "worker-completed", "the wrapper could not commit the worker's repair");
+                }
+            }
+            // Re-run the union of local checks on the final candidate.
+            const runs = await runVerification(ctx);
+            const failing = runs.filter((r) => !r.green);
+            if (failing.length > 0) {
+                await resetToChildHead(ctx);
+                return fail(ReconcileOverlapVerificationRed, "checked", `local verification still red after the reconciliation: ${failing.map((r) => r.observation.name).join(", ")}`);
+            }
+            // Topology: a two-parent merge of exactly the dispatched heads, contained in
+            // the candidate, which itself contains both input heads.
+            const candidate = await revParse(ctx, "HEAD");
+            const mergeCommit = facts.mergeCommitSha;
+            const parents = mergeCommit ? await git(ctx, ["rev-list", "--parents", "-n", "1", mergeCommit]) : null;
+            const parentList = parents?.stdout.trim().split(/\s+/).slice(1) ?? [];
+            if (candidate === null ||
+                mergeCommit === null ||
+                parentList.length !== 2 ||
+                parentList[0] !== payload.childHead ||
+                parentList[1] !== payload.requiredEpicSha ||
+                !(await isAncestor(ctx, mergeCommit, candidate)) ||
+                !(await isAncestor(ctx, payload.childHead, candidate)) ||
+                !(await isAncestor(ctx, payload.requiredEpicSha, candidate))) {
+                await resetToChildHead(ctx);
+                return fail(ReconcileOverlapTopologyRefused, "governance-scanned", "the candidate is not a merge of the dispatched heads");
+            }
+            return pushFlow(ctx);
+        },
+        async abandon(ctx) {
+            await resetToChildHead(ctx);
+        },
+    };
+    /** The working-tree text of a path, or `null` when it was deleted. */
+    async function readWorkingFile(ctx, filePath) {
+        try {
+            return await seams.readFile(path.join(ctx.worktreePath, ...filePath.split("/")));
+        }
+        catch {
+            return null;
+        }
+    }
+}
+/**
+ * Run a claimed `reconcile_overlap` job. The payload is validated FIRST — a
+ * missing or blank input SHA fails the contract before any subprocess spawns and
+ * before the worktree is prepared.
+ */
+export async function runReconcileOverlapJob(job, runner, seams) {
+    const validated = validateReconcileOverlapPayload(job);
+    if (!validated.ok) {
+        return runner.fail({
+            error_kind: ReconcileOverlapPayloadInvalid,
+            error_message: `reconcile_overlap payload rejected: ${validated.error}`,
+            classification: "crashed",
+        });
+    }
+    return runner.runLockedSpawn(createReconcileOverlapDriver(job, validated.value, seams));
+}