castle-web-cli 0.4.82 → 0.4.84

package/dist/agent.js

@@ -22,6 +22,8 @@ import { nanoid } from "nanoid";
 import { WebSocketServer } from "ws";
 import { rawDataToString } from "./ide.js";
 import { buildRouterPrompt, buildTaskPrompt, userTurnInstruction, CLAUDE_TASK_SYSTEM_REMINDER, } from "./agent-prompts.js";
+import { checkOpenrouterKey, checkOpenrouterModel, openrouterCatalogEntry, primeOpenrouterCatalog, } from "./openrouter-catalog.js";
+import { classifyProviderError, failureCopy, } from "./agent-failures.js";
 import { runAgentNative } from "./native/loop.js";
 import { createPlaytestBrowserManager } from "./native/playtest-browser.js";
 import { createPlaywrightPlaytestExecutor } from "./native/playtest-executor.js";
@@ -30,16 +32,38 @@ export const AGENT_ATTACHMENT_PREFIX = "/__castle/agent/attachments/";
 // Playtest frame PNGs (tasks/<id>/playtest/<file>.png), served for the
 // finished-task card's thumbnails -- see makePlaytestFrameHandler.
 export const AGENT_PLAYTEST_PREFIX = "/__castle/agent/playtest/";
+// Same-origin proxy for OpenRouter model capabilities (avoids browser CORS
+// against openrouter.ai). GET ?model=<slug> -> ModelCaps JSON. Powers the
+// settings popover's dynamic reasoning-effort / provider-tier pickers.
+export const AGENT_MODEL_CAPS_PREFIX = "/__castle/agent/model-caps";
 const DEFAULT_SETTINGS = {
     router: "claude",
     tasks: "claude",
     routerClaudeModel: "opus",
     // Tasks default one tier down: task agents run long unattended builds, so
-    // sonnet's cost/speed wins by default; the conductor stays on opus.
+    // sonnet's cost/speed wins by default; the operator stays on opus.
     tasksClaudeModel: "sonnet",
     // Free-form -- change to any OpenRouter slug.
     routerOpenrouterModel: "openai/gpt-5.6-sol",
     tasksOpenrouterModel: "openai/gpt-5.6-terra",
+    // Both roles think at "medium": the operator stays snappy (the user waits
+    // on every operator turn), and task agents' multi-turn tool loops don't pay
+    // reasoning tax on mechanical read/edit/run turns. Deep decomposition
+    // quality comes from the operator prompt, not a higher effort default.
+    routerReasoningEffort: "medium",
+    tasksReasoningEffort: "medium",
+    // Routing splits by what each role optimizes for: the interactive operator
+    // routes for speed (nitro = throughput-sorted endpoints), unattended task
+    // agents route for correctness (exacto = benchmark-accurate endpoints,
+    // which matters for tool-calling fidelity over long loops).
+    routerRouting: "nitro",
+    tasksRouting: "exacto",
+    // Operator pins OpenAI's priority (low-latency SLA) tier for the default
+    // sol model; harmless with other slugs since the pin falls back when the
+    // tag doesn't exist (allow_fallbacks). Tasks stay on auto: high-volume
+    // background turns should ride the cheapest available capacity.
+    routerProviderTier: "openai/priority",
+    tasksProviderTier: "",
 };
 function normalizeBackend(value) {
     return value === "cursor" || value === "claude" || value === "smith"
@@ -73,12 +97,65 @@ function normalizeOpenrouterModel(value) {
     const trimmed = value.trim();
     return trimmed && trimmed.length <= OPENROUTER_MODEL_MAX_LEN ? trimmed : null;
 }
+// OpenRouter's full effort superset -- validated against the union rather than
+// a per-model list because supported efforts are model-specific (the client
+// fetches them from the model-caps endpoint to build the picker) and
+// OpenRouter maps an unsupported level to the nearest one anyway.
+const REASONING_EFFORTS = [
+    "none",
+    "minimal",
+    "low",
+    "medium",
+    "high",
+    "xhigh",
+    "max",
+];
+function normalizeReasoningEffort(value) {
+    return REASONING_EFFORTS.includes(value)
+        ? value
+        : null;
+}
+const ROUTING_MODES = [
+    "balanced",
+    "nitro",
+    "exacto",
+    "floor",
+];
+function normalizeRoutingMode(value) {
+    return ROUTING_MODES.includes(value)
+        ? value
+        : null;
+}
+// Provider tier is an OpenRouter endpoint `tag` ("openai/flex", "azure/eu",
+// ...) which is model-specific, so validation is loose like the model slug.
+// Unlike the slug, empty string is VALID and meaningful: "auto" (no pin), so
+// this returns "" rather than null for the clear case -- callers must treat
+// null (invalid) and "" (clear) differently.
+function normalizeProviderTier(value) {
+    if (typeof value !== "string")
+        return null;
+    const trimmed = value.trim();
+    if (trimmed.length > OPENROUTER_MODEL_MAX_LEN)
+        return null;
+    return trimmed;
+}
 // OpenRouter's Anthropic-compatible endpoint (confirmed current, 2026: it
 // accepts the standard Anthropic Messages API shape -- text/tool-use/
 // extended-thinking -- for ANY OpenRouter model slug, not just Anthropic
 // ones). Using it directly means claude CLI's OWN stream-json + tool loop
 // talks to OpenRouter with zero translation layer -- no proxy needed.
 const OPENROUTER_BASE_URL = "https://openrouter.ai/api";
+// Anthropic credential sources the claude CLI will fall back to on its own.
+// This env points the CLI at a THIRD PARTY, so every one of these has to be
+// cleared or that third party receives the user's Anthropic credential. Note
+// there is no file to check for here: on macOS the CLI reads a saved login
+// from the Keychain, so `~/.claude/.credentials.json` can be absent while the
+// CLI is still perfectly able to authenticate as the user.
+const ANTHROPIC_CREDENTIAL_ENV = [
+    "ANTHROPIC_API_KEY",
+    "ANTHROPIC_AUTH_TOKEN_HELPER",
+    "CLAUDE_CODE_OAUTH_TOKEN",
+];
 // Env for a claude CLI spawn routed at OpenRouter (claudeModel "openrouter",
 // Path A). Two things make this deterministic regardless of the user's own
 // Anthropic auth (verified live against the real `claude` binary while
@@ -95,16 +172,29 @@ const OPENROUTER_BASE_URL = "https://openrouter.ai/api";
 // slug like "openai/gpt-5.1" 404s with a synthetic "model_not_found" and
 // NEVER reaches the network. Setting it makes the CLI accept any --model
 // string and actually send the request upstream.
-function envForOpenrouterSpawn() {
+//
+// `apiKey` is REQUIRED and must be non-empty, and that is a security boundary
+// rather than a convenience. This function previously set ANTHROPIC_AUTH_TOKEN
+// only `if (val)`, which meant a session with no OPENROUTER_API_KEY still
+// pointed ANTHROPIC_BASE_URL at openrouter.ai with no token of its own -- and
+// the CLI dutifully fell back to the user's saved Anthropic login and sent it
+// there. Confirmed against the real binary and a logging server standing in
+// for openrouter.ai: it sent `Authorization: Bearer sk-ant-...`. Callers must
+// resolve a key first (preflightOpenrouterRun does); there is deliberately no
+// code path from here to openrouter.ai without an OpenRouter token.
+function envForOpenrouterSpawn(apiKey) {
+    if (!apiKey) {
+        // Unreachable via runAgentTurn (pre-flight rejects a keyless run before
+        // any spawn). A backstop, so a future caller that skips pre-flight fails
+        // loudly instead of quietly leaking.
+        throw new Error("envForOpenrouterSpawn: refusing to spawn without an OpenRouter key");
+    }
     const env = { ...process.env };
-    delete env.ANTHROPIC_API_KEY;
+    for (const name of ANTHROPIC_CREDENTIAL_ENV)
+        delete env[name];
     env.ANTHROPIC_BASE_URL = OPENROUTER_BASE_URL;
     env.CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY = "1";
-    const val = openrouterApiKey();
-    if (val)
-        env.ANTHROPIC_AUTH_TOKEN = val;
-    else
-        delete env.ANTHROPIC_AUTH_TOKEN;
+    env.ANTHROPIC_AUTH_TOKEN = apiKey;
     return env;
 }
 // The one OpenRouter credential, shared by BOTH OpenRouter paths: smith's
@@ -116,6 +206,110 @@ const OPENROUTER_KEY_NAME = "OPENROUTER_API_KEY";
 function openrouterApiKey() {
     return castleKeys()[OPENROUTER_KEY_NAME] ?? process.env[OPENROUTER_KEY_NAME] ?? "";
 }
+const MODEL_CAPS_TTL_MS = 10 * 60_000;
+const OPENROUTER_API_BASE = "https://openrouter.ai/api/v1";
+const modelCapsCache = new Map();
+function asRecord(v) {
+    return v && typeof v === "object" ? v : null;
+}
+async function openrouterProviderTiers(slug) {
+    const res = await fetch(`${OPENROUTER_API_BASE}/models/${slug}/endpoints`);
+    if (!res.ok)
+        return [];
+    const json = asRecord(await res.json());
+    const data = asRecord(json?.data);
+    const endpoints = data && Array.isArray(data.endpoints) ? data.endpoints : [];
+    const tags = [];
+    for (const ep of endpoints) {
+        const rec = asRecord(ep);
+        const tag = rec && typeof rec.tag === "string" ? rec.tag : null;
+        if (tag && !tags.includes(tag))
+            tags.push(tag);
+    }
+    return tags;
+}
+async function fetchModelCaps(slug) {
+    const cached = modelCapsCache.get(slug);
+    if (cached && Date.now() - cached.at < MODEL_CAPS_TTL_MS)
+        return cached.caps;
+    // Best-effort per source: a failure in either leaves that half empty rather
+    // than failing the whole lookup, so a bad slug still yields a usable (empty)
+    // caps object the client can render as "no dynamic options".
+    let reasoningEfforts = null;
+    let defaultEffort = null;
+    try {
+        // Shared catalog (openrouter-catalog.ts) rather than a second /models
+        // fetch: it's the same list the pre-flight slug check reads, and it brings
+        // a disk-backed stale-while-revalidate cache with it.
+        const entry = await openrouterCatalogEntry(slug);
+        const reasoning = asRecord(entry?.reasoning);
+        const efforts = reasoning?.supported_efforts;
+        const supportedParams = entry?.supportedParameters;
+        const acceptsEffort = Array.isArray(supportedParams) &&
+            (supportedParams.includes("reasoning_effort") ||
+                supportedParams.includes("reasoning"));
+        if (acceptsEffort && Array.isArray(efforts) && efforts.length > 0) {
+            reasoningEfforts = efforts.filter((e) => typeof e === "string");
+            defaultEffort =
+                typeof reasoning?.default_effort === "string"
+                    ? reasoning.default_effort
+                    : null;
+        }
+    }
+    catch {
+        // leave reasoning fields null
+    }
+    let providerTiers = [];
+    try {
+        providerTiers = await openrouterProviderTiers(slug);
+    }
+    catch {
+        // leave providerTiers empty
+    }
+    const caps = {
+        model: slug,
+        reasoningEfforts,
+        defaultEffort,
+        providerTiers,
+    };
+    modelCapsCache.set(slug, { caps, at: Date.now() });
+    return caps;
+}
+// GET AGENT_MODEL_CAPS_PREFIX?model=<slug>. Returns 400 for a missing/oversized
+// slug, 200 ModelCaps otherwise (empty caps on upstream failure -- see
+// fetchModelCaps). reqPath is already query-stripped; parse req.url for it.
+function handleModelCaps(req, res) {
+    const send = (status, body) => {
+        res.writeHead(status, {
+            "content-type": "application/json",
+            "cache-control": "no-store",
+        });
+        res.end(JSON.stringify(body));
+        return true;
+    };
+    let slug = "";
+    try {
+        slug = (new URL(req.url ?? "", "http://localhost").searchParams.get("model") ?? "").trim();
+    }
+    catch {
+        slug = "";
+    }
+    if (!slug || slug.length > OPENROUTER_MODEL_MAX_LEN) {
+        return send(400, { error: "missing or invalid model" });
+    }
+    // Strip any routing suffix the client may have on the displayed slug so the
+    // OpenRouter lookup hits the base model id.
+    const baseSlug = slug.replace(/:(nitro|exacto|floor)$/, "");
+    fetchModelCaps(baseSlug)
+        .then((caps) => send(200, caps))
+        .catch(() => send(200, {
+        model: baseSlug,
+        reasoningEfforts: null,
+        defaultEffort: null,
+        providerTiers: [],
+    }));
+    return true;
+}
 // Build the headless CLI invocation for a spawning backend/role (smith never
 // comes through here -- it has no CLI process; see runAgentSmith). Cursor's
 // router runs in read-only ask mode; claude runs permission-mode auto for
@@ -178,7 +372,9 @@ openrouterModel) {
                     : []),
                 prompt,
             ],
