@cat-factory/executor-harness 1.50.4 → 1.50.8

package/dist/subagents.js

@@ -0,0 +1,206 @@
+import { readdir, stat } from 'node:fs/promises';
+import { createReadStream } from 'node:fs';
+import { 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.
+    const slices = new Map();
+    return {
+        onAssistant(content) {
+            if (!Array.isArray(content))
+                return;
+            for (const block of content) {
+                if (!isObject(block) || block.type !== 'tool_use' || block.name !== 'Task')
+                    continue;
+                const id = typeof block.id === 'string' ? block.id : undefined;
+                if (!id || slices.has(id))
+                    continue;
+                const input = isObject(block.input) ? block.input : {};
+                const description = typeof input.description === 'string' && input.description.trim()
+                    ? input.description.trim()
+                    : `Subagent ${slices.size + 1}`;
+                slices.set(id, { toolUseId: id, description, done: false });
+            }
+        },
+        onUser(content) {
+            if (!Array.isArray(content))
+                return;
+            for (const block of content) {
+                if (!isObject(block) || block.type !== 'tool_result')
+                    continue;
+                const id = typeof block.tool_use_id === 'string' ? block.tool_use_id : undefined;
+                const slice = id ? slices.get(id) : undefined;
+                if (slice)
+                    slice.done = true;
+            }
+        },
+        hasSlices() {
+            return slices.size > 0;
+        },
+        progress() {
+            if (slices.size === 0)
+                return undefined;
+            const items = [...slices.values()].map((s) => ({
+                label: s.description,
+                status: (s.done ? 'completed' : 'in_progress'),
+            }));
+            const completed = items.filter((i) => i.status === 'completed').length;
+            return {
+                completed,
+                inProgress: items.length - completed,
+                total: items.length,
+                items,
+            };
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// 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.
+ */
+export function startSubagentWatcher(dir, opts) {
+    const secrets = opts.secrets ?? [];
+    const offsets = new Map();
+    const calls = [];
+    const usage = { inputTokens: 0, outputTokens: 0 };
+    // Per-file partial-line remainder, carried as raw BYTES (not a decoded string). A JSONL
+    // record can straddle two polls (the file is appended between ticks), and the byte offset
+    // we stop at can fall in the middle of a multi-byte UTF-8 character; decoding a partial
+    // read to a string would replace that split character with U+FFFD and corrupt the line.
+    // Buffering bytes and decoding only whole lines keeps the captured text faithful.
+    const carry = new Map();
+    let polling = false;
+    const ingestLine = (line) => {
+        const trimmed = line.trim();
+        if (!trimmed.startsWith('{'))
+            return;
+        let event;
+        try {
+            event = JSON.parse(trimmed);
+        }
+        catch {
+            return;
+        }
+        // Subagent transcripts mirror the session-transcript envelope: an `assistant` entry
+        // whose `message` carries the Anthropic `usage` + `content`. Read defensively.
+        if (event.type !== 'assistant' || !isObject(event.message))
+            return;
+        const message = event.message;
+        const u = claudeCallUsage(message.usage);
+        if (u.inputTokens === 0 && u.outputTokens === 0)
+            return;
+        const content = Array.isArray(message.content) ? message.content : [];
+        const { text, reasoning } = claudeAssistantContent(content);
+        calls.push({
+            ...(typeof message.model === 'string'
+                ? { model: message.model }
+                : opts.model
+                    ? { model: opts.model }
+                    : {}),
+            // The subagent's own transcript isn't a re-sendable prompt chain, so we don't
+            // reconstruct the request side (kept empty); the response + tokens are faithful.
+            promptText: '',
+            messageCount: 0,
+            responseText: redactBody(text, secrets),
+            reasoningText: redactBody(reasoning, secrets),
+            inputTokens: u.inputTokens,
+            cachedInputTokens: u.cachedInputTokens,
+            outputTokens: u.outputTokens,
+            finishReason: typeof message.stop_reason === 'string' ? message.stop_reason : null,
+        });
+        usage.inputTokens += u.inputTokens;
+        usage.outputTokens += u.outputTokens;
+    };
+    const NEWLINE = 0x0a;
+    const readNew = (path, from, to) => new Promise((resolve) => {
+        // Tail as raw bytes and split on the newline byte, decoding each COMPLETE line to
+        // UTF-8 only on that boundary (a '\n' is a single byte, never part of a multi-byte
+        // sequence), so a record — or a multi-byte character — that spans this read and the
+        // next is reassembled from the byte carry rather than corrupted at the seam.
+        let buffer = carry.get(path) ?? Buffer.alloc(0);
+        const stream = createReadStream(path, { start: from, end: to - 1 });
+        stream.on('data', (chunk) => {
+            buffer = buffer.length ? Buffer.concat([buffer, chunk]) : chunk;
+            let nl = buffer.indexOf(NEWLINE);
+            while (nl !== -1) {
+                ingestLine(buffer.subarray(0, nl).toString('utf8'));
+                buffer = buffer.subarray(nl + 1);
+                nl = buffer.indexOf(NEWLINE);
+            }
+        });
+        stream.on('error', () => resolve());
+        stream.on('close', () => {
+            // Copy the remainder out of the shared chunk backing store before caching it, so a
+            // later Buffer.concat can't be aliased by a reused stream buffer.
+            carry.set(path, Buffer.from(buffer));
+            resolve();
+        });
+    });
+    const pollOnce = async () => {
+        if (polling)
+            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);
+                let size;
+                try {
+                    size = (await stat(path)).size;
+                }
+                catch {
+                    continue;
+                }
+                const from = offsets.get(path) ?? 0;
+                if (size <= from)
+                    continue;
+                grew = true;
+                await readNew(path, from, size);
+                offsets.set(path, size);
+            }
+            if (grew)
+                opts.onActivity?.();
+        }
+        catch (e) {
+            opts.log?.warn('subagent transcript poll failed', { error: String(e) });
+        }
+        finally {
+            polling = false;
+        }
+    };
+    const timer = setInterval(() => void pollOnce(), opts.intervalMs ?? DEFAULT_POLL_MS);
+    // Don't let the watcher's timer keep the container process alive on its own.
+    timer.unref?.();
+    return {
+        // Always does a final drain (idempotent clear of the timer), so a late transcript
+        // write between the last tick and stop is still captured, and a second stop() picks up
+        // anything appended since — the per-file offsets make re-polling safe (no double count).
+        async stop() {
+            clearInterval(timer);
+            await pollOnce();
+        },
+        usage() {
+            return { ...usage };
+        },
+        calls() {
+            return calls;
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/executor-harness",
-  "version": "1.50.4",
+  "version": "1.50.8",
   "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.138.13",
-    "@cat-factory/spend": "0.12.63"
+    "@cat-factory/server": "0.140.2",
+    "@cat-factory/spend": "0.12.68"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",

package/src/agent-runner.ts

@@ -2,10 +2,19 @@ import { spawn } from 'node:child_process'
 import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'
 import { homedir, tmpdir } from 'node:os'
 import { dirname, join } from 'node:path'
+import {
+  claudeAssistantContent,
+  claudeCallUsage,
+  isObject,
+  numberOf,
+  redactBody,
+} from './claude-stream.js'
 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 { assertOnboardingKeysCurrent, writeOnboardingPreseed } from './onboarding-preseed.js'
 import { retainSessionTranscripts } from './transcript-retention.js'
 
 // The alternate (subscription) harness runners. The Pi harness reaches models
@@ -79,15 +88,6 @@ export interface SubscriptionRunOptions {
   log?: Logger
 }
 
-function isObject(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null
-}
-
-/** Scrub any leased-credential occurrences from a telemetry body (no-op when none). */
-function redactBody(text: string, secrets: string[]): string {
-  return secrets.length ? redact(text, secrets) : text
-}
-
 /**
  * Fallback token attribution: if a CLI reported a cumulative total but no per-turn
  * usage (so every captured call has zero tokens), pin the whole total onto the LAST
@@ -112,10 +112,11 @@ function attributeCumulativeUsage(
  * never argv), `onActivity` on every chunk, abort kills the child, and the close
  * handler resolves/rejects. The caller's `onEvent` accumulates the outcome.
  *
- * `prompt` is fed over stdin: for Claude Code that is just the task prompt (the
- * system prompt rides `--append-system-prompt`); for Codex — which has no
- * system-prompt flag — the caller prepends the composed system prompt to it so
- * the role + best-practice context is not lost.
+ * `prompt` is fed over stdin: for Claude Code that is normally just the task prompt (the
+ * system prompt rides `--append-system-prompt`), unless the system prompt is too large for
+ * argv, in which case it is folded into `prompt` (see `carryClaudeSystemPrompt`); for Codex
+ * — which has no system-prompt flag — the caller always prepends the composed system prompt
+ * so the role + best-practice context is not lost.
  */
 function streamCli(
   cli: { command: string; args: string[] },
@@ -210,6 +211,46 @@ function streamCli(
   })
 }
 
+/**
+ * Fold a composed system prompt into the task prompt so the role + best-practice context
+ * rides stdin as a single user turn. Used by the Codex runner (no system-prompt flag) and
+ * by the Claude runner's argv-overflow fallback. Empty system prompt ⇒ the task prompt is
+ * returned unchanged.
+ */
+function foldSystemPrompt(systemPrompt: string, userPrompt: string): string {
+  return systemPrompt ? `${systemPrompt}\n\n---\n\n${userPrompt}` : userPrompt
+}
+
+/**
+ * Linux caps a SINGLE argv string at MAX_ARG_STRLEN (32 pages = 128 KiB) — a per-string limit,
+ * distinct from (and reached long before) the far larger total ARG_MAX for argv + env combined. A
+ * system prompt with best-practice fragments folded in can exceed that per-string cap, and `execve`
+ * then fails the whole spawn with `E2BIG` before the agent runs at all — the failure mode seen on
+ * the `pr-reviewer` step (a ~150 KiB composed prompt). The binding constraint is that per-string
+ * cap; 96 KiB stays comfortably under 128 KiB so the system-prompt argv can never approach it.
+ */
+const MAX_ARGV_STRING_BYTES = 96 * 1024
+
+/**
+ * Decide how the Claude Code runner carries the composed system prompt. Small prompts ride
+ * `--append-system-prompt` (a real system turn, cacheable) as before; a prompt too large for a
+ * single argv string is instead folded into the stdin task prompt (like the Codex runner), which
+ * has no size ceiling. Pure so the branch is unit-testable without spawning the CLI.
+ */
+export function carryClaudeSystemPrompt(
+  systemPrompt: string,
+  userPrompt: string,
+): { appendArgs: string[]; prompt: string; folded: boolean } {
+  if (Buffer.byteLength(systemPrompt, 'utf8') <= MAX_ARGV_STRING_BYTES) {
+    return {
+      appendArgs: ['--append-system-prompt', systemPrompt],
+      prompt: userPrompt,
+      folded: false,
+    }
+  }
+  return { appendArgs: [], prompt: foldSystemPrompt(systemPrompt, userPrompt), folded: true }
+}
+
 // ---------------------------------------------------------------------------
 // Claude Code
 // ---------------------------------------------------------------------------
@@ -255,20 +296,48 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
   let summary = ''
   let usage: { inputTokens: number; outputTokens: number } | undefined
 
+  // Decide how the composed system prompt is carried up front, so the telemetry seed below
+  // reflects what actually reaches the model: a small prompt rides `--append-system-prompt`
+  // (a real system turn), while an argv-overflowing prompt is folded into the first user turn
+  // — in which case NO system turn of ours is sent (the `E2BIG` fallback).
+  const { appendArgs, prompt, folded } = carryClaudeSystemPrompt(opts.systemPrompt, opts.userPrompt)
+  if (folded) {
+    opts.log?.warn('system prompt exceeds argv limit; folding into the task prompt', {
+      bytes: Buffer.byteLength(opts.systemPrompt, 'utf8'),
+    })
+  }
+
   // Reconstruct the full per-call request/response bodies for telemetry from the
   // stream. `--output-format stream-json --verbose` emits each turn as a near-verbatim
   // Anthropic Messages envelope, so `assistant` events carry the complete response
   // (text + tool_use blocks + usage), and `user` events carry the tool_result blocks
-  // fed back — together the growing prompt transcript. We seed it with the two inputs
-  // the harness supplies (they never appear in the stream): the system + first user
-  // message. Bodies are credential-scrubbed (they can echo the leased token).
+  // fed back — together the growing prompt transcript. We seed it with the inputs the
+  // harness supplies (they never appear in the stream): the system + first user message
+  // when the prompt rides argv, or a single folded user turn when it doesn't — so the
+  // reconstruction never shows a system turn that was never sent. Bodies are
+  // credential-scrubbed (they can echo the leased token).
   const secrets = opts.subscriptionToken ? secretsToRedact(opts.subscriptionToken) : []
-  const messages: Array<{ role: string; content: unknown }> = [
-    { role: 'system', content: opts.systemPrompt },
-    { role: 'user', content: opts.userPrompt },
-  ]
+  const messages: Array<{ role: string; content: unknown }> = folded
+    ? [{ role: 'user', content: prompt }]
+    : [
+        { role: 'system', content: opts.systemPrompt },
+        { role: 'user', content: opts.userPrompt },
+      ]
   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).
+  const sliceTracker = createSliceTracker()
+  let sawTodoPlan = false
+  const emitSliceProgress = (): void => {
+    if (sawTodoPlan || !opts.onProgress) return
+    const progress = sliceTracker.progress()
+    if (progress) opts.onProgress(progress)
+  }
+
   const onEvent = (event: Record<string, unknown>): void => {
     const type = event.type
     if (type === 'assistant' && isObject(event.message)) {
@@ -285,9 +354,14 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
           opts.onProgress
         ) {
           const progress = todosToProgress((block.input as Record<string, unknown>)?.todos)
-          if (progress) opts.onProgress(progress)
+          if (progress) {
+            sawTodoPlan = true
+            opts.onProgress(progress)
+          }
         }
       }
+      sliceTracker.onAssistant(content)
+      emitSliceProgress()
       // 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.
@@ -307,7 +381,11 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
     } else if (type === 'user' && isObject(event.message)) {
       // tool_result blocks the harness fed back to the model — part of the next prompt.
       const content = (event.message as Record<string, unknown>).content
-      if (Array.isArray(content)) messages.push({ role: 'tool', content })
+      if (Array.isArray(content)) {
+        sliceTracker.onUser(content)
+        emitSliceProgress()
+        messages.push({ role: 'tool', content })
+      }
     } else if (type === 'result') {
       if (typeof event.result === 'string') summary = event.result
       usage = claudeUsage(event.usage) ?? usage
@@ -333,16 +411,12 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
   // as already accepted so `-p` starts straight into the run. Best-effort: written
   // before the CLI starts; unknown keys are harmless if a CLI version ignores them.
   // (Ambient mode skips this — the developer's own config is already onboarded.)
+  // ADR 0026 D4: assert the pinned onboarding keys landed and log them with the CLI
+  // version, so a future first-run gate this set doesn't cover (which looks identical to
+  // a healthy-but-quiet subagent start) is diffable when the cold-start watchdog fires.
   if (configHome) {
-    await writeFile(
-      join(configHome, '.claude.json'),
-      JSON.stringify({
-        hasCompletedOnboarding: true,
-        bypassPermissionsModeAccepted: true,
-        hasTrustDialogAccepted: true,
-      }),
-      { mode: 0o600 },
-    ).catch(() => {})
+    await writeOnboardingPreseed(configHome)
+    await assertOnboardingKeysCurrent(configHome, process.env.CLAUDE_CLI_VERSION, opts.log)
   }
 
   // Repo-sourced Claude Skill (slice 2): install it as a native skill under the config dir's
@@ -372,6 +446,20 @@ 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.
+  const subagents = configHome
+    ? startSubagentWatcher(join(configHome, 'subagents'), {
+        ...(opts.onActivity ? { onActivity: opts.onActivity } : {}),
+        secrets,
+        model: opts.model,
+        ...(opts.log ? { log: opts.log } : {}),
+      })
+    : undefined
+
   try {
     const { stderrTail } = await streamCli(
       {
@@ -389,26 +477,50 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
           'bypassPermissions',
           '--model',
           opts.model,
-          '--append-system-prompt',
-          opts.systemPrompt,
+          ...appendArgs,
         ],
       },
-      opts.userPrompt,
+      prompt,
       opts,
       env,
       opts.subscriptionToken ? secretsToRedact(opts.subscriptionToken) : [],
       onEvent,
     )
 
+    // The parent's cumulative-usage fallback applies to the PARENT calls only (before the
+    // subagent calls, which carry their own per-turn tokens, are concatenated).
     attributeCumulativeUsage(calls, usage)
+    // Final drain of any subagent transcript writes that landed after the last poll, then
+    // fold the subagents' usage + per-call telemetry into the run's outcome — their tokens
+    // never appear on the parent stream, so this is the only place they are accounted.
+    await subagents?.stop()
+    const subUsage = subagents?.usage() ?? { inputTokens: 0, outputTokens: 0 }
+    const subCalls = subagents?.calls() ?? []
+    const mergedCalls = [...calls, ...subCalls]
+    // INVARIANT (do not "fix" this into a double count): the run total is the parent usage
+    // PLUS the subagent usage because the two are disjoint sources. The parent `usage` here
+    // 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.
+    const mergedUsage =
+      usage || subUsage.inputTokens || subUsage.outputTokens
+        ? {
+            inputTokens: (usage?.inputTokens ?? 0) + subUsage.inputTokens,
+            outputTokens: (usage?.outputTokens ?? 0) + subUsage.outputTokens,
+          }
+        : undefined
     return {
       summary,
       stats,
       stderrTail,
-      ...(usage ? { usage } : {}),
-      ...(calls.length ? { callMetrics: calls } : {}),
+      ...(mergedUsage ? { usage: mergedUsage } : {}),
+      ...(mergedCalls.length ? { callMetrics: mergedCalls } : {}),
     }
   } finally {
+    await subagents?.stop()
     if (configHome) {
       // Lift the CLI session transcripts (`projects/`) out for short-lived retention BEFORE the
       // home is deleted — the credential lives at the home root, never in `projects/`, so this
@@ -456,44 +568,6 @@ function claudeUsage(raw: unknown): { inputTokens: number; outputTokens: number
   return { inputTokens: input, outputTokens: output }
 }
 
-/** Pull the text + reasoning out of a Claude `assistant` message's content blocks. */
-function claudeAssistantContent(content: unknown[]): {
-  text: string
-  reasoning: string
-  toolUses: number
-} {
-  let text = ''
-  let reasoning = ''
-  let toolUses = 0
-  for (const block of content) {
-    if (!isObject(block)) continue
-    if (block.type === 'text' && typeof block.text === 'string') text += block.text
-    else if (block.type === 'thinking' && typeof block.thinking === 'string')
-      reasoning += block.thinking
-    else if (block.type === 'tool_use') toolUses += 1
-  }
-  return { text, reasoning, toolUses }
-}
-
-/**
- * Per-CALL token usage off a Claude `assistant` message's `usage` (this turn only, not
- * the cumulative `result` total). `inputTokens` counts every billed input bucket (fresh
- * + both cache buckets); `cachedInputTokens` is the cache share, surfaced separately.
- */
-function claudeCallUsage(raw: unknown): {
-  inputTokens: number
-  cachedInputTokens: number
-  outputTokens: number
-} {
-  if (!isObject(raw)) return { inputTokens: 0, cachedInputTokens: 0, outputTokens: 0 }
-  const cached = numberOf(raw.cache_read_input_tokens) + numberOf(raw.cache_creation_input_tokens)
-  return {
-    inputTokens: numberOf(raw.input_tokens) + cached,
-    cachedInputTokens: cached,
-    outputTokens: numberOf(raw.output_tokens),
-  }
-}
-
 // ---------------------------------------------------------------------------
 // Codex
 // ---------------------------------------------------------------------------
@@ -539,10 +613,9 @@ export async function runCodex(opts: SubscriptionRunOptions): Promise<PiRunOutco
   }
 
   // Codex has no system-prompt flag, so fold the composed role + best-practice
-  // context into the prompt itself (Claude Code instead rides --append-system-prompt).
-  const prompt = opts.systemPrompt
-    ? `${opts.systemPrompt}\n\n---\n\n${opts.userPrompt}`
-    : opts.userPrompt
+  // context into the prompt itself (Claude Code instead rides --append-system-prompt,
+  // falling back to this same fold when the prompt overflows argv).
+  const prompt = foldSystemPrompt(opts.systemPrompt, opts.userPrompt)
 
   // Codex's `exec --json` is far thinner than Claude Code's stream: it surfaces only
   // flat assistant text and (on `token_count` events) the per-turn `last_token_usage`
@@ -754,10 +827,6 @@ function codexLastTurnUsage(event: Record<string, unknown>):
   return { inputTokens: input, cachedInputTokens: cached, outputTokens: output }
 }
 
