@cat-factory/executor-harness 1.52.0 → 1.52.2

package/dist/agent-runner.js

@@ -6,7 +6,8 @@ import { claudeAssistantContent, claudeCallUsage, isObject, numberOf, redactBody
 import { createCallMetricPublisher, publishCallMetric, } from './pi.js';
 import { killChildProcess, spawnDetached } from './process.js';
 import { redact, secretsToRedact } from './redact.js';
-import { createSliceTracker, pickProgress, startSubagentWatcher } from './subagents.js';
+import { createSliceTracker, startSubagentWatcher } from './subagents.js';
+import { createTaskPlanTracker, normalizeStatus, pickProgress, toProgress, todosToProgress, } from './progress.js';
 import { assertOnboardingKeysCurrent, writeOnboardingPreseed } from './onboarding-preseed.js';
 import { retainSessionTranscripts } from './transcript-retention.js';
 /**
@@ -224,18 +225,24 @@ export async function runClaudeCode(opts) {
     // may still rewrite below (a published call must be final — see the publisher).
     const publisher = createCallMetricPublisher(calls, opts.onCallMetric);
     // 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
+    // sources. The parent's subagent 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%.
+    // progress for the parallel shape; the parent's own plan (the sequential shape) is tracked
+    // by `planTracker` + `lastTodo`. `pickProgress` picks whichever is further along on each
+    // update, so neither masks the other — the pr-reviewer prompt writes its plan ONCE and never
+    // marks it done, which used to gate the slice signal off and pin progress at 0%.
+    //
+    // The plan arrives in one of two tool vocabularies depending on the bundled CLI build:
+    // `TodoWrite` (whole-list snapshots, tracked in `lastTodo`) or the incremental
+    // `TaskCreate`/`TaskUpdate` pair (tracked by `planTracker`, which needs the tool RESULTS too
+    // because the task id is minted there). Both are read — see ./progress.ts.
     const sliceTracker = createSliceTracker();
+    const planTracker = createTaskPlanTracker();
     let lastTodo;
     const emitProgress = () => {
         if (!opts.onProgress)
             return;
-        const progress = pickProgress(lastTodo, sliceTracker.progress());
+        const progress = pickProgress(pickProgress(lastTodo, planTracker.progress()), sliceTracker.progress());
         if (progress)
             opts.onProgress(progress);
     };
@@ -255,6 +262,7 @@ export async function runClaudeCode(opts) {
                 }
             }
             sliceTracker.onAssistant(content);
+            planTracker.onAssistant(content);
             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
@@ -278,6 +286,7 @@ export async function runClaudeCode(opts) {
             const content = event.message.content;
             if (Array.isArray(content)) {
                 sliceTracker.onUser(content);
+                planTracker.onUser(content);
                 emitProgress();
                 messages.push({ role: 'tool', content });
             }
@@ -442,25 +451,6 @@ async function assembleClaudeOutcome(args) {
         ...(mergedCalls.length ? { callMetrics: mergedCalls } : {}),
     };
 }
-/** Map Claude Code's `TodoWrite` todos array onto subtask counts. */
-function todosToProgress(todos) {
-    if (!Array.isArray(todos))
-        return undefined;
-    const items = todos.filter(isObject).map((t) => ({
-        label: typeof t.content === 'string' ? t.content : String(t.content ?? ''),
-        status: normalizeStatus(t.status),
-    }));
-    const completed = items.filter((i) => i.status === 'completed').length;
-    const inProgress = items.filter((i) => i.status === 'in_progress').length;
-    return { completed, inProgress, total: items.length, items };
-}
-function normalizeStatus(status) {
-    if (status === 'completed')
-        return 'completed';
-    if (status === 'in_progress')
-        return 'in_progress';
-    return 'pending';
-}
 function claudeUsage(raw) {
     if (!isObject(raw))
         return undefined;
@@ -670,9 +660,7 @@ function codexPlanProgress(event) {
     }));
     if (items.length === 0)
         return undefined;
