Document the worker idle RPC in the top-level and worker READMEs — Closes #371

[conradbzura]

Summary

Document the worker idle RPC in both READMEs. The surface has shipped without documentation in either one, and the top-level README additionally described the worker as hosting two RPCs — a claim that has contradicted wire.proto since idle landed, so a reader came away believing the capability does not exist.

Split the material by the one-home-per-claim rule. The worker package README owns the contract, since that is where connection behavior is already documented in depth; the top-level README carries the narrative and links there, matching how it already defers to the worker package on discovery-plane trust and credential rotation. IdleUnavailable gets exactly one home, in the new worker README section, with a pointer from the error-classification table rather than a second copy.

Documentation only — no source, no tests, no behavior change.

Closes #371

Proposed changes

Add an Idle reporting section to the worker package README

Add ### Idle reporting under ## Connections, between Connection pooling and Transport configuration, covering four things a caller needs:

• The API — WorkerConnection.idle returns the continuous idle duration in seconds, wrapping rpc idle (Void) returns (Idle); the response is a wool.protocol.Idle carrying a single seconds field. The optional timeout is the deadline for the poll itself and must be positive, with None applying none. The call draws a channel from the same pool a dispatch would.
• The measurement — time since the in-flight task set last emptied, with startup counting as the initial empty state; zero while any task is in flight; restarted each time the set drains, so the value answers "how long has this worker had nothing to do" rather than "how long since it was started". Taken on a monotonic clock, and polling neither creates a DispatchSession nor enters the in-flight set, so reading the measurement cannot disturb it.
• The disambiguation — worker idleness is not channel idleness. The 60-second ResourcePool TTL two paragraphs above and WorkerOptions.max_connection_idle_ms both govern how long an unused channel survives, and neither depends on whether the worker at the other end is executing tasks. Placing this next to the pooling paragraph is the point: those are the terms a reader has just been given.
• The error — a worker predating the capability answers UNIMPLEMENTED, surfacing as IdleUnavailable, which descends from WoolError rather than RpcError so except RpcError does not catch it. Every other gRPC failure classifies as it does for dispatch.

Point at it from the error-classification table

Add one sentence beneath ### Error classification noting that the table covers dispatch-path failures where the behavior column is the load balancer's response, and that the idle poll — which reaches no load balancer — adds IdleUnavailable, linked to the new section. A pointer rather than a table row, because the table's "Dispatch behavior" column has no meaning for a poll that never enters dispatch.

Correct the RPC count and add the narrative in the top-level README

Change "two RPCs" to three under ## Workers and name idle alongside dispatch and stop, with a parenthetical gloss matching the existing style.

Add one paragraph after the WorkerConnection description under ### Self-describing worker connections, covering the poll at narrative depth — what it measures, why zero-while-busy is what makes it a usable retirement signal for a supervisor, and what IdleUnavailable means — then linking to the worker README section for the full contract.

## Error handling is deliberately untouched: its table is organized by dispatch phase and its rows describe load-balancer actions, so an idle row would misrepresent a call that has neither.