@bridge_gpt/mcp-server 0.2.50 → 0.2.52

package/build/executor/permissions.js

@@ -52,6 +52,40 @@ import { mergeClaudeSettingsWithCommandHook, provisionClaudeSettingsForWorktree,
  * carries the whole Bridge-credential guarantee again, exactly as it did before
  * BAPI-731: the shim resolves the operator's real store in its own process, and
  * the model cannot read it.
+ *
+ * BAPI-1020 appends fifteen DESTRUCTIVE / DEPLOYING rules after the original nine.
+ * Architecture Miss 28 happened with the original set in place, because it covered
+ * credentials, force-push, and `rm -rf` at the filesystem root — and nothing else.
+ * Every external or operational system a worker could reach (`gh`, `heroku`,
+ * `gcloud`, `aws`, `kubectl`, `terraform`, `docker push`, `npm publish`, a tag
+ * push, a push to `main`) was allowed.
+ *
+ * EVERY new rule is COMMAND-scoped, and that is the Architecture Miss 23
+ * constraint restated above, not a stylistic preference: a deny glob must target
+ * the ASSET, never a directory that also holds the worker's own working state. A
+ * `Bash(<cmd>:...)` rule cannot shadow a path the CLI persists tool results into.
+ * Do not widen any of them into a directory or worktree-state path glob.
+ *
+ * Two rules a reader might expect are deliberately ABSENT because they are already
+ * covered: `Bash(git push:*--force*)` above satisfies the force-push clause, and
+ * the two `rm:*-rf` rules cover the root and home cases. The hook's
+ * worktree-relative `rm -rf` check COMPLEMENTS those two rather than replacing
+ * them — a glob cannot decide whether a relative path resolves inside the
+ * worktree, and no glob can decide whether a push destination is the job's own
+ * branch. That argument-sensitive half lives in `worker-guard-hook.ts`.
+ *
+ * `Bash(gh:*)` denies `gh` TO WORKERS ONLY, and the distinction is load-bearing —
+ * do not "fix" this denial when a conductor merge appears to need `gh`. Conductor
+ * merges run in the EXECUTOR PROCESS: `merge-job.ts` spawns no worker, and
+ * `conductor/local-merge.ts` runs `gh pr view` / `gh pr merge` in the executor's
+ * own process, which reads no worktree `settings.local.json`. The merge path is
+ * therefore unaffected by this rule. The mandatory worker paths already avoid `gh`
+ * too (push via git's credential helper; PRs via the `create_pull_request` MCP
+ * tool — see the note in `env.ts`). `pr-base-contract.ts`'s
+ * `buildPrBaseContractLaunchInstruction()` does instruct `gh pr create`, but its
+ * only production caller is the INTERACTIVE `start-tickets` path, which is
+ * provisioned through `start-tickets-conductor.ts` and never receives these rules.
+ * If that ever changes, the instruction — not this rule — is what moves.
  */
 export function executorDenyRules(inputs) {
     return [
@@ -64,8 +98,46 @@ export function executorDenyRules(inputs) {
         "Bash(git push:*--force*)",
         "Bash(rm:*-rf /*)",
         "Bash(rm:*-rf ~*)",
+        // BAPI-1020 — destructive / deploying commands, in the ticket's stated order.
+        "Bash(gh:*)",
+        "Bash(git push:*--tags*)",
+        "Bash(heroku:*)",
+        "Bash(git push:*refs/tags/*)",
+        "Bash(gcloud:*)",
+        "Bash(git push:*--delete*)",
+        "Bash(aws:*)",
+        "Bash(git push:* :*)",
+        "Bash(kubectl:*)",
+        "Bash(git push:* main*)",
+        "Bash(terraform:*)",
+        "Bash(git push:* epic/*)",
+        "Bash(docker:push*)",
+        "Bash(git push:*mcp-server/v*)",
+        "Bash(npm:publish*)",
     ];
 }
+/**
+ * Branch names that a BRANCH-SHAPED deny glob would match (BAPI-1020).
+ *
+ * Two of the fifteen new rules — `Bash(git push:* main*)` and
+ * `Bash(git push:* epic/*)` — deny by branch shape rather than by command. If a
+ * worker's OWN branch ever matched one, the static deny would block the push the
+ * guard is required to allow, and AC-10 ("it still pushes its own branch") would
+ * break at push time with an error naming a rule nobody connected to the branch
+ * name. The hook cannot rescue it: a PreToolUse allow does not override a
+ * settings-level deny.
+ *
+ * Today the collision is unreachable — worker branches come from `wt.branch`, the
+ * Worktrunk `feature/<KEY>` branch, and `epic/<EPIC>` appears only as a merge base
+ * — but nothing wrote that invariant down. This does, and it fails LOUDLY at
+ * provisioning time rather than mysteriously at push time.
+ */
+export function workerBranchCollidesWithDenyGlob(branch) {
+    const trimmed = branch.trim();
+    if (trimmed.length === 0)
+        return false;
+    return trimmed === "main" || trimmed.startsWith("main") || trimmed.startsWith("epic/");
+}
 function asObject(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value)
         ? value
@@ -75,6 +147,12 @@ function asObject(value) {
  * Merge the executor deny set into a settings object under `permissions.deny`,
  * preserving all existing settings and appending only rules not already present
  * (idempotent).
+ *
+ * Append-if-absent is what keeps the merge safe for a worktree provisioned by an
+ * EARLIER executor build: the nine pre-BAPI-1020 rules already sitting in the file
+ * are matched and skipped, the fifteen new ones are appended, and any unrelated
+ * operator-authored deny entry is preserved in place rather than reordered or
+ * replaced.
  */
 export function mergeExecutorDenySettings(existing, inputs) {
     const permissions = { ...asObject(existing.permissions) };
@@ -272,6 +350,12 @@ async function provisionWorktreeSettingsExclude(worktreePath, deps) {
  * and shield that file from worker commits via `.git/info/exclude` (BAPI-740/F2).
  * Fails open: a malformed existing file is preserved (not clobbered) and I/O
  * errors return a warning — the caller still spawns the worker.
+ *
+ * BAPI-1020: this call now provisions TWO things into the same file — the deny
+ * rules and the always-on deterministic worker-guard PreToolUse hook. They are one
+ * write because they are one worktree-provisioning boundary, not because they are
+ * one mechanism: the rules deny command FAMILIES, the guard denies destructive
+ * ARGUMENTS, and neither can express the other's half.
  */
 export async function provisionExecutorDenyLayer(worktreePath, options, deps) {
     const inputs = {
@@ -281,6 +365,12 @@ export async function provisionExecutorDenyLayer(worktreePath, options, deps) {
     };
     const result = await provisionClaudeSettingsForWorktree(worktreePath, (existing) => {
         let merged = mergeExecutorDenySettings(existing, inputs);
+        // BAPI-1020 — the worker guard is registered UNCONDITIONALLY, before and
+        // independently of the conditional fallback below. PreToolUse hooks fire in
+        // EVERY permission mode, bypass included, which is what makes the guard hold
+        // even under the `skip_permissions` revert value. The merge is idempotent
+        // per command, so a re-provisioned worktree does not accumulate duplicates.
+        merged = mergeClaudeSettingsWithCommandHook(merged, options.workerGuardHookCommand, [], { enablePreToolUse: true, preToolUseMatcher: DEFAULT_PRE_TOOL_USE_MATCHER });
         if (options.preToolUseFallbackCommand) {
             merged = mergeClaudeSettingsWithCommandHook(merged, options.preToolUseFallbackCommand, [], { enablePreToolUse: true, preToolUseMatcher: DEFAULT_PRE_TOOL_USE_MATCHER });
         }
@@ -290,6 +380,14 @@ export async function provisionExecutorDenyLayer(worktreePath, options, deps) {
     // may already exist from an earlier provisioning, so it runs even when the
     // merge-write was refused or failed.
     const exclude = await provisionWorktreeSettingsExclude(worktreePath, deps);
+    // BAPI-1020 — the branch-shaped-glob collision check. Advisory rather than
+    // blocking, matching this function's established fail-open posture: the worker
+    // can still do most of its job, and killing the spawn would trade a push failure
+    // for a total one. It is loud where it matters — the warning names the condition
+    // at PROVISIONING time, so an operator reads it before the push fails, instead of
+    // decoding a deny rule from a push error twenty minutes later.
+    const collidingBranch = typeof options.workerBranch === "string" &&
+        workerBranchCollidesWithDenyGlob(options.workerBranch);
     // `blocking` and `advisory` are kept apart on purpose. A blocking warning
     // flips `ok` (the established contract, which existing callers and tests
     // read); an advisory one rides along on `ok: true` so a degraded-but-
@@ -303,6 +401,14 @@ export async function provisionExecutorDenyLayer(worktreePath, options, deps) {
         blocking.push(exclude.warning);
     else if (exclude.warning)
         advisory.push(exclude.warning);
+    if (collidingBranch) {
+        // The branch NAME is not echoed: this text travels into worker logs, and the
+        // condition ("matches a branch-shaped deny glob") is the whole diagnostic.
+        advisory.push("the job branch matches a branch-shaped executor deny glob (git push to main/ or " +
+            "epic/); the worker's own push would be denied by settings permissions.deny, " +
+            "which the PreToolUse guard cannot override — re-cut the branch before relying " +
+            "on this worktree");
+    }
     if (blocking.length > 0) {
         return { ok: false, warning: [...blocking, ...advisory].join("; ") };
     }

package/build/executor/preflight.js

@@ -46,9 +46,25 @@ export function resolveDenyProbeTimeoutMs(env = {}) {
     }
     return parsed;
 }
-/** True only for a result safe to reuse: genuinely enforced by a real layer. */
+/**
+ * True only for a result safe to reuse: genuinely enforced by a real layer, for
+ * EVERY posture that was probed.
+ *
+ * BAPI-1020 added the per-posture clause. The combined result already refuses to
+ * report `enforced: true` unless every required posture passed, but caching is the
+ * one place where being wrong is STICKY — a cached result is reused for the rest
+ * of the executor's life — so the check is made against the per-posture record
+ * directly rather than trusted to the conjunction upstream. A spawn failure, a
+ * hang, a control refusal, and a degraded guess all report `layer: "none"` for the
+ * posture they happened under, and none of them is cached.
+ */
 function isCacheableDenyResult(result) {
-    return result.enforced === true && result.layer !== "none";
+    if (result.enforced !== true || result.layer === "none")
+        return false;
+    const postures = result.postures;
+    if (postures === undefined)
+        return true;
+    return postures.every((p) => p.enforced === true && p.layer !== "none");
 }
 /** Create a fresh, empty executor-scoped deny-probe cache. */
 export function createDenyProbeCache() {
@@ -343,18 +359,26 @@ export async function collectExecutorPreflight(options, deps, seams = {}) {
     };
 }
 /**
- * Build the HTTP claim manifest — the eight original T2-accepted keys, plus the
- * optional ninth `epic_run_ids` key (BAPI-794) when the executor was configured
- * with one or more `--epic-run-id` flags. `free_slots` is supplied by the runner
- * (dynamic). The internal-only `gh` auth capability is intentionally NOT included
- * (not accepted by the T2 request schema in this slice).
+ * Build the HTTP claim manifest — the eight original T2-accepted keys, plus at
+ * most ONE optional scope-intent key: `epic_run_ids` (BAPI-794) when the
+ * executor was configured with `--epic-run-id`, or `repo_wide: true`
+ * (BAPI-1026) when it was configured with `--repo-wide`. `free_slots` is
+ * supplied by the runner (dynamic). The internal-only `gh` auth capability is
+ * intentionally NOT included (not accepted by the T2 request schema).
+ *
+ * The two scope keys are mutually exclusive by construction: `parseExecutorArgs`
+ * refuses to start an executor that supplied both, and the server rejects the
+ * combination with a 422 anyway. Exactly one is always present, because since
+ * BAPI-1026 the CLI also refuses to start with neither.
  *
- * `epic_run_ids` is added via a conditional spread, not a bare property
- * assignment: `{ epic_run_ids: options.epicRunIds }` would still create the key
- * (with value `undefined`) when unscoped, which `Object.keys()` — unlike
- * `JSON.stringify` — does NOT drop. The eight-key compatibility contract is
- * pinned on `Object.keys()`, so the key must be truly absent, not merely
- * `undefined`-valued.
+ * Both are added via a conditional spread, not a bare property assignment:
+ * `{ epic_run_ids: options.epicRunIds }` would still create the key (with value
+ * `undefined`) when unscoped, which `Object.keys()` — unlike `JSON.stringify` —
+ * does NOT drop. The eight-key compatibility contract is pinned on
+ * `Object.keys()`, so an unused key must be truly absent, not merely
+ * `undefined`-valued. For the same reason `repo_wide` is never serialized as
+ * `false`: `false` is the server's default and means "not an opt-out", so
+ * sending it would add a key that carries no information.
  */
 export function buildClaimManifest(report, options, freeSlots) {
     return {
@@ -367,5 +391,6 @@ export function buildClaimManifest(report, options, freeSlots) {
         free_slots: freeSlots,
         disk_free_gb: report.diskFreeGb ?? 0,
         ...(options.epicRunIds !== undefined ? { epic_run_ids: options.epicRunIds } : {}),
+        ...(options.repoWide === true ? { repo_wide: true } : {}),
     };
 }

package/build/executor/resume-pre-spawn.js

@@ -51,7 +51,8 @@ export function resolveResumeExpectedBranch(job, fields) {
  * Resolve the server-provided prompt template, failing loud with a contract
  * error when it is missing/empty. Validated BEFORE any worktree resolution or
  * WIP-checkpoint work so a malformed `resume` payload never spawns a real
- * `claude -p "" --dangerously-skip-permissions` worker that would burn the full
+ * `claude -p ""` worker — under whatever posture the run policy resolved, which
+ * since BAPI-1020 defaults to `--permission-mode auto` — that would burn the full
  * job timeout before failing generically (mirrors the `implement`/`spec_review`
  * `ContractError.Prompt` fail-fast in `resolveExecutorPrompt`).
  */

package/build/executor/runner.js

@@ -9,8 +9,10 @@
 import { collectExecutorPreflight, buildClaimManifest, createDenyProbeCache, } from "./preflight.js";
 import { runClaimedJob } from "./job-runner.js";
 import { appendToActiveJobLogs } from "./job-log-registry.js";
-import { createLiveWorkerRegistry } from "./live-worker-registry.js";
+import { createLiveWorkerRegistry, } from "./live-worker-registry.js";
 import { sweepExecutorWorktrees } from "./worktree-gc.js";
+import { validateBranchName } from "../base-ref.js";
+import { ensureEpicIntegrationPullRequest, createProductionEpicIntegrationGhRunner, formatEpicIntegrationPullRequestOutcome, EPIC_BRANCH_PREFIX, } from "../epic-integration-pr.js";
 /**
  * Signals that request a graceful executor shutdown (BAPI-828).
  *
@@ -133,6 +135,14 @@ export async function runExecutor(options, deps, httpClient, seams = {}) {
     // Read-only diagnostics, exactly like `lastClaimedEpicRunId` above: it never
     // feeds claim eligibility, cadence, retries, dispatch, or exit.
     let lastDispatcherAvailability = null;
+    // BAPI-1010 — one-shot executor wind-down observer state. Declared here,
+    // OUTSIDE both the claim loop and the poll loop, so a readiness attempt
+    // fires at most once for the life of this `runExecutor` invocation rather
+    // than once per poll cycle.
+    let markReadyAttempted = false;
+    // Suppresses the missing-read-capability advisory to one line per
+    // invocation, mirroring the dispatcher-liveness suppression above.
+    let missingReadCapabilityWarned = false;
     /**
      * Announce a dispatcher availability CHANGE, and only a change.
      *
@@ -164,6 +174,109 @@ export async function runExecutor(options, deps, httpClient, seams = {}) {
             deps.errorLog(formatDispatcherRecoveredDiagnostic());
         }
     };
+    /**
+     * Resolve the single epic run this executor process is unambiguously scoped
+     * to observe for wind-down, or `null` when the scope is absent or ambiguous.
+     *
+     * BAPI-1010: Slice 1 (`ExecutorOptions.epicRunIds`, BAPI-794) does not
+     * guarantee a dedicated executor receives exactly one run id — an operator
+     * may repeat `--epic-run-id` for several runs. Observing an arbitrary entry
+     * from a multi-run scope would silently pick the wrong epic, so the
+     * mutation stays disabled for both an unscoped executor (`epicRunIds`
+     * absent) and an ambiguous one (more than one id).
+     *
+     * BAPI-1026 (R54) DELIBERATELY LEAVES THIS CONDITION UNCHANGED, and that is
+     * the whole decision, not an omission.
+     *
+     * Making run scoping the default raised a real hazard: if the server could
+     * hand an executor a single-run scope it had not asked for, this gate would
+     * start authorizing a GitHub write — the one-shot epic→base integration-PR
+     * mutation — for processes that never had it, invisibly, as a side effect of
+     * a claim-scoping change. The decision is to keep the wind-down gated on
+     * EXPLICIT OPERATOR SCOPE only.
+     *
+     * No provenance flag is needed to express that, because R54 removed the only
+     * way a non-operator scope could arise: there is no server-derived scope. The
+     * server owns no executor-to-run binding to derive one from, so the accepted
+     * design makes the scope client-supplied and the CLI refuse to start without
+     * an explicit `--epic-run-id` or `--repo-wide`. Every `epicRunIds` value that
+     * can reach this line therefore came from an operator's `--epic-run-id`
+     * flags, exactly as it did before R54, and `--repo-wide` leaves `epicRunIds`
+     * absent so it cannot enable the mutation either.
+     *
+     * If a future slice ever introduces a server-derived scope, this gate must
+     * grow an explicit provenance field at the same time — cardinality would stop
+     * being evidence of operator intent the moment that happens.
+     */
+    const observedEpicRunId = options.epicRunIds !== undefined && options.epicRunIds.length === 1
+        ? options.epicRunIds[0]
+        : null;
+    /**
+     * One-shot epic-run completion observer (BAPI-1010).
+     *
+     * Called after every successful claim response (`claimed` or `none`), next
+     * to `observeDispatcherLiveness`. The FIRST time the scoped run's state
+     * reads back `status: "done"` on a valid `epic/`-prefixed feature branch,
+     * this requests the epic's existing draft integration pull request be
+     * marked ready for review — it never creates a merge and never merges
+     * anything; only a human merges an epic integration branch (see
+     * `epic-integration-pr.ts`). Every failure here — a missing read
+     * capability, a sanitized transport/validation failure, an invalid branch,
+     * or an unexpected throw — is ADVISORY: it is logged (credential-free,
+     * bounded) and never affects claiming, running jobs, or the runner's exit.
+     */
+    const observeEpicRunCompletion = async () => {
+        if (markReadyAttempted || observedEpicRunId === null)
+            return;
+        const readState = httpClient.readEpicRunState;
+        if (typeof readState !== "function") {
+            if (!missingReadCapabilityWarned) {
+                missingReadCapabilityWarned = true;
+                deps.errorLog("executor: HTTP client lacks readEpicRunState; skipping epic wind-down observation.");
+            }
+            return;
+        }
+        try {
+            const result = await readState.call(httpClient, observedEpicRunId, options.repoName);
+            if (!result.ok) {
+                deps.errorLog(`executor: epic run completion-state read failed (reason=${result.reason})`);
+                return;
+            }
+            if (result.state.status !== "done")
+                return;
+            const featureBranch = result.state.featureBranch;
+            if (typeof featureBranch !== "string" || !featureBranch.startsWith(EPIC_BRANCH_PREFIX)) {
+                return;
+            }
+            const epicKey = featureBranch.slice(EPIC_BRANCH_PREFIX.length);
+            if (epicKey.length === 0)
+                return;
+            if (validateBranchName(featureBranch) !== null)
+                return;
+            if (validateBranchName(options.baseBranch) !== null)
+                return;
+            // Marked BEFORE constructing/awaiting the PR operation — a slow or
+            // failing `gh` call must never let a later poll cycle start a second
+            // attempt while this one is still in flight.
+            markReadyAttempted = true;
+            const gh = seams.epicIntegrationGh ?? createProductionEpicIntegrationGhRunner();
+            const outcome = await ensureEpicIntegrationPullRequest({
+                epicKey,
+                epicBranch: featureBranch,
+                baseBranch: options.baseBranch,
+                command: "executor wind-down",
+                requestReady: true,
+                gh,
+                cwd: deps.cwd,
+            });
+            deps.errorLog(`executor: epic wind-down integration PR: ${JSON.stringify(formatEpicIntegrationPullRequestOutcome(outcome))}`);
+        }
+        catch {
+            // Advisory-only: never allowed to affect claiming, running jobs, or the
+            // runner's exit code.
+            deps.errorLog("executor: epic wind-down observation failed unexpectedly (advisory only).");
+        }
+    };
     // BAPI-722: ONE deny-probe cache per `runExecutor` invocation, created OUTSIDE
     // the claim loop below — that scope is the whole feature. A cache created inside
     // the loop would be discarded every cycle and re-probe exactly as before; a
@@ -182,7 +295,6 @@ export async function runExecutor(options, deps, httpClient, seams = {}) {
     // not module-global. Every dispatched job receives it, so a worker spawned by
     // any of them is reachable from the signal handlers installed below.
     const liveWorkers = createLiveWorkerRegistry();
-    const control = { liveWorkers };
     let shutdownRequested = false;
     /**
      * Wake functions for whichever poll sleep is currently in flight. A list whose
@@ -210,6 +322,35 @@ export async function runExecutor(options, deps, httpClient, seams = {}) {
         for (const wake of shutdownWaiters.splice(0, shutdownWaiters.length))
             wake();
     };
+    /**
+     * Process-level auth-fatal handler (BAPI-1021, AC-5). A dispatched job
+     * (claim, heartbeat, complete, or fail) calls this via
+     * `control.reportAuthFatal` on its FIRST 401/403 — a credential that will
+     * never become valid again by waiting.
+     *
+     * Deliberately just `beginShutdown()` underneath: an auth halt is the same
+     * kind of stop as a `SIGTERM`/`SIGINT` — terminate live workers gracefully
+     * and stop claiming new work — reusing its idempotent flag and drain
+     * behavior rather than inventing a parallel shutdown path. That reuse is
+     * also what keeps this handler from ever running a worktree
+     * reset/recreation or a conservative GC sweep: neither the existing
+     * shutdown path nor this one performs either.
+     *
+     * The ONE bounded, secret-safe log line is guarded SEPARATELY from
+     * `beginShutdown`'s own idempotency: two jobs racing an auth failure nearly
+     * concurrently must produce exactly one `executor_auth_failure` line, even
+     * though `beginShutdown()` itself is safe to call from both.
+     */
+    let authFailureLogged = false;
+    const reportAuthFatal = (notice) => {
+        if (!authFailureLogged) {
+            authFailureLogged = true;
+            deps.errorLog(`executor_auth_failure: category=${notice.category} status=${notice.httpStatus} ` +
+                `job_id=${notice.jobId ?? "n/a"} repo=${notice.repoName}`);
+        }
+        beginShutdown();
+    };
+    const control = { liveWorkers, reportAuthFatal };
     /**
      * Sleep one poll interval, or return early once shutdown is requested.
      *
@@ -453,15 +594,26 @@ export async function runExecutor(options, deps, httpClient, seams = {}) {
                     // not evidence about the dispatcher, so it is deliberately not observed.
                     if (result.kind === "claimed" || result.kind === "none") {
                         observeDispatcherLiveness(result.reconcilerLiveness);
+                        await observeEpicRunCompletion();
                     }
                     if (result.kind === "claimed") {
                         const currentEpicRunId = result.job.epic_run_id ?? null;
                         if (lastClaimedEpicRunId !== null &&
                             currentEpicRunId !== null &&
                             currentEpicRunId !== lastClaimedEpicRunId) {
+                            // BAPI-1026 (R54) — RETARGETED, not removed. `scoped=` used to
+                            // report `epicRunIds !== undefined`, which this ticket could have
+                            // made universally true and so turned the warning it guards into
+                            // dead code. It reports the claim-scope MODE instead, which stays
+                            // genuinely two-valued: a `--repo-wide` executor legitimately
+                            // claims across runs (the warning is expected there), while a
+                            // scoped executor seeing a cross-run claim is a real anomaly worth
+                            // the line. Bounded context only — a mode label and the run IDs
+                            // already present in this pre-existing message.
                             deps.errorLog(`executor claimed a job for a different epic run than the previous claim ` +
                                 `(repo=${result.job.repo_name} previous_epic_run_id=${lastClaimedEpicRunId} ` +
-                                `current_epic_run_id=${currentEpicRunId} scoped=${options.epicRunIds !== undefined})`);
+                                `current_epic_run_id=${currentEpicRunId} ` +
+                                `claim_scope_mode=${options.epicRunIds !== undefined ? "scoped" : "repo_wide"})`);
                         }
                         if (currentEpicRunId !== null)
                             lastClaimedEpicRunId = currentEpicRunId;
@@ -478,6 +630,18 @@ export async function runExecutor(options, deps, httpClient, seams = {}) {
                     else {
                         deps.errorLog(`executor claim ${result.kind}: ${result.error}`);
                         claiming = false;
+                        // BAPI-1021 (AC-5): a categorized 401/403 fatal claim halts the
+                        // RUNNER through the same handler a heartbeat/complete/fail auth
+                        // failure reaches — not merely this claim iteration. No job was
+                        // ever claimed, so the notice names the manifest's repository and
+                        // omits `jobId`.
+                        if (result.kind === "fatal" && result.authCategory === "auth_fatal") {
+                            control.reportAuthFatal?.({
+                                repoName: manifest.repo_name,
+                                category: "claim",
+                                httpStatus: result.authHttpStatus ?? 401,
+                            });
+                        }
                     }
                 }
                 // Conservative worktree GC runs once per cycle, AFTER the claim attempt and
@@ -485,7 +649,14 @@ export async function runExecutor(options, deps, httpClient, seams = {}) {
                 // both the startup cycle and between-poll-cycle cadence without ever
                 // sweeping while a job is running. Kept off the pre-claim path so it never
                 // delays claiming a ready job.
-                await maybeSweepWorktrees();
+                //
+                // BAPI-1021 (AC-5): also skipped once shutdown was requested DURING this
+                // cycle's claim loop (a claim-time auth-fatal is the case that matters —
+                // it can flip `shutdownRequested` while `active.size` is still 0). No
+                // worktree-mutating sweep may run once the auth-fatal flag is set.
+                if (!shutdownRequested) {
+                    await maybeSweepWorktrees();
+                }
             }
             if (options.once || shutdownRequested)
                 break;

package/build/executor/service-unit.js

@@ -255,6 +255,17 @@ export function buildExecutorServiceArguments(input) {
     for (const repo of input.repos)
         args.push("--repo", repo);
     args.push("--executor-id", input.executorId);
+    // BAPI-1026 (R54): forward the claim scope. Repeated `--epic-run-id <id>`
+    // pairs mirror how the operator supplied them, or the single `--repo-wide`
+    // opt-out. Appended last so the pre-existing prefix/repo/executor-id ordering
+    // — which several artifact tests pin positionally — is unchanged.
+    if (input.epicRunIds !== undefined) {
+        for (const runId of input.epicRunIds)
+            args.push("--epic-run-id", runId);
+    }
+    else if (input.repoWide === true) {
+        args.push("--repo-wide");
+    }
     return args;
 }
 // ---------------------------------------------------------------------------
@@ -845,6 +856,10 @@ export async function runExecutorInstallServiceCli(argv, overrides) {
         baseUrl,
         homeDir: deps.homeDir,
         envPath,
+        // Forwarded from the already-validated parse, so the generated unit starts
+        // with the same claim scope the operator typed (BAPI-1026).
+        ...(options.epicRunIds !== undefined ? { epicRunIds: options.epicRunIds } : {}),
+        ...(options.repoWide === true ? { repoWide: true } : {}),
     };
     // Windows has no generated user-service format here: print the fully resolved,
     // secret-free command line plus manual Task Scheduler guidance and stop. No

package/build/executor/terminal-mutation.js

@@ -1,3 +1,17 @@
+/**
+ * Terminal mutation (complete/fail) retry semantics (BAPI-534, TDD §10).
+ *
+ *  - `updated`            → terminal success.
+ *  - `stale_claim`        → definitive loss of ownership; stop touching worktree.
+ *  - `retry_later` / net  → retryable at the heartbeat interval WHILE the dead-man
+ *                           window has not elapsed; then abandon.
+ *  - `invalid_job_result` → (complete only) terminal non-success; the server has
+ *                           already failed the job, so DO NOT then call `/fail`.
+ *
+ * Retry diagnostics are bounded and never include raw result envelopes, secrets,
+ * or unbounded stdout/stderr.
+ */
+import { normalizeMutationResult } from "./types.js";
 /**
  * Send a terminal mutation with the fencing-aware retry policy. Skips entirely
  * when ownership was already abandoned.
@@ -7,9 +21,16 @@ export async function sendTerminalMutationWithRetry(params) {
     if (ownership.abandoned)
         return { outcome: "skipped" };
     while (true) {
-        const outcome = await params.send();
+        const mapped = normalizeMutationResult(await params.send());
+        const outcome = mapped.outcome;
         if (outcome === "updated")
             return { outcome: "success" };
+        if (outcome === "auth_fatal") {
+            // Return immediately after exactly one send attempt — no dead-man sleep
+            // or retry. Deliberately does NOT set `ownership.abandoned` (this is not
+            // a lost/stale claim) and never invokes `send()` a second time.
+            return { outcome: "auth_fatal", httpStatus: mapped.authHttpStatus ?? 401 };
+        }
         if (outcome === "stale_claim") {
             ownership.abandoned = true;
             ownership.abandonReason = "stale_claim";

package/build/executor/types.js

@@ -1,3 +1,89 @@
+/**
+ * Server-authoritative executor job types (T2 `ExecutorJobType` literal,
+ * mirrors `EXECUTOR_JOB_TYPE_VALUES` in `api/models/executor_job.py`).
+ *
+ * BAPI-997 (T4): the runtime array is the single source, and `ExecutorJobType`
+ * is DERIVED from it via `(typeof VALUES)[number]` rather than declared
+ * independently — adding or removing a value here changes the emitted
+ * JavaScript array (visible to a Node contract driver) and the compile-time
+ * union in one edit, so the two can never drift apart.
+ */
+export const EXECUTOR_JOB_TYPE_VALUES = [
+    "implement",
+    "resume",
+    "spec_review",
+    "remediate",
+    "rebase",
+    "ci_fix",
+    "merge",
+    "smoke",
+];
+/**
+ * Server-authoritative completion classification (T2 `ExecutorClassification`,
+ * mirrors `EXECUTOR_CLASSIFICATION_VALUES` in `api/models/executor_job.py`).
+ * The local process owner produces the first four; `no_progress`/`lease_expired`
+ * are reserved for server/other paths.
+ *
+ * BAPI-997 (T4): derived from the runtime array, same rationale as
+ * {@link EXECUTOR_JOB_TYPE_VALUES} above.
+ */
+export const EXECUTOR_CLASSIFICATION_VALUES = [
+    "clean_exit",
+    "timeout",
+    "killed",
+    "crashed",
+    "no_progress",
+    "lease_expired",
+];
+/**
+ * Outcome of a heartbeat/complete/fail mutation (T2 status mapping):
+ *  - `updated`            2xx `{ ok: true }`
+ *  - `stale_claim`        409 STALE_CLAIM — definitive dead claim (dead-man's switch)
+ *  - `retry_later`        503 RETRY_LATER — transient; keep worker alive, retry
+ *  - `invalid_job_result` 422 INVALID_JOB_RESULT on /complete — job failed server-side
+ *  - `auth_fatal`         401/403 — BAPI-1021 (AC-5): a Bridge auth/access failure.
+ *    Distinct from `fatal_http_error` because it must bypass the dead-man retry
+ *    loop and halt the executor immediately rather than waiting out the deadman
+ *    window on a credential that will never become valid again.
+ *  - `fatal_http_error`   parse/other non-retryable, NON-AUTH failure. Reserved
+ *    for exactly that now that `auth_fatal` exists — 401/403 map to `auth_fatal`
+ *    before this fallback is ever reached.
+ *
+ * BAPI-997 (T4): derived from the runtime array, same rationale as
+ * {@link EXECUTOR_JOB_TYPE_VALUES} above.
+ */
+export const EXECUTOR_MUTATION_OUTCOME_VALUES = [
+    "updated",
+    "stale_claim",
+    "retry_later",
+    "invalid_job_result",
+    "fatal_http_error",
+    "auth_fatal",
+];
+/** Normalize either mutation response form into the structured shape. */
+export function normalizeMutationResult(response) {
+    return typeof response === "string" ? { outcome: response } : response;
+}
+/**
+ * Server-minted reconciler/dispatcher liveness, carried on a claim response
+ * header (BAPI-871).
+ *
+ * SERVER-AUTHORED, and that is the whole contract. The backend derives this from
+ * the durable `process_heartbeats` row; the executor only reads it. Nothing here
+ * may be inferred from HTTP 204, an empty queue, elapsed polling time, a response
+ * body, or a local scheduler setting — those are exactly the proxies that made
+ * "nothing to do" ambiguous in the first place.
+ *
+ * `unknown` means the verdict is UNEVALUABLE — the header was absent (an older
+ * backend), unrecognized, or the server could not read its own durable source.
+ * It is not a claim that the dispatcher is absent.
+ *
+ * BAPI-997 (T4): derived from the runtime array, same rationale as
+ * {@link EXECUTOR_JOB_TYPE_VALUES} above. `http-client.ts`'s
+ * `parseReconcilerLivenessHeader` admits values from this projection rather
+ * than maintaining an independent literal set.
+ */
+export const RECONCILER_LIVENESS_VALUES = ["fresh", "stale", "never_seen", "unknown"];
 /** Normalize either heartbeat response form into the structured shape. */
 export function normalizeHeartbeatResult(response) {
     return typeof response === "string" ? { outcome: response } : response;