claude-overnight 1.51.1 → 1.51.3

package/README.md

@@ -1,16 +1,62 @@
 # claude-overnight
 
-Parallel Claude agents in isolated git worktrees. Set a usage cap so your interactive Claude Code keeps its headroom. Rate-limited? It waits. Crash? It resumes with full context.
+Overnight coding swarms in isolated git worktrees that plan, execute, review, and steer themselves until the objective is met. Hand it a goal and a budget, walk away, review the diff in the morning.
 
-Hand it an objective and a session budget, walk away, review the diff when the run ends. Every agent runs in its own worktree on its own branch — a misbehaving agent can't trash your working tree. Unmerged branches are preserved for manual review, never discarded.
+Every agent runs in its own worktree on its own branch, so a misbehaving session cannot trash your working tree. Unmerged branches are preserved for manual review, never discarded. Set a usage cap (say 90%) and your interactive Claude Code still has headroom to answer questions while the swarm runs.
 
-Built on the [Claude Agent SDK](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk) — every session runs on the SDK's agent harness. Three roles, each picked independently: **planner** (thinks, steers, reviews), **main worker** (runs the tasks), and an optional **fast worker** (a cheaper/faster second worker for well-scoped tasks, verified by the next wave's workers). Pair any planner (Opus, Sonnet) with any worker — Anthropic, Cursor, Qwen, OpenRouter, or any Anthropic-compatible endpoint.
+Built on the [Claude Agent SDK](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk): every planner, worker, reviewer, and verifier session runs on the SDK's agent harness with full session resume, streaming, and transcripts. `claude-overnight` is the orchestrator around that harness. It plans, routes, curates, resumes, and persists many SDK sessions at once. Because the harness speaks the Anthropic Messages API, any compatible endpoint plugs in as a role.
+
+## Three execution layers, mix per run
+
+| Layer | Runs on | What it does |
+|---|---|---|
+| Planner (harness) | Opus 4.6, Sonnet 4.6 | Thinking wave, orchestration, steering, post-wave review, final gate |
+| Main worker | Sonnet, Gemini 2.5, Qwen 3.6 Plus, DeepSeek, any Anthropic-compatible endpoint | Bulk implementation |
+| Fast worker (optional) | Kimi 2.6 Coding, Cursor composer-2, Haiku | Cheap well-scoped tasks, double-checked by later waves |
+
+A common recipe: **Opus planner + Sonnet bulk worker + Cursor composer-2 fast worker**. Another: **Opus planner + Kimi 2.6 bulk worker + Haiku fast worker**. Providers are saved once to `~/.claude/claude-overnight/providers.json` and appear in every future run. The bundled `cursor-composer-in-claude` proxy makes Cursor-hosted models (`auto`, `composer`, `composer-2`) look like a normal provider.
+
+## What this recipe does that others do not
+
+**Self-curating skill memory that improves mid-run.** Workers emit memory candidates when they discover something reusable: a repo-specific quirk, a recovery path, a command sequence that worked, a tool recipe worth saving. A scribe appends each candidate to disk without blocking the run. At the end of every wave, a **librarian** pass curates the queue. It promotes candidates into canon, patches existing skills via diff-style edits, or quarantines stale ones. **Wave N+1 of the same run starts with a better skill library than wave N.** Across runs, the library compounds. Inspired by Nous Research's Hermes Agent (Feb 2026), with progressive disclosure (L0 stub in every prompt, L1 body loaded on demand, L2 references on request), SQLite FTS5 retrieval, and per-skill win-rate tracking that auto-quarantines rot.
+
+**Self-fixing, not just self-running.** Every task agent reviews its own `git diff` via SDK session resume (same session, full task context, no re-prompting) and runs a simplify pass before the commit lands. After each wave a dedicated review agent scans the consolidated diff for cross-agent issues the individual sessions could not see: missed reuse, copy-paste variations, leaky abstractions. When steering declares the objective done, a final gate reviews the full `git diff main` for architecture coherence before anything reaches your working tree.
+
+**Multi-wave autonomous loop, not fire-and-forget.** After each wave a steering pass asks "how good is this?" and chooses between executing more tasks, spinning up a deeper reflection wave, or declaring done. The loop keeps going until steering is satisfied, the budget is exhausted, or the usage cap trips. Long runs keep a living status snapshot, archived milestones every five waves, and an evolving goal file, so steering picks up exactly where it left off after a rate limit or an overnight stop.
+
+**Headroom-aware usage cap.** Set the cap to 90% of your 5h window and the swarm stops accepting new work there. Your interactive Claude Code keeps the remaining 10% to answer questions or run its own sessions while the overnight run grinds on.
+
+**Crash-safe by design.** Planner state, the task plan, design docs, per-query NDJSON transcripts, steering decisions, and wave milestones all land on disk as they are produced. If the process dies mid-plan, the next resume salvages `tasks.json` and skips the expensive thinking wave. Planner crashes do not lose the $2 to $4 of orchestration work that already happened.
+
+## Run on Kimi 2.6
+
+Want a cheap Anthropic-compatible worker with a simple shell setup? Kimi 2.6 via Kimi's coding endpoint is a drop-in worker that speaks the Anthropic Messages API, same client, same flow, just a different base URL.
+
+1. **Configure the provider.** Run `claude-overnight`, choose `Other…` on the worker step, and fill in:
+
+   | Field | Value |
+   |---|---|
+   | Name | `Kimi 2.6` |
+   | Base URL | `https://api.kimi.com/coding/` |
+   | Model id | `kimi-for-coding` |
+   | API key | your Kimi coding key |
+
+2. That's it. Planner runs on Sonnet (or Opus), worker runs on Kimi.
+
+Or set it via env directly:
+
+```bash
+export ANTHROPIC_BASE_URL="https://api.kimi.com/coding/"
+export ANTHROPIC_API_KEY="sk-kimi-..."
+export ANTHROPIC_MODEL="kimi-for-coding"
+claude-overnight
+```
 
 ## 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 worker 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 worker 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 worker step, and fill in:
 
    | Field | Value |
