claude-overnight 1.17.0 → 1.17.1

package/dist/auth.d.ts

@@ -0,0 +1,19 @@
+export interface JWTPayload {
+    sub: string;
+    model: string;
+    bearer: string;
+    aud: string;
+    iat: number;
+    exp: number;
+}
+export interface TokenRecord {
+    signedToken: string;
+    payload: JWTPayload;
+}
+export declare function loadSecret(): Buffer;
+export declare function signToken(providerId: string, model: string, bearer: string, baseURL: string): TokenRecord;
+export declare function verifyToken(token: string, providerId: string): JWTPayload | null;
+export declare function refreshToken(oldToken: string, providerId: string): TokenRecord | null;
+export declare function getBearerToken(providerId: string, model: string, bearer: string, baseURL: string): string;
+export declare function clearTokenCache(): void;
+export declare function isJWTAuthError(err: unknown): boolean;

package/dist/auth.js

@@ -0,0 +1,82 @@
+import { homedir } from "os";
+import { join } from "path";
+import { readFileSync, writeFileSync, mkdirSync, chmodSync } from "fs";
+const SECRET_PATH = join(homedir(), ".claude", "claude-overnight", "jwt-secret.key");
+export function loadSecret() {
+    try {
+        const raw = readFileSync(SECRET_PATH);
+        if (raw.length >= 32)
+            return raw;
+    }
+    catch { }
+    const secret = cryptoRandomBytes(32);
+    mkdirSync(join(homedir(), ".claude", "claude-overnight"), { recursive: true });
+    writeFileSync(SECRET_PATH, secret);
+    try {
+        chmodSync(SECRET_PATH, 0o600);
+    }
+    catch { }
+    return secret;
+}
+function deriveKey(secret, providerId) {
+    const crypto = require("crypto");
+    return crypto.createHmac("sha256", secret).update(providerId).digest();
+}
+const DEFAULT_TTL_SEC = 300; // 5 minutes
+export function signToken(providerId, model, bearer, baseURL) {
+    const jwt = require("jsonwebtoken");
+    const secret = loadSecret();
+    const key = deriveKey(secret, providerId);
+    const now = Math.floor(Date.now() / 1000);
+    const payload = { sub: providerId, model, bearer, aud: baseURL, iat: now, exp: now + DEFAULT_TTL_SEC };
+    const signedToken = jwt.sign(payload, key, { algorithm: "HS256" });
+    return { signedToken, payload };
+}
+export function verifyToken(token, providerId) {
+    const jwt = require("jsonwebtoken");
+    const secret = loadSecret();
+    const key = deriveKey(secret, providerId);
+    try {
+        return jwt.verify(token, key, { algorithms: ["HS256"] });
+    }
+    catch {
+        return null;
+    }
+}
+export function refreshToken(oldToken, providerId) {
+    const payload = verifyToken(oldToken, providerId);
+    if (!payload)
+        return null;
+    const now = Math.floor(Date.now() / 1000);
+    if (payload.exp - now > 60)
+        return null;
+    return signToken(payload.sub, payload.model, payload.bearer, payload.aud);
+}
+const tokenCache = new Map();
+export function getBearerToken(providerId, model, bearer, baseURL) {
+    const cached = tokenCache.get(providerId);
+    if (cached) {
+        const payload = verifyToken(cached.signedToken, providerId);
+        if (payload && payload.exp > Math.floor(Date.now() / 1000) + 30) {
+            return cached.signedToken;
+        }
+    }
+    const fresh = refreshToken(cached?.signedToken ?? "", providerId) ?? signToken(providerId, model, bearer, baseURL);
+    tokenCache.set(providerId, fresh);
+    return fresh.signedToken;
+}
+export function clearTokenCache() {
+    tokenCache.clear();
+}
+function cryptoRandomBytes(length) {
+    const crypto = require("crypto");
+    return crypto.randomBytes(length);
+}
+export function isJWTAuthError(err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    const lower = msg.toLowerCase();
+    return lower.includes("token expired") || lower.includes("invalid_token")
+        || lower.includes("jwt") || lower.includes("signature")
+        || lower.includes("unauthorized") || lower.includes("forbidden")
+        || lower.includes("invalid_api_key") || lower.includes("authentication");
+}

package/dist/cli.d.ts

@@ -4,7 +4,10 @@ export declare function parseCliFlags(argv: string[]): {
     flags: Record<string, string>;
     positional: string[];
 };
-export declare function isAuthError(err: unknown): boolean;
+import { isJWTAuthError } from "./auth.js";
+/** @deprecated Use isJWTAuthError from auth.ts instead. */
+export declare const isAuthError: typeof isJWTAuthError;
+export { isJWTAuthError };
 export declare function fetchModels(timeoutMs?: number): Promise<ModelInfo[]>;
 export declare const PASTE_START = "\u001B[200~";
 export declare const PASTE_END = "\u001B[201~";

