@a-t-h-i/bot-lobby 0.6.5 → 0.6.7

package/README.md

@@ -2,7 +2,7 @@
 
 A [Pi](https://pi.dev) extension that turns Pi into a multi-agent software team.
 
-![The bot-lobby status scene: the oracle orchestrating DEV, DESIGN, RESEARCH and QA through a task's plan](https://raw.githubusercontent.com/a-t-h-i/bot-lobby/main/docs/gallery.png)
+![The Lobby tab: your conversation with the oracle, the activity log of every agent, and their latest thoughts](https://raw.githubusercontent.com/a-t-h-i/bot-lobby/main/docs/gallery.png)
 
 `/bot-lobby <request>` (or a request typed in the lobby) starts a task, unless
 one agent can simply do it: then it goes to the [quick-fix agent](#quick-fix-or-the-team).
@@ -16,6 +16,10 @@ The rule: **LLMs decide, the engine enforces.** Agents propose; the
 extension validates every state change, permission and approval through one
 `orchestrate` tool.
 
+The oracle is meant to be your most capable model; the agents can be smaller
+and cheaper ones. So it never assumes they are as capable as it is: it makes
+every decision itself and [briefs each agent in full](#briefing-the-agents).
+
 ## Install
 
 ```bash
@@ -35,7 +39,7 @@ tool names.
 
 1. `/bot-lobby add a login page` — starts a task; the lobby opens.
 2. Answer the Master's questions, then approve its proposal.
-3. Watch the agents work in the lobby (`alt+l` shows or hides it).
+3. Follow the agents in the lobby (`alt+l` shows or hides it): what they do, and what they think.
 
 `/bot-lobby settings` sets each agent's model, thinking level, time limit and
 extra instructions.
@@ -129,6 +133,30 @@ passwords, payments, migrations, production, personal data), or **unclear**
 - The track shows in the lobby's activity log, the task's details on the
   Tasks tab, and `/bot-lobby status`.
 
+### Briefing the agents
+
+Every agent may run on a smaller, cheaper model than the oracle's, one that
+follows instructions well but does not infer intent. So the oracle writes
+each delegation (`implement`, `scout`, `research`) as a self-contained brief
+and settles every design and architecture decision itself first:
+
+- **Goal**, the exact **Files**, numbered **What to do** with names, shapes
+  and values, the **Contracts** shared with other agents (repeated in full in
+  each brief), **Constraints**, **Done when** (checkable criteria and the
+  commands to run) and **If stuck**.
+- Plan steps are written to the same standard, so a brief is the plan step
+  made explicit, never a new decision.
+- Every agent is told to follow its brief and the approved plan exactly, use
+  the given names letter for letter, and report what does not match instead of
+  guessing. Workers end their report with a **Brief Check**: each "Done when"
+  item, met or not, with evidence.
+- The oracle holds each report to its brief. Drift, a skipped criterion or a
+  guessed choice comes back as a fix step with a more explicit brief.
+- The engine backs it up: a delegation that names nothing concrete (or a long
+  one with no done criteria) is sent back to the oracle once before any agent
+  starts. Sending the same text again goes through, so a short task that is
+  complete as written is never stuck. `workflow.briefCheck: false` turns it off.
+
 ### The full workflow
 
 - **Scouts** (read-only) investigate the domains the request touches.
@@ -188,16 +216,54 @@ everything. `workflow.freshContext: false` in the config turns this off.
 ## The lobby
 
 A full-screen view with a prompt at the bottom that talks to whatever tab is
-open. `alt+h` lists every key.
+open. `alt+h` lists every key. It is text only: no animations, just the
+conversation, the activity log and the thoughts, and a one-line status in Pi's
+footer.
 
 | Tab | What it is |
 | --- | --- |
-| **1 Lobby** | The task's status, your conversation with the oracle, an activity log of every tool call, and each agent's latest thought |
+| **1 Lobby** | Your conversation with the oracle, an activity log of every agent's steps, and each agent's latest thought |
 | **2 Tasks** | Every task and saved plan as a checklist. `s` starts a plan in a new session, `h` here; `c` comments on a plan; `a` archives, `d` deletes |
 | **3 Plan** | Plan a task with a panel of agents before building it (below) |
 | **4 Quick fix** | One agent makes a change right away, beside any running task; requests the oracle [routes here](#quick-fix-or-the-team) show up too |
 | **5 Metrics** | Run time, success rate, tokens and cost per model and agent |
 
+### Lobby
+
+![The Lobby tab](https://raw.githubusercontent.com/a-t-h-i/bot-lobby/main/docs/gallery.png)
+
+Your conversation with the oracle on the left, the activity log of every
+agent's steps on the right, and the agents' latest thoughts below. `alt+c`,
+`alt+a` and `alt+k` hide any of the three; the prompt steers the running turn.
+
+### Tasks
+
+![The Tasks tab](https://raw.githubusercontent.com/a-t-h-i/bot-lobby/main/docs/lobby-tasks.png)
+
+Every task as a checklist, with its track, plan progress, the approved plan
+and your comments on it.
+
+### Plan
+
+![The Plan tab](https://raw.githubusercontent.com/a-t-h-i/bot-lobby/main/docs/lobby-plan.png)
+
+The panel's questions, with recommended options, on the left; the draft plan
+on the right. See [Planning](#planning).
+
+### Quick fix
+
+![The Quick fix tab](https://raw.githubusercontent.com/a-t-h-i/bot-lobby/main/docs/lobby-quickfix.png)
+
+One agent's jobs, each with its live steps, the files it edited and its
+report. See [Quick fix or the team](#quick-fix-or-the-team).
+
+### Metrics
+
+![The Metrics tab](https://raw.githubusercontent.com/a-t-h-i/bot-lobby/main/docs/lobby-metrics.png)
+
+Run time, success rate, cost and tokens per model and agent, so you can see
+which cheaper models hold up.
+
 Common keys: `tab` switches tabs, `esc` browses (arrows, single-key
 commands), `ctrl+f` searches, `ctrl+s` saves the plan, `alt+o` browses
 sessions, `alt+n` starts a task in a new session, `alt+s` opens settings.
@@ -207,6 +273,25 @@ Rebind any key under `lobby.keys` in the config.
 Pi session. The Lobby tab can show any session, and your prompt steers it;
 `● waiting` in the tab bar means one has a question for you.
 
+**Agents at work.** The bottom line of the lobby shows the subagents running
+right now at its right end (`◐ DESIGN editing 2m · DEV 40s`, a running quick
+fix too), shrinking to names and then a count when the keys leave little room.
+
+**Paging.** A pane with more lines than rows shows page buttons on its bottom
+edge, `▲▲ ▲ ▼ ▼▼`: click one to scroll a page up or down (`▲▲` and `▼▼` go two
+pages). The wheel, the arrows and PageUp/PageDown still work. It applies to
+every scrolling pane: the conversation, activity and thinking, the plan draft,
+the Tasks and Quick fix lists and details, and the metrics table.
+
+**Status line when hidden.** With the lobby hidden (`alt+l`), one line under
+Pi's editor shows where things stand: a bar of the task's plan steps (or its
+stage before there is a plan) with who is working, the planning round and the
+questions waiting for you, the quick fix in hand, or `idle`. It costs nothing
+while nothing changes. Turn it off with `lobby.miniLine: false` (or in
+`/bot-lobby settings` → Lobby).
+
+![The status line under the editor while the lobby is hidden: a task, planning, idle](https://raw.githubusercontent.com/a-t-h-i/bot-lobby/main/docs/lobby-status-line.png)
+
 The conversation keeps its newest 100 messages in memory; scroll to the top
 to load the rest.
 
@@ -241,7 +326,10 @@ can be compared by looking at them.
 
 `↑↓` move · `enter` choose · `space` pick several (multi-select) · `1`–`4`
 pick · `←→` between questions · the last row takes an answer in your own words
-· `esc` puts the questions away (what you answered is kept). Editor hosts that
+· `esc` asks whether to leave (a second `enter`
+leaves, anything else keeps you answering), so a stray press does nothing.
+Questions you leave are never answered for you: the oracle waits and asks again
+when you next write, and the designer asks again before it may decide. Editor hosts that
 run Pi in RPC mode get the same questions through Pi's own dialogs.
 
 **Images.** An option can also carry an `image`: a PNG, JPEG, GIF or WebP
@@ -336,7 +424,7 @@ the result.
   "scout": { "model": "anthropic/claude-haiku-4-5-20251001", "timeoutMs": 480000 },
   "planner": { "thinking": "high", "timeoutMs": 300000 },
   "lobby": { "planningPanel": ["backend", "designer", "qa", "researcher"], "maxPlanningRounds": 5 },
-  "workflow": { "maxReviewIterations": 2, "maxParallelWorkers": 3, "stallTimeoutMs": 300000, "wrapUpAt": 0.75, "taskBudgetMinutes": 0, "fastTrack": true, "routeQuickFixes": true },
+  "workflow": { "maxReviewIterations": 2, "maxParallelWorkers": 3, "stallTimeoutMs": 300000, "wrapUpAt": 0.75, "taskBudgetMinutes": 0, "fastTrack": true, "briefCheck": true, "routeQuickFixes": true },
   "classifier": { "enabled": false, "provider": "auto", "effort": { "cheapModel": "inherit" } }
 }
 ```
@@ -347,9 +435,42 @@ the result.
   `off, minimal, low, medium, high, xhigh, max`, limited to what the model
   supports. Scouts always think at `low`.
 - `instructions` adds your own text to an agent's built-in prompt.
+- `fallbackModel` and `fallbackThinking` on any agent (and the master): see
+  [Fallback models](#fallback-models).
 - Classifier thresholds and limits (`classifier.thresholds`,
   `classifier.fileHints`) are edited in the file.
 
+## Fallback models
+
+Running the oracle on a subscription model and the agents on another provider
+means one of them can run out of usage mid-task. Give each agent class a
+**fallback model** and the **thinking level** to run it at (`/bot-lobby
+settings` → the agent → *Fallback model* / *Fallback thinking*). When a run
+fails because its model is out of usage, rate-limited, out of credit or
+unavailable, it runs again on the fallback instead of failing the task.
+
+- Works for the master, DESIGN, DEV, QA, the researcher, scouts (their fallback
+  thinks at `low` too), quick fixes and the planner and its panel seats.
+- The exhausted model is skipped for 20 minutes, so the next agents go straight
+  to their fallback instead of each spending a failed run finding out.
+- **The master** is your own Pi session: on a usage failure the session
+  switches to its fallback model and thinking level, tells you, and the oracle
+  carries on from where it stopped. Switch back with `/model` when your usage
+  returns.
+- Only usage, limit and availability errors switch model; an ordinary failure
+  still retries on the same model. If the fallback fails the same way, the run
+  fails: it does not chain to a third model.
+- The activity log says when an agent switched, and the run's receipts and the
+  Metrics tab show the model that actually ran.
+
+```json
+{
+  "master": { "model": "anthropic/claude-fable-5-1", "thinking": "high", "fallbackModel": "deepseek/deepseek-v3", "fallbackThinking": "medium" },
+  "agents": { "backend": { "model": "zai/glm-4.6", "thinking": "medium", "fallbackModel": "deepseek/deepseek-v3", "fallbackThinking": "low" } },
+  "scout": { "model": "zai/glm-4.6", "fallbackModel": "deepseek/deepseek-v3" }
+}
+```
+
 ## What the engine enforces
 
 | Rule | How |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@a-t-h-i/bot-lobby",
-  "version": "0.6.5",
+  "version": "0.6.7",
   "description": "Structured multi-agent software engineering orchestrator for Pi",
   "type": "module",
   "license": "Apache-2.0",

package/prompts/global.md

@@ -15,6 +15,24 @@ Perform your assigned responsibility precisely and remain within your domain.
 - Do not invent requirements; ask when they are genuinely ambiguous.
 - Report conclusions, evidence, decisions, findings and blockers concisely.
 
+## Following your brief
+
+The Master that instructs you plans the work and knows the whole task; you may
+be a smaller model that sees only your part. Your brief and the approved plan
+are your authority, so:
+
+- Read the whole brief and the plan before acting, and do exactly what it
+  says, in its order. Do not add features, refactors or "improvements", and do
+  not skip steps because they look unnecessary.
+- Use the names, paths, shapes and wording the brief gives you, letter for
+  letter. Where it leaves a detail open, choose the simplest option that
+  follows the existing code, and say what you chose in your report.
+- Never guess at something that matters (a contract, a file that is not there,
+  a conflict between the brief and the code). Stop that part, finish the rest,
+  and report it under Blockers or Pushback with what you found.
+- Check your own work against the brief's "Done when" list before you report,
+  criterion by criterion, and say honestly which are met and which are not.
+
 ## Hard rules
 
 - Do not add dependencies without approval.

package/prompts/master.md

@@ -68,6 +68,12 @@ more), skip the researcher when research is not needed, clarify only when it
 reads the request as ambiguous — and overrule it whenever the repository says
 otherwise. It is a hint, never a rule.
 
+When the user leaves your questions unanswered (they put them away, or
+`ask_user_question` says so), the decision is still theirs: never assume the
+answers, never fall back on the recommended options, and never carry on with
+work that depends on them. Say in one short line that the questions are
+waiting, end your turn, and ask again when they next write.
+
 When you `clarify` with options, put your recommended option first and mark
 it `(Recommended)`. When the request already makes it clearly right, the
 classifier answers for you: the reply says so, the decision is recorded, and
@@ -155,12 +161,81 @@ each `implement` task with its step number (`Step 3: ...`, or `Steps 3-4: ...`
 when one delegation covers several) so the user's checklist tracks progress
 exactly.
 
+## Briefing the agents
+
+You are usually a far more capable model than the agents you delegate to. Scouts,
+workers, the researcher and the reviewer may run on smaller, cheaper models
+that follow instructions well but do not infer intent, fill gaps sensibly or
+know what you know. Never assume they are as capable as you. Whatever you leave
+unsaid, they will guess, and a wrong guess costs a whole agent run. Your plan
+and every brief are how your goal reaches the code, so write them for a
+capable but literal reader who has read nothing but the brief and the
+repository.
+
+Every `implement` task (each assignment in a parallel batch), `scout` and
+`research` instruction is a self-contained brief with these parts, in this order:
+
+1. **Goal** — the outcome this step must produce and how it serves the user's
+   request and the approved plan, in one or two sentences. Name the step
+   number(s).
+2. **Files** — the exact paths to create or change, and the ones to leave
+   alone. When you do not know a path, say what to search for and where.
+3. **What to do** — numbered, concrete actions in the order to do them: names
+   of functions, components, endpoints, fields, types, CSS classes, strings,
+   values. Give the exact signature, shape or wording wherever it matters.
+   Write "use X", not "use a suitable library"; when a choice is left to the
+   agent, say which options are allowed and how to pick.
+4. **Contracts** — everything this step shares with another domain or step:
+   API shapes, status codes, error format, event names, shared types, data
+   formats, file locations. State them in full in every brief that touches
+   them; an agent never sees another agent's brief.
+5. **Constraints** — what it must not do: no new dependencies, no other files,
+   no refactors, no changed behavior outside the step, no restyling of code
+   it does not own. Repeat the user's explicit requirements that apply.
+6. **Done when** — a checklist of observable, checkable criteria (behaviors,
+   exact commands to run and what they should print, files that must exist),
+   including what to verify and how, with `timeout`. The agent must be able to
+   tell for itself whether it has finished.
+7. **If stuck** — what to do when something does not match the brief (a file is
+   missing, a name differs, two instructions conflict): stop that part, do not
+   invent a workaround, and report it under Blockers or Pushback with what it
+   found. Ask nothing you can answer yourself: settle it in the brief.
+
+Rules for the brief:
+
+- Decide first, delegate second. Every design, architecture and product
+  decision belongs to you; make it and write down the result. A brief must not
+  contain "consider", "as appropriate", "if needed", "etc.", "similar to",
+  "handle edge cases" or "make it look good" without the specifics. List the
+  edge cases; describe the look in concrete terms (layout, sizes, colors,
+  states).
+- Say the obvious. Repeat what you already told an earlier agent, include the
+  conventions to follow and point to an existing file to imitate by path.
+- One step, one purpose, small enough to hold in mind: a handful of files and
+  a few actions. Split anything larger into consecutive steps in the same
+  `implement` call rather than leaving the agent to sequence it. Prefer more
+  explicit detail to fewer, larger chunks.
+- The plan's steps are written to the same standard: each step names its
+  files, its actions and its done criteria, so the brief is the step made
+  explicit, never a new decision.
+- Scout and research instructions ask specific questions with the answer
+  format you want (paths, names, versions, yes/no plus evidence), and say what
+  you will do with the answer.
+
+When a report comes back, hold it to the brief: check each **Done when**
+criterion against the report's `## Brief Check`, the diff and the repository.
+Drift, a skipped criterion or a guessed choice is a fix step with a corrected,
+even more explicit brief that quotes the exact gap — not a reason to accept the
+work, and not a reason to redo it yourself. Keep every agent on your plan: if
+the code no longer matches it, say which step it deviates from and restore it.
+
 ## Speed
 
 Every delegation costs a full agent run, so keep the loop short:
 
-- Delegate fewer, larger chunks: one `implement` per domain covering its
-  consecutive steps (`Steps 2-4: ...`) rather than one call per step.
+- Delegate fewer calls, not vaguer ones: one `implement` per domain covering
+  its consecutive steps (`Steps 2-4: ...`) rather than one call per step, each
+  step still briefed in full (see Briefing the agents).
 - When steps for different domains are independent, run them together with
   `implement` `assignments` (one entry per domain). Workers then share files
   through the file desk: they claim files, queue for busy ones, and hand them

package/prompts/worker.md

@@ -19,7 +19,9 @@ them.
 
 ## Implementation
 
-- Follow the approved plan.
+- Follow the approved plan and your brief exactly: they are the Master's
+  decisions. Do not substitute your own design, rename things, or widen the
+  step. If the code contradicts the brief, do not improvise: report it.
 - Follow domain boundaries.
 
 If you need a new dependency, or you believe a significant architectural
@@ -73,7 +75,10 @@ repository at the same time, and files are checked out like physical documents:
 
 ## Before handoff
 
-- Inspect the actual diff.
+- Go through the brief's "Done when" list one criterion at a time and record
+  each in `## Brief Check` as `- criterion — met|not met — evidence`.
+- Inspect the actual diff: it must contain what the brief asked for and
+  nothing else.
 - Verify tests.
 - Update the temporary task scratchpad.
 - Report concise results.

package/src/ask/dialog.ts

@@ -9,7 +9,7 @@ import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Key, matchesKey, type Component, type TUI } from "@earendil-works/pi-tui";
 import type { LobbyTheme } from "../lobby/layout.ts";
 import { lobbyTheme } from "../lobby/theme.ts";
-import { initialState, step, type AskKey, type AskState } from "./state.ts";
+import { initialState, putAway, step, type AskKey, type AskState } from "./state.ts";
 import { renderAsk, type AskFrame } from "./view.ts";
 import { loadImages } from "./image.ts";
 import { isAbsolute, resolve } from "node:path";
@@ -68,7 +68,9 @@ export class AskDialog implements Component {
 
   /** Put the questions away from outside (the turn was aborted). */
   cancel(): void {
-    if (!this.state.result) this.handleInput("\x1b");
+    if (this.state.result) return;
+    this.state = putAway(this.state);
+    this.done(this.state.result!);
   }
 
   render(width: number): string[] {
@@ -83,7 +85,17 @@ export class AskDialog implements Component {
  * cannot draw the questionnaire. Without any UI nobody can answer: the
  * result says the questions were put away.
  */
-export const askUser: Asker = async (questions, ctx, signal, from) => {
+export const askUser: Asker = (questions, ctx, signal, from) => {
+  // A model may call the tool several times in one turn; pi runs them in parallel, and overlays opened together hide each other. One at a time.
+  const next = asking.then(() => (signal?.aborted ? { answers: [], cancelled: true } : askNow(questions, ctx, signal, from)));
+  asking = next.then(() => undefined, () => undefined);
+  return next;
+};
+
+/** Tail of the questions waiting their turn. */
+let asking: Promise<void> = Promise.resolve();
+
+const askNow: Asker = async (questions, ctx, signal, from) => {
   if (!ctx.hasUI || questions.length === 0) return { answers: [], cancelled: true };
   if ((ctx as { mode?: string }).mode === "rpc") return dialogAsker(questions, ctx, signal, from);
   // Option images are read before the questionnaire opens, so drawing it never waits on the disk.

package/src/ask/state.ts

@@ -38,10 +38,17 @@ export interface AskState {
   /** Writing the own answer of the question in view. */
   editing: boolean;
   draft: string;
+  /** Esc was pressed: asked whether to leave without answering; enter leaves, any other key keeps answering. */
+  leaving?: boolean;
   /** Set once the user submits or puts the questions away. */
   result?: AskResult;
 }
 
+/** The questions put away, with what was answered so far (also when something outside ends them). */
+export function putAway(state: AskState): AskState {
+  return { ...state, editing: false, draft: "", leaving: false, result: { answers: answersOf(state), cancelled: true } };
+}
+
 export function initialState(questions: readonly AskQuestion[]): AskState {
   return {
     questions,
@@ -127,6 +134,8 @@ function typing(state: AskState, key: AskKey): AskState {
 /** One key press. */
 export function step(state: AskState, key: AskKey): AskState {
   if (state.result) return state;
+  // Esc asks first: leaving the questions unanswered lets the oracle carry on without you, so it takes a second key.
+  if (state.leaving) return key.type === "enter" || (key.type === "text" && key.value.toLowerCase() === "y") ? putAway(state) : { ...state, leaving: false };
   if (state.editing) return typing(state, key);
   const question = state.questions[state.tab];
   if (!question) return { ...state, result: { answers: [], cancelled: false } };
@@ -153,7 +162,7 @@ export function step(state: AskState, key: AskKey): AskState {
       return advance(state);
     }
     case "escape":
-      return { ...state, result: { answers: answersOf(state), cancelled: true } };
+      return { ...state, leaving: true };
     default:
       return state;
   }

package/src/ask/tool.ts

@@ -65,12 +65,16 @@ export function invalidQuestions(questions: readonly AskQuestion[]): string | un
   return undefined;
 }
 
+/** What the model does with questions the user left unanswered: wait, never fill them in. */
+const STILL_OPEN = "Do not assume answers, do not pick the recommended options, and do not go on with work that depends on them. Say in one short line that the questions are waiting, end your turn, and put them to the user again when they next write.";
+const NOT_ANSWERED = `The user left the questions without answering. ${STILL_OPEN}`;
+
 /** What the model reads back: each question with its answer, or that it was skipped. */
 export function answerSummary(questions: readonly AskQuestion[], result: AskResult): string {
   if (result.cancelled && result.answers.length === 0) {
     // A relay that could not ask anyone (auto mode) says why.
     if (result.globalNote) return result.globalNote;
-    return "The user put the questions away without answering. Do not ask the same again right away: go on with your best judgement and say what you assumed, or ask something narrower.";
+    return NOT_ANSWERED;
   }
   const lines = questions.map((question, index) => {
     const answer = result.answers.find((entry) => entry.questionIndex === index);
@@ -82,6 +86,7 @@ export function answerSummary(questions: readonly AskQuestion[], result: AskResu
   return [
     result.cancelled ? "The user answered some questions, then put the rest away:" : "The user answered:",
     ...lines,
+    ...(result.cancelled ? ["", `The questions marked "(not answered)" are still open. ${STILL_OPEN}`] : []),
     ...(result.globalNote ? ["", `Note: ${result.globalNote}`] : []),
   ].join("\n");
 }

package/src/ask/view.ts

@@ -112,6 +112,7 @@ function previewBox(preview: Preview, width: number, rows: number, theme: LobbyT
 }
 
 function hints(state: AskState, question: AskQuestion, width: number, theme?: LobbyTheme): string[] {
+  if (state.leaving) return wrap(paint(theme, "warning", "Leave without answering? The oracle will not guess for you. enter leaves · any other key keeps answering"), width);
   const parts = state.editing
     ? ["enter keep it", "esc back to the options"]
     : [
@@ -119,7 +120,7 @@ function hints(state: AskState, question: AskQuestion, width: number, theme?: Lo
         question.multiSelect ? "space pick · enter next" : "enter choose",
         `1-${question.options.length} pick`,
         ...(state.questions.length > 1 ? ["←→ questions"] : []),
-        "esc put away",
+        "esc leave",
       ];
   return wrap(paint(theme, "dim", parts.join(" · ")), width);
 }

package/src/execution/agent-runner.ts

@@ -7,6 +7,7 @@ import { shortDuration, truncate } from "../text.ts";
 import { EditLog } from "../state/changes.ts";
 import { formatMinutes, REPORT_GRACE_MS } from "../state/budget.ts";
 import { runPiAgent, spawnPiProcess, type PiStreamEvent, type ProcessRunner, type RelayAsk } from "./pi-runner.ts";
+import { isUnavailable, looksUnavailable, markUnavailable, usableFallback } from "./fallback.ts";
 import { ASK_ENV } from "../ask/relay.ts";
 import { ASK_TOOL } from "../ask/types.ts";
 
@@ -40,6 +41,10 @@ export interface AgentRequest {
   context: AgentContext;
   model?: string;
   thinking?: string;
+  /** Where the run goes when its model runs out of usage or is unavailable. */
+  fallback?: { model: string; thinking: string };
+  /** Set by the runner once it has switched: the model that ran out. */
+  fellBackFrom?: string;
   timeoutMs: number;
   cwd: string;
   signal?: AbortSignal;
@@ -135,13 +140,24 @@ function retryable(run: AgentRun): boolean {
  */
 export async function runAgent(request: AgentRequest, run: ProcessRunner = spawnPiProcess): Promise<AgentRun> {
   const startedAt = new Date().toISOString();
-  const attempts = Math.max(1, (request.retries ?? 0) + 1);
+  let attempts = Math.max(1, (request.retries ?? 0) + 1);
   // A failed attempt may have edited files before the retry: the run owns every edit.
   const edits = new EditLog(request.cwd);
   let last: AgentRun | undefined;
+  // A model already known to be out of usage goes straight to the fallback.
+  const other = usableFallback(request.fallback, request.model);
+  if (other && isUnavailable(request.model)) request = switchToFallback(request, other, request.model ?? "the session model");
   for (let attempt = 1; attempt <= attempts; attempt++) {
     last = await runAgentOnce(request, run, attempt, startedAt, edits);
     request.onAttemptEnd?.(last);
+    // Out of usage (or the model unavailable): the same model would fail again, so the fallback takes the retry.
+    const fallback = usableFallback(request.fallback, request.model);
+    if (fallback && !request.fellBackFrom && last.status === "failed" && looksUnavailable(last.error)) {
+      if (request.model) markUnavailable(request.model);
+      request = switchToFallback(request, fallback, request.model ?? "the session model");
+      attempts += 1;
+      continue;
+    }
     if (!retryable(last)) break;
     // Under a budget a retry only uses what is left of the allotment.
     if (request.time && request.time.endsAt - Date.now() < MIN_ATTEMPT_MS) break;
@@ -150,6 +166,11 @@ export async function runAgent(request: AgentRequest, run: ProcessRunner = spawn
   return edited.length > 0 ? { ...last!, edited } : last!;
 }
 
+/** The request moved to its fallback model and thinking level. */
+function switchToFallback(request: AgentRequest, fallback: { model: string; thinking?: string }, from: string): AgentRequest {
+  return { ...request, model: fallback.model, thinking: fallback.thinking ?? request.thinking, fellBackFrom: from };
+}
+
 /** Abort every in-flight subagent (session shutdown, user cancel). */
 export function cancelAllRuns(): void {
   for (const controller of activeControllers) controller.abort();
@@ -168,6 +189,7 @@ function baseRun(request: AgentRequest, runId: string, startedAt: string, attemp
     attempts,
     startedAt,
     ...(request.thinking ? { thinking: request.thinking } : {}),
+    ...(request.fellBackFrom ? { fellBackFrom: request.fellBackFrom } : {}),
     ...(request.routedFrom ? { routedFrom: request.routedFrom } : {}),
     ...(request.route ? { route: request.route } : {}),
     ...(request.time ? { allotMs: request.time.allotMs, endsAt: request.time.endsAt } : {}),

package/src/execution/fallback.ts

@@ -0,0 +1,75 @@
+/**
+ * Fallback models. A subscription or key that runs out mid-task (a usage
+ * limit, a rate limit, no credit, the provider down or refusing the key)
+ * fails every run on that model the same way, so the run goes to the agent's
+ * configured fallback model instead, and the exhausted model is skipped for a
+ * while so the next agents do not each spend a failed run finding out.
+ */
+
+/** What a provider says when a model cannot be used right now. Deliberately narrow: an ordinary failure is not a reason to switch model. */
+const UNAVAILABLE = [
+  /usage limit/i, /rate.?limit/i, /\bquota\b/i, /limit (?:reached|exceeded|will reset)/i, /exceeded (?:your|the|current)/i,
+  /out of (?:usage|credits?|extra usage|tokens)/i, /(?:insufficient|no) (?:credits?|funds|balance|quota)/i, /credit balance/i,
+  /billing/i, /payment required/i, /\b402\b/, /\b429\b/, /too many requests/i, /resource.?exhausted/i,
+  /overloaded/i, /\b529\b/, /(?:at|over) capacity/i, /resets? (?:at|in|on)/i, /subscription/i,
+  /unauthori[sz]ed/i, /\b401\b/, /invalid (?:api )?key/i, /no api key/i, /authentication (?:failed|error)/i,
+  /model (?:is )?(?:not found|not available|unavailable)/i, /unknown model/i, /does not have access/i,
+];
+
+/** True when a failed run's error says its model is out of usage or unavailable, so another model may succeed. */
+export function looksUnavailable(error: string | undefined): boolean {
+  return Boolean(error && UNAVAILABLE.some((pattern) => pattern.test(error)));
+}
+
+/** How long a model that ran out is skipped before it is tried again. */
+export const COOLDOWN_MS = 20 * 60 * 1000;
+
+const exhausted = new Map<string, number>();
+
+/** Remember that `model` cannot be used until the cooldown passes. */
+export function markUnavailable(model: string, now = Date.now()): void {
+  exhausted.set(model, now + COOLDOWN_MS);
+}
+
+/** Whether `model` ran out recently enough to skip. */
+export function isUnavailable(model: string | undefined, now = Date.now()): boolean {
+  if (!model) return false;
+  const until = exhausted.get(model);
+  if (until === undefined) return false;
+  if (until <= now) {
+    exhausted.delete(model);
+    return false;
+  }
+  return true;
+}
+
+/** Forget every exhausted model (tests). */
+export function resetUnavailable(): void {
+  exhausted.clear();
+}
+
+/** A fallback worth switching to: a model other than the one that failed. */
+export function usableFallback<F extends { model: string }>(fallback: F | undefined, current: string | undefined): F | undefined {
+  return fallback && fallback.model !== current ? fallback : undefined;
+}
+
+/**
+ * Run `attempt` on `model`; when it fails because that model is out of usage
+ * or unavailable, run it again on the fallback. A model already known to be
+ * out goes straight to the fallback. `switched` says which model took over.
+ */
+export async function withFallback<T extends { status: string; error?: string }>(
+  model: string | undefined,
+  thinking: string,
+  fallback: { model: string; thinking: string } | undefined,
+  attempt: (model: string | undefined, thinking: string) => Promise<T>,
+): Promise<{ result: T; switchedFrom?: string }> {
+  const other = usableFallback(fallback, model);
+  if (other && isUnavailable(model)) return { result: await attempt(other.model, other.thinking), switchedFrom: model ?? "the session model" };
+  const result = await attempt(model, thinking);
+  if (other && result.status === "failed" && looksUnavailable(result.error)) {
+    if (model) markUnavailable(model);
+    return { result: await attempt(other.model, other.thinking), switchedFrom: model ?? "the session model" };
+  }
+  return { result };
+}

package/src/index.ts

@@ -21,7 +21,7 @@ export default function (pi: ExtensionAPI): void {
   // Before the lifecycle, so a task that ended while the oracle was idle is closed before it builds the next turn's prompt.
   registerFreshContext(pi, CONFIG_DIR_NAME);
   registerLifecycle(pi, CONFIG_DIR_NAME);
-  // After the lifecycle, so the lobby opens over a task the widget state already knows.
+  // After the lifecycle, so the lobby opens over a task the status already knows.
   registerLobbyEvents(pi, CONFIG_DIR_NAME);
   registerOwner(pi, CONFIG_DIR_NAME);
   onTransition((task) => pingTransition(task));