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

package/ax.js

@@ -23,11 +23,15 @@ import {
   renameSync,
   realpathSync,
   watch,
+  openSync,
+  readSync,
+  closeSync,
 } from "node:fs";
 import { randomUUID } 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);
@@ -302,6 +306,21 @@ const ARCHANGEL_GIT_CONTEXT_HOURS = 4;
 const ARCHANGEL_GIT_CONTEXT_MAX_LINES = 200;
 const ARCHANGEL_PARENT_CONTEXT_ENTRIES = 10;
 
+/**
+ * @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
  * @param {(screen: string) => boolean} predicate
@@ -315,7 +334,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 +362,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 +422,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
 // =============================================================================
 
@@ -585,6 +716,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 +1712,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
@@ -1475,14 +1730,33 @@ function detectState(screen, config) {
     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 +1768,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 +1802,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 +1818,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 +1830,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 +1841,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 +1861,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 +1882,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 +1944,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 +2173,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 +2193,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 +2202,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 +2235,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 +2279,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 +2325,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 +2333,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 +2424,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,9 +2486,22 @@ 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));
@@ -2152,30 +2510,45 @@ function cmdAgents() {
     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);
 
     return {
       session,
       tool: parsed.tool,
       state: state || "unknown",
+      target: isDefault ? "*" : "",
       type,
       log: logPath || "-",
     };
   });
 
-  // 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));
 
   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)}  LOG`,
   );
   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.log}`,
     );
   }
+
+  // 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`);
+  }
 }
 
 // =============================================================================
@@ -2838,9 +3211,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 +3598,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 +3618,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 +3642,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 +3659,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 +3677,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 +3696,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 +3730,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 +3797,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 +3809,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 +3842,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 +3854,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 +3878,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 +3886,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 +4003,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 +4038,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 +4073,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 +4091,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 +4104,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 +4122,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 +4156,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 +4262,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 +4274,7 @@ export {
   parseSessionName,
   parseAgentConfig,
   parseKeySequence,
+  parseCliArgs,
   getClaudeProjectPath,
   matchesPattern,
   getBaseDir,

package/package.json

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