@tangle-network/agent-bench 0.3.7 → 0.4.0

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

@@ -0,0 +1,300 @@
+/**
+ * Gen-5 activation gate: predicate validation, execution over run artifacts
+ * (grep + script, ws/ skip with ws/.loops searched), the prefilter kill for a
+ * missing/invalid predicate, and the quarantine verdict path (an improved
+ * score with a never-fired mechanism is quarantined, not promoted).
+ */
+
+import { existsSync } from 'node:fs'
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import type { AnalystFinding } from '@tangle-network/agent-eval'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import {
+  ACTIVATION_PREDICATE_RELPATH,
+  activationPredicateInstruction,
+  parseActivationPredicate,
+  runActivationPredicate,
+} from './activation.mts'
+import { decideVerdict } from './cell-evidence.mts'
+import { defaultRound4Config, parseStaircaseRow, STAIRCASE_SCHEMA, type OuterLoopConfig, type StaircaseRow } from './outer-loop.mts'
+import { fanOutLoopsGenerator, type ProposerSpec } from './proposer-fanout.mts'
+import { runOk } from './proc.ts'
+
+describe('parseActivationPredicate', () => {
+  it('accepts a valid grep predicate (with optional files filters)', () => {
+    const parsed = parseActivationPredicate(
+      JSON.stringify({
+        description: 'patchRiskWarnings emitted in at least one settle',
+        kind: 'grep',
+        pattern: 'patchRiskWarnings|patch-risk',
+        files: ['journal.jsonl', 'workers/'],
+      }),
+    )
+    expect(parsed.ok).toBe(true)
+  })
+
+  it('accepts a valid script predicate', () => {
+    const parsed = parseActivationPredicate(
+      JSON.stringify({ description: 'x', kind: 'script', script: 'grep -rq X .' }),
+    )
+    expect(parsed.ok).toBe(true)
+  })
+
+  it.each([
+    ['not json', 'not valid JSON'],
+    ['[]', 'JSON object'],
+    [JSON.stringify({ description: '', kind: 'grep', pattern: 'a' }), 'description'],
+    [JSON.stringify({ description: 'x', kind: 'grep' }), 'pattern'],
+    [JSON.stringify({ description: 'x', kind: 'grep', pattern: '(' }), 'RegExp'],
+    [JSON.stringify({ description: 'x', kind: 'grep', pattern: 'a', files: [1] }), 'files'],
+    [JSON.stringify({ description: 'x', kind: 'script' }), 'script'],
+    [JSON.stringify({ description: 'x', kind: 'sql' }), 'kind'],
+  ])('rejects %s', (raw, want) => {
+    const parsed = parseActivationPredicate(raw)
+    expect(parsed.ok).toBe(false)
+    if (!parsed.ok) expect(parsed.error).toContain(want)
+  })
+
+  it('the prompt instruction carries the template and the quarantine warning', () => {
+    const text = activationPredicateInstruction()
+    expect(text).toContain(ACTIVATION_PREDICATE_RELPATH)
+    expect(text).toContain('QUARANTINED')
+    expect(text).toContain('"kind": "grep"')
+  })
+})
+
+describe('runActivationPredicate', () => {
+  let runA: string
+  let runB: string
+
+  beforeEach(async () => {
+    runA = await mkdtemp(join(tmpdir(), 'act-a-'))
+    runB = await mkdtemp(join(tmpdir(), 'act-b-'))
+    await writeFile(join(runA, 'driver.log'), 'boot\nno mechanism here\n')
+    await writeFile(join(runB, 'driver.log'), 'boot\npatchRiskWarnings: 2 warnings emitted\n')
+  })
+
+  afterEach(async () => {
+    await rm(runA, { recursive: true, force: true })
+    await rm(runB, { recursive: true, force: true })
+  })
+
+  const grep = (pattern: string, files?: string[]) => ({
+    description: 'd',
+    kind: 'grep' as const,
+    pattern,
+    ...(files ? { files } : {}),
+  })
+
+  it('fires with path:line evidence when the pattern appears in ANY run dir', async () => {
+    const res = await runActivationPredicate(grep('patchRiskWarnings'), [runA, runB])
+    expect(res.fired).toBe(true)
+    expect(res.checkedRunDirs).toBe(2)
+    expect(res.evidence[0]).toContain(join(runB, 'driver.log'))
+    expect(res.evidence[0]).toContain('patchRiskWarnings')
+  })
+
+  it('does not fire when the pattern never appears (fail-closed)', async () => {
+    const res = await runActivationPredicate(grep('neverEverPresent'), [runA, runB])
+    expect(res.fired).toBe(false)
+    expect(res.evidence).toEqual([])
+  })
+
+  it('honors files filters (relative-path substring)', async () => {
+    await writeFile(join(runB, 'other.txt'), 'patchRiskWarnings\n')
+    const onlyOther = await runActivationPredicate(grep('patchRiskWarnings', ['other.txt']), [runB])
+    expect(onlyOther.fired).toBe(true)
+    const onlyMissing = await runActivationPredicate(grep('patchRiskWarnings', ['nope.bin']), [runB])
+    expect(onlyMissing.fired).toBe(false)
+  })
+
+  it('skips the ws/ workspace subtree EXCEPT ws/.loops (supervisor artifacts)', async () => {
+    // Marker only inside ws/ (a checked-out repo) → must NOT count as fired.
+    await mkdir(join(runA, 'ws', 'src'), { recursive: true })
+    await writeFile(join(runA, 'ws', 'src', 'code.py'), 'patchRiskWarnings in the repo source\n')
+    const inWs = await runActivationPredicate(grep('patchRiskWarnings'), [runA])
+    expect(inWs.fired).toBe(false)
+    // Marker in ws/.loops → the supervisor's own artifacts, searched.
+    await mkdir(join(runA, 'ws', '.loops', 'supervisor', 's1'), { recursive: true })
+    await writeFile(join(runA, 'ws', '.loops', 'supervisor', 's1', 'journal.jsonl'), '{"k":"patchRiskWarnings"}\n')
+    const inLoops = await runActivationPredicate(grep('patchRiskWarnings'), [runA])
+    expect(inLoops.fired).toBe(true)
+  })
+
+  it('script kind fires on rc=0 in any run dir, not-fired otherwise', async () => {
+    const script = (s: string) => ({ description: 'd', kind: 'script' as const, script: s })
+    const hit = await runActivationPredicate(script('grep -q patchRiskWarnings driver.log'), [runA, runB])
+    expect(hit.fired).toBe(true)
+    expect(hit.evidence[0]).toContain(runB)
+    const miss = await runActivationPredicate(script('grep -q neverEverPresent driver.log'), [runA, runB])
+    expect(miss.fired).toBe(false)
+  })
+})
+
+describe('quarantine verdict path', () => {
+  const base = {
+    violations: [],
+    coverageComplete: true,
+    resolvedCount: 3,
+    parentResolvedCount: 1,
+    costRatio: 1.0,
+    costGuardRatio: 1.2,
+  }
+
+  it('quarantines a candidate whose mechanism never fired EVEN when its score improved', () => {
+    expect(decideVerdict({ ...base, activationFired: false })).toBe('quarantined-inactive')
+  })
+
+  it('accepts an improved candidate whose mechanism fired; gate-not-applicable behaves as before', () => {
+    expect(decideVerdict({ ...base, activationFired: true })).toBe('accepted')
+    expect(decideVerdict({ ...base, activationFired: null })).toBe('accepted')
+    expect(decideVerdict(base)).toBe('accepted')
+  })
+
+  it('out-of-space still wins over quarantine; quarantine wins over no-gain/cost/coverage', () => {
+    expect(decideVerdict({ ...base, violations: ['judge.py'], activationFired: false })).toBe('rejected-out-of-space')
+    expect(decideVerdict({ ...base, coverageComplete: false, activationFired: false })).toBe('quarantined-inactive')
+    expect(decideVerdict({ ...base, resolvedCount: 1, activationFired: false })).toBe('quarantined-inactive')
+  })
+
+  it('parseStaircaseRow accepts a quarantined row with gen-5 split + activation fields', () => {
+    const row: StaircaseRow = {
+      schema: STAIRCASE_SCHEMA,
+      round: 4,
+      generation: 0,
+      runId: 'r4-x',
+      at: new Date(0).toISOString(),
+      candidate: 'hash',
+      candidateCommit: 'c'.repeat(40),
+      parent: 'baseline',
+      parentResolvedCount: 1,
+      changedFiles: [],
+      changeSpaceViolations: [],
+      perInstance: [],
+      resolvedCount: 3,
+      coverageComplete: true,
+      wallS: 10,
+      baselineWallS: 10,
+      costRatio: 1,
+      costGuardRatio: 1.2,
+      internallyPromoted: true,
+      verdict: 'quarantined-inactive',
+      holdout: 'operator-approval-required',
+      armProvenance: null,
+      diffPath: null,
+      diffSha256: null,
+      split: {
+        publicInstances: ['a', 'b'],
+        privateInstances: ['c'],
+        publicResolvedCount: 2,
+        privateResolvedCount: 1,
+      },
+      activation: { present: true, description: 'd', fired: false, evidence: [], warnings: [] },
+    }
+    expect(parseStaircaseRow(JSON.stringify(row))).toEqual(row)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Prefilter enforcement — a candidate without a parseable predicate is killed
+// before any evaluation spend.
+// ---------------------------------------------------------------------------
+
+describe('activation-predicate prefilter', () => {
+  let loopsRepo: string
+  let outDir: string
+  let driverWt: string
+
+  beforeEach(async () => {
+    loopsRepo = await mkdtemp(join(tmpdir(), 'act-repo-'))
+    outDir = await mkdtemp(join(tmpdir(), 'act-out-'))
+    await runOk('git', ['init', '-q', '-b', 'main', loopsRepo])
+    await runOk('git', ['-C', loopsRepo, 'config', 'user.email', 't@t.dev'])
+    await runOk('git', ['-C', loopsRepo, 'config', 'user.name', 'T'])
+    await writeFile(join(loopsRepo, 'src.ts'), 'base\n')
+    await runOk('git', ['-C', loopsRepo, 'add', '-A'])
+    await runOk('git', ['-C', loopsRepo, 'commit', '-q', '-m', 'init'])
+    driverWt = join(outDir, 'driver-wt')
+    await runOk('git', ['-C', loopsRepo, 'worktree', 'add', '--detach', driverWt, 'HEAD'])
+  })
+
+  afterEach(async () => {
+    await rm(outDir, { recursive: true, force: true })
+    await rm(loopsRepo, { recursive: true, force: true })
+  })
+
+  const config = (proposers: ProposerSpec[]): OuterLoopConfig => ({
+    ...defaultRound4Config(),
+    loopsRepo,
+    outDir,
+    populationSize: proposers.length,
+    proposers,
+    activationGate: true,
+  })
+
+  const generatorArgs = (candidateIndex: number) => ({
+    worktreePath: driverWt,
+    report: undefined,
+    findings: [] as AnalystFinding[],
+    maxShots: 1,
+    signal: new AbortController().signal,
+    generation: 0,
+    candidateIndex,
+  })
+
+  it('kills a candidate without .improve/activation.json (stage activation-predicate) and passes one WITH it', async () => {
+    const proposers: ProposerSpec[] = [
+      { name: 'with-predicate', harness: 'claude' },
+      { name: 'without-predicate', harness: 'claude' },
+      { name: 'invalid-predicate', harness: 'claude' },
+    ]
+    const gen = fanOutLoopsGenerator(config(proposers), {
+      author: async (proposer, args) => {
+        await mkdir(join(args.worktreePath, 'extensions', 'pi'), { recursive: true })
+        await writeFile(join(args.worktreePath, 'extensions', 'pi', `${proposer.name}.ts`), 'x\n')
+        if (proposer.name === 'with-predicate') {
+          await mkdir(join(args.worktreePath, '.improve'), { recursive: true })
+          await writeFile(
+            join(args.worktreePath, ACTIVATION_PREDICATE_RELPATH),
+            JSON.stringify({ description: 'd', kind: 'grep', pattern: 'x' }),
+          )
+        } else if (proposer.name === 'invalid-predicate') {
+          await mkdir(join(args.worktreePath, '.improve'), { recursive: true })
+          await writeFile(join(args.worktreePath, ACTIVATION_PREDICATE_RELPATH), '{}')
+        }
+        return { applied: true, summary: `${proposer.name} edit` }
+      },
+    })
+
+    const survivor = await gen.generate(generatorArgs(0))
+    const missing = await gen.generate(generatorArgs(1))
+    const invalid = await gen.generate(generatorArgs(2))
+
+    expect(survivor.applied).toBe(true)
+    expect(missing.applied).toBe(false)
+    expect(invalid.applied).toBe(false)
+    const kills = gen.drainPrefilterKills()
+    expect(kills).toHaveLength(2)
+    expect(kills.find((k) => k.proposer === 'without-predicate')).toMatchObject({ stage: 'activation-predicate' })
+    expect(kills.find((k) => k.proposer === 'without-predicate')!.reason).toContain('missing')
+    expect(kills.find((k) => k.proposer === 'invalid-predicate')!.reason).toContain('invalid')
+    // The survivor's predicate landed on the driver worktree with the patch.
+    expect(existsSync(join(driverWt, ACTIVATION_PREDICATE_RELPATH))).toBe(true)
+  })
+
+  it('does not require a predicate when the gate is off (gen-4 behavior unchanged)', async () => {
+    const cfg = config([{ name: 'legacy', harness: 'claude' }])
+    cfg.activationGate = false
+    const gen = fanOutLoopsGenerator(cfg, {
+      author: async (_p, args) => {
+        await mkdir(join(args.worktreePath, 'extensions', 'pi'), { recursive: true })
+        await writeFile(join(args.worktreePath, 'extensions', 'pi', 'l.ts'), 'x\n')
+        return { applied: true, summary: 'edit' }
+      },
+    })
+    expect((await gen.generate(generatorArgs(0))).applied).toBe(true)
+    expect(gen.drainPrefilterKills()).toEqual([])
+  })
+})

package/src/swe-arena/arms.ts

@@ -346,6 +346,14 @@ export interface ArmRunContext {
   instanceId: string
   image: string
   baseCommit: string
+  /**
+   * Workspace materialization override. Default (undefined) = SWE instance
+   * image materialization (docker cp of /testbed). Factory instances inject
+   * their archive-export + synthetic-history materialization here so the arm
+   * runners themselves stay instance-kind-agnostic. Must leave `dest` a git
+   * repo whose HEAD is the diff base for patch extraction (`baseCommit`).
+   */
+  materialize?: (dest: string) => Promise<void>
   problemStatement: string
   /** Self-repro verify command (bash -c, cwd = ws) — the MEASUREMENT gate. */
   verifyCmd: string
@@ -448,13 +456,17 @@ export async function runSoloArm(spec: SoloArmSpec, ctx: ArmRunContext): Promise
   const ws = join(runDir, 'ws')
   await mkdir(runDir, { recursive: true })
   const cell = await prepareIsolatedCellEnvironment(runDir)
-  await materializeWorkspace({
-    instanceId: ctx.instanceId,
-    image: ctx.image,
-    baseCommit: ctx.baseCommit,
-    dest: ws,
-    signal: ctx.signal,
-  })
+  // A caller-supplied materializer (synthetic-history factory cells) replaces the
+  // SWE-bench image checkout, but still runs inside the isolated cell above.
+  if (ctx.materialize) await ctx.materialize(ws)
+  else
+    await materializeWorkspace({
+      instanceId: ctx.instanceId,
+      image: ctx.image,
+      baseCommit: ctx.baseCommit,
+      dest: ws,
+      signal: ctx.signal,
+    })
 
   const promptFile = join(runDir, 'prompt.txt')
   await writeFile(promptFile, ctx.problemStatement + (spec.promptSuffix ?? WORKER_PROMPT_SUFFIX))
@@ -578,13 +590,17 @@ export async function runSupervisorArm(spec: SupervisorArmSpec, ctx: ArmRunConte
   const ws = join(runDir, 'ws')
   await mkdir(runDir, { recursive: true })
   const cell = await prepareIsolatedCellEnvironment(runDir)
-  await materializeWorkspace({
-    instanceId: ctx.instanceId,
-    image: ctx.image,
-    baseCommit: ctx.baseCommit,
-    dest: ws,
-    signal: ctx.signal,
-  })
+  // A caller-supplied materializer (synthetic-history factory cells) replaces the
+  // SWE-bench image checkout, but still runs inside the isolated cell above.
+  if (ctx.materialize) await ctx.materialize(ws)
+  else
+    await materializeWorkspace({
+      instanceId: ctx.instanceId,
+      image: ctx.image,
+      baseCommit: ctx.baseCommit,
+      dest: ws,
+      signal: ctx.signal,
+    })
 
   const paramsFile = join(runDir, 'params.json')
   await writeFile(

package/src/swe-arena/briefing.mts

@@ -0,0 +1,217 @@
+/**
+ * Gen-5 author briefing — MAP + TOOLBOX + PERMISSION (gen5_design).
+ *
+ * Principle: fully agentic evidence access, NO pre-digestion machinery. The
+ * dossier-compiler / ranked-briefing pipeline is dead; instead each run writes
+ * an INDEX FILE (a map: one line per evidence path) and the author prompt
+ * names the pre-existing TOOLS the author may drive itself, plus explicit
+ * permission to spawn its own subagents under a research budget. The
+ * 3-analyst diagnosis ensemble stays as ONE input among these — no longer the
+ * sole channel.
+ *
+ * SELF-IMPROVING BRIEFING: the briefing text itself lives in the declared
+ * change-space — `extensions/pi/author-briefing.md` in the loops repo. When
+ * that file exists at the incumbent ref it REPLACES the default text below,
+ * so a future generation's author can rewrite its own research instructions
+ * and the gate decides whether that rewrite earns its keep. The default here
+ * is the versioned fallback (`AUTHOR_BRIEFING_VERSION`).
+ *
+ * PUBLIC/PRIVATE INTERACTION: the index is proposer-visible text, so
+ * per-instance evidence rows for PRIVATE instances (score-split.mts) are
+ * excluded and the writer fails loud if a private id leaks into the rendered
+ * index.
+ */
+
+import { existsSync } from 'node:fs'
+import { readdir, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { leaksPrivateInstance, type ScoreSplit } from './score-split.mts'
+import { run } from './proc.ts'
+
+export const AUTHOR_BRIEFING_VERSION = 'map-toolbox-v1'
+
+/** Loops-repo path (inside the declared change-space) whose content, when
+ *  present at the incumbent ref, replaces the default briefing text. */
+export const AUTHOR_BRIEFING_RELPATH = 'extensions/pi/author-briefing.md'
+
+export const EVIDENCE_INDEX_FILENAME = 'evidence-index.md'
+
+/** The default TOOLBOX + PERMISSION briefing. Every tool named here already
+ *  exists — nothing bespoke is built for the author. */
+export function defaultAuthorBriefing(): string {
+  return [
+    `<!-- author-briefing ${AUTHOR_BRIEFING_VERSION} (default; override by committing ${AUTHOR_BRIEFING_RELPATH}) -->`,
+    'RESEARCH BRIEFING — you have hands. Read the evidence yourself before editing.',
+    '',
+    'TOOLBOX (all pre-existing — drive them yourself):',
+    '- traces CLI (published): `npx --yes @tangle-network/traces@latest analyze --help` — analyze any',
+    '  harness run trace (worker/supervisor sessions) for failure patterns, tool-call churn, dead ends.',
+    '- agent-eval trace analysts (`@tangle-network/agent-eval/analyst`): structured extraction over run',
+    '  artifacts when you want findings objects rather than prose.',
+    '- AxLLM (`@ax-llm/ax`): question-answering over a corpus too large to read — point it at a run dir',
+    '  and ask targeted questions instead of paging through megabytes.',
+    '- Plain grep/jq over the evidence map below — often the fastest tool.',
+    '',
+    'PERMISSION: you may spawn your own subagents (research fan-out) before writing any code.',
+    'Research budget: up to ~15 minutes / ~200k tokens of reading+subagents before your first edit;',
+    'spend it on the evidence paths in the map, not on re-deriving what they already record.',
+    '',
+    'The diagnosis findings in this prompt come from a 3-analyst ensemble. Treat them as ONE input',
+    'among the evidence sources above — verify any finding you build on against the raw artifacts.',
+    '',
+    `SELF-IMPROVEMENT: this briefing text is part of the change-space (${AUTHOR_BRIEFING_RELPATH}).`,
+    'If your research process was hampered by these instructions, you may edit that file in your',
+    'candidate alongside your main change; future generations will read your version.',
+  ].join('\n')
+}
+
+/** Resolve the briefing text: the change-space override at `ref` when present,
+ *  else the versioned default. */
+export async function resolveAuthorBriefing(
+  loopsRepo: string,
+  ref: string,
+): Promise<{ text: string; source: 'change-space' | 'default' }> {
+  const show = await run('git', ['-C', loopsRepo, 'show', `${ref}:${AUTHOR_BRIEFING_RELPATH}`])
+  if (show.code === 0 && show.stdout.trim().length > 0) {
+    return { text: show.stdout, source: 'change-space' }
+  }
+  return { text: defaultAuthorBriefing(), source: 'default' }
+}
+
+// ---------------------------------------------------------------------------
+// The evidence index — a MAP, not a briefing: one line per evidence path.
+// ---------------------------------------------------------------------------
+
+export interface EvidenceIndexRow {
+  path: string
+  note: string
+  /** Instance the row is specific to (private rows are dropped); null = run-level. */
+  iid: string | null
+}
+
+export interface EvidenceIndexArgs {
+  outDir: string
+  /** Staircase + round-summary home. */
+  roundsDir: string
+  /** Prior-round failure artifacts (dir + optional patch), with instance ids. */
+  seedArtifactRuns: Array<{ iid: string; arm: string; dir: string; patchPath?: string }>
+  /** Prior run outDirs (e.g. the gen-4 outDir) whose arm-runs/judge evidence
+   *  the author may mine. */
+  priorEvidenceDirs?: string[]
+  /** Pareto parent diffs materialized to disk (written by the outer loop). */
+  paretoParentPatches?: Array<{ label: string; path: string }>
+  /** Public/private split; null = everything is public. */
+  split: ScoreSplit | null
+}
+
+/** Collect the index rows. Pure over the filesystem — reads directory names
+ *  only, never file contents. Private-instance rows are excluded. */
+export async function collectEvidenceIndexRows(args: EvidenceIndexArgs): Promise<EvidenceIndexRow[]> {
+  const priv = new Set(args.split?.privateInstances ?? [])
+  const rows: EvidenceIndexRow[] = []
+  const push = (path: string, note: string, iid: string | null = null): void => {
+    if (iid !== null && priv.has(iid)) return
+    rows.push({ path, note, iid })
+  }
+
+  // Staircase generations + round summaries (the improvement run's history).
+  for (const name of (await readdir(args.roundsDir).catch(() => [])).sort()) {
+    if (/^gen-\d+\.jsonl$/.test(name)) {
+      push(join(args.roundsDir, name), 'staircase rows — every prior candidate: diff, per-instance verdicts, kill reasons')
+    } else if (/^round\d+-summary-.*\.json$/.test(name)) {
+      push(join(args.roundsDir, name), 'round summary — baseline, winner, gate reasons, cost rollup')
+    }
+  }
+
+  // Prior-round seed artifacts (worker evidence, judge output, patches).
+  for (const seed of args.seedArtifactRuns) {
+    if (existsSync(seed.dir)) {
+      push(seed.dir, `prior ${seed.arm} run for ${seed.iid} — worker evidence, journal, driver log`, seed.iid)
+    }
+    if (seed.patchPath && existsSync(seed.patchPath)) {
+      push(seed.patchPath, `prior ${seed.arm} delivered patch for ${seed.iid}`, seed.iid)
+    }
+  }
+
+  // Prior run outDirs: candidate diffs, arm runs (incl. judge.json near-miss
+  // details per instance), proposer shot receipts.
+  for (const dir of args.priorEvidenceDirs ?? []) {
+    if (!existsSync(dir)) continue
+    const candidates = join(dir, 'candidates')
+    if (existsSync(candidates)) push(candidates, 'prior-run candidate diffs (one .patch per surface)')
+    const armRuns = join(dir, 'arm-runs')
+    for (const tag of (await readdir(armRuns).catch(() => [])).sort()) {
+      for (const rep of (await readdir(join(armRuns, tag)).catch(() => [])).sort()) {
+        const runsRoot = join(armRuns, tag, rep, 'runs')
+        for (const iid of (await readdir(runsRoot).catch(() => [])).sort()) {
+          push(
+            join(runsRoot, iid),
+            `prior arm run ${tag} ${rep} on ${iid} — result.json, judge.json (near-miss detail), brain.jsonl, ws/.loops worker evidence`,
+            iid,
+          )
+        }
+      }
+    }
+    const shots = join(dir, 'proposer-shots')
+    if (existsSync(shots)) push(shots, 'prior-run proposer shot receipts (what earlier authors tried)')
+  }
+
+  // Pareto parent diffs.
+  for (const parent of args.paretoParentPatches ?? []) {
+    if (existsSync(parent.path)) push(parent.path, `pareto parent diff — ${parent.label}`)
+  }
+
+  return rows
+}
+
+/** Render + write `<outDir>/evidence-index.md`. Fails loud if a private
+ *  instance id leaks into the rendered text (never-surfaced invariant). */
+export async function writeEvidenceIndex(args: EvidenceIndexArgs): Promise<{ path: string; rows: EvidenceIndexRow[] }> {
+  const rows = await collectEvidenceIndexRows(args)
+  const lines: string[] = [
+    `# Evidence map (${AUTHOR_BRIEFING_VERSION})`,
+    '',
+    'One line per evidence path. This is a MAP, not a digest — open what you need.',
+    ...(args.split !== null
+      ? [
+          '',
+          `NOTE: ${args.split.privateInstances.length} improvement instance(s) are PRIVATE this run: their`,
+          'identities and per-instance evidence are withheld from authors, but your candidate is still',
+          'selected on the full public+private set. Do not overfit the visible instances.',
+        ]
+      : []),
+    '',
+    ...rows.map((r) => `- ${r.path} — ${r.note}`),
+    '',
+  ]
+  const text = lines.join('\n')
+  if (args.split !== null) {
+    const leaks = leaksPrivateInstance(text, args.split)
+    if (leaks.length > 0) {
+      throw new Error(`evidence-index: private instance id(s) leaked into the index: ${leaks.join(', ')}`)
+    }
+  }
+  const path = join(args.outDir, EVIDENCE_INDEX_FILENAME)
+  await writeFile(path, text)
+  return { path, rows }
+}
+
+// ---------------------------------------------------------------------------
+// The prompt section (MAP + TOOLBOX + PERMISSION), appended per author.
+// ---------------------------------------------------------------------------
+
+export interface BriefingContext {
+  indexPath: string
+  briefingText: string
+  briefingSource: 'change-space' | 'default'
+}
+
+export function briefingPromptSection(ctx: BriefingContext): string {
+  return [
+    `EVIDENCE MAP: ${ctx.indexPath}`,
+    'Read it first — one line per evidence path (staircase history, prior arm runs + judge near-miss',
+    'details, worker evidence, parent diffs). Open the paths you need; nothing is pre-digested for you.',
+    '',
+    ctx.briefingText.trimEnd(),
+  ].join('\n')
+}