agent-from-zero 0.30.0 → 0.32.0

package/dist/ink/commands.js

@@ -0,0 +1,103 @@
+import chalk from "chalk";
+import path from "node:path";
+import { CONFIG } from "../config.js";
+import { statsReport } from "../telemetry.js";
+import { readMemoryTyped, MEMORY_PATH } from "../memory.js";
+import { getTodos, renderTodos } from "../todos.js";
+import { listBackground } from "../background.js";
+import { listTeam } from "../team.js";
+import { boardSummary } from "../board.js";
+import { undoLast, sessionChanges } from "../undo.js";
+import { renderDiff } from "../diff.js";
+// The non-interactive slash commands: each produces a block of text to commit as
+// a note. Lifted from agent.ts's handleCommand, with console.log → a returned
+// string so the Ink REPL can render them inside its tree. The stateful commands
+// (/clear, /compact, /plan, /model, /resume, /skill) stay in the App — they
+// mutate the conversation or pop an interactive menu.
+// The in-session command reference shown by /help.
+export const SESSION_HELP = `commands:
+  /help      this text
+  /clear     wipe the conversation (and the file read-state) — fresh start
+  /compact   compact the history into a summary right now (happens automatically near the limit)
+  /model     switch model for THIS session: "/model" to pick from a list, "/model <name>" to set; "/model save <name>" to make it your default
+  /stats     event counts for this session (local telemetry — nothing leaves this machine)
+  /memory    show the durable facts the agent remembers about this project
+  /cost      tokens, cache hit rate and estimated spend this session (local)
+  /plan      toggle plan mode — research-only; the agent presents a plan you approve before any change
+  /todos     show the agent's current task plan (it maintains one with todo_write on multi-step work)
+  /bg        list background tasks this session (run_bash_background) and their status
+  /team      list the agent team (spawn_teammate): each teammate's role, status, and pending inbox
+  /tasks     show the shared task board (create_task/claim_task): each task's status, owner, and dependencies
+  /undo      revert the most recent file write (write_file / edit_file) this session
+  /diff      show every file changed this session, as a diff from where it started
+  /resume    list recent sessions in this project and continue one of them
+  /skills    list the reusable skills available in this project
+  /skill <name>  run a skill yourself (works even for user-only skills)
+  exit       leave (Ctrl+C does the same)
+
+keys (at the prompt):
+  Ctrl+R     reveal the model's thinking for the last answer (collapsed behind a spinner by default)
+  Ctrl+T     reveal the folded tool-call trace for the last answer`;
+// Run a non-interactive command. Returns the note text to display, or null if
+// `line` isn't one of these (the App handles the rest).
+export function runInfoCommand(line, ctx) {
+    switch (line) {
+        case "/help":
+            return chalk.dim(SESSION_HELP);
+        case "/cost":
+            return chalk.dim(ctx.costMeter.report()); // tokens, cache hit rate, estimated spend (local)
+        case "/stats":
+            return chalk.dim(statsReport()); // local counters, busiest first
+        case "/memory": {
+            const entries = readMemoryTyped();
+            return chalk.dim(entries.length
+                ? `long-term memory (${MEMORY_PATH}):\n${entries.map((e) => `  [${e.type}] ${e.fact}`).join("\n")}`
+                : `(no long-term memory yet — the model saves facts with the remember tool${CONFIG.memory.autoExtract ? "" : "; turn on settings.memory.autoExtract to capture them automatically"})`);
+        }
+        case "/todos": {
+            const todos = getTodos();
+            return todos.length ? renderTodos(todos) : chalk.dim("(no plan yet — the agent writes one with todo_write on multi-step tasks)");
+        }
+        case "/bg": {
+            const bg = listBackground();
+            if (!bg.length)
+                return chalk.dim("(no background tasks — the agent starts them with run_bash_background for slow commands)");
+            const icon = { running: chalk.yellow("●"), completed: chalk.green("✓"), failed: chalk.red("✗"), killed: chalk.dim("∅") };
+            return chalk.dim("background tasks this session:\n") + bg.map((t) => chalk.dim(`  ${icon[t.status]} ${t.id} [${t.status}, ${t.elapsed}s] — ${t.command.slice(0, 70)}`)).join("\n");
+        }
+        case "/team": {
+            const team = listTeam();
+            if (!team.length)
+                return chalk.dim("(no team — the agent forms one with spawn_teammate for large parallel tasks)");
+            const icon = { active: chalk.yellow("●"), idle: chalk.cyan("◐"), done: chalk.green("✓"), failed: chalk.red("✗") };
+            return (chalk.dim("agent team this session:\n") +
+                team.map((t) => chalk.dim(`  ${icon[t.status] ?? "?"} ${t.name} [${t.status}, ${t.elapsed}s] — ${t.role.slice(0, 60)}${t.pending ? chalk.yellow(` · ${t.pending} unread`) : ""}`)).join("\n"));
+        }
+        case "/tasks": {
+            const summary = boardSummary();
+            return summary === "(the task board is empty)" ? chalk.dim("(no tasks — the lead adds them with create_task; teammates claim them autonomously)") : chalk.dim(`task board:\n${summary}`);
+        }
+        case "/skills": {
+            if (!ctx.skills.length)
+                return chalk.dim("(no skills — add one at .mini-agent/skills/<name>/SKILL.md or ~/.config/mini-agent/skills/)");
+            return (chalk.dim("skills in this project:\n") +
+                ctx.skills.map((s) => chalk.dim(`  ${s.name} [${s.disableModelInvocation ? chalk.yellow("user-only") : chalk.green("model+user")}${chalk.dim("]")} — ${(s.whenToUse || s.description).slice(0, 70)}`)).join("\n"));
+        }
+        case "/undo": {
+            const undone = undoLast();
+            if (!undone)
+                return chalk.dim("(nothing to undo — no file writes recorded this session)");
+            return chalk.dim(`↩ ${undone.summary}`) + "\n" + renderDiff(undone.after ?? "", undone.before ?? "");
+        }
+        case "/diff": {
+            const changes = sessionChanges();
+            if (!changes.length)
+                return chalk.dim("(no file changes this session)");
+            const verb = { created: chalk.green("created"), modified: chalk.yellow("modified"), deleted: chalk.red("deleted") };
+            const head = chalk.dim(`${changes.length} file${changes.length === 1 ? "" : "s"} changed this session:`);
+            return head + "\n" + changes.map((c) => `\n${verb[c.status]} ${path.relative(process.cwd(), c.path) || c.path}\n${renderDiff(c.baseline, c.current)}`).join("");
+        }
+        default:
+            return null; // not an info command — the App handles it (or it's a normal task line)
+    }
+}