-function numberOf(value: unknown): number {
-  return typeof value === 'number' && Number.isFinite(value) ? value : 0
-}
-
 /** Dispatch to the configured subscription harness runner. */
 export function runSubscriptionHarness(
   harness: SubscriptionHarness,

package/src/claude-stream.ts

@@ -0,0 +1,58 @@
+import { redact } from './redact.js'
+
+// Shared parsing of Claude Code's stream-json / session-transcript envelope. The parent
+// runner (`agent-runner.ts`) reads these off the CLI's stdout; the subagent watcher
+// (`subagents.ts`) reads the same shapes off the `subagents/*.jsonl` transcripts. Kept in
+// one place so both read usage/content identically and the cycle between the two modules
+// is broken.
+
+export function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null
+}
+
+export function numberOf(value: unknown): number {
+  return typeof value === 'number' && Number.isFinite(value) ? value : 0
+}
+
+/** Scrub any leased-credential occurrences from a telemetry body (no-op when none). */
+export function redactBody(text: string, secrets: string[]): string {
+  return secrets.length ? redact(text, secrets) : text
+}
+
+/** Pull the text + reasoning out of a Claude `assistant` message's content blocks. */
+export function claudeAssistantContent(content: unknown[]): {
+  text: string
+  reasoning: string
+  toolUses: number
+} {
+  let text = ''
+  let reasoning = ''
+  let toolUses = 0
+  for (const block of content) {
+    if (!isObject(block)) continue
+    if (block.type === 'text' && typeof block.text === 'string') text += block.text
+    else if (block.type === 'thinking' && typeof block.thinking === 'string')
+      reasoning += block.thinking
+    else if (block.type === 'tool_use') toolUses += 1
+  }
+  return { text, reasoning, toolUses }
+}
+
+/**
+ * Per-CALL token usage off a Claude `assistant` message's `usage` (this turn only, not
+ * the cumulative `result` total). `inputTokens` counts every billed input bucket (fresh
+ * + both cache buckets); `cachedInputTokens` is the cache share, surfaced separately.
+ */
+export function claudeCallUsage(raw: unknown): {
+  inputTokens: number
+  cachedInputTokens: number
+  outputTokens: number
+} {
+  if (!isObject(raw)) return { inputTokens: 0, cachedInputTokens: 0, outputTokens: 0 }
+  const cached = numberOf(raw.cache_read_input_tokens) + numberOf(raw.cache_creation_input_tokens)
+  return {
+    inputTokens: numberOf(raw.input_tokens) + cached,
+    cachedInputTokens: cached,
+    outputTokens: numberOf(raw.output_tokens),
+  }
+}