@bridge_gpt/mcp-server 0.2.42 → 0.2.43

package/build/executor/job-runner.js

@@ -817,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;
@@ -883,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",
@@ -1743,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,
@@ -1757,7 +1793,7 @@ async function runPreparedSpawn(params) {
             job,
             branch,
             worktreePath,
-            result,
+            result: genericResult,
             runCommand: deps.runCommand,
             headSha: git.last_commit_sha,
             expectedBaseBranch: effectiveBaseBranch,
@@ -1778,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/observation.js

@@ -200,6 +200,50 @@ function sanitizeRateLimitField(value) {
         return null;
     return collapsed.slice(0, MAX_RATE_LIMIT_FIELD_CHARS);
 }
+/**
+ * Safely derive an ISO-8601 UTC reset timestamp from worker-controlled input, or
+ * `undefined` when the value is unusable (BAPI-898).
+ *
+ * Stateless and private: a boundary helper that accepts an unknown value plus
+ * the current epoch time and returns a derived string, never the raw input.
+ * Only a finite number is accepted. A value strictly greater than `1e12` is
+ * interpreted as milliseconds since epoch; everything else — including exactly
+ * `1e12` — is interpreted as seconds. A resolved timestamp outside ten years
+ * before or after `nowMs` is rejected as an implausible worker-reported value.
+ *
+ * The result is emitted EXCLUSIVELY through `new Date(timestampMs).toISOString()`
+ * so raw worker input can never enter telemetry or diagnostics.
+ */
+function normalizeRateLimitResetAt(value, nowMs) {
+    if (typeof value !== "number" || !Number.isFinite(value))
+        return undefined;
+    const timestampMs = value > 1e12 ? value : value * 1000;
+    if (!Number.isFinite(timestampMs))
+        return undefined;
+    const now = new Date(nowMs);
+    const min = new Date(now);
+    min.setUTCFullYear(min.getUTCFullYear() - 10);
+    const max = new Date(now);
+    max.setUTCFullYear(max.getUTCFullYear() + 10);
+    if (timestampMs < min.getTime() || timestampMs > max.getTime())
+        return undefined;
+    return new Date(timestampMs).toISOString();
+}
+/**
+ * Rank a rate-limit status by severity for most-severe-wins retention
+ * (BAPI-898): `allowed` is least severe, `allowed_warning` is next, and every
+ * other status (`rejected`, `blocked`, or anything unrecognized) is most severe.
+ *
+ * Pinned independently of stream parsing so retention logic (BAPI-898 Step 2)
+ * can compare severities without re-deriving this mapping.
+ */
+export function rateLimitSeverity(status) {
+    if (status === "allowed")
+        return 0;
+    if (status === "allowed_warning")
+        return 1;
+    return 2;
+}
 /**
  * Recognize a QUALIFYING `rate_limit_event`, or `null` for everything else.
  *
@@ -231,18 +275,46 @@ function parseRateLimitEvent(obj) {
     const qualifies = utilization >= RATE_LIMIT_WARNING_UTILIZATION || status !== "allowed";
     if (!qualifies)
         return null;
-    return { rate_limit_type: rateLimitType, status, utilization };
+    const advisory = { rate_limit_type: rateLimitType, status, utilization };
+    // Invalid or missing reset data never disqualifies an otherwise-qualifying
+    // advisory — an absent `resets_at` is neutral, not an error.
+    const resetsAt = normalizeRateLimitResetAt(record.resetsAt, Date.now());
+    if (resetsAt !== undefined)
+        advisory.resets_at = resetsAt;
+    return advisory;
 }
 /**
- * Render the operator-facing rate-limit line.
+ * Fixed consequence clause appended to every rate-limit diagnostic (BAPI-898).
+ * Stated exactly once per line so an operator reading it cold understands what
+ * happens next without cross-referencing the runbook.
+ */
+const RATE_LIMIT_CONSEQUENCE_TEXT = "The executor keeps claiming: a worker that hits the ceiling fails fast and its " +
+    "job classifies as a worker failure under the normal retry budget.";
+/** Fixed runbook reference appended to every rate-limit diagnostic (BAPI-898). */
+const RATE_LIMIT_RUNBOOK_REFERENCE = "See docs/claude/epic-conductor-v2-operator-runbook.md §8.";
+/**
+ * Render the operator-facing rate-limit line (BAPI-828, BAPI-898).
  *
  * Exported so the stderr text has ONE definition rather than being rebuilt at the
  * call site — the job runner emits it, and the tests pin it, from here.
+ *
+ * One calm, scannable line: the sanitized limit type, rounded utilization, and
+ * status; whether a reset time is known; the fixed executor consequence; and the
+ * runbook reference. Punctuation shape:
+ * `executor: worker reports … at … (…); <reset clause>. <consequence> <reference>`
+ *
+ * `resets_at` is rendered ONLY from the parser-derived field — never from raw
+ * worker input — and its absence is neutral operational information, not an
+ * error. A non-finite `utilization` reaching this formatter at runtime (outside
+ * the parser's own finite-utilization qualification contract) falls back to
+ * `100%` rather than rendering `NaN%` or `undefined%`.
  */
 export function formatWorkerRateLimitAdvisory(advisory) {
-    const percent = Math.round(advisory.utilization * 100);
+    const percent = Number.isFinite(advisory.utilization) ? Math.round(advisory.utilization * 100) : 100;
+    const resetClause = advisory.resets_at !== undefined ? `; resets at ${advisory.resets_at}` : "; reset time not reported";
     return (`executor: worker reports ${advisory.rate_limit_type} rate limit at ` +
-        `${percent}% (${advisory.status})`);
+        `${percent}% (${advisory.status})${resetClause}. ` +
+        `${RATE_LIMIT_CONSEQUENCE_TEXT} ${RATE_LIMIT_RUNBOOK_REFERENCE}`);
 }
 /**
  * Tolerantly parse one Claude stream-json line for advisory signals.
@@ -465,7 +537,12 @@ export function createObservationState(deps, options) {
     let exitCode;
     let attemptStartSha;
     let attemptEndSha;
-    /** BAPI-828: the FIRST qualifying advisory wins; later ones never overwrite it. */
+    /**
+     * BAPI-828/BAPI-898: the MOST SEVERE qualifying advisory observed so far wins,
+     * ranked by {@link rateLimitSeverity}. An advisory at equal or lower severity —
+     * including a repeat of the same event or a warning observed after a rejection
+     * — leaves this unchanged.
+     */
     let rateLimit;
     /** Residual partial line carried across stdout chunks (BAPI-828). */
     let buffer = "";
