@bridge_gpt/mcp-server 0.2.39 → 0.2.42

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/pr-state.js

@@ -8,9 +8,13 @@
  * `conductor/epic-runtime.ts#parsePrBindingFromGhJson` fails closed on any
  * non-`OPEN` state, which is correct for binding a merge action and exactly
  * wrong here, and importing it would pull the whole v1 runtime along. So this
- * module parses the same `gh pr view` payload with a different, terminal-state-
- * preserving contract, while REUSING the shared mergeability normalizer so a
- * conflict is classified identically everywhere.
+ * module parses `gh` PR records with a different, terminal-state-preserving
+ * contract, while REUSING the shared mergeability normalizer so a conflict is
+ * classified identically everywhere.
+ *
+ * The probe reads `gh pr list --head <branch>`, whose output is an ARRAY, and
+ * selects one record from it. `gh pr view` was replaced because it cannot
+ * express "no pull request" as anything but a non-zero exit (BAPI-825/B1).
  *
  * **Worktree discovery.** `/review-and-start` names branches
  * `feature/<KEY>-<slug>` and the loop cannot know the slug. When
@@ -24,8 +28,24 @@
  */
 import { isPrMergeConflict, parseGhPrMergeabilityFields } from "../conductor/github-mergeability.js";
 import { runGhCommand } from "../conductor/pr-discovery.js";
-/** The `gh pr view --json` field list the status contract fixes. */
+/**
+ * The `--json` field list the status contract fixes.
+ *
+ * Passed to `gh pr list` (BAPI-825/B1), which returns an ARRAY of records with
+ * exactly these keys. The name is retained because it is the published contract
+ * identifier and is asserted by name in the tests; only the subcommand changed.
+ */
 export const CONDUCT_EPIC_GH_PR_VIEW_FIELDS = "number,state,headRefOid,mergeable,mergeStateStatus,baseRefName,updatedAt";
