@lythos/skill-arena 0.15.6 → 0.16.0

package/README.md

@@ -16,20 +16,20 @@
 ```bash
 bun add -d @lythos/skill-arena
 # or use directly
-bunx @lythos/skill-arena@0.15.6 <command>
+bunx @lythos/skill-arena@0.16.0 <command>
 ```
 
 ## Quick Start
 
 ```bash
 # single — test one deck (most common)
-bunx @lythos/skill-arena@0.15.6 single \
+bunx @lythos/skill-arena@0.16.0 single \
   --deck ./examples/decks/scout.toml \
   --brief "Generate auth flow diagram" \
   --out ./output
 
 # single with explicit player
-bunx @lythos/skill-arena@0.15.6 single \
+bunx @lythos/skill-arena@0.16.0 single \
   --deck ./examples/decks/scout.toml \
   --brief "Generate auth flow diagram" \
   --player kimi \
@@ -37,10 +37,10 @@ bunx @lythos/skill-arena@0.15.6 single \
 
 # cross-deck vs — compare two decks (agent-orchestrated)
 # Create arena.toml declaring sides with different decks, then:
-bunx @lythos/skill-arena@0.15.6 vs --config ./arena.toml
+bunx @lythos/skill-arena@0.16.0 vs --config ./arena.toml
 
 # cross-player vs — compare kimi vs codex (CLI only)
-bunx @lythos/skill-arena@0.15.6 vs --config ./arena.toml --player kimi
+bunx @lythos/skill-arena@0.16.0 vs --config ./arena.toml --player kimi
 ```
 
 **What happens**: Agent creates isolated `/tmp` workdir per side, `deck link` skills, spawns parallel subagents, collects artifacts, judge scores outputs. Parent deck restored after.
@@ -50,14 +50,14 @@ bunx @lythos/skill-arena@0.15.6 vs --config ./arena.toml --player kimi
 ### `single` — one deck, one task
 
 ```bash
-bunx @lythos/skill-arena@0.15.6 single \
+bunx @lythos/skill-arena@0.16.0 single \
   --deck ./deck.toml \
   --brief "Produce a .docx report with radar chart" \
   --timeout 600000 \
   --out ./output
 
 # with explicit player
-bunx @lythos/skill-arena@0.15.6 single \
+bunx @lythos/skill-arena@0.16.0 single \
   --deck ./deck.toml \
   --brief "Produce a .docx report with radar chart" \
   --player kimi \
@@ -67,14 +67,14 @@ bunx @lythos/skill-arena@0.15.6 single \
 ### `vs` — multi-deck comparison
 
 ```bash
-bunx @lythos/skill-arena@0.15.6 vs --config ./arena.toml
-bunx @lythos/skill-arena@0.15.6 vs --config ./arena.toml --dry-run
+bunx @lythos/skill-arena@0.16.0 vs --config ./arena.toml
+bunx @lythos/skill-arena@0.16.0 vs --config ./arena.toml --dry-run
 ```
 
 ### `prepare-workdir` — isolate + link skills (agent-orchestrated)
 
 ```bash
-bunx @lythos/skill-arena@0.15.6 prepare-workdir \
+bunx @lythos/skill-arena@0.16.0 prepare-workdir \
   --deck ./skill-deck.toml \
   --out /tmp/arena-side-a \
   --brief "task description"
@@ -85,7 +85,7 @@ Creates `/tmp`-isolated workdir with deck copied, AGENTS.md written, and `deck l
 ### `archive` — collect agent outputs (agent-orchestrated)
 
 ```bash
-bunx @lythos/skill-arena@0.15.6 archive \
+bunx @lythos/skill-arena@0.16.0 archive \
   --from /tmp/arena-side-a \
   --to ./playground/output \
   --sides side-a
