[maphew]

C2: Deepen watch mode into a debounce module

Beads mdo-6w5.3 · parent epic mdo-6w5 (PR order 3 of 6; stacked on the C6 branch agent/6w5-c6-test-mirror, which stacks on C1)

What

New src/watch.rs (lib crate) owning all three watch-mode mechanics behind one interface:

watch::run(input, render) -> notify::Result<()>

• Registers the parent-directory watch before rendering (a save landing during the initial render is queued, not lost), runs render once immediately, then once per settled burst (trailing-edge debounce).
• A render-callback Err (transient filesystem state mid-rename) never ends watch mode; channel death ends it gracefully with Ok(()).
• Watch-mode UX lines (👀 Watching… / 🔁 File changed… / ⚠️ Watcher error) belong to the module; rendering + reporting stay CLI-side via the callback.
• Injectable timing: debounce + loop clock are pump parameters. Unit tests script a fake event channel against a virtual clock, covering — cross-platform by construction — burst collapse, bursts running longer than the window (trailing event never dropped), events after the window, sibling noise, watcher error storms, channel death mid-drain, callback errors, and the relevance gates (name/parent/Access).

main.rs keeps CLI-local helpers (render_and_report, launch_open_output) and exit-code policy; the --watch --open launch hook remains a one-time duty consumed exactly on the first callback (pre-module behavior preserved, byte-compatible print order included).

Coverage change

• tests/cli.rs keeps one spawned-binary e2e smoke: watch_survives_atomic_rename.
• watch_ignores_sibling_changes moved into module unit tests (12 new).
• Byte-identity harness (C1's) still passes for the once-mode CLI surface.

Gates

fmt --check ✓ · clippy -D warnings ✓ · cargo test --all-targets --all-features --locked ✓ (101 tests: 66 lib + 21 cli + 17 others)

Signed: kilo-kilo-auto-efficient on behalf of matt (Beads mdo-6w5.3)

[kilo-code-bot]

WARNING: This test cannot fail for the property its name pins

watcher_errors_inside_the_drain_do_not_extend_the_window asserts only the render count, but a pump that wrongly reset the deadline in the Ok(Err(e)) drain arm still yields exactly one render here: the errors at 60/60 ms would push the deadline to 370 ms instead of 250 ms, timeout still fires, and the render count is unchanged. The only discriminating observable is elapsed virtual time, which is discarded as _clock. Consider asserting the returned clock (final elapsed of ~250 ms: 50 ms to the first relevant event, then the 200 ms quiet window) so a noise-driven deadline reset actually fails this test. sibling_noise_waits_out_but_does_not_extend_the_window discards _clock the same way.

---

Reply with @kilocode-bot fix it to have Kilo Code address this issue.

[kilo-code-bot]

SUGGESTION: The sibling is never delivered inside the drain window

sibling("other.md", ..., 1000) is ready long after the remaining 200 ms window, so the drain's Ok(Ok(event)) arm never sees it — it only surfaces later as the next outer-loop event and is skipped. A pump bug that reset the deadline on irrelevant events delivered mid-drain would still pass this test as written. A sibling scripted inside the window (e.g. ready_after 100) would exercise the "irrelevant events neither extend nor cut the window" arm the test name refers to.

---

Reply with @kilocode-bot fix it to have Kilo Code address this issue.

[kilo-code-bot]

SUGGESTION: The fake channel models a timeout here, not channel death

In FakeRx::now_or_elapsed, an exhausted script yields Err(RecvTimeoutError::Timeout), so during the drain "channel death" is indistinguishable from "quiet window elapsed" — RecvTimeoutError::Disconnected never reaches pump's Err(_) => break arm from this script. The render count is correct either way; either have the fake report Disconnected when the script is exhausted, or reword the name/comment to "script exhausted while the window is open".

---

Reply with @kilocode-bot fix it to have Kilo Code address this issue.

[kilo-code-bot]

SUGGESTION: report_render's bool result is now unused, and its doc is stale

This call site discards the bool, and it is the only call site left: the one-shot exit code now comes from render_and_report(...).is_ok() (line 441) and the watch callback returns Result<(), RenderError>. Yet the doc on report_render (lines 518–522) still reads "Returns whether the render succeeded, so exit-code policy stays local to main." Either update that doc or drop the -> bool return from report_render.

---

Reply with @kilocode-bot fix it to have Kilo Code address this issue.

[kilo-code-bot]

Code Review Summary

Status: 4 Issues Found | Recommendation: Address before merge

Overview

Severity	Count
CRITICAL	0
WARNING	1
SUGGESTION	3

Issue Details (click to expand)

WARNING

File	Line	Issue
src/watch.rs	484	watcher_errors_inside_the_drain_do_not_extend_the_window asserts only the render count, which is identical whether or not the pump wrongly extends the window on error payloads (250 ms vs 370 ms deadline); the discriminating elapsed virtual clock is discarded as _clock, so the property pinned by the test's name can never fail it

SUGGESTION

File	Line	Issue
src/watch.rs	440	Sibling event scripted ready_after 1000 ms is never delivered inside the drain window, leaving the "irrelevant events neither extend nor cut the window" arm unexercised by this test
src/watch.rs	459	channel_death_during_drain_renders_and_exits is modeled as RecvTimeoutError::Timeout (exhausted script), never Disconnected — the fake cannot distinguish channel death from a quiet window during the drain
src/main.rs	483	report_render's bool result is discarded at its only remaining call site while its doc still claims "Returns whether the render succeeded, so exit-code policy stays local to main"

Files Reviewed (4 files)

• src/lib.rs - 0 issues
• src/main.rs - 1 issue
• src/watch.rs - 3 issues
• tests/cli.rs - 0 issues

Fix these issues in Kilo Cloud

---

_{Reviewed by efficient · Input: 58.1K · Output: 25.3K · Cached: 369.9K}