claude-overnight 1.16.16 → 1.17.0

package/QUICKSHEET_PLAYWRIGHT.md

@@ -62,4 +62,4 @@ npx ctx7@latest library playwright "parallel browser instances isolation"
 npx ctx7@latest docs <libraryId> "parallel browser instances"
 ```
 
-**Note:** ctx7 requires authentication (`npx ctx7@latest login` or `CONTEXT7_API_KEY` env var). If unauthenticated, lookups will fail — agents should fall back to training data.
+**Note:** ctx7 requires authentication (`npx ctx7@latest login` or `CONTEXT7_API_KEY` env var). If unauthenticated, lookups will fail  -- agents should fall back to training data.

package/README.md

@@ -1,18 +1,18 @@
 # claude-overnight
 
-**A background lane for your Claude Max plan.** Runs a capped swarm of Claude Agent SDK sessions in isolated git worktrees — stops at a usage cap you set, so your interactive Claude Code always has headroom. Rate-limited? It waits. Crash? It resumes with full context.
+**A background lane for your Claude Max plan.** Runs a capped swarm of Claude Agent SDK sessions in isolated git worktrees  -- stops at a usage cap you set, so your interactive Claude Code always has headroom. Rate-limited? It waits. Crash? It resumes with full context.
 
 Your Max plan rate limits eat interactive coding time. One deep refactor and the 5-hour window is gone before lunch. `claude-overnight` runs background agent sessions up to the percentage cap you pick (90% is typical), leaving the rest free for your own Claude Code session. Hand it an objective and a session budget, walk away, review the diff when the run ends.
 
-Isolated by default. Every agent runs in its own git worktree on its own branch, so a misbehaving agent can't trash your working tree. You choose what agents can do before the run starts — no surprise escalation mid-flight. Unmerged branches are preserved for manual review, never discarded. Built on the [Claude Agent SDK](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk) — not a Claude Code replacement, but a background lane that runs alongside it.
+Isolated by default. Every agent runs in its own git worktree on its own branch, so a misbehaving agent can't trash your working tree. You choose what agents can do before the run starts  -- no surprise escalation mid-flight. Unmerged branches are preserved for manual review, never discarded. Built on the [Claude Agent SDK](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk)  -- not a Claude Code replacement, but a background lane that runs alongside it.
 
-Different shape from hosted agent harnesses like [Claude Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview): instead of one agent in one cloud container billed separately, you get many parallel sessions on your own machine, in your real repo, against your own Max plan (or API key). Works with Claude Opus, Sonnet, and Haiku — or pair an Anthropic planner with a cheaper executor on Qwen, OpenRouter, or any Anthropic-compatible endpoint.
+Different shape from hosted agent harnesses like [Claude Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview): instead of one agent in one cloud container billed separately, you get many parallel sessions on your own machine, in your real repo, against your own Max plan (or API key). Works with Claude Opus, Sonnet, and Haiku  -- or pair an Anthropic planner with a cheaper executor on Qwen, OpenRouter, or any Anthropic-compatible endpoint.
 
 ## Run on Qwen 3.6 Plus
 
-Hit your Claude Max plan limits? Running on a tight budget? Qwen 3.6 Plus via Alibaba Cloud's DashScope gateway is a drop-in executor that speaks the Anthropic Messages API — same client, same flow, pennies per run.
+Hit your Claude Max plan limits? Running on a tight budget? Qwen 3.6 Plus via Alibaba Cloud's DashScope gateway is a drop-in executor that speaks the Anthropic Messages API  -- same client, same flow, pennies per run.
 
-1. **Get an API key.** Sign up at [Alibaba Cloud](https://account.alibabacloud.com/login/login.htm?oauth_callback=https%3A%2F%2Fmodelstudio.console.alibabacloud.com%2Fap-southeast-1%3Ftab%3Ddashboard%23%2Fapi-key&clearRedirectCookie=1) — the link takes you straight to the API key dashboard.
+1. **Get an API key.** Sign up at [Alibaba Cloud](https://account.alibabacloud.com/login/login.htm?oauth_callback=https%3A%2F%2Fmodelstudio.console.alibabacloud.com%2Fap-southeast-1%3Ftab%3Ddashboard%23%2Fapi-key&clearRedirectCookie=1)  -- the link takes you straight to the API key dashboard.
 2. **Configure the provider.** Run `claude-overnight`, choose `Other…` on the executor step, and fill in:
 
    | Field | Value |
@@ -39,7 +39,7 @@ claude-overnight
 npm install -g claude-overnight
 ```
 
-Requires Node.js ≥ 20 and Claude authentication (`claude auth login` or `ANTHROPIC_API_KEY`). No Anthropic plan or key? See **Run on Qwen 3.6 Plus** above — a cheap, drop-in alternative.
+Requires Node.js ≥ 20 and Claude authentication (`claude auth login` or `ANTHROPIC_API_KEY`). No Anthropic plan or key? See **Run on Qwen 3.6 Plus** above  -- a cheap, drop-in alternative.
 
 ## Quick start
 
@@ -56,13 +56,13 @@ claude-overnight
 
 ② Budget [10]: 200
 