@@ -31,9 +77,9 @@ export ANTHROPIC_MODEL="qwen3.6-plus"
 claude-overnight
 ```
 
-## Run via Cursor API Proxy
+## Run via Bundled Cursor Proxy
 
-Use Cursor's model gateway as a worker -- `auto` (delegates to best available), `composer`, or `composer-2` models. Runs locally through a proxy that speaks the Anthropic Messages API, so it's a drop-in replacement for any other provider.
+Use Cursor-hosted models (`auto`, `composer`, `composer-2`, etc.) through the bundled `cursor-composer-in-claude` proxy. `claude-overnight` auto-starts that local Anthropic-compatible proxy, injects the per-worktree workspace header, and treats Cursor as just another provider for the planner, main worker, or fast worker.
 
 ### macOS: Cursor agent shell patch
 
@@ -56,50 +102,44 @@ alias agent="run_cursor_agent"
 
 `claude-overnight` prints a one-time notice when you use the Cursor proxy and this snippet is not detected in `~/.zshrc` or `~/.zprofile`. The bundled proxy also sets `CURSOR_AGENT_NODE` / `CURSOR_AGENT_SCRIPT` when it can find `node` and `cursor-agent`, but your interactive shell still benefits from the alias.
 
-1. **Install the Cursor CLI and proxy:**
+1. **Install the Cursor CLI:**
 
    ```bash
    curl https://cursor.com/install -fsS | bash
