@bridge_gpt/mcp-server 0.2.41 → 0.2.42

package/build/executor/job-runner.js

@@ -24,7 +24,7 @@ import { getWorktreeMcpRegistrationTargets, normalizeWorktreePathForRegistration
 import { resolveExecutorAgentAdapter } from "../agent-launchers/executor-adapter-registry.js";
 import { redactAdapterDiagnostic } from "../agent-launchers/executor-adapter.js";
 import { resolveExecutorAgentId } from "./agent-identity.js";
-import { runProcessWithTimeout } from "./process.js";
+import { createProcessTerminationController, runProcessWithTimeout } from "./process.js";
 import { prepareResumeSpawn } from "./resume-pre-spawn.js";
 import { renderPromptSpecPrompt } from "./prompt-spec.js";
 import { buildGenericSuccessResult, buildSmokeResult, commitResidue, readCompletionArtifacts, resolveJobTimeoutSeconds, } from "./results.js";
@@ -33,15 +33,17 @@ import { removeStaleVerdictArtifacts } from "./stale-artifacts.js";
 import { isVerdictJobType, readVerdictArtifact } from "./verdict-artifact.js";
 import { createWorkerLogTee, closeWorkerLogTee, distinctWorkerLogSessionIds, formatWorkerLogSessionInvariantWarning, teeAsyncIterable, } from "./worker-log.js";
 import { acquireExecutorWorktreeLock, } from "./worktree-lock.js";
-import { registerExecutorJobLog, markExecutorJobLogFinished, } from "./job-log-registry.js";
+import { activateJobLog, deactivateJobLog, registerExecutorJobLog, markExecutorJobLogFinished, } from "./job-log-registry.js";
 import { executorViewerTabsEnabled, openExecutorViewerTab } from "./viewer-tabs.js";
 import { isImplementationStyleJobType, isRecoveryJobType, isSpawnJobType } from "./job-types.js";
 import { resolveExecutorJobBaseBranch } from "./base-branch.js";
+import { resolveExecutorJobIndexScope } from "./index-scope.js";
 import { validateWorkerFinalization } from "./worker-finalization.js";
 import { ensureExecutorWorktree } from "./worktree.js";
 import { buildPrBaseContractLaunchInstruction } from "../pr-base-contract.js";
 import { resolveExecutorPrompt, resolveWorkerPermissionPosture, } from "./worker-command.js";
-import { collectGitTelemetry, collectRemoteTrackingSha, createMcpSurfaceObserver, evaluatePreSpawnGitVerification, normalizeMcpServerNames, } from "./observation.js";
+import { collectGitTelemetry, collectRemoteTrackingSha, createMcpSurfaceObserver, evaluatePreSpawnGitVerification, formatWorkerRateLimitAdvisory, normalizeMcpServerNames, } from "./observation.js";
+import { isRecognizedServerName, MCP_SERVER_NAME } from "../mcp-identity.js";
 /** Default runtime for the no-op smoke process (ms). */
 const DEFAULT_SMOKE_DURATION_MS = 100;
 /** ProcessClassification maps 1:1 onto the wire ExecutorClassification. */
@@ -249,7 +251,7 @@ async function provisionMcpForPreparedSpawn(job, branch, worktreePath, deps, sea
  * Only server NAMES are read. The command, args, and env of each registration are
  * never retained, so nothing that could carry a secret leaves this function.
  */
-export async function verifyRequiredWorktreeMcpRegistration(worktreePath, deps, requiredServerName = REQUIRED_MCP_SERVER_NAME) {
+export async function verifyRequiredWorktreeMcpRegistration(worktreePath, deps, requiredServerName = MCP_SERVER_NAME) {
     // Normalize through the SAME path semantics the provisioner used to write the
     // file, so the absolute path handed to `--mcp-config` is the one that actually
     // exists on disk rather than a differently-spelled equivalent.
@@ -275,7 +277,17 @@ export async function verifyRequiredWorktreeMcpRegistration(worktreePath, deps,
             return { ok: false, message: REQUIRED_MCP_REGISTRATION_MISSING_MESSAGE };
         }
         const names = normalizeMcpServerNames(Object.keys(servers));
-        if (!names.includes(requiredServerName)) {
+        // BAPI-807: when the required name is Bridge's OWN registration, a
+        // permanently-supported legacy key satisfies it. A worktree provisioned
+        // before the rename (or re-entered from one) registers `bridge-api`, and
+        // refusing to spawn into it would turn the rename into an outage for exactly
+        // the users the legacy compatibility exists to protect. A non-Bridge
+        // `requiredServerName` (a future adapter's own runtime) is matched exactly,
+        // as before.
+        const satisfied = requiredServerName === MCP_SERVER_NAME
+            ? names.some((name) => isRecognizedServerName(name))
+            : names.includes(requiredServerName);
+        if (!satisfied) {
             return { ok: false, message: REQUIRED_MCP_REGISTRATION_MISSING_MESSAGE };
         }
         return {
@@ -289,12 +301,6 @@ export async function verifyRequiredWorktreeMcpRegistration(worktreePath, deps,
         return { ok: false, message: REQUIRED_MCP_REGISTRATION_MISSING_MESSAGE };
     }
 }
-/**
- * Default required registration name, retained only as the parameter default so
- * existing direct callers keep working. The SPAWN PATH always passes the
- * adapter's declared name explicitly — it never relies on this default.
- */
-const REQUIRED_MCP_SERVER_NAME = "bridge-api";
 /**
  * Refuse a spawn shape that is not internally consistent (BAPI-781).
  *
@@ -336,7 +342,7 @@ function assertUsableSpawnShape(shape, adapter) {
     }
 }
 /** Fixed, secret-free refusal text (no path, no file contents). */
-const REQUIRED_MCP_REGISTRATION_MISSING_MESSAGE = "the required 'bridge-api' MCP registration is missing or unreadable in the prepared " +
+const REQUIRED_MCP_REGISTRATION_MISSING_MESSAGE = `the required '${MCP_SERVER_NAME}' MCP registration is missing or unreadable in the prepared ` +
     "worktree; a worker loads MCP servers strictly from that file, so refusing to spawn a " +
     "worker that would run without Bridge tools";
 /**
@@ -471,6 +477,9 @@ async function superviseProcess(params) {
     const mcpSurface = params.mcpSurface;
     const result = await runProcessWithTimeout(params.proc, params.timeoutSeconds, params.deps, {
         termGraceMs: params.options.termGraceMs,
+        ...(params.terminationController
+            ? { terminationController: params.terminationController }
+            : {}),
         onStdout: (chunk) => params.observation.recordStdout(chunk),
         ...(mcpSurface
             ? {
@@ -503,12 +512,33 @@ function terminalToRunResult(terminal, successStatus) {
     }
 }
 /** Dispatch and run a single claimed job. */
-export async function runClaimedJob(job, httpClient, options, deps, _report, seams = {}) {
+export async function runClaimedJob(job, httpClient, options, deps, _report, seams = {}, 
+/**
+ * BAPI-828: the runner-scoped control object, carrying the live worker
+ * registry this job's worker registers with.
+ *
+ * A SEVENTH positional parameter, appended after the existing seams argument so
+ * every current caller — the runner's default `runJob`, the many tests that
+ * invoke this directly with four to six arguments — keeps compiling unchanged.
+ * Absent means no executor-level shutdown control, which is exactly right for a
+ * caller that has no executor loop around it.
+ */
+control) {
     const ownership = {
         abandoned: false,
         lastSuccessfulHeartbeatAt: deps.now(),
     };
-    const observation = createObservationState({ now: deps.now }, { advisoryParserEnabled: options.advisoryParserEnabled });
+    const observation = createObservationState({ now: deps.now }, {
+        advisoryParserEnabled: options.advisoryParserEnabled,
+        // BAPI-828: ONE line per job, from the per-job observation's first-wins
+        // retention rather than from a counter here. A worker nearing a weekly
+        // ceiling repeats the same event on every turn, and the operator needs the
+        // fact once. Emitting is all this does — no claim, retry, lease, or
+        // classification decision reads it.
+        onWorkerRateLimitAdvisory: (advisory) => {
+            deps.errorLog(formatWorkerRateLimitAdvisory(advisory));
+        },
+    });
     // `merge` is a deterministic executor action: dispatched BEFORE any worktree
     // ensure/recreate or worker-spawn logic — it ensures no worktree and spawns no
     // worker (TDD §5/§9).
@@ -530,7 +560,7 @@ export async function runClaimedJob(job, httpClient, options, deps, _report, sea
         // are stateless with respect to the host, which is why the whole
         // establish/dispose lifetime this branch used to manage simply stopped
         // existing rather than moving somewhere else.
-        return await runSpawnJob(job, httpClient, options, deps, ownership, observation, seams);
+        return await runSpawnJob(job, httpClient, options, deps, ownership, observation, seams, control);
     }
     // Unsupported job type — fail server-side; never spawn.
     await httpClient.fail(job, {
@@ -915,7 +945,7 @@ async function prepareSpawn(job, httpClient, options, deps, seams) {
  * returns BEFORE either the deny layer or MCP provisioning runs — neither ever
  * touches a worktree that will not become a runnable worker.
  */
-async function runSpawnJob(job, httpClient, options, deps, ownership, observation, seams) {
+async function runSpawnJob(job, httpClient, options, deps, ownership, observation, seams, control) {
     // --- Per-job base branch (BAPI-586) ----------------------------------
     // Resolve the effective logical base BEFORE any side effect: the persisted
     // run base (`payload.base_branch`) is authoritative, falling back to the
@@ -971,6 +1001,23 @@ async function runSpawnJob(job, httpClient, options, deps, ownership, observatio
     }
     const effectiveBaseBranch = baseResolution.baseBranch;
     const jobOptions = { ...options, baseBranch: effectiveBaseBranch };
+    // --- Declared index scope (BAPI-844) ---------------------------------
+    // Resolved here, alongside the base branch and for the same reason: a job that
+    // declares a scope it cannot be routed by must fail before a worktree is cut, a
+    // deny layer is written, MCP is provisioned, a log is opened, or a process is
+    // spawned. An ABSENT declaration is the ordinary unscoped job and adds nothing
+    // anywhere downstream. The error text names the field only — the declared value
+    // is opaque and never reaches `/fail`.
+    const indexScopeResolution = resolveExecutorJobIndexScope(job);
+    if (!indexScopeResolution.ok) {
+        await httpClient.fail(job, {
+            error_kind: "ContractError.IndexScope",
+            error_message: indexScopeResolution.error,
+            classification: "crashed",
+        });
+        return { status: "failed", reason: "index_scope_contract" };
+    }
+    const indexScope = indexScopeResolution.indexScope;
     // --- Permission posture (BAPI-725) -----------------------------------
     // Resolved alongside the base branch, BEFORE any side effect, for the same
     // reason: an unsupported posture is a contract failure, and failing it here
@@ -1032,6 +1079,12 @@ async function runSpawnJob(job, httpClient, options, deps, ownership, observatio
         });
         return { status: "failed", reason: "worktree_busy" };
     }
+    // BAPI-828: the post-spawn lifecycle handles this job's worker owns, filled in
+    // by `runPreparedSpawn` as each resource comes into existence and unwound in
+    // the `finally` below. A shared mutable record rather than return values,
+    // because the resources must be released even when `runPreparedSpawn` throws —
+    // which is exactly the path that has no return value to inspect.
+    const spawnLifecycle = {};
     try {
         // --- Stale verdict artifacts (BAPI-814/D1) --------------------------
         // Inside the lock and BEFORE the worker spawns, on the SHARED attempt path,
@@ -1078,14 +1131,31 @@ async function runSpawnJob(job, httpClient, options, deps, ownership, observatio
             branch,
             prep,
             effectiveBaseBranch,
+            indexScope,
             permissionPosture,
             adapter,
+            control,
+            lifecycle: spawnLifecycle,
         });
     }
     finally {
-        // Released only here — after supervision has settled and every terminal
-        // mutation above has been attempted — so the worktree is never advertised as
-        // free while this job's worker could still be touching it.
+        // BAPI-828 — cleanup ORDER is the contract, and it runs strictly after
+        // `runPreparedSpawn` has settled (normally or by throwing), which means
+        // strictly after process supervision has settled:
+        //
+        //   1. Deregister the worker. It is no longer live, so a shutdown arriving
+        //      now must not try to signal it — the registry should only ever hold
+        //      children that might still be running.
+        //   2. Close and deactivate the worker log. Idempotent: the terminal branches
+        //      inside `runPreparedSpawn` already close it on their way out, and this
+        //      is the backstop for the exceptional paths that do not.
+        //   3. Release the worktree lock — LAST, and still through the same
+        //      ownership-checked `release()` as before this ticket. The worktree must
+        //      never be advertised as free while this job's worker could still be
+        //      touching it, and the two steps above are what establish that it cannot.
+        spawnLifecycle.deregisterLiveWorker?.();
+        spawnLifecycle.deregisterLiveWorker = undefined;
+        await spawnLifecycle.closeWorkerLog?.();
         await worktreeLock.release();
     }
 }
@@ -1100,7 +1170,7 @@ async function runSpawnJob(job, httpClient, options, deps, ownership, observatio
  * rather than a 500-line indentation nobody can verify by eye.
  */
 async function runPreparedSpawn(params) {
-    const { job, httpClient, options, jobOptions, deps, ownership, observation, seams, worktreePath, branch, prep, effectiveBaseBranch, permissionPosture, adapter, } = params;
+    const { job, httpClient, options, jobOptions, deps, ownership, observation, seams, worktreePath, branch, prep, effectiveBaseBranch, indexScope, permissionPosture, adapter, control, lifecycle, } = params;
     // BAPI-586: PR-producing spawn jobs (implement/resume/remediate/ci_fix/rebase)
     // are told to open the PR against the injected run base. Verdict-only
     // `spec_review` produces no PR, so it is excluded from the instruction while
@@ -1247,7 +1317,31 @@ async function runPreparedSpawn(params) {
     catch {
         tee = null;
     }
+    // BAPI-828 — idempotent worker-log closure, defined the moment a tee could
+    // exist. Every terminal branch below calls this instead of `closeWorkerLogTee`
+    // directly, and `runSpawnJob`'s `finally` calls it once more as a backstop for
+    // the paths that throw. Before this ticket the close was open-coded at eleven
+    // separate return sites, which is why the active-log deactivation is folded in
+    // here rather than added as a twelfth thing each branch had to remember.
+    let workerLogClosed = false;
+    const closeWorkerLog = async () => {
+        if (workerLogClosed)
+            return;
+        workerLogClosed = true;
+        // Deactivate FIRST: once the tee is closing, an append from the suspend
+        // diagnostic would be writing to a log nobody is reading any more.
+        deactivateJobLog(job.id);
+        await closeWorkerLogTee(tee);
+    };
+    lifecycle.closeWorkerLog = closeWorkerLog;
     if (tee) {
+        // BAPI-828 — mark the log appendable as soon as the tee EXISTS, and
+        // deliberately BEFORE the watch-registry persistence below. The two are
+        // independent on purpose: `registerLog` swallows its own failures (it is a
+        // visibility nicety for a separate `executor watch` process), and chaining
+        // the active marker to it would mean a failed registry write silently
+        // disables suspend annotation for a worker whose tee is perfectly healthy.
+        activateJobLog(job.id, tee.logPath);
         const registerLog = seams.registerExecutorJobLog ?? registerExecutorJobLog;
         try {
             await registerLog({
@@ -1312,9 +1406,16 @@ async function runPreparedSpawn(params) {
     //
     // BAPI-586: the validated run base travels in as BAPI_BASE_BRANCH so the
     // worker can target it via `gh pr create --base "$BAPI_BASE_BRANCH"`.
+    //
+    // BAPI-844: the validated declared index scope travels the same way, as an
+    // explicit option rather than through the environment this process happens to
+    // hold — the executor's own `BAPI_INDEX_SCOPE`, if an operator exported one,
+    // is denied at the env builder and cannot reach `spawnShape.env`. It stays out
+    // of `argv` entirely: it is a routing declaration, not a command-line input,
+    // and argv is world-readable via `ps`.
     const invocation = adapter.headlessInvocation;
     if (invocation?.supported !== true) {
-        await closeWorkerLogTee(tee);
+        await closeWorkerLog();
         await finalizeRegistry();
         await httpClient.fail(job, {
             error_kind: ExecutorAdapterUnavailable,
@@ -1332,6 +1433,7 @@ async function runPreparedSpawn(params) {
             posture: permissionPosture,
             mcpConfigPath: mcpContract.configPath,
             effectiveBaseBranch,
+            indexScope,
             parentEnv: deps.env,
         });
         assertUsableSpawnShape(spawnShape, adapter);
@@ -1342,7 +1444,7 @@ async function runPreparedSpawn(params) {
         // a missing argv from Claude's flags is precisely the defaulting this
         // extraction removes, and it would spawn a real worker under a shape nobody
         // declared.
-        await closeWorkerLogTee(tee);
+        await closeWorkerLog();
         await finalizeRegistry();
         await httpClient.fail(job, {
             error_kind: ExecutorAdapterUnavailable,
@@ -1360,7 +1462,7 @@ async function runPreparedSpawn(params) {
     // certify its own containment.
     const initParsing = adapter.mcpInitParsing;
     if (initParsing?.supported !== true) {
-        await closeWorkerLogTee(tee);
+        await closeWorkerLog();
         await finalizeRegistry();
         await httpClient.fail(job, {
             error_kind: ExecutorAdapterUnavailable,
@@ -1378,7 +1480,7 @@ async function runPreparedSpawn(params) {
         });
     }
     catch (err) {
-        await closeWorkerLogTee(tee);
+        await closeWorkerLog();
         await finalizeRegistry();
         // Redact through the adapter's declared secret names before bounding. A
         // spawn error can echo the environment it failed to apply, and that
@@ -1394,6 +1496,22 @@ async function runPreparedSpawn(params) {
         });
         return { status: "failed", reason: "spawn_failed" };
     }
+    // --- Live worker registration (BAPI-828) ------------------------------
+    // Immediately after the ONE successful `deps.spawnProcess` above, and strictly
+    // before any asynchronous supervision begins. That ordering is the whole
+    // guarantee: between the spawn returning and supervision starting there is real
+    // async work (the tee wrapper, the telemetry closures), and a `SIGTERM` landing
+    // in that window used to find a live child that nothing owned.
+    //
+    // The controller is created against the RAW `proc`, not the tee-wrapped view
+    // below: signals go to the actual child, while the wrapper exists only to
+    // duplicate its output.
+    const terminationController = createProcessTerminationController(proc, deps, jobOptions.termGraceMs);
+    // Registration may terminate the worker SYNCHRONOUSLY when shutdown was already
+    // requested — the sticky case, where the signal arrived while this job was still
+    // preparing its worktree. That is intended: the child is signalled here, and
+    // supervision below still runs normally to observe its exit and report it.
+    lifecycle.deregisterLiveWorker = control?.liveWorkers.register(terminationController);
     // Tee stdout/stderr to the worker log WITHOUT changing what the runner sees.
     const supervisedProc = tee
         ? {
@@ -1419,6 +1537,10 @@ async function runPreparedSpawn(params) {
         collectTelemetry,
         collectRemoteMarker,
         mcpSurface,
+        // The SAME controller the registry holds, so an executor shutdown, a timeout,
+        // and an MCP containment refusal all converge on one `SIGTERM` and one grace
+        // timer for this child (BAPI-828).
+        terminationController,
     });
     // --- Adapter lifecycle (EXPLICIT, BAPI-781) ---------------------------
     // Consumed rather than assumed. Claude declares `{ kind: "none" }` and so
@@ -1458,7 +1580,7 @@ async function runPreparedSpawn(params) {
     // `killed`) would be actively wrong. Ownership is marked abandoned only AFTER
     // the terminal mutation is attempted, so the report goes out under a live claim.
     if (procResult.serverStopRequested) {
-        await closeWorkerLogTee(tee);
+        await closeWorkerLog();
         await finalizeRegistry();
         await httpClient.fail(job, {
             error_kind: "ServerStopRequested",
@@ -1472,7 +1594,7 @@ async function runPreparedSpawn(params) {
         return { status: "abandoned", reason: "server_stop" };
     }
     // Finalize the log tee WITHOUT signaling the worker (it has already exited).
-    await closeWorkerLogTee(tee);
+    await closeWorkerLog();
     // --- Worker-log session invariant (ADVISORY, BAPI-793) ----------------
     // "`.conductor/worker.log` for any completed job contains exactly one
     // `session_id`" — the cheap, durable invariant from the ticket that would have

package/build/executor/live-worker-registry.js

@@ -0,0 +1,83 @@
+/**
+ * Runner-scoped live worker registry (BAPI-828).
+ *
+ * WHAT THIS FIXES. Before this module the executor had no handle on its own
+ * children. `SIGTERM` to the executor killed the executor and left the Claude
+ * worker it had spawned running, still holding the worktree, still committing
+ * into it, with the worktree lock left behind by a process that no longer
+ * existed. The operator runbook's answer was to run `pkill -TERM -P <executor
+ * pid>` BEFORE stopping the executor — a manual step that is exactly as
+ * reliable as remembering it.
+ *
+ * SCOPE IS PER `runExecutor` INVOCATION, NOT MODULE-GLOBAL. A module-level set
+ * would outlive the invocation that filled it, so a second `runExecutor` call in
+ * the same process (the `--once` path, an embedded runner, a test) would inherit
+ * another run's children and could terminate them. The registry is created by
+ * `runExecutor` and travels to each dispatched job through
+ * {@link ExecutorRunControl}; when the invocation returns, the registry is
+ * garbage, which is the correct lifetime.
+ *
+ * SHUTDOWN IS STICKY, AND THAT IS THE POINT. A signal can arrive while a claimed
+ * job is still preparing its worktree — seconds before it spawns anything. A
+ * plain "terminate everyone registered right now" would miss that worker
+ * entirely and leave precisely the orphan this module exists to prevent. So the
+ * shutdown flag persists: a controller registered AFTER shutdown was requested
+ * is terminated immediately, on registration.
+ *
+ * TERMINATION IS REQUESTED EXACTLY ONCE PER CONTROLLER. The controllers
+ * themselves are idempotent, but the registry does not lean on that — it tracks
+ * what it has already asked for, so repeated or mixed `SIGTERM`/`SIGINT` cannot
+ * produce a second request even against a controller implementation that would
+ * have honored one.
+ *
+ * SECRET-FREE. The registry holds termination controllers and nothing else — no
+ * job payload, no claim token, no argv, no environment.
+ */
+/** Create an empty, runner-scoped live worker registry. */
+export function createLiveWorkerRegistry() {
+    const live = new Set();
+    const alreadyRequested = new Set();
+    let shutdownRequested = false;
+    const terminateOnce = (controller) => {
+        if (alreadyRequested.has(controller))
+            return;
+        alreadyRequested.add(controller);
+        try {
+            controller.requestTermination();
+        }
+        catch {
+            // Fail-open, and deliberately silent. A controller that throws is a defect
+            // in one worker's teardown; letting it escape would abort the shutdown
+            // drain and strand every OTHER live worker — turning one bad teardown into
+            // the exact orphan situation this registry prevents.
+        }
+    };
+    return {
+        register(controller) {
+            live.add(controller);
+            if (shutdownRequested)
+                terminateOnce(controller);
+            return () => {
+                live.delete(controller);
+            };
+        },
+        deregister(controller) {
+            live.delete(controller);
+        },
+        requestShutdown() {
+            shutdownRequested = true;
+            // Snapshot before iterating: `terminateOnce` cannot mutate `live`, but a
+            // controller's own termination path may synchronously reach code that
+            // deregisters, and mutating a Set mid-iteration is not a behavior to rely
+            // on.
+            for (const controller of [...live])
+                terminateOnce(controller);
+        },
+        isShutdownRequested() {
+            return shutdownRequested;
+        },
+        size() {
+            return live.size;
+        },
+    };
+}

package/build/executor/observation.js

@@ -166,9 +166,93 @@ 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);
+}
+/**
+ * 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;
+    return { rate_limit_type: rateLimitType, status, utilization };
+}
+/**
+ * Render the operator-facing rate-limit line.
+ *
+ * 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.
+ */
+export function formatWorkerRateLimitAdvisory(advisory) {
+    const percent = Math.round(advisory.utilization * 100);
+    return (`executor: worker reports ${advisory.rate_limit_type} rate limit at ` +
+        `${percent}% (${advisory.status})`);
+}
+/**
+ * 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 +263,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 +447,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 +465,75 @@ export function createObservationState(deps, options) {
     let exitCode;
     let attemptStartSha;
     let attemptEndSha;
+    /** BAPI-828: the FIRST qualifying advisory wins; later ones never overwrite it. */
+    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 && rateLimit === undefined) {
+            rateLimit = parsed.rate_limit;
+            try {
+                options.onWorkerRateLimitAdvisory?.(rateLimit);
+            }
+            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 +560,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