-④ Planner model (thinking, steering — use your strongest):
-  ● Opus — Opus 4.6 · Most capable
-  ○ Sonnet — Sonnet 4.6 · Best for everyday tasks
+④ Planner model (thinking, steering  -- use your strongest):
+  ● Opus  -- Opus 4.6 · Most capable
+  ○ Sonnet  -- Sonnet 4.6 · Best for everyday tasks
 
-⑤ Executor model (what runs the tasks — Qwen 3.6 Plus / OpenRouter / etc via Other…):
-  ● Sonnet — Sonnet 4.6 · Best for everyday tasks
-  ○ Opus — Opus 4.6 · Most capable
+⑤ Executor model (what runs the tasks  -- Qwen 3.6 Plus / OpenRouter / etc via Other…):
+  ● Sonnet  -- Sonnet 4.6 · Best for everyday tasks
+  ○ Opus  -- Opus 4.6 · Most capable
   ○ Other… · custom OpenAI/Anthropic-compatible endpoint
 
 ⑥ Usage cap:
@@ -89,58 +89,64 @@ claude-overnight
 ◆ Assessing... ✓ Done
 ```
 
-You interact once (objective, budget, model, review themes), then the rest runs unattended — thinking, planning, executing, reflecting, steering. Rate-limited? It waits and retries. Crash? Resume where you left off. Capped at usage limit? Pick up next time with full context preserved.
+You interact once (objective, budget, model, review themes), then the rest runs unattended  -- thinking, planning, executing, reflecting, steering. Rate-limited? It waits and retries. Crash? Resume where you left off. Capped at usage limit? Pick up next time with full context preserved.
 
 ## How it differs
 
 - vs **Claude Code**: many agents, no driver, capped so your Claude Code session keeps its headroom
-- vs **[Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview)**: on your machine, against your Max plan, in your real git history — not a cloud container billed separately
+- vs **[Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview)**: on your machine, against your Max plan, in your real git history  -- not a cloud container billed separately
 - vs **Cursor / Copilot / Cline**: asynchronous, off the keyboard
 
 ## Use cases
 
-- **Overnight refactors** — "Modernize the auth system" at budget 200.
-- **Batch feature implementation** — dozens of features from a task file, parallelized.
-- **Codebase-wide cleanups** — deduplicate, simplify, rename, normalize.
-- **Test generation at scale** — integration tests for every route or module.
-- **Documentation sprints** — API docs, READMEs, inline comments, changelogs.
-- **Framework migrations** — version upgrades, type annotations, config format swaps.
-- **Quality audits** — reflection waves surface architectural issues and code smells.
-- **Long research runs** — architect sessions explore a large codebase before any code lands.
+- **Overnight refactors**  -- "Modernize the auth system" at budget 200.
+- **Batch feature implementation**  -- dozens of features from a task file, parallelized.
+- **Codebase-wide cleanups**  -- deduplicate, simplify, rename, normalize.
+- **Test generation at scale**  -- integration tests for every route or module.
+- **Documentation sprints**  -- API docs, READMEs, inline comments, changelogs.
+- **Framework migrations**  -- version upgrades, type annotations, config format swaps.
+- **Quality audits**  -- reflection waves surface architectural issues and code smells.
+- **Long research runs**  -- architect sessions explore a large codebase before any code lands.
 
 Typical shape: one objective + a $20–$200 spend cap + walk away.
 
 ## How it works
 
-### 1. Thinking phase — parallel architect sessions
+### 1. Thinking phase  -- parallel architect sessions
 
 For budgets > 15, the tool launches **architect agents** that explore your codebase before any code is written. Each one gets a different research angle (architecture, data models, APIs, testing, etc.) and writes a structured design document. The number scales with budget: 5 for budget=50, 10 for budget=2000.
 
 ### 2. Task orchestration
 
-An orchestrator session reads all design documents and synthesizes concrete execution tasks — grounded in real files and patterns the architects found. The task plan is also written to a file for resilience — if orchestration is interrupted, partial results survive.
+An orchestrator session reads all design documents and synthesizes concrete execution tasks  -- grounded in real files and patterns the architects found. The task plan is also written to a file for resilience  -- if orchestration is interrupted, partial results survive.
 
 ### 3. Parallel execution waves
 
-Tasks run in parallel agent sessions (each in its own git worktree). After completing its task, each session automatically runs a **simplify pass** — reviewing its own `git diff` for code reuse opportunities, quality issues, and inefficiencies, then fixing them before the framework commits.
+Tasks run in parallel agent sessions (each in its own git worktree). After completing its task, each session automatically runs a **simplify pass**  -- reviewing its own `git diff` for code reuse opportunities, quality issues, and inefficiencies, then fixing them before the framework commits. This is done via the SDK's **session resume** mechanism: the same agent session continues with a follow-up prompt, so the agent's full context from its task is still available  -- no need to re-instruct or re-fill context.
 
-After each wave, steering assesses: "how good is this?" — not "what's missing?" It can:
+### 4. Post-wave review
+
+After each wave (flex mode, budget remaining), a dedicated **review agent** inspects the consolidated diff for issues the individual agents may have blind-spotted: missed reuse opportunities, copy-paste variations, leaky abstractions, efficiency regressions. Runs as a single-agent wave  -- one session reviews what the swarm just produced.
+
+### 5. Post-run final gate
+
+When the run completes (steering declares done), a final **comprehensive review** runs against the full `git diff main`. Checks architecture coherence, consistency with existing patterns, build integrity, and test pass. The last quality gate before the diff lands.
+
+### 6. Steering
+
+After each wave, steering assesses: "how good is this?"  -- not "what's missing?" It can:
 
 - **Execute** more tasks to build features, fix bugs, polish UX
 - **Reflect** by spinning up 1-2 review sessions for deep quality/architecture audits
 - **Declare done** when the vision is met at high quality
 
-### 4. Goal refinement and steering
-
-The tool starts with your broad objective but refines its definition of quality as it learns your codebase. Steering updates the goal after each wave. Late waves are informed by early discoveries.
-
-### 5. Three-layer context memory
+### Three-layer context memory
 
 Long runs stay sharp because steering maintains three layers of memory:
 
-- **Status** — a living project snapshot, updated every wave. Compressed, never truncated.
-- **Milestones** — strategic snapshots archived every ~5 waves. Long-term memory.
-- **Goal** — the evolving north star. What quality means for this codebase.
+- **Status**  -- a living project snapshot, updated every wave. Compressed, never truncated.
+- **Milestones**  -- strategic snapshots archived every ~5 waves. Long-term memory.
+- **Goal**  -- the evolving north star. What quality means for this codebase.
 
 ## Run history, resume, and knowledge carryforward
 
@@ -155,7 +161,7 @@ Every run gets its own folder in `.claude-overnight/runs/`. Nothing is ever over
       run.json, sessions/
 ```
 
