@lythos/skill-arena 0.19.1 → 0.19.3

package/README.md

@@ -16,20 +16,20 @@
 ```bash
 bun add -d @lythos/skill-arena
 # or use directly
-bunx @lythos/skill-arena@0.19.1 <command>
+bunx @lythos/skill-arena@0.19.3 <command>
 ```
 
 ## Quick Start
 
 ```bash
 # single — test one deck (most common)
-bunx @lythos/skill-arena@0.19.1 single \
+bunx @lythos/skill-arena@0.19.3 single \
   --deck ./examples/decks/scout.toml \
   --brief "Generate auth flow diagram" \
   --out ./output
 
 # single with explicit player
-bunx @lythos/skill-arena@0.19.1 single \
+bunx @lythos/skill-arena@0.19.3 single \
   --deck ./examples/decks/scout.toml \
   --brief "Generate auth flow diagram" \
   --player kimi \
@@ -37,10 +37,10 @@ bunx @lythos/skill-arena@0.19.1 single \
 
 # cross-deck vs — compare two decks (agent-orchestrated)
 # Create arena.toml declaring sides with different decks, then:
-bunx @lythos/skill-arena@0.19.1 vs --config ./arena.toml
+bunx @lythos/skill-arena@0.19.3 vs --config ./arena.toml
 
 # cross-player vs — compare kimi vs codex (CLI only)
-bunx @lythos/skill-arena@0.19.1 vs --config ./arena.toml --player kimi
+bunx @lythos/skill-arena@0.19.3 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.19.1 vs --config ./arena.toml --player kimi
 ### `single` — one deck, one task
 
 ```bash
-bunx @lythos/skill-arena@0.19.1 single \
+bunx @lythos/skill-arena@0.19.3 single \
   --deck ./deck.toml \
   --brief "Produce a .docx report with radar chart" \
   --timeout 600000 \
   --out ./output
 
 # with explicit player
-bunx @lythos/skill-arena@0.19.1 single \
+bunx @lythos/skill-arena@0.19.3 single \
   --deck ./deck.toml \
   --brief "Produce a .docx report with radar chart" \
   --player kimi \
@@ -67,14 +67,14 @@ bunx @lythos/skill-arena@0.19.1 single \
 ### `vs` — multi-deck comparison
 
 ```bash
-bunx @lythos/skill-arena@0.19.1 vs --config ./arena.toml
-bunx @lythos/skill-arena@0.19.1 vs --config ./arena.toml --dry-run
+bunx @lythos/skill-arena@0.19.3 vs --config ./arena.toml
+bunx @lythos/skill-arena@0.19.3 vs --config ./arena.toml --dry-run
 ```
 
 ### `prepare-workdir` — isolate + link skills (agent-orchestrated)
 
 ```bash
-bunx @lythos/skill-arena@0.19.1 prepare-workdir \
+bunx @lythos/skill-arena@0.19.3 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.19.1 archive \
+bunx @lythos/skill-arena@0.19.3 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.19.1 viz runs/arena-<id>/
+bunx @lythos/skill-arena@0.19.3 viz runs/arena-<id>/
 ```
 
 ## Parameters

package/package.json

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

package/src/cli.test.ts

@@ -1,4 +1,7 @@
 import { describe, it, expect } from 'bun:test'
+import { mkdtempSync, rmSync, mkdirSync, writeFileSync, readFileSync, existsSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
 import { main, defaultArenaCliIO, type ArenaCliIO } from './cli'
 
 // ─── Helpers ───────────────────────────────────────────────────────────────
@@ -120,3 +123,75 @@ describe('defaultArenaCliIO', () => {
     expect(typeof defaultArenaCliIO.exit).toBe('function')
   })
 })
+
+// ═══════════════════════════════════════════════════════════════════════════
+// archive — collect step merges per-cell decision logs
+// (TASK-20260909010121918)
+// ═══════════════════════════════════════════════════════════════════════════
+
+describe('archive — per-cell decision-log merge', () => {
+
+  function scaffold() {
+    const root = mkdtempSync(join(tmpdir(), 'arena-archive-'))
+    const from = join(root, 'work')
+    const to = join(root, 'archived')
+    mkdirSync(join(from, 'side-a'), { recursive: true })
+    mkdirSync(join(from, 'side-b'), { recursive: true })
+    return { root, from, to }
+  }
+
+  it('merges side-a per-cell logs into one decision-log.jsonl', async () => {
+    const { root, from, to } = scaffold()
+    try {
+      writeFileSync(join(from, 'side-a', 'decision-log-s1a.jsonl'), '{"t":0,"phase":"a","decision":"cell 1a","reason":"r"}\n')
+      writeFileSync(join(from, 'side-a', 'decision-log-s3a.jsonl'), '{"t":0,"phase":"a","decision":"cell 3a","reason":"r"}\n')
+      writeFileSync(join(from, 'side-a', 'report.md'), '# side-a report\n')
+
+      const { io, logs } = mockIO()
+      await main(['archive', '--from', from, '--to', to, '--sides', 'side-a'], io)
+
+      const merged = readFileSync(join(to, 'side-a', 'decision-log.jsonl'), 'utf-8')
+      expect(merged).toContain('cell 1a')
+      expect(merged).toContain('cell 3a')
+      expect(merged.trim().split('\n')).toHaveLength(2)
+      // Per-cell files stay as provenance — the merged line carries no cell attribution.
+      expect(existsSync(join(to, 'side-a', 'decision-log-s1a.jsonl'))).toBe(true)
+      expect(existsSync(join(to, 'side-a', 'decision-log-s3a.jsonl'))).toBe(true)
+      expect(logs.some(l => l.includes('merged 2 per-cell log(s)'))).toBe(true)
+    } finally {
+      rmSync(root, { recursive: true, force: true })
+    }
+  })
+
+  it('a single legacy decision-log.jsonl is already merged — not rewritten', async () => {
+    const { root, from, to } = scaffold()
+    try {
+      const legacy = '{"t":0,"phase":"a","decision":"only cell","reason":"r"}\n'
+      writeFileSync(join(from, 'side-b', 'decision-log.jsonl'), legacy)
+
+      const { io } = mockIO()
+      await main(['archive', '--from', from, '--to', to, '--sides', 'side-b'], io)
+
+      expect(readFileSync(join(to, 'side-b', 'decision-log.jsonl'), 'utf-8')).toBe(legacy)
+    } finally {
+      rmSync(root, { recursive: true, force: true })
+    }
+  })
+
+  it('mixed workdir: legacy + per-cell logs all survive the merge', async () => {
+    const { root, from, to } = scaffold()
+    try {
+      writeFileSync(join(from, 'side-a', 'decision-log.jsonl'), '{"t":0,"phase":"a","decision":"legacy entry","reason":"r"}\n')
+      writeFileSync(join(from, 'side-a', 'decision-log-s1a.jsonl'), '{"t":0,"phase":"a","decision":"cell 1a","reason":"r"}\n')
+
+      const { io } = mockIO()
+      await main(['archive', '--from', from, '--to', to, '--sides', 'side-a'], io)
+
+      const merged = readFileSync(join(to, 'side-a', 'decision-log.jsonl'), 'utf-8')
+      expect(merged).toContain('legacy entry')
+      expect(merged).toContain('cell 1a')
+    } finally {
+      rmSync(root, { recursive: true, force: true })
+    }
+  })
+})