-   npm install -g cursor-api-proxy
    ```
 
 2. **Get an API key.** Visit [cursor.com/dashboard/integrations](https://cursor.com/dashboard/integrations) and scroll to the "API Keys" section.
 
-3. **Set up.** Run `claude-overnight` and when prompted to pick a model, choose **Cursor…**. It walks you through a one-time setup: CLI check, API key entry (persisted to `providers.json`), and proxy health check.
+3. **Set up.** Run `claude-overnight` and when prompted to pick a model, choose **Cursor…**. It walks you through a one-time setup: CLI check, API key entry (persisted to `providers.json`), bundled proxy verification, and health check.
 
-4. **Start the proxy** (in a separate terminal):
-
-   ```bash
-   npx cursor-api-proxy
-   ```
-
-5. Pick your model (`auto`, `composer`, `composer-2`, etc.). The provider is saved and reappears in every future run.
+4. Pick your model (`auto`, `composer`, `composer-2`, etc.). The provider is saved and reappears in every future run.
 
 Or configure the key manually:
 
 ```bash
-export CURSOR_BRIDGE_API_KEY="sk-..."
-npx cursor-api-proxy &
+export CURSOR_BRIDGE_API_KEY="crsr_..."
 claude-overnight
 ```
 
-**Tip:** run `claude-overnight` with the `--model=cursor-auto` flag in non-interactive mode to skip the picker. If the proxy isn't running at startup, a warning is shown but Anthropic providers remain available.
+If the bundled proxy cannot auto-start, the setup wizard prints the exact `node ".../cursor-composer-in-claude/dist/cli.js"` command for this install so you can launch the same embedded proxy manually.
+
+**Tip:** once a Cursor provider is saved, run `claude-overnight` with the `--model=cursor-auto` flag in non-interactive mode to skip the picker. If the proxy isn't running at startup, the tool attempts to restart it automatically.
 
 ### macOS: “Keychain Not Found” / `cursor-user`
 
-The Cursor **`agent`** binary stores an interactive login as **`cursor-user`** in your **login** keychain. For automation, use a **[User API key](https://cursor.com/docs/cli/headless)** (`export CURSOR_API_KEY=...` from [Integrations](https://cursor.com/dashboard/integrations)) — the bundled proxy then does not need Keychain. `claude-overnight` forces `CURSOR_SKIP_KEYCHAIN=1` and `CI=true`; if System Settings still shows **“A keychain cannot be found to store …”**, the login keychain is often missing or damaged: open **Keychain Access → First Aid** on **login**, or use **Reset To Defaults** in the dialog. Some users fix a stuck keychain with:
+The Cursor **`agent`** binary stores an interactive login as **`cursor-user`** in your **login** keychain. For automation, use a **[User API key](https://cursor.com/docs/cli/headless)** (`export CURSOR_API_KEY=...` from [Integrations](https://cursor.com/dashboard/integrations)): the bundled proxy then does not need Keychain. `claude-overnight` forces `CURSOR_SKIP_KEYCHAIN=1` and `CI=true`; if System Settings still shows **“A keychain cannot be found to store …”**, the login keychain is often missing or damaged: open **Keychain Access → First Aid** on **login**, or use **Reset To Defaults** in the dialog. Some users fix a stuck keychain with:
 
 ```bash
 security unlock-keychain ~/Library/Keychains/login.keychain-db
 ```
 
-**Automation:** Saving a key via **Cursor…** in `claude-overnight` is enough — it is written to `providers.json` and injected into both the Claude SDK env and the bundled proxy (including `CURSOR_API_KEY` for the native `agent`). You do not need to `export` variables unless you want to override for one shell.
+**Automation:** Saving a key via **Cursor…** in `claude-overnight` is enough. It is written to `providers.json` and injected into both the Claude SDK env and the bundled proxy (including `CURSOR_API_KEY` for the native `agent`). You do not need to `export` variables unless you want to override for one shell.
 
 **Advanced:** If something else must share port `8765` and you manage the proxy yourself, set `CURSOR_OVERNIGHT_NO_PROXY_RESTART=1` to skip the automatic “replace listener” step when a Cursor API token is present.
 
 **How headless Cursor + macOS Keychain actually works (discovery):** We documented the full investigation: why ACP was the wrong path for opus/sonnet `*-thinking-*` variants (model-name mismatch → silent `exit 1`), how **chat-only workspace** (default in cursor-composer) fakes `HOME` and triggers **Keychain timeouts** despite a User API key, and how a cloned **account pool** makes parallel cursor-agent spawns race-free. See **[docs/CURSOR_PROXY_MACOS_DISCOVERY.md](docs/CURSOR_PROXY_MACOS_DISCOVERY.md)**.
 
-**Quick reference — bundled proxy env:** `CURSOR_BRIDGE_USE_ACP=0` (CLI streaming path accepts all friendly model names), `CURSOR_BRIDGE_CHAT_ONLY_WORKSPACE=false`, `CURSOR_CONFIG_DIRS=<5 cloned pool dirs>` (parallel-safe), plus `CURSOR_API_KEY` / `CURSOR_AUTH_TOKEN` / `CURSOR_BRIDGE_API_KEY` and `CURSOR_SKIP_KEYCHAIN=1` / `CI=true`. Details and tables are in the doc above.
+**Quick reference, bundled proxy env:** `CURSOR_BRIDGE_USE_ACP=0` (CLI streaming path accepts all friendly model names), `CURSOR_BRIDGE_CHAT_ONLY_WORKSPACE=false`, `CURSOR_CONFIG_DIRS=<5 cloned pool dirs>` (parallel-safe), plus `CURSOR_API_KEY` / `CURSOR_AUTH_TOKEN` / `CURSOR_BRIDGE_API_KEY` and `CURSOR_SKIP_KEYCHAIN=1` / `CI=true`. Details and tables are in the doc above.
 
 **Regression / stress test:** `npm run matrix:cursor-proxy` (optional `--quick`, `--include-danger`). Use `MATRIX_MODELS=composer-2,claude-opus-4-7-thinking-high` to compare models; override `MATRIX_PORT_BASE`, `MATRIX_MODEL`, `MATRIX_MSG_TIMEOUT_MS` as needed.
 
@@ -109,7 +149,7 @@ security unlock-keychain ~/Library/Keychains/login.keychain-db
 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. For Anthropic-direct roles, use `claude auth login` or `ANTHROPIC_API_KEY`. For provider-backed roles, save a Kimi / Qwen / Cursor / OpenRouter-compatible provider instead. No Anthropic plan or key? See **Run on Kimi 2.6** or **Run on Qwen 3.6 Plus** above for cheap drop-in alternatives.
 
 ## Quick start
 
@@ -126,13 +166,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
 
-⑤ Worker 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
+⑤ Worker model (runs the tasks; Kimi 2.6 / 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:
@@ -159,49 +199,93 @@ 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, curating memory, 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.
 
 ## Use cases
 
 Overnight refactors, batch feature implementation, codebase-wide cleanups, test generation, documentation sprints, framework migrations, quality audits, long research runs. One objective + a budget + walk away.
 
-## How it works
+## Typical flow
 
-### 1. Thinking phase  -- parallel architect sessions
+```
+┌─ Setup + planning ──────────────────────────────────────────────┐
+│  start/resume  →  coach rewrites objective  →  pick planner,    │
+│  worker, fast worker  →  provider preflight  →  theme review    │
+│  →  thinking wave (parallel architects)  →  task orchestration  │
+└──────────────────────┬──────────────────────────────────────────┘
+                       │
+┌─ Wave loop ──────────▼──────────────────────────────────────────┐
+│  beforeWave hook  →  execution wave (workers in worktrees)      │
+│  →  per-agent simplify pass (session resume on same context)    │
+│  →  debrief + afterWave hook  →  post-wave review agent         │
+│  →  librarian curates skill candidates into canon               │
+│  →  steering decides: execute more │ reflect deeper │ done      │
+│         ↑                                                       │
+│         └── loop until done, budget out, or cap hit             │
+│  →  final gate reviews full `git diff main`                     │
+└─────────────────────────────────────────────────────────────────┘
+
+┌─ Skill memory (compounds within a run and across runs) ─────────┐
+│  workers emit candidates  →  scribe writes to disk              │
+│  →  librarian curates at wave end  →  canon markdown +          │
+│  SQLite FTS5 index updated  →  next wave gets an L0 stub,       │
+│  hydrates L1 body on demand, L2 references on request           │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+This is the main user-visible lifecycle. Engine-internal branches (health-check heal tasks, A/B skill assignment across sibling branches, zero-work retry, budget-extension prompts, resume salvage after planning crashes) are omitted for clarity.
+
+### 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. 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.
+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. If a fast worker is configured, steering can route cheaper, well-scoped tasks there while the main worker handles heavier implementation.
 
 ### 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.
