Proposal: add event-driven one-shot waits for local path changes

Proposal: event-driven one-shot waits for local path changes

Summary

Add a small event-driven one-shot wait helper on top of the existing
codex-file-watcher subscriber API. This provides a reusable building block for
future waitable operations that can suspend on filesystem events instead of
polling.

Motivation

Some Codex workflows need to wait for a local result, such as a generated file,
lockfile update, or other filesystem-side completion signal. When the target is
watchable, an event-driven wait avoids repeated status checks and lets callers
bound the wait with tokio::time::timeout or cancellation.

This is intentionally narrower than adding a background daemon or "wake GPT"
mechanism. The change only adds a local execution-layer primitive that can be
used by later call sites with a polling fallback when an event source is not
available.

Implementation

The patch adds PathChangeWaiter to codex-rs/file-watcher/src/lib.rs.

PathChangeWaiter:

• owns a FileWatcherSubscriber and WatchRegistration;
• registers one or more WatchPath values;
• waits once for the next matching FileWatcherEvent;
• unregisters automatically when the waiter is dropped or a timeout/cancellation

drops the wait() future.

This reuses the existing FileWatcher implementation and does not add any new
dependencies.

Tests

Added coverage for:

• a normal existing file change completing the wait;
• cancellation/timeout dropping the registration and clearing watch counts;
• missing-file fallback via parent directory events.

Validation run locally:

just fmt
just test -p codex-file-watcher
just fix -p codex-file-watcher
git diff --check

just test -p codex-file-watcher result:

24 tests run: 24 passed, 0 skipped

Follow-up direction

After this primitive lands, a later change can replace selected
sleep/check/sleep loops with a strategy such as:

event-driven filesystem wait
    -> timeout/cancel cleanup
    -> polling fallback for unsupported targets

This keeps the first change small and reviewable while moving Codex toward
event-driven wait behavior where the event source supports it.

Contribution note

The repository currently says unsolicited code PRs are closed without review.
This should be proposed first as an issue or design comment, and the code patch
should be submitted only if maintainers invite a PR.

0001-Add-one-shot-path-change-waiter.patch