@cat-factory/executor-harness 1.37.2 → 1.39.2

package/dist/agent.js

@@ -5,7 +5,7 @@ import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 import { standUpFrontend, tearDownFrontend } from './frontend-infra.js';
 import { configurePackageRegistries } from './package-registries.js';
-import { captureRedactedOutput, redactSecrets } from './redact.js';
+import { captureRedactedOutput, redactSecrets, registerKnownSecrets } from './redact.js';
 import { cloneRepo, commitAll, conflictDiff, hasAgentChanges, headCommit, mergeBranch, openPullRequest, prepareExistingCheckout, pushBranch, reinitAndPush, unmergedPaths, } from './git.js';
 import { makeDirClaimer, noChangesReason, runCodingAgent, runMultiRepoCoding, } from './coding-agent.js';
 import { acquireRepoCheckout, agentNeverActed, agentOutputTail, NEVER_ACTED_CAUSE, runAgentInWorkspace, unusableFinalAnswerCause, withWorkspace, } from './pi-workspace.js';
@@ -323,6 +323,32 @@ async function runPreviewMode(job, opts) {
         throw err;
     }
 }
+/**
+ * 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.
+ */
+function applyTestSecrets(secrets) {
+    if (!secrets?.length)
+        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;
+        }
+    };
+}
 /**
  * Read-only exploration: clone `branch`, run the agent making no edits, and return its
  * prose report — or, when `output.kind==='structured'`, the parsed JSON object as
@@ -386,6 +412,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);
         try {
             opts.onPhase?.('agent');
             logger.info('agent(explore): running agent', { serviceDirectory });
@@ -412,6 +442,7 @@ async function runExploreMode(job, opts) {
             return await finalizeExploreResult(job, { summary, stats, stderrTail, usage, callMetrics, runDiag }, { infra, infraSetupFields, logger, signal: opts.signal });
         }
         finally {
+            restoreSecrets();
             if (managed)
                 await managed.cleanup();
         }
@@ -529,14 +560,19 @@ async function runMultiRepoExplore(job, opts) {
         { repo: job.repo, cloneBranch: job.branch, ghToken: job.ghToken },
         ...peers.map((peer) => ({
             repo: peer.repo,
-            cloneBranch: peer.repo.baseBranch,
+            // A read-only peer clones at its default branch (the bug-investigator) unless the job pins
+            // an explicit branch — the merger checks each peer out at its PR branch so the combined diff
+            // sees the PR change (`git diff origin/<base>...HEAD`).
+            cloneBranch: peer.cloneBranch ?? peer.repo.baseBranch,
             ghToken: peer.ghToken ?? job.ghToken,
         })),
     ].map((leg) => ({ ...leg, dirName: claimDir(leg.repo) }));
     return withWorkspace('explore-multi', async (root) => {
         // Clone phase: every repo (read-only) into its sibling dir under the workspace root. No
-        // work branch, no resume — the investigator only reads — so the legs are independent and
-        // clone in parallel (wall-clock is the slowest single clone, not the sum).
+        // work branch, no resume — the agent only reads — so the legs are independent and clone in
+        // parallel (wall-clock is the slowest single clone, not the sum). `full` is honoured per the
+        // job (the merger needs full history so `git diff origin/<base>...HEAD` has the merge base;
+        // the bug-investigator leaves it shallow).
         opts.onPhase?.('clone');
         await Promise.all(legs.map(async (leg) => {
             const dir = join(root, leg.dirName);
@@ -549,6 +585,7 @@ async function runMultiRepoExplore(job, opts) {
                 repo: { ...leg.repo, baseBranch: leg.cloneBranch },
                 ghToken: leg.ghToken,
                 dir,
+                full: job.full,
                 signal: opts.signal,
             });
         }));

package/dist/job.js

@@ -136,6 +136,10 @@ function parsePeerRepos(value) {
         // read-only explore fan-out (bug-investigator) — validate it only when present.
         if (e.newBranch !== undefined)
             spec.newBranch = str(e.newBranch, `peerRepos[${i}].newBranch`);
+        // Read-only explore fan-out: the branch to check the peer out at (the merger's PR branch).
+        if (e.cloneBranch !== undefined) {
+            spec.cloneBranch = str(e.cloneBranch, `peerRepos[${i}].cloneBranch`);
+        }
         if (typeof e.frameId === 'string' && e.frameId)
             spec.frameId = e.frameId;
         if (typeof e.ghToken === 'string' && e.ghToken)
@@ -282,6 +286,37 @@ export function parsePackageRegistries(value, env = process.env) {
     }
     return entries;
 }
+/** A valid POSIX shell variable name (letters, digits, underscore; not starting with a digit). */
+const ENV_VAR_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/**
+ * Validate the optional tester `testSecrets` list — `{ key, value }` env pairs the harness
+ * injects into the run environment. Keys must be valid env-var names; toolchain-critical /
+ * reserved names ({@link isReservedEnvName}) and duplicates are dropped so a drifted body can't
+ * clobber PATH/NODE_OPTIONS/etc. Absent ⇒ no secrets injected.
+ */
+export function parseTestSecrets(value) {
+    if (value === undefined || value === null)
+        return [];
+    if (!Array.isArray(value))
+        throw new Error("Invalid job: 'testSecrets' must be an array");
+    const entries = [];
+    const seen = new Set();
+    for (const [i, raw] of value.entries()) {
+        if (typeof raw !== 'object' || raw === null) {
+            throw new Error(`Invalid job: 'testSecrets[${i}]' must be an object`);
+        }
+        const entry = raw;
+        const key = str(entry.key, `testSecrets[${i}].key`).trim();
+        if (!ENV_VAR_NAME_PATTERN.test(key)) {
+            throw new Error(`Invalid job: 'testSecrets[${i}].key' must be a valid environment variable name`);
+        }
+        if (isReservedEnvName(key) || seen.has(key))
+            continue;
+        seen.add(key);
+        entries.push({ key, value: str(entry.value, `testSecrets[${i}].value`) });
+    }
+    return entries;
+}
 /** Parse the coding-mode bootstrap spec, or undefined when absent. Validates the target. */
 function parseAgentBootstrapSpec(value) {
     if (typeof value !== 'object' || value === null)
@@ -536,6 +571,7 @@ export function parseAgentJob(input) {
     const bootstrap = parseAgentBootstrapSpec(o.bootstrap);
     const contextFiles = parseContextFiles(o.contextFiles);
     const packageRegistries = parsePackageRegistries(o.packageRegistries);
+    const testSecrets = parseTestSecrets(o.testSecrets);
     const guardLimits = parseGuardLimits(o.guardLimits);
     const job = {
         jobId: str(o.jobId, 'jobId'),
@@ -556,6 +592,7 @@ export function parseAgentJob(input) {
         ...(output ? { output } : {}),
         ...(contextFiles.length ? { contextFiles } : {}),
         ...(packageRegistries.length ? { packageRegistries } : {}),
+        ...(testSecrets.length ? { testSecrets } : {}),
         ...(infra ? { infra } : {}),
         ...(typeof o.newBranch === 'string' && o.newBranch ? { newBranch: o.newBranch } : {}),
         ...(typeof o.pushBranch === 'string' && o.pushBranch ? { pushBranch: o.pushBranch } : {}),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/executor-harness",
-  "version": "1.37.2",
+  "version": "1.39.2",
   "description": "Container payload: a thin TypeScript wrapper that runs the Pi coding agent against a cloned repo and opens a PR. Runs in the Cloudflare Container (and, in local native mode, as a host process); carries no secrets.",
   "repository": {
     "type": "git",
@@ -26,8 +26,8 @@
     "hono": "^4.12.27",
     "typescript": "^6.0.3",
     "vitest": "^4.1.9",
-    "@cat-factory/server": "0.101.0",
-    "@cat-factory/spend": "0.11.15"
+    "@cat-factory/server": "0.105.0",
+    "@cat-factory/spend": "0.11.24"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",

package/src/agent.ts

@@ -9,10 +9,11 @@ import type {
   AgentResult,
   InfraSetupRecord,
   ServiceInfraSpec,
+  TestSecretSpec,
 } from './job.js'
 import { standUpFrontend, tearDownFrontend } from './frontend-infra.js'
 import { configurePackageRegistries } from './package-registries.js'
-import { captureRedactedOutput, redactSecrets } from './redact.js'
+import { captureRedactedOutput, redactSecrets, registerKnownSecrets } from './redact.js'
 import {
   cloneRepo,
   commitAll,
@@ -408,6 +409,30 @@ 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.
+ */
+function applyTestSecrets(secrets: TestSecretSpec[] | undefined): () => void {
+  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
+    }
+  }
+}
+
 /**
  * Read-only exploration: clone `branch`, run the agent making no edits, and return its
  * prose report — or, when `output.kind==='structured'`, the parsed JSON object as
@@ -473,6 +498,11 @@ 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)
+
       try {
         opts.onPhase?.('agent')
         logger.info('agent(explore): running agent', { serviceDirectory })
@@ -513,6 +543,7 @@ async function runExploreMode(job: AgentJob, opts: RunOptions): Promise<AgentRes
           { infra, infraSetupFields, logger, signal: opts.signal },
         )
       } finally {
+        restoreSecrets()
         if (managed) await managed.cleanup()
       }
     },
@@ -655,15 +686,20 @@ async function runMultiRepoExplore(job: AgentJob, opts: RunOptions): Promise<Age
     { repo: job.repo, cloneBranch: job.branch, ghToken: job.ghToken },
     ...peers.map((peer) => ({
       repo: peer.repo,
-      cloneBranch: peer.repo.baseBranch,
+      // A read-only peer clones at its default branch (the bug-investigator) unless the job pins
+      // an explicit branch — the merger checks each peer out at its PR branch so the combined diff
+      // sees the PR change (`git diff origin/<base>...HEAD`).
+      cloneBranch: peer.cloneBranch ?? peer.repo.baseBranch,
       ghToken: peer.ghToken ?? job.ghToken,
     })),
   ].map((leg) => ({ ...leg, dirName: claimDir(leg.repo) }))
 
   return withWorkspace('explore-multi', async (root) => {
     // Clone phase: every repo (read-only) into its sibling dir under the workspace root. No
-    // work branch, no resume — the investigator only reads — so the legs are independent and
-    // clone in parallel (wall-clock is the slowest single clone, not the sum).
+    // work branch, no resume — the agent only reads — so the legs are independent and clone in
+    // parallel (wall-clock is the slowest single clone, not the sum). `full` is honoured per the
+    // job (the merger needs full history so `git diff origin/<base>...HEAD` has the merge base;
+    // the bug-investigator leaves it shallow).
     opts.onPhase?.('clone')
     await Promise.all(
       legs.map(async (leg) => {
@@ -677,6 +713,7 @@ async function runMultiRepoExplore(job: AgentJob, opts: RunOptions): Promise<Age
           repo: { ...leg.repo, baseBranch: leg.cloneBranch },
           ghToken: leg.ghToken,
           dir,
+          full: job.full,
           signal: opts.signal,
         })
       }),

package/src/job.ts

@@ -78,6 +78,13 @@ export interface PeerRepoSpec {
    * (the bug-investigator), which only clones the peer to read it and never pushes.
    */
   newBranch?: string
+  /**
+   * The EXISTING branch to check the peer out at for a READ-ONLY explore fan-out (the `merger`
+   * scoring the combined diff clones each peer at its PR branch so the diff sees the PR change).
+   * Absent ⇒ the peer is cloned at its repo default branch (the bug-investigator). Ignored on the
+   * coding fan-out, which creates `newBranch` instead.
+   */
+  cloneBranch?: string
   /** Open a PR/MR in this peer when set AND the run changed the peer (skipped for a clean repo). */
   pr?: PrSpec
   /** Per-repo GitHub token; defaults to the job's `ghToken` (one installation per workspace today). */
@@ -236,6 +243,10 @@ function parsePeerRepos(value: unknown): PeerRepoSpec[] {
     // `newBranch` is required for a coding fan-out (it pushes to it) but ABSENT for a
     // read-only explore fan-out (bug-investigator) — validate it only when present.
     if (e.newBranch !== undefined) spec.newBranch = str(e.newBranch, `peerRepos[${i}].newBranch`)
+    // Read-only explore fan-out: the branch to check the peer out at (the merger's PR branch).
+    if (e.cloneBranch !== undefined) {
+      spec.cloneBranch = str(e.cloneBranch, `peerRepos[${i}].cloneBranch`)
+    }
     if (typeof e.frameId === 'string' && e.frameId) spec.frameId = e.frameId
     if (typeof e.ghToken === 'string' && e.ghToken) spec.ghToken = e.ghToken
     if (typeof e.pr === 'object' && e.pr !== null) {
@@ -407,6 +418,49 @@ export function parsePackageRegistries(
   return entries
 }
 
+/**
+ * One sensitive test credential the tester receives: an env-var name + its (secret) value.
+ * The backend seals these at rest and decrypts them at dispatch; the harness injects each as an
+ * environment variable the tester's shell can read (out of band — the value is NEVER in the
+ * prompt/telemetry). See {@link parseTestSecrets}.
+ */
+export interface TestSecretSpec {
+  key: string
+  value: string
+}
+
+/** A valid POSIX shell variable name (letters, digits, underscore; not starting with a digit). */
+const ENV_VAR_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/
+
+/**
+ * Validate the optional tester `testSecrets` list — `{ key, value }` env pairs the harness
+ * injects into the run environment. Keys must be valid env-var names; toolchain-critical /
+ * reserved names ({@link isReservedEnvName}) and duplicates are dropped so a drifted body can't
+ * clobber PATH/NODE_OPTIONS/etc. Absent ⇒ no secrets injected.
+ */
+export function parseTestSecrets(value: unknown): TestSecretSpec[] {
+  if (value === undefined || value === null) return []
+  if (!Array.isArray(value)) throw new Error("Invalid job: 'testSecrets' must be an array")
+  const entries: TestSecretSpec[] = []
+  const seen = new Set<string>()
+  for (const [i, raw] of value.entries()) {
+    if (typeof raw !== 'object' || raw === null) {
+      throw new Error(`Invalid job: 'testSecrets[${i}]' must be an object`)
+    }
+    const entry = raw as Record<string, unknown>
+    const key = str(entry.key, `testSecrets[${i}].key`).trim()
+    if (!ENV_VAR_NAME_PATTERN.test(key)) {
+      throw new Error(
+        `Invalid job: 'testSecrets[${i}].key' must be a valid environment variable name`,
+      )
+    }
+    if (isReservedEnvName(key) || seen.has(key)) continue
+    seen.add(key)
+    entries.push({ key, value: str(entry.value, `testSecrets[${i}].value`) })
+  }
+  return entries
+}
+
 // ---- Shared repo-bootstrap target ---------------------------------------
 
 /** The new repository a repo-bootstrap run force-pushes its fresh history to. */
@@ -602,6 +656,13 @@ export interface AgentJob extends HarnessAuthFields {
    * job on a reused container is removed.
    */
   packageRegistries?: PackageRegistrySpec[]
+  /**
+   * Tester kinds only: sensitive test credentials injected into the run's ENVIRONMENT (out of
+   * band) as `{ key, value }` env pairs, so the tester's shell can read `$KEY` without the value
+   * ever appearing in the prompt or telemetry. Reserved/toolchain env names are dropped at parse.
+   * Absent ⇒ no secrets injected.
+   */
+  testSecrets?: TestSecretSpec[]
   /**
    * Explore mode: stand the service's dependencies up before the agent runs (the
    * tester). Brings the docker-compose infra up on localhost for the duration of the
@@ -1042,6 +1103,7 @@ export function parseAgentJob(input: unknown): AgentJob {
   const bootstrap = parseAgentBootstrapSpec(o.bootstrap)
   const contextFiles = parseContextFiles(o.contextFiles)
   const packageRegistries = parsePackageRegistries(o.packageRegistries)
+  const testSecrets = parseTestSecrets(o.testSecrets)
   const guardLimits = parseGuardLimits(o.guardLimits)
   const job: AgentJob = {
     jobId: str(o.jobId, 'jobId'),
@@ -1062,6 +1124,7 @@ export function parseAgentJob(input: unknown): AgentJob {
     ...(output ? { output } : {}),
     ...(contextFiles.length ? { contextFiles } : {}),
     ...(packageRegistries.length ? { packageRegistries } : {}),
+    ...(testSecrets.length ? { testSecrets } : {}),
     ...(infra ? { infra } : {}),
     ...(typeof o.newBranch === 'string' && o.newBranch ? { newBranch: o.newBranch } : {}),
     ...(typeof o.pushBranch === 'string' && o.pushBranch ? { pushBranch: o.pushBranch } : {}),