package/src/cli.ts

@@ -5,7 +5,7 @@ import { homedir, tmpdir } from 'node:os'
 import { ZodError } from 'zod'
 import { formatPlanOutput, type ArenaResult, buildArenaPrompt } from './runner'
 import { parseArenaToml, buildExecutionPlan } from './arena-toml'
-import { buildArchiveSidePlan, buildCopyPlan, buildPreparePlan, parseDeckSkills } from './preflight'
+import { buildArchiveSidePlan, buildCopyPlan, buildPreparePlan, parseDeckCombos, parseDeckSkills, buildAgentsMd, isDecisionLogName, mergeDecisionLogs, LEGACY_DECISION_LOG } from './preflight'
 import { checkSkillExistence, formatSkillWarnings, resolveColdPoolDir } from './preflight'
 import { resolveSingleMode } from './host'
 
@@ -118,6 +118,7 @@ Modes (single):
 
 Examples:
   lythoskill-arena single --brief "find and research" --deck ./decks/scout.toml
+  lythoskill-arena single --brief "audit this repo" --deck ./decks/qa-sweep.toml --out /tmp/arena-audit
   lythoskill-arena single --brief "find and research" --deck https://raw.githubusercontent.com/lythos-labs/lythoskill/main/examples/decks/scout.toml
   lythoskill-arena vs --config arena.toml --dry-run
   lythoskill-arena vs --config arena.toml
@@ -339,17 +340,16 @@ async function singleRun(args: string[], io: ArenaCliIO) {
   // Setup workdir
   const agentWorkdir = join(tmpdir(), `arena-single-${Date.now()}`)
   mkdirSync(agentWorkdir, { recursive: true })
-  writeFileSync(join(agentWorkdir, 'skill-deck.toml'), readFileSync(deckPath, 'utf-8'))
-  writeFileSync(join(agentWorkdir, 'AGENTS.md'), [
-    '# Arena Test Environment',
-    `**Mode**: single`,
-    '## How This Works',
-    '- Isolated arena test directory. Skills in skill-deck.toml, linked via deck link.',
-    '- Complete the task using available skills. Output to this directory.',
-    '- MANDATORY: write decision-log.jsonl (see prompt for schema).',
-  ].join('\n'))
-
-  const deckRaw = readFileSync(join(agentWorkdir, 'skill-deck.toml'), 'utf-8')
+  const singleDeckRaw = readFileSync(deckPath, 'utf-8')
+  writeFileSync(join(agentWorkdir, 'skill-deck.toml'), singleDeckRaw)
+  let singleDeckParsed: Record<string, any> = {}
+  try { singleDeckParsed = Bun.TOML.parse(singleDeckRaw) as Record<string, any> } catch {}
+  writeFileSync(join(agentWorkdir, 'AGENTS.md'), buildAgentsMd({
+    mode: 'single',
+    combos: parseDeckCombos(singleDeckParsed),
+  }))
+
+  const deckRaw = singleDeckRaw
   let deckParsed: Record<string, any> = {}
   try { deckParsed = Bun.TOML.parse(deckRaw) as Record<string, any> } catch {}
   const hasSkills = parseDeckSkills(deckParsed).length > 0
@@ -679,6 +679,31 @@ async function archiveRun(args: string[], io: ArenaCliIO) {
         warn(`⚠️  Failed to copy ${planEntry.side}/${entry.name}: ${e instanceof Error ? e.message : e}`)
       }
     }
