@cat-factory/executor-harness 1.52.2 → 1.56.0

package/src/agent-runner.ts

@@ -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,
@@ -81,8 +81,9 @@ export interface SubscriptionRunOptions {
   /**
    * A repo-sourced Claude Skill to install natively before launch (repo-sourced Claude Skills,
    * slice 2). The claude-code runner writes it to `CLAUDE_CONFIG_DIR/skills/<name>/SKILL.md`
-   * (+ resource files) so the CLI loads it; the codex runner ignores it (codex reads the
-   * checkout's `.cat-context/skill/`, materialised by the caller). Absent ⇒ no skill installed.
+   * (+ resource files) so the CLI loads it — but ONLY when it owns an isolated config home, i.e.
+   * NOT under `ambientAuth`. The codex runner ignores it outright. Every case that skips the
+   * native install reads the checkout's `.cat-context/skill/`, materialised by the caller.
    */
   skill?: {
     name: string
@@ -90,6 +91,14 @@ export interface SubscriptionRunOptions {
     instructions: string
     resources: { relPath: string; content: string }[]
   }
+  /**
+   * Extra environment for the CLI child, scoped to this job (the tester's secrets, a
+   * private-registry npmrc pointer). Merged over the inherited `process.env` at spawn, so the
+   * agent and its shell tools see them without the harness mutating its OWN environment — which
+   * is shared by every concurrent job under the native host-process transport. See
+   * `RunOptions.agentEnv`.
+   */
+  extraEnv?: Record<string, string>
   /** Aborting this kills the CLI (the job's inactivity/max-duration watchdog). */
   signal?: AbortSignal
   /** Called on every chunk of CLI output, so the watchdog sees the agent is alive. */
@@ -449,14 +458,14 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
   }
 
   // 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)
@@ -542,8 +551,11 @@ function buildClaudeEnv(
   opts: SubscriptionRunOptions,
   configHome: string | undefined,
 ): Record<string, string> {
-  if (opts.ambientAuth) return {}
+  // 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 { ...opts.extraEnv }
   return {
+    ...opts.extraEnv,
     CLAUDE_CONFIG_DIR: configHome!,
     ...(opts.subscriptionBaseUrl
       ? {
@@ -738,7 +750,7 @@ export async function runCodex(opts: SubscriptionRunOptions): Promise<PiRunOutco
       },
       prompt,
       opts,
-      codexHome ? { CODEX_HOME: codexHome } : {},
+      { ...opts.extraEnv, ...(codexHome ? { CODEX_HOME: codexHome } : {}) },
       opts.subscriptionToken ? secretsToRedact(opts.subscriptionToken) : [],
       onEvent,
     )

package/src/agent.ts

@@ -38,6 +38,7 @@ import {
   runCodingAgent,
   runMultiRepoCoding,
 } from './coding-agent.js'
+import { validationFailureMessage } from './validation-checks.js'
 import {
   acquireRepoCheckout,
   agentNeverActed,
@@ -155,8 +156,7 @@ async function manageInfra(
   dir: string,
   workDir: string,
   infra: AgentInfraSpec,
-  signal: AbortSignal | undefined,
-  onActivity: (() => void) | undefined,
+  opts: RunOptions,
   logger: Logger,
 ): Promise<{
   note?: string
@@ -168,7 +168,7 @@ async function manageInfra(
     // `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 } : {}),
@@ -176,7 +176,7 @@ async function manageInfra(
       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 } : {}),
@@ -324,13 +324,39 @@ function mergeEffort(result: AgentResult, effortReport: EffortReport | undefined
 
 /** Run one generic agent job end to end, dispatching on `mode`. */
 export async function handleAgent(job: AgentJob, opts: RunOptions = {}): Promise<AgentResult> {
-  // 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: RunOptions, env: Record<string, string>): RunOptions {
+  if (Object.keys(env).length === 0) return opts
+  return { ...opts, agentEnv: { ...opts.agentEnv, ...env } }
 }
 
 /**
@@ -391,7 +417,7 @@ async function runPreviewMode(job: AgentJob, opts: RunOptions): Promise<AgentRes
     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: { infraSetup?: InfraSetupRecord } = fe.record
       ? { infraSetup: fe.record }
       : {}
@@ -423,27 +449,22 @@ async function runPreviewMode(job: AgentJob, opts: RunOptions): Promise<AgentRes
 }
 
 /**
- * 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: TestSecretSpec[] | undefined): () => void {
-  if (!secrets?.length) return () => {}
+export function testSecretEnv(secrets: TestSecretSpec[] | undefined): Record<string, string> {
+  if (!secrets?.length) return {}
   registerKnownSecrets(secrets.map((s) => s.value))
-  const previous = new Map<string, string | undefined>()
-  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]))
 }
 
 /**
@@ -536,9 +557,7 @@ async function runExploreMode(job: AgentJob, opts: RunOptions): Promise<AgentRes
       // 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).
@@ -553,10 +572,10 @@ async function runExploreMode(job: AgentJob, opts: RunOptions): Promise<AgentRes
         ? { 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')
@@ -590,7 +609,7 @@ async function runExploreMode(job: AgentJob, opts: RunOptions): Promise<AgentRes
             contextFiles: job.contextFiles,
             guardLimits: job.guardLimits,
           },
-          opts,
+          agentOpts,
         )
 
         return mergeEffort(
@@ -602,7 +621,6 @@ async function runExploreMode(job: AgentJob, opts: RunOptions): Promise<AgentRes
           effortReport,
         )
       } finally {
-        restoreSecrets()
         if (managed) await managed.cleanup()
       }
     },
@@ -949,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 } : {}),
   }
 }
 
@@ -960,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.
@@ -979,6 +1038,7 @@ async function runSingleRepoCoding(job: AgentJob, opts: RunOptions): Promise<Age
         ...(usage ? { usage } : {}),
         ...(callMetrics ? { callMetrics } : {}),
         ...ralphVerdict,
+        ...validationFields,
         ...effort,
       }
     }
@@ -991,6 +1051,7 @@ async function runSingleRepoCoding(job: AgentJob, opts: RunOptions): Promise<Age
       failureCause: 'no-changes',
       ...(usage ? { usage } : {}),
       ...(callMetrics ? { callMetrics } : {}),
+      ...validationFields,
       ...effort,
     }
   }
@@ -1025,6 +1086,7 @@ async function runSingleRepoCoding(job: AgentJob, opts: RunOptions): Promise<Age
           stats,
           ...(usage ? { usage } : {}),
           ...(callMetrics ? { callMetrics } : {}),
+          ...validationFields,
           ...effort,
         }
       }
@@ -1041,6 +1103,7 @@ async function runSingleRepoCoding(job: AgentJob, opts: RunOptions): Promise<Age
         failureCause: 'no-changes',
         ...(usage ? { usage } : {}),
         ...(callMetrics ? { callMetrics } : {}),
+        ...validationFields,
         ...effort,
       }
     }
@@ -1053,6 +1116,7 @@ async function runSingleRepoCoding(job: AgentJob, opts: RunOptions): Promise<Age
       ...(usage ? { usage } : {}),
       ...(callMetrics ? { callMetrics } : {}),
       ...ralphVerdict,
+      ...validationFields,
       ...effort,
     }
   }
@@ -1064,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,10 +108,20 @@ 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 (native `~/.claude/skills`
-   * for claude-code, `.cat-context/skill/` for Pi/codex). Absent ⇒ no skill.
+   * into {@link runAgentInWorkspace}, which installs it harness-aware: natively under the ISOLATED
+   * `CLAUDE_CONFIG_DIR` for a leased-credential claude-code run, `.cat-context/skill/` for everything
+   * else (Pi, codex, and ambient claude-code, which has no isolated config dir). Absent ⇒ no skill.
    */
   skill?: SkillSpec
 }
@@ -137,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
 }
 
 /**
@@ -270,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,
@@ -294,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,
@@ -443,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
@@ -458,6 +514,7 @@ async function finalizeCodingRun(args: {
   agentRun: Awaited<ReturnType<typeof runAgentInWorkspace>>
 }): Promise<CodingAgentOutcome> {
   const {
+    validationReport,
     dir,
     spec,
     logger,
@@ -557,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).
@@ -602,6 +724,10 @@ async function runRalphValidation(
       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: Buffer): void => {

package/src/frontend-infra.ts

@@ -3,6 +3,7 @@ import { promisify } from 'node:util'
 import { writeFile } from 'node:fs/promises'
 import { join } from 'node:path'
 import type { FrontendInfraSpec, InfraSetupRecord } from './job.js'
+import type { RunOptions } from './runner.js'
 import { killChildProcess } from './process.js'
 import { pathExists } from './fs-utils.js'
 import { captureRedactedOutput, redactSecrets } from './redact.js'
@@ -77,10 +78,10 @@ function guardProcess(child: ChildProcess, label: string, logger: Logger): Child
 export async function standUpFrontend(
   dir: string,
   infra: FrontendInfraSpec,
-  signal: AbortSignal | undefined,
-  onActivity: (() => void) | undefined,
+  run: Pick<RunOptions, 'signal' | 'onActivity' | 'agentEnv'>,
   logger: Logger = log,
 ): Promise<FrontendStandUp> {
+  const { signal, onActivity } = run
   const startedAt = Date.now()
   const processes: ChildProcess[] = []
   // The frontend app's directory: the checkout root, or a monorepo subdirectory when the config
@@ -118,6 +119,11 @@ export async function standUpFrontend(
 
   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.
@@ -128,6 +134,7 @@ export async function standUpFrontend(
       signal,
       timeout: 8 * 60_000,
       maxBuffer: 16 * 1024 * 1024,
+      env: { ...process.env, ...jobEnv },
     })
     pushOutput(installed.stdout, installed.stderr)
 
@@ -140,7 +147,7 @@ export async function standUpFrontend(
       signal,
       timeout: 12 * 60_000,
       maxBuffer: 16 * 1024 * 1024,
-      env: { ...process.env, ...buildEnv },
+      env: { ...process.env, ...jobEnv, ...buildEnv },
     })
     pushOutput(built.stdout, built.stderr)