@cat-factory/executor-harness 1.60.0 → 1.64.0

package/dist/pi.js

@@ -7,6 +7,7 @@ import { pathExists } from './fs-utils.js';
 import { redactSecrets } from './redact.js';
 import { HarnessFailure } from './failure.js';
 import { log } from './logger.js';
+import { ProgressGuard, progressGuardLimitsFromEnv, toolCallSignal, } from './progress-guard.js';
 // Drives the Pi coding-agent CLI. Pi is pointed at the Worker's OpenAI-compatible
 // proxy via a custom provider in ~/.pi/agent/models.json, authenticated with the
 // per-job session token (interpolated from $PI_PROXY_TOKEN) — so no provider key
@@ -93,21 +94,12 @@ modules). Do NOT read every module file. Only open \`blueprints/modules/<name>.m
 for a module that is directly relevant to your task, when you need its summary and
 exact code references. \`blueprints/version.json\` is a tiny manifest for quick
 staleness checks. Treat the blueprint as orientation, not a task list.`;
-// Appended to every AGENTS.md so an agent treats the persisted spec as the
-// PRESCRIPTIVE source (what must be true) and the acceptance scenarios its work must
-// satisfy. Harmless when no spec exists yet — the files simply aren't there.
-const SPEC_GUIDANCE = `
-
-## Service specification (the prescriptive spec)
-
-If a \`spec/\` folder exists, it is the specification for this service. It is sharded
-by a module (domain) → feature (group) taxonomy. **Read \`spec/overview.md\` first** —
-it states what MUST be true and indexes the modules and their features (with links).
-Open \`spec/modules/<module>/<feature>.md\` (or its \`.json\` for exact detail) for the
-feature you are working on — it carries that feature's requirements AND the domain
-rules scoped to it. \`spec/features/<module>/<feature>.feature\` are the Gherkin
-acceptance scenarios your work must satisfy — treat them as the source of truth for
-behaviour and tests. Read only the modules/features relevant to your task.`;
+// NOTE: the spec-reading guidance is NOT appended here. It is contributed once, backend-side, by
+// the `spec-aware` trait (`SPEC_AWARE_GUIDANCE` in @cat-factory/agents), which lands in the
+// composed system prompt for every spec-aware kind on BOTH harness paths. This harness used to
+// append a near-duplicate block, so a spec-aware Pi run carried the guidance twice; the claude-code
+// path never appended it. Sourcing it solely from the trait dedupes the Pi prompt and makes the two
+// paths consistent. (A non-spec-aware kind is deliberately not told to read the spec.)
 /**
  * Write the composed system prompt as Pi's GLOBAL agent context
  * (`~/.pi/agent/AGENTS.md`), which Pi reads automatically and concatenates with
@@ -143,7 +135,12 @@ export async function writeAgentsContext(systemPrompt, opts = {}) {
     // Point the agent at any linked context the backend materialised into the checkout
     // (requirements / RFCs / PRDs / tracker issues) so it reads them on demand.
     const context = contextGuidance(opts.contextFiles ?? []);
-    await writeFile(join(dir, 'AGENTS.md'), `${systemPrompt}${BLUEPRINT_GUIDANCE}${SPEC_GUIDANCE}${TODO_GUIDANCE}${monorepo}${multiRepo}${webTools}${context}`, 'utf8');
+    // Only orient the agent to `blueprints/` when the checkout actually has them — otherwise the
+    // note is dead weight re-sent on every turn. The spec-reading guidance is NOT appended here
+    // (see the note above `writeAgentsContext`): it comes solely from the backend `spec-aware`
+    // trait, so a spec-aware run no longer carries it twice.
+    const blueprint = opts.hasBlueprints ? BLUEPRINT_GUIDANCE : '';
+    await writeFile(join(dir, 'AGENTS.md'), `${systemPrompt}${blueprint}${TODO_GUIDANCE}${monorepo}${multiRepo}${webTools}${context}`, 'utf8');
 }
 /** The MULTI-REPO mechanics note appended to AGENTS.md when a run spans sibling checkouts. */
 const MULTI_REPO_GUIDANCE = `
@@ -497,174 +494,8 @@ export function parseTodoProgress(event) {
     }
     return undefined;
 }
-/** Tool-call signal read off a streamed Pi event, or undefined if not a tool call. */
-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',
-]);
-// 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.
-const PLANNING_TOOLS = new Set(['todo']);
-// 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: querying/reading the web is read-only research up to an edit,
-    // not the environment-probing the no-edit bound targets, so it doesn't count.
-    'web_search',
-    'web_fetch',
-]);
-// The rpiv-web-tools calls, tracked separately so an unbounded run of them (with no
-// other tool call between) can be caught as a search loop — see `maxConsecutiveWebCalls`.
-const WEB_TOOLS = new Set(['web_search', 'web_fetch']);
-/** 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;
-        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 and read-only exploration calls don't count toward the no-edit bound
-        // (see PLANNING_TOOLS / EXPLORATION_TOOLS) — only "action" calls without an edit do.
-        if (PLANNING_TOOLS.has(name) || EXPLORATION_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;
-    }
-}
+// The no-progress guard (its limits, tool vocabulary and the `ProgressGuard` itself) lives in
+// `progress-guard.ts` — it is shared with the claude-code runner, so it is no longer Pi's.
 /**
  * Run Pi non-interactively against `cwd` and return its assistant summary. Uses
  * print + JSON mode (`-p --mode json`) with `--approve` so it runs unattended.

package/dist/pr-description.js

@@ -0,0 +1,157 @@
+import { readFile, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { inertInline, inertMarkdown, walkFences } from './host-markdown.js';
+import { redactSecrets } from './redact.js';
+// ---------------------------------------------------------------------------
+// The agent-authored pull-request description side channel. A coding agent whose
+// dispatch opens a PR is asked (via the backend-composed system prompt) to end its
+// run by writing a reviewer briefing — the problem, the decisions made, what to
+// look out for — to a sentinel file at the root of the checkout the PR belongs to.
+// The harness reads it after the agent settles, removes it (so it never lands in a
+// commit), and uses it as the PR body in place of the generic dispatch-time text
+// the job body carries. Absent or unusable ⇒ the dispatch-time fallback, unchanged.
+//
+// The briefing is MODEL-AUTHORED text landing verbatim on a host-parsed surface, so
+// it crosses `host-markdown.ts` (auto-link triggers defused, open code fences closed)
+// on the way out — see that module for why a PR body is not an inert string sink.
+//
+// The filename is kept in sync with `PR_DESCRIPTION_FILE` in `@cat-factory/agents`
+// (the executor-harness has no dependency on that package), exactly like the
+// effort-report and follow-ups sentinels.
+// ---------------------------------------------------------------------------
+/** The sentinel file the agent writes its PR description to (relative to the checkout root). */
+export const PR_DESCRIPTION_FILE = '.cat-pr-description.md';
+/**
+ * Ceiling on the agent-authored body.
+ *
+ * The engine appends its verification report to the SAME body later, and that section carries
+ * its own 50,000-character ceiling (`MAX_SECTION_CHARS` in kernel's `hostMarkdown`). GitHub
+ * rejects a body over 65,536 with a 422, and the report publisher swallows its own failures —
+ * so a briefing budget that does not leave the report room would surface as a report that
+ * silently never publishes. 15,000 + 50,000 stays under the limit with room to join them.
+ */
+const MAX_PR_BODY_CHARS = 15_000;
+/** Ceiling on an agent-supplied title (GitHub truncates around 256; a title should be short). */
+const MAX_PR_TITLE_CHARS = 160;
+/** Opens the engine-managed region of a PR body (kept in sync with `kernel/domain/pr-report.ts`). */
+export const PR_REPORT_MARKER_START = '<!-- cat-factory:verification-report:start -->';
+/** Closes the engine-managed region of a PR body. */
+export const PR_REPORT_MARKER_END = '<!-- cat-factory:verification-report:end -->';
+/**
+ * A marker inside the agent-authored briefing would make the engine's splice treat part of the
+ * briefing as its own managed region and rewrite it, so any occurrence is stripped up front.
+ * Deliberately laxer than the exact constants above (whitespace-tolerant), so a near-miss the
+ * splice itself would not match cannot survive here either.
+ */
+const MANAGED_SECTION_MARKER = /<!--\s*cat-factory:verification-report:(?:start|end)\s*-->/g;
+/**
+ * Read + parse + REMOVE the agent's PR-description sentinel from `dir`. Lenient: returns
+ * undefined when the file is absent (the agent wrote none) or carries nothing usable. Never
+ * throws — a bad description must never fail an otherwise-good run; the caller falls back to
+ * the dispatch-time text.
+ *
+ * A SINGLE `# <title>` heading on the first line sets the PR title; everything after it is the
+ * body (see {@link splitTitle} for why a LONE heading is required). The whole text is
+ * secret-scrubbed, an over-budget body is truncated WITH a visible note (a silent cut would
+ * read as the complete briefing), and both halves are made inert for the host.
+ *
+ * On scrubbing: `redactSecrets`'s credential-assignment rule is deliberately eager, so a
+ * briefing sentence like "the token: handling changed" loses its next word. That is the right
+ * trade for a surface this public — the rule is shared with every other redaction path, and
+ * narrowing it so prose reads better would weaken all of them.
+ */
+export async function readPrDescription(dir) {
+    const path = join(dir, PR_DESCRIPTION_FILE);
+    let raw;
+    try {
+        raw = await readFile(path, 'utf8');
+    }
+    catch {
+        return undefined; // no description written — the fallback body applies
+    }
+    // Remove it so it never lands in a commit (defence in depth; the checkout also excludes it).
+    await rm(path, { force: true }).catch(() => { });
+    const text = redactSecrets(raw).replace(MANAGED_SECTION_MARKER, '').trim();
+    if (!text)
+        return undefined;
+    const split = splitTitle(text);
+    // Cap BEFORE the escapes on both halves, so a numeric entity can never be sliced in half.
+    const title = split.title ? inertInline(capTitle(split.title)) : undefined;
+    const body = split.body ? inertMarkdown(capBody(split.body)) : undefined;
+    if (!title && !body)
+        return undefined;
+    return { ...(title ? { title } : {}), ...(body ? { body } : {}) };
+}
+/**
+ * Split a leading `# <title>` heading off the briefing.
+ *
+ * The heading becomes the title ONLY when it is the single level-1 heading in the whole file,
+ * which is exactly what the prompt asks for ("a single `# <title>` heading line"). An agent
+ * that instead uses `#` for its section headings — `# Problem`, `# Decisions`, entirely
+ * idiomatic for the briefing the prompt describes — would otherwise have its first section
+ * silently become the pull request's title, replacing `<block> (<pipeline>)` with the word
+ * "Problem". Headings inside fenced code are not headings and are skipped, or a briefing
+ * quoting a shell snippet (`# rebuild the image`) would lose its title to the snippet.
+ */
+function splitTitle(text) {
+    const lines = text.split('\n');
+    const headings = [];
+    let index = 0;
+    walkFences(lines, (line, insideFence) => {
+        if (!insideFence && /^#\s+\S/.test(line))
+            headings.push(index);
+        index += 1;
+    });
+    if (headings.length !== 1 || headings[0] !== 0)
+        return { body: text };
+    const title = lines[0].replace(/^#\s+/, '').trim();
+    if (!title)
+        return { body: text };
+    return { title, body: lines.slice(1).join('\n').trim() };
+}
+/** Cut an over-long title at a word boundary when one is near, marking the cut. */
+function capTitle(value) {
+    const collapsed = value.trim();
+    if (collapsed.length <= MAX_PR_TITLE_CHARS)
+        return collapsed;
+    const head = collapsed.slice(0, MAX_PR_TITLE_CHARS - 1);
+    const space = head.lastIndexOf(' ');
+    const kept = space > MAX_PR_TITLE_CHARS * 0.6 ? head.slice(0, space) : head;
+    return `${kept.trimEnd()}…`;
+}
+/** Cut an over-budget body, marking the cut so it is never read as the whole briefing. */
+function capBody(value) {
+    if (value.length <= MAX_PR_BODY_CHARS)
+        return value;
+    return (value.slice(0, MAX_PR_BODY_CHARS).trimEnd() +
+        '\n\n_Truncated by the platform: the description exceeded the size budget._');
+}
+/**
+ * Fold an agent-authored description over the dispatch-time fallback the job body carries.
+ * Field-wise: the agent's title/body each win when present, so a body-only briefing keeps the
+ * backend-composed title and vice versa.
+ */
+export function applyPrDescription(fallback, agent) {
+    if (!agent)
+        return fallback;
+    return { title: agent.title ?? fallback.title, body: agent.body ?? fallback.body };
+}
+/**
+ * The body to PATCH onto an ALREADY-OPEN pull request when a resumed run produced a fresh
+ * briefing: the new description followed by whatever the engine's managed verification-report
+ * region currently holds.
+ *
+ * Carrying the region across is what makes the refresh safe. The engine re-publishes the report
+ * on every step settlement, so dropping it here would usually self-heal — but "usually" is not
+ * a property to rest the one artefact a reviewer reads on, and a run that settles no further
+ * step (the work is already merged, the run failed after its push) would never restore it.
+ */
+export function preserveManagedSection(currentBody, nextBody) {
+    const existing = currentBody ?? '';
+    const start = existing.indexOf(PR_REPORT_MARKER_START);
+    const end = existing.indexOf(PR_REPORT_MARKER_END);
+    if (start === -1 || end <= start)
+        return nextBody;
+    const region = existing.slice(start, end + PR_REPORT_MARKER_END.length);
+    return `${nextBody.trim()}\n\n${region}\n`;
+}

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();