@cat-factory/executor-harness 1.50.12 → 1.50.14

package/dist/agent-runner.js

@@ -5,7 +5,7 @@ import { dirname, join } from 'node:path';
 import { claudeAssistantContent, claudeCallUsage, isObject, numberOf, redactBody, } from './claude-stream.js';
 import { killChildProcess, spawnDetached } from './process.js';
 import { redact, secretsToRedact } from './redact.js';
-import { createSliceTracker, startSubagentWatcher } from './subagents.js';
+import { createSliceTracker, pickProgress, startSubagentWatcher } from './subagents.js';
 import { assertOnboardingKeysCurrent, writeOnboardingPreseed } from './onboarding-preseed.js';
 import { retainSessionTranscripts } from './transcript-retention.js';
 /**
@@ -219,17 +219,19 @@ export async function runClaudeCode(opts) {
             { role: 'user', content: opts.userPrompt },
         ];
     const calls = [];
-    // ADR 0026 D2.1: derive slice progress from the parent stream's `Task` dispatches +
-    // their terminal tool_results (both DO appear here — only a subagent's intermediate
-    // turns don't). A real parent TodoWrite plan, when the agent writes one, wins; the
-    // slice-derived progress is the fallback for the parallel-subagent shape that writes no
-    // parent plan (the pr-reviewer failure this fixes).
+    // ADR 0026 D2.1 + ADR 0027 Defect B: surface live slice progress from TWO reconciled
+    // sources. The parent's `Task` dispatches + their terminal tool_results DO appear on this
+    // stream (only a subagent's intermediate turns don't), so `sliceTracker` derives per-slice
+    // progress for the parallel-subagent shape; a parent `TodoWrite` plan (the sequential
+    // shape) is tracked in `lastTodo`. `pickProgress` picks whichever is further along on each
+    // update, so neither masks the other — the pr-reviewer prompt writes its todo plan ONCE
+    // and never marks it done, which used to gate the slice signal off and pin progress at 0%.
     const sliceTracker = createSliceTracker();
-    let sawTodoPlan = false;
-    const emitSliceProgress = () => {
-        if (sawTodoPlan || !opts.onProgress)
+    let lastTodo;
+    const emitProgress = () => {
+        if (!opts.onProgress)
             return;
-        const progress = sliceTracker.progress();
+        const progress = pickProgress(lastTodo, sliceTracker.progress());
         if (progress)
             opts.onProgress(progress);
     };
@@ -242,19 +244,14 @@ export async function runClaudeCode(opts) {
             stats.assistantChars += text.length;
             stats.toolCalls += toolUses;
             for (const block of content) {
-                if (isObject(block) &&
-                    block.type === 'tool_use' &&
-                    block.name === 'TodoWrite' &&
-                    opts.onProgress) {
+                if (isObject(block) && block.type === 'tool_use' && block.name === 'TodoWrite') {
                     const progress = todosToProgress(block.input?.todos);
-                    if (progress) {
-                        sawTodoPlan = true;
-                        opts.onProgress(progress);
-                    }
+                    if (progress)
+                        lastTodo = progress;
                 }
             }
             sliceTracker.onAssistant(content);
-            emitSliceProgress();
+            emitProgress();
             // Record this call BEFORE appending its turn: the prompt is the history that
             // produced this response. The append-only array keeps each call's prompt a strict
             // prefix of the next, so the backend's telemetry chain delta-compresses cleanly.
@@ -277,7 +274,7 @@ export async function runClaudeCode(opts) {
             const content = event.message.content;
             if (Array.isArray(content)) {
                 sliceTracker.onUser(content);
-                emitSliceProgress();
+                emitProgress();
                 messages.push({ role: 'tool', content });
             }
         }
@@ -337,13 +334,16 @@ export async function runClaudeCode(opts) {
                 }
                 : { CLAUDE_CODE_OAUTH_TOKEN: opts.subscriptionToken }),
         };
-    // ADR 0026 D2.1/D3: while the run is live, tail the CLI's `subagents/*.jsonl`
-    // transcripts (under the isolated config home) so a parallel-subagent review keeps the
-    // inactivity heartbeat alive (any new bytes ⇒ `onActivity`) and its otherwise-invisible
-    // token spend is lifted into the run's telemetry. Ambient mode has no isolated home to
-    // watch. Best-effort — a missing/renamed transcript layout just yields no extra signal.
+    // ADR 0026 D3 (path corrected by ADR 0027 Defect A): while the run is live, tail the CLI's
+    // subagent `*.jsonl` transcripts so a parallel-subagent review keeps the inactivity
+    // heartbeat alive (any new bytes ⇒ `onActivity`) and its otherwise-invisible token spend is
+    // lifted into the run's telemetry. The CLI writes them per-session under
+    // `<configHome>/projects/<encoded-cwd>/<session-uuid>/subagents/*.jsonl`, so we watch the
+    // `projects` tree and let the watcher discover the `subagents/` dir (the session uuid isn't
+    // known up front). Ambient mode has no isolated home to watch. Best-effort — a
+    // missing/renamed transcript layout just yields no extra signal.
     const subagents = configHome
-        ? startSubagentWatcher(join(configHome, 'subagents'), {
+        ? startSubagentWatcher(join(configHome, 'projects'), {
             ...(opts.onActivity ? { onActivity: opts.onActivity } : {}),
             secrets,
             model: opts.model,
@@ -384,9 +384,10 @@ export async function runClaudeCode(opts) {
         // is the terminal `result` event's cumulative, which covers ONLY the parent loop — the
         // ADR 0026 incident is itself the proof: a heavily subagent-parallelised review reported
         // ~0 tokens, i.e. the parent stream (and its `result` total) never included the subagent
-        // spend. The subagent tokens live exclusively in the `subagents/*.jsonl` transcripts (a
-        // directory distinct from the parent's `projects/` session transcript), which the watcher
-        // reads and nothing else does — so neither `calls` nor `usage` can already contain them.
+        // spend. The subagent tokens live exclusively in the per-session `subagents/*.jsonl`
+        // transcripts, which the watcher reads and nothing else does; it deliberately EXCLUDES the
+        // sibling parent session transcript (whose usage `result` already totals), so neither
+        // `calls` nor `usage` can already contain the subagent spend.
         const mergedUsage = usage || subUsage.inputTokens || subUsage.outputTokens
             ? {
                 inputTokens: (usage?.inputTokens ?? 0) + subUsage.inputTokens,

package/dist/subagents.js

@@ -1,6 +1,6 @@
 import { readdir, stat } from 'node:fs/promises';
 import { createReadStream } from 'node:fs';
-import { join } from 'node:path';
+import { basename, join } from 'node:path';
 import { claudeAssistantContent, claudeCallUsage, isObject, redactBody } from './claude-stream.js';
 export function createSliceTracker() {
     // Insertion-ordered so the progress `items` render in dispatch order.
@@ -54,21 +54,84 @@ export function createSliceTracker() {
         },
     };
 }
+/**
+ * Reconcile the two redundant views of the same slice work into the one to surface
+ * (ADR 0027 Defect B). A pr-reviewer run has BOTH a parent `TodoWrite` plan (the slices,
+ * written once at grouping time) and the {@link SliceTracker}'s `Task`-dispatch view. The
+ * sequential shape advances the todo plan; the parallel-subagent shape advances ONLY the
+ * slice tracker (the CLI writes the plan once and never marks it done, while the parallel
+ * `Task`s report in-flight/complete). Neither alone covers both shapes, and gating the
+ * slice tracker OFF whenever a todo plan exists (the old behaviour) pinned parallel runs
+ * at 0%. So prefer whichever view is further along: more `completed`, then more
+ * `inProgress` (an all-pending todo plan must not beat live in-flight slices), then more
+ * `total` (the richer view — the todo plan can carry an extra "aggregate" entry), else the
+ * todo plan. Pure + total; returns whichever single input is present when only one is.
+ */
+export function pickProgress(todo, slice) {
+    if (!todo)
+        return slice;
+    if (!slice)
+        return todo;
+    if (slice.completed !== todo.completed)
+        return slice.completed > todo.completed ? slice : todo;
+    if (slice.inProgress !== todo.inProgress)
+        return slice.inProgress > todo.inProgress ? slice : todo;
+    if (slice.total !== todo.total)
+        return slice.total > todo.total ? slice : todo;
+    return todo;
+}
 // ---------------------------------------------------------------------------
 // Subagent transcript watcher (heartbeat + usage) (D3)
 // ---------------------------------------------------------------------------
 /** Default poll cadence for the transcript directory; well under the git timeout margin. */
 const DEFAULT_POLL_MS = 3_000;
 /**
- * Start watching `dir` (the CLI's `<configHome>/subagents`) for `*.jsonl` transcripts,
- * tailing each file by byte offset. New content feeds `onActivity` (heartbeat) and each
- * assistant turn carrying usage is lifted into a {@link HarnessCallMetric} + summed into
- * the cumulative usage. Best-effort throughout: the directory may not exist yet (created
- * lazily by the CLI), a file may be mid-write, and the line/usage shape may change across
- * CLI versions — every such case is swallowed so the watcher can only ever ADD signal,
- * never break the run.
+ * Recursively collect every `*.jsonl` file that lives inside a `subagents/` directory
+ * anywhere under `root` (the CLI's `<configHome>/projects` tree). The Claude CLI writes
+ * each parallel `Task` subagent's transcript to
+ * `<configHome>/projects/<encoded-cwd>/<session-uuid>/subagents/agent-*.jsonl`; the
+ * session-uuid dir isn't known before the CLI mints it, so we DISCOVER the `subagents/`
+ * dir by walking rather than guessing its path (ADR 0027 Defect A). Files NOT under a
+ * `subagents/` dir — critically the parent's own `<session-uuid>.jsonl` session transcript,
+ * whose per-turn usage the terminal `result` event already totals — are deliberately
+ * excluded: reading them would double-count the parent. `root` itself counts as inside a
+ * `subagents/` dir when its own basename is `subagents` (so passing the leaf dir works too).
+ * Best-effort: an unreadable directory is skipped, never thrown.
+ */
+async function findSubagentTranscripts(root) {
+    const out = [];
+    const walk = async (dir, inSubagents) => {
+        let entries;
+        try {
+            entries = await readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return; // dir not created yet (or vanished) — try again next tick
+        }
+        for (const entry of entries) {
+            const full = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                await walk(full, inSubagents || entry.name === 'subagents');
+            }
+            else if (inSubagents && entry.isFile() && entry.name.endsWith('.jsonl')) {
+                out.push(full);
+            }
+        }
+    };
+    await walk(root, basename(root) === 'subagents');
+    return out;
+}
+/**
+ * Start watching `root` (the CLI's `<configHome>/projects` tree) for subagent `*.jsonl`
+ * transcripts — any file under a `subagents/` directory beneath it (see
+ * {@link findSubagentTranscripts}) — tailing each file by byte offset. New content feeds
+ * `onActivity` (heartbeat) and each assistant turn carrying usage is lifted into a
+ * {@link HarnessCallMetric} + summed into the cumulative usage. Best-effort throughout: the
+ * tree may not exist yet (created lazily by the CLI), a file may be mid-write, and the
+ * line/usage shape may change across CLI versions — every such case is swallowed so the
+ * watcher can only ever ADD signal, never break the run.
  */
