ax-agents 0.0.1-alpha.6 → 0.0.1-alpha.8

package/ax.js

@@ -23,11 +23,15 @@ import {
   renameSync,
   realpathSync,
   watch,
+  openSync,
+  readSync,
+  closeSync,
 } from "node:fs";
-import { randomUUID } from "node:crypto";
+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";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -301,6 +305,33 @@ const TRUNCATE_THINKING_LEN = 300;
 const ARCHANGEL_GIT_CONTEXT_HOURS = 4;
 const ARCHANGEL_GIT_CONTEXT_MAX_LINES = 200;
 const ARCHANGEL_PARENT_CONTEXT_ENTRIES = 10;
+const ARCHANGEL_PREAMBLE = `## Guidelines
+
+- Investigate before speaking. If uncertain, read more code and trace the logic until you're confident.
+- Explain WHY something is an issue, not just that it is.
+- Focus on your area of expertise.
+- Calibrate to the task or plan. Don't suggest refactors during a bug fix.
+- Be clear. Brief is fine, but never sacrifice clarity.
+- For critical issues, request for them to be added to the todo list.
+- Don't repeat observations you've already made unless you have more to say or better clarity.
+- Make judgment calls - don't ask questions.
+
+"No issues found." is a valid response when there's nothing significant to report.`;
+
+/**
+ * @param {string} session
+ * @param {(screen: string) => boolean} predicate
+ * @param {number} [timeoutMs]
+ * @returns {Promise<string>}
+ */
+class TimeoutError extends Error {
+  /** @param {string} [session] */
+  constructor(session) {
+    super("timeout");
+    this.name = "TimeoutError";
+    this.session = session;
+  }
+}
 
 /**
  * @param {string} session
@@ -315,7 +346,7 @@ async function waitFor(session, predicate, timeoutMs = STARTUP_TIMEOUT_MS) {
     if (predicate(screen)) return screen;
     await sleep(POLL_MS);
   }
-  throw new Error("timeout");
+  throw new TimeoutError(session);
 }
 
 // =============================================================================
@@ -343,6 +374,38 @@ function findCallerPid() {
   return null;
 }
 
+/**
+ * Find orphaned claude/codex processes (PPID=1, reparented to init/launchd)
+ * @returns {{pid: string, command: string}[]}
+ */
+function findOrphanedProcesses() {
+  const result = spawnSync("ps", ["-eo", "pid=,ppid=,args="], { encoding: "utf-8" });
+
+  if (result.status !== 0 || !result.stdout.trim()) {
+    return [];
+  }
+
+  const orphans = [];
+  for (const line of result.stdout.trim().split("\n")) {
+    // Parse: "  PID  PPID  command args..."
+    const match = line.match(/^\s*(\d+)\s+(\d+)\s+(.+)$/);
+    if (!match) continue;
+
+    const [, pid, ppid, args] = match;
+
+    // Must have PPID=1 (orphaned/reparented to init)
+    if (ppid !== "1") continue;
+
+    // Command must START with claude or codex (excludes tmux which also has PPID=1)
+    const cmd = args.split(/\s+/)[0];
+    if (cmd !== "claude" && cmd !== "codex") continue;
+
+    orphans.push({ pid, command: args.slice(0, 60) });
+  }
+
+  return orphans;
+}
+
 // =============================================================================
 // Helpers - stdin
 // =============================================================================
@@ -371,6 +434,86 @@ async function readStdin() {
 }
 
 // =============================================================================
+// =============================================================================
+// Helpers - CLI argument parsing
+// =============================================================================
+
+/**
+ * Parse CLI arguments using Node.js built-in parseArgs.
+ * @param {string[]} args - Command line arguments (without node and script path)
+ * @returns {{ flags: ParsedFlags, positionals: string[] }}
+ *
+ * @typedef {Object} ParsedFlags
+ * @property {boolean} wait
+ * @property {boolean} noWait
+ * @property {boolean} yolo
+ * @property {boolean} fresh
+ * @property {boolean} reasoning
+ * @property {boolean} follow
+ * @property {boolean} all
+ * @property {boolean} orphans
+ * @property {boolean} force
+ * @property {boolean} version
+ * @property {boolean} help
+ * @property {string} [tool]
+ * @property {string} [session]
+ * @property {number} [timeout]
+ * @property {number} [tail]
+ * @property {number} [limit]
+ * @property {string} [branch]
+ */
+function parseCliArgs(args) {
+  const { values, positionals } = parseArgs({
+    args,
+    options: {
+      // Boolean flags
+      wait: { type: "boolean", default: false },
+      "no-wait": { type: "boolean", default: false },
+      yolo: { type: "boolean", default: false },
+      fresh: { type: "boolean", default: false },
+      reasoning: { type: "boolean", default: false },
+      follow: { type: "boolean", short: "f", default: false },
+      all: { type: "boolean", default: false },
+      orphans: { type: "boolean", default: false },
+      force: { type: "boolean", default: false },
+      version: { type: "boolean", short: "V", default: false },
+      help: { type: "boolean", short: "h", default: false },
+      // Value flags
+      tool: { type: "string" },
+      session: { type: "string" },
+      timeout: { type: "string" },
+      tail: { type: "string" },
+      limit: { type: "string" },
+      branch: { type: "string" },
+    },
+    allowPositionals: true,
+    strict: false, // Don't error on unknown flags
+  });
+
+  return {
+    flags: {
+      wait: Boolean(values.wait),
+      noWait: Boolean(values["no-wait"]),
+      yolo: Boolean(values.yolo),
+      fresh: Boolean(values.fresh),
+      reasoning: Boolean(values.reasoning),
+      follow: Boolean(values.follow),
+      all: Boolean(values.all),
+      orphans: Boolean(values.orphans),
+      force: Boolean(values.force),
+      version: Boolean(values.version),
+      help: Boolean(values.help),
+      tool: /** @type {string | undefined} */ (values.tool),
+      session: /** @type {string | undefined} */ (values.session),
+      timeout: values.timeout !== undefined ? Number(values.timeout) : undefined,
+      tail: values.tail !== undefined ? Number(values.tail) : undefined,
+      limit: values.limit !== undefined ? Number(values.limit) : undefined,
+      branch: /** @type {string | undefined} */ (values.branch),
+    },
+    positionals,
+  };
+}
+
 // Helpers - session tracking
 // =============================================================================
 
@@ -413,6 +556,16 @@ function generateSessionName(tool) {
   return `${tool}-partner-${randomUUID()}`;
 }
 
