@tangle-network/agent-bench 0.3.7 → 0.3.8

package/src/swe-arena/briefing.test.mts

@@ -0,0 +1,178 @@
+/**
+ * Gen-5 MAP+TOOLBOX briefing: evidence-index generation (one line per
+ * evidence path, private instances excluded, leak guard fail-loud), the
+ * toolbox/permission prompt section, and the change-space briefing override.
+ */
+
+import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import {
+  AUTHOR_BRIEFING_RELPATH,
+  AUTHOR_BRIEFING_VERSION,
+  briefingPromptSection,
+  collectEvidenceIndexRows,
+  defaultAuthorBriefing,
+  EVIDENCE_INDEX_FILENAME,
+  resolveAuthorBriefing,
+  writeEvidenceIndex,
+} from './briefing.mts'
+import { splitInstances } from './score-split.mts'
+import { runOk } from './proc.ts'
+
+const SIX = [
+  'astropy__astropy-13033',
+  'django__django-11532',
+  'matplotlib__matplotlib-20826',
+  'pydata__xarray-4687',
+  'pytest-dev__pytest-6197',
+  'sphinx-doc__sphinx-9658',
+]
+
+describe('evidence index', () => {
+  let root: string
+  let outDir: string
+  let roundsDir: string
+  let priorDir: string
+  const split = splitInstances('r4-seed', SIX, 4)
+  const publicIid = split.publicInstances[0]!
+  const privateIid = split.privateInstances[0]!
+
+  beforeEach(async () => {
+    root = await mkdtemp(join(tmpdir(), 'briefing-'))
+    outDir = join(root, 'out')
+    roundsDir = join(root, 'rounds')
+    priorDir = join(root, 'gen4')
+    await mkdir(outDir, { recursive: true })
+    await mkdir(roundsDir, { recursive: true })
+    await writeFile(join(roundsDir, 'gen-0.jsonl'), '{}\n')
+    await writeFile(join(roundsDir, 'round4-summary-r4-x.json'), '{}\n')
+    // Seed artifact dirs: one public, one private instance.
+    for (const iid of [publicIid, privateIid]) {
+      await mkdir(join(root, 'runs', iid, 'SUP4'), { recursive: true })
+      await writeFile(join(root, 'patches', `${iid}.sup4.patch`), 'p\n').catch(async () => {
+        await mkdir(join(root, 'patches'), { recursive: true })
+        await writeFile(join(root, 'patches', `${iid}.sup4.patch`), 'p\n')
+      })
+    }
+    // Prior run outDir with arm-run judge evidence for a public + a private instance.
+    for (const iid of [publicIid, privateIid]) {
+      const runDir = join(priorDir, 'arm-runs', 'cand111111', 'rep-0', 'runs', iid)
+      await mkdir(runDir, { recursive: true })
+      await writeFile(join(runDir, 'judge.json'), '{}\n')
+    }
+    await mkdir(join(priorDir, 'candidates'), { recursive: true })
+    await mkdir(join(priorDir, 'proposer-shots'), { recursive: true })
+  })
+
+  afterEach(async () => {
+    await rm(root, { recursive: true, force: true })
+  })
+
+  const args = () => ({
+    outDir,
+    roundsDir,
+    seedArtifactRuns: [publicIid, privateIid].map((iid) => ({
+      iid,
+      arm: 'SUP4',
+      dir: join(root, 'runs', iid, 'SUP4'),
+      patchPath: join(root, 'patches', `${iid}.sup4.patch`),
+    })),
+    priorEvidenceDirs: [priorDir],
+    paretoParentPatches: [] as Array<{ label: string; path: string }>,
+    split,
+  })
+
+  it('lists one line per evidence path: staircase, summaries, seed runs, prior arm runs, shot receipts', async () => {
+    const { path, rows } = await writeEvidenceIndex(args())
+    expect(path).toBe(join(outDir, EVIDENCE_INDEX_FILENAME))
+    expect(existsSync(path)).toBe(true)
+    const text = await readFile(path, 'utf8')
+    expect(text).toContain(join(roundsDir, 'gen-0.jsonl'))
+    expect(text).toContain(join(roundsDir, 'round4-summary-r4-x.json'))
+    expect(text).toContain(join(root, 'runs', publicIid, 'SUP4'))
+    expect(text).toContain(join(root, 'patches', `${publicIid}.sup4.patch`))
+    expect(text).toContain(join(priorDir, 'candidates'))
+    expect(text).toContain(join(priorDir, 'proposer-shots'))
+    expect(text).toContain(join(priorDir, 'arm-runs', 'cand111111', 'rep-0', 'runs', publicIid))
+    // One markdown bullet per row.
+    expect(text.split('\n').filter((l) => l.startsWith('- ')).length).toBe(rows.length)
+  })
+
+  it('NEVER surfaces private instances: no private row, no private id anywhere in the rendered text', async () => {
+    const { path, rows } = await writeEvidenceIndex(args())
+    const text = await readFile(path, 'utf8')
+    for (const iid of split.privateInstances) expect(text).not.toContain(iid)
+    expect(rows.every((r) => r.iid === null || !split.privateInstances.includes(r.iid))).toBe(true)
+    // The withholding itself is disclosed (count only, no identities).
+    expect(text).toContain('2 improvement instance(s) are PRIVATE')
+  })
+
+  it('fails loud when a run-level path would leak a private id into the rendered index', async () => {
+    const leakPatch = join(outDir, `${privateIid}.parent.patch`)
+    await writeFile(leakPatch, 'x\n')
+    await expect(
+      writeEvidenceIndex({ ...args(), paretoParentPatches: [{ label: 'leaky', path: leakPatch }] }),
+    ).rejects.toThrow(/leaked/)
+  })
+
+  it('collectEvidenceIndexRows includes everything when no split is configured', async () => {
+    const rows = await collectEvidenceIndexRows({ ...args(), split: null })
+    const iids = rows.map((r) => r.iid).filter((i): i is string => i !== null)
+    expect(iids).toContain(privateIid)
+  })
+})
+
+describe('briefing text', () => {
+  it('default briefing names the toolbox (traces CLI, trace analysts, AxLLM) and grants subagent permission with a budget', () => {
+    const text = defaultAuthorBriefing()
+    expect(text).toContain('npx --yes @tangle-network/traces@latest')
+    expect(text).toContain('agent-eval trace analysts')
+    expect(text).toContain('AxLLM')
+    expect(text).toContain('spawn your own subagents')
+    expect(text).toContain('Research budget')
+    expect(text).toContain('ONE input')
+    expect(text).toContain(AUTHOR_BRIEFING_RELPATH)
+    expect(text).toContain(AUTHOR_BRIEFING_VERSION)
+  })
+
+  it('briefingPromptSection leads with the evidence map path', () => {
+    const section = briefingPromptSection({
+      indexPath: '/tmp/x/evidence-index.md',
+      briefingText: defaultAuthorBriefing(),
+      briefingSource: 'default',
+    })
+    expect(section).toContain('EVIDENCE MAP: /tmp/x/evidence-index.md')
+    expect(section.indexOf('EVIDENCE MAP')).toBeLessThan(section.indexOf('TOOLBOX'))
+  })
+
+  it('resolveAuthorBriefing prefers the change-space file at the ref (authors may rewrite their own briefing)', async () => {
+    const repo = await mkdtemp(join(tmpdir(), 'briefing-repo-'))
+    try {
+      await runOk('git', ['init', '-q', '-b', 'main', repo])
+      await runOk('git', ['-C', repo, 'config', 'user.email', 't@t.dev'])
+      await runOk('git', ['-C', repo, 'config', 'user.name', 'T'])
+      await writeFile(join(repo, 'base.txt'), 'x\n')
+      await runOk('git', ['-C', repo, 'add', '-A'])
+      await runOk('git', ['-C', repo, 'commit', '-q', '-m', 'init'])
+
+      // No override committed → the versioned default.
+      const fallback = await resolveAuthorBriefing(repo, 'main')
+      expect(fallback.source).toBe('default')
+      expect(fallback.text).toBe(defaultAuthorBriefing())
+
+      // Commit the change-space override → it wins.
+      await mkdir(join(repo, 'extensions', 'pi'), { recursive: true })
+      await writeFile(join(repo, AUTHOR_BRIEFING_RELPATH), 'MY OWN RESEARCH RULES\n')
+      await runOk('git', ['-C', repo, 'add', '-A'])
+      await runOk('git', ['-C', repo, 'commit', '-q', '-m', 'briefing override'])
+      const override = await resolveAuthorBriefing(repo, 'main')
+      expect(override.source).toBe('change-space')
+      expect(override.text).toBe('MY OWN RESEARCH RULES\n')
+    } finally {
+      await rm(repo, { recursive: true, force: true })
+    }
+  })
+})