+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
+### 5. Librarian and dynamic memory
 
-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.
+During execution, workers can emit **memory candidates** when they discover something reusable: a repo-specific quirk, a recovery path, a command sequence that worked, or a tool recipe worth reusing later. The scribe writes those candidates to `~/.claude-overnight/skills/<repo-fingerprint>/candidates/` without blocking the run.
+
+At the end of each wave, a **librarian** pass curates that queue. It can promote a candidate into canon, patch an existing skill, quarantine stale skills, or reject weak / duplicated candidates. Canon lives on disk as markdown; SQLite is only the ranked index. This is what makes the memory system dynamic rather than a fixed prompt blob.
 
 ### 6. Steering
 
-After each wave, steering assesses: "how good is this?"  -- not "what's missing?" It can:
+After each wave, steering asks "how good is this?" rather than "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
 
-### Three-layer context memory
+### 7. 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.
+
+### Run-memory layers
+
+Long runs stay sharp because steering maintains three run-memory layers:
+
+- **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.
 
-Long runs stay sharp because steering maintains three layers of memory:
+### Progressive-disclosure repo 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.
+The repo memory system is separate from the run folder and is designed around three disclosure layers so context stays small:
+
+- **L0**: a tiny ranked stub injected into planner and worker prompts. It lists only the names and descriptions of the most relevant project-specific skills and tool recipes.
+- **L1**: the full skill body, loaded on demand with `skill_read(name)` when an agent wants the actual recipe or guidance.
+- **L2**: attached references for deeper context. The library is structured for them even though most runs only need the L0 stub plus occasional L1 hydration.
+
+That progressive disclosure matters: the planner and workers do not carry the full memory library in every prompt. They get a compact overview, call `skill_search(query)` if they need to narrow it, and hydrate only the bodies that matter for the task in front of them.
 
 ## Run history, resume, and knowledge carryforward
 
