@cat-factory/executor-harness 1.50.10 → 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/job.js

@@ -647,45 +647,82 @@ export function parseAgentJob(input) {
     // preview dispatch to send dummy values it has no reason to supply. Every other mode still
     // requires them (throws when missing/empty), exactly as before.
     const agentField = (value, path) => mode === 'preview' ? (typeof value === 'string' ? value : '') : str(value, path);
+    // Parse each field, then hand the pieces to `assembleAgentJob` for the (large) object literal —
+    // the parse/assemble split keeps both within the cyclomatic-complexity budget. Behaviour is
+    // byte-identical (the literal + host validation moved verbatim).
+    const job = assembleAgentJob(o, mode, agentField, {
+        output: parseAgentOutputSpec(o.output),
+        pr: parseAgentPrSpec(o.pr),
+        infra: parseAgentInfraSpec(o.infra),
+        peerRepos: parsePeerRepos(o.peerRepos),
+        referenceRepos: parseReferenceRepos(o.referenceRepos),
+        referenceBranches: parseReferenceBranches(o.referenceBranches),
+        bootstrap: parseAgentBootstrapSpec(o.bootstrap),
+        contextFiles: parseContextFiles(o.contextFiles),
+        packageRegistries: parsePackageRegistries(o.packageRegistries),
+        skill: parseSkillSpec(o.skill),
+        testSecrets: parseTestSecrets(o.testSecrets),
+        guardLimits: parseGuardLimits(o.guardLimits),
+        validation: parseValidationSpec(o.validation),
+        reviewPrNumber: posInt(o.reviewPrNumber),
+    });
+    assertAllowedHost(job.repo.cloneUrl, 'repo.cloneUrl');
+    if (job.githubApiBase)
+        assertAllowedHost(job.githubApiBase, 'githubApiBase');
+    // Bootstrap pushes the result to a SEPARATE target repo, so its clone URL must be an
+    // allowed GitHub host too (the installation token is sent to it on the force-push).
+    if (job.bootstrap)
+        assertAllowedHost(job.bootstrap.target.cloneUrl, 'bootstrap.target.cloneUrl');
+    // Each peer repo's clone URL receives the installation token on clone/push, so it must be
+    // an allowed GitHub host too — a body-supplied peer pointing at an attacker host would
+    // exfiltrate the token exactly like a rogue primary clone URL.
+    for (const [i, peer] of (job.peerRepos ?? []).entries()) {
+        assertAllowedHost(peer.repo.cloneUrl, `peerRepos[${i}].repo.cloneUrl`);
+    }
+    // Each reference repo's clone URL receives the installation/PAT token on clone (read-only,
+    // never pushed), so it must be an allowed host too — a body-supplied reference pointing at an
+    // attacker host would exfiltrate the token exactly like a rogue peer clone URL.
+    for (const [i, ref] of (job.referenceRepos ?? []).entries()) {
+        assertAllowedHost(ref.repo.cloneUrl, `referenceRepos[${i}].repo.cloneUrl`);
+    }
+    return job;
+}
+/** Parse the optional structured-output spec (`{ kind, shapeHint?, repair?, failOnUnusableFinal? }`). */
+function parseAgentOutputSpec(raw) {
+    if (typeof raw !== 'object' || raw === null)
+        return undefined;
+    const so = raw;
+    const kind = so.kind === 'structured' ? 'structured' : 'prose';
+    const spec = { kind };
+    if (typeof so.shapeHint === 'string')
+        spec.shapeHint = so.shapeHint;
+    // Carry an explicit `repair: false` through — the handler defaults to repair-on
+    // when absent, so dropping `false` would silently re-enable the repair call for a
+    // kind that opted out (it keys off `output.repair === false`).
+    if (typeof so.repair === 'boolean')
+        spec.repair = so.repair;
+    // Carry the opt-in truncation gate through (document producers set it); dropping
+    // it would silently re-enable laundering a cut-off reply into a half-baked doc.
+    if (so.failOnUnusableFinal === true)
+        spec.failOnUnusableFinal = true;
+    return spec;
+}
+/** Parse the optional PR spec (`{ title, body }`). */
+function parseAgentPrSpec(raw) {
+    if (typeof raw !== 'object' || raw === null)
+        return undefined;
+    const p = raw;
+    return { title: str(p.title, 'pr.title'), body: typeof p.body === 'string' ? p.body : '' };
+}
+/**
+ * Assemble the {@link AgentJob} object from the request `o` + the pre-parsed {@link
+ * ParsedAgentJobParts}. Extracted from {@link parseAgentJob} so the large conditional-spread
+ * literal doesn't blow the complexity budget; behaviour is byte-identical (spread order preserved).
+ */
+function assembleAgentJob(o, mode, agentField, parts) {
+    const { output, pr, infra, peerRepos, referenceRepos, referenceBranches, bootstrap, contextFiles, packageRegistries, skill, testSecrets, guardLimits, validation, reviewPrNumber, } = parts;
     const repo = (o.repo ?? {});
-    const output = typeof o.output === 'object' && o.output !== null
-        ? (() => {
-            const so = o.output;
-            const kind = so.kind === 'structured' ? 'structured' : 'prose';
-            const spec = { kind };
-            if (typeof so.shapeHint === 'string')
-                spec.shapeHint = so.shapeHint;
-            // Carry an explicit `repair: false` through — the handler defaults to repair-on
-            // when absent, so dropping `false` would silently re-enable the repair call for a
-            // kind that opted out (it keys off `output.repair === false`).
-            if (typeof so.repair === 'boolean')
-                spec.repair = so.repair;
-            // Carry the opt-in truncation gate through (document producers set it); dropping
-            // it would silently re-enable laundering a cut-off reply into a half-baked doc.
-            if (so.failOnUnusableFinal === true)
-                spec.failOnUnusableFinal = true;
-            return spec;
-        })()
-        : undefined;
-    const pr = typeof o.pr === 'object' && o.pr !== null
-        ? (() => {
-            const p = o.pr;
-            return { title: str(p.title, 'pr.title'), body: typeof p.body === 'string' ? p.body : '' };
-        })()
-        : undefined;
-    const infra = parseAgentInfraSpec(o.infra);
-    const peerRepos = parsePeerRepos(o.peerRepos);
-    const referenceRepos = parseReferenceRepos(o.referenceRepos);
-    const referenceBranches = parseReferenceBranches(o.referenceBranches);
-    const bootstrap = parseAgentBootstrapSpec(o.bootstrap);
-    const contextFiles = parseContextFiles(o.contextFiles);
-    const packageRegistries = parsePackageRegistries(o.packageRegistries);
-    const skill = parseSkillSpec(o.skill);
-    const testSecrets = parseTestSecrets(o.testSecrets);
-    const guardLimits = parseGuardLimits(o.guardLimits);
-    const validation = parseValidationSpec(o.validation);
-    const reviewPrNumber = posInt(o.reviewPrNumber);
-    const job = {
+    return {
         jobId: str(o.jobId, 'jobId'),
         mode,
         systemPrompt: agentField(o.systemPrompt, 'systemPrompt'),
@@ -723,24 +760,4 @@ export function parseAgentJob(input) {
         ...(guardLimits ? { guardLimits } : {}),
         ...(validation ? { validation } : {}),
     };
-    assertAllowedHost(job.repo.cloneUrl, 'repo.cloneUrl');
-    if (job.githubApiBase)
-        assertAllowedHost(job.githubApiBase, 'githubApiBase');
-    // Bootstrap pushes the result to a SEPARATE target repo, so its clone URL must be an
-    // allowed GitHub host too (the installation token is sent to it on the force-push).
-    if (job.bootstrap)
-        assertAllowedHost(job.bootstrap.target.cloneUrl, 'bootstrap.target.cloneUrl');
-    // Each peer repo's clone URL receives the installation token on clone/push, so it must be
-    // an allowed GitHub host too — a body-supplied peer pointing at an attacker host would
-    // exfiltrate the token exactly like a rogue primary clone URL.
-    for (const [i, peer] of (job.peerRepos ?? []).entries()) {
-        assertAllowedHost(peer.repo.cloneUrl, `peerRepos[${i}].repo.cloneUrl`);
-    }
-    // Each reference repo's clone URL receives the installation/PAT token on clone (read-only,
-    // never pushed), so it must be an allowed host too — a body-supplied reference pointing at an
-    // attacker host would exfiltrate the token exactly like a rogue peer clone URL.
-    for (const [i, ref] of (job.referenceRepos ?? []).entries()) {
-        assertAllowedHost(ref.repo.cloneUrl, `referenceRepos[${i}].repo.cloneUrl`);
-    }
-    return job;
 }

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.10",
+  "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,8 +26,8 @@
     "hono": "^4.12.30",
     "typescript": "7.0.2",
     "vitest": "^4.1.10",
-    "@cat-factory/server": "0.140.4",
-    "@cat-factory/spend": "0.12.69"
+    "@cat-factory/server": "0.141.3",
+    "@cat-factory/spend": "0.12.73"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",

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/job.ts

@@ -1250,44 +1250,116 @@ export function parseAgentJob(input: unknown): AgentJob {
   // requires them (throws when missing/empty), exactly as before.
   const agentField = (value: unknown, path: string): string =>
     mode === 'preview' ? (typeof value === 'string' ? value : '') : str(value, path)
+  // Parse each field, then hand the pieces to `assembleAgentJob` for the (large) object literal —
+  // the parse/assemble split keeps both within the cyclomatic-complexity budget. Behaviour is
+  // byte-identical (the literal + host validation moved verbatim).
+  const job = assembleAgentJob(o, mode, agentField, {
+    output: parseAgentOutputSpec(o.output),
+    pr: parseAgentPrSpec(o.pr),
+    infra: parseAgentInfraSpec(o.infra),
+    peerRepos: parsePeerRepos(o.peerRepos),
+    referenceRepos: parseReferenceRepos(o.referenceRepos),
+    referenceBranches: parseReferenceBranches(o.referenceBranches),
+    bootstrap: parseAgentBootstrapSpec(o.bootstrap),
+    contextFiles: parseContextFiles(o.contextFiles),
+    packageRegistries: parsePackageRegistries(o.packageRegistries),
+    skill: parseSkillSpec(o.skill),
+    testSecrets: parseTestSecrets(o.testSecrets),
+    guardLimits: parseGuardLimits(o.guardLimits),
+    validation: parseValidationSpec(o.validation),
+    reviewPrNumber: posInt(o.reviewPrNumber),
+  })
+  assertAllowedHost(job.repo.cloneUrl, 'repo.cloneUrl')
+  if (job.githubApiBase) assertAllowedHost(job.githubApiBase, 'githubApiBase')
+  // Bootstrap pushes the result to a SEPARATE target repo, so its clone URL must be an
+  // allowed GitHub host too (the installation token is sent to it on the force-push).
+  if (job.bootstrap) assertAllowedHost(job.bootstrap.target.cloneUrl, 'bootstrap.target.cloneUrl')
+  // Each peer repo's clone URL receives the installation token on clone/push, so it must be
+  // an allowed GitHub host too — a body-supplied peer pointing at an attacker host would
+  // exfiltrate the token exactly like a rogue primary clone URL.
+  for (const [i, peer] of (job.peerRepos ?? []).entries()) {
+    assertAllowedHost(peer.repo.cloneUrl, `peerRepos[${i}].repo.cloneUrl`)
+  }
+  // Each reference repo's clone URL receives the installation/PAT token on clone (read-only,
+  // never pushed), so it must be an allowed host too — a body-supplied reference pointing at an
+  // attacker host would exfiltrate the token exactly like a rogue peer clone URL.
+  for (const [i, ref] of (job.referenceRepos ?? []).entries()) {
+    assertAllowedHost(ref.repo.cloneUrl, `referenceRepos[${i}].repo.cloneUrl`)
+  }
+  return job
+}
+
+/** The pre-parsed field bundle {@link parseAgentJob} hands to {@link assembleAgentJob}. */
+interface ParsedAgentJobParts {
+  output: AgentOutputSpec | undefined
+  pr: { title: string; body: string } | undefined
+  infra: ReturnType<typeof parseAgentInfraSpec>
+  peerRepos: ReturnType<typeof parsePeerRepos>
+  referenceRepos: ReturnType<typeof parseReferenceRepos>
+  referenceBranches: ReturnType<typeof parseReferenceBranches>
+  bootstrap: ReturnType<typeof parseAgentBootstrapSpec>
+  contextFiles: ReturnType<typeof parseContextFiles>
+  packageRegistries: ReturnType<typeof parsePackageRegistries>
+  skill: ReturnType<typeof parseSkillSpec>
+  testSecrets: ReturnType<typeof parseTestSecrets>
+  guardLimits: ReturnType<typeof parseGuardLimits>
+  validation: ReturnType<typeof parseValidationSpec>
+  reviewPrNumber: number | undefined
+}
+
+/** Parse the optional structured-output spec (`{ kind, shapeHint?, repair?, failOnUnusableFinal? }`). */
+function parseAgentOutputSpec(raw: unknown): AgentOutputSpec | undefined {
+  if (typeof raw !== 'object' || raw === null) return undefined
+  const so = raw as Record<string, unknown>
+  const kind = so.kind === 'structured' ? 'structured' : 'prose'
+  const spec: AgentOutputSpec = { kind }
+  if (typeof so.shapeHint === 'string') spec.shapeHint = so.shapeHint
+  // Carry an explicit `repair: false` through — the handler defaults to repair-on
+  // when absent, so dropping `false` would silently re-enable the repair call for a
+  // kind that opted out (it keys off `output.repair === false`).
+  if (typeof so.repair === 'boolean') spec.repair = so.repair
+  // Carry the opt-in truncation gate through (document producers set it); dropping
+  // it would silently re-enable laundering a cut-off reply into a half-baked doc.
+  if (so.failOnUnusableFinal === true) spec.failOnUnusableFinal = true
+  return spec
+}
+
+/** Parse the optional PR spec (`{ title, body }`). */
+function parseAgentPrSpec(raw: unknown): { title: string; body: string } | undefined {
+  if (typeof raw !== 'object' || raw === null) return undefined
+  const p = raw as Record<string, unknown>
+  return { title: str(p.title, 'pr.title'), body: typeof p.body === 'string' ? p.body : '' }
+}
+
+/**
+ * Assemble the {@link AgentJob} object from the request `o` + the pre-parsed {@link
+ * ParsedAgentJobParts}. Extracted from {@link parseAgentJob} so the large conditional-spread
+ * literal doesn't blow the complexity budget; behaviour is byte-identical (spread order preserved).
+ */
+function assembleAgentJob(
+  o: Record<string, unknown>,
+  mode: AgentJob['mode'],
+  agentField: (value: unknown, path: string) => string,
+  parts: ParsedAgentJobParts,
+): AgentJob {
+  const {
+    output,
+    pr,
+    infra,
+    peerRepos,
+    referenceRepos,
+    referenceBranches,
+    bootstrap,
+    contextFiles,
+    packageRegistries,
+    skill,
+    testSecrets,
+    guardLimits,
+    validation,
+    reviewPrNumber,
+  } = parts
   const repo = (o.repo ?? {}) as Record<string, unknown>
-  const output =
-    typeof o.output === 'object' && o.output !== null
-      ? (() => {
-          const so = o.output as Record<string, unknown>
-          const kind = so.kind === 'structured' ? 'structured' : 'prose'
-          const spec: AgentOutputSpec = { kind }
-          if (typeof so.shapeHint === 'string') spec.shapeHint = so.shapeHint
-          // Carry an explicit `repair: false` through — the handler defaults to repair-on
-          // when absent, so dropping `false` would silently re-enable the repair call for a
-          // kind that opted out (it keys off `output.repair === false`).
-          if (typeof so.repair === 'boolean') spec.repair = so.repair
-          // Carry the opt-in truncation gate through (document producers set it); dropping
-          // it would silently re-enable laundering a cut-off reply into a half-baked doc.
-          if (so.failOnUnusableFinal === true) spec.failOnUnusableFinal = true
-          return spec
-        })()
-      : undefined
-  const pr =
-    typeof o.pr === 'object' && o.pr !== null
-      ? (() => {
-          const p = o.pr as Record<string, unknown>
-          return { title: str(p.title, 'pr.title'), body: typeof p.body === 'string' ? p.body : '' }
-        })()
-      : undefined
-  const infra = parseAgentInfraSpec(o.infra)
-  const peerRepos = parsePeerRepos(o.peerRepos)
-  const referenceRepos = parseReferenceRepos(o.referenceRepos)
-  const referenceBranches = parseReferenceBranches(o.referenceBranches)
-  const bootstrap = parseAgentBootstrapSpec(o.bootstrap)
-  const contextFiles = parseContextFiles(o.contextFiles)
-  const packageRegistries = parsePackageRegistries(o.packageRegistries)
-  const skill = parseSkillSpec(o.skill)
-  const testSecrets = parseTestSecrets(o.testSecrets)
-  const guardLimits = parseGuardLimits(o.guardLimits)
-  const validation = parseValidationSpec(o.validation)
-  const reviewPrNumber = posInt(o.reviewPrNumber)
-  const job: AgentJob = {
+  return {
     jobId: str(o.jobId, 'jobId'),
     mode,
     systemPrompt: agentField(o.systemPrompt, 'systemPrompt'),
@@ -1325,22 +1397,4 @@ export function parseAgentJob(input: unknown): AgentJob {
     ...(guardLimits ? { guardLimits } : {}),
     ...(validation ? { validation } : {}),
   }
-  assertAllowedHost(job.repo.cloneUrl, 'repo.cloneUrl')
-  if (job.githubApiBase) assertAllowedHost(job.githubApiBase, 'githubApiBase')
-  // Bootstrap pushes the result to a SEPARATE target repo, so its clone URL must be an
-  // allowed GitHub host too (the installation token is sent to it on the force-push).
-  if (job.bootstrap) assertAllowedHost(job.bootstrap.target.cloneUrl, 'bootstrap.target.cloneUrl')
-  // Each peer repo's clone URL receives the installation token on clone/push, so it must be
-  // an allowed GitHub host too — a body-supplied peer pointing at an attacker host would
-  // exfiltrate the token exactly like a rogue primary clone URL.
-  for (const [i, peer] of (job.peerRepos ?? []).entries()) {
-    assertAllowedHost(peer.repo.cloneUrl, `peerRepos[${i}].repo.cloneUrl`)
-  }
-  // Each reference repo's clone URL receives the installation/PAT token on clone (read-only,
-  // never pushed), so it must be an allowed host too — a body-supplied reference pointing at an
-  // attacker host would exfiltrate the token exactly like a rogue peer clone URL.
-  for (const [i, ref] of (job.referenceRepos ?? []).entries()) {
-    assertAllowedHost(ref.repo.cloneUrl, `referenceRepos[${i}].repo.cloneUrl`)
-  }
-  return job
 }

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