@cat-factory/executor-harness 1.54.0 → 1.58.0

package/dist/validation-checks.js

@@ -0,0 +1,300 @@
+import { spawn } from 'node:child_process';
+import { killChildProcess, spawnDetached } from './process.js';
+import { MAX_CAPTURED_OUTPUT_CHARS, redactSecrets } from './redact.js';
+/**
+ * Per-command output kept on the REPORT (what crosses the wire and lands in the run's persisted
+ * `detail` blob). Deliberately smaller than {@link MAX_CAPTURED_OUTPUT_CHARS}, which is what the
+ * AGENT sees in its repair prompt: the agent needs the full failure to fix it, the operator needs
+ * enough to recognise it, and a chatty build must not inflate every run's stored state.
+ */
+export const VALIDATION_REPORT_TAIL_CHARS = 4_000;
+/**
+ * The per-command watchdog: the longest a single check may run before it is killed and treated
+ * as a failure, so one hung `pnpm test` cannot wedge a run. Overridable via env for tests;
+ * defaults to 15 minutes (matching the ralph completion command's watchdog).
+ */
+export function validationCommandTimeoutMs() {
+    const n = Number(process.env.VALIDATION_COMMAND_TIMEOUT_MS);
+    return Number.isFinite(n) && n > 0 ? Math.floor(n) : 15 * 60_000;
+}
+/**
+ * How often the check loop feeds the run's inactivity watchdog. Well under the harness's own
+ * `JOB_INACTIVITY_MS` (default 10 min) so a single slow command can never look wedged; matches
+ * the frontend stand-up's heartbeat, which exists for exactly the same reason. Overridable via
+ * env for tests, like {@link validationCommandTimeoutMs}.
+ */
+export function validationHeartbeatMs() {
+    const n = Number(process.env.VALIDATION_HEARTBEAT_MS);
+    return Number.isFinite(n) && n > 0 ? Math.floor(n) : 30_000;
+}
+/**
+ * Run every configured check IN ORDER against `cwd` and build the attempt's report.
+ *
+ * Runs all of them even after one fails, rather than short-circuiting: the agent repairing the
+ * checkout should see every problem at once instead of rediscovering the next one on the next
+ * round, which is the difference between one repair round and four. (A check whose failure makes
+ * the rest meaningless — e.g. a failed install — still costs only the cheap downstream failures.)
+ *
+ * Keeps the run's inactivity watchdog fed for the whole attempt. These commands are exactly the
+ * activity-SILENT kind — a cold `install`, a full `test` run, a `build` — and the harness spawns
+ * them itself rather than through the agent, so they emit no activity events of their own. The
+ * job-level watchdog (`JOB_INACTIVITY_MS`, default 10 min) is TIGHTER than one command's own
+ * watchdog ({@link validationCommandTimeoutMs}, default 15 min), so without this a legitimately
+ * slow check would abort the entire run as "inactivity" — mislabelling a healthy build as a
+ * wedge, and making the per-command timeout unreachable at stock settings.
+ */
+export async function runValidationChecks(cwd, spec, attempt, logger, opts) {
+    const outcomes = [];
+    const fullTails = new Map();
+    const heartbeat = setInterval(() => opts.onActivity?.(), validationHeartbeatMs());
+    heartbeat.unref?.();
+    try {
+        for (const check of spec.checks) {
+            const { outcome, fullTail } = await runOneCheck(cwd, check, logger, opts);
+            outcomes.push(outcome);
+            if (fullTail)
+                fullTails.set(check.label, fullTail);
+        }
+    }
+    finally {
+        clearInterval(heartbeat);
+    }
+    const report = {
+        passed: outcomes.every((o) => o.passed),
+        attempts: attempt,
+        maxAttempts: spec.maxAttempts,
+        outcomes,
+        at: Date.now(),
+    };
+    logger.info('validation: attempt finished', {
+        attempt,
+        maxAttempts: spec.maxAttempts,
+        passed: report.passed,
+        failed: outcomes.filter((o) => !o.passed).map((o) => o.label),
+    });
+    return { report, fullTails };
+}
+/**
+ * Run ONE check as `sh -c <command>` in `cwd`, capturing a bounded, secret-scrubbed tail of its
+ * combined stdout+stderr. The exit code is the verdict — computed here by the harness, never
+ * self-reported by the model, which is the whole point of a programmatic gate. A watchdog kills
+ * the process tree on timeout and an aborted run resolves non-zero, so the loop is never blocked.
+ *
+ * The child inherits the JOB's environment (`RunOptions.agentEnv` layered over the process env),
+ * not a mutated global: the harness spawns this itself rather than through the agent, so without
+ * the explicit merge a native-mode job would run its checks without the private-registry npmrc
+ * pointer (and against a sibling job's state, had this been staged in `process.env`).
+ */
+async function runOneCheck(cwd, check, logger, opts) {
+    const timeoutMs = validationCommandTimeoutMs();
+    const startedAt = Date.now();
+    logger.info('validation: running check', { label: check.label });
+    return new Promise((resolve) => {
+        let out = '';
+        let settled = false;
+        let timedOut = false;
+        const child = spawn('sh', ['-c', check.command], {
+            cwd,
+            detached: spawnDetached,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            env: { ...process.env, ...opts.agentEnv },
+        });
+        // Keep only the tail; guard against unbounded buffering on a chatty command.
+        const capture = (chunk) => {
+            out = (out + chunk.toString('utf8')).slice(-MAX_CAPTURED_OUTPUT_CHARS);
+        };
+        child.stdout?.on('data', capture);
+        child.stderr?.on('data', capture);
+        const finish = (exitCode) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            opts.signal?.removeEventListener('abort', onAbort);
+            const trimmed = out.trim();
+            // Scrub BEFORE truncating: a token straddling the cut would otherwise survive as a
+            // partial, and the pattern rules need the whole assignment to match.
+            const scrubbed = trimmed ? redactSecrets(trimmed) : '';
+            logger.info('validation: check finished', { label: check.label, exitCode });
+            resolve({
+                outcome: {
+                    label: check.label,
+                    command: check.command,
+                    exitCode,
+                    passed: exitCode === 0,
+                    ...(scrubbed ? { outputTail: tailFor(scrubbed) } : {}),
+                    durationMs: Date.now() - startedAt,
+                    ...(timedOut ? { timedOut: true } : {}),
+                },
+                ...(scrubbed ? { fullTail: scrubbed } : {}),
+            });
+        };
+        const timer = setTimeout(() => {
+            logger.warn('validation: check timed out', { label: check.label, timeoutMs });
+            timedOut = true;
+            killChildProcess(child, undefined, logger);
+            finish(124); // conventional timeout exit code (a non-zero fail)
+        }, timeoutMs);
+        timer.unref?.();
+        const onAbort = () => {
+            killChildProcess(child, undefined, logger);
+            finish(130); // aborted (a non-zero fail)
+        };
+        opts.signal?.addEventListener('abort', onAbort, { once: true });
+        child.on('error', (err) => {
+            logger.warn('validation: check failed to spawn', {
+                label: check.label,
+                error: err instanceof Error ? err.message : String(err),
+            });
+            finish(127); // spawn error / command not found (a non-zero fail)
+        });
+        child.on('close', (code) => finish(code ?? 1));
+    });
+}
+/** Bound an already-scrubbed output tail to what the REPORT carries. */
+function tailFor(scrubbed) {
+    if (scrubbed.length <= VALIDATION_REPORT_TAIL_CHARS)
+        return scrubbed;
+    const trimmed = scrubbed.length - VALIDATION_REPORT_TAIL_CHARS;
+    return `…(${trimmed} earlier chars trimmed)\n${scrubbed.slice(-VALIDATION_REPORT_TAIL_CHARS)}`;
+}
+/**
+ * The repair instruction handed to the agent after a failed attempt: the failing commands and
+ * their captured output, plus an explicit statement of the exit condition and the remaining
+ * budget. The FULL captured tail is used here (not the report's smaller bound) — the agent needs
+ * the whole failure to fix it, and this text never leaves the container.
+ *
+ * Deliberately prescriptive about scope: a validation loop that lets the agent "fix" the failure
+ * by weakening the check is worse than no loop at all, so the prompt forbids editing the
+ * commands' configuration to make them pass.
+ */
+export function buildRepairPrompt(report, fullTails, 
+/**
+ * New files the agent created but never `git add`ed, if the caller can tell. The harness only
+ * auto-stages TRACKED edits (`git add -u`), so an uncommitted new file is invisible to the push
+ * — yet fully visible to the checks, which run against the working tree. Naming them here is
+ * what stops the loop going green on work the pull request would not contain.
+ */
+untrackedFiles = []) {
+    const failed = report.outcomes.filter((o) => !o.passed);
+    const blocks = failed
+        .map((o) => {
+        const body = fullTails.get(o.label) ?? o.outputTail ?? '(no output captured)';
+        const reason = o.timedOut
+            ? `timed out after ${Math.round((o.durationMs ?? 0) / 1000)}s`
+            : `exited ${o.exitCode}`;
+        return `### ${o.label} — ${reason}\n\n\`\`\`\n$ ${o.command}\n${body}\n\`\`\``;
+    })
+        .join('\n\n');
+    const remaining = report.maxAttempts - report.attempts;
+    const untracked = untrackedFiles.length
+        ? [
+            '',
+            '## Uncommitted new files',
+            '',
+            'These files exist in your checkout but were never added to git, so they are NOT part of',
+            'the branch even though the checks above ran against them. `git add` each one you meant to',
+            'keep (or delete it), or the checks will pass on work the pull request will not contain:',
+            '',
+            ...untrackedFiles.map((f) => `- ${f}`),
+        ]
+        : [];
+    return [
+        'The work you just finished does NOT pass this service’s required validation checks, so',
+        'no pull request has been opened. Fix the failures below, then stop.',
+        '',
+        blocks,
+        ...untracked,
+        '',
+        '## How this is judged',
+        '',
+        `The checks above are re-run automatically against your checkout when you stop. They are the`,
+        `exit condition: a pull request opens only once every one of them exits 0. You have`,
+        `${remaining} attempt(s) left before this task fails.`,
+        '',
+        '## Rules',
+        '',
+        '- Fix the underlying problem in the code. Do NOT edit, disable, skip, or relax the checks',
+        '  themselves (their scripts, configs, thresholds, ignore files, or test assertions) to make',
+        '  them pass — a green check obtained that way is a failed task.',
+        '- Do not revert your earlier work; build on it.',
+        '- Commit your fixes, as you did before. `git add` any NEW file you create — only changes to',
+        '  files already tracked by git are staged for you, so an unadded file is silently dropped',
+        '  from the branch even though the checks can see it.',
+    ].join('\n');
+}
+/**
+ * The pre-PR validation LOOP: run the checks, and while they fail and budget remains, hand the
+ * captured output back to the agent as its next instruction and check again. Returns the LAST
+ * attempt's report — `passed: true` means the caller may open the PR; `passed: false` means the
+ * budget is spent and the caller must FAIL the job with this report as the evidence, opening
+ * nothing.
+ *
+ * Generic by construction: it knows nothing about agent kinds, repos or PRs — only how to run
+ * commands in a directory and how to ask for another pass. Every input (`workDir`, `spec`,
+ * `opts.agentEnv`) is per-job, so two concurrent jobs on the ONE local-native host process cannot
+ * see each other's configuration (`validation-checks.concurrency.test.ts` pins this).
+ *
+ * `onAttempt` publishes each completed attempt on the job view so the loop is observable while it
+ * runs; `onAgentPass` lets the caller fold each repair pass's stats/usage/telemetry into the run's
+ * totals, so a 3-round loop reports what all 3 rounds actually spent.
+ */
+export async function runValidationLoop(args) {
+    const { workDir, spec, logger, opts, runAgentPass, onAgentPass, listUncommittedNewFiles } = args;
+    let attempt = 1;
+    for (;;) {
+        const { report, fullTails } = await runValidationChecks(workDir, spec, attempt, logger, opts);
+        opts.onValidationReport?.(report);
+        if (report.passed) {
+            logger.info('validation: checkout is green', { attempt });
+            return report;
+        }
+        if (attempt >= spec.maxAttempts) {
+            logger.warn('validation: attempt budget spent — no PR will be opened', {
+                attempt,
+                maxAttempts: spec.maxAttempts,
+            });
+            return report;
+        }
+        attempt += 1;
+        logger.info('validation: repairing', { nextAttempt: attempt });
+        opts.onPhase?.('validation-repair');
+        const untracked = await safeListUncommitted(listUncommittedNewFiles, logger);
+        const run = await runAgentPass(buildRepairPrompt(report, fullTails, untracked));
+        onAgentPass?.(run);
+        opts.onPhase?.('agent');
+    }
+}
+/**
+ * The uncommitted-new-file list for a repair prompt, never throwing: this is an ADVISORY
+ * addition to the instruction, so a `git` hiccup must degrade to "no warning" rather than
+ * failing a loop that is otherwise working.
+ */
+async function safeListUncommitted(list, logger) {
+    if (!list)
+        return [];
+    try {
+        return await list();
+    }
+    catch (error) {
+        logger.warn('validation: could not list uncommitted new files', {
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return [];
+    }
+}
+/**
+ * The failure message for a run whose pre-PR validation never went green: which checks failed
+ * (with exit codes) and the last one's captured output. Read by the operator on the step's
+ * failure card, so it must say what broke without needing the full report opened.
+ */
+export function validationFailureMessage(report) {
+    const failed = report.outcomes.filter((o) => !o.passed);
+    const names = failed.map((o) => `${o.label} (exit ${o.exitCode})`).join(', ');
+    const last = failed[failed.length - 1];
+    const tail = last?.outputTail?.trim();
+    const head = `pre-PR validation failed after ${report.attempts} of ${report.maxAttempts} attempt(s)` +
+        (names ? `: ${names}` : '') +
+        '. No pull request was opened.';
+    return tail ? `${head}\n\n$ ${last?.command}\n${tail}` : head;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/executor-harness",
-  "version": "1.54.0",
+  "version": "1.58.0",
   "description": "Container payload: a thin TypeScript wrapper that runs the Pi coding agent against a cloned repo and opens a PR. Runs in the Cloudflare Container (and, in local native mode, as a host process); carries no secrets.",
   "repository": {
     "type": "git",
@@ -21,13 +21,13 @@
     "access": "public"
   },
   "devDependencies": {
-    "@hono/node-server": "^2.0.10",
+    "@hono/node-server": "^2.0.12",
     "@types/node": "^26.1.1",
-    "hono": "^4.12.30",
+    "hono": "^4.12.32",
     "typescript": "7.0.2",
     "vitest": "^4.1.10",
-    "@cat-factory/server": "0.144.4",
-    "@cat-factory/spend": "0.12.77"
+    "@cat-factory/server": "0.153.1",
+    "@cat-factory/spend": "0.12.89"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",

package/src/agent.ts

@@ -38,6 +38,7 @@ import {
   runCodingAgent,
   runMultiRepoCoding,
 } from './coding-agent.js'
+import { validationFailureMessage } from './validation-checks.js'
 import {
   acquireRepoCheckout,
   agentNeverActed,
@@ -966,6 +967,11 @@ function buildSingleRepoCodingSpec(
           },
         }
       : {}),
+    // Pre-PR validation: the service's check commands, run against the checkout BEFORE the PR
+    // opens with failures fed back to the agent (see docs/initiatives/pre-pr-validation.md).
+    // Forwarded straight off the job body — the loop is generic machinery keyed on the data, not
+    // on the agent kind.
+    ...(job.validationChecks ? { validationChecks: job.validationChecks } : {}),
   }
 }
 
@@ -977,13 +983,49 @@ function buildSingleRepoCodingSpec(
  */
 async function runSingleRepoCoding(job: AgentJob, opts: RunOptions): Promise<AgentResult> {
   const pushBranch = job.pushBranch ?? job.newBranch ?? job.branch
-  const { summary, stats, stderrTail, pushed, usage, callMetrics, validation, effortReport } =
-    await runCodingAgent(buildSingleRepoCodingSpec(job, pushBranch), opts)
+  const {
+    summary,
+    stats,
+    stderrTail,
+    pushed,
+    usage,
+    callMetrics,
+    validation,
+    validationReport,
+    effortReport,
+  } = 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 } : {}
   // The agent's effort self-assessment, spread onto every result path below (mirrors ralphVerdict).
   const effort = effortReport ? { effortReport } : {}
+  // The pre-PR validation report, spread onto every result path below: on the passing path it is
+  // the captured proof the checkout was green when the PR opened; on the exhausted path it is the
+  // evidence behind the failure below. Absent when the service configured no checks.
+  const validationFields = validationReport ? { validationReport } : {}
+
+  // Pre-PR validation spent its attempt budget with the checkout still red. FAIL the job — do
+  // NOT open a pull request, and do not pretend the push succeeded as a deliverable. The work is
+  // still on the branch (a retry resumes on it); the report carries each failing command's exit
+  // code and captured output so the step's failure detail says exactly what broke.
+  if (validationReport && !validationReport.passed) {
+    return {
+      // The work IS on the branch (the loop only runs for a pass that produced some, and the
+      // harness pushes it) — a retry resumes on top of it. `error` is what marks the job failed;
+      // reporting `pushed: false` here would misdescribe the branch state in the harness's own
+      // result for no benefit.
+      pushed,
+      branch: pushBranch,
+      summary,
+      stats,
+      error: validationFailureMessage(validationReport),
+      failureCause: 'agent',
+      ...(usage ? { usage } : {}),
+      ...(callMetrics ? { callMetrics } : {}),
+      ...validationFields,
+      ...effort,
+    }
+  }
 
   if (!pushed) {
     // A no-op: a failure for the implementer, a clean non-event for the fixers.
@@ -996,6 +1038,7 @@ async function runSingleRepoCoding(job: AgentJob, opts: RunOptions): Promise<Age
         ...(usage ? { usage } : {}),
         ...(callMetrics ? { callMetrics } : {}),
         ...ralphVerdict,
+        ...validationFields,
         ...effort,
       }
     }
@@ -1008,6 +1051,7 @@ async function runSingleRepoCoding(job: AgentJob, opts: RunOptions): Promise<Age
       failureCause: 'no-changes',
       ...(usage ? { usage } : {}),
       ...(callMetrics ? { callMetrics } : {}),
+      ...validationFields,
       ...effort,
     }
   }