@@ -222,7 +306,7 @@ Every run gets its own folder in `.claude-overnight/runs/`. Nothing is ever over
       run.json, transcripts/themes.ndjson   ← see exactly what the planner was doing
 ```
 
-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
@@ -237,7 +321,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)
@@ -247,25 +331,25 @@ 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.
 
 ### Transcripts and streaming
 
-Every planner/steering query streams through the Agent SDK with `includePartialMessages: true`, so tool calls, thinking, and text deltas are captured as they happen. Each query also appends an NDJSON transcript under `runs/<ts>/transcripts/<name>.ndjson` — so if the planner crashes mid-think you still have the forensic trail (prompt preview, every tool use, every text/thinking delta, rate-limit events, and the final result or error). `themes.md` is also written as a human-readable summary right after the thinking wave.
+Every planner/steering query streams through the Agent SDK with `includePartialMessages: true`, so tool calls, thinking, and text deltas are captured as they happen. Each query also appends an NDJSON transcript under `runs/<ts>/transcripts/<name>.ndjson`, so if the planner crashes mid-think you still have the forensic trail (prompt preview, every tool use, every text/thinking delta, rate-limit events, and the final result or error). `themes.md` is also written as a human-readable summary right after the thinking wave.
 
 Not every provider delivers the same streaming granularity:
 
 | Provider | Tool-use events | Thinking deltas | Text deltas |
 | --- | --- | --- | --- |
 | Anthropic (direct) | ✓ | ✓ | ✓ |
-| Cursor proxy (`cursor-composer-in-claude`) | — | — | ✓ (final answer only) |
-| Qwen / OpenRouter / custom Anthropic-compatible | depends on upstream | depends | usually ✓ |
+| Cursor proxy (`cursor-composer-in-claude`) | no | no | ✓ (final answer only) |
+| Kimi / Qwen / OpenRouter / custom Anthropic-compatible | depends on upstream | depends | usually ✓ |
 
-When a provider doesn't stream partials (or the model is a reasoning model on the Cursor proxy — the proxy suppresses the thinking phase and only emits the final answer), the ticker shows elapsed time with no live text, then the completed result lands in one go. The UI, transcripts, and the resume flow all behave identically either way — streaming is used when available, never required.
+When a provider doesn't stream partials (or the model is a reasoning model on the Cursor proxy, where the proxy suppresses the thinking phase and only emits the final answer), the ticker shows elapsed time with no live text, then the completed result lands in one go. The UI, transcripts, and the resume flow all behave identically either way: streaming is used when available, never required.
 
-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
 
@@ -309,20 +393,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 + worker 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 and worker separately; `Other…` adds Kimi / 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 |
@@ -331,35 +415,42 @@ claude-overnight "fix auth bug in src/auth.ts" "add tests for user model"
 | `mergeStrategy` | `"yolo" \| "branch"` | `"yolo"` | Merge into HEAD or new branch |
 | `usageCap` | `number (0-100)` | unlimited | Stop at N% utilization |
 
-## Custom providers (Qwen, OpenRouter, any Anthropic-compatible endpoint)
+## Custom providers (Kimi, Qwen, OpenRouter, any Anthropic-compatible endpoint)
 
-Planner, main worker, and optional fast worker are each picked separately  -- pair Opus-on-Anthropic for the planner/thinker with a cheaper model on another provider for the bulk of work. The fast worker is a real worker (same tools, same env), just on a cheaper/faster model — steering routes well-scoped tasks to it by default.
+Planner, main worker, and optional fast worker are each picked separately. Pair Opus-on-Anthropic for the planner/thinker with a cheaper model on another provider for the bulk of work. The fast worker is a real worker (same tools, same env), just on a cheaper/faster model, and steering routes well-scoped tasks to it by default.
 
 From the interactive picker, choose `Other…` on the planner, worker, or fast step:
 
 ```
