@bridge_gpt/mcp-server 0.2.36 → 0.2.38

package/build/executor/env.js

@@ -13,9 +13,10 @@
  * FRESH object from a strict allowlist of non-secret operational keys — it
  * never copies arbitrary `process.env`, so credentials/tokens/headers cannot
  * leak into the spawned `claude` process. The `mcp-invoke` shim (a separate
- * process) resolves `BAPI_API_KEY` itself at call time from
- * `~/.config/bridge/credentials.json` — this worker environment never carries
- * it.
+ * process) resolves `BAPI_API_KEY` itself at call time from the credential
+ * store under the worker's redirected `XDG_CONFIG_HOME` — the executor seeds a
+ * repo-scoped store into the per-job isolation directory (see
+ * `worker-config-isolation.ts`) — so this worker environment never carries it.
  */
 import { PR_BASE_BRANCH_ENV_VAR } from "../pr-base-contract.js";
 /** Non-secret operational keys forwarded to the worker when present. */
@@ -31,12 +32,19 @@ const ALLOWED_ENV_KEYS = [
     "LANG",
     "LC_ALL",
     "TERM",
-    "XDG_CONFIG_HOME",
     "NO_COLOR",
 ];
 /** Substrings that mark a key as secret-bearing (case-insensitive). */
 const SECRET_NAME_FRAGMENTS = ["TOKEN", "SECRET", "PASSWORD", "API_KEY"];