-    const completed = items.filter((i) => i.status === 'completed').length;
-    const inProgress = items.filter((i) => i.status === 'in_progress').length;
-    return { completed, inProgress, total: items.length, items };
+    return toProgress(items);
 }
 /**
  * Best-effort: pull token usage out of a Codex usage event. Codex `exec --json`

package/dist/progress.js

@@ -0,0 +1,217 @@
+import { isObject } from './claude-stream.js';
+// The parent agent's own PLAN, as progress counts. This is one of the two redundant views a
+// pr-reviewer run produces (the other is the parallel-subagent dispatch view in
+// `subagents.ts`); {@link pickProgress} reconciles them.
+//
+// The Claude Code CLI exposes the plan through TWO different tool vocabularies, and which one
+// a run uses depends on the CLI build, not on anything the harness controls:
+//
+//  - `TodoWrite` — one call carrying the WHOLE list (`todos[]`), each entry with its own
+//    status. Every call is a complete snapshot, so the last one wins.
+//  - `TaskCreate` / `TaskUpdate` — an incremental, id-keyed task list. `TaskCreate` appends a
+//    task and the CLI assigns its id in the tool RESULT; `TaskUpdate` moves one task by id.
+//
+// Both are live in the shipped schema (`sdk-tools.d.ts` in `@anthropic-ai/claude-code` declares
+// `TodoWriteInput` AND `TaskCreateInput`/`TaskUpdateInput`), so the harness tracks both rather
+// than betting on one. Reading only `TodoWrite` is what pinned a CLI 2.1.x pr-review at 0%:
+// the run planned entirely through `TaskCreate`/`TaskUpdate` and the harness saw nothing.
+//
+// Everything here is best-effort and defensive: an unknown status, a missing id, or a result
+// string the CLI reworded degrades to "no progress from this signal" rather than throwing. The
+// tool vocabulary is not a stable contract, so this module may only ever ADD signal.
+/** Statuses a plan entry can carry; anything unrecognised is treated as not-yet-started. */
+export function normalizeStatus(status) {
+    if (status === 'completed')
+        return 'completed';
+    if (status === 'in_progress')
+        return 'in_progress';
+    return 'pending';
+}
+/** Roll a label+status list up into the counts the board renders. Shared by every plan shape. */
+export function toProgress(items) {
+    return {
+        completed: items.filter((i) => i.status === 'completed').length,
+        inProgress: items.filter((i) => i.status === 'in_progress').length,
+        total: items.length,
+        items,
+    };
+}
+/** Map a `TodoWrite` call's `todos` array onto subtask counts. Each call is a full snapshot. */
+export function todosToProgress(todos) {
+    if (!Array.isArray(todos))
+        return undefined;
+    return toProgress(todos.filter(isObject).map((t) => ({
+        label: typeof t.content === 'string' ? t.content : String(t.content ?? ''),
+        status: normalizeStatus(t.status),
+    })));
+}
+/**
+ * The id the CLI assigned to a just-created task, read from `TaskCreate`'s tool RESULT.
+ *
+ * `TaskCreate`'s INPUT carries only `{subject, description}` — the id is minted by the CLI and
+ * comes back on the result, so pairing a later `TaskUpdate({taskId})` to the task it created
+ * requires reading the result text. The CLI's shipped `TaskCreateOutput` is
+ * `{task: {id, subject}}`, but the parent stream's `tool_result` block carries the rendered
+ * STRING (`"Task #1 created successfully: <subject>"`), so both shapes are accepted.
+ */
+export function parseCreatedTaskId(content) {
+    if (isObject(content)) {
+        const task = isObject(content.task) ? content.task : undefined;
+        const id = task?.id;
+        if (typeof id === 'string' && id.trim())
+            return id.trim();
+        if (typeof id === 'number')
+            return String(id);
+    }
+    const text = typeof content === 'string'
+        ? content
+        : Array.isArray(content)
+            ? content
+                .filter(isObject)
+                .map((b) => (typeof b.text === 'string' ? b.text : ''))
+                .join('\n')
+            : '';
+    return /\bTask\s+#(\d+)\b/i.exec(text)?.[1];
+}
+export function createTaskPlanTracker() {
+    // Insertion-ordered so `items` render in plan order.
+    const tasks = new Map();
+    // tool_use id of an unresolved `TaskCreate` -> the synthetic key it was filed under, so the
+    // task can be re-keyed to its real id once the result lands.
+    const pendingCreates = new Map();
+    // Updates that arrived before their target was bound (the CLI can interleave), replayed on bind.
+    const orphanUpdates = new Map();
+    // `deleted` tombstones for a task id whose create has not bound yet, replayed on bind — else a
+    // delete that races ahead of its create leaves the task in the plan forever.
+    const pendingDeletes = new Set();
+    const apply = (task, patch) => {
+        if (patch.label)
+            task.label = patch.label;
+        if (patch.status)
+            task.status = patch.status;
+    };
+    // Drop a tombstoned task. When it isn't present yet (its create hasn't bound), remember the
+    // tombstone so the bind drops it rather than leaving it stuck in the plan forever.
+    const markDeleted = (taskId) => {
+        if (!tasks.delete(taskId))
+            pendingDeletes.add(taskId);
+        orphanUpdates.delete(taskId);
+    };
+    return {
+        onAssistant(content) {
+            if (!Array.isArray(content))
+                return;
+            for (const block of content) {
+                if (!isObject(block) || block.type !== 'tool_use')
+                    continue;
+                const input = isObject(block.input) ? block.input : {};
+                if (block.name === 'TaskCreate') {
+                    const toolUseId = typeof block.id === 'string' ? block.id : undefined;
+                    if (!toolUseId || pendingCreates.has(toolUseId))
+                        continue;
+                    const label = (typeof input.subject === 'string' && input.subject.trim()) ||
+                        (typeof input.description === 'string' && input.description.trim()) ||
+                        `Task ${tasks.size + 1}`;
+                    const key = `pending:${toolUseId}`;
+                    tasks.set(key, { id: key, label, status: 'pending' });
+                    pendingCreates.set(toolUseId, key);
+                }
+                else if (block.name === 'TaskUpdate') {
+                    const taskId = typeof input.taskId === 'string' ? input.taskId : undefined;
+                    if (!taskId)
+                        continue;
+                    const patch = {};
+                    if (typeof input.subject === 'string' && input.subject.trim())
+                        patch.label = input.subject.trim();
+                    if (input.status === 'deleted') {
+                        // `deleted` is a tombstone, not a status — drop the task from the live list.
+                        markDeleted(taskId);
+                        continue;
+                    }
+                    if (input.status !== undefined)
+                        patch.status = normalizeStatus(input.status);
+                    const task = tasks.get(taskId);
+                    if (task)
+                        apply(task, patch);
+                    else
+                        orphanUpdates.set(taskId, { ...orphanUpdates.get(taskId), ...patch });
+                }
+            }
+        },
+        onUser(content) {
+            if (!Array.isArray(content))
+                return;
+            for (const block of content) {
+                if (!isObject(block) || block.type !== 'tool_result')
+                    continue;
+                const toolUseId = typeof block.tool_use_id === 'string' ? block.tool_use_id : undefined;
+                const key = toolUseId ? pendingCreates.get(toolUseId) : undefined;
+                if (!key)
+                    continue;
+                const taskId = parseCreatedTaskId(block.content);
+                pendingCreates.delete(toolUseId);
+                const task = tasks.get(key);
+                // No parsable id ⇒ leave it filed under its synthetic key: it still counts toward the
+                // plan total, it just can never be advanced by a later `TaskUpdate`. A parsed id that
+                // already names a live task (a duplicate / misparse) is also left under the synthetic key
+                // rather than overwriting that task — the rebuild below would otherwise drop a row and
+                // undercount `total`.
+                if (!taskId || !task || taskId === key || tasks.has(taskId))
+                    continue;
+                // Re-key in place. Rebuilding the map preserves insertion order, which `items` relies on.
+                const entries = [...tasks.entries()];
+                tasks.clear();
+                for (const [k, v] of entries) {
+                    if (k !== key)
+                        tasks.set(k, v);
+                    else
+                        tasks.set(taskId, { ...v, id: taskId });
+                }
+                // A tombstone that raced ahead of this bind drops the task now that it exists.
+                if (pendingDeletes.delete(taskId)) {
+                    tasks.delete(taskId);
+                    orphanUpdates.delete(taskId);
+                    continue;
+                }
+                const pendingPatch = orphanUpdates.get(taskId);
+                if (pendingPatch) {
+                    const bound = tasks.get(taskId);
+                    if (bound)
+                        apply(bound, pendingPatch);
+                    orphanUpdates.delete(taskId);
+                }
+            }
+        },
+        progress() {
+            if (tasks.size === 0)
+                return undefined;
+            return toProgress([...tasks.values()].map((t) => ({ label: t.label, status: t.status })));
+        },
+    };
+}
+/**
+ * Reconcile the redundant views of the same work into the one to surface (ADR 0027 Defect B).
+ * A pr-reviewer run has BOTH a parent plan (`TodoWrite` or `TaskCreate`/`TaskUpdate`) and the
+ * `SliceTracker`'s subagent-dispatch view. The sequential shape advances the plan; the parallel
+ * shape advances ONLY the slice tracker (the reviewer writes its plan once and the parallel
+ * subagents report in-flight/complete). Neither alone covers both shapes, and gating the slice
+ * tracker off whenever a plan exists (the original behaviour) pinned parallel runs at 0%.
+ *
+ * So prefer whichever view is further along: more `completed`, then more `inProgress` (an
+ * all-pending plan must not beat live in-flight slices), then more `total` (the richer view — a
+ * plan can carry an extra "aggregate" entry), else the 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;
+}

package/dist/subagents.js

@@ -3,6 +3,55 @@ import { createReadStream } from 'node:fs';
 import { basename, join } from 'node:path';
 import { claudeAssistantContent, claudeCallUsage, isObject, redactBody } from './claude-stream.js';
 import { publishCallMetric } from './pi.js';
+// 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);
+//  - every subagent's token spend is written to a SEPARATE `subagents/*.jsonl`
+//    transcript under the CLI's config home and never reaches the parent stream, so
+//    the run's telemetry reports ~0 tokens while hundreds of thousands are spent (P3).
+//
+// This module closes both without disabling the (context-bounding, ADR-0023-wanted)
+// subagent parallelism:
+//
+//  - {@link createSliceTracker} derives the slice plan + per-slice progress from the
+//    PARENT stream alone — the subagent-dispatch tool_use 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). `pickProgress` (./progress.ts) reconciles it with the
+//    parent's own 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.
+// ---------------------------------------------------------------------------
+// Slice / progress tracking off the PARENT stream (D2.1)
+// ---------------------------------------------------------------------------
+/**
+ * The tool names the Claude Code CLI dispatches a parallel subagent under. `Agent` is what the
+ * shipped schema declares (`AgentInput` in `sdk-tools.d.ts`, carrying `description` / `prompt` /
+ * `subagent_type`); `Task` is the older name for the same dispatch. Both are matched because the
+ * harness runs against whatever CLI the image happens to bundle, and matching only the old name
+ * is what left a CLI 2.1.x pr-review reporting no slices at all.
+ *
+ * Note the asymmetry: keeping the legacy `Task` here is the one place a CLI rename could produce a
+ * FALSE signal rather than merely no signal — if a future build were to name a plain task-list
+ * tool `Task`, its writes would be counted as in-flight slices. We accept that because no shipped
+ * build does (the incremental plan tool is `TaskCreate`/`TaskUpdate`, tracked separately in
+ * `progress.ts`), and dropping legacy coverage is the more likely regression.
+ */
+const SUBAGENT_TOOL_NAMES = new Set(['Agent', 'Task']);
 export function createSliceTracker() {
     // Insertion-ordered so the progress `items` render in dispatch order.
     const slices = new Map();
@@ -11,7 +60,9 @@ export function createSliceTracker() {
             if (!Array.isArray(content))
                 return;
             for (const block of content) {
-                if (!isObject(block) || block.type !== 'tool_use' || block.name !== 'Task')
+                if (!isObject(block) || block.type !== 'tool_use')
+                    continue;
+                if (typeof block.name !== 'string' || !SUBAGENT_TOOL_NAMES.has(block.name))
                     continue;
                 const id = typeof block.id === 'string' ? block.id : undefined;
                 if (!id || slices.has(id))
@@ -55,32 +106,6 @@ 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)
 // ---------------------------------------------------------------------------

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/executor-harness",
-  "version": "1.52.0",
+  "version": "1.52.2",
   "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.144.0",
+    "@cat-factory/server": "0.144.1",
     "@cat-factory/spend": "0.12.77"
   },
   "scripts": {

package/src/agent-runner.ts

@@ -21,7 +21,14 @@ import {
 } from './pi.js'
 import { killChildProcess, spawnDetached } from './process.js'
 import { redact, secretsToRedact } from './redact.js'
-import { createSliceTracker, pickProgress, startSubagentWatcher } from './subagents.js'
+import { createSliceTracker, startSubagentWatcher } from './subagents.js'
+import {
+  createTaskPlanTracker,
+  normalizeStatus,
+  pickProgress,
+  toProgress,
+  todosToProgress,
+} from './progress.js'
 import { assertOnboardingKeysCurrent, writeOnboardingPreseed } from './onboarding-preseed.js'
 import { retainSessionTranscripts } from './transcript-retention.js'
 
@@ -343,17 +350,26 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
   const publisher = createCallMetricPublisher(calls, opts.onCallMetric)
 
   // 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
+  // sources. The parent's subagent 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%.
+  // progress for the parallel shape; the parent's own plan (the sequential shape) is tracked
+  // by `planTracker` + `lastTodo`. `pickProgress` picks whichever is further along on each
+  // update, so neither masks the other — the pr-reviewer prompt writes its plan ONCE and never
+  // marks it done, which used to gate the slice signal off and pin progress at 0%.
+  //
+  // The plan arrives in one of two tool vocabularies depending on the bundled CLI build:
+  // `TodoWrite` (whole-list snapshots, tracked in `lastTodo`) or the incremental
+  // `TaskCreate`/`TaskUpdate` pair (tracked by `planTracker`, which needs the tool RESULTS too
+  // because the task id is minted there). Both are read — see ./progress.ts.
   const sliceTracker = createSliceTracker()
+  const planTracker = createTaskPlanTracker()
   let lastTodo: TodoProgress | undefined
   const emitProgress = (): void => {
     if (!opts.onProgress) return
-    const progress = pickProgress(lastTodo, sliceTracker.progress())
+    const progress = pickProgress(
+      pickProgress(lastTodo, planTracker.progress()),
+      sliceTracker.progress(),
+    )
     if (progress) opts.onProgress(progress)
   }
 
@@ -372,6 +388,7 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
         }
       }
       sliceTracker.onAssistant(content)
