jeo-code 0.1.0 → 0.4.4

package/src/tui/components/status.ts

@@ -1,7 +1,115 @@
 import chalk from "chalk";
-import { meter } from "./meter";
+import { categoryBadge } from "./category-index";
 
-export interface JocStatusData {
+import { animatedGradientText, applyBgGradient, hexToRgb, visibleWidth, ColorLevel } from "./color";
+import * as os from "node:os";
+import { formatUsage } from "./duration";
+import { formatCost } from "../../ai/pricing";
+
+/**
+ * One-row status bar pinned directly above the boxed input (gjc-layout parity):
+ *   <bg-gradient block: ⬢ model · ◔ thinking / ⑂ branch *D ?N / ▸ cwd>  …  ⤴ R/s · ctx P%/MaxM
+ * The left identity segment rides the theme's gradient as a BACKGROUND block;
+ * right-side live stats stay plain so they read at a glance.
+ */
+export interface StatusBarData {
+  model: string;
+  /** Thinking level label ("high", …); omitted when unset. */
+  thinking?: string;
+  branch?: string;
+  /** Uncommitted-change count for the `?N` dirty flag; omit/0 = clean. */
+  dirtyCount?: number;
+  cwd?: string;
+  /** Live output-token rate (tokens/s); omitted when not in a turn. */
+  rate?: number;
+  /** Estimated context usage 0-100 (%), when known. */
+  ctxPct?: number;
+  /** Context window in tokens, when known. */
+  ctxMaxTokens?: number;
+  cols: number;
+  unicode?: boolean;
+  color?: boolean;
+  colorLevel?: ColorLevel;
+  /** Theme gradient (from→to hex) for the left segment background. */
+  gradient?: { from: string; to: string };
+}
+
+function shortTokens(n: number): string {
+  if (n >= 1_000_000) {
+    const v = (n / 1_000_000).toFixed(1);
+    return (v.endsWith(".0") ? v.slice(0, -2) : v) + "M";
+  }
+  if (n >= 1000) return Math.round(n / 1000) + "k";
+  return Math.round(n).toString();
+}
+
+function shortenCwd(cwd: string, maxLen: number, unicode: boolean): string {
+  let s = cwd;
+  const home = os.homedir();
+  if (home && (s === home || s.startsWith(home + "/") || s.startsWith(home + "\\"))) {
+    s = "~" + s.slice(home.length);
+  }
+  if (s.length <= maxLen) return s;
+  const ell = unicode ? "…" : "...";
+  return ell + s.slice(-(Math.max(1, maxLen - ell.length)));
+}
+
+export function renderStatusBar(d: StatusBarData): string {
+  const unicode = d.unicode !== false;
+  const useColor = d.color !== false;
+  const cols = Math.max(24, Math.trunc(d.cols));
+  const sep = " / ";
+
+  // Right side first — it has priority and fixed width.
+  const rightParts: string[] = [];
+  if (typeof d.rate === "number" && Number.isFinite(d.rate) && d.rate > 0) {
+    rightParts.push(`${unicode ? "⤴" : "^"} ${d.rate >= 100 ? d.rate.toFixed(0) : d.rate.toFixed(1)}/s`);
+  }
+  if (typeof d.ctxPct === "number" && Number.isFinite(d.ctxPct)) {
+    const pct = Math.max(0, Math.min(999, Math.round(d.ctxPct)));
+    const cap = d.ctxMaxTokens && d.ctxMaxTokens > 0 ? `/${shortTokens(d.ctxMaxTokens)}` : "";
+    rightParts.push(`${unicode ? "▦" : "#"} ${pct}%${cap}`);
+  }
+  let right = rightParts.join(" · ");
+  if (useColor && right) {
+    const pct = d.ctxPct ?? 0;
+    right = pct >= 85 ? chalk.red(right) : pct >= 60 ? chalk.yellow(right) : chalk.gray(right);
+  }
+  const rightWidth = rightParts.length ? visibleWidth(rightParts.join(" · ")) : 0;
+
+  // Left identity segment (plain text; painted as one bg block at the end).
+  const bits: string[] = [];
+  let modelBit = `${unicode ? "⬢" : "*"} ${d.model}`;
+  if (d.thinking) modelBit += ` · ${unicode ? "◔" : "@"} ${d.thinking}`;
+  bits.push(modelBit);
+  if (d.branch) {
+    const dirty = d.dirtyCount && d.dirtyCount > 0 ? ` ?${d.dirtyCount}` : "";
+    bits.push(`${unicode ? "⑂" : "y"} ${d.branch}${dirty}`);
+  }
+  // Budget the cwd into whatever width remains (right stats + 2-col gap reserved).
+  const leftBudget = Math.max(8, cols - rightWidth - (rightWidth > 0 ? 2 : 0));
+  if (d.cwd) {
+    const used = visibleWidth(` ${bits.join(sep)}${sep}${unicode ? "▸" : ">"}  `);
+    const room = leftBudget - used - 1;
+    if (room >= 4) bits.push(`${unicode ? "▸" : ">"} ${shortenCwd(d.cwd, room, unicode)}`);
+  }
+  let left = ` ${bits.join(sep)} `;
+  if (visibleWidth(left) > leftBudget) left = left.slice(0, leftBudget);
+
+  const gap = Math.max(0, cols - visibleWidth(left) - rightWidth);
+  const level = d.colorLevel ?? (useColor ? ColorLevel.TrueColor : ColorLevel.None);
+  const grad = d.gradient ?? { from: "#0a3d62", to: "#48dbfb" };
+  const paintedLeft = useColor
+    ? applyBgGradient(left, hexToRgb(grad.from), hexToRgb(grad.to), level)
+    : left;
+  return `${paintedLeft}${" ".repeat(gap)}${right}`;
+}
+
+export interface JeoStatusData {
+  colorLevel?: number;
+  phase?: number;
+  palette?: readonly string[];
+  isThinking?: boolean;
   step?: number;
   maxSteps?: number;
   elapsedMs?: number;
@@ -13,6 +121,20 @@ export interface JocStatusData {
   totalCount?: number;
   mutationGuarded?: boolean;
   unicode?: boolean;
+  color?: boolean;
+  /** Compact evolution-stage identity (e.g. "●●○○○ Double Helix (DNA) [2/5]") shown in the
+   *  forge line so the current stage — the double helix — is always exposed, even when the
+   *  large ASCII art is dropped on short terminals. */
+  stage?: string;
+  stepElapsedMs?: number;
+  avgStepMs?: number;
+  /** Cumulative turn token usage (engine onUsage) shown live on the [STEP] row. */
+  usage?: { inputTokens: number; outputTokens: number } | null;
+  /** Live USD cost for the turn (price table × usage); omit when the model has no known price. */
+  costUsd?: number;
+  /** True while a delegated subagent turn is in flight — renders gjc's `(sub)` marker. */
+  subagentActive?: boolean;
+
 }
 
 export function progressPercent(step: number | undefined, maxSteps: number | undefined): number {
@@ -24,22 +146,161 @@ function seconds(ms: number | undefined): number {
   return Number.isFinite(ms) && (ms ?? 0) > 0 ? Math.round((ms ?? 0) / 1000) : 0;
 }
 
-export function renderJocStatus(data: JocStatusData): string[] {
-  const step = Number.isFinite(data.step) ? Math.max(0, Math.trunc(data.step ?? 0)) : 0;
-  const max = Number.isFinite(data.maxSteps) && (data.maxSteps ?? 0) > 0 ? Math.trunc(data.maxSteps ?? 0) : 0;
-  const pct = progressPercent(step, max);
-  const bar = meter(step, max || 1, 10, { unicode: data.unicode !== false });
+export function renderJeoStatus(data: JeoStatusData): string[] {
+  const useColor = data.color !== false;
   const elapsed = `${seconds(data.elapsedMs)}s`;
-  const msg = data.message ?? "thinking through the next tool call";
+  let msg = data.message ?? "thinking through the next tool call";
+  const level = data.colorLevel ?? (useColor ? ColorLevel.TrueColor : ColorLevel.None);
+  if (useColor && data.isThinking && level === ColorLevel.TrueColor && data.palette && data.palette.length > 0) {
+    const phase = data.phase ?? 0;
+    msg = animatedGradientText(msg, data.palette, phase, { colorLevel: level });
+  }
   const current = data.currentTool ? `forging ${data.currentTool}` : "forge idle";
+  const stage = data.stage ? `${data.stage} · ` : "";
   const ok = data.okCount ?? 0;
   const fail = data.failCount ?? 0;
   const running = data.runningCount ?? 0;
   const total = data.totalCount ?? ok + fail + running;
-  const guard = data.mutationGuarded ? ` · ${chalk.red.bold("mutation locked")}` : "";
 
+  const cyanBold = useColor ? chalk.cyan.bold : (s: string) => s;
+  const magentaBold = useColor ? chalk.magenta.bold : (s: string) => s;
+  const redBold = useColor ? chalk.red.bold : (s: string) => s;
+  const green = useColor ? chalk.green : (s: string) => s;
+  const yellow = useColor ? chalk.yellow : (s: string) => s;
+  const red = useColor ? chalk.red : (s: string) => s;
+  const toolCounts = `${green(`${ok} ok`)} / ${red(`${fail} fail`)} / ${yellow(`${running} running`)}`;
+
+  const guard = data.mutationGuarded ? ` · ${redBold("mutation locked")}` : "";
+  let extraStats = "";
+  if (Number.isFinite(data.stepElapsedMs)) {
+    extraStats += ` · now ${(data.stepElapsedMs! / 1000).toFixed(1)}s`;
+  }
+  if (Number.isFinite(data.avgStepMs)) {
+    extraStats += ` · avg ${(data.avgStepMs! / 1000).toFixed(1)}s`;
+  }
+  // Live token spend for the turn — visible per step, not only in the final summary.
+  if (data.usage && (data.usage.inputTokens || data.usage.outputTokens)) {
+    extraStats += ` · ${formatUsage(data.usage)}`;
+    // gjc-parity live output-token rate (logs/gjc-tui-study analysis Gap B):
+    // `⤴ N.N/s` like gjc's HUD. Derived purely from existing usage + elapsed —
+    // no new data sources; gated past the first second so a fresh turn doesn't
+    // flash a meaningless spike.
+    const elapsedSec = (data.elapsedMs ?? 0) / 1000;
+    if (elapsedSec >= 1 && (data.usage.outputTokens ?? 0) > 0) {
+      const rate = data.usage.outputTokens / elapsedSec;
+      const glyph = data.unicode !== false ? "⤴" : "^";
+      extraStats += ` · ${glyph} ${rate >= 100 ? rate.toFixed(0) : rate.toFixed(1)}/s`;
+    }
+  }
+  // Live USD cost (gjc parity `$0.42 (sub)`): only when a known price produced a figure.
+  if (typeof data.costUsd === "number" && Number.isFinite(data.costUsd) && data.costUsd > 0) {
+    extraStats += ` · ${formatCost(data.costUsd)}`;
+  }
+  if (data.subagentActive) {
+    extraStats += " (sub)";
+  }
+  // No step counter / step-driven meter here: with the dynamic step budget the
+  // denominator keeps extending, so `step n/m` carried no information (user feedback).
   return [
-    `  ${chalk.cyan.bold("joc thinking")} · ${msg} · step ${step}/${max} · ${pct}% ${bar} · ${elapsed}`,
-    `  ${chalk.magenta.bold("joc forge")} · ${current} · tools ${total} (${ok} ok / ${fail} fail / ${running} running)${guard}`,
+    `  ${categoryBadge("progress", { color: useColor })} elapsed ${elapsed}${extraStats}`,
+    `  ${categoryBadge("status", { color: useColor })} ${cyanBold("jeo status")} · ${msg}`,
+    `  ${categoryBadge("tool", { color: useColor })} ${magentaBold("jeo forge")} · ${stage}${current} · tools ${total} (${toolCounts})${guard}`,
   ];
+
+}
+
+export interface StatusBoxData extends JeoStatusData {
+  /** Frame width the status lines should fit. */
+  cols: number;
+  /** Phase label leading the activity row (thinking/planning/executing/reporting). */
+  phaseLabel?: string;
+  /** Current spinner frame glyph. */
+  spinner?: string;
+  /** Live streamed model activity (reasoning/uniform fallback); overrides `message`. */
+  activity?: string;
+  /** Append gjc's ⟦esc⟧ cancel hint to the activity row. */
+  escHint?: boolean;
+}
+
+/**
+ * Live status lines — UNBOXED (user feedback: the message/status must not be
+ * trapped inside a border). A fixed two-row layout:
+ *
+ *   ⠙ thinking · <live reasoning / current activity>          ⟦esc⟧
+ *     12s · now 2.5s · avg 2.5s · 8.2k in / 30 out · ⤴ 6/s · 2 ok
+ *
+ * The spinner + dim phase label lead the live thinking text, the cancel hint is
+ * right-aligned, and one compact dim metrics row folds timing/usage/rate/cost/
+ * tool-counts together. Step counters and the step-driven meter are deliberately
+ * absent: the dynamic step budget keeps extending the denominator, so `step n/m`
+ * carried no information.
+ */
+export function renderStatusBox(data: StatusBoxData): string[] {
+  const unicode = data.unicode !== false;
+  const useColor = data.color !== false;
+  const cols = Math.max(24, Math.trunc(data.cols));
+  const dim = useColor ? chalk.dim : (s: string) => s;
+  const gray = useColor ? chalk.gray : (s: string) => s;
+
+  // Activity row: spinner + phase + live thinking text (+ right-aligned ⟦esc⟧).
+  let activity = (data.activity?.trim() || data.message || "thinking through the next tool call").replace(/\s+/g, " ");
+  const level = data.colorLevel ?? (useColor ? ColorLevel.TrueColor : ColorLevel.None);
+  const esc = data.escHint ? (unicode ? "⟦esc⟧" : "[esc]") : "";
+  const spin = data.spinner ?? "";
+  const phaseLabel = data.phaseLabel ?? "thinking";
+  const headPlain = `${spin ? `${spin} ` : ""}${phaseLabel} ${unicode ? "·" : "-"} `;
+  const room = Math.max(8, cols - 1 - visibleWidth(headPlain) - (esc ? visibleWidth(esc) + 1 : 0));
+  if (visibleWidth(activity) > room) {
+    let w = 0; let cut = "";
+    for (const ch of activity) {
+      const cw = visibleWidth(ch);
+      if (w + cw > room - 1) break;
+      cut += ch; w += cw;
+    }
+    activity = cut + (unicode ? "…" : "...");
+  }
+  const plainActivityWidth = visibleWidth(activity);
+  if (useColor && data.isThinking && level === ColorLevel.TrueColor && data.palette && data.palette.length > 0) {
+    activity = animatedGradientText(activity, data.palette, data.phase ?? 0, { colorLevel: level });
+  }
+  const escPad = esc
+    ? " ".repeat(Math.max(1, cols - 1 - visibleWidth(headPlain) - plainActivityWidth - visibleWidth(esc))) + dim(esc)
+    : "";
+  const head = useColor
+    ? `${spin ? `${spin} ` : ""}${chalk.cyan.bold(phaseLabel)} ${dim(unicode ? "·" : "-")} `
+    : headPlain;
+  const activityRow = ` ${head}${activity}${escPad}`;
+
+  // Compact metrics row: elapsed · now/avg timing · usage · rate · cost · tools.
+  const bits: string[] = [`${seconds(data.elapsedMs)}s`];
+  if (Number.isFinite(data.stepElapsedMs)) bits.push(`now ${(data.stepElapsedMs! / 1000).toFixed(1)}s`);
+  if (Number.isFinite(data.avgStepMs)) bits.push(`avg ${(data.avgStepMs! / 1000).toFixed(1)}s`);
+  if (data.usage && (data.usage.inputTokens || data.usage.outputTokens)) {
+    bits.push(formatUsage(data.usage));
+    const elapsedSec = (data.elapsedMs ?? 0) / 1000;
+    if (elapsedSec >= 1 && (data.usage.outputTokens ?? 0) > 0) {
+      const rate = data.usage.outputTokens / elapsedSec;
+      bits.push(`${unicode ? "⤴" : "^"} ${rate >= 100 ? rate.toFixed(0) : rate.toFixed(1)}/s`);
+    }
+  }
+  if (typeof data.costUsd === "number" && Number.isFinite(data.costUsd) && data.costUsd > 0) bits.push(formatCost(data.costUsd));
+  const ok = data.okCount ?? 0;
+  const fail = data.failCount ?? 0;
+  const running = data.runningCount ?? 0;
+  if (ok + fail + running > 0) {
+    const counts: string[] = [];
+    if (ok) counts.push(useColor ? chalk.green(`${ok} ok`) : `${ok} ok`);
+    if (fail) counts.push(useColor ? chalk.red(`${fail} fail`) : `${fail} fail`);
+    if (running) counts.push(useColor ? chalk.yellow(`${running} run`) : `${running} run`);
+    bits.push(counts.join(" / "));
+  }
+  if (data.subagentActive) bits.push("(sub)");
+  if (data.mutationGuarded) bits.push(useColor ? chalk.red.bold("mutation locked") : "mutation locked");
+  // Width-fit by dropping trailing WHOLE segments (never mid-ANSI cuts): the
+  // leading elapsed/timing bits carry the most signal and always survive.
+  const metricsIndent = "   ";
+  const maxMetricsWidth = Math.max(8, cols - metricsIndent.length);
+  while (bits.length > 1 && visibleWidth(bits.join(" · ")) > maxMetricsWidth) bits.pop();
+  const metricsRow = `${metricsIndent}${gray(bits.join(" · "))}`;
+  return [activityRow, metricsRow];
 }

package/src/tui/components/step-timeline.ts

@@ -0,0 +1,218 @@
+/**
+ * Step-process timeline — a vertical, status-colored render of the agent's
+ * step sequence (one row per tool step) with a state glyph, an animated active
+ * marker, a connector gutter, and a summary line. Used by `LaunchTui.finish()`
+ * to collapse a turn into a readable process trace. Pure functions over a step
+ * list (color via chalk), so they unit-test with an ANSI-stripping helper.
+ */
+import chalk from "chalk";
+import { categoryBadge, type UiCategory } from "./category-index";
+import type { ToolStatus } from "./tool-list";
+
+export type StepState = "pending" | "active" | "done" | "failed";
+
+export interface TimelineStep {
+  label: string;
+  state: StepState;
+  /** Optional trailing detail (e.g. a file path or short result note). */
+  detail?: string;
+}
+
+const GLYPH_UNICODE: Record<StepState, string> = { pending: "○", active: "◐", done: "●", failed: "✗" };
+const GLYPH_ASCII: Record<StepState, string> = { pending: "o", active: "*", done: "x", failed: "!" };
+const SPIN_UNICODE = ["◐", "◓", "◑", "◒"];
+const SPIN_ASCII = ["|", "/", "-", "\\"];
+
+/** Glyph for a step state; an `active` step with a frame index animates a spinner. */
+export function stepGlyph(state: StepState, opts: { unicode?: boolean; frame?: number } = {}): string {
+  const unicode = opts.unicode !== false;
+  if (state === "active" && typeof opts.frame === "number") {
+    const set = unicode ? SPIN_UNICODE : SPIN_ASCII;
+    return set[((opts.frame % set.length) + set.length) % set.length];
+  }
+  return (unicode ? GLYPH_UNICODE : GLYPH_ASCII)[state];
+}
+
+/** Map a state to its chalk colorizer (identity when color is off). */
+export function colorForState(state: StepState, color = true): (s: string) => string {
+  if (!color) return (s: string) => s;
+  switch (state) {
+    case "pending": return chalk.gray;
+    case "active": return chalk.yellow;
+    case "done": return chalk.green;
+    case "failed": return chalk.red;
+  }
+}
+
+/** Map a live ToolStatus to a timeline state. */
+export function stateFromToolStatus(status: ToolStatus): StepState {
+  return status === "running" ? "active" : status === "ok" ? "done" : "failed";
+}
+
+/** Build timeline steps from a ToolList snapshot. */
+export function stepsFromTools(rows: { tool: string; status: ToolStatus }[]): TimelineStep[] {
+  return rows.map(r => ({ label: r.tool, state: stateFromToolStatus(r.status) }));
+}
+
+export interface StepSummary {
+  pending: number;
+  active: number;
+  done: number;
+  failed: number;
+  total: number;
+}
+
+export function summarizeSteps(steps: TimelineStep[]): StepSummary {
+  const s: StepSummary = { pending: 0, active: 0, done: 0, failed: 0, total: steps.length };
+  for (const step of steps) s[step.state]++;
+  return s;
+}
+
+/** One-line summary, e.g. "✓3 ✗1 ·1 / 5" (ASCII: "ok3 x1 .1 / 5"). */
+export function formatStepSummary(steps: TimelineStep[], opts: { unicode?: boolean; color?: boolean } = {}): string {
+  const unicode = opts.unicode !== false;
+  const color = opts.color !== false;
+  const s = summarizeSteps(steps);
+  const okMark = unicode ? "✓" : "ok";
+  const failMark = unicode ? "✗" : "x";
+  const pendMark = unicode ? "·" : ".";
+  const wrap = (fn: (x: string) => string, t: string) => (color ? fn(t) : t);
+  const parts = [
+    wrap(chalk.green, `${okMark}${s.done}`),
+    s.failed ? wrap(chalk.red, `${failMark}${s.failed}`) : "",
+    s.active ? wrap(chalk.yellow, `${unicode ? "◐" : "*"}${s.active}`) : "",
+    s.pending ? wrap(chalk.gray, `${pendMark}${s.pending}`) : "",
+  ].filter(Boolean);
+  return `${parts.join(" ")} / ${s.total}`;
+}
+
+export interface TimelineOptions {
+  unicode?: boolean;
+  color?: boolean;
+  /** Animation frame for the active step's spinner. */
+  frame?: number;
+  /** Draw a connector gutter (│ / └) between steps. */
+  connectors?: boolean;
+  /** Truncate labels+detail to this many visible chars. */
+  maxWidth?: number;
+  /** Title line above the timeline. */
+  title?: string;
+  /** Bold the active step row. */
+  highlightActive?: boolean;
+  /** Keep only the most recent N rows (older collapse to a "(+M earlier)" line). */
+  maxRows?: number;
+  /** Render the [NN:CAT] badge per row (default true); false → gjc-style bare rows. */
+  badges?: boolean;
+}
+
+/**
+ * Render a numbered, status-colored step timeline:
+ *   1 ● read        ok
+ *   2 ◐ bash        running…
+ *   3 ✗ edit        FAILED
+ */
+export function formatStepTimeline(steps: TimelineStep[], opts: TimelineOptions = {}): string[] {
+  const unicode = opts.unicode !== false;
+  const color = opts.color !== false;
+  const connectors = opts.connectors ?? true;
+  if (steps.length === 0) return [opts.title ?? (color ? chalk.gray("  (no steps)") : "  (no steps)")];
+
+  const out: string[] = [];
+  if (opts.title) out.push(opts.title);
+  const idxW = String(steps.length).length;
+  const vbar = unicode ? "│" : "|";
+  const corner = unicode ? "└" : "`";
+
+  // Keep only the most recent maxRows; collapse the rest to a count line.
+  let startIdx = 0;
+  if (opts.maxRows && opts.maxRows > 0 && steps.length > opts.maxRows) {
+    startIdx = steps.length - opts.maxRows;
+    out.push(color ? chalk.gray(`  · (+${startIdx} earlier)`) : `  · (+${startIdx} earlier)`);
+  }
+
+  for (let i = startIdx; i < steps.length; i++) {
+    const step = steps[i];
+    const last = i === steps.length - 1;
+    const conn = connectors ? (last ? corner : vbar) : " ";
+    const glyph = stepGlyph(step.state, { unicode, frame: opts.frame });
+    const paint = colorForState(step.state, color);
+    let label = step.label;
+    if (step.detail) label += ` ${step.detail}`;
+    if (opts.maxWidth && label.length > opts.maxWidth) label = label.slice(0, opts.maxWidth - 1) + "…";
+    if (color) {
+      if (step.state === "done") {
+        label = `\x1b[9m${chalk.gray(chalk.dim(label))}\x1b[29m`;
+      } else if (step.state === "failed") {
+        label = chalk.red(label);
+      } else if (step.state === "active") {
+        if (opts.highlightActive) {
+          label = chalk.cyan.bold(label);
+        }
+      } else if (step.state === "pending") {
+        label = chalk.dim(label);
+      }
+    }
+    const cat: UiCategory = step.state === "active" ? "progress" : step.state === "done" ? "done" : step.state === "failed" ? "error" : "tool";
+    const badge = opts.badges === false ? "" : ` ${categoryBadge(cat, { index: i + 1, color })}`;
+    out.push(`  ${conn} ${paint(glyph)}${badge} ${label}`);
+  }
+  return out;
+}
+
+/** Compact duration: 0.9s under a minute, else Mm Ss; sub-second as Nms. */
+export function formatDuration(ms: number): string {
+  if (ms < 1000) return `${Math.max(0, Math.round(ms))}ms`;
+  const s = ms / 1000;
+  if (s < 60) return `${s.toFixed(1)}s`;
+  const m = Math.floor(s / 60);
+  return `${m}m ${Math.round(s % 60)}s`;
+}
+
+/** Header line: "Steps  ✓2 ✗1 ◐1 / 4  ·  3.2s". */
+export function formatStepHeader(
+  steps: TimelineStep[],
+  opts: { elapsedMs?: number; unicode?: boolean; color?: boolean; label?: string } = {},
+): string {
+  const color = opts.color !== false;
+  const title = opts.label ?? "Steps";
+  const head = color ? chalk.bold(title) : title;
+  const summary = formatStepSummary(steps, { unicode: opts.unicode, color });
+  const tail = typeof opts.elapsedMs === "number" ? `  ·  ${formatDuration(opts.elapsedMs)}` : "";
+  return `${head}  ${summary}${tail}`;
+}
+
+/** Horizontal glyph strip, e.g. "● ● ✗ ◐" — a glanceable status bar. */
+export function formatStepTimelineCompact(
+  steps: TimelineStep[],
+  opts: { unicode?: boolean; color?: boolean; frame?: number; cap?: number } = {},
+): string {
+  if (steps.length === 0) return "";
+  const unicode = opts.unicode !== false;
+  const color = opts.color !== false;
+  const cap = opts.cap ?? 40;
+  const shown = steps.slice(-cap);
+  const glyphs = shown.map(s => {
+    const g = stepGlyph(s.state, { unicode, frame: opts.frame });
+    return color ? colorForState(s.state, true)(g) : g;
+  });
+  const overflow = steps.length > cap ? (color ? chalk.gray(` +${steps.length - cap}`) : ` +${steps.length - cap}`) : "";
+  return glyphs.join(" ") + overflow;
+}
+
+/** A done/total progress bar: "▓▓▓░░ 3/5" (ascii: "###.. 3/5"). */
+export function formatProgressBar(
+  done: number,
+  total: number,
+  opts: { width?: number; unicode?: boolean; color?: boolean } = {},
+): string {
+  const width = Math.max(1, opts.width ?? 10);
+  const unicode = opts.unicode !== false;
+  const color = opts.color !== false;
+  const ratio = total > 0 ? Math.min(1, Math.max(0, done / total)) : 0;
+  const filled = Math.round(ratio * width);
+  const fillCh = unicode ? "▓" : "#";
+  const emptyCh = unicode ? "░" : ".";
+  const bar = fillCh.repeat(filled) + emptyCh.repeat(width - filled);
+  const painted = color ? chalk.green(fillCh.repeat(filled)) + chalk.gray(emptyCh.repeat(width - filled)) : bar;
+  return `${painted} ${done}/${total}`;
+}

package/src/tui/components/stream.ts

@@ -1,20 +1,36 @@
+/**
+ * Streamed-output region. Keeps a BOUNDED ring of completed lines (+ a trailing
+ * partial line not yet terminated by "\n") so memory and per-frame render cost
+ * stay flat over a long session instead of growing with total output (the old
+ * implementation accumulated one ever-growing string and re-split/re-wrapped it
+ * every 120ms frame).
+ */
 export class StreamRegion {
-  private buffer: string = "";
+  private lines: string[] = [];
+  private partial = "";
+  private readonly cap: number;
+
+  constructor(cap = 500) {
+    this.cap = Math.max(1, cap);
+  }
 
   append(text: string): void {
-    this.buffer += text;
+    const parts = (this.partial + text).split("\n");
+    this.partial = parts.pop() ?? "";
+    if (parts.length > 0) {
+      for (const p of parts) this.lines.push(p);
+      // Trim from the front so the ring never exceeds `cap` completed lines.
+      if (this.lines.length > this.cap) this.lines.splice(0, this.lines.length - this.cap);
+    }
   }
 
   render(width: number, maxLines?: number): string[] {
-    if (this.buffer === "") {
-      return [];
-    }
+    const all = this.partial ? [...this.lines, this.partial] : this.lines;
+    if (all.length === 0) return [];
 
     const cols = Math.max(1, width);
-    const segments = this.buffer.split("\n");
     const result: string[] = [];
-
-    for (const segment of segments) {
+    for (const segment of all) {
       if (segment === "") {
         result.push("");
       } else {
@@ -31,6 +47,7 @@ export class StreamRegion {
   }
 
   clear(): void {
-    this.buffer = "";
+    this.lines = [];
+    this.partial = "";
   }
 }