@cat-factory/executor-harness 1.52.2 → 1.56.0

package/dist/job.js

@@ -66,6 +66,39 @@ function parseValidationSpec(value) {
         ...(iteration !== undefined ? { iteration } : {}),
     };
 }
+/**
+ * Parse the optional PRE-PR VALIDATION CHECKS spec (see
+ * docs/initiatives/pre-pr-validation.md): the service's ordered `{ label, command }` pairs and
+ * the repair-round budget. Every entry needs a non-empty command; entries without one are
+ * dropped, and a spec that ends up with no usable check returns `undefined` — so a malformed
+ * body degrades to the exact pre-feature behaviour (no loop, PR opens as before) rather than
+ * failing an otherwise-good coding run. `maxAttempts` is clamped to a sane range so a bad body
+ * can't make a container loop forever.
+ */
+function parseValidationChecksSpec(value) {
+    if (typeof value !== 'object' || value === null)
+        return undefined;
+    const o = value;
+    if (!Array.isArray(o.checks))
+        return undefined;
+    const checks = [];
+    for (const raw of o.checks) {
+        if (typeof raw !== 'object' || raw === null)
+            continue;
+        const c = raw;
+        if (typeof c.command !== 'string' || c.command.trim() === '')
+            continue;
+        const label = typeof c.label === 'string' && c.label.trim() ? c.label.trim() : c.command;
+        checks.push({ label, command: c.command });
+    }
+    if (checks.length === 0)
+        return undefined;
+    const parsed = posInt(o.maxAttempts);
+    return {
+        checks,
+        maxAttempts: Math.min(parsed ?? VALIDATION_DEFAULT_MAX_ATTEMPTS, VALIDATION_MAX_ATTEMPTS_CEILING),
+    };
+}
 /**
  * Parse the shared per-job auth fields, validating per harness: a subscription
  * harness (`claude-code` / `codex`) requires `subscriptionToken`; the default Pi
@@ -353,6 +386,18 @@ export function parseTestSecrets(value) {
     }
     return entries;
 }
+/**
+ * The ceiling the harness clamps a body-supplied `validationChecks.maxAttempts` to, and the
+ * default it applies when the body omits one.
+ *
+ * DELIBERATE DUPLICATES of `VALIDATION_MAX_ATTEMPTS_CEILING` / `VALIDATION_DEFAULT_MAX_ATTEMPTS`
+ * in `@cat-factory/contracts` — the published image takes no schema dependency, so the harness
+ * cannot import them. Keep the two in step: the API validates writes against the contracts
+ * values, so a harness clamping to a DIFFERENT ceiling would silently cap a budget an operator
+ * was allowed to save, with nothing to flag the mismatch.
+ */
+export const VALIDATION_MAX_ATTEMPTS_CEILING = 10;
+export const VALIDATION_DEFAULT_MAX_ATTEMPTS = 3;
 /** Parse the coding-mode bootstrap spec, or undefined when absent. Validates the target. */
 function parseAgentBootstrapSpec(value) {
     if (typeof value !== 'object' || value === null)
@@ -671,6 +716,7 @@ export function parseAgentJob(input) {
         testSecrets: parseTestSecrets(o.testSecrets),
         guardLimits: parseGuardLimits(o.guardLimits),
         validation: parseValidationSpec(o.validation),
+        validationChecks: parseValidationChecksSpec(o.validationChecks),
         reviewPrNumber: posInt(o.reviewPrNumber),
     });
     assertAllowedHost(job.repo.cloneUrl, 'repo.cloneUrl');
