claude-overnight 1.0.1 → 1.2.0

package/README.md

@@ -33,12 +33,15 @@ claude-overnight
   ● Sonnet — Sonnet 4.6 · Best for everyday tasks
   ○ Opus — Opus 4.6 · Most capable
 
-④ Usage:
+④ Usage cap:
   ● 90% · leave 10% for other work
 
-╭──────────────────────────────────────────╮
-│  sonnet · budget 200 · 5× · flex · 90%  │
-╰──────────────────────────────────────────╯
+⑤ Allow extra usage (billed separately):
+  ● No · stop when plan limits are reached
+
+╭──────────────────────────────────────────────────╮
+│  sonnet · budget 200 · 5× · flex · cap 90% · no extra  │
+╰──────────────────────────────────────────────────╯
 
 ✓ 5 themes → review, press Run, walk away
 
@@ -52,7 +55,7 @@ claude-overnight
 ◆ Assessing... ✓ Vision met
 ```
 
-You interact once (objective, budget, model, review themes), then everything runs autonomously — thinking, planning, executing, reflecting, steering. Rate-limited? It waits and retries. Crash? Resume where you left off.
+You interact once (objective, budget, model, review themes), then everything runs autonomously — 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 works
 
@@ -62,7 +65,7 @@ For budgets > 15, the tool launches **architect agents** that explore your codeb
 
 ### 2. Orchestration
 
-An orchestrator agent reads all design documents and synthesizes concrete execution tasks — grounded in real files and patterns the architects found. No guesswork.
+An orchestrator agent reads all design documents and synthesizes concrete execution tasks — grounded in real files and patterns the architects found. No guesswork. The task plan is also written to a file for resilience — if orchestration is interrupted, partial results survive.
 
 ### 3. Iterative execution
 
@@ -97,20 +100,30 @@ Every run gets its own folder in `.claude-overnight/runs/`. Nothing is ever over
       run.json, sessions/
 ```
 
-If a run crashes, gets rate-limited, or you Ctrl+C:
+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:
 
 ```
-  ⚠ Interrupted run
+  ⚠ Unfinished run
   ╭──────────────────────────────────────────────────╮
   │  refactor auth, add tests, update docs           │
-  │  50/200 sessions · 3 waves · $69.16              │
+  │  50/200 sessions · 150 remaining · $69.16        │
   │  34 merged · 16 unmerged · 0 failed branches     │
   ╰──────────────────────────────────────────────────╯
 
   Resume  │  Fresh  │  Quit
 ```
 
-On resume: unmerged branches auto-merge, the wave loop continues, all context is preserved.
+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 agents:
+
+```
+  ✓ Reusing 5 design docs (from prior attempt)
+    Focus 0: Project Wizard UI vs VISION.md Flow
+    Focus 1: Team Load and Rebalancer Surface
+    Focus 2: Code Health After Swarm Wave
+    ...
+```
 
 **Knowledge carries forward** — new runs inherit knowledge from completed previous runs. Thinking agents and steering see what past runs built. Run 2 knows run 1 already built the auth system.
 
@@ -162,6 +175,8 @@ claude-overnight "fix auth bug in src/auth.ts" "add tests for user model"
 | `--concurrency=N` | `5` | Parallel agents |
 | `--model=NAME` | prompted | Worker model (planner uses best available) |
 | `--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) |
 | `--timeout=SECONDS` | `300` | Inactivity timeout per agent |
 | `--no-flex` | — | Disable multi-wave steering |
 | `--dry-run` | — | Show planned tasks without running |
@@ -180,15 +195,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 |
 
+## Usage controls
+
+### Extra usage protection
+
+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
+
+### Live controls during execution
+
+Press these keys while agents are running:
+
+| Key | Action |
+|---|---|
+| `b` | Change remaining budget (number of sessions) |
+| `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.
+
+### 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.
+
 ## Rate limits
 
 Built for unattended runs lasting hours or days.
 
 - **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
-- **Planner retries**: steering and orchestration also retry on rate limits (30s/60s/120s backoff)
+- **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
 
 ## Worktrees and merging
 

package/dist/index.js

