@bridge_gpt/mcp-server 0.2.34 → 0.2.37

package/build/executor/job-runner.js

@@ -17,9 +17,11 @@
 import os from "node:os";
 import { buildExecutorWorkerEnv } from "./env.js";
 import { runHeartbeatLoop } from "./heartbeat.js";
-import { isExecutorNamedError, toExecutorFailure, secretFreeErrorMessage, MissingVerdictArtifact, } from "./job-errors.js";
+import { isExecutorNamedError, toExecutorFailure, secretFreeErrorMessage, MissingVerdictArtifact, PreSpawnVerification, WorkerConfigIsolation, BridgeCredentialUnavailable, } from "./job-errors.js";
 import { buildConductorMergeAccessForExecutorJob, buildDefaultMergeLocalDeps, runExecutorMergeJob, MERGE_RETRYABLE, MERGE_FAILED, } from "./merge-job.js";
 import { createObservationState } from "./observation.js";
+import { getWorktreeMcpRegistrationTargets, pathApiForProvisioningPlatform, provisionMcpRegistrationForWorktree, } from "../mcp-provisioning.js";
+import { evaluateClaudeMcpShadowingPolicy, inspectClaudeUserConfigForMcpShadowing, resolveClaudeUserConfigPath, } from "../claude-user-config-doctor.js";
 import { provisionExecutorDenyLayer } from "./permissions.js";
 import { runProcessWithTimeout } from "./process.js";
 import { prepareResumeSpawn } from "./resume-pre-spawn.js";
@@ -35,8 +37,10 @@ import { resolveExecutorJobBaseBranch } from "./base-branch.js";
 import { validateWorkerFinalization } from "./worker-finalization.js";
 import { ensureExecutorWorktree } from "./worktree.js";
 import { buildPrBaseContractLaunchInstruction } from "../pr-base-contract.js";
-import { buildClaudeExecutorArgv, CLAUDE_EXECUTABLE, resolveExecutorModelAlias, resolveExecutorPrompt, } from "./worker-command.js";
-import { collectGitTelemetry } from "./observation.js";
+import { buildClaudeExecutorArgv, CLAUDE_EXECUTABLE, resolveExecutorModelAlias, resolveExecutorPrompt, resolveWorkerPermissionPosture, } from "./worker-command.js";
+import { collectGitTelemetry, collectRemoteTrackingSha, evaluatePreSpawnGitVerification, } from "./observation.js";
+import { establishWorkerConfigIsolation, formatWorkerConfigIsolationReason, } from "./worker-config-isolation.js";
+import { resolveBapiCredentials } from "../credential-store.js";
 /** Default runtime for the no-op smoke process (ms). */
 const DEFAULT_SMOKE_DURATION_MS = 100;
 /** ProcessClassification maps 1:1 onto the wire ExecutorClassification. */
@@ -91,6 +95,233 @@ function buildJobLogRegistryDeps(deps) {
         platform: deps.platform,
     };
 }