+/**
+ * Quick hash for change detection (not cryptographic).
+ * @param {string | null | undefined} str
+ * @returns {string | null}
+ */
+function quickHash(str) {
+  if (!str) return null;
+  return createHash("md5").update(str).digest("hex").slice(0, 8);
+}
+
 /**
  * @param {string} cwd
  * @returns {string}
@@ -540,6 +693,93 @@ function findCodexLogPath(sessionName) {
   }
 }
 
+/**
+ * @typedef {Object} SessionMeta
+ * @property {string | null} slug - Plan identifier (if plan is active)
+ * @property {Array<{content: string, status: string, id?: string}> | null} todos - Current todos
+ * @property {string | null} permissionMode - "default", "acceptEdits", "plan"
+ * @property {string | null} gitBranch - Current git branch
+ * @property {string | null} cwd - Working directory
+ */
+
+/**
+ * Get metadata from a Claude session's JSONL file.
+ * Returns null for Codex sessions (different format, no equivalent metadata).
+ * @param {string} sessionName - The tmux session name
+ * @returns {SessionMeta | null}
+ */
+function getSessionMeta(sessionName) {
+  const parsed = parseSessionName(sessionName);
+  if (!parsed) return null;
+
+  // Only Claude sessions have this metadata
+  if (parsed.tool !== "claude") return null;
+  if (!parsed.uuid) return null;
+
+  const logPath = findClaudeLogPath(parsed.uuid, sessionName);
+  if (!logPath || !existsSync(logPath)) return null;
+
+  try {
+    const content = readFileSync(logPath, "utf-8");
+    const lines = content.trim().split("\n").filter(Boolean);
+
+    // Read from end to find most recent entry with metadata
+    for (let i = lines.length - 1; i >= 0; i--) {
+      try {
+        const entry = JSON.parse(lines[i]);
+        // User entries typically have the metadata fields
+        if (entry.type === "user" || entry.slug || entry.gitBranch) {
+          return {
+            slug: entry.slug || null,
+            todos: entry.todos || null,
+            permissionMode: entry.permissionMode || null,
+            gitBranch: entry.gitBranch || null,
+            cwd: entry.cwd || null,
+          };
+        }
+      } catch {
+        // Skip malformed lines
+      }
+    }
+    return null;
+  } catch (err) {
+    debugError("getSessionMeta", err);
+    return null;
+  }
+}
+
+/**
+ * Read a plan file by its slug.
+ * @param {string} slug - The plan slug (e.g., "curious-roaming-pascal")
+ * @returns {string | null} The plan content or null if not found
+ */
+function readPlanFile(slug) {
+  const planPath = path.join(CLAUDE_CONFIG_DIR, "plans", `${slug}.md`);
+  try {
+    if (existsSync(planPath)) {
+      return readFileSync(planPath, "utf-8");
+    }
+  } catch (err) {
+    debugError("readPlanFile", err);
+  }
+  return null;
+}
+
+/**
+ * Format todos for display in a prompt.
+ * @param {Array<{content: string, status: string, id?: string}>} todos
+ * @returns {string}
+ */
+function formatTodos(todos) {
+  if (!todos || todos.length === 0) return "";
+  return todos
+    .map((t) => {
+      const status = t.status === "completed" ? "[x]" : t.status === "in_progress" ? "[>]" : "[ ]";
+      return `${status} ${t.content || "(no content)"}`;
+    })
+    .join("\n");
+}
+
 /**
  * Extract assistant text responses from a JSONL log file.
  * This provides clean text without screen-scraped artifacts.
@@ -585,6 +825,130 @@ function getAssistantText(logPath, index = 0) {
   }
 }
 
+/**
+ * Read new complete JSON lines from a log file since the given offset.
+ * @param {string | null} logPath
+ * @param {number} fromOffset
+ * @returns {{ entries: object[], newOffset: number }}
+ */
+function tailJsonl(logPath, fromOffset) {
+  if (!logPath || !existsSync(logPath)) {
+    return { entries: [], newOffset: fromOffset };
+  }
+
+  const stats = statSync(logPath);
+  if (stats.size <= fromOffset) {
+    return { entries: [], newOffset: fromOffset };
+  }
+
+  const fd = openSync(logPath, "r");
+  const buffer = Buffer.alloc(stats.size - fromOffset);
+  readSync(fd, buffer, 0, buffer.length, fromOffset);
+  closeSync(fd);
+
+  const text = buffer.toString("utf-8");
+  const lines = text.split("\n");
+
+  // Last line may be incomplete - don't parse it yet
+  const complete = lines.slice(0, -1).filter(Boolean);
+  const incomplete = lines[lines.length - 1];
+
+  const entries = [];
+  for (const line of complete) {
+    try {
+      entries.push(JSON.parse(line));
+    } catch {
+      // Skip malformed lines
+    }
+  }
+
+  // Offset advances by complete lines only
+  const newOffset = fromOffset + text.length - incomplete.length;
+  return { entries, newOffset };
+}
+
+/**
+ * @typedef {{command?: string, file_path?: string, path?: string, pattern?: string}} ToolInput
+ */
+
+/**
+ * Format a JSONL entry for streaming display.
+ * @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) {
+  // Skip tool_result entries (they can be very verbose)
+  if (entry.type === "tool_result") return null;
+
+  // Only process assistant entries
+  if (entry.type !== "assistant") return null;
+
+  const parts = entry.message?.content || [];
+  const output = [];
+
+  for (const part of parts) {
+    if (part.type === "text" && part.text) {
+      output.push(part.text);
+    } 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 {
+        const target = input.file_path || input.path || input.pattern || "";
+        summary = target.split("/").pop() || target.slice(0, 30);
+      }
+      output.push(`> ${name}(${summary})`);
+    }
+    // Skip thinking blocks - internal reasoning
+  }
+
+  return output.length > 0 ? output.join("\n") : null;
+}
+
+/**
+ * Extract pending tool from confirmation screen.
+ * @param {string} screen
+ * @returns {string | null}
+ */
+function extractPendingToolFromScreen(screen) {
+  const lines = screen.split("\n");
+
+  // Check recent lines for tool confirmation patterns
+  for (let i = lines.length - 1; i >= Math.max(0, lines.length - 15); i--) {
+    const line = lines[i];
+    // Match tool confirmation patterns like "Bash: command" or "Write: /path/file"
+    const match = line.match(
+      /^\s*(Bash|Write|Edit|Read|Glob|Grep|Task|WebFetch|WebSearch|NotebookEdit|Skill|TodoWrite|TodoRead):\s*(.{1,40})/,
+    );
+    if (match) {
+      return `${match[1]}: ${match[2].trim()}`;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Format confirmation output with helpful commands
+ * @param {string} screen
+ * @param {Agent} _agent
+ * @returns {string}
+ */
+function formatConfirmationOutput(screen, _agent) {
+  const pendingTool = extractPendingToolFromScreen(screen);
+  const cli = path.basename(process.argv[1], ".js");
+
+  let output = pendingTool || "Confirmation required";
+  output += "\n\ne.g.";
+  output += `\n  ${cli} approve        # for y/n prompts`;
+  output += `\n  ${cli} reject`;
+  output += `\n  ${cli} select N       # for numbered menus`;
+
+  return output;
+}
+
 /**
  * @returns {string[]}
  */
@@ -1457,7 +1821,7 @@ const State = {
  * @param {string} config.promptSymbol - Symbol indicating ready state
  * @param {string[]} [config.spinners] - Spinner characters indicating thinking
  * @param {RegExp} [config.rateLimitPattern] - Pattern for rate limit detection
- * @param {string[]} [config.thinkingPatterns] - Text patterns indicating thinking
+ * @param {(string | RegExp | ((lines: string) => boolean))[]} [config.thinkingPatterns] - Text patterns indicating thinking
  * @param {(string | ((lines: string) => boolean))[]} [config.confirmPatterns] - Patterns for confirmation dialogs
  * @param {{screen: string[], lastLines: string[]} | null} [config.updatePromptPatterns] - Patterns for update prompts
  * @returns {string} The detected state
@@ -1470,19 +1834,38 @@ function detectState(screen, config) {
   // Larger range for confirmation detection (catches dialogs that scrolled slightly)
   const recentLines = lines.slice(-15).join("\n");
 
-  // Rate limited - check full screen (rate limit messages can appear anywhere)
-  if (config.rateLimitPattern && config.rateLimitPattern.test(screen)) {
+  // Rate limited - check recent lines (not full screen to avoid matching historical output)
+  if (config.rateLimitPattern && config.rateLimitPattern.test(recentLines)) {
     return State.RATE_LIMITED;
   }
 
-  // Thinking - spinners (full screen, they're unique UI elements)
+  // Confirming - check before THINKING because "Running…" in tool output matches thinking patterns
+  const confirmPatterns = config.confirmPatterns || [];
+  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;
+    } else {
+      // String patterns check recentLines (bounded range)
+      if (recentLines.includes(pattern)) return State.CONFIRMING;
+    }
+  }
+
+  // Thinking - spinners (check last lines only to avoid false positives from timing messages like "✻ Crunched for 32s")
   const spinners = config.spinners || [];
-  if (spinners.some((s) => screen.includes(s))) {
+  if (spinners.some((s) => lastLines.includes(s))) {
     return State.THINKING;
   }
-  // Thinking - text patterns (last lines)
+  // Thinking - text patterns (last lines) - supports strings, regexes, and functions
   const thinkingPatterns = config.thinkingPatterns || [];
-  if (thinkingPatterns.some((p) => lastLines.includes(p))) {
+  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;
   }
 
@@ -1494,19 +1877,6 @@ function detectState(screen, config) {
     }
   }
 
-  // Confirming - check recent lines (not full screen to avoid history false positives)
-  const confirmPatterns = config.confirmPatterns || [];
-  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;
-    } else {
-      // String patterns check recentLines (bounded range)
-      if (recentLines.includes(pattern)) return State.CONFIRMING;
-    }
-  }
-
   // Ready - only if prompt symbol is visible AND not followed by pasted content
   // "[Pasted text" indicates user has pasted content and Claude is still processing
   if (lastLines.includes(config.promptSymbol)) {
@@ -1541,12 +1911,13 @@ function detectState(screen, config) {
 /**
  * @typedef {Object} AgentConfigInput
  * @property {string} name
+ * @property {string} displayName
  * @property {string} startCommand
  * @property {string} yoloCommand
  * @property {string} promptSymbol
  * @property {string[]} [spinners]
  * @property {RegExp} [rateLimitPattern]
- * @property {string[]} [thinkingPatterns]
+ * @property {(string | RegExp | ((lines: string) => boolean))[]} [thinkingPatterns]
  * @property {ConfirmPattern[]} [confirmPatterns]
  * @property {UpdatePromptPatterns | null} [updatePromptPatterns]
  * @property {string[]} [responseMarkers]
@@ -1556,6 +1927,8 @@ function detectState(screen, config) {
  * @property {string} [approveKey]
  * @property {string} [rejectKey]
  * @property {string} [safeAllowedTools]
+ * @property {string | null} [sessionIdFlag]
+ * @property {((sessionName: string) => string | null) | null} [logPathFinder]
  */
 
 class Agent {
@@ -1566,6 +1939,8 @@ class Agent {
     /** @type {string} */
     this.name = config.name;
     /** @type {string} */
+    this.displayName = config.displayName;
+    /** @type {string} */
     this.startCommand = config.startCommand;
     /** @type {string} */
     this.yoloCommand = config.yoloCommand;
@@ -1575,7 +1950,7 @@ class Agent {
     this.spinners = config.spinners || [];
     /** @type {RegExp | undefined} */
     this.rateLimitPattern = config.rateLimitPattern;
-    /** @type {string[]} */
+    /** @type {(string | RegExp | ((lines: string) => boolean))[]} */
     this.thinkingPatterns = config.thinkingPatterns || [];
     /** @type {ConfirmPattern[]} */
     this.confirmPatterns = config.confirmPatterns || [];
@@ -1595,6 +1970,10 @@ class Agent {
     this.rejectKey = config.rejectKey || "n";
     /** @type {string | undefined} */
     this.safeAllowedTools = config.safeAllowedTools;
+    /** @type {string | null} */
+    this.sessionIdFlag = config.sessionIdFlag || null;
+    /** @type {((sessionName: string) => string | null) | null} */
+    this.logPathFinder = config.logPathFinder || null;
   }
 
   /**
@@ -1612,11 +1991,11 @@ class Agent {
     } else {
       base = this.startCommand;
     }
-    // Claude supports --session-id for deterministic session tracking
-    if (this.name === "claude" && sessionName) {
+    // Some agents support session ID flags for deterministic session tracking
+    if (this.sessionIdFlag && sessionName) {
       const parsed = parseSessionName(sessionName);
       if (parsed?.uuid) {
-        return `${base} --session-id ${parsed.uuid}`;
+        return `${base} ${this.sessionIdFlag} ${parsed.uuid}`;
       }
     }
     return base;
@@ -1674,13 +2053,8 @@ class Agent {
    * @returns {string | null}
    */
   findLogPath(sessionName) {
-    const parsed = parseSessionName(sessionName);
-    if (this.name === "claude") {
-      const uuid = parsed?.uuid;
-      if (uuid) return findClaudeLogPath(uuid, sessionName);
-    }
-    if (this.name === "codex") {
-      return findCodexLogPath(sessionName);
+    if (this.logPathFinder) {
+      return this.logPathFinder(sessionName);
     }
     return null;
   }
@@ -1908,6 +2282,7 @@ class Agent {
 
 const CodexAgent = new Agent({
   name: "codex",
+  displayName: "Codex",
   startCommand: "codex --sandbox read-only",
   yoloCommand: "codex --dangerously-bypass-approvals-and-sandbox",
   promptSymbol: "›",
@@ -1927,6 +2302,7 @@ const CodexAgent = new Agent({
   chromePatterns: ["context left", "for shortcuts"],
   reviewOptions: { pr: "1", uncommitted: "2", commit: "3", custom: "4" },
   envVar: "AX_SESSION",
+  logPathFinder: findCodexLogPath,
 });
 
 // =============================================================================
@@ -1935,12 +2311,15 @@ const CodexAgent = new Agent({
 
 const ClaudeAgent = new Agent({
   name: "claude",
+  displayName: "Claude",
   startCommand: "claude",
   yoloCommand: "claude --dangerously-skip-permissions",
   promptSymbol: "❯",
-  spinners: ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"],
+  // Claude Code spinners: ·✢✳✶✻✽ (from cli.js source)
+  spinners: ["·", "✢", "✳", "✶", "✻", "✽"],
   rateLimitPattern: /rate.?limit/i,
-  thinkingPatterns: ["Thinking"],
+  // Claude uses whimsical verbs like "Wibbling…", "Dancing…", etc. Match any capitalized -ing word + ellipsis (… or ...)
+  thinkingPatterns: ["Thinking", /[A-Z][a-z]+ing(…|\.\.\.)/],
   confirmPatterns: [
     "Do you want to make this edit",
     "Do you want to run this command",
@@ -1965,6 +2344,13 @@ const ClaudeAgent = new Agent({
   envVar: "AX_SESSION",
   approveKey: "1",
   rejectKey: "Escape",
+  sessionIdFlag: "--session-id",
+  logPathFinder: (sessionName) => {
+    const parsed = parseSessionName(sessionName);
+    const uuid = parsed?.uuid;
+    if (uuid) return findClaudeLogPath(uuid, sessionName);
+    return null;
+  },
 });
 
 // =============================================================================
@@ -2002,30 +2388,38 @@ async function waitUntilReady(agent, session, timeoutMs = DEFAULT_TIMEOUT_MS) {
       return { state, screen };
     }
   }
-  throw new Error("timeout");
+  throw new TimeoutError(session);
 }
 
 /**
- * Wait for agent to process a new message and respond.
- * Waits for screen activity before considering the response complete.
+ * Core polling loop for waiting on agent responses.
  * @param {Agent} agent
  * @param {string} session
- * @param {number} [timeoutMs]
+ * @param {number} timeoutMs
+ * @param {{onPoll?: (screen: string, state: string) => void, onStateChange?: (state: string, lastState: string | null, screen: string) => void, onReady?: (screen: string) => void}} [hooks]
  * @returns {Promise<{state: string, screen: string}>}
  */
-async function waitForResponse(agent, session, timeoutMs = DEFAULT_TIMEOUT_MS) {
+async function pollForResponse(agent, session, timeoutMs, hooks = {}) {
+  const { onPoll, onStateChange, onReady } = hooks;
   const start = Date.now();
   const initialScreen = tmuxCapture(session);
 
   let lastScreen = initialScreen;
+  let lastState = null;
   let stableAt = null;
   let sawActivity = false;
 
   while (Date.now() - start < timeoutMs) {
-    await sleep(POLL_MS);
     const screen = tmuxCapture(session);
     const state = agent.getState(screen);
 
+    if (onPoll) onPoll(screen, state);
+
+    if (state !== lastState) {
+      if (onStateChange) onStateChange(state, lastState, screen);
+      lastState = state;
+    }
+
     if (state === State.RATE_LIMITED || state === State.CONFIRMING) {
       return { state, screen };
     }
@@ -2040,6 +2434,7 @@ async function waitForResponse(agent, session, timeoutMs = DEFAULT_TIMEOUT_MS) {
 
     if (sawActivity && stableAt && Date.now() - stableAt >= STABLE_MS) {
       if (state === State.READY) {
+        if (onReady) onReady(screen);
         return { state, screen };
       }
     }
@@ -2047,26 +2442,86 @@ async function waitForResponse(agent, session, timeoutMs = DEFAULT_TIMEOUT_MS) {
     if (state === State.THINKING) {
       sawActivity = true;
     }
+
+    await sleep(POLL_MS);
   }
-  throw new Error("timeout");
+  throw new TimeoutError(session);
 }
 
 /**
- * Auto-approve loop that keeps approving confirmations until the agent is ready or rate limited.
- * Used by callers to implement yolo mode on sessions not started with native --yolo.
+ * Wait for agent response without streaming output.
  * @param {Agent} agent
  * @param {string} session
  * @param {number} [timeoutMs]
  * @returns {Promise<{state: string, screen: string}>}
  */
-async function autoApproveLoop(agent, session, timeoutMs = DEFAULT_TIMEOUT_MS) {
+async function waitForResponse(agent, session, timeoutMs = DEFAULT_TIMEOUT_MS) {
+  return pollForResponse(agent, session, timeoutMs);
+}
+
+/**
+ * Wait for agent response with streaming output to console.
+ * @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;
+  let printedThinking = false;
+
+  const streamNewEntries = () => {
+    if (!logPath) {
+      logPath = agent.findLogPath(session);
+      if (logPath && existsSync(logPath)) {
+        logOffset = statSync(logPath).size;
+      }
+    }
+    if (logPath) {
+      const { entries, newOffset } = tailJsonl(logPath, logOffset);
+      logOffset = newOffset;
+      for (const entry of entries) {
+        const formatted = formatEntry(entry);
+        if (formatted) console.log(formatted);
+      }
+    }
+  };
+
+  return pollForResponse(agent, session, timeoutMs, {
+    onPoll: () => streamNewEntries(),
+    onStateChange: (state, lastState, screen) => {
+      if (state === State.THINKING && !printedThinking) {
+        console.log("[THINKING]");
+        printedThinking = true;
+      } else if (state === State.CONFIRMING) {
+        const pendingTool = extractPendingToolFromScreen(screen);
+        console.log(pendingTool ? `[CONFIRMING] ${pendingTool}` : "[CONFIRMING]");
+      }
+      if (lastState === State.THINKING && state !== State.THINKING) {
+        printedThinking = false;
+      }
+    },
+    onReady: () => streamNewEntries(),
+  });
+}
+
+/**
+ * Auto-approve loop that keeps approving confirmations until the agent is ready or rate limited.
+ * @param {Agent} agent
+ * @param {string} session
+ * @param {number} timeoutMs
+ * @param {Function} waitFn - waitForResponse or streamResponse
+ * @returns {Promise<{state: string, screen: string}>}
+ */
+async function autoApproveLoop(agent, session, timeoutMs, waitFn) {
   const deadline = Date.now() + timeoutMs;
 
   while (Date.now() < deadline) {
     const remaining = deadline - Date.now();
     if (remaining <= 0) break;
 
-    const { state, screen } = await waitForResponse(agent, session, remaining);
+    const { state, screen } = await waitFn(agent, session, remaining);
 
     if (state === State.RATE_LIMITED || state === State.READY) {
       return { state, screen };
@@ -2078,11 +2533,10 @@ async function autoApproveLoop(agent, session, timeoutMs = DEFAULT_TIMEOUT_MS) {
       continue;
     }
 
-    // Unexpected state - log and continue polling
     debugError("autoApproveLoop", new Error(`unexpected state: ${state}`));
   }
 
-  throw new Error("timeout");
+  throw new TimeoutError(session);
 }
 
 /**
@@ -2141,41 +2595,73 @@ function cmdAgents() {
 
   if (agentSessions.length === 0) {
     console.log("No agents running");
+    // Still check for orphans
+    const orphans = findOrphanedProcesses();
+    if (orphans.length > 0) {
+      console.log(`\nOrphaned (${orphans.length}):`);
+      for (const { pid, command } of orphans) {
+        console.log(`  PID ${pid}: ${command}`);
+      }
+      console.log(`\n  Run 'ax kill --orphans' to clean up`);
+    }
     return;
   }
 
+  // Get default session for each agent type
+  const claudeDefault = ClaudeAgent.getDefaultSession();
+  const codexDefault = CodexAgent.getDefaultSession();
+
   // Get info for each agent
   const agents = agentSessions.map((session) => {
     const parsed = /** @type {ParsedSession} */ (parseSessionName(session));
     const agent = parsed.tool === "claude" ? ClaudeAgent : CodexAgent;
     const screen = tmuxCapture(session);
     const state = agent.getState(screen);
-    const logPath = agent.findLogPath(session);
     const type = parsed.archangelName ? "archangel" : "-";
+    const isDefault =
+      (parsed.tool === "claude" && session === claudeDefault) ||
+      (parsed.tool === "codex" && session === codexDefault);
+
+    // Get session metadata (Claude only)
+    const meta = getSessionMeta(session);
 
     return {
       session,
       tool: parsed.tool,
       state: state || "unknown",
+      target: isDefault ? "*" : "",
       type,
-      log: logPath || "-",
+      plan: meta?.slug || "-",
+      branch: meta?.gitBranch || "-",
     };
   });
 
-  // Print table
+  // Print sessions table
   const maxSession = Math.max(7, ...agents.map((a) => a.session.length));
   const maxTool = Math.max(4, ...agents.map((a) => a.tool.length));
   const maxState = Math.max(5, ...agents.map((a) => a.state.length));
+  const maxTarget = Math.max(6, ...agents.map((a) => a.target.length));
   const maxType = Math.max(4, ...agents.map((a) => a.type.length));
+  const maxPlan = Math.max(4, ...agents.map((a) => a.plan.length));
 
   console.log(
-    `${"SESSION".padEnd(maxSession)}  ${"TOOL".padEnd(maxTool)}  ${"STATE".padEnd(maxState)}  ${"TYPE".padEnd(maxType)}  LOG`,
+    `${"SESSION".padEnd(maxSession)}  ${"TOOL".padEnd(maxTool)}  ${"STATE".padEnd(maxState)}  ${"TARGET".padEnd(maxTarget)}  ${"TYPE".padEnd(maxType)}  ${"PLAN".padEnd(maxPlan)}  BRANCH`,
   );
   for (const a of agents) {
     console.log(
-      `${a.session.padEnd(maxSession)}  ${a.tool.padEnd(maxTool)}  ${a.state.padEnd(maxState)}  ${a.type.padEnd(maxType)}  ${a.log}`,
+      `${a.session.padEnd(maxSession)}  ${a.tool.padEnd(maxTool)}  ${a.state.padEnd(maxState)}  ${a.target.padEnd(maxTarget)}  ${a.type.padEnd(maxType)}  ${a.plan.padEnd(maxPlan)}  ${a.branch}`,
     );
   }
+
+  // Print orphaned processes if any
+  const orphans = findOrphanedProcesses();
+  if (orphans.length > 0) {
+    console.log(`\nOrphaned (${orphans.length}):`);
+    for (const { pid, command } of orphans) {
+      console.log(`  PID ${pid}: ${command}`);
+    }
+    console.log(`\n  Run 'ax kill --orphans' to clean up`);
+  }
 }
 
 // =============================================================================
@@ -2312,6 +2798,13 @@ async function cmdArchangel(agentName) {
   let isProcessing = false;
   const intervalMs = config.interval * 1000;
 
+  // Hash tracking for incremental context updates
+  /** @type {string | null} */
+  let lastPlanHash = null;
+  /** @type {string | null} */
+  let lastTodosHash = null;
+  let isFirstTrigger = true;
+
   async function processChanges() {
     clearTimeout(debounceTimer);
     clearTimeout(maxWaitTimer);
@@ -2329,6 +2822,21 @@ async function cmdArchangel(agentName) {
       const parent = findParentSession();
       const logPath = parent ? findClaudeLogPath(parent.uuid, parent.session) : null;
 
+      // Get orientation context (plan and todos) from parent session
+      const meta = parent?.session ? getSessionMeta(parent.session) : null;
+      const planContent = meta?.slug ? readPlanFile(meta.slug) : null;
+      const todosContent = meta?.todos?.length ? formatTodos(meta.todos) : null;
+
+      // Check if plan/todos have changed since last trigger
+      const planHash = quickHash(planContent);
+      const todosHash = quickHash(todosContent);
+      const includePlan = planHash !== lastPlanHash;
+      const includeTodos = todosHash !== lastTodosHash;
+
+      // Update tracking for next trigger
+      lastPlanHash = planHash;
+      lastTodosHash = todosHash;
+
       // Build file-specific context from JSONL
       const fileContexts = [];
       for (const file of files.slice(0, 5)) {
@@ -2340,7 +2848,18 @@ async function cmdArchangel(agentName) {
       }
 
       // Build the prompt
-      let prompt = basePrompt;
+      // First trigger: include intro, guidelines, and focus (archangel has memory)
+      let prompt = isFirstTrigger
+        ? `You are the archangel of ${agentName}.\n\n${ARCHANGEL_PREAMBLE}\n\n## Focus\n\n${basePrompt}\n\n---`
+        : "";
+
+      // Add orientation context (plan and todos) only if changed since last trigger
+      if (includePlan && planContent) {
+        prompt += (prompt ? "\n\n" : "") + "## Current Plan\n\n" + planContent;
+      }
+      if (includeTodos && todosContent) {
+        prompt += (prompt ? "\n\n" : "") + "## Current Todos\n\n" + todosContent;
+      }
 
       if (fileContexts.length > 0) {
         prompt += "\n\n## Recent Edits (from parent session)\n";
@@ -2374,8 +2893,7 @@ async function cmdArchangel(agentName) {
           prompt += "\n\n## Git Context\n\n" + gitContext;
         }
 
-        prompt +=
-          '\n\nReview these changes in the context of what the user is working on. Report any issues found. Keep your response concise.\nIf there are no significant issues, respond with just "No issues found."';
+        prompt += "\n\nReview these changes.";
       } else {
         // Fallback: no JSONL context available, use conversation + git context
         const parentContext = getParentSessionContext(ARCHANGEL_PARENT_CONTEXT_ENTRIES);
@@ -2395,8 +2913,7 @@ async function cmdArchangel(agentName) {
           prompt += "\n\n## Git Context\n\n" + gitContext;
         }
 
-        prompt +=
-          '\n\nReview these changes in the context of what the user is working on. Report any issues found. Keep your response concise.\nIf there are no significant issues, respond with just "No issues found."';
+        prompt += "\n\nReview these changes.";
       }
 
       // Check session still exists
@@ -2425,6 +2942,7 @@ async function cmdArchangel(agentName) {
       await sleep(200); // Allow time for large prompts to be processed
       tmuxSend(sessionName, "Enter");
       await sleep(100); // Ensure Enter is processed
+      isFirstTrigger = false;
 
       // Wait for response
       const { state: endState, screen: afterScreen } = await waitForResponse(
@@ -2838,9 +3356,31 @@ function ensureClaudeHookConfig() {
 
 /**
  * @param {string | null | undefined} session
- * @param {{all?: boolean}} [options]
+ * @param {{all?: boolean, orphans?: boolean, force?: boolean}} [options]
  */
-function cmdKill(session, { all = false } = {}) {
+function cmdKill(session, { all = false, orphans = false, force = false } = {}) {
+  // Handle orphaned processes
+  if (orphans) {
+    const orphanedProcesses = findOrphanedProcesses();
+
+    if (orphanedProcesses.length === 0) {
+      console.log("No orphaned processes found");
+      return;
+    }
+
+    const signal = force ? "-9" : "-15"; // SIGKILL vs SIGTERM
+    let killed = 0;
+    for (const { pid, command } of orphanedProcesses) {
+      const result = spawnSync("kill", [signal, pid]);
+      if (result.status === 0) {
+        console.log(`Killed: PID ${pid} (${command.slice(0, 40)})`);
+        killed++;
+      }
+    }
+    console.log(`Killed ${killed} orphaned process(es)${force ? " (forced)" : ""}`);
+    return;
+  }
+
   // If specific session provided, kill just that one
   if (session) {
     if (!tmuxHasSession(session)) {
@@ -3203,7 +3743,7 @@ function cmdMailbox({ limit = 20, branch = null, all = false } = {}) {
  * @param {string} message
  * @param {{noWait?: boolean, yolo?: boolean, timeoutMs?: number}} [options]
  */
-async function cmdAsk(agent, session, message, { noWait = false, yolo = false, timeoutMs } = {}) {
+async function cmdAsk(agent, session, message, { noWait = false, yolo = false, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
   const sessionExists = session != null && tmuxHasSession(session);
   const nativeYolo = sessionExists && isYoloSession(/** @type {string} */ (session));
 
@@ -3223,14 +3763,23 @@ async function cmdAsk(agent, session, message, { noWait = false, yolo = false, t
   await sleep(50);
   tmuxSend(activeSession, "Enter");
 
-  if (noWait) return;
+  if (noWait) {
+    const parsed = parseSessionName(activeSession);
+    const shortId = parsed?.uuid?.slice(0, 8) || activeSession;
+    const cli = path.basename(process.argv[1], ".js");
+    console.log(`Sent to: ${shortId}
+
+e.g.
+  ${cli} status --session=${shortId}
+  ${cli} output --session=${shortId}`);
+    return;
+  }
 
-  // Yolo mode on a safe session: auto-approve until done
   const useAutoApprove = yolo && !nativeYolo;
 
   const { state, screen } = useAutoApprove
-    ? await autoApproveLoop(agent, activeSession, timeoutMs)
-    : await waitForResponse(agent, activeSession, timeoutMs);
+    ? await autoApproveLoop(agent, activeSession, timeoutMs, streamResponse)
+    : await streamResponse(agent, activeSession, timeoutMs);
 
   if (state === State.RATE_LIMITED) {
     console.log(`RATE_LIMITED: ${agent.parseRetryTime(screen)}`);
@@ -3238,14 +3787,9 @@ async function cmdAsk(agent, session, message, { noWait = false, yolo = false, t
   }
 
   if (state === State.CONFIRMING) {
-    console.log(`CONFIRM: ${agent.parseAction(screen)}`);
+    console.log(`CONFIRM: ${formatConfirmationOutput(screen, agent)}`);
     process.exit(3);
   }
-
-  const output = agent.getResponse(activeSession, screen);
-  if (output) {
-    console.log(output);
-  }
 }
 
 /**
@@ -3260,9 +3804,10 @@ async function cmdApprove(agent, session, { wait = false, timeoutMs } = {}) {
   }
 
   const before = tmuxCapture(session);
-  if (agent.getState(before) !== State.CONFIRMING) {
-    console.log("ERROR: not confirming");
-    process.exit(1);
+  const beforeState = agent.getState(before);
+  if (beforeState !== State.CONFIRMING) {
+    console.log(`Already ${beforeState}`);
+    return;
   }
 
   tmuxSend(session, agent.approveKey);
@@ -3277,7 +3822,7 @@ async function cmdApprove(agent, session, { wait = false, timeoutMs } = {}) {
   }
 
   if (state === State.CONFIRMING) {
-    console.log(`CONFIRM: ${agent.parseAction(screen)}`);
+    console.log(`CONFIRM: ${formatConfirmationOutput(screen, agent)}`);
     process.exit(3);
   }
 
@@ -3296,6 +3841,13 @@ async function cmdReject(agent, session, { wait = false, timeoutMs } = {}) {
     process.exit(1);
   }
 
+  const before = tmuxCapture(session);
+  const beforeState = agent.getState(before);
+  if (beforeState !== State.CONFIRMING) {
+    console.log(`Already ${beforeState}`);
+    return;
+  }
+
   tmuxSend(session, agent.rejectKey);
 
   if (!wait) return;
@@ -3323,7 +3875,7 @@ async function cmdReview(
   session,
   option,
   customInstructions,
-  { wait = true, yolo = true, fresh = false, timeoutMs = REVIEW_TIMEOUT_MS } = {},
+  { wait = true, yolo = false, fresh = false, timeoutMs = REVIEW_TIMEOUT_MS } = {},
 ) {
   const sessionExists = session != null && tmuxHasSession(session);
 
@@ -3390,12 +3942,11 @@ async function cmdReview(
 
   if (!wait) return;
 
-  // Yolo mode on a safe session: auto-approve until done
   const useAutoApprove = yolo && !nativeYolo;
 
   const { state, screen } = useAutoApprove
-    ? await autoApproveLoop(agent, activeSession, timeoutMs)
-    : await waitForResponse(agent, activeSession, timeoutMs);
+    ? await autoApproveLoop(agent, activeSession, timeoutMs, streamResponse)
+    : await streamResponse(agent, activeSession, timeoutMs);
 
   if (state === State.RATE_LIMITED) {
     console.log(`RATE_LIMITED: ${agent.parseRetryTime(screen)}`);
@@ -3403,12 +3954,9 @@ async function cmdReview(
   }
 
   if (state === State.CONFIRMING) {
-    console.log(`CONFIRM: ${agent.parseAction(screen)}`);
+    console.log(`CONFIRM: ${formatConfirmationOutput(screen, agent)}`);
     process.exit(3);
   }
-
-  const response = agent.getResponse(activeSession, screen);
-  console.log(response || "");
 }
 
 /**
@@ -3439,7 +3987,7 @@ async function cmdOutput(agent, session, index = 0, { wait = false, timeoutMs }
   }
 
   if (state === State.CONFIRMING) {
-    console.log(`CONFIRM: ${agent.parseAction(screen)}`);
+    console.log(`CONFIRM: ${formatConfirmationOutput(screen, agent)}`);
     process.exit(3);
   }
 
@@ -3451,6 +3999,8 @@ async function cmdOutput(agent, session, index = 0, { wait = false, timeoutMs }
   const output = agent.getResponse(session, screen, index);
   if (output) {
     console.log(output);
+  } else {
+    console.log("READY_NO_CONTENT");
   }
 }
 
@@ -3473,7 +4023,7 @@ function cmdStatus(agent, session) {
   }
 
   if (state === State.CONFIRMING) {
-    console.log(`CONFIRM: ${agent.parseAction(screen)}`);
+    console.log(`CONFIRM: ${formatConfirmationOutput(screen, agent)}`);
     process.exit(3);
   }
 
@@ -3481,6 +4031,10 @@ function cmdStatus(agent, session) {
     console.log("THINKING");
     process.exit(4);
   }
+
+  // READY (or STARTING/UPDATE_PROMPT which are transient)
+  console.log("READY");
+  process.exit(0);
 }
 
 /**
@@ -3594,7 +4148,7 @@ async function cmdSelect(agent, session, n, { wait = false, timeoutMs } = {}) {
   }
 
   if (state === State.CONFIRMING) {
-    console.log(`CONFIRM: ${agent.parseAction(screen)}`);
+    console.log(`CONFIRM: ${formatConfirmationOutput(screen, agent)}`);
     process.exit(3);
   }
 
@@ -3629,19 +4183,22 @@ function getAgentFromInvocation() {
  */
 function printHelp(agent, cliName) {
   const name = cliName;
-  const backendName = agent.name === "codex" ? "Codex" : "Claude";
+  const backendName = agent.displayName;
   const hasReview = !!agent.reviewOptions;
 
   console.log(`${name} v${VERSION} - agentic assistant CLI (${backendName})
 
+Usage: ${name} [OPTIONS] <command|message> [ARGS...]
+
 Commands:
   agents                    List all running agents with state and log paths
+  target                    Show default target session for current tool
   attach [SESSION]          Attach to agent session interactively
   log SESSION               View conversation log (--tail=N, --follow, --reasoning)
   mailbox                   View archangel observations (--limit=N, --branch=X, --all)
   summon [name]             Summon archangels (all, or by name)
   recall [name]             Recall archangels (all, or by name)
-  kill                      Kill sessions in current project (--all for all, --session=NAME for one)
+  kill                      Kill sessions (--all, --session=NAME, --orphans [--force])
   status                    Check state (exit: 0=ready, 2=rate_limited, 3=confirming, 4=thinking)
   output [-N]               Show response (0=last, -1=prev, -2=older)
   debug                     Show raw screen output and detected state${
@@ -3661,11 +4218,13 @@ Commands:
 Flags:
   --tool=NAME               Use specific agent (codex, claude)
   --session=NAME            Target session by name, archangel name, or UUID prefix (self = current)
-  --wait                    Wait for response (for review, approve, etc)
-  --no-wait                 Don't wait (for messages, which wait by default)
-  --timeout=N               Set timeout in seconds (default: 120)
+  --wait                    Wait for response (default for messages; required for approve/reject)
+  --no-wait                 Fire-and-forget: send message, print session ID, exit immediately
+  --timeout=N               Set timeout in seconds (default: ${DEFAULT_TIMEOUT_MS / 1000}, reviews: ${REVIEW_TIMEOUT_MS / 1000})
   --yolo                    Skip all confirmations (dangerous)
   --fresh                   Reset conversation before review
+  --orphans                 Kill orphaned claude/codex processes (PPID=1)
+  --force                   Use SIGKILL instead of SIGTERM (with --orphans)
 
 Environment:
   AX_DEFAULT_TOOL           Default agent when using 'ax' (claude or codex, default: codex)
@@ -3677,7 +4236,8 @@ Environment:
 
 Examples:
   ${name} "explain this codebase"
-  ${name} "please review the error handling"   # Auto custom review
+  ${name} "review the error handling"           # Auto custom review (${REVIEW_TIMEOUT_MS / 60000}min timeout)
+  ${name} "FYI: auth was refactored" --no-wait  # Send context to a working session (no response needed)
   ${name} review uncommitted --wait
   ${name} approve --wait
   ${name} kill                                 # Kill agents in current project
@@ -3689,7 +4249,10 @@ Examples:
   ${name} summon reviewer                      # Summon by name (creates config if new)
   ${name} recall                               # Recall all archangels
   ${name} recall reviewer                      # Recall one by name
-  ${name} agents                               # List all agents (shows TYPE=archangel)`);
+  ${name} agents                               # List all agents (shows TYPE=archangel)
+
+Note: Reviews and complex tasks may take several minutes.
+      Use Bash run_in_background for long operations (not --no-wait).`);
 }
 
 async function main() {
@@ -3704,38 +4267,32 @@ async function main() {
   const args = process.argv.slice(2);
   const cliName = path.basename(process.argv[1], ".js");
 
-  if (args.includes("--version") || args.includes("-V")) {
+  // Parse all flags and positionals in one place
+  const { flags, positionals } = parseCliArgs(args);
+
+  if (flags.version) {
     console.log(VERSION);
     process.exit(0);
   }
 
-  // Parse flags
-  const wait = args.includes("--wait");
-  const noWait = args.includes("--no-wait");
-  const yolo = args.includes("--yolo");
-  const fresh = args.includes("--fresh");
-  const reasoning = args.includes("--reasoning");
-  const follow = args.includes("--follow") || args.includes("-f");
+  // Extract flags into local variables for convenience
+  const { wait, noWait, yolo, fresh, reasoning, follow, all, orphans, force } = flags;
 
   // Agent selection
   let agent = getAgentFromInvocation();
-  const toolArg = args.find((a) => a.startsWith("--tool="));
-  if (toolArg) {
-    const tool = toolArg.split("=")[1];
-    if (tool === "claude") agent = ClaudeAgent;
-    else if (tool === "codex") agent = CodexAgent;
+  if (flags.tool) {
+    if (flags.tool === "claude") agent = ClaudeAgent;
+    else if (flags.tool === "codex") agent = CodexAgent;
     else {
-      console.log(`ERROR: unknown tool '${tool}'`);
+      console.log(`ERROR: unknown tool '${flags.tool}'`);
       process.exit(1);
     }
   }
 
   // Session resolution
   let session = agent.getDefaultSession();
-  const sessionArg = args.find((a) => a.startsWith("--session="));
-  if (sessionArg) {
-    const val = sessionArg.split("=")[1];
-    if (val === "self") {
+  if (flags.session) {
+    if (flags.session === "self") {
       const current = tmuxCurrentSession();
       if (!current) {
         console.log("ERROR: --session=self requires running inside tmux");
@@ -3744,110 +4301,92 @@ async function main() {
       session = current;
     } else {
       // Resolve partial names, archangel names, and UUID prefixes
-      session = resolveSessionName(val);
+      session = resolveSessionName(flags.session);
     }
   }
 
-  // Timeout
+  // Timeout (convert seconds to milliseconds)
   let timeoutMs = DEFAULT_TIMEOUT_MS;
-  const timeoutArg = args.find((a) => a.startsWith("--timeout="));
-  if (timeoutArg) {
-    const val = parseInt(timeoutArg.split("=")[1], 10);
-    if (isNaN(val) || val <= 0) {
+  if (flags.timeout !== undefined) {
+    if (isNaN(flags.timeout) || flags.timeout <= 0) {
       console.log("ERROR: invalid timeout");
       process.exit(1);
     }
-    timeoutMs = val * 1000;
+    timeoutMs = flags.timeout * 1000;
   }
 
   // Tail (for log command)
-  let tail = 50;
-  const tailArg = args.find((a) => a.startsWith("--tail="));
-  if (tailArg) {
-    tail = parseInt(tailArg.split("=")[1], 10) || 50;
-  }
+  const tail = flags.tail ?? 50;
 
   // Limit (for mailbox command)
-  let limit = 20;
-  const limitArg = args.find((a) => a.startsWith("--limit="));
-  if (limitArg) {
-    limit = parseInt(limitArg.split("=")[1], 10) || 20;
-  }
+  const limit = flags.limit ?? 20;
 
   // Branch filter (for mailbox command)
-  let branch = null;
-  const branchArg = args.find((a) => a.startsWith("--branch="));
-  if (branchArg) {
-    branch = branchArg.split("=")[1] || null;
-  }
-
-  // All flag (for mailbox command - show all regardless of age)
-  const all = args.includes("--all");
-
-  // Filter out flags
-  const filteredArgs = args.filter(
-    (a) =>
-      !["--wait", "--no-wait", "--yolo", "--reasoning", "--follow", "-f", "--all"].includes(a) &&
-      !a.startsWith("--timeout") &&
-      !a.startsWith("--session") &&
-      !a.startsWith("--tool") &&
-      !a.startsWith("--tail") &&
-      !a.startsWith("--limit") &&
-      !a.startsWith("--branch"),
-  );
-  const cmd = filteredArgs[0];
+  const branch = flags.branch ?? null;
+
+  // Command is first positional
+  const cmd = positionals[0];
 
   // Dispatch commands
   if (cmd === "agents") return cmdAgents();
-  if (cmd === "summon") return cmdSummon(filteredArgs[1]);
-  if (cmd === "recall") return cmdRecall(filteredArgs[1]);
-  if (cmd === "archangel") return cmdArchangel(filteredArgs[1]);
-  if (cmd === "kill") return cmdKill(session, { all });
-  if (cmd === "attach") return cmdAttach(filteredArgs[1] || session);
-  if (cmd === "log") return cmdLog(filteredArgs[1] || session, { tail, reasoning, follow });
+  if (cmd === "target") {
+    const defaultSession = agent.getDefaultSession();
+    if (defaultSession) {
+      console.log(defaultSession);
+    } else {
+      console.log("NO_TARGET");
+      process.exit(1);
+    }
+    return;
+  }
+  if (cmd === "summon") return cmdSummon(positionals[1]);
+  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 === "mailbox") return cmdMailbox({ limit, branch, all });
   if (cmd === "approve") return cmdApprove(agent, session, { wait, timeoutMs });
   if (cmd === "reject") return cmdReject(agent, session, { wait, timeoutMs });
   if (cmd === "review")
-    return cmdReview(agent, session, filteredArgs[1], filteredArgs[2], {
+    return cmdReview(agent, session, positionals[1], positionals[2], {
       wait,
-      yolo,
       fresh,
       timeoutMs,
     });
   if (cmd === "status") return cmdStatus(agent, session);
   if (cmd === "debug") return cmdDebug(agent, session);
   if (cmd === "output") {
-    const indexArg = filteredArgs[1];
+    const indexArg = positionals[1];
     const index = indexArg?.startsWith("-") ? parseInt(indexArg, 10) : 0;
     return cmdOutput(agent, session, index, { wait, timeoutMs });
   }
-  if (cmd === "send" && filteredArgs.length > 1)
-    return cmdSend(session, filteredArgs.slice(1).join(" "));
+  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 === "select" && filteredArgs[1])
-    return cmdSelect(agent, session, filteredArgs[1], { wait, timeoutMs });
+  if (cmd === "select" && positionals[1])
+    return cmdSelect(agent, session, positionals[1], { wait, timeoutMs });
 
   // Default: send message
-  let message = filteredArgs.join(" ");
+  let message = positionals.join(" ");
   if (!message && hasStdinData()) {
     message = await readStdin();
   }
 
-  if (!message || cmd === "--help" || cmd === "-h") {
+  if (!message || flags.help) {
     printHelp(agent, cliName);
     process.exit(0);
   }
 
-  // Detect "please review" and route to custom review mode
-  const reviewMatch = message.match(/^please review\s*(.*)/i);
+  // Detect "review ..." or "please review ..." and route to custom review mode
+  const reviewMatch = message.match(/^(?:please )?review\s*(.*)/i);
   if (reviewMatch && agent.reviewOptions) {
     const customInstructions = reviewMatch[1].trim() || null;
     return cmdReview(agent, session, "custom", customInstructions, {
       wait: !noWait,
       yolo,
-      timeoutMs,
+      timeoutMs: flags.timeout !== undefined ? timeoutMs : REVIEW_TIMEOUT_MS,
     });
   }
 
@@ -3868,6 +4407,9 @@ const isDirectRun =
 if (isDirectRun) {
   main().catch((err) => {
     console.log(`ERROR: ${err.message}`);
+    if (err instanceof TimeoutError && err.session) {
+      console.log(`Hint: Use 'ax debug --session=${err.session}' to see current screen state`);
+    }
     process.exit(1);
   });
 }
@@ -3877,6 +4419,7 @@ export {
   parseSessionName,
   parseAgentConfig,
   parseKeySequence,
+  parseCliArgs,
   getClaudeProjectPath,
   matchesPattern,
   getBaseDir,