@worca/app 1.5.0 → 1.6.0-rc.1

package/src/core/broker-client.mjs

@@ -0,0 +1,206 @@
+// src/core/broker-client.mjs
+// worca's side of the credential broker (plans/credential-broker-design.html §6.1).
+// With WORCA_BROKER_URL set, worca holds no model credential: every claude spawn
+// gets a short-lived token from the broker instead (claude-runner.mjs), and the
+// broker adds the person's real key on the way to the provider.
+//
+//   WORCA_BROKER_URL          the broker's INTERNAL address (http://broker:8080). Unset = off.
+//   WORCA_BROKER_SECRET(_FILE) the shared secret for the broker's /internal API
+//   WORCA_BROKER_SYSTEM_BILL_TO who pays for work no signed-in person caused
+import { readFileSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+
+/** This server process's identity towards the broker: tokens issued under an older one are revoked at boot. */
+export const BOOT_ID = `srv-${randomUUID()}`;
+const INFO_TTL_MS = 60_000;
+const CALL_TIMEOUT_MS = 10_000;
+
+/** Whether the broker is on (pure: reads only `env`). */
+export function brokerEnabled(env = process.env) {
+  return typeof env.WORCA_BROKER_URL === 'string' && env.WORCA_BROKER_URL.trim() !== '';
+}
+
+/** {url, secret, error}: the broker's address without a trailing slash, and the secret. */
+export function brokerConfig(env = process.env, readFile = readFileSync) {
+  if (!brokerEnabled(env)) return null;
+  let url = String(env.WORCA_BROKER_URL).trim().replace(/\/+$/, '');
+  let error = null;
+  try {
+    const u = new URL(url);
+    if (u.protocol !== 'http:' && u.protocol !== 'https:') error = 'WORCA_BROKER_URL must be http(s)';
+    else if (u.pathname !== '/' || u.search || u.username) error = 'WORCA_BROKER_URL must be an origin, e.g. http://broker:8080';
+    url = u.origin;
+  } catch { error = 'WORCA_BROKER_URL is not a URL'; }
+  let secret = null;
+  const file = String(env.WORCA_BROKER_SECRET_FILE || '').trim();
+  if (file) {
+    try { secret = String(readFile(file, 'utf8')).trim() || null; } catch (err) { error ||= `WORCA_BROKER_SECRET_FILE cannot be read: ${err.code || err.message}`; }
+  } else if (typeof env.WORCA_BROKER_SECRET === 'string') secret = env.WORCA_BROKER_SECRET.trim() || null;
+  if (!secret) error ||= 'WORCA_BROKER_SECRET (or WORCA_BROKER_SECRET_FILE) is required with WORCA_BROKER_URL';
+  return { url, secret, error };
+}
+
+let _cfg = null;
+function cfg() {
+  if (!_cfg) _cfg = brokerConfig();
+  return _cfg;
+}
+/** Test seam: forget cached config and info. */
+export function resetBrokerClient() { _cfg = null; _info = null; }
+
+async function call(method, path, body, { timeoutMs = CALL_TIMEOUT_MS, fetchImpl = fetch } = {}) {
+  const c = cfg();
+  if (!c) throw new Error('the credential broker is not configured');
+  if (c.error) throw new Error(c.error);
+  const ac = new AbortController();
+  const timer = setTimeout(() => ac.abort(), timeoutMs);
+  let res;
+  try {
+    res = await fetchImpl(`${c.url}${path}`, {
+      method,
+      headers: { authorization: `Bearer ${c.secret}`, ...(body !== undefined ? { 'content-type': 'application/json' } : {}) },
+      body: body !== undefined ? JSON.stringify(body) : undefined,
+      signal: ac.signal,
+    });
+  } catch (err) {
+    throw new Error(`cannot reach the credential broker at ${c.url}: ${err.name === 'AbortError' ? 'timed out' : (err.cause?.code || err.message)}`);
+  } finally { clearTimeout(timer); }
+  let data = null;
+  try { data = await res.json(); } catch { data = null; }
+  if (!res.ok) {
+    const why = res.status === 401 ? 'the broker refused worca\'s secret (WORCA_BROKER_SECRET differs between worca and the broker)' : (data?.error || `HTTP ${res.status}`);
+    throw Object.assign(new Error(`credential broker: ${why}`), { status: res.status });
+  }
+  return data;
+}
+
+let _info = null;
+/** GET /internal/info, cached for a minute. */
+export async function brokerInfo({ force = false } = {}) {
+  if (!force && _info && Date.now() - _info.at < INFO_TTL_MS) return _info.value;
+  const value = await call('GET', '/internal/info');
+  _info = { at: Date.now(), value };
+  return value;
+}
+
+/** The last info fetched, without a network call (null before the first). */
+export function cachedBrokerInfo() { return _info ? _info.value : null; }
+
+/** Mint a spawn token. Returns {token, expiresAt, spawnId}. */
+export async function mintSpawnToken({ billTo, slots, runId = null, threadId = null, kind = 'phase', ttlSec, budgetUsd, isolated = false } = {}) {
+  const spawnId = `sp-${randomUUID()}`;
+  const body = { billTo, slots, spawnId, kind, issuer: BOOT_ID, isolated: isolated === true };
+  if (runId) body.runId = String(runId);
+  if (threadId) body.threadId = String(threadId);
+  if (ttlSec) body.ttlSec = ttlSec;
+  if (budgetUsd != null) body.budgetUsd = budgetUsd;
+  const r = await call('POST', '/internal/tokens', body);
+  return { ...r, spawnId };
+}
+
+/** Revoke one spawn's token. Never throws: the token also expires on its own. */
+export async function revokeSpawnToken(spawnId) {
+  if (!spawnId) return;
+  try { await call('DELETE', `/internal/tokens/${encodeURIComponent(spawnId)}`); }
+  catch (err) { console.warn(`[worca] broker: could not revoke a spawn token (it expires on its own): ${err.message}`); }
+}
+
+/** Revoke every token an earlier worca process issued (their spawns died with it). */
+export async function revokeStaleTokens() {
+  return call('POST', '/internal/tokens/revoke', { exceptIssuer: BOOT_ID });
+}
+
+/**
+ * "Push as me": `person`'s GitHub user token for ONE git or gh call worca makes itself.
+ * Rejects with .code 'not_connected' | 'not_configured' | 'expired' when there is none.
+ */
+export async function personGithubToken(person) {
+  try {
+    return await call('POST', '/internal/github-token', { person });
+  } catch (err) {
+    // call() folds the broker's {error, code} into the message; recover the code.
+    const m = /not connected|not set up|renew|sign in again/i.exec(err.message || '');
+    err.code = !m ? err.code : /not set up/i.test(m[0]) ? 'not_configured' : /not connected/i.test(m[0]) ? 'not_connected' : 'expired';
+    throw err;
+  }
+}
+
+/** Slot status for one person: {person, keyPage, slots:[{id,label,state,…}]}. */
+export async function personSlots(person) {
+  return call('GET', `/internal/people/${encodeURIComponent(String(person || '').toLowerCase())}/slots`);
+}
+
+/** Usage rows, newest first. */
+export async function brokerUsage({ since, billTo, runId } = {}) {
+  const q = new URLSearchParams();
+  if (since) q.set('since', since);
+  if (billTo) q.set('billTo', billTo);
+  if (runId) q.set('runId', runId);
+  return call('GET', `/internal/usage${q.size ? `?${q}` : ''}`);
+}
+
+/** Spend per person and slot in a window: {rows:[{billTo, slot, usd, requests, runs, …}]}. */
+export async function brokerUsageSummary({ since, until } = {}) {
+  const q = new URLSearchParams();
+  if (since) q.set('since', since);
+  if (until) q.set('until', until);
+  return call('GET', `/internal/usage/summary${q.size ? `?${q}` : ''}`);
+}
+
+/**
+ * Summary rows (one per person and slot) folded into one row per person, most spend first.
+ * Pure. `local` (single mode, or work no signed-in person caused) stays its own row.
+ */
+export function foldUsageByPerson(rows = []) {
+  const by = new Map();
+  for (const r of rows) {
+    const p = by.get(r.billTo) || { person: r.billTo, usd: 0, requests: 0, inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, lastAt: null, slots: [] };
+    p.usd += Number(r.usd) || 0;
+    p.requests += Number(r.requests) || 0;
+    p.inputTokens += Number(r.inputTokens) || 0;
+    p.outputTokens += Number(r.outputTokens) || 0;
+    p.cacheReadTokens += Number(r.cacheReadTokens) || 0;
+    if (!p.lastAt || (r.lastAt && r.lastAt > p.lastAt)) p.lastAt = r.lastAt || p.lastAt;
+    p.slots.push({ slot: r.slot, plan: r.plan || 'api', usd: Number(r.usd) || 0, requests: Number(r.requests) || 0 });
+    by.set(r.billTo, p);
+  }
+  return [...by.values()].sort((a, b) => b.usd - a.usd || b.requests - a.requests);
+}
+
+/** The broker proxy URL for a slot. */
+export function slotBaseUrl(slot, env = process.env) {
+  const c = brokerConfig(env);
+  return c ? `${c.url}/p/${slot}` : null;
+}
+
+/** The slot a broker proxy URL names, or null when `url` is not this broker's. */
+export function slotOfBaseUrl(url, env = process.env) {
+  const c = brokerConfig(env);
+  if (!c || typeof url !== 'string') return null;
+  const m = new RegExp(`^${c.url.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}/p/([a-z][a-z0-9-]{1,31})/?$`).exec(url.trim());
+  return m ? m[1] : null;
+}
+
+/**
+ * Boot check (plans/credential-broker-design.html §6.7): reach the broker (retrying
+ * while it starts), then revoke tokens a previous worca process left behind.
+ * Resolves with the broker's info; rejects with a one-line reason.
+ */
+export async function connectBroker({ waitMs = 60_000, log = console.log } = {}) {
+  const c = cfg();
+  if (c?.error) throw new Error(c.error);
+  const deadline = Date.now() + waitMs;
+  let lastErr;
+  for (;;) {
+    try {
+      const info = await brokerInfo({ force: true });
+      try { await revokeStaleTokens(); } catch (err) { log(`[worca] broker: could not revoke older tokens: ${err.message}`); }
+      return info;
+    } catch (err) {
+      lastErr = err;
+      if (err.status === 401 || Date.now() >= deadline) break;
+      await new Promise((r) => setTimeout(r, 2000));
+    }
+  }
+  throw new Error(`cannot reach the credential broker: ${lastErr?.message || 'unknown error'}`);
+}

package/src/core/broker-guard.mjs

@@ -0,0 +1,112 @@
+// src/core/broker-guard.mjs
+// Guarantee K1 (plans/credential-broker-design.html §6.8): with the credential
+// broker on, no model credential may exist anywhere an agent can reach. worca
+// refuses to start while one does, and names each finding by WHERE it is — never by
+// its value. The pure part takes everything as input; the boot wrapper gathers it.
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/** Env vars that authenticate a model provider. Empty values (as Compose sets them) don't count. */
+export const MODEL_CREDENTIAL_ENV_KEYS = Object.freeze([
+  'ANTHROPIC_API_KEY', 'ANTHROPIC_AUTH_TOKEN', 'CLAUDE_CODE_OAUTH_TOKEN',
+  'OPENAI_API_KEY', 'OPENROUTER_API_KEY',
+  'AWS_ACCESS_KEY_ID', 'AWS_SECRET_ACCESS_KEY', 'AWS_SESSION_TOKEN', 'AWS_BEARER_TOKEN_BEDROCK',
+  'GOOGLE_APPLICATION_CREDENTIALS', 'ANTHROPIC_FOUNDRY_API_KEY', 'AZURE_OPENAI_API_KEY',
+]);
+
+// ANTHROPIC_AUTH_TOKEN, OPENAI_API_KEY, … — but not *_MAX_OUTPUT_TOKENS (same rule as ask/model-proposal.mjs).
+const SECRET_ENV_RE = /(^|_)(TOKEN|KEY|SECRET|PASSWORD|PASSWD|CREDENTIALS?)(_|$)/i;
+const SECRET_HEADER_RE = /authorization|api[-_]?key|token|secret|cookie|password/i;
+const LOOPBACK_RE =/^https?:\/\/(127\.\d+\.\d+\.\d+|localhost|\[::1\])(:\d+)?(\/|$)/i;
+
+const describe = (v) => `(set, ${String(v).length} chars)`;
+
+/**
+ * @param {{env?:Record<string,string|undefined>, files?:{path:string, kind:'login'|'settings'|'secret', content?:string}[],
+ *          models?:object[], providers?:Record<string,object>, brokerUrl?:string}} o
+ * @returns {string[]} findings, one line each
+ */
+export function findLocalCredentials({ env = {}, files = [], models = [], providers = {}, brokerUrl = '', slotOrigins = [] } = {}) {
+  const out = [];
+  for (const k of MODEL_CREDENTIAL_ENV_KEYS) {
+    const v = env[k];
+    if (typeof v === 'string' && v.trim()) out.push(`env ${k} ${describe(v.trim())}`);
+  }
+  for (const f of files) {
+    if (f.kind === 'login') out.push(`${f.path}: a stored Claude Code sign-in`);
+    else if (f.kind === 'secret') out.push(`${f.path}: a mounted API key`);
+    else if (f.kind === 'settings' && /"apiKeyHelper"\s*:/.test(f.content || '')) out.push(`${f.path}: an apiKeyHelper`);
+  }
+  const brokerPrefix = brokerUrl ? `${brokerUrl.replace(/\/+$/, '')}/p/` : null;
+  for (const m of models || []) {
+    const id = JSON.stringify(m?.id ?? '?');
+    for (const [k, v] of Object.entries(m?.env || {})) {
+      if (typeof v !== 'string' || !v.trim()) continue;
+      if (k === 'ANTHROPIC_BASE_URL') {
+        if (!(brokerPrefix && v.trim().startsWith(brokerPrefix))) out.push(`catalog model ${id}: env ANTHROPIC_BASE_URL routes around the broker`);
+      } else if (SECRET_ENV_RE.test(k)) {
+        out.push(`catalog model ${id}: env ${k} ${/^\$\{[A-Za-z_][A-Za-z0-9_]*\}$/.test(v.trim()) ? `= ${v.trim()}` : describe(v.trim())}`);
+      }
+    }
+    const up = m?.upstream;
+    if (up && typeof up === 'object') {
+      if (typeof up.apiKey === 'string' && up.apiKey.trim()) out.push(`catalog model ${id}: upstream.apiKey`);
+      // A remote endpoint is fine when a broker slot pins its origin (the bridge goes there
+      // through the broker); a keyless local one is reached directly and holds no key.
+      if (typeof up.baseUrl === 'string' && up.baseUrl.trim() && !LOOPBACK_RE.test(up.baseUrl.trim()) && !isPrivateUrl(up.baseUrl)) {
+        let origin = null;
+        try { origin = new URL(up.baseUrl).origin; } catch { /* reported below */ }
+        if (!origin || !slotOrigins.includes(origin)) {
+          out.push(`catalog model ${id}: upstream.baseUrl ${origin ? new URL(origin).host : up.baseUrl} has no credential slot on the broker (add one to WORCA_BROKER_SLOTS_FILE)`);
+        }
+      }
+      for (const [h, v] of Object.entries(up.headers || {})) {
+        if (SECRET_HEADER_RE.test(h) && typeof v === 'string' && v.trim()) out.push(`catalog model ${id}: upstream.headers ${h}`);
+      }
+    }
+  }
+  for (const [name, p] of Object.entries(providers || {})) {
+    for (const k of ['apiKey', 'githubToken']) {
+      if (p && typeof p[k] === 'string' && p[k].trim()) out.push(`providers.${name}.${k}`);
+    }
+  }
+  return out;
+}
+
+function isPrivateUrl(u) {
+  try {
+    const h = new URL(u).hostname.toLowerCase().replace(/^\[|\]$/g, '');
+    if (h === 'host.docker.internal' || h.endsWith('.internal') || h.endsWith('.local') || !h.includes('.')) return true;
+    const m = /^(\d+)\.(\d+)\.\d+\.\d+$/.exec(h);
+    if (!m) return false;
+    const [a, b] = [Number(m[1]), Number(m[2])];
+    return a === 10 || a === 127 || (a === 192 && b === 168) || (a === 172 && b >= 16 && b <= 31);
+  } catch { return false; }
+}
+
+/** The files the guard looks at under each HOME that agents or the server run with. */
+export function credentialFiles(homes, { exists = existsSync, read = (p) => readFileSync(p, 'utf8') } = {}) {
+  const out = [];
+  for (const home of [...new Set(homes.filter(Boolean))]) {
+    const dir = process.env.CLAUDE_CONFIG_DIR && home === process.env.HOME ? process.env.CLAUDE_CONFIG_DIR : join(home, '.claude');
+    const login = join(dir, '.credentials.json');
+    if (exists(login)) out.push({ path: login, kind: 'login' });
+    const settings = join(dir, 'settings.json');
+    if (exists(settings)) {
+      let content = '';
+      try { content = read(settings); } catch { content = ''; }
+      out.push({ path: settings, kind: 'settings', content });
+    }
+  }
+  if (exists('/run/secrets/anthropic_api_key')) out.push({ path: '/run/secrets/anthropic_api_key', kind: 'secret' });
+  return out;
+}
+
+/** The one-paragraph refusal the server prints before exiting 78. */
+export function guardMessage(findings, keyPage) {
+  return [
+    'worca: the credential broker is on, but model credentials are still reachable by agents:',
+    ...findings.map((f) => `worca:   ${f}`),
+    `worca: remove them from worca (they belong in the broker${keyPage ? `: ${keyPage}` : ''}), then restart.`,
+  ].join('\n');
+}

package/src/core/broker-routing.mjs

@@ -0,0 +1,138 @@
+// src/core/broker-routing.mjs
+// Which credential-broker slot a model spends from (plans/credential-broker-design.html
+// §5.3). The broker's slots each pin one provider origin; a model reaches a slot by:
+//   - Copilot            -> the broker's Copilot slot (auth 'copilot')
+//   - a bridged provider -> the slot whose pinned origin equals the base URL's origin
+//                           (api.openai.com -> openai, openrouter.ai -> openrouter, a
+//                           gateway named in the broker's slots file -> that slot)
+//   - a keyless local endpoint (llama.cpp, Ollama, LM Studio on this machine or network)
+//                        -> no slot: it holds no key, the bridge reaches it directly
+//   - anything else      -> the anthropic slot, or the slot its ANTHROPIC_BASE_URL names
+// Synchronous: reads the broker info cached at boot and on every spawn (broker-client.mjs).
+import { brokerEnabled, cachedBrokerInfo, slotOfBaseUrl } from './broker-client.mjs';
+import { isLocalBaseUrl } from './model-env.mjs';
+import { findBridgedEntry } from './bridge/registry.mjs';
+import { providerConfig, listGlobalModels } from './settings.mjs';
+import { listPluginModels } from './plugin-models.mjs';
+
+const DEFAULT_BASE = Object.freeze({ openai: 'https://api.openai.com/v1', anthropic: 'https://api.anthropic.com' });
+
+/**
+ * {slot, prefix} for a base URL whose origin a (non-Copilot) slot pins, else null. Pure.
+ * One host can serve both APIs (a gateway): a slot of the wanted `protocol` wins.
+ */
+export function slotForBaseUrl(baseUrl, slots = [], protocol = null) {
+  let u;
+  try { u = new URL(String(baseUrl || '').trim()); } catch { return null; }
+  const same = slots.filter((x) => x.auth !== 'copilot' && x.auth !== 'github-user' && x.upstream === u.origin);
+  const s = (protocol && same.find((x) => x.protocol === protocol)) || same[0];
+  if (!s) return null;
+  return { slot: s.id, prefix: u.pathname.replace(/\/+$/, '') };
+}
+
+/**
+ * How a bridged entry's upstream reaches its provider with the broker on. Pure given `slots`.
+ * @param {{provider:string, baseUrl?:string}} upstream
+ * @returns {{slot:string, prefix:string, copilot?:boolean}|{keyless:true}|{error:string}}
+ */
+export function routeUpstream(upstream, { slots = [], providerBaseUrl = null } = {}) {
+  if (!upstream) return { slot: 'anthropic', prefix: '' };
+  if (upstream.provider === 'copilot') {
+    const s = slots.find((x) => x.auth === 'copilot');
+    return s ? { slot: s.id, prefix: '', copilot: true } : { error: 'the credential broker has no GitHub Copilot slot' };
+  }
+  const base = upstream.baseUrl || providerBaseUrl || DEFAULT_BASE[upstream.provider] || null;
+  if (!base) return { error: `provider ${upstream.provider} has no base URL` };
+  // A slot that pins this origin wins, even for a local address: the operator put that
+  // server behind the broker (a llama-server with --api-key, say). Otherwise a local
+  // endpoint holds no key and is reached directly.
+  const protocol = upstream.api === 'anthropic' || upstream.provider === 'anthropic' ? 'anthropic' : 'openai';
+  const hit = slotForBaseUrl(base, slots, protocol);
+  if (hit) return hit;
+  if (isLocalBaseUrl(base)) return { keyless: true };
+  let host = base;
+  try { host = new URL(base).host; } catch { /* keep */ }
+  return { error: `no credential slot for ${host}: the broker's operator adds it to WORCA_BROKER_SLOTS_FILE` };
+}
+
+/** The broker's slots from the cached info ([] before the first contact). */
+export function brokerSlots() {
+  return cachedBrokerInfo()?.slots || [];
+}
+
+/** routeUpstream against the live broker info, with the provider's own base URL as the fallback. */
+export function routeBridgedUpstream(upstream) {
+  let providerBaseUrl = null;
+  try { providerBaseUrl = upstream && upstream.provider !== 'copilot' ? (providerConfig(upstream.provider).baseUrl || null) : null; } catch { /* none */ }
+  return routeUpstream(upstream, { slots: brokerSlots(), providerBaseUrl });
+}
+
+/** Every non-empty `model` string anywhere in a run's manifest (v1 stepper or v2 graph). Pure. */
+export function manifestModels(manifest, out = new Set(), depth = 0) {
+  if (!manifest || typeof manifest !== 'object' || depth > 8) return out;
+  if (Array.isArray(manifest)) { for (const x of manifest) manifestModels(x, out, depth + 1); return out; }
+  for (const [k, v] of Object.entries(manifest)) {
+    if (k === 'model' && typeof v === 'string' && v.trim()) out.add(v.trim());
+    else if (v && typeof v === 'object') manifestModels(v, out, depth + 1);
+  }
+  return out;
+}
+
+/**
+ * Which credentials a set of models needs, and which of them a person lacks. Pure.
+ * @param {string[]} modelIds
+ * @param {(id:string)=>({slot:string}|{keyless:true}|{error:string}|null)} slotOf
+ * @param {{id:string,label:string,state:string}[]} status  the person's slots (broker)
+ * @returns {{missing:{slot:string,label:string,state:string,models:string[]}[], errors:string[]}}
+ */
+export function missingCredentials(modelIds, slotOf, status = []) {
+  const need = new Map();
+  const errors = [];
+  for (const id of new Set(modelIds)) {
+    const r = slotOf(id);
+    if (!r || r.keyless) continue;
+    if (r.error) { errors.push(`${id}: ${r.error}`); continue; }
+    if (!need.has(r.slot)) need.set(r.slot, []);
+    need.get(r.slot).push(id);
+  }
+  const byId = new Map(status.map((s) => [s.id, s]));
+  const missing = [];
+  for (const [slot, models] of need) {
+    const s = byId.get(slot);
+    if (s && ['set', 'keyless', 'operator'].includes(s.state)) continue;
+    missing.push({ slot, label: s?.label || slot, state: s?.state || 'missing', models });
+  }
+  return { missing, errors };
+}
+
+/** One sentence naming what's missing, for a refusal. */
+export function describeMissing({ missing, errors }, keyPage) {
+  const parts = missing.map((m) => `${m.label} (${m.state === 'invalid' ? 'rejected by the provider' : 'not added'}; needed by ${m.models.join(', ')})`);
+  const where = keyPage ? ` Add them on the key page (${keyPage}), then start again.` : '';
+  return [
+    parts.length ? `missing credentials: ${parts.join('; ')}.${where}` : '',
+    errors.length ? `models that can't reach a credential: ${errors.join('; ')}.` : '',
+  ].filter(Boolean).join(' ');
+}
+
+/**
+ * The slot a catalog model spends from, for badges and the start-of-run check.
+ * @returns {{slot:string}|{keyless:true}|{error:string}|null} null with the broker off
+ */
+export function modelSlot(modelId) {
+  if (!brokerEnabled()) return null;
+  const id = typeof modelId === 'string' ? modelId.trim() : '';
+  if (!id) return null;
+  const bridged = findBridgedEntry(id);
+  if (bridged) {
+    const r = routeBridgedUpstream(bridged.upstream);
+    return r.slot ? { slot: r.slot } : r;
+  }
+  const lc = id.toLowerCase();
+  let entry = null;
+  try { entry = listGlobalModels().find((m) => m.id.toLowerCase() === lc) || listPluginModels().find((m) => m.id.toLowerCase() === lc) || null; } catch { entry = null; }
+  const base = entry && entry.env && typeof entry.env.ANTHROPIC_BASE_URL === 'string' ? entry.env.ANTHROPIC_BASE_URL : null;
+  if (!base) return { slot: 'anthropic' };
+  const s = slotOfBaseUrl(base);
+  return s ? { slot: s } : { error: 'this model routes around the credential broker' };
+}

package/src/core/claude-auth.mjs

@@ -0,0 +1,29 @@
+// src/core/claude-auth.mjs
+// "Did this Claude failure happen because the CLI is signed out?" — for the
+// surfaces that only learn it after the spawn (Ask Worca, run overview, model
+// Test). The CLI's own error text is not reliable: signed out, a first-party
+// model id can fail as `[claude-code:unrecognized_model]` instead of "Not
+// logged in". So a failed run on a model the CLI serves itself (not routed to
+// an endpoint or the bridge) asks preflight's probeClaudeAuth, which is cheap
+// (remembered 60 s) and says 'signed-out' only when `claude auth status` does.
+import { isClaudeSignedOutError, probeClaudeAuth } from './preflight.mjs';
+import { modelHasBaseUrlRouting } from './config.mjs';
+import { configuredClaudeBin } from './onboarding.mjs';
+
+/**
+ * Never throws.
+ * @param {{message?:string, model?:string, bin?:string, probe?:typeof probeClaudeAuth, routed?:(model:string)=>boolean}} o
+ *   `probe` / `routed` are injectable for tests.
+ * @returns {Promise<boolean>}
+ */
+export async function failedBecauseSignedOut({
+  message, model, bin = configuredClaudeBin(), probe = probeClaudeAuth, routed = modelHasBaseUrlRouting,
+} = {}) {
+  try {
+    if (isClaudeSignedOutError(message)) return true;
+    if (model && routed(model)) return false;   // the endpoint / bridge authenticates, not the CLI sign-in
+    // Fresh, not the remembered answer: a failure is rare, and a stale one would
+    // misname it for up to a minute after signing in or out.
+    return (await probe({ bin, force: true })).state === 'signed-out';
+  } catch { return false; }
+}