@bridge_gpt/mcp-server 0.2.60 → 0.2.65

package/build/executor/completion-supervision.js

@@ -0,0 +1,286 @@
+import { sha256Hex } from "./completion-contract.js";
+import { canonicalJson } from "./required-verification.js";
+/** Reserved for the owned-process sweep after the worker exits. */
+export const CLEANUP_RESERVE_MS = 20_000;
+/** Reserved for `validateWorkerFinalization` (git + gh reads). */
+export const FINALIZATION_RESERVE_MS = 60_000;
+/** Reserved for preparing and delivering the terminal report, with retries. */
+export const REPORT_RESERVE_MS = 30_000;
+/** Reserved for cleanup after declared checks, when any are declared. */
+export const CHECK_CLEANUP_RESERVE_MS = 10_000;
+/**
+ * Between closing stdin at the hold deadline and the process timer's SIGTERM.
+ * The measured CLI stops its own tasks within ~0.4 s of stdin EOF; the rest is
+ * margin for EOF draining.
+ */
+export const STDIN_CLOSE_GRACE_MS = 10_000;
+/** A worker window shorter than this cannot do useful work: refuse instead. */
+export const MIN_WORKER_WINDOW_MS = 60_000;
+/** Bound on the post-exit wait for stdout/stderr EOF. */
+export const EOF_DRAIN_BOUND_MS = 5_000;
+/**
+ * Plan the covered attempt's phases from its remaining authorized allowance.
+ *
+ * `remainingMs` is what is left of the job's own timeout at this moment (the
+ * caller has already spent some of it preparing the worktree), minus any
+ * allowance the ORIGINATING attempt already spent when this job is a
+ * continuation. The plan never returns a window larger than that.
+ */
+export function planCompletionAllowance(input) {
+    const verificationMs = input.declaredCheckTimeoutsMs.reduce((sum, ms) => sum + Math.max(0, ms), 0);
+    const reservations = {
+        cleanupMs: CLEANUP_RESERVE_MS,
+        verificationMs,
+        checkCleanupMs: verificationMs > 0 ? CHECK_CLEANUP_RESERVE_MS : 0,
+        finalizationMs: FINALIZATION_RESERVE_MS,
+        reportMs: REPORT_RESERVE_MS,
+    };
+    const reserved = reservations.cleanupMs +
+        reservations.verificationMs +
+        reservations.checkCleanupMs +
+        reservations.finalizationMs +
+        reservations.reportMs;
+    const available = Math.max(0, input.remainingMs - Math.max(0, input.spentAllowanceMs ?? 0));
+    const workerWindowMs = available - reserved;
+    if (workerWindowMs < MIN_WORKER_WINDOW_MS)
+        return { ok: false, reason: "allowance_exhausted" };
+    const deadlineAtMs = input.nowMs + available;
+    const workerDeadlineAtMs = input.nowMs + workerWindowMs;
+    return {
+        ok: true,
+        deadlineAtMs,
+        workerDeadlineAtMs,
+        holdDeadlineAtMs: workerDeadlineAtMs - STDIN_CLOSE_GRACE_MS,
+        workerWindowMs,
+        reservations,
+    };
+}
+/** The payload key the server stamps the declaration under. */
+export const REQUIRED_VERIFICATION_PAYLOAD_KEY = "required_verification";
+export const REQUIRED_VERIFICATION_SCHEMA_VERSION = 1;
+/** Bounds, identical to the server's `ReconcileVerificationCommand` / overlap contract. */
+export const DECLARATION_MAX_COMMANDS = 16;
+export const DECLARATION_MAX_NAME_CHARS = 120;
+export const DECLARATION_MAX_ARGV = 32;
+export const DECLARATION_MAX_ARG_CHARS = 1024;
+export const DECLARATION_MIN_TIMEOUT_SECONDS = 1;
+export const DECLARATION_MAX_TIMEOUT_SECONDS = 30 * 60;
+const DIGEST_RE = /^[0-9a-f]{64}$/;
+const COMMAND_KEYS = ["argv", "identity", "name", "position", "timeout_seconds"];
+const DECLARATION_KEYS = new Set([
+    "schema_version",
+    "provenance",
+    "plan_version",
+    "plan_hash",
+    "commands",
+    "digest",
+    "refusal_reason",
+]);
+/** `cmd-<position>-<16 hex>` over the canonical typed value — the server's `command_identity`. */
+export function declaredCommandIdentity(position, value) {
+    const typed = { name: value.name, argv: [...value.argv], timeout_seconds: value.timeout_seconds };
+    return `cmd-${String(position).padStart(2, "0")}-${sha256Hex(canonicalJson(typed)).slice(0, 16)}`;
+}
+/** SHA-256 over every declaration field except `digest` — the server's `declaration_digest`. */
+export function computeDeclarationDigest(declaration) {
+    const body = {};
+    for (const [k, v] of Object.entries(declaration))
+        if (k !== "digest")
+            body[k] = v;
+    return sha256Hex(canonicalJson(body));
+}
+function isInt(value) {
+    return typeof value === "number" && Number.isInteger(value);
+}
+function validCommand(raw, index) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return "malformed_command";
+    const e = raw;
+    const keys = Object.keys(e).sort();
+    if (keys.length !== COMMAND_KEYS.length || keys.some((k, i) => k !== COMMAND_KEYS[i]))
+        return "malformed_command";
+    const { identity, position, name, argv, timeout_seconds: timeout } = e;
+    if (typeof name !== "string" || name.trim().length === 0 || name.length > DECLARATION_MAX_NAME_CHARS) {
+        return "malformed_command";
+    }
+    if (!Array.isArray(argv) || argv.length === 0 || argv.length > DECLARATION_MAX_ARGV)
+        return "malformed_command";
+    for (const arg of argv) {
+        if (typeof arg !== "string" || arg.trim().length === 0 || arg.length > DECLARATION_MAX_ARG_CHARS || arg.includes("\0")) {
+            return "malformed_command";
+        }
+    }
+    if (!isInt(timeout) || timeout < DECLARATION_MIN_TIMEOUT_SECONDS || timeout > DECLARATION_MAX_TIMEOUT_SECONDS) {
+        return "malformed_command";
+    }
+    if (!isInt(position) || position !== index)
+        return "position_mismatch";
+    if (typeof identity !== "string" || identity !== declaredCommandIdentity(index, { name, argv: argv, timeout_seconds: timeout })) {
+        return "identity_mismatch";
+    }
+    return { identity, position, name, argv: [...argv], timeoutSeconds: timeout };
+}
+/**
+ * Read and validate a claimed job's `required_verification` declaration,
+ * all-or-nothing. See {@link RequiredVerificationRead}.
+ */
+export function readRequiredVerification(payload) {
+    if (!payload || !Object.prototype.hasOwnProperty.call(payload, REQUIRED_VERIFICATION_PAYLOAD_KEY)) {
+        return { kind: "none" };
+    }
+    const raw = payload[REQUIRED_VERIFICATION_PAYLOAD_KEY];
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        return { kind: "refused", reason: "not_an_object", provenance: null, digest: null };
+    }
+    const d = raw;
+    const digest = typeof d.digest === "string" && DIGEST_RE.test(d.digest) ? d.digest : null;
+    const provenance = d.provenance === "declared" || d.provenance === "declared_empty" || d.provenance === "absent" || d.provenance === "refused"
+        ? d.provenance
+        : null;
+    const refuse = (reason) => ({
+        kind: "refused",
+        reason,
+        provenance,
+        digest,
+    });
+    if (d.schema_version !== REQUIRED_VERIFICATION_SCHEMA_VERSION)
+        return refuse("unsupported_schema_version");
+    if (Object.keys(d).some((k) => !DECLARATION_KEYS.has(k)))
+        return refuse("unsupported_schema_version");
+    if (provenance === null)
+        return refuse("unknown_provenance");
+    if (digest === null)
+        return refuse("malformed_digest");
+    if (provenance === "refused")
+        return refuse("server_refused");
+    if (Object.prototype.hasOwnProperty.call(d, "refusal_reason"))
+        return refuse("unknown_provenance");
+    const planVersion = d.plan_version;
+    const planHash = d.plan_hash;
+    if (!(planVersion === null || (isInt(planVersion) && planVersion >= 0)))
+        return refuse("malformed_plan_identity");
+    if (!(planHash === null || (typeof planHash === "string" && planHash.length > 0))) {
+        return refuse("malformed_plan_identity");
+    }
+    if (!Array.isArray(d.commands) || d.commands.length > DECLARATION_MAX_COMMANDS)
+        return refuse("cardinality_mismatch");
+    const commands = d.commands;
+    if ((provenance === "declared") !== commands.length > 0)
+        return refuse("cardinality_mismatch");
+    const checks = [];
+    const seen = new Set();
+    for (let i = 0; i < commands.length; i++) {
+        const parsed = validCommand(commands[i], i);
+        if (typeof parsed === "string")
+            return refuse(parsed);
+        if (seen.has(parsed.identity))
+            return refuse("duplicate_identity");
+        seen.add(parsed.identity);
+        checks.push(parsed);
+    }
+    if (computeDeclarationDigest(d) !== digest)
+        return refuse("digest_mismatch");
+    return {
+        kind: "ok",
+        declaration: {
+            provenance,
+            digest,
+            planVersion: planVersion,
+            planHash: planHash,
+            checks,
+        },
+    };
+}
+/**
+ * The declared checks of a VALIDATED declaration, or `[]`. Never a partial
+ * list: a declaration that fails validation has no runnable checks at all, and
+ * the covered lane refuses it before launch (see {@link readRequiredVerification}).
+ */
+export function readDeclaredChecks(payload) {
+    const read = readRequiredVerification(payload);
+    return read.kind === "ok" ? read.declaration.checks : [];
+}
+export function finalizationObligations(branch, baseBranch) {
+    return {
+        push: { remote: "origin", ref: `refs/heads/${branch}` },
+        prCreate: { head: branch, base: baseBranch },
+    };
+}
+/**
+ * Map a finalization outcome onto the contract verdict plus which of the two
+ * obligations were independently satisfied. The mapping reads the executor's
+ * own finalization error kinds; it never trusts worker text.
+ */
+export function finalizationFacts(outcome) {
+    if (outcome === null)
+        return { verdict: "unknown", pushSatisfied: false, prSatisfied: false };
+    if (outcome.ok)
+        return { verdict: "ok", pushSatisfied: true, prSatisfied: true };
+    switch (outcome.errorKind) {
+        case "WorkerFinalizationPrNotAttached":
+        case "WorkerFinalizationPrBaseMismatch":
+            return { verdict: "unmet", pushSatisfied: true, prSatisfied: false };
+        case "WorkerFinalizationMissingRemoteBranchAndPr":
+        case "WorkerFinalizationSavedButUnfinalized":
+            return { verdict: "unmet", pushSatisfied: false, prSatisfied: false };
+        default:
+            return { verdict: "unknown", pushSatisfied: false, prSatisfied: false };
+    }
+}
+/**
+ * Read the server-stamped completion binding for a claimed job.
+ *
+ * The job id, run, child and attempt come from the CLAIM (the server minted
+ * them); the park generation and originating job come from the payload's
+ * `completion_binding`, which only the reconciler writes. Nothing here is taken
+ * from worker output.
+ */
+export function readCompletionBinding(job, dispatchHeadSha) {
+    const raw = job.payload?.["completion_binding"];
+    const b = raw && typeof raw === "object" ? raw : {};
+    const intOrNull = (v) => typeof v === "number" && Number.isInteger(v) && v >= 0 ? v : null;
+    const spentSeconds = intOrNull(b["spent_allowance_seconds"]) ?? 0;
+    return {
+        binding: {
+            job_id: job.id,
+            epic_run_id: job.epic_run_id ?? null,
+            ticket_key: job.ticket_key ?? null,
+            attempt: job.attempt_count,
+            park_generation: intOrNull(b["park_generation"]),
+            originating_job_id: intOrNull(b["originating_job_id"]),
+            dispatch_head_sha: dispatchHeadSha,
+            final_head_sha: null,
+        },
+        spentAllowanceMs: spentSeconds * 1000,
+    };
+}
+/**
+ * Read the server-owned optional-watcher declaration. Only an exact kind +
+ * input digest match makes a watcher optional; worker prose or a label the
+ * worker assigns can never do it.
+ */
+export function readOptionalWatchers(payload) {
+    const policy = payload?.["completion_policy"];
+    const raw = policy && typeof policy === "object" ? policy["optional_watchers"] : undefined;
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const entry of raw.slice(0, 16)) {
+        if (!entry || typeof entry !== "object")
+            continue;
+        const e = entry;
+        if ((e["kind"] === "monitor" || e["kind"] === "bash_bg") && typeof e["input_digest"] === "string" && /^[0-9a-f]{64}$/.test(e["input_digest"])) {
+            out.push({ kind: e["kind"], input_digest: e["input_digest"] });
+        }
+    }
+    return out;
+}
+/** Terminal `error_kind` for each completion cause. Executor-owned vocabulary. */
+export const COMPLETION_CAUSE_ERROR_KINDS = {
+    required_work_incomplete: "ContractError.RequiredWorkIncomplete",
+    required_check_failed: "ContractError.RequiredCheckFailed",
+    permission_stop: "ContractError.PermissionStop",
+    unsupported_completion_evidence: "ContractError.CompletionEvidenceUnsupported",
+    cleanup_unconfirmed: "ContractError.CleanupUnconfirmed",
+    verification_runner_unavailable: "ContractError.VerificationRunnerUnavailable",
+};