+/**
+ * Map executor deps into the shared MCP-provisioning filesystem boundary.
+ *
+ * `bridgeApiBaseUrl` is an EXPLICIT argument, deliberately not read from
+ * `deps.env` (BAPI-727). The worker env allowlist strips `BAPI_BASE_URL`, and the
+ * executor's own endpoint may have come from `--base-url` rather than the
+ * environment at all — so the environment is not a trustworthy source here. The
+ * only correct value is the one the caller threads down from the validated
+ * runtime configuration.
+ */
+function buildExecutorMcpProvisioningDeps(deps, bridgeApiBaseUrl) {
+    return {
+        readFile: deps.readFile,
+        writeFile: deps.writeFile,
+        mkdir: deps.mkdir,
+        platform: deps.platform,
+        cwd: deps.cwd,
+        mcpServerInvocation: deps.mcpServerInvocation,
+        bridgeApiBaseUrl,
+    };
+}
+/**
+ * Provision secret-free Bridge MCP registration + Claude trust pre-approval
+ * (BAPI-724) into a prepared spawn worktree, for every job type that reaches
+ * the shared spawn path. Reuses the exact `start-tickets` provisioning
+ * machinery by constructing a synthetic `created` {@link SummaryRow} for this
+ * job/worktree — no registration serialization or second trust write happens
+ * here.
+ *
+ * Fail-open by construction: a provisioner warning or a `spawn-failed` result
+ * is logged via `deps.errorLog` and this function still returns normally, and
+ * an unexpected thrown exception is caught and reduced to a single fixed,
+ * secret-free diagnostic. Either way `runSpawnJob` proceeds to spawn the
+ * worker — a job that later needs an MCP tool it cannot reach fails loudly
+ * through its own process/gate/timeout/budget path, never here.
+ *
+ * BAPI-727 keeps that fail-open contract UNCONDITIONAL. The blocking Claude
+ * shadow-integrity check deliberately lives in `runSpawnJob` ABOVE this call, not
+ * inside it: the fixed `catch` below would otherwise convert a confirmed
+ * integrity refusal into a logged warning and spawn the worker anyway.
+ */
+async function provisionMcpForPreparedSpawn(job, branch, worktreePath, deps, seams, bridgeApiBaseUrl) {
+    const provision = seams.provisionMcp ?? provisionMcpRegistrationForWorktree;
+    const row = {
+        key: job.ticket_key ?? String(job.id),
+        branch,
+        status: "created",
+        path: worktreePath,
+    };
+    try {
+        const result = await provision(row, buildExecutorMcpProvisioningDeps(deps, bridgeApiBaseUrl));
+        for (const warning of result.warnings ?? []) {
+            deps.errorLog(`MCP provisioning warning: ${warning}`);
+        }
+        if (result.status === "spawn-failed") {
+            deps.errorLog(`MCP provisioning did not complete (${result.error ?? "unknown reason"}); continuing fail-open`);
+        }
+    }
+    catch {
+        // Fail-open, secret-free: a fixed diagnostic only. Never interpolate the
+        // thrown exception, the worktree path, a command/argument, or credential
+        // material — this branch exists precisely so an unexpected provisioning
+        // failure can never leak anything into the executor's own logs.
+        deps.errorLog("MCP provisioning did not complete; continuing fail-open");
+    }
+}
+/**
+ * Adapt `ExecutorDeps` into the isolation module's explicit required interface,
+ * or `null` when this executor was constructed without the filesystem
+ * boundaries isolation needs.
+ *
+ * Returning `null` (rather than substituting a default) is the fail-closed
+ * posture: the optional `ExecutorDeps` members exist so existing embedders and
+ * test builders stay source-compatible, NOT so a worker may spawn without
+ * isolation. The caller turns `null` into a refusal.
+ */
+function buildWorkerConfigIsolationDeps(deps) {
+    const { mkdtemp, chmod, rmRecursive, lstatPath, tmpdir } = deps;
+    if (!mkdtemp || !chmod || !rmRecursive || !lstatPath || !tmpdir)
+        return null;
+    return {
+        platform: deps.platform,
+        env: deps.env,
+        tmpdir,
+        mkdtemp,
+        mkdir: deps.mkdir,
+        chmod,
+        rmRecursive,
+        lstatPath,
+        join: (...segments) => pathApiForProvisioningPlatform(deps.platform).join(...segments),
+        writeFile: deps.writeFile,
+    };
+}
+/**
+ * Resolve the repo-scoped Bridge credential to seed into the isolated store.
+ *
+ * Resolved through the SHARED resolver (`resolveBapiCredentials`) rather than by
+ * reading any file directly, per the repository's shell-spawned credential rule:
+ * env `BAPI_API_KEY` first, then the user-scoped `bapi:<repo>` store. It runs
+ * against the EXECUTOR's own deps/env — deliberately, because the executor is
+ * still outside the isolation boundary and is the only party that can still see
+ * the operator's store.
+ *
+ * Returns null when no credential can be resolved. `runSpawnJob` turns null into
+ * a pre-spawn `/fail` with `ContractError.BridgeCredentialUnavailable` — it never
+ * proceeds to establish isolation with an empty store, because every job type
+ * that reaches `runSpawnJob` needs Bridge MCP tools, and a worker without them
+ * exits cleanly having done nothing (RUN-FINDINGS-2026-08-05 F2). A resolution
+ * exception is swallowed into the same null so no raw error (which could carry a
+ * path or a secret) ever reaches a diagnostic; the refusal message is a fixed
+ * constant.
+ */
+async function resolveSeedBridgeCredential(deps, repoName) {
+    const trimmed = typeof repoName === "string" ? repoName.trim() : "";
+    if (trimmed.length === 0)
+        return null;
+    try {
+        const resolved = await resolveBapiCredentials(trimmed, {
+            env: deps.env,
+            homedir: deps.homedir,
+            platform: deps.platform,
+            readFile: deps.readFile,
+            stat: deps.stat,
+            // Route the resolver's (secret-free) insecure-mode warning through the
+            // executor's own log seam instead of raw process stderr.
+            stderr: (message) => deps.errorLog(message),
+        });
+        if (!resolved.ok)
+            return null;
+        return { repoName: trimmed, apiKey: resolved.credentials.apiKey };
+    }
+    catch {
+        // Never let a credential-resolution error carry a secret into a diagnostic.
+        return null;
+    }
+}
+/**
+ * Fixed, secret-free refusal text for `ContractError.BridgeCredentialUnavailable`.
+ * Names both supported resolution routes and no value, path fragment, or raw
+ * error — this exact text is what `/fail` persists as `error_message`.
+ */
+const BRIDGE_CREDENTIAL_UNAVAILABLE_MESSAGE = "no Bridge API credential could be resolved for this job's repository, so an isolated worker " +
+    "would run without Bridge MCP tools and do nothing; set BAPI_API_KEY in the executor's " +
+    "environment or add a bapi:<repo> entry to the user-scoped credential store " +
+    "(~/.config/bridge/credentials.json)";
+/**
+ * Confirm the prepared worktree's own `.mcp.json` actually carries the Bridge
+ * shim registration the worker needs (BAPI-731 requirement, plan step 10).
+ *
+ * Read-only. Verifies PRESENCE of the `bridge-api` server name only — it does not
+ * filter, rewrite, or narrow the registered surface, so every other valid
+ * worktree-provisioned server (including supported Tier-2 targets) is preserved
+ * exactly as provisioned.
+ */
+async function verifyRequiredWorktreeMcpRegistration(worktreePath, deps) {
+    const [target] = getWorktreeMcpRegistrationTargets(worktreePath, deps.platform);
+    if (!target) {
+        return { ok: false, message: REQUIRED_MCP_REGISTRATION_MISSING_MESSAGE };
+    }
+    try {
+        const raw = await deps.readFile(target.filePath);
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+            return { ok: false, message: REQUIRED_MCP_REGISTRATION_MISSING_MESSAGE };
+        }
+        const servers = parsed[target.topLevelKey];
+        if (!servers || typeof servers !== "object" || Array.isArray(servers)) {
+            return { ok: false, message: REQUIRED_MCP_REGISTRATION_MISSING_MESSAGE };
+        }
+        const present = Object.prototype.hasOwnProperty.call(servers, REQUIRED_MCP_SERVER_NAME);
+        return present ? { ok: true } : { ok: false, message: REQUIRED_MCP_REGISTRATION_MISSING_MESSAGE };
+    }
+    catch {
+        // Unreadable or malformed is indistinguishable from absent for this purpose,
+        // and both mean the worker cannot reach Bridge. The raw error never escapes.
+        return { ok: false, message: REQUIRED_MCP_REGISTRATION_MISSING_MESSAGE };
+    }
+}
+/** The registration name the provisioner writes and a worker requires. */
+const REQUIRED_MCP_SERVER_NAME = "bridge-api";
+/** Fixed, secret-free refusal text (no path, no file contents). */
+const REQUIRED_MCP_REGISTRATION_MISSING_MESSAGE = "worker config isolation active but the required 'bridge-api' MCP registration is missing or " +
+    "unreadable in the prepared worktree; an isolated worker has no operator-scoped registration to " +
+    "fall back to, so refusing to spawn a worker that would run without Bridge tools";
+/**
+ * The stable `error_kind` for a claimed job refused because the machine's Claude
+ * user configuration can shadow the worker's provisioned MCP registration
+ * (BAPI-727). It joins the established `ContractError.*` family every other
+ * pre-spawn refusal in `runSpawnJob` already posts — this is the same class of
+ * failure: a local precondition that makes the job unrunnable-as-specified, decided
+ * before any side effect. The message is fixed and secret-free.
+ */
+export const MCP_SHADOWING_ERROR_KIND = "ContractError.McpShadowing";
+/**
+ * Run the read-only Claude user-config inspection against a PREPARED worktree,
+ * covering all three scopes: user, the executor's main checkout (`deps.cwd`), and
+ * the concrete worktree this job will run in.
+ *
+ * Degraded outcomes (unreadable/malformed config) and an enabled override are
+ * logged and allowed through — the first is inconclusive, the second is a
+ * deliberate operator decision. Only a confirmed collision without the override
+ * blocks. An unexpected throw fails OPEN with a fixed diagnostic: the inspector is
+ * a guard, and a guard that crashes must not become a new way for jobs to die.
+ */
+async function checkClaudeMcpShadowingForPreparedWorktree(worktreePath, deps, seams) {
+    try {
+        const inspect = seams.inspectClaudeUserConfig ?? inspectClaudeUserConfigForMcpShadowing;
+        const inspection = await inspect({
+            claudeConfigPath: resolveClaudeUserConfigPath(deps.homedir(), deps.platform),
+            platform: deps.platform,
+            cwd: deps.cwd,
+            mainRepositoryPath: deps.cwd,
+            worktreePath,
+        }, { readFile: deps.readFile });
+        const policy = evaluateClaudeMcpShadowingPolicy(inspection, deps.env);
+        for (const warning of policy.warnings) {
+            deps.errorLog(`Claude MCP shadowing: ${warning}`);
+        }
+        if (policy.ok)
+            return { blocked: false };
+        return { blocked: true, message: policy.refusals.join("; ") };
+    }
+    catch {
+        deps.errorLog("Claude MCP shadowing check did not complete; continuing without a shadowing verdict");
+        return { blocked: false };
+    }
+}
 /**
  * Default merge dispatch: resolve Bridge API access, then run the deterministic
  * merge. Exported for unit tests (access-resolution failure → retryable). The
@@ -156,7 +387,15 @@ function createNoopProcess(deps, durationMs, message) {
         },
     };
 }
-/** Run the process and heartbeat loop concurrently; return the process outcome. */
+/**
+ * Run the process and heartbeat loop concurrently; return the process outcome.
+ *
+ * BAPI-731: `serverStopRequested` is carried ALONGSIDE the process
+ * classification rather than folded into it. When the server cancels a run the
+ * worker is SIGKILLed, so its raw classification would read as `killed` — which
+ * the caller would otherwise report as a worker fault. Keeping the flag separate
+ * is what lets the caller report a deliberate server cancellation distinctly.
+ */
 async function superviseProcess(params) {
     const isDoneRef = { value: false };
     const hb = runHeartbeatLoop({
@@ -168,6 +407,7 @@ async function superviseProcess(params) {
         proc: params.proc,
         observation: params.observation,
         collectTelemetry: params.collectTelemetry,
+        collectRemoteMarker: params.collectRemoteMarker,
         isDone: () => isDoneRef.value,
     });
     const result = await runProcessWithTimeout(params.proc, params.timeoutSeconds, params.deps, {
@@ -175,9 +415,11 @@ async function superviseProcess(params) {
         onStdout: (chunk) => params.observation.recordStdout(chunk),
     });
     isDoneRef.value = true;
-    await hb;
+    const loopOutcome = await hb;
     params.observation.setExitCode(result.exitCode);
-    return result;
+    return loopOutcome.kind === "server_stop"
+        ? { ...result, serverStopRequested: true }
+        : result;
 }
 function terminalToRunResult(terminal, successStatus) {
     switch (terminal.outcome) {
@@ -214,7 +456,27 @@ export async function runClaimedJob(job, httpClient, options, deps, _report, sea
     // via the shared `isSpawnJobType` policy (`job-types.ts`) AFTER the dedicated
     // `merge` and `smoke` branches so those keep their bespoke handling.
     if (isSpawnJobType(job.job_type)) {
-        return runSpawnJob(job, httpClient, options, deps, ownership, observation, seams);
+        // BAPI-731: the per-job isolated Claude config directory is created INSIDE
+        // `runSpawnJob` (it must not exist before the pre-spawn contract passes) but
+        // is disposed HERE, in a `finally` around the whole call. That placement is
+        // the lifetime guarantee: disposal cannot run until the worker process has
+        // terminated, the log tee is finalized, and the terminal report has been
+        // sent — while still covering every exit path, including spawn exceptions,
+        // timeouts, stale claims, dead-man abandonment, server stops, artifact
+        // failures, finalization failures, and terminal-report failures.
+        const isolationHolder = { current: null };
+        try {
+            return await runSpawnJob(job, httpClient, options, deps, ownership, observation, seams, isolationHolder);
+        }
+        finally {
+            if (isolationHolder.current) {
+                // Best-effort by contract: a cleanup failure is logged, never allowed to
+                // replace the job outcome already determined above.
+                const diagnostic = await isolationHolder.current.dispose();
+                if (diagnostic)
+                    deps.errorLog(diagnostic);
+            }
+        }
     }
     // Unsupported job type — fail server-side; never spawn.
     await httpClient.fail(job, {
@@ -401,6 +663,19 @@ async function runMergeJob(job, httpClient, options, deps, ownership, observatio
     });
     return terminalToRunResult(terminal, "failed");
 }
+/**
+ * BAPI-724 design note (deliberate, not an accidental AC-5 gap): `smoke` stays
+ * on this no-worktree, no-real-worker-LLM `createNoopProcess` path and does
+ * NOT receive MCP registration. The ratified requirement anchors MCP
+ * provisioning to "the executor's worktree-preparation path
+ * (`job-runner.ts`), alongside the existing `provisionExecutorDenyLayer` call"
+ * — that call, like the new MCP provisioning call, exists ONLY inside
+ * `runSpawnJob`, which `smoke` never reaches (see `isSpawnJobType` /
+ * `job-types.ts`, and this module's own "no real worker LLM" framing of the
+ * acceptance spine). Converting smoke into a worktree-having, worker-spawning
+ * job to give it something to register MCP into would be a materially larger,
+ * unratified change to that architectural boundary, not a wiring task.
+ */
 async function runSmokeJob(job, httpClient, options, deps, ownership, observation) {
     const timeout = resolveJobTimeoutSeconds(job, options.defaultJobTimeoutSeconds);
     if (!timeout.ok) {
@@ -488,10 +763,18 @@ async function prepareSpawn(job, httpClient, options, deps, seams) {
         }
     }
     // Resolve an explicit `payload.prompt` or the `/implement-ticket <KEY> --auto`
-    // synthesis (implement + recovery). `spec_review` matches neither — it is
-    // resolved AFTER worktree preparation from its structured `payload.prompt_spec`
-    // (rendering `{{GIT_LOG}}` needs the prepared worktree), so a non-ok result
-    // here is not yet a failure when a `prompt_spec` is present to render.
+    // synthesis (implement + recovery).
+    //
+    // BAPI-725: `spec_review` now takes the explicit-prompt path like any other job
+    // — the reconciler builds its prompt server-side and ships it in
+    // `payload.prompt`, so it resolves here and returns below without ever reaching
+    // the prompt-spec renderer. A stale `payload.prompt_spec` on an in-flight job
+    // enqueued before this change cannot override that: the explicit prompt wins
+    // unconditionally at the `explicit.ok` return.
+    //
+    // The renderer below is NOT dead. `smoke` and any future structured-prompt job
+    // still reach it, and rendering `{{GIT_LOG}}` is why it must run after worktree
+    // preparation rather than in `resolveExecutorPrompt`.
     const explicit = resolveExecutorPrompt(job);
     const payload = job.payload && typeof job.payload === "object"
         ? job.payload
@@ -526,12 +809,19 @@ async function prepareSpawn(job, httpClient, options, deps, seams) {
     }
     // Explicit/synthesized prompt wins verbatim, preserving existing behavior.
     if (explicit.ok) {
-        return { ok: true, worktreePath: wt.worktreePath, branch: wt.branch, prompt: explicit.prompt };
+        return {
+            ok: true,
+            worktreePath: wt.worktreePath,
+            branch: wt.branch,
+            prompt: explicit.prompt,
+            expectedHeadSha: wt.expectedHeadSha,
+        };
     }
     // No explicit/synthesized prompt: render the structured `payload.prompt_spec`
-    // against the prepared worktree (the `spec_review` path). A malformed spec
-    // fails loud with `ContractError.Prompt` so we `/fail` rather than spawn a
-    // worker with an empty prompt. Error messages are secret-free by construction.
+    // against the prepared worktree (`smoke`, and any future structured-prompt job;
+    // `spec_review` left this path in BAPI-725). A malformed spec fails loud with
+    // `ContractError.Prompt` so we `/fail` rather than spawn a worker with an empty
+    // prompt. Error messages are secret-free by construction.
     const renderPrompt = seams.renderPromptSpecPrompt ?? renderPromptSpecPrompt;
     try {
         const rendered = await renderPrompt(job, {
@@ -540,7 +830,13 @@ async function prepareSpawn(job, httpClient, options, deps, seams) {
             baseBranch: options.baseBranch,
             runCommand: deps.runCommand,
         });
-        return { ok: true, worktreePath: wt.worktreePath, branch: wt.branch, prompt: rendered };
+        return {
+            ok: true,
+            worktreePath: wt.worktreePath,
+            branch: wt.branch,
+            prompt: rendered,
+            expectedHeadSha: wt.expectedHeadSha,
+        };
     }
     catch (err) {
         const failure = isExecutorNamedError(err)
@@ -554,7 +850,17 @@ async function prepareSpawn(job, httpClient, options, deps, seams) {
         return { ok: false, result: { status: "failed", reason: "prompt_contract" } };
     }
 }
-async function runSpawnJob(job, httpClient, options, deps, ownership, observation, seams) {
+/**
+ * Final pre-spawn preparation order (BAPI-724, BAPI-727): worktree + prompt
+ * preparation (which itself performs reset-based untracked cleanup and command
+ * provisioning), timeout-contract validation, the BLOCKING Claude MCP
+ * shadow-integrity check, the deny-layer attempt, the MCP registration +
+ * trust-approval attempt, worker-log/viewer setup, then `deps.spawnProcess`.
+ * Failed preparation, an invalid timeout, or a confirmed MCP-shadowing collision
+ * returns BEFORE either the deny layer or MCP provisioning runs — neither ever
+ * touches a worktree that will not become a runnable worker.
+ */
+async function runSpawnJob(job, httpClient, options, deps, ownership, observation, seams, isolationHolder) {
     // --- Per-job base branch (BAPI-586) ----------------------------------
     // Resolve the effective logical base BEFORE any side effect: the persisted
     // run base (`payload.base_branch`) is authoritative, falling back to the
@@ -574,6 +880,26 @@ async function runSpawnJob(job, httpClient, options, deps, ownership, observatio
     }
     const effectiveBaseBranch = baseResolution.baseBranch;
     const jobOptions = { ...options, baseBranch: effectiveBaseBranch };
+    // --- Permission posture (BAPI-725) -----------------------------------
+    // Resolved alongside the base branch, BEFORE any side effect, for the same
+    // reason: an unsupported posture is a contract failure, and failing it here
+    // means no worktree is cut, no deny layer is written, and no process is
+    // spawned for a job that can never run correctly. The error text names only
+    // the field — the supplied value never reaches `/fail`.
+    let permissionPosture;
+    try {
+        permissionPosture = resolveWorkerPermissionPosture(job.payload);
+    }
+    catch (err) {
+        await httpClient.fail(job, isExecutorNamedError(err)
+            ? toExecutorFailure(err)
+            : {
+                error_kind: "ContractError.PermissionPosture",
+                error_message: secretFreeErrorMessage(err),
+                classification: "crashed",
+            });
+        return { status: "failed", reason: "permission_posture_contract" };
+    }
     // --- Worktree + prompt (resume pre-spawn protocol or standard) -------
     const prep = await prepareSpawn(job, httpClient, jobOptions, deps, seams);
     if (!prep.ok)
@@ -596,6 +922,115 @@ async function runSpawnJob(job, httpClient, options, deps, ownership, observatio
         });
         return { status: "failed", reason: "timeout_contract" };
     }
+    // --- Pre-spawn git verification (FAIL-CLOSED, BAPI-731 WS-E) ---------
+    // FIRST of the pre-spawn contracts, and deliberately BEFORE every
+    // executor-owned write to the worktree (deny layer, MCP provisioning, worker
+    // log). Placement is load-bearing twice over: those writes would themselves
+    // dirty the tree and make a later cleanliness assertion vacuous, and a job that
+    // cannot run correctly should not have had anything written for it.
+    //
+    // This is insurance against the F11a class — a `ci_fix` attempt that committed
+    // leftover unrelated work and burned a remediation attempt without touching the
+    // failing check. It does NOT replace or weaken the existing hard-reset /
+    // untracked-clean / head-verify behavior in `worktree-core.ts`; it is an
+    // additional independent check on top of them.
+    const preSpawnTelemetry = await collectGitTelemetry({ runCommand: deps.runCommand, now: deps.now }, worktreePath, effectiveBaseBranch);
+    const verification = evaluatePreSpawnGitVerification(preSpawnTelemetry, prep.expectedHeadSha);
+    if (!verification.ok) {
+        // Record the attempt boundary even for a refusal: an attempt that never
+        // spawned still started and ended at the observed commit, so the reconciler
+        // sees a machine-readable "went nowhere" rather than a silent gap.
+        if (verification.observedSha) {
+            observation.setAttemptStartSha(verification.observedSha);
+            observation.setAttemptEndSha(verification.observedSha);
+        }
+        observation.setGitTelemetry(preSpawnTelemetry);
+        await httpClient.fail(job, {
+            error_kind: PreSpawnVerification,
+            error_message: verification.message,
+            classification: "crashed",
+            ...commitResidue(preSpawnTelemetry),
+            telemetry: observation.snapshot(),
+        });
+        return { status: "failed", reason: "pre_spawn_verification" };
+    }
+    observation.setAttemptStartSha(verification.observedSha);
+    // --- Claude MCP shadow integrity (BLOCKING, BAPI-727) ----------------
+    // Runs against the CONCRETE prepared worktree, after preparation and timeout
+    // validation but BEFORE the deny layer, MCP provisioning, worker-log setup, and
+    // spawn. Placement is the point: a `projects["<this worktree>"]` entry in
+    // ~/.claude.json would silently win over the registration provisioned two steps
+    // below, so the job must be stopped before any of those side effects — not
+    // after them, and not inside `provisionMcpForPreparedSpawn()`, whose fail-open
+    // catch exists to swallow provisioning errors and would swallow this refusal too.
+    const shadow = await checkClaudeMcpShadowingForPreparedWorktree(worktreePath, deps, seams);
+    if (shadow.blocked) {
+        await httpClient.fail(job, {
+            error_kind: MCP_SHADOWING_ERROR_KIND,
+            error_message: shadow.message,
+            classification: "crashed",
+        });
+        return { status: "failed", reason: "mcp_shadowing_contract" };
+    }
+    // --- Worker config isolation (FAIL-CLOSED, BAPI-731 WS-A) ------------
+    // After the retained BAPI-727 shadowing refusal (which stays defense-in-depth
+    // for the named `bridge-api` collision) and before the deny layer, MCP
+    // provisioning, log setup, and spawn.
+    //
+    // FAIL-CLOSED, unlike the fail-OPEN provisioning steps immediately below. The
+    // whole point is that a worker must never fall back to the operator's
+    // configuration: that fallback is how a worker acquired a `dbhub` handle it was
+    // never granted (BAPI-715 finding F4). "Could not isolate" therefore means
+    // "do not run", not "run with less containment".
+    const isolationEstablish = seams.establishWorkerConfigIsolation ?? establishWorkerConfigIsolation;
+    const isolationDeps = buildWorkerConfigIsolationDeps(deps);
+    // BAPI-731 gap: the isolated XDG root is where the Bridge credential store is
+    // looked up, so it must carry this repo's entry or the worker loses every
+    // Bridge MCP tool. Resolved here, outside the boundary, and scoped to one repo.
+    const seedCredential = isolationDeps
+        ? await resolveSeedBridgeCredential(deps, job.repo_name)
+        : null;
+    // FAIL-CLOSED on an unresolvable credential (RUN-FINDINGS-2026-08-05 F2):
+    // establishing isolation with an EMPTY store would succeed, and the worker
+    // would spawn, find no `bapi:<repo>` entry under the redirected XDG root, lose
+    // every Bridge MCP tool, and exit cleanly having done nothing — the original
+    // F2 death, reported as success. Every job type that reaches `runSpawnJob`
+    // needs Bridge MCP (`smoke`/`merge` never come through here), so a distinct
+    // pre-spawn refusal breaks nothing legitimate and makes the cause queryable.
+    if (isolationDeps && !seedCredential) {
+        await httpClient.fail(job, {
+            error_kind: BridgeCredentialUnavailable,
+            error_message: BRIDGE_CREDENTIAL_UNAVAILABLE_MESSAGE,
+            classification: "crashed",
+            ...commitResidue(preSpawnTelemetry),
+            telemetry: observation.snapshot(),
+        });
+        return { status: "failed", reason: "bridge_credential_unavailable" };
+    }
+    const isolationResult = isolationDeps
+        ? await isolationEstablish(isolationDeps, {
+            ...(seedCredential ? { bridgeCredential: seedCredential } : {}),
+        })
+        : {
+            ok: false,
+            platform: String(deps.platform),
+            reason: "missing-filesystem-dependency",
+            message: formatWorkerConfigIsolationReason(String(deps.platform), "missing-filesystem-dependency"),
+        };
+    if (!isolationResult.ok) {
+        await httpClient.fail(job, {
+            error_kind: WorkerConfigIsolation,
+            error_message: isolationResult.message,
+            classification: "crashed",
+            ...commitResidue(preSpawnTelemetry),
+            telemetry: observation.snapshot(),
+        });
+        return { status: "failed", reason: "worker_config_isolation" };
+    }
+    const isolation = isolationResult.isolation;
+    // Hand the handle to the caller's `finally` so it is disposed on EVERY exit
+    // path from here on, including ones that never reach the spawn below.
+    isolationHolder.current = isolation;
     // --- Deny layer (fail-open) ------------------------------------------
     const deny = await provisionExecutorDenyLayer(worktreePath, { baseBranch: effectiveBaseBranch }, {
         readFile: deps.readFile,
@@ -605,6 +1040,35 @@ async function runSpawnJob(job, httpClient, options, deps, ownership, observatio
     });
     if (!deny.ok)
         deps.errorLog(deny.warning);
+    // --- MCP registration + trust pre-approval (fail-open, BAPI-724) -----
+    // Unconditional for every job type that reaches this shared spawn path
+    // (implement/resume/spec_review/remediate/ci_fix/rebase) — no job-type
+    // branching, so a future spawn job type inherits the same default access.
+    // BAPI-727: the validated endpoint travels from executor bootstrap through the
+    // runtime options to the generated registration, so the worker's MCP server
+    // targets the same Bridge API this executor claimed the job from.
+    await provisionMcpForPreparedSpawn(job, branch, worktreePath, deps, seams, options.resolvedBaseUrl);
+    // --- Required Bridge MCP registration (FAIL-CLOSED under isolation) ---
+    // Provisioning itself stays fail-OPEN: a skipped or malformed Tier-2 target is
+    // a warning, and every valid worktree-provisioned server is kept. But the
+    // REQUIRED `bridge-api` shim registration becomes fail-closed once isolation is
+    // active, because the two changes compose into a new failure mode: before
+    // isolation, a worker missing its worktree registration could still fall back
+    // to an operator-scoped `bridge-api` entry and function; under isolation there
+    // is no fallback at all, so it would run silently toolless and produce
+    // confidently wrong work. Refusing is the only safe reading.
+    const verifyRegistration = seams.verifyRequiredWorktreeMcpRegistration ?? verifyRequiredWorktreeMcpRegistration;
+    const registration = await verifyRegistration(worktreePath, deps);
+    if (!registration.ok) {
+        await httpClient.fail(job, {
+            error_kind: WorkerConfigIsolation,
+            error_message: registration.message,
+            classification: "crashed",
+            ...commitResidue(preSpawnTelemetry),
+            telemetry: observation.snapshot(),
+        });
+        return { status: "failed", reason: "worker_config_isolation" };
+    }
     // --- Worker log tee + watch registry + viewer tab (BAPI-535 §8) ------
     const registryDeps = buildJobLogRegistryDeps(deps);
     const markFinished = seams.markExecutorJobLogFinished ?? markExecutorJobLogFinished;
@@ -670,10 +1134,24 @@ async function runSpawnJob(job, httpClient, options, deps, ownership, observatio
     };
     // --- Spawn -----------------------------------------------------------
     const alias = resolveExecutorModelAlias(job.payload);
-    const argv = buildClaudeExecutorArgv(prompt, alias);
+    // BAPI-725: the posture resolved at the top of this function — after the deny
+    // layer has already been provisioned above, which is what keeps `acceptEdits`
+    // from being a relaxation of what the worker may do.
+    const argv = buildClaudeExecutorArgv(prompt, alias, permissionPosture);
     // BAPI-586: inject the validated run base as BAPI_BASE_BRANCH so the worker
     // can target it via `gh pr create --base "$BAPI_BASE_BRANCH"`.
-    const env = buildExecutorWorkerEnv(deps.env, effectiveBaseBranch);
+    // BAPI-731: the Claude/XDG paths come from the isolation handle established
+    // above — never from `deps.env`, which is exactly what makes them
+    // un-overridable by the operator's environment. The API key is read from the
+    // executor's own environment and passed explicitly because isolation removes
+    // the worker's previous (inherited-`HOME`) authentication path entirely; see
+    // the note in `env.ts` and inventory finding 4.
+    const env = buildExecutorWorkerEnv(deps.env, {
+        effectiveBaseBranch,
+        claudeConfigDir: isolation.claudeConfigDir,
+        xdgConfigHome: isolation.xdgConfigHome,
+        anthropicApiKey: deps.env.ANTHROPIC_API_KEY,
+    });
     let proc;
     try {
         proc = deps.spawnProcess(CLAUDE_EXECUTABLE, argv, { cwd: worktreePath, env });
@@ -697,6 +1175,10 @@ async function runSpawnJob(job, httpClient, options, deps, ownership, observatio
         }
         : proc;
     const collectTelemetry = () => collectGitTelemetry({ runCommand: deps.runCommand, now: deps.now }, worktreePath, effectiveBaseBranch);
+    // BAPI-731 (WS-H): sample the LOCAL remote-tracking marker so a mid-job push
+    // flushes telemetry promptly instead of waiting up to a full heartbeat
+    // interval. Local ref read only — never a network call on this path.
+    const collectRemoteMarker = () => collectRemoteTrackingSha({ runCommand: deps.runCommand }, worktreePath, branch);
     const procResult = await superviseProcess({
         job,
         httpClient,
@@ -707,9 +1189,37 @@ async function runSpawnJob(job, httpClient, options, deps, ownership, observatio
         proc: supervisedProc,
         timeoutSeconds: timeout.timeoutSeconds,
         collectTelemetry,
+        collectRemoteMarker,
     });
     // Final telemetry snapshot from the worktree.
-    observation.setGitTelemetry(await collectTelemetry());
+    const finalTelemetry = await collectTelemetry();
+    observation.setGitTelemetry(finalTelemetry);
+    // Only a SUCCESSFUL final HEAD read may close the attempt boundary. A degraded
+    // read leaves `attempt_end_sha` absent rather than relabeling an older sample.
+    if (typeof finalTelemetry.last_commit_sha === "string") {
+        observation.setAttemptEndSha(finalTelemetry.last_commit_sha);
+    }
+    // --- Server-requested stop (BAPI-731, WS-B executor half) -------------
+    // Handled BEFORE the abandonment check below, because the server stop is the
+    // one abandonment path that still owes a terminal report: the job was
+    // deliberately CANCELLED while the claim was still valid, so reporting it as a
+    // worker crash (the process was SIGKILLed, so its raw classification is
+    // `killed`) would be actively wrong. Ownership is marked abandoned only AFTER
+    // the terminal mutation is attempted, so the report goes out under a live claim.
+    if (procResult.serverStopRequested) {
+        await closeWorkerLogTee(tee);
+        await finalizeRegistry();
+        await httpClient.fail(job, {
+            error_kind: "ServerStopRequested",
+            error_message: "the server requested this run stop; the owned worker was terminated",
+            classification: "killed",
+            ...commitResidue(finalTelemetry),
+            telemetry: observation.snapshot(),
+        });
+        ownership.abandoned = true;
+        ownership.abandonReason = "server_stop";
+        return { status: "abandoned", reason: "server_stop" };
+    }
     // Finalize the log tee WITHOUT signaling the worker (it has already exited).
     await closeWorkerLogTee(tee);
     if (ownership.abandoned) {