@@ -1042,6 +1086,7 @@ async function runSingleRepoCoding(job: AgentJob, opts: RunOptions): Promise<Age
           stats,
           ...(usage ? { usage } : {}),
           ...(callMetrics ? { callMetrics } : {}),
+          ...validationFields,
           ...effort,
         }
       }
@@ -1058,6 +1103,7 @@ async function runSingleRepoCoding(job: AgentJob, opts: RunOptions): Promise<Age
         failureCause: 'no-changes',
         ...(usage ? { usage } : {}),
         ...(callMetrics ? { callMetrics } : {}),
+        ...validationFields,
         ...effort,
       }
     }
@@ -1070,6 +1116,7 @@ async function runSingleRepoCoding(job: AgentJob, opts: RunOptions): Promise<Age
       ...(usage ? { usage } : {}),
       ...(callMetrics ? { callMetrics } : {}),
       ...ralphVerdict,
+      ...validationFields,
       ...effort,
     }
   }
@@ -1081,6 +1128,7 @@ async function runSingleRepoCoding(job: AgentJob, opts: RunOptions): Promise<Age
     ...(usage ? { usage } : {}),
     ...(callMetrics ? { callMetrics } : {}),
     ...ralphVerdict,
+    ...validationFields,
     ...effort,
   }
 }