package/dist/ink/launch.js

@@ -0,0 +1,15 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { render } from "ink";
+import { buildInkSession } from "./setup.js"; // the front-end-agnostic session bootstrap
+import { makeRunTurn } from "./chat.js"; // drives one turn through the real loop
+import { App } from "./app.js"; // the Ink REPL
+// Launch the Ink REPL and resolve when it exits. buildInkSession does the same
+// wiring agent.ts does (MCP, skills, judge, memory, cost, hooks, telemetry,
+// optional resume); App renders it and runs the loop. Exported so BOTH the
+// `npm run ink` entry (main.tsx) and agent.ts (the default `mini-agent` entry,
+// once it hands interactive sessions to Ink) can start it.
+export async function launchInk(opts = {}) {
+    const session = await buildInkSession({ resume: opts.resume });
+    const { waitUntilExit } = render(_jsx(App, { session: session, runTurn: makeRunTurn(session.client, session.messages) }));
+    await waitUntilExit(); // keep the process alive until the user quits
+}

package/dist/ink/main.js

@@ -0,0 +1,4 @@
+import { launchInk } from "./launch.js"; // the reusable launcher (shared with agent.ts)
+// Direct entry for the Ink REPL: npm run ink. agent.ts launches the same thing
+// for a normal `mini-agent` interactive session.
+await launchInk({ resume: process.argv.includes("-r") || process.argv.includes("--resume") });

package/dist/ink/setup.js