@@ -727,7 +773,7 @@ function parseAgentPrSpec(raw) {
  * literal doesn't blow the complexity budget; behaviour is byte-identical (spread order preserved).
  */
 function assembleAgentJob(o, mode, agentField, parts) {
-    const { output, pr, infra, peerRepos, referenceRepos, referenceBranches, bootstrap, contextFiles, packageRegistries, skill, testSecrets, guardLimits, validation, reviewPrNumber, } = parts;
+    const { output, pr, infra, peerRepos, referenceRepos, referenceBranches, bootstrap, contextFiles, packageRegistries, skill, testSecrets, guardLimits, validation, validationChecks, reviewPrNumber, } = parts;
     const repo = (o.repo ?? {});
     return {
         jobId: str(o.jobId, 'jobId'),
@@ -754,6 +800,7 @@ function assembleAgentJob(o, mode, agentField, parts) {
         ...(reviewPrNumber !== undefined ? { reviewPrNumber } : {}),
         ...(guardLimits ? { guardLimits } : {}),
         ...(validation ? { validation } : {}),
+        ...(validationChecks ? { validationChecks } : {}),
     };
 }
 /**

package/dist/package-registries.js

@@ -1,15 +1,29 @@
-import { chmod, rm, writeFile } from 'node:fs/promises';
+import { chmod, readFile, rm, writeFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { registerKnownSecrets } from './redact.js';
 // Private package-registry auth for the checkout's installs (npm private orgs,
-// GitHub Packages). The job's allowlisted entries are rendered into the USER
-// `~/.npmrc` — read by npm, pnpm and yarn v1 alike, and inherited by every child
-// process (the agent's own shell installs and the frontend-infra stand-up's) — so
-// the token never rides argv or the checkout. Written per job; a job with NO
-// entries removes any stale file, because warm-pool containers are reused across
-// jobs and must not leak a prior workspace's token.
-/** Where the per-job npm auth lands (the user npmrc, outside any checkout). */
+// GitHub Packages). The job's allowlisted entries are rendered into an npmrc — read by
+// npm, pnpm and yarn v1 alike, and inherited by every child process (the agent's own
+// shell installs and the frontend-infra stand-up's) — so the token never rides argv or
+// the checkout.
+//
+// WHERE that npmrc lands depends on whether the harness process owns its HOME:
+//   - container (the default): the user `~/.npmrc`. HOME belongs to that one container, so
+//     writing it is safe and a job with NO entries CLEARS it — warm-pool containers are
+//     reused across jobs and must not leak a prior workspace's token.
+//   - shared native host process (`ambientAuth`, the local native transport): HOME is the
+//     DEVELOPER's. Writing there would overwrite their own npm config, clearing there would
+//     DELETE it, and concurrent jobs in the one process would race on the single file. Such a
+//     job gets its own npmrc under a per-job directory instead, pointed at by
+//     `npm_config_userconfig`; the developer's file is never written and never removed.
+//
+// Note the isolated path trades a little reach for that safety: `~/.npmrc` is read by npm, pnpm
+// and yarn v1 alike, whereas `npm_config_userconfig` is honoured by npm and pnpm but NOT by yarn
+// (v1 or Berry). A yarn-based checkout on the native path therefore sees only the developer's own
+// registries, not the job's. Since the alternative is overwriting the file they actually use, the
+// limitation stands — a yarn repo needing private-registry auth wants the container path.
+/** Where the per-job npm auth lands in a container (the user npmrc, outside any checkout). */
 export function npmrcPath() {
     return join(homedir(), '.npmrc');
 }
@@ -34,18 +48,69 @@ export function renderNpmrc(entries) {
     return `${lines.join('\n')}\n`;
 }
 /**
- * Write (or clear) the per-job `~/.npmrc` before the agent runs. Tokens are
- * registered for output redaction so a token echoed in an npm error never reaches
+ * Write (or clear) the job's npmrc before the agent runs, and return the env the agent's child
+ * process needs to find it (empty for the container default, which npm picks up from HOME).
+ * Tokens are registered for output redaction so a token echoed in an npm error never reaches
  * logs or stored output.
  */
-export async function configurePackageRegistries(entries) {
+export async function configurePackageRegistries(entries, scope = {}) {
+    const hasEntries = Boolean(entries?.length);
+    if (scope.isolatedDir) {
+        // A job with no entries needs no file at all: emitting no override leaves the developer's
+        // own `~/.npmrc` in effect (their private registries keep working) — and, crucially, leaves
+        // it ALONE. Clearing a stale file is a container concern; here nothing stale can exist,
+        // because the per-job dir is created and removed with the job.
+        if (!hasEntries)
+            return {};
+        const path = join(scope.isolatedDir, '.npmrc');
+        await writeIsolatedNpmrc(path, entries);
+        return { npm_config_userconfig: path };
+    }
     const path = npmrcPath();
-    if (!entries || entries.length === 0) {
+    if (!hasEntries) {
         await rm(path, { force: true });
-        return;
+        return {};
     }
     registerKnownSecrets(entries.map((entry) => entry.token));
     await writeFile(path, renderNpmrc(entries), { mode: 0o600 });
     // writeFile's mode only applies on create — tighten an existing file too.
     await chmod(path, 0o600);
+    return {};
+}
+/**
+ * Write the per-job npmrc, seeded from the developer's own `~/.npmrc` when they have one so
+ * their unrelated settings (a corporate registry, a proxy) keep working for this run. The job's
+ * lines are APPENDED, and npm resolves the last occurrence of a key, so the job's entries win on
+ * any host they both configure. Copying their file into a 0600 temp adds no exposure: an ambient
+ * run already has the developer's full file access by definition.
+ *
+ * The seeded credentials are registered for redaction alongside the job's own. The job's tokens
+ * were always registered; the developer's were not, because before this path existed their file
+ * was overwritten and no credential of theirs was in play during the run. Now that theirs is in
+ * effect, an npm error echoing one must be scrubbed on exactly the same terms.
+ */
+async function writeIsolatedNpmrc(path, entries) {
+    registerKnownSecrets(entries.map((entry) => entry.token));
+    // Best-effort: no personal npmrc (or an unreadable one) just means the job's entries stand alone.
+    const inherited = await readFile(npmrcPath(), 'utf8').catch(() => '');
+    registerKnownSecrets(npmrcCredentials(inherited));
+    const prefix = inherited && !inherited.endsWith('\n') ? `${inherited}\n` : inherited;
+    await writeFile(path, `${prefix}${renderNpmrc(entries)}`, { mode: 0o600 });
+    await chmod(path, 0o600);
+}
+/**
+ * The credential VALUES in npmrc content: the three keys npm accepts a secret under, on any host
+ * line. Used to register a seeded (developer-owned) file's tokens for redaction. An `${ENV_VAR}`
+ * reference is not itself a secret — npm expands it at read time — so it is skipped rather than
+ * registered as a literal to scrub.
+ */
+export function npmrcCredentials(content) {
+    const found = [];
+    for (const line of content.split(/\r?\n/)) {
+        const match = /^\s*(?:.*:)?_(?:authToken|auth|password)\s*=\s*(.+?)\s*$/.exec(line);
+        const value = match?.[1]?.replace(/^["']|["']$/g, '');
+        if (value && !/^\$\{.*\}$/.test(value))
+            found.push(value);
+    }
+    return found;
 }

package/dist/pi-workspace.js

@@ -118,11 +118,13 @@ export async function runAgentInWorkspace(spec, opts = {}) {
     // harness paths; kept out of the agent's commits via a local git exclude entry.
     const contextFiles = spec.contextFiles ?? [];
     await materializeContextFiles(spec.dir, contextFiles);
-    // Repo-sourced skill (slice 2): claude-code installs it natively (written by the runner into the
-    // config dir), so it reads from there. Every other harness (Pi/codex) reads the checkout, so
-    // materialise the skill's resources under `.cat-context/skill/` (its instructions are folded
-    // into the prompt by the backend). A resource-free skill is a no-op here.
-    if (spec.skill && spec.harness !== 'claude-code') {
+    // Repo-sourced skill (slice 2): claude-code installs it natively into its ISOLATED config dir,
+    // so it reads from there. Everything else reads the checkout, so materialise the skill's
+    // resources under `.cat-context/skill/` (its instructions are folded into the prompt by the
+    // backend) — Pi, codex, and AMBIENT claude-code, which has no isolated config dir to install
+    // into (the runner refuses to write a repo's skill into the developer's own `~/.claude`; see
+    // `runClaudeCode`). A resource-free skill is a no-op here.
+    if (spec.skill && !installsSkillNatively(spec)) {
         await materializeSkillResources(spec.dir, spec.skill);
     }
     // Subscription harnesses (Claude Code / Codex) authenticate with the leased
@@ -144,6 +146,7 @@ export async function runAgentInWorkspace(spec, opts = {}) {
             subscriptionBaseUrl: spec.subscriptionBaseUrl,
             ...(spec.ambientAuth ? { ambientAuth: true } : {}),
             ...(spec.skill ? { skill: spec.skill } : {}),
+            ...(opts.agentEnv ? { extraEnv: opts.agentEnv } : {}),
             signal: opts.signal,
             onActivity: opts.onActivity,
             onProgress: opts.onProgress,
@@ -169,9 +172,11 @@ export async function runAgentInWorkspace(spec, opts = {}) {
     //    container env, which `webSearchConfigFromEnv` autodetects.
     // The proxy vars are handed to Pi's child via `extraEnv` (not the harness's own
     // process.env), so detection runs against the same merged view the extension sees.
-    const extraEnv = spec.webSearchProxy
-        ? webSearchProxyEnv(proxyBaseUrl, sessionToken)
-        : {};
+    const extraEnv = {
+        ...(spec.webSearchProxy ? webSearchProxyEnv(proxyBaseUrl, sessionToken) : {}),
+        // Per-job env (tester secrets, a private-registry npmrc pointer) — see `RunOptions.agentEnv`.
+        ...opts.agentEnv,
+    };
     const webSearch = webSearchConfigFromEnv({ ...process.env, ...extraEnv });
     if (webSearch)
         await writeWebToolsConfig(webSearch);
@@ -201,6 +206,17 @@ export async function runAgentInWorkspace(spec, opts = {}) {
     });
     return withEffortReport(spec.dir, piOutcome);
 }
+/**
+ * Whether the claude-code runner will install this run's repo-sourced skill natively (into the
+ * CLI's config dir) rather than the caller materialising it into the checkout. True ONLY for a
+ * leased-credential claude-code run, which gets a throwaway per-run config home. An AMBIENT run
+ * uses the developer's own `~/.claude`, which the runner will not write a repo's skill into —
+ * it would outlive the run in their personal setup, and two concurrent jobs carrying same-named
+ * skills from different repos would overwrite each other's.
+ */
+export function installsSkillNatively(spec) {
+    return spec.harness === 'claude-code' && !spec.ambientAuth;
+}
 /**
  * Lift the agent's effort self-assessment off its sentinel file in `dir` and fold it onto the
  * run outcome. Shared by both harness paths so EVERY container agent's effort report is captured

package/dist/pi.js

@@ -210,9 +210,10 @@ export async function materializeContextFiles(cwd, files) {
 export const SKILL_CONTEXT_SUBDIR = 'skill';
 /**
  * Materialise a repo-sourced skill's RESOURCE files under `.cat-context/skill/` in the checkout
- * (repo-sourced Claude Skills, slice 2) — the Pi/codex path, whose agents read the checkout rather
- * than a native `~/.claude/skills` dir (the skill's instructions are folded into their prompt by
- * the backend). Resource sub-paths were sanitized at the job boundary (no traversal), so nested
+ * (repo-sourced Claude Skills, slice 2) — the path for every run that does NOT get a native
+ * install: Pi, codex, and ambient claude-code (no isolated `CLAUDE_CONFIG_DIR` to install into).
+ * Their agents read the checkout, and the skill's instructions are folded into their prompt by the
+ * backend (`renderSkillForHarness`, which keys off ambient auth as well as the harness). Resource sub-paths were sanitized at the job boundary (no traversal), so nested
  * dirs are created as needed. Kept out of the agent's commits via the same `.cat-context/` git
  * exclude entry. A skill with no resource bodies is a no-op.
  */

package/dist/runner.js

@@ -213,6 +213,9 @@ export class JobRegistry {
                 onFollowUp: (items) => {
                     entry.followUpBuffer.push(...items);
                 },
+                onValidationReport: (report) => {
+                    entry.validationReport = report;
+                },
                 onCallMetric: (call) => {
                     // Stamp the job-scoped sequence on the metric OBJECT: the handler keeps the same
                     // instance for its terminal result, so both channels carry the same `seq` and the

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.52.2",
+  "version": "1.56.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",
@@ -26,8 +26,8 @@
     "hono": "^4.12.30",
     "typescript": "7.0.2",
     "vitest": "^4.1.10",
-    "@cat-factory/server": "0.144.1",
-    "@cat-factory/spend": "0.12.77"
+    "@cat-factory/server": "0.149.0",
+    "@cat-factory/spend": "0.12.83"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",