@cat-factory/executor-harness 1.52.2 → 1.56.0

package/src/job.ts

@@ -2,6 +2,7 @@ import type { HarnessCallMetric, PiRunStats } from './pi.js'
 import type { HarnessKind } from './pi-workspace.js'
 import type { FailureCause } from './failure.js'
 import type { EffortReport } from './effort.js'
+import type { ValidationChecksSpec, ValidationReport } from './validation-checks.js'
 
 // The job the Worker's ContainerAgentExecutor POSTs to /run. Kept as plain
 // types with a hand-rolled validator so the image needs no schema dependency.
@@ -174,6 +175,38 @@ function parseValidationSpec(value: unknown): ValidationSpec | undefined {
   }
 }
 
+/**
+ * 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: unknown): ValidationChecksSpec | undefined {
+  if (typeof value !== 'object' || value === null) return undefined
+  const o = value as Record<string, unknown>
+  if (!Array.isArray(o.checks)) return undefined
+  const checks: { label: string; command: string }[] = []
+  for (const raw of o.checks) {
+    if (typeof raw !== 'object' || raw === null) continue
+    const c = raw as Record<string, unknown>
+    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
@@ -831,8 +864,29 @@ export interface AgentJob extends HarnessAuthFields {
    * agent commits + pushes. Present only for a `ralph` iteration. See {@link ValidationSpec}.
    */
   validation?: ValidationSpec
+  /**
+   * Coding mode: the service's PRE-PR VALIDATION CHECKS — commands the harness runs against the
+   * checkout after the agent settles and BEFORE opening a PR, feeding a failure back to the agent
+   * until they pass or the budget is spent. Present only on a dispatch that opens a PR and whose
+   * service configured checks; absent ⇒ the run behaves exactly as before. Deliberately keyed off
+   * job DATA, not the agent kind. See {@link ValidationChecksSpec}.
+   */
+  validationChecks?: ValidationChecksSpec
 }
 
