claude-overnight 1.1.0 → 1.2.1

package/README.md

@@ -33,22 +33,26 @@ 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  │
+╰──────────────────────────────────────────────────╯
+
+⠹ 8s · $0.04 · 12% · identifying themes   ← every phase shows cost + usage
 ✓ 5 themes → review, press Run, walk away
 
-◆ Thinking: 5 agents exploring...     ← architects analyze your codebase
-◆ Orchestrating plan...               ← synthesizes 50 concrete tasks
-◆ Wave 1 · 50 tasks                   ← fully autonomous from here
+◆ Thinking: 5 agents exploring...         ← architects analyze your codebase
+◆ Orchestrating plan...                   ← synthesizes 50 concrete tasks
+◆ Wave 1 · 50 tasks · $4.20 spent        ← fully autonomous from here
 ◆ Assessing... how close to amazing?
-◆ Wave 2 · 30 tasks                   ← improvements from assessment
-◆ Reflection: 2 agents reviewing      ← deep quality audit
-◆ Wave 3 · 20 tasks                   ← fixes from review findings
+◆ Wave 2 · 30 tasks · $18.50 spent       ← improvements from assessment
+◆ Reflection: 2 agents reviewing          ← deep quality audit
+◆ Wave 3 · 20 tasks · $31.00 spent       ← fixes from review findings
 ◆ Assessing... ✓ Vision met
 ```
 
@@ -172,6 +176,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 |
@@ -190,12 +196,38 @@ 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 — run is resumable

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)")}
 
@@ -677,6 +679,8 @@ async function main() {
     let concurrency;
     let objective = fileCfg?.objective;
     let usageCap;
+    let allowExtraUsage = false;
+    let extraUsageBudget;
     if (!nonInteractive) {
         // ① Objective
         while (true) {
@@ -724,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 = [];
@@ -747,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(" · "));
@@ -780,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";
@@ -789,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;
@@ -816,18 +852,8 @@ async function main() {
         try {
             if (useThinking) {
                 // Phase 1: Quick theme identification → review → then autonomous
-                let themeFrame = 0;
-                const themeSpinner = setInterval(() => {
-                    const spin = chalk.cyan(BRAILLE[themeFrame++ % BRAILLE.length]);
-                    process.stdout.write(`\x1B[2K\r  ${spin} ${chalk.dim("identifying themes...")}`);
-                }, 120);
                 let themes;
-                try {
-                    themes = await identifyThemes(objective, thinkingCount, plannerModel, permissionMode);
-                }
-                finally {
-                    clearInterval(themeSpinner);
-                }
+                themes = await identifyThemes(objective, thinkingCount, plannerModel, permissionMode, makeProgressLog());
                 process.stdout.write(`\x1B[2K\r  ${chalk.green(`\u2713 ${themes.length} themes`)}\n\n`);
                 // Show themes for review — this is the LAST user interaction
                 planRestore();
@@ -852,7 +878,7 @@ async function main() {
                                 break;
                             process.stdout.write("\x1B[?25l");
                             try {
-                                themes = await identifyThemes(`${objective}\n\nUser feedback: ${feedback}`, thinkingCount, plannerModel, permissionMode);
+                                themes = await identifyThemes(`${objective}\n\nUser feedback: ${feedback}`, thinkingCount, plannerModel, permissionMode, makeProgressLog());
                                 process.stdout.write(`\x1B[2K\r  ${chalk.green(`\u2713 ${themes.length} themes`)}\n\n`);
                             }
                             catch (err) {
@@ -894,9 +920,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();
                     }
@@ -1046,6 +1072,7 @@ 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;
@@ -1073,6 +1100,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 {
@@ -1094,6 +1123,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;
@@ -1131,14 +1162,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();
         }
@@ -1163,6 +1195,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);
@@ -1170,7 +1209,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,
         });
@@ -1236,10 +1275,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();
                     }
@@ -1290,7 +1329,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: finalPhase, startedAt: new Date(runStartedAt).toISOString(), cwd,
     });

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,8 +36,9 @@ 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 identifyThemes(objective: string, count: number, model: string, permissionMode: PermMode, onLog?: (text: string) => void): Promise<string[]>;
 export declare function buildThinkingTasks(objective: string, themes: string[], designDir: string, plannerModel: string, previousKnowledge?: string): Task[];
 export declare function buildReflectionTasks(objective: string, goal: string, reflectionDir: string, waveNum: number, plannerModel: string): Task[];
 export declare function orchestrate(objective: string, designDocs: string, cwd: string, plannerModel: string, workerModel: string, permissionMode: PermMode, budget: number, concurrency: number, onLog: (text: string) => void, flexNote?: string, outFile?: string): Promise<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}`);
             }
         }
     };
@@ -332,24 +366,8 @@ export async function planTasks(objective, cwd, plannerModel, workerModel, permi
     return tasks;
 }
 // ── Thinking wave ──
-export async function identifyThemes(objective, count, model, permissionMode) {
-    let resultText = "";
-    for await (const msg of query({
-        prompt: `Split this objective into exactly ${count} independent research angles for architects exploring a codebase. Each angle should cover a distinct aspect.
-
-Objective: ${objective}
-
-Return ONLY a JSON object: {"themes": ["angle description", ...]}`,
-        options: {
-            model,
-            permissionMode,
-            ...(permissionMode === "bypassPermissions" && { allowDangerouslySkipPermissions: true }),
-            persistSession: false,
-        },
-    })) {
-        if (msg.type === "result" && msg.subtype === "success")
-            resultText = msg.result || "";
-    }
+export async function identifyThemes(objective, count, model, permissionMode, onLog = () => { }) {
+    const resultText = await runPlannerQuery(`Split this objective into exactly ${count} independent research angles for architects exploring a codebase. Each angle should cover a distinct aspect.\n\nObjective: ${objective}\n\nReturn ONLY a JSON object: {"themes": ["angle description", ...]}`, { cwd: process.cwd(), model, permissionMode }, onLog);
     const parsed = attemptJsonParse(resultText);
     if (parsed?.themes && Array.isArray(parsed.themes))
         return parsed.themes.slice(0, count);

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;

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.1.0",
+  "version": "1.2.1",
   "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": {