@bridge_gpt/mcp-server 0.2.53 → 0.2.55

package/build/implement-epic/bridge-client.js

@@ -0,0 +1,773 @@
+/**
+ * Bridge API client for the `implement-epic` CLI (BAPI-802).
+ *
+ * This module lives OUTSIDE `mcp_server/src/conductor/`, which is frozen v1. It
+ * imports from `conductor/bridge-api-client.ts` in the reuse-only direction the
+ * freeze allows — shared URL construction, the access type, and the timeout/
+ * sanitization fetch helpers — and adds nothing under `conductor/`. That import
+ * is recorded in `conductor/README.md`'s survivor table.
+ *
+ * Two contract properties, fixed by `implement-epic-bridge-client` and relied on by
+ * BAPI-803, which extends this same file:
+ *
+ * - **No function throws.** Every failure — transport, timeout, HTTP status,
+ *   malformed body, even a bad `baseUrl` — resolves to
+ *   `{ ok: false, status, error }`. A CLI that has to wrap each call in
+ *   `try/catch` gets that wrong exactly once, in the recovery path where it
+ *   matters most.
+ * - **The API key never leaves the `X-API-Key` header.** It is not in a URL, a
+ *   query string, a request body, or any returned error text. Unrecognized
+ *   throw values collapse to a stable generic message rather than being
+ *   stringified, because a stringified unknown is exactly how a credential
+ *   escapes.
+ *
+ * Credentials are NOT resolved here: the caller passes an access object it
+ * already obtained from `resolveConductorBridgeApiAccess()`, which reads
+ * `BAPI_API_KEY` then the user-scoped credential store.
+ *
+ * No MCP tool is registered from this module — the `tools/list` token budget is
+ * effectively frozen.
+ */
+import { buildConductorJiraUrl, buildConductorVcsUrl, fetchConductorJsonPostWithTimeout, fetchConductorJsonPutWithTimeout, fetchConductorJsonWithTimeout, fetchConductorReadiness, fetchEffectiveSupervisorConfig, fetchEffectiveSupervisorSetup, fetchEpicRunState, fetchParseStatus, fetchPrReviewStatus, pollCiChecksForCommit, ConductorBridgeApiError, CONDUCTOR_FETCH_TIMEOUT_MS, } from "../conductor/bridge-api-client.js";
+/**
+ * The one message returned for any failure whose cause cannot be described
+ * without risking the credential. Stable so callers can match on it.
+ */
+const GENERIC_ERROR = "Bridge API request failed";
+/** GET headers. The key travels in this header and nowhere else. */
+function getHeaders(access) {
+    return { "X-API-Key": access.apiKey };
+}
+/** POST headers. Same rule, plus the JSON content type. */
+function postHeaders(access) {
+    return { "X-API-Key": access.apiKey, "Content-Type": "application/json" };
+}
+/** PUT headers. Identical to {@link postHeaders}; named for the call site. */
+function putHeaders(access) {
+    return { "X-API-Key": access.apiKey, "Content-Type": "application/json" };
+}
+/**
+ * Remove the exact API key from a message that is otherwise safe to surface.
+ *
+ * The shared helpers already redact header values from their diagnostics, so
+ * this is a second, independent pass over the final string: the belt is cheap
+ * and the failure it guards against is unrecoverable. Very short keys are left
+ * alone because scrubbing a 1-3 character string would mangle ordinary prose.
+ */
+function scrubKey(text, apiKey) {
+    if (!apiKey || apiKey.length < 4)
+        return text;
+    return text.split(apiKey).join("[REDACTED]");
+}
+/**
+ * Convert any thrown value into a `{ ok: false }` result.
+ *
+ * A `ConductorBridgeApiError` carries a message the shared helper already built
+ * from the coarse kind, HTTP status, backend error code, and a bounded,
+ * secret-redacted body preview — that is what lets a 409 name the override
+ * branch the server preserved. Anything else is collapsed to
+ * {@link GENERIC_ERROR}: an unknown throw value has unknown contents, and
+ * stringifying it is how a credential or a raw response body escapes.
+ */
+function toFailure(err, access) {
+    if (err instanceof ConductorBridgeApiError) {
+        return {
+            ok: false,
+            status: typeof err.status === "number" ? err.status : null,
+            error: scrubKey(err.message || GENERIC_ERROR, access.apiKey),
+        };
+    }
+    return { ok: false, status: null, error: GENERIC_ERROR };
+}
+/** True when `value` is a plain (non-array, non-null) object. */
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Read a `string | null` field, returning `undefined` when it is neither. */
+function nullableString(value) {
+    if (value === null)
+        return null;
+    if (typeof value === "string")
+        return value;
+    return undefined;
+}
+/**
+ * Run `operation` and convert any thrown value into a sanitized failure result.
+ *
+ * Every +803 read is this shape, so the try/catch lives in one place: a helper
+ * added later cannot forget it and reintroduce a throwing client.
+ */
+async function wrap(access, operation) {
+    try {
+        return { ok: true, value: await operation() };
+    }
+    catch (err) {
+        return toFailure(err, access);
+    }
+}
+/**
+ * `PUT /jira/epic-runs/supervisor-config/defaults/?repo_name=` — replace the
+ * project-default supervisor configuration.
+ *
+ * The complete {@link EpicSupervisorConfigRequest} is sent. `init` builds it by
+ * reading the effective config and flipping exactly one field, so enabling
+ * auto-merge never silently reverts another operator setting.
+ */
+export async function putSupervisorConfigDefaults(access, config, fetchImpl = globalThis.fetch) {
+    return wrap(access, () => {
+        const url = buildConductorJiraUrl(access.baseUrl, "/epic-runs/supervisor-config/defaults/", { repo_name: access.repoName });
+        return fetchConductorJsonPutWithTimeout(url, putHeaders(access), JSON.stringify(config), CONDUCTOR_FETCH_TIMEOUT_MS, fetchImpl);
+    });
+}
+/** `GET /jira/epic-runs/supervisor-config/defaults/` — the effective config. */
+export async function getEffectiveSupervisorConfig(access, fetchImpl = globalThis.fetch) {
+    return wrap(access, () => fetchEffectiveSupervisorConfig(access, undefined, fetchImpl));
+}
+/**
+ * `GET /jira/epic-runs/supervisor-setup/defaults/` — the effective setup.
+ *
+ * Returned verbatim, `done_gate_config` included and un-normalized: it is the
+ * raw operator-authored JSONB that `parseDoneGateConfig` is the sole authority
+ * on, and normalizing it here would fork that vocabulary.
+ */
+export async function getEffectiveSupervisorSetup(access, fetchImpl = globalThis.fetch) {
+    return wrap(access, () => fetchEffectiveSupervisorSetup(access, undefined, fetchImpl));
+}
+/**
+ * `GET /jira/epic-runs/conductor-readiness?repo_name=` — readiness facts.
+ *
+ * `init` reads three of them: `supervisor.auto_merge_enabled`,
+ * `supervisor.required_checks_count`, and `supervisor.required_checks_empty`.
+ * The underlying fetcher validates the body fail-closed, so a 200 whose body is
+ * missing `required_checks_empty` becomes a failure here rather than an
+ * apparently-healthy report.
+ */
+export async function getConductorReadiness(access, fetchImpl = globalThis.fetch) {
+    return wrap(access, () => fetchConductorReadiness(access, fetchImpl));
+}
+/**
+ * `POST /jira/resolve-ci-checks` — discover and classify the repository's CI
+ * checks, and warm the `poll-ci-checks` cache as a side effect.
+ *
+ * `commitRef` is optional and forwarded only when supplied. The response is the
+ * server's soft envelope, preserved verbatim inside `value`.
+ */
+export async function resolveCiChecks(access, commitRef, fetchImpl = globalThis.fetch) {
+    return wrap(access, () => {
+        const url = buildConductorJiraUrl(access.baseUrl, "/resolve-ci-checks");
+        const payload = { repo_name: access.repoName };
+        if (typeof commitRef === "string" && commitRef.trim().length > 0) {
+            payload.commit_ref = commitRef;
+        }
+        return fetchConductorJsonPostWithTimeout(url, postHeaders(access), JSON.stringify(payload), CONDUCTOR_FETCH_TIMEOUT_MS, fetchImpl);
+    });
+}
+/**
+ * `GET /jira/poll-ci-checks?repo_name=&commit_ref=` — CI status for one SHA.
+ *
+ * Until `resolve-ci-checks` has run once for the repository this answers 200
+ * with `{ available: false, action: "Call resolve-ci-checks first…" }`. That is
+ * a successful result carrying an instruction, not an error, and it stays in
+ * `value` so `status` can act on it.
+ */
+export async function pollCiChecks(access, commitRef, fetchImpl = globalThis.fetch) {
+    return wrap(access, () => pollCiChecksForCommit(access, commitRef, fetchImpl));
+}
+/**
+ * `GET /vcs/pull-requests/{n}/reviews/status?repo_name=` — normalized review
+ * state. Root-mounted, NOT under `/jira`.
+ *
+ * `prNumber` is validated by the wrapped fetcher before any request is issued,
+ * so a zero/negative/non-integer number fails without a network round trip.
+ */
+export async function getPrReviewStatus(access, prNumber, fetchImpl = globalThis.fetch) {
+    return wrap(access, () => fetchPrReviewStatus(access, prNumber, fetchImpl));
+}
+/** `GET /jira/parse-status?repo_name=` — the durable parse-run status. */
+export async function getParseStatus(access, fetchImpl = globalThis.fetch) {
+    return wrap(access, () => fetchParseStatus(access, fetchImpl));
+}
+/**
+ * `GET /jira/epic-runs/runs/{epicKey}/state?repo_name=` — the durable epic-run
+ * state.
+ *
+ * A pure READ. `implement-epic` never creates an `epic_run`; `init` calls this
+ * only to refuse when the server is already conducting the same epic through
+ * the v2 reconciler, which would otherwise drive the same tickets in parallel.
+ */
+export async function getEpicRunState(access, epicKey, fetchImpl = globalThis.fetch) {
+    return wrap(access, () => fetchEpicRunState(access, epicKey, fetchImpl));
+}
+/**
+ * `GET /jira/config-field/base_branch?repo_name=` — the repository's configured
+ * base branch.
+ *
+ * Normalized defensively: an absent `value`, an explicit `null`, and a
+ * blank string all become `base_branch: null`, which the caller reads as "not
+ * configured" and falls through to `main`. A body that is not an object at all
+ * is a failure — silently treating an unparseable response as "not configured"
+ * would provision the epic branch from the wrong base.
+ */
+export async function getConfigFieldBaseBranch(access, fetchImpl = globalThis.fetch) {
+    const result = await wrap(access, () => {
+        const url = buildConductorJiraUrl(access.baseUrl, "/config-field/base_branch", {
+            repo_name: access.repoName,
+        });
+        return fetchConductorJsonWithTimeout(url, getHeaders(access), CONDUCTOR_FETCH_TIMEOUT_MS, fetchImpl);
+    });
+    if (!result.ok)
+        return result;
+    if (!isRecord(result.value)) {
+        return { ok: false, status: null, error: GENERIC_ERROR };
+    }
+    const raw = result.value["value"];
+    if (raw === null || raw === undefined) {
+        return { ok: true, value: { base_branch: null } };
+    }
+    if (typeof raw !== "string") {
+        return { ok: false, status: null, error: GENERIC_ERROR };
+    }
+    const trimmed = raw.trim();
+    return { ok: true, value: { base_branch: trimmed.length === 0 ? null : trimmed } };
+}
+const INDEX_SCOPE_FRESHNESS_VALUES = new Set([
+    "fresh",
+    "pending",
+    "blocked",
+    "failed",
+    "unavailable",
+    "unobserved_advance",
+]);
+/**
+ * Read the server's freshness verdict, failing CLOSED.
+ *
+ * An absent or unrecognized value becomes `null` rather than a guess, and every
+ * caller treats `null` as "not fresh". A malformed control-plane response must
+ * never be the thing that lets a conductor proceed against a stale index.
+ */
+function parseFreshnessStatus(value) {
+    return typeof value === "string" && INDEX_SCOPE_FRESHNESS_VALUES.has(value)
+        ? value
+        : null;
+}
+/**
+ * Read a soft envelope's refusal, or `null` when the body reports success.
+ *
+ * A body that is not an object at all is a refusal too: silently treating an
+ * unparseable response as success is how a cut gets recorded against a commit
+ * nobody verified.
+ */
+function softEnvelopeFailure(body) {
+    if (!isRecord(body))
+        return { ok: false, status: null, error: GENERIC_ERROR };
+    if (body["ok"] === true)
+        return null;
+    const error = typeof body["error"] === "string" && body["error"].length > 0 ? body["error"] : GENERIC_ERROR;
+    const message = typeof body["message"] === "string" && body["message"].length > 0 ? body["message"] : null;
+    return { ok: false, status: null, error: message ? `${error}: ${message}` : error };
+}
+/** Read a required string field, or `null` when it is absent or empty. */
+function requiredString(body, key) {
+    const value = body[key];
+    return typeof value === "string" && value.length > 0 ? value : null;
+}
+/**
+ * `POST /jira/index-scope/cut/begin` — lease a cut hold at the indexed commit.
+ *
+ * `candidateCommitSha` is the CLI's own preflight observation, sent as a
+ * cross-check. The server re-reads the canonical snapshot under the parse lock
+ * and refuses on disagreement, which is the "the index moved while I was
+ * checking" case the protocol re-drives rather than papers over.
+ */
+export async function beginIndexScopeCut(access, request, fetchImpl = globalThis.fetch) {
+    const result = await wrap(access, () => {
+        const url = buildConductorJiraUrl(access.baseUrl, "/index-scope/cut/begin");
+        return fetchConductorJsonPostWithTimeout(url, postHeaders(access), JSON.stringify({
+            repo_name: access.repoName,
+            feature_branch: request.featureBranch,
+            base_branch: request.baseBranch,
+            candidate_commit_sha: request.candidateCommitSha ?? null,
+            epic_run_id: request.epicRunId ?? null,
+        }), CONDUCTOR_FETCH_TIMEOUT_MS, fetchImpl);
+    });
+    if (!result.ok)
+        return result;
+    const refusal = softEnvelopeFailure(result.value);
+    if (refusal)
+        return refusal;
+    const body = result.value;
+    const cutHoldId = requiredString(body, "cut_hold_id");
+    const scopeId = requiredString(body, "scope_id");
+    const shadowRepoName = requiredString(body, "shadow_repo_name");
+    const cutCommitSha = requiredString(body, "cut_commit_sha");
+    if (!cutHoldId || !scopeId || !shadowRepoName || !cutCommitSha) {
+        // An `ok: true` body missing any of these is not a usable lease, and acting
+        // on a partial one would push a ref at `undefined`.
+        return { ok: false, status: null, error: GENERIC_ERROR };
+    }
+    return { ok: true, value: { cut_hold_id: cutHoldId, scope_id: scopeId, shadow_repo_name: shadowRepoName, cut_commit_sha: cutCommitSha } };
+}
+/**
+ * `POST /jira/index-scope/cut/commit` — record the immutable cut.
+ *
+ * `epicRefCommitSha` is what the CLI read back from `origin` AFTER creating the
+ * ref, not what it intended to create. The server proves the two agree.
+ */
+export async function commitIndexScopeCut(access, request, fetchImpl = globalThis.fetch) {
+    const result = await wrap(access, () => {
+        const url = buildConductorJiraUrl(access.baseUrl, "/index-scope/cut/commit");
+        return fetchConductorJsonPostWithTimeout(url, postHeaders(access), JSON.stringify({
+            repo_name: access.repoName,
+            scope_id: request.scopeId,
+            cut_hold_id: request.cutHoldId,
+            epic_ref_commit_sha: request.epicRefCommitSha,
+        }), CONDUCTOR_FETCH_TIMEOUT_MS, fetchImpl);
+    });
+    if (!result.ok)
+        return result;
+    const refusal = softEnvelopeFailure(result.value);
+    if (refusal)
+        return refusal;
+    const body = result.value;
+    const scopeId = requiredString(body, "scope_id");
+    const shadowRepoName = requiredString(body, "shadow_repo_name");
+    const cutCommitSha = requiredString(body, "cut_commit_sha");
+    if (!scopeId || !shadowRepoName || !cutCommitSha) {
+        return { ok: false, status: null, error: GENERIC_ERROR };
+    }
+    return {
+        ok: true,
+        value: {
+            scope_id: scopeId,
+            shadow_repo_name: shadowRepoName,
+            cut_commit_sha: cutCommitSha,
+            outcome: requiredString(body, "outcome"),
+        },
+    };
+}
+/**
+ * `POST /jira/index-scope/cut/abandon` — release this CLI's own cut hold.
+ *
+ * Called from `init`'s `finally` on every pre-seed outcome. Idempotent: a hold
+ * already released (or already reclaimed) still resolves successfully, so the
+ * cleanup path can never turn a primary failure into a second one.
+ */
+export async function abandonIndexScopeCut(access, request, fetchImpl = globalThis.fetch) {
+    const result = await wrap(access, () => {
+        const url = buildConductorJiraUrl(access.baseUrl, "/index-scope/cut/abandon");
+        return fetchConductorJsonPostWithTimeout(url, postHeaders(access), JSON.stringify({
+            repo_name: access.repoName,
+            scope_id: request.scopeId,
+            cut_hold_id: request.cutHoldId,
+        }), CONDUCTOR_FETCH_TIMEOUT_MS, fetchImpl);
+    });
+    if (!result.ok)
+        return result;
+    const refusal = softEnvelopeFailure(result.value);
+    if (refusal)
+        return refusal;
+    return { ok: true, value: true };
+}
+/**
+ * `POST /jira/index-scope/bootstrap` — seed the scope and drive its verifying
+ * parse.
+ *
+ * Accepted means SCHEDULED, never ready. Readiness is observed through
+ * {@link getIndexScopeStatus}, because the bootstrap copies a repository's whole
+ * parse cache and then runs a parse.
+ */
+export async function bootstrapIndexScope(access, request, fetchImpl = globalThis.fetch) {
+    const result = await wrap(access, () => {
+        const url = buildConductorJiraUrl(access.baseUrl, "/index-scope/bootstrap");
+        return fetchConductorJsonPostWithTimeout(url, postHeaders(access), JSON.stringify({ repo_name: access.repoName, scope_id: request.scopeId }), CONDUCTOR_FETCH_TIMEOUT_MS, fetchImpl);
+    });
+    if (!result.ok)
+        return result;
+    const refusal = softEnvelopeFailure(result.value);
+    if (refusal)
+        return refusal;
+    return { ok: true, value: true };
+}
+/** `GET /jira/index-scope/status?repo_name=&scope_id=` — the scope's own state. */
+export async function getIndexScopeStatus(access, scopeId, fetchImpl = globalThis.fetch) {
+    const result = await wrap(access, () => {
+        const url = buildConductorJiraUrl(access.baseUrl, "/index-scope/status", {
+            repo_name: access.repoName,
+            scope_id: scopeId,
+        });
+        return fetchConductorJsonWithTimeout(url, getHeaders(access), CONDUCTOR_FETCH_TIMEOUT_MS, fetchImpl);
+    });
+    if (!result.ok)
+        return result;
+    const refusal = softEnvelopeFailure(result.value);
+    if (refusal)
+        return refusal;
+    const body = result.value;
+    const resolvedScopeId = requiredString(body, "scope_id");
+    const shadowRepoName = requiredString(body, "shadow_repo_name");
+    const lifecycleState = requiredString(body, "lifecycle_state");
+    if (!resolvedScopeId || !shadowRepoName || !lifecycleState) {
+        return { ok: false, status: null, error: GENERIC_ERROR };
+    }
+    return {
+        ok: true,
+        value: {
+            scope_id: resolvedScopeId,
+            shadow_repo_name: shadowRepoName,
+            lifecycle_state: lifecycleState,
+            cut_commit_sha: nullableString(body["cut_commit_sha"]) ?? null,
+            required_commit_sha: nullableString(body["required_commit_sha"]) ?? null,
+            indexed_commit_sha: nullableString(body["indexed_commit_sha"]) ?? null,
+            seed_source_commit_sha: nullableString(body["seed_source_commit_sha"]) ?? null,
+            last_error: nullableString(body["last_error"]) ?? null,
+            freshness_status: parseFreshnessStatus(body["freshness_status"]),
+            blocked_reason: nullableString(body["blocked_reason"]) ?? null,
+        },
+    };
+}
+/**
+ * The bounded outcomes `POST /jira/index-scope/catch-up` may report (BAPI-932).
+ *
+ * Three are successes — the scope was behind and every replayed commit passed
+ * the gate (`repaired`); it was already current and nothing was written
+ * (`already_current`); it was pinned correctly but not yet indexed, so the
+ * existing scheduler was asked to re-drive the parse (`parse_scheduled`). The
+ * rest are refusals, and a refusal leaves both watermarks byte-identical.
+ */
+export const INDEX_SCOPE_CATCH_UP_OUTCOMES = [
+    "repaired",
+    "already_current",
+    "parse_scheduled",
+    "race_lost",
+    "blocked",
+    "history_limit_exceeded",
+    "refused_lifecycle",
+    "invalid_scope",
+    "unavailable",
+    // Route-minted, before the service is reached.
+    "unknown_index_scope",
+    "epic_shadow_index_lookup_failed",
+    "scope_does_not_belong_to_repository",
+];
+/**
+ * `POST /jira/index-scope/catch-up` — replay a scope's missed observations.
+ *
+ * Fails CLOSED in the same two ways the rest of this client does: a soft-envelope
+ * refusal becomes a `BridgeResult` failure, and an unrecognized `outcome` narrows
+ * to `null` rather than being passed through. A `null` outcome with `ok: true`
+ * cannot happen — an unrecognized success is downgraded to a failure, because
+ * "the server said something we do not understand" must never be read by a
+ * conductor as "the repair worked".
+ */
+export async function catchUpIndexScope(access, request, fetchImpl = globalThis.fetch) {
+    const result = await wrap(access, () => {
+        const url = buildConductorJiraUrl(access.baseUrl, "/index-scope/catch-up");
+        return fetchConductorJsonPostWithTimeout(url, postHeaders(access), JSON.stringify({ repo_name: access.repoName, scope_id: request.scopeId }), CONDUCTOR_FETCH_TIMEOUT_MS, fetchImpl);
+    });
+    if (!result.ok)
+        return result;
+    if (!isRecord(result.value))
+        return { ok: false, status: null, error: GENERIC_ERROR };
+    const body = result.value;
+    const rawOutcome = body["outcome"];
+    const outcome = typeof rawOutcome === "string" && INDEX_SCOPE_CATCH_UP_OUTCOMES.includes(rawOutcome)
+        ? rawOutcome
+        : null;
+    const ok = body["ok"] === true;
+    if (ok && outcome === null) {
+        // A success we cannot name is not a success we may act on.
+        return { ok: false, status: null, error: GENERIC_ERROR };
+    }
+    if (!ok && outcome === null) {
+        // A refusal we cannot name still refuses; surface the server's own error
+        // token when it gave one, exactly as the soft-envelope helper would.
+        const refusal = softEnvelopeFailure(body);
+        if (refusal)
+            return refusal;
+        return { ok: false, status: null, error: GENERIC_ERROR };
+    }
+    return {
+        ok: true,
+        value: {
+            ok,
+            outcome,
+            reason: nullableString(body["reason"]) ?? null,
+            required_commit_sha: nullableString(body["required_commit_sha"]) ?? null,
+            parse_scheduled: body["parse_scheduled"] === true,
+        },
+    };
+}
+function nullableNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+/**
+ * Read a boolean field, defaulting to the SAFE value rather than to `false`.
+ *
+ * The safe default differs per field and each caller passes it, because guessing
+ * uniformly would be wrong in both directions: an unreadable `lease_valid` must
+ * read as `true` (assume it is live, do not offer to reclaim it) while an
+ * unreadable `retention_elapsed` must read as `false` (assume the window has not
+ * passed).
+ */
+function booleanOr(value, fallback) {
+    return typeof value === "boolean" ? value : fallback;
+}
+function parseLifecycleEntry(value) {
+    if (!isRecord(value))
+        return null;
+    const scopeId = requiredString(value, "scope_id");
+    if (!scopeId)
+        return null;
+    const blockers = Array.isArray(value["blockers"])
+        ? value["blockers"].filter((entry) => typeof entry === "string")
+        : [];
+    return {
+        scope_id: scopeId,
+        shadow_repo_name: nullableString(value["shadow_repo_name"]) ?? null,
+        feature_branch: nullableString(value["feature_branch"]) ?? null,
+        epic_run_id: nullableString(value["epic_run_id"]) ?? null,
+        lifecycle_state: nullableString(value["lifecycle_state"]) ?? null,
+        lease_epoch: nullableNumber(value["lease_epoch"]),
+        lease_expires_at: nullableString(value["lease_expires_at"]) ?? null,
+        // Fail closed on each: an unreadable field must never make a scope look more
+        // reclaimable than it is.
+        lease_valid: booleanOr(value["lease_valid"], true),
+        retention_deadline: nullableString(value["retention_deadline"]) ?? null,
+        retention_elapsed: booleanOr(value["retention_elapsed"], false),
+        recoverable: booleanOr(value["recoverable"], false),
+        active_parse_run: booleanOr(value["active_parse_run"], true),
+        parse_lock_held: booleanOr(value["parse_lock_held"], true),
+        active_automation_run: booleanOr(value["active_automation_run"], true),
+        active_epic_run: booleanOr(value["active_epic_run"], true),
+        identity_valid: booleanOr(value["identity_valid"], false),
+        blockers,
+    };
+}
+/** `GET /jira/index-scope/lifecycle?repo_name=` — every scope this repo owns. */
+export async function getIndexScopeLifecycle(access, fetchImpl = globalThis.fetch) {
+    const result = await wrap(access, () => {
+        const url = buildConductorJiraUrl(access.baseUrl, "/index-scope/lifecycle", {
+            repo_name: access.repoName,
+        });
+        return fetchConductorJsonWithTimeout(url, getHeaders(access), CONDUCTOR_FETCH_TIMEOUT_MS, fetchImpl);
+    });
+    if (!result.ok)
+        return result;
+    const refusal = softEnvelopeFailure(result.value);
+    if (refusal)
+        return refusal;
+    const body = result.value;
+    const rawScopes = Array.isArray(body["scopes"]) ? body["scopes"] : [];
+    const scopes = [];
+    for (const raw of rawScopes) {
+        const parsed = parseLifecycleEntry(raw);
+        // A malformed entry is DROPPED rather than failing the whole listing: the
+        // listing is a diagnostic, and showing an operator four readable scopes plus
+        // nothing about a fifth beats showing them nothing at all.
+        if (parsed !== null)
+            scopes.push(parsed);
+    }
+    return {
+        ok: true,
+        value: { retention_seconds: nullableNumber(body["retention_seconds"]), scopes },
+    };
+}
+/** Shared parser for the three lease verbs, whose response shape is identical. */
+function toLeaseResult(body) {
+    const refusal = softEnvelopeFailure(body);
+    if (refusal)
+        return refusal;
+    const record = body;
+    const scopeId = requiredString(record, "scope_id");
+    if (!scopeId)
+        return { ok: false, status: null, error: GENERIC_ERROR };
+    return {
+        ok: true,
+        value: {
+            scope_id: scopeId,
+            lifecycle_state: nullableString(record["lifecycle_state"]) ?? null,
+            lease_epoch: nullableNumber(record["lease_epoch"]),
+            lease_expires_at: nullableString(record["lease_expires_at"]) ?? null,
+            already_retired: booleanOr(record["already_retired"], false),
+        },
+    };
+}
+async function postScopeLifecycle(access, path, body, fetchImpl) {
+    const result = await wrap(access, () => {
+        const url = buildConductorJiraUrl(access.baseUrl, path);
+        return fetchConductorJsonPostWithTimeout(url, postHeaders(access), JSON.stringify({ repo_name: access.repoName, ...body }), CONDUCTOR_FETCH_TIMEOUT_MS, fetchImpl);
+    });
+    if (!result.ok)
+        return result;
+    return toLeaseResult(result.value);
+}
+/** `POST /jira/index-scope/heartbeat` — renew the lease under `leaseEpoch`. */
+export async function heartbeatIndexScope(access, request, fetchImpl = globalThis.fetch) {
+    return postScopeLifecycle(access, "/index-scope/heartbeat", { scope_id: request.scopeId, lease_epoch: request.leaseEpoch }, fetchImpl);
+}
+/**
+ * `POST /jira/index-scope/recover` — take a new ownership generation.
+ *
+ * Deliberately sends NO epoch: recovery exists for the case where the caller has
+ * no valid one, and the server's increment is what fences the previous owner.
+ */
+export async function recoverIndexScope(access, request, fetchImpl = globalThis.fetch) {
+    return postScopeLifecycle(access, "/index-scope/recover", { scope_id: request.scopeId }, fetchImpl);
+}
+/** `POST /jira/index-scope/retire` — start retention; delete nothing. */
+export async function retireIndexScope(access, request, fetchImpl = globalThis.fetch) {
+    return postScopeLifecycle(access, "/index-scope/retire", { scope_id: request.scopeId, lease_epoch: request.leaseEpoch }, fetchImpl);
+}
+/**
+ * `POST /jira/index-scope/reclaim` — schedule the server-side teardown.
+ *
+ * There is deliberately no raw-deletion mode and no field that could name a
+ * namespace, table, or repository: the only knob is `overrideRetention`, which
+ * waives the two TIME blockers and nothing else. Everything actually deleted is
+ * derived server-side from the scope id.
+ *
+ * A refusal carries the server's ordered blocker tokens so the CLI can print WHY
+ * rather than a generic failure.
+ */
+export async function reclaimIndexScope(access, request, fetchImpl = globalThis.fetch) {
+    const result = await wrap(access, () => {
+        const url = buildConductorJiraUrl(access.baseUrl, "/index-scope/reclaim");
+        return fetchConductorJsonPostWithTimeout(url, postHeaders(access), JSON.stringify({
+            repo_name: access.repoName,
+            scope_id: request.scopeId,
+            override_retention: request.overrideRetention === true,
+        }), CONDUCTOR_FETCH_TIMEOUT_MS, fetchImpl);
+    });
+    if (!result.ok)
+        return result;
+    const refusal = softEnvelopeFailure(result.value);
+    if (refusal) {
+        const body = isRecord(result.value) ? result.value : {};
+        const blockers = Array.isArray(body["blockers"])
+            ? body["blockers"].filter((entry) => typeof entry === "string")
+            : undefined;
+        return blockers && blockers.length > 0 ? { ...refusal, blockers } : refusal;
+    }
+    const body = result.value;
+    return {
+        ok: true,
+        value: {
+            scope_id: nullableString(body["scope_id"]) ?? null,
+            scheduled: booleanOr(body["scheduled"], false),
+        },
+    };
+}
+/**
+ * Epic-run statuses that mean a v2 conductor may still be driving the run.
+ *
+ * These are the NON-TERMINAL members of the server's `EpicRunStatus` vocabulary
+ * (`api/models/epic_run.py`: `planning | pending_approval | active | blocked |
+ * abandoned | done`); only `abandoned` and `done` are terminal. `active` is the
+ * state a run spends nearly all of its life in, so omitting it would make this
+ * whole advisory silent for exactly the overlap it exists to surface.
+ *
+ * The vocabulary matters and is easy to get wrong: `running`/`queued` belong to
+ * `ExecutorJobStatusValue` and `paused` to `RunControlState`, and none of the
+ * three is ever an `epic_runs.status`. Status alone is not liveness either — the
+ * caller additionally requires an unexpired lease, so a `blocked` run whose lease
+ * has lapsed is correctly read as wreckage rather than as a live conductor.
+ */
+const ACTIVE_EPIC_RUN_STATUSES = [
+    "planning",
+    "pending_approval",
+    "active",
+    "blocked",
+];
+/**
+ * `GET /automation/health?repo_name=` — read-only parse-dispatcher liveness.
+ *
+ * Root-mounted, NOT under `/jira`. The response is narrowed to two safe fields;
+ * signals, stale-ticket samples, queue contents, and every timestamp are
+ * deliberately dropped — an advisory line needs a verdict, not a report.
+ *
+ * `absent` is claimed ONLY on positive evidence: a `stale` or `never_seen`
+ * heartbeat together with a responding process that is not itself sweeping.
+ * Every other shape — `unknown`, a missing field, a malformed body, any read
+ * failure — is `unavailable`.
+ */
+export async function getParseDispatcherHealth(access, fetchImpl = globalThis.fetch) {
+    const result = await wrap(access, () => {
+        const url = new URL(buildConductorVcsUrl(access.baseUrl, "/automation/health"));
+        url.searchParams.set("repo_name", access.repoName);
+        return fetchConductorJsonWithTimeout(url.toString(), getHeaders(access), CONDUCTOR_FETCH_TIMEOUT_MS, fetchImpl);
+    });
+    if (!result.ok)
+        return result;
+    if (!isRecord(result.value)) {
+        return {
+            ok: true,
+            value: { observation: "unavailable", heartbeatState: null, respondingSchedulerRunning: false },
+        };
+    }
+    const reconciler = isRecord(result.value["reconciler"]) ? result.value["reconciler"] : null;
+    const scheduler = isRecord(result.value["scheduler"]) ? result.value["scheduler"] : null;
+    const rawState = reconciler === null ? undefined : reconciler["state"];
+    const heartbeatState = typeof rawState === "string" ? rawState : null;
+    const respondingSchedulerRunning = scheduler !== null &&
+        scheduler["running"] === true &&
+        typeof scheduler["job_count"] === "number" &&
+        scheduler["job_count"] > 0;
+    let observation;
+    if (heartbeatState === "fresh" || respondingSchedulerRunning) {
+        observation = "observed";
+    }
+    else if (heartbeatState === "stale" || heartbeatState === "never_seen") {
+        observation = "absent";
+    }
+    else {
+        observation = "unavailable";
+    }
+    return { ok: true, value: { observation, heartbeatState, respondingSchedulerRunning } };
+}
+/**
+ * `GET /jira/epic-runs/runs?repo_name=` — live v2 conductor runs on THIS repo.
+ *
+ * Scoped by the authenticated repository identity carried on `access`; no caller
+ * ever names a repository here. Liveness is judged on the LEASE, not on the
+ * status alone: an `active` row whose lease expired is a crashed run, and calling
+ * that a concurrent conductor would make the advisory cry wolf on exactly the
+ * wreckage `recover` exists to clean up.
+ *
+ * Only `epic_key` and a controlled state survive into the result. Lease owners,
+ * run ids, policies, and timestamps are dropped.
+ */
+export async function getLiveRepositoryConductors(access, now, fetchImpl = globalThis.fetch) {
+    const result = await wrap(access, () => {
+        const url = buildConductorJiraUrl(access.baseUrl, "/epic-runs/runs", {
+            repo_name: access.repoName,
+        });
+        return fetchConductorJsonWithTimeout(url, getHeaders(access), CONDUCTOR_FETCH_TIMEOUT_MS, fetchImpl);
+    });
+    if (!result.ok)
+        return result;
+    if (!isRecord(result.value) || !Array.isArray(result.value["runs"])) {
+        return { ok: true, value: { observation: "unavailable", conductors: [] } };
+    }
+    const nowMs = now.getTime();
+    const conductors = [];
+    for (const entry of result.value["runs"]) {
+        if (!isRecord(entry))
+            continue;
+        const status = entry["status"];
+        if (typeof status !== "string" || !ACTIVE_EPIC_RUN_STATUSES.includes(status))
+            continue;
+        const leaseRaw = nullableString(entry["lease_expires_at"]);
+        if (typeof leaseRaw !== "string")
+            continue;
+        const leaseMs = Date.parse(leaseRaw);
+        if (!Number.isFinite(leaseMs) || leaseMs <= nowMs)
+            continue;
+        conductors.push({
+            kind: "v2",
+            epicKey: nullableString(entry["epic_key"]) ?? null,
+            state: status,
+            livenessSource: "lease",
+        });
+    }
+    return { ok: true, value: { observation: conductors.length > 0 ? "observed" : "absent", conductors } };
+}