ax-agents 0.1.1 → 0.1.3

package/ax.js

@@ -144,6 +144,15 @@ function debugError(context, err) {
   if (DEBUG) console.error(`[debug:${context}]`, err instanceof Error ? err.message : err);
 }
 
+/**
+ * Log debug message when AX_DEBUG=1
+ * @param {string} tag - Short tag for the debug message (e.g., "poll", "tmux")
+ * @param {string} message - The debug message
+ */
+function debug(tag, message) {
+  if (DEBUG) console.error(`[${tag}] ${message}`);
+}
+
 // =============================================================================
 // Project root detection (walk up to find .ai/ directory)
 // =============================================================================
@@ -214,6 +223,7 @@ function tmuxCapture(session, scrollback = 0) {
  * @param {string} keys
  */
 function tmuxSend(session, keys) {
+  debug("tmux", `send session=${session}, keys=${keys}`);
   tmux(["send-keys", "-t", session, keys]);
 }
 
@@ -222,6 +232,7 @@ function tmuxSend(session, keys) {
  * @param {string} text
  */
 function tmuxSendLiteral(session, text) {
+  debug("tmux", `sendLiteral session=${session}, text=${text.slice(0, 50)}...`);
   tmux(["send-keys", "-t", session, "-l", text]);
 }
 
@@ -241,11 +252,15 @@ function tmuxKill(session) {
  * @param {string} command
  */
 function tmuxNewSession(session, command) {
+  debug("tmux", `newSession: ${session}, command: ${command.slice(0, 80)}...`);
   // Use spawnSync to avoid command injection via session/command
   const result = spawnSync("tmux", ["new-session", "-d", "-s", session, command], {
     encoding: "utf-8",
   });
-  if (result.status !== 0) throw new Error(result.stderr || "tmux new-session failed");
+  if (result.status !== 0) {
+    debug("tmux", `newSession failed: ${result.stderr}`);
+    throw new Error(result.stderr || "tmux new-session failed");
+  }
 }
 
 /**
@@ -404,11 +419,16 @@ class TimeoutError extends Error {
  */
 async function waitFor(session, predicate, timeoutMs = STARTUP_TIMEOUT_MS) {
   const start = Date.now();
+  debug("waitFor", `waiting (timeout=${timeoutMs}ms)`);
   while (Date.now() - start < timeoutMs) {
     const screen = tmuxCapture(session);
-    if (predicate(screen)) return screen;
+    if (predicate(screen)) {
+      debug("waitFor", `matched after ${Date.now() - start}ms`);
+      return screen;
+    }
     await sleep(POLL_MS);
   }
+  debug("waitFor", `timeout after ${timeoutMs}ms`);
   throw new TimeoutError(session);
 }
 
@@ -711,6 +731,7 @@ function findClaudeLogPath(sessionId, sessionName) {
   const cwd = (sessionName && getTmuxSessionCwd(sessionName)) || process.cwd();
   const projectPath = getClaudeProjectPath(cwd);
   const claudeProjectDir = path.join(CLAUDE_CONFIG_DIR, "projects", projectPath);
+  debug("log", `findClaudeLogPath: sessionId=${sessionId}, projectDir=${claudeProjectDir}`);
 
   // Check sessions-index.json first
   const indexPath = path.join(claudeProjectDir, "sessions-index.json");
@@ -720,7 +741,10 @@ function findClaudeLogPath(sessionId, sessionName) {
       const entry = index.entries?.find(
         /** @param {{sessionId: string, fullPath?: string}} e */ (e) => e.sessionId === sessionId,
       );
-      if (entry?.fullPath) return entry.fullPath;
+      if (entry?.fullPath) {
+        debug("log", `findClaudeLogPath: found via index -> ${entry.fullPath}`);
+        return entry.fullPath;
+      }
     } catch (err) {
       debugError("findClaudeLogPath", err);
     }
@@ -728,8 +752,12 @@ function findClaudeLogPath(sessionId, sessionName) {
 
   // Fallback: direct path
   const directPath = path.join(claudeProjectDir, `${sessionId}.jsonl`);
-  if (existsSync(directPath)) return directPath;
+  if (existsSync(directPath)) {
+    debug("log", `findClaudeLogPath: found via direct path -> ${directPath}`);
+    return directPath;
+  }
 
+  debug("log", `findClaudeLogPath: not found`);
   return null;
 }
 
@@ -738,6 +766,7 @@ function findClaudeLogPath(sessionId, sessionName) {
  * @returns {string | null}
  */
 function findCodexLogPath(sessionName) {
+  debug("log", `findCodexLogPath: sessionName=${sessionName}`);
   // For Codex, we need to match by timing since we can't control the session ID
   // Get tmux session creation time
   try {
@@ -748,13 +777,22 @@ function findCodexLogPath(sessionName) {
         encoding: "utf-8",
       },
     );
-    if (result.status !== 0) return null;
+    if (result.status !== 0) {
+      debug("log", `findCodexLogPath: tmux display-message failed`);
+      return null;
+    }
     const createdTs = parseInt(result.stdout.trim(), 10) * 1000; // tmux gives seconds, we need ms
-    if (isNaN(createdTs)) return null;
+    if (isNaN(createdTs)) {
+      debug("log", `findCodexLogPath: invalid timestamp`);
+      return null;
+    }
 
     // Codex stores sessions in ~/.codex/sessions/YYYY/MM/DD/rollout-TIMESTAMP-UUID.jsonl
     const sessionsDir = path.join(CODEX_CONFIG_DIR, "sessions");
-    if (!existsSync(sessionsDir)) return null;
+    if (!existsSync(sessionsDir)) {
+      debug("log", `findCodexLogPath: sessions dir not found`);
+      return null;
+    }
 
     const startDate = new Date(createdTs);
     const year = startDate.getFullYear().toString();
@@ -762,11 +800,15 @@ function findCodexLogPath(sessionName) {
     const day = String(startDate.getDate()).padStart(2, "0");
 
     const dayDir = path.join(sessionsDir, year, month, day);
-    if (!existsSync(dayDir)) return null;
+    if (!existsSync(dayDir)) {
+      debug("log", `findCodexLogPath: day dir not found: ${dayDir}`);
+      return null;
+    }
 
     // Find the closest log file created after the tmux session started
     // Use 60-second window to handle slow startups (model download, first run, heavy load)
     const files = readdirSync(dayDir).filter((f) => f.endsWith(".jsonl"));
+    debug("log", `findCodexLogPath: ${files.length} jsonl files in ${dayDir}`);
     const candidates = [];
 
     for (const file of files) {
@@ -789,11 +831,16 @@ function findCodexLogPath(sessionName) {
       }
     }
 
-    if (candidates.length === 0) return null;
+    if (candidates.length === 0) {
+      debug("log", `findCodexLogPath: no candidates within time window`);
+      return null;
+    }
     // Return the closest match
     candidates.sort((a, b) => a.diff - b.diff);
+    debug("log", `findCodexLogPath: found ${candidates.length} candidates, best: ${candidates[0].path}`);
     return candidates[0].path;
   } catch {
+    debug("log", `findCodexLogPath: exception caught`);
     return null;
   }
 }
@@ -977,11 +1024,12 @@ function tailJsonl(logPath, fromOffset) {
  */
 
 /**
- * Format a JSONL entry for streaming display.
+ * 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
  * @returns {string | null}
  */
-function formatEntry(entry) {
+function formatClaudeLogEntry(entry) {
   // Skip tool_result entries (they can be very verbose)
   if (entry.type === "tool_result") return null;
 
@@ -994,6 +1042,9 @@ function formatEntry(entry) {
   for (const part of parts) {
     if (part.type === "text" && part.text) {
       output.push(part.text);
+    } else if (part.type === "thinking" && part.thinking) {
+      // Include thinking blocks - extended thinking models put responses here
+      output.push(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 || {};
@@ -1006,12 +1057,69 @@ function formatEntry(entry) {
       }
       output.push(`> ${name}(${summary})`);
     }
-    // Skip thinking blocks - internal reasoning
   }
 
   return output.length > 0 ? output.join("\n") : null;
 }
 
+/**
+ * Format a Codex JSONL log entry for streaming display.
+ * Codex format:
+ * - {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}
+ */
+function formatCodexLogEntry(entry) {
+  // Skip function_call_output entries (equivalent to tool_result - can be verbose)
+  if (entry.type === "response_item" && entry.payload?.type === "function_call_output") {
+    return null;
+  }
+
+  // Handle function calls
+  if (entry.type === "response_item" && entry.payload?.type === "function_call") {
+    const name = entry.payload.name || "tool";
+    let summary = "";
+    try {
+      const args = JSON.parse(entry.payload.arguments || "{}");
+      if (name === "shell_command" && args.command) {
+        summary = args.command.slice(0, 50);
+      } else {
+        const target = args.file_path || args.path || args.pattern || "";
+        summary = target.split("/").pop() || target.slice(0, 30);
+      }
+    } catch {
+      summary = "...";
+    }
+    return `> ${name}(${summary})`;
+  }
+
+  // Handle assistant messages (final response)
+  if (entry.type === "response_item" && entry.payload?.role === "assistant") {
+    const parts = entry.payload.content || [];
+    const output = [];
+    for (const part of parts) {
+      if ((part.type === "output_text" || part.type === "text") && part.text) {
+        output.push(part.text);
+      }
+    }
+    return output.length > 0 ? output.join("\n") : null;
+  }
+
+  // Handle streaming agent messages
+  if (entry.type === "event_msg" && entry.payload?.type === "agent_message") {
+    return entry.payload.message || null;
+  }
+
+  // Handle agent reasoning (thinking during review)
+  if (entry.type === "event_msg" && entry.payload?.type === "agent_reasoning") {
+    return entry.payload.text || null;
+  }
+
+  return null;
+}
+
 /**
  * Extract pending tool from confirmation screen.
  * @param {string} screen
@@ -1075,16 +1183,23 @@ function resolveSessionName(partial) {
 
   const sessions = tmuxListSessions();
   const agentSessions = sessions.filter((s) => parseSessionName(s));
+  debug("session", `resolving "${partial}" from ${agentSessions.length} agent sessions`);
 
   // Exact match
-  if (agentSessions.includes(partial)) return partial;
+  if (agentSessions.includes(partial)) {
+    debug("session", `exact match: ${partial}`);
+    return partial;
+  }
 
   // Archangel name match (e.g., "reviewer" matches "claude-archangel-reviewer-uuid")
   const archangelMatches = agentSessions.filter((s) => {
     const parsed = parseSessionName(s);
     return parsed?.archangelName === partial;
   });
-  if (archangelMatches.length === 1) return archangelMatches[0];
+  if (archangelMatches.length === 1) {
+    debug("session", `archangel match: ${archangelMatches[0]}`);
+    return archangelMatches[0];
+  }
   if (archangelMatches.length > 1) {
     console.log("ERROR: ambiguous archangel name. Matches:");
     for (const m of archangelMatches) console.log(`  ${m}`);
@@ -1093,7 +1208,10 @@ function resolveSessionName(partial) {
 
   // Prefix match
   const matches = agentSessions.filter((s) => s.startsWith(partial));
-  if (matches.length === 1) return matches[0];
+  if (matches.length === 1) {
+    debug("session", `prefix match: ${matches[0]}`);
+    return matches[0];
+  }
   if (matches.length > 1) {
     console.log("ERROR: ambiguous session prefix. Matches:");
     for (const m of matches) console.log(`  ${m}`);
@@ -1105,13 +1223,17 @@ function resolveSessionName(partial) {
     const parsed = parseSessionName(s);
     return parsed?.uuid?.startsWith(partial);
   });
-  if (uuidMatches.length === 1) return uuidMatches[0];
+  if (uuidMatches.length === 1) {
+    debug("session", `UUID match: ${uuidMatches[0]}`);
+    return uuidMatches[0];
+  }
   if (uuidMatches.length > 1) {
     console.log("ERROR: ambiguous UUID prefix. Matches:");
     for (const m of uuidMatches) console.log(`  ${m}`);
     process.exit(1);
   }
 
+  debug("session", `no match found, returning as-is: ${partial}`);
   return partial; // Return as-is, let caller handle not found
 }
 
@@ -1991,7 +2113,10 @@ const State = {
  * @returns {string} The detected state
  */
 function detectState(screen, config) {
-  if (!screen) return State.STARTING;
+  if (!screen) {
+    debug("state", "no screen -> STARTING");
+    return State.STARTING;
+  }
 
   const lines = screen.trim().split("\n");
   const lastLines = lines.slice(-8).join("\n");
@@ -2000,6 +2125,7 @@ function detectState(screen, config) {
 
   // Rate limited - check recent lines (not full screen to avoid matching historical output)
   if (config.rateLimitPattern && config.rateLimitPattern.test(recentLines)) {
+    debug("state", "rateLimitPattern matched -> RATE_LIMITED");
     return State.RATE_LIMITED;
   }
 
@@ -2011,6 +2137,7 @@ function detectState(screen, config) {
     /3:\s*Good/i.test(recentLines) &&
     /0:\s*Dismiss/i.test(recentLines)
   ) {
+    debug("state", "feedback modal detected -> FEEDBACK_MODAL");
     return State.FEEDBACK_MODAL;
   }
 
@@ -2019,54 +2146,71 @@ function detectState(screen, config) {
   for (const pattern of confirmPatterns) {
     if (typeof pattern === "function") {
       // Functions check lastLines first (most specific), then recentLines
-      if (pattern(lastLines)) return State.CONFIRMING;
-      if (pattern(recentLines)) return State.CONFIRMING;
+      if (pattern(lastLines)) {
+        debug("state", "confirmPattern function matched lastLines -> CONFIRMING");
+        return State.CONFIRMING;
+      }
+      if (pattern(recentLines)) {
+        debug("state", "confirmPattern function matched recentLines -> CONFIRMING");
+        return State.CONFIRMING;
+      }
     } else {
       // String patterns check recentLines (bounded range)
-      if (recentLines.includes(pattern)) return State.CONFIRMING;
+      if (recentLines.includes(pattern)) {
+        debug("state", `confirmPattern "${pattern}" matched -> CONFIRMING`);
+        return State.CONFIRMING;
+      }
+    }
+  }
+
+  // Check for active work patterns first (agent shows prompt even while working)
+  const activeWorkPatterns = config.activeWorkPatterns || [];
+  for (const p of activeWorkPatterns) {
+    const matched = p instanceof RegExp ? p.test(lastLines) : lastLines.includes(p);
+    if (matched) {
+      debug("state", `activeWorkPattern "${p}" matched -> THINKING`);
+      return State.THINKING;
     }
   }
 
   // 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)) {
-    // Check if any line has the prompt followed by pasted content indicator
-    // "[Pasted text" indicates user has pasted content and Claude is still processing
-    const linesArray = lastLines.split("\n");
-    const promptWithPaste = linesArray.some(
-      (l) => l.includes(config.promptSymbol) && l.includes("[Pasted text"),
-    );
-    if (!promptWithPaste) {
-      return State.READY;
-    }
-    // If prompt has pasted content, Claude is still processing - not ready yet
+    debug("state", `promptSymbol "${config.promptSymbol}" found -> READY`);
+    return State.READY;
   }
 
   // Thinking - spinners (check last lines only)
   const spinners = config.spinners || [];
-  if (spinners.some((s) => lastLines.includes(s))) {
-    return State.THINKING;
+  for (const s of spinners) {
+    if (lastLines.includes(s)) {
+      debug("state", `spinner "${s}" matched -> THINKING`);
+      return State.THINKING;
+    }
   }
   // Thinking - text patterns (last lines) - supports strings, regexes, and functions
   const thinkingPatterns = config.thinkingPatterns || [];
-  if (
-    thinkingPatterns.some((p) => {
-      if (typeof p === "function") return p(lastLines);
-      if (p instanceof RegExp) return p.test(lastLines);
-      return lastLines.includes(p);
-    })
-  ) {
-    return State.THINKING;
+  for (const p of thinkingPatterns) {
+    let matched = false;
+    if (typeof p === "function") matched = p(lastLines);
+    else if (p instanceof RegExp) matched = p.test(lastLines);
+    else matched = lastLines.includes(p);
+    if (matched) {
+      debug("state", `thinkingPattern "${p}" matched -> THINKING`);
+      return State.THINKING;
+    }
   }
 
   // Update prompt
   if (config.updatePromptPatterns) {
     const { screen: sp, lastLines: lp } = config.updatePromptPatterns;
     if (sp && sp.some((p) => screen.includes(p)) && lp && lp.some((p) => lastLines.includes(p))) {
+      debug("state", "updatePromptPatterns matched -> UPDATE_PROMPT");
       return State.UPDATE_PROMPT;
     }
   }
 
+  debug("state", "no patterns matched -> STARTING");
   return State.STARTING;
 }
 
@@ -2094,6 +2238,7 @@ function detectState(screen, config) {
  * @property {string[]} [spinners]
  * @property {RegExp} [rateLimitPattern]
  * @property {(string | RegExp | ((lines: string) => boolean))[]} [thinkingPatterns]
+ * @property {(string | RegExp)[]} [activeWorkPatterns]
  * @property {ConfirmPattern[]} [confirmPatterns]
  * @property {UpdatePromptPatterns | null} [updatePromptPatterns]
  * @property {string[]} [responseMarkers]
@@ -2105,6 +2250,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]
  */
 
 class Agent {
@@ -2128,6 +2274,8 @@ class Agent {
     this.rateLimitPattern = config.rateLimitPattern;
     /** @type {(string | RegExp | ((lines: string) => boolean))[]} */
     this.thinkingPatterns = config.thinkingPatterns || [];
+    /** @type {(string | RegExp)[]} */
+    this.activeWorkPatterns = config.activeWorkPatterns || [];
     /** @type {ConfirmPattern[]} */
     this.confirmPatterns = config.confirmPatterns || [];
     /** @type {UpdatePromptPatterns | null} */
@@ -2150,6 +2298,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;
   }
 
   /**
@@ -2162,24 +2312,31 @@ class Agent {
     let base;
     if (yolo) {
       base = this.yoloCommand;
+      debug("command", `mode=yolo`);
     } else if (customAllowedTools) {
       // Custom permissions from --auto-approve flag
       // Escape for shell: backslashes first, then double quotes
       const escaped = customAllowedTools.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
       base = `${this.startCommand} --allowedTools "${escaped}"`;
+      debug("command", `mode=custom, allowedTools=${customAllowedTools}`);
     } else if (this.safeAllowedTools) {
       // Default: auto-approve safe read-only operations
       base = `${this.startCommand} --allowedTools "${this.safeAllowedTools}"`;
+      debug("command", `mode=safe, allowedTools=${this.safeAllowedTools}`);
     } else {
       base = this.startCommand;
+      debug("command", `mode=default`);
     }
     // Some agents support session ID flags for deterministic session tracking
     if (this.sessionIdFlag && sessionName) {
       const parsed = parseSessionName(sessionName);
       if (parsed?.uuid) {
-        return `${base} ${this.sessionIdFlag} ${parsed.uuid}`;
+        const cmd = `${base} ${this.sessionIdFlag} ${parsed.uuid}`;
+        debug("command", `full: ${cmd}`);
+        return cmd;
       }
     }
+    debug("command", `full: ${base}`);
     return base;
   }
 
@@ -2289,6 +2446,18 @@ class Agent {
     return null;
   }
 
+  /**
+   * Format a log entry for streaming display.
+   * @param {object} entry
+   * @returns {string | null}
+   */
+  formatLogEntry(entry) {
+    if (this.logEntryFormatter) {
+      return this.logEntryFormatter(entry);
+    }
+    return null;
+  }
+
   /**
    * @param {string} screen
    * @returns {string}
@@ -2299,6 +2468,7 @@ class Agent {
       spinners: this.spinners,
       rateLimitPattern: this.rateLimitPattern,
       thinkingPatterns: this.thinkingPatterns,
+      activeWorkPatterns: this.activeWorkPatterns,
       confirmPatterns: this.confirmPatterns,
       updatePromptPatterns: this.updatePromptPatterns,
     });
@@ -2528,11 +2698,13 @@ const CodexAgent = new Agent({
     screen: ["Update available"],
     lastLines: ["Skip"],
   },
+  activeWorkPatterns: ["esc to interrupt"],
   responseMarkers: ["•", "- ", "**"],
   chromePatterns: ["context left", "for shortcuts"],
-  reviewOptions: { pr: "1", uncommitted: "2", commit: "3", custom: "4" },
+  reviewOptions: { branch: "1", uncommitted: "2", commit: "3", custom: "4" },
   envVar: "AX_SESSION",
   logPathFinder: findCodexLogPath,
+  logEntryFormatter: formatCodexLogEntry,
 });
 
 // =============================================================================
@@ -2550,6 +2722,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"],
   confirmPatterns: [
     "Do you want to make this edit",
     "Do you want to run this command",
@@ -2581,6 +2754,7 @@ const ClaudeAgent = new Agent({
     if (uuid) return findClaudeLogPath(uuid, sessionName);
     return null;
   },
+  logEntryFormatter: formatClaudeLogEntry,
 });
 
 // =============================================================================
@@ -2599,9 +2773,11 @@ async function waitUntilReady(agent, session, timeoutMs = DEFAULT_TIMEOUT_MS) {
   const start = Date.now();
   const initialScreen = tmuxCapture(session);
   const initialState = agent.getState(initialScreen);
+  debug("waitUntilReady", `start: initialState=${initialState}, timeout=${timeoutMs}ms`);
 
   // Dismiss feedback modal if present
   if (initialState === State.FEEDBACK_MODAL) {
+    debug("waitUntilReady", `dismissing feedback modal`);
     tmuxSend(session, "0");
     await sleep(200);
   } else if (
@@ -2610,6 +2786,7 @@ async function waitUntilReady(agent, session, timeoutMs = DEFAULT_TIMEOUT_MS) {
     initialState === State.CONFIRMING ||
     initialState === State.READY
   ) {
+    debug("waitUntilReady", `already in terminal state: ${initialState}`);
     return { state: initialState, screen: initialScreen };
   }
 
@@ -2620,15 +2797,18 @@ async function waitUntilReady(agent, session, timeoutMs = DEFAULT_TIMEOUT_MS) {
 
     // Dismiss feedback modal if it appears
     if (state === State.FEEDBACK_MODAL) {
+      debug("waitUntilReady", `dismissing feedback modal`);
       tmuxSend(session, "0");
       await sleep(200);
       continue;
     }
 
     if (state === State.RATE_LIMITED || state === State.CONFIRMING || state === State.READY) {
+      debug("waitUntilReady", `reached state=${state} after ${Date.now() - start}ms`);
       return { state, screen };
     }
   }
+  debug("waitUntilReady", `timeout after ${timeoutMs}ms`);
   throw new TimeoutError(session);
 }
 
@@ -2644,11 +2824,19 @@ 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);
+  debug("poll", `start: initialState=${initialState}, timeoutMs=${timeoutMs}`);
 
   let lastScreen = initialScreen;
   let lastState = null;
   let stableAt = null;
   let sawActivity = false;
+  let sawThinking = false;
+
+  // Fallback timeout: accept READY without sawThinking after this many ms
+  // This handles fast responses where we might miss the THINKING state
+  // Clamp to timeoutMs so short timeouts don't always fail
+  const THINKING_FALLBACK_MS = Math.min(10000, timeoutMs);
 
   while (Date.now() - start < timeoutMs) {
     const screen = tmuxCapture(session);
@@ -2676,19 +2864,28 @@ async function pollForResponse(agent, session, timeoutMs, hooks = {}) {
       lastScreen = screen;
       stableAt = Date.now();
       if (screen !== initialScreen) {
+        if (!sawActivity) debug("poll", "sawActivity=true (screen changed from initial)");
         sawActivity = true;
       }
     }
 
+    // Check if we can return READY
     if (sawActivity && stableAt && Date.now() - stableAt >= STABLE_MS) {
       if (state === State.READY) {
-        if (onReady) onReady(screen);
-        return { state, screen };
+        // Require sawThinking OR enough time has passed (fallback for fast responses)
+        const elapsed = Date.now() - start;
+        if (sawThinking || elapsed >= THINKING_FALLBACK_MS) {
+          debug("poll", `returning READY after ${elapsed}ms (sawThinking=${sawThinking})`);
+          if (onReady) onReady(screen);
+          return { state, screen };
+        }
       }
     }
 
     if (state === State.THINKING) {
       sawActivity = true;
+      if (!sawThinking) debug("poll", "sawThinking=true");
+      sawThinking = true;
     }
 
     await sleep(POLL_MS);
@@ -2718,20 +2915,43 @@ async function streamResponse(agent, session, timeoutMs = DEFAULT_TIMEOUT_MS) {
   let logPath = agent.findLogPath(session);
   let logOffset = logPath && existsSync(logPath) ? statSync(logPath).size : 0;
   let printedThinking = false;
+  debug("stream", `start: logPath=${logPath || "null"}, logOffset=${logOffset}`);
+  // 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
+  /** @type {string[]} */
+  const recentMessages = [];
+  const DEDUPE_WINDOW = 10;
 
   const streamNewEntries = () => {
     if (!logPath) {
       logPath = agent.findLogPath(session);
       if (logPath && existsSync(logPath)) {
-        logOffset = statSync(logPath).size;
+        // 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;
       }
     }
     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 = formatEntry(entry);
-        if (formatted) console.log(formatted);
+        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);
       }
     }
   };
@@ -2764,6 +2984,7 @@ async function streamResponse(agent, session, timeoutMs = DEFAULT_TIMEOUT_MS) {
  */
 async function autoApproveLoop(agent, session, timeoutMs, waitFn) {
   const deadline = Date.now() + timeoutMs;
+  debug("autoApprove", `starting loop, timeout=${timeoutMs}ms`);
 
   while (Date.now() < deadline) {
     const remaining = deadline - Date.now();
@@ -2772,10 +2993,12 @@ async function autoApproveLoop(agent, session, timeoutMs, waitFn) {
     const { state, screen } = await waitFn(agent, session, remaining);
 
     if (state === State.RATE_LIMITED || state === State.READY) {
+      debug("autoApprove", `finished with state=${state}`);
       return { state, screen };
     }
 
     if (state === State.CONFIRMING) {
+      debug("autoApprove", `auto-approving confirmation`);
       tmuxSend(session, agent.approveKey);
       await sleep(APPROVE_DELAY_MS);
       continue;
@@ -2785,6 +3008,7 @@ async function autoApproveLoop(agent, session, timeoutMs, waitFn) {
     debugError("autoApproveLoop", new Error(`unexpected state: ${state}`));
   }
 
+  debug("autoApprove", `timeout`);
   throw new TimeoutError(session);
 }
 
@@ -2800,9 +3024,13 @@ async function cmdStart(agent, session, { yolo = false, allowedTools = null } =
   // Generate session name if not provided
   if (!session) {
     session = agent.generateSession({ allowedTools, yolo });
+    debug("session", `generated new session: ${session}`);
   }
 
-  if (tmuxHasSession(session)) return session;
+  if (tmuxHasSession(session)) {
+    debug("session", `reusing existing session: ${session}`);
+    return session;
+  }
 
   // Check agent CLI is installed before trying to start
   const cliCheck = spawnSync("which", [agent.name], { encoding: "utf-8" });
@@ -2812,6 +3040,7 @@ async function cmdStart(agent, session, { yolo = false, allowedTools = null } =
   }
 
   const command = agent.getCommand(yolo, session, allowedTools);
+  debug("session", `creating tmux session: ${session}`);
   tmuxNewSession(session, command);
 
   const start = Date.now();
@@ -4291,7 +4520,7 @@ async function cmdAsk(
     : await cmdStart(agent, session, { yolo, allowedTools });
 
   tmuxSendLiteral(activeSession, message);
-  await sleep(50);
+  await sleep(200);
   tmuxSend(activeSession, "Enter");
 
   if (noWait) {
@@ -4422,6 +4651,13 @@ async function cmdReview(
   customInstructions,
   { wait = true, yolo = false, fresh = false, timeoutMs = REVIEW_TIMEOUT_MS } = {},
 ) {
+  const validOptions = ["uncommitted", "custom", "branch", "commit"];
+  if (option && !validOptions.includes(option)) {
+    console.error(`Unknown review option: ${option}`);
+    console.error(`Valid options: ${validOptions.join(", ")}`);
+    process.exit(1);
+  }
+
   const sessionExists = session != null && tmuxHasSession(session);
 
   // Reset conversation if --fresh and session exists
@@ -4436,12 +4672,17 @@ async function cmdReview(
   if (!agent.reviewOptions) {
     /** @type {Record<string, string>} */
     const reviewPrompts = {
-      pr: "Review the current PR.",
       uncommitted: "Review uncommitted changes.",
-      commit: "Review the most recent git commit.",
+      branch: customInstructions
+        ? `Review changes on the current branch compared to ${customInstructions}.`
+        : "Review changes on the current branch compared to main.",
+      commit: customInstructions
+        ? `Review commit ${customInstructions}.`
+        : "Review the most recent commit.",
       custom: customInstructions || "Review the code.",
     };
-    const prompt = (option && reviewPrompts[option]) || reviewPrompts.commit;
+    const prompt = (option && reviewPrompts[option]) || reviewPrompts.uncommitted;
+    debug("review", `Claude path: noWait=${!wait}, timeoutMs=${timeoutMs}`);
     return cmdAsk(agent, session, prompt, { noWait: !wait, yolo, timeoutMs });
   }
 
@@ -4467,21 +4708,55 @@ async function cmdReview(
     ? /** @type {string} */ (session)
     : await cmdStart(agent, session, { yolo });
 
+  debug("review", `Codex path: sending /review command`);
   tmuxSendLiteral(activeSession, "/review");
   await sleep(50);
   tmuxSend(activeSession, "Enter");
 
+  debug("review", `waiting for review menu`);
   await waitFor(activeSession, (s) => s.includes("Select a review preset") || s.includes("review"));
 
   if (option) {
     const key = agent.reviewOptions[option] || option;
+    debug("review", `selecting option=${option} (key=${key})`);
     tmuxSend(activeSession, key);
 
     if (option === "custom" && customInstructions) {
+      debug("review", `waiting for custom instructions prompt`);
       await waitFor(activeSession, (s) => s.includes("custom") || s.includes("instructions"));
       tmuxSendLiteral(activeSession, customInstructions);
       await sleep(50);
       tmuxSend(activeSession, "Enter");
+    } else if (option === "branch") {
+      debug("review", `waiting for branch picker`);
+      await waitFor(activeSession, (s) => !s.includes("Select a review preset"));
+      await sleep(200);
+      if (customInstructions) {
+        debug("review", `typing branch filter: ${customInstructions}`);
+        tmuxSendLiteral(activeSession, customInstructions);
+        await sleep(100);
+      }
+      tmuxSend(activeSession, "Enter");
+    } else if (option === "commit") {
+      debug("review", `waiting for commit picker`);
+      await waitFor(activeSession, (s) => !s.includes("Select a review preset"));
+      await sleep(200);
+      if (customInstructions) {
+        // Codex commit picker shows messages, not hashes - resolve ref to message
+        let searchTerm = customInstructions;
+        const gitResult = spawnSync("git", ["log", "--format=%s", "-n", "1", customInstructions], {
+          encoding: "utf-8",
+        });
+        if (gitResult.status === 0 && gitResult.stdout.trim()) {
+          // Use first few words of commit message for search
+          searchTerm = gitResult.stdout.trim().slice(0, 40);
+          debug("review", `resolved commit ${customInstructions} -> "${searchTerm}"`);
+        }
+        debug("review", `typing commit filter: ${searchTerm}`);
+        tmuxSendLiteral(activeSession, searchTerm);
+        await sleep(100);
+      }
+      tmuxSend(activeSession, "Enter");
     }
   }
 
@@ -4772,7 +5047,7 @@ Usage: ${name} [OPTIONS] <command|message> [ARGS...]
 
 Messaging:
   <message>                 Send message to ${name}
-  review [TYPE]             Review code: pr, uncommitted, commit, custom
+  review [TYPE] [TARGET]    Review code: uncommitted, branch [base], commit [ref], custom
 
 Sessions:
   compact                   Summarise session to shrink context size
@@ -4815,6 +5090,8 @@ Examples:
   ${name} "FYI: auth was refactored" --no-wait          # Send context to a working session (no response needed)
   ${name} --auto-approve='Bash("cargo *")' "run tests"  # Session with specific permissions
   ${name} review uncommitted --wait
+  ${name} review branch main                            # Review changes vs main branch
+  ${name} review commit HEAD~1                          # Review specific commit
   ${name} kill                                          # Kill agents in current project
   ${name} kill --all                                    # Kill all agents across all projects
   ${name} kill --session=NAME                           # Kill specific session
@@ -4952,9 +5229,9 @@ async function main() {
   if (cmd === "review") {
     const customInstructions = await readStdinIfNeeded(positionals[2]);
     return cmdReview(agent, session, positionals[1], customInstructions ?? undefined, {
-      wait,
+      wait: !noWait,
       fresh,
-      timeoutMs,
+      timeoutMs: flags.timeout !== undefined ? timeoutMs : REVIEW_TIMEOUT_MS,
     });
   }
   if (cmd === "status") return cmdStatus(agent, session);
@@ -5039,4 +5316,8 @@ export {
   State,
   normalizeAllowedTools,
   computePermissionHash,
+  formatClaudeLogEntry,
+  formatCodexLogEntry,
+  CodexAgent,
+  ClaudeAgent,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ax-agents",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "A CLI for orchestrating AI coding agents via tmux",
   "bin": {
     "ax": "ax.js",