@vextlabs/theron-cli 0.1.0 → 0.2.0

package/dist/repl.js

@@ -9,9 +9,13 @@ import chalk from "chalk";
 import { spawnSync } from "node:child_process";
 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 } from "./tools/index.js";
+import { TOOL_REGISTRY, TOOL_SCHEMAS, READONLY_TOOL_SCHEMAS, MUTATING_TOOLS } from "./tools/index.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 { getProfileOrDefault, listProfiles, DEFAULT_PROFILE_SLUG } from "./profiles/index.js";
 import { runVerifiers, summarizeIssues, formatForNextTurn } from "./verifiers/index.js";
 import { connectionsCommand } from "./connections.js";
@@ -43,11 +47,129 @@ export async function runRepl(opts) {
         /** Verifier issues to prepend to the NEXT user message — surfaces
          *  after the model self-corrects. Cleared once consumed. */
         pendingVerifierBlock: "",
+        /** Auto-loaded project memory (THERON.md / CLAUDE.md / AGENTS.md).
+         *  Reloaded whenever cwd changes (/cd). Injected into every turn so
+         *  the model honors repo-local rules without the user re-typing them
+         *  — Theron's CLAUDE.md analogue. */
+        projectMemory: loadProjectMemory(opts.cwd),
+        /** Plan mode — read-only tools + plan instruction + hard write deny.
+         *  Toggled by --plan / /plan / "approve". */
+        planMode: opts.planMode === true,
+        /** Custom slash commands loaded from ~/.theron/commands + ./.theron/
+         *  commands. Reloaded on /cd and /commands reload. */
+        customCommands: loadCustomCommands(opts.cwd),
+        /** Pretty-render the assistant's markdown at end of turn. */
+        renderMode: opts.renderMode === true,
+        /** Stable session id keyed to cwd, for save/resume. Updated on /cd. */
+        sessionId: sessionIdForCwd(opts.cwd),
+        /** Creation timestamp of the active on-disk session. */
+        sessionCreated: new Date().toISOString(),
     };
     const updateCtx = () => {
         ctx.cwd = session.cwd;
         ctx.yolo = session.yolo;
     };