package/dist/cli.js

@@ -29,12 +29,11 @@ export function parseCliFlags(argv) {
     }
     return { flags, positional };
 }
-// ── Auth error detection ──
-const AUTH_PATTERNS = ["unauthorized", "forbidden", "invalid_api_key", "authentication"];
-export function isAuthError(err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    return AUTH_PATTERNS.some((p) => msg.toLowerCase().includes(p));
-}
+// ── Auth error detection (re-exported from auth module for backward compatibility) ──
+import { isJWTAuthError } from "./auth.js";
+/** @deprecated Use isJWTAuthError from auth.ts instead. */
+export const isAuthError = isJWTAuthError;
+export { isJWTAuthError };
 // ── Fetch models via SDK ──
 export async function fetchModels(timeoutMs = 10_000) {
     let q;

package/dist/index.js

@@ -10,7 +10,7 @@ import { query } from "@anthropic-ai/claude-agent-sdk";
 import { Swarm } from "./swarm.js";
 import { planTasks, refinePlan, identifyThemes, buildThinkingTasks, orchestrate, salvageFromFile } from "./planner.js";
 import { detectModelTier, setPlannerEnvResolver } from "./planner-query.js";
-import { pickModel, loadProviders, preflightProvider, buildEnvResolver } from "./providers.js";
+import { pickModel, loadProviders, preflightProvider, buildEnvResolver, healthCheckCursorProxy, PROXY_DEFAULT_URL, isCursorProxyProvider } from "./providers.js";
 import { RunDisplay } from "./ui.js";
 import { renderSummary } from "./render.js";
 import { executeRun } from "./run.js";
@@ -217,6 +217,16 @@ async function main() {
             process.exit(1);
         }
     }
+    // ── Pre-check: warn if saved Cursor providers exist but proxy is down ──
+    const savedCursorProviders = loadProviders().filter(isCursorProxyProvider);
+    if (savedCursorProviders.length > 0 && !dryRun) {
+        const proxyUp = await healthCheckCursorProxy();
+        if (!proxyUp) {
+            console.warn(chalk.yellow(`\n  ⚠ ${savedCursorProviders.length} Cursor provider(s) saved but proxy is not running at ${PROXY_DEFAULT_URL}`));
+            console.warn(chalk.yellow(`    Start it: npx cursor-api-proxy`));
+            console.warn(chalk.dim(`    (Continuing — you can still use Anthropic models)\n`));
+        }
+    }
     // ── Load tasks ──
     let tasks = [];
     let fileCfg;

package/dist/planner-query.js

@@ -18,6 +18,11 @@ export function detectModelTier(model) {
         return "sonnet";
     if (m.includes("haiku"))
         return "haiku";
+    // Cursor API Proxy models
+    if (m === "auto")
+        return "unknown";
+    if (m.startsWith("composer"))
+        return "sonnet";
     return "unknown";
 }
 export function modelCapabilityBlock(model) {
@@ -29,6 +34,10 @@ export function modelCapabilityBlock(model) {
         case "haiku":
             return `Each agent runs Claude Haiku  -- fast and efficient, best for focused, well-specified tasks. Be explicit about files, functions, and expected changes. Keep each task scoped to a clear, concrete deliverable.`;
         default:
+            // Cursor API Proxy or unknown model — generic but mention Cursor context
+            if (model.toLowerCase().startsWith("composer") || model.toLowerCase() === "auto") {
+                return `Each agent runs a Cursor model with full codebase access. Capable of focused implementation work. Be explicit about files, functions, and expected changes.`;
+            }
             return `Each agent has full codebase access and can work autonomously.`;
     }
 }
@@ -44,6 +53,47 @@ let _plannerRateLimitInfo = {
     utilization: 0, status: "", isUsingOverage: false, windows: new Map(), costUsd: 0,
 };
 export function getPlannerRateLimitInfo() { return _plannerRateLimitInfo; }
