@apralabs/apra-fleet 0.4.1 → 0.4.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +53 -12
- package/dist/agents/backlog-groomer.md +42 -21
- package/dist/agents/ci-watcher.md +14 -0
- package/dist/agents/deployer.md +59 -46
- package/dist/agents/doer.md +157 -134
- package/dist/agents/harvester.md +31 -32
- package/dist/agents/integ-test-runner.md +92 -113
- package/dist/agents/kb-reconciler.md +40 -42
- package/dist/agents/plan-reviewer.md +139 -63
- package/dist/agents/planner.md +176 -100
- package/dist/agents/regression-test-runner.md +77 -81
- package/dist/agents/reviewer.md +69 -85
- package/dist/agents/schemas/integ-test-runner-output.json +1 -1
- package/dist/agents/schemas/plan-reviewer-output.json +37 -0
- package/dist/agents/schemas/regression-test-runner-output.json +4 -17
- package/dist/cli/agent-transform.d.ts +83 -2
- package/dist/cli/agent-transform.d.ts.map +1 -1
- package/dist/cli/agent-transform.js +266 -21
- package/dist/cli/agent-transform.js.map +1 -1
- package/dist/cli/auth.d.ts.map +1 -1
- package/dist/cli/auth.js +29 -11
- package/dist/cli/auth.js.map +1 -1
- package/dist/cli/config.d.ts +7 -5
- package/dist/cli/config.d.ts.map +1 -1
- package/dist/cli/config.js +44 -43
- package/dist/cli/config.js.map +1 -1
- package/dist/cli/install.d.ts +33 -0
- package/dist/cli/install.d.ts.map +1 -1
- package/dist/cli/install.js +294 -61
- package/dist/cli/install.js.map +1 -1
- package/dist/cli/kb-directives.d.ts.map +1 -1
- package/dist/cli/kb-directives.js +2 -1
- package/dist/cli/kb-directives.js.map +1 -1
- package/dist/cli/register-member.d.ts.map +1 -1
- package/dist/cli/register-member.js +7 -3
- package/dist/cli/register-member.js.map +1 -1
- package/dist/cli/start.d.ts.map +1 -1
- package/dist/cli/start.js +7 -0
- package/dist/cli/start.js.map +1 -1
- package/dist/cli/uninstall.d.ts.map +1 -1
- package/dist/cli/uninstall.js +5 -3
- package/dist/cli/uninstall.js.map +1 -1
- package/dist/cli/watch.d.ts +26 -3
- package/dist/cli/watch.d.ts.map +1 -1
- package/dist/cli/watch.js +41 -9
- package/dist/cli/watch.js.map +1 -1
- package/dist/commands/kb-server.d.ts +3 -0
- package/dist/commands/kb-server.d.ts.map +1 -1
- package/dist/commands/kb-server.js +43 -3
- package/dist/commands/kb-server.js.map +1 -1
- package/dist/index.js +3 -3
- package/dist/os/git-bash-candidates.d.ts +35 -0
- package/dist/os/git-bash-candidates.d.ts.map +1 -0
- package/dist/os/git-bash-candidates.js +46 -0
- package/dist/os/git-bash-candidates.js.map +1 -0
- package/dist/os/index.d.ts +13 -4
- package/dist/os/index.d.ts.map +1 -1
- package/dist/os/index.js +17 -2
- package/dist/os/index.js.map +1 -1
- package/dist/os/linux.d.ts +6 -0
- package/dist/os/linux.d.ts.map +1 -1
- package/dist/os/linux.js +36 -3
- package/dist/os/linux.js.map +1 -1
- package/dist/os/os-commands.d.ts +68 -2
- package/dist/os/os-commands.d.ts.map +1 -1
- package/dist/os/os-commands.js.map +1 -1
- package/dist/os/windows-gitbash.d.ts +98 -0
- package/dist/os/windows-gitbash.d.ts.map +1 -0
- package/dist/os/windows-gitbash.js +259 -0
- package/dist/os/windows-gitbash.js.map +1 -0
- package/dist/os/windows.d.ts +6 -0
- package/dist/os/windows.d.ts.map +1 -1
- package/dist/os/windows.js +73 -8
- package/dist/os/windows.js.map +1 -1
- package/dist/providers/agy.d.ts +118 -8
- package/dist/providers/agy.d.ts.map +1 -1
- package/dist/providers/agy.js +580 -55
- package/dist/providers/agy.js.map +1 -1
- package/dist/providers/claude.d.ts +83 -4
- package/dist/providers/claude.d.ts.map +1 -1
- package/dist/providers/claude.js +365 -12
- package/dist/providers/claude.js.map +1 -1
- package/dist/providers/codex.d.ts +7 -4
- package/dist/providers/codex.d.ts.map +1 -1
- package/dist/providers/codex.js +24 -4
- package/dist/providers/codex.js.map +1 -1
- package/dist/providers/copilot.d.ts +7 -4
- package/dist/providers/copilot.d.ts.map +1 -1
- package/dist/providers/copilot.js +27 -4
- package/dist/providers/copilot.js.map +1 -1
- package/dist/providers/index.d.ts +0 -1
- package/dist/providers/index.d.ts.map +1 -1
- package/dist/providers/index.js +0 -3
- package/dist/providers/index.js.map +1 -1
- package/dist/providers/none.d.ts +7 -4
- package/dist/providers/none.d.ts.map +1 -1
- package/dist/providers/none.js +22 -4
- package/dist/providers/none.js.map +1 -1
- package/dist/providers/opencode.d.ts +6 -3
- package/dist/providers/opencode.d.ts.map +1 -1
- package/dist/providers/opencode.js +27 -4
- package/dist/providers/opencode.js.map +1 -1
- package/dist/providers/provider.d.ts +215 -11
- package/dist/providers/provider.d.ts.map +1 -1
- package/dist/providers/provider.js +58 -2
- package/dist/providers/provider.js.map +1 -1
- package/dist/services/agent-provisioner.js +2 -2
- package/dist/services/agent-provisioner.js.map +1 -1
- package/dist/services/agy-project.d.ts +102 -0
- package/dist/services/agy-project.d.ts.map +1 -0
- package/dist/services/agy-project.js +356 -0
- package/dist/services/agy-project.js.map +1 -0
- package/dist/services/auth-socket.js +4 -4
- package/dist/services/auth-web.js +1 -1
- package/dist/services/cloud/activity.js +2 -2
- package/dist/services/cloud/activity.js.map +1 -1
- package/dist/services/cloud/lifecycle.d.ts.map +1 -1
- package/dist/services/cloud/lifecycle.js +33 -4
- package/dist/services/cloud/lifecycle.js.map +1 -1
- package/dist/services/context-admission.d.ts.map +1 -1
- package/dist/services/context-admission.js +9 -7
- package/dist/services/context-admission.js.map +1 -1
- package/dist/services/credential-cleanup.d.ts.map +1 -1
- package/dist/services/credential-cleanup.js +47 -10
- package/dist/services/credential-cleanup.js.map +1 -1
- package/dist/services/exit-drain.d.ts +44 -0
- package/dist/services/exit-drain.d.ts.map +1 -0
- package/dist/services/exit-drain.js +52 -0
- package/dist/services/exit-drain.js.map +1 -0
- package/dist/services/github-app.d.ts.map +1 -1
- package/dist/services/github-app.js +32 -4
- package/dist/services/github-app.js.map +1 -1
- package/dist/services/http-transport.d.ts +1 -0
- package/dist/services/http-transport.d.ts.map +1 -1
- package/dist/services/http-transport.js +48 -1
- package/dist/services/http-transport.js.map +1 -1
- package/dist/services/knowledge/kb-config.d.ts +42 -0
- package/dist/services/knowledge/kb-config.d.ts.map +1 -0
- package/dist/services/knowledge/kb-config.js +54 -0
- package/dist/services/knowledge/kb-config.js.map +1 -0
- package/dist/services/knowledge/kb-providers.d.ts +7 -1
- package/dist/services/knowledge/kb-providers.d.ts.map +1 -1
- package/dist/services/knowledge/kb-providers.js +191 -17
- package/dist/services/knowledge/kb-providers.js.map +1 -1
- package/dist/services/knowledge/require-sqlite-project.d.ts +32 -0
- package/dist/services/knowledge/require-sqlite-project.d.ts.map +1 -0
- package/dist/services/knowledge/require-sqlite-project.js +38 -0
- package/dist/services/knowledge/require-sqlite-project.js.map +1 -0
- package/dist/services/member-home.d.ts +1 -1
- package/dist/services/member-home.d.ts.map +1 -1
- package/dist/services/member-home.js +15 -12
- package/dist/services/member-home.js.map +1 -1
- package/dist/services/model-pricing.d.ts.map +1 -1
- package/dist/services/model-pricing.js +7 -8
- package/dist/services/model-pricing.js.map +1 -1
- package/dist/services/orphan-recovery.d.ts +6 -3
- package/dist/services/orphan-recovery.d.ts.map +1 -1
- package/dist/services/orphan-recovery.js +17 -14
- package/dist/services/orphan-recovery.js.map +1 -1
- package/dist/services/preflight-check.js +2 -2
- package/dist/services/preflight-check.js.map +1 -1
- package/dist/services/secret-token.d.ts +38 -0
- package/dist/services/secret-token.d.ts.map +1 -0
- package/dist/services/secret-token.js +51 -0
- package/dist/services/secret-token.js.map +1 -0
- package/dist/services/service-manager/types.d.ts +3 -1
- package/dist/services/service-manager/types.d.ts.map +1 -1
- package/dist/services/service-manager/windows.d.ts +14 -2
- package/dist/services/service-manager/windows.d.ts.map +1 -1
- package/dist/services/service-manager/windows.js +65 -7
- package/dist/services/service-manager/windows.js.map +1 -1
- package/dist/services/shell-probe.d.ts +131 -0
- package/dist/services/shell-probe.d.ts.map +1 -0
- package/dist/services/shell-probe.js +210 -0
- package/dist/services/shell-probe.js.map +1 -0
- package/dist/services/singleton.d.ts +2 -0
- package/dist/services/singleton.d.ts.map +1 -1
- package/dist/services/singleton.js +1 -1
- package/dist/services/singleton.js.map +1 -1
- package/dist/services/ssh.d.ts.map +1 -1
- package/dist/services/ssh.js +60 -4
- package/dist/services/ssh.js.map +1 -1
- package/dist/services/stall/find-log-file.d.ts.map +1 -1
- package/dist/services/stall/find-log-file.js +22 -16
- package/dist/services/stall/find-log-file.js.map +1 -1
- package/dist/services/stall/read-log-tail.d.ts.map +1 -1
- package/dist/services/stall/read-log-tail.js +26 -15
- package/dist/services/stall/read-log-tail.js.map +1 -1
- package/dist/services/stall/stall-detector.d.ts +53 -4
- package/dist/services/stall/stall-detector.d.ts.map +1 -1
- package/dist/services/stall/stall-detector.js +212 -34
- package/dist/services/stall/stall-detector.js.map +1 -1
- package/dist/services/stall/stall-poller.d.ts.map +1 -1
- package/dist/services/stall/stall-poller.js +35 -42
- package/dist/services/stall/stall-poller.js.map +1 -1
- package/dist/services/strategy.d.ts +9 -0
- package/dist/services/strategy.d.ts.map +1 -1
- package/dist/services/strategy.js +119 -8
- package/dist/services/strategy.js.map +1 -1
- package/dist/services/substitution-engine.js +2 -2
- package/dist/services/substitution-engine.js.map +1 -1
- package/dist/services/tool-registry.d.ts.map +1 -1
- package/dist/services/tool-registry.js +5 -3
- package/dist/services/tool-registry.js.map +1 -1
- package/dist/services/user-config.js +1 -1
- package/dist/services/user-config.js.map +1 -1
- package/dist/services/vcs/azure-devops.d.ts +67 -2
- package/dist/services/vcs/azure-devops.d.ts.map +1 -1
- package/dist/services/vcs/azure-devops.js +281 -15
- package/dist/services/vcs/azure-devops.js.map +1 -1
- package/dist/services/vcs/bitbucket.d.ts.map +1 -1
- package/dist/services/vcs/bitbucket.js +16 -0
- package/dist/services/vcs/bitbucket.js.map +1 -1
- package/dist/services/vcs/github.d.ts.map +1 -1
- package/dist/services/vcs/github.js +24 -0
- package/dist/services/vcs/github.js.map +1 -1
- package/dist/services/vcs/types.d.ts +123 -2
- package/dist/services/vcs/types.d.ts.map +1 -1
- package/dist/skills/fleet-sprint-cli/SKILL.md +20 -1
- package/dist/skills/pm/SKILL.md +1 -2
- package/dist/skills/pm/cost.md +0 -4
- package/dist/skills/pm/fleet-addendum.md +2 -3
- package/dist/tools/check-status.d.ts +7 -4
- package/dist/tools/check-status.d.ts.map +1 -1
- package/dist/tools/check-status.js +5 -3
- package/dist/tools/check-status.js.map +1 -1
- package/dist/tools/cloud-control.js +2 -2
- package/dist/tools/cloud-control.js.map +1 -1
- package/dist/tools/compose-permissions.d.ts +6 -0
- package/dist/tools/compose-permissions.d.ts.map +1 -1
- package/dist/tools/compose-permissions.js +211 -50
- package/dist/tools/compose-permissions.js.map +1 -1
- package/dist/tools/credential-store-set.js +1 -1
- package/dist/tools/execute-command.d.ts.map +1 -1
- package/dist/tools/execute-command.js +56 -29
- package/dist/tools/execute-command.js.map +1 -1
- package/dist/tools/execute-prompt.d.ts +15 -2
- package/dist/tools/execute-prompt.d.ts.map +1 -1
- package/dist/tools/execute-prompt.js +1214 -873
- package/dist/tools/execute-prompt.js.map +1 -1
- package/dist/tools/kb-capture.d.ts +2 -2
- package/dist/tools/kb-capture.d.ts.map +1 -1
- package/dist/tools/kb-capture.js +29 -5
- package/dist/tools/kb-capture.js.map +1 -1
- package/dist/tools/kb-export.d.ts +2 -2
- package/dist/tools/kb-export.d.ts.map +1 -1
- package/dist/tools/kb-export.js +3 -28
- package/dist/tools/kb-export.js.map +1 -1
- package/dist/tools/kb-feedback.d.ts.map +1 -1
- package/dist/tools/kb-feedback.js +3 -1
- package/dist/tools/kb-feedback.js.map +1 -1
- package/dist/tools/kb-freshness-sweep.d.ts.map +1 -1
- package/dist/tools/kb-freshness-sweep.js +3 -1
- package/dist/tools/kb-freshness-sweep.js.map +1 -1
- package/dist/tools/kb-import.d.ts.map +1 -1
- package/dist/tools/kb-import.js +2 -1
- package/dist/tools/kb-import.js.map +1 -1
- package/dist/tools/kb-list.d.ts.map +1 -1
- package/dist/tools/kb-list.js +3 -1
- package/dist/tools/kb-list.js.map +1 -1
- package/dist/tools/kb-query.d.ts +2 -2
- package/dist/tools/kb-reconcile-prefilter.d.ts.map +1 -1
- package/dist/tools/kb-reconcile-prefilter.js +3 -1
- package/dist/tools/kb-reconcile-prefilter.js.map +1 -1
- package/dist/tools/kb-resolve-contradiction.d.ts.map +1 -1
- package/dist/tools/kb-resolve-contradiction.js +3 -1
- package/dist/tools/kb-resolve-contradiction.js.map +1 -1
- package/dist/tools/kb-setup.d.ts.map +1 -1
- package/dist/tools/kb-setup.js +125 -20
- package/dist/tools/kb-setup.js.map +1 -1
- package/dist/tools/kb-stats.d.ts.map +1 -1
- package/dist/tools/kb-stats.js +64 -43
- package/dist/tools/kb-stats.js.map +1 -1
- package/dist/tools/list-members.d.ts +2 -2
- package/dist/tools/list-members.d.ts.map +1 -1
- package/dist/tools/list-members.js +7 -2
- package/dist/tools/list-members.js.map +1 -1
- package/dist/tools/member-detail.d.ts +2 -2
- package/dist/tools/member-detail.d.ts.map +1 -1
- package/dist/tools/member-detail.js +22 -3
- package/dist/tools/member-detail.js.map +1 -1
- package/dist/tools/member-reservation.d.ts +58 -1
- package/dist/tools/member-reservation.d.ts.map +1 -1
- package/dist/tools/member-reservation.js +71 -18
- package/dist/tools/member-reservation.js.map +1 -1
- package/dist/tools/monitor-task.d.ts.map +1 -1
- package/dist/tools/monitor-task.js +17 -2
- package/dist/tools/monitor-task.js.map +1 -1
- package/dist/tools/provision-auth.d.ts +80 -1
- package/dist/tools/provision-auth.d.ts.map +1 -1
- package/dist/tools/provision-auth.js +147 -59
- package/dist/tools/provision-auth.js.map +1 -1
- package/dist/tools/provision-vcs-auth.d.ts +96 -3
- package/dist/tools/provision-vcs-auth.d.ts.map +1 -1
- package/dist/tools/provision-vcs-auth.js +254 -88
- package/dist/tools/provision-vcs-auth.js.map +1 -1
- package/dist/tools/register-member.d.ts +21 -12
- package/dist/tools/register-member.d.ts.map +1 -1
- package/dist/tools/register-member.js +141 -16
- package/dist/tools/register-member.js.map +1 -1
- package/dist/tools/remove-member.d.ts.map +1 -1
- package/dist/tools/remove-member.js +29 -4
- package/dist/tools/remove-member.js.map +1 -1
- package/dist/tools/revoke-vcs-auth.js +2 -2
- package/dist/tools/revoke-vcs-auth.js.map +1 -1
- package/dist/tools/send-email.d.ts +2 -2
- package/dist/tools/setup-git-app.d.ts.map +1 -1
- package/dist/tools/setup-git-app.js +11 -7
- package/dist/tools/setup-git-app.js.map +1 -1
- package/dist/tools/setup-ssh-key.d.ts.map +1 -1
- package/dist/tools/setup-ssh-key.js +2 -1
- package/dist/tools/setup-ssh-key.js.map +1 -1
- package/dist/tools/shutdown-server.d.ts +2 -0
- package/dist/tools/shutdown-server.d.ts.map +1 -1
- package/dist/tools/shutdown-server.js +23 -1
- package/dist/tools/shutdown-server.js.map +1 -1
- package/dist/tools/stop-prompt.js +2 -2
- package/dist/tools/stop-prompt.js.map +1 -1
- package/dist/tools/update-agent-cli.js +2 -2
- package/dist/tools/update-agent-cli.js.map +1 -1
- package/dist/tools/update-member.d.ts +21 -12
- package/dist/tools/update-member.d.ts.map +1 -1
- package/dist/tools/update-member.js +61 -12
- package/dist/tools/update-member.js.map +1 -1
- package/dist/tools/vcs-credential-exec.d.ts +127 -0
- package/dist/tools/vcs-credential-exec.d.ts.map +1 -0
- package/dist/tools/vcs-credential-exec.js +197 -0
- package/dist/tools/vcs-credential-exec.js.map +1 -0
- package/dist/types.d.ts +24 -1
- package/dist/types.d.ts.map +1 -1
- package/dist/utils/agent-helpers.d.ts +36 -0
- package/dist/utils/agent-helpers.d.ts.map +1 -1
- package/dist/utils/agent-helpers.js +39 -1
- package/dist/utils/agent-helpers.js.map +1 -1
- package/dist/utils/log-helpers.d.ts.map +1 -1
- package/dist/utils/log-helpers.js +2 -2
- package/dist/utils/log-helpers.js.map +1 -1
- package/dist/utils/platform.d.ts +7 -0
- package/dist/utils/platform.d.ts.map +1 -1
- package/dist/utils/platform.js +11 -1
- package/dist/utils/platform.js.map +1 -1
- package/dist/utils/prompt-errors.d.ts.map +1 -1
- package/dist/utils/prompt-errors.js +7 -1
- package/dist/utils/prompt-errors.js.map +1 -1
- package/dist/utils/shell-escape.d.ts +16 -0
- package/dist/utils/shell-escape.d.ts.map +1 -1
- package/dist/utils/shell-escape.js +22 -2
- package/dist/utils/shell-escape.js.map +1 -1
- package/dist/utils/vcs-provider-detect.d.ts +65 -0
- package/dist/utils/vcs-provider-detect.d.ts.map +1 -0
- package/dist/utils/vcs-provider-detect.js +109 -0
- package/dist/utils/vcs-provider-detect.js.map +1 -0
- package/dist/utils/workspace-trust.d.ts +20 -17
- package/dist/utils/workspace-trust.d.ts.map +1 -1
- package/dist/utils/workspace-trust.js +91 -1
- package/dist/utils/workspace-trust.js.map +1 -1
- package/dist/workflows/auto-sprint.js +180 -32
- package/package.json +7 -5
- package/packages/apra-fleet-client/src/client/api.mjs +403 -12
- package/packages/apra-fleet-client/src/client/errors.mjs +6 -2
- package/packages/apra-fleet-se/apra-pm/agents/_shared/GRAPH-SEMANTICS.md +10 -2
- package/packages/apra-fleet-se/apra-pm/agents/backlog-groomer.md +42 -21
- package/packages/apra-fleet-se/apra-pm/agents/ci-watcher.md +14 -0
- package/packages/apra-fleet-se/apra-pm/agents/deployer.md +59 -46
- package/packages/apra-fleet-se/apra-pm/agents/doer.md +157 -134
- package/packages/apra-fleet-se/apra-pm/agents/harvester.md +31 -32
- package/packages/apra-fleet-se/apra-pm/agents/integ-test-runner.md +92 -113
- package/packages/apra-fleet-se/apra-pm/agents/kb-reconciler.md +40 -42
- package/packages/apra-fleet-se/apra-pm/agents/plan-reviewer.md +139 -63
- package/packages/apra-fleet-se/apra-pm/agents/planner.md +176 -100
- package/packages/apra-fleet-se/apra-pm/agents/regression-test-runner.md +77 -81
- package/packages/apra-fleet-se/apra-pm/agents/reviewer.md +69 -85
- package/packages/apra-fleet-se/apra-pm/agents/schemas/integ-test-runner-output.json +1 -1
- package/packages/apra-fleet-se/apra-pm/agents/schemas/plan-reviewer-output.json +37 -0
- package/packages/apra-fleet-se/apra-pm/agents/schemas/regression-test-runner-output.json +4 -17
- package/packages/apra-fleet-se/apra-pm/skills/pm/SKILL.md +1 -2
- package/packages/apra-fleet-se/apra-pm/skills/pm/cost.md +0 -4
- package/packages/apra-fleet-se/apra-pm/skills/pm/fleet-addendum.md +2 -3
- package/packages/apra-fleet-se/bin/cli.mjs +280 -3
- package/packages/apra-fleet-se/bin/serve.mjs +114 -5
- package/packages/apra-fleet-se/fleet-sprint/abort.mjs +481 -0
- package/packages/apra-fleet-se/fleet-sprint/beads-children.mjs +491 -0
- package/packages/apra-fleet-se/fleet-sprint/beads-identity-check.mjs +282 -0
- package/packages/apra-fleet-se/fleet-sprint/beads-identity.mjs +208 -0
- package/packages/apra-fleet-se/fleet-sprint/beads-scope.mjs +638 -0
- package/packages/apra-fleet-se/fleet-sprint/beads-transitions.mjs +301 -0
- package/packages/apra-fleet-se/fleet-sprint/branch-ensure.mjs +96 -0
- package/packages/apra-fleet-se/fleet-sprint/conflict-ladder.mjs +8 -0
- package/packages/apra-fleet-se/fleet-sprint/contracts.mjs +199 -34
- package/packages/apra-fleet-se/fleet-sprint/coordination.mjs +516 -0
- package/packages/apra-fleet-se/fleet-sprint/dispatch-failure.mjs +184 -0
- package/packages/apra-fleet-se/fleet-sprint/dispatch-role.mjs +1121 -0
- package/packages/apra-fleet-se/fleet-sprint/dispatch-safety-guard.mjs +216 -4
- package/packages/apra-fleet-se/fleet-sprint/docs/README.md +23 -8
- package/packages/apra-fleet-se/fleet-sprint/docs/dolt-manual-recovery-verified.md +10 -8
- package/packages/apra-fleet-se/fleet-sprint/docs/dolt-sync-redesign.md +285 -4
- package/packages/apra-fleet-se/fleet-sprint/docs/escalate-to-llm-design.md +3 -3
- package/packages/apra-fleet-se/fleet-sprint/docs/run-sprint-cycle-prelude-decision.md +215 -0
- package/packages/apra-fleet-se/fleet-sprint/docs/shared-orchestrator-reservation-design.md +12 -12
- package/packages/apra-fleet-se/fleet-sprint/docs/stabilization-log.md +14 -4
- package/packages/apra-fleet-se/fleet-sprint/dolt-literal-guard.mjs +56 -1
- package/packages/apra-fleet-se/fleet-sprint/dolt-settle.mjs +275 -99
- package/packages/apra-fleet-se/fleet-sprint/dolt-sync.mjs +1054 -39
- package/packages/apra-fleet-se/fleet-sprint/errors.mjs +308 -0
- package/packages/apra-fleet-se/fleet-sprint/explicit-id-create-guard.mjs +501 -0
- package/packages/apra-fleet-se/fleet-sprint/fatal-diagnostics.mjs +134 -0
- package/packages/apra-fleet-se/fleet-sprint/full-db-fetch-guard.mjs +102 -0
- package/packages/apra-fleet-se/fleet-sprint/git-sync.mjs +556 -0
- package/packages/apra-fleet-se/fleet-sprint/git-topology.mjs +495 -0
- package/packages/apra-fleet-se/fleet-sprint/guarded-modules.mjs +564 -0
- package/packages/apra-fleet-se/fleet-sprint/inline-ladder-guard.mjs +216 -0
- package/packages/apra-fleet-se/fleet-sprint/kb.mjs +728 -0
- package/packages/apra-fleet-se/fleet-sprint/mcp-result.mjs +75 -0
- package/packages/apra-fleet-se/fleet-sprint/member-provisioning.mjs +252 -0
- package/packages/apra-fleet-se/fleet-sprint/member-sync.mjs +581 -0
- package/packages/apra-fleet-se/fleet-sprint/member-target.mjs +93 -0
- package/packages/apra-fleet-se/fleet-sprint/newtask-text.mjs +266 -0
- package/packages/apra-fleet-se/fleet-sprint/parent-notes-staleness.mjs +201 -0
- package/packages/apra-fleet-se/fleet-sprint/phases/deploy.mjs +136 -0
- package/packages/apra-fleet-se/fleet-sprint/phases/develop.mjs +822 -0
- package/packages/apra-fleet-se/fleet-sprint/phases/ensure-sprint-branch.mjs +294 -0
- package/packages/apra-fleet-se/fleet-sprint/phases/final-review.mjs +403 -0
- package/packages/apra-fleet-se/fleet-sprint/phases/harvest.mjs +180 -0
- package/packages/apra-fleet-se/fleet-sprint/phases/integ-test.mjs +358 -0
- package/packages/apra-fleet-se/fleet-sprint/phases/plan.mjs +390 -0
- package/packages/apra-fleet-se/fleet-sprint/phases/publish-pr.mjs +323 -0
- package/packages/apra-fleet-se/fleet-sprint/phases/re-review.mjs +232 -0
- package/packages/apra-fleet-se/fleet-sprint/phases/regression-test.mjs +174 -0
- package/packages/apra-fleet-se/fleet-sprint/phases/replan.mjs +197 -0
- package/packages/apra-fleet-se/fleet-sprint/phases/review.mjs +305 -0
- package/packages/apra-fleet-se/fleet-sprint/prompts.mjs +559 -0
- package/packages/apra-fleet-se/fleet-sprint/role-policies.mjs +1416 -0
- package/packages/apra-fleet-se/fleet-sprint/round-session.mjs +100 -0
- package/packages/apra-fleet-se/fleet-sprint/runner.js +1672 -9072
- package/packages/apra-fleet-se/fleet-sprint/se-os-commands.mjs +134 -0
- package/packages/apra-fleet-se/fleet-sprint/se-posix.mjs +159 -0
- package/packages/apra-fleet-se/fleet-sprint/se-windows-gitbash.mjs +97 -0
- package/packages/apra-fleet-se/fleet-sprint/se-windows.mjs +143 -0
- package/packages/apra-fleet-se/fleet-sprint/shell-command-guard.mjs +304 -0
- package/packages/apra-fleet-se/fleet-sprint/skills/fleet-sprint-cli/SKILL.md +20 -1
- package/packages/apra-fleet-se/fleet-sprint/skills/fleet-supervisor/SKILL.md +21 -2
- package/packages/apra-fleet-se/fleet-sprint/sprint-args.mjs +454 -0
- package/packages/apra-fleet-se/fleet-sprint/sprint-report.mjs +239 -0
- package/packages/apra-fleet-se/fleet-sprint/sprint-state.mjs +163 -0
- package/packages/apra-fleet-se/fleet-sprint/unbracketed-push-guard.mjs +234 -0
- package/packages/apra-fleet-se/fleet-sprint/usage-limit-controller.mjs +211 -0
- package/packages/apra-fleet-se/fleet-sprint/vcs-auth.mjs +1279 -0
- package/packages/apra-fleet-se/fleet-sprint/vcs-module.mjs +204 -19
- package/packages/apra-fleet-se/fleet-sprint/vcs-providers/azure-devops.mjs +707 -12
- package/packages/apra-fleet-se/fleet-sprint/vcs-providers/bitbucket.mjs +28 -0
- package/packages/apra-fleet-se/fleet-sprint/vcs-providers/dolt.mjs +33 -4
- package/packages/apra-fleet-se/fleet-sprint/vcs-providers/github.mjs +191 -43
- package/packages/apra-fleet-se/fleet-sprint/vcs-providers/index.mjs +333 -6
- package/packages/apra-fleet-se/fleet-sprint/vcs-providers/shell-helpers.mjs +165 -0
- package/packages/apra-fleet-se/fleet-sprint/viewer-extensions.mjs +167 -37
- package/packages/apra-fleet-se/fleet-sprint/worklists.mjs +559 -0
- package/packages/apra-fleet-se/package.json +1 -1
- package/packages/apra-fleet-workflow/src/viewer/index.mjs +178 -1
- package/packages/apra-fleet-workflow/src/workflow/index.mjs +478 -32
- package/skills/fleet/SKILL.md +27 -16
- package/skills/fleet/auth-azdevops.md +57 -7
- package/skills/fleet/auth-bitbucket.md +5 -5
- package/skills/fleet/auth-github.md +7 -6
- package/skills/fleet/beads-conflict-resolution.md +141 -0
- package/skills/fleet/beads.md +16 -12
- package/skills/fleet/onboarding.md +6 -6
- package/skills/fleet/permissions.md +11 -7
- package/skills/fleet/profiles/node.json +1 -1
- package/skills/fleet/skill-matrix.md +1 -1
- package/skills/fleet/troubleshooting.md +4 -3
- package/version.json +1 -1
- package/dist/providers/gemini.d.ts +0 -52
- package/dist/providers/gemini.d.ts.map +0 -1
- package/dist/providers/gemini.js +0 -236
- package/dist/providers/gemini.js.map +0 -1
- package/packages/apra-fleet-se/fleet-sprint/docs/coach-role-design.md +0 -23
|
@@ -1,13 +1,18 @@
|
|
|
1
1
|
# Dolt sync redesign: from a 3-tier recovery ladder to one deterministic settle step
|
|
2
2
|
|
|
3
|
-
Status:
|
|
4
|
-
|
|
5
|
-
|
|
3
|
+
Status: IMPLEMENTED. Every part of this design has landed. The document is
|
|
4
|
+
retained as the reference for WHY the system is shaped this way, and the
|
|
5
|
+
source cites its Part numbers directly (`dolt-settle.mjs`, `dolt-sync.mjs`,
|
|
6
|
+
`runner.js`, `bin/serve.mjs`, `src/supervisor/server.mjs`,
|
|
7
|
+
`dolt-orphan-sweep.mjs`, `dolt-mutex.mjs`, `fleet-members.mjs`, and several
|
|
8
|
+
tests), so **the Part numbering here is load-bearing -- do not renumber it.**
|
|
9
|
+
Part 4's table is the live-run verification record.
|
|
10
|
+
|
|
6
11
|
See `dolt-manual-recovery-verified.md` for the live-verified mechanical spec
|
|
7
12
|
(exact flags, exact commands, exact OS-specific detachment technique) this
|
|
8
13
|
design's `settle()` step is built from.
|
|
9
14
|
|
|
10
|
-
###
|
|
15
|
+
### What landed, part by part
|
|
11
16
|
|
|
12
17
|
| Part | Item | Status |
|
|
13
18
|
|------|------|--------|
|
|
@@ -1188,6 +1193,57 @@ For the target member M, starting from both clones at the same sandbox head:
|
|
|
1188
1193
|
declared verified. It is intentionally NOT in any default CI pass, and no
|
|
1189
1194
|
CI configuration should be added that pretends otherwise.
|
|
1190
1195
|
|
|
1196
|
+
### 6.7 Re-affirmed CI-exclusion decision (apra-fleet-j918.5.3, current pass)
|
|
1197
|
+
|
|
1198
|
+
**Decided 2026-09-15, against tree `f4eda6e08e53412c5cffe5bae25d686280987cbd`
|
|
1199
|
+
(branch `chore/j918-test-suite-cleanup`).** A test-suite audit flagged that
|
|
1200
|
+
the merge-conflict recovery path (`settleDoltConflicts()`,
|
|
1201
|
+
`fleet-sprint/dolt-settle.mjs`) is exercised in `npm test` ONLY by
|
|
1202
|
+
`test/dolt-settle.test.mjs`'s hand-written SQL-string simulator -- a scripted
|
|
1203
|
+
`command()` mock that regex-matches emitted SQL text (`CALL DOLT_MERGE`,
|
|
1204
|
+
`SELECT * FROM dolt_conflicts`, `CALL DOLT_CONFLICTS_RESOLVE`, ...; see e.g.
|
|
1205
|
+
`test/dolt-settle.test.mjs:389-423`) rather than running a real `dolt`
|
|
1206
|
+
process. This 6.2/6.6 exclusion was decided in 2026-08 for a different
|
|
1207
|
+
reason (no generic CI runner has a live fleet server or SSH-reachable
|
|
1208
|
+
members) and never separately weighed against the fact that CI's only
|
|
1209
|
+
coverage of the real recovery path is that simulator. Re-examining now
|
|
1210
|
+
because the failure mode this path guards -- a Dolt-CLI/SQL-dialect
|
|
1211
|
+
regression silently corrupting or losing rows in the SHARED beads DB during
|
|
1212
|
+
a real merge -- is a data-loss risk, and an inherited justification for a
|
|
1213
|
+
different concern is not evidence this specific gap is acceptable.
|
|
1214
|
+
|
|
1215
|
+
**The header's exclusion claim was re-verified against the current file
|
|
1216
|
+
before writing this section** (`scripts/dolt-settle-integration.mjs:24-27`):
|
|
1217
|
+
it still requires a live `apra-fleet` server (`ApraFleet`/`McpClient` over
|
|
1218
|
+
`resolveFleetServerConnection`) plus SSH-reachable members
|
|
1219
|
+
(`createMemberReservationClient`, real `execute_command` dispatch) -- nothing
|
|
1220
|
+
about that dependency has changed since Part 6.2, so **this script itself
|
|
1221
|
+
stays excluded from `npm test`/`test:unit`/`test:slow`, unchanged.** Its
|
|
1222
|
+
live-fleet/SSH requirement is a hard blocker for any generic CI runner
|
|
1223
|
+
regardless of how cheap `dolt` itself is to run.
|
|
1224
|
+
|
|
1225
|
+
That said, the data-loss coverage gap is real and worth closing separately,
|
|
1226
|
+
because it does not actually require this script's live-fleet/SSH machinery:
|
|
1227
|
+
`dolt` is a single, statically-linked binary, already version-pinned
|
|
1228
|
+
(`DOLT_VERSION`, Part 5.1), and `settleDoltConflicts()` only needs an
|
|
1229
|
+
injected `command()` -- it never requires the fleet/SSH transport itself.
|
|
1230
|
+
A much narrower job -- two local `bd` clones on the CI runner, a local
|
|
1231
|
+
merge conflict manufactured directly (no fleet server, no member
|
|
1232
|
+
reservation, no SSH), and `settleDoltConflicts()` wired to a `command()`
|
|
1233
|
+
that shells out to the pinned local `dolt` binary -- is plausible without
|
|
1234
|
+
reproducing any of the live-fleet dependency that justifies excluding
|
|
1235
|
+
*this* script. Weighed against that: added CI runtime, and the blast
|
|
1236
|
+
radius of any CI job that manipulates real Dolt merge state (mitigated by
|
|
1237
|
+
running entirely in a disposable local temp dir, same isolation principle
|
|
1238
|
+
as Part 6.4, never touching a shared remote).
|
|
1239
|
+
|
|
1240
|
+
**Decision: add that narrower, local-only, live-`dolt` test as a follow-up,
|
|
1241
|
+
filed as apra-fleet-j918.9 (linked from this doc; not implemented by this
|
|
1242
|
+
task).** `scripts/dolt-settle-integration.mjs` remains excluded from CI as
|
|
1243
|
+
Part 6.2/6.6 already state -- this section adds the current-pass
|
|
1244
|
+
justification and the follow-up, it does not change the exclusion itself.
|
|
1245
|
+
No CI configuration is added by this task.
|
|
1246
|
+
|
|
1191
1247
|
---
|
|
1192
1248
|
|
|
1193
1249
|
## Part 7 -- persistent vs. ephemeral `dolt sql-server`, answered precisely
|
|
@@ -1480,3 +1536,228 @@ so the list below reads as history rather than as a pending action:
|
|
|
1480
1536
|
integrity bug (a filed bead reference vanished), but not a sync/conflict
|
|
1481
1537
|
issue and not something settle() affects. Left open, unrelated.
|
|
1482
1538
|
|
|
1539
|
+
## Part 9 -- sync COST: fewer and cheaper syncs per sprint
|
|
1540
|
+
|
|
1541
|
+
Parts 1-8 are about sync CORRECTNESS (what happens when a sync conflicts).
|
|
1542
|
+
This part is about sync COST, from a separate read-only review of where a
|
|
1543
|
+
fleet-sprint actually spends its `bd dolt pull` / `bd dolt push` minutes. The
|
|
1544
|
+
measured shape on the reference machine: about 20 D-pull/D-push pairs per
|
|
1545
|
+
sprint, each bracketed by 1-2 uncached `bd config get sync.remote` probes
|
|
1546
|
+
(0.6s each), against a 548 MB embedded Dolt store whose full open-and-walk
|
|
1547
|
+
cost is paid on every invocation regardless of how little changed.
|
|
1548
|
+
|
|
1549
|
+
Three changes landed in `dolt-sync.mjs` (a fourth, in the supervisor's
|
|
1550
|
+
pre-launch scope guard, is described in `src/supervisor/scope-overlap.mjs`).
|
|
1551
|
+
|
|
1552
|
+
### 9.1 The `sync.remote` probe is memoized per member
|
|
1553
|
+
|
|
1554
|
+
`isMemberSyncRemoteConfigured()` spawned a fresh `bd config get sync.remote
|
|
1555
|
+
--json` on every call -- the D-pull pre-gate, the D-push pre-gate, and
|
|
1556
|
+
`status()` -- which totals roughly 90-160 spawns per sprint for a value that
|
|
1557
|
+
never changes mid-run. A codebase search confirmed no production path in this
|
|
1558
|
+
package writes `sync.remote` during a live sprint; only test fixtures and
|
|
1559
|
+
one-time setup scripts do.
|
|
1560
|
+
|
|
1561
|
+
The result is now cached per member for the process lifetime (one runner
|
|
1562
|
+
process per sprint). Two properties matter:
|
|
1563
|
+
|
|
1564
|
+
- **Only a positively parsed answer is cached.** Every fail-safe path (the
|
|
1565
|
+
command threw, a `failSoft` error result, no output, unparseable output)
|
|
1566
|
+
still reports "configured" and is deliberately NOT cached, so one transient
|
|
1567
|
+
probe failure cannot pin the fail-safe answer for the rest of the run. The
|
|
1568
|
+
fail-CLOSED contract is unchanged.
|
|
1569
|
+
- **Explicit invalidation, not a TTL.** A TTL re-adds spawns for no real
|
|
1570
|
+
safety. Three HARD seams drop the memo, and every one of them drops the 9.3
|
|
1571
|
+
remote-tip fingerprint alongside it (the two are always forgotten
|
|
1572
|
+
together): `noteMemberCommand()`, called from the runner's central
|
|
1573
|
+
`command()` wrapper for any `bd config set` / `bd dolt remote` / `bd init` /
|
|
1574
|
+
`bd bootstrap` the orchestrator issues on that member; the auth self-heal
|
|
1575
|
+
firing inside `runDoltStep`; and `repair()`.
|
|
1576
|
+
- **The per-dispatch seam is SOFT (round 4).** A dispatched agent runs its
|
|
1577
|
+
`bd` commands in its own session on the member, never through the
|
|
1578
|
+
`command()` wrapper, so `noteMemberCommand()` cannot see them; the runner's
|
|
1579
|
+
central `agent()` wrapper calls `noteMemberDispatchCompleted()` the moment
|
|
1580
|
+
any dispatch settles. Round 3 made that an unconditional wipe of both
|
|
1581
|
+
memos. Combined with "a push never mints a fingerprint" (9.3), the
|
|
1582
|
+
fingerprint was then EMPTY at the start of every dispatch bracket -- the
|
|
1583
|
+
module's primary path -- so the primary path paid one `ls-remote` more
|
|
1584
|
+
than before the feature and skipped nothing, and the probe was re-spawned
|
|
1585
|
+
once per dispatch (golden mock-sprint transcript: 1 -> 14). The hazards
|
|
1586
|
+
the wipe guarded were checked against what bd actually does:
|
|
1587
|
+
`bd bootstrap` -- the one self-heal this repo's agent instructions
|
|
1588
|
+
prescribe -- is non-destructive (an existing DB is validated and reported,
|
|
1589
|
+
never replaced) and, where it creates a DB, CLONES it from `sync.remote`,
|
|
1590
|
+
so a surviving fingerprint that still equals the remote tip is still the
|
|
1591
|
+
truth; `bd init` refuses on an existing DB unless forced, and a forced
|
|
1592
|
+
re-init yields an unrelated history that no pull can fast-forward (its next
|
|
1593
|
+
push diverges into the terminals that already forget the tip and settle).
|
|
1594
|
+
The one event a surviving fingerprint would get WRONG is an agent-side
|
|
1595
|
+
`bd config set sync.remote <other>`. So the seam now MARKS the member as
|
|
1596
|
+
dispatched-since-verified and drops nothing; the fingerprint is bound to
|
|
1597
|
+
the URL it was minted against; and a marked member's `sync.remote` is
|
|
1598
|
+
re-read (one `bd config get`, a plain config.yaml read, no Dolt engine)
|
|
1599
|
+
only at the one decision a stale memo could turn into stale data -- the
|
|
1600
|
+
moment a D-pull is about to be SKIPPED on that fingerprint. Same URL:
|
|
1601
|
+
skip. Different or unreadable: fingerprint forgotten, real pull. Every
|
|
1602
|
+
other consumer of the memo fails closed anyway (a wrong "configured"
|
|
1603
|
+
answer just issues a real pull/push against whatever remote bd itself has
|
|
1604
|
+
configured). The re-read is therefore paid once per skip-after-dispatch,
|
|
1605
|
+
never per dispatch; a bracket whose tip moved pays nothing extra; a
|
|
1606
|
+
member with a remote is back to one probe per process. The one case that
|
|
1607
|
+
never reaches that check is a member memoized as having NO remote (both
|
|
1608
|
+
pre-gates exit on it first): its memo is re-read once after any dispatch,
|
|
1609
|
+
because an agent wiring a remote mid-dispatch would otherwise leave every
|
|
1610
|
+
later D-push of that member reporting a benign no-remote skip -- success
|
|
1611
|
+
-- while its bead closes never left the clone. That costs one config.yaml
|
|
1612
|
+
read per dispatch for no-remote members only (sandboxes; the no-remote
|
|
1613
|
+
mock sprint's golden transcript shows one probe per dispatch for exactly
|
|
1614
|
+
this reason).
|
|
1615
|
+
- **The probe never waits on a prompt, and switches itself off when it
|
|
1616
|
+
cannot work.** The probe URL carries no userinfo (9.3), so a member whose
|
|
1617
|
+
only credential for the host was URL-embedded would have git try to
|
|
1618
|
+
PROMPT -- under Git Credential Manager on Windows, a dialog that blocks
|
|
1619
|
+
until the 30s probe timeout, on every bracket. The probe runs with
|
|
1620
|
+
`-c credential.interactive=never -c core.askPass=` (config flags, never a
|
|
1621
|
+
shell env prefix -- the member's shell may be PowerShell) so it fails at
|
|
1622
|
+
once, and after two consecutive failed probes the member's probe is
|
|
1623
|
+
disabled for the process (re-armed by the hard seams), so every pull is
|
|
1624
|
+
simply real again. Two rather than one so a single blip does not cost the
|
|
1625
|
+
feature.
|
|
1626
|
+
|
|
1627
|
+
### 9.2 The transient retry ladder is time-boxed, not count-boxed
|
|
1628
|
+
|
|
1629
|
+
The ladder was widened to 8 retries with a 30s backoff cap to survive a live
|
|
1630
|
+
Windows machine-wide `git.exe` spawn outage (`fork/exec ... "Not enough memory
|
|
1631
|
+
resources"`), measured at 1-3 minutes. That was the right diagnosis but the
|
|
1632
|
+
wrong bound: it applied the long budget to EVERY transient kind, and the unit
|
|
1633
|
+
suite went from 80s to 6m15s because ordinary transients in fixtures now
|
|
1634
|
+
walked the full ladder (91.5s of pure sleep in one exhausted ladder, before
|
|
1635
|
+
counting the 600s per-attempt timeout).
|
|
1636
|
+
|
|
1637
|
+
The budget was never really about a count -- it was about spanning a
|
|
1638
|
+
wall-clock outage window. So the ladder is split by error class:
|
|
1639
|
+
|
|
1640
|
+
| class | bound | backoff cap |
|
|
1641
|
+
|---|---|---|
|
|
1642
|
+
| spawn outage (`fork/exec`, "Not enough memory resources") | 3 min WALL CLOCK | 30s |
|
|
1643
|
+
| every other transient | 5 retries (`maxTransientRetries`) | 8s |
|
|
1644
|
+
|
|
1645
|
+
A wall-clock bound is the same 3 minutes whether each attempt returns
|
|
1646
|
+
instantly or sits on the 600s step timeout; the old count-based bound
|
|
1647
|
+
multiplied out to a worst case of 9 attempts x 600s. The generic default is
|
|
1648
|
+
the pre-widening 5 (a first cut mis-restored it as 2; corrected). An
|
|
1649
|
+
explicitly passed `maxTransientRetries` is honored by BOTH ladders: it bounds
|
|
1650
|
+
the generic class as before, and it is a hard attempt cap on the spawn-outage
|
|
1651
|
+
ladder too (the wall-clock budget still applies underneath it). Left unset --
|
|
1652
|
+
the production shape, since no runner call site passes one -- the spawn-outage
|
|
1653
|
+
class keeps its full wall-clock budget. A `diverged` classification is still
|
|
1654
|
+
never retried, under either ladder. The spawn-outage sub-classifier matches
|
|
1655
|
+
only the `fork/exec` line: the "Not enough memory resources" wording on its
|
|
1656
|
+
own never classifies `transient` in the first place (it is not in the dolt
|
|
1657
|
+
provider's TRANSIENT table), so a pattern for it was dead and was removed.
|
|
1658
|
+
|
|
1659
|
+
### 9.3 Remote-tip fingerprint: skip a D-pull only when it is provably a no-op
|
|
1660
|
+
|
|
1661
|
+
**The correctness anchor.** The shared remote's `refs/dolt/data` is the ONLY
|
|
1662
|
+
channel through which beads state moves between machines. A member's clone can
|
|
1663
|
+
therefore be stale in exactly one way: that ref advanced since the member last
|
|
1664
|
+
pulled or pushed. "Is a D-pull needed?" then has a cheap, EXACT answer --
|
|
1665
|
+
compare the remote SHA now against the SHA this member last synchronized to --
|
|
1666
|
+
rather than a policy bet about who else might be writing.
|
|
1667
|
+
|
|
1668
|
+
This is why the alternatives were rejected. "Skip for read-only roles" and
|
|
1669
|
+
"skip within N seconds of the last pull" both trade real staleness for speed:
|
|
1670
|
+
a reviewer reads acceptance criteria a remote doer just pushed, and a
|
|
1671
|
+
plan-reviewer reads the planner's freshly pushed DAG. Any fixed bound is a
|
|
1672
|
+
guess about other writers, and a wrong guess produces exactly the
|
|
1673
|
+
false-FAILED-streak failure the post-streak verify pull exists to prevent. A
|
|
1674
|
+
tip-equal skip removes only pulls that are provably no-ops, so no operator has
|
|
1675
|
+
to pick a risk bound at all.
|
|
1676
|
+
|
|
1677
|
+
**Mechanism.** Before a real `bd dolt pull`, one `git ls-remote <sync.remote>
|
|
1678
|
+
refs/dolt/data` -- one network round trip, no Dolt engine startup, no 548 MB
|
|
1679
|
+
chunk store to open (0.35s measured, against multi-minute real pulls). On a
|
|
1680
|
+
match the pull is not spawned and the step returns `{ ok: true, member,
|
|
1681
|
+
skipped: true, reason: 'remote-unchanged', remoteTip }`.
|
|
1682
|
+
|
|
1683
|
+
**The recorded tip is minted in exactly one place, from a value the clone is
|
|
1684
|
+
provably current with:**
|
|
1685
|
+
|
|
1686
|
+
- after a successful PULL, record the SHA observed IMMEDIATELY BEFORE it --
|
|
1687
|
+
never one read afterwards. A push racing in during the pull is not in what
|
|
1688
|
+
was fetched, so recording the later SHA would claim freshness the clone does
|
|
1689
|
+
not have. Recording the earlier one can only cost one redundant future pull.
|
|
1690
|
+
- after a successful PUSH by this member, FORGET the recorded tip. A push never
|
|
1691
|
+
records anything.
|
|
1692
|
+
|
|
1693
|
+
**Why a push cannot mint a fingerprint.** Two earlier cuts recorded a SHA read
|
|
1694
|
+
from the remote after the push -- unconditionally at first, then only when the
|
|
1695
|
+
ref had "advanced" past a pre-push read. Both lose the same race: the push
|
|
1696
|
+
mutex serializes this fleet's pushes against each other and nothing else, so
|
|
1697
|
+
an unrelated machine can push in the gap between our push landing and our
|
|
1698
|
+
post-push `ls-remote` returning. That read then observes a stranger's commit
|
|
1699
|
+
this clone has never seen, records it as ours, and the next D-pull is wrongly
|
|
1700
|
+
skipped -- exactly the staleness the feature exists to prevent. A network read
|
|
1701
|
+
of "the remote's current tip" is never a proxy for "what my push published".
|
|
1702
|
+
Nor is there a local proxy for this transport: bd's git-backed remote is Dolt's
|
|
1703
|
+
git blobstore, where a push wraps the chunk-store manifest in a fresh git
|
|
1704
|
+
commit built inside the push on top of the remote head it just fetched. That
|
|
1705
|
+
commit -- the remote's new `refs/dolt/data` -- is not a function of local Dolt
|
|
1706
|
+
state, is not printed by `bd dolt push`, and lands locally only in a
|
|
1707
|
+
per-process UUID-named ref (`refs/dolt/blobstore/<remote>/dolt/data/<uuid>`)
|
|
1708
|
+
inside a sha256-named cache dir under `.beads/`, reachable only by a
|
|
1709
|
+
shell-dialect-specific scan of the member's disk (verified against a live
|
|
1710
|
+
clone: the cache repo's tracking refs and `FETCH_HEAD` already disagreed with
|
|
1711
|
+
the remote's live tip). So the pusher forgets its tip and pays one real pull
|
|
1712
|
+
at its next bracket, after which the skip is re-armed. A no-op push is treated
|
|
1713
|
+
identically -- it proves nothing about the clone's freshness. As a side
|
|
1714
|
+
effect no `ls-remote` is issued anywhere in the D-push bracket: the mutex hold
|
|
1715
|
+
is exactly push + reconcile + settle.
|
|
1716
|
+
|
|
1717
|
+
**Fail-open, always.** Every uncertainty falls through to a REAL pull: no
|
|
1718
|
+
recorded tip yet, an `ls-remote` failure or timeout, unparseable output, a
|
|
1719
|
+
`sync.remote` that could not be positively read, or a URL that fails the
|
|
1720
|
+
strict safe-charset gate. A divergence, a settle, a successful push, an auth
|
|
1721
|
+
self-heal, a `repair()`, an orchestrator-issued `bd init`/`bootstrap`/`config
|
|
1722
|
+
set`, and a `sync.remote` found changed under a dispatch (9.1) all FORGET the
|
|
1723
|
+
recorded tip rather than leave a stale one. The recorded tip is bound to the
|
|
1724
|
+
URL it was observed at and never validates a probe of any other URL. There
|
|
1725
|
+
is deliberately no path in which doubt produces a skip.
|
|
1726
|
+
|
|
1727
|
+
**Three implementation constraints worth restating:**
|
|
1728
|
+
|
|
1729
|
+
- The probe target is resolved from `sync.remote` (through the 9.1 memo, so it
|
|
1730
|
+
costs no extra `bd config get`), NEVER from git's `origin`. The two can
|
|
1731
|
+
legitimately differ on a member, and probing `origin` would compare this
|
|
1732
|
+
member's freshness against the wrong ref. bd spells a git-transport remote
|
|
1733
|
+
`git+https://...`; the `git+` prefix is bd's own scheme marker and is
|
|
1734
|
+
stripped before `ls-remote`. A `sync.remote` with NO scheme -- a bare Dolt
|
|
1735
|
+
remote NAME (`origin`, which the integration fixtures legitimately set) or
|
|
1736
|
+
a bare path (a Dolt file remote, never a git repository) -- yields no probe
|
|
1737
|
+
at all, because `git ls-remote origin` would silently resolve against
|
|
1738
|
+
git's origin, the exact target this rule forbids.
|
|
1739
|
+
- The probe command string is journaled VERBATIM into the persisted,
|
|
1740
|
+
dashboard-visible run transcript (`silent` only suppresses the console
|
|
1741
|
+
line). An http(s) userinfo (`user:token@`) in `sync.remote` is therefore
|
|
1742
|
+
stripped before the URL is interpolated into the command; previously such
|
|
1743
|
+
a token only ever appeared as command OUTPUT (`bd config get`). The
|
|
1744
|
+
stripped URL still authenticates through the git credential helper every
|
|
1745
|
+
provisioned member carries (that is how `git push` works on members); a
|
|
1746
|
+
member whose only credential was URL-embedded gets a failed probe, which is
|
|
1747
|
+
a real pull. ssh URLs keep their `git@` -- a login name, not a secret.
|
|
1748
|
+
- The probe string reaches the member's own shell, which may be PowerShell or
|
|
1749
|
+
a POSIX shell. Rather than trying to quote correctly for both, any remote URL
|
|
1750
|
+
containing a character outside a conservative safe charset (no whitespace,
|
|
1751
|
+
no quote, no metacharacter of either dialect) is REFUSED -- which yields no
|
|
1752
|
+
fingerprint and a real pull, the safe direction.
|
|
1753
|
+
|
|
1754
|
+
Disable per call site with `remoteTipFingerprint: false`.
|
|
1755
|
+
|
|
1756
|
+
### 9.4 Not done here, on purpose
|
|
1757
|
+
|
|
1758
|
+
Two larger items from the same review are deliberately out of scope: squashing
|
|
1759
|
+
the Dolt history and re-bootstrapping every member clone (the largest per-op
|
|
1760
|
+
win, but a destructive operational change needing a quiescent window and its
|
|
1761
|
+
own runbook), and moving `sync.remote` off the git transport onto a native
|
|
1762
|
+
Dolt bucket remote.
|
|
1763
|
+
|
|
@@ -7,8 +7,8 @@ Status: design -- not yet implemented. Last updated: 2026-08-10.
|
|
|
7
7
|
auto-repair, then resume) or a cleanly dead one (abort with a diagnosis report and, where needed,
|
|
8
8
|
a specific human referral) -- never leave it wedged, silently burning tokens, or ambiguous.
|
|
9
9
|
|
|
10
|
-
> **Supersedes
|
|
11
|
-
> resolution"
|
|
10
|
+
> **Supersedes the earlier "coach role" design note** ("coach role: just-in-time error
|
|
11
|
+
> resolution"), which this doc replaces in full. sprint-doctor is the same core idea --
|
|
12
12
|
> an in-workflow LLM layer for failures the deterministic engine did not foresee, positioned
|
|
13
13
|
> strictly AFTER typed handlers/ladders, failing loudly when it cannot fix -- carried further.
|
|
14
14
|
> Ideas incorporated directly from coach, credited inline where they appear: the three-layer
|
|
@@ -703,7 +703,7 @@ ENGINE's maintainers without silent uploads -- and its flow is adopted whole:
|
|
|
703
703
|
|
|
704
704
|
- **Sanitize FIRST, locally, always** -- before the report is even written to disk: absolute
|
|
705
705
|
paths -> stable placeholders (`<work-folder>/...`, `<home>/...`); hostnames/usernames/IPs/
|
|
706
|
-
emails -> redacted tokens; anything matching secret patterns (keys, tokens, `{{
|
|
706
|
+
emails -> redacted tokens; anything matching secret patterns (keys, tokens, `{{secret.*}}`
|
|
707
707
|
values, env dumps) -> stripped outright, never placeholdered; target-repo identifiers (repo
|
|
708
708
|
name, branch names, bead titles) -> anonymized to `<target-repo>`/`<sprint-branch>` by
|
|
709
709
|
default, with an opt-in tier for internal users to keep them; code snippets excluded by
|
|
@@ -0,0 +1,215 @@
|
|
|
1
|
+
# Decision: runSprintCycle's closure prelude stays; the "~700-line runner.js" target is restated
|
|
2
|
+
|
|
3
|
+
Status: DECIDED. **Option (1) -- KEEP the prelude as composition-root wiring, and
|
|
4
|
+
restate the epic's roughly 700-line aspiration for `runner.js`.**
|
|
5
|
+
|
|
6
|
+
This note records a decision only. **No code was moved, no module was created or
|
|
7
|
+
deleted, and no behaviour changed by the task that wrote it.** If a later change
|
|
8
|
+
makes the reasoning below false, reopen the question (see "What would reopen
|
|
9
|
+
this") rather than quietly extracting.
|
|
10
|
+
|
|
11
|
+
Scope of the question: `runSprintCycle()` in
|
|
12
|
+
`packages/apra-fleet-se/fleet-sprint/runner.js` is a closure. Everything declared
|
|
13
|
+
inside it captures the per-cycle context, so slicing it is not the move-only
|
|
14
|
+
mechanical operation the twelve `phases/*` extractions were -- it is a design
|
|
15
|
+
change about what the per-cycle context IS and who owns it. The prelude here
|
|
16
|
+
means everything from the `runSprintCycle` function header down to the FIRST
|
|
17
|
+
phase invocation (the `runEnsureSprintBranchPhase` call).
|
|
18
|
+
|
|
19
|
+
## How the figures below were measured
|
|
20
|
+
|
|
21
|
+
Anchored by symbol, never by line number: the script locates the header, the
|
|
22
|
+
closing brace and the first `run*Phase(` call itself. Run from
|
|
23
|
+
`packages/apra-fleet-se`:
|
|
24
|
+
|
|
25
|
+
```sh
|
|
26
|
+
F=fleet-sprint/runner.js
|
|
27
|
+
S=$(grep -n '^async function runSprintCycle' $F | cut -d: -f1)
|
|
28
|
+
E=$(awk -v s="$S" 'NR>s && /^}/ {print NR; exit}' $F)
|
|
29
|
+
P=$(awk -v s="$S" -v e="$E" 'NR>s && NR<e && /await run[A-Za-z]*Phase\(/ {print NR; exit}' $F)
|
|
30
|
+
body() { sed -n "$1,$2p" $F; }
|
|
31
|
+
|
|
32
|
+
echo "runSprintCycle total=$(body $S $E | wc -l)"
|
|
33
|
+
echo "prelude total=$(body $S $((P-1)) | wc -l)" \
|
|
34
|
+
"comment=$(body $S $((P-1)) | grep -cE '^\s*(//|/\*|\*)')" \
|
|
35
|
+
"blank=$(body $S $((P-1)) | grep -cE '^\s*$')"
|
|
36
|
+
echo "runner.js total=$(wc -l < $F) comment=$(grep -cE '^\s*(//|/\*|\*)' $F)" \
|
|
37
|
+
"imports=$(grep -cE '^import ' $F) exports=$(grep -cE '^export ' $F)"
|
|
38
|
+
|
|
39
|
+
# named inner closures of runSprintCycle
|
|
40
|
+
body $S $E | grep -nE '^ (async )?function [A-Za-z_$]+|^ const [A-Za-z_$]+ = (async )?\(|^ const dispatchCtx = \{' \
|
|
41
|
+
| awk -F: -v s="$S" '{print " line "($1+s-1)": "$2}'
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
## The measurement (observations at the HEAD this note was written against)
|
|
45
|
+
|
|
46
|
+
These are observations of one tree, not targets and not literals to assert
|
|
47
|
+
against. Re-run the script above before relying on any of them.
|
|
48
|
+
|
|
49
|
+
```
|
|
50
|
+
runSprintCycle 769..2934 total=2166
|
|
51
|
+
first phase invocation at 1780: await runEnsureSprintBranchPhase({
|
|
52
|
+
prelude 769..1779 total=1011 comment=630 blank=41
|
|
53
|
+
runner.js total=3097 comment=1862 imports=49 exports=28
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
Derived: the prelude is 1011 lines of which **630 are comment lines and 41 are
|
|
57
|
+
blank, leaving roughly 340 lines that are actually code**. Across the whole file,
|
|
58
|
+
1862 of 3097 lines are comments -- `runner.js` is about 60% prose. The part of
|
|
59
|
+
`runSprintCycle` after the first phase invocation is 1155 lines, of which 605 are
|
|
60
|
+
comments and 72 blank, leaving roughly 478 code lines. `main()` is 142 lines.
|
|
61
|
+
|
|
62
|
+
### The named inner closures
|
|
63
|
+
|
|
64
|
+
Sizes are the declaration's own span. "Captures mutable" lists which of
|
|
65
|
+
`runSprintCycle`'s fourteen `let` bindings the body references -- the property
|
|
66
|
+
that decides whether a helper can be lifted at all.
|
|
67
|
+
|
|
68
|
+
| Closure | Lines | Captures per-cycle MUTABLE state | Cycle-scope bindings captured |
|
|
69
|
+
|---|---|---|---|
|
|
70
|
+
| `agent` | 12 | none | dispatch wrapper over `context.agent` |
|
|
71
|
+
| `unmappedRoleFallbackPool` | 12 | none | few |
|
|
72
|
+
| `getMemberForRole` | 6 | none | few |
|
|
73
|
+
| `getMembersForRole` | 12 | none | few |
|
|
74
|
+
| `withGitSync` | 1 | none | alias onto `gitSync.withGitSync` |
|
|
75
|
+
| `dispatchCtx` (dispatchRole engine context) | 112 | none | 15 |
|
|
76
|
+
| `decomposedParentIds` | 4 | none | 1 (`bdListScoped`) |
|
|
77
|
+
| `readyLeafBeads` | 7 | none | 1 (`bdListScoped`) |
|
|
78
|
+
| `reclaimStaleInProgress` | 32 | `sprintLaunchTime` | 6 |
|
|
79
|
+
| `dispatchReview` | 109 | `cycle` | 8 |
|
|
80
|
+
| `reEnsureBranchOnMembers` | 13 | none | 3 |
|
|
81
|
+
| `updateDashboard` | 63 | none | 5 |
|
|
82
|
+
| `probeFileExists` | 11 | none | 3 |
|
|
83
|
+
| `recordReopen` | 3 | none | `reopenCounts` |
|
|
84
|
+
| `thrashingBeadIds` | 5 | none | `reopenCounts` |
|
|
85
|
+
|
|
86
|
+
Summed declaration bodies: **401 lines**; including each one's leading doc
|
|
87
|
+
comment block (which would move with it): **537 lines**.
|
|
88
|
+
|
|
89
|
+
## The decision, and the arithmetic that forces it
|
|
90
|
+
|
|
91
|
+
**Extracting the prelude cannot deliver the stated goal, so it is not worth its
|
|
92
|
+
cost.** If every one of the fourteen closures above were extracted -- the
|
|
93
|
+
maximal, most aggressive version of option (2) -- `runner.js` would fall from
|
|
94
|
+
3097 lines to roughly **2560**. That is still about 3.6x the roughly 700-line
|
|
95
|
+
aspiration, and it is an *over*-estimate of the saving: each extracted helper
|
|
96
|
+
must be re-injected at its call sites, which adds lines back. No amount of
|
|
97
|
+
prelude extraction reaches ~700. The target was never going to be met this way,
|
|
98
|
+
so choosing between "extract" and "keep" on the basis of that number is choosing
|
|
99
|
+
between two ways of missing it.
|
|
100
|
+
|
|
101
|
+
### Why the prelude is composition-root wiring rather than implementation
|
|
102
|
+
|
|
103
|
+
The concrete, checkable property: **essentially every code-bearing statement in
|
|
104
|
+
the prelude either resolves an injectable seam or constructs a collaborator, and
|
|
105
|
+
almost none of them compute anything about the sprint.** The dominant shapes are
|
|
106
|
+
|
|
107
|
+
```js
|
|
108
|
+
const X = context.X ?? createX({ ...wiring }); // injectable seam with a default
|
|
109
|
+
const { a, b, c } = createY({ ...wiring }); // collaborator construction
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
covering `createSyncBrackets`, `createBeadsScope`, `createSprintState`,
|
|
113
|
+
`createMemberSessionGuard`, `createRoundSessionRegistry`, `createKbPrimingClient`,
|
|
114
|
+
`createKbWorkClient`, `createGitSync`, the dolt-push mutex, the child-id
|
|
115
|
+
allocator, and the `dispatchCtx` engine context. That is the definition of a
|
|
116
|
+
composition root: the one place that knows how the object graph is assembled and
|
|
117
|
+
is therefore allowed to depend on everything. Pushing it into a "context module"
|
|
118
|
+
does not remove the wiring, it renames its file -- and it breaks the one property
|
|
119
|
+
a composition root exists to provide, that there is exactly ONE place to look to
|
|
120
|
+
see how a sprint is assembled.
|
|
121
|
+
|
|
122
|
+
The second property: **the prelude is mostly prose.** 630 of its 1011 lines are
|
|
123
|
+
comments, and they are not decoration -- they record why each seam has the
|
|
124
|
+
precedence order it has (the four-source ladders for the push mutex and the id
|
|
125
|
+
allocator), why the `agent` wrapper is the single place `sprint_id` and the
|
|
126
|
+
knowledge-bank block are attached, and why the pause guard is registered before
|
|
127
|
+
any dispatch can occur. A line count that treats those lines as debt is measuring
|
|
128
|
+
the wrong thing; deleting them to hit a number would be a strict loss.
|
|
129
|
+
|
|
130
|
+
### Why option (2) -- a per-cycle context module -- is rejected
|
|
131
|
+
|
|
132
|
+
Beyond the arithmetic above: it trades closure capture for parameter passing at
|
|
133
|
+
a bad exchange rate. `dispatchCtx` alone captures 15 cycle-scope bindings and
|
|
134
|
+
`dispatchReview` captures 8. Converting those to explicit parameters widens every
|
|
135
|
+
signature and every call site, and the resulting module would still have to be
|
|
136
|
+
constructed from the same wiring, in the same place, in the same order. The
|
|
137
|
+
`phases/*` slices were worth their widened signatures because each one removed a
|
|
138
|
+
self-contained *phase body* -- a unit with a name in the sprint's vocabulary. A
|
|
139
|
+
"per-cycle context" module is not such a unit; it is the composition root with an
|
|
140
|
+
extra import hop.
|
|
141
|
+
|
|
142
|
+
### Why option (3) -- extract only the non-capturing subset -- is rejected
|
|
143
|
+
|
|
144
|
+
The measurement makes option (3) look more attractive than it is: only two of the
|
|
145
|
+
fourteen closures capture mutable state (`reclaimStaleInProgress` ->
|
|
146
|
+
`sprintLaunchTime`, `dispatchReview` -> `cycle`), so a naive reading says the
|
|
147
|
+
other twelve are liftable. But mutable capture is not the real cost -- immutable
|
|
148
|
+
capture is. The twelve non-mutating closures still capture between 1 and 15
|
|
149
|
+
cycle-scope bindings each, and the two largest (`dispatchCtx` at 112 lines,
|
|
150
|
+
`updateDashboard` at 63) are among the heaviest capturers. What is left after
|
|
151
|
+
excluding them is genuinely tiny: `decomposedParentIds` (4 lines),
|
|
152
|
+
`readyLeafBeads` (7), `recordReopen` (3), `thrashingBeadIds` (5),
|
|
153
|
+
`getMemberForRole` (6) -- roughly 25 lines of body. Creating a module to hold
|
|
154
|
+
25 lines of one-liners, each of which then needs to be threaded back in, makes
|
|
155
|
+
the codebase harder to read to save nothing. Option (3) is a real option; it is
|
|
156
|
+
rejected on measured size, not on principle.
|
|
157
|
+
|
|
158
|
+
`dispatchReview` deserves a specific note because it is the largest genuinely
|
|
159
|
+
shared helper. It is injected into `phases/review.mjs` and `phases/re-review.mjs`
|
|
160
|
+
(both name it in their "WHY SOME HELPERS ARE INJECTED RATHER THAN IMPORTED"
|
|
161
|
+
headers). Being shared by two phases is exactly why it sits at cycle scope rather
|
|
162
|
+
than in either phase module, and it captures `cycle`, so it is the single worst
|
|
163
|
+
candidate for a mechanical lift.
|
|
164
|
+
|
|
165
|
+
## The roughly 700-line target is restated
|
|
166
|
+
|
|
167
|
+
The `~700-line` figure originated in the Phase 0 epic description, derived
|
|
168
|
+
against a tree where `phases/*` did not exist and `runner.js` was 11,678 lines.
|
|
169
|
+
It was an aspiration attached to an estimate, never a computed budget, and the
|
|
170
|
+
work since has shown it is unreachable: the composition root plus the facade plus
|
|
171
|
+
their documentation costs more than 700 lines on their own, and the floor
|
|
172
|
+
computed above puts even a maximal extraction at roughly 2560.
|
|
173
|
+
|
|
174
|
+
**Stop quoting ~700.** It is replaced by two properties that are already
|
|
175
|
+
mechanically enforced, and which say what the refactor was actually for:
|
|
176
|
+
|
|
177
|
+
1. **`runner.js` hosts no phase body.** Pinned by
|
|
178
|
+
`test/phase-sequence-order.test.mjs`, which asserts a zero-match shape scan
|
|
179
|
+
over `runner.js` with a `>= 12` count across `phases/*` as its non-vacuity
|
|
180
|
+
control.
|
|
181
|
+
2. **`runner.js` is a complete facade.** Every previously-exported symbol is
|
|
182
|
+
still importable from it, so no importer or mock-sprint file changes.
|
|
183
|
+
|
|
184
|
+
Size becomes an *observation* reported alongside those gates, not a gate itself.
|
|
185
|
+
For context, `runner.js` at 3097 lines is not an outlier in its own package:
|
|
186
|
+
`dolt-sync.mjs` is 2325, and `dolt-settle.mjs`, `role-policies.mjs`,
|
|
187
|
+
`contracts.mjs`, `dispatch-role.mjs` and `vcs-auth.mjs` are all around 1000+.
|
|
188
|
+
|
|
189
|
+
## What would reopen this
|
|
190
|
+
|
|
191
|
+
Any one of these makes the reasoning above false and the question worth asking
|
|
192
|
+
again:
|
|
193
|
+
|
|
194
|
+
- A **third** consumer appears for `dispatchReview`, or `dispatchReview` stops
|
|
195
|
+
capturing `cycle`. It would then be a shared service rather than cycle-scoped
|
|
196
|
+
glue, and `phases/`-adjacent placement becomes defensible.
|
|
197
|
+
- The prelude starts doing **sprint computation** rather than wiring -- i.e. new
|
|
198
|
+
statements that are not `context.X ?? createX(...)`-shaped and that derive
|
|
199
|
+
decisions about beads, members or scheduling. That is implementation, and it
|
|
200
|
+
belongs in a module.
|
|
201
|
+
- `updateDashboard` or `probeFileExists` grows materially, or acquires a second
|
|
202
|
+
caller outside `runSprintCycle`.
|
|
203
|
+
- The comment-to-code ratio inverts: if the prelude's code lines exceed its
|
|
204
|
+
comment lines, the "it is mostly prose" argument no longer holds and the raw
|
|
205
|
+
code size should be re-weighed.
|
|
206
|
+
|
|
207
|
+
## Correction to an inherited claim
|
|
208
|
+
|
|
209
|
+
The planning note for this decision stated that "Review, Re-Review and Final
|
|
210
|
+
Review all share `dispatchReview`". **That is not true at this HEAD.** Only
|
|
211
|
+
`phases/review.mjs` and `phases/re-review.mjs` receive it;
|
|
212
|
+
`phases/final-review.mjs` merely cites it in a comment ("No duplicate log() dump
|
|
213
|
+
-- see dispatchReview() for why") and runs its own dispatch. The conclusion is
|
|
214
|
+
unaffected -- two sharers is still more than one, which is still the reason the
|
|
215
|
+
helper is cycle-scoped -- but the count is two, not three.
|
|
@@ -6,19 +6,19 @@ Source doc path: `packages/apra-fleet-se/fleet-sprint/docs/shared-orchestrator-r
|
|
|
6
6
|
|
|
7
7
|
## Problem recap
|
|
8
8
|
|
|
9
|
-
Every fleet-sprint launch resolves an `orchestrator` pseudo-role
|
|
10
|
-
`ROLE_ORCHESTRATOR
|
|
9
|
+
Every fleet-sprint launch resolves an `orchestrator` pseudo-role
|
|
10
|
+
(`ROLE_ORCHESTRATOR` / `getMemberForRole(ROLE_ORCHESTRATOR)` in `runner.js`)
|
|
11
11
|
whose beads clone is the sprint's ground truth for all scope reads and bd mutations. Absent an
|
|
12
12
|
explicit `--role-map '{"orchestrator":[...]}'`, this silently defaults to
|
|
13
|
-
`unmappedRoleFallbackPool[0]`
|
|
13
|
+
`unmappedRoleFallbackPool[0]` -- for a single-member sprint, the dispatch
|
|
14
14
|
member itself. Two production incidents followed: beads created on the interactive operator
|
|
15
15
|
machine's clone were invisible to sprints whose accidental orchestrator was a different,
|
|
16
16
|
never-synced member.
|
|
17
17
|
|
|
18
18
|
The naive fix (role-map a hub member as orchestrator on every launch) deadlocks concurrency:
|
|
19
19
|
the launch overlap guard unions `--members` with every roleMap value INCLUDING orchestrator
|
|
20
|
-
(
|
|
21
|
-
every second concurrent launch
|
|
20
|
+
(`memberUnion` in `src/supervisor/api.mjs`), so a shared orchestrator member would 409
|
|
21
|
+
every second concurrent launch. The operator's proposal: the supervisor holds
|
|
22
22
|
a standing, shared, orchestrator-role-only reservation on one designated member and injects it
|
|
23
23
|
as the default orchestrator into every launch.
|
|
24
24
|
|
|
@@ -116,8 +116,8 @@ exclusivity was never what protected orchestrator-role dolt writes; the mutex wa
|
|
|
116
116
|
|
|
117
117
|
- **Supervisor ledger** (src/supervisor/ledger.mjs): per-sprint entries
|
|
118
118
|
`{ members, issueRoots, childPid, reservedAt, branch, base, goal, exit*, logPath }`
|
|
119
|
-
|
|
120
|
-
(
|
|
119
|
+
-- claimed and released in exact lockstep with the sprint lifecycle
|
|
120
|
+
(`claim()`/`release()` in `ledger.mjs`), atomically persisted, PID-probe
|
|
121
121
|
reconciled on restart. Everything about it is sprint-lifecycle-scoped.
|
|
122
122
|
- **Launch overlap guard** (api.mjs:162-209): all-or-nothing 409 on any member of the incoming
|
|
123
123
|
union (members + every roleMap value, orchestrator included) overlapping any live ledger
|
|
@@ -138,7 +138,7 @@ exclusivity was never what protected orchestrator-role dolt writes; the mutex wa
|
|
|
138
138
|
|
|
139
139
|
### A4. Interaction with in-flight work (pause/resume `apra-fleet-p2to`, sprint-doctor `apra-fleet-iiny`)
|
|
140
140
|
|
|
141
|
-
Pause/resume's reservation logic (escalate-to-llm-design.md
|
|
141
|
+
Pause/resume's reservation logic (escalate-to-llm-design.md) releases each member via
|
|
142
142
|
owner-checked `member_reservation release` on pause and re-reserves on resume, failing resume
|
|
143
143
|
cleanly when a member was taken. This operates on the sprint's OWN per-sprint reservation set.
|
|
144
144
|
Under this design the pinned member is deliberately NOT in that set (D1), so pause/resume never
|
|
@@ -149,7 +149,7 @@ points**:
|
|
|
149
149
|
|
|
150
150
|
1. **Sprint-doctor's wedged-reservation remedy is NOT orthogonal.** The doctor's remedy table
|
|
151
151
|
allows `member_reservation force_release` when a member is "reserved by a sprint id whose
|
|
152
|
-
pid/ledger entry is dead" (escalate-to-llm-design.md
|
|
152
|
+
pid/ledger entry is dead" (escalate-to-llm-design.md). The pin sentinel has no pid and
|
|
153
153
|
no ledger entry -- to that heuristic it looks exactly like a wedged dead reservation, and a
|
|
154
154
|
doctor run would strip the pin. The doctor rule must learn: a reservation whose owner
|
|
155
155
|
matches the supervisor pin sentinel prefix is never force-releasable (and the supervisor
|
|
@@ -204,9 +204,9 @@ After D0, the orchestrator's entire command surface is `bd`/`bd dolt` via execut
|
|
|
204
204
|
|
|
205
205
|
**Why not a shared/`exclusive:false` reservation TYPE in the ledger:** every ledger invariant
|
|
206
206
|
is sprint-lifecycle-shaped -- claim/release in lockstep with one sprint's launch/terminal
|
|
207
|
-
events
|
|
207
|
+
events, a `childPid` for restart PID-probe reconciliation,
|
|
208
208
|
release driven by watchdog/reconcile/Stop (`POST /api/reservations/:sprintId/force-release`,
|
|
209
|
-
dashboard.mjs
|
|
209
|
+
`src/supervisor/dashboard.mjs`, per escalate-to-llm-design.md). A permanent, sprint-less, shared
|
|
210
210
|
entry violates all of it: it has no pid to probe, must survive every reconciliation pass, must
|
|
211
211
|
be skipped by the overlap guard, and must never be force-released by the Stop path. That is
|
|
212
212
|
not a reservation with a flag -- it is a different object with a different lifecycle, and
|
|
@@ -286,7 +286,7 @@ is a documented follow-up, not a blocker.
|
|
|
286
286
|
(`FLEET_SE_DATA_DIR`, default `~/.apra-fleet-se`, ledger.mjs:177-181), e.g.
|
|
287
287
|
`supervisor-config.json`: `{ "pinnedRoles": { "orchestrator": ["memberA", "memberB"] } }`.
|
|
288
288
|
Generic shape (role -> ordered member list); only `orchestrator` is honored initially.
|
|
289
|
-
- **Flag**: `fleet-se
|
|
289
|
+
- **Flag**: `fleet-se-serve --pin-orchestrator <member[,member...]>` overriding the file
|
|
290
290
|
(serve.mjs currently takes only `--port`, serve.mjs:52-62 -- room to grow).
|
|
291
291
|
- **API**: `GET /api/config/pinned-roles` (consumed by dashboard, launch form, and the CLI
|
|
292
292
|
follow-up) and `PUT` for runtime changes (re-runs sentinel reserve/release accordingly).
|
|
@@ -1,9 +1,19 @@
|
|
|
1
1
|
# Auto-Sprint Stabilization Log
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
3
|
+
A closed historical log from the stabilization push that first drove
|
|
4
|
+
fleet-sprint against a real sprint end to end. Each numbered entry records
|
|
5
|
+
one defect as symptom -> root cause -> fix -> evidence, and most carry a
|
|
6
|
+
**Lesson** paragraph -- that is the durable part.
|
|
7
|
+
|
|
8
|
+
Read it as an archive, not as current documentation: entries name the
|
|
9
|
+
branches, commits and beads of the run they were written during, and the code
|
|
10
|
+
they describe has moved on since. It is kept for two reasons -- those Lesson
|
|
11
|
+
paragraphs, and the fact that regression tests elsewhere in this repo cite
|
|
12
|
+
these entries by number as the reason they exist (for example
|
|
13
|
+
`packages/apra-fleet-client/test/transport-idle-timeout-guard.test.mjs` cites
|
|
14
|
+
Issue 8). **The Issue numbering is therefore load-bearing: do not renumber or
|
|
15
|
+
remove entries.** New findings belong in the relevant design doc or a bead,
|
|
16
|
+
not appended here.
|
|
7
17
|
|
|
8
18
|
## Loop iteration 1 (2026-07-19)
|
|
9
19
|
|