@bridge_gpt/mcp-server 0.2.41 → 0.2.43

package/build/drive-epic.js

@@ -0,0 +1,375 @@
+/**
+ * `drive-epic` — the one universal conductor entry point (BAPI-887).
+ *
+ * Bridge has two conductors and a standing rule that they must never operate on
+ * the same epic: two transition authorities on one epic wedge it permanently.
+ *
+ *   - **v2 engine** — bootstrapped by `setup-epic`, which creates a durable
+ *     `epic_run` row, stores a plan DAG, and approves it.
+ *   - **LLM-conductor pilot** — `/loop 5m /conduct-epic <EPIC>`, which creates no
+ *     run row and keeps its whole memory in a local checkpoint plus GitHub.
+ *
+ * Asking a prompt to pick correctly every time is not a control. This subcommand
+ * makes the choice STRUCTURAL: it reads server-side conductor readiness and
+ * routes to exactly one path, so no prompt names either underlying conductor and
+ * no prompt can present both. Every ticket-authoring surface hands off to
+ * `drive-epic` and to nothing else.
+ *
+ * ## The output invariant
+ *
+ * Every branch — including every error path — emits **at most one** conductor
+ * invocation. An escalation carries NO alternative conductor command: "v2 failed,
+ * try the pilot instead" is precisely the dual-authority hazard this subcommand
+ * exists to remove. {@link assertSingleConductorInvocation} enforces this on the
+ * way out rather than trusting each branch to have got it right.
+ *
+ * ## Three-state routing, fail-closed
+ *
+ *   - readiness green            -> delegate to the `setup-epic` (v2) flow
+ *   - readiness read, not green  -> print the pilot instruction
+ *   - readiness UNKNOWN          -> escalate to the operator, print no conductor
+ *
+ * Unknown is never treated as not-ready, and selection never happens by
+ * exception handling. An unreachable, unauthorized, or malformed readiness
+ * response means we do not know which authority owns this epic, and guessing is
+ * the failure mode.
+ *
+ * ## Consolidation day
+ *
+ * Two conductors is a transitional state; one is to be eliminated at the end of
+ * the current evaluation period. Consolidation is:
+ *
+ *   1. set {@link DRIVE_EPIC_PREFERRED_CONDUCTOR} to the surviving conductor;
+ *   2. delete the losing branch in {@link renderConductorHandoff}.
+ *
+ * No prompt, bundled doc, command mirror, or posture test changes as a result —
+ * that is the whole reason the duality is confined to this one subcommand and
+ * this one constant. Epics already assigned to the eliminated conductor must be
+ * drained first; that drain is a conductor-lifecycle concern outside this file.
+ *
+ * No MCP tool is registered here. The `tools/list` token budget is deliberately
+ * ratcheted down, and a tool would be useless in a bare-chat session anyway,
+ * where the model has no tool call to make.
+ */
+import { resolveConductorBridgeApiAccess, fetchConductorReadiness, safeDiagnosticMessage, } from "./conductor/bridge-api-client.js";
+import { runSetupEpicCli } from "./setup-epic.js";
+// BAPI-806: mcp-identity.ts is the SOLE source of the package-name literal, so
+// the printed invocation interpolates it rather than repeating it.
+import { MCP_PACKAGE_NAME } from "./mcp-identity.js";
+/** Jira epic key shape. Matches `conduct-epic`'s positional rule exactly. */
+const EPIC_KEY_PATTERN = /^[A-Z]+-[0-9]+$/;
+/** The two conductor paths. Derived types below come from this constant. */
+export const DRIVE_EPIC_CONDUCTORS = ["v2", "pilot"];
+/**
+ * THE consolidation-day edit point.
+ *
+ * When readiness is green, v2 is preferred and the pilot is the fallback for
+ * projects that cannot run it. This is expressed as one named constant rather
+ * than as branching scattered through the routing logic precisely so that
+ * eliminating a conductor is a one-line change plus one deleted branch.
+ */
+export const DRIVE_EPIC_PREFERRED_CONDUCTOR = "v2";
+/**
+ * The v2 readiness predicate, as a list so a failure can name what is missing.
+ *
+ * These are the facts v2 actually needs to drive an epic: a stored supervisor
+ * posture, a reconciler that is ticking, a provisioned and live executor, and
+ * complete GitHub App credentials. Each is read from the SERVER's report and
+ * never re-derived locally — two implementations of one classification drift,
+ * and a CLI that disagreed with the server about whether v2 can run would be
+ * worse than no check at all.
+ */
+export const V2_READINESS_REQUIREMENTS = [
+    {
+        id: "supervisor_setup",
+        describe: "supervisor setup stored for this repository",
+        satisfied: (r) => r.supervisor.setup_present,
+    },
+    {
+        id: "supervisor_config",
+        describe: "supervisor configuration stored for this repository",
+        satisfied: (r) => r.supervisor.config_present,
+    },
+    {
+        id: "github_credentials",
+        describe: "GitHub App credentials that resolve completely",
+        satisfied: (r) => r.github.credentials_complete,
+    },
+    {
+        id: "reconciler_live",
+        describe: "a reconciler that is ticking and not stale",
+        satisfied: (r) => r.reconciler.liveness_readable && !r.reconciler.stale,
+    },
+    {
+        id: "executor_live",
+        describe: "an executor provisioned and reporting ready",
+        satisfied: (r) => r.executor.liveness_readable && r.executor.ready === true,
+    },
+];
+export function getDriveEpicUsage() {
+    return [
+        "Usage: mcp-server drive-epic [options] <EPIC>",
+        "",
+        "Drives one epic with the conductor this project can actually run. Reads",
+        "conductor readiness from Bridge API and routes to exactly one path — it",
+        "never asks you to choose.",
+        "",
+        "Arguments:",
+        "  <EPIC>                 Jira epic key, matches [A-Z]+-[0-9]+ (e.g. BAPI-885)",
+        "",
+        "Options:",
+        "  --plan-file <path>     Plan DAG sidecar. When supplied and the v2 path is",
+        "                         selected, drive-epic runs that bootstrap directly",
+        "                         instead of printing the command to run.",
+        "  --repo <name>          Repo name (default: BAPI_REPO_NAME or .bridge/config)",
+        "  -h, --help             Show this help",
+    ].join("\n");
+}
+/**
+ * Parse argv. Rejects malformed input BEFORE any side effect — no readiness
+ * read, no credential resolution, no delegation.
+ */
+export function parseDriveEpicArgs(argv) {
+    if (argv.includes("-h") || argv.includes("--help")) {
+        return { status: "help", usage: getDriveEpicUsage() };
+    }
+    const positionals = [];
+    let planFile;
+    let repo;
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === "--plan-file" || arg === "--repo") {
+            const value = argv[i + 1];
+            if (value === undefined || value.startsWith("-")) {
+                return { status: "error", message: `${arg} requires a value.` };
+            }
+            if (arg === "--plan-file")
+                planFile = value;
+            else
+                repo = value;
+            i++;
+            continue;
+        }
+        const eq = arg.match(/^(--plan-file|--repo)=(.*)$/);
+        if (eq) {
+            const value = eq[2];
+            if (value.trim().length === 0) {
+                return { status: "error", message: `${eq[1]} requires a value.` };
+            }
+            if (eq[1] === "--plan-file")
+                planFile = value;
+            else
+                repo = value;
+            continue;
+        }
+        if (arg.startsWith("-")) {
+            return { status: "error", message: `Unsupported flag: ${arg}` };
+        }
+        positionals.push(arg);
+    }
+    if (positionals.length === 0) {
+        return { status: "error", message: "Missing required epic key." };
+    }
+    if (positionals.length > 1) {
+        // Rejected rather than ignored: a second positional means the caller
+        // believes something we did not parse, and driving the wrong epic is not
+        // recoverable by re-reading the output.
+        return {
+            status: "error",
+            message: `Expected exactly one epic key, got ${positionals.length}: ${positionals.join(", ")}`,
+        };
+    }
+    const epicKey = positionals[0];
+    if (!EPIC_KEY_PATTERN.test(epicKey)) {
+        return { status: "error", message: `Malformed epic key '${epicKey}'. Expected e.g. BAPI-885.` };
+    }
+    const options = { epicKey, ...(planFile ? { planFile } : {}), ...(repo ? { repo } : {}) };
+    return { status: "ok", options };
+}
+/**
+ * Route a readiness report to exactly one conductor.
+ *
+ * Pure and total: it takes the already-read report and always returns a
+ * decision. The unknown case is produced by the caller, which is the only place
+ * that can observe a failed read — selection itself never happens by exception
+ * handling, and so never needs to report that it could not decide.
+ */
+export function selectConductor(readiness) {
+    const missing = V2_READINESS_REQUIREMENTS.filter((req) => !req.satisfied(readiness));
+    if (missing.length === 0) {
+        return {
+            kind: "selected",
+            conductor: DRIVE_EPIC_PREFERRED_CONDUCTOR,
+            reason: "conductor readiness is green",
+        };
+    }
+    return {
+        kind: "selected",
+        conductor: "pilot",
+        reason: `the engine path still needs ${missing.map((m) => m.describe).join("; ")}`,
+    };
+}
+/**
+ * Render the selected path and only the selected path.
+ *
+ * Precondition: the caller has already ruled out delegation. The `v2` branch
+ * reads as "green, but no plan file was supplied", which is only true once
+ * {@link runDriveEpicCli} has declined to delegate — so route first, render
+ * second.
+ *
+ * CONSOLIDATION DAY: delete the branch of the conductor being eliminated and
+ * point {@link DRIVE_EPIC_PREFERRED_CONDUCTOR} at the survivor. Nothing outside
+ * this file moves.
+ */
+export function renderConductorHandoff(selection, epicKey) {
+    if (selection.conductor === "v2") {
+        const invocation = `npx -y ${MCP_PACKAGE_NAME} drive-epic ${epicKey} --plan-file <path>`;
+        return {
+            conductor: "v2",
+            invocation,
+            lines: [
+                `${epicKey}: ${selection.reason}, but no plan file was supplied.`,
+                "",
+                "The engine path needs a plan DAG, and nothing derives one from an epic key:",
+                "the dependency edges and per-ticket touched_files it carries do not exist",
+                "anywhere else. Produce one, then re-run this command with it.",
+                "",
+                `  1. Run /plan-epic ${epicKey} in an interactive session. It writes the`,
+                "     sidecar to {docs_dir}/epic-plans/{epic_slug}/epic-plan.dag.json.",
+                "     If the epic's tickets already exist, run emit-conductor-bundle",
+                "     finalize instead — it resolves the placeholder keys in an existing",
+                "     sidecar and attaches touched_files.",
+                "",
+                `  2. ${invocation}`,
+                "",
+                `That second command bootstraps the run for you; ${SETUP_EPIC_SUBCOMMAND} is not`,
+                "something you invoke directly.",
+            ],
+        };
+    }
+    const invocation = `/loop 5m /conduct-epic ${epicKey}`;
+    return {
+        conductor: "pilot",
+        invocation,
+        lines: [
+            `${epicKey}: ${selection.reason}. Drive it from an interactive session with:`,
+            "",
+            `  ${invocation}`,
+        ],
+    };
+}
+/**
+ * Tokens that identify a conductor path in user-facing output. Used by the
+ * output guard and by its test — one list, so a new spelling cannot be added to
+ * the renderer without the guard seeing it.
+ */
+export const CONDUCTOR_INVOCATION_TOKENS = ["setup-epic", "conduct-epic"];
+/** The v2 token, named once so prose and the guard cannot drift apart. */
+const SETUP_EPIC_SUBCOMMAND = CONDUCTOR_INVOCATION_TOKENS[0];
+/**
+ * Fail closed if a rendered branch names more than one conductor.
+ *
+ * This is a guard, not decoration: the whole value of a single entry point is
+ * that a reader is never handed a choice, and a well-meaning "you could also
+ * try..." line added later would silently reintroduce the dual-authority
+ * hazard. Checking on the way out costs nothing and cannot be forgotten.
+ */
+export function assertSingleConductorInvocation(text) {
+    const named = CONDUCTOR_INVOCATION_TOKENS.filter((token) => text.includes(token));
+    if (named.length > 1) {
+        throw new Error(`drive-epic emitted more than one conductor invocation (${named.join(", ")}). ` +
+            "Exactly one path may ever be presented.");
+    }
+}
+export function createDefaultDriveEpicDeps() {
+    return {
+        resolveAccess: async (repo) => {
+            const result = await resolveConductorBridgeApiAccess(repo ? { repoName: repo } : {});
+            return result.ok ? { ok: true, access: result.access } : { ok: false, error: result.error };
+        },
+        readReadiness: (access) => fetchConductorReadiness(access, globalThis.fetch),
+        runSetupEpic: (argv) => runSetupEpicCli(argv),
+        // stdout is safe here: `drive-epic` is dispatched BEFORE MCP server
+        // construction, so nothing has claimed stdout for the protocol transport.
+        log: (message) => console.log(message),
+        errorLog: (message) => console.error(message),
+    };
+}
+/**
+ * Run the CLI. Returns `0` on a successful handoff and `1` on any validation,
+ * readiness, prerequisite, or execution failure. Never throws: the caller
+ * dispatches this at module top level, where an escaping exception would take
+ * down the process before any diagnostic reached the operator.
+ */
+export async function runDriveEpicCli(argv, overrides = {}) {
+    const deps = { ...createDefaultDriveEpicDeps(), ...overrides };
+    const parsed = parseDriveEpicArgs(argv);
+    if (parsed.status === "help") {
+        deps.log(parsed.usage);
+        return 0;
+    }
+    if (parsed.status === "error") {
+        deps.errorLog(parsed.message);
+        deps.errorLog("");
+        deps.errorLog(getDriveEpicUsage());
+        return 1;
+    }
+    const { epicKey, planFile, repo } = parsed.options;
+    try {
+        // --- Resolve access. A missing credential is UNKNOWN, not not-ready. -----
+        const accessResult = await deps.resolveAccess(repo);
+        if (!accessResult.ok) {
+            return escalate(deps, epicKey, `conductor readiness could not be read: ${accessResult.error}`);
+        }
+        // --- Read readiness. Any failure here is UNKNOWN. ------------------------
+        let readiness;
+        try {
+            readiness = await deps.readReadiness(accessResult.access);
+        }
+        catch (err) {
+            return escalate(deps, epicKey, `conductor readiness could not be read: ${safeDiagnosticMessage(err, "readiness request failed")}`);
+        }
+        // --- Route. Exactly one path from here on. -------------------------------
+        const selection = selectConductor(readiness);
+        // Decide delegation BEFORE rendering. The v2 branch's text is specifically
+        // about a missing plan file, and rendering it on the path that has one
+        // would produce a message contradicting what is about to happen.
+        if (selection.conductor === "v2" && planFile) {
+            // Delegate. `setup-epic` owns branch, run-row, plan, and approval
+            // behavior; drive-epic reimplements none of it and prints nothing of its
+            // own alongside it, so its output remains the only conductor output.
+            const setupArgv = ["--epic-key", epicKey, "--plan-file", planFile, ...(repo ? ["--repo", repo] : [])];
+            return await deps.runSetupEpic(setupArgv);
+        }
+        const handoff = renderConductorHandoff(selection, epicKey);
+        const text = handoff.lines.join("\n");
+        assertSingleConductorInvocation(text);
+        deps.log(text);
+        return 0;
+    }
+    catch (err) {
+        // Last resort. Sanitized, on stderr, converted to an exit code — a
+        // credential must never reach this line, and a stringified unknown is
+        // exactly how one escapes.
+        deps.errorLog(`drive-epic failed: ${safeDiagnosticMessage(err, "unexpected error")}`);
+        return 1;
+    }
+}
+/**
+ * The escalation branch. Prints NO conductor invocation at all — naming a
+ * fallback here is the dual-authority hazard, and an operator who does not know
+ * which authority owns an epic must not be nudged toward either one.
+ */
+function escalate(deps, epicKey, reason) {
+    const lines = [
+        `Cannot determine which conductor owns ${epicKey}: ${reason}`,
+        "",
+        "This is not a not-ready result — it is an unknown one, and starting the wrong",
+        "conductor on an epic wedges it permanently. Restore Bridge API access and run",
+        "drive-epic again, or ask an operator to resolve conductor readiness.",
+    ];
+    const text = lines.join("\n");
+    assertSingleConductorInvocation(text);
+    deps.errorLog(text);
+    return 1;
+}

