@bridge_gpt/mcp-server 0.2.2 → 0.2.3

package/build/conductor/supervisor-config.js

@@ -0,0 +1,150 @@
+/**
+ * Supervisor configuration resolution (BAPI-396, conductor C4).
+ *
+ * Centralizes the supervisor's wake cadence, global timeout, per-state stall
+ * thresholds, liveness thresholds, escalation cooldown, and LLM budget caps.
+ * All values are resolved from `process.env` with conservative, bounded defaults
+ * following the style of {@link resolveConductorStoreConfig} in `store.ts`:
+ * malformed values fall back to the default and excessive values are clamped.
+ *
+ * Token discipline: the WAKE cadence (frequent, deterministic event polling) is
+ * intentionally separate from the LLM cadence (judgment-triggered only). The
+ * deterministic loop runs every `wake_interval_ms`; the LLM is consulted at most
+ * `llm_max_calls` times per run and only for ambiguous escalation candidates.
+ */
+const MINUTE_MS = 60_000;
+const HOUR_MS = 60 * MINUTE_MS;
+// --- Wake cadence: frequent, deterministic. -------------------------------
+const WAKE_INTERVAL_DEFAULT_MS = 45_000;
+const WAKE_INTERVAL_MIN_MS = 30_000;
+const WAKE_INTERVAL_MAX_MS = 60_000;
+// --- Global run timeout: a conservative long-run ceiling. -----------------
+const GLOBAL_TIMEOUT_DEFAULT_MS = 24 * HOUR_MS;
+const GLOBAL_TIMEOUT_MIN_MS = 5 * MINUTE_MS;
+const GLOBAL_TIMEOUT_MAX_MS = 7 * 24 * HOUR_MS;
+// --- Escalation cooldown: at least 15 minutes by default. -----------------
+const ESCALATION_COOLDOWN_DEFAULT_MS = 15 * MINUTE_MS;
+const ESCALATION_COOLDOWN_MIN_MS = 5 * MINUTE_MS;
+const ESCALATION_COOLDOWN_MAX_MS = 24 * HOUR_MS;
+// --- Liveness thresholds (timestamp-only, separate from progress). --------
+const QUIET_AFTER_DEFAULT_MS = 5 * MINUTE_MS;
+const QUIET_AFTER_MIN_MS = MINUTE_MS;
+const QUIET_AFTER_MAX_MS = HOUR_MS;
+const LIVENESS_STALLED_AFTER_DEFAULT_MS = 20 * MINUTE_MS;
+const LIVENESS_STALLED_AFTER_MIN_MS = 5 * MINUTE_MS;
+const LIVENESS_STALLED_AFTER_MAX_MS = 4 * HOUR_MS;
+const DEAD_AFTER_DEFAULT_MS = 2 * HOUR_MS;
+const DEAD_AFTER_MIN_MS = 10 * MINUTE_MS;
+const DEAD_AFTER_MAX_MS = 24 * HOUR_MS;
+// --- LLM budget. ----------------------------------------------------------
+const LLM_MAX_CALLS_DEFAULT = 10;
+const LLM_MAX_CALLS_MIN = 0;
+const LLM_MAX_CALLS_MAX = 1000;
+const LLM_TIMEOUT_DEFAULT_MS = 30_000;
+const LLM_TIMEOUT_MIN_MS = 1_000;
+const LLM_TIMEOUT_MAX_MS = 120_000;
+/**
+ * Parse a bounded integer from an env-style string. Mirrors `parseBoundedInt`
+ * in `store.ts`: blank/undefined/non-finite/float-with-fraction/non-numeric
+ * values resolve to `fallback`; in-range integers pass through; out-of-range
+ * integers clamp to `[min, max]`.
+ */
+export function parseBoundedSupervisorInt(raw, fallback, min, max) {
+    if (raw === undefined)
+        return fallback;
+    const trimmed = raw.trim();
+    if (trimmed.length === 0)
+        return fallback;
+    // Reject anything that is not a base-10 integer (e.g. "abc", "12.5",
+    // "Infinity", "1e3"): parseInt would silently truncate "12.5" -> 12, which
+    // hides malformed config. A strict integer regex keeps the contract honest.
+    if (!/^[+-]?\d+$/.test(trimmed))
+        return fallback;
+    const parsed = Number.parseInt(trimmed, 10);
+    if (!Number.isFinite(parsed))
+        return fallback;
+    return Math.min(max, Math.max(min, parsed));
+}
+const POLL_LIMIT_DEFAULT = 200;
+const POLL_LIMIT_MIN = 1;
+const POLL_LIMIT_MAX = 1000;
+/** Truthy parse for boolean-ish env strings (`0`/`false`/`off`/`no` => false). */
+function parseBoolEnv(raw, fallback) {
+    if (raw === undefined)
+        return fallback;
+    const v = raw.trim().toLowerCase();
+    if (v.length === 0)
+        return fallback;
+    if (v === "0" || v === "false" || v === "off" || v === "no")
+        return false;
+    if (v === "1" || v === "true" || v === "on" || v === "yes")
+        return true;
+    return fallback;
+}
+/**
+ * Resolve the supervisor configuration. Precedence per field: a direct override
+ * (when provided and valid) wins over the environment, which wins over the
+ * conservative default. Stall thresholds are per-state and intentionally make
+ * `active` / `verifying` (long legitimate work) far more tolerant than
+ * `not_started` / `unknown` (quick stalls) to avoid false positives on long
+ * tests/builds.
+ */
+export function resolveSupervisorConfig(overrides = {}, env = process.env) {
+    const wake_interval_ms = clampOverride(overrides.wake_interval_ms, parseBoundedSupervisorInt(env.BAPI_CONDUCTOR_WAKE_INTERVAL_MS, WAKE_INTERVAL_DEFAULT_MS, WAKE_INTERVAL_MIN_MS, WAKE_INTERVAL_MAX_MS), WAKE_INTERVAL_MIN_MS, WAKE_INTERVAL_MAX_MS);
+    const global_timeout_ms = clampOverride(overrides.global_timeout_ms, parseBoundedSupervisorInt(env.BAPI_CONDUCTOR_GLOBAL_TIMEOUT_MS, GLOBAL_TIMEOUT_DEFAULT_MS, GLOBAL_TIMEOUT_MIN_MS, GLOBAL_TIMEOUT_MAX_MS), GLOBAL_TIMEOUT_MIN_MS, GLOBAL_TIMEOUT_MAX_MS);
+    const escalation_cooldown_ms = clampOverride(overrides.escalation_cooldown_ms, parseBoundedSupervisorInt(env.BAPI_CONDUCTOR_ESCALATION_COOLDOWN_MS, ESCALATION_COOLDOWN_DEFAULT_MS, ESCALATION_COOLDOWN_MIN_MS, ESCALATION_COOLDOWN_MAX_MS), ESCALATION_COOLDOWN_MIN_MS, ESCALATION_COOLDOWN_MAX_MS);
+    const quiet_after_ms = parseBoundedSupervisorInt(env.BAPI_CONDUCTOR_QUIET_AFTER_MS, QUIET_AFTER_DEFAULT_MS, QUIET_AFTER_MIN_MS, QUIET_AFTER_MAX_MS);
+    const liveness_stalled_after_ms = parseBoundedSupervisorInt(env.BAPI_CONDUCTOR_LIVENESS_STALLED_AFTER_MS, LIVENESS_STALLED_AFTER_DEFAULT_MS, LIVENESS_STALLED_AFTER_MIN_MS, LIVENESS_STALLED_AFTER_MAX_MS);
+    const dead_after_ms = parseBoundedSupervisorInt(env.BAPI_CONDUCTOR_DEAD_AFTER_MS, DEAD_AFTER_DEFAULT_MS, DEAD_AFTER_MIN_MS, DEAD_AFTER_MAX_MS);
+    // LLM is enabled by default but degrades cleanly. A direct `llm_enabled:false`
+    // override (e.g. CLI `--no-llm`) forces deterministic-only mode.
+    const llm_enabled = overrides.llm_enabled !== undefined
+        ? overrides.llm_enabled
+        : parseBoolEnv(env.BAPI_CONDUCTOR_LLM_ENABLED, true);
+    const llm_max_calls = clampOverride(overrides.llm_max_calls, parseBoundedSupervisorInt(env.BAPI_CONDUCTOR_LLM_MAX_CALLS, LLM_MAX_CALLS_DEFAULT, LLM_MAX_CALLS_MIN, LLM_MAX_CALLS_MAX), LLM_MAX_CALLS_MIN, LLM_MAX_CALLS_MAX);
+    const llm_timeout_ms = clampOverride(overrides.llm_timeout_ms, parseBoundedSupervisorInt(env.BAPI_CONDUCTOR_LLM_TIMEOUT_MS, LLM_TIMEOUT_DEFAULT_MS, LLM_TIMEOUT_MIN_MS, LLM_TIMEOUT_MAX_MS), LLM_TIMEOUT_MIN_MS, LLM_TIMEOUT_MAX_MS);
+    const poll_limit = parseBoundedSupervisorInt(env.BAPI_CONDUCTOR_SUPERVISOR_POLL_LIMIT, POLL_LIMIT_DEFAULT, POLL_LIMIT_MIN, POLL_LIMIT_MAX);
+    return {
+        wake_interval_ms,
+        global_timeout_ms,
+        stall_thresholds_ms: resolveStallThresholds(env),
+        liveness: {
+            quiet_after_ms,
+            stalled_after_ms: liveness_stalled_after_ms,
+            dead_after_ms,
+        },
+        escalation_cooldown_ms,
+        llm_enabled,
+        llm_max_calls,
+        llm_timeout_ms,
+        poll_limit,
+    };
+}
+/** Apply a direct numeric override only when present + finite; else keep base. */
+function clampOverride(override, base, min, max) {
+    if (override === undefined || !Number.isFinite(override))
+        return base;
+    return Math.min(max, Math.max(min, Math.floor(override)));
+}
+/** Resolve per-state stall thresholds with conservative defaults. */
+function resolveStallThresholds(env) {
+    return {
+        // A worker that never starts should surface quickly.
+        not_started: parseBoundedSupervisorInt(env.BAPI_CONDUCTOR_STALL_NOT_STARTED_MS, 15 * MINUTE_MS, MINUTE_MS, HOUR_MS),
+        // Active work (tests/builds) is given a long, tolerant budget.
+        active: parseBoundedSupervisorInt(env.BAPI_CONDUCTOR_STALL_ACTIVE_MS, 2 * HOUR_MS, 10 * MINUTE_MS, 12 * HOUR_MS),
+        // Already-stalled workers re-escalate on a slower cadence.
+        stalled: parseBoundedSupervisorInt(env.BAPI_CONDUCTOR_STALL_STALLED_MS, 30 * MINUTE_MS, 5 * MINUTE_MS, 6 * HOUR_MS),
+        // Blocked workers may legitimately wait a long time (human input, deps).
+        blocked: parseBoundedSupervisorInt(env.BAPI_CONDUCTOR_STALL_BLOCKED_MS, 24 * HOUR_MS, 30 * MINUTE_MS, 7 * 24 * HOUR_MS),
+        // A done candidate that never gets verified should surface.
+        candidate_done: parseBoundedSupervisorInt(env.BAPI_CONDUCTOR_STALL_CANDIDATE_DONE_MS, 30 * MINUTE_MS, 5 * MINUTE_MS, 6 * HOUR_MS),
+        // Verification (CI) gets a long, tolerant budget like active work.
+        verifying: parseBoundedSupervisorInt(env.BAPI_CONDUCTOR_STALL_VERIFYING_MS, 2 * HOUR_MS, 10 * MINUTE_MS, 12 * HOUR_MS),
+        // Unknown-state workers surface on a moderate cadence.
+        unknown: parseBoundedSupervisorInt(env.BAPI_CONDUCTOR_STALL_UNKNOWN_MS, 30 * MINUTE_MS, 5 * MINUTE_MS, 6 * HOUR_MS),
+        // Terminal states never "stall"; large sentinels keep arithmetic uniform.
+        complete: Number.MAX_SAFE_INTEGER,
+        failed: Number.MAX_SAFE_INTEGER,
+    };
+}

