fleet

Documentation

Overview

Package main — fleet claims hidden CLI subtree.

This file implements the operator-invisible `fleet claims` namespace that backs the Delivery controller in internal/dispatch. The Python coord skill (skills/coordinator/loop.py) shells out to these subcommands instead of writing inbox files directly — the dispatch-lifecycle primitive's load-bearing contract is that EVERY fleet-created resource is owned by a journal, and only the Go side can mutate the journal atomically.

PR1 scope (DESIGN-dispatch-lifecycle.md §"Vertical-slice sequencing"):

• `acquire-prompt` — coord_prompt_inbox AcquireAndDeliver
• `release` — Delivery Release (kind=coord_prompt_inbox)
• `inspect` — Delivery Inspect

All subcommands:

• Hidden from `fleet --help` (cobra.Command.Hidden = true).
• Read prompt content from stdin (no --content-file flag — avoids path leaks, matches DESIGN §"Acquire is Go-side; Python shells out via fleet claims").
• Emit a JSON envelope on stdout: `{"outcome": "...", ...}`.
• Exit with a STABLE code per outcome (plan-eng A1): acquired → 0 already_acquired → 0 released → 0 already_released → 0 not_owned → 10 absent → 11 contested → 12 (reserved for PR2 per-task_slug lock) error → 1

Golden-file contract tests in cmd/fleet/testdata/claims/*.json pin the JSON schema + outcome enums; the CLI is the public boundary the Python skill depends on.

fleet coord-run is the Go-level supervisor wrapper for a coord session. It owns the three coord-exit paths the design calls out: signal, clean exit, and panic. Whatever happens to the child, the top-level `defer coord.Cleanup(...)` runs.

See docs/DESIGN-cleanup-fleet-owns-resources.md §PR-C for design.

Usage:

fleet coord-run --agent <id> --project <p> -- <child-cmd> [args...]

Production wiring:

• FLEET_LEASE_FAILOVER OFF (default): the dispatch path (cmd/fleet/dispatch.go) builds the default --command argv as ["sh","-c","claude --dangerously-skip-permissions; ..."] — a bare engine, NOT routed through this supervisor (byte-identical to pre-PR2 behavior).

• FLEET_LEASE_FAILOVER ON (DESIGN-handoff-drain-storm-leak PR2): dispatch wraps that engine argv in this supervisor: ["fleet","coord-run","--agent",<id>,"--project",<p>,"--", "sh","-c","claude ..."]. The supervisor then ACQUIRES + HEARTBEATS the coordinator lease for the coord's whole life, stands down (exit 0) if a healthy leader already holds it, releases the lease on EVERY exit path (alongside coord.Cleanup), and — on a contested acquire — reaps the stale holder via the authenticated internal/coord.KillCoordIfIdentityMatches STONITH.

PR-C originally introduced this subcommand without wiring it in; PR2 closes that gap behind the failover flag so the lease has a real lifetime holder.

Exit-path matrix (per task plan acceptance criteria):

Child exits cleanly (status 0)       → runCoordRun returns nil
Child exits non-zero                  → returns *exec.ExitError
Parent receives SIGTERM/SIGINT        → ctx.Done() fires, child gets
                                        SIGTERM via CommandContext,
                                        wait returns, function returns
Internal panic (e.g. opts validation) → propagated AFTER cleanup
                                        runs via defer/recover

In ALL paths above, coord.Cleanup fires exactly once. The top-level defer is panic-safe because Cleanup itself runs each step inside its own recover (see internal/coord/cleanup.go).

coord_lease_unix.go — the lease-wiring half of `fleet coord-run` (DESIGN-handoff-drain-storm-leak PR2). Build-tagged to linux||darwin because internal/coordlock's lease primitive + internal/coord's STONITH (kill.go) are themselves gated to those two GOOS values (they need platform pid-start / monotonic-clock reads). Other Unix targets (e.g. FreeBSD) compile coord_lease_other.go instead, whose defaultAcquireLease reports the lease as unsupported so `fleet coord-run` runs the legacy bare-child path (codex PR2 iter-2 [P2]: keep GOOS=freebsd building).

Command fleet is the operator-facing CLI for the Fleet parallel-agent console. See docs/DESIGN.md for the v1 product spec.

Package main — `fleet rc` operator-facing CLI subtree.

Implements docs/DESIGN-rc-listener-lifecycle.md v8. The operator controls per-project remote-control listeners via:

fleet rc up      <project> [--cwd <path>] [--idempotent]
fleet rc down    <project>
fleet rc connect <project> [--coord <id>]
fleet rc status  [<project>] [--healthy]
fleet rc list
fleet rc reset   [<project>]

Stable JSON envelopes + exit codes; the Python skill (skills/coordinator/remote_control.py:spawn_daemon_if_needed) consumes `fleet rc up --idempotent` and routes ALL spawn through the Go controller (codex round 2: single owner).

Exit-code table (mirrors fleet claims):

acquired / already_acquired / released / already_released /
connected           → 0
not_enabled         → 10
not_owned           → 10
absent              → 11
contested           → 12
error               → 1