@apralabs/apra-fleet 0.3.6 → 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 +378 -252
- package/dist/agents/backlog-groomer.md +303 -0
- package/dist/agents/ci-watcher.md +13 -1
- package/dist/agents/deployer.md +66 -13
- package/dist/agents/doer.md +67 -8
- package/dist/agents/harvester.md +22 -3
- package/dist/agents/integ-test-runner.md +166 -60
- package/dist/agents/kb-reconciler.md +216 -0
- package/dist/agents/plan-reviewer.md +88 -18
- package/dist/agents/planner.md +182 -19
- package/dist/agents/regression-test-runner.md +234 -0
- package/dist/agents/reviewer.md +125 -9
- package/dist/agents/schemas/backlog-groomer-input.json +35 -0
- package/dist/agents/schemas/backlog-groomer-output.json +164 -0
- 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 +34 -0
- package/dist/agents/schemas/kb-reconciler-output.json +87 -0
- package/dist/agents/schemas/planner-output.json +65 -0
- package/dist/agents/schemas/regression-test-runner-input.json +15 -0
- package/dist/agents/schemas/regression-test-runner-output.json +50 -0
- package/dist/agents/schemas/reviewer-output.json +108 -7
- package/dist/cli/agent-transform.d.ts +1 -0
- package/dist/cli/agent-transform.d.ts.map +1 -1
- package/dist/cli/agent-transform.js +77 -0
- package/dist/cli/agent-transform.js.map +1 -1
- package/dist/cli/auth.d.ts +3 -0
- package/dist/cli/auth.d.ts.map +1 -1
- package/dist/cli/auth.js +181 -5
- package/dist/cli/auth.js.map +1 -1
- package/dist/cli/config.d.ts +5 -1
- package/dist/cli/config.d.ts.map +1 -1
- package/dist/cli/config.js +7 -1
- package/dist/cli/config.js.map +1 -1
- package/dist/cli/dolt-install.d.ts +91 -0
- package/dist/cli/dolt-install.d.ts.map +1 -0
- package/dist/cli/dolt-install.js +334 -0
- package/dist/cli/dolt-install.js.map +1 -0
- package/dist/cli/install-guard.d.ts +29 -0
- package/dist/cli/install-guard.d.ts.map +1 -0
- package/dist/cli/install-guard.js +153 -0
- package/dist/cli/install-guard.js.map +1 -0
- package/dist/cli/install.d.ts +45 -3
- package/dist/cli/install.d.ts.map +1 -1
- package/dist/cli/install.js +736 -109
- package/dist/cli/install.js.map +1 -1
- package/dist/cli/join.d.ts +12 -0
- package/dist/cli/join.d.ts.map +1 -0
- package/dist/cli/join.js +87 -0
- package/dist/cli/join.js.map +1 -0
- 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/register-member.d.ts +2 -0
- package/dist/cli/register-member.d.ts.map +1 -0
- package/dist/cli/register-member.js +193 -0
- package/dist/cli/register-member.js.map +1 -0
- package/dist/cli/restart.d.ts +2 -0
- package/dist/cli/restart.d.ts.map +1 -0
- package/dist/cli/restart.js +7 -0
- package/dist/cli/restart.js.map +1 -0
- package/dist/cli/spoke.d.ts +35 -0
- package/dist/cli/spoke.d.ts.map +1 -0
- package/dist/cli/spoke.js +212 -0
- package/dist/cli/spoke.js.map +1 -0
- package/dist/cli/start.d.ts +2 -0
- package/dist/cli/start.d.ts.map +1 -0
- package/dist/cli/start.js +92 -0
- package/dist/cli/start.js.map +1 -0
- package/dist/cli/status.d.ts +2 -0
- package/dist/cli/status.d.ts.map +1 -0
- package/dist/cli/status.js +83 -0
- package/dist/cli/status.js.map +1 -0
- package/dist/cli/stop.d.ts +2 -0
- package/dist/cli/stop.d.ts.map +1 -0
- package/dist/cli/stop.js +51 -0
- package/dist/cli/stop.js.map +1 -0
- package/dist/cli/uninstall.d.ts.map +1 -1
- package/dist/cli/uninstall.js +120 -9
- package/dist/cli/uninstall.js.map +1 -1
- package/dist/cli/update.d.ts.map +1 -1
- package/dist/cli/update.js +10 -1
- package/dist/cli/update.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/cli/workflow-assets.d.ts +37 -0
- package/dist/cli/workflow-assets.d.ts.map +1 -0
- package/dist/cli/workflow-assets.js +144 -0
- package/dist/cli/workflow-assets.js.map +1 -0
- package/dist/cli/workflow.d.ts +75 -0
- package/dist/cli/workflow.d.ts.map +1 -0
- package/dist/cli/workflow.js +397 -0
- package/dist/cli/workflow.js.map +1 -0
- 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/hub-service/activity.d.ts +30 -0
- package/dist/hub-service/activity.d.ts.map +1 -0
- package/dist/hub-service/activity.js +20 -0
- package/dist/hub-service/activity.js.map +1 -0
- package/dist/hub-service/audit-log.d.ts +19 -0
- package/dist/hub-service/audit-log.d.ts.map +1 -0
- package/dist/hub-service/audit-log.js +13 -0
- package/dist/hub-service/audit-log.js.map +1 -0
- package/dist/hub-service/db/pool.d.ts +19 -0
- package/dist/hub-service/db/pool.d.ts.map +1 -0
- package/dist/hub-service/db/pool.js +53 -0
- package/dist/hub-service/db/pool.js.map +1 -0
- package/dist/hub-service/enrollment.d.ts +29 -0
- package/dist/hub-service/enrollment.d.ts.map +1 -0
- package/dist/hub-service/enrollment.js +48 -0
- package/dist/hub-service/enrollment.js.map +1 -0
- package/dist/hub-service/envelope-routes.d.ts +46 -0
- package/dist/hub-service/envelope-routes.d.ts.map +1 -0
- package/dist/hub-service/envelope-routes.js +94 -0
- package/dist/hub-service/envelope-routes.js.map +1 -0
- package/dist/hub-service/handlers/installers.d.ts +14 -0
- package/dist/hub-service/handlers/installers.d.ts.map +1 -0
- package/dist/hub-service/handlers/installers.js +8 -0
- package/dist/hub-service/handlers/installers.js.map +1 -0
- package/dist/hub-service/http-server.d.ts +31 -0
- package/dist/hub-service/http-server.d.ts.map +1 -0
- package/dist/hub-service/http-server.js +711 -0
- package/dist/hub-service/http-server.js.map +1 -0
- package/dist/hub-service/hub-jwt.d.ts +30 -0
- package/dist/hub-service/hub-jwt.d.ts.map +1 -0
- package/dist/hub-service/hub-jwt.js +105 -0
- package/dist/hub-service/hub-jwt.js.map +1 -0
- package/dist/hub-service/jwt-revocation.d.ts +20 -0
- package/dist/hub-service/jwt-revocation.d.ts.map +1 -0
- package/dist/hub-service/jwt-revocation.js +18 -0
- package/dist/hub-service/jwt-revocation.js.map +1 -0
- package/dist/hub-service/machines.d.ts +16 -0
- package/dist/hub-service/machines.d.ts.map +1 -0
- package/dist/hub-service/machines.js +14 -0
- package/dist/hub-service/machines.js.map +1 -0
- package/dist/hub-service/main.d.ts +3 -0
- package/dist/hub-service/main.d.ts.map +1 -0
- package/dist/hub-service/main.js +64 -0
- package/dist/hub-service/main.js.map +1 -0
- package/dist/hub-service/member-tokens.d.ts +11 -0
- package/dist/hub-service/member-tokens.d.ts.map +1 -0
- package/dist/hub-service/member-tokens.js +49 -0
- package/dist/hub-service/member-tokens.js.map +1 -0
- package/dist/hub-service/member-view.d.ts +20 -0
- package/dist/hub-service/member-view.d.ts.map +1 -0
- package/dist/hub-service/member-view.js +76 -0
- package/dist/hub-service/member-view.js.map +1 -0
- package/dist/hub-service/members.d.ts +44 -0
- package/dist/hub-service/members.d.ts.map +1 -0
- package/dist/hub-service/members.js +25 -0
- package/dist/hub-service/members.js.map +1 -0
- package/dist/hub-service/presence.d.ts +40 -0
- package/dist/hub-service/presence.d.ts.map +1 -0
- package/dist/hub-service/presence.js +44 -0
- package/dist/hub-service/presence.js.map +1 -0
- package/dist/hub-service/project-view.d.ts +12 -0
- package/dist/hub-service/project-view.d.ts.map +1 -0
- package/dist/hub-service/project-view.js +34 -0
- package/dist/hub-service/project-view.js.map +1 -0
- package/dist/hub-service/projects.d.ts +48 -0
- package/dist/hub-service/projects.d.ts.map +1 -0
- package/dist/hub-service/projects.js +80 -0
- package/dist/hub-service/projects.js.map +1 -0
- package/dist/hub-service/relay-queue.d.ts +115 -0
- package/dist/hub-service/relay-queue.d.ts.map +1 -0
- package/dist/hub-service/relay-queue.js +148 -0
- package/dist/hub-service/relay-queue.js.map +1 -0
- package/dist/hub-service/session-jwt.d.ts +10 -0
- package/dist/hub-service/session-jwt.d.ts.map +1 -0
- package/dist/hub-service/session-jwt.js +69 -0
- package/dist/hub-service/session-jwt.js.map +1 -0
- package/dist/hub-service/usage.d.ts +40 -0
- package/dist/hub-service/usage.d.ts.map +1 -0
- package/dist/hub-service/usage.js +25 -0
- package/dist/hub-service/usage.js.map +1 -0
- package/dist/hub-service/users.d.ts +56 -0
- package/dist/hub-service/users.d.ts.map +1 -0
- package/dist/hub-service/users.js +72 -0
- package/dist/hub-service/users.js.map +1 -0
- package/dist/hub-service/workspaces.d.ts +20 -0
- package/dist/hub-service/workspaces.d.ts.map +1 -0
- package/dist/hub-service/workspaces.js +10 -0
- package/dist/hub-service/workspaces.js.map +1 -0
- package/dist/index.js +254 -132
- package/dist/index.js.map +1 -1
- package/dist/os/linux.d.ts +14 -0
- package/dist/os/linux.d.ts.map +1 -1
- package/dist/os/linux.js +80 -4
- package/dist/os/linux.js.map +1 -1
- package/dist/os/os-commands.d.ts +15 -0
- package/dist/os/os-commands.d.ts.map +1 -1
- package/dist/os/windows.d.ts +36 -0
- package/dist/os/windows.d.ts.map +1 -1
- package/dist/os/windows.js +74 -18
- package/dist/os/windows.js.map +1 -1
- package/dist/paths.d.ts +23 -0
- package/dist/paths.d.ts.map +1 -1
- package/dist/paths.js +29 -0
- package/dist/paths.js.map +1 -1
- package/dist/providers/agy.d.ts +20 -2
- package/dist/providers/agy.d.ts.map +1 -1
- package/dist/providers/agy.js +259 -21
- package/dist/providers/agy.js.map +1 -1
- package/dist/providers/claude.d.ts +16 -2
- package/dist/providers/claude.d.ts.map +1 -1
- package/dist/providers/claude.js +283 -16
- package/dist/providers/claude.js.map +1 -1
- package/dist/providers/codex.d.ts +13 -2
- package/dist/providers/codex.d.ts.map +1 -1
- package/dist/providers/codex.js +36 -6
- package/dist/providers/codex.js.map +1 -1
- package/dist/providers/copilot.d.ts +13 -2
- package/dist/providers/copilot.d.ts.map +1 -1
- package/dist/providers/copilot.js +34 -7
- 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 +13 -2
- package/dist/providers/gemini.d.ts.map +1 -1
- package/dist/providers/gemini.js +49 -5
- package/dist/providers/gemini.js.map +1 -1
- package/dist/providers/index.d.ts +1 -0
- package/dist/providers/index.d.ts.map +1 -1
- package/dist/providers/index.js +3 -0
- package/dist/providers/index.js.map +1 -1
- package/dist/providers/none.d.ts +61 -0
- package/dist/providers/none.d.ts.map +1 -0
- package/dist/providers/none.js +124 -0
- package/dist/providers/none.js.map +1 -0
- package/dist/providers/opencode.d.ts +14 -2
- package/dist/providers/opencode.d.ts.map +1 -1
- package/dist/providers/opencode.js +104 -4
- package/dist/providers/opencode.js.map +1 -1
- package/dist/providers/provider.d.ts +156 -1
- package/dist/providers/provider.d.ts.map +1 -1
- package/dist/providers/provider.js +54 -0
- package/dist/providers/provider.js.map +1 -1
- package/dist/services/agent-provisioner.d.ts +3 -3
- package/dist/services/agent-provisioner.d.ts.map +1 -1
- package/dist/services/agent-provisioner.js +11 -7
- package/dist/services/agent-provisioner.js.map +1 -1
- package/dist/services/auth-socket.d.ts.map +1 -1
- package/dist/services/auth-socket.js +2 -0
- package/dist/services/auth-socket.js.map +1 -1
- package/dist/services/budget-awareness.d.ts +130 -0
- package/dist/services/budget-awareness.d.ts.map +1 -0
- package/dist/services/budget-awareness.js +129 -0
- package/dist/services/budget-awareness.js.map +1 -0
- 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/cloud-sync.d.ts +35 -0
- package/dist/services/cloud-sync.d.ts.map +1 -0
- package/dist/services/cloud-sync.js +90 -0
- package/dist/services/cloud-sync.js.map +1 -0
- package/dist/services/context-admission.d.ts +82 -0
- package/dist/services/context-admission.d.ts.map +1 -0
- package/dist/services/context-admission.js +136 -0
- package/dist/services/context-admission.js.map +1 -0
- package/dist/services/event-bus.d.ts +27 -0
- package/dist/services/event-bus.d.ts.map +1 -0
- package/dist/services/event-bus.js +20 -0
- package/dist/services/event-bus.js.map +1 -0
- package/dist/services/file-chunker.d.ts +38 -0
- package/dist/services/file-chunker.d.ts.map +1 -0
- package/dist/services/file-chunker.js +63 -0
- package/dist/services/file-chunker.js.map +1 -0
- package/dist/services/file-transfer-relay.d.ts +55 -0
- package/dist/services/file-transfer-relay.d.ts.map +1 -0
- package/dist/services/file-transfer-relay.js +115 -0
- package/dist/services/file-transfer-relay.js.map +1 -0
- package/dist/services/github-app.d.ts.map +1 -1
- package/dist/services/github-app.js +12 -2
- package/dist/services/github-app.js.map +1 -1
- package/dist/services/http-transport.d.ts +25 -0
- package/dist/services/http-transport.d.ts.map +1 -0
- package/dist/services/http-transport.js +371 -0
- package/dist/services/http-transport.js.map +1 -0
- package/dist/services/hub-client.d.ts +69 -0
- package/dist/services/hub-client.d.ts.map +1 -0
- package/dist/services/hub-client.js +217 -0
- package/dist/services/hub-client.js.map +1 -0
- package/dist/services/jwt.d.ts +17 -0
- package/dist/services/jwt.d.ts.map +1 -0
- package/dist/services/jwt.js +70 -0
- package/dist/services/jwt.js.map +1 -0
- 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/known-sessions.d.ts +8 -0
- package/dist/services/known-sessions.d.ts.map +1 -0
- package/dist/services/known-sessions.js +40 -0
- package/dist/services/known-sessions.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/model-pricing.d.ts +36 -0
- package/dist/services/model-pricing.d.ts.map +1 -0
- package/dist/services/model-pricing.js +108 -0
- package/dist/services/model-pricing.js.map +1 -0
- package/dist/services/orphan-recovery.d.ts +59 -0
- package/dist/services/orphan-recovery.d.ts.map +1 -0
- package/dist/services/orphan-recovery.js +122 -0
- package/dist/services/orphan-recovery.js.map +1 -0
- package/dist/services/pending-responses.d.ts +23 -0
- package/dist/services/pending-responses.d.ts.map +1 -0
- package/dist/services/pending-responses.js +52 -0
- package/dist/services/pending-responses.js.map +1 -0
- 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/registry.d.ts +4 -1
- package/dist/services/registry.d.ts.map +1 -1
- package/dist/services/registry.js +3 -0
- package/dist/services/registry.js.map +1 -1
- package/dist/services/relay-context.d.ts +23 -0
- package/dist/services/relay-context.d.ts.map +1 -0
- package/dist/services/relay-context.js +8 -0
- package/dist/services/relay-context.js.map +1 -0
- package/dist/services/relay-executor.d.ts +68 -0
- package/dist/services/relay-executor.d.ts.map +1 -0
- package/dist/services/relay-executor.js +70 -0
- package/dist/services/relay-executor.js.map +1 -0
- package/dist/services/relay-request.d.ts +65 -0
- package/dist/services/relay-request.d.ts.map +1 -0
- package/dist/services/relay-request.js +129 -0
- package/dist/services/relay-request.js.map +1 -0
- package/dist/services/relay-strategy.d.ts +19 -0
- package/dist/services/relay-strategy.d.ts.map +1 -0
- package/dist/services/relay-strategy.js +111 -0
- package/dist/services/relay-strategy.js.map +1 -0
- package/dist/services/service-manager/index.d.ts +5 -0
- package/dist/services/service-manager/index.d.ts.map +1 -0
- package/dist/services/service-manager/index.js +66 -0
- package/dist/services/service-manager/index.js.map +1 -0
- package/dist/services/service-manager/linux.d.ts +10 -0
- package/dist/services/service-manager/linux.d.ts.map +1 -0
- package/dist/services/service-manager/linux.js +97 -0
- package/dist/services/service-manager/linux.js.map +1 -0
- package/dist/services/service-manager/macos.d.ts +10 -0
- package/dist/services/service-manager/macos.d.ts.map +1 -0
- package/dist/services/service-manager/macos.js +94 -0
- package/dist/services/service-manager/macos.js.map +1 -0
- package/dist/services/service-manager/types.d.ts +18 -0
- package/dist/services/service-manager/types.d.ts.map +1 -0
- package/dist/services/service-manager/types.js +5 -0
- package/dist/services/service-manager/types.js.map +1 -0
- package/dist/services/service-manager/windows.d.ts +10 -0
- package/dist/services/service-manager/windows.d.ts.map +1 -0
- package/dist/services/service-manager/windows.js +73 -0
- package/dist/services/service-manager/windows.js.map +1 -0
- package/dist/services/session-registry.d.ts +70 -0
- package/dist/services/session-registry.d.ts.map +1 -0
- package/dist/services/session-registry.js +91 -0
- package/dist/services/session-registry.js.map +1 -0
- package/dist/services/singleton.d.ts +15 -0
- package/dist/services/singleton.d.ts.map +1 -0
- package/dist/services/singleton.js +98 -0
- package/dist/services/singleton.js.map +1 -0
- package/dist/services/sprint-coordination.d.ts +168 -0
- package/dist/services/sprint-coordination.d.ts.map +1 -0
- package/dist/services/sprint-coordination.js +564 -0
- package/dist/services/sprint-coordination.js.map +1 -0
- package/dist/services/ssh.d.ts.map +1 -1
- package/dist/services/ssh.js +70 -3
- package/dist/services/ssh.js.map +1 -1
- 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 -33
- 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 +187 -12
- package/dist/services/stall/stall-detector.js.map +1 -1
- package/dist/services/stall/stall-poller.d.ts +50 -0
- package/dist/services/stall/stall-poller.d.ts.map +1 -1
- package/dist/services/stall/stall-poller.js +268 -18
- package/dist/services/stall/stall-poller.js.map +1 -1
- package/dist/services/strategy.d.ts.map +1 -1
- package/dist/services/strategy.js +57 -7
- package/dist/services/strategy.js.map +1 -1
- package/dist/services/substitution-engine.d.ts +20 -0
- package/dist/services/substitution-engine.d.ts.map +1 -0
- package/dist/services/substitution-engine.js +92 -0
- package/dist/services/substitution-engine.js.map +1 -0
- package/dist/services/task-cleanup.d.ts.map +1 -1
- package/dist/services/task-cleanup.js +1 -9
- package/dist/services/task-cleanup.js.map +1 -1
- package/dist/services/token-issuer.d.ts +47 -0
- package/dist/services/token-issuer.d.ts.map +1 -0
- package/dist/services/token-issuer.js +63 -0
- package/dist/services/token-issuer.js.map +1 -0
- package/dist/services/tool-registry.d.ts +3 -0
- package/dist/services/tool-registry.d.ts.map +1 -0
- package/dist/services/tool-registry.js +225 -0
- package/dist/services/tool-registry.js.map +1 -0
- package/dist/services/user-config.d.ts +14 -0
- package/dist/services/user-config.d.ts.map +1 -1
- package/dist/services/user-config.js +55 -0
- package/dist/services/user-config.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/vcs/types.d.ts +44 -0
- package/dist/services/vcs/types.d.ts.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 +114 -0
- package/dist/skills/pm/beads.md +6 -0
- package/dist/skills/pm/cost.md +3 -0
- package/dist/skills/pm/doer-reviewer-loop.md +3 -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 +250 -2
- package/dist/tools/check-status.js.map +1 -1
- package/dist/tools/child-id-allocator.d.ts +45 -0
- package/dist/tools/child-id-allocator.d.ts.map +1 -0
- package/dist/tools/child-id-allocator.js +62 -0
- package/dist/tools/child-id-allocator.js.map +1 -0
- package/dist/tools/cloud-control.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 +38 -4
- package/dist/tools/compose-permissions.d.ts.map +1 -1
- package/dist/tools/compose-permissions.js +295 -33
- package/dist/tools/compose-permissions.js.map +1 -1
- package/dist/tools/dolt-push-mutex.d.ts +44 -0
- package/dist/tools/dolt-push-mutex.d.ts.map +1 -0
- package/dist/tools/dolt-push-mutex.js +83 -0
- package/dist/tools/dolt-push-mutex.js.map +1 -0
- package/dist/tools/execute-command.d.ts +13 -1
- package/dist/tools/execute-command.d.ts.map +1 -1
- package/dist/tools/execute-command.js +108 -21
- package/dist/tools/execute-command.js.map +1 -1
- package/dist/tools/execute-prompt.d.ts +84 -12
- package/dist/tools/execute-prompt.d.ts.map +1 -1
- package/dist/tools/execute-prompt.js +1191 -88
- package/dist/tools/execute-prompt.js.map +1 -1
- package/dist/tools/get-member-model-pricing.d.ts +21 -0
- package/dist/tools/get-member-model-pricing.d.ts.map +1 -0
- package/dist/tools/get-member-model-pricing.js +29 -0
- package/dist/tools/get-member-model-pricing.js.map +1 -0
- 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/list-members.d.ts.map +1 -1
- package/dist/tools/list-members.js +39 -7
- package/dist/tools/list-members.js.map +1 -1
- package/dist/tools/member-detail.d.ts +1 -1
- package/dist/tools/member-detail.d.ts.map +1 -1
- package/dist/tools/member-detail.js +16 -2
- package/dist/tools/member-detail.js.map +1 -1
- package/dist/tools/member-reservation.d.ts +29 -0
- package/dist/tools/member-reservation.d.ts.map +1 -0
- package/dist/tools/member-reservation.js +71 -0
- package/dist/tools/member-reservation.js.map +1 -0
- 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/provision-vcs-auth.d.ts +7 -7
- package/dist/tools/provision-vcs-auth.js +1 -1
- package/dist/tools/provision-vcs-auth.js.map +1 -1
- package/dist/tools/register-member.d.ts +20 -5
- package/dist/tools/register-member.d.ts.map +1 -1
- package/dist/tools/register-member.js +174 -6
- package/dist/tools/register-member.js.map +1 -1
- package/dist/tools/remove-member.d.ts +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 +33 -0
- package/dist/tools/report-status.d.ts.map +1 -0
- package/dist/tools/report-status.js +45 -0
- package/dist/tools/report-status.js.map +1 -0
- package/dist/tools/respond-to-message.d.ts +21 -0
- package/dist/tools/respond-to-message.d.ts.map +1 -0
- package/dist/tools/respond-to-message.js +23 -0
- package/dist/tools/respond-to-message.js.map +1 -0
- 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/send-files.d.ts +3 -0
- package/dist/tools/send-files.d.ts.map +1 -1
- package/dist/tools/send-files.js +88 -8
- package/dist/tools/send-files.js.map +1 -1
- package/dist/tools/send-message.d.ts +27 -0
- package/dist/tools/send-message.d.ts.map +1 -0
- package/dist/tools/send-message.js +46 -0
- package/dist/tools/send-message.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/shutdown-server.d.ts +2 -0
- package/dist/tools/shutdown-server.d.ts.map +1 -1
- package/dist/tools/shutdown-server.js +19 -0
- package/dist/tools/shutdown-server.js.map +1 -1
- package/dist/tools/update-member.d.ts +11 -8
- package/dist/tools/update-member.d.ts.map +1 -1
- package/dist/tools/update-member.js +36 -2
- package/dist/tools/update-member.js.map +1 -1
- package/dist/types.d.ts +16 -3
- package/dist/types.d.ts.map +1 -1
- package/dist/utils/agent-helpers.d.ts +2 -1
- package/dist/utils/agent-helpers.d.ts.map +1 -1
- package/dist/utils/agent-helpers.js +7 -2
- package/dist/utils/agent-helpers.js.map +1 -1
- package/dist/utils/pid-helpers.d.ts +15 -0
- package/dist/utils/pid-helpers.d.ts.map +1 -1
- package/dist/utils/pid-helpers.js +23 -0
- package/dist/utils/pid-helpers.js.map +1 -1
- package/dist/utils/process-utils.d.ts +3 -0
- package/dist/utils/process-utils.d.ts.map +1 -0
- package/dist/utils/process-utils.js +42 -0
- package/dist/utils/process-utils.js.map +1 -0
- package/dist/utils/prompt-errors.d.ts +2 -1
- package/dist/utils/prompt-errors.d.ts.map +1 -1
- package/dist/utils/prompt-errors.js +13 -3
- 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/utils/workspace-trust.d.ts +24 -0
- package/dist/utils/workspace-trust.d.ts.map +1 -0
- package/dist/utils/workspace-trust.js +35 -0
- package/dist/utils/workspace-trust.js.map +1 -0
- package/dist/workflows/auto-sprint.js +994 -91
- package/package.json +40 -9
- package/packages/apra-fleet-client/package.json +26 -0
- package/packages/apra-fleet-client/src/client/api.mjs +510 -0
- package/packages/apra-fleet-client/src/client/client.mjs +146 -0
- package/packages/apra-fleet-client/src/client/errors.mjs +71 -0
- package/packages/apra-fleet-client/src/client/factory.mjs +65 -0
- package/packages/apra-fleet-client/src/client/server-resolution.mjs +265 -0
- package/packages/apra-fleet-client/src/client/transport.mjs +327 -0
- package/packages/apra-fleet-se/apra-pm/agents/backlog-groomer.md +303 -0
- package/packages/apra-fleet-se/apra-pm/agents/ci-watcher.md +101 -0
- package/packages/apra-fleet-se/apra-pm/agents/deployer.md +151 -0
- package/packages/apra-fleet-se/apra-pm/agents/doer.md +259 -0
- package/packages/apra-fleet-se/apra-pm/agents/harvester.md +188 -0
- package/packages/apra-fleet-se/apra-pm/agents/integ-test-runner.md +332 -0
- package/packages/apra-fleet-se/apra-pm/agents/kb-reconciler.md +216 -0
- package/packages/apra-fleet-se/apra-pm/agents/plan-reviewer.md +201 -0
- package/packages/apra-fleet-se/apra-pm/agents/planner.md +322 -0
- package/packages/apra-fleet-se/apra-pm/agents/regression-test-runner.md +234 -0
- package/packages/apra-fleet-se/apra-pm/agents/reviewer.md +275 -0
- package/packages/apra-fleet-se/apra-pm/agents/schemas/backlog-groomer-input.json +35 -0
- package/packages/apra-fleet-se/apra-pm/agents/schemas/backlog-groomer-output.json +164 -0
- package/packages/apra-fleet-se/apra-pm/agents/schemas/ci-watcher-input.json +26 -0
- package/packages/apra-fleet-se/apra-pm/agents/schemas/ci-watcher-output.json +18 -0
- package/packages/apra-fleet-se/apra-pm/agents/schemas/deployer-input.json +19 -0
- package/packages/apra-fleet-se/apra-pm/agents/schemas/deployer-output.json +17 -0
- package/packages/apra-fleet-se/apra-pm/agents/schemas/doer-input.json +25 -0
- package/packages/apra-fleet-se/apra-pm/agents/schemas/doer-output.json +82 -0
- package/packages/apra-fleet-se/apra-pm/agents/schemas/harvester-input.json +31 -0
- package/packages/apra-fleet-se/apra-pm/agents/schemas/harvester-output.json +75 -0
- package/packages/apra-fleet-se/apra-pm/agents/schemas/integ-test-runner-input.json +20 -0
- package/packages/apra-fleet-se/apra-pm/agents/schemas/integ-test-runner-output.json +61 -0
- package/packages/apra-fleet-se/apra-pm/agents/schemas/kb-reconciler-output.json +87 -0
- package/packages/apra-fleet-se/apra-pm/agents/schemas/plan-reviewer-input.json +15 -0
- package/packages/apra-fleet-se/apra-pm/agents/schemas/plan-reviewer-output.json +30 -0
- package/packages/apra-fleet-se/apra-pm/agents/schemas/planner-output.json +65 -0
- package/packages/apra-fleet-se/apra-pm/agents/schemas/regression-test-runner-input.json +15 -0
- package/packages/apra-fleet-se/apra-pm/agents/schemas/regression-test-runner-output.json +50 -0
- package/packages/apra-fleet-se/apra-pm/agents/schemas/reviewer-input.json +25 -0
- package/packages/apra-fleet-se/apra-pm/agents/schemas/reviewer-output.json +135 -0
- package/packages/apra-fleet-se/apra-pm/skills/pm/SKILL.md +402 -0
- package/packages/apra-fleet-se/apra-pm/skills/pm/beads.md +148 -0
- package/packages/apra-fleet-se/apra-pm/skills/pm/cost.md +157 -0
- package/packages/apra-fleet-se/apra-pm/skills/pm/doer-reviewer-loop.md +300 -0
- package/packages/apra-fleet-se/apra-pm/skills/pm/fleet-addendum.md +127 -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/apra-pm/skills/pm/simple-sprint.md +65 -0
- package/packages/apra-fleet-se/apra-pm/skills/pm/sprint.md +327 -0
- package/packages/apra-fleet-se/apra-pm/skills/pm/worktrees.md +92 -0
- package/packages/apra-fleet-se/apra-pm/version.json +3 -0
- package/packages/apra-fleet-se/bin/cli.mjs +864 -0
- package/packages/apra-fleet-se/bin/serve.mjs +395 -0
- package/packages/apra-fleet-se/fleet-sprint/conflict-ladder.mjs +178 -0
- package/packages/apra-fleet-se/fleet-sprint/contracts.mjs +940 -0
- package/packages/apra-fleet-se/fleet-sprint/dispatch-safety-guard.mjs +177 -0
- package/packages/apra-fleet-se/fleet-sprint/docs/README.md +191 -0
- package/packages/apra-fleet-se/fleet-sprint/docs/coach-role-design.md +23 -0
- 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/fleet-sprint-diagram.md +94 -0
- package/packages/apra-fleet-se/fleet-sprint/docs/shared-orchestrator-reservation-design.md +399 -0
- package/packages/apra-fleet-se/fleet-sprint/docs/stabilization-log.md +1125 -0
- package/packages/apra-fleet-se/fleet-sprint/dolt-literal-guard.mjs +72 -0
- package/packages/apra-fleet-se/fleet-sprint/dolt-settle.mjs +972 -0
- package/packages/apra-fleet-se/fleet-sprint/dolt-sync.mjs +1310 -0
- package/packages/apra-fleet-se/fleet-sprint/errors.mjs +616 -0
- package/packages/apra-fleet-se/fleet-sprint/full-db-fetch-guard.mjs +118 -0
- package/packages/apra-fleet-se/fleet-sprint/runner.js +10747 -0
- package/packages/apra-fleet-se/fleet-sprint/skills/fleet-sprint-cli/SKILL.md +114 -0
- package/packages/apra-fleet-se/fleet-sprint/skills/fleet-supervisor/SKILL.md +350 -0
- package/packages/apra-fleet-se/fleet-sprint/sprint-lock.mjs +140 -0
- package/packages/apra-fleet-se/fleet-sprint/sprint-progress.mjs +101 -0
- package/packages/apra-fleet-se/fleet-sprint/vcs-module.mjs +435 -0
- package/packages/apra-fleet-se/fleet-sprint/vcs-providers/azure-devops.mjs +68 -0
- package/packages/apra-fleet-se/fleet-sprint/vcs-providers/bitbucket.mjs +53 -0
- package/packages/apra-fleet-se/fleet-sprint/vcs-providers/dolt.mjs +146 -0
- package/packages/apra-fleet-se/fleet-sprint/vcs-providers/generic-git.mjs +176 -0
- package/packages/apra-fleet-se/fleet-sprint/vcs-providers/github.mjs +235 -0
- package/packages/apra-fleet-se/fleet-sprint/vcs-providers/index.mjs +218 -0
- package/packages/apra-fleet-se/fleet-sprint/viewer-extensions.mjs +942 -0
- package/packages/apra-fleet-se/package.json +29 -0
- package/packages/apra-fleet-se/workflow.json +1 -0
- package/packages/apra-fleet-workflow/package.json +30 -0
- package/packages/apra-fleet-workflow/src/viewer/command-output-cap.mjs +112 -0
- package/packages/apra-fleet-workflow/src/viewer/debounced-writer.mjs +153 -0
- package/packages/apra-fleet-workflow/src/viewer/html-utils.mjs +31 -0
- package/packages/apra-fleet-workflow/src/viewer/index.mjs +1439 -0
- package/packages/apra-fleet-workflow/src/viewer/lean-state.mjs +237 -0
- package/packages/apra-fleet-workflow/src/viewer/run-state-paths.mjs +130 -0
- package/packages/apra-fleet-workflow/src/viewer/run-title.mjs +60 -0
- package/packages/apra-fleet-workflow/src/viewer/sprint-state-paths.mjs +29 -0
- package/packages/apra-fleet-workflow/src/workflow/engine.mjs +200 -0
- package/packages/apra-fleet-workflow/src/workflow/errors.mjs +146 -0
- package/packages/apra-fleet-workflow/src/workflow/index.mjs +1727 -0
- package/packages/apra-fleet-workflow/src/workflow/journal.mjs +291 -0
- package/packages/apra-fleet-workflow/src/workflow/pricing.mjs +99 -0
- package/packages/apra-fleet-workflow/src/workflow/vetting.mjs +111 -0
- package/scripts/agy-transcript-reader.js +1 -0
- package/scripts/fleet-statusline.sh +17 -13
- package/skills/fleet/SKILL.md +37 -2
- package/skills/fleet/beads.md +14 -7
- package/skills/fleet/knowledge-agent.md +66 -0
- package/skills/fleet/permissions.md +76 -2
- package/skills/fleet/profiles/base-dev.json +11 -1
- package/skills/fleet/profiles/base-reviewer.json +9 -1
- package/skills/fleet/profiles/node.json +2 -2
- package/skills/fleet/profiles/tag-kb-reconciler.json +20 -0
- package/version.json +1 -1
- package/scripts/agy-settings-merge.js +0 -27
- /package/{dist → packages/apra-fleet-se/apra-pm}/agents/_shared/GRAPH-SEMANTICS.md +0 -0
|
@@ -0,0 +1,1482 @@
|
|
|
1
|
+
# Dolt sync redesign: from a 3-tier recovery ladder to one deterministic settle step
|
|
2
|
+
|
|
3
|
+
Status: BEING IMPLEMENTED on branch `fix/dolt-settle-recovery` (written
|
|
4
|
+
2026-08-13). Per-part implementation status is tracked in "Implementation
|
|
5
|
+
status" immediately below; Part 4's verification table is the live-run record.
|
|
6
|
+
See `dolt-manual-recovery-verified.md` for the live-verified mechanical spec
|
|
7
|
+
(exact flags, exact commands, exact OS-specific detachment technique) this
|
|
8
|
+
design's `settle()` step is built from.
|
|
9
|
+
|
|
10
|
+
### Implementation status
|
|
11
|
+
|
|
12
|
+
| Part | Item | Status |
|
|
13
|
+
|------|------|--------|
|
|
14
|
+
| 3.1-3.2, 5 | `fleet-sprint/dolt-settle.mjs` + `test/dolt-settle.test.mjs` | DONE |
|
|
15
|
+
| 3.2 step 4 | `labels` set-union (real INSERT, live-read uniqueness key) | DONE |
|
|
16
|
+
| 2.4, 3.2 | settle wired at the push AND pull/readiness divergence terminals | DONE |
|
|
17
|
+
| 2.4 | old ladder (`dolt-recovery*.mjs`, tier-2 runbook) retired | DONE (deleted) |
|
|
18
|
+
| 3.4 | mutex lease renewal while held | DONE |
|
|
19
|
+
| 3.3 | supervisor orphaned-sql-server sweep | DONE |
|
|
20
|
+
| 5.5 V2 | `dolt-manual-recovery-verified.md` step 1 corrected to the pinned installer | DONE |
|
|
21
|
+
| 6 | `scripts/dolt-settle-integration.mjs` | DONE |
|
|
22
|
+
| 4 | live 3-OS verification | DONE (all 3 PASS, 2026-08-13 -- see Part 4) |
|
|
23
|
+
| 8 | beads audit executed | DONE (2026-08-13 -- see Part 8 dispositions) |
|
|
24
|
+
|
|
25
|
+
Produced by a deep architecture review (apra-fleet-ga61, apra-fleet-5mqg
|
|
26
|
+
evidence chains, full reads of dolt-sync.mjs / dolt-recovery*.mjs / runner.js /
|
|
27
|
+
dolt-mutex.mjs, plus upstream beads sync semantics) after the user explicitly
|
|
28
|
+
rejected the existing multi-tier ladder as an acceptable end state: "I am not
|
|
29
|
+
interested in a multi-tier ladder, I just need a reliable system which works
|
|
30
|
+
100% of time."
|
|
31
|
+
|
|
32
|
+
---
|
|
33
|
+
|
|
34
|
+
## Part 1 -- how the current system actually works (verified against code)
|
|
35
|
+
|
|
36
|
+
### 1.1 G-push and D-push
|
|
37
|
+
|
|
38
|
+
Two orthogonal sync planes per fleet member:
|
|
39
|
+
|
|
40
|
+
- **G-pull/G-push** -- the member's git code checkout against the shared
|
|
41
|
+
sprint branch (`syncMemberBefore`/`syncMemberAfter`, `runner.js` ~868-1012).
|
|
42
|
+
- **D-pull/D-push** -- the member's beads Dolt clone against the shared Dolt
|
|
43
|
+
remote (`refs/dolt/data`), exclusively in `dolt-sync.mjs` (the declared
|
|
44
|
+
"SINGLE permitted dolt command surface").
|
|
45
|
+
|
|
46
|
+
`syncMemberAfterOrdered()` (`runner.js:1094-1145`) runs **G-push strictly
|
|
47
|
+
before D-push**. If G-push throws, D-push is skipped and the error rethrown --
|
|
48
|
+
pushing a bead close to the shared DB while the code justifying it never left
|
|
49
|
+
the member's checkout would advertise an **unreachable close**. D-push here is
|
|
50
|
+
`fatal: true` for the mirrored reason.
|
|
51
|
+
|
|
52
|
+
D-push conflict policy (`dolt-sync.mjs:108-114, 670-721`): first-successful-
|
|
53
|
+
pusher-wins. A rejected push gets exactly one reconcile `bd dolt pull` and one
|
|
54
|
+
re-push; a divergence outliving that becomes `DoltDivergedError` -> terminal
|
|
55
|
+
`BEADS_SYNC_CONFLICT` (after the recovery ladder).
|
|
56
|
+
|
|
57
|
+
### 1.2 What `dolt_push_mutex` does and does not prevent
|
|
58
|
+
|
|
59
|
+
`src/supervisor/dolt-mutex.mjs`: a supervisor-process, in-memory, FIFO mutex,
|
|
60
|
+
60s lease, pid-liveness reclaim, HTTP long-poll. Prevents two sprints pushing
|
|
61
|
+
in overlapping windows -- serializes remote-ref updates.
|
|
62
|
+
|
|
63
|
+
**Does NOT prevent row-level conflicts**, because conflicts are created at
|
|
64
|
+
local **commit** time, during agent dispatches, entirely outside the mutex:
|
|
65
|
+
|
|
66
|
+
1. Members A and B both D-pull; both clones sit at remote commit X.
|
|
67
|
+
2. A's dispatched agent commits a change to `bead-1` locally.
|
|
68
|
+
3. Concurrently, B's dispatched agent commits a *different* change to the same
|
|
69
|
+
`bead-1` locally (even a disjoint field -- Dolt conflicts are row-level,
|
|
70
|
+
not cell-level, in bd's current embedded mode).
|
|
71
|
+
4. A acquires the mutex, pushes, releases. Remote now has A's version.
|
|
72
|
+
5. B acquires the mutex (FIFO), push rejected, runs its one reconcile pull --
|
|
73
|
+
Dolt hits a **row-level conflict**. `bd` auto-aborts the merge, B's clone
|
|
74
|
+
is now wedged (one unresolved conflict blocks all pull/push for that
|
|
75
|
+
clone), `DoltDivergedError` surfaces.
|
|
76
|
+
|
|
77
|
+
Additional real gaps in the mutex itself:
|
|
78
|
+
- **Lease expiry with a live holder:** `reclaimExpired()` force-evicts at 60s
|
|
79
|
+
even if the pid is alive, and `doltPushAfter` never calls `renew()`. A
|
|
80
|
+
push+reconcile (or, today, a Tier-2 dispatch with `timeout_s: 1800` run
|
|
81
|
+
*while the mutex is nominally held*) loses mutual exclusion 60s in.
|
|
82
|
+
- **In-memory only** -- a supervisor restart forgets holder and queue.
|
|
83
|
+
- **Non-participants** -- an operator's own clone, manual `bd dolt push`, or a
|
|
84
|
+
sprint run without a supervisor bypass the mutex entirely.
|
|
85
|
+
|
|
86
|
+
### 1.3 Conflict shapes actually possible
|
|
87
|
+
|
|
88
|
+
Single-row `issues` conflicts dominate, but are not the only shape:
|
|
89
|
+
`issues` multi-row, `dependencies` (audit-only vs semantic), `labels`
|
|
90
|
+
(set-union), `comments`/`events` (append-only union), machine-local
|
|
91
|
+
metadata/config rows (trivially `theirs`), and **schema-level forks** from
|
|
92
|
+
mixed `bd` binary versions across members -- upstream documents this last one
|
|
93
|
+
as a genuine anti-pattern that can make a clone *permanently* unmergeable; no
|
|
94
|
+
row-data algorithm fixes it, it must be prevented operationally (fleet-wide
|
|
95
|
+
version pinning).
|
|
96
|
+
|
|
97
|
+
Upstream `bd` itself (newer than this fleet's pin) now ships
|
|
98
|
+
`TryAutoResolveMergeConflicts` with a per-table deterministic rulebook,
|
|
99
|
+
including per-field last-writer-wins by `updated_at` for `issues` -- direct
|
|
100
|
+
corroboration that a total mechanical rule for this data model exists and is
|
|
101
|
+
what the vendor converged on independently.
|
|
102
|
+
|
|
103
|
+
### 1.4 The recovery ladder as it ACTUALLY behaves in production
|
|
104
|
+
|
|
105
|
+
- **Path A never runs.** `runner.js:1142` builds the ladder without injecting
|
|
106
|
+
`sql`/`spawnSqlServer`/`readMetadata`/`writeMetadata`. `recoverDoltConflictPathA`
|
|
107
|
+
throws its precondition guard immediately every time (confirmed live across
|
|
108
|
+
4 incidents in 2 sprint logs). Path A's careful reversible-teardown code is
|
|
109
|
+
production-dead.
|
|
110
|
+
- **Path B never runs.** Hard-disabled (`enablePathB: false`) for a correct
|
|
111
|
+
reason: this bracket wraps an arbitrary multi-command dispatch with no
|
|
112
|
+
single `pendingMutation` to replay -- firing Path B here would silently
|
|
113
|
+
discard the dispatch's bead writes and report success.
|
|
114
|
+
- **Tier 2 is the only tier that ever executes** -- dispatches a real LLM
|
|
115
|
+
agent with `dolt-tier2-runbook.md`, with **no code-guaranteed rollback**:
|
|
116
|
+
step 6 (teardown/revert) is the last item of an instruction list, not a
|
|
117
|
+
`finally`. Proven live (apra-fleet-5mqg): an agent hit its 50-turn budget
|
|
118
|
+
immediately after *announcing* it was about to do step 6, having already
|
|
119
|
+
used a raw ephemeral server to resolve a conflict, leaving the member with
|
|
120
|
+
an orphaned server-mode data dir -- which in turn made the apra-fleet-ga61
|
|
121
|
+
network-client credential-prompt bug reachable in the first place.
|
|
122
|
+
- **Structural zero-success:** `recoverDoltConflict` returns
|
|
123
|
+
`{ ok: false, tier: 'tier-2', escalated: true }` by construction -- Tier 2
|
|
124
|
+
only dispatches, it never verifies. Every divergence reaching the terminal
|
|
125
|
+
ends in `BEADS_SYNC_CONFLICT` for that streak, 100% of the time, even when
|
|
126
|
+
the dispatched agent successfully fixes the clone (the fix only helps some
|
|
127
|
+
*later* bracket).
|
|
128
|
+
- **The pull side has no recovery at all.** A clone wedged by a previous
|
|
129
|
+
failed reconcile hard-aborts the *next* sprint at the readiness gate, with
|
|
130
|
+
no recovery seam.
|
|
131
|
+
|
|
132
|
+
### 1.5 Which runbook is used by which actor
|
|
133
|
+
|
|
134
|
+
- `dolt-tier2-runbook.md` -- read by the dispatched Tier-2 LLM agent (wired
|
|
135
|
+
via `DEFAULT_TIER2_RUNBOOK_PATH`). The only runbook any code reads.
|
|
136
|
+
- `docs/dolt-operator-conflict-runbook.md` -- human operator debugging their
|
|
137
|
+
own clone by hand. Zero code references.
|
|
138
|
+
- `dolt-manual-recovery-verified.md` -- live-verified mechanical spec, not yet
|
|
139
|
+
referenced by code (this design makes it so, in spirit: `dolt-settle.mjs` is
|
|
140
|
+
its executable form).
|
|
141
|
+
|
|
142
|
+
---
|
|
143
|
+
|
|
144
|
+
## Part 2 -- the redesign: one deterministic settle step, no ladder
|
|
145
|
+
|
|
146
|
+
### 2.1 Why NOT full centralization (single always-on Dolt server, no per-member clones)
|
|
147
|
+
|
|
148
|
+
Rejected, decisively:
|
|
149
|
+
|
|
150
|
+
1. It would move 100% of beads traffic onto bd's **least-proven** code path.
|
|
151
|
+
apra-fleet-ga61 is a real, still-partially-open bug specifically in bd's
|
|
152
|
+
*network-client* mode on Windows (credential-prompt landmines triggered by
|
|
153
|
+
explicit `--user`/`--password`). That path is dormant today because the
|
|
154
|
+
fleet runs embedded. Centralizing makes the buggy path the *only* path, for
|
|
155
|
+
every command, on every member, forever.
|
|
156
|
+
2. It converts a publish-time dependency into a total-availability dependency.
|
|
157
|
+
Today a supervisor outage only delays pushes (local clones stay safe by
|
|
158
|
+
design). Under centralization, a network blip fails every `bd` read/write
|
|
159
|
+
on every member mid-dispatch -- worse than a rare, mechanically-resolvable
|
|
160
|
+
conflict, for a fleet of long-running agents on separate machines over SSH.
|
|
161
|
+
3. Migration cost is fleet-wide and cross-cutting (auth/TLS provisioning,
|
|
162
|
+
backup story for the sole canonical clone, decommissioning the entire
|
|
163
|
+
clone/sync surface with both systems live during migration).
|
|
164
|
+
|
|
165
|
+
(If the fleet ever gets an HA supervisor and all members on one reliable LAN,
|
|
166
|
+
this is a legitimate long-term end state -- just not the reliable-today
|
|
167
|
+
answer.)
|
|
168
|
+
|
|
169
|
+
### 2.2 THE RECOMMENDATION: a single, total, deterministic `settle()` step
|
|
170
|
+
|
|
171
|
+
Replace the entire ladder with **one conflict-settlement function that is
|
|
172
|
+
total over row-level conflicts** -- no gates, no allowlist, no escalation
|
|
173
|
+
path, no LLM, no runbook dispatch. Its correctness rule is beads' own
|
|
174
|
+
published merge semantics (the same rules upstream `TryAutoResolveMergeConflicts`
|
|
175
|
+
encodes), executed via the exact live-verified mechanics in
|
|
176
|
+
`dolt-manual-recovery-verified.md`.
|
|
177
|
+
|
|
178
|
+
**The settle algorithm**, per conflicted table, read from
|
|
179
|
+
`dolt_conflicts_<table>`'s `base_*`/`our_*`/`their_*` columns:
|
|
180
|
+
|
|
181
|
+
- **`issues`** (modify/modify): per-field merge -- a field changed by only one
|
|
182
|
+
side keeps that side; a field changed by both sides resolves by
|
|
183
|
+
**last-writer-wins on `updated_at`** (bd stamps this on every mutation);
|
|
184
|
+
`updated_at` itself merges to `max(ours, theirs)`. Tiebreak on equal/
|
|
185
|
+
unparseable `updated_at`: **theirs** (consistent with the existing
|
|
186
|
+
first-successful-pusher-wins policy -- the remote side already published).
|
|
187
|
+
A fixed tiebreak is what makes this total.
|
|
188
|
+
- **`issues` add/add** on the same id: identical rows keep; otherwise the same
|
|
189
|
+
per-field rule.
|
|
190
|
+
- **`issues` delete/modify**: modify wins (beads closes rather than deletes;
|
|
191
|
+
genuine deletes are near-nonexistent, so this is not a live risk).
|
|
192
|
+
- **`labels`**: set-union. **`comments`/`events`**: append-only union (keep
|
|
193
|
+
both, never drop). **`dependencies`**: audit-only diffs -> theirs; semantic
|
|
194
|
+
diffs -> per-field LWW, same tiebreak. Machine-local metadata/config rows:
|
|
195
|
+
theirs.
|
|
196
|
+
- **Any other table**: generic per-field LWW-by-`updated_at` where the column
|
|
197
|
+
exists, else theirs. **The function never returns "cannot resolve."** Its
|
|
198
|
+
only other possible outcome is an *operational* error (server wouldn't
|
|
199
|
+
start, a SQL statement failed) -- handled like any other infra command
|
|
200
|
+
failure via the existing degraded/fatal policy, not as an escalation tier.
|
|
201
|
+
|
|
202
|
+
**The mechanism**, straight from the verified doc, with two deliberate
|
|
203
|
+
hardening choices:
|
|
204
|
+
|
|
205
|
+
1. Read the real data dir from `bd dolt status` live -- never hardcode
|
|
206
|
+
`.beads/embeddeddolt` (closes the per-project-mode/orphaned-directory risk
|
|
207
|
+
apra-fleet-5mqg's live validation surfaced).
|
|
208
|
+
2. Spawn the ephemeral `dolt sql-server` genuinely detached: WMI
|
|
209
|
+
`Win32_Process.Create` on Windows (verified live -- `Start-Process` and
|
|
210
|
+
`schtasks` both fail to survive the SSH session), `nohup ... & disown` on
|
|
211
|
+
POSIX. Record the pid.
|
|
212
|
+
3. **Do not flip `.beads/metadata.json` or route `bd` through the server at
|
|
213
|
+
all.** Drive the raw `dolt` client directly at the socket: `--no-tls`
|
|
214
|
+
*before* `--host`/`--port` (order-sensitive), never pass `--user`/
|
|
215
|
+
`--password` (passing `--user=root` explicitly is what triggers the
|
|
216
|
+
interactive-credential-prompt failure; omitting both flags authenticates
|
|
217
|
+
silently as root with the documented empty-password default), `USE beads;`
|
|
218
|
+
first. This is what the Tier-2 transcript actually did successfully, and it
|
|
219
|
+
**eliminates the entire apra-fleet-5mqg rollback class outright** -- bd's
|
|
220
|
+
own routing state is never touched, so there is nothing to revert.
|
|
221
|
+
4. `SET @@dolt_allow_commit_conflicts=1; CALL DOLT_MERGE('origin/main');` ->
|
|
222
|
+
read `dolt_conflicts` and each `dolt_conflicts_<table>` -> apply the
|
|
223
|
+
rulebook via `UPDATE`s + `CALL DOLT_CONFLICTS_RESOLVE(...)` per table ->
|
|
224
|
+
`CALL DOLT_COMMIT(...)` -> verify `dolt_conflicts` is empty.
|
|
225
|
+
5. `bd dolt pull` then `bd dolt push` to republish.
|
|
226
|
+
6. **Teardown in a real code `try/finally`:** kill the recorded pid, verify
|
|
227
|
+
the port closed, verify `bd dolt status` reports embedded -- on every path,
|
|
228
|
+
including throw. Belt-and-suspenders: a supervisor sweep that kills any
|
|
229
|
+
orphaned loopback `dolt sql-server` older than N minutes on a member
|
|
230
|
+
(closes apra-fleet-5mqg even against an orchestrator-process kill).
|
|
231
|
+
|
|
232
|
+
### 2.3 What stays, fixed in detail
|
|
233
|
+
|
|
234
|
+
- Keep the D-pull/D-push brackets, first-pusher-wins reconcile, and the mutex
|
|
235
|
+
(it still guarantees at most one loser per race and orderly remote-ref
|
|
236
|
+
updates) -- but fix the lease hole: `doltPushAfter` should `renew()` on an
|
|
237
|
+
interval while held, or release before settle and re-acquire for the
|
|
238
|
+
republish push.
|
|
239
|
+
- Wire settle at **both** divergence terminals: the push terminal (where the
|
|
240
|
+
ladder sits today) *and* the pull/readiness-gate terminal (currently
|
|
241
|
+
recovery-free -- a wedged clone at sprint start must self-heal, not abort).
|
|
242
|
+
- Optional accelerator, not a tier: if a newer pinned `bd` ships
|
|
243
|
+
`TryAutoResolveMergeConflicts`, use it as the reconcile-pull so most
|
|
244
|
+
conflicts never even reach settle. Settle remains the single total terminal
|
|
245
|
+
either way.
|
|
246
|
+
- The one shape settle cannot fix -- a schema fork from mixed `bd` versions --
|
|
247
|
+
is *prevented*, not resolved: enforce the fleet-wide `bd` version pin at
|
|
248
|
+
member provisioning/readiness-gate time. (Full centralization would have the
|
|
249
|
+
same constraint, so this is not a point against settle.)
|
|
250
|
+
|
|
251
|
+
### 2.4 Migration plan (concrete files/functions)
|
|
252
|
+
|
|
253
|
+
1. **New** `packages/apra-fleet-se/fleet-sprint/dolt-settle.mjs`:
|
|
254
|
+
`settleDoltConflicts(member, { command, log })` implementing the above
|
|
255
|
+
end-to-end through the injected `command()` -- binary check/winget
|
|
256
|
+
install, WMI/nohup spawn, `dolt --no-tls ... sql -q ...`, kill.
|
|
257
|
+
Unit-testable exactly like Path A was (scripted mock `command()`). Port
|
|
258
|
+
Path A's `finally` discipline; delete its gates/allowlist.
|
|
259
|
+
2. **`runner.js`**: at `syncMemberAfterOrdered` (line 1142) replace
|
|
260
|
+
`buildDoltRecoveryLadder(...)` with the settle callback; drop `agent`/
|
|
261
|
+
`resolveConflictModel` threading for dolt recovery. Wire the same settle
|
|
262
|
+
into the pre-dispatch D-pull and readiness-gate paths.
|
|
263
|
+
3. **`dolt-sync.mjs`**: `surfaceDivergence` invokes settle (rename
|
|
264
|
+
`opts.recover` -> `opts.settle`; a settle success IS a verified recovery
|
|
265
|
+
because settle itself re-pushes and verifies -- unlike Tier 2, it can
|
|
266
|
+
return `ok: true`). Add the equivalent terminal inside `doltPullBefore`.
|
|
267
|
+
Add mutex `renew` handling around long holds.
|
|
268
|
+
4. **`src/supervisor/dolt-mutex.mjs` + `createHttpDoltPushMutexClient`
|
|
269
|
+
(`runner.js`)**: expose/consume `renew`; add the orphaned-sql-server sweep
|
|
270
|
+
to the supervisor.
|
|
271
|
+
5. **Delete/retire**: `dolt-recovery-path-b.mjs`, `dolt-recovery-tier2.mjs`
|
|
272
|
+
(the dispatch machinery, `buildDoltRecoveryLadder`, wedged-state prompt),
|
|
273
|
+
Path A's gate machinery in `dolt-recovery.mjs` (file superseded by
|
|
274
|
+
`dolt-settle.mjs`). `errors.mjs` unchanged -- `DoltDivergedError` survives
|
|
275
|
+
only as "settle itself had an operational failure," already handled by the
|
|
276
|
+
existing degraded/fatal taxonomy.
|
|
277
|
+
6. **Close the loop on the P0s**: ga61's client landmines are permanently
|
|
278
|
+
encoded in settle's fixed flag set (and bd stays embedded, keeping ga61's
|
|
279
|
+
trigger dormant); apra-fleet-5mqg is closed structurally (no metadata flip
|
|
280
|
+
+ try/finally kill + supervisor sweep).
|
|
281
|
+
|
|
282
|
+
### 2.5 The runbook question, answered explicitly
|
|
283
|
+
|
|
284
|
+
**The Tier-2 runbook/LLM-dispatch concept is obsolete under this redesign.**
|
|
285
|
+
Do not revise `dolt-tier2-runbook.md` -- retire it (delete, or mark
|
|
286
|
+
historical). Its content should not be "improved" with the verified material,
|
|
287
|
+
because its premise -- an LLM executing a teardown-critical procedure from
|
|
288
|
+
prose -- is the exact defect apra-fleet-5mqg proved. Instead:
|
|
289
|
+
|
|
290
|
+
- `dolt-manual-recovery-verified.md` becomes the specification `dolt-settle.mjs`
|
|
291
|
+
encodes, and remains the human copy-paste fallback.
|
|
292
|
+
- `docs/dolt-operator-conflict-runbook.md` stays for humans on their own
|
|
293
|
+
clones, updated to point at the verified doc and to note that fleet members
|
|
294
|
+
now self-heal via settle rather than escalating to a human/LLM.
|
|
295
|
+
|
|
296
|
+
### Critical files for implementation
|
|
297
|
+
|
|
298
|
+
- `packages/apra-fleet-se/fleet-sprint/dolt-sync.mjs`
|
|
299
|
+
- `packages/apra-fleet-se/fleet-sprint/runner.js`
|
|
300
|
+
- `packages/apra-fleet-se/fleet-sprint/dolt-recovery.mjs` (superseded by the
|
|
301
|
+
new `dolt-settle.mjs`)
|
|
302
|
+
- `packages/apra-fleet-se/fleet-sprint/dolt-recovery-tier2.mjs` (retired,
|
|
303
|
+
along with `dolt-recovery-path-b.mjs`)
|
|
304
|
+
- `packages/apra-fleet-se/fleet-sprint/docs/dolt-manual-recovery-verified.md`
|
|
305
|
+
(the spec the settle code encodes)
|
|
306
|
+
|
|
307
|
+
---
|
|
308
|
+
|
|
309
|
+
## Part 3 -- implementation-level detail
|
|
310
|
+
|
|
311
|
+
This section exists so implementation does not require re-deriving anything
|
|
312
|
+
from Parts 1/2. Every function signature, SQL template, and OS-specific
|
|
313
|
+
command below is meant to be copied close to verbatim into
|
|
314
|
+
`dolt-settle.mjs`.
|
|
315
|
+
|
|
316
|
+
### 3.1 Module shape
|
|
317
|
+
|
|
318
|
+
```js
|
|
319
|
+
// packages/apra-fleet-se/fleet-sprint/dolt-settle.mjs
|
|
320
|
+
|
|
321
|
+
/**
|
|
322
|
+
* @typedef {Object} SettleOpts
|
|
323
|
+
* @property {(cmd: string, opts?: object) => Promise<{stdout: string, stderr: string, exitCode: number}>} command
|
|
324
|
+
* Injected shell-command runner, member-scoped (same shape as every other
|
|
325
|
+
* dolt-sync.mjs/runner.js call site already uses -- NOT a raw child_process
|
|
326
|
+
* call; must route through whatever member-dispatch mechanism the caller
|
|
327
|
+
* already has, exactly like Path A's `command` opt did).
|
|
328
|
+
* @property {(msg: string) => void} [log]
|
|
329
|
+
* @property {string} [remote='origin']
|
|
330
|
+
* @property {string} [branch='main']
|
|
331
|
+
* @property {number} [portRangeStart=13300] Ephemeral port search start.
|
|
332
|
+
* @property {number} [portRangeEnd=13400]
|
|
333
|
+
* @property {string} [doltWindowsPath='C:\\Program Files\\Dolt\\bin\\dolt.exe']
|
|
334
|
+
* @property {string} [doltPosixPath='dolt']
|
|
335
|
+
*/
|
|
336
|
+
|
|
337
|
+
/**
|
|
338
|
+
* Total, deterministic settle: resolves EVERY row-level Dolt conflict shape
|
|
339
|
+
* this data model can produce, no gates, no escalation. Only throws on a
|
|
340
|
+
* genuine operational failure (server wouldn't start, an individual SQL
|
|
341
|
+
* statement errored for a reason unrelated to conflict content) -- callers
|
|
342
|
+
* treat that exactly like any other infra command failure (existing
|
|
343
|
+
* degraded/fatal taxonomy in dolt-sync.mjs), NOT as a ladder tier.
|
|
344
|
+
*
|
|
345
|
+
* @param {string} member
|
|
346
|
+
* @param {SettleOpts} opts
|
|
347
|
+
* @returns {Promise<{ ok: true, resolvedTables: string[], resolvedRowCounts: Record<string, number> }>}
|
|
348
|
+
*/
|
|
349
|
+
export async function settleDoltConflicts(member, opts) { /* see 3.4 */ }
|
|
350
|
+
```
|
|
351
|
+
|
|
352
|
+
`settleDoltConflicts` REPLACES `recoverDoltConflict`/`buildDoltRecoveryLadder`
|
|
353
|
+
as the one function `dolt-sync.mjs` and `runner.js` call at every divergence
|
|
354
|
+
terminal. There is no `tier` return field because there is no tier -- callers
|
|
355
|
+
branch only on the promise resolving vs throwing.
|
|
356
|
+
|
|
357
|
+
### 3.2 Step-by-step with exact commands (cross-referencing
|
|
358
|
+
`dolt-manual-recovery-verified.md`, which remains the authoritative source for
|
|
359
|
+
any flag/ordering detail not repeated here)
|
|
360
|
+
|
|
361
|
+
**Step 0 -- resolve the real data dir (never hardcode).**
|
|
362
|
+
```js
|
|
363
|
+
const { stdout } = await command('bd dolt status');
|
|
364
|
+
// stdout line 2 is " Data: <path>" when embedded, or a host:port line when
|
|
365
|
+
// server. Parse both; if server mode is already active, target THAT
|
|
366
|
+
// host:port instead of starting a second ephemeral server (see 3.5).
|
|
367
|
+
```
|
|
368
|
+
|
|
369
|
+
**Step 1 -- ensure `dolt` binary present. CORRECTED (see Part 5): do NOT use
|
|
370
|
+
`winget`/`apt`/`brew`.** This repo already has a portable, version-pinned
|
|
371
|
+
installer wired into `apra-fleet install` -- `src/cli/dolt-install.ts`,
|
|
372
|
+
`downloadAndExtractDolt(BIN_DIR)` -- which lands the binary at
|
|
373
|
+
`path.join(BIN_DIR, platform === 'win32' ? 'dolt.exe' : 'dolt')`
|
|
374
|
+
(`BIN_DIR` from `src/cli/config.ts`, a fleet-managed dir, never system PATH).
|
|
375
|
+
Every fleet member that has run `apra-fleet install` already has this binary
|
|
376
|
+
at that exact path, at the exact pinned version. `dolt-settle.mjs` step 1
|
|
377
|
+
should simply be:
|
|
378
|
+
```js
|
|
379
|
+
const doltPath = path.join(BIN_DIR, process.platform === 'win32' ? 'dolt.exe' : 'dolt');
|
|
380
|
+
if (!(await command(`Test-Path '${doltPath}'` /* or `test -x` on POSIX */)).stdout.includes('True' /* or exit 0 */)) {
|
|
381
|
+
// reuse the SAME installer the fleet already ships, not an OS package manager:
|
|
382
|
+
await downloadAndExtractDolt(BIN_DIR);
|
|
383
|
+
}
|
|
384
|
+
```
|
|
385
|
+
This also sidesteps the PATH problem entirely: today's manual verification
|
|
386
|
+
(3.6) hit a real snag where a `winget`-installed binary was invisible to a
|
|
387
|
+
freshly spawned process because PATH is only re-read on next shell start --
|
|
388
|
+
`BIN_DIR` is an absolute path passed explicitly, no PATH involved at all.
|
|
389
|
+
|
|
390
|
+
**Step 2 -- pick an ephemeral loopback port and spawn, genuinely detached.**
|
|
391
|
+
Port selection: try ports sequentially in `[portRangeStart, portRangeEnd)`,
|
|
392
|
+
probing with a plain TCP connect-refused check before use (do not trust
|
|
393
|
+
"probably free" -- a stale ephemeral server from an earlier interrupted run,
|
|
394
|
+
exactly the apra-fleet-5mqg failure class, may still be listening; if the
|
|
395
|
+
probe succeeds, treat that as a live server. Do NOT assume it is safe to
|
|
396
|
+
reuse -- see 3.5 for the disposition).
|
|
397
|
+
|
|
398
|
+
```powershell
|
|
399
|
+
# Windows -- WMI Win32_Process.Create, the ONLY verified-working detachment.
|
|
400
|
+
# Start-Process and schtasks BOTH fail (die with the SSH session / never run
|
|
401
|
+
# without an interactive logon session, respectively) -- do not use either.
|
|
402
|
+
$result = Invoke-CimMethod -ClassName Win32_Process -MethodName Create -Arguments @{
|
|
403
|
+
CommandLine = '"<doltWindowsPath>" sql-server --host 127.0.0.1 --port <port> --data-dir <dataDir>'
|
|
404
|
+
CurrentDirectory = '<memberRepoRoot>'
|
|
405
|
+
}
|
|
406
|
+
# $result.ReturnValue must be 0; $result.ProcessId is the pid to record.
|
|
407
|
+
```
|
|
408
|
+
```bash
|
|
409
|
+
# POSIX
|
|
410
|
+
nohup dolt sql-server --host 127.0.0.1 --port <port> --data-dir <dataDir> \
|
|
411
|
+
> /tmp/dolt-settle-<member>-<port>.log 2>&1 &
|
|
412
|
+
echo "PID:$!"
|
|
413
|
+
disown
|
|
414
|
+
```
|
|
415
|
+
Verify up before proceeding (poll, do not sleep-and-hope): retry a TCP connect
|
|
416
|
+
to `127.0.0.1:<port>` up to ~10x over 5s; separately tail the redirected log
|
|
417
|
+
for `"Server ready. Accepting connections."` as a secondary confirmation.
|
|
418
|
+
|
|
419
|
+
**Step 3 -- connect and merge. Exact working invocation (landmines from live
|
|
420
|
+
verification baked in -- CAVEAT: verified against `dolt 1.86.3` via a manual
|
|
421
|
+
`winget` install, NOT this repo's pinned `v2.2.0`. Flag parsing/behavior can
|
|
422
|
+
differ across a version gap that large. Re-verify every landmine below
|
|
423
|
+
against the actual pinned `BIN_DIR` binary as the FIRST step of the manual
|
|
424
|
+
OS testing pass (3.6/Part 4) before trusting any of it in real code.):**
|
|
425
|
+
```
|
|
426
|
+
dolt --no-tls --host=127.0.0.1 --port=<port> sql -q "<SQL>"
|
|
427
|
+
```
|
|
428
|
+
- `--no-tls` MUST precede `--host`/`--port` (order-sensitive parser).
|
|
429
|
+
- Do NOT pass `--user` or `--password` at all, in any form. Passing
|
|
430
|
+
`--user=root` explicitly switches the client into an interactive
|
|
431
|
+
credential-resolution path that fails non-interactively
|
|
432
|
+
(`Failed to parse credentials: The handle is invalid` -- the apra-fleet-ga61
|
|
433
|
+
symptom, reproduced and root-caused live). Omitting both authenticates
|
|
434
|
+
silently as root with the documented empty-password default.
|
|
435
|
+
- On Windows/PowerShell specifically, an empty-string arg like
|
|
436
|
+
`--password ''` can be silently DROPPED by PowerShell's native-argument
|
|
437
|
+
passing, shifting the next flag into becoming its value -- moot here since
|
|
438
|
+
the flag is omitted entirely, but do not "fix" this by adding
|
|
439
|
+
`--password=''` back; that reintroduces the credential-prompt bug.
|
|
440
|
+
- Run from `<dataDir>/beads` OR pass `--data-dir` again on the client
|
|
441
|
+
invocation; either works, but be consistent (the verified doc used cwd).
|
|
442
|
+
- Always lead every query with `USE beads;` -- the database name is not
|
|
443
|
+
implied by `--data-dir` once connected over SQL.
|
|
444
|
+
|
|
445
|
+
```sql
|
|
446
|
+
USE beads;
|
|
447
|
+
SET @@dolt_allow_commit_conflicts = 1;
|
|
448
|
+
CALL DOLT_MERGE('<remote>/<branch>');
|
|
449
|
+
SELECT `table` FROM dolt_conflicts; -- enumerate every conflicted table, no gate/allowlist
|
|
450
|
+
```
|
|
451
|
+
|
|
452
|
+
**Step 4 -- resolve each conflicted table with the settle rulebook.** For each
|
|
453
|
+
table name returned by `dolt_conflicts`, query its `dolt_conflicts_<table>`
|
|
454
|
+
view (columns: `base_*`, `our_*`, `their_*`, plus PK columns) and apply:
|
|
455
|
+
|
|
456
|
+
```sql
|
|
457
|
+
-- issues: per-field LWW by updated_at, `theirs` tiebreak on equal/null.
|
|
458
|
+
-- Computed as one UPDATE using CASE per contested field, then resolve.
|
|
459
|
+
UPDATE issues i
|
|
460
|
+
JOIN dolt_conflicts_issues c ON i.id = c.our_id
|
|
461
|
+
SET
|
|
462
|
+
i.title = CASE WHEN c.their_updated_at >= c.our_updated_at THEN c.their_title ELSE c.our_title END,
|
|
463
|
+
i.status = CASE WHEN c.their_updated_at >= c.our_updated_at THEN c.their_status ELSE c.our_status END,
|
|
464
|
+
i.priority = CASE WHEN c.their_updated_at >= c.our_updated_at THEN c.their_priority ELSE c.our_priority END,
|
|
465
|
+
-- ... one CASE per mutable column; enumerate ALL of them, do not special-case
|
|
466
|
+
-- "which fields changed" -- CASE on updated_at recency is total and simpler
|
|
467
|
+
-- than diffing base vs our vs their per field, and produces the same result
|
|
468
|
+
-- for a single-field change (the unchanged side's CASE branches are no-ops).
|
|
469
|
+
i.updated_at = GREATEST(c.our_updated_at, c.their_updated_at)
|
|
470
|
+
WHERE i.id IN (SELECT our_id FROM dolt_conflicts_issues);
|
|
471
|
+
|
|
472
|
+
CALL DOLT_CONFLICTS_RESOLVE('--theirs', 'issues');
|
|
473
|
+
-- NOTE: --theirs here is safe DESPITE the LWW UPDATE above having already
|
|
474
|
+
-- run, because DOLT_CONFLICTS_RESOLVE operates on the conflict markers, not
|
|
475
|
+
-- content -- the UPDATE already rewrote the working-set row to the correct
|
|
476
|
+
-- merged content; --theirs/--ours only decides which side's row shape
|
|
477
|
+
-- (columns/existence) wins the conflict-resolution bookkeeping itself. If a
|
|
478
|
+
-- prototype shows this interacts differently in practice, this is the one
|
|
479
|
+
-- step to validate most carefully in the manual OS testing pass (3.6) --
|
|
480
|
+
-- flag it explicitly if `--theirs` clobbers the LWW-merged row.
|
|
481
|
+
|
|
482
|
+
-- labels: set-union (add/add is the only realistic labels conflict shape).
|
|
483
|
+
INSERT INTO labels (issue_id, label)
|
|
484
|
+
SELECT our_issue_id, our_label FROM dolt_conflicts_labels
|
|
485
|
+
WHERE NOT EXISTS (
|
|
486
|
+
SELECT 1 FROM labels l WHERE l.issue_id = dolt_conflicts_labels.our_issue_id
|
|
487
|
+
AND l.label = dolt_conflicts_labels.our_label
|
|
488
|
+
)
|
|
489
|
+
UNION
|
|
490
|
+
SELECT their_issue_id, their_label FROM dolt_conflicts_labels
|
|
491
|
+
WHERE NOT EXISTS (
|
|
492
|
+
SELECT 1 FROM labels l WHERE l.issue_id = dolt_conflicts_labels.their_issue_id
|
|
493
|
+
AND l.label = dolt_conflicts_labels.their_label
|
|
494
|
+
);
|
|
495
|
+
CALL DOLT_CONFLICTS_RESOLVE('--theirs', 'labels');
|
|
496
|
+
|
|
497
|
+
-- comments / events: append-only union -- both rows always kept, never
|
|
498
|
+
-- dropped. If comment/event ids collide (shouldn't, they're generated with
|
|
499
|
+
-- enough entropy per bd's schema, but do not assume): keep theirs, re-insert
|
|
500
|
+
-- ours under a synthesized new id rather than discarding it.
|
|
501
|
+
CALL DOLT_CONFLICTS_RESOLVE('--theirs', 'comments');
|
|
502
|
+
CALL DOLT_CONFLICTS_RESOLVE('--theirs', 'events');
|
|
503
|
+
-- (append-only tables essentially never generate a REAL conflict needing
|
|
504
|
+
-- content merge -- the theirs/ours split only ever concerns row survival,
|
|
505
|
+
-- and both survive by construction upstream; verify this empirically in 3.6.)
|
|
506
|
+
|
|
507
|
+
-- dependencies: audit-columns-only diff -> theirs; semantic (dep_type) diff
|
|
508
|
+
-- -> per-field LWW, same tiebreak as issues.
|
|
509
|
+
UPDATE dependencies d
|
|
510
|
+
JOIN dolt_conflicts_dependencies c ON d.id = c.our_id
|
|
511
|
+
SET d.dep_type = CASE WHEN c.their_updated_at >= c.our_updated_at THEN c.their_dep_type ELSE c.our_dep_type END
|
|
512
|
+
WHERE c.our_dep_type != c.their_dep_type;
|
|
513
|
+
CALL DOLT_CONFLICTS_RESOLVE('--theirs', 'dependencies');
|
|
514
|
+
|
|
515
|
+
-- machine-local metadata/config rows (e.g. kv.memory.*, dolt_auto_push_*):
|
|
516
|
+
-- always theirs, no merge logic needed.
|
|
517
|
+
CALL DOLT_CONFLICTS_RESOLVE('--theirs', '<config-table>');
|
|
518
|
+
|
|
519
|
+
-- ANY table not explicitly enumerated above (the generic fallback --
|
|
520
|
+
-- guarantees totality): generic per-field LWW-by-updated_at where the
|
|
521
|
+
-- column exists on that table, else theirs outright. Implement this as a
|
|
522
|
+
-- catch-all after the named-table branches, driven off `information_schema`
|
|
523
|
+
-- to discover whether `updated_at` exists on the conflicted table, rather
|
|
524
|
+
-- than hardcoding a fixed table list -- this is what makes the function
|
|
525
|
+
-- genuinely total rather than "total over the tables we thought of."
|
|
526
|
+
```
|
|
527
|
+
|
|
528
|
+
```sql
|
|
529
|
+
CALL DOLT_COMMIT('-m', 'settle: automated deterministic conflict resolution');
|
|
530
|
+
SELECT COUNT(*) FROM dolt_conflicts; -- MUST be 0 before proceeding; if not, throw (operational failure, not "unresolvable")
|
|
531
|
+
SELECT commit_hash, committer, message FROM dolt_log LIMIT 5; -- sanity: both sides' history present
|
|
532
|
+
```
|
|
533
|
+
|
|
534
|
+
**Step 5 -- CORRECTED ORDER (see Part 7.2): tear the ephemeral server down
|
|
535
|
+
BEFORE republishing, not after.** Embedded-mode `bd` (used by `bd dolt pull`/
|
|
536
|
+
`bd dolt push` below) must open the SAME data dir the ephemeral server still
|
|
537
|
+
holds under Dolt's per-directory exclusive-access lock; running the republish
|
|
538
|
+
while the server is still up hits that lock and fails or falls back
|
|
539
|
+
read-only. So: once step 4's SQL-side verification confirms
|
|
540
|
+
`dolt_conflicts` is empty and the commit is in, kill the recorded pid and
|
|
541
|
+
verify the port is closed FIRST (the non-`finally` portion of step 6, run
|
|
542
|
+
inline here on the happy path), and only then republish:
|
|
543
|
+
```
|
|
544
|
+
# kill <pid>; verify port closed -- see step 6 for the exact per-OS commands
|
|
545
|
+
bd dolt pull
|
|
546
|
+
bd dolt push
|
|
547
|
+
```
|
|
548
|
+
Confirm push actually succeeds mechanically (exit code + no divergence
|
|
549
|
+
message) -- never trust "the SQL said 0 conflicts" alone as proof of success,
|
|
550
|
+
exactly the posture the old Tier 2 runbook already correctly called for.
|
|
551
|
+
|
|
552
|
+
**Step 6 -- teardown, unconditionally, in a real `finally`.** The kill +
|
|
553
|
+
port-close verification above is the happy-path early execution of this same
|
|
554
|
+
teardown; the `finally` block below is what GUARANTEES it also runs on every
|
|
555
|
+
throw path (settle failure before reaching step 4/5), so teardown logic
|
|
556
|
+
lives in one place and is simply invoked early on success:
|
|
557
|
+
```js
|
|
558
|
+
try {
|
|
559
|
+
// steps 2-5
|
|
560
|
+
} finally {
|
|
561
|
+
await killByPid(pid); // Stop-Process -Force / kill, per OS
|
|
562
|
+
await verifyPortClosed(port); // TCP connect must now fail
|
|
563
|
+
const status = await command('bd dolt status');
|
|
564
|
+
if (!status.stdout.includes('embedded')) {
|
|
565
|
+
log(`[settle] WARNING: dolt_mode not embedded after teardown for ${member} -- this should be impossible since settle never flips it; investigate immediately, do not silently continue.`);
|
|
566
|
+
}
|
|
567
|
+
await command(`rm -f /tmp/dolt-settle-${member}-${port}.log`); // or Remove-Item on Windows
|
|
568
|
+
}
|
|
569
|
+
```
|
|
570
|
+
|
|
571
|
+
### 3.3 Supervisor-side orphan sweep (belt-and-suspenders for 3.2's teardown)
|
|
572
|
+
|
|
573
|
+
New, small addition to `src/supervisor/dolt-mutex.mjs` or a sibling module:
|
|
574
|
+
on a timer (e.g. every 5 minutes), for each known member, check for any
|
|
575
|
+
process matching `dolt sql-server.*--port 13[3-9]\d\d` (the settle port
|
|
576
|
+
range) older than e.g. 10 minutes, and kill it. This is a pure safety net --
|
|
577
|
+
if 3.2's `finally` is correct, this sweep should NEVER find anything. Its
|
|
578
|
+
value is covering the one case even a `finally` cannot: the orchestrator
|
|
579
|
+
process itself being killed mid-settle (SIGKILL, machine crash) before the
|
|
580
|
+
`finally` block runs.
|
|
581
|
+
|
|
582
|
+
### 3.4 Mutex lease fix
|
|
583
|
+
|
|
584
|
+
```js
|
|
585
|
+
// runner.js, wherever doltPushAfter currently holds the mutex across a
|
|
586
|
+
// push+reconcile:
|
|
587
|
+
const grant = await mutexClient.acquire();
|
|
588
|
+
const renewInterval = setInterval(() => mutexClient.renew(grant.token).catch(() => {}), 20_000); // well under the 60s lease
|
|
589
|
+
try {
|
|
590
|
+
// push, reconcile, settle-if-needed, republish
|
|
591
|
+
} finally {
|
|
592
|
+
clearInterval(renewInterval);
|
|
593
|
+
await mutexClient.release(grant.token);
|
|
594
|
+
}
|
|
595
|
+
```
|
|
596
|
+
Requires `createHttpDoltPushMutexClient` (runner.js) to expose a `renew`
|
|
597
|
+
method against the existing (or a new) `/api/dolt-push-mutex/:sprintId/renew`
|
|
598
|
+
route, and `dolt-mutex.mjs`'s `reclaimExpired()` logic already supports the
|
|
599
|
+
concept (it is literally what a lease renewal resets) -- this is additive,
|
|
600
|
+
not a behavior change to the reclaim logic itself.
|
|
601
|
+
|
|
602
|
+
### 3.5 Handling a pre-existing live server on the target port/data dir -- IMPLEMENTATION NOTE: option (b), not kill-and-reuse
|
|
603
|
+
|
|
604
|
+
If step 0/2's probe finds an already-listening server (from an interrupted
|
|
605
|
+
prior settle attempt, or -- per the earlier live investigation -- a stray
|
|
606
|
+
`.beads/dolt` per-project-mode-looking directory that turned out to be
|
|
607
|
+
orphaned residue from an old interrupted recovery): do NOT assume it is safe
|
|
608
|
+
to route through.
|
|
609
|
+
|
|
610
|
+
**As shipped, `pickFreePort` does NOT kill-and-reuse a busy port.** The
|
|
611
|
+
originally-sketched behavior above ("kill it first, then start a fresh one")
|
|
612
|
+
was evaluated during implementation review and deliberately NOT built: safely
|
|
613
|
+
scoping a same-data-dir kill requires distinguishing "genuinely orphaned
|
|
614
|
+
residue" from "another concurrent settle legitimately in progress" without a
|
|
615
|
+
race, and getting that distinction wrong (killing a live settle mid-merge) is
|
|
616
|
+
worse than the bounded wait below. Instead, `pickFreePort` skips any busy
|
|
617
|
+
candidate port outright and moves to the next free one; a stray orphaned
|
|
618
|
+
server is left for the supervisor's orphan sweep (Part 3.3) to reap on its
|
|
619
|
+
own schedule.
|
|
620
|
+
|
|
621
|
+
**This is a deliberate, accepted, WEAKER guarantee than "idempotent and
|
|
622
|
+
self-healing against its own prior failures" as originally stated below.**
|
|
623
|
+
Concretely: if the orchestrator dies mid-settle, the orphaned server still
|
|
624
|
+
holds the data dir's exclusive chunk-journal lock, and a fresh settle attempt
|
|
625
|
+
against the SAME data dir can fail or come up read-only for up to the sweep's
|
|
626
|
+
age threshold plus its run interval (~15 minutes with the current
|
|
627
|
+
`DEFAULT_MAX_AGE_MS`/`DEFAULT_SWEEP_INTERVAL_MS` defaults) until the sweep
|
|
628
|
+
reaps the orphan. Settle remains self-healing against ORDINARY merge
|
|
629
|
+
conflicts (the common case) unconditionally; self-healing against its own
|
|
630
|
+
prior orchestrator-death failure on the SAME data dir is bounded by the sweep
|
|
631
|
+
window above, not instantaneous. 15 minutes was judged an acceptable
|
|
632
|
+
worst-case bound given this failure mode requires BOTH a mid-settle
|
|
633
|
+
orchestrator death AND a same-data-dir retry inside that window -- narrow
|
|
634
|
+
enough that tightening the sweep's interval/threshold further was not judged
|
|
635
|
+
worth the added risk of the sweep interrupting a slow-but-live settle.
|
|
636
|
+
|
|
637
|
+
### 3.6 Manual verification plan across all 3 OSes
|
|
638
|
+
|
|
639
|
+
This must be done by hand (not via fleet-sprint) before this is considered
|
|
640
|
+
done, per the explicit instruction that started this branch. For EACH of
|
|
641
|
+
Windows (`fleet-win-dev1`), Linux (`fleet-lin-dev1`), and macOS (`fleet-mac`):
|
|
642
|
+
|
|
643
|
+
1. **Prereq check**: confirm `bd dolt status` on the member starts in
|
|
644
|
+
`embedded` mode (matches the fleet's real baseline).
|
|
645
|
+
2. **Manufacture a real row-level conflict deliberately** (do not simulate --
|
|
646
|
+
use two actual clones): from the orchestrator's own local clone AND the
|
|
647
|
+
target member's clone, both starting at the same remote commit, make a
|
|
648
|
+
conflicting edit to the SAME bead's SAME field from each side (e.g. change
|
|
649
|
+
`status` on one, `priority` on the other -- proves cell-vs-row-level
|
|
650
|
+
conflict semantics; then a second run changing the SAME field on both
|
|
651
|
+
sides -- proves the LWW tiebreak actually fires). Push from the
|
|
652
|
+
orchestrator side first (uncontested), so the member's next `bd dolt pull`
|
|
653
|
+
is guaranteed to hit a real merge conflict.
|
|
654
|
+
3. **Run `settleDoltConflicts` against the member** (initially by hand,
|
|
655
|
+
running each step of 3.2 as discrete commands via `execute_command` per
|
|
656
|
+
OS, before it's wired into automated `runner.js` code) and capture:
|
|
657
|
+
- the exact spawn technique's success/failure per OS (WMI on Windows;
|
|
658
|
+
`nohup`+`disown` on POSIX -- confirm POSIX detachment ALSO survives the
|
|
659
|
+
SSH session the way Windows notably did NOT with `Start-Process`; do not
|
|
660
|
+
assume POSIX is fine just because the existing `task-wrapper.ts` bash
|
|
661
|
+
pattern assumes it).
|
|
662
|
+
- the connect/query flag set working identically on all 3 (the ordering/
|
|
663
|
+
`--user` landmines were only verified on Windows so far -- confirm the
|
|
664
|
+
SAME landmines, or their absence, on Linux/macOS `dolt` builds).
|
|
665
|
+
- the settle SQL actually producing the LWW-correct row (query the
|
|
666
|
+
resolved row afterward and confirm it matches which side had the later
|
|
667
|
+
`updated_at`, not just that `dolt_conflicts` is empty).
|
|
668
|
+
- `bd dolt push` succeeding and the orchestrator's own subsequent
|
|
669
|
+
`bd dolt pull` seeing the settled, correct row.
|
|
670
|
+
- teardown leaving zero residual processes/ports/mode-flips.
|
|
671
|
+
4. **Record pass/fail per OS per step** in this doc's Part 4 (append a table
|
|
672
|
+
once the runs happen) before calling any OS done.
|
|
673
|
+
|
|
674
|
+
---
|
|
675
|
+
|
|
676
|
+
## Part 4 -- verification log
|
|
677
|
+
|
|
678
|
+
VERIFIED 2026-08-13, all three OSes green in ONE sequential run of
|
|
679
|
+
`node scripts/dolt-settle-integration.mjs --members fleet-win-dev1,fleet-lin-dev1,fleet-mac`
|
|
680
|
+
(exit 0). Every row below is the script's own emitted output, pasted verbatim
|
|
681
|
+
-- not a hand-written claim. Each run manufactured TWO real conflicts per
|
|
682
|
+
member from two independent clones, asserted each was genuinely unmergeable
|
|
683
|
+
via a failing `bd dolt pull` BEFORE settle was credited with anything, then
|
|
684
|
+
asserted the settled row's VALUES (not merely "no conflicts"), convergence in
|
|
685
|
+
the other clone, and zero residue.
|
|
686
|
+
|
|
687
|
+
| OS | Date | Spawn technique verified? | Flag set verified? | LWW correctness verified? | Teardown clean? | Notes |
|
|
688
|
+
|----|------|---------------------------|---------------------|----------------------------|------------------|-------|
|
|
689
|
+
| fleet-win-dev1 (win32) | 2026-08-13 | yes | yes | yes | yes | PASS; dolt 2.2.0 |
|
|
690
|
+
| fleet-lin-dev1 (linux) | 2026-08-13 | yes | yes | yes | yes | PASS; dolt 2.2.0 |
|
|
691
|
+
| fleet-mac (darwin) | 2026-08-13 | yes | yes | yes | yes | PASS; dolt 2.2.0 |
|
|
692
|
+
|
|
693
|
+
Precondition V0/V1 (Part 5.5) satisfied: all three members ran the PINNED
|
|
694
|
+
`dolt 2.2.0` from `~/.apra-fleet/bin`, recorded by the script before and after
|
|
695
|
+
each run; no run completed via the 5.6 degraded fallback (a DEGRADED verdict
|
|
696
|
+
would have been reported instead of PASS).
|
|
697
|
+
|
|
698
|
+
### 4.1 What the live runs CHANGED in this design (findings, not confirmations)
|
|
699
|
+
|
|
700
|
+
The pass above was not reached by running the design as written. Seven
|
|
701
|
+
mechanical claims in Parts 3/5 turned out to be wrong on real members; each
|
|
702
|
+
was corrected in `dolt-settle.mjs` and is now pinned by a unit test:
|
|
703
|
+
|
|
704
|
+
1. **`--theirs` after the LWW UPDATE clobbers the merged row.** Part 3.2 step
|
|
705
|
+
4 flagged this as "the one step to validate most carefully" -- and it was
|
|
706
|
+
indeed wrong. `DOLT_CONFLICTS_RESOLVE` rewrites the working-set row from the
|
|
707
|
+
chosen side, so the carefully merged row was overwritten with theirs
|
|
708
|
+
(fleet-lin-dev1: a row whose later `updated_at` was ours came back with
|
|
709
|
+
their older value). Settle now resolves LWW/union tables with `--ours`
|
|
710
|
+
AFTER writing the merged row, and separately INSERTs their-side-only rows
|
|
711
|
+
so nothing is dropped.
|
|
712
|
+
2. **Whole-row recency is NOT a per-field merge.** Part 3.2's "CASE on
|
|
713
|
+
updated_at recency is total and simpler ... the unchanged side's CASE
|
|
714
|
+
branches are no-ops" is false for DISJOINT edits: the newer side's stale
|
|
715
|
+
value overwrites the other side's real change (A set `status`, B set
|
|
716
|
+
`priority`, B was newer, A's status was lost). The merge now compares each
|
|
717
|
+
field against `base_*`: untouched-by-us takes theirs, untouched-by-them
|
|
718
|
+
takes ours, both-changed falls back to LWW-by-`updated_at` with the theirs
|
|
719
|
+
tiebreak.
|
|
720
|
+
3. **Each `dolt sql -q` is its own SESSION.** `SET @@dolt_allow_commit_conflicts
|
|
721
|
+
= 1` issued as a separate invocation is lost, and `DOLT_MERGE` then fails
|
|
722
|
+
with "Merge conflict detected, @autocommit transaction rolled back". Every
|
|
723
|
+
query now carries the SET in its preamble.
|
|
724
|
+
4. **`dolt sql -r json` emits one JSON document PER STATEMENT**, concatenated
|
|
725
|
+
(`{}` for non-SELECTs). Parsing the output as a single document silently
|
|
726
|
+
returned zero conflicted tables on a genuinely conflicted clone.
|
|
727
|
+
5. **POSIX detachment needed more than `nohup ... & disown`.** Under the
|
|
728
|
+
fleet's own bash wrapper the dispatch hung to its 300s timeout while the
|
|
729
|
+
server was up and holding the lock. The working form is a detached
|
|
730
|
+
SUBSHELL, `< /dev/null`, and the pid read from `pgrep` (not `$!`). `setsid`
|
|
731
|
+
does not exist on macOS and is resolved at runtime.
|
|
732
|
+
6. **There is no portable shell one-liner for a TCP probe.** `cmd || fallback`
|
|
733
|
+
is a PowerShell 5.1 parse error; `/dev/tcp` is bash-only and fleet-mac's
|
|
734
|
+
shell is ZSH, where the probe silently reported "nothing listening" while
|
|
735
|
+
the server logged "Server ready". Both the probe and the port scan are now
|
|
736
|
+
`node -e` (every member has node) -- and PowerShell strips double quotes
|
|
737
|
+
from native arguments, so the JS is backslash-escaped there.
|
|
738
|
+
7. **WMI needs an EXPANDED path.** Passing `$env:USERPROFILE\...` inside
|
|
739
|
+
Win32_Process.Create's single-quoted argument fails with ReturnValue 9
|
|
740
|
+
("path not found"); the command line is now assembled from an expanded
|
|
741
|
+
PowerShell variable.
|
|
742
|
+
|
|
743
|
+
Timings, for scale: a full settle (spawn, merge, resolve, commit, teardown,
|
|
744
|
+
republish) takes roughly 8s on macOS, 15s on Windows and 20s on Linux.
|
|
745
|
+
|
|
746
|
+
---
|
|
747
|
+
|
|
748
|
+
## Part 5 -- pinning a working Dolt version end-to-end
|
|
749
|
+
|
|
750
|
+
The manual verification pass (2026-08-12/13, fleet-win-dev1) contained one
|
|
751
|
+
genuine mistake, caught and corrected the same day: it installed dolt via
|
|
752
|
+
`winget install --id DoltHub.Dolt`, which silently delivered a STALE build
|
|
753
|
+
(1.86.3) while the vendor's current release is 2.2.3 -- and while this repo
|
|
754
|
+
already carries a version pin. This Part makes the pin airtight end-to-end
|
|
755
|
+
and supersedes both `dolt-manual-recovery-verified.md` step 1 (the
|
|
756
|
+
winget/apt/brew instructions -- to be corrected in that doc) and the Part 3.2
|
|
757
|
+
step-1 code sketch. A first revision of this Part contained its own error --
|
|
758
|
+
it assumed members run `apra-fleet install` -- corrected in 5.2 below.
|
|
759
|
+
|
|
760
|
+
### 5.1 The pin, and its single source of truth
|
|
761
|
+
|
|
762
|
+
`src/cli/dolt-install.ts` holds the repo's only Dolt version pin and asset
|
|
763
|
+
knowledge:
|
|
764
|
+
|
|
765
|
+
- `export const DOLT_VERSION = 'v2.2.0'` (line 22). Assets download directly
|
|
766
|
+
from `https://github.com/dolthub/dolt/releases/download/v2.2.0/` per
|
|
767
|
+
platform/arch (`resolveDoltAsset`, lines 48-78: win32/x64 ->
|
|
768
|
+
`dolt-windows-amd64.zip`, linux/x64 -> `dolt-linux-amd64.tar.gz`,
|
|
769
|
+
darwin/x64 and darwin/arm64 -> the darwin tarballs; any other combo throws
|
|
770
|
+
`UnsupportedDoltPlatformError`, never a silent no-op).
|
|
771
|
+
- `downloadAndExtractDolt(destDir)` extracts the single static binary into a
|
|
772
|
+
caller-supplied dir -- on the orchestrator, `BIN_DIR` = `~/.apra-fleet/bin`
|
|
773
|
+
(`src/cli/config.ts:9`). Never system PATH, no admin rights.
|
|
774
|
+
- `verifyDolt(doltPath)` is a *functional* check, not an existence check: it
|
|
775
|
+
runs `dolt version` (throws on failure -- catching present-but-broken
|
|
776
|
+
binaries) then smoke-tests a real `dolt sql-server` (warn-not-fail).
|
|
777
|
+
|
|
778
|
+
Anything else -- winget, apt, brew, `install.sh | bash` -- is a second,
|
|
779
|
+
unpinned version channel and is banned from every code path and runbook this
|
|
780
|
+
design owns. The winget incident is the proof: the winget package is not even
|
|
781
|
+
vendor-current (1.86.3 vs 2.2.3), so "install via package manager" does not
|
|
782
|
+
merely risk drift, it guarantees it.
|
|
783
|
+
|
|
784
|
+
### 5.2 Orchestrator and member are NOT symmetric (corrected premise)
|
|
785
|
+
|
|
786
|
+
Verified against the actual provisioning code, not assumed:
|
|
787
|
+
|
|
788
|
+
- **The orchestrator** is the machine running `apra-fleet` itself. It goes
|
|
789
|
+
through `apra-fleet install`, whose apra-fleet-ire.3 Dolt step
|
|
790
|
+
(`src/cli/install.ts:1368-1401`) really attempts
|
|
791
|
+
`downloadAndExtractDolt(BIN_DIR)` + `verifyDolt` in-process. That step is
|
|
792
|
+
NON-FATAL (try/catch, "a missing/broken dolt must never fail apra-fleet
|
|
793
|
+
install", plus the `doltStepEnabled()` gate at install.ts:57-60), so even
|
|
794
|
+
the orchestrator's binary must be verified, never assumed -- but at least
|
|
795
|
+
a pinned install was *attempted* there, and re-running `apra-fleet
|
|
796
|
+
install` locally is a complete repair path (the already-installed check at
|
|
797
|
+
install.ts:1382 makes re-runs idempotent).
|
|
798
|
+
- **A fleet member never runs `apra-fleet` at all.** It is an SSH-reachable
|
|
799
|
+
command target. Member onboarding (`src/tools/register-member.ts` +
|
|
800
|
+
`src/services/agent-provisioner.ts`) provisions SSH auth, workspace
|
|
801
|
+
overlays, LLM/agent assets, and credentials -- it installs neither `bd`
|
|
802
|
+
nor `dolt`, and no code path anywhere dispatches `apra-fleet install` to a
|
|
803
|
+
member (repo-wide search: the string appears only in orchestrator CLI help
|
|
804
|
+
text and docs). `docs/beads.md:82`'s statement that "`apra-fleet install`
|
|
805
|
+
also provisions a portable Dolt CLI" is true only of the machine running
|
|
806
|
+
the install -- i.e. the orchestrator.
|
|
807
|
+
|
|
808
|
+
So the reason a member lacks a correctly-pinned dolt is not "the non-fatal
|
|
809
|
+
install step failed there" (this document's earlier framing -- wrong): it is
|
|
810
|
+
that **nothing has ever attempted to install one there, full stop**. What a
|
|
811
|
+
member *may* have is a stray, arbitrary-version dolt from manual operator
|
|
812
|
+
action -- fleet-win-dev1's winget 1.86.3 is a live example sitting on a real
|
|
813
|
+
member right now. Conclusion: on members, pin enforcement cannot be
|
|
814
|
+
delegated to any install-time mechanism, because none exists. It must be
|
|
815
|
+
done by the thing that needs the binary: settle itself.
|
|
816
|
+
|
|
817
|
+
### 5.3 Settle checks AND installs the pinned dolt on the member
|
|
818
|
+
|
|
819
|
+
`settleDoltConflicts()` is self-sufficient: step 1 probes for the pinned
|
|
820
|
+
binary and, if it is missing or the wrong version, **installs it itself over
|
|
821
|
+
`command()`** before proceeding. (This supersedes Part 3.2 step 1's sketch,
|
|
822
|
+
which called the orchestrator-local `downloadAndExtractDolt()` -- impossible
|
|
823
|
+
across a `command()` dispatch boundary -- and this document's earlier
|
|
824
|
+
throw-and-defer-to-readiness-gate design.)
|
|
825
|
+
|
|
826
|
+
**Step 1a -- probe.** The fleet-managed member-side location is
|
|
827
|
+
`~/.apra-fleet/bin/dolt(.exe)` -- the same `BIN_DIR` convention as the
|
|
828
|
+
orchestrator, resolved with the MEMBER's shell (`$env:USERPROFILE` /
|
|
829
|
+
`$HOME`), so the layout is identical everywhere and, on a machine that is
|
|
830
|
+
both orchestrator and local member, both writers produce identical bytes at
|
|
831
|
+
the identical path.
|
|
832
|
+
|
|
833
|
+
```js
|
|
834
|
+
const res = await command(`"<memberDoltPath>" version`);
|
|
835
|
+
// PASS requires BOTH: exit 0 with parseable "dolt version X.Y.Z" output
|
|
836
|
+
// (the remote functional equivalent of verifyDolt's throwing version
|
|
837
|
+
// check -- a file that exists but cannot run `dolt version` is BROKEN),
|
|
838
|
+
// AND the version equals the pin (2.2.0). Anything else -> step 1b.
|
|
839
|
+
```
|
|
840
|
+
|
|
841
|
+
**Step 1b -- install, via remote shell, from the SAME pinned asset URLs.**
|
|
842
|
+
Resolve the member's platform/arch first -- NOT `process.platform` (that is
|
|
843
|
+
the orchestrator's): take it from the member registry metadata the caller
|
|
844
|
+
already has (`detectOS` at registration), with a remote fallback probe
|
|
845
|
+
(`node -e "console.log(process.platform, process.arch)"` -- members
|
|
846
|
+
necessarily have node, since `bd` is npm-installed). Feed that pair through
|
|
847
|
+
the same platform->asset mapping `resolveDoltAsset` defines, yielding the
|
|
848
|
+
exact `.../download/v2.2.0/<asset>` URL. Then:
|
|
849
|
+
|
|
850
|
+
```powershell
|
|
851
|
+
# Windows member
|
|
852
|
+
New-Item -ItemType Directory -Force "$env:USERPROFILE\.apra-fleet\bin"
|
|
853
|
+
Invoke-WebRequest -Uri <assetUrl> -OutFile "$env:TEMP\dolt-settle.zip"
|
|
854
|
+
Expand-Archive -Force "$env:TEMP\dolt-settle.zip" "$env:TEMP\dolt-settle"
|
|
855
|
+
# Release archives nest the binary (e.g. dolt-windows-amd64/bin/dolt.exe) --
|
|
856
|
+
# locate by name, exactly like extractSingleFileFromZip does by basename:
|
|
857
|
+
Get-ChildItem -Recurse -Filter dolt.exe "$env:TEMP\dolt-settle" |
|
|
858
|
+
Select-Object -First 1 | Copy-Item -Force -Destination "$env:USERPROFILE\.apra-fleet\bin\dolt.exe"
|
|
859
|
+
```
|
|
860
|
+
```bash
|
|
861
|
+
# POSIX member
|
|
862
|
+
mkdir -p "$HOME/.apra-fleet/bin"
|
|
863
|
+
curl -fL --max-time 300 <assetUrl> -o /tmp/dolt-settle.tgz
|
|
864
|
+
mkdir -p /tmp/dolt-settle && tar -xzf /tmp/dolt-settle.tgz -C /tmp/dolt-settle
|
|
865
|
+
install -m 0755 "$(find /tmp/dolt-settle -type f -name dolt | head -1)" "$HOME/.apra-fleet/bin/dolt"
|
|
866
|
+
```
|
|
867
|
+
|
|
868
|
+
Then **re-probe (step 1a again)**: the freshly installed binary must pass
|
|
869
|
+
the version check before settle continues. Cleanup of the temp
|
|
870
|
+
archive/extract dir happens in settle's existing `finally`.
|
|
871
|
+
|
|
872
|
+
Safety bounds, so a settle-time install can never make recovery worse than
|
|
873
|
+
the conflict it is fixing:
|
|
874
|
+
|
|
875
|
+
- **Bounded time:** a hard timeout on the download dispatch (300s;
|
|
876
|
+
`--max-time` / `Invoke-WebRequest -TimeoutSec`, plus the `command()`
|
|
877
|
+
timeout as backstop). The asset is a single ~100MB static binary; if it
|
|
878
|
+
cannot arrive in that window, the member's network is the problem.
|
|
879
|
+
- **One attempt.** No retry loops inside settle; a failed install throws.
|
|
880
|
+
- **Classification:** download/HTTP failure, unsupported platform/arch, and
|
|
881
|
+
a corrupted download (post-install re-probe fails) are typed operational
|
|
882
|
+
errors (`DoltBinaryUnavailableError`: member, URL, failing output, exact
|
|
883
|
+
manual repair command) -- ordinary infra failures under Part 2.2's
|
|
884
|
+
degraded/fatal taxonomy, NOT escalation tiers. One deliberate exception --
|
|
885
|
+
a blocked *replacement* of an existing binary -- degrades instead of
|
|
886
|
+
throwing; that is 5.6.
|
|
887
|
+
|
|
888
|
+
The earlier objections to a settle-time download (unbounded mid-recovery
|
|
889
|
+
network dependency, second-installer drift risk) are answered rather than
|
|
890
|
+
dismissed: the time bound is explicit and single-shot; the drift risk is
|
|
891
|
+
closed structurally in 5.4 because the shell installer shares the pin/asset
|
|
892
|
+
source of truth under a drift guard, and on members there is no alternative
|
|
893
|
+
installer to drift *from* -- deferring repair to an install mechanism that
|
|
894
|
+
does not exist on members was the actual design error.
|
|
895
|
+
|
|
896
|
+
### 5.4 One pin, two executors -- kept from drifting; and `install.cjs`
|
|
897
|
+
|
|
898
|
+
Two pieces of code now materialize the pin: `downloadAndExtractDolt`
|
|
899
|
+
(in-process, orchestrator) and settle's remote-shell installer (members).
|
|
900
|
+
They must share one source of truth. `dolt-settle.mjs` cannot import the
|
|
901
|
+
TypeScript `src/cli/dolt-install.ts` across the package boundary at runtime,
|
|
902
|
+
so: `dolt-settle.mjs` exports its own `DOLT_VERSION`/asset-map constants,
|
|
903
|
+
and a mandatory unit test asserts them equal to the values parsed from
|
|
904
|
+
`src/cli/dolt-install.ts`'s source text -- the exact source-text drift-guard
|
|
905
|
+
convention this repo already uses (`test/dolt-literal-guard.test.mjs`,
|
|
906
|
+
`contracts-schema-dist-staleness-guard.test.mjs`). A pin bump that touches
|
|
907
|
+
one file and not the other fails CI.
|
|
908
|
+
|
|
909
|
+
`install.cjs` (repo root, read in full -- 22 lines): a thin launcher that
|
|
910
|
+
spawns `node dist/index.js install <args>` (install.cjs:8-21), i.e. the SAME
|
|
911
|
+
compiled `install.ts` path, same pin, same non-fatal semantics. It is not a
|
|
912
|
+
second mechanism and holds no second pin -- and per 5.2 it is
|
|
913
|
+
orchestrator-only; no member ever executes it. One precise caveat: it runs
|
|
914
|
+
whatever `dist/` is present, so a stale build carries a stale pin -- covered
|
|
915
|
+
by extending the dist-staleness guard above to assert the built `dist`
|
|
916
|
+
embeds the current `DOLT_VERSION`.
|
|
917
|
+
|
|
918
|
+
### 5.5 Is `v2.2.0` the right pin? Yes -- but the landmines are UNVERIFIED on it
|
|
919
|
+
|
|
920
|
+
Keep `v2.2.0`. It is the pin the apra-fleet-ire PoC validated
|
|
921
|
+
(dolt-install.ts:4-10) and no known bug motivates chasing the vendor's
|
|
922
|
+
2.2.3; bumping the pin is separate work with its own verification pass.
|
|
923
|
+
|
|
924
|
+
**The gap, stated as hard preconditions rather than a footnote:** every
|
|
925
|
+
mechanical landmine settle encodes -- `--no-tls` ordering before
|
|
926
|
+
`--host`/`--port`, omitting `--user`/`--password` entirely, the
|
|
927
|
+
`DOLT_CONFLICTS_RESOLVE` table-name requirement, the Part 3.2 step-4
|
|
928
|
+
`--theirs`-after-LWW-UPDATE interplay -- was live-verified against the stray
|
|
929
|
+
winget **1.86.3**, NOT against pinned **v2.2.0**. Numbered preconditions of
|
|
930
|
+
the Part 4 / Part 6 verification work:
|
|
931
|
+
|
|
932
|
+
1. **Precondition V0 (per OS):** before any Part 4 cell is marked verified
|
|
933
|
+
for an OS, re-run the full flag-set/landmine matrix of
|
|
934
|
+
`dolt-manual-recovery-verified.md` step 3 against the member-side binary
|
|
935
|
+
settle itself installed (5.3), at v2.2.0, and record the exact
|
|
936
|
+
`dolt version` output in that OS's Part 4 Notes cell. A row without a
|
|
937
|
+
recorded v2.2.0 version string is not a verified row.
|
|
938
|
+
2. **Precondition V1:** the Part 6 integration script asserts, after
|
|
939
|
+
settle's step 1 has run, that the member-side binary settle used reports
|
|
940
|
+
exactly the pinned version -- thereby exercising settle's own installer
|
|
941
|
+
on a member that never had a pinned dolt, and guaranteeing no green run
|
|
942
|
+
is ever produced by an unpinned binary again. A run that completed via
|
|
943
|
+
the 5.6 degraded fallback reports DEGRADED, never PASS.
|
|
944
|
+
3. **Precondition V2:** correct `dolt-manual-recovery-verified.md` step 1 to
|
|
945
|
+
the settle-installer/`~/.apra-fleet/bin` path and mark the
|
|
946
|
+
winget/apt/brew instructions as the historical mistake they were.
|
|
947
|
+
|
|
948
|
+
### 5.6 When the pinned install is BLOCKED: kill-first, then warn-and-fall-back
|
|
949
|
+
|
|
950
|
+
New failure mode, explicitly designed for: step 1b must *replace* an
|
|
951
|
+
existing wrong-version binary at `~/.apra-fleet/bin/dolt(.exe)`, and on
|
|
952
|
+
Windows an in-use executable cannot be overwritten -- a running `dolt`
|
|
953
|
+
process (most plausibly settle's own orphaned ephemeral server, the Part
|
|
954
|
+
7.2/3.3 residue class) holds the file. Handling ladder:
|
|
955
|
+
|
|
956
|
+
1. **Detect specifically.** The final copy/`install` step fails with a
|
|
957
|
+
sharing-violation class error ("being used by another process",
|
|
958
|
+
EBUSY/ETXTBSY/EPERM-on-replace). Only THIS class enters the ladder;
|
|
959
|
+
download/extract failures remain hard operational errors per 5.3.
|
|
960
|
+
2. **Remediate first -- kill, then retry once.** Enumerate processes whose
|
|
961
|
+
*executable path equals the target binary path*
|
|
962
|
+
(`Get-Process | Where-Object { $_.Path -eq <path> }` /
|
|
963
|
+
`lsof <path>` / `fuser`): any such process is by definition a fleet
|
|
964
|
+
orphan -- nothing but settle and this installer ever launches the binary
|
|
965
|
+
at the fleet-managed path -- so killing it is the same legitimate
|
|
966
|
+
self-heal as Part 3.3's sweep, not collateral damage. Kill, wait
|
|
967
|
+
briefly, retry the replacement once. A process holding the file that is
|
|
968
|
+
NOT running our binary path (e.g. an operator's own dolt install
|
|
969
|
+
elsewhere, an AV scanner) is not ours to kill -- skip to step 3.
|
|
970
|
+
3. **Only then: warn and fall back, per explicit direction -- but gated,
|
|
971
|
+
not blind.** Settle logs and returns a WARNING ("pin not enforced on
|
|
972
|
+
<member>: could not replace <path>; proceeding with dolt <version> at
|
|
973
|
+
<path>"), selects a fallback binary -- the existing runnable (wrong-version)
|
|
974
|
+
binary already at the fleet-managed path (`ensurePinnedDolt()`'s actual
|
|
975
|
+
implementation never falls back further, to `dolt` on the member's PATH or
|
|
976
|
+
anywhere else) -- and requires it to pass a functional gate before any
|
|
977
|
+
data is touched:
|
|
978
|
+
`dolt version` must run, and the FIRST statement issued through the
|
|
979
|
+
ephemeral server must be a harmless
|
|
980
|
+
`dolt --no-tls --host=... --port=... sql -q "SELECT 1"` preflight. That
|
|
981
|
+
one command exercises exactly the version-sensitive landmine surface
|
|
982
|
+
(global-flag ordering, credential-less auth); if the fallback's parsing
|
|
983
|
+
differs, settle fails fast with a clean operational error before the
|
|
984
|
+
merge is ever reopened. Only if the preflight passes does settle proceed.
|
|
985
|
+
4. **Return-shape addendum to Part 3.1:** settle's result gains
|
|
986
|
+
`warnings: string[]` and `doltVersionUsed: string`; callers log
|
|
987
|
+
warnings, and the Part 6 script maps a non-pinned `doltVersionUsed` to
|
|
988
|
+
DEGRADED (per V1).
|
|
989
|
+
|
|
990
|
+
Is the degraded path's "landmines unverified on this version" exposure
|
|
991
|
+
acceptable? **Yes, as a clearly-flagged last resort** -- on evidence, not
|
|
992
|
+
optimism: the entire landmine set was in fact discovered on and works on
|
|
993
|
+
1.86.3, and the pinned target is 2.2.0, so the flag surface is demonstrably
|
|
994
|
+
stable across a wide version span; the `SELECT 1` preflight converts the
|
|
995
|
+
residual risk into a fast, data-free failure; and the step-4 verification
|
|
996
|
+
(`dolt_conflicts` count must be 0 before commit/push) remains the hard
|
|
997
|
+
correctness gate regardless of which binary executed the SQL. The
|
|
998
|
+
alternative -- hard-failing settle because a file handle was held -- would
|
|
999
|
+
reintroduce exactly the "recovery that refuses to recover" posture this
|
|
1000
|
+
redesign exists to eliminate. What is NOT acceptable, and remains a hard
|
|
1001
|
+
throw: no runnable dolt at all after the ladder (missing pin install +
|
|
1002
|
+
no usable fallback), an unsupported platform with no existing binary, or a
|
|
1003
|
+
fallback that fails the functional gate.
|
|
1004
|
+
|
|
1005
|
+
---
|
|
1006
|
+
|
|
1007
|
+
## Part 6 -- the integration script: manufacture a real conflict, prove settle() recovers
|
|
1008
|
+
|
|
1009
|
+
Scope, deliberately narrow: **a reliable script, run from the orchestrator,
|
|
1010
|
+
against any one member at a time**, that (a) deliberately manufactures a
|
|
1011
|
+
genuine Dolt row-level merge conflict between the orchestrator's clone and
|
|
1012
|
+
that member's clone, (b) invokes the real `settleDoltConflicts()` through the
|
|
1013
|
+
real dispatch path, and (c) proves recovery with explicit assertions. It is
|
|
1014
|
+
the executable form of Part 3.6 and the tool that fills in Part 4's table.
|
|
1015
|
+
It is not a mocked unit test and it is not a CI suite.
|
|
1016
|
+
|
|
1017
|
+
### 6.1 File, invocation, and why that location
|
|
1018
|
+
|
|
1019
|
+
**File:** `packages/apra-fleet-se/scripts/dolt-settle-integration.mjs`.
|
|
1020
|
+
|
|
1021
|
+
Rationale: `packages/apra-fleet-se/scripts/` is this package's existing home
|
|
1022
|
+
for runnable operator-facing launchers (`scripts/run-tests.mjs`), and --
|
|
1023
|
+
decisive for gating -- the package's `test` script globs only
|
|
1024
|
+
`test/*.test.mjs` (package.json:16), so nothing under `scripts/` can ever be
|
|
1025
|
+
swept into `npm test` by accident. The mocked unit coverage for
|
|
1026
|
+
`dolt-settle.mjs` (scripted `command()`, exactly how Path A was tested in
|
|
1027
|
+
`test/dolt-sync-discipline.test.mjs`) is a separate, ordinary
|
|
1028
|
+
`test/dolt-settle.test.mjs` that DOES run in `npm test`; this script is the
|
|
1029
|
+
live complement, not a replacement for that.
|
|
1030
|
+
|
|
1031
|
+
**Invocation:**
|
|
1032
|
+
|
|
1033
|
+
```
|
|
1034
|
+
node scripts/dolt-settle-integration.mjs --member fleet-win-dev1
|
|
1035
|
+
node scripts/dolt-settle-integration.mjs --all # win-dev1, lin-dev1, mac -- strictly sequential
|
|
1036
|
+
node scripts/dolt-settle-integration.mjs --member fleet-mac --keep-sandbox # debug aid: skip teardown of the sandbox remote/dirs
|
|
1037
|
+
```
|
|
1038
|
+
|
|
1039
|
+
plus a package.json convenience entry:
|
|
1040
|
+
|
|
1041
|
+
```json
|
|
1042
|
+
"test:dolt-settle-integration": "node scripts/dolt-settle-integration.mjs"
|
|
1043
|
+
```
|
|
1044
|
+
|
|
1045
|
+
`--all` iterates the three members one at a time in a fixed order, never in
|
|
1046
|
+
parallel (per the explicit requirement), with a full setup/teardown cycle per
|
|
1047
|
+
member so a failure on one OS cannot contaminate the next.
|
|
1048
|
+
|
|
1049
|
+
### 6.2 Gating -- decisively NOT part of `npm test`
|
|
1050
|
+
|
|
1051
|
+
This script requires a live apra-fleet server and SSH-reachable members --
|
|
1052
|
+
things no generic CI runner has. Decision: it is **never** wired into
|
|
1053
|
+
`npm test`, `test:unit`, or `test:slow`; it is a manual / dedicated-runner
|
|
1054
|
+
entry point only. The repo has no existing env-var gate convention for
|
|
1055
|
+
live-fleet tests (searched: the closest precedent is
|
|
1056
|
+
`test/dolt-sync-discipline.test.mjs`'s "skip with a clear message, never a
|
|
1057
|
+
silent pass" posture for a missing dolt binary, lines 96-101). This script
|
|
1058
|
+
adopts the same posture translated to a script: a **preflight** that calls
|
|
1059
|
+
`fleet_status`/`list_members` and probes each target member with a trivial
|
|
1060
|
+
`execute_command` echo; any unreachable prerequisite exits with code 2 and an
|
|
1061
|
+
explicit "PRECONDITION FAILED (not a settle failure): ..." message. Exit 0 =
|
|
1062
|
+
proven recovery; exit 1 = a real assertion failure; exit 2 = environment not
|
|
1063
|
+
available. No silent green, ever.
|
|
1064
|
+
|
|
1065
|
+
### 6.3 Real plumbing, no reimplementation
|
|
1066
|
+
|
|
1067
|
+
The script connects exactly the way `bin/cli.mjs` does (imports from
|
|
1068
|
+
`@apralabs/apra-fleet-client`): `resolveFleetServerConnection` from
|
|
1069
|
+
`@apralabs/apra-fleet-client/server-resolution`, `McpClient` over the
|
|
1070
|
+
resolved transport, wrapped in `ApraFleet`. The member-scoped command runner
|
|
1071
|
+
is the same shape the sprint runner already injects everywhere
|
|
1072
|
+
(cli.mjs:632-638):
|
|
1073
|
+
|
|
1074
|
+
```js
|
|
1075
|
+
const commandFor = (member) => async (cmd, opts = {}) => {
|
|
1076
|
+
const res = await fleetApi.executeCommand({ command: cmd, member_name: member, ...opts });
|
|
1077
|
+
// parse stdout/stderr/exitCode from the execute_command result envelope,
|
|
1078
|
+
// identically to the runner's own parsing
|
|
1079
|
+
};
|
|
1080
|
+
```
|
|
1081
|
+
|
|
1082
|
+
Settle is invoked as the **real import** --
|
|
1083
|
+
`import { settleDoltConflicts } from '../fleet-sprint/dolt-settle.mjs'` --
|
|
1084
|
+
with `command: commandFor(member)`. Server side, that traverses the real
|
|
1085
|
+
`src/tools/execute-command.ts` SSH dispatch. Nothing in the conflict path is
|
|
1086
|
+
mocked or re-implemented; the only test-specific code is sandbox setup,
|
|
1087
|
+
conflict manufacture, and assertions.
|
|
1088
|
+
|
|
1089
|
+
Before touching the member, the script takes a **member reservation** (the
|
|
1090
|
+
same `member_reservation` tool `createMemberReservationClient` uses,
|
|
1091
|
+
runner.js:1467-1490 / cli.mjs:730-734) so a concurrently-launched sprint
|
|
1092
|
+
cannot dispatch onto the member mid-test, and releases it in the final
|
|
1093
|
+
`finally`. The `dolt_push_mutex` is NOT taken: it serializes pushes to the
|
|
1094
|
+
*production* remote, and per 6.4 this script never touches that remote.
|
|
1095
|
+
|
|
1096
|
+
### 6.4 Sandbox, not production -- decided
|
|
1097
|
+
|
|
1098
|
+
**The script never touches the real shared beads DB or any production
|
|
1099
|
+
`.beads` clone. Mandatory, not optional.** Justification: the script's whole
|
|
1100
|
+
purpose is to manufacture wedging conflicts and then run brand-new recovery
|
|
1101
|
+
code against them; a settle bug mid-test would wedge or mis-merge whatever DB
|
|
1102
|
+
it ran against. Doing that against the production remote -- while real
|
|
1103
|
+
sprints may be pushing -- converts a test failure into a production incident.
|
|
1104
|
+
A "disposable test bead inside the production DB" is therefore rejected too:
|
|
1105
|
+
the bead may be disposable, but the *clone wedging and the merge commits* are
|
|
1106
|
+
not scoped to the bead.
|
|
1107
|
+
|
|
1108
|
+
Concrete isolation, per member run:
|
|
1109
|
+
|
|
1110
|
+
- **Orchestrator side:** a fresh temp dir on the orchestrator machine;
|
|
1111
|
+
`bd init` a new beads DB there; create one test issue whose id/title are
|
|
1112
|
+
unmistakable (`[SETTLE-IT] disposable conflict fixture <runId>`).
|
|
1113
|
+
- **Sandbox remote:** a dedicated database named
|
|
1114
|
+
`beads-settle-it-<runId>` on the **same remote endpoint and credentials
|
|
1115
|
+
the fleet's production beads DB already uses** -- reusing the one
|
|
1116
|
+
remote/auth path all three members have already proven reachable (a
|
|
1117
|
+
separate ad-hoc remote server would add an unproven network dependency and
|
|
1118
|
+
violate 6.2's "no new environment assumptions"). Distinct database name =
|
|
1119
|
+
full isolation from production data and refs. Configure the temp clone's
|
|
1120
|
+
sync remote to it; `bd dolt push` the baseline.
|
|
1121
|
+
- **Member side:** a fresh temp dir on the member (`command()`-created),
|
|
1122
|
+
bootstrapped from the sandbox remote using the same clone-bootstrap
|
|
1123
|
+
sequence the fleet already uses for provisioning (the sequence Path B's
|
|
1124
|
+
re-bootstrap encodes in `dolt-recovery-path-b.mjs` -- lift it before that
|
|
1125
|
+
file is retired per Part 2.4). All member-side `bd`/`dolt` commands run
|
|
1126
|
+
with cwd set to this temp dir, so the member's real production clone is
|
|
1127
|
+
physically out of scope of every command the script issues.
|
|
1128
|
+
- **Teardown (`finally`, always, unless `--keep-sandbox`):** delete the
|
|
1129
|
+
sandbox remote database, remove both temp dirs, release the reservation.
|
|
1130
|
+
|
|
1131
|
+
### 6.5 The per-member flow (sequential, two scenarios)
|
|
1132
|
+
|
|
1133
|
+
For the target member M, starting from both clones at the same sandbox head:
|
|
1134
|
+
|
|
1135
|
+
1. **Probe** (Precondition V1, Part 5.5): `"<memberDoltPath>" version` on M
|
|
1136
|
+
must report exactly the pinned 2.2.0; `bd dolt status` in M's sandbox
|
|
1137
|
+
clone must report embedded mode. Fail (exit 1) on mismatch.
|
|
1138
|
+
2. **Orchestrator edit + push:** update the test bead's target field in the
|
|
1139
|
+
orchestrator clone (e.g. `bd update <id> --priority 1`), `bd dolt push`.
|
|
1140
|
+
Uncontested -- this becomes the remote ("theirs") side.
|
|
1141
|
+
3. **Member conflicting edit:** on M, update the SAME field of the SAME bead
|
|
1142
|
+
to a different value (`bd update <id> --priority 3`) -- strictly
|
|
1143
|
+
wall-clock-after step 2, so M's row carries the later `updated_at` and the
|
|
1144
|
+
LWW-correct final value is unambiguous (3).
|
|
1145
|
+
4. **Prove the conflict is real:** run `bd dolt pull` on M and **assert it
|
|
1146
|
+
FAILS** with output matching a genuine merge conflict
|
|
1147
|
+
(`isDoltPullConflict`-class patterns). If the pull succeeds -- e.g. a
|
|
1148
|
+
future bd auto-resolves it (Part 2.3's accelerator) -- the run is reported
|
|
1149
|
+
INCONCLUSIVE-FOR-SETTLE (exit 2), never PASS: the script must not claim
|
|
1150
|
+
settle recovered a conflict that never existed.
|
|
1151
|
+
5. **Invoke `settleDoltConflicts(M, { command: commandFor(M), log })`** and
|
|
1152
|
+
assert it resolves with `ok: true` and `resolvedTables` containing
|
|
1153
|
+
`issues`.
|
|
1154
|
+
6. **Assert, independently of settle's own return values:**
|
|
1155
|
+
a. M's `bd dolt status` is clean and reports embedded mode; a direct
|
|
1156
|
+
conflict re-check shows zero conflicts.
|
|
1157
|
+
b. `bd show <id> --json` on M: the contested field equals the
|
|
1158
|
+
LWW-correct value (3 -- M's later `updated_at` won) and `updated_at`
|
|
1159
|
+
equals the max of the two sides. Asserting the *value*, not just
|
|
1160
|
+
"conflicts empty", is what catches a wrong-direction resolve.
|
|
1161
|
+
c. M's republish push succeeded (settle step 5's push exit status,
|
|
1162
|
+
re-verified by the script via `bd dolt status` / push idempotency).
|
|
1163
|
+
d. Orchestrator convergence: `bd dolt pull` in the orchestrator clone,
|
|
1164
|
+
then `bd show <id> --json` there shows the same settled value.
|
|
1165
|
+
e. **Zero residue on M:** no process matching `dolt sql-server` in the
|
|
1166
|
+
settle port range (`Get-Process`/`pgrep -f`), TCP connect to the used
|
|
1167
|
+
port now refused, `bd dolt status` still embedded,
|
|
1168
|
+
`.beads/metadata.json` `dolt_mode` still `"embedded"`, ephemeral log
|
|
1169
|
+
file removed.
|
|
1170
|
+
7. **Scenario 2 -- disjoint fields:** repeat 2-6 with the orchestrator
|
|
1171
|
+
changing `status` and M changing `priority`. This exercises the row-level
|
|
1172
|
+
(not cell-level) conflict shape from Part 1.2 and asserts BOTH sides'
|
|
1173
|
+
field values survive in the settled row -- the per-field merge, not a
|
|
1174
|
+
whole-row clobber.
|
|
1175
|
+
8. **Report:** print one summary line per OS in exactly Part 4's column
|
|
1176
|
+
format (`| <OS> | <date> | yes/no | yes/no | yes/no | yes/no | dolt
|
|
1177
|
+
<version>, <notes> |`). **Filling Part 4 IS running this script once per
|
|
1178
|
+
member and pasting the emitted rows.** A Part 4 row filled any other way
|
|
1179
|
+
should say so explicitly in its Notes.
|
|
1180
|
+
|
|
1181
|
+
### 6.6 Relationship to `npm test`, restated decisively
|
|
1182
|
+
|
|
1183
|
+
- `npm test` (CI, every PR): mocked `dolt-settle` unit suite only
|
|
1184
|
+
(`test/dolt-settle.test.mjs`, scripted `command()`, no network, no fleet).
|
|
1185
|
+
- `npm run test:dolt-settle-integration`: this script; run manually from an
|
|
1186
|
+
orchestrator with a live fleet, and required -- all three members green,
|
|
1187
|
+
on pinned v2.2.0 (Preconditions V0/V1) -- before this branch's redesign is
|
|
1188
|
+
declared verified. It is intentionally NOT in any default CI pass, and no
|
|
1189
|
+
CI configuration should be added that pretends otherwise.
|
|
1190
|
+
|
|
1191
|
+
---
|
|
1192
|
+
|
|
1193
|
+
## Part 7 -- persistent vs. ephemeral `dolt sql-server`, answered precisely
|
|
1194
|
+
|
|
1195
|
+
The question: is there any harm in leaving the dolt server running? If
|
|
1196
|
+
multiple members share one OS, each with its own embedded-dolt database, can
|
|
1197
|
+
each simply have its own long-lived server -- is the only issue knowing which
|
|
1198
|
+
server belongs to which member?
|
|
1199
|
+
|
|
1200
|
+
### 7.1 Multiple members per machine, one server each: NOT a problem
|
|
1201
|
+
|
|
1202
|
+
Two (or N) independent `dolt sql-server` processes on the same machine, each
|
|
1203
|
+
bound to a distinct loopback port and pointed at a **distinct** `--data-dir`,
|
|
1204
|
+
have no meaningful interaction. This is confirmed against Dolt's own storage
|
|
1205
|
+
architecture, not assumed: every lock Dolt takes lives *inside the served
|
|
1206
|
+
data directory* -- the chunk-journal filesystem lock and the
|
|
1207
|
+
`sql-server.info` running-server marker are both per-`.dolt`-dir artifacts --
|
|
1208
|
+
so two servers over two directories share nothing but ordinary OS resources
|
|
1209
|
+
(CPU, RAM, disk bandwidth) and the port namespace, which distinct ports
|
|
1210
|
+
resolve by construction. There is no global dolt registry, no shared lock, no
|
|
1211
|
+
cross-database state.
|
|
1212
|
+
|
|
1213
|
+
And "which server belongs to which member" is, exactly as the question
|
|
1214
|
+
suspects, trivial bookkeeping, not a hard problem: each member's own
|
|
1215
|
+
`.beads/metadata.json` already records its dolt routing (`dolt_mode`, and
|
|
1216
|
+
host:port when in server mode -- the very fields `bd dolt status` reports,
|
|
1217
|
+
Part 3.2 step 0). Member-local config records a member-local port; no
|
|
1218
|
+
cross-member coordination is ever needed. **So per-member servers were never
|
|
1219
|
+
rejected because of identification or co-tenancy. That was not the reason.**
|
|
1220
|
+
For the ephemeral design, co-tenancy needs only one sentence of care: the
|
|
1221
|
+
port-range probe in Part 3.2 step 2 already makes concurrent settles on two
|
|
1222
|
+
co-located members pick different ports.
|
|
1223
|
+
|
|
1224
|
+
### 7.2 The real risk -- same data dir, two engines -- and its true severity
|
|
1225
|
+
|
|
1226
|
+
The hazard is the SAME member's data dir being open in two engines at once:
|
|
1227
|
+
bd in embedded mode (which links Dolt's own storage libraries in-process) and
|
|
1228
|
+
a separate `dolt sql-server`, both on one `--data-dir`.
|
|
1229
|
+
|
|
1230
|
+
What actually happens, per Dolt's storage design (verified against upstream,
|
|
1231
|
+
consistent with this repo's prior findings): Dolt's chunk store is guarded by
|
|
1232
|
+
a **per-directory exclusive-access lock** -- the sql-server acquires
|
|
1233
|
+
exclusive access via a filesystem lock on the chunk journal and drops a
|
|
1234
|
+
`sql-server.info` marker; the chunk journal itself is a **single-writer,
|
|
1235
|
+
append-only** persistence structure, and manifest updates flow through that
|
|
1236
|
+
same held lock. A second dolt-based process attempting to open the same
|
|
1237
|
+
directory for writing does not silently corrupt anything -- it **fails
|
|
1238
|
+
closed**: it either errors ("database is locked to another dolt process" /
|
|
1239
|
+
`ErrDatabaseLocked`) or degrades to read-only. Since bd embeds these same
|
|
1240
|
+
libraries, bd participates in the same protocol.
|
|
1241
|
+
|
|
1242
|
+
Two consequences, stated plainly:
|
|
1243
|
+
|
|
1244
|
+
1. **This design's corruption anxiety was over-cautious.** Concurrent
|
|
1245
|
+
dual-engine access to one data dir is not a demonstrated
|
|
1246
|
+
corrupt-the-chunk-store hazard; it is a deterministic
|
|
1247
|
+
**lock-failure/availability** hazard. The 5mqg incident's damage was an
|
|
1248
|
+
orphaned server *holding the lock and wedging subsequent embedded bd
|
|
1249
|
+
commands* plus un-reverted routing state -- not chunk-store corruption.
|
|
1250
|
+
2. **It exposes a real ordering bug in Part 3.2, corrected there:** step 5
|
|
1251
|
+
was originally written to run `bd dolt pull` / `bd dolt push`
|
|
1252
|
+
(embedded-mode bd, which must open the data dir) while the ephemeral
|
|
1253
|
+
server was still up -- teardown was only step 6. Embedded bd would hit the
|
|
1254
|
+
server's exclusive lock and fail or fall back read-only. Part 3.2 above
|
|
1255
|
+
has been corrected in place: tear the server down FIRST -- kill the
|
|
1256
|
+
recorded pid and verify the port closed -- and only then run the
|
|
1257
|
+
republish. The `finally` teardown remains as the guarantee for throw
|
|
1258
|
+
paths; the happy path simply reaches it before, not after, republishing.
|
|
1259
|
+
|
|
1260
|
+
### 7.3 Option C -- permanent per-member server, bd committed to server mode
|
|
1261
|
+
|
|
1262
|
+
Option C: run one ALWAYS-ON `dolt sql-server` per member and flip that
|
|
1263
|
+
member's bd permanently to `dolt_mode: "server"` against it -- no embedded
|
|
1264
|
+
mode, no ephemeral side-channel. Evaluated on its actual merits:
|
|
1265
|
+
|
|
1266
|
+
- **Does it eliminate the detachment headache? No -- it converts it into a
|
|
1267
|
+
permanently-owned service-management problem.** The WMI dance exists
|
|
1268
|
+
because a process must outlive an SSH session. An always-on server must
|
|
1269
|
+
additionally outlive **reboots and crashes**, which on Windows means a real
|
|
1270
|
+
Windows Service -- requiring admin rights, which the fleet's install
|
|
1271
|
+
posture explicitly does not have (`dolt-install.ts` line 10: "no
|
|
1272
|
+
admin/system install needed"; the entire `BIN_DIR` design exists to avoid
|
|
1273
|
+
elevation) -- or a scheduled task, which is *proven broken* in this exact
|
|
1274
|
+
environment (`SCHED_S_TASK_QUEUED`, no interactive logon: the
|
|
1275
|
+
apra-fleet-i8qj failure, re-reproduced live in
|
|
1276
|
+
`dolt-manual-recovery-verified.md` step 2). The remaining option is a
|
|
1277
|
+
WMI-spawned session-0 process plus a bespoke supervisor watchdog for
|
|
1278
|
+
liveness, restart, and stale-port recovery, per member, forever. That is
|
|
1279
|
+
strictly MORE operational machinery than a 10-30 second ephemeral spawn
|
|
1280
|
+
whose entire lifecycle sits inside one `try/finally`. (Linux systemd user
|
|
1281
|
+
units need lingering enabled; macOS launchd is workable; but the design
|
|
1282
|
+
must be uniform across a Windows-heavy fleet, and Windows is the hard
|
|
1283
|
+
case.)
|
|
1284
|
+
- **It reopens ga61's risk surface, permanently, for everything.** The
|
|
1285
|
+
corrected ga61 finding is precise: the interactive credential-prompt bug is
|
|
1286
|
+
specific to the raw manually-invoked dolt CLI with explicit
|
|
1287
|
+
`--user`/`--password` -- but bd's OWN compiled client in server mode
|
|
1288
|
+
showed a separate, real, live failure ("database 'beads' not found on Dolt
|
|
1289
|
+
server", suspected server-readiness race). Under Option C, **every bd
|
|
1290
|
+
command on that member, in every dispatch, forever** runs through that
|
|
1291
|
+
least-proven client path -- reintroducing at per-member scope the exact
|
|
1292
|
+
argument that killed full centralization in Part 2.1(1). The ephemeral
|
|
1293
|
+
design keeps bd embedded 100% of the time and exposes only the raw dolt
|
|
1294
|
+
CLI (with the fixed, verified flag set) to a server, for seconds. Settle
|
|
1295
|
+
never routes bd through a server at all.
|
|
1296
|
+
- **It adds an availability coupling embedded mode does not have.** Server
|
|
1297
|
+
down (crash, reboot, upgrade window) means every bd command on that member
|
|
1298
|
+
fails until the watchdog wins -- Part 2.1(2)'s total-availability argument,
|
|
1299
|
+
at member scope. Embedded bd has no liveness dependency.
|
|
1300
|
+
- **Security surface:** an always-listening loopback port whose
|
|
1301
|
+
authentication is the documented root/empty-password default (the very
|
|
1302
|
+
default settle exploits to avoid the credential bug) makes the member's
|
|
1303
|
+
full beads DB writable by any local process, indefinitely -- times N
|
|
1304
|
+
members per host. Loopback-only, so not critical, but it is a standing
|
|
1305
|
+
surface bought for zero functional gain, versus one that exists for
|
|
1306
|
+
seconds under a recorded pid.
|
|
1307
|
+
|
|
1308
|
+
### 7.4 Decision
|
|
1309
|
+
|
|
1310
|
+
**Keep the ephemeral design of Part 2, amended with the 7.2 ordering fix
|
|
1311
|
+
(teardown before republish).** Per-member persistent servers are not rejected
|
|
1312
|
+
because of co-tenancy or server-identification -- 7.1 shows those concerns
|
|
1313
|
+
are empty -- but because Option C buys nothing the ephemeral design lacks
|
|
1314
|
+
(the conflict path is rare and takes seconds) at the cost of: a permanent
|
|
1315
|
+
per-member service-management subsystem with no admin-free Windows story, a
|
|
1316
|
+
permanent commitment of every bd command to the fleet's least-proven client
|
|
1317
|
+
path (the live ga61-class readiness failure), a new availability coupling,
|
|
1318
|
+
and a standing open port.
|
|
1319
|
+
|
|
1320
|
+
Revisit Option C only when ALL of the following hold, none of which hold
|
|
1321
|
+
today: (1) bd's server-mode client has closed the ga61-class races with
|
|
1322
|
+
regression evidence, (2) the fleet has an elevation-capable,
|
|
1323
|
+
cross-OS-uniform service management story, and (3) conflict/settle frequency
|
|
1324
|
+
is demonstrably high enough that per-settle server spawns are a measured
|
|
1325
|
+
throughput problem. Until then, embedded-always plus ephemeral-settle is the
|
|
1326
|
+
configuration every piece of live evidence in this document actually
|
|
1327
|
+
supports.
|
|
1328
|
+
|
|
1329
|
+
---
|
|
1330
|
+
|
|
1331
|
+
## Part 8 -- beads to evaluate once this work lands
|
|
1332
|
+
|
|
1333
|
+
A deep search of the shared beads DB (`bd search`, plus reading every hit and
|
|
1334
|
+
its parent/child chain in full) turned up more than the two P0s this design
|
|
1335
|
+
was already tracking. Several closed beads' close reasons are directly
|
|
1336
|
+
contradicted by evidence gathered in the course of this design, and there is
|
|
1337
|
+
a whole parent epic whose disposition assumed the old ladder was working.
|
|
1338
|
+
None of this list should be actioned automatically -- each item needs a
|
|
1339
|
+
deliberate close/reopen/comment decision once `dolt-settle.mjs` actually
|
|
1340
|
+
lands and passes the Part 6 integration script, not before.
|
|
1341
|
+
|
|
1342
|
+
**EXECUTED 2026-08-13**, after Part 4's live 3-OS pass. What was actually done,
|
|
1343
|
+
so the list below reads as history rather than as a pending action:
|
|
1344
|
+
|
|
1345
|
+
- 8.1 -- `apra-fleet-ga61` and `apra-fleet-5mqg`: CLOSED, each with an
|
|
1346
|
+
evidence comment citing the shipped code, the commit range, and the live
|
|
1347
|
+
3-OS table. ga61's close comment explicitly scopes OUT the separate bd-side
|
|
1348
|
+
auto-start "database not found" readiness race, which this work does not
|
|
1349
|
+
claim to fix (it did not occur in any live run -- bd stayed embedded).
|
|
1350
|
+
- 8.2 -- `apra-fleet-vkc` and `apra-fleet-vkc.1`: NOT reopened; each received
|
|
1351
|
+
a superseding comment correcting its inaccurate close reason (the ladder was
|
|
1352
|
+
"wired" only in the literal sense) and recording that option (b),
|
|
1353
|
+
decommission, is what finally shipped. `apra-fleet-vkc.2`: comment only, its
|
|
1354
|
+
narrower claim was and remains true.
|
|
1355
|
+
- 8.3 -- `apra-fleet-417`: bookkeeping comment only; status untouched and
|
|
1356
|
+
`apra-fleet-66u` deliberately not touched. `apra-fleet-k7b.4` / `k7b.8`:
|
|
1357
|
+
naming/semantics comment only, no reopen -- `BEADS_SYNC_CONFLICT` is kept
|
|
1358
|
+
as-is (public terminal string) despite now firing only on operational
|
|
1359
|
+
failure.
|
|
1360
|
+
- 8.4 -- `apra-fleet-iiny`: not touched. The exclusion was made doc-side
|
|
1361
|
+
instead, in `escalate-to-llm-design.md` (Dolt/beads-sync wedging is out of
|
|
1362
|
+
sprint-doctor's symptom scope, pointing here).
|
|
1363
|
+
- 8.5 -- no action taken, as specified.
|
|
1364
|
+
|
|
1365
|
+
### 8.1 Close once settle() lands and is verified (Part 4/6 green on all 3 OSes)
|
|
1366
|
+
|
|
1367
|
+
- **`apra-fleet-ga61`** (P0, open) -- "bd/Dolt network client fails on
|
|
1368
|
+
Windows in non-interactive sessions." Settle's design closes this at the
|
|
1369
|
+
root: bd stays embedded 100% of the time (Part 7.2/7.4's decision), and
|
|
1370
|
+
the only code that ever talks to a `dolt sql-server` is settle's own raw
|
|
1371
|
+
CLI invocation using the exact fixed, landmine-safe flag set (Parts 3.2,
|
|
1372
|
+
5.5-5.6). Close with a comment citing the shipped `dolt-settle.mjs` and the
|
|
1373
|
+
Part 4 verification log as evidence, not just the design doc.
|
|
1374
|
+
- **`apra-fleet-5mqg`** (P0, open) -- "Tier 2's server-mode revert is an LLM
|
|
1375
|
+
instruction step, not a guaranteed rollback." Directly and completely
|
|
1376
|
+
closed by this redesign: there is no more LLM-driven Tier 2 in the
|
|
1377
|
+
recovery path (Part 2.4/2.5), and settle's teardown is a real code
|
|
1378
|
+
`finally` (Part 3.2 step 6) plus a supervisor orphan sweep (Part 3.3) as a
|
|
1379
|
+
second layer. Close once the Part 6 script's residue assertions (6.5.6e)
|
|
1380
|
+
pass on all 3 OSes -- that is the actual regression test for this bead.
|
|
1381
|
+
|
|
1382
|
+
### 8.2 Reopen with evidence -- closed on a claim this design's own investigation disproves
|
|
1383
|
+
|
|
1384
|
+
- **`apra-fleet-vkc`** (closed 2026-08-10, "Wire or decommission the existing
|
|
1385
|
+
dolt-recovery ladder... currently unwired, same failure pattern as the
|
|
1386
|
+
id-allocator/mutex") -- close reason states "ladder wired as internal
|
|
1387
|
+
detail of dolt-sync.mjs." This is misleading at best: per Part 1.4 of this
|
|
1388
|
+
document, confirmed against `runner.js:1142` and 4 independent live sprint
|
|
1389
|
+
incidents, Path A is reached but its precondition guard throws on every
|
|
1390
|
+
single invocation (no `sql`/`spawnSqlServer` ever injected), and Path B is
|
|
1391
|
+
deliberately disabled -- so in production only Tier 2 (the LLM escalation)
|
|
1392
|
+
ever does anything. "Wired" in the literal sense (the function is called)
|
|
1393
|
+
is true; "wired" in the sense the bead title implies (capable of resolving
|
|
1394
|
+
a conflict without an LLM) is false. Reopen with this evidence, OR -- more
|
|
1395
|
+
likely the right call given settle() replaces the whole ladder outright --
|
|
1396
|
+
close it again for real once settle() ships, with a comment that
|
|
1397
|
+
supersedes the original (now-inaccurate) close reason rather than letting
|
|
1398
|
+
a false claim stand uncorrected in the historical record.
|
|
1399
|
+
- **`apra-fleet-vkc.1`** (closed 2026-08-10, "Decide and execute: wire the
|
|
1400
|
+
dolt-recovery ladder into doltPushAfter() or decommission it") -- close
|
|
1401
|
+
reason cites "39/39 ladder unit tests, 14/14 wiring-shape test" passing.
|
|
1402
|
+
Those tests verify the *shape* of the wiring (opts flow through correctly,
|
|
1403
|
+
`enablePathB:false` is set) -- they do not appear to assert Path A ever
|
|
1404
|
+
successfully resolves a conflict with a real `sql()` runtime, which this
|
|
1405
|
+
design's own investigation shows was never possible in production. Same
|
|
1406
|
+
disposition as `vkc`: reopen with evidence, or supersede via a comment once
|
|
1407
|
+
settle() lands and the ladder modules it replaces are deleted.
|
|
1408
|
+
- **`apra-fleet-vkc.2`** (closed 2026-08-10, "doltPushAfter conflict path
|
|
1409
|
+
reaches the recovery ladder (or ladder is provably absent)") -- narrower
|
|
1410
|
+
claim than vkc/vkc.1 ("reaches the ladder", not "the ladder resolves
|
|
1411
|
+
anything"), and that narrower claim does appear to still be literally true
|
|
1412
|
+
(Tier 2 is genuinely reached). Lower priority than vkc/vkc.1 -- just needs
|
|
1413
|
+
a comment once settle() lands noting the ladder it verified reaching has
|
|
1414
|
+
been replaced, not a reopen.
|
|
1415
|
+
|
|
1416
|
+
### 8.3 Review, not necessarily close -- epic and terminal-classification beads whose premises shift under this redesign
|
|
1417
|
+
|
|
1418
|
+
- **`apra-fleet-417`** (P1, open epic, "fleet-sprint dolt sync must be
|
|
1419
|
+
fault-tolerant") -- 9/10 children closed; the ONE thing keeping it open is
|
|
1420
|
+
`apra-fleet-66u`, an unrelated stall-detection-scoring bug that has nothing
|
|
1421
|
+
to do with dolt sync (confirmed by reading 66u's own description). So this
|
|
1422
|
+
epic is not blocked on dolt-sync work today -- BUT its own recorded
|
|
1423
|
+
disposition explicitly maps its "dolt-recovery-ladder" acceptance criterion
|
|
1424
|
+
onto `apra-fleet-vkc`/`vkc.1`/`vkc.2` ("live, under a different sprint
|
|
1425
|
+
root"), which 8.2 above shows was an inaccurate closure. Action: once
|
|
1426
|
+
settle() lands, add a comment to `apra-fleet-417` noting that the ladder
|
|
1427
|
+
criterion it deferred to vkc/vkc.1/vkc.2 has now been superseded by
|
|
1428
|
+
`dolt-settle.mjs`, so the epic's own acceptance criteria still fully hold
|
|
1429
|
+
(arguably more completely than before) -- this is a bookkeeping update, not
|
|
1430
|
+
a reopen, and should NOT touch `66u`'s unrelated blocking status.
|
|
1431
|
+
- **`apra-fleet-k7b.4`** (closed, "Classify unmergeable beads Dolt conflicts
|
|
1432
|
+
as their own terminal state (BEADS_SYNC_CONFLICT)") and **`apra-fleet-
|
|
1433
|
+
k7b.8`** (closed, "[test] DOLT_DIVERGED surfaces as BEADS_SYNC_CONFLICT
|
|
1434
|
+
with captured conflict dump") -- not wrong, and not to be reopened; both
|
|
1435
|
+
describe real, still-correct behavior for settle's own genuine operational
|
|
1436
|
+
failures (Part 5.3's typed `DoltBinaryUnavailableError` and similar should
|
|
1437
|
+
still be able to surface as a `BEADS_SYNC_CONFLICT`-class terminal, or a
|
|
1438
|
+
clearly-named sibling, when settle itself cannot complete). Action: once
|
|
1439
|
+
settle() lands, review whether `BEADS_SYNC_CONFLICT` is still the right
|
|
1440
|
+
terminal name/semantics given that under the new design it should fire
|
|
1441
|
+
drastically less often (only on a genuine operational failure, never on an
|
|
1442
|
+
ordinary resolvable conflict) -- a naming/semantics comment update at most,
|
|
1443
|
+
not a functional change these beads need to re-litigate.
|
|
1444
|
+
|
|
1445
|
+
### 8.4 Cross-reference, do not touch -- a parallel initiative this design must not collide with
|
|
1446
|
+
|
|
1447
|
+
- **`apra-fleet-iiny`** (P2, open epic, "sprint-doctor: LLM-escalation
|
|
1448
|
+
mechanism for stalled/wedged fleet-sprint runs", 0/8 children, not
|
|
1449
|
+
started) -- a general-purpose, NOT dolt-specific, symptom/remedy registry
|
|
1450
|
+
for stalled/wedged sprints of any kind, actively being designed in
|
|
1451
|
+
parallel (see `packages/apra-fleet-se/fleet-sprint/docs/shared-
|
|
1452
|
+
orchestrator-reservation-design.md` and the most recent commit on this
|
|
1453
|
+
repo at design-doc-writing time). This is not a beads-hygiene item to close
|
|
1454
|
+
or reopen -- it is a real risk of architectural collision: once
|
|
1455
|
+
`dolt-settle.mjs` ships, Dolt conflicts must NOT become one of
|
|
1456
|
+
sprint-doctor's LLM-escalatable "symptoms" -- that would silently
|
|
1457
|
+
reintroduce the exact LLM-driven, no-guaranteed-rollback recovery class
|
|
1458
|
+
this whole redesign exists to eliminate (Part 2, Part 7.4). Action: when
|
|
1459
|
+
sprint-doctor's symptom/remedy registry (`apra-fleet-iiny.3`) is designed,
|
|
1460
|
+
cross-link it to this document and explicitly exclude Dolt/beads-sync
|
|
1461
|
+
wedging from its scope -- settle() (and its typed operational-failure
|
|
1462
|
+
throw, per Part 5.3) is the terminal answer for that failure class, not a
|
|
1463
|
+
sprint-doctor escalation.
|
|
1464
|
+
|
|
1465
|
+
### 8.5 Noted, out of scope -- found during the search, not related
|
|
1466
|
+
|
|
1467
|
+
- **`apra-fleet-spp`** (closed, auth-vs-divergence misclassification fix) --
|
|
1468
|
+
already correctly fixed in `dolt-sync.mjs`'s classification layer; settle()
|
|
1469
|
+
does not touch G-push/D-push classification and should not disturb this.
|
|
1470
|
+
No action.
|
|
1471
|
+
- **`apra-fleet-eft.17.3`** (closed, golden-transcript no-remote D-pull
|
|
1472
|
+
gating) -- test-harness/golden-fixture issue, orthogonal to settle(). No
|
|
1473
|
+
action.
|
|
1474
|
+
- **`apra-fleet-xuo.1`** (closed, committed the operator runbook) -- already
|
|
1475
|
+
done; `docs/dolt-operator-conflict-runbook.md` still needs the pointer
|
|
1476
|
+
update noted in Part 2.5, but that is tracked in this document already, not
|
|
1477
|
+
a reason to reopen xuo.1 itself.
|
|
1478
|
+
- **`apra-fleet-4j2`** (P2, open, "integ-test-runner reported filing
|
|
1479
|
+
apra-fleet-bnb.1... bead does not exist") -- a Dolt-DB-adjacent data
|
|
1480
|
+
integrity bug (a filed bead reference vanished), but not a sync/conflict
|
|
1481
|
+
issue and not something settle() affects. Left open, unrelated.
|
|
1482
|
+
|