Mirror project files via hardlink so Glob/Grep can see them

Claude Code's Glob and Grep are backed by `rg --files`, which skips
symlinks unless `--follow` is passed. The sandbox mirrored individual
files as symlinks, so `rg --files` over the sandbox tree returned zero
results — Glob across patterns like `**/*.tsx` came back empty even when
the project contained hundreds of matching files. Verified on a recent
run: 0 files via `rg --files`, 384 via `rg --files --follow`.

Switch the file mirror from `symlink()` to `link()`, with a `copyFile()`
fallback on EXDEV for projects on a different filesystem from
`~/.mdredd`. Hardlinks are indistinguishable from real files to anything
that walks the FS, so Glob/Grep work natively. The realpath-of-symlink
target validation still happens against the source — link() doesn't
follow symlinks, so we link the realpath rather than the symlink path.

Side effect: realpath() of a hardlinked file in the sandbox stays inside
the sandbox (each hardlink path is a first-class name), unlike symlinks
which leaked the source path. The old "realpath escapes the sandbox"
known-limit goes away.

Author: slaFFik

CLAUDE.md

@@ -62,7 +62,7 @@ Tests are plain tsx scripts, not a framework. Each file declares scenarios via a
 1. **Preflight** (`src/server/preflight.ts`) — verifies the `claude` binary is on PATH and supports the required CLI flags (offline checks: `--version` + `--help` parsing). No live API ping — auth issues surface in the first run's stderr via SSE, which is more diagnosable than a gate-zero blocker on transient API hiccups. Computes a per-project `storageRoot` at `~/.mdredd/projects/<projectKey>/` (`projectKey = sha256(resolve(cwd)).slice(0, 12)`); acquires `<storageRoot>/.lock` via `proper-lockfile` (single-instance per project); writes a `.lock.meta.json` sidecar with pid/port for human debugging. Mass-marks any `preparing`/`streaming` runs from a previous boot as `abandoned` and ensures a `~/.mdredd/.gitignore` exists at the global root.
 2. **Sandbox** (`src/server/sandbox.ts`) — for each run, builds `~/.mdredd/projects/<projectKey>/<runFolder>/project/` as the child `claude` cwd. **This is the central isolation primitive — read its file-level docstring before changing anything.** Key invariants:
    - An **empty `.git/`** is planted on a `sandbox` branch so Claude Code's upward project-root walk terminates inside the run dir. This prevents host git status, branch, recent commits, and per-project auto-memory from leaking into the child's system prompt.
