@bridge_gpt/mcp-server 0.2.67 → 0.2.68

package/build/executor/required-work-ledger.js

@@ -875,7 +875,33 @@ export function createRequiredWorkLedger(init) {
             if (!liveOptional.includes(tid))
                 liveOptional.push(tid);
         const readyToClose = resultsSeen > 0 && latestIsResult && !turnOpen && liveRequired.length === 0 && snap.required.length === 0;
-        return { readyToClose, liveRequired, liveOptional, activitySeq, latestIsResult };
+        const bashBgIds = [];
+        let onlyBashBg = true;
+        for (const o of obligations.values()) {
+            if (!isLive(o) || !o.required)
+                continue;
+            if (o.kind === "bash_bg")
+                bashBgIds.push(o.taskId ?? o.toolUseId);
+            else
+                onlyBashBg = false;
+        }
+        for (const tid of snap.required) {
+            const o = findByTaskId(tid);
+            if (!o || o.kind !== "bash_bg")
+                onlyBashBg = false;
+            else if (!bashBgIds.includes(o.taskId ?? o.toolUseId))
+                bashBgIds.push(o.taskId ?? o.toolUseId);
+        }
+        return {
+            readyToClose,
+            liveRequired,
+            liveOptional,
+            activitySeq,
+            latestIsResult,
+            turnOpen,
+            finalResultNoOpenTurn: resultsSeen > 0 && latestIsResult && !turnOpen,
+            liveRequiredBashBg: onlyBashBg ? bashBgIds : [],
+        };
     };
     // One predicate for "a required task is still pending", shared by the envelope
     // and the observe-only query so the two cannot drift apart.
@@ -1003,6 +1029,13 @@ export function createRequiredWorkLedger(init) {
 }
 /** The measured settle window after the closure rule first holds (BAPI-1292 C6an-hold2). */
 export const CLOSURE_DEBOUNCE_MS = 1500;