@@ -96,7 +96,7 @@ Copies agent artifacts from workdir(s) to output, skipping internal files (`.cla
 ### `viz` — render results (WIP — HTML report generation pending)
 
 ```bash
-bunx @lythos/skill-arena@0.15.6 viz runs/arena-<id>/
+bunx @lythos/skill-arena@0.16.0 viz runs/arena-<id>/
 ```
 
 ## Parameters

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lythos/skill-arena",
-  "version": "0.15.6",
+  "version": "0.16.0",
   "description": "Skill Arena — benchmark skill effectiveness with controlled-variable comparison",
   "keywords": [
     "ai-agent",
@@ -42,15 +42,15 @@
     "bun": ">=1.0.0"
   },
   "dependencies": {
-    "@lythos/cold-pool": "^0.15.6",
-    "@lythos/infra": "^0.15.6",
-    "@lythos/test-utils": "^0.15.6",
+    "@lythos/cold-pool": "^0.16.0",
+    "@lythos/infra": "^0.16.0",
+    "@lythos/test-utils": "^0.16.0",
     "zod": "^3.24.0",
     "zod-to-json-schema": "^3.25.2"
   },
   "optionalDependencies": {
-    "@lythos/agent-adapter-claude-sdk": "^0.15.6",
-    "@lythos/agent-adapter-deepseek-serve": "^0.15.6",
-    "@lythos/agent-adapter-codex": "^0.15.6"
+    "@lythos/agent-adapter-claude-sdk": "^0.16.0",
+    "@lythos/agent-adapter-deepseek-serve": "^0.16.0",
+    "@lythos/agent-adapter-codex": "^0.16.0"
   }
 }

package/src/cli.test.ts

@@ -0,0 +1,118 @@
+import { describe, it, expect } from 'bun:test'
+import { main, defaultArenaCliIO, type ArenaCliIO } from './cli'
+
+// ─── Helpers ───────────────────────────────────────────────────────────────
+
+async function catchExitAsync(fn: () => Promise<void>): Promise<number | undefined> {
+  let exitCode: number | undefined
+  try { await fn() } catch (e: any) {
+    if (!String(e).includes('EXIT:')) throw e
+    const m = String(e).match(/EXIT:(\d+)/)
+    if (m) exitCode = parseInt(m[1], 10)
+  }
+  return exitCode
+}
+
+function mockIO(): { io: Required<ArenaCliIO>; logs: string[]; errors: string[]; warns: string[] } {
+  const logs: string[] = []
+  const errors: string[] = []
+  const warns: string[] = []
+  const io: Required<ArenaCliIO> = {
+    log: (msg: string) => logs.push(msg),
+    error: (msg: string) => errors.push(msg),
+    warn: (msg: string) => warns.push(msg),
+    exit: (code: number) => { throw new Error(`EXIT:${code}`) },
+  }
+  return { io, logs, errors, warns }
+}
+
+// ─── Tests ─────────────────────────────────────────────────────────────────
+
+describe('main', () => {
+  it('shows help on --help', async () => {
+    const { io, logs, errors } = mockIO()
+    const exitCode = await catchExitAsync(async () => {
+      await main(['--help'], io)
+    })
+    expect(exitCode).toBe(0)
+    expect(logs.length).toBeGreaterThan(0)
+    expect(logs[0]).toContain('lythoskill-arena')
+    expect(errors.length).toBe(0)
+  })
+
+  it('shows help on -h', async () => {
+    const { io, logs, errors } = mockIO()
+    const exitCode = await catchExitAsync(async () => {
+      await main(['-h'], io)
+    })
+    expect(exitCode).toBe(0)
+    expect(logs.length).toBeGreaterThan(0)
+    expect(logs[0]).toContain('lythoskill-arena')
+    expect(errors.length).toBe(0)
+  })
+
+  it('shows help on no args', async () => {
+    const { io, logs, errors } = mockIO()
+    const exitCode = await catchExitAsync(async () => {
+      await main([], io)
+    })
+    expect(exitCode).toBe(0)
+    expect(logs.length).toBeGreaterThan(0)
+    expect(errors.length).toBe(0)
+  })
+
+  it('errors on unknown command', async () => {
+    const { io, logs, errors } = mockIO()
+    const exitCode = await catchExitAsync(async () => {
+      await main(['bogus'], io)
+    })
+    expect(exitCode).toBe(1)
+    expect(errors.length).toBeGreaterThan(0)
+    expect(errors[0]).toContain('Unknown command')
+    expect(errors[0]).toContain('bogus')
+  })
+})
+
+describe('singleRun', () => {
+  it('errors when --deck is missing', async () => {
+    const { io, logs, errors } = mockIO()
+    const exitCode = await catchExitAsync(async () => {
+      await main(['single', '--brief', 'test task'], io)
+    })
+    expect(exitCode).toBe(1)
+    expect(errors.length).toBeGreaterThan(0)
+    expect(errors[0]).toContain('--deck')
+    expect(errors[0]).toContain('required')
+  })
+
+  it('errors when both --task and --brief are missing', async () => {
+    const { io, logs, errors } = mockIO()
+    const exitCode = await catchExitAsync(async () => {
+      await main(['single', '--deck', './some-deck.toml'], io)
+    })
+    expect(exitCode).toBe(1)
+    expect(errors.length).toBeGreaterThan(0)
+    expect(errors[0]).toContain('--task')
+    expect(errors[0]).toContain('--brief')
+  })
+
+  it('errors when --brief is empty string', async () => {
+    const { io, logs, errors } = mockIO()
+    const exitCode = await catchExitAsync(async () => {
+      await main(['single', '--deck', './some-deck.toml', '--brief', ''], io)
+    })
+    expect(exitCode).toBe(1)
+    expect(errors.length).toBeGreaterThan(0)
+    expect(errors[0]).toContain('--task')
+    expect(errors[0]).toContain('--brief')
+  })
+})
+
+describe('defaultArenaCliIO', () => {
+  it('has all required functions', () => {
+    expect(typeof defaultArenaCliIO.log).toBe('function')
+    expect(typeof defaultArenaCliIO.error).toBe('function')
+    expect(typeof defaultArenaCliIO.warn).toBe('function')
+    expect(typeof defaultArenaCliIO.exit).toBe('function')
+  })
+})

package/src/cli.ts

@@ -8,6 +8,22 @@ import { parseArenaToml, buildExecutionPlan } from './arena-toml'
 import { buildArchiveSidePlan, buildCopyPlan, buildPreparePlan, parseDeckSkills } from './preflight'
 import { checkSkillExistence, formatSkillWarnings, resolveColdPoolDir } from './preflight'
 
+// ─── ArenaCliIO interface (injected for testability) ───────────────────────
+
+export interface ArenaCliIO {
+  log?: (msg: string) => void
+  error?: (msg: string) => void
+  warn?: (msg: string) => void
+  exit?: (code: number) => never
+}
+
+export const defaultArenaCliIO: Required<ArenaCliIO> = {
+  log: console.log,
+  error: console.error,
+  warn: console.warn,
+  exit: (code) => { process.exit(code) },
+}
+
 // ─── fetchWithProxy (infra dependency, no package boundary) ─────────────────
 
 async function fetchWithProxy(url: string, init?: RequestInit): Promise<Response> {
@@ -82,9 +98,10 @@ function validateLinkResult(exitCode: number | null, stderr: string): { ok: bool
 }
 
 // ═══════════════════════════════════════════════════════════════════════════
-export async function main(args: string[] = process.argv.slice(2)) {
+export async function main(args: string[] = process.argv.slice(2), io: ArenaCliIO = defaultArenaCliIO) {
+  const { log, exit } = { ...defaultArenaCliIO, ...io }
   if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
-    console.log(`lythoskill-arena — skill evaluation CLI
+    log(`lythoskill-arena — skill evaluation CLI
 
 Usage:
   lythoskill-arena single|vs|viz <options>
@@ -103,28 +120,30 @@ Examples:
   lythoskill-arena prepare-workdir --deck ./decks/scout.toml --out /tmp/arena-20260517-side-a
   lythoskill-arena archive --from /tmp/arena-20260517 --to playground/arena-20260517 --sides side-a,side-b
 `)
-    process.exit(0)
+    exit(0)
   }