@@ -475,15 +552,30 @@ export function createObservationState(deps, options) {
         const parsed = parseClaudeStreamJsonLine(line);
         if (parsed.phase_hint)
             advisory.phase_hint = parsed.phase_hint;
-        if (parsed.rate_limit && rateLimit === undefined) {
-            rateLimit = parsed.rate_limit;
-            try {
-                options.onWorkerRateLimitAdvisory?.(rateLimit);
+        if (parsed.rate_limit) {
+            const observedAdvisory = parsed.rate_limit;
+            const isFirstObservation = rateLimit === undefined;
+            // BAPI-898: strict severity comparison replaces the old "first advisory
+            // wins" rule. Equal or lower severity — a repeat event or a warning
+            // observed after a rejected/blocked status — leaves the stored advisory
+            // unchanged.
+            if (isFirstObservation ||
+                rateLimitSeverity(observedAdvisory.status) > rateLimitSeverity(rateLimit.status)) {
+                rateLimit = observedAdvisory;
             }
-            catch {
-                // The callback only logs. A throwing one must not propagate out of the
-                // stdout pump, where it would be swallowed as a stream error and
-                // silently disable observation for the rest of the run.
+            // The callback preserves one stderr line per job: it fires ONLY for the
+            // first qualifying advisory, while a later severity escalation is still
+            // retained above for `observation.snapshot()` and the existing terminal
+            // telemetry path.
+            if (isFirstObservation) {
+                try {
+                    options.onWorkerRateLimitAdvisory?.(observedAdvisory);
+                }
+                catch {
+                    // The callback only logs. A throwing one must not propagate out of the
+                    // stdout pump, where it would be swallowed as a stream error and
+                    // silently disable observation for the rest of the run.
+                }
             }
         }
     };

package/build/executor/runner.js

@@ -42,6 +42,56 @@ export const SUSPEND_GAP_SLACK_MS = 60_000;
 export function formatSuspendGapDiagnostic(elapsedMs) {
     return `executor: host appears to have been suspended for ~${Math.round(elapsedMs / 1000)} s (poll gap)`;
 }
+function normalizeDispatcherAvailability(value) {
+    if (value === "fresh")
+        return "fresh";
+    if (value === "stale" || value === "never_seen")
+        return "absent";
+    return "unknown";
+}
+/**
+ * The unavailable diagnostic. Exported so the message has ONE definition that a
+ * test can assert against rather than a copy that drifts.
+ *
+ * Calm on purpose, and it says what the executor is going to do next: this is
+ * not a failure of the executor, it keeps polling, and the fix is on the server
+ * side. An executor that exited here would turn a restartable dispatcher outage
+ * into a second outage.
+ */
+export function formatDispatcherUnavailableDiagnostic(liveness) {
+    return (`executor: no fresh reconciler/dispatcher heartbeat is available ` +
+        `(reconciler_liveness=${liveness}); the dispatcher may not be running. ` +
+        "Check DISABLE_SCHEDULER and GET /automation/health; see " +
+        "docs/claude/epic-conductor-v2-operator-runbook.md. Continuing to poll.");
+}
+/** The recovery diagnostic, emitted once when an absent dispatcher comes back. */
+export function formatDispatcherRecoveredDiagnostic() {
+    return ("executor: reconciler/dispatcher heartbeat is fresh again; continuing to poll.");
+}
+/**
+ * How often the executor publishes PER-PROCESS liveness (BAPI-871).
+ *
+ * The server calls an executor stale at 300 s (`EXECUTOR_STALE_SECONDS`). 60 s is
+ * comfortably below that — four consecutive misses before anyone is alarmed —
+ * which keeps a transient network blip, a VPN reconnect, or one slow request from
+ * manufacturing an outage while still detecting a genuinely dead process within
+ * the server's own window.
+ *
+ * Deliberately INDEPENDENT of claim results and of any active job. An executor
+ * that is idle is exactly the executor whose liveness was previously invisible,
+ * so a cadence that paused while nothing was claimed would rebuild the blind spot
+ * this endpoint exists to remove.
+ */
+export const PROCESS_HEARTBEAT_INTERVAL_MS = 60_000;
+/** Delivery-failure diagnostic. Bounded, credential-free, stderr-only. */
+export function formatProcessHeartbeatFailureDiagnostic() {
+    return ("executor: process-heartbeat delivery is failing; the server may report this " +
+        "executor as stale. Claiming and running jobs are unaffected.");
+}
+/** Emitted once when delivery starts working again. */
+export function formatProcessHeartbeatRecoveredDiagnostic() {
+    return "executor: process-heartbeat delivery has recovered.";
+}
 /**
  * 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).
@@ -70,6 +120,50 @@ export async function runExecutor(options, deps, httpClient, seams = {}) {
     // the sole eligibility authority. Declared here, outside both loops below, so
     // it persists across poll cycles for the lifetime of this `runExecutor` call.
     let lastClaimedEpicRunId = null;
+    // BAPI-871 — the last normalized dispatcher availability OBSERVED on a
+    // successful claim response, retained for the lifetime of this `runExecutor`
+    // call. Declared here, outside both loops, so the suppression below spans poll
+    // cycles: an absent dispatcher must produce one diagnostic, not one per poll.
+    //
+    // `null` means "nothing EVALUABLE observed yet", which is what makes the FIRST
+    // absent observation announce itself rather than being treated as an unchanged
+    // state. Only `fresh` and `absent` are ever stored — see the transparency rule
+    // for `unknown` in the observer below.
+    //
+    // Read-only diagnostics, exactly like `lastClaimedEpicRunId` above: it never
+    // feeds claim eligibility, cadence, retries, dispatch, or exit.
+    let lastDispatcherAvailability = null;
+    /**
+     * Announce a dispatcher availability CHANGE, and only a change.
+     *
+     * Called after every successful claim response and before the runner branches
+     * on claimed-versus-no-job, because the no-job branch is precisely the one that
+     * used to say nothing at all.
+     */
+    const observeDispatcherLiveness = (liveness) => {
+        const availability = normalizeDispatcherAvailability(liveness);
+        // `unknown` is TRANSPARENT: it emits nothing and, just as importantly, does
+        // not overwrite what was last actually established. An operator who saw
+        // "the dispatcher may not be running", then a stretch of unevaluable polls,
+        // then a fresh heartbeat, must still be told it recovered — and swallowing
+        // that recovery because an unevaluable poll sat in between would leave the
+        // absence warning standing as the last word.
+        if (availability === "unknown")
+            return;
+        const previous = lastDispatcherAvailability;
+        lastDispatcherAvailability = availability;
+        if (availability === previous)
+            return;
+        if (availability === "absent") {
+            // stderr, never `console.log` — stdout is the MCP protocol channel.
+            deps.errorLog(formatDispatcherUnavailableDiagnostic(liveness));
+        }
+        else if (previous === "absent") {
+            // Only from `absent`. A first-ever `fresh` observation is the ordinary
+            // healthy start-up and deserves no announcement.
+            deps.errorLog(formatDispatcherRecoveredDiagnostic());
+        }
+    };
     // 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
     // the loop would be discarded every cycle and re-probe exactly as before; a
@@ -144,6 +238,102 @@ export async function runExecutor(options, deps, httpClient, seams = {}) {
                 shutdownWaiters.splice(index, 1);
         }
     };
+    // The heartbeat loop's OWN stop signal (BAPI-871). Deliberately separate from
+    // `shutdownRequested`: winding the loop down at the end of a `once` run must
+    // not flip the runner's shutdown flag, because `beginShutdown` is idempotent
+    // on that flag and a signal arriving late — after the loop ended but before the
+    // handlers are unsubscribed — must still reach the live workers.
+    let heartbeatStopRequested = false;
+    const heartbeatWaiters = [];
+    const stopProcessHeartbeats = () => {
+        heartbeatStopRequested = true;
+        for (const wake of heartbeatWaiters.splice(0, heartbeatWaiters.length))
+            wake();
+    };
+    /**
+     * Sleep one heartbeat interval, returning early on either stop condition.
+     *
+     * Races the interval against a real shutdown AND the loop's own wind-down, so
+     * process exit never waits out a full cadence.
+     */
+    const sleepUntilHeartbeatOrStop = async (ms) => {
+        if (heartbeatStopRequested || shutdownRequested)
+            return "stop";
+        let wake;
+        const interrupted = new Promise((resolve) => {
+            wake = resolve;
+        });
+        heartbeatWaiters.push(wake);
+        shutdownWaiters.push(wake);
+        try {
+            return await Promise.race([
+                deps.sleep(ms).then(() => "slept"),
+                interrupted.then(() => "stop"),
+            ]);
+        }
+        finally {
+            for (const list of [heartbeatWaiters, shutdownWaiters]) {
+                const index = list.indexOf(wake);
+                if (index !== -1)
+                    list.splice(index, 1);
+            }
+        }
+    };
+    /**
+     * Publish per-process liveness on a fixed cadence until shutdown (BAPI-871).
+     *
+     * Runs CONCURRENTLY with the poll loop rather than inside it, because the poll
+     * loop's cadence is the operator's to configure and its cycle time varies with
+     * whatever work it picks up — neither of which should be able to change how
+     * often this process proves it is alive.
+     *
+     * Every failure mode is contained here: delivery is non-critical monitoring, so
+     * a failure is reported to stderr and the loop keeps going. It cannot fail a
+     * claim, fail a job, or end the run.
+     */
+    const runProcessHeartbeatLoop = async () => {
+        const publish = httpClient.processHeartbeat;
+        // A client without the capability (every object-literal test fake) simply
+        // does not heartbeat. Nothing else about the run changes.
+        if (typeof publish !== "function")
+            return;
+        // `repoName` FIRST so the client authenticates with the primary repo's key in
+        // multi-repo mode, then the remaining configured repos, de-duplicated.
+        const repoNames = [options.repoName, ...options.repos].filter((repo, index, all) => repo && all.indexOf(repo) === index);
+        const request = {
+            component: "executor",
+            instance_id: options.executorId,
+            repo_names: repoNames,
+        };
+        // Suppression state: one message per CHANGE of delivery state, so a long
+        // outage produces one line rather than one per minute.
+        let lastFailed = false;
+        for (;;) {
+            let outcome;
+            try {
+                outcome = await publish.call(httpClient, request);
+            }
+            catch {
+                // The client already contains its own errors; this is belt-and-braces so
+                // an unexpected throw can never escape into the run.
+                outcome = "failed";
+            }
+            if (outcome === "failed" && !lastFailed) {
+                deps.errorLog(formatProcessHeartbeatFailureDiagnostic());
+            }
+            else if (outcome === "delivered" && lastFailed) {
+                deps.errorLog(formatProcessHeartbeatRecoveredDiagnostic());
+            }
+            lastFailed = outcome === "failed";
+            if (heartbeatStopRequested || shutdownRequested)
+                return;
+            // Woken by the same waiter list a real shutdown fires, so process exit does
+            // not have to wait out a full interval.
+            if ((await sleepUntilHeartbeatOrStop(PROCESS_HEARTBEAT_INTERVAL_MS)) === "stop") {
+                return;
+            }
+        }
+    };
     /**
      * Annotate an abnormally long COMPLETED poll gap (BAPI-828).
      *
@@ -222,9 +412,19 @@ export async function runExecutor(options, deps, httpClient, seams = {}) {
             }
         }
     }
+    // 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 (;;) {
             const report = await collectPreflight(options, deps, preflightSeams);
+            // First heartbeat goes out immediately once preflight passes, so a freshly
+            // started executor is visible to the server without waiting one interval.
+            // Gated on `report.ok` because an executor that preflight refuses is not
+            // going to do any work, and advertising it as live would be a lie.
+            if (report.ok && processHeartbeats === null && !shutdownRequested) {
+                processHeartbeats = runProcessHeartbeatLoop();
+            }
             // 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
@@ -248,6 +448,12 @@ export async function runExecutor(options, deps, httpClient, seams = {}) {
                     const freeSlots = options.maxConcurrent - active.size;
                     const manifest = buildClaimManifest(report, options, freeSlots);
                     const result = await httpClient.claim(manifest);
+                    // Evaluated on every SUCCESSFUL claim response — 200 and 204 alike —
+                    // 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") {
+                        observeDispatcherLiveness(result.reconcilerLiveness);
+                    }
                     if (result.kind === "claimed") {
                         const currentEpicRunId = result.job.epic_run_id ?? null;
                         if (lastClaimedEpicRunId !== null &&
@@ -304,6 +510,19 @@ export async function runExecutor(options, deps, httpClient, seams = {}) {
         await Promise.all(active.values());
     }
     finally {
+        // Join the heartbeat loop before returning, via its OWN stop signal. A `once`
+        // run breaks out of the poll loop with `shutdownRequested` still false, and
+        // it must stay false: `beginShutdown` is idempotent on that flag, so setting
+        // it here would silently swallow a signal that arrives during this wind-down.
+        if (processHeartbeats !== null) {
+            stopProcessHeartbeats();
+            try {
+                await processHeartbeats;
+            }
+            catch {
+                /* a monitoring loop must never change the runner's outcome */
+            }
+        }
         // 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