@cat-factory/executor-harness 1.62.0 → 1.64.2

package/src/agent-runner.ts

@@ -19,11 +19,13 @@ import {
   type PiRunStats,
   type TodoProgress,
 } from './pi.js'
+import { ProgressGuard, type ProgressGuardLimits } from './progress-guard.js'
 import { killChildProcess, spawnDetached } from './process.js'
 import { redact, secretsToRedact } from './redact.js'
 import { createSliceTracker, startSubagentWatcher } from './subagents.js'
 import {
   createTaskPlanTracker,
+  mergeProgress,
   normalizeStatus,
   pickProgress,
   toProgress,
@@ -101,6 +103,17 @@ export interface SubscriptionRunOptions {
   extraEnv?: Record<string, string>
   /** Aborting this kills the CLI (the job's inactivity/max-duration watchdog). */
   signal?: AbortSignal
+  /**
+   * Fully-resolved no-progress guard limits (env defaults merged loosen-only with the kind's
+   * tuning + any complexity-scaled allowance). When set, the claude-code runner runs the SAME
+   * {@link ProgressGuard} as Pi over the CLI's tool stream and kills a run that has plainly
+   * stopped making progress (no-edit probing, error-retry loop, web rabbit-hole) rather than
+   * letting it burn the whole wall-clock budget. Omitted ⇒ the guard is disabled for this run
+   * (only the external watchdog bounds it), preserving the pre-guard behaviour.
+   */
+  guardLimits?: ProgressGuardLimits
+  /** Whether this run is expected to edit files (false for assess-only runs); gates the no-edit bound. */
+  expectsEdits?: boolean
   /** Called on every chunk of CLI output, so the watchdog sees the agent is alive. */
   onActivity?: () => void
   /** Called with the latest subtask counts each time the CLI updates its todo/plan list. */
@@ -154,7 +167,7 @@ function streamCli(
   opts: SubscriptionRunOptions,
   env: Record<string, string>,
   secrets: string[],
-  onEvent: (event: Record<string, unknown>) => void,
+  onEvent: (event: Record<string, unknown>, meta?: { final?: boolean }) => void,
 ): Promise<{ stderrTail: string }> {
   const { command, args } = cli
   return new Promise((resolve, reject) => {
@@ -178,7 +191,12 @@ function streamCli(
 
     const killChild = (): void => killChildProcess(child)
 
-    const processLine = (line: string): void => {
+    // `final` marks the at-close flush of a trailing unterminated line: the CLI has already
+    // exited, so an observer must not act on that record in a way that KILLS the run (mirrors
+    // `runPi`'s `runGuard = false` flush — without it, a guard tripping on the last buffered
+    // record could turn a clean exit into a spurious "no progress" failure). The record's
+    // progress/telemetry signal is still delivered; only kill decisions are suppressed.
+    const processLine = (line: string, final = false): void => {
       if (!line.startsWith('{')) return
       let event: Record<string, unknown>
       try {
@@ -187,7 +205,7 @@ function streamCli(
         return
       }
       try {
-        onEvent(event)
+        onEvent(event, { final })
       } catch {
         // A faulty observer must never break the run.
       }
@@ -226,10 +244,13 @@ function streamCli(
     })
     child.on('close', (code) => {
       opts.signal?.removeEventListener('abort', onAbort)
-      if (lineBuffer.trim()) processLine(lineBuffer.trim())
       const stderrTail = redact(stderr, secrets).slice(-700)
+      if (lineBuffer.trim()) processLine(lineBuffer.trim(), true)
       if (aborted) {
-        reject(new Error('agent run aborted by watchdog'))
+        // Carry the tail on the rejection so a caller that REPLACES this generic message with a
+        // more specific cause (the no-progress guard's diagnostic) can still append it — the
+        // stderr is often the only evidence of what the CLI was doing when it was killed.
+        reject(Object.assign(new Error('agent run aborted by watchdog'), { stderrTail }))
         return
       }
       if (code !== 0) {
@@ -358,31 +379,67 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
   // may still rewrite below (a published call must be final — see the publisher).
   const publisher = createCallMetricPublisher(calls, opts.onCallMetric)
 
-  // ADR 0026 D2.1 + ADR 0027 Defect B: surface live slice progress from TWO reconciled
-  // sources. The parent's subagent dispatches + their terminal tool_results DO appear on this
-  // stream (only a subagent's intermediate turns don't), so `sliceTracker` derives per-slice
-  // progress for the parallel shape; the parent's own plan (the sequential shape) is tracked
-  // by `planTracker` + `lastTodo`. `pickProgress` picks whichever is further along on each
-  // update, so neither masks the other — the pr-reviewer prompt writes its plan ONCE and never
-  // marks it done, which used to gate the slice signal off and pin progress at 0%.
+  // ADR 0026 D2.1 + ADR 0027 Defect B: surface live slice progress from the two views the run
+  // produces of the SAME slicing. The parent's subagent dispatches + their terminal tool_results
+  // DO appear on this stream (only a subagent's intermediate turns don't), so `sliceTracker`
+  // knows which slices are in flight and which have returned; the parent's own plan (tracked by
+  // `planTracker` + `lastTodo`) is the only place a not-yet-dispatched slice is named at all.
   //
   // The plan arrives in one of two tool vocabularies depending on the bundled CLI build:
   // `TodoWrite` (whole-list snapshots, tracked in `lastTodo`) or the incremental
   // `TaskCreate`/`TaskUpdate` pair (tracked by `planTracker`, which needs the tool RESULTS too
-  // because the task id is minted there). Both are read — see ./progress.ts.
+  // because the task id is minted there). Both are read, and `pickProgress` resolves that
+  // either/or; the plan then MERGES with the dispatch view (`mergeProgress`) rather than
+  // competing with it — picking the further-along view collapsed the list to the dispatched
+  // slices alone the moment the first subagent returned. See ./progress.ts.
   const sliceTracker = createSliceTracker()
   const planTracker = createTaskPlanTracker()
   let lastTodo: TodoProgress | undefined
   const emitProgress = (): void => {
     if (!opts.onProgress) return
-    const progress = pickProgress(
+    const progress = mergeProgress(
       pickProgress(lastTodo, planTracker.progress()),
       sliceTracker.progress(),
     )
     if (progress) opts.onProgress(progress)
   }
 
-  const onEvent = (event: Record<string, unknown>): void => {
+  // No-progress guard on the CLI's own tool stream — the claude-code analogue of runPi's guard,
+  // absent on this path until now. Claude Code reports a tool CALL (its name) on the `assistant`
+  // turn and that call's RESULT (`is_error`) on the following `user` turn, so correlate them by
+  // `tool_use` id to feed the guard a {name,isError} signal. A tripped guard aborts the CLI via
+  // `guardAbort` (folded into streamCli's signal below) and the run then fails with its
+  // diagnostic. Disabled when the caller supplies no limits (only the external watchdog bounds it).
+  const guard = opts.guardLimits
+    ? new ProgressGuard(opts.guardLimits, opts.expectsEdits ?? true)
+    : undefined
+  const toolNames = new Map<string, string>()
+  const guardAbort = new AbortController()
+  let guardReason: string | undefined
+
+  // Feed a user turn's settled tool calls to the guard, pairing each `tool_result`'s `is_error`
+  // with the name captured for its `tool_use` id on the assistant turn. The FIRST reason trips
+  // it: record the diagnostic and abort the CLI (streamCli's close handler rejects; the catch
+  // below surfaces `guardReason` over the generic abort message). A standalone closure so the
+  // per-block loop doesn't nest onEvent past the readable-depth limit.
+  const feedGuard = (content: unknown[]): void => {
+    if (!guard || guardReason) 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 name = id ? toolNames.get(id) : undefined
+      if (id) toolNames.delete(id)
+      if (!name) continue
+      const reason = guard.observeSignal({ name, isError: block.is_error === true })
+      if (reason) {
+        guardReason = reason
+        guardAbort.abort()
+        return
+      }
+    }
+  }
+
+  const onEvent = (event: Record<string, unknown>, meta?: { final?: boolean }): void => {
     const type = event.type
     if (type === 'assistant' && isObject(event.message)) {
       const message = event.message as Record<string, unknown>
@@ -391,7 +448,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') {
+        if (!isObject(block) || block.type !== 'tool_use') continue
+        // Remember each call's name against its id so the guard can pair it with the
+        // `is_error` its `tool_result` carries on the next `user` turn.
+        if (typeof block.id === 'string' && typeof block.name === 'string') {
+          toolNames.set(block.id, block.name)
+        }
+        if (block.name === 'TodoWrite') {
           const progress = todosToProgress((block.input as Record<string, unknown>)?.todos)
           if (progress) lastTodo = progress
         }
@@ -422,6 +485,9 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
         sliceTracker.onUser(content)
         planTracker.onUser(content)
         emitProgress()
+        // Not on the at-close flush: the CLI has already exited, so tripping the guard there
+        // would kill nothing and only convert a clean exit into a spurious failure.
+        if (!meta?.final) feedGuard(content)
         messages.push({ role: 'tool', content })
       }
     } else if (type === 'result') {
@@ -488,6 +554,12 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
       })
     : undefined
 
+  // Fold the guard's abort into the run signal so a tripped guard kills the CLI the same way the
+  // external watchdog does; `guardReason` (set above) distinguishes the two at the catch below.
+  const runSignal = opts.signal
+    ? AbortSignal.any([opts.signal, guardAbort.signal])
+    : guardAbort.signal
+
   try {
     const { stderrTail } = await streamCli(
       {
@@ -509,7 +581,7 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
         ],
       },
       prompt,
-      opts,
+      { ...opts, signal: runSignal },
       env,
       opts.subscriptionToken ? secretsToRedact(opts.subscriptionToken) : [],
       onEvent,
@@ -524,6 +596,16 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
       usage,
       subagents,
     })
+  } catch (err) {
+    // A tripped no-progress guard aborted the CLI; streamCli rejects with its generic abort
+    // message, so replace it with the guard's actionable diagnostic — carrying the stderr tail
+    // it attached, since that is usually the only evidence of what the CLI was doing when it was
+    // killed. Byte-for-byte the shape `runPi` fails with.
+    if (guardReason) {
+      const tail = (err as { stderrTail?: string } | undefined)?.stderrTail
+      throw new Error(tail ? `${guardReason} Agent stderr: ${tail}` : guardReason)
+    }
+    throw err
   } finally {
     await subagents?.stop()
     if (configHome) {

package/src/claude-stream.ts

@@ -10,6 +10,25 @@ export function isObject(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null
 }
 
+/**
+ * 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.
+ *
+ * Lives here rather than in `subagents.ts` because BOTH the slice tracker and the no-progress
+ * guard (`pi.ts`, which `subagents.ts` imports — so it cannot import back) must agree on what a
+ * subagent dispatch looks like.
+ */
+export const SUBAGENT_TOOL_NAMES = new Set(['Agent', 'Task'])
+
 export function numberOf(value: unknown): number {
   return typeof value === 'number' && Number.isFinite(value) ? value : 0
 }

package/src/coding-agent.ts

@@ -46,7 +46,7 @@ import {
   runAgentInWorkspace,
   withWorkspace,
 } from './pi-workspace.js'
-import type { ProgressGuardLimits } from './pi.js'
+import type { ProgressGuardLimits } from './progress-guard.js'
 import type { RunOptions } from './runner.js'
 import { log, type Logger } from './logger.js'
 import {

package/src/embed.ts

@@ -7,21 +7,23 @@
 
 export {
   PI_MAX_OUTPUT_TOKENS,
-  DEFAULT_PROGRESS_GUARD_LIMITS,
   writePiModelsConfig,
   writeAgentsContext,
   runPi,
   summarizePiRun,
   parsePiOutput,
   parseTodoProgress,
-  progressGuardLimitsFromEnv,
   terminalRunError,
   type PiRunOutcome,
   type PiRunStats,
-  type ProgressGuardLimits,
   type TodoItem,
   type TodoProgress,
 } from './pi.js'
+export {
+  DEFAULT_PROGRESS_GUARD_LIMITS,
+  progressGuardLimitsFromEnv,
+  type ProgressGuardLimits,
+} from './progress-guard.js'
 export {
   cloneRepo,
   createBranch,

package/src/pi-workspace.ts

@@ -1,4 +1,4 @@
-import { mkdir, mkdtemp, rm } from 'node:fs/promises'
+import { mkdir, mkdtemp, readdir, rm, stat } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import type { RepoSpec, SkillSpec } from './job.js'
@@ -8,13 +8,10 @@ import {
   type ContextFileInfo,
   type PiRunOutcome,
   type PiRunStats,
-  type ProgressGuardLimits,
   type RunDiagnostics,
   CONTEXT_DIR,
   materializeContextFiles,
   materializeSkillResources,
-  mergeGuardLimits,
-  progressGuardLimitsFromEnv,
   runPi,
   webSearchConfigFromEnv,
   webSearchProxyEnv,
@@ -22,6 +19,11 @@ import {
   writePiModelsConfig,
   writeWebToolsConfig,
 } from './pi.js'
+import {
+  type ProgressGuardLimits,
+  mergeGuardLimits,
+  progressGuardLimitsFromEnv,
+} from './progress-guard.js'
 import type { RunOptions } from './runner.js'
 import { type SubscriptionHarness, runSubscriptionHarness } from './agent-runner.js'
 
@@ -226,6 +228,31 @@ export interface AgentRunSpec {
   multiRepo?: boolean
 }
 
+/**
+ * Whether the run's checkout actually ships a `blueprints/` folder — what gates the blueprint
+ * orientation note in AGENTS.md (an external repo has none, so the note would be ~10 lines of
+ * dead guidance pointing at files that don't exist, re-sent on every turn).
+ *
+ * A MULTI-REPO run's `dir` is the workspace ROOT with each repo checked out as a sibling under
+ * it, so the root itself never holds `blueprints/`: the legs are checked too, and the note is
+ * included when ANY leg ships one (it orients the agent to the concept, and the agent finds the
+ * per-repo folder from there). Best-effort throughout — any stat/readdir failure simply omits
+ * the note rather than failing the dispatch.
+ */
+export async function checkoutHasBlueprints(dir: string, multiRepo: boolean): Promise<boolean> {
+  const isBlueprintDir = (path: string): Promise<boolean> =>
+    stat(join(path, 'blueprints'))
+      .then((s) => s.isDirectory())
+      .catch(() => false)
+  if (await isBlueprintDir(dir)) return true
+  if (!multiRepo) return false
+  const legs = await readdir(dir, { withFileTypes: true }).catch(() => [])
+  const checks = await Promise.all(
+    legs.filter((e) => e.isDirectory()).map((e) => isBlueprintDir(join(dir, e.name))),
+  )
+  return checks.some(Boolean)
+}
+
 /**
  * Write Pi's global agent context (`~/.pi/agent/AGENTS.md`) + provider config,
  * then run Pi once in `spec.dir` and return its summary/stats/stderr. The context
@@ -272,6 +299,13 @@ export async function runAgentInWorkspace(
       ...(spec.skill ? { skill: spec.skill } : {}),
       ...(opts.agentEnv ? { extraEnv: opts.agentEnv } : {}),
       signal: opts.signal,
+      // Run the SAME no-progress guard Pi gets (previously claude-code/codex had none): env
+      // defaults merged loosen-only with the kind's tuning + the backend's complexity-scaled
+      // no-edit allowance, so a claude-code run that stops making progress is killed early
+      // instead of burning the full wall-clock budget. The claude runner consumes it; codex
+      // ignores it for now (its stream isn't wired to the guard).
+      guardLimits: mergeGuardLimits(progressGuardLimitsFromEnv(), spec.guardLimits),
+      expectsEdits: spec.expectsEdits ?? true,
       onActivity: opts.onActivity,
       onProgress: opts.onProgress,
       // Stream this run's per-call telemetry to the job's live drain. The subscription
@@ -303,11 +337,13 @@ export async function runAgentInWorkspace(
   }
   const webSearch = webSearchConfigFromEnv({ ...process.env, ...extraEnv })
   if (webSearch) await writeWebToolsConfig(webSearch)
+  const hasBlueprints = await checkoutHasBlueprints(spec.dir, spec.multiRepo === true)
   await writeAgentsContext(spec.systemPrompt, {
     webSearch: Boolean(webSearch),
     guidance: spec.webToolsGuidance,
     serviceDirectory: spec.serviceDirectory,
     contextFiles,
+    hasBlueprints,
     ...(spec.multiRepo ? { multiRepo: true } : {}),
   })
   await writePiModelsConfig({ model: spec.model, proxyBaseUrl })