-Any run that stops before the steering system declares the objective complete — capped at usage limit, Ctrl+C, crash, rate limit timeout, steering failure — is automatically resumable:
+Any run that stops before the steering system declares the objective complete  -- capped at usage limit, Ctrl+C, crash, rate limit timeout, steering failure  -- is automatically resumable:
 
 ```
   ⚠ Unfinished run
@@ -170,7 +176,7 @@ Any run that stops before the steering system declares the objective complete
 
 On resume: unmerged branches auto-merge, the wave loop continues, all context is preserved. Designs and reflections stay on disk until the objective is truly complete.
 
-If the thinking phase succeeds but orchestration crashes, the next run detects the orphaned design docs and reuses them — no re-running $9 worth of architect sessions:
+If the thinking phase succeeds but orchestration crashes, the next run detects the orphaned design docs and reuses them  -- no re-running $9 worth of architect sessions:
 
 ```
   ✓ Reusing 5 design docs (from prior attempt)
@@ -180,11 +186,11 @@ If the thinking phase succeeds but orchestration crashes, the next run detects t
     ...
 ```
 
-**Knowledge carries forward** — new runs inherit knowledge from completed previous runs. Thinking sessions and steering see what past runs built. Run 2 knows run 1 already built the auth system.
+**Knowledge carries forward**  -- new runs inherit knowledge from completed previous runs. Thinking sessions and steering see what past runs built. Run 2 knows run 1 already built the auth system.
 
-Add `.claude-overnight/` to your `.gitignore` (with the trailing slash — see below).
+Add `.claude-overnight/` to your `.gitignore` (with the trailing slash  -- see below).
 
-A separate, tiny `claude-overnight.log.md` is also written at the repo root on every run. It's human-readable, append-only, one block per run (objective, start/finish, cost, outcome, branch), and is designed to be **committed** — so even after `.claude-overnight/` is cleaned up you can still recover which prompt produced which commits. Use `.claude-overnight/` (with trailing slash) in your gitignore so this file isn't matched by accident.
+A separate, tiny `claude-overnight.log.md` is also written at the repo root on every run. It's human-readable, append-only, one block per run (objective, start/finish, cost, outcome, branch), and is designed to be **committed**  -- so even after `.claude-overnight/` is cleaned up you can still recover which prompt produced which commits. Use `.claude-overnight/` (with trailing slash) in your gitignore so this file isn't matched by accident.
 
 ## Task file and inline modes
 
@@ -228,20 +234,20 @@ claude-overnight "fix auth bug in src/auth.ts" "add tests for user model"
 |---|---|---|
 | `--budget=N` | `10` | Total agent sessions |
 | `--concurrency=N` | `5` | Parallel agents |
-| `--model=NAME` | prompted | Worker model — interactive picks planner + executor separately; `Other…` adds Qwen / OpenRouter / any Anthropic-compat endpoint. In non-interactive mode, a saved provider's model id is auto-resolved to the provider. |
+| `--model=NAME` | prompted | Worker model  -- interactive picks planner + executor separately; `Other…` adds Qwen / OpenRouter / any Anthropic-compat endpoint. In non-interactive mode, a saved provider's model id is auto-resolved to the provider. |
 | `--usage-cap=N` | unlimited | Stop at N% utilization |
 | `--allow-extra-usage` | off | Allow extra/overage usage (billed separately) |
-| `--extra-usage-budget=N` | — | Max $ for extra usage (implies --allow-extra-usage) |
+| `--extra-usage-budget=N` |  -- | Max $ for extra usage (implies --allow-extra-usage) |
 | `--timeout=SECONDS` | `900` | Inactivity timeout per agent (nudges at timeout, kills at 2×) |
-| `--no-flex` | — | Disable multi-wave steering |
-| `--dry-run` | — | Show planned tasks without running |
+| `--no-flex` |  -- | Disable multi-wave steering |
+| `--dry-run` |  -- | Show planned tasks without running |
 
 ## Task file fields
 
 | Field | Type | Default | Description |
 |---|---|---|---|
 | `tasks` | `(string \| {prompt, cwd?, model?})[]` | required | Tasks to run |
-| `objective` | `string` | — | High-level goal for steering |
+| `objective` | `string` |  -- | High-level goal for steering |
 | `flexiblePlan` | `boolean` | `false` | Enable multi-wave planning |
 | `model` | `string` | prompted | Worker model |
 | `concurrency` | `number` | `5` | Parallel agents |
@@ -252,12 +258,12 @@ claude-overnight "fix auth bug in src/auth.ts" "add tests for user model"
 
 ## Custom providers (Qwen, OpenRouter, any Anthropic-compatible endpoint)
 
-Planner and executor are picked separately — pair Opus-on-Anthropic for the planner/thinker with a cheaper model on another provider for the bulk of execution.
+Planner and executor are picked separately  -- pair Opus-on-Anthropic for the planner/thinker with a cheaper model on another provider for the bulk of execution.
 
 From the interactive picker, choose `Other…` on the planner or executor step:
 
 ```