package/build/executor/credentials.js

@@ -17,7 +17,7 @@
  * never resolves or stores it, and `ANTHROPIC_API_KEY` remains absolutely denied
  * to a worker (`executor/env.ts`).
  */
-import { resolveBapiCredentials } from "../credential-store.js";
+import { readStoredBinding, resolveBapiCredentials } from "../credential-store.js";
 import { normalizeBaseUrlCandidate } from "../base-url.js";
 /**
  * The documented production Bridge API base URL — the value an operator pastes
@@ -79,6 +79,24 @@ export async function resolveExecutorApiAccess(repoName, deps, explicitBaseUrl)
             error: `could not resolve Bridge API credentials for repo '${trimmed}' (${result.kind})`,
         };
     }
+    // BAPI-1260: a stored key that guided setup approved for ONE endpoint is never
+    // sent to another. A restarted executor re-reads the binding here, so a unit
+    // whose --base-url drifted from the approved target refuses before its first
+    // authenticated request. An unbound (legacy) entry keeps today's behavior —
+    // the explicit-target requirement above still applies to it. This agrees
+    // with the production epic launch (BAPI-1272), which also accepts an unbound
+    // stored key at production and refuses one bound to another endpoint.
+    if (result.credentials.source === "file") {
+        const bound = await readStoredBinding(`bapi:${trimmed}`, storeDeps);
+        if (bound !== null && bound !== url.baseUrl) {
+            return {
+                ok: false,
+                error: `the stored credential for repo '${trimmed}' is approved for a different Bridge API ` +
+                    "endpoint than this executor's base URL; it was not sent. Re-run guided setup " +
+                    "(install conductor) to re-bind it, or correct --base-url.",
+            };
+        }
+    }
     return {
         ok: true,
         apiKey: result.credentials.apiKey,

package/build/executor/deps.js

@@ -25,6 +25,43 @@ const MAX_COMMAND_BUFFER = 10 * 1024 * 1024;
  * evaluation instead of stalling.
  */
 const EXECUTOR_HTTP_TIMEOUT_MS = 30_000;
