pi-squire 0.2.2 → 0.3.1

package/CHANGELOG.md

@@ -6,6 +6,68 @@ follows [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.3.1] - 2026-10-03
+
+### Changed
+
+- With auto-exit on, a delegate whose run ends on a usage-limit error now
+  closes its window, as after a normal completion. The parent still gets the
+  `failed` reply and the session file stays. Other failures still leave the
+  window open. `test/harness.test.ts` now fails its run with a `400` instead
+  of a `429`, since a `429` is a usage limit and now exits.
+
+## [0.3.0] - 2026-10-03
+
+### Added
+
+- A delegate whose run ends on a usage-limit error (a quota message, or a
+  `429` that survived Pi's retries) records a mark in
+  `pi-squire-limits.json` in Pi's agent directory. Every Pi session then
+  refuses to launch a delegate on a marked model until the mark clears.
+- A usage-limit mark clears at the reset time in the failed response's headers
+  (`retry-after`, `anthropic-ratelimit-*-reset`, `x-ratelimit-reset-*`) when
+  Pi reports them, ahead of the time in the error text.
+- An agent's `fallback:` frontmatter (comma-separated or a YAML list of
+  `provider/id`) names models to launch on, in order, when its `model` is
+  usage-limited or unusable. The tool result and the command notice name the
+  substitute and the skipped model; the call is refused only when every
+  candidate is skipped. An explicit `model` is never substituted.
+- A `failed` result from a delegate that recorded a usage-limit mark gets a
+  `Usage limit:` line after `Status:`, naming the scope and clear time.
+  `delegation_status` ends with a `Usage-limit marks:` block of the active
+  marks, and its details gain `marks`.
+- `/delegate-clear <all|provider|provider/model>` removes usage-limit marks and
+  their repeat-hit history. An argument matching no active mark changes
+  nothing and lists the active marks. No tool can clear marks.
+- Before a launch on a paid `opencode-go` model, pi-squire reads the OpenCode
+  Go quota (cached for 60 seconds). A window at 100% or `rate-limited` skips
+  the model and records a `proactive` mark that clears at the window's reset
+  time. A failed reading never blocks a launch: the result and notice say
+  "Could not read opencode-go quota: …; launched without a proactive check.",
+  and `delegation_status` shows the error in `readingErrors` until a later
+  reading succeeds. `/delegate-clear` also drops the cached reading. A proactive
+  mark that cannot be written does not stop the launch.
+- Before a launch, pi-squire reads Claude Code's usage cache for an
+  `anthropic` candidate on a Claude subscription login and skips it when its
+  5-hour or 7-day window is at 100%, or its model-scoped week is and names that
+  model. A stale cache is refreshed in the background with
+  `claude -p /usage`, at most every 5 minutes, without delaying the launch.
+- A usage-limit mark clears early when a launch considers the marked
+  `opencode-go` or OAuth `anthropic` candidate and a re-check (at most every
+  10 minutes per provider) shows every window under 100% and a window cycle
+  that began after the mark was recorded. Headroom alone never clears a mark,
+  and a model-scoped mark on `opencode-go` never clears early.
+- `delegation_status` shows how long ago a running delegate last wrote its
+  session file, at the end of its `state:` line (`last active 12 min ago`),
+  and adds the same moment to its details as `lastActiveAt`. A long gap may
+  mean the delegate is stuck but does not prove it.
+
+### Fixed
+
+- A tmux call that hangs now fails after 10 seconds with
+  `tmux <subcommand> timed out after 10 s`, instead of hanging `delegate`,
+  `delegation_status`, `delegation_close` and the background poll.
+
 ## [0.2.2] - 2026-10-02
 
 ### Fixed
@@ -86,7 +148,9 @@ author's dotfiles; the changes below are against that copy.
 
 - The published file list includes `child.ts`, which `index.ts` imports.
 
-[Unreleased]: https://github.com/gvanderclay/pi-squire/compare/v0.2.2...HEAD
+[Unreleased]: https://github.com/gvanderclay/pi-squire/compare/v0.3.1...HEAD
+[0.3.1]: https://github.com/gvanderclay/pi-squire/compare/v0.3.0...v0.3.1
+[0.3.0]: https://github.com/gvanderclay/pi-squire/compare/v0.2.2...v0.3.0
 [0.2.2]: https://github.com/gvanderclay/pi-squire/compare/v0.2.1...v0.2.2
 [0.2.1]: https://github.com/gvanderclay/pi-squire/compare/v0.2.0...v0.2.1
 [0.2.0]: https://github.com/gvanderclay/pi-squire/compare/v0.1.0...v0.2.0

