harness-everything 0.40.0 → 0.41.0

package/ci/lib/doc-reconciliation-prep-fixtures.js

@@ -25,9 +25,15 @@ const PILOT_SWITCH = 'HARNESS_DOC_RECONCILIATION_PILOT';
 const PILOT_REPORT_FILE = 'doc-reconciliation-pilot.json';
 const BASELINE_AUTHOR = Object.freeze({ name: 'doc-recon-replay', email: 'doc-recon-replay@invalid' });
 const BASELINE_DATE = '2026-01-01T00:00:00Z';
-const FIXTURE_OPS = new Set(['provideEvidence', 'mutateIdentity', 'timestampHints', 'seedState', 'gitCommit']);
+const FIXTURE_OPS = new Set(['provideEvidence', 'mutateIdentity', 'timestampHints', 'seedState', 'gitCommit', 'editJournal', 'editDocCheck', 'observeStateTree']);
 const CONTROLLER_OPS = new Set(['plan', 'start', 'binding', 'stageBinding', 'step', 'obligation']);
-const ALL_OPS = new Set(['route', 'stop', 'stopGeneric', ...CONTROLLER_OPS, ...FIXTURE_OPS]);
+// Host-transport ops (F4): hostRun executes a registered command the way the host would; hookDeliver sends one raw
+// host payload through the real hook entry (state-persist.js). Neither writes a journal or accepted record itself.
+const HOST_OPS = new Set(['hostRun', 'hookDeliver']);
+const ALL_OPS = new Set(['route', 'stop', 'stopGeneric', ...CONTROLLER_OPS, ...FIXTURE_OPS, ...HOST_OPS]);
+// CI-only qualification preloader. Passed as `node --require <file>` to every child of a replay that asks for it.
+const QUALIFICATION_PRELOAD = path.join(__dirname, 'doc-reconciliation-qualification-preload.js');
+const CAPTURE_JOURNAL_FILE = 'doc-reconciliation-capture.json';
 // The only session files a case may seed, and only inside its own temporary state home.
 const SEEDABLE_FILES = new Set(['workflow-stages.json']);
 
@@ -38,14 +44,18 @@ const DISTRIBUTIONS = Object.freeze({
     controller: path.join(REPO_ROOT, 'hooks', 'scripts', 'workflow-disposition.js'),
     stopGate: path.join(REPO_ROOT, 'hooks', 'scripts', 'workflow-stop-gate.js'),
     kernel: path.join(REPO_ROOT, 'harness-everything', 'scripts', 'kernel-router.js'),
-    genericStopGate: path.join(REPO_ROOT, 'hooks', 'scripts', 'stop-gate.js')
+    genericStopGate: path.join(REPO_ROOT, 'hooks', 'scripts', 'stop-gate.js'),
+    stateHook: path.join(REPO_ROOT, 'hooks', 'scripts', 'state-persist.js'),
+    docCheck: path.join(REPO_ROOT, 'harness-everything', 'scripts', 'doc-check.js')
   },
   packaged: {
     root: path.join(REPO_ROOT, 'plugins', 'harness-everything'),
     controller: path.join(REPO_ROOT, 'plugins', 'harness-everything', 'hooks', 'scripts', 'workflow-disposition.js'),
     stopGate: path.join(REPO_ROOT, 'plugins', 'harness-everything', 'hooks', 'scripts', 'workflow-stop-gate.js'),
     kernel: path.join(REPO_ROOT, 'plugins', 'harness-everything', 'skills', 'harness-everything', 'scripts', 'kernel-router.js'),
-    genericStopGate: path.join(REPO_ROOT, 'plugins', 'harness-everything', 'hooks', 'scripts', 'stop-gate.js')
+    genericStopGate: path.join(REPO_ROOT, 'plugins', 'harness-everything', 'hooks', 'scripts', 'stop-gate.js'),
+    stateHook: path.join(REPO_ROOT, 'plugins', 'harness-everything', 'hooks', 'scripts', 'state-persist.js'),
+    docCheck: path.join(REPO_ROOT, 'plugins', 'harness-everything', 'skills', 'harness-everything', 'scripts', 'doc-check.js')
   }
 });
 
@@ -94,13 +104,26 @@ function childEnv(workspace, stateHome, pilot) {
   return env;
 }
 
+// A distribution is a named one above, or an explicit set of entry paths (F4-T2: a test runs the real entries from its own
+// staged tree, with its own export). Either way every entry point is an absolute path.
+const DISTRIBUTION_KEYS = ['controller', 'stopGate', 'kernel', 'genericStopGate', 'stateHook', 'docCheck'];
+function resolveDistribution(distribution) {
+  if (typeof distribution === 'string') {
+    if (!DISTRIBUTIONS[distribution]) throw new Error(`unknown distribution ${distribution}`);
+    return DISTRIBUTIONS[distribution];
+  }
+  if (distribution && typeof distribution === 'object' && DISTRIBUTION_KEYS.every(key => typeof distribution[key] === 'string')) return distribution;
+  throw new Error('unknown distribution');
+}
+
 function createSession(distribution, caseId, pilot) {
-  if (!DISTRIBUTIONS[distribution]) throw new Error(`unknown distribution ${distribution}`);
+  const dist = resolveDistribution(distribution);
   const token = crypto.randomBytes(4).toString('hex');
   const workspace = fs.mkdtempSync(path.join(os.tmpdir(), `doc-recon-${caseId}-${distribution}-ws-${token}-`));
   const stateHome = fs.mkdtempSync(path.join(os.tmpdir(), `doc-recon-${caseId}-${distribution}-state-${token}-`));
   return {
-    distribution,
+    dist,
+    distribution: typeof distribution === 'string' ? distribution : 'custom',
     caseId,
     pilot,
     workspace,
@@ -114,8 +137,11 @@ function disposeSession(handle) {
   fs.rmSync(handle.stateHome, { recursive: true, force: true });
 }
 
+// The preloader is a test-driver argument only: a replay with `preload: true` adds it to every child it launches.
 function runScript(handle, script, args, stdin, pilot) {
-  return spawnSync(process.execPath, [script, ...args], {
+  const preload = handle.preload ? ['--require', QUALIFICATION_PRELOAD] : [];
+  // Test-only extra arguments (for example a file-access spy). They come before the preloader, so the spy sees everything.
+  return spawnSync(process.execPath, [...(handle.nodeArgs || []), ...preload, script, ...args], {
     cwd: handle.workspace,
     encoding: 'utf8',
     input: stdin === undefined ? undefined : JSON.stringify(stdin),
@@ -159,10 +185,13 @@ function readJsonOrNull(file) {
 function snapshot(handle) {
   const dir = sessionDirOf(handle);
   if (!dir) return { workflow: null, obligations: null, handoff: null };
+  // The capture journal is included only when a hook actually wrote it, so legacy replays keep their shape.
+  const capture = readJsonOrNull(path.join(dir, CAPTURE_JOURNAL_FILE));
   return {
     workflow: readJsonOrNull(path.join(dir, 'workflow-run.json')),
     obligations: readJsonOrNull(path.join(dir, 'workflow-obligations.json')),
-    handoff: readJsonOrNull(path.join(dir, 'handoff-state.json'))
+    handoff: readJsonOrNull(path.join(dir, 'handoff-state.json')),
+    ...(capture ? { capture } : {})
   };
 }
 
@@ -207,6 +236,20 @@ function runFixture(handle, action, pilot) {
     fs.writeFileSync(target, String(p.content), 'utf8');
     return fixtureResult(handle, pilot, { op: 'mutateIdentity', kind: p.kind, path: p.path });
   }
+  if (action.op === 'observeStateTree') {
+    // Read-only: lists the relative paths the replay wrote under its state home and workspace (F4-T12 matrix; no contents).
+    const list = root => { const out = []; const walk = dir => { for (const entry of fs.readdirSync(dir, { withFileTypes: true })) { const full = path.join(dir, entry.name); if (entry.isDirectory()) walk(full); else out.push(path.relative(root, full).split(path.sep).join('/')); } }; if (fs.existsSync(root)) walk(root); return out.sort(); };
+    return fixtureResult(handle, pilot, { op: 'observeStateTree', stateFiles: list(handle.stateHome), workspaceFiles: list(handle.workspace) });
+  }
+  if (action.op === 'editDocCheck') {
+    // Appends to the leg's installed doc-check file after a capture (F4-T6: the assessment-time digest check). Only a staged
+    // copy may change: the target must sit outside the repository.
+    if (typeof p.append !== 'string') throw new Error('editDocCheck needs an append string');
+    const target = handle.dist.docCheck;
+    if (path.basename(target) !== 'doc-check.js' || target.startsWith(REPO_ROOT + path.sep)) throw new Error('editDocCheck may only edit a staged doc-check copy');
+    fs.appendFileSync(target, p.append, 'utf8');
+    return fixtureResult(handle, pilot, { op: 'editDocCheck' });
+  }
   if (action.op === 'gitCommit') {
     // Commits the replay workspace's current tree into HEAD mid-workflow. The baseline recorded at plan is not moved by
     // this fixture: the case exists to show that scope is still assessed against that recorded baseline. A clean tree
@@ -230,6 +273,17 @@ function runFixture(handle, action, pilot) {
     fs.writeFileSync(target, JSON.stringify(p.json, null, 2), 'utf8');
     return fixtureResult(handle, pilot, { op: 'seedState', file: p.file });
   }
+  if (action.op === 'editJournal') {
+    // Rewrites one retained field of the replay's own capture journal, as an edited payload or result would appear on disk.
+    const dir = sessionDirOf(handle);
+    if (!dir) throw new Error('editJournal needs an existing session');
+    const file = path.join(dir, CAPTURE_JOURNAL_FILE);
+    const doc = readJsonOrNull(file);
+    if (!doc || !Array.isArray(doc.records) || !doc.records[p.index]) throw new Error('editJournal needs an existing journal record');
+    doc.records[p.index][p.key] = p.value;
+    fs.writeFileSync(file, JSON.stringify(doc, null, 2), 'utf8');
+    return fixtureResult(handle, pilot, { op: 'editJournal', key: p.key });
+  }
   if (action.op === 'timestampHints') {
     const dir = sessionDirOf(handle);
     if (!dir) throw new Error('timestampHints needs an existing session');
@@ -244,13 +298,82 @@ function runFixture(handle, action, pilot) {
   throw new Error(`unknown fixture op ${action.op}`);
 }
 
+function resultOf(handle, result, pilot) {
+  return {
+    exitCode: result.status,
+    signal: result.signal,
+    error: result.error ? result.error.message : null,
+    errorCode: result.error ? result.error.code || null : null,
+    stdout: result.stdout || '',
+    stderr: result.stderr || '',
+    json: parseJsonOrNull(result.stdout || ''),
+    state: snapshot(handle),
+    pilot
+  };
+}
+
+const DOC_CHECK_TOKEN = '{{DOC_CHECK}}';
+const CAPTURE_HOOK_EVENTS = new Set(['PreToolUse', 'PostToolUse', 'PostToolUseFailure', 'SubagentStart', 'SubagentStop']);
+
+// Host-transport ops (F4). hostRun executes the distribution's registered doc-check entry by argv, with no shell, the
+// way the host runs a registered command. hookDeliver sends one raw host payload to the real state-persist hook, with
+// the session and workspace fields the host would send. Payload content is declared by the case and then the entry
+// itself records it; the replay never writes a journal record or accepted event directly.
+function runHostOp(handle, action, pilot) {
+  const dist = handle.dist;
+  const p = action.payload || {};
+  if (action.op === 'hostRun') {
+    if (p.command !== 'doc-check' || !Array.isArray(p.args) || !p.args.every(arg => typeof arg === 'string')) {
+      throw new Error('hostRun needs command "doc-check" and string args');
+    }
+    return resultOf(handle, runScript(handle, scriptFor(handle, 'docCheck', dist.docCheck), p.args, undefined, pilot), pilot);
+  }
+  if (!CAPTURE_HOOK_EVENTS.has(p.event)) throw new Error(`hookDeliver event ${p.event} is not a capture event`);
+  const body = {
+    session_id: p.sessionId === undefined ? handle.sessionId : p.sessionId,
+    cwd: handle.workspace,
+    hook_event_name: p.event
+  };
+  if (p.event === 'PreToolUse' || p.event === 'PostToolUse' || p.event === 'PostToolUseFailure') {
+    if (typeof p.command !== 'string' || typeof p.toolUseId !== 'string') throw new Error('hookDeliver tool events need command and toolUseId');
+    body.tool_name = p.toolName === undefined ? 'Bash' : p.toolName;
+    // {{DOC_CHECK}} is the installed doc-check path of the leg under test, so a positive fixture invokes the path the
+    // host would really run; a relative spelling stays a literal negative case.
+    body.tool_input = { command: p.command.split(DOC_CHECK_TOKEN).join(dist.docCheck) };
+    body.tool_use_id = p.toolUseId;
+    // A subagent's own tool call carries its host agent_id at the top level (F4 executor identity).
+    if (p.agentId !== undefined) body.agent_id = p.agentId;
+  }
+  if (p.event === 'PostToolUse') {
+    if (p.fromRun !== undefined) {
+      const run = handle.actions[p.fromRun];
+      if (!run) throw new Error(`hookDeliver fromRun ${p.fromRun} names no earlier action`);
+      body.tool_response = { stdout: run.stdout, stderr: '', interrupted: false };
+    } else {
+      body.tool_response = p.response;
+    }
+    if (p.interrupted !== undefined) body.tool_response.interrupted = p.interrupted;
+    if (p.omitInterrupted === true) delete body.tool_response.interrupted;
+  } else if (p.event === 'PostToolUseFailure') {
+    body.error = p.error;
+    body.is_interrupt = p.isInterrupt === true;
+  } else {
+    body.agent_id = p.agentId;
+    body.agent_type = p.agentType;
+    if (p.event === 'SubagentStop') body.last_assistant_message = p.lastAssistantMessage;
+  }
+  // The hook is fail-open and prints nothing, so only its exit status and the journal it writes are observable.
+  return resultOf(handle, runScript(handle, scriptFor(handle, 'hookDeliver', dist.stateHook), [], body, pilot), pilot);
+}
+
 // Actions are the only way replay state changes. Each controller/stop op maps to the existing public entry point.
 function runAction(handle, action, pilot) {
-  const dist = DISTRIBUTIONS[handle.distribution];
+  const dist = handle.dist;
   const sid = handle.sessionId;
   const p = action.payload || {};
   if (!ALL_OPS.has(action.op)) throw new Error(`unsupported replay op ${action.op}`);
   if (FIXTURE_OPS.has(action.op)) return runFixture(handle, action, pilot);
+  if (HOST_OPS.has(action.op)) return runHostOp(handle, action, pilot);
   let result;
   if (action.op === 'route') {
     result = runScript(handle, scriptFor(handle, 'route', dist.kernel), [], { session_id: sid, cwd: handle.workspace, prompt: p.prompt }, pilot);
@@ -376,13 +499,16 @@ function runtimePilotOf(handle) {
 // Replays one case through one distribution. Actions run in order and the replay stops at its first infrastructure
 // fault: the faulted action is recorded, no later action runs, and the temporary directories are still removed.
 // A crash is recorded, not hidden.
+// `options.preload: true` adds the CI-only qualification preloader to every child (F4 test transport). Production
+// replays never set it, so the production gate stays unmet.
 function replayCase(caseDef, distribution, options = {}) {
   const limits = limitsFor(caseDef);
   const mode = options.pilot === undefined ? 'off' : 'on';
-  const handle = { ...createSession(distribution, caseDef.id, options.pilot), distribution, limits };
+  const handle = { ...createSession(distribution, caseDef.id, options.pilot), limits, preload: options.preload === true, nodeArgs: Array.isArray(options.nodeArgs) ? options.nodeArgs : [] };
   try {
     materialiseInput(handle, caseDef.input);
     const actions = {};
+    handle.actions = actions;
     for (const action of caseDef.actions) {
       if (Object.prototype.hasOwnProperty.call(actions, action.id)) throw new Error(`duplicate action id ${action.id}`);
       const payload = action.payload && action.payload.requirements === '$requirements'

package/ci/lib/doc-reconciliation-qualification-preload.js

@@ -0,0 +1,37 @@
+'use strict';
+
+// #325 Phase 3b F4 CI-only qualification preloader (docs/doc-workflow-reconciliation.md, F4 "Test transport").
+//
+// Loaded only by the test driver: `node --require <this file> <real entry> ...`. It is not packaged, no
+// production code reads it, and no environment or argv switch enables it.
+//
+// Boundary: it supplies only the explicitly fake qualification object through the origin-provider factory,
+// and only when the caller omitted qualification. It never touches the snapshot, resolveEvent outcomes,
+// principals, capability, accepted records or core eligibility.
+
+const fs = require('fs');
+const path = require('path');
+
+const FAKE_QUALIFICATION = Object.freeze({
+  source: 'fake-test-fixture',
+  faked: true,
+  ref: 'ci-qualification-preload',
+  toolUseIdPopulated: true,
+  agentIdPopulated: true,
+});
+
+// The entry decides which provider copy is patched, so the canonical and packaged legs are each covered.
+const entry = process.argv[1] ? path.resolve(process.argv[1]) : '';
+const providerFile = path.join(path.dirname(entry), 'lib', 'doc-reconciliation-provider.js');
+
+if (fs.existsSync(providerFile)) {
+  const provider = require(providerFile);
+  const factory = provider.createClaudeOriginProvider;
+  provider.createClaudeOriginProvider = input => {
+    const safe = input && typeof input === 'object' && !Array.isArray(input) ? input : {};
+    return factory({
+      ...safe,
+      qualification: safe.qualification === undefined ? FAKE_QUALIFICATION : safe.qualification,
+    });
+  };
+}

package/ci/lib/doc-reconciliation-replay.js

@@ -0,0 +1,104 @@
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawn, spawnSync } = require('child_process');
+const fx = require('./doc-reconciliation-prep-fixtures');
+
+const CORPUS = path.join(__dirname, '..', 'fixtures', 'doc-obligations', 'reconciliation-s2b', 'corpus');
+const CASES = path.join(__dirname, '..', 'fixtures', 'doc-obligations', 'reconciliation-s2b', 'f4', 'cases.json');
+const EVENT_HOOKS = new Set(['PreToolUse', 'PostToolUse', 'PostToolUseFailure', 'SubagentStart', 'SubagentStop']);
+const SITES = ['moduleLoads', 'stateFiles', 'captureRecords', 'pilotReport', 'workflowStep', 'workflowStop', 'genericStop'];
+
+function load(streamId) {
+  const file = path.join(CORPUS, `${streamId}.json`);
+  const stream = JSON.parse(fs.readFileSync(file, 'utf8'));
+  if (!stream.id || !Array.isArray(stream.events) || !stream.expectations) throw new Error(`invalid stream ${file}`);
+  for (const site of SITES) if (!stream.expectations[site]) throw new Error(`${stream.id} missing expectation site ${site}`);
+  return stream;
+}
+
+function tracePreloader(file) {
+  fs.writeFileSync(file, `const M=require('module'), fs=require('fs'); const old=M._load; M._load=function(id,p,m){const x=old.apply(this,arguments);if(typeof id==='string'&&/(doc-reconciliation|state-persist|workflow-disposition|stop-gate)/.test(id))fs.appendFileSync(process.env.F4_C1_TRACE,JSON.stringify({pid:process.pid,module:id,requester:m&&m.filename})+'\\n');return x};\n`);
+}
+
+function actionsFor(stream, template) {
+  const actions = template.actions.filter(a => !['lint-run','post-lint','verify-pass','stop','stop-generic'].includes(a.id));
+  stream.events.forEach((event, i) => {
+    if (!EVENT_HOOKS.has(event.event)) throw new Error(`${stream.id}: unsupported event ${event.event}`);
+    const id = `capture-${String(i + 1).padStart(2, '0')}`;
+    if (event.runArgs) actions.push({ id: `${id}-run`, op: 'hostRun', payload: { command: 'doc-check', args: event.runArgs } });
+    const payload = { event: event.event };
+    if (event.toolName) payload.toolName = event.toolName;
+    if (event.command !== undefined) payload.command = event.command;
+    if (event.toolUseId) payload.toolUseId = event.toolUseId;
+    if (event.runArgs && event.event === 'PostToolUse') payload.fromRun = `${id}-run`;
+    if (event.event === 'PostToolUse') payload.response = { stdout: event.runArgs ? 'doc-check completed' : 'completed', stderr: '', interrupted: false };
+    if (event.event === 'PostToolUseFailure') { payload.error = 'stable fixture failure'; payload.isInterrupt = false; }
+    if (event.event === 'SubagentStart' || event.event === 'SubagentStop') {
+      payload.agentId = `agent-${i + 1}`; payload.agentType = 'reviewer';
+      if (event.event === 'SubagentStop') payload.lastAssistantMessage = 'APPROVE: reviewed the governed document.';
+    }
+    actions.push({ id, op: 'hookDeliver', payload });
+  });
+  actions.push({ id: 'verify-pass', op: 'step', payload: { stepId: 'req-verify', disposition: 'pass', evidence: 'recorded document verification' }, expectExit: { on: [0, 2] } });
+  actions.push({ id: 'stop', op: 'stop' }, { id: 'stop-generic', op: 'stopGeneric' });
+  return actions;
+}
+
+function concurrent(stream, leg, mode) {
+  const dist = fx.DISTRIBUTIONS[leg];
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'f4c1-concurrent-'));
+  const stateHome = path.join(root, 'state'); const workspace = path.join(root, 'workspace');
+  fs.mkdirSync(workspace); fs.mkdirSync(stateHome);
+  const barrier = path.join(root, 'barrier'); fs.mkdirSync(barrier);
+  const worker = path.join(root, 'worker.js');
+  fs.writeFileSync(worker, `const fs=require('fs'),cp=require('child_process'),path=require('path');const [hook,barrier,home,workspace,sid,index,pilot]=process.argv.slice(2);fs.writeFileSync(path.join(barrier,'ready-'+index),'ready');while(!fs.existsSync(path.join(barrier,'go')))Atomics.wait(new Int32Array(new SharedArrayBuffer(4)),0,0,20);const p={session_id:sid,cwd:workspace,hook_event_name:'PostToolUse',tool_name:'Bash',tool_input:{command:'npm test'},tool_use_id:'concurrent-'+index,tool_response:{stdout:'ok',stderr:'',interrupted:false}};const r=cp.spawnSync(process.execPath,[hook],{input:JSON.stringify(p),encoding:'utf8',env:{...process.env,HARNESS_STATE_HOME:home,HARNESS_WORKSPACE_ROOT:workspace,...(pilot==='on'?{HARNESS_DOC_RECONCILIATION_PILOT:'1'}:{})}});process.exit(r.status||0);`);
+  const children = [1, 2].map(i => spawn(process.execPath, [worker, dist.stateHook, barrier, stateHome, workspace, 'concurrent-session', String(i), mode], { stdio: 'ignore' }));
+  while (![1, 2].every(i => fs.existsSync(path.join(barrier, `ready-${i}`)))) Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 20);
+  fs.writeFileSync(path.join(barrier, 'go'), 'release');
+  const exits = children.map(child => new Promise(resolve => child.on('exit', (code, signal) => resolve({ code, signal }))));
+  return Promise.all(exits).then(results => {
+    const files=[]; const walk=d=>{for(const e of fs.readdirSync(d,{withFileTypes:true})){const f=path.join(d,e.name);if(e.isDirectory())walk(f);else files.push({path:path.relative(stateHome,f),json:f.endsWith('.json')?safeJson(f):undefined,provenance:'concurrent state-persist process'});}};walk(stateHome);
+    fs.rmSync(root,{recursive:true,force:true}); return {results,files};
+  });
+}
+function safeJson(file){try{return JSON.parse(fs.readFileSync(file,'utf8'));}catch(_){return null;}}
+
+async function replay(streamId, leg='source', mode='on') {
+  if (!fx.DISTRIBUTIONS[leg]) throw new Error(`unknown distribution ${leg}`);
+  if (!['on','off'].includes(mode)) throw new Error(`unknown mode ${mode}`);
+  const stream=load(streamId); const cases=JSON.parse(fs.readFileSync(CASES,'utf8')).cases;
+  const template=cases.find(item=>item.id==='F4-POS-body-edit');
+  const definition={...template,id:stream.id,actions:actionsFor(stream,template)};
+  const scratch=fs.mkdtempSync(path.join(os.tmpdir(),'f4c1-')); const spy=path.join(scratch,'trace.js'); const trace=path.join(scratch,'modules.jsonl'); tracePreloader(spy);
+  const previous=process.env.F4_C1_TRACE; process.env.F4_C1_TRACE=trace;
+  let root;
+  try { root=fx.replayCase(definition,leg,{...(mode==='on'?{pilot:'1'}:{}),nodeArgs:['--require',spy]}); }
+  finally { if(previous===undefined)delete process.env.F4_C1_TRACE;else process.env.F4_C1_TRACE=previous; }
+  const modules=fs.existsSync(trace)?fs.readFileSync(trace,'utf8').trim().split('\n').filter(Boolean).map(JSON.parse):[];
+  const stateFiles=[]; const provenance=[];
+  for(const [actionId,action] of Object.entries(root.actions)) for(const key of ['workflow','obligations','handoff','capture']) if(action.state&&action.state[key]) {
+    stateFiles.push({actionId,key,provenance:`snapshot after ${actionId}`,value:action.state[key]});
+    if(key==='capture') for(const record of action.state.capture.records||[]) provenance.push({actionId,event:record.event,toolUseId:record.tool_use_id||record.toolUseId,provenance:'state-persist capture journal'});
+  }
+  const result={stream:stream.id,leg,mode,infrastructureErrors:fx.infrastructureFaults(definition,root,mode),moduleLoads:modules,stateFiles,captureRecords:provenance,pilotReport:root.pilot,pilotReportOrigin:root.pilotReportOrigin,workflowStep:Object.fromEntries(Object.entries(root.actions).filter(([id])=>id==='verify-pass').map(([id,a])=>[id,{exitCode:a.exitCode,stdout:a.stdout,stderr:a.stderr}])),workflowStop:root.actions.stop&&{exitCode:root.actions.stop.exitCode,stdout:root.actions.stop.stdout,stderr:root.actions.stop.stderr},genericStop:root.actions['stop-generic']&&{exitCode:root.actions['stop-generic'].exitCode,stdout:root.actions['stop-generic'].stdout,stderr:root.actions['stop-generic'].stderr},expectations:stream.expectations};
+  if(stream.concurrency) result.concurrency=await concurrent(stream,leg,mode);
+  fs.rmSync(scratch,{recursive:true,force:true});
+  return result;
+}
+
+async function selfCheck(){
+  const ids=fs.readdirSync(CORPUS).filter(f=>f.endsWith('.json')).map(f=>path.basename(f,'.json')).sort();
+  let failed=false;
+  for(const leg of ['source','packaged']) for(const id of ids){const stream=load(id);const result=await replay(id,leg,stream.mode);const journal=result.concurrency&&result.concurrency.files.find(file=>file.path.endsWith('doc-reconciliation-capture.json'));const concurrentBad=result.concurrency&&(result.concurrency.results.some(x=>x.code!==0)||!journal||journal.json.records.length!==2);const bad=result.infrastructureErrors.length||concurrentBad;console.log(`${bad?'INFRA':'OK'} ${leg}/${id}${bad?`: ${JSON.stringify(result.infrastructureErrors)} ${JSON.stringify(result.concurrency&&result.concurrency.results)} journalRecords=${journal&&journal.json.records.length}`:''}`);failed ||= Boolean(bad);}
+  return failed?1:0;
+}
+
+if(require.main===module){
+  if(process.argv[2]==='--worker')process.exit(0);
+  if(process.argv[2]==='--self-check')selfCheck().then(code=>process.exit(code));
+  else replay(process.argv[2],process.argv[3]||'source',process.argv[4]||'on').then(r=>console.log(JSON.stringify(r,null,2)));
+}
+module.exports={load,replay,selfCheck};

package/ci/lib/doc-reconciliation-staged-tree.js

@@ -0,0 +1,102 @@
+'use strict';
+
+// #325 F4-T2 test helper: stages a scratch copy of one leg's real entries (hooks, harness scripts and the retained
+// live-host capture), so a test chooses the qualification export itself. A staged tree never carries the repository's
+// export, and nothing here writes into the repository. The real entries run from the copy, with copied siblings, so
+// the provider walks up to the copied retained directory exactly as it would in the checkout.
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const crypto = require('crypto');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+const LIVE_REL = path.join('benchmarks', 'results', 'live-host', 'claude-325-3b-s2b');
+const EXPORT_FILE = 'doc-reconciliation-qualification.json';
+const CAPTURE_FILE = 'capture.sanitized.jsonl';
+// The export names its sanitized capture as a sibling in the same lib directory, so source and packaged copies resolve it
+// the same way (the provider reads it from there).
+const SIBLING_CAPTURE = 'doc-reconciliation-capture.sanitized.jsonl';
+// Facts observed in the retained Run 2b capture (see benchmarks/results/live-host/claude-325-3b-s2b/README.md). A valid
+// export states exactly these; the runtime checks them against the sibling file.
+const OBSERVED_PAYLOAD_KINDS = {
+  PostToolUse: ['agent_id', 'interrupted', 'tool_use_id'],
+  PreToolUse: ['agent_id', 'tool_use_id'],
+  SubagentStart: ['agent_id'],
+  SubagentStop: ['agent_id'],
+};
+const OBSERVED_CORRELATION = { preToPostByToolUseId: true, interruptedExplicit: true, subagentStartStopSameAgent: true, agentResultAliasCorrelated: true };
+
+// Top-level entries the source leg never reads: VCS and dependency trees, the worktrees, the test corpus, the evidence
+// directories and the packaging copies. The live-host capture is copied separately, below.
+const SOURCE_EXCLUDE = new Set(['.git', 'node_modules', '.worktrees', 'ci', 'benchmarks', 'behavioral-evals', 'evals', 'docs', 'plugins', 'submission', 'opencode-plugin']);
+
+function sha256File(file) {
+  return crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+}
+
+// Stages one leg. Returns the replay distribution (explicit entry paths inside the copy) and the helpers a test needs.
+// The live-host directory is copied to the top of the tree, which is where the provider's upward walk finds it.
+function stage(leg) {
+  if (leg !== 'source' && leg !== 'packaged') throw new Error(`unknown leg ${leg}`);
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), `f4-staged-${leg}-`));
+  let base;
+  if (leg === 'source') {
+    // The source package: the root carries the hooks, the harness scripts, the shared libraries and the root skill
+    // folders that bindings resolve. Only data that the entries never read is left out.
+    for (const entry of fs.readdirSync(ROOT)) {
+      if (SOURCE_EXCLUDE.has(entry)) continue;
+      fs.cpSync(path.join(ROOT, entry), path.join(root, entry), { recursive: true });
+    }
+    base = root;
+  } else {
+    fs.cpSync(path.join(ROOT, 'plugins', 'harness-everything'), path.join(root, 'plugin'), { recursive: true });
+    base = path.join(root, 'plugin');
+  }
+  fs.cpSync(path.join(ROOT, LIVE_REL), path.join(root, LIVE_REL), { recursive: true });
+  const libDir = path.join(base, 'hooks', 'scripts', 'lib');
+  // The copied tree may carry a checkout's own export: a staged tree starts without one.
+  fs.rmSync(path.join(libDir, EXPORT_FILE), { force: true });
+  fs.rmSync(path.join(libDir, SIBLING_CAPTURE), { force: true });
+  fs.copyFileSync(path.join(root, LIVE_REL, CAPTURE_FILE), path.join(libDir, SIBLING_CAPTURE));
+  const skillScripts = leg === 'source' ? path.join(base, 'harness-everything', 'scripts') : path.join(base, 'skills', 'harness-everything', 'scripts');
+  const dist = {
+    controller: path.join(base, 'hooks', 'scripts', 'workflow-disposition.js'),
+    stopGate: path.join(base, 'hooks', 'scripts', 'workflow-stop-gate.js'),
+    kernel: path.join(skillScripts, 'kernel-router.js'),
+    genericStopGate: path.join(base, 'hooks', 'scripts', 'stop-gate.js'),
+    stateHook: path.join(base, 'hooks', 'scripts', 'state-persist.js'),
+    docCheck: path.join(skillScripts, 'doc-check.js'),
+  };
+  return {
+    root,
+    leg,
+    dist,
+    libDir,
+    exportFile: path.join(libDir, EXPORT_FILE),
+    captureFile: path.join(libDir, SIBLING_CAPTURE),
+    retainedCaptureFile: path.join(root, LIVE_REL, CAPTURE_FILE),
+    // The export that binds the staged capture bytes and records the two populated fields.
+    // The valid export for this capture. `overrides` lets a test change one field, to show the runtime refuses it.
+    validExport(overrides = {}) {
+      return {
+        schema: 'harness.doc-reconciliation.qualification.v1',
+        host: 'claude-code',
+        hostVersion: '2.1.308',
+        captureRecordVersion: 'claude-capture-record/1',
+        payloadKinds: OBSERVED_PAYLOAD_KINDS,
+        correlation: OBSERVED_CORRELATION,
+        sanitizedCapture: { file: SIBLING_CAPTURE, sha256: sha256File(path.join(libDir, SIBLING_CAPTURE)) },
+        ...overrides,
+      };
+    },
+    writeExport(content) {
+      fs.writeFileSync(this.exportFile, typeof content === 'string' ? content : JSON.stringify(content, null, 2) + '\n', 'utf8');
+    },
+    cleanup() {
+      fs.rmSync(root, { recursive: true, force: true });
+    },
+  };
+}
+
+module.exports = { stage, EXPORT_FILE, SIBLING_CAPTURE, LIVE_REL, CAPTURE_FILE };