+// ── Proactive throttle: wait before making API calls when utilization is high ──
+/**
+ * Proactive rate-limit gate. Called before each planner/steering query to
+ * prevent hammering the API when we're already near a limit.
+ *
+ * Levels:
+ *   - rejected -> wait until resetsAt (or 60s fallback)
+ *   - utilization >= 90% -> wait 30s with exponential backoff
+ *   - utilization >= 75% -> brief 5s cooldown
+ *   - utilization < 75% -> pass through immediately
+ */
+async function throttlePlanner(onLog, aborted) {
+    const MAX_BACKOFF = 3;
+    for (let backoff = 0; backoff <= MAX_BACKOFF; backoff++) {
+        if (aborted())
+            return;
+        const rl = _plannerRateLimitInfo;
+        const rejected = rl.resetsAt && rl.resetsAt > Date.now();
+        const highUtil = rl.utilization >= 0.9;
+        const elevatedUtil = rl.utilization >= 0.75;
+        if (!rejected && !highUtil && !elevatedUtil)
+            return;
+        const waitMs = rejected
+            ? Math.max(5000, rl.resetsAt - Date.now())
+            : highUtil
+                ? 30_000 * (1 + backoff)
+                : 5000;
+        const reason = rejected ? "Rate limited" : `Utilization ${Math.round(rl.utilization * 100)}%`;
+        onLog(`${reason}  -- waiting ${Math.ceil(waitMs / 1000)}s before query${backoff > 0 ? ` (backoff ${backoff})` : ""}`, "event");
+        await new Promise((r) => setTimeout(r, waitMs));
+        if (aborted())
+            return;
+        // After a wait, clear the rejected flag so we don't loop forever if
+        // the SDK stopped sending updates.
+        if (rejected && rl.resetsAt && rl.resetsAt <= Date.now()) {
+            rl.resetsAt = undefined;
+            rl.utilization = 0;
+        }
+    }
+    // Exhausted backoffs — proceed anyway, the retry loop will catch a rejection.
+}
 // ── Query execution ──
 const NUDGE_MS = 15 * 60 * 1000;
 const HARD_TIMEOUT_MS = 30 * 60 * 1000;
