@bridge_gpt/mcp-server 0.2.41 → 0.2.43

package/build/conduct-epic/cut-protocol.js

@@ -0,0 +1,327 @@
+/**
+ * The shared EXACT-CUT protocol and scope-readiness poll (BAPI-843; BAPI-850).
+ *
+ * Extracted from `conduct-epic init` so that the LLM-conductor pilot and the v2
+ * `setup-epic --feature-branch` entry point drive ONE implementation of the
+ * local cut — the same local `git` fetch, the same remote-ref existence check,
+ * the same exact-SHA push, and the same mismatch classification. This module is
+ * the single owner of those operations; neither CLI re-implements any of them.
+ *
+ * What the cut is: the server leases a hold on the canonical parse lock and
+ * names the commit the canonical index actually covers (`cut/begin`); this
+ * module creates `origin/<feature>` at EXACTLY that commit with the operator's
+ * own `git` — never the GitHub App, which is `contents: read` and cannot create
+ * refs — reads the ref back, and asks the server to record it as the scope's
+ * immutable cut (`cut/commit`). The hold is released on every outcome.
+ *
+ * Contract properties, fixed here and relied on by both CLIs:
+ *
+ * - **Never force-updates an existing branch.** The push refspec has no leading
+ *   `+`, so it can only create. A branch that already exists at any commit other
+ *   than the held cut commit is a refusal, never a repoint.
+ * - **Takes an already validated branch and SHA.** Callers validate the branch
+ *   name (`validateBranchName`) and normalize the candidate SHA before calling;
+ *   this module re-proves the SHA shape it pushes, but it is not a parser.
+ * - **No credential ever reaches argv.** The only subprocess is `git`, and its
+ *   arguments are refs, remotes, and SHAs. Bridge and GitHub credentials travel
+ *   only inside the typed client's headers.
+ * - **Every failure is classified, never thrown.** Callers get a discriminated
+ *   outcome with operator-ready sentences and the bounded facts (expected and
+ *   observed SHAs) they need to report; there is nothing to `try/catch`.
+ */
+import { execFile } from "node:child_process";
+import { abandonIndexScopeCut, beginIndexScopeCut, commitIndexScopeCut, getIndexScopeStatus, } from "./bridge-client.js";
+/**
+ * Poll bound for a scope bootstrap, shared by `conduct-epic init` and
+ * `setup-epic`. A seed copies a repository's whole parse cache and the
+ * verifying parse then downloads and change-detects it, so the ceiling is
+ * generous; the interval is what keeps the poll cheap.
+ */
+export const SCOPE_BOOTSTRAP_POLL_INTERVAL_MS = 5_000;
+export const SCOPE_BOOTSTRAP_MAX_POLLS = 240; // ~20 minutes at the interval above.
+/**
+ * Build the default list-argument subprocess runner both CLIs use for `git`.
+ *
+ * One body rather than two copies: `execFile` with `shell: false`, a generous
+ * buffer for porcelain output, and an exit code that never throws — a missing
+ * binary resolves to a non-zero code the caller classifies.
+ */
+export function createExecFileRunCommand() {
+    return (file, args, options) => new Promise((resolve) => {
+        execFile(file, args, {
+            cwd: options?.cwd,
+            // Git porcelain output for a many-worktree checkout can be large.
+            maxBuffer: 16 * 1024 * 1024,
+            encoding: "utf-8",
+            timeout: options?.timeoutMs,
+            // Explicit: arguments are a list, never a concatenated shell string.
+            shell: false,
+        }, (error, stdout, stderr) => {
+            const code = error?.code;
+            resolve({
+                stdout: stdout ?? "",
+                stderr: stderr ?? "",
+                exitCode: typeof code === "number" ? code : error ? 1 : 0,
+            });
+        });
+    });
+}
+/** Run `git` in the operator's checkout. */
+export function runGit(deps, args) {
+    return Promise.resolve(deps.runCommand("git", args, { cwd: deps.cwd }));
+}
+/** The single trimmed line a `git rev-parse`-style command produced, or null. */
+export function firstOutputLine(result) {
+    const value = result.stdout.split("\n")[0]?.trim() ?? "";
+    return value.length === 0 ? null : value;
+}
+/** The SHA from `git ls-remote --heads origin <ref>` output, or null. */
+export function lsRemoteSha(result) {
+    const line = firstOutputLine(result);
+    if (line === null)
+        return null;
+    const sha = line.split(/\s+/)[0]?.trim() ?? "";
+    return sha.length === 0 ? null : sha;
+}
+/**
+ * Normalize a commit SHA to its canonical 40-character lowercase form, or `null`.
+ *
+ * Mirrors the server's own guard so a malformed value is refused HERE — before it
+ * becomes a `git push` refspec — rather than becoming an opaque git error or, far
+ * worse, a ref pushed at something that is not a commit.
+ */
+export function normalizeCommitSha(value) {
+    if (typeof value !== "string")
+        return null;
+    const normalized = value.trim().toLowerCase();
+    return /^[0-9a-f]{40}$/.test(normalized) ? normalized : null;
+}
+/**
+ * Read the head of `origin/<branch>` WITHOUT mutating anything.
+ *
+ * `sha: null` means the branch does not exist on origin. A failed `ls-remote`
+ * (no remote, no network, no git) is its own outcome, never "absent": treating an
+ * unanswered read as absence is how a push lands on top of a branch nobody saw.
+ */
+export async function readRemoteBranchHead(deps, branch) {
+    const result = await runGit(deps, ["ls-remote", "--heads", "origin", `refs/heads/${branch}`]);
+    if (result.exitCode !== 0) {
+        return { ok: false, error: `git ls-remote could not read origin/${branch}.` };
+    }
+    return { ok: true, sha: lsRemoteSha(result) };
+}
+/**
+ * Make sure the exact cut object is resolvable locally, fetching it if needed.
+ *
+ * The cut is pushed BY SHA, so the object must exist in the operator's
+ * repository. A base-branch fetch usually brings it along; when it did not — the
+ * index covers a commit that is no longer an ancestor of the base tip — one
+ * targeted, NON-MUTATING fetch of that SHA is attempted (it updates no ref,
+ * creates no branch, and checks nothing out). Returns `true` when the commit
+ * resolves.
+ */
+export async function ensureCommitResolvableLocally(deps, commitSha) {
+    const present = await runGit(deps, ["rev-parse", "--verify", "--quiet", `${commitSha}^{commit}`]);
+    if (present.exitCode === 0)
+        return true;
+    await runGit(deps, ["fetch", "origin", commitSha]);
+    const retry = await runGit(deps, ["rev-parse", "--verify", "--quiet", `${commitSha}^{commit}`]);
+    return retry.exitCode === 0;
+}
+/**
+ * Drive the exact cut: `cut/begin` → re-check the remote ref under the hold →
+ * create the ref at the held commit (if absent) → read it back → `cut/commit`,
+ * releasing the hold on EVERY outcome.
+ *
+ * Everything between `begin` and the release happens while the SERVER holds the
+ * canonical repository's parse lock, so the commit the index covers cannot move
+ * underneath the ref this module creates.
+ */
+export async function performExactIndexScopeCut(deps, access, request) {
+    const { featureBranch, baseBranch, candidateCommitSha } = request;
+    const lease = await beginIndexScopeCut(access, {
+        featureBranch,
+        baseBranch,
+        candidateCommitSha,
+        epicRunId: request.epicRunId ?? null,
+    }, deps.fetchImpl);
+    if (!lease.ok) {
+        return {
+            ok: false,
+            kind: "begin_refused",
+            failures: [`The index-scope cut could not begin: ${lease.error}`],
+            lease: null,
+            expectedSha: candidateCommitSha,
+            observedSha: null,
+        };
+    }
+    const cut = lease.value;
+    try {
+        if (cut.cut_commit_sha !== candidateCommitSha) {
+            // The server re-read the canonical snapshot under its own hold and named a
+            // different commit. Nothing has been pushed yet, so refusing costs nothing
+            // and continuing would cut the epic at a commit the preflight never checked.
+            return {
+                ok: false,
+                kind: "canonical_moved",
+                failures: [
+                    `The canonical index moved while init was preparing ` +
+                        `(preflight saw ${candidateCommitSha}, the cut hold names ${cut.cut_commit_sha}). Re-run init.`,
+                ],
+                lease: cut,
+                expectedSha: candidateCommitSha,
+                observedSha: cut.cut_commit_sha,
+            };
+        }
+        // Re-check `origin/<feature>` WHILE the hold is active. A preflight
+        // observation is evidence for a refusal, never for a mutation: another
+        // operator may have created the ref in between.
+        const held = await readRemoteBranchHead(deps, featureBranch);
+        if (!held.ok) {
+            return {
+                ok: false,
+                kind: "ls_remote_failed",
+                failures: [held.error],
+                lease: cut,
+                expectedSha: cut.cut_commit_sha,
+                observedSha: null,
+            };
+        }
+        const heldSha = held.sha;
+        if (heldSha !== null && heldSha !== cut.cut_commit_sha) {
+            return {
+                ok: false,
+                kind: "existing_ref_mismatch",
+                failures: [
+                    `origin/${featureBranch} exists at ${heldSha}, which is not the canonical indexed ` +
+                        `commit ${cut.cut_commit_sha}. Delete it or finish the previous run first.`,
+                ],
+                lease: cut,
+                expectedSha: cut.cut_commit_sha,
+                observedSha: heldSha,
+            };
+        }
+        let branchCreated = false;
+        if (heldSha === null) {
+            // Create the ref from the EXACT commit, with the operator's own git. No
+            // local checkout, no branch, no worktree — and deliberately not the GitHub
+            // App, which is `contents: read` and cannot create refs. Not a force push:
+            // the refspec has no leading `+`, so it can only create.
+            const pushed = await runGit(deps, [
+                "push",
+                "origin",
+                `${cut.cut_commit_sha}:refs/heads/${featureBranch}`,
+            ]);
+            if (pushed.exitCode !== 0) {
+                return {
+                    ok: false,
+                    kind: "push_failed",
+                    failures: [
+                        `Could not create origin/${featureBranch} at the canonical indexed commit ${cut.cut_commit_sha}.`,
+                    ],
+                    lease: cut,
+                    expectedSha: cut.cut_commit_sha,
+                    observedSha: null,
+                };
+            }
+            branchCreated = true;
+        }
+        // Read the ref BACK from origin. What matters is what the remote now holds,
+        // not what this process intended to push.
+        const confirmed = await readRemoteBranchHead(deps, featureBranch);
+        const confirmedSha = confirmed.ok ? confirmed.sha : null;
+        if (confirmedSha !== cut.cut_commit_sha) {
+            return {
+                ok: false,
+                kind: "confirm_failed",
+                failures: [`origin/${featureBranch} did not resolve to ${cut.cut_commit_sha} after the push.`],
+                lease: cut,
+                expectedSha: cut.cut_commit_sha,
+                observedSha: confirmedSha,
+            };
+        }
+        const committed = await commitIndexScopeCut(access, { scopeId: cut.scope_id, cutHoldId: cut.cut_hold_id, epicRefCommitSha: confirmedSha }, deps.fetchImpl);
+        if (!committed.ok) {
+            return {
+                ok: false,
+                kind: "commit_refused",
+                failures: [`The index-scope cut could not be recorded: ${committed.error}`],
+                lease: cut,
+                expectedSha: cut.cut_commit_sha,
+                observedSha: confirmedSha,
+            };
+        }
+        return { ok: true, lease: cut, branchCreated, outcome: committed.value.outcome };
+    }
+    finally {
+        // The hold is released on EVERY pre-seed outcome, including the success path
+        // (where the server already released it — abandon is idempotent). The seed
+        // acquires this same canonical lock itself and it is not reentrant, so
+        // handing off while still holding it would deadlock the epic against its own
+        // seed. A failed release never masks the primary failure: it is reported and
+        // the original outcome stands.
+        const abandoned = await abandonIndexScopeCut(access, { scopeId: cut.scope_id, cutHoldId: cut.cut_hold_id }, deps.fetchImpl);
+        if (!abandoned.ok) {
+            deps.errorLog(`announced: the cut hold could not be released cleanly: ${abandoned.error}`);
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Scope-readiness poll (BAPI-843; shared with `setup-epic` by BAPI-850)
+// ---------------------------------------------------------------------------
+/** The operator-facing label for each lifecycle state the poll reports. */
+export const SCOPE_LIFECYCLE_LABELS = Object.freeze({
+    provisioning: "Provisioning",
+    seeding: "Seeding",
+    verifying: "Verifying",
+    ready: "Ready",
+    failed: "Failed",
+});
+/**
+ * Poll a scope's lifecycle until it is `ready`, `failed`, or the bounded wait
+ * elapses, reporting each NEWLY observed lifecycle transition exactly once, in
+ * order, through `onTransition`.
+ *
+ * Readiness is a server-side fact this poll observes rather than concludes from
+ * any request of its own: `ready` is accepted ONLY when the status also proves
+ * `indexed_commit_sha == cut_commit_sha`. A `ready` whose watermark disagrees is
+ * reported as `ready_mismatch` — the control plane contradicting itself, which
+ * is worth refusing rather than proceeding on.
+ *
+ * A transient read failure is not a verdict: the poll keeps going and lets the
+ * bound be the thing that gives up. The interval and cap are the shared
+ * {@link SCOPE_BOOTSTRAP_POLL_INTERVAL_MS} / {@link SCOPE_BOOTSTRAP_MAX_POLLS}.
+ */
+export async function pollIndexScopeLifecycle(deps, access, scopeId, options = {}) {
+    const sleep = deps.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const maxPolls = options.maxPolls ?? SCOPE_BOOTSTRAP_MAX_POLLS;
+    const intervalMs = options.intervalMs ?? SCOPE_BOOTSTRAP_POLL_INTERVAL_MS;
+    let lastState = "unknown";
+    let lastStatus = null;
+    let lastReportedState = null;
+    for (let poll = 0; poll < maxPolls; poll += 1) {
+        await sleep(intervalMs);
+        const status = await getIndexScopeStatus(access, scopeId, deps.fetchImpl);
+        if (!status.ok) {
+            lastState = `unreadable (${status.error})`;
+            continue;
+        }
+        lastStatus = status.value;
+        lastState = status.value.lifecycle_state;
+        if (lastState !== lastReportedState) {
+            lastReportedState = lastState;
+            options.onTransition?.(lastState, status.value);
+        }
+        if (lastState === "ready") {
+            if (status.value.indexed_commit_sha !== null &&
+                status.value.indexed_commit_sha === status.value.cut_commit_sha) {
+                return { kind: "ready", status: status.value };
+            }
+            return { kind: "ready_mismatch", status: status.value };
+        }
+        if (lastState === "failed") {
+            return { kind: "failed", status: status.value, reason: status.value.last_error ?? "unknown" };
+        }
+    }
+    return { kind: "timeout", lastState, lastStatus };
+}

package/build/conduct-epic/spawn.js

@@ -21,6 +21,7 @@
  *   argv would be visible to every process on the machine via `ps`.
  */
 import { powershellSquote, shSquoteInner, } from "../start-tickets.js";
+import { INDEX_SCOPE_ENV_VAR } from "../index-scope-contract.js";
 /** The agents `conduct-epic spawn` may launch. */
 export const CONDUCT_EPIC_AGENTS = ["claude", "cursor-agent"];
 /** The repository's established default agent. */
@@ -52,6 +53,11 @@ export function resolveConductEpicAgent(agent) {
  * Returns the command as a string rather than an argv array because that is what
  * every terminal spawner in this repository consumes — a tab is opened by handing
  * a shell a command line, not by `exec`ing a process.
+ *
+ * BAPI-844: a validated `indexScope` is prefixed as an environment assignment
+ * using the SAME quoting helpers as the rest of the command — the shell's own
+ * environment mechanism, not an argument the agent can see. An absent scope emits
+ * no prefix, so the unscoped command is unchanged byte-for-byte.
  */
 export function buildConductEpicAgentCommand(input) {
     const resolved = resolveConductEpicAgent(input.agent);
@@ -61,15 +67,21 @@ export function buildConductEpicAgentCommand(input) {
         return { ok: false, error: "A worktree path is required to build the agent command." };
     }
     if (input.platform === "win32") {
+        const scopePrefix = input.indexScope
+            ? `$env:${INDEX_SCOPE_ENV_VAR} = ${powershellSquote(input.indexScope)}; `
+            : "";
         return {
             ok: true,
-            command: `Set-Location -LiteralPath ${powershellSquote(input.worktreePath)}; ` +
+            command: `${scopePrefix}Set-Location -LiteralPath ${powershellSquote(input.worktreePath)}; ` +
                 `${resolved.agent} ${powershellSquote(input.prompt)}`,
         };
     }
+    const scopePrefix = input.indexScope
+        ? `export ${INDEX_SCOPE_ENV_VAR}='${shSquoteInner(input.indexScope)}' && `
+        : "";
     return {
         ok: true,
-        command: `cd '${shSquoteInner(input.worktreePath)}' && ` +
+        command: `${scopePrefix}cd '${shSquoteInner(input.worktreePath)}' && ` +
             `${resolved.agent} '${shSquoteInner(input.prompt)}'`,
     };
 }

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

@@ -214,6 +214,20 @@ export function extractSanitizedErrorDiagnostics(body) {
         diagnostics.errorCode = boundedErrorPreview(errorCode);
     if (message)
         diagnostics.bodyPreview = boundedErrorPreview(message);
+    // BAPI-872: extract the allowlisted stale-CAS `current_row_version`, from
+    // either the nested `detail` object or (defensively) the top level. Only a
+    // genuine non-negative safe integer is accepted — never a boolean (JS has no
+    // strict-int check, so `Number.isSafeInteger` alone would still accept `1`
+    // but not `true`), never a string, never negative — so a malformed value can
+    // never be mistaken for a usable CAS conflict downstream.
+    const rawCurrentRowVersion = detail && typeof detail === "object" && !Array.isArray(detail)
+        ? detail["current_row_version"]
+        : record["current_row_version"];
+    if (typeof rawCurrentRowVersion === "number" &&
+        Number.isSafeInteger(rawCurrentRowVersion) &&
+        rawCurrentRowVersion >= 0) {
+        diagnostics.currentRowVersion = rawCurrentRowVersion;
+    }
     return diagnostics;
 }
 /** Redact exact secret substrings (e.g. the API key from the request headers). */
@@ -231,6 +245,10 @@ function redactDiagnosticValues(diagnostics, secrets) {
         out.errorCode = scrub(diagnostics.errorCode);
     if (diagnostics.bodyPreview)
         out.bodyPreview = scrub(diagnostics.bodyPreview);
+    // A number has nothing to scrub; carried through unchanged (BAPI-872).
+    if (typeof diagnostics.currentRowVersion === "number") {
+        out.currentRowVersion = diagnostics.currentRowVersion;
+    }
     return out;
 }
 /**
@@ -267,6 +285,13 @@ export class ConductorBridgeApiError extends Error {
     status;
     errorCode;
     bodyPreview;
+    /**
+     * The stale-CAS `current_row_version` (BAPI-872), when the backend supplied
+     * one. Deliberately NOT interpolated into `.message` (unlike `bodyPreview`) —
+     * every recovery CLI surface must never print a row-version value, and callers
+     * that need it read this field directly.
+     */
+    currentRowVersion;
     constructor(kindOrMessage, status, diagnostics) {
         const isKnownKind = CONDUCTOR_BRIDGE_API_ERROR_KINDS.includes(kindOrMessage);
         const errorCode = diagnostics?.errorCode;
@@ -293,6 +318,9 @@ export class ConductorBridgeApiError extends Error {
             this.errorCode = errorCode;
         if (bodyPreview)
             this.bodyPreview = bodyPreview;
+        if (typeof diagnostics?.currentRowVersion === "number") {
+            this.currentRowVersion = diagnostics.currentRowVersion;
+        }
     }
 }
 /**
@@ -873,6 +901,27 @@ export async function updateEpicRunStatus(access, request, fetchImpl = globalThi
     const parsed = await fetchConductorJsonPatchWithTimeout(url, conductorPostHeaders(access), body, CONDUCTOR_FETCH_TIMEOUT_MS, fetchImpl);
     return parsed;
 }
+/**
+ * POST `/jira/epic-runs/runs/{epic_run_id}/stop` — the operator emergency brake
+ * (BAPI-732, wired to the conductor CLI in BAPI-872). Idempotent: a repeated stop
+ * returns HTTP 200 with `committed: false`; a terminal run (`done`/`abandoned`)
+ * returns a `409 RUN_TERMINAL` conflict, which surfaces as a thrown
+ * {@link ConductorBridgeApiError} with `status: 409` and `errorCode: "RUN_TERMINAL"`.
+ * Transport/auth/server failures throw a sanitized {@link ConductorBridgeApiError}.
+ */
+export async function stopEpicRun(access, request, fetchImpl = globalThis.fetch) {
+    requireNonEmptyString(request.epicRunId);
+    const url = buildConductorJiraUrl(access.baseUrl, `${epicRunApiPath(request.epicRunId)}/stop`);
+    const body = JSON.stringify({
+        repo_name: access.repoName,
+        ...(request.reason !== undefined ? { reason: request.reason } : {}),
+        ...(request.expectedGeneration !== undefined
+            ? { expected_generation: request.expectedGeneration }
+            : {}),
+    });
+    const parsed = await fetchConductorJsonPostWithTimeout(url, conductorPostHeaders(access), body, CONDUCTOR_FETCH_TIMEOUT_MS, fetchImpl);
+    return parsed;
+}
 // ---------------------------------------------------------------------------
 // Per-ticket CAS status advancement
 // ---------------------------------------------------------------------------
@@ -937,6 +986,78 @@ export async function advanceEpicTicketStatus(access, request, fetchImpl = globa
     const parsed = await fetchConductorJsonPatchWithTimeout(url, conductorPostHeaders(access), body, CONDUCTOR_FETCH_TIMEOUT_MS, fetchImpl);
     return parseAdvanceEpicTicketStatusResult(parsed);
 }
+// ---------------------------------------------------------------------------
+// Operator recovery: ticket unpark + adopt-current-head-and-unpark (BAPI-872)
+// ---------------------------------------------------------------------------
+/**
+ * Catch a stale-CAS 400 thrown by the POST transport and translate it into the
+ * SAME `{ok: false, kind: "cas-conflict", current_row_version}` result
+ * {@link parseAdvanceEpicTicketStatusResult} already produces for the PATCH CAS
+ * endpoint — the previously dormant conflict branch that now becomes production
+ * behavior for both unpark lanes. Only a genuine stale-CAS shape (400 status with
+ * a validated `currentRowVersion`) is translated; every other failure re-throws
+ * unchanged, preserving `ConductorBridgeApiError` for terminal, validation,
+ * authorization, and transport failures.
+ */
+async function postUnparkLikeRequest(url, headers, body, fetchImpl) {
+    try {
+        const parsed = await fetchConductorJsonPostWithTimeout(url, headers, body, CONDUCTOR_FETCH_TIMEOUT_MS, fetchImpl);
+        return parseAdvanceEpicTicketStatusResult(parsed);
+    }
+    catch (err) {
+        if (err instanceof ConductorBridgeApiError &&
+            err.status === 400 &&
+            typeof err.currentRowVersion === "number") {
+            return parseAdvanceEpicTicketStatusResult({
+                ok: false,
+                kind: "cas-conflict",
+                current_row_version: err.currentRowVersion,
+            });
+        }
+        throw err;
+    }
+}
+/**
+ * POST `/jira/epic-runs/runs/{epic_run_id}/tickets/{ticket_key}/unpark` — move a
+ * parked `needs_human` ticket back into its gate machine (BAPI-536, wired to the
+ * conductor CLI in BAPI-872). A stale `expectedRowVersion` surfaces as the
+ * discriminated `{ok: false, kind: "cas-conflict", current_row_version}` result
+ * rather than a thrown error, so a bounded caller-side retry can re-read state and
+ * try again without special-casing an exception.
+ */
+export async function unparkEpicTicket(access, request, fetchImpl = globalThis.fetch) {
+    requireNonEmptyString(request.epicRunId);
+    requireNonEmptyString(request.ticketKey);
+    requireNonNegativeSafeInteger(request.expectedRowVersion);
+    const url = buildConductorJiraUrl(access.baseUrl, `${epicRunApiPath(request.epicRunId)}/tickets/${encodeURIComponent(request.ticketKey)}/unpark`);
+    const body = JSON.stringify({
+        repo_name: access.repoName,
+        expected_row_version: request.expectedRowVersion,
+        ...(request.idempotencyKey !== undefined ? { idempotency_key: request.idempotencyKey } : {}),
+        ...(request.reason !== undefined ? { reason: request.reason } : {}),
+    });
+    return postUnparkLikeRequest(url, conductorPostHeaders(access), body, fetchImpl);
+}
+/**
+ * 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
+ * ticket's anchored `expected_head_sha` (BAPI-571 B3, wired to the conductor CLI
+ * in BAPI-872). Same CAS-conflict/result shape as {@link unparkEpicTicket}; shares
+ * {@link parseAdvanceEpicTicketStatusResult} rather than a second parser.
+ */
+export async function adoptCurrentHeadAndUnparkTicket(access, request, fetchImpl = globalThis.fetch) {
+    requireNonEmptyString(request.epicRunId);
+    requireNonEmptyString(request.ticketKey);
+    requireNonNegativeSafeInteger(request.expectedRowVersion);
+    const url = buildConductorJiraUrl(access.baseUrl, `${epicRunApiPath(request.epicRunId)}/tickets/${encodeURIComponent(request.ticketKey)}/adopt-current-head-and-unpark`);
+    const body = JSON.stringify({
+        repo_name: access.repoName,
+        expected_row_version: request.expectedRowVersion,
+        ...(request.idempotencyKey !== undefined ? { idempotency_key: request.idempotencyKey } : {}),
+        ...(request.reason !== undefined ? { reason: request.reason } : {}),
+    });
+    return postUnparkLikeRequest(url, conductorPostHeaders(access), body, fetchImpl);
+}
 /**
  * Idempotently seed an epic ticket status row via POST to the per-epic tickets
  * endpoint. The backend uses ON CONFLICT DO NOTHING so repeated seeding across
@@ -1078,6 +1199,13 @@ function parseShadowDispatchFreshnessResult(parsed) {
         indexedCommitSha: typeof obj.indexed_commit_sha === "string" ? obj.indexed_commit_sha : null,
         shadowRepoName: typeof obj.shadow_repo_name === "string" ? obj.shadow_repo_name : null,
         lastError: typeof obj.last_error === "string" ? obj.last_error : null,
+        // Fail closed: only an explicit `true` expires a deadline. An older backend
+        // that does not send the field at all keeps the previous behavior (hold
+        // forever on this side, bounded by the Python reconciler's own park).
+        deadlineExpired: obj.deadline_expired === true,
+        blockedAdvanceReason: typeof obj.blocked_advance_reason === "string" && obj.blocked_advance_reason.length > 0
+            ? obj.blocked_advance_reason
+            : null,
     };
 }
 /**
@@ -1176,7 +1304,26 @@ function parseValidateEpicPlanResult(parsed) {
         insertedEdges < 0) {
         throw new ConductorBridgeApiError("server");
     }
-    return { planHash, serializationEnabled, insertedEdges };
+    // BAPI-848 — the coverage diagnostics are read TOLERANTLY, unlike the fields
+    // above. A server that predates them is not a protocol error, and the CLI must
+    // keep working against one; the defaults below are the honest reading of an
+    // absent field (nothing reported), and the renderer states the scope it was
+    // actually given rather than inventing coverage it cannot see.
+    return {
+        planHash,
+        serializationEnabled,
+        insertedEdges,
+        overlappingPairsFound: safeCount(p["overlapping_pairs_found"]),
+        undeclaredNodes: safeCount(p["undeclared_nodes"]),
+        undeclaredPairsSkipped: safeCount(p["undeclared_pairs_skipped"]),
+        coverageScope: typeof p["coverage_scope"] === "string" && p["coverage_scope"].trim() !== ""
+            ? p["coverage_scope"]
+            : "unreported",
+    };
+}
+/** Non-negative safe integer, or 0 for anything else (absent field included). */
+function safeCount(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : 0;
 }
 /**
  * POST the immutable plan blob to the durable-store endpoint. The blob is