+/**
+ * Wrap a real child stdin as the fakeable {@link OwnedStdin} (BAPI-1301, D4a).
+ *
+ * The permanent no-op `error` listener is the load-bearing line. A child that
+ * exits while its stdin is held open turns the next write (or the final `end()`)
+ * into an `EPIPE` emitted as an `error` event, and an `error` event with no
+ * listener is an uncaught exception that would crash the executor and every job
+ * it is supervising. With the listener attached the failure is still observable
+ * — `writeStdinBounded` / `closeStdinBounded` register their own one-shot
+ * `error` listener and report `write_error` — but it can never escape.
+ */
+function wrapChildStdin(stream) {
+    if (!stream)
+        return null;
+    stream.setDefaultEncoding("utf8");
+    stream.on("error", () => {
+        /* observed by the bounded write/close helpers; never uncaught */
+    });
+    return {
+        write: (data) => stream.write(data),
+        once: (event, listener) => {
+            stream.once(event, listener);
+        },
+        off: (event, listener) => {
+            stream.off(event, listener);
+        },
+        end: () => {
+            stream.end();
+        },
+        get writableEnded() {
+            return stream.writableEnded;
+        },
+        get destroyed() {
+            return stream.destroyed;
+        },
+    };
+}
 export function createDefaultExecutorDeps() {
     return {
         async runCommand(file, args, options) {
@@ -46,24 +83,50 @@ export function createDefaultExecutorDeps() {
             }
         },
         spawnProcess(file, args, options) {
+            // BAPI-1301 (D4a): stdin is piped ONLY when the caller selected it. Every
+            // legacy spawn keeps `"ignore"`, byte-for-byte the pre-BAPI-1301 stdio.
+            const pipeStdin = options.stdin === "pipe";
             const child = spawn(file, args, {
                 cwd: options.cwd,
                 env: options.env,
-                stdio: ["ignore", "pipe", "pipe"],
+                stdio: [pipeStdin ? "pipe" : "ignore", "pipe", "pipe"],
                 shell: false,
             });
             child.stdout?.setEncoding("utf8");
             child.stderr?.setEncoding("utf8");
+            const stdin = pipeStdin ? wrapChildStdin(child.stdin) : null;
+            // Recorded on the first `exit`, so `exited()` resolves even when it is
+            // asked after the event already fired.
+            let exitInfo = null;
+            const exitWaiters = [];
+            const settleExit = (info) => {
+                if (exitInfo !== null)
+                    return;
+                exitInfo = info;
+                for (const waiter of exitWaiters.splice(0))
+                    waiter(info);
+            };
+            child.on("exit", (code, signal) => settleExit({ exitCode: code, signal }));
+            child.on("error", () => settleExit({ exitCode: null, signal: null }));
             return {
                 pid: child.pid,
                 stdout: child.stdout ?? null,
                 stderr: child.stderr ?? null,
+                ...(pipeStdin ? { stdin } : {}),
                 wait() {
                     return new Promise((resolve) => {
                         child.on("close", (code, signal) => resolve({ exitCode: code, signal }));
                         child.on("error", () => resolve({ exitCode: null, signal: null }));
                     });
                 },
+                exited() {
+                    return new Promise((resolve) => {
+                        if (exitInfo !== null)
+                            resolve(exitInfo);
+                        else
+                            exitWaiters.push(resolve);
+                    });
+                },
                 kill(signal) {
                     try {
                         child.kill(signal);
@@ -128,6 +191,7 @@ export function createDefaultExecutorDeps() {
         env: process.env,
         cwd: process.cwd(),
         platform: process.platform,
+        arch: process.arch,
         homedir: os.homedir,
         async fetch(url, init) {
             const g = globalThis;

package/build/executor/env.js

@@ -119,6 +119,12 @@ const SECRET_NAME_FRAGMENTS = ["TOKEN", "SECRET", "PASSWORD", "API_KEY"];
  */
 export const EXPLICIT_DENY_KEYS = [
     "BRIDGE_MCP_PROFILE",
+    // BAPI-1301: the per-job ownership tag. The executor injects a fresh,
+    // unpredictable value AFTER this builder and the adapter have run
+    // (`process-containment.ts`), so an ambient value from the shell that
+    // launched the executor must never reach a worker: whoever chose the tag
+    // could make an unrelated process look job-owned to the cleanup sweep.
+    "BRIDGE_EXECUTOR_JOB_TAG",
     EPIC_IMPLEMENTER_NODE_PATH_ENV,
     // BAPI-1190: the legacy spelling stays denied so a stale ambient value from an
     // older package can never reach a worker during a version-skew window.

package/build/executor/heartbeat.js

@@ -49,6 +49,14 @@ export const PUSH_DETECT_INTERVAL_MS = 5_000;
  */
 export async function runHeartbeatLoop(params) {
     const { job, httpClient, options, deps, ownership, proc, observation } = params;
+    // BAPI-1301: every signal this loop sends goes through here, so a job-level
+    // phase host can withhold it once no owned child is live.
+    const signalTarget = () => params.currentChild ? params.currentChild() : proc;
+    const killCurrent = (reason) => {
+        const target = signalTarget();
+        if (target)
+            killOwnedProcess(target, reason);
+    };
     const pushDetectIntervalMs = params.pushDetectIntervalMs ?? PUSH_DETECT_INTERVAL_MS;
     // Baseline for push detection. `undefined` means "not yet sampled": the FIRST
     // successful sample only establishes the baseline and never itself triggers a
@@ -65,6 +73,7 @@ export async function runHeartbeatLoop(params) {
         const git = await params.collectTelemetry();
         observation.setGitTelemetry(git);
         const residue = observation.snapshot();
+        const ownershipContext = params.ownershipContext?.();
         const result = normalizeHeartbeatResult(await httpClient.heartbeat(job, {
             // Unconditionally the LOCAL head — never the remote marker. This is what
             // preserves the BAPI-704 semantic that a zero-commit job reports the base
@@ -72,11 +81,12 @@ export async function runHeartbeatLoop(params) {
             local_commit_count: git.local_commit_count,
             last_commit_sha: git.last_commit_sha,
             telemetry: residue,
+            ...(ownershipContext !== undefined ? { ownership_context: ownershipContext } : {}),
         }));
         // Checked BEFORE the outcome switch: a stop request is authoritative even
         // when it rides along with a non-`updated` outcome.
         if (result.stop_requested === true) {
-            killOwnedProcess(proc, "server_stop");
+            killCurrent("server_stop");
             return { kind: "server_stop" };
         }
         if (result.outcome === "auth_fatal") {
@@ -94,7 +104,7 @@ export async function runHeartbeatLoop(params) {
         }
         if (result.outcome === "stale_claim") {
             // Definitive dead claim: kill the worker and stop touching the worktree.
-            killOwnedProcess(proc, "stale_claim");
+            killCurrent("stale_claim");
             ownership.abandoned = true;
             ownership.abandonReason = "stale_claim";
             return { kind: "abandoned" };
@@ -102,7 +112,7 @@ export async function runHeartbeatLoop(params) {
         // retry_later / fatal_http_error: keep the worker alive within the dead-man
         // window; SIGKILL + abandon once 2 minutes pass without a successful beat.
         if (deps.now() - ownership.lastSuccessfulHeartbeatAt >= options.deadmanMs) {
-            killOwnedProcess(proc, "deadman");
+            killCurrent("deadman");
             ownership.abandoned = true;
             ownership.abandonReason = "deadman";
             return { kind: "abandoned" };

package/build/executor/http-client.js

@@ -9,6 +9,73 @@
  */
 import { RECONCILER_LIVENESS_VALUES } from "./types.js";
 import { readEpicRunCompletionState, } from "../conductor/bridge-api-client.js";
+/** BAPI-1258 — the server's stable `error_code` for refused capacity evidence. */
+export const UNSUPPORTED_TERMINAL_CAPACITY_ERROR_CODE = "UNSUPPORTED_TERMINAL_CAPACITY";
+/**
+ * Whether a `/fail` response refused the capacity evidence it carried: a 422
+ * (malformed envelope) or a 409 whose `error_code` is the stable unsupported
+ * code. A 409 `STALE_CLAIM` is NOT a refusal — the claim is gone, and resending
+ * cannot help. The body is inspected only for that one closed token.
+ */
+function isCapacityEvidenceRefusal(status, bodyText) {
+    if (status === 422)
+        return true;
+    if (status !== 409)
+        return false;
+    return readDetailErrorCode(bodyText) === UNSUPPORTED_TERMINAL_CAPACITY_ERROR_CODE;
+}
+/**
+ * BAPI-1301 (D4a) — the server's stable `error_code` when a covered `/complete`
+ * carries an envelope that does not prove the attempt finished its required
+ * work. The job is still claimed; the executor must report `/fail` (with the
+ * same envelope) instead.
+ */
+export const COMPLETION_EVIDENCE_REFUSES_SUCCESS_ERROR_CODE = "COMPLETION_EVIDENCE_REFUSES_SUCCESS";
+/**
+ * Read the stable `detail.error_code` token from an error body, or null. Only
+ * that one closed token is inspected; nothing else in the body is retained.
+ */
+function readDetailErrorCode(bodyText) {
+    try {
+        const parsed = JSON.parse(bodyText);
+        const detail = parsed && typeof parsed === "object" ? parsed.detail : undefined;
+        if (!detail || typeof detail !== "object")
+            return null;
+        const code = detail.error_code;
+        return typeof code === "string" ? code : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * BAPI-1301 (D4a) — whether a `/complete` response refused SUCCESS for a covered
+ * job because its completion evidence cannot support it: a 409 whose
+ * `error_code` is exactly {@link COMPLETION_EVIDENCE_REFUSES_SUCCESS_ERROR_CODE}.
+ *
+ * Mirrors {@link isCapacityEvidenceRefusal}'s shape, but is exported and NOT
+ * wired into `mapMutationResponse`: the mutation mapping stays unchanged (a 409
+ * still maps to `stale_claim` for every caller that does not ask), and the job
+ * runner — which holds the envelope — decides to re-report as `/fail`. A 409
+ * `STALE_CLAIM` is never a refusal: the claim is gone and a re-send cannot help.
+ */
+export function isCompletionEvidenceRefusal(status, bodyText) {
+    if (status !== 409)
+        return false;
+    return readDetailErrorCode(bodyText) === COMPLETION_EVIDENCE_REFUSES_SUCCESS_ERROR_CODE;
+}
+/**
+ * BAPI-1301 (D4a) — normalize a claim response's `required_capabilities`. Only an
+ * array of strings is admitted; anything else (absent on an older server, null,
+ * malformed) reads as `[]` — "no requirement", which is exactly what an older
+ * server's rows mean. A malformed value can never manufacture a requirement the
+ * executor would then refuse to run.
+ */
+export function normalizeRequiredCapabilities(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.every((entry) => typeof entry === "string") ? [...value] : [];
+}
 /** Bound a server-provided diagnostic snippet included in error strings. */
 function boundedDetail(text) {
     const trimmed = (text ?? "").trim();
@@ -118,6 +185,22 @@ function toConductorGetFetch(fetchLike) {
         };
     };
 }
+/**
+ * BAPI-1301 (D4a) — the completion-contract fields of a terminal report, each
+ * present only when set. Omitting an undefined key (rather than sending it as
+ * `undefined`/`null`) keeps a legacy terminal body byte-identical, which an
+ * older server's strict `extra="forbid"` schema depends on.
+ */
+function completionContractFields(report) {
+    return {
+        ...(report.completion_contract !== undefined
+            ? { completion_contract: report.completion_contract }
+            : {}),
+        ...(report.completion_evidence !== undefined
+            ? { completion_evidence: report.completion_evidence }
+            : {}),
+    };
+}
 export function createExecutorHttpClient(config) {
     const base = config.baseUrl.replace(/\/+$/, "") + "/executor/jobs";
     function keyForRepo(repoName) {
@@ -182,6 +265,12 @@ export function createExecutorHttpClient(config) {
                     if (!job || typeof job !== "object" || typeof job.claim_token !== "string") {
                         return { kind: "fatal", error: "claim returned a malformed job payload" };
                     }
+                    // BAPI-1301 (D4a): the requirement is normalized in place only when
+                    // the server sent the key, so an older server's claim keeps its exact
+                    // shape; a present-but-malformed value reads as "no requirement".
+                    if ("required_capabilities" in job) {
+                        job.required_capabilities = normalizeRequiredCapabilities(job.required_capabilities);
+                    }
                     return { kind: "claimed", job, reconcilerLiveness };
                 }
                 catch {
@@ -218,6 +307,11 @@ export function createExecutorHttpClient(config) {
                     local_commit_count: payload.local_commit_count,
                     last_commit_sha: payload.last_commit_sha,
                     telemetry: payload.telemetry,
+                    // BAPI-1301 (D4a): the key is added only when present, so a legacy
+                    // heartbeat body is byte-identical for an older server.
+                    ...(payload.ownership_context !== undefined
+                        ? { ownership_context: payload.ownership_context }
+                        : {}),
                 };
                 const res = await post(`/${job.id}/heartbeat`, body, job.repo_name);
                 status = res.status;
@@ -266,10 +360,11 @@ export function createExecutorHttpClient(config) {
                 local_commit_count: completion.local_commit_count,
                 last_commit_sha: completion.last_commit_sha,
                 telemetry: completion.telemetry,
+                ...completionContractFields(completion),
             };
             return mutate(`/${job.id}/complete`, body, true, job.repo_name);
         },
-        fail(job, failure) {
+        async fail(job, failure) {
             const body = {
                 repo_name: job.repo_name,
                 claim_token: job.claim_token,
@@ -279,7 +374,28 @@ export function createExecutorHttpClient(config) {
                 local_commit_count: failure.local_commit_count,
                 last_commit_sha: failure.last_commit_sha,
                 telemetry: failure.telemetry,
+                ...completionContractFields(failure),
             };
+            if (failure.capacity_evidence === undefined) {
+                return mutate(`/${job.id}/fail`, body, false, job.repo_name);
+            }
+            // BAPI-1258 — send the evidence once. If the server refuses it (unsupported
+            // protocol, or a malformed envelope), re-send the SAME ordinary failure
+            // without it, exactly once, so the job still reaches a terminal state and
+            // the original error kind/classification are preserved. Refused evidence
+            // never becomes an automatic recovery.
+            let first;
+            try {
+                first = await post(`/${job.id}/fail`, { ...body, capacity_evidence: failure.capacity_evidence }, job.repo_name);
+            }
+            catch {
+                return { outcome: "fatal_http_error" };
+            }
+            if (!isCapacityEvidenceRefusal(first.status, first.text)) {
+                return mapMutationResponse(first.status, first.text, false);
+            }
+            (config.warn ?? ((message) => console.error(message)))(`executor: server refused terminal capacity evidence for job ${job.id} ` +
+                `(HTTP ${first.status}); reporting an ordinary failure without automatic recovery.`);
             return mutate(`/${job.id}/fail`, body, false, job.repo_name);
         },
         /**