@bridge_gpt/mcp-server 0.2.39 → 0.2.42

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;

package/build/executor/runner.js

@@ -8,7 +8,40 @@
  */
 import { collectExecutorPreflight, buildClaimManifest, createDenyProbeCache, } from "./preflight.js";
 import { runClaimedJob } from "./job-runner.js";
+import { appendToActiveJobLogs } from "./job-log-registry.js";
+import { createLiveWorkerRegistry } from "./live-worker-registry.js";
 import { sweepExecutorWorktrees } from "./worktree-gc.js";
+/**
+ * Signals that request a graceful executor shutdown (BAPI-828).
+ *
+ * Both, not just `SIGTERM`: an operator stopping a foreground executor types
+ * Ctrl-C, so a `SIGINT` that orphaned the worker would be the common case rather
+ * than the rare one. `SIGKILL` is deliberately absent — it cannot be trapped, and
+ * the worktree lock's stale-owner recovery is what covers it.
+ */
+export const EXECUTOR_SHUTDOWN_SIGNALS = ["SIGTERM", "SIGINT"];
+/**
+ * Extra wall-clock slack, beyond three poll intervals, before a COMPLETED poll
+ * sleep is called a host suspend (BAPI-828).
+ *
+ * The threshold is `3 * pollIntervalMs + SUSPEND_GAP_SLACK_MS`, so it scales with
+ * however the operator configured polling instead of pinning a constant that a
+ * long interval would trivially exceed and a short one would never reach. Three
+ * intervals plus a full minute is far outside anything ordinary scheduling jitter
+ * or a slow GC sweep produces, which keeps the diagnostic rare enough to mean
+ * something when it does appear.
+ */
+export const SUSPEND_GAP_SLACK_MS = 60_000;
+/**
+ * Render the fixed suspend-gap diagnostic.
+ *
+ * Exported so the stderr line and the worker-log annotation are the same string
+ * by construction — an operator correlating one against the other is the whole
+ * reason both exist.
+ */
+export function formatSuspendGapDiagnostic(elapsedMs) {
+    return `executor: host appears to have been suspended for ~${Math.round(elapsedMs / 1000)} s (poll gap)`;
+}
 /**
  * Run the executor loop. Returns 0 on the `once` path (a single cycle drained);
  * in continuous mode it does not return (the process is long-lived).
@@ -50,6 +83,92 @@ export async function runExecutor(options, deps, httpClient, seams = {}) {
         denyProbeCache: createDenyProbeCache(),
         ...(seams.preflightSeams ?? {}),
     };
+    // --- Graceful shutdown state (BAPI-828) -------------------------------
+    // ONE registry per invocation — see `live-worker-registry.ts` for why this is
+    // not module-global. Every dispatched job receives it, so a worker spawned by
+    // any of them is reachable from the signal handlers installed below.
+    const liveWorkers = createLiveWorkerRegistry();
+    const control = { liveWorkers };
+    let shutdownRequested = false;
+    /**
+     * Wake functions for whichever poll sleep is currently in flight. A list whose
+     * entries are REMOVED when their sleep completes normally, rather than one
+     * long-lived promise every cycle races against: the latter would accumulate one
+     * pending reaction per poll for the entire life of a long-running executor.
+     */
+    const shutdownWaiters = [];
+    /**
+     * Handle the first shutdown signal. Idempotent across repeated and mixed
+     * `SIGTERM`/`SIGINT`: a second signal must not send a second `SIGTERM` to a
+     * worker, install a second grace timer, or start a second drain.
+     *
+     * Deliberately does NOT call `process.exit` and does NOT signal any child
+     * directly. The loop below is allowed to unwind normally so worker supervision,
+     * worker-log closure, and the ownership-checked worktree-lock release all still
+     * run — exiting here is precisely what would leave the lock behind.
+     */
+    const beginShutdown = () => {
+        if (shutdownRequested)
+            return;
+        shutdownRequested = true;
+        deps.errorLog("executor: shutdown signal received; terminating live workers and draining");
+        liveWorkers.requestShutdown();
+        for (const wake of shutdownWaiters.splice(0, shutdownWaiters.length))
+            wake();
+    };
+    /**
+     * Sleep one poll interval, or return early once shutdown is requested.
+     *
+     * The return value is load-bearing: only a `"slept"` result may feed the
+     * suspend-gap calculation. A shutdown wake is an INTERRUPTED wait whose elapsed
+     * time says nothing about the host, and reporting one as a suspend would
+     * manufacture a diagnostic out of an ordinary Ctrl-C.
+     */
+    const sleepUntilPollOrShutdown = async (ms) => {
+        if (shutdownRequested)
+            return "shutdown";
+        let wake;
+        const interrupted = new Promise((resolve) => {
+            wake = resolve;
+        });
+        shutdownWaiters.push(wake);
+        try {
+            return await Promise.race([
+                deps.sleep(ms).then(() => "slept"),
+                interrupted.then(() => "shutdown"),
+            ]);
+        }
+        finally {
+            const index = shutdownWaiters.indexOf(wake);
+            if (index !== -1)
+                shutdownWaiters.splice(index, 1);
+        }
+    };
+    /**
+     * Annotate an abnormally long COMPLETED poll gap (BAPI-828).
+     *
+     * ADVISORY BY CONSTRUCTION: it logs and appends, and touches nothing else.
+     * Preflight, claim eligibility, heartbeat cadence, leases, active jobs, retries,
+     * and worktree handling are all deliberately left alone — the host having slept
+     * is a fact for the operator reading the log, never an input to scheduling. The
+     * whole point is that an executor whose MacBook idled to sleep mid-run left
+     * nothing in its logs saying so, and the freeze was misdiagnosed for hours.
+     */
+    const reportSuspendGap = async (elapsedMs) => {
+        if (elapsedMs <= 3 * options.pollIntervalMs + SUSPEND_GAP_SLACK_MS)
+            return;
+        const diagnostic = formatSuspendGapDiagnostic(elapsedMs);
+        deps.errorLog(diagnostic);
+        const appendFile = deps.appendFile;
+        if (!appendFile)
+            return;
+        try {
+            await appendToActiveJobLogs(diagnostic, { appendFile });
+        }
+        catch {
+            /* annotation is never allowed to disturb the poll loop */
+        }
+    };
     /**
      * Run the conservative worktree GC sweep ONLY while the runner owns no active
      * job worktree. Failures are logged to stderr and never abort claiming
@@ -69,7 +188,12 @@ export async function runExecutor(options, deps, httpClient, seams = {}) {
     function dispatch(job, report) {
         const promise = (async () => {
             try {
-                await runJob(job, httpClient, options, deps, report);
+                // `undefined` for the behavior seams (the job runner defaults them), then
+                // the runner-scoped control object carrying the live-worker registry. A
+                // job dispatched after shutdown was requested still runs through here so
+                // its worktree lock unwinds through the normal `finally`; the registry's
+                // sticky flag terminates whatever it manages to spawn.
+                await runJob(job, httpClient, options, deps, report, undefined, control);
             }
             catch (err) {
                 const message = err instanceof Error ? err.message : String(err);
@@ -81,58 +205,121 @@ export async function runExecutor(options, deps, httpClient, seams = {}) {
         })();
         active.set(job.id, promise);
     }
-    for (;;) {
-        const report = await collectPreflight(options, deps, preflightSeams);
-        // BAPI-727: preflight warnings were previously collected but never emitted, so
-        // a non-fatal finding — an overridden MCP-shadowing collision, an unreadable
-        // ~/.claude.json — was invisible to the operator. Emit them before the claim
-        // decision; this only logs and never changes the existing `!report.ok`
-        // claim-skipping behavior below.
-        for (const warning of report.warnings) {
-            deps.errorLog(`executor preflight warning: ${warning}`);
-        }
-        if (!report.ok) {
-            deps.errorLog(`executor preflight refused claiming: ${report.fatalFindings.join("; ")}`);
+    // Handlers go on BEFORE preflight and before the first claim (BAPI-828).
+    // Preflight can take seconds and the first claim can spawn a worker immediately
+    // after it, so registering any later would leave a real window in which a
+    // `SIGTERM` reached the executor and nothing owned the child it had just made.
+    const unsubscribers = [];
+    const onSignal = seams.onSignal;
+    if (onSignal) {
+        for (const signal of EXECUTOR_SHUTDOWN_SIGNALS) {
+            try {
+                unsubscribers.push(onSignal(signal, beginShutdown));
+            }
+            catch {
+                // A host that refuses a handler for one signal must not stop the executor
+                // from running, or from handling the other signal.
+            }
         }
-        else {
-            let claiming = true;
-            while (claiming && options.maxConcurrent - active.size > 0) {
-                const freeSlots = options.maxConcurrent - active.size;
-                const manifest = buildClaimManifest(report, options, freeSlots);
-                const result = await httpClient.claim(manifest);
-                if (result.kind === "claimed") {
-                    const currentEpicRunId = result.job.epic_run_id ?? null;
-                    if (lastClaimedEpicRunId !== null &&
-                        currentEpicRunId !== null &&
-                        currentEpicRunId !== lastClaimedEpicRunId) {
-                        deps.errorLog(`executor claimed a job for a different epic run than the previous claim ` +
-                            `(repo=${result.job.repo_name} previous_epic_run_id=${lastClaimedEpicRunId} ` +
-                            `current_epic_run_id=${currentEpicRunId} scoped=${options.epicRunIds !== undefined})`);
+    }
+    try {
+        for (;;) {
+            const report = await collectPreflight(options, deps, preflightSeams);
+            // BAPI-727: preflight warnings were previously collected but never emitted, so
+            // a non-fatal finding — an overridden MCP-shadowing collision, an unreadable
+            // ~/.claude.json — was invisible to the operator. Emit them before the claim
+            // decision; this only logs and never changes the existing `!report.ok`
+            // claim-skipping behavior below.
+            for (const warning of report.warnings) {
+                deps.errorLog(`executor preflight warning: ${warning}`);
+            }
+            if (!report.ok) {
+                deps.errorLog(`executor preflight refused claiming: ${report.fatalFindings.join("; ")}`);
+            }
+            else if (shutdownRequested) {
+                // Shutdown arrived during preflight. Claiming now would take on work this
+                // executor is about to stop doing, and the server would have to wait out
+                // the whole lease before anyone else could have it.
+                deps.errorLog("executor: shutdown requested; not claiming new work");
+            }
+            else {
+                let claiming = true;
+                while (claiming && !shutdownRequested && options.maxConcurrent - active.size > 0) {
+                    const freeSlots = options.maxConcurrent - active.size;
+                    const manifest = buildClaimManifest(report, options, freeSlots);
+                    const result = await httpClient.claim(manifest);
+                    if (result.kind === "claimed") {
+                        const currentEpicRunId = result.job.epic_run_id ?? null;
+                        if (lastClaimedEpicRunId !== null &&
+                            currentEpicRunId !== null &&
+                            currentEpicRunId !== lastClaimedEpicRunId) {
+                            deps.errorLog(`executor claimed a job for a different epic run than the previous claim ` +
+                                `(repo=${result.job.repo_name} previous_epic_run_id=${lastClaimedEpicRunId} ` +
+                                `current_epic_run_id=${currentEpicRunId} scoped=${options.epicRunIds !== undefined})`);
+                        }
+                        if (currentEpicRunId !== null)
+                            lastClaimedEpicRunId = currentEpicRunId;
+                        // Dispatched even when the signal landed while this claim was in
+                        // flight (BAPI-828). The job is OURS the moment the server answered,
+                        // so dropping it here would strand a claimed row under a live lease
+                        // and skip the worktree-lock unwind. The registry's sticky shutdown
+                        // terminates whatever it spawns, immediately, on registration.
+                        dispatch(result.job, report);
+                    }
+                    else if (result.kind === "none") {
+                        claiming = false;
+                    }
+                    else {
+                        deps.errorLog(`executor claim ${result.kind}: ${result.error}`);
+                        claiming = false;
                     }
-                    if (currentEpicRunId !== null)
-                        lastClaimedEpicRunId = currentEpicRunId;
-                    dispatch(result.job, report);
-                }
-                else if (result.kind === "none") {
-                    claiming = false;
-                }
-                else {
-                    deps.errorLog(`executor claim ${result.kind}: ${result.error}`);
-                    claiming = false;
                 }
+                // Conservative worktree GC runs once per cycle, AFTER the claim attempt and
+                // only while idle (`active.size === 0` — no owned job worktree). This covers
+                // both the startup cycle and between-poll-cycle cadence without ever
+                // sweeping while a job is running. Kept off the pre-claim path so it never
+                // delays claiming a ready job.
+                await maybeSweepWorktrees();
+            }
+            if (options.once || shutdownRequested)
+                break;
+            // Sample the clock immediately around the ACTUAL sleep, so the measured gap
+            // is the wait itself and not the claim/GC work on either side of it.
+            const sleepStartedAt = deps.now();
+            const wake = await sleepUntilPollOrShutdown(options.pollIntervalMs);
+            if (wake === "shutdown")
+                break;
+            await reportSuspendGap(deps.now() - sleepStartedAt);
+        }
+        // Drain every dispatched job — on the `once` path and the shutdown path alike.
+        // Terminated workers still have to finish supervision, flush final telemetry,
+        // close their worker logs, deregister, and release their worktree locks;
+        // returning ahead of that is exactly what would leave a lock owned by a
+        // process that has already exited.
+        //
+        // INSIDE the try, so the handlers are still installed while it runs: a second
+        // `SIGTERM` arriving mid-drain must reach `beginShutdown` (an idempotent no-op
+        // by then) rather than Node's default terminate action, which would kill the
+        // executor in the middle of releasing its locks.
+        await Promise.all(active.values());
+    }
+    finally {
+        // Unsubscribe in a runner-level `finally`, so a direct or repeated
+        // `runExecutor` call — an embedded runner, a `--once` invocation in a loop, a
+        // test suite — cannot leave stale listeners bound to a registry that has since
+        // gone out of scope.
+        for (const unsubscribe of unsubscribers) {
+            try {
+                unsubscribe();
+            }
+            catch {
+                /* a failed unsubscribe must not mask the runner's own outcome */
             }
