Skip to content

v0.4.3

Choose a tag to compare

@kumaakh kumaakh released this 28 Sep 15:29
· 190 commits to main since this release
f390e28

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).

  1. Beads bd 1.3.0 (installed via npm) is required on every member that runs sprints -- the orchestrator and every doer/reviewer clone. Check with bd version. A mixed-version fleet fails in sync, not at launch.

  2. 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 with node --version and npm --version. Installing with --workflows none installs the core without fleet-se, so Node.js/npm are not required there. Updating from 0.4.2 with apra-fleet update on 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); run apra-fleet install --force --workflows none to install the 0.4.3 core, or install Node.js 22.16+ first.

  3. {{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.. The apra-fleet auth CLI now takes secret.<name> / --secret (secure. / --secure remain as deprecated aliases). Canonical doc: docs/secret-variables.md.

  4. Breaking for scripted callers: the reason codes secure_credential_not_found / _denied / _expired were renamed to secret_variable_not_found / _denied / _expired with no alias. Anything that switches on structuredContent.reason must be updated.

  5. better-sqlite3 is no longer a dependency. Nothing loaded it at runtime (the knowledge bank uses builtin node:sqlite). If you extended apra-fleet locally and import 'better-sqlite3', move to node:sqlite (DatabaseSync). No KB data migration.

  6. Beads-identity check is fatal. Every sprint now verifies that each member's .beads belongs to the project it was launched for. A member whose workFolder is not a git clone with an origin remote, or has no sync.remote configured, fails the precondition -- fix the workFolder rather than bypassing (there is no bypass flag). fleet-se serve also hard-fails at startup when it cannot find a single .beads (pass --beads-dir to point it explicitly).

  7. Breaking for GitHub App users -- action required: two new App permissions. Tokens are minted with exactly the permission set of the requested git_access level; 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, admin and full (pushes touching .github/workflows/**).
    • Actions: Read and write on push+pr (agents can re-run failed CI jobs on their own PRs; admin/full already 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.

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 23 kb_* / 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.json so 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_permissions discovers 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-sqlite3 removed; .beads.gate.lock ignored; opt-in check-bead-milestones operator 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 --force reuses 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)