@hienlh/ppm 0.23.8 → 0.23.10

package/src/providers/codex-app-server/codex-rollout-tail-parser.ts

@@ -0,0 +1,203 @@
+import type { ChatEvent } from "../provider.interface.ts";
+import { stripSharedContext } from "../../shared/provider-context.ts";
+import { redactTruncate } from "./codex-redact.ts";
+import { completeLines, parseLine } from "./codex-rollout-header.ts";
+import { mapRolloutItem } from "./codex-rollout-items.ts";
+import { subagentToolResult, subagentToolUse } from "./codex-subagent-thread.ts";
+import {
+  customToolCallToToolUse, fnCallToToolUse, fnOutputToToolResult, genericCallToToolUse,
+} from "./codex-history.ts";
+
+/**
+ * Line-fed parser for ONE codex rollout, for the live Agent-session window.
+ *
+ * Unlike `rolloutMessageSteps` (`codex-history.ts`) this never groups events
+ * into user/assistant turns and never answers a "load more" request — it just
+ * turns each newly-written record into flat step events, in the order they
+ * were written, as the file grows. It must never change how history renders,
+ * so it is a separate reader over the same schema rather than a refactor of
+ * the existing one.
+ *
+ * A child rollout writes its OWN `session_meta` first and its parent's second
+ * (a forked context) — only the first describes the file, so every session_meta
+ * after the first is ignored entirely here, the same as `readRolloutHeader` does.
+ */
+
+/**
+ * First cli_version observed (2026-10-01 survey of ~3400 local rollouts)
+ * writing the newer `item_completed` record instead of the legacy
+ * `response_item` pairs. Below this, a file is read the legacy way; at or
+ * above it, or when the version cannot be read at all, the newer/default path
+ * is used — an older writer's rollout has nothing later versions removed, so
+ * reading it as the newer shape would just find no item_completed records and
+ * emit nothing.
+ */
+const FIRST_ITEM_EVENTS_CLI_VERSION = "0.154.0";
+
+function isOlderThan(version: string, floor: string): boolean {
+  const parts = (v: string) => v.split(".").map((n) => Number.parseInt(n, 10) || 0);
+  const a = parts(version);
+  const b = parts(floor);
+  for (let i = 0; i < Math.max(a.length, b.length); i++) {
+    const diff = (a[i] ?? 0) - (b[i] ?? 0);
+    if (diff !== 0) return diff < 0;
+  }
+  return false;
+}
+
+/** One step, wire-ready for `/ws/global` push. */
+export interface TailEventEnvelope {
+  ev: ChatEvent;
+  /** Epoch ms, from the record's own timestamp (carried forward when absent). */
+  ts: number;
+  /** A later event reusing a `toolUseId` already emitted — the client updates
+   *  that step in place (a tool_result answering an earlier tool_use is the
+   *  common case) instead of appending a new one. */
+  replace?: boolean;
+}
+
+export interface TailFeedResult {
+  events: TailEventEnvelope[];
+  /** The file rewrote its own history (compaction / rollback): the caller must
+   *  drop everything it has for this parser and re-read the file from byte 0. */
+  reset?: boolean;
+  /** Thread ids of subagents spawned since the previous `feed()` call, so the
+   *  caller can start tailing their rollouts alongside this one. */
+  links: string[];
+}
+
+/** Redact the input of a tool_use whose tool name is an unmapped item/call
+ *  type verbatim — the generic fallback that would otherwise carry through
+ *  whatever fields an unrecognized record happened to have, unredacted. */
+function redactIfGeneric(ev: ChatEvent, rawType: string): ChatEvent {
+  if (ev.type === "tool_use" && ev.tool === rawType) {
+    return { ...ev, input: redactTruncate(ev.input) };
+  }
+  return ev;
+}
+
+/** Always-generic legacy-path call (its tool name already comes from `p.name`,
+ *  there is nothing more specific to compare it against). */
+function redactGenericCall(ev: ChatEvent): ChatEvent {
+  return ev.type === "tool_use" ? { ...ev, input: redactTruncate(ev.input) } : ev;
+}
+
+export function createRolloutTailParser(): { feed(chunk: string): TailFeedResult } {
+  // Raw text not yet terminated by a newline — carried to the next feed() call
+  // rather than parsed early, so a chunk boundary landing mid-line (or mid
+  // multi-byte character) never produces a corrupt partial record.
+  let pending = "";
+  let headerSeen = false;
+  let format: "item-events" | "legacy" = "item-events";
+  const seenIds = new Set<string>();
+  let lastTs = 0;
+
+  function resolveTs(raw: unknown): number {
+    if (typeof raw === "string") {
+      const parsed = Date.parse(raw);
+      if (!Number.isNaN(parsed)) { lastTs = parsed; return parsed; }
+    }
+    return lastTs;
+  }
+
+  function push(out: TailEventEnvelope[], ev: ChatEvent, ts: number): void {
+    const id = "toolUseId" in ev ? ev.toolUseId : undefined;
+    if (id) {
+      if (seenIds.has(id)) { out.push({ ev, ts, replace: true }); return; }
+      seenIds.add(id);
+    }
+    out.push({ ev, ts });
+  }
+
+  function reset(out: TailEventEnvelope[]): void {
+    // The window is about to be rebuilt from byte 0, so every id emitted so
+    // far is no longer "already sent" from the caller's point of view either.
+    seenIds.clear();
+    out.length = 0;
+  }
+
+  function feed(chunk: string): TailFeedResult {
+    pending += chunk;
+    const lastNl = pending.lastIndexOf("\n");
+    const ready = lastNl >= 0 ? pending.slice(0, lastNl + 1) : "";
+    pending = lastNl >= 0 ? pending.slice(lastNl + 1) : pending;
+
+    const out: TailEventEnvelope[] = [];
+    const links: string[] = [];
+    const linkSeen = new Set<string>();
+    let didReset = false;
+
+    for (const line of completeLines(ready)) {
+      const rec = parseLine(line);
+      if (!rec) continue;
+      const p = rec.payload ?? {};
+      const ts = resolveTs(rec.timestamp);
+
+      if (rec.type === "session_meta") {
+        if (!headerSeen) {
+          headerSeen = true;
+          const cliVersion = typeof p.cli_version === "string" ? p.cli_version : undefined;
+          format = cliVersion && isOlderThan(cliVersion, FIRST_ITEM_EVENTS_CLI_VERSION) ? "legacy" : "item-events";
+        }
+        continue;
+      }
+
+      if (rec.type === "compacted") {
+        reset(out);
+        didReset = true;
+        continue;
+      }
+
+      if (rec.type === "event_msg") {
+        if (p.type === "thread_rolled_back") {
+          reset(out);
+          didReset = true;
+          continue;
+        }
+        if (p.type === "user_message" && typeof p.message === "string") {
+          push(out, { type: "text", content: stripSharedContext(p.message) }, ts);
+          continue;
+        }
+        if (p.type === "agent_message" && typeof p.message === "string") {
+          push(out, { type: "text", content: p.message }, ts);
+          continue;
+        }
+        if (p.type === "item_completed" && format === "item-events") {
+          const item = p.item;
+          const rawType = item && typeof item === "object" && typeof (item as Record<string, unknown>).type === "string"
+            ? (item as Record<string, unknown>).type as string
+            : "";
+          const mapped = mapRolloutItem(item);
+          if (mapped.kind === "user") {
+            push(out, { type: "text", content: stripSharedContext(mapped.text) }, ts);
+          } else if (mapped.kind === "assistant") {
+            push(out, { type: "text", content: mapped.text }, ts);
+          } else if (mapped.kind === "events") {
+            for (const ev of mapped.events) push(out, redactIfGeneric(ev, rawType), ts);
+          } else if (mapped.kind === "subagent") {
+            const { activity } = mapped;
+            if (!linkSeen.has(activity.threadId)) { linkSeen.add(activity.threadId); links.push(activity.threadId); }
+            // No `children`: the window renders nested agents flat, following
+            // in timestamp order as their own steps rather than nested inline.
+            push(out, activity.done ? subagentToolResult(activity) : subagentToolUse(activity), ts);
+          }
+          continue;
+        }
+        continue;
+      }
+
+      if (rec.type === "response_item" && format === "legacy") {
+        if (p.type === "function_call") push(out, fnCallToToolUse(p), ts);
+        else if (p.type === "function_call_output") push(out, fnOutputToToolResult(p), ts);
+        else if (p.type === "custom_tool_call") push(out, customToolCallToToolUse(p), ts);
+        else if (p.type === "custom_tool_call_output") push(out, fnOutputToToolResult(p), ts);
+        else if (typeof p.type === "string" && p.type.endsWith("_call_output")) push(out, fnOutputToToolResult(p), ts);
+        else if (typeof p.type === "string" && p.type.endsWith("_call")) push(out, redactGenericCall(genericCallToToolUse(p)), ts);
+      }
+    }
+
+    return { events: out, links, ...(didReset ? { reset: true as const } : {}) };
+  }
+
+  return { feed };
+}