-/** Explicit deny-list of known secret / MCP / conductor keys. */
+/**
+ * Explicit deny-list of known secret / MCP / conductor keys.
+ *
+ * BAPI-731 adds the two Claude configuration paths. They are denied on the
+ * INHERITED-COPY path and then set explicitly from executor-computed values
+ * below, following the `BAPI_BASE_BRANCH` precedent — an operator's
+ * `CLAUDE_CONFIG_DIR` or `XDG_CONFIG_HOME` must never be able to redirect a
+ * worker back at the operator's own configuration and undo isolation.
+ */
 const EXPLICIT_DENY_KEYS = [
     "BRIDGE_MCP_PROFILE",
     "CONDUCTOR_NODE_PATH",
@@ -45,6 +53,8 @@ const EXPLICIT_DENY_KEYS = [
     "OPENAI_API_KEY",
     "GITHUB_TOKEN",
     "GH_TOKEN",
+    "CLAUDE_CONFIG_DIR",
+    "XDG_CONFIG_HOME",
 ];
 /**
  * True only when `key` is a safe, allowlisted operational key. Exported so the
@@ -72,24 +82,7 @@ export function isExecutorEnvKeyAllowed(key) {
         return false;
     return true;
 }
-/**
- * Build the secret-free worker environment: a fresh object containing only the
- * allowlisted keys that are present (and non-undefined) in `parentEnv`, plus the
- * literal `BRIDGE_SKIP_PREPUSH=\"1\"` (BAPI-551). This is a constant, never read
- * from `parentEnv` — the worker's advisory local pre-push suite (~70s) is
- * redundant for a conductor worker, since its PR is CI-gated by the merge gate
- * anyway, and the delay was observed causing a worker to background the push and
- * exit before it landed. `BAPI_CONDUCTOR_*` identity keys remain intentionally
- * absent from the worker env (TDD §7) — this literal does not change that.
- *
- * BAPI-586: when `effectiveBaseBranch` is provided (the validated run base for
- * this job), it is injected as `BAPI_BASE_BRANCH` so the worker can run
- * `gh pr create --base "$BAPI_BASE_BRANCH"` deterministically. It is set from the
- * EXPLICIT job value, NOT copied from `parentEnv` (`BAPI_BASE_BRANCH` is not in
- * the allowlist), so any inherited value cannot override the run base and no
- * unrelated `BAPI_*` / secret value can leak in via this key.
- */
-export function buildExecutorWorkerEnv(parentEnv, effectiveBaseBranch) {
+export function buildExecutorWorkerEnv(parentEnv, options = {}) {
     const env = {};
     for (const key of ALLOWED_ENV_KEYS) {
         if (!isExecutorEnvKeyAllowed(key))
@@ -100,8 +93,41 @@ export function buildExecutorWorkerEnv(parentEnv, effectiveBaseBranch) {
         }
     }
     env.BRIDGE_SKIP_PREPUSH = "1";
-    if (typeof effectiveBaseBranch === "string" && effectiveBaseBranch.length > 0) {
-        env[PR_BASE_BRANCH_ENV_VAR] = effectiveBaseBranch;
+    if (typeof options.effectiveBaseBranch === "string" &&
+        options.effectiveBaseBranch.length > 0) {
+        env[PR_BASE_BRANCH_ENV_VAR] = options.effectiveBaseBranch;
+    }
+    // --- Worker config isolation (BAPI-731) --------------------------------
+    // Both paths are assigned from EXPLICIT executor-computed values and are on
+    // `EXPLICIT_DENY_KEYS`, so the inherited-copy loop above can never supply them.
+    // That ordering is the isolation guarantee: an operator `CLAUDE_CONFIG_DIR` or
+    // `XDG_CONFIG_HOME` cannot redirect the worker back at the operator's own
+    // configuration (and its `projects[...].mcpServers` map).
+    if (typeof options.claudeConfigDir === "string" && options.claudeConfigDir.length > 0) {
+        env.CLAUDE_CONFIG_DIR = options.claudeConfigDir;
+    }
+    if (typeof options.xdgConfigHome === "string" && options.xdgConfigHome.length > 0) {
+        env.XDG_CONFIG_HOME = options.xdgConfigHome;
+    }
+    // The ONE deliberately-injected credential, and a genuine exception to this
+    // module's otherwise absolute secret-free rule. It is injected because
+    // isolation REMOVES the worker's previous authentication path: a worker used to
+    // authenticate as a side effect of inheriting the operator's `HOME` and
+    // `~/.claude.json`, and that inheritance is exactly the defect being closed.
+    // Per the measured inventory (`docs/claude/claude-cli-config-isolation-inventory.md`,
+    // finding 4) an operator OAuth/subscription login does NOT follow an isolated
+    // `CLAUDE_CONFIG_DIR`, while `ANTHROPIC_API_KEY` does — so this is the only
+    // supported way an isolated worker can authenticate at all.
+    //
+    // It is passed from an EXPLICIT executor-resolved value rather than copied
+    // (`ANTHROPIC_API_KEY` remains on `EXPLICIT_DENY_KEYS` and still matches the
+    // `API_KEY` secret fragment), so it travels only when the isolation strategy
+    // deliberately supplies it, never as ambient leakage. Nothing writes it to
+    // disk: the only file seeded into the isolated directory is the repo-scoped
+    // Bridge credential store (see `worker-config-isolation.ts`), which never
+    // carries the Anthropic key.
+    if (typeof options.anthropicApiKey === "string" && options.anthropicApiKey.length > 0) {
+        env.ANTHROPIC_API_KEY = options.anthropicApiKey;
     }
     return env;
 }

package/build/executor/heartbeat.js

@@ -12,40 +12,83 @@
  *
  * After abandonment the loop stops all further heartbeat / telemetry / mutation
  * work so `runClaimedJob` never reports success after losing ownership.
+ *
+ * BAPI-731 adds two behaviors, neither of which may weaken the above:
+ *
+ *  - PUSH-TRIGGERED PROMPTNESS (WS-H). The loop samples the LOCAL
+ *    remote-tracking marker for the job's branch on a short sub-interval tick.
+ *    When the marker first appears or changes, the worker has pushed, so the
+ *    loop flushes one immediate heartbeat instead of waiting up to a full
+ *    interval. This is TELEMETRY ONLY (R14): the marker is never persisted, never
+ *    reported as `last_commit_sha`, and never drives an executor decision — the
+ *    reconciler remains the sole consumer and the sole transition authority
+ *    (`docs/claude/conductor-standing-rules.md`).
+ *
+ *  - SERVER STOP (WS-B executor half). A heartbeat response carrying the
+ *    server's stop request kills the owned worker like `stale_claim` does, but
+ *    reports a DISTINCT outcome so the runner can send a server-cancelled
+ *    terminal report rather than classifying a deliberate cancellation as a
+ *    worker crash. Inert until the reconciler ticket ships the field.
+ *
+ * Every heartbeat — initial, periodic, and push-triggered — goes through the ONE
+ * `sendHeartbeat` path below, so requests can never overlap or arrive out of
+ * order.
  */
 import { killOwnedProcess } from "./process.js";
+import { normalizeHeartbeatResult } from "./types.js";
 /**
- * Run the heartbeat loop until the worker is done or ownership is abandoned. The
- * FIRST heartbeat fires promptly (no initial interval wait).
+ * How often the push detector samples the local remote-tracking ref. Bounded
+ * well under the heartbeat interval so a push is noticed promptly, and it is a
+ * purely local `git rev-parse` (no network), so the cost is negligible.
+ */
+export const PUSH_DETECT_INTERVAL_MS = 5_000;
+/**
+ * Run the heartbeat loop until the worker is done, ownership is abandoned, or
+ * the server requests a stop. The FIRST heartbeat fires promptly (no initial
+ * interval wait).
  */
 export async function runHeartbeatLoop(params) {
     const { job, httpClient, options, deps, ownership, proc, observation } = params;
-    let first = true;
-    while (!ownership.abandoned && !params.isDone()) {
-        if (!first) {
-            await deps.sleep(options.heartbeatIntervalMs);
-            if (ownership.abandoned || params.isDone())
-                break;
-        }
-        first = false;
+    const pushDetectIntervalMs = params.pushDetectIntervalMs ?? PUSH_DETECT_INTERVAL_MS;
+    // Baseline for push detection. `undefined` means "not yet sampled": the FIRST
+    // successful sample only establishes the baseline and never itself triggers a
+    // flush, so a branch that was already pushed before this loop started does not
+    // manufacture a spurious immediate beat.
+    let remoteMarker;
+    let remoteBaselineEstablished = false;
+    /**
+     * The single heartbeat send path. Returns the loop outcome when the beat is
+     * terminal, or `null` to continue. Never called concurrently with itself:
+     * every caller awaits it before doing anything else.
+     */
+    const sendHeartbeat = async () => {
         const git = await params.collectTelemetry();
         observation.setGitTelemetry(git);
         const residue = observation.snapshot();
-        const outcome = await httpClient.heartbeat(job, {
+        const result = normalizeHeartbeatResult(await httpClient.heartbeat(job, {
+            // Unconditionally the LOCAL head — never the remote marker. This is what
+            // preserves the BAPI-704 semantic that a zero-commit job reports the base
+            // SHA paired with `local_commit_count: 0`.
             local_commit_count: git.local_commit_count,
             last_commit_sha: git.last_commit_sha,
             telemetry: residue,
-        });
-        if (outcome === "updated") {
+        }));
+        // Checked BEFORE the outcome switch: a stop request is authoritative even
+        // when it rides along with a non-`updated` outcome.
+        if (result.stop_requested === true) {
+            killOwnedProcess(proc, "server_stop");
+            return { kind: "server_stop" };
+        }
+        if (result.outcome === "updated") {
             ownership.lastSuccessfulHeartbeatAt = deps.now();
-            continue;
+            return null;
         }
-        if (outcome === "stale_claim") {
+        if (result.outcome === "stale_claim") {
             // Definitive dead claim: kill the worker and stop touching the worktree.
             killOwnedProcess(proc, "stale_claim");
             ownership.abandoned = true;
             ownership.abandonReason = "stale_claim";
-            break;
+            return { kind: "abandoned" };
         }
         // retry_later / fatal_http_error: keep the worker alive within the dead-man
         // window; SIGKILL + abandon once 2 minutes pass without a successful beat.
@@ -53,7 +96,85 @@ export async function runHeartbeatLoop(params) {
             killOwnedProcess(proc, "deadman");
             ownership.abandoned = true;
             ownership.abandonReason = "deadman";
-            break;
+            return { kind: "abandoned" };
+        }
+        return null;
+    };
+    /**
+     * Wait out one heartbeat interval in short push-detector ticks, flushing an
+     * immediate beat if the worker pushes meanwhile. Returns an outcome when a
+     * flushed beat was terminal.
+     */
+    const waitIntervalWatchingForPush = async () => {
+        if (!params.collectRemoteMarker || pushDetectIntervalMs <= 0) {
+            await deps.sleep(options.heartbeatIntervalMs);
+            return null;
+        }
+        let waited = 0;
+        while (waited < options.heartbeatIntervalMs) {
+            const slice = Math.min(pushDetectIntervalMs, options.heartbeatIntervalMs - waited);
+            await deps.sleep(slice);
+            waited += slice;
+            if (ownership.abandoned || params.isDone())
+                return null;
+            let sample;
+            try {
+                sample = await params.collectRemoteMarker();
+            }
+            catch {
+                // Degrade-don't-throw: a failed local ref read is an observability gap,
+                // never a job failure.
+                sample = undefined;
+            }
+            if (sample === undefined)
+                continue;
+            if (!remoteBaselineEstablished) {
+                remoteBaselineEstablished = true;
+                remoteMarker = sample;
+                continue;
+            }
+            if (sample === remoteMarker)
+                continue;
+            // The marker moved: the worker pushed. A rewind/force-push moves it too and
+            // is treated identically — a flush trigger, never a gate or a decision.
+            remoteMarker = sample;
+            const outcome = await sendHeartbeat();
+            if (outcome)
+                return outcome;
+            if (ownership.abandoned || params.isDone())
+                return null;
+        }
+        return null;
+    };
+    let first = true;
+    while (!ownership.abandoned && !params.isDone()) {
+        if (!first) {
+            const waitOutcome = await waitIntervalWatchingForPush();
+            if (waitOutcome)
+                return waitOutcome;
+            if (ownership.abandoned || params.isDone())
+                break;
+        }
+        else {
+            // Establish the push baseline alongside the prompt first beat, so an
+            // already-pushed branch does not look like a brand-new push one tick later.
+            if (params.collectRemoteMarker) {
+                try {
+                    const sample = await params.collectRemoteMarker();
+                    if (sample !== undefined) {
+                        remoteMarker = sample;
+                    }
+                    remoteBaselineEstablished = true;
+                }
+                catch {
+                    remoteBaselineEstablished = true;
+                }
+            }
         }
+        first = false;
+        const outcome = await sendHeartbeat();
+        if (outcome)
+            return outcome;
     }
+    return ownership.abandoned ? { kind: "abandoned" } : { kind: "done" };
 }

package/build/executor/http-client.js

@@ -12,6 +12,28 @@ function isOkBody(bodyText) {
         return false;
     }
 }
+/**
+ * The server-published run-level stop field on a heartbeat response (BAPI-731,
+ * WS-B). Owned by the reconciler safety-plane ticket; until it ships the field is
+ * simply never present.
+ */
+export const HEARTBEAT_STOP_FIELD = "stop_requested";
+/**
+ * True ONLY for a literal `true` on the stop field. Anything else — absent,
+ * `false`, a string, a truthy non-boolean, or an unparseable body — means "no
+ * stop was requested", so an ambiguous body can never cancel a healthy run.
+ */
+function parseStopRequested(bodyText) {
+    try {
+        const parsed = JSON.parse(bodyText);
+        if (!parsed || typeof parsed !== "object")
+            return false;
+        return parsed[HEARTBEAT_STOP_FIELD] === true;
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Map a mutation (heartbeat/complete/fail) HTTP response onto the fencing
  * outcome. `allowInvalidResult` maps 422 to `invalid_job_result` (complete only).
@@ -92,14 +114,33 @@ export function createExecutorHttpClient(config) {
             // 5xx and any other unexpected status are retryable.
             return { kind: "retryable", error: `claim failed (HTTP ${status}): ${boundedDetail(text)}` };
         },
-        heartbeat(job, payload) {
-            return mutate(`/${job.id}/heartbeat`, {
-                repo_name: job.repo_name,
-                claim_token: job.claim_token,
-                local_commit_count: payload.local_commit_count,
-                last_commit_sha: payload.last_commit_sha,
-                telemetry: payload.telemetry,
-            }, false, job.repo_name);
+        // Heartbeat does NOT go through `mutate()`: it is the one mutation whose
+        // response BODY carries information beyond the outcome (the BAPI-731 stop
+        // request), so it maps the response itself instead of discarding the body.
+        async heartbeat(job, payload) {
+            let status;
+            let text;
+            try {
+                const res = await post(`/${job.id}/heartbeat`, {
+                    repo_name: job.repo_name,
+                    claim_token: job.claim_token,
+                    local_commit_count: payload.local_commit_count,
+                    last_commit_sha: payload.last_commit_sha,
+                    telemetry: payload.telemetry,
+                }, job.repo_name);
+                status = res.status;
+                text = res.text;
+            }
+            catch {
+                // Transient network error — identical to the previous behavior; the
+                // caller's dead-man logic decides whether to keep the worker alive.
+                return { outcome: "fatal_http_error" };
+            }
+            const outcome = mapMutationResponse(status, text, false);
+            const result = { outcome };
+            if (parseStopRequested(text))
+                result.stop_requested = true;
+            return result;
         },
         complete(job, completion) {
             return mutate(`/${job.id}/complete`, {

package/build/executor/job-errors.js

@@ -4,6 +4,10 @@ export const WorktreeLostBeforePush = "WorktreeLostBeforePush";
 export const BranchMismatch = "BranchMismatch";
 export const WorkerFinalizationMissingRemoteBranchAndPr = "WorkerFinalizationMissingRemoteBranchAndPr";
 export const WorkerFinalizationPrBaseMismatch = "WorkerFinalizationPrBaseMismatch";
+export const WorkerFinalizationSavedButUnfinalized = "WorkerFinalizationSavedButUnfinalized";
+export const WorkerConfigIsolation = "ContractError.WorkerConfigIsolation";
+export const PreSpawnVerification = "ContractError.PreSpawnVerification";
+export const BridgeCredentialUnavailable = "ContractError.BridgeCredentialUnavailable";
 /** Bound a failure message so no unbounded/secret-bearing text is posted. */
 const ERROR_MESSAGE_MAX_CHARS = 300;
 /**