+
+    // ── Collect: merge per-cell decision logs into one decision-log.jsonl ──
+    // Cells sharing a side workdir each wrote `decision-log-<cell-id>.jsonl`
+    // (TASK-20260909010121918). Reconstructing the single-file view here is
+    // what makes the merged log possible to read; the per-cell files were
+    // just copied and stay as provenance. A lone legacy `decision-log.jsonl`
+    // is already the merged view — nothing to do.
+    const logNames = entries
+      .filter(e => e.isFile() && isDecisionLogName(e.name))
+      .map(e => e.name)
+      .sort()
+    // A lone `decision-log.jsonl` IS the merged view — do not rewrite it.
+    const needsMerge = logNames.length > 1 || (logNames.length === 1 && logNames[0] !== LEGACY_DECISION_LOG)
+    if (needsMerge) {
+      try {
+        const sources = logNames.map(name => ({
+          cell: name,
+          content: readFileSync(join(sideOutDir, name), 'utf-8'),
+        }))
+        writeFileSync(join(sideOutDir, LEGACY_DECISION_LOG), mergeDecisionLogs(sources))
+        log(`   ${planEntry.side}/${LEGACY_DECISION_LOG} ← merged ${logNames.length} per-cell log(s)`)
+      } catch (e) {
+        warn(`⚠️  Failed to merge decision logs for ${planEntry.side}: ${e instanceof Error ? e.message : e}`)
+      }
+    }
   }
 
   log(`✅ Archive complete → ${outDir}`)

package/src/preflight.test.ts

@@ -11,6 +11,9 @@
  */
 
 import { describe, it, expect } from 'bun:test'
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
 import {
   parseDeckSkills,
   checkSkillExistence,
@@ -18,6 +21,11 @@ import {
   buildCopyPlan,
   resolveColdPoolDir,
   formatSkillWarnings,
+  decisionLogName,
+  isDecisionLogName,
+  mergeDecisionLogs,
+  LEGACY_DECISION_LOG,
+  type DecisionLogSource,
 } from './preflight'
 
 // ═══════════════════════════════════════════════════════════════════════════
@@ -582,3 +590,211 @@ describe('buildPreparePlan', () => {
     expect(plan.deckContent).toBe(DECK_ONE_SKILL)
   })
 })
