@bridge_gpt/mcp-server 0.2.51 → 0.2.52

package/build/env-file-link.js

@@ -0,0 +1,164 @@
+/**
+ * Interactive worktree environment-file LINKING (BAPI-1019, Slice A / A.2).
+ *
+ * Architecture Miss 28 was a conductor worker that truncated the operator's real
+ * operational database. It could reach that database because Worktrunk's
+ * `copy-ignored` step had placed a COPY of the operator's `.env` inside the
+ * worker's worktree. BAPI-1019 removes `.env*` from that copy step at source
+ * (`.config/wt.toml`), which fixes the executor case outright — an executor
+ * worktree must hold neither a copy nor a link — but it also takes `.env` away
+ * from the INTERACTIVE worktrees a human actually works in, which legitimately
+ * need it.
+ *
+ * This module gives that file back by REFERENCE rather than by value. For each
+ * supported name present in the main checkout it creates
+ * `<worktree>/<name>` as a SYMLINK to the main checkout's file, so an operator's
+ * secrets exist exactly once at rest no matter how many worktrees are open, and
+ * editing the operator's `.env` is immediately visible everywhere instead of
+ * drifting per worktree.
+ *
+ * CONTAINMENT RULES, all load-bearing:
+ *
+ *  - This module is for the INTERACTIVE path only. `createWorktrees()` in
+ *    `start-tickets.ts` is its sole production caller; `ensureExecutorWorktree()`
+ *    must never call it. An executor worktree that held a link would resolve to
+ *    the operator's real `.env` exactly as a copy did.
+ *  - It NEVER reads or logs file CONTENTS. Its whole dependency surface is
+ *    metadata (`stat`/`lstat`), link creation, unlinking, and — only on a
+ *    platform that cannot make links — a copy. There is deliberately no
+ *    `readFile` seam to misuse.
+ *  - Its returned warnings are FIXED text plus a closed category. No absolute
+ *    path, username, resolved link target, file content, or exception text
+ *    reaches the caller, because these strings surface in `start-tickets`'
+ *    operator-facing summary.
+ *  - A destination that already exists as a REGULAR FILE (a copy left behind by
+ *    an earlier run, before this ticket) is replaced with a link. That is the
+ *    migration path off the old behavior: leaving the copy in place would leave
+ *    the second at-rest copy this ticket exists to remove.
+ *
+ * ACCEPTED WINDOWS GAP. Creating a symlink on Windows requires Developer Mode or
+ * an elevated process, so `symlink` there commonly fails with `EPERM`. On that
+ * recognized failure this module falls back to a COPY and returns a warning
+ * rather than throwing: an interactive Windows worktree with a copied `.env` is
+ * the behavior operators already had, whereas a hard failure would break worktree
+ * creation outright. The residual second-copy-at-rest gap on Windows is recorded
+ * as accepted in the ticket's exploration ("Criteria Coverage"), not as a defect
+ * to solve here. It does NOT weaken the executor guarantee, which is enforced by
+ * `executor/env-file-guard.ts` on every platform.
+ */
+import { pathApiForPlatform } from "./worktree-core.js";
+/**
+ * The operator environment files an interactive worktree may receive by link.
+ *
+ * A CLOSED list, not a glob. `.env` and `.env.test` are the two files this
+ * repository's own tooling reads; matching `.env.*` here would start linking
+ * whatever an operator happens to have lying around (`.env.production`,
+ * `.env.backup`) into every worktree, which is a wider blast radius than the
+ * problem needs. The executor's strip, by contrast, is deliberately a WIDE
+ * pattern — removing too much from a worker is safe, linking too much is not.
+ */
+export const LINKED_OPERATOR_ENV_FILES = [".env", ".env.test"];
+/**
+ * The FIXED warning texts. Basenames are the only variable part, and a basename
+ * is a constant from {@link LINKED_OPERATOR_ENV_FILES} rather than anything
+ * discovered on disk — so no path, username, or secret can enter these strings.
+ */
+function symlinkUnsupportedWarning(name) {
+    return {
+        category: "symlink_unsupported",
+        message: `worktree ${name}: this platform could not create a symbolic link, so the file was ` +
+            "copied instead. The worktree now holds a second copy of that environment file at " +
+            "rest. On Windows, enable Developer Mode (or run elevated) to get links instead.",
+    };
+}
+function linkFailedWarning(name) {
+    return {
+        category: "link_failed",
+        message: `worktree ${name}: could not be provided from the main checkout, so this worktree has ` +
+            "no copy of it. Commands that need it will fail until it is linked by hand.",
+    };
+}
+/**
+ * Error codes that mean "this platform/filesystem cannot make a symlink here",
+ * as opposed to an ordinary failure. `EPERM` is the Windows non-Developer-Mode
+ * signature; the rest cover filesystems and runtimes without link support.
+ */
+const SYMLINK_UNSUPPORTED_CODES = new Set([
+    "EPERM",
+    "ENOSYS",
+    "EOPNOTSUPP",
+    "ENOTSUP",
+    "UNKNOWN",
+]);
+function errorCode(err) {
+    if (!err || typeof err !== "object")
+        return undefined;
+    const code = err.code;
+    return typeof code === "string" ? code : undefined;
+}
+/** True when two metadata records describe the same underlying file. */
+function sameFile(a, b) {
+    if (!a || !b)
+        return false;
+    return a.dev === b.dev && a.ino === b.ino;
+}
+/**
+ * Provide the main checkout's operator environment files to an interactive
+ * worktree as symlinks.
+ *
+ * Never throws: every per-name failure becomes a fixed warning, because a
+ * worktree that was created successfully must not be reported as failed just
+ * because a convenience link could not be made. A name whose SOURCE is absent in
+ * the main checkout is an ordinary no-op with no warning at all — most checkouts
+ * have `.env` and no `.env.test`, and warning about that would train operators to
+ * ignore this channel.
+ */
+export async function linkOperatorEnvFiles(mainCheckout, worktreePath, deps) {
+    const pathApi = pathApiForPlatform(deps.platform ?? process.platform);
+    const result = { linked: [], copied: [], unchanged: [], warnings: [] };
+    for (const name of LINKED_OPERATOR_ENV_FILES) {
+        const source = pathApi.join(mainCheckout, name);
+        const destination = pathApi.join(worktreePath, name);
+        try {
+            // The main checkout is the authority on whether this name exists at all.
+            // Checked FIRST so a missing source touches the destination in no way.
+            const sourceStats = await deps.stat(source);
+            if (!sourceStats || !sourceStats.isFile())
+                continue;
+            const existing = await deps.lstat(destination);
+            if (existing) {
+                if (existing.isSymbolicLink() && sameFile(await deps.stat(destination), sourceStats)) {
+                    // Already pointing at this exact file. Re-creating it would be churn,
+                    // and every unlink of a correct entry is a window in which the worktree
+                    // has no `.env` at all.
+                    result.unchanged.push(name);
+                    continue;
+                }
+                // A stale link, or a regular-file copy from before this ticket. Remove
+                // the ENTRY — `unlink` never follows, so the main checkout's real file is
+                // untouched even when the entry is a link pointing straight at it.
+                await deps.unlink(destination);
+            }
+            try {
+                await deps.symlink(source, destination);
+                result.linked.push(name);
+            }
+            catch (err) {
+                if (!SYMLINK_UNSUPPORTED_CODES.has(errorCode(err) ?? ""))
+                    throw err;
+                // The accepted platform gap. Fall back to the old behavior rather than
+                // leaving the worktree without a file it needs.
+                await deps.copyFile(source, destination);
+                result.copied.push(name);
+                result.warnings.push(symlinkUnsupportedWarning(name));
+            }
+        }
+        catch {
+            // Bounded on purpose: the caught error is never inspected for text, only
+            // discarded. A filesystem error message can carry an absolute path (which
+            // contains a username) and this string is printed to an operator summary.
+            result.warnings.push(linkFailedWarning(name));
+        }
+    }
+    return result;
+}