+/**
+ * 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
+
 /** Per-job, per-knob progress-guard overrides (see {@link AgentJob.guardLimits}). */
 export interface GuardLimitsSpec {
   maxToolCallsWithoutEdit?: number
@@ -876,6 +930,14 @@ export interface AgentResult {
    * — the failure-class artifact the orchestrator-side provisioning logs can't capture.
    */
   infraSetup?: InfraSetupRecord
+  /**
+   * The PRE-PR VALIDATION report: the outcome of running the service's configured check commands
+   * against the checkout after the agent settled and before opening a PR, plus how many repair
+   * rounds the harness spent. Present on BOTH outcomes — a passing report accompanies the opened
+   * PR (the captured proof), and a failing one accompanies the run's `error` (no PR was opened).
+   * Absent when the job carried no {@link AgentJob.validationChecks}.
+   */
+  validationReport?: ValidationReport
   /**
    * Preview mode: the in-container URL the built app is served at (e.g. `http://localhost:4173`).
    * This is NOT host-reachable on its own — the container runtime publishes the serve port to an
@@ -1282,6 +1344,7 @@ export function parseAgentJob(input: unknown): AgentJob {
     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')
@@ -1319,6 +1382,7 @@ interface ParsedAgentJobParts {
   testSecrets: ReturnType<typeof parseTestSecrets>
   guardLimits: ReturnType<typeof parseGuardLimits>
   validation: ReturnType<typeof parseValidationSpec>
+  validationChecks: ReturnType<typeof parseValidationChecksSpec>
   reviewPrNumber: number | undefined
 }
 
@@ -1371,6 +1435,7 @@ function assembleAgentJob(
     testSecrets,
     guardLimits,
     validation,
+    validationChecks,
     reviewPrNumber,
   } = parts
   const repo = (o.repo ?? {}) as Record<string, unknown>
@@ -1399,6 +1464,7 @@ function assembleAgentJob(
     ...(reviewPrNumber !== undefined ? { reviewPrNumber } : {}),
     ...(guardLimits ? { guardLimits } : {}),
     ...(validation ? { validation } : {}),
+    ...(validationChecks ? { validationChecks } : {}),
   }
 }
 

package/src/package-registries.ts

@@ -1,22 +1,47 @@
-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 type { PackageRegistrySpec } from './job.js'
 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.
+// 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 (the user npmrc, outside any checkout). */
+/** Where the per-job npm auth lands in a container (the user npmrc, outside any checkout). */
 export function npmrcPath(): string {
   return join(homedir(), '.npmrc')
 }
 
+/**
+ * Per-job isolation for the rendered npmrc. Set `isolatedDir` when the harness process is
+ * SHARED across concurrent jobs and its HOME is the developer's own — i.e. the local native
+ * host-process transport, which is exactly the set of jobs carrying `ambientAuth`. Absent ⇒
+ * the container default (`~/.npmrc`).
+ */
+export interface PackageRegistryScope {
+  /** A per-job directory (removed with the job) to hold this job's npmrc. */
+  isolatedDir?: string
+}
+
 /**
  * Render the job's registry entries as npmrc lines: each scope routed to its
  * registry, plus one `_authToken` credential line per distinct host.
@@ -39,20 +64,75 @@ export function renderNpmrc(entries: readonly PackageRegistrySpec[]): string {
 }
 
 /**
- * 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: readonly PackageRegistrySpec[] | undefined,
-): Promise<void> {
+  scope: PackageRegistryScope = {},
+): Promise<Record<string, string>> {
+  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 })
+  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: string,
+  entries: readonly PackageRegistrySpec[],
+): Promise<void> {
+  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: string): string[] {
+  const found: string[] = []
+  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/src/pi-workspace.ts

@@ -241,11 +241,13 @@ export async function runAgentInWorkspace(
   // 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)
   }
 
@@ -268,6 +270,7 @@ export async function runAgentInWorkspace(
       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,
@@ -293,9 +296,11 @@ export async function runAgentInWorkspace(
   //    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: Record<string, string> = spec.webSearchProxy
-    ? webSearchProxyEnv(proxyBaseUrl, sessionToken)
-    : {}
+  const extraEnv: Record<string, string> = {
+    ...(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)
   await writeAgentsContext(spec.systemPrompt, {
@@ -325,6 +330,20 @@ export async function runAgentInWorkspace(
   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: Pick<AgentRunSpec, 'harness' | 'ambientAuth'>,
+): boolean {
+  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/src/pi.ts

@@ -250,9 +250,10 @@ 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/src/runner.ts

@@ -1,5 +1,6 @@
 import { redactSecrets } from './redact.js'
 import type { FollowUpLine } from './follow-ups.js'
+import type { ValidationReport } from './validation-checks.js'
 import type { HarnessCallMetric, TodoProgress, ToolSpan } from './pi.js'
 import { log, type Logger } from './logger.js'
 import {
@@ -30,6 +31,13 @@ export interface RunOptions {
   onSpan?: (span: ToolSpan) => void
   /** Receives the forward-looking follow-up / question items the Coder streamed since the last poll. */
   onFollowUp?: (items: FollowUpLine[]) => void
+  /**
+   * Receives each completed PRE-PR VALIDATION attempt the moment the harness finishes running
+   * the service's check commands, so the backend can surface the repair loop LIVE ("lint failed,
+   * repairing — attempt 2 of 3") instead of only in the terminal result. Latest-wins (NOT a drain
+   * buffer): a published attempt is final, and the loop republishes a whole new one per round.
+   */
+  onValidationReport?: (report: ValidationReport) => void
   /**
    * Receives each per-call telemetry row the moment the agent's CLI stream yields it, so a
    * run's model calls reach `llm_call_metrics` WHILE it runs rather than only in its terminal
@@ -51,6 +59,17 @@ export interface RunOptions {
   onPhase?: (phase: string) => void
   /** A per-job child logger carrying the run's correlation fields (jobId, repo, branch, …). */
   log?: Logger
+  /**
+   * Extra environment for the agent's child process, scoped to THIS job. The CLI is spawned with
+   * `{...process.env, ...agentEnv}`, so these reach the agent and every shell tool it spawns.
+   *
+   * This is the seam for anything per-job that would otherwise be written to a process- or
+   * HOME-global (the tester's secrets, a private-registry npmrc pointer). Those globals are only
+   * per-job when the process is — true for a container, FALSE for the local native host-process
+   * transport, which serves every concurrent ambient job from one process on the developer's own
+   * HOME. Set it via `withAgentEnv`; never mutate `process.env` for a job.
+   */
+  agentEnv?: Record<string, string>
 }
 
 export type JobState = 'running' | 'done' | 'failed'
@@ -151,6 +170,13 @@ export interface JobView<TResult extends JobResultBase = JobResultBase> {
    * Absent on a job that produced output promptly (the overwhelming common case). Sticky once set.
    */
   coldStart?: { atMs: number; message: string }
+  /**
+   * The LATEST completed pre-PR validation attempt (see `docs/initiatives/pre-pr-validation.md`).
+   * Unlike {@link spans}/{@link followUps} this is NOT drain-on-read: it is a whole-value latest
+   * publish, so re-reading it on a later poll is harmless and a dropped poll loses nothing (the
+   * next round republishes). Absent for a job whose service configured no checks.
+   */
+  validationReport?: ValidationReport
 }
 
 interface JobEntry<TResult extends JobResultBase> extends JobView<TResult> {
@@ -414,6 +440,9 @@ export class JobRegistry<TJob = unknown, TResult extends JobResultBase = JobResu
         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