@apralabs/apra-fleet 0.4.0 → 0.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (427) hide show
  1. package/README.md +145 -7
  2. package/dist/agents/backlog-groomer.md +17 -1
  3. package/dist/agents/ci-watcher.md +13 -1
  4. package/dist/agents/deployer.md +15 -3
  5. package/dist/agents/doer.md +35 -1
  6. package/dist/agents/harvester.md +22 -3
  7. package/dist/agents/integ-test-runner.md +18 -2
  8. package/dist/agents/kb-reconciler.md +216 -0
  9. package/dist/agents/plan-reviewer.md +14 -1
  10. package/dist/agents/planner.md +88 -5
  11. package/dist/agents/regression-test-runner.md +19 -1
  12. package/dist/agents/reviewer.md +104 -3
  13. package/dist/agents/schemas/doer-output.json +63 -3
  14. package/dist/agents/schemas/harvester-output.json +59 -2
  15. package/dist/agents/schemas/integ-test-runner-output.json +2 -2
  16. package/dist/agents/schemas/kb-reconciler-output.json +87 -0
  17. package/dist/agents/schemas/planner-output.json +65 -0
  18. package/dist/agents/schemas/reviewer-output.json +105 -8
  19. package/dist/cli/install.d.ts +1 -0
  20. package/dist/cli/install.d.ts.map +1 -1
  21. package/dist/cli/install.js +136 -5
  22. package/dist/cli/install.js.map +1 -1
  23. package/dist/cli/join.js +1 -1
  24. package/dist/cli/join.js.map +1 -1
  25. package/dist/cli/kb-commit.d.ts +12 -0
  26. package/dist/cli/kb-commit.d.ts.map +1 -0
  27. package/dist/cli/kb-commit.js +53 -0
  28. package/dist/cli/kb-commit.js.map +1 -0
  29. package/dist/cli/kb-directives.d.ts +17 -0
  30. package/dist/cli/kb-directives.d.ts.map +1 -0
  31. package/dist/cli/kb-directives.js +146 -0
  32. package/dist/cli/kb-directives.js.map +1 -0
  33. package/dist/cli/kb-import.d.ts +13 -0
  34. package/dist/cli/kb-import.d.ts.map +1 -0
  35. package/dist/cli/kb-import.js +56 -0
  36. package/dist/cli/kb-import.js.map +1 -0
  37. package/dist/cli/uninstall.d.ts.map +1 -1
  38. package/dist/cli/uninstall.js +11 -0
  39. package/dist/cli/uninstall.js.map +1 -1
  40. package/dist/cli/watch.d.ts +53 -4
  41. package/dist/cli/watch.d.ts.map +1 -1
  42. package/dist/cli/watch.js +118 -17
  43. package/dist/cli/watch.js.map +1 -1
  44. package/dist/commands/kb-server.d.ts +8 -0
  45. package/dist/commands/kb-server.d.ts.map +1 -0
  46. package/dist/commands/kb-server.js +221 -0
  47. package/dist/commands/kb-server.js.map +1 -0
  48. package/dist/index.js +77 -2
  49. package/dist/index.js.map +1 -1
  50. package/dist/os/linux.d.ts +1 -0
  51. package/dist/os/linux.d.ts.map +1 -1
  52. package/dist/os/linux.js +18 -1
  53. package/dist/os/linux.js.map +1 -1
  54. package/dist/os/os-commands.d.ts +5 -0
  55. package/dist/os/os-commands.d.ts.map +1 -1
  56. package/dist/os/windows.d.ts +35 -0
  57. package/dist/os/windows.d.ts.map +1 -1
  58. package/dist/os/windows.js +67 -31
  59. package/dist/os/windows.js.map +1 -1
  60. package/dist/providers/agy.d.ts +12 -1
  61. package/dist/providers/agy.d.ts.map +1 -1
  62. package/dist/providers/agy.js +134 -9
  63. package/dist/providers/agy.js.map +1 -1
  64. package/dist/providers/claude.d.ts +11 -1
  65. package/dist/providers/claude.d.ts.map +1 -1
  66. package/dist/providers/claude.js +47 -19
  67. package/dist/providers/claude.js.map +1 -1
  68. package/dist/providers/codex.d.ts +11 -1
  69. package/dist/providers/codex.d.ts.map +1 -1
  70. package/dist/providers/codex.js +29 -6
  71. package/dist/providers/codex.js.map +1 -1
  72. package/dist/providers/copilot.d.ts +11 -1
  73. package/dist/providers/copilot.d.ts.map +1 -1
  74. package/dist/providers/copilot.js +26 -6
  75. package/dist/providers/copilot.js.map +1 -1
  76. package/dist/providers/email/headers.d.ts +15 -0
  77. package/dist/providers/email/headers.d.ts.map +1 -0
  78. package/dist/providers/email/headers.js +42 -0
  79. package/dist/providers/email/headers.js.map +1 -0
  80. package/dist/providers/email/index.d.ts +18 -0
  81. package/dist/providers/email/index.d.ts.map +1 -0
  82. package/dist/providers/email/index.js +60 -0
  83. package/dist/providers/email/index.js.map +1 -0
  84. package/dist/providers/email/provider.d.ts +49 -0
  85. package/dist/providers/email/provider.d.ts.map +1 -0
  86. package/dist/providers/email/provider.js +2 -0
  87. package/dist/providers/email/provider.js.map +1 -0
  88. package/dist/providers/email/sendgrid.d.ts +12 -0
  89. package/dist/providers/email/sendgrid.d.ts.map +1 -0
  90. package/dist/providers/email/sendgrid.js +67 -0
  91. package/dist/providers/email/sendgrid.js.map +1 -0
  92. package/dist/providers/email/smtp.d.ts +65 -0
  93. package/dist/providers/email/smtp.d.ts.map +1 -0
  94. package/dist/providers/email/smtp.js +373 -0
  95. package/dist/providers/email/smtp.js.map +1 -0
  96. package/dist/providers/gemini.d.ts +11 -1
  97. package/dist/providers/gemini.d.ts.map +1 -1
  98. package/dist/providers/gemini.js +38 -4
  99. package/dist/providers/gemini.js.map +1 -1
  100. package/dist/providers/none.d.ts +11 -1
  101. package/dist/providers/none.d.ts.map +1 -1
  102. package/dist/providers/none.js +21 -0
  103. package/dist/providers/none.js.map +1 -1
  104. package/dist/providers/opencode.d.ts +11 -1
  105. package/dist/providers/opencode.d.ts.map +1 -1
  106. package/dist/providers/opencode.js +55 -4
  107. package/dist/providers/opencode.js.map +1 -1
  108. package/dist/providers/provider.d.ts +77 -0
  109. package/dist/providers/provider.d.ts.map +1 -1
  110. package/dist/providers/provider.js +44 -0
  111. package/dist/providers/provider.js.map +1 -1
  112. package/dist/services/agent-provisioner.d.ts.map +1 -1
  113. package/dist/services/agent-provisioner.js +3 -6
  114. package/dist/services/agent-provisioner.js.map +1 -1
  115. package/dist/services/cloud/lifecycle.d.ts.map +1 -1
  116. package/dist/services/cloud/lifecycle.js +3 -0
  117. package/dist/services/cloud/lifecycle.js.map +1 -1
  118. package/dist/services/cloud/task-wrapper.d.ts +18 -0
  119. package/dist/services/cloud/task-wrapper.d.ts.map +1 -1
  120. package/dist/services/cloud/task-wrapper.js +157 -0
  121. package/dist/services/cloud/task-wrapper.js.map +1 -1
  122. package/dist/services/github-app.d.ts.map +1 -1
  123. package/dist/services/github-app.js +11 -2
  124. package/dist/services/github-app.js.map +1 -1
  125. package/dist/services/knowledge/audn.d.ts +37 -0
  126. package/dist/services/knowledge/audn.d.ts.map +1 -0
  127. package/dist/services/knowledge/audn.js +219 -0
  128. package/dist/services/knowledge/audn.js.map +1 -0
  129. package/dist/services/knowledge/file-hash.d.ts +11 -0
  130. package/dist/services/knowledge/file-hash.d.ts.map +1 -0
  131. package/dist/services/knowledge/file-hash.js +123 -0
  132. package/dist/services/knowledge/file-hash.js.map +1 -0
  133. package/dist/services/knowledge/http-provider.d.ts +46 -0
  134. package/dist/services/knowledge/http-provider.d.ts.map +1 -0
  135. package/dist/services/knowledge/http-provider.js +254 -0
  136. package/dist/services/knowledge/http-provider.js.map +1 -0
  137. package/dist/services/knowledge/kb-providers.d.ts +15 -0
  138. package/dist/services/knowledge/kb-providers.d.ts.map +1 -0
  139. package/dist/services/knowledge/kb-providers.js +92 -0
  140. package/dist/services/knowledge/kb-providers.js.map +1 -0
  141. package/dist/services/knowledge/kb-scope-input.d.ts +5 -0
  142. package/dist/services/knowledge/kb-scope-input.d.ts.map +1 -0
  143. package/dist/services/knowledge/kb-scope-input.js +11 -0
  144. package/dist/services/knowledge/kb-scope-input.js.map +1 -0
  145. package/dist/services/knowledge/kb-service.d.ts +3 -0
  146. package/dist/services/knowledge/kb-service.d.ts.map +1 -0
  147. package/dist/services/knowledge/kb-service.js +2 -0
  148. package/dist/services/knowledge/kb-service.js.map +1 -0
  149. package/dist/services/knowledge/path-validation.d.ts +2 -0
  150. package/dist/services/knowledge/path-validation.d.ts.map +1 -0
  151. package/dist/services/knowledge/path-validation.js +13 -0
  152. package/dist/services/knowledge/path-validation.js.map +1 -0
  153. package/dist/services/knowledge/pre-init.d.ts +14 -0
  154. package/dist/services/knowledge/pre-init.d.ts.map +1 -0
  155. package/dist/services/knowledge/pre-init.js +147 -0
  156. package/dist/services/knowledge/pre-init.js.map +1 -0
  157. package/dist/services/knowledge/project-slug.d.ts +2 -0
  158. package/dist/services/knowledge/project-slug.d.ts.map +1 -0
  159. package/dist/services/knowledge/project-slug.js +49 -0
  160. package/dist/services/knowledge/project-slug.js.map +1 -0
  161. package/dist/services/knowledge/sqlite-provider.d.ts +147 -0
  162. package/dist/services/knowledge/sqlite-provider.d.ts.map +1 -0
  163. package/dist/services/knowledge/sqlite-provider.js +1646 -0
  164. package/dist/services/knowledge/sqlite-provider.js.map +1 -0
  165. package/dist/services/knowledge/types.d.ts +163 -0
  166. package/dist/services/knowledge/types.d.ts.map +1 -0
  167. package/dist/services/knowledge/types.js +9 -0
  168. package/dist/services/knowledge/types.js.map +1 -0
  169. package/dist/services/member-home.d.ts +89 -0
  170. package/dist/services/member-home.d.ts.map +1 -0
  171. package/dist/services/member-home.js +256 -0
  172. package/dist/services/member-home.js.map +1 -0
  173. package/dist/services/member-remote-url.d.ts +34 -0
  174. package/dist/services/member-remote-url.d.ts.map +1 -0
  175. package/dist/services/member-remote-url.js +39 -0
  176. package/dist/services/member-remote-url.js.map +1 -0
  177. package/dist/services/orphan-recovery.d.ts +5 -2
  178. package/dist/services/orphan-recovery.d.ts.map +1 -1
  179. package/dist/services/orphan-recovery.js +19 -8
  180. package/dist/services/orphan-recovery.js.map +1 -1
  181. package/dist/services/preflight-check.d.ts +56 -0
  182. package/dist/services/preflight-check.d.ts.map +1 -0
  183. package/dist/services/preflight-check.js +277 -0
  184. package/dist/services/preflight-check.js.map +1 -0
  185. package/dist/services/stall/log-path-resolver.d.ts +11 -8
  186. package/dist/services/stall/log-path-resolver.d.ts.map +1 -1
  187. package/dist/services/stall/log-path-resolver.js +17 -40
  188. package/dist/services/stall/log-path-resolver.js.map +1 -1
  189. package/dist/services/stall/stall-detector.d.ts +32 -0
  190. package/dist/services/stall/stall-detector.d.ts.map +1 -1
  191. package/dist/services/stall/stall-detector.js +149 -6
  192. package/dist/services/stall/stall-detector.js.map +1 -1
  193. package/dist/services/stall/stall-poller.d.ts +34 -0
  194. package/dist/services/stall/stall-poller.d.ts.map +1 -1
  195. package/dist/services/stall/stall-poller.js +134 -2
  196. package/dist/services/stall/stall-poller.js.map +1 -1
  197. package/dist/services/strategy.d.ts.map +1 -1
  198. package/dist/services/strategy.js +2 -2
  199. package/dist/services/strategy.js.map +1 -1
  200. package/dist/services/tool-registry.d.ts.map +1 -1
  201. package/dist/services/tool-registry.js +87 -1
  202. package/dist/services/tool-registry.js.map +1 -1
  203. package/dist/services/vcs/github.d.ts.map +1 -1
  204. package/dist/services/vcs/github.js +32 -1
  205. package/dist/services/vcs/github.js.map +1 -1
  206. package/dist/services/version-check.d.ts +22 -0
  207. package/dist/services/version-check.d.ts.map +1 -0
  208. package/dist/services/version-check.js +103 -0
  209. package/dist/services/version-check.js.map +1 -0
  210. package/dist/skills/fleet-sprint-cli/SKILL.md +13 -2
  211. package/dist/skills/pm/beads.md +6 -0
  212. package/dist/skills/pm/fleet-addendum.md +6 -0
  213. package/dist/skills/pm/index.md +56 -0
  214. package/dist/skills/pm/kb-reconcile.md +132 -0
  215. package/dist/skills/pm/kb-review.md +109 -0
  216. package/dist/tools/check-status.d.ts +47 -0
  217. package/dist/tools/check-status.d.ts.map +1 -1
  218. package/dist/tools/check-status.js +242 -0
  219. package/dist/tools/check-status.js.map +1 -1
  220. package/dist/tools/child-id-allocator.d.ts +2 -2
  221. package/dist/tools/code-intelligence-codebase-memory.d.ts +11 -0
  222. package/dist/tools/code-intelligence-codebase-memory.d.ts.map +1 -0
  223. package/dist/tools/code-intelligence-codebase-memory.js +270 -0
  224. package/dist/tools/code-intelligence-codebase-memory.js.map +1 -0
  225. package/dist/tools/code-intelligence-freshness.d.ts +2 -0
  226. package/dist/tools/code-intelligence-freshness.d.ts.map +1 -0
  227. package/dist/tools/code-intelligence-freshness.js +26 -0
  228. package/dist/tools/code-intelligence-freshness.js.map +1 -0
  229. package/dist/tools/code-intelligence-gitnexus.d.ts +14 -0
  230. package/dist/tools/code-intelligence-gitnexus.d.ts.map +1 -0
  231. package/dist/tools/code-intelligence-gitnexus.js +475 -0
  232. package/dist/tools/code-intelligence-gitnexus.js.map +1 -0
  233. package/dist/tools/code-intelligence-kb-enrich.d.ts +2 -0
  234. package/dist/tools/code-intelligence-kb-enrich.d.ts.map +1 -0
  235. package/dist/tools/code-intelligence-kb-enrich.js +65 -0
  236. package/dist/tools/code-intelligence-kb-enrich.js.map +1 -0
  237. package/dist/tools/code-intelligence-reindex.d.ts +7 -0
  238. package/dist/tools/code-intelligence-reindex.d.ts.map +1 -0
  239. package/dist/tools/code-intelligence-reindex.js +106 -0
  240. package/dist/tools/code-intelligence-reindex.js.map +1 -0
  241. package/dist/tools/code-intelligence-telemetry.d.ts +5 -0
  242. package/dist/tools/code-intelligence-telemetry.d.ts.map +1 -0
  243. package/dist/tools/code-intelligence-telemetry.js +52 -0
  244. package/dist/tools/code-intelligence-telemetry.js.map +1 -0
  245. package/dist/tools/code-intelligence-tests.d.ts +2 -0
  246. package/dist/tools/code-intelligence-tests.d.ts.map +1 -0
  247. package/dist/tools/code-intelligence-tests.js +24 -0
  248. package/dist/tools/code-intelligence-tests.js.map +1 -0
  249. package/dist/tools/code-intelligence.d.ts +114 -0
  250. package/dist/tools/code-intelligence.d.ts.map +1 -0
  251. package/dist/tools/code-intelligence.js +124 -0
  252. package/dist/tools/code-intelligence.js.map +1 -0
  253. package/dist/tools/compose-permissions.d.ts +26 -0
  254. package/dist/tools/compose-permissions.d.ts.map +1 -1
  255. package/dist/tools/compose-permissions.js +244 -33
  256. package/dist/tools/compose-permissions.js.map +1 -1
  257. package/dist/tools/execute-command.d.ts +2 -0
  258. package/dist/tools/execute-command.d.ts.map +1 -1
  259. package/dist/tools/execute-command.js +86 -16
  260. package/dist/tools/execute-command.js.map +1 -1
  261. package/dist/tools/execute-prompt.d.ts +13 -1
  262. package/dist/tools/execute-prompt.d.ts.map +1 -1
  263. package/dist/tools/execute-prompt.js +257 -45
  264. package/dist/tools/execute-prompt.js.map +1 -1
  265. package/dist/tools/kb-capture.d.ts +53 -0
  266. package/dist/tools/kb-capture.d.ts.map +1 -0
  267. package/dist/tools/kb-capture.js +130 -0
  268. package/dist/tools/kb-capture.js.map +1 -0
  269. package/dist/tools/kb-context.d.ts +17 -0
  270. package/dist/tools/kb-context.d.ts.map +1 -0
  271. package/dist/tools/kb-context.js +29 -0
  272. package/dist/tools/kb-context.js.map +1 -0
  273. package/dist/tools/kb-export.d.ts +19 -0
  274. package/dist/tools/kb-export.d.ts.map +1 -0
  275. package/dist/tools/kb-export.js +344 -0
  276. package/dist/tools/kb-export.js.map +1 -0
  277. package/dist/tools/kb-feedback.d.ts +23 -0
  278. package/dist/tools/kb-feedback.d.ts.map +1 -0
  279. package/dist/tools/kb-feedback.js +43 -0
  280. package/dist/tools/kb-feedback.js.map +1 -0
  281. package/dist/tools/kb-freshness-sweep.d.ts +14 -0
  282. package/dist/tools/kb-freshness-sweep.d.ts.map +1 -0
  283. package/dist/tools/kb-freshness-sweep.js +29 -0
  284. package/dist/tools/kb-freshness-sweep.js.map +1 -0
  285. package/dist/tools/kb-harvest.d.ts +20 -0
  286. package/dist/tools/kb-harvest.d.ts.map +1 -0
  287. package/dist/tools/kb-harvest.js +143 -0
  288. package/dist/tools/kb-harvest.js.map +1 -0
  289. package/dist/tools/kb-import.d.ts +44 -0
  290. package/dist/tools/kb-import.d.ts.map +1 -0
  291. package/dist/tools/kb-import.js +239 -0
  292. package/dist/tools/kb-import.js.map +1 -0
  293. package/dist/tools/kb-invalidate.d.ts +19 -0
  294. package/dist/tools/kb-invalidate.d.ts.map +1 -0
  295. package/dist/tools/kb-invalidate.js +34 -0
  296. package/dist/tools/kb-invalidate.js.map +1 -0
  297. package/dist/tools/kb-list.d.ts +32 -0
  298. package/dist/tools/kb-list.d.ts.map +1 -0
  299. package/dist/tools/kb-list.js +43 -0
  300. package/dist/tools/kb-list.js.map +1 -0
  301. package/dist/tools/kb-promote.d.ts +20 -0
  302. package/dist/tools/kb-promote.d.ts.map +1 -0
  303. package/dist/tools/kb-promote.js +20 -0
  304. package/dist/tools/kb-promote.js.map +1 -0
  305. package/dist/tools/kb-query.d.ts +35 -0
  306. package/dist/tools/kb-query.d.ts.map +1 -0
  307. package/dist/tools/kb-query.js +111 -0
  308. package/dist/tools/kb-query.js.map +1 -0
  309. package/dist/tools/kb-reconcile-prefilter.d.ts +14 -0
  310. package/dist/tools/kb-reconcile-prefilter.d.ts.map +1 -0
  311. package/dist/tools/kb-reconcile-prefilter.js +26 -0
  312. package/dist/tools/kb-reconcile-prefilter.js.map +1 -0
  313. package/dist/tools/kb-resolve-contradiction.d.ts +23 -0
  314. package/dist/tools/kb-resolve-contradiction.d.ts.map +1 -0
  315. package/dist/tools/kb-resolve-contradiction.js +37 -0
  316. package/dist/tools/kb-resolve-contradiction.js.map +1 -0
  317. package/dist/tools/kb-session-prime.d.ts +26 -0
  318. package/dist/tools/kb-session-prime.d.ts.map +1 -0
  319. package/dist/tools/kb-session-prime.js +392 -0
  320. package/dist/tools/kb-session-prime.js.map +1 -0
  321. package/dist/tools/kb-setup.d.ts +20 -0
  322. package/dist/tools/kb-setup.d.ts.map +1 -0
  323. package/dist/tools/kb-setup.js +49 -0
  324. package/dist/tools/kb-setup.js.map +1 -0
  325. package/dist/tools/kb-stats.d.ts +20 -0
  326. package/dist/tools/kb-stats.d.ts.map +1 -0
  327. package/dist/tools/kb-stats.js +115 -0
  328. package/dist/tools/kb-stats.js.map +1 -0
  329. package/dist/tools/member-detail.d.ts.map +1 -1
  330. package/dist/tools/member-detail.js +8 -0
  331. package/dist/tools/member-detail.js.map +1 -1
  332. package/dist/tools/monitor-task.d.ts.map +1 -1
  333. package/dist/tools/monitor-task.js +21 -3
  334. package/dist/tools/monitor-task.js.map +1 -1
  335. package/dist/tools/provision-auth.d.ts.map +1 -1
  336. package/dist/tools/provision-auth.js +10 -3
  337. package/dist/tools/provision-auth.js.map +1 -1
  338. package/dist/tools/register-member.d.ts +3 -0
  339. package/dist/tools/register-member.d.ts.map +1 -1
  340. package/dist/tools/register-member.js +30 -1
  341. package/dist/tools/register-member.js.map +1 -1
  342. package/dist/tools/remove-member.d.ts.map +1 -1
  343. package/dist/tools/remove-member.js +17 -3
  344. package/dist/tools/remove-member.js.map +1 -1
  345. package/dist/tools/report-status.d.ts.map +1 -1
  346. package/dist/tools/report-status.js +2 -1
  347. package/dist/tools/report-status.js.map +1 -1
  348. package/dist/tools/send-email.d.ts +69 -0
  349. package/dist/tools/send-email.d.ts.map +1 -0
  350. package/dist/tools/send-email.js +177 -0
  351. package/dist/tools/send-email.js.map +1 -0
  352. package/dist/tools/setup-ssh-key.d.ts.map +1 -1
  353. package/dist/tools/setup-ssh-key.js +2 -0
  354. package/dist/tools/setup-ssh-key.js.map +1 -1
  355. package/dist/tools/update-member.d.ts +3 -0
  356. package/dist/tools/update-member.d.ts.map +1 -1
  357. package/dist/tools/update-member.js +25 -1
  358. package/dist/tools/update-member.js.map +1 -1
  359. package/dist/types.d.ts +1 -0
  360. package/dist/types.d.ts.map +1 -1
  361. package/dist/utils/prompt-errors.js +1 -1
  362. package/dist/utils/prompt-errors.js.map +1 -1
  363. package/dist/utils/session-caller.d.ts +28 -0
  364. package/dist/utils/session-caller.d.ts.map +1 -0
  365. package/dist/utils/session-caller.js +24 -0
  366. package/dist/utils/session-caller.js.map +1 -0
  367. package/dist/utils/work-folder-validation.d.ts +39 -0
  368. package/dist/utils/work-folder-validation.d.ts.map +1 -0
  369. package/dist/utils/work-folder-validation.js +60 -0
  370. package/dist/utils/work-folder-validation.js.map +1 -0
  371. package/dist/workflows/auto-sprint.js +546 -6
  372. package/package.json +7 -4
  373. package/packages/apra-fleet-client/src/client/api.mjs +118 -4
  374. package/packages/apra-fleet-se/apra-pm/agents/backlog-groomer.md +17 -1
  375. package/packages/apra-fleet-se/apra-pm/agents/ci-watcher.md +13 -1
  376. package/packages/apra-fleet-se/apra-pm/agents/deployer.md +15 -3
  377. package/packages/apra-fleet-se/apra-pm/agents/doer.md +35 -1
  378. package/packages/apra-fleet-se/apra-pm/agents/harvester.md +22 -3
  379. package/packages/apra-fleet-se/apra-pm/agents/integ-test-runner.md +18 -2
  380. package/packages/apra-fleet-se/apra-pm/agents/kb-reconciler.md +216 -0
  381. package/packages/apra-fleet-se/apra-pm/agents/plan-reviewer.md +14 -1
  382. package/packages/apra-fleet-se/apra-pm/agents/planner.md +88 -5
  383. package/packages/apra-fleet-se/apra-pm/agents/regression-test-runner.md +19 -1
  384. package/packages/apra-fleet-se/apra-pm/agents/reviewer.md +104 -3
  385. package/packages/apra-fleet-se/apra-pm/agents/schemas/doer-output.json +63 -3
  386. package/packages/apra-fleet-se/apra-pm/agents/schemas/harvester-output.json +59 -2
  387. package/packages/apra-fleet-se/apra-pm/agents/schemas/integ-test-runner-output.json +2 -2
  388. package/packages/apra-fleet-se/apra-pm/agents/schemas/kb-reconciler-output.json +87 -0
  389. package/packages/apra-fleet-se/apra-pm/agents/schemas/planner-output.json +65 -0
  390. package/packages/apra-fleet-se/apra-pm/agents/schemas/reviewer-output.json +105 -8
  391. package/packages/apra-fleet-se/apra-pm/skills/pm/beads.md +6 -0
  392. package/packages/apra-fleet-se/apra-pm/skills/pm/fleet-addendum.md +6 -0
  393. package/packages/apra-fleet-se/apra-pm/skills/pm/index.md +56 -0
  394. package/packages/apra-fleet-se/apra-pm/skills/pm/kb-reconcile.md +132 -0
  395. package/packages/apra-fleet-se/apra-pm/skills/pm/kb-review.md +109 -0
  396. package/packages/apra-fleet-se/bin/cli.mjs +7 -0
  397. package/packages/apra-fleet-se/bin/serve.mjs +14 -2
  398. package/packages/apra-fleet-se/fleet-sprint/contracts.mjs +31 -5
  399. package/packages/apra-fleet-se/fleet-sprint/docs/README.md +1 -1
  400. package/packages/apra-fleet-se/fleet-sprint/docs/coach-role-design.md +23 -151
  401. package/packages/apra-fleet-se/fleet-sprint/docs/dolt-manual-recovery-verified.md +256 -0
  402. package/packages/apra-fleet-se/fleet-sprint/docs/dolt-sync-redesign.md +1482 -0
  403. package/packages/apra-fleet-se/fleet-sprint/docs/escalate-to-llm-design.md +908 -0
  404. package/packages/apra-fleet-se/fleet-sprint/docs/shared-orchestrator-reservation-design.md +399 -0
  405. package/packages/apra-fleet-se/fleet-sprint/dolt-settle.mjs +972 -0
  406. package/packages/apra-fleet-se/fleet-sprint/dolt-sync.mjs +167 -101
  407. package/packages/apra-fleet-se/fleet-sprint/errors.mjs +50 -6
  408. package/packages/apra-fleet-se/fleet-sprint/runner.js +1416 -116
  409. package/packages/apra-fleet-se/fleet-sprint/skills/fleet-sprint-cli/SKILL.md +13 -2
  410. package/packages/apra-fleet-se/fleet-sprint/skills/fleet-supervisor/SKILL.md +350 -0
  411. package/packages/apra-fleet-se/fleet-sprint/sprint-progress.mjs +101 -0
  412. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/github.mjs +30 -17
  413. package/packages/apra-fleet-se/fleet-sprint/viewer-extensions.mjs +62 -2
  414. package/packages/apra-fleet-se/package.json +1 -0
  415. package/packages/apra-fleet-workflow/src/viewer/index.mjs +127 -13
  416. package/packages/apra-fleet-workflow/src/viewer/run-title.mjs +60 -0
  417. package/packages/apra-fleet-workflow/src/workflow/index.mjs +8 -4
  418. package/skills/fleet/knowledge-agent.md +66 -0
  419. package/skills/fleet/permissions.md +28 -4
  420. package/skills/fleet/profiles/base-dev.json +10 -1
  421. package/skills/fleet/profiles/base-reviewer.json +8 -1
  422. package/skills/fleet/profiles/tag-kb-reconciler.json +20 -0
  423. package/version.json +1 -1
  424. package/packages/apra-fleet-se/fleet-sprint/docs/dolt-tier2-runbook.md +0 -127
  425. package/packages/apra-fleet-se/fleet-sprint/dolt-recovery-path-b.mjs +0 -339
  426. package/packages/apra-fleet-se/fleet-sprint/dolt-recovery-tier2.mjs +0 -360
  427. package/packages/apra-fleet-se/fleet-sprint/dolt-recovery.mjs +0 -363
@@ -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
+