@vextlabs/theron-cli 0.3.0 → 0.4.0

package/dist/repl.js

@@ -5,17 +5,23 @@
 import readline from "node:readline";
 import path from "node:path";
 import process from "node:process";
+import os from "node:os";
 import chalk from "chalk";
 import { spawnSync } from "node:child_process";
+import { promptMultiline, promptLine } from "./input.js";
 import { streamChat, fetchInteractionPlan } from "./api.js";
 import { loadCapConfig, resolveCapPolicy } from "./cap_config.js";
 import { loadProjectMemory, formatProjectMemoryForRequest } from "./project_memory.js";
 import { rankProfilesForPrompt } from "./profile_match.js";
-import { TOOL_REGISTRY, TOOL_SCHEMAS, READONLY_TOOL_SCHEMAS, MUTATING_TOOLS } from "./tools/index.js";
+import { TOOL_REGISTRY, TOOL_SCHEMAS, READONLY_TOOL_SCHEMAS, MUTATING_TOOLS, setLoadedSkills } from "./tools/index.js";
+import { loadAllMarkdownSkills, loadMarkdownSkills } from "@vextlabs/theron-agent-sdk";
+import { fileURLToPath } from "node:url";
+import { groupByEntrance } from "./skills/catalog.js";
 import { renderMarkdown, ui } from "./render.js";
 import { loadCustomCommands, substituteArgs } from "./slash_commands.js";
 import { resolveFileRefs } from "./file_refs.js";
-import { sessionIdForCwd, loadSession, saveSession, deleteSession, listSessions, } from "./sessions.js";
+import { sessionIdForCwd, loadSession, saveSession, deleteSession, listSessions, pushSession, pullSession, } from "./sessions.js";
+import { rewindLast, checkpointCount } from "./checkpoints.js";
 import { getProfileOrDefault, listProfiles, DEFAULT_PROFILE_SLUG } from "./profiles/index.js";
 import { runVerifiers, summarizeIssues, formatForNextTurn } from "./verifiers/index.js";
 import { connectionsCommand } from "./connections.js";
@@ -26,18 +32,70 @@ export async function runRepl(opts) {
         cwd: opts.cwd,
         maxBytes: 64 * 1024,
         yolo: opts.yolo,
+        apiUrl: opts.apiUrl,
+        apiKey: opts.apiKey,
     };
     const messages = [];
     let pendingActions = [];
-    const rl = opts.oneShot
-        ? null
-        : readline.createInterface({ input: process.stdin, output: process.stdout, terminal: process.stdin.isTTY === true });
+    // Input routing:
+    //   - Interactive TTY → the raw-mode multiline editor (src/input.ts).
+    //     It owns raw mode itself, so we do NOT also stand up a readline
+    //     Interface (two stdin consumers would double-handle keystrokes).
+    //   - Piped / non-TTY → a line-buffered readline Interface, used to
+    //     pull one prompt per line off the pipe.
+    //   - One-shot → neither; the prompt is handed straight in.
+    const isInteractiveTTY = !opts.oneShot && process.stdin.isTTY === true;
+    const rl = !opts.oneShot && !isInteractiveTTY
+        ? readline.createInterface({ input: process.stdin, output: process.stdout, terminal: false })
+        : null;
     // Track whether stdin has ended (happens when piping input — stdin
     // EOFs after the last line is consumed). Without this guard we hit
     // ERR_USE_AFTER_CLOSE on the next question() call. Listening for
     // 'close' lets the loop bail gracefully instead of throwing.
     let rlClosed = false;
     rl?.on("close", () => { rlClosed = true; });
