@idl3/claude-control 1.3.0 → 1.4.3

package/lib/sessions.js

@@ -20,9 +20,16 @@ import { pinKey } from './pins.js';
 import { readPaneRegistry, gcPaneRegistry } from './pane-registry.js';
 import {
   matchesProcess as codexMatchesProcess,
+  processMatchKind as codexProcessMatchKind,
   buildTranscriptIndex as buildCodexIndex,
+  readCodexTranscriptRecord,
   parseTuiStatus as parseCodexTuiStatus,
+  parseCodexPrompt,
+  findOpenRollout,
+  readRolloutMeta,
 } from './codex.js';
+import { hasActiveSubAgents } from './subagents.js';
+import { isCodexAppServerCapture } from './codex-rpc.js';
 
 const execFile = promisify(_execFile);
 
@@ -30,6 +37,7 @@ const execFile = promisify(_execFile);
 const CLAUDE_COMM_RE = /(^|\/)claude$/;
 // Matches Codex CLI executable basename.
 const CODEX_COMM_RE = /(^|\/)codex$/;
+const CLAUDE_ARG_RE = /(^|[\s/])claude(?:\s|$)/;
 
 // A pane is a Claude Code session when its process title is the Claude version
 // (e.g. "2.1.162") — shells report zsh/bash/etc. A linked transcript also counts.