+      planTracker.onAssistant(content)
       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
@@ -394,6 +411,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)
+        planTracker.onUser(content)
         emitProgress()
         messages.push({ role: 'tool', content })
       }
@@ -584,24 +602,6 @@ async function assembleClaudeOutcome(args: {
   }
 }
 
-/** Map Claude Code's `TodoWrite` todos array onto subtask counts. */
-function todosToProgress(todos: unknown): TodoProgress | undefined {
-  if (!Array.isArray(todos)) return undefined
-  const items = todos.filter(isObject).map((t) => ({
-    label: typeof t.content === 'string' ? t.content : String(t.content ?? ''),
-    status: normalizeStatus(t.status),
-  }))
-  const completed = items.filter((i) => i.status === 'completed').length
-  const inProgress = items.filter((i) => i.status === 'in_progress').length
-  return { completed, inProgress, total: items.length, items }
-}
-
-function normalizeStatus(status: unknown): 'pending' | 'in_progress' | 'completed' {
-  if (status === 'completed') return 'completed'
-  if (status === 'in_progress') return 'in_progress'
-  return 'pending'
-}
-
 function claudeUsage(raw: unknown): { inputTokens: number; outputTokens: number } | undefined {
   if (!isObject(raw)) return undefined
   // Count every input bucket Anthropic bills: fresh input plus BOTH cache reads and
@@ -829,9 +829,7 @@ function codexPlanProgress(event: Record<string, unknown>): TodoProgress | undef
     status: normalizeStatus(s.status),
   }))
   if (items.length === 0) return undefined