package/README.md

@@ -115,10 +115,10 @@ temporary folder, not as text on the command line.
 The roster is read at call time from `<agent dir>/agents/<name>/AGENT.md`, one
 directory per agent, so a new agent is usable without a reload. Frontmatter
 carries `description`, `model` (`provider/id`) and `thinking`, and optionally
-`auto-exit` (`true` or `false`, default `true`; see [Auto-exit](#auto-exit))
-and `exclude-tools`. The body is the delegate's system prompt, appended to
-Pi's own prompt; it reaches the child as a path to a private file under the
-system temporary folder, so the text stays off the command line. The
+`auto-exit` (`true` or `false`, default `true`; see [Auto-exit](#auto-exit)),
+`exclude-tools` and `fallback`. The body is the delegate's system prompt,
+appended to Pi's own prompt; it reaches the child as a path to a private file
+under the system temporary folder, so the text stays off the command line. The
 [first-use example](#first-use) is a complete `AGENT.md`.
 
 `exclude-tools` names the tools the delegate goes without, as a
@@ -133,6 +133,11 @@ delegate's result reaches the parent through the `message:*` provider's reply
 when its run settles, not through a tool, so excluding tools cannot stop it
 answering.
 
+`fallback` lists models to try, in order, when the agent's `model` is
+usage-limited (see [Usage limits](#usage-limits)), as a comma-separated list
+or a YAML list of `provider/id`. An entry that is not `provider/id` is dropped
+with a warning; the agent still loads.
+
 The body is followed by one fixed final-message line and a paragraph naming the
 parent session's address. The delegate's task arrives as a message from that
 session, and that message and every later one from the same address are
@@ -201,7 +206,7 @@ level is refused with close matches and nothing starts.
 
 <id> scout (provider/model, thinking low)
   name: scout-<first 8 of the id>
-  state: running — the window is open and no result has arrived
+  state: running — the window is open and no result has arrived (last active 12 min ago)
   window: scout-<first 8 of the id> (@1)
   auto-exit: on — the delegate closes its window after a normal completion unless the user took over there
   session: <the delegate's session file, or its id when there is none yet>
@@ -220,6 +225,9 @@ level is refused with close matches and nothing starts.
 - **Running** means the window is open and no result has arrived. An open
   window is connection, not task state: the delegate may still be working, or
   waiting for the user, and only a result means done.
+  When the delegate's session file exists, the line ends with when it was last
+  written (`just now`, `12 min ago`, `2 h 5 min ago`). That is a hint, not
+  proof: a long gap may mean the delegate is stuck, or just thinking.
 - **Done** comes from the recorded result, and shows the envelope's status
   (`done`, `failed` or `stopped`).
 - A delegate that closed itself by auto-exit reads **done**: its result
@@ -236,11 +244,104 @@ level is refused with close matches and nothing starts.
 - When tmux cannot be asked about a window, the state is `unknown`, never
   `closed`, because a failed check is not evidence the window is gone.
 
+`delegation_status` also ends with a `Usage-limit marks:` block, one line per
+active mark: its scope, source (`reactive` or `proactive`), clear time and
+reason (cut to about 120 characters), then one line per provider whose last
+quota reading failed. The block is left out when there is neither, and shows
+even when no delegation is recorded. The details gain a `marks` array of
+`{ scope, source, reason, clearsAt }` and a `readingErrors` array (see
+[Usage limits](#usage-limits)).
+
 `delegation_close` kills the window and records the close even when the
 result has already arrived. When the window is already gone it only records
 the close. An unknown or already closed id returns a message and kills
 nothing. The delegate's session file and result envelope stay on disk.
 
+## Usage limits
+
+When a delegate's run ends on a usage-limit error, it records a mark in
+`pi-squire-limits.json` in Pi's agent directory, which every Pi session on the
+machine reads. Quota messages count, and so does a `429` that survived Pi's
+retries; overloaded and `5xx` errors do not. A mark covers the failing
+model's whole provider, except for a free model (an id ending in `-free`, or
+zero cost in Pi's registry), which is never covered by a provider mark and,
+when it is the one that failed, is marked alone.
+
+A mark clears at the reset time the error states ("try again in 30 minutes",
+`resets_at`), otherwise after 5 minutes, doubling on each repeat hit up to 6
+hours. When the failed response's headers state a reset (`retry-after`,
+`anthropic-ratelimit-*-reset`, `x-ratelimit-reset-requests` or `-tokens`),
+that time wins over the error text. Until then `delegate` and `/delegate`
+refuse a marked model passed as `model` / `--model`, and say when it clears.
+
+Without an explicit model, the delegation launches on the agent's model, or
+else on the first of its `fallback` models that has credentials and is not
+marked. The tool result and the command's notice then say, for example, "Used
+fallback opencode-go/b because alpha/fast-model is usage-limited until …", and
+the result details list the skipped models under `skipped`. When every
+candidate is marked or unusable, the call is refused with one line per
+candidate and why it was skipped.
+
+Before a launch, pi-squire also reads the OpenCode Go quota for a paid
+`opencode-go` candidate (`GET https://opencode.ai/zen/go/v1/usage`, with the
+provider's API key). A window at 100% or more, or one the provider reports as
+`rate-limited`, skips the candidate and records a `proactive` mark on
+`opencode-go`, for example "Go 5h window at 100%", that clears at that window's
+reset time (the 5-minute cooldown when none is given). A reading is reused for
+60 seconds. Free models and other providers are never read, and a candidate that
+is already marked is skipped without a read. The key is sent only to
+`https://opencode.ai`, with redirects refused: a provider or model base URL on
+another origin means no request at all.
+
+For an `anthropic` candidate used through a Claude subscription (an OAuth
+login; API-key users get no proactive check and rely on reactive marks),
+pi-squire reads Claude Code's own usage cache, the `cachedUsageUtilization`
+field of `$CLAUDE_CONFIG_DIR/.claude.json` (`~/.claude.json` when the variable
+is unset). It never calls Anthropic's usage endpoint. A 5-hour or 7-day window
+at 100% or more records a `proactive` mark on `anthropic`, cleared at that
+window's reset time. A model-scoped weekly window at 100% (for example Opus)
+marks only the `provider/model` candidates whose name or id contains the scope
+name, so other Anthropic models stay usable. The check reads the cache as it
+stands and never waits: when the cache is missing or older than 5 minutes,
+pi-squire starts `claude -p /usage --no-session-persistence` in the background
+(in a temporary directory, output discarded, killed after 30 seconds) so Claude
+Code rewrites it, at most once every 5 minutes per Pi process. It starts only
+when Claude Code state exists (`$CLAUDE_CONFIG_DIR`, or `~/.claude.json` or
+`~/.claude` when the variable is unset). A missing `claude` binary is ignored. A
+window at 100% whose reset time has already passed counts as reset and blocks
+nothing.
+
+A failed reading (for Go: no key, a base URL off the Go origin, a non-2xx
+answer, an unreadable body, a timeout, a network error; for Claude: a missing or
+unreadable cache) never blocks a launch. The tool result and the command's
+notice gain "Could not read <provider> quota: <reason>; launched without a
+proactive check.", and `delegation_status` lists the provider's last reading
+error and its time under the `Usage-limit marks:` block and in a `readingErrors`
+array of `{ provider, reason, at }`.
+
+A mark can also clear early. When a launch considers a marked `opencode-go` or
+OAuth `anthropic` candidate, pi-squire re-checks that provider's quota, at most
+once every 10 minutes per provider and never in the background, and not for a
+mark recorded less than 10 minutes ago. It clears a mark only when the reading
+succeeded, every applying window is under 100%, and a window began a new cycle
+after the mark was recorded (its reset time minus its length is later than the
+mark's time); headroom alone never clears one, because a quota endpoint can show
+headroom while the account still answers 429. A model-scoped Claude mark clears
+only when its scoped window has reset; a model-scoped mark on `opencode-go`
+never clears early, because Go has no scoped window. A window without a reset time or
+length cannot prove a reset. The tool result and the command's notice then say
+"Cleared the usage-limit mark on <scope>: its quota has reset since the mark was
+recorded." A failed re-check keeps the mark, lists the reading error in
+`delegation_status`, and adds no note.
+
+A mark can be stale (the quota came back, or the plan changed). Only you clear
+one, with `/delegate-clear <target>`: `all`, a provider (its mark and every
+model mark under it), or `provider/model` (that model's mark and the provider
+mark covering it). Clearing also forgets the repeat-hit history, so the next
+hit starts at 5 minutes again, and drops the cached quota reading so the next
+launch reads it afresh. With no argument, or one matching no active
+mark, it changes nothing and lists the active marks. No tool clears marks.
+
 ## Auto-exit
 
 The parent resolves each delegation's auto-exit from the call
@@ -252,7 +353,9 @@ The parent resolves each delegation's auto-exit from the call
   down (`ctx.shutdown()`) on the next event-loop turn, after the settle
   reply has been sent, so its tmux window closes. The session file stays, and
   `pi --session <path>` reopens it.
-- A run that ended stopped or failed never exits the delegate.
+- A run that ended stopped, or failed on anything but a usage limit, never
+  exits the delegate. A usage-limit failure is final until the quota resets,
+  so it exits like a normal completion; the parent still gets the failed reply.
 - The user taking over turns it off for the rest of the session, with a
   notice: typed or RPC input, or a run the user stopped (Esc).
 - `/auto-exit` inside the delegate turns it on again for the next normal
@@ -284,6 +387,13 @@ Delegate session: <session file or id>
   task, so the delegation stays running while the user steers it. The next
   run that completes sends the result, `done`, and its body opens with a note
   that the user took over partway.
+- A `failed` reply from a delegate that recorded a usage-limit mark (see
+  [Usage limits](#usage-limits)) gets one more line right after `Status:`,
+  for example `Usage limit: the delegate hit a usage limit on provider
+  opencode-go; it is marked until 2026-10-03T12:05:00.000Z and later
+  delegations skip it.` (a model scope reads `on model provider/id`; a mark
+  that has since cleared reads `it was marked until …`). A failed reply with
+  no such mark is unchanged.
 - The task is quoted from the request copy the provider puts on the payload,
   capped at 2 KiB with the copy's `sent/` path. A request with no copy is
   named by id alone.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-squire",
-	"version": "0.2.2",
+	"version": "0.3.1",
 	"description": "Starts a delegate Pi session in a background tmux window, sends it the task over message:*, and shows the parent its result",
 	"keywords": [
 		"pi-package",

package/src/agents.ts

@@ -33,6 +33,8 @@ export type Agent = {
 	autoExit: boolean;
 	/** Tools the delegate goes without, from `exclude-tools`; empty means all of them. */
 	excludeTools: string[];
+	/** Models to try, in order, when `model` is usage-limited; from `fallback`, empty when absent. */
+	fallback: string[];
 	/** The body of `AGENT.md`: the delegate's system prompt. */
 	prompt: string;
 };
@@ -54,7 +56,7 @@ function parseAgent(
 	path: string,
 	text: string,
 	tools: readonly string[] | undefined,
-): { agent?: Agent; warning?: string } {
+): { agent?: Agent; warning?: string; notes?: string[] } {
 	let frontmatter: Record<string, unknown>;
 	let body: string;
 	try {
@@ -94,7 +96,18 @@ function parseAgent(
 		return {
 			warning: `${path} has exclude-tools ${JSON.stringify(unknownTool)}, not a tool this session has; skipped`,
 		};
+	// A bad fallback entry is dropped with a note; it never costs the agent.
+	const notes: string[] = [];
+	const listedFallback = toolList(frontmatter.fallback);
+	if (listedFallback === null)
+		notes.push(`${path} has fallback ${JSON.stringify(frontmatter.fallback)}, not a list of provider/id; ignored`);
+	const fallback = (listedFallback ?? []).filter((entry) => {
+		if (MODEL.test(entry)) return true;
+		notes.push(`${path} has fallback ${JSON.stringify(entry)}, not provider/id; dropped`);
+		return false;
+	});
 	return {
+		notes,
 		agent: {
 			name,
 			description: description as string,
@@ -102,12 +115,13 @@ function parseAgent(
 			thinking: thinking as Thinking,
 			autoExit: autoExit ?? true,
 			excludeTools,
+			fallback,
 			prompt: body,
 		},
 	};
 }
 
-/** A tool list, comma-separated or a YAML list of names; undefined when absent, null when it is neither. */
+/** A list of names (tools or models), comma-separated or a YAML list of names; undefined when absent, null when it is neither. */
 function toolList(value: unknown): string[] | undefined | null {
 	if (value === undefined || value === null) return undefined;
 	const names = Array.isArray(value) ? value : typeof value === "string" ? value.split(",") : null;
@@ -153,7 +167,8 @@ export function readRoster(agentDir: string, tools?: readonly string[]): Roster
 			warnings.push(`${path} is not under a usable agent name; skipped`);
 			continue;
 		}
-		const { agent, warning } = parseAgent(name, path, text, tools);
+		const { agent, warning, notes } = parseAgent(name, path, text, tools);
+		warnings.push(...(notes ?? []));
 		if (agent !== undefined) agents.push(agent);
 		else if (warning !== undefined) warnings.push(warning);
 	}

package/src/child.ts

@@ -17,6 +17,8 @@
 // ponytail: drop the takeover once #5581 lands and the minimum Pi has it.
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 
+import { classify, type Response, recordLimit } from "./limits.ts";
+
 /** The launch variable that carries the parent's resolved setting. */
 export const AUTO_EXIT_ENV = "PI_DELEGATE_AUTO_EXIT";
 
@@ -24,10 +26,27 @@ const OFF_NOTICE =
 	"delegate: auto-exit is off for this session because you took over here; the window stays open. /auto-exit turns it back on.";
 const ON_NOTICE = "delegate: auto-exit is on; this delegate closes after its next normal completion.";
 
-type Message = { role?: string; stopReason?: unknown };
+type Message = { role?: string; stopReason?: unknown; errorMessage?: unknown; provider?: unknown; model?: unknown };
 
 type Inbound = { envelope?: { from?: unknown; kind?: unknown; body?: unknown }; handled?: boolean };
 
+/** A run that ended on a usage-limit error leaves a mark for every Pi session. */
+function recordUsageLimit(last: Message, ctx: ExtensionContext, response?: Response): void {
+	const { provider, model, errorMessage } = last;
+	if (typeof provider !== "string" || typeof model !== "string" || typeof errorMessage !== "string") return;
+	try {
+		recordLimit(ctx.modelRegistry, {
+			provider,
+			model,
+			message: errorMessage,
+			delegation: ctx.sessionManager.getSessionId(),
+			response,
+		});
+	} catch {
+		// A mark that cannot be written must not break the run's end.
+	}
+}
+
 export function registerChild(pi: ExtensionAPI, parent: string): void {
 	let current: ExtensionContext | undefined;
 	pi.on("session_start", async (_event, ctx) => {
@@ -59,6 +78,15 @@ export function registerChild(pi: ExtensionAPI, parent: string): void {
 		if (event.source !== "extension") disarm(ctx);
 	});
 
+	// The latest provider response of the current run; its headers may state the reset.
+	let response: Response | undefined;
+	pi.on("agent_start", async () => {
+		response = undefined;
+	});
+	pi.on("after_provider_response", async (event) => {
+		response = { status: event.status, headers: event.headers };
+	});
+
 	// Stopped mid-text the last message says `aborted`; stopped during a tool
 	// call Pi 0.99.1 ends with an `error` message, and only the signal tells a
 	// stop from a real error. Either way it is the user taking over.
@@ -70,7 +98,10 @@ export function registerChild(pi: ExtensionAPI, parent: string): void {
 		}
 		const stopped = last?.stopReason === "aborted" || ctx.signal?.aborted === true;
 		if (stopped) disarm(ctx);
-		completed = !stopped && last?.stopReason !== "error";
+		if (!stopped && last?.stopReason === "error") recordUsageLimit(last, ctx, response);
+		// A usage limit is final until the quota resets, so it ends the work like a completion.
+		const limited = typeof last?.errorMessage === "string" && classify(last.errorMessage) !== undefined;
+		completed = !stopped && (last?.stopReason !== "error" || limited);
 	});
 
 	pi.on("agent_settled", async (_event, ctx) => {

package/src/index.ts

@@ -47,9 +47,11 @@ import { Type } from "typebox";
 
 import { type Agent, isThinking, type Roster, readRoster, THINKING_LEVELS } from "./agents.ts";
 import { AUTO_EXIT_ENV, registerChild } from "./child.ts";
+import { activeMark, clearMarks, isFree, readMarks } from "./limits.ts";
 import { createResults, delegateName } from "./results.ts";
 import { createTmuxClient, type TmuxClient } from "./tmux.ts";
 import { createTracking, toolResult } from "./tracking.ts";
+import { createProactive, createUsageClient, type Proactive, type UsageClient } from "./usage.ts";
 
 /** The hook a provider of `message:*` answers with the written request. */
 const SEND = "message:send";
@@ -104,7 +106,20 @@ type SendPayload = { to: unknown; body: unknown; envelope?: { id?: unknown }; er
 type LaunchPayload = { args: string[]; env: Record<string, string>; agent: string };
 type Parsed = { agent: string; model?: string; thinking?: string; label?: string; autoExit?: boolean; task: string };
 /** A request that passed the roster, model, thinking and label checks. */
-type Start = { agent: Agent; model: string; thinking: string; label?: string; autoExit: boolean; task: string };
+type Start = {
+	agent: Agent;
+	model: string;
+	/** Candidates passed over for `model`, with why; empty unless a fallback was used. */
+	skipped: Skipped[];
+	/** Lines for the parent, such as a quota reading that failed. */
+	notices: string[];
+	thinking: string;
+	label?: string;
+	autoExit: boolean;
+	task: string;
+};
+/** A candidate model passed over: `why` finishes "<model> is …", `reason` is the long form for a refusal. */
+type Skipped = { model: string; why: string; reason: string };
 /** A delegation that is open in a tmux window. */
 type Launched = { id: string; name: string; windowId: string; windowName: string; requestId: string };
 
@@ -209,6 +224,71 @@ function modelProblem(value: string, registry: ModelRegistry): string | undefine
 	return `unknown model ${JSON.stringify(value)}${close.length > 0 ? `; close matches: ${close.join(", ")}` : ""}`;
 }
 
+/**
+ * The model for a launch. An explicit model is the only candidate; otherwise
+ * the agent's model then its fallbacks. The first candidate that passes
+ * `modelProblem` and has no active mark wins; the rest are returned as skipped.
+ * A paid candidate on a provider with a quota check is read first, and
+ * skipped when its quota is used up. Refuses, listing every candidate, when
+ * none is left.
+ */
+async function chooseModel(
+	explicit: string | undefined,
+	agent: Agent,
+	models: ModelRegistry,
+	proactive: Proactive,
+): Promise<{ model: string; skipped: Skipped[]; notices: string[] }> {
+	const candidates = explicit !== undefined ? [explicit] : [agent.model, ...agent.fallback];
+	const skipped: Skipped[] = [];
+	const notices: string[] = [];
+	for (const model of candidates) {
+		const problem = modelProblem(model, models);
+		if (problem !== undefined) {
+			skipped.push({ model, why: `unavailable (${problem})`, reason: problem });
+			continue;
+		}
+		const slash = model.indexOf("/");
+		const provider = model.slice(0, slash);
+		const id = model.slice(slash + 1);
+		let mark = activeMark(models, provider, id);
+		if (mark !== undefined) {
+			const cleared = await proactive.recheck(models, provider, id);
+			for (const line of cleared) if (!notices.includes(line)) notices.push(line);
+			if (cleared.length > 0) mark = activeMark(models, provider, id);
+		}
+		if (mark === undefined && !isFree(models, provider, id)) {
+			const checked = await proactive.check(models, provider, id);
+			if (checked.notice !== undefined && !notices.includes(checked.notice)) notices.push(checked.notice);
+			mark = activeMark(models, provider, id) ?? checked.mark;
+		}
+		if (mark === undefined) return { model, skipped, notices };
+		const what = mark.scope.includes("/") ? `model ${mark.scope}` : `provider ${mark.scope}`;
+		const until = new Date(mark.clearsAt).toISOString();
+		skipped.push({
+			model,
+			why: `usage-limited until ${until}`,
+			reason: `usage-limited (${what}) until ${until}: ${mark.reason}`,
+		});
+	}
+	if (skipped.length === 1) {
+		const [only] = skipped;
+		throw new Error(
+			only.why.startsWith("usage-limited")
+				? `${only.model} is ${only.reason}. Clear marks with /delegate-clear.`
+				: only.reason,
+		);
+	}
+	throw new Error(
+		`no model is available for agent ${agent.name}:\n${skipped.map((item) => `- ${item.model}: ${item.reason}`).join("\n")}\nClear marks with /delegate-clear.`,
+	);
+}
+
+/** The sentence that says a fallback ran, or "" when the agent's own model did. */
+const fallbackNote = (start: Start): string =>
+	start.skipped.length === 0
+		? ""
+		: `Used fallback ${start.model} because ${start.skipped.map((item) => `${item.model} is ${item.why}`).join("; ")}.`;
+
 /** Why `value` is not a thinking level, or undefined when it is. */
 function thinkingProblem(value: string): string | undefined {
 	if (isThinking(value)) return undefined;
@@ -236,7 +316,7 @@ function toolDescription(agents: readonly Agent[]): string {
 		"Agents:",
 		...agents.map(
 			(agent) =>
-				`- ${agent.name} — ${agent.description} (default ${agent.model}, thinking ${agent.thinking}${agent.autoExit ? "" : ", auto-exit off"}${
+				`- ${agent.name} — ${agent.description} (default ${[agent.model, ...agent.fallback.map((model) => `fallback ${model}`)].join(", ")}, thinking ${agent.thinking}${agent.autoExit ? "" : ", auto-exit off"}${
 					agent.excludeTools.length > 0 ? `, no ${agent.excludeTools.join("/")}` : ""
 				})`,
 		),
@@ -249,11 +329,15 @@ function toolDescription(agents: readonly Agent[]): string {
 }
 
 /**
- * Register `/delegate` and the three tools. The second parameter is a
- * test-only seam for tmux: Pi passes only `pi`, so it is not part of the
- * package's documented contract.
+ * Register `/delegate` and the three tools. The second and third
+ * parameters are test-only seams, for tmux and for the usage readers: Pi
+ * passes only `pi`, so they are not part of the package's documented contract.
  */
-export default function delegate(pi: ExtensionAPI, tmux: TmuxClient = createTmuxClient()): void {
+export default function delegate(
+	pi: ExtensionAPI,
+	tmux: TmuxClient = createTmuxClient(),
+	usage: UsageClient = createUsageClient(),
+): void {
 	// A delegate registers only its auto-exit side: `delegate` is one level deep (Q27).
 	const parentId = process.env[PARENT_ENV] ?? "";
 	if (parentId !== "") {
@@ -263,7 +347,8 @@ export default function delegate(pi: ExtensionAPI, tmux: TmuxClient = createTmux
 
 	const results = createResults(pi);
 
-	const tracking = createTracking(pi, results, tmux);
+	const proactive = createProactive(usage);
+	const tracking = createTracking(pi, results, tmux, proactive.errors);
 
 	/** Captured because `getArgumentCompletions` is called without a context. */
 	let registry: ModelRegistry | undefined;
@@ -294,7 +379,7 @@ export default function delegate(pi: ExtensionAPI, tmux: TmuxClient = createTmux
 	}
 
 	/** The request as a start, or an error naming what to fix. */
-	function validate(request: Parsed, roster: Roster, models: ModelRegistry): Start {
+	async function validate(request: Parsed, roster: Roster, models: ModelRegistry): Promise<Start> {
 		if (roster.agents.length === 0) {
 			throw new Error(
 				`no agents are defined; add ${join(
@@ -312,10 +397,8 @@ export default function delegate(pi: ExtensionAPI, tmux: TmuxClient = createTmux
 			);
 		}
 		if (request.task.trim() === "") throw new Error("a task is required");
-		const model = request.model ?? agent.model;
 		const thinking = request.thinking ?? agent.thinking;
-		const badModel = modelProblem(model, models);
-		if (badModel !== undefined) throw new Error(badModel);
+		const { model, skipped, notices } = await chooseModel(request.model, agent, models, proactive);
 		const badThinking = thinkingProblem(thinking);
 		if (badThinking !== undefined) throw new Error(badThinking);
 		const badLabel = request.label === undefined ? undefined : labelProblem(request.label);
@@ -323,6 +406,8 @@ export default function delegate(pi: ExtensionAPI, tmux: TmuxClient = createTmux
 		return {
 			agent,
 			model,
+			skipped,
+			notices,
 			thinking,
 			label: request.label,
 			autoExit: request.autoExit ?? agent.autoExit,
@@ -405,7 +490,7 @@ export default function delegate(pi: ExtensionAPI, tmux: TmuxClient = createTmux
 	}
 
 	const started = (launched: Launched, start: Start): string =>
-		`delegate: ${start.agent.name} ${launched.id} started in window ${launched.windowName}`;
+		`delegate: ${start.agent.name} ${launched.id} started in window ${launched.windowName}${start.skipped.length > 0 ? `. ${fallbackNote(start)}` : ""}${start.notices.map((line) => `. ${line}`).join("")}`;
 
 	async function command(input: string, ctx: ExtensionContext): Promise<void> {
 		const fail = (message: string) => ctx.ui.notify(`delegate: ${message}`, "error");
@@ -415,7 +500,7 @@ export default function delegate(pi: ExtensionAPI, tmux: TmuxClient = createTmux
 			return;
 		}
 		try {
-			const start = validate(outcome.parsed, rosterFor(ctx), ctx.modelRegistry);
+			const start = await validate(outcome.parsed, rosterFor(ctx), ctx.modelRegistry);
 			const launched = await launch(start, ctx);
 			ctx.ui.notify(started(launched, start), "info");
 		} catch (err) {
@@ -457,7 +542,7 @@ export default function delegate(pi: ExtensionAPI, tmux: TmuxClient = createTmux
 			ctx: ExtensionContext,
 		) {
 			if (!tmux.insideTmux()) throw new Error(NOT_IN_TMUX);
-			const start = validate(
+			const start = await validate(
 				{
 					agent: params.agent,
 					model: params.model,
@@ -472,12 +557,14 @@ export default function delegate(pi: ExtensionAPI, tmux: TmuxClient = createTmux
 			const launched = await launch(start, ctx);
 			ctx.ui.notify(started(launched, start), "info");
 			return toolResult(
-				`Started delegation ${launched.id}: ${start.agent.name} (${start.model}, thinking ${start.thinking}) in window ${launched.windowName}. It runs in the background and its result arrives as a message; delegation_status reports it and delegation_close ends it.`,
+				`Started delegation ${launched.id}: ${start.agent.name} (${start.model}, thinking ${start.thinking}) in window ${launched.windowName}. It runs in the background and its result arrives as a message; delegation_status reports it and delegation_close ends it.${start.skipped.length > 0 ? ` ${fallbackNote(start)}` : ""}${start.notices.map((line) => ` ${line}`).join("")}`,
 				{
 					outcome: "started",
 					id: launched.id,
 					agent: start.agent.name,
 					model: start.model,
+					skipped: start.skipped.map(({ model, reason }) => ({ model, reason })),
+					notices: start.notices,
 					thinking: start.thinking,
 					autoExit: start.autoExit,
 					windowId: launched.windowId,
@@ -520,6 +607,34 @@ export default function delegate(pi: ExtensionAPI, tmux: TmuxClient = createTmux
 		handler: command,
 	});
 
+	pi.registerCommand("delegate-clear", {
+		description: "Clear usage-limit marks: all, a provider, or a provider/model",
+		getArgumentCompletions: (prefix: string) => {
+			const hits = [
+				"all",
+				...readMarks()
+					.filter((m) => m.clearsAt > Date.now())
+					.map((m) => m.scope),
+			].filter((v) => v.startsWith(prefix.trim()));
+			return hits.length > 0 ? hits.map((value) => ({ value, label: value })) : null;
+		},
+		handler: async (args: string, ctx: ExtensionContext) => {
+			const target = args.trim();
+			const cleared = target === "" ? [] : clearMarks(target);
+			if (cleared.length > 0) proactive.clear();
+			const active = readMarks().filter((m) => m.clearsAt > Date.now());
+			const list = active.map((m) => `${m.scope} until ${new Date(m.clearsAt).toISOString()}`).join(", ");
+			ctx.ui.notify(
+				cleared.length > 0
+					? `delegate-clear: cleared ${cleared.join(", ")}.`
+					: active.length === 0
+						? "delegate-clear: no usage-limit marks are active."
+						: `delegate-clear: ${target === "" ? "name a mark to clear" : `no active mark matches "${target}"`}. Active marks: ${list}. Use all, a provider or provider/model.`,
+				"info",
+			);
+		},
+	});
+
 	pi.registerTool(delegateTool() as never);
 	tracking.registerTools();
 }