-   - Top-level entries of the user's project are mirrored by recursively walking the source tree, creating real directories on the sandbox side and **symlinking only individual files**. Filtering applies at every level: `HARD_EXCLUDED` (`.git`, `.claude`, `node_modules`, `.DS_Store`), root + nested `.gitignore`, the user's global git excludes file, symlinks whose realpath escapes `cwd`, and symlink cycles.
+   - Top-level entries of the user's project are mirrored by recursively walking the source tree, creating real directories on the sandbox side and **hardlinking individual files** (with a copy fallback on `EXDEV` when source and storage live on different filesystems). Hardlinks rather than symlinks because Claude Code's `Glob` and `Grep` are backed by `rg --files`, which skips symlinks without `--follow` — symlinked leaves would make the entire tree invisible to glob discovery. Filtering applies at every level: `HARD_EXCLUDED` (`.git`, `.claude`, `node_modules`, `.DS_Store`), root + nested `.gitignore`, the user's global git excludes file, source-side symlinks whose realpath escapes `cwd`, and symlink cycles.
    - Filtering subtleties — easy to regress when refactoring `sandbox.ts`: the ignore chain is walked **most-specific to least-specific** using `Ignore.test()` so a nested `!keep.log` overrides a root `*.log` (matches git's per-directory precedence — don't switch to `.ignores()`, which short-circuits and ignores negation). `Mirror.walk` records the **realpath of every directory it descends into** (not only symlink targets), so a symlink pointing back at a real-dir ancestor (`a/b/loop -> a`) is rejected on first encounter rather than after a wasted level of mirroring. Storage-root exclusion uses **realpath** (`realIsStorageRoot` against `classified.realTarget ?? <cwdReal>/<name>`), not the entry's path string — a top-level symlink like `alias -> .storage` would otherwise pass a name-based guard and let the mirror copy the sandbox's own state into a run dir.
    - In `write` mode, a `.claude/settings.json` allows `Write`/`Edit` only against `../outputs/**` (the per-run outputs dir, one level above the child's cwd). Read-only mode passes a tools allowlist of `Read,Glob,Grep,WebSearch,WebFetch`; write mode adds `Write,Edit`.
 3. **Spawn** (`src/server/runner.ts`) — invokes `claude -p <prompt> --output-format stream-json --include-partial-messages --verbose --model <m> --tools <list> --allowedTools <list> --strict-mcp-config --setting-sources project --disable-slash-commands`. The runner **strips** `NODE_OPTIONS`, `GIT_DIR`, `GIT_WORK_TREE`, `GIT_INDEX_FILE`, `GIT_COMMON_DIR`, `GIT_CEILING_DIRECTORIES`, `CLAUDE_PROJECT_DIR`, `CLAUDE_PROJECT_NAME` from the spawn environment so a parent shell can't override the planted sandbox. `HOME` / `CLAUDE_CONFIG_DIR` are kept so the child reads the user's auth.

README.md

@@ -59,7 +59,7 @@ Each variant run gets its own sandbox under `~/.mdredd/projects/<projectKey>/<ru
 │   ├── CLAUDE.md                ← (CLAUDE.md variants) the variant being tested
 │   ├── .claude/skills/<name>/SKILL.md   ← (skill variants)
 │   ├── .claude/agents/<name>.md         ← (agent variants)
-│   └── <top-level entries>      ← symlinked from your project, see below
+│   └── <top-level entries>      ← hardlinked from your project, see below
 ├── outputs/                     ← write target in Write mode; empty in read-only
 ├── variant.md                   ← exact bytes of the variant we ran
 ├── config.json                  ← run config + token usage + cost
@@ -72,13 +72,13 @@ Each variant run gets its own sandbox under `~/.mdredd/projects/<projectKey>/<ru
 ### What the child claude sees
 
 - **The variant file**, written at its canonical path (`CLAUDE.md`, `.claude/skills/<name>/SKILL.md`, or `.claude/agents/<name>.md`).
-- **Symlinks to every top-level entry of your project** that isn't excluded — so `Read`, `Glob`, and `Grep` resolve to your real files. This is intentional: it keeps stack detection realistic, so skills like `pest-testing`, `inertia-react-development`, etc. that Claude Code auto-suggests from `composer.json` / `package.json` still load the way they would in a real session.
+- **A mirror of every top-level entry of your project** that isn't excluded: directories are recreated, individual files are hardlinked back to your sources (copy fallback when source and `~/.mdredd` live on different filesystems). `Read`, `Glob`, and `Grep` therefore see real files at every leaf — Claude Code's ripgrep-backed `Glob`/`Grep` skip symlinks without `--follow`, so hardlinks rather than symlinks are required for glob discovery to work at all. Stack detection stays realistic: skills like `pest-testing`, `inertia-react-development`, etc. that Claude Code auto-suggests from `composer.json` / `package.json` still load the way they would in a real session.
 - **Your global Claude Code auth** (`HOME` / `CLAUDE_CONFIG_DIR` are passed through unmodified) so the child can talk to the API.
 - **Your user-global instructions at `~/.claude/CLAUDE.md`** and any user-global skills/agents/plugins/MCP servers you have installed — these are part of "how Claude behaves on your machine" and are deliberately not stripped.
 
 ### What the child claude does **not** see
 
-- **Your project's real `.git/`.** A self-contained empty `.git/` is planted in the sandbox before any symlinks, so Claude Code's upward project-root walk terminates inside the run folder. Result: `git status` is clean, `git branch --show-current` returns `sandbox`, `git log` reports no commits — none of your branch name, working-tree status, or recent commit subjects can be auto-injected into the child's system prompt.
+- **Your project's real `.git/`.** A self-contained empty `.git/` is planted in the sandbox before any files are mirrored, so Claude Code's upward project-root walk terminates inside the run folder. Result: `git status` is clean, `git branch --show-current` returns `sandbox`, `git log` reports no commits — none of your branch name, working-tree status, or recent commit subjects can be auto-injected into the child's system prompt.
 - **Your project's auto-memory.** Because Claude Code derives the per-project memory directory (`~/.claude/projects/<encoded-cwd>/memory/`) from where it found `.git`, the planted sandbox `.git/` redirects this lookup to a per-run path that's empty by default. Your project's accumulated `feedback_*.md` / `project_*.md` notes do not bleed in.
 - **Your project's `.claude/` directory.** Hard-excluded so an on-disk skill or agent file with the same name can't shadow the variant under test.
 - **mdredd's own storage** (`~/.mdredd/`), to keep variant runs out of each other's sandboxes.
@@ -95,4 +95,4 @@ Two artifacts make this auditable:
 ### Known limits
 
 - A baseline ~5–10k cache-creation tokens still come from Claude Code's own system prompt, tool schemas, and your user-global config (`~/.claude/CLAUDE.md`, user-level skills). That overhead is the same for every variant in a session, so it cancels out in A/B comparisons — but it's not zero.
-- Symlinks mean `realpath()` of any file inside the sandbox resolves outside it. If a future Claude Code version starts using `realpath` for project resolution instead of `.git` walking, the planted `.git/` won't catch that path. Watch `init.json`'s `memory_paths.auto` after Claude Code updates.
+- Hardlinks share an inode with your source files. The planted `.claude/settings.json` deny rules (`Write(**)`, `Edit(**)` with a single `../outputs/**` allow) keep the child from writing to anything but the per-run outputs directory, so this isolation is path-based and survives the inode sharing — but if you ever loosen those rules in your fork, writes through the sandbox path will modify the underlying source file.

src/server/sandbox.ts

@@ -1,4 +1,4 @@
-import { lstat, readdir, readFile, realpath, symlink, writeFile } from 'node:fs/promises';
+import { copyFile, link, lstat, readdir, readFile, realpath, writeFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { join, sep } from 'node:path';
 import ignore, { type Ignore } from 'ignore';
@@ -30,15 +30,19 @@ export interface SandboxResult {
  *
  *   <storageRoot>/<runFolder>/
  *     project/           ← child claude's cwd
- *       <user's cwd mirrored as a tree of real dirs + per-file symlinks>
+ *       <user's cwd mirrored as a tree of real dirs + per-file hardlinks>
  *       CLAUDE.md or .claude/skills/<name>/SKILL.md or .claude/agents/<name>.md
  *       .claude/settings.json  (write mode only)
  *     outputs/           ← write target for write mode; empty in read-only
  *
  * The mirror walks the source tree recursively, creating real directories on
- * the sandbox side and symlinking only individual files. This lets us apply
- * filtering (gitignore, hard-exclude, symlink-target validation) at every
- * level, not just at the top.
+ * the sandbox side and hardlinking individual files (falling back to copy on
+ * EXDEV when the storage root sits on a different filesystem from the source).
+ * This lets us apply filtering (gitignore, hard-exclude, symlink-target
+ * validation) at every level, not just at the top. Hardlinks rather than
+ * symlinks because Claude Code's `Glob` and `Grep` tools are backed by
+ * `rg --files`, which skips symlinks unless `--follow` is passed — symlinking
+ * the leaves makes the entire tree invisible to glob-based discovery.
  *
  * Filtered at every level:
  *   - HARD_EXCLUDED entries (`.git`, `.claude`, `node_modules`, `.DS_Store`)
@@ -217,10 +221,18 @@ class Mirror {
       await this.walk(walkSource, subDest, rel, chain, nextAncestors, false);
       this.recordMirror(isTopLevel, name);
     } else if (classified.isFile) {
-      // Symlink the file itself. For symlink-to-file entries we point at the
-      // realpath rather than re-creating an indirect chain — the realpath was
-      // already verified to be inside cwd above.
-      await symlink(classified.realTarget ?? source, join(dest, name));
+      // Link the realpath rather than the source path. `link()` does not
+      // follow symlinks, so a symlink-to-file source would otherwise produce
+      // another symlink-leaf and reproduce the rg-can't-see-symlinks bug
+      // the file-level docstring describes. Realpath was verified above.
+      const linkSource = classified.realTarget ?? source;
+      const linkDest = join(dest, name);
+      try {
+        await link(linkSource, linkDest);
+      } catch (err) {
+        if ((err as NodeJS.ErrnoException).code !== 'EXDEV') throw err;
+        await copyFile(linkSource, linkDest);
+      }
       this.recordMirror(isTopLevel, name);
     } else {
       this.recordSkip(isTopLevel, name, 'unsupported file type');

test/sandbox.spec.ts

@@ -1,4 +1,14 @@
-import { mkdir, mkdtemp, readFile, readdir, rm, stat, symlink, writeFile } from 'node:fs/promises';
+import {
+  lstat,
+  mkdir,
+  mkdtemp,
+  readFile,
+  readdir,
+  rm,
+  stat,
+  symlink,
+  writeFile,
+} from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join, relative } from 'node:path';
 import { buildSandbox } from '../src/server/sandbox.js';
@@ -329,6 +339,57 @@ await scenario('sandbox: read-only mode plants no .claude/settings.json', async
   });
 });
 
