@bridge_gpt/mcp-server 0.2.51 → 0.2.52

package/build/executor/http-client.js

@@ -1,3 +1,14 @@
+/**
+ * Executor `/executor/jobs/*` protocol HTTP client (BAPI-534, TDD §7, §10).
+ *
+ * Encapsulates the T2 protocol behind an injected `fetch` boundary with correct
+ * fencing-token semantics. The claim response `repo_name` and `claim_token` are
+ * echoed on every heartbeat/complete/fail (the server mutation guards are
+ * repo-bound and fenced on `claim_token`). The `X-API-Key` header value is never
+ * logged and never included in any error string.
+ */
+import { RECONCILER_LIVENESS_VALUES } from "./types.js";
+import { readEpicRunCompletionState, } from "../conductor/bridge-api-client.js";
 /** Bound a server-provided diagnostic snippet included in error strings. */
 function boundedDetail(text) {
     const trimmed = (text ?? "").trim();
@@ -39,13 +50,6 @@ function parseStopRequested(bodyText) {
  * (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.
@@ -76,17 +80,43 @@ export function parseReconcilerLivenessHeader(headers) {
 /**
  * Map a mutation (heartbeat/complete/fail) HTTP response onto the fencing
  * outcome. `allowInvalidResult` maps 422 to `invalid_job_result` (complete only).
+ *
+ * BAPI-1021 (AC-5): 401/403 map to `auth_fatal` with the exact status attached,
+ * BEFORE the generic `fatal_http_error` fallback — the response body is never
+ * retained on this path (never logged, never echoed into the returned metadata).
  */
 function mapMutationResponse(status, bodyText, allowInvalidResult) {
     if (status === 409)
-        return "stale_claim";
+        return { outcome: "stale_claim" };
     if (status === 503)
-        return "retry_later";
+        return { outcome: "retry_later" };
     if (status === 422 && allowInvalidResult)
-        return "invalid_job_result";
+        return { outcome: "invalid_job_result" };
     if (status >= 200 && status < 300 && isOkBody(bodyText))
-        return "updated";
-    return "fatal_http_error";
+        return { outcome: "updated" };
+    if (status === 401 || status === 403)
+        return { outcome: "auth_fatal", authHttpStatus: status };
+    return { outcome: "fatal_http_error" };
+}
+/**
+ * Adapt the executor's injected `FetchLike` transport to the narrower
+ * `ConductorFetch` shape the shared read-only Bridge API GET helper expects
+ * (BAPI-1010). GET-only; deliberately ignores the caller's `AbortSignal` —
+ * `FetchLike`'s production implementation (`createDefaultExecutorDeps`)
+ * already wraps every request in its own `AbortController` timeout, so no
+ * request is ever left uncancelled by discarding this one.
+ */
+function toConductorGetFetch(fetchLike) {
+    return async (url, init) => {
+        const requestInit = { method: "GET", headers: init.headers };
+        const res = await fetchLike(url, requestInit);
+        const text = await res.text();
+        return {
+            ok: res.status >= 200 && res.status < 300,
+            status: res.status,
+            json: async () => JSON.parse(text),
+        };
+    };
 }
 export function createExecutorHttpClient(config) {
     const base = config.baseUrl.replace(/\/+$/, "") + "/executor/jobs";
@@ -119,7 +149,7 @@ export function createExecutorHttpClient(config) {
         catch {
             // Transient network error — treat as fatal for a single mutation attempt;
             // the caller's retry/dead-man logic decides whether to keep the worker alive.
-            return "fatal_http_error";
+            return { outcome: "fatal_http_error" };
         }
     }
     return {
@@ -158,7 +188,18 @@ export function createExecutorHttpClient(config) {
                     return { kind: "fatal", error: "claim returned invalid JSON" };
                 }
             }
-            if (status === 401 || status === 403 || status === 422) {
+            if (status === 401 || status === 403) {
+                // BAPI-1021 (AC-5): carry the auth category + exact status alongside the
+                // existing error string, distinguishing this from the non-auth fatal 422
+                // contract response below without parsing `error`.
+                return {
+                    kind: "fatal",
+                    error: `claim rejected (HTTP ${status}): ${boundedDetail(text)}`,
+                    authCategory: "auth_fatal",
+                    authHttpStatus: status,
+                };
+            }
+            if (status === 422) {
                 return { kind: "fatal", error: `claim rejected (HTTP ${status}): ${boundedDetail(text)}` };
             }
             // 5xx and any other unexpected status are retryable.
@@ -171,13 +212,14 @@ export function createExecutorHttpClient(config) {
             let status;
             let text;
             try {
-                const res = await post(`/${job.id}/heartbeat`, {
+                const body = {
                     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);
+                };
+                const res = await post(`/${job.id}/heartbeat`, body, job.repo_name);
                 status = res.status;
                 text = res.text;
             }
@@ -186,8 +228,10 @@ export function createExecutorHttpClient(config) {
                 // 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 };
+            const mapped = mapMutationResponse(status, text, false);
+            const result = { outcome: mapped.outcome };
+            if (mapped.authHttpStatus !== undefined)
+                result.authHttpStatus = mapped.authHttpStatus;
             if (parseStopRequested(text))
                 result.stop_requested = true;
             return result;
@@ -211,7 +255,7 @@ export function createExecutorHttpClient(config) {
             }
         },
         complete(job, completion) {
-            return mutate(`/${job.id}/complete`, {
+            const body = {
                 repo_name: job.repo_name,
                 claim_token: job.claim_token,
                 job_type: completion.job_type,
@@ -222,10 +266,11 @@ export function createExecutorHttpClient(config) {
                 local_commit_count: completion.local_commit_count,
                 last_commit_sha: completion.last_commit_sha,
                 telemetry: completion.telemetry,
-            }, true, job.repo_name);
+            };
+            return mutate(`/${job.id}/complete`, body, true, job.repo_name);
         },
         fail(job, failure) {
-            return mutate(`/${job.id}/fail`, {
+            const body = {
                 repo_name: job.repo_name,
                 claim_token: job.claim_token,
                 error_kind: failure.error_kind,
@@ -234,7 +279,30 @@ export function createExecutorHttpClient(config) {
                 local_commit_count: failure.local_commit_count,
                 last_commit_sha: failure.last_commit_sha,
                 telemetry: failure.telemetry,
-            }, false, job.repo_name);
+            };
+            return mutate(`/${job.id}/fail`, body, false, job.repo_name);
+        },
+        /**
+         * Read-only epic-run completion-state projection (BAPI-1010). Delegates
+         * URL construction, timeout handling, response validation, and failure
+         * sanitization entirely to {@link readEpicRunCompletionState} — this
+         * method only resolves the repo-scoped access and adapts the transport.
+         * Never throws: `readEpicRunCompletionState` is itself non-throwing, and
+         * the try/catch below is belt-and-braces so a future change there can
+         * never surface an exception through this public contract.
+         */
+        async readEpicRunState(epicRunId, repoName) {
+            const access = {
+                repoName,
+                apiKey: keyForRepo(repoName),
+                baseUrl: config.baseUrl,
+            };
+            try {
+                return await readEpicRunCompletionState(access, epicRunId, toConductorGetFetch(config.fetch));
+            }
+            catch {
+                return { ok: false, reason: "network" };
+            }
         },
     };
 }

package/build/executor/job-errors.js

@@ -86,6 +86,14 @@
  *    alternative to reporting it is defaulting to Claude's behavior for an agent
  *    nobody implemented, which would spawn a real worker under containment the
  *    operator never declared.
+ *  - `ContractError.WorkerEnvFilePresent` — the worktree could not be CONFIRMED
+ *    free of `.env` / `.env.*` entries at the last moment before spawn
+ *    (BAPI-1019). An operator environment file inside a worker's worktree is how
+ *    Architecture Miss 28 happened: the worker resolved a real database from one
+ *    and a test harness then truncated that database. Fail-CLOSED, pre-spawn, and
+ *    NON-RETRYABLE — the condition is a property of the HOST's worktree tooling
+ *    rather than of the ticket, so the next job on the same host reproduces it
+ *    identically; see `env-file-guard.ts`.
  *
  * These kinds are deliberately DISTINCT from each other so the refusals stay
  * tellable apart in `executor_jobs.error_kind`.
@@ -123,6 +131,14 @@ export const ExecutorAdapterUnavailable = "ContractError.ExecutorAdapterUnavaila
  * alternative is running an attempt that may read a stale verdict as its own.
  */
 export const StaleArtifactCleanupFailed = "ContractError.StaleArtifactCleanupFailed";
+/**
+ * BAPI-1019 (A.4): the worktree still held — or could not be proven free of — an
+ * operator environment file at the spawn boundary. Sits beside
+ * {@link PreSpawnVerification} and {@link StaleArtifactCleanupFailed} because it
+ * is the same shape: a pre-spawn assertion about the worktree that refuses rather
+ * than proceeding on an unverified premise.
+ */
+export const WorkerEnvFilePresent = "ContractError.WorkerEnvFilePresent";
 /** Rendered in place of an empty name list, so "none" is never ambiguous. */
 export const EMPTY_MCP_SERVER_NAME_MARKER = "none";
 /** Bound the rendered name lists so a pathological registration cannot spam a job row. */
@@ -207,6 +223,25 @@ export const WORKTREE_BUSY_MESSAGE = "another executor job already holds this ti
     "second claim is refused rather than allowed in. The refusal is expected when two jobs exist " +
     "for one ticket; the job that holds the worktree continues normally, and this one is safe to " +
     "retry once it finishes. See the executor's stderr for the conflicting job id.";
+/**
+ * The fixed message posted with {@link WorkerEnvFilePresent} (BAPI-1019).
+ *
+ * FIXED and identity-free, following {@link WORKTREE_BUSY_MESSAGE} and
+ * {@link WORKER_STARTUP_FATAL_MESSAGE}: it states what was OBSERVED (an
+ * environment file was present in the worktree at spawn and could not be
+ * confirmed removed) and names the remediation, and it carries no worktree path,
+ * no username, no discovered filename, no link target, no file content, and no
+ * exception text. This string is stored on the job row and read back by anyone
+ * with access to the run; the attributable detail (job id, guard category) goes
+ * to the executor's own stderr, on the host that already has it.
+ *
+ * It does NOT say "retry" anywhere, deliberately. The condition recurs
+ * identically until an operator changes the host's worktree tooling.
+ */
+export const WORKER_ENV_FILE_PRESENT_MESSAGE = "an environment file was present in this job's worktree at spawn and could not be confirmed " +
+    "removed, so no worker was started. A worker that reads one resolves real credentials and a " +
+    "real database. Check the copy-ignored exclusions in .config/wt.toml and any local tooling " +
+    "that writes into worktrees.";
 // The Claude-specific matcher that used to live here moved into the Claude
 // executor adapter as `classifyClaudeAuthFailure` (BAPI-781). Recognizing one
 // CLI's not-logged-in output is precisely a per-agent capability, and leaving it
@@ -217,8 +252,14 @@ export const WORKTREE_BUSY_MESSAGE = "another executor job already holds this ti
 // classification onto a stable executor failure remains executor-owned, so an
 // adapter cannot invent its own error kinds or its own operator-facing
 // remediation text.
-/** Bound a failure message so no unbounded/secret-bearing text is posted. */
-const ERROR_MESSAGE_MAX_CHARS = 300;
+/**
+ * Bound a failure message so no unbounded/secret-bearing text is posted.
+ *
+ * EXPORTED (BAPI-1019) so a fixed-message contract test can assert against the
+ * same number {@link ExecutorNamedError} truncates at, rather than restating
+ * `300` and silently going vacuous the day the bound changes.
+ */
+export const ERROR_MESSAGE_MAX_CHARS = 300;
 /**
  * An `Error` subclass carrying a stable `errorKind` plus a bounded
  * `errorMessage`. Named executor failures default to the `crashed` wire

package/build/executor/job-runner.js

@@ -14,10 +14,10 @@
  * `spec_review`, plus per-job worker-log tee, watch registry, and optional
  * read-only viewer tabs wired around every spawned worker.
  */
-import { rm } from "node:fs/promises";
+import { rm, readdir, lstat, unlink } from "node:fs/promises";
 import os from "node:os";
 import { runHeartbeatLoop } from "./heartbeat.js";
-import { isExecutorNamedError, toExecutorFailure, secretFreeErrorMessage, MissingVerdictArtifact, PreSpawnVerification, RequiredMcpRegistration, McpSurfaceMismatch, WorkerStartupFatal, WORKER_STARTUP_FATAL_MESSAGE, formatMcpSurfaceMismatch, ClaudeNotAuthenticated, CLAUDE_NOT_AUTHENTICATED_MESSAGE, ExecutorAdapterUnavailable, ExecutorNamedError, WorktreeBusy, StaleArtifactCleanupFailed, WORKTREE_BUSY_MESSAGE, } from "./job-errors.js";
+import { isExecutorNamedError, toExecutorFailure, secretFreeErrorMessage, MissingVerdictArtifact, PreSpawnVerification, RequiredMcpRegistration, McpSurfaceMismatch, WorkerStartupFatal, WORKER_STARTUP_FATAL_MESSAGE, formatMcpSurfaceMismatch, ClaudeNotAuthenticated, CLAUDE_NOT_AUTHENTICATED_MESSAGE, ExecutorAdapterUnavailable, ExecutorNamedError, WorktreeBusy, StaleArtifactCleanupFailed, WORKTREE_BUSY_MESSAGE, WorkerEnvFilePresent, WORKER_ENV_FILE_PRESENT_MESSAGE, } from "./job-errors.js";
 import { buildConductorMergeAccessForExecutorJob, buildDefaultMergeLocalDeps, runExecutorMergeJob, MERGE_RETRYABLE, MERGE_FAILED, } from "./merge-job.js";
 import { createObservationState } from "./observation.js";
 import { getWorktreeMcpRegistrationTargets, normalizeWorktreePathForRegistration, provisionMcpRegistrationForWorktree, } from "../mcp-provisioning.js";
@@ -27,9 +27,13 @@ import { resolveExecutorAgentId } from "./agent-identity.js";
 import { createProcessTerminationController, runProcessWithTimeout } from "./process.js";
 import { prepareResumeSpawn } from "./resume-pre-spawn.js";
 import { renderPromptSpecPrompt } from "./prompt-spec.js";
+import { defaultResolveBinPath } from "../start-tickets-conductor.js";
+/** The packaged bin basename of the deterministic worker guard (BAPI-1020). */
+const WORKER_GUARD_BIN_FILENAME = "worker-guard-hook-bin.js";
 import { buildGenericSuccessResult, buildSmokeResult, commitResidue, readCompletionArtifacts, resolveJobTimeoutSeconds, } from "./results.js";
 import { sendTerminalMutationWithRetry } from "./terminal-mutation.js";
 import { removeStaleVerdictArtifacts } from "./stale-artifacts.js";
+import { stripWorkerEnvFiles } from "./env-file-guard.js";
 import { isVerdictJobType, readVerdictArtifact } from "./verdict-artifact.js";
 import { createWorkerLogTee, closeWorkerLogTee, distinctWorkerLogSessionIds, formatWorkerLogSessionInvariantWarning, teeAsyncIterable, } from "./worker-log.js";
 import { acquireExecutorWorktreeLock, } from "./worktree-lock.js";
@@ -499,6 +503,18 @@ async function superviseProcess(params) {
     isDoneRef.value = true;
     const loopOutcome = await hb;
     params.observation.setExitCode(result.exitCode);
+    if (loopOutcome.kind === "auth_fatal") {
+        // BAPI-1021 (AC-5): notify the runner immediately with ONLY the bounded
+        // identifiers — never carried onto `result` itself, so the process's own
+        // classification/completion handling is unaffected and the job continues
+        // to drain normally.
+        params.control?.reportAuthFatal?.({
+            jobId: params.job.id,
+            repoName: params.job.repo_name,
+            category: "heartbeat",
+            httpStatus: loopOutcome.httpStatus,
+        });
+    }
     return loopOutcome.kind === "server_stop"
         ? { ...result, serverStopRequested: true }
         : result;
@@ -515,7 +531,33 @@ function terminalToRunResult(terminal, successStatus) {
             return { status: "abandoned", reason: "deadman" };
         case "skipped":
             return { status: "abandoned", reason: "already_abandoned" };
+        case "auth_fatal":
+            // BAPI-1021 (AC-5): a halted authentication/access condition, not an
+            // ordinary job failure or a lost/stale claim — `reportAuthFatal` (called
+            // by the wrapper below, before this mapping runs) is what actually
+            // notifies the runner.
+            return { status: "abandoned", reason: "auth_fatal" };
+    }
+}
+/**
+ * BAPI-1021 (AC-5): send a terminal mutation via
+ * {@link sendTerminalMutationWithRetry}, and — on an `auth_fatal` outcome —
+ * notify the runner exactly once via `control.reportAuthFatal`, carrying ONLY
+ * the job ID, repository, operation category, and HTTP status. Every other
+ * outcome passes through completely unchanged.
+ */
+async function sendTerminalMutationWithAuthReport(params, job, control) {
+    const terminal = await sendTerminalMutationWithRetry(params);
+    if (terminal.outcome === "auth_fatal") {
+        const notice = {
+            jobId: job.id,
+            repoName: job.repo_name,
+            category: params.kind,
+            httpStatus: terminal.httpStatus,
+        };
+        control?.reportAuthFatal?.(notice);
     }
+    return terminal;
 }
 /** Dispatch and run a single claimed job. */
 export async function runClaimedJob(job, httpClient, options, deps, _report, seams = {}, 
@@ -549,10 +591,10 @@ control) {
     // ensure/recreate or worker-spawn logic — it ensures no worktree and spawns no
     // worker (TDD §5/§9).
     if (job.job_type === "merge") {
-        return runMergeJob(job, httpClient, options, deps, ownership, observation, seams);
+        return runMergeJob(job, httpClient, options, deps, ownership, observation, seams, control);
     }
     if (job.job_type === "smoke") {
-        return runSmokeJob(job, httpClient, options, deps, ownership, observation);
+        return runSmokeJob(job, httpClient, options, deps, ownership, observation, control);
     }
     // `implement`/`resume`/`spec_review` and the recovery jobs (`remediate`/
     // `ci_fix`/`rebase`) all run through the real headless-spawn path — dispatched
@@ -640,7 +682,7 @@ function createMergeFlowProcess(startMerge) {
  * ignored. The local merge executor's outcome otherwise drives `/complete`
  * (success) or `/fail`; stale/retry/invalid terminal outcomes reuse T3a handling.
  */
-async function runMergeJob(job, httpClient, options, deps, ownership, observation, seams) {
+async function runMergeJob(job, httpClient, options, deps, ownership, observation, seams, control) {
     // Resolve + enforce payload.timeout_seconds BEFORE starting any merge work.
     const timeout = resolveJobTimeoutSeconds(job, options.defaultJobTimeoutSeconds);
     if (!timeout.ok) {
@@ -664,6 +706,7 @@ async function runMergeJob(job, httpClient, options, deps, ownership, observatio
         proc: flow.proc,
         timeoutSeconds,
         collectTelemetry: async () => ({}),
+        control,
     });
     // Ownership abandonment (stale-claim / dead-man) wins: never send a terminal
     // mutation for a claim we no longer own, and never process a late outcome.
@@ -673,7 +716,7 @@ async function runMergeJob(job, httpClient, options, deps, ownership, observatio
     // Overall merge flow timed out: fail the active claim as RETRYABLE and ignore
     // any later merge promise resolution (the abort has already been signalled).
     if (procResult.classification === "timeout") {
-        const terminal = await sendTerminalMutationWithRetry({
+        const terminal = await sendTerminalMutationWithAuthReport({
             kind: "fail",
             send: () => httpClient.fail(job, {
                 error_kind: MERGE_RETRYABLE,
@@ -685,13 +728,13 @@ async function runMergeJob(job, httpClient, options, deps, ownership, observatio
             options,
             ownership,
             log: deps.log,
-        });
+        }, job, control);
         return terminalToRunResult(terminal, "failed");
     }
     // A thrown error inside the merge flow maps to a bounded MergeFailed.
     const flowError = flow.getError();
     if (flowError !== undefined) {
-        const terminal = await sendTerminalMutationWithRetry({
+        const terminal = await sendTerminalMutationWithAuthReport({
             kind: "fail",
             send: () => httpClient.fail(job, {
                 error_kind: MERGE_FAILED,
@@ -703,14 +746,14 @@ async function runMergeJob(job, httpClient, options, deps, ownership, observatio
             options,
             ownership,
             log: deps.log,
-        });
+        }, job, control);
         return terminalToRunResult(terminal, "failed");
     }
     const outcome = flow.getOutcome();
     if (outcome === undefined) {
         // Clean process result with no stored outcome — an internal invariant break;
         // fail loud rather than silently reporting success.
-        const terminal = await sendTerminalMutationWithRetry({
+        const terminal = await sendTerminalMutationWithAuthReport({
             kind: "fail",
             send: () => httpClient.fail(job, {
                 error_kind: MERGE_FAILED,
@@ -722,7 +765,7 @@ async function runMergeJob(job, httpClient, options, deps, ownership, observatio
             options,
             ownership,
             log: deps.log,
-        });
+        }, job, control);
         return terminalToRunResult(terminal, "failed");
     }
     if (outcome.ok) {
@@ -733,24 +776,24 @@ async function runMergeJob(job, httpClient, options, deps, ownership, observatio
             result: outcome.result,
             telemetry: observation.snapshot(),
         };
-        const terminal = await sendTerminalMutationWithRetry({
+        const terminal = await sendTerminalMutationWithAuthReport({
             kind: "complete",
             send: () => httpClient.complete(job, completion),
             deps,
             options,
             ownership,
             log: deps.log,
-        });
+        }, job, control);
         return terminalToRunResult(terminal, "completed");
     }
-    const terminal = await sendTerminalMutationWithRetry({
+    const terminal = await sendTerminalMutationWithAuthReport({
         kind: "fail",
         send: () => httpClient.fail(job, { ...outcome.failure, telemetry: observation.snapshot() }),
         deps,
         options,
         ownership,
         log: deps.log,
-    });
+    }, job, control);
     return terminalToRunResult(terminal, "failed");
 }
 /**
@@ -767,7 +810,7 @@ async function runMergeJob(job, httpClient, options, deps, ownership, observatio
  * 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) {
+async function runSmokeJob(job, httpClient, options, deps, ownership, observation, control) {
     const timeout = resolveJobTimeoutSeconds(job, options.defaultJobTimeoutSeconds);
     if (!timeout.ok) {
         // Consistent with runSpawnJob: a timeout-contract failure fails the job
@@ -796,6 +839,7 @@ async function runSmokeJob(job, httpClient, options, deps, ownership, observatio
         proc,
         timeoutSeconds,
         collectTelemetry: async () => ({}),
+        control,
     });
     if (ownership.abandoned) {
         return { status: "abandoned", reason: ownership.abandonReason };
@@ -813,14 +857,14 @@ async function runSmokeJob(job, httpClient, options, deps, ownership, observatio
         result,
         telemetry: observation.snapshot(),
     };
-    const terminal = await sendTerminalMutationWithRetry({
+    const terminal = await sendTerminalMutationWithAuthReport({
         kind: "complete",
         send: () => httpClient.complete(job, completion),
         deps,
         options,
         ownership,
         log: deps.log,
-    });
+    }, job, control);
     return terminalToRunResult(terminal, "completed");
 }
 /**
@@ -1284,6 +1328,14 @@ async function runPreparedSpawn(params) {
             worktreePath,
             baseBranch: effectiveBaseBranch,
             homedir: deps.homedir(),
+            // BAPI-1020 — the prepared worktree's own branch and the packaged guard bin.
+            // `branch` comes from `prepareSpawn`'s `wt.branch`, i.e. the worktree the
+            // executor actually created, never from job payload text: the guard decides
+            // "is this push destination mine?" by comparing against it, so a value the
+            // payload could influence would let a job nominate its own safe branch.
+            workerBranch: branch,
+            workerGuardHookBinPath: (seams.resolveWorkerGuardBinPath ??
+                (() => defaultResolveBinPath(WORKER_GUARD_BIN_FILENAME)))(),
         });
         // Log on WARNING PRESENCE, not on `!ok` (BAPI-815/R2). The git-exclude
         // hygiene step can degrade without failing the deny layer — present-but-
@@ -1354,6 +1406,13 @@ async function runPreparedSpawn(params) {
             writeFile: deps.writeFile,
             appendFile: deps.appendFile,
             platform: deps.platform,
+            // BAPI-1021 (AC-6): the archive seams. All optional on `ExecutorDeps`
+            // already, so this is source-compatible with every existing deps
+            // builder — archival simply does not run when either is absent.
+            rename: deps.rename,
+            stat: deps.stat,
+            now: deps.now,
+            errorLog: deps.errorLog,
         });
     }
     catch {
@@ -1476,6 +1535,10 @@ async function runPreparedSpawn(params) {
             mcpConfigPath: mcpContract.configPath,
             effectiveBaseBranch,
             indexScope,
+            // BAPI-1020 — becomes `BAPI_WORKER_BRANCH` in the worker environment, which
+            // is the deterministic guard's only source of branch identity. Same
+            // provenance as the deny-provisioning value above: the prepared worktree.
+            workerBranch: branch,
             parentEnv: deps.env,
         });
         assertUsableSpawnShape(spawnShape, adapter);
@@ -1514,6 +1577,44 @@ async function runPreparedSpawn(params) {
         return { status: "failed", reason: "executor_adapter_unavailable" };
     }
     const mcpSurface = createMcpSurfaceObserver(mcpContract.expectedServerNames, (line) => initParsing.value.parseInitEvent(line));
+    // --- Worker env-file strip (FAIL-CLOSED, BAPI-1019/A.4) ---------------
+    // THE LAST thing that touches the worktree before a worker exists. Placed
+    // after the deny layer, after MCP provisioning and its verification, and after
+    // spawn-shape/observer construction precisely so nothing that runs later can
+    // re-introduce a file the guard just confirmed gone. Everything between this
+    // call and `deps.spawnProcess` below is pure in-memory work.
+    //
+    // Fail-CLOSED, following `StaleArtifactCleanupFailed` rather than the
+    // fail-OPEN deny-layer posture two hundred lines up. The deny layer shrinks a
+    // safety margin when it degrades; this gate is the margin. Architecture Miss 28
+    // was a worker that reached the operator's real database through a copied
+    // `.env` and truncated it — so "could not confirm the worktree is clean" must
+    // refuse, never proceed and hope.
+    const stripEnvFiles = seams.stripWorkerEnvFiles ?? stripWorkerEnvFiles;
+    const stripped = await stripEnvFiles(worktreePath, {
+        readdir: (dirPath) => readdir(dirPath),
+        // `lstat`/`unlink` only — the guard must never resolve a symlink, because an
+        // entry pointing at the main checkout would resolve to the operator's real
+        // `.env` and unlinking THAT would delete it. The narrow bag is the
+        // enforcement: no `stat`, `readlink`, or `readFile` is reachable from here.
+        lstat: (target) => lstat(target),
+        unlink: (target) => unlink(target),
+        platform: deps.platform,
+    });
+    if (!stripped.ok) {
+        await closeWorkerLog();
+        await finalizeRegistry();
+        // Exactly ONE bounded stderr line: the job id and the closed guard category.
+        // No worktree path (it carries a username), no removed filename, no errno, no
+        // exception text.
+        deps.errorLog(`[executor] job ${job.id}: refusing to spawn, worker env files unconfirmed: ${stripped.category}`);
+        await httpClient.fail(job, {
+            error_kind: WorkerEnvFilePresent,
+            error_message: WORKER_ENV_FILE_PRESENT_MESSAGE,
+            classification: "crashed",
+        });
+        return { status: "failed", reason: "worker_env_file_present" };
+    }
     let proc;
     try {
         proc = deps.spawnProcess(spawnShape.executable, spawnShape.argv, {
@@ -1583,6 +1684,7 @@ async function runPreparedSpawn(params) {
         // and an MCP containment refusal all converge on one `SIGTERM` and one grace
         // timer for this child (BAPI-828).
         terminationController,
+        control,
     });
     // --- Adapter lifecycle (EXPLICIT, BAPI-781) ---------------------------
     // Consumed rather than assumed. Claude declares `{ kind: "none" }` and so
@@ -1742,14 +1844,14 @@ async function runPreparedSpawn(params) {
                         classification: "crashed",
                     };
                 await finalizeRegistry();
-                const terminal = await sendTerminalMutationWithRetry({
+                const terminal = await sendTerminalMutationWithAuthReport({
                     kind: "fail",
                     send: () => httpClient.fail(job, { ...failure, ...commitResidue(git), telemetry: observation.snapshot() }),
                     deps,
                     options,
                     ownership,
                     log: deps.log,
-                });
+                }, job, control);
                 return terminalToRunResult(terminal, "failed");
             }
             // BAPI-528 Wave 3 M2: verdict jobs (`spec_review`) also produce a
@@ -1769,14 +1871,14 @@ async function runPreparedSpawn(params) {
                 ...commitResidue(git),
                 telemetry: observation.snapshot(),
             };
-            const terminal = await sendTerminalMutationWithRetry({
+            const terminal = await sendTerminalMutationWithAuthReport({
                 kind: "complete",
                 send: () => httpClient.complete(job, completion),
                 deps,
                 options,
                 ownership,
                 log: deps.log,
-            });
+            }, job, control);
             await finalizeRegistry();
             return terminalToRunResult(terminal, "completed");
         }
@@ -1806,7 +1908,7 @@ async function runPreparedSpawn(params) {
         });
         if (!finalization.ok) {
             await finalizeRegistry();
-            const terminal = await sendTerminalMutationWithRetry({
+            const terminal = await sendTerminalMutationWithAuthReport({
                 kind: "fail",
                 send: () => httpClient.fail(job, {
                     ...finalization.failure,
@@ -1817,7 +1919,7 @@ async function runPreparedSpawn(params) {
                 options,
                 ownership,
                 log: deps.log,
-            });
+            }, job, control);
             return terminalToRunResult(terminal, "failed");
         }
         // BAPI-862: attach the pull request the EXECUTOR verified. `pr_url` was never
@@ -1840,14 +1942,14 @@ async function runPreparedSpawn(params) {
             ...commitResidue(git),
             telemetry: observation.snapshot(),
         };
-        const terminal = await sendTerminalMutationWithRetry({
+        const terminal = await sendTerminalMutationWithAuthReport({
             kind: "complete",
             send: () => httpClient.complete(job, completion),
             deps,
             options,
             ownership,
             log: deps.log,
-        });
+        }, job, control);
         await finalizeRegistry();
         return terminalToRunResult(terminal, "completed");
     }
@@ -1869,7 +1971,7 @@ async function runPreparedSpawn(params) {
     const authDetection = adapter.authFailureDetection;
     const authFailure = authDetection?.supported === true &&
         authDetection.value.classify(procResult.stdoutExcerpt).notAuthenticated;
-    const terminal = await sendTerminalMutationWithRetry({
+    const terminal = await sendTerminalMutationWithAuthReport({
         kind: "fail",
         send: () => httpClient.fail(job, {
             error_kind: authFailure ? ClaudeNotAuthenticated : classificationToErrorKind(procResult.classification),
@@ -1884,6 +1986,6 @@ async function runPreparedSpawn(params) {
         options,
         ownership,
         log: deps.log,
-    });
+    }, job, control);
     return terminalToRunResult(terminal, "failed");
 }