claude-overnight 1.25.47 → 1.25.49

package/dist/cli/cli.d.ts

@@ -9,32 +9,11 @@ import { isJWTAuthError } from "../core/auth.js";
 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~";
 export declare const PASTE_PLACEHOLDER_MAX = 80;
-export type InputSegment = {
-    type: "text";
-    content: string;
-} | {
-    type: "paste";
-    content: string;
-};
-/** Split a raw stdin chunk into typed and pasted segments. */
-export declare function splitPaste(chunk: string): Array<{
-    type: "typed" | "paste";
-    text: string;
-}>;
-export declare function segmentsToString(segs: InputSegment[]): string;
-export declare function renderSegments(segs: InputSegment[]): string;
-export declare function appendCharToSegments(segs: InputSegment[], ch: string): void;
-/** Appends a pasted block. Short single-line pastes inline as text; the rest become placeholders. */
-export declare function appendPasteToSegments(segs: InputSegment[], text: string): void;
-/** Backspace removes one char, or an entire paste block atomically. */
-export declare function backspaceSegments(segs: InputSegment[]): void;
 /**
- * Read a line from the user with bracketed-paste awareness.
- * Pasted multi-line text stays in the buffer as a single block  -- only a typed
- * Enter submits. Falls back to cooked readline when stdin isn't a TTY.
+ * Read a line from the user with bracketed-paste awareness. Pasted multi-line
+ * text stays in the buffer as a single block  -- only a typed Enter submits.
+ * Falls back to cooked readline when stdin isn't a TTY.
  */
 export declare function ask(question: string): Promise<string>;
 export declare function select<T>(label: string, items: {

package/dist/cli/cli.js

@@ -4,6 +4,7 @@ import { resolve } from "path";
 import { createInterface } from "readline";
 import chalk from "chalk";
 import { query } from "@anthropic-ai/claude-agent-sdk";
+import { parseChunk, setBracketedPaste, deleteWordBackward } from "../ui/raw-input.js";
 // ── CLI flag parsing ──
 export function parseCliFlags(argv) {
     const known = new Set(["concurrency", "model", "timeout", "budget", "usage-cap", "extra-usage-budget", "merge"]);
@@ -66,69 +67,34 @@ export async function fetchModels(timeoutMs = 10_000) {
         return [];
     }
 }
-// ── Bracketed paste + segment-based input ──
+// ── Interactive primitives ──
 //
-// When the terminal is in bracketed paste mode, pasted content is wrapped with
-// \x1B[200~ ... \x1B[201~ so we can distinguish typed Enter from pasted newlines.
-// Multi-line or long pastes are stored as opaque segments and shown as a compact
-// [Pasted +N lines] placeholder while editing  -- the full text is substituted on submit.
-export const PASTE_START = "\x1B[200~";
-export const PASTE_END = "\x1B[201~";
+// Text entry goes through the shared raw-input parser in `../ui/raw-input.ts`,
+// which enforces the single invariant that used to be duplicated (and buggy)
+// here and in the Ink overlay:
+//   - Typed Enter = a stdin chunk that is exactly "\r", "\n", or "\r\n".
+//   - Anything else with embedded newlines is a paste, not a submit.
+// Multi-line pastes render as a compact `[Pasted +N lines]` placeholder while
+// editing — the full content is substituted on submit.
 export const PASTE_PLACEHOLDER_MAX = 80;
-/** Split a raw stdin chunk into typed and pasted segments. */
-export function splitPaste(chunk) {
-    const out = [];
-    let i = 0;
-    while (i < chunk.length) {
-        const start = chunk.indexOf(PASTE_START, i);
-        if (start === -1) {
-            out.push({ type: "typed", text: chunk.slice(i) });
-            break;
-        }
-        if (start > i)
-            out.push({ type: "typed", text: chunk.slice(i, start) });
-        const bodyStart = start + PASTE_START.length;
-        const end = chunk.indexOf(PASTE_END, bodyStart);
-        if (end === -1) {
-            out.push({ type: "paste", text: chunk.slice(bodyStart) });
-            break;
-        }
-        out.push({ type: "paste", text: chunk.slice(bodyStart, end) });
-        i = end + PASTE_END.length;
-    }
-    return out;
-}
-export function segmentsToString(segs) {
-    return segs.map((s) => s.content).join("");
-}
-export function renderSegments(segs) {
-    return segs.map((s) => {
-        if (s.type === "text")
-            return s.content;
-        const lines = s.content.split("\n").length;
-        return chalk.dim(`[Pasted +${lines} line${lines === 1 ? "" : "s"}]`);
-    }).join("");
-}
-export function appendCharToSegments(segs, ch) {
+function appendTypedChar(segs, ch) {
     const last = segs[segs.length - 1];
     if (last && last.type === "text")
         last.content += ch;
     else
         segs.push({ type: "text", content: ch });
 }
-/** Appends a pasted block. Short single-line pastes inline as text; the rest become placeholders. */
-export function appendPasteToSegments(segs, text) {
+function appendPaste(segs, text) {
     if (!text)
         return;
     const norm = text.replace(/\r\n?/g, "\n");
     if (!norm.includes("\n") && norm.length <= PASTE_PLACEHOLDER_MAX) {
-        appendCharToSegments(segs, norm);
+        appendTypedChar(segs, norm);
         return;
     }
     segs.push({ type: "paste", content: norm });
 }
-/** Backspace removes one char, or an entire paste block atomically. */
-export function backspaceSegments(segs) {
+function backspaceSegs(segs) {
     while (segs.length > 0) {
         const last = segs[segs.length - 1];
         if (last.type === "paste") {
@@ -143,14 +109,22 @@ export function backspaceSegments(segs) {
         return;
     }
 }
+function segsToString(segs) { return segs.map((s) => s.content).join(""); }
+function renderSegs(segs) {
+    return segs.map((s) => {
+        if (s.type === "text")
+            return s.content;
+        const lines = s.content.split("\n").length;
+        return chalk.dim(`[Pasted +${lines} line${lines === 1 ? "" : "s"}]`);
+    }).join("");
+}
 function stripAnsi(s) {
     return s.replace(/\x1B\[[0-9;]*[a-zA-Z]/g, "");
 }
-// ── Interactive primitives ──
 /**
- * Read a line from the user with bracketed-paste awareness.
- * Pasted multi-line text stays in the buffer as a single block  -- only a typed
- * Enter submits. Falls back to cooked readline when stdin isn't a TTY.
+ * Read a line from the user with bracketed-paste awareness. Pasted multi-line
+ * text stays in the buffer as a single block  -- only a typed Enter submits.
+ * Falls back to cooked readline when stdin isn't a TTY.
  */
 export function ask(question) {
     const { stdin, stdout } = process;
@@ -163,28 +137,25 @@ export function ask(question) {
         const tail = question.split("\n").pop() ?? "";
         const tailVisibleLen = stripAnsi(tail).length;
         let prevWrapRows = 0;
-        // Only rewrite the input line (and any wrapped continuation rows). The
-        // question header above is never touched, so redraws can't stack copies
-        // even if the initial write scrolled the viewport.
         const redraw = () => {
             const cols = stdout.columns || 80;
             if (prevWrapRows > 0)
                 stdout.write(`\x1B[${prevWrapRows}A`);
             stdout.write("\r\x1B[J");
-            const rendered = renderSegments(segs);
+            const rendered = renderSegs(segs);
             stdout.write(tail + rendered);
             const visible = tailVisibleLen + stripAnsi(rendered).length;
             prevWrapRows = visible > 0 ? Math.floor((visible - 1) / cols) : 0;
         };
         stdout.write(question);
-        stdout.write("\x1B[?2004h");
+        setBracketedPaste(stdout, true);
         try {
             stdin.setRawMode(true);
         }
         catch { }
         stdin.resume();
         const cleanup = () => {
-            stdout.write("\x1B[?2004l");
+            setBracketedPaste(stdout, false);
             try {
                 stdin.setRawMode(false);
             }
@@ -192,48 +163,44 @@ export function ask(question) {
             stdin.removeListener("data", onData);
             stdin.pause();
         };
+        const submit = () => { stdout.write("\n"); cleanup(); resolve(segsToString(segs).trim()); };
         const onData = (buf) => {
-            const chunk = buf.toString();
-            for (const seg of splitPaste(chunk)) {
-                if (seg.type === "paste") {
-                    appendPasteToSegments(segs, seg.text);
-                    redraw();
-                    continue;
-                }
-                for (let ci = 0; ci < seg.text.length; ci++) {
-                    const ch = seg.text[ci];
-                    if (ch === "\r" || ch === "\n") {
-                        stdout.write("\n");
-                        cleanup();
-                        resolve(segmentsToString(segs).trim());
-                        return;
+            for (const ev of parseChunk(buf.toString())) {
+                switch (ev.type) {
+                    case "char":
+                        appendTypedChar(segs, ev.text);
+                        break;
+                    case "paste":
+                        appendPaste(segs, ev.text);
+                        break;
+                    case "backspace":
+                        backspaceSegs(segs);
+                        break;
+                    case "word-delete": {
+                        const s = segsToString(segs);
+                        const next = deleteWordBackward(s);
+                        segs.length = 0;
+                        if (next)
+                            segs.push({ type: "text", content: next });
+                        break;
                     }
-                    if (ch === "\x03") {
+                    case "clear-line":
+                        segs.length = 0;
+                        break;
+                    case "submit":
+                        submit();
+                        return;
+                    case "cancel":
+                        submit();
+                        return; // lone ESC = submit, preserves old behavior
+                    case "interrupt":
                         cleanup();
                         stdout.write("\n");
                         process.exit(130);
-                    }
-                    if (ch === "\x7F" || ch === "\b") {
-                        backspaceSegments(segs);
-                        redraw();
-                        continue;
-                    }
-                    // ESC submits the current input (same as Enter)
-                    if (ch === "\x1B") {
-                        stdout.write("\n");
-                        cleanup();
-                        resolve(segmentsToString(segs).trim());
-                        return;
-                    }
-                    const code = ch.charCodeAt(0);
-                    if (code < 0x20)
-                        continue; // control chars
-                    if (code >= 0x7F && code < 0xA0)
-                        continue; // DEL + C1 controls
-                    appendCharToSegments(segs, ch);
+                    // tab + nav: ignore during single-line prompts
                 }
-                redraw();
             }
+            redraw();
         };
         stdin.on("data", onData);
     });

package/dist/core/_version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "1.25.47";
+export declare const VERSION = "1.25.49";

package/dist/core/_version.js

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

package/dist/ui/input.d.ts

@@ -1,13 +1,13 @@
 import React from "react";
 import type { UiStore, HostCallbacks } from "./store.js";
+import { deleteWordBackward as rawDeleteWordBackward } from "./raw-input.js";
 export declare const MAX_INPUT_LEN = 600;
 export declare const CONTROL_CHAR_RE: RegExp;
-/** Strip control characters from typed raw input so escape flushes, newlines,
- *  and C1 bytes never end up in the user's buffer. Exported for tests. */
+/** Strip control characters from typed raw input. Exported for tests. */
 export declare function sanitizeTyped(raw: string): string;
 /** Delete the previous word including any trailing whitespace, readline-style.
- *  Bound to Ctrl+W and Opt/Cmd+Backspace. Exported for tests. */
-export declare function deleteWordBackward(s: string): string;
+ *  Exported for tests. */
+export declare const deleteWordBackward: typeof rawDeleteWordBackward;
 interface Props {
     store: UiStore;
     callbacks: HostCallbacks;

package/dist/ui/input.js

@@ -1,171 +1,172 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 // Keyboard + input-overlay layer.
 //
-// `useInput` dispatches typed characters and special keys. The hotkey table
-// here is the executable mirror of the canonical footer contract:
-//   ? ask · i steer · d debrief · p pause · s settings · f fallback ·
-//   r skip-rl · q quit · arrows+0-9 for agent detail nav
+// Two input paths, chosen by `state.input.mode`:
 //
-// Text-entry overlays (steer, ask, settings) are *not* separate phases — they
-// capture typed chars, show a minimal hint in the footer (handled by
-// footer.tsx), and dispatch on Enter/Esc.
+//   - mode === "none"  → Ink's `useInput` dispatches hotkeys (?, i, d, p, s, …)
+//   - mode !== "none"  → a raw stdin tap using the shared parser in
+//                        `./raw-input.ts`. Ink's useInput is disabled while
+//                        the overlay is open so paste never gets fragmented
+//                        into per-char keypress events (which used to fire
+//                        `key.return` on any `\n` in the paste and submit).
 //
-// Text-entry input hygiene: terminals send a zoo of escape/control sequences
-// for navigation keys (arrows, cmd+arrow → ctrl+a/e on macOS, option+letter,
-// pageup/pgdn, home/end, lone ESC flushes). We explicitly swallow all of them
-// instead of letting them fall through to the "typed char" branch, which used
-// to corrupt the buffer or dismiss the overlay and discard unfinished text.
-import { useState, useSyncExternalStore } from "react";
-import { Text, Box, useInput } from "ink";
+// The shared parser is the same one `cli.ts` `ask()` uses, so preflight
+// prompts and in-run overlays behave identically: typed Enter = a stdin chunk
+// that's exactly "\r"/"\n"/"\r\n"; anything else with embedded newlines is a
+// paste, not a submit.
+import { useEffect, useState, useSyncExternalStore } from "react";
+import { Text, Box, useInput, useStdin } from "ink";
 import chalk from "chalk";
 import { visibleLen, wrap } from "./primitives.js";
 import { SETTINGS_FIELDS, SETTINGS_LABELS, NUMERIC_SETTINGS_FIELDS, applySettingEdit, readSettingValue, } from "./settings.js";
+import { parseChunk, setBracketedPaste, deleteWordBackward as rawDeleteWordBackward } from "./raw-input.js";
 export const MAX_INPUT_LEN = 600;
-// Any printable char is kept verbatim; everything else is filtered out before
-// touching the buffer. Matches: ASCII C0 controls (0x00-0x1F), DEL (0x7F), C1
-// controls (0x80-0x9F), and lone ESC (already handled by `key.escape`).
+// Kept for backwards compatibility with existing tests. Matches C0, DEL, C1.
 export const CONTROL_CHAR_RE = /[\x00-\x1f\x7f-\x9f]/g;
-/** Strip control characters from typed raw input so escape flushes, newlines,
- *  and C1 bytes never end up in the user's buffer. Exported for tests. */
+/** Strip control characters from typed raw input. Exported for tests. */
 export function sanitizeTyped(raw) {
     return raw.replace(CONTROL_CHAR_RE, "");
 }
 /** Delete the previous word including any trailing whitespace, readline-style.
- *  Bound to Ctrl+W and Opt/Cmd+Backspace. Exported for tests. */
-export function deleteWordBackward(s) {
-    const trimmed = s.replace(/\s+$/, "");
-    const idx = trimmed.search(/\S+$/);
-    return idx < 0 ? "" : trimmed.slice(0, idx);
-}
+ *  Exported for tests. */
+export const deleteWordBackward = rawDeleteWordBackward;
 export function InputLayer({ store, callbacks, onToast }) {
     const [buffer, setBuffer] = useState("");
     const [settingsField, setSettingsField] = useState(0);
-    useInput((raw, key) => {
-        const state = store.get();
-        const mode = state.input.mode;
-        const swarm = state.swarm;
-        const lc = state.liveConfig;
-        // ── Text-entry modes ──
-        if (mode !== "none") {
-            // Navigation keys must NEVER touch the buffer or dismiss the overlay.
-            // (Bug: cmd+arrow on macOS Terminal sends ctrl+a/ctrl+e which used to
-            // leak through and append "a"/"e"; arrows on some terminals flushed
-            // partial ESC sequences that dropped the user's unfinished text.)
-            if (key.upArrow || key.downArrow || key.leftArrow || key.rightArrow ||
-                key.pageUp || key.pageDown || key.home || key.end)
+    const state = useSyncExternalStore(store.subscribe, store.get, store.get);
+    const mode = state.input.mode;
+    const textEntry = mode !== "none";
+    // ── Text-entry path: raw stdin tap via the shared parser ──
+    const { stdin, setRawMode, isRawModeSupported } = useStdin();
+    useEffect(() => {
+        if (!textEntry || !stdin || !isRawModeSupported)
+            return;
+        setRawMode(true);
+        setBracketedPaste(process.stdout, true);
+        // Snapshot the overlay-relevant state locally; callbacks always pull the
+        // latest live state via `store.get()` on each event.
+        const onData = (buf) => {
+            const cur = store.get();
+            const m = cur.input.mode;
+            if (m === "none")
                 return;
-            // Esc bails (loses the buffer — always intentional).
-            if (key.escape) {
+            const swarm = cur.swarm;
+            const lc = cur.liveConfig;
+            const closeOverlay = () => {
                 setBuffer("");
                 setSettingsField(0);
                 store.patch({ input: { mode: "none", buffer: "", settingsField: 0 } });
-                return;
-            }
-            if (key.return) {
-                const text = buffer.trim();
-                if (mode === "steer" && text)
-                    callbacks.onSteer(text);
-                else if (mode === "ask" && text)
-                    callbacks.onAsk(text);
-                else if (mode === "settings") {
-                    const field = SETTINGS_FIELDS[settingsField % SETTINGS_FIELDS.length];
-                    if (lc)
-                        applySettingEdit(field, text, lc, swarm);
-                    callbacks.settingsTick();
-                    const next = settingsField + 1;
-                    setBuffer("");
-                    if (next >= SETTINGS_FIELDS.length) {
-                        setSettingsField(0);
-                        store.patch({ input: { mode: "none", buffer: "", settingsField: 0 } });
-                    }
-                    else {
-                        setSettingsField(next);
-                        store.patch({ input: { mode: "settings", buffer: "", settingsField: next } });
-                    }
-                    return;
-                }
+            };
+            const advanceSettings = () => {
+                const next = settingsField + 1;
                 setBuffer("");
-                setSettingsField(0);
-                store.patch({ input: { mode: "none", buffer: "", settingsField: 0 } });
-                return;
-            }
-            // Word-delete: option/alt + backspace — expected on macOS.
-            if ((key.meta || key.ctrl) && (key.backspace || key.delete)) {
-                const next = deleteWordBackward(buffer);
-                setBuffer(next);
-                store.patch({ input: { ...state.input, buffer: next } });
-                return;
-            }
-            // Swallow modifier combos so they can't leak as stray letters.
-            // (cmd+→ on macOS Terminal = \x05 = ctrl+e → input handler sees raw='e';
-            // without this guard we used to append 'e'.)
-            if (key.ctrl || key.meta) {
-                if (mode !== "settings" && key.ctrl && raw === "u") {
-                    // ctrl+U: clear the whole line — standard readline behavior.
-                    setBuffer("");
-                    store.patch({ input: { ...state.input, buffer: "" } });
-                    return;
+                if (next >= SETTINGS_FIELDS.length) {
+                    setSettingsField(0);
+                    store.patch({ input: { mode: "none", buffer: "", settingsField: 0 } });
                 }
-                if (key.ctrl && raw === "w") {
-                    const next = deleteWordBackward(buffer);
-                    setBuffer(next);
-                    store.patch({ input: { ...state.input, buffer: next } });
-                    return;
+                else {
+                    setSettingsField(next);
+                    store.patch({ input: { mode: "settings", buffer: "", settingsField: next } });
                 }
-                return;
-            }
-            if (key.tab) {
-                if (mode === "settings") {
-                    const field = SETTINGS_FIELDS[settingsField % SETTINGS_FIELDS.length];
-                    if (field === "pause" && swarm && lc) {
-                        const next = !swarm.paused;
-                        swarm.setPaused(next);
-                        lc.paused = next;
-                        lc.dirty = true;
-                        callbacks.settingsTick();
-                    }
-                    const next = settingsField + 1;
-                    setBuffer("");
-                    if (next >= SETTINGS_FIELDS.length) {
-                        setSettingsField(0);
-                        store.patch({ input: { mode: "none", buffer: "", settingsField: 0 } });
+            };
+            for (const ev of parseChunk(buf.toString())) {
+                switch (ev.type) {
+                    case "cancel":
+                        closeOverlay();
+                        return;
+                    case "interrupt":
+                        // Treat ^C inside overlay as cancel, not process exit.
+                        closeOverlay();
+                        return;
+                    case "submit": {
+                        const text = buffer.trim();
+                        if (m === "steer" && text)
+                            callbacks.onSteer(text);
+                        else if (m === "ask" && text)
+                            callbacks.onAsk(text);
+                        else if (m === "settings") {
+                            const field = SETTINGS_FIELDS[settingsField % SETTINGS_FIELDS.length];
+                            if (lc)
+                                applySettingEdit(field, text, lc, swarm);
+                            callbacks.settingsTick();
+                            advanceSettings();
+                            return;
+                        }
+                        closeOverlay();
+                        return;
                     }
-                    else {
-                        setSettingsField(next);
-                        store.patch({ input: { mode: "settings", buffer: "", settingsField: next } });
+                    case "tab":
+                        if (m === "settings") {
+                            const field = SETTINGS_FIELDS[settingsField % SETTINGS_FIELDS.length];
+                            if (field === "pause" && swarm && lc) {
+                                const next = !swarm.paused;
+                                swarm.setPaused(next);
+                                lc.paused = next;
+                                lc.dirty = true;
+                                callbacks.settingsTick();
+                            }
+                            advanceSettings();
+                        }
+                        break;
+                    case "backspace":
+                        setBuffer((prev) => {
+                            const next = prev.slice(0, -1);
+                            store.patch({ input: { ...store.get().input, buffer: next } });
+                            return next;
+                        });
+                        break;
+                    case "word-delete":
+                        setBuffer((prev) => {
+                            const next = rawDeleteWordBackward(prev);
+                            store.patch({ input: { ...store.get().input, buffer: next } });
+                            return next;
+                        });
+                        break;
+                    case "clear-line":
+                        if (m !== "settings") {
+                            setBuffer("");
+                            store.patch({ input: { ...store.get().input, buffer: "" } });
+                        }
+                        break;
+                    case "nav":
+                        // Navigation keys are a no-op inside the overlay. Used to leak
+                        // as stray letters because cmd+→ on macOS sends ctrl+e.
+                        break;
+                    case "char":
+                    case "paste": {
+                        let text = ev.type === "paste" ? ev.text.replace(/\r\n?/g, "\n") : ev.text;
+                        // Settings mode is single-line and numeric fields are digits-only.
+                        if (m === "settings") {
+                            const field = SETTINGS_FIELDS[settingsField % SETTINGS_FIELDS.length];
+                            if (field === "pause")
+                                break;
+                            if (NUMERIC_SETTINGS_FIELDS.has(field))
+                                text = text.replace(/[^0-9.]/g, "");
+                            text = text.replace(/\n/g, " ");
+                        }
+                        if (!text)
+                            break;
+                        setBuffer((prev) => {
+                            const next = (prev + text).slice(0, MAX_INPUT_LEN);
+                            store.patch({ input: { ...store.get().input, buffer: next } });
+                            return next;
+                        });
+                        break;
                     }
                 }
-                // Tab in steer/ask modes is a no-op, not a submit or a "tab character".
-                return;
-            }
-            if (key.backspace || key.delete) {
-                const next = buffer.slice(0, -1);
-                setBuffer(next);
-                store.patch({ input: { ...state.input, buffer: next } });
-                return;
-            }
-            // Typed printable char(s) — raw is the string for this event. Strip any
-            // control chars (lone ESC flushes, \n linefeeds parseKeypress labels as
-            // 'enter', partial ESC [ sequences) before touching the buffer.
-            if (raw && raw.length > 0) {
-                let text = sanitizeTyped(raw);
-                if (mode === "settings") {
-                    const field = SETTINGS_FIELDS[settingsField % SETTINGS_FIELDS.length];
-                    if (NUMERIC_SETTINGS_FIELDS.has(field))
-                        text = text.replace(/[^0-9.]/g, "");
-                    if (field === "pause")
-                        return;
-                }
-                if (!text)
-                    return;
-                const next = (buffer + text).slice(0, MAX_INPUT_LEN);
-                setBuffer(next);
-                store.patch({ input: { ...state.input, buffer: next } });
             }
-            return;
-        }
-        // ── Hotkey mode ──
-        // Arrow keys — agent detail cycle
+        };
+        stdin.on("data", onData);
+        return () => {
+            stdin.off("data", onData);
+            setBracketedPaste(process.stdout, false);
+        };
+    }, [textEntry, stdin, setRawMode, isRawModeSupported, buffer, settingsField, store, callbacks]);
+    // ── Hotkey path: Ink's useInput, only active when no overlay is open ──
+    useInput((raw, key) => {
+        const s = store.get();
+        const swarm = s.swarm;
+        const lc = s.liveConfig;
         if (key.rightArrow || key.downArrow) {
             callbacks.cycleAgent(1);
             return;
@@ -178,19 +179,17 @@ export function InputLayer({ store, callbacks, onToast }) {
             callbacks.clearSelectedAgent();
             return;
         }
-        // Escape in hotkey mode — clear agent selection or dismiss answered ask
         if (key.escape) {
-            if (state.selectedAgentId != null) {
+            if (s.selectedAgentId != null) {
                 callbacks.clearSelectedAgent();
                 return;
             }
-            if (state.ask && !state.ask.streaming) {
+            if (s.ask && !s.ask.streaming) {
                 callbacks.clearAsk();
                 return;
             }
             return;
         }
-        // Ctrl-C: abort swarm or exit
         if (key.ctrl && raw === "c") {
             if (swarm && !swarm.aborted) {
                 swarm.abort();
@@ -198,9 +197,8 @@ export function InputLayer({ store, callbacks, onToast }) {
             }
             process.exit(0);
         }
-        // Enter in hotkey mode — reveal ask answer file in Finder if we have one
         if (key.return) {
-            if (state.askTempFileAvailable)
+            if (s.askTempFileAvailable)
                 callbacks.openAskTempFile();
             return;
         }
@@ -209,18 +207,16 @@ export function InputLayer({ store, callbacks, onToast }) {
         const code = raw.charCodeAt(0);
         if (code < 0x20 || code > 0x7E)
             return;
-        // Any ctrl/meta combo (that isn't one of the specific hotkeys above) is
-        // nav-adjacent on most terminals; ignore instead of matching "c"/"i" etc.
         if (key.ctrl || key.meta)
             return;
         const toast = (msg) => onToast(msg);
         switch (raw.toLowerCase()) {
             case "?":
-                if (!state.hasOnAsk)
+                if (!s.hasOnAsk)
                     return toast("Ask not wired for this run");
-                if (state.askBusy || state.ask?.streaming)
+                if (s.askBusy || s.ask?.streaming)
                     return toast("Ask already in flight");
-                if (state.ask && !state.ask.streaming) {
+                if (s.ask && !s.ask.streaming) {
                     callbacks.clearAsk();
                     return;
                 }
@@ -228,17 +224,16 @@ export function InputLayer({ store, callbacks, onToast }) {
                 setBuffer("");
                 return;
             case "i":
-                if (!state.hasOnSteer)
+                if (!s.hasOnSteer)
                     return toast("Steering not wired for this run");
                 store.patch({ input: { mode: "steer", buffer: "", settingsField: 0 } });
                 setBuffer("");
                 return;
             case "d":
-                // Show latest debrief entry in the overlay; if nothing yet, toast.
-                if (state.debrief)
-                    return; // already visible
-                if (state.debriefHistory.length > 0) {
-                    const last = state.debriefHistory[state.debriefHistory.length - 1];
+                if (s.debrief)
+                    return;
+                if (s.debriefHistory.length > 0) {
+                    const last = s.debriefHistory[s.debriefHistory.length - 1];
                     store.patch({ debrief: { text: last.text, label: last.label } });
                     return;
                 }
@@ -270,11 +265,8 @@ export function InputLayer({ store, callbacks, onToast }) {
                 swarm.retryRateLimitNow();
                 return;
             case "q":
-                // Second press with the current swarm already aborted = hard exit.
                 if (swarm?.aborted)
                     process.exit(0);
-                // Always request quit: flips the runner's `stopping` flag so the wave
-                // loop breaks instead of advancing to steering / post-run review.
                 callbacks.requestQuit();
                 return;
         }
@@ -284,9 +276,7 @@ export function InputLayer({ store, callbacks, onToast }) {
             if (n < running.length)
                 callbacks.selectAgent(running[n].id);
         }
-    });
-    // Render the active text-entry prompt under the footer hint.
-    const state = useSyncExternalStore(store.subscribe, store.get, store.get);
+    }, { isActive: !textEntry });
     if (state.input.mode === "none")
         return null;
     const caretOn = state.tick % 2 === 0;
@@ -305,7 +295,7 @@ function InputPrompt({ mode, buffer, settingsField, state, caretOn }) {
     let subtitle;
     let hint;
     let currentLine = null;
-    let filteredBuffer = buffer;
+    const filteredBuffer = buffer;
     if (mode === "settings") {
         const total = SETTINGS_FIELDS.length;
         const field = SETTINGS_FIELDS[settingsField % total];
@@ -323,13 +313,11 @@ function InputPrompt({ mode, buffer, settingsField, state, caretOn }) {
         const action = mode === "steer" ? "queue" : "send";
         hint = chalk.dim(`Enter ${action} \u00b7 Esc cancel \u00b7 Ctrl+U clear \u00b7 Ctrl+W del word`);
     }
-    // Word-wrap the buffer so long entries don't blow past the box edge.
     const bufferLines = filteredBuffer.length === 0
         ? [""]
         : wrap(filteredBuffer, Math.max(20, innerW));
     const caret = caretOn ? accent("\u2588") : " ";
     const lastIdx = bufferLines.length - 1;
-    // Char counter — dims normally, warns at 80%, red at 95%.
     const pct = buffer.length / MAX_INPUT_LEN;
     const counter = buffer.length === 0 ? "" :
         pct >= 0.95 ? chalk.red(`${buffer.length}/${MAX_INPUT_LEN}`)

package/dist/ui/raw-input.d.ts

@@ -0,0 +1,38 @@
+export type InputEvent = {
+    type: "char";
+    text: string;
+} | {
+    type: "paste";
+    text: string;
+} | {
+    type: "backspace";
+} | {
+    type: "word-delete";
+} | {
+    type: "clear-line";
+} | {
+    type: "submit";
+} | {
+    type: "cancel";
+} | {
+    type: "interrupt";
+} | {
+    type: "tab";
+} | {
+    type: "nav";
+    name: "up" | "down" | "left" | "right" | "home" | "end" | "pgup" | "pgdn";
+};
+export declare const PASTE_START = "\u001B[200~";
+export declare const PASTE_END = "\u001B[201~";
+export declare function sanitize(raw: string): string;
+/** Split a chunk into events. Honors bracketed paste, detects paste-by-shape
+ *  (multi-byte chunk containing newlines), and cleanly consumes escape
+ *  sequences without leaking their terminator as a typed char. */
+export declare function parseChunk(chunk: string): InputEvent[];
+/** Enable/disable bracketed paste on the given stdout. Best-effort — terminals
+ *  that don't support it simply ignore the sequence, and `parseChunk`'s
+ *  shape-based paste detection covers them. */
+export declare function setBracketedPaste(stdout: NodeJS.WriteStream, enabled: boolean): void;
+/** Readline-style word delete: strip trailing whitespace, then strip the last
+ *  non-whitespace run. */
+export declare function deleteWordBackward(s: string): string;

package/dist/ui/raw-input.js

@@ -0,0 +1,241 @@
+// Shared raw-stdin parser for text entry.
+//
+// Single source of truth for what a chunk from stdin means. Used by both the
+// Ink overlay (src/ui/input.tsx) during a run and the preflight `ask()` prompt
+// (src/cli/cli.ts) before a run. Fixes two classes of bugs that existed in
+// both copies:
+//
+//   1. "@ triggered send" — CSI/SS3 terminator check was `< 0x7E` (missed `~`)
+//      and the ESC+printable branch silently dropped the next char.
+//   2. "paste with newline sent early" — Ink's useInput fragments multi-byte
+//      chunks into per-char keypress events, firing key.return on any `\n` in
+//      a paste. Here we keep the whole chunk and decide paste-vs-typed-enter
+//      by whether the chunk is exactly a newline (typed) or contains
+//      newlines alongside other bytes (pasted).
+//
+// The parser is pure: takes a string chunk, returns an ordered event list.
+// Bracketed-paste markers are honored when present but we don't rely on them.
+export const PASTE_START = "\x1B[200~";
+export const PASTE_END = "\x1B[201~";
+// Control chars to strip from any text we append to a buffer. Matches C0
+// (0x00-0x1F), DEL (0x7F), and C1 (0x80-0x9F). Newlines are kept — the caller
+// decides per segment whether to strip or preserve them.
+const CONTROL_STRIP_RE = /[\x00-\x08\x0B\x0C\x0E-\x1F\x7F-\x9F]/g;
+export function sanitize(raw) {
+    return raw.replace(CONTROL_STRIP_RE, "");
+}
+// CSI/SS3 final byte is in the range 0x40..0x7E inclusive. (The old code used
+// `< 0x7E` which dropped past the `~` terminator used by function keys and
+// the bracketed-paste close marker.)
+function isCsiFinal(code) {
+    return code >= 0x40 && code <= 0x7E;
+}
+// Recognized CSI/SS3 sequences for navigation. Anything else with a valid
+// CSI/SS3 shape is silently consumed.
+function csiToNav(body) {
+    // body = everything between ESC[ (or ESCO) and the terminator, plus terminator
+    // Common sequences: A=up, B=down, C=right, D=left, H=home, F=end,
+    //                   5~=pgup, 6~=pgdn, 1~/7~=home, 4~/8~=end
+    if (body === "A")
+        return { type: "nav", name: "up" };
+    if (body === "B")
+        return { type: "nav", name: "down" };
+    if (body === "C")
+        return { type: "nav", name: "right" };
+    if (body === "D")
+        return { type: "nav", name: "left" };
+    if (body === "H" || body === "1~" || body === "7~")
+        return { type: "nav", name: "home" };
+    if (body === "F" || body === "4~" || body === "8~")
+        return { type: "nav", name: "end" };
+    if (body === "5~")
+        return { type: "nav", name: "pgup" };
+    if (body === "6~")
+        return { type: "nav", name: "pgdn" };
+    return null;
+}
+/** Split a chunk into events. Honors bracketed paste, detects paste-by-shape
+ *  (multi-byte chunk containing newlines), and cleanly consumes escape
+ *  sequences without leaking their terminator as a typed char. */
+export function parseChunk(chunk) {
+    const out = [];
+    if (!chunk)
+        return out;
+    // First pass: carve out bracketed-paste blocks. Everything outside those
+    // markers is "free text" — we still apply shape-based paste detection to it.
+    const parts = [];
+    let i = 0;
+    while (i < chunk.length) {
+        const ps = chunk.indexOf(PASTE_START, i);
+        if (ps === -1) {
+            parts.push({ kind: "free", text: chunk.slice(i) });
+            break;
+        }
+        if (ps > i)
+            parts.push({ kind: "free", text: chunk.slice(i, ps) });
+        const bodyStart = ps + PASTE_START.length;
+        const pe = chunk.indexOf(PASTE_END, bodyStart);
+        if (pe === -1) {
+            parts.push({ kind: "paste", text: chunk.slice(bodyStart) });
+            break;
+        }
+        parts.push({ kind: "paste", text: chunk.slice(bodyStart, pe) });
+        i = pe + PASTE_END.length;
+    }
+    for (const part of parts) {
+        if (part.kind === "paste") {
+            if (part.text)
+                out.push({ type: "paste", text: part.text });
+            continue;
+        }
+        // Free text: walk byte by byte, consuming escape sequences and control
+        // bytes. Typed enter = a chunk that's EXACTLY "\r", "\n", or "\r\n".
+        const s = part.text;
+        if (!s)
+            continue;
+        // Fast path: a chunk that is just enter, tab, backspace, or ^C.
+        if (s === "\r" || s === "\n" || s === "\r\n") {
+            out.push({ type: "submit" });
+            continue;
+        }
+        if (s === "\x03") {
+            out.push({ type: "interrupt" });
+            continue;
+        }
+        if (s === "\x7F" || s === "\b") {
+            out.push({ type: "backspace" });
+            continue;
+        }
+        if (s === "\t") {
+            out.push({ type: "tab" });
+            continue;
+        }
+        if (s === "\x1B") {
+            out.push({ type: "cancel" });
+            continue;
+        }
+        if (s === "\x15") {
+            out.push({ type: "clear-line" });
+            continue;
+        } // ^U
+        if (s === "\x17") {
+            out.push({ type: "word-delete" });
+            continue;
+        } // ^W
+        // Shape-based paste: multi-char chunk containing a newline that is NOT
+        // just "\r\n". Terminals buffer keypresses at ~1 byte; paste comes in as
+        // a single large chunk. Anything multi-char with embedded newlines is
+        // paste, not a sequence of typed Enters.
+        if ((s.includes("\n") || s.includes("\r")) && s.length > 2) {
+            const stripped = s.replace(/\r/g, "");
+            if (stripped)
+                out.push({ type: "paste", text: stripped });
+            continue;
+        }
+        // Otherwise walk the chunk one logical token at a time.
+        let j = 0;
+        let buf = "";
+        const flushBuf = () => { if (buf) {
+            out.push({ type: "char", text: buf });
+            buf = "";
+        } };
+        while (j < s.length) {
+            const ch = s[j];
+            if (ch === "\r" || ch === "\n") {
+                // Bare newline embedded inside a short non-paste chunk: treat as
+                // submit if it's the tail, otherwise drop (shouldn't happen in well-
+                // formed terminal input — paste goes through the shape path above).
+                flushBuf();
+                out.push({ type: "submit" });
+                j++;
+                continue;
+            }
+            if (ch === "\x03") {
+                flushBuf();
+                out.push({ type: "interrupt" });
+                j++;
+                continue;
+            }
+            if (ch === "\x7F" || ch === "\b") {
+                flushBuf();
+                out.push({ type: "backspace" });
+                j++;
+                continue;
+            }
+            if (ch === "\t") {
+                flushBuf();
+                out.push({ type: "tab" });
+                j++;
+                continue;
+            }
+            if (ch === "\x15") {
+                flushBuf();
+                out.push({ type: "clear-line" });
+                j++;
+                continue;
+            }
+            if (ch === "\x17") {
+                flushBuf();
+                out.push({ type: "word-delete" });
+                j++;
+                continue;
+            }
+            if (ch === "\x1B") {
+                flushBuf();
+                const next = j + 1 < s.length ? s[j + 1] : null;
+                if (next === null) {
+                    out.push({ type: "cancel" });
+                    j++;
+                    continue;
+                }
+                if (next === "[" || next === "O") {
+                    // CSI or SS3: consume up to and including the final byte (0x40..0x7E).
+                    let k = j + 2;
+                    let body = "";
+                    while (k < s.length) {
+                        const code = s.charCodeAt(k);
+                        body += s[k];
+                        k++;
+                        if (isCsiFinal(code))
+                            break;
+                    }
+                    const nav = csiToNav(body);
+                    if (nav)
+                        out.push(nav);
+                    j = k;
+                    continue;
+                }
+                // ESC + printable = Meta/Alt + key. Drop both bytes; upstream can
+                // surface specific combos later if needed.
+                j += 2;
+                continue;
+            }
+            const code = ch.charCodeAt(0);
+            // Skip remaining control bytes silently.
+            if (code < 0x20 || (code >= 0x7F && code < 0xA0)) {
+                j++;
+                continue;
+            }
+            buf += ch;
+            j++;
+        }
+        flushBuf();
+    }
+    return out;
+}
+/** Enable/disable bracketed paste on the given stdout. Best-effort — terminals
+ *  that don't support it simply ignore the sequence, and `parseChunk`'s
+ *  shape-based paste detection covers them. */
+export function setBracketedPaste(stdout, enabled) {
+    try {
+        stdout.write(enabled ? "\x1B[?2004h" : "\x1B[?2004l");
+    }
+    catch { }
+}
+/** Readline-style word delete: strip trailing whitespace, then strip the last
+ *  non-whitespace run. */
+export function deleteWordBackward(s) {
+    const trimmed = s.replace(/\s+$/, "");
+    const idx = trimmed.search(/\S+$/);
+    return idx < 0 ? "" : trimmed.slice(0, idx);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-overnight",
-  "version": "1.25.47",
+  "version": "1.25.49",
   "description": "Parallel Claude agents in git worktrees with a usage cap that reserves headroom for your interactive Claude Code. Crash-safe resume. Provider-agnostic model catalog (Anthropic, Cursor, OpenAI, Gemini, DeepSeek, Llama, Qwen) with capability-based task scoping.",
   "type": "module",
   "bin": {

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

@@ -1,6 +1,6 @@
 {
   "name": "claude-overnight",
-  "version": "1.25.47",
+  "version": "1.25.49",
   "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. Supports Cursor API Proxy, Qwen, OpenRouter.",
   "author": {
     "name": "Francesco Fornace"

package/plugins/claude-overnight/skills/claude-overnight/SKILL.md

@@ -1,12 +1,13 @@
 ---
 name: claude-overnight
 description: >
-  Understand, install, and inspect claude-overnight runs  -- a CLI that
+  Understand, author, install, and inspect claude-overnight runs  -- a CLI that
   launches parallel Claude agents in git worktrees with thinking waves,
-  multi-wave steering, three-layer review, and crash-safe resume. Use when the user mentions
-  claude-overnight, a `.claude-overnight/` folder, an "overnight" or
-  "swarm" run, or asks to check status / resume / continue a
-  multi-phase plan. Not for Vercel Workflow DevKit.
+  multi-wave steering, three-layer review, and crash-safe resume. Use when the user
+  mentions claude-overnight, a `.claude-overnight/` folder, an "overnight" or
+  "swarm" run, asks to check status / resume / continue a multi-phase plan,
+  or asks to plan / design / write a `tasks.json` / objective / overnight workflow.
+  Not for Vercel Workflow DevKit.
 ---
 
 # What it is
@@ -49,6 +50,15 @@ Live keys while running: `b` change budget · `t` change usage cap · `q` gracef
 
 Exit codes: `0` all ok · `1` some failed · `2` all/none.
 
+# Authoring a run (tasks.json / objective)
+
+When the user asks you to *plan*, *design*, or *write* an overnight run (not inspect one), load the authoring knowledge **on demand** — don't carry it by default:
+
+- `recipes.md` (next to this file) — scenario → recipe matrix: objective shape, `flexiblePlan`, initial tasks, `concurrency`, budget range, planner/worker pairing, phases to skip. Read this when picking a run shape for a known scenario (refactor, feature batch, migration, test/docs sprint, bug hunt, research).
+- `authoring.md` (next to this file) — decision tree (fixed vs flex vs inline; when to `--no-flex`; when thinking wave is wasted), pre-flight critic checklist (no "do anything" prompts, language-agnostic phrasing, verify-before-done, budget ≥ per-wave cost × expected waves, decomposition sanity), and anti-patterns. Read this before finalizing any tasks.json or before pressing Run.
+
+Rule of thumb: if the user has a concrete list of tasks and a clear endpoint, prefer fixed-plan (`--no-flex`) and skip the thinking wave. If the user has a fuzzy objective ("modernize X", "audit Y"), prefer `objective + flexiblePlan: true` with a small seed task list and let steering drive. Never send a single "do anything" prompt to one agent — decompose first (see authoring.md).
+
 # On-disk layout (this is how you inspect status)
 
 Every run lives at `<repo>/.claude-overnight/runs/<ISO-timestamp>/`:

package/plugins/claude-overnight/skills/claude-overnight/authoring.md

@@ -0,0 +1,107 @@
+# Authoring a claude-overnight Run
+
+Read this before finalizing a `tasks.json` or telling the user to press Run. Pair with `recipes.md` for the scenario matrix.
+
+## Decision tree
+
+1. **Does the user have a concrete list of tasks with a clear endpoint?**
+   - Yes → **fixed plan**: `tasks.json` with explicit `tasks[]`, `--no-flex`, skip thinking wave (auto-skipped below budget 15; for higher budgets pass a pre-written `tasks.json` — the CLI will not re-plan).
+   - No → continue.
+
+2. **Is the objective fuzzy ("modernize", "audit", "clean up", "make it amazing")?**
+   - Yes → **flex plan**: `objective` + `flexiblePlan: true` + 2–5 seed tasks. Let the thinking wave explore and steering drive. Budget ≥ 30.
+   - No but also not concrete → write 3–5 seed tasks you *know* are needed, enable flex, and let steering add the rest.
+
+3. **Is this a single-wave mechanical job (docs, formatting, coverage fill)?**
+   - Yes → `--no-flex`, skip thinking, low-cost worker (Qwen or Sonnet), high concurrency OK.
+
+4. **Is this a shared-surface problem (migration, bug hunt, one-file refactor)?**
+   - Yes → low concurrency (2–4). Merge conflicts dominate otherwise.
+
+5. **Does completion require running the app (not just reading code)?**
+   - Yes → task prompts must *explicitly* instruct run-and-test. Add `afterWave` hook to run tests. See *verify-before-done* below.
+
+## Pre-flight critic checklist
+
+Walk the proposed run against each item before Run. One fail = revise.
+
+### Task shape
+- [ ] **No "do anything" prompts.** Every task names a scope (files, module, feature) and a concrete outcome. If a task reads "improve X", decompose it first.
+- [ ] **Language-agnostic phrasing.** Don't bake in `npm`, `jest`, `pnpm`, etc., in the objective unless the repo is pinned to them. Shape meta-prompts ("run the project's test suite"), not tool names.
+- [ ] **Verify-before-done.** Each task that changes behavior must include "run and test the change" — not just "edit the code". For UI tasks, require browser verification (Playwright MCP). For backend, require the test suite or a repro script.
+- [ ] **Decomposition is real.** If a task is >1 day of human work, split. If two tasks touch the same file heavily, merge or serialize (low concurrency).
+- [ ] **One outcome per task.** No "refactor auth AND add tests AND update docs" — that's three tasks.
+
+### Budget & economics
+- [ ] **Budget ≥ per-wave cost × expected waves.** For flex runs, expect 3–6 waves. Per-wave cost = planner (~$1–3) + tasks × worker cost.
+- [ ] **Thinking wave justified.** Skip if tasks are already concrete or budget < 15. Thinking at budget=2000 costs $15–40 — worth it only for genuine exploration.
+- [ ] **Planner isn't cheaped out.** Planner quality = run quality ceiling. Opus for high-stakes, Sonnet for everyday, never Qwen for planner.
+- [ ] **Usage cap set.** Default 90% leaves headroom for interactive Claude. `--allow-extra-usage` off unless the user explicitly opts in, and only with `--extra-usage-budget=N`.
+
+### Environment & safety
+- [ ] **Clean git tree** (or user has explicitly OK'd uncommitted changes being swept into worktrees).
+- [ ] **`.claude-overnight/` in `.gitignore`** (with trailing slash — the `.md` log file at repo root stays committable).
+- [ ] **Required env / keys present.** API keys, DB URLs, auth tokens — if the worker needs them, the repo's `.env` must have them (worktrees inherit).
+- [ ] **MCP servers configured** for parallel Playwright (one `--isolated` entry per concurrency slot, or shared `--isolated --headless` if no login needed).
+- [ ] **Hooks don't abort the run.** `beforeWave`/`afterWave`/`afterRun` failures surface but never stop — make sure that's what the user wants.
+
+### Circuit-breaker awareness
+- [ ] **User knows to watch for 2 consecutive zero-file-change waves** — that's the halt signal. Silent try/catch in wave loops is a landmine; if the run looks "busy but unchanged", stop it.
+- [ ] **First-attempt failure mitigation.** First planner call is expensive ($2–4). If the objective can be expressed as concrete tasks, skip the planner entirely.
+
+## Common anti-patterns
+
+### The "overnight hail-mary"
+User dumps a vague wish + $1000 budget + flex + max concurrency and walks away. Output: 200 worktrees, 50 merge conflicts, no coherent diff, $400 of steering context-shuffling.
+**Fix:** decompose the wish into 5–10 seed tasks, start at budget=50, verify the first wave delivers before topping up (live `b` key).
+
+### The "single agent, do everything"
+One task prompt: "refactor the whole auth system". One agent touches 40 files, simplify pass can't review a sprawl, merge succeeds but the result is incoherent.
+**Fix:** decompose into per-surface tasks (middleware, session store, tokens, tests). Let steering add integration work.
+
+### The "verification theater"
+Tasks say "add tests" but don't say "run them". Agent writes plausible-looking tests that don't compile. Final gate catches it — but 10 waves in.
+**Fix:** every behavior-changing task ends with "run the test suite and ensure it passes". `afterWave: "pnpm test"` adds a safety net.
+
+### The "wrong tool for the job"
+Using flex mode for a mechanical docs sprint — planner burns budget steering a problem that needs no steering.
+**Fix:** `--no-flex` for mechanical work.
+
+### The "proxied model mystery"
+Worker is on Cursor proxy. User wonders why there are no thinking deltas in transcripts.
+**Fix:** expected behavior — Cursor proxy suppresses thinking phase (see README table). Don't chase it.
+
+## Writing a good objective (for flex runs)
+
+Structure: `<verb> <scope> so that <outcome / quality bar>`.
+
+Good:
+- "Modernize the auth system so that session tokens meet SOC2 storage requirements and existing flows continue to work."
+- "Raise test coverage in `packages/api` to >80% line coverage, prioritizing error paths and boundary cases."
+
+Bad:
+- "Make the code better." → no scope, no outcome.
+- "Do whatever needs doing on auth." → no quality bar.
+- "Refactor everything and add features." → two objectives.
+
+The `goal.md` file lets steering evolve the "north star" — but it can only evolve a seed that's already grounded. A vague seed stays vague.
+
+## Writing good seed tasks (flex mode)
+
+Each seed should:
+1. Name a scope (file, module, feature, package).
+2. Name an outcome (what "done" looks like).
+3. Be independently verifiable (a test, a build step, a visible UI change).
+4. Not overlap heavily with siblings (otherwise serialize or drop concurrency).
+
+Example seeds for "Modernize auth":
+- "Audit `packages/auth/middleware.ts` and document the session-token storage approach, flagging SOC2 gaps."
+- "Add a reproduction test for the current session-token storage that fails under the new SOC2 requirement."
+- "Design a migration path from cookie storage to encrypted-at-rest store; output as `designs/auth-migration.md`."
+
+Steering will add execution tasks (the actual migration code) in later waves, grounded in what the seeds found.
+
+## When to invoke the coach skill vs. this one
+
+- **`claude-overnight` skill** (this one): Claude helps the user plan an overnight run *outside* the CLI — picking shape, writing tasks.json, critiquing budget.
+- **`claude-overnight-coach` skill**: runs *inside* the CLI at startup, turns a raw objective into recommended settings + checklist. Different entry point, overlapping knowledge. Don't invoke coach from here.

package/plugins/claude-overnight/skills/claude-overnight/recipes.md

@@ -0,0 +1,48 @@
+# Overnight Run Recipes
+
+Scenario → recommended run shape. These are defaults, not laws — adjust when the repo or user constraints say so. Always pair with `authoring.md` (decision tree + pre-flight).
+
+## Recipe matrix
+
+| Scenario | Shape | `flexiblePlan` | Budget | Concurrency | Planner / Worker | Skip phases | Notes |
+|---|---|---|---|---|---|---|---|
+| **Fixed refactor** (concrete file list, clear endpoint) | `tasks.json` with explicit tasks | `false` (`--no-flex`) | 1× tasks + ~20% headroom | 3–5 | Sonnet / Sonnet | thinking wave, post-wave review | Each task = one cohesive unit of work. Cheapest mode. |
+| **Feature batch** (N independent features) | `tasks.json`, one task per feature | `false` initially; `true` if features bleed into shared code | 2–3× feature count | 4–6 | Opus / Sonnet | thinking wave if features are well-scoped | Require verify-before-done per task. |
+| **Framework migration** (Next 14→16, React 18→19, etc.) | `objective` + seed tasks per package | `true` | 50–200 | 3–5 | Opus / Sonnet | none — keep thinking + review | Steering re-plans as breakage surfaces. `beforeWave`: install deps. |
+| **Test sprint** (raise coverage, fill gaps) | `objective` + seed per module | `true` | 30–100 | 5–8 | Sonnet / Sonnet (or Qwen for cost) | thinking if coverage report is attached | `afterWave`: run test suite, feed failures forward. |
+| **Docs sprint** (API docs, guides) | `tasks.json` per doc surface | `false` | 1× docs + 10% | 4–6 | Sonnet / Sonnet (or Qwen) | thinking wave, reflection | Pure output task — flex mode wastes planner. |
+| **Bug hunt** (unknown cause, repro unstable) | `objective` + the repro | `true` | 20–80 | 2–4 | Opus / Opus | none | Low concurrency — workers step on each other on shared bug surface. Verify fix via reproduction script. |
+| **Codebase audit / research** (no code changes) | `objective` + focus list | `true` | 30–80 | 5–10 | Opus / Sonnet | n/a — architects *are* the work | Output is `designs/*.md` + `milestones/`. Set `permissionMode: "default"` so workers can't write. |
+| **Framework-wide cleanup** (dead code, consistency) | `objective` + seed tasks | `true` | 100–300 | 5–8 | Opus / Sonnet + fast Qwen | thinking if scope is obvious | Use fast worker for well-scoped mechanical tasks. |
+| **Long research run** (exploration, prototypes) | `objective` + loose tasks | `true` | 200–1000 | 3–5 | Opus / Opus | none | `usageCap: 90`, `--allow-extra-usage` off unless explicitly requested. |
+
+## Budget heuristics
+
+- **Per-wave cost floor** ≈ $2–4 planner + $N workers × avg task cost (Sonnet ≈ $0.15–0.40, Opus ≈ $0.50–1.50, Qwen ≈ <$0.05). Budget must cover *expected waves × per-wave cost*, not just task count.
+- **Thinking wave cost** scales with budget: 5 architects at budget=50 (~$3–8), 10 at budget=2000 (~$15–40). Skip when you don't need exploration.
+- **Flex overhead**: each steering pass is one planner call (~$0.50–2 on Opus). For 10-wave flex runs, reserve ~$10 for steering alone.
+
+## Model pairing defaults
+
+| Run type | Planner | Main worker | Fast worker |
+|---|---|---|---|
+| High-stakes (production refactor, migration) | Opus | Sonnet | — |
+| Everyday (features, tests, cleanups) | Sonnet | Sonnet | Qwen 3.6 Plus |
+| Cost-sensitive (docs, mechanical batch) | Sonnet | Qwen 3.6 Plus | — |
+| Research / audit (read-heavy) | Opus | Opus | — |
+
+Rationale: planner quality is the ceiling for the whole run. Never cheap out on planner unless the run is purely mechanical.
+
+## Phase-skip cheatsheet
+
+- **Skip thinking wave** when: tasks are already concrete · user has already explored the code · scenario is "docs/tests/mechanical batch" · budget < 15 (auto-skipped).
+- **Skip flex / steering** (`--no-flex`) when: endpoint is crisp · tasks are independent · no assessment needed between waves.
+- **Skip post-wave review** when: single-wave run · budget is tight · tasks are trivially verifiable (docs, formatting).
+- **Always keep final gate** (post-run review) unless `--dry-run`. It's the last quality check before the diff lands.
+
+## Anti-recipes (don't do these)
+
+- "Do everything in `src/`" → one agent, no decomposition. See `authoring.md` → *decompose fallback*.
+- `budget=5` + `flexiblePlan: true` → planner eats most of the budget, workers starve.
+- High concurrency on shared-file scenarios (migrations, bug hunts) → merge conflicts dominate. Drop to 2–4.
+- `usageCap: 100` + `--allow-extra-usage` without `--extra-usage-budget` → silent overage. Always cap extra spend explicitly.