-  const completed = items.filter((i) => i.status === 'completed').length
-  const inProgress = items.filter((i) => i.status === 'in_progress').length
-  return { completed, inProgress, total: items.length, items }
+  return toProgress(items)
 }
 
 /**

package/src/progress.ts

@@ -0,0 +1,232 @@
+import { isObject } from './claude-stream.js'
+import type { TodoProgress } from './pi.js'
+
+// The parent agent's own PLAN, as progress counts. This is one of the two redundant views a
+// pr-reviewer run produces (the other is the parallel-subagent dispatch view in
+// `subagents.ts`); {@link pickProgress} reconciles them.
+//
+// The Claude Code CLI exposes the plan through TWO different tool vocabularies, and which one
+// a run uses depends on the CLI build, not on anything the harness controls:
+//
+//  - `TodoWrite` — one call carrying the WHOLE list (`todos[]`), each entry with its own
+//    status. Every call is a complete snapshot, so the last one wins.
+//  - `TaskCreate` / `TaskUpdate` — an incremental, id-keyed task list. `TaskCreate` appends a
+//    task and the CLI assigns its id in the tool RESULT; `TaskUpdate` moves one task by id.
+//
+// Both are live in the shipped schema (`sdk-tools.d.ts` in `@anthropic-ai/claude-code` declares
+// `TodoWriteInput` AND `TaskCreateInput`/`TaskUpdateInput`), so the harness tracks both rather
+// than betting on one. Reading only `TodoWrite` is what pinned a CLI 2.1.x pr-review at 0%:
+// the run planned entirely through `TaskCreate`/`TaskUpdate` and the harness saw nothing.
+//
+// Everything here is best-effort and defensive: an unknown status, a missing id, or a result
+// string the CLI reworded degrades to "no progress from this signal" rather than throwing. The
+// tool vocabulary is not a stable contract, so this module may only ever ADD signal.
+
+/** Statuses a plan entry can carry; anything unrecognised is treated as not-yet-started. */
+export function normalizeStatus(status: unknown): 'pending' | 'in_progress' | 'completed' {
+  if (status === 'completed') return 'completed'
+  if (status === 'in_progress') return 'in_progress'
+  return 'pending'
+}
+
+/** Roll a label+status list up into the counts the board renders. Shared by every plan shape. */
+export function toProgress(items: { label: string; status: ReturnType<typeof normalizeStatus> }[]) {
+  return {
+    completed: items.filter((i) => i.status === 'completed').length,
+    inProgress: items.filter((i) => i.status === 'in_progress').length,
+    total: items.length,
+    items,
+  }
+}
+
+/** Map a `TodoWrite` call's `todos` array onto subtask counts. Each call is a full snapshot. */
+export function todosToProgress(todos: unknown): TodoProgress | undefined {
+  if (!Array.isArray(todos)) return undefined
+  return toProgress(
+    todos.filter(isObject).map((t) => ({
+      label: typeof t.content === 'string' ? t.content : String(t.content ?? ''),
+      status: normalizeStatus(t.status),
+    })),
+  )
+}
+
+/**
+ * The id the CLI assigned to a just-created task, read from `TaskCreate`'s tool RESULT.
+ *
+ * `TaskCreate`'s INPUT carries only `{subject, description}` — the id is minted by the CLI and
+ * comes back on the result, so pairing a later `TaskUpdate({taskId})` to the task it created
+ * requires reading the result text. The CLI's shipped `TaskCreateOutput` is
+ * `{task: {id, subject}}`, but the parent stream's `tool_result` block carries the rendered
+ * STRING (`"Task #1 created successfully: <subject>"`), so both shapes are accepted.
+ */
+export function parseCreatedTaskId(content: unknown): string | undefined {
+  if (isObject(content)) {
+    const task = isObject(content.task) ? content.task : undefined
+    const id = task?.id
+    if (typeof id === 'string' && id.trim()) return id.trim()
+    if (typeof id === 'number') return String(id)
+  }
+  const text =
+    typeof content === 'string'
+      ? content
+      : Array.isArray(content)
+        ? content
+            .filter(isObject)
+            .map((b) => (typeof b.text === 'string' ? b.text : ''))
+            .join('\n')
+        : ''
+  return /\bTask\s+#(\d+)\b/i.exec(text)?.[1]
+}
+
+interface PlannedTask {
+  id: string
+  label: string
+  status: ReturnType<typeof normalizeStatus>
+}
+
+/**
+ * Tracks the parent's incremental `TaskCreate` / `TaskUpdate` plan.
+ *
+ * A `TaskCreate` is registered as pending against its tool_use id, then bound to the CLI-assigned
+ * task id when its result arrives; `TaskUpdate` moves the bound task. A create whose result is
+ * never seen (or whose id can't be parsed) still counts toward `total` under a synthetic key, so
+ * the plan size stays honest even when the pairing fails — it simply can never advance.
+ *
+ * `deleted` tombstones are dropped from the list entirely (matching `TodoWrite`'s live-tasks-only
+ * shape), so a task the agent abandons doesn't hold the bar back forever.
+ */
+export interface TaskPlanTracker {
+  /** Feed an `assistant` message's content blocks: registers creates + applies updates. */
+  onAssistant(content: unknown[]): void
+  /** Feed a `user` message's content blocks: binds each create to its CLI-assigned task id. */
+  onUser(content: unknown[]): void
+  /** The plan as progress counts, or undefined when nothing has been planned yet. */
+  progress(): TodoProgress | undefined
+}
+
+export function createTaskPlanTracker(): TaskPlanTracker {
+  // Insertion-ordered so `items` render in plan order.
+  const tasks = new Map<string, PlannedTask>()
+  // tool_use id of an unresolved `TaskCreate` -> the synthetic key it was filed under, so the
+  // task can be re-keyed to its real id once the result lands.
+  const pendingCreates = new Map<string, string>()
+  // Updates that arrived before their target was bound (the CLI can interleave), replayed on bind.
+  const orphanUpdates = new Map<string, Partial<PlannedTask>>()
+  // `deleted` tombstones for a task id whose create has not bound yet, replayed on bind — else a
+  // delete that races ahead of its create leaves the task in the plan forever.
+  const pendingDeletes = new Set<string>()
+
+  const apply = (task: PlannedTask, patch: Partial<PlannedTask>): void => {
+    if (patch.label) task.label = patch.label
+    if (patch.status) task.status = patch.status
+  }
+
+  // Drop a tombstoned task. When it isn't present yet (its create hasn't bound), remember the
+  // tombstone so the bind drops it rather than leaving it stuck in the plan forever.
+  const markDeleted = (taskId: string): void => {
+    if (!tasks.delete(taskId)) pendingDeletes.add(taskId)
+    orphanUpdates.delete(taskId)
+  }
+
+  return {
+    onAssistant(content) {
+      if (!Array.isArray(content)) return
+      for (const block of content) {
+        if (!isObject(block) || block.type !== 'tool_use') continue
+        const input = isObject(block.input) ? block.input : {}
+        if (block.name === 'TaskCreate') {
+          const toolUseId = typeof block.id === 'string' ? block.id : undefined
+          if (!toolUseId || pendingCreates.has(toolUseId)) continue
+          const label =
+            (typeof input.subject === 'string' && input.subject.trim()) ||
+            (typeof input.description === 'string' && input.description.trim()) ||
+            `Task ${tasks.size + 1}`
+          const key = `pending:${toolUseId}`
+          tasks.set(key, { id: key, label, status: 'pending' })
+          pendingCreates.set(toolUseId, key)
+        } else if (block.name === 'TaskUpdate') {
+          const taskId = typeof input.taskId === 'string' ? input.taskId : undefined
+          if (!taskId) continue
+          const patch: Partial<PlannedTask> = {}
+          if (typeof input.subject === 'string' && input.subject.trim())
+            patch.label = input.subject.trim()
+          if (input.status === 'deleted') {
+            // `deleted` is a tombstone, not a status — drop the task from the live list.
+            markDeleted(taskId)
+            continue
+          }
+          if (input.status !== undefined) patch.status = normalizeStatus(input.status)
+          const task = tasks.get(taskId)
+          if (task) apply(task, patch)
+          else orphanUpdates.set(taskId, { ...orphanUpdates.get(taskId), ...patch })
+        }
+      }
+    },
+    onUser(content) {
+      if (!Array.isArray(content)) return
+      for (const block of content) {
+        if (!isObject(block) || block.type !== 'tool_result') continue
+        const toolUseId = typeof block.tool_use_id === 'string' ? block.tool_use_id : undefined
+        const key = toolUseId ? pendingCreates.get(toolUseId) : undefined
+        if (!key) continue
+        const taskId = parseCreatedTaskId(block.content)
+        pendingCreates.delete(toolUseId!)
+        const task = tasks.get(key)
+        // No parsable id ⇒ leave it filed under its synthetic key: it still counts toward the
+        // plan total, it just can never be advanced by a later `TaskUpdate`. A parsed id that
+        // already names a live task (a duplicate / misparse) is also left under the synthetic key
+        // rather than overwriting that task — the rebuild below would otherwise drop a row and
+        // undercount `total`.
+        if (!taskId || !task || taskId === key || tasks.has(taskId)) continue
+        // Re-key in place. Rebuilding the map preserves insertion order, which `items` relies on.
+        const entries = [...tasks.entries()]
+        tasks.clear()
+        for (const [k, v] of entries) {
+          if (k !== key) tasks.set(k, v)
+          else tasks.set(taskId, { ...v, id: taskId })
+        }
+        // A tombstone that raced ahead of this bind drops the task now that it exists.
+        if (pendingDeletes.delete(taskId)) {
+          tasks.delete(taskId)
+          orphanUpdates.delete(taskId)
+          continue
+        }
+        const pendingPatch = orphanUpdates.get(taskId)
+        if (pendingPatch) {
+          const bound = tasks.get(taskId)
+          if (bound) apply(bound, pendingPatch)
+          orphanUpdates.delete(taskId)
+        }
+      }
+    },
+    progress() {
+      if (tasks.size === 0) return undefined
+      return toProgress([...tasks.values()].map((t) => ({ label: t.label, status: t.status })))
+    },
+  }
+}
+
+/**
+ * Reconcile the redundant views of the same work into the one to surface (ADR 0027 Defect B).
+ * A pr-reviewer run has BOTH a parent plan (`TodoWrite` or `TaskCreate`/`TaskUpdate`) and the
+ * `SliceTracker`'s subagent-dispatch view. The sequential shape advances the plan; the parallel
+ * shape advances ONLY the slice tracker (the reviewer writes its plan once and the parallel
+ * subagents report in-flight/complete). Neither alone covers both shapes, and gating the slice
+ * tracker off whenever a plan exists (the original behaviour) pinned parallel runs at 0%.
+ *
+ * So prefer whichever view is further along: more `completed`, then more `inProgress` (an
+ * all-pending plan must not beat live in-flight slices), then more `total` (the richer view — a
+ * plan can carry an extra "aggregate" entry), else the 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
+}

package/src/subagents.ts

@@ -19,10 +19,10 @@ import { publishCallMetric, type HarnessCallMetric, type TodoProgress } from './
 // subagent parallelism:
 //
 //  - {@link createSliceTracker} derives the slice plan + per-slice progress from the
-//    PARENT stream alone — the `Task` tool_use dispatch and its terminal tool_result
+//    PARENT stream alone — the subagent-dispatch tool_use 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). {@link pickProgress} reconciles it with any parent
-//    TodoWrite plan (ADR 0027 Defect B);
+//    need no file watching (D2.1). `pickProgress` (./progress.ts) reconciles it with the
+//    parent's own 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).
@@ -42,17 +42,32 @@ import { publishCallMetric, type HarnessCallMetric, type TodoProgress } from './
 // Slice / progress tracking off the PARENT stream (D2.1)
 // ---------------------------------------------------------------------------
 
+/**
+ * The tool names the Claude Code CLI dispatches a parallel subagent under. `Agent` is what the
+ * shipped schema declares (`AgentInput` in `sdk-tools.d.ts`, carrying `description` / `prompt` /
+ * `subagent_type`); `Task` is the older name for the same dispatch. Both are matched because the
+ * harness runs against whatever CLI the image happens to bundle, and matching only the old name
+ * is what left a CLI 2.1.x pr-review reporting no slices at all.
+ *
+ * Note the asymmetry: keeping the legacy `Task` here is the one place a CLI rename could produce a
+ * FALSE signal rather than merely no signal — if a future build were to name a plain task-list
+ * tool `Task`, its writes would be counted as in-flight slices. We accept that because no shipped
+ * build does (the incremental plan tool is `TaskCreate`/`TaskUpdate`, tracked separately in
+ * `progress.ts`), and dropping legacy coverage is the more likely regression.
+ */
+const SUBAGENT_TOOL_NAMES = new Set(['Agent', 'Task'])
+
 interface TrackedSlice {
-  /** The `Task` tool_use id, used to pair the terminal tool_result. */
+  /** The dispatch's tool_use id, used to pair the terminal tool_result. */
   toolUseId: string
   /** The subagent's description (`Review <slice> slice`), rendered as the progress label. */
   description: string
   done: boolean
 }
 