@@ -0,0 +1,102 @@
+import OpenAI from "openai";
+import path from "node:path";
+import { createRequire } from "node:module";
+import { CONFIG, requireApiKey } from "../config.js";
+import { buildSystemMessage } from "../prompt.js";
+import { estimateHistoryTokens } from "../context.js";
+import { initCostMeter, DEFAULT_PRICING } from "../cost.js";
+import { gitBranch } from "../tui.js";
+import { newSessionId, latestSession } from "../session.js";
+import { initTelemetry, emit } from "../telemetry.js";
+import { runHooks } from "../hooks.js";
+import { connectMcpServers } from "../mcp.js";
+import { Judge } from "../judge.js";
+import { registerExternalTool } from "../tools.js";
+import { rememberTool, readMemory } from "../memory.js";
+import { loadSkills, buildSkillTool } from "../skills.js";
+import { killAllBackground } from "../background.js";
+import { banner } from "../ui.js";
+// The Ink REPL's session bootstrap — the same wiring agent.ts (the readline REPL)
+// does before the prompt loop, but front-end-agnostic: it touches none of
+// readline/editLine, just the shared modules (MCP, skills, judge, memory, cost,
+// hooks, telemetry, session). It returns everything the Ink App needs to run a
+// real session, so main.tsx stays a thin render() call. (agent.ts is left
+// untouched so `npm start` keeps working until 2d flips the default.)
+const pkg = createRequire(import.meta.url)("../../package.json");
+// Build the session. `resume` mirrors `-r/--resume`: fold the most recent
+// conversation in this directory into the fresh constitution.
+export async function buildInkSession(opts = {}) {
+    requireApiKey();
+    const client = new OpenAI({ baseURL: CONFIG.baseURL, apiKey: CONFIG.apiKey, maxRetries: 0 });
+    const systemMessage = buildSystemMessage(); // stable prefix = cache hits every request
+    const messages = [{ role: "system", content: systemMessage }];
+    const notices = [];
+    let sessionId = newSessionId();
+    const startedAt = Date.now();
+    if (opts.resume) {
+        const prev = latestSession();
+        if (prev) {
+            messages.push(...prev.messages);
+            sessionId = prev.id; // keep appending to the same file
+            notices.push(`(resumed session ${prev.id} — ${prev.messages.length} messages; files must be re-read before editing)`);
+        }
+        else {
+            notices.push("(no previous session here — starting fresh)");
+        }
+    }
+    initTelemetry(sessionId);
+    emit("agent_session_start", { mode: "repl" });
+    // MCP servers — must finish before the first model call so their tools appear
+    // in the manual. A server that fails to start is skipped, never fatal.
+    const disconnectMcp = await connectMcpServers();
+    process.on("exit", disconnectMcp);
+    process.on("exit", killAllBackground); // SIGKILL any background job so it never outlives the agent
+    const judge = CONFIG.judge.enabled ? new Judge(client, CONFIG.judge.model || CONFIG.model) : undefined;
+    if (judge)
+        notices.push(`(permission judge on — model ${CONFIG.judge.model || CONFIG.model})`);
+    // The remember tool flows through the same permission gate as any tool.
+    registerExternalTool(rememberTool);
+    const memCount = readMemory().length;
+    if (memCount)
+        notices.push(`(long-term memory: ${memCount} facts loaded)`);
+    // Skills: model-invocable ones get the single `skill` tool; user-only ones are
+    // reachable via /skill <name>.
+    const skills = loadSkills();
+    if (skills.some((s) => !s.disableModelInvocation))
+        registerExternalTool(buildSkillTool(skills));
+    if (skills.length)
+        notices.push(`(skills: ${skills.length} loaded — ${skills.map((s) => s.name).join(", ")})`);
+    const costMeter = initCostMeter({
+        inputPerM: CONFIG.pricing.inputPerM ?? DEFAULT_PRICING.inputPerM,
+        cachedInputPerM: CONFIG.pricing.cachedInputPerM ?? DEFAULT_PRICING.cachedInputPerM,
+        outputPerM: CONFIG.pricing.outputPerM ?? DEFAULT_PRICING.outputPerM,
+    });
+    // SessionStart hooks run once; their stdout becomes context on the first turn.
+    const sessionStart = await runHooks("SessionStart", {});
+    if (sessionStart.stdout)
+        messages.push({ role: "user", content: `[SessionStart hook]\n${sessionStart.stdout}` });
+    const dir = path.basename(process.cwd());
+    const branch = gitBranch();
+    const getStatus = () => ({
+        ctxPct: Math.min(100, Math.round((estimateHistoryTokens(messages) / CONFIG.contextWindow) * 100)),
+        cost: costMeter.cost(),
+        elapsedMs: Date.now() - startedAt,
+    });
+    return {
+        client,
+        messages,
+        systemMessage,
+        initialSessionId: sessionId,
+        startedAt,
+        costMeter,
+        skills,
+        judge,
+        model: CONFIG.model,
+        dir,
+        branch,
+        bannerText: banner(pkg.version, CONFIG.model, new URL(CONFIG.baseURL).host),
+        notices,
+        getStatus,
+        disconnectMcp,
+    };
+}

package/dist/ink/sink.js

@@ -0,0 +1,50 @@
+// Build a LoopOutput backed by Ink state. Pure glue: every method maps a loop
+// event to a state change.
+export function makeInkSink(api) {
+    return {
+        // A spinner becomes the single "status" line below the conversation. A fresh
+        // handle per model call (the loop makes one per round); `active` mirrors
+        // ora's isSpinning so the loop's `spinner?.spinning` checks behave the same.
+        spinner(text) {
+            api.setStatus(text);
+            let active = true;
+            return {
+                set: (t) => {
+                    if (active)
+                        api.setStatus(t);
+                },
+                stop: () => {
+                    if (active) {
+                        active = false;
+                        api.setStatus(null);
+                    }
+                },
+                get spinning() {
+                    return active;
+                },
+            };
+        },
+        // The "💭 thought for Ns" indicator is just a committed line.
+        reasoning: (line) => api.pushItem({ kind: "note", text: line }),
+        // The streamed answer accumulates in the dynamic region as raw text (live,
+        // "it's typing"), then commits as ONE markdown-rendered item when it ends —
+        // partial markdown mid-stream renders badly, so we format only once it's whole.
+        answer() {
+            let buf = "";
+            api.setLive("");
+            return {
+                push: (tok) => {
+                    buf += tok;
+                    api.setLive(buf);
+                },
+                end: () => {
+                    api.setLive(null); // clear the live preview first, then commit (no flicker/duplicate)
+                    if (buf.trim())
+                        api.pushItem({ kind: "answer", text: buf });
+                },
+            };
+        },
+        // Generic narration — already chalk-formatted by the loop; just commit it.
+        note: (line) => api.pushItem({ kind: "note", text: line }),
+    };
+}

