@bridge_gpt/mcp-server 0.2.51 → 0.2.52

package/build/executor/merge-job.js

@@ -23,11 +23,9 @@
  */
 import { makeLocalMergeExecutor, resolveLocalMergeMethod, } from "../conductor/local-merge.js";
 import { resolveConductorBridgeApiAccess, } from "../conductor/bridge-api-client.js";
-import { createProductionEpicIntegrationGhRunner, ensureEpicIntegrationPullRequest, formatEpicIntegrationPullRequestOutcome, } from "../epic-integration-pr.js";
+import { createProductionEpicIntegrationGhRunner, ensureEpicIntegrationPullRequest, formatEpicIntegrationPullRequestOutcome, EPIC_BRANCH_PREFIX, } from "../epic-integration-pr.js";
 import { secretFreeErrorMessage } from "./job-errors.js";
 import { resolveExecutorJobBaseBranch } from "./base-branch.js";
-/** `epic/<KEY>` prefix a child PR's base branch carries under BAPI-949/BAPI-950. */
-const EPIC_BRANCH_PREFIX = "epic/";
 function positiveIntOrNull(value) {
     return typeof value === "number" && Number.isInteger(value) && value > 0 ? value : null;
 }
@@ -42,8 +40,21 @@ function asString(value) {
  * Extract and validate merge fields. Prefers the claimed-job `expected_head_sha`
  * over any payload copy, validates `pr_number` as a positive integer, and fails
  * (before any subprocess) when the PR number or expected head SHA is absent.
+ *
+ * BAPI-1021 (AC-11): also resolves the two branch-ref expectations the local
+ * merge executor's ref-verification guard needs, and fails closed — before any
+ * `makeLocalMergeExecutor` construction or `runCommand` seam is reached — when
+ * either cannot be resolved:
+ *
+ *  - `expectedBaseBranch` via {@link resolveExecutorJobBaseBranch}, the SAME
+ *    resolver every other PR-producing job type uses, with `repositoryBaseBranch`
+ *    as its documented legacy fallback for a payload omitting `base_branch`.
+ *  - `expectedHeadBranch` EXCLUSIVELY from a trimmed, nonblank
+ *    `job.expected_branch` — never from payload data, which is untrusted and
+ *    job-type-generic. There is no fallback: a merge job with no known expected
+ *    head branch cannot be ref-verified.
  */
-export function readMergeJobPayloadFields(job) {
+export function readMergeJobPayloadFields(job, repositoryBaseBranch) {
     const payload = job.payload && typeof job.payload === "object" ? job.payload : {};
     const prNumber = positiveIntOrNull(payload.pr_number);
     if (prNumber === null) {
@@ -53,6 +64,15 @@ export function readMergeJobPayloadFields(job) {
     if (!expectedHeadSha) {
         return { ok: false, error: "merge job requires an expected_head_sha (top-level or payload)" };
     }
+    const baseResolution = resolveExecutorJobBaseBranch(job, repositoryBaseBranch);
+    if (!baseResolution.ok) {
+        return { ok: false, error: baseResolution.error };
+    }
+    const expectedBaseBranch = baseResolution.baseBranch;
+    const expectedHeadBranch = asString(job.expected_branch ?? undefined);
+    if (!expectedHeadBranch) {
+        return { ok: false, error: "merge job requires a nonblank expected_branch" };
+    }
     const method = resolveLocalMergeMethod(payload.method);
     const requiredChecks = Array.isArray(payload.required_checks)
         ? payload.required_checks.filter((c) => typeof c === "string")
@@ -62,7 +82,17 @@ export function readMergeJobPayloadFields(job) {
     const ciWaitPollIntervalMs = nonNegativeIntOrUndefined(payload.ci_wait_poll_interval_ms);
     return {
         ok: true,
-        fields: { prNumber, expectedHeadSha, method, requiredChecks, actionKey, ciWaitTimeoutMs, ciWaitPollIntervalMs },
+        fields: {
+            prNumber,
+            expectedHeadSha,
+            method,
+            requiredChecks,
+            actionKey,
+            ciWaitTimeoutMs,
+            ciWaitPollIntervalMs,
+            expectedBaseBranch,
+            expectedHeadBranch,
+        },
     };
 }
 /** Construct the {@link ConductorMergeRequest} for the local merge executor. */
@@ -124,10 +154,18 @@ export function buildMergeJobResult(response, fields) {
  *    safe to re-fire the same merge later.
  *  - {@link MERGE_CONFLICT}: needs a rebase before it can merge.
  *  - {@link MERGE_FAILED}: deterministic other failure (bad state, missing input).
+ *  - {@link MERGE_REF_MISMATCH}: BAPI-1021 — a DELIBERATE, terminal safety
+ *    refusal: the PR's current base or head branch did not match the caller's
+ *    expectation, so no provider merge was attempted. This is neither
+ *    retryable (the mismatch will not resolve itself) nor a rebase target (it
+ *    is not a conflict) — see `_merge_entry_failure_is_retryable` and
+ *    `_merge_entry_failure_requires_rebase` on the backend gate-retry path,
+ *    which both explicitly exclude it.
  */
 export const MERGE_RETRYABLE = "MergeRetryable";
 export const MERGE_CONFLICT = "MergeConflict";
 export const MERGE_FAILED = "MergeFailed";
+export const MERGE_REF_MISMATCH = "MergeRefMismatch";
 /** Reasons whose failure is transient/infrastructure and safe to retry. */
 const RETRYABLE_MERGE_REASONS = new Set([
     "gh_pr_view_timeout",
@@ -151,10 +189,18 @@ const RETRYABLE_MERGE_REASONS = new Set([
  * `ci_poll_`-prefixed reason is retryable — a prefix match keeps unbounded HTTP-status
  * variants covered so a distinct reason never accidentally downgrades to
  * {@link MERGE_FAILED}. Conflict classification is checked first so it is never masked.
+ *
+ * BAPI-1021: `ref_mismatch` is classified BEFORE conflict, retryable-prefix, and
+ * generic-failure handling, and is deliberately NEVER added to
+ * {@link RETRYABLE_MERGE_REASONS} — it is a terminal safety refusal, not a
+ * transient or conflict-shaped failure, and must not be re-firable by any
+ * future classification change.
  */
 export function classifyMergeFailureErrorKind(response) {
     const hasConflictEvent = response.ledger_events.some((ev) => ev.type === "merge.conflict");
     const reason = asString(response.reason ?? undefined);
+    if (reason === "ref_mismatch")
+        return MERGE_REF_MISMATCH;
     if (hasConflictEvent || reason === "gh_merge_conflict")
         return MERGE_CONFLICT;
     if (reason && (reason.startsWith("ci_poll_") || RETRYABLE_MERGE_REASONS.has(reason))) {
@@ -168,13 +214,19 @@ export function classifyMergeFailureErrorKind(response) {
  * `error_message` includes only the sanitized merge status and reason (never raw
  * `gh` output). `classification` stays within the executor's vocabulary; the
  * `error_kind` is the routing signal.
+ *
+ * BAPI-1021: a {@link MERGE_REF_MISMATCH} classifies as `classification:
+ * "clean_exit"` rather than `"crashed"` — it is a deliberate refusal the
+ * executor made correctly, not a crash. Every other merge outcome keeps its
+ * existing `"crashed"` classification.
  */
 export function buildMergeJobFailure(response) {
     const reason = asString(response.reason ?? undefined) ?? response.status;
+    const errorKind = classifyMergeFailureErrorKind(response);
     return {
-        error_kind: classifyMergeFailureErrorKind(response),
+        error_kind: errorKind,
         error_message: secretFreeErrorMessage(new Error(`local merge ${response.status}: ${reason}`)),
-        classification: "crashed",
+        classification: errorKind === MERGE_REF_MISMATCH ? "clean_exit" : "crashed",
     };
 }
 /**
@@ -186,14 +238,8 @@ export function buildMergeJobFailure(response) {
  * merge outcome). NEVER changes the returned result, the `error_kind`, or the
  * `/complete` payload — only emits a sanitized advisory line.
  */
-async function tryEnsurePostMergeEpicIntegrationPr(job, seams) {
-    if (seams.repositoryBaseBranch === undefined)
-        return;
+async function tryEnsurePostMergeEpicIntegrationPr(seams, childBaseBranch) {
     try {
-        const baseResolution = resolveExecutorJobBaseBranch(job, seams.repositoryBaseBranch);
-        if (!baseResolution.ok)
-            return;
-        const childBaseBranch = baseResolution.baseBranch;
         if (!childBaseBranch.startsWith(EPIC_BRANCH_PREFIX))
             return;
         const epicKey = childBaseBranch.slice(EPIC_BRANCH_PREFIX.length);
@@ -220,7 +266,7 @@ async function tryEnsurePostMergeEpicIntegrationPr(job, seams) {
  * bounded, secret-free executor failure.
  */
 export async function runExecutorMergeJob(job, seams) {
-    const resolution = readMergeJobPayloadFields(job);
+    const resolution = readMergeJobPayloadFields(job, seams.repositoryBaseBranch);
     if (!resolution.ok) {
         return {
             ok: false,
@@ -238,6 +284,11 @@ export async function runExecutorMergeJob(job, seams) {
         method: fields.method,
         ciWaitTimeoutMs: fields.ciWaitTimeoutMs,
         ciWaitPollIntervalMs: fields.ciWaitPollIntervalMs,
+        // BAPI-1021 (AC-11): pass the already-resolved expectations through
+        // unchanged so verification and the post-merge enrichment below use one
+        // authoritative value — neither re-resolves it independently.
+        expectedBaseBranch: fields.expectedBaseBranch,
+        expectedHeadBranch: fields.expectedHeadBranch,
     }, seams.localMergeDeps);
     let response;
     try {
@@ -257,7 +308,7 @@ export async function runExecutorMergeJob(job, seams) {
         // Build the successful outcome COMPLETELY first — enrichment can only ever
         // add an advisory log line, never alter what is returned.
         const result = buildMergeJobResult(response, fields);
-        await tryEnsurePostMergeEpicIntegrationPr(job, seams);
+        await tryEnsurePostMergeEpicIntegrationPr(seams, fields.expectedBaseBranch);
         return { ok: true, result };
     }
     return { ok: false, failure: buildMergeJobFailure(response) };

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;