@bridge_gpt/mcp-server 0.2.34 → 0.2.37

package/build/executor/cli.js

@@ -11,10 +11,12 @@ import { VERSION } from "../version.generated.js";
 import { resolveWorktrunkBinary } from "../start-tickets-prereqs.js";
 import { resolveStartTicketsRepoName } from "../start-tickets-repo.js";
 import { createDefaultExecutorDeps } from "./deps.js";
-import { resolveExecutorApiAccess, } from "./credentials.js";
+import { resolveBaseUrl, resolveExecutorApiAccess, EXECUTOR_BASE_URL_REQUIRED_MESSAGE, } from "./credentials.js";
 import { createExecutorHttpClient } from "./http-client.js";
 import { runExecutor } from "./runner.js";
 import { runExecutorWatchCli } from "./watch-cli.js";
+import { sweepOrphanedWorkerConfigDirectories } from "./worker-config-isolation.js";
+import { pathApiForProvisioningPlatform } from "../mcp-provisioning.js";
 /** Fixed executor timing/behavior defaults. */
 const DEFAULT_POLL_INTERVAL_MS = 15_000;
 const DEFAULT_HEARTBEAT_INTERVAL_MS = 60_000;
@@ -22,7 +24,12 @@ const DEFAULT_DEADMAN_MS = 120_000;
 const DEFAULT_TERM_GRACE_MS = 10_000;
 const DEFAULT_BASE_BRANCH = "main";
 const DEFAULT_JOB_TIMEOUT_SECONDS = 20 * 60;