+/**
+ * How many candidate pull requests the probe asks `gh` for.
+ *
+ * More than one, deliberately: a branch routinely carries a closed pull request
+ * plus a reopened one, and `--limit 1` would hand back whichever `gh` ordered
+ * first rather than letting {@link selectConductEpicPrState} prefer the OPEN
+ * one. Bounded so a branch with a long pull-request history cannot turn one
+ * probe into an unbounded read.
+ */
+export const CONDUCT_EPIC_GH_PR_LIST_LIMIT = 20;
 /** The accepted GitHub PR states. Terminal states are RETAINED, not filtered. */
 export const CONDUCT_EPIC_PR_STATES = ["OPEN", "MERGED", "CLOSED"];
 function isRecord(value) {
@@ -75,14 +95,57 @@ export function conductEpicPrHasConflict(pr) {
     return isPrMergeConflict({ mergeable: pr.mergeable, mergeStateStatus: pr.merge_state });
 }
 /**
- * Run `gh pr view <branch> --json …` and normalize the result.
+ * Choose the one pull request the loop acts on from `gh`'s candidate list.
+ *
+ * An OPEN pull request always wins: it is the only one any action row can
+ * advance, and a stale closed sibling must never displace it. Among terminal
+ * candidates the most recently updated wins, because that is the one whose
+ * MERGED or CLOSED state describes the branch's current reality.
+ *
+ * Deterministic when timestamps tie or are unavailable: a valid `updated_at`
+ * outranks an absent one, and source order breaks any remaining tie. A probe
+ * that returned a different pull request run-to-run for identical input would
+ * make every downstream row unreproducible.
+ */
+export function selectConductEpicPrState(candidates) {
+    if (candidates.length === 0)
+        return null;
+    const open = candidates.find((pr) => pr.state === "OPEN");
+    if (open)
+        return open;
+    let best = candidates[0];
+    for (const candidate of candidates.slice(1)) {
+        const bestAt = Date.parse(best.updated_at ?? "");
+        const candidateAt = Date.parse(candidate.updated_at ?? "");
+        const bestUsable = Number.isFinite(bestAt);
+        const candidateUsable = Number.isFinite(candidateAt);
+        // Strictly greater, so an equal timestamp keeps the earlier record and
+        // source order remains the final tie-breaker.
+        if (candidateUsable && (!bestUsable || candidateAt > bestAt))
+            best = candidate;
+    }
+    return best;
+}
+/**
+ * Run `gh pr list --head <branch> --state all --json …` and normalize the result.
  *
  * Nothing throws. The three outcomes are kept strictly apart:
  *
- * - **`ok`** — `gh` succeeded and returned a parseable PR record.
- * - **`none`** — `gh` SUCCEEDED and returned nothing. Confirmed absence.
+ * - **`ok`** — `gh` succeeded and returned at least one parseable PR record.
+ * - **`none`** — `gh` SUCCEEDED and returned an empty array. Confirmed absence.
  * - **`error`** — `gh` could not be run, exited non-zero, or returned output
- *   that is not a valid PR record. Unavailable evidence, not absence.
+ *   that is not a valid PR array. Unavailable evidence, not absence.
+ *
+ * **`gh pr list`, not `gh pr view` (BAPI-825/B1).** `gh pr view <branch>` prints
+ * `no pull requests found for branch "…"` to stderr and **exits 1** when the
+ * branch has no pull request, and `runGhCommand` discards stderr, so every
+ * pre-PR tick produced `{ok: false, stdout: ""}`. Under BAPI-814/B2's correct
+ * rule that a non-zero exit is a failed probe, `none` became unreachable in
+ * production: the loop saw `pr: null` PLUS a `probe_errors` entry on every tick
+ * before a worker opened its pull request, so the "no PR yet" rows could never
+ * fire and a worker that died early parked at the three-hour hard deadline
+ * instead of getting its one-hour respawn. `gh pr list` exits 0 with `[]`,
+ * which makes absence expressible without weakening the failure rule.
  *
  * Every `error` reason is a fixed bounded string chosen here. The raw output is
  * never included — a `gh` failure message can echo a URL, a token hint, or the
@@ -92,33 +155,43 @@ export async function discoverConductEpicPrState(branch, options = {}) {
     const runGh = options.runGh ?? runGhCommand;
     let result;
     try {
-        result = await runGh(["pr", "view", branch, "--json", CONDUCT_EPIC_GH_PR_VIEW_FIELDS], {
-            cwd: options.cwd,
-        });
+        result = await runGh([
+            "pr",
+            "list",
+            "--head",
+            branch,
+            "--state",
+            "all",
+            "--json",
+            CONDUCT_EPIC_GH_PR_VIEW_FIELDS,
+            "--limit",
+            String(CONDUCT_EPIC_GH_PR_LIST_LIMIT),
+        ], { cwd: options.cwd });
     }
     catch {
         return { kind: "error", reason: "the gh command could not be run" };
     }
     // A non-zero `gh` exit is a FAILED PROBE, never "no PR" (BAPI-814/B2).
     //
-    // `gh` exits non-zero both when the branch genuinely has no pull request and
-    // when it is unauthenticated, rate-limited, or offline, and this module
-    // deliberately does not parse its stderr to tell those apart. Reporting the
-    // ambiguity as absence is the dangerous half of that choice: the loop reads a
-    // GitHub outage as "no PR yet" and keeps waiting on a pull request it can no
-    // longer see. Reporting it as a failed probe is the safe half — the status
-    // contract turns that into `pr: null` PLUS a `probe_errors` entry, which the
-    // command treats as unavailable evidence rather than a negative result.
+    // `gh pr list` exits non-zero only when it could not answer — unauthenticated,
+    // rate-limited, offline, not a repository. Absence is now expressed as a
+    // successful `[]`, so nothing legitimate is lost by keeping this strict: the
+    // status contract turns an error into `pr: null` PLUS a `probe_errors` entry,
+    // which the command treats as unavailable evidence rather than a negative
+    // result.
     //
     // The reason is a FIXED string. `gh`'s own output can echo a URL, a token
     // hint, or the repository layout, so none of it is interpolated here.
     if (!result.ok)
         return { kind: "error", reason: "the gh command failed" };
-    // A SUCCESSFUL command with empty output is genuine absence: `gh` ran, looked,
-    // and found nothing. That stays distinct from the failure above.
+    // Empty stdout from a SUCCESSFUL `--json` run is malformed, not absence: the
+    // documented answer for "no pull requests" is the two bytes `[]`. Silence is
+    // a shape this command should never produce, and reading it as a confirmed
+    // negative is precisely the inference this module refuses to make.
     const raw = typeof result.stdout === "string" ? result.stdout.trim() : "";
-    if (raw.length === 0)
-        return { kind: "none" };
+    if (raw.length === 0) {
+        return { kind: "error", reason: "gh returned no output for a --json query" };
+    }
     let parsed;
     try {
         parsed = JSON.parse(raw);
@@ -126,7 +199,23 @@ export async function discoverConductEpicPrState(branch, options = {}) {
     catch {
         return { kind: "error", reason: "gh returned output that is not valid JSON" };
     }
-    const pr = parseConductEpicPrState(parsed);
+    if (!Array.isArray(parsed)) {
+        return { kind: "error", reason: "gh returned a PR list in an unexpected shape" };
+    }
+    // A successful, well-formed empty list is the ONLY confirmed absence.
+    if (parsed.length === 0)
+        return { kind: "none" };
+    const records = [];
+    for (const entry of parsed) {
+        const pr = parseConductEpicPrState(entry);
+        // An unusable record is a shape error, never silently dropped: discarding
+        // it could empty the list and turn a real pull request into "no PR".
+        if (pr === null) {
+            return { kind: "error", reason: "gh returned a PR record in an unexpected shape" };
+        }
+        records.push(pr);
+    }
+    const pr = selectConductEpicPrState(records);
     if (pr === null)
         return { kind: "error", reason: "gh returned a PR record in an unexpected shape" };
     return { kind: "ok", pr };

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

@@ -1078,6 +1078,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 +1183,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