+await scenario(
+  'sandbox: regular files are mirrored as hardlinks (visible to rg --files)',
+  async () => {
+    await withCwd(async (cwd) => {
+      // ripgrep-backed Glob/Grep skip symlinks without --follow. Hardlinking
+      // leaves makes the sandbox tree indistinguishable from a real one to
+      // anything that walks the filesystem.
+      await writeFile(join(cwd, 'a.tsx'), 'export {}');
+
+      const sb = await build(cwd);
+      const mirrored = join(sb.projectDir, 'a.tsx');
+      const linkStat = await lstat(mirrored);
+      if (linkStat.isSymbolicLink()) {
+        throw new Error('mirrored regular file should not be a symlink');
+      }
+      const srcStat = await lstat(join(cwd, 'a.tsx'));
+      if (linkStat.ino !== srcStat.ino) {
+        // EXDEV fallback would copy instead — only acceptable when source and
+        // sandbox live on different filesystems. The temp dir helper places
+        // both under tmpdir(), so they should share a filesystem here.
+        throw new Error('hardlink should share inode with source');
+      }
+    });
+  },
+);
+
+await scenario(
+  'sandbox: symlink-to-file is mirrored as a hardlink to the realpath target',
+  async () => {
+    await withCwd(async (cwd) => {
+      // A symlink-to-file inside cwd resolves to a real file we already verified
+      // is inside cwd; the mirror should hardlink the realpath, not the symlink
+      // (linking the symlink would re-create a symlink-leaf and reproduce the
+      // visibility bug we're fixing).
+      await writeFile(join(cwd, 'real.tsx'), 'export {}');
+      await symlink(join(cwd, 'real.tsx'), join(cwd, 'aliased.tsx'));
+
+      const sb = await build(cwd);
+      const mirrored = join(sb.projectDir, 'aliased.tsx');
+      const linkStat = await lstat(mirrored);
+      if (linkStat.isSymbolicLink()) {
+        throw new Error('symlink-to-file should be mirrored as a real file, not a symlink');
+      }
+      const realSrc = await lstat(join(cwd, 'real.tsx'));
+      if (linkStat.ino !== realSrc.ino) {
+        throw new Error('hardlink should share inode with the realpath target');
+      }
+    });
+  },
+);
+
 await scenario('sandbox: top-level symlink to storage root is refused', async () => {
   await withCwd(async (cwd) => {
     // The path-string guard alone misses a symlink whose name doesn't match