-export function startSubagentWatcher(dir, opts) {
+export function startSubagentWatcher(root, opts) {
     const secrets = opts.secrets ?? [];
     const offsets = new Map();
     const calls = [];
@@ -151,16 +214,8 @@ export function startSubagentWatcher(dir, opts) {
             return;
         polling = true;
         try {
-            let entries;
-            try {
-                entries = (await readdir(dir)).filter((n) => n.endsWith('.jsonl'));
-            }
-            catch {
-                return; // dir not created yet (or vanished) — try again next tick
-            }
             let grew = false;
-            for (const name of entries) {
-                const path = join(dir, name);
+            for (const path of await findSubagentTranscripts(root)) {
                 let size;
                 try {
                     size = (await stat(path)).size;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/executor-harness",
-  "version": "1.50.12",
+  "version": "1.50.14",
   "description": "Container payload: a thin TypeScript wrapper that runs the Pi coding agent against a cloned repo and opens a PR. Runs in the Cloudflare Container (and, in local native mode, as a host process); carries no secrets.",
   "repository": {
     "type": "git",
@@ -26,7 +26,7 @@
     "hono": "^4.12.30",
     "typescript": "7.0.2",
     "vitest": "^4.1.10",
-    "@cat-factory/server": "0.141.2",
+    "@cat-factory/server": "0.141.3",
     "@cat-factory/spend": "0.12.73"
   },
   "scripts": {

package/src/agent-runner.ts

@@ -13,7 +13,7 @@ import type { Logger } from './logger.js'
 import type { HarnessCallMetric, PiRunOutcome, PiRunStats, TodoProgress } from './pi.js'
 import { killChildProcess, spawnDetached } from './process.js'
 import { redact, secretsToRedact } from './redact.js'
-import { createSliceTracker, startSubagentWatcher } from './subagents.js'
+import { createSliceTracker, pickProgress, startSubagentWatcher } from './subagents.js'
 import { assertOnboardingKeysCurrent, writeOnboardingPreseed } from './onboarding-preseed.js'
 import { retainSessionTranscripts } from './transcript-retention.js'
 
@@ -325,16 +325,18 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
       ]
   const calls: HarnessCallMetric[] = []
 
-  // ADR 0026 D2.1: derive slice progress from the parent stream's `Task` dispatches +
-  // their terminal tool_results (both DO appear here — only a subagent's intermediate
-  // turns don't). A real parent TodoWrite plan, when the agent writes one, wins; the
-  // slice-derived progress is the fallback for the parallel-subagent shape that writes no
-  // parent plan (the pr-reviewer failure this fixes).
+  // ADR 0026 D2.1 + ADR 0027 Defect B: surface live slice progress from TWO reconciled
+  // sources. The parent's `Task` dispatches + their terminal tool_results DO appear on this
+  // stream (only a subagent's intermediate turns don't), so `sliceTracker` derives per-slice
+  // progress for the parallel-subagent shape; a parent `TodoWrite` plan (the sequential
+  // shape) is tracked in `lastTodo`. `pickProgress` picks whichever is further along on each
+  // update, so neither masks the other — the pr-reviewer prompt writes its todo plan ONCE
+  // and never marks it done, which used to gate the slice signal off and pin progress at 0%.
   const sliceTracker = createSliceTracker()
-  let sawTodoPlan = false
-  const emitSliceProgress = (): void => {
-    if (sawTodoPlan || !opts.onProgress) return
-    const progress = sliceTracker.progress()
+  let lastTodo: TodoProgress | undefined
+  const emitProgress = (): void => {
+    if (!opts.onProgress) return
+    const progress = pickProgress(lastTodo, sliceTracker.progress())
     if (progress) opts.onProgress(progress)
   }
 
@@ -347,21 +349,13 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
       stats.assistantChars += text.length
       stats.toolCalls += toolUses
       for (const block of content) {
-        if (
-          isObject(block) &&
-          block.type === 'tool_use' &&
-          block.name === 'TodoWrite' &&
-          opts.onProgress
-        ) {
+        if (isObject(block) && block.type === 'tool_use' && block.name === 'TodoWrite') {
           const progress = todosToProgress((block.input as Record<string, unknown>)?.todos)
-          if (progress) {
-            sawTodoPlan = true
-            opts.onProgress(progress)
-          }
+          if (progress) lastTodo = progress
         }
       }
       sliceTracker.onAssistant(content)
-      emitSliceProgress()
+      emitProgress()
       // Record this call BEFORE appending its turn: the prompt is the history that
       // produced this response. The append-only array keeps each call's prompt a strict
       // prefix of the next, so the backend's telemetry chain delta-compresses cleanly.
@@ -383,7 +377,7 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
       const content = (event.message as Record<string, unknown>).content
       if (Array.isArray(content)) {
         sliceTracker.onUser(content)
-        emitSliceProgress()
+        emitProgress()
         messages.push({ role: 'tool', content })
       }
     } else if (type === 'result') {
@@ -446,13 +440,16 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
           : { CLAUDE_CODE_OAUTH_TOKEN: opts.subscriptionToken! }),
       }
 
-  // ADR 0026 D2.1/D3: while the run is live, tail the CLI's `subagents/*.jsonl`
-  // transcripts (under the isolated config home) so a parallel-subagent review keeps the
-  // inactivity heartbeat alive (any new bytes ⇒ `onActivity`) and its otherwise-invisible
-  // token spend is lifted into the run's telemetry. Ambient mode has no isolated home to
-  // watch. Best-effort — a missing/renamed transcript layout just yields no extra signal.
+  // ADR 0026 D3 (path corrected by ADR 0027 Defect A): while the run is live, tail the CLI's
+  // subagent `*.jsonl` transcripts so a parallel-subagent review keeps the inactivity
+  // heartbeat alive (any new bytes ⇒ `onActivity`) and its otherwise-invisible token spend is
+  // lifted into the run's telemetry. The CLI writes them per-session under
+  // `<configHome>/projects/<encoded-cwd>/<session-uuid>/subagents/*.jsonl`, so we watch the
+  // `projects` tree and let the watcher discover the `subagents/` dir (the session uuid isn't
+  // known up front). Ambient mode has no isolated home to watch. Best-effort — a
+  // missing/renamed transcript layout just yields no extra signal.
   const subagents = configHome
-    ? startSubagentWatcher(join(configHome, 'subagents'), {
+    ? startSubagentWatcher(join(configHome, 'projects'), {
         ...(opts.onActivity ? { onActivity: opts.onActivity } : {}),
         secrets,
         model: opts.model,
@@ -502,9 +499,10 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
     // is the terminal `result` event's cumulative, which covers ONLY the parent loop — the
     // ADR 0026 incident is itself the proof: a heavily subagent-parallelised review reported
     // ~0 tokens, i.e. the parent stream (and its `result` total) never included the subagent
-    // spend. The subagent tokens live exclusively in the `subagents/*.jsonl` transcripts (a
-    // directory distinct from the parent's `projects/` session transcript), which the watcher
-    // reads and nothing else does — so neither `calls` nor `usage` can already contain them.
+    // spend. The subagent tokens live exclusively in the per-session `subagents/*.jsonl`
+    // transcripts, which the watcher reads and nothing else does; it deliberately EXCLUDES the
+    // sibling parent session transcript (whose usage `result` already totals), so neither
+    // `calls` nor `usage` can already contain the subagent spend.
     const mergedUsage =
       usage || subUsage.inputTokens || subUsage.outputTokens
         ? {

package/src/subagents.ts

@@ -1,13 +1,13 @@
 import { readdir, stat } from 'node:fs/promises'
-import { createReadStream } from 'node:fs'
-import { join } from 'node:path'
+import { createReadStream, type Dirent } from 'node:fs'
+import { basename, join } from 'node:path'
 import { claudeAssistantContent, claudeCallUsage, isObject, redactBody } from './claude-stream.js'
 import type { Logger } from './logger.js'
 import type { HarnessCallMetric, TodoProgress } from './pi.js'
 
-// ADR 0026 D2.1 + D3. When the Claude Code CLI reviews a large PR it fans the work
-// out across parallel `Task` subagents. Two things then go dark to the harness, which
-// only reads the PARENT process's stream-json stdout:
+// ADR 0026 D2.1 + D3, corrected by ADR 0027. When the Claude Code CLI reviews a large PR
+// it fans the work out across parallel `Task` subagents. Two things then go dark to the
+// harness, which only reads the PARENT process's stream-json stdout:
 //
 //  - the parent stream falls quiet for the whole (potentially 15+ minute) parallel
 //    review, so the inactivity heartbeat freezes and a healthy run looks wedged (P3);
@@ -21,11 +21,19 @@ import type { HarnessCallMetric, TodoProgress } from './pi.js'
 //  - {@link createSliceTracker} derives the slice plan + per-slice progress from the
 //    PARENT stream alone — the `Task` tool_use dispatch and its terminal tool_result
 //    DO appear there (only the subagent's intermediate turns don't), so slices/progress
-//    need no file watching (D2.1);
+//    need no file watching (D2.1). {@link pickProgress} reconciles it with any parent
+//    TodoWrite plan (ADR 0027 Defect B);
 //  - {@link startSubagentWatcher} tails the `subagents/*.jsonl` transcripts for the
 //    heartbeat (any new bytes ⇒ `onActivity`) and sums each subagent turn's usage into
 //    the run's telemetry (D3).
 //
+// The CLI does NOT write those transcripts to `<configHome>/subagents` (the location ADR
+// 0026 assumed, which never exists — ADR 0027 Defect A). It writes them PER SESSION under
+// `<configHome>/projects/<encoded-cwd>/<session-uuid>/subagents/agent-*.jsonl`, and the
+// session-uuid dir isn't known before the CLI mints it — so the watcher is pointed at the
+// `projects` root and DISCOVERS the `subagents/` dir by walking (see
+// {@link findSubagentTranscripts}).
+//
 // Both degrade gracefully: the CLI's subagent transcript layout is not a stable contract,
 // so a missing directory, an unreadable file, or an unparseable line is swallowed and the
 // harness falls back to today's parent-stream-only behaviour.
@@ -52,8 +60,10 @@ export interface SliceTracker {
   hasSlices(): boolean
   /**
    * Progress derived from the dispatched subagents (completed / in-flight / total),
-   * or undefined when none have been dispatched. Used ONLY as a fallback when the
-   * agent never wrote a parent TodoWrite plan — a real todo list, when present, wins.
+   * or undefined when none have been dispatched. Reconciled with any parent TodoWrite
+   * plan by {@link pickProgress} — it is NOT gated off by the presence of a todo plan
+   * (that gate was ADR 0027 Defect B: the pr-reviewer prompt writes the plan ONCE at
+   * grouping time and never marks it done, which used to permanently mask this signal).
    */
   progress(): TodoProgress | undefined
 }
@@ -106,6 +116,31 @@ export function createSliceTracker(): SliceTracker {
   }
 }
 
+/**
+ * Reconcile the two redundant views of the same slice work into the one to surface
+ * (ADR 0027 Defect B). A pr-reviewer run has BOTH a parent `TodoWrite` plan (the slices,
+ * written once at grouping time) and the {@link SliceTracker}'s `Task`-dispatch view. The
+ * sequential shape advances the todo plan; the parallel-subagent shape advances ONLY the
+ * slice tracker (the CLI writes the plan once and never marks it done, while the parallel
+ * `Task`s report in-flight/complete). Neither alone covers both shapes, and gating the
+ * slice tracker OFF whenever a todo plan exists (the old behaviour) pinned parallel runs
+ * at 0%. So prefer whichever view is further along: more `completed`, then more
+ * `inProgress` (an all-pending todo plan must not beat live in-flight slices), then more
+ * `total` (the richer view — the todo plan can carry an extra "aggregate" entry), else the
+ * todo plan. Pure + total; returns whichever single input is present when only one is.
+ */
+export function pickProgress(
+  todo: TodoProgress | undefined,
+  slice: TodoProgress | undefined,
+): TodoProgress | undefined {
+  if (!todo) return slice
+  if (!slice) return todo
+  if (slice.completed !== todo.completed) return slice.completed > todo.completed ? slice : todo
+  if (slice.inProgress !== todo.inProgress) return slice.inProgress > todo.inProgress ? slice : todo
+  if (slice.total !== todo.total) return slice.total > todo.total ? slice : todo
+  return todo
+}
+
 // ---------------------------------------------------------------------------
 // Subagent transcript watcher (heartbeat + usage) (D3)
 // ---------------------------------------------------------------------------
@@ -135,15 +170,51 @@ export interface SubagentWatcher {
 }
 
 /**
- * Start watching `dir` (the CLI's `<configHome>/subagents`) for `*.jsonl` transcripts,
- * tailing each file by byte offset. New content feeds `onActivity` (heartbeat) and each
- * assistant turn carrying usage is lifted into a {@link HarnessCallMetric} + summed into
- * the cumulative usage. Best-effort throughout: the directory may not exist yet (created
- * lazily by the CLI), a file may be mid-write, and the line/usage shape may change across
- * CLI versions — every such case is swallowed so the watcher can only ever ADD signal,
- * never break the run.
+ * Recursively collect every `*.jsonl` file that lives inside a `subagents/` directory
+ * anywhere under `root` (the CLI's `<configHome>/projects` tree). The Claude CLI writes
+ * each parallel `Task` subagent's transcript to
+ * `<configHome>/projects/<encoded-cwd>/<session-uuid>/subagents/agent-*.jsonl`; the
+ * session-uuid dir isn't known before the CLI mints it, so we DISCOVER the `subagents/`
+ * dir by walking rather than guessing its path (ADR 0027 Defect A). Files NOT under a
+ * `subagents/` dir — critically the parent's own `<session-uuid>.jsonl` session transcript,
+ * whose per-turn usage the terminal `result` event already totals — are deliberately
+ * excluded: reading them would double-count the parent. `root` itself counts as inside a
+ * `subagents/` dir when its own basename is `subagents` (so passing the leaf dir works too).
+ * Best-effort: an unreadable directory is skipped, never thrown.
+ */
+async function findSubagentTranscripts(root: string): Promise<string[]> {
+  const out: string[] = []
+  const walk = async (dir: string, inSubagents: boolean): Promise<void> => {
+    let entries: Dirent[]
+    try {
+      entries = await readdir(dir, { withFileTypes: true })
+    } catch {
+      return // dir not created yet (or vanished) — try again next tick
+    }
+    for (const entry of entries) {
+      const full = join(dir, entry.name)
+      if (entry.isDirectory()) {
+        await walk(full, inSubagents || entry.name === 'subagents')
+      } else if (inSubagents && entry.isFile() && entry.name.endsWith('.jsonl')) {
+        out.push(full)
+      }
+    }
+  }
+  await walk(root, basename(root) === 'subagents')
+  return out
+}
+
+/**
+ * Start watching `root` (the CLI's `<configHome>/projects` tree) for subagent `*.jsonl`
+ * transcripts — any file under a `subagents/` directory beneath it (see
+ * {@link findSubagentTranscripts}) — tailing each file by byte offset. New content feeds
+ * `onActivity` (heartbeat) and each assistant turn carrying usage is lifted into a
+ * {@link HarnessCallMetric} + summed into the cumulative usage. Best-effort throughout: the
+ * tree may not exist yet (created lazily by the CLI), a file may be mid-write, and the
+ * line/usage shape may change across CLI versions — every such case is swallowed so the
+ * watcher can only ever ADD signal, never break the run.
  */
-export function startSubagentWatcher(dir: string, opts: SubagentWatcherOptions): SubagentWatcher {
+export function startSubagentWatcher(root: string, opts: SubagentWatcherOptions): SubagentWatcher {
   const secrets = opts.secrets ?? []
   const offsets = new Map<string, number>()
   const calls: HarnessCallMetric[] = []
@@ -225,15 +296,8 @@ export function startSubagentWatcher(dir: string, opts: SubagentWatcherOptions):
     if (polling) return
     polling = true
     try {
-      let entries: string[]
-      try {
-        entries = (await readdir(dir)).filter((n) => n.endsWith('.jsonl'))
-      } catch {
-        return // dir not created yet (or vanished) — try again next tick
-      }
       let grew = false
-      for (const name of entries) {
-        const path = join(dir, name)
+      for (const path of await findSubagentTranscripts(root)) {
         let size: number
         try {
           size = (await stat(path)).size