agent-lyceum 0.18.0 → 0.19.0

package/dist/fallback.js

@@ -0,0 +1,157 @@
+/** `<runtime>/<model>`, the model trimmed and lowercased (no model = ""), so entries naming the same model share one key. */
+const keyOf = (runtime, model) => `${runtime}/${(model ?? "").trim().toLowerCase()}`;
+/**
+ * The primary model followed by the agent's fallback chain, in order. An entry with the same key as the primary or as an
+ * earlier entry is dropped: a chain shared through `dispatcher.fallback` may list the agent's own primary (spec 20.12).
+ */
+export function candidatesFor(agent) {
+    // `validate` refuses an agent without a runtime before anything is woken.
+    const runtime = agent.runtime;
+    const primary = { runtime, model: agent.model, effort: agent.effort, primary: true, key: keyOf(runtime, agent.model) };
+    const out = [primary];
+    const seen = new Set([primary.key]);
+    for (const f of agent.fallback) {
+        const model = f.model || undefined;
+        const key = keyOf(f.runtime, model);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push({ runtime: f.runtime, model, effort: f.effort, primary: false, key });
+    }
+    return out;
+}
+/**
+ * The agent as it runs on candidate `c`: itself for the primary; for a backup, the same agent on the backup's runtime, model
+ * and effort, at the primary's effective web level (spec 20.12). A set `allow_web` carries over. Unset, claude-code has no web
+ * tools while codex keeps its own default, which may search: a codex backup of such an agent gets `none`.
+ */
+export function agentForCandidate(agent, c) {
+    if (c.primary)
+        return agent;
+    const allowWeb = agent.allowWeb ?? (agent.runtime === "claude-code" && c.runtime === "codex" ? "none" : undefined);
+    return { ...agent, runtime: c.runtime, model: c.model, effort: c.effort, allowWeb };
+}
+/** Models that failed with `rate_limit`/`quota`, and until when (epoch ms) wakes skip them. Shared by a run, kept in `state.json`. */
+export class Cooldowns {
+    table = new Map();
+    /** Cool `key` down for `sec` seconds from `now`; never shortens a longer cooldown already in place. */
+    mark(key, kind, now, sec) {
+        if (sec <= 0)
+            return;
+        const until = now + sec * 1000;
+        if ((this.table.get(key)?.until ?? 0) >= until)
+            return;
+        this.table.set(key, { until, kind });
+    }
+    /** Milliseconds of cooldown left for `key` at `now`; 0 = none. */
+    active(key, now) {
+        const until = this.table.get(key)?.until ?? 0;
+        return Math.max(0, until - now);
+    }
+    toJSON() {
+        return Object.fromEntries([...this.table].map(([k, v]) => [k, { until: new Date(v.until).toISOString(), kind: v.kind }]));
+    }
+    /** Rebuild from `toJSON()` output; a missing table (older `state.json`) is an empty one. */
+    static from(json) {
+        const c = new Cooldowns();
+        for (const [k, v] of Object.entries(json ?? {})) {
+            const until = Date.parse(v.until);
+            if (Number.isFinite(until))
+                c.table.set(k, { until, kind: v.kind });
+        }
+        return c;
+    }
+}
+/** The candidates for one wake: the chain minus those cooling down, or the whole chain when every one is (something must be tried). */
+export function planAttempts(agent, cooldowns, now) {
+    const all = candidatesFor(agent);
+    const warm = all.filter((c) => cooldowns.active(c.key, now) === 0);
+    return warm.length ? warm : all;
+}
+/**
+ * What to do after a failed call (spec 20.2 decisions 2 and 5). `attemptsOnCurrent` counts the calls made on the current
+ * candidate, the failed one included; each candidate gets `retry` retries. `legacy` (the agent has no fallback chain)
+ * keeps the old loop: every kind is retried `retry` times, then the wake fails.
+ */
+export function nextStep(kind, attemptsOnCurrent, retry, hasNext, legacy) {
+    const retriesLeft = attemptsOnCurrent <= retry;
+    if (legacy)
+        return retriesLeft ? "retry-same" : "stop";
+    switch (kind) {
+        case "rate_limit":
+        case "quota":
+            return hasNext ? "next-candidate" : "stop";
+        case "timeout":
+        case "network":
+        case "crash":
+            return retriesLeft ? "retry-same" : hasNext ? "next-candidate" : "stop";
+        case "auth":
+            return "stop";
+        default:
+            // `unknown` and unclassified failures: same model only, as before fallback existed.
+            return retriesLeft ? "retry-same" : "stop";
+    }
+}
+/** Wait before the `n`th retry (1-based) on the same candidate: 5s, 15s, 45s, then 60s. */
+export function backoffMs(n) {
+    return Math.min(5 * 3 ** (n - 1), 60) * 1000;
+}
+/** `setTimeout` as a promise that resolves early (never rejects) when `signal` aborts. */
+export function defaultSleep(ms, signal) {
+    return new Promise((resolve) => {
+        if (signal?.aborted)
+            return resolve();
+        const done = () => {
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", done);
+            resolve();
+        };
+        const timer = setTimeout(done, ms);
+        signal?.addEventListener("abort", done, { once: true });
+    });
+}
+/**
+ * The one retry/fallback loop shared by `RunSession.wake` and `call` (spec 20.2 decision 9): call each candidate,
+ * retry it or move on as `nextStep` says, back off between retries. Success and cancellation end the loop as they are.
+ */
+export async function runWithFallback(o) {
+    const first = o.candidates[0];
+    if (!first)
+        throw new Error("runWithFallback needs at least one candidate");
+    const sleep = o.sleep ?? defaultSleep;
+    const now = o.now ?? Date.now;
+    const tried = [];
+    let index = 0;
+    let used = first;
+    let ctx = { attempt: 0, candidateAttempt: 0 };
+    let result;
+    for (;;) {
+        if (o.beforeAttempt?.(used, ctx) === "stop")
+            return { result, tried, used, stopped: "beforeAttempt" };
+        result = await o.invoke(used, ctx);
+        await o.afterAttempt?.(used, result, ctx);
+        if (result.ok || result.cancelled)
+            return { result, tried, used };
+        tried.push({ runtime: used.runtime, model: used.model, kind: result.kind, error: result.error });
+        if (!o.legacy && (result.kind === "rate_limit" || result.kind === "quota"))
+            o.cooldowns.mark(used.key, result.kind, now(), o.cooldownSec);
+        const next = o.candidates[index + 1];
+        const step = nextStep(result.kind, ctx.candidateAttempt + 1, o.retry, !!next, o.legacy);
+        if (step === "stop")
+            return { result, tried, used };
+        if (step === "retry-same") {
+            if (!o.legacy) {
+                await sleep(backoffMs(ctx.candidateAttempt + 1), o.signal);
+                if (o.signal?.aborted)
+                    return { result, tried, used, stopped: "aborted" };
+            }
+            ctx = { attempt: ctx.attempt + 1, candidateAttempt: ctx.candidateAttempt + 1, previous: result };
+            continue;
+        }
+        const to = next;
+        o.onSwitch?.(used, to, result.kind, result);
+        ctx = { attempt: ctx.attempt + 1, candidateAttempt: 0, previous: result, switchedFrom: used };
+        index++;
+        used = to;
+    }
+}

