@ferris1225/pi-subagents 0.31.0 → 1.0.0

package/README.md

@@ -11,18 +11,39 @@ Focused background delegation for [pi](https://pi.dev): `explore` / `worker` /
 to the main agent automatically. Install it, and the main model starts using it
 on its own — no prompt engineering, no babysitting.
 
+## 1.0 — controllable agent threads
+
+Version 1.0 turns pi-subagents from a one-shot background runner into a small
+thread runtime. Every dispatch has a stable run id and retained Pi session, so
+work can be steered while it runs, parked without losing context, resumed after
+settlement, retargeted, or forked into another path. An internal append-only
+lifecycle trajectory keeps retries and stale generations from corrupting the
+logical thread.
+
+The common quality loop now runs end to end without waking the main agent between
+steps:
+
+```text
+reviewer (find blockers) → worker (fix) → reviewer (verify) → final PASS/FAIL
+```
+
+Each chain is delivered as one concise completion group, while full per-run
+reports remain available through `subagent_status`. Ordered model pools keep the
+same retained context across provider fallback, and isolated parallel workers
+use detached Git worktrees whose changes are applied back without touching the
+parent index.
+
 ## Highlights
 
 - **Zero-setup proactive dispatch** — the extension injects a delegation directive
   into the main system prompt, so the main model automatically sends broad searches
   to `explore`, self-contained implementations to `worker`, and pre-commit reviews
   to `reviewer`. You just use pi; delegation happens by itself.
-- **Vision-capable image tasks** — a task that may need to view screenshots,
-  mockups, or design files is flagged `vision: true`; the sub-agent then runs on
-  the vision model you configure in `/subagents-setup`. Not configured? It falls
-  back to the main session's current model. Configured model unavailable? You are
-  asked to pick a replacement, which is persisted. The agents know they can `read`
-  image files when the brief asks.
+- **Vision-capable image tasks** — flag screenshot/mockup/design work with
+  `vision: true`. The configured vision primary is followed by that agent's
+  backup and the current main-window model. Setup lists only in-scope,
+  image-capable models from providers with a configured API key or OAuth session,
+  and runtime failures never silently rewrite your configuration.
 - **Results come back on their own** — completions are delivered as messages that
   wake the main agent automatically, even mid-turn. No polling, no `sleep`, no
   "go check" step. `subagent_wait` is a **non-blocking** in-turn lookup by default
@@ -35,23 +56,24 @@ on its own — no prompt engineering, no babysitting.
 - **A quality gate that closes the loop** — when a reviewer returns `REVIEW_FAIL`,
   the extension dispatches a worker briefed with the concrete findings, then a
   re-review, up to `maxFixRounds` times — and only then wakes the main agent.
-- **Self-healing model management** — unavailable configured models are repaired
-  and persisted automatically; a provider hiccup retries the same model up to 5×
-  with backoff, then falls back once to the main window's model; terminal errors
-  (quota/auth) short-circuit straight to the main agent; an idle watchdog kills
-  runs that go silent; startup races are retried with backoff.
-- **Resumes, not restarts, on a model switch** — every run is session-backed, so
-  a model quota/auth failure resumes on another model with its earlier searches,
-  reads, and edits intact (no re-scanning). When every model is out, the run is
-  handed back with its session preserved for a one-call `subagent({ resume })`.
+  Every round stays in the triggering reviewer's cwd, and chains that target the
+  same repository are serialized so shared-checkout edits cannot race.
+- **Ordered model pools without config churn** — each agent can have a primary
+  and backup; the current main-window model is the final candidate. Transient
+  provider failures retry the same candidate with backoff, while permanent stale
+  model/config errors and quota/auth errors advance immediately. Saved refs are
+  never rewritten behind your back.
+- **Resumes, retargets, and forks preserve context** — every run is session-backed.
+  `subagent_control` can steer active work, retarget it after a stable abort,
+  park/resume it under the same run id, or fork a parked/settled checkpoint into
+  a new independent run. Concurrent resume calls are serialized.
 - **Honest completions** — a run that ended with failed tool calls (e.g. a broken
   build) is reported as `completed with N failed tool call(s)` with the errors
   attached — a cheerful final text can never hide a failure.
-- **Parallel fan-out** — independent tasks run concurrently up to a configurable
-  limit (default 4).
-- **Live progress widget** — each run's status, current activity, model, token
-  usage, and elapsed time; auto-fix chain rounds hang under their triggering
-  review as a tree, each finished round keeping a one-line outcome.
+- **Parallel fan-out with filesystem isolation** — independent tasks run up to a
+  configurable limit (default 4). Parallel workers default to detached Git
+  worktrees; tracked, deleted, untracked, and binary changes are applied back
+  without touching the parent index. Failed integration keeps recovery artifacts.
 - **Recursion is structurally impossible** — children are leaf processes; the
   `subagent` tool is excluded from their toolset.
 - **Zero runtime dependencies** — agents are plain Markdown files; overriding or
@@ -121,32 +143,70 @@ subagent({
 });
 ```
 
-The sub-agent reads the images with its `read` tool. Model selection for
-vision-flagged runs: configured `visionModel` → main session's current model →
-agent's own model. When a configured vision model is no longer available, the
-TUI asks you to pick a replacement (persisted); outside the TUI it warns and
-falls back. A vision-flagged auto-fix chain keeps its worker/re-review rounds on
-the vision model too, since they re-read the same images.
+The sub-agent reads images with its `read` tool. Runtime order for a
+vision-flagged run is configured `visionModel` → that agent's configured backup
+→ current main-window model (deduplicated). A stale configured ref is attempted
+once, then skipped as a permanent candidate error; it is not rewritten. A
+vision-flagged auto-fix chain keeps the flag for worker/re-review rounds because
+they may need to inspect the same images.
+
+### Controlling and stopping
 
-### Waiting, inspecting, stopping
+Dispatch confirmations, tool result rows, and completion blocks all show the
+stable `#id`, so a thread remains directly controllable after its live UI is gone.
 
+- `subagent_control` — `steer`, `retarget`, `park`, `resume`, or `fork` a logical
+  thread by stable run id. Resume accepts an optional replacement objective;
+  fork creates a new id and leaves the source unchanged. Park active work before
+  forking it.
 - `subagent_wait` — in-turn result lookup. **Non-blocking by default**: a settled
-  run returns its result immediately; a still-active run tells the model to end
-  its turn (the wake-up message arrives on its own). Pass `timeoutMs` only when
-  you must stay in the turn.
-- `subagent_status` — what is running now, what finished this session, full
-  result by run id.
-- `subagent_stop` — cancel a run (or all); the child is terminated and an aborted
-  result with partial output is delivered.
+  run returns immediately; an active run tells the model to end its turn. Pass
+  `timeoutMs` only when you must stay in the turn.
+- `subagent_status` — active/parked/finished runs and full result by run id.
+- `subagent_stop` — destructive cancellation. It retires that thread's retained
+  session (independent forks survive) and delivers exactly one aborted partial
+  result after the run and any worktree integration have quiesced.
+
+Examples:
+
+```ts
+subagent_control({ action: "steer", id: 7, instruction: "Check the Windows path too." });
+subagent_control({ action: "park", id: 7 });
+subagent_control({ action: "resume", id: 7, objective: "Finish the tests." });
+subagent_control({ action: "fork", id: 7, objective: "Try the smaller alternative." });
+```
+
+### Worktree isolation
+
+Single tasks default to `isolation: "shared"`. Parallel `worker` tasks default
+to `isolation: "worktree"`; opt into shared mode only when a worker must see the
+caller's live uncommitted tree. Worktree mode requires a Git repository with a
+committed `HEAD` and is rejected for read-only agents.
+
+A parked isolated thread keeps its current worktree. Resume it there; fork is
+available after that isolated checkpoint settles and its seed is integrated.
+Resuming or forking a settled isolated thread creates a fresh worktree, merges a
+recorded checkpoint onto the current `HEAD` (including when the seed was already
+committed), and clones the Pi session with the new cwd. Forks then integrate only
+their unique follow-on edits, so a shared seed is applied once. A run remains
+active while final Git integration is in progress and becomes `done` only after
+that boundary finishes.
+
+Every Git operation has a 120-second deadline and process-tree cleanup; captured
+Git output and binary patches are capped at 64 MiB. Setup/bound failures surface
+instead of hanging. Finalization failures retain the patch/worktree when
+available and are recorded in `~/.pi/agent/pi-subagents-recovery.json`; later
+sessions show the recovery paths again until the artifacts are removed.
 
 ## Configuration
 
 Stored at `~/.pi/agent/pi-subagents.json` (follows `PI_CODING_AGENT_DIR` when
-set). The `/subagents-setup` wizard drives every field interactively — models,
-thinking levels, the vision model, concurrency, fix rounds, idle timeout, scope,
-and injection — with a per-agent "configure one" menu when the config already
-exists. `notifyOnReviewPass` and `maxResultLines` are edited directly in the
-file.
+set). The `/subagents-setup` wizard drives every field interactively — models, the
+default plus each enabled agent's thinking level, the vision model, concurrency,
+fix rounds, idle timeout, scope, and injection — with a per-agent "configure
+one" menu when the config already exists. Model pickers show only models in the
+current session scope that are available through a configured API key or OAuth
+session. `notifyOnReviewPass` and `maxResultLines` are edited directly in the file.
 
 ```json
 {
@@ -154,6 +214,9 @@ file.
   "agentModels": {
     "explore": "anthropic/claude-haiku-4-5"
   },
+  "agentBackupModels": {
+    "explore": "openai/gpt-5-mini"
+  },
   "agentThinkingLevels": {
     "explore": "low"
   },
@@ -172,7 +235,8 @@ file.
 | Field | Description |
 | --- | --- |
 | `enabledAgents` | Agent names exposed to discovery and prompt injection. An empty array disables all agents. |
-| `agentModels` | Optional `provider/model-id` override per agent. |
+| `agentModels` | Optional primary `provider/model-id` override per agent. |
+| `agentBackupModels` | Optional backup per agent, tried after its primary and before the current main-window model. |
 | `agentThinkingLevels` | Optional thinking level per agent; agents without an entry use the agent's frontmatter `thinking`, then `thinkingLevel`. |
 | `thinkingLevel` | Default thinking level: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max` (default `high`). |
 | `visionModel` | Optional vision-capable model for `vision: true` tasks (screenshots/mockups/designs). Unset = falls back to the main session's current model. |