+
+// ═══════════════════════════════════════════════════════════════════════════
+// parseDeckCombos + combo surfacing in AGENTS.md (F1/F2, TASK-20260909152255103)
+// ═══════════════════════════════════════════════════════════════════════════
+
+import { parseDeckCombos, buildAgentsMd } from './preflight'
+
+const DECK_WITH_COMBOS = `
+[deck]
+max_cards = 10
+
+[tool.skills.pdf]
+path = "github.com/anthropics/skills/skills/pdf"
+
+[combo.promo]
+prompt = "Pipeline: Position → Draft → Review."
+
+[combo.research]
+prompt = "Pipeline: Discover → Verify → Analyze."
+`
+
+describe('parseDeckCombos', () => {
+
+  it('extracts combo names in declaration order', () => {
+    const parsed = Bun.TOML.parse(DECK_WITH_COMBOS) as Record<string, any>
+    expect(parseDeckCombos(parsed)).toEqual(['promo', 'research'])
+  })
+
+  it('no combo section → empty array', () => {
+    const parsed = Bun.TOML.parse(DECK_ONE_SKILL) as Record<string, any>
+    expect(parseDeckCombos(parsed)).toEqual([])
+  })
+
+  it('legacy bare [combo] prompt field → empty array (default combo, no named section)', () => {
+    const parsed = Bun.TOML.parse('[combo]\nprompt = "do stuff"') as Record<string, any>
+    expect(parseDeckCombos(parsed)).toEqual([])
+  })
+})
+
+describe('buildAgentsMd combo surfacing (F1)', () => {
+
+  it('deck with combos → AGENTS.md lists them under "Read These First"', () => {
+    const parsed = Bun.TOML.parse(DECK_WITH_COMBOS) as Record<string, any>
+    const md = buildAgentsMd({ mode: 'single', combos: parseDeckCombos(parsed) })
+    expect(md).toContain('## Combos — Read These First')
+    expect(md).toContain('- `promo`')
+    expect(md).toContain('- `research`')
+    expect(md.indexOf('Combos — Read These First')).toBeLessThan(md.indexOf('## Setup Order'))
+  })
+
+  it('combo consumer declared: agent reads/executes, CLI only parses (F2)', () => {
+    const md = buildAgentsMd({ mode: 'single', combos: ['promo'] })
+    expect(md).toContain('executed by YOU (the agent)')
+    expect(md).toContain('the CLI only parses them; nothing runs them')
+  })
+
+  it('deck without combos → no combos section', () => {
+    const md = buildAgentsMd({ mode: 'single' })
+    expect(md).not.toContain('Combos')
+  })
+})
+
+describe('buildAgentsMd vocabulary gloss (F3)', () => {
+
+  it('glosses cold pool / working set / innate / tool / max_cards', () => {
+    const md = buildAgentsMd({ mode: 'single' })
+    expect(md).toContain('**cold pool**')
+    expect(md).toContain('**working set**')
+    expect(md).toContain('**innate**')
+    expect(md).toContain('**tool**')
+    expect(md).toContain('**max_cards**')
+  })
+})
+
+// ═══════════════════════════════════════════════════════════════════════════
+// decision logs — per-cell naming (TASK-20260909010121918)
+//
+// Defect: five cells per side shared one workdir and one mandated filename
+// (`decision-log.jsonl`). Filename is a constant → shared path → last writer
+// wins; the 2026-09-09 side-a log lost S3a/S4a/S5a entirely.
+// ═══════════════════════════════════════════════════════════════════════════
+
+describe('decisionLogName', () => {
+
+  it('per-cell id → per-cell filename', () => {
+    expect(decisionLogName('s1a')).toBe('decision-log-s1a.jsonl')
+    expect(decisionLogName('claude-run-2')).toBe('decision-log-claude-run-2.jsonl')
+  })
+
+  it('two distinct cell ids never share a path', () => {
+    expect(decisionLogName('s1a')).not.toBe(decisionLogName('s3a'))
+  })
+
+  it('no id → legacy single-cell name', () => {
+    expect(decisionLogName()).toBe(LEGACY_DECISION_LOG)
+    expect(decisionLogName('')).toBe(LEGACY_DECISION_LOG)
+  })
+
+  it('id cannot escape the workdir (no separators, no traversal, no dotfile)', () => {
+    expect(decisionLogName('../evil')).toBe('decision-log-evil.jsonl')
+    expect(decisionLogName('a/b')).toBe('decision-log-a-b.jsonl')
+    expect(decisionLogName('claude run 1')).toBe('decision-log-claude-run-1.jsonl')
+    for (const hostile of ['../evil', 'a/b', '..', './x', 'a\\b', '..\0']) {
+      const name = decisionLogName(hostile)
+      expect(name).not.toContain('/')
+      expect(name).not.toContain('\\')
+      expect(name.startsWith('.')).toBe(false)
+      expect(isDecisionLogName(name)).toBe(true)
+    }
+  })
+
+  it('separator-only id degrades to the legacy name, never to a bare prefix', () => {
+    expect(decisionLogName('///')).toBe(LEGACY_DECISION_LOG)
+  })
+})
+
+describe('isDecisionLogName', () => {
+
+  it('accepts the legacy name and per-cell names', () => {
+    expect(isDecisionLogName('decision-log.jsonl')).toBe(true)
+    expect(isDecisionLogName('decision-log-s1a.jsonl')).toBe(true)
+  })
+
+  it('rejects unrelated files', () => {
+    expect(isDecisionLogName('decision-log.jsonl.bak')).toBe(false)
+    expect(isDecisionLogName('decision-log.txt')).toBe(false)
+    expect(isDecisionLogName('my-decision-log.jsonl')).toBe(false)
+    expect(isDecisionLogName('judge-verdict.json')).toBe(false)
+  })
+})
+
+describe('mergeDecisionLogs', () => {
+
+  const s1a: DecisionLogSource = {
+    cell: 's1a',
+    content: '{"t":0,"phase":"setup","decision":"picked palette","reason":"theme"}\n',
+  }
+  const s3a: DecisionLogSource = {
+    cell: 's3a',
+    content: '{"t":0,"phase":"setup","decision":"resolved id","reason":"card"}\n',
+  }
+
+  it('keeps every line from every cell — nothing is dropped', () => {
+    const merged = mergeDecisionLogs([s1a, s3a])
+    expect(merged).toContain('picked palette')
+    expect(merged).toContain('resolved id')
+    expect(merged.trim().split('\n')).toHaveLength(2)
+  })
+
+  it('order is by cell id, not input order — same inputs, same bytes', () => {
+    const a = mergeDecisionLogs([s1a, s3a])
+    const b = mergeDecisionLogs([s3a, s1a])
+    expect(a).toBe(b)
+    expect(a.indexOf('picked palette')).toBeLessThan(a.indexOf('resolved id'))
+  })
+
+  it('lines are kept verbatim — no re-encoding, no injected field', () => {
+    const odd: DecisionLogSource = { cell: 'x', content: 'not json at all\n{"t":1,"phase":"p","decision":"d","reason":"r"}' }
+    const merged = mergeDecisionLogs([odd])
+    expect(merged).toContain('not json at all')
+    expect(JSON.parse(merged.trim().split('\n')[1])).toEqual({ t: 1, phase: 'p', decision: 'd', reason: 'r' })
+  })
+
+  it('blank lines are not entries; each line keeps exactly one newline', () => {
+    const gappy: DecisionLogSource = { cell: 'g', content: '\n{"t":1,"phase":"p","decision":"d","reason":"r"}\n\n' }
+    expect(mergeDecisionLogs([gappy])).toBe('{"t":1,"phase":"p","decision":"d","reason":"r"}\n')
+  })
+
+  it('a lone legacy file merges to itself (idempotent)', () => {
+    const content = '{"t":0,"phase":"setup","decision":"d","reason":"r"}\n'
+    expect(mergeDecisionLogs([{ cell: LEGACY_DECISION_LOG, content }])).toBe(content)
+  })
+
+  it('no sources → empty string (callers can skip writing)', () => {
+    expect(mergeDecisionLogs([])).toBe('')
+  })
+})
+
+describe('decision-log — 2-writer concurrency (real fs)', () => {
+
+  it('two cells writing concurrently in ONE workdir both survive the merge', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'arena-decision-log-'))
+    try {
+      // Two cells, one shared workdir, one writer each, interleaved by an await.
+      // Before the fix both paths were the same constant, so this write pair
+      // clobbered and the merge below would lose one cell's only entry.
+      const write = async (cellId: string, line: string) => {
+        await Bun.sleep(0)
+        writeFileSync(join(dir, decisionLogName(cellId)), line + '\n', 'utf-8')
+      }
+      await Promise.all([
+        write('s1a', '{"t":0,"phase":"setup","decision":"cel a","reason":"ra"}'),
+        write('s3a', '{"t":0,"phase":"setup","decision":"cell b","reason":"rb"}'),
+      ])
+
+      const merged = mergeDecisionLogs([
+        { cell: 's1a', content: await Bun.file(join(dir, decisionLogName('s1a'))).text() },
+        { cell: 's3a', content: await Bun.file(join(dir, decisionLogName('s3a'))).text() },
+      ])
+
+      expect(merged).toContain('cel a')
+      expect(merged).toContain('cell b')
+      expect(merged.trim().split('\n')).toHaveLength(2)
+    } finally {
+      rmSync(dir, { recursive: true, force: true })
+    }
+  })
+})