package/build/epic-integration-pr.js

@@ -21,6 +21,12 @@ export const EPIC_INTEGRATION_PR_WRITE_TIMEOUT_MS = 20_000;
 /** Bounded result count for the existence probe. */
 const LIST_LIMIT = 20;
 const PR_LIST_JSON_FIELDS = "number,headRefName,baseRefName,isDraft";
+/**
+ * `epic/<KEY>` prefix a child PR's base branch carries under BAPI-949/BAPI-950.
+ * Exported (BAPI-1010) so every call site that derives an epic key from a base
+ * branch shares one definition instead of re-declaring a private literal.
+ */
+export const EPIC_BRANCH_PREFIX = "epic/";
 /** The production call sites this helper is invoked from. */
 export const EPIC_INTEGRATION_PR_COMMANDS = [
     "setup-epic",
@@ -28,6 +34,10 @@ export const EPIC_INTEGRATION_PR_COMMANDS = [
     "conduct-epic catch-up",
     "conduct-epic finish",
     "executor merge",
+    // BAPI-1010: the executor's one-shot wind-down observer, distinct from
+    // "executor merge" so the generated PR body and diagnostics never mislabel
+    // a done-state readiness request as a ticket merge enrichment.
+    "executor wind-down",
 ];
 /** Only the sanctioned safe fields. Never raw command output. */
 export function formatEpicIntegrationPullRequestOutcome(outcome) {

package/build/executor/cli.js

@@ -40,7 +40,11 @@ export function getExecutorUsage() {
         "  --repo <name>                 Repo to serve (repeatable).",
         "  --repos=<a,b>                 Comma-separated repos.",
         "  --epic-run-id <id>            Dedicate this executor to an epic run (repeatable).",
-        "                                Omit for the default repository-wide behavior.",
+        "  --repo-wide                   Explicit compatibility opt-out: claim from every",
+        "                                authorized repo, oldest-first, unscoped by run.",
+        "                                Exactly one of --epic-run-id or --repo-wide is",
+        "                                REQUIRED; omitting both is a startup error, not",
+        "                                repository-wide claiming (BAPI-1026 / R54).",
         "  --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).",
@@ -83,6 +87,7 @@ function isValidEpicRunId(value) {
 export function parseExecutorArgs(argv, context) {
     const repos = [];
     const epicRunIds = [];
+    let repoWide = false;
     let executorId;
     let maxConcurrent = DEFAULT_MAX_CONCURRENT;
     let once = false;
@@ -122,6 +127,9 @@ export function parseExecutorArgs(argv, context) {
             if (!epicRunIds.includes(trimmed))
                 epicRunIds.push(trimmed);
         }
+        else if (arg === "--repo-wide") {
+            repoWide = true;
+        }
         else if (arg === "--executor-id") {
             executorId = argv[++i];
             if (!executorId)
@@ -182,6 +190,29 @@ export function parseExecutorArgs(argv, context) {
     const executorIdFinal = executorId && executorId.trim().length > 0
         ? executorId.trim()
         : `${context.hostname}-${context.pid}`;
+    // BAPI-1026 (R54) — the claim scope is now MANDATORY and explicit.
+    //
+    // Before this ticket, omitting `--epic-run-id` silently meant "claim the
+    // oldest queued row of ANY run in every authorized repo", which is how an
+    // executor could take a job belonging to an abandoned run (BAPI-993 B2). The
+    // server no longer treats an omitted scope as repository-wide once its
+    // deprecation window closes, so an executor started with no scope would poll
+    // forever and claim nothing. Refusing to START is the loud failure that
+    // replaces that silent idle: a misconfiguration is a startup error, visible
+    // immediately, rather than an executor that looks healthy and does no work.
+    if (repoWide && epicRunIds.length > 0) {
+        return {
+            kind: "error",
+            message: "--repo-wide cannot be combined with --epic-run-id: pass one claim scope, not both",
+        };
+    }
+    if (!repoWide && epicRunIds.length === 0) {
+        return {
+            kind: "error",
+            message: "a claim scope is required: pass --epic-run-id <id> (repeatable) to serve " +
+                "specific epic runs, or --repo-wide to deliberately claim repository-wide",
+        };
+    }
     const options = {
         executorId: executorIdFinal,
         repos,
@@ -208,6 +239,9 @@ export function parseExecutorArgs(argv, context) {
         // was supplied, so downstream `epicRunIds !== undefined` checks (the claim
         // manifest builder, startup diagnostics) see an unambiguous "unscoped".
         ...(epicRunIds.length > 0 ? { epicRunIds } : {}),
+        // BAPI-1026 (R54) — same "truly absent, never a falsy placeholder"
+        // discipline: `repoWide` is either `true` or the key is missing.
+        ...(repoWide ? { repoWide: true } : {}),
     };
     return { kind: "ok", options };
 }
@@ -267,14 +301,15 @@ export async function runExecutorCli(argv, overrides = {}) {
         return 1;
     }
     const options = parsed.options;
-    // BAPI-794 — startup diagnostics: only non-secret run identifiers, never
-    // credentials, job payloads, or command arguments beyond the run IDs
-    // themselves (which are not secrets — see EPIC_RUN_ID_PATTERN's docstring).
+    // BAPI-794/BAPI-1026 — startup diagnostics: a bounded MODE label and, when
+    // scoped, only the COUNT of runs. Never credentials, job payloads, command
+    // arguments — and, since BAPI-1026, never the run IDs either, matching the
+    // per-claim logging policy the server side already enforces.
     if (options.epicRunIds !== undefined) {
-        errorLog(`executor scoped to epic run(s): ${options.epicRunIds.join(", ")}`);
+        errorLog(`executor claim scope: scoped (epic_run_count=${options.epicRunIds.length})`);
     }
     else {
-        errorLog("executor running repository-wide (no --epic-run-id configured)");
+        errorLog("executor claim scope: repo_wide (explicit --repo-wide)");
     }
     // The mutating executor requires an EXPLICIT base URL (BAPI-676): `--base-url`
     // then `BAPI_BASE_URL`, never an implicit production default. Fail here —

package/build/executor/deps.js

@@ -9,7 +9,7 @@
  */
 import { execFile, spawn } from "node:child_process";
 import { existsSync } from "node:fs";
-import { open, readFile, writeFile, appendFile, mkdir, mkdtemp, chmod, rm, readdir, lstat, stat, statfs, } from "node:fs/promises";
+import { open, readFile, writeFile, appendFile, mkdir, mkdtemp, chmod, rm, rename, 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";
@@ -92,6 +92,10 @@ export function createDefaultExecutorDeps() {
             }
         },
         removeFile: (filePath) => rm(filePath, { force: true }),
+        // BAPI-1021 (AC-6): worker-log archival's rename seam. Real `fs.promises.rename`
+        // rejects with `code: "EXDEV"` across filesystems/devices, which worker-log.ts
+        // treats as an ordinary best-effort archive failure like any other.
+        rename: (oldPath, newPath) => rename(oldPath, newPath),
         stat: (filePath) => stat(filePath).then((s) => ({ mode: s.mode })),
         statMtimeMs: (filePath) => stat(filePath)
             .then((s) => s.mtimeMs)

package/build/executor/env-file-guard.js

@@ -0,0 +1,113 @@
+/**
+ * Fail-closed pre-spawn env-file strip for an executor worktree (BAPI-1019, A.3).
+ *
+ * Architecture Miss 28: a v2 conductor worker ran an allowed `pytest` whose
+ * harness truncated the operator's real operational database. The worker could
+ * reach that database because its worktree carried a copy of the operator's
+ * `.env`, delivered by Worktrunk's `copy-ignored` step. `.config/wt.toml` now
+ * excludes `.env*` from that copy, which removes the cause — but Worktrunk runs
+ * `post-start` hooks in the BACKGROUND after `wt switch` returns, and any local
+ * tooling an operator adds can write into a worktree at any time. A source-level
+ * exclusion therefore cannot be the whole answer: the executor has to check, at
+ * the last possible moment, that the worktree it is about to hand a worker is
+ * actually free of environment files.
+ *
+ * That is this module. It runs as the FINAL step before `deps.spawnProcess` and
+ * it fails CLOSED — following `StaleArtifactCleanupFailed`, not the fail-open
+ * deny-layer posture. "Could not confirm clean" and "confirmed clean" must be
+ * distinguishable outcomes, and only the second one is allowed to spawn.
+ *
+ * THE SINGLE MOST IMPORTANT DETAIL: this module uses `lstat` and `unlink` and
+ * NEVER follows a symbolic link. An interactive worktree's `.env` is a symlink
+ * into the main checkout (see `../env-file-link.ts`), and if an entry like that
+ * ever appeared in an executor worktree, resolving it and unlinking the RESOLVED
+ * target would delete the operator's real `.env`. `unlink` removes the directory
+ * entry itself, so a link is removed as a link. There is deliberately no `stat`,
+ * `realpath`, `readlink`, or `readFile` in the dependency surface — the guarantee
+ * is enforced by what the module cannot reach, not by remembering not to call it.
+ *
+ * The re-list after removal is what makes the two outcomes tellable apart. An
+ * unreadable directory, a failed `lstat`, a failed `unlink`, or a surviving entry
+ * all produce `ok: false`; only a second listing that shows no matching entry
+ * produces `ok: true`.
+ *
+ * REDACTION. A failure returns a fixed CATEGORY and nothing else — no filename,
+ * no path, no resolved target, no exception text. This value reaches the job row
+ * and the executor's stderr, and a worktree path contains an operator's username.
+ * Successful `removed` names are safe by construction: they are basenames drawn
+ * from a fixed pattern, and knowing that `.env` was removed is the diagnostic. See
+ * `secretFreeErrorMessage()` / `ERROR_MESSAGE_MAX_CHARS` in `job-errors.ts` for
+ * the bounding posture these strings satisfy.
+ */
+import { pathApiForExecutorPlatform } from "./worktree-inspection.js";
+/**
+ * True for `.env` and anything under the `.env.` prefix.
+ *
+ * Deliberately WIDER than the interactive linker's closed two-name list: removing
+ * too much from a worker worktree is harmless, and an operator's `.env.staging`
+ * is exactly as dangerous as their `.env`. It is still a PREFIX rule, not a
+ * substring one — `.envrc` (direnv) and `.envx` do not match, because they are
+ * not environment files this contract is about and silently deleting an
+ * operator's direnv config would be a surprise well outside this ticket.
+ */
+export function isWorkerEnvFileName(name) {
+    return name === ".env" || name.startsWith(".env.");
+}
+/**
+ * Strip every `.env` / `.env.*` entry from a worktree ROOT and prove it worked.
+ *
+ * Only the root is examined. A nested `.env` (a fixture under `tests/`, a
+ * vendored example) is not what reaches a process's environment loader, and
+ * walking the tree would turn a fast pre-spawn gate into an unbounded traversal
+ * of a whole checkout.
+ */
+export async function stripWorkerEnvFiles(worktreePath, deps) {
+    const pathApi = pathApiForExecutorPlatform(deps.platform ?? process.platform);
+    let entries;
+    try {
+        entries = await deps.readdir(worktreePath);
+    }
+    catch {
+        // Cannot even see the directory ⇒ cannot confirm it is clean. Refuse.
+        return { ok: false, category: "listing_failed" };
+    }
+    // Sorted so a successful `removed` list is deterministic and two job rows for
+    // the same condition render identically.
+    const matches = entries.filter(isWorkerEnvFileName).sort();
+    for (const name of matches) {
+        const target = pathApi.join(worktreePath, name);
+        try {
+            // Non-following metadata. The result is deliberately unused for a decision:
+            // a regular file and a symlink are both removed the same way, by `unlink`.
+            // The call is here so an entry that cannot be inspected refuses the spawn
+            // instead of being unlinked blind.
+            await deps.lstat(target);
+        }
+        catch {
+            return { ok: false, category: "metadata_failed" };
+        }
+        try {
+            await deps.unlink(target);
+        }
+        catch {
+            // Includes the directory case (`EISDIR`/`EPERM`): a `.env` that is a
+            // DIRECTORY is not removable by `unlink`, and this guard deliberately does
+            // not escalate to a recursive delete inside a worktree.
+            return { ok: false, category: "unlink_failed" };
+        }
+    }
+    // The confirmation half. Without this, "we called unlink" would be reported as
+    // "the worktree is clean", which is exactly the claim this gate must not make
+    // on faith.
+    let remaining;
+    try {
+        remaining = await deps.readdir(worktreePath);
+    }
+    catch {
+        return { ok: false, category: "verification_listing_failed" };
+    }
+    if (remaining.some(isWorkerEnvFileName)) {
+        return { ok: false, category: "entry_survived" };
+    }
+    return { ok: true, removed: matches };
+}

package/build/executor/env.js

@@ -33,13 +33,26 @@
  * executor must not reach a worker and silently change which configuration —
  * and which MCP registrations — the CLI resolves.
  *
+ * BAPI-1019: this builder also injects four SENTINEL DATABASE literals
+ * (`DATABASE_URL`, `POSTGRES_DATABASE`, `POSTGRES_DB`, `PGDATABASE`), all naming a
+ * database that does not exist. Architecture Miss 28 was a worker that ran an
+ * allowed `pytest` whose harness truncated the operator's real operational
+ * database; it could name that database because a copied `.env` reached its
+ * worktree and nothing in the worker environment said otherwise. The env-file
+ * strip in `env-file-guard.ts` removes the file, and these constants are the
+ * SECOND layer: code inside a worker that resolves a database from the
+ * environment resolves a name that connects to nothing. The two layers are
+ * independent on purpose — the harness calls `load_dotenv(override=False)`, so a
+ * value already in the environment WINS over a `.env` entry, which is what makes
+ * the sentinel effective even if a file ever survived the strip.
+ *
  * The `mcp-invoke` shim (a separate process) resolves `BAPI_API_KEY` itself at
  * call time from the operator's real user-scoped credential store, exactly as it
  * did before BAPI-731, so this worker environment never carries it. The model is
  * still denied direct reads of that store by the deny layer
  * (`Read(~/.config/bridge/**)` in `permissions.ts`).
  */
-import { PR_BASE_BRANCH_ENV_VAR } from "../pr-base-contract.js";
+import { PR_BASE_BRANCH_ENV_VAR, WORKER_BRANCH_ENV_VAR } from "../pr-base-contract.js";
 import { INDEX_SCOPE_ENV_VAR, validateOptionalIndexScope } from "../index-scope-contract.js";
 /** Non-secret operational keys forwarded to the worker when present. */
 const ALLOWED_ENV_KEYS = [
@@ -56,6 +69,36 @@ const ALLOWED_ENV_KEYS = [
     "TERM",
     "NO_COLOR",
 ];
+/**
+ * The database name every worker resolves, and it exists nowhere (BAPI-1019).
+ *
+ * A NAME rather than an empty value, deliberately: an unset `POSTGRES_DB` makes a
+ * client fall back to a default (often the connecting user's name, which on a
+ * developer host is a real database), while a name nothing has ever created fails
+ * at connect and says so. The failure text carries this string, which is what the
+ * harness drill asserts on — proving the name reached the driver rather than
+ * merely that a connection failed.
+ */
+export const WORKER_SENTINEL_DATABASE_NAME = "bridge_worker_no_database";
+/**
+ * The sentinel connection URL. Points at port 1 on loopback — a privileged port
+ * nothing binds — so the failure is immediate and local rather than a DNS lookup
+ * or a timeout against something real.
+ */
+export const WORKER_SENTINEL_DATABASE_URL = `postgresql://${WORKER_SENTINEL_DATABASE_NAME}@127.0.0.1:1/${WORKER_SENTINEL_DATABASE_NAME}`;
+/**
+ * Every environment key that names a database target, in the order they are set.
+ *
+ * `DATABASE_URL` is listed first because it WINS over the `POSTGRES_*` trio in
+ * `db/utils.py`; the other three are set anyway so a code path that reads only
+ * the discrete parts is covered too.
+ */
+export const WORKER_SENTINEL_DATABASE_ENV_KEYS = [
+    "DATABASE_URL",
+    "POSTGRES_DATABASE",
+    "POSTGRES_DB",
+    "PGDATABASE",
+];
 /** Substrings that mark a key as secret-bearing (case-insensitive). */
 const SECRET_NAME_FRAGMENTS = ["TOKEN", "SECRET", "PASSWORD", "API_KEY"];
 /**
@@ -101,6 +144,24 @@ export const EXPLICIT_DENY_KEYS = [
     // decision, and inheriting one would route an unscoped worker's plan and review
     // at another epic's shadow index while nothing in the job said so.
     INDEX_SCOPE_ENV_VAR,
+    // BAPI-1020: the worker's own branch follows the same rule, and for this key the
+    // rule is the guard's integrity rather than a research-scope mistake. The
+    // deterministic PreToolUse guard decides "is this push destination my own
+    // branch?" by comparing against this value, so an operator's ambient
+    // `BAPI_WORKER_BRANCH` reaching a worker would let the environment redefine what
+    // the guard treats as safe. Absent from ALLOWED_ENV_KEYS so it is never copied
+    // from `parentEnv`, and denied EXPLICITLY here so the answer is local and
+    // auditable rather than inferred from an omission.
+    WORKER_BRANCH_ENV_VAR,
+    // BAPI-1019: the four database keys follow the BAPI_INDEX_SCOPE precedent
+    // exactly — absent from ALLOWED_ENV_KEYS so they are never copied from
+    // `parentEnv`, and denied EXPLICITLY here so an operator's ambient value can
+    // never win over the sentinel constants the builder sets. Denying a key the
+    // builder also sets is not redundant: the deny list is what makes
+    // `isExecutorEnvKeyAllowed` answer "no" for these names locally and
+    // auditably, rather than relying on a reader noticing they are missing from
+    // the allowlist.
+    ...WORKER_SENTINEL_DATABASE_ENV_KEYS,
 ];
 /**
  * True only when `key` is a safe, allowlisted operational key. Exported so the
@@ -140,10 +201,26 @@ export function buildExecutorBaseWorkerEnv(parentEnv, options = {}) {
     }
     env.BRIDGE_SKIP_PREPUSH = "1";
     env.MAX_MCP_OUTPUT_TOKENS = "50000";
+    // BAPI-1019 — the sentinel database target, set for EVERY job type and every
+    // adapter, from constants and never from `parentEnv`. Set here rather than in
+    // an adapter because "a worker cannot name a real database" is a property of
+    // being a worker, not of being a Claude worker.
+    env.DATABASE_URL = WORKER_SENTINEL_DATABASE_URL;
+    env.POSTGRES_DATABASE = WORKER_SENTINEL_DATABASE_NAME;
+    env.POSTGRES_DB = WORKER_SENTINEL_DATABASE_NAME;
+    env.PGDATABASE = WORKER_SENTINEL_DATABASE_NAME;
     if (typeof options.effectiveBaseBranch === "string" &&
         options.effectiveBaseBranch.length > 0) {
         env[PR_BASE_BRANCH_ENV_VAR] = options.effectiveBaseBranch;
     }
+    // BAPI-1020 — the worker's own branch, set ONLY from the explicit job value and
+    // ONLY when it is a non-empty string. An empty or absent value adds no key at
+    // all, so an unscoped job's environment stays byte-identical to the
+    // pre-BAPI-1020 one rather than carrying an empty string the guard would have to
+    // special-case.
+    if (typeof options.workerBranch === "string" && options.workerBranch.length > 0) {
+        env[WORKER_BRANCH_ENV_VAR] = options.workerBranch;
+    }
     // BAPI-844: the index-scope declaration, set ONLY from the explicit option and
     // only after the shared shape check. A malformed explicit value throws here —
     // before an environment exists — rather than being dropped: silently omitting it

package/build/executor/heartbeat.js

@@ -79,6 +79,15 @@ export async function runHeartbeatLoop(params) {
             killOwnedProcess(proc, "server_stop");
             return { kind: "server_stop" };
         }
+        if (result.outcome === "auth_fatal") {
+            // BAPI-1021 (AC-5): bypass the dead-man wait entirely — an auth failure
+            // will never resolve itself by waiting out `deadmanMs`. Deliberately does
+            // NOT reset `lastSuccessfulHeartbeatAt`, set `ownership.abandoned`/
+            // `abandonReason` (this is not a lost/stale claim), or invoke worktree
+            // reset/recreation/cleanup: the current job drains normally while the
+            // runner's process-level handler stops future claiming.
+            return { kind: "auth_fatal", httpStatus: result.authHttpStatus ?? 401 };
+        }
         if (result.outcome === "updated") {
             ownership.lastSuccessfulHeartbeatAt = deps.now();
             return null;