@idl3/claude-control 1.3.0 → 1.4.3

package/lib/codex.js

@@ -8,6 +8,10 @@
 
 import fs from 'node:fs/promises';
 import path from 'node:path';
+import { execFile as _execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const execFile = promisify(_execFile);
 
 // ---------------------------------------------------------------------------
 // inputSummary — intentionally duplicated from lib/transcript.js (not exported
@@ -115,12 +119,194 @@ export function extractUsageFromTail(text) {
 // a path ending in "/codex", or "codex" followed by a space (with flags).
 // Does NOT match "codex-control" or version strings like "2.1.162".
 // ---------------------------------------------------------------------------
-export function matchesProcess(cmd) {
+export function processMatchKind(cmd) {
   const c = String(cmd || '').trim();
-  return c === 'codex' || /(^|\/)codex$/.test(c) || /^codex\s/.test(c);
+  if (!c) return null;
+  const parts = c.split(/\s+/).filter(Boolean);
+  const basename = (s) => String(s || '').replace(/\\/g, '/').split('/').pop();
+  if (basename(parts[0]) === 'codex') return 'direct';
+  if (basename(parts[0]) === 'node' && basename(parts[1]) === 'codex') return 'node-wrapper';
+  return null;
+}
+
+export function matchesProcess(cmd) {
+  return processMatchKind(cmd) !== null;
 }
 
+const SUBAGENT_NOTIFICATION_OPEN = '<subagent_notification>';
+const SUBAGENT_NOTIFICATION_CLOSE = '</subagent_notification>';
+
+function isCodexSubagentNotificationText(text) {
+  if (typeof text !== 'string') return false;
+  const trimmed = text.trim();
+  return trimmed.startsWith(SUBAGENT_NOTIFICATION_OPEN) && trimmed.endsWith(SUBAGENT_NOTIFICATION_CLOSE);
+}
+
+function statusValueText(value) {
+  if (value == null) return null;
+  if (typeof value === 'string') return value;
+  if (typeof value === 'number' || typeof value === 'boolean') return String(value);
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return String(value);
+  }
+}
+
+function statusKindFrom(status, candidates) {
+  for (const key of candidates) {
+    if (Object.hasOwn(status, key)) return key;
+  }
+  return null;
+}
+
+function agentIdFromPath(agentPath) {
+  const parts = agentPath.split('/').filter(Boolean);
+  return parts[parts.length - 1] || agentPath;
+}
+
+// ---------------------------------------------------------------------------
+// parseCodexSubagentNotification
+//
+// Parse the exact Codex wrapper emitted into rollout transcripts when a
+// sub-agent status is delivered as message text.
+//
+// Returns a normalized update:
+//   {
+//     agentId, agentPath,
+//     status: 'running' | 'done',
+//     state: 'running' | 'completed' | 'error',
+//     statusKind, result, error, rawStatus, raw
+//   }
+// or null when text is not the exact wrapper or the JSON shape is unusable.
 // ---------------------------------------------------------------------------
+export function parseCodexSubagentNotification(text) {
+  if (!isCodexSubagentNotificationText(text)) return null;
+
+  const trimmed = text.trim();
+  const jsonText = trimmed
+    .slice(SUBAGENT_NOTIFICATION_OPEN.length, trimmed.length - SUBAGENT_NOTIFICATION_CLOSE.length)
+    .trim();
+  if (!jsonText) return null;
+
+  let raw;
+  try {
+    raw = JSON.parse(jsonText);
+  } catch {
+    return null;
+  }
+
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null;
+  const agentPath = raw.agent_path;
+  if (typeof agentPath !== 'string' || !agentPath) return null;
+
+  const rawStatus = raw.status;
+  if (!rawStatus || typeof rawStatus !== 'object' || Array.isArray(rawStatus)) return null;
+
+  const completedKind = statusKindFrom(rawStatus, ['completed', 'complete', 'done', 'finished']);
+  if (completedKind) {
+    return {
+      agentId: agentIdFromPath(agentPath),
+      agentPath,
+      status: 'done',
+      state: 'completed',
+      statusKind: completedKind,
+      result: statusValueText(rawStatus[completedKind]),
+      error: null,
+      rawStatus,
+      raw,
+    };
+  }
+
+  const errorKind = statusKindFrom(rawStatus, [
+    'failed',
+    'error',
+    'errored',
+    'cancelled',
+    'canceled',
+    'timed_out',
+    'timeout',
+  ]);
+  if (errorKind) {
+    return {
+      agentId: agentIdFromPath(agentPath),
+      agentPath,
+      status: 'done',
+      state: 'error',
+      statusKind: errorKind,
+      result: null,
+      error: statusValueText(rawStatus[errorKind]),
+      rawStatus,
+      raw,
+    };
+  }
+
+  const runningKind = statusKindFrom(rawStatus, ['running', 'started', 'in_progress', 'pending']);
+  if (runningKind) {
+    return {
+      agentId: agentIdFromPath(agentPath),
+      agentPath,
+      status: 'running',
+      state: 'running',
+      statusKind: runningKind,
+      result: null,
+      error: null,
+      rawStatus,
+      raw,
+    };
+  }
+
+  return null;
+}
+
+export function parseCodexSubagentNotificationRecord(line) {
+  const trimmed = String(line || '').trim();
+  if (!trimmed) return null;
+  let record;
+  try {
+    record = JSON.parse(trimmed);
+  } catch {
+    return null;
+  }
+  if (record?.type !== 'response_item') return null;
+  const p = record.payload || {};
+  if (p.type !== 'message' || !Array.isArray(p.content)) return null;
+  for (const item of p.content) {
+    const update = parseCodexSubagentNotification(item?.text);
+    if (update) {
+      return {
+        ...update,
+        ts: record.timestamp ?? null,
+        role: p.role ?? null,
+      };
+    }
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+/**
+ * Decode a Codex reasoning `summary` into plain text. The shape varies by Codex
+ * version: an array of strings, an array of `{ text }` / `{ summary }` objects,
+ * or a bare string. Returns the joined, trimmed text, or '' when nothing usable.
+ * @param {unknown} summary
+ * @returns {string}
+ */
+function decodeReasoningSummary(summary) {
+  if (typeof summary === 'string') return summary.trim();
+  if (!Array.isArray(summary)) return '';
+  const parts = summary
+    .map((item) => {
+      if (typeof item === 'string') return item;
+      if (item && typeof item === 'object') {
+        return item.text ?? item.summary ?? '';
+      }
+      return '';
+    })
+    .filter(Boolean);
+  return parts.join('\n\n').trim();
+}
+
 // parseCodexRecord
 //
 // Parse one JSONL line from a Codex rollout file into a NormalizedMessage,
@@ -164,6 +350,7 @@ export function parseCodexRecord(line) {
     if (Array.isArray(p.content)) {
       for (const item of p.content) {
         const text = item?.text;
+        if (isCodexSubagentNotificationText(text)) continue;
         if (typeof text === 'string' && text) {
           blocks.push({ kind: 'text', text });
         }
@@ -180,13 +367,19 @@ export function parseCodexRecord(line) {
     };
   }
 
-  // --- response_item/reasoning (encrypted) ---
+  // --- response_item/reasoning ---
+  // Codex emits a `summary` array of reasoning parts (the human-readable gist;
+  // the full chain is encrypted in `encrypted_content`, which we never get). Show
+  // the decoded summary as a thinking block; if there's nothing readable, hide
+  // the block entirely rather than render a useless "[reasoning encrypted]".
   if (subType === 'reasoning') {
+    const summary = decodeReasoningSummary(p.summary);
+    if (!summary) return null;
     return {
       uuid: record.id ?? null,
       role: 'assistant',
       ts,
-      blocks: [{ kind: 'thinking', text: '[reasoning encrypted]' }],
+      blocks: [{ kind: 'thinking', text: summary }],
       rawType: 'reasoning',
     };
   }
@@ -277,6 +470,193 @@ export function parseCodexRecord(line) {
   return null;
 }
 
+export async function readCodexTranscriptRecord(filePath) {
+  let stat;
+  try {
+    stat = await fs.stat(filePath);
+  } catch {
+    return null;
+  }
+  const mtime = stat.mtimeMs;
+
+  // Head-read only the first 65536 bytes to extract session_meta.
+  const buf = await readHead(filePath, 65536);
+  if (!buf || buf.length === 0) return null;
+
+  const text = buf.toString('utf8');
+  const firstLine = text.split('\n')[0];
+  if (!firstLine || !firstLine.trim()) return null;
+
+  let record;
+  try {
+    record = JSON.parse(firstLine.trim());
+  } catch {
+    return null;
+  }
+
+  if (record.type !== 'session_meta') return null;
+  const payload = record.payload || {};
+  if (typeof payload.cwd !== 'string' || !payload.cwd) return null;
+
+  const lastActivity = record.timestamp ?? null;
+  const lastActivityMs = lastActivity ? (Date.parse(lastActivity) || null) : null;
+
+  // Tail-read for rate-limit usage (token_count events appear throughout).
+  let usagePct = null;
+  let usageWindowMin = null;
+  const tailBuf = await readTail(filePath, 32768);
+  if (tailBuf && tailBuf.length > 0) {
+    const tailText = tailBuf.toString('utf8');
+    const usage = extractUsageFromTail(tailText);
+    if (usage) {
+      usagePct = usage.usagePct;
+      usageWindowMin = usage.usageWindowMin;
+    }
+  }
+
+  return {
+    cwd: payload.cwd,
+    sessionId: payload.id ?? null,
+    lastActivity,
+    lastActivityMs,
+    // session_meta has model_provider but no concrete model id.
+    model: null,
+    aiTitle: null,
+    customTitle: null,
+    transcriptPath: filePath,
+    mtime,
+    transcriptPending: false,
+    pendingToolUseId: null,
+    pendingQuestion: null,
+    agentType: 'codex',
+    usagePct,
+    usageWindowMin,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// readRolloutMeta
+//
+// Read a single rollout .jsonl file and return the discovered record object,
+// or null on any failure (missing file, empty, non-session_meta first line,
+// missing cwd).
+//
+// This is the per-file parsing logic extracted from buildTranscriptIndex so
+// it can be called directly by findOpenRollout-based binding (lsof path).
+// Unlike the loop inside buildTranscriptIndex, this function does NOT apply
+// the ACTIVE_WINDOW mtime gate — a live file found via lsof must always be
+// parsed regardless of mtime staleness.
+// ---------------------------------------------------------------------------
+export async function readRolloutMeta(filePath, now = new Date()) {
+  try {
+    const stat = await fs.stat(filePath);
+    const mtime = stat.mtimeMs;
+
+    const buf = await readHead(filePath, 65536);
+    if (!buf || buf.length === 0) return null;
+
+    const text = buf.toString('utf8');
+    const firstLine = text.split('\n')[0];
+    if (!firstLine || !firstLine.trim()) return null;
+
+    let record;
+    try {
+      record = JSON.parse(firstLine.trim());
+    } catch {
+      return null;
+    }
+
+    if (record.type !== 'session_meta') return null;
+    const payload = record.payload || {};
+    if (typeof payload.cwd !== 'string' || !payload.cwd) return null;
+
+    const lastActivity = record.timestamp ?? null;
+    const lastActivityMs = lastActivity ? (Date.parse(lastActivity) || null) : null;
+
+    let usagePct = null;
+    let usageWindowMin = null;
+    const tailBuf = await readTail(filePath, 32768);
+    if (tailBuf && tailBuf.length > 0) {
+      const tailText = tailBuf.toString('utf8');
+      const usage = extractUsageFromTail(tailText);
+      if (usage) {
+        usagePct = usage.usagePct;
+        usageWindowMin = usage.usageWindowMin;
+      }
+    }
+
+    return {
+      cwd: payload.cwd,
+      sessionId: payload.id ?? null,
+      lastActivity,
+      lastActivityMs,
+      model: null,
+      aiTitle: null,
+      customTitle: null,
+      transcriptPath: filePath,
+      mtime,
+      transcriptPending: false,
+      pendingToolUseId: null,
+      pendingQuestion: null,
+      agentType: 'codex',
+      usagePct,
+      usageWindowMin,
+    };
+  } catch {
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// parseLsofRollout
+//
+// Pure parser for `lsof -Fn` stdout output. Returns the first open file path
+// that matches a Codex rollout pattern (/rollout-*.jsonl), or null if none.
+//
+// lsof -Fn output format:
+//   p<pid>
+//   f<fd>
+//   n<path>
+//   ...
+//
+// We look only at lines starting with 'n' whose remainder ends with
+// /rollout-<something>.jsonl.
+// ---------------------------------------------------------------------------
+export function parseLsofRollout(stdout) {
+  if (!stdout) return null;
+  const lines = stdout.split('\n');
+  for (const line of lines) {
+    if (!line.startsWith('n')) continue;
+    const filePath = line.slice(1);
+    if (/\/rollout-[^/]*\.jsonl$/.test(filePath)) return filePath;
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// findOpenRollout
+//
+// Given a codex process pid, run `lsof -p <pid> -Fn` and return the path of
+// the rollout .jsonl file the process has open, or null if not found / any
+// error / pid is null/invalid.
+//
+// Best-effort: any lsof failure (timeout, non-zero exit, ENOENT, etc.)
+// returns null and never throws — the caller falls back to the heuristic.
+// ---------------------------------------------------------------------------
+export async function findOpenRollout(pid) {
+  if (pid == null || typeof pid !== 'number' || !Number.isFinite(pid) || pid <= 0) return null;
+  try {
+    const { stdout } = await execFile(
+      '/usr/sbin/lsof',
+      ['-p', String(pid), '-Fn'],
+      { timeout: 2000 },
+    );
+    return parseLsofRollout(stdout);
+  } catch {
+    return null;
+  }
+}
+
 // ---------------------------------------------------------------------------
 // buildTranscriptIndex
 //
@@ -288,7 +668,7 @@ export function parseCodexRecord(line) {
 // care about the clock may omit it and get `new Date()`.
 // ---------------------------------------------------------------------------
 export async function buildTranscriptIndex({ codexSessionsRoot }, now = new Date()) {
-  const index = { byCwd: new Map() };
+  const index = { byCwd: new Map(), byPath: new Map(), bySessionId: new Map() };
 
   if (!codexSessionsRoot) return index;
 
@@ -301,10 +681,26 @@ export async function buildTranscriptIndex({ codexSessionsRoot }, now = new Date
     return path.join(codexSessionsRoot, yyyy, mm, dd);
   }
 
-  const today = datePath(now);
-  const yesterday = datePath(new Date(now.getTime() - 24 * 3600 * 1000));
-  // Dedup if equal (e.g. right at midnight boundary)
-  const dateDirs = today === yesterday ? [today] : [today, yesterday];
+  // Codex appends to ONE rollout file per session, stored under its START-date
+  // dir — so a long-running session's file stays in an old date dir while its
+  // mtime keeps advancing. Scanning only today+yesterday therefore loses any
+  // session that started >1 day ago but is still active (it vanishes from the
+  // UI). Scan the last LOOKBACK_DAYS date dirs (cheap readdir + stat), but only
+  // parse rollouts whose mtime is recent (ACTIVE_WINDOW) so we never head/tail-
+  // read the thousands of dead rollouts that accumulate over time.
+  // ponytail: 14-day start-age ceiling — a codex session running continuously
+  // for >14 days would need a wider window; widen LOOKBACK_DAYS if that happens.
+  const LOOKBACK_DAYS = 14;
+  const ACTIVE_WINDOW_MS = 3 * 24 * 3600 * 1000;
+  const dateDirs = [];
+  const seenDirs = new Set();
+  for (let i = 0; i < LOOKBACK_DAYS; i++) {
+    const dp = datePath(new Date(now.getTime() - i * 24 * 3600 * 1000));
+    if (!seenDirs.has(dp)) {
+      seenDirs.add(dp);
+      dateDirs.push(dp);
+    }
+  }
 
   for (const dateDir of dateDirs) {
     let files;
@@ -321,69 +717,31 @@ export async function buildTranscriptIndex({ codexSessionsRoot }, now = new Date
       rollouts.map(async (filename) => {
         const filePath = path.join(dateDir, filename);
         try {
-          // Stat for mtime.
+          // Stat for mtime gate (active window check).
           const stat = await fs.stat(filePath);
           const mtime = stat.mtimeMs;
 
-          // Head-read only the first 65536 bytes to extract session_meta.
-          const buf = await readHead(filePath, 65536);
-          if (!buf || buf.length === 0) return;
+          // Skip dead sessions: only parse rollouts touched within ACTIVE_WINDOW.
+          // This keeps the expensive head/tail reads bounded to live sessions even
+          // though we now scan many more date dirs. (now - mtime can be negative
+          // under an injected test clock — treated as active, never skipped.)
+          if (now.getTime() - mtime > ACTIVE_WINDOW_MS) return;
 
-          const text = buf.toString('utf8');
-          const firstLine = text.split('\n')[0];
-          if (!firstLine || !firstLine.trim()) return;
+          const discovered = await readCodexTranscriptRecord(filePath);
+          if (!discovered) return;
 
-          let record;
-          try {
-            record = JSON.parse(firstLine.trim());
-          } catch {
-            return;
+          // Newest mtime wins per cwd.
+          const existing = index.byCwd.get(discovered.cwd);
+          if (!existing || discovered.mtime > existing.mtime) {
+            index.byCwd.set(discovered.cwd, discovered);
           }
-
-          if (record.type !== 'session_meta') return;
-          const payload = record.payload || {};
-          if (typeof payload.cwd !== 'string' || !payload.cwd) return;
-
-          const lastActivity = record.timestamp ?? null;
-          const lastActivityMs = lastActivity ? (Date.parse(lastActivity) || null) : null;
-
-          // Tail-read for rate-limit usage (token_count events appear throughout).
-          let usagePct = null;
-          let usageWindowMin = null;
-          const tailBuf = await readTail(filePath, 32768);
-          if (tailBuf && tailBuf.length > 0) {
-            const tailText = tailBuf.toString('utf8');
-            const usage = extractUsageFromTail(tailText);
-            if (usage) {
-              usagePct = usage.usagePct;
-              usageWindowMin = usage.usageWindowMin;
+          index.byPath.set(discovered.transcriptPath, discovered);
+          if (discovered.sessionId) {
+            const byId = index.bySessionId.get(discovered.sessionId);
+            if (!byId || discovered.mtime > byId.mtime) {
+              index.bySessionId.set(discovered.sessionId, discovered);
             }
           }
-
-          const discovered = {
-            cwd: payload.cwd,
-            sessionId: payload.id ?? null,
-            lastActivity,
-            lastActivityMs,
-            // session_meta has model_provider but no concrete model id.
-            model: null,
-            aiTitle: null,
-            customTitle: null,
-            transcriptPath: filePath,
-            mtime,
-            transcriptPending: false,
-            pendingToolUseId: null,
-            pendingQuestion: null,
-            agentType: 'codex',
-            usagePct,
-            usageWindowMin,
-          };
-
-          // Newest mtime wins per cwd.
-          const existing = index.byCwd.get(payload.cwd);
-          if (!existing || mtime > existing.mtime) {
-            index.byCwd.set(payload.cwd, discovered);
-          }
         } catch {
           // Per-file resilience: skip malformed or unreadable files.
         }
@@ -391,7 +749,6 @@ export async function buildTranscriptIndex({ codexSessionsRoot }, now = new Date
     );
   }
 
-  // Return byCwd only — no byDir key. sessions.js merge loop guards `if (byDir)`.
   return index;
 }
 
@@ -416,6 +773,12 @@ export function detectPendingFromCapture(capture) {
 
   const lines = capture.split('\n');
 
+  // Build a whitespace-free concatenation of all lines for wrap-tolerant heading
+  // matching. A narrow pane may break mid-word (e.g. "follo" + "wing"), so joining
+  // with a space would produce "follo wing" — not matching "following". Instead we
+  // strip all whitespace from both the candidate and the heading before comparing.
+  const dewrapped = lines.join('').replace(/\s+/g, '');
+
   const headings = [
     { text: 'Would you like to run the following command?', kind: 'exec_command' },
     { text: 'Would you like to make the following edits?', kind: 'apply_patch' },
@@ -426,12 +789,13 @@ export function detectPendingFromCapture(capture) {
   let header = null;
   let headingIdx = -1;
 
+  // First try per-line exact match (fast path, no allocation).
   for (let i = 0; i < lines.length; i++) {
     const trimmed = lines[i].trim();
     for (const h of headings) {
       if (trimmed === h.text) {
         pendingKind = h.kind;
-        header = trimmed;
+        header = h.text;
         headingIdx = i;
         break;
       }
@@ -439,38 +803,129 @@ export function detectPendingFromCapture(capture) {
     if (headingIdx !== -1) break;
   }
 
-  if (!pendingKind) return noModal;
+  // If exact per-line match failed, try wrap-tolerant match by comparing
+  // whitespace-stripped strings. A narrow pane can break mid-word (e.g.
+  // "follo" + "wing"), so we strip all whitespace from both the candidate
+  // and the heading before comparing, then use the canonical heading text.
+  if (!pendingKind) {
+    for (const h of headings) {
+      const headingStripped = h.text.replace(/\s+/g, '');
+      if (dewrapped.includes(headingStripped)) {
+        pendingKind = h.kind;
+        header = h.text;
+        // Locate the line that starts the heading by finding the first line
+        // that contains the opening word(s). The heading start line is the
+        // anchor from which we begin option scanning (after the heading block).
+        const firstWord = h.text.split(' ')[0];
+        for (let i = 0; i < lines.length; i++) {
+          if (lines[i].includes(firstWord)) {
+            headingIdx = i;
+            break;
+          }
+        }
+        break;
+      }
+    }
+  }
 
-  // Scan lines after the heading for option lines.
   // Option line regex: /^\s*[›\s]\s*(\d+)\.\s+(.+?)(?:\s+\(([^)]+)\))?\s*$/
   // U+203A = ›
   const optionLineRegex = /^\s*[›\s]\s*(\d+)\.\s+(.+?)(?:\s+\(([^)]+)\))?\s*$/;
-  const footerHints = ['Press enter to confirm or esc to cancel', 'Press enter to continue'];
+
+  // Footer detection — prefix-based so wrapped footers still stop collection.
+  const isFooterLine = (line) => {
+    const t = line.trim();
+    return (
+      t.startsWith('Press enter to confirm or esc to') ||
+      t.startsWith('Press enter to continue')
+    );
+  };
 
   const options = [];
   let seenOption = false;
 
-  for (let i = headingIdx + 1; i < lines.length; i++) {
-    const raw = lines[i];
-    const trimmed = raw.trim();
-
-    // Check footer hint — stop collecting after it.
-    if (footerHints.includes(trimmed)) break;
-
-    const m = optionLineRegex.exec(raw);
-    if (m) {
-      seenOption = true;
-      options.push({
-        n: Number(m[1]),
-        label: m[2].trim(),
-        shortcut: m[3] || null,
-        // Highlighted if the raw line contains the › character (U+203A).
-        highlighted: raw.includes('›'),
-      });
-    } else if (seenOption && trimmed && !m) {
-      // First non-blank, non-option line after at least one option was captured.
-      break;
+  if (pendingKind && headingIdx !== -1) {
+    for (let i = headingIdx + 1; i < lines.length; i++) {
+      const raw = lines[i];
+      const trimmed = raw.trim();
+
+      // Check footer hint — stop collecting after it.
+      if (isFooterLine(raw)) break;
+
+      const m = optionLineRegex.exec(raw);
+      if (m) {
+        seenOption = true;
+        options.push({
+          n: Number(m[1]),
+          label: m[2].trim(),
+          shortcut: m[3] || null,
+          // Highlighted if the raw line contains the › character (U+203A).
+          highlighted: raw.includes('›'),
+        });
+      } else if (seenOption && trimmed && !m) {
+        // First non-blank, non-option line after at least one option was captured.
+        break;
+      }
+    }
+  }
+
+  if (options.length === 0 && pendingKind) return noModal;
+
+  // ── Generic fallback: planning / clarifying question ───────────────────────
+  // No known heading matched. Check whether the capture contains a numbered
+  // picker (Codex uses › 1. / 2. lines) AND a confirm/cancel footer. If so,
+  // treat it as a free-form question with pendingKind='question'.
+  if (!pendingKind) {
+    // Scan for footer first — a footer is required.
+    const hasFooter = lines.some(isFooterLine);
+    if (hasFooter) {
+      // Collect options and find the index of the first option line.
+      let firstOptionIdx = -1;
+      const genericOptions = [];
+      let genericSeenOption = false;
+      for (let i = 0; i < lines.length; i++) {
+        const raw = lines[i];
+        if (isFooterLine(raw)) break;
+        const m = optionLineRegex.exec(raw);
+        if (m) {
+          if (firstOptionIdx === -1) firstOptionIdx = i;
+          genericSeenOption = true;
+          genericOptions.push({
+            n: Number(m[1]),
+            label: m[2].trim(),
+            shortcut: m[3] || null,
+            highlighted: raw.includes('›'),
+          });
+        } else if (genericSeenOption && raw.trim() && !m) {
+          break;
+        }
+      }
+
+      if (genericOptions.length > 0) {
+        // Derive header from the question block immediately above the options.
+        // Codex separates the question from the picker with a blank line, so we
+        // first skip any blanks directly above the first option, then collect the
+        // contiguous block of non-empty lines — stopping at the next blank. This
+        // captures the actual question without sweeping in preceding scrollback.
+        let i = firstOptionIdx - 1;
+        while (i >= 0 && !lines[i].trim()) i--; // skip the separator blank(s)
+        const questionLines = [];
+        for (; i >= 0; i--) {
+          const t = lines[i].trim();
+          if (!t) break;
+          questionLines.unshift(t);
+        }
+        const derivedHeader = questionLines.join(' ').replace(/\s+/g, ' ').trim() || 'Question';
+
+        return {
+          transcriptPending: true,
+          pendingKind: 'question',
+          header: derivedHeader,
+          options: genericOptions,
+        };
+      }
     }
+    return noModal;
   }
 
   if (options.length === 0) return noModal;
@@ -549,6 +1004,15 @@ export function buildSpawnCommand({ cwd, bin = 'codex' } = {}) {
   return { bin, args: ['-C', cwd] };
 }
 
+/**
+ * Build the command shape for Codex app-server mode. `bin` is the configured
+ * operator command (for example "codex" or "yodex"); callers append and quote
+ * runtime args before typing the command into the tmux shell.
+ */
+export function buildAppServerCommand({ endpoint, bin = 'codex' } = {}) {
+  return { bin, args: ['app-server', '--listen', endpoint] };
+}
+
 // ---------------------------------------------------------------------------
 // parseTuiStatus
 //