@bridge_gpt/mcp-server 0.2.66 → 0.2.68

package/build/executor/gate-qualification-job.js

@@ -0,0 +1,499 @@
+/**
+ * Deterministic `gate_qualification` executor job (BAPI-1391).
+ *
+ * A repository owner confirms a gate profile: the local commands that must pass
+ * before an unattended Epic Implementer run may rely on it. Confirming is not
+ * proof the commands work. This job is the proof. It runs the confirmed
+ * commands ONCE, on a clean, detached checkout of the default branch resolved
+ * at claim time, and reports bounded FACTS so the server can record a
+ * qualification. Like `ci_rerun` it is run-less and deterministic: no worker,
+ * no LLM, no worktrunk worktree, and no fallback to any of those.
+ *
+ * Five properties are load-bearing:
+ *
+ * 1. **Validate before any effect.** Every payload rule in the cross-runtime
+ *    contract — shape, bounds, every command digest and identity, the
+ *    `command_digests` list, and the envelope digest — is recomputed here
+ *    BEFORE any git or command runs. A job that cannot prove exactly which
+ *    commands it was asked to run must not run anything and discover the
+ *    problem afterwards. Any failure is a contract refusal.
+ *
+ * 2. **What is tested is what is reported.** The default branch is resolved
+ *    from the remote at claim time, fetched, pinned to a full SHA, and checked
+ *    out DETACHED into a fresh temporary directory outside the owner's working
+ *    tree. The checkout must sit exactly at that SHA with a clean tracked tree,
+ *    or the job reports an inability instead of a result. `tested_head_sha` is
+ *    that SHA. The owner's own working tree and branch are never touched; the
+ *    temporary checkout is always removed.
+ *
+ * 3. **Only the payload commands, in payload order.** They run through the
+ *    shared required-verification core (argv, never a shell) with an EXPLICIT
+ *    environment built from the executor's worker base environment plus
+ *    `CI=1`. `process.env` is never handed to a command.
+ *
+ * 4. **Facts, never output.** The result carries an identity, a closed outcome
+ *    and reason, and a duration per command. No name, argv, exit code, output,
+ *    or path ever reaches the server, a `/fail` message, telemetry, or
+ *    diagnostics. A command's local output tail is printed only on the owner's
+ *    own terminal (see {@link GateQualificationDeps.showLocalOutput}).
+ *
+ * 5. **A failure is a result; an interruption is not.** A command that exits
+ *    non-zero, times out, or cannot launch is a COMPLETED job with
+ *    `outcome: "failed"` — that is exactly what qualification exists to learn.
+ *    A command cut short by shutdown or lost ownership proved nothing about the
+ *    gate, so it is reported as an inability (`GateQualificationInterrupted`)
+ *    and never recorded as an unqualified gate.
+ */
+import { createHash } from "node:crypto";
+import { mkdtemp, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { validateBranchName } from "../base-ref.js";
+import { buildExecutorBaseWorkerEnv } from "./env.js";
+import { ARTIFACT_GIT_TIMEOUT_MS, OWNERSHIP_POLL_MS, canonicalJson, createSupervisedCommandLauncher, preCheckArtifactState, runRequiredVerificationCommands, toCompletionCheckFact, } from "./required-verification.js";
+import { GATE_QUALIFICATION_CAPABILITY, } from "./types.js";
+// ---------------------------------------------------------------------------
+// Contract constants
+// ---------------------------------------------------------------------------
+export const GATE_QUALIFICATION_SCHEMA_VERSION = 1;
+export const GATE_QUALIFICATION_MAX_COMMANDS = 16;
+export const GATE_QUALIFICATION_MAX_NAME_CHARS = 120;
+export const GATE_QUALIFICATION_MAX_ARGV = 32;
+export const GATE_QUALIFICATION_MAX_ARG_CHARS = 1024;
+export const GATE_QUALIFICATION_MAX_COMMAND_TIMEOUT_SECONDS = 1800;
+/** Closed `/fail` error kinds for an inability to run (never carries output). */
+export const GATE_QUALIFICATION_CONTRACT_ERROR = "GateQualificationContractError";
+export const GATE_QUALIFICATION_CHECKOUT_UNAVAILABLE = "GateQualificationCheckoutUnavailable";
+export const GATE_QUALIFICATION_INTERRUPTED = "GateQualificationInterrupted";
+/** The whole-job timeout / no-outcome kind the job runner reports. */
+export const GATE_QUALIFICATION_FAILED = "GateQualificationFailed";
+/** Bound on the remote symref read. */
+export const GATE_QUALIFICATION_LS_REMOTE_TIMEOUT_MS = 60_000;
+/** Bound on fetching the default branch. */
+export const GATE_QUALIFICATION_FETCH_TIMEOUT_MS = 5 * 60 * 1000;
+/** Bound on materializing the detached checkout (large trees take a while). */
+export const GATE_QUALIFICATION_WORKTREE_ADD_TIMEOUT_MS = 5 * 60 * 1000;
+/** Bound on removing the detached checkout. */
+export const GATE_QUALIFICATION_WORKTREE_REMOVE_TIMEOUT_MS = 2 * 60 * 1000;
+/**
+ * Time held back from the job timeout for checkout teardown and the terminal
+ * report, so the commands' reservation ends before the supervisor's timeout
+ * fires and the job can still report a completed result.
+ */
+export const GATE_QUALIFICATION_DEADLINE_RESERVE_MS = 60_000;
+const HEX64_RE = /^[0-9a-f]{64}$/;
+const FULL_SHA_RE = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
+const SYMREF_HEAD_RE = /^ref: refs\/heads\/(\S+)\tHEAD$/m;
+/** Fixed `/fail` messages, one per inability. */
+const MESSAGES = {
+    contract: "gate_qualification payload failed contract validation",
+    capability: "gate_qualification job does not require the gate qualification capability",
+    repo: "gate_qualification payload names a different repository than the job",
+    defaultBranch: "default branch could not be resolved",
+    fetch: "default branch could not be fetched",
+    revParse: "default branch commit could not be resolved",
+    checkout: "detached checkout could not be created",
+    notClean: "detached checkout is not clean at the resolved commit",
+    interrupted: "gate qualification was interrupted before every command finished",
+};
+// ---------------------------------------------------------------------------
+// Payload validation
+// ---------------------------------------------------------------------------
+function sha256Hex(text) {
+    return createHash("sha256").update(text, "utf8").digest("hex");
+}
+/** Python's `f"{position:02d}"` for a non-negative integer. */
+function pad2(position) {
+    return position < 10 ? `0${position}` : String(position);
+}
+/** Code-point length, matching Python's `len()`. */
+function codePointLength(text) {
+    return [...text].length;
+}
+function isSafePositiveInt(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** The command digest the server computed: sha256 of the canonical declaration. */
+export function gateCommandDigest(command) {
+    return sha256Hex(canonicalJson({ name: command.name, argv: [...command.argv], timeout_seconds: command.timeout_seconds }));
+}
+/** The command identity the server derived from its position and digest. */
+export function gateCommandIdentity(position, digest) {
+    return `cmd-${pad2(position)}-${digest.slice(0, 16)}`;
+}
+function parseCommand(raw, index) {
+    if (!isPlainObject(raw))
+        return null;
+    const { identity, position, name, argv, timeout_seconds: timeoutSeconds, digest } = raw;
+    if (position !== index)
+        return null;
+    if (typeof name !== "string" || name.trim().length === 0)
+        return null;
+    if (codePointLength(name) > GATE_QUALIFICATION_MAX_NAME_CHARS)
+        return null;
+    if (!Array.isArray(argv) || argv.length < 1 || argv.length > GATE_QUALIFICATION_MAX_ARGV)
+        return null;
+    for (const arg of argv) {
+        if (typeof arg !== "string" || arg.trim().length === 0)
+            return null;
+        if (codePointLength(arg) > GATE_QUALIFICATION_MAX_ARG_CHARS)
+            return null;
+        if (arg.includes("\u0000"))
+            return null;
+    }
+    if (typeof timeoutSeconds !== "number" ||
+        !Number.isInteger(timeoutSeconds) ||
+        timeoutSeconds < 1 ||
+        timeoutSeconds > GATE_QUALIFICATION_MAX_COMMAND_TIMEOUT_SECONDS) {
+        return null;
+    }
+    if (typeof digest !== "string" || !HEX64_RE.test(digest))
+        return null;
+    const typedArgv = argv;
+    if (gateCommandDigest({ name, argv: typedArgv, timeout_seconds: timeoutSeconds }) !== digest)
+        return null;
+    if (typeof identity !== "string" || identity !== gateCommandIdentity(index, digest))
+        return null;
+    return { identity, position: index, name, argv: [...typedArgv], timeoutSeconds, digest };
+}
+/**
+ * Validate `job.payload.gate_qualification` against the cross-runtime contract,
+ * SYNCHRONOUSLY and before any git or command effect.
+ *
+ * Also checks the claimed row: it must require the gate qualification
+ * capability when the server reported its requirements (an older shape that
+ * carries none is tolerated, because the server's capability filter already
+ * decided who could claim it), and the payload must name the job's repository.
+ * Fails closed with a fixed message on the first broken rule.
+ */
+export function parseGateQualificationPayload(job) {
+    const refuse = (message) => ({
+        ok: false,
+        failure: { errorKind: GATE_QUALIFICATION_CONTRACT_ERROR, message },
+    });
+    if (Array.isArray(job.required_capabilities) && !job.required_capabilities.includes(GATE_QUALIFICATION_CAPABILITY)) {
+        return refuse(MESSAGES.capability);
+    }
+    const outer = job.payload;
+    if (!isPlainObject(outer))
+        return refuse(MESSAGES.contract);
+    const envelope = outer.gate_qualification;
+    if (!isPlainObject(envelope))
+        return refuse(MESSAGES.contract);
+    if (envelope.schema_version !== GATE_QUALIFICATION_SCHEMA_VERSION)
+        return refuse(MESSAGES.contract);
+    if (!isSafePositiveInt(envelope.revision))
+        return refuse(MESSAGES.contract);
+    if (typeof envelope.repo_name !== "string")
+        return refuse(MESSAGES.contract);
+    if (envelope.repo_name !== job.repo_name)
+        return refuse(MESSAGES.repo);
+    const rawCommands = envelope.commands;
+    if (!Array.isArray(rawCommands) ||
+        rawCommands.length < 1 ||
+        rawCommands.length > GATE_QUALIFICATION_MAX_COMMANDS) {
+        return refuse(MESSAGES.contract);
+    }
+    const commands = [];
+    for (let index = 0; index < rawCommands.length; index += 1) {
+        const command = parseCommand(rawCommands[index], index);
+        if (command === null)
+            return refuse(MESSAGES.contract);
+        commands.push(command);
+    }
+    const digests = envelope.command_digests;
+    if (!Array.isArray(digests) ||
+        digests.length !== commands.length ||
+        digests.some((value, index) => value !== commands[index].digest)) {
+        return refuse(MESSAGES.contract);
+    }
+    // The envelope digest covers the object exactly as received, minus its own
+    // digest key, so any field the server signed is checked byte for byte.
+    const { digest, ...signed } = envelope;
+    if (typeof digest !== "string" || !HEX64_RE.test(digest))
+        return refuse(MESSAGES.contract);
+    if (sha256Hex(canonicalJson(signed)) !== digest)
+        return refuse(MESSAGES.contract);
+    return {
+        ok: true,
+        payload: { repoName: envelope.repo_name, revision: envelope.revision, commands, digest },
+    };
+}
+// ---------------------------------------------------------------------------
+// Default branch and the detached checkout
+// ---------------------------------------------------------------------------
+/** The branch named by `git ls-remote --symref origin HEAD`, or null when none is reported. */
+export function parseSymrefHead(stdout) {
+    const match = SYMREF_HEAD_RE.exec(stdout);
+    return match ? match[1] : null;
+}
+/**
+ * Read full HEAD and the tracked tree/index of the checkout.
+ *
+ * The same two reads as `observeFinalArtifact`, but accepting a SHA-256
+ * object name as well: the contract allows a 64-hex `tested_head_sha`, and the
+ * shared observer's 40-hex rule would report such a checkout as unreadable.
+ */
+async function observeCheckout(runCommand, dir) {
+    let head = null;
+    let trackedStatus = null;
+    try {
+        const r = await runCommand("git", ["rev-parse", "--verify", "HEAD"], {
+            cwd: dir,
+            timeoutMs: ARTIFACT_GIT_TIMEOUT_MS,
+        });
+        const value = r.stdout.trim();
+        if (r.exitCode === 0 && FULL_SHA_RE.test(value))
+            head = value;
+    }
+    catch {
+        head = null;
+    }
+    try {
+        const r = await runCommand("git", ["status", "--porcelain=v1", "--untracked-files=no"], {
+            cwd: dir,
+            timeoutMs: ARTIFACT_GIT_TIMEOUT_MS,
+        });
+        if (r.exitCode === 0)
+            trackedStatus = r.stdout.trim();
+    }
+    catch {
+        trackedStatus = null;
+    }
+    return { head, trackedStatus };
+}
+/** Run git in the owner's repository root, mapping a thrown runner to a failed result. */
+async function git(deps, args, timeoutMs) {
+    try {
+        const r = await deps.runCommand("git", args, { cwd: deps.repoRoot, timeoutMs });
+        return { ok: r.exitCode === 0, stdout: r.stdout };
+    }
+    catch {
+        return { ok: false, stdout: "" };
+    }
+}
+/** Best-effort removal of the detached checkout. Never throws. */
+async function removeCheckout(deps, dir) {
+    await git(deps, ["worktree", "remove", "--force", dir], GATE_QUALIFICATION_WORKTREE_REMOVE_TIMEOUT_MS);
+    try {
+        await deps.removeDir(dir);
+    }
+    catch {
+        // Best effort: a leftover temporary directory costs disk, never correctness.
+    }
+}
+// ---------------------------------------------------------------------------
+// The core
+// ---------------------------------------------------------------------------
+function toResultFact(fact) {
+    // The shared server-bound view, minus `position`: the result envelope keys
+    // each fact by identity only.
+    const bounded = toCompletionCheckFact(fact);
+    return {
+        identity: bounded.identity,
+        outcome: bounded.outcome,
+        reason: bounded.reason,
+        duration_ms: bounded.duration_ms,
+    };
+}
+/** A fact that says the run was cut short by shutdown or lost ownership. */
+function isInterruptionFact(fact) {
+    return (fact.outcome === "cancelled" ||
+        fact.reason === "executor_cancelled" ||
+        fact.reason === "ownership_lost");
+}
+/**
+ * Run one `gate_qualification` job.
+ *
+ * Returns the bounded result envelope, or a fixed-text inability. Never throws
+ * for a git, process, or payload condition, and never returns command output.
+ */
+export async function runGateQualificationJob(job, input, deps) {
+    const startedAt = deps.now();
+    const inability = (errorKind, message) => {
+        deps.errorLog(`[gate_qualification] ${message}`);
+        return { ok: false, failure: { errorKind, message } };
+    };
+    // 1. The contract, before any effect.
+    const parsed = parseGateQualificationPayload(job);
+    if (!parsed.ok)
+        return inability(parsed.failure.errorKind, parsed.failure.message);
+    const payload = parsed.payload;
+    // 2. The default branch as the remote names it NOW, at claim time. A remote
+    // that reports no symref (some hosts omit it) falls back to the executor's
+    // configured base branch; a remote that cannot be read is an inability.
+    const lsRemote = await git(deps, ["ls-remote", "--symref", "origin", "HEAD"], GATE_QUALIFICATION_LS_REMOTE_TIMEOUT_MS);
+    if (!lsRemote.ok)
+        return inability(GATE_QUALIFICATION_CHECKOUT_UNAVAILABLE, MESSAGES.defaultBranch);
+    const branch = parseSymrefHead(lsRemote.stdout) ?? deps.fallbackBaseBranch;
+    if (validateBranchName(branch) !== null) {
+        return inability(GATE_QUALIFICATION_CHECKOUT_UNAVAILABLE, MESSAGES.defaultBranch);
+    }
+    const remoteRef = `refs/remotes/origin/${branch}`;
+    const fetched = await git(deps, ["fetch", "--no-tags", "origin", `+refs/heads/${branch}:${remoteRef}`], GATE_QUALIFICATION_FETCH_TIMEOUT_MS);
+    if (!fetched.ok)
+        return inability(GATE_QUALIFICATION_CHECKOUT_UNAVAILABLE, MESSAGES.fetch);
+    const revParse = await git(deps, ["rev-parse", "--verify", `${remoteRef}^{commit}`], ARTIFACT_GIT_TIMEOUT_MS);
+    const sha = revParse.stdout.trim();
+    if (!revParse.ok || !FULL_SHA_RE.test(sha)) {
+        return inability(GATE_QUALIFICATION_CHECKOUT_UNAVAILABLE, MESSAGES.revParse);
+    }
+    if (input.signal.aborted)
+        return inability(GATE_QUALIFICATION_INTERRUPTED, MESSAGES.interrupted);
+    // 3. A DETACHED checkout in a fresh temporary directory, outside the owner's
+    // working tree. Removed in `finally` whatever happens next.
+    let dir;
+    try {
+        dir = await deps.makeTempDir();
+    }
+    catch {
+        return inability(GATE_QUALIFICATION_CHECKOUT_UNAVAILABLE, MESSAGES.checkout);
+    }
+    try {
+        const added = await git(deps, ["worktree", "add", "--detach", dir, sha], GATE_QUALIFICATION_WORKTREE_ADD_TIMEOUT_MS);
+        if (!added.ok)
+            return inability(GATE_QUALIFICATION_CHECKOUT_UNAVAILABLE, MESSAGES.checkout);
+        const before = await observeCheckout(deps.runCommand, dir);
+        const preState = preCheckArtifactState(before, sha);
+        if (preState !== null)
+            return inability(GATE_QUALIFICATION_CHECKOUT_UNAVAILABLE, MESSAGES.notClean);
+        // 4. Only the payload commands, in payload order. The reservation ends a
+        // little before the job timeout so a slow last command still leaves time to
+        // tear the checkout down and report a completed result.
+        const timeoutMs = input.timeoutSeconds * 1000;
+        const deadlineAtMs = startedAt + Math.max(0, timeoutMs - GATE_QUALIFICATION_DEADLINE_RESERVE_MS);
+        const ownershipHeld = deps.ownershipHeld ?? (() => true);
+        // Ownership is re-checked WHILE a command runs, not only between commands,
+        // exactly as the covered lane does: a lost claim terminates the running
+        // command. The supervisor's own abort (timeout, stop) is chained in too.
+        const commandAbort = new AbortController();
+        const onOuterAbort = () => commandAbort.abort();
+        if (input.signal.aborted)
+            commandAbort.abort();
+        else
+            input.signal.addEventListener("abort", onOuterAbort, { once: true });
+        let watchTimer;
+        const watchOwnership = () => {
+            watchTimer = deps.setTimer(() => {
+                watchTimer = undefined;
+                if (!ownershipHeld())
+                    commandAbort.abort();
+                else
+                    watchOwnership();
+            }, OWNERSHIP_POLL_MS);
+        };
+        watchOwnership();
+        const commands = payload.commands.map((command) => ({
+            identity: command.identity,
+            position: command.position,
+            name: command.name,
+            argv: command.argv,
+            timeoutSeconds: command.timeoutSeconds,
+        }));
+        let facts;
+        try {
+            const run = await runRequiredVerificationCommands({
+                commands,
+                worktreePath: dir,
+                env: deps.commandEnv,
+                launch: deps.launch,
+                now: deps.now,
+                deadlineAtMs,
+                signal: commandAbort.signal,
+                ownershipHeld,
+                onInterruption: "stop",
+            });
+            facts = run.facts;
+        }
+        finally {
+            if (watchTimer !== undefined)
+                deps.clearTimer(watchTimer);
+            input.signal.removeEventListener("abort", onOuterAbort);
+        }
+        // Names and closed tokens only: no argv, no output, no path.
+        for (const fact of facts) {
+            deps.log(`[gate_qualification] command ${fact.position} (${fact.name.slice(0, 60)}): ${fact.outcome}${fact.reason ? ` (${fact.reason})` : ""}`);
+            if (deps.showLocalOutput && fact.outcome !== "exited_zero" && fact.output.trim().length > 0) {
+                deps.errorLog(`[gate_qualification] output tail for ${fact.name.slice(0, 60)}:\n${fact.output}`);
+            }
+        }
+        // 5. An interruption proved nothing about the gate: an inability, never a
+        // completed "failed" that the server would record as unqualified.
+        if (facts.some(isInterruptionFact)) {
+            return inability(GATE_QUALIFICATION_INTERRUPTED, MESSAGES.interrupted);
+        }
+        const resultFacts = facts.map(toResultFact);
+        const outcome = resultFacts.every((fact) => fact.outcome === "exited_zero") ? "passed" : "failed";
+        return {
+            ok: true,
+            result: {
+                schema_version: 1,
+                revision: payload.revision,
+                tested_head_sha: sha,
+                outcome,
+                commands: resultFacts,
+            },
+        };
+    }
+    finally {
+        await removeCheckout(deps, dir);
+    }
+}
+// ---------------------------------------------------------------------------
+// Production wiring
+// ---------------------------------------------------------------------------
+/**
+ * The explicit command environment: the executor's worker base environment
+ * (allowlisted keys, parent credentials stripped, sentinel database values,
+ * `BRIDGE_SKIP_PREPUSH=1`) plus `CI=1`, so test tooling runs non-interactively.
+ */
+export function buildGateQualificationEnv(parentEnv) {
+    return { ...buildExecutorBaseWorkerEnv(parentEnv), CI: "1" };
+}
+/**
+ * Production dependencies built from the executor's own boundary.
+ *
+ * Git runs in `deps.cwd` — the owner's repository checkout every other
+ * executor job works from. Commands launch through the shared supervised
+ * launcher and register with the executor's live-process registry, so executor
+ * shutdown reaches them exactly as it reaches a worker.
+ */
+export function createProductionGateQualificationDeps(input) {
+    const { deps, options } = input;
+    const makeTempDir = async () => {
+        const root = deps.tmpdir ? deps.tmpdir() : os.tmpdir();
+        const prefix = path.join(root, "bridge-gate-qualification-");
+        return deps.mkdtemp ? deps.mkdtemp(prefix) : mkdtemp(prefix);
+    };
+    const removeDir = async (dirPath) => {
+        if (deps.rmRecursive)
+            await deps.rmRecursive(dirPath);
+        else
+            await rm(dirPath, { recursive: true, force: true });
+    };
+    return {
+        runCommand: deps.runCommand,
+        launch: createSupervisedCommandLauncher({
+            deps,
+            ...(input.registerLive ? { registerLive: input.registerLive } : {}),
+        }),
+        commandEnv: buildGateQualificationEnv(deps.env),
+        repoRoot: deps.cwd,
+        fallbackBaseBranch: options.baseBranch,
+        makeTempDir,
+        removeDir,
+        now: deps.now,
+        setTimer: deps.setTimer,
+        clearTimer: deps.clearTimer,
+        log: deps.log,
+        errorLog: deps.errorLog,
+        // A job-type filter is set only by the short-lived owner-terminal
+        // qualifier; a durable service executor never sets one. That executor's
+        // stderr is the owner's own terminal, so it alone may show output tails.
+        showLocalOutput: options.jobTypes !== undefined && options.jobTypes.length > 0,
+        ownershipHeld: input.ownershipHeld,
+    };
+}

package/build/executor/guarded-fast-forward-push.js

@@ -0,0 +1,129 @@
+export const PUSH_TIMEOUT_MS = 180_000;
+export 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;
+const SHA = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/i;
+export function isSafePublicationBranch(branch) {
+    return branch.length > 0 && !branch.startsWith("-") && !branch.startsWith("/") &&
+        !branch.endsWith("/") && !branch.endsWith(".") && branch !== "@" &&
+        !/[\x00-\x20\x7f~^:?*\[\\+]/.test(branch) && !branch.includes("..") &&
+        !branch.includes("@{") && !branch.includes("//") &&
+        branch.split("/").every(part => !part.startsWith(".") && !part.endsWith(".lock"));
+}
+/** No command text, remote URL, or environment escapes this closed outcome. */
+export async function guardedFastForwardPush(input) {
+    const refuse = (reason) => ({ status: "refused", reason });
+    if (!isSafePublicationBranch(input.branch) || !SHA.test(input.expectedOriginSha) ||
+        input.trustedExcludedShas?.some(sha => !SHA.test(sha)) ||
+        (input.candidateSha !== undefined && (!SHA.test(input.candidateSha) || input.candidateSha === input.expectedOriginSha)))
+        return refuse("invalid_input");
+    let timedOut = false;
+    const git = async (args) => {
+        const timeoutMs = Math.min(PUSH_TIMEOUT_MS, input.remainingMs());
+        if (timeoutMs <= 0 || (!input.mayMutate() || input.signal?.aborted)) {
+            timedOut = true;
+            return { exitCode: 124, stdout: "", stderr: "" };
+        }
+        return input.runCommand("git", args, { cwd: input.worktreePath, timeoutMs, signal: input.signal,
+            env: { ...input.env, GIT_TERMINAL_PROMPT: "0" } });
+    };
+    try {
+        if ((await git(["check-ref-format", "--branch", input.branch])).exitCode !== 0)
+            return refuse("invalid_input");
+        const branch = await git(["symbolic-ref", "--quiet", "--short", "HEAD"]);
+        if (branch.exitCode !== 0 || branch.stdout.trim() !== input.branch)
+            return refuse("branch_mismatch");
+        const head = await git(["rev-parse", "HEAD"]);
+        const candidate = head.stdout.trim().toLowerCase();
+        if (head.exitCode !== 0 || !SHA.test(candidate))
+            return refuse("ancestry_unknown");
+        if (candidate === input.expectedOriginSha.toLowerCase() ||
+            (input.candidateSha !== undefined && candidate !== input.candidateSha.toLowerCase()))
+            return refuse("invalid_input");
+        const ancestor = await git(["merge-base", "--is-ancestor", input.expectedOriginSha, "HEAD"]);
+        if (ancestor.exitCode === 1)
+            return refuse("not_fast_forward");
+        if (ancestor.exitCode !== 0)
+            return refuse("ancestry_unknown");
+        for (const sha of input.trustedExcludedShas ?? []) {
+            if ((await git(["cat-file", "-e", `${sha}^{commit}`])).exitCode !== 0 ||
+                (await git(["merge-base", "--is-ancestor", sha, "HEAD"])).exitCode !== 0)
+                return refuse("range_unreadable");
+        }
+        const range = await git(["rev-list", "HEAD", `^${input.expectedOriginSha}`, ...(input.trustedExcludedShas ?? []).map(sha => `^${sha}`)]);
+        const commits = range.stdout.trim().split(/\s+/);
+        if (range.exitCode !== 0 || commits.length === 0 || commits.some(sha => !SHA.test(sha)))
+            return refuse("range_unreadable");
+        const workflow = (paths) => paths.split("\0").some(path => path.startsWith(".github/workflows/"));
+        for (const commit of commits) {
+            const parentsResult = await git(["rev-list", "--parents", "-n", "1", commit]);
+            const ids = parentsResult.stdout.trim().split(/\s+/);
+            if (parentsResult.exitCode !== 0 || ids[0] !== commit || ids.some(sha => !SHA.test(sha)))
+                return refuse("range_unreadable");
+            const parents = ids.slice(1);
+            let paths;
+            if (parents.length > 1) {
+                if (parents.length !== 2)
+                    return refuse("range_unreadable");
+                // Compare the candidate resolution to Git's automatic merge, rather than
+                // attributing already-published excluded parent changes to the worker.
+                const merge = await git(["merge-tree", "--write-tree", "-z", "--name-only", "--messages", parents[0], parents[1]]);
+                const tokens = merge.stdout.split("\0");
+                const tree = tokens[0]?.trim() ?? "";
+                if (![0, 1].includes(merge.exitCode) || !SHA.test(tree) || !merge.stdout.endsWith("\0"))
+                    return refuse("range_unreadable");
+                const endPaths = tokens.indexOf("", 1);
+                if (endPaths < 0)
+                    return refuse("range_unreadable");
+                const conflicts = tokens.slice(1, endPaths);
+                if (merge.exitCode === 1 && conflicts.length === 0)
+                    return refuse("range_unreadable");
+                if (conflicts.some(path => path.startsWith(".github/workflows/")))
+                    return refuse("workflow_files_in_range");
+                for (let at = endPaths + 1; at < tokens.length - 1;) {
+                    if (tokens[at] === "")
+                        break;
+                    const count = Number(tokens[at]);
+                    if (!Number.isInteger(count) || count < 1 || at + count + 2 >= tokens.length - 1)
+                        return refuse("range_unreadable");
+                    at += count + 3;
+                }
+                paths = await git(["diff-tree", "-r", "--no-commit-id", "--name-only", "--no-renames", "-z", tree, commit]);
+            }
+            else {
+                paths = await git(["diff-tree", "--root", "-r", "--no-commit-id", "--name-only", "--no-renames", "-z", commit]);
+            }
+            if (paths.exitCode !== 0)
+                return refuse("range_unreadable");
+            if (workflow(paths.stdout))
+                return refuse("workflow_files_in_range");
+        }
+        // Re-check HEAD and ownership immediately before mutation.
+        const latest = await git(["rev-parse", "HEAD"]);
+        if (latest.exitCode !== 0 || latest.stdout.trim().toLowerCase() !== candidate)
+            return refuse("ancestry_unknown");
+        if ((!input.mayMutate() || input.signal?.aborted) || input.remainingMs() <= 0)
+            return refuse("timeout");
+        const destination = `refs/heads/${input.branch}`;
+        const push = await git(["push", "--no-verify", "--porcelain",
+            `--force-with-lease=${destination}:${input.expectedOriginSha}`, "origin", `HEAD:${destination}`]);
+        const text = `${push.stdout}\n${push.stderr}`;
+        if (timedOut || push.exitCode === 124 || /timed out|timeout/i.test(text))
+            return refuse("timeout");
+        if (PUSH_AUTH_FAILURE_RE.test(text))
+            return refuse("auth_failed");
+        if (PUSH_LEASE_FAILURE_RE.test(text))
+            return refuse("lease_rejected");
+        if (push.exitCode !== 0)
+            return refuse("remote_rejected");
+        const update = push.stdout.split("\n").some(line => {
+            const parts = line.split("\t");
+            return parts[0] === " " && parts[1] === `HEAD:${destination}`;
+        });
+        if (!update)
+            return refuse("lease_rejected");
+        return { status: "published", from_sha: input.expectedOriginSha.toLowerCase(), to_sha: candidate };
+    }
+    catch {
+        return refuse(timedOut || input.remainingMs() <= 0 ? "timeout" : "remote_rejected");
+    }
+}

package/build/executor/heartbeat.js

@@ -22,7 +22,7 @@
  *    interval. This is TELEMETRY ONLY (R14): the marker is never persisted, never
  *    reported as `last_commit_sha`, and never drives an executor decision — the
  *    reconciler remains the sole consumer and the sole transition authority
- *    (`docs/claude/epic-implementer-standing-rules.md`).
+ *    (`docs/epic-implementer/standing-rules.md`).
  *
  *  - SERVER STOP (WS-B executor half). A heartbeat response carrying the
  *    server's stop request kills the owned worker like `stale_claim` does, but

package/build/executor/http-client.js

@@ -76,6 +76,22 @@ export function normalizeRequiredCapabilities(value) {
         return [];
     return value.every((entry) => typeof entry === "string") ? [...value] : [];
 }
+const FULL_SHA_PATTERN = /^[0-9a-fA-F]{40}$/;
+/**
+ * BAPI-1367 — normalize a claim response's `prior_attempt_head_sha`. Absent or
+ * explicit null reads as null silently (an older server, or no prior head). A
+ * present value that is not a 40-hex string also reads as null, and `onMalformed`
+ * is told once so the caller can warn. The raw value is never passed on, so it
+ * can never reach a log line.
+ */
+export function normalizePriorAttemptHeadSha(value, onMalformed) {
+    if (value === undefined || value === null)
+        return null;
+    if (typeof value === "string" && FULL_SHA_PATTERN.test(value))
+        return value;
+    onMalformed();
+    return null;
+}
 /** Bound a server-provided diagnostic snippet included in error strings. */
 function boundedDetail(text) {
     const trimmed = (text ?? "").trim();
@@ -271,6 +287,10 @@ export function createExecutorHttpClient(config) {
                     if ("required_capabilities" in job) {
                         job.required_capabilities = normalizeRequiredCapabilities(job.required_capabilities);
                     }
+                    // BAPI-1367: a malformed prior head fails closed to null with one
+                    // bounded warning naming only the job, never the raw value or a SHA.
+                    job.prior_attempt_head_sha = normalizePriorAttemptHeadSha(job.prior_attempt_head_sha, () => (config.warn ?? ((message) => console.error(message)))(`executor: ignoring malformed prior attempt head in the claim for job ${String(job.id)}; ` +
+                        `treating it as a first dispatch.`));
                     return { kind: "claimed", job, reconcilerLiveness };
                 }
                 catch {