package/build/conductor/supervisor-escalation.js

@@ -0,0 +1,244 @@
+/**
+ * Deterministic escalation policy (BAPI-396, conductor C4).
+ *
+ * Escalation v1 is TERMINAL OUTPUT + a ledger `supervisor.assessment` event
+ * only — it never merges, transitions Jira, emails, pays, or takes any other
+ * privileged action. This module is the deterministic core of that policy:
+ *
+ *   - {@link findSupervisorEscalationCandidates} inspects worker state/liveness
+ *     and the global deadline and returns machine-reasoned candidates.
+ *   - {@link shouldEmitEscalation} enforces a per-worker, per-reason cooldown
+ *     and returns the cooldown window identifier used to build the idempotency
+ *     key — so the same escalation is not re-emitted within a window even across
+ *     crash/restart (the window is time-bucketed and the history is persisted in
+ *     the projection summary).
+ *   - {@link recordEscalationResult} records the emit outcome into state.
+ *   - {@link formatEscalationForTerminal} renders a concise, secret-free line.
+ */
+/** Coarse kind embedded in the idempotency key for all escalations. */
+export const ESCALATION_KIND = "escalation";
+/** ms since the most recent signal a worker produced (0 when none). */
+function elapsedSinceSignal(worker, now) {
+    const candidates = [
+        worker.last_event_time,
+        worker.last_progress_time,
+        worker.last_heartbeat_time,
+    ]
+        .map((iso) => (iso ? Date.parse(iso) : NaN))
+        .filter((v) => Number.isFinite(v));
+    if (candidates.length === 0)
+        return 0;
+    return Math.max(0, now - Math.max(...candidates));
+}
+/**
+ * Inspect run state and return deterministic escalation candidates. Reasons:
+ * `worker_not_started`, `worker_stalled`, `worker_blocked`, `worker_dead`,
+ * `candidate_done_stuck`, `verification_stalled`, and `global_timeout`. Terminal
+ * workers never produce candidates. `ambiguous` marks candidates that benefit
+ * from an LLM judgment (long-running stalls) vs. unambiguous ones.
+ */
+export function findSupervisorEscalationCandidates(state, config, now) {
+    const candidates = [];
+    for (const worker of Object.values(state.workers)) {
+        if (worker.state === "complete" || worker.state === "failed")
+            continue;
+        const elapsed = elapsedSinceSignal(worker, now);
+        const baseContext = {
+            worker_id: worker.worker_id,
+            ticket_key: worker.ticket_key,
+            state: worker.state,
+            liveness: worker.liveness,
+        };
+        // A dead worker is the strongest liveness signal — surface it regardless of
+        // progress state.
+        if (worker.liveness === "dead") {
+            candidates.push({
+                reason: "worker_dead",
+                kind: ESCALATION_KIND,
+                worker_id: worker.worker_id,
+                state: worker.state,
+                liveness: worker.liveness,
+                elapsed_ms: elapsed,
+                ambiguous: false,
+                context: baseContext,
+            });
+            continue;
+        }
+        switch (worker.state) {
+            case "not_started":
+                // Worker tabs spawn AFTER `run.started`, so every roster worker is
+                // `not_started` on the supervisor's first iteration. Gate on liveness (as
+                // for `verifying`) so a worker that simply hasn't started YET does not
+                // escalate immediately — only once it has gone quiet/stalled/dead (no
+                // signal for the configured liveness grace) is a not-started worker worth
+                // surfacing. A still-not-started worker that later crosses its stall
+                // threshold is promoted to `stalled` by housekeeping and surfaces as
+                // `worker_stalled`.
+                if (worker.liveness !== "alive") {
+                    candidates.push({
+                        reason: "worker_not_started",
+                        kind: ESCALATION_KIND,
+                        worker_id: worker.worker_id,
+                        state: worker.state,
+                        liveness: worker.liveness,
+                        elapsed_ms: elapsed,
+                        ambiguous: false,
+                        context: baseContext,
+                    });
+                }
+                break;
+            case "blocked":
+                candidates.push({
+                    reason: "worker_blocked",
+                    kind: ESCALATION_KIND,
+                    worker_id: worker.worker_id,
+                    state: worker.state,
+                    liveness: worker.liveness,
+                    elapsed_ms: elapsed,
+                    ambiguous: false,
+                    context: { ...baseContext, blocked_reason: worker.blocked_reason },
+                });
+                break;
+            case "stalled":
+                candidates.push({
+                    reason: "worker_stalled",
+                    kind: ESCALATION_KIND,
+                    worker_id: worker.worker_id,
+                    state: worker.state,
+                    liveness: worker.liveness,
+                    elapsed_ms: elapsed,
+                    ambiguous: true,
+                    context: baseContext,
+                });
+                break;
+            case "candidate_done":
+                // `gate.met` flips a worker to `candidate_done` the instant the gate is
+                // reached — that is healthy progress, not a stall. Gate on liveness (as
+                // for `verifying`) so we only surface a done-candidate that has gone
+                // quiet/stalled waiting for verification, not every gate.met.
+                if (worker.liveness !== "alive") {
+                    candidates.push({
+                        reason: "candidate_done_stuck",
+                        kind: ESCALATION_KIND,
+                        worker_id: worker.worker_id,
+                        state: worker.state,
+                        liveness: worker.liveness,
+                        elapsed_ms: elapsed,
+                        ambiguous: true,
+                        context: baseContext,
+                    });
+                }
+                break;
+            case "verifying":
+                // Only surface verification as a candidate once liveness shows it has
+                // gone quiet/stalled — a healthy in-progress verification is not an
+                // escalation.
+                if (worker.liveness === "stalled") {
+                    candidates.push({
+                        reason: "verification_stalled",
+                        kind: ESCALATION_KIND,
+                        worker_id: worker.worker_id,
+                        state: worker.state,
+                        liveness: worker.liveness,
+                        elapsed_ms: elapsed,
+                        ambiguous: true,
+                        context: baseContext,
+                    });
+                }
+                break;
+            default:
+                break;
+        }
+    }
+    // Run-level: global timeout.
+    const deadlineMs = state.global_deadline_at ? Date.parse(state.global_deadline_at) : NaN;
+    if (Number.isFinite(deadlineMs) && now >= deadlineMs) {
+        candidates.push({
+            reason: "global_timeout",
+            kind: ESCALATION_KIND,
+            worker_id: null,
+            state: null,
+            liveness: null,
+            elapsed_ms: Math.max(0, now - deadlineMs),
+            ambiguous: false,
+            context: {
+                run_id: state.run_id,
+                deadline_at: state.global_deadline_at,
+                worker_count: Object.keys(state.workers).length,
+            },
+        });
+    }
+    return candidates;
+}
+/** Bucket `now` into a stable cooldown window id of width `cooldown_ms`. */
+function cooldownWindowFor(now, cooldownMs) {
+    const width = cooldownMs > 0 ? cooldownMs : 1;
+    return String(Math.floor(now / width));
+}
+/**
+ * Decide whether a candidate should be emitted now. A candidate is SUPPRESSED
+ * when an escalation for the same worker + reason was already emitted (or hit a
+ * duplicate) within the SAME cooldown window. Returns the cooldown window
+ * identifier the caller must pass to `makeSupervisorIdempotencyKey` so the
+ * idempotency key and the suppression check agree.
+ */
+export function shouldEmitEscalation(state, candidate, config, now) {
+    const cooldownWindow = cooldownWindowFor(now, config.escalation_cooldown_ms);
+    const alreadyDecided = state.escalations.some((record) => record.reason === candidate.reason &&
+        (record.worker_id ?? null) === (candidate.worker_id ?? null) &&
+        record.cooldown_window === cooldownWindow &&
+        // A prior emit/duplicate OR an explicit LLM "do not escalate" (suppressed)
+        // decision in this window is binding — do not re-decide (and, for ambiguous
+        // candidates, do not re-query the LLM) until the window rolls over.
+        (record.outcome === "emitted" ||
+            record.outcome === "duplicate" ||
+            record.outcome === "suppressed"));
+    return { emit: !alreadyDecided, cooldown_window: cooldownWindow };
+}
+/**
+ * Record the outcome of an escalation emit attempt into run state. The recorded
+ * window/idempotency metadata is what {@link shouldEmitEscalation} consults
+ * after a projection hydrate/restart to avoid duplicate terminal spam.
+ */
+export function recordEscalationResult(state, candidate, cooldownWindow, idempotencyKey, outcome, now) {
+    const record = {
+        idempotency_key: idempotencyKey,
+        worker_id: candidate.worker_id ?? null,
+        reason: candidate.reason,
+        kind: candidate.kind,
+        cooldown_window: cooldownWindow,
+        outcome,
+        recorded_at: new Date(now).toISOString(),
+    };
+    state.escalations.push(record);
+    return record;
+}
+/** Format a compact elapsed duration like `1h2m`, `3m`, `45s`. */
+function formatElapsed(ms) {
+    const totalSeconds = Math.max(0, Math.floor(ms / 1000));
+    const hours = Math.floor(totalSeconds / 3600);
+    const minutes = Math.floor((totalSeconds % 3600) / 60);
+    const seconds = totalSeconds % 60;
+    if (hours > 0)
+        return `${hours}h${minutes}m`;
+    if (minutes > 0)
+        return `${minutes}m`;
+    return `${seconds}s`;
+}
+/**
+ * Render a concise, SECRET-FREE terminal escalation line. Includes run id,
+ * worker id, reason, state, liveness, elapsed time, and optional LLM-drafted
+ * text. Never includes raw payloads or full JSON dumps.
+ */
+export function formatEscalationForTerminal(runId, candidate, draftText) {
+    const worker = candidate.worker_id ? ` worker=${candidate.worker_id}` : "";
+    const stateBit = candidate.state ? ` state=${candidate.state}` : "";
+    const liveBit = candidate.liveness ? ` liveness=${candidate.liveness}` : "";
+    const elapsed = ` elapsed=${formatElapsed(candidate.elapsed_ms)}`;
+    let line = `[supervisor] run=${runId}${worker} reason=${candidate.reason}${stateBit}${liveBit}${elapsed}`;
+    if (draftText && draftText.trim().length > 0) {
+        // Single-line the drafted text so the terminal stays scannable.
+        line += ` :: ${draftText.replace(/\s+/g, " ").trim()}`;
+    }
+    return line;
+}