-⑤ Executor model (what runs the tasks — Qwen 3.6 Plus / OpenRouter / etc via Other…):
+⑤ Executor model (what runs the tasks  -- Qwen 3.6 Plus / OpenRouter / etc via Other…):
   ○ Sonnet
   ○ Opus
   ● Other…
@@ -272,13 +278,13 @@ From the interactive picker, choose `Other…` on the planner or executor step:
 
 Saved providers live user-level at `~/.claude/claude-overnight/providers.json` (mode 0600) and show up automatically in every repo. No per-project config.
 
-**How routing works.** Each `query()` gets its own env override (`ANTHROPIC_BASE_URL` + `ANTHROPIC_AUTH_TOKEN`) — planner queries use the planner provider, executor queries use the executor provider. No global shell env, no proxy daemon, no `process.env` pollution between calls.
+**How routing works.** Each `query()` gets its own env override (`ANTHROPIC_BASE_URL` + `ANTHROPIC_AUTH_TOKEN`)  -- planner queries use the planner provider, executor queries use the executor provider. No global shell env, no proxy daemon, no `process.env` pollution between calls.
 
 **Pre-flight.** Before the swarm starts, each custom provider is pinged with a 1-turn auth check. Bad keys fail fast with `✗ executor preflight failed: ...` instead of N scattered mid-run errors.
 
 **Resume.** Provider ids are persisted in `run.json` and rehydrated on resume. If you deleted a provider between runs, resume refuses to start and tells you exactly which id is missing.
 
-**Non-interactive / CI.** `claude-overnight --model=qwen3.6-plus` auto-resolves the model id to a saved provider — no separate `--provider` flag.
+**Non-interactive / CI.** `claude-overnight --model=qwen3.6-plus` auto-resolves the model id to a saved provider  -- no separate `--provider` flag.
 
 ## Parallel Playwright Testing
 
@@ -316,8 +322,8 @@ See `QUICKSHEET_PLAYWRIGHT.md` for full config examples.
 
 By default, extra/overage usage is **blocked**. When your plan's rate limits are exhausted, the run stops cleanly and is resumable. You control this in the interactive prompt (step ⑤) or via CLI flags:
 
-- `--allow-extra-usage` — opt in to extra usage (billed separately)
-- `--extra-usage-budget=20` — allow up to $20 of extra usage, then stop
+- `--allow-extra-usage`  -- opt in to extra usage (billed separately)
+- `--extra-usage-budget=20`  -- allow up to $20 of extra usage, then stop
 
 ### Live controls during execution
 
@@ -329,11 +335,11 @@ Press these keys while agents are running:
 | `t` | Change usage cap threshold (0-100%) |
 | `q` | Graceful stop (press twice to force quit) |
 
-Changes take effect between waves — active agents finish their current task.
+Changes take effect between waves  -- active agents finish their current task.
 
 ### Multi-window usage display
 
-The usage bar cycles through all rate limit windows (5h, 7d, etc.) every 3 seconds, showing utilization per window. Usage info is shown during all phases — thinking, orchestration, steering, and execution.
+The usage bar cycles through all rate limit windows (5h, 7d, etc.) every 3 seconds, showing utilization per window. Usage info is shown during all phases  -- thinking, orchestration, steering, and execution.
 
 When using extra usage with a budget, a dedicated progress bar shows spend vs limit with color-coded fill (magenta → yellow → red).
 
@@ -341,14 +347,14 @@ When using extra usage with a budget, a dedicated progress bar shows spend vs li
 
 Built for unattended runs lasting hours or days.
 
