@bridge_gpt/mcp-server 0.2.67 → 0.2.68

package/build/epic-workarounds-path.js

@@ -0,0 +1,39 @@
+/**
+ * The one TypeScript spelling of the Epic Implementer workaround folder (BAPI-1399).
+ *
+ * A worker that defers a MINOR requirement behind a guarded workaround commits a
+ * record at `.bridge/epic-workarounds/<TICKET>.md` on its ticket branch. While
+ * that folder exists on the epic head, the integration pull request stays in
+ * draft: the reconciler's coordinator withholds `mark_ready`
+ * (`api/library/epic_implementer/integration_completion.py`), and the local actor
+ * re-checks the folder before it takes a pull request out of draft
+ * (`executor/integration-job.ts`). Nothing about a workaround is stored in the
+ * database or in run state; the hold is worked out from the folder at the exact
+ * epic head every time.
+ *
+ * Python declares the same value once, beside its directory-listing helper in
+ * `api/library/github/github_webhooks_lib.py`. The static test
+ * `tests/pytest/static/test_epic_workarounds_path_pin.py` fails if any consumer
+ * spells the path differently or drops it.
+ */
+import { TICKET_KEY_PATTERN } from "./ticket-key-utils.js";
+/** The workaround folder, repository-relative, with its trailing slash. */
+export const EPIC_WORKAROUNDS_DIR = ".bridge/epic-workarounds/";
+/** The folder without its trailing slash: the form a contents API path takes. */
+export const EPIC_WORKAROUNDS_DIR_PATH = EPIC_WORKAROUNDS_DIR.slice(0, -1);
+/** A ticket key: the canonical grammar the Epic Implementer accepts everywhere else. */
+const TICKET_KEY_RE = TICKET_KEY_PATTERN;
+/** Upper bound on a ticket key, so a pasted blob is never a path segment. */
+const MAX_TICKET_KEY_CHARS = 64;
+/**
+ * The record path for one ticket, `.bridge/epic-workarounds/<TICKET>.md`, or
+ * `null` when the key is not a valid ticket key. A key is never sanitized into a
+ * path: anything that is not exactly a key is refused.
+ */
+export function epicWorkaroundRecordPath(ticketKey) {
+    if (typeof ticketKey !== "string")
+        return null;
+    if (ticketKey.length > MAX_TICKET_KEY_CHARS || !TICKET_KEY_RE.test(ticketKey))
+        return null;
+    return `${EPIC_WORKAROUNDS_DIR}${ticketKey}.md`;
+}

package/build/executor/cli.js

@@ -22,6 +22,35 @@ import { startExecutorSleepAssertion } from "./platform.js";
 import { runExecutor } from "./runner.js";
 import { runExecutorWatchCli } from "./watch-cli.js";
 import { removeRunExecutorRecordIfOwned } from "../executor-launch.js";
+/** Register an optional parent watch without making the timer a process owner. */
+export function registerExecutorParentWatch(pid, onGone, seams = {
+    setInterval: (callback, ms) => setInterval(callback, ms),
+    clearInterval: (handle) => clearInterval(handle),
+    signalZero: (parentPid) => process.kill(parentPid, 0),
+}) {
+    let disposed = false;
+    let notified = false;
+    const timer = seams.setInterval(() => {
+        if (disposed || notified)
+            return;
+        try {
+            seams.signalZero(pid);
+        }
+        catch (error) {
+            if (error.code === "ESRCH") {
+                notified = true;
+                onGone();
+            }
+        }
+    }, 5_000);
+    timer.unref?.();
+    return () => {
+        if (disposed)
+            return;
+        disposed = true;
+        seams.clearInterval(timer);
+    };
+}
 /** Fixed executor timing/behavior defaults. */
 const DEFAULT_POLL_INTERVAL_MS = 15_000;
 const DEFAULT_HEARTBEAT_INTERVAL_MS = 60_000;