-⑤ Worker model (what runs the tasks  -- Qwen 3.6 Plus / OpenRouter / etc via Other…):
+⑤ Worker model (runs the tasks; Kimi 2.6 / Qwen 3.6 Plus / OpenRouter / etc via Other…):
   ○ Sonnet
   ○ Opus
   ● Other…
 
-  Name: Qwen 3.6 Plus
-  Base URL: https://dashscope-intl.aliyuncs.com/apps/anthropic
-  Model id: qwen3.6-plus
+  Name: Kimi 2.6
+  Base URL: https://api.kimi.com/coding/
+  Model id: kimi-for-coding
   API key source:
     ● Paste key now        · stored plaintext in ~/.claude/claude-overnight/providers.json (0600)
     ○ Read from env var    · nothing written to disk
 ```
 
+Common examples:
+
+| Name | Base URL | Model id |
+|---|---|---|
+| `Kimi 2.6` | `https://api.kimi.com/coding/` | `kimi-for-coding` |
+| `Qwen 3.6 Plus` | `https://dashscope-intl.aliyuncs.com/apps/anthropic` | `qwen3.6-plus` |
+
 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, main-worker queries use the worker provider, fast-worker queries use the fast 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, main-worker queries use the worker provider, fast-worker queries use the fast 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 `✗ worker 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=kimi-for-coding` (or `qwen3.6-plus`) auto-resolves the model id to a saved provider, no separate `--provider` flag.
 
 ## Parallel Playwright Testing
 
@@ -397,8 +488,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
 
@@ -410,11 +501,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).
 
@@ -422,14 +513,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
@@ -443,13 +534,36 @@ Conflicts retry with `-X theirs`. Unresolved branches are preserved for manual m
 
 ## Claude Code plugin
 