+    // Persist the conversation under the cwd-keyed session id. Called after
+    // 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.
+    const persistSession = () => {
+        if (opts.headless)
+            return;
+        const state = {
+            id: session.sessionId,
+            cwd: session.cwd,
+            created: session.sessionCreated,
+            updated: new Date().toISOString(),
+            profile: session.profile.slug,
+            messages,
+        };
+        saveSession(state);
+    };
+    // The memory text we inject as a leading system note + send as the
+    // `project_context` body field. Recomputed when memory reloads.
+    let projectContext = formatProjectMemoryForRequest(session.projectMemory);
+    // Reload project memory from the current cwd (after /cd) and refresh
+    // the injected context string. Returns true if any memory is now loaded.
+    const reloadProjectMemory = () => {
+        session.projectMemory = loadProjectMemory(session.cwd);
+        projectContext = formatProjectMemoryForRequest(session.projectMemory);
+        return session.projectMemory.sources.length > 0;
+    };
+    // After a /cd the new directory may carry its own .theron/commands and
+    // maps to a different session id. Refresh both so custom commands and
+    // save/resume track the directory the user is actually in.
+    const reloadDirScopedState = () => {
+        session.customCommands = loadCustomCommands(session.cwd);
+        session.sessionId = sessionIdForCwd(session.cwd);
+    };
+    // ── Session resume ────────────────────────────────────────────────
+    // --continue → the cwd-keyed session; --resume [id] → that session or a
+    // picker. Seed the loaded messages before the loop. Headless skips
+    // resume (a one-shot pipe shouldn't replay a stale conversation).
+    //
+    // Numbered session picker for `--resume` with no id. Reuses the REPL's
+    // own readline (never opens a competing Interface on the same stdin).
+    // Returns the chosen session id, or null on empty list / invalid pick.
+    const pickSession = async () => {
+        const sessions = listSessions();
+        if (sessions.length === 0) {
+            process.stdout.write(ui.info("no saved sessions to resume.\n"));
+            return null;
+        }
+        process.stdout.write(ui.info("\nsaved sessions — pick a number to resume:\n"));
+        const home = process.env.HOME || "";
+        sessions.slice(0, 20).forEach((s, i) => {
+            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 n = Number(answer.trim());
+        if (Number.isInteger(n) && n >= 1 && n <= Math.min(sessions.length, 20)) {
+            return sessions[n - 1].id;
+        }
+        process.stdout.write(ui.info("no valid selection — starting fresh.\n"));
+        return null;
+    };
+    let resumedNotice = "";
+    if (!opts.headless && (opts.continueSession || opts.resumeSession)) {
+        let toLoad = null;
+        if (opts.continueSession) {
+            toLoad = session.sessionId;
+        }
+        else if (opts.resumeSession) {
+            if (opts.resumeId) {
+                toLoad = opts.resumeId;
+            }
+            else {
+                // Numbered picker — reuse a transient readline over stdin.
+                toLoad = await pickSession();
+            }
+        }
+        if (toLoad) {
+            const loaded = loadSession(toLoad);
+            if (loaded && loaded.messages.length > 0) {
+                messages.push(...loaded.messages);
+                session.sessionId = loaded.id;
+                session.sessionCreated = loaded.created;
+                resumedNotice = `◉ resumed session ${loaded.id} (${loaded.messages.length} messages)`;
+            }
+            else {
+                resumedNotice = opts.continueSession
+                    ? "◉ no saved session for this directory yet — starting fresh"
+                    : `◉ session not found: ${toLoad} — starting fresh`;
+            }
+        }
+    }
     if (!opts.oneShot) {
         // Branded welcome — block-letter THERON banner + pill + numbered
         // security notes + quickstart status line. Same flow Claude Code
@@ -93,6 +215,26 @@ export async function runRepl(opts) {
         if (session.profile.promptStarters && session.profile.promptStarters.length > 0) {
             process.stdout.write(ui.info(`  try: "${session.profile.promptStarters[0]}"\n`));
         }
+        // Project-memory notice — same affordance Claude Code prints when it
+        // picks up a CLAUDE.md. Tells the user which file(s) Theron is now
+        // honoring so the behavior is never invisible.
+        if (session.projectMemory.sources.length > 0) {
+            const names = session.projectMemory.sources.map((s) => path.basename(s)).join(", ");
+            process.stdout.write(ui.info(`◉ loaded project memory: ${names}${session.projectMemory.truncated ? " (truncated)" : ""}\n`));
+        }
+        // Custom-command notice — tell the user which /<name> commands are live.
+        if (session.customCommands.map.size > 0) {
+            const names = Array.from(session.customCommands.map.keys()).map((n) => "/" + n).join(", ");
+            process.stdout.write(ui.info(`◉ custom commands: ${names}\n`));
+        }
+        // Resume notice — which session we restored (if any).
+        if (resumedNotice) {
+            process.stdout.write(ui.info(resumedNotice + "\n"));
+        }
+        // Plan-mode notice — make the read-only stance visible on launch.
+        if (session.planMode) {
+            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"));
     }
@@ -128,7 +270,76 @@ export async function runRepl(opts) {
         if (trimmed === "/quit" || trimmed === "/exit")
             break;
         if (trimmed === "/help") {
-            process.stdout.write("\n" + renderSlashHelp() + "\n\n");
+            const customHelp = Array.from(session.customCommands.map.values()).map((c) => ({
+                trigger: "/" + c.name,
+                desc: c.description ?? `custom command (${c.source}) — ${path.basename(c.file)}`,
+            }));
+            process.stdout.write("\n" + renderSlashHelp(customHelp) + "\n\n");
+            continue;
+        }
+        // /plan — toggle plan mode. Also exits on the bare word "approve"
+        // (handled further down so it can't be a slash). Read-only tools +
+        // plan instruction when ON; normal policy when OFF.
+        if (trimmed === "/plan") {
+            session.planMode = !session.planMode;
+            if (session.planMode) {
+                process.stdout.write(ui.warn("plan mode ON — read-only. Write / Edit / Bash / Stoa are blocked (even with --yes). " +
+                    "The model will investigate and propose a plan. Type 'approve' or /plan to exit.\n\n"));
+            }
+            else {
+                process.stdout.write(ui.info("plan mode OFF — normal tool policy restored.\n\n"));
+            }
+            continue;
+        }
+        // /render — toggle end-of-turn markdown rendering.
+        if (trimmed === "/render") {
+            session.renderMode = !session.renderMode;
+            process.stdout.write(session.renderMode
+                ? ui.info("markdown rendering ON — the reply is pretty-printed once the turn ends.\n\n")
+                : ui.info("markdown rendering OFF — raw streamed text.\n\n"));
+            continue;
+        }
+        // /commands — list custom slash commands; `/commands reload` re-scans.
+        if (trimmed === "/commands" || trimmed === "/commands reload") {
+            if (trimmed === "/commands reload") {
+                session.customCommands = loadCustomCommands(session.cwd);
+                process.stdout.write(ui.info("re-scanned commands directories.\n"));
+            }
+            const cmds = Array.from(session.customCommands.map.values());
+            if (cmds.length === 0) {
+                process.stdout.write(ui.info("\nno custom commands. Add a markdown file at ./.theron/commands/<name>.md " +
+                    "(or ~/.theron/commands/<name>.md) — typing /<name> sends its body as the prompt, " +
+                    "with $ARGUMENTS / $1 / $2 substituted.\n\n"));
+            }
+            else {
+                process.stdout.write(ui.info(`\ncustom commands (${cmds.length}):\n`));
+                for (const c of cmds) {
+                    const desc = c.description ? ` — ${c.description}` : "";
+                    process.stdout.write(ui.info(`  /${c.name.padEnd(14)} (${c.source})${desc}\n`));
+                }
+                if (session.customCommands.dirs.length > 0) {
+                    process.stdout.write(ui.info(`\nscanned: ${session.customCommands.dirs.join(", ")}\n`));
+                }
+                process.stdout.write("\n");
+            }
+            continue;
+        }
+        // /sessions — list saved sessions so the user knows what --resume can pick.
+        if (trimmed === "/sessions") {
+            const sessions = listSessions();
+            if (sessions.length === 0) {
+                process.stdout.write(ui.info("\nno saved sessions yet. They're written under ~/.theron/sessions/.\n\n"));
+            }
+            else {
+                process.stdout.write(ui.info(`\nsaved sessions (${sessions.length}) — resume with \`theron --resume <id>\`:\n`));
+                for (const s of sessions.slice(0, 30)) {
+                    const here = s.id === session.sessionId ? "◉ " : "  ";
+                    const home = process.env.HOME || "";
+                    const shortCwd = home && s.cwd.startsWith(home) ? "~" + s.cwd.slice(home.length) : s.cwd;
+                    process.stdout.write(`  ${here}${ui.toolLabel(s.id, "")}  ${ui.info(`${s.messageCount} msgs · ${s.profile} · ${shortCwd}`)}\n`);
+                }
+                process.stdout.write("\n");
+            }
             continue;
         }
         if (trimmed === "/status") {
@@ -143,9 +354,41 @@ export async function runRepl(opts) {
             if (session.pinnedSpecs.length > 0) {
                 process.stdout.write(ui.info(`pinned: ${session.pinnedSpecs.map((s) => "@" + s).join(", ")}\n`));
             }
+            if (session.projectMemory.sources.length > 0) {
+                process.stdout.write(ui.info(`memory: ${session.projectMemory.sources.join(", ")}\n`));
+            }
+            else {
+                process.stdout.write(ui.info(`memory: none (add a THERON.md to this repo)\n`));
+            }
+            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 (session.planMode) {
+                process.stdout.write(ui.warn("Write / Edit / Bash / Stoa are blocked. /plan or 'approve' to exit.\n"));
+            }
             process.stdout.write("\n");
             continue;
         }
+        // /memory — show what project-memory files are loaded; `/memory reload`
+        // re-reads them from disk (handy after you edit THERON.md mid-session).
+        if (trimmed === "/memory" || trimmed === "/memory reload") {
+            if (trimmed === "/memory reload")
+                reloadProjectMemory();
+            if (session.projectMemory.sources.length === 0) {
+                process.stdout.write(ui.info("\nno project memory loaded. Add a THERON.md (or CLAUDE.md / AGENTS.md) " +
+                    "to this directory or any parent, or ~/.theron/THERON.md for global rules.\n\n"));
+            }
+            else {
+                process.stdout.write(ui.info(`\nproject memory${trimmed.endsWith("reload") ? " (reloaded)" : ""}:\n`));
+                for (const s of session.projectMemory.sources) {
+                    process.stdout.write(ui.info(`  ${s}\n`));
+                }
+                if (session.projectMemory.truncated) {
+                    process.stdout.write(ui.warn("  (one or more files were truncated to 32KB)\n"));
+                }
+                process.stdout.write("\n");
+            }
+            continue;
+        }
         if (trimmed === "/mode" || trimmed === "/mode list") {
             // Render the full profile registry. Grouped two columns for
             // readability — 33 entries is enough to want layout.
@@ -185,6 +428,12 @@ export async function runRepl(opts) {
         if (trimmed === "/clear") {
             messages.length = 0;
             pendingActions = [];
+            // Truncate the on-disk session too, otherwise the next save would
+            // re-persist an empty conversation under the same id and a later
+            // --continue would resume nothing useful. Deleting fully resets it.
+            if (!opts.headless)
+                deleteSession(session.sessionId);
+            session.sessionCreated = new Date().toISOString();
             process.stdout.write(ui.info("conversation cleared\n\n"));
             continue;
         }
@@ -210,7 +459,17 @@ export async function runRepl(opts) {
                     throw new Error("not a directory");
                 session.cwd = next;
                 updateCtx();
-                process.stdout.write(ui.info(`cwd → ${session.cwd}\n\n`));
+                // New directory may carry a different (or no) project-memory
+                // file — reload so the model honors THIS repo's rules. Also
+                // re-scan custom commands and re-key the save/resume session id.
+                reloadProjectMemory();
+                reloadDirScopedState();
+                process.stdout.write(ui.info(`cwd → ${session.cwd}\n`));
+                if (session.projectMemory.sources.length > 0) {
+                    const names = session.projectMemory.sources.map((s) => path.basename(s)).join(", ");
+                    process.stdout.write(ui.info(`◉ project memory: ${names}\n`));
+                }
+                process.stdout.write("\n");
             }
             catch (err) {
                 process.stdout.write(ui.error(`cd failed: ${err instanceof Error ? err.message : String(err)}\n\n`));
@@ -442,10 +701,10 @@ export async function runRepl(opts) {
             }
         }
         if (trimmed === "/bug") {
-            // Try to open the issue tracker in the user's browser. We fall
+            // Open the public feedback surface in the user's browser. We fall
             // back to printing the URL when the platform opener is missing
             // (e.g. headless CI) — either way the user sees the link.
-            const issueUrl = "https://github.com/Vext-Labs-Inc/sucrityflash/issues/new?labels=cli&title=Theron+CLI+bug";
+            const issueUrl = "https://tryvext.com";
             const opener = process.platform === "darwin" ? "open" :
                 process.platform === "win32" ? "start" :
                     "xdg-open";
@@ -464,11 +723,45 @@ export async function runRepl(opts) {
             process.stdout.write(ui.info("include `theron --version` output + the prompt that broke.\n\n"));
             continue;
         }
-        // Unknown slash → friendly nudge.
+        // Custom slash command → substitute args into its body and FALL
+        // THROUGH into the normal prompt path (set `trimmed`, do NOT
+        // continue) so it becomes this turn's prompt and runs through pins /
+        // verifier / message-push like any typed message. Runs AFTER every
+        // built-in check + the unknown-slash guard is below, so a custom
+        // command can never shadow a built-in (and load-time rejects
+        // reserved names anyway).
+        let isExpandedCommand = false;
         if (trimmed.startsWith("/")) {
+            const [head, ...argTokens] = trimmed.slice(1).split(/\s+/);
+            const cmdName = (head || "").toLowerCase();
+            const custom = session.customCommands.map.get(cmdName);
+            if (custom) {
+                const argString = argTokens.join(" ");
+                const expanded = substituteArgs(custom.body, argString).trim();
+                if (expanded) {
+                    process.stdout.write(ui.info(`▸ /${cmdName}${argString ? " " + argString : ""}\n`));
+                    trimmed = expanded;
+                    isExpandedCommand = true;
+                }
+                else {
+                    process.stdout.write(ui.error(`/${cmdName} expanded to an empty prompt — nothing to send.\n\n`));
+                    continue;
+                }
+            }
+        }
+        // Unknown slash → friendly nudge. (Custom commands already matched
+        // above and set isExpandedCommand; only a real unknown reaches here.)
+        if (!isExpandedCommand && trimmed.startsWith("/")) {
             process.stdout.write(ui.error(`unknown command: ${trimmed.split(/\s/)[0]}. type /help for the list.\n\n`));
             continue;
         }
+        // "approve" — exit plan mode and restore the normal tool policy. Only
+        // meaningful while in plan mode; otherwise it's just a chat message.
+        if (session.planMode && /^approve$/i.test(trimmed)) {
+            session.planMode = false;
+            process.stdout.write(ui.info("plan approved — plan mode OFF, normal tool policy restored. Re-send your go-ahead to execute.\n\n"));
+            continue;
+        }
         // If the user typed a bare 1-4 and we just rendered action chips,
         // expand it into the action's prompt — terminal analogue of
         // clicking an amber chip on web.
@@ -489,6 +782,26 @@ export async function runRepl(opts) {
         // forced-spec extractor (interaction.ts) picks them up. Cleared
         // after one turn — same shape the web composer uses.
         let toSend = trimmed;
+        // @-FILE refs — resolve BEFORE the pin/specialist @-scan so any
+        // @<path> that names a real file is inlined (and stripped) rather
+        // than mistaken for a specialist. Path traversal is confined to cwd
+        // and secrets/binaries are skipped (see file_refs.ts). Bare @words
+        // that aren't files are left untouched for the @-mention router.
+        {
+            const refs = resolveFileRefs(toSend, session.cwd);
+            if (refs.attachments.length > 0) {
+                toSend = refs.text;
+                for (const a of refs.attachments) {
+                    const kb = (Buffer.byteLength(a.content, "utf8") / 1024).toFixed(1);
+                    process.stdout.write(ui.info(`◉ inlined @${a.token} (${kb} KB${a.truncated ? ", truncated" : ""})\n`));
+                }
+            }
+            // Surface refused path-like tokens so a silently-skipped @file
+            // doesn't look like it worked.
+            for (const s of refs.skipped) {
+                process.stdout.write(ui.warn(`@${s.token}: ${s.reason}\n`));
+            }
+        }
         let activePins = [];
         if (session.pinnedSpecs.length > 0) {
             activePins = [...session.pinnedSpecs];
@@ -520,7 +833,24 @@ export async function runRepl(opts) {
                 toSend = need.map((s) => "@" + s).join(" ") + " " + toSend;
             }
         }
-        messages.push({ role: "user", content: toSend });
+        // Seed auto-loaded project memory (THERON.md / CLAUDE.md / AGENTS.md)
+        // as the FIRST message of a fresh conversation. The substrate's CLI
+        // message schema has no `system` role, so the memory rides as a
+        // labeled leading `user` note — this works with NO server change. The
+        // same text is ALSO sent as the structured `project_context` field
+        // (see runOneTurn → streamChat) for servers that handle it natively.
+        // Re-seeded after /clear (which empties `messages`) so the model never
+        // loses the repo's rules mid-session.
+        if (messages.length === 0 && projectContext) {
+            messages.push({ role: "user", content: projectContext });
+        }
+        // Plan-mode instruction. The CLI message schema has no `system` role,
+        // so — exactly like projectContext — the instruction rides as a
+        // leading note on this turn's user message. The model MAY ignore it;
+        // 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;
+        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
         // the race we print the amber headline above the streaming text
@@ -536,17 +866,22 @@ export async function runRepl(opts) {
         });
         let planPrinted = false;
         void planPromise.then((p) => {
-            if (p && !planPrinted) {
+            // Headline is interactive chrome — suppress it in headless mode so
+            // stdout stays clean for piping / JSON.
+            if (p && !planPrinted && !opts.headless) {
                 planPrinted = true;
                 process.stdout.write("\n" + ui.planHeadline(p.headline) + "\n");
             }
         });
         // Inner loop: run turn, execute tool calls, repeat until end_turn.
         // We also accumulate the files the model touched (Write/Edit args)
-        // so the verifier pass can scope itself to just this turn's edits.
+        // so the verifier pass can scope itself to just this turn's edits,
+        // and the names of every tool the model invoked (for headless JSON).
         let turnGuard = 0;
         const touchedFiles = new Set();
+        const toolsUsed = [];
         let lastAssistantText = "";
+        let turnErrored = false;
         while (turnGuard < 20) {
             turnGuard += 1;
             const res = await runOneTurn({
@@ -560,10 +895,23 @@ export async function runRepl(opts) {
                 // same pin context, no need to re-announce.
                 pinnedSpecs: turnGuard === 1 ? activePins : undefined,
                 profile: session.profile.slug,
+                projectContext: projectContext || undefined,
                 touchedFilesSink: touchedFiles,
+                toolsUsedSink: toolsUsed,
+                // Plan mode: hard-deny mutating tools at the executor (even with
+                // --yes) and send the model only the read-only tool subset.
+                planMode: session.planMode,
+                tools: session.planMode ? READONLY_TOOL_SCHEMAS : TOOL_SCHEMAS,
+                // Render / headless control the streaming sink: when render-mode
+                // is on (or headless), buffer the text instead of echoing raw
+                // deltas — the answer is emitted once at end (rendered or JSON).
+                bufferText: session.renderMode || !!opts.headless,
+                headless: !!opts.headless,
             });
             if (res.kind === "error") {
-                process.stdout.write(ui.error(res.message) + "\n\n");
+                if (!opts.headless)
+                    process.stdout.write(ui.error(res.message) + "\n\n");
+                turnErrored = true;
                 break;
             }
             if (res.kind === "end_turn") {
@@ -572,11 +920,22 @@ export async function runRepl(opts) {
             }
             // tool_use — keep looping
         }
+        // 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
+        // (bufferText above), so this is the ONLY place the answer prints —
+        // double-printing is structurally impossible. Skipped in headless
+        // (JSON/text payload handles output) and when there's no text.
+        if (session.renderMode && !opts.headless && lastAssistantText) {
+            const useColor = !!process.stdout.isTTY && !process.env.NO_COLOR;
+            const rendered = useColor ? renderMarkdown(lastAssistantText) : lastAssistantText;
+            process.stdout.write("\n" + rendered.replace(/\n+$/, "") + "\n\n");
+        }
         // ── Verifier pass ─────────────────────────────────────────────
         // After the turn settles, run the active profile's verifier kernels
         // against the assistant output + the files it touched. Blocking
         // issues get fed back into the NEXT user message so the model can
         // self-correct. Warnings + info surface inline as a chip.
+        let verifierPayload = null;
         if (session.profile.verifiers && session.profile.verifiers.length > 0) {
             const issues = await runVerifiers(session.profile.verifiers, {
                 cwd: session.cwd,
@@ -585,17 +944,21 @@ export async function runRepl(opts) {
                 profile: session.profile.slug,
             });
             const sum = summarizeIssues(issues);
+            verifierPayload = { ok: sum.ok, summary: sum.summary, details: sum.details };
             if (issues.length === 0) {
-                process.stdout.write(ui.info(`✓ verifiers (${session.profile.verifiers.join(", ")}) green\n\n`));
+                if (!opts.headless)
+                    process.stdout.write(ui.info(`✓ verifiers (${session.profile.verifiers.join(", ")}) green\n\n`));
             }
             else {
-                const head = sum.ok
-                    ? ui.info(`verifiers · ${sum.summary}\n`)
-                    : ui.error(`verifiers · ${sum.summary}\n`);
-                process.stdout.write("\n" + head);
-                for (const line of sum.details)
-                    process.stdout.write(ui.info(line) + "\n");
-                process.stdout.write("\n");
+                if (!opts.headless) {
+                    const head = sum.ok
+                        ? ui.info(`verifiers · ${sum.summary}\n`)
+                        : ui.error(`verifiers · ${sum.summary}\n`);
+                    process.stdout.write("\n" + head);
+                    for (const line of sum.details)
+                        process.stdout.write(ui.info(line) + "\n");
+                    process.stdout.write("\n");
+                }
                 // Stage blocking issues for the next turn — model self-corrects
                 // on the user's next prompt.
                 session.pendingVerifierBlock = formatForNextTurn(issues);
@@ -603,12 +966,28 @@ export async function runRepl(opts) {
         }
         // After the turn settles, surface suggested actions if the plan
         // came back. They render as numbered chips; on the next prompt
-        // the user can type "1" / "2" / "3" to fire one.
+        // the user can type "1" / "2" / "3" to fire one. Suppressed in
+        // headless mode (chips are interactive chrome).
         const plan = await planPromise.catch(() => null);
-        if (plan && plan.suggested_actions.length > 0) {
+        if (!opts.headless && plan && plan.suggested_actions.length > 0) {
             renderSuggestedActions(plan);
             pendingActions = plan.suggested_actions.slice(0, 4);
         }
+        // Persist the conversation after every turn so a later --continue
+        // resumes from here. No-op in headless mode.
+        persistSession();
+        // Headless mode: emit the single payload and exit. The wire format
+        // carries no usage/cost frame, so `cost` is null (never fabricated).
+        if (opts.headless) {
+            emitHeadlessPayload({
+                outputFormat: opts.outputFormat ?? "text",
+                answer: lastAssistantText,
+                toolsUsed,
+                verifier: verifierPayload,
+                sessionId: session.sessionId,
+            });
+            return turnErrored ? 1 : 0;
+        }
         if (opts.oneShot)
             break;
     }
@@ -623,49 +1002,65 @@ async function runOneTurn(args) {
     const toolCalls = [];
     let stopReason = null;
     let firstDelta = true;
+    const headless = args.headless === true;
+    const bufferText = args.bufferText === true;
     // Show the pin header BEFORE thinking spinner so the user knows
-    // immediately that their /pin took effect.
-    if (args.pinnedSpecs && args.pinnedSpecs.length > 0) {
+    // immediately that their /pin took effect. (Suppressed in headless.)
+    if (!headless && args.pinnedSpecs && args.pinnedSpecs.length > 0) {
         process.stdout.write(announcePin(args.pinnedSpecs) + "\n");
     }
     // "thinking…" spinner — fires immediately, clears the moment the
-    // first text delta lands. Removes the awkward silent gap between
-    // prompt submission and first token.
+    // first text delta lands. Spinner writes to stderr; we still skip it in
+    // headless so a `2>&1` redirect can't contaminate parseable output.
     const spinner = new Spinner("thinking…");
-    spinner.start();
+    if (!headless)
+        spinner.start();
     await streamChat({
         apiUrl: args.apiUrl,
         apiKey: args.apiKey,
         messages: args.messages,
-        tools: TOOL_SCHEMAS,
+        tools: args.tools ?? TOOL_SCHEMAS,
         profile: args.profile,
+        projectContext: args.projectContext,
     }, {
         onTextDelta: (d) => {
             if (firstDelta) {
-                spinner.stop();
-                process.stdout.write("\n");
+                if (!headless) {
+                    spinner.stop();
+                    if (!bufferText)
+                        process.stdout.write("\n");
+                }
                 firstDelta = false;
             }
             assistantText += d;
-            process.stdout.write(d);
+            // Buffer-only when render mode / headless is on, so the answer is
+            // emitted once at the end (rendered or as JSON). Otherwise stream
+            // raw deltas live.
+            if (!bufferText)
+                process.stdout.write(d);
         },
         onToolCall: (call) => {
             toolCalls.push(call);
             // Update the spinner label so the user sees what's queued.
-            if (firstDelta)
+            if (firstDelta && !headless)
                 spinner.setLabel(`${call.name}…`);
         },
         onTurnEnd: (reason) => { stopReason = reason; },
         onError: (msg) => {
             stopReason = "error";
-            spinner.stop();
-            process.stdout.write("\n" + announceError(msg) + "\n");
+            if (!headless) {
+                spinner.stop();
+                process.stdout.write("\n" + announceError(msg) + "\n");
+            }
         },
     });
     // Always stop the spinner in case neither delta nor error fired
     // (e.g. immediate turn_end with no content — empty model response).
-    spinner.stop();
-    if (assistantText)
+    if (!headless)
+        spinner.stop();
+    // When streaming raw, close the answer block with spacing. When
+    // buffering, the caller owns final spacing (render / JSON).
+    if (assistantText && !bufferText && !headless)
         process.stdout.write("\n\n");
     args.messages.push({ role: "assistant", content: assistantText, tool_calls: toolCalls });
     if (stopReason === "error")
@@ -683,6 +1078,24 @@ async function runOneTurn(args) {
             });
             continue;
         }
+        // ── PLAN-MODE HARD DENY ───────────────────────────────────────
+        // This runs BEFORE the confirm()/yolo check, so it is the GUARANTEE
+        // (not the schema filter) that no mutating tool can execute in plan
+        // mode — even under --yes / yolo. Stoa (real SaaS side effects) and
+        // Bash (can write via the shell) are denied alongside Write/Edit. The
+        // deny is fed back as a tool result so the model can pivot to a plan.
+        if (args.planMode && MUTATING_TOOLS.has(call.name)) {
+            if (!headless) {
+                process.stdout.write(announceTool(call.name, tool.describe(call.args)) + "\n");
+                process.stdout.write(announceWarn(`[plan mode] ${call.name} is disabled — read-only until you /plan or 'approve'`) + "\n\n");
+            }
+            args.messages.push({
+                role: "tool",
+                tool_call_id: call.id,
+                content: `[plan-mode] ${call.name} is disabled in plan mode. Investigate with read-only tools (Read/Glob/Grep/LS) and propose a numbered plan; do not modify files or run commands.`,
+            });
+            continue;
+        }
         // 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")) {
@@ -694,8 +1107,9 @@ async function runOneTurn(args) {
         }
         // Tool announcement — bullet style matches a list of actions
         // rather than CLI chrome. Single line, brand-amber name + dim
-        // detail.
-        process.stdout.write(announceTool(call.name, tool.describe(call.args)) + "\n");
+        // detail. (Suppressed in headless so stdout stays parseable.)
+        if (!headless)
+            process.stdout.write(announceTool(call.name, tool.describe(call.args)) + "\n");
         if (!args.ctx.yolo && tool.confirmPolicy !== "never") {
             const ok = await confirm(`  Allow ${call.name}?`, args.rl);
             if (!ok) {
@@ -704,37 +1118,74 @@ async function runOneTurn(args) {
                     tool_call_id: call.id,
                     content: `[user denied] User declined to run ${call.name}.`,
                 });
-                process.stdout.write(announceWarn("denied") + "\n\n");
+                if (!headless)
+                    process.stdout.write(announceWarn("denied") + "\n\n");
                 continue;
             }
         }
         // Spinner during tool execution — Bash/Read on a large file can
         // take seconds. Without this the user stares at silence.
         const toolSpin = new Spinner(`running ${call.name}…`);
-        toolSpin.start();
+        if (!headless)
+            toolSpin.start();
         let result;
         try {
             result = await tool.execute(call.args, args.ctx);
-            toolSpin.stop();
+            if (!headless)
+                toolSpin.stop();
+            // Record only tools that actually ran (not denied / plan-blocked).
+            if (args.toolsUsedSink)
+                args.toolsUsedSink.push(call.name);
         }
         catch (err) {
-            toolSpin.stop();
+            if (!headless)
+                toolSpin.stop();
             // Hardened: malformed args / tool throws / fs errors all turn
             // into a structured tool-result string the model can RECOVER
             // from instead of crashing the REPL. The error gets fed back in
             // the conversation so the model can fix its call and try again.
             const errMsg = err instanceof Error ? err.message : String(err);
             result = `[error] ${call.name} failed: ${errMsg}\n\nThe tool call was rejected. Common causes: missing required args, invalid path, file too large, command refused. You can retry with corrected args.`;
-            process.stdout.write(announceError(`${call.name} failed: ${errMsg}`) + "\n");
+            if (!headless)
+                process.stdout.write(announceError(`${call.name} failed: ${errMsg}`) + "\n");
         }
         // Show more of each tool's output in the local CLI preview. The
         // model always sees the full output server-side; the truncation
         // only affects what the user sees in their terminal.
-        process.stdout.write(ui.info(truncatePreview(result, 4000)) + "\n\n");
+        if (!headless)
+            process.stdout.write(ui.info(truncatePreview(result, 4000)) + "\n\n");
         args.messages.push({ role: "tool", tool_call_id: call.id, content: result });
     }
     return { kind: "tool_use" };
 }
+/** Plan-mode instruction. Rides as a leading user note (the CLI message
+ *  schema has no `system` role) — same mechanism as projectContext. The
+ *  executor-side hard deny is the real guarantee; this just biases the
+ *  model toward investigate-and-plan behavior. */
+const PLAN_MODE_INSTRUCTION = "You are in PLAN MODE. Investigate the task using ONLY read-only tools " +
+    "(Read, Glob, Grep, LS). Do NOT modify files or run shell commands — " +
+    "Write, Edit, Bash, and Stoa are disabled and any attempt is rejected. " +
+    "Produce a numbered, ordered plan of the changes you WOULD make, then STOP " +
+    "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. */
+function emitHeadlessPayload(p) {
+    if (p.outputFormat === "json") {
+        const obj = {
+            answer: p.answer,
+            tools_used: p.toolsUsed,
+            verifier: p.verifier,
+            cost: null,
+            session_id: p.sessionId,
+        };
+        process.stdout.write(JSON.stringify(obj) + "\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
@@ -814,8 +1265,4 @@ function expandActionToPrompt(a) {
 function chalkBoldThronWord() {
     return chalk.bold.hex("#FFAE00")("Theron");
 }
-// Expose renderMarkdown so `theron --markdown` mode can pretty-print
-// after the stream finishes if someone wants that flow. Currently the
-// REPL streams raw deltas to keep latency snappy.
-export { renderMarkdown };
 //# sourceMappingURL=repl.js.map