jeo-code 0.1.0

package/src/tui/components/color.ts

@@ -0,0 +1,172 @@
+/**
+ * Terminal color-capability detection + a tiny truecolor gradient engine.
+ *
+ * The evolution TUI wants smooth per-character color gradients across its ASCII
+ * art, but a terminal might support 24-bit truecolor, 256 colors, 16 colors, or
+ * nothing at all. This module detects the level from the environment (honoring
+ * `NO_COLOR` / `FORCE_COLOR` / `COLORTERM` / `TERM`) and renders gradients that
+ * gracefully downgrade: truecolor → 256 → 16 → plain text.
+ *
+ * Escapes are emitted directly (not via chalk) so the output is deterministic
+ * and testable regardless of chalk's own TTY auto-detection.
+ */
+
+/** Color capability tiers. */
+export enum ColorLevel {
+  None = 0,
+  Basic = 1, // 16 colors
+  Ansi256 = 2,
+  TrueColor = 3,
+}
+
+export interface RGB {
+  r: number;
+  g: number;
+  b: number;
+}
+
+export type EnvLike = Record<string, string | undefined>;
+
+const ESC = "\x1b[";
+/** Matches any SGR / CSI escape sequence. */
+const ANSI_RE = /\x1b\[[0-9;]*m/g;
+
+/** Remove every SGR escape sequence, leaving only visible characters. */
+export function stripAnsi(s: string): string {
+  return s.replace(ANSI_RE, "");
+}
+
+/** Visible (printable) width of a string, ignoring SGR escapes. */
+export function visibleWidth(s: string): number {
+  return stripAnsi(s).length;
+}
+
+/**
+ * Detect the terminal color level from an environment map. Pure + injectable so
+ * tests can pin behavior. `isTty` is a hint for the ambiguous "no signal" case.
+ */
+export function detectColorLevel(env: EnvLike = process.env, isTty = false): ColorLevel {
+  // NO_COLOR: presence (any value, even empty) disables color. https://no-color.org
+  if (env.NO_COLOR !== undefined) return ColorLevel.None;
+
+  const force = env.FORCE_COLOR;
+  if (force !== undefined) {
+    if (force === "0" || force === "false") return ColorLevel.None;
+    if (force === "1" || force === "true") return ColorLevel.Basic;
+    if (force === "2") return ColorLevel.Ansi256;
+    if (force === "3") return ColorLevel.TrueColor;
+    // Any other truthy value: assume basic.
+    return ColorLevel.Basic;
+  }
+
+  const term = (env.TERM ?? "").toLowerCase();
+  if (term === "dumb") return ColorLevel.None;
+
+  const colorterm = (env.COLORTERM ?? "").toLowerCase();
+  if (colorterm === "truecolor" || colorterm === "24bit") return ColorLevel.TrueColor;
+
+  if (/-256(color)?$/.test(term) || term.includes("256")) return ColorLevel.Ansi256;
+  if (/^(xterm|screen|vt100|vt220|rxvt|tmux|ansi|linux|konsole|alacritty|kitty|wezterm)/.test(term)) {
+    return ColorLevel.Basic;
+  }
+
+  return isTty ? ColorLevel.Basic : ColorLevel.None;
+}
+
+/** Parse `#rrggbb` / `#rgb` / `rrggbb` into an RGB triple. Defaults to black on bad input. */
+export function hexToRgb(hex: string): RGB {
+  let h = hex.trim().replace(/^#/, "");
+  if (h.length === 3) h = h[0]! + h[0]! + h[1]! + h[1]! + h[2]! + h[2]!;
+  if (!/^[0-9a-fA-F]{6}$/.test(h)) return { r: 0, g: 0, b: 0 };
+  return {
+    r: parseInt(h.slice(0, 2), 16),
+    g: parseInt(h.slice(2, 4), 16),
+    b: parseInt(h.slice(4, 6), 16),
+  };
+}
+
+const clamp255 = (n: number) => Math.max(0, Math.min(255, Math.round(n)));
+
+/** Linear interpolation between two RGB colors. `t` in [0,1]. */
+export function lerpColor(a: RGB, b: RGB, t: number): RGB {
+  const k = Math.max(0, Math.min(1, t));
+  return {
+    r: clamp255(a.r + (b.r - a.r) * k),
+    g: clamp255(a.g + (b.g - a.g) * k),
+    b: clamp255(a.b + (b.b - a.b) * k),
+  };
+}
+
+/** `n` evenly spaced RGB stops from `from` to `to` (inclusive endpoints). */
+export function gradientStops(from: RGB, to: RGB, n: number): RGB[] {
+  const count = Math.max(1, Math.trunc(n));
+  if (count === 1) return [from];
+  const out: RGB[] = [];
+  for (let i = 0; i < count; i++) out.push(lerpColor(from, to, i / (count - 1)));
+  return out;
+}
+
+/** Convert an RGB triple to the nearest xterm-256 color index. */
+export function rgbToAnsi256(c: RGB): number {
+  const { r, g, b } = c;
+  // Grayscale ramp (232-255) when channels are near-equal.
+  if (Math.abs(r - g) < 8 && Math.abs(g - b) < 8) {
+    if (r < 8) return 16;
+    if (r > 248) return 231;
+    return Math.round(((r - 8) / 247) * 24) + 232;
+  }
+  const q = (v: number) => Math.round((v / 255) * 5);
+  return 16 + 36 * q(r) + 6 * q(g) + q(b);
+}
+
+/** Convert an RGB triple to the nearest basic 16-color SGR foreground code (30-37 / 90-97). */
+export function rgbToAnsi16(c: RGB): number {
+  const { r, g, b } = c;
+  const max = Math.max(r, g, b);
+  if (max < 40) return 30; // black
+  const bright = max > 170;
+  const bit = (v: number) => (v > max / 2 ? 1 : 0);
+  const code = bit(r) + bit(g) * 2 + bit(b) * 4; // 0..7
+  return (bright ? 90 : 30) + code;
+}
+
+/** Open-foreground escape for one color at a given level (empty at None). */
+export function fgEscape(c: RGB, level: ColorLevel): string {
+  switch (level) {
+    case ColorLevel.TrueColor:
+      return `${ESC}38;2;${c.r};${c.g};${c.b}m`;
+    case ColorLevel.Ansi256:
+      return `${ESC}38;5;${rgbToAnsi256(c)}m`;
+    case ColorLevel.Basic:
+      return `${ESC}${rgbToAnsi16(c)}m`;
+    default:
+      return "";
+  }
+}
+
+/** Reset escape (empty at None). */
+export function resetEscape(level: ColorLevel): string {
+  return level === ColorLevel.None ? "" : `${ESC}0m`;
+}
+
+/**
+ * Apply a left→right color gradient across the visible characters of `text`.
+ * SGR escapes already in `text` are stripped first (the gradient owns color).
+ * At `ColorLevel.None` the plain text is returned unchanged. Whitespace runs
+ * still consume gradient positions so multi-line art stays phase-aligned.
+ */
+export function applyGradient(text: string, from: RGB, to: RGB, level: ColorLevel = ColorLevel.TrueColor): string {
+  const plain = stripAnsi(text);
+  if (level === ColorLevel.None || plain.length === 0) return plain;
+  const stops = gradientStops(from, to, plain.length);
+  let out = "";
+  for (let i = 0; i < plain.length; i++) {
+    const ch = plain[i]!;
+    if (ch === " ") {
+      out += ch; // don't paint spaces (keeps escapes lean, transparent bg)
+      continue;
+    }
+    out += fgEscape(stops[i]!, level) + ch;
+  }
+  return out + resetEscape(level);
+}

package/src/tui/components/config-panel.ts

@@ -0,0 +1,193 @@
+/**
+ * Pure formatters for the TUI configuration panels (`/model`, `/models`,
+ * `/provider`, `/agents`, `/config`). Each returns plain string lines (color via
+ * chalk) so it can be unit-tested with an ANSI-stripping helper and reused by
+ * both the interactive REPL and one-shot commands.
+ */
+import chalk from "chalk";
+import type { ProviderStatus } from "../../ai/provider-status";
+import type { SubagentRole } from "../../agent/subagents";
+import type { ProviderModelsResult } from "../../ai/model-discovery";
+import type { PickEntry } from "../../ai/model-picker";
+import type { CatalogModel } from "../../ai/model-catalog";
+import type { EnrichedModel } from "../../ai/model-enrich";
+import { formatTokens } from "../../ai/model-catalog";
+
+/** A single "Model: alias → resolved (provider)" status line. */
+export function formatModelLine(d: {
+  label: string;
+  resolved: string;
+  provider: string;
+  ready?: boolean;
+}): string {
+  const expansion = d.resolved !== d.label ? ` → ${d.resolved}` : "";
+  const readyMark = d.ready === undefined ? "" : d.ready ? ` ${chalk.green("✓")}` : ` ${chalk.yellow("· no credential")}`;
+  return `${chalk.bold(d.label)}${expansion} ${chalk.gray(`(${d.provider})`)}${readyMark}`;
+}
+
+/** Aliases section: ` alias      → target` lines, sorted by alias. */
+export function formatAliasLines(aliases: Record<string, string>): string[] {
+  const entries = Object.entries(aliases).sort((a, b) => a[0].localeCompare(b[0]));
+  if (entries.length === 0) return ["  (no aliases)"];
+  const width = Math.max(...entries.map(([a]) => a.length), 4);
+  return entries.map(([alias, target]) => `  ${alias.padEnd(width)} → ${target}`);
+}
+
+/** Provider credential table: ` name      ✓ label  [baseUrl]`. */
+export function formatProviderPanel(statuses: ProviderStatus[]): string[] {
+  if (statuses.length === 0) return ["  (no providers)"];
+  const width = Math.max(...statuses.map(s => s.name.length), 6);
+  return statuses.map(s => {
+    const mark = s.ready ? chalk.green("✓") : chalk.gray("·");
+    const base = s.baseUrl ? chalk.gray(`  [${s.baseUrl}]`) : "";
+    const label = s.ready ? s.label : chalk.yellow(s.label);
+    return `  ${s.name.padEnd(width)} ${mark} ${label}${base}`;
+  });
+}
+
+/** Subagent roster: ` id        title — model ≤N steps  (read-only)`. */
+export function formatAgentsPanel(
+  roles: readonly SubagentRole[],
+  resolve: (role: SubagentRole) => { model: string; maxSteps: number },
+): string[] {
+  if (roles.length === 0) return ["  (no subagent roles)"];
+  const width = Math.max(...roles.map(r => r.id.length), 8);
+  return roles.map(r => {
+    const { model, maxSteps } = resolve(r);
+    const ro = r.readOnly ? chalk.gray("  (read-only)") : "";
+    return `  ${chalk.cyan(r.id.padEnd(width))} ${r.title} — ${model} ≤${maxSteps} steps${ro}`;
+  });
+}
+
+/** Detail block for a single subagent role. */
+export function formatAgentDetail(
+  role: SubagentRole,
+  resolved: { model: string; maxSteps: number },
+): string[] {
+  return [
+    `${chalk.cyan(role.id)} — ${role.title}`,
+    `  ${role.description}`,
+    `  model:     ${resolved.model}`,
+    `  maxSteps:  ${resolved.maxSteps}`,
+    `  mutates:   ${role.readOnly ? "no (read-only: read/find/search only)" : "yes (full toolset)"}`,
+  ];
+}
+
+/** Effective runtime-config snapshot used by `/config`. */
+export function formatConfigPanel(d: {
+  model: string;
+  resolved: string;
+  provider: string;
+  thinkingLevel: string;
+  ollamaBaseUrl?: string;
+  openaiBaseUrl?: string;
+  requestMaxRetries?: number;
+  sessionId?: string;
+}): string[] {
+  const lines = [
+    `  model:     ${formatModelLine({ label: d.model, resolved: d.resolved, provider: d.provider })}`,
+    `  thinking:  ${d.thinkingLevel}`,
+  ];
+  if (d.ollamaBaseUrl) lines.push(`  ollama:    ${d.ollamaBaseUrl}`);
+  if (d.openaiBaseUrl) lines.push(`  openai:    ${d.openaiBaseUrl}`);
+  if (typeof d.requestMaxRetries === "number") lines.push(`  retries:   ${d.requestMaxRetries}`);
+  if (d.sessionId) lines.push(`  session:   ${d.sessionId}`);
+  return lines;
+}
+
+/**
+ * Live-discovered models grouped by provider. Each provider header shows the
+ * auth source or a failure reason; the active model id (if any) is marked.
+ */
+export function formatLiveModels(
+  results: ProviderModelsResult[],
+  opts: { current?: string; perProvider?: number } = {},
+): string[] {
+  const cap = opts.perProvider ?? 12;
+  const lines: string[] = [];
+  for (const r of results) {
+    if (r.ok && r.models.length === 0) continue; // reachable but empty → skip the header noise
+    if (!r.ok) {
+      lines.push(`${chalk.bold(r.provider)} ${chalk.gray(`(${r.source})`)}: ${chalk.yellow(r.error ?? "unavailable")}`);
+      continue;
+    }
+    lines.push(`${chalk.bold(r.provider)} ${chalk.gray(`(${r.source})`)}: ${r.models.length} model${r.models.length === 1 ? "" : "s"}`);
+    for (const m of r.models.slice(0, cap)) {
+      const mark = opts.current && m === opts.current ? chalk.green(" ◀ current") : "";
+      lines.push(`  ${m}${mark}`);
+    }
+    if (r.models.length > cap) lines.push(chalk.gray(`  …(+${r.models.length - cap} more)`));
+  }
+  if (lines.length === 0) lines.push("  (no live models — log in with 'joc auth login' or start Ollama)");
+  return lines;
+}
+
+/** True when `model` appears in a provider's discovered list (exact match). */
+export function liveModelKnown(results: ProviderModelsResult[], model: string): boolean {
+  return results.some(r => r.ok && r.models.includes(model));
+}
+
+/**
+ * Numbered pick list: `  #N  model  (provider)`. Select one with `/model #N`.
+ * The active model (if any) is marked.
+ */
+export function formatPickList(entries: PickEntry[], opts: { current?: string; cap?: number } = {}): string[] {
+  if (entries.length === 0) return ["  (no models — log in with 'joc auth login' or start Ollama)"];
+  const cap = opts.cap ?? 60;
+  const width = String(Math.min(entries.length, cap)).length + 1; // "#" + digits
+  const lines = entries.slice(0, cap).map(e => {
+    const tag = `#${e.index}`.padStart(width);
+    const mark = opts.current && e.model === opts.current ? chalk.green(" ◀ current") : "";
+    return `  ${chalk.yellow(tag)}  ${e.model} ${chalk.gray(`(${e.provider})`)}${mark}`;
+  });
+  if (entries.length > cap) lines.push(chalk.gray(`  …(+${entries.length - cap} more — narrow with /provider <name> or /search)`));
+  return lines;
+}
+
+function thinkCell(levels: string[]): string {
+  return levels.length ? levels.join(",") : "-";
+}
+
+/** Catalog table grouped by provider: provider · model · ctx · out · thinking · img. */
+export function formatCatalogTable(models: CatalogModel[], opts: { current?: string } = {}): string[] {
+  if (models.length === 0) return ["  (no catalog matches)"];
+  const pw = Math.max(...models.map(m => m.provider.length), 8);
+  const mw = Math.min(Math.max(...models.map(m => m.canonical.length), 6), 30);
+  const lines = [`  ${"provider".padEnd(pw)}  ${"model".padEnd(mw)}  ${"ctx".padStart(5)}  ${"out".padStart(5)}  thinking  img`];
+  for (const m of models) {
+    const mark = opts.current && (m.canonical === opts.current || m.providerModel === opts.current) ? chalk.green(" ◀") : "";
+    lines.push(
+      `  ${chalk.gray(m.provider.padEnd(pw))}  ${m.canonical.padEnd(mw)}  ${formatTokens(m.contextTokens).padStart(5)}  ${formatTokens(m.maxOutputTokens).padStart(5)}  ${chalk.cyan(thinkCell(m.thinking))}  ${m.images ? "yes" : "no"}${mark}`,
+    );
+  }
+  return lines;
+}
+
+/** One-line capability summary for a single model, e.g. for `/model` output. */
+export function formatCapabilityLine(m: CatalogModel): string {
+  return `${chalk.gray("caps:")} ctx ${formatTokens(m.contextTokens)} · out ${formatTokens(m.maxOutputTokens)} · thinking ${thinkCell(m.thinking)} · images ${m.images ? "yes" : "no"}`;
+}
+
+/**
+ * Live + catalog capability table: live (logged-in) models annotated with
+ * context/out/thinking/img when the catalog knows them, "-" otherwise.
+ */
+export function formatEnrichedModels(models: EnrichedModel[], opts: { current?: string; cap?: number } = {}): string[] {
+  if (models.length === 0) return ["  (no live models — log in with 'joc auth login' or start Ollama)"];
+  const cap = opts.cap ?? 50;
+  const shown = models.slice(0, cap);
+  const pw = Math.max(...shown.map(m => m.provider.length), 8);
+  const mw = Math.min(Math.max(...shown.map(m => m.id.length), 6), 36);
+  const lines = [`  ${"provider".padEnd(pw)}  ${"model".padEnd(mw)}  ${"ctx".padStart(5)}  ${"out".padStart(5)}  thinking  img`];
+  for (const m of shown) {
+    const ctx = m.meta ? formatTokens(m.meta.contextTokens) : "-";
+    const out = m.meta ? formatTokens(m.meta.maxOutputTokens) : "-";
+    const think = m.meta ? thinkCell(m.meta.thinking) : "?";
+    const img = m.meta ? (m.meta.images ? "yes" : "no") : "?";
+    const mark = opts.current && m.id === opts.current ? chalk.green(" ◀") : "";
+    const id = m.id.length > mw ? m.id.slice(0, mw - 1) + "…" : m.id.padEnd(mw);
+    lines.push(`  ${chalk.gray(m.provider.padEnd(pw))}  ${id}  ${ctx.padStart(5)}  ${out.padStart(5)}  ${chalk.cyan(think)}  ${img}${mark}`);
+  }
+  if (models.length > cap) lines.push(chalk.gray(`  …(+${models.length - cap} more)`));
+  return lines;
+}

package/src/tui/components/evolution.ts

@@ -0,0 +1,305 @@
+import chalk from "chalk";
+
+/**
+ * Canonical "evolution" model for the joc TUI (single source of truth).
+ *
+ * Every evolving surface — the ASCII art, the spinner, the progress meter, and
+ * the footer track — derives its stage from the functions and tables here, so a
+ * turn evolves in lockstep instead of each component drifting with its own
+ * threshold copy. Five stages map an agent's progress from a primordial cell to
+ * a singularity:
+ *
+ *   0 Primordial Cell → 1 Double Helix → 2 Tool User → 3 AI Coding Agent → 4 Singularity
+ */
+export const EVOLUTION_STAGE_COUNT = 5;
+
+export const EVOLUTION_STAGE_NAMES: readonly string[] = [
+  "Primordial Cell",
+  "Double Helix (DNA)",
+  "Tool User (Homo Habilis)",
+  "AI Coding Agent",
+  "Super intelligence (Singularity)",
+];
+
+/** Per-stage accent color (chalk). Index-aligned with the stage tables. */
+export const EVOLUTION_STAGE_COLORS: readonly ((s: string) => string)[] = [
+  s => chalk.cyan(s),
+  s => chalk.green(s),
+  s => chalk.yellow(s),
+  s => chalk.magenta(s),
+  s => chalk.blue(s),
+];
+
+/** Spinner frame sets, one per evolution stage. */
+export const EVOLUTION_SPINNER_FRAMES: readonly string[][] = [
+  [".", "..", "...", "....", "...", ".."],
+  ["\u2801", "\u2802", "\u2804", "\u2808", "\u2810", "\u2820"],
+  ["|", "/", "-", "\\"],
+  ["\u280b", "\u2819", "\u2839", "\u2838", "\u283c", "\u2834", "\u2826", "\u2827", "\u2807", "\u280f"],
+  ["\u25dc", "\u25dd", "\u25de", "\u25df"],
+];
+
+/**
+ * ASCII-only spinner fallback, one set per stage, for terminals that cannot
+ * render braille/box-drawing (`supportsUnicode === false`). Index-aligned with
+ * `EVOLUTION_SPINNER_FRAMES`.
+ */
+export const EVOLUTION_SPINNER_FRAMES_ASCII: readonly string[][] = [
+  [".", "..", "...", "....", "...", ".."],
+  ["-", "=", "~", "="],
+  ["|", "/", "-", "\\"],
+  ["[.  ]", "[.. ]", "[...]", "[ ..]", "[  .]", "[   ]"],
+  ["+", "x", "*", "x"],
+];
+
+/** Stage spinner frames honoring unicode capability (defaults to unicode). */
+export function spinnerFramesFor(stageIndex: number, unicode = true): string[] {
+  const table = unicode ? EVOLUTION_SPINNER_FRAMES : EVOLUTION_SPINNER_FRAMES_ASCII;
+  return [...table[clampStageIndex(stageIndex)]!];
+}
+
+export interface MeterGlyphs {
+  fill: string;
+  empty: string;
+  color: (s: string) => string;
+}
+
+/** Progress-bar fill/empty glyphs + color, one per evolution stage. */
+export const EVOLUTION_METER_GLYPHS: readonly MeterGlyphs[] = [
+  { fill: "o", empty: ".", color: chalk.cyan },
+  { fill: "x", empty: " ", color: chalk.green },
+  { fill: "=", empty: "-", color: chalk.yellow },
+  { fill: "#", empty: "-", color: chalk.magenta },
+  { fill: "\u2588", empty: "\u2591", color: chalk.blue },
+];
+
+/** ASCII-only meter glyphs (stage 4's block glyphs swapped for `#`/`-`). */
+export const EVOLUTION_METER_GLYPHS_ASCII: readonly MeterGlyphs[] = [
+  { fill: "o", empty: ".", color: chalk.cyan },
+  { fill: "x", empty: " ", color: chalk.green },
+  { fill: "=", empty: "-", color: chalk.yellow },
+  { fill: "#", empty: "-", color: chalk.magenta },
+  { fill: "#", empty: "-", color: chalk.blue },
+];
+
+/** Stage meter glyphs honoring unicode capability (defaults to unicode). */
+export function meterGlyphsFor(stageIndex: number, unicode = true): MeterGlyphs {
+  const table = unicode ? EVOLUTION_METER_GLYPHS : EVOLUTION_METER_GLYPHS_ASCII;
+  return table[clampStageIndex(stageIndex)]!;
+}
+
+/**
+ * Per-stage truecolor gradient palette (`from` → `to` hex), index-aligned with
+ * the stage tables. Drives smooth per-character gradients in the ASCII art when
+ * the terminal supports it; downgrades to 256/16/plain via `src/tui/components/color.ts`.
+ * The palette traces a cosmic arc: cyan tide → green helix → amber tools →
+ * magenta machine → white-hot singularity.
+ */
+export interface StageGradient {
+  from: string;
+  to: string;
+}
+
+export const EVOLUTION_STAGE_GRADIENTS: readonly StageGradient[] = [
+  { from: "#0a3d62", to: "#48dbfb" }, // Primordial Cell — deep tide → bright cyan
+  { from: "#10ac84", to: "#7bed9f" }, // Double Helix — emerald → mint
+  { from: "#ff9f1a", to: "#feca57" }, // Tool User — amber → gold
+  { from: "#8e44ad", to: "#f368e0" }, // AI Coding Agent — violet → magenta
+  { from: "#5352ed", to: "#ffffff" }, // Singularity — indigo → white-hot
+];
+
+/** Gradient palette for a stage index (clamped). */
+export function stageGradient(index: number): StageGradient {
+  return EVOLUTION_STAGE_GRADIENTS[clampStageIndex(index)]!;
+}
+
+/** Clamp any index into the valid stage range [0, COUNT-1]. */
+export function clampStageIndex(index: number): number {
+  if (!Number.isFinite(index)) return 0;
+  return Math.max(0, Math.min(EVOLUTION_STAGE_COUNT - 1, Math.trunc(index)));
+}
+
+/**
+ * Canonical stage for a discrete agent step against a step budget. Step 0 is
+ * always the primordial stage; thereafter progress is split into quartiles.
+ * Guards against non-finite / non-positive `maxSteps`.
+ */
+export function stageIndexForStep(step: number, maxSteps: number): number {
+  if (!Number.isFinite(step) || step <= 0) return 0;
+  if (!Number.isFinite(maxSteps) || maxSteps <= 0) return 0;
+  const ratio = step / maxSteps;
+  if (ratio <= 0.25) return 1;
+  if (ratio <= 0.5) return 2;
+  if (ratio <= 0.75) return 3;
+  return 4;
+}
+
+/**
+ * Canonical stage for a continuous progress ratio in [0,1] (used by the meter,
+ * which measures generic completion rather than agent steps). Five equal-ish
+ * bands; non-finite ratios fall back to stage 0.
+ */
+export function stageIndexForRatio(ratio: number): number {
+  if (!Number.isFinite(ratio)) return 0;
+  const r = Math.max(0, Math.min(1, ratio));
+  if (r <= 0.2) return 0;
+  if (r <= 0.4) return 1;
+  if (r <= 0.6) return 2;
+  if (r <= 0.8) return 3;
+  return 4;
+}
+
+/** Stage name for a discrete step (convenience for footers/summaries). */
+export function evolutionStageName(step: number, maxSteps: number): string {
+  return EVOLUTION_STAGE_NAMES[stageIndexForStep(step, maxSteps)]!;
+}
+
+/**
+ * Render a compact evolution track, e.g. `●●●○○ Tool User (Homo Habilis) [3/5]`.
+ * The active marker is tinted with the stage color; pass `color: false` for
+ * plain (NO_COLOR / non-TTY) output.
+ */
+export function evolutionTrack(
+  activeIndex: number,
+  opts: { color?: boolean; unicode?: boolean; ratio?: number } = {},
+): string {
+  const active = clampStageIndex(activeIndex);
+  const useColor = opts.color !== false;
+  const unicode = opts.unicode !== false;
+  const filled = unicode ? "\u25cf" : "#"; // ● / #
+  const empty = unicode ? "\u25cb" : "-"; // ○ / -
+  const half = unicode ? "\u25d0" : "+"; // ◐ / +  (in-progress next stage)
+  // The next (not-yet-reached) stage shows a half marker while progress within
+  // the current stage is partway (continuous sub-stage feedback).
+  const ratio = opts.ratio;
+  const nextPartial = ratio !== undefined && Number.isFinite(ratio) && ratio > 0 && ratio < 1 ? active + 1 : -1;
+  let markers = "";
+  for (let i = 0; i < EVOLUTION_STAGE_COUNT; i++) {
+    const glyph = i <= active ? filled : i === nextPartial ? half : empty;
+    if (useColor && i === active) {
+      markers += EVOLUTION_STAGE_COLORS[i]!(glyph);
+    } else {
+      markers += glyph;
+    }
+  }
+  return `${markers} ${EVOLUTION_STAGE_NAMES[active]} [${active + 1}/${EVOLUTION_STAGE_COUNT}]`;
+}
+
+/**
+ * Monotonic stage progress: evolution should only move forward within a turn.
+ * `observe(step, maxSteps)` returns the highest stage seen so far, so a transient
+ * step drop (e.g. a retry resetting the counter) never visibly "devolves" the UI.
+ */
+export interface StageProgress {
+  observe(step: number, maxSteps: number): number;
+  current(): number;
+  /** True iff the most recent `observe` increased the peak stage (a transition). */
+  advanced(): boolean;
+  reset(): void;
+}
+
+export function createStageProgress(): StageProgress {
+  let peak = 0;
+  let justAdvanced = false;
+  return {
+    observe(step: number, maxSteps: number): number {
+      const next = Math.max(peak, stageIndexForStep(step, maxSteps));
+      justAdvanced = next > peak;
+      peak = next;
+      return peak;
+    },
+    current() {
+      return peak;
+    },
+    advanced() {
+      return justAdvanced;
+    },
+    reset() {
+      peak = 0;
+      justAdvanced = false;
+    },
+  };
+}
+export const EVOLUTION_STAGE_TIPS: readonly string[] = [
+  "Primordial code is forming. Use /model to switch models if details are lost.",
+  "DNA replication in progress. Use /compact to clean up long context histories.",
+  "Tool use discovered! The agent can run read/write/edit/bash/find/search tools.",
+  "AI reasoning active. You can run workflow skills like deep-interview, ralplan, team, and ultragoal.",
+  "Cosmic singularity reached. Your agent has evolved to maximum intelligence.",
+];
+
+export function getEvolutionTip(step: number, maxSteps: number): string {
+  const idx = stageIndexForStep(step, maxSteps);
+  return EVOLUTION_STAGE_TIPS[idx]!;
+}
+export const EVOLUTION_STAGE_STATUS_MESSAGES: readonly string[][] = [
+  ["Synthesizing primordial logic...", "Forming basic concepts...", "Replicating data structures..."],
+  ["Transcribing instructions...", "Binding code blocks...", "Mapping logic pathways..."],
+  ["Analyzing codebase structure...", "Grasping edit patterns...", "Executing tool commands..."],
+  ["Formulating execution plan...", "Refining syntax trees...", "Resolving type boundaries..."],
+  ["Achieving absolute consensus...", "Optimizing to zero entropy...", "Transcending human limits..."],
+];
+
+export function getEvolutionStatusMessage(step: number, maxSteps: number, tickCount: number): string {
+  const stageIdx = stageIndexForStep(step, maxSteps);
+  const pool = EVOLUTION_STAGE_STATUS_MESSAGES[stageIdx]!;
+  return pool[tickCount % pool.length]!;
+}
+
+/**
+ * Fraction [0,1] of progress *within the current stage's band* — drives smooth
+ * sub-stage animation (e.g. a partially-filled "next stage" marker). Step 0 and
+ * non-positive/non-finite inputs yield 0; beyond budget yields 1.
+ */
+export function stageProgressRatio(step: number, maxSteps: number): number {
+  if (!Number.isFinite(step) || step <= 0) return 0;
+  if (!Number.isFinite(maxSteps) || maxSteps <= 0) return 0;
+  const r = step / maxSteps;
+  if (r <= 0.25) return r / 0.25;
+  if (r <= 0.5) return (r - 0.25) / 0.25;
+  if (r <= 0.75) return (r - 0.5) / 0.25;
+  return Math.min(1, (r - 0.75) / 0.25);
+}
+
+/** Whole-turn completion ratio [0,1] (step against budget). */
+export function overallProgress(step: number, maxSteps: number): number {
+  if (!Number.isFinite(step) || step <= 0) return 0;
+  if (!Number.isFinite(maxSteps) || maxSteps <= 0) return 0;
+  return Math.max(0, Math.min(1, step / maxSteps));
+}
+
+/** Name of the next stage (clamped at the final stage). */
+export function nextStageName(step: number, maxSteps: number): string {
+  return EVOLUTION_STAGE_NAMES[clampStageIndex(stageIndexForStep(step, maxSteps) + 1)]!;
+}
+
+/**
+ * Whole steps remaining until the stage index increases. Returns 0 at the final
+ * stage. Bounded loop so a pathological `maxSteps` cannot spin forever.
+ */
+export function stepsToNextStage(step: number, maxSteps: number): number {
+  const cur = stageIndexForStep(step, maxSteps);
+  if (cur >= EVOLUTION_STAGE_COUNT - 1) return 0;
+  let s = Math.max(0, Math.trunc(Number.isFinite(step) ? step : 0));
+  let n = 0;
+  const cap = Number.isFinite(maxSteps) && maxSteps > 0 ? maxSteps * 2 + 10 : 10;
+  while (stageIndexForStep(s, maxSteps) <= cur && n < cap) {
+    s++;
+    n++;
+  }
+  return n;
+}
+
+/** Per-stage transition message, shown when the agent first enters a stage. */
+export const EVOLUTION_TRANSITION_MESSAGES: readonly string[] = [
+  "Spark of life — a primordial cell stirs.",
+  "Strands align — the double helix forms.",
+  "Tools in hand — the agent learns to build.",
+  "Cognition online — the AI coding agent awakens.",
+  "Singularity — intelligence transcends its bounds.",
+];
+
+/** Transition message for a stage index (clamped). */
+export function transitionMessage(index: number): string {
+  return EVOLUTION_TRANSITION_MESSAGES[clampStageIndex(index)]!;
+}