rivet-design 0.14.9 → 0.14.11

package/dist/agent-variants/workerRuntime.js

@@ -0,0 +1,705 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.describeWorkerRuntimeDecision = exports.WorkerRuntimeResolver = exports.adapterForVendor = exports.makeCursorAdapter = exports.parseCursorWorkerResult = exports.makeCodexAdapter = exports.makeClaudeAdapter = exports.parseCodexWorkerResult = exports.parseClaudeWorkerResult = exports.PREFLIGHT_TIERS = exports.EXECUTOR_FIDELITY_TIERS = void 0;
+const child_process_1 = require("child_process");
+const os_1 = __importDefault(require("os"));
+const logger_1 = require("../utils/logger");
+const hostAgentEnv_1 = require("../utils/hostAgentEnv");
+const runnerSelection_1 = require("../cli/runnerSelection");
+const workerDefaults_1 = require("../hosts/workerDefaults");
+const log = (0, logger_1.createLogger)('WorkerRuntime');
+/**
+ * Fidelity → tier, per vendor. Claude mirrors the host registry (one model,
+ * effort varies — PR #965). Codex maps fidelity onto reasoning effort, its
+ * native analogue. Cursor cannot vary quality per invocation, so fidelity is
+ * intentionally a no-op there until a per-model benchmark says otherwise.
+ */
+exports.EXECUTOR_FIDELITY_TIERS = {
+    claude: {
+        low: { vendor: 'claude', ...workerDefaults_1.FIDELITY_WORKER_TIERS.low },
+        medium: { vendor: 'claude', ...workerDefaults_1.FIDELITY_WORKER_TIERS.medium },
+        high: { vendor: 'claude', ...workerDefaults_1.FIDELITY_WORKER_TIERS.high },
+    },
+    codex: {
+        low: { vendor: 'codex', reasoningEffort: 'low' },
+        medium: { vendor: 'codex', reasoningEffort: 'medium' },
+        high: { vendor: 'codex', reasoningEffort: 'high' },
+    },
+    cursor: {
+        low: { vendor: 'cursor' },
+        medium: { vendor: 'cursor' },
+        high: { vendor: 'cursor' },
+    },
+};
+/** Cheapest valid tier per vendor — what the preflight probe runs with. Same
+ *  flags as a real worker (the probe must test the exact invocation), minimum
+ *  spend. */
+exports.PREFLIGHT_TIERS = {
+    claude: exports.EXECUTOR_FIDELITY_TIERS.claude.low,
+    codex: exports.EXECUTOR_FIDELITY_TIERS.codex.low,
+    cursor: exports.EXECUTOR_FIDELITY_TIERS.cursor.low,
+};
+const requireVendorTier = (tier, vendor) => {
+    if (tier.vendor !== vendor) {
+        throw new Error(`executor tier/adapter mismatch: ${tier.vendor} tier handed to ${vendor} adapter`);
+    }
+    return tier;
+};
+/** Claude's `--output-format json`: one trailing JSON result object. */
+const parseClaudeWorkerResult = (stdout) => {
+    try {
+        const trimmed = stdout.trim();
+        const start = trimmed.indexOf('{');
+        if (start === -1)
+            return {};
+        const parsed = JSON.parse(trimmed.slice(start));
+        const sum = (...values) => values.reduce((total, value) => total + (typeof value === 'number' ? value : 0), 0);
+        const usage = parsed.usage;
+        const errorParts = [parsed.subtype, parsed.result, parsed.error]
+            .filter((value) => typeof value === 'string')
+            .join(': ');
+        return {
+            ...(usage || typeof parsed.total_cost_usd === 'number'
+                ? {
+                    usage: {
+                        ...(usage
+                            ? {
+                                tokensIn: sum(usage.input_tokens, usage.cache_read_input_tokens, usage.cache_creation_input_tokens),
+                                tokensOut: sum(usage.output_tokens),
+                            }
+                            : {}),
+                        ...(typeof parsed.total_cost_usd === 'number'
+                            ? { costUsd: parsed.total_cost_usd }
+                            : {}),
+                    },
+                }
+                : {}),
+            ...(errorParts.length > 0 ? { resultText: errorParts } : {}),
+            ...(typeof parsed.api_error_status === 'number'
+                ? { apiErrorStatus: parsed.api_error_status }
+                : {}),
+        };
+    }
+    catch {
+        return {};
+    }
+};
+exports.parseClaudeWorkerResult = parseClaudeWorkerResult;
+/** Codex's `exec --json`: JSONL events. Usage rides `turn.completed`; failures
+ *  surface as `item.completed` items of type `error` (and `turn.failed`). */
+const parseCodexWorkerResult = (stdout) => {
+    const info = {};
+    const errors = [];
+    for (const line of stdout.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed.startsWith('{'))
+            continue;
+        try {
+            const event = JSON.parse(trimmed);
+            if (event.type === 'turn.completed' && event.usage) {
+                info.usage = {
+                    tokensIn: event.usage.input_tokens ?? 0,
+                    tokensOut: (event.usage.output_tokens ?? 0) +
+                        (event.usage.reasoning_output_tokens ?? 0),
+                };
+            }
+            if (event.type === 'item.completed' &&
+                event.item?.type === 'error' &&
+                typeof event.item.message === 'string') {
+                errors.push(event.item.message);
+            }
+            if (event.type === 'turn.failed' || event.type === 'error') {
+                const message = typeof event.error === 'string' ? event.error : event.error?.message;
+                if (message)
+                    errors.push(message);
+            }
+        }
+        catch {
+            // Interleaved non-JSON log lines are expected; skip them.
+        }
+    }
+    if (errors.length > 0)
+        info.resultText = errors.join(': ');
+    return info;
+};
+exports.parseCodexWorkerResult = parseCodexWorkerResult;
+const makeClaudeAdapter = (binary = 'claude') => ({
+    vendor: 'claude',
+    binary,
+    promptDelivery: 'stdin',
+    buildArgs(tier) {
+        const claudeTier = requireVendorTier(tier, 'claude');
+        return [
+            '--print',
+            '--output-format',
+            'json',
+            '--model',
+            claudeTier.model,
+            '--effort',
+            claudeTier.effort,
+            '--dangerously-skip-permissions',
+            '--allowed-tools',
+            'Read,Write,Edit,Bash,Glob,Grep',
+            '--exclude-dynamic-system-prompt-sections',
+        ];
+    },
+    parseResult: exports.parseClaudeWorkerResult,
+    supportsModelFallback: true,
+    // Strip nested-session markers: a `claude` worker spawned from a server
+    // that was itself started inside a Claude Code session would otherwise hit
+    // the refuse-to-nest guard (see hostAgentEnv.ts).
+    spawnEnv: () => (0, hostAgentEnv_1.sanitizeHostAgentEnv)(process.env),
+});
+exports.makeClaudeAdapter = makeClaudeAdapter;
+const makeCodexAdapter = (binary = runnerSelection_1.RUNNER_VENDOR_BINARIES.codex) => ({
+    vendor: 'codex',
+    binary,
+    promptDelivery: 'stdin',
+    buildArgs(tier) {
+        const codexTier = requireVendorTier(tier, 'codex');
+        return [
+            'exec',
+            '--json',
+            '--skip-git-repo-check',
+            // Same posture as claude's --dangerously-skip-permissions; the worker
+            // is already confined to its own workspace by the briefing contract.
+            '--dangerously-bypass-approvals-and-sandbox',
+            ...(codexTier.model ? ['--model', codexTier.model] : []),
+            '-c',
+            `model_reasoning_effort=${codexTier.reasoningEffort}`,
+            '-',
+        ];
+    },
+    parseResult: exports.parseCodexWorkerResult,
+    supportsModelFallback: false,
+    spawnEnv: () => process.env,
+});
+exports.makeCodexAdapter = makeCodexAdapter;
+/** Cursor's `-p --output-format json`: one trailing JSON result object, like
+ *  claude's — but usage keys are camelCase (`inputTokens`) and `subtype`/
+ *  `result` are populated on success too ("success"/"ok"), so error text is
+ *  taken only when `is_error` is set. Shape live-verified 2026-07-23 against
+ *  cursor-agent 2026.07.23-e383d2b. */
+const parseCursorWorkerResult = (stdout) => {
+    try {
+        const trimmed = stdout.trim();
+        const start = trimmed.indexOf('{');
+        if (start === -1)
+            return {};
+        const parsed = JSON.parse(trimmed.slice(start));
+        const sum = (...values) => values.reduce((total, value) => total + (typeof value === 'number' ? value : 0), 0);
+        const usage = parsed.usage;
+        const errorParts = parsed.is_error === true
+            ? [parsed.subtype, parsed.result]
+                .filter((value) => typeof value === 'string')
+                .join(': ')
+            : '';
+        return {
+            ...(usage
+                ? {
+                    usage: {
+                        tokensIn: sum(usage.inputTokens, usage.cacheReadTokens, usage.cacheWriteTokens),
+                        tokensOut: sum(usage.outputTokens),
+                    },
+                }
+                : {}),
+            ...(errorParts.length > 0 ? { resultText: errorParts } : {}),
+        };
+    }
+    catch {
+        return {};
+    }
+};
+exports.parseCursorWorkerResult = parseCursorWorkerResult;
+const makeCursorAdapter = (binary = runnerSelection_1.RUNNER_VENDOR_BINARIES.cursor) => ({
+    vendor: 'cursor',
+    binary,
+    // cursor-agent's print mode does not read the prompt from stdin — it goes
+    // in argv. Briefings are ~16-20KB, well inside ARG_MAX.
+    promptDelivery: 'argv',
+    buildArgs(tier) {
+        const cursorTier = requireVendorTier(tier, 'cursor');
+        return [
+            '-p',
+            '--output-format',
+            'json',
+            ...(cursorTier.model ? ['-m', cursorTier.model] : []),
+            '--force',
+        ];
+    },
+    parseResult: exports.parseCursorWorkerResult,
+    supportsModelFallback: false,
+    spawnEnv: () => process.env,
+});
+exports.makeCursorAdapter = makeCursorAdapter;
+const adapterForVendor = (vendor, binaryOverride) => {
+    switch (vendor) {
+        case 'claude':
+            return (0, exports.makeClaudeAdapter)(binaryOverride);
+        case 'codex':
+            return (0, exports.makeCodexAdapter)(binaryOverride);
+        case 'cursor':
+            return (0, exports.makeCursorAdapter)(binaryOverride);
+    }
+};
+exports.adapterForVendor = adapterForVendor;
+const PREFLIGHT_PROMPT = 'Reply with the single word: ok. Do not use any tools.';
+const DEFAULT_PREFLIGHT_TIMEOUT_MS = 30_000;
+/** Vendor selections arrive as user-typed strings (config file, env var) —
+ *  trim and case-fold before matching so `"Claude "` or `CODEX` still select
+ *  the vendor instead of silently falling through to PATH probing. */
+const asExecutableVendor = (value) => {
+    if (typeof value !== 'string')
+        return undefined;
+    const normalized = value.trim().toLowerCase();
+    return runnerSelection_1.EXECUTABLE_RUNNER_VENDORS.includes(normalized)
+        ? normalized
+        : undefined;
+};
+/** Strip ANSI escapes / control characters so a TUI splash (cursor-agent's
+ *  sign-in banner renders box art to stdout) reads as one diagnosable line. */
+const sanitizeProbeText = (text) => text
+    // eslint-disable-next-line no-control-regex
+    .replace(/\u001b\][^\u0007]*(?:\u0007|\u001b\\)/g, '')
+    // eslint-disable-next-line no-control-regex
+    .replace(/\u001b\[[0-9;?]*[a-zA-Z]/g, '')
+    // eslint-disable-next-line no-control-regex
+    .replace(/[\u0000-\u0008\u000b-\u001f\u007f]/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+/** An installed-but-logged-out CLI is the common first-run state (the CLI
+ *  login is separate from the IDE's). Every vendor prints some "sign in"
+ *  variant; match it so the degrade message says what to actually do. */
+const LOGIN_MARKERS = /sign[ -]?in|not logged in|not signed in|unauthenticated|not authenticated|authentication required|invalid api key|please run \/login|401/i;
+const VENDOR_LOGIN_HINTS = {
+    claude: 'not logged in — run /login inside `claude`',
+    codex: 'not logged in — run `codex login`',
+    cursor: 'not logged in — run `cursor-agent login`',
+};
+/** Health-cache identity of one probe: same vendor with a different binary or
+ *  resolved model is a different runtime and must preflight independently.
+ *  Request-PINNED probes get their own identity too: they run without the
+ *  fallback-model rung, so their verdicts and ordinary (fallback-eligible)
+ *  verdicts are not interchangeable in either direction — a pinned request
+ *  must not ride a fallback-earned healthy, and an ordinary resolve must not
+ *  join a pinned probe and lose its fallback rung. Distinct keys make both
+ *  impossible and remove any in-flight sharing between the two modes. */
+const probeCacheKey = (adapter, tier, requestPinnedModel) => `${adapter.vendor}|${adapter.binary}|${'model' in tier && tier.model ? tier.model : 'default'}${requestPinnedModel ? '|pinned' : ''}`;
+const defaultPreflightSpawn = ({ command, args, cwd, env }) => (0, child_process_1.spawn)(command, args, {
+    cwd,
+    env,
+    stdio: ['pipe', 'pipe', 'pipe'],
+    detached: process.platform !== 'win32',
+});
+const killProcessTree = (pid) => {
+    if (!pid)
+        return;
+    try {
+        if (process.platform === 'win32') {
+            process.kill(pid, 'SIGKILL');
+            return;
+        }
+        process.kill(-pid, 'SIGKILL');
+    }
+    catch {
+        try {
+            process.kill(pid, 'SIGKILL');
+        }
+        catch {
+            // Already gone.
+        }
+    }
+};
+/**
+ * Resolves and preflights the executor's worker runtime, per request.
+ *
+ * Precedence: env override (`RIVET_EXECUTOR_VENDOR`, or legacy
+ * `RIVET_EXECUTOR_COMMAND` = claude-grammar custom binary) > user config
+ * `workerVendor` > the request initiator's agent > (human / no preference)
+ * probe installed vendors in registry order.
+ *
+ * Note this is deliberately PER-REQUEST, unlike apply-runner resolution
+ * (`resolveRunner`, fixed for the server's lifetime): one live session can
+ * serve requests initiated by different agents, and each request's workers
+ * should run on its initiator's runtime.
+ *
+ * Preflight lifecycle: one in-flight probe per runtime identity (vendor +
+ * binary + resolved model — concurrent resolves join it); a healthy result
+ * is cached until a runtime-shaped worker failure invalidates it
+ * (`markUnhealthy`) or a config edit changes the resolved model; an
+ * unhealthy result is re-probed on the next resolve — so a user who fixes
+ * their auth is not stuck on the host path, and each new run retries a
+ * broken vendor at most once.
+ */
+class WorkerRuntimeResolver {
+    options;
+    health = new Map();
+    inFlight = new Map();
+    constructor(options = {}) {
+        this.options = options;
+    }
+    /** Invalidate a cached-healthy vendor after a runtime-shaped worker failure
+     *  (spawn error, unknown CLI option, auth rejection) so the next run
+     *  re-probes instead of leasing four more items to a dead runtime. */
+    markUnhealthy(vendor, reason) {
+        for (const key of this.health.keys()) {
+            if (key.startsWith(`${vendor}|`)) {
+                this.health.set(key, {
+                    healthy: false,
+                    reason,
+                    category: 'worker_failure',
+                });
+            }
+        }
+        log.warn(`worker runtime ${vendor} marked unhealthy: ${reason}`);
+    }
+    async resolve(args) {
+        const { candidates, source, strict } = this.candidatesFor(args?.initiator, args?.selection);
+        const diagnostics = [];
+        for (const candidate of candidates) {
+            // The request model pin binds to ONE runtime: the requested provider,
+            // or — for a model-only request — the primary candidate the request
+            // resolved against. Fallback / later probe-path candidates are probed
+            // (and would run) without it: another CLI's model id is meaningless
+            // there, and a silent re-target would hand the user a runtime they
+            // didn't pick. When the RIVET_EXECUTOR_MODEL ops escape hatch is set,
+            // the pin is inert (the env model is what preflights and runs), so it
+            // must not travel as modelOverride — that would disable the ops
+            // model-fallback rung over a pin that is not even in effect.
+            const envModel = (this.options.env ?? process.env).RIVET_EXECUTOR_MODEL;
+            const modelPinApplies = Boolean(!envModel &&
+                args?.selection?.model &&
+                (args.selection.provider
+                    ? args.selection.provider === candidate.vendor
+                    : candidate === candidates[0]));
+            const outcome = await this.preflight(candidate, args?.signal, modelPinApplies ? args?.selection : undefined);
+            if (outcome.healthy) {
+                return {
+                    mode: 'executor',
+                    adapter: candidate,
+                    // A strict resolution that lands on a non-primary candidate got
+                    // there via the cross-vendor fallback opt-in — label it as such.
+                    source: strict && candidate !== candidates[0] ? 'fallback' : source,
+                    ...(modelPinApplies ? { modelOverride: args.selection.model } : {}),
+                };
+            }
+            diagnostics.push({
+                vendor: candidate.vendor,
+                binary: candidate.binary,
+                reason: outcome.reason,
+            });
+            if (strict && !(this.options.crossVendorFallback?.() ?? false))
+                break;
+        }
+        return { mode: 'host', diagnostics };
+    }
+    /** Candidate adapters in trial order, plus whether the choice was explicit
+     *  (strict = unhealthy means host path, not another vendor). */
+    candidatesFor(initiator, selection) {
+        const env = this.options.env ?? process.env;
+        const probe = this.options.binaryProbe ?? runnerSelection_1.isBinaryOnPath;
+        // Legacy ops escape hatch: a custom command is assumed claude-grammar.
+        const legacyCommand = env.RIVET_EXECUTOR_COMMAND;
+        if (legacyCommand) {
+            return {
+                candidates: [(0, exports.makeClaudeAdapter)(legacyCommand)],
+                source: 'env',
+                strict: true,
+            };
+        }
+        const envVendor = asExecutableVendor(env.RIVET_EXECUTOR_VENDOR);
+        if (envVendor) {
+            return {
+                candidates: this.withFallbackCandidates(envVendor, probe),
+                source: 'env',
+                strict: true,
+            };
+        }
+        // Explicit per-request choice: the user's live intent ("--worker-provider
+        // claude" relayed by the host agent) beats a sticky config default, and
+        // only the ops env escape hatches beat it. Strict like every explicit
+        // choice — an unhealthy selection lands on the host path with the reason.
+        const requested = asExecutableVendor(selection?.provider);
+        if (requested) {
+            return {
+                candidates: this.withFallbackCandidates(requested, probe),
+                source: 'request',
+                strict: true,
+            };
+        }
+        const configured = asExecutableVendor(this.options.configuredVendor?.());
+        if (configured) {
+            return {
+                candidates: this.withFallbackCandidates(configured, probe),
+                source: 'user_config',
+                strict: true,
+            };
+        }
+        const initiatorVendor = initiator?.kind === 'agent'
+            ? asExecutableVendor(initiator.agent)
+            : undefined;
+        if (initiatorVendor) {
+            // Strict even when the initiator's CLI is not installed: the missing
+            // binary fails preflight and the request degrades to the host path —
+            // never to another vendor's CLI without the fallback opt-in.
+            return {
+                candidates: this.withFallbackCandidates(initiatorVendor, probe),
+                source: 'initiator',
+                strict: true,
+            };
+        }
+        // Human request / unknown agent: no prior vendor expectation exists, so
+        // probing across installed vendors is fine.
+        return {
+            candidates: runnerSelection_1.EXECUTABLE_RUNNER_VENDORS.filter((vendor) => probe(runnerSelection_1.RUNNER_VENDOR_BINARIES[vendor])).map((vendor) => this.adapterFor(vendor)),
+            source: 'probe',
+            strict: false,
+        };
+    }
+    withFallbackCandidates(vendor, probe) {
+        const primary = this.adapterFor(vendor);
+        if (!(this.options.crossVendorFallback?.() ?? false))
+            return [primary];
+        const rest = runnerSelection_1.EXECUTABLE_RUNNER_VENDORS.filter((candidate) => candidate !== vendor && probe(runnerSelection_1.RUNNER_VENDOR_BINARIES[candidate])).map((candidate) => this.adapterFor(candidate));
+        return [primary, ...rest];
+    }
+    adapterFor(vendor) {
+        return (0, exports.adapterForVendor)(vendor);
+    }
+    /** Tier the probe runs with — cheapest per vendor, with the same model
+     *  override precedence a real worker gets (`RIVET_EXECUTOR_MODEL` env >
+     *  request `--worker-model` > `workerModels.<vendor>` config) so the probe
+     *  exercises the exact model a real worker would run, not the CLI
+     *  default. */
+    probeTierFor(adapter, selection) {
+        const base = exports.PREFLIGHT_TIERS[adapter.vendor];
+        const env = this.options.env ?? process.env;
+        // The request model applies only to the vendor it was requested with —
+        // probing a cross-vendor fallback candidate with another CLI's model id
+        // would wrongly fail the fallback.
+        const requestModel = selection?.model &&
+            (!selection.provider || selection.provider === adapter.vendor)
+            ? selection.model
+            : undefined;
+        const model = env.RIVET_EXECUTOR_MODEL ??
+            requestModel ??
+            this.options.configuredModelFor?.(adapter.vendor);
+        return model ? { ...base, model } : base;
+    }
+    async preflight(adapter, signal, selection) {
+        const tier = this.probeTierFor(adapter, selection);
+        // Cache key includes the binary and resolved model, not just the vendor:
+        // `workerModels.<vendor>` is read lazily, so a config edit while the
+        // server is live must re-probe rather than ride a stale healthy result
+        // for a model preflight never exercised.
+        // A request-pinned model must never silently degrade: if the user asked
+        // for a specific model and it fails preflight, the honest outcome is
+        // unhealthy (→ host path with the reason), not a fallback-model run the
+        // user didn't pick. resolve() only passes `selection` through when the
+        // pin applies to this adapter, so its presence is the signal. Pinned
+        // probes carry their own cache identity (see probeCacheKey), so pinned
+        // and ordinary resolves never share verdicts or in-flight probes.
+        const requestPinnedModel = Boolean(selection?.model);
+        const key = probeCacheKey(adapter, tier, requestPinnedModel);
+        const cached = this.health.get(key);
+        // Healthy results are reused; unhealthy results are re-probed (each new
+        // resolve gives a fixed vendor one fresh chance).
+        if (cached?.healthy)
+            return cached;
+        const inFlight = this.inFlight.get(key);
+        if (inFlight)
+            return inFlight;
+        const startedAt = Date.now();
+        const probePromise = (requestPinnedModel
+            ? this.runProbe(adapter, tier, signal)
+            : this.probeWithModelFallback(adapter, tier, signal))
+            .then((outcome) => {
+            this.health.set(key, outcome);
+            // Telemetry gets the coarse category only: the raw reason is built
+            // from stderr/spawn errors and can carry local paths or account
+            // fragments. Full detail stays in server.log and run feedback.
+            this.options.telemetry?.track('agent_variants.executor_preflight', {
+                source: 'mcp',
+                vendor: adapter.vendor,
+                healthy: outcome.healthy,
+                durationMs: Date.now() - startedAt,
+                reason: outcome.healthy ? null : outcome.category,
+            });
+            if (!outcome.healthy) {
+                log.warn(`worker runtime preflight failed for ${adapter.vendor} ` +
+                    `(${adapter.binary}): ${outcome.reason}`);
+            }
+            return outcome;
+        })
+            .finally(() => {
+            this.inFlight.delete(key);
+        });
+        this.inFlight.set(key, probePromise);
+        return probePromise;
+    }
+    /** One probe — plus, for claude (the only vendor with a structured
+     *  fallback-model rung), a second probe on the fallback model when the
+     *  primary MODEL is what failed. A healthy fallback probe marks the
+     *  runtime healthy under the primary identity: real workers still start
+     *  on the primary tier and degrade per item via the executor's one-shot
+     *  fallback retry, exactly the pre-preflight behavior. */
+    async probeWithModelFallback(adapter, tier, signal) {
+        const outcome = await this.runProbe(adapter, tier, signal);
+        const fallback = this.options.probeModelFallback;
+        if (outcome.healthy ||
+            !fallback ||
+            !adapter.supportsModelFallback ||
+            outcome.category !== 'exit_nonzero') {
+            return outcome;
+        }
+        const primaryModel = 'model' in tier ? tier.model : undefined;
+        const fallbackModel = fallback.fallbackModel();
+        if (!primaryModel ||
+            !fallbackModel ||
+            fallbackModel === primaryModel ||
+            !fallback.isModelAvailabilityFailure({
+                message: outcome.reason,
+                ...(outcome.apiErrorStatus !== undefined
+                    ? { apiErrorStatus: outcome.apiErrorStatus }
+                    : {}),
+                model: primaryModel,
+            })) {
+            return outcome;
+        }
+        log.warn(`worker runtime preflight: ${adapter.vendor} model '${primaryModel}' ` +
+            `unavailable — probing fallback model '${fallbackModel}'`);
+        const fallbackOutcome = await this.runProbe(adapter, { ...tier, model: fallbackModel }, signal);
+        return fallbackOutcome.healthy ? fallbackOutcome : outcome;
+    }
+    runProbe(adapter, tier, signal) {
+        const timeoutMs = this.options.probeTimeoutMs ??
+            Number((this.options.env ?? process.env)
+                .RIVET_EXECUTOR_PREFLIGHT_TIMEOUT_MS ?? DEFAULT_PREFLIGHT_TIMEOUT_MS);
+        const spawnProbe = this.options.spawnProbe ?? defaultPreflightSpawn;
+        const args = adapter.buildArgs(tier);
+        if (adapter.promptDelivery === 'argv')
+            args.push(PREFLIGHT_PROMPT);
+        return new Promise((resolve) => {
+            // A signal that aborted before we attached would otherwise leave the
+            // probe running to its full timeout — check up front.
+            if (signal?.aborted) {
+                resolve({
+                    healthy: false,
+                    reason: 'probe aborted (run cancelled)',
+                    category: 'aborted',
+                });
+                return;
+            }
+            let child;
+            try {
+                child = spawnProbe({
+                    command: adapter.binary,
+                    args,
+                    cwd: os_1.default.tmpdir(),
+                    env: adapter.spawnEnv(),
+                });
+            }
+            catch (error) {
+                resolve({
+                    healthy: false,
+                    reason: error instanceof Error ? error.message : String(error),
+                    category: 'spawn_error',
+                });
+                return;
+            }
+            let settled = false;
+            let stderrTail = '';
+            let stdoutTail = '';
+            const settle = (outcome) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                signal?.removeEventListener('abort', onAbort);
+                resolve(outcome);
+            };
+            const onAbort = () => {
+                killProcessTree(child.pid);
+                settle({
+                    healthy: false,
+                    reason: 'probe aborted (run cancelled)',
+                    category: 'aborted',
+                });
+            };
+            const timer = setTimeout(() => {
+                killProcessTree(child.pid);
+                settle({
+                    healthy: false,
+                    reason: `probe timed out after ${timeoutMs}ms`,
+                    category: 'timeout',
+                });
+            }, timeoutMs);
+            // Note: a dedup-shared probe can be aborted by the first joiner's
+            // signal. Accepted: the outcome is cached as unhealthy and the next
+            // resolve re-probes.
+            signal?.addEventListener('abort', onAbort, { once: true });
+            child.stderr?.on('data', (chunk) => {
+                stderrTail = (stderrTail + chunk.toString()).slice(-2000);
+            });
+            child.stdout?.on('data', (chunk) => {
+                stdoutTail = (stdoutTail + chunk.toString()).slice(-16384);
+            });
+            child.on('error', (error) => {
+                settle({ healthy: false, reason: error.message, category: 'spawn_error' });
+            });
+            child.on('close', (code) => {
+                if (code === 0) {
+                    settle({ healthy: true });
+                    return;
+                }
+                const { resultText, apiErrorStatus } = adapter.parseResult(stdoutTail);
+                const stderrDetail = sanitizeProbeText(stderrTail);
+                // A logged-out CLI often reports nothing on stderr and no parseable
+                // result — just a sign-in splash on stdout. Fall back to that tail
+                // so the reason is never an empty "probe exited 1: ".
+                const stdoutDetail = sanitizeProbeText(stdoutTail);
+                const detail = stderrDetail || (resultText ? '' : stdoutDetail);
+                const loginRequired = LOGIN_MARKERS.test(`${stderrDetail}\n${resultText ?? ''}\n${stdoutDetail}`);
+                // Once diagnosed as a login problem the hint IS the reason — the raw
+                // output is a sign-in banner (ASCII art on cursor-agent) that only
+                // buries the actionable part.
+                settle(loginRequired
+                    ? {
+                        healthy: false,
+                        category: 'login_required',
+                        reason: `${adapter.binary} is ${VENDOR_LOGIN_HINTS[adapter.vendor]} (probe exited ${code})`,
+                    }
+                    : {
+                        healthy: false,
+                        category: 'exit_nonzero',
+                        ...(apiErrorStatus !== undefined ? { apiErrorStatus } : {}),
+                        reason: `probe exited ${code}: ${detail.slice(-400)}${resultText ? ` | result: ${resultText.slice(-500)}` : ''}`,
+                    });
+            });
+            // Always close stdin: argv-delivery CLIs (cursor-agent print mode) can
+            // block on an open stdin pipe — the real worker spawn ends stdin
+            // unconditionally for the same reason.
+            if (adapter.promptDelivery === 'stdin') {
+                child.stdin?.write(PREFLIGHT_PROMPT);
+            }
+            child.stdin?.end();
+        });
+    }
+}
+exports.WorkerRuntimeResolver = WorkerRuntimeResolver;
+/** One-line human summary of a decision, for run feedback and server.log:
+ *  `codex` / `host path (claude: probe exited 1: …)`. */
+const describeWorkerRuntimeDecision = (decision) => {
+    if (decision.mode === 'executor') {
+        return decision.adapter.vendor;
+    }
+    const reasons = decision.diagnostics
+        .map((d) => `${d.vendor}: ${d.reason}`)
+        .join('; ');
+    return `host path${reasons ? ` (${reasons})` : ' (no worker runtime installed)'}`;
+};
+exports.describeWorkerRuntimeDecision = describeWorkerRuntimeDecision;
+//# sourceMappingURL=workerRuntime.js.map