-  return cli(args)
+  return cli(args, io)
 }
 
-function cli(args: string[]) {
+function cli(args: string[], io: ArenaCliIO) {
   const cmd = args[0]
   const rest = args.slice(1)
 
-  if (cmd === 'vs' || cmd === 'compare') return vsRun(rest)
-  if (cmd === 'single' || cmd === 'run') return singleRun(rest)
-  if (cmd === 'viz') return vizRun(rest)
-  if (cmd === 'prepare-workdir') return prepareWorkdir(rest)
-  if (cmd === 'archive') return archiveRun(rest)
+  if (cmd === 'vs' || cmd === 'compare') return vsRun(rest, io)
+  if (cmd === 'single' || cmd === 'run') return singleRun(rest, io)
+  if (cmd === 'viz') return vizRun(rest, io)
+  if (cmd === 'prepare-workdir') return prepareWorkdir(rest, io)
+  if (cmd === 'archive') return archiveRun(rest, io)
 
-  console.error(`Unknown command: ${cmd}`)
-  process.exit(1)
+  const { error, exit } = { ...defaultArenaCliIO, ...io }
+  error(`Unknown command: ${cmd}`)
+  exit(1)
 }
 
 // ── single: single-player deck test (exec shortcut) ──────────────────────
 
-async function singleRun(args: string[]) {
+async function singleRun(args: string[], io: ArenaCliIO) {
+  const { log, error, warn, exit } = { ...defaultArenaCliIO, ...io }
   const opts: Record<string, string | undefined> = {}
   for (let i = 0; i < args.length; i++) {
     if (args[i] === '--task' || args[i] === '-t') opts.task = args[++i]
@@ -136,7 +155,7 @@ async function singleRun(args: string[]) {
   }
 
   if (!opts.deck) {
-    console.error(`❌ --deck <path|url> is required.
+    error(`❌ --deck <path|url> is required.
    --deck accepts local paths and http/https URLs (auto-fetched).
 
    Example (no local file needed — URL is auto-fetched):
@@ -146,10 +165,10 @@ async function singleRun(args: string[]) {
 
    Or with a local deck file you already have:
      lythoskill-arena single --deck ./examples/decks/scout.toml --brief "your task"`)
-    process.exit(1)
+    exit(1)
   }
   if (!opts.task && (!opts.brief || !opts.brief.trim())) {
-    console.error(`❌ --task <path> or --brief "<text>" is required.
+    error(`❌ --task <path> or --brief "<text>" is required.
    --task reads a .agent.md scenario file; --brief takes inline text.
 
    Example (no local file needed — URL is auto-fetched):
@@ -159,24 +178,24 @@ async function singleRun(args: string[]) {
 
    Or with a local deck file:
      lythoskill-arena single --deck ./examples/decks/scout.toml --brief "your task"`)
-    process.exit(1)
+    exit(1)
   }
 
   let resolvedTaskPath: string | undefined
   if (opts.task) {
     resolvedTaskPath = resolve(opts.task)
     if (!existsSync(resolvedTaskPath)) {
-      console.error(`❌ Task file not found: ${resolvedTaskPath}
+      error(`❌ Task file not found: ${resolvedTaskPath}
    Use --brief for inline tasks, or point --task to an existing .agent.md file.
    Format: name + description + Given/When/Then sections.
 
    Example (URL):  lythoskill-arena single --brief "your task" --deck https://raw.githubusercontent.com/lythos-labs/lythoskill/main/examples/decks/scout.toml
    Or (local):     lythoskill-arena single --brief "your task" --deck ./examples/decks/scout.toml`)
-      process.exit(1)
+      exit(1)
     }
     const raw = readFileSync(resolvedTaskPath, 'utf-8')
     if (!raw.startsWith('---')) {
-      console.error(`❌ Invalid .agent.md: missing frontmatter (must start with "---")
+      error(`❌ Invalid .agent.md: missing frontmatter (must start with "---")
    Correct format:
    ---
    name: my-scenario
@@ -189,13 +208,13 @@ async function singleRun(args: string[]) {
    ...
    ## Then
    ...`)
-      process.exit(1)
+      exit(1)
     }
     if (!raw.includes('## When')) {
-      console.error(`❌ Invalid .agent.md: missing "## When" section.
+      error(`❌ Invalid .agent.md: missing "## When" section.
    The ## When section defines what the agent should do.
    See template: playground/arena-one-shot/TASK-arena.agent.md`)
-      process.exit(1)
+      exit(1)
     }
   }
 
@@ -213,7 +232,7 @@ async function singleRun(args: string[]) {
     }
     const { mirrorUrls, isLikelyGitHubBlock } = await import('../../lythoskill-cold-pool/src/mirror.js')
     const dest = resolve(process.cwd(), 'arena-deck.toml')
-    console.log(`📥 Fetching arena deck: ${url}`)
+    log(`📥 Fetching arena deck: ${url}`)
     let res: Response | undefined
     let allFailed = true
 
@@ -222,7 +241,7 @@ async function singleRun(args: string[]) {
     if (!res?.ok) {
       for (const mirrorUrl of mirrorUrls(url)) {
         try {
-          console.log(`   ↳ trying mirror: ${mirrorUrl}`)
+          log(`   ↳ trying mirror: ${mirrorUrl}`)
           const r = await fetchWithProxy(mirrorUrl, { signal: AbortSignal.timeout(30_000) })
           if (r.ok) { res = r; allFailed = false; break }
         } catch {}
@@ -231,21 +250,21 @@ async function singleRun(args: string[]) {
 
     if (!res?.ok) {
       const errorDetail = res ? `HTTP ${res.status}` : 'unreachable'
-      console.error(`❌ Cannot reach ${url} (${errorDetail})`)
-      if (allFailed) console.error('   Set LYTHOS_GH_MIRROR to use a custom mirror.')
-      console.error('   Or download manually and reference the local file.')
-      process.exit(1)
+      error(`❌ Cannot reach ${url} (${errorDetail})`)
+      if (allFailed) error('   Set LYTHOS_GH_MIRROR to use a custom mirror.')
+      error('   Or download manually and reference the local file.')
+      exit(1)
     }
 
     deckWrite(dest, await res.text())
-    console.log(`   → saved to ${dest}`)
+    log(`   → saved to ${dest}`)
     deckPath = dest
   } else {
     deckPath = resolve(opts.deck)
-    if (!deckExists(deckPath)) { console.error(`❌ Deck file not found: ${deckPath}
+    if (!deckExists(deckPath)) { error(`❌ Deck file not found: ${deckPath}
    Make sure the path is correct, or use a URL:
      --deck https://raw.githubusercontent.com/lythos-labs/lythoskill/main/examples/decks/scout.toml
-   (URLs are auto-fetched — no local file needed)`); process.exit(1) }
+   (URLs are auto-fetched — no local file needed)`); exit(1) }
   }
 
   const { useAgent } = await import('@lythos/test-utils/agents')
@@ -263,9 +282,9 @@ async function singleRun(args: string[]) {
   // Markdown is for LLM agents; task text is read/stored as a raw string.
   const taskText = resolvedTaskPath ? readFileSync(resolvedTaskPath, 'utf-8') : opts.brief!
 
-  console.log(`🤖 agent-run: ${player} × ${deckPath}`)
-  if (opts.task) console.log(`📋 task: ${resolve(opts.task!)}`)
-  else console.log(`📋 brief: ${opts.brief!.slice(0, 60)}...`)
+  log(`🤖 agent-run: ${player} × ${deckPath}`)
+  if (opts.task) log(`📋 task: ${resolve(opts.task!)}`)
+  else log(`📋 brief: ${opts.brief!.slice(0, 60)}...`)
 
   // Setup workdir
   const agentWorkdir = join(tmpdir(), `arena-single-${Date.now()}`)
@@ -298,11 +317,11 @@ async function singleRun(args: string[]) {
     const linkStderr = await new Response(linkProc.stderr).text()
     const linkResult = validateLinkResult(linkProc.exitCode, linkStderr)
     if (!linkResult.ok) {
-      console.error(`❌ ${linkResult.error}`)
-      process.exit(1)
+      error(`❌ ${linkResult.error}`)
+      exit(1)
     }
   } else {
-    console.log('ℹ️  No skills declared in deck — skipping link')
+    log('ℹ️  No skills declared in deck — skipping link')
   }
 
   const { existsSync: es } = await import('node:fs')
@@ -313,10 +332,10 @@ async function singleRun(args: string[]) {
     const skills = parseDeckSkills(deckParsed)
     const checks = checkSkillExistence(skills, coldPoolDir, es)
     for (const warning of formatSkillWarnings(checks)) {
-      console.warn(`⚠️  ${warning}`)
+      warn(`⚠️  ${warning}`)
     }
   } catch (e) {
-    console.warn('⚠️  Could not check skill existence:', e instanceof Error ? e.message : e)
+    warn('⚠️  Could not check skill existence:', e instanceof Error ? e.message : e)
   }
 
   // Template injection: brief is the {task} variable, template carries fixed contract
@@ -345,23 +364,24 @@ async function singleRun(args: string[]) {
       const plan = buildCopyPlan(agentWorkdir, outDir, entries, skipSet)
       for (const { src, dest, name } of plan) {
         try { cpSync(src, dest, { recursive: true }) } catch (e) {
-          console.warn(`⚠️  Failed to copy agent output: ${name} — ${e instanceof Error ? e.message : e}`)
+          warn(`⚠️  Failed to copy agent output: ${name} — ${e instanceof Error ? e.message : e}`)
         }
       }
     } catch (e) {
-      console.warn(`⚠️  Failed to copy agent output: ${e instanceof Error ? e.message : e}`)
+      warn(`⚠️  Failed to copy agent output: ${e instanceof Error ? e.message : e}`)
     }
   }
 
   // Summary (no judge — single mode is execution-only)
-  console.log(`\n✅ Agent run complete → ${outDir}`)
-  console.log(`   deck: ${deckPath}`)
-  console.log(`   player: ${player}`)
+  log(`\n✅ Agent run complete → ${outDir}`)
+  log(`   deck: ${deckPath}`)
+  log(`   player: ${player}`)
 }
 
 // ── vs: arena.toml-driven comparison ──────────────────────────────────────
 
-async function vsRun(args: string[]) {
+async function vsRun(args: string[], io: ArenaCliIO) {
+  const { log, error, exit } = { ...defaultArenaCliIO, ...io }
   // Native TOML parser is simpler than adding smol-toml dependency
   const opts: Record<string, string | undefined> = {}
   for (let i = 0; i < args.length; i++) {
@@ -372,14 +392,14 @@ async function vsRun(args: string[]) {
   }
 
   if (!opts.config) {
-    console.error('❌ arena.toml path required: lythoskill-arena vs --config arena.toml')
-    process.exit(1)
+    error('❌ arena.toml path required: lythoskill-arena vs --config arena.toml')
+    exit(1)
   }
 
   const configPath = resolve(opts.config)
   if (!existsSync(configPath)) {
-    console.error(`❌ Config file not found: ${configPath}`)
-    process.exit(1)
+    error(`❌ Config file not found: ${configPath}`)
+    exit(1)
   }
 
   const toml = parseArenaToml(readFileSync(configPath, 'utf-8'))
@@ -395,11 +415,11 @@ async function vsRun(args: string[]) {
   const isDryRun = opts.dryRun === 'true'
 
   if (isDryRun) {
-    console.log(`🔍 Scanning arena.toml: ${configPath}`)
+    log(`🔍 Scanning arena.toml: ${configPath}`)
   } else {
-    console.log(`🏟  Arena VS: ${configPath}`)
-    console.log(`   sides: ${toml.side.length}`)
-    console.log(`   runs per side: ${toml.arena.runs_per_side}`)
+    log(`🏟  Arena VS: ${configPath}`)
+    log(`   sides: ${toml.side.length}`)
+    log(`   runs per side: ${toml.arena.runs_per_side}`)
   }
 
   const { runArenaFromToml } = await import('./runner')
@@ -408,38 +428,40 @@ async function vsRun(args: string[]) {
     taskPath,
     outDir: opts.out ? resolve(opts.out) : undefined,
     dryRun: isDryRun,
-    log: console.log,
+    log: log,
     configDir: resolve(configPath, '..'),
   })
 
   if ('plan' in result) {
-    if (!isDryRun) console.log('📋 Execution plan (dry-run):')
-    for (const line of formatPlanOutput(result.plan)) console.log(line)
+    if (!isDryRun) log('📋 Execution plan (dry-run):')
+    for (const line of formatPlanOutput(result.plan)) log(line)
   } else if ('manifest' in result) {
     const r = result
-    console.log(`\n📊 Arena complete: ${r.manifest.id}`)
-    console.log(`   report: ${r.artifactsDir}/report.md`)
-    console.log(`   participants: ${r.manifest.participants.map(p => p.name).join(', ')}`)
+    log(`\n📊 Arena complete: ${r.manifest.id}`)
+    log(`   report: ${r.artifactsDir}/report.md`)
+    log(`   participants: ${r.manifest.participants.map(p => p.name).join(', ')}`)
   }
 }
 
 // ── viz: generate HTML report from arena.json ─────────────────────────────
 
-async function vizRun(args: string[]) {
+async function vizRun(args: string[], io: ArenaCliIO) {
+  const { error, exit, log } = { ...defaultArenaCliIO, ...io }
   const runsDir = args.find(a => !a.startsWith('-'))
-  if (!runsDir) { console.error('❌ runs/<arena-id> path required: lythoskill-arena viz runs/arena-20260504'); process.exit(1) }
+  if (!runsDir) { error('❌ runs/<arena-id> path required: lythoskill-arena viz runs/arena-20260504'); exit(1) }
 
   const arenaJsonPath = resolve(runsDir, 'arena.json')
-  if (!existsSync(arenaJsonPath)) { console.error(`❌ arena.json not found in: ${runsDir}`); process.exit(1) }
+  if (!existsSync(arenaJsonPath)) { error(`❌ arena.json not found in: ${runsDir}`); exit(1) }
 
-  console.log(`📈 Arena HTML report not yet implemented. See report.md in ${runsDir}/`)
+  log(`📈 Arena HTML report not yet implemented. See report.md in ${runsDir}/`)
 }
 
 // ═══════════════════════════════════════════════════════════════════════════
 // ── prepare-workdir: reusable workdir setup (used by both CLI and agent) ──
 // Intent: create an isolated arena workdir with deck linked and ready to run
 
-async function prepareWorkdir(args: string[]) {
+async function prepareWorkdir(args: string[], io: ArenaCliIO) {
+  const { log, error, warn, exit } = { ...defaultArenaCliIO, ...io }
   const opts: Record<string, string | undefined> = {}
   let dryRun = false
   for (let i = 0; i < args.length; i++) {
@@ -450,15 +472,15 @@ async function prepareWorkdir(args: string[]) {
   }
 
   if (!opts.deck) {
-    console.error(`❌ --deck <path> is required.
+    error(`❌ --deck <path> is required.
    lythoskill-arena prepare-workdir --deck ./skill-deck.toml --out /tmp/arena-side-a`)
-    process.exit(1)
+    exit(1)
   }
 
   const deckPath = resolve(opts.deck)
   if (!existsSync(deckPath)) {
-    console.error(`❌ Deck file not found: ${deckPath}`)
-    process.exit(1)
+    error(`❌ Deck file not found: ${deckPath}`)
+    exit(1)
   }
 
   const workDir = opts.out
@@ -475,16 +497,16 @@ async function prepareWorkdir(args: string[]) {
     brief: opts.brief,
   })
 
-  console.log('📋 Prepare plan:')
-  console.log(`   deck:    ${plan.deckPath}`)
-  console.log(`   workdir: ${plan.workDir}`)
-  console.log(`   skills:  ${plan.skills.length} declared (${plan.skills.map(s => s.name).join(', ') || 'none'})`)
-  console.log(`   link:    ${plan.hasSkills ? 'Bun.spawn deck link' : 'skip (no skills)'}`)
-  console.log(`   AGENTS.md: write (${plan.agentsMd.split('\n').length} lines)`)
-  if (opts.brief) console.log(`   brief:   ${opts.brief!.slice(0, 60)}...`)
+  log('📋 Prepare plan:')
+  log(`   deck:    ${plan.deckPath}`)
+  log(`   workdir: ${plan.workDir}`)
+  log(`   skills:  ${plan.skills.length} declared (${plan.skills.map(s => s.name).join(', ') || 'none'})`)
+  log(`   link:    ${plan.hasSkills ? 'Bun.spawn deck link' : 'skip (no skills)'}`)
+  log(`   AGENTS.md: write (${plan.agentsMd.split('\n').length} lines)`)
+  if (opts.brief) log(`   brief:   ${opts.brief!.slice(0, 60)}...`)
 
   if (dryRun) {
-    console.log(`\n🏁 Dry-run complete (no files created). Remove --dry-run to execute.`)
+    log(`\n🏁 Dry-run complete (no files created). Remove --dry-run to execute.`)
     return
   }
 
@@ -506,11 +528,11 @@ async function prepareWorkdir(args: string[]) {
     const linkStderr = await new Response(linkProc.stderr).text()
     const linkResult = validateLinkResult(linkProc.exitCode, linkStderr)
     if (!linkResult.ok) {
-      console.error(`❌ ${linkResult.error}`)
-      process.exit(1)
+      error(`❌ ${linkResult.error}`)
+      exit(1)
     }
   } else {
-    console.log('ℹ️  No skills declared in deck — skipping link')
+    log('ℹ️  No skills declared in deck — skipping link')
   }
 
   // Skill existence check
@@ -519,22 +541,23 @@ async function prepareWorkdir(args: string[]) {
     const coldPoolDir = resolveColdPoolDir(Bun.TOML.parse(deckContent)?.deck?.cold_pool, homedir(), coldPoolDefault)
     const checks = checkSkillExistence(plan.skills, coldPoolDir, existsSync)
     for (const warning of formatSkillWarnings(checks)) {
-      console.warn(`⚠️  ${warning}`)
+      warn(`⚠️  ${warning}`)
     }
   } catch (e) {
-    console.warn('⚠️  Could not check skill existence:', e instanceof Error ? e.message : e)
+    warn('⚠️  Could not check skill existence:', e instanceof Error ? e.message : e)
   }
 
-  console.log(`✅ Workdir ready → ${workDir}`)
-  console.log(`   deck: ${deckPath}`)
-  if (opts.brief) console.log(`   brief: ${opts.brief!.slice(0, 60)}...`)
+  log(`✅ Workdir ready → ${workDir}`)
+  log(`   deck: ${deckPath}`)
+  if (opts.brief) log(`   brief: ${opts.brief!.slice(0, 60)}...`)
 }
 
 // ═══════════════════════════════════════════════════════════════════════════
 // ── archive: copy agent outputs from workdir(s) to outDir ─────────────────
 // Intent: same copy behavior as CLI singleRun, reusable for agent-orchestrated
 
-async function archiveRun(args: string[]) {
+async function archiveRun(args: string[], io: ArenaCliIO) {
+  const { log, error, warn, exit } = { ...defaultArenaCliIO, ...io }
   const opts: Record<string, string | undefined> = {}
   let dryRun = false
   for (let i = 0; i < args.length; i++) {
@@ -546,9 +569,9 @@ async function archiveRun(args: string[]) {
   }
 
   if (!opts.from || !opts.to) {
-    console.error(`❌ --from <workdir> and --to <outdir> are required.
+    error(`❌ --from <workdir> and --to <outdir> are required.
    lythoskill-arena archive --from /tmp/arena-20260517 --to playground/arena-20260517 --sides side-a,side-b --report ./report.md`)
-    process.exit(1)
+    exit(1)
   }
 
   const fromDir = resolve(opts.from)
@@ -558,18 +581,18 @@ async function archiveRun(args: string[]) {
   const plan = buildArchiveSidePlan(fromDir, sides, existsSync)
 
   // ── Plan output (always shown, also serves as dry-run) ──────────────────
-  console.log('📋 Archive plan:')
+  log('📋 Archive plan:')
   for (const pe of plan) {
     if (!pe.found) {
-      console.log(`   ⚠️  ${pe.side}: not found (${pe.sourceDir}) — will skip`)
+      log(`   ⚠️  ${pe.side}: not found (${pe.sourceDir}) — will skip`)
     } else if (pe.sourceDir === fromDir && pe.side !== '.') {
-      console.log(`   ${pe.side}: ${pe.sourceDir} (fallback → root) → ${join(outDir, pe.side)}`)
+      log(`   ${pe.side}: ${pe.sourceDir} (fallback → root) → ${join(outDir, pe.side)}`)
     } else {
-      console.log(`   ${pe.side}: ${pe.sourceDir} → ${join(outDir, pe.side)}`)
+      log(`   ${pe.side}: ${pe.sourceDir} → ${join(outDir, pe.side)}`)
     }
   }
   if (dryRun) {
-    console.log(`\n🏁 Dry-run complete (no files copied). Remove --dry-run to execute.`)
+    log(`\n🏁 Dry-run complete (no files copied). Remove --dry-run to execute.`)
     return
   }
 
@@ -579,7 +602,7 @@ async function archiveRun(args: string[]) {
   if (opts.report && existsSync(resolve(opts.report))) {
     const { cpSync: cpR } = await import('node:fs')
     cpR(resolve(opts.report), join(outDir, 'report.md'))
-    console.log(`📄 report.md → ${outDir}/report.md`)
+    log(`📄 report.md → ${outDir}/report.md`)
   }
 
   const { cpSync, readdirSync } = await import('node:fs')
@@ -587,7 +610,7 @@ async function archiveRun(args: string[]) {
 
   for (const planEntry of plan) {
     if (!planEntry.found) {
-      console.warn(`⚠️  Side workdir not found: ${planEntry.sourceDir}`)
+      warn(`⚠️  Side workdir not found: ${planEntry.sourceDir}`)
       continue
     }
 
@@ -601,14 +624,14 @@ async function archiveRun(args: string[]) {
       const dest = join(sideOutDir, entry.name)
       try {
         cpSync(src, dest, { recursive: entry.isDirectory() })
-        console.log(`   ${planEntry.side}/${entry.name} → ${dest}`)
+        log(`   ${planEntry.side}/${entry.name} → ${dest}`)
       } catch (e) {
-        console.warn(`⚠️  Failed to copy ${planEntry.side}/${entry.name}: ${e instanceof Error ? e.message : e}`)
+        warn(`⚠️  Failed to copy ${planEntry.side}/${entry.name}: ${e instanceof Error ? e.message : e}`)
       }
     }
   }
 
-  console.log(`✅ Archive complete → ${outDir}`)
+  log(`✅ Archive complete → ${outDir}`)
 }
 
 // ── Entry point ────────────────────────────────────────────────────────────

package/src/runner.test.ts

@@ -1,5 +1,5 @@
 import { describe, test, expect } from 'bun:test'
-import { buildArenaPrompt, formatPlanOutput } from './runner'
+import { buildArenaPrompt, formatPlanOutput, runArenaFromToml, type ArenaIO } from './runner'
 import { buildExecutionPlan, parseArenaToml } from './arena-toml'
 
 describe('buildArenaPrompt — plan-mode (pure, no IO)', () => {
@@ -89,3 +89,262 @@ describe('buildArenaPrompt — plan-mode (pure, no IO)', () => {
     expect(buildArenaPrompt(opts)).toBe(buildArenaPrompt(opts))
   })
 })
+
+describe('runArenaFromToml — dry-run mode (no fs/spawn/agent calls)', () => {
+  test('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)
+  })
+
+  test('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', () => {
+  test('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', () => {
+  test('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')
+  })
+
+  test('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 {