package/build/conductor/supervisor-judgment-python.js

@@ -0,0 +1,141 @@
+/**
+ * TypeScript-to-Python judgment adapter (BAPI-396, conductor C4).
+ *
+ * Lets the Node conductor CLI invoke the approved Python LLM boundary
+ * (`src.python.conductor.supervisor_judgment`) WITHOUT any direct model-provider
+ * code in TypeScript. The compact judgment request is passed to the Python
+ * module over stdin as JSON, the module is spawned with `shell: false` and a
+ * list of arguments (never a shell string), and stdout is validated through the
+ * shared {@link parseSupervisorJudgmentResponse}.
+ *
+ * Every boundary failure (missing Python, timeout, non-zero exit, malformed
+ * output) is converted to a SANITIZED {@link SupervisorJudgmentError}: the
+ * caller ({@link assessSupervisorCandidate}) catches it and degrades to a
+ * deterministic assessment. Secrets, stderr text, and stack traces are never
+ * placed in the thrown error.
+ */
+import { spawn as nodeSpawn } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { SupervisorJudgmentError, parseSupervisorJudgmentResponse, } from "./supervisor-judgment.js";
+/** The Python module the adapter invokes via `python -m <module>`. */
+export const SUPERVISOR_JUDGMENT_PYTHON_MODULE = "src.python.conductor.supervisor_judgment";
+function nonEmpty(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+/**
+ * Resolve the Python executable. Prefers the explicit, safe env override
+ * `BAPI_CONDUCTOR_PYTHON`; otherwise falls back to `python3`. No shell string is
+ * ever constructed — the returned value is used as `spawn`'s `command` arg.
+ */
+export function resolveSupervisorJudgmentCommand(env = process.env) {
+    if (nonEmpty(env.BAPI_CONDUCTOR_PYTHON))
+        return env.BAPI_CONDUCTOR_PYTHON.trim();
+    return "python3";
+}
+/**
+ * Resolve the working directory the Python module runs from (the repo root, so
+ * `src.python...` imports resolve). Prefers the explicit `BAPI_CONDUCTOR_PYTHON_CWD`
+ * override; otherwise derives the repo root relative to this compiled module
+ * (`<repo>/mcp_server/build/conductor/<file>.js` -> `<repo>`).
+ */
+export function resolveSupervisorJudgmentCwd(env = process.env) {
+    if (nonEmpty(env.BAPI_CONDUCTOR_PYTHON_CWD))
+        return env.BAPI_CONDUCTOR_PYTHON_CWD.trim();
+    const here = fileURLToPath(import.meta.url);
+    // dirname=conductor, ../=build, ../../=mcp_server, ../../../=repo root.
+    return path.resolve(path.dirname(here), "..", "..", "..");
+}
+/** Build the secret-free stdin payload for the Python module. */
+function buildRequestPayload(request, env) {
+    const payload = {
+        run_id: request.run_id,
+        candidate: request.candidate,
+        worker: request.worker,
+    };
+    if (nonEmpty(env.BAPI_CONDUCTOR_REPO_NAME))
+        payload.repo_name = env.BAPI_CONDUCTOR_REPO_NAME.trim();
+    if (nonEmpty(env.BAPI_CONDUCTOR_RUN_ID))
+        payload.session_id = env.BAPI_CONDUCTOR_RUN_ID.trim();
+    return payload;
+}
+/**
+ * Spawn the Python judgment module and resolve with the validated response.
+ * Rejects with a sanitized {@link SupervisorJudgmentError} on any boundary
+ * failure. The request is passed over stdin (keeping payloads out of the process
+ * argument list); the timeout is `config.llm_timeout_ms`.
+ */
+export function requestPythonSupervisorJudgment(request, config, deps = {}) {
+    const spawnFn = deps.spawn ?? nodeSpawn;
+    const env = deps.env ?? process.env;
+    const command = resolveSupervisorJudgmentCommand(env);
+    const cwd = resolveSupervisorJudgmentCwd(env);
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        let stdout = "";
+        let child;
+        try {
+            child = spawnFn(command, ["-m", SUPERVISOR_JUDGMENT_PYTHON_MODULE], {
+                cwd,
+                shell: false,
+                stdio: ["pipe", "pipe", "pipe"],
+            });
+        }
+        catch {
+            reject(new SupervisorJudgmentError("python judgment process could not be started"));
+            return;
+        }
+        const finish = (fn, value) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            fn(value);
+        };
+        // NOTE: the timer is intentionally NOT unref'd. It must keep the event loop
+        // alive so the timeout actually fires and rejects when the Python subprocess
+        // hangs (and so the deterministic degraded path is taken). The timer is
+        // always cleared in `finish`, so it never outlives a settled judgment.
+        const timer = setTimeout(() => {
+            try {
+                child.kill("SIGKILL");
+            }
+            catch {
+                /* best-effort */
+            }
+            finish(reject, new SupervisorJudgmentError("python judgment timed out"));
+        }, config.llm_timeout_ms);
+        child.on("error", () => finish(reject, new SupervisorJudgmentError("python judgment process error")));
+        child.stdout?.on("data", (chunk) => {
+            stdout += String(chunk);
+        });
+        child.on("close", (code) => {
+            if (code !== 0) {
+                finish(reject, new SupervisorJudgmentError("python judgment exited non-zero"));
+                return;
+            }
+            try {
+                const parsed = parseSupervisorJudgmentResponse(stdout.trim());
+                finish(resolve, parsed);
+            }
+            catch {
+                finish(reject, new SupervisorJudgmentError("python judgment returned malformed output"));
+            }
+        });
+        try {
+            child.stdin?.write(JSON.stringify(buildRequestPayload(request, env)));
+            child.stdin?.end();
+        }
+        catch {
+            finish(reject, new SupervisorJudgmentError("python judgment stdin write failed"));
+        }
+    });
+}
+/**
+ * Build the default injectable judgment client used by the runtime. The returned
+ * function matches {@link SupervisorJudgmentClient}; it forwards each request to
+ * {@link requestPythonSupervisorJudgment} with the resolved config/deps.
+ */
+export function createDefaultSupervisorJudgmentClient(config, deps = {}) {
+    return (request) => requestPythonSupervisorJudgment(request, config, deps);
+}