@cat-factory/executor-harness 1.62.0 → 1.64.0

package/dist/progress-guard.js

@@ -0,0 +1,211 @@
+import { SUBAGENT_TOOL_NAMES } from './claude-stream.js';
+// The harness's no-progress guard: the live anti-rabbithole bound every agent run is held to,
+// plus the tool-name vocabulary it classifies calls with and the limits it reads from the
+// environment. Extracted from `pi.ts` when the guard stopped being Pi's: it now also drives the
+// claude-code subscription runner (`agent-runner.ts` feeds it via `observeSignal`), so the two
+// harnesses share ONE definition of "this run has stopped making progress" — and the tool-name
+// sets below deliberately cover both CLIs' vocabularies.
+/**
+ * Tool-call signal read off a streamed Pi event, or undefined if not a tool call. Exported for
+ * `runPi`'s span emitter, which reads the same event for its per-tool trace spans.
+ */
+export function toolCallSignal(event) {
+    // `tool_execution_end` is the canonical per-call stream event (statsFromEvents
+    // counts the same one), so the guard reads it and nothing else — no double count.
+    if (event.type !== 'tool_execution_end')
+        return undefined;
+    const name = typeof event.toolName === 'string' ? event.toolName : '';
+    return { name, isError: event.isError === true };
+}
+// `satisfies` (not a type annotation) so each property keeps its concrete `number`
+// type — `maxConsecutiveWebCalls` is optional on the interface (callers may omit it),
+// but the defaults always define it, so consumers reading it off here get a `number`.
+export const DEFAULT_PROGRESS_GUARD_LIMITS = {
+    // Counts only non-exploration, non-planning calls (see EXPLORATION_TOOLS), so the
+    // ceiling can be generous without risking a false kill on a read-heavy large task.
+    maxToolCallsWithoutEdit: 40,
+    maxConsecutiveErrors: 12,
+    // A genuine research burst is a handful of searches; an uninterrupted run of this
+    // many web calls (with no read/edit/bash between) is a search loop, not progress.
+    maxConsecutiveWebCalls: 25,
+};
+// Tool names that mutate files, so a call to one clears the no-edit suspicion. Kept
+// broad on purpose: different models/extensions name the same capability differently
+// (`edit`/`write`, but also `apply_patch`/`patch`/`str_replace`/`multiedit`/`create`),
+// and a false "no edits" reading would kill a run that IS making changes. Matched
+// case-insensitively. NOTE: a file written purely via `bash` (e.g. a heredoc) is not
+// recognised here — broaden or move to a working-tree signal if that becomes common.
+const FILE_EDIT_TOOLS = new Set([
+    'edit',
+    'write',
+    'apply_patch',
+    'patch',
+    'str_replace',
+    'multiedit',
+    'create',
+    // Claude Code tool names (the guard now runs on the claude-code stream too): Edit/Write/
+    // MultiEdit already match above; NotebookEdit is its own tool.
+    'notebookedit',
+]);
+// Planning/bookkeeping tools that are neither file edits nor the environment-probing
+// the no-edit bound targets — the todo list the agent maintains as it works. These do
+// NOT count toward `maxToolCallsWithoutEdit`: a run that diligently updates a long
+// todo list before its first edit (common on a large task) would otherwise be killed
+// for "no edits" purely from planning calls. They still reset the consecutive-error
+// streak (a successful call means the agent isn't wedged). Matched case-insensitively.
+// `todo` is Pi's tool; `TodoWrite` and the incremental `TaskCreate`/`TaskUpdate` pair are
+// Claude Code's plan vocabularies — all pure bookkeeping, exempt from the no-edit bound.
+const PLANNING_TOOLS = new Set(['todo', 'todowrite', 'taskcreate', 'taskupdate']);
+// A subagent dispatch (Claude Code's `Agent`/`Task`) is exempt from the no-edit bound because
+// the parent stream CANNOT see the edits it makes: only the dispatch and its terminal
+// tool_result appear there, while every Edit/Write the subagent performs happens on a transcript
+// the guard never reads (`subagents.ts` watches those separately, for usage/progress only). So a
+// coder that fans its implementation out across subagents looks, to this guard, like a run making
+// dozens of action calls and zero edits — and would be killed for making excellent progress.
+// Counting them as edits instead would be worse (a read-only research subagent would then clear
+// the suspicion the bound exists to hold), so they are neutral: they neither count toward the
+// bound nor satisfy it. Sourced from the same set the slice tracker matches on, lower-cased for
+// this module's case-insensitive comparison.
+const SUBAGENT_DISPATCH_TOOLS = new Set([...SUBAGENT_TOOL_NAMES].map((name) => name.toLowerCase()));
+// Read-only exploration tools: reading/searching the repo is legitimate work-up to an
+// edit, NOT the environment-probing the no-edit bound targets, so they don't count
+// toward `maxToolCallsWithoutEdit` (a large task may read/search dozens of files
+// before its first edit). The bound thus counts only "action" calls — chiefly `bash`
+// (the credential rabbit-hole's vector) — that have yet to produce an edit. Kept broad
+// since models/extensions name the same capability differently. Matched case-insensitively.
+const EXPLORATION_TOOLS = new Set([
+    'read',
+    'grep',
+    'search',
+    'glob',
+    'ls',
+    'list',
+    'find',
+    'tree',
+    'cat',
+    'view',
+    'head',
+    'tail',
+    'stat',
+    // rpiv-web-tools (Pi) + Claude Code's WebSearch/WebFetch: querying/reading the web is
+    // read-only research up to an edit, not the environment-probing the no-edit bound targets.
+    'web_search',
+    'web_fetch',
+    'websearch',
+    'webfetch',
+]);
+// The web-tool calls, tracked separately so an unbounded run of them (with no other tool
+// call between) can be caught as a search loop — see `maxConsecutiveWebCalls`. Covers both
+// Pi's `web_search`/`web_fetch` and Claude Code's `WebSearch`/`WebFetch`.
+const WEB_TOOLS = new Set(['web_search', 'web_fetch', 'websearch', 'webfetch']);
+/** Read {@link ProgressGuardLimits} from the environment, falling back to the defaults. */
+export function progressGuardLimitsFromEnv(env = process.env) {
+    const num = (raw, fallback) => {
+        const n = Number(raw);
+        return Number.isFinite(n) && n > 0 ? Math.floor(n) : fallback;
+    };
+    return {
+        maxToolCallsWithoutEdit: num(env.JOB_MAX_TOOLCALLS_WITHOUT_EDIT, DEFAULT_PROGRESS_GUARD_LIMITS.maxToolCallsWithoutEdit),
+        maxConsecutiveErrors: num(env.JOB_MAX_CONSECUTIVE_TOOL_ERRORS, DEFAULT_PROGRESS_GUARD_LIMITS.maxConsecutiveErrors),
+        maxConsecutiveWebCalls: num(env.JOB_MAX_CONSECUTIVE_WEB_CALLS, DEFAULT_PROGRESS_GUARD_LIMITS.maxConsecutiveWebCalls),
+    };
+}
+/**
+ * Apply per-knob overrides onto a base set of guard limits, ENFORCING loosen-only: an
+ * override can only RAISE a knob (more headroom), never lower it below the base. A
+ * larger value is more lenient for every knob (more no-edit tool calls / errors / web
+ * calls tolerated), so each result is `max(base, override)`. This is a hard guarantee,
+ * not a convention — a tuning entry (built-in or a custom kind's, which reaches this via
+ * an untrusted job body) that supplies a value TIGHTER than the base is clamped back up
+ * to the base rather than aborting a legitimately-progressing run. An absent/undefined
+ * knob keeps the base value untouched.
+ */
+export function mergeGuardLimits(base, overrides) {
+    if (!overrides)
+        return base;
+    const loosen = (b, o) => typeof o === 'number' ? Math.max(b, o) : b;
+    return {
+        maxToolCallsWithoutEdit: loosen(base.maxToolCallsWithoutEdit, overrides.maxToolCallsWithoutEdit),
+        maxConsecutiveErrors: loosen(base.maxConsecutiveErrors, overrides.maxConsecutiveErrors),
+        // `maxConsecutiveWebCalls` is optional on the interface (callers may omit it), so
+        // fall back to the default before loosening — keeps `loosen`'s base a concrete number.
+        maxConsecutiveWebCalls: loosen(base.maxConsecutiveWebCalls ?? DEFAULT_PROGRESS_GUARD_LIMITS.maxConsecutiveWebCalls, overrides.maxConsecutiveWebCalls),
+    };
+}
+/**
+ * Live anti-rabbithole guard: fed each streamed Pi event, it returns a diagnostic
+ * reason the moment a run has plainly stopped making progress, so the harness can
+ * kill Pi early instead of letting it burn the whole budget (and then surface a
+ * useful failure instead of a generic "no file changes"). Pure and incremental so
+ * it can be unit-tested over a fixed event sequence.
+ */
+export class ProgressGuard {
+    limits;
+    expectsEdits;
+    toolCalls = 0;
+    edits = 0;
+    consecutiveErrors = 0;
+    consecutiveWebCalls = 0;
+    constructor(limits, 
+    /** When false (assess-only runs like the merger), the no-edit bound is skipped. */
+    expectsEdits = true) {
+        this.limits = limits;
+        this.expectsEdits = expectsEdits;
+    }
+    /** Feed one parsed Pi event; returns a diagnostic reason when the run should abort, else null. */
+    observe(event) {
+        const tool = toolCallSignal(event);
+        if (!tool)
+            return null;
+        return this.observeSignal(tool);
+    }
+    /**
+     * Feed one already-parsed tool-call signal (name + error flag), returning a diagnostic reason
+     * when the run should abort, else null. Split out of {@link observe} so a caller whose stream
+     * is NOT Pi's `tool_execution_end` envelope — the claude-code runner, which correlates a
+     * `tool_use` block's name with its `tool_result`'s `is_error` — can drive the SAME guard logic
+     * without synthesising a fake Pi event.
+     */
+    observeSignal(tool) {
+        const name = tool.name.toLowerCase();
+        // The error streak tracks ANY tool call (a planning call still proves the agent
+        // isn't wedged in a failing-op loop), so it's updated before the planning skip.
+        this.consecutiveErrors = tool.isError ? this.consecutiveErrors + 1 : 0;
+        if (this.consecutiveErrors >= this.limits.maxConsecutiveErrors) {
+            return (`no progress: ${this.consecutiveErrors} consecutive failing tool calls — the agent is stuck ` +
+                `retrying a failing operation rather than making progress. Aborting.`);
+        }
+        // Web search/fetch loop: web tools are read-only (they don't count toward the
+        // no-edit bound), so guard them separately — an uninterrupted streak of them is a
+        // research rabbit-hole. Any non-web tool call resets the streak.
+        if (WEB_TOOLS.has(name)) {
+            this.consecutiveWebCalls++;
+            const webCap = this.limits.maxConsecutiveWebCalls ?? DEFAULT_PROGRESS_GUARD_LIMITS.maxConsecutiveWebCalls;
+            if (this.consecutiveWebCalls >= webCap) {
+                return (`no progress: ${this.consecutiveWebCalls} consecutive web search/fetch calls without ` +
+                    `any other action — the agent is stuck researching instead of doing the work. Aborting.`);
+            }
+        }
+        else {
+            this.consecutiveWebCalls = 0;
+        }
+        // Planning, read-only exploration and subagent-dispatch calls don't count toward the
+        // no-edit bound (see PLANNING_TOOLS / EXPLORATION_TOOLS / SUBAGENT_DISPATCH_TOOLS) —
+        // only "action" calls without an edit do.
+        if (PLANNING_TOOLS.has(name) ||
+            EXPLORATION_TOOLS.has(name) ||
+            SUBAGENT_DISPATCH_TOOLS.has(name)) {
+            return null;
+        }
+        this.toolCalls++;
+        if (FILE_EDIT_TOOLS.has(name))
+            this.edits++;
+        if (this.expectsEdits &&
+            this.edits === 0 &&
+            this.toolCalls >= this.limits.maxToolCallsWithoutEdit) {
+            return (`no progress: ${this.toolCalls} tool calls and not one file edit — the agent is exploring or ` +
+                `probing the environment without implementing anything. Aborting before it burns the whole run.`);
+        }
+        return null;
+    }
+}

