roforge-cli 0.3.1 → 0.3.3

package/bin/roforge.js

@@ -9,7 +9,7 @@ import { Session } from "../src/session.js";
 import { BridgeServer } from "../src/bridge/server.js";
 import { probeMcp } from "../src/mcp.js";
 import { TUI } from "../src/tui/tui.js";
-import { bold, dim, red, green, cyan, yellow, gray } from "../src/tui/ansi.js";
+import { bold, dim, red, green, cyan, yellow, gray, magenta } from "../src/tui/ansi.js";
 
 const argv = process.argv.slice(2);
 const command = argv[0] || "tui";
@@ -262,6 +262,39 @@ async function main() {
       return;
     }
 
+    case "pro": {
+      const { queryProStatus, renderProStatus, probeBridge, startOwnBridge } = await import("../src/pro.js");
+      const port = flags.port ? Number(flags.port) : cfg.bridge.port;
+      const host = cfg.bridge.host;
+      const token = cfg.bridge.token;
+      const base = `http://${host}:${port}`;
+      console.log(bold("RoForge Pro") + dim(" — license status\n"));
+      // Attach to an already-running bridge (e.g. `roforge studio`);
+      // otherwise start a throwaway one for the plugin to connect to.
+      const health = await probeBridge(base);
+      if (health) {
+        const res = await queryProStatus(null, { port, token, baseUrl: base });
+        console.log(renderProStatus(res, { bold, dim, red, green, magenta, yellow }) + "\n");
+        return;
+      }
+      const bridge = startOwnBridge({ port, host, token });
+      try {
+        await bridge.start();
+      } catch (e) {
+        console.error(red(`bridge could not start on port ${port}: ${e.message}`));
+        process.exit(1);
+      }
+      // The plugin pings every ~1s; give it a moment to show up if it's up.
+      const deadline = Date.now() + 6000;
+      while (!bridge.connected && Date.now() < deadline) {
+        await new Promise((r) => setTimeout(r, 250));
+      }
+      const res = await queryProStatus(bridge, { port, token });
+      console.log(renderProStatus(res, { bold, dim, red, green, magenta, yellow }) + "\n");
+      bridge.stop();
+      return;
+    }
+
     case "help":
     case "--help":
     case "-h": {
@@ -375,6 +408,7 @@ ${bold("Usage")}
   roforge tools               list all tools
   roforge login --provider <p> store a key (gemini|groq|openrouter|anthropic|openai)
   roforge providers           list providers, keys, and auto-routing order
+  roforge pro                 show RoForge Pro license status (needs Studio bridge)
   roforge analyze <file...>   run the official Luau analyzer on files
   roforge config [set k v]    show / set configuration
   roforge version
@@ -389,7 +423,7 @@ ${bold("Model providers (BYOK, zero backend)")}
   auto (default): first configured key wins, free tiers first:
   gemini → groq → openrouter → anthropic → openai
   free tiers: Gemini 2.5 Flash (~1,500 req/day), Groq Llama 3.3 70B (~1,000 req/day),
-  OpenRouter ":free" models (e.g. qwen/qwen3-coder:free)
+  OpenRouter ":free" models (e.g. nvidia/nemotron-3-super-120b-a12b:free)
   pin: --provider <p> or --model <provider>:<model> · ROFORGE_FREE_FIRST=0
 
 ${bold("Config & keys")}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "roforge-cli",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "RoForge \u2014 Claude-Code-style local AI agent for Roblox Studio. BYOK, zero backend, zero dependencies.",
   "type": "module",
   "bin": {

package/src/bridge/server.js

@@ -10,11 +10,12 @@ import http from "node:http";
 import { json } from "./wire.js";
 
 export class BridgeServer {
-  constructor({ port, host = "127.0.0.1", token, jobTimeoutMs = 60000 }) {
+  constructor({ port, host = "127.0.0.1", token, jobTimeoutMs = 60000, completedTtlMs = 30000 }) {
     this.port = port;
     this.host = host;
     this.token = token;
     this.jobTimeoutMs = jobTimeoutMs;
+    this.completedTtlMs = completedTtlMs;
     this.jobs = new Map(); // id → {id, tool, args, status, resolve, timer}
     this.lastPingAt = null;
     this.lastSeenAt = null;
@@ -45,7 +46,7 @@ export class BridgeServer {
   stop() {
     for (const job of this.jobs.values()) {
       clearTimeout(job.timer);
-      job.resolve({ ok: false, error: "bridge shut down" });
+      if (typeof job.resolve === "function") job.resolve({ ok: false, error: "bridge shut down" });
     }
     this.jobs.clear();
     if (this.server) {
@@ -114,20 +115,91 @@ export class BridgeServer {
           }
           clearTimeout(job.timer);
           const out = body.error ? { ok: false, error: body.error } : { ok: true, result: body.result ?? "" };
-          this.jobs.delete(job.id);
-          job.resolve(out);
+          job.status = "done";
+          job.out = out;
+          if (typeof job.resolve === "function") job.resolve(out);
+          this._retire(job);
           emit("job_done", { id: job.id, ...out });
           json(res, 200, { ok: true });
         });
         return;
       }
 
+      // Enqueue a job from an authenticated client (used by `roforge pro`
+      // attaching to an already-running bridge). The plugin still discovers
+      // it via the normal GET /jobs claim path.
+      if (req.method === "POST" && path === "/v1/bridge/jobs/enqueue") {
+        let body = {};
+        const chunks = [];
+        let size = 0;
+        req.on("data", (c) => {
+          size += c.length;
+          if (size < 1024 * 1024) chunks.push(c);
+        });
+        req.on("end", () => {
+          try {
+            body = chunks.length ? JSON.parse(Buffer.concat(chunks).toString("utf8")) : {};
+          } catch {
+            body = {};
+          }
+          if (typeof body.tool !== "string" || !body.tool) {
+            return json(res, 400, { error: "missing tool", code: "BAD_REQUEST" });
+          }
+          const id = this.enqueueRemote(body.tool, body.args ?? {});
+          json(res, 200, { ok: true, id });
+        });
+        return;
+      }
+
+      // Poll a (possibly completed) job's status — read by an attaching client.
+      const gs = /^\/v1\/bridge\/jobs\/(\w+)$/.exec(path);
+      if (req.method === "GET" && gs) {
+        const st = this.jobStatus(gs[1]);
+        if (!st) return json(res, 404, { error: "unknown job", code: "JOB_NOT_FOUND" });
+        return json(res, 200, { ok: true, ...st });
+      }
+
       return json(res, 404, { error: `no route: ${req.method} ${path}`, code: "NOT_FOUND" });
     } catch (e) {
       json(res, 500, { error: e.message, code: "INTERNAL" });
     }
   }
 
+  // Keep a finished job readable for a short window (so an attaching client
+  // can poll its result), then drop it. Unref'd: housekeeping must not keep
+  // the CLI process (or test runner) alive.
+  _retire(job) {
+    const t = setTimeout(() => {
+      if (this.jobs.get(job.id) === job) this.jobs.delete(job.id);
+    }, this.completedTtlMs);
+    if (typeof t.unref === "function") t.unref();
+  }
+
+  // Enqueue a job on behalf of a remote (attaching) client. Returns the id to
+  // poll. The plugin claims it through the normal GET /jobs path.
+  enqueueRemote(tool, args, { timeoutMs = this.jobTimeoutMs } = {}) {
+    const id = `job_${this.nextJobId++}`;
+    const job = { id, tool, args, status: "pending", remote: true, out: null, resolve: null, claimedAt: null, timer: null };
+    job.timer = setTimeout(() => {
+      if (this.jobs.get(id) === job && job.status !== "done") {
+        job.status = "timeout";
+        job.out = { ok: false, error: `studio job timed out after ${Math.round(timeoutMs / 1000)}s` };
+        this._retire(job);
+      }
+    }, timeoutMs);
+    this.jobs.set(id, job);
+    return id;
+  }
+
+  // Current status of a job for a poller: {id, status} while in flight, or
+  // {id, status:"done"|"timeout", ...out} once finished. null if unknown.
+  jobStatus(id) {
+    const job = this.jobs.get(id);
+    if (!job) return null;
+    if (job.status === "pending" || job.status === "claimed") return { id, status: job.status };
+    return { id, status: job.status, ...(job.out || {}) };
+  }
+
   // Submit a tool job and wait for the plugin's result. Resolves to
   // {ok:true, result:string} or {ok:false, error:string}.
   submit(tool, args, { timeoutMs = this.jobTimeoutMs } = {}) {

package/src/config.js

@@ -46,7 +46,10 @@ export const PROVIDERS = {
     env: "OPENROUTER_API_KEY",
     baseField: "openrouterBaseUrl",
     defaultModel: "qwen/qwen3-coder",
-    freeModel: "qwen/qwen3-coder:free", // :free models: req/day limit, no billing
+    // Free tier rotates — this is the live free model verified 2026-09-13
+    // via the public OpenRouter models API + a real request. When it dies,
+    // check https://openrouter.ai/models?max_price=0 and update here.
+    freeModel: "nvidia/nemotron-3-super-120b-a12b:free",
     hasFreeTier: true,
   },
   anthropic: {
@@ -114,7 +117,8 @@ const DEFAULTS = {
     "gpt-4o": { input: 2.5, output: 10 },
     "gemini-2.5-flash": { input: 0, output: 0 },
     "llama-3.3-70b-versatile": { input: 0, output: 0 },
-    "qwen/qwen3-coder:free": { input: 0, output: 0 },
+    "nvidia/nemotron-3-super-120b-a12b:free": { input: 0, output: 0 },
+    "nvidia/nemotron-3-ultra-550b-a55b:free": { input: 0, output: 0 },
   },
 };
 
@@ -184,6 +188,7 @@ export function resolveConfig() {
   if (process.env.ROFORGE_PROVIDER) cfg.provider = process.env.ROFORGE_PROVIDER;
   if (process.env.ROFORGE_MCP_URL) cfg.mcpUrl = process.env.ROFORGE_MCP_URL;
   if (process.env.ROFORGE_BRIDGE_PORT) cfg.bridge.port = Number(process.env.ROFORGE_BRIDGE_PORT);
+  if (process.env.ROFORGE_BRIDGE_TOKEN) cfg.bridge.token = process.env.ROFORGE_BRIDGE_TOKEN;
   if (process.env.ROFORGE_STUDIO_MODE) cfg.studioMode = process.env.ROFORGE_STUDIO_MODE;
   if (process.env.ROFORGE_MAX_ITERATIONS) cfg.maxIterations = Number(process.env.ROFORGE_MAX_ITERATIONS);
   if (process.env.ROFORGE_FREE_FIRST === "0" || process.env.ROFORGE_FREE_FIRST === "false") cfg.freeFirst = false;

package/src/pro.js

@@ -0,0 +1,126 @@
+// RoForge Pro — CLI-side status plumbing.
+//
+// The entitlement itself is checked inside Studio by the bridge plugin
+// (MarketplaceService only exists there). This module reaches the connected
+// Studio and renders its `forge_pro` report for `roforge pro`.
+//
+// Two ways to reach Studio, tried in order:
+//   1. ATTACH — if a bridge is already running on the configured port (e.g.
+//      `roforge studio` is up and the plugin is bound to it), enqueue the
+//      forge_pro job on that bridge and poll for the result. This is the
+//      normal case: you check Pro while your Studio session is live.
+//   2. OWN — otherwise start a throwaway bridge on the configured port, wait
+//      for the plugin (bound to the same port + token) to connect, submit,
+//      and stop. This lets `roforge pro` work standalone too.
+
+import { BridgeServer } from "./bridge/server.js";
+
+const HEALTH_PATH = "/health";
+
+// Probe for an already-running bridge on baseUrl. Returns the /health body
+// ({ok, service, connected, port}) or null when nothing is listening.
+export async function probeBridge(baseUrl, { timeoutMs = 1200 } = {}) {
+  try {
+    const r = await fetch(`${baseUrl}${HEALTH_PATH}`, { signal: AbortSignal.timeout(timeoutMs) });
+    if (!r.ok) return null;
+    const j = await r.json();
+    return j && j.service === "roforge-bridge" ? j : null;
+  } catch {
+    return null;
+  }
+}
+
+// Enqueue `tool` on a running bridge and poll for the result. Resolves to
+// {ok, result?/error}. `connected` lets the caller fail fast when the plugin
+// isn't actually bound to this bridge.
+export async function remoteSubmit(baseUrl, token, tool, args, { timeoutMs = 20000, pollMs = 150 } = {}) {
+  const auth = { authorization: `Bearer ${token}`, "content-type": "application/json" };
+  const enq = await fetch(`${baseUrl}/v1/bridge/jobs/enqueue`, {
+    method: "POST",
+    headers: auth,
+    body: JSON.stringify({ tool, args }),
+  });
+  if (!enq.ok) {
+    let msg = `HTTP ${enq.status}`;
+    try { msg = (await enq.json()).error || msg; } catch { /* keep status */ }
+    return { ok: false, error: msg };
+  }
+  const { id } = await enq.json();
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const st = await (await fetch(`${baseUrl}/v1/bridge/jobs/${id}`, { headers: { authorization: `Bearer ${token}` } })).json();
+    if (st.status === "done") {
+      return st.error ? { ok: false, error: st.error } : { ok: true, result: st.result ?? "" };
+    }
+    if (st.status === "timeout") return { ok: false, error: st.error || "studio job timed out" };
+    await new Promise((r) => setTimeout(r, pollMs));
+  }
+  return { ok: false, error: "timed out waiting for Studio" };
+}
+
+// Query Pro status, attaching to a running bridge when present. Returns
+// { text } on success, { error } otherwise. `bridge` may be null to force the
+// "own bridge" path (used by tests).
+export async function queryProStatus(bridge, { port, token, baseUrl, timeoutMs = 20000 } = {}) {
+  const base = baseUrl || `http://127.0.0.1:${port}`;
+
+  // Path 1: attach to a running bridge.
+  if (!bridge) {
+    const health = await probeBridge(base);
+    if (health) {
+      if (!health.connected) {
+        return {
+          error:
+            "A bridge is running but Studio is not connected. Open Roblox Studio with the " +
+            "RoForge Bridge plugin active and paste the bridge token into it.",
+        };
+      }
+      const out = await remoteSubmit(base, token, "forge_pro", {}, { timeoutMs });
+      if (!out.ok) return { error: out.error };
+      return { text: String(out.result ?? "") };
+    }
+  }
+
+  // Path 2: own bridge (already started by the caller).
+  if (!bridge || !bridge.connected) {
+    return {
+      error:
+        "No Studio bridge connection. Pro status is checked inside Studio (MarketplaceService), " +
+        "so this needs the RoForge Bridge plugin running and connected.",
+    };
+  }
+  const out = await bridge.submit("forge_pro", {}, { timeoutMs });
+  if (!out.ok) return { error: out.error };
+  return { text: String(out.result ?? "") };
+}
+
+// Start a throwaway bridge for the "own bridge" path. Returns the started
+// BridgeServer or throws on EADDRINUSE.
+export function startOwnBridge({ port, host = "127.0.0.1", token }) {
+  const bridge = new BridgeServer({ port, host, token });
+  return bridge;
+}
+
+// Render the forge_pro report (plain text from the plugin) with minimal
+// styling: the tier header gets color, the rest stays as-is.
+export function renderProStatus(res, { bold, dim, red, green, magenta, yellow } = {}) {
+  const id = (fn, s) => (fn ? fn(s) : String(s));
+  if (res && res.error) {
+    return (
+      id(red, res.error) +
+      "\n" +
+      id(dim, "  1. open Roblox Studio with the RoForge Bridge plugin\n") +
+      id(dim, "  2. run `roforge studio` here and paste the token it prints into the plugin\n") +
+      id(dim, "  3. re-run `roforge pro` while both are running")
+    );
+  }
+  const lines = String(res?.text ?? "").split("\n");
+  const out = [];
+  for (const line of lines) {
+    if (line.startsWith("RoForge Pro: PRO")) out.push(id(green, line));
+    else if (line.startsWith("RoForge Pro: FREE")) out.push(id(yellow, line));
+    else if (line.startsWith("Unlock Pro:")) out.push(id(magenta, line));
+    else out.push(line);
+  }
+  return out.join("\n");
+}

package/src/providers/openai.js

@@ -3,6 +3,34 @@
 import { createSSE } from "../util.js";
 import { ProviderError } from "./anthropic.js";
 
+// fetch with a per-attempt timeout and ONE automatic retry on network-level
+// failures (UND_ERR_CONNECT_TIMEOUT etc.) — user-initiated aborts are never
+// retried.
+export async function fetchWithRetry(url, opts, { timeoutMs = 60000, retries = 1 } = {}) {
+  let lastErr;
+  for (let attempt = 0; attempt <= retries; attempt++) {
+    if (opts.signal?.aborted) throw lastErr || new ProviderError("aborted");
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(new Error("timeout")), timeoutMs);
+    const onAbort = () => controller.abort(opts.signal.reason);
+    if (opts.signal) opts.signal.addEventListener("abort", onAbort, { once: true });
+    try {
+      return await fetch(url, { ...opts, signal: controller.signal });
+    } catch (e) {
+      lastErr = e;
+      if (opts.signal?.aborted) break; // user Ctrl+C — don't retry
+      const sig = `${e.cause?.code || ""} ${e.name} ${e.message}`;
+      const isNetwork = /UND_ERR|ECONN|ETIMEDOUT|EAI_AGAIN|EPIPE|EHOSTUNREACH|ENOTFOUND|timeout|aborted/i.test(sig);
+      if (!isNetwork || attempt === retries) break;
+      await new Promise((r) => setTimeout(r, 1200 * (attempt + 1)));
+    } finally {
+      clearTimeout(timer);
+      if (opts.signal) opts.signal.removeEventListener("abort", onAbort);
+    }
+  }
+  throw lastErr;
+}
+
 export async function chatStream(cfg, params, events = {}) {
   const key = cfg.openaiKey;
   if (!key) throw new ProviderError("No OpenAI API key. Run `roforge login` or set OPENAI_API_KEY.");
@@ -17,7 +45,7 @@ export async function chatStream(cfg, params, events = {}) {
 
   let res;
   try {
-    res = await fetch(`${cfg.openaiBaseUrl}/v1/chat/completions`, {
+    res = await fetchWithRetry(`${cfg.openaiBaseUrl}/v1/chat/completions`, {
       method: "POST",
       headers: {
         Authorization: `Bearer ${key}`,
@@ -27,10 +55,20 @@ export async function chatStream(cfg, params, events = {}) {
       signal: params.signal,
     });
   } catch (e) {
-    throw new ProviderError(`network error calling OpenAI: ${e.cause?.code || e.message}`);
+    throw new ProviderError(
+      `network error calling OpenAI: ${e.cause?.code || e.message} (retried once — if it persists, check your connection)`
+    );
   }
   if (!res.ok) {
     const text = await res.text().catch(() => "");
+    // OpenRouter retires free slugs; the 404 body names the paid replacement
+    if (res.status === 404 && /unavailable for free/i.test(text)) {
+      const m = text.match(/use this slug instead:\s*([^\s",}]+)/);
+      throw new ProviderError(
+        `${params.model} was retired from the free tier. Paid slug: ${m ? m[1] : "(see error)"} — ` +
+          "or pick a live free model: https://openrouter.ai/models?max_price=0 (then /model openrouter:<slug>)"
+      );
+    }
     throw new ProviderError(`OpenAI HTTP ${res.status}: ${text.slice(0, 400)}`);
   }
 

package/src/tools/studio.js

@@ -28,6 +28,7 @@ const BRIDGE_TOOL_NAMES = [
   "forge_diff",
   "forge_export",
   "forge_import",
+  "forge_pro",
 ];
 
 const BRIDGE_DESCRIPTIONS = {
@@ -53,8 +54,9 @@ const BRIDGE_DESCRIPTIONS = {
   forge_bulk_create: "Create many instances in one call (paste-style): items[] of {path: parent path, class_name, name?, properties?}. Destructive.",
   forge_snapshot: "Capture the current instance tree under a name, so forge_diff can show what changed later. Keeps the last 10.",
   forge_diff: "Compare a snapshot to the current instance tree: added (+) and removed (-) instances. Omit name to diff the most recent snapshot.",
-  forge_export: "Export a DataModel subtree as JSON (properties, script sources truncated, attributes). Defaults to workspace, depth 3 (max 6).",
-  forge_import: "Apply a forge_export JSON back into Studio: recreates the instance tree (properties, sources, attributes) under a parent. dry_run=true only reports. Destructive; max 500 nodes.",
+  forge_export: "Export a DataModel subtree as JSON (properties, script sources truncated, attributes). Defaults to workspace, depth 3 (max 6; 10 with RoForge Pro).",
+  forge_import: "Apply a forge_export JSON back into Studio: recreates the instance tree (properties, sources, attributes) under a parent. dry_run=true only reports. Destructive; max 500 nodes (2500 with RoForge Pro).",
+  forge_pro: "Report the current RoForge Pro entitlement: Free or Pro, which pass/product the Studio user owns, and the active limits + Pro features. Call it to know whether the user has Pro.",
 };
 
 const BRIDGE_SCHEMAS = {
@@ -213,6 +215,7 @@ const BRIDGE_SCHEMAS = {
     },
     additionalProperties: false,
   },
+  forge_pro: { type: "object", properties: {}, additionalProperties: false },
 };
 
 // Tools that modify the DataModel — gated by the approval prompt.

package/src/tui/frame.js

@@ -0,0 +1,264 @@
+// LiveRegion — a flicker-free live region at the bottom of the append-scroll
+// output, sized to preserve the terminal scrollback above it (the core trick
+// behind Claude Code's fluid TUI, adapted to an append-scroll layout).
+//
+// Model & cursor invariant:
+//   • Committed history scrolls normally above the region (plain append).
+//   • The region owns the currently-streaming content: every completed
+//     content line is appended (terminal scrolls, nothing is ever lost), and
+//     one status line always sits on the last line, rewritten in place.
+//   • The cursor is ALWAYS at the end of the status line.
+//   • Adding a line = overwrite the status line with the new content line,
+//     then write the status on the fresh line below (single write, no
+//     intermediate clear → no flicker).
+//   • The last (partially streamed) content line is rewritten in place as it
+//     grows: up one line, rewrite, back down, rewrite the status.
+//   • Committing = release(): the region's lines simply become history; the
+//     cursor drops to a fresh line below for the next turn.
+//
+// Long lines are pre-wrapped to the terminal width (segment-aware) so the
+// terminal never auto-wraps and breaks the cursor arithmetic.
+// A terminal resize erases the region; the next update re-renders it.
+
+import { COLUMNS } from "./ansi.js";
+
+const SGR_RESET = "\x1b[0m";
+function sgrFor(attr) {
+  if (!attr) return SGR_RESET;
+  const p = [];
+  if (attr & 1) p.push("1"); // bold
+  if (attr & 2) p.push("2"); // dim
+  if (attr & 4) p.push("31"); // red
+  if (attr & 8) p.push("32"); // green
+  if (attr & 16) p.push("33"); // yellow
+  if (attr & 32) p.push("36"); // cyan
+  if (attr & 64) p.push("35"); // magenta
+  if (attr & 128) p.push("34"); // blue
+  return "\x1b[" + p.join(";") + "m";
+}
+
+export const ATTR = {
+  PLAIN: 0,
+  BOLD: 1,
+  DIM: 2,
+  RED: 4,
+  GREEN: 8,
+  YELLOW: 16,
+  CYAN: 32,
+  MAGENTA: 64,
+  BLUE: 128,
+};
+
+/**
+ * Word-aware wrap for styled lines.
+ * @param {Array<{text: string, attr?: number}>} segments
+ * @param {number} width
+ * @returns {Array<Array<{text: string, attr?: number}>>} wrapped lines
+ */
+export function wrapSegments(segments, width) {
+  width = Math.max(2, width);
+  const lines = [[]];
+  let col = 0;
+  let pendingSpace = 0; // width of whitespace awaiting a word (dropped on wrap)
+  const lastLine = () => lines[lines.length - 1];
+  for (const seg of segments || []) {
+    const text = String(seg.text ?? "");
+    const attr = seg.attr ?? 0;
+    // pieces alternate: word, whitespace, word, ...
+    for (const piece of text.split(/(\s+)/)) {
+      if (!piece) continue;
+      if (/^\s+$/.test(piece)) {
+        // remember; only emitted when a following word lands on this line
+        pendingSpace = piece.length;
+        continue;
+      }
+      let w = piece;
+      while (w.length) {
+        // a pending space only counts when the word isn't starting a fresh line
+        const spaceNeeded = col > 0 && pendingSpace ? pendingSpace : 0;
+        const room = width - col - spaceNeeded;
+        if (w.length <= room) {
+          // whole word fits
+          if (spaceNeeded) {
+            lastLine().push({ text: " ".repeat(spaceNeeded), attr });
+            col += spaceNeeded;
+          }
+          pendingSpace = 0;
+          lastLine().push({ text: w, attr });
+          col += w.length;
+          w = "";
+        } else if (w.length > width) {
+          // unbreakable: longer than a full line — hard-break it
+          if (col > 0 || spaceNeeded) {
+            lines.push([]);
+            col = 0;
+          }
+          pendingSpace = 0;
+          lastLine().push({ text: w.slice(0, width - col), attr });
+          w = w.slice(width - col);
+          lines.push([]);
+          col = 0;
+        } else {
+          // breakable word that doesn't fit the remainder — wrap it whole
+          lines.push([]);
+          col = 0;
+          pendingSpace = 0;
+        }
+      }
+    }
+  }
+  // drop a trailing line that is empty or whitespace-only
+  if (lines.length > 1) {
+    const tail = lines[lines.length - 1];
+    if (!tail.length || tail.every((s) => /^\s*$/.test(s.text))) lines.pop();
+  }
+  return lines.length ? lines : [[]];
+}
+
+function renderLine(segments) {
+  let out = "";
+  let state = 0;
+  for (const seg of segments || []) {
+    const a = seg.attr ?? 0;
+    if (a !== state) {
+      out += sgrFor(a);
+      state = a;
+    }
+    out += String(seg.text ?? "");
+  }
+  if (state) out += SGR_RESET;
+  return out;
+}
+
+export class LiveRegion {
+  /**
+   * @param {(s: string) => void} emit
+   * @param {{ maxRows?: number, enabled?: boolean }} opts
+   *   maxRows is accepted for API compatibility; the append model keeps every
+   *   completed line live (terminal scrollback is the cap), so it is a no-op.
+   */
+  constructor(emit, { maxRows = 6, enabled = true } = {}) {
+    this.emit = emit;
+    this.maxRows = maxRows;
+    this.enabled = enabled && Boolean(process.stdout.isTTY);
+    this.active = false;
+    this._rendered = false;
+    this._shown = 0; // completed content display lines already written
+    this._lastContent = null;
+  }
+
+  begin(_opts) {
+    this.active = true;
+    this._rendered = false;
+    this._shown = 0;
+    this._lastContent = null;
+  }
+
+  get isActive() {
+    return this.active;
+  }
+
+  /**
+   * Update the region.
+   * @param {Array<Array<{text, attr?}>>} contentLines styled logical lines —
+   *   the full content so far, where the LAST line is the partially streamed
+   *   line (grows across calls). Earlier lines are complete.
+   * @param {Array<{text, attr?}>|null} status styled status line (last row)
+   */
+  update(contentLines, status) {
+    if (!this.active) return;
+    this._lastContent = contentLines;
+    const cols = COLUMNS();
+    // wrap every logical line into display lines
+    const display = [];
+    for (const line of contentLines || []) display.push(...wrapSegments(line, cols));
+    const statusLine = status ? wrapSegments(status, cols - 1).slice(0, 1)[0] || [] : [];
+    const C = display.length;
+
+    if (!this._rendered) {
+      // first render: append everything from the current cursor position.
+      // The first line is written at the cursor (col 0 of a fresh line, or
+      // right after a sameLine header) — no leading newline.
+      const rows = [...display, ...(statusLine.length ? [statusLine] : [])];
+      let out = "";
+      rows.forEach((r, i) => {
+        if (i > 0) out += "\n";
+        out += renderLine(r) + "\x1b[K";
+      });
+      if (out) this.emit(out);
+      this._rendered = true;
+      this._shown = C;
+      this._hadStatus = statusLine.length > 0;
+      return;
+    }
+
+    const newLines = display.slice(this._shown);
+    const lastLine = C > 0 ? display[C - 1] : null;
+    let out = "";
+    if (newLines.length === 0 && C === 0 && !statusLine.length) {
+      // nothing to show and nothing stale to clear — but a previously
+      // rendered status line must be blanked
+      if (this._hadStatus) {
+        out = "\x1b[1G\x1b[K";
+        this._hadStatus = false;
+      }
+      if (out) this.emit(out);
+      return;
+    }
+    if (newLines.length > 0) {
+      // New completed line(s): the cursor sits at the end of the status line.
+      // Overwrite it with the first new line, push the rest below, then write
+      // the status on the fresh bottom line. One write, no flicker.
+      out += "\x1b[1G";
+      for (const nl of newLines) out += renderLine(nl) + "\x1b[K\n";
+      if (statusLine.length) out += renderLine(statusLine) + "\x1b[K";
+      this._shown = C;
+      this._hadStatus = statusLine.length > 0;
+    } else if (C > 0 || statusLine.length) {
+      // No new lines: the last content line may have grown (or only the
+      // status changed). Rewrite the last content line in place, then the
+      // status.
+      if (C > 0) {
+        out += "\x1b[1A\x1b[1G"; // up to the last content line
+        out += renderLine(lastLine) + "\x1b[K"; // rewrite it (clear stale tail)
+        out += "\n"; // back down to the status line
+      } else {
+        out += "\x1b[1G";
+      }
+      out += renderLine(statusLine) + "\x1b[K"; // clears stale status text too
+      this._hadStatus = statusLine.length > 0;
+    }
+    if (out) this.emit(out);
+  }
+
+  /** Final update + release; region lines become committed history. */
+  end(status) {
+    if (!this.active) return;
+    if (status) this.update(this._lastContent || [], status);
+    this.release();
+  }
+
+  /** Release: drop the cursor to a fresh line below; lines become history. */
+  release() {
+    if (this.active && this._rendered) this.emit("\n");
+    this.active = false;
+    this._rendered = false;
+    this._shown = 0;
+  }
+
+  /** Erase the region on terminal resize (stale width would be wrong). */
+  eraseOnResize() {
+    if (!this.active || !this._rendered) return;
+    const h = this._shown + 1; // content lines + status
+    const out = ["\x1b[" + Math.max(0, h - 1) + "A", "\x1b[1G"];
+    for (let i = 0; i < h; i++) {
+      out.push("\x1b[2K");
+      if (i < h - 1) out.push("\n");
+    }
+    // return to the region top so the next update re-renders in place
+    out.push("\x1b[" + Math.max(0, h - 1) + "A");
+    this.emit(out.join(""));
+    this._rendered = false;
+    this._shown = 0;
+  }
+}

package/src/tui/markdown.js

@@ -3,7 +3,23 @@
 // code-fence state across deltas, and resets cleanly per assistant segment.
 // Deliberately small: headings, bullets, numbered lists, bold, inline code,
 // fences, blockquotes, rules. Everything else passes through untouched.
-import { bold, dim, cyan, gray } from "./ansi.js";
+//
+// Two output modes:
+//   push()/finish()    — ANSI strings (piped / non-TTY path, legacy rendering)
+//   pushLines() & co   — styled segment lines (Array<{text, attr}>) for the
+//                        LiveRegion, which wraps them to terminal width
+//                        itself while preserving per-segment style.
+import { bold, dim, cyan } from "./ansi.js";
+import { ATTR } from "./frame.js";
+
+const A = ATTR;
+
+// attr → string-mode ANSI helper (respects NO_COLOR / --no-color at call time)
+const STRING_STYLE = {
+  [A.BOLD]: bold,
+  [A.DIM]: dim,
+  [A.CYAN]: cyan,
+};
 
 export class MarkdownStream {
   constructor() {
@@ -11,57 +27,129 @@ export class MarkdownStream {
     this.inFence = false;
   }
 
-  // Consume a chunk; returns the renderable output for completed lines.
+  // --- string mode (piped output) -------------------------------------------
+
+  // Consume a chunk; returns the rendered output for completed lines.
   push(delta) {
+    const lines = this.pushLines(delta);
+    if (!lines.length) return "";
+    return lines.map((segs) => segsToAnsi(segs)).join("\n") + "\n";
+  }
+
+  // Flush the incomplete trailing line (at end of an assistant segment).
+  finish() {
+    const segs = this.finishLines();
+    return segs ? segsToAnsi(segs) + "\n" : "";
+  }
+
+  // --- segment mode (LiveRegion) --------------------------------------------
+
+  // Consume a chunk; returns styled lines for every line that COMPLETED in
+  // this delta (each line = Array<{text, attr}>). The partial trailing line
+  // stays buffered; use partialLines() to render it.
+  pushLines(delta) {
     this.buf += String(delta ?? "");
-    let out = "";
+    const out = [];
     let idx;
     while ((idx = this.buf.indexOf("\n")) !== -1) {
       const line = this.buf.slice(0, idx);
       this.buf = this.buf.slice(idx + 1);
-      out += this._renderLine(line) + "\n";
+      out.push(this._renderLineSegs(line));
     }
     return out;
   }
 
-  // Flush the incomplete trailing line (at end of an assistant segment).
-  finish() {
-    if (!this.buf.length) return "";
+  // Styled segments for the currently buffered (incomplete) line, or null.
+  partialLines() {
+    if (!this.buf.length) return null;
+    return this._renderLineSegs(this.buf);
+  }
+
+  // Flush the incomplete trailing line as segments (or null).
+  finishLines() {
+    if (!this.buf.length) return null;
     const line = this.buf;
     this.buf = "";
-    return this._renderLine(line) + "\n";
+    return this._renderLineSegs(line);
   }
 
-  _renderLine(line) {
+  // --- shared core ------------------------------------------------------------
+
+  _renderLineSegs(line) {
     if (/^\s*(```|~~~)/.test(line)) {
       this.inFence = !this.inFence;
-      return dim("  " + line.trim());
+      return [{ text: "  " + line.trim(), attr: A.DIM }];
     }
     if (this.inFence) {
-      return dim("  " + line);
+      return [{ text: "  " + line, attr: A.DIM }];
     }
-    return this._renderPlain(line);
+    return this._renderPlainSegs(line);
+  }
+
+  _pushSeg(line, text, attr) {
+    if (!text) return;
+    const last = line[line.length - 1];
+    if (last && last.attr === attr) last.text += text;
+    else line.push({ text, attr: attr || 0 });
   }
 
-  _renderPlain(line) {
+  _renderPlainSegs(line) {
     const h = line.match(/^(#{1,4})\s+(.*)$/);
-    if (h) return bold(h[1] + " " + this._inline(h[2]));
+    if (h) {
+      const out = [{ text: h[1] + " ", attr: A.BOLD }];
+      for (const seg of this._inlineSegs(h[2])) {
+        // heading text is bold by default; code inside keeps its own style
+        this._pushSeg(out, seg.text, seg.attr === A.CYAN ? seg.attr : A.BOLD);
+      }
+      return out;
+    }
     if (/^\s*([-*+])\s+/.test(line)) {
-      return cyan("•  ") + this._inline(line.replace(/^\s*[-*+]\s+/, ""));
+      const out = [{ text: "•  ", attr: A.CYAN }];
+      for (const seg of this._inlineSegs(line.replace(/^\s*[-*+]\s+/, ""))) this._pushSeg(out, seg.text, seg.attr);
+      return out;
     }
     const num = line.match(/^\s*(\d+)[.)]\s+(.*)$/);
-    if (num) return gray(num[1] + ".") + " " + this._inline(num[2]);
+    if (num) {
+      const out = [{ text: num[1] + ". ", attr: A.DIM }];
+      for (const seg of this._inlineSegs(num[2])) this._pushSeg(out, seg.text, seg.attr);
+      return out;
+    }
     if (/^\s*>\s?/.test(line)) {
-      return dim("│ ") + dim(this._inline(line.replace(/^\s*>\s?/, "")));
+      const out = [{ text: "│ ", attr: A.DIM }];
+      for (const seg of this._inlineSegs(line.replace(/^\s*>\s?/, ""))) this._pushSeg(out, seg.text, A.DIM);
+      return out;
     }
-    if (/^\s*([-*_])\1{2,}\s*$/.test(line)) return dim("────────────────────────────────");
-    if (!line.trim()) return "";
-    return this._inline(line);
+    if (/^\s*([-*_])\1{2,}\s*$/.test(line)) {
+      return [{ text: "────────────────────────────────", attr: A.DIM }];
+    }
+    if (!line.trim()) return [];
+    return this._inlineSegs(line);
+  }
+
+  // Split inline text into plain / code / bold segments.
+  _inlineSegs(s) {
+    const out = [];
+    // tokenize: `code`, **bold**, and plain runs
+    const re = /(`[^`]+`|\*\*[^*]+\*\*)/g;
+    let last = 0;
+    let m;
+    while ((m = re.exec(s)) !== null) {
+      if (m.index > last) this._pushSeg(out, s.slice(last, m.index), A.PLAIN);
+      const tok = m[0];
+      if (tok.startsWith("`")) this._pushSeg(out, tok.slice(1, -1), A.CYAN);
+      else this._pushSeg(out, tok.slice(2, -2), A.BOLD);
+      last = m.index + tok.length;
+    }
+    if (last < s.length) this._pushSeg(out, s.slice(last), A.PLAIN);
+    return out;
   }
+}
 
-  _inline(s) {
-    s = s.replace(/`([^`]+)`/g, (_, c) => cyan(c));
-    s = s.replace(/\*\*([^*]+)\*\*/g, (_, b) => bold(b));
-    return s;
+export function segsToAnsi(segs) {
+  let out = "";
+  for (const seg of segs || []) {
+    const style = STRING_STYLE[seg.attr] || ((t) => t);
+    out += style(seg.text);
   }
+  return out;
 }

package/src/tui/tui.js

@@ -1,10 +1,17 @@
 // RoForge TUI — Claude-Code-style interactive terminal session.
-// Append-style rendering (terminal scrollback preserved), single status line
-// with a spinner, approval prompts, slash commands, input history.
+// Append-style rendering (terminal scrollback preserved).
+//
+// Two render paths, picked once at startup:
+//   • LIVE (stdout is a TTY): the streaming block (markdown + status line) is
+//     a LiveRegion — rewritten in place every frame, zero flicker, history
+//     committed above it. See frame.js.
+//   • LEGACY (piped output / tests): plain append + \r-spinner, exactly the
+//     pre-LiveRegion behavior.
 import { createRequire } from "node:module";
 import { bold, dim, red, green, yellow, cyan, magenta, gray, wrap, SPINNER_FRAMES, CLEAR_LINE } from "./ansi.js";
 import { parseModelRef, PROVIDERS } from "../config.js";
-import { MarkdownStream } from "./markdown.js";
+import { MarkdownStream, segsToAnsi } from "./markdown.js";
+import { LiveRegion, ATTR } from "./frame.js";
 
 const VERSION = (() => {
   try {
@@ -22,7 +29,7 @@ for (const p of Object.values(PROVIDERS)) {
 }
 
 export class TUI {
-  constructor(session, { out = process.stdout, err = process.stderr } = {}) {
+  constructor(session, { out = process.stdout, err = process.stderr, live } = {}) {
     this.session = session;
     this.out = out;
     this.err = err;
@@ -38,7 +45,16 @@ export class TUI {
     this.spinnerVisible = false;
     this.ctrlCTime = 0;
     this.running = false;
+
+    // LiveRegion (live path). `live` overrides detection (tests).
+    this.live = new LiveRegion((s) => this.out.write(s), { maxRows: 6 });
+    this._liveOK =
+      live === undefined ? Boolean(process.stdout.isTTY) && this.out === process.stdout : live;
     this._md = null; // active MarkdownStream for the current assistant segment
+    this._segLines = []; // completed styled lines for the current segment
+    this._statusLabel = "thinking…";
+    this._costStatus = null; // final cost line for this turn (plain text)
+    this._lastLiveSig = null;
     this._toolOutputs = []; // recent tool outputs, expandable via /out
     this._toolOutSeq = 0;
   }
@@ -85,6 +101,8 @@ export class TUI {
         // Ctrl+C
         if (this.busy) {
           this.session.abort();
+          this._stopSpinner();
+          this._liveCommit();
           this.out.write("\r\n" + yellow("aborted — type a new message or /exit\n"));
           continue;
         }
@@ -220,7 +238,7 @@ export class TUI {
           this.out.write(`model → ${this.session.cfg._activeModel} (${this.session.providerName}${free})\n`);
           if (!ref && !KNOWN_MODELS.has(arg)) {
             this.out.write(
-              dim(`  (unrecognized model name — double-check the spelling, or pin explicitly: /model provider:model, e.g. /model gemini:gemini-2.5-flash)\n`)
+              dim(`  (unrecognized model name — double-check the spelling, or pin explicitly: /model provider:model, e.g. /model gemini:2.5-flash)\n`)
             );
           }
         } else {
@@ -299,12 +317,18 @@ export class TUI {
   async _runTurn(text) {
     this.out.write(dim("you> ") + text + "\n");
     this.busy = true;
-    this._md = null;
+    this._resetSegment();
+    this._costStatus = null;
+    this._lastLiveSig = null;
     try {
       await this.session.send(text);
     } catch (e) {
+      this._stopSpinner();
+      this._liveCommit();
       this.out.write(red(`error: ${e.message || e}`) + "\n");
     }
+    // commit the live block with the final cost line as its status
+    this._liveCommit(this._costStatus ? [{ text: this._costStatus, attr: ATTR.DIM }] : null);
     this.busy = false;
     this._printPrompt();
   }
@@ -314,17 +338,92 @@ export class TUI {
     this.out.write("> ");
   }
 
+  // ---------------- live-region plumbing ----------------
+
+  // Region content for the current assistant segment: completed lines + the
+  // partial line, with the magenta "RoForge> " header on the first
+  // non-empty line (leading blank lines from the model stay blank).
+  _regionLines() {
+    const lines = [...this._segLines];
+    const partial = this._md ? this._md.partialLines() : null;
+    if (partial) lines.push(partial);
+    const first = lines.findIndex((l) => l && l.some((s) => s.text));
+    if (first === -1) return [];
+    lines[first] = [{ text: "RoForge> ", attr: ATTR.MAGENTA }, ...lines[first]];
+    return lines;
+  }
+
+  _statusSegs() {
+    if (this._costStatus) return [{ text: this._costStatus, attr: ATTR.DIM }];
+    const frame = SPINNER_FRAMES[this.spinnerFrame];
+    return [{ text: frame + " " + this._statusLabel, attr: ATTR.DIM }];
+  }
+
+  // Redraw the live region (no-op when nothing changed since the last frame).
+  _liveRefresh() {
+    if (!this._liveOK || !this.live.isActive) return;
+    const lines = this._regionLines();
+    const status = this._statusSegs();
+    const last = lines.length ? lines[lines.length - 1] : null;
+    const sig =
+      lines.length +
+      ":" +
+      (last ? last.map((s) => s.text).join("") : "") +
+      "|" +
+      status.map((s) => s.text).join("");
+    if (sig === this._lastLiveSig) return;
+    this._lastLiveSig = sig;
+    this.live.update(lines, status);
+  }
+
+  // Commit the live block to history. statusSegs = final status line, or null
+  // to commit with a blank one (acts as a separator).
+  _liveCommit(statusSegs = null) {
+    if (!this._liveOK || !this.live.isActive) return;
+    this._finalizeMd();
+    this.live.update(this._regionLines(), statusSegs || []);
+    this.live.release();
+    this._lastLiveSig = null;
+  }
+
+  _finalizeMd() {
+    if (this._md) {
+      const tail = this._md.finishLines();
+      if (tail) this._segLines.push(tail);
+      this._md = null;
+    }
+  }
+
+  // Start a fresh assistant segment (clears streamed content + markdown).
+  // The "running tool" region and gaps between segments show no content, so
+  // the stale block never re-renders in a new region.
+  _resetSegment() {
+    this._md = null;
+    this._segLines = [];
+  }
+
+  // ---------------- spinner ----------------
+
   _startSpinner(label = "thinking…") {
-    if (!process.stdout.isTTY) return;
     this._stopSpinner();
-    this.spinnerVisible = true;
-    this.out.write(label);
-    this.spinnerTimer = setInterval(() => {
-      this.spinnerFrame = (this.spinnerFrame + 1) % SPINNER_FRAMES.length;
-      const len = label.length + 3;
-      this.out.write("\r" + CLEAR_LINE + this.spinnerFrame + " " + label.slice(0, Math.max(0, len - 2)));
-    }, 90);
-    this.spinnerTimer.unref && this.spinnerTimer.unref();
+    this._statusLabel = label;
+    if (this._liveOK) {
+      this.spinnerTimer = setInterval(() => {
+        this.spinnerFrame = (this.spinnerFrame + 1) % SPINNER_FRAMES.length;
+        if (this.live.isActive) this._liveRefresh();
+      }, 90);
+      this.spinnerTimer.unref && this.spinnerTimer.unref();
+      this._liveRefresh();
+    } else if (process.stdout.isTTY) {
+      this.spinnerVisible = true;
+      this.out.write(label);
+      this.spinnerTimer = setInterval(() => {
+        this.spinnerFrame = (this.spinnerFrame + 1) % SPINNER_FRAMES.length;
+        const len = label.length + 3;
+        this.out.write("\r" + CLEAR_LINE + this.spinnerFrame + " " + label.slice(0, Math.max(0, len - 2)));
+      }, 90);
+      this.spinnerTimer.unref && this.spinnerTimer.unref();
+    }
   }
 
   _stopSpinner() {
@@ -340,32 +439,42 @@ export class TUI {
 
   // ---------------- ui event sink (Session) ----------------
 
-  _flushMd() {
-    if (this._md) {
-      const tail = this._md.finish();
-      if (tail) this.out.write(tail);
-      this._md = null;
-    }
-  }
-
   onText(delta) {
     this._stopSpinner();
-    if (!this._assistantHeaderShown) {
-      this.out.write(magenta("RoForge> ") );
-      this._assistantHeaderShown = true;
-    }
     if (!this._md) this._md = new MarkdownStream();
-    const rendered = this._md.push(delta);
-    if (rendered) this.out.write(rendered);
+    const newLines = this._md.pushLines(delta);
+    for (const l of newLines) this._segLines.push(l);
+    if (this._liveOK) {
+      if (!this.live.isActive) this.live.begin();
+      this._liveRefresh();
+    } else {
+      if (!this._assistantHeaderShown) {
+        this.out.write(magenta("RoForge> "));
+        this._assistantHeaderShown = true;
+      }
+      if (newLines.length) this.out.write(newLines.map(segsToAnsi).join("\n") + "\n");
+    }
   }
 
   onAssistantDone() {
-    this._flushMd();
+    if (this._md) {
+      const tail = this._md.finishLines();
+      this._md = null;
+      if (tail) {
+        if (this._liveOK) {
+          this._segLines.push(tail);
+          this._liveRefresh();
+        } else {
+          this.out.write(segsToAnsi(tail) + "\n");
+        }
+      }
+    }
   }
 
   onToolStart(tool, args) {
     this._stopSpinner();
-    this._flushMd();
+    this._liveCommit(); // assistant block → history (blank separator)
+    this._resetSegment(); // running region shows status only, no content
     let argsStr;
     try {
       argsStr = JSON.stringify(args || {});
@@ -377,7 +486,8 @@ export class TUI {
     this._toolOutputs.push({ id: this._toolOutSeq, tool: tool.name, args: argsStr, full: "" });
     if (this._toolOutputs.length > 30) this._toolOutputs.shift();
     this.out.write(dim(`  ⚙ [${this._toolOutSeq}] ${tool.name}(${argsStr})`) + "\n");
-    this._startSpinner(dim("running " + tool.name + "…"));
+    if (this._liveOK) this.live.begin();
+    this._startSpinner("running " + tool.name + "…");
   }
 
   onToolEnd(tool, args, result) {
@@ -385,6 +495,8 @@ export class TUI {
     const r = String(result || "");
     const last = this._toolOutputs[this._toolOutputs.length - 1];
     if (last && last.tool === tool.name) last.full = r;
+    this._liveCommit(); // "running…" block → history
+    this._resetSegment(); // next assistant text starts a fresh segment
     const first = r.split("\n")[0].slice(0, 120);
     const more = (r.length > 120 || r.includes("\n")) && last ? dim(` (more: /out ${last.id})`) : "";
     if (r.startsWith("ERROR")) {
@@ -392,27 +504,45 @@ export class TUI {
     } else {
       this.out.write(dim(`    ↳ ${first}`) + more + "\n");
     }
+    if (this._liveOK) this.live.begin();
     this._startSpinner("thinking…");
   }
 
   onInfo(msg) {
     this._stopSpinner();
+    this._liveCommit();
     this.out.write(gray(msg) + "\n");
   }
 
   onWarn(msg) {
     this._stopSpinner();
+    this._liveCommit();
     this.out.write(red(msg) + "\n");
   }
 
   onStatus(msg) {
-    // Only the per-turn cost footer is printed here; the spinner covers
-    // "thinking…" and tool progress is shown on its own lines.
-    if (String(msg).includes("tok")) this.out.write("\n" + gray(msg) + "\n");
+    const m = String(msg);
+    if (m.includes("tok")) {
+      // per-turn cost footer — becomes the live block's final status line
+      this._costStatus = m;
+      if (this._liveOK && this.live.isActive) {
+        this._stopSpinner();
+        this._liveRefresh();
+      } else if (!this._liveOK) {
+        this.out.write("\n" + gray(m) + "\n");
+      }
+      return;
+    }
+    // "thinking… (step n/total)" / "done" → live status label
+    if (this._liveOK && this.live.isActive) {
+      this._statusLabel = m === "done" ? "finishing…" : m;
+      this._liveRefresh();
+    }
   }
 
   async promptApproval(name, args) {
     this._stopSpinner();
+    this._liveCommit();
     let target = "";
     try {
       target = JSON.stringify(args || {});
@@ -421,7 +551,9 @@ export class TUI {
     }
     if (target.length > 100) target = target.slice(0, 97) + "…";
     this.out.write(yellow(`  ✋ approve ${name}(${target})? `) + dim("[y]es / [n]o / [a]lways "));
-    return await this._readChar();
+    const ans = await this._readChar();
+    this.out.write("\n"); // next output starts on a fresh line
+    return ans;
   }
 
   _readChar() {
@@ -476,6 +608,15 @@ export class TUI {
     if (process.stdin.isTTY) {
       this._setRaw(true);
       process.stdin.on("data", (c) => this._onData(c));
+      if (this._liveOK) {
+        this._onResize = () => {
+          if (this.live.isActive) {
+            this.live.eraseOnResize();
+            this._lastLiveSig = null;
+          }
+        };
+        process.stdout.on("resize", this._onResize);
+      }
       this._printPrompt();
       return true;
     }
@@ -487,6 +628,11 @@ export class TUI {
   stop() {
     this.running = false;
     this._stopSpinner();
+    this._liveCommit();
+    if (this._onResize) {
+      process.stdout.removeListener("resize", this._onResize);
+      this._onResize = null;
+    }
     this._setRaw(false);
     process.stdin.removeAllListeners("data");
   }