@cat-factory/executor-harness 1.31.0

package/dist/coding-agent.js

@@ -0,0 +1,285 @@
+import { mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { branchHasCommitsSince, cloneExistingBranch, cloneRepo, commitTrackedEdits, createBranch, excludeFromGit, headCommit, listUntrackedFiles, prepareExistingCheckout, pushBranch, refreshFromBaseIfClean, remoteBranchExists, } from './git.js';
+import { FOLLOW_UPS_FILENAME, FollowUpTailer } from './follow-ups.js';
+import { acquireRepoCheckout, agentNeverActed, agentOutputTail, runAgentInWorkspace, } from './pi-workspace.js';
+import { log } from './logger.js';
+/**
+ * How often the harness checkpoints the agent's work mid-run by pushing the branch.
+ * A per-run container can be evicted at any moment; pushing the agent's commits
+ * periodically means an evicted run's work survives on the branch, so a retry
+ * RESUMES on top of it instead of starting over. Overridable via env for tests.
+ */
+function checkpointIntervalMs() {
+    const n = Number(process.env.JOB_CHECKPOINT_INTERVAL_MS);
+    return Number.isFinite(n) && n > 0 ? Math.floor(n) : 60_000;
+}
+/**
+ * How often the harness tails the Coder's follow-up sentinel file to surface new items.
+ * Short (a few seconds) so the Follow-up companion lights up promptly while the Coder is
+ * still running. Overridable via env for tests.
+ */
+function followUpPollIntervalMs() {
+    const n = Number(process.env.JOB_FOLLOWUP_POLL_INTERVAL_MS);
+    return Number.isFinite(n) && n > 0 ? Math.floor(n) : 3_000;
+}
+/**
+ * Clone (or RESUME an existing branch) → write context → run Pi → push the branch
+ * iff it carries work. The agent commits its OWN work (it alone knows which files
+ * belong vs scratch/artifacts it created), so the harness never blanket-stages:
+ * {@link commitTrackedEdits} is only a safety net for forgotten edits to ALREADY
+ * tracked files, and the run is judged a no-op only when the branch never advanced
+ * past its pre-run tip ({@link branchHasCommitsSince}). The harness owns push + PR;
+ * it checkpoints (pushes) periodically so an evicted run's commits survive and a
+ * retry resumes on them. Returns the run's summary/stats, whether it pushed, and
+ * whether it resumed; callers decide what to do after a push (open a PR, or nothing).
+ */
+export async function runCodingAgent(spec, opts = {}) {
+    const { signal } = opts;
+    // The registry already binds jobId/repo/branch; add the coding kind + the push branch
+    // (which differs from the cloned branch the registry bound).
+    const logger = (opts.log ?? log).child({ kind: spec.kind, branch: spec.pushBranch });
+    return acquireRepoCheckout({ persistent: spec.persistentCheckout === true, prefix: spec.kind, repo: spec.repo }, async (dir) => {
+        // Resume an evicted earlier run when its work branch already exists on the
+        // remote: clone THAT branch and continue on its commits, rather than branching
+        // off base and redoing everything. Only the impl path (which creates a fresh
+        // `newBranch`) can resume; the ci-fix/conflict paths already clone the PR branch.
+        //
+        // Resume safety relies on two invariants the dispatcher (worker) upholds, since
+        // the harness can't see run/PR state from inside the container:
+        //  - At most ONE active run per block at a time. The work branch is deterministic
+        //    per block (`cat-factory/<blockId>`), so two concurrent runs would target the
+        //    same branch; their pushes race. A plain (non-forced) push fails safely on a
+        //    non-fast-forward rather than clobbering the other run's commits, so the worst
+        //    case is one run failing — never lost work — but the dispatcher should not
+        //    knowingly run two at once.
+        //  - Re-dispatch only NON-terminal runs (failed / evicted / stale-running), whose
+        //    branch is by definition unmerged. Resuming a branch whose PR already merged
+        //    could re-introduce merged work; that is avoided two ways: the platform deletes
+        //    the work branch when its PR merges (GitHubPullRequestMerger), so a re-run finds
+        //    no branch and starts fresh, and a `done` block is never re-dispatched anyway.
+        const resumed = spec.newBranch != null &&
+            (await remoteBranchExists(spec.repo.cloneUrl, spec.newBranch, spec.ghToken, signal));
+        opts.onPhase?.('clone');
+        if (spec.persistentCheckout) {
+            // Reused checkout: clean-sweep + fetch + switch branch in place. A resumed branch
+            // (or a run without `newBranch`, working directly on `cloneBranch`) already exists
+            // on the remote, so check it out directly; otherwise (re)create `newBranch` off the
+            // base tip — the same resume-vs-fresh decision the clone paths below make.
+            const targetBranch = spec.newBranch ?? spec.cloneBranch;
+            logger.info('coding-agent: preparing reused checkout', { branch: targetBranch, resumed });
+            await prepareExistingCheckout({
+                dir,
+                repo: spec.repo,
+                ghToken: spec.ghToken,
+                branch: targetBranch,
+                baseBranch: spec.cloneBranch,
+                existing: resumed || spec.newBranch == null,
+                signal,
+            });
+        }
+        else if (resumed) {
+            logger.info('coding-agent: resuming existing branch', { branch: spec.newBranch });
+            await cloneExistingBranch({
+                cloneUrl: spec.repo.cloneUrl,
+                branch: spec.newBranch,
+                ghToken: spec.ghToken,
+                dir,
+                signal,
+            });
+        }
+        else {
+            logger.info('coding-agent: cloning', { cloneBranch: spec.cloneBranch });
+            await cloneRepo({
+                repo: { ...spec.repo, baseBranch: spec.cloneBranch },
+                ghToken: spec.ghToken,
+                dir,
+                signal,
+            });
+            if (spec.newBranch)
+                await createBranch(dir, spec.newBranch, signal);
+        }
+        // The branch tip before the agent runs this time. A FRESH run produced work iff
+        // the branch advances past it; a RESUMED run already carries prior work, so it is
+        // never a no-op regardless of what this pass adds. Captured BEFORE the resume base
+        // refresh below so that refresh's merge commit counts as advancement and is pushed.
+        const baseSha = await headCommit(dir, signal);
+        // A resumed branch was cut from an OLDER base; merge the latest base in when the
+        // two merge cleanly, so the agent works against current base and the PR stays
+        // current. On a conflict this is a no-op (the run continues on the stale base — the
+        // merge gate handles a conflicting PR downstream, as before), so it never blocks a
+        // resume. Best-effort: any error is treated as "continue without refreshing".
+        if (resumed) {
+            const refreshed = await refreshFromBaseIfClean(dir, spec.cloneBranch, spec.ghToken, signal).catch(() => false);
+            if (!refreshed) {
+                logger.info('coding-agent: resume base refresh skipped (conflict or error)', {
+                    base: spec.cloneBranch,
+                });
+            }
+        }
+        // Serialize all pushes to the work branch through a single in-flight promise.
+        // A checkpoint tick and the final push (or two slow checkpoint ticks) must never
+        // run `git push` to the same branch concurrently: overlapping pushes race on the
+        // remote ref and can make a push fail with a ref-lock / non-fast-forward error —
+        // which, on the FINAL push, would fail the whole run even though the work is
+        // committed. `pushWorkOnce` coalesces concurrent callers onto one push and only
+        // pushes once the branch has advanced past `baseSha` (see below).
+        //
+        // Only push once the branch has advanced past its pre-run tip: pushing while it
+        // still sits at `baseSha` would create the work branch at the base commit (a
+        // zero-diff branch), which a later retry would see via `remoteBranchExists` and
+        // treat as resumable work — then fail to open a PR ("no commits between base and
+        // head"). So a run that never commits leaves NO branch behind, preserving the
+        // clean no-op outcome.
+        let pushInFlight = null;
+        const pushWorkOnce = () => {
+            if (pushInFlight)
+                return pushInFlight;
+            pushInFlight = (async () => {
+                if (!(await branchHasCommitsSince(dir, baseSha, signal)))
+                    return;
+                await pushBranch(dir, spec.pushBranch, spec.ghToken, signal);
+            })().finally(() => {
+                pushInFlight = null;
+            });
+            return pushInFlight;
+        };
+        // Read the in-flight push, if any. A function (with an explicit return type) so the
+        // value isn't subject to the caller's straight-line narrowing — `pushInFlight` is
+        // only ever assigned inside closures, which flow analysis can't observe.
+        const inFlightPush = () => pushInFlight;
+        // Checkpoint the agent's committed work to the branch periodically so an eviction
+        // mid-run doesn't lose it (a retry then resumes from the pushed commits). The
+        // agent commits its own work; this only PUSHES already-committed commits, so it
+        // never races the agent's staging. Best-effort: a failed checkpoint is skipped.
+        // Surface checkpoint-push failures at warn with a running count: a checkpoint losing
+        // a race is harmless once, but a steadily-climbing count means mid-run work is NOT
+        // being durably checkpointed, so an eviction would lose it — previously invisible at
+        // info level. Still best-effort: a failed checkpoint never fails the run.
+        let checkpointFailures = 0;
+        const checkpoint = setInterval(() => {
+            pushWorkOnce().catch((err) => {
+                checkpointFailures++;
+                logger.warn('coding-agent: checkpoint push failed', {
+                    reason: err instanceof Error ? err.message : String(err),
+                    checkpointFailures,
+                });
+            });
+        }, checkpointIntervalMs());
+        checkpoint.unref?.();
+        // In a monorepo the service lives in a subdirectory: run Pi with its cwd set to
+        // that subtree (git stays rooted at `dir` so commits/pushes still cover the whole
+        // checkout). Created if missing so a coder scaffolding a brand-new service into an
+        // existing monorepo has a cwd to start in. The agent is also TOLD it's in a
+        // monorepo (and where) via the AGENTS.md context below.
+        const serviceDirectory = spec.repo.serviceDirectory;
+        const workDir = serviceDirectory ? join(dir, serviceDirectory) : dir;
+        if (serviceDirectory)
+            await mkdir(workDir, { recursive: true });
+        // 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
+        // lives in the agent's working directory (its cwd), where the prompt tells it to write.
+        const followUpTailer = spec.streamFollowUps && opts.onFollowUp
+            ? new FollowUpTailer(join(workDir, FOLLOW_UPS_FILENAME), opts.onFollowUp, logger)
+            : undefined;
+        let followUpTick;
+        if (followUpTailer) {
+            await excludeFromGit(dir, FOLLOW_UPS_FILENAME, signal);
+            followUpTick = setInterval(() => {
+                void followUpTailer.poll();
+            }, followUpPollIntervalMs());
+            followUpTick.unref?.();
+        }
+        let outcome;
+        try {
+            opts.onPhase?.('agent');
+            logger.info('coding-agent: running agent', { serviceDirectory });
+            const { summary, stats, stderrTail, usage } = await runAgentInWorkspace({
+                dir: workDir,
+                systemPrompt: spec.systemPrompt,
+                userPrompt: spec.userPrompt,
+                model: spec.model,
+                harness: spec.harness,
+                subscriptionToken: spec.subscriptionToken,
+                subscriptionBaseUrl: spec.subscriptionBaseUrl,
+                ambientAuth: spec.ambientAuth,
+                proxyBaseUrl: spec.proxyBaseUrl,
+                sessionToken: spec.sessionToken,
+                serviceDirectory,
+                webToolsGuidance: spec.webToolsGuidance,
+                webSearchProxy: spec.webSearchProxy,
+                guardLimits: spec.guardLimits,
+            }, opts);
+            // Stop tailing the follow-up sentinel and flush any items written after the last
+            // tick, so a fast final burst still reaches the job view before the run is recorded.
+            if (followUpTick)
+                clearInterval(followUpTick);
+            if (followUpTailer)
+                await followUpTailer.poll().catch(() => { });
+            // 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);
+            // 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).
+            clearInterval(checkpoint);
+            const inflight = inFlightPush();
+            if (inflight)
+                await inflight.catch(() => { });
+            // Surface (don't fail on) untracked, non-ignored files the agent left behind:
+            // `commitTrackedEdits` only captures edits to ALREADY tracked files, so a NEW
+            // file the agent created but forgot to commit is silently dropped. Logging it
+            // makes that loss observable when a PR turns out to be missing a file.
+            const leftover = await listUntrackedFiles(dir, signal);
+            if (leftover.length > 0) {
+                logger.warn('coding-agent: uncommitted new files left behind (not pushed)', {
+                    count: leftover.length,
+                    files: leftover.slice(0, 20),
+                });
+            }
+            const hasWork = resumed || (await branchHasCommitsSince(dir, baseSha, signal));
+            if (!hasWork) {
+                logger.info('coding-agent: no changes produced', { ...stats });
+                outcome = {
+                    pushed: false,
+                    resumed,
+                    summary,
+                    stats,
+                    ...(stderrTail ? { stderrTail } : {}),
+                    ...(usage ? { usage } : {}),
+                };
+            }
+            else {
+                opts.onPhase?.('push');
+                logger.info('coding-agent: pushing', { resumed, ...stats });
+                await pushWorkOnce();
+                outcome = {
+                    pushed: true,
+                    resumed,
+                    summary,
+                    stats,
+                    ...(stderrTail ? { stderrTail } : {}),
+                    ...(usage ? { usage } : {}),
+                };
+            }
+        }
+        finally {
+            // Safety net for the throw path (the happy path already cleared these above).
+            clearInterval(checkpoint);
+            if (followUpTick)
+                clearInterval(followUpTick);
+        }
+        return outcome;
+    });
+}
+/**
+ * The "no changes" reason both coding agents report: a caller-supplied lead phrase
+ * plus the shared "never acted" cause and a credential-scrubbed tail of Pi's stderr.
+ */
+export function noChangesReason(lead, stats, stderrTail) {
+    const cause = agentNeverActed(stats)
+        ? ' (the agent never acted — it most likely could not reach the model)'
+        : '';
+    return `${lead}${cause}.${agentOutputTail(stderrTail)}`;
+}

package/dist/conflict-resolver.js

@@ -0,0 +1,138 @@
+import { cloneRepo, commitAll, conflictDiff, headCommit, mergeBranch, pushBranch, unmergedPaths, } from './git.js';
+import { agentNeverActed, agentOutputTail, NEVER_ACTED_CAUSE, runAgentInWorkspace, withWorkspace, } from './pi-workspace.js';
+import { log } from './logger.js';
+// Async job execution for the merge-conflict resolver. When a PR cannot be merged
+// because it conflicts with its base, the engine dispatches this: clone the PR head
+// branch (full history), merge the base branch into it to surface the conflicts,
+// run Pi to resolve them, complete the merge commit and push back onto the SAME
+// branch (no new branch / PR) so the PR becomes mergeable and CI re-runs.
+//
+// Shares the thin workspace/Pi base (withWorkspace + runAgentInWorkspace) with the
+// other agents; it diverges only in needing a full clone, a base→branch merge to
+// produce the conflicts, and a guard that refuses to push a half-resolved tree.
+/** Run one conflict-resolver job: clone → merge base → Pi resolves → push (same branch). */
+export async function handleConflictResolver(job, opts = {}) {
+    const { signal } = opts;
+    const trace = { jobId: job.jobId, repo: `${job.repo.owner}/${job.repo.name}`, branch: job.branch };
+    return withWorkspace('conflict', async (dir) => {
+        log.info('conflict: cloning PR branch (full history)', trace);
+        // Full clone so the merge base + `origin/<base>` are present for the merge.
+        await cloneRepo({
+            repo: { ...job.repo, baseBranch: job.branch },
+            ghToken: job.ghToken,
+            dir,
+            signal,
+            full: true,
+        });
+        const prTip = await headCommit(dir, signal);
+        log.info('conflict: merging base into PR branch', { ...trace, base: job.repo.baseBranch });
+        const clean = await mergeBranch(dir, job.repo.baseBranch, signal);
+        // No conflicts to resolve. If base brought new commits the merge advanced the
+        // branch, so push it; otherwise the branch is already up to date — a no-op we
+        // leave alone (re-dispatching it never changes the PR, so a gate that keeps
+        // seeing GitHub report this branch as "conflicting" is a base-resolution problem,
+        // not the agent's — logged here so that loop is diagnosable).
+        if (clean) {
+            if ((await headCommit(dir, signal)) === prTip) {
+                log.info('conflict: base merged clean and branch already up to date — nothing to push', {
+                    ...trace,
+                    base: job.repo.baseBranch,
+                });
+                return {
+                    resolved: true,
+                    summary: 'No conflicts: the branch is already up to date with its base.',
+                    stats: { toolCalls: 0, assistantChars: 0 },
+                };
+            }
+            log.info('conflict: base merged clean — pushing the merge commit', trace);
+            await pushBranch(dir, job.branch, job.ghToken, signal);
+            return {
+                resolved: true,
+                summary: 'Merged the base in cleanly (no conflicts to resolve).',
+                stats: { toolCalls: 0, assistantChars: 0 },
+            };
+        }
+        // The merge left conflicts in the working tree. Surface the EXACT files + hunks
+        // to the agent: the generic task prompt alone never told it which files conflict
+        // (or even that there were conflicts), so it would drift onto the original feature
+        // task. Lead with the conflict; keep the task only as trailing reference.
+        const conflicted = await unmergedPaths(dir, signal);
+        log.info('conflict: resolving conflicts with agent', { ...trace, conflicted });
+        const diff = await conflictDiff(dir, conflicted, signal);
+        const userPrompt = buildConflictPrompt(job.repo.baseBranch, job.branch, conflicted, diff, job.userPrompt);
+        const { summary, stats, stderrTail, usage } = await runAgentInWorkspace({
+            dir,
+            systemPrompt: job.systemPrompt,
+            userPrompt,
+            model: job.model,
+            harness: job.harness,
+            subscriptionToken: job.subscriptionToken,
+            subscriptionBaseUrl: job.subscriptionBaseUrl,
+            proxyBaseUrl: job.proxyBaseUrl,
+            sessionToken: job.sessionToken,
+        }, opts);
+        // Never push a half-resolved tree: if any conflict markers / unmerged paths
+        // remain, the PR would still be broken. Fail so the engine can retry / notify.
+        const unresolved = await unmergedPaths(dir, signal);
+        if (unresolved.length > 0) {
+            log.error('conflict: unresolved conflicts remain — refusing to push', {
+                ...trace,
+                unresolved: unresolved.length,
+            });
+            return {
+                resolved: false,
+                summary,
+                stats,
+                error: unresolvedReason(unresolved, stats, stderrTail),
+                ...(usage ? { usage } : {}),
+            };
+        }
+        // Complete the merge commit with the agent's resolution staged, then push.
+        await commitAll(dir, `Merge ${job.repo.baseBranch} into ${job.branch}`, signal);
+        log.info('conflict: pushing resolved branch', { ...trace, ...stats });
+        await pushBranch(dir, job.branch, job.ghToken, signal);
+        return { resolved: true, summary, stats, ...(usage ? { usage } : {}) };
+    });
+}
+/**
+ * The conflict-focused user prompt: lead with the exact conflicted files and their
+ * hunks (so the model acts on the real conflict, not the original feature task), then
+ * carry the task only as trailing reference. The role/system prompt frames it as a
+ * merge-conflict resolution; this gives it the concrete material.
+ */
+function buildConflictPrompt(baseBranch, prBranch, conflicted, diff, taskReference) {
+    const fileList = conflicted.map((p) => `- ${p}`).join('\n');
+    const parts = [
+        `The base branch \`${baseBranch}\` was merged into this pull-request branch ` +
+            `\`${prBranch}\` and left Git merge conflicts in the following ${conflicted.length} ` +
+            `file(s):`,
+        '',
+        fileList,
+        '',
+        'Resolve EVERY conflict in these files: open each one, understand both sides of each ' +
+            '`<<<<<<<` / `=======` / `>>>>>>>` region, and edit it to a correct result that ' +
+            "preserves the intent of BOTH the base changes and this PR's changes — never just " +
+            'discard one side. Remove every conflict marker and leave the project building. Do ' +
+            'not create a new branch or PR; the harness completes the merge commit and pushes once ' +
+            'no conflict markers remain.',
+        '',
+        'Conflict hunks (`git diff` of the conflicted files):',
+        '',
+        '```diff',
+        diff,
+        '```',
+    ];
+    const ref = taskReference.trim();
+    if (ref) {
+        parts.push('', 'For reference, the task this pull request implements:', '', ref);
+    }
+    return parts.join('\n');
+}
+/** Human-readable reason the agent failed to fully resolve the conflicts. */
+function unresolvedReason(unresolved, stats, stderrTail) {
+    const cause = agentNeverActed(stats) ? NEVER_ACTED_CAUSE : '';
+    const sample = unresolved.slice(0, 10).join(', ');
+    return (`The agent did not resolve all merge conflicts ` +
+        `(${unresolved.length} file(s) still conflicted: ${sample}).${cause}` +
+        agentOutputTail(stderrTail));
+}

package/dist/embed.js

@@ -0,0 +1,8 @@
+// Embeddable surface of the executor harness: the Pi-driving and git helpers
+// the container payload uses, re-exported so other packages (e.g. the benchmark
+// harness) can run the *same* coding-agent flow outside the container — clone a
+// 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 { cloneRepo, createBranch, changedPathsFromPorcelain, hasAgentChanges, redactSecrets, } from './git.js';

package/dist/explore.js

@@ -0,0 +1,74 @@
+import { join } from 'node:path';
+import { mkdir } from 'node:fs/promises';
+import { cloneRepo } from './git.js';
+import { agentNeverActed, agentOutputTail, runAgentInWorkspace, withWorkspace, } from './pi-workspace.js';
+import { log } from './logger.js';
+// The shared read-only container agent: clone a branch, run Pi to EXPLORE the
+// checkout (read-only), and return its prose report/proposal. Both the architect
+// (proposes a design after reading the code) and the tech-debt analysis agent use
+// this one path. Unlike the coding agents (`/run`, `/ci-fix`) it pushes nothing and
+// opens no PR, and — like the merger — it makes no edits, so an edit-free run is the
+// expected, correct outcome rather than a "no changes" failure. The only failure
+// mode is producing no text at all (the agent never reached the model).
+/** Run one read-only exploration job end to end: clone branch → Pi explores → return prose. */
+export async function handleExplore(job, opts = {}) {
+    const trace = {
+        jobId: job.jobId,
+        kind: job.label ?? 'explore',
+        repo: `${job.repo.owner}/${job.repo.name}`,
+        branch: job.branch,
+    };
+    return withWorkspace(job.label ?? 'explore', async (dir) => {
+        log.info('explore: cloning', trace);
+        await cloneRepo({
+            repo: { ...job.repo, baseBranch: job.branch },
+            ghToken: job.ghToken,
+            dir,
+            signal: opts.signal,
+        });
+        // In a monorepo the service lives in a subdirectory: run Pi with its cwd set
+        // there (created if missing, mirroring the coding agent) so a service-scoped
+        // exploration sees the right subtree.
+        const serviceDirectory = job.repo.serviceDirectory;
+        const workDir = serviceDirectory ? join(dir, serviceDirectory) : dir;
+        if (serviceDirectory)
+            await mkdir(workDir, { recursive: true });
+        log.info('explore: running agent', { ...trace, serviceDirectory });
+        const { summary, stats, stderrTail, usage } = await runAgentInWorkspace({
+            dir: workDir,
+            systemPrompt: job.systemPrompt,
+            userPrompt: job.userPrompt,
+            model: job.model,
+            harness: job.harness,
+            subscriptionToken: job.subscriptionToken,
+            subscriptionBaseUrl: job.subscriptionBaseUrl,
+            proxyBaseUrl: job.proxyBaseUrl,
+            sessionToken: job.sessionToken,
+            serviceDirectory,
+            // Read-only: it inspects and reports, making no edits — so the no-progress
+            // guard's no-edit bound must not fire on its legitimately edit-free run.
+            expectsEdits: false,
+            webToolsGuidance: job.webToolsGuidance,
+            webSearchProxy: job.webSearch,
+        }, opts);
+        // The prose report IS the deliverable; an edit-free run is success. The only
+        // failure is producing no text at all (the signature of never reaching the model).
+        if (!summary.trim()) {
+            return {
+                summary,
+                stats,
+                error: noOutputReason(stats, stderrTail),
+                ...(usage ? { usage } : {}),
+            };
+        }
+        log.info('explore: done', { ...trace, ...stats });
+        return { summary, stats, ...(usage ? { usage } : {}) };
+    });
+}
+/** Human-readable reason a read-only run produced no usable output. */
+function noOutputReason(stats, stderrTail) {
+    const cause = agentNeverActed(stats)
+        ? ' (the agent never acted — it most likely could not reach the model)'
+        : '';
+    return `Read-only agent produced no report${cause}.${agentOutputTail(stderrTail)}`;
+}

package/dist/failure.js

@@ -0,0 +1,47 @@
+// Single source of truth for how a job FAILS: the canonical failure-cause vocabulary plus
+// the watchdog abort-message builders.
+//
+// WHY THIS MODULE EXISTS — the backend classifies a failed job by REGEX-matching the
+// harness's free-text `error` string (it has no other signal today):
+//   - server `ContainerRepoBootstrapper.classifyBootstrapFailure`:
+//       /inactivity|no agent activity|max duration/i → 'timeout', else → 'agent'
+//   - orchestration `job.logic.isContainerEvictionError`: /evicted or crashed/i (FACADE-owned,
+//     NOT emitted here — the harness must keep NOT emitting that phrase for a non-eviction)
+// Because those phrases are matched downstream, their wording MUST stay stable. Centralizing
+// the builders here keeps the emitted text from drifting away from the regex that reads it.
+// Alongside the strings we now also emit a STRUCTURED {@link FailureCause} on the job view so
+// the backend can prefer it and treat the regex as a backward-compatible fallback.
+/**
+ * A thrown failure that carries a structured {@link FailureCause}, so a `git` / `api`
+ * operation that fails deep in a helper surfaces its real cause instead of being flattened
+ * to the generic `agent` in the registry's catch. The watchdog kills set their cause from
+ * `killReason` and never throw this; anything else thrown without a cause stays `agent`.
+ */
+export class HarnessFailure extends Error {
+    failureCause;
+    constructor(failureCause, message) {
+        super(message);
+        this.name = 'HarnessFailure';
+        this.failureCause = failureCause;
+    }
+}
+/** The structured cause a thrown error carries, or undefined for a plain/agent error. */
+export function failureCauseOf(err) {
+    return err instanceof HarnessFailure ? err.failureCause : undefined;
+}
+/**
+ * The inactivity-watchdog abort message PREFIX. The `no agent activity` phrase is
+ * regex-matched by the backend's `classifyBootstrapFailure` (→ `timeout`); do not reword it.
+ * The caller appends a `(likely hung ...)` diagnostic clause (phase + last tool) after this,
+ * so the prefix deliberately stops before the parenthetical (see `runner.ts` drive catch).
+ */
+export function inactivityAbortMessage(inactivityMs) {
+    return `Aborted: no agent activity for ${Math.round(inactivityMs / 1000)}s`;
+}
+/**
+ * The max-duration-watchdog abort message. The `max duration` phrase is regex-matched by the
+ * backend's `classifyBootstrapFailure` (→ `timeout`); do not reword it.
+ */
+export function maxDurationAbortMessage(maxDurationMs) {
+    return `Aborted: exceeded max duration of ${Math.round(maxDurationMs / 1000)}s`;
+}

package/dist/fixer.js

@@ -0,0 +1,44 @@
+import { noChangesReason, runCodingAgent } from './coding-agent.js';
+// Async job execution for the test Fixer. When a Tester withholds its greenlight the
+// engine dispatches this: clone the PR HEAD branch, run Pi to fix the concerns in the
+// Tester's report (folded into the user prompt by the backend), then commit + push
+// back onto the SAME branch (no new branch, no new PR) so the Tester can re-run. The
+// engine re-dispatches the Tester after the push and loops up to the attempt budget.
+//
+// The clone/Pi/push mechanics are shared with implementation + the CI-fixer via
+// runCodingAgent; the Fixer only differs in working ON the existing PR branch.
+/** Run one Fixer job end to end: clone branch → Pi fixes → push (same branch). */
+export async function handleFixer(job, opts = {}) {
+    const { summary, stats, stderrTail, pushed, usage } = await runCodingAgent({
+        kind: 'fix-tests',
+        jobId: job.jobId,
+        repo: job.repo,
+        // Work directly on the PR head branch — no new branch, no new PR.
+        cloneBranch: job.branch,
+        pushBranch: job.branch,
+        ghToken: job.ghToken,
+        systemPrompt: job.systemPrompt,
+        userPrompt: job.userPrompt,
+        model: job.model,
+        harness: job.harness,
+        subscriptionToken: job.subscriptionToken,
+        subscriptionBaseUrl: job.subscriptionBaseUrl,
+        proxyBaseUrl: job.proxyBaseUrl,
+        sessionToken: job.sessionToken,
+        commitMessage: 'Fix issues found by the tester',
+        webToolsGuidance: job.webToolsGuidance,
+        webSearchProxy: job.webSearch,
+    }, opts);
+    // Not an error: the engine re-runs the Tester regardless. Report `pushed: false`
+    // so the (unused) result is still meaningful.
+    if (!pushed) {
+        return {
+            pushed: false,
+            summary,
+            stats,
+            error: noChangesReason('No test fix produced', stats, stderrTail),
+            ...(usage ? { usage } : {}),
+        };
+    }
+    return { pushed: true, summary, stats, ...(usage ? { usage } : {}) };
+}