@bridge_gpt/mcp-server 0.2.41 → 0.2.43

package/build/executor/job-log-registry.js

@@ -82,6 +82,75 @@ export async function markExecutorJobLogFinished(jobId, finishedAt, deps) {
     const filePath = jobLogRecordPath(stateDir, jobId, deps.platform ?? process.platform);
     await deps.writeFile(filePath, JSON.stringify(normalizeRecord(updated), null, 2));
 }
+// ---------------------------------------------------------------------------
+// Active worker logs (BAPI-828)
+// ---------------------------------------------------------------------------
+/**
+ * In-memory map of job id → worker-log path for jobs whose tee is currently open.
+ *
+ * DELIBERATELY SEPARATE FROM THE PERSISTED RECORD ABOVE, and deliberately not
+ * derived from it. The persisted record is a visibility nicety for a SEPARATE
+ * `executor watch` process, it is written with best-effort error swallowing, and
+ * it keeps its row after `finished_at` is stamped. This map answers a different
+ * question — "which worker logs can be appended to right now, in THIS process" —
+ * and the suspend diagnostic depends on that answer being correct. Deriving it
+ * from the persisted record would mean a failed registry write silently disables
+ * suspend annotation for a worker whose tee is perfectly healthy.
+ *
+ * Process-scoped module state rather than runner-scoped, unlike the live worker
+ * registry: entries are keyed by server-minted job id, so two concurrent
+ * `runExecutor` invocations in one process cannot collide, and each value is a
+ * path only its own job ever deactivates.
+ *
+ * SECRET-FREE: a filesystem path inside the job's own worktree, nothing else.
+ */
+const activeJobLogPaths = new Map();
+/**
+ * Mark a job's worker log as open and appendable.
+ *
+ * Called once the tee EXISTS, before any registry persistence — see the map's
+ * docstring for why the two are not chained. Re-activating the same job id simply
+ * overwrites the path.
+ */
+export function activateJobLog(jobId, logPath) {
+    if (typeof logPath !== "string" || logPath.length === 0)
+        return;
+    activeJobLogPaths.set(jobId, logPath);
+}
+/** Stop appending to a job's worker log. Idempotent. */
+export function deactivateJobLog(jobId) {
+    activeJobLogPaths.delete(jobId);
+}
+/** The distinct currently-appendable log paths (a snapshot, safe to iterate). */
+export function activeJobLogPathsSnapshot() {
+    return [...new Set(activeJobLogPaths.values())];
+}
+/**
+ * Append one diagnostic line to every currently active worker log.
+ *
+ * FAIL-OPEN PER PATH. Each append is contained independently, so one missing,
+ * deleted, or unwritable log cannot suppress the diagnostic for the others and
+ * cannot propagate an error into the executor's poll loop — this is annotation,
+ * never correctness.
+ *
+ * Paths are DEDUPLICATED (two jobs can legitimately name the same log during a
+ * re-entry window) and exactly one trailing newline is written, whether or not
+ * the caller supplied one.
+ */
+export async function appendToActiveJobLogs(line, deps) {
+    const paths = activeJobLogPathsSnapshot();
+    if (paths.length === 0)
+        return;
+    const payload = `${line.replace(/\n+$/, "")}\n`;
+    await Promise.all(paths.map(async (logPath) => {
+        try {
+            await deps.appendFile(logPath, payload);
+        }
+        catch {
+            /* one unwritable log never blocks the others, or the executor */
+        }
+    }));
+}
 /**
  * Load and validate a record for `executor watch <job>`. Returns a structured
  * missing/invalid result rather than throwing raw filesystem/JSON errors.

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, {
@@ -787,6 +817,35 @@ async function runSmokeJob(job, httpClient, options, deps, ownership, observatio
     });
     return terminalToRunResult(terminal, "completed");
 }
+/**
+ * BAPI-862: the payload key the reconciler stamps with the implement gate's last
+ * observation reason code. Server-minted and opaque to the executor beyond the
+ * closed set below — the executor never derives, defaults, or infers it.
+ */
+const IMPLEMENT_LAST_OBSERVATION_KEY = "implement_last_observation_reason";
+/**
+ * The one observation reason code that changes the stale-branch guard's advice.
+ * Matches `PR_ATTACH_PENDING_REASON_CODE` in the reconciler; the two strings are
+ * one vocabulary on purpose, so an operator greps a single term across the job
+ * row, the gate observation, and the executor refusal.
+ */
+const PR_NOT_ATTACHED_REASON_CODE = "pr_not_attached";
+/**
+ * Map the job payload's reconciliation observation onto the guard's narrow
+ * classification. Anything absent, malformed, or unrecognized degrades to
+ * `"unknown"` — the pre-BAPI-862 delete/rebase guidance. That direction is
+ * deliberate: the softened message asserts the branch holds finished work, and
+ * asserting that on a guess would talk an operator OUT of cleaning up a genuinely
+ * stale branch.
+ */
+function resolveStaleBranchClassification(payload) {
+    if (!payload || typeof payload !== "object")
+        return "unknown";
+    const raw = payload[IMPLEMENT_LAST_OBSERVATION_KEY];
+    if (typeof raw !== "string")
+        return "unknown";
+    return raw.trim() === PR_NOT_ATTACHED_REASON_CODE ? "succeeded_pr_not_attached" : "unknown";
+}
 async function prepareSpawn(job, httpClient, options, deps, seams) {
     if (job.job_type === "resume") {
         const prepareResume = seams.prepareResumeSpawn ?? prepareResumeSpawn;
@@ -853,7 +912,14 @@ async function prepareSpawn(job, httpClient, options, deps, seams) {
     // `spec_review` stay fresh-off-base with the guard ON. `resume` never reaches
     // here — it has its own preservation protocol above.
     const reuseExistingBranch = isRecoveryJobType(job.job_type);
-    const wt = await ensureWorktree(job, options, deps, { reuseExistingBranch });
+    const wt = await ensureWorktree(job, options, deps, {
+        reuseExistingBranch,
+        // BAPI-862: hand the guard the reconciler's own reading of why this branch
+        // may already carry commits. Read from the SERVER-minted payload field and
+        // validated against a closed set — never inferred locally, and never taken
+        // from worker output (R14 rules 3 and 4).
+        staleBranchClassification: resolveStaleBranchClassification(job.payload),
+    });
     if (!wt.ok) {
         await httpClient.fail(job, {
             error_kind: "WorktreeError",
@@ -915,7 +981,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 +1037,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 +1115,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 +1167,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 +1206,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 +1353,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 +1442,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 +1469,7 @@ async function runPreparedSpawn(params) {
             posture: permissionPosture,
             mcpConfigPath: mcpContract.configPath,
             effectiveBaseBranch,
+            indexScope,
             parentEnv: deps.env,
         });
         assertUsableSpawnShape(spawnShape, adapter);
@@ -1342,7 +1480,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 +1498,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 +1516,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 +1532,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 +1573,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 +1616,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 +1630,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
@@ -1621,7 +1779,7 @@ async function runPreparedSpawn(params) {
         // the verdict-artifact path above stays limited to verdict jobs like
         // `spec_review`. Recovery jobs complete through this same generic envelope.
         const artifacts = await readCompletionArtifacts(worktreePath, deps);
-        const result = buildGenericSuccessResult({
+        const genericResult = buildGenericSuccessResult({
             summary: `${job.job_type} ${job.ticket_key ?? ""} completed`.trim(),
             branch,
             headSha: git.last_commit_sha,
@@ -1635,7 +1793,7 @@ async function runPreparedSpawn(params) {
             job,
             branch,
             worktreePath,
-            result,
+            result: genericResult,
             runCommand: deps.runCommand,
             headSha: git.last_commit_sha,
             expectedBaseBranch: effectiveBaseBranch,
@@ -1656,6 +1814,17 @@ async function runPreparedSpawn(params) {
             });
             return terminalToRunResult(terminal, "failed");
         }
+        // BAPI-862: attach the pull request the EXECUTOR verified. `pr_url` was never
+        // populated on this path before — `buildGenericSuccessResult` has no PR field
+        // at all — which is why job 1397's stored `result.pr_url` was null even though
+        // the reconciler's whole implement gate is waiting on that identity. The value
+        // comes strictly from the authoritative `gh` observation finalization just
+        // made; worker prose is never admissible here (R14 rule 3). It is omitted
+        // rather than set to null when finalization had no PR to verify (a
+        // non-implementation job), so the field's presence always means "verified".
+        const result = typeof finalization.prUrl === "string"
+            ? { ...genericResult, pr_url: finalization.prUrl }
+            : genericResult;
         const completion = {
             job_type: job.job_type,
             exit_code: procResult.exitCode ?? 0,

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;
+        },
+    };
+}