package/dist/loop.js

@@ -1,5 +1,4 @@
 import chalk from "chalk"; // terminal colors for status lines
-import ora from "ora"; // the "thinking..." spinner while waiting for the first token
 import { toolDefinitions, dispatch, snapshotFileState, restoreFileState, isReadOnlyTool } from "./tools.js"; // the tool manuals + the executor + file-state isolation
 import { classifyError, ApiErrorKind } from "./errors.js"; // failure taxonomy
 import { checkPermission } from "./permissions.js"; // the allow/ask/deny gate
@@ -13,7 +12,7 @@ import { runHooks } from "./hooks.js"; // user lifecycle hooks (PreToolUse / Pos
 import { recordUsage } from "./cost.js"; // meter token usage from the stream
 import { mark, thinkingWord, spinnerText } from "./ui.js"; // centralized terminal styling (markers, spinner)
 import { recordToolCall, recordReasoning } from "./tui.js"; // folded tool-call trace (Ctrl+T) + the model's hidden thinking (Ctrl+R)
-import { MarkdownStream } from "./markdown.js"; // render the streamed answer as terminal markdown
+import { STDOUT_OUTPUT } from "./output.js"; // where the loop's screen output goes (stdout by default, Ink REPL passes its own)
 import { todoNag, getTodos, renderTodos } from "./todos.js"; // the agent's plan: show it on screen + nag when it goes stale
 import { pendingNotifications } from "./background.js"; // background tasks (Day 37): surface finished jobs as a turn
 export const MAX_RETRIES = 10; // total failed API calls per query, across all rounds
@@ -36,6 +35,11 @@ export var TerminateReason;
     TerminateReason["FatalApiError"] = "fatal_api_error";
     TerminateReason["UserInterrupt"] = "user_interrupt";
 })(TerminateReason || (TerminateReason = {}));
+// Resolve the output sink for a loop: the caller's sink, or stdout (the old
+// behaviour) when none was passed. Centralised so every site reads the same way.
+function sink(opts) {
+    return opts.output ?? STDOUT_OUTPUT;
+}
 // Which model should a delegated sub-agent run on? The configured sub-agent
 // model if set and non-blank, otherwise the same model as the orchestrator.
 // Pulled out as a pure function so the tiering rule is testable on its own.
