Auto-Fingerprinting

Auto-fingerprinting eliminates the need for manual input configuration. Instead of declaring which files affect a task, the runner automatically tracks which files a task actually accesses during execution.

How It Works

1. First run - Execute the task while tracking file system access
2. Record fingerprint - Store content hashes of all accessed files
3. Subsequent runs - Validate the fingerprint against current file state
4. Cache hit - If all files are unchanged, replay cached result
5. Cache miss - Re-execute and update the fingerprint

Enable Auto-Fingerprinting

const results = await defaultTaskRunner(
    tasks,
    {
        autoFingerprint: true,
        fingerprintEnvPatterns: ["VITE_*", "NODE_ENV"],
        cacheDiagnostics: true,
    },
    context,
);

What Gets Tracked

The fingerprint captures:

• File reads - Content hashes of all files opened during execution
• Missing files - Files that were probed but didn't exist (creating them later invalidates the cache)
• Directory listings - If a command scans a directory (e.g., glob for *.test.ts), adding/removing files invalidates the cache
• Environment variables - Matching the configured patterns
• Command arguments - Task overrides and configuration

File Access Tracking

On Linux, file accesses are tracked via strace intercepting open, openat, creat, stat, access, unlink, rename, and related syscalls. On other platforms, a preload script patches fs / fs/promises calls.

Both backends classify accesses as read, stat, readdir, write, or missing. Writes are used for self-modifying task detection.

Self-modifying task detection

When a task both reads and writes the same workspace-relative file (e.g. a tsc --build invocation that updates its own .tsbuildinfo), caching that task's output would capture post-write state and guarantee false cache hits on subsequent runs.

The fingerprint manager populates a modifiedInputs field with every path seen as both read and write. The orchestrator skips the cache write for that task and fires printSelfModifyingSkip(task, modifiedFiles) so the UI can explain the skip. The next run re-executes from scratch.

In Nx-style (non-auto-fingerprint) mode, the orchestrator re-hashes every declared input after execution and compares against the pre-run hash — same effect without needing write tracking.

Empty-fingerprint safety net

Static binaries on platforms without strace (esbuild on macOS/Windows, Rust/Go tools) can bypass the preload script entirely, which means the tracker returns zero file accesses. Persisting that empty fingerprint would produce a false cache hit on every subsequent run.

When the real tracker is used but returns zero workspace accesses, the orchestrator:

1. Skips the cache write.
2. Sets result.emptyFingerprint = true.
3. Fires printEmptyFingerprintWarning(task, reason) — implementers typically print a hint to add the task's inputs explicitly or fall back to Nx-style declarations.

This closes the "silent stale cache" class of bugs without needing a full fspy-style native syscall interceptor.

Cache Miss Diagnostics

When cacheDiagnostics is enabled, the runner explains exactly why a cache miss occurred:

Cache miss reasons:
  - File modified: src/index.ts
  - Environment variable changed: NODE_ENV
  - Directory contents changed: src/components

Untracked Environment Variables

Some env vars should be available to tasks but not affect the cache (e.g., CI build IDs):

{
    autoFingerprint: true,
    fingerprintEnvPatterns: ["VITE_*", "CI_*"],
    untrackedEnvVars: ["CI_BUILD_ID", "CI_JOB_URL"],
}

Comparison with Nx-style