@bridge_gpt/mcp-server 0.2.60 → 0.2.65

package/build/conductor/bridge-api-client.js

@@ -11,10 +11,12 @@
  */
 import os from "node:os";
 import { readFile, stat } from "node:fs/promises";
-import { resolveBapiCredentials } from "../credential-store.js";
+import { resolveBapiCredentials, resolveEpicLaunchCredential } from "../credential-store.js";
+import { readEpicLaunchProfile, resolveEpicLaunchTarget, } from "../epic-launch-profile.js";
 import { resolveStartTicketsRepoName } from "../start-tickets-repo.js";
 import { normalizePrNumber, normalizeSha } from "./git-ci-types.js";
 import { ConductorValidationError } from "./errors.js";
+import { parseContinuationStatusResult, parseContinueParkedChildResult, } from "./epic-child-continuation.js";
 import { resolveDeclaredRunBaseBranch } from "./run-branch.js";
 /** Default Bridge API base URL when `BAPI_BASE_URL` is unset. */
 export const CONDUCTOR_DEFAULT_BASE_URL = "https://bridgegpt-api.com";
@@ -63,6 +65,85 @@ export async function resolveConductorBridgeApiAccess(deps = {}) {
         : CONDUCTOR_DEFAULT_BASE_URL;
     return { ok: true, access: { repoName, apiKey: credResult.credentials.apiKey, baseUrl } };
 }
+/**
+ * The STRONGER launch-resolution contract (BAPI-1260), used by `drive-epic` and
+ * by a `setup-epic` that was handed a launch selection. The order is the point:
+ *
+ *   1. the selected profile is read and validated (host-local, read-only);
+ *   2. the TARGET is decided from `--base-url`, the profile, and `BAPI_BASE_URL`
+ *      — conflicts refuse. With none of them set, the target is
+ *      {@link CONDUCTOR_DEFAULT_BASE_URL} (BAPI-1272);
+ *   3. the repository is decided (profile binding, then `--repo`, then the
+ *      shared resolver);
+ *   4. only then is a credential looked up, coupled to that target AND that
+ *      repository ({@link resolveEpicLaunchCredential}). A stored key with no
+ *      binding is accepted only when the target is production; a key bound to
+ *      another endpoint, or an ambient key without a matching `BAPI_BASE_URL`,
+ *      is still refused.
+ *
+ * Nothing is sent anywhere by this function. {@link resolveConductorBridgeApiAccess}
+ * is deliberately left as it is for every other client.
+ */
+export async function resolveEpicLaunchBridgeApiAccess(selection, deps = {}) {
+    const env = deps.env ?? process.env;
+    const cwd = deps.cwd ?? process.cwd();
+    const homedir = deps.homedir ?? os.homedir;
+    const platform = deps.platform ?? process.platform;
+    const readFileImpl = deps.readFile ?? ((p) => readFile(p, "utf-8"));
+    const statImpl = deps.stat ?? ((p) => stat(p));
+    let profile = null;
+    if (selection.profileName !== undefined) {
+        const read = await readEpicLaunchProfile(selection.profileName, {
+            env,
+            homedir,
+            readFile: readFileImpl,
+            host: (deps.hostname ?? os.hostname)(),
+        });
+        if (!read.ok)
+            return { ok: false, kind: "profile-unusable", error: read.message };
+        profile = read.profile;
+    }
+    const target = resolveEpicLaunchTarget({
+        flagBaseUrl: selection.baseUrl,
+        flagRepo: deps.repoName,
+        profile,
+        env,
+        defaultBaseUrl: CONDUCTOR_DEFAULT_BASE_URL,
+    });
+    if (!target.ok)
+        return { ok: false, kind: target.kind, error: target.message };
+    const repoName = target.repoName ||
+        deps.repoName?.trim() ||
+        (await resolveStartTicketsRepoName({ env, cwd, readFile: readFileImpl }));
+    if (!repoName) {
+        return {
+            ok: false,
+            kind: "repo-missing",
+            error: "could not resolve repo name (set BAPI_REPO_NAME or add a valid .bridge/config)",
+        };
+    }
+    let cred;
+    try {
+        cred = await resolveEpicLaunchCredential(repoName, target.baseUrl, { env, homedir, platform, readFile: readFileImpl, stat: statImpl }, { productionBaseUrl: CONDUCTOR_DEFAULT_BASE_URL });
+    }
+    catch {
+        return { ok: false, kind: "credentials-unavailable", error: "failed to resolve Bridge API credentials" };
+    }
+    if (!cred.ok) {
+        const bindingFailure = cred.kind === "binding-unbound" || cred.kind === "binding-mismatch" || cred.kind === "ambient-key-unbound";
+        // The binding messages are fixed sentences naming the target KEY and the
+        // store path only; the generic store failures stay generic as before.
+        return bindingFailure
+            ? { ok: false, kind: "credential-unbound", error: cred.error }
+            : { ok: false, kind: "credentials-unavailable", error: "Bridge API credentials unavailable" };
+    }
+    return {
+        ok: true,
+        access: { repoName, apiKey: cred.apiKey, baseUrl: target.baseUrl },
+        targetSource: target.source,
+        profile,
+    };
+}
 /**
  * Build a `${baseUrl}/jira${apiPath}` URL with query params, trimming trailing
  * slashes on the base so there is never a double slash after the host. Query
@@ -668,6 +749,18 @@ export async function remediateEpicTicket(access, request, fetchImpl = globalThi
         throw err;
     }
 }
+/**
+ * BAPI-1310 (E1) — the server's refusal codes for the unexplained review-head
+ * stop. Each is an HTTP 409 that leaves the ticket parked.
+ */
+export const REVIEW_HEAD_REFUSAL_CODES = [
+    "REVIEW_HEAD_ADOPTION_REQUIRED",
+    "REVIEW_HEAD_EPISODE_CONFLICT",
+    "REVIEW_HEAD_STATE_INVALID",
+    "REVIEW_HEAD_BINDING_CHANGED",
+    "REVIEW_HEAD_LIVE_WORK",
+    "REVIEW_HEAD_UNAVAILABLE",
+];
 // ---------------------------------------------------------------------------
 // Local boundary validators (reject before any fetch call)
 // ---------------------------------------------------------------------------