@@ -281,7 +285,7 @@ async function runSubAgent(description, opts) {
     // Show the delegation, and the model when it differs from the orchestrator's —
     // the tiering should be visible, not a silent surprise on the bill.
     if (!opts.quiet)
-        console.log(mark.subAgentStart(description.slice(0, 100), subModel !== opts.model ? subModel : "")); // annotate the tier only on a real switch
+        sink(opts).note(mark.subAgentStart(description.slice(0, 100), subModel !== opts.model ? subModel : "")); // annotate the tier only on a real switch
     await runHooks("SubagentStart", { description: description.slice(0, 200), model: subModel }); // lifecycle hook (observational)
     const snapshot = snapshotFileState(); // what the sub-agent reads, the parent has NOT seen
     try {
@@ -301,7 +305,7 @@ async function runSubAgent(description, opts) {
         restoreFileState(snapshot); // the parent's read-before-edit state, exactly as it was
         await runHooks("SubagentStop", { description: description.slice(0, 200) }); // lifecycle hook (observational)
         if (!opts.quiet)
-            console.log(mark.subAgentDone); // close the bracket
+            sink(opts).note(mark.subAgentDone); // close the bracket
     }
 }
 // Exponential backoff with jitter: 500ms, 1s, 2s, ... ±25%, capped.
@@ -335,7 +339,7 @@ opts) {
     let reasoningShown = false; // have we printed the "thought for Ns" indicator yet?
     const spinner = opts.quiet
         ? null // the eval harness wants silence
-        : ora({ text: spinnerText(word, 0, !!opts.subAgent, opts.model), discardStdin: false }).start(); // discardStdin:false — ora would otherwise eat Ctrl+C
+        : sink(opts).spinner(spinnerText(word, 0, !!opts.subAgent, opts.model)); // a fresh spinner from the sink (stdout → ora; Ink → React state)
     let lastEvent = Date.now(); // when did we last hear ANYTHING from the stream?
     let stallWarned = false; // only warn once per quiet stretch
     // The two-level watchdog, checked once per second:
@@ -345,8 +349,8 @@ opts) {
     const watchdog = setInterval(() => {
         // While the model is reasoning, prefix the spinner with 💭 so "it's thinking"
         // reads differently from "it's waiting on the first token".
-        if (spinner?.isSpinning)
-            spinner.text = (reasoningActive ? chalk.dim("💭 ") : "") + spinnerText(word, Math.floor((Date.now() - startedAt) / 1000), !!opts.subAgent, opts.model, Math.round(streamedChars / 4));
+        if (spinner?.spinning)
+            spinner.set((reasoningActive ? chalk.dim("💭 ") : "") + spinnerText(word, Math.floor((Date.now() - startedAt) / 1000), !!opts.subAgent, opts.model, Math.round(streamedChars / 4)));
         const quietMs = Date.now() - lastEvent; // ms since the last event
         if (quietMs > IDLE_TIMEOUT_MS) {
             emit("agent_watchdog_idle"); // record the cut — these should be rare
@@ -355,7 +359,7 @@ opts) {
         else if (quietMs > STALL_WARN_MS && !stallWarned) {
             stallWarned = true; // don't repeat the warning every second
             emit("agent_watchdog_stall"); // record the slowness — pattern-spotting data
-            console.log(chalk.dim(`  [watchdog] stream quiet for ${Math.round(quietMs / 1000)}s — still waiting (slow ≠ dead)`));
+            sink(opts).note(chalk.dim(`  [watchdog] stream quiet for ${Math.round(quietMs / 1000)}s — still waiting (slow ≠ dead)`));
         }
     }, 1000);
     try {
@@ -370,8 +374,7 @@ opts) {
         // teammate's manual simply omits spawn_teammate and task.
         { model: opts.model, messages, tools: toolsFor(opts), stream: true, stream_options: { include_usage: true } }, { signal });
         let content = ""; // accumulated answer text
-        let printedPrefix = false; // have we printed the answer prefix yet?
-        let md = null; // renders the streamed answer as markdown, block by block
+        let ans = null; // renders the streamed answer (stdout: markdown block by block; Ink: React state) — non-null once the answer starts
         const calls = []; // tool calls under assembly, indexed by delta.index
         // The model has finished thinking and is about to say/do something. Close out
         // the spinner, stash the trace, and print a single one-line indicator with the
@@ -382,7 +385,7 @@ opts) {
                 return;
             reasoningShown = true;
             reasoningActive = false;
-            if (spinner?.isSpinning)
+            if (spinner?.spinning)
                 spinner.stop();
             if (opts.quiet || opts.subAgent)
                 return; // no UI for silent / nested runs
@@ -390,7 +393,7 @@ opts) {
             const secs = Math.round((Date.now() - startedAt) / 1000);
             const toks = Math.round(reasoningBuf.length / 4); // same ~chars/4 estimate as the spinner
             const tokStr = toks >= 1000 ? `${(toks / 1000).toFixed(1)}k` : `${toks}`;
-            process.stdout.write(chalk.dim(`💭 thought for ${secs}s (~${tokStr} tokens) · Ctrl+R to view`) + "\n");
+            sink(opts).reasoning(chalk.dim(`💭 thought for ${secs}s (~${tokStr} tokens) · Ctrl+R to view`));
         };
         for await (const chunk of stream) {
             lastEvent = Date.now(); // feed the watchdog
@@ -414,27 +417,24 @@ opts) {
             if (delta.content) {
                 flushReasoning(); // thinking is over — show the one-line indicator first
                 streamedChars += delta.content.length; // count the answer toward the live token estimate
-                if (spinner?.isSpinning)
+                if (spinner?.spinning)
                     spinner.stop(); // first token: replace the spinner with real output
                 if (!opts.quiet && !opts.subAgent) {
                     // Only the top-level agent streams to the screen — a sub-agent's
-                    // inner monologue would be mistaken for the answer.
-                    if (!printedPrefix) {
-                        // Stream the answer through the markdown renderer: it buffers a block
-                        // (paragraph / heading / list / table) and prints it formatted the
-                        // moment that block completes — still live, but no raw `##`/`|---|`.
-                        // The ⏺ marker leads the first line; wrapped lines align under it.
-                        md = new MarkdownStream((s) => process.stdout.write(s), { firstPrefix: "\n" + mark.answer, indent: "  " });
-                        printedPrefix = true;
-                    }
-                    md.push(delta.content); // hand the token to the renderer (it decides when to paint)
+                    // inner monologue would be mistaken for the answer. The sink decides
+                    // how to paint: the stdout sink buffers a markdown block (paragraph /
+                    // heading / list / table) and flushes it whole — live, but no raw
+                    // `##`/`|---|`; the Ink sink accumulates into React state.
+                    if (!ans)
+                        ans = sink(opts).answer(); // first token: start the answer renderer
+                    ans.push(delta.content); // hand the token to the renderer (it decides when to paint)
                 }
                 content += delta.content; // always keep it for the history (the answer only, never the reasoning)
             }
             if (delta.tool_calls?.length)
                 flushReasoning(); // thinking is over — indicator before the tool logs (which print after we return)
             for (const tc of delta.tool_calls ?? []) {
-                if (spinner?.isSpinning)
+                if (spinner?.spinning)
                     spinner.stop(); // tool call starting — spinner served its purpose
                 const slot = (calls[tc.index] ??= { id: "", name: "", args: "" }); // create the slot on first fragment
                 if (tc.id)
@@ -446,15 +446,13 @@ opts) {
             }
         }
         flushReasoning(); // a reasoning-only turn (no content, no tools) still records + indicates
-        if (md)
-            md.end(); // flush the final (un-terminated) block through the renderer
-        if (printedPrefix)
-            process.stdout.write("\n"); // end the streamed line cleanly
+        if (ans)
+            ans.end(); // flush the final (un-terminated) block + end the line cleanly (the sink owns the trailing newline)
         return { content, toolCalls: calls.filter(Boolean) }; // sparse array → dense
     }
     finally {
         clearInterval(watchdog); // always stop the timer
-        if (spinner?.isSpinning)
+        if (spinner?.spinning)
             spinner.stop(); // and never leave a zombie spinner
     }
 }
