Skip to main content

Run and inspect the fleet

The reconciler is deliberately observable. A tick reports what advanced, what was dispatched, and why work was withheld. Runtime state is reached through the FleetStore port: an unregistered repository uses .autodev/fleet.sqlite, while a registered workspace requires the central daemon and its global ~/.local/share/autodev/fleet.sqlite. Use CLI verbs rather than editing either store.

Preflight​

Before a live run:

git status --short
autodev board check
autodev fleet disk
autodev fleet doctor
autodev fleet status

A dirty working tree no longer blocks the final apply step: the fleet stages and gates each landing in its own checkout under worktree_root and advances the base ref, then tries to bring your checkout forward without touching your work. fleet doctor exits 1 when persisted wave state is malformed; fleet disk compares measured worktree/cache use with the configured floor.

Run one tick​

autodev fleet tick

A tick performs one reconciler pass: it may reclaim stale resources, advance existing waves, run turns and reviews, integrate, gate, apply, and dispatch new work. It may also do nothing, in which case the report names why.

Use JSON for automation:

autodev fleet tick --output json

Do not infer success from a process saying it wrote a commit. autodev observes Git, evaluates evidence, records the judge verdict, and gates the integrated tree before applying.

Run the drive loop​

autodev fleet drive --ticks 60 --interval 5

The drive runs repeated ticks under a single-drive lease. By default it stops when the fleet is genuinely quiet or when the maximum tick count is reached. A ready story withheld by a disk floor, or a repository deliberately paused, is reported as stopped/paused rather than falsely called finished.

To keep serving instead of ending at the first quiet moment, use --loop:

autodev fleet drive --loop --interval 5

A quiet fleet then sleeps --interval and ticks again rather than ending the drive. --loop is refused alongside an explicit --ticks, because those are two different instructions about when to stop. It is not a daemon: it does not restart itself, and a signal still ends it.

Avoid killing a drive during an agent turn. If the process is terminated by a crash, reboot, or operator signal, restart with inspection. The next reconciler pass recovers ordinary dead workers and terminal worktrees, but some missing-process-group or refused-kill cases still require operator attention. Read the event record and fleet doctor; see Current limitations.

Inspect live and historical state​

autodev fleet status
autodev fleet status --output json
autodev fleet doctor
autodev fleet disk

status shows waves, workers, latest events, and pause/drain information. doctor focuses on wave states the reconciler cannot act on. disk shows cache and worktree pressure.

The daemon exposes the embedded loopback-only operator workspace and drives every registered workspace:

autodev daemon start --single-user

The client is compiled into the binary and served at http://127.0.0.1:7777/; the machine API is separate at 127.0.0.1:7788. --single-user grants act on loopback. Otherwise connections are read-only unless the daemon was started with an --act-token and the client presents it as ?token=.... Treat that token as a secret. See Use the operator workspace for its evidence and authority boundaries.

For a registered workspace, do not start a second daemon or a competing fleet drive. The same daemon process owns its global runtime store, serves both listeners, and runs the drive:

autodev daemon start --single-user

See Central daemon and workspaces for registration and history import.

Shut down for a safe binary replacement​

Shutdown prevents every later external-command launch while current commands finish:

autodev fleet shutdown \
  --reason "replace fleet binary" \
  --principal operator \
  --wait 600

At the timeout overdue process groups receive TERM, then KILL. Exit 0 and frozen mean the fleet-wide command floor is empty; completed commands have durable resume checkpoints.

Resume normal dispatch afterwards:

autodev fleet start --principal operator

autodev daemon stop and autodev daemon restart do not signal or replace the daemon. After a frozen shutdown, let the supervisor replace it, verify daemon status, and only then start.

Recover a wave​

First pause new dispatch and read fleet status, fleet doctor, and the event sequence. Then use a typed state transition:

autodev fleet park wave-12 --reason "investigating repeated gate failure"
autodev fleet unpark wave-12

Parking cancels workers but keeps the wave's stories held. A running tick does not hold the repository write lock across its turns, so parking does not require stopping the drive first.

Unparking has two outcomes. Normally it reopens the wave and restores one attempt. But a wave must re-earn the areas it claims before re-entering the loop: if another live wave now holds one of them, the wave stays parked, nothing is written, and the answer names the area and the wave holding it. It re-enters when that claim is released.

If the wave must end and release its stories for future dispatch:

autodev fleet retire wave-12 --reason "superseded by corrected contracts"

There is no fleet cancel command. Do not delete the SQLite store or lock files as routine recovery; that discards the evidence you need to diagnose the failure and may erase unrelated fleet state.

Know the delivery boundary​

The fleet can apply an integrated, gated commit to the local branch and advance a story to done. It does not imply authority to:

  • push the branch;
  • merge a remote pull request;
  • publish a crate or package;
  • deploy an environment;
  • notify external systems.

Those remain separate operator or automation actions unless your surrounding system explicitly provides them.