-- **Smooth overage transition**: when extra usage is allowed, plan limit rejection is seamless — no dispatch blocking, agents continue into overage
-- **Interrupt + resume**: agents and planner queries that go silent are interrupted and resumed with full conversation context via SDK session resume — not killed and restarted from scratch
+- **Smooth overage transition**: when extra usage is allowed, plan limit rejection is seamless  -- no dispatch blocking, agents continue into overage
+- **Interrupt + resume**: agents and planner queries that go silent are interrupted and resumed with full conversation context via SDK session resume  -- not killed and restarted from scratch
 - **Hard block**: pauses until the rate limit window resets, then resumes
 - **Soft throttle**: slows dispatch at >75% utilization
 - **Extra usage guard**: detects overage billing and stops unless explicitly allowed
 - **Cooldown between phases**: waits for rate limit reset after thinking before starting orchestration
 - **Retry with backoff**: transient errors (429, overloaded) retry automatically
-- **Usage cap**: set a ceiling, active agents finish, no new ones start — run is resumable
+- **Usage cap**: set a ceiling, active agents finish, no new ones start  -- run is resumable
 - **Planner retries**: steering and orchestration retry on rate limits (30s/60s/120s backoff) with full context
 
 ## Git worktrees and branch merging

package/dist/bin.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 // Tiny launcher: prints a splash the instant node is ready, then dynamically
 // imports the real entrypoint. Loading `@anthropic-ai/claude-agent-sdk` and the
-// rest of the module graph takes several seconds on a cold cache — without
+// rest of the module graph takes several seconds on a cold cache  -- without
 // this, the terminal sits black that whole time. index.ts stops the splash
 // via `globalThis.__coStopSplash` as soon as its header is about to print.
 const argv = process.argv.slice(2);

package/dist/cli.d.ts

@@ -30,7 +30,7 @@ export declare function appendPasteToSegments(segs: InputSegment[], text: string
 export declare function backspaceSegments(segs: InputSegment[]): void;
 /**
  * Read a line from the user with bracketed-paste awareness.
- * Pasted multi-line text stays in the buffer as a single block — only a typed
+ * Pasted multi-line text stays in the buffer as a single block  -- only a typed
  * Enter submits. Falls back to cooked readline when stdin isn't a TTY.
  */
 export declare function ask(question: string): Promise<string>;

package/dist/cli.js

@@ -58,11 +58,11 @@ export async function fetchModels(timeoutMs = 10_000) {
             // Silent: callers fall back to a text prompt with the current value as default.
         }
         else if (isAuthError(err)) {
-            console.error(chalk.red("\n  Authentication failed — check your API key or run: claude auth\n"));
+            console.error(chalk.red("\n  Authentication failed  -- check your API key or run: claude auth\n"));
             process.exit(1);
         }
         else {
-            console.warn(chalk.yellow(`\n  Could not fetch models: ${String(err.message || err).slice(0, 80)} — continuing with defaults`));
+            console.warn(chalk.yellow(`\n  Could not fetch models: ${String(err.message || err).slice(0, 80)}  -- continuing with defaults`));
         }
         return [];
     }