package/src/preflight.ts

@@ -237,6 +237,159 @@ export function buildArchiveSidePlan(
   return plan
 }
 
+// ── parseDeckCombos ──────────────────────────────────────────────────────
+
+/**
+ * Parse `[combo.<name>] prompt = "..."` sections from a parsed deck TOML.
+ *
+ * Combos are orchestration playbooks for the AGENT — the CLI never executes
+ * them (deck consumption contract, packages/lythoskill-deck/skill/SKILL.md).
+ * Returns combo names in declaration order so generated orientation docs
+ * (AGENTS.md) can point the agent at them before anything else.
+ *
+ * Pure: Record → string[]. No IO.
+ */
+export function parseDeckCombos(
+  deckParsed: Record<string, any>
+): string[] {
+  const combo = deckParsed?.combo
+  if (!combo || typeof combo !== 'object') return []
+  return Object.keys(combo).filter(k => k !== 'prompt')
+}
+
+// ── Decision logs: per-cell naming + collect-time merge ──────────────────
+//
+// Why per-cell names (TASK-20260909010121918): the 2026-09-09 run had five cells
+// per side sharing one workdir, each mandated to write `decision-log.jsonl`.
+// Filename is a constant, so the cells shared a path — last writer won, and
+// side-a kept only S1a's 9 entries. A per-cell filename removes the shared path
+// entirely: no write contention, no ordering assumption, no atomicity needed.
+// Rejected alternative (append-only read-then-append in one op) stays racy on
+// any multi-step append and silently depends on every agent obeying it.
+
+/** Legacy name — a workdir with exactly one decision-writing cell. */
+export const LEGACY_DECISION_LOG = 'decision-log.jsonl'
+
+/**
+ * Cell id → its own decision-log filename.
+ *
+ * The id is slugged to `[A-Za-z0-9_-]`: no `/` or `\` (an id cannot write
+ * outside the workdir or into a subdirectory) and no `.` (the result can never
+ * be `.`/`..` or a hidden file). Empty/absent id → the legacy single-cell name.
+ *
+ * Pure: string → string. No IO.
+ */
+export function decisionLogName(cellId?: string): string {
+  if (!cellId) return LEGACY_DECISION_LOG
+  const slug = cellId.replace(/[^A-Za-z0-9_-]+/g, '-').replace(/^-+|-+$/g, '')
+  return slug ? `decision-log-${slug}.jsonl` : LEGACY_DECISION_LOG
+}
+
+/** True for `decision-log.jsonl` and `decision-log-<cell-id>.jsonl` alike. */
+export function isDecisionLogName(name: string): boolean {
+  return /^decision-log(-[^/]+)?\.jsonl$/.test(name)
+}
+
+/** One cell's log, as read from disk. `cell` is the id used for merge order. */
+export interface DecisionLogSource {
+  cell: string
+  content: string
+}
+
+/**
+ * Merge per-cell decision logs into one JSONL stream.
+ *
+ * Lossless by construction: every non-empty line of every source is kept
+ * verbatim (no dedupe, no field injection, no JSON re-parse), sources ordered
+ * by cell id so the same inputs always produce the same bytes. The per-cell
+ * files are NOT consumed — they stay as provenance, since a merged line carries
+ * no cell attribution and `t` is cell-relative, not a wall clock.
+ *
+ * Pure: DecisionLogSource[] → string. No IO.
+ */
+export function mergeDecisionLogs(sources: DecisionLogSource[]): string {
+  const ordered = [...sources].sort((a, b) => (a.cell < b.cell ? -1 : a.cell > b.cell ? 1 : 0))
+  const lines: string[] = []
+  for (const source of ordered) {
+    for (const line of source.content.split('\n')) {
+      const trimmed = line.trim()
+      if (trimmed) lines.push(trimmed)
+    }
+  }
+  return lines.length > 0 ? lines.join('\n') + '\n' : ''
+}
+
+// ── buildAgentsMd ────────────────────────────────────────────────────────
+
+/**
+ * Build the unified arena workdir AGENTS.md — the agent's orientation artifact.
+ *
+ * Single source of truth for the template; all three write sites use it:
+ *   - prepare-workdir (buildPreparePlan)
+ *   - single (cli.ts agent-run)
+ *   - A/B runner cells (runner.ts)
+ *
+ * F1 (TASK-20260909152255103): combo sections are surfaced FIRST when present —
+ * they are the best orientation artifact in the deck. F3: first-timer
+ * vocabulary glossed here (the one tool-level place; the full glossary lives
+ * in the deck skill's references/glossary.md).
+ *
+ * Pure: strings → string. No IO.
+ */
+export function buildAgentsMd(params: {
+  mode: string
+  headerLines?: string[]
+  combos?: string[]
+}): string {
+  const lines: string[] = [
+    '# Arena Test Environment',
+    `**Mode**: ${params.mode}`,
+    ...(params.headerLines ?? []),
+    '',
+  ]
+
+  if (params.combos && params.combos.length > 0) {
+    lines.push(
+      '## Combos — Read These First',
+      'This deck has combo prompts in `skill-deck.toml`. They are YOUR orchestration',
+      'playbook: each `[combo.<name>] prompt` is read and executed by YOU (the agent) —',
+      'the CLI only parses them; nothing runs them. Open `skill-deck.toml` and follow',
+      'each combo in order:',
+      ...params.combos.map(name => `- \`${name}\``),
+      '',
+    )
+  }
+
+  lines.push(
+    '## Setup Order (why this sequence)',
+    '1. `skill-deck.toml` copied here → declares which skills you can use',
+    '2. `deck link` runs → cold pool skills become visible in the working set',
+    '3. Skill existence checked → warns if any declared skill is missing from cold pool',
+    '4. `AGENTS.md` written last → confirms setup succeeded before agent starts',
+    'If setup fails mid-sequence, the workdir is incomplete and nothing runs.',
+    '',
+    '## Vocabulary (first time here?)',
+    '- **cold pool** — where skill sources live on disk. You never read it directly.',
+    '- **working set** — `.claude/skills/`: the symlinks you actually see. `deck link` keeps it matching the deck.',
+    '- **innate** — always-on skills (governance, meta). **tool** — skills you load on demand.',
+    '- **max_cards** — hard budget in the toml; `deck link` refuses to exceed it.',
+    '',
+    '## How This Works',
+    '- Write ALL output files to this directory (CWD).',
+    '- Use available skills — check the working set directory (e.g. `ls .claude/skills/`).',
+    '',
+    '## Output Contract',
+    '- MANDATORY: `decision-log.jsonl` — one JSON line per decision:',
+    '  `{"t":<seconds>,"phase":"setup|content|design|output","decision":"...","reason":"..."}`',
+    '- MANDATORY when other cells share this directory: name yours',
+    '  `decision-log-<cell-id>.jsonl` (`decision-log-s1a.jsonl`) instead. Two cells on one',
+    '  filename means last-writer-wins — one cell\'s whole trail is erased. Per-cell names',
+    '  never collide, and the run merges them into one `decision-log.jsonl` when it collects.',
+  )
+
+  return lines.join('\n')
+}
+
 // ── buildPreparePlan ─────────────────────────────────────────────────────
 
 /**
@@ -270,25 +423,10 @@ export function buildPreparePlan(params: {
   const skills = parseDeckSkills(deckParsed)
   const hasSkills = skills.length > 0
 
-  const agentsMd = [
-    '# Arena Test Environment',
-    '**Mode**: agent-orchestrated cell',
-    '',
-    '## Setup Order (why this sequence)',
-    '1. `skill-deck.toml` copied here → declares which skills you can use',
-    '2. `deck link` runs → cold pool skills become visible in the working set',
-    '3. Skill existence checked → warns if any declared skill is missing from cold pool',
-    '4. `AGENTS.md` written last → confirms setup succeeded before agent starts',
-    'If setup fails mid-sequence, the workdir is incomplete and nothing runs.',
-    '',
-    '## How This Works',
-    '- Write ALL output files to this directory (CWD).',
-    '- Use available skills — check the working set directory (e.g. `ls .claude/skills/`).',
-    '',
-    '## Output Contract',
-    '- MANDATORY: `decision-log.jsonl` — one JSON line per decision:',
-    '  `{"t":<seconds>,"phase":"setup|content|design|output","decision":"...","reason":"..."}`',
-  ].join('\n')
+  const agentsMd = buildAgentsMd({
+    mode: 'agent-orchestrated cell',
+    combos: parseDeckCombos(deckParsed),
+  })
 
   return { deckPath: params.deckPath, deckContent: params.deckContent, workDir: params.workDir, skills, hasSkills, agentsMd }
 }

package/src/runner.test.ts

@@ -348,3 +348,181 @@ deck = "/tmp/deck.toml"
     expect(logs.some(l => l.includes('deck link') && l.includes('exit 1'))).toBe(true)
   })
 })
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Per-cell decision logs (TASK-20260909010121918)
+//
+// Cells of one side share a workdir (`work/<side>/`). Before the fix, every
+// cell was told to write the same `decision-log.jsonl` there, so a run with
+// runs_per_side > 1 kept only the last cell's trail. Cell id → per-cell file
+// name; the run merges them at collect time.
+// ═══════════════════════════════════════════════════════════════════════════
+
+describe('buildArenaPrompt — per-cell decision-log name', () => {
+
+  it('cellId → mandates the per-cell filename, not the shared one', () => {
+    const prompt = buildArenaPrompt({
+      brief: 'test',
+      cwd: '/tmp/arena-cell',
+      deckPath: '/tmp/test-deck.toml',
+      cellId: 'claude-run-1',
+    })
+    expect(prompt).toContain('MANDATORY — write decision-log-claude-run-1.jsonl')
+    expect(prompt).toContain('shared with other cells')
+  })
+
+  it('no cellId → legacy single-cell filename (arena single keeps its contract)', () => {
+    const prompt = buildArenaPrompt({
+      brief: 'test',
+      cwd: '/tmp/arena-cell',
+      deckPath: '/tmp/test-deck.toml',
+    })
+    expect(prompt).toContain('MANDATORY — write decision-log.jsonl')
+    expect(prompt).not.toContain('shared with other cells')
+  })
+
+  it('two cells of one side are told two different filenames', () => {
+    const base = { brief: 't', cwd: '/tmp/c', deckPath: '/tmp/d.toml' }
+    const a = buildArenaPrompt({ ...base, cellId: 'side-a-run-1' })
+    const b = buildArenaPrompt({ ...base, cellId: 'side-a-run-2' })
+    expect(a).toContain('decision-log-side-a-run-1.jsonl')
+    expect(b).toContain('decision-log-side-a-run-2.jsonl')
+  })
+})
+
+describe('runArenaFromToml — collect merges per-cell decision logs', () => {
+
+  const TOML_TWO_SIDES_TWO_RUNS = `
+[arena]
+task = "Write a hello world function"
+criteria = ["completeness"]
+runs_per_side = 2
+
+[[side]]
+name = "claude"
+player = "claude"
+deck = "/tmp/deck.toml"
+
+[[side]]
+name = "kimi"
+player = "kimi"
+deck = "/tmp/deck.toml"
+`
+
+  it('merges every cell log into <artifactsDir>/decision-log.jsonl', async () => {
+    const files = new Map<string, string>()
+    const cellLogs = new Map<string, string>([
+      ['/tmp/arena-out/work/claude/decision-log-claude-run-1.jsonl', '{"t":0,"phase":"setup","decision":"claude cell 1","reason":"r"}\n'],
+      ['/tmp/arena-out/work/claude/decision-log-claude-run-2.jsonl', '{"t":0,"phase":"setup","decision":"claude cell 2","reason":"r"}\n'],
+      ['/tmp/arena-out/work/kimi/decision-log-kimi-run-1.jsonl', '{"t":0,"phase":"setup","decision":"kimi cell 1","reason":"r"}\n'],
+      ['/tmp/arena-out/work/kimi/decision-log-kimi-run-2.jsonl', '{"t":0,"phase":"setup","decision":"kimi cell 2","reason":"r"}\n'],
+    ])
+
+    const mockIO: ArenaIO = {
+      log: () => {},
+      mkdir: () => {},
+      writeFile: (path: string, data: string) => { files.set(path, data) },
+      readFile: (path: string) => {
+        if (cellLogs.has(path)) return cellLogs.get(path)!
+        if (path === '/tmp/deck.toml') return 'skills = ["test"]'
+        throw new Error(`Unexpected read: ${path}`)
+      },
+      readdir: () => [],
+      cp: () => {},
+      spawn: async () => ({ exitCode: 0, stderr: '' }),
+      agentSpawn: async () => ({ stdout: 'ok', stderr: '', durationMs: 10 }),
+      exists: (path: string) => path === '/tmp/deck.toml' || cellLogs.has(path),
+      chdir: () => {},
+    }
+
+    await runArenaFromToml({
+      toml: parseArenaToml(TOML_TWO_SIDES_TWO_RUNS),
+      taskPath: '/tmp/task.md',
+      outDir: '/tmp/arena-out',
+      io: mockIO,
+    })
+
+    const merged = files.get('/tmp/arena-out/decision-log.jsonl')
+    expect(merged).toBeDefined()
+    // Every cell survives — the failure mode was losing all but one.
+    expect(merged).toContain('claude cell 1')
+    expect(merged).toContain('claude cell 2')
+    expect(merged).toContain('kimi cell 1')
+    expect(merged).toContain('kimi cell 2')
+    expect(merged!.trim().split('\n')).toHaveLength(4)
+    // Deterministic: ordered by cell id.
+    expect(merged).toBe(
+      '{"t":0,"phase":"setup","decision":"claude cell 1","reason":"r"}\n' +
+      '{"t":0,"phase":"setup","decision":"claude cell 2","reason":"r"}\n' +
+      '{"t":0,"phase":"setup","decision":"kimi cell 1","reason":"r"}\n' +
+      '{"t":0,"phase":"setup","decision":"kimi cell 2","reason":"r"}\n'
+    )
+  })
+
+  it('the prompt each cell actually receives names its own log file', async () => {
+    const prompts: string[] = []
+    const files = new Map<string, string>()
+
+    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 (opts: { brief: string }) => {
+        prompts.push(opts.brief)
+        return { stdout: '', stderr: '', durationMs: 1 }
+      },
+      exists: (path: string) => path === '/tmp/deck.toml',
+      chdir: () => {},
+    }
+
+    await runArenaFromToml({
+      toml: parseArenaToml(TOML_TWO_SIDES_TWO_RUNS),
+      taskPath: '/tmp/task.md',
+      outDir: '/tmp/arena-out',
+      io: mockIO,
+    })
+
+    // Two cells per side share ONE workdir — the prompts must not name one file.
+    expect(prompts).toHaveLength(4)
+    expect(prompts[0]).toContain('MANDATORY — write decision-log-claude-run-1.jsonl')
+    expect(prompts[1]).toContain('MANDATORY — write decision-log-claude-run-2.jsonl')
+    expect(prompts[2]).toContain('MANDATORY — write decision-log-kimi-run-1.jsonl')
+    expect(prompts[3]).toContain('MANDATORY — write decision-log-kimi-run-2.jsonl')
+    expect(new Set(prompts.map(p => p.match(/write (\S+\.jsonl)/)?.[1])).size).toBe(4)
+  })
+
+  it('no cell produced a log → no merged file invented', async () => {
+    const files = new Map<string, string>()
+    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 () => ({ stdout: '', stderr: '', durationMs: 1 }),
+      exists: (path: string) => path === '/tmp/deck.toml',
+      chdir: () => {},
+    }
+
+    await runArenaFromToml({
+      toml: parseArenaToml(TOML_TWO_SIDES_TWO_RUNS),
+      taskPath: '/tmp/task.md',
+      outDir: '/tmp/arena-out',
+      io: mockIO,
+    })
+
+    expect(files.has('/tmp/arena-out/decision-log.jsonl')).toBe(false)
+  })
+})

package/src/runner.ts

@@ -12,11 +12,11 @@ try { await import('@lythos/agent-adapter-deepseek-serve') } catch { /* package
 try { await import('@lythos/agent-adapter-deepseek-harness') } catch { /* package not installed */ }
 try { await import('@lythos/agent-adapter-codex') } catch { /* package not installed */ }
 import { runComparativeJudge } from './comparative-judge'