+/**
+ * The absolute post-result window (BAPI-1395). Once a final result is in, no
+ * turn is open, and the only live required work is the worker's own background
+ * Bash, stdin is closed at most this long after the window opens — whatever the
+ * worker does meanwhile. Normal early closure is unchanged.
+ */
+export const COMPLETION_WINDOW_MS = 30 * 60 * 1000;
 /**
  * Hold stdin open until the closure rule holds for a full debounce window, then
  * close it exactly once.
@@ -1017,6 +1050,13 @@ export const CLOSURE_DEBOUNCE_MS = 1500;
  * optional watchers are live. It is never sent while required work is live and
  * never asks for a broad stop — cancelling required work is not the executor's
  * call.
+ *
+ * The completion window (BAPI-1395): when the final result is in and only
+ * required `bash_bg` work is live, one fixed end `min(opened + window, deadline)`
+ * is set. A new worker turn cancels it; background activity does not. The one
+ * nudge (shared with the optional-watcher nudge, so a job gets at most one)
+ * asks the worker to stop only its own tasks that are merely waiting. Closing
+ * at the end resolves nothing: the live tasks stay unresolved in the ledger.
  */
 export function createClosureSupervisor(opts) {
     const { ledger, deps } = opts;
@@ -1029,6 +1069,14 @@ export function createClosureSupervisor(opts) {
     let debounceTimer = null;
     let armedSeq = -1;
     let pending = Promise.resolve();
+    const windowMs = opts.windowMs ?? COMPLETION_WINDOW_MS;
+    let windowOpened = false;
+    let windowTimer = null;
+    const clearWindow = () => {
+        if (windowTimer !== null)
+            deps.clearTimer(windowTimer);
+        windowTimer = null;
+    };
     const clearDebounce = () => {
         if (debounceTimer !== null)
             deps.clearTimer(debounceTimer);
@@ -1041,6 +1089,7 @@ export function createClosureSupervisor(opts) {
         closed = true;
         closedReason = reason;
         clearDebounce();
+        clearWindow();
         if (deadlineTimer !== null)
             deps.clearTimer(deadlineTimer);
         deadlineTimer = null;
@@ -1054,6 +1103,48 @@ export function createClosureSupervisor(opts) {
                 // then reports `stdout_not_read_to_eof`, never success.
             }
         });
+        if (reason === "window") {
+            try {
+                opts.onWindowExpiry?.();
+            }
+            catch {
+                /* the caller's termination scheduling must never break closure */
+            }
+        }
+    };
+    const sendNudge = (line, onUndelivered) => {
+        nudged = true;
+        nudgeAwaitingReply = true;
+        pending = pending.then(async () => {
+            let ok = false;
+            try {
+                ok = (await opts.writeMessage(line)).ok;
+            }
+            catch {
+                ok = false;
+            }
+            if (!ok && !closed && !disposed)
+                onUndelivered();
+        });
+    };
+    const openWindow = (bashBgIds) => {
+        windowOpened = true;
+        const now = deps.now();
+        const windowEnd = Math.min(now + windowMs, opts.deadlineAtMs);
+        // The deadline timer already closes at `deadlineAtMs`; a second timer there
+        // would only race it, so the window schedules its own close only when it
+        // ends strictly earlier.
+        if (windowEnd < opts.deadlineAtMs) {
+            windowTimer = deps.setTimer(() => {
+                windowTimer = null;
+                close("window");
+            }, Math.max(0, windowEnd - now));
+        }
+        if (!nudged && opts.buildWindowNudge) {
+            sendNudge(opts.buildWindowNudge([...bashBgIds]), () => {
+                nudgeAwaitingReply = false;
+            });
+        }
     };
     let deadlineTimer = deps.setTimer(() => {
         deadlineTimer = null;
@@ -1065,30 +1156,26 @@ export function createClosureSupervisor(opts) {
         const s = ledger.closureState();
         if (armedSeq !== s.activitySeq)
             clearDebounce();
+        if (s.turnOpen && windowOpened) {
+            clearWindow();
+            windowOpened = false;
+        }
         if (!s.latestIsResult) {
             // The nudge was answered (or other activity began): the next result decides again.
             nudgeAwaitingReply = false;
             return;
         }
+        if (!windowOpened && s.finalResultNoOpenTurn && s.liveRequiredBashBg.length > 0) {
+            openWindow(s.liveRequiredBashBg);
+            return;
+        }
         if (!s.readyToClose)
             return;
         if (!nudged && s.liveOptional.length > 0) {
-            nudged = true;
-            nudgeAwaitingReply = true;
-            const line = opts.buildNudge([...s.liveOptional]);
-            pending = pending.then(async () => {
-                let ok = false;
-                try {
-                    ok = (await opts.writeMessage(line)).ok;
-                }
-                catch {
-                    ok = false;
-                }
-                // An undelivered nudge will never be answered: fall back to the rule.
-                if (!ok && !closed && !disposed) {
-                    nudgeAwaitingReply = false;
-                    onActivity();
-                }
+            // An undelivered nudge will never be answered: fall back to the rule.
+            sendNudge(opts.buildNudge([...s.liveOptional]), () => {
+                nudgeAwaitingReply = false;
+                onActivity();
             });
             return;
         }
@@ -1117,6 +1204,7 @@ export function createClosureSupervisor(opts) {
         settled: () => pending,
         dispose: () => {
             clearDebounce();
+            clearWindow();
             if (deadlineTimer !== null)
                 deps.clearTimer(deadlineTimer);
             deadlineTimer = null;

package/build/executor/retirement.js

@@ -0,0 +1,69 @@
+/** Process-local, pure retirement bookkeeping for a single-run executor. */
+export const SUSPEND_GAP_SLACK_MS = 60_000;
+export function initialRetirementState() {
+    return { unreachableMs: 0, idleMs: 0, definitiveReason: null, definitiveReads: 0, definitiveMs: 0, failedCallEvidence: false };
+}
+/** Bounds prevent accidental years-long values and unsafe number conversions. */
+export function parseRetirementSetting(raw, defaultValue, maximum) {
+    if (raw === undefined)
+        return { value: defaultValue, warning: false };
+    if (!/^(0|[1-9][0-9]*)$/.test(raw))
+        return { value: defaultValue, warning: true };
+    const value = Number(raw);
+    return Number.isSafeInteger(value) && value <= maximum
+        ? { value, warning: false }
+        : { value: defaultValue, warning: true };
+}
+export function transitionRetirement(prior, cycle, config) {
+    const state = { ...prior };
+    const elapsed = cycle.sleep.completed && cycle.sleep.elapsedMs >= 0 &&
+        cycle.sleep.elapsedMs <= 3 * config.pollIntervalMs + SUSPEND_GAP_SLACK_MS
+        ? cycle.sleep.elapsedMs : 0;
+    const success = cycle.successfulServerCall || cycle.claimedJob || cycle.claimedAction || cycle.scopedRead === "ok";
+    const failure = cycle.failedServerCall || ["network", "timeout", "server", "malformed", "unexpected"].includes(cycle.scopedRead);
+    if (success) {
+        state.unreachableMs = 0;
+        state.failedCallEvidence = false;
+    }
+    else if (failure) {
+        state.failedCallEvidence = true;
+    }
+    if (cycle.claimedJob || cycle.claimedAction || cycle.activeCount > 0)
+        state.idleMs = 0;
+    else if ((cycle.claimOutcome === "none" || cycle.claimOutcome === "preflight-refused") && elapsed > 0)
+        state.idleMs += elapsed;
+    if (cycle.activeCount === 0 && !success && state.failedCallEvidence)
+        state.unreachableMs += elapsed;
+    if (cycle.scopedRead === "not-found" || cycle.scopedRead === "unauthorized") {
+        if (state.definitiveReason === cycle.scopedRead) {
+            state.definitiveReads += 1;
+            state.definitiveMs += elapsed;
+        }
+        else {
+            state.definitiveReason = cycle.scopedRead;
+            state.definitiveReads = 1;
+            state.definitiveMs = 0;
+        }
+    }
+    else if (cycle.scopedRead === "ok" || cycle.scopedRead === "unavailable" || cycle.scopedRead === "network" || cycle.scopedRead === "timeout" || cycle.scopedRead === "server" || cycle.scopedRead === "malformed" || cycle.scopedRead === "unexpected") {
+        state.definitiveReason = null;
+        state.definitiveReads = 0;
+        state.definitiveMs = 0;
+    }
+    else if (state.definitiveReason !== null) {
+        state.definitiveMs += elapsed;
+    }
+    let decision = { kind: "continue" };
+    if (cycle.activeCount === 0) {
+        if (state.definitiveReason !== null && state.definitiveReads >= 3 && state.definitiveMs >= 5 * 60_000) {
+            decision = { kind: "retire", reason: state.definitiveReason === "not-found" ? "run_not_found" : "run_unauthorized", awakeMinutes: Math.floor(state.definitiveMs / 60_000) };
+        }
+        else if (config.unreachableMinutes > 0 && state.unreachableMs >= config.unreachableMinutes * 60_000) {
+            decision = { kind: "retire", reason: "server_unreachable", awakeMinutes: Math.floor(state.unreachableMs / 60_000) };
+        }
+        else if (config.idleHours > 0 && state.idleMs >= config.idleHours * 3_600_000) {
+            decision = { kind: "retire", reason: "idle", awakeMinutes: Math.floor(state.idleMs / 60_000) };
+        }
+    }
+    return { state, decision };
+}

package/build/executor/runner.js

@@ -18,6 +18,7 @@ import { INTEGRATION_ACTION_PROTOCOL_VERSION, } from "./types.js";
 import { buildIntegrationCorrectionJob, createIntegrationCorrectionLeaseAdapter, runIntegrationAction, } from "./integration-job.js";
 import { validateBranchName } from "../base-ref.js";
 import { isTerminalEpicRunStatus } from "../epic-run-status.js";
+import { initialRetirementState, parseRetirementSetting, transitionRetirement } from "./retirement.js";
 import { ensureEpicIntegrationPullRequest, createProductionEpicIntegrationGhRunner, formatEpicIntegrationPullRequestOutcome, EPIC_BRANCH_PREFIX, } from "../epic-integration-pr.js";
 /**
  * Signals that request a graceful executor shutdown (BAPI-828).
@@ -109,7 +110,10 @@ export function formatProcessHeartbeatRecoveredDiagnostic() {
  */
 export function formatRunTerminalReadFailureDiagnostic(reason) {
     return (`executor: could not read the scoped run's state (reason=${reason}); ` +
-        "staying up and claiming until it can be read.");
+        "continuing to poll during the bounded retirement window.");
+}
+export function formatExecutorRetirement(reason, awakeMinutes) {
+    return `executor: retiring (reason=${reason}, awake_minutes=${awakeMinutes}); restart with drive-epic <EPIC> or the printed manual command.`;
 }
 /** Seconds a correction worker may run: what the action deadline leaves, less a margin. */
 function correctionTimeoutSeconds(deadlineAt, nowMs) {
@@ -227,6 +231,20 @@ export async function runExecutor(options, deps, httpClient, seams = {}) {
     // Suppresses the missing-read-capability advisory to one line per
     // invocation, mirroring the dispatcher-liveness suppression above.
     let missingReadCapabilityWarned = false;
+    let cycleSuccessfulCall = false;
+    let cycleFailedCall = false;
+    let cycleClaimedJob = false;
+    let cycleClaimedAction = false;
+    let cycleClaimOutcome = "not-attempted";
+    let heartbeatDelivered = false;
+    let pendingSleep = { completed: false, elapsedMs: 0 };
+    const unreachableSetting = parseRetirementSetting(deps.env.BAPI_EXECUTOR_UNREACHABLE_RETIRE_MINUTES, 60, 10_080);
+    const idleSetting = parseRetirementSetting(deps.env.BAPI_EXECUTOR_IDLE_RETIRE_HOURS, 24, 8_760);
+    if (unreachableSetting.warning)
+        deps.errorLog("executor: invalid BAPI_EXECUTOR_UNREACHABLE_RETIRE_MINUTES; using 60");
+    if (idleSetting.warning)
+        deps.errorLog("executor: invalid BAPI_EXECUTOR_IDLE_RETIRE_HOURS; using 24");
+    let retirementState = initialRetirementState();
     /**
      * Announce a dispatcher availability CHANGE, and only a change.
      *
@@ -323,9 +341,16 @@ export async function runExecutor(options, deps, httpClient, seams = {}) {
         try {
             const result = await readState.call(httpClient, observedEpicRunId, options.repoName);
             if (!result.ok) {
-                deps.errorLog(`executor: epic run completion-state read failed (reason=${result.reason})`);
+                cycleFailedCall = true;
+                if (shouldReport(result.reason, lastCompletionReadFailure, lastCompletionReadFailureAt)) {
+                    deps.errorLog(`executor: epic run completion-state read failed (reason=${result.reason})`);
+                    lastCompletionReadFailureAt = deps.now();
+                }
+                lastCompletionReadFailure = result.reason;
                 return;
             }
+            cycleSuccessfulCall = true;
+            lastCompletionReadFailure = null;
             if (result.state.status !== "done")
                 return;
             const featureBranch = result.state.featureBranch;
@@ -369,6 +394,12 @@ export async function runExecutor(options, deps, httpClient, seams = {}) {
     // The last failure reason reported, so a long outage logs once per change
     // rather than once per poll.
     let lastRunStateFailure = null;
+    let lastRunStateFailureAt = -Infinity;
+    let lastPreflightRefusal = null;
+    let lastPreflightRefusalAt = -Infinity;
+    let lastCompletionReadFailure = null;
+    let lastCompletionReadFailureAt = -Infinity;
+    const shouldReport = (value, previous, at) => value !== previous || deps.now() - at >= 15 * 60_000;
     /**
      * Is the scoped run finished? Called only between claim cycles while this
      * process holds NO job. The wind-down observer runs FIRST, so a run that just
@@ -378,17 +409,19 @@ export async function runExecutor(options, deps, httpClient, seams = {}) {
      */
     const scopedRunIsTerminal = async () => {
         if (!exitWhenRunTerminal || observedEpicRunId === null)
-            return false;
+            return { terminal: false, read: "none" };
         await observeEpicRunCompletion();
         const readState = httpClient.readEpicRunState;
         if (typeof readState !== "function")
-            return false;
+            return { terminal: false, read: "unavailable" };
         let reason = null;
         let terminal = false;
         try {
             const result = await readState.call(httpClient, observedEpicRunId, options.repoName);
-            if (result.ok)
+            if (result.ok) {
+                cycleSuccessfulCall = true;
                 terminal = isTerminalEpicRunStatus(result.state.status);
+            }
             else
                 reason = result.reason;
         }
@@ -396,14 +429,17 @@ export async function runExecutor(options, deps, httpClient, seams = {}) {
             reason = "unexpected";
         }
         if (reason !== null) {
-            if (reason !== lastRunStateFailure) {
+            if (shouldReport(reason, lastRunStateFailure, lastRunStateFailureAt)) {
                 deps.errorLog(formatRunTerminalReadFailureDiagnostic(reason));
+                lastRunStateFailureAt = deps.now();
             }
             lastRunStateFailure = reason;
-            return false;
+            cycleFailedCall = true;
+            const read = reason === "not-found" || reason === "unauthorized" || reason === "network" || reason === "timeout" || reason === "server" || reason === "malformed" ? reason : "unexpected";
+            return { terminal: false, read };
         }
         lastRunStateFailure = null;
-        return terminal;
+        return { terminal, read: "ok" };
     };
     // BAPI-722: ONE deny-probe cache per `runExecutor` invocation, created OUTSIDE
     // the claim loop below — that scope is the whole feature. A cache created inside
@@ -623,6 +659,8 @@ export async function runExecutor(options, deps, httpClient, seams = {}) {
                 deps.errorLog(formatProcessHeartbeatRecoveredDiagnostic());
             }
             lastFailed = outcome === "failed";
+            if (outcome === "delivered")
+                heartbeatDelivered = true;
             if (heartbeatStopRequested || shutdownRequested)
                 return;
             // Woken by the same waiter list a real shutdown fires, so process exit does
@@ -674,6 +712,7 @@ export async function runExecutor(options, deps, httpClient, seams = {}) {
         }
     }
     function dispatch(job, report) {
+        cycleClaimedJob = true;
         const promise = (async () => {
             try {
                 // `undefined` for the behavior seams (the job runner defaults them), then
@@ -711,6 +750,7 @@ export async function runExecutor(options, deps, httpClient, seams = {}) {
             },
         }));
     function dispatchIntegrationAction(action) {
+        cycleClaimedAction = true;
         const key = --integrationSeq;
         const promise = (async () => {
             try {
@@ -747,10 +787,12 @@ export async function runExecutor(options, deps, httpClient, seams = {}) {
                         : { repo_wide: true }),
                 });
                 if (result.kind === "claimed") {
+                    cycleSuccessfulCall = true;
                     dispatchIntegrationAction(result.action);
                     continue;
                 }
                 if (result.kind === "fatal") {
+                    cycleFailedCall = true;
                     if (result.authHttpStatus === 401 || result.authHttpStatus === 403) {
                         control.reportAuthFatal?.({
                             repoName,
@@ -766,6 +808,7 @@ export async function runExecutor(options, deps, httpClient, seams = {}) {
                     return;
                 }
                 if (result.kind === "retryable") {
+                    cycleFailedCall = true;
                     deps.errorLog(`executor integration action claim retryable: ${result.error}`);
                 }
                 break;
@@ -789,11 +832,32 @@ export async function runExecutor(options, deps, httpClient, seams = {}) {
             }
         }
     }
+    const rawParentPid = deps.env.BAPI_EXECUTOR_PARENT_WATCH_PID;
+    if (rawParentPid !== undefined) {
+        const pid = Number(rawParentPid);
+        if (!/^[1-9][0-9]*$/.test(rawParentPid) || !Number.isSafeInteger(pid)) {
+            deps.errorLog("executor: invalid BAPI_EXECUTOR_PARENT_WATCH_PID; ignoring parent watch");
+        }
+        else if (seams.watchParent) {
+            unsubscribers.push(seams.watchParent(pid, () => {
+                if (shutdownRequested)
+                    return;
+                deps.errorLog(`executor: watched parent process ${pid} exited; shutting down.`);
+                beginShutdown();
+            }));
+        }
+    }
     // Started after the FIRST successful preflight and joined before the runner
     // returns. Declared here so the `finally` below can await it.
     let processHeartbeats = null;
     try {
         for (;;) {
+            cycleSuccessfulCall = heartbeatDelivered;
+            heartbeatDelivered = false;
+            cycleFailedCall = false;
+            cycleClaimedJob = false;
+            cycleClaimedAction = false;
+            cycleClaimOutcome = "not-attempted";
             const report = await collectPreflight(options, deps, preflightSeams);
             latestCorrectionQualification = report.correctionIntentQualified === true &&
                 report.correctionQualificationEvidence?.hook_installed === true &&
@@ -826,7 +890,13 @@ export async function runExecutor(options, deps, httpClient, seams = {}) {
                 deps.errorLog(`executor preflight: ${notice}`);
             }
             if (!report.ok) {
-                deps.errorLog(`executor preflight refused claiming: ${report.fatalFindings.join("; ")}`);
+                cycleClaimOutcome = "preflight-refused";
+                const finding = report.fatalFindings.join("; ");
+                if (shouldReport(finding, lastPreflightRefusal, lastPreflightRefusalAt)) {
+                    deps.errorLog(`executor preflight refused claiming: ${finding}`);
+                    lastPreflightRefusalAt = deps.now();
+                }
+                lastPreflightRefusal = finding;
             }
             else if (shutdownRequested) {
                 // Shutdown arrived during preflight. Claiming now would take on work this
@@ -835,6 +905,7 @@ export async function runExecutor(options, deps, httpClient, seams = {}) {
                 deps.errorLog("executor: shutdown requested; not claiming new work");
             }
             else {
+                lastPreflightRefusal = null;
                 let claiming = true;
                 while (claiming && !shutdownRequested && options.maxConcurrent - active.size > 0) {
                     const freeSlots = options.maxConcurrent - active.size;
@@ -844,10 +915,12 @@ export async function runExecutor(options, deps, httpClient, seams = {}) {
                     // ahead of the branch below. An error result carries no verdict and is
                     // not evidence about the dispatcher, so it is deliberately not observed.
                     if (result.kind === "claimed" || result.kind === "none") {
+                        cycleSuccessfulCall = true;
                         observeDispatcherLiveness(result.reconcilerLiveness);
                         await observeEpicRunCompletion();
                     }
                     if (result.kind === "claimed") {
+                        cycleClaimOutcome = "claimed";
                         const currentEpicRunId = result.job.epic_run_id ?? null;
                         if (lastClaimedEpicRunId !== null &&
                             currentEpicRunId !== null &&
@@ -876,9 +949,13 @@ export async function runExecutor(options, deps, httpClient, seams = {}) {
                         dispatch(result.job, report);
                     }
                     else if (result.kind === "none") {
+                        if (cycleClaimOutcome !== "claimed")
+                            cycleClaimOutcome = "none";
                         claiming = false;
                     }
                     else {
+                        cycleClaimOutcome = "error";
+                        cycleFailedCall = true;
                         deps.errorLog(`executor claim ${result.kind}: ${result.error}`);
                         claiming = false;
                         // BAPI-1021 (AC-5): a categorized 401/403 fatal claim halts the
@@ -919,11 +996,35 @@ export async function runExecutor(options, deps, httpClient, seams = {}) {
             // keeps refusing still holds a sleep assertion and a record, and must not
             // outlive its run. `break` takes the SAME path a `--once` pass does:
             // drain, stop the heartbeat loop, unsubscribe, exit 0.
-            if (!shutdownRequested && active.size === 0 && (await scopedRunIsTerminal())) {
+            const scoped = !shutdownRequested && active.size === 0
+                ? await scopedRunIsTerminal()
+                : { terminal: false, read: "none" };
+            if (scoped.terminal) {
                 runTerminal = true;
                 deps.errorLog(`executor: run ${observedEpicRunId} is finished and no job is held; exiting.`);
                 break;
             }
+            if (exitWhenRunTerminal && !shutdownRequested) {
+                const transition = transitionRetirement(retirementState, {
+                    sleep: pendingSleep,
+                    scopedRead: scoped.read,
+                    successfulServerCall: cycleSuccessfulCall,
+                    failedServerCall: cycleFailedCall,
+                    claimedJob: cycleClaimedJob,
+                    claimedAction: cycleClaimedAction,
+                    claimOutcome: cycleClaimOutcome,
+                    activeCount: active.size,
+                }, {
+                    pollIntervalMs: options.pollIntervalMs,
+                    unreachableMinutes: unreachableSetting.value,
+                    idleHours: idleSetting.value,
+                });
+                retirementState = transition.state;
+                if (transition.decision.kind === "retire") {
+                    deps.errorLog(formatExecutorRetirement(transition.decision.reason, transition.decision.awakeMinutes));
+                    break;
+                }
+            }
             if (options.once || shutdownRequested)
                 break;
             // Sample the clock immediately around the ACTUAL sleep, so the measured gap
@@ -932,7 +1033,9 @@ export async function runExecutor(options, deps, httpClient, seams = {}) {
             const wake = await sleepUntilPollOrShutdown(options.pollIntervalMs);
             if (wake === "shutdown")
                 break;
-            await reportSuspendGap(deps.now() - sleepStartedAt);
+            const elapsedMs = deps.now() - sleepStartedAt;
+            pendingSleep = { completed: true, elapsedMs };
+            await reportSuspendGap(elapsedMs);
         }
         // Drain every dispatched job — on the `once` path and the shutdown path alike.
         // Terminated workers still have to finish supervision, flush final telemetry,

package/build/executor/test-clock.js

@@ -250,6 +250,21 @@ export function makeFakeExecutorDeps(clock, overrides = {}) {
             }
         };
     }
+    // Explicit safe answers for the new preparation reservation and routing reads.
+    // Existing fixtures still own every legacy Git invocation.
+    const fixtureRun = merged.runCommand;
+    merged.runCommand = async (file, args, options) => {
+        if (file === "git" && args.join(" ") === "rev-parse --path-format=absolute --git-common-dir") {
+            return { stdout: overrides.cwd ? `${overrides.cwd}/.git` : "/fake-common.git", stderr: "", exitCode: 0 };
+        }
+        if (file === "git" && args[0] === "config" && args[1] === "--get-all") {
+            return args[2] === "remote.origin.url" ? { stdout: "/fake-origin", stderr: "", exitCode: 0 }
+                : { stdout: "", stderr: "", exitCode: 1 };
+        }
+        if (file === "git" && args[0] === "config" && args[1] === "--local")
+            return { stdout: "", stderr: "", exitCode: 0 };
+        return fixtureRun(file, args, options);
+    };
     return merged;
 }
 /** Sensible default executor options for tests. */

package/build/executor/types.js

@@ -24,6 +24,11 @@ export const EXECUTOR_JOB_TYPE_VALUES = [
     // this union does not carry fails as `ContractError.UnsupportedJobType`,
     // which is the single most likely way this ticket could ship half-landed.
     "ci_rerun",
+    // BAPI-1391 — the run-less gate qualification: run a repository owner's
+    // confirmed local gate commands once on a clean, detached checkout of the
+    // default branch. Deterministic like `ci_rerun` (no worker, no worktree), and
+    // implemented in `gate-qualification-job.ts`.
+    "gate_qualification",
 ];
 /**
  * Server-authoritative completion classification (T2 `ExecutorClassification`,
@@ -42,6 +47,12 @@ export const EXECUTOR_CLASSIFICATION_VALUES = [
     "no_progress",
     "lease_expired",
 ];
+/**
+ * BAPI-1391 — the capability a REPOSITORY-WIDE executor declares when it can run
+ * a run-less `gate_qualification` job. Mirrors the server's stamped
+ * `required_capabilities`, so only a claim declaring it can take such a job.
+ */
+export const GATE_QUALIFICATION_CAPABILITY = "gate_qualification.v1";
 /**
  * BAPI-1311 — the capability an executor declares when it can run a FOCUSED
  * merge-stage `rebase`: validate `payload.focused_rebase` before any worker
@@ -73,6 +84,27 @@ export const TERMINAL_CAPACITY_CAUSE_VALUES = [
     "quota_exhausted",
     "provider_capacity_unavailable",
 ];
+/**
+ * BAPI-1392 — the customized command names carried on a claimed job's payload.
+ *
+ * Returns an empty list for an absent or malformed value, and the usable
+ * non-empty string names (first-seen order, de-duplicated) otherwise. Never
+ * mutates the payload and never throws. Shape-only: catalog membership is
+ * checked by the packaged-recipe resolver against this executor's own bundled
+ * catalog.
+ */
+export function readCustomizedCommands(payload) {
+    const raw = payload && typeof payload === "object" ? payload.customized_commands : undefined;
+    if (!Array.isArray(raw))
+        return [];
+    const names = [];
+    for (const entry of raw) {
+        if (typeof entry === "string" && entry.trim().length > 0 && !names.includes(entry)) {
+            names.push(entry);
+        }
+    }
+    return names;
+}
 /**
  * Outcome of a heartbeat/complete/fail mutation (T2 status mapping):
  *  - `updated`            2xx `{ ok: true }`