agenticreplay 0.1.0 → 0.1.2

package/node_modules/@agenticreplay/fs-capture/dist/shadow.js

@@ -0,0 +1,668 @@
+import { lstat, mkdir, rm, writeFile } from 'node:fs/promises';
+import { randomBytes } from 'node:crypto';
+import { isAbsolute, join, relative, resolve } from 'node:path';
+import { gitAvailable, runGit, runGitRaw } from './git.js';
+/** git's hardcoded id for a tree with no entries; always resolvable, even in a fresh store. */
+export const EMPTY_TREE = '4b825dc642cb6eb9a060e54bf8d69288fbee4904';
+export const GIT_MISSING_MESSAGE = 'git is required for filesystem capture; install git or run with --no-fs';
+/**
+ * Paths never captured, in .gitignore syntax. Secrets first, then noise that would bloat every
+ * snapshot, then `.agenticreplay/` so a run never records its own trace.
+ */
+export const SENSITIVE_PATTERNS = [
+    '.env*',
+    '.ssh/',
+    '.aws/',
+    '.netrc',
+    '*.pem',
+    '*.key',
+    'id_rsa*',
+    'id_ed25519*',
+    '.agenticreplay/',
+    'node_modules/',
+    '.git/',
+];
+/** Mode git gives a nested repository staged as a gitlink. */
+const GITLINK_MODE = '160000';
+/**
+ * The same policy as a pathspec. A `.gitignore` in the workspace outranks `$GIT_DIR/info/exclude`,
+ * so a single `!.env` line there would otherwise re-include a secret; pathspec exclusions are
+ * applied by `git add` itself and no ignore file can override them.
+ */
+function toPathspecs(pattern) {
+    if (pattern.endsWith('/')) {
+        const bare = pattern.slice(0, -1);
+        return [`:(exclude,glob)**/${bare}`, `:(exclude,glob)**/${bare}/**`];
+    }
+    return [`:(exclude,glob)**/${pattern}`];
+}
+const SENSITIVE_PATHSPECS = SENSITIVE_PATTERNS.flatMap(toPathspecs);
+function statusOf(letter) {
+    switch (letter) {
+        case 'A':
+            return 'added';
+        case 'D':
+            return 'deleted';
+        case 'R':
+            return 'renamed';
+        case 'C':
+            return 'added';
+        default:
+            return 'modified';
+    }
+}
+/** numstat writes `-` for a binary file, which is zero lines, not an unknown count. */
+function toCount(field) {
+    const parsed = Number.parseInt(field ?? '', 10);
+    return Number.isNaN(parsed) ? 0 : parsed;
+}
+/**
+ * The one `git add` failure a snapshot may ignore.
+ *
+ * Read off the message because git has no distinct exit code for it, and safe to read that way
+ * because `childEnv` sets `LC_ALL=C` for every child: the wording is git's, not the operator's
+ * locale's.
+ */
+function matchedNothing(stderr) {
+    return /did not match any files/i.test(stderr);
+}
+/**
+ * The nested repositories a `git add` failure says it could not index, because they hold no commit.
+ *
+ * Read off the message for the same reason {@link matchedNothing} is, and with the same licence:
+ * git has no exit code of its own for this, and `childEnv` sets `LC_ALL=C`, so the wording is
+ * git's rather than the operator's locale's.
+ *
+ * Anchored, and the whole line consumed, because the path is the rest of it: a directory may hold
+ * a space, a quote or a bracket, so nothing here may split on one. Git prints the path with a
+ * trailing slash — `error: 'newproject/' does not have a commit checked out` — which is dropped,
+ * since every pathspec and every path this store reports elsewhere is without one.
+ */
+function commitlessNested(stderr) {
+    const named = new Set();
+    for (const line of stderr.split(/\r?\n/)) {
+        const path = /^error: '(.*)\/' does not have a commit checked out$/.exec(line.trim())?.[1];
+        if (path !== undefined && path !== '')
+            named.add(path);
+    }
+    return [...named];
+}
+/**
+ * The nested repository a declared path sits strictly inside, if any: the first directory on the
+ * way down from the work tree to it that holds a `.git` of its own. Not the work tree's own, and not
+ * the path itself — a declared path that IS a repository is stored as a gitlink, which
+ * {@link ShadowIndex.dropForcedGitlinks} already handles.
+ *
+ * ASKED OF THE FILESYSTEM, NOT OF GIT, because git answers the same question three different ways
+ * depending on things the operator does not control. Measured with the operator's own project at
+ * `data` and an adapter declaring `data/cache`:
+ *
+ *   committed, not ignored   `add -A` stages `data` as a gitlink, and `add -f -- data/cache` then
+ *                            dies: "Pathspec 'data/cache' is in submodule 'data'" — every turn of a
+ *                            recording, so it held no snapshot at all, and the safety copy before a
+ *                            replay, after its `agenticreplay-safety-*` directory already existed
+ *   ignored, or no commit    `add -f -- data/cache` exits 0 having staged nothing and named nothing
+ *
+ * Neither is an answer anything downstream can use, and the second is silent: a replay whose reset
+ * reached inside that repository deleted the operator's files under exit 0, with no copy anywhere.
+ * A `.git` on the way down is the one fact all three share.
+ *
+ * Only literal segments are walked. A glob ends the walk, and every segment before it encloses
+ * whatever the glob matches; a path that leaves the work tree has no enclosing repository here.
+ */
+async function enclosingRepository(workTree, declared) {
+    const inside = relative(workTree, resolve(workTree, declared));
+    if (inside === '' || isAbsolute(inside) || inside.split(/[\\/]/)[0] === '..')
+        return undefined;
+    const segments = inside.split(/[\\/]/).filter((segment) => segment !== '');
+    const literal = [];
+    for (const segment of segments) {
+        if (/[*?[]/.test(segment))
+            break;
+        literal.push(segment);
+    }
+    // Every proper prefix of the path; and all of the literal ones, when a glob cut the walk short.
+    const deepest = literal.length === segments.length ? literal.length - 1 : literal.length;
+    for (let depth = 1; depth <= deepest; depth += 1) {
+        if (await holdsGitDir(join(workTree, ...literal.slice(0, depth)))) {
+            return literal.slice(0, depth).join('/');
+        }
+    }
+    return undefined;
+}
+/**
+ * Whether `dir` has a `.git` — a directory for a repository of its own, a file for a submodule or a
+ * linked worktree. A path this process cannot even look at counts as one: what depends on the
+ * answer is whether agenticreplay may delete inside it, and nothing may conclude "safe" from an error.
+ */
+async function holdsGitDir(dir) {
+    try {
+        await lstat(join(dir, '.git'));
+        return true;
+    }
+    catch (err) {
+        const code = err.code;
+        return !(code === 'ENOENT' || code === 'ENOTDIR');
+    }
+}
+/** The paths a `ls-files --stage -z` listing records as gitlinks. */
+function gitlinkPaths(staged) {
+    return staged
+        .split('\0')
+        .filter((entry) => entry.startsWith(`${GITLINK_MODE} `))
+        .map((entry) => entry.slice(entry.indexOf('\t') + 1));
+}
+/**
+ * A workspace snapshotted into a git object store that is not the workspace's own repository.
+ *
+ * Every operation names `--git-dir` and `--work-tree` explicitly, so nothing here can write to a
+ * real `.git`, and the workspace never learns it is being recorded.
+ */
+export class ShadowIndex {
+    gitDir;
+    workTree;
+    forced;
+    constructor(gitDir, workTree, 
+    /** See {@link ShadowIndexOptions.forced}. Empty for every ordinary workspace. */
+    forced = []) {
+        this.gitDir = gitDir;
+        this.workTree = workTree;
+        this.forced = forced;
+    }
+    /** Named once each, however many snapshots a run takes. See {@link dropForcedGitlinks}. */
+    reportedGitlinks = new Set();
+    skipped = [];
+    /** The same, for the ones git could not index at all. See {@link addAll}. */
+    reportedUncommitted = new Set();
+    uncommitted = [];
+    /** The same, for declared paths inside a nested repository. See {@link addForced}. */
+    reportedInside = new Set();
+    inside = [];
+    /**
+     * Nested repositories the last snapshot dropped from a declared artifact path, the first time
+     * each is seen. Empty on every ordinary snapshot.
+     */
+    get skippedGitlinks() {
+        return this.skipped;
+    }
+    /**
+     * Nested repositories the last snapshot could not hold at all, the first time each is seen —
+     * they have no commit, so git has no id to record them by. See {@link addAll}.
+     *
+     * Reported for the same reason {@link gitlinks} is: this store holds nothing of what is inside
+     * them, so a restore puts nothing back there, and whoever is about to run an agent over this
+     * directory needs to know that before it starts rather than afterwards.
+     */
+    get uncommittedNested() {
+        return this.uncommitted;
+    }
+    /**
+     * Declared artifact paths the last snapshot could not hold because each sits inside a nested
+     * repository, with the repository, the first time each path is seen. Empty on every ordinary
+     * snapshot; see `enclosingRepository` for why git cannot be asked.
+     *
+     * The repository matters as much as the path: it is the thing a reset reaching inside it would
+     * destroy with no copy anywhere, since this store holds nothing of what a nested repository
+     * holds — see {@link uncommittedNested}, which says the same of the ones git could not name.
+     */
+    get forcedInsideNested() {
+        return this.inside;
+    }
+    static async isAvailable() {
+        return gitAvailable();
+    }
+    static async create(opts) {
+        if (!(await gitAvailable()))
+            throw new Error(GIT_MISSING_MESSAGE);
+        const { gitDir, workTree, forced = [] } = opts;
+        await mkdir(gitDir, { recursive: true });
+        const init = await runGit(['init', '--bare', '-q', gitDir]);
+        if (init.code !== 0) {
+            throw new Error(`failed to create shadow git dir at ${gitDir}: ${init.stderr.trim()}`);
+        }
+        // Byte fidelity on materialize, and no chance of git running a filesystem-monitor hook.
+        const settings = [
+            ['core.autocrlf', 'false'],
+            ['core.eol', 'lf'],
+            ['core.fsmonitor', 'false'],
+            ['gc.auto', '0'],
+        ];
+        for (const [key, value] of settings) {
+            await runGit(['config', key, value], { gitDir });
+        }
+        await mkdir(join(gitDir, 'info'), { recursive: true });
+        await writeFile(join(gitDir, 'info', 'exclude'), `${SENSITIVE_PATTERNS.join('\n')}\n`, 'utf8');
+        return new ShadowIndex(gitDir, workTree, [...forced]);
+    }
+    opts(extra = {}) {
+        return {
+            gitDir: this.gitDir,
+            workTree: this.workTree,
+            cwd: this.workTree,
+            indexFile: join(this.gitDir, 'index'),
+            ...extra,
+        };
+    }
+    async run(args, extra) {
+        const res = await runGit(args, this.opts(extra));
+        if (res.code !== 0) {
+            throw new Error(`git ${args[0] ?? ''} failed (${res.code}): ${res.stderr.trim()}`);
+        }
+        return res.stdout;
+    }
+    /**
+     * Stages the whole work tree and returns the resulting tree id. No commit is created.
+     *
+     * A second `add -f` covers the paths an adapter declared, and only those. `-f` is what overrides
+     * the workspace's `.gitignore`, which is otherwise honoured — right for a coding agent, where
+     * the ignored paths are build output, and wrong for a pipeline, where the ignored directory is
+     * the whole product. IndexRAG's first three ignore lines are `vector_store/`, `cache/` and
+     * `dataset/`; without this a recording of an indexing run holds every call that built the index
+     * and not one byte of the index.
+     *
+     * `SENSITIVE_PATHSPECS` is repeated on the forced add deliberately: a pathspec exclusion is
+     * applied by `git add` itself and no `-f` overrides it, so an adapter that declares `.` to try
+     * to sweep a secret in still cannot stage `.env`. That is what makes this safe to hand to
+     * third-party plugin code.
+     */
+    async snapshot() {
+        this.skipped = [];
+        this.uncommitted = [];
+        this.inside = [];
+        await this.addAll();
+        if (this.forced.length > 0)
+            await this.addForced();
+        return (await this.run(['write-tree'])).trim();
+    }
+    /**
+     * One `git add`, retried past every nested repository git cannot index at all.
+     *
+     * A NESTED REPOSITORY WITH NO COMMIT STOPS `git add` DEAD. Git stores an embedded repository as
+     * a gitlink, which is the id of its HEAD commit; one that has never been committed to has no
+     * HEAD, so git answers `error: '<path>/' does not have a commit checked out` and then
+     * `fatal: adding files failed` — exit 128, the whole add abandoned, and the index left empty.
+     * That shape is not exotic: it is what `git init` in a subdirectory leaves behind, which is what
+     * anyone starting a second project inside their workspace has until they make the first commit.
+     *
+     * Measured on agenticreplay before this, both times it can happen:
+     *
+     *   - there while recording — every turn's snapshot threw, so the trace held no `fs.snapshot`
+     *     at all, and the replay then read that absence as `--no-fs` and told the operator the run
+     *     was "recorded with --no-fs" when nobody had passed it
+     *   - appearing before a replay — the SAFETY snapshot threw, so `agenticreplay replay` exited 1 with
+     *     git's own sentence about a commit checked out, having already made its `agenticreplay-safety-*`
+     *     scratch directory, which nothing then removed and nothing printed the path of
+     *
+     * Left out and named, which is what git already does with a nested repository that HAS a commit:
+     * that one is stored as a gitlink whose contents this store never holds, and everything
+     * downstream — `replay.nested_kept`, `assertRestorable`, the restore's own note — exists to say
+     * so. One without a commit is the same fact about the same directory, so it is reported the same
+     * way rather than made a fatal error. See {@link uncommittedNested}.
+     *
+     * ONE AT A TIME, because git names one and stops: with three of them the first add named only
+     * the first, and excluding it made the next add fail on the second. So this re-adds until git is
+     * satisfied, and gives up the moment a failure names nothing new — every other failure comes
+     * back to the caller with git's own words, to be judged exactly as before.
+     *
+     * `:(exclude,literal)` rather than a bare `:(exclude)`: the path arrives from git's message as
+     * 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,
+     * while `:(exclude,literal)a*` took out only a path named exactly that. So a nested repository
+     * called `a*` — a legal name on POSIX, not on Windows — would quietly drop its neighbours from
+     * the snapshot. A name holding `[` does not, as it happens: git compares the leading directory
+     * literally before it ever wildmatches, so `my [new] project` excludes only itself either way.
+     * `literal` is used for every one of them because which characters a name holds is not this
+     * code's to know.
+     */
+    async addSkippingCommitless(args) {
+        const excluded = [];
+        for (;;) {
+            const res = await runGit([...args, ...excluded.map((path) => `:(exclude,literal)${path}`), ...SENSITIVE_PATHSPECS], this.opts());
+            if (res.code === 0)
+                return { res, excluded };
+            const named = commitlessNested(res.stderr).filter((path) => !excluded.includes(path));
+            if (named.length === 0)
+                return { res, excluded };
+            excluded.push(...named);
+        }
+    }
+    async addAll() {
+        const { res, excluded } = await this.addSkippingCommitless(['add', '-A', '--', '.']);
+        if (res.code !== 0)
+            throw new Error(`git add failed (${res.code}): ${res.stderr.trim()}`);
+        this.noteUncommitted(excluded);
+    }
+    /**
+     * Remember which of these are new to this store, so a run names each once however many snapshots
+     * it takes, and accumulate within one snapshot — the ordinary add and the forced add can each
+     * meet one the other cannot see.
+     */
+    noteUncommitted(paths) {
+        const fresh = paths.filter((path) => !this.reportedUncommitted.has(path));
+        for (const path of fresh)
+            this.reportedUncommitted.add(path);
+        this.uncommitted = [...new Set([...this.uncommitted, ...fresh])].sort();
+    }
+    /**
+     * Stage the declared paths, tolerating the ones that do not exist yet — and only those.
+     *
+     * `git add` refuses a pathspec that matches nothing — "did not match any files" — and every
+     * run's snapshot 0 is taken before the harness has written anything, so one missing directory
+     * would fail the whole add and lose the paths that *were* there. One call in the ordinary case;
+     * the retry only runs while the product is still being built.
+     *
+     * Every *other* non-zero exit is a real failure, and telling the two apart is the whole reason
+     * to read the retry's result rather than discard it. A file inside the ignored directory that
+     * git cannot open — the harness still writing `cache/`, an editor or a scanner holding it,
+     * EACCES, a path too long on Windows — exits non-zero for an unrelated reason, and `runGit`
+     * resolves rather than throws, so nothing upstream could notice. What that produced was a
+     * snapshot silently missing the paths the adapter declared: a trace holding every call that
+     * built an index and no byte of the index, with no warning anywhere. Worse on the replay side,
+     * where the same hole lands in the safety snapshot `resetArtifacts` depends on — agenticreplay may delete
+     * only what it took a copy of first, so a failure it cannot account for stops the snapshot here.
+     *
+     * Stopping is safe at both call sites: `snapshotWithRetry` turns a throw during recording into
+     * one skipped checkpoint and an `fs.snapshot_failed` warning, and `replayWorkspace` takes its
+     * safety snapshot before anything destructive has happened.
+     */
+    async addForced() {
+        // The declared paths inside a nested repository are set aside before git sees them: git stages
+        // nothing inside another repository, and asked to anyway it either dies or says nothing — see
+        // `enclosingRepository`. They are named instead, and the rest are captured as before.
+        const reachable = [];
+        const inside = [];
+        for (const path of this.forced) {
+            const repository = await enclosingRepository(this.workTree, path);
+            if (repository === undefined)
+                reachable.push(path);
+            else
+                inside.push({ path, repository });
+        }
+        this.noteInside(inside);
+        // Nothing left to add, and nothing to drop: `ls-files -- <no paths>` lists the whole index, and
+        // dropping every gitlink in it would take the workspace's own nested repositories out of the
+        // snapshot along with the ones this method is about.
+        if (reachable.length === 0)
+            return;
+        // Both adds go through the same loop, because they see different things: `-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 nested repository the first add could not.
+        const left = [];
+        const together = await this.addSkippingCommitless(['add', '-f', '--', ...reachable]);
+        left.push(...together.excluded);
+        if (together.res.code !== 0) {
+            for (const path of reachable) {
+                const one = await this.addSkippingCommitless(['add', '-f', '--', path]);
+                left.push(...one.excluded);
+                if (one.res.code === 0 || matchedNothing(one.res.stderr))
+                    continue;
+                throw new Error(`git add failed for the declared artifact path '${path}' (${one.res.code}): ` +
+                    one.res.stderr.trim());
+            }
+        }
+        this.noteUncommitted(left);
+        await this.dropForcedGitlinks(reachable);
+    }
+    /** Named once each, however many snapshots a run takes, and keyed by the declared path. */
+    noteInside(entries) {
+        const fresh = entries.filter((entry) => !this.reportedInside.has(entry.path));
+        for (const entry of fresh)
+            this.reportedInside.add(entry.path);
+        this.inside = fresh;
+    }
+    /**
+     * Unstage any nested repository the forced add just recorded as a gitlink.
+     *
+     * `-f` reaches paths the workspace ignores, and an ignored directory is exactly where a cloned
+     * corpus sits — `dataset/` is one of IndexRAG's declared paths and the ordinary place to
+     * `git clone` a corpus into. `git add` stores such a directory as a gitlink whose contents live
+     * nowhere in this store, and {@link materialize} refuses a tree holding one rather than checking
+     * out an empty directory in its place. Before the forced add those paths were never staged, so
+     * the restore worked; leaving them staged makes every restore of that workspace fail — including
+     * the one `agenticreplay replay` performs *after* deleting the artifacts it could then no longer put back.
+     *
+     * Dropped rather than refused, because the other declared paths are still worth capturing and a
+     * recording missing a cloned corpus is a far smaller loss than one that cannot be replayed at
+     * all. {@link skippedGitlinks} names them, once each, so a run can say so rather than quietly
+     * omit them — which is the failure the rest of this method exists to stop repeating.
+     */
+    async dropForcedGitlinks(paths) {
+        const staged = await this.run(['ls-files', '--stage', '-z', '--', ...paths]);
+        const links = gitlinkPaths(staged);
+        for (const path of links) {
+            await this.run(['update-index', '--force-remove', '--', path]);
+        }
+        const fresh = links.filter((path) => !this.reportedGitlinks.has(path));
+        for (const path of fresh)
+            this.reportedGitlinks.add(path);
+        this.skipped = fresh;
+    }
+    async diff(fromTree, toTree) {
+        // --raw and --numstat accumulate into one report; --name-status would *replace* --numstat,
+        // which is why the status letters are read out of the raw block instead.
+        const out = await this.run([
+            'diff-tree',
+            '-r',
+            '-M',
+            '-z',
+            '--raw',
+            '--numstat',
+            fromTree,
+            toTree,
+        ]);
+        const tokens = out.split('\0');
+        let cursor = 0;
+        const records = [];
+        while (cursor < tokens.length) {
+            const token = tokens[cursor];
+            if (token === undefined)
+                break;
+            if (token === '') {
+                cursor += 1;
+                continue;
+            }
+            if (!token.startsWith(':'))
+                break;
+            const fields = token.split(' ');
+            const letter = (fields[fields.length - 1] ?? 'M').charAt(0);
+            cursor += 1;
+            const first = tokens[cursor++] ?? '';
+            if (letter === 'R' || letter === 'C') {
+                records.push({ letter, oldPath: first, path: tokens[cursor++] ?? '' });
+            }
+            else {
+                records.push({ letter, path: first });
+            }
+        }
+        const counts = new Map();
+        while (cursor < tokens.length) {
+            const token = tokens[cursor];
+            cursor += 1;
+            if (token === undefined)
+                break;
+            if (token === '')
+                continue;
+            const fields = token.split('\t');
+            const insertions = toCount(fields[0]);
+            const deletions = toCount(fields[1]);
+            // A rename leaves the path field empty and follows with old and new paths as their own
+            // records, because a NUL-separated numstat cannot hold two paths in one field.
+            let path = fields[2] ?? '';
+            if (path === '') {
+                cursor += 1;
+                path = tokens[cursor++] ?? '';
+            }
+            counts.set(path, { insertions, deletions });
+        }
+        // Second pass, ignoring carriage returns at end of line. A file that reports changes in the
+        // first pass and none in this one changed only its line endings. Run once for the whole diff
+        // rather than per file, so the cost is one extra git invocation however many files moved.
+        const contentful = await this.changedIgnoringEol(fromTree, toTree);
+        return records.map((record) => {
+            const count = counts.get(record.path) ?? { insertions: 0, deletions: 0 };
+            const change = {
+                path: record.path,
+                status: statusOf(record.letter),
+                insertions: count.insertions,
+                deletions: count.deletions,
+            };
+            if (record.oldPath !== undefined)
+                change.oldPath = record.oldPath;
+            if (contentful !== undefined &&
+                change.status === 'modified' &&
+                count.insertions + count.deletions > 0 &&
+                !contentful.has(record.path)) {
+                change.eolOnly = true;
+            }
+            return change;
+        });
+    }
+    /**
+     * Paths that still differ once a trailing carriage return is not counted as a difference, or
+     * undefined when this git cannot answer — in which case nothing is annotated, which is better
+     * than claiming a real edit was only line endings.
+     */
+    async changedIgnoringEol(fromTree, toTree) {
+        try {
+            const out = await this.run([
+                'diff-tree',
+                '-r',
+                '-M',
+                '-z',
+                '--numstat',
+                '--ignore-cr-at-eol',
+                fromTree,
+                toTree,
+            ]);
+            const paths = new Set();
+            for (const token of out.split('')) {
+                if (token === '')
+                    continue;
+                const fields = token.split('	');
+                const path = fields[2];
+                if (path !== undefined && path !== '')
+                    paths.add(path);
+            }
+            return paths;
+        }
+        catch {
+            // An older git without --ignore-cr-at-eol.
+            return undefined;
+        }
+    }
+    async patch(fromTree, toTree, path) {
+        const args = ['diff-tree', '-r', '-M', '-p', fromTree, toTree];
+        if (path !== undefined)
+            args.push('--', path);
+        return this.run(args);
+    }
+    async readFileAt(tree, path) {
+        const res = await runGitRaw(['cat-file', 'blob', `${tree}:${path}`], this.opts());
+        if (res.code !== 0) {
+            throw new Error(`cannot read ${path} at tree ${tree}: ${res.stderr.trim()}`);
+        }
+        return new Uint8Array(res.stdout);
+    }
+    /**
+     * Writes the whole tree into `destDir`, which should be fresh: files already there that the tree
+     * does not name are left where they are. Fork replay debugs whatever this produces, so it refuses
+     * a tree holding a nested repository: `git add` records those as a gitlink whose contents were
+     * never stored, and checkout would silently leave an empty directory in their place.
+     */
+    /**
+     * What is on disk under `paths` that the last snapshot did not take a copy of.
+     *
+     * Asked of the index the snapshot wrote, so it answers for that snapshot exactly: anything git
+     * calls "other" under these paths is a file in the work tree with no entry in it. Two rules put
+     * things there and both are deliberate — `SENSITIVE_PATHSPECS` keeps credentials out of a trace
+     * however an adapter declares its paths, and {@link dropForcedGitlinks} removes a nested
+     * repository whose contents no snapshot can hold — which is precisely why the answer has to be
+     * available to a caller about to delete these paths on the strength of that copy.
+     *
+     * A nested repository comes back as the directory, with a trailing slash, because git will not
+     * look inside one. That is the honest shape of the answer: what is missing is everything under
+     * it.
+     */
+    async uncaptured(paths) {
+        if (paths.length === 0)
+            return [];
+        const out = await this.run(['ls-files', '--others', '-z', '--', ...paths]);
+        return out.split('\0').filter((path) => path !== '');
+    }
+    /**
+     * The nested repositories a tree records as gitlinks, whose contents this store never held.
+     *
+     * {@link materialize} refuses such a tree; this answers the same question without writing a
+     * byte, so a caller about to do something irreversible can find out *before* doing it rather
+     * than from the exception afterwards. See `replayWorkspace`, where the reset the restore is
+     * supposed to undo runs before the restore.
+     */
+    async gitlinks(tree) {
+        const indexFile = join(this.gitDir, `gitlinks-${randomBytes(8).toString('hex')}.index`);
+        try {
+            await this.run(['read-tree', tree], { indexFile });
+            return gitlinkPaths(await this.run(['ls-files', '--stage', '-z'], { indexFile }));
+        }
+        finally {
+            await rm(indexFile, { force: true });
+        }
+    }
+    /**
+     * Is this tree actually in the store?
+     *
+     * Same posture as {@link gitlinks}: ask before doing something that would otherwise fail from
+     * inside git, with a message about object names that says nothing about the cause.
+     *
+     * The cause worth naming is a run whose store is not all there: one pulled from a gateway it was
+     * pushed to without `--fs` — the archive then carries manifest.json, events.jsonl,
+     * redactions.json and blobs/, not this store — or one whose store `agenticreplay scrub --drop-fs`
+     * deleted. Either way its `fs.snapshot` events name trees whose objects are not here.
+     * {@link materialize} on one of those dies in `read-tree`, and the caller has no way to tell
+     * that from a corrupt store.
+     */
+    async has(tree) {
+        const res = await runGitRaw(['cat-file', '-e', `${tree}^{tree}`], this.opts());
+        return res.code === 0;
+    }
+    /**
+     * The files a tree records — blobs only, so a nested repository's gitlink is not among them —
+     * each with the id of the bytes it holds.
+     *
+     * What a {@link materialize} of the tree will write, asked without writing it: a caller about to
+     * restore a tree over a directory can check each path against the copy it took first, and can
+     * tell afterwards whether what stands at a path is still what the tree put there.
+     */
+    async files(tree) {
+        const listed = await this.run(['ls-tree', '-r', '-z', '--full-tree', tree]);
+        const files = [];
+        for (const entry of listed.split('\0')) {
+            const tab = entry.indexOf('\t');
+            const [, type, oid] = entry.slice(0, tab).split(' ');
+            if (type === 'blob' && oid !== undefined)
+                files.push({ path: entry.slice(tab + 1), oid });
+        }
+        return files;
+    }
+    async materialize(tree, destDir, opts = {}) {
+        await mkdir(destDir, { recursive: true });
+        const indexFile = join(this.gitDir, `materialize-${randomBytes(8).toString('hex')}.index`);
+        try {
+            await this.run(['read-tree', tree], { indexFile });
+            const gitlinks = gitlinkPaths(await this.run(['ls-files', '--stage', '-z'], { indexFile }));
+            if (gitlinks.length > 0 && opts.allowIncomplete !== true) {
+                throw new Error(`cannot materialize tree ${tree} byte for byte: it contains embedded git ` +
+                    `repositories whose contents were never captured (${gitlinks.join(', ')}). ` +
+                    'Ignore or remove them in the workspace, or pass allowIncomplete to accept the gap.');
+            }
+            await this.run(['checkout-index', '-a', '-f'], {
+                indexFile,
+                workTree: destDir,
+                cwd: destDir,
+            });
+        }
+        finally {
+            await rm(indexFile, { force: true });
+        }
+    }
+}
+//# sourceMappingURL=shadow.js.map