apra-labs/apra-fleet/fleet-sprint-cli

fleet-sprint

fleet-sprint is apra-fleet's autonomous sprint engine. It drives a full plan -> develop -> review -> deploy -> integ-test -> harvest cycle across one or more registered fleet members, working a set of beads issues on a branch and opening a PR at the end.

The command

apra-fleet workflow fleet-sprint \
  --issue <id[,id2,...]> \
  --members <name[,name2,...]> \
  --branch <branch-name> \
  --base <base-branch> \
  [--goal P1|P1/P2|P1/P2/P3]      # default P1/P2
  [--max-cycles N]                # default 5
  [--allow-missing-members]
  [--requirements-file <path>]
  [--role-map <json|@file>]       # {"doer":["m1","m2"], ...}
  [--viewer-port <port>]          # default 8080
  [--budget <usd>]                # default unlimited
  [--dispatch-timeout-s <s>]      # default 9000
  [--usage-limit-max-wait-s <s>]  # usage-limit pause budget; default from role-policies
  [--usage-limit-max-reprobes <n>]# usage-limit reprobe cap; default from role-policies
  [--skip-regression]             # skip the once-per-sprint regression pass
  [--sync]                        # synced-topology mode

--issue, --members, --branch, and --base are required. Verify the live flag set with apra-fleet workflow fleet-sprint --help before relying on this list -- flags evolve and this skill can drift.

Flag notes

• --issue takes comma-separated beads parent/epic IDs. Scope is

resolved internally by walking the parent-child tree down from each target id (every descendant at any depth, any status), so it only ever understands the parent-child hierarchy. A blocked-by-only manifest bead is invisible to the scope filter no matter what you pass -- only true children are picked up. See the epics/manifest-bead guidance in packages/apra-fleet-se/fleet-sprint/docs/README.md.

• --branch must differ from --base (main vs origin/main or

refs/heads/main count as the same branch); an equal pair is rejected at launch.

• --branch is created from --base if it does not already exist. If it

does exist (e.g. you are resuming), it is reused as-is.

• `--base` is resolved against the remote, not your local checkout. A new

sprint branch is cut from origin/<base>, so any local commit on <base> that you have not pushed is invisible to the run. Push <base> first -- otherwise the sprint silently starts from an older tree, and work that depends on those commits (a .beads/config.yaml from bd init, a new package.json script) fails in ways that look unrelated.

• --role-map assigns specific members to specific roles, e.g.

--role-map '{"doer":["m1","m2"],"reviewer":["m3"]}'. Accepts inline JSON or @path/to/file.json. The backlog key names the member whose beads clone the engine runs its own bd/git commands against. orchestrator is its deprecated alias (works with a warning in 0.4.4, removed in v0.5) -- rename it to backlog. Without a backlog entry the engine picks a member and logs backlog: <member> (auto-selected: <reason>); check that line.

• --skip-regression skips the regression pass for this run. The skip is

logged and stated in the sprint analysis and the PR body.

• --goal controls which bead priorities are in scope for the run.
• --budget caps total spend in USD; the run aborts when it is exhausted.
• --usage-limit-max-wait-s / --usage-limit-max-reprobes bound how long a

dispatch that hit a provider usage/rate limit is paused (and re-probed on a backoff ladder) before the run gives up with a typed abort. Both are optional; omitted, the engine uses its own defaults. A resumed member re-dispatches without consuming a retry attempt.

Preconditions to check first

1. Every --issue target exists and is open: bd show <id>, **and already has

children**: bd list --parent <id> must return at least one open bead. Pre-sprint validation runs BEFORE the planner, so a childless epic aborts the run ("No open/in-progress/blocked/deferred beads found for scope ...") rather than being decomposed. The planner refines an existing DAG; it does not create the first level of it.

1. Every --members name is registered with the fleet (list_members /

mcp__apra-fleet__list_members). An unregistered member aborts the sprint unless --allow-missing-members is passed.

1. Multi-member sprints align their members automatically: at launch every

member is fetched and checked out on the sprint branch (WIP preserved in a named fleet-sprint[<branch>] stash, one [Align] line per member), so do not align members by hand. The launch refuses, before moving any member, only for an unreachable member, differing origin URLs, a base missing on origin, a fetch auth failure or a diverged sprint branch -- fix what the message names and relaunch. See fleet-sprint-diagram.md in the package docs.

1. If a member's LLM session is stale or unauthenticated (dispatch fails

with empty_response, or "member CLI likely died"), re-run provision_llm_auth for that member before retrying.

1. Beads identity: before any bd mutation, the sprint probes every

member's bd where/sync.remote/git origin and prints a Beads: banner plus one beads ok: <member> ... line per member. These abort with BeadsIdentityError naming the member, cause and fix, before anything is dispatched -- there is no bypass flag:

• MISMATCH: a field that resolved on both sides differs. Fix that

member's workFolder (wrong .beads) or its sync.remote.

• bd missing on a member (not installed or not on PATH). Fix: install

bd on that member or fix its PATH so bd --version works in its work folder (re-running the member fleet install places it in the member's fleet bin dir), then relaunch.

• BEADS_SETUP_FAILED: a member mapped to a beads-reading role had no beads

database (or no sync.remote), and setting it up from the expected beads remote failed. Matching members are left untouched. Any other probe failure (including no beads database on a member used only for deployer/ci-watcher) is only a [beads-identity] WARNING: line (naming the member, field, probe, error and the fix): that field is not compared and the sprint proceeds -- read the warning and fix the member.

Launching it

Run this on your own orchestrating machine, not on a --members target -- members are dispatch destinations, not where this command runs.

Use the installed apra-fleet binary. After npm install -g it is on PATH; the standalone installer does not add it to PATH, so call it as ~/.apra-fleet/bin/apra-fleet (Windows: $HOME\.apra-fleet\bin\apra-fleet.exe). Start it as a genuinely detached OS process. A harness-owned background task can be silently killed when its owning tool call's process group ends, which orphans the sprint mid-run.

Windows:

Start-Process -FilePath "apra-fleet" -ArgumentList "workflow","fleet-sprint", `
  "--issue","<id>","--members","<name>","--branch","<branch>","--base","<base>" `
  -RedirectStandardOutput "<log>.log" -RedirectStandardError "<log>.err.log" `
  -WindowStyle Hidden -PassThru

POSIX:

nohup apra-fleet workflow fleet-sprint \
  --issue <id> --members <name> --branch <branch> --base <base> \
  > sprint.log 2>&1 &
disown

From a source checkout you can run the same engine directly with node packages/apra-fleet-se/bin/cli.mjs <same flags>. That form runs the working tree instead of the installed copy -- use it when developing the engine itself, and the packaged binary otherwise.

Watching it

On start, the run prints a dashboard URL (http://localhost:<viewer-port>, default port 8080). Watch progress there rather than tailing raw stdout -- the dashboard shows per-role activity, the bead DAG, live cost, and the final verdict and PR link.