@cat-factory/executor-harness 1.52.0 → 1.54.0

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

@@ -51,6 +51,17 @@ export interface RunOptions {
   onPhase?: (phase: string) => void
   /** A per-job child logger carrying the run's correlation fields (jobId, repo, branch, …). */
   log?: Logger
+  /**
+   * Extra environment for the agent's child process, scoped to THIS job. The CLI is spawned with
+   * `{...process.env, ...agentEnv}`, so these reach the agent and every shell tool it spawns.
+   *
+   * This is the seam for anything per-job that would otherwise be written to a process- or
+   * HOME-global (the tester's secrets, a private-registry npmrc pointer). Those globals are only
+   * per-job when the process is — true for a container, FALSE for the local native host-process
+   * transport, which serves every concurrent ambient job from one process on the developer's own
+   * HOME. Set it via `withAgentEnv`; never mutate `process.env` for a job.
+   */
+  agentEnv?: Record<string, string>
 }
 
 export type JobState = 'running' | 'done' | 'failed'

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)
 // ---------------------------------------------------------------------------