fix(watch): capped quiet-period debounce; harness atomic writes, joined drains, stdout drain; #129 handshake control; #318 site (#129, #318, #320, #379)

[dean0x]

Summary

Closes the C2 watch-reliability cluster: one product defect and three harness defects that
together produced the cli_watch flake family. mds watch --debounce becomes a quiet
period with a hard cap (#379) — the fixed-window semantics were the actual cause of the
burst got 3 failures, not the test. The harness gets atomic writes, a joinable pipe
drain, and a stdout drain that runs before the readiness wait (#320), and the two
remaining "poll the artifact instead of synchronising" sites are converted (#318). #129's
two surfaces are closed and pinned by a two-arm control test.

This PR also carries the manual watch-soak.yml Linux soak instrument from the closed
PR #375. That PR was YAML-only and still went red twice — on the very defects fixed
here (i17 :4370, i18 :4448) — so it could not pass verify-pr-checks.mjs and was
closed rather than merged. It ships here, on a branch that fixes what reddened it.

17 commits, RED-first throughout: every behaviour claim has an observed failing run
before its fix.

What was wrong

Three distinct mechanisms, read out of the CI transcripts rather than assumed.

1. Fixed-window debounce — a PRODUCT defect. watch_debounce_single_rebuild_from_burst
failed as got 3 at cli_watch.rs:1222, with three summary lines
Recompiled … in 40ms / 80ms / 3ms — runs 33996153739, 33976595173,
33753123463 (11 of 146 ci.yml runs since 2026-08-26). The window expired at a fixed
offset from the first event (watch.rs:608 on main), so a save burst longer than
the window split into N rebuilds no matter how the test was written, each compile seeing
a different intermediate state of the file. No harness change can close that.

2. fs::write truncate-then-write at --debounce 0 — a HARNESS defect.
std::fs::write truncates and then writes, publishing a 0-byte intermediate. With
coalescing off the watcher compiled that intermediate, which is an extra observable
rebuild and an extra output transition. (The same tearing is reachable by real users with
an in-place editor — filed separately as #380.)

3. Dir-mode warning emitted after the output write, sampled unsynchronised — a HARNESS
defect. The i16–i20 family asserted an exact warning count on a stderr snapshot taken
the instant the output artifact appeared. In directory mode the duplicate-vars warning is
emitted after the output write, so the sample could be one short — or, once a second
rebuild entered the picture, one long:

• run 34366009518 (on main 2b91850): i17 :4370 left 3 / right 2
• run 34404318888 (on the YAML-only ci: add a manual Linux watch-soak workflow for the cli_watch flake family (#129, #318, #320) #375 head): attempt 1 — i17 :4370 left 1 /
  right 2 and i18 :4448 left 2 / right 1; attempt 2 — i18 :4448 left
  2 / right 1

4. Unjoined drain thread — a HARNESS defect. Tests killed the child, slept ~100 ms,
then read a shared stderr buffer with no happens-before edge to the drain thread's last
write. Field signature: watch_clear_non_tty_no_ansi_escape, reported as
cli_watch.rs:520 in runs 32954883014 / 32954876042 (that line number is from
the commit those runs were on; the test is cli_watch.rs:555 on main 2b91850, its
unjoined read :587).

Design

D1 — --debounce is a quiet period with a hard cap (#379). The first relevant event
opens the window; every further content event restarts it. Bounds:

const MAX_DEBOUNCE_MS: u64 = 60_000;                      // clamp
const DEBOUNCE_CAP_FACTOR: u32 = 10;                      // cap = max(10 x window, floor)
const DEBOUNCE_CAP_FLOOR: Duration = Duration::from_millis(1_000);
const MAX_DEBOUNCE_MESSAGES: usize = 10_000;              // work + memory bound

enum DebounceEnd { Disabled, Quiet, Cap, MessageLimit, Interrupted, Disconnected }
struct DebounceOutcome { paths: BTreeSet<PathBuf>, end: DebounceEnd }
fn clamp_debounce(u64) -> Option<Duration>    // 0 -> None; else min(v, 60s)
fn debounce_cap(Duration) -> Duration         // max(10 x window, 1s)

drain_debounce returns the typed DebounceOutcome instead of (BTreeSet<PathBuf>, bool).
Decisions and their reasons:

• Relevance does not gate extension. The window is a coalescing device, not a
  filter — deciding relevance inside it would mean re-deriving files_of_interest per
  message. Known cost, stated in the CHANGELOG and under Known limitations: in directory
  mode npm install churn under an excluded directory can delay a real edit by up to the
  cap.
• Access events never extend. A reader cannot postpone a writer's rebuild.
• assert!, not debug_assert!, on deadline <= hard_cap. It is the release-build
  enforcement of the bound. It is pure arithmetic, so a descheduled runner cannot trip
  it — only a defect can. deadline == hard_cap is a sound Cap discriminator because
  the cap is at least 10× the window, so the initial deadline never equals it.
  window * DEBOUNCE_CAP_FACTOR cannot overflow Duration: the clamp caps the window at
  60 s, so the product is at most 600 s.
• Clamp behaviour observed, not assumed: --debounce 18446744073709551615
  (u64::MAX) previously watched forever without ever rebuilding, no panic; u64::MAX + 1
  is rejected by clap.
• No new output. The quiet period changes when a rebuild happens, never what is
  printed.

D2 — common::write_atomic. Temp + rename: one FS event, the way an editor writes.
The temp name puts the suffix after the full file name (.<name>.tmp-<pid>-<seq>) so
extension() is never "mds" and the temp is never collected as a source; a
debug_assert_ne! pins that. <pid> disambiguates processes, an AtomicU64 sequence
disambiguates within one.

D3 — a mechanical migration rule, stated in the file's doc comment so a reviewer can
reproduce the set exactly. Convert a std::fs::write( call iff it occurs AFTER the
spawn_ready/spawn_unsynchronized call in the same test fn AND targets a watched path
(.mds source, imported partial, --vars file, external dep). 45 sites converted.
Untouched: pre-spawn fixture writes, .git markers, mds.json, output files. Two
// DELIBERATE: exceptions whose subject is the truncate+write pair:
watch_single_status_line_per_rebuild and watch_debounce_single_rebuild_from_burst.

D4 — joinable drain. PipeTap::finish(self, &mut ChildGuard) reaps the child, then
joins the drain thread. Termination is proved, not bounded: the drain loop ends only
at EOF, EOF arrives when the child's write end closes, and the child is reaped first, so
the join cannot hang on a live writer. bytes()/text() stay non-blocking for the
live-poll sites. ChildGuard moved into tests/common so finish can take
&mut ChildGuard and put "reaped before join" in the type rather than in a comment.
13 of 13 post-kill flush sleeps deleted.

D5 — stdout drained before the readiness wait. mds watch -o - publishes its startup
output before it writes the readiness marker, so an undrained pipe filled and blocked
the child while the poller waited for a marker that could never arrive. Both spawn helpers
now return (Child, StderrTap, Option<StdoutTap>) and drain stdout inside
spawn_watch_unsynchronized. child.stdout.is_some() is exactly "the caller piped
stdout", because Command inherits by default.

D6 — #129 control test. watch_readiness_handshake_makes_ctrl_c_exit_deterministic:
two arms, same signal, opposite verdicts, 20 iterations. CONTROL — spawn_unsynchronized
with SIGINT gated on the Watching … line (printed before the watcher exists and long
before ctrlc::set_handler) → death by SIGINT; if this arm ever exits cleanly the
treatment arm proves nothing, and the assertion message says so. TREATMENT — spawn_ready
with an immediate SIGINT → exit 0 and Stopped watching.. N = 20 is a live
discriminator, not a rate bound; the soak workflow is the rate instrument.

D7 — #318 cli_build.rs site. watch_bare_filename_from_cwd_succeeds synchronises on
the handshake and reads hello.md once. Polling is the defect, not the bound: it
turns "the startup compile wrote the file" into "something wrote the file eventually", so
a shorter loop would have preserved it. run_watch_file publishes the startup output well
before emit_ready_marker, so a single direct read is sound.

D8 — the burst test was rewritten, not added. Its name is cited by three CI runs and
by the issue, so keeping the name keeps the history legible. The burst is now deliberately
longer than the window (12 writes, 30 ms apart, ≥330 ms against a 250 ms window). A new
watch_debounce_cap_rebuilds_while_writes_never_stop pins the cap.

D9 — unit tests for the pure parts (clamp_debounce, debounce_cap, quiet-period
extension, cap, message limit, interrupt, Access-does-not-extend), so the properties are
pinned without a process.

Why one PR, not two. The D-U5 baseline plan was two PRs — harness first, product
second — with the soak run against the harness-only head as the control. That collapsed
when PR #375's YAML-only head went red twice on i17/i18 (run 34404318888): a "harness
only" PR cannot be merged green while the product defect is live. So the soak control is
taken by ref instead of by PR: pre-fix on --ref ci/watch-soak-workflow (= a8faafb,
soak workflow + main), post-fix on --ref main — both after merge, because
workflow_dispatch requires the workflow to exist on the dispatched ref.

Evidence

RED-first, per commit

SHA	Subject	RED/GREEN evidence
fc83b1d	RED — rename-into-place must trigger a rebuild; temp files must be invisible	RED: error[E0432]: unresolved import common::write_atomic
b055957	common::write_atomic	GREEN: 3 tests run: 3 passed (0.590 / 0.590 / 0.647 s)
04b01a6	route every watched write through write_atomic	GREEN ×3: 75 tests run: 75 passed
fb3cd9b	RED — StderrTap::bytes can read a truncated buffer	Green on macOS ×3 — stated honestly in the commit body; the Linux field signature is watch_clear_non_tty_no_ansi_escape in runs 32954883014 / 32954876042
5b343fc	join the drain thread — PipeTap::finish	GREEN: 76 tests run: 76 passed
cffb951	replace 12 of the 13 post-kill flush sleeps	GREEN ×3: 76 tests run: 76 passed — the 13th (watch_stdout_no_duplicate_write_on_startup) was converted in 11c8a43 together with the stdout drain; all 13 are gone at the head.
f145067	RED — spawn_watch_ready deadlocks on a large piped stdout	Real local RED: mds watch did not signal readiness within 10s at common/mod.rs:371, finished in 10.01s
11c8a43	drain stdout before the readiness wait	GREEN ×3: 77 tests run: 77 passed
0b959b2	RED — i16–i20 sample stderr too early	RED is CI-only (macOS cannot reproduce): runs 34366009518, 34404318888 as above
57084a8	bounded wait_for_stderr_count	GREEN: i16–i20 ×8 + full suite ×3
3373f1f	RED — quiet-period and capped debounce semantics	7 of 11 RED, table below
f3fb1a0	--debounce is a quiet period with a hard cap	GREEN + M1–M11 mutation table
3caf629	docs	rendered --help recorded in the commit body
f78dd7c	#129 handshake control test	20/20 both arms ×4; mutation RED
a27bac9	#318 cli_build.rs site	46 tests run: 46 passed ×3
214ff30	CHANGELOG evidence bullets	hygiene gate clean

Commit 11 — observed RED (numbers as printed)

Test	Observed
clamp_debounce_contract	left Some(18446744073709551.615s), right Some(60s)
debounce_cap_contract	left 4294967295s, right 1s
debounce_quiet_period_extends_on_content_events	left 18 paths, right 40
debounce_cap_ends_a_continuous_stream	left Quiet, right Cap
debounce_message_limit_bounds_one_window	left Quiet, right MessageLimit
watch_debounce_single_rebuild_from_burst	left "---\nname: v8\n---\nBurst v8!\n", right "Burst v12!\n" — one Recompiled line, but it compiled v8 — the expected string was corrected in the GREEN commit to the observed product output "---\nname: v12\n---\nBurst v12!\n" (frontmatter passes through verbatim); the RED subject, the Recompiled == 1 count, was unchanged.
watch_debounce_cap_rebuilds_while_writes_never_stop	Got 14 Recompiled lines (expected 1..=4)

Already GREEN, as expected (they pin behaviour that was already correct):
debounce_zero_is_disabled_and_leaves_the_channel_untouched,
debounce_interrupt_returns_immediately, debounce_access_events_do_not_extend.
cli_watch at commit 11: 78 tests run: 76 passed, 2 failed — exactly the two new
integration tests, so the caller refactor broke nothing.

Commit 12 — mutation table (M1–M11)

Each mutation was a scratch edit applied with a uniqueness-checked script, run, then
restored from a pristine copy and verified with cmp (RESTORED_OK for all eleven).
git status --porcelain was M .gitignore only at the end.

#	Mutation	Tests run	Observed
M1	fixed deadline restored (drop the reassignment)	quiet-period unit + burst	RED — left 17 right 40 paths; burst left "---\nname: v8\n---\nBurst v8!\n" right "...v12..."
M2	.min(hard_cap) dropped	debounce_cap_ends_a_continuous_stream	RED — watch.rs:742 panic: "debounce deadline escaped its cap: a file written to continuously would postpone its own rebuild (and the idle-tick backstop behind it) for as long as the writing lasts"; the assert fires on the worker thread and drain_bounded then reports "did not return within 3s"
M3	DEBOUNCE_CAP_FLOOR = 3600s	cap unit + cap integration	RED — unit left Disconnected right Cap; integration "a rebuild must happen WHILE the writes are still arriving"
M4	Access events extend (drop the is_content_event guard)	debounce_access_events_do_not_extend	RED — "300ms of reads must not extend a 100ms window past ~100ms; got 468.653875ms"
M5	Msg::Interrupt keeps draining (continue)	debounce_interrupt_returns_immediately	RED — left Disconnected right Interrupted
M6	clamp_debounce(0) = Some(1ms)	zero unit + clamp contract	RED — left Some(1ms) right None; left Quiet right Disabled
M7	message bound removed (100_000_000)	debounce_message_limit_bounds_one_window	RED — left Quiet right MessageLimit
M8	Cap classification inverted	debounce_cap_ends_a_continuous_stream	RED — left Quiet right Cap
M9	clamp dropped (.min removed)	clamp_debounce_contract	RED — left Some(18446744073709551.615s) right Some(60s)
M10	dir caller drops changed.extend(drained.paths)	3 dir-mode tests, then the whole suite	GREEN — FINDING, weak control. watch_dir_mode_shared_partial_rebuilds_importers, watch_dir_mode_partial_edit_rebuilds_exactly_n_importers, watch_dir_mode_soak_50_edits_bounded_and_clean_exit all PASS; whole suite 78 tests run: 78 passed
M11	file caller ignores interrupted()	3 ctrl-c tests, then the whole suite	GREEN — FINDING, weak control. watch_ctrl_c_exits_cleanly, watch_ctrl_c_prints_stopped_watching, watch_file_mode_ctrl_c_during_startup_compile_terminates all PASS; whole suite 78 tests run: 78 passed

Why M10/M11 are weak, with root causes. M10: the drained paths are redundant with the
initial batch whenever the first event of a burst already names every file the burst
touches — which is what every dir-mode test does. The line is load-bearing only for a
burst that STARTS on one file and CONTINUES on another inside one window; nothing in the
suite pins that. M11: all three ctrl-c tests spawn with --debounce 0, so drain_debounce
returns Disabled without ever receiving a message and can never observe an Interrupt —
no ctrl-c test in the suite runs with coalescing on. Both are recorded rather than
patched: adding either test is a behaviour claim of its own and belongs in its own
RED/GREEN pair, not appended to a GREEN commit.

#129 CI harvest, with its non-vacuity check

ci.yml since 2026-08-26: 146 runs, 21 red. 0 of the 21 contain a FAILED
watch_ctrl_c_prints_stopped_watching. Non-vacuity: the test name appears 13× across
those logs, every occurrence ok — the harvest was reading logs that do mention the test.
So #129's two surfaces were latent, not actively firing, in the observed window; they are
closed by construction (the #323 ordering, the joined drain) and now pinned by the control
test, which mutates RED (left: None right: Some(2)) when the control arm is turned into
a second treatment arm.

JS HMR half of #318 — no follow-up issue warranted

ci.yml, ~300-run window, 2026-07-24 → 2026-09-09: 69 red runs, of which 14 had a
failing JS packages — build & test (ubuntu-latest) job. 0 of those 14 show any
hmr-e2e / waitFor / waitForContent failure signature; the HMR subtests appear
164× in those logs and every occurrence is ok. Filing a follow-up would be filing
against a defect no run has exhibited. Deferred, not filed.

R4 — the one RED that reproduced locally

spawn_watch_ready genuinely deadlocked on 512 KiB of piped stdout, failing with the full
10 s READY_TIMEOUT and an empty stderr. Deterministic, on macOS, before the fix.

Local gates (this head)

cargo fmt --all --check                                          clean
cargo clippy -p mds-cli --all-targets -- -D warnings             clean
cargo clippy -p mds-cli --all-targets \
  --features startup-race-probe -- -D warnings                   clean
cargo nextest run -p mds-cli                 833 tests run: 833 passed, 0 skipped (7.049s)
cargo nextest run -p mds-cli --test cli_watch x3   79 passed (4.116 / 4.084 / 4.132s)
cargo nextest run -p mds-cli --test cli_build x3   46 passed (1.367 / 1.355 / 1.376s)
node scripts/verify-no-control-bytes.mjs     clean — 559 files, 6541880 bytes
node scripts/verify-versions.mjs             clean — 8 packages + 4 crates at 0.4.2
npm run test:gates                           # pass 212  # fail 0
RUSTDOCFLAGS="-D warnings" cargo doc -p mds-core --no-deps        clean
git diff main HEAD --name-only | grep -E 'release.yml|actions/|mds-napi|mds-python|verify-napi-names|musl-load-probe|mds-core|packages/'
                                             EMPTY — no release surface touched

cargo test --doc -p mds-cli is N/A: error: no library targets found in package mds-cli. It is a binary crate with no doctests — not a regression.

Snyk

No Snyk code scan ran. The Snyk MCP server failed to start for the entire session
(ENOENT, missing snyk-macos-arm64 wrapper binary). The security/snyk (dean0x) check
on this PR is SCA-only ("No manifest changes") — it does not cover the Rust source
changed here. Stated rather than implied. This is CLI test-harness and watch-loop Rust
with no new dependencies.

Harness mutation controls (H1–H13)

Each control is a scratch edit applied with a uniqueness-checked script (exactly one
occurrence or abort), run against only the named tests, restored by cp from a
pristine copy taken before the pass, and verified with cmp — RESTORED_OK for all of
them — plus git status --porcelain back to M .gitignore only after each. The
harness half of this PR (D2–D5) landed with RED/GREEN pairs but not with per-invariant
mutations; this is that table.

Six are RED, six are GREEN-on-macOS-by-mechanism, two are weak. Every outcome is
recorded, including the ones that did not fail — a control never observed RED proves
nothing about the test it is supposed to validate, so the GREENs carry their cause.

#	Edit	Tests	Observed	Verdict
H1	write_atomic as copy+remove: write temp, fs::copy(tmp, path), remove_file(tmp) — no rename	i16–i20 ×3	5 tests run: 5 passed, 74 skipped ×3 (0.876 / 0.932 / 1.083 s)	GREEN-macOS — soak-only. The non-atomic replacement's observable (a torn intermediate) is a Linux-timing signature; the soak is the instrument.
H2	temp file placed in std::env::temp_dir() instead of the target's directory	R1 / R2 / R3	3 tests run: 3 passed, 76 skipped (0.967 s)	GREEN — weak here by construction. $TMPDIR and the fixtures' tempfile::tempdir() are both on /dev/disk3s5 on this machine, so the rename stayed intra-filesystem and could not fail. The cross-device failure this control is meant to provoke is unreachable locally.
H3	is_content_event rejects Modify(Name(_)) (extra arm returning false)	R1 / R2	2 tests run: 2 passed, 77 skipped (0.789 s)	GREEN-macOS — soak-only, cause observed not assumed. A diagnostic probe (an eprintln! of every kind reaching is_content_event, with R1's final assert forced to dump) shows ONE write_atomic rename on macOS produces Create(File) ×4, Modify(Data(Content)) ×4, Modify(Metadata(Any)) ×1 and Modify(Name(Any)) ×3 — so dropping the Name variant still leaves content events behind. Under Linux/inotify the destination arrives as IN_MOVED_TO alone, where this mutation is expected RED.
H4	temp-name shape inverted to .tmp-<pid>-<seq>.<name> (suffix BEFORE the name)	R3; collect_mds_files_ignores_write_atomic_temp_names	RED — common/mod.rs:121: assertion left != right failed: write_atomic temp name must never end in .mds; it would be collected as a source / left: Some("mds") / right: Some("mds"). The output.rs unit test stayed GREEN (1 test run: 1 passed, 833 skipped) — it asserts on literal names, so it is not the instrument for the shape; the debug_assert_ne! is.	RED
H5	PipeTap::finish returns self.bytes() WITHOUT joining (join block deleted, kill kept)	stderr_tap_finish_captures_every_line_the_child_wrote ×3; watch_clear_non_tty_no_ansi_escape ×3	2 tests run: 2 passed, 77 skipped ×3 (0.850 / 0.813 / 0.686 s)	GREEN-macOS — soak-only. Matches the phase-B1 finding: the unjoined-drain tearing has only ever been observed on Linux.
H6	child.kill_and_wait() deleted from finish (join kept)	stderr_tap_finish_captures_every_line_the_child_wrote	RED (hang). The test never completed: killed after >180 s against a 0.85 s baseline, with no exit status ever written. Cause is structural — EOF cannot arrive while the child lives, so the join cannot return. (timeout(1) is not present on macOS and no gtimeout; the bound was a background run plus a bounded monitor rather than an exit-124 wrapper.)	RED
H7	stdout drain moved AFTER the readiness poll — spawn_watch_unsynchronized returns None, spawn_watch_ready takes and drains stdout only once the marker is seen	R4 watch_ready_with_large_piped_stdout_does_not_deadlock	RED — FAIL [10.015s], common/mod.rs:386: mds watch did not signal readiness within 10s; stderr so far was: (empty). The full READY_TIMEOUT, exactly the pre-fix signature.	RED
H8	spawn_ready's assert!(stdout_tap.is_none()) removed	the two piped-stdout tests + R4	3 tests run: 3 passed, 76 skipped (1.951 s)	GREEN — weak, by design. No test misuses spawn_ready with a pipe, so nothing exercises the guard. It is a misuse barrier for future authors, not a pinned property, and this control cannot be strengthened without adding a test whose subject is the misuse.
H9	control arm of watch_readiness_handshake_makes_ctrl_c_exit_deterministic spawned with spawn_ready	that test	RED — cli_watch.rs:4213: left: None / right: Some(2), got ExitStatus(unix_wait_status(0)). Re-confirms the B3 observation on the current head.	RED
H10	emit_ready_marker() moved BEFORE ctrlc::set_handler(...) in run_watch_file	that test	1 test run: 1 passed, 78 skipped (0.956 s) — the inverted-order window is one tx.clone() plus one set_handler call, so 20 iterations do not land in it on macOS.	GREEN-macOS — soak-only
H10b	positive control for H10: the same inversion plus a 200 ms sleep between the marker and set_handler	that test	RED — cli_watch.rs:4243, treatment arm: got ExitStatus(unix_wait_status(2)).	RED — and it rescues H10. The test does discriminate the ordering; H10's GREEN is a window-size result, not a blind test.
H11	watch_bare_filename_from_cwd_succeeds reverted to spawn_watch_unsynchronized + a 10 s artifact poll	that test ×3	1 test run: 1 passed, 45 skipped ×3 (0.474 / 0.473 / 0.464 s)	GREEN-macOS — soak-only. Expected: polling is a soundness defect (it asserts "something wrote the file eventually"), not a local failure.
H12	two arms, both raising i17's expected count 2→3: (a) with the pristine helper; (b) with wait_for_stderr_count mutated to RETURN the text on timeout instead of panicking	i17	(a) RED inside the wait — cli_watch.rs:4314: expected at least 3 occurrences of "warning: key 'x' is set more than once in vars file …" within 2s; saw 2. (b) RED at the exact-count assert instead — cli_watch.rs:4592: left: 2 / right: 3, after 2.525 s.	RED. The pair is the point: strip the panic and the timeout is absorbed silently, the failure moves downstream, and the wait stops guarding.
H13	i17's post-spawn write_atomic reverted to plain std::fs::write	i17 ×3	1 test run: 1 passed, 78 skipped ×3 (0.480 / 0.503 / 0.494 s)	GREEN-macOS — soak-only. The truncate-intermediate rebuild is the CI-only signature (runs 34366009518 / 34404318888).

What the GREENs mean. H1, H3, H5, H10, H11 and H13 all mutate invariants whose
failure signature is a Linux/inotify timing or event-shape property; macOS either
cannot produce the signature (H3 — observed, above) or does not produce it at this
window size (H10, rescued by H10b). They are recorded as macOS-GREEN and the Linux soak
is named as their instrument, rather than being presented as passing controls. H2 and H8
are weak for structural reasons stated in their rows, not for want of running them.

Local gates (final head)

Run after every mutation control was restored and verified, on head b537078
(d4bdd2c + the docs commit). cargo test --workspace is CI's command and is included
here in full — it did not stall locally.

cargo fmt --all --check                                           clean
cargo clippy --workspace --all-targets -- -D warnings             clean
cargo clippy -p mds-cli --all-targets \
  --features startup-race-probe -- -D warnings                    clean
cargo nextest run -p mds-core -p mds-cli    2240 tests run: 2240 passed, 0 skipped (9.547s)
cargo nextest run -p mds-cli --test cli_watch x3
                                            79 tests run: 79 passed, 0 skipped
                                            (4.142 / 4.091 / 4.051s)
cargo test -p mds-cli --test cli_watch --features startup-race-probe
                                            79 passed; 0 failed (14.56s)
cargo test --doc -p mds-core                53 passed; 0 failed (13.28s)
cargo test --workspace                      exit 0 — 2293 passed across 30 test
                                            binaries, 0 `test result: FAILED`
cargo +1.88 check -p mds-core -p mds-cli -p mds-python            clean (1.88 installed)
RUSTDOCFLAGS="-D warnings" cargo doc -p mds-core --no-deps        clean
node scripts/verify-no-control-bytes.mjs    clean — 559 files, 6543710 bytes
node scripts/verify-versions.mjs            clean — 8 packages + 4 crates at 0.4.2
npm run test:gates                          # pass 212  # fail 0
git diff main HEAD --name-only | grep -E 'release.yml|actions/|mds-napi|mds-python|verify-napi-names|musl-load-probe|mds-core|packages/'
                                            EMPTY — no release surface touched
git status --porcelain                      ` M .gitignore` only (pre-existing local
                                            edit, never staged)

cargo test --doc -p mds-cli remains N/A (no library targets found in package mds-cli) — a binary crate has no doctests. Not a regression.

Pending

• Pre-fix / post-fix soak run ids — workflow_dispatch requires the workflow to exist
  on the dispatched ref, so both runs happen after merge: pre-fix on
  --ref ci/watch-soak-workflow (= a8faafb), post-fix on --ref main. Run ids to be
  recorded here.

Known limitations

• Dir-mode excluded-directory churn. Every event opens or extends a window, including
  events under directories that are filtered only afterwards, so npm install churn can
  delay a real edit — and the idle tick behind it — by up to the cap (max(10 × window, 1 s)). Documented in the CHANGELOG bullet; not fixed here, because filtering inside the
  window means re-deriving files_of_interest per message.
• --debounce 0 tearing is still reachable by real users. An in-place editor save can
  be compiled as its 0-byte truncate intermediate, leaving a transiently empty output. The
  harness stops producing it; the product does not. Filed as mds watch --debounce 0: an in-place editor save can compile the 0-byte truncate intermediate and leave a transiently empty output #380.
• wait_for_stderr_contains_str still returns its partial text on timeout instead of
  panicking, so a caller that does not assert on the returned text silently tolerates a
  timeout. Left as-is; filed as cli_watch harness: wait_for_stderr_contains_str returns the partial text on timeout, so count assertions built on it are vacuous #381.
• The test: flaky cli_watch.rs::watch_ctrl_c_prints_stopped_watching (timing) #129 control compiles out on Windows (#[cfg(unix)]) — SIGINT has no Windows
  analogue, so the property is not asserted there.
• PipeTap::finish's single-shot-under-clone invariant is documented, not tested. A
  clone calling finish concurrently blocks on the drain slot and then observes a fully
  drained buffer; nothing pins that.
• M10 and M11 are weak controls (see the table): there is no dir-mode test where the
  drained paths differ from the first batch, and no ctrl-c test that runs with coalescing
  on.
• The burst test's == 1 Recompiled count is cut off early. finish_text reaps the
  child immediately after the first Recompiled line, so the count cannot observe a
  second rebuild that would have followed. The discriminating assertion in that test is
  the v12 final-content check, not the count — the count alone would pass a watcher
  that rebuilt again a moment later.
• spawn_ready / spawn_unsynchronized panic on stdout misuse AFTER the spawn. The
  child is already running when the assertion fires, and the panic unwinds before a
  ChildGuard is constructed, so the misuse path leaks that child until the test process
  exits. Harness-only, and only on a misuse no test commits (see H8), but the guard is
  placed one step later than it should be.
• write_atomic's temp-name check is a debug_assert_ne!. It holds in practice
  because tests are debug builds, but it is not a release-build guarantee. The property
  it guards is independently pinned by collect_mds_files_ignores_write_atomic_temp_names
  — though note from H4 that the unit test uses literal names and so does not fail when
  the generator's shape changes; only the debug_assert_ne! catches that.
• i18's exact count of 1 is design-dependent. It holds because the fixture never
  interpolates x, so the vars-file rebuild produces byte-identical output and the
  content-changed gate reports nothing. A comment above the write now says so. The
  robust redesign (assert the delta across the source edit) is left for a later phase.

Changes

• crates/mds-cli/src/watch.rs — drain_debounce returns DebounceOutcome { paths, end };
  quiet-period reset, debounce_cap, clamp_debounce, MAX_DEBOUNCE_MESSAGES;
  assert! on the computed deadline; module doc gains a # Coalescing section and the
  bounded-loop invariant now names both debounce bounds; unit tests for every pure part.
• crates/mds-cli/src/main.rs — --debounce clap help rewritten (quiet period, cap,
  clamp, 0 disables).
• crates/mds-cli/src/output.rs — unit coverage for the atomic-write shape.
• README.md — --debounce block rewritten in the style of the --poll-interval block
  below it.
• crates/mds-cli/tests/common/mod.rs — write_atomic; ChildGuard moved here;
  PipeTap { bytes, text, finish, finish_text } with StderrTap/StdoutTap aliases;
  both spawn_watch_* return (Child, StderrTap, Option<StdoutTap>) and drain stdout
  before the readiness wait.
• crates/mds-cli/tests/cli_watch.rs — 45 writes converted to write_atomic under a
  documented rule (2 documented exceptions); 13 post-kill flush sleeps deleted;
  spawn_ready / spawn_ready_piped_stdout / spawn_unsynchronized wrappers;
  wait_for_stderr_count; the burst test rewritten and a cap test added; the test: flaky cli_watch.rs::watch_ctrl_c_prints_stopped_watching (timing) #129 two-arm
  control test and its wait_bounded helper; i18 comment explaining its exact count.
  79 tests.
• crates/mds-cli/tests/cli_build.rs — watch_bare_filename_from_cwd_succeeds
  synchronised on the handshake, poll loop and private ChildGuard deleted, stderr
  drained. 46 tests.
• .github/workflows/watch-soak.yml — manual workflow_dispatch Linux soak instrument
  (from the closed ci: add a manual Linux watch-soak workflow for the cli_watch flake family (#129, #318, #320) #375). Not a gate, not a required context, not release-surface;
  publishes zero check-runs on any PR head.
• CHANGELOG.md — one ### Changed bullet for mds watch --debounce is a fixed window from the first event; a burst longer than the window splits into N rebuilds #379 and seven ### Internal bullets.
• d4bdd2c fix(watch): cover the Disconnected debounce exit (scrutinize) — unit test
  for the DebounceEnd::Disconnected arm, which no test reached.
• b537078 docs(watch): correct two C2 notes (scrutinize P2) — two documentation
  corrections, no behaviour change. (a) PipeTap's drain-slot comment claimed "several
  tests hand a clone to a helper"; no call site clones a tap, so it now states what the
  shape is actually for — Clone is harness API, and the mutex is what makes a
  concurrent finish from a clone safe. (b) the CHANGELOG's debounce "known cost" was
  scoped to directory mode; verified against drain_debounce (extends on any content
  event, relevance never re-derived) and the file-mode arming at watch.rs:1327/:1422
  (parent directory, RecursiveMode::NonRecursive), it applies in both — dir mode
  differs only in that an irrelevant event can also open a window, since file mode
  checks relevance first.

Related Issues

Closes #318
Closes #320
Closes #129
Closes #379

Refs #317 #319 #321 #326 #380 #381
Supersedes #375

[dean0x]

Soak evidence (post-merge, as planned)

Measured with the manual watch-soak.yml instrument (workflow_dispatch-only, two matrix legs, cargo test -p mds-cli --test cli_watch run N times with a per-iteration tally; ubuntu-latest, cargo test not nextest).

Why the measurement is post-merge. workflow_dispatch can only dispatch a workflow whose file is present on the default branch. watch-soak.yml reached main only with this PR's squash (c4f5880), so no dispatch was possible before the merge. The pre-fix number is therefore measured on ci/watch-soak-workflow (a8faafb) — the branch kept from closed PR #375, which is pre-fix main (2b91850) plus the workflow file only. git diff --name-only 2b91850 a8faafb returns exactly .github/workflows/watch-soak.yml and CHANGELOG.md — zero .rs files. The Rust under test on the PRE row is byte-identical to pre-fix main.

Instrument controls first (PF-013 — a gate never observed rejecting anything is not evidence). M14 and M15 were run before the measurements, on a throwaway scratch/watch-soak-m14 branch that has since been deleted (local and remote).

Runs

#	Purpose	Run	Ref / sha	Iter	default p/f	startup-race-probe p/f	Distinct panic sites (count)	Verdict
M14	must-fail control	34778759271	scratch/watch-soak-m14 @ f40270d	3 (filtered)	0 / 3	0 / 3	cli_watch.rs:1111:5 — "M14 must-fail control" (6)	PASS — instrument rejected as expected
M15	empty-artifact control	34778796788	scratch/watch-soak-m14 @ 1cb8637	1 (filtered)	1 / 0 (Soak step ✅)	1 / 0 (Soak step ✅)	none — upload step failed instead	PASS — instrument rejected as expected
PRE	pre-fix baseline	34778737538	ci/watch-soak-workflow @ a8faafb (= pre-fix main 2b91850 + workflow only)	20	15 / 5 (failed at 3, 9, 12, 15, 17)	18 / 2 (failed at 1, 13)	default: :4370:5 (3), :4297:5 (2) · probe: :4297:5 (1), :4310:5 (1)	flaky — reproduced
POST	post-fix	34778740544	main @ c4f5880	20	20 / 0	20 / 0	none	clean

Control detail

M14 — must-fail control. assert!(false, "M14 must-fail control") planted as the first statement of watch_ctrl_c_prints_stopped_watching. Both legs: job conclusion failure, summary.txt shows passed: 0 / failed: 3 / failed at: 1 2 3, and the artifact holds iter-001.log, iter-002.log, iter-003.log per leg (6 logs), each containing panicked at crates/mds-cli/tests/cli_watch.rs:1111:5 with the M14 must-fail control message. The ::error::3 of 3 iterations failed on leg <leg> annotation is emitted after the $GITHUB_STEP_SUMMARY write, so its presence proves the step-summary table block executed on both legs. The instrument fails loudly, keeps exactly the failing logs, and tallies a rate rather than aborting at the first red.

M15 — empty-artifact control. The assert! was reverted and the > soak/summary.txt write block (plus its cat) deleted, so a clean soak leaves soak/ empty. Both legs: the Soak step succeeded (iter 1 PASS, clean soak: 1/1 passed on leg <leg>) and the Upload failing logs and the tally step failed with:

##[error]No files were found with the provided path: soak/. No artifacts will be uploaded.

alongside the echoed input if-no-files-found: error. gh run download 34778796788 returns "no valid artifacts found to download". This confirms an empty soak/ cannot masquerade as a clean run (PF-016): the always-write summary.txt is what keeps the artifact non-empty, and removing it is caught.

PRE — what actually failed

Both legs failed on the #326 duplicate-key-warning rebuild assertions, not on the ESC or burst sites:

• i17_dir_watch_vars_file_duplicate_warns_once_per_rebuild — cli_watch.rs:4370:5, 3× (default leg)
  I17: one rebuild must add exactly one more warning (guards a double-emit between :1793 and :1919)
• i16_file_watch_vars_file_duplicate_warns_at_startup_and_on_every_rebuild — cli_watch.rs:4297:5 (2× default, 1× probe) and cli_watch.rs:4310:5 (1× probe)
  I16: a second rebuild must report the duplicate again

(Line numbers are a8faafb's cli_watch.rs.) No *_edit_during_startup_window_is_not_lost failure appeared on the probe leg in either run.

Verdict

Aggregate over both legs: 7 / 40 iterations failed pre-fix → 0 / 40 post-fix. The instrument is proven to reject both a failing suite (M14) and an empty artifact (M15), so the post-fix failed: 0 on both legs is a measurement and not a vacuous green. The POST artifacts contain summary.txt only — zero iteration logs kept, which is what a clean soak looks like.