@worca/app 1.5.0 → 1.6.0-rc.1

package/src/core/policy/registry.mjs

@@ -15,6 +15,8 @@
 // accepted on read, downgraded to soft with a warning — a later version enforces it without a
 // format change). Every field lists the kinds it accepts; the editor disables the rest.
 
+import { domainError } from '../web-allowlist.mjs';
+
 export const POLICY_SCHEMA = 1;
 export const KINDS = Object.freeze(['default', 'soft', 'hard']);
 export const ON_BREACH = Object.freeze(['pause', 'warn']);
@@ -41,6 +43,10 @@ export const FIELDS = Object.freeze([
   { key: 'cost.humanRateUsd', group: 'cost', label: 'Developer rate (USD/h)', help: 'Prices the estimated human hours behind "Saved". A developer\'s own rate wins when set.', type: 'usd', kinds: ['default'], local: 'humanRateUsdPerHour' },
   { key: 'ask.maxTurns', group: 'ask', label: 'Turn limit', help: 'Ask Worca agentic turns per chat turn.', type: 'int', min: 1, max: 500, kinds: ['default'], local: 'askMaxTurns' },
   { key: 'ask.maxBudgetUsd', group: 'ask', label: 'Per-turn cost cap (USD)', help: 'Ask Worca per-turn cap; null means no cap.', type: 'usd-or-null', min: 0.1, max: 100, kinds: ['default'], local: 'askMaxBudgetUsd' },
+  // The two web fields only ever NARROW, and bind (no "go past it"): web access is opt-in per developer, and the policy
+  // branch is writable by whoever can push to the repo — so a policy may switch it off or cap the hosts, never widen.
+  { key: 'ask.webEnabled', group: 'ask', label: 'Web access', help: 'Off switches Ask Worca web access off for chats pinned to this project. A policy can never switch it on — each developer opts in.', type: 'bool', kinds: ['soft'], offOnly: true, local: 'askWeb.enabled' },
+  { key: 'ask.webAllowedDomains', group: 'ask', label: 'Web allowlist', help: 'The most a developer may allow (example.com or *.example.com): hosts outside this list are dropped from their own Ask web allowlist. It never adds a host.', type: 'string[]', kinds: ['soft'], domains: true, local: 'askWeb.allowedDomains' },
   { key: 'guardrails.default', group: 'guardrails', label: 'Default set', help: 'What the New pipeline picker starts on. A built-in id, a user set id, or gp:<name> for a set this policy ships.', type: 'string', kinds: ['default'] },
   { key: 'guardrails.minimum', group: 'guardrails', label: 'Minimum tier', help: 'A run whose set ranks below this warns and is recorded.', type: 'enum', values: TIERS, kinds: ['soft'] },
   { key: 'models.allowed', group: 'models', label: 'Allowed models', help: 'A chosen step model outside this list warns and is recorded. Others still run.', type: 'string[]', kinds: ['soft'] },
@@ -98,13 +104,17 @@ export function validateValue(meta, value) {
       if (value === null) return null;
       return finiteNum(value) && value >= (meta.min ?? 0) && value <= (meta.max ?? Infinity) ? null : `must be null or a number between ${meta.min} and ${meta.max}`;
     case 'int': return Number.isInteger(value) && value >= (meta.min ?? -Infinity) && value <= (meta.max ?? Infinity) ? null : `must be an integer between ${meta.min} and ${meta.max}`;
-    case 'bool': return typeof value === 'boolean' ? null : 'must be true or false';
+    case 'bool':
+      if (typeof value !== 'boolean') return 'must be true or false';
+      return meta.offOnly && value !== false ? 'a team policy can only switch web access off — turning it on is each developer\'s own choice' : null;
     case 'enum': return meta.values.includes(value) ? null : `must be one of ${meta.values.join(' | ')}`;
     case 'string': return typeof value === 'string' && value.trim() && value.length <= TEXT_MAX ? null : 'must be a non-empty string';
     case 'semver': return typeof value === 'string' && SEMVER_RE.test(value) ? null : 'must be a version like 1.4.0';
     case 'string[]':
       if (!Array.isArray(value)) return 'must be a list';
-      return value.every((x) => typeof x === 'string' && x.trim() && x.length <= TEXT_MAX) ? null : 'every entry must be a non-empty string';
+      if (!value.every((x) => typeof x === 'string' && x.trim() && x.length <= TEXT_MAX)) return 'every entry must be a non-empty string';
+      if (meta.domains) { for (const x of value) { const e = domainError(x); if (e) return e; } }
+      return null;
     case 'steps': {
       if (!isPlainObject(value)) return 'must be an object of role → { model, effort }';
       for (const [role, sel] of Object.entries(value)) {

package/src/core/preflight.mjs

@@ -470,3 +470,119 @@ export async function probeClaudeCapabilities(bin = 'claude') {
   const version = raw ? (/(\d+\.\d+\.\d+)/.exec(raw)?.[1] ?? raw.split(/\s+/)[0] ?? null) : null;
   return { mcpConfig: !!help && help.includes('--mcp-config'), version };
 }
+
+// ── Is the Claude Code CLI signed in? ─────────────────────────────────────────
+// Finding the binary is not enough: a signed-out CLI starts, then every agent
+// exits 1 with "Not logged in" (a workspace scan got ~30 s into its first phase
+// before failing). probeClaudeAuth asks `claude auth status` up front.
+//
+// Only 'signed-out' may ever block anything. 'unknown' — an older CLI without the
+// `auth` command, a hang, unparseable output — never does, so a probe gap can
+// only fall back to today's behaviour, never refuse a working setup.
+
+/** Env vars that authenticate the CLI without a stored sign-in, which `claude
+ *  auth status` does not (reliably) report: a custom endpoint or the model bridge
+ *  (ANTHROPIC_BASE_URL + ANTHROPIC_AUTH_TOKEN), an API key or OAuth token, and
+ *  the cloud transports (Bedrock / Vertex / Foundry). */
+export const CLAUDE_AUTH_ENV_KEYS = Object.freeze([
+  'ANTHROPIC_BASE_URL', 'ANTHROPIC_AUTH_TOKEN', 'ANTHROPIC_API_KEY', 'CLAUDE_CODE_OAUTH_TOKEN',
+]);
+export const CLAUDE_AUTH_ENV_FLAGS = Object.freeze([
+  'CLAUDE_CODE_USE_BEDROCK', 'CLAUDE_CODE_USE_VERTEX', 'CLAUDE_CODE_USE_FOUNDRY',
+]);
+
+const flagOn = (v) => !!v && v !== '0' && String(v).toLowerCase() !== 'false';
+
+/** The first env var that signs the CLI in on its own, or null. Pure. */
+export function claudeAuthFromEnv(env = process.env) {
+  for (const k of CLAUDE_AUTH_ENV_KEYS) if (typeof env[k] === 'string' && env[k].trim()) return k;
+  for (const k of CLAUDE_AUTH_ENV_FLAGS) if (flagOn(env[k])) return k;
+  return null;
+}
+
+/**
+ * Read `claude auth status` output (JSON by default, `--text` on some builds).
+ * @param {string} text  stdout + stderr
+ * @returns {'signed-in'|'signed-out'|'unknown'}
+ */
+export function parseClaudeAuthStatus(text) {
+  const s = String(text || '').trim();
+  if (!s) return 'unknown';
+  const json = /\{[\s\S]*\}/.exec(s);
+  if (json) {
+    try {
+      const o = JSON.parse(json[0]);
+      if (o && typeof o.loggedIn === 'boolean') return o.loggedIn ? 'signed-in' : 'signed-out';
+    } catch { /* fall through to the text forms */ }
+  }
+  if (/\bnot (logged|signed) in\b|\blogged out\b|\bsigned out\b/i.test(s)) return 'signed-out';
+  if (/\b(logged|signed) in\b/i.test(s)) return 'signed-in';
+  return 'unknown';
+}
+
+/** Run a command with any exit code: resolves {code, out} (stdout+stderr), or
+ *  null on a spawn failure / timeout. `auth status` exits non-zero when signed out. */
+function execAnyExit(cmd, args, { timeout = 8000 } = {}) {
+  return new Promise((resolveP) => {
+    let child;
+    try { child = spawn(cmd, args, { stdio: ['ignore', 'pipe', 'pipe'] }); }
+    catch { resolveP(null); return; }
+    let out = '';
+    let settled = false;
+    const done = (val) => { if (settled) return; settled = true; clearTimeout(timer); resolveP(val); };
+    const timer = setTimeout(() => { try { child.kill('SIGKILL'); } catch { /* ignore */ } done(null); }, timeout);
+    child.stdout?.on('data', (d) => { out += d.toString(); });
+    child.stderr?.on('data', (d) => { out += d.toString(); });
+    child.on('error', () => done(null));
+    child.on('close', (code) => done({ code, out }));
+  });
+}
+
+/** The refusal every surface shows for a signed-out CLI (the API's `code`, and its text). */
+export const CLAUDE_SIGNED_OUT_CODE = 'claude-signed-out';
+export const CLAUDE_SIGNED_OUT_MESSAGE = "Claude Code isn't signed in. Run `claude` in a terminal and type /login, then try again.";
+
+/** Is `message` the CLI's own signed-out failure ("Not logged in · Please run
+ *  /login")? For surfaces that only learn it after the spawn. Pure. */
+export function isClaudeSignedOutError(message) {
+  return /\bnot logged in\b|please run \/login/i.test(String(message || ''));
+}
+
+export const CLAUDE_AUTH_TTL_MS = 60_000;
+const _authCache = new Map();   // exe -> { at, promise }
+
+/** Test seam: forget remembered answers. */
+export function clearClaudeAuthCache() { _authCache.clear(); }
+
+/**
+ * Is the Claude Code CLI signed in? Never throws.
+ *  - mock mode: never starts claude → {state:'unknown', source:'mock'}
+ *  - an auth env var (see CLAUDE_AUTH_ENV_KEYS / _FLAGS) → {state:'signed-in', source:'env'}
+ *  - otherwise `claude auth status`, remembered per binary for CLAUDE_AUTH_TTL_MS
+ *    (concurrent callers share one spawn); `force` skips the remembered answer.
+ * @param {{bin?:string, env?:Record<string,string|undefined>, mock?:boolean, force?:boolean,
+ *   now?:()=>number, run?:(exe:string, args:string[])=>Promise<{code:number,out:string}|null>}} [o]
+ * @returns {Promise<{state:'signed-in'|'signed-out'|'unknown', source:'mock'|'env'|'cli', detail:string|null}>}
+ */
+export async function probeClaudeAuth({
+  bin = 'claude', env = process.env, mock, force = false, now = Date.now, run = execAnyExit,
+} = {}) {
+  const isMock = mock ?? (flagOn(env.WORCA_MOCK ?? env.ORCH_MOCK));
+  if (isMock) return { state: 'unknown', source: 'mock', detail: null };
+  // Credential broker (broker-client.mjs): the CLI is signed in per spawn with a
+  // broker token, never by worca's env or a stored login. Whether the PERSON has a
+  // key is the broker's per-slot status, not this probe's question.
+  if (typeof env.WORCA_BROKER_URL === 'string' && env.WORCA_BROKER_URL.trim()) return { state: 'signed-in', source: 'broker', detail: 'broker' };
+  const envKey = claudeAuthFromEnv(env);
+  if (envKey) return { state: 'signed-in', source: 'env', detail: envKey };
+  const name = bin && String(bin).trim() ? String(bin).trim() : 'claude';
+  const exe = resolveClaudeBin(name).bin;
+  const hit = _authCache.get(exe);
+  if (!force && hit && now() - hit.at < CLAUDE_AUTH_TTL_MS) return hit.promise;
+  const promise = Promise.resolve()
+    .then(() => run(exe, ['auth', 'status']))
+    .then((r) => ({ state: r ? parseClaudeAuthStatus(r.out) : 'unknown', source: 'cli', detail: null }))
+    .catch(() => ({ state: 'unknown', source: 'cli', detail: null }));
+  _authCache.set(exe, { at: now(), promise });
+  return promise;
+}

package/src/core/recoverable-error.mjs

@@ -24,6 +24,13 @@ export function classifyError(err) {
   // stamp — including an explicit null — is authoritative.
   if (err && typeof err === 'object' && err.errorClass !== undefined) return err.errorClass;
   const msg = String((err && err.message) || err || '');
+  // The credential broker's refusals (a missing or rejected key, a dead token, nobody to
+  // bill) arrive as a 403 the CLI prints as "Failed to authenticate. API Error: 403
+  // worca-broker: …" — no 401, no authentication_error left in the text. Same class.
+  if (BROKER_AUTH_RE.test(msg)) return 'auth';
+  // OpenRouter's daily allowance of `:free` requests is spent: only its daily reset clears
+  // it, so it pauses like the session limit below instead of retrying as a 429.
+  if (FREE_DAILY_RE.test(msg)) return 'usage_limit';
   if (/\b401\b|invalid authentication|authentication_error|please run .*login|not logged in/i.test(msg)) return 'auth';
   // Session/usage caps that only clear after a multi-hour reset (the CLI prints
   // "You've hit your session limit · resets 6pm"). Distinct from rate_limit (a
@@ -37,6 +44,94 @@ export function classifyError(err) {
   return null;
 }
 
+// OpenRouter's `:free` models run on a donated provider pool that every OpenRouter
+// user shares: its 429 ("temporarily rate-limited upstream", limit_source
+// upstream_provider_shared_pool) arrives for a single request, whatever worca's
+// max-concurrent setting. Still class rate_limit (a retry can clear it); only the
+// final pause message changes, so it names the real cause and the real fixes.
+const SHARED_POOL_RE = /rate-limited upstream|upstream_provider_shared_pool/i;
+
+/** Whether a rate-limit error came from a provider's shared (free) pool. */
+export function isSharedPoolRateLimit(err) {
+  const msg = String((err && typeof err === 'object' ? err.message : err) ?? '');
+  return SHARED_POOL_RE.test(msg);
+}
+
+/** The fix text a rate-limit pause carries ('' when there is nothing specific to say). */
+export function rateLimitHint(err) {
+  if (!isSharedPoolRateLimit(err)) return '';
+  return "the provider's shared free pool is saturated — every user of this free model shares it, " +
+    "so this is not worca's max-concurrent setting. Use the paid variant, add your own provider key " +
+    '(BYOK) on the provider, or give the model a fallback model list';
+}
+
+// OpenRouter's daily allowance for `:free` models (1000 requests a day on an account that
+// bought $10 of credit, 50 below): its 429 names the limit ("Rate limit exceeded:
+// free-models-per-day-high-balance", limit_source openrouter_free_tier_daily) and clears
+// only at the daily reset, 00:00 UTC. The bridge adds "resets <ISO>" when OpenRouter says.
+const FREE_DAILY_RE = /openrouter_free_tier_daily|free-models-per-day/i;
+const FREE_DAILY_RESET_RE = /resets (\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z)/;
+
+/** Whether an error is OpenRouter's spent daily allowance of free-model requests. */
+export function isFreeDailyLimit(err) {
+  const msg = String((err && typeof err === 'object' ? err.message : err) ?? '');
+  return FREE_DAILY_RE.test(msg);
+}
+
+/** When the free-model allowance comes back (ms): the reset the error names, else the next 00:00 UTC. */
+export function freeDailyResetAt(err, now = Date.now()) {
+  const msg = String((err && typeof err === 'object' ? err.message : err) ?? '');
+  const m = FREE_DAILY_RESET_RE.exec(msg);
+  const named = m ? Date.parse(m[1]) : NaN;
+  if (Number.isFinite(named) && named > now) return named;
+  const d = new Date(now);
+  return Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate() + 1);
+}
+
+/** "3h 12m" / "12m" / "under a minute". Pure. */
+export function untilText(ms) {
+  const min = Math.floor(Math.max(0, ms) / 60_000);
+  if (min < 1) return 'under a minute';
+  const h = Math.floor(min / 60);
+  return h ? `${h}h ${min % 60}m` : `${min}m`;
+}
+
+/**
+ * The pause text for a spent free-model allowance ('' for any other error): what ran out,
+ * when it comes back, and the two ways on. `used`/`limit` when a key reading has them.
+ */
+export function freeDailyHint(err, { now = Date.now(), used = null, limit = null } = {}) {
+  if (!isFreeDailyLimit(err)) return '';
+  const at = freeDailyResetAt(err, now);
+  const hhmm = new Date(at).toISOString().slice(11, 16);
+  const count = Number.isFinite(limit) && limit > 0 ? ` (${Number.isFinite(used) ? used : limit} / ${limit})` : '';
+  return `OpenRouter's free-model requests for today are used up${count} — they reset at ${hhmm} UTC, in ${untilText(at - now)}. ` +
+    'Resume after the reset, or switch this step to a paid model';
+}
+
+// The credential broker (src/broker/) answers in the provider's own error envelope
+// with a `worca-broker:` message, so its refusals already land in the right class:
+// a missing/rejected key or a dead token is `auth` (401), a spent budget is `quota`
+// (its message says "quota reached"), a busy slot is `rate_limit` (429). Only the
+// pause text differs: it says what to do, which is never "sign in to Claude Code".
+const BROKER_RE = /worca-broker:/i;
+/** The broker's credential refusals (classifyError reads them as `auth`). */
+const BROKER_AUTH_RE = /worca-broker: (?:no .+ for \S+|your .+ was rejected|.+ key for \S+: |token expired or revoked|no token|this action has no signed-in person|cannot get a token)/i;
+
+/** Whether an error came from the credential broker. */
+export function isBrokerError(err) {
+  const msg = String((err && typeof err === 'object' ? err.message : err) ?? '');
+  return BROKER_RE.test(msg);
+}
+
+/** The fix text a pause caused by the broker carries ('' for any other error). */
+export function brokerHint(err, cls = classifyError(err)) {
+  if (!isBrokerError(err)) return '';
+  if (cls === 'auth') return 'the credential broker refused this spawn: add or replace the key on the key page (Settings › My credentials links to it), then resume';
+  if (cls === 'quota') return 'a spending cap on the credential broker was reached: raise it on the key page or wait for the reset, then resume';
+  return '';
+}
+
 // Precedence for folding per-line classes into the one whole-text class — the
 // SAME order as the regex chain above. First-match-wins there equals
 // strongest-class-wins here, because every per-line match (the patterns are

package/src/core/recovery-backoff.mjs

@@ -0,0 +1,84 @@
+// src/core/recovery-backoff.mjs
+// The ONE backoff rule for recoverable errors (recoverable-error.mjs classes). The
+// node retry loop (run-harness#_backoff) and worca's own helper calls — the Auto
+// classifier, title generation — share it, so "how long does worca wait on a 429"
+// has one answer.
+//
+// A rate limit waits longer than a network blip: a provider's 429 (a shared free
+// pool, a per-minute cap) takes seconds to clear, and the CLI has already retried
+// the request itself before exiting. Each wait honours a retry-after hint when the
+// message carries one, and is capped so three retries stay within ~2 minutes.
+// WORCA_RECOVERY_BACKOFF_MS overrides the base for every class (tests pin it to 0).
+import { classifyError } from './recoverable-error.mjs';
+
+export const RATE_LIMIT_BACKOFF_BASE_MS = 5_000;
+export const NETWORK_BACKOFF_BASE_MS = 1_000;
+/** Per-wait cap: 3 capped waits stay within ~2 minutes. */
+export const MAX_RECOVERY_WAIT_MS = 40_000;
+/** Retries a helper call gets (withRecoveryRetry) — the node loop's own budget is RECOVERY_MAX_AUTO_ATTEMPTS. */
+export const HELPER_RETRY_ATTEMPTS = 3;
+/** The classes a wait can clear. auth/quota/usage_limit never clear by waiting. */
+export const RETRYABLE_CLASSES = Object.freeze(['rate_limit', 'network']);
+
+/** The first wait for a class, before doubling. */
+export function backoffBaseMs(cls, env = process.env) {
+  const n = Number(env?.WORCA_RECOVERY_BACKOFF_MS);
+  if (env?.WORCA_RECOVERY_BACKOFF_MS != null && env.WORCA_RECOVERY_BACKOFF_MS !== '' && Number.isFinite(n) && n >= 0) return n;
+  return cls === 'rate_limit' ? RATE_LIMIT_BACKOFF_BASE_MS : NETWORK_BACKOFF_BASE_MS;
+}
+
+/** A retry-after hint in an error message ("retry-after: 12", "retry after 3 seconds", "1500ms"), in ms; null when absent. */
+export function retryAfterMs(err) {
+  const msg = String((err && typeof err === 'object' ? err.message : err) ?? '');
+  const m = /retry[- ]after[:=\s]*(\d+(?:\.\d+)?)\s*(ms|milliseconds?|s|secs?|seconds?)?/i.exec(msg);
+  if (!m) return null;
+  const n = Number(m[1]);
+  if (!Number.isFinite(n) || n < 0) return null;
+  return /^m/i.test(m[2] || '') ? Math.round(n) : Math.round(n * 1000);
+}
+
+/** The wait before retry `attempt` (1-based): base·2^(attempt-1), at least a retry-after hint, at most MAX_RECOVERY_WAIT_MS. */
+export function recoveryDelayMs({ cls, attempt = 1, err = null, env = process.env } = {}) {
+  const base = backoffBaseMs(cls, env);
+  if (!base) return 0;
+  const exp = base * Math.pow(2, Math.max(0, attempt - 1));
+  const hint = retryAfterMs(err) ?? 0;
+  return Math.min(MAX_RECOVERY_WAIT_MS, Math.max(exp, hint));
+}
+
+/** Wait `ms`, resolving early (never rejecting) when `signal` aborts. */
+export function sleepAbortable(ms, signal) {
+  if (!ms || ms <= 0 || signal?.aborted) return Promise.resolve();
+  return new Promise((res) => {
+    // Not unref'd: a helper call waiting out a 429 is real pending work — an
+    // unref'd timer would let a headless CLI process exit mid-wait.
+    const t = setTimeout(done, ms);
+    function done() { clearTimeout(t); signal?.removeEventListener?.('abort', done); res(); }
+    signal?.addEventListener?.('abort', done, { once: true });
+  });
+}
+
+/**
+ * Run `fn`, retrying it on a retryable class (rate_limit / network) with the
+ * shared backoff. Anything else — and the last error once `attempts` retries are
+ * spent, or once `signal` aborts — is rethrown unchanged.
+ * @param {() => Promise<any>} fn
+ * `classes` narrows what is retried (title generation retries only rate_limit: an
+ * unspawnable CLI is stamped network, and a cosmetic call should not wait it out).
+ * @param {{attempts?:number, classes?:string[], signal?:AbortSignal, env?:object,
+ *          onRetry?:(w:{attempt:number, cls:string, delayMs:number, err:Error}) => void}} [o]
+ */
+export async function withRecoveryRetry(fn, { attempts = HELPER_RETRY_ATTEMPTS, classes = RETRYABLE_CLASSES, signal, env = process.env, onRetry } = {}) {
+  for (let attempt = 1; ; attempt++) {
+    try {
+      return await fn();
+    } catch (err) {
+      const cls = classifyError(err);
+      if (attempt > attempts || !classes.includes(cls) || signal?.aborted || err?.name === 'AbortError') throw err;
+      const delayMs = recoveryDelayMs({ cls, attempt, err, env });
+      try { onRetry?.({ attempt, cls, delayMs, err }); } catch { /* a logger must not break the retry */ }
+      await sleepAbortable(delayMs, signal);
+      if (signal?.aborted) throw err;
+    }
+  }
+}

package/src/core/redact.mjs

@@ -0,0 +1,25 @@
+// src/core/redact.mjs
+// Broker spawn tokens in agent output (plans/credential-broker-design.html §6.10).
+// A token only works on the broker's private port and only while its spawn lives,
+// but an agent can still print its own env into a transcript every teammate sees.
+// The `wbt_` prefix makes it recognisable; this removes it wherever worca stores or
+// shows agent output. Pure, cheap on text without the prefix.
+
+export const BROKER_TOKEN_RE = /\bwbt_[A-Za-z0-9_-]{20,}/g;
+export const REDACTED_TOKEN = 'wbt_[redacted]';
+
+/** `text` with every broker token replaced. Non-strings come back unchanged. */
+export function redactSecrets(text) {
+  if (typeof text !== 'string' || !text.includes('wbt_')) return text;
+  return text.replace(BROKER_TOKEN_RE, REDACTED_TOKEN);
+}
+
+/** Deep copy of a JSON-like value with every string redacted (events, tool results). */
+export function redactDeep(value, depth = 0) {
+  if (typeof value === 'string') return redactSecrets(value);
+  if (depth > 32 || value === null || typeof value !== 'object') return value;
+  if (Array.isArray(value)) return value.map((v) => redactDeep(v, depth + 1));
+  const out = {};
+  for (const [k, v] of Object.entries(value)) out[k] = redactDeep(v, depth + 1);
+  return out;
+}

package/src/core/run-context.mjs

@@ -41,6 +41,7 @@ import { contextMaxBytesPerFile, contextMaxBytesTotal, skillMount, defaultRoot }
 import { readRunManifest, updateRunManifest } from './run-manifest.mjs';
 import { isValidSkillName } from './skills.mjs';
 import { mergePermissionRules } from './guardrails.mjs';
+import { screenMcpSecrets, mcpSecretsMode } from './mcp-secrets.mjs';
 
 /**
  * The `--allowedTools` grant shape this build emits for merged MCP servers.
@@ -1138,6 +1139,11 @@ export async function assembleRunContext({
     members: liveMembers, projectsRoot: rootUsable ? projectsRoot : null, homeDir, isWorkspace, platform,
   });
   for (const w of mcp.warnings) warnings.push(w);
+  // Secrets in these definitions reach the run's agents (mcp-secrets.mjs): with the
+  // credential broker on they are left out by default, otherwise named.
+  const screened = screenMcpSecrets(mcp.servers, { mode: mcpSecretsMode() });
+  for (const w of screened.warnings) warnings.push(w);
+  mcp.servers = screened.servers;
   const written = Object.keys(mcp.servers).sort();
   let mcpConfigPath = null;
   if (written.length) {

package/src/core/run-harness.mjs

@@ -55,8 +55,8 @@ import {
   probeClaudeCapabilities, explainUnspawnableClaude,
 } from './preflight.mjs';
 import { fanoutCap, mapWithCap } from './fanout.mjs';
-import { resolveStepModels, observeModelCost, resolveModelCost, modelCostConfig, readTeamMetricsPrefs } from './config.mjs';
-import { bridgeCallsFor, forgetBridgeTag } from './bridge/telemetry.mjs';
+import { resolveStepModels, observeModelCost, resolveModelCost, modelCostConfig, readTeamMetricsPrefs, catalogHasModel } from './config.mjs';
+import { bridgeCallsFor, bridgeCostFor, forgetBridgeTag } from './bridge/telemetry.mjs';
 import { readGuardrailSet } from './guardrail-store.mjs';
 import { unionGuardrails, guardrailsToPermissionRules, mergePermissionRules } from './guardrails.mjs';
 import { collectRequiredSkills, validateSkills, injectSkills, pluginSkillDirs } from './skills.mjs';
@@ -66,10 +66,16 @@ import {
   isValidSourceRef, snapshotWorktreePatch,
 } from './worktree.mjs';
 import { readPluginsLock, pluginCurrentDir } from './plugins-lock.mjs'; // §9.4 disabled-plugin hint
-import { classifyError } from './recoverable-error.mjs';
+import { classifyError, rateLimitHint, brokerHint, freeDailyHint } from './recoverable-error.mjs';
+import { cachedFreeDailyCounts } from './openrouter-free.mjs';
+import { withBillTo, currentBillTo } from './billing.mjs';
+import { brokerEnabled, brokerInfo, personSlots } from './broker-client.mjs';
+import { mockEnabled } from './claude-runner.mjs';
+import { modelSlot, manifestModels, missingCredentials, describeMissing } from './broker-routing.mjs';
+import { recoveryDelayMs, sleepAbortable } from './recovery-backoff.mjs';
 import {
   resolveFailure, isTerminal, markTerminal, answerFromDecision,
-  REASON, pauseConsequences, describePauseReason,
+  REASON, pauseConsequences, describePauseReason, RECOVERY_MAX_AUTO_ATTEMPTS,
 } from './failure-policy.mjs';
 import { recordRunMetrics } from './metrics/record.mjs';
 // Team policy (team-policy design §6–§7): the document a run's cost gates fold in, its
@@ -626,8 +632,27 @@ export class RunHarness extends EventEmitter {
       bin: this.opts.claude?.bin,
       permissionMode: this.opts.claude?.permissionMode || 'acceptEdits',
       model: this.opts.claude?.model,
+      effort: this.opts.claude?.effort,
       mock: !!this.opts.claude?.mock,
     };
+    // A resumed run keeps the model it was started with (`worca --model`, the UI's
+    // start pair): the resume sites pass none, so it rides the resume point — which
+    // _buildResumePoint rewrites at every pause from this.claude — like memoryScope
+    // below. A resume that names its own model wins. A saved model that left the
+    // catalog is dropped (the run falls back to the default, as before) and
+    // resume() says so once the run log is bound.
+    this._staleResumeModel = null;
+    {
+      const saved = this.opts.resume?.resumePoint?.claude;
+      if (saved && !this.claude.model && typeof saved.model === 'string' && saved.model) {
+        if (catalogHasModel(saved.model)) {
+          this.claude.model = saved.model;
+          if (!this.claude.effort && typeof saved.effort === 'string' && saved.effort) this.claude.effort = saved.effort;
+        } else {
+          this._staleResumeModel = saved.model;
+        }
+      }
+    }
     // The mock runner routes EVERY dontAsk spawn to the Ask Worca mock (claude-runner.mjs
     // runMock, rule R-F), so a mock pipeline role under dontAsk writes no artifact and
     // the run dies at its first artifact read with no hint why. Fail at construction
@@ -967,8 +992,16 @@ export class RunHarness extends EventEmitter {
     const where = label || nc?.key || ctx?.nodeId || 'orchestrator';
     const meta = ctx ? { nodeId: ctx.nodeId, executionId: ctx.executionId, cycle: ctx.ordinal } : {};
     const line = firstLine(err?.message || (err == null ? '' : String(err))) || 'unknown error';
+    // A shared-pool 429 (OpenRouter `:free`) names its real cause and fixes —
+    // otherwise "rate limited" reads as worca's own max-concurrent setting.
+    // A credential-broker refusal (a missing key, a spent cap) says where to fix it.
+    const hint = reason !== REASON.RECOVERABLE ? ''
+      : cls === 'rate_limit' ? rateLimitHint(err) : brokerHint(err, cls);
+    // OpenRouter's spent daily free requests: say what ran out and when it comes back,
+    // not the raw 429 line (freeDailyHint is '' for any other usage limit).
+    const freeDaily = reason === REASON.USAGE_LIMIT ? freeDailyHint(err, cachedFreeDailyCounts(currentBillTo())) : '';
     const text = detail ?? (reason === REASON.ERROR ? errorDetail(err)
-      : reason === REASON.RECOVERABLE ? `${cls || 'recoverable'}: ${line}` : line);
+      : reason === REASON.RECOVERABLE ? `${cls || 'recoverable'}: ${line}${hint ? ` — ${hint}` : ''}` : (freeDaily || line));
     if (reason === REASON.ERROR) {
       // The ONE error-level line, written BEFORE the pause sentinel the caller
       // throws next (a pause/abort is never logged as a failure).
@@ -986,9 +1019,9 @@ export class RunHarness extends EventEmitter {
       this._log(where, 'warn', `${describePauseReason(reason)} — pausing for manual resume: ${text}`, meta);
       audit = `Pipeline **paused**: session/usage limit on ${where} — ${text}. Resume after the reset.`;
     } else if (reason === REASON.RECOVERABLE) {
-      this._log(where, 'warn', `recoverable ${cls || 'error'} error — pausing for manual resume: ${line}`,
+      this._log(where, 'warn', `recoverable ${cls || 'error'} error — pausing for manual resume: ${line}${hint ? ` — ${hint}` : ''}`,
         { ...meta, ...(err?.stream ? { stream: err.stream } : {}) });
-      audit = `Pipeline **paused**: recoverable ${cls || 'error'} error on ${where} — ${line}. Resume to retry.`;
+      audit = `Pipeline **paused**: recoverable ${cls || 'error'} error on ${where} — ${line}.${hint ? ` ${hint[0].toUpperCase()}${hint.slice(1)}.` : ''} Resume to retry.`;
     } else {
       this._log(where, 'warn', `${text} — pausing for manual resume`, meta);
       audit = `Pipeline **paused**: ${text}.`;
@@ -1001,8 +1034,15 @@ export class RunHarness extends EventEmitter {
   /**
    * Execute the full pipeline. Resolves with { status, pipelineDir } on success
    * or stop; rejects only on unexpected internal errors (it emits 'error' too).
+   *
+   * Every spawn of the run is billed to the person who started it (billing.mjs,
+   * credential broker): the whole loop runs inside that async context.
    */
-  async run() {
+  run() {
+    return withBillTo(this.opts.startedBy || currentBillTo(), () => this._run());
+  }
+
+  async _run() {
     try {
       this.state.startedAt = new Date().toISOString();
       this._setStatus('running');
@@ -1041,6 +1081,9 @@ export class RunHarness extends EventEmitter {
       this.toolInstruction = tools.instruction || '';
       this.state.tools = tools;
       this.stepModels = stepModels;
+      // Credential broker: every model this run will spawn needs its person's key; refuse
+      // NOW, naming what's missing, instead of pausing mid-run at the first node that needs it.
+      await this._brokerPreflight(topology.manifest, stepModels);
       await this._resolveGuardrails();
       await this._resolvePolicy();
       this._log(
@@ -1373,8 +1416,18 @@ export class RunHarness extends EventEmitter {
    * artifacts exist from the original run, unless the point is stamped
    * `setupIncomplete` (D7 replay), which re-runs whatever setup never finished.
    * Resolves like run().
+   *
+   * Billed to whoever resumed it (the request's person, billing.mjs); a resume with
+   * no person behind it (a restart's auto-resume) stays with the run's starter.
    */
-  async resume() {
+  resume() {
+    const who = currentBillTo();
+    const starter = this.resumeOpts?.row?.started_by ?? this.opts.startedBy ?? null;
+    // Pays: whoever resumed. Runs as: the starter's agent user, whose HOME holds the sessions.
+    return withBillTo(who && who !== 'local' ? who : (starter || who), () => this._resume(), { owner: starter || who });
+  }
+
+  async _resume() {
     const saved = this.resumeOpts;
     if (!saved?.row || !saved?.resumePoint) throw new Error('resume(): no saved pipeline provided');
     const { row, resumePoint: rp, steps } = saved;
@@ -1428,6 +1481,9 @@ export class RunHarness extends EventEmitter {
       this.state.pipelineDir = rp.pipelineDir;
       this.logWriter.bind(rp.pipelineDir);
       recordArtifact(row.id, RUN_LOG_KIND, RUN_LOG_FILE);
+      if (this._staleResumeModel) {
+        this._log('orchestrator', 'warn', `model ${JSON.stringify(this._staleResumeModel)} the run was started with is no longer in the catalog — resuming on the default model`);
+      }
       this.stepModels = rp.stepModels || null;
       this.workflowId = rp.workflowId || this.workflowId;
       // Pauses are counted only in _completePaused, so a crash-resume of an `interrupted`
@@ -3023,6 +3079,33 @@ export class RunHarness extends EventEmitter {
    * recoverable-error gate surfaces it cleanly.
    * @param {Iterable<string>} agentKeys the run's distinct agent keys, in launch order
    */
+  /**
+   * Credential-broker preflight (docs/credential-broker.md): the models in the manifest
+   * (plus the step defaults and the run's own model, which an empty node model falls back
+   * to) mapped to broker slots, checked against the paying person's keys. Throws a
+   * Preflight error naming every missing key; a broker it can't ask never blocks here
+   * (the first spawn reports that instead).
+   */
+  async _brokerPreflight(manifest, stepModels) {
+    if (!brokerEnabled() || mockEnabled({ mock: this.claude.mock })) return;
+    let info;
+    try { info = await brokerInfo(); } catch { return; }
+    const person = info.mode === 'multi' ? currentBillTo() : 'local';
+    if (info.mode === 'multi' && (!person || person === 'local') && !process.env.WORCA_BROKER_SYSTEM_BILL_TO) {
+      throw Object.assign(new Error('Preflight failed: this run has no signed-in person to charge. Start it from the web UI, or set WORCA_BROKER_SYSTEM_BILL_TO.'), { errorClass: 'auth' });
+    }
+    const models = manifestModels(manifest);
+    for (const m of Object.values(stepModels || {})) if (typeof m === 'string' && m.trim()) models.add(m.trim());
+    if (this.claude?.model) models.add(this.claude.model);
+    if (!models.size) models.add('claude-sonnet-5');   // nothing named: the CLI's own default is a Claude model
+    let status;
+    try { status = (await personSlots(person === 'local' || !person ? (process.env.WORCA_BROKER_SYSTEM_BILL_TO || 'local') : person)).slots || []; } catch { return; }
+    const r = missingCredentials([...models], modelSlot, status);
+    if (r.missing.length || r.errors.length) {
+      throw Object.assign(new Error(`Preflight failed: ${describeMissing(r, info.publicUrl)}`), { errorClass: 'auth' });
+    }
+  }
+
   _preflightAgentKeys(agentKeys) {
     const reg = this.registry || {};
     const missing = [];
@@ -3154,7 +3237,9 @@ export class RunHarness extends EventEmitter {
     await appendAudit(this.pipeline.dir, `Recoverable **${cls}** error on ${node.key}: ${firstLine(err.message)}`).catch(() => {});
 
     if (verdict.outcome === 'retry') {
-      await this._backoff(attempt, this.pauseAbort.signal);
+      const delayMs = recoveryDelayMs({ cls, attempt, err });
+      this._log(node.key, 'warn', `${cls}: retrying in ${Math.round(delayMs / 100) / 10}s (retry ${attempt}/${RECOVERY_MAX_AUTO_ATTEMPTS})`);
+      await this._backoff(attempt, this.pauseAbort.signal, { cls, err, delayMs });
       return verdict;
     }
 
@@ -3193,23 +3278,11 @@ export class RunHarness extends EventEmitter {
     return next;
   }
 
-  /** Abort-aware backoff: base * 2^(attempt-1) ms, resolving early (and still
-   *  'retry') if the pause-only signal fires so a pause is not delayed. */
-  _backoff(attempt, signal) {
-    const base = (() => {
-      const n = Number(process.env.WORCA_RECOVERY_BACKOFF_MS);
-      return Number.isFinite(n) && n >= 0 ? n : 1000;
-    })();
-    const ms = base * Math.pow(2, Math.max(0, attempt - 1));
-    if (!ms) return Promise.resolve();
-    return new Promise((res) => {
-      const t = setTimeout(res, ms);
-      t.unref?.();
-      if (signal) {
-        if (signal.aborted) { clearTimeout(t); res(); }
-        else signal.addEventListener('abort', () => { clearTimeout(t); res(); }, { once: true });
-      }
-    });
+  /** Abort-aware backoff (recovery-backoff.mjs: base·2^(attempt-1), longer for a
+   *  rate limit, at least a retry-after hint, capped per wait), resolving early
+   *  (and still 'retry') if the pause-only signal fires so a pause is not delayed. */
+  _backoff(attempt, signal, { cls = null, err = null, delayMs } = {}) {
+    return sleepAbortable(delayMs ?? recoveryDelayMs({ cls, attempt, err }), signal);
   }
 
   /** Monotonic id source for recovery prompts (no Date.now/random — replay-safe). */
@@ -3977,9 +4050,16 @@ export class RunHarness extends EventEmitter {
     // instead of once per node. Looked up ONCE and shared with observeModelCost
     // below: modelCostConfig re-reads settings.json on every call.
     const costCfg = isResult && attr?.model ? modelCostConfig(attr.model) : null;
-    const cost = costCfg
-      ? resolveModelCost(attr.model, rawCost, e.raw.usage, costCfg)
-      : rawCost;
+    // A bridged node whose upstream reported what its calls cost (OpenRouter's
+    // usage.cost, booked per execution id) records that figure: the CLI prices an
+    // id it does not know at $0, and a pinned price is only an estimate of it.
+    // Read before _recordBridgeCalls forgets the tag.
+    const upstreamCost = isResult && attr?.executionId ? bridgeCostFor(attr.executionId) : null;
+    const cost = upstreamCost
+      ? upstreamCost.costUsd
+      : costCfg
+        ? resolveModelCost(attr.model, rawCost, e.raw.usage, costCfg)
+        : rawCost;
     if (isResult) this._recordBridgeCalls(attr?.stepKey, attr?.executionId);
     if (Number.isFinite(cost)) this._recordCost(cost, attr?.stepKey);
     else if (isResult && !this.claude.mock) {
@@ -4406,6 +4486,8 @@ export class RunHarness extends EventEmitter {
     if (!step) return;
     step.bridgeCalls = (step.bridgeCalls || 0) + calls.initiated;
     step.bridgeContinued = (step.bridgeContinued || 0) + calls.continued;
+    // OpenRouter `:free` calls (continuations too): what the step spent of the day's allowance.
+    if (calls.free) step.bridgeFreeCalls = (step.bridgeFreeCalls || 0) + calls.free;
     this.state.updatedAt = new Date().toISOString();
     this._emit('state', this.getState());
     this._persist().catch(() => {});