@@ -1169,6 +1262,108 @@ export async function unparkEpicTicket(access, request, fetchImpl = globalThis.f
     });
     return postUnparkLikeRequest(url, conductorPostHeaders(access), body, fetchImpl);
 }
+const TYPED_CONTINUATION_STATUSES = new Set([200, 201, 409, 503]);
+const SAFE_ERROR_CODE_RE = /^[A-Za-z0-9_.:-]{1,64}$/;
+function continuationChildPath(epicRunId, ticketKey) {
+    return `${epicRunApiPath(epicRunId)}/tickets/${encodeURIComponent(ticketKey)}`;
+}
+function safeDetailErrorCode(body) {
+    if (body === null || typeof body !== "object")
+        return null;
+    const detail = body.detail;
+    if (detail === null || typeof detail !== "object")
+        return null;
+    const code = detail.error_code;
+    return typeof code === "string" && SAFE_ERROR_CODE_RE.test(code) ? code : null;
+}
+/**
+ * POST `.../tickets/{ticket_key}/continue` exactly once and classify the answer.
+ *
+ * Never throws for an HTTP or transport outcome — every one of them is returned
+ * as a {@link ContinuationPostOutcome}, so no caller can accidentally turn a
+ * timeout into "refused" by catching an exception. Never falls back to unpark.
+ * The API key travels only in the header; the body carries no credential and no
+ * caller-asserted authority.
+ */
+export async function postContinueParkedChild(access, request, fetchImpl = globalThis.fetch, timeoutMs = CONDUCTOR_FETCH_TIMEOUT_MS) {
+    const b = request.bindings;
+    requireNonEmptyString(b.epicRunId);
+    requireNonEmptyString(b.ticketKey);
+    const url = buildConductorJiraUrl(access.baseUrl, `${continuationChildPath(b.epicRunId, b.ticketKey)}/continue`);
+    const body = JSON.stringify({
+        repo_name: b.repoName,
+        request_id: request.requestId,
+        parked_gate: b.parkedGate,
+        expected_row_version: b.expectedRowVersion,
+        expected_head_sha: b.expectedHeadSha,
+        source_park_generation: b.sourceParkGeneration,
+        request_fingerprint: request.requestFingerprint,
+        ...(request.reason ? { reason: request.reason } : {}),
+    });
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        let resp;
+        try {
+            resp = await fetchImpl(url, {
+                method: "POST",
+                headers: conductorPostHeaders(access),
+                body,
+                signal: controller.signal,
+            });
+        }
+        catch {
+            return { kind: "uncertain", reason: controller.signal.aborted ? "timeout" : "network" };
+        }
+        let parsed;
+        let parsedOk = true;
+        try {
+            parsed = await resp.json();
+        }
+        catch {
+            parsedOk = false;
+        }
+        if (TYPED_CONTINUATION_STATUSES.has(resp.status) && parsedOk) {
+            try {
+                return { kind: "result", status: resp.status, result: parseContinueParkedChildResult(parsed) };
+            }
+            catch {
+                // Fall through: an untyped body on these statuses is classified below.
+            }
+        }
+        if (resp.status >= 200 && resp.status < 300) {
+            return { kind: "uncertain", reason: "malformed", status: resp.status };
+        }
+        if (resp.status >= 500) {
+            return { kind: "uncertain", reason: "server", status: resp.status };
+        }
+        // A 4xx without a typed body is an authoritative pre-mutation rejection.
+        return {
+            kind: "refused_http",
+            status: resp.status,
+            errorCode: parsedOk ? safeDetailErrorCode(parsed) : null,
+        };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * GET `.../tickets/{ticket_key}/continuation` — the child's current episode and,
+ * with `requestId`, that request's receipt. Read-only; bounded by the standard
+ * conductor timeout. Throws {@link ConductorBridgeApiError} on transport or HTTP
+ * failure and {@link ContinuationParseError} on a malformed body.
+ */
+export async function fetchChildContinuationStatus(access, query, fetchImpl = globalThis.fetch) {
+    requireNonEmptyString(query.epicRunId);
+    requireNonEmptyString(query.ticketKey);
+    const params = { repo_name: access.repoName };
+    if (query.requestId)
+        params.request_id = query.requestId;
+    const url = buildConductorJiraUrl(access.baseUrl, `${continuationChildPath(query.epicRunId, query.ticketKey)}/continuation`, params);
+    const parsed = await fetchConductorJsonWithTimeout(url, conductorGetHeaders(access), CONDUCTOR_FETCH_TIMEOUT_MS, fetchImpl);
+    return parseContinuationStatusResult(parsed);
+}
 /**
  * POST `/jira/epic-runs/runs/{epic_run_id}/tickets/{ticket_key}/adopt-current-head-and-unpark`
  * — the recovery lane for a human/external push that drifted the PR head off the
@@ -1359,8 +1554,13 @@ const REPAIR_TOKEN_RE = /^[a-z0-9_.:-]{1,120}$/;
 const POLICY_DIGEST_TOKEN_RE = /^policy:[0-9a-f]{12}$/;
 /** A dotted policy-path NAME. Never a value. */
 const POLICY_PATH_RE = /^[A-Za-z0-9_-]{1,100}(?:\.[A-Za-z0-9_-]{1,100}){0,15}$/;
-/** `resume-run`'s closed run-control state vocabulary. */
-const RESUME_RUN_STATES = ["paused", "quarantined", "none"];
+/**
+ * `resume-run`'s closed PRIOR-state vocabulary. `blocked` is the qualifying
+ * integration block the run-addressed route may lift; it is never a resulting state.
+ */
+const RESUME_RUN_BEFORE_STATES = ["blocked", "paused", "quarantined", "none"];
+/** `resume-run`'s closed RESULTING-state vocabulary: a resume always leaves no control. */
+const RESUME_RUN_AFTER_STATES = ["none"];
 function requireOnlyRepairKeys(p, extraKeys) {
     for (const key of Object.keys(p)) {
         if (!REPAIR_BASE_KEYS.includes(key) && !extraKeys.includes(key)) {
@@ -1427,18 +1627,29 @@ function parseResumeRunResult(parsed) {
     requireOnlyRepairKeys(p, []);
     const before = p["before"];
     const after = p["after"];
+    const committed = p["committed"];
+    const eventRecorded = p["event_recorded"];
     if (typeof before !== "string" ||
-        !RESUME_RUN_STATES.includes(before) ||
+        !RESUME_RUN_BEFORE_STATES.includes(before) ||
         typeof after !== "string" ||
-        !RESUME_RUN_STATES.includes(after)) {
+        !RESUME_RUN_AFTER_STATES.includes(after)) {
+        throw new ConductorBridgeApiError("server");
+    }
+    // Exactly two families: an applied resume (`blocked`/`paused`/`quarantined` →
+    // `none`, committed, either audit outcome) or the already-current no-op
+    // (`none` → `none`, nothing committed, no event). Any other combination is
+    // unconfirmed, never coerced into a result.
+    const applied = before !== "none" && committed;
+    const noOp = before === "none" && !committed && !eventRecorded;
+    if (!applied && !noOp) {
         throw new ConductorBridgeApiError("server");
     }
     return {
         epic_run_id: p["epic_run_id"],
         before,
         after,
-        committed: p["committed"],
-        event_recorded: p["event_recorded"],
+        committed,
+        event_recorded: eventRecorded,
     };
 }
 /**
@@ -1983,12 +2194,109 @@ export async function getEpicPlan(access, epicKey, planVersion, fetchImpl = glob
     const parsed = await fetchConductorJsonWithTimeout(url, conductorGetHeaders(access), CONDUCTOR_FETCH_TIMEOUT_MS, fetchImpl);
     return parsed;
 }
+/**
+ * BAPI-1252: the backend's closed canonical refusal vocabulary, mirrored as
+ * string literals (the Python source is `api/models/canonical_index_state.py`;
+ * a test pins the two together). A refusal carries exactly one of these and
+ * nothing else — no SHA, generation, owner, or server error text.
+ */
+export const CANONICAL_REFUSAL_REASONS = [
+    "canonical_validity_unavailable",
+    "canonical_index_unverified",
+    "canonical_source_missing",
+    "canonical_generation_mismatch",
+    "canonical_manifest_mismatch",
+    "canonical_index_advanced",
+    "canonical_capability_unsupported",
+];
+/** The canonical validity states the backend can report. */
+export const CANONICAL_VALIDITY_STATES = ["unverified", "writing", "verified"];
+/** The only canonical manifest versions this client accepts as evidence. */
+export const SUPPORTED_CANONICAL_MANIFEST_VERSIONS = ["v1"];
+const CANONICAL_PROVENANCE_KEYS = [
+    "canonical_validity_state",
+    "canonical_validity_verified",
+    "canonical_source_commit_sha",
+    "canonical_generation",
+    "canonical_manifest_version",
+    "canonical_validity_reason",
+];
+const FULL_COMMIT_SHA_RE = /^[0-9a-f]{40}$/;
+const CANONICAL_GENERATION_RE = /^[A-Za-z0-9_.:-]{1,128}$/;
+/**
+ * BAPI-1252: decode a `/jira/parse-status` body's canonical provenance, failing
+ * CLOSED. Only an explicit `verified` state, a literal `true` verified flag, a
+ * full lowercase 40-character source SHA, a well-formed generation, a supported
+ * manifest version, and no refusal reason decode as evidence. Everything else is
+ * one bounded refusal:
+ *
+ * - all six fields absent (an older server) → `canonical_capability_unsupported`;
+ * - an unknown state, an unknown manifest version, a malformed SHA or
+ *   generation, a non-boolean flag, or an unknown reason token →
+ *   `canonical_capability_unsupported` (the client cannot prove it, so it is not
+ *   proof);
+ * - a known refusal reason → that reason;
+ * - any non-verified state → `canonical_index_unverified`.
+ *
+ * Pure and total: it never throws and never consults lifecycle fields such as
+ * `status` or `indexed_commit_sha`.
+ */
+export function decodeCanonicalProvenance(body) {
+    const unsupported = { verified: false, reason: "canonical_capability_unsupported" };
+    if (body === null || typeof body !== "object" || Array.isArray(body))
+        return unsupported;
+    const obj = body;
+    const present = CANONICAL_PROVENANCE_KEYS.some((key) => key in obj && obj[key] !== undefined);
+    if (!present)
+        return unsupported;
+    const reason = obj.canonical_validity_reason;
+    if (reason !== undefined && reason !== null) {
+        if (typeof reason !== "string")
+            return unsupported;
+        if (!CANONICAL_REFUSAL_REASONS.includes(reason))
+            return unsupported;
+        return { verified: false, reason: reason };
+    }
+    const flag = obj.canonical_validity_verified;
+    if (flag !== undefined && flag !== null && typeof flag !== "boolean")
+        return unsupported;
+    const state = obj.canonical_validity_state;
+    if (typeof state !== "string")
+        return unsupported;
+    if (!CANONICAL_VALIDITY_STATES.includes(state))
+        return unsupported;
+    if (state !== "verified" || flag !== true) {
+        return { verified: false, reason: "canonical_index_unverified" };
+    }
+    const sha = obj.canonical_source_commit_sha;
+    const generation = obj.canonical_generation;
+    const version = obj.canonical_manifest_version;
+    if (typeof sha !== "string" || !FULL_COMMIT_SHA_RE.test(sha))
+        return unsupported;
+    if (typeof generation !== "string" || !CANONICAL_GENERATION_RE.test(generation)) {
+        return unsupported;
+    }
+    if (typeof version !== "string" ||
+        !SUPPORTED_CANONICAL_MANIFEST_VERSIONS.includes(version)) {
+        return unsupported;
+    }
+    return {
+        verified: true,
+        sourceCommitSha: sha,
+        generation,
+        manifestVersion: version,
+    };
+}
 /**
  * GET `/jira/parse-status?repo_name=<repo>` and return the durable parse-run
  * status. See {@link ParseRepositoryStatusValue} for the full state set (the
  * status surface distinguishes queued/running from terminal succeeded/failed).
  * Throws a sanitized {@link ConductorBridgeApiError} on any transport/auth/server
  * failure. URL + auth are unchanged from the pre-BAPI-527 two-state client.
+ *
+ * BAPI-1252: the body is returned as the server sent it, so a payload from an
+ * older server (no canonical fields) still decodes exactly as before. Canonical
+ * provenance is read from it only through {@link decodeCanonicalProvenance}.
  */
 export async function fetchParseStatus(access, fetchImpl = globalThis.fetch) {
     const url = buildConductorJiraUrl(access.baseUrl, "/parse-status", {
@@ -2092,6 +2400,21 @@ export const CONDUCTOR_REVIEW_ALIGNMENT_STATUSES = new Set([
     "not_configured",
     "invalid",
 ]);
+/** The closed verdict vocabulary the parser accepts. */
+export const REQUIRED_CHECKS_VERIFICATIONS = new Set([
+    "verified",
+    "unknown_name",
+    "unverifiable",
+]);
+/** BAPI-1260 — one mandatory-evidence verdict. Only `confirmed` ever holds. */
+export const ADMISSION_EVIDENCE_VERDICTS = [
+    "confirmed",
+    "denied",
+    "unable_to_verify",
+    "not_applicable",
+];
+/** The evidence schema this client renders. A newer one is shown as unknown, never as held. */
+export const ADMISSION_EVIDENCE_SCHEMA_VERSION = 1;
 /** Upper bound of the server's capped `fresh_reconciler_count` ("two or more"). */
 export const READINESS_FRESH_RECONCILER_COUNT_CAP = 2;
 const READINESS_SOURCES = new Set(["epic", "project_default", "none"]);
@@ -2139,6 +2462,20 @@ function requireNullableString(o, key) {
         throw readinessShapeError();
     return v;
 }
+/**
+ * BAPI-1279 — the executor coverage fields. Each is omitted when the server did
+ * not send it (an older deploy), and a present non-boolean fails CLOSED to
+ * `false`: coverage that cannot be read is coverage that is not confirmed.
+ */
+function parseOptionalExecutorCoverage(o) {
+    const out = {};
+    for (const key of ["process_heartbeat_fresh", "repo_wide_executor_live"]) {
+        if (!(key in o))
+            continue;
+        out[key] = o[key] === true;
+    }
+    return out;
+}
 function requireNullableBool(o, key) {
     const v = o[key];
     if (v === null || v === undefined)
@@ -2178,6 +2515,89 @@ function requireEnum(o, key, allowed) {
         throw readinessShapeError();
     return v;
 }
+/** The five BAPI-1254 supervisor keys, which travel as one all-or-none group. */
+const REQUIRED_CHECKS_VERIFICATION_KEYS = [
+    "required_checks_verification",
+    "required_checks_mismatch_count",
+    "required_checks_unverified_count",
+    "required_checks_evidence_observed_at",
+    "required_checks_evidence_fresh",
+];
+/**
+ * A strict ISO-8601 instant with an EXPLICIT UTC designator (`Z` or `+00:00`).
+ * A timezone-free or offset time is rejected rather than read in local time.
+ */
+const UTC_TIMESTAMP_PATTERN = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,9})?(Z|\+00:00)$/;
+function requireNonNegativeInt(o, key) {
+    const v = requireInt(o, key);
+    if (v < 0)
+        throw readinessShapeError();
+    return v;
+}
+/**
+ * Parse the BAPI-1254 required-check verification group, FAIL-CLOSED.
+ *
+ * All five keys ABSENT is an older server: every field becomes `null`, which
+ * every consumer renders as "could not verify" — absence is never verification.
+ * Any key present makes all five mandatory, and each is checked for exact type:
+ * the verdict against its closed vocabulary, both counts as non-negative
+ * integers, the time as an explicit-UTC instant, freshness as a real boolean.
+ * The server's cross-field invariants are then re-applied, because a
+ * contradictory group (a `verified` with a mismatch, a stale `unknown_name`)
+ * is untrusted input, not a verdict to render.
+ */
+function parseRequiredChecksVerification(sup, requiredChecksCount) {
+    const present = REQUIRED_CHECKS_VERIFICATION_KEYS.filter((key) => Object.prototype.hasOwnProperty.call(sup, key) && sup[key] !== undefined);
+    if (present.length === 0) {
+        return {
+            required_checks_verification: null,
+            required_checks_mismatch_count: null,
+            required_checks_unverified_count: null,
+            required_checks_evidence_observed_at: null,
+            required_checks_evidence_fresh: null,
+        };
+    }
+    if (present.length !== REQUIRED_CHECKS_VERIFICATION_KEYS.length)
+        throw readinessShapeError();
+    const verification = requireEnum(sup, "required_checks_verification", REQUIRED_CHECKS_VERIFICATIONS);
+    const mismatch = requireNonNegativeInt(sup, "required_checks_mismatch_count");
+    const unverified = requireNonNegativeInt(sup, "required_checks_unverified_count");
+    const observedAt = sup.required_checks_evidence_observed_at;
+    if (typeof observedAt !== "string" ||
+        !UTC_TIMESTAMP_PATTERN.test(observedAt) ||
+        Number.isNaN(Date.parse(observedAt))) {
+        throw readinessShapeError();
+    }
+    const fresh = requireBool(sup, "required_checks_evidence_fresh");
+    if (requiredChecksCount < 0 || mismatch + unverified > requiredChecksCount) {
+        throw readinessShapeError();
+    }
+    if (verification === "verified" &&
+        !(requiredChecksCount > 0 && mismatch === 0 && unverified === 0 && fresh)) {
+        throw readinessShapeError();
+    }
+    if (verification === "unknown_name" && !(fresh && mismatch > 0))
+        throw readinessShapeError();
+    if (verification === "unverifiable" && mismatch > 0)
+        throw readinessShapeError();
+    return {
+        required_checks_verification: verification,
+        required_checks_mismatch_count: mismatch,
+        required_checks_unverified_count: unverified,
+        required_checks_evidence_observed_at: observedAt,
+        required_checks_evidence_fresh: fresh,
+    };
+}
+/** Optional positive-integer threshold: absent/null from an older server. */
+function parseOptionalPositiveInt(o, key) {
+    const v = o[key];
+    if (v === undefined || v === null)
+        return null;
+    const parsed = requireInt(o, key);
+    if (parsed <= 0)
+        throw readinessShapeError();
+    return parsed;
+}
 /**
  * Validate a raw readiness body into the typed response, FAIL-CLOSED.
  *
@@ -2197,6 +2617,7 @@ export function parseConductorReadinessResponse(body) {
     const rec = requireObject(root.reconciler);
     const exec = requireObject(root.executor);
     const thr = requireObject(root.thresholds);
+    const requiredChecksCount = requireInt(sup, "required_checks_count");
     return {
         repo_name: repoName,
         supervisor: {
@@ -2208,13 +2629,14 @@ export function parseConductorReadinessResponse(body) {
             config_source: requireEnum(sup, "config_source", READINESS_SOURCES),
             config_created_at: requireNullableString(sup, "config_created_at"),
             config_updated_at: requireNullableString(sup, "config_updated_at"),
-            required_checks_count: requireInt(sup, "required_checks_count"),
+            required_checks_count: requiredChecksCount,
             required_checks_empty: requireBool(sup, "required_checks_empty"),
             auto_merge_enabled: requireBool(sup, "auto_merge_enabled"),
             merge_approval_required_set: requireBool(sup, "merge_approval_required_set"),
             review_policy_alignment: parseReviewPolicyAlignment(sup),
             // Absent on a pre-BAPI-694 server, where no repository default can exist.
             review_policy_present: sup.review_policy_present === true,
+            ...parseRequiredChecksVerification(sup, requiredChecksCount),
         },
         github: {
             credentials_readable: requireBool(gh, "credentials_readable"),
@@ -2240,18 +2662,91 @@ export function parseConductorReadinessResponse(body) {
             last_seen_at: requireNullableString(exec, "last_seen_at"),
             last_seen_age_seconds: requireNullableInt(exec, "last_seen_age_seconds"),
             ready: requireNullableBool(exec, "ready"),
+            ...parseOptionalExecutorCoverage(exec),
         },
         thresholds: {
             reconciler_stale_after_seconds: requireInt(thr, "reconciler_stale_after_seconds"),
             executor_stale_after_seconds: requireInt(thr, "executor_stale_after_seconds"),
+            required_checks_evidence_max_age_seconds: parseOptionalPositiveInt(thr, "required_checks_evidence_max_age_seconds"),
         },
         review_workflow: parseReviewWorkflow(root),
         conductor_ci_workflow: parseConductorCiWorkflow(root),
         unattended: parseUnattended(root),
         bring_up: parseBringUp(root),
         merge_execution: parseMergeExecution(root),
+        ...(() => {
+            const evidence = parseAdmissionEvidence(root);
+            return evidence === undefined ? {} : { admission_evidence: evidence };
+        })(),
     };
 }
+const ADMISSION_EVIDENCE_OWNERS = new Set(["operator", "repository_admin", "bridge_operations"]);
+const BOUNDED_TOKEN = /^[a-z0-9][a-z0-9_.:-]{0,79}$/;
+/**
+ * Parse the optional BAPI-1260 `admission_evidence` block.
+ *
+ * Absent → `undefined` (the key is then omitted from the parsed response).
+ * Present → validated strictly, EXCEPT that an unrecognized verdict is coerced
+ * to `unable_to_verify` rather than failing the whole readiness read: a newer
+ * server's vocabulary must degrade to "not proven", never to "held" and never
+ * to "no readiness at all". Free-text fields are bounded tokens only, so a
+ * payload cannot smuggle prose into operator output.
+ */
+function parseAdmissionEvidence(body) {
+    const raw = body.admission_evidence;
+    if (raw === undefined)
+        return undefined;
+    if (raw === null)
+        return null;
+    const o = requireObject(raw);
+    const schemaVersion = requireInt(o, "schema_version");
+    const observedAt = o.observed_at;
+    if (typeof observedAt !== "string")
+        throw readinessShapeError();
+    if (!Array.isArray(o.records) || o.records.length > 32)
+        throw readinessShapeError();
+    const token = (value, nullable) => {
+        if (value === null && nullable)
+            return null;
+        if (typeof value !== "string" || !BOUNDED_TOKEN.test(value))
+            throw readinessShapeError();
+        return value;
+    };
+    const records = o.records.map((entry) => {
+        const r = requireObject(entry);
+        const verdictRaw = r.verdict;
+        const verdict = ADMISSION_EVIDENCE_VERDICTS.includes(verdictRaw)
+            ? verdictRaw
+            : "unable_to_verify";
+        const owner = r.next_action_owner;
+        if (owner !== null && owner !== undefined && !ADMISSION_EVIDENCE_OWNERS.has(owner)) {
+            throw readinessShapeError();
+        }
+        const maxAge = requireInt(r, "max_age_seconds");
+        if (maxAge <= 0)
+            throw readinessShapeError();
+        const at = r.observed_at;
+        if (at !== null && typeof at !== "string")
+            throw readinessShapeError();
+        return {
+            predicate: token(r.predicate, false),
+            verdict,
+            observed_at: at,
+            source: token(r.source, false),
+            source_version: r.source_version === null || r.source_version === undefined
+                ? null
+                : typeof r.source_version === "string" && r.source_version.length <= 80
+                    ? r.source_version
+                    : (() => {
+                        throw readinessShapeError();
+                    })(),
+            max_age_seconds: maxAge,
+            reason: r.reason === undefined ? null : token(r.reason, true),
+            next_action_owner: (owner ?? null),
+        };
+    });
+    return { schema_version: schemaVersion, observed_at: observedAt, records };
+}
 /**
  * Parse the optional `merge_execution` block (BAPI-1135).
  *
@@ -2353,8 +2848,9 @@ function parseConductorCiWorkflow(body) {
  *
  * `notify_webhook_default_verified` is the one tri-state: absent is coerced to
  * `null` rather than to `false`, because "not verified here" and "verified as
- * broken" are different statements and only one of them is evidence. Every other
- * field is a strict boolean and a wrong type throws.
+ * broken" are different statements and only one of them is evidence.
+ * `escalation_email_available` (BAPI-1274) is lenient: anything but `true` is
+ * `false`. Every other field is a strict boolean and a wrong type throws.
  */
 function parseUnattended(body) {
     const raw = body.unattended;
@@ -2368,6 +2864,10 @@ function parseUnattended(body) {
             ? null
             : requireNullableBool(o, "notify_webhook_default_verified"),
         repository_readiness_confirmed: requireBool(o, "repository_readiness_confirmed"),
+        // BAPI-1274 — optional and lenient: absent, null, or any non-boolean
+        // normalizes to `false` rather than throwing, because a server older than
+        // BAPI-1274 omits it and must keep today's behavior.
+        escalation_email_available: o.escalation_email_available === true,
     };
 }
 /**
@@ -2384,6 +2884,15 @@ export async function fetchConductorReadiness(access, fetchImpl = globalThis.fet
     const body = await fetchConductorJsonWithTimeout(url, conductorGetHeaders(access), CONDUCTOR_FETCH_TIMEOUT_MS, fetchImpl);
     return parseConductorReadinessResponse(body);
 }
+const ROW_OUTCOMES = new Set(["created", "changed", "preserved"]);
+function optionalRowOutcome(o, key) {
+    const v = o[key];
+    if (v === undefined || v === null)
+        return null;
+    if (typeof v !== "string" || !ROW_OUTCOMES.has(v))
+        throw readinessShapeError();
+    return v;
+}
 /** Validate a raw bootstrap body, fail-closed (see {@link parseConductorReadinessResponse}). */
 export function parseConductorSupervisorBootstrapResponse(body) {
     const o = requireObject(body);
@@ -2398,6 +2907,8 @@ export function parseConductorSupervisorBootstrapResponse(body) {
         repo_name: repoName,
         setup_written: requireBool(o, "setup_written"),
         config_written: requireBool(o, "config_written"),
+        setup_outcome: optionalRowOutcome(o, "setup_outcome"),
+        config_outcome: optionalRowOutcome(o, "config_outcome"),
         setup_source: requireEnum(o, "setup_source", READINESS_SOURCES),
         config_source: requireEnum(o, "config_source", READINESS_SOURCES),
         setup_created_at: requireNullableString(o, "setup_created_at"),
@@ -2411,14 +2922,167 @@ export function parseConductorSupervisorBootstrapResponse(body) {
 /**
  * POST `/jira/epic-runs/supervisor-bootstrap?repo_name=<repo>`.
  *
- * The ONLY write this client performs. Since BAPI-694 it may also carry the
- * optional repository-default `review_policy`; omitting that field stores no
- * default rather than a neutral one.
+ * Since BAPI-694 it may also carry the optional repository-default
+ * `review_policy`; omitting that field keeps the stored default. Since BAPI-1288
+ * a relaxation is refused with 409 unless `approval` carries the exact token a
+ * {@link previewConductorSupervisorBootstrap} of the SAME request returned.
+ * A 409 is never retried here — see {@link classifySupervisorBootstrapFailure}.
  */
 export async function bootstrapConductorSupervisorDefaults(access, request, fetchImpl) {
     const url = buildConductorJiraUrl(access.baseUrl, `${EPIC_RUNS_API_PREFIX}/supervisor-bootstrap`, {
         repo_name: access.repoName,
     });
-    const body = await fetchConductorJsonPostWithTimeout(url, conductorPostHeaders(access), JSON.stringify(request), CONDUCTOR_FETCH_TIMEOUT_MS, fetchImpl);
+    const body = await fetchConductorJsonWithMethodAndTimeout("POST", url, conductorPostHeaders(access), JSON.stringify(request), CONDUCTOR_FETCH_TIMEOUT_MS, fetchImpl, { readErrorField: true });
     return parseConductorSupervisorBootstrapResponse(body);
 }
+// ---------------------------------------------------------------------------
+// BAPI-1288 — preview of a protected project-default change
+// ---------------------------------------------------------------------------
+/** Closed vocabularies of a server-authored gate-change effect. */
+const GATE_CHANGE_REQUIREMENTS = new Set([
+    "done_gate",
+    "required_ci_checks",
+    "done_gate_review",
+    "review_policy_default",
+]);
+const GATE_CHANGE_KINDS = new Set(["removed", "weakened", "replaced"]);
+const GATE_OBLIGATIONS = new Set([
+    "ci_check_green",
+    "sticky_verdict_approved",
+    "native_review_approved",
+    "approval_minimum",
+    "verdictless_review_parks",
+]);
+const CHECK_REF_RE = /^ci-[0-9a-f]{12}$/;
+/** Bounds the client enforces on server text before it may be displayed. */
+const MAX_EFFECTS = 16;
+const MAX_DESCRIPTION_LENGTH = 300;
+const MAX_CHECK_REFS = 50;
+const MAX_APPROVAL_TOKEN_LENGTH = 1024;
+function requireObligationList(o, key) {
+    const v = o[key];
+    if (!Array.isArray(v) || v.length > GATE_OBLIGATIONS.size)
+        throw readinessShapeError();
+    for (const item of v) {
+        if (typeof item !== "string" || !GATE_OBLIGATIONS.has(item))
+            throw readinessShapeError();
+    }
+    return v;
+}
+function parseGateChangeEffect(raw) {
+    const o = requireObject(raw);
+    const refs = o.removed_ci_check_refs;
+    if (!Array.isArray(refs) ||
+        refs.length > MAX_CHECK_REFS ||
+        refs.some((r) => typeof r !== "string" || !CHECK_REF_RE.test(r))) {
+        throw readinessShapeError();
+    }
+    const description = o.description;
+    if (typeof description !== "string" ||
+        description.length === 0 ||
+        description.length > MAX_DESCRIPTION_LENGTH ||
+        /[\u0000-\u001F\u007F]/.test(description)) {
+        throw readinessShapeError();
+    }
+    const count = requireInt(o, "removed_ci_check_count");
+    if (count < 0)
+        throw readinessShapeError();
+    return {
+        row: requireEnum(o, "row", new Set(["setup", "config"])),
+        requirement: requireEnum(o, "requirement", GATE_CHANGE_REQUIREMENTS),
+        change: requireEnum(o, "change", GATE_CHANGE_KINDS),
+        removed_obligations: requireObligationList(o, "removed_obligations"),
+        replacement_obligations: requireObligationList(o, "replacement_obligations"),
+        removed_ci_check_count: count,
+        removed_ci_check_refs: refs,
+        stored_min_approvals: requireNullableInt(o, "stored_min_approvals"),
+        proposed_min_approvals: requireNullableInt(o, "proposed_min_approvals"),
+        description,
+    };
+}
+/**
+ * Validate a raw preview body, fail-closed.
+ *
+ * Every field is checked against the server's closed contract; anything else —
+ * an unknown outcome, an effect category this client does not know, an
+ * over-long or control-character description, a token without
+ * `approval_required`, a writer or repository that does not match the request —
+ * is a shape error, so an unbounded server string can never reach the operator's
+ * terminal as if it were a vetted description.
+ */
+export function parseConductorSupervisorBootstrapPreview(body, expectedRepoName) {
+    const o = requireObject(body);
+    if (o.repo_name !== expectedRepoName)
+        throw readinessShapeError();
+    if (o.writer !== "bootstrap")
+        throw readinessShapeError();
+    const names = o.changed_field_names;
+    if (!Array.isArray(names) || names.some((n) => typeof n !== "string" || n.length > 100)) {
+        throw readinessShapeError();
+    }
+    const effectsRaw = o.effects;
+    if (!Array.isArray(effectsRaw) || effectsRaw.length > MAX_EFFECTS)
+        throw readinessShapeError();
+    const effects = effectsRaw.map(parseGateChangeEffect);
+    const approvalRequired = requireBool(o, "approval_required");
+    const token = requireNullableString(o, "approval_token");
+    if (approvalRequired !== effects.length > 0)
+        throw readinessShapeError();
+    if (approvalRequired !== (token !== null))
+        throw readinessShapeError();
+    if (token !== null && (token.length === 0 || token.length > MAX_APPROVAL_TOKEN_LENGTH)) {
+        throw readinessShapeError();
+    }
+    return {
+        repo_name: expectedRepoName,
+        writer: "bootstrap",
+        setup_outcome: requireEnum(o, "setup_outcome", ROW_OUTCOMES),
+        config_outcome: requireEnum(o, "config_outcome", ROW_OUTCOMES),
+        changed_field_names: names,
+        approval_required: approvalRequired,
+        effects,
+        approval_token: token,
+    };
+}
+/**
+ * POST `/jira/epic-runs/supervisor-bootstrap/preview?repo_name=<repo>` — what a
+ * bootstrap with `request` WOULD do. Read-only on the server.
+ *
+ * Send the same body to {@link bootstrapConductorSupervisorDefaults} afterwards
+ * (plus `approval` when the preview required it); any difference makes the
+ * server's token check fail with a fresh-preview conflict.
+ */
+export async function previewConductorSupervisorBootstrap(access, request, fetchImpl) {
+    const url = buildConductorJiraUrl(access.baseUrl, `${EPIC_RUNS_API_PREFIX}/supervisor-bootstrap/preview`, { repo_name: access.repoName });
+    const body = await fetchConductorJsonWithMethodAndTimeout("POST", url, conductorPostHeaders(access), JSON.stringify(request), CONDUCTOR_FETCH_TIMEOUT_MS, fetchImpl, { readErrorField: true });
+    return parseConductorSupervisorBootstrapPreview(body, access.repoName);
+}
+const GATE_CHANGE_CODE_TO_KIND = Object.freeze({
+    APPROVAL_REQUIRED: "approval-required",
+    STALE_PREVIEW: "stale-preview",
+    UNKNOWN_STORED_STATE: "unknown-stored-state",
+    NON_RELAXABLE: "non-relaxable",
+    INVALID_PROPOSAL: "invalid-proposal",
+    STATE_UNAVAILABLE: "state-unavailable",
+});
+export function classifySupervisorBootstrapFailure(err) {
+    if (!(err instanceof ConductorBridgeApiError))
+        return "network";
+    const mapped = err.errorCode ? GATE_CHANGE_CODE_TO_KIND[err.errorCode] : undefined;
+    if (mapped)
+        return mapped;
+    if (err.kind === "invalid-input")
+        return "unsupported-protocol";
+    if (err.kind === "unauthorized")
+        return "unauthorized";
+    if (err.kind === "timeout")
+        return "timeout";
+    if (err.kind === "network")
+        return "network";
+    if (err.status === 404 || err.status === 405 || err.status === 422) {
+        return "unsupported-protocol";
+    }
+    if (err.kind === "server")
+        return "server";
+    return "rejected";
+}