-            env: viaOpenrouter ? envForOpenrouterSpawn() : envForAgentSpawn(backend),
+            env: viaOpenrouter
+                ? envForOpenrouterSpawn(openrouterApiKey())
+                : envForAgentSpawn(backend),
         };
     }
     return {
@@ -435,6 +631,15 @@ function baseName(p) {
     const parts = p.split(/[\\/]/).filter(Boolean);
     return parts[parts.length - 1] || p;
 }
+// First non-blank line, capped -- the one-line technical reason shown in the
+// UI's collapsed error disclosure. The full text goes to the consoles.
+function firstLine(text, max = 200) {
+    const line = (text ?? "")
+        .split("\n")
+        .map((l) => l.trim())
+        .find((l) => l.length > 0);
+    return (line ?? "").slice(0, max);
+}
 // First string-typed value among loosely-typed tool inputs, or "" when none is
 // a string (avoids "[object Object]" from String()-ing an object/array value).
 function firstString(...vals) {
@@ -504,7 +709,13 @@ function toolActivityLabel(ev) {
 // (~/.castle/keys.json) rather than sandbox-wide env -- so an ambient key can't
 // override a user's own subscription login. Falls back to process.env for
 // older sandboxes that still inject the keys as env.
-const CASTLE_KEYS_PATH = path.join(os.homedir(), ".castle", "keys.json");
+// Overridable so the QA battery can isolate from a developer's REAL
+// ~/.castle/keys.json. Without this, a machine that has a live OPENROUTER_API_KEY
+// there shadows the fake key the harness injects via env (keys-file-first, see
+// openrouterApiKey), which breaks the keyless and injected-key scenarios in
+// exactly the way that is hard to reproduce on CI. Mirrors the other
+// CASTLE_OPENROUTER_* test overrides.
+const CASTLE_KEYS_PATH = process.env.CASTLE_KEYS_PATH ?? path.join(os.homedir(), ".castle", "keys.json");
 function castleKeys() {
     try {
         return JSON.parse(fs.readFileSync(CASTLE_KEYS_PATH, "utf8"));
@@ -520,16 +731,41 @@ const BACKEND_KEY_ENV = {
     claude: "ANTHROPIC_API_KEY",
     cursor: "CURSOR_API_KEY",
 };
-// True when the user has their OWN saved auth for this backend -- a /login, or
-// (for cursor, which reuses one auth.json) any saved creds. When so we do NOT
-// inject Castle's key, so their auth is used and billed to them.
+// cursor-agent rewrites ~/.config/cursor/auth.json on every successful run,
+// including Castle's own CURSOR_API_KEY runs -- so the file existing does NOT
+// mean a user logged in. A real login (OAuth, or a tester's own key) overwrites
+// it and drops Castle's apiKey; a file whose apiKey is still Castle's key is just
+// our cache. Treating that cache as a login would suppress the injected key, and
+// once its ~60-min token expires cursor-agent (no headless refresh) fails auth.
+function cursorHasUserLogin(home) {
+    const authPath = path.join(home, ".config", "cursor", "auth.json");
+    try {
+        const auth = JSON.parse(fs.readFileSync(authPath, "utf8"));
+        return auth.apiKey !== castleKeys().CURSOR_API_KEY;
+    }
+    catch {
+        return false;
+    }
+}
+// True when the user has their OWN saved auth for this backend -- a login that we
+// should defer to (and bill to them) instead of injecting Castle's key.
+//
+// KNOWN GAP (macOS): the claude check is a false negative for most logged-in
+// users. `claude /login` stores credentials in the KEYCHAIN there, not in
+// ~/.claude/.credentials.json, so this returns false and Castle's key gets
+// injected and billed even though the user has a perfectly good subscription
+// login the CLI would have used. Verified while tracing the OpenRouter
+// credential leak: on a machine with no .credentials.json at all, the CLI still
+// authenticated from the Keychain. Left alone deliberately -- reading the
+// Keychain (`security find-generic-password`) changes who pays for a run, which
+// is a product decision, not a cleanup.
 function backendHasSavedAuth(backend) {
     const home = os.homedir();
     if (backend === "claude") {
         return fs.existsSync(path.join(home, ".claude", ".credentials.json"));
     }
     if (backend === "cursor") {
-        return fs.existsSync(path.join(home, ".config", "cursor", "auth.json"));
+        return cursorHasUserLogin(home);
     }
     return false;
 }
@@ -836,6 +1072,67 @@ function logAgentUsage(label, backend, usage) {
     const output = formatTokenCount(usage.output_tokens);
     console.error(`[agent usage] ${label} ${backend}: input=${input} cache_read=${read} cache_created=${created} output=${output}`);
 }
+// Per-deck machine-readable usage ledger, appended to <deckDir>/.castle/agent/,
+// harvested out-of-band (by the cloud launcher) for rough per-user token
+// metering. Distinct from logAgentUsage's stderr line, which is lossy
+// (rounds to "3.2k") and gets truncated when the serve restarts.
+const USAGE_LEDGER_FILE = "usage.jsonl";
+// The ledger is only useful where the cloud launcher harvests it, so the managed
+// sandbox environments set CASTLE_USAGE_LEDGER=1 (E2B via cloudSandbox.serveOnPort,
+// castle-sandboxes via its image). A local `castle-web serve` leaves it unset, so
+// dev deck dirs don't accumulate a ledger nothing reads.
+const USAGE_LEDGER_ENABLED = process.env.CASTLE_USAGE_LEDGER === "1";
+// Concrete model behind a finished run: smith and claude-via-OpenRouter both
+// bill the OpenRouter slug; plain claude bills its own slug; cursor has no
+// per-model split tracked here.
+function resolveRunModel(backend, claudeModel, openrouterModel) {
+    if (backend === "smith")
+        return openrouterModel;
+    if (backend === "claude") {
+        return claudeModel === "openrouter" ? openrouterModel : claudeModel;
+    }
+    return backend;
+}
+// One record per finished run: the human-readable stderr line PLUS a precise
+// append-only JSONL line in the deck's usage ledger. Precise counts (not the
+// stderr line's rounded values) and self-describing (id/role/backend/model) so
+// the harvester can attribute and de-dup. Best-effort: a metering write must
+// never fail an agent run.
+function reportRunUsage(agentDir, role, backend, claudeModel, openrouterModel, result, taskId) {
+    const usage = result.usage;
+    logAgentUsage(taskId ? `task ${taskId}` : "router", backend, usage);
+    if (!USAGE_LEDGER_ENABLED)
+        return;
+    // cursor-agent's stream-json doesn't report token usage, so a cursor run has no
+    // `usage`; still record it (zero counts, tokens_reported:false) for run-count
+    // visibility. Other backends only write once they actually produced usage.
+    if (!usage && backend !== "cursor")
+        return;
+    try {
+        const line = JSON.stringify({
+            at: nowIso(),
+            id: nanoid(),
+            role,
+            backend,
+            model: resolveRunModel(backend, claudeModel, openrouterModel),
+            ...(taskId ? { taskId } : {}),
+            // A failed run still resolves with a usage object of all zeros (an auth
+            // error emits a result event with zeroed counts), so its zeros would
+            // otherwise be indistinguishable downstream from a real "measured zero".
+            ...(result.ok ? {} : { failed: true }),
+            tokens_reported: usage !== undefined,
+            input_tokens: usage?.input_tokens ?? 0,
+            output_tokens: usage?.output_tokens ?? 0,
+            cache_read_input_tokens: usage?.cache_read_input_tokens ?? 0,
+            cache_creation_input_tokens: usage?.cache_creation_input_tokens ?? 0,
+        });
+        fs.mkdirSync(agentDir, { recursive: true });
+        fs.appendFileSync(path.join(agentDir, USAGE_LEDGER_FILE), line + "\n");
+    }
+    catch {
+        /* best-effort: a metering write must never fail an agent run */
+    }
+}
 // Build the per-run stdout event handler over a shared mutable parser state.
 // Splitting the cursor + claude stream decoding out of runAgentCli keeps each
 // within the max-lines budget; behavior is identical (same delta/activity/
@@ -1039,19 +1336,47 @@ function runAgentCli(opts) {
             settle({
                 ok: false,
                 finalText: state.accumulated,
-                error: `could not run cursor-agent: ${err.message}`,
+                // The binary itself wouldn't start (ENOENT, EACCES). Names the command
+                // actually being spawned -- this used to say "cursor-agent" for every
+                // backend, so a missing `claude` reported the wrong tool.
+                error: `could not run ${opts.command}: ${err.message}`,
+                failure: { kind: "spawn", detail: `${opts.command}: ${err.message}` },
             });
         });
         child.on("close", (code) => {
             const ok = code === 0 && !state.resultIsError && state.sawResult;
+            // A provider error does NOT arrive on stderr: the claude CLI reports it
+            // in the stream-json result event (is_error:true) and exits 0, leaving
+            // stderr empty -- verified against the real binary. So classify against
+            // the result text first, with stderr as the fallback for the shapes that
+            // do write there. Both are read BEFORE the 300-char truncation below.
+            //
+            // ONLY for OpenRouter-routed runs (opts.openrouterModel is set only when
+            // roleUsesOpenrouter): the classifier's copy is OpenRouter-branded, so a
+            // plain claude/cursor failure must NOT run through it -- an Anthropic 529
+            // would otherwise read as "OpenRouter is busy", naming the wrong
+            // provider. Plain runs keep their provider-neutral "exit" copy, exactly
+            // as before this feature.
+            const classified = ok || !opts.openrouterModel
+                ? undefined
+                : classifyProviderError(state.finalText, opts.openrouterModel) ??
+                    classifyProviderError(stderrTail, opts.openrouterModel);
+            const error = ok
+                ? undefined
+                : `agent exited ${code}${stderrTail ? `: ${stderrTail.slice(-300)}` : ""}`;
             settle({
                 ok,
                 finalText: state.finalText || state.accumulated,
                 usage: state.usage,
                 crashed: !state.sawResult,
-                error: ok
-                    ? undefined
-                    : `agent exited ${code}${stderrTail ? `: ${stderrTail.slice(-300)}` : ""}`,
+                error,
+                failure: classified
+                    ? {
+                        ...classified,
+                        detail: firstLine(state.finalText) || classified.detail,
+                        verbose: [state.finalText, stderrTail].filter(Boolean).join("\n"),
+                    }
+                    : undefined,
             });
         });
     });
@@ -1094,6 +1419,10 @@ async function runAgentSmith(opts) {
             role: opts.role,
             model: opts.model,
             apiKey: openrouterApiKey(),
+            reasoningEffort: opts.openrouterTuning?.reasoningEffort,
+            routing: opts.openrouterTuning?.routing,
+            // "" (auto) becomes undefined so no provider.order is sent.
+            providerTier: opts.openrouterTuning?.providerTier || undefined,
             prompt: opts.prompt,
             systemReminder: opts.systemReminder,
             attachments: opts.attachments,
@@ -1110,6 +1439,7 @@ async function runAgentSmith(opts) {
             ok: !result.error && !result.crashed,
             finalText: result.text,
             error: result.error,
+            failure: result.failure,
             usage: result.usage,
             playtestFrames: result.playtestFrames,
             crashed: result.crashed,
@@ -1129,11 +1459,82 @@ async function runAgentSmith(opts) {
         opts.children.delete(handle);
     }
 }
+// True when a role's path goes through OpenRouter: the smith native loop, or
+// the claude CLI routed at OpenRouter. The client has a twin of this in
+// conductor.tsx (it decides whether to show the slug field) -- keep them in
+// step; this one decides whether the slug is worth validating at all.
+export function roleUsesOpenrouter(backend, claudeModel) {
+    return backend === "smith" || (backend === "claude" && claudeModel === "openrouter");
+}
+function configFailure(reason, detail, extra) {
+    return { kind: "config", reason, detail, ...extra };
+}
+// Everything decidable about an OpenRouter run BEFORE spending anything on it.
+// Returns a failure to surface as-is, or null to proceed.
+//
+// Ordering is deliberate: the key is checked first because a keyless run must
+// never reach envForOpenrouterSpawn (see the credential-leak note there), and
+// because a bad key otherwise costs over two minutes of internal CLI retries.
+// Everything here either answers definitively or falls open -- checkOpenrouter*
+// resolve "unavailable" on any network trouble, and we allow the run rather
+// than invent a verdict.
+async function preflightOpenrouterRun(opts) {
+    if (!roleUsesOpenrouter(opts.backend, opts.claudeModel))
+        return null;
+    const apiKey = openrouterApiKey();
+    if (!apiKey) {
+        return configFailure("no-key", `no ${OPENROUTER_KEY_NAME} is set (checked ${CASTLE_KEYS_PATH} and the environment)`);
+    }
+    const model = opts.openrouterModel.trim();
+    if (!model) {
+        return configFailure("unknown-model", "no OpenRouter model is set for this role");
+    }
+    // Key and slug checks are independent, so overlap them rather than paying
+    // both round-trips in series. Both are cached and single-flighted.
+    const [key, slug] = await Promise.all([
+        checkOpenrouterKey(apiKey),
+        checkOpenrouterModel(model),
+    ]);
+    if (key.status === "bad-key") {
+        return configFailure("bad-key", `OpenRouter rejected ${OPENROUTER_KEY_NAME}`);
+    }
+    if (key.status === "no-credits") {
+        return configFailure("no-credits", "the OpenRouter key is out of credits");
+    }
+    if (slug.status === "unknown-model") {
+        return configFailure("unknown-model", `OpenRouter has no model "${model}"`, {
+            model,
+            suggestion: slug.suggestions[0],
+        });
+    }
+    if (slug.status === "no-tools") {
+        return configFailure("no-tools", `"${model}" does not support tool calling`, {
+            model,
+        });
+    }
+    return null;
+}
 // The one backend dispatch point for running an agent turn: smith runs
 // in-process (runAgentSmith -> runAgentNative); cursor/claude spawn a CLI
 // (buildAgentInvocation -> runAgentCli). Everything downstream consumes the
 // same CliRunResult contract either way.
-function runAgentTurn(opts) {
+async function runAgentTurn(opts) {
+    // Deterministic config errors stop here: nothing spawned, no request issued,
+    // nothing billed. Returned (not thrown) because the callers' catch paths
+    // emit generic "something went wrong" copy, which would bury the specific
+    // reason this pre-flight exists to produce.
+    const failure = await preflightOpenrouterRun(opts);
+    if (failure) {
+        return {
+            ok: false,
+            finalText: "",
+            error: failure.detail,
+            failure,
+            // NOT "crashed": nothing ran. crashed drives the task retry loop, and a
+            // config failure is exactly what must not be retried.
+            crashed: false,
+        };
+    }
     if (opts.backend === "smith") {
         return runAgentSmith({
             cwd: opts.cwd,
@@ -1144,6 +1545,7 @@ function runAgentTurn(opts) {
             // appends it to its own system framing).
             systemReminder: opts.role === "task" ? CLAUDE_TASK_SYSTEM_REMINDER : undefined,
             attachments: opts.attachments,
+            openrouterTuning: opts.openrouterTuning,
             timeoutMs: opts.timeoutMs,
             logPath: opts.logPath,
             playtest: opts.playtest,
@@ -1170,6 +1572,9 @@ function runAgentTurn(opts) {
         onThinking: opts.onThinking,
         onSpawn: opts.onSpawn,
         labelUnknownTools: opts.labelUnknownTools,
+        openrouterModel: roleUsesOpenrouter(opts.backend, opts.claudeModel)
+            ? opts.openrouterModel
+            : undefined,
     });
 }
 // -- task store ---------------------------------------------------------------
@@ -1398,6 +1803,7 @@ async function runTaskAgentIn(ctx, task) {
             prompt: taskPrompt,
             claudeModel: ctx.claudeModel,
             openrouterModel: ctx.openrouterModel,
+            openrouterTuning: ctx.openrouterTuning,
             cwd: ctx.deckDir,
             timeoutMs: TASK_TIMEOUT_MS,
             logPath: path.join(dir, "log.jsonl"),
@@ -1416,11 +1822,18 @@ async function runTaskAgentIn(ctx, task) {
                     ctx.onFeed(`[${activity}]`);
             },
         });
-        logAgentUsage(`task ${task.id}`, ctx.backend, result.usage);
+        reportRunUsage(path.dirname(ctx.tasksDir), "task", ctx.backend, ctx.claudeModel, ctx.openrouterModel, result, task.id);
         if (ctx.stopRequested.has(task.id))
             return result;
         if (!result.crashed)
             return result;
+        // A crash normally means "the process died, try again" -- but a claude CLI
+        // that dies on a bad key or slug BEFORE emitting its result event also
+        // lands here (crashed = never saw a result), and retrying that burns all
+        // three attempts, backoff included, on config that cannot change between
+        // them. Deterministic failures get exactly one attempt.
+        if (result.failure?.kind === "config")
+            return result;
         if (attempt < MAX_TASK_ATTEMPTS) {
             ctx.onRetry(attempt + 1);
             if (await waitBeforeTaskRetry(attempt, ctx.stopRequested, task.id))
@@ -1451,6 +1864,7 @@ function startTask(ctx, task) {
         backend: ctx.backend(),
         claudeModel: ctx.claudeModel(),
         openrouterModel: ctx.openrouterModel(),
+        openrouterTuning: ctx.openrouterTuning(),
         stopRequested: ctx.stopRequested,
         quickReference: ctx.quickReference,
         playtest: ctx.playtest,
@@ -1509,6 +1923,19 @@ function startTask(ctx, task) {
                 : result.ok
                     ? result.finalText.slice(-RESULT_SUMMARY_CHARS)
                     : `${result.error ?? "failed"}\n${result.finalText.slice(-RESULT_SUMMARY_CHARS)}`;
+            if (!wasStopped && !result.ok) {
+                const failure = resolveFailure(result);
+                // spawnedTasks/willRetry are router-turn concepts; a task card has
+                // neither. Same copy table either way -- see failureCopy.
+                task.errorCopy = failureCopy({
+                    failure,
+                    spawnedTasks: false,
+                    willRetry: false,
+                });
+                task.errorDetail = failure.detail || result.error;
+                const label = failure.reason ? `${failure.kind}/${failure.reason}` : failure.kind;
+                console.error(`[task ${task.id}] failed (${label}): ${failure.verbose ?? task.errorDetail}`);
+            }
             ctx.touch(task);
         }
         catch (err) {
@@ -1646,6 +2073,7 @@ function createTaskStore(opts) {
         backend: opts.backend,
         claudeModel: opts.claudeModel,
         openrouterModel: opts.openrouterModel,
+        openrouterTuning: opts.openrouterTuning,
         playtest: opts.playtest,
         restart: opts.restart,
         onStarted: opts.onStarted,
@@ -1861,6 +2289,8 @@ function asClientTask(task) {
         phase: task.phase,
         acknowledged: task.acknowledged,
         rejected: task.rejected,
+        errorCopy: task.errorCopy,
+        errorDetail: task.errorDetail,
         playtestFrames: (task.playtestFrames ?? []).map((rel) => `${AGENT_PLAYTEST_PREFIX}${task.id}/${path.basename(rel)}`),
     };
 }
@@ -1983,34 +2413,27 @@ function makePlaytestFrameHandler(tasksDir) {
         return true;
     };
 }
-// Classify from the error strings runAgentCli actually produces (see its
-// child.on("error"), timeout, and close handlers).
-function classifyRouterFailure(error) {
-    if (error?.startsWith("could not run"))
-        return "spawn";
-    if (error === "agent run timed out")
-        return "timeout";
-    return "exit";
-}
-// Plain-language copy for a failed turn. `salvaged` = the turn already
-// produced something the user can see (streamed text and/or spawned tasks),
-// so "pick it back up" framing fits; a turn that died with nothing is a clean
-// hiccup. `willRetry` = the queue is about to re-run this instruction itself.
-function routerFailureCopy(opts) {
-    if (opts.willRetry) {
-        return "Something went wrong on my end -- give me a moment to try that again.";
-    }
-    const tasksNote = opts.spawnedTasks
-        ? " The steps I already kicked off are still running."
-        : "";
-    switch (opts.kind) {
-        case "spawn":
-            return `I couldn't start working on that -- something in this setup isn't right. If this keeps happening, the person running this session needs to take a look.${tasksNote}`;
-        case "timeout":
-            return `That took me too long and I had to stop partway. Send another message and I'll pick it back up.${tasksNote}`;
-        case "exit":
-            return `Something went wrong on my end partway through. Send another message and I'll pick it back up.${tasksNote}`;
-    }
+// -- router failure handling ---------------------------------------------------
+// A failed router turn settles gracefully: the chat gets short plain-language
+// copy (classified by failure kind), and the raw CLI error rides along as
+// `errorDetail` for the client to reveal on demand -- never spliced into the
+// message text, where it would both read as machinery at the wrong register
+// and replay into every later turn's transcript.
+// The structured failure a run reported, or one reconstructed from the error
+// string for the paths that don't carry one (timeouts, interrupts, anything a
+// classifier miss left unlabelled). Reconstruction keeps the pre-existing
+// buckets exactly as they were -- an unclassified failure must behave the way
+// it did before agent-failures.ts existed.
+function resolveFailure(result) {
+    if (result.failure)
+        return result.failure;
+    const error = result.error;
+    const kind = error?.startsWith("could not run")
+        ? "spawn"
+        : error === "agent run timed out"
+            ? "timeout"
+            : "exit";
+    return { kind, detail: error ?? "unknown failure" };
 }
 // Assemble the full stateless prompt for one router turn: rules + deck
 // context + transcript replay (minus log lines and the in-flight reply) +
@@ -2161,6 +2584,7 @@ function runRouterTurnIn(ctx, instruction, attachments = []) {
         prompt,
         claudeModel: ctx.claudeModel(),
         openrouterModel: ctx.openrouterModel(),
+        openrouterTuning: ctx.openrouterTuning(),
         attachments,
         cwd: ctx.deckDir,
         timeoutMs: ROUTER_TIMEOUT_MS,
@@ -2193,10 +2617,12 @@ function runRouterTurnIn(ctx, instruction, attachments = []) {
         },
     })
         .then((result) => {
-        logAgentUsage("router", backend, result.usage);
+        reportRunUsage(ctx.agentDir, "router", backend, ctx.claudeModel(), ctx.openrouterModel(), result);
         // Signals the finally -> onSettled(retryable): the turn failed cleanly
         // enough (transient, nothing salvaged) that the queue may re-run it.
         let retryable = false;
+        // Full provider text for the browser console, when a failure carried one.
+        let errorVerbose;
         // The settle path must ALWAYS reach ctx.onSettled() (clears
         // routerRunning + flushes pendingSends). A throw here on Node v25 would
         // otherwise both freeze the composer and crash the serve, so the whole
@@ -2234,24 +2660,35 @@ function runRouterTurnIn(ctx, instruction, attachments = []) {
                 message.status = "done";
             }
             else {
-                const kind = classifyRouterFailure(result.error);
+                const failure = resolveFailure(result);
                 // Only a turn that produced NOTHING visible is safe to silently
                 // re-run: with streamed text or spawned tasks in play, a retry
                 // would answer the same instruction twice (and could re-spawn
                 // near-duplicate tasks past the title dedup). Spawn failures are
                 // persistent (the CLI itself won't launch) and timeouts are too
                 // expensive to repeat blind, so only "exit" crashes retry.
+                //
+                // "config" and "no-work" are deterministic -- the same slug, key, or
+                // model would fail again identically, so a retry is pure latency in
+                // front of the same message. "transient" is excluded too, but for a
+                // different reason: it has ALREADY been retried at the transport
+                // layer (3 backed-off connects), and a turn-level retry on top just
+                // doubles the wait with the composer frozen.
                 const salvaged = cleaned !== "" || taskIds.length > 0;
-                retryable = kind === "exit" && !salvaged;
-                const copy = routerFailureCopy({
-                    kind,
+                retryable = failure.kind === "exit" && !salvaged;
+                const copy = failureCopy({
+                    failure,
                     spawnedTasks: taskIds.length > 0,
                     willRetry: retryable && ctx.canAutoRetry(),
                 });
                 message.text = cleaned ? `${cleaned}\n\n${copy}` : copy;
                 message.status = "error";
-                message.errorDetail = result.error ?? "unknown failure";
-                console.error(`[router] turn failed (${kind}): ${message.errorDetail}`);
+                message.errorDetail = failure.detail || result.error || "unknown failure";
+                errorVerbose = failure.verbose;
+                const label = failure.reason
+                    ? `${failure.kind}/${failure.reason}`
+                    : failure.kind;
+                console.error(`[router] turn failed (${label}): ${failure.verbose ?? message.errorDetail}`);
             }
             if (taskIds.length > 0)
                 message.taskIds = taskIds;
@@ -2263,6 +2700,12 @@ function runRouterTurnIn(ctx, instruction, attachments = []) {
                 status: message.status,
                 taskIds: message.taskIds ?? [],
                 errorDetail: message.errorDetail,
+                // Broadcast-only, never persisted: the client console.errors this so
+                // the whole provider response is inspectable without leaving the
+                // browser. Keeping it out of MessageRecord is the same call
+                // errorDetail already makes -- a multi-KB dump has no business in
+                // messages.json or a replayed transcript.
+                errorVerbose,
             });
         }
         catch (err) {
@@ -2323,20 +2766,97 @@ function applyAgentSettings(incoming, ctx) {
         const value = normalizeClaudeModel(incoming[key]);
         if (value && value !== settings[key]) {
             settings[key] = value;
-            changes.push(`${key === "routerClaudeModel" ? "conductor" : "tasks"} claude model -> ${value}`);
+            changes.push(`${key === "routerClaudeModel" ? "operator" : "tasks"} claude model -> ${value}`);
         }
     }
     for (const key of ["routerOpenrouterModel", "tasksOpenrouterModel"]) {
         const value = normalizeOpenrouterModel(incoming[key]);
         if (value && value !== settings[key]) {
             settings[key] = value;
-            changes.push(`${key === "routerOpenrouterModel" ? "conductor" : "tasks"} openrouter model -> ${value}`);
+            changes.push(`${key === "routerOpenrouterModel" ? "operator" : "tasks"} openrouter model -> ${value}`);
+        }
+    }
+    for (const key of ["routerReasoningEffort", "tasksReasoningEffort"]) {
+        const value = normalizeReasoningEffort(incoming[key]);
+        if (value && value !== settings[key]) {
+            settings[key] = value;
+            changes.push(`${key === "routerReasoningEffort" ? "operator" : "tasks"} reasoning effort -> ${value}`);
+        }
+    }
+    for (const key of ["routerRouting", "tasksRouting"]) {
+        const value = normalizeRoutingMode(incoming[key]);
+        if (value && value !== settings[key]) {
+            settings[key] = value;
+            changes.push(`${key === "routerRouting" ? "operator" : "tasks"} routing -> ${value}`);
+        }
+    }
+    for (const key of ["routerProviderTier", "tasksProviderTier"]) {
+        // "" is a valid value (auto), so check for null (invalid) explicitly
+        // rather than truthiness -- otherwise the tier could never be cleared.
+        const value = normalizeProviderTier(incoming[key]);
+        if (value !== null && value !== settings[key]) {
+            settings[key] = value;
+            changes.push(`${key === "routerProviderTier" ? "operator" : "tasks"} provider tier -> ${value || "auto"}`);
         }
     }
     if (changes.length === 0)
         return;
     fs.writeFileSync(ctx.settingsPath, JSON.stringify(settings, null, 2) + "\n");
+    // The value is saved and broadcast IMMEDIATELY -- validation never gates a
+    // write. The verdict follows in a second frame once the catalog answers.
     ctx.broadcast({ type: "settings", settings });
+    void broadcastSettingsWarnings(ctx);
+}
+// Which slugs are worth a verdict: only roles actually routed at OpenRouter
+// (otherwise we'd warn about an inert leftover value), and only when a slug is
+// set at all.
+function slugKeysToValidate(settings) {
+    const keys = [];
+    if (roleUsesOpenrouter(settings.router ?? "claude", settings.routerClaudeModel ?? "opus") &&
+        settings.routerOpenrouterModel) {
+        keys.push("routerOpenrouterModel");
+    }
+    if (roleUsesOpenrouter(settings.tasks ?? "claude", settings.tasksClaudeModel ?? "sonnet") &&
+        settings.tasksOpenrouterModel) {
+        keys.push("tasksOpenrouterModel");
+    }
+    return keys;
+}
+// Advisory verdicts for the settings popover. Every warning carries the slug it
+// was computed FOR: this is async, so by the time it lands the user may have
+// typed something else, and the client drops a verdict whose model no longer
+// matches (see warningFor). An unreachable catalog yields no warnings at all --
+// silence, never a guess.
+export async function computeSettingsWarnings(settings) {
+    const out = {};
+    await Promise.all(slugKeysToValidate(settings).map(async (key) => {
+        const model = settings[key];
+        if (!model)
+            return;
+        const check = await checkOpenrouterModel(model);
+        if (check.status === "unknown-model") {
+            // suggestion is carried SEPARATELY (not baked into message) so the
+            // client can render it as a one-click fix rather than plain text.
+            out[key] = {
+                model,
+                status: "unknown-model",
+                message: "No such model on OpenRouter.",
+                suggestion: check.suggestions[0],
+            };
+        }
+        else if (check.status === "no-tools") {
+            out[key] = {
+                model,
+                status: "no-tools",
+                message: "This model can't use tools, so it can't do work. Pick another.",
+            };
+        }
+    }));
+    return out;
+}
+async function broadcastSettingsWarnings(ctx) {
+    const settingsWarnings = await computeSettingsWarnings(ctx.settings);
+    ctx.broadcast({ type: "settings", settings: ctx.settings, settingsWarnings });
 }
 function killOrphanAgents(registryPath) {
     const recorded = readJsonFile(registryPath) ?? [];
@@ -2495,6 +3015,11 @@ function startRouterTurn(ctx, instruction, attachments = []) {
         backend: () => ctx.settings.router,
         claudeModel: () => ctx.settings.routerClaudeModel,
         openrouterModel: () => ctx.settings.routerOpenrouterModel,
+        openrouterTuning: () => ({
+            reasoningEffort: ctx.settings.routerReasoningEffort,
+            routing: ctx.settings.routerRouting,
+            providerTier: ctx.settings.routerProviderTier,
+        }),
         canAutoRetry: () => !ctx.state.autoRetryUsed && ctx.state.pendingSends.length === 0,
         onSettled: (retryable) => onRouterQueueSettled(ctx, retryable),
     }, instruction, attachments);
@@ -2702,6 +3227,10 @@ export function createAgentServer(opts) {
     const attachmentsDir = path.join(agentDir, "attachments");
     const messagesPath = path.join(agentDir, "messages.json");
     fs.mkdirSync(tasksDir, { recursive: true });
+    // Warm the OpenRouter catalog now so the first pre-flight and the first
+    // popover open read a cache instead of paying for the fetch. Fire-and-forget
+    // by design -- nothing here depends on it, and it falls open if it fails.
+    primeOpenrouterCatalog();
     // ONE warm Chromium for the serve's entire lifetime, shared by every
     // playtest call (each call still gets its own fresh browser context +
     // page -- see playtest-executor.ts). Lazily launched on first use; never
@@ -2784,6 +3313,20 @@ export function createAgentServer(opts) {
         tasksOpenrouterModel: normalizeOpenrouterModel(storedSettings?.tasksOpenrouterModel) ??
             legacyOpenrouterModel ??
             DEFAULT_SETTINGS.tasksOpenrouterModel,
+        routerReasoningEffort: normalizeReasoningEffort(storedSettings?.routerReasoningEffort) ??
+            DEFAULT_SETTINGS.routerReasoningEffort,
+        tasksReasoningEffort: normalizeReasoningEffort(storedSettings?.tasksReasoningEffort) ??
+            DEFAULT_SETTINGS.tasksReasoningEffort,
+        routerRouting: normalizeRoutingMode(storedSettings?.routerRouting) ??
+            DEFAULT_SETTINGS.routerRouting,
+        tasksRouting: normalizeRoutingMode(storedSettings?.tasksRouting) ??
+            DEFAULT_SETTINGS.tasksRouting,
+        // Provider tier: "" is valid (auto), so keep a normalized "" over the
+        // default rather than treating it as absent.
+        routerProviderTier: normalizeProviderTier(storedSettings?.routerProviderTier) ??
+            DEFAULT_SETTINGS.routerProviderTier,
+        tasksProviderTier: normalizeProviderTier(storedSettings?.tasksProviderTier) ??
+            DEFAULT_SETTINGS.tasksProviderTier,
     };
     const applySettings = (incoming) => applyAgentSettings(incoming, { settings, settingsPath, broadcast });
     const taskFeeds = createTaskFeeds(broadcast);
@@ -2797,6 +3340,11 @@ export function createAgentServer(opts) {
         backend: () => settings.tasks,
         openrouterModel: () => settings.tasksOpenrouterModel,
         claudeModel: () => settings.tasksClaudeModel,
+        openrouterTuning: () => ({
+            reasoningEffort: settings.tasksReasoningEffort,
+            routing: settings.tasksRouting,
+            providerTier: settings.tasksProviderTier,
+        }),
         playtest,
         restart: opts.restart,
         // Task lifecycle stays on the board only -- log lines for it were spam.
@@ -2853,6 +3401,13 @@ export function createAgentServer(opts) {
             queued: routerQueue.queuedSnippets(),
         };
         socket.send(JSON.stringify(hello));
+        // Slug verdicts follow hello rather than riding it: they're async, and the
+        // boot snapshot must never wait on a network call. This is what makes a
+        // stored-but-bad slug warn the first time the popover opens -- without it,
+        // applyAgentSettings only ever validates on an edit (it early-returns when
+        // nothing changed), so a migrated or hand-edited slug would stay silent.
+        // The catalog is primed at boot, so in practice this lands immediately.
+        void broadcastSettingsWarnings({ settings, broadcast });
         socket.on("message", (rawData) => {
             let msg;
             try {
@@ -2896,6 +3451,8 @@ export function createAgentServer(opts) {
     const handleAttachment = makeAttachmentHandler(attachmentsDir);
     const handlePlaytestFrame = makePlaytestFrameHandler(tasksDir);
     function handleHttpRequest(req, res, reqPath) {
+        if (reqPath === AGENT_MODEL_CAPS_PREFIX)
+            return handleModelCaps(req, res);
         return handleAttachment(req, res, reqPath) || handlePlaytestFrame(req, res, reqPath);
     }
     function shutdown() {