@@ -11,8 +11,8 @@ import { planTasks, refinePlan, detectModelTier, steerWave, identifyThemes, buil
 import { startRenderLoop, renderSummary } from "./ui.js";
 // ── CLI flag parsing ──
 function parseCliFlags(argv) {
-    const known = new Set(["concurrency", "model", "timeout", "budget", "usage-cap"]);
-    const booleans = new Set(["--dry-run", "-h", "--help", "-v", "--version", "--no-flex"]);
+    const known = new Set(["concurrency", "model", "timeout", "budget", "usage-cap", "extra-usage-budget"]);
+    const booleans = new Set(["--dry-run", "-h", "--help", "-v", "--version", "--no-flex", "--allow-extra-usage"]);
     const flags = {};
     const positional = [];
     for (let i = 0; i < argv.length; i++) {
@@ -523,6 +523,8 @@ async function main() {
     --concurrency=N        Max parallel agents ${chalk.dim("(default: 5)")}
     --model=NAME           Worker model override ${chalk.dim("(planner always uses best available)")}
     --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)")}
     --timeout=SECONDS      Agent inactivity timeout ${chalk.dim("(default: 300s, kills only silent agents)")}
     --no-flex              Disable adaptive multi-wave planning ${chalk.dim("(run all tasks in one shot)")}
 
@@ -606,9 +608,18 @@ async function main() {
         console.log(chalk.dim(`\n  ${completedRuns.length} previous run${completedRuns.length > 1 ? "s" : ""}`));
         for (const r of completedRuns.slice(0, 3)) {
             const date = r.state.startedAt?.slice(0, 10) || "unknown";
-            const obj = r.state.objective?.slice(0, 40) || "";
+            const obj = r.state.objective?.slice(0, 50) || "";
             const cost = r.state.accCost > 0 ? ` · $${r.state.accCost.toFixed(0)}` : "";
-            console.log(chalk.dim(`     ${date} · ${r.state.accCompleted} tasks${cost}${obj ? ` · ${obj}` : ""}${obj.length >= 40 ? "…" : ""}`));
+            const merged = r.state.branches.filter(b => b.status === "merged").length;
+            console.log(chalk.dim(`     ${date} · ${r.state.accCompleted} done · ${merged} merged${cost}${obj ? ` · ${obj}` : ""}${obj.length >= 50 ? "…" : ""}`));
+            // Show status if available
+            let status = "";
+            try {
+                status = readFileSync(join(r.dir, "status.md"), "utf-8").trim().split("\n")[0].slice(0, 80);
+            }
+            catch { }
+            if (status)
+                console.log(chalk.dim(`       ${status}`));
         }
     }
     // ── Resume detection ──
@@ -628,10 +639,11 @@ async function main() {
             lastStatus = readFileSync(join(incomplete.dir, "status.md"), "utf-8").trim().slice(0, 120);
         }
         catch { }
-        console.log(chalk.yellow(`\n  ⚠ Interrupted run`));
+        const label = "Unfinished run";
+        console.log(chalk.yellow(`\n  ⚠ ${label}`));
         const boxLines = [
             `${obj}${obj.length >= 50 ? "…" : ""}`,
-            `${prev.accCompleted}/${prev.budget} sessions · ${prev.waveNum + 1} waves · $${prev.accCost.toFixed(2)}`,
+            `${prev.accCompleted}/${prev.budget} sessions · ${prev.remaining} remaining · $${prev.accCost.toFixed(2)}`,
         ];
         if (lastStatus)
             boxLines.push(lastStatus);
@@ -667,6 +679,8 @@ async function main() {
     let concurrency;
     let objective = fileCfg?.objective;
     let usageCap;
+    let allowExtraUsage = false;
+    let extraUsageBudget;
     if (!nonInteractive) {
         // ① Objective
         while (true) {
@@ -714,13 +728,29 @@ async function main() {
             const ans = await ask(`  ${chalk.cyan("③")} ${chalk.dim("Worker model [claude-sonnet-4-6]:")} `);
             workerModel = ans || "claude-sonnet-4-6";
         }
-        // ④ Usage
-        usageCap = await select(`${chalk.cyan("④")} Usage:`, [
+        // ④ Usage cap
+        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" },
             { name: "75%", value: 0.75, hint: "conservative, plenty of headroom" },
             { name: "50%", value: 0.5, hint: "use half, keep the rest" },
         ]);
+        // ⑤ Extra usage
+        const extraChoice = await select(`${chalk.cyan("⑤")} Allow extra usage ${chalk.dim("(billed separately)")}:`, [
+            { name: "No", value: "no", hint: "stop when plan limits are reached" },
+            { name: "Yes, with $ limit", value: "budget", hint: "set a spending cap" },
+            { name: "Yes, unlimited", value: "unlimited", hint: "keep going no matter what" },
+        ]);
+        if (extraChoice === "budget") {
+            const budgetAns = await ask(`  ${chalk.dim("Max extra usage $:")} `);
+            extraUsageBudget = parseFloat(budgetAns);
+            if (!extraUsageBudget || extraUsageBudget <= 0)
+                extraUsageBudget = 5;
+            allowExtraUsage = true;
+        }
+        else if (extraChoice === "unlimited") {
+            allowExtraUsage = true;
+        }
         concurrency = Math.min(5, budget);
         // Config summary box
         const parts = [];
@@ -737,6 +767,10 @@ async function main() {
             parts.push("flex");
         if (usageCap != null)
             parts.push(`cap ${Math.round(usageCap * 100)}%`);
+        if (allowExtraUsage)
+            parts.push(extraUsageBudget ? `extra $${extraUsageBudget}` : "extra ∞");
+        else
+            parts.push("no extra");
         if (completedRuns.length > 0)
             parts.push(`${completedRuns.length} prior`);
         const inner = parts.join(chalk.dim(" · "));
@@ -770,6 +804,17 @@ async function main() {
         else {
             usageCap = fileCfg?.usageCap != null ? fileCfg.usageCap / 100 : undefined;
         }
+        // Extra usage: default OFF for non-interactive
+        allowExtraUsage = argv.includes("--allow-extra-usage");
+        const extraBudgetFlag = cliFlags["extra-usage-budget"];
+        if (extraBudgetFlag != null) {
+            extraUsageBudget = parseFloat(extraBudgetFlag);
+            if (isNaN(extraUsageBudget) || extraUsageBudget <= 0) {
+                console.error(chalk.red(`  --extra-usage-budget must be a positive number`));
+                process.exit(1);
+            }
+            allowExtraUsage = true;
+        }
     }
     validateConcurrency(concurrency);
     const permissionMode = fileCfg?.permissionMode ?? "auto";
@@ -779,7 +824,8 @@ async function main() {
     const mergeStrategy = fileCfg?.mergeStrategy ?? "yolo";
     if (nonInteractive) {
         const capStr = usageCap != null ? `  cap=${Math.round(usageCap * 100)}%` : "";
-        console.log(chalk.dim(`  ${workerModel}  concurrency=${concurrency}  worktrees=${useWorktrees}  merge=${mergeStrategy}  perms=${permissionMode}${capStr}`));
+        const extraStr = allowExtraUsage ? (extraUsageBudget ? `  extra=$${extraUsageBudget}` : "  extra=∞") : "  extra=off";
+        console.log(chalk.dim(`  ${workerModel}  concurrency=${concurrency}  worktrees=${useWorktrees}  merge=${mergeStrategy}  perms=${permissionMode}${capStr}${extraStr}`));
     }
     // ── Flex mode: adaptive multi-wave planning ──
     let flex = !argv.includes("--no-flex") && (fileCfg?.flexiblePlan ?? objective != null) && objective != null && (budget ?? 10) > 2;
@@ -862,7 +908,17 @@ async function main() {
                 mkdirSync(designDir, { recursive: true });
                 const existingDesigns = readMdDir(designDir);
                 if (existingDesigns) {
-                    console.log(chalk.green(`\n  ✓ Reusing ${readdirSync(designDir).filter(f => f.endsWith(".md")).length} existing design docs`) + chalk.dim(` (from prior attempt)\n`));
+                    const designFiles = readdirSync(designDir).filter(f => f.endsWith(".md")).sort();
+                    console.log(chalk.green(`\n  ✓ Reusing ${designFiles.length} design docs`) + chalk.dim(` (from prior attempt)`));
+                    for (const f of designFiles) {
+                        try {
+                            const firstLine = readFileSync(join(designDir, f), "utf-8").split("\n")[0].replace(/^#+\s*/, "").trim();
+                            if (firstLine)
+                                console.log(chalk.dim(`    ${firstLine.slice(0, 80)}`));
+                        }
+                        catch { }
+                    }
+                    console.log("");
                 }
                 else {
                     const thinkingTasks = buildThinkingTasks(objective, themes, designDir, plannerModel, previousKnowledge || undefined);
@@ -874,9 +930,9 @@ async function main() {
                         useWorktrees: false,
                         mergeStrategy: "yolo",
                         agentTimeoutMs,
-                        usageCap,
+                        usageCap, allowExtraUsage, extraUsageBudget,
                     });
-                    const stopThinkRender = startRenderLoop(thinkingSwarm);
+                    const stopThinkRender = startRenderLoop(thinkingSwarm, { remaining: 0, usageCap, dirty: false });
                     try {
                         await thinkingSwarm.run();
                     }
@@ -1026,11 +1082,12 @@ async function main() {
     let currentSwarm;
     let remaining;
     let currentTasks;
+    const liveConfig = { remaining: 0, usageCap, dirty: false };
     let waveNum;
     const waveHistory = [];
     let accCost, accCompleted, accFailed, accTools;
     let accIn = 0, accOut = 0;
-    let lastCapped = false, lastAborted = false;
+    let lastCapped = false, lastAborted = false, objectiveComplete = false;
     let lastWaveKind;
     let reflectionBudgetUsed;
     const branches = [];
@@ -1053,6 +1110,8 @@ async function main() {
         concurrency = resumeState.concurrency;
         flex = resumeState.flex;
         usageCap = resumeState.usageCap;
+        allowExtraUsage = resumeState.allowExtraUsage ?? false;
+        extraUsageBudget = resumeState.extraUsageBudget;
         console.log(chalk.green(`\n  ✓ Resumed`) + chalk.dim(` · wave ${waveNum + 1} · ${remaining} remaining · $${accCost.toFixed(2)} spent\n`));
     }
     else {
@@ -1074,6 +1133,8 @@ async function main() {
         lastWaveKind = "execute";
         reflectionBudgetUsed = 0;
     }
+    liveConfig.remaining = remaining;
+    liveConfig.usageCap = usageCap;
     const maxReflectionBudget = Math.max(2, Math.ceil((budget ?? 10) * 0.05));
     // For flex + branch strategy: create one target branch, waves merge via yolo into it
     let runBranch;
@@ -1111,14 +1172,15 @@ async function main() {
         if (currentTasks.length > remaining)
             currentTasks = currentTasks.slice(0, remaining);
         if (flex) {
-            console.log(chalk.cyan(`\n  ◆ Wave ${waveNum + 1}`) + chalk.dim(` · ${currentTasks.length} tasks · ${remaining} remaining\n`));
+            const costSoFar = accCost > 0 ? ` · $${accCost.toFixed(2)} spent` : "";
+            console.log(chalk.cyan(`\n  ◆ Wave ${waveNum + 1}`) + chalk.dim(` · ${currentTasks.length} tasks · ${remaining} remaining${costSoFar}\n`));
         }
         const swarm = new Swarm({
             tasks: currentTasks, concurrency, cwd, model: workerModel, permissionMode, allowedTools,
-            useWorktrees, mergeStrategy: waveMerge, agentTimeoutMs, usageCap,
+            useWorktrees, mergeStrategy: waveMerge, agentTimeoutMs, usageCap, allowExtraUsage, extraUsageBudget,
         });
         currentSwarm = swarm;
-        const stopRender = startRenderLoop(swarm);
+        const stopRender = startRenderLoop(swarm, liveConfig);
         try {
             await swarm.run();
         }
@@ -1143,6 +1205,13 @@ async function main() {
         accFailed += swarm.failed;
         accTools += swarm.agents.reduce((sum, a) => sum + a.toolCalls, 0);
         remaining -= swarm.completed + swarm.failed;
+        // Apply live config changes if user adjusted budget/threshold mid-wave
+        if (liveConfig.dirty) {
+            remaining = liveConfig.remaining;
+            usageCap = liveConfig.usageCap;
+            liveConfig.dirty = false;
+        }
+        liveConfig.remaining = remaining;
         lastCapped = swarm.cappedOut;
         lastAborted = swarm.aborted;
         recordBranches(swarm, branches);
@@ -1150,7 +1219,7 @@ async function main() {
         saveRunState(runDir, {
             id: `run-${new Date().toISOString().slice(0, 19)}`, objective: objective, budget: budget ?? tasks.length,
             remaining, workerModel, plannerModel, concurrency, permissionMode,
-            usageCap, flex, useWorktrees, mergeStrategy, waveNum, currentTasks,
+            usageCap, allowExtraUsage, extraUsageBudget, flex, useWorktrees, mergeStrategy, waveNum, currentTasks,
             lastWaveKind, reflectionBudgetUsed, accCost, accCompleted, accFailed,
             branches, phase: "steering", startedAt: new Date(runStartedAt).toISOString(), cwd,
         });
@@ -1193,6 +1262,7 @@ async function main() {
                 if (steer.done || steer.action === "done") {
                     console.log(chalk.green(`  \u2713 ${steer.reasoning}\n`));
                     steerDone = true;
+                    objectiveComplete = true;
                     remaining = 0; // exit outer loop too
                     break;
                 }
@@ -1215,10 +1285,10 @@ async function main() {
                         tasks: reflTasks, concurrency: 2, cwd,
                         model: plannerModel, permissionMode,
                         useWorktrees: false, mergeStrategy: "yolo",
-                        agentTimeoutMs, usageCap,
+                        agentTimeoutMs, usageCap, allowExtraUsage, extraUsageBudget,
                     });
                     currentSwarm = reflSwarm;
-                    const stopReflRender = startRenderLoop(reflSwarm);
+                    const stopReflRender = startRenderLoop(reflSwarm, liveConfig);
                     try {
                         await reflSwarm.run();
                     }
@@ -1245,6 +1315,7 @@ async function main() {
                 // action === "execute"
                 if (steer.tasks.length === 0) {
                     console.log(chalk.green(`  \u2713 ${steer.reasoning}\n`));
+                    objectiveComplete = true;
                     remaining = 0;
                     break;
                 }
@@ -1262,22 +1333,26 @@ async function main() {
         }
         waveNum++;
     }
-    // Mark run as done — keep sessions/milestones/status/goal, clean transient files
+    // Only truly "done" if steering explicitly completed the objective (or non-flex single wave with budget exhausted)
+    const trulyDone = objectiveComplete || (!flex && remaining <= 0);
+    const finalPhase = trulyDone ? "done" : "capped";
     saveRunState(runDir, {
         id: `run-${new Date().toISOString().slice(0, 19)}`, objective: objective ?? "", budget: budget ?? tasks.length,
         remaining, workerModel, plannerModel, concurrency, permissionMode,
-        usageCap, flex, useWorktrees, mergeStrategy, waveNum, currentTasks: [],
+        usageCap, allowExtraUsage, extraUsageBudget, flex, useWorktrees, mergeStrategy, waveNum, currentTasks: [],
         lastWaveKind, reflectionBudgetUsed, accCost, accCompleted, accFailed,
-        branches, phase: "done", startedAt: new Date(runStartedAt).toISOString(), cwd,
+        branches, phase: finalPhase, startedAt: new Date(runStartedAt).toISOString(), cwd,
     });
-    try {
-        rmSync(join(runDir, "designs"), { recursive: true, force: true });
-    }
-    catch { }
-    try {
-        rmSync(join(runDir, "reflections"), { recursive: true, force: true });
+    if (trulyDone) {
+        try {
+            rmSync(join(runDir, "designs"), { recursive: true, force: true });
+        }
+        catch { }
+        try {
+            rmSync(join(runDir, "reflections"), { recursive: true, force: true });
+        }
+        catch { }
     }
-    catch { }
     // Switch back if we created a run branch
     if (runBranch && originalRef) {
         try {

package/dist/planner.d.ts

@@ -1,4 +1,13 @@
-import type { Task, PermMode } from "./types.js";
+import type { Task, PermMode, RateLimitWindow } from "./types.js";
+/** Rate limit info emitted by planner queries for UI display. */
+export interface PlannerRateLimitInfo {
+    utilization: number;
+    status: string;
+    isUsingOverage: boolean;
+    windows: Map<string, RateLimitWindow>;
+    resetsAt?: number;
+    costUsd: number;
+}
 export interface WaveSummary {
     wave: number;
     kind: "execute" | "reflect" | "think";
@@ -27,6 +36,7 @@ export interface RunMemory {
 }
 export type ModelTier = "opus" | "sonnet" | "haiku" | "unknown";
 export declare function detectModelTier(model: string): ModelTier;
+export declare function getPlannerRateLimitInfo(): PlannerRateLimitInfo;
 export declare function planTasks(objective: string, cwd: string, plannerModel: string, workerModel: string, permissionMode: PermMode, budget: number | undefined, concurrency: number, onLog: (text: string) => void, flexNote?: string, outFile?: string): Promise<Task[]>;
 export declare function identifyThemes(objective: string, count: number, model: string, permissionMode: PermMode): Promise<string[]>;
 export declare function buildThinkingTasks(objective: string, themes: string[], designDir: string, plannerModel: string, previousKnowledge?: string): Task[];

package/dist/planner.js

@@ -172,7 +172,13 @@ async function runPlannerQuery(prompt, opts, onLog) {
     }
     throw new Error("Planner query failed after retries");
 }
+/** Shared mutable rate limit state that planner queries write to for UI display. Reset per query. */
+let _plannerRateLimitInfo = {
+    utilization: 0, status: "", isUsingOverage: false, windows: new Map(), costUsd: 0,
+};
+export function getPlannerRateLimitInfo() { return _plannerRateLimitInfo; }
 async function runPlannerQueryOnce(prompt, opts, onLog) {
+    _plannerRateLimitInfo = { utilization: 0, status: "", isUsingOverage: false, windows: new Map(), costUsd: 0 };
     let resultText = "";
     const startedAt = Date.now();
     const pq = query({
@@ -191,14 +197,18 @@ async function runPlannerQueryOnce(prompt, opts, onLog) {
     // Progress ticker — fast updates with compact format
     let lastLogText = "";
     let toolCount = 0;
+    let costUsd = 0;
     const ticker = setInterval(() => {
         const elapsed = Math.round((Date.now() - startedAt) / 1000);
         const m = Math.floor(elapsed / 60);
         const s = elapsed % 60;
         const timeStr = m > 0 ? `${m}m ${s}s` : `${s}s`;
         const toolStr = toolCount > 0 ? ` · ${toolCount} tools` : "";
+        const costStr = costUsd > 0 ? ` · $${costUsd.toFixed(3)}` : "";
+        const rlPct = _plannerRateLimitInfo.utilization;
+        const rlStr = rlPct > 0 ? ` · ${Math.round(rlPct * 100)}%` : "";
         const extra = lastLogText ? ` · ${lastLogText}` : "";
-        onLog(`${timeStr}${toolStr}${extra}`);
+        onLog(`${timeStr}${toolStr}${costStr}${rlStr}${extra}`);
     }, 500);
     let lastActivity = Date.now();
     let timer;
@@ -235,11 +245,35 @@ async function runPlannerQueryOnce(prompt, opts, onLog) {
                     }
                 }
             }
+            if (msg.type === "rate_limit_event") {
+                const info = msg.rate_limit_info;
+                if (info) {
+                    _plannerRateLimitInfo.utilization = info.utilization ?? 0;
+                    _plannerRateLimitInfo.status = info.status ?? "";
+                    if (info.isUsingOverage)
+                        _plannerRateLimitInfo.isUsingOverage = true;
+                    if (info.resetsAt)
+                        _plannerRateLimitInfo.resetsAt = info.resetsAt;
+                    if (info.rateLimitType) {
+                        _plannerRateLimitInfo.windows.set(info.rateLimitType, {
+                            type: info.rateLimitType,
+                            utilization: info.utilization ?? 0,
+                            status: info.status,
+                            resetsAt: info.resetsAt,
+                        });
+                    }
+                }
+            }
             if (msg.type === "result") {
+                const r = msg;
+                if (typeof r.total_cost_usd === "number") {
+                    costUsd = r.total_cost_usd;
+                    _plannerRateLimitInfo.costUsd += costUsd;
+                }
                 if (msg.subtype === "success")
-                    resultText = msg.result || "";
+                    resultText = r.result || "";
                 else
-                    throw new Error(`Planner failed: ${msg.result || msg.subtype}`);
+                    throw new Error(`Planner failed: ${r.result || msg.subtype}`);
             }
         }
     };

package/dist/swarm.d.ts

@@ -1,4 +1,4 @@
-import type { Task, AgentState, SwarmPhase, PermMode, MergeStrategy } from "./types.js";
+import type { Task, AgentState, SwarmPhase, PermMode, MergeStrategy, RateLimitWindow } from "./types.js";
 export interface SwarmConfig {
     tasks: Task[];
     concurrency: number;
@@ -12,6 +12,10 @@ export interface SwarmConfig {
     mergeStrategy?: MergeStrategy;
     /** Stop dispatching new tasks when rate-limit utilization reaches this fraction (0-1). */
     usageCap?: number;
+    /** Allow agents to use extra usage (overage billing). Default false. */
+    allowExtraUsage?: boolean;
+    /** Max $ to spend on extra usage before stopping. Only applies when allowExtraUsage is true. */
+    extraUsageBudget?: number;
 }
 export interface MergeResult {
     branch: string;
@@ -42,6 +46,14 @@ export declare class Swarm {
     rateLimitUtilization: number;
     rateLimitStatus: string;
     rateLimitResetsAt?: number;
+    /** Per-window rate limit snapshots (updated on every rate_limit_event). */
+    rateLimitWindows: Map<string, RateLimitWindow>;
+    /** Whether any agent is currently using extra/overage usage. */
+    isUsingOverage: boolean;
+    /** Why overage is disabled (if applicable). */
+    overageDisabledReason?: string;
+    /** Accumulated cost from extra/overage usage only. */
+    overageCostUsd: number;
     private queue;
     private config;
     private nextId;
@@ -50,7 +62,9 @@ export declare class Swarm {
     private cleanedUp;
     logFile?: string;
     readonly model: string | undefined;
-    readonly usageCap: number | undefined;
+    usageCap: number | undefined;
+    readonly allowExtraUsage: boolean;
+    readonly extraUsageBudget: number | undefined;
     constructor(config: SwarmConfig);
     get active(): number;
     get pending(): number;
@@ -60,6 +74,7 @@ export declare class Swarm {
     logSequence: number;
     log(agentId: number, text: string): void;
     private worker;
+    private capForOverage;
     private throttle;
     private runAgent;
     private autoCommit;

package/dist/swarm.js

@@ -22,6 +22,14 @@ export class Swarm {
     rateLimitUtilization = 0;
     rateLimitStatus = "";
     rateLimitResetsAt;
+    /** Per-window rate limit snapshots (updated on every rate_limit_event). */
+    rateLimitWindows = new Map();
+    /** Whether any agent is currently using extra/overage usage. */
+    isUsingOverage = false;
+    /** Why overage is disabled (if applicable). */
+    overageDisabledReason;
+    /** Accumulated cost from extra/overage usage only. */
+    overageCostUsd = 0;
     queue;
     config;
     nextId = 0;
@@ -30,7 +38,9 @@ export class Swarm {
     cleanedUp = false;
     logFile;
     model;
-    usageCap;
+    usageCap; // mutable — can be changed live
+    allowExtraUsage;
+    extraUsageBudget;
     constructor(config) {
         if (!config.tasks.length) {
             throw new Error("SwarmConfig: tasks array must not be empty");
@@ -52,6 +62,8 @@ export class Swarm {
         this.config = config;
         this.model = config.model;
         this.usageCap = config.usageCap;
+        this.allowExtraUsage = config.allowExtraUsage ?? false;
+        this.extraUsageBudget = config.extraUsageBudget;
         this.queue = [...config.tasks];
         this.total = config.tasks.length;
     }
@@ -119,14 +131,33 @@ export class Swarm {
         }
         this.log(-1, `Worker finished (${tasksProcessed} tasks)`);
     }
+    capForOverage(reason) {
+        if (this.cappedOut)
+            return;
+        this.cappedOut = true;
+        this.queue.length = 0;
+        this.log(-1, reason);
+    }
     async throttle() {
+        if (this.cappedOut)
+            return;
         // Usage cap: stop dispatching when utilization exceeds user's cap
-        const cap = this.config.usageCap;
+        const cap = this.usageCap;
         if (cap != null && cap < 1 && this.rateLimitUtilization >= cap) {
             this.cappedOut = true;
             this.log(-1, `Usage cap ${Math.round(cap * 100)}% reached (at ${Math.round(this.rateLimitUtilization * 100)}%) — finishing active agents, no new tasks`);
             return;
         }
+        // Extra usage enforcement: stop if overage detected and not allowed
+        if (this.isUsingOverage && !this.allowExtraUsage) {
+            this.capForOverage(`Extra usage detected but not allowed — stopping dispatch`);
+            return;
+        }
+        // Extra usage budget enforcement
+        if (this.isUsingOverage && this.extraUsageBudget != null && this.overageCostUsd >= this.extraUsageBudget) {
+            this.capForOverage(`Extra usage budget $${this.extraUsageBudget} reached ($${this.overageCostUsd.toFixed(2)} spent) — stopping dispatch`);
+            return;
+        }
         // Hard block: rate limit rejected — wait until reset
         if (this.rateLimitResetsAt) {
             const resetTarget = this.rateLimitResetsAt;
@@ -604,6 +635,8 @@ export class Swarm {
                 const cost = safeAdd(r.total_cost_usd);
                 agent.costUsd = cost;
                 this.totalCostUsd += cost;
+                if (this.isUsingOverage)
+                    this.overageCostUsd += cost;
                 if (r.usage) {
                     this.totalInputTokens += safeAdd(r.usage.input_tokens);
                     this.totalOutputTokens += safeAdd(r.usage.output_tokens);
@@ -629,8 +662,29 @@ export class Swarm {
                 if (info.status === "rejected" && info.resetsAt) {
                     this.rateLimitResetsAt = info.resetsAt;
                 }
+                // Track per-window state
+                const windowType = info.rateLimitType;
+                if (windowType) {
+                    this.rateLimitWindows.set(windowType, {
+                        type: windowType,
+                        utilization: info.utilization ?? 0,
+                        status: info.status,
+                        resetsAt: info.resetsAt,
+                    });
+                }
+                // Track overage state
+                if (info.isUsingOverage) {
+                    this.isUsingOverage = true;
+                }
+                if (info.overageDisabledReason) {
+                    this.overageDisabledReason = info.overageDisabledReason;
+                }
+                if (this.isUsingOverage && !this.allowExtraUsage) {
+                    this.capForOverage(`Extra usage detected but not allowed — stopping dispatch`);
+                }
                 const pct = info.utilization != null ? `${Math.round(info.utilization * 100)}%` : "";
-                this.log(agent.id, `Rate: ${info.status} ${pct}`);
+                const overageTag = this.isUsingOverage ? " [EXTRA]" : "";
+                this.log(agent.id, `Rate: ${info.status} ${pct}${overageTag}${windowType ? ` (${windowType})` : ""}`);
                 break;
             }
         }

package/dist/types.d.ts

@@ -103,6 +103,13 @@ export interface BranchRecord {
     filesChanged: number;
     costUsd: number;
 }
+/** Per-window rate limit snapshot (matches SDK rateLimitType). */
+export interface RateLimitWindow {
+    type: string;
+    utilization: number;
+    status: string;
+    resetsAt?: number;
+}
 /** Persisted run state for crash recovery and resume. */
 export interface RunState {
     id: string;
@@ -114,6 +121,8 @@ export interface RunState {
     concurrency: number;
     permissionMode: PermMode;
     usageCap?: number;
+    allowExtraUsage: boolean;
+    extraUsageBudget?: number;
     flex: boolean;
     useWorktrees: boolean;
     mergeStrategy: MergeStrategy;
@@ -125,7 +134,7 @@ export interface RunState {
     accCompleted: number;
     accFailed: number;
     branches: BranchRecord[];
-    phase: "executing" | "steering" | "reflecting" | "done";
+    phase: "executing" | "steering" | "reflecting" | "capped" | "done";
     startedAt: string;
     cwd: string;
 }

package/dist/ui.d.ts

@@ -1,4 +1,11 @@
 import type { Swarm } from "./swarm.js";
-export declare function renderFrame(swarm: Swarm): string;
-export declare function startRenderLoop(swarm: Swarm): () => void;
+export declare function renderFrame(swarm: Swarm, showHotkeys?: boolean): string;
+/** Mutable config that can be changed live during execution. */
+export interface LiveConfig {
+    remaining: number;
+    usageCap: number | undefined;
+    /** Set by hotkey handler when user changes a value. Cleared after main loop reads it. */
+    dirty: boolean;
+}
+export declare function startRenderLoop(swarm: Swarm, liveConfig?: LiveConfig): () => void;
 export declare function renderSummary(swarm: Swarm): string;

package/dist/ui.js

@@ -1,5 +1,9 @@
 import chalk from "chalk";
 const SPINNER = ["|", "/", "-", "\\"];
+const WINDOW_SHORT_NAMES = {
+    five_hour: "5h", seven_day: "7d", seven_day_opus: "7d op",
+    seven_day_sonnet: "7d sn", overage: "extra",
+};
 function colorEvent(text) {
     if (text === "Done" || text.startsWith("Merged ") || text.startsWith("Committed "))
         return chalk.green(text);
@@ -11,7 +15,7 @@ function colorEvent(text) {
         return chalk.yellow(text);
     return text;
 }
-export function renderFrame(swarm) {
+export function renderFrame(swarm, showHotkeys = false) {
     const w = Math.max((process.stdout.columns ?? 80) || 80, 60);
     const out = [];
     // ── Header ──
@@ -43,33 +47,58 @@ export function renderFrame(swarm) {
         : "";
     out.push(chalk.gray(`  \u2191 ${tokIn} in  \u2193 ${tokOut} out`) +
         (cost ? `  ${cost}` : ""));
-    // ── Usage bar ──
+    // ── Usage bar(s) — cycle through windows every 3s ──
+    const windows = Array.from(swarm.rateLimitWindows.values());
     const rlPct = swarm.rateLimitUtilization;
-    if (rlPct > 0 || swarm.rateLimitResetsAt || swarm.cappedOut) {
+    if (rlPct > 0 || swarm.rateLimitResetsAt || swarm.cappedOut || windows.length > 0) {
         const barW = Math.min(30, w - 40);
-        const filled = Math.round(rlPct * barW);
         const capFrac = swarm.usageCap;
         const capMark = capFrac != null && capFrac < 1 ? Math.round(capFrac * barW) : -1;
-        let barStr = "";
-        for (let i = 0; i < barW; i++) {
-            if (i === capMark)
-                barStr += chalk.yellow("\u2502");
-            else if (i < filled)
-                barStr += rlPct > 0.9 ? chalk.red("\u2588") : rlPct > 0.75 ? chalk.yellow("\u2588") : chalk.blue("\u2588");
-            else
-                barStr += chalk.gray("\u2591");
-        }
-        let label = `${Math.round(rlPct * 100)}% used`;
-        if (swarm.cappedOut) {
-            label = chalk.yellow(`Capped at ${capFrac != null ? Math.round(capFrac * 100) : 100}% — finishing active`);
+        // Show primary usage bar
+        const renderBar = (pct, windowLabel) => {
+            const filled = Math.round(pct * barW);
+            let barStr = "";
+            for (let i = 0; i < barW; i++) {
+                if (i === capMark)
+                    barStr += chalk.yellow("\u2502");
+                else if (i < filled)
+                    barStr += pct > 0.9 ? chalk.red("\u2588") : pct > 0.75 ? chalk.yellow("\u2588") : chalk.blue("\u2588");
+                else
+                    barStr += chalk.gray("\u2591");
+            }
+            let label = `${Math.round(pct * 100)}% used`;
+            if (swarm.cappedOut) {
+                if (swarm.isUsingOverage && !swarm.allowExtraUsage) {
+                    label = chalk.red("Extra usage blocked — stopping");
+                }
+                else {
+                    label = chalk.yellow(`Capped at ${capFrac != null ? Math.round(capFrac * 100) : 100}% — finishing active`);
+                }
+            }
+            else if (swarm.rateLimitResetsAt) {
+                const waitSec = Math.max(0, Math.ceil((swarm.rateLimitResetsAt - Date.now()) / 1000));
+                const mm = Math.floor(waitSec / 60);
+                const ss = waitSec % 60;
+                label = chalk.red(`Waiting for reset ${mm > 0 ? `${mm}m ${ss}s` : `${ss}s`}`);
+            }
+            if (swarm.isUsingOverage && !swarm.cappedOut)
+                label += chalk.red(" [EXTRA USAGE]");
+            const prefix = windowLabel ? chalk.dim(windowLabel.padEnd(6)) : chalk.dim("Usage ");
+            out.push(`  ${prefix}${barStr}  ${label}`);
+        };
+        if (windows.length > 1) {
+            // Cycle through windows every 3 seconds
+            const cycleIdx = Math.floor(Date.now() / 3000) % windows.length;
+            const win = windows[cycleIdx];
+            const shortName = WINDOW_SHORT_NAMES[win.type] ?? win.type.replace(/_/g, " ");
+            renderBar(win.utilization, shortName);
+            // Show dots indicator for which window we're viewing
+            const dots = windows.map((_, i) => i === cycleIdx ? "●" : "○").join("");
+            out[out.length - 1] += chalk.dim(`  ${dots}`);
         }
-        else if (swarm.rateLimitResetsAt) {
-            const waitSec = Math.max(0, Math.ceil((swarm.rateLimitResetsAt - Date.now()) / 1000));
-            const mm = Math.floor(waitSec / 60);
-            const ss = waitSec % 60;
-            label = chalk.red(`Waiting for reset ${mm > 0 ? `${mm}m ${ss}s` : `${ss}s`}`);
+        else {
+            renderBar(rlPct);
         }
-        out.push(`  ${chalk.dim("Usage")} ${barStr}  ${label}`);
     }
     out.push("");
     // ── Agent table ──
@@ -115,6 +144,8 @@ export function renderFrame(swarm) {
             : chalk.cyan(`[${entry.agentId}]`);
         out.push(chalk.gray(`  ${t} `) + tag + ` ${colorEvent(truncate(entry.text, w - 22))}`);
     }
+    if (showHotkeys)
+        out.push(chalk.dim("  [b] budget  [t] threshold  [q] stop"));
     out.push("");
     return out.join("\n");
 }
@@ -170,7 +201,7 @@ function fmtDur(ms) {
         return `${m}m ${s % 60}s`;
     return `${Math.floor(m / 60)}h ${m % 60}m`;
 }
-export function startRenderLoop(swarm) {
+export function startRenderLoop(swarm, liveConfig) {
     if (!process.stdout.isTTY) {
         return startPlainLog(swarm);
     }
@@ -180,17 +211,93 @@ export function startRenderLoop(swarm) {
     catch {
         return () => { };
     }
+    // Live hotkey input state
+    let inputMode = "none";
+    let inputBuf = "";
+    const hasHotkeys = !!liveConfig && !!process.stdin.isTTY;
+    const render = () => {
+        let frame = renderFrame(swarm, hasHotkeys);
+        if (inputMode !== "none") {
+            const label = inputMode === "budget" ? "New budget (remaining sessions)" : "New usage cap (0-100%)";
+            frame += `\n  ${chalk.cyan(">")} ${label}: ${inputBuf}█`;
+        }
+        return frame;
+    };
     const interval = setInterval(() => {
         try {
             process.stdout.write("\x1B[H\x1B[J");
-            process.stdout.write(renderFrame(swarm));
+            process.stdout.write(render());
         }
         catch {
             clearInterval(interval);
         }
     }, 250);
+    // Keyboard listener for live controls
+    let keyHandler;
+    if (liveConfig && process.stdin.isTTY) {
+        try {
+            process.stdin.setRawMode(true);
+            process.stdin.resume();
+        }
+        catch { }
+        keyHandler = (buf) => {
+            const s = buf.toString();
+            if (inputMode !== "none") {
+                if (s === "\r" || s === "\n") {
+                    const val = parseFloat(inputBuf);
+                    if (inputMode === "budget" && !isNaN(val) && val > 0) {
+                        liveConfig.remaining = Math.round(val);
+                        liveConfig.dirty = true;
+                        swarm.log(-1, `Budget changed to ${liveConfig.remaining} remaining`);
+                    }
+                    else if (inputMode === "threshold" && !isNaN(val) && val >= 0 && val <= 100) {
+                        const frac = val / 100;
+                        liveConfig.usageCap = frac > 0 ? frac : undefined;
+                        liveConfig.dirty = true;
+                        swarm.usageCap = liveConfig.usageCap;
+                        swarm.log(-1, `Usage cap changed to ${val > 0 ? val + "%" : "unlimited"}`);
+                    }
+                    inputMode = "none";
+                    inputBuf = "";
+                }
+                else if (s === "\x1B" || s === "\x03") {
+                    inputMode = "none";
+                    inputBuf = "";
+                }
+                else if (s === "\x7F") {
+                    inputBuf = inputBuf.slice(0, -1);
+                }
+                else if (/^[0-9.]$/.test(s)) {
+                    inputBuf += s;
+                }
+                return;
+            }
+            if (s === "b" || s === "B") {
+                inputMode = "budget";
+                inputBuf = "";
+            }
+            else if (s === "t" || s === "T") {
+                inputMode = "threshold";
+                inputBuf = "";
+            }
+            else if (s === "q" || s === "Q" || s === "\x03") {
+                if (swarm.aborted)
+                    process.exit(0); // second press = force quit
+                swarm.abort();
+            }
+        };
+        process.stdin.on("data", keyHandler);
+    }
     return () => {
         clearInterval(interval);
+        if (keyHandler) {
+            process.stdin.removeListener("data", keyHandler);
+            try {
+                process.stdin.setRawMode(false);
+                process.stdin.pause();
+            }
+            catch { }
+        }
         try {
             process.stdout.write("\x1B[H\x1B[J");
             process.stdout.write(renderFrame(swarm));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-overnight",
-  "version": "1.0.1",
+  "version": "1.2.0",
   "description": "Run 10, 100, or 1000 Claude agents overnight. Parallel autonomous AI coding with thinking waves, iterative quality steering, crash recovery, and rate limit handling. Built on the Claude Agent SDK.",
   "type": "module",
   "bin": {