package/build/executor/cli.js

@@ -14,6 +14,7 @@ import { DEFAULT_EXECUTOR_AGENT_ID } from "./agent-identity.js";
 import { createDefaultExecutorDeps } from "./deps.js";
 import { resolveBaseUrl, resolveExecutorApiAccess, EXECUTOR_BASE_URL_REQUIRED_MESSAGE, } from "./credentials.js";
 import { createExecutorHttpClient } from "./http-client.js";
+import { startExecutorSleepAssertion } from "./platform.js";
 import { runExecutor } from "./runner.js";
 import { runExecutorWatchCli } from "./watch-cli.js";
 /** Fixed executor timing/behavior defaults. */
@@ -210,6 +211,21 @@ export function parseExecutorArgs(argv, context) {
     };
     return { kind: "ok", options };
 }
+/**
+ * Default signal registrar: `process.on`, disposed with `process.off`.
+ *
+ * The SAME register-and-return-an-unsubscriber shape the notifications CLI and
+ * the plane supervisor already use. Defined here rather than inside `runExecutor`
+ * so the runner never touches `process` itself — the runner stays a pure loop
+ * over injected boundaries, and this bootstrap file remains the one place that
+ * knows the process object exists.
+ */
+function defaultSignalRegistrar(signal, handler) {
+    process.on(signal, handler);
+    return () => {
+        process.off(signal, handler);
+    };
+}
 function hasRepoFlag(argv) {
     return argv.some((a) => a === "--repo" || a === "--repos" || a.startsWith("--repos="));
 }