-            // Conservative worktree GC runs once per cycle, AFTER the claim attempt and
-            // only while idle (`active.size === 0` — no owned job worktree). This covers
-            // both the startup cycle and between-poll-cycle cadence without ever
-            // sweeping while a job is running. Kept off the pre-claim path so it never
-            // delays claiming a ready job.
-            await maybeSweepWorktrees();
         }
-        if (options.once)
-            break;
-        await deps.sleep(options.pollIntervalMs);
     }
-    // `once`: ensure every dispatched job promise settles before returning.
-    await Promise.all(active.values());
+    // A graceful signal shutdown is a NORMAL executor exit, not an error: the run did
+    // exactly what it was asked to do. A distinct nonzero code here would make every
+    // deliberate operator stop look like a crash to launchd, systemd, and the CLI
+    // boundary alike.
     return 0;
 }

package/build/executor/test-clock.js

@@ -9,6 +9,7 @@
 import { resolveAgentSpec } from "../agent-registry.js";
 import { createClaudeExecutorAdapter } from "../agent-launchers/claude-executor-adapter.js";
 import { validateExecutorAdapterCapabilities } from "../agent-launchers/executor-adapter.js";
+import { MCP_SERVER_NAME } from "../mcp-identity.js";
 export class VirtualClock {
     t = 0;
     timers = [];
@@ -70,7 +71,7 @@ async function flushMicrotasks() {
 export const DEFAULT_WORKER_INIT_EVENT_LINE = `${JSON.stringify({
     type: "system",
     subtype: "init",
-    mcp_servers: [{ name: "bridge-api", status: "connected" }],
+    mcp_servers: [{ name: MCP_SERVER_NAME, status: "connected" }],
 })}\n`;
 /** A single-chunk stdout stream carrying {@link DEFAULT_WORKER_INIT_EVENT_LINE}. */
 async function* defaultWorkerStdout() {
@@ -136,7 +137,7 @@ export function makeFakeExecutorDeps(clock, overrides = {}) {
             // registration must therefore override this read explicitly — it will not
             // get that state by accident, which is the point.
             if (typeof filePath === "string" && filePath.endsWith(".mcp.json")) {
-                return JSON.stringify({ mcpServers: { "bridge-api": { command: "node", args: [] } } });
+                return JSON.stringify({ mcpServers: { [MCP_SERVER_NAME]: { command: "node", args: [] } } });
             }
             // Mirror real fs/promises: a missing-file rejection carries code "ENOENT"
             // (so BAPI-664 command provisioning treats absent files as fillable).