saphan fleet
Shows the state of the fleet — streams, seats, running legs, capacity and refusals — from the record.
Shows the state of the fleet — streams, seats, running legs, capacity and refusals — from the record. None of these commands dispatches work or chooses where it should run. show and next first read fresh agent activity into the record, observe and reap record what they find, and headroom and usage can spend money; each says so below. Run it with a subcommand.
saphan fleet debt
Lists every stream that still owes a gate, with the gates it owes, its worktree path and host, whether that path exists, and how much disk it still uses. It is read-only and deletes nothing, so its answer is as fresh as the record's last update, not the disk. A host it cannot reach, or a check it could not complete, is shown as unmeasured and makes the command exit non-zero after printing the report.
| flag | type | default | what it does |
|---|---|---|---|
--json | bool | false | Print the report as JSON. |
saphan fleet dispatchable
Answers, for every seat in the registry, whether a run may be dispatched onto it now: may-dispatch, refused (a measured obstacle) or unmeasured (the deciding fact was never read). Each refused or unmeasured row names one obstacle, and the report also shows how many concurrent runs the fleet can actually take. It only reads the record: it contacts no vendor, spends nothing and is safe to run in a loop.
| flag | type | default | what it does |
|---|---|---|---|
--role | string | Ask on behalf of this role (master, executor, review, design, scribe or advisor); without it, a seat reserved for a role reads role-reserved. |
saphan fleet free
Answers, for every seat, whether an executor dispatch could land on it now: free, not-free with the obstacle, or unmeasured-here naming which input could not be read and when it could be read again. It reads only the record and configuration, contacts no host or vendor, reserves nothing and costs nothing. ⚠ A vendor's usage figure is the one it last displayed, so a seat that reads free may still be refused by the vendor on the next request.
| flag | type | default | what it does |
|---|---|---|---|
--backend | string | Ask only about this backend; seats on other backends are still listed, marked wrong-backend. |
saphan fleet headroom
Probes which places can run work right now by starting a short test run of each configured model on each applicable local backend, and reports them beside what the record already knows. ⚠ Every probe is a real, billed run. It never dispatches work and never picks a winner.
| flag | type | default | what it does |
|---|---|---|---|
--actor | string | The name the probes are recorded under, as given and not verified; defaults to SAPHAN_ACTOR, then the configured identity. | |
--backend | string | Probe only this backend, claude-code or codex; by default every applicable local backend. | |
--estimate-usd | float64 | 0 | The cost estimate the report is measured against; required. |
--model | string | Probe this one model on every backend instead of each backend's configured list. |
saphan fleet health
Counts failed work runs over a recent time window. Capacity probes are not counted as failures, and older rows that cannot be classified are shown separately rather than counted as work.
| flag | type | default | what it does |
|---|---|---|---|
--window | duration | 2h0m0s | How far back to look, for example 2h or 24h; defaults to two hours. |
saphan fleet legs
Lists the legs running now, one row each: stream, seat, machine, model, mode, start and elapsed time, cost quote, budget cap, spend so far, last commit, working directory with its host, and whether the process is alive — with the source of every value. Spend is only known once a run finishes, so a running leg shows it as not yet recorded rather than 0. ⚠ A budget cap is only enforced by backends that support one. It reads the record as last updated and contacts no host.
saphan fleet next
Shows, for one stream, its current state, every gate it still owes, every next act that is allowed with a ready-to-paste command, and every act that is not with its refusal. --rules shows how dispatch works in this project instead. A stream waiting on a human gate exits 0; an unknown stream exits 2.
| flag | type | default | what it does |
|---|---|---|---|
--rules | bool | false | Also show how dispatch works in this project, derived from the live rules and machine registry; works without --stream. |
--stream | string | The stream to show. |
saphan fleet observe
Checks git, on the machine that holds each stream's repository, for streams awaiting merge observation (or the one named) and reports for each whether a merge was observed, not yet merged, or cannot be observed, with a manual check to run in that case. An observed merge is recorded permanently. It writes no git state and decides no gate.
| flag | type | default | what it does |
|---|---|---|---|
--repo | string | Record, once, the absolute path of the named stream's owning repository, for streams recorded before the engine captured it; every later check uses it. | |
--round | string | The run ID to observe, when the stream has completed runs on several remote machines and the engine will not choose one. |
saphan fleet reap
Closes the record of a run on a remote machine only after asking that machine whether any process of the run is still alive there and getting a clear "no". If the machine is unreachable, the answer is ambiguous, or the run is alive, the run stays open and the reason is printed; there is no time limit and no force option. Local runs are cleaned up by saphan run itself.
| flag | type | default | what it does |
|---|---|---|---|
--json | bool | false | Print the result as JSON. |
saphan fleet refusals
Lists refused runs, newest first: when each started, its stream, the rule that refused it, the seat it was placed on, and the recorded reason word for word. With --seat, it adds a summary per seat of its last refusal and how many runs succeeded since. It opens the database read-only.
| flag | type | default | what it does |
|---|---|---|---|
--limit | int | 50 | Show at most this many rows; 0 shows every row. Defaults to 50. |
--seat | stringArray | Show only refusals on this seat, with a per-seat summary; repeatable. | |
--since | duration | 0s | Show only refusals that started within this window, for example 2h or 24h; defaults to the whole record. |
--stream | string | Show only refusals for this stream. |
saphan fleet show
Shows every stream with its state, resolved from agent activity, human gate decisions and observed git merges, followed by the one notification that needs your attention. It first reads fresh agent activity into the record and records any merge it now observes. It exits 2 when a stream is waiting on a human gate.
| flag | type | default | what it does |
|---|---|---|---|
--changed-since | string | Show only streams that changed at or after the as_of_ts of an earlier JSON response, for polling. | |
--detail | string | How much each JSON row carries: summary (the default) or full, which adds evidence, phase timings and the merge message. | |
--since | string | Show only streams updated at or after this RFC 3339 time. | |
--state | string | Show only streams in exactly this state, for example in-flight or gated:accept. | |
--streams | stringSlice | Show only these streams; comma-separated or repeated. |
saphan fleet usage
Reads each seat's current usage from its vendor and reports it, without dispatching anything. Reading usage costs nothing; ⚠ a claude-code seat whose usage read does not clear it may be sent one small paid model request, at most once per seat per 30 minutes, and every row shows whether that happened. Seats on backends other than claude-code and codex are reported as unsupported.
| flag | type | default | what it does |
|---|---|---|---|
--actor | string | The name the probes are recorded under, as given and not verified; defaults to SAPHAN_ACTOR, then the configured identity. | |
--machine | string | Read only the seats on this machine. | |
--model | string | claude-haiku-4-5-20251001 | A label for the report only; it does not choose the model used by any paid request. |
--slot | int | 0 | Read only this slot; requires --machine. |
Global options apply to every command — see Every command.