@@ -306,12 +322,43 @@ export async function runExecutorCli(argv, overrides = {}) {
     // Hand the loop the VALIDATED runtime configuration: the parsed options plus the
     // normalized base URL resolution actually settled on.
     const runtimeOptions = { ...options, resolvedBaseUrl };
+    // --- Sleep assertion (BAPI-828) ---------------------------------------
+    // Started HERE — after argument parsing, base-URL resolution, credential
+    // resolution, and HTTP client construction have all succeeded, and immediately
+    // before the loop begins. That position is the whole design: it guarantees the
+    // assertion exists before the first claim can spawn a worker, while a `--help`
+    // run, an unknown flag, a missing base URL, and a credential failure each
+    // return above without ever spawning `caffeinate`. Fail-open throughout — a
+    // host that cannot hold the assertion still claims and still works.
+    const sleepAssertion = startExecutorSleepAssertion({
+        platform: context.platform,
+        // The EXECUTOR's environment, read straight from deps. A worker environment
+        // never reaches this call, and the opt-out is never forwarded to one.
+        env: deps.env,
+        cwd: deps.cwd,
+        executorPid: context.pid,
+        spawnProcess: deps.spawnProcess,
+        setTimer: deps.setTimer,
+        clearTimer: deps.clearTimer,
+        errorLog,
+    });
+    const runnerSeams = {
+        onSignal: overrides.onSignal ?? defaultSignalRegistrar,
+    };
     try {
-        return await run(runtimeOptions, deps, httpClient);
+        return await run(runtimeOptions, deps, httpClient, runnerSeams);
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
         errorLog(`Error: executor exited unexpectedly: ${message.slice(0, 200)}`);
         return 1;
     }
+    finally {
+        // Released for a normal completion, a graceful signal shutdown, AND a thrown
+        // runner error alike. Without the `finally` the throw path above would return
+        // its exit code while still holding a `caffeinate` child — which, being a
+        // live child of this process, is exactly the kind of thing that keeps a Node
+        // process from exiting when nobody calls `process.exit`.
+        await sleepAssertion.release();
+    }
 }

