@idl3/claude-control 0.1.2 → 0.1.3

package/lib/sessions.js

@@ -10,8 +10,17 @@
 import { EventEmitter } from 'node:events';
 import fs from 'node:fs/promises';
 import path from 'node:path';
+import { execFile as _execFile } from 'node:child_process';
+import { promisify } from 'node:util';
 
 import { parseTuiStatus, prettyModel } from './tui.js';
+import { assignTranscripts, parseEtime } from './match.js';
+import { pinKey } from './pins.js';
+
+const execFile = promisify(_execFile);
+
+// Matches Claude Code's executable basename (e.g. /Users/x/.local/bin/claude).
+const CLAUDE_COMM_RE = /(^|\/)claude$/;
 
 // 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.
@@ -151,11 +160,12 @@ async function readTail(filePath, maxBytes) {
  * Parse the tail buffer of a JSONL file and return the last record that has a
  * truthy `.cwd` field, plus basic metadata.
  *
- * @param {string} filePath  Absolute path of the .jsonl file
- * @param {number} mtime     mtime (ms since epoch) of the file
- * @returns {Promise<{cwd:string, sessionId:string|null, lastActivity:string|null, transcriptPath:string, mtime:number}|null>}
+ * @param {string} filePath     Absolute path of the .jsonl file
+ * @param {number} mtime        mtime (ms since epoch) of the file
+ * @param {number} [birthtime]  birthtime (ms since epoch) of the file
+ * @returns {Promise<object|null>}
  */
-async function extractTailRecord(filePath, mtime) {
+async function extractTailRecord(filePath, mtime, birthtime = null) {
   const buf = await readTail(filePath, TAIL_BYTES);
   if (!buf) return null;
 
@@ -169,11 +179,13 @@ async function extractTailRecord(filePath, mtime) {
     cwd: null,
     sessionId: null,
     lastActivity: null,
+    lastActivityMs: null,
     model: null,
     aiTitle: null,
     customTitle: null,
     transcriptPath: filePath,
     mtime,
+    birthtimeMs: birthtime,
     transcriptPending: false,
     pendingToolUseId: null,
     pendingQuestion: null,
@@ -196,7 +208,11 @@ async function extractTailRecord(filePath, mtime) {
     let rec;
     try { rec = JSON.parse(line); } catch { continue; }
     if (!rec || typeof rec !== 'object') continue;
-    if (base.lastActivity === null && typeof rec.timestamp === 'string') base.lastActivity = rec.timestamp;
+    if (base.lastActivity === null && typeof rec.timestamp === 'string') {
+      base.lastActivity = rec.timestamp;
+      const t = Date.parse(rec.timestamp);
+      base.lastActivityMs = Number.isNaN(t) ? null : t;
+    }
     if (base.sessionId === null && typeof rec.sessionId === 'string') base.sessionId = rec.sessionId;
     if (base.customTitle === null && rec.type === 'custom-title' && rec.customTitle) base.customTitle = rec.customTitle;
     if (base.aiTitle === null && rec.type === 'ai-title' && rec.aiTitle) base.aiTitle = rec.aiTitle;
@@ -210,40 +226,83 @@ async function extractTailRecord(filePath, mtime) {
 }
 
 // ---------------------------------------------------------------------------
-// findNewestJsonl — returns { path, mtime } or null
+// findRecentJsonl — newest-mtime *.jsonl files in a dir (top K)
 // ---------------------------------------------------------------------------
 
 /**
- * Given a directory, find the *.jsonl file with the newest mtime.
+ * Given a directory, return its `k` *.jsonl files with the newest mtime, each
+ * with `birthtimeMs`. We need more than one because multiple Claude sessions can
+ * share a directory — each needs its own transcript candidate.
  *
  * @param {string} dir
- * @returns {Promise<{filePath:string, mtime:number}|null>}
+ * @param {number} k
+ * @returns {Promise<Array<{filePath:string, mtime:number, birthtimeMs:number}>>}
  */
-async function findNewestJsonl(dir) {
+async function findRecentJsonl(dir, k) {
   let entries;
   try {
     entries = await fs.readdir(dir);
   } catch {
-    return null;
+    return [];
   }
 
-  let newest = null;
-
-  await Promise.all(
+  const stats = await Promise.all(
     entries
       .filter((e) => e.endsWith('.jsonl'))
       .map(async (e) => {
         const full = path.join(dir, e);
-        let st;
-        try { st = await fs.stat(full); } catch { return; }
-        const mtime = st.mtimeMs;
-        if (!newest || mtime > newest.mtime) {
-          newest = { filePath: full, mtime };
+        try {
+          const st = await fs.stat(full);
+          return { filePath: full, mtime: st.mtimeMs, birthtimeMs: st.birthtimeMs };
+        } catch {
+          return null;
         }
       }),
   );
 
-  return newest;
+  return stats
+    .filter(Boolean)
+    .sort((a, b) => b.mtime - a.mtime)
+    .slice(0, Math.max(1, k));
+}
+
+/**
+ * List recent transcripts across all project dirs for the manual-pin picker.
+ * Takes the newest .jsonl per project dir (bounded), tail-parses each for a
+ * title/cwd/sessionId, and returns the most recently active `limit`.
+ *
+ * @param {{ projectsRoot: string, limit?: number }} opts
+ * @returns {Promise<Array<{transcriptPath,title,sessionId,cwd,lastActivity,mtime}>>}
+ */
+export async function listRecentTranscripts({ projectsRoot, limit = 60 }) {
+  let dirs;
+  try {
+    const entries = await fs.readdir(projectsRoot, { withFileTypes: true });
+    dirs = entries.filter((e) => e.isDirectory()).map((e) => path.join(projectsRoot, e.name));
+  } catch {
+    return [];
+  }
+
+  const out = [];
+  await Promise.all(
+    dirs.map(async (dir) => {
+      const recent = await findRecentJsonl(dir, 1);
+      if (!recent.length) return;
+      const r = recent[0];
+      const rec = await extractTailRecord(r.filePath, r.mtime, r.birthtimeMs);
+      if (!rec) return;
+      out.push({
+        transcriptPath: rec.transcriptPath,
+        title: rec.customTitle || rec.aiTitle || null,
+        sessionId: rec.sessionId,
+        cwd: rec.cwd,
+        lastActivity: rec.lastActivity,
+        mtime: r.mtime,
+      });
+    }),
+  );
+
+  return out.sort((a, b) => b.mtime - a.mtime).slice(0, limit);
 }
 
 // ---------------------------------------------------------------------------
@@ -260,13 +319,15 @@ export class SessionRegistry extends EventEmitter {
     this._tmux = tmux;
     this._debounceMs = debounceMs;
 
+    /** @type {Record<string,string>} pin key (windowId.paneIndex) -> transcript path */
+    this._pins = {};
     /** @type {Session[]} */
     this._sessions = [];
     /** @type {string|null} — last JSON snapshot for change detection */
     this._lastEmitted = null;
     /** @type {Map<string, boolean>} id -> pending flag */
     this._pendingMap = new Map();
-    /** @type {Map<string, {ctxPct:number|null, model:string|null}>} windowId -> TUI status */
+    /** @type {Map<string, {ctxPct:number|null, model:string|null}>} target -> TUI status */
     this._ctxMap = new Map();
     /** @type {ReturnType<setInterval>|null} */
     this._interval = null;
@@ -283,6 +344,16 @@ export class SessionRegistry extends EventEmitter {
     return this._sessions;
   }
 
+  /**
+   * Replace the manual pin map (windowId.paneIndex -> transcript path) and
+   * re-reconcile so the change shows immediately.
+   * @param {Record<string,string>} pins
+   */
+  setPins(pins) {
+    this._pins = pins || {};
+    this.refresh().catch(() => {});
+  }
+
   /**
    * Set the pending flag for a session (called by server when tailer fires
    * 'pending'). Emits 'change' if the flag actually flipped.
@@ -307,41 +378,69 @@ export class SessionRegistry extends EventEmitter {
    * @returns {Promise<Session[]>}
    */
   async refresh() {
-    const [allWindows, transcriptIndex] = await Promise.all([
-      this._listWindows(),
-      this._buildTranscriptIndex(),
-    ]);
+    const allPanes = await this._listWindows();
 
     // Grouped tmux sessions (e.g. a `_mobile` mirror of session `0`) expose the
-    // SAME underlying window under multiple session names — identical window_id.
-    // Collapse those so the UI shows each real window once (keeping the first,
-    // which is the primary session by tmux's list ordering).
-    const seenWindowIds = new Set();
-    const windows = allWindows.filter((w) => {
-      if (seenWindowIds.has(w.windowId)) return false;
-      seenWindowIds.add(w.windowId);
+    // SAME underlying pane under multiple session names — identical
+    // (window_id, pane_index). Collapse those so the UI shows each real pane
+    // once (keeping the first, which is the primary session by tmux ordering).
+    const seenPanes = new Set();
+    const panes = allPanes.filter((p) => {
+      const key = `${p.windowId}.${p.paneIndex}`;
+      if (seenPanes.has(key)) return false;
+      seenPanes.add(key);
       return true;
     });
 
-    const sessions = windows.map((win) => {
-      // Primary match: directory-name encoding (survives mid-session `cd`).
-      // encodeCwd is lossy ('/' and '.' both -> '-'), so a byDir hit is only
-      // trusted when the cwd recorded inside the transcript is consistent with
-      // this window's cwd — equal, a descendant (the agent cd'd into a subdir),
-      // or absent. An unrelated sibling (e.g. my.lib vs my-lib) is rejected and
-      // falls through to the exact-cwd index.
-      const byDirHit = transcriptIndex.byDir.get(encodeCwd(win.cwd));
-      const transcript =
-        (byDirHit && isCwdConsistent(byDirHit.cwd, win.cwd) ? byDirHit : null) ??
-        transcriptIndex.byCwd.get(win.cwd) ??
-        null;
+    // Only Claude panes have transcripts to match (shells don't).
+    const claudePanes = panes.filter((p) => isClaudeCmd(p.cmd));
+
+    // Manual pins win first: a pinned pane is force-bound to its transcript and
+    // that transcript is removed from the auto-matcher pool. Pins are keyed by
+    // the stable windowId.paneIndex (the target renumbers; the window id doesn't).
+    const pinnedByTarget = new Map();
+    const pinnedPaths = new Set();
+    for (const p of claudePanes) {
+      const pinned = this._pins[pinKey(p.windowId, p.paneIndex)];
+      if (!pinned) continue;
+      const rec = await this._recordForPath(pinned);
+      if (rec) {
+        pinnedByTarget.set(p.target, rec);
+        pinnedPaths.add(rec.transcriptPath);
+      }
+    }
+
+    // Auto-match the rest with the deterministic 1:1 matcher (pinned panes and
+    // pinned transcripts excluded so nothing double-binds or gets stolen).
+    const autoPanes = claudePanes.filter((p) => !pinnedByTarget.has(p.target));
+    const [candidatesRaw, procStart] = await Promise.all([
+      this._buildCandidates(autoPanes),
+      this._buildProcStart(autoPanes),
+    ]);
+    const candidates = candidatesRaw.filter((c) => !pinnedPaths.has(c.transcriptPath));
+    const assignment = assignTranscripts(
+      autoPanes.map((p) => ({
+        target: p.target,
+        windowName: p.windowName,
+        cwd: p.cwd,
+        procStartMs: procStart.get(p.target) ?? null,
+      })),
+      candidates,
+    );
+    for (const [target, rec] of pinnedByTarget) assignment.set(target, rec);
+
+    const sessions = panes.map((win) => {
+      const transcript = isClaudeCmd(win.cmd)
+        ? assignment.get(win.target) ?? null
+        : null;
+      const isPinned = pinnedByTarget.has(win.target);
       const id = win.target;
       // Pending = subscribed-tailer pending (live modal) OR transcript-derived
       // pending (works for ANY session, even unsubscribed ones, for push).
       const pending =
         (this._pendingMap.get(id) ?? false) || !!transcript?.transcriptPending;
       const title = transcript?.customTitle || transcript?.aiTitle || null;
-      const ctx = this._ctxMap.get(win.windowId) || {};
+      const ctx = this._ctxMap.get(win.target) || {};
 
       return {
         id,
@@ -358,6 +457,7 @@ export class SessionRegistry extends EventEmitter {
         active: win.active,
         cwd: win.cwd,
         transcriptPath: transcript?.transcriptPath ?? null,
+        pinned: isPinned,
         lastActivity: transcript?.lastActivity ?? null,
         pending,
         pendingQuestion: transcript?.pendingQuestion ?? null,
@@ -368,33 +468,8 @@ export class SessionRegistry extends EventEmitter {
       };
     });
 
-    // Dedup transcript collisions: when multiple tmux windows share a cwd they
-    // all match the SAME newest transcript for that dir → the rail shows the
-    // same title twice and two sessions tail one file. Keep the transcript on
-    // the best (active, else first-seen) session; strip it from the others so
-    // they stay distinct, transcript-less live panes (still subscribable).
-    const seenTranscript = new Set();
-    const byPriority = [...sessions].sort((a, b) =>
-      a.active === b.active ? 0 : a.active ? -1 : 1,
-    );
-    for (const s of byPriority) {
-      if (!s.transcriptPath) continue;
-      if (seenTranscript.has(s.transcriptPath)) {
-        s.transcriptPath = null;
-        s.sessionId = null;
-        s.lastActivity = null;
-        s.title = null;
-        s.name = s.tmuxName || s.target;
-        // This session no longer owns the transcript, so its transcript-derived
-        // pending is bogus; drop it (the owning session keeps the real one).
-        s.pending = this._pendingMap.get(s.id) ?? false;
-        s.pendingQuestion = null;
-      } else {
-        seenTranscript.add(s.transcriptPath);
-      }
-    }
-
-    // Only surface Claude sessions; skip plain shell panes.
+    // Only surface Claude sessions; skip plain shell panes. (assignTranscripts
+    // already guarantees 1:1, so no post-hoc collision dedup is needed.)
     this._sessions = sessions.filter((s) => isClaudeCmd(s.cmd) || s.transcriptPath);
     this._maybeEmit();
     return this._sessions;
@@ -413,7 +488,7 @@ export class SessionRegistry extends EventEmitter {
         try {
           const cap = await this._tmux.capturePane(s.target, 8);
           const { ctxPct, model } = parseTuiStatus(cap);
-          this._ctxMap.set(s.windowId, { ctxPct, model });
+          this._ctxMap.set(s.target, { ctxPct, model });
           // Merge into the live session object without a full rebuild.
           if (ctxPct !== null) s.ctxPct = ctxPct;
           if (model) s.model = model;
@@ -468,51 +543,119 @@ export class SessionRegistry extends EventEmitter {
   }
 
   /**
-   * Scan all immediate subdirectories of projectsRoot. For each, find the
-   * newest *.jsonl and extract the last record that carries a .cwd field.
-   * Returns a Map keyed by cwd (keeping the newest mtime entry per cwd).
+   * Build the transcript candidate pool for the given Claude panes. A session's
+   * transcript lives in the project dir `encodeCwd(launchCwd)`, where launchCwd
+   * is the pane's current path. For each such dir we read the newest few
+   * transcripts (enough for every pane sharing that dir) so the matcher has a
+   * real choice when sessions collide on a directory. Tail-only reads (≤64 KB).
    *
-   * @returns {Promise<Map<string, {cwd:string, sessionId:string|null, lastActivity:string|null, transcriptPath:string, mtime:number}>>}
+   * @param {import('./tmux.js').Window[]} claudePanes
+   * @returns {Promise<object[]>} candidate records (see extractTailRecord)
    */
-  async _buildTranscriptIndex() {
-    /** @type {{byDir: Map<string, object>, byCwd: Map<string, object>}} */
-    const index = { byDir: new Map(), byCwd: new Map() };
-
-    let projectEntries;
+  /**
+   * Build a transcript record for an exact path (for manual pins). Stats the
+   * file for mtime/birthtime, then tail-parses it. Null if unreadable.
+   * @param {string} filePath
+   * @returns {Promise<object|null>}
+   */
+  async _recordForPath(filePath) {
     try {
-      const entries = await fs.readdir(this._projectsRoot, { withFileTypes: true });
-      projectEntries = entries
-        .filter((e) => e.isDirectory())
-        .map((e) => ({ name: e.name, dir: path.join(this._projectsRoot, e.name) }));
+      const st = await fs.stat(filePath);
+      return await extractTailRecord(filePath, st.mtimeMs, st.birthtimeMs);
     } catch {
-      return index;
+      return null;
+    }
+  }
+
+  async _buildCandidates(claudePanes) {
+    // dir name -> how many panes launched there (so we fetch enough candidates).
+    const dirCounts = new Map();
+    for (const p of claudePanes) {
+      const dir = encodeCwd(p.cwd);
+      dirCounts.set(dir, (dirCounts.get(dir) ?? 0) + 1);
     }
 
+    const candidates = [];
     await Promise.all(
-      projectEntries.map(async ({ name, dir }) => {
-        const newest = await findNewestJsonl(dir);
-        if (!newest) return;
+      [...dirCounts.entries()].map(async ([name, count]) => {
+        const dir = path.join(this._projectsRoot, name);
+        // A small buffer beyond the pane count tolerates resume/compaction
+        // spawning a fresh file mid-session.
+        const recent = await findRecentJsonl(dir, count + 2);
+        const recs = await Promise.all(
+          recent.map((r) =>
+            extractTailRecord(r.filePath, r.mtime, r.birthtimeMs),
+          ),
+        );
+        for (const rec of recs) if (rec) candidates.push(rec);
+      }),
+    );
 
-        const rec = await extractTailRecord(newest.filePath, newest.mtime);
-        if (!rec) return;
+    return candidates;
+  }
 
-        // Primary key: the project directory name (Claude Code's cwd encoding).
-        const byDirExisting = index.byDir.get(name);
-        if (!byDirExisting || newest.mtime > byDirExisting.mtime) {
-          index.byDir.set(name, rec);
-        }
+  /**
+   * Resolve each Claude pane's claude-process start time (ms epoch) for the
+   * start-time matching pass. One `ps` snapshot, then walk the process tree from
+   * each pane's shell pid to its `claude` descendant. Best-effort: panes whose
+   * proc can't be found map to null and fall through to other match passes.
+   *
+   * @param {import('./tmux.js').Window[]} claudePanes
+   * @returns {Promise<Map<string, number|null>>} target -> startMs
+   */
+  async _buildProcStart(claudePanes) {
+    const out = new Map();
+    if (claudePanes.length === 0) return out;
+
+    let rows;
+    try {
+      const { stdout } = await execFile(
+        'ps',
+        ['-axo', 'pid=,ppid=,etime=,comm='],
+        { timeout: 5000, maxBuffer: 8 * 1024 * 1024 },
+      );
+      rows = stdout.split('\n');
+    } catch {
+      return out; // ps unavailable — every pane falls back to null
+    }
+
+    /** @type {Map<number, number[]>} ppid -> child pids */
+    const children = new Map();
+    /** @type {Map<number, {etime:string, comm:string}>} */
+    const info = new Map();
+    for (const line of rows) {
+      const m = /^\s*(\d+)\s+(\d+)\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] });
+      if (!children.has(ppid)) children.set(ppid, []);
+      children.get(ppid).push(pid);
+    }
 
-        // Secondary key: the exact cwd recorded inside the transcript, when present.
-        if (rec.cwd) {
-          const byCwdExisting = index.byCwd.get(rec.cwd);
-          if (!byCwdExisting || newest.mtime > byCwdExisting.mtime) {
-            index.byCwd.set(rec.cwd, rec);
-          }
+    const now = Date.now();
+    const findClaudeStart = (rootPid) => {
+      // BFS for a descendant whose command basename is `claude`.
+      const queue = [rootPid];
+      const seen = new Set();
+      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)) {
+          const sec = parseEtime(meta.etime);
+          return sec == null ? null : now - sec * 1000;
         }
-      }),
-    );
+        for (const c of children.get(pid) ?? []) queue.push(c);
+      }
+      return null;
+    };
 
-    return index;
+    for (const p of claudePanes) {
+      out.set(p.target, p.panePid ? findClaudeStart(p.panePid) : null);
+    }
+    return out;
   }
 
   /**

package/lib/subagents.js

@@ -0,0 +1,154 @@
+/**
+ * lib/subagents.js — watch a session's sub-agent (Task/Agent) transcripts.
+ *
+ * Claude Code writes each sub-agent's conversation to a sibling of the parent
+ * transcript:
+ *   <project>/<sessionId>.jsonl                     ← parent
+ *   <project>/<sessionId>/subagents/agent-<id>.jsonl ← sub-agent transcript
+ *   <project>/<sessionId>/subagents/agent-<id>.meta.json
+ *       { agentType, description, toolUseId }         ← links to the parent's
+ *                                                       Task tool-call
+ *
+ * This watcher discovers those files (lazily — polled when the parent transcript
+ * grows, which is exactly when sub-agents spawn), tails each one with the same
+ * bounded TranscriptTailer the main transcript uses, and emits a 'change' event
+ * carrying the full sub-agent entry whenever it appears or grows. The server
+ * relays each entry to subscribed clients as a `subagent` frame.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { EventEmitter } from 'node:events';
+
+import { TranscriptTailer } from './transcript.js';
+
+const META_RE = /^agent-(.+)\.meta\.json$/;
+// A sub-agent whose transcript hasn't grown in this long is treated as finished,
+// even if we never saw the parent's tool_result (e.g. it predates the parent's
+// bounded message buffer). Live sub-agents append continuously.
+const RUNNING_WINDOW_MS = 45_000;
+
+export class SubAgentsWatcher extends EventEmitter {
+  /**
+   * @param {string} transcriptPath  absolute path to the PARENT transcript
+   * @param {{ maxBuffer?: number }} [opts]
+   */
+  constructor(transcriptPath, { maxBuffer = 200 } = {}) {
+    super();
+    // <project>/<sessionId>.jsonl → <project>/<sessionId>/subagents
+    this._dir = path.join(transcriptPath.replace(/\.jsonl$/, ''), 'subagents');
+    this._maxBuffer = maxBuffer;
+    /** @type {Map<string, {agentId, toolUseId, agentType, description, status, tailer}>} */
+    this._agents = new Map(); // keyed by agentId
+    this._stopped = false;
+  }
+
+  /** Current sub-agents (snapshot), each with its buffered messages. */
+  snapshot() {
+    return [...this._agents.values()].map((a) => this._entry(a));
+  }
+
+  /**
+   * Rescan the subagents dir for new agent files. Cheap; safe to call often.
+   * Call on each parent-transcript append (when sub-agents are spawned) and once
+   * at subscribe time.
+   */
+  poll() {
+    if (this._stopped) return;
+    let entries;
+    try {
+      entries = fs.readdirSync(this._dir);
+    } catch {
+      return; // dir doesn't exist yet (no sub-agents) — nothing to do
+    }
+    for (const name of entries) {
+      const m = META_RE.exec(name);
+      if (!m) continue;
+      const agentId = m[1];
+      if (this._agents.has(agentId)) continue;
+      this._track(agentId);
+    }
+  }
+
+  /**
+   * Mark a sub-agent finished (the parent transcript produced a tool_result for
+   * its toolUseId — the authoritative "done" signal). Idempotent. Accepts a Set
+   * or a single id so the server can sweep its whole buffer at subscribe time.
+   * @param {string|Set<string>} toolUseIds
+   */
+  markDone(toolUseIds) {
+    const has = (id) =>
+      toolUseIds instanceof Set ? toolUseIds.has(id) : toolUseIds === id;
+    for (const a of this._agents.values()) {
+      if (a.toolUseId && has(a.toolUseId) && !a.doneByParent) {
+        a.doneByParent = true;
+        this.emit('change', this._entry(a));
+      }
+    }
+  }
+
+  stop() {
+    this._stopped = true;
+    for (const a of this._agents.values()) a.tailer?.stop();
+    this._agents.clear();
+  }
+
+  // -- internals --
+
+  _track(agentId) {
+    const metaPath = path.join(this._dir, `agent-${agentId}.meta.json`);
+    const jsonlPath = path.join(this._dir, `agent-${agentId}.jsonl`);
+    let meta = {};
+    try {
+      meta = JSON.parse(fs.readFileSync(metaPath, 'utf8')) || {};
+    } catch {
+      return; // meta not readable yet — a later poll retries
+    }
+
+    const tailer = new TranscriptTailer(jsonlPath, { maxBuffer: this._maxBuffer });
+    const agent = {
+      agentId,
+      jsonlPath,
+      toolUseId: meta.toolUseId ?? null,
+      agentType: meta.agentType ?? null,
+      description: meta.description ?? null,
+      doneByParent: false,
+      tailer,
+    };
+    this._agents.set(agentId, agent);
+
+    tailer.on('append', () => this.emit('change', this._entry(agent)));
+    tailer.on('error', () => {}); // best-effort; a missing file just yields no messages
+    tailer
+      .start()
+      .then(() => this.emit('change', this._entry(agent)))
+      .catch(() => {});
+  }
+
+  /**
+   * Status: done if the parent confirmed it (authoritative), otherwise inferred
+   * from transcript freshness — a live sub-agent's file is actively appended; a
+   * finished one goes static. This keeps historical sub-agents correctly "done"
+   * even when their parent tool_result predates the bounded message buffer.
+   */
+  _statusFor(a) {
+    if (a.doneByParent) return 'done';
+    try {
+      const mtimeMs = fs.statSync(a.jsonlPath).mtimeMs;
+      return Date.now() - mtimeMs < RUNNING_WINDOW_MS ? 'running' : 'done';
+    } catch {
+      return 'done';
+    }
+  }
+
+  _entry(a) {
+    return {
+      agentId: a.agentId,
+      toolUseId: a.toolUseId,
+      agentType: a.agentType,
+      description: a.description,
+      status: this._statusFor(a),
+      messages: a.tailer ? a.tailer.getMessages() : [],
+    };
+  }
+}