Repository navigation
v0.4.3
Before you upgrade
0.4.3 carries a few required upgrades and deprecations. Full details and discussion: Apra Fleet 0.4.3 -- deprecations and required upgrades (#496).
-
Beads
bd1.3.0 (installed via npm) is required on every member that runs sprints -- the orchestrator and every doer/reviewer clone. Check withbd version. A mixed-version fleet fails in sync, not at launch. -
Node.js 22.16 or later and npm are required on the machine running the supervisor/orchestrator and on every member that runs sprints. fleet-se -- the fleet-sprint engine, the fleet supervisor, and the beads task tracker
bd-- needs them; apra-fleet core (the single-binary server, console, members, secrets, health) does not. Check withnode --versionandnpm --version. Installing with--workflows noneinstalls the core without fleet-se, so Node.js/npm are not required there. Updating from 0.4.2 withapra-fleet updateon a machine without Node.js leaves 0.4.2 running (the new installer stops before changing anything, but the 0.4.2 updater hides its output); runapra-fleet install --force --workflows noneto install the 0.4.3 core, or install Node.js 22.16+ first. -
{{secure.NAME}}is deprecated -- use{{secret.NAME}}. The old spelling still resolves identically but appends a[deprecated]notice to the tool result and the fleet log; it does not hard-fail in 0.4.3. Update playbooks,deploy.md, saved prompts and sprint args:{{secure.->{{secret.. Theapra-fleet authCLI now takessecret.<name>/--secret(secure./--secureremain as deprecated aliases). Canonical doc:docs/secret-variables.md. -
Breaking for scripted callers: the reason codes
secure_credential_not_found/_denied/_expiredwere renamed tosecret_variable_not_found/_denied/_expiredwith no alias. Anything that switches onstructuredContent.reasonmust be updated. -
better-sqlite3is no longer a dependency. Nothing loaded it at runtime (the knowledge bank uses builtinnode:sqlite). If you extended apra-fleet locally andimport 'better-sqlite3', move tonode:sqlite(DatabaseSync). No KB data migration. -
Beads-identity check is fatal. Every sprint now verifies that each member's
.beadsbelongs to the project it was launched for. A member whose workFolder is not a git clone with anoriginremote, or has nosync.remoteconfigured, fails the precondition -- fix the workFolder rather than bypassing (there is no bypass flag).fleet-se servealso hard-fails at startup when it cannot find a single.beads(pass--beads-dirto point it explicitly). -
Breaking for GitHub App users -- action required: two new App permissions. Tokens are minted with exactly the permission set of the requested
git_accesslevel; if the App lacks any of them the mint fails with "is not granted one or more of the requested permissions" (no silent downgrade). 0.4.3 adds:- Workflows: Read and write on
push,push+pr,adminandfull(pushes touching.github/workflows/**). - Actions: Read and write on
push+pr(agents can re-run failed CI jobs on their own PRs;admin/fullalready had it).
Before upgrading, an org owner must add both to the fleet GitHub App (Settings -> Developer settings -> GitHub Apps -> Permissions & events) and accept the new permissions on the installation (org Settings -> GitHub Apps -> Configure -> Review request). Otherwise fleet-sprint pushes its branch but skips raising the PR (
[Publish PR Skipped] ... Could not provision a push+pr credential). PAT mode is unaffected. Setup guide and per-level table:docs/github-app-setup.md. - Workflows: Read and write on
Highlights
Dispatch reliability, especially on Windows. A dispatch to a Windows member no longer hangs after the LLM process has exited while a leftover child (sandbox server, test run, filesystem crawl) still holds the output pipe -- dispatches now complete on process exit with a short drain window. Test runners are bounded by wall-clock time with a process-tree kill, the stall detector catches frozen log tails with no parseable timestamp and uses an adaptive cadence, and a leaked per-member busy lock (an SSH drop during pre-exec steps left the member "busy" until restart) is now released. Writing the Claude workspace-trust file no longer fails with ENAMETOOLONG on Windows.
VCS auth that heals instead of flapping. Credential cleanup now revokes the exact credential a deploy wrote, instead of unsetting the right git-config key while orphaning the real token file. A push rejected because a member's Dolt clone was stale is no longer misread as a credential failure, and provision_vcs_auth stopped clobbering its own registration. register_member now detects and self-heals a member's VCS provider up front instead of failing hours into an unattended run, and provision_vcs_auth failures now carry their human-readable cause in structuredContent. Azure DevOps gained support for legacy *.visualstudio.com hosts, and PR descriptions are deterministically capped at 3500 chars so Azure DevOps no longer rejects them. push+pr tokens now carry actions:write, so an agent can re-run failed CI jobs on its own PR (see "Before you upgrade" item 6), and a new docs/github-app-setup.md documents exactly which App permissions each access level needs.
Beads: safer and cheaper. Every sprint verifies which beads database each member is mutating (see "Before you upgrade"), and the supervisor dashboard shows it. Beads/Dolt syncs per sprint are fewer and cheaper (bulk scope-guard fetch, probe memoization, time-boxed retries, remote-tip fingerprinting). Child-bead creation now refuses an id collision instead of bd silently overwriting an existing bead. A new maintenance playbook documents bd prune / bd flatten for reclaiming Dolt storage -- read its prerequisites first: flattening rewrites history and every other clone must re-bootstrap.
Antigravity (AGY) end to end. AGY members now run fleet-sprint roles: Claude-only tools with no Antigravity mapping are dropped from transformed agents (Antigravity CLI refused every role dispatch over ToolSearch), tool-discovery prose in the 11 role prompts is gated per provider, and permissions are delivered into isolated per-project configs so members run under --mode accept-edits with exact per-tool allowlists rather than machine-global grants.
execute_prompt session forking. New fork parameter (boolean or session id) branches a new session from an existing one -- implemented for Claude via --resume <src> --fork-session. Non-fork-capable providers return fork_unsupported; an unknown explicit fork source is a terminal session_not_found. Separately, every fleet-sprint dispatch site now states resume explicitly, so one-off prompts no longer silently reattach to a member's last (possibly huge) session.
Also in this release
- Knowledge bank:
memory-contract/v1-- a machine-checkable spec, JSON schemas, MCP/OpenAPI bindings and a conformance suite for the 23kb_*/code_*tools (with 81 newly confirmed canonical KB entries); config-driven HTTP KB provider selection restored; a title-keyed three-way merge for.fleet/kb-canonical.jsonso harvest conflicts no longer force a blind ours/theirs pick. - fleet-sprint planning: lanes are now the review unit for planner/plan-reviewer (fixes the D1 R1 D2 R2 doer-streak pattern); the planner treats CORRECTION/SUPERSEDES notes as authoritative over stale descriptions; deferred beads are named on every terminal path and no longer counted as blockers.
- Supervisor: sprint widget shows the merge target (
Branch: branch -> base). - Permissions:
compose_permissionsdiscovers provider-installed fleet profiles; onboarding exec timeouts raised from 5s to 15s. - Dogfood boundary: a build-time scanner fails if apra-fleet-specific assumptions leak into the generic sprint engine's prompts.
- Deploy: new Sandbox Deploy mode for integration/regression testing that converges on hosts where an OS supervisor (launchd/systemd) keeps the server alive.
- Runner refactor (in progress): the standalone runner refactor landed as incremental groundwork (9 of 16 children); the auto-sprint that built it did not reach a PASS.
- CI/tests: each test suite runs once per job (was twice); fleet-se test concurrency lowered to 4; flaky bd-replay template fixed; CI watcher runbook added.
better-sqlite3removed;.beads.gate.lockignored; opt-incheck-bead-milestonesoperator script.- Install hardening: the installer now fails loudly, before making any changes, when Node.js 22.16+/npm (required for fleet-se) are missing instead of silently skipping the beads step; on Windows,
install --forcereuses an existing elevated scheduled task instead of failing with Access Denied, and never reports success while the server is left stopped. - Release validation: a repeatable fresh-install test harness (Windows Sandbox + a clean Docker container) exercises a no-Node install, a full install, and both upgrade paths before each tag.
Pull requests in this release
| PR | Summary |
|---|---|
| #512 | Windows dispatches complete on process exit; bounded test runners; hardened stall detector |
| #537 | Release the per-member busy lock when a pre-exec step throws |
| #504 | Write workspace trust file via file channel, avoiding ENAMETOOLONG on Windows (#499) |
| #482 | Stall detector adaptive cadence |
| #511 | Stability: sync and stall fixes, deferred-bead accounting, workflows:write permission scope, missing-remote-ref push |
| #473 | VCS auth: revoke the exact credential a deploy wrote |
| #474 | Stale-Dolt-clone push no longer misread as a credential failure; provision_vcs_auth stops clobbering its registration |
| #467 | register_member detects and self-heals a member's VCS provider |
| #527 | Surface provision_vcs_auth failure cause in structuredContent |
| #541 | push+pr GitHub App tokens may re-run CI jobs (actions:write) -- App permission change required |
| #503 | Azure DevOps legacy *.visualstudio.com hosts; planner stops retrying a cancelled run (#502) |
| #475 | Cap PR description at 3500 chars, deterministically |
| #495 | Standardize on {{secret.NAME}}; deprecate {{secure.NAME}} with warning |
| #494 | Drop unused better-sqlite3 dependency |
| #498 | Show and verify the beads database every sprint member uses |
| #468 | Fewer and cheaper beads syncs per sprint |
| #486 | Guard against beads child-id collision overwrite |
| #488 | Beads prune/flatten/compact maintenance playbook |
| #519 | Antigravity end-to-end: isolated project permissions, conditional prompt gating |
| #509 | Drop Claude-only tools with no Antigravity mapping from transformed agents |
| #461 | execute_prompt session forking |
| #487 | State resume explicitly at every fleet-sprint dispatch site |
| #457 | memory-contract/v1: spec, schemas, bindings, conformance suite |
| #517 | Restore config-driven HTTP KB provider selection |
| #484 | Title-keyed three-way merge for the canonical KB export |
| #492 | Lanes are the review unit for planner/plan-reviewer |
| #481 | Planner reads parent NOTES; plan-reviewer contradiction check |
| #508 | Supervisor sprint widget shows merge target |
| #507 | compose_permissions discovers provider-installed fleet profiles |
| #471 | Enforce fleet-sprint's generic-product boundary |
| #470 | Sandbox Deploy mode for integration/regression testing |
| #469 | Standalone runner refactor groundwork (partial; sprint did not PASS) |
| #483 | Test-suite cleanup (partial; sprint aborted on stall) |
| #472 | Self-heal an incomplete bd-init test template |
| #480 | Widen phase4 regression pin after squash-merge |
| #491 | Lower fleet-se test concurrency from 8 to 4 |
| #534 | Run each CI test suite once per job |
| #489 | CI watcher runbook |
| #528 | Milestone check tool, ignore gate lock, groomer hygiene |
| #516 | Docs: fix the product, not the environment |
| #465 | Bumped version to 0.4.3 |
| #544 | Installer fails loudly when Node.js 22.16+/npm are missing, before any changes |
| #545 | Windows install reuses the existing elevated scheduled task; never reports success with the server stopped |
| #549 | Fresh-install release-validation harness (Windows Sandbox + Linux Docker) |