@cat-factory/executor-harness 1.62.0 → 1.64.2

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/progress.js

@@ -1,7 +1,8 @@
 import { isObject } from './claude-stream.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 parent agent's own PLAN, as progress counts. This is one of the two views a pr-reviewer
+// run produces of the same slicing (the other is the parallel-subagent dispatch view in
+// `subagents.ts`). The plan is the INVENTORY, the dispatches are the live STATUS, and
+// {@link mergeProgress} folds them into the one list the board renders.
 //
 // 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:
@@ -190,17 +191,14 @@ export function createTaskPlanTracker() {
     };
 }
 /**
- * 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
+ * Reconcile the parent's TWO plan vocabularies (`TodoWrite` snapshots vs the incremental
+ * `TaskCreate`/`TaskUpdate` pair) into one plan. A run uses one or the other, so this is a
+ * genuine either/or: prefer whichever is further along — more `completed`, then more
+ * `inProgress`, then more `total` — else the `TodoWrite` view. Pure + total; returns whichever
  * single input is present when only one is.
+ *
+ * This is NOT how the plan reconciles with the parallel-subagent view — those describe the same
+ * slices from two angles and are MERGED, see {@link mergeProgress}.
  */
 export function pickProgress(todo, slice) {
     if (!todo)
@@ -215,3 +213,114 @@ export function pickProgress(todo, slice) {
         return slice.total > todo.total ? slice : todo;
     return todo;
 }
+/** Status ordering, so a merge can only ever ADVANCE an entry, never walk it back. */
+const STATUS_RANK = {
+    pending: 0,
+    in_progress: 1,
+    completed: 2,
+};
+/**
+ * Words that carry no identity in a slice label, so `Review identity/auth slice` (the subagent
+ * description) and `identity/auth` (the plan entry's subject) compare equal.
+ */
+const LABEL_FILLER = new Set([
+    'a',
+    'agent',
+    'an',
+    'and',
+    'chunk',
+    'chunks',
+    'for',
+    'of',
+    'pass',
+    'review',
+    'reviewing',
+    'slice',
+    'slices',
+    'subagent',
+    'the',
+]);
+/**
+ * A slice label reduced to its identifying words, for pairing a plan entry with the subagent
+ * dispatched to review it. Case, punctuation and the boilerplate around the slice name all
+ * differ between the two vocabularies; the slice NAME does not.
+ */
+export function sliceLabelKey(label) {
+    return label
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, ' ')
+        .split(' ')
+        .filter((w) => w.length > 0 && !LABEL_FILLER.has(w))
+        .join(' ');
+}
+/** Advance an entry to the stronger of its current status and the dispatch's. */
+function advance(entry, status) {
+    if (STATUS_RANK[status] > STATUS_RANK[entry.status])
+        entry.status = status;
+    entry.paired = true;
+}
+/**
+ * MERGE the parent's plan with the `SliceTracker`'s subagent-dispatch view into the single list
+ * the board renders (ADR 0027 Defect B, corrected).
+ *
+ * The two are not competing answers, they are two halves of one: the plan is the INVENTORY (it
+ * names every slice, including the ones not dispatched yet, which is the only place a `pending`
+ * slice exists at all), and the dispatch view is the live STATUS (the plan advances only when
+ * the agent remembers to update it, which it does unreliably). Picking whichever looked "further
+ * along" — the previous behaviour — made the rendered list SHRINK the moment the first subagent
+ * returned: the dispatch view won on `completed`, and it only knows the slices dispatched so far,
+ * so every queued slice vanished from the window and reappeared one at a time as it was dispatched.
+ *
+ * Pairing is by normalised label ({@link sliceLabelKey}) — exact first, then containment — and
+ * finally positionally into the leftover pending entries, in dispatch order (the agent dispatches
+ * in plan order). A dispatch that pairs with nothing is APPENDED rather than dropped, so the list
+ * is at worst a union and can never lose a slice. Statuses only ever advance, so a plan entry the
+ * agent already marked done is not walked back by a re-dispatch.
+ *
+ * Pure + total. Falls back to {@link pickProgress} when either side carries counts but no items
+ * (nothing to merge onto).
+ */
+export function mergeProgress(plan, slice) {
+    if (!plan)
+        return slice;
+    if (!slice)
+        return plan;
+    const planItems = plan.items ?? [];
+    const sliceItems = slice.items ?? [];
+    if (planItems.length === 0 || sliceItems.length === 0)
+        return pickProgress(plan, slice);
+    const entries = planItems.map((i) => ({
+        label: i.label,
+        status: normalizeStatus(i.status),
+        key: sliceLabelKey(i.label),
+        paired: false,
+    }));
+    const take = (match) => entries.find((e) => !e.paired && match(e));
+    // Pass 1 — the same slice named the same way.
+    // Pass 2 — one label contains the other (a dispatch description often expands the plan's short
+    //          name). Length-guarded so a one-word residue can't match everything.
+    // Pass 3 — no words in common at all (renamed between planning and dispatch): absorb into the
+    //          still-untouched pending entries in dispatch order.
+    // Anything still unpaired is a slice the plan never mentioned, so it JOINS the list.
+    const matchers = [
+        (key) => (e) => key.length > 0 && e.key === key,
+        (key) => (e) => key.length >= 3 && e.key.length >= 3 && (e.key.includes(key) || key.includes(e.key)),
+        () => (e) => e.status === 'pending',
+    ];
+    let unpaired = sliceItems;
+    for (const matcher of matchers) {
+        const rest = [];
+        for (const item of unpaired) {
+            const hit = take(matcher(sliceLabelKey(item.label)));
+            if (hit)
+                advance(hit, normalizeStatus(item.status));
+            else
+                rest.push(item);
+        }
+        unpaired = rest;
+    }
+    return toProgress([
+        ...entries.map((e) => ({ label: e.label, status: e.status })),
+        ...unpaired.map((i) => ({ label: i.label, status: normalizeStatus(i.status) })),
+    ]);
+}

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.2",
   "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.171.0",
+    "@cat-factory/server": "0.162.0",
+    "@cat-factory/spend": "0.12.100"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",