Worker Protocol
The worker protocol turns important transitions into machine-readable events. A worker does not become “done” because it says so in prose. It becomes reviewable when it reports the right event for the current launch, active work item, and delivery attempt.
Required States
Section titled “Required States”Workers report:
| State | Meaning |
|---|---|
ack |
The worker received the current delivery and can start the active work item. |
working |
The worker is actively making progress. |
blocked |
Work cannot continue without a blocker being resolved. Requires detail. |
ready_for_review |
The work is ready for Hub review. |
not_done |
The worker has a known next step and still owns it. Requires detail. |
done |
The non-deploy task is complete and ready for Hub review. |
deploy_done |
The deploy stage completed with evidence. Requires detail. |
Scope Rules
Section titled “Scope Rules”Every accepted report must match:
- current session
- current worker launch
- active work item
- current delivery ID
- current ACK
Reports from stale launches, inactive work items, old delivery attempts, or workers that never ACKed the delivery are invalid.
Why It Matters
Section titled “Why It Matters”Terminal text is easy to misread. A prompt placeholder, spinner, old “done” line, or stale transcript can look like live state. The protocol makes the worker say exactly where it is in the current work item, then lets Hub audit and recover from that evidence later.
Compatibility
Section titled “Compatibility”Legacy textual handoff markers remain useful as review evidence and compatibility for older sessions. Current structured events are the authority for Hub-managed workers.