@@ -75,6 +83,31 @@ export function isCwdConsistent(recCwd, winCwd) {
 
 const PENDING_QUESTION_MAX = 140; // truncate the surfaced question text
 
+function codexRecordToCandidate(rec) {
+  return {
+    transcriptPath: rec.transcriptPath,
+    cwd: rec.cwd,
+    projectDir: null, // triggers isCwdConsistent scope fallback in match.js
+    birthtimeMs: rec.mtime,
+    mtimeMs: rec.mtime,
+    lastActivityMs: rec.lastActivityMs ?? rec.mtime,
+    customTitle: rec.customTitle,
+    aiTitle: rec.aiTitle,
+    recentText: null,
+    // Pass through for later session assembly
+    sessionId: rec.sessionId,
+    lastActivity: rec.lastActivity,
+    model: rec.model,
+    transcriptPending: rec.transcriptPending,
+    pendingToolUseId: rec.pendingToolUseId,
+    pendingQuestion: rec.pendingQuestion,
+    agentType: rec.agentType,
+    usagePct: rec.usagePct ?? null,
+    usageWindowMin: rec.usageWindowMin ?? null,
+    mtime: rec.mtime,
+  };
+}
+
 /**
  * Walk a set of JSONL tail lines and decide whether an AskUserQuestion is still
  * OPEN — i.e. an assistant `tool_use` block named "AskUserQuestion" exists whose
@@ -365,8 +398,14 @@ export class SessionRegistry extends EventEmitter {
     this._ctxMap = new Map();
     /** @type {Map<string, boolean>} target -> actively-generating flag */
     this._thinkingMap = new Map();
+    /** @type {Map<string, boolean>} target -> compacting-conversation flag */
+    this._compactingMap = new Map();
+    /** @type {Map<string, boolean>} target -> has a sub-agent actively running */
+    this._subAgentActiveMap = new Map();
     /** @type {Map<string, {pending:boolean, question:string|null}>} target -> pane-derived prompt */
     this._panePromptMap = new Map();
+    /** @type {Map<string, {transcriptPath:string, sessionId?:string|null}>} target -> exact Codex rollout hint */
+    this._transcriptHintMap = new Map();
     /** @type {Map<string, string>} target -> most-recent captured pane text (for fingerprint tiebreak) */
     this._paneTextCache = new Map();
     /** @type {number} monotonically-incrementing refresh() cycle counter */
@@ -419,15 +458,74 @@ export class SessionRegistry extends EventEmitter {
    */
   setPending(id, pending) {
     const session = this._sessions.find((s) => s.id === id);
+    this._pendingMap.set(id, !!pending);
     if (!session) return;
+    const panePrompt = this._panePromptMap.get(id) ?? null;
     const was = session.pending;
-    session.pending = !!pending;
-    this._pendingMap.set(id, !!pending);
+    session.pending = !!pending || !!panePrompt?.pending;
     if (was !== session.pending) {
       this._maybeEmit();
     }
   }
 
+  /**
+   * Set a structured prompt surfaced by a non-transcript transport such as
+   * Codex app-server. Pane-scraped Claude prompts still flow through _pollThinking().
+   *
+   * @param {string} id
+   * @param {{question?: string|null}|null} prompt
+   */
+  setPrompt(id, prompt) {
+    const rec = { pending: !!prompt, question: prompt?.question ?? null };
+    if (rec.pending) this._panePromptMap.set(id, rec);
+    else this._panePromptMap.delete(id);
+
+    const session = this._sessions.find((s) => s.id === id);
+    if (!session) return;
+    const wasPending = session.pending;
+    const wasQuestion = session.pendingQuestion ?? null;
+    session.pending = (this._pendingMap.get(id) ?? false) || rec.pending;
+    session.pendingQuestion = rec.question;
+    if (wasPending !== session.pending || wasQuestion !== session.pendingQuestion) {
+      this._maybeEmit();
+    }
+  }
+
+  /**
+   * Set active-generation state from a structured transport.
+   *
+   * @param {string} id
+   * @param {boolean} thinking
+   */
+  setThinking(id, thinking) {
+    const session = this._sessions.find((s) => s.id === id);
+    const next = !!thinking;
+    this._thinkingMap.set(id, next);
+    if (!session) return;
+    const was = session.thinking;
+    session.thinking = next;
+    if (was !== next) {
+      this._maybeEmit();
+    }
+  }
+
+  /**
+   * Bind a pane target to an exact transcript path discovered from a structured
+   * transport (currently Codex app-server's thread.path). This is authoritative
+   * for that target and avoids cwd/time ambiguity.
+   *
+   * @param {string} id
+   * @param {{transcriptPath?: string|null, sessionId?: string|null}|null} hint
+   */
+  setTranscriptHint(id, hint) {
+    if (!hint?.transcriptPath) this._transcriptHintMap.delete(id);
+    else this._transcriptHintMap.set(id, {
+      transcriptPath: hint.transcriptPath,
+      sessionId: hint.sessionId ?? null,
+    });
+    this.refresh().catch(() => {});
+  }
+
   /**
    * Rescan tmux windows and project directories. Returns the new session list.
    *
@@ -464,10 +562,13 @@ export class SessionRegistry extends EventEmitter {
     // only when ps is unavailable.
     const paneProc = await this._buildPaneProc(panes);
     const isClaudePane = (p) => {
+      if (p.ccAgent === 'claude') return true;
       const info = paneProc.get(p.target);
       return info ? info.isClaude : isClaudeCmd(p.cmd);
     };
     const paneKind = (p) => {
+      if (p.ccAgent === 'claude') return 'claude';
+      if (p.ccAgent === 'codex') return 'codex';
       const info = paneProc.get(p.target);
       if (info?.kind) return info.kind;
       if (isClaudeCmd(p.cmd)) return 'claude';
@@ -503,8 +604,9 @@ export class SessionRegistry extends EventEmitter {
     for (const p of claudePanes) {
       if (pinnedByTarget.has(p.target)) continue;
       const reg = p.paneId ? paneReg.get(p.paneId) : null;
-      if (!reg) continue;
-      const rec = await this._recordForPath(reg.transcriptPath);
+      const hint = this._transcriptHintMap.get(p.target) || reg;
+      if (!hint) continue;
+      const rec = await this._recordForPath(hint.transcriptPath);
       if (rec) {
         hookByTarget.set(p.target, rec);
         pinnedPaths.add(rec.transcriptPath); // exclude from the auto-matcher pool
@@ -583,44 +685,121 @@ export class SessionRegistry extends EventEmitter {
     // Discover Codex session transcripts and match them to Codex panes.
     // The Claude assignment above is computed first and left untouched;
     // codex results are merged in after.
+    //
+    // Binding strategy (authoritative → heuristic):
+    //   1. lsof: the live codex process holds its rollout file OPEN — lsof on
+    //      its pid gives the exact path. Zero-ambiguity; self-heals on resume.
+    //   2. cwd + mtime heuristic (assignTranscripts): fallback for panes whose
+    //      pid is unknown or whose lsof call failed.
     const codexPanes = panes.filter((p) => paneKind(p) === 'codex');
     if (codexPanes.length > 0) {
-      const codexIndex = await buildCodexIndex({ codexSessionsRoot: this._codexSessionsRoot });
-      const codexCandidates = [];
-      for (const rec of codexIndex.byCwd.values()) {
-        codexCandidates.push({
-          transcriptPath: rec.transcriptPath,
-          cwd: rec.cwd,
-          projectDir: null, // triggers isCwdConsistent scope fallback in match.js
-          birthtimeMs: rec.mtime,
-          mtimeMs: rec.mtime,
-          lastActivityMs: rec.lastActivityMs ?? rec.mtime,
-          customTitle: rec.customTitle,
-          aiTitle: rec.aiTitle,
-          recentText: null,
-          // Pass through for later session assembly
-          sessionId: rec.sessionId,
-          lastActivity: rec.lastActivity,
-          model: rec.model,
-          transcriptPending: rec.transcriptPending,
-          pendingToolUseId: rec.pendingToolUseId,
-          pendingQuestion: rec.pendingQuestion,
-          agentType: rec.agentType,
-          usagePct: rec.usagePct ?? null,
-          usageWindowMin: rec.usageWindowMin ?? null,
-          mtime: rec.mtime,
-        });
+      // --- Phase 1: exact binding via RPC hints, pane registry, then lsof -------
+      const exactByTarget = new Map();
+      const exactPaths = new Set();
+      const appServerTargets = new Set();
+      const markAppServerIfVisible = async (p) => {
+        let capture = this._paneTextCache.get(p.target) ?? '';
+        if (!capture && this._tmux?.capturePane) {
+          try {
+            capture = await this._tmux.capturePane(p.target, 80, false, true);
+            this._paneTextCache.set(p.target, capture);
+          } catch {
+            capture = '';
+          }
+        }
+        if (isCodexAppServerCapture(capture)) appServerTargets.add(p.target);
+      };
+      await Promise.all(
+        codexPanes.map(async (p) => {
+          try {
+            const runtimeHint = this._transcriptHintMap.get(p.target);
+            if (runtimeHint?.transcriptPath) {
+              const rec = await readCodexTranscriptRecord(runtimeHint.transcriptPath);
+              if (rec && isCwdConsistent(rec.cwd, p.cwd)) {
+                exactByTarget.set(p.target, codexRecordToCandidate({
+                  ...rec,
+                  sessionId: rec.sessionId ?? runtimeHint.sessionId ?? null,
+                }));
+                exactPaths.add(rec.transcriptPath);
+                return;
+              }
+            }
+
+            const reg = p.paneId ? paneReg.get(p.paneId) : null;
+            const procInfo = paneProc.get(p.target);
+            const codexPid = procInfo?.pid ?? null;
+            if (!codexPid) {
+              await markAppServerIfVisible(p);
+              if (appServerTargets.has(p.target)) return;
+              if (reg?.transcriptPath) {
+                const rec = await readCodexTranscriptRecord(reg.transcriptPath);
+                if (rec && isCwdConsistent(rec.cwd, p.cwd)) {
+                  exactByTarget.set(p.target, codexRecordToCandidate({
+                    ...rec,
+                    sessionId: rec.sessionId ?? reg.sessionId ?? null,
+                  }));
+                  exactPaths.add(rec.transcriptPath);
+                }
+              }
+              return;
+            }
+            const rolloutPath = await findOpenRollout(codexPid);
+            if (!rolloutPath || exactPaths.has(rolloutPath)) {
+              await markAppServerIfVisible(p);
+              if (appServerTargets.has(p.target)) return;
+              if (reg?.transcriptPath) {
+                const rec = await readCodexTranscriptRecord(reg.transcriptPath);
+                if (rec && isCwdConsistent(rec.cwd, p.cwd)) {
+                  exactByTarget.set(p.target, codexRecordToCandidate({
+                    ...rec,
+                    sessionId: rec.sessionId ?? reg.sessionId ?? null,
+                  }));
+                  exactPaths.add(rec.transcriptPath);
+                }
+              }
+              return;
+            }
+            const rec = await readCodexTranscriptRecord(rolloutPath);
+            if (!rec) return;
+            if (!isCwdConsistent(rec.cwd, p.cwd)) {
+              await markAppServerIfVisible(p);
+              return;
+            }
+            exactByTarget.set(p.target, codexRecordToCandidate(rec));
+            exactPaths.add(rec.transcriptPath);
+          } catch {
+            // exact lookup failed; heuristic fallback below can still bind it
+          }
+        }),
+      );
+
+      // --- Phase 2: heuristic fallback for unresolved panes ------------------
+      const unresolved = codexPanes.filter((p) =>
+        !exactByTarget.has(p.target) && !appServerTargets.has(p.target),
+      );
+      if (unresolved.length > 0) {
+        const codexIndex = await buildCodexIndex({ codexSessionsRoot: this._codexSessionsRoot });
+        const codexCandidates = [];
+        // Use every active rollout, not only the newest per cwd. Legacy TUI and
+        // RPC app-server panes often share one cwd; collapsing by cwd can leave
+        // the older still-live pane with no fallback candidate.
+        for (const rec of codexIndex.byPath.values()) {
+          if (!exactPaths.has(rec.transcriptPath)) {
+            codexCandidates.push(codexRecordToCandidate(rec));
+          }
+        }
+        const codexPaneInputs = unresolved.map((p) => ({
+          target: p.target,
+          windowName: p.windowName,
+          cwd: p.cwd,
+          projectDir: null,
+          procStartMs: paneProc.get(p.target)?.startMs ?? null,
+          capturedText: this._paneTextCache.get(p.target) ?? null,
+        }));
+        const codexAssignment = assignTranscripts(codexPaneInputs, codexCandidates);
+        for (const [t, rec] of codexAssignment) assignment.set(t, rec);
       }
-      const codexPaneInputs = codexPanes.map((p) => ({
-        target: p.target,
-        windowName: p.windowName,
-        cwd: p.cwd,
-        projectDir: null,
-        procStartMs: paneProc.get(p.target)?.startMs ?? null,
-        capturedText: this._paneTextCache.get(p.target) ?? null,
-      }));
-      const codexAssignment = assignTranscripts(codexPaneInputs, codexCandidates);
-      for (const [t, rec] of codexAssignment) assignment.set(t, rec);
+      for (const [t, rec] of exactByTarget) assignment.set(t, rec);
     }
     // ── End Codex matching ───────────────────────────────────────────────────
 
@@ -634,7 +813,7 @@ export class SessionRegistry extends EventEmitter {
       // Pending = subscribed-tailer pending (live modal) OR transcript-derived
       // pending OR pane-derived prompt (a numbered picker on screen — catches
       // questions even when the transcript isn't matched). Works for ANY session.
-      const panePrompt = isClaude ? this._panePromptMap.get(id) : null;
+      const panePrompt = this._panePromptMap.get(id) ?? null;
       const pending =
         (this._pendingMap.get(id) ?? false) ||
         !!transcript?.transcriptPending ||
@@ -670,11 +849,15 @@ export class SessionRegistry extends EventEmitter {
         cmd: win.cmd,
         isClaude,
         kind,
+        transport: kind === 'claude' ? (win.ccTransport || 'tmux') : (win.ccTransport || null),
+        endpoint: win.ccEndpoint || null,
         ccShell: !!win.ccShell, // a composer >_ sister shell pane
 
         model: ctx.model || prettyModel(transcript?.model) || null,
         ctxPct: ctx.ctxPct ?? null,
         thinking: (isClaude || kind === 'codex') ? this._thinkingMap.get(win.target) ?? false : false,
+        compacting: (isClaude || kind === 'codex') ? this._compactingMap.get(win.target) ?? false : false,
+        subAgentActive: isClaude ? this._subAgentActiveMap.get(win.target) ?? false : false,
         usagePct: transcript?.usagePct ?? null,
         usageWindowMin: transcript?.usageWindowMin ?? null,
       };
@@ -701,6 +884,7 @@ export class SessionRegistry extends EventEmitter {
       sessions.map(async (s) => {
         if (!this._tmux.isValidTarget(s.target)) return;
         try {
+          if (s.transport === 'print') return;
           const cap = await this._tmux.capturePane(s.target, 8);
           // Codex panes use the codex header/footer parser (the Claude tui.js
           // parser doesn't match codex's "model:"/footer formats). Codex has no
@@ -736,17 +920,33 @@ export class SessionRegistry extends EventEmitter {
       sessions.map(async (s) => {
         if (!this._tmux.isValidTarget(s.target)) return;
         try {
-          // Capture enough of the bottom to catch BOTH the working line ("esc to
-          // interrupt", which can sit several rows above the input box) AND a TUI
-          // question picker (parsePanePrompt scans ~18 bottom rows). One capture
-          // feeds both — keeping activity detection robust without extra execs.
-          const cap = await this._tmux.capturePane(s.target, 26);
-          const { thinking } = parseTuiStatus(cap);
+          if (s.transport === 'print') return;
+          // Capture the VISIBLE pane only (no scrollback). One capture feeds the
+          // working line ("esc to interrupt"), the TUI question picker
+          // (parsePanePrompt), and the codex prompt parse. Scrollback MUST be
+          // excluded: a `-S -N` window pulls in an already-answered picker frozen
+          // in history (still showing its ❯ cursor + "esc to cancel" footer),
+          // which re-fires the prompt after it was answered and lets stray
+          // numbered prose look like a live menu. The live picker is always on
+          // the visible screen, so visible-only is both sufficient and accurate.
+          const cap = await this._tmux.capturePane(s.target, 26, false, false, { visibleOnly: true });
+          const { thinking, compacting } = parseTuiStatus(cap);
           this._thinkingMap.set(s.target, thinking);
+          this._compactingMap.set(s.target, compacting);
           // Cache raw capture text for the content-fingerprint tiebreak in
           // the next refresh() — cheap: already captured here.
           this._paneTextCache.set(s.target, cap);
           s.thinking = thinking;
+          s.compacting = compacting;
+
+          // Sub-agent activity (Claude only) — scan the session's subagents dir so
+          // the rail's "cloning" state lights for EVERY window, not just the one a
+          // client subscribed to (the SubAgentsWatcher is subscription-scoped).
+          if (s.kind === 'claude') {
+            const subActive = hasActiveSubAgents(s.transcriptPath);
+            this._subAgentActiveMap.set(s.target, subActive);
+            s.subAgentActive = subActive;
+          }
 
           // Pane-derived question detection (Claude panes only): an on-screen
           // numbered picker means a question is waiting — even if the transcript
@@ -759,6 +959,17 @@ export class SessionRegistry extends EventEmitter {
               (this._pendingMap.get(s.target) ?? false) || rec.pending || s.pending;
             s.pending = merged;
             if (rec.pending && !s.pendingQuestion) s.pendingQuestion = rec.question;
+          } else if (s.kind === 'codex') {
+            // Pane-derived question detection for Codex panes: parseCodexPrompt
+            // detects approval modals and planning questions on screen. Feeds the
+            // same _panePromptMap so refresh() can surface the ASK sidebar icon.
+            const prompt = parseCodexPrompt(cap);
+            const rec = { pending: !!prompt, question: prompt?.question ?? null };
+            this._panePromptMap.set(s.target, rec);
+            const merged =
+              (this._pendingMap.get(s.target) ?? false) || rec.pending || s.pending;
+            s.pending = merged;
+            if (rec.pending && !s.pendingQuestion) s.pendingQuestion = rec.question;
           }
         } catch {
           // pane gone / capture failed — leave previous value
@@ -882,18 +1093,18 @@ export class SessionRegistry extends EventEmitter {
   }
 
   /**
-   * Classify each pane and resolve its claude-process start time in ONE `ps`
+   * Classify each pane and resolve its agent-process start time in ONE `ps`
    * snapshot. A pane is a Claude session iff its process subtree (from the pane
    * shell pid) contains a `claude` descendant — far more reliable than the
    * `pane_current_command` version-regex, which flips to `node`/`git` while
-   * Claude runs a tool. The same walk yields the claude start time (ms epoch)
+   * Claude runs a tool. The same walk yields the agent start time (ms epoch)
    * for the start-time matching fallback.
    *
    * Best-effort: if `ps` is unavailable every pane maps to {isClaude:false,
    * startMs:null} and callers fall back to the cmd heuristic / other passes.
    *
    * @param {import('./tmux.js').Window[]} allPanes
-   * @returns {Promise<Map<string, {isClaude: boolean, startMs: number|null}>>} target -> info
+   * @returns {Promise<Map<string, {isClaude: boolean, isCodex: boolean, kind: string|null, startMs: number|null}>>} target -> info
    */
   async _buildPaneProc(allPanes) {
     const out = new Map();
@@ -903,7 +1114,7 @@ export class SessionRegistry extends EventEmitter {
     try {
       const { stdout } = await execFile(
         'ps',
-        ['-axo', 'pid=,ppid=,etime=,comm='],
+        ['-axo', 'pid=,ppid=,etime=,comm=,args='],
         { timeout: 5000, maxBuffer: 8 * 1024 * 1024 },
       );
       rows = stdout.split('\n');
@@ -913,43 +1124,53 @@ export class SessionRegistry extends EventEmitter {
 
     /** @type {Map<number, number[]>} ppid -> child pids */
     const children = new Map();
-    /** @type {Map<number, {etime:string, comm:string}>} */
+    /** @type {Map<number, {etime:string, comm:string, args:string}>} */
     const info = new Map();
     for (const line of rows) {
-      const m = /^\s*(\d+)\s+(\d+)\s+(\S+)\s+(.*)$/.exec(line);
+      const m = /^\s*(\d+)\s+(\d+)\s+(\S+)\s+(\S+)\s*(.*)$/.exec(line);
       if (!m) continue;
       const pid = Number(m[1]);
       const ppid = Number(m[2]);
-      info.set(pid, { etime: m[3], comm: m[4] });
+      info.set(pid, { etime: m[3], comm: m[4], args: m[5] || '' });
       if (!children.has(ppid)) children.set(ppid, []);
       children.get(ppid).push(pid);
     }
 
     const now = Date.now();
-    // BFS from the pane shell pid for a `claude` or `codex` descendant; return its start.
+    // BFS from the pane shell pid for a `claude` or `codex` descendant; return its start + pid.
     const findClaude = (rootPid) => {
       const queue = [rootPid];
       const seen = new Set();
+      let codexFallback = null;
       while (queue.length) {
         const pid = queue.shift();
         if (seen.has(pid)) continue;
         seen.add(pid);
         const meta = info.get(pid);
-        if (meta && CLAUDE_COMM_RE.test(meta.comm)) {
+        if (meta && (CLAUDE_COMM_RE.test(meta.comm) || CLAUDE_ARG_RE.test(meta.args))) {
           const sec = parseEtime(meta.etime);
-          return { isClaude: true, isCodex: false, kind: 'claude', startMs: sec == null ? null : now - sec * 1000 };
+          return { isClaude: true, isCodex: false, kind: 'claude', startMs: sec == null ? null : now - sec * 1000, pid };
         }
-        if (meta && CODEX_COMM_RE.test(meta.comm)) {
+        const codexKind = meta
+          ? (CODEX_COMM_RE.test(meta.comm) ? 'direct' : codexProcessMatchKind(meta.args))
+          : null;
+        if (codexKind) {
           const sec = parseEtime(meta.etime);
-          return { isClaude: false, isCodex: true, kind: 'codex', startMs: sec == null ? null : now - sec * 1000 };
+          const codexInfo = { isClaude: false, isCodex: true, kind: 'codex', startMs: sec == null ? null : now - sec * 1000, pid };
+          // npm/nvm installs launch Codex as `node .../bin/codex`, which then
+          // spawns the native Codex child. The native child holds the rollout
+          // file open, so prefer it for lsof-based transcript binding while
+          // keeping the wrapper as a fallback when no child is visible yet.
+          if (codexKind === 'direct') return codexInfo;
+          if (!codexFallback) codexFallback = codexInfo;
         }
         for (const c of children.get(pid) ?? []) queue.push(c);
       }
-      return { isClaude: false, isCodex: false, kind: null, startMs: null };
+      return codexFallback || { isClaude: false, isCodex: false, kind: null, startMs: null, pid: null };
     };
 
     for (const p of allPanes) {
-      out.set(p.target, p.panePid ? findClaude(p.panePid) : { isClaude: false, isCodex: false, kind: null, startMs: null });
+      out.set(p.target, p.panePid ? findClaude(p.panePid) : { isClaude: false, isCodex: false, kind: null, startMs: null, pid: null });
     }
     return out;
   }

package/lib/subagents.js

@@ -37,6 +37,42 @@ const RUNNING_WINDOW_MS = 45_000;
 // (possibly premature, e.g. background-launch-ack) doneByParent flag.
 const ACTIVE_WINDOW_MS = 20_000;
 
+const SUBAGENT_JSONL_RE = /^agent-.+\.jsonl$/;
+
+/**
+ * Cheap probe: does this parent transcript have a sub-agent that's actively
+ * running RIGHT NOW? True when any agent-*.jsonl in its subagents dir was written
+ * within `windowMs` (live sub-agents append every few seconds). Used by the
+ * session poll to light the rail's "cloning" state for EVERY window — not just
+ * the one a client subscribed to (the SubAgentsWatcher is subscription-scoped).
+ * readdir + a stat per file; no tailing, no buffering. Returns false on any
+ * error / missing dir (the common no-sub-agents case, fast ENOENT).
+ *
+ * @param {string} transcriptPath  absolute path to the PARENT transcript (.jsonl)
+ * @param {number} [windowMs]
+ * @returns {boolean}
+ */
+export function hasActiveSubAgents(transcriptPath, windowMs = RUNNING_WINDOW_MS) {
+  if (!transcriptPath) return false;
+  const dir = path.join(transcriptPath.replace(/\.jsonl$/, ''), 'subagents');
+  let entries;
+  try {
+    entries = fs.readdirSync(dir);
+  } catch {
+    return false; // no subagents dir → none running
+  }
+  const cutoff = Date.now() - windowMs;
+  for (const name of entries) {
+    if (!SUBAGENT_JSONL_RE.test(name)) continue;
+    try {
+      if (fs.statSync(path.join(dir, name)).mtimeMs >= cutoff) return true;
+    } catch {
+      // file vanished between readdir and stat — skip
+    }
+  }
+  return false;
+}
+
 // ---------------------------------------------------------------------------
 // Agent definition front-matter cache + discovery
 // ---------------------------------------------------------------------------
@@ -245,6 +281,83 @@ export function _bustAgentsCache() {
   _agentsCache.clear();
 }
 
+export class CodexSubAgentsWatcher extends EventEmitter {
+  constructor() {
+    super();
+    /** @type {Map<string, {agentId:string, agentPath:string, status:'running'|'done', state:string, result:string|null, error:string|null, rawStatus:any, messages:any[], createdAtMs:number, updatedAtMs:number}>} */
+    this._agents = new Map();
+    this._stopped = false;
+  }
+
+  snapshot() {
+    return [...this._agents.values()].map((a) => this._entry(a));
+  }
+
+  poll() {
+    // Codex sub-agent notifications arrive inline via transcript/RPC events.
+  }
+
+  markDone() {
+    // Completion is driven by Codex notification status, not parent tool_result ids.
+  }
+
+  ingest(update) {
+    if (this._stopped || !update?.agentId) return null;
+    const now = Date.now();
+    const prev = this._agents.get(update.agentId);
+    const status = update.status === 'done' ? 'done' : 'running';
+    const state = update.state || status;
+    const text =
+      update.error ? `Codex sub-agent ${state}: ${update.error}` :
+      update.result ? String(update.result) :
+      state === 'running' ? 'Codex sub-agent running…' :
+      `Codex sub-agent ${state}`;
+    const message = {
+      uuid: `codex-subagent-${update.agentId}-${now}`,
+      role: 'assistant',
+      ts: update.ts ?? now,
+      blocks: [{ kind: update.error ? 'text' : 'text', text }],
+      rawType: 'codex_subagent_notification',
+    };
+    const next = {
+      agentId: update.agentId,
+      agentPath: update.agentPath,
+      status,
+      state,
+      result: update.result ?? null,
+      error: update.error ?? null,
+      rawStatus: update.rawStatus ?? null,
+      messages: prev ? [...prev.messages, message].slice(-200) : [message],
+      createdAtMs: prev?.createdAtMs ?? now,
+      updatedAtMs: now,
+    };
+    this._agents.set(update.agentId, next);
+    const entry = this._entry(next);
+    this.emit('change', entry);
+    return entry;
+  }
+
+  stop() {
+    this._stopped = true;
+    this._agents.clear();
+  }
+
+  _entry(a) {
+    return {
+      agentId: a.agentId,
+      toolUseId: null,
+      agentType: 'codex',
+      description: a.agentPath,
+      status: a.status,
+      messages: a.messages.slice(),
+      createdAt: a.createdAtMs,
+      model: null,
+      def: null,
+      nested: [],
+    };
+  }
+}
+
 export class SubAgentsWatcher extends EventEmitter {
   /**
    * @param {string} transcriptPath  absolute path to the PARENT transcript