package/dist/policy.d.ts

@@ -37,6 +37,8 @@ export declare function sharedIndex(project: ResolvedProject): string | undefine
 /** The repo directory this agent works in: its own worktree, or the main repo. */
 export declare function repoDirFor(project: ResolvedProject, agent: string): string;
 export declare function writePolicy(project: ResolvedProject, agent: ResolvedAgent): WritePolicy;
+/** Test seam: pretend the OS sandbox is (un)available; `undefined` re-probes the host. */
+export declare function setOsSandboxForTest(available: boolean | undefined): void;
 export declare function enforcementFor(project: ResolvedProject, agent: ResolvedAgent): AgentEnforcement;
 /** Can `agent` legitimately change this protected file? */
 export declare function mayEditProtected(project: ResolvedProject, agent: ResolvedAgent, file: string): boolean;

package/dist/policy.js

@@ -136,6 +136,10 @@ function osSandboxAvailable() {
         sandboxProbe = false;
     return sandboxProbe;
 }
+/** Test seam: pretend the OS sandbox is (un)available; `undefined` re-probes the host. */
+export function setOsSandboxForTest(available) {
+    sandboxProbe = available;
+}
 export function enforcementFor(project, agent) {
     const pol = writePolicy(project, agent);
     const os = osSandboxAvailable();

package/dist/process-runner.js

@@ -83,12 +83,14 @@ export function runInvocation(inv, opts) {
             void Promise.all([endStream(outLog), endStream(errLog)]).then(() => {
                 if (spawnError) {
                     const hint = spawnError.code === "ENOENT" ? ` ("${inv.cmd}" not found on PATH)` : "";
-                    return resolve({ ok: false, text: "", exitCode: null, timedOut: false, error: `${spawnError.message}${hint}` });
+                    // a missing binary is a crash the chain may route around (the next candidate can be another CLI); other spawn errors stay unclassified
+                    const kind = hint ? "crash" : "unknown";
+                    return resolve({ ok: false, text: "", exitCode: null, timedOut: false, error: `${spawnError.message}${hint}`, kind });
                 }
                 if (reason === "cancel")
                     return resolve({ ...cancelled, exitCode: exitCode ?? null });
                 if (reason === "timeout")
-                    return resolve({ ok: false, text: "", exitCode: exitCode ?? null, timedOut: true, error: `timed out after ${opts.timeoutSec}s` });
+                    return resolve({ ok: false, text: "", exitCode: exitCode ?? null, timedOut: true, error: `timed out after ${opts.timeoutSec}s`, kind: "timeout" });
                 const parsed = parser
                     ? parser.finish({ code: exitCode ?? null, stdoutTail: stdoutTail.text(), stderrTail: stderrTail.text() })
                     : inv.parse({ stdout: fallback.length ? fallback.toString("utf8") : stdoutTail.text(), stderr: stderrTail.text(), code: exitCode ?? null });

package/dist/run-outcome.d.ts

@@ -1,5 +1,5 @@
 import type { DoneContract } from "./format.js";
-import type { EndReason } from "./run-store.js";
+import type { EndReason, RunFailure } from "./run-store.js";
 import type { RunOutcome } from "./schema.js";
 export interface UnintegratedWork {
     agent: string;
@@ -16,17 +16,9 @@ export declare function resolveDoneOutcome(contract: DoneContract, rejections: n
 export declare function endOutcome(endReason: EndReason, done?: {
     outcome: RunOutcome;
     note?: string;
-}, failure?: {
-    agent: string;
-    error?: string;
-    attempts: number;
-}): {
+}, failure?: RunFailure): {
     outcome: RunOutcome;
     note?: string;
 };
 /** What to tell the user when an agent kept failing and the run stopped: where to look, what to fix, how to go on. */
-export declare function failureGuide(project: string, run: string, f: {
-    agent: string;
-    error?: string;
-    attempts: number;
-}, runDir: string): string;
+export declare function failureGuide(project: string, run: string, f: RunFailure, runDir: string): string;

package/dist/run-outcome.js

@@ -35,9 +35,14 @@ export function endOutcome(endReason, done, failure) {
 }
 /** What to tell the user when an agent kept failing and the run stopped: where to look, what to fix, how to go on. */
 export function failureGuide(project, run, f, runDir) {
+    // With a fallback chain: every model given up on, in order.
+    const tried = f.tried?.length
+        ? ["Models tried, in order:", ...f.tried.map((t, i) => `  ${i + 1}. ${t.model ? `${t.runtime}/${t.model}` : t.runtime}: ${t.kind ?? "unknown error"}${t.error ? ` (${t.error})` : ""}`)]
+        : [];
     return [
         "",
         `${f.agent} was called ${f.attempts} time(s) and failed every time (${f.error ?? "unknown error"}). The run stopped; nothing was lost: the message ${f.agent} was handling is still unread and the work done so far is kept.`,
+        ...tried,
         "To fix it:",
         `  1. Read why it failed: ${path.join(runDir, "log.jsonl")} (event "wake"), and the full output of each attempt in ${path.join(runDir, "mail", "attempts")}`,
         `  2. Fix the cause: the ${f.agent} CLI (installed, logged in, model name), a timeout (dispatcher.wake_timeout_sec), or its AGENT.md / the message it keeps failing on. Check with: agent-lyceum doctor -p ${project}`,

package/dist/run-session.d.ts

@@ -2,7 +2,7 @@ import { type Invoker } from "./adapters/index.js";
 import type { ResolvedProject } from "./config.js";
 import type { RunOutcome } from "./schema.js";
 import { type ResultBranch, type WorkspacePlan } from "./worktree.js";
-import { newRunId, type EndReason, type RunState } from "./run-store.js";
+import { newRunId, type EndReason, type RunFailure, type RunState } from "./run-store.js";
 import { type PreparedTask } from "./task.js";
 import { type CommandRunner, type PrOutcome } from "./open-pr.js";
 export { newRunId };
@@ -36,11 +36,7 @@ export interface RunSummary {
     /** The project's name, for the commands printed after the run. */
     project: string;
     /** The run stopped because this agent kept failing. */
-    failure?: {
-        agent: string;
-        error?: string;
-        attempts: number;
-    };
+    failure?: RunFailure;
 }
 export interface RunOptions {
     project: ResolvedProject;
@@ -65,6 +61,8 @@ export interface RunOptions {
     /** Stop the run when this fires: running agents are killed, unread mail is kept, the run ends `cancelled` and can be resumed. */
     signal?: AbortSignal;
     log?: (line: string) => void;
+    /** The wait between retries of a model with a fallback chain; tests pass one that does not wait. Default: a timer cut short by `signal`. */
+    sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
 }
 export declare class RunSession {
     private readonly opts;
@@ -89,6 +87,8 @@ export declare class RunSession {
     private doneOutcome;
     private doneNote;
     private failure;
+    /** Models cooling down after a rate limit or quota error; one table for the run, shared by parallel wake-ups. */
+    private readonly cooldowns;
     private doneVerification;
     /** The accepted `done` carried `open_pr: true` (only the lead can send `done`). */
     private openPrRequested;
@@ -113,6 +113,8 @@ export declare class RunSession {
     private pendingAgents;
     private pickBatch;
     private wake;
+    /** Copy the shared cooldown table into the state (only once something has cooled down); true when it was. */
+    private syncCooldowns;
     /**
      * A finished member's files go from its worktree into the repo before anyone reads its mail, so the lead
      * sees them. When that cannot be done, nothing is applied, the member's work stays on its branch, and the lead is told.

package/dist/run-session.js

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { realInvoker } from "./adapters/index.js";
+import { agentForCandidate, candidatesFor, Cooldowns, planAttempts, runWithFallback } from "./fallback.js";
 import { briefOf, digestOf, doneContract, mergeSteps, parseSteps } from "./format.js";
 import { ProtectedGuard } from "./guard.js";
 import { addBatch, askersWithAnswers, askReplyPath, checkAnswers, describeCheck, isComplete, markDelivered, parseAskBody, readAskReply, renderAnswers, resolveOptionLetters, writeAskReply } from "./ask-reply.js";
@@ -35,6 +36,21 @@ function readIndex(file) {
 function retryPrompt(prompt, error) {
     return `${prompt}\n\n# Retry notice\nYour previous attempt at this wake-up failed${error ? ` (${error})` : ""} after possibly changing files already. Its mail was discarded. Check the current state of the repository before redoing the work, and send the mail again.`;
 }
+/** `runtime/model`, or the runtime alone for its default model. */
+const modelLabel = (c) => (c.model ? `${c.runtime}/${c.model}` : c.runtime);
+/** Each model given up on once, in order, with its last failure (retries on the same model are one entry). */
+function lastPerModel(tried) {
+    const out = [];
+    for (const t of tried) {
+        const last = out.at(-1);
+        const entry = { runtime: t.runtime, ...(t.model ? { model: t.model } : {}), ...(t.kind ? { kind: t.kind } : {}), ...(t.error ? { error: t.error } : {}) };
+        if (last && last.runtime === t.runtime && last.model === t.model)
+            out[out.length - 1] = entry;
+        else
+            out.push(entry);
+    }
+    return out;
+}
 export class RunSession {
     opts;
     resume;
@@ -58,6 +74,8 @@ export class RunSession {
     doneOutcome;
     doneNote;
     failure;
+    /** Models cooling down after a rate limit or quota error; one table for the run, shared by parallel wake-ups. */
+    cooldowns;
     doneVerification;
     /** The accepted `done` carried `open_pr: true` (only the lead can send `done`). */
     openPrRequested = false;
@@ -225,6 +243,7 @@ export class RunSession {
         this.log = log;
         this.guard = guard;
         this.state = state;
+        this.cooldowns = Cooldowns.from(state.cooldowns);
         // Only a segment that starts here has a baseline: a fresh run or a follow-up reopen. A plain resume continues one begun by an earlier process.
         this.sharedAtStart = !resume || opts.followup ? readIndex(sharedIndex(project)) : undefined;
     }
@@ -273,7 +292,7 @@ export class RunSession {
         return pending;
     }
     async wake(agent) {
-        const { invoke, say, cfg, runDir, project, log, state, claims, attempts, noSessionNoted, opts } = this;
+        const { invoke, say, cfg, runDir, project, log, state, claims, attempts, noSessionNoted, opts, cooldowns } = this;
         const queue = listUnread(project, agent.name);
         if (queue.length === 0)
             return { ok: true };
@@ -293,92 +312,153 @@ export class RunSession {
             userPrompt: buildUserPrompt(project, agent, queue, unread.length, (state.reopened?.length ?? 0) > 0),
             timeoutSec: cfg.wake_timeout_sec,
         };
-        let result;
-        for (let attempt = 0; attempt <= cfg.retry; attempt++) {
-            if (state.max_rounds > 0 && state.rounds >= state.max_rounds) {
+        // Without a fallback chain (one candidate) the loop, its output and its records are exactly those of plain retries (spec 20.2 decision 11).
+        const all = candidatesFor(agent);
+        const chain = all.length > 1;
+        const candidates = chain ? planAttempts(agent, cooldowns, Date.now()) : all;
+        // The model a backup's calls stand in for: the one switched away from in this wake, or the cooling-down primary it started past.
+        let replaced = candidates[0]?.primary ? undefined : all[0];
+        let calls = 0;
+        let stoppedByCancel = false;
+        const outcome = await runWithFallback({
+            candidates,
+            legacy: !chain,
+            retry: cfg.retry,
+            cooldowns,
+            cooldownSec: cfg.fallback_cooldown_sec,
+            signal: opts.signal,
+            sleep: opts.sleep,
+            beforeAttempt: (_c, ctx) => {
+                // A cancel that came during the previous call: no new model is tried (without a chain the call still goes ahead, as before).
+                if (chain && ctx.attempt > 0 && opts.signal?.aborted) {
+                    stoppedByCancel = true;
+                    return "stop";
+                }
                 // The round limit (when one is set) ends the run; this message stays unread for the resume.
-                abandonClaim(runDir, claim.id);
-                claims.delete(agent.name);
-                return { ok: false, cancelled: true };
-            }
-            const round = ++state.rounds;
-            const started = Date.now();
-            const att = beginAttempt(runDir, claim.id);
-            say(`[round ${roundsLabel(state.rounds, state.max_rounds)}] waking ${agent.name} (${agent.runtime})${attempt ? ` — retry ${attempt}` : ""}`);
-            const sessionId = agent.resume ? state.sessions[agent.name] : undefined;
-            const handling = unread.map((m) => ({ from: m.meta.from, type: m.meta.type, subject: m.meta.subject, brief: briefOf(m.body), digest: digestOf(m.meta.type, m.body) }));
-            // What the panel shows for the message being worked on is uncut; the wake record below keeps the short digest.
-            const activeHandling = unread.map((m, i) => ({ ...handling[i], digest: digestOf(m.meta.type, m.body, true) }));
-            state.active[agent.name] = { round, since: new Date(started).toISOString(), handling: activeHandling };
-            this.saveState();
-            result = await invoke({ ...base, signal: opts.signal, logDir: attemptLogDir(runDir, att.id), userPrompt: attempt ? retryPrompt(base.userPrompt, result?.error) : base.userPrompt, sessionId }).catch((e) => ({
-                ok: false,
-                text: "",
-                exitCode: null,
-                timedOut: false,
-                error: e.message,
-            }));
-            if (result.sessionId && agent.resume)
-                state.sessions[agent.name] = result.sessionId;
-            if (result.outputTokens)
-                state.output_tokens += result.outputTokens;
-            delete state.active[agent.name];
-            state.wakes.push({
-                round,
-                agent: agent.name,
-                at: new Date().toISOString(),
-                duration_ms: Date.now() - started,
-                ok: result.ok,
-                output_tokens: result.outputTokens,
-                handling,
-                error: result.error,
-            });
-            state.last_wake[agent.name] = { at: new Date().toISOString(), ok: result.ok, error: result.error };
-            log("wake", {
-                agent: agent.name,
-                runtime: agent.runtime,
-                attempt,
-                ok: result.ok,
-                exit_code: result.exitCode,
-                timed_out: result.timedOut,
-                duration_ms: Date.now() - started,
-                messages: unread.map((m) => m.meta.id),
-                error: result.error,
-            });
-            this.saveState();
-            if (result.ok) {
-                attempts.set(agent.name, finishAttempt(runDir, att.id, "output_ready"));
-                if (agent.resume && !result.sessionId && !state.sessions[agent.name] && !noSessionNoted.has(agent.name)) {
-                    noSessionNoted.add(agent.name);
-                    this.note(`${agent.name} has resume: true but its ${agent.runtime} CLI reported no session id, so every wake-up starts a fresh session.`);
+                return state.max_rounds > 0 && state.rounds >= state.max_rounds ? "stop" : undefined;
+            },
+            onSwitch: (from, to, kind) => {
+                replaced = from;
+                this.syncCooldowns();
+                if (opts.signal?.aborted)
+                    return;
+                say(`  ${agent.name} falling back to ${modelLabel(to)} (${kind ?? "unknown error"})`);
+                this.note(`${agent.name} fell back from ${modelLabel(from)} to ${modelLabel(to)} (${kind ?? "unknown error"}); the backup starts a fresh session and redoes this wake-up. ` +
+                    `Anything the failed attempts already did outside the mailbox (file edits, commands) was not undone: side effects may have happened.`);
+            },
+            invoke: async (c, ctx) => {
+                calls++;
+                this.syncCooldowns();
+                const attempt = ctx.attempt;
+                // A backup runs as the same agent on another runtime/model, in a session of its own.
+                const runAs = agentForCandidate(agent, c);
+                const sessionKey = c.primary ? agent.name : `${agent.name}@${c.key}`;
+                const round = ++state.rounds;
+                const started = Date.now();
+                const att = beginAttempt(runDir, claim.id);
+                const retryN = chain ? ctx.candidateAttempt : attempt;
+                say(`[round ${roundsLabel(state.rounds, state.max_rounds)}] waking ${agent.name} (${chain ? modelLabel(c) : agent.runtime})${retryN ? ` — retry ${retryN}` : ""}`);
+                const sessionId = agent.resume ? state.sessions[sessionKey] : undefined;
+                const handling = unread.map((m) => ({ from: m.meta.from, type: m.meta.type, subject: m.meta.subject, brief: briefOf(m.body), digest: digestOf(m.meta.type, m.body) }));
+                // What the panel shows for the message being worked on is uncut; the wake record below keeps the short digest.
+                const activeHandling = unread.map((m, i) => ({ ...handling[i], digest: digestOf(m.meta.type, m.body, true) }));
+                state.active[agent.name] = { round, since: new Date(started).toISOString(), handling: activeHandling };
+                this.saveState();
+                const result = await invoke({
+                    ...base,
+                    agent: runAs,
+                    signal: opts.signal,
+                    logDir: attemptLogDir(runDir, att.id),
+                    userPrompt: attempt ? retryPrompt(base.userPrompt, ctx.previous?.error) : base.userPrompt,
+                    sessionId,
+                }).catch((e) => ({
+                    ok: false,
+                    text: "",
+                    exitCode: null,
+                    timedOut: false,
+                    error: e.message,
+                }));
+                if (result.sessionId && agent.resume)
+                    state.sessions[sessionKey] = result.sessionId;
+                if (result.outputTokens)
+                    state.output_tokens += result.outputTokens;
+                delete state.active[agent.name];
+                // With a chain only: which model ran, what it replaced, why it failed.
+                const which = chain ? { runtime: c.runtime, model: c.model, fallback_from: c.primary || !replaced ? undefined : modelLabel(replaced), kind: result.kind } : {};
+                state.wakes.push({
+                    round,
+                    agent: agent.name,
+                    at: new Date().toISOString(),
+                    duration_ms: Date.now() - started,
+                    ok: result.ok,
+                    output_tokens: result.outputTokens,
+                    handling,
+                    error: result.error,
+                    ...which,
+                });
+                state.last_wake[agent.name] = { at: new Date().toISOString(), ok: result.ok, error: result.error, ...(chain ? { runtime: c.runtime, model: c.model } : {}) };
+                log("wake", {
+                    agent: agent.name,
+                    runtime: c.runtime,
+                    attempt,
+                    ok: result.ok,
+                    exit_code: result.exitCode,
+                    timed_out: result.timedOut,
+                    duration_ms: Date.now() - started,
+                    messages: unread.map((m) => m.meta.id),
+                    error: result.error,
+                    ...(chain ? { model: c.model, fallback_from: which.fallback_from, kind: result.kind } : {}),
+                });
+                this.saveState();
+                if (result.ok) {
+                    attempts.set(agent.name, finishAttempt(runDir, att.id, "output_ready"));
+                    if (agent.resume && !result.sessionId && !state.sessions[sessionKey] && !noSessionNoted.has(agent.name)) {
+                        noSessionNoted.add(agent.name);
+                        this.note(`${agent.name} has resume: true but its ${c.runtime} CLI reported no session id, so every wake-up starts a fresh session.`);
+                    }
+                    return result;
                 }
-                break;
-            }
-            if (result.cancelled) {
-                // Stopped on purpose: not a failure to report. Its output is set aside and its input stays unread for the resume.
+                if (result.cancelled) {
+                    // Stopped on purpose: not a failure to report. Its output is set aside (its input stays unread for the resume, below).
+                    const parked = parkOutbox(runDir, outboxDir(project, agent.name), att.id);
+                    finishAttempt(runDir, att.id, "failed", { error: "cancelled", parked });
+                    return result;
+                }
+                // A failed attempt's output is never trusted: park it under the attempt, away from the next attempt's result.
                 const parked = parkOutbox(runDir, outboxDir(project, agent.name), att.id);
-                finishAttempt(runDir, att.id, "failed", { error: "cancelled", parked });
-                abandonClaim(runDir, claim.id);
-                claims.delete(agent.name);
-                say(`  ${agent.name} stopped (cancelled)`);
-                return { ok: false, cancelled: true };
-            }
-            // A failed attempt's output is never trusted: park it under the attempt, away from the next attempt's result.
-            const parked = parkOutbox(runDir, outboxDir(project, agent.name), att.id);
-            finishAttempt(runDir, att.id, "failed", { error: result.error, parked });
-            say(`  ${agent.name} failed: ${result.error ?? "unknown error"}`);
-            this.note(`${agent.name} attempt ${att.n} failed (${result.error ?? "unknown error"})${parked.length ? `; ${parked.length} output file(s) set aside in ${path.join("mail", "attempts", att.id, "outbox")}` : ""}. ` +
-                `Anything it already did outside its mailbox (file edits, commands) was not undone: side effects may have happened.`);
-        }
-        if (result?.ok)
+                finishAttempt(runDir, att.id, "failed", { error: result.error, parked });
+                say(`  ${agent.name} failed: ${result.error ?? "unknown error"}`);
+                this.note(`${agent.name} attempt ${att.n} failed (${result.error ?? "unknown error"})${parked.length ? `; ${parked.length} output file(s) set aside in ${path.join("mail", "attempts", att.id, "outbox")}` : ""}. ` +
+                    `Anything it already did outside its mailbox (file edits, commands) was not undone: side effects may have happened.`);
+                return result;
+            },
+        });
+        if (this.syncCooldowns())
+            this.saveState();
+        const { result } = outcome;
+        if (result?.ok) {
             markOutputReady(runDir, claim.id);
-        if (!result?.ok) {
-            // The agent failed every time it was called: the run stops here (see settle) and its message stays unread for the resume.
-            abandonClaim(runDir, claim.id);
-            claims.delete(agent.name);
-            return { ok: false, error: result?.error, attempts: cfg.retry + 1 };
+            return { ok: true };
         }
-        return { ok: true };
+        // The input stays unread for the resume: the round limit, or a cancel (during a call or a backoff).
+        abandonClaim(runDir, claim.id);
+        claims.delete(agent.name);
+        if (outcome.stopped === "beforeAttempt" && !stoppedByCancel)
+            return { ok: false, cancelled: true };
+        if (result?.cancelled || outcome.stopped) {
+            say(`  ${agent.name} stopped (cancelled)`);
+            return { ok: false, cancelled: true };
+        }
+        // The agent failed every time it was called: the run stops here (see settle) and its message stays unread for the resume.
+        return { ok: false, error: result?.error, attempts: calls, ...(chain ? { tried: lastPerModel(outcome.tried) } : {}) };
+    }
+    /** Copy the shared cooldown table into the state (only once something has cooled down); true when it was. */
+    syncCooldowns() {
+        const table = this.cooldowns.toJSON();
+        if (!Object.keys(table).length)
+            return false;
+        this.state.cooldowns = table;
+        return true;
     }
     /**
      * A finished member's files go from its worktree into the repo before anyone reads its mail, so the lead
@@ -543,7 +623,8 @@ export class RunSession {
         const failedIdx = results.findIndex((r) => !r.ok && !r.cancelled);
         if (failedIdx >= 0) {
             const failed = must(batch[failedIdx], "failed agent");
-            this.failure = { agent: failed.name, error: results[failedIdx]?.error, attempts: results[failedIdx]?.attempts ?? this.cfg.retry + 1 };
+            const r = results[failedIdx];
+            this.failure = { agent: failed.name, error: r?.error, attempts: r?.attempts ?? this.cfg.retry + 1, ...(r?.tried ? { tried: r.tried } : {}) };
             state.failure = this.failure;
             this.endReason = failed.name === project.lead ? "lead_failed" : "agent_failed";
             return;