package/src/providers/codex-app-server/codex-subagent-thread.ts

@@ -62,7 +62,12 @@ export function subagentCardId(threadId: string): string {
   return `subagent-${threadId}`;
 }
 
-/** The spawn, as the Agent card the chat already knows how to expand. */
+/** The spawn, as the Agent card the chat already knows how to expand.
+ *
+ * `transcript` is only ever passed by a history reader that already found and parsed the
+ * child's rollout — live streaming (`codex-event-mapper.ts`) and the tail parser call this
+ * with none, so `transcriptAvailable` stays unset there and the chat keeps this card's full
+ * live children instead of slimming away a source it cannot later stream from disk. */
 export function subagentToolUse(activity: SubagentActivity, transcript?: SubagentTranscript | null): ChatEvent {
   return {
     type: "tool_use",
@@ -70,6 +75,7 @@ export function subagentToolUse(activity: SubagentActivity, transcript?: Subagen
     input: { description: activity.path },
     toolUseId: subagentCardId(activity.threadId),
     ...(transcript?.events.length ? { children: transcript.events } : {}),
+    ...(transcript ? { transcriptAvailable: true } : {}),
   };
 }
 

package/src/server/index.ts

@@ -926,8 +926,13 @@ if (process.argv.includes("__serve__")) {
 
       if (url.pathname === "/ws/global") {
         // App-wide event bus: owns file watching + cross-cutting broadcasts, so
-        // they no longer depend on a chat tab being mounted.
-        const upgraded = server.upgrade(req, { data: { type: "global" } });
+        // they no longer depend on a chat tab being mounted. The token is
+        // snapshotted here — not re-read from config on every push — so the
+        // agent-transcript hub can tell a long-lived socket apart from one
+        // whose password/token has since been rotated.
+        const authConfig = configService.get("auth");
+        const token = authConfig.enabled ? (url.searchParams.get("token") ?? null) : null;
+        const upgraded = server.upgrade(req, { data: { type: "global", token } });
         if (upgraded) return undefined;
         return new Response("WebSocket upgrade failed", { status: 400 });
       }

package/src/server/routes/chat.ts

@@ -24,6 +24,8 @@ import { aggregateTasks } from "../../services/task-status-aggregator.ts";
 import { MANY_IMAGE_DIMENSION_LIMIT, type StripMode } from "../../services/transcript-images.ts";
 import { auditTranscriptImagesFile, stripTranscriptImagesFile } from "../../services/transcript-images-file.ts";
 import { listCodexAccounts } from "../../services/codex-account.service.ts";
+import { codexUsageSource } from "../../providers/codex-app-server/codex-usage-source.ts";
+import { invalidateUsage, refreshUsage, registerUsageSource } from "../../services/provider-usage/usage-registry.ts";
 import { findRolloutByThreadId } from "../../providers/codex-app-server/codex-history.ts";
 import { getSessionProjectPath, setSessionMetadata, setSessionTitle, getSessionTitle, getPinnedSessionIds, pinSession, unpinSession, deleteSessionMapping, deleteSessionMetadata, deleteSessionTitle, getAllUnread, clearSessionUnread, setSessionUnread } from "../../services/db.service.ts";
 import { setSessionTag, bulkSetSessionTag, getTagById, getSessionTags, getProjectDefaultTagId } from "../../services/tag.service.ts";
@@ -104,13 +106,19 @@ chatRoutes.get("/usage", async (c) => {
   const sessionId = c.req.query("session");
   const accountId = c.req.query("accountId");
   if (c.req.query("refresh")) {
-    // `?refresh=1` is the user pressing refresh, so drop the cached value first — otherwise
-    // a provider's own getUsage answers from cache and the button does nothing visible.
     if (providerId && providerId !== "claude") {
       const provider = providerRegistry.get(providerId);
       if (provider?.getUsage) {
-        const { invalidateUsage } = await import("../../services/provider-usage/usage-registry.ts");
-        invalidateUsage(providerId);
+        if (providerId === "codex") {
+          // A memory-only invalidation promotes an old database snapshot on the next read.
+          // Fetch every account live; parallel reads stay within the client's 30s timeout.
+          registerUsageSource(codexUsageSource);
+          const accounts = codexUsageSource.listAccountIds();
+          const ids = accounts.length > 0 ? accounts : [""];
+          await Promise.all(ids.map((id) => refreshUsage("codex", id)));
+        } else {
+          invalidateUsage(providerId);
+        }
       }
     } else {
       try { await refreshUsageNow(); } catch { /* use stale cache */ }

package/src/server/ws/global.ts

@@ -21,10 +21,20 @@ import { startWatching, stopWatching, onFileChange } from "../../services/file-w
 import { configService } from "../../services/config.service.ts";
 import { onDesignEvent } from "../../services/design/design-events.ts";
 import { resolve } from "node:path";
+import {
+  handleAgentActivitySubscribe, handleAgentActivityUnsubscribe,
+  handleAgentTranscriptClientClosed, handleAgentTranscriptPing,
+  handleAgentTranscriptSubscribe, handleAgentTranscriptUnsubscribe,
+} from "../../services/agent-transcript/agent-transcript-hub.ts";
+import type {
+  AgentActivitySubscribeMsg, AgentActivityUnsubscribeMsg,
+  AgentTranscriptSubscribeMsg, AgentTranscriptUnsubscribeMsg,
+} from "../../shared/agent-transcript-protocol.ts";
 
 type GlobalWsSocket = {
-  data: { type: string };
-  send: (data: string) => void;
+  /** Auth token snapshotted at upgrade (`server/index.ts`) — re-checked on every agent-transcript push. */
+  data: { type: string; token?: string | null };
+  send: (data: string) => number;
 };
 
 const clients = new Set<GlobalWsSocket>();
@@ -102,11 +112,17 @@ export const globalWebSocket = {
       return;
     }
     // Sent on connect and whenever the active project changes.
-    if (msg.type === "watch") setWatch(ws, msg.projectName ?? "");
+    if (msg.type === "watch") return setWatch(ws, msg.projectName ?? "");
+    if (msg.type === "agent-transcript:subscribe") return handleAgentTranscriptSubscribe(ws, msg as AgentTranscriptSubscribeMsg);
+    if (msg.type === "agent-transcript:unsubscribe") return handleAgentTranscriptUnsubscribe(ws, msg as AgentTranscriptUnsubscribeMsg);
+    if (msg.type === "agent-activity:subscribe") return handleAgentActivitySubscribe(ws, msg as AgentActivitySubscribeMsg);
+    if (msg.type === "agent-activity:unsubscribe") return handleAgentActivityUnsubscribe(ws, msg as AgentActivityUnsubscribeMsg);
+    if (msg.type === "ping") return handleAgentTranscriptPing(ws);
   },
 
   close(ws: GlobalWsSocket) {
     releaseWatch(ws);
+    handleAgentTranscriptClientClosed(ws);
     clients.delete(ws);
   },
 };

package/src/services/agent-transcript/agent-transcript-activity.ts

@@ -0,0 +1,72 @@
+/**
+ * "Who is running right now" for one session, for the running-agents bar.
+ * Liveness is decided from transcript write time on disk, never from chat
+ * state in memory — the same signal `member-activity.service.ts` already uses
+ * for the team panel, so a resumed, backgrounded or reopened session reads the
+ * same way as one still streaming live.
+ */
+import { join } from "node:path";
+import { getCachedSubagentGroups, getCachedTranscriptsByMember } from "./agent-transcript-index-cache.ts";
+import { scanCodexDescendants } from "./agent-transcript-codex-activity.ts";
+import { summarizeTranscriptTail } from "../team-member-activity/transcript-tail-summary.ts";
+import { subagentCardId } from "../../providers/codex-app-server/codex-subagent-thread.ts";
+import type { OwnedSession } from "./session-ownership.ts";
+import { ACTIVITY_WINDOW_MS, type AgentTranscriptRunningEntry } from "../../shared/agent-transcript-protocol.ts";
+
+function lastStepLabel(tail: Awaited<ReturnType<typeof summarizeTranscriptTail>>): string | undefined {
+  return tail.lastNarrative ?? tail.lastTool;
+}
+
+async function claudeActivity(owned: OwnedSession, now: number): Promise<AgentTranscriptRunningEntry[]> {
+  const subagentsDir = join(owned.claude!.sessionDir, "subagents");
+  const groups = getCachedSubagentGroups(subagentsDir);
+  const out: AgentTranscriptRunningEntry[] = [];
+
+  for (const [cardId, entries] of groups) {
+    let newest = entries[0];
+    for (const e of entries) if (e.modifiedAt > newest!.modifiedAt) newest = e;
+    if (!newest || now - newest.modifiedAt > ACTIVITY_WINDOW_MS) continue;
+    const tail = await summarizeTranscriptTail(newest.transcriptPath);
+    out.push({ cardId, lastWriteAt: newest.modifiedAt, lastStep: lastStepLabel(tail) });
+  }
+
+  // A team is itself a session: its members carry no toolUseId (they are not
+  // card-spawned), so they never appear in `groups` above and need their own pass.
+  for (const [memberName, entry] of getCachedTranscriptsByMember(subagentsDir)) {
+    if (!entry.sizeBytes || now - entry.modifiedAt > ACTIVITY_WINDOW_MS) continue;
+    const tail = await summarizeTranscriptTail(entry.transcriptPath);
+    out.push({ memberName, lastWriteAt: entry.modifiedAt, lastStep: lastStepLabel(tail) });
+  }
+
+  return out;
+}
+
+function codexActivity(owned: OwnedSession, now: number): AgentTranscriptRunningEntry[] {
+  const { path, dirs } = owned.codex!;
+  const descendants = scanCodexDescendants(path, dirs, owned.projectPath);
+  const out: AgentTranscriptRunningEntry[] = [];
+  for (const d of descendants) {
+    // Age out on staleness alone, not "done AND stale": a child that crashed
+    // before ever writing its own completed record would otherwise show as
+    // running forever, since `done` would never become true for it.
+    if (now - d.lastWriteAt > ACTIVITY_WINDOW_MS) continue;
+    out.push({ cardId: subagentCardId(d.threadId), lastWriteAt: d.lastWriteAt, lastStep: d.lastStep });
+  }
+  return out;
+}
+
+/** Test-only: counts calls to `computeRunningAgents`, so a test can prove the
+ *  hub computes this once per tick and fans the SAME result out to every
+ *  subscriber, rather than recomputing it once per subscriber. */
+let callCountForTest = 0;
+export function _resetComputeRunningAgentsCallCountForTest(): void {
+  callCountForTest = 0;
+}
+export function _computeRunningAgentsCallCountForTest(): number {
+  return callCountForTest;
+}
+
+export async function computeRunningAgents(owned: OwnedSession, now: number): Promise<AgentTranscriptRunningEntry[]> {
+  callCountForTest++;
+  return owned.providerId === "claude" ? claudeActivity(owned, now) : codexActivity(owned, now);
+}

package/src/services/agent-transcript/agent-transcript-codex-activity.ts

@@ -0,0 +1,161 @@
+/**
+ * Codex side of the running-agents feed: which threads the session has spawned,
+ * and what each was last doing — read from bounded tails, not full parses.
+ *
+ * A direct child's spawn/completion is recorded as a `SubAgentActivity` item
+ * in the ROOT session's own rollout (not in the child's file), so discovering
+ * "what has this session spawned" means reading a slice of the root rollout
+ * itself. A grandchild's spawn is recorded the same way, but inside the
+ * child's own rollout — so once a child is known, its tail is read the same
+ * way to find further descendants, bounded in both count and depth so a
+ * runaway spawn loop cannot make this unbounded work.
+ */
+import { dirname } from "node:path";
+import { cachedReadTailText, mtimeOf } from "./agent-transcript-codex-tail-cache.ts";
+import { agentTranscriptClock } from "./agent-transcript-hub-clock.ts";
+import { completeLines, parseLine } from "../../providers/codex-app-server/codex-rollout-header.ts";
+import { parseSubagentActivity } from "../../providers/codex-app-server/codex-subagent-thread.ts";
+import { mapRolloutItem } from "../../providers/codex-app-server/codex-rollout-items.ts";
+import { findRolloutByThreadId, isCodexRolloutPath } from "../../providers/codex-app-server/codex-history.ts";
+import { INDEX_REFRESH_MS } from "../../shared/agent-transcript-protocol.ts";
+
+/** How many spawn levels deep the descendant scan follows before giving up. */
+const MAX_DESCENDANT_DEPTH = 8;
+/** Hard cap so a runaway spawn loop cannot make this scan unbounded. */
+const MAX_DESCENDANTS = 64;
+
+/**
+ * `findRolloutByThreadId` walks every rollout under a dir with a recursive
+ * `readdirSync` — fine for a one-off lookup, not for one per descendant on a
+ * 3s activity tick with a thousand-rollout `~/.codex/sessions`. Cached by
+ * (dir, threadId) for the same window the index cache uses elsewhere, and a
+ * miss is cached too so a thread that never resolves doesn't re-scan forever.
+ */
+const FILE_LOOKUP_TTL_MS = INDEX_REFRESH_MS;
+const MAX_LOOKUP_CACHE_ENTRIES = 1000;
+interface LookupEntry { expiresAt: number; file: string | null; }
+const lookupCache = new Map<string, LookupEntry>();
+
+function evictLookupCacheIfOverCapacity(now: number): void {
+  if (lookupCache.size < MAX_LOOKUP_CACHE_ENTRIES) return;
+  for (const [key, entry] of lookupCache) {
+    if (entry.expiresAt <= now) lookupCache.delete(key);
+  }
+  while (lookupCache.size >= MAX_LOOKUP_CACHE_ENTRIES) {
+    const oldest = lookupCache.keys().next().value;
+    if (oldest === undefined) break;
+    lookupCache.delete(oldest);
+  }
+}
+
+function cachedFindRolloutByThreadId(dir: string, threadId: string, projectPath: string): string | null {
+  const now = agentTranscriptClock.now();
+  const key = `${dir}\0${threadId}`;
+  const hit = lookupCache.get(key);
+  if (hit && hit.expiresAt > now) return hit.file;
+  evictLookupCacheIfOverCapacity(now);
+  const file = findRolloutByThreadId(dir, threadId, projectPath);
+  lookupCache.set(key, { expiresAt: now + FILE_LOOKUP_TTL_MS, file });
+  return file;
+}
+
+/** Test-only: forget every cached lookup. */
+export function _resetCodexDescendantLookupCache(): void {
+  lookupCache.clear();
+}
+
+export interface CodexDescendant {
+  threadId: string;
+  path: string;
+  done: boolean;
+  lastWriteAt: number;
+  lastStep?: string;
+}
+
+/** A short, one-line label for the most recent tool call in a tail of rollout records. */
+function lastStepFromLines(lines: string[]): string | undefined {
+  let label: string | undefined;
+  for (const line of lines) {
+    const rec = parseLine(line);
+    if (!rec || rec.type !== "event_msg") continue;
+    const p = rec.payload ?? {};
+    if (p.type !== "item_completed") continue;
+    const mapped = mapRolloutItem(p.item);
+    if (mapped.kind !== "events") continue;
+    for (const ev of mapped.events) {
+      if (ev.type === "tool_use") label = ev.tool;
+      else if (ev.type === "text" && ev.content.trim()) label = ev.content.trim().split("\n")[0]!.slice(0, 160);
+    }
+  }
+  return label;
+}
+
+/** `SubAgentActivity` items in a tail of rollout records, most-recent state per thread. */
+function subagentActivityFromLines(lines: string[]): Map<string, boolean> {
+  const byThread = new Map<string, boolean>();
+  for (const line of lines) {
+    const rec = parseLine(line);
+    if (!rec || rec.type !== "event_msg") continue;
+    const p = rec.payload ?? {};
+    if (p.type !== "item_completed") continue;
+    const activity = parseSubagentActivity(p.item);
+    if (activity) byThread.set(activity.threadId, activity.done);
+  }
+  return byThread;
+}
+
+/**
+ * Descendant threads of one rollout file (direct children when `rolloutPath`
+ * is the session's own root, grandchildren when it is an already-known
+ * child), each resolved to its own file and last-write time.
+ */
+function directDescendants(rolloutPath: string, dirs: string[], projectPath: string): CodexDescendant[] {
+  const tail = cachedReadTailText(rolloutPath);
+  if (!tail) return [];
+  const lines = completeLines(tail.text);
+  const activity = subagentActivityFromLines(lines);
+  const out: CodexDescendant[] = [];
+  // A child almost always lands in the same spawn-day folder as the rollout
+  // that spawned it — trying that folder first turns the common case into a
+  // readdir of a few dozen files instead of the whole sessions tree, with the
+  // full dir list (each itself cached) still there as a fallback.
+  const searchDirs = [dirname(rolloutPath), ...dirs];
+  for (const [threadId, done] of activity) {
+    let file: string | null = null;
+    for (const dir of searchDirs) {
+      const found = cachedFindRolloutByThreadId(dir, threadId, projectPath);
+      if (found && isCodexRolloutPath(found)) { file = found; break; }
+    }
+    if (!file) continue;
+    const childTail = cachedReadTailText(file);
+    out.push({
+      threadId,
+      path: file,
+      done,
+      lastWriteAt: mtimeOf(file),
+      lastStep: childTail ? lastStepFromLines(completeLines(childTail.text)) : undefined,
+    });
+  }
+  return out;
+}
+
+/**
+ * Every descendant of `rootRolloutPath`, discovered breadth-first up to
+ * `MAX_DESCENDANT_DEPTH` levels and `MAX_DESCENDANTS` total threads.
+ */
+export function scanCodexDescendants(rootRolloutPath: string, dirs: string[], projectPath: string): CodexDescendant[] {
+  const seen = new Map<string, CodexDescendant>();
+  let frontier = [rootRolloutPath];
+  for (let depth = 0; depth < MAX_DESCENDANT_DEPTH && frontier.length > 0 && seen.size < MAX_DESCENDANTS; depth++) {
+    const next: string[] = [];
+    for (const path of frontier) {
+      for (const d of directDescendants(path, dirs, projectPath)) {
+        if (seen.has(d.threadId) || seen.size >= MAX_DESCENDANTS) continue;
+        seen.set(d.threadId, d);
+        next.push(d.path);
+      }
+    }
+    frontier = next;
+  }
+  return [...seen.values()];
+}

package/src/services/agent-transcript/agent-transcript-codex-tail-cache.ts

@@ -0,0 +1,85 @@
+/**
+ * Cached "read the tail of this rollout as text" for the Codex side of the
+ * running-agents feed. Split out of `agent-transcript-codex-activity.ts` to
+ * keep both files within the project's file-size guideline.
+ *
+ * The activity feed polls every 3s whether or not a descendant's rollout
+ * actually changed; re-reading 256KB of an unchanged file on every one of
+ * those ticks (up to 64 descendants deep) is exactly the "still cheap when
+ * idle" invariant this cache exists to protect. A result is only ever
+ * reused when the file's size AND mtime both still match what was read.
+ */
+import { statSync } from "node:fs";
+import { agentTranscriptFsIo, statSizeSafe } from "./agent-transcript-fs-io.ts";
+
+const TAIL_BYTES = 256 * 1024;
+const MAX_TAIL_READ_CACHE_ENTRIES = 1000;
+
+export function mtimeOf(path: string): number {
+  try {
+    return statSync(path).mtimeMs;
+  } catch {
+    return 0;
+  }
+}
+
+/**
+ * Read the tail of a file as text, dropping a possibly-partial first line.
+ * Never throws — a file that vanishes or locks up between the stat and the
+ * read (this runs on a 3s ticker, unattended) degrades to "nothing read"
+ * rather than reaching the caller and, through it, an un-awaited tick
+ * promise with nothing to catch its rejection.
+ */
+function readTailText(path: string): { text: string; size: number } | null {
+  const size = statSizeSafe(path);
+  if (size === null) return null;
+  const start = Math.max(0, size - TAIL_BYTES);
+  let buf: Buffer;
+  try {
+    buf = agentTranscriptFsIo.readRange(path, start, size - start);
+  } catch {
+    return null;
+  }
+  const text = buf.toString("utf8");
+  // A mid-file read almost always starts inside a record; `completeLines`
+  // already drops an unterminated trailing line, this drops the stray
+  // leading one the same way a truncated head would.
+  return { text: start > 0 ? text.slice(text.indexOf("\n") + 1) : text, size };
+}
+
+interface TailReadCacheEntry {
+  size: number;
+  mtimeMs: number;
+  result: { text: string; size: number } | null;
+}
+const tailReadCache = new Map<string, TailReadCacheEntry>();
+
+function evictTailReadCacheIfOverCapacity(): void {
+  if (tailReadCache.size < MAX_TAIL_READ_CACHE_ENTRIES) return;
+  const oldest = tailReadCache.keys().next().value;
+  if (oldest !== undefined) tailReadCache.delete(oldest);
+}
+
+/**
+ * `readTailText`, but skips the 256KB read entirely when the file's size
+ * and mtime match what was read on a previous tick.
+ */
+export function cachedReadTailText(path: string): { text: string; size: number } | null {
+  const size = statSizeSafe(path);
+  if (size === null) {
+    tailReadCache.delete(path);
+    return null;
+  }
+  const mtimeMs = mtimeOf(path);
+  const hit = tailReadCache.get(path);
+  if (hit && hit.size === size && hit.mtimeMs === mtimeMs) return hit.result;
+  const result = readTailText(path);
+  evictTailReadCacheIfOverCapacity();
+  tailReadCache.set(path, { size, mtimeMs, result });
+  return result;
+}
+
+/** Test-only: forget every cached tail read. */
+export function _resetCodexTailReadCache(): void {
+  tailReadCache.clear();
+}