-/** Tracks parallel `Task` subagents seen on the parent stream to derive slice progress. */
+/** Tracks parallel subagents seen on the parent stream to derive slice progress. */
 export interface SliceTracker {
-  /** Feed an `assistant` message's content blocks: registers any `Task` dispatches. */
+  /** Feed an `assistant` message's content blocks: registers any subagent dispatches. */
   onAssistant(content: unknown[]): void
   /** Feed a `user` message's content blocks: marks the paired subagent(s) complete. */
   onUser(content: unknown[]): void
@@ -60,8 +75,8 @@ export interface SliceTracker {
   hasSlices(): boolean
   /**
    * Progress derived from the dispatched subagents (completed / in-flight / total),
-   * 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
+   * or undefined when none have been dispatched. Reconciled with the parent's own plan
+   * by `pickProgress` (./progress.ts) — it is NOT gated off by the presence of a 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).
    */
@@ -76,7 +91,8 @@ export function createSliceTracker(): SliceTracker {
     onAssistant(content) {
       if (!Array.isArray(content)) return
       for (const block of content) {
-        if (!isObject(block) || block.type !== 'tool_use' || block.name !== 'Task') continue
+        if (!isObject(block) || block.type !== 'tool_use') continue
+        if (typeof block.name !== 'string' || !SUBAGENT_TOOL_NAMES.has(block.name)) continue
         const id = typeof block.id === 'string' ? block.id : undefined
         if (!id || slices.has(id)) continue
         const input = isObject(block.input) ? block.input : {}
@@ -116,31 +132,6 @@ 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)
 // ---------------------------------------------------------------------------