-import { parseArenaToml, buildExecutionPlan, type ArenaToml, type ExecutionPlan } from './arena-toml'
+import { parseArenaToml, buildExecutionPlan, type ArenaToml, type ExecutionPlan, type ExecutionCell } from './arena-toml'
 import { resolvePlayer, resolveSides } from './player'
 import { aggregateAllStats } from './stats'
 import type { SideStats } from './stats'
-import { buildCopyPlan } from './preflight'
+import { buildCopyPlan, buildAgentsMd, parseDeckCombos, decisionLogName, mergeDecisionLogs, type DecisionLogSource } from './preflight'
 
 // ── ArenaIO interface (Intent/Plan/Execute fractal pattern) ───────────────
 
@@ -99,8 +99,11 @@ export function buildArenaPrompt(opts: {
   deckPath: string
   outputDir?: string
   preflightReport?: string
+  /** Cell id — when set, the mandated log is `decision-log-<id>.jsonl` (per-cell). */
+  cellId?: string
 }): string {
   const out = opts.outputDir ?? opts.cwd
+  const logName = decisionLogName(opts.cellId)
   const lines = [
     'You are running an arena evaluation cell.',
     '',
@@ -108,7 +111,11 @@ export function buildArenaPrompt(opts: {
     `Deck: ${opts.deckPath}`,
     `Produce output to: ${out}/`,
     '',
-    'MANDATORY — write decision-log.jsonl to the output directory.',
+    `MANDATORY — write ${logName} to the output directory.`,
+    ...(opts.cellId
+      ? ['That per-cell name is yours alone: the workdir is shared with other cells,',
+         'and a shared filename means the last writer erases everyone else\'s trail.']
+      : []),
     'Each line is one JSON object with: t (seconds elapsed),',
     'phase (setup/content/design/output), decision (what you chose),',
     'reason (why). This is your decision trail — the only way the',
@@ -132,6 +139,18 @@ export function buildArenaPrompt(opts: {
   return lines.join('\n')
 }
 
+// ── Cell identity ─────────────────────────────────────────────────────────
+
+/**
+ * Deterministic cell id for a planned cell.
+ *
+ * Cells of one side share a workdir (`work/<side>/`), so the id is what keeps
+ * their decision logs — and any other per-cell artifact — from sharing a path.
+ */
+export function cellIdOf(cell: ExecutionCell): string {
+  return `${cell.side}-run-${cell.run}`
+}
+
 // ── Plan formatting ───────────────────────────────────────────────────────
 
 export function formatPlanOutput(plan: ExecutionPlan): string[] {
@@ -234,15 +253,15 @@ export async function runArenaFromToml(opts: {
 
     try {
       // Setup: deck + AGENTS.md + link
-      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',
-        '- Isolated arena test directory. Skills in skill-deck.toml, linked via deck link.',
-        '- Complete the task using available skills. Output to this directory.',
-        '- MANDATORY: write decision-log.jsonl (see prompt for schema).',
-      ].join('\n'))
+      const cellDeckRaw = ioWithDefaults.readFile(cell.deck)
+      ioWithDefaults.writeFile(join(workDir, 'skill-deck.toml'), cellDeckRaw)
+      let cellDeckParsed: Record<string, any> = {}
+      try { cellDeckParsed = Bun.TOML.parse(cellDeckRaw) as Record<string, any> } catch {}
+      ioWithDefaults.writeFile(join(workDir, 'AGENTS.md'), buildAgentsMd({
+        mode: 'A/B cell',
+        headerLines: [`**Side**: ${cell.side}`, `**Player**: ${cell.player}`, `**Run**: ${cell.run}`],
+        combos: parseDeckCombos(cellDeckParsed),
+      }))
       const linkProc = await ioWithDefaults.spawn(
         ['bunx', '@lythos/skill-deck', 'link'],
         { cwd: workDir, env: { ...process.env, HOME: process.env.HOME! } },
@@ -257,6 +276,7 @@ export async function runArenaFromToml(opts: {
         cwd: workDir,
         deckPath: cell.deck,
         outputDir: workDir,
+        cellId: cellIdOf(cell),
       })
       const agentResult = await ioWithDefaults.agentSpawn({
         player: resolvePlayer(cell.player),
@@ -334,6 +354,26 @@ export async function runArenaFromToml(opts: {
     }
   }
 
+  // ── Collect: merge per-cell decision logs into one decision-log.jsonl ───
+  // Cells sharing a side workdir each wrote their own file (see cellIdOf);
+  // the merged file is what a reader/judge opens, the per-cell files stay as
+  // provenance. Written only when at least one cell produced a log.
+  const logSources: DecisionLogSource[] = []
+  for (const cell of plan.cells) {
+    const logPath = join(artifactsDir, 'work', cell.side, decisionLogName(cellIdOf(cell)))
+    try {
+      if (ioWithDefaults.exists(logPath)) {
+        logSources.push({ cell: cellIdOf(cell), content: ioWithDefaults.readFile(logPath) })
+      }
+    } catch (e) {
+      io.log?.(`⚠️ Failed to read decision log for ${cellIdOf(cell)}: ${e instanceof Error ? e.message : e}`)
+    }
+  }
+  if (logSources.length > 0) {
+    ioWithDefaults.writeFile(join(artifactsDir, 'decision-log.jsonl'), mergeDecisionLogs(logSources))
+    io.log?.(`[arena] merged ${logSources.length} per-cell decision log(s) → ${artifactsDir}/decision-log.jsonl`)
+  }
+
   // Aggregate + comparative
   const stats = aggregateAllStats(verdictsBySide)
   const flatVerdicts: { participantId: string; verdict: unknown }[] = []