@xingular/harness 2.1.1 → 3.0.0

package/src/refine/cli.ts

@@ -0,0 +1,114 @@
+// `xingular-harness refine`: refinement from a terminal.
+//
+//   refine demo [--k N] [--mode parallel|sequential] [--out <dir>]
+//       Runs the deterministic ledger demo end to end with no model and no credentials.
+//   refine run --tree <dir> --task <file.md> [--source <dir>] [--scope <id>] [--k N]
+//              [--mode parallel|sequential] [--data <dir>] [--state <dir>] [--model <id>]
+//       Refines a harness tree on one task with the default Pi account.
+import { mkdtempSync, readFileSync } from 'node:fs'
+import { homedir, tmpdir } from 'node:os'
+import { basename, join, resolve } from 'node:path'
+
+import { createHarness } from '../harness'
+import * as store from '../tree/store'
+import { PI_SURFACE } from '../tree/surface'
+import { readTree } from '../tree/tree'
+import { DemoExecutor, DemoImprover, demoBaseTree, demoTasks } from './demo'
+import { Library } from './library'
+import { runRefinement, type RefineSummary } from './runner'
+import type { RecursionMode } from './types'
+
+export const REFINE_USAGE = `Usage: xingular-harness refine <demo | run> [options]
+
+  demo [--k N] [--mode parallel|sequential] [--out <dir>]
+        Run the deterministic demo: no model, no credentials.
+  run --tree <dir> --task <file.md> [--source <dir>] [--scope <id>] [--k N]
+      [--mode parallel|sequential] [--data <dir>] [--state <dir>] [--model <id>]
+        Refine a harness on one task with the default account. Costs about
+        4k executions and 3k improver sessions.
+`
+
+interface Parsed {
+  command: string | undefined
+  values: Record<string, string>
+}
+
+function parse(argv: string[]): Parsed {
+  const [command, ...rest] = argv
+  const values: Record<string, string> = {}
+  for (let i = 0; i < rest.length; i++) {
+    const arg = rest[i]!
+    if (arg.startsWith('--') && i + 1 < rest.length) values[arg.slice(2)] = rest[++i]!
+  }
+  return { command, values }
+}
+
+function mode(value: string | undefined): RecursionMode {
+  if (!value || value === 'parallel') return 'parallel'
+  if (value === 'sequential') return 'sequential'
+  throw new Error('--mode is parallel or sequential.')
+}
+
+function describe(summary: RefineSummary, write: (text: string) => void): void {
+  const ledger = summary.recursion?.ledger
+  write(`${summary.taskId}: ${summary.status}${ledger ? ` · R=${ledger.R}/${ledger.expectedR} executions, P=${ledger.P}/${ledger.expectedP} improver sessions` : ''} · $${summary.usd.toFixed(4)}\n`)
+  if (summary.selection?.chosenLabel) write(`  chose ${summary.selection.chosenLabel}${summary.chosenIsBase ? ' (unchanged harness)' : ''}: ${summary.selection.why.split('\n')[0]}\n`)
+  if (summary.experience?.lesson) write(`  lesson: ${summary.experience.lesson}\n`)
+  for (const error of summary.errors) write(`  ! ${error}\n`)
+}
+
+export async function runRefineCli(argv: string[], io: { write: (text: string) => void } = { write: (text) => void process.stdout.write(text) }): Promise<number> {
+  const { command, values } = parse(argv)
+  try {
+    if (command === 'demo') {
+      const root = values.out ? resolve(values.out) : mkdtempSync(join(tmpdir(), 'harness-refine-demo-'))
+      const k = Number(values.k ?? 1)
+      store.seed(root, 'demo', demoBaseTree(), 'demo base harness')
+      const executor = new DemoExecutor(root)
+      const improver = new DemoImprover()
+      for (const task of demoTasks(root)) {
+        const summary = await runRefinement({ root, id: `${task.id}-${mode(values.mode)}-${k}`, task, k, mode: mode(values.mode), executor, improver })
+        describe(summary, io.write)
+      }
+      io.write(`library: ${new Library(root, 'demo', 'accounting').entries().join(', ') || '(empty)'}\nrecords: ${join(root, 'refine')}\n`)
+      return 0
+    }
+    if (command === 'run') {
+      if (!values.tree || !values.task) {
+        io.write(REFINE_USAGE)
+        return 2
+      }
+      const base = join(homedir(), '.xingular-harness')
+      const harness = createHarness({ dataRoot: resolve(values.data ?? join(base, 'data')), stateDir: resolve(values.state ?? join(base, 'state')) })
+      try {
+        const scope = values.scope ?? basename(resolve(values.tree)).replace(/[^A-Za-z0-9_-]/g, '-')
+        const tree = readTree(PI_SURFACE, resolve(values.tree))
+        store.commit(harness.env.root, scope, tree, { kind: 'import', note: `from ${values.tree}` })
+        const prompt = readFileSync(resolve(values.task), 'utf8')
+        const { id } = harness.refine.start({
+          task: { id: basename(values.task).replace(/\.md$/, '').replace(/[^A-Za-z0-9_-]/g, '-'), prompt, scope, sourceDir: values.source ? resolve(values.source) : null },
+          k: Number(values.k ?? 1),
+          mode: mode(values.mode),
+          improver: values.model ? { model: values.model } : {}
+        })
+        harness.bus.on((notice) => {
+          if (notice.type === 'refine.event' && notice.id === id) {
+            const event = notice.event as { type: string; label?: string; phase?: string }
+            if (event.type === 'phase') io.write(`· ${event.phase}\n`)
+            else if (event.type === 'stage.finished' || event.type === 'rollout.finished') io.write(`  ${event.type === 'stage.finished' ? 'proposed' : 'ran'} ${event.label}\n`)
+          }
+        })
+        const summary = await harness.refine.wait(id)
+        if (summary) describe(summary, io.write)
+        return summary?.status === 'ok' ? 0 : 1
+      } finally {
+        await harness.close()
+      }
+    }
+    io.write(REFINE_USAGE)
+    return command ? 2 : 0
+  } catch (error) {
+    io.write(`${error instanceof Error ? error.message : String(error)}\n`)
+    return 1
+  }
+}