-This repo also ships a Claude Code plugin so any Claude instance (inside this repo or any other) knows how to use, inspect, and resume `claude-overnight` runs:
+This repo ships a Claude Code plugin so any Claude instance (inside this repo or any other) knows how to use, inspect, and resume `claude-overnight` runs:
 
 ```
 /plugin marketplace add Fornace/claude-overnight
 /plugin install claude-overnight
 ```
 
+The plugin includes a skill for **authoring runs outside the CLI**. Claude can help you pick the run shape, critique the budget and decomposition, and write a `tasks.json` file before you ever invoke the CLI.
+
+### Writing `tasks.json` externally
+
+When you pass a pre-written `tasks.json` to the CLI, it **skips the thinking wave and planning phase** and starts executing immediately:
+
+```bash
+claude-overnight tasks.json
+```
+
+This is useful when:
+- You already have a concrete task list and don't need the planner to explore the codebase.
+- You want to save the planner cost ($2–4) on a straightforward, mechanical job.
+- You used the Claude skill to design the run and want to lock the plan before executing.
+
+A fixed-plan `tasks.json` (without `flexiblePlan: true`) bypasses orchestration entirely. A flex-plan `tasks.json` (with `objective` + `flexiblePlan: true` + seed tasks) still uses steering across waves, but skips the initial thinking wave if the tasks are already concrete.
+
+### What happens when `tasks.json` exists
+
+- **Crash resilience.** During normal planning, the orchestrator writes `tasks.json` to disk as soon as it generates the tasks. If the planner crashes or the process dies before the run state is persisted, the next resume salvages the tasks from `tasks.json` instead of re-running the expensive planning query.
+- **Resume fallback.** If a run's state file is missing or incomplete, the resume flow falls back to `tasks.json` to reconstruct the task list. This also covers legacy runs from before v1.11.7 where the agent wrote the file but the orchestrator didn't save `run.json`.
+- **Orphan recovery.** The state scanner backfills minimal run metadata for any run directory that contains a `tasks.json` but no `run.json`, so incomplete planning shells still show up in `claude-overnight --list`.
+
 ## Exit codes
 
 | Code | Meaning |

package/dist/cli/help.js

@@ -25,7 +25,7 @@ export function printHelp() {
     --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 + worker separately  -- supports 'Other…' for Qwen / OpenRouter / etc.)")}
+    --model=NAME           Worker model override ${chalk.dim("(interactive mode picks planner + worker separately  -- supports 'Other…' for Kimi / Qwen / OpenRouter / etc.)")}
     --fast-model=NAME      Fast worker model for quick tasks ${chalk.dim("(optional  -- checked by next wave's workers)")}
     --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)")}

package/dist/cli/settings.js

