@cat-factory/executor-harness 1.52.0 → 1.54.0

package/src/agent.ts

@@ -155,8 +155,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 +167,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 +175,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 +323,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 +416,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 +448,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 +556,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 +571,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 +608,7 @@ async function runExploreMode(job: AgentJob, opts: RunOptions): Promise<AgentRes
             contextFiles: job.contextFiles,
             guardLimits: job.guardLimits,
           },
-          opts,
+          agentOpts,
         )
 
         return mergeEffort(
@@ -602,7 +620,6 @@ async function runExploreMode(job: AgentJob, opts: RunOptions): Promise<AgentRes
           effortReport,
         )
       } finally {
-        restoreSecrets()
         if (managed) await managed.cleanup()
       }
     },

package/src/coding-agent.ts

@@ -105,8 +105,9 @@ export interface CodingAgentSpec extends HarnessAuthFields {
   validation?: { command: string; iteration?: number }
   /**
    * 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
 }
@@ -602,6 +603,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)
 

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.
  */