@bridge_gpt/mcp-server 0.2.34 → 0.2.37

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

@@ -90,9 +90,49 @@ const CONDUCTOR_ERROR_PREVIEW_MAX = 200;
  * backend message that happens to echo a token/header never reaches a log line.
  */
 function redactErrorPreview(text) {
-    return text
+    return (text
         .replace(/sk-[A-Za-z0-9_-]{8,}/g, "[REDACTED]")
-        .replace(/(Bearer|X-API-Key|api[_-]?key)\b\s*[:=]?\s*\S+/gi, "$1 [REDACTED]");
+        .replace(/(Bearer|X-API-Key|api[_-]?key)\b\s*[:=]?\s*\S+/gi, "$1 [REDACTED]")
+        // BAPI-754: the notification webhook URL is the run policy's one
+        // secret-bearing value (it can carry userinfo credentials or a query
+        // token). `stripWebhookUrlsDeep` removes it structurally before extraction,
+        // which handles every body the server actually emits; these two patterns are
+        // the textual backstop for a message that INTERPOLATED the URL into prose
+        // rather than carrying it as its own JSON leaf.
+        //
+        // Both are deliberately narrow — they match only a URL-shaped value. A
+        // broader "everything after webhook_url" rule would eat the field-path
+        // messages a 422 exists to deliver ("policy_json.notify.webhook_url: Input
+        // should be a valid URL"), leaving the operator with a redaction where their
+        // actionable error used to be.
+        .replace(/(webhook[_-]?url)\b["']?\s*[:=]?\s*["']?https?:\/\/\S+/gi, "$1 [REDACTED]")
+        // A URL carrying userinfo credentials is unsafe wherever it appears.
+        .replace(/https?:\/\/[^\s/@]+:[^\s/@]+@\S+/gi, "[REDACTED]"));
+}
+/**
+ * Return a deep copy of a parsed error body with every `webhook_url` key removed,
+ * at any depth.
+ *
+ * Structural removal, not pattern matching: a regex over the rendered JSON would
+ * depend on the exact serialization of a value we do not control, and a URL that
+ * failed to match would be printed in full. Removing the KEY cannot miss.
+ * Non-object input is returned unchanged, and cyclic input is left alone rather
+ * than throwing — this runs on an error path and must never raise.
+ */
+function stripWebhookUrlsDeep(value, depth = 0) {
+    if (depth > 12)
+        return undefined;
+    if (Array.isArray(value))
+        return value.map((item) => stripWebhookUrlsDeep(item, depth + 1));
+    if (!value || typeof value !== "object")
+        return value;
+    const out = {};
+    for (const [key, item] of Object.entries(value)) {
+        if (key === "webhook_url")
+            continue;
+        out[key] = stripWebhookUrlsDeep(item, depth + 1);
+    }
+    return out;
 }
 /** Collapse whitespace, redact secrets, and bound a string to the preview cap. */
 function boundedErrorPreview(text) {
@@ -201,7 +241,7 @@ function redactDiagnosticValues(diagnostics, secrets) {
  */
 async function readSanitizedErrorDiagnostics(resp, headers = {}) {
     try {
-        const diagnostics = extractSanitizedErrorDiagnostics(await resp.json());
+        const diagnostics = extractSanitizedErrorDiagnostics(stripWebhookUrlsDeep(await resp.json()));
         const secrets = Object.entries(headers)
             .filter(([k]) => /key|authorization|token/i.test(k))
             .map(([, v]) => v);
@@ -435,6 +475,21 @@ function conductorPostHeaders(access) {
  * POST and PATCH wrappers below.
  */
 async function fetchConductorJsonWithMethodAndTimeout(method, url, headers, body, timeoutMs, fetchImpl) {
+    const { body: parsed } = await fetchConductorJsonWithMethodStatusAndTimeout(method, url, headers, body, timeoutMs, fetchImpl);
+    return parsed;
+}
+/**
+ * Same transport as {@link fetchConductorJsonWithMethodAndTimeout}, but returns
+ * the successful response's HTTP status alongside the parsed body.
+ *
+ * BAPI-754: `POST /jira/epic-runs/runs` is idempotent and answers `201` for a
+ * fresh run and `200` for a reused one. That distinction is the ONLY signal
+ * separating "the policy I sent is now in force" from "a policy I did not send is
+ * already in force", and the body is byte-identical in both cases — so a caller
+ * that only sees the body has to issue another request to learn which happened.
+ * Success statuses only; every non-2xx path still throws exactly as before.
+ */
+async function fetchConductorJsonWithMethodStatusAndTimeout(method, url, headers, body, timeoutMs, fetchImpl) {
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), timeoutMs);
     try {
@@ -456,7 +511,7 @@ async function fetchConductorJsonWithMethodAndTimeout(method, url, headers, body
             throw new ConductorBridgeApiError("http", resp.status, diagnostics);
         }
         try {
-            return await resp.json();
+            return { status: resp.status, body: await resp.json() };
         }
         catch {
             throw new ConductorBridgeApiError("network");
@@ -737,6 +792,67 @@ export async function createEpicRun(access, request, fetchImpl = globalThis.fetc
     const parsed = await fetchConductorJsonPostWithTimeout(url, conductorPostHeaders(access), JSON.stringify(body), CONDUCTOR_FETCH_TIMEOUT_MS, fetchImpl);
     return parsed;
 }
+/**
+ * The same create call as {@link createEpicRun}, plus the disposition the HTTP
+ * status carries.
+ *
+ * `created: true` means HTTP `201` — a fresh run, so any `policyJson` sent is now
+ * the run's policy. `created: false` means HTTP `200` — the server returned an
+ * existing live run and IGNORED the submitted policy, because create is
+ * idempotent and never retargets a run. A caller that supplied a policy must
+ * therefore reconcile `run.policy_json` (already server-redacted) against what it
+ * asked for rather than assume it took effect.
+ *
+ * Added as a separate export rather than by widening {@link createEpicRun}'s
+ * return type, so existing callers that only need the record are untouched.
+ */
+export async function createEpicRunWithDisposition(access, request, fetchImpl = globalThis.fetch) {
+    requireNonEmptyString(request.epicKey);
+    const body = {
+        repo_name: access.repoName,
+        epic_key: request.epicKey,
+        status: request.status ?? "planning",
+        current_plan_version: request.currentPlanVersion ?? 0,
+    };
+    if (request.policyJson !== undefined)
+        body.policy_json = request.policyJson;
+    if (request.budgetWallClockSeconds !== undefined) {
+        body.budget_wall_clock_seconds = request.budgetWallClockSeconds;
+    }
+    if (request.budgetCostCents !== undefined) {
+        body.budget_cost_cents = request.budgetCostCents;
+    }
+    const url = buildConductorJiraUrl(access.baseUrl, `${EPIC_RUNS_API_PREFIX}/runs`);
+    const { status, body: parsed } = await fetchConductorJsonWithMethodStatusAndTimeout("POST", url, conductorPostHeaders(access), JSON.stringify(body), CONDUCTOR_FETCH_TIMEOUT_MS, fetchImpl);
+    return { run: parsed, created: status === 201 };
+}
+/**
+ * PATCH `/jira/epic-runs/runs/{identifier}` with a COMPLETE replacement of the
+ * operator-managed run policy.
+ *
+ * The endpoint's `policy_json` is replace-not-merge: keys absent from the request
+ * are removed and revert to resolver defaults. That is exactly the semantic a
+ * `--replace-policy` operator wants — the policy file is the whole policy — and it
+ * is why this helper sends the composed object verbatim instead of reading the
+ * stored policy and merging into it. A read-modify-write here would silently
+ * resurrect keys the operator deleted from their file.
+ *
+ * Two server-retained paths are deliberately NOT sent back:
+ * `notify.webhook_url` (absent from every response, so a client has nothing to
+ * echo; omitting it retains the stored URL) and the server-minted
+ * `feature_branch_provisioning` (retained automatically, and re-authoring it is a
+ * provenance conflict the server rejects).
+ */
+export async function replaceEpicRunPolicy(access, request, fetchImpl = globalThis.fetch) {
+    requireNonEmptyString(request.epicRunId);
+    const url = buildConductorJiraUrl(access.baseUrl, epicRunApiPath(request.epicRunId));
+    const body = JSON.stringify({
+        repo_name: access.repoName,
+        policy_json: request.policyJson,
+    });
+    const parsed = await fetchConductorJsonPatchWithTimeout(url, conductorPostHeaders(access), body, CONDUCTOR_FETCH_TIMEOUT_MS, fetchImpl);
+    return parsed;
+}
 /**
  * PATCH `/jira/epic-runs/runs/{identifier}` to transition an epic run's
  * lifecycle status. Drives the same backend `update_epic_run` CAS path the
@@ -985,6 +1101,15 @@ export async function reconcileShadowMerge(access, request, fetchImpl = globalTh
  * authoritative commit-watermark verdict for one ready ticket. The caller treats
  * `covered`/`not_applicable` as dispatchable, `stale` as hold, and `failed` as a
  * terminal shadow failure (the backend has already persisted the blocked state).
+ *
+ * BAPI-678: `stale` now covers two backend situations, and deliberately does not
+ * distinguish them on the wire — ordinary unproven freshness, and a `failed`
+ * shadow lifecycle DOWNGRADED by the backend's `policy_json.shadow.warn_only`
+ * posture. Both mean exactly the same thing to this caller (hold, do not claim a
+ * dispatch key), which is why no new verdict was introduced. The backend also
+ * bounds the warn-only hold with its own stale deadline and parks the ticket if
+ * it expires, so a hold here is not unbounded even though nothing on this side
+ * tracks its age. See {@link ShadowFreshnessVerdict}.
  */
 export async function fetchShadowDispatchFreshness(access, request, fetchImpl = globalThis.fetch) {
     requireNonEmptyString(request.epicKey);
@@ -995,6 +1120,64 @@ export async function fetchShadowDispatchFreshness(access, request, fetchImpl =
     const parsed = await fetchConductorJsonPostWithTimeout(url, conductorPostHeaders(access), body, CONDUCTOR_FETCH_TIMEOUT_MS, fetchImpl);
     return parseShadowDispatchFreshnessResult(parsed);
 }
+/**
+ * POST `/jira/epic-runs/plan/validate` to validate a plan blob without storing it.
+ *
+ * The point of the call is what it does NOT do: no run is created, no plan is
+ * stored, and no automation-start debit is charged. `setup-epic` runs this before
+ * every create so a plan the server would reject costs an operator nothing.
+ *
+ * Error handling is load-bearing for the CLI's branching, so it is spelled out:
+ *
+ * - A **`404`** surfaces as `ConductorBridgeApiError.status === 404` and means the
+ *   server predates this lane. That is the ONE case the CLI is allowed to fall
+ *   back from, so it must stay distinguishable from a validation failure.
+ * - A **transport failure** throws with NO `status`, which is how the CLI knows to
+ *   say "server unreachable, cannot fully validate" rather than blaming the plan.
+ * - A **`400`** is the plan's own field-named rejection and is terminal.
+ *
+ * A nominal `200` whose body does not match the strict success shape is treated as
+ * a protocol error rather than a partial success: reporting "valid" on a body we
+ * could not fully verify is precisely the false assurance this lane exists to
+ * remove.
+ */
+export async function validateEpicPlan(access, request, fetchImpl = globalThis.fetch) {
+    requirePositiveSafeInteger(request.planVersion);
+    const blobVersion = request.planBlob.plan_version;
+    if (blobVersion !== undefined && blobVersion !== request.planVersion) {
+        throw new ConductorValidationError(`planVersion mismatch: request.planVersion=${request.planVersion} but planBlob.plan_version=${blobVersion}`);
+    }
+    const url = buildConductorJiraUrl(access.baseUrl, `${EPIC_RUNS_API_PREFIX}/plan/validate`);
+    const body = {
+        repo_name: access.repoName,
+        plan_version: request.planVersion,
+        plan_blob: request.planBlob,
+    };
+    if (request.epicKey !== undefined)
+        body.epic_key = request.epicKey;
+    const parsed = await fetchConductorJsonPostWithTimeout(url, conductorPostHeaders(access), JSON.stringify(body), CONDUCTOR_FETCH_TIMEOUT_MS, fetchImpl);
+    return parseValidateEpicPlanResult(parsed);
+}
+/** Strict parse of the validate lane's success body; throws on any deviation. */
+function parseValidateEpicPlanResult(parsed) {
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new ConductorBridgeApiError("server");
+    }
+    const p = parsed;
+    const planHash = p["plan_hash"];
+    const serializationEnabled = p["serialization_enabled"];
+    const insertedEdges = p["inserted_edges"];
+    if (p["valid"] !== true ||
+        typeof planHash !== "string" ||
+        planHash.trim() === "" ||
+        typeof serializationEnabled !== "boolean" ||
+        typeof insertedEdges !== "number" ||
+        !Number.isSafeInteger(insertedEdges) ||
+        insertedEdges < 0) {
+        throw new ConductorBridgeApiError("server");
+    }
+    return { planHash, serializationEnabled, insertedEdges };
+}
 /**
  * POST the immutable plan blob to the durable-store endpoint. The blob is
  * written once per `(epic_run_id, plan_version)` and never mutated — a
@@ -1019,6 +1202,38 @@ export async function storeEpicPlan(access, request, fetchImpl = globalThis.fetc
     });
     return fetchConductorJsonPostWithTimeout(url, conductorPostHeaders(access), body, CONDUCTOR_FETCH_TIMEOUT_MS, fetchImpl);
 }
+/**
+ * PATCH one approved plan node's `ticket_spec` without re-storing or re-approving
+ * the plan (BAPI-722).
+ *
+ * This is how a ticket specification too large for Jira's 32,767-character
+ * description cap reaches the reviewer intact: it is stored on the approved plan
+ * node, which the reconciler already consults FIRST when resolving a spec-review
+ * prompt. Nothing else about the run changes — not the plan version, not the
+ * approval pointers, and not a single `epic_ticket_status` row — which is what
+ * makes it safe against a live epic.
+ *
+ * `expectedPlanHash` is the optimistic-concurrency token; a stale token on a real
+ * content change returns HTTP 409. The API key travels ONLY in the `X-API-Key`
+ * header, and neither the spec text nor any credential is ever incorporated into a
+ * thrown error message. Errors surface as a sanitized
+ * {@link ConductorBridgeApiError}.
+ */
+export async function updateApprovedPlanNodeTicketSpec(access, request, fetchImpl = globalThis.fetch) {
+    requireNonEmptyString(request.epicKey);
+    requireNonEmptyString(request.ticketKey);
+    requireNonEmptyString(request.expectedPlanHash);
+    requireNonEmptyString(request.ticketSpec);
+    const url = buildConductorJiraUrl(access.baseUrl, `${epicRunApiPath(request.epicKey)}/plan/nodes/` +
+        `${encodeURIComponent(request.ticketKey)}/ticket-spec`);
+    const body = JSON.stringify({
+        repo_name: access.repoName,
+        expected_plan_hash: request.expectedPlanHash,
+        ticket_spec: request.ticketSpec,
+    });
+    const parsed = await fetchConductorJsonPatchWithTimeout(url, conductorPostHeaders(access), body, CONDUCTOR_FETCH_TIMEOUT_MS, fetchImpl);
+    return parsed;
+}
 /**
  * Atomically approve a plan version. Bumps `epic_runs.approved_plan_hash` to
  * the named version's `plan_hash` in a single CAS write — never a
@@ -1203,3 +1418,177 @@ export async function transitionJiraStatus(access, ticketNumber, targetStatus =
         throw err;
     }
 }
+const READINESS_SOURCES = new Set(["epic", "project_default", "none"]);
+const ACTIONS_LEVELS = new Set(["write", "read", "none", "unknown"]);
+function readinessShapeError() {
+    // Deliberately carries NO field name, value, or payload excerpt: a malformed
+    // body is untrusted input and its contents must not reach output.
+    return new ConductorBridgeApiError("invalid-input", undefined, {
+        errorCode: "READINESS_SHAPE_INVALID",
+    });
+}
+function requireObject(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw readinessShapeError();
+    }
+    return value;
+}
+function requireBool(o, key) {
+    const v = o[key];
+    if (typeof v !== "boolean")
+        throw readinessShapeError();
+    return v;
+}
+function requireInt(o, key) {
+    const v = o[key];
+    if (typeof v !== "number" || !Number.isInteger(v))
+        throw readinessShapeError();
+    return v;
+}
+function requireNullableInt(o, key) {
+    const v = o[key];
+    if (v === null || v === undefined)
+        return null;
+    if (typeof v !== "number" || !Number.isInteger(v))
+        throw readinessShapeError();
+    return v;
+}
+function requireNullableString(o, key) {
+    const v = o[key];
+    if (v === null || v === undefined)
+        return null;
+    if (typeof v !== "string")
+        throw readinessShapeError();
+    return v;
+}
+function requireNullableBool(o, key) {
+    const v = o[key];
+    if (v === null || v === undefined)
+        return null;
+    if (typeof v !== "boolean")
+        throw readinessShapeError();
+    return v;
+}
+function requireEnum(o, key, allowed) {
+    const v = o[key];
+    if (typeof v !== "string" || !allowed.has(v))
+        throw readinessShapeError();
+    return v;
+}
+/**
+ * Validate a raw readiness body into the typed response, FAIL-CLOSED.
+ *
+ * Every field the composed doctor makes a safety decision on is checked for
+ * presence and exact type. This is not defensive nicety: a 200 whose body is
+ * missing `required_checks_empty`, or carries it as the string `"false"`, would
+ * otherwise be cast straight into an apparently-healthy report and the operator
+ * would be told a trivially-passing gate was fine.
+ */
+export function parseConductorReadinessResponse(body) {
+    const root = requireObject(body);
+    const repoName = root.repo_name;
+    if (typeof repoName !== "string" || repoName.length === 0)
+        throw readinessShapeError();
+    const sup = requireObject(root.supervisor);
+    const gh = requireObject(root.github);
+    const rec = requireObject(root.reconciler);
+    const exec = requireObject(root.executor);
+    const thr = requireObject(root.thresholds);
+    return {
+        repo_name: repoName,
+        supervisor: {
+            setup_present: requireBool(sup, "setup_present"),
+            setup_source: requireEnum(sup, "setup_source", READINESS_SOURCES),
+            setup_created_at: requireNullableString(sup, "setup_created_at"),
+            setup_updated_at: requireNullableString(sup, "setup_updated_at"),
+            config_present: requireBool(sup, "config_present"),
+            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_empty: requireBool(sup, "required_checks_empty"),
+            auto_merge_enabled: requireBool(sup, "auto_merge_enabled"),
+            merge_approval_required_set: requireBool(sup, "merge_approval_required_set"),
+        },
+        github: {
+            credentials_readable: requireBool(gh, "credentials_readable"),
+            owner_resolved: requireBool(gh, "owner_resolved"),
+            repo_id_resolved: requireBool(gh, "repo_id_resolved"),
+            installation_id_resolved: requireBool(gh, "installation_id_resolved"),
+            credentials_complete: requireBool(gh, "credentials_complete"),
+            actions_probe_succeeded: requireBool(gh, "actions_probe_succeeded"),
+            actions_permission_present: requireBool(gh, "actions_permission_present"),
+            actions_permission_level: requireEnum(gh, "actions_permission_level", ACTIONS_LEVELS),
+            actions_write: requireBool(gh, "actions_write"),
+        },
+        reconciler: {
+            liveness_readable: requireBool(rec, "liveness_readable"),
+            last_tick_at: requireNullableString(rec, "last_tick_at"),
+            last_tick_age_seconds: requireNullableInt(rec, "last_tick_age_seconds"),
+            stale: requireBool(rec, "stale"),
+            active_run_count: requireInt(rec, "active_run_count"),
+            expired_lease_count: requireInt(rec, "expired_lease_count"),
+        },
+        executor: {
+            liveness_readable: requireBool(exec, "liveness_readable"),
+            last_seen_at: requireNullableString(exec, "last_seen_at"),
+            last_seen_age_seconds: requireNullableInt(exec, "last_seen_age_seconds"),
+            ready: requireNullableBool(exec, "ready"),
+        },
+        thresholds: {
+            reconciler_stale_after_seconds: requireInt(thr, "reconciler_stale_after_seconds"),
+            executor_stale_after_seconds: requireInt(thr, "executor_stale_after_seconds"),
+        },
+    };
+}
+/**
+ * GET `/jira/epic-runs/conductor-readiness?repo_name=<repo>`.
+ *
+ * The API key travels ONLY in `X-API-Key`; `repo_name` is URL-encoded into the
+ * query string because the endpoint scopes on it. Fails closed on transport,
+ * auth, and shape errors alike.
+ */
+export async function fetchConductorReadiness(access, fetchImpl = globalThis.fetch) {
+    const url = buildConductorJiraUrl(access.baseUrl, `${EPIC_RUNS_API_PREFIX}/conductor-readiness`, {
+        repo_name: access.repoName,
+    });
+    const body = await fetchConductorJsonWithTimeout(url, conductorGetHeaders(access), CONDUCTOR_FETCH_TIMEOUT_MS, fetchImpl);
+    return parseConductorReadinessResponse(body);
+}
+/** Validate a raw bootstrap body, fail-closed (see {@link parseConductorReadinessResponse}). */
+export function parseConductorSupervisorBootstrapResponse(body) {
+    const o = requireObject(body);
+    const repoName = o.repo_name;
+    if (typeof repoName !== "string" || repoName.length === 0)
+        throw readinessShapeError();
+    const names = o.audited_field_names;
+    if (!Array.isArray(names) || names.some((n) => typeof n !== "string")) {
+        throw readinessShapeError();
+    }
+    return {
+        repo_name: repoName,
+        setup_written: requireBool(o, "setup_written"),
+        config_written: requireBool(o, "config_written"),
+        setup_source: requireEnum(o, "setup_source", READINESS_SOURCES),
+        config_source: requireEnum(o, "config_source", READINESS_SOURCES),
+        setup_created_at: requireNullableString(o, "setup_created_at"),
+        setup_updated_at: requireNullableString(o, "setup_updated_at"),
+        config_created_at: requireNullableString(o, "config_created_at"),
+        config_updated_at: requireNullableString(o, "config_updated_at"),
+        required_checks_count: requireInt(o, "required_checks_count"),
+        audited_field_names: names,
+    };
+}
+/**
+ * POST `/jira/epic-runs/supervisor-bootstrap?repo_name=<repo>`.
+ *
+ * The ONLY write this client performs. Deliberately carries no `review_policy`
+ * field: repository-default review policy is owned by BAPI-694.
+ */
+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);
+    return parseConductorSupervisorBootstrapResponse(body);
+}

package/build/conductor/deny-enforcement-preflight.js

@@ -47,6 +47,7 @@ export async function runDenyEnforcementPreflight(opts = {}) {
             const { result, layer } = await runDenyEnforcementCheck(ctx, {
                 model: opts.model,
                 timeoutMs: opts.timeoutMs,
+                permissionPosture: opts.permissionPosture,
             });
             if (result.status === "pass" && layer === "settings-deny") {
                 return {

package/build/conductor/done-gate.js

@@ -83,15 +83,49 @@ function parseCiChecksCondition(entry) {
     }
     return { type: REQUIRED_CI_CHECKS_GREEN, required_checks: normalized };
 }
-/** Valid review source values. */
-const VALID_REVIEW_SOURCES = new Set(["sticky_verdict", "native_review_decision", "min_approvals", "combination"]);
+/** Valid — i.e. CANONICAL — review source values (BAPI-689). */
+const VALID_REVIEW_SOURCES = new Set(["verdict_protocol", "native_review_decision", "min_approvals", "combination"]);
+/**
+ * Historical review-source spellings accepted on INPUT only.
+ *
+ * BAPI-689 unified three vocabularies onto one, but `done_gate_config` is
+ * free-form operator-authored JSONB that this module only ever reads — there is
+ * no migration that rewrites it. So already-stored configs keep naming the
+ * sticky-verdict source `sticky_verdict` (this module's own former spelling) or
+ * `claude_review_sticky` / `github_review_decision` (the former supervisor
+ * spellings), and they must stay readable.
+ *
+ * Mapping is applied at the parser seam and the CANONICAL value is what the
+ * parsed condition carries, so no alias survives into the config hash, the gate
+ * evaluator, or any serialized output.
+ */
+const REVIEW_SOURCE_ALIASES = Object.freeze({
+    sticky_verdict: "verdict_protocol",
+    claude_review_sticky: "verdict_protocol",
+    github_review_decision: "native_review_decision",
+});
+/**
+ * Canonicalize a raw stored review-source value.
+ *
+ * Returns the canonical spelling for a known alias, the value unchanged when it
+ * is already canonical, and the value unchanged when it is neither — so an
+ * unsupported spelling still reaches (and fails) `VALID_REVIEW_SOURCES` rather
+ * than being coerced into a default. Exact-match only: no case folding and no
+ * trimming, matching the strictness of every other field in this parser.
+ */
+function normalizeReviewSource(source) {
+    return REVIEW_SOURCE_ALIASES[source] ?? source;
+}
 /**
  * Parse and validate a single `review_state` condition entry.
  * Returns the normalized condition or `null` on any validation failure.
  */
 function parseReviewStateCondition(entry) {
-    const source = entry.source;
-    if (typeof source !== "string" || !VALID_REVIEW_SOURCES.has(source))
+    const rawSource = entry.source;
+    if (typeof rawSource !== "string")
+        return null;
+    const source = normalizeReviewSource(rawSource);
+    if (!VALID_REVIEW_SOURCES.has(source))
         return null;
     const condition = { type: REVIEW_STATE, source: source };
     if (entry.require_sticky_verdict !== undefined) {
@@ -425,7 +459,12 @@ export function evaluateReviewCondition(condition, snapshot) {
         return { passed: false, changesRequested: false, reason: "review snapshot unavailable" };
     }
     const source = condition.source;
-    if (source === "sticky_verdict") {
+    // BAPI-689: the condition's `source` is always CANONICAL here — every path to a
+    // `ReviewStateCondition` goes through `parseReviewStateCondition`, which maps
+    // the historical spellings before validating. `snapshot.sticky_verdict` is a
+    // different thing entirely (the parsed value OF the sticky comment) and keeps
+    // its name.
+    if (source === "verdict_protocol") {
         if (snapshot.sticky_verdict === "approved")
             return { passed: true, changesRequested: false, reason: "sticky verdict approved" };
         if (snapshot.sticky_verdict === "changes_requested")

package/build/conductor/epic-reconcile.js

@@ -171,6 +171,12 @@ export async function reconcileEpic(access, observed, plan, deps, supervisorConf
                 deps.log(`[epic-reconcile] shadow-freshness error for ${ticketKey}: ${safeDiagnosticMessage(err, "freshness error")}; holding`);
             }
             if (verdict === "stale") {
+                // BAPI-678: this covers ordinary unproven freshness AND the backend's
+                // warn-only downgrade of a `failed` shadow lifecycle. Identical handling
+                // is intentional — either way the watermark is unproven, so hold before
+                // claiming a dispatch key. The backend clocks the hold and parks the
+                // ticket if its own stale deadline expires, so "hold" is bounded there
+                // rather than repeating forever here.
                 deps.log(`[epic-reconcile] holding ${ticketKey}: shadow watermark stale`);
                 continue;
             }