+    // Shared input history for the multiline editor (Up/Down recall).
+    // Load from ~/.theron/history on start; append on submit.
+    const HISTORY_FILE = path.join(process.env.HOME ?? os.homedir(), ".theron", "history");
+    const MAX_HISTORY = 500;
+    const inputHistory = [];
+    // Load history from disk (ignore errors — first run, missing file, etc.)
+    try {
+        const { promises: fsp } = await import("node:fs");
+        const raw = await fsp.readFile(HISTORY_FILE, "utf-8").catch(() => "");
+        const lines = raw.split("\n").filter((l) => l.trim());
+        inputHistory.push(...lines.slice(-MAX_HISTORY));
+    }
+    catch { /* ignore */ }
+    /** Append one entry to the on-disk history file, keeping last MAX_HISTORY. */
+    const appendHistory = async (entry) => {
+        if (!entry.trim() || opts.headless)
+            return;
+        try {
+            const { promises: fsp } = await import("node:fs");
+            await fsp.mkdir(path.dirname(HISTORY_FILE), { recursive: true });
+            await fsp.appendFile(HISTORY_FILE, entry.replace(/\n/g, " ") + "\n", "utf-8");
+        }
+        catch { /* best effort */ }
+    };
+    // Read one line for pickers / confirmations. TTY uses the raw
+    // single-line reader (consistent with the multiline editor); piped
+    // input reuses the readline Interface; otherwise there's no input.
+    const askLine = async (question) => {
+        if (isInteractiveTTY)
+            return await promptLine(question);
+        if (rl && !rlClosed) {
+            return await new Promise((resolve) => {
+                try {
+                    rl.question(question, (a) => resolve(a));
+                }
+                catch {
+                    resolve(null);
+                }
+            });
+        }
+        return null;
+    };
     // Mutable session state — slash commands rewrite these, REPL reads.
     const session = {
         cwd: opts.cwd,
@@ -73,6 +131,11 @@ export async function runRepl(opts) {
     // every turn (and after /clear truncation). Never throws — saveSession
     // fails open. Skipped in headless mode where we don't want to mutate
     // the user's saved history from a one-shot pipe.
+    //
+    // When --cloud is set, also fire-and-forget a push to /api/sessions/sync
+    // so the session is portable across devices (CLI to IDE and back). The
+    // cloud push is non-blocking: it resolves in the background and a failure
+    // is silently ignored (the local save is the source of truth).
     const persistSession = () => {
         if (opts.headless)
             return;
@@ -85,6 +148,13 @@ export async function runRepl(opts) {
             messages,
         };
         saveSession(state);
+        if (opts.cloud && opts.apiKey) {
+            // Fire-and-forget: never blocks the REPL, never throws.
+            void pushSession(state, {
+                apiUrl: opts.apiUrl,
+                apiKey: opts.apiKey,
+            }).catch(() => { });
+        }
     };
     // The memory text we inject as a leading system note + send as the
     // `project_context` body field. Recomputed when memory reloads.
@@ -123,16 +193,7 @@ export async function runRepl(opts) {
             const shortCwd = home && s.cwd.startsWith(home) ? "~" + s.cwd.slice(home.length) : s.cwd;
             process.stdout.write(`  ${ui.actionChip(i + 1, `${s.id} · ${s.messageCount} msgs · ${s.profile} · ${shortCwd}`)}\n`);
         });
-        if (!rl || rlClosed)
-            return null;
-        const answer = await new Promise((resolve) => {
-            try {
-                rl.question(ui.prompt(), (a) => resolve(a));
-            }
-            catch {
-                resolve("");
-            }
-        });
+        const answer = (await askLine(ui.prompt())) ?? "";
         const n = Number(answer.trim());
         if (Number.isInteger(n) && n >= 1 && n <= Math.min(sessions.length, 20)) {
             return sessions[n - 1].id;
@@ -156,7 +217,21 @@ export async function runRepl(opts) {
             }
         }
         if (toLoad) {
-            const loaded = loadSession(toLoad);
+            let loaded = loadSession(toLoad);
+            // Cloud fallback: when --cloud is set and the local session is
+            // missing or empty, try pulling from /api/sessions/:id. This is the
+            // cross-device resume path (start in IDE, continue in CLI).
+            if ((!loaded || loaded.messages.length === 0) && opts.cloud && opts.apiKey) {
+                const cloudState = await pullSession(toLoad, {
+                    apiUrl: opts.apiUrl,
+                    apiKey: opts.apiKey,
+                });
+                if (cloudState && cloudState.messages.length > 0) {
+                    loaded = cloudState;
+                    // Persist locally so future resumes don't need the network.
+                    saveSession(cloudState);
+                }
+            }
             if (loaded && loaded.messages.length > 0) {
                 messages.push(...loaded.messages);
                 session.sessionId = loaded.id;
@@ -170,7 +245,7 @@ export async function runRepl(opts) {
             }
         }
     }
-    if (!opts.oneShot) {
+    if (!opts.oneShot && !opts.noBanner) {
         // Branded welcome — block-letter THERON banner + pill + numbered
         // security notes + quickstart status line. Same flow Claude Code
         // uses on first launch, in our amber-on-paper palette.
@@ -236,30 +311,82 @@ export async function runRepl(opts) {
             process.stdout.write(ui.warn("plan mode — read-only. Write / Edit / Bash / Stoa are blocked until you /plan or type 'approve'.\n"));
         }
         process.stdout.write("\n");
-        process.stdout.write(ui.info("type a message · /help for commands · /mode list to see all 33 · Ctrl-C to quit\n\n"));
+        process.stdout.write(ui.info("type a message · Enter sends · Shift+Tab or \\+Enter for a new line · /help for commands · Ctrl-C to clear or quit\n\n"));
+    }
+    // ── Skills ────────────────────────────────────────────────────────────────
+    // Three sources, lowest→highest precedence (later overrides earlier by name):
+    //   1. BUNDLED — the curated skill library shipped with the CLI (../skills,
+    //      sibling of dist/). Elite playbooks: literature-review, fact-check,
+    //      experiment-design, data-analysis, tdd, refactor, optimize, api-design,
+    //      plan, red-team, write-tests, reproduce.
+    //   2. USER     — ~/.theron/skills/*.md
+    //   3. PROJECT  — <cwd>/.theron/skills/*.md
+    // So users can extend or override any built-in by dropping a same-named file.
+    const bundledSkillsDir = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "skills");
+    const [bundledSkills, userProjectSkills] = await Promise.all([
+        loadMarkdownSkills(bundledSkillsDir).catch(() => []),
+        loadAllMarkdownSkills(opts.cwd).catch(() => []),
+    ]);
+    const mergedSkills = new Map();
+    for (const s of bundledSkills)
+        mergedSkills.set(s.name, s);
+    for (const s of userProjectSkills)
+        mergedSkills.set(s.name, s);
+    const loadedSkills = [...mergedSkills.values()];
+    setLoadedSkills(loadedSkills);
+    // Fast O(1) map for slash-command lookup.
+    const skillsMap = new Map(loadedSkills.map((s) => [s.name, s]));
+    if (!opts.oneShot && loadedSkills.length > 0) {
+        process.stdout.write(ui.info(`◉ skills loaded: ${loadedSkills.map((s) => "/" + s.name).join(", ")}\n`));
     }
-    const promptOnce = () => new Promise((resolve) => {
+    // ── Session token totals (for /status + per-turn cost display) ────────────
+    let sessionInputTokens = 0;
+    let sessionOutputTokens = 0;
+    // ── SIGINT handling ────────────────────────────────────────────────────────
+    // Idle prompt → exit 130 (POSIX Ctrl-C convention).
+    // During a streaming turn → cancel that turn, return to prompt.
+    // The per-turn handler is installed in the turn loop below; this is the
+    // idle fallback re-installed after each turn ends.
+    // We removeAllListeners first so the global handler in bin/theron.js
+    // doesn't also fire, causing a double-exit or premature exit during a turn.
+    const idleSigintHandler = () => process.exit(130);
+    process.removeAllListeners("SIGINT");
+    process.on("SIGINT", idleSigintHandler);
+    const promptOnce = () => {
         if (opts.oneShot && messages.length === 0) {
-            resolve(opts.oneShot);
-            return;
-        }
-        if (!rl || rlClosed) {
-            resolve(null);
-            return;
+            return Promise.resolve(opts.oneShot);
         }
-        try {
-            rl.question(ui.prompt(), (answer) => resolve(answer));
+        // Interactive TTY → the multiline editor with a visible input box.
+        if (isInteractiveTTY) {
+            return promptMultiline({
+                label: "theron",
+                placeholder: session.profile.promptStarters?.[0]
+                    ? `try: ${session.profile.promptStarters[0]}`
+                    : "type a message — /help for commands",
+                hint: "Enter to send · Shift+Tab or \\+Enter for newline · /help · Ctrl+C to clear",
+                history: inputHistory,
+            });
         }
-        catch (err) {
-            // ERR_USE_AFTER_CLOSE — stdin EOFed (typical when piping
-            // input). Bail the loop cleanly instead of throwing.
-            if (err?.code === "ERR_USE_AFTER_CLOSE") {
+        // Piped / non-TTY → one line per prompt off the readline Interface.
+        return new Promise((resolve) => {
+            if (!rl || rlClosed) {
                 resolve(null);
                 return;
             }
-            throw err;
-        }
-    });
+            try {
+                rl.question(ui.prompt(), (answer) => resolve(answer));
+            }
+            catch (err) {
+                // ERR_USE_AFTER_CLOSE — stdin EOFed (typical when piping
+                // input). Bail the loop cleanly instead of throwing.
+                if (err?.code === "ERR_USE_AFTER_CLOSE") {
+                    resolve(null);
+                    return;
+                }
+                throw err;
+            }
+        });
+    };
     while (true) {
         const input = await promptOnce();
         if (input == null)
@@ -342,6 +469,36 @@ export async function runRepl(opts) {
             }
             continue;
         }
+        // /rewind — restore the most recently snapshotted file to the content it
+        // had BEFORE Theron's last Write or Edit.  If the file was newly created
+        // (before === null), it is deleted.  Fail-safe: if the restore write
+        // fails the error is shown but the session continues.
+        if (trimmed === "/rewind") {
+            const cp = rewindLast();
+            if (!cp) {
+                process.stdout.write(ui.info("nothing to rewind — no checkpoints in this session.\n\n"));
+            }
+            else {
+                const remaining = checkpointCount();
+                try {
+                    const fsModule = await import("node:fs");
+                    const { promises: fsp } = fsModule;
+                    if (cp.before === null) {
+                        // File was created from scratch by Theron — delete it.
+                        await fsp.unlink(cp.path);
+                        process.stdout.write(ui.info(`deleted ${cp.path} (${remaining} checkpoint${remaining === 1 ? "" : "s"} left)\n\n`));
+                    }
+                    else {
+                        await fsp.writeFile(cp.path, cp.before, "utf-8");
+                        process.stdout.write(ui.info(`reverted ${cp.path} (${remaining} checkpoint${remaining === 1 ? "" : "s"} left)\n\n`));
+                    }
+                }
+                catch (err) {
+                    process.stdout.write(ui.error(`rewind failed: ${err instanceof Error ? err.message : String(err)}\n\n`));
+                }
+            }
+            continue;
+        }
         if (trimmed === "/status") {
             process.stdout.write("\n" + renderStatus({
                 cwd: session.cwd,
@@ -362,6 +519,9 @@ export async function runRepl(opts) {
             }
             process.stdout.write(ui.info(`plan mode: ${session.planMode ? "ON (read-only)" : "off"}  ·  render: ${session.renderMode ? "on" : "off"}\n`));
             process.stdout.write(ui.info(`session: ${session.sessionId} (${messages.length} messages)\n`));
+            if (sessionInputTokens > 0 || sessionOutputTokens > 0) {
+                process.stdout.write(ui.info(`tokens: ${sessionInputTokens.toLocaleString()} in → ${sessionOutputTokens.toLocaleString()} out (session total)\n`));
+            }
             if (session.planMode) {
                 process.stdout.write(ui.warn("Write / Edit / Bash / Stoa are blocked. /plan or 'approve' to exit.\n"));
             }
@@ -425,6 +585,62 @@ export async function runRepl(opts) {
             process.stdout.write("\n");
             continue;
         }
+        // /compact — summarize the conversation to save context. POSTs to
+        // /api/cli/compact if present; else asks the model to summarize older
+        // messages in-loop. The result replaces the conversation with a
+        // summary message + the most recent N messages, then persists.
+        if (trimmed === "/compact") {
+            if (messages.length < 4) {
+                process.stdout.write(ui.info("conversation too short to compact.\n\n"));
+                continue;
+            }
+            // Keep the last 6 messages, summarize everything before that.
+            const KEEP = 6;
+            const toSummarize = messages.slice(0, Math.max(0, messages.length - KEEP));
+            const recent = messages.slice(Math.max(0, messages.length - KEEP));
+            if (toSummarize.length === 0) {
+                process.stdout.write(ui.info("nothing old enough to compact.\n\n"));
+                continue;
+            }
+            // Try the server's /api/cli/compact endpoint first.
+            let summary = null;
+            try {
+                const r = await fetch(`${opts.apiUrl.replace(/\/$/, "")}/api/cli/compact`, {
+                    method: "POST",
+                    headers: {
+                        "content-type": "application/json",
+                        ...(opts.apiKey ? { authorization: `Bearer ${opts.apiKey}` } : {}),
+                    },
+                    body: JSON.stringify({ messages: toSummarize }),
+                    signal: AbortSignal.timeout(30_000),
+                });
+                if (r.ok) {
+                    const data = (await r.json());
+                    if (typeof data.summary === "string" && data.summary.trim()) {
+                        summary = data.summary.trim();
+                    }
+                }
+            }
+            catch { /* fall through to local summarize */ }
+            if (!summary) {
+                // Fallback: build a local summary from the messages text.
+                const textParts = [];
+                for (const m of toSummarize) {
+                    if (m.role === "user" || m.role === "assistant") {
+                        const prefix = m.role === "user" ? "User" : "Assistant";
+                        textParts.push(`${prefix}: ${m.content.slice(0, 400)}`);
+                    }
+                }
+                summary = `[Conversation summary — earlier ${toSummarize.length} messages compacted]\n${textParts.join("\n\n").slice(0, 2000)}`;
+            }
+            // Replace the conversation with summary + recent messages.
+            const summaryMsg = { role: "user", content: summary };
+            messages.length = 0;
+            messages.push(summaryMsg, ...recent);
+            persistSession();
+            process.stdout.write(ui.info(`compacted: ${toSummarize.length} messages → 1 summary (${messages.length} total now)\n\n`));
+            continue;
+        }
         if (trimmed === "/clear") {
             messages.length = 0;
             pendingActions = [];
@@ -529,6 +745,23 @@ export async function runRepl(opts) {
             process.stdout.write("\n");
             continue;
         }
+        if (trimmed === "/skills") {
+            if (loadedSkills.length === 0) {
+                process.stdout.write(ui.info("\nno skills loaded. Add SKILL.md files to ~/.theron/skills/ or .theron/skills/.\n" +
+                    "Each file needs YAML frontmatter with 'name' and 'description', then the body.\n\n"));
+            }
+            else {
+                process.stdout.write(ui.info(`\nloaded skills (${loadedSkills.length}) — invoke via /<name> [args]:\n`));
+                for (const group of groupByEntrance(loadedSkills)) {
+                    process.stdout.write(`\n  ${ui.toolLabel(group.title, "")}\n`);
+                    for (const s of group.items) {
+                        process.stdout.write(`    ${ui.toolLabel("/" + s.name, "")}  ${ui.info(s.description || "(no description)")}\n`);
+                    }
+                }
+                process.stdout.write(ui.info("\n  add your own in ~/.theron/skills/ or .theron/skills/ (a same-named file overrides a built-in)\n\n"));
+            }
+            continue;
+        }
         // /suggest <prompt> — rank profiles by similarity to a prompt and
         // show the top 3 candidates so the user can switch with /mode <slug>
         // without scrolling /mode list. Embedding-keyed injector pattern
@@ -748,6 +981,27 @@ export async function runRepl(opts) {
                     continue;
                 }
             }
+            // Skill slash command — check after custom commands so custom commands
+            // can override skills of the same name, but skills extend the built-in set.
+            if (!isExpandedCommand) {
+                const skill = skillsMap.get(cmdName);
+                if (skill) {
+                    const argString = argTokens.join(" ");
+                    const toolNote = skill.allowedTools && skill.allowedTools.length > 0
+                        ? `\n\n(Prefer these tools: ${skill.allowedTools.join(", ")})`
+                        : "";
+                    const injected = (skill.body + toolNote + (argString ? `\n\nArgs: ${argString}` : "")).trim();
+                    if (injected) {
+                        process.stdout.write(ui.info(`▸ /${cmdName} (skill)\n`));
+                        trimmed = injected;
+                        isExpandedCommand = true;
+                    }
+                    else {
+                        process.stdout.write(ui.error(`/${cmdName} skill has an empty body — nothing to send.\n\n`));
+                        continue;
+                    }
+                }
+            }
         }
         // Unknown slash → friendly nudge. (Custom commands already matched
         // above and set isExpandedCommand; only a real unknown reaches here.)
@@ -850,6 +1104,8 @@ export async function runRepl(opts) {
         // the executor-side hard deny (see runOneTurn) is the real safety net,
         // so correctness never depends on the model honoring this text.
         const planPrefixed = session.planMode ? PLAN_MODE_INSTRUCTION + "\n\n" + toSend : toSend;
+        // Append to persistent history.
+        void appendHistory(trimmed);
         messages.push({ role: "user", content: planPrefixed });
         // Fire the interaction-plan classifier in parallel with the first
         // model turn. The plan is shared across web/CLI/IDE — if it wins
@@ -879,10 +1135,25 @@ export async function runRepl(opts) {
         // and the names of every tool the model invoked (for headless JSON).
         let turnGuard = 0;
         const touchedFiles = new Set();
+        const readFiles = new Set();
         const toolsUsed = [];
         let lastAssistantText = "";
         let turnErrored = false;
-        while (turnGuard < 20) {
+        let turnCanceled = false;
+        // ── Per-turn SIGINT (Ctrl-C cancels streaming turn, not the process) ──
+        // Install a turn-scoped handler that aborts the turn; after the turn the
+        // idle handler is restored so Ctrl-C at the prompt still exits 130.
+        const turnAbort = new AbortController();
+        process.removeAllListeners("SIGINT");
+        process.once("SIGINT", () => {
+            turnCanceled = true;
+            turnAbort.abort();
+            // Restore idle handler immediately so a second Ctrl-C exits cleanly.
+            process.removeAllListeners("SIGINT");
+            process.on("SIGINT", idleSigintHandler);
+        });
+        const maxTurnsPerPrompt = opts.maxTurns ?? 20;
+        while (turnGuard < maxTurnsPerPrompt) {
             turnGuard += 1;
             const res = await runOneTurn({
                 apiUrl: opts.apiUrl,
@@ -897,6 +1168,7 @@ export async function runRepl(opts) {
                 profile: session.profile.slug,
                 projectContext: projectContext || undefined,
                 touchedFilesSink: touchedFiles,
+                readFilesSink: readFiles,
                 toolsUsedSink: toolsUsed,
                 // Plan mode: hard-deny mutating tools at the executor (even with
                 // --yes) and send the model only the read-only tool subset.
@@ -907,7 +1179,26 @@ export async function runRepl(opts) {
                 // deltas — the answer is emitted once at end (rendered or JSON).
                 bufferText: session.renderMode || !!opts.headless,
                 headless: !!opts.headless,
+                // Thread the abort signal for Ctrl-C mid-turn cancel.
+                signal: turnAbort.signal,
+                outputFormat: opts.outputFormat,
+                // Token/cost accumulation — fires when server emits a usage frame.
+                onUsageCb: (usage) => {
+                    sessionInputTokens += usage.input_tokens;
+                    sessionOutputTokens += usage.output_tokens;
+                    if (!opts.headless) {
+                        const costStr = usage.cost_usd != null ? ` · $${usage.cost_usd.toFixed(4)}` : "";
+                        process.stdout.write(chalk.dim(`↳ ${usage.input_tokens}→${usage.output_tokens} tokens${costStr}\n\n`));
+                    }
+                },
             });
+            // Restore idle SIGINT after the turn completes (normal path).
+            process.removeAllListeners("SIGINT");
+            process.on("SIGINT", idleSigintHandler);
+            if (res.kind === "canceled") {
+                turnCanceled = true;
+                break;
+            }
             if (res.kind === "error") {
                 if (!opts.headless)
                     process.stdout.write(ui.error(res.message) + "\n\n");
@@ -918,7 +1209,27 @@ export async function runRepl(opts) {
                 lastAssistantText = res.assistantText ?? "";
                 break;
             }
-            // tool_use — keep looping
+            // tool_use — keep looping (SIGINT handler is already restored above)
+            // Re-install turn handler for the next tool-loop iteration.
+            process.removeAllListeners("SIGINT");
+            process.once("SIGINT", () => {
+                turnCanceled = true;
+                turnAbort.abort();
+                process.removeAllListeners("SIGINT");
+                process.on("SIGINT", idleSigintHandler);
+            });
+        }
+        // Ensure idle handler is restored even if we exited the loop another way.
+        process.removeAllListeners("SIGINT");
+        process.on("SIGINT", idleSigintHandler);
+        // Warn if we hit the max-turn cap.
+        if (turnGuard >= maxTurnsPerPrompt && !turnCanceled) {
+            process.stdout.write(ui.warn(`[max-turns] reached the ${maxTurnsPerPrompt}-turn cap — Theron stopped. Use --max-turns N to increase.\n\n`));
+        }
+        // Ctrl-C mid-turn: show ⊘ canceled, skip verifiers, go back to prompt.
+        if (turnCanceled) {
+            process.stdout.write(chalk.dim("\n⊘ canceled\n\n"));
+            continue;
         }
         // Render the assistant's markdown once the turn settles, when render
         // mode is on and we're an interactive TTY. We buffered the raw deltas
@@ -941,6 +1252,7 @@ export async function runRepl(opts) {
                 cwd: session.cwd,
                 assistantText: lastAssistantText,
                 touchedFiles: Array.from(touchedFiles),
+                readFiles: Array.from(readFiles),
                 profile: session.profile.slug,
             });
             const sum = summarizeIssues(issues);
@@ -992,6 +1304,9 @@ export async function runRepl(opts) {
             break;
     }
     rl?.close();
+    // Remove our SIGINT handler so main()'s process.exit(code) path
+    // after runRepl returns doesn't leave a ghost listener.
+    process.removeListener("SIGINT", idleSigintHandler);
     // Final newline so the user's shell prompt lands on a clean line
     // instead of the readline `> ` getting % -terminated by zsh.
     process.stdout.write("\n");
@@ -1004,6 +1319,11 @@ async function runOneTurn(args) {
     let firstDelta = true;
     const headless = args.headless === true;
     const bufferText = args.bufferText === true;
+    const streamJson = args.outputFormat === "stream-json";
+    // Thread the per-turn abort signal into the ToolContext so long-running
+    // tools (Bash) can be killed on Ctrl-C.
+    if (args.signal)
+        args.ctx.signal = args.signal;
     // Show the pin header BEFORE thinking spinner so the user knows
     // immediately that their /pin took effect. (Suppressed in headless.)
     if (!headless && args.pinnedSpecs && args.pinnedSpecs.length > 0) {
@@ -1022,6 +1342,7 @@ async function runOneTurn(args) {
         tools: args.tools ?? TOOL_SCHEMAS,
         profile: args.profile,
         projectContext: args.projectContext,
+        signal: args.signal,
     }, {
         onTextDelta: (d) => {
             if (firstDelta) {
@@ -1038,20 +1359,39 @@ async function runOneTurn(args) {
             // raw deltas live.
             if (!bufferText)
                 process.stdout.write(d);
+            // stream-json: emit one NDJSON frame per text delta.
+            if (streamJson)
+                process.stdout.write(JSON.stringify({ type: "text_delta", delta: d }) + "\n");
         },
         onToolCall: (call) => {
             toolCalls.push(call);
             // Update the spinner label so the user sees what's queued.
             if (firstDelta && !headless)
                 spinner.setLabel(`${call.name}…`);
+            // stream-json: emit the tool_use frame.
+            if (streamJson)
+                process.stdout.write(JSON.stringify({ type: "tool_use", id: call.id, name: call.name, args: call.args }) + "\n");
+        },
+        onTurnEnd: (reason) => {
+            stopReason = reason;
+            if (streamJson)
+                process.stdout.write(JSON.stringify({ type: "turn_end", stop_reason: reason }) + "\n");
         },
-        onTurnEnd: (reason) => { stopReason = reason; },
         onError: (msg) => {
             stopReason = "error";
             if (!headless) {
                 spinner.stop();
-                process.stdout.write("\n" + announceError(msg) + "\n");
+                // Suppress the "canceled" error message — the outer loop prints ⊘ canceled.
+                if (msg !== "canceled")
+                    process.stdout.write("\n" + announceError(msg) + "\n");
             }
+            if (streamJson)
+                process.stdout.write(JSON.stringify({ type: "error", message: msg }) + "\n");
+        },
+        onUsage: (usage) => {
+            args.onUsageCb?.(usage);
+            if (streamJson)
+                process.stdout.write(JSON.stringify({ type: "usage", ...usage }) + "\n");
         },
     });
     // Always stop the spinner in case neither delta nor error fired
@@ -1063,6 +1403,10 @@ async function runOneTurn(args) {
     if (assistantText && !bufferText && !headless)
         process.stdout.write("\n\n");
     args.messages.push({ role: "assistant", content: assistantText, tool_calls: toolCalls });
+    // Ctrl-C mid-turn: signal was aborted → return "canceled" so the outer
+    // loop can print ⊘ canceled and return to the prompt cleanly.
+    if (args.signal?.aborted)
+        return { kind: "canceled" };
     if (stopReason === "error")
         return { kind: "error", message: "stream error" };
     if (toolCalls.length === 0)
@@ -1098,13 +1442,22 @@ async function runOneTurn(args) {
         }
         // Record Write/Edit paths so the post-turn verifier pass can
         // scope itself to just the files this turn touched.
-        if (args.touchedFilesSink && (call.name === "Write" || call.name === "Edit")) {
+        if (args.touchedFilesSink && (call.name === "Write" || call.name === "Edit" || call.name === "MultiEdit")) {
             const path = call.args?.file_path
                 ?? call.args?.path;
             if (typeof path === "string" && path.length > 0) {
                 args.touchedFilesSink.add(path);
             }
         }
+        // Record Read/Grep paths so source_gate credits the model for
+        // consulting the source (reading is correct behavior, not a violation).
+        if (args.readFilesSink && (call.name === "Read" || call.name === "Grep")) {
+            const path = call.args?.file_path
+                ?? call.args?.path;
+            if (typeof path === "string" && path.length > 0) {
+                args.readFilesSink.add(path);
+            }
+        }
         // Tool announcement — bullet style matches a list of actions
         // rather than CLI chrome. Single line, brand-amber name + dim
         // detail. (Suppressed in headless so stdout stays parseable.)
@@ -1154,6 +1507,9 @@ async function runOneTurn(args) {
         // only affects what the user sees in their terminal.
         if (!headless)
             process.stdout.write(ui.info(truncatePreview(result, 4000)) + "\n\n");
+        // stream-json: emit tool_result frame.
+        if (streamJson)
+            process.stdout.write(JSON.stringify({ type: "tool_result", tool_call_id: call.id, content: result }) + "\n");
         args.messages.push({ role: "tool", tool_call_id: call.id, content: result });
     }
     return { kind: "tool_use" };
@@ -1169,8 +1525,10 @@ const PLAN_MODE_INSTRUCTION = "You are in PLAN MODE. Investigate the task using
     "and wait for the user to approve before executing.";
 /** Emit the single headless payload. For json this is ONE JSON object on
  *  stdout (no other stdout writes happen in headless mode, so it parses
- *  cleanly). For text it's just the answer. `cost` is null because the
- *  NDJSON wire format carries no usage/cost frame — we never fabricate it. */
+ *  cleanly). For text it's just the answer. For stream-json the events were
+ *  already emitted live; we only emit a final `result` frame here.
+ *  `cost` is null because the NDJSON wire format carries no usage/cost frame
+ *  — we never fabricate it. */
 function emitHeadlessPayload(p) {
     if (p.outputFormat === "json") {
         const obj = {
@@ -1182,20 +1540,29 @@ function emitHeadlessPayload(p) {
         };
         process.stdout.write(JSON.stringify(obj) + "\n");
     }
+    else if (p.outputFormat === "stream-json") {
+        // Events were streamed live during the turn. Emit a final `result` frame.
+        process.stdout.write(JSON.stringify({
+            type: "result",
+            answer: p.answer,
+            tools_used: p.toolsUsed,
+            verifier: p.verifier,
+            cost: null,
+            session_id: p.sessionId,
+        }) + "\n");
+    }
     else {
         process.stdout.write(p.answer.replace(/\n+$/, "") + "\n");
     }
 }
 async function confirm(question, rl) {
-    // CRITICAL: reuse the OUTER REPL's readline.Interface. Creating a
-    // new Interface + closing it would close stdin under the outer rl
-    // on some terminals (zsh observed) — the REPL would die after the
-    // first tool call. Pass through the existing rl, share the same
-    // input stream.
+    const full = `${question} ${ui.info("(y/N) ")}`;
+    // Piped input → reuse the REPL's line-buffered readline Interface so
+    // we read exactly one line off the pipe.
     if (rl) {
         return await new Promise((resolve) => {
             try {
-                rl.question(`${question} ${ui.info("(y/N) ")}`, (a) => {
+                rl.question(full, (a) => {
                     const yes = a.trim().toLowerCase();
                     resolve(yes === "y" || yes === "yes");
                 });
@@ -1211,21 +1578,12 @@ async function confirm(question, rl) {
             }
         });
     }
-    // Fallback for one-shot mode where rl is null — read stdin once.
-    return await new Promise((resolve) => {
-        process.stdout.write(`${question} ${ui.info("(y/N) ")}`);
-        let buf = "";
-        const onData = (chunk) => {
-            buf += chunk.toString("utf8");
-            const nl = buf.indexOf("\n");
-            if (nl >= 0) {
-                process.stdin.off("data", onData);
-                const yes = buf.slice(0, nl).trim().toLowerCase();
-                resolve(yes === "y" || yes === "yes");
-            }
-        };
-        process.stdin.on("data", onData);
-    });
+    // Interactive TTY (or one-shot) → the raw single-line reader, which
+    // shares stdin handling with the multiline editor and falls back to a
+    // plain data read when stdin isn't a TTY.
+    const a = await promptLine(full);
+    const yes = a.trim().toLowerCase();
+    return yes === "y" || yes === "yes";
 }
 function truncatePreview(s, max) {
     if (s.length <= max)