Why Is It Designed This Way?

Why debounce after filtering?

Rejected paths should not consume the action window. The resulting batch describes relevant user work rather than raw watcher implementation noise.

Why do urgent events bypass filtering and throttling?

Signals are lifecycle control, not ordinary file observations. Ctrl-C must remain responsive even during a large event burst or an overly broad filter.

Why is the action handler serial?

Restart, queue, quit, and signal decisions conflict when applied concurrently. One ordered policy point makes the resulting process transition explainable.

Why does the handler return itself?

The return is a commit boundary. It separates a snapshot-based policy decision from mutation of the runtime’s job registry and shutdown state.

Why does every job have its own task?

Waiting for a child, receiving controls, and running a grace timer must progress concurrently with new event collection. Single ownership also removes locks from CommandState transitions.

Why use three control queues?

Graceful stopping intentionally suppresses stale normal work while preserving escalation and administrative control. Priority is part of process safety, not just throughput tuning.

Why distinguish runtime and critical errors?

A transient watcher or process error may be reported and tolerated. Loss of a core worker or an explicit upgrade changes whether the whole runtime can still honor its contract.

Why is configuration dynamically replaceable?

Watchexec is both a CLI and an embeddable long-lived runtime. Consumers can change handlers, paths, filters, and policy without reconstructing all source and supervisor tasks.