Add --trace flag for automatic file access tracing#18
Merged
Conversation
When running with `taskrunner --trace`, the subprocess is wrapped with fsatrace (LD_PRELOAD-based file system tracer) to discover which files are actually read and written during execution. After the command finishes, a report is printed to stderr showing project-relative file paths categorized as reads and writes. This helps verify that snapshot inputs are complete — e.g. running `--trace --force` on the docs BUILD script revealed that mdbook reads 56 files from apps/ and libs/ that aren't declared in the snapshot. Trace mode propagates to nested taskrunner calls via _taskrunner_trace env var. Requires fsatrace to be installed (clear error if missing). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Internal git metadata files aren't meaningful project inputs. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
…etection --trace now shows a directory-level summary by default (e.g. "apps/ (51 files)") instead of listing every individual file. Use --trace-files for the full file list. Both modes also compare traced reads against declared snapshot inputs and report discrepancies — files actually read but not covered by the snapshot. For example, docs BUILD declares `snapshot .` (= docs/) but mdbook reads from apps/ and libs/. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
These are not meaningful project inputs: - .gitignore files at any depth (e.g. libs/hs/re-geo/.gitignore) - .git bare path (was only filtering .git/ prefix) - .taskrunner/ internal state directory Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The parent fsatrace already traces the entire process tree via LD_PRELOAD inheritance, so nested taskrunner calls don't need to independently wrap with fsatrace. This was causing duplicate trace report sections in the output — one per nested taskrunner invocation. Now only the outermost --trace/--trace-files invocation wraps and reports. The _taskrunner_trace env var is still propagated but no longer triggers tracing on its own. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
zyla
approved these changes
Apr 12, 2026
Collaborator
zyla
left a comment
zyla
left a comment
There was a problem hiding this comment.
Neat.
Maybe add a test for nested task?
…alls Ensures that when an outer taskrunner with --trace invokes a nested taskrunner, only one File System Trace Report section is produced, and it captures file operations from both outer and inner processes (since fsatrace's LD_PRELOAD inherits to all children). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds
--traceand--trace-filesflags that wrap command execution with fsatrace (LD_PRELOAD-based file system tracer) to automatically discover which files are read/written during task execution. This helps verify thatsnapshotinputs are complete.Inspired by Rattle, which uses the same mechanism for automatic dependency tracking in build systems.
Features
1. Directory summary (default with
--trace)2. Full file listing (
--trace-files)3. Snapshot discrepancy detection
Automatically compares traced reads against declared snapshot inputs and flags gaps:
Changes
--traceCLI flag: directory-level summary + discrepancy detection--trace-filesCLI flag: individual file listing + discrepancy detectionsrc/Trace.hsmodule: fsatrace detection, command wrapping, output parsing, filtering, report formatting, discrepancy analysis.git/,.gitignorefiles,.taskrunner/, system paths--traceinvocation reports — nested taskrunner calls don't produce duplicate sections (parent fsatrace traces the entire process tree via LD_PRELOAD)# fsatracedirective in golden tests, auto-skip when fsatrace isn't installedReal-world example: docs BUILD discrepancy
The docs
snapshot .declares only thedocs/directory as input, butmdbook buildactually reads 55 files fromapps/andlibs/(gathered READMEs and docs from across the monorepo). A change to e.g.apps/higgs/docs/LiveQuery.mdwould not invalidate the cache.Test plan
stack build— compiles cleanly, no warningsstack test— all 38 tests pass (37 existing + 1 new trace-basic)docs/scripts/BUILD— found real discrepancyhiggs/marketing-calendar— single report section, no duplicates🤖 Generated with Claude Code