@cat-factory/executor-harness 1.52.2 → 1.56.0

package/README.md

@@ -59,12 +59,56 @@ The implementation job (`POST /run`) is the canonical sequence:
    Pi reads and concatenates both), and point Pi at the Worker's LLM proxy via
    `~/.pi/agent/models.json` (provider `proxy`, `api: openai-completions`),
 3. **run Pi** non-interactively (`pi -p --mode json --model proxy/<model> --approve`),
-4. **commit, push** a branch and **open a PR**, returning `{ prUrl, branch, summary }`.
+4. **validate** the checkout, when the job body carries `validationChecks` — the service's
+   configured check commands (install/lint/test/build) run with `sh -c` in the checkout, and
+   while they fail and the attempt budget remains the agent is re-run with the captured output
+   as its instruction (see [pre-PR validation](../../../docs/initiatives/pre-pr-validation.md)),
+5. **commit, push** a branch and **open a PR**, returning `{ prUrl, branch, summary }` — but
+   ONLY if step 4 ended green. A spent budget returns an error result with the validation report
+   and opens no PR. Absent `validationChecks`, step 4 does not happen at all.
 
 Bootstrap differs at the ends — it may start from an empty dir, and **resets
 history to one commit and force-pushes** the default branch instead of opening a
 PR. Blueprint **commits onto a branch** (no history reset) and returns the tree.
 
+## Per-job state: never a process- or HOME-global
+
+A job's staging state (the tester's secrets, private-registry auth, a repo-sourced Claude
+Skill) must be scoped to that job, not written into `process.env` or the home directory.
+
+In a container those two ARE per-job — one job per process, and `HOME` belongs to that
+container — so a global was a safe place to stage. The **local native transport** breaks both
+assumptions: one long-lived host process serves every concurrent `ambientAuth` job, on the
+**developer's own home**. A global there is shared mutable state across siblings, and writing
+(or clearing) a dotfile destroys a file the developer owns.
+
+So per-job values ride explicit **child env** (`RunOptions.agentEnv` →
+`SubscriptionRunOptions.extraEnv`, merged over the inherited env at spawn) and per-job files go
+under a per-job directory:
+
+| State                | Container                                    | Native (`ambientAuth`)                                                    |
+| -------------------- | -------------------------------------------- | ------------------------------------------------------------------------- |
+| Tester secrets       | child env                                    | child env (same path — the old `process.env` set/restore is gone)         |
+| Private-registry auth | `~/.npmrc`; cleared when a job has no entries | per-job `.npmrc` + `npm_config_userconfig`, seeded from the developer's; theirs is never written or removed |
+| Repo-sourced Claude Skill | installed into the isolated `CLAUDE_CONFIG_DIR` | not installed — read from the checkout's `.cat-context/skill/`, like codex |
+
+Two consequences worth knowing:
+
+- **The skill's PROMPT follows the same split.** A native install gets a short pointer; every
+  checkout-reading case (Pi, codex, ambient claude-code) gets the instructions folded in plus a
+  pointer to `.cat-context/skill/`. That decision is the backend's `renderSkillForHarness`, which
+  keys off `ambientAuth` as well as the harness — rendering an ambient run as an install would
+  point the agent at a skill that is nowhere on disk.
+- **`npm_config_userconfig` reaches less than `~/.npmrc` did.** npm and pnpm honour it; yarn does
+  not. And it only reaches processes that are handed the job env, so anything the HARNESS itself
+  spawns (the frontend stand-up's install/build, a ralph validation command) is passed
+  `RunOptions.agentEnv` explicitly rather than relying on inheritance.
+
+When you add per-job state, put it in one of those two places. `~/.pi/*` and
+`~/.config/rpiv-web-tools` remain HOME-global, which is fine only because the Pi harness never
+runs natively (the native router sends `ambientAuth` jobs — Claude/Codex only — to the host
+process and everything else to a container).
+
 ## No secrets in the image
 
 The image (built from the `Dockerfile`, base `node:26-trixie-slim`) contains
@@ -86,8 +130,10 @@ Kimi / DeepSeek) and meters spend. The provider key never enters the container.
 | `src/bootstrap.ts` | The `/bootstrap` handler (clone-or-empty → adapt → reinit + force-push).                                |
 | `src/blueprint.ts` | The `/blueprint` handler (decompose → render `blueprints/` → commit on branch).                         |
 | `src/embed.ts`     | Bundled assets/templates written into the workspace.                                                    |