@@ -487,13 +485,13 @@ async function runOneCall(call, opts) {
     if (!opts.quiet && v.decision !== "deny" && (call.name === "write_file" || call.name === "edit_file")) {
         const preview = previewChange(call.name, call.args);
         if (preview)
-            console.log(preview.replace(/^/gm, indent)); // nest under the sub-agent marker if any
+            sink(opts).note(preview.replace(/^/gm, indent)); // nest under the sub-agent marker if any
     }
     let content; // what goes back to the model as the tool result
     if (v.decision === "deny") {
         emit("agent_tool_denied", { tool: call.name }); // hard blocks, per tool
         if (!opts.quiet)
-            console.log(mark.denied(v.reason)); // tell the user we blocked it
+            sink(opts).note(mark.denied(v.reason)); // tell the user we blocked it
         content = `[permission] Denied: ${v.reason}. This is a hard rule — do not try to work around it; pick a different approach or ask the user.`; // teach the model the boundary
     }
     else if (v.decision === "ask") {
@@ -510,14 +508,14 @@ async function runOneCall(call, opts) {
             if (cmd && (await opts.judge.classify(cmd)) === "allow") {
                 autoAllowed = true;
                 if (!opts.quiet)
-                    console.log(mark.judge); // visible — the user can see the judge worked
+                    sink(opts).note(mark.judge); // visible — the user can see the judge worked
             }
         }
         const ok = autoAllowed || (await opts.confirm(`${call.name} (${v.reason}):\n   ${v.summary}`, call.name)); // judge-allowed, or pause and ask the human
         if (!ok)
             emit("agent_tool_declined", { tool: call.name }); // the human said no — that is signal
         if (!ok && !opts.quiet)
-            console.log(mark.declined); // make the refusal visible
+            sink(opts).note(mark.declined); // make the refusal visible
         content = ok
             ? await runWithHooks(call, opts) // approved — run it (PreToolUse can still block)
             : `[permission] The user declined this action. Ask them how to proceed, or choose a safer alternative.`; // declined — tell the model
@@ -528,7 +526,7 @@ async function runOneCall(call, opts) {
     // todo_write's whole point is the VISIBLE plan: the model got a one-line tally,
     // the human gets the rendered checklist (quiet runs — eval/sub-agents — stay silent).
     if (call.name === "todo_write" && !opts.quiet && !content.startsWith("[error]")) {
-        console.log(renderTodos(getTodos()));
+        sink(opts).note(renderTodos(getTodos()));
     }
     return { id: call.id, content }; // paired by id for the API
 }
@@ -546,7 +544,7 @@ async function runWithHooks(call, opts) {
     if (pre.block) {
         emit("agent_hook_block", { event: "PreToolUse", tool: call.name }); // a hook said no
         if (!opts.quiet)
-            console.log(mark.hookBlock("PreToolUse")); // make it visible
+            sink(opts).note(mark.hookBlock("PreToolUse")); // make it visible
         return `[hook] A PreToolUse hook blocked this call: ${pre.feedback}. Treat this as a hard boundary — adjust your approach.`;
     }
     // A PreToolUse hook may REWRITE the arguments (e.g. add a commit trailer). The
@@ -556,7 +554,7 @@ async function runWithHooks(call, opts) {
         try {
             JSON.parse(pre.rewrite); // must be valid JSON args
             if (!opts.quiet)
-                console.log(chalk.dim(`  ⎿ PreToolUse hook rewrote the arguments`));
+                sink(opts).note(chalk.dim(`  ⎿ PreToolUse hook rewrote the arguments`));
             call = { ...call, args: pre.rewrite };
         }
         catch {
@@ -744,7 +742,7 @@ async function runCreateTask(call, opts) {
         return "[error] create_task needs a 'subject'.";
     const task = createTask(subject, description, blockedBy);
     if (!opts.quiet)
-        console.log(chalk.magenta(`  ⎿ ${boardActor(opts)} created ${task.id}: ${subject.slice(0, 50)}`));
+        sink(opts).note(chalk.magenta(`  ⎿ ${boardActor(opts)} created ${task.id}: ${subject.slice(0, 50)}`));
     return `Created ${task.id}: "${subject}"${blockedBy.length ? ` (blockedBy: ${blockedBy.join(", ")})` : ""}. It's on the board for a teammate to claim.`;
 }
 async function runListTasks(_call, opts) {
@@ -781,7 +779,7 @@ async function runCompleteTask(call, opts) {
     if (!res.ok)
         return `[error] ${res.error}`;
     if (!opts.quiet)
-        console.log(chalk.magenta(`  ⎿ ${boardActor(opts)} completed ${taskId}`));
+        sink(opts).note(chalk.magenta(`  ⎿ ${boardActor(opts)} completed ${taskId}`));
     const unblocked = res.unblocked?.length ? ` Unblocked: ${res.unblocked.join(", ")}.` : "";
     return `Completed ${taskId}.${unblocked} Claim the next ready task, or idle until the lead shuts you down.`;
 }
@@ -817,7 +815,7 @@ async function runSpawnTeammate(call, opts) {
     const done = runTeammate(name, role, task, opts);
     registerTeammate(name, role, done);
     if (!opts.quiet)
-        console.log(mark.teammateStart(name, role));
+        sink(opts).note(mark.teammateStart(name, role));
     return `Teammate "${name}" (${role}) spawned and is now working in parallel. It will message you (as "lead") with progress and its final result. Reply with send_message; keep coordinating the rest of the team. Do not wait idly — continue your own work.`;
 }
 // Run one teammate to completion: a fresh conversation seeded with its task, a
@@ -847,7 +845,7 @@ async function runTeammate(name, role, task, opts) {
             subAgent: true,
             teammate: { name },
             maxRounds: TEAMMATE_MAX_ROUNDS,
-            confirm: teammateConfirm(name),
+            confirm: teammateConfirm(name, sink(opts)),
             askUser: undefined, // teammates have no line to the human
         });
         // How it ended decides what the lead hears. A shutdown handshake gets a
@@ -861,7 +859,7 @@ async function runTeammate(name, role, task, opts) {
             sendMessage(name, LEAD, summary, "result");
         finishTeammate(name, result.reason === TerminateReason.Done);
         if (!opts.quiet)
-            console.log(mark.teammateDone(name, result.reason === TerminateReason.Done));
+            sink(opts).note(mark.teammateDone(name, result.reason === TerminateReason.Done));
     }
     catch (err) {
         // A teammate must never take the whole process down. Report the failure to
@@ -885,11 +883,11 @@ const SHUTDOWN_GRACE_MS = 30_000; // how long the lead waits for teammates to ex
 // DENY rules (the no-fly zone) are enforced by the gate before confirm is ever
 // called, so they always hold. Production Claude Code instead "bubbles" the
 // request up to the lead and on to the human — omitted here, like the reference.
-function teammateConfirm(name) {
+function teammateConfirm(name, output) {
     return async (_question, toolName) => {
         const ok = toolName === "write_file" || toolName === "edit_file";
         if (!ok)
-            console.log(chalk.yellow(`  ⎿ [${name}] declined ${toolName ?? "an action"} (teammates can't prompt you; do it yourself or allowlist it)`));
+            output.note(chalk.yellow(`  ⎿ [${name}] declined ${toolName ?? "an action"} (teammates can't prompt you; do it yourself or allowlist it)`));
         return ok;
     };
 }
@@ -925,7 +923,7 @@ compaction) {
     try {
         if (!opts.subAgent)
             await runHooks("PreCompact", {}); // lifecycle hook (top-level only; hooks are the human's project policy)
-        await compactHistory(messages, opts.client, opts.model, opts.signal); // do the actual work
+        await compactHistory(messages, opts.client, opts.model, opts.signal, (s) => sink(opts).note(s)); // do the actual work — narration through the sink (so it doesn't corrupt an Ink live region)
         compaction.count++; // one more successful compaction this query
         compaction.failures = 0; // success resets the failure streak
         emit("agent_compaction_ok"); // worth counting — frequent compaction means tasks are too big
@@ -956,7 +954,7 @@ function injectBackgroundNotifications(messages, opts) {
     const count = (note.match(/<task_notification>/g) ?? []).length; // for the one-line on-screen mark
     messages.push({ role: "user", content: note }); // the model reacts to it on the next round
     if (!opts.quiet)
-        console.log(mark.bgNote(count));
+        sink(opts).note(mark.bgNote(count));
     return true;
 }
 // Consume this agent's mailbox into its conversation, ROUTING protocol messages
@@ -1005,7 +1003,7 @@ function consumeInbox(messages, opts) {
     const header = opts.teammate ? "Messages from your team — read and act on them:" : "Team inbox — react to these (RESULT = that teammate finished a part):";
     messages.push({ role: "user", content: `${header}\n\n${lines.join("\n\n")}` });
     if (!opts.quiet)
-        console.log(opts.teammate ? chalk.dim(`  ⎿ [${me}] received ${msgs.length} message(s)`) : mark.inbox(msgs.length));
+        sink(opts).note(opts.teammate ? chalk.dim(`  ⎿ [${me}] received ${msgs.length} message(s)`) : mark.inbox(msgs.length));
     return true;
 }
 // At a stop-point (no tool calls), decide whether the TEAM keeps this agent's
@@ -1041,7 +1039,7 @@ async function continueForTeam(messages, opts) {
                 // reference's identity-reinjection, folded into the work hand-off).
                 messages.push({ role: "user", content: `You are ${me}. You claimed task ${claimed.id} from the board: "${claimed.subject}".\n${claimed.description}\nWhen it is done and verified, call complete_task("${claimed.id}") — then you'll be offered the next ready task.` });
                 if (!opts.quiet)
-                    console.log(chalk.magenta(`  ⎿ [${me}] claimed ${claimed.id}: ${claimed.subject.slice(0, 50)}`));
+                    sink(opts).note(chalk.magenta(`  ⎿ [${me}] claimed ${claimed.id}: ${claimed.subject.slice(0, 50)}`));
                 setTeammateState(me, "active");
                 return true;
             }
@@ -1069,7 +1067,7 @@ async function shutdownTeam(opts) {
     if (!running.length)
         return;
     if (!opts.quiet)
-        console.log(chalk.magenta(`  ⎿ disbanding team — shutting down ${running.length} teammate(s)`));
+        sink(opts).note(chalk.magenta(`  ⎿ disbanding team — shutting down ${running.length} teammate(s)`));
     for (const name of running) {
         const id = createRequest("shutdown", LEAD, name, "task complete");
         markShutdown(name, id);
@@ -1152,7 +1150,7 @@ opts) {
                 if (attempts.total >= MAX_RETRIES)
                     return { reason: TerminateReason.RetryBudgetExhausted, detail: `${e.kind}: ${e.message}` };
                 const wait = backoffMs(attempts.consecutive); // how long to back off this time
-                console.log(chalk.dim(`  [retry] ${e.kind} — attempt ${attempts.total}/${MAX_RETRIES}, waiting ${wait}ms`)); // retries must be visible, or the app just looks frozen
+                sink(opts).note(chalk.dim(`  [retry] ${e.kind} — attempt ${attempts.total}/${MAX_RETRIES}, waiting ${wait}ms`)); // retries must be visible, or the app just looks frozen
                 await interruptibleSleep(wait, opts.isInterrupted); // wait, but stay responsive to Ctrl+C
                 continue; // retry the same round
             }
@@ -1187,7 +1185,7 @@ opts) {
                     if (stop.block) {
                         emit("agent_hook_block", { event: "Stop" }); // the agent was sent back to work
                         if (!opts.quiet)
-                            console.log(chalk.yellow(`\n↩ Stop hook: not done yet — ${stop.feedback.slice(0, 120)}`)); // show why
+                            sink(opts).note(chalk.yellow(`\n↩ Stop hook: not done yet — ${stop.feedback.slice(0, 120)}`)); // show why
                         messages.push({ role: "user", content: `[Stop hook] You are not finished: ${stop.feedback}` }); // inject the instruction
                         break; // exit the inner while → advance the round counter
                     }
@@ -1235,7 +1233,7 @@ opts) {
             // Fold this round's tool calls into ONE tally line instead of one line per
             // call (the per-call announcements were recorded for Ctrl+T in runOneCall).
             if (!opts.quiet && out.toolCalls.length) {
-                console.log(agentIndent(opts) + mark.toolTally(out.toolCalls.map((c) => c.name)) + chalk.dim(" · Ctrl+T"));
+                sink(opts).note(agentIndent(opts) + mark.toolTally(out.toolCalls.map((c) => c.name)) + chalk.dim(" · Ctrl+T"));
             }
             // Background tasks (Day 37): if a job the model started has finished, slip
             // its <task_notification> in here, right after this round's tool results —
@@ -1255,7 +1253,7 @@ opts) {
                 if (nag) {
                     messages.push({ role: "user", content: nag });
                     if (!opts.quiet)
-                        console.log(chalk.dim("  ⎿ plan reminder injected"));
+                        sink(opts).note(chalk.dim("  ⎿ plan reminder injected"));
                 }
             }
             break; // round complete, move to the next one