atris 3.61.0 → 3.63.0

package/lib/engine-registry.js

@@ -14,7 +14,9 @@ const {
   engineTakesModel,
   engineEffortLevels,
 } = require('./runner-command');
-const { rankEnginesDetailed, routerPickExplanation } = require('./router-brain');
+// Through the module object so tests can see when ranking runs.
+const routerBrain = require('./router-brain');
+const { routerPickExplanation } = routerBrain;
 // Friendly name for a saved model: claude-opus-5-5 reads as "opus 5.5".
 const { modelLabel: rosterModelLabel } = require('./roster-models');
 
@@ -22,29 +24,116 @@ const ENGINE_REGISTRY_SCHEMA = 'atris.engine_registry.v2';
 const ENGINE_TIERS = Object.freeze(['fast', 'pro', 'max']);
 const ENGINE_ROLES = Object.freeze(['navigator', 'executor', 'validator']);
 const ENGINE_DUTIES = Object.freeze(['leader', 'errands', 'learning']);
-const ENGINE_HEALTH_STATUSES = Object.freeze(['ready', 'not_installed', 'credit_out', 'error']);
+const ENGINE_HEALTH_STATUSES = Object.freeze(['ready', 'not_installed', 'credit_out', 'error', 'cooling']);
+const DEFAULT_ENGINE_COOLDOWN_MINUTES = 30;
+
+// How long a stalled engine sits out: ATRIS_ENGINE_COOLDOWN_MINUTES, else 30.
+function engineCooldownMs() {
+  const minutes = Number(process.env.ATRIS_ENGINE_COOLDOWN_MINUTES);
+  return (Number.isFinite(minutes) && minutes > 0 ? minutes : DEFAULT_ENGINE_COOLDOWN_MINUTES) * 60000;
+}
+
+function nowMs(now) {
+  if (now === undefined || now === null) return Date.now();
+  const ms = now instanceof Date ? now.getTime() : Date.parse(now);
+  return Number.isFinite(ms) ? ms : Date.now();
+}
+
+// True while an engine sits out after a stall. Once the cooldown passes the
+// engine is ready again with no human step.
+function engineCooling(engine, now) {
+  const health = engine && engine.health;
+  if (!health || health.status !== 'cooling') return false;
+  const until = Date.parse(health.cooling_until || '');
+  return Number.isFinite(until) && until > nowMs(now);
+}
+
+// Every resolver asks this one question: can this engine take work now?
+function engineReadyAt(engine, now) {
+  const health = engine && engine.health;
+  const status = health && health.status;
+  if (status === 'ready') return true;
+  if (status === 'cooling') return !engineCooling(engine, now);
+  // 'error' survives from before failed runs stopped benching their engine:
+  // it came from any errored run, real task failures included. It sits out
+  // the same window as a stall; a missing stamp (older saves) routes at once.
+  if (status === 'error') {
+    const failedAt = Date.parse(health.last_failure_ts || '');
+    return !Number.isFinite(failedAt) || failedAt + engineCooldownMs() <= nowMs(now);
+  }
+  return false;
+}
+
+const TRANSIENT_FAILURE_PATTERN = /\b(?:econnreset|econnrefused|econnaborted|etimedout|enotfound|eai_again|epipe|enetunreach|ehostunreach)\b|socket hang up|connection (?:reset|refused|closed|dropped|lost|error|timed out|interrupted)|lost (?:the )?connection|network (?:error|failure|is unreachable)|stream (?:disconnected|error|closed)|\bdisconnected\b|(?:service|server|model|temporarily|currently)[ _-]unavailable|overloaded|bad gateway|gateway time-?out/;
+
+function tailText(value, size = 600) {
+  const text = String(value || '');
+  return text.length > size ? text.slice(-size) : text;
+}
+
+// Why a run stalled, in plain words, or null when it failed for a real task
+// reason. A stall is a time cap (the run hit its max, a spawn timeout, or the
+// codex watchdog's 124/125) or a transient error (a dropped connection, a
+// network error, an unavailable service). Only engine-level signals count:
+// the task's own output (report, stdout, the claude summary and receipt) is
+// the work it produced, and its words must not decide the engine's health.
+function engineStallReason(result) {
+  if (!result || typeof result !== 'object') return null;
+  const claude = result.claude || {};
+  const reason = String(result.reason || '');
+  if (/wall-exceeded/.test(reason)) return null;
+  const exitCode = Number.isInteger(result.exitCode) ? result.exitCode
+    : Number.isInteger(result.exit_code) ? result.exit_code : null;
+  const capSecondsValue = Math.floor(Number(result.max_seconds || result.maxSeconds)) || 0;
+  const capText = capSecondsValue >= 60 ? `stalled at ${Math.round(capSecondsValue / 60)} min`
+    : capSecondsValue > 0 ? `stalled at ${capSecondsValue}s`
+      : 'hit its time limit';
+  if (exitCode === 124) return { kind: 'time_cap', text: 'stalled at startup' };
+  if (result.timed_out === true || claude.timed_out === true || exitCode === 125
+    || /\bclaude-timeout\b|(?:^|\n)timeout(?:\n|$)/.test(reason)) {
+    return { kind: 'time_cap', text: capText };
+  }
+  const text = [
+    reason,
+    result.error && (result.error.message || result.error.code || result.error),
+    result.model_unavailable,
+    tailText(result.stderr),
+    tailText(claude.stderr),
+  ].filter(Boolean).map(String).join('\n').toLowerCase();
+  if (/spawn[^\n]*etimedout/.test(text)) return { kind: 'time_cap', text: 'timed out starting up' };
+  if (TRANSIENT_FAILURE_PATTERN.test(text)) return { kind: 'transient', text: 'lost its connection' };
+  return null;
+}
 
 function engineFailureHealthStatus(result) {
   if (!result || result.status !== 'errored') return null;
+  // Same rule as engineStallReason: only engine-level signals decide engine
+  // health. The task's own output (report, stdout, the claude summary and
+  // receipt) is the work product, never the engine's vital signs.
+  const rateLimitInfo = result.rate_limit_info;
+  const rateLimitStatus = String(
+    rateLimitInfo && typeof rateLimitInfo === 'object' ? rateLimitInfo.status || '' : rateLimitInfo || '',
+  ).trim().toLowerCase();
+  // The engine's own rate-limit event is a credit wall only when the window
+  // is actually closed: claude reports resetsAt with status 'allowed' on
+  // healthy turns too.
+  if (rateLimitStatus && rateLimitStatus !== 'allowed') return 'credit_out';
   const signalText = [
     result.reason,
     result.model_unavailable,
-    result.report,
-    result.stdout,
     result.stderr,
-    result.error,
-    result.claude && result.claude.summary,
-    result.claude && result.claude.receipt_text,
+    result.error && (result.error.message || result.error.code || result.error),
     result.claude && result.claude.stderr,
-    result.rate_limit_info && JSON.stringify(result.rate_limit_info),
+    rateLimitStatus,
   ].filter(Boolean).join('\n').toLowerCase();
   if (/usage[ _-]?limit|purchase more credits|insufficient credits|credit(?:s)?[ _-]?(?:out|limit)|rate[ _-]?limit|not authenticated|please log in|login required|auth(?:entication)?[ _-]?expired|payment required|subscription/.test(signalText)) {
     return 'credit_out';
   }
   if (/not installed|command not found|\benoent\b/.test(signalText)) return 'not_installed';
-  // Timeouts and unavailable models are transient: 'error' keeps the engine
-  // routable, while 'not_installed' would drop it from routing until a doctor run.
-  return 'error';
+  // A real task failure (its tests failed, its report says why) says nothing
+  // about the engine, so health stays. 'error' survives only as the stall
+  // marker: the caller walks it through the cooling path.
+  return engineStallReason(result) ? 'error' : null;
 }
 
 const ENGINE_SEED_META = Object.freeze({
@@ -55,12 +144,12 @@ const ENGINE_SEED_META = Object.freeze({
   // review when picked; it stays out of roles, so every review list built
   // from roles (the router, one lap, wish audit, the chart) is unchanged.
   codex: Object.freeze({ tier: 'pro', roles: Object.freeze(['executor']), roster_only_roles: Object.freeze(['validator']), models: Object.freeze(['codex']), fallback_order: 10 }),
-  claude: Object.freeze({ tier: 'max', roles: Object.freeze(['validator', 'executor', 'navigator']), roster_only_roles: Object.freeze(['navigator']), models: Object.freeze(['opus 5.5', 'opus 5', 'opus 4.8', 'fable', 'haiku']), fallback_order: 20 }),
+  claude: Object.freeze({ tier: 'max', roles: Object.freeze(['validator', 'executor', 'navigator']), roster_only_roles: Object.freeze(['navigator']), models: Object.freeze(['opus 5.5', 'opus 5', 'fable', 'haiku']), fallback_order: 20 }),
   cursor: Object.freeze({ tier: 'pro', roles: Object.freeze(['executor']), models: Object.freeze(['composer 2.5', 'grok 4.6', 'kimi 3']), fallback_order: 30 }),
   // Devin gathers context for search only when a roster picks it.
   devin: Object.freeze({ tier: 'max', roles: Object.freeze(['executor']), roster_only_roles: Object.freeze(['navigator']), models: Object.freeze(['built-in router']), duty: 'errands', fallback_order: 40 }),
   grok: Object.freeze({ tier: 'pro', roles: Object.freeze(['executor']), models: Object.freeze(['grok 4.7 fast', 'grok 4.7']), fallback_order: 45 }),
-  fable: Object.freeze({ tier: 'max', roles: Object.freeze(['validator', 'executor']), models: Object.freeze(['opus 5.5', 'opus 5', 'opus 4.8', 'fable', 'haiku']), duty: 'leader', fallback_order: 50 }),
+  fable: Object.freeze({ tier: 'max', roles: Object.freeze(['validator', 'executor']), models: Object.freeze(['opus 5.5', 'opus 5', 'fable', 'haiku']), duty: 'leader', fallback_order: 50 }),
   composer: Object.freeze({ tier: 'fast', roles: Object.freeze(['navigator', 'executor']), models: Object.freeze(['composer 2.5']), fallback_order: 60 }),
   haiku: Object.freeze({ tier: 'fast', roles: Object.freeze(['validator', 'navigator']), roster_only_roles: Object.freeze(['navigator']), models: Object.freeze(['haiku']), fallback_order: 70 }),
   agy: Object.freeze({
@@ -77,7 +166,7 @@ const ENGINE_SEED_META = Object.freeze({
     duty: 'errands',
     fallback_order: 90,
   }),
-  opencode: Object.freeze({ tier: 'pro', roles: Object.freeze(['executor']), models: Object.freeze(['opencode/big-pickle', 'opencode/claude-opus-4-8', 'opencode/gpt-5.2']), fallback_order: 95 }),
+  opencode: Object.freeze({ tier: 'pro', roles: Object.freeze(['executor']), models: Object.freeze(['opencode/big-pickle', 'opencode/claude-opus-5-5', 'opencode/gpt-5.2']), fallback_order: 95 }),
   commandcode: Object.freeze({
     tier: 'max',
     roles: Object.freeze(['validator', 'executor']),
@@ -155,7 +244,7 @@ function normalizeFallbackOrder(value, fallback) {
   return Number.isInteger(order) ? order : fallback;
 }
 
-function normalizeEngineEntry(id, saved = {}) {
+function normalizeEngineEntry(id, saved = {}, now) {
   const def = RUNNER_PROFILE_DEFS[id];
   const seed = ENGINE_SEED_META[id] || { tier: 'pro', roles: ['executor'], models: [id], fallback_order: 100 };
   const savedHealth = saved && saved.health && typeof saved.health === 'object' ? saved.health : {};
@@ -173,8 +262,18 @@ function normalizeEngineEntry(id, saved = {}) {
     installed = binInstalled(def.bin);
     status = installed ? 'ready' : 'not_installed';
   }
-  const health = { status };
+  let health = { status };
   if (status !== 'ready' && savedHealth.last_failure_ts) health.last_failure_ts = String(savedHealth.last_failure_ts);
+  if (status === 'cooling') {
+    // A cooldown that has passed reads as ready, so the engine comes back
+    // with no human step.
+    if (engineCooling({ health: savedHealth }, now)) {
+      health.cooling_until = String(savedHealth.cooling_until);
+      if (savedHealth.cooling_reason) health.cooling_reason = String(savedHealth.cooling_reason);
+    } else {
+      health = { status: 'ready' };
+    }
+  }
   return {
     ...saved,
     id,
@@ -182,7 +281,13 @@ function normalizeEngineEntry(id, saved = {}) {
     bin: def.bin,
     tier: normalizeTier(saved.tier, seed.tier),
     roles: normalizeRoles(saved.roles, Array.from(seed.roles)),
-    models: normalizeModels(saved.models, Array.from(seed.models)),
+    // The seed model list is the live catalog and always wins on read, unless
+    // the owner set models on purpose: `atris engine set --models` saves
+    // models_set_by_owner next to the list. A list copied in at seed time has
+    // no mark, so it thaws to the current seed instead of pinning stale names.
+    models: saved.models_set_by_owner === true
+      ? normalizeModels(saved.models, Array.from(seed.models))
+      : Array.from(seed.models),
     duty: normalizeDuty(saved.duty, seed.duty),
     fallback_order: normalizeFallbackOrder(saved.fallback_order, seed.fallback_order),
     installed,
@@ -190,7 +295,7 @@ function normalizeEngineEntry(id, saved = {}) {
   };
 }
 
-function seededRegistry(root = process.cwd(), preloadedRaw = null) {
+function seededRegistry(root = process.cwd(), preloadedRaw = null, now) {
   const file = engineRegistryFile(root);
   const raw = preloadedRaw || readRawRegistry(file);
   const savedById = new Map();
@@ -204,7 +309,7 @@ function seededRegistry(root = process.cwd(), preloadedRaw = null) {
     updated_at: new Date().toISOString(),
     // Hidden profiles are registered engines too: they seed, route, and take
     // health policy exactly like visible ones.
-    engines: Object.keys(RUNNER_PROFILE_DEFS).map((id) => normalizeEngineEntry(id, savedById.get(id) || {})),
+    engines: Object.keys(RUNNER_PROFILE_DEFS).map((id) => normalizeEngineEntry(id, savedById.get(id) || {}, now)),
   };
 }
 
@@ -237,6 +342,7 @@ function setEngineOverrides(name, overrides = {}, root = process.cwd()) {
     const models = normalizeModels(overrides.models, []);
     if (!models.length) throw new Error('models must include at least one name');
     nextOverrides.models = models;
+    nextOverrides.models_set_by_owner = true;
   }
   if (!Object.keys(nextOverrides).length) throw new Error('set requires --duty or --models');
 
@@ -282,7 +388,7 @@ function setEngineOverrides(name, overrides = {}, root = process.cwd()) {
 // one read, one decision.
 function readEngineRegistry(root = process.cwd(), options = {}) {
   const raw = readRawRegistry(engineRegistryFile(root));
-  const registry = seededRegistry(root, raw);
+  const registry = seededRegistry(root, raw, options.now);
   const needsPersist = JSON.stringify(raw.engines || []) !== JSON.stringify(registry.engines);
   if (options.persist !== false && needsPersist && canPersistEngineRegistry(root)) {
     writeEngineRegistry(root, registry);
@@ -754,6 +860,22 @@ function resolveEngineModelWords(text) {
   throw new Error(`"${clean}" is not an engine or a model atris knows`);
 }
 
+// The engine a model name belongs to, read the same way a roster line is,
+// or '' when the name is not one atris can place. The claude cli's
+// own aliases ("default", "opusplan", with or without [1m]) count as claude.
+function modelEngineName(model) {
+  const base = String(model || '').trim().replace(CLAUDE_LONG_CONTEXT, '').trim();
+  try {
+    return resolveEngineModelWords(base).engine || '';
+  } catch {
+    return CLAUDE_MODEL_ALIASES.includes(base.toLowerCase()) ? 'claude' : '';
+  }
+}
+
+function isClaudeFamilyModel(model) {
+  return CLAUDE_FAMILY_ENGINES.includes(modelEngineName(model));
+}
+
 // What an engine can do by its seed, used to check hand-written lines before
 // any registry is read.
 function engineCanTake(engineId, role) {
@@ -787,6 +909,7 @@ function rosterPickFromValue(value, role, options = {}) {
   let maxSeconds = null;
   let namedModel = false;
   let namedEffort = false;
+  let prep = '';
   for (const raw of extras) {
     // "max: 20 min" and "until: 2026-10-24" read like "max 20 min".
     const part = raw.replace(/^(max|until)\s*:\s*/i, '$1 ');
@@ -795,7 +918,15 @@ function rosterPickFromValue(value, role, options = {}) {
     const maxMatch = /^max\b/i.test(part) && !/^max$/i.test(part);
     const modelMatch = /^model\s*(?::\s*|\s+)(.+)$/i.exec(part);
     const effortMatch = /^effort\s*(?::\s*|\s+)(.+)$/i.exec(part);
-    if (modelMatch && !namedModel) {
+    const prepMatch = /^prep\s*(?::\s*|\s+)(.+)$/i.exec(part);
+    if (prepMatch && !prep) {
+      // "prep: search": that job's lead reads the task first and hands this
+      // worker a trimmed brief. Whether it names this same job is checked
+      // where the job is known.
+      const words = prepMatch[1].trim();
+      prep = rosterJobKey(splitJobName(words).name);
+      if (!prep) throw new Error(`"prep: ${words}" does not name a job; use prep: search or another job name`);
+    } else if (modelMatch && !namedModel) {
       if (primary.model) throw new Error(`names two models for ${primary.engine}`);
       const words = modelMatch[1].trim();
       if (!engineTakesModel(primary.engine)) throw new Error(`${primary.engine} runs one fixed model and cannot take "${words}"`);
@@ -840,12 +971,21 @@ function rosterPickFromValue(value, role, options = {}) {
     ...(backup && backup.model ? { backup_model: backup.model } : {}),
     ...(backup && backup.effort ? { backup_effort: backup.effort } : {}),
     ...(maxSeconds ? { max_seconds: maxSeconds } : {}),
+    ...(prep ? { prep } : {}),
     until,
     ...(until ? {} : { never_expires: true }),
     ...(untilYearless ? { until_needs_year: untilYearless } : {}),
   };
 }
 
+// A worker that names its own job as prep would wait on itself. The line
+// still counts; only the prep is dropped, with a plain warning.
+function selfPrepWarning(worker, key, label) {
+  if (!worker || !worker.prep || worker.prep !== key) return '';
+  delete worker.prep;
+  return `asks ${label} to prep for itself, so this worker runs without prep`;
+}
+
 // A job line's name part, "small build (like build)", split into the name
 // and the kind it says it is like.
 function splitJobName(text) {
@@ -873,6 +1013,7 @@ function rosterWorkerFromValue(value, role, options = {}) {
     model: pick.model,
     ...(pick.effort ? { effort: pick.effort } : {}),
     ...(pick.max_seconds ? { max_seconds: pick.max_seconds } : {}),
+    ...(pick.prep ? { prep: pick.prep } : {}),
     until: pick.until,
     ...(pick.never_expires ? { never_expires: true } : {}),
     ...(pick.until_needs_year ? { until_needs_year: pick.until_needs_year } : {}),
@@ -921,6 +1062,7 @@ function pickWorkers(pick) {
     model: pick.model || '',
     ...(pick.effort ? { effort: pick.effort } : {}),
     ...cap,
+    ...(pick.prep ? { prep: pick.prep } : {}),
     until: pick.until,
     ...(pick.never_expires ? { never_expires: true } : {}),
     ...(pick.line ? { line: pick.line } : {}),
@@ -971,6 +1113,8 @@ function parseRosterMarkdown(text, file, options = {}) {
     for (const entry of lines) {
       try {
         const worker = rosterWorkerFromValue(entry.value, ENGINE_JOBS[kind], options);
+        const selfPrep = selfPrepWarning(worker, key, label);
+        if (selfPrep) warn(entry, selfPrep);
         workers.push({ ...worker, line: entry.lineNumber, text: entry.raw });
         if (worker.until_needs_year) warn(entry, `has no year in its until date, so this ${label} worker counts as expired; write until ${worker.until_needs_year}`);
       } catch (error) {
@@ -988,6 +1132,7 @@ function parseRosterMarkdown(text, file, options = {}) {
       backup: second ? second.engine : '',
       ...(second && second.model ? { backup_model: second.model } : {}),
       ...(first.max_seconds ? { max_seconds: first.max_seconds } : {}),
+      ...(first.prep ? { prep: first.prep } : {}),
       until: first.until,
       ...(first.never_expires ? { never_expires: true } : {}),
       ...(builtIn ? {} : { like: kind }),
@@ -1040,6 +1185,8 @@ function parseRosterMarkdown(text, file, options = {}) {
     }
     try {
       const pick = rosterPickFromValue(entry.value, ENGINE_JOBS[kind], options);
+      const selfPrep = selfPrepWarning(pick, key, label);
+      if (selfPrep) warn(entry, selfPrep);
       picks[key] = { ...pick, ...(builtIn ? {} : { like: kind }), file: display, line: entry.lineNumber };
       if (pick.until_needs_year) {
         warn(entry, `has no year in its until date, so ${label} counts as expired; write until ${pick.until_needs_year}`);
@@ -1215,12 +1362,13 @@ function workerModelText(engine, model) {
   return model;
 }
 
-// One worker line: "- claude code, model: opus 5.5, effort: high, max: 20 min, until 2026-10-24".
+// One worker line: "- claude code, model: opus 5.5, effort: high, max: 20 min, prep: search, until 2026-10-24".
 function workerLineText(worker) {
   const parts = [rosterToolLabel(worker.engine)];
   if (worker.model) parts.push(`model: ${workerModelText(worker.engine, worker.model)}`);
   if (worker.effort) parts.push(`effort: ${worker.effort}`);
   if (Number(worker.max_seconds) > 0) parts.push(`max: ${rosterMaxText(worker.max_seconds).replace(/^max /, '')}`);
+  if (worker.prep) parts.push(`prep: ${rosterJobLabel(worker.prep)}`);
   if (worker.until) parts.push(`until ${worker.until}`);
   return `- ${parts.join(', ')}`;
 }
@@ -1360,6 +1508,24 @@ function assignedWorkerLines(key, engineName, options, context) {
     if (keep.length === currentLines.length) throw new Error(`${label} has no ${tool} worker to remove`);
     return { lines: keep.length ? keep : null };
   }
+  // --promote moves the first line naming exactly the tool and model (and
+  // effort, if given) to the top, every line exactly as written. Unlike an
+  // assign, it rewrites nothing: the demoted lead keeps its own cap, prep,
+  // and notes. With no model the words match only a line with no model, so
+  // promoting "claude" can never move "claude, model: ..." by accident.
+  if (options.promote !== undefined) {
+    const words = String(options.promote).trim();
+    const want = resolveRosterWords(words);
+    const matches = currentWorkers
+      .map((worker, index) => index)
+      .filter((index) => currentWorkers[index].engine === want.engine
+        && (currentWorkers[index].model || '') === (want.model || '')
+        && (currentWorkers[index].effort || '') === (want.effort || ''));
+    if (!matches.length) throw new Error(`${label} has no ${words} worker to move up`);
+    const index = matches[0];
+    const note = matches.length > 1 ? `${label} has ${matches.length} workers named ${words}; the first moved up` : '';
+    return { lines: [currentLines[index], ...currentLines.filter((line, i) => i !== index)], ...(note ? { note } : {}) };
+  }
   const likeName = String(options.like || '').trim();
   const likeKind = likeName ? rosterJob(likeName) : '';
   if (likeName && !likeKind) throw new Error(`unknown kind "${likeName}". use --like search, build, or review`);
@@ -1397,12 +1563,17 @@ function assignedWorkerLines(key, engineName, options, context) {
   if (effort && !engineEffortLevels(engine.id).includes(effort)) throw new Error(effortRefusal(engine.id, effort));
   const maxSeconds = options.max === undefined ? null : parseRosterMax(`max ${String(options.max).replace(/^max\s*:?\s*/i, '')}`);
   if (options.max !== undefined && !maxSeconds) throw new Error(`"${options.max}" is not a time cap; use --max "20 min", --max 90s, or --max 2h`);
+  const prepWords = options.prep === undefined ? '' : String(options.prep).trim();
+  const prep = prepWords ? rosterJobKey(splitJobName(prepWords).name) : '';
+  if (options.prep !== undefined && !prep) throw new Error(`"${options.prep}" is not a job name; use --prep search or another job`);
+  if (prep && prep === key) throw new Error(`${label} cannot prep for itself; pick another job, like --prep search`);
   const now = rosterDate(options.now);
   const line = workerLineText({
     engine: engine.id,
     model,
     ...(effort ? { effort } : {}),
     ...(maxSeconds ? { max_seconds: maxSeconds } : {}),
+    ...(prep ? { prep } : {}),
     until: days ? rosterUntil(now, days) : '',
   });
   const heading = jobHeadingText(key, builtIn ? '' : kind);
@@ -1470,13 +1641,14 @@ function setRosterPick(jobName, engineName, options = {}, root = process.cwd())
     const worker = savedPick && savedPick.workers ? savedPick.workers.find((item) => item.line === entry.lineNumber) : null;
     return worker || { engine: rosterToolName(String(entry.value).split(',')[0]), model: '' };
   });
-  const { lines, heading } = assignedWorkerLines(key, engineName, options, {
+  const { lines, heading, note } = assignedWorkerLines(key, engineName, options, {
     registry,
     savedPick,
     currentLines: workerEntries.map((entry) => entry.raw),
     currentWorkers,
     jobName,
   });
+  if (note && typeof options.note === 'function') options.note(note);
   const next = replaceJobSection(base, {
     matches: (title) => rosterJobHeading(title).key === key,
     // Only an assign names a heading, and only when the job's kind changes;
@@ -1576,7 +1748,7 @@ const ROSTER_LAYERS = Object.freeze(['session', 'project', 'machine']);
 // or not ready (down, or it cannot do this kind of work).
 function rosterWorkerWalk(pick, role, registry, now) {
   const ready = registry.engines
-    .filter((engine) => engine.health && engine.health.status === 'ready')
+    .filter((engine) => engineReadyAt(engine, now))
     .filter((engine) => engineHasRole(engine, role));
   return pickWorkers(pick).map((worker) => {
     if (worker.error) return { worker, skip: 'bad line', engine: null, raw: null };
@@ -1584,17 +1756,24 @@ function rosterWorkerWalk(pick, role, registry, now) {
     const saved = savedRosterModel(worker.engine, worker.model);
     if (saved === null && !worker.lenient_model) return { worker, skip: 'bad model', engine: null, raw: null };
     const raw = ready.find((engine) => engine.id === worker.engine) || null;
-    if (!raw) return { worker, skip: 'not ready', engine: null, raw: null };
+    if (!raw) {
+      // A worker benched after a stall says so and when it comes back.
+      const benched = registry.engines.find((engine) => engine.id === worker.engine && engineCooling(engine, now));
+      if (benched) return { worker, skip: 'cooling', cooling: coolingView(benched), engine: null, raw: null };
+      return { worker, skip: 'not ready', engine: null, raw: null };
+    }
     // A backup runs its own model and effort, never the lead's.
     const model = saved || '';
     const effort = savedRosterEffort(raw.id, worker.effort);
     const maxSeconds = Number(worker.max_seconds) > 0 ? Number(worker.max_seconds) : 0;
-    const engine = model || effort || maxSeconds
+    const prep = worker.prep || '';
+    const engine = model || effort || maxSeconds || prep
       ? {
         ...raw,
         ...(model ? { roster_model: model } : {}),
         ...(effort ? { roster_effort: effort } : {}),
         ...(maxSeconds ? { roster_max_seconds: maxSeconds } : {}),
+        ...(prep ? { roster_prep: prep } : {}),
       }
       : raw;
     return { worker, skip: '', engine, raw };
@@ -1615,6 +1794,7 @@ function rosterChoiceForPick(pick, role, registry, { key, label, source, scopeTe
   const after = walk.slice(leadIndex + 1).filter((step) => !step.skip);
   const first = walk[0];
   const why = first.skip === 'expired' ? 'expired'
+    : first.skip === 'cooling' ? `is ${first.cooling.text}`
     : first.skip === 'bad model' ? `names a model ${first.worker.engine} cannot run`
       : first.skip === 'bad line' ? 'has a bad first line'
         : 'is not ready';
@@ -1633,6 +1813,8 @@ function rosterChoiceForPick(pick, role, registry, { key, label, source, scopeTe
   };
 }
 
+const ROSTER_PIN_FIELDS = Object.freeze(['roster_model', 'roster_effort', 'roster_max_seconds', 'roster_prep']);
+
 const ROSTER_SCOPE_TEXT = Object.freeze({ session: ' (this session)', project: '', machine: ' (all projects)' });
 
 // Walk one job's roster layers in order: this session, this project, all
@@ -1689,36 +1871,58 @@ function resolveEngineForRoleRanked(role, root = process.cwd(), options = {}) {
   if (!ENGINE_ROLES.includes(normalizedRole)) {
     throw new Error(`Unknown role "${role}". Known roles: ${ENGINE_ROLES.join(', ')}`);
   }
-  const registry = readEngineRegistry(root);
+  const registry = readEngineRegistry(root, { now: options.now });
   const engines = registry.engines
     .filter((engine) => engine.roles.includes(normalizedRole))
     .filter((engine) => !routerSkipsRole(engine, normalizedRole))
-    .filter((engine) => engine.health && engine.health.status === 'ready')
+    .filter((engine) => engineReadyAt(engine, options.now))
     .sort((a, b) => {
       const byOrder = Number(a.fallback_order) - Number(b.fallback_order);
       return byOrder || String(a.id).localeCompare(String(b.id));
     });
-  const ranked = rankEnginesDetailed(engines, {
-    root,
-    taskType: options.taskType || options.task_type || normalizedRole,
-    lowStakes: options.lowStakes,
-    stakes: options.stakes,
-  });
+  // Ranking reads the router's history off disk (task receipts, mission
+  // events, dispatch receipts). A valid roster pick decides without it, so
+  // rank only when something asks for the full ranked list.
+  let rankedCache = null;
+  const rank = () => {
+    if (!rankedCache) {
+      rankedCache = routerBrain.rankEnginesDetailed(engines, {
+        root,
+        taskType: options.taskType || options.task_type || normalizedRole,
+        lowStakes: options.lowStakes,
+        stakes: options.stakes,
+      });
+    }
+    return rankedCache;
+  };
   const choice = rosterChoice(normalizedRole, withProjectRoster(registry, root, options), options);
   if (choice) {
     // The job's own workers go first, in order, then the router's list.
     const after = choice.walk.slice(choice.lead_index + 1).filter((step) => !step.skip).map((step) => step.raw);
     const lead = [choice.engine, ...after].filter((engine, index, list) => list.findIndex((other) => other.id === engine.id) === index);
     const leadIds = new Set(lead.map((engine) => engine.id));
-    return {
+    const result = {
       engine: choice.engine,
       reason: choice.reason,
       source: choice.source,
       job: choice.job,
       team: choice.team,
-      ranked: [...lead, ...ranked.candidates.filter((candidate) => !leadIds.has(candidate.id))],
     };
+    let rankedList = null;
+    Object.defineProperty(result, 'ranked', {
+      enumerable: true,
+      configurable: true,
+      get() {
+        if (!rankedList) rankedList = [...lead, ...rank().candidates.filter((candidate) => !leadIds.has(candidate.id))];
+        return rankedList;
+      },
+      set(value) {
+        rankedList = value;
+      },
+    });
+    return result;
   }
+  const ranked = rank();
   return { engine: ranked.candidates[0] || null, reason: routerPickExplanation(ranked), source: 'router', team: [], ranked: ranked.candidates };
 }
 
@@ -1754,7 +1958,8 @@ function resolveEngineForRole(role, root = process.cwd(), options = {}) {
 }
 
 // Everything the roster pins on this job's live pick when that pick is this
-// exact engine: roster_model, roster_effort, roster_max_seconds. {} otherwise.
+// exact engine: roster_model, roster_effort, roster_max_seconds, roster_prep.
+// {} otherwise.
 // A caller that already chose an engine (a mission's preferred engine,
 // --engine) still gets the pins.
 function rosterPinFor(role, engineId, root = process.cwd(), options = {}) {
@@ -1763,7 +1968,7 @@ function rosterPinFor(role, engineId, root = process.cwd(), options = {}) {
   const choice = rosterChoice(normalizedRole, withProjectRoster(readEngineRegistry(root, { persist: false }), root, options), options);
   if (!choice || choice.engine.id !== engineId) return {};
   const pin = {};
-  for (const field of ['roster_model', 'roster_effort', 'roster_max_seconds']) {
+  for (const field of ROSTER_PIN_FIELDS) {
     if (choice.engine[field]) pin[field] = choice.engine[field];
   }
   return pin;
@@ -1779,7 +1984,7 @@ function resolveEngineForRoleWithPreference(role, root = process.cwd(), preferre
     };
   }
   const preferred = resolveRegisteredEngine(requested, root);
-  if (preferred.health && preferred.health.status === 'ready') {
+  if (engineReadyAt(preferred, options.now)) {
     const pin = rosterPinFor(role, preferred.id, root, options);
     return {
       engine: Object.keys(pin).length ? { ...preferred, ...pin } : preferred,
@@ -1805,6 +2010,7 @@ function setEngineHealth(name, status, root = process.cwd()) {
   if (!ENGINE_HEALTH_STATUSES.includes(normalizedStatus)) {
     throw new Error(`Unknown health "${status}". Known health statuses: ${ENGINE_HEALTH_STATUSES.join(', ')}`);
   }
+  if (normalizedStatus === 'cooling') return setEngineCooling(id, { root });
   const registry = readEngineRegistry(root, { persist: false });
   const engines = registry.engines.map((engine) => {
     if (engine.id !== id) return engine;
@@ -1817,6 +2023,55 @@ function setEngineHealth(name, status, root = process.cwd()) {
   return engines.find((engine) => engine.id === id);
 }
 
+// Bench an engine after a stall: it is not ready until the cooldown passes,
+// so every resolver hands its jobs to the roster's next worker meanwhile.
+function setEngineCooling(name, { root = process.cwd(), now, reason = 'stalled', minutes } = {}) {
+  const id = canonicalEngineName(name);
+  if (!id) throw new Error(`Unknown engine "${name}". Known engines: ${RUNNER_PROFILE_NAMES.join(', ')}`);
+  const at = nowMs(now);
+  const ms = Number(minutes) > 0 ? Number(minutes) * 60000 : engineCooldownMs();
+  const registry = readEngineRegistry(root, { persist: false, now });
+  const engines = registry.engines.map((engine) => {
+    if (engine.id !== id) return engine;
+    return {
+      ...engine,
+      health: {
+        status: 'cooling',
+        last_failure_ts: new Date(at).toISOString(),
+        cooling_until: new Date(at + ms).toISOString(),
+        cooling_reason: String(reason || 'stalled'),
+      },
+    };
+  });
+  writeEngineRegistry(root, { ...registry, updated_at: new Date(at).toISOString(), engines });
+  return engines.find((engine) => engine.id === id);
+}
+
+// "cooling until 14:32 (stalled)" for the roster and engine views.
+function coolingView(engine) {
+  const health = (engine && engine.health) || {};
+  const until = new Date(health.cooling_until);
+  const clock = Number.isFinite(until.getTime())
+    ? `${String(until.getHours()).padStart(2, '0')}:${String(until.getMinutes()).padStart(2, '0')}`
+    : 'later';
+  const reason = String(health.cooling_reason || 'stalled');
+  return { until: health.cooling_until || null, reason, text: `cooling until ${clock} (${reason})` };
+}
+
+// The one health write for a finished run: a stall benches the engine for
+// the cooldown, a credit wall or a missing binary writes its own status, and
+// a real task failure changes nothing. Returns the updated engine, or null.
+function recordEngineRunHealth(engineId, result, root = process.cwd(), { ok = false, now } = {}) {
+  if (!engineId) return null;
+  if (ok) return setEngineHealth(engineId, 'ready', root);
+  const status = engineFailureHealthStatus({ ...result, status: 'errored' });
+  if (status === 'error') {
+    const stall = engineStallReason(result);
+    if (stall) return setEngineCooling(engineId, { root, now, reason: stall.kind === 'transient' ? 'connection dropped' : 'stalled' });
+  }
+  return status ? setEngineHealth(engineId, status, root) : null;
+}
+
 // Execution-stage guard. Routing hands out engines from policy without ever
 // touching the machine, so the moment we are about to spawn one is where a
 // missing binary has to fail loudly, in one plain sentence naming the binary.
@@ -1868,10 +2123,12 @@ module.exports = {
   setRosterPick,
   confirmRoster,
   normalizeRosterModel,
+  isClaudeFamilyModel,
   rosterModelLabel,
   parseRosterUntil,
   rosterPickExpired,
   rosterPinFor,
+  ROSTER_PIN_FIELDS,
   rosterMaxText,
   mainCheckoutRoot,
   ROSTER_LAYERS,
@@ -1896,6 +2153,10 @@ module.exports = {
   resolveEngineForRole,
   resolveEngineForRoleWithPreference,
   engineFailureHealthStatus,
+  engineStallReason,
+  engineReadyAt,
+  coolingView,
+  recordEngineRunHealth,
   setEngineOverrides,
   setEngineHealth,
 };