package/dist/subagents.js

@@ -1,57 +1,8 @@
 import { readdir, stat } from 'node:fs/promises';
 import { createReadStream } from 'node:fs';
 import { basename, join } from 'node:path';
-import { claudeAssistantContent, claudeCallUsage, isObject, redactBody } from './claude-stream.js';
+import { claudeAssistantContent, claudeCallUsage, isObject, redactBody, SUBAGENT_TOOL_NAMES, } from './claude-stream.js';
 import { publishCallMetric } from './pi.js';
-// ADR 0026 D2.1 + D3, corrected by ADR 0027. When the Claude Code CLI reviews a large PR
-// it fans the work out across parallel `Task` subagents. Two things then go dark to the
-// harness, which only reads the PARENT process's stream-json stdout:
-//
-//  - the parent stream falls quiet for the whole (potentially 15+ minute) parallel
-//    review, so the inactivity heartbeat freezes and a healthy run looks wedged (P3);
-//  - every subagent's token spend is written to a SEPARATE `subagents/*.jsonl`
-//    transcript under the CLI's config home and never reaches the parent stream, so
-//    the run's telemetry reports ~0 tokens while hundreds of thousands are spent (P3).
-//
-// This module closes both without disabling the (context-bounding, ADR-0023-wanted)
-// subagent parallelism:
-//
-//  - {@link createSliceTracker} derives the slice plan + per-slice progress from the
-//    PARENT stream alone — the subagent-dispatch tool_use and its terminal tool_result
-//    DO appear there (only the subagent's intermediate turns don't), so slices/progress
-//    need no file watching (D2.1). `pickProgress` (./progress.ts) reconciles it with the
-//    parent's own plan (ADR 0027 Defect B);
-//  - {@link startSubagentWatcher} tails the `subagents/*.jsonl` transcripts for the
-//    heartbeat (any new bytes ⇒ `onActivity`) and sums each subagent turn's usage into
-//    the run's telemetry (D3).
-//
-// The CLI does NOT write those transcripts to `<configHome>/subagents` (the location ADR
-// 0026 assumed, which never exists — ADR 0027 Defect A). It writes them PER SESSION under
-// `<configHome>/projects/<encoded-cwd>/<session-uuid>/subagents/agent-*.jsonl`, and the
-// session-uuid dir isn't known before the CLI mints it — so the watcher is pointed at the
-// `projects` root and DISCOVERS the `subagents/` dir by walking (see
-// {@link findSubagentTranscripts}).
-//
-// Both degrade gracefully: the CLI's subagent transcript layout is not a stable contract,
-// so a missing directory, an unreadable file, or an unparseable line is swallowed and the
-// harness falls back to today's parent-stream-only behaviour.
-// ---------------------------------------------------------------------------
-// Slice / progress tracking off the PARENT stream (D2.1)
-// ---------------------------------------------------------------------------
-/**
- * The tool names the Claude Code CLI dispatches a parallel subagent under. `Agent` is what the
- * shipped schema declares (`AgentInput` in `sdk-tools.d.ts`, carrying `description` / `prompt` /
- * `subagent_type`); `Task` is the older name for the same dispatch. Both are matched because the
- * harness runs against whatever CLI the image happens to bundle, and matching only the old name
- * is what left a CLI 2.1.x pr-review reporting no slices at all.
- *
- * Note the asymmetry: keeping the legacy `Task` here is the one place a CLI rename could produce a
- * FALSE signal rather than merely no signal — if a future build were to name a plain task-list
- * tool `Task`, its writes would be counted as in-flight slices. We accept that because no shipped
- * build does (the incremental plan tool is `TaskCreate`/`TaskUpdate`, tracked separately in
- * `progress.ts`), and dropping legacy coverage is the more likely regression.
- */
-const SUBAGENT_TOOL_NAMES = new Set(['Agent', 'Task']);
 export function createSliceTracker() {
     // Insertion-ordered so the progress `items` render in dispatch order.
     const slices = new Map();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/executor-harness",
-  "version": "1.62.0",
+  "version": "1.64.0",
   "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,9 +26,9 @@
     "hono": "^4.12.32",
     "typescript": "7.0.2",
     "vitest": "^4.1.10",
-    "@cat-factory/kernel": "0.168.0",
-    "@cat-factory/spend": "0.12.97",
-    "@cat-factory/server": "0.158.0"
+    "@cat-factory/kernel": "0.170.0",
+    "@cat-factory/server": "0.160.0",
+    "@cat-factory/spend": "0.12.99"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",

package/src/agent-runner.ts

@@ -19,6 +19,7 @@ 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'
@@ -101,6 +102,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 +166,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 +190,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 +204,7 @@ function streamCli(
         return
       }
       try {
-        onEvent(event)
+        onEvent(event, { final })
       } catch {
         // A faulty observer must never break the run.
       }
@@ -226,10 +243,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) {
@@ -382,7 +402,42 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
     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 +446,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 +483,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 +552,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 +579,7 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
         ],
       },
       prompt,
-      opts,
+      { ...opts, signal: runSignal },
       env,
       opts.subscriptionToken ? secretsToRedact(opts.subscriptionToken) : [],
       onEvent,
@@ -524,6 +594,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 })