ax-agents 0.1.3 → 0.1.5

package/ax.js

@@ -9,6 +9,7 @@
 //   2 - rate limited
 //   3 - awaiting confirmation
 //   4 - thinking
+//   5 - iteration complete, more work to do (ax do)
 
 import { execSync, spawnSync, spawn } from "node:child_process";
 import {
@@ -31,7 +32,7 @@ import { randomUUID, createHash } from "node:crypto";
 import { fileURLToPath } from "node:url";
 import path from "node:path";
 import os from "node:os";
-import { parseArgs } from "node:util";
+import { parseArgs, styleText } from "node:util";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -134,14 +135,102 @@ const VERSION = packageJson.version;
  * @property {{UserPromptSubmit?: ClaudeHookEntry[], PreToolUse?: ClaudeHookEntry[], Stop?: ClaudeHookEntry[], [key: string]: ClaudeHookEntry[] | undefined}} [hooks]
  */
 
+// =============================================================================
+// Terminal Stream Types - Abstraction layer for terminal I/O
+// =============================================================================
+
+/**
+ * Style properties for terminal text (ANSI colors, formatting)
+ * @typedef {Object} TerminalStyle
+ * @property {string} [fg] - Foreground color (e.g., "red", "green", "#ff0000")
+ * @property {string} [bg] - Background color
+ * @property {boolean} [bold] - Bold text
+ * @property {boolean} [dim] - Dimmed text
+ * @property {boolean} [italic] - Italic text
+ * @property {boolean} [underline] - Underlined text
+ */
+
+/**
+ * A span of text with optional styling
+ * @typedef {Object} TextSpan
+ * @property {string} text - The text content
+ * @property {TerminalStyle} [style] - Optional style properties
+ */
+
+/**
+ * A line of terminal output, containing styled spans and raw text
+ * @typedef {Object} TerminalLine
+ * @property {TextSpan[]} spans - Styled text spans
+ * @property {string} raw - Raw text content (spans joined, styles stripped)
+ * @property {'text' | 'thinking' | 'tool'} [lineType] - Content type for styling
+ */
+
+/**
+ * A segment of log output with type information
+ * @typedef {Object} LogSegment
+ * @property {'text' | 'thinking' | 'tool'} type - Content type
+ * @property {string} content - The text content
+ */
+
+/**
+ * Query for matching terminal lines
+ * @typedef {Object} MatchQuery
+ * @property {string | RegExp} pattern - Pattern to match against raw line text
+ * @property {Partial<TerminalStyle>} [style] - Optional style filter (ignored if implementation doesn't support styles)
+ */
+
+/**
+ * Result of a pattern match operation
+ * @typedef {Object} MatchResult
+ * @property {boolean} matched - Whether a match was found
+ * @property {TerminalLine} [line] - The matched line (if matched)
+ * @property {number} [lineIndex] - Index of the matched line (if matched)
+ */
+
+/**
+ * Options for reading from a terminal stream
+ * @typedef {Object} ReadOptions
+ * @property {number} [max] - Maximum number of lines to return
+ * @property {number} [timeoutMs] - Timeout in milliseconds
+ */
+
+/**
+ * Options for waiting for a match
+ * @typedef {Object} WaitOptions
+ * @property {number} [timeoutMs] - Timeout in milliseconds
+ */
+
+/**
+ * Interface for reading terminal output.
+ * Implementations: JsonlTerminalStream (Claude logs), ScreenTerminalStream (tmux capture)
+ * @typedef {Object} TerminalStream
+ * @property {(opts?: ReadOptions) => Promise<TerminalLine[]>} readNext - Read new lines since last read
+ * @property {(query: MatchQuery, opts?: WaitOptions) => Promise<MatchResult>} waitForMatch - Wait for a line matching the query
+ */
+
 const DEBUG = process.env.AX_DEBUG === "1";
 
+// ANSI colour codes for debug output
+const COLORS = {
+  reset: "\x1b[0m",
+  bright: "\x1b[1m",
+  cyan: "\x1b[96m", // Bright cyan
+  magenta: "\x1b[95m", // Bright magenta
+  yellow: "\x1b[93m", // Bright yellow
+  red: "\x1b[91m", // Bright red
+};
+
 /**
  * @param {string} context
  * @param {unknown} err
  */
 function debugError(context, err) {
-  if (DEBUG) console.error(`[debug:${context}]`, err instanceof Error ? err.message : err);
+  if (DEBUG) {
+    const msg = err instanceof Error ? err.message : err;
+    console.error(
+      `${COLORS.bright}${COLORS.red}[error:${context}]${COLORS.reset} ${COLORS.magenta}${msg}${COLORS.reset}`,
+    );
+  }
 }
 
 /**
@@ -150,7 +239,11 @@ function debugError(context, err) {
  * @param {string} message - The debug message
  */
 function debug(tag, message) {
-  if (DEBUG) console.error(`[${tag}] ${message}`);
+  if (DEBUG) {
+    console.error(
+      `${COLORS.bright}${COLORS.cyan}[${tag}]${COLORS.reset} ${COLORS.yellow}${message}${COLORS.reset}`,
+    );
+  }
 }
 
 // =============================================================================
@@ -174,6 +267,46 @@ const AI_DIR = path.join(PROJECT_ROOT, ".ai");
 const AGENTS_DIR = path.join(AI_DIR, "agents");
 const HOOKS_DIR = path.join(AI_DIR, "hooks");
 const RFP_DIR = path.join(AI_DIR, "rfps");
+const DO_DIR = path.join(AI_DIR, "do");
+
+/**
+ * Get path to progress file for a named do task
+ * @param {string} name - Task name (default: "default")
+ * @returns {string}
+ */
+function getDoProgressPath(name = "default") {
+  const dir = path.join(DO_DIR, name);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  const filePath = path.join(dir, "progress.txt");
+  // Touch the file if it doesn't exist so agent can read it on first iteration
+  if (!existsSync(filePath)) writeFileSync(filePath, "");
+  return filePath;
+}
+
+/**
+ * Build prompt for do loop with preamble and progress context
+ * @param {string} userPrompt
+ * @param {string} name
+ * @returns {string}
+ */
+function buildDoPrompt(userPrompt, name) {
+  const progressPath = getDoProgressPath(name);
+  const progress = existsSync(progressPath) ? readFileSync(progressPath, "utf-8") : "";
+
+  const relProgressPath = `.ai/do/${name}/progress.txt`;
+  const preamble = DO_PREAMBLE.replace(/\{progressPath\}/g, relProgressPath);
+
+  return `${preamble}
+
+## Progress So Far
+${progress || "(No progress yet)"}
+
+## Your Task
+${userPrompt}
+
+Remember: Work on ONE thing, update ${relProgressPath}, run tests, commit.
+When ALL tasks are complete, output <promise>COMPLETE</promise>`;
+}
 
 // =============================================================================
 // Helpers - tmux
@@ -205,11 +338,13 @@ function tmuxHasSession(session) {
 /**
  * @param {string} session
  * @param {number} [scrollback]
+ * @param {boolean} [withEscapes] - Include ANSI escape sequences (uses -e flag)
  * @returns {string}
  */
-function tmuxCapture(session, scrollback = 0) {
+function tmuxCapture(session, scrollback = 0, withEscapes = false) {
   try {
     const args = ["capture-pane", "-t", session, "-p"];
+    if (withEscapes) args.push("-e"); // Include escape sequences
     if (scrollback) args.push("-S", String(-scrollback));
     return tmux(args);
   } catch (err) {
@@ -236,6 +371,64 @@ function tmuxSendLiteral(session, text) {
   tmux(["send-keys", "-t", session, "-l", text]);
 }
 
+/**
+ * Paste text into a tmux session using load-buffer + paste-buffer.
+ * More reliable than send-keys -l for large text.
+ * Uses a named buffer to avoid races with concurrent invocations.
+ * @param {string} session
+ * @param {string} text
+ */
+function tmuxPasteLiteral(session, text) {
+  debug("tmux", `pasteLiteral session=${session}, text=${text.slice(0, 50)}...`);
+  // Use unique buffer name per invocation to avoid races (even to same session)
+  const bufferName = `ax-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+  // Load text into named tmux buffer from stdin
+  const loadResult = spawnSync("tmux", ["load-buffer", "-b", bufferName, "-"], {
+    input: text,
+    encoding: "utf-8",
+  });
+  if (loadResult.status !== 0) {
+    debug("tmux", `load-buffer failed: ${loadResult.stderr}`);
+    throw new Error(loadResult.stderr || "tmux load-buffer failed");
+  }
+  try {
+    // Paste buffer into the session
+    tmux(["paste-buffer", "-b", bufferName, "-t", session]);
+    // Move cursor to end of pasted text
+    tmux(["send-keys", "-t", session, "End"]);
+  } finally {
+    // Clean up the named buffer
+    try {
+      tmux(["delete-buffer", "-b", bufferName]);
+    } catch (err) {
+      debugError("tmuxPasteLiteral", err);
+    }
+  }
+}
+
+/**
+ * Paste text and send Enter, waiting for multiline paste indicator if needed.
+ * Claude Code shows "[Pasted text #N +M lines]" for multiline input and needs
+ * time to process it before accepting Enter.
+ * @param {string} session
+ * @param {string} text
+ */
+async function tmuxSendText(session, text) {
+  const parsed = parseSessionName(session);
+  const isClaude = parsed?.tool === "claude";
+  const newlineCount = (text.match(/\n/g) || []).length;
+
+  tmuxPasteLiteral(session, text);
+
+  // For multiline text in Claude, use adaptive delay based on paste size
+  if (isClaude && newlineCount > 0) {
+    const delay = Math.min(1500, 50 + 3 * text.length + 20 * newlineCount);
+    debug("sendText", `multiline paste (${text.length} chars, ${newlineCount} lines), waiting ${delay}ms`);
+    await sleep(delay);
+  }
+  tmuxSend(session, "Enter");
+}
+
 /**
  * @param {string} session
  */
@@ -247,6 +440,23 @@ function tmuxKill(session) {
   }
 }
 
+/**
+ * Rename a tmux session.
+ * @param {string} oldName
+ * @param {string} newName
+ * @returns {boolean}
+ */
+function tmuxRenameSession(oldName, newName) {
+  try {
+    tmux(["rename-session", "-t", oldName, newName]);
+    debug("tmux", `renamed session: ${oldName} -> ${newName}`);
+    return true;
+  } catch (err) {
+    debugError("tmuxRenameSession", err);
+    return false;
+  }
+}
+
 /**
  * @param {string} session
  * @param {string} command
@@ -396,6 +606,24 @@ const RFP_PREAMBLE = `## Guidelines
 - Prioritize clarity over brevity.
 - If you have nothing to propose, respond with ONLY "EMPTY_RESPONSE".`;
 
+// Note: DO_PREAMBLE is a template - {progressPath} gets replaced at runtime
+const DO_PREAMBLE = `You are an autonomous coding agent in a loop. Each iteration:
+
+1. Read {progressPath} to see what's done
+2. Choose the highest priority remaining task
+3. Implement ONE small feature/fix
+4. Run feedback loops (tests, types, lint)
+5. Commit your changes with a clear message
+6. Append to {progressPath} what you did
+7. If ALL tasks are complete, output: <promise>COMPLETE</promise>
+
+Guidelines:
+- Work on ONE task per iteration, keep changes small
+- Always run tests before committing - do NOT commit if tests fail
+- Update {progressPath} BEFORE outputting COMPLETE
+- Prioritize risky/architectural work first
+- If stuck, document the blocker in {progressPath}`;
+
 /**
  * @param {string} session
  * @param {(screen: string) => boolean} predicate
@@ -559,6 +787,10 @@ async function readStdinIfNeeded(value) {
  * @property {string} [branch]
  * @property {string} [archangels]
  * @property {string} [autoApprove]
+ * @property {string} [name]
+ * @property {number} [maxLoops]
+ * @property {boolean} loop
+ * @property {boolean} reset
  */
 function parseCliArgs(args) {
   const { values, positionals } = parseArgs({
@@ -577,6 +809,8 @@ function parseCliArgs(args) {
       stale: { type: "boolean", default: false },
       version: { type: "boolean", short: "V", default: false },
       help: { type: "boolean", short: "h", default: false },
+      loop: { type: "boolean", default: false },
+      reset: { type: "boolean", default: false },
       // Value flags
       tool: { type: "string" },
       "auto-approve": { type: "string" },
@@ -586,6 +820,8 @@ function parseCliArgs(args) {
       limit: { type: "string" },
       branch: { type: "string" },
       archangels: { type: "string" },
+      name: { type: "string" },
+      "max-loops": { type: "string" },
     },
     allowPositionals: true,
     strict: false, // Don't error on unknown flags
@@ -613,6 +849,10 @@ function parseCliArgs(args) {
       branch: /** @type {string | undefined} */ (values.branch),
       archangels: /** @type {string | undefined} */ (values.archangels),
       autoApprove: /** @type {string | undefined} */ (values["auto-approve"]),
+      name: /** @type {string | undefined} */ (values.name),
+      maxLoops: values["max-loops"] !== undefined ? Number(values["max-loops"]) : undefined,
+      loop: Boolean(values.loop),
+      reset: Boolean(values.reset),
     },
     positionals,
   };
@@ -681,6 +921,31 @@ function generateSessionName(tool, { allowedTools = null, yolo = false } = {}) {
   return `${tool}-partner-${uuid}`;
 }
 
+/**
+ * Rebuild a session name with a new UUID, preserving other attributes.
+ * @param {string} sessionName - existing session name
+ * @param {string} newUuid - new UUID to use
+ * @returns {string | null}
+ */
+function rebuildSessionName(sessionName, newUuid) {
+  const parsed = parseSessionName(sessionName);
+  if (!parsed || !parsed.uuid) return null;
+
+  // Archangel sessions: {tool}-archangel-{name}-{uuid}
+  if (parsed.archangelName) {
+    return `${parsed.tool}-archangel-${parsed.archangelName}-${newUuid}`;
+  }
+
+  // Partner sessions: {tool}-partner-{uuid}[-p{hash}|-yolo]
+  let name = `${parsed.tool}-partner-${newUuid}`;
+  if (parsed.yolo) {
+    name += "-yolo";
+  } else if (parsed.permissionHash) {
+    name += `-p${parsed.permissionHash}`;
+  }
+  return name;
+}
+
 /**
  * Quick hash for change detection (not cryptographic).
  * @param {string | null | undefined} str
@@ -761,6 +1026,42 @@ function findClaudeLogPath(sessionId, sessionName) {
   return null;
 }
 
+/**
+ * Find the most recently created Claude session UUID for a project.
+ * @param {string} sessionName - tmux session name (used to get cwd)
+ * @returns {string | null}
+ */
+function findNewestClaudeSessionUuid(sessionName) {
+  const cwd = getTmuxSessionCwd(sessionName) || process.cwd();
+  const projectPath = getClaudeProjectPath(cwd);
+  const claudeProjectDir = path.join(CLAUDE_CONFIG_DIR, "projects", projectPath);
+  const indexPath = path.join(claudeProjectDir, "sessions-index.json");
+
+  if (!existsSync(indexPath)) {
+    debug("log", `findNewestClaudeSessionUuid: no index at ${indexPath}`);
+    return null;
+  }
+
+  try {
+    const index = JSON.parse(readFileSync(indexPath, "utf-8"));
+    if (!index.entries?.length) return null;
+
+    // Sort by created timestamp (most recent first)
+    const sorted = [...index.entries].sort((a, b) => {
+      const aTime = a.created ? new Date(a.created).getTime() : 0;
+      const bTime = b.created ? new Date(b.created).getTime() : 0;
+      return bTime - aTime;
+    });
+
+    const newest = sorted[0];
+    debug("log", `findNewestClaudeSessionUuid: newest=${newest.sessionId}`);
+    return newest.sessionId;
+  } catch (err) {
+    debugError("findNewestClaudeSessionUuid", err);
+    return null;
+  }
+}
+
 /**
  * @param {string} sessionName
  * @returns {string | null}
@@ -837,7 +1138,10 @@ function findCodexLogPath(sessionName) {
     }
     // Return the closest match
     candidates.sort((a, b) => a.diff - b.diff);
-    debug("log", `findCodexLogPath: found ${candidates.length} candidates, best: ${candidates[0].path}`);
+    debug(
+      "log",
+      `findCodexLogPath: found ${candidates.length} candidates, best: ${candidates[0].path}`,
+    );
     return candidates[0].path;
   } catch {
     debug("log", `findCodexLogPath: exception caught`);
@@ -1026,9 +1330,14 @@ function tailJsonl(logPath, fromOffset) {
 /**
  * Format a Claude Code JSONL log entry for streaming display.
  * Claude format: {type: "assistant", message: {content: [...]}}
- * @param {{type?: string, message?: {content?: Array<{type?: string, text?: string, name?: string, input?: ToolInput, tool?: string, arguments?: ToolInput}>}}} entry
+ * @param {{type?: string, message?: {content?: Array<{type?: string, text?: string, thinking?: string, name?: string, input?: ToolInput, tool?: string, arguments?: ToolInput}>}}} entry
  * @returns {string | null}
  */
+/**
+ * Format a Claude JSONL log entry for streaming display.
+ * @param {{type?: string, message?: {content?: Array<{type?: string, text?: string, thinking?: string, name?: string, tool?: string, input?: {command?: string, file_path?: string, path?: string, pattern?: string, description?: string, subagent_type?: string}, arguments?: {command?: string, file_path?: string, path?: string, pattern?: string, description?: string, subagent_type?: string}}>}}} entry
+ * @returns {LogSegment[] | null}
+ */
 function formatClaudeLogEntry(entry) {
   // Skip tool_result entries (they can be very verbose)
   if (entry.type === "tool_result") return null;
@@ -1037,29 +1346,34 @@ function formatClaudeLogEntry(entry) {
   if (entry.type !== "assistant") return null;
 
   const parts = entry.message?.content || [];
+  /** @type {LogSegment[]} */
   const output = [];
 
   for (const part of parts) {
     if (part.type === "text" && part.text) {
-      output.push(part.text);
+      output.push({ type: "text", content: part.text });
     } else if (part.type === "thinking" && part.thinking) {
       // Include thinking blocks - extended thinking models put responses here
-      output.push(part.thinking);
+      output.push({ type: "thinking", content: part.thinking });
     } else if (part.type === "tool_use" || part.type === "tool_call") {
       const name = part.name || part.tool || "tool";
       const input = part.input || part.arguments || {};
       let summary;
       if (name === "Bash" && input.command) {
         summary = input.command.slice(0, 50);
+      } else if (name === "Task" && (input.description || input.subagent_type)) {
+        // Task tool: show description or subagent type
+        summary = input.description || input.subagent_type || "";
+        summary = summary.slice(0, 40);
       } else {
         const target = input.file_path || input.path || input.pattern || "";
         summary = target.split("/").pop() || target.slice(0, 30);
       }
-      output.push(`> ${name}(${summary})`);
+      output.push({ type: "tool", content: `> ${name}(${summary})` });
     }
   }
 
-  return output.length > 0 ? output.join("\n") : null;
+  return output.length > 0 ? output : null;
 }
 
 /**
@@ -1068,8 +1382,9 @@ function formatClaudeLogEntry(entry) {
  * - {type: "response_item", payload: {type: "message", role: "assistant", content: [{type: "output_text", text: "..."}]}}
  * - {type: "response_item", payload: {type: "function_call", name: "...", arguments: "{...}"}}
  * - {type: "event_msg", payload: {type: "agent_message", message: "..."}}
- * @param {{type?: string, payload?: {type?: string, role?: string, name?: string, arguments?: string, message?: string, content?: Array<{type?: string, text?: string}>}}} entry
- * @returns {string | null}
+ * - {type: "event_msg", payload: {type: "agent_reasoning", text: "..."}}
+ * @param {{type?: string, payload?: {type?: string, role?: string, name?: string, arguments?: string, message?: string, text?: string, content?: Array<{type?: string, text?: string}>}}} entry
+ * @returns {LogSegment[] | null}
  */
 function formatCodexLogEntry(entry) {
   // Skip function_call_output entries (equivalent to tool_result - can be verbose)
@@ -1085,6 +1400,10 @@ function formatCodexLogEntry(entry) {
       const args = JSON.parse(entry.payload.arguments || "{}");
       if (name === "shell_command" && args.command) {
         summary = args.command.slice(0, 50);
+      } else if (name === "Task" && (args.description || args.subagent_type)) {
+        // Task tool: show description or subagent type
+        summary = args.description || args.subagent_type || "";
+        summary = summary.slice(0, 40);
       } else {
         const target = args.file_path || args.path || args.pattern || "";
         summary = target.split("/").pop() || target.slice(0, 30);
@@ -1092,34 +1411,640 @@ function formatCodexLogEntry(entry) {
     } catch {
       summary = "...";
     }
-    return `> ${name}(${summary})`;
+    return [{ type: "tool", content: `> ${name}(${summary})` }];
   }
 
   // Handle assistant messages (final response)
   if (entry.type === "response_item" && entry.payload?.role === "assistant") {
     const parts = entry.payload.content || [];
+    /** @type {LogSegment[]} */
     const output = [];
     for (const part of parts) {
       if ((part.type === "output_text" || part.type === "text") && part.text) {
-        output.push(part.text);
+        output.push({ type: "text", content: part.text });
       }
     }
-    return output.length > 0 ? output.join("\n") : null;
+    return output.length > 0 ? output : null;
   }
 
   // Handle streaming agent messages
   if (entry.type === "event_msg" && entry.payload?.type === "agent_message") {
-    return entry.payload.message || null;
+    const message = entry.payload.message;
+    return message ? [{ type: "text", content: message }] : null;
   }
 
   // Handle agent reasoning (thinking during review)
   if (entry.type === "event_msg" && entry.payload?.type === "agent_reasoning") {
-    return entry.payload.text || null;
+    const text = entry.payload.text;
+    return text ? [{ type: "thinking", content: text }] : null;
   }
 
   return null;
 }
 
+// =============================================================================
+// Terminal Stream Primitives - Pure functions for parsing terminal data
+// =============================================================================
+
+/**
+ * Parse a JSONL log entry into TerminalLine[].
+ * Wraps formatClaudeLogEntry/formatCodexLogEntry to return structured data.
+ * @param {object} entry - A parsed JSONL entry
+ * @param {'claude' | 'codex'} format - The log format
+ * @returns {TerminalLine[]}
+ */
+function parseJsonlEntry(entry, format) {
+  const segments = format === "claude" ? formatClaudeLogEntry(entry) : formatCodexLogEntry(entry);
+  if (!segments) return [];
+
+  // Convert segments to TerminalLines, splitting multiline content
+  /** @type {TerminalLine[]} */
+  const lines = [];
+  for (const segment of segments) {
+    const contentLines = segment.content.split("\n");
+    for (const line of contentLines) {
+      lines.push({
+        spans: [{ text: line }],
+        raw: line,
+        lineType: segment.type,
+      });
+    }
+  }
+  return lines;
+}
+
+/**
+ * Parse raw screen output into TerminalLine[].
+ * Each line becomes a TerminalLine with a single unstyled span.
+ * @param {string} screen - Raw screen content from tmux capture
+ * @returns {TerminalLine[]}
+ */
+function parseScreenLines(screen) {
+  if (!screen) return [];
+  return screen.split("\n").map((line) => ({
+    spans: [{ text: line }],
+    raw: line,
+  }));
+}
+
+/**
+ * ANSI color code to color name mapping.
+ * @type {Record<string, string>}
+ */
+const ANSI_COLORS = {
+  30: "black",
+  31: "red",
+  32: "green",
+  33: "yellow",
+  34: "blue",
+  35: "magenta",
+  36: "cyan",
+  37: "white",
+  90: "bright-black",
+  91: "bright-red",
+  92: "bright-green",
+  93: "bright-yellow",
+  94: "bright-blue",
+  95: "bright-magenta",
+  96: "bright-cyan",
+  97: "bright-white",
+};
+
+/**
+ * ANSI background color code to color name mapping.
+ * @type {Record<string, string>}
+ */
+const ANSI_BG_COLORS = {
+  40: "black",
+  41: "red",
+  42: "green",
+  43: "yellow",
+  44: "blue",
+  45: "magenta",
+  46: "cyan",
+  47: "white",
+  100: "bright-black",
+  101: "bright-red",
+  102: "bright-green",
+  103: "bright-yellow",
+  104: "bright-blue",
+  105: "bright-magenta",
+  106: "bright-cyan",
+  107: "bright-white",
+};
+
+/**
+ * Parse ANSI escape sequences from a line of text into styled spans.
+ * @param {string} line - Line containing ANSI escape sequences
+ * @returns {TextSpan[]}
+ */
+function parseAnsiLine(line) {
+  if (!line) return [{ text: "" }];
+
+  const spans = [];
+  /** @type {TerminalStyle} */
+  let currentStyle = {};
+  let currentText = "";
+
+  // ANSI escape sequence pattern: ESC [ <params> m
+  // Matches sequences like \x1b[31m (red), \x1b[1;31m (bold red), \x1b[0m (reset)
+  // eslint-disable-next-line no-control-regex
+  const ansiPattern = /\x1b\[([0-9;]*)m/g;
+  let lastIndex = 0;
+  let match;
+
+  while ((match = ansiPattern.exec(line)) !== null) {
+    // Add text before this escape sequence
+    const textBefore = line.slice(lastIndex, match.index);
+    if (textBefore) {
+      currentText += textBefore;
+    }
+
+    // Flush current span if we have text
+    if (currentText) {
+      /** @type {TextSpan} */
+      const span = { text: currentText };
+      if (Object.keys(currentStyle).length > 0) {
+        span.style = { ...currentStyle };
+      }
+      spans.push(span);
+      currentText = "";
+    }
+
+    // Parse SGR (Select Graphic Rendition) parameters
+    // Note: \x1b[m (empty params) is equivalent to \x1b[0m (reset)
+    const params = match[1].split(";").filter(Boolean);
+    if (params.length === 0) {
+      // Empty params means reset (e.g., \x1b[m)
+      currentStyle = {};
+    }
+    for (const param of params) {
+      const code = param;
+      if (code === "0") {
+        // Reset
+        currentStyle = {};
+      } else if (code === "1") {
+        currentStyle.bold = true;
+      } else if (code === "2") {
+        currentStyle.dim = true;
+      } else if (code === "3") {
+        currentStyle.italic = true;
+      } else if (code === "4") {
+        currentStyle.underline = true;
+      } else if (code === "22") {
+        // Normal intensity (neither bold nor dim)
+        delete currentStyle.bold;
+        delete currentStyle.dim;
+      } else if (code === "23") {
+        delete currentStyle.italic;
+      } else if (code === "24") {
+        delete currentStyle.underline;
+      } else if (ANSI_COLORS[code]) {
+        currentStyle.fg = ANSI_COLORS[code];
+      } else if (ANSI_BG_COLORS[code]) {
+        currentStyle.bg = ANSI_BG_COLORS[code];
+      } else if (code === "39") {
+        // Default foreground
+        delete currentStyle.fg;
+      } else if (code === "49") {
+        // Default background
+        delete currentStyle.bg;
+      }
+    }
+
+    lastIndex = ansiPattern.lastIndex;
+  }
+
+  // Add remaining text
+  const remaining = line.slice(lastIndex);
+  if (remaining) {
+    currentText += remaining;
+  }
+
+  // Flush final span
+  if (currentText || spans.length === 0) {
+    /** @type {TextSpan} */
+    const span = { text: currentText };
+    if (Object.keys(currentStyle).length > 0) {
+      span.style = { ...currentStyle };
+    }
+    spans.push(span);
+  }
+
+  return spans;
+}
+
+/**
+ * Parse raw screen output with ANSI codes into styled TerminalLine[].
+ * @param {string} screen - Screen content with ANSI escape codes
+ * @returns {TerminalLine[]}
+ */
+function parseStyledScreenLines(screen) {
+  if (!screen) return [];
+  return screen.split("\n").map((line) => {
+    const spans = parseAnsiLine(line);
+    // Raw text is spans joined without styles
+    const raw = spans.map((s) => s.text).join("");
+    return { spans, raw };
+  });
+}
+
+/**
+ * Find a line matching the given query.
+ * Style filters are ignored when lines don't have style information.
+ * @param {TerminalLine[]} lines - Lines to search
+ * @param {MatchQuery} query - Query with pattern and optional style filter
+ * @returns {MatchResult}
+ */
+function findMatch(lines, query) {
+  const { pattern, style } = query;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const text = line.raw;
+
+    // Check pattern match
+    const patternMatches =
+      typeof pattern === "string" ? text.includes(pattern) : pattern.test(text);
+
+    if (!patternMatches) continue;
+
+    // If no style filter requested, we have a match
+    if (!style) {
+      return { matched: true, line, lineIndex: i };
+    }
+
+    // Check style match (if line has styled spans)
+    // Style filter is silently ignored if implementation doesn't provide styles
+    const hasStyledSpans = line.spans.some((span) => span.style);
+    if (!hasStyledSpans) {
+      // No style info available - pattern match is enough
+      return { matched: true, line, lineIndex: i };
+    }
+
+    // Check if any span matches both pattern and style
+    const styleMatches = line.spans.some((span) => {
+      if (!span.style) return false;
+      const spanMatchesPattern =
+        typeof pattern === "string" ? span.text.includes(pattern) : pattern.test(span.text);
+      if (!spanMatchesPattern) return false;
+
+      // Check each requested style property
+      const spanStyle = /** @type {Record<string, unknown>} */ (span.style);
+      for (const [key, value] of Object.entries(style)) {
+        if (spanStyle[key] !== value) return false;
+      }
+      return true;
+    });
+
+    if (styleMatches) {
+      return { matched: true, line, lineIndex: i };
+    }
+  }
+
+  return { matched: false };
+}
+
+// =============================================================================
+// Terminal Stream Implementations
+// =============================================================================
+
+/**
+ * Terminal stream that reads from JSONL log files (Claude/Codex logs).
+ * Implements TerminalStream interface.
+ * @implements {TerminalStream}
+ */
+class JsonlTerminalStream {
+  /** @type {() => string | null} */
+  logPathFinder;
+  /** @type {'claude' | 'codex'} */
+  format;
+  /** @type {string | null} */
+  logPath;
+  /** @type {number} */
+  offset;
+  /** @type {boolean} */
+  skipExisting;
+  /** @type {boolean} */
+  initialized;
+
+  /**
+   * @param {() => string | null} logPathFinder - Function that returns current log path (may change during session)
+   * @param {'claude' | 'codex'} format - Log format for parsing entries
+   * @param {{skipExisting?: boolean}} [opts] - Options
+   */
+  constructor(logPathFinder, format, opts = {}) {
+    this.logPathFinder = logPathFinder;
+    this.format = format;
+    this.logPath = null;
+    this.offset = 0;
+    this.skipExisting = opts.skipExisting ?? false;
+    this.initialized = false;
+  }
+
+  /**
+   * Read new lines since last read.
+   * @param {ReadOptions} [opts]
+   * @returns {Promise<TerminalLine[]>}
+   */
+  async readNext(opts = {}) {
+    // Check for new/changed log path
+    const currentLogPath = this.logPathFinder();
+    if (currentLogPath && currentLogPath !== this.logPath) {
+      this.logPath = currentLogPath;
+      if (existsSync(this.logPath)) {
+        if (this.skipExisting && !this.initialized) {
+          // Skip to end of file - only read new content
+          this.offset = statSync(this.logPath).size;
+          this.initialized = true;
+        } else {
+          // Read from beginning
+          this.offset = 0;
+        }
+      }
+    }
+
+    if (!this.logPath) {
+      return [];
+    }
+
+    const { entries, newOffset } = tailJsonl(this.logPath, this.offset);
+    this.offset = newOffset;
+
+    const lines = [];
+    for (const entry of entries) {
+      const entryLines = parseJsonlEntry(entry, this.format);
+      lines.push(...entryLines);
+    }
+
+    if (opts.max && lines.length > opts.max) {
+      return lines.slice(0, opts.max);
+    }
+
+    return lines;
+  }
+
+  /**
+   * Wait for a line matching the query.
+   * @param {MatchQuery} query
+   * @param {WaitOptions} [opts]
+   * @returns {Promise<MatchResult>}
+   */
+  async waitForMatch(query, opts = {}) {
+    const timeoutMs = opts.timeoutMs || 30000;
+    const pollInterval = 100;
+    const deadline = Date.now() + timeoutMs;
+
+    while (Date.now() < deadline) {
+      const lines = await this.readNext();
+      if (lines.length > 0) {
+        const result = findMatch(lines, query);
+        if (result.matched) {
+          return result;
+        }
+      }
+      await sleep(pollInterval);
+    }
+
+    return { matched: false };
+  }
+}
+
+/**
+ * Terminal stream that reads from tmux screen capture.
+ * Implements TerminalStream interface.
+ * @implements {TerminalStream}
+ */
+class ScreenTerminalStream {
+  /**
+   * @param {string} session - tmux session name
+   * @param {number} [scrollback] - Number of scrollback lines to capture
+   */
+  constructor(session, scrollback = 0) {
+    this.session = session;
+    this.scrollback = scrollback;
+    this.lastScreen = "";
+  }
+
+  /**
+   * Read current screen lines (returns all visible lines on each call).
+   * Note: Unlike JsonlTerminalStream, this returns the full screen each time.
+   * @param {ReadOptions} [opts]
+   * @returns {Promise<TerminalLine[]>}
+   */
+  async readNext(opts = {}) {
+    const screen = tmuxCapture(this.session, this.scrollback);
+    this.lastScreen = screen;
+
+    const lines = parseScreenLines(screen);
+
+    if (opts.max && lines.length > opts.max) {
+      return lines.slice(-opts.max); // Return last N lines for screen capture
+    }
+
+    return lines;
+  }
+
+  /**
+   * Wait for a line matching the query.
+   * @param {MatchQuery} query
+   * @param {WaitOptions} [opts]
+   * @returns {Promise<MatchResult>}
+   */
+  async waitForMatch(query, opts = {}) {
+    const timeoutMs = opts.timeoutMs || 30000;
+    const pollInterval = 100;
+    const deadline = Date.now() + timeoutMs;
+
+    while (Date.now() < deadline) {
+      const lines = await this.readNext();
+      const result = findMatch(lines, query);
+      if (result.matched) {
+        return result;
+      }
+      await sleep(pollInterval);
+    }
+
+    return { matched: false };
+  }
+
+  /**
+   * Get the last captured screen (raw string).
+   * Useful for compatibility with existing code that needs raw screen.
+   * @returns {string}
+   */
+  getLastScreen() {
+    return this.lastScreen;
+  }
+}
+
+/**
+ * Terminal stream that reads from tmux screen capture with ANSI styling.
+ * Uses `tmux capture-pane -e` to capture escape sequences.
+ * Implements TerminalStream interface.
+ * @implements {TerminalStream}
+ */
+class StyledScreenTerminalStream {
+  /**
+   * @param {string} session - tmux session name
+   * @param {number} [scrollback] - Number of scrollback lines to capture
+   */
+  constructor(session, scrollback = 0) {
+    this.session = session;
+    this.scrollback = scrollback;
+    this.lastScreen = "";
+  }
+
+  /**
+   * Read current screen lines with ANSI styling parsed.
+   * @param {ReadOptions} [opts]
+   * @returns {Promise<TerminalLine[]>}
+   */
+  async readNext(opts = {}) {
+    const screen = tmuxCapture(this.session, this.scrollback, true); // withEscapes=true
+    this.lastScreen = screen;
+
+    const lines = parseStyledScreenLines(screen);
+
+    if (opts.max && lines.length > opts.max) {
+      return lines.slice(-opts.max); // Return last N lines for screen capture
+    }
+
+    return lines;
+  }
+
+  /**
+   * Wait for a line matching the query (supports style-aware matching).
+   * @param {MatchQuery} query
+   * @param {WaitOptions} [opts]
+   * @returns {Promise<MatchResult>}
+   */
+  async waitForMatch(query, opts = {}) {
+    const timeoutMs = opts.timeoutMs || 30000;
+    const pollInterval = 100;
+    const deadline = Date.now() + timeoutMs;
+
+    while (Date.now() < deadline) {
+      const lines = await this.readNext();
+      const result = findMatch(lines, query);
+      if (result.matched) {
+        return result;
+      }
+      await sleep(pollInterval);
+    }
+
+    return { matched: false };
+  }
+
+  /**
+   * Get the last captured screen (raw string with ANSI codes).
+   * @returns {string}
+   */
+  getLastScreen() {
+    return this.lastScreen;
+  }
+}
+
+/**
+ * Fake terminal stream for testing.
+ * Implements TerminalStream interface.
+ * @implements {TerminalStream}
+ */
+class FakeTerminalStream {
+  /**
+   * @param {TerminalLine[]} lines - Initial lines to provide
+   */
+  constructor(lines = []) {
+    this.lines = [...lines];
+    this.readCount = 0;
+    /** @type {TerminalLine[][]} */
+    this.pendingLines = [];
+  }
+
+  /**
+   * Queue lines to be returned on subsequent readNext calls.
+   * @param {TerminalLine[]} lines
+   */
+  queueLines(lines) {
+    this.pendingLines.push(lines);
+  }
+
+  /**
+   * Add more lines to the current buffer (simulates new output).
+   * @param {TerminalLine[]} lines
+   */
+  addLines(lines) {
+    this.lines.push(...lines);
+  }
+
+  /**
+   * Read new lines since last read.
+   * First call returns initial lines, subsequent calls return queued lines.
+   * @param {ReadOptions} [opts]
+   * @returns {Promise<TerminalLine[]>}
+   */
+  async readNext(opts = {}) {
+    this.readCount++;
+
+    /** @type {TerminalLine[]} */
+    let result = [];
+    if (this.readCount === 1) {
+      result = this.lines;
+    } else if (this.pendingLines.length > 0) {
+      result = this.pendingLines.shift() || [];
+    }
+
+    if (opts.max && result.length > opts.max) {
+      return result.slice(0, opts.max);
+    }
+
+    return result;
+  }
+
+  /**
+   * Wait for a line matching the query.
+   * Immediately checks available lines without polling.
+   * @param {MatchQuery} query
+   * @param {WaitOptions} [_opts]
+   * @returns {Promise<MatchResult>}
+   */
+  async waitForMatch(query, _opts = {}) {
+    // Check initial lines
+    const result = findMatch(this.lines, query);
+    if (result.matched) {
+      return result;
+    }
+
+    // Check all pending lines
+    for (const pendingBatch of this.pendingLines) {
+      const batchResult = findMatch(pendingBatch, query);
+      if (batchResult.matched) {
+        return batchResult;
+      }
+    }
+
+    return { matched: false };
+  }
+
+  /**
+   * Create a TerminalLine from a raw string (helper for tests).
+   * @param {string} raw
+   * @returns {TerminalLine}
+   */
+  static line(raw) {
+    return { spans: [{ text: raw }], raw };
+  }
+
+  /**
+   * Create multiple TerminalLines from raw strings (helper for tests).
+   * @param {string[]} raws
+   * @returns {TerminalLine[]}
+   */
+  static lines(raws) {
+    return raws.map((raw) => FakeTerminalStream.line(raw));
+  }
+}
+
 /**
  * Extract pending tool from confirmation screen.
  * @param {string} screen
@@ -2100,6 +3025,36 @@ const State = {
   FEEDBACK_MODAL: "feedback_modal",
 };
 
+/**
+ * Check if the prompt symbol appears with bold styling in the last lines.
+ * Used to distinguish actual prompts from text that happens to contain the symbol.
+ * @param {string} session - tmux session name
+ * @param {string} promptSymbol - The prompt symbol to look for
+ * @returns {boolean}
+ */
+function hasStyledPrompt(session, promptSymbol) {
+  const styledScreen = tmuxCapture(session, 0, true); // withEscapes=true
+
+  // If styled capture fails, fall back to allowing READY to avoid deadlock
+  if (!styledScreen) {
+    debug("state", "styled capture failed, falling back to unstyled check");
+    return true;
+  }
+
+  // Trim to match detectState behavior (removes trailing blank lines)
+  const lines = parseStyledScreenLines(styledScreen.trim());
+  const lastLines = lines.slice(-8);
+
+  for (const line of lastLines) {
+    for (const span of line.spans) {
+      if (span.text.includes(promptSymbol) && span.style?.bold) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
 /**
  * Pure function to detect agent state from screen content.
  * @param {string} screen - The screen content to analyze
@@ -2108,8 +3063,11 @@ const State = {
  * @param {string[]} [config.spinners] - Spinner characters indicating thinking
  * @param {RegExp} [config.rateLimitPattern] - Pattern for rate limit detection
  * @param {(string | RegExp | ((lines: string) => boolean))[]} [config.thinkingPatterns] - Text patterns indicating thinking
+ * @param {(string | RegExp)[]} [config.activeWorkPatterns] - Patterns indicating active work (beats ready)
  * @param {(string | ((lines: string) => boolean))[]} [config.confirmPatterns] - Patterns for confirmation dialogs
  * @param {{screen: string[], lastLines: string[]} | null} [config.updatePromptPatterns] - Patterns for update prompts
+ * @param {string} [config.session] - tmux session for styled prompt verification
+ * @param {boolean} [config.requireStyledPrompt] - If true, require prompt to be bold (Codex)
  * @returns {string} The detected state
  */
 function detectState(screen, config) {
@@ -2176,8 +3134,18 @@ function detectState(screen, config) {
   // Ready - check BEFORE thinking to avoid false positives from timing messages like "✻ Worked for 45s"
   // If the prompt symbol is visible, the agent is ready regardless of spinner characters in timing messages
   if (lastLines.includes(config.promptSymbol)) {
-    debug("state", `promptSymbol "${config.promptSymbol}" found -> READY`);
-    return State.READY;
+    // If styled prompt check is enabled, verify prompt has expected styling
+    // This prevents false positives from output containing the prompt symbol
+    if (config.requireStyledPrompt && config.session) {
+      if (hasStyledPrompt(config.session, config.promptSymbol)) {
+        debug("state", `promptSymbol "${config.promptSymbol}" found with bold styling -> READY`);
+        return State.READY;
+      }
+      debug("state", `promptSymbol "${config.promptSymbol}" found but not bold, continuing checks`);
+    } else {
+      debug("state", `promptSymbol "${config.promptSymbol}" found -> READY`);
+      return State.READY;
+    }
   }
 
   // Thinking - spinners (check last lines only)
@@ -2250,7 +3218,7 @@ function detectState(screen, config) {
  * @property {string} [safeAllowedTools]
  * @property {string | null} [sessionIdFlag]
  * @property {((sessionName: string) => string | null) | null} [logPathFinder]
- * @property {((entry: object) => string | null) | null} [logEntryFormatter]
+ * @property {boolean} [requireStyledPrompt] - If true, require prompt to be bold for READY detection
  */
 
 class Agent {
@@ -2298,8 +3266,8 @@ class Agent {
     this.sessionIdFlag = config.sessionIdFlag || null;
     /** @type {((sessionName: string) => string | null) | null} */
     this.logPathFinder = config.logPathFinder || null;
-    /** @type {((entry: object) => string | null) | null} */
-    this.logEntryFormatter = config.logEntryFormatter || null;
+    /** @type {boolean} */
+    this.requireStyledPrompt = config.requireStyledPrompt || false;
   }
 
   /**
@@ -2447,22 +3415,41 @@ class Agent {
   }
 
   /**
-   * Format a log entry for streaming display.
-   * @param {object} entry
-   * @returns {string | null}
+   * Create a terminal stream for reading agent output.
+   * Returns JsonlTerminalStream for agents with log file support,
+   * otherwise falls back to ScreenTerminalStream.
+   * @param {string} sessionName
+   * @param {{skipExisting?: boolean}} [opts] - Options
+   * @returns {TerminalStream}
    */
-  formatLogEntry(entry) {
-    if (this.logEntryFormatter) {
-      return this.logEntryFormatter(entry);
+  createStream(sessionName, opts = {}) {
+    // Prefer JSONL stream if agent has log path finder
+    if (this.logPathFinder) {
+      /** @type {'claude' | 'codex'} */
+      const format = this.name === "claude" ? "claude" : "codex";
+      return new JsonlTerminalStream(() => this.findLogPath(sessionName), format, opts);
     }
-    return null;
+    // Fall back to screen capture
+    return new ScreenTerminalStream(sessionName);
+  }
+
+  /**
+   * Create a styled terminal stream with ANSI color support.
+   * Only uses screen capture (JSONL doesn't have style info).
+   * @param {string} sessionName
+   * @param {number} [scrollback]
+   * @returns {StyledScreenTerminalStream}
+   */
+  createStyledStream(sessionName, scrollback = 0) {
+    return new StyledScreenTerminalStream(sessionName, scrollback);
   }
 
   /**
    * @param {string} screen
+   * @param {string} [session] - Optional session for styled prompt verification
    * @returns {string}
    */
-  getState(screen) {
+  getState(screen, session) {
     return detectState(screen, {
       promptSymbol: this.promptSymbol,
       spinners: this.spinners,
@@ -2471,6 +3458,8 @@ class Agent {
       activeWorkPatterns: this.activeWorkPatterns,
       confirmPatterns: this.confirmPatterns,
       updatePromptPatterns: this.updatePromptPatterns,
+      session,
+      requireStyledPrompt: this.requireStyledPrompt,
     });
   }
 
@@ -2704,7 +3693,7 @@ const CodexAgent = new Agent({
   reviewOptions: { branch: "1", uncommitted: "2", commit: "3", custom: "4" },
   envVar: "AX_SESSION",
   logPathFinder: findCodexLogPath,
-  logEntryFormatter: formatCodexLogEntry,
+  requireStyledPrompt: true, // Codex prompt is bold, use this to avoid false positives
 });
 
 // =============================================================================
@@ -2722,7 +3711,7 @@ const ClaudeAgent = new Agent({
   rateLimitPattern: /rate.?limit/i,
   // Claude uses whimsical verbs like "Wibbling…", "Dancing…", etc. Match any capitalized -ing word + ellipsis (… or ...)
   thinkingPatterns: ["Thinking", /[A-Z][a-z]+ing(…|\.\.\.)/],
-  activeWorkPatterns: ["[Pasted text", "esc to interrupt"],
+  activeWorkPatterns: ["esc to interrupt"],
   confirmPatterns: [
     "Do you want to make this edit",
     "Do you want to run this command",
@@ -2754,7 +3743,6 @@ const ClaudeAgent = new Agent({
     if (uuid) return findClaudeLogPath(uuid, sessionName);
     return null;
   },
-  logEntryFormatter: formatClaudeLogEntry,
 });
 
 // =============================================================================
@@ -2772,7 +3760,7 @@ const ClaudeAgent = new Agent({
 async function waitUntilReady(agent, session, timeoutMs = DEFAULT_TIMEOUT_MS) {
   const start = Date.now();
   const initialScreen = tmuxCapture(session);
-  const initialState = agent.getState(initialScreen);
+  const initialState = agent.getState(initialScreen, session);
   debug("waitUntilReady", `start: initialState=${initialState}, timeout=${timeoutMs}ms`);
 
   // Dismiss feedback modal if present
@@ -2793,7 +3781,7 @@ async function waitUntilReady(agent, session, timeoutMs = DEFAULT_TIMEOUT_MS) {
   while (Date.now() - start < timeoutMs) {
     await sleep(POLL_MS);
     const screen = tmuxCapture(session);
-    const state = agent.getState(screen);
+    const state = agent.getState(screen, session);
 
     // Dismiss feedback modal if it appears
     if (state === State.FEEDBACK_MODAL) {
@@ -2824,7 +3812,7 @@ async function pollForResponse(agent, session, timeoutMs, hooks = {}) {
   const { onPoll, onStateChange, onReady } = hooks;
   const start = Date.now();
   const initialScreen = tmuxCapture(session);
-  const initialState = agent.getState(initialScreen);
+  const initialState = agent.getState(initialScreen, session);
   debug("poll", `start: initialState=${initialState}, timeoutMs=${timeoutMs}`);
 
   let lastScreen = initialScreen;
@@ -2840,7 +3828,7 @@ async function pollForResponse(agent, session, timeoutMs, hooks = {}) {
 
   while (Date.now() - start < timeoutMs) {
     const screen = tmuxCapture(session);
-    const state = agent.getState(screen);
+    const state = agent.getState(screen, session);
 
     if (onPoll) onPoll(screen, state);
 
@@ -2906,16 +3894,19 @@ async function waitForResponse(agent, session, timeoutMs = DEFAULT_TIMEOUT_MS) {
 
 /**
  * Wait for agent response with streaming output to console.
+ * Uses TerminalStream abstraction for reading agent output.
  * @param {Agent} agent
  * @param {string} session
  * @param {number} [timeoutMs]
  * @returns {Promise<{state: string, screen: string}>}
  */
 async function streamResponse(agent, session, timeoutMs = DEFAULT_TIMEOUT_MS) {
-  let logPath = agent.findLogPath(session);
-  let logOffset = logPath && existsSync(logPath) ? statSync(logPath).size : 0;
+  // Create terminal stream for this agent/session
+  // Skip existing content - only stream new responses
+  const stream = agent.createStream(session, { skipExisting: true });
   let printedThinking = false;
-  debug("stream", `start: logPath=${logPath || "null"}, logOffset=${logOffset}`);
+  debug("stream", `start: using ${stream.constructor.name}`);
+
   // Sliding window for deduplication - only dedupe recent messages
   // This catches Codex's duplicate log entries (A,B,A,B pattern) while
   // allowing legitimate repeated messages across turns
@@ -2923,54 +3914,50 @@ async function streamResponse(agent, session, timeoutMs = DEFAULT_TIMEOUT_MS) {
   const recentMessages = [];
   const DEDUPE_WINDOW = 10;
 
-  const streamNewEntries = () => {
-    if (!logPath) {
-      logPath = agent.findLogPath(session);
-      if (logPath && existsSync(logPath)) {
-        // Read from beginning when file is first discovered
-        // (Claude creates log file when first message is sent)
-        debug("stream", `log file discovered: ${logPath}`);
-        logOffset = 0;
-      }
+  const streamNewLines = async () => {
+    const lines = await stream.readNext();
+    if (lines.length > 0) {
+      debug("stream", `read ${lines.length} lines`);
     }
-    if (logPath) {
-      const { entries, newOffset } = tailJsonl(logPath, logOffset);
-      if (entries.length > 0) {
-        debug("stream", `read ${entries.length} entries, offset ${logOffset} -> ${newOffset}`);
-      }
-      logOffset = newOffset;
-      for (const entry of entries) {
-        const formatted = agent.formatLogEntry(entry);
-        if (!formatted) continue;
-
-        // Dedupe messages within sliding window (Codex logs can contain duplicates)
-        // Tool calls (starting with ">") are always printed
-        if (!formatted.startsWith(">")) {
-          if (recentMessages.includes(formatted)) continue;
-          recentMessages.push(formatted);
-          if (recentMessages.length > DEDUPE_WINDOW) recentMessages.shift();
-        }
 
-        console.log(formatted);
+    for (const line of lines) {
+      const text = line.raw;
+      if (!text) continue;
+
+      // Dedupe messages within sliding window (Codex logs can contain duplicates)
+      // Tool calls are exempt: lineType === "tool" for JSONL streams, or starts with ">" for screen streams
+      const isToolLine = line.lineType === "tool" || (!line.lineType && text.startsWith(">"));
+      if (!isToolLine) {
+        if (recentMessages.includes(text)) continue;
+        recentMessages.push(text);
+        if (recentMessages.length > DEDUPE_WINDOW) recentMessages.shift();
       }
+
+      // Style based on content type
+      // For screen streams, tool lines start with ">" and should be dimmed
+      const isThinking = line.lineType === "thinking";
+      const styled = isToolLine || isThinking ? styleText("dim", text) : text;
+      console.log(styled);
     }
   };
 
   return pollForResponse(agent, session, timeoutMs, {
-    onPoll: () => streamNewEntries(),
+    onPoll: () => streamNewLines(),
     onStateChange: (state, lastState, screen) => {
       if (state === State.THINKING && !printedThinking) {
-        console.log("[THINKING]");
+        console.log(styleText("dim", "[THINKING]"));
         printedThinking = true;
       } else if (state === State.CONFIRMING) {
         const pendingTool = extractPendingToolFromScreen(screen);
-        console.log(pendingTool ? `[CONFIRMING] ${pendingTool}` : "[CONFIRMING]");
+        console.log(
+          styleText("yellow", pendingTool ? `[CONFIRMING] ${pendingTool}` : "[CONFIRMING]"),
+        );
       }
       if (lastState === State.THINKING && state !== State.THINKING) {
         printedThinking = false;
       }
     },
-    onReady: () => streamNewEntries(),
+    onReady: () => streamNewLines(),
   });
 }
 
@@ -3046,7 +4033,7 @@ async function cmdStart(agent, session, { yolo = false, allowedTools = null } =
   const start = Date.now();
   while (Date.now() - start < STARTUP_TIMEOUT_MS) {
     const screen = tmuxCapture(session);
-    const state = agent.getState(screen);
+    const state = agent.getState(screen, session);
 
     if (state === State.UPDATE_PROMPT) {
       await agent.handleUpdatePrompt(session);
@@ -3107,7 +4094,7 @@ function cmdAgents() {
     const parsed = /** @type {ParsedSession} */ (parseSessionName(session));
     const agent = parsed.tool === "claude" ? ClaudeAgent : CodexAgent;
     const screen = tmuxCapture(session);
-    const state = agent.getState(screen);
+    const state = agent.getState(screen, session);
     const type = parsed.archangelName ? "archangel" : "-";
     const isDefault =
       (parsed.tool === "claude" && session === claudeDefault) ||
@@ -3270,7 +4257,7 @@ async function cmdArchangel(agentName) {
   const start = Date.now();
   while (Date.now() - start < ARCHANGEL_STARTUP_TIMEOUT_MS) {
     const screen = tmuxCapture(sessionName);
-    const state = agent.getState(screen);
+    const state = agent.getState(screen, sessionName);
 
     if (state === State.UPDATE_PROMPT) {
       await agent.handleUpdatePrompt(sessionName);
@@ -3436,7 +4423,7 @@ async function cmdArchangel(agentName) {
 
       // Wait for ready
       const screen = tmuxCapture(sessionName);
-      const state = agent.getState(screen);
+      const state = agent.getState(screen, sessionName);
 
       if (state === State.RATE_LIMITED) {
         console.error(`[archangel:${agentName}] Rate limited - stopping`);
@@ -4519,9 +5506,13 @@ async function cmdAsk(
     ? /** @type {string} */ (session)
     : await cmdStart(agent, session, { yolo, allowedTools });
 
-  tmuxSendLiteral(activeSession, message);
-  await sleep(200);
-  tmuxSend(activeSession, "Enter");
+  if (sessionExists) {
+    await waitUntilReady(agent, activeSession, timeoutMs);
+    tmuxSend(activeSession, "C-u"); // Clear any stale input
+    await sleep(50);
+  }
+
+  await tmuxSendText(activeSession, message);
 
   if (noWait) {
     const parsed = parseSessionName(activeSession);
@@ -4566,6 +5557,92 @@ e.g.
   }
 }
 
+/**
+ * @param {Agent} agent
+ * @param {string} prompt
+ * @param {{name?: string, maxLoops?: number, loop?: boolean, reset?: boolean, session?: string | null, yolo?: boolean, timeoutMs?: number}} [options]
+ */
+async function cmdDo(agent, prompt, options = {}) {
+  const maxLoops = options.maxLoops || 10;
+  const name = options.name || "default";
+  const loop = options.loop || false;
+  const reset = options.reset || false;
+  const yolo = options.yolo || false;
+  const timeoutMs = options.timeoutMs || DEFAULT_TIMEOUT_MS;
+
+  // Reset progress file if requested
+  if (reset) {
+    const progressPath = getDoProgressPath(name);
+    writeFileSync(progressPath, "");
+  }
+
+  // Use provided session or start a new one
+  const session = options.session
+    ? await cmdStart(agent, options.session, { yolo })
+    : await cmdStart(agent, null, { yolo });
+
+  // Print session ID for targeting approvals when not in yolo mode
+  if (!yolo) {
+    const parsed = parseSessionName(session);
+    const shortId = parsed?.uuid?.slice(0, 8) || session;
+    console.error(`Session: ${shortId}`);
+  }
+
+  const iterations = loop ? maxLoops : 1;
+
+  for (let i = 0; i < iterations; i++) {
+    // Fresh context (except first iteration)
+    if (i > 0) {
+      tmuxSendLiteral(session, "/new");
+      tmuxSend(session, "Enter");
+      await waitUntilReady(agent, session, timeoutMs);
+    }
+
+    // Build prompt with preamble + progress context
+    const fullPrompt = buildDoPrompt(prompt, name);
+
+    // Send prompt and submit
+    await tmuxSendText(session, fullPrompt);
+
+    const { state, screen } = yolo
+      ? await autoApproveLoop(agent, session, timeoutMs, streamResponse)
+      : await streamResponse(agent, session, timeoutMs);
+
+    if (state === State.RATE_LIMITED) {
+      console.log(`\nRate limited: ${agent.parseRetryTime(screen)}`);
+      process.exit(2);
+    }
+
+    if (state === State.CONFIRMING) {
+      const parsed = parseSessionName(session);
+      const shortId = parsed?.uuid?.slice(0, 8) || session;
+      console.log(`\nAwaiting confirmation: ${formatConfirmationOutput(screen, agent)}`);
+      console.log(`Add --session=${shortId} if you have multiple sessions`);
+      console.log("Use 'ax approve --wait' or 'ax reject' to continue");
+      process.exit(3);
+    }
+
+    const response = agent.getResponse(session, screen) || "";
+
+    // Check completion
+    if (response.includes("<promise>COMPLETE</promise>")) {
+      console.log(`\nCompleted after ${i + 1} iteration(s)`);
+      return;
+    }
+
+    // Single iteration mode (default): exit with code 5 to signal "more work"
+    if (!loop) {
+      console.log(`\nIteration complete. Re-run to continue, or --reset to start over.`);
+      process.exit(5);
+    }
+
+    console.log(`\n--- Iteration ${i + 1}/${maxLoops} complete ---`);
+  }
+
+  console.log(`\nReached max iterations (${maxLoops}) without completion`);
+  process.exit(1);
+}
+
 /**
  * @param {Agent} agent
  * @param {string | null | undefined} session
@@ -4578,7 +5655,7 @@ async function cmdApprove(agent, session, { wait = false, timeoutMs } = {}) {
   }
 
   const before = tmuxCapture(session);
-  const beforeState = agent.getState(before);
+  const beforeState = agent.getState(before, session);
   if (beforeState !== State.CONFIRMING) {
     console.log(`Already ${beforeState}`);
     return;
@@ -4616,7 +5693,7 @@ async function cmdReject(agent, session, { wait = false, timeoutMs } = {}) {
   }
 
   const before = tmuxCapture(session);
-  const beforeState = agent.getState(before);
+  const beforeState = agent.getState(before, session);
   if (beforeState !== State.CONFIRMING) {
     console.log(`Already ${beforeState}`);
     return;
@@ -4708,6 +5785,12 @@ async function cmdReview(
     ? /** @type {string} */ (session)
     : await cmdStart(agent, session, { yolo });
 
+  if (sessionExists) {
+    await waitUntilReady(agent, activeSession, timeoutMs);
+    tmuxSend(activeSession, "C-u"); // Clear any stale input
+    await sleep(50);
+  }
+
   debug("review", `Codex path: sending /review command`);
   tmuxSendLiteral(activeSession, "/review");
   await sleep(50);
@@ -4804,7 +5887,7 @@ async function cmdOutput(
     screen = tmuxCapture(session, 500);
   }
 
-  const state = agent.getState(screen);
+  const state = agent.getState(screen, session);
 
   if (state === State.RATE_LIMITED) {
     console.log(`RATE_LIMITED: ${agent.parseRetryTime(screen)}`);
@@ -4843,7 +5926,7 @@ function cmdStatus(agent, session) {
   }
 
   const screen = tmuxCapture(session);
-  const state = agent.getState(screen);
+  const state = agent.getState(screen, session);
 
   if (state === State.RATE_LIMITED) {
     console.log(`RATE_LIMITED: ${agent.parseRetryTime(screen)}`);
@@ -4877,7 +5960,7 @@ function cmdDebug(agent, session, { scrollback = 0 } = {}) {
   }
 
   const screen = tmuxCapture(session, scrollback);
-  const state = agent.getState(screen);
+  const state = agent.getState(screen, session);
 
   console.log(`=== Session: ${session} ===`);
   console.log(`=== State: ${state} ===`);
@@ -5048,6 +6131,8 @@ Usage: ${name} [OPTIONS] <command|message> [ARGS...]
 Messaging:
   <message>                 Send message to ${name}
   review [TYPE] [TARGET]    Review code: uncommitted, branch [base], commit [ref], custom
+  do <prompt>               Run one iteration (re-run to continue, exit 5 = more work)
+                            Options: --name=NAME, --loop, --max-loops=N, --reset, --yolo
 
 Sessions:
   compact                   Summarise session to shrink context size
@@ -5067,7 +6152,7 @@ Archangels:
 Recovery/State:
   status                    Exit code: ready=0 rate_limit=2 confirm=3 thinking=4
   output [-N]               Show response (0=last, -1=prev, -2=older)
-  debug                     Show raw screen output and detected state
+  debug [SESSION]           Show raw screen output and detected state
   approve                   Approve pending action (send 'y')
   reject                    Reject pending action (send 'n')
   select N                  Select menu option N
@@ -5189,7 +6274,7 @@ async function main() {
   const cmd = positionals[0];
 
   // Dispatch commands
-  if (cmd === "agents") return cmdAgents();
+  if (cmd === "agents" || cmd === "list") return cmdAgents();
   if (cmd === "target") {
     const defaultSession = agent.getDefaultSession({ allowedTools: autoApprove, yolo });
     if (defaultSession) {
@@ -5204,8 +6289,14 @@ async function main() {
   if (cmd === "recall") return cmdRecall(positionals[1]);
   if (cmd === "archangel") return cmdArchangel(positionals[1]);
   if (cmd === "kill") return cmdKill(session, { all, orphans, force });
-  if (cmd === "attach") return cmdAttach(positionals[1] || session);
-  if (cmd === "log") return cmdLog(positionals[1] || session, { tail, reasoning, follow });
+  if (cmd === "attach") {
+    const attachSession = positionals[1] ? resolveSessionName(positionals[1]) : session;
+    return cmdAttach(attachSession);
+  }
+  if (cmd === "log") {
+    const logSession = positionals[1] ? resolveSessionName(positionals[1]) : session;
+    return cmdLog(logSession, { tail, reasoning, follow });
+  }
   if (cmd === "mailbox") return cmdMailbox({ limit, branch, all });
   if (cmd === "rfp") {
     if (positionals[1] === "wait") {
@@ -5224,6 +6315,23 @@ async function main() {
     }
     return cmdRfp(prompt, { archangels: flags.archangels, fresh, noWait });
   }
+  if (cmd === "do") {
+    const rawPrompt = positionals.slice(1).join(" ");
+    const prompt = await readStdinIfNeeded(rawPrompt);
+    if (!prompt) {
+      console.log("ERROR: no prompt provided");
+      process.exit(1);
+    }
+    return cmdDo(agent, prompt, {
+      name: flags.name || "default",
+      maxLoops: flags.maxLoops || 10,
+      loop: flags.loop,
+      reset: flags.reset,
+      session: flags.session ? session : null,
+      yolo,
+      timeoutMs,
+    });
+  }
   if (cmd === "approve") return cmdApprove(agent, session, { wait, timeoutMs });
   if (cmd === "reject") return cmdReject(agent, session, { wait, timeoutMs });
   if (cmd === "review") {
@@ -5235,7 +6343,10 @@ async function main() {
     });
   }
   if (cmd === "status") return cmdStatus(agent, session);
-  if (cmd === "debug") return cmdDebug(agent, session);
+  if (cmd === "debug") {
+    const debugSession = positionals[1] ? resolveSessionName(positionals[1]) : session;
+    return cmdDebug(agent, debugSession);
+  }
   if (cmd === "output") {
     const indexArg = positionals[1];
     const index = indexArg?.startsWith("-") ? parseInt(indexArg, 10) : 0;
@@ -5244,7 +6355,23 @@ async function main() {
   if (cmd === "send" && positionals.length > 1)
     return cmdSend(session, positionals.slice(1).join(" "));
   if (cmd === "compact") return cmdAsk(agent, session, "/compact", { noWait: true, timeoutMs });
-  if (cmd === "reset") return cmdAsk(agent, session, "/new", { noWait: true, timeoutMs });
+  if (cmd === "reset") {
+    // Send /new and wait for completion
+    await cmdAsk(agent, session, "/new", { timeoutMs });
+
+    // Find the newest session UUID and rename tmux session to match
+    if (session && agent.name === "claude") {
+      const newUuid = findNewestClaudeSessionUuid(session);
+      if (newUuid) {
+        const newName = rebuildSessionName(session, newUuid);
+        if (newName && newName !== session) {
+          tmuxRenameSession(session, newName);
+          console.log(`Session: ${newName}`);
+        }
+      }
+    }
+    return;
+  }
   if (cmd === "select" && positionals[1])
     return cmdSelect(agent, session, positionals[1], { wait, timeoutMs });
 
@@ -5318,6 +6445,17 @@ export {
   computePermissionHash,
   formatClaudeLogEntry,
   formatCodexLogEntry,
+  // Terminal stream primitives
+  parseJsonlEntry,
+  parseScreenLines,
+  parseAnsiLine,
+  parseStyledScreenLines,
+  findMatch,
+  // Terminal stream implementations
+  JsonlTerminalStream,
+  ScreenTerminalStream,
+  StyledScreenTerminalStream,
+  FakeTerminalStream,
   CodexAgent,
   ClaudeAgent,
 };