@bridge_gpt/mcp-server 0.2.41 → 0.2.43

package/build/executor/observation.js

@@ -166,9 +166,165 @@ export async function collectRemoteTrackingSha(deps, worktreePath, branch) {
     }
 }
 /**
- * Tolerantly parse one Claude stream-json line for an advisory `phase_hint`.
+ * Utilization at which a still-`allowed` rate limit becomes worth reporting
+ * (BAPI-828).
+ *
+ * The comparison is `>=`, not `>`: a provider that reports
+ * `surpassedThreshold: 0.75` alongside `utilization: 0.75` is telling us the
+ * threshold was reached, and treating exactly-at-threshold as uninteresting would
+ * drop the very first warning the provider bothered to send.
+ */
+export const RATE_LIMIT_WARNING_UTILIZATION = 0.75;
+/**
+ * Character cap on each worker-supplied rate-limit string.
+ *
+ * SMALL ON PURPOSE, unlike the surface observer's line buffer above. These two
+ * values are persisted into job telemetry and interpolated into a stderr line, so
+ * the bound is a content limit rather than a stop-unbounded-growth limit. Real
+ * values (`seven_day`, `allowed_warning`) are an order of magnitude under it.
+ */
+export const MAX_RATE_LIMIT_FIELD_CHARS = 64;
+/**
+ * Normalize one worker-controlled rate-limit string, or `null` when unusable.
+ *
+ * Newlines and tabs collapse to spaces BEFORE truncation. That ordering matters:
+ * the sanitized value is interpolated into a single-line stderr diagnostic, and a
+ * worker that embedded `\n executor: ...` could otherwise forge an executor
+ * diagnostic line in the operator's terminal and in the worker log.
+ */
+function sanitizeRateLimitField(value) {
+    if (typeof value !== "string")
+        return null;
+    const collapsed = value.replace(/[\r\n\t]+/g, " ").trim();
+    if (collapsed.length === 0)
+        return null;
+    return collapsed.slice(0, MAX_RATE_LIMIT_FIELD_CHARS);
+}
+/**
+ * Safely derive an ISO-8601 UTC reset timestamp from worker-controlled input, or
+ * `undefined` when the value is unusable (BAPI-898).
+ *
+ * Stateless and private: a boundary helper that accepts an unknown value plus
+ * the current epoch time and returns a derived string, never the raw input.
+ * Only a finite number is accepted. A value strictly greater than `1e12` is
+ * interpreted as milliseconds since epoch; everything else — including exactly
+ * `1e12` — is interpreted as seconds. A resolved timestamp outside ten years
+ * before or after `nowMs` is rejected as an implausible worker-reported value.
+ *
+ * The result is emitted EXCLUSIVELY through `new Date(timestampMs).toISOString()`
+ * so raw worker input can never enter telemetry or diagnostics.
+ */
+function normalizeRateLimitResetAt(value, nowMs) {
+    if (typeof value !== "number" || !Number.isFinite(value))
+        return undefined;
+    const timestampMs = value > 1e12 ? value : value * 1000;
+    if (!Number.isFinite(timestampMs))
+        return undefined;
+    const now = new Date(nowMs);
+    const min = new Date(now);
+    min.setUTCFullYear(min.getUTCFullYear() - 10);
+    const max = new Date(now);
+    max.setUTCFullYear(max.getUTCFullYear() + 10);
+    if (timestampMs < min.getTime() || timestampMs > max.getTime())
+        return undefined;
+    return new Date(timestampMs).toISOString();
+}
+/**
+ * Rank a rate-limit status by severity for most-severe-wins retention
+ * (BAPI-898): `allowed` is least severe, `allowed_warning` is next, and every
+ * other status (`rejected`, `blocked`, or anything unrecognized) is most severe.
+ *
+ * Pinned independently of stream parsing so retention logic (BAPI-898 Step 2)
+ * can compare severities without re-deriving this mapping.
+ */
+export function rateLimitSeverity(status) {
+    if (status === "allowed")
+        return 0;
+    if (status === "allowed_warning")
+        return 1;
+    return 2;
+}
+/**
+ * Recognize a QUALIFYING `rate_limit_event`, or `null` for everything else.
+ *
+ * Qualification is deliberately two-sided: utilization at or above the warning
+ * threshold, OR a status that is not exactly `allowed`. Either alone would miss a
+ * real case — a hard `blocked` at low utilization is the most actionable event
+ * there is, and a provider that keeps saying `allowed` right up to the ceiling
+ * still deserves a warning at 90%.
+ *
+ * Everything unrecognized returns `null` rather than throwing: this is the
+ * advisory parser, and R5 says a parser that throws is a bug.
+ */
+function parseRateLimitEvent(obj) {
+    if (obj.type !== "rate_limit_event")
+        return null;
+    const info = obj.rate_limit_info;
+    if (!info || typeof info !== "object" || Array.isArray(info))
+        return null;
+    const record = info;
+    const rateLimitType = sanitizeRateLimitField(record.rateLimitType);
+    const status = sanitizeRateLimitField(record.status);
+    if (rateLimitType === null || status === null)
+        return null;
+    const utilization = record.utilization;
+    // `Number.isFinite` rejects NaN and both infinities as well as non-numbers, so a
+    // malformed value can never reach the percentage arithmetic below.
+    if (typeof utilization !== "number" || !Number.isFinite(utilization))
+        return null;
+    const qualifies = utilization >= RATE_LIMIT_WARNING_UTILIZATION || status !== "allowed";
+    if (!qualifies)
+        return null;
+    const advisory = { rate_limit_type: rateLimitType, status, utilization };
+    // Invalid or missing reset data never disqualifies an otherwise-qualifying
+    // advisory — an absent `resets_at` is neutral, not an error.
+    const resetsAt = normalizeRateLimitResetAt(record.resetsAt, Date.now());
+    if (resetsAt !== undefined)
+        advisory.resets_at = resetsAt;
+    return advisory;
+}
+/**
+ * Fixed consequence clause appended to every rate-limit diagnostic (BAPI-898).
+ * Stated exactly once per line so an operator reading it cold understands what
+ * happens next without cross-referencing the runbook.
+ */
+const RATE_LIMIT_CONSEQUENCE_TEXT = "The executor keeps claiming: a worker that hits the ceiling fails fast and its " +
+    "job classifies as a worker failure under the normal retry budget.";
+/** Fixed runbook reference appended to every rate-limit diagnostic (BAPI-898). */
+const RATE_LIMIT_RUNBOOK_REFERENCE = "See docs/claude/epic-conductor-v2-operator-runbook.md §8.";
+/**
+ * Render the operator-facing rate-limit line (BAPI-828, BAPI-898).
+ *
+ * Exported so the stderr text has ONE definition rather than being rebuilt at the
+ * call site — the job runner emits it, and the tests pin it, from here.
+ *
+ * One calm, scannable line: the sanitized limit type, rounded utilization, and
+ * status; whether a reset time is known; the fixed executor consequence; and the
+ * runbook reference. Punctuation shape:
+ * `executor: worker reports … at … (…); <reset clause>. <consequence> <reference>`
+ *
+ * `resets_at` is rendered ONLY from the parser-derived field — never from raw
+ * worker input — and its absence is neutral operational information, not an
+ * error. A non-finite `utilization` reaching this formatter at runtime (outside
+ * the parser's own finite-utilization qualification contract) falls back to
+ * `100%` rather than rendering `NaN%` or `undefined%`.
+ */
+export function formatWorkerRateLimitAdvisory(advisory) {
+    const percent = Number.isFinite(advisory.utilization) ? Math.round(advisory.utilization * 100) : 100;
+    const resetClause = advisory.resets_at !== undefined ? `; resets at ${advisory.resets_at}` : "; reset time not reported";
+    return (`executor: worker reports ${advisory.rate_limit_type} rate limit at ` +
+        `${percent}% (${advisory.status})${resetClause}. ` +
+        `${RATE_LIMIT_CONSEQUENCE_TEXT} ${RATE_LIMIT_RUNBOOK_REFERENCE}`);
+}
+/**
+ * Tolerantly parse one Claude stream-json line for advisory signals.
  * Catches ALL parse/schema errors and never throws; returns `{}` when nothing
  * usable is found.
+ *
+ * BAPI-828: a line may now yield BOTH a `phase_hint` and a `rate_limit` record.
+ * They are independent observations of the same event, so neither suppresses the
+ * other — a `rate_limit_event` still contributes its type as a phase hint exactly
+ * as it did before this ticket.
  */
 export function parseClaudeStreamJsonLine(line) {
     try {
@@ -179,11 +335,17 @@ export function parseClaudeStreamJsonLine(line) {
         if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
             return {};
         const obj = parsed;
+        const out = {};
         // Advisory only: prefer an explicit phase/subtype, else the stream event type.
         const hint = pickString(obj.phase) ??
             pickString(obj.subtype) ??
             pickString(obj.type);
-        return hint ? { phase_hint: hint } : {};
+        if (hint)
+            out.phase_hint = hint;
+        const rateLimit = parseRateLimitEvent(obj);
+        if (rateLimit)
+            out.rate_limit = rateLimit;
+        return out;
     }
     catch {
         return {};
@@ -357,6 +519,13 @@ export function createMcpSurfaceObserver(expectedServerNames, parseInitEvent) {
         },
     };
 }
+/**
+ * Cap on the partial advisory line the observation state will buffer, in
+ * characters. Mirrors {@link MAX_BUFFERED_SURFACE_LINE_CHARS} and exists for the
+ * same reason: hold one complete stream-json line intact so a chunk boundary
+ * cannot hide an event, while still refusing to grow without bound.
+ */
+export const MAX_BUFFERED_ADVISORY_LINE_CHARS = 1_048_576;
 /**
  * Create the observation state. When `advisoryParserEnabled` is false, stdout is
  * still timestamped (`last_stdout_at`) but never parsed — proving the advisory
@@ -368,16 +537,95 @@ export function createObservationState(deps, options) {
     let exitCode;
     let attemptStartSha;
     let attemptEndSha;
+    /**
+     * BAPI-828/BAPI-898: the MOST SEVERE qualifying advisory observed so far wins,
+     * ranked by {@link rateLimitSeverity}. An advisory at equal or lower severity —
+     * including a repeat of the same event or a warning observed after a rejection
+     * — leaves this unchanged.
+     */
+    let rateLimit;
+    /** Residual partial line carried across stdout chunks (BAPI-828). */
+    let buffer = "";
+    /** True while skipping the remainder of a line that blew the size cap. */
+    let discardingOversizedLine = false;
+    const consumeAdvisoryLine = (line) => {
+        const parsed = parseClaudeStreamJsonLine(line);
+        if (parsed.phase_hint)
+            advisory.phase_hint = parsed.phase_hint;
+        if (parsed.rate_limit) {
+            const observedAdvisory = parsed.rate_limit;
+            const isFirstObservation = rateLimit === undefined;
+            // BAPI-898: strict severity comparison replaces the old "first advisory
+            // wins" rule. Equal or lower severity — a repeat event or a warning
+            // observed after a rejected/blocked status — leaves the stored advisory
+            // unchanged.
+            if (isFirstObservation ||
+                rateLimitSeverity(observedAdvisory.status) > rateLimitSeverity(rateLimit.status)) {
+                rateLimit = observedAdvisory;
+            }
+            // The callback preserves one stderr line per job: it fires ONLY for the
+            // first qualifying advisory, while a later severity escalation is still
+            // retained above for `observation.snapshot()` and the existing terminal
+            // telemetry path.
+            if (isFirstObservation) {
+                try {
+                    options.onWorkerRateLimitAdvisory?.(observedAdvisory);
+                }
+                catch {
+                    // The callback only logs. A throwing one must not propagate out of the
+                    // stdout pump, where it would be swallowed as a stream error and
+                    // silently disable observation for the rest of the run.
+                }
+            }
+        }
+    };
     return {
         recordStdout(chunk) {
             advisory.last_stdout_at = new Date(deps.now()).toISOString();
             if (!options.advisoryParserEnabled)
                 return;
-            for (const line of chunk.split("\n")) {
-                const hint = parseClaudeStreamJsonLine(line);
-                if (hint.phase_hint)
-                    advisory.phase_hint = hint.phase_hint;
+            if (typeof chunk !== "string" || chunk.length === 0)
+                return;
+            // BAPI-828: line assembly replaces the previous per-chunk `split("\n")`.
+            // stdout arrives in arbitrary chunks, and a `rate_limit_event` split across
+            // two reads used to be parsed as two malformed halves and lost. Phase hints
+            // tolerated that (the next event supplied another); a rate-limit event may
+            // legitimately occur once in a whole run, so losing it loses the signal.
+            let input = chunk;
+            // Still skipping past a line that already blew the cap. Resync ON THE
+            // NEWLINE rather than merely clearing, so the dead line's tail cannot be
+            // parsed as though it were a fresh event.
+            if (discardingOversizedLine) {
+                const resyncAt = input.indexOf("\n");
+                if (resyncAt === -1)
+                    return;
+                discardingOversizedLine = false;
+                input = input.slice(resyncAt + 1);
+            }
+            buffer += input;
+            let newlineAt = buffer.indexOf("\n");
+            while (newlineAt !== -1) {
+                consumeAdvisoryLine(buffer.slice(0, newlineAt));
+                buffer = buffer.slice(newlineAt + 1);
+                newlineAt = buffer.indexOf("\n");
+            }
+            if (buffer.length > MAX_BUFFERED_ADVISORY_LINE_CHARS) {
+                // Unparseable by definition, and not worth carrying. Drop it and resync;
+                // a LATER valid line still parses normally, so one pathological line
+                // cannot disable advisory observation for the rest of the run.
+                buffer = "";
+                discardingOversizedLine = true;
+                return;
             }
+            // Parse the residual NON-destructively. A worker whose final chunk carries
+            // no trailing newline would otherwise strand its last event in the buffer
+            // forever — and the pre-BAPI-828 parser DID read that trailing fragment, so
+            // skipping it would be a silent regression in phase-hint reporting. Keeping
+            // the buffer means the same bytes are re-parsed once the rest arrives, which
+            // is harmless: a truncated line does not parse, and the first-wins guard
+            // above makes a repeat parse of a complete line a no-op.
+            if (buffer.length > 0)
+                consumeAdvisoryLine(buffer);
         },
         setGitTelemetry(telemetry) {
             git = telemetry;
@@ -404,6 +652,11 @@ export function createObservationState(deps, options) {
                 residue.phase_hint = advisory.phase_hint;
             if (advisory.last_stdout_at)
                 residue.last_stdout_at = advisory.last_stdout_at;
+            // BAPI-828: rides the existing envelope into heartbeats and terminal
+            // mutations. Absent when no qualifying event was seen, so a job that never
+            // approached a limit serializes byte-identically to before this ticket.
+            if (rateLimit !== undefined)
+                residue.rate_limit = rateLimit;
             if (exitCode !== undefined)
                 residue.exit_code = exitCode;
             // The attempt boundary pair is independent of `last_commit_sha`: it

package/build/executor/platform.js

@@ -16,10 +16,19 @@
  * `CLAUDE_CODE_OAUTH_TOKEN` before an otherwise-runnable host may claim work
  * would reintroduce exactly the onboarding barrier this epic removes.
  *
- * PURE. Nothing here reads the filesystem, the environment, or a credential.
- * The returned reason is a fixed sentence plus the platform name — never a host
- * path, an environment value, or raw exception text.
+ * PURE (the gate). `evaluateExecutorPlatform` and its message renderer read no
+ * filesystem, no environment, and no credential. The returned reason is a fixed
+ * sentence plus the platform name — never a host path, an environment value, or
+ * raw exception text.
+ *
+ * BAPI-828 adds a SECOND, deliberately impure concern to this module: the Darwin
+ * sleep assertion at the bottom. It lives here because it answers the same kind
+ * of question — "what does this executor do differently because of the platform
+ * it is on" — and a competing `platform-ish` module is how two places end up
+ * disagreeing about what `darwin` means. It spawns a child and reads the
+ * executor's own environment, so the purity claim above is scoped to the gate.
  */
+import { createProcessTerminationController } from "./process.js";
 /**
  * Platforms on which a conductor worker may be spawned.
  *
@@ -52,3 +61,138 @@ export function evaluateExecutorPlatform(platform) {
     }
     return { supported: false, platform: name, message: formatUnsupportedExecutorPlatform(name) };
 }
+// ---------------------------------------------------------------------------
+// Darwin sleep assertion (BAPI-828)
+// ---------------------------------------------------------------------------
+/**
+ * Executor-only opt-out for the Darwin sleep assertion.
+ *
+ * READ FROM THE EXECUTOR'S OWN ENVIRONMENT ONLY, and never forwarded to a
+ * worker. `env.ts`'s `ALLOWED_ENV_KEYS` is a strict twelve-key allowlist, so this
+ * key is excluded from every worker environment by construction — nothing needed
+ * adding to a deny list, and nothing may be added to the allowlist for it. A
+ * worker holds no sleep assertion of its own, so letting job-side state reach
+ * this decision would invert the trust boundary for no benefit.
+ */
+export const EXECUTOR_NO_SLEEP_ASSERTION_ENV = "BAPI_EXECUTOR_NO_SLEEP_ASSERTION";
+/**
+ * Grace before the assertion child is escalated to `SIGKILL`.
+ *
+ * Much shorter than a worker's ten seconds on purpose: `caffeinate` has no work
+ * to flush and no state to commit, so a lingering one is pure delay at shutdown.
+ */
+export const SLEEP_ASSERTION_GRACE_MS = 2_000;
+/**
+ * The exact assertion command. `caffeinate -i -s -w <pid>`:
+ *  - `-i` prevents idle SYSTEM sleep (the failure this ticket exists for),
+ *  - `-s` prevents sleep while on AC power,
+ *  - `-w <pid>` ties the assertion's lifetime to the executor process, so even a
+ *    `SIGKILL`ed executor — the one shutdown path that cannot run cleanup — stops
+ *    holding the machine awake as soon as it dies.
+ */
+export const SLEEP_ASSERTION_COMMAND = "caffeinate";
+/** Build the fixed assertion argv for `executorPid`. */
+export function buildSleepAssertionArgs(executorPid) {
+    return ["-i", "-s", "-w", String(executorPid)];
+}
+/**
+ * FIXED failure text. Deliberately carries no error message, no argv, and no
+ * environment: a spawn failure can echo the environment it failed to apply, and
+ * that environment may hold the operator's forwarded token. There is nothing an
+ * operator can do with the underlying errno that this sentence does not already
+ * tell them, so nothing is lost by refusing to interpolate it.
+ */
+export const SLEEP_ASSERTION_FAILED_MESSAGE = "executor could not hold a sleep assertion (caffeinate); continuing without it — " +
+    "on a laptop, keep the host awake by other means or the run may stall while it sleeps";
+/** FIXED premature-exit text, secret-free for the same reason. */
+export const SLEEP_ASSERTION_EXITED_MESSAGE = "executor sleep assertion (caffeinate) exited before the executor did; the host may " +
+    "idle-sleep for the remainder of this run";
+/** Render the success line, which names only the child's pid. */
+export function formatSleepAssertionHeld(pid) {
+    return `executor holding sleep assertion (caffeinate pid ${pid})`;
+}
+/** The shared inert handle shape; `release` resolves immediately. */
+const INERT_ASSERTION = {
+    held: false,
+    release: async () => { },
+};
+/**
+ * Start a Darwin sleep assertion for the executor's lifetime.
+ *
+ * FAIL-OPEN, ALWAYS. Every failure mode — a non-Darwin host, the opt-out, a
+ * throwing spawn, a child with no usable pid, a `caffeinate` that dies early —
+ * produces at most one bounded diagnostic and an inert handle. Not one of them
+ * prevents the executor from claiming: an executor that refused to work because
+ * it could not stop the laptop sleeping would be a strictly worse outcome than
+ * the sleep it is guarding against.
+ *
+ * GATED BEFORE ANY SPAWN. The platform and opt-out checks run before
+ * `spawnProcess` is touched, so a linux host and an opted-out darwin host each
+ * perform exactly zero process work — which is what makes "no probe on an
+ * unsupported platform" assertable rather than merely likely.
+ */
+export function startExecutorSleepAssertion(deps) {
+    if (deps.platform !== "darwin")
+        return INERT_ASSERTION;
+    if (deps.env[EXECUTOR_NO_SLEEP_ASSERTION_ENV] === "1")
+        return INERT_ASSERTION;
+    // The executor's own environment, minus the keys Node reports as undefined
+    // (`SpawnProcessOptions.env` is `Record<string, string>`). No filtering beyond
+    // that: `caffeinate` is a first-party Apple binary that reads no credential,
+    // and handing it a stripped environment would only risk breaking its PATH.
+    const env = {};
+    for (const [key, value] of Object.entries(deps.env)) {
+        if (typeof value === "string")
+            env[key] = value;
+    }
+    let child;
+    try {
+        child = deps.spawnProcess(SLEEP_ASSERTION_COMMAND, buildSleepAssertionArgs(deps.executorPid), {
+            cwd: deps.cwd,
+            env,
+        });
+    }
+    catch {
+        deps.errorLog(SLEEP_ASSERTION_FAILED_MESSAGE);
+        return INERT_ASSERTION;
+    }
+    // A spawn that "succeeded" without producing a usable child is the same
+    // situation as one that threw: we are not holding an assertion, and pretending
+    // otherwise would report a guard that does not exist.
+    if (!child || typeof child.pid !== "number" || typeof child.kill !== "function") {
+        deps.errorLog(SLEEP_ASSERTION_FAILED_MESSAGE);
+        return INERT_ASSERTION;
+    }
+    deps.errorLog(formatSleepAssertionHeld(child.pid));
+    // Cleanup routes through the SAME escalation used for workers, so there is one
+    // implementation of "ask a child to stop, then insist" in the executor.
+    const controller = createProcessTerminationController(child, deps, SLEEP_ASSERTION_GRACE_MS);
+    let releasing = false;
+    // Watch the child WITHOUT blocking startup: claiming must not wait on this, and
+    // an assertion that dies early is a warning, never a job failure. Reporting is
+    // suppressed once WE initiated the release, because a child exiting after being
+    // asked to is the expected outcome, not a premature death.
+    const settled = (async () => {
+        try {
+            await child.wait();
+        }
+        catch {
+            /* an unobservable exit is still an exit */
+        }
+        if (!releasing)
+            deps.errorLog(SLEEP_ASSERTION_EXITED_MESSAGE);
+    })();
+    return {
+        held: true,
+        async release() {
+            if (releasing)
+                return;
+            releasing = true;
+            controller.requestTermination();
+            // Await the child so a caller that releases and then exits does not race the
+            // teardown, and so `pmset -g assertions` is observably clean afterwards.
+            await settled;
+            controller.dispose();
+        },
+    };
+}

package/build/executor/process.js

@@ -2,6 +2,48 @@
 export const DEFAULT_EXCERPT_BYTES = 8_000;
 /** Default SIGTERM→SIGKILL grace period (ms). */
 export const DEFAULT_TERM_GRACE_MS = 10_000;
+/**
+ * Create the shared termination controller for `proc`.
+ *
+ * `termGraceMs` is captured at creation, so a controller handed to
+ * {@link runProcessWithTimeout} keeps the grace period its creator chose rather
+ * than silently adopting a second one.
+ */
+export function createProcessTerminationController(proc, deps, termGraceMs = DEFAULT_TERM_GRACE_MS) {
+    let requested = false;
+    let escalated = false;
+    let disposed = false;
+    let graceTimer;
+    return {
+        requestTermination() {
+            // A disposed controller belongs to a settled child: signalling it would
+            // either hit nothing or, worse, a recycled pid.
+            if (requested || disposed)
+                return;
+            requested = true;
+            proc.kill("SIGTERM");
+            graceTimer = deps.setTimer(() => {
+                graceTimer = undefined;
+                if (escalated || disposed)
+                    return;
+                escalated = true;
+                proc.kill("SIGKILL");
+            }, termGraceMs);
+        },
+        isTerminationRequested() {
+            return requested;
+        },
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            if (graceTimer !== undefined) {
+                deps.clearTimer(graceTimer);
+                graceTimer = undefined;
+            }
+        },
+    };
+}
 function byteLength(value) {
     return Buffer.byteLength(value, "utf8");
 }
@@ -45,19 +87,19 @@ export async function runProcessWithTimeout(proc, timeoutSeconds, deps, options
     const limit = options.excerptLimitBytes ?? DEFAULT_EXCERPT_BYTES;
     let stdoutExcerpt = "";
     let stderrExcerpt = "";
+    /**
+     * Reserved for the `onStdoutTerminationCheck` containment path ONLY (BAPI-828).
+     * An executor `SIGTERM`/`SIGINT` shutdown reaches the same controller below but
+     * must NOT set this flag: reporting an operator-initiated stop as an MCP
+     * containment refusal would invent a containment failure that never happened.
+     */
     let terminationRequested = false;
-    let terminating = false;
-    let graceTimer;
-    /** TERM now, KILL after the grace period. Idempotent — never signals twice. */
-    const terminate = () => {
-        if (terminating)
-            return;
-        terminating = true;
-        proc.kill("SIGTERM");
-        graceTimer = deps.setTimer(() => {
-            proc.kill("SIGKILL");
-        }, termGraceMs);
-    };
+    // ONE escalation mechanism, whoever asks. Reused when the job runner already
+    // created and registered a controller for this child (BAPI-828), so executor
+    // shutdown, timeout, and MCP containment converge on a single `SIGTERM` and a
+    // single grace timer rather than racing three of each.
+    const controller = options.terminationController ?? createProcessTerminationController(proc, deps, termGraceMs);
+    const terminate = () => controller.requestTermination();
     const pumpStdout = pump(proc.stdout, (chunk) => {
         // Advisory observation ALWAYS runs first and always runs: the tee and the
         // telemetry must see every chunk regardless of what the assertion decides.
@@ -80,8 +122,10 @@ export async function runProcessWithTimeout(proc, timeoutSeconds, deps, options
     }, timeoutSeconds * 1000);
     const { exitCode, signal } = await proc.wait();
     deps.clearTimer(timeoutTimer);
-    if (graceTimer !== undefined)
-        deps.clearTimer(graceTimer);
+    // The child has settled, so any outstanding escalation is now aimed at a
+    // finished process. Disposal is idempotent and safe for a controller this call
+    // did not create — the job runner's `finally` may dispose it again.
+    controller.dispose();
     await pumpStdout;
     await pumpStderr;
     let classification;