+| `src/package-registries.ts` | Private-registry (npm) auth: renders the job's allowlisted entries into an npmrc — the user `~/.npmrc` in a container, a per-job file pointed at by `npm_config_userconfig` for a native job. |
 | `src/agent-runner.ts` | The subscription-harness runners (`runClaudeCode` / `runCodex`) — talk direct to the vendor with a leased OAuth token, lift per-turn usage/telemetry off the CLI event stream. |
 | `src/transcript-retention.ts` | Lifts the CLI session transcripts (`projects/` / `sessions/`) out of the isolated, credential-bearing config home before it is deleted, and prunes them on a TTL (debugging artifact retention). |
+| `src/validation-checks.ts` | Pre-PR validation: runs the job's check commands in the checkout (bounded, secret-scrubbed capture, per-command watchdog) and drives the retry-until-green loop that gates the PR. Generic — keyed off the job body, never the agent kind. |
 | `src/logger.ts`    | Structured logging.                                                                                     |
 
 ## Runner lifecycle knobs
@@ -100,6 +146,7 @@ runner):
 | `PORT`                | `8080`          | HTTP port the harness listens on.                           |
 | `JOB_MAX_DURATION_MS` | `3600000` (60m) | Hard ceiling on a job's wall-clock time; force-fails after. |
 | `JOB_INACTIVITY_MS`   | `600000` (10m)  | Kills a hung agent that produces no output for this long.   |
+| `VALIDATION_COMMAND_TIMEOUT_MS` | `900000` (15m) | Per-command watchdog for a pre-PR validation check; a timeout counts as a failure (exit 124) so one hung command can't wedge the loop. |
 | `HARNESS_TRANSCRIPT_TTL_MS` | `259200000` (3d) | How long lifted subscription-CLI session transcripts are kept before the retention sweep prunes them. |
 | `HARNESS_TRANSCRIPT_ROOT`   | `<tmpdir>/cf-agent-transcripts` | Where retained session transcripts are moved to (one dir per run). Meaningful only on a reused (warm-pool) container; a per-run container is torn down with the job. The TTL sweep deletes only dirs it created (each carries a `.cf-retained` marker), so pointing this at a shared directory never touches unrelated content — though a dedicated dir is still recommended. An override on a different filesystem than the config home falls back to copy-then-remove. |
 

package/dist/agent-runner.js

@@ -1,6 +1,6 @@
 import { spawn } from 'node:child_process';
 import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