@@ -184,40 +248,41 @@ file.
 | `maxFixRounds` | Auto-fix rounds when a reviewer returns `REVIEW_FAIL` (default 2; `0` disables the loop). |
 | `idleTimeoutSec` | Idle watchdog: a sub-agent whose stdout goes silent for this long is terminated and retried. `0` disables it. Default 90. |
 
-### Model precedence
+### Model precedence and fallback
 
-```text
-per-agent override → current main-session model → agent frontmatter model
-```
-
-For vision-flagged runs:
+Normal run pool:
 
 ```text
-visionModel (configured) → current main-session model → agent model
+configured agent primary → configured agent backup → current main-window model
 ```
 
-Unavailable configured models are replaced with a usable current-session model
-and the repaired config is saved. At runtime, a model that fails at the provider
-level before producing output is retried (same model up to 5× on transient
-errors, then once with the main window's model — per-run only, never persisted);
-if everything fails, the task is handed back to the main window with
-instructions to execute it directly.
+If no primary is configured, the current main-window model is primary; the
+agent frontmatter model is used only when no current main model exists. For
+vision runs, `visionModel` replaces the first slot while the selected agent's
+backup and current main model remain the fallbacks. Duplicate refs are removed.
+
+Each candidate gets startup-race retries. Provider failures retry the same
+candidate up to five times only when transient (timeouts, network, 429, 5xx).
+Permanent model/config failures (`model not found`, unknown provider, 404) and
+quota/auth/billing failures skip that delay and advance immediately. No runtime
+outcome rewrites `pi-subagents.json`. If the whole pool fails, the result is
+handed to the main window with its retained run id and session.
 
-### Resuming after a model quota/auth failure
+### Resuming retained context
 
-Every sub-agent run is **session-backed**: its pi session is persisted to a
-temp dir for the run. When a model fails at the provider level, the retry and
-the fallback **resume that session** instead of starting over — so a model
-switch inherits the sub-agent's earlier searches, reads, and edits and never
-re-scans. If every available model is exhausted (e.g. the account is out of
-quota), the run is handed back with its session preserved; once you have a
-working model again, resume it in-context:
+Every run stores its Pi session in a private temp directory. Same-model retries
+and pool fallbacks resume that session, so searches, reads, reasoning, and edits
+remain in context. A parked, completed, or failed thread can later be resumed
+under its stable id:
 
 ```ts
-subagent({ resume: 7 }); // continue run #7 from where its model stopped
+subagent_control({ action: "resume", id: 7 });
+subagent_control({ action: "resume", id: 7, objective: "Continue with the repaired credentials." });
 ```
 
-The session is reclaimed once the resume succeeds (or when the session ends).
+Use `fork` when both paths should remain available. `subagent_stop` is the
+explicit destructive operation that retires a retained session; otherwise
+sessions live until the parent Pi session shuts down.
 
 ### Configuration migration
 
@@ -230,7 +295,8 @@ after an update via a toast (marker persisted in `announcedFeatures`).
 ## Agent discovery and overrides
 
 - Built-in agents ship with the package; user agents live in `~/.pi/agent/agents/`;
-  project agents in the nearest `.pi/agents/` directory.
+  project agents in the nearest `.pi/agents/` directory are loaded only when Pi
+  trusts that project.
 - For duplicate names: project overrides user overrides built-in. Keep the
   matching filename and `name` field to replace a built-in agent.
 - Optional frontmatter: `model` (default model reference), `thinking` (default
@@ -239,16 +305,18 @@ after an update via a toast (marker persisted in `announcedFeatures`).
 
 ## How it stays reliable
 
-- **Three-layer model resilience** — same-model retry with backoff on transient
-  provider errors (503/429/timeout/network), then a one-shot fallback to the main
-  window's model. Terminal errors (quota/billing/invalid key/auth) never retry.
+- **Ordered model resilience** — transient failures retry the same candidate,
+  then advance through configured backup and current-main candidates. Permanent
+  stale-model/config and quota/auth/billing errors skip same-model backoff.
 - **Startup-race retries** — a silent zero-activity child exit (concurrent pi
   startup lock contention) is relaunched with backoff; only clean silent exits
   qualify, so real work is never duplicated.
 - **Idle watchdog** — a stalled provider stream (no output for `idleTimeoutSec`)
   terminates the child and retries via the normal fallback path.
-- **Dispatch crashes surface** — an exception in the dispatch layer produces a
-  failed result with a notification, never a silent hang.
+- **Dispatch failures surface** — partial parallel startup reports every failed
+  item and reason; if none start, the tool throws so Pi records a real tool error.
+  Dispatch crashes likewise produce a failed result instead of a silent hang.
+- **Safe live status** — tool activity is credential-redacted and stripped of terminal control sequences before `subagent_status` can return it.
 - **Leaf children** — no nested delegation, no runaway trees.
 
 ## Development
@@ -259,11 +327,13 @@ npm run check
 npm test
 ```
 
-The source is modular: `dispatch.ts` (subagent tool + auto-fix chain + vision
-model), `tools.ts` (wait/status/stop), `widget.ts` (widget + announcements),
-`runtime.ts` (shared session state), `spawn.ts` (child process layer),
-`monitor.ts` (run tracking), `setup.ts` (wizard), `prompt.ts` (delegation
-directive). No runtime dependencies beyond pi peer dependencies.
+The source is modular: `dispatch.ts` (dispatch, controls, isolation, auto-fix),
+`rpc-run.ts` / `spawn.ts` (persistent child transport + model pools),
+`worktree.ts` / `session-fork.ts` (filesystem/session branching),
+`trajectory.ts` (internal lifecycle history), `tools.ts`
+(wait/status/control/stop), `announcements.ts` (recovery and feature notices),
+and `runtime.ts` (session-scoped ownership). No runtime dependencies beyond pi peer
+dependencies.
 
 ## License
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ferris1225/pi-subagents",
-  "version": "0.31.0",
-  "description": "Focused sub-agent delegation for pi: explore / worker / reviewer agents in isolated context, with proactive dispatch injection and per-agent model selection.",
+  "version": "1.0.0",
+  "description": "Controllable background sub-agent threads for pi: explore, worker, reviewer, auto-fix chains, model pools, and Git worktree isolation.",
   "type": "module",
   "license": "MIT",
   "publishConfig": {

package/src/agents.ts

@@ -123,16 +123,16 @@ function findNearestProjectAgentsDir(cwd: string): string | null {
 export interface DiscoverOptions {
 	/** Which directories to read from. Default: "user". */
 	scope?: AgentScope;
-	/** If provided and non-empty, only agents whose name is listed are returned. */
+	/** If provided, only agents whose name is listed are returned. */
 	enabledNames?: readonly string[];
-	/** Per-agent model override ("provider/model-id"), keyed by agent name. */
-	modelOverrides?: Record<string, string>;
+	/** Project-controlled prompts are loaded only after Pi trusts the project. */
+	projectTrusted?: boolean;
 	/** Override the built-in agents directory (used by tests). */
 	builtinDir?: string;
 }
 
 /**
- * Discover agents across scopes, apply enable-filter and model overrides.
+ * Discover agents across scopes and apply the enabled-name filter.
  * Override priority for the same name: project > user > builtin.
  */
 export function discoverAgents(cwd: string, options: DiscoverOptions = {}): AgentDiscoveryResult {
@@ -143,7 +143,9 @@ export function discoverAgents(cwd: string, options: DiscoverOptions = {}): Agen
 	const builtin = loadAgentsFromDir(builtinDir, "builtin");
 	const user = scope === "project" ? [] : loadAgentsFromDir(join(getAgentDir(), "agents"), "user");
 	const project =
-		scope === "user" || !projectAgentsDir ? [] : loadAgentsFromDir(projectAgentsDir, "project");
+		scope === "user" || !projectAgentsDir || options.projectTrusted !== true
+			? []
+			: loadAgentsFromDir(projectAgentsDir, "project");
 
 	// Merge with override priority builtin < user < project.
 	const byName = new Map<string, AgentConfig>();
@@ -153,18 +155,11 @@ export function discoverAgents(cwd: string, options: DiscoverOptions = {}): Agen
 
 	let agents = Array.from(byName.values());
 
-	if (options.enabledNames && options.enabledNames.length > 0) {
+	if (options.enabledNames !== undefined) {
 		const enabled = new Set(options.enabledNames);
 		agents = agents.filter((agent) => enabled.has(agent.name));
 	}
 
-	if (options.modelOverrides) {
-		agents = agents.map((agent) => {
-			const override = options.modelOverrides?.[agent.name];
-			return override ? { ...agent, model: override } : agent;
-		});
-	}
-
 	return { agents, projectAgentsDir };
 }
 

package/src/announcements.ts

@@ -0,0 +1,59 @@
+/** Session-start recovery and one-time feature announcements. */
+
+import { stat } from "node:fs/promises";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { loadConfig, saveConfig } from "./config.ts";
+import { announceRecoveryRecords } from "./recovery.ts";
+import type { SubagentRuntime } from "./runtime.ts";
+
+const ANNOUNCEMENTS: Array<{
+	key: string;
+	condition: (config: Awaited<ReturnType<typeof loadConfig>>) => boolean;
+	message: string;
+}> = [
+	{
+		key: "visionModel",
+		condition: (config) => config.visionModel === undefined,
+		message:
+			"pi-subagents: new — a vision-capable model can now handle image tasks (screenshots, mockups, designs). Run /subagents-setup to configure it; until set, vision tasks use the main session's current model.",
+	},
+];
+
+async function announceNewFeatures(
+	ctx: { ui: { notify: (message: string, kind: "info" | "warning" | "error") => void } },
+	runtime: SubagentRuntime,
+): Promise<void> {
+	try {
+		let configExists = true;
+		try {
+			await stat(runtime.configPath);
+		} catch {
+			configExists = false;
+		}
+		if (!configExists) return;
+
+		const config = await loadConfig(runtime.configPath);
+		const pending = ANNOUNCEMENTS.filter(
+			(announcement) =>
+				announcement.condition(config) && !config.announcedFeatures.includes(announcement.key),
+		);
+		if (pending.length === 0) return;
+		await saveConfig(
+			{
+				...config,
+				announcedFeatures: [...config.announcedFeatures, ...pending.map((announcement) => announcement.key)],
+			},
+			runtime.configPath,
+		);
+		for (const announcement of pending) ctx.ui.notify(announcement.message, "info");
+	} catch {
+		/* announcement failures are non-fatal */
+	}
+}
+
+export function registerAnnouncements(pi: ExtensionAPI, runtime: SubagentRuntime): void {
+	pi.on("session_start", async (_event, ctx) => {
+		await announceRecoveryRecords(runtime.configPath, ctx);
+		if (ctx.mode === "tui") await announceNewFeatures(ctx, runtime);
+	});
+}

package/src/background.ts

@@ -14,6 +14,7 @@ export type BackgroundTask = (signal: AbortSignal) => Promise<void>;
 interface PendingTask {
 	task: BackgroundTask;
 	controller: AbortController;
+	complete: () => void;
 	/** Called when a queued task is aborted before its body ever runs (drain skips
 	 * an already-aborted entry; cancelAll aborts every pending entry), so the
 	 * task body never produces a result. Callers that resolve waiters on a run id
@@ -23,13 +24,15 @@ interface PendingTask {
 	onCancelled?: () => void;
 	/** Invoked when the task throws and was not cancelled (cancellation is not a
 	 * failure — e.g. session shutdown races must never be reported as errors). */
-	onError?: (error: unknown) => void;
+	onError?: (error: unknown) => void | Promise<void>;
 }
 
 export class BackgroundTaskQueue {
 	private concurrency: number;
 	private readonly pending: PendingTask[] = [];
 	private readonly active = new Set<AbortController>();
+	private readonly completions = new WeakMap<AbortController, Promise<void>>();
+	private readonly idleWaiters = new Set<() => void>();
 	private stopped = false;
 
 	constructor(concurrency: number) {
@@ -46,19 +49,55 @@ export class BackgroundTaskQueue {
 		this.drain();
 	}
 
-	enqueue(task: BackgroundTask, onCancelled?: () => void, onError?: (error: unknown) => void): AbortController {
+	enqueue(task: BackgroundTask, onCancelled?: () => void, onError?: (error: unknown) => void | Promise<void>): AbortController {
 		const controller = new AbortController();
+		let complete!: () => void;
+		const completion = new Promise<void>((resolve) => {
+			complete = resolve;
+		});
+		this.completions.set(controller, completion);
 		if (this.stopped) {
 			controller.abort();
 			this.runCancelled(onCancelled);
+			complete();
 			return controller;
 		}
 
-		this.pending.push({ task, controller, onCancelled, onError });
+		this.pending.push({ task, controller, complete, onCancelled, onError });
 		this.drain();
 		return controller;
 	}
 
+	/** Resolve after this exact task has left the pending/active sets. This is
+	 * stronger than waiting for its task body: callers may safely reuse a
+	 * concurrency slot or the task's persisted checkpoint after it resolves. */
+	waitForTask(controller: AbortController | undefined): Promise<void> {
+		if (!controller) return Promise.resolve();
+		return this.completions.get(controller) ?? Promise.resolve();
+	}
+
+	/** Cancel one queued/running task. Queued entries are removed immediately;
+	 * active entries resolve waitForTask only after their body and error handler
+	 * have quiesced and the concurrency slot has been released. */
+	cancel(controller: AbortController | undefined): void {
+		if (!controller) return;
+		controller.abort();
+		const index = this.pending.findIndex((entry) => entry.controller === controller);
+		if (index !== -1) {
+			const [entry] = this.pending.splice(index, 1);
+			this.runCancelled(entry.onCancelled);
+			entry.complete();
+			this.drain();
+			this.resolveIdleWaiters();
+		}
+	}
+
+	/** Resolve once no queued or running task remains. */
+	waitForIdle(): Promise<void> {
+		if (this.pending.length === 0 && this.active.size === 0) return Promise.resolve();
+		return new Promise<void>((resolve) => this.idleWaiters.add(resolve));
+	}
+
 	/** Stop queued work and request cancellation for running work. */
 	cancelAll(): void {
 		if (this.stopped) return;
@@ -67,8 +106,10 @@ export class BackgroundTaskQueue {
 		for (const entry of this.pending.splice(0)) {
 			entry.controller.abort();
 			this.runCancelled(entry.onCancelled);
+			entry.complete();
 		}
 		for (const controller of this.active) controller.abort();
+		this.resolveIdleWaiters();
 	}
 
 	/** Cancellation callbacks are user-supplied: a throw must never break the queue
@@ -85,28 +126,40 @@ export class BackgroundTaskQueue {
 	private drain(): void {
 		while (!this.stopped && this.active.size < this.concurrency) {
 			const entry = this.pending.shift();
-			if (!entry) return;
+			if (!entry) {
+				this.resolveIdleWaiters();
+				return;
+			}
 			if (entry.controller.signal.aborted) {
 				this.runCancelled(entry.onCancelled);
+				entry.complete();
 				continue;
 			}
 
 			this.active.add(entry.controller);
 			void entry.task(entry.controller.signal)
-				.catch((error: unknown) => {
+				.catch(async (error: unknown) => {
 					// Cancellation is not a failure: aborted work (e.g. session
 					// shutdown) must never be reported as an exception.
 					if (entry.controller.signal.aborted) return;
 					try {
-						entry.onError?.(error);
+						await entry.onError?.(error);
 					} catch {
 						/* error reporting must never break the queue */
 					}
 				})
 				.finally(() => {
 					this.active.delete(entry.controller);
+					entry.complete();
 					this.drain();
+					this.resolveIdleWaiters();
 				});
 		}
 	}
+
+	private resolveIdleWaiters(): void {
+		if (this.pending.length > 0 || this.active.size > 0) return;
+		for (const resolve of this.idleWaiters) resolve();
+		this.idleWaiters.clear();
+	}
 }

package/src/config.ts

@@ -25,7 +25,7 @@ export const DEFAULT_ENABLED_AGENTS: readonly string[] = ["explore", "worker", "
 
 /**
  * Agents that used to ship but were removed. normalizeConfig strips them from
- * enabledAgents/agentModels so upgraded installs clean their config automatically
+ * enabledAgents/model mappings so upgraded installs clean their config automatically
  * (the schema-upgrade save in loadConfig then persists the cleanup).
  */
 export const REMOVED_AGENT_NAMES: readonly string[] = ["plan"];
@@ -70,8 +70,10 @@ export const IDLE_TIMEOUT_SEC_LIMIT = 600;
 export interface SubagentsConfig {
 	/** Agent names that are discoverable and injected. Default: explore, worker, reviewer. */
 	enabledAgents: string[];
-	/** Per-agent model override, keyed by agent name, as "provider/model-id". */
+	/** Per-agent primary model override, keyed by agent name, as "provider/model-id". */
 	agentModels: Record<string, string>;
+	/** Optional per-agent backup model, tried after the primary and before the current main-window model. */
+	agentBackupModels: Record<string, string>;
 	/** Per-agent thinking-level override, keyed by agent name. */
 	agentThinkingLevels: Record<string, ThinkingLevel>;
 	/** Thinking level for sub-agents without a per-agent override or frontmatter default. Default: "high". */
@@ -125,6 +127,7 @@ export interface SubagentsConfig {
 export const DEFAULT_CONFIG: SubagentsConfig = {
 	enabledAgents: [...DEFAULT_ENABLED_AGENTS],
 	agentModels: {},
+	agentBackupModels: {},
 	agentThinkingLevels: {},
 	thinkingLevel: DEFAULT_THINKING_LEVEL,
 	notifyOnReviewPass: false,
@@ -172,6 +175,7 @@ export function normalizeConfig(raw: unknown): SubagentsConfig {
 	const config: SubagentsConfig = {
 		enabledAgents: [...DEFAULT_CONFIG.enabledAgents],
 		agentModels: {},
+		agentBackupModels: {},
 		agentThinkingLevels: {},
 		thinkingLevel: DEFAULT_CONFIG.thinkingLevel,
 		notifyOnReviewPass: DEFAULT_CONFIG.notifyOnReviewPass,
@@ -202,6 +206,13 @@ export function normalizeConfig(raw: unknown): SubagentsConfig {
 		}
 	}
 
+	if (isRecord(raw.agentBackupModels)) {
+		for (const [key, value] of Object.entries(raw.agentBackupModels)) {
+			if (REMOVED_AGENT_NAMES.includes(key.trim())) continue;
+			if (isModelReference(value)) config.agentBackupModels[key.trim()] = value.trim();
+		}
+	}
+
 	if (isRecord(raw.agentThinkingLevels)) {
 		for (const [key, value] of Object.entries(raw.agentThinkingLevels)) {
 			if (REMOVED_AGENT_NAMES.includes(key.trim())) continue;
@@ -272,6 +283,7 @@ function defaultConfig(): SubagentsConfig {
 		...DEFAULT_CONFIG,
 		enabledAgents: [...DEFAULT_CONFIG.enabledAgents],
 		agentModels: {},
+		agentBackupModels: {},
 		agentThinkingLevels: {},
 		announcedFeatures: [],
 	};