Watch drops the final startup batch with post_on_start enabled

[robjarawan]

I reproduced missing startup notifications in watch with post_on_start True and batch 10. With 17 existing files, I only get notifications for the first 10. The other seven stay on disk but their startup notifications disappear.

Basically, File.gather() saves the remainder of the initial scan in queued_messages. When that remainder fits in one batch, it clears the queue, then returns self.wakeup() instead of the saved messages. This also drops a full final batch: 20 files produce only 10 startup notifications.

I checked fork development at 24de015ccbdd20419ff4cc58e560478009d6ed20. The affected path is also present in upstream development at 446a826bc3c30e6523775809dd85d1544b583c67.

Reproduction

I used temporary local files, parsed watch options and the real File.on_start() / File.gather() path with a real watchdog observer. I primed the cached file identities before starting the observer, as on a restart. Otherwise the identity writes can generate modify events that hide the missing startup notifications.

batch 10
sleep 1
post_on_start True
recursive True
fileAgeMin 0
blockSize 1
identity arbitrary startup-control

I pointed postpath and post_baseDir at the temporary directory and used a local file: URL. No broker or external service was involved. I drained several gather calls after the initial scan and checked every expected filename.

Existing files	Watch notifications	Expected
0	0	0
1	1	1
10	10	10
11	10	11
17	10	17
20	10	20
21	20	21
25	20	25

The same eight cases with one-shot posting (sleep -1) all pass. The regression run gives 5 failed, 11 passed. These are missing-notification assertions, not observer startup errors.

I plan to return the final queued batch before switching to new watch events, and retain the batch-boundary and one-shot controls. New events can be processed on the following gather call, just as they already are while larger startup batches drain.

Upstream #403 discusses incremental scanning performance. This issue is the separate loss of notifications already collected by the scan.

[robjarawan]

I cleaned draft #142 without changing the startup-tail behavior. The branch is now one commit directly on fork development, includes its changelog entry, and no longer carries the separate #140 maintenance changes. Current head: 73f4724e2d011f7d0422241ee739526d6d48125b.

The final proof is:

• exact base behavior: 5 failed, 11 passed
• current startup regression: 16 passed
• broader offline suite: 370 passed, 1 skipped
• current fix: retain the final watch startup batch #142/fix: synchronize the watch event buffer handoff #144 composition: 19 passed
• current-head GitHub unit suite: 389 passed, 1 skipped, including all 19 Azure fixture tests
• 3,168 additional startup state cases and 44 native/polling filesystem cases

The current code returns and clears the final queued startup batch before wakeup() can replace it. It remains primed, does not repeat the scan, and delivers live events on the next gather call. Exact ordering, multiplicity, finite draining, observer liveness and one-shot behavior all pass in the additional controls.

The committed matrix could be strengthened with the threshold-minus-one count and explicit multiplicity/liveness assertions, but it already detects the original loss and the stricter controls do not expose a remaining product defect.

The runtime review is complete. The PR remains draft while most current-head flow checks are queued and the separate transform-flow evidence is absent. #144 remains the companion fix for the distinct live-event handoff race.