package/src/coding-agent.ts

@@ -42,6 +42,11 @@ import {
 import type { ProgressGuardLimits } from './pi.js'
 import type { RunOptions } from './runner.js'
 import { log, type Logger } from './logger.js'
+import {
+  runValidationLoop,
+  type ValidationChecksSpec,
+  type ValidationReport,
+} from './validation-checks.js'
 
 // The shared skeleton for the container coding agents that clone a repo, run Pi
 // against it and push the result on a branch. The implementation (`/run`) and
@@ -103,6 +108,15 @@ export interface CodingAgentSpec extends HarnessAuthFields {
    * condition — computed by the harness, never the model). Absent for every non-`ralph` run.
    */
   validation?: { command: string; iteration?: number }
+  /**
+   * PRE-PR VALIDATION: the service's configured check commands + repair-round budget. When set,
+   * the harness runs them against the checkout after the agent settles and, while they fail and
+   * budget remains, re-runs the agent with the captured output as its instruction. A red checkout
+   * at the end means the caller opens NO pull request and fails the job. Set only for a dispatch
+   * that opens a PR and whose service configured checks; absent everywhere else. See
+   * `docs/initiatives/pre-pr-validation.md`.
+   */
+  validationChecks?: ValidationChecksSpec
   /**
    * A repo-sourced Claude Skill to make available for this run (a `skill` step, slice 2). Threaded
    * into {@link runAgentInWorkspace}, which installs it harness-aware: natively under the ISOLATED
@@ -138,6 +152,12 @@ export interface CodingAgentOutcome {
     validationOutputTail?: string
     iteration?: number
   }
+  /**
+   * The pre-PR validation loop's LAST attempt (present only when {@link CodingAgentSpec.validationChecks}
+   * was set). `passed: false` means the attempt budget was spent with the checkout still red —
+   * the caller must open no PR and fail the job with this as the evidence.
+   */
+  validationReport?: ValidationReport
 }
 
 /**
@@ -271,15 +291,17 @@ export async function runCodingAgent(
         followUpTick.unref?.()
       }
 
-      let outcome: CodingAgentOutcome
-      try {
-        opts.onPhase?.('agent')
-        logger.info('coding-agent: running agent', { serviceDirectory })
-        const agentRun = await runAgentInWorkspace(
+      // One agent pass over this checkout, parameterised only by the prompt — so the pre-PR
+      // validation loop below can re-run the agent with a repair instruction without
+      // re-deriving (or drifting from) the dispatch's own settings.
+      const runAgentPass = (
+        userPrompt: string,
+      ): Promise<Awaited<ReturnType<typeof runAgentInWorkspace>>> =>
+        runAgentInWorkspace(
           {
             dir: workDir,
             systemPrompt: spec.systemPrompt,
-            userPrompt: spec.userPrompt,
+            userPrompt,
             model: spec.model,
             harness: spec.harness,
             subscriptionToken: spec.subscriptionToken,
@@ -295,7 +317,38 @@ export async function runCodingAgent(
           },
           opts,
         )
+
+      let outcome: CodingAgentOutcome
+      try {
+        opts.onPhase?.('agent')
+        logger.info('coding-agent: running agent', { serviceDirectory })
+        let agentRun = await runAgentPass(spec.userPrompt)
+        // PRE-PR VALIDATION: run the service's configured checks against the checkout and, while
+        // they fail and budget remains, hand the captured output back to the agent and run it
+        // again. Sits BETWEEN the agent and the finalize/push/PR step so a red checkout never
+        // reaches `openPullRequest` — the whole point of the feature. Keyed purely off the job
+        // body carrying checks (no agent-kind switch); absent ⇒ this is a no-op and the flow
+        // below is byte-for-byte what it was.
+        const validationChecks = spec.validationChecks
+        let validationReport: ValidationReport | undefined
+        if (validationChecks && (await producedWork(dir, spec, baseSha, resumed, opts))) {
+          validationReport = await runValidationLoop({
+            workDir,
+            spec: validationChecks,
+            logger,
+            opts,
+            runAgentPass,
+            onAgentPass: (run) => {
+              agentRun = mergeAgentPasses(agentRun, run)
+            },
+            // The checks run against the WORKING TREE, but only tracked edits are staged for the
+            // push — so a repair round can go green on a new file the PR would never contain.
+            // Name those files in the next repair prompt so the agent adds them.
+            listUncommittedNewFiles: () => listUntrackedFiles(workDir, opts.signal),
+          })
+        }
         outcome = await finalizeCodingRun({
+          validationReport,
           dir,
           spec,
           logger,
@@ -444,6 +497,8 @@ async function prepareCodingCheckout(
  * {@link runCodingAgent} so its body stays small; returns the built {@link CodingAgentOutcome}.
  */
 async function finalizeCodingRun(args: {
+  /** The pre-PR validation loop's last attempt, attached to the outcome (absent when unconfigured). */
+  validationReport?: ValidationReport
   dir: string
   spec: CodingAgentSpec
   logger: Logger
@@ -459,6 +514,7 @@ async function finalizeCodingRun(args: {
   agentRun: Awaited<ReturnType<typeof runAgentInWorkspace>>
 }): Promise<CodingAgentOutcome> {
   const {
+    validationReport,
     dir,
     spec,
     logger,
@@ -558,9 +614,74 @@ async function finalizeCodingRun(args: {
   if (spec.validation) {
     outcome.validation = await runRalphValidation(workDir, spec.validation, logger, opts)
   }
+  // Pre-PR validation: the loop already ran (before this finalize, so a red checkout never
+  // reaches the PR-opening caller); attach its verdict for the caller to gate on and for the
+  // backend to record on the step.
+  if (validationReport) outcome.validationReport = validationReport
   return outcome
 }
 
+/**
+ * Whether this pass produced anything worth VALIDATING — i.e. the branch advanced past its
+ * pre-run tip (or the run resumed an earlier one's pushed work). Gates the pre-PR validation
+ * loop, for two reasons: a run that changed nothing has nothing to check, and its real failure
+ * is "the agent produced no file changes" — reporting a red BASE branch instead would blame the
+ * run for a pre-existing condition it never touched (and burn the whole repair budget re-running
+ * an agent that already declined to act).
+ *
+ * Commits forgotten edits to tracked files first, exactly as {@link finalizeCodingRun} does, so
+ * an agent that edited-but-didn't-commit still counts as work. That call is idempotent, so
+ * finalize repeating it later is a no-op. Uncommitted NEW files are invisible here — but they
+ * are equally invisible to finalize, so a run whose only product is an uncommitted new file is
+ * a no-op on both paths, and the checks would have nothing to gate anyway.
+ */
+async function producedWork(
+  dir: string,
+  spec: CodingAgentSpec,
+  baseSha: string,
+  resumed: boolean,
+  opts: RunOptions,
+): Promise<boolean> {
+  await commitTrackedEdits(dir, spec.commitMessage, opts.signal)
+  return resumed || (await branchHasCommitsSince(dir, baseSha, opts.signal))
+}
+
+/**
+ * Fold a pre-PR validation REPAIR pass's run into the accumulated agent outcome, so a looped run
+ * reports what every round actually spent rather than only the first. Counts and telemetry are
+ * summed/concatenated; the single-valued fields (the summary the backend renders, the effort
+ * report, the diagnostics that judge the FINAL answer) take the LATEST pass, which is the one
+ * whose state the PR is opened from.
+ */
+function mergeAgentPasses<T extends Awaited<ReturnType<typeof runAgentInWorkspace>>>(
+  previous: T,
+  next: T,
+): T {
+  return {
+    ...next,
+    stats: {
+      toolCalls: (previous.stats?.toolCalls ?? 0) + (next.stats?.toolCalls ?? 0),
+      assistantChars: (previous.stats?.assistantChars ?? 0) + (next.stats?.assistantChars ?? 0),
+    },
+    ...(previous.usage || next.usage
+      ? {
+          usage: {
+            inputTokens: (previous.usage?.inputTokens ?? 0) + (next.usage?.inputTokens ?? 0),
+            outputTokens: (previous.usage?.outputTokens ?? 0) + (next.usage?.outputTokens ?? 0),
+          },
+        }
+      : {}),
+    ...(previous.callMetrics || next.callMetrics
+      ? { callMetrics: [...(previous.callMetrics ?? []), ...(next.callMetrics ?? [])] }
+      : {}),
+    // The repair pass's own effort report wins when it wrote one; otherwise keep the first
+    // pass's rather than losing the assessment entirely.
+    ...((next.effortReport ?? previous.effortReport)
+      ? { effortReport: next.effortReport ?? previous.effortReport }
+      : {}),
+  }
+}
+
 /**
  * The Ralph-loop validation watchdog: the longest a completion command may run before it is
  * killed and treated as a failure (a hung `pnpm test` must never block the loop forever).