@@ -53,8 +103,11 @@ export async function runPlannerQuery(prompt, opts, onLog) {
     const BACKOFF = [30_000, 60_000, 120_000];
     let currentPrompt = prompt;
     let currentOpts = opts;
+    let aborted = false;
     for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
         try {
+            // Proactive throttle: wait if utilization is already high
+            await throttlePlanner(onLog, () => aborted);
             return await runPlannerQueryOnce(currentPrompt, currentOpts, onLog);
         }
         catch (err) {
@@ -78,6 +131,7 @@ export async function runPlannerQuery(prompt, opts, onLog) {
             throw err;
         }
     }
+    aborted = true;
     throw new Error("Planner query failed after retries");
 }
 async function runPlannerQueryOnce(prompt, opts, onLog) {

package/dist/providers.d.ts

@@ -13,6 +13,10 @@ export interface ProviderConfig {
     keyEnv?: string;
     /** Inline API key. Stored plaintext in providers.json (mode 0600). */
     key?: string;
+    /** When true, use JWT token auth instead of raw API keys. The bearer token is embedded in a short-lived JWT. */
+    useJWT?: boolean;
+    /** When true, this provider routes through cursor-api-proxy (special env/health-check handling). */
+    cursorProxy?: boolean;
 }
 export declare function getStorePath(): string;
 export declare function loadProviders(): ProviderConfig[];
@@ -47,6 +51,24 @@ export declare function preflightProvider(p: ProviderConfig, cwd: string, timeou
     ok: false;
     error: string;
 }>;
+export declare const PROXY_DEFAULT_URL = "http://127.0.0.1:8765";
+/** Check if a provider routes through cursor-api-proxy. */
+export declare function isCursorProxyProvider(p: ProviderConfig): boolean;
+/**
+ * Health check: GET /health on the proxy. Returns true if proxy is reachable.
+ */
+export declare function healthCheckCursorProxy(baseUrl?: string): Promise<boolean>;
+/**
+ * Fetch available Cursor models via GET /v1/models on the proxy.
+ * Returns model IDs like ["auto", "composer", "composer-2", "opus-4.6", ...].
+ */
+export declare function fetchCursorModels(baseUrl?: string): Promise<string[]>;
+/**
+ * Interactive setup guide for cursor-api-proxy.
+ * Walks through CLI install, login, and proxy start.
+ * Returns true when proxy is running and healthy.
+ */
+export declare function setupCursorProxy(): Promise<boolean>;
 export type EnvResolver = (model?: string) => Record<string, string> | undefined;
 /**
  * Build a single resolver that swarm.ts and planner-query.ts share. Maps a

package/dist/providers.js

@@ -1,9 +1,11 @@
 import { readFileSync, writeFileSync, mkdirSync, existsSync, chmodSync } from "fs";
 import { homedir } from "os";
 import { join } from "path";
+import { execSync } from "child_process";
 import chalk from "chalk";
 import { query } from "@anthropic-ai/claude-agent-sdk";
-import { ask, select } from "./cli.js";
+import { ask, select, selectKey } from "./cli.js";
+import { getBearerToken, clearTokenCache } from "./auth.js";
 // ── Store ──
 const STORE_PATH = join(homedir(), ".claude", "claude-overnight", "providers.json");
 export function getStorePath() { return STORE_PATH; }
@@ -26,6 +28,7 @@ export function saveProvider(p) {
         chmodSync(STORE_PATH, 0o600);
     }
     catch { }
+    clearTokenCache();
 }
 export function deleteProvider(id) {
     const all = loadProviders().filter(x => x.id !== id);
@@ -36,6 +39,7 @@ export function deleteProvider(id) {
         chmodSync(STORE_PATH, 0o600);
     }
     catch { }
+    clearTokenCache();
 }
 function isValidProvider(p) {
     return p && typeof p.id === "string" && typeof p.baseURL === "string"
@@ -55,15 +59,27 @@ export function resolveKey(p) {
  * you pass `options.env`.
  */
 export function envFor(p) {
-    const key = resolveKey(p);
-    if (!key)
-        throw new Error(`Provider "${p.id}" has no API key (${p.keyEnv ? `env ${p.keyEnv} is empty` : "inline key missing"})`);
     const base = {};
     for (const [k, v] of Object.entries(process.env))
         if (v !== undefined)
             base[k] = v;
+    if (p.cursorProxy) {
+        // cursor-api-proxy: routes through local proxy, no real API key needed
+        base.ANTHROPIC_BASE_URL = p.baseURL;
+        base.ANTHROPIC_AUTH_TOKEN = process.env.CURSOR_BRIDGE_API_KEY || "unused";
+        delete base.ANTHROPIC_API_KEY;
+        return base;
+    }
+    const key = resolveKey(p);
+    if (!key)
+        throw new Error(`Provider "${p.id}" has no API key (${p.keyEnv ? `env ${p.keyEnv} is empty` : "inline key missing"})`);
     base.ANTHROPIC_BASE_URL = p.baseURL;
-    base.ANTHROPIC_AUTH_TOKEN = key;
+    if (p.useJWT) {
+        base.ANTHROPIC_AUTH_TOKEN = getBearerToken(p.id, p.model, key, p.baseURL);
+    }
+    else {
+        base.ANTHROPIC_AUTH_TOKEN = key;
+    }
     delete base.ANTHROPIC_API_KEY;
     return base;
 }
@@ -90,8 +106,10 @@ export async function pickModel(label, anthropicModels, currentModelId) {
         }
         for (const p of saved) {
             const keySrc = p.keyEnv ? `env ${p.keyEnv}` : "stored key";
-            items.push({ name: `${p.displayName}`, value: { kind: "provider", provider: p }, hint: `${p.model} · ${keySrc}` });
+            const cursorTag = p.cursorProxy ? chalk.dim(" · cursor") : "";
+            items.push({ name: `${p.displayName}${cursorTag}`, value: { kind: "provider", provider: p }, hint: `${p.model} · ${keySrc}` });
         }
+        items.push({ name: chalk.green("Cursor…"), value: { kind: "cursor" }, hint: "Cursor API Proxy — composer, composer-2, auto, etc." });
         items.push({ name: chalk.cyan("Other…"), value: { kind: "other" }, hint: "Qwen 3.6 Plus, OpenRouter, or any Anthropic-compatible endpoint" });
         let defaultIdx = 0;
         if (currentModelId) {
@@ -111,6 +129,13 @@ export async function pickModel(label, anthropicModels, currentModelId) {
         if (picked.kind === "provider") {
             return { model: picked.provider.model, providerId: picked.provider.id, provider: picked.provider };
         }
+        if (picked.kind === "cursor") {
+            const cursorPick = await pickCursorModel();
+            if (cursorPick)
+                return cursorPick;
+            // user cancelled cursor picker — loop back
+            continue;
+        }
         const added = await promptNewProvider();
         if (added) {
             saveProvider(added);
@@ -144,12 +169,20 @@ async function promptNewProvider() {
         if (!process.env[envName]) {
             console.log(chalk.yellow(`\n  ⚠ ${envName} is not set in the current shell  -- you'll need to export it before running.`));
         }
-        return { id, displayName, baseURL, model, keyEnv: envName };
+        const useJWT = await select(`  ${chalk.cyan("Auth method")}:`, [
+            { name: "JWT tokens", value: "jwt", hint: "short-lived tokens, raw keys never passed to agents" },
+            { name: "Raw API key", value: "raw", hint: "key sent directly with every request" },
+        ]);
+        return { id, displayName, baseURL, model, keyEnv: envName, useJWT: useJWT === "jwt" };
     }
     const key = await ask(`\n  ${chalk.cyan("API key")}: `);
     if (!key)
         return null;
-    return { id, displayName, baseURL, model, key };
+    const useJWT = await select(`  ${chalk.cyan("Auth method")}:`, [
+        { name: "JWT tokens", value: "jwt", hint: "short-lived tokens, raw keys never passed to agents" },
+        { name: "Raw API key", value: "raw", hint: "key sent directly with every request" },
+    ]);
+    return { id, displayName, baseURL, model, key, useJWT: useJWT === "jwt" };
 }
 function slugify(s) {
     return s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 32) || "provider";
@@ -221,6 +254,264 @@ export async function preflightProvider(p, cwd, timeoutMs = 20_000) {
         catch { }
     }
 }
+// ── Cursor API Proxy ──
+export const PROXY_DEFAULT_URL = "http://127.0.0.1:8765";
+/** Check if a provider routes through cursor-api-proxy. */
+export function isCursorProxyProvider(p) {
+    return p.cursorProxy === true || p.baseURL === PROXY_DEFAULT_URL;
+}
+/**
+ * Health check: GET /health on the proxy. Returns true if proxy is reachable.
+ */
+export async function healthCheckCursorProxy(baseUrl = PROXY_DEFAULT_URL) {
+    const url = `${baseUrl.replace(/\/$/, "")}/health`;
+    try {
+        const res = await fetch(url, { method: "GET", signal: AbortSignal.timeout(3_000) });
+        return res.ok;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Fetch available Cursor models via GET /v1/models on the proxy.
+ * Returns model IDs like ["auto", "composer", "composer-2", "opus-4.6", ...].
+ */
+export async function fetchCursorModels(baseUrl = PROXY_DEFAULT_URL) {
+    const url = `${baseUrl.replace(/\/$/, "")}/v1/models`;
+    try {
+        const res = await fetch(url, { method: "GET", signal: AbortSignal.timeout(5_000) });
+        if (!res.ok)
+            return [];
+        const json = await res.json();
+        return (json.data || []).map(m => m.id).filter(Boolean);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Known Cursor model recommendations — short hints to guide users.
+ */
+const CURSOR_MODEL_HINTS = {
+    "auto": "fast — delegates to best available model",
+    "composer": "Cursor Composer — good for focused tasks",
+    "composer-2": "Cursor Composer 2 — latest, strongest Cursor model",
+};
+function cursorModelHint(modelId) {
+    const m = modelId.toLowerCase();
+    if (CURSOR_MODEL_HINTS[m])
+        return CURSOR_MODEL_HINTS[m];
+    if (m.includes("opus"))
+        return "Opus-tier Cursor model";
+    if (m.includes("sonnet"))
+        return "Sonnet-tier Cursor model";
+    if (m.includes("haiku"))
+        return "Haiku-tier Cursor model (fast)";
+    return "Cursor model";
+}
+function setupSteps() {
+    return [
+        {
+            label: "Cursor agent CLI",
+            check: () => {
+                try {
+                    execSync("which agent", { stdio: "pipe" });
+                    return true;
+                }
+                catch {
+                    return false;
+                }
+            },
+            autoCmd: "curl https://cursor.com/install -fsS | bash",
+            manualCmd: "curl https://cursor.com/install -fsS | bash",
+            successMsg: "Cursor CLI found",
+        },
+        {
+            label: "Cursor authentication",
+            check: () => {
+                try {
+                    const out = execSync("agent --list-models", { stdio: "pipe", timeout: 10_000 });
+                    return out.toString().trim().length > 0;
+                }
+                catch {
+                    return false;
+                }
+            },
+            autoCmd: "agent login",
+            manualCmd: "agent login",
+            successMsg: "Cursor authenticated",
+        },
+        {
+            label: "cursor-api-proxy server",
+            check: () => {
+                try {
+                    execSync("npx cursor-api-proxy --help", { stdio: "pipe", timeout: 10_000 });
+                    return true;
+                }
+                catch {
+                    return false;
+                }
+            },
+            autoCmd: "npx cursor-api-proxy",
+            manualCmd: "npx cursor-api-proxy",
+            successMsg: "cursor-api-proxy available",
+        },
+    ];
+}
+/**
+ * Interactive setup guide for cursor-api-proxy.
+ * Walks through CLI install, login, and proxy start.
+ * Returns true when proxy is running and healthy.
+ */
+export async function setupCursorProxy() {
+    console.log(chalk.dim("\n  Cursor API Proxy Setup"));
+    console.log(chalk.dim("  " + "─".repeat(40)));
+    console.log(chalk.dim("  We need three things: Cursor CLI, authentication, and the proxy server.\n"));
+    const steps = setupSteps();
+    for (const step of steps) {
+        if (step.check()) {
+            console.log(chalk.green(`  ✓ ${step.successMsg}`));
+            continue;
+        }
+        console.log(chalk.yellow(`\n  ${step.label} not found`));
+        const choice = await selectKey(`  Set up ${step.label}:`, [
+            { key: "a", desc: "uto (run command)" },
+            { key: "m", desc: "anual (show command)" },
+            { key: "s", desc: "kip (I'll handle it)" },
+        ]);
+        if (choice === "a") {
+            if (step.label === "Cursor authentication") {
+                // agent login needs interactive browser — run it directly
+                console.log(chalk.dim(`  Running: ${step.autoCmd}`));
+                console.log(chalk.dim("  (A browser window will open for login)\n"));
+                try {
+                    execSync(step.autoCmd, { stdio: "inherit", timeout: 120_000 });
+                    console.log(chalk.green(`  ✓ ${step.successMsg}`));
+                }
+                catch {
+                    console.log(chalk.yellow("  Login failed — try manual mode"));
+                    // Fall through to manual display
+                }
+            }
+            else if (step.label === "cursor-api-proxy server") {
+                // Don't auto-start the proxy server here — it blocks. Just verify it's installable.
+                console.log(chalk.dim(`  Install check: ${step.autoCmd} --help`));
+                try {
+                    execSync("npx cursor-api-proxy --help", { stdio: "pipe", timeout: 30_000 });
+                    console.log(chalk.green(`  ✓ cursor-api-proxy installed`));
+                    console.log(chalk.yellow(`  → Start it in another terminal: ${chalk.bold("npx cursor-api-proxy")}`));
+                    const ready = await selectKey(`  Is the proxy running now?`, [
+                        { key: "y", desc: "es" },
+                        { key: "n", desc: "ot yet" },
+                    ]);
+                    if (ready === "y") {
+                        if (await healthCheckCursorProxy()) {
+                            console.log(chalk.green(`  ✓ Proxy connected`));
+                            return true;
+                        }
+                    }
+                }
+                catch {
+                    console.log(chalk.red("  cursor-api-proxy not installed. Install with: npm install -g cursor-api-proxy"));
+                }
+            }
+            else {
+                console.log(chalk.dim(`  Running: ${step.autoCmd}`));
+                try {
+                    execSync(step.autoCmd, { stdio: "inherit", timeout: 60_000 });
+                    console.log(chalk.green(`  ✓ ${step.successMsg}`));
+                }
+                catch {
+                    console.log(chalk.yellow("  Command failed — try manual mode"));
+                }
+            }
+        }
+        else if (choice === "m") {
+            console.log(chalk.cyan(`\n  Run this command:`));
+            console.log(chalk.white(`    ${step.manualCmd}`));
+            if (step.label === "cursor-api-proxy server") {
+                console.log(chalk.yellow(`    Then start the proxy: ${chalk.bold("npx cursor-api-proxy")}`));
+            }
+            console.log();
+            const done = await selectKey(`  Done?`, [
+                { key: "y", desc: "es" },
+                { key: "n", desc: "ot yet" },
+            ]);
+            if (done === "y" && step.label === "cursor-api-proxy server") {
+                if (await healthCheckCursorProxy()) {
+                    console.log(chalk.green(`  ✓ Proxy connected`));
+                    return true;
+                }
+            }
+        }
+        else {
+            console.log(chalk.dim(`  Skipped: ${step.label}`));
+        }
+    }
+    // Final health check
+    if (await healthCheckCursorProxy()) {
+        console.log(chalk.green("\n  ✓ Proxy is running and healthy"));
+        return true;
+    }
+    console.log(chalk.yellow("\n  Proxy not reachable yet. You can start it later and add it via 'Cursor' in the model picker."));
+    return false;
+}
+// ── Cursor model picker sub-flow ──
+async function pickCursorModel() {
+    console.log(chalk.dim("\n  Cursor API Proxy Models"));
+    console.log(chalk.dim("  " + "─".repeat(40)));
+    // Quick health check with spinner
+    let frame = 0;
+    const BRAILLE = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+    const spinner = setInterval(() => {
+        process.stdout.write(`\x1B[2K\r  ${chalk.cyan(BRAILLE[frame++ % BRAILLE.length])} ${chalk.dim("checking proxy...")}`);
+    }, 120);
+    const healthy = await healthCheckCursorProxy();
+    clearInterval(spinner);
+    process.stdout.write("\x1B[2K\r");
+    if (!healthy) {
+        console.log(chalk.yellow("  Proxy is not running at " + PROXY_DEFAULT_URL));
+        const choice = await selectKey(`  What next?`, [
+            { key: "s", desc: "etup guide" },
+            { key: "r", desc: "etry" },
+            { key: "c", desc: "ancel" },
+        ]);
+        if (choice === "s") {
+            const ok = await setupCursorProxy();
+            if (!ok)
+                return null;
+        }
+        else if (choice === "r") {
+            return pickCursorModel();
+        }
+        else {
+            return null;
+        }
+    }
+    // Fetch live models
+    const modelIds = await fetchCursorModels();
+    if (modelIds.length === 0) {
+        console.log(chalk.yellow("  No models returned from proxy"));
+        return null;
+    }
+    const picked = await select("  Select a Cursor model:", modelIds.map(id => ({
+        name: id,
+        value: id,
+        hint: cursorModelHint(id),
+    })), 0);
+    // Save as a cursor proxy provider
+    const provider = {
+        id: `cursor-${picked}`,
+        displayName: `Cursor: ${picked}`,
+        baseURL: PROXY_DEFAULT_URL,
+        model: picked,
+        cursorProxy: true,
+    };
+    saveProvider(provider);
+    console.log(chalk.green(`  ✓ Saved as provider: ${provider.displayName}`));
+    return { model: picked, providerId: provider.id, provider };
+}
 /**
  * Build a single resolver that swarm.ts and planner-query.ts share. Maps a
  * model string to the env overrides that should be passed to `query()`.

package/dist/run.js

@@ -9,7 +9,8 @@ import { buildEnvResolver } from "./providers.js";
 import { RunDisplay } from "./ui.js";
 import { renderSummary } from "./render.js";
 import { fmtTokens } from "./render.js";
-import { isAuthError, selectKey, ask } from "./cli.js";
+import { isJWTAuthError } from "./auth.js";
+import { selectKey, ask } from "./cli.js";
 import { readRunMemory, writeStatus, writeGoalUpdate, saveRunState, saveWaveSession, loadWaveHistory, recordBranches, archiveMilestone, writeSteerInbox, consumeSteerInbox, countSteerInbox, appendOvernightLogStart, updateOvernightLogEnd, } from "./state.js";
 export async function executeRun(cfg) {
     const restore = () => { try {
@@ -353,6 +354,11 @@ export async function executeRun(cfg) {
                 currentTasks = currentTasks.slice(0, remaining);
             syncRunInfo();
             saveRunState(runDir, buildRunState({ remaining, phase: "steering", currentTasks }));
+            // Pre-wave rate limit gate: don't spawn a new wave if the API is already
+            // near a limit. This prevents wasting sessions on instant rejections.
+            await throttleBeforeWave(() => getPlannerRateLimitInfo(), (text) => display.appendSteeringEvent(text), () => stopping);
+            if (stopping)
+                break;
             const swarm = new Swarm({
                 tasks: currentTasks, concurrency, cwd, model: workerModel, permissionMode, allowedTools,
                 useWorktrees, mergeStrategy: waveMerge, agentTimeoutMs: cfg.agentTimeoutMs,
@@ -366,7 +372,7 @@ export async function executeRun(cfg) {
                 await swarm.run();
             }
             catch (err) {
-                if (isAuthError(err)) {
+                if (isJWTAuthError(err)) {
                     display.stop();
                     restore();
                     console.error(chalk.red(`\n  Authentication failed  -- check your API key or run: claude auth\n`));
@@ -751,3 +757,51 @@ function checkProjectHealth(cwd) {
         };
     }
 }
+// ── Pre-wave rate limit gate ──
+function sleep(ms) {
+    return new Promise(r => setTimeout(r, ms));
+}
+/**
+ * Proactive rate-limit gate called before spawning a new wave. Prevents
+ * starting a batch of agents when the API is already near or at a limit,
+ * which would waste sessions on instant rejections.
+ *
+ * Thresholds:
+ *   - any window rejected → wait until resetsAt (or 60s fallback)
+ *   - utilization >= 90% → wait 60s
+ *   - utilization >= 75% → wait 15s
+ */
+async function throttleBeforeWave(getRL, log, shouldStop) {
+    const MAX_ATTEMPTS = 4;
+    for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
+        if (shouldStop())
+            return;
+        const rl = getRL();
+        // Check for rejected windows
+        let rejectedReset;
+        for (const w of rl.windows.values()) {
+            if (w.status === "rejected" && w.resetsAt && w.resetsAt > Date.now()) {
+                if (!rejectedReset || w.resetsAt < rejectedReset)
+                    rejectedReset = w.resetsAt;
+            }
+        }
+        const highUtil = rl.utilization >= 0.9;
+        const elevatedUtil = rl.utilization >= 0.75;
+        const explicitRejected = rl.resetsAt && rl.resetsAt > Date.now();
+        if (!rejectedReset && !explicitRejected && !highUtil && !elevatedUtil)
+            return;
+        const waitMs = rejectedReset
+            ? Math.max(10_000, rejectedReset - Date.now())
+            : explicitRejected
+                ? Math.max(10_000, rl.resetsAt - Date.now())
+                : highUtil
+                    ? 60_000 * (1 + attempt)
+                    : 15_000;
+        const reason = rejectedReset ? `Rate limit window blocked`
+            : explicitRejected ? "Rate limited"
+                : `Utilization ${Math.round(rl.utilization * 100)}%`;
+        log(`${reason}  -- waiting ${Math.ceil(waitMs / 1000)}s before wave${attempt > 0 ? ` (attempt ${attempt + 1})` : ""}`);
+        await sleep(waitMs);
+    }
+    // Exhausted attempts — proceed anyway, swarm's internal retry will handle rejections.
+}

package/dist/swarm.d.ts

@@ -110,6 +110,8 @@ export declare class Swarm {
     private checkStall;
     private capForOverage;
     private throttle;
+    /** Returns the nearest future resetsAt from any rejected window, or undefined. */
+    private windowRejectedReset;
     private runAgent;
     private agentSummary;
     private handleMsg;

package/dist/swarm.js

@@ -377,15 +377,23 @@ export class Swarm {
             const cap = this.usageCap;
             const capExceeded = cap != null && cap < 1 && this.rateLimitUtilization >= cap;
             const rejected = this.rateLimitResetsAt && this.rateLimitResetsAt > Date.now();
-            if (!capExceeded && !rejected)
+            // Proactive: check per-window rejections even when rateLimitResetsAt isn't set
+            const windowRejected = this.windowRejectedReset();
+            // Proactive: near-critical utilization (no cap set but API is clearly strained)
+            const nearCritical = cap == null && this.rateLimitUtilization >= 0.95;
+            if (!capExceeded && !rejected && !windowRejected && !nearCritical)
                 break;
             const fallbackMs = Math.min(300_000, 60_000 * (1 + consecutiveWaits * 2));
-            const waitMs = this.rateLimitResetsAt && this.rateLimitResetsAt > Date.now()
-                ? Math.max(5000, this.rateLimitResetsAt - Date.now())
-                : fallbackMs;
+            const waitMs = (rejected || windowRejected)
+                ? Math.max(5000, (windowRejected ?? this.rateLimitResetsAt) - Date.now())
+                : nearCritical
+                    ? 30_000 * (1 + consecutiveWaits)
+                    : fallbackMs;
             const reason = capExceeded
                 ? `Usage at ${Math.round(this.rateLimitUtilization * 100)}% (cap ${Math.round(cap * 100)}%)`
-                : `Rate limited${this.windowTag()}`;
+                : nearCritical
+                    ? `Near-critical utilization ${Math.round(this.rateLimitUtilization * 100)}%`
+                    : `Rate limited${this.windowTag()}`;
             this.log(-1, `${reason}  -- waiting ${Math.ceil(waitMs / 1000)}s then retrying ([r] to retry now)`);
             this.rateLimitPaused++;
             await this.rateLimitSleep(waitMs);
@@ -398,6 +406,17 @@ export class Swarm {
                 return;
         }
     }
+    /** Returns the nearest future resetsAt from any rejected window, or undefined. */
+    windowRejectedReset() {
+        let nearest;
+        for (const w of this.rateLimitWindows.values()) {
+            if (w.status === "rejected" && w.resetsAt && w.resetsAt > Date.now()) {
+                if (!nearest || w.resetsAt < nearest)
+                    nearest = w.resetsAt;
+            }
+        }
+        return nearest;
+    }
     // ── Agent execution ──
     async runAgent(task) {
         const id = this.nextId++;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-overnight",
-  "version": "1.17.0",
+  "version": "1.17.1",
   "description": "Background lane for your Claude Max plan. Parallel Claude Agent SDK sessions in git worktrees with a usage cap that reserves headroom for your interactive Claude Code. Crash-safe resume. Opus/Sonnet/Haiku + Qwen/OpenRouter.",
   "type": "module",
   "bin": {
@@ -15,13 +15,15 @@
   },
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.2.92",
-    "chalk": "^5.4.1"
+    "chalk": "^5.4.1",
+    "jsonwebtoken": "^9.0.2"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
     "node-pty": "^1.1.0",
     "strip-ansi": "^7.1.0",
-    "typescript": "^5.7.0"
+    "typescript": "^5.7.0",
+    "@types/jsonwebtoken": "^9.0.7"
   },
   "license": "MIT",
   "author": "Francesco Fornace",

package/plugins/claude-overnight/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-overnight",
-  "version": "1.17.0",
+  "version": "1.17.1",
   "description": "Claude Code skill for understanding, installing, and inspecting claude-overnight runs  -- parallel Claude agents in git worktrees with thinking waves, multi-wave steering, and crash-safe resume.",
   "author": {
     "name": "Francesco Fornace"