-const DEFAULT_MAX_CONCURRENT = 1;
+/**
+ * ONE job per executor process. Exported so the invariant can be pinned against
+ * the real constant rather than a copy: BAPI-688 adds more executor *processes*
+ * (persistent service units), and must never turn one process into multi-slot.
+ */
+export const DEFAULT_MAX_CONCURRENT = 1;
 export function getExecutorUsage() {
     return [
         "Usage: mcp-server executor --repo <name> [--repo <name> ...] [options]",
@@ -32,6 +39,7 @@ export function getExecutorUsage() {
         "Options:",
         "  --repo <name>                 Repo to serve (repeatable).",
         "  --repos=<a,b>                 Comma-separated repos.",
+        "  --base-url <url>              Bridge API endpoint (overrides BAPI_BASE_URL).",
         "  --executor-id <id>            Stable executor id (default: <hostname>-<pid>).",
         "  --max-concurrent <n>          Max concurrent jobs (>= 1, default 1).",
         "  --once                        Run a single preflight/claim cycle and exit.",
@@ -41,6 +49,12 @@ export function getExecutorUsage() {
         "  --base-branch <name>          Base branch (default main).",
         "  --no-advisory-parser          Disable the advisory stream-json parser.",
         "  -h, --help                    Show this help.",
+        "",
+        "Subcommands:",
+        "  executor watch <job>          Attach (read-only) to a running job's worker log.",
+        "  executor install-service      Generate a launchd/systemd user service unit for a",
+        "                                stable --executor-id so the executor survives reboot.",
+        "                                See `executor install-service --help`.",
     ].join("\n");
 }
 function parseIntArg(value, flag) {
@@ -63,6 +77,7 @@ export function parseExecutorArgs(argv, context) {
     let deadmanMs = DEFAULT_DEADMAN_MS;
     let baseBranch = DEFAULT_BASE_BRANCH;
     let advisoryParserEnabled = true;
+    let baseUrl;
     for (let i = 0; i < argv.length; i++) {
         const arg = argv[i];
         if (arg === "--help" || arg === "-h")
@@ -120,6 +135,12 @@ export function parseExecutorArgs(argv, context) {
                 return { kind: "error", message: "--base-branch requires a value" };
             baseBranch = v;
         }
+        else if (arg === "--base-url") {
+            const v = argv[++i];
+            if (!v)
+                return { kind: "error", message: "--base-url requires a value" };
+            baseUrl = v;
+        }
         else if (arg === "--no-advisory-parser") {
             advisoryParserEnabled = false;
         }
@@ -150,9 +171,29 @@ export function parseExecutorArgs(argv, context) {
         baseBranch,
         advisoryParserEnabled,
         defaultJobTimeoutSeconds: DEFAULT_JOB_TIMEOUT_SECONDS,
+        baseUrl,
     };
     return { kind: "ok", options };
 }
+/**
+ * Build the sweep boundary from executor deps, or `null` when this executor was
+ * constructed without the filesystem operations the sweep needs. `null` simply
+ * skips the sweep — unlike isolation itself, a missing sweep is not a safety
+ * problem, only uncollected residue.
+ */
+function buildWorkerConfigSweepDeps(deps) {
+    const { tmpdir, readdir, lstatPath, rmRecursive } = deps;
+    if (!tmpdir || !readdir || !lstatPath || !rmRecursive)
+        return null;
+    return {
+        tmpdir,
+        readdir,
+        lstatPath,
+        rmRecursive,
+        join: (...segments) => pathApiForProvisioningPlatform(deps.platform).join(...segments),
+        now: deps.now,
+    };
+}
 function hasRepoFlag(argv) {
     return argv.some((a) => a === "--repo" || a === "--repos" || a.startsWith("--repos="));
 }
@@ -194,20 +235,35 @@ export async function runExecutorCli(argv, overrides = {}) {
         return 1;
     }
     const options = parsed.options;
+    // The mutating executor requires an EXPLICIT base URL (BAPI-676): `--base-url`
+    // then `BAPI_BASE_URL`, never an implicit production default. Fail here —
+    // before any credential resolution, HTTP client, or claim side effect.
+    const baseUrlResult = resolveBaseUrl(deps.env, options.baseUrl);
+    if (!baseUrlResult.ok) {
+        errorLog(`Error: ${EXECUTOR_BASE_URL_REQUIRED_MESSAGE}`);
+        return 1;
+    }
+    const baseUrl = baseUrlResult.baseUrl;
     // Resolve credentials for EVERY configured repo so multi-repo mode sends the
     // correct repo-bound `X-API-Key` per claim/heartbeat/complete/fail — not just
     // the first repo's key. Uses the (injectable) single-repo resolver per repo.
     const resolveApi = overrides.resolveApiAccess ?? resolveExecutorApiAccess;
     const apiKeyByRepo = {};
-    let baseUrl = "";
+    // BAPI-727: retain the normalized base URL from the SUCCESSFUL access result —
+    // not `options.baseUrl` (the raw, pre-validation CLI string) and not
+    // `deps.env.BAPI_BASE_URL` (which loses to an explicit `--base-url`). Worker MCP
+    // provisioning propagates this exact value, so a worker can never be pointed at a
+    // different endpoint than the executor that dispatched it. Every repo resolves
+    // against the same explicit URL, so the value is identical across the loop.
+    let resolvedBaseUrl;
     for (const repo of options.repos) {
-        const access = await resolveApi(repo, deps);
+        const access = await resolveApi(repo, deps, baseUrl);
         if (!access.ok) {
             errorLog(`Error: ${access.error}`);
             return 1;
         }
         apiKeyByRepo[repo] = access.apiKey;
-        baseUrl = access.baseUrl;
+        resolvedBaseUrl = access.baseUrl;
     }
     const createHttpClient = overrides.createHttpClient ?? createExecutorHttpClient;
     const httpClient = createHttpClient({
@@ -217,9 +273,30 @@ export async function runExecutorCli(argv, overrides = {}) {
         mcpVersion: VERSION,
         fetch: deps.fetch,
     });
+    // BAPI-731: sweep isolation directories orphaned by an ungraceful earlier exit
+    // (SIGKILL, OOM, host reboot) where per-job disposal never ran. Deliberately a
+    // ONE-SHOT startup step, separate from per-job disposal: normal cleanup stays
+    // immediate, and this only reclaims residue. Never blocks claiming — a sweep
+    // failure is a bounded diagnostic, because refusing to start over leftover
+    // temp directories would be a worse failure than the leftovers.
+    const sweep = overrides.sweepOrphanedWorkerConfigDirectories ?? sweepOrphanedWorkerConfigDirectories;
+    try {
+        const isolationSweepDeps = buildWorkerConfigSweepDeps(deps);
+        if (isolationSweepDeps) {
+            const swept = await sweep(isolationSweepDeps);
+            for (const diagnostic of swept.diagnostics)
+                errorLog(diagnostic);
+        }
+    }
+    catch {
+        errorLog("worker config isolation sweep did not complete; continuing startup");
+    }
     const run = overrides.runExecutor ?? runExecutor;
+    // Hand the loop the VALIDATED runtime configuration: the parsed options plus the
+    // normalized base URL resolution actually settled on.
+    const runtimeOptions = { ...options, resolvedBaseUrl };
     try {
-        return await run(options, deps, httpClient);
+        return await run(runtimeOptions, deps, httpClient);
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);

package/build/executor/credentials.js

@@ -7,25 +7,53 @@
  * diagnostics/results.
  */
 import { resolveBapiCredentials } from "../credential-store.js";
-/** Default Bridge API base URL when `BAPI_BASE_URL` is unset/blank. */
+import { normalizeBaseUrlCandidate } from "../base-url.js";
+/**
+ * The documented production Bridge API base URL — the value an operator pastes
+ * into `BAPI_BASE_URL` or `--base-url` when they *do* mean production.
+ *
+ * It is NOT an implicit executor fallback (BAPI-676): the executor requires an
+ * explicit base URL and fails fast when none is supplied, so pointing at
+ * production is always a deliberate act. Other flows (MCP server,
+ * install-bridge) legitimately keep their own production defaults.
+ */
 export const DEFAULT_BAPI_BASE_URL = "https://bridgegpt-api.com";
-function resolveBaseUrl(env) {
-    const raw = env.BAPI_BASE_URL;
-    if (typeof raw === "string" && raw.trim().length > 0) {
-        return raw.trim().replace(/\/+$/, "");
-    }
-    return DEFAULT_BAPI_BASE_URL;
+/**
+ * Shared, secret-free prerequisite message for a missing executor base URL.
+ * Names both supported sources and states the no-production-default contract so
+ * the CLI and preflight diagnostics stay identically worded. It interpolates no
+ * configuration or credential value.
+ */
+export const EXECUTOR_BASE_URL_REQUIRED_MESSAGE = "no Bridge API base URL configured for the executor: pass --base-url <url> or set BAPI_BASE_URL " +
+    `(production is ${DEFAULT_BAPI_BASE_URL}). The executor never defaults to production.`;
+/**
+ * Resolve the executor's base URL: explicit override (`--base-url`) first, then
+ * `BAPI_BASE_URL`, then failure. A blank override is treated as absent so a
+ * nonblank environment value can still win; there is NO production fallback.
+ */
+export function resolveBaseUrl(env, explicitBaseUrl) {
+    const fromFlag = normalizeBaseUrlCandidate(explicitBaseUrl);
+    if (fromFlag !== null)
+        return { ok: true, baseUrl: fromFlag };
+    const fromEnv = normalizeBaseUrlCandidate(env?.BAPI_BASE_URL);
+    if (fromEnv !== null)
+        return { ok: true, baseUrl: fromEnv };
+    return { ok: false };
 }
 /**
  * Resolve API access for a single repo. Returns a structured, secret-free
  * failure for credential-not-found, read/parse failure, missing key, or an
  * invalid repo name — never throwing, never echoing credential-file contents.
  */
-export async function resolveExecutorApiAccess(repoName, deps) {
+export async function resolveExecutorApiAccess(repoName, deps, explicitBaseUrl) {
     const trimmed = typeof repoName === "string" ? repoName.trim() : "";
     if (trimmed.length === 0) {
         return { ok: false, error: "invalid repo name: repo name is required" };
     }
+    const url = resolveBaseUrl(deps.env, explicitBaseUrl);
+    if (!url.ok) {
+        return { ok: false, error: EXECUTOR_BASE_URL_REQUIRED_MESSAGE };
+    }
     const storeDeps = {
         env: deps.env,
         homedir: deps.homedir,
@@ -43,17 +71,17 @@ export async function resolveExecutorApiAccess(repoName, deps) {
     return {
         ok: true,
         apiKey: result.credentials.apiKey,
-        baseUrl: resolveBaseUrl(deps.env),
+        baseUrl: url.baseUrl,
     };
 }
 /**
  * Resolve credentials for every configured repo before the executor starts
  * claiming. Each repo resolves independently; failures are reported per-repo.
  */
-export async function resolveAllExecutorApiAccess(repos, deps) {
+export async function resolveAllExecutorApiAccess(repos, deps, explicitBaseUrl) {
     const out = [];
     for (const repo of repos) {
-        const access = await resolveExecutorApiAccess(repo, deps);
+        const access = await resolveExecutorApiAccess(repo, deps, explicitBaseUrl);
         if (access.ok) {
             out.push({ ok: true, repoName: repo, apiKey: access.apiKey, baseUrl: access.baseUrl });
         }

package/build/executor/deps.js

@@ -8,9 +8,11 @@
  * server's JSON-RPC channel in adjacent tooling).
  */
 import { execFile, spawn } from "node:child_process";
-import { readFile, writeFile, appendFile, mkdir, stat, statfs } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { readFile, writeFile, appendFile, mkdir, mkdtemp, chmod, rm, readdir, lstat, stat, statfs, } from "node:fs/promises";
 import os from "node:os";
 import { promisify } from "node:util";
+import { resolveMcpShimInvocationForRuntime } from "../mcp-server-invocation.js";
 const execFileAsync = promisify(execFile);
 /** Bounded subprocess output buffer (bytes). */
 const MAX_COMMAND_BUFFER = 10 * 1024 * 1024;
@@ -83,6 +85,23 @@ export function createDefaultExecutorDeps() {
             const s = await statfs(path);
             return { bavail: Number(s.bavail), bsize: Number(s.bsize) };
         },
+        // --- Worker config isolation filesystem boundaries (BAPI-731) ----------
+        // Bound to real `node:fs/promises` operations here so the isolation module
+        // itself never reaches for a filesystem global and stays fully unit-testable.
+        mkdtemp: (prefix) => mkdtemp(prefix),
+        chmod: (path, mode) => chmod(path, mode),
+        rmRecursive: (path) => rm(path, { recursive: true, force: true }),
+        readdir: (dirPath) => readdir(dirPath),
+        // `lstat`, never `stat`: a symlinked isolation parent or swept entry must be
+        // recognizable AS a symlink rather than reported as its target directory.
+        lstatPath: (path) => lstat(path)
+            .then((s) => ({
+            isDirectory: s.isDirectory(),
+            isSymbolicLink: s.isSymbolicLink(),
+            mtimeMs: s.mtimeMs,
+        }))
+            .catch(() => null),
+        tmpdir: () => os.tmpdir(),
         sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
         now: () => Date.now(),
         setTimer: (cb, ms) => setTimeout(cb, ms),
@@ -113,5 +132,17 @@ export function createDefaultExecutorDeps() {
         },
         log: (message) => console.error(message),
         errorLog: (message) => console.error(message),
+        // Resolve how the worker MCP shim launches at dispatch time from THIS
+        // running executor's own on-disk build (absolute-build-path primary,
+        // npm-channel fallback) — never from process.cwd(). Mirrors
+        // `buildMcpProvisioningDeps` in `start-tickets.ts`. `nodeExecutable` stays
+        // "node" (not `process.execPath`) to preserve today's worker runtime
+        // selection; see `mcp-server-invocation.ts`'s scope-boundary note.
+        mcpServerInvocation: resolveMcpShimInvocationForRuntime({
+            moduleUrl: import.meta.url,
+            nodeExecutable: "node",
+            argv1: process.argv[1],
+            fileExists: existsSync,
+        }),
     };
 }

package/build/executor/env.js

@@ -1,12 +1,22 @@
 /**
  * Secret-free executor worker environment (BAPI-534, TDD §7).
  *
- * v2 executor workers get NO Bridge MCP and NO conductor identity: unlike the
- * conductor worker env builder, this one omits `BRIDGE_MCP_PROFILE`, every
- * `BAPI_CONDUCTOR_*` key, `CONDUCTOR_NODE_PATH`, and all secret-bearing keys.
- * It constructs a 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.
+ * v2 executor workers get Bridge MCP access by default (BAPI-724), but NOT
+ * through this environment. Access is provisioned into the worktree's
+ * `.mcp.json`/`.cursor/mcp.json` (secret-free shim registration, resolved and
+ * written BEFORE spawn — see `../mcp-provisioning.js` wiring in
+ * `job-runner.ts`), never via env vars. This builder still omits
+ * `BRIDGE_MCP_PROFILE` (an absent profile selects the intended `core` tool
+ * group default), every `BAPI_CONDUCTOR_*` key, `CONDUCTOR_NODE_PATH` (the
+ * shim's node executable is resolved into the registration's command/args at
+ * provisioning time instead), and all secret-bearing keys. It constructs a
+ * 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 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. */
@@ -22,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",
@@ -36,12 +53,22 @@ 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
  * allowlist is locally auditable/testable. A key is allowed iff it is in the
  * allowlist AND is not explicitly denied, does not begin with `BAPI_CONDUCTOR_`,
  * and does not contain a secret-name fragment.
+ *
+ * The `BAPI_CONDUCTOR_` rejection is a WHOLE-PREFIX rule, not an enumerated list,
+ * which is what makes it hold for keys added later. BAPI-722's
+ * `BAPI_CONDUCTOR_DENY_PROBE_TIMEOUT_MS` is rejected twice over — it is absent from
+ * `ALLOWED_ENV_KEYS` and it carries the prefix — so it stays executor-process
+ * configuration and can never reach a spawned worker. That is deliberate: a worker
+ * runs no deny probe, and letting job-side state influence the executor's own
+ * safety-probe budget would invert the trust boundary.
  */
 export function isExecutorEnvKeyAllowed(key) {
     if (!ALLOWED_ENV_KEYS.includes(key))
@@ -55,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))
@@ -83,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" };
 }