Skip to content

Debounce the fs.watch wake path in v2-sampler #78

Description

@pseudoseed

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    area/towerTower, afx, terminals, messagingfork-onlyDeliberately not upstreamed to cluesmith/codev

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions