agenticreplay 0.1.0 → 0.1.2

package/packages/cli/src/commands/replay.ts

@@ -1,2289 +0,0 @@
-import { spawn } from 'node:child_process';
-import { mkdtemp, realpath, rm } from 'node:fs/promises';
-import { tmpdir } from 'node:os';
-import {
-  constants as fsConstants,
-  copyFileSync,
-  createReadStream,
-  linkSync,
-  lstatSync,
-  readlinkSync,
-  renameSync,
-  rmdirSync,
-  statSync,
-  symlinkSync,
-  unlinkSync,
-} from 'node:fs';
-import { createHash, randomBytes } from 'node:crypto';
-import { isAbsolute, join, relative, resolve } from 'node:path';
-import {
-  enclosingDelegation,
-  TraceReader,
-  deriveCheckpoints,
-  resolveRunSelector,
-  ensureRunsDir,
-  snapToCheckpoint,
-  TraceWriter,
-} from '@agenticreplay/core';
-import { FsCapture } from '@agenticreplay/fs-capture';
-import {
-  createProxy,
-  defaultDialects,
-  type RecordedExchange,
-  type RecordedRetrieval,
-  type RunCa,
-} from '@agenticreplay/proxy';
-import { defaultAdapters, resolveLaunch } from '@agenticreplay/adapters';
-import { serveViewer } from '@agenticreplay/viewer';
-import { isBlobRef, type TraceEvent } from '@agenticreplay/schema';
-import type { HarnessArtifacts } from '@agenticreplay/plugin-api';
-import { ExchangeEventDeriver, appendDerivedEvents } from '../exchange-events.js';
-import { cdCommand, type Output } from '../out.js';
-import type { ParsedArgs } from '../args.js';
-import { SerialQueue } from '../serial.js';
-import { appendSnapshot } from '../fs-events.js';
-import { drainMcpFrames, mcpForReplay, pointAtMcpConfig } from '../mcp.js';
-import { planTlsCapture, recordedTlsHosts, setupTlsCapture, trustRunCa } from '../tls-capture.js';
-import { upstreamPlan, type UpstreamPlan } from '../upstream.js';
-import { AGENTICREPLAY_VERSION } from '../version.js';
-
-export interface ReplayResult {
-  /** The run that was *read*: the recording being replayed or forked. */
-  runId: string;
-  mode: 'exact' | 'fork';
-  canonicalExact: number;
-  divergences: number;
-  /**
-   * Requests the recording could not serve.
-   *
-   * Printed in `replay.done` since the beginning and never returned, so every caller that was not
-   * a terminal had to scrape it back out of the log line — while `exitCode` folds it into a single
-   * bit. It is the number that says whether a replay actually reproduced the run.
-   */
-  unmatched: number;
-  liveCalls: number;
-  exitCode: number;
-  /**
-   * The run this invocation *wrote*, whichever mode it ran in — a fork's continuation, or an exact
-   * replay's record of its own findings. Absent only when `--no-trace` turned the latter off.
-   *
-   * `forkRunId` is kept as the fork-only name because callers use it to mean "there is a fork
-   * here": `--ui` opens it in preference to the parent, and `compare` reads token usage out of it.
-   * Neither is true of an exact replay's trace, which holds no exchanges at all.
-   */
-  traceRunId?: string;
-  forkRunId?: string;
-  /** Scratch worktree a fork ran in, so a verify command can be run against its result. */
-  worktree?: string;
-}
-
-/**
- * Rebuild the recorded exchanges from a trace.
- *
- * Eligible redacted transport bodies come back verbatim from storage. Canonical request matching
- * is a separate measure; a provider-translated origin response is not the client's response.
- */
-export async function loadExchanges(reader: TraceReader): Promise<RecordedExchange[]> {
-  const events = await reader.events();
-  const requests = events.filter((e) => e.type === 'net.request' && e.attrs?.phase === 'body');
-  const responses = new Map<string, TraceEvent>();
-  for (const event of events) {
-    if (event.type === 'net.response' && typeof event.attrs?.request_id === 'string') {
-      responses.set(event.attrs.request_id, event);
-    }
-  }
-  const dialects = defaultDialects();
-  const exchanges: RecordedExchange[] = [];
-  for (const req of requests) {
-    const id = req.attrs?.request_id;
-    if (typeof id !== 'string') continue;
-    const res = responses.get(id);
-    if (
-      !res ||
-      !res.causes?.includes(req.seq) ||
-      res.attrs?.response_complete !== true ||
-      req.attrs?.capture_incomplete ||
-      req.attrs?.truncated ||
-      res.attrs?.capture_incomplete ||
-      res.attrs?.truncated ||
-      res.attrs?.abandoned ||
-      req.attrs?.replay_eligible === false ||
-      res.transformations?.some((change) => change.rule === 'provider-protocol-translation') ||
-      req.payload === undefined ||
-      res.payload === undefined
-    )
-      continue;
-    const dialectId = req.attrs?.model_dialect;
-    const dialect = dialects.find((d) => d.id === dialectId);
-    if (!dialect) continue;
-    const rawRequest = await rawBodyOf(reader, req);
-    const rawResponse = await rawBodyOf(reader, res);
-    const headers = res.attrs?.headers as Record<string, unknown> | undefined;
-    const streamed =
-      String(headers?.['content-type'] ?? '').includes('text/event-stream') ||
-      rawResponse.trimStart().startsWith('data:') ||
-      rawResponse.trimStart().startsWith('event:');
-    exchanges.push({
-      seq: req.seq,
-      dialect: dialect.id,
-      path: String(req.attrs?.path ?? '/'),
-      rawRequest,
-      rawResponse,
-      status: Number(res.attrs?.status ?? 0),
-      streamed,
-      canonicalRequest: dialect.toCanonicalRequest(JSON.parse(rawRequest)),
-      durationMs: Number(res.attrs?.duration_ms ?? 0),
-    });
-  }
-  return exchanges;
-}
-
-/**
- * Rebuild the recording's retrieval calls — embeddings, rerank — from its `net.*` pairs.
- *
- * They live there rather than in `model.request` because that is what they are: HTTP the proxy
- * saw and no dialect claimed. What sets them apart from the rest of that traffic is the two
- * attributes `RetrievalRule` put on them. `replay_key` is what a later run looks the answer up
- * by, and its presence is the whole test for "this pair can be served again" — a pair without one
- * is the opaque traffic `net.*` has always held, and is skipped here rather than guessed at.
- *
- * Pairing is by `causes`, not by position. A run interleaves retrieval with model calls and the
- * responses arrive out of order under a worker pool, so the nth response is not the answer to the
- * nth request; the writer already records which request each response answered.
- */
-export async function loadRetrievals(reader: TraceReader): Promise<RecordedRetrieval[]> {
-  const events = await reader.events();
-  const responses = new Map<number, TraceEvent>();
-  for (const event of events) {
-    if (event.type !== 'net.response') continue;
-    for (const cause of event.causes ?? []) responses.set(cause, event);
-  }
-
-  const out: RecordedRetrieval[] = [];
-  for (const request of events) {
-    if (request.type !== 'net.request') continue;
-    const key = request.attrs?.['replay_key'];
-    if (typeof key !== 'string' || key === '') continue;
-    const response = responses.get(request.seq);
-    if (
-      request.attrs?.['truncated'] ||
-      response?.attrs?.['truncated'] ||
-      request.attrs?.['capture_incomplete'] ||
-      response?.attrs?.['capture_incomplete'] ||
-      response?.attrs?.['abandoned'] ||
-      response === undefined
-    )
-      continue;
-    const headers = response?.attrs?.['headers'];
-    const contentType =
-      headers !== null && typeof headers === 'object'
-        ? ((headers as Record<string, unknown>)['content-type'] ?? 'application/json')
-        : 'application/json';
-    const stored = response?.attrs?.['stored'];
-    const digest = response?.attrs?.['response_sha256'];
-    const batchKey = request.attrs?.['batch_key'];
-    out.push({
-      seq: request.seq,
-      rule: String(request.attrs?.['rule'] ?? 'unknown'),
-      key,
-      path: String(request.attrs?.['path'] ?? ''),
-      status: Number(response?.attrs?.['status'] ?? 200),
-      contentType: typeof contentType === 'string' ? contentType : 'application/json',
-      // Needed only to reorder a batch, which cannot be done without knowing which text each
-      // recorded vector answered. A recording made before that existed has none, and simply
-      // cannot be reordered.
-      rawRequest: await rawBodyOf(reader, request),
-      // A digest-only recording kept no body. Empty here is what the proxy reads as "agenticreplay has
-      // proof of this answer and not the answer", and it says so rather than serving nothing.
-      rawResponse:
-        stored === 'digest' || response === undefined ? '' : await rawBodyOf(reader, response),
-      ...(typeof digest === 'string' ? { digest } : {}),
-      ...(typeof batchKey === 'string' ? { batchKey } : {}),
-    });
-  }
-  return out;
-}
-
-/**
- * Read a recorded body back as the exact bytes that were sent.
- *
- * The subtlety is the spill boundary. The writer stores `JSON.stringify(payload)` in a blob once a
- * payload crosses `INLINE_PAYLOAD_LIMIT`, and every wire body is a *string* — so the same body is
- * kept as itself while it fits inline and as a quoted, backslash-escaped JSON string literal once
- * it spills. Reading the blob bytes straight back therefore returns an escaped copy: canonicalizing
- * it yields `model: ''` and `messages: []`, every request falls to rung 4, and replay against any
- * real harness matches nothing at all. Undoing the writer's encoding is what makes the two forms
- * identical again.
- *
- * Not `resolvePayload`, which would hand back a parsed object for a body that was recorded as one;
- * exact replay means the agent gets the same bytes, so anything that is not a JSON string is
- * returned verbatim.
- */
-async function rawBodyOf(reader: TraceReader, event: TraceEvent): Promise<string> {
-  const payload = event.payload;
-  if (isBlobRef(payload)) {
-    const text = new TextDecoder().decode(await reader.blob(payload));
-    try {
-      const decoded: unknown = JSON.parse(text);
-      return typeof decoded === 'string' ? decoded : text;
-    } catch {
-      // Not JSON at all — a blob written by something else, or a future media type. The bytes are
-      // still the best answer available.
-      return text;
-    }
-  }
-  if (typeof payload === 'string') return payload;
-  return JSON.stringify(payload ?? {});
-}
-
-/**
- * The arguments that will make the agent ask again.
- *
- * A run recorded as `agenticreplay record claude -- -p "..."` carries its prompt in argv, and replaying it
- * is simply a matter of passing it back. A run driven by hand carries nothing: the prompt went
- * into a terminal, and argv is just `["claude"]`. Replaying that launched an agent with no reason
- * to call anything, so the recorded exchanges were never requested and the replay came back empty.
- *
- * The prompts recorded from the harness's own transcript are what closes that gap. Only the first
- * turn is driven — the harnesses take one prompt per non-interactive invocation — so a multi-turn
- * conversation says how much of itself it is reproducing instead of quietly reproducing one turn
- * and calling it a replay.
- */
-function driveArgs(
-  adapter: {
-    driveArgs?(prompts: string[], recorded: string[]): string[] | undefined;
-    replayArgs?(recorded: string[]): string[] | undefined;
-    artifacts?: HarnessArtifacts;
-  },
-  ctx: { manifest: { argv: string[] }; prompts: string[] },
-  out: Output,
-  args?: ParsedArgs,
-): string[] {
-  const argv = chosenArgs(adapter, ctx, out);
-  return args?.bool('serialize') ? serialized(adapter.artifacts, argv, out) : argv;
-}
-
-/**
- * Run the harness one request at a time, for an operator who asked for determinism explicitly.
- *
- * Never on by default, and the reason is the whole point of a replay: clamping concurrency
- * changes the run being reproduced. A pipeline with ten workers and one with one worker do the
- * same work in a different order, and a replay that quietly ran the second is not a replay of the
- * first. What it *is* good for is the second question someone asks of a flaky pipeline — "is this
- * a concurrency problem?" — which is worth one flag and worth being asked for.
- *
- * The adapter declares which flag its harness spells this with; agenticreplay does not guess. An adapter
- * that declares none says so rather than silently doing nothing.
- */
-function serialized(
-  artifacts: HarnessArtifacts | undefined,
-  argv: string[],
-  out: Output,
-): string[] {
-  const clamp = artifacts?.concurrencyFlag;
-  if (clamp === undefined) {
-    out.warn('replay.serialize_unsupported', {
-      why: 'this adapter declares no concurrency flag, so agenticreplay has nothing to clamp',
-      effect: 'the replay runs exactly as recorded',
-    });
-    return argv;
-  }
-  const at = argv.indexOf(clamp.flag);
-  const next = [...argv];
-  if (at === -1) next.push(clamp.flag, clamp.serialValue);
-  else next[at + 1] = clamp.serialValue;
-  out.info('replay.serialized', {
-    flag: clamp.flag,
-    value: clamp.serialValue,
-    note: 'this replays a different run from the one recorded, on purpose',
-  });
-  return next;
-}
-
-/** The argv a replay would run with, before `--serialize` has a say. */
-function chosenArgs(
-  adapter: {
-    driveArgs?(prompts: string[], recorded: string[]): string[] | undefined;
-    replayArgs?(recorded: string[]): string[] | undefined;
-  },
-  ctx: { manifest: { argv: string[] }; prompts: string[] },
-  out: Output,
-): string[] {
-  const recorded = ctx.manifest.argv.slice(1);
-  const prompts = ctx.prompts;
-  // Before the transcript is consulted, because a harness that keeps none never reached the hook
-  // below at all: the early return for "no prompts" fired first, so an adapter for a pipeline —
-  // whose argv is the entire instruction and whose prompts exist nowhere — had no way to say
-  // anything about its own replay.
-  const rewritten = adapter.replayArgs?.(recorded);
-  if (rewritten !== undefined) return rewritten;
-  if (prompts.length === 0) return recorded;
-
-  // Whether argv already drives the run, decided by comparing it against the prompts the harness
-  // recorded rather than by looking for a flag. `codex exec` with the prompt on stdin has a
-  // non-empty argv that carries no prompt at all, so "argv is non-empty" answers the wrong
-  // question; "argv contains what the person actually asked" answers the right one.
-  if (prompts.some((prompt) => recorded.includes(prompt))) return recorded;
-
-  const driven = adapter.driveArgs?.(prompts, recorded);
-  if (driven === undefined) return recorded;
-
-  // Said before the run, not after, because it reframes every divergence that follows. A harness
-  // driven without a terminal does not send byte-identical requests to the ones it sent with one —
-  // Claude Code splices an extra reminder turn into an interactive conversation, and the calls it
-  // makes for itself, like naming the session, have no counterpart at all. Those show up as
-  // unmatched, and without this line they read as a corrupt trace rather than as the cost of
-  // reproducing a conversation nobody recorded the keystrokes of.
-  out.info('replay.driven', {
-    source: 'harness transcript',
-    turns_recorded: prompts.length,
-    turns_driven: 1,
-    note:
-      prompts.length > 1
-        ? 'the harness takes one prompt per non-interactive run; later turns are not re-asked'
-        : 'requests the harness made for itself may not recur',
-  });
-  return driven;
-}
-
-/**
- * Prompts off a `session.snapshot`.
- *
- * The transcript rides in the same payload, so this spills to a blob for any real session — which
- * is why it takes the reader rather than reading the event alone.
- */
-async function readPrompts(reader: TraceReader, events: TraceEvent[]): Promise<string[]> {
-  const event = events.find((e) => e.type === 'session.snapshot');
-  if (event === undefined) return [];
-  let payload: unknown = event.payload;
-  try {
-    if (isBlobRef(payload)) {
-      payload = JSON.parse(new TextDecoder().decode(await reader.blob(payload)));
-    }
-    if (typeof payload === 'string') payload = JSON.parse(payload);
-  } catch {
-    return [];
-  }
-  if (payload === null || typeof payload !== 'object') return [];
-  const prompts = (payload as { prompts?: unknown }).prompts;
-  return Array.isArray(prompts) ? prompts.filter((p): p is string => typeof p === 'string') : [];
-}
-
-export async function replayCommand(
-  args: ParsedArgs,
-  out: Output,
-  cwd = process.cwd(),
-): Promise<ReplayResult> {
-  const selector = args.positionals[0] ?? 'last';
-  const runDir = (await resolveRunSelector(cwd, selector)).dir;
-  const reader = await TraceReader.open(runDir);
-  if (reader.manifest().capture?.status === 'incomplete') {
-    out.warn('replay.source_incomplete', {
-      issues: reader.manifest().capture!.issues.join(','),
-      detail: 'only complete transport pairs are eligible; missing responses cannot be served',
-    });
-  }
-  const manifest = reader.manifest();
-  const events = await reader.events();
-
-  const integrity = await reader.verifyIntegrity();
-  // Two different facts, and saying the wrong one costs trust in the right one. A recorder that was
-  // killed leaves a run with no digest at all, and telling that person their trace "changed since
-  // the run ended" is an accusation about a file nothing touched.
-  if (integrity.state === 'mismatch') {
-    out.warn('trace.integrity', {
-      expected: integrity.expected,
-      actual: integrity.actual,
-      note: 'events.jsonl changed since the run ended',
-    });
-  } else if (integrity.state === 'unsealed') {
-    out.warn('trace.unsealed', {
-      actual: integrity.actual,
-      note: 'the recorder never sealed this run, so there is nothing to verify it against',
-    });
-  }
-
-  const exchanges = await loadExchanges(reader);
-  const retrievals = await loadRetrievals(reader);
-  const prompts = await readPrompts(reader, events);
-  const from = args.num('from');
-  const model = args.str('model');
-  const isFork = from !== undefined || model !== undefined;
-
-  const result = isFork
-    ? await replayFork(args, out, {
-        manifest,
-        events,
-        exchanges,
-        retrievals,
-        runDir,
-        cwd,
-        prompts,
-        from,
-        model,
-      })
-    : await replayExact(args, out, {
-        manifest,
-        events,
-        exchanges,
-        retrievals,
-        runDir,
-        cwd,
-        prompts,
-      });
-
-  if (args.bool('ui')) {
-    // Show the run you just produced: after a fork that is the child, not the parent, because
-    // the child is the one carrying the outcome you asked the question about.
-    const target = result.forkRunId
-      ? (await resolveRunSelector(cwd, result.forkRunId)).dir
-      : runDir;
-    await openViewer(target, args, out);
-  }
-
-  return result;
-}
-
-async function openViewer(runDir: string, args: ParsedArgs, out: Output): Promise<void> {
-  const server = await serveViewer({ runDir, port: args.num('port') ?? 0 });
-  out.phase('viewer', { url: server.url });
-  out.plain('  ctrl-c to stop');
-  await new Promise<void>((resolve) => {
-    process.once('SIGINT', () => void server.close().then(resolve));
-  });
-}
-
-interface Ctx {
-  manifest: ReturnType<TraceReader['manifest']>;
-  events: TraceEvent[];
-  exchanges: RecordedExchange[];
-  /** Embedding and rerank calls the recording can answer without a dialect. */
-  retrievals: RecordedRetrieval[];
-  runDir: string;
-  cwd: string;
-  /** The user's turns, recovered from the harness transcript. Empty when there was none. */
-  prompts: string[];
-}
-
-/**
- * Exact replay. Every response comes from the trace and egress is blocked — if the agent reaches
- * for the network here, that is a bug we want to fail on, not paper over.
- *
- * It also restores the filesystem the run started from, and that is not a nicety. A harness reads
- * files into the conversation, so the bytes on disk end up inside the recorded request; the run
- * then edits those same files. Replaying in the directory you recorded in re-reads what the
- * recording itself changed, the trailing message differs, and the replay halts at rung 4 —
- * correctly, but uselessly, because nothing about the recording was wrong. Restoring first is
- * what makes "exact" mean anything, and it has the second virtue of leaving your checkout alone
- * rather than letting the agent edit it a second time.
- */
-async function replayExact(args: ParsedArgs, out: Output, ctx: Ctx): Promise<ReplayResult> {
-  // Before `replayWorkspace`, because these refuse and `replayWorkspace` replaces the working
-  // tree. Resolved after it, a refusal threw with the checkout holding the recorded run's files
-  // and the operator's own tree left behind in an `agenticreplay-safety-*` scratch whose path nothing
-  // prints — the outcome the release exists to prevent, escaping it because it only ran at the
-  // child's launch. An invocation that cannot work should decide so before it touches anything,
-  // which is the rule `attach` already follows where it resolves the advertised URL before making
-  // a run directory.
-  //
-  // Two refusals, not one. `upstreamPlan` rejects an upstream that is not an origin;
-  // `planTlsCapture` rejects a `--tls-hosts` list that names `*` or contradicts itself, and an
-  // `AGENTICREPLAY_TLS_UPSTREAM_CA` that cannot be read. It is the refusing half of `setupTlsCapture` on
-  // its own — it mints nothing, so the certificate authority is still created down where the run
-  // is, after the workspace exists.
-  const plan = await upstreamPlan(args);
-  // A run recorded through interception is reproduced through it, without the operator having to
-  // remember which hosts they named. See `setupTlsCapture`.
-  const interceptedHosts = recordedTlsHosts(ctx.events);
-  await planTlsCapture(args, interceptedHosts);
-
-  // Armed on the line after the call, which is only sound because `replayWorkspace` owns its own
-  // destructive step: it either returns with the tree replaced and a `release` that undoes that,
-  // or it throws having already put the tree back. Arming here without that guarantee would have
-  // read as covering the restore while missing it entirely — the restore is inside the call, so a
-  // `materialize` that failed part-way rejected before `workspace` was ever assigned.
-  const workspace = await replayWorkspace(args, out, ctx);
-  try {
-    return await replayRestored(args, out, ctx, { plan, interceptedHosts, workspace });
-  } finally {
-    // The outermost of three, and the one that needs no list to be right. Hoisting a refusal is
-    // only ever as complete as the list of refusals somebody thought of, and that list has been
-    // wrong twice; `replayRestored` has its own `finally` for the span it owns; this covers what
-    // is left, which is `openReplayTrace` throwing before that span begins. `release` is
-    // idempotent, so the ordinary path still puts the tree back where it always did — before the
-    // run reports itself done — and this is a no-op behind it.
-    await workspace.release();
-  }
-}
-
-/**
- * The replay itself, once the filesystem it needs is in place.
- *
- * Split from `replayExact` for one reason: everything in here happens with the recording's files
- * over the operator's checkout, so it has to run inside something that puts them back.
- */
-async function replayRestored(
-  args: ParsedArgs,
-  out: Output,
-  ctx: Ctx,
-  prepared: {
-    plan: UpstreamPlan;
-    interceptedHosts: readonly string[] | undefined;
-    workspace: Workspace;
-  },
-): Promise<ReplayResult> {
-  const { plan, interceptedHosts, workspace } = prepared;
-  const divergences: { level: string; detail: string; seq: number }[] = [];
-  const unmatched: { seq: number; reason: string }[] = [];
-  const trace = await openReplayTrace(args, ctx, workspace.dir);
-  // Serial for the same reason the recorder's is: the callbacks fire from the proxy's request
-  // handler, and two overlapping appends would interleave lines in events.jsonl.
-  const writes = new SerialQueue();
-
-  /**
-   * The two things a failed replay would otherwise leave running or on disk.
-   *
-   * Filled as each is built, because what needs cleaning up depends on how far the run got:
-   * `createProxy` throwing has a key to remove and no socket, and everything after it has both.
-   */
-  let mintedCa: RunCa | undefined;
-  let openProxy: { close: () => Promise<void> } | undefined;
-
-  /**
-   * Give up on a replay that has already built something, then re-throw. `agenticreplay record`'s
-   * `abandon` is the same function for the same two reasons.
-   *
-   * A listening proxy keeps Node's event loop alive, so a throw printed the error and then hung
-   * forever — `agenticreplay replay` was the one command of the three that had to be killed. And an
-   * unsealed trace has no `ended_at` or `integrity`, so `verifyIntegrity` reports the run as
-   * *tampered* rather than as unfinished.
-   *
-   * Sealing rather than discarding, for the reason the fork gives: a run that failed to launch is
-   * still a run someone will want to read. The CA is not disposed here because the `finally`
-   * below does it on both paths.
-   */
-  async function abandon(err: unknown): Promise<never> {
-    await openProxy?.close().catch(() => undefined);
-    await writes.drain().catch(() => undefined);
-    if (trace) {
-      await trace
-        .append({ type: 'run.end', actor: 'agenticreplay', turn: 0, attrs: { error: String(err) } })
-        .catch(() => undefined);
-      await trace.close().catch(() => undefined);
-    }
-    throw err;
-  }
-
-  /*
-   * Everything from here to the child's exit mints a key and then opens a socket, so everything
-   * from here to the child's exit has to come back through `abandon` — the rule `agenticreplay record`
-   * states in the same words, having learned it the same way.
-   *
-   * The guard used to start at the spawn, which covered the failure it was written for and missed
-   * the four that happen first. `RunCa.create` writes `tls/ca.key`; `createProxy` binds; then
-   * `mcpForReplay` rewrites a config and `adapter.prepare` runs a harness's own validation, which
-   * is where `agenticreplay replay` on a trace naming an adapter this build does not have ended up — the
-   * right error message, printed, and then a process that never exited with a private key left
-   * behind in the run directory.
-   */
-  try {
-    // A subscription-backed harness does not use the ordinary base URL, so exact replay needs the
-    // same per-run CA and HTTPS proxy as recording. The proxy's TLS hook then answers Codex's
-    // model request from the trace before it can open an origin connection.
-    // The hosts were resolved before the workspace was restored, where anything refusable about
-    // them was refused; this is the half that mints.
-    const tls = await setupTlsCapture({
-      args,
-      out,
-      ...(interceptedHosts ? { recordedHosts: interceptedHosts } : {}),
-      writer: trace,
-      runDir: ctx.runDir,
-      writes,
-      turn: () => 0,
-    });
-    // Handed to `abandon` the moment it exists, not once the run is under way: `createProxy` on
-    // the next line is one of the throws this key has to survive being disposed by.
-    mintedCa = tls.ca;
-
-    const proxy = await createProxy({
-      mode: 'replay',
-      exchanges: ctx.exchanges,
-      retrievals: ctx.retrievals,
-      loose: args.bool('loose'),
-      upstream: plan.upstream,
-      upstreamHeaders: plan.headers,
-      upstreamHeadersOrigin: plan.headersOrigin,
-      ...tls.proxyOptions,
-      onDivergence: (d) => {
-        divergences.push(d);
-        if (!trace) return;
-        writes.push(async () => {
-          await trace.append({
-            type: 'divergence',
-            actor: 'agenticreplay',
-            // Turn 0 for everything in this trace, and deliberately not a running count. An exact
-            // match produces no callback, so a counter here would number the third divergence as
-            // turn 1 and claim a position in the conversation that it does not have. `source_seq`
-            // is the honest coordinate: it points straight at the parent's own event.
-            turn: 0,
-            attrs: { level: d.level, rung: d.rung, detail: d.detail, source_seq: d.seq },
-          });
-        });
-      },
-      // Printed as it happens rather than tallied at the end. A halted replay stops the agent, so
-      // the count in `replay.done` arrives after the operator has already seen the run die — and a
-      // bare `unmatched=1` with no reason is indistinguishable from a bug in agenticreplay itself.
-      //
-      // The two directories are on the line because a distance in the hundreds of thousands is true
-      // and unactionable. Harnesses put absolute paths in their tool calls, so a replay running
-      // anywhere but the recording's own directory gets a permission refusal where the recording has
-      // file contents — by far the most common cause of a halt, and invisible from the number alone.
-      onUnmatched: (u) => {
-        unmatched.push(u);
-        // A halt inside a delegation is not a corrupt trace and not a bug, and looks like both. The
-        // harness writes the delegate's prompt itself, fresh on every run, so the request really is
-        // a different question — which is exactly what the matcher refuses to serve from a
-        // recording. Without this the operator sees `distance 54` and goes looking for the fault.
-        const delegation = enclosingDelegation(ctx.events, u.seq);
-        const next =
-          workspace.dir === ctx.manifest.cwd
-            ? 'agenticreplay replay <run> --loose'
-            : `${cdCommand(ctx.manifest.cwd)} && agenticreplay replay <run> --in-place   # or --loose to continue live`;
-        out.warn('replay.unmatched', {
-          seq: u.seq,
-          index: u.index,
-          reason: u.reason,
-          ...(delegation === undefined
-            ? {}
-            : {
-                inside: `${delegation.subagent} delegated at seq ${delegation.seq}`,
-                why: 'the harness writes a delegate prompt of its own each run, so this request is a different question rather than a drifted one',
-              }),
-          recorded_in: ctx.manifest.cwd,
-          replayed_in: workspace.dir,
-          next,
-        });
-        // Again as a line of its own. The field above is for whatever reads the record; on a terminal
-        // it is shown JSON-escaped — every backslash doubled, every quote escaped — which is correct
-        // for a key=value line and useless to paste, and a Windows path is nothing but backslashes.
-        out.plain(`  next: ${next}`);
-        if (!trace) return;
-        // `error`, not `divergence`: nothing was served and the run is over, so calling it an
-        // inexact match would put a rung on a ladder the request never climbed. It is also the one
-        // finding here that exists nowhere else — a matched exchange is already in the parent, but
-        // "the agent asked for something this recording cannot answer" is new, and until now it
-        // lived only in the operator's scrollback.
-        writes.push(async () => {
-          await trace.append({
-            type: 'error',
-            actor: 'agenticreplay',
-            turn: 0,
-            attrs: {
-              rule: 'replay_unmatched',
-              rung: 4,
-              reason: u.reason,
-              index: u.index,
-              source_seq: u.seq,
-              recorded_in: ctx.manifest.cwd,
-              replayed_in: workspace.dir,
-            },
-          });
-        });
-      },
-    });
-    // Listening from here on, so from here on a throw that does not close it is a process that
-    // does not exit.
-    openProxy = proxy;
-
-    await trace?.append({
-      type: 'run.start',
-      actor: 'agenticreplay',
-      turn: 0,
-      attrs: {
-        adapter: ctx.manifest.adapter.id,
-        cwd: workspace.dir,
-        proxy: proxy.url,
-        mode: 'replay',
-        // Also on the manifest, which is what an out-of-process reader sees first. Here as well
-        // because a trace read on its own should say what it is a replay of.
-        parent_run: ctx.manifest.run_id,
-        exchanges: ctx.exchanges.length,
-      },
-    });
-
-    out.phase('replaying', {
-      run: ctx.manifest.run_id,
-      exchanges: ctx.exchanges.length,
-      // Read from the flag, because `--loose` is exactly the run where it is not blocked. It was a
-      // literal, so `agenticreplay replay <run> --loose` announced `egress=blocked` and then answered the
-      // first unmatched request from the provider — the one line a reader checks to know whether a
-      // run can spend money, saying the opposite of what the run was about to do. Worse than an
-      // inaccuracy, because `replay halted` recommends `--loose` by name: the reader is following
-      // agenticreplay's own advice when the label stops being true.
-      egress: args.bool('loose') ? 'live-on-unmatched' : 'blocked',
-      proxy: proxy.url,
-      cwd: workspace.dir,
-    });
-
-    // The agent runs live for everything that is not a model call, MCP included. Without a config it
-    // talks to servers agenticreplay cannot see — or, for a harness that requires the variable, does not start
-    // at all, which is how a replay of a working recording exits non-zero for a reason that has
-    // nothing to do with the recording.
-    const mcp =
-      trace === undefined
-        ? undefined
-        : await mcpForReplay(
-            args,
-            ctx.events,
-            trace,
-            out,
-            join(ctx.runDir, 'mcp-frames.jsonl'),
-            ctx.runDir,
-          );
-
-    const adapter = defaultAdapters().get(ctx.manifest.adapter.id);
-    const launch = await adapter.prepare({
-      runId: ctx.manifest.run_id,
-      cwd: workspace.dir,
-      proxyUrl: proxy.url,
-      runDir: ctx.runDir,
-      userArgs: driveArgs(adapter, ctx, out, args),
-      env: process.env,
-    });
-    // Replaying must not introduce a catalog request before the capture plugin is installed.
-    if (adapter.id === 'opencode') launch.env.OPENCODE_DISABLE_MODELS_FETCH = '1';
-    if (proxy.tls) await trustRunCa(trace, proxy.tls, proxy.url, launch.env, out);
-    if (mcp) {
-      pointAtMcpConfig(launch.env, mcp.configPath);
-      // Same as record: the path has to reach the harness the way the harness actually reads it, or
-      // a replay re-instruments a config nothing opens and every recorded MCP call goes unmatched.
-      const mcpArgs = adapter.mcpConfigArgs?.(mcp.configPath);
-      if (mcpArgs !== undefined) launch.args = [...mcpArgs, ...launch.args];
-    }
-
-    const exitCode = await runChild(
-      launch.command,
-      launch.args,
-      { ...process.env, ...launch.env },
-      workspace.dir,
-      agentStdoutFor(args),
-    );
-
-    await writes.drain();
-    const stats = proxy.stats();
-    await proxy.close();
-
-    for (const d of divergences) {
-      out.warn('divergence', { seq: d.seq, level: d.level, detail: d.detail });
-    }
-
-    // A halted replay is a failed replay even if the harness chose to exit 0 on the error. The exit
-    // code is what a script reads, so it has to reflect what happened rather than what the agent
-    // decided to do about it — and the trace records the same verdict for the same reason.
-    const verdict = exitCode === 0 && unmatched.length > 0 ? 1 : exitCode;
-
-    if (trace) {
-      // What the replay discovered rather than repeated: these calls really happened just now, and
-      // exist nowhere in the parent.
-      if (mcp) await drainMcpFrames(mcp, trace, () => 0, 0);
-      await trace.append({
-        type: 'run.end',
-        actor: 'agenticreplay',
-        turn: 0,
-        attrs: {
-          exit_code: verdict,
-          agent_exit_code: exitCode,
-          matched: stats.matchedExact,
-          divergences: stats.divergences,
-          unmatched: stats.unmatched,
-        },
-      });
-      await trace.close(verdict);
-    }
-
-    /**
-     * Retrieval fidelity, on its own axis and only when the run has one.
-     *
-     * Never folded into `exact`: that number is about a matching ladder these calls do not climb,
-     * and mixing them would make a recording look more faithfully reproduced the more embeddings
-     * it happened to make. Omitted entirely when neither the recording nor the replay had any, so
-     * an ordinary run's verdict line keeps the shape it has always had.
-     */
-    const retrieval =
-      stats.retrievalTotal > 0 || stats.retrievalServed > 0 || stats.retrievalLive > 0
-        ? { retrieval: `${stats.retrievalServed}/${stats.retrievalTotal}` }
-        : {};
-
-    out.phase('replay.done', {
-      // `matched=1 total=13` was the old shape, and on a healthy replay of a real harness it read as
-      // a failure: rung 1 is only reachable when nothing in the request was redacted, so a run whose
-      // every request was served from disk still reported one match. What someone wants to know here
-      // is how much of the recording was reused, and how much of that reuse was exact.
-      reused: `${stats.matchedExact + stats.matchedInexact}/${ctx.exchanges.length}`,
-      canonical_exact: stats.matchedExact,
-      divergences: stats.divergences,
-      unmatched: stats.unmatched,
-      // Only when it happened. An exchange served from a position other than the cursor is not a
-      // fidelity loss — it was byte-identical, or it carried a divergence of its own and is
-      // counted there — but it is worth saying, because it is the difference between a recording
-      // that reproduced and one that merely happened to line up.
-      ...(stats.reordered > 0 ? { reordered: stats.reordered } : {}),
-      ...retrieval,
-      exit: exitCode,
-      // Omitted entirely under --no-trace: `Output` drops undefined fields, so the line stays the
-      // shape it has always been for anyone who opted out.
-      trace: trace?.runId,
-    });
-
-    return {
-      runId: ctx.manifest.run_id,
-      mode: 'exact',
-      ...(trace === undefined ? {} : { traceRunId: trace.runId }),
-      canonicalExact: stats.matchedExact,
-      divergences: stats.divergences,
-      unmatched: stats.unmatched,
-      liveCalls: stats.liveCalls,
-      exitCode: verdict,
-    };
-  } catch (err) {
-    // `return await`, not the bare `return abandon(err)` that `agenticreplay record` can afford. The
-    // difference is the `finally` below: a promise returned out of a `catch` is not adopted by
-    // the caller until the `finally` has finished, and this one awaits real I/O, so the
-    // rejection sits with no handler attached for as long as that takes. Node reports it as an
-    // unhandled rejection and kills the process on the spot — the operator got a raw stack trace
-    // where `agenticreplay replay` had always printed `error replay.failed`, and `main`'s catch never ran
-    // at all. Awaiting here turns it back into a throw *inside* the catch, before the finally,
-    // which is what every frame above expects.
-    return await abandon(err);
-  } finally {
-    // Both paths, which is why these two are here and the proxy is not: a replay that ran
-    // closes its own proxy after reading `stats()`, and one that did not comes through
-    // `abandon`. These do not divide that way. The whole justification for restoring over
-    // the working tree is that it is put back, and `tls-capture.ts` asks the caller to own
-    // the run CA on every exit path — `replayCommand` had no equivalent of the `minted`
-    // wrapper `recordCommand` and `attachCommand` use, so a key outlived every failure
-    // between the mint and the launch.
-    await workspace.release();
-    await mintedCa?.dispose();
-  }
-}
-
-/**
- * The run an exact replay writes about itself, or nothing under `--no-trace`.
- *
- * Spec §4 says every inexact match is an event in the trace, and until now the exact path had no
- * trace to put one in: divergences were printed and discarded with the scrollback. They cannot go
- * into the run being replayed — it is append-only and its manifest carries a digest over
- * events.jsonl, so a single line appended would invalidate every verification anyone had done of
- * it — so the replay becomes a run of its own, pointing back at its subject through `parent_run`.
- * That one field is what `agenticreplay list`, `agenticreplay show` and `agenticreplay gc` already read, which is why it is
- * on the manifest and not only in an event: gc uses it to refuse to delete a run something else
- * still points at.
- *
- * There is no `fork_point`. An exact replay does not branch anywhere, and a fabricated checkpoint
- * would be a number `agenticreplay list` prints as though someone had chosen it.
- *
- * What it deliberately does NOT record is the exchanges it served. Every one of them was read out
- * of the parent's own events.jsonl and handed back byte for byte, so copying them here would
- * duplicate the trace's single largest cost — the conversation bodies, blobs and all — to store a
- * second copy that is identical by construction, and would make `agenticreplay gc` report a store twice the
- * size for one recording's worth of content. An unmatched request is the opposite case: it is
- * something the agent asked that the recording never contained, so it exists nowhere else and is
- * written as an `error` event above. The rule is that this trace holds what replaying *discovered*,
- * and points at the parent for what replaying merely repeated.
- */
-async function openReplayTrace(
-  args: ParsedArgs,
-  ctx: Ctx,
-  cwd: string,
-): Promise<TraceWriter | undefined> {
-  if (!args.bool('trace', true)) return undefined;
-  const dir = await ensureRunsDir(ctx.cwd);
-  return TraceWriter.create(dir, {
-    adapter: ctx.manifest.adapter,
-    argv: ctx.manifest.argv,
-    // Where the replay actually ran, which is not always where the recording did: `--worktree`
-    // puts it in a scratch copy, and `agenticreplay gc` reads exactly this to decide whether the directory
-    // is one of ours to reclaim.
-    cwd,
-    agenticreplayVersion: AGENTICREPLAY_VERSION,
-    parentRun: ctx.manifest.run_id,
-  });
-}
-
-/**
- * Fork replay. Replay deterministically to a checkpoint, materialize the filesystem as it was at
- * that moment, then let the agent continue live — optionally on a different model.
- */
-async function replayFork(
-  args: ParsedArgs,
-  out: Output,
-  ctx: Ctx & { cwd: string; from?: number; model?: string },
-): Promise<ReplayResult> {
-  const checkpoints = deriveCheckpoints(ctx.events);
-  if (checkpoints.length === 0) {
-    throw new Error(
-      'this run has no checkpoints, so there is nothing to fork from\n' +
-        '  checkpoints need a filesystem snapshot; was the run recorded with --no-fs?',
-    );
-  }
-
-  const target = ctx.from ?? checkpoints[checkpoints.length - 1]!.seq;
-  const { checkpoint, snapped } = snapToCheckpoint(checkpoints, target);
-  if (snapped) {
-    // Saying so matters: silently forking from different state than the user asked for is the
-    // worst failure mode this tool has.
-    out.warn('fork.snapped', {
-      requested: target,
-      using: checkpoint.seq,
-      why: 'nearest preceding checkpoint',
-    });
-  }
-
-  // Exchanges are indexed by position, so the fork point in exchange terms is how many model
-  // requests happened at or before the checkpoint.
-  const forkAt = ctx.exchanges.filter((e) => e.seq <= checkpoint.seq).length;
-
-  // Before the worktree and the fork's own run directory, because both of these refuse:
-  // `upstreamPlan` an upstream that is not an origin, `planTlsCapture` a `--tls-hosts` list that
-  // names `*` or contradicts itself and an `AGENTICREPLAY_TLS_UPSTREAM_CA` that cannot be read. Resolved
-  // after them, a typo in any of them left a restored temp tree in `$TMPDIR` that `agenticreplay gc` will
-  // not reclaim — no manifest points at it — and an empty fork in `agenticreplay list`, reading
-  // `FROM <parent>@<n>` as though it had run.
-  const plan = await upstreamPlan(args);
-  // A fork continues a recorded conversation, so it is intercepted on the same terms the
-  // recording was; see `setupTlsCapture` below, which this is the refusing half of.
-  const forkInterceptedHosts = recordedTlsHosts(ctx.events);
-  await planTlsCapture(args, forkInterceptedHosts);
-
-  // Before the worktree too, for the same reason as the two above: this refuses, and refusing
-  // after `mkdtemp` left an empty `agenticreplay-<seq>-*` directory in `$TMPDIR` on every attempt — no
-  // manifest points at it, so `agenticreplay gc` never reclaims it, and nothing printed where it was.
-  let restoreFrom: { fs: FsCapture; tree: string } | undefined;
-  if (checkpoint.fsTree && args.bool('fs', true)) {
-    // Restore from the ORIGINAL run's shadow store: that is the only place the tree object
-    // exists. Pointing a fresh store at the tree id fails to unpack it, which is exactly the
-    // silent-wrong-state failure the checkpoint machinery is meant to prevent.
-    const fs = await FsCapture.start({ runDir: ctx.runDir, cwd: ctx.cwd });
-    // A RUN CAN BE WITHOUT THE STORE ITS OWN EVENTS POINT AT — see `NO_SNAPSHOT_WHY`.
-    //
-    // The line above guards against reading the WRONG store. It cannot guard against there being
-    // no store at all, and `materialize` then died inside git — "failed to unpack tree object
-    // <40 hex>" — which names neither the cause nor anything to do about it, on the exact path the
-    // gateway console tells people to take (`agenticreplay pull <run>` then `agenticreplay compare last --from N`).
-    //
-    // Refusing rather than forking anyway: an empty worktree is not the state the checkpoint
-    // describes, and a fork from the wrong state is the failure this machinery exists to prevent.
-    // `--no-fs` is the way to say "the conversation is what I am forking", and it now leaves the
-    // workspace alone on both ends — this restore and the fork's own capture below.
-    if (!(await fs.hasTree(checkpoint.fsTree))) {
-      // The detail goes in the warning, not the thrown message: `agenticreplay compare` renders each leg's
-      // error in one cell of a table, so anything past the first line is lost exactly where this
-      // is most likely to be read.
-      out.warn('fork.no_snapshot', {
-        seq: checkpoint.seq,
-        tree: checkpoint.fsTree,
-        store: join(ctx.runDir, 'fs'),
-        why: NO_SNAPSHOT_WHY,
-        recorded_in: ctx.manifest.cwd,
-        next: `agenticreplay ${args.command} ${ctx.manifest.run_id} --from ${checkpoint.seq} --no-fs   # fork the conversation, without the workspace`,
-      });
-      throw new Error(
-        `no workspace snapshot for the checkpoint at seq ${checkpoint.seq} — see fork.no_snapshot; --no-fs forks without it`,
-      );
-    }
-    await keepNested(out, fs, checkpoint.fsTree, 'a fresh worktree');
-    restoreFrom = { fs, tree: checkpoint.fsTree };
-  }
-
-  const worktree = await mkdtemp(join(tmpdir(), `agenticreplay-${checkpoint.seq}-`));
-  if (restoreFrom !== undefined) {
-    await restoreFrom.fs.restore(restoreFrom.tree, worktree, { allowIncomplete: true });
-  }
-
-  const dir = await ensureRunsDir(ctx.cwd);
-  const writer = await TraceWriter.create(dir, {
-    adapter: ctx.manifest.adapter,
-    argv: ctx.manifest.argv,
-    cwd: worktree,
-    agenticreplayVersion: AGENTICREPLAY_VERSION,
-    // Also in the manifest, not only the fork event: the manifest is what an out-of-process
-    // reader sees first, and `agenticreplay gc` uses it to decide a parent run may not be deleted.
-    parentRun: ctx.manifest.run_id,
-    forkPoint: checkpoint.seq,
-    ...(ctx.model === undefined ? {} : { forkModel: ctx.model }),
-  });
-
-  const deriver = new ExchangeEventDeriver();
-  let turn = 0;
-  // When each turn began, so an MCP frame drained after the agent exits is attributed to the turn
-  // it happened during rather than to whichever turn happened to be last.
-  const turnStartedAt: { turn: number; at: number }[] = [];
-  const turnAtFork = (at: number): number => {
-    let found = 0;
-    for (const mark of turnStartedAt) {
-      if (mark.at > at) break;
-      found = mark.turn;
-    }
-    return found;
-  };
-  const writes = new SerialQueue();
-
-  /**
-   * The fork's own filesystem capture, over its worktree.
-   *
-   * A fork had none, so its trace carried no `fs.snapshot` — and a checkpoint is derived from a
-   * snapshot (spec §3), so a fork had no checkpoints and could not itself be forked. `agenticreplay compare
-   * last` immediately after a fork failed with "this run has no checkpoints", because `last` had
-   * resolved to the fork. The tool is pitched on iterative exploration; a branch you cannot branch
-   * again is a dead end one step in.
-   *
-   * Same posture as recording: a capture layer that will not start degrades the trace and never
-   * stops the run.
-   */
-  let forkFs: FsCapture | undefined;
-  if (args.bool('fs', true)) {
-    try {
-      // Same widening as the recording's: a fork of a pipeline produces the same kind of
-      // artifact, and a fork whose snapshots omit it is a fork that cannot itself be replayed.
-      const forkArtifacts = defaultAdapters().get(ctx.manifest.adapter.id).artifacts?.capture;
-      forkFs = await FsCapture.start({
-        runDir: writer.runDir,
-        cwd: worktree,
-        ...(forkArtifacts === undefined ? {} : { forced: forkArtifacts }),
-      });
-    } catch (err) {
-      out.warn('fs.unavailable', { reason: String(err) });
-    }
-  }
-
-  // A fork runs a real agent live, so it has exactly the same blind spot `agenticreplay record` does: a
-  // harness that talks to its own backend over TLS reads no base-URL variable and is invisible
-  // without interception. The flag was parsed here and silently discarded, which is the worse
-  // half — the operator believes they captured that traffic.
-  // Same for a fork: it continues a recorded conversation, so its prefix is replayed and the
-  // requests carrying it arrive by the same intercepted transport they were recorded on.
-
-  /** Filled as each is built; see the exact path's pair, which this mirrors. */
-  let mintedCa: RunCa | undefined;
-  let openProxy: { close: () => Promise<void> } | undefined;
-
-  /**
-   * The same two failures `agenticreplay record` had. A listening proxy keeps Node's event loop alive, so
-   * a throw printed the error and then hung; and a fork that mints a certificate authority must
-   * not leave the private key on disk when it dies. The trace is sealed either way, because a
-   * fork that failed to launch is still a fork someone will want to read.
-   *
-   * This used to guard the spawn alone, which is one throw out of five: `RunCa.create` writes the
-   * key, `mcpForReplay` rewrites a config, `createProxy` binds, and `adapter.prepare` runs a
-   * harness's own validation — all of them before the child, all of them leaving the key, the
-   * socket, or both.
-   */
-  async function abandon(err: unknown): Promise<never> {
-    await openProxy?.close().catch(() => undefined);
-    await writes.drain().catch(() => undefined);
-    await mintedCa?.dispose().catch(() => undefined);
-    await writer
-      .append({ type: 'run.end', actor: 'agenticreplay', turn, attrs: { error: String(err) } })
-      .catch(() => undefined);
-    await writer.close().catch(() => undefined);
-    throw err;
-  }
-
-  const tls = await setupTlsCapture({
-    args,
-    out,
-    ...(forkInterceptedHosts ? { recordedHosts: forkInterceptedHosts } : {}),
-    writer,
-    writes,
-    turn: () => turn,
-  }).catch(abandon);
-  mintedCa = tls.ca;
-
-  // A fork continues the run live past the checkpoint, so its MCP traffic is new and belongs in the
-  // fork's own trace. Without this the layer simply stopped at the fork point.
-  const mcp = await mcpForReplay(args, ctx.events, writer, out, undefined, ctx.runDir).catch(
-    abandon,
-  );
-
-  const proxy = await createProxy({
-    mode: 'hybrid',
-    forkAt,
-    forkModel: ctx.model,
-    exchanges: ctx.exchanges,
-    // Past the cursor too: a fork changes which model answers, not what a paragraph embeds to.
-    retrievals: ctx.retrievals,
-    upstream: plan.upstream,
-    upstreamHeaders: plan.headers,
-    upstreamHeadersOrigin: plan.headersOrigin,
-    ...tls.proxyOptions,
-    onExchange: (exchange) => {
-      writes.push(async () => {
-        turn += 1;
-        turnStartedAt.push({ turn, at: Date.now() });
-        await appendDerivedEvents(writer, deriver, exchange, turn);
-        if (forkFs) await appendSnapshot(forkFs, writer, out, turn);
-      });
-    },
-    onRoute: (decision) => {
-      writes.push(async () => {
-        await writer.append({
-          type: 'route.decision',
-          // On a fork the gateway is agenticreplay: it substituted the model and picked what serves it.
-          actor: 'gateway',
-          turn,
-          attrs: { ...decision },
-        });
-      });
-    },
-    onDivergence: (d) => {
-      writes.push(async () => {
-        await writer.append({
-          type: 'divergence',
-          actor: 'agenticreplay',
-          turn,
-          attrs: { level: d.level, rung: d.rung, detail: d.detail, source_seq: d.seq },
-        });
-      });
-    },
-  });
-  // Listening from here on — see the exact path.
-  openProxy = proxy;
-
-  // A fork is a run, and a run opens with run.start (spec §2.3). It opened on `fork` instead, so
-  // the gateway refused every fork on push — "0 run.start and 1 run.end events" — which meant the
-  // output of `agenticreplay compare`, the thing the tool is pitched on, could not be shared with anyone.
-  // `fork` keeps everything that makes it a fork; it just is not the first line any more.
-  await writer.append({
-    type: 'run.start',
-    actor: 'agenticreplay',
-    turn: 0,
-    attrs: {
-      adapter: ctx.manifest.adapter.id,
-      cwd: worktree,
-      proxy: proxy.url,
-      forked_from: ctx.manifest.run_id,
-    },
-  });
-
-  await writer.append({
-    type: 'fork',
-    actor: 'agenticreplay',
-    turn: 0,
-    attrs: {
-      parent_run: ctx.manifest.run_id,
-      fork_point: checkpoint.seq,
-      model: ctx.model ?? ctx.manifest.adapter.id,
-      worktree,
-    },
-  });
-
-  // The state the fork starts from, so its first checkpoint is the checkpoint it branched at
-  // rather than whatever the first live turn happened to leave behind.
-  if (forkFs) await appendSnapshot(forkFs, writer, out, 0, { initial: true });
-
-  out.phase('forked', {
-    from: ctx.manifest.run_id,
-    at: checkpoint.seq,
-    run: writer.runId,
-    model: ctx.model ?? '(unchanged)',
-    worktree,
-  });
-
-  // `defaultAdapters().get` refuses a manifest naming an adapter this build does not have, which
-  // is what replaying a newer agenticreplay's recording looks like from here, and `prepare` is where a
-  // harness validates its own invocation. Both are throws with the proxy already listening.
-  const launch = await (async () => {
-    const adapter = defaultAdapters().get(ctx.manifest.adapter.id);
-    const prepared = await adapter.prepare({
-      runId: writer.runId,
-      cwd: worktree,
-      proxyUrl: proxy.url,
-      runDir: writer.runDir,
-      userArgs: driveArgs(adapter, ctx, out, args),
-      env: process.env,
-    });
-
-    if (proxy.tls) {
-      await trustRunCa(writer, proxy.tls, proxy.url, prepared.env, out);
-    }
-    if (mcp) {
-      pointAtMcpConfig(prepared.env, mcp.configPath);
-      // Same as record: the path has to reach the harness the way the harness actually reads it,
-      // or a replay re-instruments a config nothing opens and every recorded MCP call goes
-      // unmatched.
-      const mcpArgs = adapter.mcpConfigArgs?.(mcp.configPath);
-      if (mcpArgs !== undefined) prepared.args = [...mcpArgs, ...prepared.args];
-    }
-    return prepared;
-  })().catch(abandon);
-
-  const exitCode = await runChild(
-    launch.command,
-    launch.args,
-    { ...process.env, ...launch.env },
-    worktree,
-    agentStdoutFor(args),
-  ).catch(abandon);
-  await writes.drain();
-  if (mcp) await drainMcpFrames(mcp, writer, turnAtFork, turn);
-
-  const stats = proxy.stats();
-  await writer.append({
-    type: 'run.end',
-    actor: 'agenticreplay',
-    turn,
-    attrs: { exit_code: exitCode },
-  });
-  const manifest = await writer.close(exitCode);
-  await proxy.close();
-  await tls.ca?.dispose();
-
-  out.phase('fork.done', {
-    run: writer.runId,
-    replayed: forkAt,
-    live: stats.liveCalls,
-    divergences: stats.divergences,
-    // A fork keeps replaying retrieval past its own cursor, so this says how much of the parent's
-    // index work it reused rather than paid for again. `live` counts chat turns; these are not.
-    ...(stats.retrievalTotal > 0 || stats.retrievalLive > 0
-      ? { retrieval: `${stats.retrievalServed}/${stats.retrievalTotal}` }
-      : {}),
-    events: manifest.counts?.events ?? writer.seq,
-    exit: exitCode,
-  });
-
-  return {
-    runId: ctx.manifest.run_id,
-    traceRunId: writer.runId,
-    forkRunId: writer.runId,
-    worktree,
-    mode: 'fork',
-    canonicalExact: stats.matchedExact,
-    divergences: stats.divergences,
-    unmatched: stats.unmatched,
-    liveCalls: stats.liveCalls,
-    exitCode,
-  };
-}
-
-/** Where an exact replay runs, and how to put the directory back afterwards. */
-interface Workspace {
-  dir: string;
-  /**
-   * Put the working tree back. Idempotent, and called from two places for that reason: once at
-   * the child's launch, where it belongs on the ordinary path, and once from a `finally` around
-   * the whole restored span, which is what makes the guarantee hold for a throw that never
-   * reaches the launch at all.
-   */
-  release: () => Promise<void>;
-  /**
-   * Whether this directory holds the recording's state and will be put back afterwards.
-   *
-   * False for `--in-place`, for a run with no snapshot to restore, and for a replay invoked from
-   * somewhere other than the directory the recording was made in. It gates the one thing a replay
-   * does that is not reversible on its own: deleting an adapter's declared artifacts. AgenticReplay may
-   * delete only what it took a copy of first — anywhere else that would be destroying the
-   * operator's index to reproduce someone else's.
-   */
-  restored: boolean;
-}
-
-const noRelease = async (): Promise<void> => {};
-
-/**
- * Whether two paths name the same directory — asked of the filesystem, not of the strings.
- *
- * Windows gives a process its working directory as it was spelled, so one folder arrives as
- * `C:\proj` from PowerShell and `c:\proj` from cmd or an editor's terminal, or through a junction
- * under another name altogether. Compared as strings, the directory a run was recorded in read as
- * somewhere else, and that is not a cosmetic miss: "elsewhere" skips the safety copy, so the
- * replay ran over the working tree and kept what it wrote there. Measured from cmd: the recorded
- * edit replaced uncommitted work in the very directory the run was made in.
- *
- * `realpath` answers with the name on disk — drive letter, case and links resolved. A path that
- * does not exist here, such as a colleague's, keeps the comparison it always had.
- */
-async function sameDirectory(a: string, b: string): Promise<boolean> {
-  const onDisk = (p: string): Promise<string> => realpath(p).catch(() => resolve(p));
-  return (await onDisk(a)) === (await onDisk(b));
-}
-
-/**
- * Prepare the filesystem an exact replay needs.
- *
- * Two facts decide this, and they pull against each other. A harness reads files into the
- * conversation, so the bytes on disk are inside the recorded request and replaying against a
- * directory the recording itself edited produces a different request. And a harness writes
- * *absolute* paths into its tool calls, so replaying a copy of that directory somewhere else makes
- * the agent read outside its working directory — where it gets a permission refusal in place of
- * the file, which diverges just as badly. Measured on a real Claude Code run: a scratch copy
- * halted at the first tool result; the same trace restored at its own path replayed all six
- * exchanges with nothing unmatched.
- *
- * So the default restores the recorded state *over the working tree*, at the path the run was
- * recorded in. That is only defensible because it is reversible: the current tree is snapshotted
- * into a scratch store first and put back in a `finally`, so a replay is observationally a no-op
- * on your checkout, and the snapshot id is printed before anything is touched in case the process
- * is killed in between.
- *
- * Three ways out. `--worktree` replays in a scratch copy and never touches your files, at the cost
- * of the divergence above. `--in-place` uses the tree exactly as it stands, restoring nothing.
- * And a replay invoked from somewhere other than the directory the run was recorded in never
- * restores, because writing a recorded tree over an unrelated directory is not a thing to do by
- * default.
- */
-async function replayWorkspace(args: ParsedArgs, out: Output, ctx: Ctx): Promise<Workspace> {
-  const artifacts = adapterArtifacts(ctx);
-  // `--worktree` IS A PROMISE — "never touches your files" — so once it is asked for, nothing
-  // below may fall back to the operator's directory. Two branches did, both ahead of the one that
-  // reads it: `--in-place` given beside it won without a word, and a run with no snapshot took the
-  // in-place warning and ran the agent over the working tree anyway. Measured on a run recorded
-  // with --no-fs: `agenticreplay replay last --worktree` wrote the recorded edit over uncommitted work.
-  const wantsWorktree = args.bool('worktree');
-  if (wantsWorktree && args.bool('in-place')) {
-    throw new Error(
-      '--worktree and --in-place cannot both apply: one replays in a scratch copy and never ' +
-        'touches your files, the other replays in them. Give one.',
-    );
-  }
-  if (args.bool('in-place')) {
-    warnArtifactsKept(artifacts, out);
-    return { dir: ctx.cwd, release: noRelease, restored: false };
-  }
-
-  const initial = deriveCheckpoints(ctx.events).find((c) => c.fsTree !== undefined);
-  if (!initial?.fsTree) {
-    // Refused rather than run in an empty directory: an empty directory is not a copy of anything
-    // the run started from, and a replay that halts at the first file it reads is no way to learn
-    // that. `--in-place` is the honest version of what this used to do, and says what it does.
-    if (wantsWorktree) {
-      out.warn('replay.no_snapshot', {
-        why: 'this run was recorded without filesystem capture, so it holds no workspace to copy',
-        next: `agenticreplay replay ${ctx.manifest.run_id} --in-place   # against this directory as it stands`,
-      });
-      throw new Error(
-        'no workspace snapshot to copy — see replay.no_snapshot; --in-place replays without it',
-      );
-    }
-    out.warn('replay.in-place', {
-      why: 'this run has no filesystem snapshot to restore',
-      note: 'recorded with --no-fs; a file the run read may since have changed',
-    });
-    warnArtifactsKept(artifacts, out);
-    return { dir: ctx.cwd, release: noRelease, restored: false };
-  }
-
-  const recorded = await FsCapture.start({ runDir: ctx.runDir, cwd: ctx.cwd });
-
-  if (args.bool('worktree')) {
-    // Both before `mkdtemp`, because either can refuse, and a refusal after it left an empty
-    // `agenticreplay-replay-*` directory in `$TMPDIR` on every attempt: nothing had printed its path yet,
-    // and `agenticreplay gc` never reclaims an exact replay's worktree.
-    await assertSnapshotHeld(out, ctx, recorded, initial.fsTree);
-    await keepNested(out, recorded, initial.fsTree, 'a fresh worktree');
-    // A fresh directory, so there is nothing for a reset to remove: the restore below is the only
-    // thing that puts anything here, and what it puts here is the recording's starting state.
-    const worktree = await mkdtemp(join(tmpdir(), `agenticreplay-replay-${ctx.manifest.run_id}-`));
-    await recorded.restore(initial.fsTree, worktree, { allowIncomplete: true });
-    return { dir: worktree, release: noRelease, restored: true };
-  }
-
-  if (!(await sameDirectory(ctx.cwd, ctx.manifest.cwd))) {
-    out.warn('replay.elsewhere', {
-      recorded_in: ctx.manifest.cwd,
-      running_in: ctx.cwd,
-      note: 'not restoring over a directory the run was not recorded in; use --worktree for a copy',
-    });
-    warnArtifactsKept(artifacts, out);
-    return { dir: ctx.cwd, release: noRelease, restored: false };
-  }
-
-  // BEFORE THE COPY, NOT INSIDE THE TRY BELOW — both of these.
-  //
-  // They refuse without writing a byte, so they have to run while there is still nothing to undo.
-  // Refusing after the safety copy existed meant the catch called `release`, whose `materialize`
-  // refused for the same reason the guard just did — the operator's own tree holds the same
-  // nested repositories — so a replay that had touched nothing printed "your files are in that
-  // store and were not put back" and left a copy of the whole workspace in a temp directory.
-  await assertSnapshotHeld(out, ctx, recorded, initial.fsTree);
-  const keptNested = await assertRestorable(recorded, initial.fsTree, ctx.cwd, artifacts);
-
-  // A store of its own, under the OS temp dir: the safety snapshot is scratch, and writing it into
-  // the trace's shadow store would leave an object in a recorded run that nothing references.
-  const scratch = await mkdtemp(join(tmpdir(), 'agenticreplay-safety-'));
-  // With the adapter's declared artifacts, for the reason the safety snapshot exists at all: the
-  // replay is about to delete those paths (see `resetArtifacts`), and a snapshot that skipped
-  // them because the workspace ignores them would make that deletion permanent. AgenticReplay may delete
-  // only what it has a copy of.
-  const forced = [
-    ...new Set([...(artifacts?.capture ?? []), ...(artifacts?.resetBeforeReplay ?? [])]),
-  ];
-  const safety = await FsCapture.start({
-    runDir: scratch,
-    cwd: ctx.cwd,
-    ...(forced.length === 0 ? {} : { forced }),
-  });
-  const before = await safety.snapshotTurn(0);
-
-  // BOTH TREES, because the gap belongs to whichever of them holds a gitlink.
-  //
-  // `keptNested` is what the *recording* cannot write. What `release` below actually skips is
-  // every gitlink in the *copy of the operator's own tree*, and those are not the same set: a
-  // repository cloned into the workspace since the recording was made is in the second and not
-  // the first. Reporting only the first said nothing about it and then promised, unqualified,
-  // that the files come back — while the replayed agent's writes inside it stayed.
-  const keptHere = await safety.gitlinks(before.tree);
-  // And the ones no snapshot could hold at all. A nested repository with no commit is not a
-  // gitlink — git has no id to record it by — so neither `gitlinks` call can see it, and before
-  // this the safety snapshot did not merely miss it: it threw, and `agenticreplay replay` exited on git's
-  // own sentence about a commit checked out with an `agenticreplay-safety-*` directory left behind. It is
-  // skipped now, which makes it exactly the case these lines are about: agenticreplay holds no copy of
-  // what is inside it.
-  //
-  // And the repositories around a declared artifact path, which the forced add set aside for the
-  // same reason: git stages nothing inside another repository, so neither snapshot holds them.
-  const kept = [
-    ...new Set([
-      ...keptNested,
-      ...keptHere,
-      ...safety.uncommittedNested,
-      ...safety.forcedInsideNested.map((entry) => entry.repository),
-    ]),
-  ].sort();
-
-  // Not "they are left exactly as they are", which is only true of the restore. The replay runs
-  // the recorded agent live in this directory, and agenticreplay does not intercept what it does — so a
-  // recorded build step, generator or `rm` reaches inside these repositories like any other
-  // path, and neither snapshot holds anything of theirs. Said before the agent starts.
-  keepNestedNote(out, kept, {
-    effect:
-      'agenticreplay holds no copy of what is inside them, so whatever this replay does there stays',
-    next: 'replay with --worktree to run the agent somewhere agenticreplay can put back',
-  });
-
-  out.info('replay.restored', {
-    to: initial.fsTree,
-    your_tree: before.tree,
-    // The unqualified sentence is the one the operator acts on, so where it is not true of the
-    // whole tree it does not get to be said of the whole tree.
-    note:
-      kept.length === 0
-        ? 'your files are restored when the replay ends'
-        : `your files are restored when the replay ends, except inside ${kept.join(', ')}`,
-  });
-
-  // Two callers, on purpose — see `Workspace.release`. Restoring twice would be wrong rather than
-  // merely wasteful: the second pass would write the pre-replay tree back over whatever the
-  // caller has done since, and the `rm` would take the scratch with it.
-  let released = false;
-  // Filled in below, before anything is written — see `assertOverwritable`.
-  let introduced: Introduced = { files: [], dirs: [], walked: new Map() };
-  const release = async (): Promise<void> => {
-    if (released) return;
-    released = true;
-    try {
-      // `allowIncomplete`, always — and the gap it tolerates is real, not notional. The nested
-      // repositories this copy holds only as gitlinks are the one part of the tree the replay
-      // can change and this cannot put back, which is why `replay.nested_kept` says so before
-      // the agent starts rather than leaving it to be discovered here.
-      //
-      // Refusing at this point recovers none of that and abandons everything the copy *does*
-      // hold: it left the working tree in the replay's state and the operator's own files in a
-      // scratch directory, which is the one outcome a safety copy exists to prevent.
-      await safety.restore(before.tree, ctx.cwd, { allowIncomplete: true });
-    } catch (err) {
-      // Say where the copy is before rethrowing. This is the one failure after which the scratch
-      // store holds the only copy of the operator's working tree, and until now the path it is at
-      // was printed nowhere — the directory was kept, deliberately, and nothing said so.
-      out.warn('replay.restore_failed', {
-        your_tree: before.tree,
-        copy_at: scratch,
-        note: 'your files are in that store and were not put back; it is not deleted',
-      });
-      throw err;
-    }
-    // What the recording wrote where there was nothing, taken away again — after the put-back, and
-    // only once it has succeeded: the copy never held these, so the put-back alone left them.
-    await removeIntroduced(ctx.cwd, introduced, out);
-    // Only after the restore succeeded. This store holds the only copy of your working tree as
-    // it was before the replay overwrote it, so removing it on the failure path would delete the
-    // thing the failure means you still need — better a directory to clean up by hand than the
-    // one that had your uncommitted work in it.
-    //
-    // Left behind on every run until now: a whole workspace per `agenticreplay replay`, in a directory
-    // `agenticreplay gc` deliberately will not touch because it only reclaims scratch worktrees belonging
-    // to forks. Owning its lifetime here is the fix; teaching gc to delete unknown temp
-    // directories is how gc ends up removing someone's work.
-    await rm(scratch, { recursive: true, force: true });
-  };
-
-  // The destructive step, inside the thing that undoes it.
-  //
-  // A caller cannot guard this one: it happens here, and the `release` that undoes it does not
-  // exist outside this function until this function returns. So a `materialize` that failed
-  // part-way — it is `read-tree` + `checkout-index -a -f` with no rollback of its own, and a
-  // path conflict, EACCES or ENOSPC stops it mid-tree — left the operator holding a mixture of
-  // their files and the recording's, with the only copy of the original in a scratch directory
-  // whose path nothing prints, and no release attempted anywhere.
-  //
-  // With this, the function has one postcondition either way: it returns with the tree replaced
-  // and a `release` that puts it back, or it throws with the tree as it found it. That is what
-  // lets the caller arm its own guard on the line after the call rather than before it.
-  try {
-    // `assertRestorable` ran before the copy above — it is the half that can refuse without
-    // having done anything. This is the other direction: whatever the reset is about to delete
-    // has to be in the copy taken a moment ago, not merely in the recording. It needs the copy,
-    // so it runs here, and its failure is what `release` is for.
-    await assertResettable(safety, ctx.cwd, artifacts);
-    // And the same rule for what the restore overwrites rather than deletes, and for what the
-    // recorded agent writes after it — every tree the run recorded, not only the first. Before
-    // the reset, which is the first thing here that changes the working tree.
-    const trees = deriveCheckpoints(ctx.events).flatMap((c) => (c.fsTree ? [c.fsTree] : []));
-    introduced = await assertOverwritable(recorded, trees, safety, before.tree, ctx.cwd);
-
-    // Before the restore, not after — and that ordering is the whole definition of the reset.
-    // `materialize` writes the tree's files and leaves anything else where it is, so a cache the
-    // recording never had would survive it and the harness would resume from work the recording
-    // did not do. Clearing first and restoring second leaves these paths holding *exactly* what
-    // they held when the recording started, which is the only state the recording can answer for
-    // — including the case where that state was a populated cache, as it is for a recording of
-    // one mid-pipeline stage. Doing it the other way round deleted that stage's own input.
-    await resetArtifacts(ctx.cwd, artifacts, out);
-    // `keptNested`, not `kept`: this writes the *recording's* tree, so the only gaps it can meet
-    // are that tree's own gitlinks. A repository the operator added since is not in it to skip.
-    //
-    // Tolerated only because the guard above has already decided these repositories are not in
-    // anything this replay deletes; where they were, it threw instead of reaching here.
-    await recorded.restore(initial.fsTree, ctx.cwd, {
-      allowIncomplete: keptNested.length > 0,
-    });
-  } catch (err) {
-    // The original failure is the one to report. `release` can fail for its own reasons, and
-    // letting that replace this one told the operator about the cleanup and never about the cause.
-    try {
-      await release();
-    } catch {
-      // `release` has already warned, with the path to the copy it kept.
-    }
-    throw err;
-  }
-
-  return { dir: ctx.cwd, release, restored: true };
-}
-
-/**
- * Why a run's events can name workspace snapshots its own store does not hold.
- *
- * Two ways, and nothing left on disk says which: `agenticreplay pull` of a run pushed without `--fs` — the
- * default, because push will not ship what scrub cannot reach — and `agenticreplay scrub --drop-fs`, which
- * deletes the store and keeps the `fs.snapshot` events that name it. This used to name only the
- * first, and as though it were unconditional ("a gateway archive … never the filesystem
- * snapshots"), which blamed a gateway for a run that had never been near one and hid the way to
- * get the snapshots: a copy pushed with `--fs` restores and replays exactly.
- */
-const NO_SNAPSHOT_WHY =
-  "the run's workspace snapshots are not in its store: a pulled run carries them only if it was pushed with --fs, and agenticreplay scrub --drop-fs deletes them";
-
-/**
- * Refuse a restore the run's own store cannot serve, before anything is written.
- *
- * Asked up front for the reason {@link assertRestorable} is: otherwise the restore dies inside
- * git, "failed to unpack tree object <40 hex>", which is true and names neither the cause nor
- * anything to do about it — the one diagnosis the fork path already gave (`fork.no_snapshot`).
- *
- * Refused, not degraded to `--in-place` the way a run recorded with `--no-fs` is. Both callers
- * were asked for the recorded tree — a scratch copy of it, or it put over the checkout and taken
- * back afterwards — and running the agent over the tree as it stands instead keeps whatever the
- * replay writes, which neither of those does. `--in-place` is one flag away, and says so.
- */
-async function assertSnapshotHeld(
-  out: Output,
-  ctx: Ctx,
-  capture: FsCapture,
-  tree: string,
-): Promise<void> {
-  if (await capture.hasTree(tree)) return;
-  out.warn('replay.no_snapshot', {
-    tree,
-    store: join(ctx.runDir, 'fs'),
-    why: NO_SNAPSHOT_WHY,
-    next: `agenticreplay replay ${ctx.manifest.run_id} --in-place   # against this directory as it stands`,
-  });
-  throw new Error(
-    'no workspace snapshot to restore — see replay.no_snapshot; --in-place replays without it',
-  );
-}
-
-/**
- * Refuse before deleting, rather than from inside the restore that was meant to undo the deletion.
- *
- * Asked of the tree rather than attempted on it: this runs while the operator's artifacts are
- * still on disk, so it has to be free of side effects.
- *
- * **Only the repositories this replay would destroy.** A snapshot records a nested repository as a
- * gitlink and never holds its contents, so a restore cannot put one back — and where the replay
- * deletes the path first, that is the whole of the harm the guard exists for: the reset empties
- * `cache/`, the restore cannot refill it, and a corpus is gone. Where the replay deletes nothing,
- * there is nothing to put back: `materialize` writes the tree's files and leaves everything else
- * alone, so the nested repository is still sitting there when the restore finishes, untouched.
- *
- * Refusing that case turned every recording made in a workspace with a submodule or a vendored
- * checkout into one that could not be replayed at all — and `claude`, like every adapter but
- * `indexrag`, declares no reset paths, so that is every such recording it makes. Issue #103.
- *
- * Returns the ones being left as they are, so the caller can say so and can tell `materialize`
- * that their absence is expected rather than a gap it should refuse over.
- *
- * Exported for the test that pins which of the two it does, for the same reason {@link resetRoots}
- * is: deciding wrongly here costs the operator either a corpus or every replay in the workspace.
- */
-export async function assertRestorable(
-  capture: FsCapture,
-  tree: string,
-  dir: string,
-  artifacts: HarnessArtifacts | undefined,
-): Promise<string[]> {
-  const gitlinks = await capture.gitlinks(tree);
-  if (gitlinks.length === 0) return [];
-  const roots = resetRoots(dir, artifacts);
-  // Containment in BOTH directions, because the reset is destructive either way — see
-  // `reachedByReset`, which `assertResettable` asks the same question of for a repository with no
-  // commit, since neither this guard nor `uncaptured` can see one.
-  const doomed = gitlinks.filter((path) => reachedByReset(path, roots));
-  if (doomed.length === 0) return gitlinks;
-  throw new Error(
-    `this replay would delete ${roots.join(', ')} to put the harness back where the recording ` +
-      `started, and cannot put ${doomed.join(', ')} back: the snapshot holds those as embedded ` +
-      'git repositories, whose contents it never captured — whether the reset removes one ' +
-      'outright or reaches inside it. Nothing has been deleted. Move them ' +
-      'outside the adapter’s reset paths, or replay with --in-place to leave the working tree ' +
-      'alone.',
-  );
-}
-
-/**
- * Compare paths the way the filesystem underneath them does.
- *
- * `rm -rf <dir>/Cache` removes `cache` on Windows, and git treats the two as one path there,
- * so a case-sensitive prefix test calls a corpus safe and then deletes it. Folded on the
- * platforms whose filesystems are case-insensitive by default; erring that way costs at worst
- * a replay refused on a case-sensitive APFS volume, and erring the other way costs the corpus.
- */
-function fold(path: string): string {
-  return process.platform === 'win32' || process.platform === 'darwin' ? path.toLowerCase() : path;
-}
-
-/**
- * Whether resetting `roots` reaches `path`, in either direction.
- *
- * `path` inside a root is the obvious half: the thing sits in a directory being deleted.
- * A root inside `path` is the half that reads backwards and matters just as much — a multi-segment
- * declaration such as `resetBeforeReplay: ['data/cache']` with a nested repository at `data`
- * deletes a path *inside* the operator's own repository.
- *
- * Whole segments, so `data2` is not read as being inside `data`; folded where the filesystem folds,
- * so `Data` is not read as being somewhere else. Shared by the two guards that have to agree about
- * it — {@link assertRestorable} for a repository the snapshot holds as a gitlink, and
- * {@link assertResettable} for one it could not hold at all.
- */
-function reachedByReset(path: string, roots: readonly string[]): boolean {
-  const one = fold(path);
-  return roots.some((root) => {
-    const other = fold(root);
-    return one === other || one.startsWith(`${other}/`) || other.startsWith(`${one}/`);
-  });
-}
-
-/**
- * Say which nested repositories a restore cannot write, and what that costs here.
- *
- * `effect` differs by caller because the consequence does: a fork writes into a directory of its
- * own, where the repository is simply missing and the operator's copy is never in reach. An
- * in-place replay runs the agent over the operator's own tree, where it is very much in reach and
- * agenticreplay cannot put it back.
- */
-function keepNestedNote(
-  out: Output,
-  paths: readonly string[],
-  fields: { effect: string; next?: string },
-): void {
-  if (paths.length === 0) return;
-  out.warn('replay.nested_kept', {
-    paths: paths.join(','),
-    why: 'these are git repositories of their own, and the snapshot never held their contents — recorded as a reference, or, with no commit to reference, not at all',
-    ...fields,
-  });
-}
-
-/** The same note, for the restores that write into a directory of their own. */
-async function keepNested(
-  out: Output,
-  capture: FsCapture,
-  tree: string,
-  where: string,
-): Promise<void> {
-  keepNestedNote(out, await capture.gitlinks(tree), {
-    effect: `they are absent from ${where}`,
-  });
-}
-
-/** What the adapter that made this recording says about its own artifacts, if anything. */
-function adapterArtifacts(ctx: {
-  manifest: { adapter: { id: string } };
-}): HarnessArtifacts | undefined {
-  try {
-    return defaultAdapters().get(ctx.manifest.adapter.id).artifacts;
-  } catch {
-    // A trace naming an adapter this build does not have. The replay fails on that later, with a
-    // better message than one from here; nothing about the workspace should depend on it.
-    return undefined;
-  }
-}
-
-/**
- * Delete the artifacts the harness resumes from, so the replay starts where the recording did.
- *
- * A pipeline picks up where it left off: it reads its own cache, sees which items are finished
- * and does the rest. Replayed on top of the recording's *completed* cache it does nothing — no
- * request is made, nothing is matched, and the replay reports having reproduced a run it never
- * ran. `reused=0/6 exit=0` is what that looks like, and it reads as a broken recording.
- *
- * Whole paths, never "the parts that look invalid". IndexRAG's resume skips by `chunk_id`
- * including entries whose recorded outcome was a failure, so keeping what looks valid promotes
- * the previous run's failures to completed work — a subtler wrong answer than the one being
- * fixed. The workspace is restored afterwards, which is what makes deleting acceptable at all,
- * and `workspace.restored` is the gate: agenticreplay deletes only where it took a copy first.
- */
-async function resetArtifacts(
-  dir: string,
-  artifacts: HarnessArtifacts | undefined,
-  out: Output,
-): Promise<void> {
-  const removed: string[] = [];
-  for (const root of resetRoots(dir, artifacts)) {
-    await rm(resolve(dir, root), { recursive: true, force: true });
-    removed.push(root);
-  }
-  if (removed.length > 0) {
-    out.info('replay.artifacts_reset', {
-      paths: [...new Set(removed)].join(','),
-      why: 'the harness resumes from these, so they are put back to the recording’s starting state',
-      note: 'your files are restored when the replay ends',
-    });
-  }
-}
-
-/**
- * The paths {@link resetArtifacts} will actually remove.
- *
- * The declared path itself, with a trailing glob stripped — `cache/**` is a declaration about
- * `cache`, and a glob suffix is the only part of a pattern this can act on without a glob library.
- *
- * Not the pattern's *first segment*, which is what this took before. Nothing constrains a
- * declaration to one segment — `resetBeforeReplay` is `readonly string[]` and the plugin docs call
- * it "whole paths" — so an adapter declaring `data/cache` had `rm -rf <cwd>/data` run against the
- * operator's working directory. That deletion is wider than the copy meant to reverse it: only
- * `data/cache` is force-staged, and the rest of `data/` is in the safety tree only if the workspace
- * does not ignore it — and a workspace that ignores its pipeline's product directory is the entire
- * reason `artifacts.capture` exists. `data/raw-inputs/` would have been deleted permanently, under
- * a message saying the files come back when the replay ends.
- *
- * Shared with the check that runs before the removal, so the two cannot disagree about what is
- * about to be deleted — a guard looking at a different set from the `rm` would be worse than none.
- */
-export function resetRoots(dir: string, artifacts: HarnessArtifacts | undefined): string[] {
-  const roots: string[] = [];
-  for (const pattern of artifacts?.resetBeforeReplay ?? []) {
-    const declared = pattern.replace(/[\\/]+\*{1,2}$/, '').replace(/[\\/]+$/, '');
-    if (declared === '' || declared === '.' || declared === '..' || declared.includes('*'))
-      continue;
-    // Never outside the workspace, whatever an adapter declares.
-    const resolved = resolve(dir, declared);
-    if (!isInsideDir(dir, resolved)) continue;
-    // Through `resolve` and back, so what leaves here is the path the deletion will act on
-    // rather than the spelling the adapter happened to use. `./cache`, `data//cache` and
-    // `tools/../cache` all reach `rm` as one path and have to leave here as one too: the
-    // guard below compares these strings, and a guard looking at a different set from the
-    // `rm` is worse than none. Forward slashes, since this is also a `git ls-files` pathspec.
-    const root = relative(dir, resolved).split(/[\\/]/).join('/');
-    if (root === '') continue;
-    roots.push(root);
-  }
-  return [...new Set(roots)];
-}
-
-/** What a restore will write where the working tree holds nothing, for the put-back to remove. */
-export interface Introduced {
-  /** Each with the ids of every version of it the recording holds, to know it again by. */
-  files: { path: string; oids: ReadonlySet<string> }[];
-  /** Directories it has to create for them, deepest first, so each is empty when its turn comes. */
-  dirs: string[];
-  /**
-   * The links on the way to these files that git walked into as directories when it took the copy
-   * — a junction, on Windows — and that were links then, each with where it pointed. The removal
-   * may pass through real directories and through these, while each still points there, and
-   * through nothing else.
-   */
-  walked: ReadonlyMap<string, string>;
-}
-
-/**
- * Refuse the reset unless the safety copy holds everything the reset is about to delete.
- *
- * `assertRestorable` asks whether the *recording's* tree can be written back. This asks the other
- * half, and it is the half that owns the operator's files: `resetArtifacts` deletes whole
- * directories, and the only thing that can put back what was in them and not in the recording is
- * the safety snapshot taken moments earlier. That snapshot is not unconditionally complete. The
- * sensitive pathspecs are applied to its forced add as well — rightly; they are what stops an
- * adapter sweeping a credential into a trace — and a nested repository inside a declared path is
- * dropped because no snapshot can hold one. Both are deliberate, and both mean the copy is missing
- * something the `rm` would take: an `.env` the operator keeps beside a cache, a prebuilt store
- * cloned into `vector_store/`. Neither need appear in the recording's tree at all, since the
- * operator may have put it there afterwards, so the other guard passes and the loss is permanent
- * and silent.
- *
- * Refusing rather than warning, because there is no second chance after the `rm`, and the rule this
- * replay is operating under says so in as many words: agenticreplay deletes only what it took a copy of
- * first. In the ordinary run nothing under these paths is excluded and this asks git one question
- * and moves on.
- */
-export async function assertResettable(
-  safety: FsCapture,
-  dir: string,
-  artifacts: HarnessArtifacts | undefined,
-): Promise<void> {
-  const roots = resetRoots(dir, artifacts);
-  if (roots.length === 0) return;
-
-  // THE SAME RULE, FOR THE NESTED REPOSITORIES NO SNAPSHOT NAMES AS GITLINKS.
-  //
-  // `assertRestorable` asks this of the recording's gitlinks, before anything is copied. Two kinds
-  // of repository are in no tree, so that guard cannot see them — and the `uncaptured` question
-  // below cannot either: `ls-files --others -- data/cache` does not descend into an embedded
-  // repository, so a reset root INSIDE one comes back empty (measured: empty for `data/cache`,
-  // `data/` for `data`). So the direction the other guard needs `root.startsWith(path)` for is the
-  // one that gets through here, for both:
-  //
-  //   - one with no commit, which git cannot record at all (`uncommittedNested`)
-  //   - one around a declared path, which the forced add sets aside rather than hand to git
-  //     (`forcedInsideNested`). Measured before it did: with `data/` ignored, `add -f -- data/cache`
-  //     exited 0 having staged nothing, and the reset then deleted the operator's `data/cache`
-  //     under exit 0 and "your files are restored when the replay ends" — committed or not.
-  //
-  // It has to be asked HERE because this is the first thing holding a snapshot of the operator's
-  // own tree, which is the only place either kind is ever named.
-  const unheld = [
-    ...safety.uncommittedNested,
-    ...safety.forcedInsideNested.map((entry) => entry.repository),
-  ];
-  const reached = [...new Set(unheld)].filter((path) => reachedByReset(path, roots)).sort();
-  if (reached.length > 0) {
-    // Not "commit inside them", which this said before and which never helped: a committed
-    // repository is a gitlink, whose contents no snapshot holds either, so the same reset is
-    // refused the same way.
-    throw new Error(
-      `this replay would delete ${roots.join(', ')} to put the harness back where the recording ` +
-        `started, and cannot put ${reached.join(', ')} back: those are git repositories of their ` +
-        'own, and no snapshot holds a byte of what is inside them — whether the reset removes one ' +
-        'outright or reaches inside it. Nothing has been deleted. Move those repositories clear of ' +
-        'the adapter’s reset paths, or replay with --in-place to leave the working tree alone.',
-    );
-  }
-
-  const missing = await safety.uncaptured(roots);
-  if (missing.length === 0) return;
-  const shown = missing.slice(0, 5).join(', ');
-  const rest = missing.length > 5 ? `, and ${missing.length - 5} more` : '';
-  throw new Error(
-    `this replay would delete ${roots.join(', ')} to put the harness back where the recording ` +
-      `started, and the copy agenticreplay took first does not hold ${shown}${rest} — a nested git ` +
-      'repository, or a path the sensitive-file rules keep out of every snapshot. AgenticReplay deletes ' +
-      'only what it has a copy of, so nothing has been deleted. Move those out of the reset ' +
-      'paths, or replay with --in-place to leave the working tree alone.',
-  );
-}
-
-/**
- * Refuse the restore unless the safety copy holds every file it is about to overwrite — and name
- * the files it will write where the operator has none. Exported for the test that pins what the
- * removal may walk through.
- *
- * `materialize` writes each file the recorded tree holds, whatever is at that path. The copy it is
- * undone from is an ordinary snapshot, which honours the workspace's `.gitignore`, so a path the
- * recording tracked and the workspace ignores now was overwritten with the recorded bytes, and the
- * put-back had nothing to put back. Measured: a `settings.json` moved into `.gitignore` after the
- * recording, holding the operator's local settings, came out of `agenticreplay replay` holding the
- * recording's, under "your files are restored when the replay ends" — and neither git nor agenticreplay
- * held the original anywhere. The rule `assertResettable` enforces for a delete holds for an
- * overwrite: agenticreplay destroys only what it took a copy of first.
- *
- * The same listing settles the other half of that sentence. A file the recorded tree holds and the
- * working tree does not — deleted since, say — is written by the restore, and the put-back, whose
- * copy never had it, left it there: a replay brought back a config the operator had removed and
- * committed the removal of. Those are returned for the put-back to take away again. AgenticReplay put them
- * there, and nothing of the operator's was at those paths when it did.
- *
- * EVERY TREE THE RUN RECORDED, not only the one the restore writes. An exact replay makes the
- * recorded agent do what it did, so the files it wrote are in the later checkpoints: one it
- * created came back with the replay and stayed after the put-back, like the restore's own, and
- * one it overwrote that the copy does not hold is lost to the agent exactly as it would be to the
- * restore. Both are answered the same way.
- *
- * Asked before `resetArtifacts`: the reset deletes what the copy holds, and an artifact would look
- * absent after it. Artifacts are forced into the copy, so neither list can name one.
- */
-export async function assertOverwritable(
-  recorded: FsCapture,
-  trees: readonly string[],
-  safety: FsCapture,
-  held: string,
-  dir: string,
-): Promise<Introduced> {
-  const copied = new Set((await safety.files(held)).map((file) => fold(file.path)));
-  // What is on disk at a path, asked once per path. A path this process cannot even look at counts
-  // as something there: nothing here may conclude "safe to overwrite" from an error it cannot read.
-  const seen = new Map<string, 'dir' | 'other' | 'none'>();
-  const at = (path: string): 'dir' | 'other' | 'none' => {
-    let kind = seen.get(path);
-    if (kind === undefined) {
-      try {
-        kind = lstatSync(join(dir, path)).isDirectory() ? 'dir' : 'other';
-      } catch (err) {
-        const code = (err as NodeJS.ErrnoException).code;
-        kind = code === 'ENOENT' || code === 'ENOTDIR' ? 'none' : 'other';
-      }
-      seen.set(path, kind);
-    }
-    return kind;
-  };
-  const absent = (path: string): boolean => at(path) === 'none';
-  // Every directory git walked into when it took the copy. A link among them — a junction, on
-  // Windows, whose contents the copy holds as ordinary files — is a directory as far as the
-  // restore and the put-back are concerned, and is treated as one here.
-  const intoCopy = new Set<string>();
-  for (const held of copied) {
-    const parts = held.split('/');
-    for (let i = 1; i < parts.length; i += 1) intoCopy.add(parts.slice(0, i).join('/'));
-  }
-  // What the restore would destroy to write `path`, asked the way it writes: every directory on
-  // the way first, then the path itself. A file or a link standing where the recording has a
-  // directory is destroyed to make the directory — and the error from asking for the path under it
-  // does not say so, since POSIX answers ENOTDIR there and Windows answers ENOENT, exactly as for a
-  // path under nothing at all. Undefined when nothing is in the way.
-  const inTheWay = (path: string): string | undefined => {
-    const parts = path.split('/');
-    for (let i = 1; i < parts.length; i += 1) {
-      const prefix = parts.slice(0, i).join('/');
-      const kind = at(prefix);
-      if (kind === 'none') return undefined;
-      if (kind === 'other' && !intoCopy.has(fold(prefix))) return prefix;
-    }
-    return absent(path) ? undefined : path;
-  };
-  const overwritten = new Set<string>();
-  const files: Introduced['files'] = [];
-  const recordedFiles = new Map<string, Set<string>>();
-  for (const tree of new Set(trees)) {
-    for (const { path, oid } of await recorded.files(tree)) {
-      const oids = recordedFiles.get(path) ?? new Set<string>();
-      oids.add(oid);
-      recordedFiles.set(path, oids);
-    }
-  }
-  for (const [path, oids] of recordedFiles) {
-    if (copied.has(fold(path))) continue;
-    const blocker = inTheWay(path);
-    if (blocker === undefined) files.push({ path, oids });
-    // Held: the put-back writes it back, clearing the directory the restore made in its place.
-    else if (blocker !== path && copied.has(fold(blocker))) continue;
-    else overwritten.add(blocker);
-  }
-  if (overwritten.size > 0) {
-    const listed = [...overwritten].sort();
-    const shown = listed.slice(0, 5).join(', ');
-    const rest = listed.length > 5 ? `, and ${listed.length - 5} more` : '';
-    throw new Error(
-      `this replay would overwrite ${shown}${rest}: your tree has them and the copy agenticreplay took ` +
-        'first does not — the workspace ignores them, or they sit in a nested repository — so ' +
-        'nothing could put them back. Nothing has been changed. Move them aside, or replay with ' +
-        '--worktree to leave the working tree alone.',
-    );
-  }
-  const parents = new Set<string>();
-  for (const file of files) {
-    const parts = file.path.split('/');
-    for (let i = 1; i < parts.length; i += 1) parents.add(parts.slice(0, i).join('/'));
-  }
-  const dirs: string[] = [];
-  for (const parent of parents) if (absent(parent)) dirs.push(parent);
-  dirs.sort((a, b) => b.split('/').length - a.split('/').length);
-  // What the removal may pass through besides real directories: the links on the way to these
-  // files that git walked into — asked now, while the tree is still the operator's. Not every
-  // directory git walked into: a real one there now could be a link by the time the removal runs,
-  // and a path that was a directory when the copy was taken is no licence to follow a link there.
-  // Where each pointed, too: a link re-pointed by the time the removal runs is another link, and
-  // following it could leave the workspace as surely as following a new one.
-  const walked = new Map<string, string>();
-  for (const parent of parents) {
-    if (!intoCopy.has(fold(parent))) continue;
-    try {
-      const at = join(dir, parent);
-      if (lstatSync(at).isSymbolicLink()) walked.set(fold(parent), readlinkSync(at));
-    } catch {
-      // Gone, or not ours to look at: nothing to walk through.
-    }
-  }
-  return { files, dirs, walked };
-}
-
-/**
- * Take away what the recording put where the operator had nothing — and only that.
- *
- * Asked of each file as it stands now, not as it stood when the list was made. The replayed agent
- * has run since, for minutes with a real harness, in a tree nothing else was told to keep out of:
- * the operator's own new file, a watcher's output, or a replay that went its own way can be at one
- * of these paths by now, and these are exactly the paths no copy holds. So a file goes only while
- * its bytes are a version the recording holds for that path — what the restore wrote, or what the
- * recorded agent wrote after it. Anything else is left where it is, and named.
- *
- * `rmdir` takes a directory only while it is empty, so one that something else wrote into stays,
- * with what it wrote. Exported for the test that pins which files it will not take; `judging` is
- * that test's way in to the moment a file is being judged, and nothing in agenticreplay passes one.
- */
-export async function removeIntroduced(
-  dir: string,
-  introduced: Introduced,
-  out: Output,
-  judging?: (path: string) => void | Promise<void>,
-): Promise<void> {
-  const kept: string[] = [];
-  const setAside: string[] = [];
-  for (const file of introduced.files) {
-    if (!onlyThroughDirectories(dir, file.path, introduced.walked)) continue;
-    const suffix = `.agenticreplay-${randomBytes(4).toString('hex')}`;
-    const outcome = await takeIfRecorded(join(dir, file.path), suffix, file.oids, judging);
-    if (outcome === 'kept') kept.push(file.path);
-    else if (outcome === 'set-aside') setAside.push(`${file.path}${suffix}`);
-  }
-  for (const made of introduced.dirs) {
-    if (!onlyThroughDirectories(dir, made, introduced.walked)) continue;
-    try {
-      rmdirSync(join(dir, made));
-    } catch {
-      // Not empty: something wrote into it that is not agenticreplay's to take.
-    }
-  }
-  if (kept.length > 0 || setAside.length > 0) {
-    out.warn('replay.left_in_place', {
-      paths: kept.length > 0 ? kept.sort().join(',') : undefined,
-      set_aside: setAside.length > 0 ? setAside.sort().join(',') : undefined,
-      why: 'agenticreplay takes away only what it can show it put there, and could not show it of these — written since by something else, or in use where they could not be moved',
-      next: 'delete them yourself if they are not yours; set_aside names ones whose path was taken while they were being judged',
-    });
-  }
-}
-
-/**
- * Remove the file at `target` if, and only if, it holds one of `oids` — judged on the very file that
- * goes. Hashing a path and then removing the path looks it up twice, and a writer that replaces
- * the file in between would have its bytes removed unjudged. Renamed aside first, the file is
- * pinned: the rename is atomic, and what is hashed is what is removed. A file written at the path
- * a moment later is a new file there, which this never touches.
- *
- * One that does not match goes back where it was — without replacing anything that has taken the
- * path meanwhile. Then it stays beside it under the name it was set aside as, and is named.
- */
-async function takeIfRecorded(
-  target: string,
-  suffix: string,
-  oids: ReadonlySet<string>,
-  judging?: (path: string) => void | Promise<void>,
-): Promise<'absent' | 'taken' | 'kept' | 'set-aside'> {
-  try {
-    if (lstatSync(target).isDirectory()) return 'kept';
-  } catch {
-    return 'absent';
-  }
-  const aside = `${target}${suffix}`;
-  try {
-    renameSync(target, aside);
-  } catch (err) {
-    // Gone in the meantime, or held open where the platform will not move it: not taken either way.
-    return (err as NodeJS.ErrnoException).code === 'ENOENT' ? 'absent' : 'kept';
-  }
-  await judging?.(target);
-  // A file that cannot even be read is not one agenticreplay can show it wrote — and throwing here would
-  // leave it under the name it was set aside as. Back where it was, like any other.
-  const now = await blobId(aside, oids).catch(() => undefined);
-  if (now !== undefined && oids.has(now)) {
-    try {
-      unlinkSync(aside);
-      return 'taken';
-    } catch {
-      // Could not remove it: put it back rather than leave it under a name nobody knows.
-    }
-  }
-  return putBack(aside, target) ? 'kept' : 'set-aside';
-}
-
-/**
- * Move `aside` back to `target` unless something is at `target` now — and decide that atomically.
- * Checking the path and then renaming onto it is a race the rename loses: on POSIX `rename`
- * replaces whatever arrived in between, which is the very write this exists to keep. So every way
- * back is a primitive that creates only if absent, and fails on EEXIST: a hard link for a file; a
- * fresh `symlink` for a link, which `link` would follow on some platforms (macOS); and, where the
- * filesystem has no hard links, a copy opened with O_EXCL.
- */
-function putBack(aside: string, target: string): boolean {
-  try {
-    if (lstatSync(aside).isSymbolicLink()) {
-      const to = readlinkSync(aside);
-      const junction = process.platform === 'win32' && isDirectory(aside);
-      symlinkSync(to, target, junction ? 'junction' : undefined);
-    } else {
-      try {
-        linkSync(aside, target);
-      } catch (err) {
-        if ((err as NodeJS.ErrnoException).code === 'EEXIST') return false;
-        copyFileSync(aside, target, fsConstants.COPYFILE_EXCL);
-      }
-    }
-  } catch {
-    // EEXIST among them: something has the path now, and this file stays beside it, named.
-    return false;
-  }
-  try {
-    unlinkSync(aside);
-  } catch {
-    // Two names for one file: the one the operator knows is back, which is what matters.
-  }
-  return true;
-}
-
-/** Whether `path` leads to a directory, following links; false when it leads nowhere. */
-function isDirectory(path: string): boolean {
-  try {
-    return statSync(path).isDirectory();
-  } catch {
-    return false;
-  }
-}
-
-/**
- * The git blob id of what stands at `path` now — the id `ls-tree` reports for the same bytes, in
- * the object format `like` is in. Undefined when nothing is there; something that is neither a
- * file nor a link gets an id no blob has, so it is never taken for one.
- */
-async function blobId(path: string, like: ReadonlySet<string>): Promise<string | undefined> {
-  let st: ReturnType<typeof lstatSync>;
-  try {
-    st = lstatSync(path);
-  } catch {
-    return undefined;
-  }
-  const sample = like.values().next().value;
-  const hash = createHash(sample !== undefined && sample.length === 64 ? 'sha256' : 'sha1');
-  if (st.isSymbolicLink()) {
-    const target = readlinkSync(path, { encoding: 'buffer' });
-    hash.update(`blob ${target.length}\0`).update(target);
-  } else if (st.isFile()) {
-    hash.update(`blob ${st.size}\0`);
-    for await (const chunk of createReadStream(path)) hash.update(chunk as Buffer);
-  } else {
-    return 'not a file';
-  }
-  return hash.digest('hex');
-}
-
-/**
- * Whether removing `file` under `dir` stays inside the tree: every directory on the way a real one,
- * or a link git walked into when it took the copy that still points where it pointed then. Asked
- * at removal time, because a link can have appeared on the way since, or been re-pointed — the
- * replayed agent may have done either — and `rm` follows it wherever it points now.
- */
-function onlyThroughDirectories(
-  dir: string,
-  file: string,
-  walked: ReadonlyMap<string, string>,
-): boolean {
-  const parts = file.split('/');
-  for (let i = 1; i < parts.length; i += 1) {
-    const prefix = parts.slice(0, i).join('/');
-    const at = join(dir, prefix);
-    try {
-      const st = lstatSync(at);
-      if (st.isDirectory()) continue;
-      const then = walked.get(fold(prefix));
-      if (!st.isSymbolicLink() || then === undefined || readlinkSync(at) !== then) return false;
-    } catch {
-      return false;
-    }
-  }
-  return true;
-}
-
-/** The `--in-place` half of the same rule: say what was not done, rather than doing it unsafely. */
-function warnArtifactsKept(artifacts: HarnessArtifacts | undefined, out: Output): void {
-  const paths = artifacts?.resetBeforeReplay ?? [];
-  if (paths.length === 0) return;
-  out.warn('replay.artifacts_kept', {
-    paths: paths.join(','),
-    why: 'this replay is not restoring the working tree, so agenticreplay has no copy to put back',
-    effect:
-      'the harness may resume from artifacts the recording had not produced yet and ask nothing',
-    next: 'replay without --in-place, or clear them yourself',
-  });
-}
-
-/** Whether `target` is `dir` or sits under it, by the platform's own path rules. */
-function isInsideDir(dir: string, target: string): boolean {
-  const rel = relative(resolve(dir), target);
-  return rel !== '' && !rel.startsWith('..') && !isAbsolute(rel);
-}
-
-/** Where the replayed agent's own stdout should go, given the flags. */
-function agentStdoutFor(args: ParsedArgs): 'inherit' | 'stderr' | 'ignore' {
-  if (args.bool('quiet')) return 'ignore';
-  return args.bool('json') ? 'stderr' : 'inherit';
-}
-
-/**
- * Launch the agent for a replay or a fork.
- *
- * Where the replayed agent's own stdout goes:
- *
- *   inherit  the default — you asked to watch the run happen again, so you watch it
- *   stderr   `--json`: agenticreplay's stdout is the result document, so the agent's output moves aside
- *            rather than landing in the middle of it
- *   ignore   `--quiet`: the run is being replayed for its verdict, not for its narration
- *
- * stdin and stderr stay inherited in every case, so a harness that prompts still can and a
- * harness that fails still says why.
- */
-async function runChild(
-  command: string,
-  argv: string[],
-  env: NodeJS.ProcessEnv,
-  cwd = process.cwd(),
-  agentStdout: 'inherit' | 'stderr' | 'ignore' = 'inherit',
-): Promise<number> {
-  // Same resolution as record and as detection; see resolveLaunch.
-  const target = await resolveLaunch(command, argv);
-  return new Promise((resolve, reject) => {
-    const child = spawn(target.file, target.args, {
-      env,
-      cwd,
-      shell: target.shell,
-      stdio:
-        agentStdout === 'inherit'
-          ? 'inherit'
-          : ['inherit', agentStdout === 'ignore' ? 'ignore' : 'pipe', 'inherit'],
-    });
-    if (agentStdout === 'stderr') child.stdout?.pipe(process.stderr);
-    child.on('error', (err) =>
-      reject(new Error(`could not launch "${command}": ${String(err)}\n  is it on your PATH?`)),
-    );
-    child.on('close', (code) => resolve(code ?? 0));
-  });
-}