package/src/swe-arena/calibrate.ts

@@ -19,8 +19,11 @@
 
 import { rm, writeFile } from 'node:fs/promises'
 import { join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { judgeFactoryPatch } from './factory-judge-child.mts'
+import { loadFactoryInstance, loadFactoryInstances, type LoadedFactoryInstance } from './fixtures'
 import { materializeWorkspace } from './materialize'
-import { run, shq } from './proc'
+import { run, runOk, shq } from './proc'
 import type { SerializedJudge } from './serialized-judge'
 
 export interface CalibrateOptions {
@@ -114,3 +117,101 @@ export async function calibrateInstance(opts: CalibrateOptions): Promise<Calibra
     }
   }
 }
+
+// ---------------------------------------------------------------------------
+// Factory-bench admission gate — the same "calibrate through the OFFICIAL
+// judge" lesson, generalized: gold (the real PR's impl-only diff) must judge
+// resolved, and the bare base (empty patch) must judge unresolved. Both runs
+// go through the SAME judge code the arena uses (judgeFactoryPatch — the
+// factory-judge-child body), deliberately bypassing serialized-judge's
+// empty-patch short-circuit so the base direction really executes the judge
+// tests on the bare tree instead of trivially returning false.
+// ---------------------------------------------------------------------------
+
+export interface FactoryCalibrationResult {
+  iid: string
+  /** Gold = impl-only PR diff. Must be resolved with full score. */
+  goldResolved: boolean
+  goldPassed: number
+  /** Base = empty patch. Must be unresolved. */
+  baseResolved: boolean
+  basePassed: number
+  total: number
+  /** goldResolved && !baseResolved — the pool admission bar. */
+  admitted: boolean
+}
+
+/**
+ * The real PR's impl-only patch: full first-parent diff base→judge_ref minus
+ * the judge test files (they are the hidden judge, not the deliverable).
+ */
+export async function goldImplPatch(inst: LoadedFactoryInstance): Promise<string> {
+  const res = await runOk('git', [
+    '-C', inst.repo_local_mirror,
+    'diff', inst.base_commit, inst.judge_ref,
+    '--', '.',
+    ...inst.judge_tests.map((t) => `:(exclude)${t}`),
+  ])
+  if (res.stdout.trim().length === 0) {
+    throw new Error(`calibrate ${inst.id}: impl-only gold diff is empty — judge_tests exclude everything?`)
+  }
+  return res.stdout
+}
+
+/** Run both admission directions for one instance. Throws only on infra failure. */
+export async function calibrateFactoryInstance(inst: LoadedFactoryInstance): Promise<FactoryCalibrationResult> {
+  const gold = await judgeFactoryPatch(inst, await goldImplPatch(inst))
+  const base = await judgeFactoryPatch(inst, '')
+  return {
+    iid: inst.id,
+    goldResolved: gold.result.resolved,
+    goldPassed: gold.result.passed,
+    baseResolved: base.result.resolved,
+    basePassed: base.result.passed,
+    total: inst.judgeTestTotal,
+    admitted: gold.result.resolved && !base.result.resolved,
+  }
+}
+
+// ---------------------------------------------------------------------------
+// CLI:  tsx src/swe-arena/calibrate.ts --factory <instancesDirOrInstanceDir> [id ...]
+// Rejection is LOUD: any instance failing either direction exits nonzero.
+// ---------------------------------------------------------------------------
+
+const isMain = process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href
+
+if (isMain) {
+  const [mode, root, ...ids] = process.argv.slice(2)
+  if (mode !== '--factory' || !root) {
+    console.error('usage: tsx src/swe-arena/calibrate.ts --factory <instancesDir|instanceDir> [id ...]')
+    process.exit(2)
+  }
+  let instances: LoadedFactoryInstance[]
+  try {
+    instances = loadFactoryInstances(root)
+  } catch {
+    instances = [loadFactoryInstance(root)]
+  }
+  if (ids.length > 0) {
+    const byId = new Map(instances.map((i) => [i.id, i]))
+    instances = ids.map((id) => {
+      const inst = byId.get(id)
+      if (!inst) throw new Error(`unknown instance id ${id} (have: ${[...byId.keys()].join(', ')})`)
+      return inst
+    })
+  }
+  let rejected = 0
+  for (const inst of instances) {
+    const r = await calibrateFactoryInstance(inst)
+    const verdict = r.admitted ? 'ADMITTED' : 'REJECTED'
+    console.log(
+      `CALIBRATE ${r.iid}: gold ${r.goldPassed}/${r.total} resolved=${r.goldResolved}; ` +
+        `base ${r.basePassed}/${r.total} resolved=${r.baseResolved} → ${verdict}`,
+    )
+    if (!r.admitted) rejected += 1
+  }
+  if (rejected > 0) {
+    console.error(`calibration gate: ${rejected} instance(s) REJECTED (gold must pass AND base must fail)`)
+    process.exit(1)
+  }
+}

