fleet

name	fleet
description	Check repository occupancy before edits, find which local agents are running, claim a workspace before writing, release claims afterward, and diagnose fleet sources. Use before modifying a repo or launching concurrent agent work.

Fleet

Treat exit codes as the control-flow API. Use --json for serde envelopes; inspect meta.complete and meta.sources instead of parsing human text.

Preflight

Use one stable owner name across the lane:

fleet repo "$PWD" --for "<owner>"

• Exit 0: safe for that owner.
• Exit 3: occupied. Stop and inspect fleet status.
• Exit 1: required evidence is unavailable. Restore the failed source and retry.

Before fan-out, run fleet collisions --json. Exit 3 means STOP; do not launch more writers.

Claims lifecycle

Claim before writing and release after the lane finishes:

fleet claim "$PWD" --owner "<owner>" --ttl 4h
# perform writes
fleet release "$PWD" --owner "<owner>"

Exit 4 means another live claim exists or the release no longer names the current lease. Inspect fleet claims --json; use --steal only when takeover is intentional.

Exit codes

Exit	Meaning
0	success, including empty results and partial status
1	required source unavailable, unexpected failure, or failed doctor check
2	usage error
3	occupied workspace or collision; stop
4	claim or release conflict

Human inspection and triage

• fleet status: one-screen actors by workspace, live claims, collisions, and the unclaimed-writer advisory.
• fleet watch --interval 5: redraw that summary; Ctrl-C exits 0.
• fleet doctor: offline checks for source reachability, claims integrity, fixture mode, and stale leases.
• fleet schema --pretty: full machine contract.

Unclaimed writers are advisory in status; they never make status exit 3.