@@ -422,6 +451,7 @@ export async function runExecutorCli(argv, overrides = {}) {
     const createIntegrationClient = overrides.createIntegrationClient ?? createIntegrationActionHttpClient;
     const runnerSeams = {
         onSignal: overrides.onSignal ?? defaultSignalRegistrar,
+        watchParent: registerExecutorParentWatch,
         // BAPI-1279 — on a terminal exit, delete the launcher record drive-epic
         // wrote for this run, but only if it still names THIS instance (its id, and
         // this process or the relay that started it). Advisory: a failure here

package/build/executor/completion-contract.js

@@ -231,6 +231,10 @@ export const COMPLETION_CAUSE_VALUES = [
     "cleanup_unconfirmed",
     "verification_runner_unavailable",
 ];
+export const END_CAUSE_VALUES = [
+    "worker_exit", "completion_window", "job_timeout", "executor_abort",
+    "executor_shutdown", "server_stop", "lease_lost",
+];
 export const MAX_TASKS = 64;
 export const MAX_DENIALS = 32;
 export const MAX_IDENTIFIER_CHARS = 128;
@@ -359,16 +363,25 @@ export function deriveCompletionCause(envelope) {
     if (blocking.length > 0 && envelope.evidence === "sufficient" && blocking.some((d) => d.result_after_denial)) {
         return "permission_stop";
     }
-    if (envelope.cleanup.verdict !== "confirmed" || envelope.cleanup.survivors !== 0)
-        return "cleanup_unconfirmed";
     const unresolved = envelope.tasks.some((t) => t.required && !TASK_RESOLVING_STATES.has(t.state));
-    if (blocking.length > 0 ||
+    const requiredWorkIncomplete = blocking.length > 0 ||
         envelope.evidence !== "sufficient" ||
         envelope.execution !== "complete" ||
         unresolved ||
-        envelope.verification === "incomplete") {
-        return "required_work_incomplete";
+        envelope.verification === "incomplete";
+    // One exception to cleanup precedence: a completed sweep with no survivor and
+    // exactly the single reason `ownership_unverifiable` yields to unfinished
+    // work. Exact array checks, so a mixed list (e.g. with `not_run`) never does.
+    const narrowCleanupUncertainty = envelope.cleanup.verdict === "unconfirmed" &&
+        envelope.cleanup.survivors === 0 &&
+        envelope.cleanup.reasons.length === 1 &&
+        envelope.cleanup.reasons[0] === "ownership_unverifiable";
+    if ((envelope.cleanup.verdict !== "confirmed" || envelope.cleanup.survivors !== 0) &&
+        !(narrowCleanupUncertainty && requiredWorkIncomplete)) {
+        return "cleanup_unconfirmed";
     }
+    if (requiredWorkIncomplete)
+        return "required_work_incomplete";
     if (envelope.verification === "unavailable")
         return "verification_runner_unavailable";
     if (envelope.verification === "failed")

package/build/executor/deps.js

@@ -1,3 +1,4 @@
+import { recordProvisionedAssets } from "../generated-assets-inventory.js";
 /**
  * Default (production) executor dependencies (BAPI-534, TDD §7).
  *
@@ -70,6 +71,7 @@ export function createDefaultExecutorDeps() {
                     cwd: options?.cwd,
                     env: options?.env,
                     timeout: options?.timeoutMs,
+                    signal: options?.signal,
                     maxBuffer: MAX_COMMAND_BUFFER,
                     encoding: "utf8",
                     shell: false,
@@ -78,7 +80,7 @@ export function createDefaultExecutorDeps() {
             }
             catch (err) {
                 const e = err;
-                const exitCode = typeof e.code === "number" ? e.code : 1;
+                const exitCode = e.killed || e.code === "ABORT_ERR" ? 124 : typeof e.code === "number" ? e.code : 1;
                 return { stdout: e.stdout ?? "", stderr: e.stderr ?? "", exitCode };
             }
         },
@@ -137,6 +139,7 @@ export function createDefaultExecutorDeps() {
                 },
             };
         },
+        recordPackagedAssets: recordProvisionedAssets,
         readFile: (filePath) => readFile(filePath, "utf-8"),
         writeFile: (filePath, data) => writeFile(filePath, data, "utf-8"),
         appendFile: (filePath, data) => appendFile(filePath, data, "utf-8"),

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,
+    };
+}