-import { homedir, tmpdir } from 'node:os';
+import { tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { claudeAssistantContent, claudeCallUsage, isObject, numberOf, redactBody, } from './claude-stream.js';
 import { createCallMetricPublisher, publishCallMetric, } from './pi.js';
@@ -323,14 +323,14 @@ export async function runClaudeCode(opts) {
         await assertOnboardingKeysCurrent(configHome, process.env.CLAUDE_CLI_VERSION, opts.log);
     }
     // Repo-sourced Claude Skill (slice 2): install it as a native skill under the config dir's
-    // `skills/<name>/` so the CLI discovers and can invoke it. Written to the isolated per-run
-    // config home when present, else the developer's `~/.claude` (ambient/native mode). Best-effort:
-    // a write failure must not wedge the run — the prompt still names the skill.
-    if (opts.skill) {
-        const skillsRoot = configHome
-            ? join(configHome, 'skills')
-            : join(homedir(), '.claude', 'skills');
-        await writeNativeSkill(skillsRoot, opts.skill).catch(() => { });
+    // `skills/<name>/` so the CLI discovers and can invoke it. ONLY into the isolated per-run config
+    // home — never the developer's own `~/.claude` (ambient/native mode), where it would persist in
+    // their personal setup after the run and two concurrent jobs carrying same-named skills from
+    // different repos would clobber each other. An ambient run reads the skill from the checkout
+    // instead (`.cat-context/skill/`, materialised by the caller). Best-effort: a write failure must
+    // not wedge the run — the prompt still names the skill.
+    if (opts.skill && configHome) {
+        await writeNativeSkill(join(configHome, 'skills'), opts.skill).catch(() => { });
     }
     const env = buildClaudeEnv(opts, configHome);
     // ADR 0026 D3 (path corrected by ADR 0027 Defect A): while the run is live, tail the CLI's
@@ -402,9 +402,12 @@ export async function runClaudeCode(opts) {
  * keep its cyclomatic complexity down; behaviour is a straight move of the original expression.
  */
 function buildClaudeEnv(opts, configHome) {
+    // The job-scoped env rides along in BOTH modes; the credential/config vars below are what
+    // ambient mode drops (the developer's own logged-in `~/.claude` is used instead).
     if (opts.ambientAuth)
-        return {};
+        return { ...opts.extraEnv };
     return {
+        ...opts.extraEnv,
         CLAUDE_CONFIG_DIR: configHome,
         ...(opts.subscriptionBaseUrl
             ? {
@@ -574,7 +577,7 @@ export async function runCodex(opts) {
                 opts.model,
                 '-',
             ],
-        }, prompt, opts, codexHome ? { CODEX_HOME: codexHome } : {}, opts.subscriptionToken ? secretsToRedact(opts.subscriptionToken) : [], onEvent);
+        }, prompt, opts, { ...opts.extraEnv, ...(codexHome ? { CODEX_HOME: codexHome } : {}) }, opts.subscriptionToken ? secretsToRedact(opts.subscriptionToken) : [], onEvent);
         // Fallback for a CLI/version that never emits per-turn `last_token_usage`: record a
         // single call from the cumulative total + final text so the run is still observable.
         if (calls.length === 0 && (usage || summary)) {

package/dist/agent.js

@@ -8,6 +8,7 @@ import { configurePackageRegistries } from './package-registries.js';
 import { captureRedactedOutput, redactSecrets, registerKnownSecrets } from './redact.js';
 import { cloneRepo, commitAll, conflictDiff, fetchPullRequestHead, fetchReferenceBranches, hasAgentChanges, headCommit, inferVcsProvider, mergeBranch, openPullRequest, prepareExistingCheckout, pushBranch, reinitAndPush, unmergedPaths, } from './git.js';
 import { makeDirClaimer, noChangesReason, runCodingAgent, runMultiRepoCoding, } from './coding-agent.js';
+import { validationFailureMessage } from './validation-checks.js';
 import { acquireRepoCheckout, agentNeverActed, agentOutputTail, NEVER_ACTED_CAUSE, runAgentInWorkspace, unusableFinalAnswerCause, withWorkspace, } from './pi-workspace.js';
 import { diagnosticsSuffix, resolveStructuredOutput, } from './structured-output.js';
 import { log } from './logger.js';
@@ -96,12 +97,12 @@ async function standUpInfra(dir, infra, signal, logger) {
  * `package.json` / `outputDir` / `mocks/` all live under the service subtree, so installing,
  * building, serving and seeding WireMock from the root would target the wrong directory.
  */
-async function manageInfra(dir, workDir, infra, signal, onActivity, logger) {
+async function manageInfra(dir, workDir, infra, opts, logger) {
     if (infra.kind === 'frontend') {
         // `onActivity` feeds the inactivity watchdog through the frontend build/serve stand-up,
         // which (unlike docker-compose's 5-min-capped `up`) can run past the inactivity window.
         // Runs in `workDir` so a monorepo frontend builds/serves from its own package subtree.
-        const fe = await standUpFrontend(workDir, infra, signal, onActivity, logger);
+        const fe = await standUpFrontend(workDir, infra, opts, logger);
         return {
             ...(fe.note ? { note: fe.note } : {}),
             ...(fe.serveUrl ? { serveUrl: fe.serveUrl } : {}),
@@ -109,7 +110,7 @@ async function manageInfra(dir, workDir, infra, signal, onActivity, logger) {
             cleanup: () => tearDownFrontend(fe.processes, logger),
         };
     }
-    const standUp = await standUpInfra(dir, infra, signal, logger);
+    const standUp = await standUpInfra(dir, infra, opts.signal, logger);
     return {
         ...(standUp.note ? { note: standUp.note } : {}),
         ...(standUp.record ? { record: standUp.record } : {}),
@@ -238,14 +239,39 @@ function mergeEffort(result, effortReport) {
 }
 /** Run one generic agent job end to end, dispatching on `mode`. */
 export async function handleAgent(job, opts = {}) {
-    // Private-registry auth first, before any mode runs: every mode with a checkout may
-    // install dependencies (the agent's own shell and the frontend-infra stand-up both
-    // inherit `HOME`, so they all read the written ~/.npmrc). A job with no entries
-    // clears any stale ~/.npmrc from a prior job on a reused (warm-pool) container.
-    await configurePackageRegistries(job.packageRegistries);
-    if (job.mode === 'preview')
-        return runPreviewMode(job, opts);
-    return job.mode === 'coding' ? runCodingMode(job, opts) : runExploreMode(job, opts);
+    // An `ambientAuth` job runs in the SHARED native host process on the developer's own HOME
+    // (see `LocalProcessRunnerTransport`), so anything this job would otherwise write to a
+    // process- or HOME-global gets a per-job directory instead — it can't corrupt the
+    // developer's files, and concurrent jobs can't race on them.
+    const scopeDir = job.ambientAuth ? await mkdtemp(join(tmpdir(), 'cf-jobenv-')) : undefined;
+    try {
+        // Private-registry auth first, before any mode runs: every mode with a checkout may
+        // install dependencies (the agent's own shell and the frontend-infra stand-up both
+        // inherit this env, so they all read the written npmrc). In a container a job with no
+        // entries clears any stale ~/.npmrc from a prior job on a reused (warm-pool) container.
+        const registryEnv = await configurePackageRegistries(job.packageRegistries, scopeDir ? { isolatedDir: scopeDir } : {});
+        const scoped = withAgentEnv(opts, registryEnv);
+        if (job.mode === 'preview')
+            return await runPreviewMode(job, scoped);
+        return job.mode === 'coding'
+            ? await runCodingMode(job, scoped)
+            : await runExploreMode(job, scoped);
+    }
+    finally {
+        if (scopeDir)
+            await rm(scopeDir, { recursive: true, force: true }).catch(() => { });
+    }
+}
+/**
+ * Layer extra child-process env onto a job's {@link RunOptions}. The agent CLI is spawned with
+ * `{...process.env, ...agentEnv}`, so this is how per-job values reach the agent (and the shell
+ * tools it spawns) WITHOUT mutating the harness's own `process.env` — which is shared by every
+ * concurrent job when the harness runs as a native host process. Empty `env` ⇒ `opts` unchanged.
+ */
+function withAgentEnv(opts, env) {
+    if (Object.keys(env).length === 0)
+        return opts;
+    return { ...opts, agentEnv: { ...opts.agentEnv, ...env } };
 }
 /**
  * Decide a preview stand-up's outcome from its result (pure, so the success/failure boundary
@@ -300,7 +326,7 @@ async function runPreviewMode(job, opts) {
         logger.info('agent(preview): building + serving', {
             serviceDirectory: job.repo.serviceDirectory,
         });
-        const fe = await standUpFrontend(workDir, infra, opts.signal, opts.onActivity, logger);
+        const fe = await standUpFrontend(workDir, infra, opts, logger);
         const infraSetupFields = fe.record
             ? { infraSetup: fe.record }
             : {};
@@ -332,30 +358,23 @@ async function runPreviewMode(job, opts) {
     }
 }
 /**
- * Inject the tester's sensitive secrets into the PROCESS environment so the agent's shell tools
- * (spawned as child processes that inherit this env) can read `$KEY` — the out-of-band delivery
- * channel. Each value is registered for redaction so it can't leak into captured output/logs.
- * Returns a restore closure that puts the environment back afterward (warm-pool hygiene, so a
- * later job on a reused container never inherits a prior run's secrets). Reserved/toolchain env
- * names were already dropped at parse. A no-op when there are no secrets.
+ * Build the env carrying the tester's sensitive secrets, so the agent's shell tools (spawned as
+ * child processes that inherit it) can read `$KEY` — the out-of-band delivery channel. Each value
+ * is registered for redaction so it can't leak into captured output/logs. Reserved/toolchain env
+ * names were already dropped at parse. No secrets ⇒ an empty env.
+ *
+ * Returned as EXPLICIT child env rather than written onto `process.env`: a process-global
+ * set/restore is only safe when the process runs one job, which the native host-process transport
+ * breaks (it serves every concurrent ambient job from one process). There, two overlapping tester
+ * runs would read each other's secrets, and whichever finished first would delete the other's
+ * mid-run. Scoping them to the spawn env makes the delivery correct under concurrency and drops
+ * the restore step entirely.
  */
-function applyTestSecrets(secrets) {
+export function testSecretEnv(secrets) {
     if (!secrets?.length)
-        return () => { };
+        return {};
     registerKnownSecrets(secrets.map((s) => s.value));
-    const previous = new Map();
-    for (const { key, value } of secrets) {
-        previous.set(key, process.env[key]);
-        process.env[key] = value;
-    }
-    return () => {
-        for (const [key, prior] of previous) {
-            if (prior === undefined)
-                delete process.env[key];
-            else
-                process.env[key] = prior;
-        }
-    };
+    return Object.fromEntries(secrets.map(({ key, value }) => [key, value]));
 }
 /**
  * Read-only exploration: clone `branch`, run the agent making no edits, and return its
@@ -442,9 +461,7 @@ async function runExploreMode(job, opts) {
         // The run-mode guidance itself lives in the backend-composed system/user prompt; the
         // harness only manages the lifecycle + this dynamic stand-up note.
         const infra = job.infra;
-        const managed = infra
-            ? await manageInfra(dir, workDir, infra, opts.signal, opts.onActivity, logger)
-            : undefined;
+        const managed = infra ? await manageInfra(dir, workDir, infra, opts, logger) : undefined;
         // Fold the stand-up outcome into the agent prompt: a stand-up problem (build/compose
         // failure) is flagged as a concern; a frontend serve URL points the UI tester at the
         // app it just built + served (the backend env resolution already reached the harness).
@@ -458,10 +475,10 @@ async function runExploreMode(job, opts) {
         const infraSetupFields = managed?.record
             ? { infraSetup: managed.record }
             : {};
-        // Inject the tester's sensitive secrets into the environment (out of band) so the agent's
-        // shell can read them as `$KEY`; restore afterwards so a reused (warm-pool) container never
-        // leaks them to a later job. A no-op for non-tester runs (no `testSecrets`).
-        const restoreSecrets = applyTestSecrets(job.testSecrets);
+        // Hand the tester's sensitive secrets to the agent's child process (out of band) so its
+        // shell can read them as `$KEY`. Scoped to this job's env, so a concurrent job in the same
+        // harness process never sees them. A no-op for non-tester runs (no `testSecrets`).
+        const agentOpts = withAgentEnv(opts, testSecretEnv(job.testSecrets));
         try {
             opts.onPhase?.('agent');
             logger.info('agent(explore): running agent', { serviceDirectory });
@@ -484,11 +501,10 @@ async function runExploreMode(job, opts) {
                 webSearchProxy: job.webSearch,
                 contextFiles: job.contextFiles,
                 guardLimits: job.guardLimits,
-            }, opts);
+            }, agentOpts);
             return mergeEffort(await finalizeExploreResult(job, { summary, stats, stderrTail, usage, callMetrics, runDiag }, { infra, infraSetupFields, logger, signal: opts.signal }), effortReport);
         }
         finally {
-            restoreSecrets();
             if (managed)
                 await managed.cleanup();
         }
@@ -787,6 +803,11 @@ function buildSingleRepoCodingSpec(job, pushBranch) {
                 },
             }
             : {}),
+        // 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 } : {}),
     };
 }
 /**
@@ -797,12 +818,38 @@ function buildSingleRepoCodingSpec(job, pushBranch) {
  */
 async function runSingleRepoCoding(job, opts) {
     const pushBranch = job.pushBranch ?? job.newBranch ?? job.branch;
-    const { summary, stats, stderrTail, pushed, usage, callMetrics, validation, 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.
         if (job.noChangesIsError === false) {
@@ -814,6 +861,7 @@ async function runSingleRepoCoding(job, opts) {
                 ...(usage ? { usage } : {}),
                 ...(callMetrics ? { callMetrics } : {}),
                 ...ralphVerdict,
+                ...validationFields,
                 ...effort,
             };
         }
@@ -826,6 +874,7 @@ async function runSingleRepoCoding(job, opts) {
             failureCause: 'no-changes',
             ...(usage ? { usage } : {}),
             ...(callMetrics ? { callMetrics } : {}),
+            ...validationFields,
             ...effort,
         };
     }
@@ -859,6 +908,7 @@ async function runSingleRepoCoding(job, opts) {
                     stats,
                     ...(usage ? { usage } : {}),
                     ...(callMetrics ? { callMetrics } : {}),
+                    ...validationFields,
                     ...effort,
                 };
             }
@@ -871,6 +921,7 @@ async function runSingleRepoCoding(job, opts) {
                 failureCause: 'no-changes',
                 ...(usage ? { usage } : {}),
                 ...(callMetrics ? { callMetrics } : {}),
+                ...validationFields,
                 ...effort,
             };
         }
@@ -883,6 +934,7 @@ async function runSingleRepoCoding(job, opts) {
             ...(usage ? { usage } : {}),
             ...(callMetrics ? { callMetrics } : {}),
             ...ralphVerdict,
+            ...validationFields,
             ...effort,
         };
     }
@@ -894,6 +946,7 @@ async function runSingleRepoCoding(job, opts) {
         ...(usage ? { usage } : {}),
         ...(callMetrics ? { callMetrics } : {}),
         ...ralphVerdict,
+        ...validationFields,
         ...effort,
     };
 }

package/dist/coding-agent.js

@@ -8,6 +8,7 @@ import { FOLLOW_UPS_FILENAME, FollowUpTailer } from './follow-ups.js';
 import { EFFORT_REPORT_FILE } from './effort.js';
 import { acquireRepoCheckout, agentNeverActed, agentOutputTail, runAgentInWorkspace, withWorkspace, } from './pi-workspace.js';
 import { log } from './logger.js';
+import { runValidationLoop, } from './validation-checks.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
@@ -128,28 +129,57 @@ export async function runCodingAgent(spec, opts = {}) {
             }, followUpPollIntervalMs());
             followUpTick.unref?.();
         }
+        // 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) => runAgentInWorkspace({
+            dir: workDir,
+            systemPrompt: spec.systemPrompt,
+            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,
+            ...(spec.skill ? { skill: spec.skill } : {}),
+        }, opts);
         let outcome;
         try {
             opts.onPhase?.('agent');
             logger.info('coding-agent: running agent', { serviceDirectory });
-            const agentRun = 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,
-                ...(spec.skill ? { skill: spec.skill } : {}),
-            }, opts);
+            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;
+            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,
@@ -284,7 +314,7 @@ async function prepareCodingCheckout(dir, spec, logger, opts) {
  * {@link runCodingAgent} so its body stays small; returns the built {@link CodingAgentOutcome}.
  */
 async function finalizeCodingRun(args) {
-    const { dir, spec, logger, opts, baseSha, resumed, workDir, checkpoint, followUpTick, followUpTailer, pushWorkOnce, inFlightPush, agentRun, } = args;
+    const { validationReport, dir, spec, logger, opts, baseSha, resumed, workDir, checkpoint, followUpTick, followUpTailer, pushWorkOnce, inFlightPush, agentRun, } = args;
     const { signal } = opts;
     const { summary, stats, stderrTail, usage, callMetrics, effortReport } = agentRun;
     let outcome;
@@ -368,8 +398,63 @@ 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, spec, baseSha, resumed, opts) {
+    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(previous, next) {
+    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).
@@ -401,6 +486,10 @@ async function runRalphValidation(cwd, validation, logger, opts) {
             cwd,
             detached: spawnDetached,
             stdio: ['ignore', 'pipe', 'pipe'],
+            // The job's own env (see `RunOptions.agentEnv`): a validation command typically installs
+            // before it tests, and this is spawned by the HARNESS rather than the agent, so it does not
+            // otherwise inherit the job's private-registry npmrc pointer on the native path.
+            env: { ...process.env, ...opts.agentEnv },
         });
         // Keep only the tail; guard against unbounded buffering on a chatty command.
         const capture = (chunk) => {

package/dist/frontend-infra.js

@@ -56,7 +56,8 @@ function guardProcess(child, label, logger) {
  * the agent as a prompt note (and captured on the record) rather than failing the job — the
  * agent then reports the gap as a concern. Every path returns the processes to tear down.
  */
-export async function standUpFrontend(dir, infra, signal, onActivity, logger = log) {
+export async function standUpFrontend(dir, infra, run, logger = log) {
+    const { signal, onActivity } = run;
     const startedAt = Date.now();
     const processes = [];
     // The frontend app's directory: the checkout root, or a monorepo subdirectory when the config
@@ -94,6 +95,11 @@ export async function standUpFrontend(dir, infra, signal, onActivity, logger = l
         };
     };
     const buildEnv = (infra.envInjection ?? DEFAULTS.envInjection) === 'build' ? (infra.env ?? {}) : {};
+    // The job's own env (see `RunOptions.agentEnv`) — today the private-registry npmrc pointer.
+    // The stand-up is spawned by the HARNESS, not by the agent, so it does not inherit whatever the
+    // agent's CLI child was given: without this the install here would miss the job's registry auth
+    // on the native path, where the npmrc is per-job rather than the process's `~/.npmrc`.
+    const jobEnv = run.agentEnv ?? {};
     try {
         // 1) Install dependencies.
         const install = installCommand(infra);
@@ -103,6 +109,7 @@ export async function standUpFrontend(dir, infra, signal, onActivity, logger = l
             signal,
             timeout: 8 * 60_000,
             maxBuffer: 16 * 1024 * 1024,
+            env: { ...process.env, ...jobEnv },
         });
         pushOutput(installed.stdout, installed.stderr);
         // 2) Build (build-time env injected here; runtime injection writes a shim after).
@@ -114,7 +121,7 @@ export async function standUpFrontend(dir, infra, signal, onActivity, logger = l
             signal,
             timeout: 12 * 60_000,
             maxBuffer: 16 * 1024 * 1024,
-            env: { ...process.env, ...buildEnv },
+            env: { ...process.env, ...jobEnv, ...buildEnv },
         });
         pushOutput(built.stdout, built.stderr);
         // Runtime injection: write a `window.env` shim into the build output the app can load