package/src/swe-arena/cell-evidence.mts

@@ -248,9 +248,17 @@ export type StaircaseVerdict =
    *  evaluation — the candidate never became a measured surface. Emitted by
    *  the outer loop's kill-row writer, never by `decideVerdict`. */
   | 'rejected-prefilter'
+  /** GEN-5 activation gate: the candidate's own machine-checkable predicate
+   *  (activation.mts) proved its mechanism NEVER fired in its campaign
+   *  traces — recorded, never promoted, EVEN when the score improved. */
+  | 'quarantined-inactive'
 
 /** protocol_v2 keep-if-better: improvement-set resolved-count must RISE and
- *  cost must stay within the guard. Fail-closed on unprovable cost. */
+ *  cost must stay within the guard. Fail-closed on unprovable cost.
+ *  GEN-5: `activationFired === false` quarantines the candidate ahead of the
+ *  score comparison — an improved score with an inactive mechanism is
+ *  indistinguishable from luck (undefined/null = gate not applicable:
+ *  disabled, baseline, or predicate unevaluated). */
 export function decideVerdict(input: {
   violations: string[]
   coverageComplete: boolean
@@ -258,8 +266,10 @@ export function decideVerdict(input: {
   parentResolvedCount: number
   costRatio: number | null
   costGuardRatio: number
+  activationFired?: boolean | null
 }): StaircaseVerdict {
   if (input.violations.length > 0) return 'rejected-out-of-space'
+  if (input.activationFired === false) return 'quarantined-inactive'
   if (!input.coverageComplete) return 'rejected-incomplete'
   if (input.resolvedCount <= input.parentResolvedCount) return 'rejected-no-gain'
   if (input.costRatio === null || input.costRatio > input.costGuardRatio) return 'rejected-cost'
@@ -273,27 +283,46 @@ export function decideVerdict(input: {
 // coverage-incomplete downstream, fail-closed).
 // ---------------------------------------------------------------------------
 
-/** Parse every `<cellDir>/cached-result.json` under one campaign dir. Missing dir = []. */
-export async function loadCampaignCells(campaignDir: string): Promise<EvidenceCell[]> {
+/** Every `<cellDir>/cached-result.json` under one campaign dir, verbatim and
+ *  identity-checked. Missing dir = []. A cache that exists but carries no
+ *  scenarioId/rep cannot be attributed to a cell, so it throws rather than
+ *  disappearing from the campaign's coverage. */
+export async function loadCampaignCellRecords(campaignDir: string): Promise<Record<string, unknown>[]> {
   const entries = await readdir(campaignDir, { withFileTypes: true }).catch(() => [])
-  const cells: EvidenceCell[] = []
+  const records: Record<string, unknown>[] = []
   for (const entry of entries) {
     if (!entry.isDirectory()) continue
     const path = join(campaignDir, entry.name, 'cached-result.json')
     const raw = await readFile(path, 'utf8').catch(() => null)
     if (raw === null) continue
-    let parsed: Record<string, unknown>
+    let parsed: unknown
     try {
-      parsed = JSON.parse(raw) as Record<string, unknown>
+      parsed = JSON.parse(raw)
     } catch {
       throw new Error(`loadCampaignCells: corrupt cell cache ${path}`)
     }
-    if (typeof parsed.scenarioId !== 'string' || typeof parsed.rep !== 'number') {
+    // null and arrays parse fine and would make the identity check below throw a
+    // TypeError instead of naming what is wrong with the file.
+    const record =
+      parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)
+        ? (parsed as Record<string, unknown>)
+        : null
+    if (record === null || typeof record.scenarioId !== 'string' || typeof record.rep !== 'number') {
       throw new Error(`loadCampaignCells: ${path} is not a campaign cell (scenarioId/rep missing)`)
     }
+    records.push(record)
+  }
+  return records
+}
+
+/** Parse every `<cellDir>/cached-result.json` under one campaign dir. Missing dir = []. */
+export async function loadCampaignCells(campaignDir: string): Promise<EvidenceCell[]> {
+  const cells: EvidenceCell[] = []
+  for (const parsed of await loadCampaignCellRecords(campaignDir)) {
     cells.push({
-      scenarioId: parsed.scenarioId,
-      rep: parsed.rep,
+      // loadCampaignCellRecords has already proven both are present and typed.
+      scenarioId: parsed.scenarioId as string,
+      rep: parsed.rep as number,
       artifact: (parsed.artifact ?? null) as R4Artifact | null,
       ...(typeof parsed.error === 'string' ? { error: parsed.error } : {}),
       ...(typeof parsed.costUsd === 'number' ? { costUsd: parsed.costUsd } : {}),
@@ -377,6 +406,8 @@ export function gateEvidenceFromCells(input: {
   iids: string[]
   reps: number
   costGuardRatio: number
+  /** GEN-5 activation-gate outcome for the winner (see decideVerdict). */
+  activationFired?: boolean | null
 }): GateEvidence {
   const winnerRuns = replicateRunsFromCells(input.winnerCells)
   const baselineRuns = replicateRunsFromCells(input.baselineCells)
@@ -400,6 +431,7 @@ export function gateEvidenceFromCells(input: {
       parentResolvedCount: baseResolved,
       costRatio,
       costGuardRatio: input.costGuardRatio,
+      ...(input.activationFired !== undefined ? { activationFired: input.activationFired } : {}),
     }),
   }
 }

package/src/swe-arena/factory-command-container.ts

@@ -0,0 +1,284 @@
+import { randomUUID } from 'node:crypto'
+import { mkdir, mkdtemp, realpath, rm, stat } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { delimiter, isAbsolute, join } from 'node:path'
+
+import { run, type RunResult } from './proc'
+
+const WORKSPACE_PATH = '/workspace'
+const STATE_PATH = '/factory-state'
+const IMAGE_DIGEST_RE = /^.+@sha256:[0-9a-f]{64}$/
+const CONTAINER_PATH =
+  `${STATE_PATH}/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin`
+const CONTROL_TIMEOUT_MS = 30_000
+
+export type FactoryCommandNetwork = 'enabled' | 'none'
+
+export interface RunFactoryCommandOptions {
+  image: string
+  network: FactoryCommandNetwork
+  timeoutMs: number
+  signal?: AbortSignal
+  maxBuffer?: number
+}
+
+function hostPath(baseEnv: NodeJS.ProcessEnv): string {
+  const path = (baseEnv.PATH ?? '')
+    .split(delimiter)
+    .filter((entry) => entry.length > 0 && isAbsolute(entry))
+    .join(delimiter)
+  if (!path) throw new Error('factory container control process requires an absolute PATH')
+  return path
+}
+
+async function createControlEnvironment(): Promise<{
+  env: NodeJS.ProcessEnv
+  dispose: () => Promise<void>
+}> {
+  const root = await mkdtemp(join(tmpdir(), 'factory-container-control-'))
+  const home = join(root, 'home')
+  const dockerConfig = join(root, 'docker')
+  const xdgConfig = join(root, 'xdg')
+  const temp = join(root, 'tmp')
+  try {
+    await Promise.all(
+      [home, dockerConfig, xdgConfig, temp].map((dir) =>
+        mkdir(dir, { recursive: true, mode: 0o700 }),
+      ),
+    )
+    let disposal: Promise<void> | undefined
+    return {
+      env: {
+        PATH: hostPath(process.env),
+        HOME: home,
+        DOCKER_CONFIG: dockerConfig,
+        XDG_CONFIG_HOME: xdgConfig,
+        TMPDIR: temp,
+        TMP: temp,
+        TEMP: temp,
+        LANG: 'C',
+        LC_ALL: 'C',
+        TZ: 'UTC',
+      },
+      dispose: () => (disposal ??= rm(root, { recursive: true, force: true })),
+    }
+  } catch (error) {
+    await rm(root, { recursive: true, force: true })
+    throw error
+  }
+}
+
+function currentUser(): { uid: number; gid: number } {
+  const uid = process.getuid?.()
+  const gid = process.getgid?.()
+  if (
+    typeof uid !== 'number' ||
+    typeof gid !== 'number' ||
+    !Number.isSafeInteger(uid) ||
+    !Number.isSafeInteger(gid)
+  ) {
+    throw new Error('factory command containers require a POSIX uid and gid')
+  }
+  if (uid === 0) {
+    throw new Error('factory command containers refuse to run candidate commands as root')
+  }
+  return { uid, gid }
+}
+
+function containerEnvironment(): string[] {
+  return [
+    `PATH=${CONTAINER_PATH}`,
+    `HOME=${STATE_PATH}/home`,
+    `XDG_CONFIG_HOME=${STATE_PATH}/xdg/config`,
+    `XDG_DATA_HOME=${STATE_PATH}/xdg/data`,
+    `XDG_CACHE_HOME=${STATE_PATH}/xdg/cache`,
+    `XDG_STATE_HOME=${STATE_PATH}/xdg/state`,
+    `XDG_RUNTIME_DIR=${STATE_PATH}/xdg/runtime`,
+    'TMPDIR=/tmp',
+    'TMP=/tmp',
+    'TEMP=/tmp',
+    'LANG=C',
+    'LC_ALL=C',
+    'TZ=UTC',
+    'CI=false',
+    `COREPACK_HOME=${STATE_PATH}/corepack`,
+    'COREPACK_DEFAULT_TO_LATEST=0',
+    'COREPACK_ENABLE_DOWNLOAD_PROMPT=0',
+    `PNPM_HOME=${STATE_PATH}/pnpm-home`,
+    `npm_config_store_dir=${STATE_PATH}/pnpm-store`,
+    `NPM_CONFIG_CACHE=${STATE_PATH}/npm-cache`,
+    `NPM_CONFIG_USERCONFIG=${STATE_PATH}/npm/user.npmrc`,
+    `NPM_CONFIG_GLOBALCONFIG=${STATE_PATH}/npm/global.npmrc`,
+    'GIT_CONFIG_NOSYSTEM=1',
+    `GIT_CONFIG_GLOBAL=${STATE_PATH}/git/global.config`,
+    `GIT_CONFIG_SYSTEM=${STATE_PATH}/git/system.config`,
+    'GIT_TERMINAL_PROMPT=0',
+    'GCM_INTERACTIVE=Never',
+  ]
+}
+
+const COMMAND_WRAPPER = `
+set -eu
+mkdir -p \
+  "$HOME" \
+  "$XDG_CONFIG_HOME" \
+  "$XDG_DATA_HOME" \
+  "$XDG_CACHE_HOME" \
+  "$XDG_STATE_HOME" \
+  "$XDG_RUNTIME_DIR" \
+  "$COREPACK_HOME" \
+  "$PNPM_HOME" \
+  "$npm_config_store_dir" \
+  "$NPM_CONFIG_CACHE" \
+  "${STATE_PATH}/npm" \
+  "${STATE_PATH}/git" \
+  "${STATE_PATH}/bin"
+touch \
+  "$NPM_CONFIG_USERCONFIG" \
+  "$NPM_CONFIG_GLOBALCONFIG" \
+  "$GIT_CONFIG_GLOBAL" \
+  "$GIT_CONFIG_SYSTEM"
+corepack enable --install-directory "${STATE_PATH}/bin" >/dev/null
+exec /bin/bash --noprofile --norc -c "$1"
+`
+
+function dockerArgs(input: {
+  name: string
+  workspace: string
+  command: string
+  image: string
+  network: FactoryCommandNetwork
+  uid: number
+  gid: number
+}): string[] {
+  const user = `${input.uid}:${input.gid}`
+  return [
+    'run',
+    '--rm',
+    '--name',
+    input.name,
+    '--hostname',
+    'factory-command',
+    '--pull=missing',
+    '--read-only',
+    '--init',
+    '--cap-drop=ALL',
+    '--security-opt=no-new-privileges',
+    '--pids-limit=512',
+    '--memory=4g',
+    '--memory-swap=4g',
+    '--cpus=2',
+    '--ulimit',
+    'nofile=4096:4096',
+    '--ipc=private',
+    '--network',
+    input.network === 'none' ? 'none' : 'bridge',
+    '--user',
+    user,
+    '--workdir',
+    WORKSPACE_PATH,
+    '--mount',
+    `type=bind,src=${input.workspace},dst=${WORKSPACE_PATH},bind-propagation=rprivate`,
+    '--tmpfs',
+    `/tmp:rw,nosuid,nodev,mode=1777,size=512m,uid=${input.uid},gid=${input.gid}`,
+    '--tmpfs',
+    `${STATE_PATH}:rw,nosuid,nodev,mode=700,size=2048m,uid=${input.uid},gid=${input.gid}`,
+    '--entrypoint=/usr/bin/env',
+    input.image,
+    '-i',
+    ...containerEnvironment(),
+    '/bin/bash',
+    '--noprofile',
+    '--norc',
+    '-c',
+    COMMAND_WRAPPER,
+    'factory-command',
+    input.command,
+  ]
+}
+
+function isAlreadyRemoved(result: RunResult): boolean {
+  return /no such container/iu.test(result.stderr || result.stdout)
+}
+
+/**
+ * Run one repository-controlled command in a fresh container.
+ *
+ * The candidate sees one writable bind mount: its disposable workspace.
+ * Process ids, root files, HOME, XDG state, Corepack, npm, and pnpm caches are
+ * private to this invocation and disappear when the container exits.
+ */
+export async function runFactoryCommand(
+  workspace: string,
+  command: string,
+  options: RunFactoryCommandOptions,
+): Promise<RunResult> {
+  if (!command.trim()) throw new Error('factory command must not be empty')
+  if (!IMAGE_DIGEST_RE.test(options.image)) {
+    throw new Error(`factory command image must be pinned by sha256 digest: ${options.image}`)
+  }
+  if (!Number.isSafeInteger(options.timeoutMs) || options.timeoutMs <= 0) {
+    throw new Error(`factory command timeout must be a positive integer: ${options.timeoutMs}`)
+  }
+  const workspacePath = await realpath(workspace)
+  if (!(await stat(workspacePath)).isDirectory()) {
+    throw new Error(`factory command workspace is not a directory: ${workspacePath}`)
+  }
+  if (workspacePath.includes(',')) {
+    throw new Error(`factory command workspace path contains an unsupported comma: ${workspacePath}`)
+  }
+  const { uid, gid } = currentUser()
+  const name = `factory-command-${process.pid}-${randomUUID()}`
+  const control = await createControlEnvironment()
+  let commandResult: RunResult | undefined
+  let commandError: unknown
+  try {
+    commandResult = await run(
+      'docker',
+      dockerArgs({
+        name,
+        workspace: workspacePath,
+        command,
+        image: options.image,
+        network: options.network,
+        uid,
+        gid,
+      }),
+      {
+        env: control.env,
+        timeoutMs: options.timeoutMs,
+        killGraceMs: 2_000,
+        ...(options.signal ? { signal: options.signal } : {}),
+        ...(options.maxBuffer === undefined ? {} : { maxBuffer: options.maxBuffer }),
+      },
+    )
+  } catch (error) {
+    commandError = error
+  }
+
+  let cleanupError: unknown
+  try {
+    const cleanup = await run('docker', ['rm', '-f', name], {
+      env: control.env,
+      timeoutMs: CONTROL_TIMEOUT_MS,
+    })
+    if (cleanup.code !== 0 && !isAlreadyRemoved(cleanup)) {
+      cleanupError = new Error(
+        `factory command container cleanup failed (${cleanup.code}): ${(cleanup.stderr || cleanup.stdout).slice(-1000)}`,
+      )
+    }
+  } catch (error) {
+    cleanupError = error
+  }
+  await control.dispose()
+
+  if (commandError !== undefined && cleanupError !== undefined) {
+    throw new AggregateError(
+      [commandError, cleanupError],
+      'factory command and container cleanup both failed',
+    )
+  }
+  if (commandError !== undefined) throw commandError
+  if (cleanupError !== undefined) throw cleanupError
+  return commandResult!
+}