claim_host
Idempotent
Acquire an exclusive lock on a host for a workstream before running tasks; automatically takes over stale locks from crashed workers. Keep the lock fresh with heartbeats and release it when finished.
Instructions
Claim exclusive use of a host. Fails if another owner holds a fresh lock — a stale lock
(heartbeat older than its TTL, e.g. from a crashed worker) is taken over automatically.
Always report a phase (what you are doing); the server flags a lock STUCK when its heartbeat
is fresh but the phase has not moved for too long, so keep the phase current (pass a new phase
to heartbeat_host) as you progress. Heartbeat while you work; release with release_host when done.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| note | No | Free text for the dashboard, e.g. the current step | |
| force | No | Take over even if another owner's lock is still fresh | |
| owner | Yes | Who is asking: workstream/session id, e.g. 'ws/occluder-wire', 'p-1a2b3c4d', 'coord-session' | |
| phase | No | What you are doing, e.g. 'compile', 'test' — powers stuck detection | |
| host_id | Yes | Host id from list_hosts, e.g. 'build-pc' | |
| ttl_sec | No | Lock lifetime without heartbeat, seconds (min 60) |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| note | No | free text from the owner, e.g. the current step | |
| fresh | Yes | heartbeat within ttl (False = stale, can be taken over) | |
| owner | Yes | ||
| phase | No | what the owner is doing ('', 'compile', 'test', ...); '' = not reported | |
| stuck | No | fresh heartbeat but the phase has not moved past the server's threshold (liveness != progress) | |
| age_sec | Yes | seconds since the last heartbeat | |
| host_id | Yes | ||
| ttl_sec | Yes | ||
| acquired_at | Yes | ||
| phase_since | No | when the current phase started (NULL when no phase) | |
| heartbeat_at | Yes | ||
| stuck_reason | No | why the server marked this lock stuck | |
| phase_age_sec | No | seconds since the phase was last changed |