@@ -21,13 +21,13 @@ export async function editRunSettings(options) {
     const plannerPick = await pickModel(`${chalk.cyan("①")} Planner model ${chalk.dim("(thinking, steering  -- use your strongest)")}:`, models, options.defaults?.plannerModel ?? s.plannerModel);
     s.plannerModel = plannerPick.model;
     s.plannerProviderId = plannerPick.providerId;
-    const workerPick = await pickModel(`${chalk.cyan("②")} Worker model ${chalk.dim("(what runs the tasks  -- Qwen 3.6 Plus / OpenRouter / etc via Other…)")}:`, models, options.defaults?.workerModel ?? s.workerModel);
+    const workerPick = await pickModel(`${chalk.cyan("②")} Worker model ${chalk.dim("(what runs the tasks  -- Kimi 2.6 / Qwen 3.6 Plus / OpenRouter / etc via Other…)")}:`, models, options.defaults?.workerModel ?? s.workerModel);
     s.workerModel = workerPick.model;
     s.workerProviderId = workerPick.providerId;
     const suggestFast = !!(options.defaults?.fastModel);
-    const fastChoice = await select(`${chalk.cyan("③")} Fast worker model ${chalk.dim("(optional  -- Haiku/Qwen for well-scoped tasks, checked by next wave's workers)")}:`, [
+    const fastChoice = await select(`${chalk.cyan("③")} Fast worker model ${chalk.dim("(optional  -- Haiku/Kimi/Qwen for well-scoped tasks, checked by next wave's workers)")}:`, [
         { name: "Skip", value: "skip", hint: "single-worker mode (main worker handles everything)" },
-        { name: "Pick a fast worker", value: "pick", hint: "Haiku, Qwen, or any provider  -- a cheaper, faster second worker" },
+        { name: "Pick a fast worker", value: "pick", hint: "Haiku, Kimi, Qwen, or any provider  -- a cheaper, faster second worker" },
     ], suggestFast ? 1 : 0);
     if (fastChoice === "pick") {
         const fastPick = await pickModel(`${chalk.cyan("③b")} Fast worker model:`, models, options.defaults?.fastModel ?? s.fastModel);

package/dist/core/_version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "1.51.1";
+export declare const VERSION = "1.51.3";

package/dist/core/_version.js

@@ -1,2 +1,2 @@
 // Auto-generated by build — do not edit manually.
-export const VERSION = "1.51.1";
+export const VERSION = "1.51.3";

package/dist/prompt-evolution/adapters/mcp-browser.d.ts

@@ -0,0 +1,70 @@
+/**
+ * MCP-browser prompt adapter.
+ *
+ * MCP-browser stores prompts as inline template literals in
+ * platform/supervisor/gemini-client.ts. This adapter:
+ * 1. Extracts those prompt strings by parsing the TS file
+ * 2. Defines benchmark cases for each prompt type
+ * 3. Provides repo contexts for planning/refinement evaluation
+ *
+ * The prompts are evaluated by sending them to a model (via OpenRouter
+ * or any Anthropic-compatible proxy) and scoring the structured output.
+ */
+import type { BenchmarkCase } from "../types.js";
+/** Prompt kinds we can benchmark */
+export type McpPromptKind = "planning" | "review" | "evolution" | "goal-refinement" | "plan-supervision" | "simple-supervision" | "stuck-analysis";
+/** Extract a const prompt string from gemini-client.ts by name */
+export declare function extractPrompt(kind: McpPromptKind): string;
+/** Build a synthetic user prompt for a given kind and scenario */
+export declare function buildUserPrompt(kind: McpPromptKind, scenario: McpScenario): string;
+export interface McpScenario {
+    name: string;
+    repoContext?: RepoContext;
+    stepContext?: StepContext;
+    terminalContext?: TerminalContext;
+    reviewContext?: ReviewContext;
+    evolutionContext?: EvolutionContext;
+    goalContext?: GoalContext;
+}
+export interface RepoContext {
+    goal: string;
+    fileTree: string;
+    readmeSnippet: string;
+    hasCiCd: boolean;
+}
+export interface StepContext {
+    stepTitle: string;
+    stepDescription: string;
+    acceptanceCriteria: string[];
+    phaseTitle: string;
+    progress: string;
+}
+export interface TerminalContext {
+    state: "idle" | "error" | "context_limit" | "completed" | "working";
+    recentOutput: string;
+    projectGoal: string;
+}
+export interface ReviewContext {
+    stepTitle: string;
+    stepDescription: string;
+    acceptanceCriteria: string[];
+    terminalOutput: string;
+}
+export interface EvolutionContext {
+    completedPlanSummary: string;
+    reviewNotes: string;
+    evolutionNumber: number;
+}
+export interface GoalContext {
+    originalTitle: string;
+    originalDescription: string;
+    gitHistory: string;
+    fileTree: string;
+}
+export declare const PLANNING_SCENARIOS: McpScenario[];
+export declare const REVIEW_SCENARIOS: McpScenario[];
+export declare const SUPERVISION_SCENARIOS: McpScenario[];
+export declare const STUCK_SCENARIOS: McpScenario[];
+/** Convert scenarios to benchmark cases for a given prompt kind */
+export declare function scenariosToCases(kind: McpPromptKind, scenarios: McpScenario[]): BenchmarkCase[];
+export declare function hydrateCases(cases: BenchmarkCase[]): BenchmarkCase[];