v2-sampler wakes on fs.watch events under .builders/. Filesystem watchers fire in bursts, so a builder running an install, a test suite or a build can wake the hierarchy walk thousands of times in a few seconds.
Why this is a fix rather than an investigation
#77 was originally opened to measure whether this actually costs CPU. Closed without measuring, because the measurement could not change the action: if it proved expensive the answer is debouncing, and if it proved cheap debouncing is still correct. Watchers coalesce badly by nature; that is a property of the mechanism, not a property of this workload.
The work
Debounce the watch-driven wake in packages/codev/src/agent-farm/servers/v2-sampler.ts.
- Coalesce a burst into one walk. A trailing debounce in the tens of milliseconds is the usual shape; pick a number and say why.
- Do not debounce the 30-second tick. It is already the slow path and it is what guarantees liveness when no filesystem event arrives.
- Preserve the latency criterion. Spec 52 criterion 2 requires a spawned builder to produce a delta within 500ms with no client timer involved. A debounce window that pushes past that trades one defect for another.
- Do not let a long burst starve the walk entirely. A pure trailing debounce under sustained churn can defer indefinitely. Either cap the deferral or use a leading-plus-trailing shape so state still moves during a long install.
That last point is the one worth getting right. Under a pnpm install the events do not stop, and a naive trailing debounce means the tree stops updating for the entire install, which is precisely when someone is watching it.
Constraints
- Additive-only still applies (FRD Part 0).
v2-sampler.ts is fork-owned, so this is an ordinary edit to our own module. Do not touch tower-server.ts, pty-session.ts, or existing handlers.
- Spec 52's tests are the regression surface. Criterion 2 (500ms spawn delta), scenario 9j (upserts not driven by output volume) and scenario 3 (idle cost) all bear on this.
Reference
v2-samplerwakes onfs.watchevents under.builders/. Filesystem watchers fire in bursts, so a builder running an install, a test suite or a build can wake the hierarchy walk thousands of times in a few seconds.Why this is a fix rather than an investigation
#77 was originally opened to measure whether this actually costs CPU. Closed without measuring, because the measurement could not change the action: if it proved expensive the answer is debouncing, and if it proved cheap debouncing is still correct. Watchers coalesce badly by nature; that is a property of the mechanism, not a property of this workload.
The work
Debounce the watch-driven wake in
packages/codev/src/agent-farm/servers/v2-sampler.ts.That last point is the one worth getting right. Under a
pnpm installthe events do not stop, and a naive trailing debounce means the tree stops updating for the entire install, which is precisely when someone is watching it.Constraints
v2-sampler.tsis fork-owned, so this is an ordinary edit to our own module. Do not touchtower-server.ts,pty-session.ts, or existing handlers.Reference
packages/codev/src/agent-farm/servers/v2-sampler.tscodev/specs/52-v2-server-events.md