package/build/executor/env.js

@@ -40,6 +40,7 @@
  * (`Read(~/.config/bridge/**)` in `permissions.ts`).
  */
 import { PR_BASE_BRANCH_ENV_VAR } from "../pr-base-contract.js";
+import { INDEX_SCOPE_ENV_VAR, validateOptionalIndexScope } from "../index-scope-contract.js";
 /** Non-secret operational keys forwarded to the worker when present. */
 const ALLOWED_ENV_KEYS = [
     "PATH",
@@ -92,6 +93,14 @@ export const EXPLICIT_DENY_KEYS = [
     "GH_TOKEN",
     "CLAUDE_CONFIG_DIR",
     "XDG_CONFIG_HOME",
+    // BAPI-844: the index-scope declaration follows the BAPI_BASE_BRANCH rule —
+    // absent from ALLOWED_ENV_KEYS so it is never copied from `parentEnv`, and
+    // denied EXPLICITLY here so an operator's ambient `BAPI_INDEX_SCOPE` can never
+    // reach a worker. A worker's research index is a run-scoped decision; a value
+    // exported in the shell that happened to launch the executor is not that
+    // decision, and inheriting one would route an unscoped worker's plan and review
+    // at another epic's shadow index while nothing in the job said so.
+    INDEX_SCOPE_ENV_VAR,
 ];
 /**
  * True only when `key` is a safe, allowlisted operational key. Exported so the
@@ -130,10 +139,22 @@ export function buildExecutorBaseWorkerEnv(parentEnv, options = {}) {
         }
     }
     env.BRIDGE_SKIP_PREPUSH = "1";
+    env.MAX_MCP_OUTPUT_TOKENS = "50000";
     if (typeof options.effectiveBaseBranch === "string" &&
         options.effectiveBaseBranch.length > 0) {
         env[PR_BASE_BRANCH_ENV_VAR] = options.effectiveBaseBranch;
     }
+    // BAPI-844: the index-scope declaration, set ONLY from the explicit option and
+    // only after the shared shape check. A malformed explicit value throws here —
+    // before an environment exists — rather than being dropped: silently omitting it
+    // would spawn a worker that researches the canonical index while the job it came
+    // from declared a scope, which is the one outcome the declaration exists to
+    // prevent. An absent option adds no key at all, so the returned object is
+    // unchanged for every unscoped worker.
+    const indexScope = validateOptionalIndexScope(options.indexScope);
+    if (indexScope !== undefined) {
+        env[INDEX_SCOPE_ENV_VAR] = indexScope;
+    }
     // Nothing agent-specific is added here, and deliberately nothing secret. An
     // adapter that needs to forward an operator-owned credential declares it as a
     // passthrough and copies it onto the object this function returns; see

package/build/executor/http-client.js

@@ -34,6 +34,45 @@ function parseStopRequested(bodyText) {
         return false;
     }
 }
+/**
+ * The claim response header carrying server-derived dispatcher liveness
+ * (BAPI-871). Exported so the client and its tests name it once.
+ */
+export const RECONCILER_LIVENESS_HEADER = "X-BAPI-Reconciler-Liveness";
+/** The only values the server is documented to send. */
+const RECONCILER_LIVENESS_VALUES = [
+    "fresh",
+    "stale",
+    "never_seen",
+    "unknown",
+];
+/**
+ * Read the liveness header off a claim response, admitting ONLY documented
+ * values.
+ *
+ * Absent, blank, or unrecognized all map to `unknown` — the compatibility path.
+ * An executor talking to a backend from before this header existed must keep
+ * claiming exactly as it did, and "I have no verdict" is what `unknown` means.
+ * A value the server never promised is treated the same way rather than being
+ * passed through: an unrecognized string reaching the runner's availability
+ * logic could silently become a fifth state nobody handles.
+ *
+ * Header lookup is case-insensitive via `Headers.get`, which is required by the
+ * spec — HTTP header names are not case-sensitive, and proxies do re-case them.
+ */
+export function parseReconcilerLivenessHeader(headers) {
+    let raw = null;
+    try {
+        raw = headers.get(RECONCILER_LIVENESS_HEADER);
+    }
+    catch {
+        return "unknown";
+    }
+    const value = (raw ?? "").trim().toLowerCase();
+    return RECONCILER_LIVENESS_VALUES.includes(value)
+        ? value
+        : "unknown";
+}
 /**
  * Map a mutation (heartbeat/complete/fail) HTTP response onto the fencing
  * outcome. `allowInvalidResult` maps 422 to `invalid_job_result` (complete only).
@@ -68,7 +107,9 @@ export function createExecutorHttpClient(config) {
             body: JSON.stringify(body),
         });
         const text = await res.text();
-        return { status: res.status, text };
+        // `headers` is surfaced (optional, so the many response fakes that omit it
+        // stay assignable) purely for the claim path's liveness annotation.
+        return { status: res.status, text, headers: res.headers };
     }
     async function mutate(pathSuffix, body, allowInvalidResult, repoName) {
         try {
@@ -85,24 +126,33 @@ export function createExecutorHttpClient(config) {
         async claim(manifest) {
             let status;
             let text;
+            let reconcilerLiveness = "unknown";
             try {
                 const res = await post("/claim", manifest, manifest.repo_name);
                 status = res.status;
                 text = res.text;
+                // Parsed on EVERY response, then attached only to the successful
+                // variants below. A response fake that omits `headers` degrades to
+                // `unknown` rather than throwing.
+                if (res.headers)
+                    reconcilerLiveness = parseReconcilerLivenessHeader(res.headers);
             }
             catch (err) {
                 const message = err instanceof Error ? err.message : String(err);
                 return { kind: "retryable", error: `claim network error: ${boundedDetail(message)}` };
             }
+            // Both successful outcomes carry the verdict. Nothing about the liveness
+            // value changes the classification below: a 204 is still "no job", and the
+            // retryable/fatal split is untouched.
             if (status === 204)
-                return { kind: "none" };
+                return { kind: "none", reconcilerLiveness };
             if (status === 200) {
                 try {
                     const job = JSON.parse(text);
                     if (!job || typeof job !== "object" || typeof job.claim_token !== "string") {
                         return { kind: "fatal", error: "claim returned a malformed job payload" };
                     }
-                    return { kind: "claimed", job };
+                    return { kind: "claimed", job, reconcilerLiveness };
                 }
                 catch {
                     return { kind: "fatal", error: "claim returned invalid JSON" };
@@ -142,6 +192,24 @@ export function createExecutorHttpClient(config) {
                 result.stop_requested = true;
             return result;
         },
+        /**
+         * Publish per-process liveness (BAPI-871).
+         *
+         * Authenticated with the manifest's PRIMARY repo key. The server verifies
+         * every entry in `repo_names` before writing anything, so a key that does not
+         * hold one of them gets a 4xx — reported here as `failed` and nothing more.
+         * Delivery is non-critical monitoring: it never throws, never classifies a
+         * fencing outcome, and never stops the caller from claiming or running work.
+         */
+        async processHeartbeat(request) {
+            try {
+                const { status, text } = await post("/process-heartbeat", request, request.repo_names[0] ?? "");
+                return status >= 200 && status < 300 && isOkBody(text) ? "delivered" : "failed";
+            }
+            catch {
+                return "failed";
+            }
+        },
         complete(job, completion) {
             return mutate(`/${job.id}/complete`, {
                 repo_name: job.repo_name,

package/build/executor/index-scope.js

@@ -0,0 +1,39 @@
+/**
+ * Per-job index-scope resolution (BAPI-844).
+ *
+ * The server names the index scope a v2 job's worker must research against, as
+ * the top-level `index_scope_id` on the claimed job — the same wire position as
+ * `epic_run_id`, and for the same reason: it is a server-minted IDENTITY, not
+ * job-type-specific payload data. There is exactly one wire representation, and
+ * this module is the only place the executor reads it.
+ *
+ * Mirrors {@link ../executor/base-branch.ts} deliberately, including its posture:
+ *
+ * - ABSENT → an unscoped job. The worker's environment, command, and routing are
+ *   byte-identical to the pre-BAPI-844 ones.
+ * - PRESENT and well-formed → carried into the worker environment as an explicit
+ *   spawn option (never inherited).
+ * - PRESENT but malformed → a contract failure, resolved BEFORE any side effect.
+ *   Dropping it instead would spawn a worker that silently researched the
+ *   canonical index while the job it came from declared a scope.
+ */
+import { validateOptionalIndexScope } from "../index-scope-contract.js";
+/**
+ * Resolve the declared index scope for one executor job.
+ *
+ * The diagnostic names the contract only. The submitted value never appears in
+ * it, because this string reaches `/fail`, the job row, and operator output —
+ * all places an opaque routing token must not be persisted.
+ */
+export function resolveExecutorJobIndexScope(job) {
+    try {
+        const indexScope = validateOptionalIndexScope(job.index_scope_id);
+        return indexScope === undefined ? { ok: true } : { ok: true, indexScope };
+    }
+    catch {
+        return {
+            ok: false,
+            error: "job index_scope_id is present but is not a valid index-scope identity.",
+        };
+    }
+}

package/build/executor/job-errors.js

@@ -20,6 +20,14 @@
  *    opened a PR whose base branch is not the run base, so `claude-review.yml`
  *    (triggered only on `branches: [main]`) never fires and the `code_review`
  *    gate would hang forever; see `worker-finalization.ts`.
+ *  - `WorkerFinalizationPrNotAttached` — an implementation-style job (BAPI-862)
+ *    exited cleanly and its exact HEAD is durable on origin, but no usable pull
+ *    request exists for that branch: none is visible, its URL is blank, its
+ *    description is blank (BAPI-824 folded in), or it does not yet carry the
+ *    pushed head. The work is COMPLETE and PUSHED — only the attachment is
+ *    missing — so this kind is deliberately distinct from every other
+ *    finalization failure, and its guidance names attachment and warns against
+ *    deleting or rebasing the branch; see `worker-finalization.ts`.
  *  - `WorkerFinalizationSavedButUnfinalized` — an implementation-style job
  *    (BAPI-762) exited cleanly, and an origin branch exists at an authoritative
  *    tip that does NOT match the worker's own HEAD — durable work exists on
@@ -98,6 +106,7 @@ export const WorktreeLostBeforePush = "WorktreeLostBeforePush";
 export const BranchMismatch = "BranchMismatch";
 export const WorkerFinalizationMissingRemoteBranchAndPr = "WorkerFinalizationMissingRemoteBranchAndPr";
 export const WorkerFinalizationPrBaseMismatch = "WorkerFinalizationPrBaseMismatch";
+export const WorkerFinalizationPrNotAttached = "WorkerFinalizationPrNotAttached";
 export const WorkerFinalizationSavedButUnfinalized = "WorkerFinalizationSavedButUnfinalized";
 export const WorkerConfigIsolation = "ContractError.WorkerConfigIsolation";
 export const PreSpawnVerification = "ContractError.PreSpawnVerification";