@cat-factory/executor-harness 1.52.0 → 1.54.0

package/README.md

@@ -65,6 +65,44 @@ 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,6 +124,7 @@ 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/logger.ts`    | Structured logging.                                                                                     |

package/dist/agent-runner.js

@@ -1,12 +1,13 @@
 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';
 import { killChildProcess, spawnDetached } from './process.js';
 import { redact, secretsToRedact } from './redact.js';
-import { createSliceTracker, pickProgress, startSubagentWatcher } from './subagents.js';
+import { createSliceTracker, startSubagentWatcher } from './subagents.js';
+import { createTaskPlanTracker, normalizeStatus, pickProgress, toProgress, todosToProgress, } from './progress.js';
 import { assertOnboardingKeysCurrent, writeOnboardingPreseed } from './onboarding-preseed.js';
 import { retainSessionTranscripts } from './transcript-retention.js';
 /**
@@ -224,18 +225,24 @@ export async function runClaudeCode(opts) {
     // may still rewrite below (a published call must be final — see the publisher).
     const publisher = createCallMetricPublisher(calls, opts.onCallMetric);
     // ADR 0026 D2.1 + ADR 0027 Defect B: surface live slice progress from TWO reconciled
-    // sources. The parent's `Task` dispatches + their terminal tool_results DO appear on this
+    // sources. The parent's subagent dispatches + their terminal tool_results DO appear on this
     // stream (only a subagent's intermediate turns don't), so `sliceTracker` derives per-slice
-    // progress for the parallel-subagent shape; a parent `TodoWrite` plan (the sequential
-    // shape) is tracked in `lastTodo`. `pickProgress` picks whichever is further along on each
-    // update, so neither masks the other — the pr-reviewer prompt writes its todo plan ONCE
-    // and never marks it done, which used to gate the slice signal off and pin progress at 0%.
+    // progress for the parallel shape; the parent's own plan (the sequential shape) is tracked
+    // by `planTracker` + `lastTodo`. `pickProgress` picks whichever is further along on each
+    // update, so neither masks the other — the pr-reviewer prompt writes its plan ONCE and never
+    // marks it done, which used to gate the slice signal off and pin progress at 0%.
+    //
+    // The plan arrives in one of two tool vocabularies depending on the bundled CLI build:
+    // `TodoWrite` (whole-list snapshots, tracked in `lastTodo`) or the incremental
+    // `TaskCreate`/`TaskUpdate` pair (tracked by `planTracker`, which needs the tool RESULTS too
+    // because the task id is minted there). Both are read — see ./progress.ts.
     const sliceTracker = createSliceTracker();
+    const planTracker = createTaskPlanTracker();
     let lastTodo;
     const emitProgress = () => {
         if (!opts.onProgress)
             return;
-        const progress = pickProgress(lastTodo, sliceTracker.progress());
+        const progress = pickProgress(pickProgress(lastTodo, planTracker.progress()), sliceTracker.progress());
         if (progress)
             opts.onProgress(progress);
     };
@@ -255,6 +262,7 @@ export async function runClaudeCode(opts) {
                 }
             }
             sliceTracker.onAssistant(content);
+            planTracker.onAssistant(content);
             emitProgress();
             // Record this call BEFORE appending its turn: the prompt is the history that
             // produced this response. The append-only array keeps each call's prompt a strict
@@ -278,6 +286,7 @@ export async function runClaudeCode(opts) {
             const content = event.message.content;
             if (Array.isArray(content)) {
                 sliceTracker.onUser(content);
+                planTracker.onUser(content);
                 emitProgress();
                 messages.push({ role: 'tool', content });
             }
@@ -314,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
@@ -393,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
             ? {
@@ -442,25 +454,6 @@ async function assembleClaudeOutcome(args) {
         ...(mergedCalls.length ? { callMetrics: mergedCalls } : {}),
     };
 }
-/** Map Claude Code's `TodoWrite` todos array onto subtask counts. */
-function todosToProgress(todos) {
-    if (!Array.isArray(todos))
-        return undefined;
-    const items = todos.filter(isObject).map((t) => ({
-        label: typeof t.content === 'string' ? t.content : String(t.content ?? ''),
-        status: normalizeStatus(t.status),
-    }));
-    const completed = items.filter((i) => i.status === 'completed').length;
-    const inProgress = items.filter((i) => i.status === 'in_progress').length;
-    return { completed, inProgress, total: items.length, items };
-}
-function normalizeStatus(status) {
-    if (status === 'completed')
-        return 'completed';
-    if (status === 'in_progress')
-        return 'in_progress';
-    return 'pending';
-}
 function claudeUsage(raw) {
     if (!isObject(raw))
         return undefined;
@@ -584,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)) {
@@ -670,9 +663,7 @@ function codexPlanProgress(event) {
     }));
     if (items.length === 0)
         return undefined;
-    const completed = items.filter((i) => i.status === 'completed').length;
-    const inProgress = items.filter((i) => i.status === 'in_progress').length;
-    return { completed, inProgress, total: items.length, items };
+    return toProgress(items);
 }
 /**
  * Best-effort: pull token usage out of a Codex usage event. Codex `exec --json`

package/dist/agent.js

@@ -96,12 +96,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 +109,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 +238,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 +325,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 +357,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 +460,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 +474,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 +500,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();
         }

package/dist/coding-agent.js

@@ -401,6 +401,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

package/dist/package-registries.js

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

package/dist/pi-workspace.js

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

package/dist/pi.js

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