@cat-factory/executor-harness 1.60.0 → 1.64.0

package/README.md

@@ -73,7 +73,16 @@ The implementation job (`POST /run`) is the canonical sequence:
 6. **commit, push** a branch and **open a PR**, returning `{ prUrl, branch, summary }` — but
    ONLY if step 4 ended green. A spent budget returns an error result with the validation report
    and opens no PR. Absent `validationChecks` / `reproduction`, steps 4 and 5 do not happen at
-   all.
+   all. The PR's description prefers the agent-authored reviewer briefing over the generic
+   dispatch-time text the job body carries: a PR-opening agent is prompted to write one to the
+   `.cat-pr-description.md` sentinel at the checkout root (one per sibling repo in a multi-repo
+   run; an optional leading `# <title>` line, when it is the file's only `#` heading, sets the PR
+   title), and `src/pr-description.ts` lifts it — secret-scrubbed, size-capped with a visible
+   note, made inert for the host by `src/host-markdown.ts`, kept out of the commit like the
+   effort/follow-ups sentinels — onto `openPullRequest`. Absent or unusable ⇒ the fallback text,
+   unchanged. On a RESUMED run the PR already exists, so an agent briefing additionally refreshes
+   its title/description in place (carrying the engine's managed report region across); the
+   generic fallback never does, so a human's edit is safe.
 
 Bootstrap differs at the ends — it may start from an empty dir, and **resets
 history to one commit and force-pushes** the default branch instead of opening a

package/dist/agent-runner.js

@@ -4,6 +4,7 @@ import { tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { claudeAssistantContent, claudeCallUsage, isObject, numberOf, redactBody, } from './claude-stream.js';
 import { createCallMetricPublisher, publishCallMetric, } from './pi.js';
+import { ProgressGuard } from './progress-guard.js';
 import { killChildProcess, spawnDetached } from './process.js';
 import { redact, secretsToRedact } from './redact.js';
 import { createSliceTracker, startSubagentWatcher } from './subagents.js';
@@ -58,7 +59,12 @@ function streamCli(cli, prompt, opts, env, secrets, onEvent) {
         let aborted = false;
         let lineBuffer = '';
         const killChild = () => killChildProcess(child);
-        const processLine = (line) => {
+        // `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, final = false) => {
             if (!line.startsWith('{'))
                 return;
             let event;
@@ -69,7 +75,7 @@ function streamCli(cli, prompt, opts, env, secrets, onEvent) {
                 return;
             }
             try {
-                onEvent(event);
+                onEvent(event, { final });
             }
             catch {
                 // A faulty observer must never break the run.
@@ -106,11 +112,14 @@ function streamCli(cli, prompt, opts, env, secrets, onEvent) {
         });
         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) {
@@ -246,7 +255,44 @@ export async function runClaudeCode(opts) {
         if (progress)
             opts.onProgress(progress);
     };
-    const onEvent = (event) => {
+    // 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();
+    const guardAbort = new AbortController();
+    let guardReason;
+    // 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) => {
+        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, meta) => {
         const type = event.type;
         if (type === 'assistant' && isObject(event.message)) {
             const message = event.message;
@@ -255,7 +301,14 @@ export async function runClaudeCode(opts) {
             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?.todos);
                     if (progress)
                         lastTodo = progress;
@@ -288,6 +341,10 @@ export async function runClaudeCode(opts) {
                 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 });
             }
         }
@@ -350,6 +407,11 @@ export async function runClaudeCode(opts) {
             ...(opts.log ? { log: opts.log } : {}),
         })
         : 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({
             command: 'claude',
@@ -368,7 +430,7 @@ export async function runClaudeCode(opts) {
                 opts.model,
                 ...appendArgs,
             ],
-        }, prompt, opts, env, opts.subscriptionToken ? secretsToRedact(opts.subscriptionToken) : [], onEvent);
+        }, prompt, { ...opts, signal: runSignal }, env, opts.subscriptionToken ? secretsToRedact(opts.subscriptionToken) : [], onEvent);
         return await assembleClaudeOutcome({
             summary,
             stats,
@@ -379,6 +441,17 @@ export async function runClaudeCode(opts) {
             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?.stderrTail;
+            throw new Error(tail ? `${guardReason} Agent stderr: ${tail}` : guardReason);
+        }
+        throw err;
+    }
     finally {
         await subagents?.stop();
         if (configHome) {

package/dist/agent.js

@@ -6,7 +6,9 @@ import { promisify } from 'node:util';
 import { standUpFrontend, tearDownFrontend } from './frontend-infra.js';
 import { configurePackageRegistries } from './package-registries.js';
 import { captureRedactedOutput, redactSecrets, registerKnownSecrets } from './redact.js';
-import { cloneRepo, commitAll, conflictDiff, fetchPullRequestHead, fetchReferenceBranches, hasAgentChanges, headCommit, inferVcsProvider, mergeBranch, openPullRequest, prepareExistingCheckout, pushBranch, reinitAndPush, unmergedPaths, } from './git.js';
+import { cloneRepo, commitAll, conflictDiff, fetchPullRequestHead, fetchReferenceBranches, hasAgentChanges, headCommit, mergeBranch, prepareExistingCheckout, pushBranch, reinitAndPush, unmergedPaths, } from './git.js';
+import { inferVcsProvider, openPullRequest } from './vcs-api.js';
+import { applyPrDescription } from './pr-description.js';
 import { makeDirClaimer, noChangesReason, runCodingAgent, runMultiRepoCoding, } from './coding-agent.js';
 import { validationFailureMessage } from './validation-checks.js';
 import { acquireRepoCheckout, agentNeverActed, agentOutputTail, NEVER_ACTED_CAUSE, runAgentInWorkspace, unusableFinalAnswerCause, withWorkspace, } from './pi-workspace.js';
@@ -822,7 +824,7 @@ function buildSingleRepoCodingSpec(job, pushBranch) {
  */
 async function runSingleRepoCoding(job, opts) {
     const pushBranch = job.pushBranch ?? job.newBranch ?? job.branch;
-    const { summary, stats, stderrTail, pushed, usage, callMetrics, validation, validationReport, reproductionReport, effortReport, } = await runCodingAgent(buildSingleRepoCodingSpec(job, pushBranch), opts);
+    const { summary, stats, stderrTail, pushed, usage, callMetrics, validation, validationReport, reproductionReport, effortReport, prDescription, } = await runCodingAgent(buildSingleRepoCodingSpec(job, pushBranch), opts);
     // Ralph loop: the harness-computed validation verdict, forwarded onto the coding result as
     // `ralphVerdict` so the backend's `toRunResult` lifts it onto `AgentRunResult.ralphVerdict`.
     const ralphVerdict = validation ? { ralphVerdict: validation } : {};
@@ -894,7 +896,11 @@ async function runSingleRepoCoding(job, opts) {
             ghToken: job.ghToken,
             head: pushBranch,
             base: job.repo.baseBranch,
-            pr: job.pr,
+            // The agent-authored briefing (title/body) wins field-wise over the dispatch-time text.
+            pr: applyPrDescription(job.pr, prDescription),
+            // A resumed run's PR is already open, so refresh it rather than lose the briefing to the
+            // duplicate-PR 422 — only from a REAL briefing (see `refreshExisting` for why).
+            ...(prDescription ? { refreshExisting: true } : {}),
             apiBase: job.githubApiBase,
             // The provider (set by the server from the configured backend) selects GitHub-PR vs
             // GitLab-MR authoritatively; the clone URL supplies the GitLab REST base + project path.

package/dist/claude-stream.js

@@ -7,6 +7,24 @@ import { redact } from './redact.js';
 export function isObject(value) {
     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) {
     return typeof value === 'number' && Number.isFinite(value) ? value : 0;
 }

package/dist/coding-agent.js

@@ -3,9 +3,11 @@ import { join } from 'node:path';
 import { spawn } from 'node:child_process';
 import { killChildProcess, spawnDetached } from './process.js';
 import { MAX_CAPTURED_OUTPUT_CHARS, redactSecrets } from './redact.js';
-import { branchAheadOfBase, changedFilesSinceBase, branchHasCommitsSince, cloneExistingBranch, cloneRepo, commitTrackedEdits, createBranch, excludeFromGit, fetchReferenceBranches, headCommit, listUntrackedFiles, openPullRequest, prepareExistingCheckout, pushBranch, refreshFromBaseIfClean, remoteBranchExists, } from './git.js';
+import { branchAheadOfBase, changedFilesSinceBase, branchHasCommitsSince, cloneExistingBranch, cloneRepo, commitTrackedEdits, createBranch, excludeFromGit, fetchReferenceBranches, headCommit, listUntrackedFiles, prepareExistingCheckout, pushBranch, refreshFromBaseIfClean, remoteBranchExists, } from './git.js';
+import { openPullRequest } from './vcs-api.js';
 import { FOLLOW_UPS_FILENAME, FollowUpTailer } from './follow-ups.js';
 import { EFFORT_REPORT_FILE } from './effort.js';
+import { applyPrDescription, PR_DESCRIPTION_FILE, readPrDescription, } from './pr-description.js';
 import { acquireRepoCheckout, agentNeverActed, agentOutputTail, runAgentInWorkspace, withWorkspace, } from './pi-workspace.js';
 import { log } from './logger.js';
 import { runValidationLoop, } from './validation-checks.js';
@@ -115,6 +117,9 @@ export async function runCodingAgent(spec, opts = {}) {
         // but that cannot un-stage a mid-run commit; the per-clone exclude is what prevents it. A bare
         // filename pattern matches the file in any subdirectory, so it covers a monorepo `workDir` too.
         await excludeFromGit(dir, EFFORT_REPORT_FILE, signal);
+        // Same treatment for the agent-authored PR-description sentinel: excluded locally so the
+        // agent's own `git add` can never stage the briefing into the PR it describes.
+        await excludeFromGit(dir, PR_DESCRIPTION_FILE, signal);
         // Follow-up companion: tail the Coder's sentinel file and stream new items out on the
         // job view. Locally exclude it from git first so the agent's own `git add` can never
         // stage it and it never surfaces as an untracked leftover or in the PR. The sentinel
@@ -376,6 +381,12 @@ async function finalizeCodingRun(args) {
     // Safety net for forgotten edits: commit changes to TRACKED files only (never
     // untracked scratch files/artifacts — the agent owns committing new files).
     await commitTrackedEdits(dir, spec.commitMessage, signal);
+    // The agent-authored PR description, read AFTER the validation loop (a repair round may have
+    // changed what the briefing should say) and removed so it never lingers in the checkout. The
+    // prompt asks for it at the top level of the checkout; a monorepo agent working in a service
+    // subdirectory may drop it in its cwd instead, so probe the checkout root first, then the cwd.
+    const prDescription = (await readPrDescription(dir)) ??
+        (workDir !== dir ? await readPrDescription(workDir) : undefined);
     // Stop periodic checkpoints and let any in-flight one settle BEFORE the final
     // push, so the two never run a concurrent `git push` to the same branch (the
     // final push below is then a fresh attempt whose failure is the real signal).
@@ -438,6 +449,7 @@ async function finalizeCodingRun(args) {
             ...(usage ? { usage } : {}),
             ...(callMetrics ? { callMetrics } : {}),
             ...(effortReport ? { effortReport } : {}),
+            ...(prDescription ? { prDescription } : {}),
         };
     }
     // Ralph loop: run the programmatic completion command against the pushed/committed
@@ -698,7 +710,7 @@ export async function runMultiRepoCoding(job, opts = {}) {
             multiRepo: true,
         }, opts);
         // Commit forgotten tracked edits, then push + open a PR for each repo the run actually changed.
-        const { primaryPushed, primaryPrUrl, peerPullRequests } = await pushMultiRepoLegs(legs, job, logger, opts);
+        const { primaryPushed, primaryPrUrl, peerPullRequests } = await pushMultiRepoLegs(legs, job, logger, opts, root);
         const anyWork = primaryPushed || peerPullRequests.length > 0;
         if (!anyWork) {
             // Nothing changed in ANY repo. For the implementer this is a failure (as in the
@@ -799,6 +811,9 @@ async function prepareMultiRepoCheckouts(root, legs, job, logger, opts) {
             await createBranch(dir, leg.workBranch, signal);
         }
         leg.dir = dir;
+        // Exclude the agent-authored PR-description sentinel locally (as the single-repo path does)
+        // so the agent's own `git add` can never stage the briefing into the PR it describes.
+        await excludeFromGit(dir, PR_DESCRIPTION_FILE, signal);
         // The branch tip before the agent runs. Captured BEFORE the resume base refresh below so
         // that refresh's merge commit counts as advancement and is pushed (as in the single-repo
         // path). A fresh leg produced work iff its branch advances past this; a resumed leg already
@@ -844,7 +859,9 @@ async function prepareMultiRepoCheckouts(root, legs, job, logger, opts) {
  * no PR; a read-only reference leg is never committed or pushed). Extracted so the multi-repo body
  * stays small; returns the primary's push/PR state plus the peer PRs.
  */
-async function pushMultiRepoLegs(legs, job, logger, opts) {
+async function pushMultiRepoLegs(legs, job, logger, opts, 
+/** The workspace root the agent ran in — the fallback probe for the primary's briefing. */
+root) {
     const { signal } = opts;
     opts.onPhase?.('push');
     let primaryPushed = false;
@@ -855,6 +872,14 @@ async function pushMultiRepoLegs(legs, job, logger, opts) {
         // guarantee (the spec carries no branch/PR, and the clone phase gave it no work branch).
         if (leg.readOnly)
             continue;
+        // Lift (and remove) the agent-authored PR description for THIS repo's PR before anything
+        // else touches the checkout — each sibling checkout carries its own briefing for its own PR.
+        // The agent's cwd here is the WORKSPACE ROOT rather than any one checkout, so an agent that
+        // read the prompt loosely may well have written a single briefing there instead. Fall back
+        // to it for the PRIMARY leg only: at the root there is nothing to say which repo it
+        // describes, and the primary is the one the run is actually about.
+        const agentPrDescription = (await readPrDescription(leg.dir)) ??
+            (leg.primary ? await readPrDescription(root) : undefined);
         await commitTrackedEdits(leg.dir, job.commitMessage ?? leg.pr?.title ?? 'Agent changes', signal);
         const advanced = await branchHasCommitsSince(leg.dir, leg.baseSha, signal);
         let hasWork = advanced || leg.resumed;
@@ -884,7 +909,10 @@ async function pushMultiRepoLegs(legs, job, logger, opts) {
                 ghToken: leg.ghToken,
                 head: leg.workBranch,
                 base: leg.repo.baseBranch,
-                pr: leg.pr,
+                pr: applyPrDescription(leg.pr, agentPrDescription),
+                // See the single-repo call site: refresh a resumed leg's already-open PR, but only
+                // when the text is the agent's own briefing rather than the dispatch-time fallback.
+                ...(agentPrDescription ? { refreshExisting: true } : {}),
                 apiBase: job.githubApiBase,
                 cloneUrl: leg.repo.cloneUrl,
                 ...(leg.repo.provider ? { provider: leg.repo.provider } : {}),

package/dist/embed.js

@@ -4,5 +4,6 @@
 // repo, write the agent context, point Pi at an OpenAI-compatible endpoint, run
 // it, and inspect what changed. The HTTP server / job lifecycle stays internal;
 // only the reusable primitives are exposed here.
-export { PI_MAX_OUTPUT_TOKENS, DEFAULT_PROGRESS_GUARD_LIMITS, writePiModelsConfig, writeAgentsContext, runPi, summarizePiRun, parsePiOutput, parseTodoProgress, progressGuardLimitsFromEnv, terminalRunError, } from './pi.js';
+export { PI_MAX_OUTPUT_TOKENS, writePiModelsConfig, writeAgentsContext, runPi, summarizePiRun, parsePiOutput, parseTodoProgress, terminalRunError, } from './pi.js';
+export { DEFAULT_PROGRESS_GUARD_LIMITS, progressGuardLimitsFromEnv, } from './progress-guard.js';
 export { cloneRepo, createBranch, changedPathsFromPorcelain, hasAgentChanges, redactSecrets, } from './git.js';