@@ -72,7 +72,7 @@ export async function fetchModels(timeoutMs = 10_000) {
 // When the terminal is in bracketed paste mode, pasted content is wrapped with
 // \x1B[200~ ... \x1B[201~ so we can distinguish typed Enter from pasted newlines.
 // Multi-line or long pastes are stored as opaque segments and shown as a compact
-// [Pasted +N lines] placeholder while editing — the full text is substituted on submit.
+// [Pasted +N lines] placeholder while editing  -- the full text is substituted on submit.
 export const PASTE_START = "\x1B[200~";
 export const PASTE_END = "\x1B[201~";
 export const PASTE_PLACEHOLDER_MAX = 80;
@@ -150,7 +150,7 @@ function stripAnsi(s) {
 // ── Interactive primitives ──
 /**
  * Read a line from the user with bracketed-paste awareness.
- * Pasted multi-line text stays in the buffer as a single block — only a typed
+ * Pasted multi-line text stays in the buffer as a single block  -- only a typed
  * Enter submits. Falls back to cooked readline when stdin isn't a TTY.
  */
 export function ask(question) {

package/dist/index.js

@@ -169,7 +169,7 @@ async function main() {
     }
     if (argv.includes("-h") || argv.includes("--help")) {
         console.log(`
-  ${chalk.bold("🌙  claude-overnight")} ${chalk.dim("v" + VERSION + " — background lane for your Claude Max plan")}
+  ${chalk.bold("🌙  claude-overnight")} ${chalk.dim("v" + VERSION + "  -- background lane for your Claude Max plan")}
   ${chalk.dim("─".repeat(60))}
 
   ${chalk.cyan("Usage")}
@@ -183,7 +183,8 @@ async function main() {
     --dry-run              Show planned tasks without running them
     --budget=N             Target number of agent runs ${chalk.dim("(default: 10)")}
     --concurrency=N        Max parallel agents ${chalk.dim("(default: 5)")}
-    --model=NAME           Worker model override ${chalk.dim("(interactive mode picks planner + executor separately — supports 'Other…' for Qwen / OpenRouter / etc.)")}
+    --model=NAME           Worker model override ${chalk.dim("(interactive mode picks planner + executor separately  -- supports 'Other…' for Qwen / OpenRouter / etc.)")}
+    --fast-model=NAME      Fast model for quick tasks ${chalk.dim("(optional  -- checked by worker model in next wave)")}
     --usage-cap=N          Stop at N% utilization ${chalk.dim("(e.g. 90 to save 10% for other work)")}
     --allow-extra-usage    Allow extra/overage usage ${chalk.dim("(default: stop when plan limits hit)")}
     --extra-usage-budget=N Max $ for extra usage ${chalk.dim("(implies --allow-extra-usage)")}
@@ -259,7 +260,7 @@ async function main() {
         process.exit(1);
     }
     if (noTTY)
-        console.log(chalk.dim("  Non-interactive mode — using defaults\n"));
+        console.log(chalk.dim("  Non-interactive mode  -- using defaults\n"));
     // ── Run history ──
     const rootDir = join(cwd, ".claude-overnight");
     const runsDir = join(rootDir, "runs");
@@ -406,7 +407,7 @@ async function main() {
             // Covers two cases:
             //   1. Planning-phase resumes (the prior run died before executeRun).
             //   2. Stopped/capped runs whose state was saved with currentTasks: []
-            //      (saveRunState always stores [] — the plan is on disk in tasks.json).
+            //      (saveRunState always stores []  -- the plan is on disk in tasks.json).
             if (resumeState.currentTasks.length === 0) {
                 const loaded = salvageFromFile(join(resumeRunDir, "tasks.json"), resumeState.budget, () => { }, "resume");
                 if (loaded) {
@@ -415,12 +416,12 @@ async function main() {
                     console.log(chalk.green(`\n  ✓ ${label} · ${loaded.length} tasks loaded from tasks.json`));
                 }
                 else if (resumeState.phase === "planning") {
-                    // No tasks.json — the thinking wave got killed before orchestrate ran.
+                    // No tasks.json  -- the thinking wave got killed before orchestrate ran.
                     // If design docs survived, re-orchestrate from them (salvages the
                     // thinking spend instead of throwing it away).
                     const designs = readMdDir(join(resumeRunDir, "designs"));
                     if (!designs || !resumeState.objective) {
-                        console.error(chalk.red(`\n  Planning-phase run has no usable tasks.json or designs — start Fresh instead.\n`));
+                        console.error(chalk.red(`\n  Planning-phase run has no usable tasks.json or designs  -- start Fresh instead.\n`));
                         process.exit(1);
                     }
                     const remainingBudget = Math.max(resumeState.concurrency, resumeState.budget - resumeState.accCompleted);
@@ -456,8 +457,10 @@ async function main() {
     // ── Config resolution ──
     let workerModel;
     let plannerModel;
+    let fastModel;
     let workerProvider;
     let plannerProvider;
+    let fastProvider;
     let budget;
     let concurrency;
     let objective = fileCfg?.objective;
@@ -470,23 +473,22 @@ async function main() {
     if (resuming) {
         workerModel = resumeState.workerModel;
         plannerModel = resumeState.plannerModel;
+        fastModel = resumeState.fastModel;
         const saved = loadProviders();
-        if (resumeState.workerProviderId) {
-            workerProvider = saved.find(p => p.id === resumeState.workerProviderId);
-            if (!workerProvider) {
-                console.error(chalk.red(`\n  Resume aborted: worker provider "${resumeState.workerProviderId}" is no longer in ~/.claude/claude-overnight/providers.json`));
+        const resolveProvider = (providerId, role) => {
+            if (!providerId)
+                return undefined;
+            const p = saved.find(s => s.id === providerId);
+            if (!p) {
+                console.error(chalk.red(`\n  Resume aborted: ${role} provider "${providerId}" is no longer in ~/.claude/claude-overnight/providers.json`));
                 console.error(chalk.dim(`  Re-add it via a fresh run's "Other…" flow, or start Fresh instead.\n`));
                 process.exit(1);
             }
-        }
-        if (resumeState.plannerProviderId) {
-            plannerProvider = saved.find(p => p.id === resumeState.plannerProviderId);
-            if (!plannerProvider) {
-                console.error(chalk.red(`\n  Resume aborted: planner provider "${resumeState.plannerProviderId}" is no longer in ~/.claude/claude-overnight/providers.json`));
-                console.error(chalk.dim(`  Re-add it via a fresh run's "Other…" flow, or start Fresh instead.\n`));
-                process.exit(1);
-            }
-        }
+            return p;
+        };
+        workerProvider = resolveProvider(resumeState.workerProviderId, "worker");
+        plannerProvider = resolveProvider(resumeState.plannerProviderId, "planner");
+        fastProvider = resolveProvider(resumeState.fastProviderId, "fast");
         budget = resumeState.budget;
         concurrency = resumeState.concurrency;
         objective = resumeState.objective;
@@ -538,12 +540,22 @@ async function main() {
             clearInterval(modelSpinner);
             process.stdout.write(`\x1B[2K\r`);
         }
-        const plannerPick = await pickModel(`${chalk.cyan("④")} Planner model ${chalk.dim("(thinking, steering — use your strongest)")}:`, models);
+        const plannerPick = await pickModel(`${chalk.cyan("④")} Planner model ${chalk.dim("(thinking, steering  -- use your strongest)")}:`, models);
         plannerModel = plannerPick.model;
         plannerProvider = plannerPick.provider;
-        const workerPick = await pickModel(`${chalk.cyan("⑤")} Executor model ${chalk.dim("(what runs the tasks — Qwen 3.6 Plus / OpenRouter / etc via Other…)")}:`, models);
+        const workerPick = await pickModel(`${chalk.cyan("⑤")} Executor model ${chalk.dim("(what runs the tasks  -- Qwen 3.6 Plus / OpenRouter / etc via Other…)")}:`, models);
         workerModel = workerPick.model;
         workerProvider = workerPick.provider;
+        // ⑤b Optional fast model for quick tasks that will be verified
+        const fastChoice = await select(`${chalk.cyan("⑤b")} Fast model ${chalk.dim("(optional  -- Haiku/Qwen for quick tasks, checked by worker)")}:`, [
+            { name: "Skip", value: "skip", hint: "two-tier mode only (current setup)" },
+            { name: "Pick a fast model", value: "pick", hint: "Haiku, Qwen, or any provider  -- for well-scoped tasks" },
+        ]);
+        if (fastChoice === "pick") {
+            const fastPick = await pickModel(`${chalk.cyan("⑤c")} Fast model:`, models);
+            fastModel = fastPick.model;
+            fastProvider = fastPick.provider;
+        }
         usageCap = await select(`${chalk.cyan("⑥")} Usage cap:`, [
             { name: "Unlimited", value: undefined, hint: "full capacity, wait through rate limits" },
             { name: "90%", value: 0.9, hint: "leave 10% for other work" },
@@ -603,7 +615,9 @@ async function main() {
             mergeStrategy = "yolo";
         }
         const parts = [];
-        if (workerModel !== plannerModel)
+        if (fastModel)
+            parts.push(`${detectModelTier(plannerModel)} → ${detectModelTier(workerModel)} + ${detectModelTier(fastModel)}`);
+        else if (workerModel !== plannerModel)
             parts.push(`${detectModelTier(workerModel)} → ${detectModelTier(plannerModel)}`);
         else
             parts.push(detectModelTier(workerModel));
@@ -631,16 +645,35 @@ async function main() {
         let models = [];
         if (!cliFlags.model && !fileCfg?.model)
             models = await fetchModels(5_000);
-        workerModel = cliFlags.model ?? fileCfg?.model ?? (models[0]?.value || "claude-sonnet-4-6");
-        plannerModel = models[0]?.value || workerModel;
+        // Multi-provider default resolution: match current ANTHROPIC_BASE_URL against
+        // saved providers first, then fetched models, then other providers, then hardcoded
+        // Anthropic default. Adding a new provider to providers.json automatically affects
+        // the default without code changes.
+        const activeBaseURL = process.env.ANTHROPIC_BASE_URL;
+        const savedForCLI = loadProviders();
+        const activeProvider = activeBaseURL ? savedForCLI.find(p => p.baseURL === activeBaseURL) : undefined;
+        const defaultModel = activeProvider?.model
+            ?? models[0]?.value
+            ?? savedForCLI.find(p => p !== activeProvider)?.model
+            ?? "claude-sonnet-4-6";
+        workerModel = cliFlags.model ?? fileCfg?.model ?? defaultModel;
+        plannerModel = activeProvider?.model ?? models[0]?.value ?? workerModel;
         // Auto-resolve a saved custom provider if --model matches its id or model id.
         // Lets `claude-overnight --model=qwen3-coder-plus` route correctly without a separate flag.
-        const savedForCli = loadProviders();
-        const matched = savedForCli.find(p => p.id === workerModel || p.model === workerModel);
+        const matched = savedForCLI.find(p => p.id === workerModel || p.model === workerModel);
         if (matched) {
             workerProvider = matched;
             workerModel = matched.model;
         }
+        // Fast model: --fast-model flag
+        if (cliFlags["fast-model"]) {
+            fastModel = cliFlags["fast-model"];
+            const matchedFast = savedForCLI.find(p => p.id === fastModel || p.model === fastModel);
+            if (matchedFast) {
+                fastProvider = matchedFast;
+                fastModel = matchedFast.model;
+            }
+        }
         concurrency = cliFlags.concurrency ? parseInt(cliFlags.concurrency) : (fileCfg?.concurrency ?? 5);
         budget = cliFlags.budget ? parseInt(cliFlags.budget) : undefined;
         if (budget != null && (isNaN(budget) || budget < 1)) {
@@ -693,27 +726,35 @@ async function main() {
     }
     if (useWorktrees)
         validateGitRepo(cwd);
-    // Custom-provider routing: build a model→env resolver so planner and worker
-    // queries hit the right endpoint without touching process.env globally.
-    const envForModel = buildEnvResolver({ plannerModel, plannerProvider, workerModel, workerProvider });
+    // Custom-provider routing: build a model→env resolver so planner, worker,
+    // and fast queries hit the right endpoint without touching process.env globally.
+    const envForModel = buildEnvResolver({ plannerModel, plannerProvider, workerModel, workerProvider, fastModel, fastProvider });
     setPlannerEnvResolver(envForModel);
-    // Fail fast if a custom provider is misconfigured — one bad key would
+    // Fail fast if a custom provider is misconfigured  -- one bad key would
     // otherwise surface as N agent failures scattered across the run.
-    if (plannerProvider || workerProvider) {
+    if (plannerProvider || workerProvider || fastProvider) {
+        const seen = new Set();
+        const all = [
+            ["planner", plannerProvider],
+            ["executor", workerProvider],
+            ["fast", fastProvider],
+        ];
         const pending = [];
-        if (plannerProvider)
-            pending.push(["planner", plannerProvider]);
-        if (workerProvider && workerProvider.id !== plannerProvider?.id)
-            pending.push(["executor", workerProvider]);
-        for (const [role, p] of pending) {
-            process.stdout.write(`  ${chalk.dim(`◆ Pinging ${role} (${p.displayName})...`)}`);
-            const r = await preflightProvider(p, cwd);
-            if (!r.ok) {
-                process.stdout.write(`\x1B[2K\r  ${chalk.red(`✗ ${role} preflight failed:`)} ${chalk.dim(r.error)}\n`);
+        for (const [role, p] of all) {
+            if (p && !seen.has(p.id)) {
+                seen.add(p.id);
+                pending.push([role, p]);
+            }
+        }
+        process.stdout.write(`  ${chalk.dim(`◆ Pinging ${pending.map(([r, p]) => `${r} (${p.displayName})`).join(", ")}...`)}\n`);
+        const results = await Promise.all(pending.map(async ([role, p]) => ({ role, provider: p, result: await preflightProvider(p, cwd) })));
+        for (const { role, provider, result } of results) {
+            if (!result.ok) {
+                console.error(chalk.red(`  ✗ ${role} preflight failed: ${chalk.dim(result.error)}`));
                 console.error(chalk.red(`\n  Fix the provider at ~/.claude/claude-overnight/providers.json and retry.\n`));
                 process.exit(1);
             }
-            process.stdout.write(`\x1B[2K\r  ${chalk.green(`✓ ${role} ready`)} ${chalk.dim(`· ${p.displayName} · ${p.model}`)}\n`);
+            console.log(`  ${chalk.green(`✓ ${role} ready`)} ${chalk.dim(`· ${provider.displayName} · ${provider.model}`)}`);
         }
     }
     if (nonInteractive) {
@@ -736,7 +777,7 @@ async function main() {
     // Persist an early planning-phase state so the run is visible to the resume
     // picker even if orchestrate dies before executeRun gets a chance to run.
     // Without this, a crashed plan phase leaves no run.json and the run vanishes
-    // from findIncompleteRuns — you pay for orchestration and can't see it.
+    // from findIncompleteRuns  -- you pay for orchestration and can't see it.
     if (needsPlan && objective) {
         try {
             saveRunState(runDir, {
@@ -906,7 +947,7 @@ async function main() {
                     process.stdout.write(`\x1B[2K\r  ${chalk.green(`✓ ${tasks.length} tasks`)}\n\n`);
                 }
                 else {
-                    console.log(chalk.yellow(`\n  No design docs — falling back to direct planning\n`));
+                    console.log(chalk.yellow(`\n  No design docs  -- falling back to direct planning\n`));
                     const waveBudget = Math.min(50, Math.max(concurrency, Math.ceil(((budget ?? 10) - thinkingUsed) * 0.5)));
                     tasks = await planTasks(objective, cwd, plannerModel, workerModel, permissionMode, waveBudget, concurrency, makeProgressLog(), undefined, taskFile);
                     process.stdout.write(`\x1B[2K\r  ${chalk.green(`✓ ${tasks.length} tasks`)}\n\n`);
@@ -977,7 +1018,7 @@ async function main() {
         catch (err) {
             planRestore();
             if (isAuthError(err))
-                console.error(chalk.red(`\n  Authentication failed — check your API key or run: claude auth\n`));
+                console.error(chalk.red(`\n  Authentication failed  -- check your API key or run: claude auth\n`));
             else
                 console.error(chalk.red(`\n  Planning failed: ${err.message}\n`));
             process.exit(1);
@@ -994,8 +1035,8 @@ async function main() {
     }
     // ── Execute ──
     await executeRun({
-        tasks, objective, budget: budget ?? tasks.length, workerModel, plannerModel,
-        workerProvider, plannerProvider, concurrency,
+        tasks, objective, budget: budget ?? tasks.length, workerModel, plannerModel, fastModel,
+        workerProvider, plannerProvider, fastProvider, concurrency,
         permissionMode, useWorktrees, mergeStrategy, usageCap, allowExtraUsage, extraUsageBudget,
         flex, agentTimeoutMs, cwd, allowedTools, runDir, previousKnowledge,
         resuming, resumeState: resumeState ?? undefined,

package/dist/merge.d.ts

@@ -22,7 +22,7 @@ export declare function mergeAllBranches(agents: {
  * 3-way merge. Walks `git diff --name-status base..branch` and for each entry
  * either checks out the branch's version (add/modify/rename) or removes the
  * file (delete). Always succeeds unless the branch itself is broken. Trades
- * merge-graph fidelity for "your changes actually land" — the right call for
+ * merge-graph fidelity for "your changes actually land"  -- the right call for
  * an autonomous swarm.
  */
 export declare function forceMergeOverlay(branch: string, cwd: string): boolean;