driftproof 0.8.0 → 0.9.0

package/lib/provider.js

@@ -4,9 +4,12 @@
 const fs = require('fs');
 const os = require('os');
 const path = require('path');
-const { spawn } = require('child_process');
+// Called through the module object (cp.spawn), never destructured: the gate
+// records spawns by replacing that property, so nothing real runs offline.
+const cp = require('child_process');
 const { withRetry, withTimeout } = require('./json');
 const { stubComplete, stubEnabled } = require('./stub');
+const { readAnthropicApiResponse, readOpenaiApiResponse } = require('./usage');
 const {
   parseClaudeCliJson, parseCodexJsonl, parseAnthropicApiUsage, parseOpenaiApiUsage, normalizeUsage,
 } = require('./usage');
@@ -126,15 +129,23 @@ const CODEX_OVERHEAD_NOTE =
 //
 // `temperature` is honoured ONLY on api surfaces; cli surfaces control sampling
 // themselves, so temperature is ignored there and the receipt records that fact.
-async function complete({ system, prompt, model, maxTokens = 1024, timeoutMs = null, temperature = undefined }) {
+// `trusted` (spec 022) selects the SAME-USER legacy spawn on the two CLI lanes.
+// It is false unless a caller says otherwise; bin/driftproof exposes it as
+// --trusted-skill, for skills the operator authored. Api lanes ignore it.
+async function complete({ system, prompt, model, maxTokens = 1024, timeoutMs = null, temperature = undefined, trusted = false }) {
   const surface = surfaceForModel(model);
   const provider = providerForSurface(surface);
-  // Offline stub surface: canned completion, zero model calls. The receipt still
-  // records the real surface/provider so a stub run is not mistaken for a genuine
-  // one at read time — only the generation/judge TEXT is canned.
+  // Offline stub surface: canned completion, zero model calls. The reply says
+  // so: surface `stub`, answeredBy `stub`, no model reported, no stop reason,
+  // no isolation (nothing was spawned). Spec 026 F1: the receipt used to record
+  // the REAL surface name here and read TESTED while the text was canned; now
+  // the receipt's surface, level and answered_by are derived from what this
+  // function returned, and a stub run reads UNVERIFIED with surface stub. The
+  // requested model's provider is still reported, so a reader knows what was
+  // asked for.
   if (stubEnabled()) {
     const s = stubComplete({ system, prompt });
-    return { ...s, usage: normalizeUsage(s.usage), wall_ms: (s.usage && s.usage.wall_ms) || 0, surface, provider, attempts: 1 };
+    return { ...s, usage: normalizeUsage(s.usage), wall_ms: (s.usage && s.usage.wall_ms) || 0, surface: 'stub', provider, attempts: 1, answeredBy: 'stub', reportedModels: null, stopReason: null, isolation: 'none' };
   }
 
   // Per-surface tolerance (see retryPolicyForSurface): a cli/subscription surface
@@ -149,9 +160,9 @@ async function complete({ system, prompt, model, maxTokens = 1024, timeoutMs = n
   const laneRunner = () => {
     switch (surface) {
       case 'api': return completeAnthropicApi({ system, prompt, model, maxTokens, temperature });
-      case 'claude-cli': return completeClaudeCli({ system, prompt, model, timeoutMs: effTimeout });
+      case 'claude-cli': return completeClaudeCli({ system, prompt, model, timeoutMs: effTimeout, trusted });
       case 'openai-api': return completeOpenaiApi({ system, prompt, model, maxTokens, temperature, timeoutMs: effTimeout });
-      case 'openai-cli': return completeCodexCli({ system, prompt, model, timeoutMs: effTimeout });
+      case 'openai-cli': return completeCodexCli({ system, prompt, model, timeoutMs: effTimeout, trusted });
       default: throw new Error(`unknown surface: ${surface}`);
     }
   };
@@ -172,7 +183,16 @@ async function complete({ system, prompt, model, maxTokens = 1024, timeoutMs = n
   try {
     const out = await withRetry(runner, { tries: policy.tries, baseDelayMs });
     const usage = normalizeUsage({ ...(out.usage || {}), wall_ms: wallMs });
-    return { ...out, usage, wall_ms: wallMs, surface, provider, attempts };
+    // v0.6 (spec 026 AC-1, AC-2, AC-8): a model surface answered; what it said
+    // served the call, why the reply stopped, and which spawn path was taken
+    // are what the lane could read, null where its surface reports nothing.
+    return {
+      ...out, usage, wall_ms: wallMs, surface, provider, attempts,
+      answeredBy: 'model',
+      reportedModels: Array.isArray(out.reportedModels) && out.reportedModels.length ? out.reportedModels : null,
+      stopReason: typeof out.stopReason === 'string' && out.stopReason ? out.stopReason : null,
+      isolation: out.isolation || 'none',
+    };
   } catch (e) {
     // Surface the attempt count so a persistently-failing call can be charged for
     // (and, for a timeout, marked failed_timeout by the runner instead of fatal).
@@ -197,50 +217,191 @@ async function completeAnthropicApi({ system, prompt, model, maxTokens, temperat
   if (temperature !== undefined) params.temperature = temperature;
   const resp = await client.messages.create(params);
   const text = (resp.content || []).filter((b) => b.type === 'text').map((b) => b.text).join('');
-  return { text, usage: parseAnthropicApiUsage(resp.usage) };
+  // v0.6: the response names the model that served it and why it stopped.
+  return { text, usage: parseAnthropicApiUsage(resp.usage), ...readAnthropicApiResponse(resp), isolation: 'none' };
 }
 
-// ── anthropic/cli (claude -p) ──────────────────────────────────────────────────
-function completeClaudeCli({ system, prompt, model, timeoutMs }) {
-  return new Promise((resolve, reject) => {
-    // Strip ANTHROPIC_API_KEY so the CLI uses the subscription session, not the
-    // metered API key. Everything else in the env is preserved.
+// ── isolation: the eval-user hop (spec 022) ───────────────────────────────────
+//
+// Every local-CLI spawn runs as a DEDICATED UNPRIVILEGED UNIX USER by default.
+// The third-party SKILL.md a run evaluates is instructions to an agent with
+// tools, and until spec 022 that agent ran as the operator: same uid, whole
+// environment block, operator's cwd, operator's CLI configuration. The
+// 2026-09-03 security audit (findings A2, N5) confirmed a live API token in the
+// inherited environment and this host's SSH keys and CLI session tokens
+// readable by the same uid; this was then reproduced by execution.
+//
+// The boundary is a uid change reached through sudo from an EMPTY environment:
+//
+//   /usr/bin/sudo -n -u <eval-user> /usr/bin/env -i HOME=/home/<eval-user>
+//     PATH=/home/<eval-user>/.local/bin:/usr/bin:/bin bash -lc '<wrapper>'
+//     driftproof-eval-hop <cli> <cli-args...>
+//
+// Operator prerequisite, NOT created here (RUNBOOK.md): the user exists with a
+// mode-700 home and no extra groups, has its own logged-in `claude` and `codex`
+// under ~/.local/bin, and a sudoers rule grants the operator NOPASSWD as that
+// user. The runner refuses loudly when any of that is missing; it never creates
+// a user, edits sudoers, or logs a CLI in.
+//
+// The same-user (legacy) spawn survives ONLY behind `trusted: true`, exposed by
+// bin/driftproof as --trusted-skill, for skills the operator authored.
+const SUDO_BIN = '/usr/bin/sudo';
+const ENV_BIN = '/usr/bin/env';
+const EVAL_USER_DEFAULT = 'driftproof-eval';
+// A user name that can safely follow `sudo -u`: no leading dash, no shell
+// metacharacter, no path separator. Anything else is refused before any spawn.
+const EVAL_USER_RE = /^[a-z_][a-z0-9_-]{0,31}$/;
+// The ONLY names the child environment carries, each CONSTRUCTED from the eval
+// user's name in isolatedEnv() and never copied from process.env. Verified
+// 2026-09-03: both CLIs run through the hop with these two alone; the login
+// shell supplies LANG and TERM itself. Data, frozen, asserted by the gate.
+const ISOLATED_ENV_ALLOWLIST = Object.freeze(['HOME', 'PATH']);
+// $0 of the wrapper, so `ps` shows what the bash process is.
+const HOP_LABEL = 'driftproof-eval-hop';
+// The wrapper runs INSIDE the hop, as the eval user. It takes the CLI as
+// positional parameters ("$@"), so no SKILL.md text is ever shell-interpreted.
+//   - the cwd is a fresh per-call directory under the system tmp, created by
+//     the eval user (one the parent creates is mode 700 to it);
+//   - the CLI runs under setsid in its own process group, stdin preserved
+//     (`<&0` defeats the /dev/null a non-interactive bash gives a background job);
+//   - TERM/INT/HUP, which sudo relays from the parent on timeout, kill that
+//     whole group, remove the directory and exit 143;
+//   - a normal exit removes the directory and returns the CLI's status.
+const ISOLATED_WRAPPER = [
+  'd=$(mktemp -d -t driftproof-eval.XXXXXXXX) || exit 97',
+  'cd "$d" || exit 97',
+  'setsid -w "$@" <&0 & pid=$!',
+  'trap \'kill -TERM -- "-$pid" 2>/dev/null; sleep 1; kill -KILL -- "-$pid" 2>/dev/null; cd /; rm -rf "$d"; exit 143\' TERM INT HUP',
+  'wait "$pid"; r=$?',
+  'cd /; rm -rf "$d"; exit $r',
+].join('; ');
+
+// DRIFTPROOF_EVAL_USER selects WHICH user isolates, never WHETHER isolation
+// happens (that is the trusted flag, an argv decision). Empty means default.
+function evalUser() {
+  const raw = process.env.DRIFTPROOF_EVAL_USER;
+  const u = raw === undefined || raw === '' ? EVAL_USER_DEFAULT : raw;
+  if (!EVAL_USER_RE.test(u)) throw new Error(`DRIFTPROOF_EVAL_USER is not a plausible unix user name: ${JSON.stringify(u)}`);
+  return u;
+}
+
+// The child environment: constructed, not copied. Keys are exactly the allowlist.
+function isolatedEnv(user) {
+  const home = `/home/${user}`;
+  return { HOME: home, PATH: `${home}/.local/bin:/usr/bin:/bin` };
+}
+
+// The isolation a plan records into the receipt (run.answered_by.isolation,
+// spec 026 AC-2): the hop is `eval-user`, the legacy spawn `same-user`.
+function isolationOf(plan) { return plan && plan.mode === 'isolated' ? 'eval-user' : 'same-user'; }
+
+// The spawn plan for one CLI call: { mode, user, file, args, env }. Pure, so the
+// gate can inspect what WOULD be spawned. Untrusted → the hop; trusted → the
+// legacy same-user spawn exactly as it was (env inherited; the claude lane still
+// strips ANTHROPIC_API_KEY so the CLI uses the subscription, not the metered key).
+function buildSpawnPlan({ bin, args, trusted = false }) {
+  if (trusted) {
     const env = { ...process.env };
-    delete env.ANTHROPIC_API_KEY;
-
-    // v0.4: `--output-format json` returns ONE JSON object carrying both the
-    // final text (`result`) and the token usage (`usage`) — the default text
-    // output carries no usage at all, which is why usage was previously null on
-    // this lane. The text is read from the parsed object; if the CLI ever emits
-    // something unparseable we fall back to the raw stdout so a run degrades to
-    // the old behaviour (text, no usage) rather than failing.
-    const args = ['-p', '--output-format', 'json', '--model', resolveModel(model)];
-    if (system) args.push('--append-system-prompt', system);
-
-    const child = spawn('claude', args, { env, stdio: ['pipe', 'pipe', 'pipe'] });
-    let out = '';
-    let err = '';
-    const killer = setTimeout(() => { child.kill('SIGKILL'); }, timeoutMs + 5000);
-    child.stdout.on('data', (d) => { out += d; });
-    child.stderr.on('data', (d) => { err += d; });
-    child.on('error', (e) => {
-      clearTimeout(killer);
-      if (e.code === 'ENOENT') reject(new Error("the anthropic/cli surface requires the `claude` CLI on PATH. Install it or set CLAUDE_PROVIDER=api."));
-      else reject(e);
-    });
-    child.on('close', (code) => {
-      clearTimeout(killer);
-      if (code !== 0) return reject(new Error(`claude CLI exited ${code}: ${err.slice(0, 400)}`));
-      const parsed = parseClaudeCliJson(out);
-      if (!parsed) return resolve({ text: out.trim(), usage: null });
-      if (parsed.isError) return reject(new Error(`claude CLI reported is_error: ${String(parsed.text || '').slice(0, 300)}`));
-      resolve({ text: String(parsed.text || '').trim(), usage: parsed.usage });
-    });
-    child.stdin.write(prompt);
+    if (bin === 'claude') delete env.ANTHROPIC_API_KEY;
+    return { mode: 'same-user', user: null, file: bin, args: [...args], env };
+  }
+  const user = evalUser();
+  const childEnv = isolatedEnv(user);
+  return {
+    mode: 'isolated',
+    user,
+    file: SUDO_BIN,
+    args: ['-n', '-u', user, ENV_BIN, '-i', ...ISOLATED_ENV_ALLOWLIST.map((k) => `${k}=${childEnv[k]}`), 'bash', '-lc', ISOLATED_WRAPPER, HOP_LABEL, bin, ...args],
+    // The sudo front process gets NOTHING from this process. sudo resolves
+    // /usr/bin/env itself; env -i then starts the child from empty.
+    env: {},
+  };
+}
+
+// Run a plan: `input` to stdin, stdout/stderr collected, settled on close.
+// The timeout signal differs by mode. The legacy child gets SIGKILL as it
+// always did. The hop gets SIGTERM: it is the signal the operator's uid can
+// deliver to a root-owned sudo, and the one sudo relays to the wrapper's trap.
+// SIGKILL would neither be permitted nor relayed, and a wrapper without the
+// trap left the CLI orphaned with the stdout pipe open, so close never fired.
+function runPlan(plan, { input = null, timeoutMs = 300000, graceMs = 5000 } = {}) {
+  return new Promise((resolve, reject) => {
+    let child;
+    try { child = cp.spawn(plan.file, plan.args, { env: plan.env, stdio: ['pipe', 'pipe', 'pipe'] }); }
+    catch (e) { return reject(e); }
+    let stdout = '';
+    let stderr = '';
+    let timedOut = false;
+    const killer = setTimeout(() => {
+      timedOut = true;
+      child.kill(plan.mode === 'isolated' ? 'SIGTERM' : 'SIGKILL');
+    }, timeoutMs + graceMs);
+    child.stdout.on('data', (d) => { stdout += d; });
+    child.stderr.on('data', (d) => { stderr += d; });
+    child.on('error', (e) => { clearTimeout(killer); reject(e); });
+    child.on('close', (code, signal) => { clearTimeout(killer); resolve({ code, signal, stdout, stderr, timedOut }); });
+    child.stdin.on('error', () => { /* EPIPE if the CLI exits before reading all of stdin */ });
+    if (input != null) child.stdin.write(input);
     child.stdin.end();
   });
 }
 
+// The hop with an arbitrary command in place of the CLI, for the gate: the same
+// plan builder and the same runner, never trusted. No provider is reached.
+function runIsolated(cmdArgv, opts = {}) {
+  const [bin, ...args] = cmdArgv;
+  return runPlan(buildSpawnPlan({ bin, args, trusted: false }), { graceMs: 0, ...opts });
+}
+
+// A hop failure, said in terms of what to fix. Returns null when the failure is
+// the CLI's own (exit status from inside the hop), which the lane reports as before.
+function hopFailure(bin, r) {
+  const err = String(r.stderr || '').trim();
+  if (r.code === 127) {
+    return `the \`${bin}\` CLI is not on the eval user's PATH inside the isolated hop (${err.slice(0, 200)}). `
+      + 'Install and log it in as that user (RUNBOOK.md), or pass --trusted-skill for a skill you authored.';
+  }
+  const sudoLine = err.split('\n').find((l) => /^sudo:/.test(l));
+  if (sudoLine) {
+    return `the isolated eval-user hop failed before reaching \`${bin}\`: ${sudoLine}. The eval user and its NOPASSWD sudoers `
+      + 'rule are an operator prerequisite (RUNBOOK.md); pass --trusted-skill only for a skill you authored.';
+  }
+  return null;
+}
+
+// ── anthropic/cli (claude -p) ──────────────────────────────────────────────────
+async function completeClaudeCli({ system, prompt, model, timeoutMs, trusted = false }) {
+  // v0.4: `--output-format json` returns ONE JSON object carrying both the
+  // final text (`result`) and the token usage (`usage`) — the default text
+  // output carries no usage at all, which is why usage was previously null on
+  // this lane. The text is read from the parsed object; if the CLI ever emits
+  // something unparseable we fall back to the raw stdout so a run degrades to
+  // the old behaviour (text, no usage) rather than failing.
+  const args = ['-p', '--output-format', 'json', '--model', resolveModel(model)];
+  if (system) args.push('--append-system-prompt', system);
+  const plan = buildSpawnPlan({ bin: 'claude', args, trusted });
+  let r;
+  try {
+    r = await runPlan(plan, { input: prompt, timeoutMs });
+  } catch (e) {
+    if (e.code === 'ENOENT') {
+      throw new Error(plan.mode === 'isolated'
+        ? `the isolated hop requires ${SUDO_BIN}`
+        : "the anthropic/cli surface requires the `claude` CLI on PATH. Install it or set CLAUDE_PROVIDER=api.");
+    }
+    throw e;
+  }
+  if (r.code !== 0) {
+    const hop = plan.mode === 'isolated' ? hopFailure('claude', r) : null;
+    throw new Error(hop || `claude CLI exited ${r.code}: ${r.stderr.slice(0, 400)}`);
+  }
+  const parsed = parseClaudeCliJson(r.stdout);
+  if (!parsed) return { text: r.stdout.trim(), usage: null, stopReason: null, reportedModels: null, isolation: isolationOf(plan) };
+  if (parsed.isError) throw new Error(`claude CLI reported is_error: ${String(parsed.text || '').slice(0, 300)}`);
+  // v0.6: the CLI's own stop_reason and the modelUsage map's canonical ids.
+  return { text: String(parsed.text || '').trim(), usage: parsed.usage, stopReason: parsed.stopReason, reportedModels: parsed.reportedModels, isolation: isolationOf(plan) };
+}
+
 // ── openai/api (Chat Completions-compatible) ───────────────────────────────────
 // Generic OpenAI-compatible client using global fetch (Node ≥ 18). The base_url
 // is configurable — env OPENAI_BASE_URL wins, else the registry's provider
@@ -278,7 +439,8 @@ async function completeOpenaiApi({ system, prompt, model, maxTokens, temperature
   let parsed;
   try { parsed = JSON.parse(raw); } catch (_e) { throw new Error(`openai/api: unparseable response: ${raw.slice(0, 200)}`); }
   const text = ((parsed.choices && parsed.choices[0] && parsed.choices[0].message && parsed.choices[0].message.content) || '');
-  return { text: String(text).trim(), usage: parseOpenaiApiUsage(parsed.usage) };
+  // v0.6: the response's model and the first choice's finish_reason.
+  return { text: String(text).trim(), usage: parseOpenaiApiUsage(parsed.usage), ...readOpenaiApiResponse(parsed), isolation: 'none' };
 }
 
 // Read the OpenAI provider config (base_url + api-key env) from the registry,
@@ -294,7 +456,7 @@ function openaiProviderConfig() {
 
 // ── openai/cli (codex exec — ChatGPT subscription) ─────────────────────────────
 // Invocation template (from the verified recon, reference_codex_cli):
-//   codex exec --json -s read-only --skip-git-repo-check --ephemeral -o <tmp> [-m <model>] "PROMPT"
+//   codex exec --json -s read-only --skip-git-repo-check --ephemeral [-m <model>] -
 // Honoured facts:
 //   - `-a/--ask-for-approval` is INVALID on `codex exec` — it is NEVER passed;
 //     exec already defaults to approval_policy "never".
@@ -305,6 +467,12 @@ function openaiProviderConfig() {
 //   - `codex exec` has no system-prompt flag, so a system prompt (the SKILL.md in
 //     with_skill mode) is folded into the prompt text.
 //   - stderr emits a harmless "Reading additional input from stdin…" notice.
+//   - `-o/--output-last-message` is NEVER passed (spec 022 AC-9, approval F-1).
+//     The final message is taken from the `--json` stream on the stdout pipe
+//     this process owns. A `-o` path is a file the child writes and the parent
+//     reads back; isolated, the child is the eval user running third-party
+//     instructions, and a symlink planted at that path would have made this
+//     process read an operator-owned file into the generation.
 const CODEX_EXEC_ARGS = ['exec', '--json', '-s', 'read-only', '--skip-git-repo-check', '--ephemeral'];
 
 function codexAuthPresent(homeDir) {
@@ -315,9 +483,9 @@ function codexAuthPresent(homeDir) {
 }
 
 // Build the exact argv for a codex exec call. Exposed for the gate to assert the
-// template (and that `-a` never appears). `outFile` receives the final message.
-function buildCodexArgs({ model, outFile }) {
-  const args = [...CODEX_EXEC_ARGS, '-o', outFile];
+// template (that `-a` never appears, and neither does `-o`).
+function buildCodexArgs({ model } = {}) {
+  const args = [...CODEX_EXEC_ARGS];
   if (model) args.push('-m', resolveModel(model));
   return args;
 }
@@ -326,66 +494,60 @@ function buildCodexArgs({ model, outFile }) {
 // means "read the prompt from stdin". The prompt is NEVER a positional argv —
 // real SKILL.md files start with `---` (YAML frontmatter) and codex rejects a
 // positional beginning with `--`. Exposed so the gate can lock this in.
-function codexFinalArgs({ model, outFile }) {
-  return [...buildCodexArgs({ model, outFile }), '-'];
+function codexFinalArgs({ model } = {}) {
+  return [...buildCodexArgs({ model }), '-'];
 }
 
-function completeCodexCli({ system, prompt, model, timeoutMs }) {
-  return new Promise((resolve, reject) => {
-    if (!codexAuthPresent()) {
-      return reject(new Error('the openai/cli surface requires codex auth (~/.codex/auth.json). Run `codex login` (or `codex login --device-auth` on a headless box).'));
+async function completeCodexCli({ system, prompt, model, timeoutMs, trusted = false }) {
+  // The auth presence check is a PARENT-side read of ~/.codex/auth.json, which
+  // only means something on the same-user path; the eval user's home is not
+  // readable from here, and a missing login there surfaces as codex's own error.
+  if (trusted && !codexAuthPresent()) {
+    throw new Error('the openai/cli surface requires codex auth (~/.codex/auth.json). Run `codex login` (or `codex login --device-auth` on a headless box).');
+  }
+  // codex exec has no system-prompt flag → fold the system prompt into the
+  // prompt text (this is how the SKILL.md reaches the model in with_skill mode).
+  const fullPrompt = system ? `${system}\n\n---\n\n${prompt}` : prompt;
+  // The prompt is delivered on STDIN, not as a positional argv: real SKILL.md
+  // files begin with `---` (YAML frontmatter), and a positional argument that
+  // starts with `--` is rejected by codex's arg parser ("unexpected argument
+  // '---'"). `-` as the positional tells `codex exec` to read instructions from
+  // stdin (per its --help), which is content-agnostic.
+  const plan = buildSpawnPlan({ bin: 'codex', args: codexFinalArgs({ model }), trusted });
+  // stdout is CAPTURED. `--json` streams JSONL events there: the last
+  // `item.completed`/`agent_message` carries the final text and the terminal
+  // `turn.completed` event carries this call's token usage — the only place
+  // codex reports it. Nothing is read from the filesystem after the call, on
+  // either mode: the stdout pipe is the one channel only the child we spawned
+  // can write to, and the eval user cannot make this process read a file
+  // through it (spec 022 AC-9).
+  let r;
+  try {
+    r = await runPlan(plan, { input: fullPrompt, timeoutMs });
+  } catch (e) {
+    if (e.code === 'ENOENT') {
+      throw new Error(plan.mode === 'isolated'
+        ? `the isolated hop requires ${SUDO_BIN}`
+        : 'the openai/cli surface requires the `codex` CLI on PATH (npm i -g @openai/codex).');
     }
-    // codex exec has no system-prompt flag → fold the system prompt into the
-    // prompt text (this is how the SKILL.md reaches the model in with_skill mode).
-    const fullPrompt = system ? `${system}\n\n---\n\n${prompt}` : prompt;
-    const outFile = path.join(os.tmpdir(), `driftproof-codex-${process.pid}-${Date.now()}-${Math.floor(codexCounter())}.txt`);
-    // The prompt is delivered on STDIN, not as a positional argv: real SKILL.md
-    // files begin with `---` (YAML frontmatter), and a positional argument that
-    // starts with `--` is rejected by codex's arg parser ("unexpected argument
-    // '---'"). `-` as the positional tells `codex exec` to read instructions from
-    // stdin (per its --help), which is content-agnostic.
-    const args = codexFinalArgs({ model, outFile });
-
-    // v0.4: stdout is CAPTURED (it was 'ignore'). `--json` streams JSONL events
-    // there, and the terminal `turn.completed` event carries this call's token
-    // usage — the only place codex reports it. The final message still comes from
-    // the -o file (cleaner than scraping the stream); the JSONL is read for usage.
-    const child = spawn('codex', args, { env: { ...process.env }, stdio: ['pipe', 'pipe', 'pipe'] });
-    let err = '';
-    let jsonl = '';
-    const killer = setTimeout(() => { child.kill('SIGKILL'); }, timeoutMs + 5000);
-    child.stdout.on('data', (d) => { jsonl += d; });
-    child.stderr.on('data', (d) => { err += d; });
-    child.on('error', (e) => {
-      clearTimeout(killer);
-      if (e.code === 'ENOENT') reject(new Error('the openai/cli surface requires the `codex` CLI on PATH (npm i -g @openai/codex).'));
-      else reject(e);
-    });
-    child.on('close', (code) => {
-      clearTimeout(killer);
-      let text = '';
-      try { text = fs.readFileSync(outFile, 'utf8'); } catch (_e) { /* fall through */ }
-      try { fs.unlinkSync(outFile); } catch (_e) { /* best effort */ }
-      if (code !== 0) return reject(new Error(`codex exec exited ${code}: ${String(err).slice(0, 400)}`));
-      const ev = parseCodexJsonl(jsonl);
-      // Prefer the -o file; fall back to the stream's agent_message if it is empty.
-      const finalText = String(text || ev.text || '').trim();
-      resolve({ text: finalText, usage: ev.usage });
-    });
-    child.stdin.on('error', () => { /* ignore EPIPE if codex exits before reading all input */ });
-    child.stdin.write(fullPrompt);
-    child.stdin.end();
-  });
+    throw e;
+  }
+  if (r.code !== 0) {
+    const hop = plan.mode === 'isolated' ? hopFailure('codex', r) : null;
+    throw new Error(hop || `codex exec exited ${r.code}: ${String(r.stderr).slice(0, 400)}`);
+  }
+  const ev = parseCodexJsonl(r.stdout);
+  // codex reports neither the serving model nor a stop reason on its stream;
+  // both read null and the receipt says the surface did not report them.
+  return { text: String(ev.text || '').trim(), usage: ev.usage, stopReason: ev.stopReason, reportedModels: ev.reportedModels, isolation: isolationOf(plan) };
 }
 
-// A monotonically-increasing counter for temp-file uniqueness that does not use
-// Math.random (kept deterministic-friendly for any harness that forbids it).
-let _codexCounter = 0;
-function codexCounter() { _codexCounter += 1; return _codexCounter; }
-
 module.exports = {
   complete, resolveModel, surfaceLabel, providerName, MODEL_ALIASES,
   inferProvider, surfaceForModel, providerForSurface,
   isMeteredSurface, isSubscriptionSurface, retryPolicyForSurface,
   CODEX_OVERHEAD_NOTE, CODEX_EXEC_ARGS, buildCodexArgs, codexFinalArgs, codexAuthPresent,
+  // spec 022 — the eval-user hop
+  SUDO_BIN, EVAL_USER_DEFAULT, ISOLATED_ENV_ALLOWLIST, ISOLATED_WRAPPER, HOP_LABEL,
+  evalUser, isolatedEnv, buildSpawnPlan, runIsolated, isolationOf,
 };

package/lib/receipt.js

@@ -20,9 +20,30 @@ const SCHEMA_FILES = {
   // published v0.4 receipt asserts conformance by NUMBER, and the number has to
   // keep resolving to the schema it meant (AC-10).
   '0.4': 'receipt.v0.4.schema.json',
-  '0.5': 'receipt.schema.json',
+  // v0.5 moved the same way when v0.6 took the current pointer (spec 026): the
+  // six report-008 receipts assert v0.5 by number, and v0.6 is not additive for
+  // the validator (it requires the receipt to say what answered it), so the
+  // number has to keep resolving to the schema it meant.
+  '0.5': 'receipt.v0.5.schema.json',
+  '0.6': 'receipt.schema.json',
 };
 
+// THE BAND RULE, stated on every receipt (results.aggregates.band_rule, spec
+// 026 AC-6) so a reader recomputes the summary from the rows by the formula
+// it names rather than by guessing which of the two "bands" a receipt carries.
+// Per case, stddev is the spread of judge samples; per arm, it is this.
+const BAND_RULE = 'per arm: the sample standard deviation (n-1) of the per-case means across the included cases; the comparison band is the quadrature sum of the two arms; null where an arm has fewer than two included cases';
+
+// THE ONE PREDICATE for "this case did not complete" (spec 026 AC-3). Every
+// reader in lib/ and scripts/ asks this, never the failed_timeout literal: a
+// reader that excluded by that literal admitted a failed_unmeasured case (an
+// empty generation, a judge with no score) into its statistics as if it had
+// been measured. A case is failed when its case_status is present and is not
+// 'ok'; the status names what was observed, and both failure statuses are
+// recorded without fabricated samples or hashes.
+const FAILED_STATUSES = ['failed_timeout', 'failed_unmeasured'];
+function caseFailed(c) { return !!(c && c.case_status && c.case_status !== 'ok'); }
+
 const _validators = {};
 // Lazily compile the JSON Schema validator (ajv) for a given version. Kept lazy
 // so the library can be required without ajv present (pure hashing utilities).
@@ -80,6 +101,27 @@ function aggregate(caseResults) {
   return { case_count: caseResults.length, pass_count: passes, borderline_count: borderline, mean_score: band.mean, stddev: band.stddev };
 }
 
+// The comparison block from the two arms' aggregates. Every null it carries is
+// named: `delta_uncertainty_unavailable` is `no_cases` when an arm has no
+// included case (then every score is null too: the mean of nothing is not a
+// number) and `single_case` when an arm has one (a mean, no band). Otherwise
+// the block is numeric and the field is absent (spec 026 AC-7).
+function comparisonOf(aggWith, aggBase) {
+  const noCases = aggWith.case_count === 0 || aggBase.case_count === 0;
+  const single = !noCases && (aggWith.case_count < 2 || aggBase.case_count < 2);
+  const cmp = {
+    with_skill_score: aggWith.mean_score,
+    baseline_score: aggBase.mean_score,
+    delta: noCases ? null : round(aggWith.mean_score - aggBase.mean_score),
+    // Combined uncertainty of the delta: quadrature sum of the two aggregate
+    // bands. Diff uses this for the headline "within noise" vs real-move rule.
+    delta_uncertainty: noCases ? null : combineUncertainty(aggWith.stddev, aggBase.stddev),
+  };
+  if (noCases) cmp.delta_uncertainty_unavailable = 'no_cases';
+  else if (single) cmp.delta_uncertainty_unavailable = 'single_case';
+  return cmp;
+}
+
 // Assemble a full receipt from the runner's raw pieces, seal it, and return it.
 //   skill:   { name, version, contentHash }
 //   suite:   { format, suiteHash, caseCount }
@@ -109,7 +151,7 @@ function buildReceipt({ skill, suite, run, cases, economics = null, verification
   // The excluded case STAYS in `results.cases`. It is removed from the mean, not
   // from the record — deleting the evidence of a failure is a different and worse
   // defect than averaging over it.
-  const armUnusable = (c) => c.case_status === 'failed_timeout'
+  const armUnusable = (c) => caseFailed(c)
     || (c.mean == null && c.score == null);
   const excludedIds = new Map();
   for (const c of cases) {
@@ -183,25 +225,23 @@ function buildReceipt({ skill, suite, run, cases, economics = null, verification
       registry: run.registry || 'unregistered',
       transcripts: run.transcripts || 'hashes-only',
       judge: run.judge || { samples: 1, temperature: null, sampling: 'single', surface: run.surface },
+      // v0.6 (spec 026 AC-1, AC-2): what answered. Carried from the caller as
+      // given and never defaulted: a receipt that does not say what answered it
+      // is refused by the schema, which is the point.
+      ...(run.answered_by ? { answered_by: run.answered_by } : {}),
     },
     results: {
       cases,
       aggregates: {
         with_skill: aggWith,
         baseline: aggBase,
+        band_rule: BAND_RULE,
         // Present only when something was excluded, so a clean run's receipt is
         // unchanged and the archive does not acquire an empty field.
         ...(excludedCases.length ? { excluded_cases: excludedCases } : {}),
       },
     },
-    comparison: {
-      with_skill_score: aggWith.mean_score,
-      baseline_score: aggBase.mean_score,
-      delta: round(aggWith.mean_score - aggBase.mean_score),
-      // Combined uncertainty of the delta: quadrature sum of the two aggregate
-      // bands. Diff uses this for the headline "within noise" vs real-move rule.
-      delta_uncertainty: combineUncertainty(aggWith.stddev, aggBase.stddev),
-    },
+    comparison: comparisonOf(aggWith, aggBase),
     verification_level: verificationLevel,
     receipt_hash: '',
   };
@@ -226,5 +266,5 @@ function buildReceipt({ skill, suite, run, cases, economics = null, verification
 }
 
 module.exports = {
-  buildReceipt, sealReceipt, computeReceiptHash, verifyReceiptHash, validateReceipt,
+  buildReceipt, sealReceipt, computeReceiptHash, verifyReceiptHash, validateReceipt, BAND_RULE, comparisonOf, caseFailed, FAILED_STATUSES,
 };