agenticreplay 0.1.0 → 0.1.2

package/packages/fs-capture/test/shadow.test.ts

@@ -1,1058 +0,0 @@
-import {
-  chmod,
-  lstat,
-  mkdir,
-  readFile,
-  readlink,
-  rename,
-  rm,
-  stat,
-  symlink,
-  writeFile,
-} from 'node:fs/promises';
-import { join } from 'node:path';
-import { afterAll, describe, expect, it } from 'vitest';
-import type { FileChange } from '../src/index.js';
-import { EMPTY_TREE, ShadowIndex, gitAvailable, runGit } from '../src/index.js';
-import { cleanupTempDirs, listFilesRecursive, makeTempDir } from './helpers.js';
-
-const hasGit = await gitAvailable();
-const itGit = it.skipIf(!hasGit);
-
-afterAll(cleanupTempDirs);
-
-interface Fixture {
-  root: string;
-  workTree: string;
-  gitDir: string;
-  shadow: ShadowIndex;
-}
-
-async function fixture(): Promise<Fixture> {
-  const root = await makeTempDir();
-  const workTree = join(root, 'ws');
-  const gitDir = join(root, 'run', 'fs');
-  await mkdir(workTree, { recursive: true });
-  const shadow = await ShadowIndex.create({ gitDir, workTree });
-  return { root, workTree, gitDir, shadow };
-}
-
-async function write(dir: string, rel: string, content: string | Uint8Array): Promise<void> {
-  const full = join(dir, rel);
-  await mkdir(join(full, '..'), { recursive: true });
-  await writeFile(full, content);
-}
-
-function byPath(changes: FileChange[], path: string): FileChange {
-  const found = changes.find((change) => change.path === path);
-  if (!found) throw new Error(`no change for ${path} in ${JSON.stringify(changes)}`);
-  return found;
-}
-
-async function filesIn(shadow: ShadowIndex, tree: string): Promise<string[]> {
-  const changes = await shadow.diff(EMPTY_TREE, tree);
-  return changes.map((change) => change.path).sort();
-}
-
-describe('ShadowIndex.create', () => {
-  itGit('initialises a shadow git dir without creating a .git in the workspace', async () => {
-    const { workTree, gitDir } = await fixture();
-    expect((await stat(join(gitDir, 'objects'))).isDirectory()).toBe(true);
-    expect((await stat(join(gitDir, 'info', 'exclude'))).isFile()).toBe(true);
-    expect(await listFilesRecursive(workTree)).toEqual([]);
-  });
-
-  itGit('is idempotent over an existing shadow dir', async () => {
-    const { workTree, gitDir } = await fixture();
-    await write(workTree, 'a.txt', 'one\n');
-    const first = await (await ShadowIndex.create({ gitDir, workTree })).snapshot();
-    const second = await (await ShadowIndex.create({ gitDir, workTree })).snapshot();
-    expect(second).toBe(first);
-  });
-
-  itGit('throws an actionable error when git is missing', async () => {
-    const root = await makeTempDir();
-    const saved = process.env.PATH;
-    process.env.PATH = join(root, 'empty');
-    try {
-      await expect(
-        ShadowIndex.create({ gitDir: join(root, 'fs'), workTree: root }),
-      ).rejects.toThrow(/git is required for filesystem capture.*--no-fs/s);
-    } finally {
-      process.env.PATH = saved;
-    }
-  });
-
-  itGit('reports availability', async () => {
-    expect(await ShadowIndex.isAvailable()).toBe(true);
-  });
-});
-
-describe('snapshot', () => {
-  itGit('snapshots an empty directory as the empty tree', async () => {
-    const { shadow } = await fixture();
-    expect(await shadow.snapshot()).toBe(EMPTY_TREE);
-  });
-
-  itGit('is content addressed: no changes yields the same tree sha', async () => {
-    const { workTree, shadow } = await fixture();
-    await write(workTree, 'a.txt', 'stable\n');
-    await write(workTree, 'nested/b.txt', 'also stable\n');
-    const first = await shadow.snapshot();
-    const second = await shadow.snapshot();
-    expect(first).toMatch(/^[0-9a-f]{40}$/);
-    expect(second).toBe(first);
-  });
-
-  itGit('leaves the workspace and its real git repo untouched', async () => {
-    const { workTree, shadow } = await fixture();
-    await runGit(['init', '-q'], { cwd: workTree });
-    await write(workTree, 'tracked.txt', 'hi\n');
-    const before = await runGit(['status', '--porcelain'], { cwd: workTree });
-    await shadow.snapshot();
-    const after = await runGit(['status', '--porcelain'], { cwd: workTree });
-    expect(after.stdout).toBe(before.stdout);
-    // The shadow index must never become the real repo's index.
-    const staged = await runGit(['diff', '--cached', '--name-only'], { cwd: workTree });
-    expect(staged.stdout).toBe('');
-  });
-});
-
-describe('diff', () => {
-  itGit('reports an added file with its insertion count', async () => {
-    const { workTree, shadow } = await fixture();
-    const before = await shadow.snapshot();
-    await write(workTree, 'added.txt', 'one\ntwo\nthree\n');
-    const after = await shadow.snapshot();
-    const changes = await shadow.diff(before, after);
-    expect(changes).toHaveLength(1);
-    expect(byPath(changes, 'added.txt')).toEqual({
-      path: 'added.txt',
-      status: 'added',
-      insertions: 3,
-      deletions: 0,
-    });
-  });
-
-  itGit('reports a modified file with insertions and deletions', async () => {
-    const { workTree, shadow } = await fixture();
-    await write(workTree, 'keep.txt', 'l1\nl2\nl3\n');
-    const before = await shadow.snapshot();
-    await write(workTree, 'keep.txt', 'l1\nCHANGED\nl3\nl4\n');
-    const after = await shadow.snapshot();
-    const change = byPath(await shadow.diff(before, after), 'keep.txt');
-    expect(change.status).toBe('modified');
-    expect(change.insertions).toBe(2);
-    expect(change.deletions).toBe(1);
-  });
-
-  itGit('reports a deleted file', async () => {
-    const { workTree, shadow } = await fixture();
-    await write(workTree, 'gone.txt', 'bye\n');
-    const before = await shadow.snapshot();
-    await rm(join(workTree, 'gone.txt'));
-    const after = await shadow.snapshot();
-    const change = byPath(await shadow.diff(before, after), 'gone.txt');
-    expect(change.status).toBe('deleted');
-    expect(change.deletions).toBe(1);
-  });
-
-  itGit('reports a rename with the old path', async () => {
-    const { workTree, shadow } = await fixture();
-    await write(workTree, 'old.txt', 'a\nb\nc\nd\ne\nf\ng\nh\n');
-    const before = await shadow.snapshot();
-    await rename(join(workTree, 'old.txt'), join(workTree, 'new.txt'));
-    const after = await shadow.snapshot();
-    const changes = await shadow.diff(before, after);
-    expect(changes).toHaveLength(1);
-    expect(byPath(changes, 'new.txt')).toEqual({
-      path: 'new.txt',
-      status: 'renamed',
-      oldPath: 'old.txt',
-      insertions: 0,
-      deletions: 0,
-    });
-  });
-
-  itGit('reports several changes at once and counts binary files as zero lines', async () => {
-    const { workTree, shadow } = await fixture();
-    await write(workTree, 'bin.dat', new Uint8Array([0, 1, 2, 3]));
-    await write(workTree, 'text.txt', 'one\n');
-    const before = await shadow.snapshot();
-    await write(workTree, 'bin.dat', new Uint8Array([9, 9, 9, 9, 9]));
-    await write(workTree, 'text.txt', 'one\ntwo\n');
-    await write(workTree, 'deep/nested/new.txt', 'x\n');
-    const changes = await shadow.diff(before, await shadow.snapshot());
-    expect(changes.map((change) => change.path).sort()).toEqual([
-      'bin.dat',
-      'deep/nested/new.txt',
-      'text.txt',
-    ]);
-    expect(byPath(changes, 'bin.dat')).toMatchObject({ insertions: 0, deletions: 0 });
-    expect(byPath(changes, 'deep/nested/new.txt').status).toBe('added');
-  });
-
-  itGit('returns an empty list for identical trees', async () => {
-    const { workTree, shadow } = await fixture();
-    await write(workTree, 'a.txt', 'same\n');
-    const tree = await shadow.snapshot();
-    expect(await shadow.diff(tree, tree)).toEqual([]);
-  });
-
-  itGit('handles paths with spaces and unicode', async () => {
-    const { workTree, shadow } = await fixture();
-    const before = await shadow.snapshot();
-    await write(workTree, 'a dir/héllo wörld ✓.txt', 'unicode\n');
-    const changes = await shadow.diff(before, await shadow.snapshot());
-    expect(changes.map((change) => change.path)).toEqual(['a dir/héllo wörld ✓.txt']);
-  });
-});
-
-describe('line-ending-only changes', () => {
-  /**
-   * The shadow store keeps the bytes that were on disk, deliberately: normalising line endings
-   * would make the record disagree with the disk. The consequence on Windows is a one-character
-   * fix reported as every line changed, because the tool that made it wrote LF over a CRLF file.
-   * The counts are right, and unhelpful without this.
-   */
-  const CRLF = 'one\r\ntwo\r\nthree\r\n';
-  const LF = 'one\ntwo\nthree\n';
-
-  it('marks a file whose only change is CRLF to LF', async () => {
-    const { workTree, shadow } = await fixture();
-    await write(workTree, 'f.txt', CRLF);
-    const before = await shadow.snapshot();
-    await write(workTree, 'f.txt', LF);
-    const after = await shadow.snapshot();
-
-    const change = byPath(await shadow.diff(before, after), 'f.txt');
-    expect(change.status).toBe('modified');
-    // Honest, not silently normalised away: those lines really do differ byte for byte.
-    expect(change.insertions).toBe(3);
-    expect(change.deletions).toBe(3);
-    expect(change.eolOnly).toBe(true);
-  });
-
-  it('does not mark a real edit that also changed line endings', async () => {
-    const { workTree, shadow } = await fixture();
-    await write(workTree, 'f.txt', CRLF);
-    const before = await shadow.snapshot();
-    await write(workTree, 'f.txt', 'one\nTWO\nthree\n');
-    const after = await shadow.snapshot();
-    expect(byPath(await shadow.diff(before, after), 'f.txt').eolOnly).toBeUndefined();
-  });
-
-  it('does not mark a plain edit that left line endings alone', async () => {
-    const { workTree, shadow } = await fixture();
-    await write(workTree, 'f.txt', LF);
-    const before = await shadow.snapshot();
-    await write(workTree, 'f.txt', 'one\nTWO\nthree\n');
-    const after = await shadow.snapshot();
-    expect(byPath(await shadow.diff(before, after), 'f.txt').eolOnly).toBeUndefined();
-  });
-
-  it('does not mark a newly added file', async () => {
-    const { workTree, shadow } = await fixture();
-    const before = await shadow.snapshot();
-    await write(workTree, 'new.txt', CRLF);
-    const after = await shadow.snapshot();
-    expect(byPath(await shadow.diff(before, after), 'new.txt').eolOnly).toBeUndefined();
-  });
-});
-
-describe('exclusions', () => {
-  itGit("honours the workspace's own .gitignore", async () => {
-    const { workTree, shadow } = await fixture();
-    await write(workTree, '.gitignore', 'ignored.log\nbuild/\n');
-    await write(workTree, 'ignored.log', 'noise\n');
-    await write(workTree, 'build/out.js', 'noise\n');
-    await write(workTree, 'kept.txt', 'signal\n');
-    expect(await filesIn(shadow, await shadow.snapshot())).toEqual(['.gitignore', 'kept.txt']);
-  });
-
-  itGit('never captures secrets, with no .gitignore present', async () => {
-    const { workTree, shadow } = await fixture();
-    await write(workTree, '.env', 'API_KEY=sk-live-secret\n');
-    await write(workTree, '.env.local', 'API_KEY=sk-live-secret\n');
-    await write(workTree, 'id_rsa', 'PRIVATE KEY\n');
-    await write(workTree, 'id_ed25519', 'PRIVATE KEY\n');
-    await write(workTree, '.netrc', 'machine example.com password hunter2\n');
-    await write(workTree, 'certs/server.pem', 'CERT\n');
-    await write(workTree, 'certs/server.key', 'KEY\n');
-    await write(workTree, '.ssh/known_hosts', 'host\n');
-    await write(workTree, 'home/.aws/credentials', 'aws_secret_access_key=x\n');
-    await write(workTree, 'node_modules/pkg/index.js', 'noise\n');
-    await write(workTree, '.agenticreplay/runs/run_a/events.jsonl', '{}\n');
-    await write(workTree, 'src/app.ts', 'export const ok = 1;\n');
-    expect(await filesIn(shadow, await shadow.snapshot())).toEqual(['src/app.ts']);
-  });
-
-  // Security property: gitignore negation outranks $GIT_DIR/info/exclude, so the exclusions must
-  // not rest on info/exclude alone.
-  itGit('never captures secrets even when .gitignore tries to un-ignore them', async () => {
-    const { workTree, shadow } = await fixture();
-    await write(workTree, '.gitignore', '!.env\n!id_rsa\n!.ssh/\n!*.key\n!.agenticreplay/\n');
-    await write(workTree, '.env', 'API_KEY=sk-live-secret\n');
-    await write(workTree, 'id_rsa', 'PRIVATE KEY\n');
-    await write(workTree, '.ssh/id_ed25519', 'PRIVATE KEY\n');
-    await write(workTree, 'deep/nested/secret.key', 'KEY\n');
-    await write(workTree, '.agenticreplay/runs/run_a/events.jsonl', '{}\n');
-    await write(workTree, 'ok.txt', 'fine\n');
-    expect(await filesIn(shadow, await shadow.snapshot())).toEqual(['.gitignore', 'ok.txt']);
-  });
-  // GIT_LITERAL_PATHSPECS turns `:(exclude,glob)...` into an ordinary filename, which would
-  // quietly disarm every exclusion above. Nothing in the ambient environment may weaken this.
-  itGit('never captures secrets when the environment tampers with pathspec parsing', async () => {
-    const { workTree, shadow } = await fixture();
-    await write(workTree, '.env', 'API_KEY=sk-live-secret\n');
-    await write(workTree, '.gitignore', '!.env\n');
-    await write(workTree, 'ok.txt', 'fine\n');
-    const saved = process.env.GIT_LITERAL_PATHSPECS;
-    process.env.GIT_LITERAL_PATHSPECS = '1';
-    try {
-      expect(await filesIn(shadow, await shadow.snapshot())).toEqual(['.gitignore', 'ok.txt']);
-    } finally {
-      if (saved === undefined) delete process.env.GIT_LITERAL_PATHSPECS;
-      else process.env.GIT_LITERAL_PATHSPECS = saved;
-    }
-  });
-});
-
-/**
- * Paths an adapter declares as its harness's product, captured despite the workspace ignoring them.
- *
- * A coding agent's output is the working tree, which the ordinary snapshot already holds. A
- * pipeline's output is an index, and every such project ignores it — IndexRAG's first three
- * `.gitignore` lines are `vector_store/`, `cache/` and `dataset/` — so a recording of an indexing
- * run held every call that built the index and nothing of the index itself.
- */
-/**
- * A NESTED REPOSITORY WITH NO COMMIT.
- *
- * `git init` in a subdirectory and nothing committed yet — which is what anyone starting a second
- * project inside their workspace has. Git records an embedded repository by the id of its HEAD
- * commit, and this one has none, so `git add -A` answers `does not have a commit checked out` and
- * abandons the whole add. Every one of these pins that the snapshot is taken anyway, without that
- * directory, and that it is named.
- */
-describe('a nested repository with no commit', () => {
-  async function initRepo(dir: string): Promise<void> {
-    await mkdir(dir, { recursive: true });
-    for (const args of [
-      ['init', '-q'],
-      ['config', 'user.email', 't@e.com'],
-      ['config', 'user.name', 'T'],
-    ]) {
-      await runGit(args, { cwd: dir });
-    }
-  }
-
-  async function commitless(workTree: string, rel: string): Promise<void> {
-    await initRepo(join(workTree, rel));
-    await write(workTree, `${rel}/mine.py`, 'MY OWN WORK\n');
-  }
-
-  itGit('snapshots the rest of the tree instead of failing', async () => {
-    const { workTree, shadow } = await fixture();
-    await write(workTree, 'README.md', 'the outer project\n');
-    await commitless(workTree, 'newproject');
-
-    expect(await filesIn(shadow, await shadow.snapshot())).toEqual(['README.md']);
-  });
-
-  itGit('names it, once, however many snapshots the run takes', async () => {
-    const { workTree, shadow } = await fixture();
-    await write(workTree, 'README.md', 'x\n');
-    await commitless(workTree, 'newproject');
-
-    await shadow.snapshot();
-    expect(shadow.uncommittedNested).toEqual(['newproject']);
-    await write(workTree, 'README.md', 'y\n');
-    await shadow.snapshot();
-    expect(shadow.uncommittedNested).toEqual([]);
-  });
-
-  /**
-   * Git names one and stops — with three of them the first add reported only the first, and
-   * excluding it made the next add fail on the second. Anything that runs the add once and gives
-   * up on the first name passes the single-repository test and fails here.
-   */
-  itGit('leaves out every one of several, not only the first git named', async () => {
-    const { workTree, shadow } = await fixture();
-    await write(workTree, 'README.md', 'x\n');
-    for (const name of ['one', 'two', 'three']) await commitless(workTree, name);
-
-    expect(await filesIn(shadow, await shadow.snapshot())).toEqual(['README.md']);
-    expect([...shadow.uncommittedNested].sort()).toEqual(['one', 'three', 'two']);
-  });
-
-  itGit(
-    'leaves out one buried under ordinary directories, and keeps their other contents',
-    async () => {
-      const { workTree, shadow } = await fixture();
-      await write(workTree, 'a/b/keep.txt', 'mine\n');
-      await commitless(workTree, 'a/b/newproject');
-
-      expect(await filesIn(shadow, await shadow.snapshot())).toEqual(['a/b/keep.txt']);
-      expect(shadow.uncommittedNested).toEqual(['a/b/newproject']);
-    },
-  );
-
-  itGit('leaves out a name holding pattern characters, and only it', async () => {
-    const { workTree, shadow } = await fixture();
-    await write(workTree, 'README.md', 'x\n');
-    await write(workTree, 'my n project/neighbour.txt', 'must stay\n');
-    await commitless(workTree, 'my [new] project');
-
-    expect(await filesIn(shadow, await shadow.snapshot())).toEqual([
-      'README.md',
-      'my n project/neighbour.txt',
-    ]);
-    expect(shadow.uncommittedNested).toEqual(['my [new] project']);
-  });
-
-  /**
-   * WHY THE EXCLUSION SAYS `literal`.
-   *
-   * The path is whatever the operator called the directory, and a pathspec without `literal` is a
-   * pattern. Measured beside a workspace holding `ab/` and `ax/`: `:(exclude)a*` took both out of
-   * the add; `:(exclude,literal)a*` took out only a path named exactly that. So a repository named
-   * `a*` would drop its neighbours from the snapshot — silently, since the add still succeeds.
-   *
-   * POSIX only, because `*` is not a legal character in a Windows filename, so the workspace this
-   * needs cannot exist there. The test above is the same shape with a `[`, which every platform
-   * can hold — and it passes either way, because git compares the leading directory literally
-   * before it wildmatches. This is the one that fails when `literal` is dropped.
-   */
-  it.skipIf(!hasGit || process.platform === 'win32')(
-    'takes the path literally, so a name holding a wildcard excludes only itself',
-    async () => {
-      const { workTree, shadow } = await fixture();
-      await write(workTree, 'README.md', 'x\n');
-      await write(workTree, 'ab/neighbour.txt', 'must stay\n');
-      await write(workTree, 'ax/neighbour.txt', 'must stay too\n');
-      await commitless(workTree, 'a*');
-
-      expect(await filesIn(shadow, await shadow.snapshot())).toEqual([
-        'README.md',
-        'ab/neighbour.txt',
-        'ax/neighbour.txt',
-      ]);
-      expect(shadow.uncommittedNested).toEqual(['a*']);
-    },
-  );
-
-  itGit('still records one that has a commit as a gitlink, beside one that has none', async () => {
-    const { workTree, gitDir, shadow } = await fixture();
-    await write(workTree, 'README.md', 'x\n');
-    await initRepo(join(workTree, 'vendor'));
-    await write(workTree, 'vendor/lib.py', 'upstream\n');
-    await runGit(['add', '-A'], { cwd: join(workTree, 'vendor') });
-    await runGit(['commit', '-qm', 'u'], { cwd: join(workTree, 'vendor') });
-    await commitless(workTree, 'fresh');
-
-    const tree = await shadow.snapshot();
-    expect(shadow.uncommittedNested).toEqual(['fresh']);
-    // The committed one is still a gitlink in the tree, which is what `gitlinks` reports and what
-    // the replay's own guard reads; the commit-less one is in neither, by definition.
-    expect(await shadow.gitlinks(tree)).toEqual(['vendor']);
-    const listed = await runGit(['ls-tree', '-r', '--full-tree', tree], { gitDir });
-    expect(listed.stdout).not.toContain('fresh');
-  });
-
-  itGit('drops the outer one only, when one with no commit holds another', async () => {
-    const { workTree, shadow } = await fixture();
-    await write(workTree, 'README.md', 'x\n');
-    await commitless(workTree, 'outer');
-    await commitless(workTree, 'outer/inner');
-
-    expect(await filesIn(shadow, await shadow.snapshot())).toEqual(['README.md']);
-    expect(shadow.uncommittedNested).toEqual(['outer']);
-  });
-
-  /**
-   * `-A` never reaches a path the workspace ignores, and a declared artifact path is exactly where
-   * an ignored one is — so the forced add can meet a commit-less repository the first add could
-   * not see. It has to survive that too, and say so.
-   */
-  itGit('survives one inside a declared artifact path the workspace ignores', async () => {
-    const root = await makeTempDir();
-    const workTree = join(root, 'ws');
-    await mkdir(workTree, { recursive: true });
-    const shadow = await ShadowIndex.create({
-      gitDir: join(root, 'run', 'fs'),
-      workTree,
-      forced: ['dataset'],
-    });
-    await write(workTree, '.gitignore', 'dataset/\n');
-    await write(workTree, 'dataset/corpus.txt', 'the product\n');
-    await write(workTree, 'main.py', 'print(1)\n');
-    await initRepo(join(workTree, 'dataset', 'scratch'));
-    await write(workTree, 'dataset/scratch/notes.md', 'never committed\n');
-
-    expect(await filesIn(shadow, await shadow.snapshot())).toEqual([
-      '.gitignore',
-      'dataset/corpus.txt',
-      'main.py',
-    ]);
-    expect(shadow.uncommittedNested).toEqual(['dataset/scratch']);
-  });
-
-  /** A failure that is not this one still throws, with git's own words. */
-  itGit('still fails on an add that goes wrong for any other reason', async () => {
-    const { workTree, shadow } = await fixture();
-    await write(workTree, 'README.md', 'x\n');
-    await rm(workTree, { recursive: true, force: true });
-
-    await expect(shadow.snapshot()).rejects.toThrow(/git add failed/);
-  });
-});
-
-/**
- * A DECLARED PATH INSIDE A NESTED REPOSITORY.
- *
- * Git stages nothing inside another repository, and asked to it answers in whichever way the
- * operator's setup happens to produce: with the repository committed and not ignored, `add -A`
- * stages it as a gitlink and `add -f -- data/cache` then dies ("Pathspec 'data/cache' is in
- * submodule 'data'"), which cost a recording every snapshot it took; ignored, or with no commit,
- * `add -f` exits 0 having staged nothing, which is silent. So the path is set aside before git sees
- * it, and named with the repository around it.
- */
-describe('a declared path inside a nested repository', () => {
-  async function initRepo(dir: string): Promise<void> {
-    await mkdir(dir, { recursive: true });
-    for (const args of [
-      ['init', '-q'],
-      ['config', 'user.email', 't@e.com'],
-      ['config', 'user.name', 'T'],
-    ]) {
-      await runGit(args, { cwd: dir });
-    }
-  }
-
-  /** The operator's own project at `rel`, with their work in `cache/` inside it. */
-  async function project(workTree: string, rel: string, commit: boolean): Promise<void> {
-    await initRepo(join(workTree, rel));
-    await write(workTree, `${rel}/cache/mine.bin`, 'their own work\n');
-    await write(workTree, `${rel}/notes.md`, 'theirs too\n');
-    if (commit) {
-      await runGit(['add', '-A'], { cwd: join(workTree, rel) });
-      await runGit(['commit', '-qm', 'u'], { cwd: join(workTree, rel) });
-    }
-  }
-
-  async function forcedFixture(forced: string[]): Promise<Fixture> {
-    const root = await makeTempDir();
-    const workTree = join(root, 'ws');
-    const gitDir = join(root, 'run', 'fs');
-    await mkdir(workTree, { recursive: true });
-    const shadow = await ShadowIndex.create({ gitDir, workTree, forced });
-    return { root, workTree, gitDir, shadow };
-  }
-
-  /** The case that took every snapshot down with it. */
-  itGit('snapshots around one that is committed and not ignored, instead of dying', async () => {
-    const { workTree, shadow } = await forcedFixture(['data/cache']);
-    await write(workTree, 'README.md', 'x\n');
-    await project(workTree, 'data', true);
-
-    const tree = await shadow.snapshot();
-    // The outer file, and `data` as the gitlink `add -A` made of it — none of what is inside.
-    expect(await filesIn(shadow, tree)).toEqual(['README.md', 'data']);
-    expect(shadow.forcedInsideNested).toEqual([{ path: 'data/cache', repository: 'data' }]);
-    // What `add -A` made of the repository itself is left as it was: a gitlink, which the
-    // replay's own guard reads.
-    expect(await shadow.gitlinks(tree)).toEqual(['data']);
-  });
-
-  /** The silent case: nothing failed, and nothing said the declared path was not captured. */
-  itGit('names one the workspace ignores, which git passes over without a word', async () => {
-    const { workTree, shadow } = await forcedFixture(['data/cache']);
-    await write(workTree, '.gitignore', 'data/\n');
-    await project(workTree, 'data', true);
-
-    expect(await filesIn(shadow, await shadow.snapshot())).toEqual(['.gitignore']);
-    expect(shadow.forcedInsideNested).toEqual([{ path: 'data/cache', repository: 'data' }]);
-  });
-
-  itGit('names one with no commit, as well as naming the repository itself', async () => {
-    const { workTree, shadow } = await forcedFixture(['data/cache']);
-    await write(workTree, 'README.md', 'x\n');
-    await project(workTree, 'data', false);
-
-    expect(await filesIn(shadow, await shadow.snapshot())).toEqual(['README.md']);
-    expect(shadow.forcedInsideNested).toEqual([{ path: 'data/cache', repository: 'data' }]);
-    expect(shadow.uncommittedNested).toEqual(['data']);
-  });
-
-  itGit('names the nearest repository on the way down, however deep the path is', async () => {
-    const { workTree, shadow } = await forcedFixture(['a/b/data/cache/index']);
-    await write(workTree, 'a/b/keep.txt', 'mine\n');
-    await project(workTree, 'a/b/data', true);
-
-    await shadow.snapshot();
-    expect(shadow.forcedInsideNested).toEqual([
-      { path: 'a/b/data/cache/index', repository: 'a/b/data' },
-    ]);
-  });
-
-  itGit('still captures the declared paths that are not inside one', async () => {
-    const { workTree, shadow } = await forcedFixture(['data/cache', 'cache']);
-    await write(workTree, '.gitignore', 'cache/\ndata/\n');
-    await write(workTree, 'cache/index.bin', 'the product\n');
-    await project(workTree, 'data', true);
-
-    expect(await filesIn(shadow, await shadow.snapshot())).toEqual([
-      '.gitignore',
-      'cache/index.bin',
-    ]);
-    expect(shadow.forcedInsideNested).toEqual([{ path: 'data/cache', repository: 'data' }]);
-  });
-
-  /**
-   * With every declared path set aside there is nothing to add — and nothing may be dropped:
-   * `ls-files -- <no paths>` lists the WHOLE index, so dropping the gitlinks it returns would take
-   * the workspace's own nested repositories out of the snapshot too.
-   */
-  itGit(
-    'leaves the workspace’s other nested repositories alone when nothing is left to add',
-    async () => {
-      const { workTree, shadow } = await forcedFixture(['data/cache']);
-      await write(workTree, 'README.md', 'x\n');
-      await project(workTree, 'data', true);
-      await project(workTree, 'vendor', true);
-
-      const tree = await shadow.snapshot();
-      expect((await shadow.gitlinks(tree)).sort()).toEqual(['data', 'vendor']);
-      expect(shadow.skippedGitlinks).toEqual([]);
-    },
-  );
-
-  /** A declared path that IS the repository is a gitlink, dropped as before — not "inside" one. */
-  itGit('leaves a declared path that is itself a repository to the gitlink handling', async () => {
-    const { workTree, shadow } = await forcedFixture(['dataset']);
-    await write(workTree, '.gitignore', 'dataset/\n');
-    await project(workTree, 'dataset', true);
-
-    await shadow.snapshot();
-    expect(shadow.forcedInsideNested).toEqual([]);
-    expect(shadow.skippedGitlinks).toEqual(['dataset']);
-  });
-
-  itGit('walks only the literal segments before a glob', async () => {
-    const { workTree, shadow } = await forcedFixture(['data/*/cache', 'test_results_*.json']);
-    await write(workTree, 'test_results_1.json', '{}\n');
-    await project(workTree, 'data', true);
-
-    expect(await filesIn(shadow, await shadow.snapshot())).toContain('test_results_1.json');
-    expect(shadow.forcedInsideNested).toEqual([{ path: 'data/*/cache', repository: 'data' }]);
-  });
-
-  itGit('names each one once, however many snapshots the run takes', async () => {
-    const { workTree, shadow } = await forcedFixture(['data/cache']);
-    await write(workTree, 'README.md', 'x\n');
-    await project(workTree, 'data', true);
-
-    await shadow.snapshot();
-    expect(shadow.forcedInsideNested).toHaveLength(1);
-    await write(workTree, 'README.md', 'y\n');
-    await shadow.snapshot();
-    expect(shadow.forcedInsideNested).toEqual([]);
-  });
-
-  itGit('says nothing when no declared path is inside a repository', async () => {
-    const { workTree, shadow } = await forcedFixture(['cache']);
-    await write(workTree, 'cache/index.bin', 'x\n');
-
-    await shadow.snapshot();
-    expect(shadow.forcedInsideNested).toEqual([]);
-  });
-});
-
-describe('forced capture', () => {
-  itGit('captures a path the workspace ignores, when the adapter declares it', async () => {
-    const root = await makeTempDir();
-    const workTree = join(root, 'ws');
-    await mkdir(workTree, { recursive: true });
-    const shadow = await ShadowIndex.create({
-      gitDir: join(root, 'run', 'fs'),
-      workTree,
-      forced: ['cache'],
-    });
-    await write(workTree, '.gitignore', 'cache/\nvector_store/\n');
-    await write(workTree, 'cache/mini_faqs.json', '{"faq_data":[]}\n');
-    await write(workTree, 'vector_store/index.faiss', 'binary\n');
-    await write(workTree, 'main.py', 'print(1)\n');
-
-    expect(await filesIn(shadow, await shadow.snapshot())).toEqual([
-      '.gitignore',
-      'cache/mini_faqs.json',
-      'main.py',
-    ]);
-  });
-
-  /**
-   * The security property that makes this safe to hand to third-party plugin code: the sensitive
-   * pathspecs are applied to the forced add too, and a pathspec exclusion is enforced by `git add`
-   * itself — no `-f` and no `.gitignore` negation overrides it. So an adapter that declares `.`
-   * to try to sweep the whole tree in still cannot capture a credential.
-   */
-  itGit('still refuses secrets when the adapter declares the whole tree', async () => {
-    const root = await makeTempDir();
-    const workTree = join(root, 'ws');
-    await mkdir(workTree, { recursive: true });
-    const shadow = await ShadowIndex.create({
-      gitDir: join(root, 'run', 'fs'),
-      workTree,
-      forced: ['.'],
-    });
-    await write(workTree, '.gitignore', '!.env\n');
-    await write(workTree, '.env', 'API_KEY=sk-live-secret\n');
-    await write(workTree, '.ssh/id_ed25519', 'PRIVATE KEY\n');
-    await write(workTree, 'node_modules/pkg/index.js', 'noise\n');
-    await write(workTree, 'ok.txt', 'fine\n');
-
-    const files = await filesIn(shadow, await shadow.snapshot());
-    expect(files).toEqual(['.gitignore', 'ok.txt']);
-  });
-
-  // Snapshot 0 is taken before the harness has written anything, and `git add` refuses a pathspec
-  // that matches nothing. One missing directory must not cost the whole snapshot.
-  itGit('snapshots normally when a declared path does not exist yet', async () => {
-    const root = await makeTempDir();
-    const workTree = join(root, 'ws');
-    await mkdir(workTree, { recursive: true });
-    const shadow = await ShadowIndex.create({
-      gitDir: join(root, 'run', 'fs'),
-      workTree,
-      forced: ['cache', 'vector_store'],
-    });
-    await write(workTree, '.gitignore', 'cache/\nvector_store/\n');
-    await write(workTree, 'main.py', 'print(1)\n');
-
-    expect(await filesIn(shadow, await shadow.snapshot())).toEqual(['.gitignore', 'main.py']);
-
-    // And it picks the path up as soon as the harness creates it.
-    await write(workTree, 'cache/mini_faqs.json', '{}\n');
-    expect(await filesIn(shadow, await shadow.snapshot())).toEqual([
-      '.gitignore',
-      'cache/mini_faqs.json',
-      'main.py',
-    ]);
-  });
-
-  itGit('tracks a forced path across edits and deletions', async () => {
-    const root = await makeTempDir();
-    const workTree = join(root, 'ws');
-    await mkdir(workTree, { recursive: true });
-    const shadow = await ShadowIndex.create({
-      gitDir: join(root, 'run', 'fs'),
-      workTree,
-      forced: ['cache'],
-    });
-    await write(workTree, '.gitignore', 'cache/\n');
-    await write(workTree, 'cache/a.json', '{"n":1}\n');
-    const first = await shadow.snapshot();
-
-    await write(workTree, 'cache/a.json', '{"n":2}\n');
-    const second = await shadow.snapshot();
-    expect(first).not.toBe(second);
-    expect(new TextDecoder().decode(await shadow.readFileAt(second, 'cache/a.json'))).toBe(
-      '{"n":2}\n',
-    );
-
-    await rm(join(workTree, 'cache'), { recursive: true, force: true });
-    expect(await filesIn(shadow, await shadow.snapshot())).toEqual(['.gitignore']);
-  });
-
-  /**
-   * "Did not match any files" is the *only* `git add` failure a snapshot may ignore.
-   *
-   * The per-path retry exists for the pathspec that matches nothing, and it used to swallow every
-   * other failure with it — a file git cannot open because the harness is still writing it, EACCES,
-   * a path too long — because `runGit` resolves rather than throws and no exit code was read. The
-   * snapshot then returned a tree id as if all was well while silently not holding the declared
-   * path, which is worse than failing: on replay the same hole lands in the safety snapshot that
-   * `resetArtifacts` deletes against, so what agenticreplay could not copy it deletes anyway.
-   *
-   * A path outside the workspace is the portable way to provoke a non-benign failure (the original
-   * report used a file held open by another process, which only Windows makes easy) — and it is
-   * worth refusing on its own account, since an adapter reaching outside the workspace is not
-   * something to do quietly.
-   */
-  itGit('refuses a declared path git fails on for any other reason', async () => {
-    const root = await makeTempDir();
-    const workTree = join(root, 'ws');
-    await mkdir(workTree, { recursive: true });
-    await write(root, 'outside.txt', 'not yours\n');
-    const shadow = await ShadowIndex.create({
-      gitDir: join(root, 'run', 'fs'),
-      workTree,
-      forced: ['cache', '../outside.txt'],
-    });
-    await write(workTree, '.gitignore', 'cache/\n');
-    await write(workTree, 'cache/mini_faqs.json', '{}\n');
-
-    await expect(shadow.snapshot()).rejects.toThrow(/declared artifact path '\.\.\/outside\.txt'/);
-  });
-
-  /**
-   * A cloned corpus inside a declared path, which `-f` reaches for the first time.
-   *
-   * `git add` records a nested repository as a gitlink whose contents live nowhere in this store,
-   * and `materialize` refuses such a tree rather than checking out an empty directory in its
-   * place. `dataset/` is both one of IndexRAG's declared paths and the ordinary place to clone a
-   * corpus into, so before this the first replay of such a workspace failed at the restore — after
-   * the reset had already deleted the artifacts the restore was supposed to put back.
-   */
-  itGit('drops a nested repository inside a declared path, and names it once', async () => {
-    const root = await makeTempDir();
-    const workTree = join(root, 'ws');
-    await mkdir(workTree, { recursive: true });
-    const shadow = await ShadowIndex.create({
-      gitDir: join(root, 'run', 'fs'),
-      workTree,
-      forced: ['cache', 'dataset'],
-    });
-    await write(workTree, '.gitignore', 'cache/\ndataset/\n');
-    await write(workTree, 'cache/mini_faqs.json', '{}\n');
-    await write(workTree, 'dataset/notes.txt', 'loose file, still captured\n');
-    const corpus = join(workTree, 'dataset', 'hotpotqa');
-    await mkdir(corpus, { recursive: true });
-    await runGit(['init', '-q'], { cwd: corpus });
-    await write(corpus, 'docs.jsonl', '{"id":1}\n');
-    await runGit(['add', '-A'], { cwd: corpus });
-    await runGit(['-c', 'user.email=a@b.c', '-c', 'user.name=a', 'commit', '-qm', 'x'], {
-      cwd: corpus,
-    });
-
-    const tree = await shadow.snapshot();
-    expect(shadow.skippedGitlinks).toEqual(['dataset/hotpotqa']);
-    expect(await shadow.gitlinks(tree)).toEqual([]);
-    // Everything else the adapter declared is still there, and the tree restores.
-    expect(await filesIn(shadow, tree)).toEqual([
-      '.gitignore',
-      'cache/mini_faqs.json',
-      'dataset/notes.txt',
-    ]);
-    await expect(shadow.materialize(tree, join(root, 'dest'))).resolves.toBeUndefined();
-
-    // Named once: a warning repeated on every turn of a long run is a warning nobody reads.
-    await shadow.snapshot();
-    expect(shadow.skippedGitlinks).toEqual([]);
-  });
-
-  /**
-   * What the snapshot did not take a copy of, for a caller about to delete these paths.
-   *
-   * Two rules keep things out of a forced add, and both are right: the sensitive pathspecs stop an
-   * adapter sweeping a credential into a trace however it declares its paths, and a nested
-   * repository cannot be held at all. Both mean the copy is missing something a reset would take —
-   * an `.env` the operator keeps beside a cache, a prebuilt store cloned into `vector_store/` —
-   * and neither need appear in the recording's own tree, since the operator may have put it there
-   * afterwards. `agenticreplay replay` deletes these paths on the strength of this copy, so it has to be
-   * able to ask what the copy is missing before it does.
-   */
-  itGit('reports what a forced snapshot could not hold under the declared paths', async () => {
-    const root = await makeTempDir();
-    const workTree = join(root, 'ws');
-    await mkdir(workTree, { recursive: true });
-    const shadow = await ShadowIndex.create({
-      gitDir: join(root, 'run', 'fs'),
-      workTree,
-      forced: ['cache', 'vector_store'],
-    });
-    await write(workTree, '.gitignore', 'cache/\nvector_store/\n');
-    await write(workTree, 'cache/mini_faqs.json', '{}\n');
-    await write(workTree, 'cache/.env', 'INDEXRAG_EMBEDDING_API_KEY=sk-live\n');
-    const prebuilt = join(workTree, 'vector_store', 'prebuilt');
-    await mkdir(prebuilt, { recursive: true });
-    await runGit(['init', '-q'], { cwd: prebuilt });
-    await write(prebuilt, 'faiss.bin', 'months of work\n');
-    await runGit(['add', '-A'], { cwd: prebuilt });
-    await runGit(['-c', 'user.email=a@b.c', '-c', 'user.name=a', 'commit', '-qm', 'p'], {
-      cwd: prebuilt,
-    });
-
-    await shadow.snapshot();
-    // The credential, kept out on purpose; and the clone, which no snapshot can hold. A trailing
-    // slash on the second because git will not look inside a repository of its own.
-    expect(await shadow.uncaptured(['cache', 'vector_store'])).toEqual([
-      'cache/.env',
-      'vector_store/prebuilt/',
-    ]);
-    // And the ordinary case says nothing, so a guard built on this is quiet in a normal run.
-    expect(await shadow.uncaptured(['cache/mini_faqs.json'])).toEqual([]);
-  });
-
-  /**
-   * The same question `materialize` answers by throwing, asked without writing anything.
-   *
-   * `agenticreplay replay` deletes the artifacts *before* the restore that puts them back, which is the
-   * only ordering that leaves them holding what they held when recording began. That makes the
-   * restore's refusal unrecoverable unless it can be seen coming — and recordings made before
-   * gitlinks were dropped are still on disk, which is who this is for.
-   */
-  itGit('reports the gitlinks a restore would refuse, without touching the workspace', async () => {
-    const { root, workTree, shadow } = await fixture();
-    await write(workTree, 'a.txt', 'x\n');
-    const clean = await shadow.snapshot();
-    expect(await shadow.gitlinks(clean)).toEqual([]);
-
-    // Not inside a declared path, so `add -A` stages it exactly as it always has.
-    const inner = join(workTree, 'vendor', 'inner');
-    await mkdir(inner, { recursive: true });
-    await runGit(['init', '-q'], { cwd: inner });
-    await write(inner, 'f.txt', 'inner\n');
-    await runGit(['add', '-A'], { cwd: inner });
-    await runGit(['-c', 'user.email=a@b.c', '-c', 'user.name=a', 'commit', '-qm', 'x'], {
-      cwd: inner,
-    });
-
-    const withLink = await shadow.snapshot();
-    expect(await shadow.gitlinks(withLink)).toEqual(['vendor/inner']);
-    await expect(shadow.materialize(withLink, join(root, 'dest'))).rejects.toThrow(
-      /embedded git repositor/i,
-    );
-  });
-});
-
-describe('readFileAt', () => {
-  itGit('returns the exact bytes stored in a tree', async () => {
-    const { workTree, shadow } = await fixture();
-    const bytes = new Uint8Array([0x00, 0xff, 0x10, 0x0a, 0x7f]);
-    await write(workTree, 'nested/bin.dat', bytes);
-    await write(workTree, 'nested/u.txt', 'héllo ünicode ✓\n漢字\n');
-    const tree = await shadow.snapshot();
-    expect(await shadow.readFileAt(tree, 'nested/bin.dat')).toEqual(bytes);
-    expect(Buffer.from(await shadow.readFileAt(tree, 'nested/u.txt')).toString('utf8')).toBe(
-      'héllo ünicode ✓\n漢字\n',
-    );
-  });
-
-  itGit('throws for a path that is not in the tree', async () => {
-    const { workTree, shadow } = await fixture();
-    await write(workTree, 'a.txt', 'x\n');
-    const tree = await shadow.snapshot();
-    await expect(shadow.readFileAt(tree, 'missing.txt')).rejects.toThrow(/missing\.txt/);
-  });
-});
-
-describe('patch', () => {
-  itGit('produces a unified diff for the whole tree', async () => {
-    const { workTree, shadow } = await fixture();
-    await write(workTree, 'a.txt', 'l1\nl2\n');
-    const before = await shadow.snapshot();
-    await write(workTree, 'a.txt', 'l1\nl2\nl3\n');
-    await write(workTree, 'b.txt', 'new\n');
-    const patch = await shadow.patch(before, await shadow.snapshot());
-    expect(patch).toContain('diff --git a/a.txt b/a.txt');
-    expect(patch).toContain('+l3');
-    expect(patch).toContain('b.txt');
-  });
-
-  itGit('narrows to a single path when asked', async () => {
-    const { workTree, shadow } = await fixture();
-    await write(workTree, 'a.txt', 'l1\n');
-    await write(workTree, 'b.txt', 'l1\n');
-    const before = await shadow.snapshot();
-    await write(workTree, 'a.txt', 'l1\nl2\n');
-    await write(workTree, 'b.txt', 'l1\nl2\n');
-    const patch = await shadow.patch(before, await shadow.snapshot(), 'a.txt');
-    expect(patch).toContain('a.txt');
-    expect(patch).not.toContain('b.txt');
-  });
-});
-
-describe('materialize', () => {
-  itGit('round-trips a nested tree byte for byte', async () => {
-    const { root, workTree, shadow } = await fixture();
-    const unicode = 'héllo ünicode ✓\n漢字とカナ\nlast line without newline';
-    const binary = new Uint8Array([0, 1, 2, 253, 254, 255, 10, 13]);
-    await write(workTree, 'top.txt', 'top\n');
-    await write(workTree, 'nested/deep/u.txt', unicode);
-    await write(workTree, 'nested/deep/deeper/bin.dat', binary);
-    await write(workTree, 'nested/crlf.txt', 'a\r\nb\r\n');
-    await write(workTree, 'run.sh', '#!/bin/sh\necho hi\n');
-    await chmod(join(workTree, 'run.sh'), 0o755);
-    const tree = await shadow.snapshot();
-
-    const dest = join(root, 'materialized');
-    await shadow.materialize(tree, dest);
-
-    expect(await listFilesRecursive(dest)).toEqual(await listFilesRecursive(workTree));
-    for (const rel of await listFilesRecursive(workTree)) {
-      const original = await readFile(join(workTree, rel));
-      const restored = await readFile(join(dest, rel));
-      expect(restored.equals(original), `bytes differ for ${rel}`).toBe(true);
-    }
-    // Windows has no execute bit — git itself gives up on it there (`core.fileMode=false`), so a
-    // restore cannot put back what the filesystem cannot hold. Only this line is skipped: the
-    // byte-for-byte round trip above is exactly as meaningful on Windows and still runs.
-    //
-    // The consequence is real and belongs in the open, not in a green test: a run recorded on
-    // POSIX and forked on Windows gets its scripts back without `+x`.
-    if (process.platform !== 'win32') {
-      expect((await stat(join(dest, 'run.sh'))).mode & 0o111).toBeGreaterThan(0);
-    }
-  });
-
-  /**
-   * Creating the symlink is what fails on Windows, in this test's own setup: `symlink()` needs
-   * Developer Mode or elevation, so the scenario cannot be built and `materialize` is never
-   * reached. The gap on Windows is therefore unmeasured here, not proven — worth saying plainly
-   * rather than leaving a red test that looks like a restore bug.
-   */
-  itGit.skipIf(process.platform === 'win32')(
-    'round-trips a symlink as a symlink, without following it',
-    async () => {
-      const { root, workTree, shadow } = await fixture();
-      await write(workTree, 'target.txt', 'pointed at\n');
-      await symlink('target.txt', join(workTree, 'link.txt'));
-      await symlink('/etc/passwd', join(workTree, 'escape.txt'));
-      const dest = join(root, 'materialized-links');
-      await shadow.materialize(await shadow.snapshot(), dest);
-      expect(await readlink(join(dest, 'link.txt'))).toBe('target.txt');
-      expect(await readlink(join(dest, 'escape.txt'))).toBe('/etc/passwd');
-      expect((await lstat(join(dest, 'escape.txt'))).isSymbolicLink()).toBe(true);
-    },
-  );
-
-  itGit('creates the destination directory if it does not exist', async () => {
-    const { root, workTree, shadow } = await fixture();
-    await write(workTree, 'a.txt', 'x\n');
-    const dest = join(root, 'does', 'not', 'exist');
-    await shadow.materialize(await shadow.snapshot(), dest);
-    expect(await readFile(join(dest, 'a.txt'), 'utf8')).toBe('x\n');
-  });
-
-  itGit('materializes the empty tree as an empty directory', async () => {
-    const { root, shadow } = await fixture();
-    const dest = join(root, 'empty-dest');
-    await shadow.materialize(await shadow.snapshot(), dest);
-    expect(await listFilesRecursive(dest)).toEqual([]);
-  });
-
-  // git add stores a nested repository as a gitlink whose contents live nowhere in the shadow
-  // store, so checkout-index would silently produce an empty directory. Fork replay must not
-  // debug a workspace that quietly lost a subtree.
-  itGit('refuses to materialize a tree containing an embedded git repository', async () => {
-    const { root, workTree, shadow } = await fixture();
-    await write(workTree, 'a.txt', 'x\n');
-    const inner = join(workTree, 'vendor', 'inner');
-    await mkdir(inner, { recursive: true });
-    await runGit(['init', '-q'], { cwd: inner });
-    await write(inner, 'f.txt', 'inner\n');
-    await runGit(['add', '-A'], { cwd: inner });
-    await runGit(['-c', 'user.email=a@b.c', '-c', 'user.name=a', 'commit', '-qm', 'x'], {
-      cwd: inner,
-    });
-    const tree = await shadow.snapshot();
-    const dest = join(root, 'dest');
-    await expect(shadow.materialize(tree, dest)).rejects.toThrow(/embedded git repositor/i);
-    await expect(
-      shadow.materialize(tree, dest, { allowIncomplete: true }),
-    ).resolves.toBeUndefined();
-    expect(await readFile(join(dest, 'a.txt'), 'utf8')).toBe('x\n');
-  });
-});