Expose worker idle time so callers can shut down inactive workers — Closes #253

[conradbzura]

Summary

Add an idle RPC so callers can observe how long a worker has been continuously idle and retire inactive workers on their own schedule. The worker measures idle time against a monotonic clock — seconds since its in-flight task set last became empty, with startup counting as empty, zero while any task runs, resetting whenever work resumes — and reports it through a new IdleTime wire message. WorkerConnection surfaces this as idle_time(), returning a plain float, alongside a stop() control, so a caller can poll-then-retire over the same single-worker surface.

A worker predating the RPC answers gRPC UNIMPLEMENTED, which surfaces as the new IdleUnavailable — deliberately a WoolError rather than an RpcError, so an absent capability is never mistaken for an RPC-health fault that would evict a healthy worker. The change ships mechanism only: the worker reports, the caller decides — there is no built-in auto-shutdown policy, and the routine dispatch path is untouched.

LocalWorker shutdown is refactored to route through WorkerConnection.stop() instead of a hand-built stub, and the shutdown grace period is renamed from timeout to grace so it no longer collides with the client-side deadline timeout on dispatch and idle. The old timeout keyword is kept as a deprecated alias that still works and emits a DeprecationWarning, so existing callers are not broken.

Closes #253

Proposed changes

• Wire protocol — Add an idle unary RPC returning a new IdleTime message (a double seconds field) to the Worker service, re-exported from wool.protocol.
• Worker idle tracking — WorkerService records a monotonic timestamp of when its in-flight docket last emptied and answers the idle RPC with the elapsed seconds, or zero while busy. The timestamp flips only on the docket's empty/non-empty edges, so polling never enters the docket and cannot disturb the measurement.
• Client control surface — WorkerConnection gains idle_time() (returns the reported idle seconds, validating a positive deadline) and stop() (sends the stop RPC with a shutdown grace period). A missing RPC surfaces as IdleUnavailable, a new public WoolError subclass.
• Backwards-compatible grace rename — Rename the stop() shutdown grace period from timeout to grace on Worker and WorkerLike, keeping timeout as a deprecated alias. The wire field StopRequest.timeout and the startup deadline keep the name timeout.
• LocalWorker shutdown — Route LocalWorker._stop through a WorkerConnection, reusing its credential handling, secure-channel construction, and channel pooling, and release the pooled channel afterward.

Test cases

#	Test Suite	Given	When	Then	Coverage Target
1	TestMessageConstruction	An IdleTime message	Constructed with and without a seconds value	The seconds field holds the value and defaults to 0.0	IdleTime wire message
2	TestMessageConstruction	Any finite double	An IdleTime is serialized and re-parsed	The seconds field survives the round-trip exactly	IdleTime wire fidelity
3	TestWorkerService	N in-flight tasks, each returning or raising	Tasks complete one at a time and idle is polled after each	Idle stays zero until the last task drains, then accrues	Docket-emptiness idle invariant
4	TestWorkerService	A worker with accrued idle	A dispatch is rejected before tracking (backpressure, malformed id, sync callable)	Idle keeps counting — the rejected task never enters the docket	Idle immune to pre-tracking rejection
5	TestWorkerConnection	A worker answering idle with any gRPC status code	idle_time is awaited	UNIMPLEMENTED maps to IdleUnavailable, transient codes to TransientRpcError, others to RpcError	Idle error mapping
6	TestWorkerConnection	Any non-positive timeout	idle_time is awaited with it	It raises ValueError without calling the stub	Idle timeout validation
7	TestWorkerConnection	None or any positive timeout	idle_time is awaited with it	It forwards the timeout to the stub as the gRPC deadline	Idle deadline forwarding
8	TestWorkerConnection	A worker reporting any double	idle_time is awaited	It returns exactly that value	Idle value fidelity
9	TestWorkerConnection	A worker acknowledging stop	stop is awaited with a grace period	It sends a StopRequest carrying the grace and returns None	Stop request forwarding
10	TestWorker	A started worker	stop is called with the deprecated timeout keyword	It emits a DeprecationWarning and forwards the value as grace	Backwards-compatible stop alias
11	TestLocalWorker	A started worker whose stop RPC raises	stop is awaited	The error propagates and the pooled channel is still released	Stop channel cleanup
12	TestWorkerIdleReporting	A freshly started real worker over each transport	idle_time is polled twice with a wait	Both readings are positive and non-decreasing	Idle accrual from startup (integration)
13	TestWorkerIdleReporting	A real worker with one in-flight routine	idle_time is polled	It reports zero while the docket is non-empty	Zero-while-busy (integration)
14	TestWorkerIdleReporting	A servicer without the idle RPC	idle_time is polled over a real channel	It raises IdleUnavailable, not RpcError	Legacy-worker detection (integration)
15	TestWorkerControlSurface	An idle real worker	The caller polls idle, stops it, then polls again	Stop terminates the worker and a later poll raises TransientRpcError	Poll-then-retire flow (integration)