@apralabs/apra-fleet 0.4.0 → 0.4.1
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 +145 -7
- package/dist/agents/backlog-groomer.md +17 -1
- package/dist/agents/ci-watcher.md +13 -1
- package/dist/agents/deployer.md +15 -3
- package/dist/agents/doer.md +35 -1
- package/dist/agents/harvester.md +22 -3
- package/dist/agents/integ-test-runner.md +18 -2
- package/dist/agents/kb-reconciler.md +216 -0
- package/dist/agents/plan-reviewer.md +14 -1
- package/dist/agents/planner.md +88 -5
- package/dist/agents/regression-test-runner.md +19 -1
- package/dist/agents/reviewer.md +104 -3
- package/dist/agents/schemas/doer-output.json +63 -3
- package/dist/agents/schemas/harvester-output.json +59 -2
- package/dist/agents/schemas/integ-test-runner-output.json +2 -2
- package/dist/agents/schemas/kb-reconciler-output.json +87 -0
- package/dist/agents/schemas/planner-output.json +65 -0
- package/dist/agents/schemas/reviewer-output.json +105 -8
- package/dist/cli/install.d.ts +1 -0
- package/dist/cli/install.d.ts.map +1 -1
- package/dist/cli/install.js +136 -5
- package/dist/cli/install.js.map +1 -1
- package/dist/cli/join.js +1 -1
- package/dist/cli/join.js.map +1 -1
- package/dist/cli/kb-commit.d.ts +12 -0
- package/dist/cli/kb-commit.d.ts.map +1 -0
- package/dist/cli/kb-commit.js +53 -0
- package/dist/cli/kb-commit.js.map +1 -0
- package/dist/cli/kb-directives.d.ts +17 -0
- package/dist/cli/kb-directives.d.ts.map +1 -0
- package/dist/cli/kb-directives.js +146 -0
- package/dist/cli/kb-directives.js.map +1 -0
- package/dist/cli/kb-import.d.ts +13 -0
- package/dist/cli/kb-import.d.ts.map +1 -0
- package/dist/cli/kb-import.js +56 -0
- package/dist/cli/kb-import.js.map +1 -0
- package/dist/cli/uninstall.d.ts.map +1 -1
- package/dist/cli/uninstall.js +11 -0
- package/dist/cli/uninstall.js.map +1 -1
- package/dist/cli/watch.d.ts +53 -4
- package/dist/cli/watch.d.ts.map +1 -1
- package/dist/cli/watch.js +118 -17
- package/dist/cli/watch.js.map +1 -1
- package/dist/commands/kb-server.d.ts +8 -0
- package/dist/commands/kb-server.d.ts.map +1 -0
- package/dist/commands/kb-server.js +221 -0
- package/dist/commands/kb-server.js.map +1 -0
- package/dist/index.js +77 -2
- package/dist/index.js.map +1 -1
- package/dist/os/linux.d.ts +1 -0
- package/dist/os/linux.d.ts.map +1 -1
- package/dist/os/linux.js +18 -1
- package/dist/os/linux.js.map +1 -1
- package/dist/os/os-commands.d.ts +5 -0
- package/dist/os/os-commands.d.ts.map +1 -1
- package/dist/os/windows.d.ts +35 -0
- package/dist/os/windows.d.ts.map +1 -1
- package/dist/os/windows.js +67 -31
- package/dist/os/windows.js.map +1 -1
- package/dist/providers/agy.d.ts +12 -1
- package/dist/providers/agy.d.ts.map +1 -1
- package/dist/providers/agy.js +134 -9
- package/dist/providers/agy.js.map +1 -1
- package/dist/providers/claude.d.ts +11 -1
- package/dist/providers/claude.d.ts.map +1 -1
- package/dist/providers/claude.js +47 -19
- package/dist/providers/claude.js.map +1 -1
- package/dist/providers/codex.d.ts +11 -1
- package/dist/providers/codex.d.ts.map +1 -1
- package/dist/providers/codex.js +29 -6
- package/dist/providers/codex.js.map +1 -1
- package/dist/providers/copilot.d.ts +11 -1
- package/dist/providers/copilot.d.ts.map +1 -1
- package/dist/providers/copilot.js +26 -6
- package/dist/providers/copilot.js.map +1 -1
- package/dist/providers/email/headers.d.ts +15 -0
- package/dist/providers/email/headers.d.ts.map +1 -0
- package/dist/providers/email/headers.js +42 -0
- package/dist/providers/email/headers.js.map +1 -0
- package/dist/providers/email/index.d.ts +18 -0
- package/dist/providers/email/index.d.ts.map +1 -0
- package/dist/providers/email/index.js +60 -0
- package/dist/providers/email/index.js.map +1 -0
- package/dist/providers/email/provider.d.ts +49 -0
- package/dist/providers/email/provider.d.ts.map +1 -0
- package/dist/providers/email/provider.js +2 -0
- package/dist/providers/email/provider.js.map +1 -0
- package/dist/providers/email/sendgrid.d.ts +12 -0
- package/dist/providers/email/sendgrid.d.ts.map +1 -0
- package/dist/providers/email/sendgrid.js +67 -0
- package/dist/providers/email/sendgrid.js.map +1 -0
- package/dist/providers/email/smtp.d.ts +65 -0
- package/dist/providers/email/smtp.d.ts.map +1 -0
- package/dist/providers/email/smtp.js +373 -0
- package/dist/providers/email/smtp.js.map +1 -0
- package/dist/providers/gemini.d.ts +11 -1
- package/dist/providers/gemini.d.ts.map +1 -1
- package/dist/providers/gemini.js +38 -4
- package/dist/providers/gemini.js.map +1 -1
- package/dist/providers/none.d.ts +11 -1
- package/dist/providers/none.d.ts.map +1 -1
- package/dist/providers/none.js +21 -0
- package/dist/providers/none.js.map +1 -1
- package/dist/providers/opencode.d.ts +11 -1
- package/dist/providers/opencode.d.ts.map +1 -1
- package/dist/providers/opencode.js +55 -4
- package/dist/providers/opencode.js.map +1 -1
- package/dist/providers/provider.d.ts +77 -0
- package/dist/providers/provider.d.ts.map +1 -1
- package/dist/providers/provider.js +44 -0
- package/dist/providers/provider.js.map +1 -1
- package/dist/services/agent-provisioner.d.ts.map +1 -1
- package/dist/services/agent-provisioner.js +3 -6
- package/dist/services/agent-provisioner.js.map +1 -1
- package/dist/services/cloud/lifecycle.d.ts.map +1 -1
- package/dist/services/cloud/lifecycle.js +3 -0
- package/dist/services/cloud/lifecycle.js.map +1 -1
- package/dist/services/cloud/task-wrapper.d.ts +18 -0
- package/dist/services/cloud/task-wrapper.d.ts.map +1 -1
- package/dist/services/cloud/task-wrapper.js +157 -0
- package/dist/services/cloud/task-wrapper.js.map +1 -1
- package/dist/services/github-app.d.ts.map +1 -1
- package/dist/services/github-app.js +11 -2
- package/dist/services/github-app.js.map +1 -1
- package/dist/services/knowledge/audn.d.ts +37 -0
- package/dist/services/knowledge/audn.d.ts.map +1 -0
- package/dist/services/knowledge/audn.js +219 -0
- package/dist/services/knowledge/audn.js.map +1 -0
- package/dist/services/knowledge/file-hash.d.ts +11 -0
- package/dist/services/knowledge/file-hash.d.ts.map +1 -0
- package/dist/services/knowledge/file-hash.js +123 -0
- package/dist/services/knowledge/file-hash.js.map +1 -0
- package/dist/services/knowledge/http-provider.d.ts +46 -0
- package/dist/services/knowledge/http-provider.d.ts.map +1 -0
- package/dist/services/knowledge/http-provider.js +254 -0
- package/dist/services/knowledge/http-provider.js.map +1 -0
- package/dist/services/knowledge/kb-providers.d.ts +15 -0
- package/dist/services/knowledge/kb-providers.d.ts.map +1 -0
- package/dist/services/knowledge/kb-providers.js +92 -0
- package/dist/services/knowledge/kb-providers.js.map +1 -0
- package/dist/services/knowledge/kb-scope-input.d.ts +5 -0
- package/dist/services/knowledge/kb-scope-input.d.ts.map +1 -0
- package/dist/services/knowledge/kb-scope-input.js +11 -0
- package/dist/services/knowledge/kb-scope-input.js.map +1 -0
- package/dist/services/knowledge/kb-service.d.ts +3 -0
- package/dist/services/knowledge/kb-service.d.ts.map +1 -0
- package/dist/services/knowledge/kb-service.js +2 -0
- package/dist/services/knowledge/kb-service.js.map +1 -0
- package/dist/services/knowledge/path-validation.d.ts +2 -0
- package/dist/services/knowledge/path-validation.d.ts.map +1 -0
- package/dist/services/knowledge/path-validation.js +13 -0
- package/dist/services/knowledge/path-validation.js.map +1 -0
- package/dist/services/knowledge/pre-init.d.ts +14 -0
- package/dist/services/knowledge/pre-init.d.ts.map +1 -0
- package/dist/services/knowledge/pre-init.js +147 -0
- package/dist/services/knowledge/pre-init.js.map +1 -0
- package/dist/services/knowledge/project-slug.d.ts +2 -0
- package/dist/services/knowledge/project-slug.d.ts.map +1 -0
- package/dist/services/knowledge/project-slug.js +49 -0
- package/dist/services/knowledge/project-slug.js.map +1 -0
- package/dist/services/knowledge/sqlite-provider.d.ts +147 -0
- package/dist/services/knowledge/sqlite-provider.d.ts.map +1 -0
- package/dist/services/knowledge/sqlite-provider.js +1646 -0
- package/dist/services/knowledge/sqlite-provider.js.map +1 -0
- package/dist/services/knowledge/types.d.ts +163 -0
- package/dist/services/knowledge/types.d.ts.map +1 -0
- package/dist/services/knowledge/types.js +9 -0
- package/dist/services/knowledge/types.js.map +1 -0
- package/dist/services/member-home.d.ts +89 -0
- package/dist/services/member-home.d.ts.map +1 -0
- package/dist/services/member-home.js +256 -0
- package/dist/services/member-home.js.map +1 -0
- package/dist/services/member-remote-url.d.ts +34 -0
- package/dist/services/member-remote-url.d.ts.map +1 -0
- package/dist/services/member-remote-url.js +39 -0
- package/dist/services/member-remote-url.js.map +1 -0
- package/dist/services/orphan-recovery.d.ts +5 -2
- package/dist/services/orphan-recovery.d.ts.map +1 -1
- package/dist/services/orphan-recovery.js +19 -8
- package/dist/services/orphan-recovery.js.map +1 -1
- package/dist/services/preflight-check.d.ts +56 -0
- package/dist/services/preflight-check.d.ts.map +1 -0
- package/dist/services/preflight-check.js +277 -0
- package/dist/services/preflight-check.js.map +1 -0
- package/dist/services/stall/log-path-resolver.d.ts +11 -8
- package/dist/services/stall/log-path-resolver.d.ts.map +1 -1
- package/dist/services/stall/log-path-resolver.js +17 -40
- package/dist/services/stall/log-path-resolver.js.map +1 -1
- package/dist/services/stall/stall-detector.d.ts +32 -0
- package/dist/services/stall/stall-detector.d.ts.map +1 -1
- package/dist/services/stall/stall-detector.js +149 -6
- package/dist/services/stall/stall-detector.js.map +1 -1
- package/dist/services/stall/stall-poller.d.ts +34 -0
- package/dist/services/stall/stall-poller.d.ts.map +1 -1
- package/dist/services/stall/stall-poller.js +134 -2
- package/dist/services/stall/stall-poller.js.map +1 -1
- package/dist/services/strategy.d.ts.map +1 -1
- package/dist/services/strategy.js +2 -2
- package/dist/services/strategy.js.map +1 -1
- package/dist/services/tool-registry.d.ts.map +1 -1
- package/dist/services/tool-registry.js +87 -1
- package/dist/services/tool-registry.js.map +1 -1
- package/dist/services/vcs/github.d.ts.map +1 -1
- package/dist/services/vcs/github.js +32 -1
- package/dist/services/vcs/github.js.map +1 -1
- package/dist/services/version-check.d.ts +22 -0
- package/dist/services/version-check.d.ts.map +1 -0
- package/dist/services/version-check.js +103 -0
- package/dist/services/version-check.js.map +1 -0
- package/dist/skills/fleet-sprint-cli/SKILL.md +13 -2
- package/dist/skills/pm/beads.md +6 -0
- package/dist/skills/pm/fleet-addendum.md +6 -0
- package/dist/skills/pm/index.md +56 -0
- package/dist/skills/pm/kb-reconcile.md +132 -0
- package/dist/skills/pm/kb-review.md +109 -0
- package/dist/tools/check-status.d.ts +47 -0
- package/dist/tools/check-status.d.ts.map +1 -1
- package/dist/tools/check-status.js +242 -0
- package/dist/tools/check-status.js.map +1 -1
- package/dist/tools/child-id-allocator.d.ts +2 -2
- package/dist/tools/code-intelligence-codebase-memory.d.ts +11 -0
- package/dist/tools/code-intelligence-codebase-memory.d.ts.map +1 -0
- package/dist/tools/code-intelligence-codebase-memory.js +270 -0
- package/dist/tools/code-intelligence-codebase-memory.js.map +1 -0
- package/dist/tools/code-intelligence-freshness.d.ts +2 -0
- package/dist/tools/code-intelligence-freshness.d.ts.map +1 -0
- package/dist/tools/code-intelligence-freshness.js +26 -0
- package/dist/tools/code-intelligence-freshness.js.map +1 -0
- package/dist/tools/code-intelligence-gitnexus.d.ts +14 -0
- package/dist/tools/code-intelligence-gitnexus.d.ts.map +1 -0
- package/dist/tools/code-intelligence-gitnexus.js +475 -0
- package/dist/tools/code-intelligence-gitnexus.js.map +1 -0
- package/dist/tools/code-intelligence-kb-enrich.d.ts +2 -0
- package/dist/tools/code-intelligence-kb-enrich.d.ts.map +1 -0
- package/dist/tools/code-intelligence-kb-enrich.js +65 -0
- package/dist/tools/code-intelligence-kb-enrich.js.map +1 -0
- package/dist/tools/code-intelligence-reindex.d.ts +7 -0
- package/dist/tools/code-intelligence-reindex.d.ts.map +1 -0
- package/dist/tools/code-intelligence-reindex.js +106 -0
- package/dist/tools/code-intelligence-reindex.js.map +1 -0
- package/dist/tools/code-intelligence-telemetry.d.ts +5 -0
- package/dist/tools/code-intelligence-telemetry.d.ts.map +1 -0
- package/dist/tools/code-intelligence-telemetry.js +52 -0
- package/dist/tools/code-intelligence-telemetry.js.map +1 -0
- package/dist/tools/code-intelligence-tests.d.ts +2 -0
- package/dist/tools/code-intelligence-tests.d.ts.map +1 -0
- package/dist/tools/code-intelligence-tests.js +24 -0
- package/dist/tools/code-intelligence-tests.js.map +1 -0
- package/dist/tools/code-intelligence.d.ts +114 -0
- package/dist/tools/code-intelligence.d.ts.map +1 -0
- package/dist/tools/code-intelligence.js +124 -0
- package/dist/tools/code-intelligence.js.map +1 -0
- package/dist/tools/compose-permissions.d.ts +26 -0
- package/dist/tools/compose-permissions.d.ts.map +1 -1
- package/dist/tools/compose-permissions.js +244 -33
- package/dist/tools/compose-permissions.js.map +1 -1
- package/dist/tools/execute-command.d.ts +2 -0
- package/dist/tools/execute-command.d.ts.map +1 -1
- package/dist/tools/execute-command.js +86 -16
- package/dist/tools/execute-command.js.map +1 -1
- package/dist/tools/execute-prompt.d.ts +13 -1
- package/dist/tools/execute-prompt.d.ts.map +1 -1
- package/dist/tools/execute-prompt.js +257 -45
- package/dist/tools/execute-prompt.js.map +1 -1
- package/dist/tools/kb-capture.d.ts +53 -0
- package/dist/tools/kb-capture.d.ts.map +1 -0
- package/dist/tools/kb-capture.js +130 -0
- package/dist/tools/kb-capture.js.map +1 -0
- package/dist/tools/kb-context.d.ts +17 -0
- package/dist/tools/kb-context.d.ts.map +1 -0
- package/dist/tools/kb-context.js +29 -0
- package/dist/tools/kb-context.js.map +1 -0
- package/dist/tools/kb-export.d.ts +19 -0
- package/dist/tools/kb-export.d.ts.map +1 -0
- package/dist/tools/kb-export.js +344 -0
- package/dist/tools/kb-export.js.map +1 -0
- package/dist/tools/kb-feedback.d.ts +23 -0
- package/dist/tools/kb-feedback.d.ts.map +1 -0
- package/dist/tools/kb-feedback.js +43 -0
- package/dist/tools/kb-feedback.js.map +1 -0
- package/dist/tools/kb-freshness-sweep.d.ts +14 -0
- package/dist/tools/kb-freshness-sweep.d.ts.map +1 -0
- package/dist/tools/kb-freshness-sweep.js +29 -0
- package/dist/tools/kb-freshness-sweep.js.map +1 -0
- package/dist/tools/kb-harvest.d.ts +20 -0
- package/dist/tools/kb-harvest.d.ts.map +1 -0
- package/dist/tools/kb-harvest.js +143 -0
- package/dist/tools/kb-harvest.js.map +1 -0
- package/dist/tools/kb-import.d.ts +44 -0
- package/dist/tools/kb-import.d.ts.map +1 -0
- package/dist/tools/kb-import.js +239 -0
- package/dist/tools/kb-import.js.map +1 -0
- package/dist/tools/kb-invalidate.d.ts +19 -0
- package/dist/tools/kb-invalidate.d.ts.map +1 -0
- package/dist/tools/kb-invalidate.js +34 -0
- package/dist/tools/kb-invalidate.js.map +1 -0
- package/dist/tools/kb-list.d.ts +32 -0
- package/dist/tools/kb-list.d.ts.map +1 -0
- package/dist/tools/kb-list.js +43 -0
- package/dist/tools/kb-list.js.map +1 -0
- package/dist/tools/kb-promote.d.ts +20 -0
- package/dist/tools/kb-promote.d.ts.map +1 -0
- package/dist/tools/kb-promote.js +20 -0
- package/dist/tools/kb-promote.js.map +1 -0
- package/dist/tools/kb-query.d.ts +35 -0
- package/dist/tools/kb-query.d.ts.map +1 -0
- package/dist/tools/kb-query.js +111 -0
- package/dist/tools/kb-query.js.map +1 -0
- package/dist/tools/kb-reconcile-prefilter.d.ts +14 -0
- package/dist/tools/kb-reconcile-prefilter.d.ts.map +1 -0
- package/dist/tools/kb-reconcile-prefilter.js +26 -0
- package/dist/tools/kb-reconcile-prefilter.js.map +1 -0
- package/dist/tools/kb-resolve-contradiction.d.ts +23 -0
- package/dist/tools/kb-resolve-contradiction.d.ts.map +1 -0
- package/dist/tools/kb-resolve-contradiction.js +37 -0
- package/dist/tools/kb-resolve-contradiction.js.map +1 -0
- package/dist/tools/kb-session-prime.d.ts +26 -0
- package/dist/tools/kb-session-prime.d.ts.map +1 -0
- package/dist/tools/kb-session-prime.js +392 -0
- package/dist/tools/kb-session-prime.js.map +1 -0
- package/dist/tools/kb-setup.d.ts +20 -0
- package/dist/tools/kb-setup.d.ts.map +1 -0
- package/dist/tools/kb-setup.js +49 -0
- package/dist/tools/kb-setup.js.map +1 -0
- package/dist/tools/kb-stats.d.ts +20 -0
- package/dist/tools/kb-stats.d.ts.map +1 -0
- package/dist/tools/kb-stats.js +115 -0
- package/dist/tools/kb-stats.js.map +1 -0
- package/dist/tools/member-detail.d.ts.map +1 -1
- package/dist/tools/member-detail.js +8 -0
- package/dist/tools/member-detail.js.map +1 -1
- package/dist/tools/monitor-task.d.ts.map +1 -1
- package/dist/tools/monitor-task.js +21 -3
- package/dist/tools/monitor-task.js.map +1 -1
- package/dist/tools/provision-auth.d.ts.map +1 -1
- package/dist/tools/provision-auth.js +10 -3
- package/dist/tools/provision-auth.js.map +1 -1
- package/dist/tools/register-member.d.ts +3 -0
- package/dist/tools/register-member.d.ts.map +1 -1
- package/dist/tools/register-member.js +30 -1
- 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 +17 -3
- package/dist/tools/remove-member.js.map +1 -1
- package/dist/tools/report-status.d.ts.map +1 -1
- package/dist/tools/report-status.js +2 -1
- package/dist/tools/report-status.js.map +1 -1
- package/dist/tools/send-email.d.ts +69 -0
- package/dist/tools/send-email.d.ts.map +1 -0
- package/dist/tools/send-email.js +177 -0
- package/dist/tools/send-email.js.map +1 -0
- package/dist/tools/setup-ssh-key.d.ts.map +1 -1
- package/dist/tools/setup-ssh-key.js +2 -0
- package/dist/tools/setup-ssh-key.js.map +1 -1
- package/dist/tools/update-member.d.ts +3 -0
- package/dist/tools/update-member.d.ts.map +1 -1
- package/dist/tools/update-member.js +25 -1
- package/dist/tools/update-member.js.map +1 -1
- package/dist/types.d.ts +1 -0
- package/dist/types.d.ts.map +1 -1
- package/dist/utils/prompt-errors.js +1 -1
- package/dist/utils/prompt-errors.js.map +1 -1
- package/dist/utils/session-caller.d.ts +28 -0
- package/dist/utils/session-caller.d.ts.map +1 -0
- package/dist/utils/session-caller.js +24 -0
- package/dist/utils/session-caller.js.map +1 -0
- package/dist/utils/work-folder-validation.d.ts +39 -0
- package/dist/utils/work-folder-validation.d.ts.map +1 -0
- package/dist/utils/work-folder-validation.js +60 -0
- package/dist/utils/work-folder-validation.js.map +1 -0
- package/dist/workflows/auto-sprint.js +546 -6
- package/package.json +7 -4
- package/packages/apra-fleet-client/src/client/api.mjs +118 -4
- package/packages/apra-fleet-se/apra-pm/agents/backlog-groomer.md +17 -1
- package/packages/apra-fleet-se/apra-pm/agents/ci-watcher.md +13 -1
- package/packages/apra-fleet-se/apra-pm/agents/deployer.md +15 -3
- package/packages/apra-fleet-se/apra-pm/agents/doer.md +35 -1
- package/packages/apra-fleet-se/apra-pm/agents/harvester.md +22 -3
- package/packages/apra-fleet-se/apra-pm/agents/integ-test-runner.md +18 -2
- package/packages/apra-fleet-se/apra-pm/agents/kb-reconciler.md +216 -0
- package/packages/apra-fleet-se/apra-pm/agents/plan-reviewer.md +14 -1
- package/packages/apra-fleet-se/apra-pm/agents/planner.md +88 -5
- package/packages/apra-fleet-se/apra-pm/agents/regression-test-runner.md +19 -1
- package/packages/apra-fleet-se/apra-pm/agents/reviewer.md +104 -3
- package/packages/apra-fleet-se/apra-pm/agents/schemas/doer-output.json +63 -3
- package/packages/apra-fleet-se/apra-pm/agents/schemas/harvester-output.json +59 -2
- package/packages/apra-fleet-se/apra-pm/agents/schemas/integ-test-runner-output.json +2 -2
- package/packages/apra-fleet-se/apra-pm/agents/schemas/kb-reconciler-output.json +87 -0
- package/packages/apra-fleet-se/apra-pm/agents/schemas/planner-output.json +65 -0
- package/packages/apra-fleet-se/apra-pm/agents/schemas/reviewer-output.json +105 -8
- package/packages/apra-fleet-se/apra-pm/skills/pm/beads.md +6 -0
- package/packages/apra-fleet-se/apra-pm/skills/pm/fleet-addendum.md +6 -0
- package/packages/apra-fleet-se/apra-pm/skills/pm/index.md +56 -0
- package/packages/apra-fleet-se/apra-pm/skills/pm/kb-reconcile.md +132 -0
- package/packages/apra-fleet-se/apra-pm/skills/pm/kb-review.md +109 -0
- package/packages/apra-fleet-se/bin/cli.mjs +7 -0
- package/packages/apra-fleet-se/bin/serve.mjs +14 -2
- package/packages/apra-fleet-se/fleet-sprint/contracts.mjs +31 -5
- package/packages/apra-fleet-se/fleet-sprint/docs/README.md +1 -1
- package/packages/apra-fleet-se/fleet-sprint/docs/coach-role-design.md +23 -151
- package/packages/apra-fleet-se/fleet-sprint/docs/dolt-manual-recovery-verified.md +256 -0
- package/packages/apra-fleet-se/fleet-sprint/docs/dolt-sync-redesign.md +1482 -0
- package/packages/apra-fleet-se/fleet-sprint/docs/escalate-to-llm-design.md +908 -0
- package/packages/apra-fleet-se/fleet-sprint/docs/shared-orchestrator-reservation-design.md +399 -0
- package/packages/apra-fleet-se/fleet-sprint/dolt-settle.mjs +972 -0
- package/packages/apra-fleet-se/fleet-sprint/dolt-sync.mjs +167 -101
- package/packages/apra-fleet-se/fleet-sprint/errors.mjs +50 -6
- package/packages/apra-fleet-se/fleet-sprint/runner.js +1416 -116
- package/packages/apra-fleet-se/fleet-sprint/skills/fleet-sprint-cli/SKILL.md +13 -2
- package/packages/apra-fleet-se/fleet-sprint/skills/fleet-supervisor/SKILL.md +350 -0
- package/packages/apra-fleet-se/fleet-sprint/sprint-progress.mjs +101 -0
- package/packages/apra-fleet-se/fleet-sprint/vcs-providers/github.mjs +30 -17
- package/packages/apra-fleet-se/fleet-sprint/viewer-extensions.mjs +62 -2
- package/packages/apra-fleet-se/package.json +1 -0
- package/packages/apra-fleet-workflow/src/viewer/index.mjs +127 -13
- package/packages/apra-fleet-workflow/src/viewer/run-title.mjs +60 -0
- package/packages/apra-fleet-workflow/src/workflow/index.mjs +8 -4
- package/skills/fleet/knowledge-agent.md +66 -0
- package/skills/fleet/permissions.md +28 -4
- package/skills/fleet/profiles/base-dev.json +10 -1
- package/skills/fleet/profiles/base-reviewer.json +8 -1
- package/skills/fleet/profiles/tag-kb-reconciler.json +20 -0
- package/version.json +1 -1
- package/packages/apra-fleet-se/fleet-sprint/docs/dolt-tier2-runbook.md +0 -127
- package/packages/apra-fleet-se/fleet-sprint/dolt-recovery-path-b.mjs +0 -339
- package/packages/apra-fleet-se/fleet-sprint/dolt-recovery-tier2.mjs +0 -360
- package/packages/apra-fleet-se/fleet-sprint/dolt-recovery.mjs +0 -363
|
@@ -0,0 +1,399 @@
|
|
|
1
|
+
# Design: Pinned Shared Orchestrator (supervisor-held orchestrator-role pin)
|
|
2
|
+
|
|
3
|
+
Status: DESIGN PROPOSAL (no beads filed yet; matured from the 2026-08 stale-beads incidents)
|
|
4
|
+
Author: design session, 2026-08-11
|
|
5
|
+
Source doc path: `packages/apra-fleet-se/fleet-sprint/docs/shared-orchestrator-reservation-design.md`
|
|
6
|
+
|
|
7
|
+
## Problem recap
|
|
8
|
+
|
|
9
|
+
Every fleet-sprint launch resolves an `orchestrator` pseudo-role (runner.js:73
|
|
10
|
+
`ROLE_ORCHESTRATOR`, runner.js:4938 `orchestratorMember = getMemberForRole(ROLE_ORCHESTRATOR)`)
|
|
11
|
+
whose beads clone is the sprint's ground truth for all scope reads and bd mutations. Absent an
|
|
12
|
+
explicit `--role-map '{"orchestrator":[...]}'`, this silently defaults to
|
|
13
|
+
`unmappedRoleFallbackPool[0]` (runner.js:4915-4920) -- for a single-member sprint, the dispatch
|
|
14
|
+
member itself. Two production incidents followed: beads created on the interactive operator
|
|
15
|
+
machine's clone were invisible to sprints whose accidental orchestrator was a different,
|
|
16
|
+
never-synced member.
|
|
17
|
+
|
|
18
|
+
The naive fix (role-map a hub member as orchestrator on every launch) deadlocks concurrency:
|
|
19
|
+
the launch overlap guard unions `--members` with every roleMap value INCLUDING orchestrator
|
|
20
|
+
(api.mjs:103-117 `memberUnion`, api.mjs:133-141), so a shared orchestrator member would 409
|
|
21
|
+
every second concurrent launch (api.mjs:202-207). The operator's proposal: the supervisor holds
|
|
22
|
+
a standing, shared, orchestrator-role-only reservation on one designated member and injects it
|
|
23
|
+
as the default orchestrator into every launch.
|
|
24
|
+
|
|
25
|
+
---
|
|
26
|
+
|
|
27
|
+
## Part A -- Research findings (evidence, not assumption)
|
|
28
|
+
|
|
29
|
+
### A1. The concurrency-safety premise is PARTLY FALSE: the orchestrator role DOES mutate git working-tree state
|
|
30
|
+
|
|
31
|
+
The working assumption ("orchestrator commands are dolt/bd-only and never touch git
|
|
32
|
+
branch/working-tree state") does not survive a read of runner.js. The orchestrator-role command
|
|
33
|
+
sites split into two classes:
|
|
34
|
+
|
|
35
|
+
**Beads/dolt-only sites (the majority, as assumed).** `bd list/show/update/close/dep/defer`
|
|
36
|
+
against `member_name: orchestratorMember` -- e.g. runner.js:5123 (all-beads read), 5210
|
|
37
|
+
(scope filter), 5315 (status reopen), 7036 (claim), 7511 (bd show), 7577/8284/8677 (reopen per
|
|
38
|
+
verdict), 8073-8083 (bug triage), 9066 (target close), 5925 (bd dep remove), 2247-2249
|
|
39
|
+
(verifyDoerStreakClosed). Plus the D-pull/D-push brackets: `DoltSync.syncBefore(orchestratorMember, ...)`
|
|
40
|
+
at runner.js:2247, 5545 (readinessGate), 5836, 8124; `DoltSync.syncAfter(orchestratorMember, ...)`
|
|
41
|
+
at 6502, 6769, 7689, 8345, 9078 and `doltPushAfter` at 8691. All of these are `bd`/`bd dolt`
|
|
42
|
+
commands routed through dolt-sync.mjs (the single `bd dolt` chokepoint, dolt-sync.mjs:6-8;
|
|
43
|
+
actual commands are `bd dolt pull` at dolt-sync.mjs:365/675 and `bd dolt push` at 620/695).
|
|
44
|
+
None of these touch the git working tree.
|
|
45
|
+
|
|
46
|
+
**Git working-tree sites (the premise-breakers), with file:line evidence:**
|
|
47
|
+
|
|
48
|
+
1. **Branch ensure includes the orchestrator.** `branchEnsureMembers` is explicitly the union
|
|
49
|
+
of `orchestratorMember` + doer pool + reviewer pool (runner.js:5517-5521). The ensure loop
|
|
50
|
+
(runner.js:5557-5726) runs, on the orchestrator's clone: `git fetch origin <base>` (5566),
|
|
51
|
+
`git fetch origin <branch>` (5582), local-branch probe (5598), two `git merge-base
|
|
52
|
+
--is-ancestor` checks (5616, 5625), then a **`git checkout <branch>` or `git checkout -B
|
|
53
|
+
<branch> <startPoint>`** (5689, decision built by `decideEnsureBranchAction`,
|
|
54
|
+
runner.js:4553-4634), with a **`git stash push -u`** fallback on a dirty tree (5709-5716).
|
|
55
|
+
2. **Per-cycle re-ensure.** `reEnsureBranchOnMembers()` re-runs `git checkout <branch>` on
|
|
56
|
+
every branchEnsureMembers entry -- orchestrator included -- each cycle (runner.js:5745-5756).
|
|
57
|
+
3. **Requirements-file probe reads the orchestrator's working tree.** `probeFileExists()`
|
|
58
|
+
dispatches a `node -e fs.existsSync(...)` to `orchestratorMember` (runner.js:5819-5829);
|
|
59
|
+
what it sees depends on which branch that clone has checked out.
|
|
60
|
+
4. **Publish PR pushes from the orchestrator's clone.** `git push -u origin <branch>` with
|
|
61
|
+
`member_name: orchestratorMember` (runner.js:9000-9008), `git remote get-url origin`
|
|
62
|
+
(9046-9051), and the VCSModule create-PR curl dispatched on the orchestrator (9132-9142).
|
|
63
|
+
The push publishes the orchestrator's LOCAL `refs/heads/<branch>` -- it assumes that clone's
|
|
64
|
+
branch ref is current (true today only because orchestrator == doer in single-member
|
|
65
|
+
practice; already latent-fragile for true multi-member synced-mode sprints).
|
|
66
|
+
5. **Abort finalization does git on the orchestrator.** `finalizeAbort()` runs `git fetch`,
|
|
67
|
+
`git rev-list --count origin/<base>..<branch>` (against the LOCAL branch ref) and `git push
|
|
68
|
+
-u origin <branch>` on the member resolved at runner.js:9392-9394 -- i.e. the orchestrator
|
|
69
|
+
(finalizeAbort body: runner.js:4358-4398).
|
|
70
|
+
|
|
71
|
+
**Consequence:** N concurrent sprints sharing ONE pinned orchestrator member would fight over a
|
|
72
|
+
single working tree: each sprint's ensure/re-ensure flips HEAD to its own branch, the
|
|
73
|
+
requirements probe can read another sprint's branch content, a stash from sprint A can be
|
|
74
|
+
popped into confusion, and publish/abort pushes read local refs whose state interleaves with
|
|
75
|
+
other sprints' checkouts. **The pin is NOT safe as-is.** It becomes safe only after the
|
|
76
|
+
orchestrator role is made genuinely beads-only (see D0 below) -- a bounded, well-localized
|
|
77
|
+
refactor, because every git site above is either relocatable to a dispatch member or
|
|
78
|
+
unnecessary for a non-dispatch orchestrator.
|
|
79
|
+
|
|
80
|
+
### A2. The dolt push mutex: what it does and does not already cover
|
|
81
|
+
|
|
82
|
+
The supervisor owns ONE global mutex serializing every cross-sprint `bd dolt push`
|
|
83
|
+
(dolt-mutex.mjs:6-18, motivated by PoC constraints C.2 "any concurrent write to the same row
|
|
84
|
+
hard-conflicts" and C.3 "one unresolved conflict wedges the entire clone"). It is FIFO, leased,
|
|
85
|
+
pid-probed, and exposed over HTTP to the detached children (dolt-mutex.mjs:267-331). runner.js
|
|
86
|
+
threads it plus a per-sprint id into every D-push: `mutex: doltPushMutex, sprintId:
|
|
87
|
+
sprintMutexId` at runner.js:6502/6769/7689/8345/9078/8691 (fatal-path variant at 1143), where
|
|
88
|
+
`sprintMutexId` is the sprint branch (runner.js:4674-4676). Holder identity is logged on grant,
|
|
89
|
+
reclaim, and release (dolt-mutex.mjs:139, 181).
|
|
90
|
+
|
|
91
|
+
So: **cross-sprint push windows are already serialized today, for any pair of clones.** The
|
|
92
|
+
mutex was designed for pushes from DIFFERENT clones racing at the shared dolt remote -- exactly
|
|
93
|
+
the accidental-shared-orchestrator case the prompt describes. To that extent, reservation
|
|
94
|
+
exclusivity was never what protected orchestrator-role dolt writes; the mutex was.
|
|
95
|
+
|
|
96
|
+
**What the mutex does NOT cover, and the pin makes load-bearing:**
|
|
97
|
+
|
|
98
|
+
- `DoltSync.syncBefore` (D-pull) is never mutex-guarded -- no `mutex:` at runner.js:2247,
|
|
99
|
+
5026, 5545, 5836, 8124. Two sprints pulling different clones concurrently is fine; two
|
|
100
|
+
sprints concurrently running `bd dolt pull` against the SAME pinned clone is a new, untested
|
|
101
|
+
interleaving (including pull racing an in-flight push-reconcile, dolt-sync.mjs:675).
|
|
102
|
+
- Plain local bd mutations (`bd update/close/dep/defer/create`) are not serialized at all.
|
|
103
|
+
Today each sprint mutates its own orchestrator clone; under the pin, three sprints issue
|
|
104
|
+
concurrent bd writes against ONE embedded-dolt clone (`.beads/embeddeddolt`). Whether bd
|
|
105
|
+
1.1.x embedded mode tolerates concurrent same-clone processes (vs. erroring "database
|
|
106
|
+
locked" or corrupting) is **empirically unknown in this repo** -- nothing in
|
|
107
|
+
dolt-sync.mjs/dolt-mutex.mjs speaks to same-clone process concurrency. This must be spiked,
|
|
108
|
+
and the safe default design is to serialize (D3 below).
|
|
109
|
+
- `execute_command` (the transport under every orchestrator `command()`) enforces neither
|
|
110
|
+
reservations nor per-member mutual exclusion -- src/tools/execute-command.ts only marks the
|
|
111
|
+
statusline busy (execute-command.ts:238, 264-265); the `reservedBy` dispatch rejection
|
|
112
|
+
exists only in execute_prompt (execute-prompt.ts:536-543). So nothing at the transport layer
|
|
113
|
+
will accidentally serialize (or reject) the shared traffic either.
|
|
114
|
+
|
|
115
|
+
### A3. Reservation model today (ledger + server-side reservedBy)
|
|
116
|
+
|
|
117
|
+
- **Supervisor ledger** (src/supervisor/ledger.mjs): per-sprint entries
|
|
118
|
+
`{ members, issueRoots, childPid, reservedAt, branch, base, goal, exit*, logPath }`
|
|
119
|
+
(ledger.mjs:65-108), claimed and released in exact lockstep with the sprint lifecycle
|
|
120
|
+
(ledger.mjs:21-29, claim at 461-477, release at 485-499), atomically persisted, PID-probe
|
|
121
|
+
reconciled on restart. Everything about it is sprint-lifecycle-scoped.
|
|
122
|
+
- **Launch overlap guard** (api.mjs:162-209): all-or-nothing 409 on any member of the incoming
|
|
123
|
+
union (members + every roleMap value, orchestrator included) overlapping any live ledger
|
|
124
|
+
entry, merged with the fleet server's own per-member `reservedBy` record via `listMembers`
|
|
125
|
+
(api.mjs:185-200).
|
|
126
|
+
- **Server-side reservation authority**: `member_reservation` (src/tools/member-reservation.ts)
|
|
127
|
+
sets `agent.reservedBy`; reserve fails if held by a different id (member-reservation.ts:42-44),
|
|
128
|
+
refresh by the same id succeeds (49-51), release is owner-checked (61-63), force_release is
|
|
129
|
+
unconditional (71-79). `sprint_id` is an opaque string -- nothing requires it to be a real
|
|
130
|
+
sprint. Enforcement is at execute_prompt only (execute-prompt.ts:536-543), keyed on per-call
|
|
131
|
+
`sprint_id` falling back to `APRA_FLEET_SPRINT_ID` (execute-prompt.ts:106-114, 254-259).
|
|
132
|
+
- **Who actually reserves**: supervisor-spawned children run bin/cli.mjs, which reserves
|
|
133
|
+
`validMembers` only -- roleMap values are NOT in its reserveAll set (cli.mjs:723-729). The
|
|
134
|
+
supervisor ledger union DOES fold roleMap values in (api.mjs:442). So today a role-mapped
|
|
135
|
+
orchestrator outside `--members` is overlap-guarded at the supervisor but never server-side
|
|
136
|
+
reserved by the child -- an existing asymmetry the pin design can exploit cleanly (the pinned
|
|
137
|
+
member simply never enters either per-sprint set).
|
|
138
|
+
|
|
139
|
+
### A4. Interaction with in-flight work (pause/resume `apra-fleet-p2to`, sprint-doctor `apra-fleet-iiny`)
|
|
140
|
+
|
|
141
|
+
Pause/resume's reservation logic (escalate-to-llm-design.md:520-533) releases each member via
|
|
142
|
+
owner-checked `member_reservation release` on pause and re-reserves on resume, failing resume
|
|
143
|
+
cleanly when a member was taken. This operates on the sprint's OWN per-sprint reservation set.
|
|
144
|
+
Under this design the pinned member is deliberately NOT in that set (D1), so pause/resume never
|
|
145
|
+
touches it -- and even a buggy release attempt would be refused by the owner check
|
|
146
|
+
(member-reservation.ts:61-63), because the pin's owner is a supervisor sentinel, not the sprint
|
|
147
|
+
id. So the mechanisms are structurally orthogonal, **with two real (non-hand-waved) contact
|
|
148
|
+
points**:
|
|
149
|
+
|
|
150
|
+
1. **Sprint-doctor's wedged-reservation remedy is NOT orthogonal.** The doctor's remedy table
|
|
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:679). The pin sentinel has no pid and
|
|
153
|
+
no ledger entry -- to that heuristic it looks exactly like a wedged dead reservation, and a
|
|
154
|
+
doctor run would strip the pin. The doctor rule must learn: a reservation whose owner
|
|
155
|
+
matches the supervisor pin sentinel prefix is never force-releasable (and the supervisor
|
|
156
|
+
should self-heal the pin regardless -- D2).
|
|
157
|
+
2. **Explicit orchestrator override** (D4's escape hatch) puts the overriding member back in
|
|
158
|
+
the per-sprint reservation set, where pause/resume handles it under existing semantics --
|
|
159
|
+
intentionally unchanged.
|
|
160
|
+
|
|
161
|
+
---
|
|
162
|
+
|
|
163
|
+
## Part B -- Design
|
|
164
|
+
|
|
165
|
+
### D0 (prerequisite). Make the orchestrator role beads-only
|
|
166
|
+
|
|
167
|
+
Because of A1, the pin requires relocating the orchestrator's git surface first. All four
|
|
168
|
+
sites are bounded:
|
|
169
|
+
|
|
170
|
+
- **Branch ensure / re-ensure**: drop `orchestratorMember` from `branchEnsureMembers`
|
|
171
|
+
(runner.js:5517-5521) whenever the orchestrator is not also a dispatch member (compute:
|
|
172
|
+
member appears in doer/reviewer pools). A beads-only orchestrator has no need for the sprint
|
|
173
|
+
branch; its clone's git checkout becomes irrelevant to the sprint.
|
|
174
|
+
- **Requirements probe/read** (runner.js:5819-5829 and the up-front read near 5523): dispatch
|
|
175
|
+
to `getMemberForRole('planner')` -- the planner is the consumer of the requirements content
|
|
176
|
+
and its member is already branch-ensured.
|
|
177
|
+
- **Publish PR** (runner.js:9000-9152): run the branch push, origin-URL probe, and PR curl on a
|
|
178
|
+
dispatch member -- recommend `getMemberForRole('harvester')` (the last code-writing role;
|
|
179
|
+
its clone G-pushed most recently, so its local ref is current -- runner.js:8913-8923). This
|
|
180
|
+
also fixes the latent multi-member staleness noted in A1 point 4.
|
|
181
|
+
- **finalizeAbort** (runner.js:9390-9400 member resolution): resolve the same dispatch member
|
|
182
|
+
instead of the orchestrator.
|
|
183
|
+
|
|
184
|
+
After D0, the orchestrator's entire command surface is `bd`/`bd dolt` via execute_command, and
|
|
185
|
+
"sharing" reduces to the beads-clone concurrency question handled in D3.
|
|
186
|
+
|
|
187
|
+
### D1. Data model: a supervisor "pinned roles" config + server-side sentinel -- NOT a ledger reservation type
|
|
188
|
+
|
|
189
|
+
**Recommended:** model the pin as supervisor configuration plus a standing server-side
|
|
190
|
+
`reservedBy` sentinel, with the ledger kept completely ignorant of it:
|
|
191
|
+
|
|
192
|
+
- Supervisor config: `pinnedRoles: { orchestrator: ["<member>", ...] }` (ordered fallback
|
|
193
|
+
list, D5). Product-generic -- no member name in code.
|
|
194
|
+
- At startup (and on a periodic self-heal sweep), the supervisor reserves the active pinned
|
|
195
|
+
member server-side via the EXISTING `member_reservation` tool with a sentinel owner id, e.g.
|
|
196
|
+
`sprint_id: "supervisor-pin:orchestrator"`. No tool/schema change: `sprint_id` is already an
|
|
197
|
+
opaque string (member-reservation.ts:24-27), refresh-by-same-owner already succeeds
|
|
198
|
+
(member-reservation.ts:49-51), and `list_members`/dashboards already display `reservedBy`
|
|
199
|
+
(api.mjs:399-426).
|
|
200
|
+
- Per-sprint reservations EXCLUDE the pinned member: the injected orchestrator roleMap entry is
|
|
201
|
+
subtracted before `memberUnion` feeds the overlap guard and `ledger.claim` (api.mjs:442,
|
|
202
|
+
487, 539), and the child's `reserveAll` set (cli.mjs:723-729) already never contained roleMap
|
|
203
|
+
values, so no child-side change is needed for the supervisor path.
|
|
204
|
+
|
|
205
|
+
**Why not a shared/`exclusive:false` reservation TYPE in the ledger:** every ledger invariant
|
|
206
|
+
is sprint-lifecycle-shaped -- claim/release in lockstep with one sprint's launch/terminal
|
|
207
|
+
events (ledger.mjs:21-29), a `childPid` for restart PID-probe reconciliation (ledger.mjs:70-71),
|
|
208
|
+
release driven by watchdog/reconcile/Stop (`POST /api/reservations/:sprintId/force-release`,
|
|
209
|
+
dashboard.mjs:279-282 per escalate-to-llm-design.md:521). A permanent, sprint-less, shared
|
|
210
|
+
entry violates all of it: it has no pid to probe, must survive every reconciliation pass, must
|
|
211
|
+
be skipped by the overlap guard, and must never be force-released by the Stop path. That is
|
|
212
|
+
not a reservation with a flag -- it is a different object with a different lifecycle, and
|
|
213
|
+
encoding it as a ledger row means special-casing every ledger consumer (watchdog, reconcile,
|
|
214
|
+
readopt, dashboard, overlap guard, history). Config + sentinel touches exactly two seams
|
|
215
|
+
instead: launch-time injection/validation (api.mjs) and the server-side `reservedBy` record
|
|
216
|
+
that execute_prompt already enforces. The sentinel also gives cross-process reach the ledger
|
|
217
|
+
cannot: it protects against dispatches from CLI-launched sprints and manual sessions that never
|
|
218
|
+
consult this supervisor's ledger at all (the eft.26.1 hole, api.mjs:143-153).
|
|
219
|
+
|
|
220
|
+
### D2. Enforcement: how the pinned member is kept out of other roles
|
|
221
|
+
|
|
222
|
+
Three layers, cheapest first:
|
|
223
|
+
|
|
224
|
+
1. **Launch-time validation (authoritative, clear message).** In `launch()` (api.mjs:436),
|
|
225
|
+
after `roleMapResolver` (api.mjs:441): reject 400 if the pinned member appears in the
|
|
226
|
+
request's `members` list or in any roleMap value other than `orchestrator`, with an error
|
|
227
|
+
naming the member, the pin, and the fix ("member '<m>' is pinned as the shared orchestrator
|
|
228
|
+
and cannot be used as doer/reviewer/...; remove it from members/roleMap or change the pin").
|
|
229
|
+
This runs before `beforeLaunch`/`ledger.claim`, preserving the no-partial-claim contract
|
|
230
|
+
(api.mjs:35-36).
|
|
231
|
+
2. **Dispatch-time, for free.** The sentinel `reservedBy` makes execute_prompt reject ANY agent
|
|
232
|
+
dispatch to the pinned member from any sprint (owner `supervisor-pin:orchestrator` never
|
|
233
|
+
equals a caller `sprint_id`, execute-prompt.ts:536-543) -- while execute_command (the
|
|
234
|
+
orchestrator's entire post-D0 traffic) is unaffected because it performs no reservedBy check
|
|
235
|
+
(A2). This is exactly the asymmetry the proposal needs, and it already exists.
|
|
236
|
+
3. **Self-heal + doctor guard.** The supervisor periodically re-asserts the sentinel
|
|
237
|
+
(idempotent refresh, member-reservation.ts:49-51) so an accidental/manual force_release
|
|
238
|
+
cannot silently de-protect the member; the sprint-doctor remedy table gains the rule from
|
|
239
|
+
A4.1 (sentinel-prefixed owners are never force-releasable).
|
|
240
|
+
|
|
241
|
+
### D3. Serializing the shared beads clone (the genuinely new mechanism)
|
|
242
|
+
|
|
243
|
+
Generalize the supervisor's global dolt-push mutex into keyed mutexes: key = member name (the
|
|
244
|
+
current global push mutex becomes, or wraps, key `"<dolt-remote>"` -- unchanged behavior), and
|
|
245
|
+
a new per-member clone lock for the pinned orchestrator. The runner acquires the clone lock
|
|
246
|
+
around (a) `DoltSync.syncBefore(orchestratorMember, ...)` and (b) each orchestrator bd-mutation
|
|
247
|
+
bracket, whenever the orchestrator member is supervisor-pinned (the child knows via a flag the
|
|
248
|
+
supervisor injects alongside the roleMap, or simply: whenever `--service-url` is present it
|
|
249
|
+
asks). The existing lease/pid-reclaim/FIFO machinery (dolt-mutex.mjs:31-42) is reused verbatim;
|
|
250
|
+
only the keying changes. Pure reads (`bd list/show`) can stay unlocked initially -- reads
|
|
251
|
+
racing a writer are the same exposure the operator's interactive session already creates today
|
|
252
|
+
against its own clone.
|
|
253
|
+
|
|
254
|
+
Precondition spike: empirically test bd embedded-dolt behavior under concurrent same-clone
|
|
255
|
+
processes (two parallel `bd update`, `bd dolt pull` racing `bd update`). If bd's own locking
|
|
256
|
+
proves robust, the clone lock can be narrowed to the pull/push brackets only.
|
|
257
|
+
|
|
258
|
+
### D4. Auto-injection and the override question
|
|
259
|
+
|
|
260
|
+
Injection point: `launch()` in api.mjs, server-side, after `roleMapResolver` (api.mjs:441) and
|
|
261
|
+
before `memberUnion`/`beforeLaunch`/`spawnSprint` -- if the resolved roleMap has no
|
|
262
|
+
`orchestrator` key, inject `roleMap.orchestrator = [activePinnedMember]`; the spawner already
|
|
263
|
+
forwards roleMap into child argv untouched (spawner.mjs:223-225), and runner.js resolution
|
|
264
|
+
(4915-4920) then never falls back to `unmappedRoleFallbackPool[0]`. Because the pinned member
|
|
265
|
+
arrives only via roleMap (never `--members`), it is also structurally excluded from the
|
|
266
|
+
doer/reviewer fallback pools (runner.js:4910-4913 builds those from `physicalMembers`).
|
|
267
|
+
|
|
268
|
+
**Recommendation: soft pin -- an explicit `roleMap.orchestrator` from the caller WINS,** loudly
|
|
269
|
+
logged and echoed in the launch response (e.g. `orchestratorPinOverridden: true`). Reasons:
|
|
270
|
+
the incidents were caused by a silent implicit default, not by explicit choices -- injection
|
|
271
|
+
plus validation eliminates the silent path entirely; a hard pin would leave no way to launch
|
|
272
|
+
sprints during maintenance of the pinned member (defeating D6's fallback story); and an
|
|
273
|
+
explicitly-mapped override member flows into the NORMAL exclusive reservation path (union +
|
|
274
|
+
ledger + reserveAll), so it is safe under existing rules with zero new semantics. The escape
|
|
275
|
+
hatch is an explicit, logged, per-launch act -- precisely the property the implicit default
|
|
276
|
+
lacked.
|
|
277
|
+
|
|
278
|
+
CLI-direct launches (bin/cli.mjs without the supervisor) keep today's behavior; when
|
|
279
|
+
`--service-url` is provided the CLI SHOULD fetch the pin (D5's GET endpoint) and apply the same
|
|
280
|
+
default+validation. This deployment's practice is supervisor-API-only launches, so the CLI gap
|
|
281
|
+
is a documented follow-up, not a blocker.
|
|
282
|
+
|
|
283
|
+
### D5. Configuration surface (product-generic)
|
|
284
|
+
|
|
285
|
+
- **File**: `pinnedRoles` object in a supervisor config file in the existing data dir
|
|
286
|
+
(`FLEET_SE_DATA_DIR`, default `~/.apra-fleet-se`, ledger.mjs:177-181), e.g.
|
|
287
|
+
`supervisor-config.json`: `{ "pinnedRoles": { "orchestrator": ["memberA", "memberB"] } }`.
|
|
288
|
+
Generic shape (role -> ordered member list); only `orchestrator` is honored initially.
|
|
289
|
+
- **Flag**: `fleet-se serve --pin-orchestrator <member[,member...]>` overriding the file
|
|
290
|
+
(serve.mjs currently takes only `--port`, serve.mjs:52-62 -- room to grow).
|
|
291
|
+
- **API**: `GET /api/config/pinned-roles` (consumed by dashboard, launch form, and the CLI
|
|
292
|
+
follow-up) and `PUT` for runtime changes (re-runs sentinel reserve/release accordingly).
|
|
293
|
+
Dashboard shows the pin and its health.
|
|
294
|
+
- No member name appears anywhere in code; `fleet-dev` is purely this deployment's config value.
|
|
295
|
+
|
|
296
|
+
### D6. Single point of failure -- honest assessment and mitigation
|
|
297
|
+
|
|
298
|
+
Real regression risk: today, sprints accidentally spread orchestrator duty across their own
|
|
299
|
+
first members, so no single dead machine blocks ALL launches; a pin concentrates every launch
|
|
300
|
+
AND every in-flight sprint's bd reads/writes on one member. Mitigations, in order:
|
|
301
|
+
|
|
302
|
+
1. **Ordered fallback list** (D5): at launch, the supervisor health-probes the first pinned
|
|
303
|
+
member (cheap `execute_command` echo plus optionally a `bd dolt pull` probe, the same probe
|
|
304
|
+
shape `checkMemberTopology`'s synced mode already uses, cli.mjs:645) with a short timeout;
|
|
305
|
+
on failure it advances to the next configured member, re-pointing the sentinel. All
|
|
306
|
+
candidates failing => the launch is rejected 503 with an explicit message naming every
|
|
307
|
+
probed member and failure -- **fail loud at launch, never a silent mid-sprint hang**.
|
|
308
|
+
2. **In-flight sprints**: a pin dying mid-sprint is the same failure mode as any member dying
|
|
309
|
+
mid-sprint today (orchestrator included) -- not made worse, but concentrated. The
|
|
310
|
+
supervisor watchdog/dashboard should surface pin health continuously so the operator learns
|
|
311
|
+
about it from the dashboard, not from three simultaneously wedged sprints. Fits naturally
|
|
312
|
+
into sprint-doctor's diagnosis table later.
|
|
313
|
+
3. Accept the residual coupling consciously: the accidental-spread status quo bought
|
|
314
|
+
"availability" at the price of the exact correctness incidents that motivated this design.
|
|
315
|
+
Note the deployment guidance: pin the hub/local member (the machine the supervisor itself
|
|
316
|
+
runs on), which removes most network/SSH failure modes from the orchestrator path.
|
|
317
|
+
|
|
318
|
+
### D7. Audit/attribution
|
|
319
|
+
|
|
320
|
+
Push attribution already exists and survives: every D-push acquires the supervisor mutex with a
|
|
321
|
+
per-sprint id (runner.js:6502 et al., `sprintId: sprintMutexId` = the sprint branch,
|
|
322
|
+
runner.js:4674-4676), and the mutex logs holder identity on grant/reclaim/release
|
|
323
|
+
(dolt-mutex.mjs:139, 181). Each sprint's own log labels every orchestrator command it issued.
|
|
324
|
+
What IS lost: today, concurrent sprints' bd mutations land on different clones, so dolt-level
|
|
325
|
+
history is separable by machine; under the pin, one clone's dolt history interleaves all
|
|
326
|
+
sprints. The D3 clone lock plus per-sprint runner logs (every mutation is issued and logged by
|
|
327
|
+
exactly one sprint process) is sufficient traceability for v1 -- no new mechanism proposed. If
|
|
328
|
+
finer attribution is ever needed, it belongs in bd (an actor/annotation flag), not here.
|
|
329
|
+
|
|
330
|
+
### D8. Would this have prevented today's two incidents?
|
|
331
|
+
|
|
332
|
+
Both incidents (fleet-mac/k4sc, fleet-win-dev1/ot2z) had the same shape: single-member sprint,
|
|
333
|
+
orchestrator collapsed onto the dispatch target, and beads created/updated on the interactive
|
|
334
|
+
operator machine's clone were invisible because the resolved orchestrator's clone had never
|
|
335
|
+
pulled them -- and could not, since the operator clone had also never pushed them.
|
|
336
|
+
|
|
337
|
+
- **With the pin set to the member whose clone the interactive orchestrator session itself
|
|
338
|
+
uses** (this deployment: the hub/local member): both incidents are prevented at the source --
|
|
339
|
+
the sprint's scope reads run against the very clone where the beads were created; no push or
|
|
340
|
+
pull needs to have happened. This is the honest core of the fix for THIS deployment.
|
|
341
|
+
- **Product-generically, the gap relocates rather than vanishes**: if the operator's
|
|
342
|
+
interactive clone is NOT the pinned member, unpushed operator mutations are exactly as
|
|
343
|
+
invisible as before -- `DoltSync.syncBefore(pin)` at launch (runner.js:5545, readinessGate)
|
|
344
|
+
pulls the pin's clone, but a pull cannot fetch what was never pushed. So the previously
|
|
345
|
+
discussed launch-time pre-sync/freshness gate (verify the pin's clone is current against the
|
|
346
|
+
dolt remote, and surface staleness loudly) remains **complementary, not superseded** -- it is
|
|
347
|
+
the guard for the "discipline burden" now concentrated on one well-known member, which is
|
|
348
|
+
itself an improvement: one clone to keep honest instead of N accidental ones.
|
|
349
|
+
- **Dispatch-member sync is unaffected**: doers/reviewers keep their own per-dispatch D-pull
|
|
350
|
+
(runner.js:5026 inside the withGitSync bracket) and D-push; nothing in this design touches
|
|
351
|
+
the dispatch-side sync lattice.
|
|
352
|
+
|
|
353
|
+
---
|
|
354
|
+
|
|
355
|
+
## Recommendation
|
|
356
|
+
|
|
357
|
+
The idea is **sound in intent and correctly identifies that reservation exclusivity was never
|
|
358
|
+
the real safety mechanism for orchestrator-role dolt writes (the supervisor dolt-push mutex
|
|
359
|
+
was)** -- but it is **not implementable as stated**, for one hard reason found in the code: the
|
|
360
|
+
orchestrator role is not beads-only today. Branch-ensure checks the orchestrator's clone onto
|
|
361
|
+
the sprint branch every cycle, the requirements probe reads its working tree, and publish/abort
|
|
362
|
+
push from its local refs (A1). A shared pinned orchestrator without D0 would corrupt exactly
|
|
363
|
+
the cross-sprint isolation the reservation system exists to protect. With three modifications
|
|
364
|
+
the design is solid:
|
|
365
|
+
|
|
366
|
+
1. D0: make the orchestrator role beads-only (relocate the four git sites).
|
|
367
|
+
2. D1/D2: model the pin as supervisor config + `member_reservation` sentinel (no ledger type,
|
|
368
|
+
no MCP schema change), enforce at launch validation + the existing execute_prompt check.
|
|
369
|
+
3. D3: serialize shared-clone bd access via a per-member generalization of the existing
|
|
370
|
+
supervisor mutex, after a concurrency spike on bd embedded-dolt behavior.
|
|
371
|
+
|
|
372
|
+
Soft pin (explicit roleMap.orchestrator overrides, loudly) is recommended over hard pin. The
|
|
373
|
+
launch-time pre-sync/freshness gate stays on the roadmap as a complementary guard (D8).
|
|
374
|
+
|
|
375
|
+
### Bead sketches (NOT filed -- for operator decision)
|
|
376
|
+
|
|
377
|
+
1. **`refactor(fleet-sprint): make the orchestrator role beads-only`** -- Drop the orchestrator
|
|
378
|
+
from `branchEnsureMembers` when it is not also a dispatch member; relocate the
|
|
379
|
+
requirements-file probe/read to the planner member and the Publish-PR push/origin-probe/PR
|
|
380
|
+
call plus finalizeAbort git steps to a dispatch member (harvester/doer). Prerequisite for
|
|
381
|
+
any shared-orchestrator work; independently fixes the latent stale-local-ref publish push
|
|
382
|
+
for multi-member sprints.
|
|
383
|
+
2. **`spike(beads): embedded-dolt same-clone concurrency behavior`** -- Empirically establish
|
|
384
|
+
what bd 1.1.x embedded mode does under concurrent same-clone processes (parallel `bd
|
|
385
|
+
update`, `bd dolt pull` racing a write): clean lock-wait, transient error, or corruption.
|
|
386
|
+
Output decides whether bead 4's clone lock wraps all mutations or only the pull/push
|
|
387
|
+
brackets.
|
|
388
|
+
3. **`feat(supervisor): pinned-orchestrator config, sentinel reservation, and launch
|
|
389
|
+
injection`** -- `pinnedRoles` config file + `--pin-orchestrator` serve flag + GET/PUT API;
|
|
390
|
+
sentinel reserve via `member_reservation` with self-heal refresh; launch-time injection of
|
|
391
|
+
the default `roleMap.orchestrator` with health-probed fallback list and 503-on-all-dead;
|
|
392
|
+
400-validation rejecting the pinned member in any non-orchestrator role; pin excluded from
|
|
393
|
+
memberUnion/ledger claim; dashboard surfacing. Soft-pin override semantics per D4.
|
|
394
|
+
4. **`feat(supervisor+runner): per-member beads-clone lock for the shared orchestrator`** --
|
|
395
|
+
Generalize the dolt-push mutex to keyed (per-member) locks over the same lease/FIFO/pid
|
|
396
|
+
machinery; runner acquires the clone lock around orchestrator syncBefore and bd-mutation
|
|
397
|
+
brackets when the orchestrator is supervisor-pinned. Scope narrowed or widened by bead 2's
|
|
398
|
+
findings. Includes the sprint-doctor rule change: sentinel-owned reservations are never
|
|
399
|
+
force-releasable.
|