package/src/refine/demo.ts

@@ -0,0 +1,124 @@
+// A deterministic local executor and improver that exercise the real refinement workflow with
+// no model and no credentials: the base harness sums only positive ledger amounts, and the
+// scripted improver removes that filter.
+//
+// Ported from Harness² (Apache-2.0, Google LLC; `harness2/demo.py`).
+import { spawnSync } from 'node:child_process'
+import { cpSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import type { Tree } from '../tree/surface'
+import type { Executor, Improver, ImproverCall, ImproverReply, RefineTask, Rollout } from './types'
+
+export const DEMO_SCRIPT = `import { readFileSync } from 'node:fs'
+
+const rows = readFileSync(process.argv[2], 'utf8').trim().split('\\n').slice(1)
+const cents = rows.map((row) => Math.round(Number(row) * 100))
+const total = cents.filter((amount) => amount > 0).reduce((sum, amount) => sum + amount, 0)
+console.log(\`Total: \${(total / 100).toFixed(2)}\`)
+`
+
+export function demoBaseTree(): Tree {
+  return {
+    'systemprompt.md': 'Reconcile the ledger using node scripts/summarize.mjs.\n',
+    'guardrails.md': '',
+    'memory.md': '',
+    'tool_guidance.md': '',
+    'scripts/summarize.mjs': DEMO_SCRIPT
+  }
+}
+
+export const DEMO_LEDGERS: Record<string, string> = {
+  'ledger-1': '100.25\n-20.10\n5.00\n',
+  'ledger-2': '35.50\n-10.25\n-5.00\n'
+}
+
+/** Writes the demo's source ledgers under `root` and returns the tasks. */
+export function demoTasks(root: string, scope = 'demo'): RefineTask[] {
+  return Object.entries(DEMO_LEDGERS).map(([id, amounts]) => {
+    const sourceDir = join(root, 'sources', id)
+    mkdirSync(sourceDir, { recursive: true })
+    writeFileSync(join(sourceDir, 'ledger.csv'), `amount\n${amounts}`)
+    writeFileSync(join(sourceDir, 'reference_answer.txt'), 'never shown to a model')
+    return {
+      id,
+      scope,
+      domain: 'accounting',
+      prompt: 'Sum every signed amount in ledger.csv. Return Total: with two decimal places.',
+      sourceDir,
+      leakGlobs: ['reference_answer.txt'],
+      prompts: { work: 'reconcile signed amounts in a transaction ledger' }
+    }
+  })
+}
+
+export class DemoExecutor implements Executor {
+  executions = 0
+
+  constructor(private readonly root: string) {}
+
+  async execute(task: RefineTask, harnessDir: string | null, label: string, runId: string): Promise<Rollout> {
+    this.executions++
+    const dir = join(this.root, 'executions', runId)
+    mkdirSync(dir, { recursive: true })
+    const script = join(harnessDir ?? '', 'scripts', 'summarize.mjs')
+    const result = spawnSync(process.execPath, [script, join(task.sourceDir ?? '', 'ledger.csv')], { encoding: 'utf8', timeout: 10_000 })
+    if (result.status !== 0) {
+      return { label, runId, dir, ok: false, delivered: false, costUsd: 0, wallMs: 0, error: result.stderr || 'script failed' }
+    }
+    writeFileSync(join(dir, 'answer.txt'), result.stdout)
+    writeFileSync(join(dir, 'trajectory.md'), `[ACTION] Run scripts/summarize.mjs on ledger.csv\n[OBSERVATION]\n${result.stdout}`)
+    return { label, runId, dir, ok: true, delivered: true, costUsd: 0, wallMs: 0, error: '' }
+  }
+
+  trajectory(rollout: Rollout): string {
+    return readFileSync(join(rollout.dir, 'trajectory.md'), 'utf8')
+  }
+
+  deliverableFiles(rollout: Rollout): Record<string, string> {
+    const path = join(rollout.dir, 'answer.txt')
+    return existsSync(path) ? { 'answer.txt': readFileSync(path, 'utf8') } : {}
+  }
+
+  validateTree(_task: RefineTask, tree: Tree): void {
+    if (!tree['scripts/summarize.mjs']) throw new Error('The local executor requires scripts/summarize.mjs')
+  }
+}
+
+function signedTotal(ledger: string): string {
+  const cents = ledger.trim().split('\n').slice(1).map((row) => Math.round(Number(row) * 100))
+  return (cents.reduce((sum, amount) => sum + amount, 0) / 100).toFixed(2)
+}
+
+/** Scripted edits, selection and reflection. */
+export class DemoImprover implements Improver {
+  readonly calls: string[] = []
+
+  async call(input: ImproverCall): Promise<ImproverReply> {
+    this.calls.push(input.label)
+    const context = input.contextDir
+    let workspace: string | null = null
+    let text: string
+    if (input.label.startsWith('select.')) {
+      const expected = `Total: ${signedTotal(readFileSync(join(context, 'source', 'ledger.csv'), 'utf8'))}`
+      const ids = readdirSync(join(context, 'candidates')).filter((name) => name.endsWith('.md')).sort()
+      const chosen = ids.find((name) => readFileSync(join(context, 'candidates', name), 'utf8').includes(expected))?.replace(/\.md$/, '') ?? ids[0]!.replace(/\.md$/, '')
+      text = `<why>The signed total matches the source ledger.</why>\n\`\`\`choice\n${chosen}\n\`\`\``
+    } else if (input.label.startsWith('experience.')) {
+      const changed = readFileSync(join(context, 'harness', 'scripts', 'summarize.mjs'), 'utf8') !== readFileSync(join(context, 'base_harness', 'scripts', 'summarize.mjs'), 'utf8')
+      text =
+        `<edits>\ncomponent: scripts/summarize.mjs\ncandidates: inv1\nchange: dropped the positive-only filter from the amount sum\nobserved: the probe total included the credits the base run omitted\nverdict: ${changed ? 'helped' : 'no observed effect'}\n</edits>\n\n` +
+        (changed
+          ? '<experience>\ncue: When a ledger includes credits and debits\nlesson: Include both signs when summing in scripts/summarize.mjs.\nevidence: The scripts/summarize.mjs row -- removing the positive-only filter changed the probe total to include the credits omitted by the base trajectory.\nconfidence: high for this observed arithmetic contrast\n</experience>'
+          : 'NO_ENTRY')
+    } else {
+      workspace = mkdtempSync(join(tmpdir(), 'harness-demo-'))
+      cpSync(join(context, 'harness'), workspace, { recursive: true })
+      const script = join(workspace, 'scripts', 'summarize.mjs')
+      writeFileSync(script, readFileSync(script, 'utf8').replace('.filter((amount) => amount > 0)', ''))
+      text = '<notes>Keep signed amounts: the base total omitted credits in the source ledger.</notes>'
+    }
+    return { label: input.label, text, costUsd: 0, attempts: 1, cached: false, workspace }
+  }
+}

package/src/refine/evidence.ts

@@ -0,0 +1,349 @@
+// The evidence folder an improver reads. Evidence is served as files and the prompt is a short
+// pointer, so nothing is truncated to fit a prompt:
+//
+//   context/task.md                  the task as the agent received it
+//   context/source/                  the material it was done from
+//   context/rollouts/<label>.md      full trajectories
+//   context/deliverables/<label>/    what each rollout produced
+//   context/harness/<rel>            the tree being edited
+//   context/library/INDEX.md         earlier tasks in this area and their full harnesses
+//   context/pool/<label>/            candidate harnesses, their diffs and rollouts
+//   context/decisions/<label>.md     earlier edit and composition notes
+//
+// Ported from Harness² (Apache-2.0, Google LLC; `harness2/core/context.py`).
+import { copyFileSync, cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import { dirname, extname, join, relative, sep } from 'node:path'
+
+import { PI_SURFACE, type Tree } from '../tree/surface'
+import { readTree } from '../tree/tree'
+import type { Executor, RefineTask, Rollout } from './types'
+
+/** Strings that only a grader's own output contains. A tripwire, not the defence itself. */
+export const GRADER_VERDICT_MARKERS = [
+  'deterministic_eval_summary',
+  'deterministic_eval_result',
+  'judge_scope_and_deterministic_status',
+  'Judge findings on the rendered result',
+  '"passed_count"',
+  '"pass_rate"',
+  '"test_pass_rate"',
+  'review_verdict',
+  '"reviewVerdict"'
+] as const
+
+const SCANNED = new Set(['.md', '.txt', '.json', '.csv', '.tsv', '.yaml', '.yml', '.html', '.htm', '.log', '.py', '.js', '.mjs', '.ts', '.sh', '.xml', '.ini', '.toml', '.patch', '.diff', ''])
+
+/** Minimum per-observation truncation; lower values fabricate defects. */
+export const MIN_OBS_TRUNC = 10_000
+
+function files(dir: string): string[] {
+  const out: string[] = []
+  let names: string[]
+  try {
+    names = readdirSync(dir)
+  } catch {
+    return out
+  }
+  for (const name of names.sort()) {
+    const path = join(dir, name)
+    let isDir = false
+    try {
+      isDir = statSync(path).isDirectory()
+    } catch {
+      continue
+    }
+    if (isDir) out.push(...files(path))
+    else out.push(path)
+  }
+  return out
+}
+
+function rel(root: string, path: string): string {
+  return relative(root, path).split(sep).join('/')
+}
+
+function globToRegExp(glob: string): RegExp {
+  const pattern = glob.replace(/\\/g, '/').replace(/^\.\//, '')
+  let out = ''
+  for (const ch of pattern) {
+    if (ch === '*') out += '[^]*'
+    else if (ch === '?') out += '.'
+    else out += ch.replace(/[.+^${}()|[\]\\]/g, '\\$&')
+  }
+  return new RegExp(`^(?:[^]*/)?${out}$`)
+}
+
+/** Refuses a folder holding a path the task marks as an answer key. */
+export function assertNoLeakPaths(root: string, globs: readonly string[] = []): void {
+  if (!globs.length || !existsSync(root)) return
+  const rx = globs.map(globToRegExp)
+  const hits = files(root).map((path) => rel(root, path)).filter((path) => rx.some((r) => r.test(path)))
+  if (hits.length) throw new Error(`answer-key path(s) would enter model context: ${hits.sort().slice(0, 8).join(', ')}`)
+}
+
+/** Refuses a folder containing a grader's output, by file name and by content. */
+export function assertNoGraderVerdicts(root: string, markers: readonly string[] = GRADER_VERDICT_MARKERS): void {
+  if (!existsSync(root)) return
+  for (const path of files(root)) {
+    const name = rel(root, path)
+    for (const marker of markers) {
+      if (name.includes(marker)) throw new Error(`grader verdict would enter model context: '${name}' matched marker '${marker}' in its NAME. Find the read path that produced it.`)
+    }
+    if (!SCANNED.has(extname(path).toLowerCase())) continue
+    let body: string
+    try {
+      body = readFileSync(path, 'utf8')
+    } catch {
+      continue
+    }
+    for (const marker of markers) {
+      const at = body.indexOf(marker)
+      if (at >= 0) throw new Error(`grader verdict would enter model context: '${name}' contains marker '${marker}' at offset ${at}. Find the read path that produced it.`)
+    }
+  }
+}
+
+/** The same tripwire on a tree, before it is rolled or stored. */
+export function assertTreeHasNoGraderVerdicts(tree: Record<string, string>, markers: readonly string[] = GRADER_VERDICT_MARKERS): void {
+  for (const [name, body] of Object.entries(tree).sort()) {
+    for (const marker of markers) {
+      if (name.includes(marker)) throw new Error(`harness file '${name}' has grader-verdict marker '${marker}' in its NAME; rename it`)
+      if (SCANNED.has(extname(name).toLowerCase()) && body.includes(marker)) throw new Error(`harness file '${name}' contains grader-verdict marker '${marker}'; remove that string -- files carrying it cannot be served as evidence to later tasks`)
+    }
+  }
+}
+
+function copyFolder(src: string, dst: string): number {
+  let n = 0
+  for (const path of files(src)) {
+    if (path.includes(`${sep}__pycache__${sep}`) || path.endsWith('.pyc')) continue
+    const target = join(dst, relative(src, path))
+    mkdirSync(dirname(target), { recursive: true })
+    copyFileSync(path, target)
+    n++
+  }
+  return n
+}
+
+/** Copies the task's source material under `root/source`, minus answer-key paths. */
+export function copySource(task: RefineTask, root: string): number {
+  const src = task.sourceDir
+  if (!src || !existsSync(src)) return 0
+  const leak = (task.leakGlobs ?? []).map(globToRegExp)
+  let n = 0
+  for (const path of files(src)) {
+    const name = rel(src, path)
+    if (name.split('/').includes('__pycache__') || leak.some((r) => r.test(name))) continue
+    const target = join(root, 'source', name)
+    mkdirSync(dirname(target), { recursive: true })
+    copyFileSync(path, target)
+    n++
+  }
+  if (n) assertNoLeakPaths(join(root, 'source'), task.leakGlobs)
+  return n
+}
+
+/** A line-based unified diff, enough for a reader to see what changed. */
+export function unifiedDiff(before: Tree, after: Tree, fromLabel: string, toLabel: string): string {
+  const out: string[] = []
+  for (const name of [...new Set([...Object.keys(before), ...Object.keys(after)])].sort()) {
+    const a = before[name] ?? ''
+    const b = after[name] ?? ''
+    if (a === b) continue
+    out.push(`--- ${fromLabel}/${name}`, `+++ ${toLabel}/${name}`)
+    const x = a ? a.split('\n') : []
+    const y = b ? b.split('\n') : []
+    // A longest-common-subsequence walk; trees are small enough for the quadratic table.
+    const dp: number[][] = Array.from({ length: x.length + 1 }, () => new Array<number>(y.length + 1).fill(0))
+    for (let i = x.length - 1; i >= 0; i--) for (let j = y.length - 1; j >= 0; j--) dp[i]![j] = x[i] === y[j] ? dp[i + 1]![j + 1]! + 1 : Math.max(dp[i + 1]![j]!, dp[i]![j + 1]!)
+    let i = 0
+    let j = 0
+    while (i < x.length || j < y.length) {
+      if (i < x.length && j < y.length && x[i] === y[j]) {
+        out.push(` ${x[i]}`)
+        i++
+        j++
+      } else if (j < y.length && (i >= x.length || dp[i]![j + 1]! >= dp[i + 1]![j]!)) {
+        out.push(`+${y[j]}`)
+        j++
+      } else {
+        out.push(`-${x[i]}`)
+        i++
+      }
+    }
+  }
+  return out.length ? `${out.join('\n')}\n` : ''
+}
+
+export interface PoolEntry {
+  label: string
+  /** The candidate's harness folder, or null. */
+  harnessDir: string | null
+  rollout: Rollout | null
+}
+
+export interface EvidenceTree {
+  root: string
+  taskId: string
+  rollouts: string[]
+  deliverables: string[]
+  harnessFiles: number
+  library: boolean
+  pool: string[]
+  failed: string[]
+  sourceFiles: number
+  decisions: number
+}
+
+/** The evidence-layout listing that goes in a mission; it mentions only what exists. */
+export function layout(tree: EvidenceTree): string {
+  const lines = ['context/task.md                  the task as the agent received it']
+  if (tree.sourceFiles) lines.push('context/source/                 task source materials')
+  if (tree.decisions) lines.push('context/decisions/              earlier edits and composition decisions')
+  if (tree.rollouts.length) {
+    const names = tree.rollouts.slice(0, 6).map((label) => `${label}.md`).join(', ')
+    const more = tree.rollouts.length > 6 ? ` (+${tree.rollouts.length - 6} more)` : ''
+    lines.push(`context/rollouts/               FULL trajectories: ${names}${more}`)
+  }
+  if (tree.deliverables.length) lines.push('context/deliverables/<label>/    the files each rollout produced, one per artifact (browse INDEX.md for the set)')
+  if (tree.harnessFiles) lines.push(`context/harness/                the harness you are editing (${tree.harnessFiles} files)`)
+  if (tree.pool.length) lines.push(`context/pool/                   ${tree.pool.length} candidates, each with its harness and its rollout`)
+  if (tree.library) lines.push('context/library/                earlier tasks in this area -- browse INDEX.md first, then open what looks relevant')
+  return lines.join('\n')
+}
+
+export interface BuildInput {
+  task: RefineTask
+  executor: Executor
+  rollouts?: readonly Rollout[]
+  harnessDir?: string | null
+  libraryDir?: string | null
+  pool?: readonly PoolEntry[]
+  decisions?: Record<string, string>
+  obsTrunc?: number
+}
+
+function writeRollout(dest: string, rollout: Rollout, executor: Executor, obsTrunc: number): string {
+  let failure = ''
+  mkdirSync(join(dest, 'rollouts'), { recursive: true })
+  try {
+    writeFileSync(join(dest, 'rollouts', `${rollout.label}.md`), executor.trajectory(rollout, { obsTrunc }))
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    writeFileSync(join(dest, 'rollouts', `${rollout.label}.md`), `(trajectory unavailable: ${message})`)
+    failure = `${rollout.label}: ${message}`
+  }
+  const dir = join(dest, 'deliverables', rollout.label)
+  mkdirSync(dir, { recursive: true })
+  let produced: Record<string, string> = {}
+  try {
+    produced = executor.deliverableFiles(rollout)
+  } catch (error) {
+    produced = { 'unavailable.md': `(deliverable unavailable: ${error instanceof Error ? error.message : String(error)})` }
+  }
+  const names = Object.keys(produced).sort()
+  for (const name of names) {
+    const target = join(dir, name)
+    mkdirSync(dirname(target), { recursive: true })
+    writeFileSync(target, produced[name]!)
+  }
+  writeFileSync(join(dir, 'INDEX.md'), names.length ? `# ${rollout.label} produced ${names.length} file(s)\n\n${names.map((name) => `- \`${name}\``).join('\n')}\n` : `# ${rollout.label} produced nothing\n`)
+  return failure
+}
+
+function renderDeliverable(executor: Executor, rollout: Rollout): string {
+  const produced = executor.deliverableFiles(rollout)
+  const names = Object.keys(produced).sort()
+  if (!names.length) return ''
+  if (names.length === 1) return produced[names[0]!]!
+  return names.map((name) => `## ${name}\n\n${produced[name]}`).join('\n\n')
+}
+
+export { renderDeliverable }
+
+/**
+ * Writes the evidence folder and returns what landed, so a mission describes only that. A
+ * trajectory is written in full; `obsTrunc` applies per observation.
+ */
+export function build(dest: string, input: BuildInput): EvidenceTree {
+  const { task, executor } = input
+  rmSync(dest, { recursive: true, force: true })
+  mkdirSync(dest, { recursive: true })
+  const obsTrunc = Math.max(input.obsTrunc ?? 50_000, MIN_OBS_TRUNC)
+
+  writeFileSync(join(dest, 'task.md'), task.prompt)
+  const sourceFiles = copySource(task, dest)
+  for (const [label, notes] of Object.entries(input.decisions ?? {})) {
+    mkdirSync(join(dest, 'decisions'), { recursive: true })
+    writeFileSync(join(dest, 'decisions', `${label}.md`), notes || 'No decision notes returned.')
+  }
+
+  const rollouts: string[] = []
+  const deliverables: string[] = []
+  const failed: string[] = []
+  for (const rollout of input.rollouts ?? []) {
+    const failure = writeRollout(dest, rollout, executor, obsTrunc)
+    if (failure) failed.push(failure)
+    else rollouts.push(rollout.label)
+    deliverables.push(rollout.label)
+  }
+
+  let harnessFiles = 0
+  if (input.harnessDir && existsSync(input.harnessDir)) {
+    assertNoLeakPaths(input.harnessDir, task.leakGlobs)
+    harnessFiles = copyFolder(input.harnessDir, join(dest, 'harness'))
+  }
+
+  const pool: string[] = []
+  for (const entry of input.pool ?? []) {
+    const dir = join(dest, 'pool', entry.label)
+    mkdirSync(dir, { recursive: true })
+    if (entry.harnessDir && existsSync(entry.harnessDir)) {
+      assertNoLeakPaths(entry.harnessDir, task.leakGlobs)
+      copyFolder(entry.harnessDir, join(dir, 'harness'))
+      const reference = readTree(PI_SURFACE, join(dest, 'harness'))
+      const candidate = readTree(PI_SURFACE, entry.harnessDir)
+      writeFileSync(join(dir, 'harness.diff'), unifiedDiff(reference, candidate, 'current', entry.label))
+    }
+    if (entry.rollout) {
+      try {
+        writeFileSync(join(dir, 'rollout.md'), executor.trajectory(entry.rollout, { obsTrunc }))
+        writeFileSync(join(dir, 'produced.md'), renderDeliverable(executor, entry.rollout) || '(nothing produced)')
+      } catch (error) {
+        writeFileSync(join(dir, 'rollout.md'), `(unavailable: ${error instanceof Error ? error.message : String(error)})`)
+      }
+    }
+    pool.push(entry.label)
+  }
+
+  let library = false
+  if (input.libraryDir && existsSync(input.libraryDir) && readdirSync(input.libraryDir).length) {
+    assertNoLeakPaths(input.libraryDir, task.leakGlobs)
+    cpSync(input.libraryDir, join(dest, 'library'), { recursive: true })
+    library = true
+  }
+
+  assertNoLeakPaths(dest, task.leakGlobs)
+  assertNoGraderVerdicts(dest)
+  if ((input.rollouts ?? []).length && !rollouts.length) {
+    throw new Error(`no trajectory could be rendered for ANY rollout -- the improver would be adapting on nothing: ${failed.slice(0, 4).join('; ')}`)
+  }
+  return { root: dest, taskId: task.id, rollouts, deliverables, harnessFiles, library, pool, failed, sourceFiles, decisions: Object.keys(input.decisions ?? {}).length }
+}
+
+/** The short pointer to the evidence on disk: the job, where the evidence is, and the instruction to open it. */
+export function mission(tree: EvidenceTree, job: string): string {
+  return [
+    job.trim(),
+    '',
+    '# YOUR EVIDENCE',
+    '',
+    'It is on disk, in `context/`. Read it -- do not answer from this message alone.',
+    '',
+    layout(tree),
+    '',
+    'Every trajectory EVENT is present: the trajectory was not clipped to fit this mission. An individual observation may contain an explicit renderer-truncation marker; that marker is ours, not behavior by the solver. Do not diagnose it as a solver failure.',
+    '',
+    'Read `task.md` and the current harness first. Inventory every available rollout or candidate and inspect each at least once before deciding. For a candidate, compare what changed from its editing baseline, what behavior changed in its rollout, what improved, and what regressed or remained unresolved. Then deep-read the evidence relevant to any edit. Cite the specific trajectory moment behind every change; one you cannot trace to a moment is speculation.'
+  ].join('\n')
+}