[wan9chi]

Motivation

A task that creates a symbolic link doesn't have it among its outputs unless an output glob matches it. Nitro's dependency tracer, for example, links .output/server/node_modules/tslib into .nf3. fspy records nothing for symlink, so a hit leaves the link out. When the task checks the path first, as nf3 does, the link is a plain input and a clean checkout misses.

Changes

fspy records the path of a new link as a write, before the call:

• Unix preload: symlink and symlinkat.
• Linux seccomp supervisor: the same calls for static binaries.
• Windows: NtFsControlFile with FSCTL_SET_REPARSE_POINT(_EX), which covers CreateSymbolicLinkW and junctions.

vt needs no change: a written symlink counts as a file, and the archive stores links as links (#885).

E2E cases: symlink_in_output (synthetic, vtt symlink) and nitro_auto_outputs_restore_links (the nitro_build_cache Nitro build with automatic tracking only). Both run only on Unix in the first commit, because Windows already behaves differently there, and on every platform after.

Part of a stack that lets automatic tracking cache tasks which read their own outputs and list the folders holding them, so they also hit on a clean checkout.

🤖 Generated with Claude Code

---

Note

Medium Risk
Changes cross-platform file-access tracing used for cache fingerprints; incorrect recording could cause wrong hits or misses, but scope is limited to symlink/junction creation paths.

Overview
Automatic caching now treats symlinks a task creates as restorable outputs, even when no output glob matches them (e.g. Nitro nf3 links under .output/server/node_modules). Cache hits replay those paths as links, and a later run still hits if the links are missing, like on a fresh clone.

fspy records the new link path as a write before the syscall returns: on Unix via symlink / symlinkat (preload and seccomp), and on Windows via an NtFsControlFile hook when FSCTL_SET_REPARSE_POINT(_EX) runs (symbolic links and junctions). Existing archive/restore behavior for matched outputs is unchanged; this closes the gap where creation was invisible to tracking.

Docs note that Windows junctions count as written symlinks in rebuildable logic. vtt symlink works on Windows for e2e. New fspy and e2e tests cover symlink tracking and Nitro-style auto-tracked link restore.

^{Reviewed by Cursor Bugbot for commit 25a585d. Bugbot is set up for automated code reviews on this repo. Configure here.}

[github-actions]

fspy benchmark

linux

dynamic/launch             change  +0.39%  [ -2.44% ..  +3.21%]  overhead   +55.64%
dynamic/access             change  -0.46%  [ -2.55% ..  +1.39%]  overhead   +12.51%
dynamic/access-relative    change  +0.67%  [ -0.67% ..  +1.85%]  overhead   +61.16%
dynamic/access-contended   change  -0.41%  [ -2.43% ..  +1.80%]  overhead   +15.00%
static/launch              change  +0.90%  [ -1.86% ..  +3.21%]  overhead  +189.72%
static/access              change  +0.43%  [ -0.69% ..  +1.59%]  overhead  +800.47%
static/access-relative     change  +0.35%  [ -0.88% ..  +1.27%]  overhead +1378.84%
static/access-contended    change  +0.46%  [ -0.05% ..  +1.20%]  overhead +3221.20%

macos

dynamic/launch             change  +0.07%  [ -4.15% ..  +5.41%]  overhead  +237.35%
dynamic/access             change  +0.35%  [ -4.63% ..  +4.30%]  overhead    +5.45%
dynamic/access-relative    change  -2.20%  [ -6.17% ..  +4.62%]  overhead  +247.19%
dynamic/access-contended   change  +0.00%  [ -8.11% ..  +5.24%]  overhead    +2.33%

windows

dynamic/launch             change  -0.19%  [ -2.45% ..  +2.02%]  overhead   +24.87%
dynamic/access             change  +0.00%  [ -0.56% ..  +0.56%]  overhead    +1.14%
dynamic/access-relative    change  +0.00%  [ -0.72% ..  +0.91%]  overhead    +1.28%
dynamic/access-contended   change  +0.00%  [ -0.54% ..  +0.36%]  overhead    +1.45%