castle-web-cli 0.4.83 → 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";
@@ -143,6 +145,17 @@ function normalizeProviderTier(value) {
 // 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
@@ -159,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
@@ -183,29 +209,9 @@ function openrouterApiKey() {
 const MODEL_CAPS_TTL_MS = 10 * 60_000;
 const OPENROUTER_API_BASE = "https://openrouter.ai/api/v1";
 const modelCapsCache = new Map();
-let modelsListCache = null;
 function asRecord(v) {
     return v && typeof v === "object" ? v : null;
 }
-async function openrouterModelsById() {
-    if (modelsListCache && Date.now() - modelsListCache.at < MODEL_CAPS_TTL_MS) {
-        return modelsListCache.byId;
-    }
-    const res = await fetch(`${OPENROUTER_API_BASE}/models`);
-    if (!res.ok)
-        throw new Error(`models list HTTP ${res.status}`);
-    const json = asRecord(await res.json());
-    const data = json && Array.isArray(json.data) ? json.data : [];
-    const byId = new Map();
-    for (const entry of data) {
-        const rec = asRecord(entry);
-        const id = rec && typeof rec.id === "string" ? rec.id : null;
-        if (id)
-            byId.set(id, entry);
-    }
-    modelsListCache = { byId, at: Date.now() };
-    return byId;
-}
 async function openrouterProviderTiers(slug) {
     const res = await fetch(`${OPENROUTER_API_BASE}/models/${slug}/endpoints`);
     if (!res.ok)
@@ -232,10 +238,13 @@ async function fetchModelCaps(slug) {
     let reasoningEfforts = null;
     let defaultEffort = null;
     try {
-        const model = asRecord((await openrouterModelsById()).get(slug));
-        const reasoning = asRecord(model?.reasoning);
+        // 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 = model?.supported_parameters;
+        const supportedParams = entry?.supportedParameters;
         const acceptsEffort = Array.isArray(supportedParams) &&
             (supportedParams.includes("reasoning_effort") ||
                 supportedParams.includes("reasoning"));
@@ -363,7 +372,9 @@ openrouterModel) {
                     : []),
                 prompt,
             ],
-            env: viaOpenrouter ? envForOpenrouterSpawn() : envForAgentSpawn(backend),
+            env: viaOpenrouter
+                ? envForOpenrouterSpawn(openrouterApiKey())
+                : envForAgentSpawn(backend),
         };
     }
     return {
@@ -620,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) {
@@ -689,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"));
@@ -723,6 +749,16 @@ function cursorHasUserLogin(home) {
 }
 // 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") {
@@ -1062,7 +1098,8 @@ function resolveRunModel(backend, claudeModel, openrouterModel) {
 // 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, usage, taskId) {
+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;
@@ -1079,6 +1116,10 @@ function reportRunUsage(agentDir, role, backend, claudeModel, openrouterModel, u
             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,
@@ -1295,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,
             });
         });
     });
@@ -1370,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,
@@ -1389,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,
@@ -1431,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 ---------------------------------------------------------------
@@ -1678,11 +1822,18 @@ async function runTaskAgentIn(ctx, task) {
                     ctx.onFeed(`[${activity}]`);
             },
         });
-        reportRunUsage(path.dirname(ctx.tasksDir), "task", ctx.backend, ctx.claudeModel, ctx.openrouterModel, result.usage, task.id);
+        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))
@@ -1772,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) {
@@ -2125,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)}`),
     };
 }
@@ -2247,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) +
@@ -2458,10 +2617,12 @@ function runRouterTurnIn(ctx, instruction, attachments = []) {
         },
     })
         .then((result) => {
-        reportRunUsage(ctx.agentDir, "router", backend, ctx.claudeModel(), ctx.openrouterModel(), 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
@@ -2499,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;
@@ -2528,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) {
@@ -2624,7 +2802,61 @@ function applyAgentSettings(incoming, ctx) {
     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) ?? [];
@@ -2995,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
@@ -3165,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 {

package/dist/native/loop.js

@@ -565,6 +565,10 @@ async function runLoop(opts, toolSchemas, log) {
     const imageLabels = new Map();
     let finalText = "";
     let totalUsage;
+    // Whether this run has called ANY tool, across every iteration -- not just
+    // the current one. Scoped to the run because the question is "did this task
+    // do anything at all", which one iteration can't answer.
+    let usedAnyTool = false;
     // Once our own timeout/external-abort fires, whatever streamChatCompletion
     // reports is moot -- the abort IS the reason for stopping, so we always
     // attribute the final error to it (rather than a network error that might
@@ -635,6 +639,9 @@ async function runLoop(opts, toolSchemas, log) {
                 return {
                     text: finalText,
                     error: streamResult.error ?? "openrouter stream ended without a final response",
+                    // Present only for an HTTP status streamChat could label; absent for
+                    // a dropped connection, which stays unclassified on purpose.
+                    failure: streamResult.failure,
                     usage: totalUsage,
                     playtestFrames: playtestFrameList(playtestFrames),
                     crashed: streamResult.crashed,
@@ -657,12 +664,40 @@ async function runLoop(opts, toolSchemas, log) {
                     : {}),
             });
             if (toolCalls.length === 0) {
+                // No tool calls is the normal way a run ends -- the model is done and
+                // signing off. But a TASK that reaches this on iteration 1, having
+                // never called a single tool, did no work: it chatted. That used to
+                // return a bare success, so the card finalized "done" at 100% with
+                // nothing changed -- the loudest silent failure this backend had.
+                //
+                // Only tasks: the router legitimately answers in plain text, and a
+                // task that used tools and THEN signs off with prose is fine.
+                //
+                // This narrows the failure class rather than closing it: a task whose
+                // only tool calls were reads still counts as "used a tool" here and
+                // can still finish having changed nothing. Detecting that needs a
+                // notion of which tools mutate, which is a bigger change than this.
+                if (opts.role === "task" && !usedAnyTool) {
+                    return {
+                        text: finalText,
+                        error: "the model replied without calling any tools, so nothing was done",
+                        failure: {
+                            kind: "no-work",
+                            detail: "model returned prose with no tool calls",
+                            model: opts.model,
+                            verbose: finalText,
+                        },
+                        usage: totalUsage,
+                        playtestFrames: playtestFrameList(playtestFrames),
+                    };
+                }
                 return {
                     text: finalText,
                     usage: totalUsage,
                     playtestFrames: playtestFrameList(playtestFrames),
                 };
             }
+            usedAnyTool = true;
             messages.push({
                 role: "assistant",
                 content: streamResult.message.content || null,