@lythos/skill-arena 0.15.7 → 0.16.1

package/src/runner.test.ts

@@ -1,9 +1,9 @@
-import { describe, test, expect } from 'bun:test'
-import { buildArenaPrompt, formatPlanOutput } from './runner'
+import { describe, it, expect } from 'bun:test'
+import { buildArenaPrompt, formatPlanOutput, runArenaFromToml, type ArenaIO } from './runner'
 import { buildExecutionPlan, parseArenaToml } from './arena-toml'
 
 describe('buildArenaPrompt — plan-mode (pure, no IO)', () => {
-  test('includes CWD, Deck, and output directory', () => {
+  it('includes CWD, Deck, and output directory', () => {
     const prompt = buildArenaPrompt({
       brief: 'Write a hello world function',
       cwd: '/tmp/arena-cell',
@@ -14,7 +14,7 @@ describe('buildArenaPrompt — plan-mode (pure, no IO)', () => {
     expect(prompt).toContain('Produce output to: /tmp/arena-cell/')
   })
 
-  test('includes decision-log.jsonl mandatory instructions', () => {
+  it('includes decision-log.jsonl mandatory instructions', () => {
     const prompt = buildArenaPrompt({
       brief: 'test',
       cwd: '/tmp/arena-cell',
@@ -27,7 +27,7 @@ describe('buildArenaPrompt — plan-mode (pure, no IO)', () => {
     expect(prompt).toContain('reason (why)')
   })
 
-  test('includes robustness and tools instructions', () => {
+  it('includes robustness and tools instructions', () => {
     const prompt = buildArenaPrompt({
       brief: 'test',
       cwd: '/tmp/arena-cell',
@@ -38,7 +38,7 @@ describe('buildArenaPrompt — plan-mode (pure, no IO)', () => {
     expect(prompt).toContain('.claude/skills/')
   })
 
-  test('task brief appears at the end', () => {
+  it('task brief appears at the end', () => {
     const prompt = buildArenaPrompt({
       brief: 'Generate a dark-mode CSS theme',
       cwd: '/tmp/arena-cell',
@@ -54,7 +54,7 @@ describe('buildArenaPrompt — plan-mode (pure, no IO)', () => {
     expect(briefIdx).toBeGreaterThan(toolsIdx)
   })
 
-  test('outputDir overrides default output path', () => {
+  it('outputDir overrides default output path', () => {
     const prompt = buildArenaPrompt({
       brief: 'test',
       cwd: '/tmp/arena-cell',
@@ -64,7 +64,7 @@ describe('buildArenaPrompt — plan-mode (pure, no IO)', () => {
     expect(prompt).toContain('Produce output to: /custom/output/')
   })
 
-  test('preflightReport included when provided', () => {
+  it('preflightReport included when provided', () => {
     const prompt = buildArenaPrompt({
       brief: 'test',
       cwd: '/tmp/arena-cell',
@@ -75,7 +75,7 @@ describe('buildArenaPrompt — plan-mode (pure, no IO)', () => {
     expect(prompt).toContain('✅ 3 skills linked, 0 missing')
   })
 
-  test('no preflight section when report not provided', () => {
+  it('no preflight section when report not provided', () => {
     const prompt = buildArenaPrompt({
       brief: 'test',
       cwd: '/tmp/arena-cell',
@@ -84,8 +84,267 @@ describe('buildArenaPrompt — plan-mode (pure, no IO)', () => {
     expect(prompt).not.toContain('Preflight:')
   })
 
-  test('prompt is deterministic — same inputs = same output', () => {
+  it('prompt is deterministic — same inputs = same output', () => {
     const opts = { brief: 'test', cwd: '/tmp/a', deckPath: '/tmp/d.toml' }
     expect(buildArenaPrompt(opts)).toBe(buildArenaPrompt(opts))
   })
 })
+
+describe('runArenaFromToml — dry-run mode (no fs/spawn/agent calls)', () => {
+  it('returns plan without executing cells', async () => {
+    const toml = parseArenaToml(`
+[arena]
+task = "Write a hello world function"
+criteria = ["completeness", "correctness"]
+runs_per_side = 1
+
+[[side]]
+name = "claude"
+player = "claude"
+deck = "/tmp/deck.toml"
+
+[[side]]
+name = "kimi"
+player = "kimi"
+deck = "/tmp/deck.toml"
+`)
+
+    const logs: string[] = []
+    const result = await runArenaFromToml({
+      toml,
+      taskPath: '/tmp/task.md',
+      dryRun: true,
+      log: (msg) => logs.push(msg),
+    })
+
+    expect('plan' in result).toBe(true)
+    const plan = (result as { plan: ReturnType<typeof buildExecutionPlan> }).plan
+    expect(plan.total_runs).toBe(2)
+    expect(plan.cells.length).toBe(2)
+    expect(logs.length).toBeGreaterThan(0)
+    expect(logs.some(l => l.includes('Dry-run'))).toBe(true)
+  })
+
+  it('dry-run does not call io.mkdir or io.agentSpawn', async () => {
+    const toml = parseArenaToml(`
+[arena]
+task = "Write a hello world function"
+criteria = ["completeness"]
+runs_per_side = 1
+
+[[side]]
+name = "claude"
+player = "claude"
+deck = "/tmp/deck.toml"
+
+[[side]]
+name = "kimi"
+player = "kimi"
+deck = "/tmp/deck.toml"
+`)
+
+    let mkdirCalled = false
+    let agentSpawnCalled = false
+
+    const mockIO: ArenaIO = {
+      mkdir: () => { mkdirCalled = true },
+      agentSpawn: async () => { agentSpawnCalled = true; return { stdout: '', stderr: '', durationMs: 0 } },
+    }
+
+    await runArenaFromToml({
+      toml,
+      taskPath: '/tmp/task.md',
+      dryRun: true,
+      io: mockIO,
+    })
+
+    expect(mkdirCalled).toBe(false)
+    expect(agentSpawnCalled).toBe(false)
+  })
+})
+
+describe('runArenaFromToml — single cell execution with mock agentSpawn', () => {
+  it('executes one cell and writes outputs via io', async () => {
+    const toml = parseArenaToml(`
+[arena]
+task = "Write a hello world function"
+criteria = ["completeness"]
+runs_per_side = 1
+
+[[side]]
+name = "claude"
+player = "claude"
+deck = "/tmp/deck.toml"
+
+[[side]]
+name = "kimi"
+player = "kimi"
+deck = "/tmp/deck.toml"
+`)
+
+    const files = new Map<string, string>()
+    const dirs = new Set<string>()
+
+    const mockIO: ArenaIO = {
+      log: () => {},
+      mkdir: (path: string) => { dirs.add(path) },
+      writeFile: (path: string, data: string) => { files.set(path, data) },
+      readFile: (path: string) => {
+        if (path === '/tmp/deck.toml') return 'skills = ["test"]'
+        throw new Error(`Unexpected read: ${path}`)
+      },
+      readdir: () => ['decision-log.jsonl'],
+      cp: () => {},
+      spawn: async () => ({ exitCode: 0, stderr: '' }),
+      agentSpawn: async () => ({
+        stdout: 'I wrote hello world',
+        stderr: '',
+        durationMs: 1234,
+      }),
+      exists: (path: string) => path === '/tmp/deck.toml',
+      chdir: () => {},
+    }
+
+    const result = await runArenaFromToml({
+      toml,
+      taskPath: '/tmp/task.md',
+      outDir: '/tmp/arena-out',
+      io: mockIO,
+    })
+
+    expect('manifest' in result).toBe(true)
+    const r = result as { manifest: { id: string; status: string }; artifactsDir: string }
+    expect(r.manifest.status).toBe('completed')
+    expect(r.artifactsDir).toBe('/tmp/arena-out')
+
+    // arena.json written twice (initial + final)
+    expect(files.has('/tmp/arena-out/arena.json')).toBe(true)
+    // agent stdout persisted
+    expect(files.has('/tmp/arena-out/runs/claude/run-1/agent-stdout.txt')).toBe(true)
+    expect(files.get('/tmp/arena-out/runs/claude/run-1/agent-stdout.txt')).toContain('I wrote hello world')
+    // judge-verdict.json written
+    expect(files.has('/tmp/arena-out/runs/claude/run-1/judge-verdict.json')).toBe(true)
+    // report.md written
+    expect(files.has('/tmp/arena-out/report.md')).toBe(true)
+    // directories created
+    expect(dirs.has('/tmp/arena-out')).toBe(true)
+    expect(dirs.has('/tmp/arena-out/runs/claude/run-1')).toBe(true)
+    expect(dirs.has('/tmp/arena-out/work/claude')).toBe(true)
+  })
+})
+
+describe('runArenaFromToml — error recovery path', () => {
+  it('cell exception produces ERROR verdict and continues', async () => {
+    const toml = parseArenaToml(`
+[arena]
+task = "Write a hello world function"
+criteria = ["completeness"]
+runs_per_side = 1
+
+[[side]]
+name = "claude"
+player = "claude"
+deck = "/tmp/deck.toml"
+
+[[side]]
+name = "kimi"
+player = "kimi"
+deck = "/tmp/deck.toml"
+`)
+
+    const files = new Map<string, string>()
+
+    let spawnCount = 0
+    const mockIO: ArenaIO = {
+      log: () => {},
+      mkdir: () => {},
+      writeFile: (path: string, data: string) => { files.set(path, data) },
+      readFile: (path: string) => {
+        if (path === '/tmp/deck.toml') return 'skills = ["test"]'
+        throw new Error(`Unexpected read: ${path}`)
+      },
+      readdir: () => [],
+      cp: () => {},
+      spawn: async () => ({ exitCode: 0, stderr: '' }),
+      agentSpawn: async () => {
+        spawnCount++
+        if (spawnCount === 1) throw new Error('Agent spawn failed')
+        return { stdout: 'ok', stderr: '', durationMs: 100 }
+      },
+      exists: (path: string) => path === '/tmp/deck.toml',
+      chdir: () => {},
+    }
+
+    const result = await runArenaFromToml({
+      toml,
+      taskPath: '/tmp/task.md',
+      outDir: '/tmp/arena-out',
+      io: mockIO,
+    })
+
+    expect('manifest' in result).toBe(true)
+    const r = result as { manifest: { status: string }; stats: { sideName: string; errorRate: number }[] }
+    expect(r.manifest.status).toBe('completed')
+    expect(r.stats.length).toBe(2)
+    const claudeStats = r.stats.find(s => s.sideName === 'claude')
+    expect(claudeStats!.errorRate).toBe(1)
+
+    const verdictPath = '/tmp/arena-out/runs/claude/run-1/judge-verdict.json'
+    expect(files.has(verdictPath)).toBe(true)
+    const verdict = JSON.parse(files.get(verdictPath)!)
+    expect(verdict.verdict).toBe('ERROR')
+    expect(verdict.reason).toContain('Agent spawn failed')
+  })
+
+  it('spawn non-zero exit logs warning but continues', async () => {
+    const toml = parseArenaToml(`
+[arena]
+task = "Write a hello world function"
+criteria = ["completeness"]
+runs_per_side = 1
+
+[[side]]
+name = "claude"
+player = "claude"
+deck = "/tmp/deck.toml"
+
+[[side]]
+name = "kimi"
+player = "kimi"
+deck = "/tmp/deck.toml"
+`)
+
+    const logs: string[] = []
+    const files = new Map<string, string>()
+
+    const mockIO: ArenaIO = {
+      log: (msg: string) => logs.push(msg),
+      mkdir: () => {},
+      writeFile: (path: string, data: string) => { files.set(path, data) },
+      readFile: (path: string) => {
+        if (path === '/tmp/deck.toml') return 'skills = ["test"]'
+        throw new Error(`Unexpected read: ${path}`)
+      },
+      readdir: () => [],
+      cp: () => {},
+      spawn: async () => ({ exitCode: 1, stderr: 'link failed' }),
+      agentSpawn: async () => ({
+        stdout: 'done',
+        stderr: '',
+        durationMs: 100,
+      }),
+      exists: (path: string) => path === '/tmp/deck.toml',
+      chdir: () => {},
+    }
+
+    const result = await runArenaFromToml({
+      toml,
+      taskPath: '/tmp/task.md',
+      outDir: '/tmp/arena-out',
+      io: mockIO,
+    })
+
+    expect('manifest' in result).toBe(true)
+    expect(logs.some(l => l.includes('deck link') && l.includes('exit 1'))).toBe(true)
+  })
+})

package/src/runner.ts

@@ -17,6 +17,42 @@ import { aggregateAllStats } from './stats'
 import type { SideStats } from './stats'
 import { buildCopyPlan } from './preflight'
 
+// ── ArenaIO interface (Intent/Plan/Execute fractal pattern) ───────────────
+
+export interface ArenaIO {
+  log?: (msg: string) => void
+  mkdir?: (path: string, opts?: { recursive?: boolean }) => void
+  writeFile?: (path: string, data: string) => void
+  readFile?: (path: string) => string
+  readdir?: (path: string) => string[]
+  cp?: (src: string, dest: string, opts?: { recursive?: boolean }) => void
+  spawn?: (cmd: string[], opts: { cwd: string; env?: Record<string, string> }) => Promise<{ exitCode: number | null; stderr: string }>
+  agentSpawn?: (opts: { player: string; cwd: string; brief: string; timeoutMs: number }) => Promise<{ stdout: string; stderr: string; durationMs: number }>
+  exists?: (path: string) => boolean
+  chdir?: (cwd: string) => void
+}
+
+export const defaultArenaIO: ArenaIO = {
+  log: (msg: string) => { console.log(msg) },
+  mkdir: (path: string, opts?: { recursive?: boolean }) => mkdirSync(path, opts),
+  writeFile: (path: string, data: string) => writeFileSync(path, data, 'utf-8'),
+  readFile: (path: string) => readFileSync(path, 'utf-8'),
+  readdir: (path: string) => readdirSync(path),
+  cp: (src: string, dest: string, opts?: { recursive?: boolean }) => cpSync(src, dest, opts),
+  spawn: async (cmd: string[], opts: { cwd: string; env?: Record<string, string> }) => {
+    const proc = Bun.spawn(cmd, { cwd: opts.cwd, env: opts.env })
+    await proc.exited
+    const stderr = await new Response(proc.stderr).text()
+    return { exitCode: proc.exitCode, stderr }
+  },
+  agentSpawn: async (opts: { player: string; cwd: string; brief: string; timeoutMs: number }) => {
+    const agent = useAgent(opts.player)
+    return agent.spawn({ cwd: opts.cwd, brief: opts.brief, timeoutMs: opts.timeoutMs })
+  },
+  exists: (path: string) => existsSync(path),
+  chdir: (cwd: string) => { process.chdir(cwd) },
+}
+
 // ── Helpers ───────────────────────────────────────────────────────────────
 
 function stamp(): string {
@@ -33,18 +69,18 @@ export interface ArenaResult {
 
 // ── Task + judge text resolution (no parsing — natural language) ──────────
 
-function resolveTaskText(toml: ArenaToml, configDir?: string): string {
+function resolveTaskText(toml: ArenaToml, io: Required<Pick<ArenaIO, 'exists' | 'readFile'>>, configDir?: string): string {
   const p = toml.arena.task
   const candidate = configDir ? resolve(configDir, p) : resolve(p)
-  if (existsSync(candidate)) return readFileSync(candidate, 'utf-8')
+  if (io.exists(candidate)) return io.readFile(candidate)
   return p
 }
 
-function resolveJudgeText(toml: ArenaToml, configDir?: string): string | null {
+function resolveJudgeText(toml: ArenaToml, io: Required<Pick<ArenaIO, 'exists' | 'readFile'>>, configDir?: string): string | null {
   if (toml.arena.judge) {
     const p = toml.arena.judge
     const candidate = configDir ? resolve(configDir, p) : resolve(p)
-    if (existsSync(candidate)) return readFileSync(candidate, 'utf-8')
+    if (io.exists(candidate)) return io.readFile(candidate)
     return p
   }
   if (toml.arena.criteria && toml.arena.criteria.length > 0) {
@@ -116,8 +152,14 @@ export async function runArenaFromToml(opts: {
   dryRun?: boolean
   log?: (msg: string) => void
   configDir?: string
+  io?: ArenaIO
 }): Promise<ArenaResult | { plan: ReturnType<typeof buildExecutionPlan> }> {
   const { toml, taskPath, outDir, dryRun, log, configDir } = opts
+  const io: ArenaIO = {
+    ...defaultArenaIO,
+    ...opts.io,
+    log: log ?? opts.io?.log ?? defaultArenaIO.log,
+  }
 
   const resolvePath = (p: string) => {
     if (p.startsWith('/')) return p
@@ -125,7 +167,19 @@ export async function runArenaFromToml(opts: {
     return resolve(p)
   }
 
-  const taskText = resolveTaskText(toml, configDir)
+  const ioWithDefaults = {
+    exists: io.exists!,
+    readFile: io.readFile!,
+    writeFile: io.writeFile!,
+    mkdir: io.mkdir!,
+    readdir: io.readdir!,
+    cp: io.cp!,
+    spawn: io.spawn!,
+    agentSpawn: io.agentSpawn!,
+    chdir: io.chdir!,
+  }
+
+  const taskText = resolveTaskText(toml, ioWithDefaults, configDir)
   const resolvedToml: ArenaToml = {
     ...toml,
     side: toml.side.map(s => ({ ...s, deck: resolvePath(s.deck) })),
@@ -134,7 +188,7 @@ export async function runArenaFromToml(opts: {
   const plan = buildExecutionPlan(resolvedToml)
 
   if (dryRun) {
-    for (const line of formatPlanOutput(plan)) log?.(line)
+    for (const line of formatPlanOutput(plan)) io.log?.(line)
     return { plan }
   }
 
@@ -158,29 +212,29 @@ export async function runArenaFromToml(opts: {
     status: 'running',
   })
 
-  mkdirSync(artifactsDir, { recursive: true })
-  writeFileSync(join(artifactsDir, 'arena.json'), JSON.stringify(manifest, null, 2) + '\n')
+  ioWithDefaults.mkdir(artifactsDir, { recursive: true })
+  ioWithDefaults.writeFile(join(artifactsDir, 'arena.json'), JSON.stringify(manifest, null, 2) + '\n')
 
-  const judgeText = resolveJudgeText(resolvedToml, configDir)
+  const judgeText = resolveJudgeText(resolvedToml, ioWithDefaults, configDir)
   const judgeInput: JudgeInput | undefined = judgeText
     ? { criteria: judgeText, task_context: taskText.slice(0, 500) }
     : undefined
 
-  // ── Per-cell: agent.spawn directly, no AgentScenario/parseAgentMd ────
+  // ── Per-cell: agent.spawn via IO injection ─────────────────────────────
   const verdictsBySide = new Map<string, JudgeVerdict[]>()
 
   for (const cell of plan.cells) {
     const cellDir = join(artifactsDir, 'runs', cell.side, `run-${cell.run}`)
-    mkdirSync(cellDir, { recursive: true })
+    ioWithDefaults.mkdir(cellDir, { recursive: true })
 
     const workDir = join(artifactsDir, 'work', cell.side)
-    mkdirSync(workDir, { recursive: true })
+    ioWithDefaults.mkdir(workDir, { recursive: true })
     const originalCwd = process.cwd()
 
     try {
       // Setup: deck + AGENTS.md + link
-      writeFileSync(join(workDir, 'skill-deck.toml'), readFileSync(cell.deck, 'utf-8'))
-      writeFileSync(join(workDir, 'AGENTS.md'), [
+      ioWithDefaults.writeFile(join(workDir, 'skill-deck.toml'), ioWithDefaults.readFile(cell.deck))
+      ioWithDefaults.writeFile(join(workDir, 'AGENTS.md'), [
         '# Arena Test Environment',
         `**Side**: ${cell.side}`, `**Player**: ${cell.player}`, `**Run**: ${cell.run}`,
         '## How This Works',
@@ -188,55 +242,54 @@ export async function runArenaFromToml(opts: {
         '- Complete the task using available skills. Output to this directory.',
         '- MANDATORY: write decision-log.jsonl (see prompt for schema).',
       ].join('\n'))
-      const linkProc = Bun.spawn(
+      const linkProc = await ioWithDefaults.spawn(
         ['bunx', '@lythos/skill-deck', 'link'],
         { cwd: workDir, env: { ...process.env, HOME: process.env.HOME! } },
       )
-      await linkProc.exited
-      log?.(`[arena] deck link for ${cell.side}: exit ${linkProc.exitCode}`)
+      io.log?.(`[arena] deck link for ${cell.side}: exit ${linkProc.exitCode}`)
 
-      process.chdir(workDir)
+      ioWithDefaults.chdir(workDir)
 
-      // Direct agent.spawn (no parseAgentMd, no AgentScenario)
-      const agent = useAgent(resolvePlayer(cell.player))
+      // Agent spawn via IO injection
       const fullPrompt = buildArenaPrompt({
         brief: taskText,
         cwd: workDir,
         deckPath: cell.deck,
         outputDir: workDir,
       })
-      const agentResult = await agent.spawn({
+      const agentResult = await ioWithDefaults.agentSpawn({
+        player: resolvePlayer(cell.player),
         cwd: workDir,
         brief: fullPrompt,
         timeoutMs: 300000,
       })
 
-      process.chdir(originalCwd)
+      ioWithDefaults.chdir(originalCwd)
 
       // Persist agent output
       const sanitizer = createSanitizer({ projectRoot: process.cwd(), homeDir: homedir(), workDir })
-      writeFileSync(join(cellDir, 'agent-stdout.txt'), sanitizer.sanitize(agentResult.stdout), 'utf-8')
-      if (agentResult.stderr) writeFileSync(join(cellDir, 'agent-stderr.txt'), sanitizer.sanitize(agentResult.stderr), 'utf-8')
+      ioWithDefaults.writeFile(join(cellDir, 'agent-stdout.txt'), sanitizer.sanitize(agentResult.stdout))
+      if (agentResult.stderr) ioWithDefaults.writeFile(join(cellDir, 'agent-stderr.txt'), sanitizer.sanitize(agentResult.stderr))
 
       // Copy artifacts
       const skipSet = new Set(['.claude', 'skill-deck.toml', 'skill-deck.lock', 'AGENTS.md'])
       try {
-        const entries = readdirSync(workDir)
+        const entries = ioWithDefaults.readdir(workDir)
         const copyPlan = buildCopyPlan(workDir, cellDir, entries, skipSet)
         for (const { src, dest, name } of copyPlan) {
-          try { cpSync(src, dest, { recursive: true }) } catch (e) {
-            log?.(`⚠️ Failed to copy agent output: ${name} — ${e instanceof Error ? e.message : e}`)
+          try { ioWithDefaults.cp(src, dest, { recursive: true }) } catch (e) {
+            io.log?.(`⚠️ Failed to copy agent output: ${name} — ${e instanceof Error ? e.message : e}`)
           }
         }
       } catch (e) {
-        log?.(`⚠️ Failed to read agent workdir for copy: ${e instanceof Error ? e.message : e}`)
+        io.log?.(`⚠️ Failed to read agent workdir for copy: ${e instanceof Error ? e.message : e}`)
       }
 
       // Evidence
       const checkpoints = readCheckpoints(workDir)
       let artifactFiles: string[] = []
       try {
-        for (const e of readdirSync(workDir)) {
+        for (const e of ioWithDefaults.readdir(workDir)) {
           if (!e.startsWith('.') && !skipSet.has(e) && e !== 'agent-stdout.txt' && e !== 'agent-stderr.txt' && e !== 'judge-verdict.json' && e !== '_checkpoints') {
             artifactFiles.push(e)
           }
@@ -259,7 +312,7 @@ export async function runArenaFromToml(opts: {
         v = { verdict: 'ERROR' as const, reason: 'No judge criteria provided', criteria: [] }
       }
 
-      writeFileSync(join(cellDir, 'judge-verdict.json'), JSON.stringify({
+      ioWithDefaults.writeFile(join(cellDir, 'judge-verdict.json'), JSON.stringify({
         ...v,
         agent_stdout: agentResult.stdout.slice(0, 5000),
         agent_stderr: agentResult.stderr.slice(0, 1000),
@@ -274,7 +327,7 @@ export async function runArenaFromToml(opts: {
         reason: `Runner exception: ${e instanceof Error ? e.message : String(e)}`,
         criteria: [],
       }
-      writeFileSync(join(cellDir, 'judge-verdict.json'), JSON.stringify(errVerdict, null, 2) + '\n')
+      ioWithDefaults.writeFile(join(cellDir, 'judge-verdict.json'), JSON.stringify(errVerdict, null, 2) + '\n')
       if (!verdictsBySide.has(cell.side)) verdictsBySide.set(cell.side, [])
       verdictsBySide.get(cell.side)!.push(errVerdict)
     }
@@ -288,10 +341,10 @@ export async function runArenaFromToml(opts: {
   }
   const judge = useAgent(resolved[0]?.platform ?? 'claude')
   const report = await runComparativeJudge({ manifest, verdicts: flatVerdicts, judge, workdir: artifactsDir })
-  writeReport(artifactsDir, manifest, report, stats)
+  writeReport(artifactsDir, manifest, report, stats, ioWithDefaults)
 
   const finalManifest = ArenaManifest.parse({ ...manifest, status: 'completed' })
-  writeFileSync(join(artifactsDir, 'arena.json'), JSON.stringify(finalManifest, null, 2) + '\n')
+  ioWithDefaults.writeFile(join(artifactsDir, 'arena.json'), JSON.stringify(finalManifest, null, 2) + '\n')
 
   return { manifest: finalManifest, report, stats, artifactsDir }
 }
@@ -319,7 +372,7 @@ export async function runArena(opts: {
 
 // ── Report ────────────────────────────────────────────────────────────────
 
-function writeReport(dir: string, manifest: ArenaManifestType, report: any, stats: SideStats[]): void {
+function writeReport(dir: string, manifest: ArenaManifestType, report: any, stats: SideStats[], io: Required<Pick<ArenaIO, 'writeFile'>>): void {
   const lines: string[] = [
     `# Arena Report: ${manifest.id}`, '',
     `**Task**: ${manifest.task}`,
@@ -331,7 +384,7 @@ function writeReport(dir: string, manifest: ArenaManifestType, report: any, stat
     '## Key Findings', '', ...(report.key_findings ?? []).map((f: string) => `- ${f}`), '',
     '## Recommendations', '', ...(report.recommendations ?? []).map((r: any) => `- **${r.audience}**: ${r.recommendation}`),
   ]
-  writeFileSync(join(dir, 'report.md'), lines.join('\n') + '\n')
+  io.writeFile(join(dir, 'report.md'), lines.join('\n') + '\n')
 }
 
 function renderStatsTable(stats: SideStats[]): string {

package/src/stats.test.ts

@@ -1,4 +1,4 @@
-import { describe, test, expect } from 'bun:test'
+import { describe, it, expect } from 'bun:test'
 import { aggregateSideStats, aggregateAllStats } from './stats'
 import type { JudgeVerdict } from '@lythos/test-utils/schema'
 
@@ -14,7 +14,7 @@ function makeVerdict(overrides?: Partial<JudgeVerdict>): JudgeVerdict {
 // ── aggregateSideStats ─────────────────────────────────────────────────────
 
 describe('aggregateSideStats', () => {
-  test('single run: passRate=1, no variance', () => {
+  it('single run: passRate=1, no variance', () => {
     const stats = aggregateSideStats('test', [makeVerdict()])
     expect(stats.sideName).toBe('test')
     expect(stats.runs).toBe(1)
@@ -23,7 +23,7 @@ describe('aggregateSideStats', () => {
     expect(stats.errorRate).toBe(0)
   })
 
-  test('3 runs: 2 PASS, 1 FAIL', () => {
+  it('3 runs: 2 PASS, 1 FAIL', () => {
     const verdicts = [
       makeVerdict(),
       makeVerdict(),
@@ -34,7 +34,7 @@ describe('aggregateSideStats', () => {
     expect(stats.failRate).toBeCloseTo(1 / 3)
   })
 
-  test('confidence: mean across runs', () => {
+  it('confidence: mean across runs', () => {
     const verdicts = [
       makeVerdict({ confidence: 90 }),
       makeVerdict({ confidence: 80 }),
@@ -45,13 +45,13 @@ describe('aggregateSideStats', () => {
     expect(stats.confidenceVariance).toBeCloseTo(100) // (100+0+100)/2 = 100
   })
 
-  test('confidence: null when no verdict has it', () => {
+  it('confidence: null when no verdict has it', () => {
     const stats = aggregateSideStats('test', [makeVerdict(), makeVerdict()])
     expect(stats.meanConfidence).toBeNull()
     expect(stats.confidenceVariance).toBeNull()
   })
 
-  test('per-criterion pass rate', () => {
+  it('per-criterion pass rate', () => {
     const verdicts = [
       makeVerdict({ criteria: [{ name: 'accuracy', passed: true }] }),
       makeVerdict({ criteria: [{ name: 'accuracy', passed: false }] }),
@@ -63,7 +63,7 @@ describe('aggregateSideStats', () => {
     expect(stats.criteria[0].mean).toBeCloseTo(2 / 3)
   })
 
-  test('per-criterion scores: mean and variance', () => {
+  it('per-criterion scores: mean and variance', () => {
     const verdicts = [
       makeVerdict({ scores: { coverage: 5, relevance: 4 } }),
       makeVerdict({ scores: { coverage: 3, relevance: 4 } }),
@@ -75,14 +75,14 @@ describe('aggregateSideStats', () => {
     expect(stats.scoreByCriterion.relevance.variance).toBe(0) // all 4s
   })
 
-  test('zero runs: all zeros', () => {
+  it('zero runs: all zeros', () => {
     const stats = aggregateSideStats('empty', [])
     expect(stats.runs).toBe(0)
     expect(stats.passRate).toBe(0)
     expect(stats.meanConfidence).toBeNull()
   })
 
-  test('handles ERROR verdicts correctly', () => {
+  it('handles ERROR verdicts correctly', () => {
     const verdicts = [
       makeVerdict(),
       makeVerdict({ verdict: 'ERROR', reason: 'parse failed' }),
@@ -96,7 +96,7 @@ describe('aggregateSideStats', () => {
 // ── aggregateAllStats ──────────────────────────────────────────────────────
 
 describe('aggregateAllStats', () => {
-  test('aggregates multiple sides', () => {
+  it('aggregates multiple sides', () => {
     const map = new Map<string, JudgeVerdict[]>()
     map.set('side-a', [makeVerdict(), makeVerdict()])
     map.set('side-b', [makeVerdict({ verdict: 'FAIL', reason: 'nope' })])