@apralabs/apra-fleet 0.4.0 → 0.4.2

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 (548) hide show
  1. package/README.md +159 -13
  2. package/dist/agents/backlog-groomer.md +31 -19
  3. package/dist/agents/ci-watcher.md +16 -1
  4. package/dist/agents/deployer.md +37 -47
  5. package/dist/agents/doer.md +147 -114
  6. package/dist/agents/harvester.md +41 -34
  7. package/dist/agents/integ-test-runner.md +98 -114
  8. package/dist/agents/kb-reconciler.md +205 -0
  9. package/dist/agents/plan-reviewer.md +45 -44
  10. package/dist/agents/planner.md +121 -50
  11. package/dist/agents/regression-test-runner.md +84 -81
  12. package/dist/agents/reviewer.md +118 -44
  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 +3 -3
  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/regression-test-runner-output.json +4 -17
  19. package/dist/agents/schemas/reviewer-output.json +105 -8
  20. package/dist/cli/auth.d.ts.map +1 -1
  21. package/dist/cli/auth.js +1 -2
  22. package/dist/cli/auth.js.map +1 -1
  23. package/dist/cli/config.d.ts +3 -3
  24. package/dist/cli/config.d.ts.map +1 -1
  25. package/dist/cli/config.js +4 -13
  26. package/dist/cli/config.js.map +1 -1
  27. package/dist/cli/install.d.ts +1 -0
  28. package/dist/cli/install.d.ts.map +1 -1
  29. package/dist/cli/install.js +141 -44
  30. package/dist/cli/install.js.map +1 -1
  31. package/dist/cli/join.js +1 -1
  32. package/dist/cli/join.js.map +1 -1
  33. package/dist/cli/kb-commit.d.ts +12 -0
  34. package/dist/cli/kb-commit.d.ts.map +1 -0
  35. package/dist/cli/kb-commit.js +53 -0
  36. package/dist/cli/kb-commit.js.map +1 -0
  37. package/dist/cli/kb-directives.d.ts +17 -0
  38. package/dist/cli/kb-directives.d.ts.map +1 -0
  39. package/dist/cli/kb-directives.js +146 -0
  40. package/dist/cli/kb-directives.js.map +1 -0
  41. package/dist/cli/kb-import.d.ts +13 -0
  42. package/dist/cli/kb-import.d.ts.map +1 -0
  43. package/dist/cli/kb-import.js +56 -0
  44. package/dist/cli/kb-import.js.map +1 -0
  45. package/dist/cli/register-member.js +1 -1
  46. package/dist/cli/start.d.ts.map +1 -1
  47. package/dist/cli/start.js +7 -0
  48. package/dist/cli/start.js.map +1 -1
  49. package/dist/cli/uninstall.d.ts.map +1 -1
  50. package/dist/cli/uninstall.js +16 -3
  51. package/dist/cli/uninstall.js.map +1 -1
  52. package/dist/cli/watch.d.ts +76 -4
  53. package/dist/cli/watch.d.ts.map +1 -1
  54. package/dist/cli/watch.js +150 -17
  55. package/dist/cli/watch.js.map +1 -1
  56. package/dist/commands/kb-server.d.ts +8 -0
  57. package/dist/commands/kb-server.d.ts.map +1 -0
  58. package/dist/commands/kb-server.js +221 -0
  59. package/dist/commands/kb-server.js.map +1 -0
  60. package/dist/index.js +77 -2
  61. package/dist/index.js.map +1 -1
  62. package/dist/os/git-bash-candidates.d.ts +35 -0
  63. package/dist/os/git-bash-candidates.d.ts.map +1 -0
  64. package/dist/os/git-bash-candidates.js +46 -0
  65. package/dist/os/git-bash-candidates.js.map +1 -0
  66. package/dist/os/index.d.ts +13 -4
  67. package/dist/os/index.d.ts.map +1 -1
  68. package/dist/os/index.js +17 -2
  69. package/dist/os/index.js.map +1 -1
  70. package/dist/os/linux.d.ts +1 -0
  71. package/dist/os/linux.d.ts.map +1 -1
  72. package/dist/os/linux.js +19 -2
  73. package/dist/os/linux.js.map +1 -1
  74. package/dist/os/os-commands.d.ts +12 -0
  75. package/dist/os/os-commands.d.ts.map +1 -1
  76. package/dist/os/os-commands.js.map +1 -1
  77. package/dist/os/windows-gitbash.d.ts +93 -0
  78. package/dist/os/windows-gitbash.d.ts.map +1 -0
  79. package/dist/os/windows-gitbash.js +244 -0
  80. package/dist/os/windows-gitbash.js.map +1 -0
  81. package/dist/os/windows.d.ts +35 -0
  82. package/dist/os/windows.d.ts.map +1 -1
  83. package/dist/os/windows.js +93 -35
  84. package/dist/os/windows.js.map +1 -1
  85. package/dist/providers/agy.d.ts +15 -3
  86. package/dist/providers/agy.d.ts.map +1 -1
  87. package/dist/providers/agy.js +145 -11
  88. package/dist/providers/agy.js.map +1 -1
  89. package/dist/providers/claude.d.ts +14 -3
  90. package/dist/providers/claude.d.ts.map +1 -1
  91. package/dist/providers/claude.js +69 -22
  92. package/dist/providers/claude.js.map +1 -1
  93. package/dist/providers/codex.d.ts +14 -3
  94. package/dist/providers/codex.d.ts.map +1 -1
  95. package/dist/providers/codex.js +34 -8
  96. package/dist/providers/codex.js.map +1 -1
  97. package/dist/providers/copilot.d.ts +14 -3
  98. package/dist/providers/copilot.d.ts.map +1 -1
  99. package/dist/providers/copilot.js +33 -8
  100. package/dist/providers/copilot.js.map +1 -1
  101. package/dist/providers/email/headers.d.ts +15 -0
  102. package/dist/providers/email/headers.d.ts.map +1 -0
  103. package/dist/providers/email/headers.js +42 -0
  104. package/dist/providers/email/headers.js.map +1 -0
  105. package/dist/providers/email/index.d.ts +18 -0
  106. package/dist/providers/email/index.d.ts.map +1 -0
  107. package/dist/providers/email/index.js +60 -0
  108. package/dist/providers/email/index.js.map +1 -0
  109. package/dist/providers/email/provider.d.ts +49 -0
  110. package/dist/providers/email/provider.d.ts.map +1 -0
  111. package/dist/providers/email/provider.js +2 -0
  112. package/dist/providers/email/provider.js.map +1 -0
  113. package/dist/providers/email/sendgrid.d.ts +12 -0
  114. package/dist/providers/email/sendgrid.d.ts.map +1 -0
  115. package/dist/providers/email/sendgrid.js +67 -0
  116. package/dist/providers/email/sendgrid.js.map +1 -0
  117. package/dist/providers/email/smtp.d.ts +65 -0
  118. package/dist/providers/email/smtp.d.ts.map +1 -0
  119. package/dist/providers/email/smtp.js +373 -0
  120. package/dist/providers/email/smtp.js.map +1 -0
  121. package/dist/providers/index.d.ts +0 -1
  122. package/dist/providers/index.d.ts.map +1 -1
  123. package/dist/providers/index.js +0 -3
  124. package/dist/providers/index.js.map +1 -1
  125. package/dist/providers/none.d.ts +14 -3
  126. package/dist/providers/none.d.ts.map +1 -1
  127. package/dist/providers/none.js +26 -2
  128. package/dist/providers/none.js.map +1 -1
  129. package/dist/providers/opencode.d.ts +14 -3
  130. package/dist/providers/opencode.d.ts.map +1 -1
  131. package/dist/providers/opencode.js +60 -6
  132. package/dist/providers/opencode.js.map +1 -1
  133. package/dist/providers/provider.d.ts +91 -5
  134. package/dist/providers/provider.d.ts.map +1 -1
  135. package/dist/providers/provider.js +45 -1
  136. package/dist/providers/provider.js.map +1 -1
  137. package/dist/services/agent-provisioner.d.ts.map +1 -1
  138. package/dist/services/agent-provisioner.js +5 -8
  139. package/dist/services/agent-provisioner.js.map +1 -1
  140. package/dist/services/cloud/activity.js +2 -2
  141. package/dist/services/cloud/activity.js.map +1 -1
  142. package/dist/services/cloud/lifecycle.d.ts.map +1 -1
  143. package/dist/services/cloud/lifecycle.js +3 -0
  144. package/dist/services/cloud/lifecycle.js.map +1 -1
  145. package/dist/services/cloud/task-wrapper.d.ts +18 -0
  146. package/dist/services/cloud/task-wrapper.d.ts.map +1 -1
  147. package/dist/services/cloud/task-wrapper.js +157 -0
  148. package/dist/services/cloud/task-wrapper.js.map +1 -1
  149. package/dist/services/context-admission.d.ts.map +1 -1
  150. package/dist/services/context-admission.js +9 -7
  151. package/dist/services/context-admission.js.map +1 -1
  152. package/dist/services/credential-cleanup.d.ts.map +1 -1
  153. package/dist/services/credential-cleanup.js +22 -3
  154. package/dist/services/credential-cleanup.js.map +1 -1
  155. package/dist/services/github-app.d.ts.map +1 -1
  156. package/dist/services/github-app.js +11 -2
  157. package/dist/services/github-app.js.map +1 -1
  158. package/dist/services/knowledge/audn.d.ts +37 -0
  159. package/dist/services/knowledge/audn.d.ts.map +1 -0
  160. package/dist/services/knowledge/audn.js +219 -0
  161. package/dist/services/knowledge/audn.js.map +1 -0
  162. package/dist/services/knowledge/file-hash.d.ts +11 -0
  163. package/dist/services/knowledge/file-hash.d.ts.map +1 -0
  164. package/dist/services/knowledge/file-hash.js +123 -0
  165. package/dist/services/knowledge/file-hash.js.map +1 -0
  166. package/dist/services/knowledge/http-provider.d.ts +46 -0
  167. package/dist/services/knowledge/http-provider.d.ts.map +1 -0
  168. package/dist/services/knowledge/http-provider.js +254 -0
  169. package/dist/services/knowledge/http-provider.js.map +1 -0
  170. package/dist/services/knowledge/kb-providers.d.ts +15 -0
  171. package/dist/services/knowledge/kb-providers.d.ts.map +1 -0
  172. package/dist/services/knowledge/kb-providers.js +92 -0
  173. package/dist/services/knowledge/kb-providers.js.map +1 -0
  174. package/dist/services/knowledge/kb-scope-input.d.ts +5 -0
  175. package/dist/services/knowledge/kb-scope-input.d.ts.map +1 -0
  176. package/dist/services/knowledge/kb-scope-input.js +11 -0
  177. package/dist/services/knowledge/kb-scope-input.js.map +1 -0
  178. package/dist/services/knowledge/kb-service.d.ts +3 -0
  179. package/dist/services/knowledge/kb-service.d.ts.map +1 -0
  180. package/dist/services/knowledge/kb-service.js +2 -0
  181. package/dist/services/knowledge/kb-service.js.map +1 -0
  182. package/dist/services/knowledge/path-validation.d.ts +2 -0
  183. package/dist/services/knowledge/path-validation.d.ts.map +1 -0
  184. package/dist/services/knowledge/path-validation.js +13 -0
  185. package/dist/services/knowledge/path-validation.js.map +1 -0
  186. package/dist/services/knowledge/pre-init.d.ts +14 -0
  187. package/dist/services/knowledge/pre-init.d.ts.map +1 -0
  188. package/dist/services/knowledge/pre-init.js +147 -0
  189. package/dist/services/knowledge/pre-init.js.map +1 -0
  190. package/dist/services/knowledge/project-slug.d.ts +2 -0
  191. package/dist/services/knowledge/project-slug.d.ts.map +1 -0
  192. package/dist/services/knowledge/project-slug.js +49 -0
  193. package/dist/services/knowledge/project-slug.js.map +1 -0
  194. package/dist/services/knowledge/sqlite-provider.d.ts +147 -0
  195. package/dist/services/knowledge/sqlite-provider.d.ts.map +1 -0
  196. package/dist/services/knowledge/sqlite-provider.js +1646 -0
  197. package/dist/services/knowledge/sqlite-provider.js.map +1 -0
  198. package/dist/services/knowledge/types.d.ts +163 -0
  199. package/dist/services/knowledge/types.d.ts.map +1 -0
  200. package/dist/services/knowledge/types.js +9 -0
  201. package/dist/services/knowledge/types.js.map +1 -0
  202. package/dist/services/member-home.d.ts +89 -0
  203. package/dist/services/member-home.d.ts.map +1 -0
  204. package/dist/services/member-home.js +259 -0
  205. package/dist/services/member-home.js.map +1 -0
  206. package/dist/services/member-remote-url.d.ts +34 -0
  207. package/dist/services/member-remote-url.d.ts.map +1 -0
  208. package/dist/services/member-remote-url.js +39 -0
  209. package/dist/services/member-remote-url.js.map +1 -0
  210. package/dist/services/model-pricing.d.ts.map +1 -1
  211. package/dist/services/model-pricing.js +0 -5
  212. package/dist/services/model-pricing.js.map +1 -1
  213. package/dist/services/orphan-recovery.d.ts +9 -3
  214. package/dist/services/orphan-recovery.d.ts.map +1 -1
  215. package/dist/services/orphan-recovery.js +22 -8
  216. package/dist/services/orphan-recovery.js.map +1 -1
  217. package/dist/services/preflight-check.d.ts +56 -0
  218. package/dist/services/preflight-check.d.ts.map +1 -0
  219. package/dist/services/preflight-check.js +277 -0
  220. package/dist/services/preflight-check.js.map +1 -0
  221. package/dist/services/shell-probe.d.ts +131 -0
  222. package/dist/services/shell-probe.d.ts.map +1 -0
  223. package/dist/services/shell-probe.js +210 -0
  224. package/dist/services/shell-probe.js.map +1 -0
  225. package/dist/services/singleton.d.ts +2 -0
  226. package/dist/services/singleton.d.ts.map +1 -1
  227. package/dist/services/singleton.js +1 -1
  228. package/dist/services/singleton.js.map +1 -1
  229. package/dist/services/ssh.js +2 -2
  230. package/dist/services/ssh.js.map +1 -1
  231. package/dist/services/stall/find-log-file.d.ts.map +1 -1
  232. package/dist/services/stall/find-log-file.js +22 -16
  233. package/dist/services/stall/find-log-file.js.map +1 -1
  234. package/dist/services/stall/log-path-resolver.d.ts +11 -8
  235. package/dist/services/stall/log-path-resolver.d.ts.map +1 -1
  236. package/dist/services/stall/log-path-resolver.js +17 -40
  237. package/dist/services/stall/log-path-resolver.js.map +1 -1
  238. package/dist/services/stall/read-log-tail.d.ts.map +1 -1
  239. package/dist/services/stall/read-log-tail.js +6 -5
  240. package/dist/services/stall/read-log-tail.js.map +1 -1
  241. package/dist/services/stall/stall-detector.d.ts +32 -0
  242. package/dist/services/stall/stall-detector.d.ts.map +1 -1
  243. package/dist/services/stall/stall-detector.js +149 -6
  244. package/dist/services/stall/stall-detector.js.map +1 -1
  245. package/dist/services/stall/stall-poller.d.ts +34 -0
  246. package/dist/services/stall/stall-poller.d.ts.map +1 -1
  247. package/dist/services/stall/stall-poller.js +160 -35
  248. package/dist/services/stall/stall-poller.js.map +1 -1
  249. package/dist/services/strategy.d.ts +9 -0
  250. package/dist/services/strategy.d.ts.map +1 -1
  251. package/dist/services/strategy.js +41 -7
  252. package/dist/services/strategy.js.map +1 -1
  253. package/dist/services/tool-registry.d.ts.map +1 -1
  254. package/dist/services/tool-registry.js +87 -1
  255. package/dist/services/tool-registry.js.map +1 -1
  256. package/dist/services/user-config.js +1 -1
  257. package/dist/services/user-config.js.map +1 -1
  258. package/dist/services/vcs/azure-devops.d.ts +1 -1
  259. package/dist/services/vcs/azure-devops.d.ts.map +1 -1
  260. package/dist/services/vcs/azure-devops.js +105 -10
  261. package/dist/services/vcs/azure-devops.js.map +1 -1
  262. package/dist/services/vcs/bitbucket.d.ts.map +1 -1
  263. package/dist/services/vcs/bitbucket.js +16 -0
  264. package/dist/services/vcs/bitbucket.js.map +1 -1
  265. package/dist/services/vcs/github.d.ts.map +1 -1
  266. package/dist/services/vcs/github.js +56 -1
  267. package/dist/services/vcs/github.js.map +1 -1
  268. package/dist/services/vcs/types.d.ts +123 -2
  269. package/dist/services/vcs/types.d.ts.map +1 -1
  270. package/dist/services/version-check.d.ts +22 -0
  271. package/dist/services/version-check.d.ts.map +1 -0
  272. package/dist/services/version-check.js +103 -0
  273. package/dist/services/version-check.js.map +1 -0
  274. package/dist/skills/fleet-sprint-cli/SKILL.md +15 -3
  275. package/dist/skills/pm/SKILL.md +0 -1
  276. package/dist/skills/pm/beads.md +6 -0
  277. package/dist/skills/pm/cost.md +0 -1
  278. package/dist/skills/pm/fleet-addendum.md +6 -1
  279. package/dist/skills/pm/index.md +56 -0
  280. package/dist/skills/pm/kb-reconcile.md +132 -0
  281. package/dist/skills/pm/kb-review.md +109 -0
  282. package/dist/tools/check-status.d.ts +47 -0
  283. package/dist/tools/check-status.d.ts.map +1 -1
  284. package/dist/tools/check-status.js +245 -3
  285. package/dist/tools/check-status.js.map +1 -1
  286. package/dist/tools/child-id-allocator.d.ts +2 -2
  287. package/dist/tools/cloud-control.js +2 -2
  288. package/dist/tools/cloud-control.js.map +1 -1
  289. package/dist/tools/code-intelligence-codebase-memory.d.ts +11 -0
  290. package/dist/tools/code-intelligence-codebase-memory.d.ts.map +1 -0
  291. package/dist/tools/code-intelligence-codebase-memory.js +270 -0
  292. package/dist/tools/code-intelligence-codebase-memory.js.map +1 -0
  293. package/dist/tools/code-intelligence-freshness.d.ts +2 -0
  294. package/dist/tools/code-intelligence-freshness.d.ts.map +1 -0
  295. package/dist/tools/code-intelligence-freshness.js +26 -0
  296. package/dist/tools/code-intelligence-freshness.js.map +1 -0
  297. package/dist/tools/code-intelligence-gitnexus.d.ts +14 -0
  298. package/dist/tools/code-intelligence-gitnexus.d.ts.map +1 -0
  299. package/dist/tools/code-intelligence-gitnexus.js +475 -0
  300. package/dist/tools/code-intelligence-gitnexus.js.map +1 -0
  301. package/dist/tools/code-intelligence-kb-enrich.d.ts +2 -0
  302. package/dist/tools/code-intelligence-kb-enrich.d.ts.map +1 -0
  303. package/dist/tools/code-intelligence-kb-enrich.js +65 -0
  304. package/dist/tools/code-intelligence-kb-enrich.js.map +1 -0
  305. package/dist/tools/code-intelligence-reindex.d.ts +7 -0
  306. package/dist/tools/code-intelligence-reindex.d.ts.map +1 -0
  307. package/dist/tools/code-intelligence-reindex.js +106 -0
  308. package/dist/tools/code-intelligence-reindex.js.map +1 -0
  309. package/dist/tools/code-intelligence-telemetry.d.ts +5 -0
  310. package/dist/tools/code-intelligence-telemetry.d.ts.map +1 -0
  311. package/dist/tools/code-intelligence-telemetry.js +52 -0
  312. package/dist/tools/code-intelligence-telemetry.js.map +1 -0
  313. package/dist/tools/code-intelligence-tests.d.ts +2 -0
  314. package/dist/tools/code-intelligence-tests.d.ts.map +1 -0
  315. package/dist/tools/code-intelligence-tests.js +24 -0
  316. package/dist/tools/code-intelligence-tests.js.map +1 -0
  317. package/dist/tools/code-intelligence.d.ts +114 -0
  318. package/dist/tools/code-intelligence.d.ts.map +1 -0
  319. package/dist/tools/code-intelligence.js +124 -0
  320. package/dist/tools/code-intelligence.js.map +1 -0
  321. package/dist/tools/compose-permissions.d.ts +26 -0
  322. package/dist/tools/compose-permissions.d.ts.map +1 -1
  323. package/dist/tools/compose-permissions.js +257 -33
  324. package/dist/tools/compose-permissions.js.map +1 -1
  325. package/dist/tools/execute-command.d.ts +2 -0
  326. package/dist/tools/execute-command.d.ts.map +1 -1
  327. package/dist/tools/execute-command.js +114 -28
  328. package/dist/tools/execute-command.js.map +1 -1
  329. package/dist/tools/execute-prompt.d.ts +13 -1
  330. package/dist/tools/execute-prompt.d.ts.map +1 -1
  331. package/dist/tools/execute-prompt.js +310 -61
  332. package/dist/tools/execute-prompt.js.map +1 -1
  333. package/dist/tools/kb-capture.d.ts +53 -0
  334. package/dist/tools/kb-capture.d.ts.map +1 -0
  335. package/dist/tools/kb-capture.js +130 -0
  336. package/dist/tools/kb-capture.js.map +1 -0
  337. package/dist/tools/kb-context.d.ts +17 -0
  338. package/dist/tools/kb-context.d.ts.map +1 -0
  339. package/dist/tools/kb-context.js +29 -0
  340. package/dist/tools/kb-context.js.map +1 -0
  341. package/dist/tools/kb-export.d.ts +19 -0
  342. package/dist/tools/kb-export.d.ts.map +1 -0
  343. package/dist/tools/kb-export.js +344 -0
  344. package/dist/tools/kb-export.js.map +1 -0
  345. package/dist/tools/kb-feedback.d.ts +23 -0
  346. package/dist/tools/kb-feedback.d.ts.map +1 -0
  347. package/dist/tools/kb-feedback.js +43 -0
  348. package/dist/tools/kb-feedback.js.map +1 -0
  349. package/dist/tools/kb-freshness-sweep.d.ts +14 -0
  350. package/dist/tools/kb-freshness-sweep.d.ts.map +1 -0
  351. package/dist/tools/kb-freshness-sweep.js +29 -0
  352. package/dist/tools/kb-freshness-sweep.js.map +1 -0
  353. package/dist/tools/kb-harvest.d.ts +20 -0
  354. package/dist/tools/kb-harvest.d.ts.map +1 -0
  355. package/dist/tools/kb-harvest.js +143 -0
  356. package/dist/tools/kb-harvest.js.map +1 -0
  357. package/dist/tools/kb-import.d.ts +44 -0
  358. package/dist/tools/kb-import.d.ts.map +1 -0
  359. package/dist/tools/kb-import.js +239 -0
  360. package/dist/tools/kb-import.js.map +1 -0
  361. package/dist/tools/kb-invalidate.d.ts +19 -0
  362. package/dist/tools/kb-invalidate.d.ts.map +1 -0
  363. package/dist/tools/kb-invalidate.js +34 -0
  364. package/dist/tools/kb-invalidate.js.map +1 -0
  365. package/dist/tools/kb-list.d.ts +32 -0
  366. package/dist/tools/kb-list.d.ts.map +1 -0
  367. package/dist/tools/kb-list.js +43 -0
  368. package/dist/tools/kb-list.js.map +1 -0
  369. package/dist/tools/kb-promote.d.ts +20 -0
  370. package/dist/tools/kb-promote.d.ts.map +1 -0
  371. package/dist/tools/kb-promote.js +20 -0
  372. package/dist/tools/kb-promote.js.map +1 -0
  373. package/dist/tools/kb-query.d.ts +35 -0
  374. package/dist/tools/kb-query.d.ts.map +1 -0
  375. package/dist/tools/kb-query.js +111 -0
  376. package/dist/tools/kb-query.js.map +1 -0
  377. package/dist/tools/kb-reconcile-prefilter.d.ts +14 -0
  378. package/dist/tools/kb-reconcile-prefilter.d.ts.map +1 -0
  379. package/dist/tools/kb-reconcile-prefilter.js +26 -0
  380. package/dist/tools/kb-reconcile-prefilter.js.map +1 -0
  381. package/dist/tools/kb-resolve-contradiction.d.ts +23 -0
  382. package/dist/tools/kb-resolve-contradiction.d.ts.map +1 -0
  383. package/dist/tools/kb-resolve-contradiction.js +37 -0
  384. package/dist/tools/kb-resolve-contradiction.js.map +1 -0
  385. package/dist/tools/kb-session-prime.d.ts +26 -0
  386. package/dist/tools/kb-session-prime.d.ts.map +1 -0
  387. package/dist/tools/kb-session-prime.js +392 -0
  388. package/dist/tools/kb-session-prime.js.map +1 -0
  389. package/dist/tools/kb-setup.d.ts +20 -0
  390. package/dist/tools/kb-setup.d.ts.map +1 -0
  391. package/dist/tools/kb-setup.js +49 -0
  392. package/dist/tools/kb-setup.js.map +1 -0
  393. package/dist/tools/kb-stats.d.ts +20 -0
  394. package/dist/tools/kb-stats.d.ts.map +1 -0
  395. package/dist/tools/kb-stats.js +115 -0
  396. package/dist/tools/kb-stats.js.map +1 -0
  397. package/dist/tools/list-members.d.ts.map +1 -1
  398. package/dist/tools/list-members.js +6 -2
  399. package/dist/tools/list-members.js.map +1 -1
  400. package/dist/tools/member-detail.d.ts.map +1 -1
  401. package/dist/tools/member-detail.js +13 -3
  402. package/dist/tools/member-detail.js.map +1 -1
  403. package/dist/tools/member-reservation.d.ts.map +1 -1
  404. package/dist/tools/member-reservation.js +13 -1
  405. package/dist/tools/member-reservation.js.map +1 -1
  406. package/dist/tools/monitor-task.d.ts.map +1 -1
  407. package/dist/tools/monitor-task.js +38 -5
  408. package/dist/tools/monitor-task.js.map +1 -1
  409. package/dist/tools/provision-auth.d.ts.map +1 -1
  410. package/dist/tools/provision-auth.js +15 -8
  411. package/dist/tools/provision-auth.js.map +1 -1
  412. package/dist/tools/provision-vcs-auth.d.ts +5 -2
  413. package/dist/tools/provision-vcs-auth.d.ts.map +1 -1
  414. package/dist/tools/provision-vcs-auth.js +58 -52
  415. package/dist/tools/provision-vcs-auth.js.map +1 -1
  416. package/dist/tools/register-member.d.ts +21 -12
  417. package/dist/tools/register-member.d.ts.map +1 -1
  418. package/dist/tools/register-member.js +70 -3
  419. package/dist/tools/register-member.js.map +1 -1
  420. package/dist/tools/remove-member.d.ts.map +1 -1
  421. package/dist/tools/remove-member.js +19 -5
  422. package/dist/tools/remove-member.js.map +1 -1
  423. package/dist/tools/report-status.d.ts.map +1 -1
  424. package/dist/tools/report-status.js +2 -1
  425. package/dist/tools/report-status.js.map +1 -1
  426. package/dist/tools/revoke-vcs-auth.js +2 -2
  427. package/dist/tools/revoke-vcs-auth.js.map +1 -1
  428. package/dist/tools/send-email.d.ts +69 -0
  429. package/dist/tools/send-email.d.ts.map +1 -0
  430. package/dist/tools/send-email.js +177 -0
  431. package/dist/tools/send-email.js.map +1 -0
  432. package/dist/tools/setup-ssh-key.d.ts.map +1 -1
  433. package/dist/tools/setup-ssh-key.js +4 -1
  434. package/dist/tools/setup-ssh-key.js.map +1 -1
  435. package/dist/tools/stop-prompt.js +2 -2
  436. package/dist/tools/stop-prompt.js.map +1 -1
  437. package/dist/tools/update-agent-cli.js +2 -2
  438. package/dist/tools/update-agent-cli.js.map +1 -1
  439. package/dist/tools/update-member.d.ts +21 -12
  440. package/dist/tools/update-member.d.ts.map +1 -1
  441. package/dist/tools/update-member.js +43 -2
  442. package/dist/tools/update-member.js.map +1 -1
  443. package/dist/types.d.ts +12 -1
  444. package/dist/types.d.ts.map +1 -1
  445. package/dist/utils/agent-helpers.d.ts +36 -0
  446. package/dist/utils/agent-helpers.d.ts.map +1 -1
  447. package/dist/utils/agent-helpers.js +39 -1
  448. package/dist/utils/agent-helpers.js.map +1 -1
  449. package/dist/utils/platform.d.ts +7 -0
  450. package/dist/utils/platform.d.ts.map +1 -1
  451. package/dist/utils/platform.js +11 -1
  452. package/dist/utils/platform.js.map +1 -1
  453. package/dist/utils/prompt-errors.js +1 -1
  454. package/dist/utils/prompt-errors.js.map +1 -1
  455. package/dist/utils/session-caller.d.ts +28 -0
  456. package/dist/utils/session-caller.d.ts.map +1 -0
  457. package/dist/utils/session-caller.js +24 -0
  458. package/dist/utils/session-caller.js.map +1 -0
  459. package/dist/utils/work-folder-validation.d.ts +39 -0
  460. package/dist/utils/work-folder-validation.d.ts.map +1 -0
  461. package/dist/utils/work-folder-validation.js +60 -0
  462. package/dist/utils/work-folder-validation.js.map +1 -0
  463. package/dist/utils/workspace-trust.d.ts.map +1 -1
  464. package/dist/utils/workspace-trust.js +5 -1
  465. package/dist/utils/workspace-trust.js.map +1 -1
  466. package/dist/workflows/auto-sprint.js +550 -23
  467. package/package.json +7 -4
  468. package/packages/apra-fleet-client/src/client/api.mjs +210 -7
  469. package/packages/apra-fleet-se/apra-pm/agents/backlog-groomer.md +31 -19
  470. package/packages/apra-fleet-se/apra-pm/agents/ci-watcher.md +16 -1
  471. package/packages/apra-fleet-se/apra-pm/agents/deployer.md +37 -47
  472. package/packages/apra-fleet-se/apra-pm/agents/doer.md +147 -114
  473. package/packages/apra-fleet-se/apra-pm/agents/harvester.md +41 -34
  474. package/packages/apra-fleet-se/apra-pm/agents/integ-test-runner.md +98 -114
  475. package/packages/apra-fleet-se/apra-pm/agents/kb-reconciler.md +205 -0
  476. package/packages/apra-fleet-se/apra-pm/agents/plan-reviewer.md +45 -44
  477. package/packages/apra-fleet-se/apra-pm/agents/planner.md +121 -50
  478. package/packages/apra-fleet-se/apra-pm/agents/regression-test-runner.md +84 -81
  479. package/packages/apra-fleet-se/apra-pm/agents/reviewer.md +118 -44
  480. package/packages/apra-fleet-se/apra-pm/agents/schemas/doer-output.json +63 -3
  481. package/packages/apra-fleet-se/apra-pm/agents/schemas/harvester-output.json +59 -2
  482. package/packages/apra-fleet-se/apra-pm/agents/schemas/integ-test-runner-output.json +3 -3
  483. package/packages/apra-fleet-se/apra-pm/agents/schemas/kb-reconciler-output.json +87 -0
  484. package/packages/apra-fleet-se/apra-pm/agents/schemas/planner-output.json +65 -0
  485. package/packages/apra-fleet-se/apra-pm/agents/schemas/regression-test-runner-output.json +4 -17
  486. package/packages/apra-fleet-se/apra-pm/agents/schemas/reviewer-output.json +105 -8
  487. package/packages/apra-fleet-se/apra-pm/skills/pm/SKILL.md +0 -1
  488. package/packages/apra-fleet-se/apra-pm/skills/pm/beads.md +6 -0
  489. package/packages/apra-fleet-se/apra-pm/skills/pm/cost.md +0 -1
  490. package/packages/apra-fleet-se/apra-pm/skills/pm/fleet-addendum.md +6 -1
  491. package/packages/apra-fleet-se/apra-pm/skills/pm/index.md +56 -0
  492. package/packages/apra-fleet-se/apra-pm/skills/pm/kb-reconcile.md +132 -0
  493. package/packages/apra-fleet-se/apra-pm/skills/pm/kb-review.md +109 -0
  494. package/packages/apra-fleet-se/bin/cli.mjs +139 -3
  495. package/packages/apra-fleet-se/bin/serve.mjs +49 -2
  496. package/packages/apra-fleet-se/fleet-sprint/contracts.mjs +182 -38
  497. package/packages/apra-fleet-se/fleet-sprint/docs/README.md +23 -8
  498. package/packages/apra-fleet-se/fleet-sprint/docs/dolt-manual-recovery-verified.md +258 -0
  499. package/packages/apra-fleet-se/fleet-sprint/docs/dolt-sync-redesign.md +1487 -0
  500. package/packages/apra-fleet-se/fleet-sprint/docs/escalate-to-llm-design.md +908 -0
  501. package/packages/apra-fleet-se/fleet-sprint/docs/shared-orchestrator-reservation-design.md +399 -0
  502. package/packages/apra-fleet-se/fleet-sprint/docs/stabilization-log.md +14 -4
  503. package/packages/apra-fleet-se/fleet-sprint/dolt-settle.mjs +1148 -0
  504. package/packages/apra-fleet-se/fleet-sprint/dolt-sync.mjs +229 -112
  505. package/packages/apra-fleet-se/fleet-sprint/errors.mjs +91 -6
  506. package/packages/apra-fleet-se/fleet-sprint/runner.js +2469 -238
  507. package/packages/apra-fleet-se/fleet-sprint/se-os-commands.mjs +134 -0
  508. package/packages/apra-fleet-se/fleet-sprint/se-posix.mjs +154 -0
  509. package/packages/apra-fleet-se/fleet-sprint/se-windows-gitbash.mjs +97 -0
  510. package/packages/apra-fleet-se/fleet-sprint/se-windows.mjs +143 -0
  511. package/packages/apra-fleet-se/fleet-sprint/skills/fleet-sprint-cli/SKILL.md +15 -3
  512. package/packages/apra-fleet-se/fleet-sprint/skills/fleet-supervisor/SKILL.md +350 -0
  513. package/packages/apra-fleet-se/fleet-sprint/sprint-progress.mjs +101 -0
  514. package/packages/apra-fleet-se/fleet-sprint/vcs-module.mjs +51 -0
  515. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/azure-devops.mjs +657 -12
  516. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/dolt.mjs +33 -4
  517. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/github.mjs +60 -30
  518. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/index.mjs +205 -2
  519. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/shell-helpers.mjs +164 -0
  520. package/packages/apra-fleet-se/fleet-sprint/viewer-extensions.mjs +141 -26
  521. package/packages/apra-fleet-se/package.json +1 -0
  522. package/packages/apra-fleet-workflow/src/viewer/index.mjs +294 -14
  523. package/packages/apra-fleet-workflow/src/viewer/run-title.mjs +60 -0
  524. package/packages/apra-fleet-workflow/src/workflow/index.mjs +443 -35
  525. package/skills/fleet/SKILL.md +20 -9
  526. package/skills/fleet/auth-azdevops.md +44 -5
  527. package/skills/fleet/auth-bitbucket.md +3 -3
  528. package/skills/fleet/auth-github.md +2 -2
  529. package/skills/fleet/beads-conflict-resolution.md +141 -0
  530. package/skills/fleet/beads.md +16 -12
  531. package/skills/fleet/knowledge-agent.md +66 -0
  532. package/skills/fleet/onboarding.md +4 -4
  533. package/skills/fleet/permissions.md +32 -8
  534. package/skills/fleet/profiles/base-dev.json +10 -1
  535. package/skills/fleet/profiles/base-reviewer.json +8 -1
  536. package/skills/fleet/profiles/tag-kb-reconciler.json +20 -0
  537. package/skills/fleet/skill-matrix.md +1 -1
  538. package/skills/fleet/troubleshooting.md +2 -1
  539. package/version.json +1 -1
  540. package/dist/providers/gemini.d.ts +0 -42
  541. package/dist/providers/gemini.d.ts.map +0 -1
  542. package/dist/providers/gemini.js +0 -202
  543. package/dist/providers/gemini.js.map +0 -1
  544. package/packages/apra-fleet-se/fleet-sprint/docs/coach-role-design.md +0 -151
  545. package/packages/apra-fleet-se/fleet-sprint/docs/dolt-tier2-runbook.md +0 -127
  546. package/packages/apra-fleet-se/fleet-sprint/dolt-recovery-path-b.mjs +0 -339
  547. package/packages/apra-fleet-se/fleet-sprint/dolt-recovery-tier2.mjs +0 -360
  548. package/packages/apra-fleet-se/fleet-sprint/dolt-recovery.mjs +0 -363
@@ -0,0 +1,1148 @@
1
+ // Dolt conflict recovery: settle() -- see docs/dolt-sync-redesign.md for the
2
+ // full design. Short version: this module replaces the entire 3-tier
3
+ // Path A / Path B / Tier 2 recovery ladder (dolt-recovery.mjs,
4
+ // dolt-recovery-path-b.mjs, dolt-recovery-tier2.mjs) with ONE deterministic,
5
+ // zero-agent-dispatch function that is TOTAL over every row-level Dolt
6
+ // conflict shape this data model can produce -- no gates, no allowlist, no
7
+ // escalation, no LLM. The old ladder's Path A never actually ran in
8
+ // production (no sql() runtime was ever injected at its runner.js call
9
+ // site) and its LLM-driven Tier 2 had no code-guaranteed rollback (see
10
+ // apra-fleet-ga61, apra-fleet-5mqg). settleDoltConflicts() fixes both: it IS
11
+ // the sql runtime (driving the raw `dolt` CLI itself, not routing bd through
12
+ // it), and its teardown is a real `finally`, not a step an agent can abandon
13
+ // mid-procedure.
14
+ //
15
+ // -----------------------------------------------------------------------------
16
+ // Mechanics (every step live-verified -- see docs/dolt-manual-recovery-verified.md
17
+ // and docs/dolt-sync-redesign.md Parts 3/5/7 for the full evidence trail):
18
+ //
19
+ // 0. Resolve the REAL data dir/mode from `bd dolt status` -- never
20
+ // hardcoded. If the member is already in server mode, target that
21
+ // live server instead of spawning a second one.
22
+ // 1. Ensure a correctly-pinned `dolt` binary exists on the MEMBER at its
23
+ // own `~/.apra-fleet/bin`. Members never run `apra-fleet install`
24
+ // (they are pure SSH command targets, not apra-fleet installs) so
25
+ // nothing else on a member ever puts a pinned dolt there -- settle is
26
+ // self-sufficient: probe, and if missing/wrong-version, install it
27
+ // itself from the SAME pinned GitHub-release asset dolt-install.ts
28
+ // uses. If an existing binary can't be replaced because a stray dolt
29
+ // process holds the file, kill it (a legitimate self-heal -- nothing
30
+ // else ever launches a binary at this path) and retry once; only then
31
+ // fall back to whatever runnable dolt IS present, gated behind a
32
+ // functional preflight query.
33
+ // 2. Spawn a genuinely-detached ephemeral `dolt sql-server` against the
34
+ // resolved data dir. `Start-Process`/`schtasks` on Windows both die
35
+ // with the launching SSH session -- WMI `Win32_Process.Create` is what
36
+ // actually survives (session 0). POSIX: `nohup ... & disown`.
37
+ // 3. Drive the raw `dolt` CLI directly at the socket -- NEVER route `bd`
38
+ // through it (bd's own routing state, `.beads/metadata.json`, is never
39
+ // touched, which is what makes teardown unconditionally safe).
40
+ // `--no-tls` MUST precede `--host`/`--port` (order-sensitive parser);
41
+ // NEVER pass `--user`/`--password` (both are credential-prompt
42
+ // landmines -- omitting them authenticates silently as root/empty).
43
+ // 4. Re-open the merge, enumerate EVERY conflicted table (no allowlist),
44
+ // and resolve each one via the fixed per-table rulebook below, with a
45
+ // generic per-field last-writer-wins-by-`updated_at` fallback (falling
46
+ // back further to `--theirs` outright if a table has no `updated_at`
47
+ // column) for any table not named explicitly -- this is what makes the
48
+ // function TOTAL rather than gated.
49
+ // 5. Tear the server down FIRST (kill + verify port closed), THEN
50
+ // republish via `bd dolt pull`/`bd dolt push`. Embedded-mode `bd` must
51
+ // not race the server's exclusive chunk-journal lock -- republishing
52
+ // while the server is still up would hit that lock and fail or fall
53
+ // back read-only (design doc Part 7.2).
54
+ // 6. Guaranteed teardown in a real `finally`, regardless of outcome --
55
+ // the ephemeral-server class of state is undone on every exit path.
56
+ // =============================================================================
57
+
58
+ import { DoltDivergedError, DoltSyncError, DoltBinaryUnavailableError } from './errors.mjs';
59
+ import { getSeCommands } from './se-os-commands.mjs';
60
+
61
+ /** Must equal src/cli/dolt-install.ts's DOLT_VERSION byte-for-byte -- a
62
+ * drift-guard test (dolt-settle.test.mjs) asserts this against that file's
63
+ * source text. Two executors of one pin (design doc Part 5.4): dolt-install.ts
64
+ * installs it in-process on the orchestrator; this module installs it over
65
+ * command() on members, since members never run `apra-fleet install`. */
66
+ export const DOLT_VERSION = 'v2.2.0';
67
+ const DOLT_RELEASE_BASE = `https://github.com/dolthub/dolt/releases/download/${DOLT_VERSION}`;
68
+
69
+ /** Default embedded dolt data dir -- used ONLY as a last-resort fallback
70
+ * when `bd dolt status` itself cannot be parsed. Every real call path
71
+ * resolves the data dir live (step 0); this constant existing at all is
72
+ * exactly the anti-pattern design doc Part 5 warns against, so it is never
73
+ * used silently -- resolveDoltStatus() logs loudly if it has to fall back
74
+ * to it. */
75
+ export const DEFAULT_EMBEDDED_DATA_DIR = '.beads/embeddeddolt';
76
+
77
+ export const RECOVERY_SQL_SERVER_HOST = '127.0.0.1';
78
+ export const DEFAULT_PORT_RANGE = Object.freeze({ start: 13300, end: 13400 });
79
+
80
+ /** Tables settle() has an explicit, named rulebook entry for. Anything else
81
+ * still gets resolved -- via the generic per-field-LWW-or-theirs fallback
82
+ * (resolveGenericTable) -- this list is NOT an allowlist/gate. */
83
+ const NAMED_RULEBOOK = Object.freeze({
84
+ issues: 'lww',
85
+ dependencies: 'lww',
86
+ labels: 'union',
87
+ comments: 'theirs',
88
+ events: 'theirs',
89
+ });
90
+
91
+ // ---------------------------------------------------------------------------
92
+ // Section 1: pinned-dolt asset resolution (mirrors src/cli/dolt-install.ts's
93
+ // resolveDoltAsset exactly -- kept as plain data here since dolt-settle.mjs
94
+ // cannot import the TypeScript module across the package boundary at
95
+ // runtime; the drift-guard test is what keeps these two in sync).
96
+ // ---------------------------------------------------------------------------
97
+
98
+ /**
99
+ * @param {string} platform - 'win32' | 'linux' | 'darwin'
100
+ * @param {string} arch - 'x64' | 'arm64'
101
+ * @returns {{ assetName: string, url: string, archiveType: 'zip'|'tar.gz', binaryName: string }}
102
+ */
103
+ export function resolveDoltAsset(platform, arch) {
104
+ const binaryName = platform === 'win32' ? 'dolt.exe' : 'dolt';
105
+ let assetName;
106
+ let archiveType;
107
+ if (platform === 'win32' && arch === 'x64') {
108
+ assetName = 'dolt-windows-amd64.zip';
109
+ archiveType = 'zip';
110
+ } else if (platform === 'linux' && arch === 'x64') {
111
+ assetName = 'dolt-linux-amd64.tar.gz';
112
+ archiveType = 'tar.gz';
113
+ } else if (platform === 'darwin' && arch === 'x64') {
114
+ assetName = 'dolt-darwin-amd64.tar.gz';
115
+ archiveType = 'tar.gz';
116
+ } else if (platform === 'darwin' && arch === 'arm64') {
117
+ assetName = 'dolt-darwin-arm64.tar.gz';
118
+ archiveType = 'tar.gz';
119
+ }
120
+ if (!assetName || !archiveType) {
121
+ throw new Error(`settle: unsupported platform/arch for pinned dolt install: ${platform}/${arch}`);
122
+ }
123
+ return { assetName, url: `${DOLT_RELEASE_BASE}/${assetName}`, archiveType, binaryName };
124
+ }
125
+
126
+ /**
127
+ * The member-side fleet-managed dolt path, resolved with the MEMBER's own
128
+ * shell dialect (never the orchestrator's homedir/platform) via
129
+ * se-os-commands.mjs's getSeCommands(). The binary filename is still
130
+ * OS-dependent (dolt.exe on either Windows dialect, dolt everywhere else --
131
+ * the same OS-vs-shell distinction resolveDoltAsset's platform-branched
132
+ * asset selection stays on), decided off the resolved primitive's `.shell`
133
+ * identifier rather than a `platform === 'win32'` check, so this function
134
+ * carries no platform branch of its own (apra-fleet-7dir.16).
135
+ * @param {{ os?: string, shell?: string }|string} target
136
+ * @returns {string} a double-quoted, shell-dialect-correct path
137
+ */
138
+ function memberDoltPath(target) {
139
+ const seCmds = getSeCommands(target);
140
+ const binaryName = seCmds.shell === 'posix' ? 'dolt' : 'dolt.exe';
141
+ return `"${seCmds.homePath(`.apra-fleet/bin/${binaryName}`)}"`;
142
+ }
143
+
144
+ // ---------------------------------------------------------------------------
145
+ // Section 1b: shell dialect. Every command below is dispatched into the
146
+ // MEMBER's own shell -- PowerShell (5.1, so no `&&`/`||`) on Windows, bash on
147
+ // POSIX -- and the two disagree about things settle depends on. All of this
148
+ // was found by running settle against real members, not by reading docs:
149
+ //
150
+ // - Invoking a quoted absolute path needs PowerShell's call operator
151
+ // (`& "..."`); a leading `&` in bash is a syntax error outright.
152
+ // - Inside a double-quoted string, bash treats a backtick as command
153
+ // substitution while PowerShell treats it as its escape character, so a
154
+ // SQL identifier quote must be escaped differently for each (and SQL that
155
+ // can avoid backticks entirely simply does).
156
+ // - `cmd 2>$null || fallback` parses in bash but is a hard parse ERROR in
157
+ // PowerShell 5.1, so no single "works everywhere" probe string exists.
158
+ //
159
+ // memberDoltPath/invokeBinary/escapeSqlForShell all resolve their dialect via
160
+ // se-os-commands.mjs's getSeCommands({ os, shell }) rather than a bare
161
+ // `platform === 'win32'` check (apra-fleet-7dir.16/.20), so a Windows member
162
+ // whose registered shell is Git-for-Windows bash gets the bash dialect for
163
+ // all three instead of being force-assumed PowerShell.
164
+ // ---------------------------------------------------------------------------
165
+
166
+ /**
167
+ * Invoke an executable at a quoted path with arguments, in the member's
168
+ * actual shell dialect.
169
+ * @param {{ os?: string, shell?: string }|string} target
170
+ * @param {string} quotedPath
171
+ * @param {string} args
172
+ */
173
+ function invokeBinary(target, quotedPath, args) {
174
+ return getSeCommands(target).shell === 'powershell' ? `& ${quotedPath} ${args}` : `${quotedPath} ${args}`;
175
+ }
176
+
177
+ /**
178
+ * Escape a SQL string so it survives as ONE double-quoted argument in the
179
+ * member's shell. Backticks and `$` are the dangerous characters in both
180
+ * dialects, for opposite reasons. Delegates to se-os-commands.mjs's
181
+ * escapeSqlArg primitive (apra-fleet-7dir.20) rather than re-implementing the
182
+ * escaping here.
183
+ * @param {{ os?: string, shell?: string }|string} target bare platform string
184
+ * ('win32'|'linux'|'darwin', back-compat with every existing caller/test)
185
+ * or a { os, shell } record for full shell-dialect fidelity.
186
+ * @param {string} sql
187
+ */
188
+ export function escapeSqlForShell(target, sql) {
189
+ return getSeCommands(target).escapeSqlArg(sql);
190
+ }
191
+
192
+ // ---------------------------------------------------------------------------
193
+ // Section 2: `bd dolt status` parsing -- resolve the REAL data dir/mode.
194
+ // ---------------------------------------------------------------------------
195
+
196
+ /**
197
+ * @param {{ command: Function, member: string }} opts
198
+ * @returns {Promise<{ mode: 'embedded'|'server'|'unknown', dataDir: string|null, host: string|null, port: number|null, raw: string }>}
199
+ */
200
+ export async function resolveDoltStatus({ command, member, log = () => {} }) {
201
+ const res = await command('bd dolt status', { member_name: member, silent: true, failSoft: true, label: `settle: bd dolt status for '${member}'` });
202
+ const raw = String((res && (res.output || res.error)) || '');
203
+
204
+ const embeddedMatch = raw.match(/embedded[^\n]*\n\s*Data:\s*(.+)/i);
205
+ if (embeddedMatch) {
206
+ return { mode: 'embedded', dataDir: embeddedMatch[1].trim(), host: null, port: null, raw };
207
+ }
208
+ const serverMatch = raw.match(/server[^\n]*?(\d{1,3}(?:\.\d{1,3}){3}|localhost):(\d+)/i);
209
+ if (serverMatch) {
210
+ return { mode: 'server', dataDir: null, host: serverMatch[1], port: Number(serverMatch[2]), raw };
211
+ }
212
+ log(`[Dolt Settle] WARNING: could not parse 'bd dolt status' for member '${member}' -- falling back to default data dir '${DEFAULT_EMBEDDED_DATA_DIR}'. Raw: ${raw.slice(0, 300)}`);
213
+ return { mode: 'unknown', dataDir: DEFAULT_EMBEDDED_DATA_DIR, host: null, port: null, raw };
214
+ }
215
+
216
+ // ---------------------------------------------------------------------------
217
+ // Section 3: ensure a correctly-pinned dolt binary on the member (design doc
218
+ // Part 5.3/5.6).
219
+ // ---------------------------------------------------------------------------
220
+
221
+ /** Probe an existing binary at `doltPath` for exit-0 + parseable version. */
222
+ async function probeDoltVersion({ command, member, doltPath, platform, shell = '' }) {
223
+ const res = await command(invokeBinary({ os: platform, shell }, doltPath, 'version'), { member_name: member, silent: true, failSoft: true, label: `settle: probe dolt version for '${member}'` });
224
+ const text = String((res && (res.output || res.error)) || '');
225
+ const match = text.match(/dolt version (\d+\.\d+\.\d+\S*)/i);
226
+ return { ok: !!(res && res.ok !== false) && !!match, version: match ? match[1] : null, raw: text };
227
+ }
228
+
229
+ /** Step 1b: install the pinned binary via remote shell from the same pinned
230
+ * asset URL resolveDoltAsset() computes. Bounded, single-attempt.
231
+ * The PowerShell script body is kept byte-identical to today regardless of
232
+ * the member's registered shell -- it is `doltPath` (already the
233
+ * PowerShell-dialect `psDoltPath` form, resolved by the caller) that must
234
+ * stay in `$env:USERPROFILE...` form even for a gitbash member, since the
235
+ * dialect INSIDE the wrapped script is PowerShell, not the member's own
236
+ * shell (apra-fleet-7dir.21's NON-OBVIOUS constraint). Only the OUTER
237
+ * invocation is routed via getSeCommands(...).wrapPowerShellScript, which
238
+ * returns the script unchanged for a powershell member and a bash-invocable
239
+ * `-EncodedCommand` form for a gitbash member. */
240
+ async function installPinnedDolt({ command, member, platform, arch, doltPath, shell = '', log }) {
241
+ const asset = resolveDoltAsset(platform, arch);
242
+ log(`[Dolt Settle] installing pinned dolt ${DOLT_VERSION} on member '${member}' from ${asset.url}`);
243
+
244
+ if (platform === 'win32') {
245
+ const script = [
246
+ 'New-Item -ItemType Directory -Force "$env:USERPROFILE\\.apra-fleet\\bin" | Out-Null',
247
+ `Invoke-WebRequest -Uri "${asset.url}" -OutFile "$env:TEMP\\dolt-settle.zip" -TimeoutSec 300`,
248
+ 'Expand-Archive -Force "$env:TEMP\\dolt-settle.zip" "$env:TEMP\\dolt-settle"',
249
+ `Get-ChildItem -Recurse -Filter "${asset.binaryName}" "$env:TEMP\\dolt-settle" | Select-Object -First 1 | Copy-Item -Force -Destination ${doltPath}`,
250
+ 'Remove-Item -Recurse -Force "$env:TEMP\\dolt-settle.zip","$env:TEMP\\dolt-settle" -ErrorAction SilentlyContinue',
251
+ ].join('; ');
252
+ const wrapped = getSeCommands({ os: platform, shell }).wrapPowerShellScript(script, 'dolt-settle installPinnedDolt');
253
+ return command(wrapped, { member_name: member, silent: true, failSoft: true, timeout_s: 320, label: `settle: install pinned dolt on '${member}'` });
254
+ }
255
+
256
+ const script = [
257
+ 'mkdir -p "$HOME/.apra-fleet/bin"',
258
+ `curl -fL --max-time 300 "${asset.url}" -o /tmp/dolt-settle-${member}.tgz`,
259
+ `mkdir -p /tmp/dolt-settle-${member} && tar -xzf /tmp/dolt-settle-${member}.tgz -C /tmp/dolt-settle-${member}`,
260
+ `install -m 0755 "$(find /tmp/dolt-settle-${member} -type f -name ${asset.binaryName} | head -1)" "$HOME/.apra-fleet/bin/${asset.binaryName}"`,
261
+ `rm -rf /tmp/dolt-settle-${member}.tgz /tmp/dolt-settle-${member}`,
262
+ ].join(' && ');
263
+ return command(script, { member_name: member, silent: true, failSoft: true, timeout_s: 320, label: `settle: install pinned dolt on '${member}'` });
264
+ }
265
+
266
+ /** Is this install failure the "file is in use / can't be replaced" class
267
+ * (design doc Part 5.6), as opposed to a hard failure (network, unsupported
268
+ * platform, corrupted download) that must still throw? */
269
+ function isBinaryLockedError(output) {
270
+ const text = String(output || '');
271
+ // NOTE: deliberately no bare "Permission denied" -- that also matches an
272
+ // ordinary POSIX EACCES (wrong perms, non-lock cause), which would waste
273
+ // a kill-and-retry cycle on a failure the retry can never fix. ETXTBSY /
274
+ // EBUSY / "text file busy" already cover the real POSIX in-use case.
275
+ return /being used by another process|Access to the path .* is denied|ETXTBSY|EBUSY|text file busy/i.test(text);
276
+ }
277
+
278
+ /** Kill any process whose executable path is exactly the fleet-managed dolt
279
+ * path -- by construction the only thing that ever launches a binary there
280
+ * is settle/the installer, so this is always a legitimate self-heal, never
281
+ * collateral damage against an unrelated process. */
282
+ async function killProcessAtPath({ command, member, platform, doltPath, shell = '', log }) {
283
+ log(`[Dolt Settle] attempting to kill any process locking '${doltPath}' on member '${member}' before retrying the pinned install.`);
284
+ if (platform === 'win32') {
285
+ const script = `Get-Process | Where-Object { $_.Path -eq ${doltPath} } | Stop-Process -Force -ErrorAction SilentlyContinue`;
286
+ const wrapped = getSeCommands({ os: platform, shell }).wrapPowerShellScript(script, 'dolt-settle killProcessAtPath');
287
+ return command(wrapped, { member_name: member, silent: true, failSoft: true, label: `settle: kill locking dolt process on '${member}'` });
288
+ }
289
+ return command('pkill -f "\\.apra-fleet/bin/dolt" || true', { member_name: member, silent: true, failSoft: true, label: `settle: kill locking dolt process on '${member}'` });
290
+ }
291
+
292
+ /**
293
+ * Design doc Part 5.3/5.6: probe -> install if missing/wrong-version ->
294
+ * (if blocked) kill-and-retry-once -> (if still blocked) warn and fall back
295
+ * to whatever runnable dolt IS present, gated behind a functional preflight.
296
+ * Throws DoltBinaryUnavailableError only when NOTHING runnable is available
297
+ * after the full ladder, or the platform/arch is unsupported with no
298
+ * existing binary -- an ordinary operational failure, not an escalation.
299
+ *
300
+ * @returns {Promise<{ doltPath: string, psDoltPath: string, version: string, pinned: boolean, warnings: string[] }>}
301
+ */
302
+ export async function ensurePinnedDolt({ command, member, platform, arch = 'x64', shell = '', log = () => {} }) {
303
+ // `doltPath` is the member-shell-native invocation path (bash for a
304
+ // gitbash member, PowerShell otherwise) -- used for the version probe and
305
+ // (via the returned doltInfo) every later `dolt` invocation dispatched
306
+ // directly to the member's own shell (runDoltSql).
307
+ const doltPath = memberDoltPath({ os: platform, shell });
308
+ // `psDoltPath` is ALWAYS the PowerShell-dialect form (shell forced to ''),
309
+ // because installPinnedDolt/killProcessAtPath/spawnEphemeralServer embed
310
+ // it inside a raw PowerShell SCRIPT body, not a member-shell-dispatched
311
+ // command. The dialect INSIDE those wrapped scripts is always PowerShell
312
+ // even for a gitbash member -- only the OUTER invocation is now routed
313
+ // through getSeCommands(...).wrapPowerShellScript (apra-fleet-7dir.21/.22)
314
+ // -- so a gitbash member must still get the PowerShell-dialect path here,
315
+ // or a bare `$HOME/...` path would silently fail to expand inside those
316
+ // PowerShell script bodies.
317
+ const psDoltPath = memberDoltPath({ os: platform, shell: '' });
318
+ const warnings = [];
319
+
320
+ const initial = await probeDoltVersion({ command, member, doltPath, platform, shell });
321
+ if (initial.ok && initial.version === DOLT_VERSION.replace(/^v/, '')) {
322
+ return { doltPath, psDoltPath, version: initial.version, pinned: true, warnings };
323
+ }
324
+
325
+ // Missing, broken, or wrong version -- attempt the pinned install.
326
+ let install;
327
+ try {
328
+ install = await installPinnedDolt({ command, member, platform, arch, doltPath: psDoltPath, shell, log });
329
+ } catch (err) {
330
+ throw new DoltBinaryUnavailableError(
331
+ `[Dolt Settle] unsupported platform/arch for member '${member}' installing pinned dolt: ${err.message}`,
332
+ { member, probedPath: doltPath, probeOutput: err.message, repairCommand: `manually install dolt ${DOLT_VERSION} at ${doltPath} on ${member}` },
333
+ );
334
+ }
335
+
336
+ const installFailed = install && install.ok === false;
337
+ const installOutput = String((install && (install.error || install.output)) || '');
338
+
339
+ if (installFailed && isBinaryLockedError(installOutput)) {
340
+ // Kill-first, then retry once (Part 5.6 step 2).
341
+ await killProcessAtPath({ command, member, platform, doltPath: psDoltPath, shell, log });
342
+ const retry = await installPinnedDolt({ command, member, platform, arch, doltPath: psDoltPath, shell, log });
343
+ if (!(retry && retry.ok === false)) {
344
+ const reprobed = await probeDoltVersion({ command, member, doltPath, platform, shell });
345
+ if (reprobed.ok) return { doltPath, psDoltPath, version: reprobed.version, pinned: true, warnings };
346
+ }
347
+ // Still blocked after kill+retry -- warn and fall back (Part 5.6 step 3).
348
+ const fallback = await probeDoltVersion({ command, member, doltPath, platform, shell });
349
+ if (fallback.ok) {
350
+ const warn = `[Dolt Settle] pin not enforced on '${member}': could not replace ${doltPath} (locked even after kill+retry); proceeding with dolt ${fallback.version} as a functionally-probed fallback. Landmines unverified on this version -- see docs/dolt-sync-redesign.md Part 5.6.`;
351
+ log(warn);
352
+ warnings.push(warn);
353
+ return { doltPath, psDoltPath, version: fallback.version, pinned: false, warnings };
354
+ }
355
+ throw new DoltBinaryUnavailableError(
356
+ `[Dolt Settle] no usable dolt binary on member '${member}' after install+kill+retry: ${installOutput}`,
357
+ { member, probedPath: doltPath, probeOutput: installOutput, repairCommand: `manually free ${doltPath} on ${member} and re-run settle` },
358
+ );
359
+ }
360
+
361
+ if (installFailed) {
362
+ throw new DoltBinaryUnavailableError(
363
+ `[Dolt Settle] failed to install pinned dolt ${DOLT_VERSION} on member '${member}': ${installOutput}`,
364
+ { member, probedPath: doltPath, probeOutput: installOutput, repairCommand: `manually install dolt ${DOLT_VERSION} at ${doltPath} on ${member}` },
365
+ );
366
+ }
367
+
368
+ const reprobed = await probeDoltVersion({ command, member, doltPath, platform, shell });
369
+ if (!reprobed.ok) {
370
+ throw new DoltBinaryUnavailableError(
371
+ `[Dolt Settle] pinned dolt install reported success but the binary still fails 'dolt version' on member '${member}' -- likely a corrupted download.`,
372
+ { member, probedPath: doltPath, probeOutput: reprobed.raw, repairCommand: `delete ${doltPath} on ${member} and re-run settle` },
373
+ );
374
+ }
375
+ return { doltPath, psDoltPath, version: reprobed.version, pinned: true, warnings };
376
+ }
377
+
378
+ // ---------------------------------------------------------------------------
379
+ // Section 4: ephemeral sql-server spawn/teardown.
380
+ // ---------------------------------------------------------------------------
381
+
382
+ /** Genuinely-detached spawn -- WMI on Windows (Start-Process/schtasks both
383
+ * die with the launching SSH session, verified live), nohup+disown on
384
+ * POSIX. Returns the pid so teardown can target it precisely. */
385
+ export async function spawnEphemeralServer({ command, member, platform, doltPath, dataDir, host, port, shell = '', log = () => {} }) {
386
+ log(`[Dolt Settle] starting ephemeral dolt sql-server for member '${member}' at ${host}:${port} --data-dir ${dataDir}`);
387
+
388
+ if (platform === 'win32') {
389
+ // The command line is assembled in PowerShell, from a DOUBLE-quoted
390
+ // $exe, so `$env:USERPROFILE` actually expands: passing the raw
391
+ // '$env:USERPROFILE\...' text inside WMI's single-quoted argument
392
+ // makes Win32_Process.Create fail with ReturnValue 9 / "path not
393
+ // found" (verified live on fleet-win-dev1). Paths are quoted inside
394
+ // the command line so a space in either survives.
395
+ const script = [
396
+ `$exe = ${doltPath}`,
397
+ `$cl = '"' + $exe + '" sql-server --host ${host} --port ${port} --data-dir ' + '"${dataDir}"'`,
398
+ '$r = Invoke-CimMethod -ClassName Win32_Process -MethodName Create -Arguments @{ CommandLine = $cl }',
399
+ 'if ($r.ReturnValue -ne 0) { throw "Win32_Process.Create failed with ReturnValue $($r.ReturnValue) for command line: $cl" }',
400
+ 'Write-Output "PID:$($r.ProcessId)"',
401
+ ].join('; ');
402
+ const wrapped = getSeCommands({ os: platform, shell }).wrapPowerShellScript(script, 'dolt-settle spawnEphemeralServer');
403
+ const res = await command(wrapped, { member_name: member, silent: true, failSoft: true, label: `settle: spawn ephemeral sql-server on '${member}'` });
404
+ if (res && res.ok === false) {
405
+ throw new DoltSyncError(`[Dolt Settle] failed to spawn ephemeral sql-server for member '${member}': ${res.error}`, { member, doltOutput: res.error });
406
+ }
407
+ const pidMatch = String(res.output || '').match(/PID:(\d+)/);
408
+ if (!pidMatch) {
409
+ throw new DoltSyncError(`[Dolt Settle] spawned sql-server for member '${member}' but could not parse its PID from output: ${res.output}`, { member, doltOutput: res.output });
410
+ }
411
+ return { pid: Number(pidMatch[1]) };
412
+ }
413
+
414
+ // POSIX detachment, every piece of it verified live on fleet-lin-dev1
415
+ // because the obvious form does NOT work under the fleet's own bash
416
+ // wrapper (which backgrounds the command and `wait`s on it):
417
+ // - `( ... & )` -- a SUBSHELL the dispatching shell never waits on.
418
+ // A plain `nohup ... & echo PID; disown` left the dispatch hanging
419
+ // until its 300s inactivity timeout while the server was actually up
420
+ // and holding the data dir lock: a "spawn failure" that silently
421
+ // leaves a live orphan behind.
422
+ // - `setsid` -- own session, so it outlives the SSH session.
423
+ // - `< /dev/null` -- otherwise the server inherits the dispatch's stdin
424
+ // and the SSH channel never closes.
425
+ // - the pid comes from `pgrep` on the port, not `$!`: `$!` belongs to
426
+ // the subshell, not to the server we must be able to kill.
427
+ const logPath = `/tmp/dolt-settle-${member}-${port}.log`;
428
+ const matcher = `sql-server --host ${host} --port ${port}`;
429
+ // `setsid` does NOT exist on macOS (verified live on fleet-mac: the spawn
430
+ // silently produced no pid), so it is resolved at runtime and simply
431
+ // omitted where absent -- `nohup` inside the detached subshell is what
432
+ // actually keeps the server alive there.
433
+ const script = `SETSID=$(command -v setsid || true); ( $SETSID nohup ${doltPath} sql-server --host ${host} --port ${port} --data-dir ${dataDir} > ${logPath} 2>&1 < /dev/null & ) ; sleep 1; echo "PID:$(pgrep -f '${matcher}' | head -1)"`;
434
+ const res = await command(script, { member_name: member, silent: true, failSoft: true, label: `settle: spawn ephemeral sql-server on '${member}'` });
435
+ if (res && res.ok === false) {
436
+ throw new DoltSyncError(`[Dolt Settle] failed to spawn ephemeral sql-server for member '${member}': ${res.error}`, { member, doltOutput: res.error });
437
+ }
438
+ const pidMatch = String(res.output || '').match(/PID:(\d+)/);
439
+ if (!pidMatch) {
440
+ throw new DoltSyncError(`[Dolt Settle] spawned sql-server for member '${member}' but could not parse its PID from output: ${res.output}`, { member, doltOutput: res.output });
441
+ }
442
+ return { pid: Number(pidMatch[1]), logPath };
443
+ }
444
+
445
+ /** Bounded poll for the server to actually accept connections -- never
446
+ * sleep-and-hope. */
447
+ export async function waitForServerReady({ command, member, platform, shell = '', host, port, log = () => {}, attempts = 10, intervalMs = 500 }) {
448
+ for (let i = 0; i < attempts; i += 1) {
449
+ const probe = platformAwareTcpProbe({ command, member, platform, shell, host, port });
450
+ // eslint-disable-next-line no-await-in-loop -- intentional bounded poll
451
+ const res = await probe;
452
+ if (res) return true;
453
+ // eslint-disable-next-line no-await-in-loop -- intentional bounded poll
454
+ await new Promise((resolve) => { setTimeout(resolve, intervalMs); });
455
+ }
456
+ throw new DoltSyncError(`[Dolt Settle] ephemeral sql-server for member '${member}' never became reachable at ${host}:${port} after ${attempts} attempts.`, { member });
457
+ }
458
+
459
+ /**
460
+ * Is something listening on host:port on the member?
461
+ *
462
+ * Done in NODE, not in the member's shell, because no shell one-liner works
463
+ * everywhere -- all of this is live-verified, not assumed:
464
+ * - `cmd || fallback` is a hard PARSE ERROR in PowerShell 5.1
465
+ * (fleet-win-dev1), so no single string can cover both families.
466
+ * - `/dev/tcp` is a BASH feature and fleet-mac's shell is ZSH, where it does
467
+ * not exist -- the probe silently reported "nothing listening" while the
468
+ * server was up and logging "Server ready. Accepting connections."
469
+ * Every member necessarily has node (bd is npm-installed), and a single-quoted
470
+ * JS string survives both bash and PowerShell unchanged.
471
+ */
472
+ /**
473
+ * Wrap a JS snippet as a `node -e` argument for the member's shell.
474
+ *
475
+ * PowerShell 5.1's native-argument passing STRIPS the double quotes inside a
476
+ * single-quoted string, so `require("net")` arrived at node as
477
+ * `require(net)` and died with a SyntaxError (verified live on
478
+ * fleet-win-dev1). Backslash-escaping them is the documented workaround --
479
+ * and must NOT be applied on POSIX (or on a Windows member whose registered
480
+ * shell is Git-for-Windows bash, which runs `node` directly rather than
481
+ * through PowerShell's native-argument passing): the backslashes would
482
+ * survive literally into the JS. Dialect is resolved off the member's
483
+ * REGISTERED shell (getSeCommands) rather than platform, so this only
484
+ * escapes for the true powershell dialect (apra-fleet-7dir.22/.23).
485
+ * @param {{ os?: string, shell?: string }|string} target
486
+ * @param {string} js
487
+ */
488
+ function nodeEval(target, js) {
489
+ const needsPowerShellEscaping = getSeCommands(target).shell === 'powershell';
490
+ return `node -e '${needsPowerShellEscaping ? js.replace(/"/g, '\\"') : js}'`;
491
+ }
492
+
493
+ function tcpProbeScript(target, host, port, timeoutMs = 2000) {
494
+ return nodeEval(target, `const net=require("net");const s=net.connect(${port},"${host}");const done=(v)=>{try{s.destroy()}catch(e){};console.log(v?"PROBE:True":"PROBE:False");process.exit(0)};s.on("connect",()=>done(true));s.on("error",()=>done(false));setTimeout(()=>done(false),${timeoutMs})`);
495
+ }
496
+
497
+ async function platformAwareTcpProbe({ command, member, platform, shell = '', host, port }) {
498
+ const res = await command(tcpProbeScript({ os: platform, shell }, host, port), { member_name: member, silent: true, failSoft: true, label: `settle: TCP probe for '${member}'` });
499
+ return /PROBE:True/i.test(String((res && res.output) || ''));
500
+ }
501
+
502
+ /** Kill the server + verify the port is actually closed. Best-effort by
503
+ * design (called from the happy path AND the unconditional `finally` --
504
+ * see settleDoltConflicts). */
505
+ async function killServerAndVerify({ command, member, platform, shell = '', pid, host, port, log = () => {} }) {
506
+ // Kill the recorded pid AND, belt-and-braces, anything still bound to our
507
+ // ephemeral port: the recorded pid is resolved by a pattern match at spawn
508
+ // time, so a mis-resolved pid must not be able to leave the real server
509
+ // running (which would hold the data dir lock and wedge the republish).
510
+ // Both forms are scoped to settle's own port, never to dolt at large.
511
+ const matcher = `sql-server --host ${host} --port ${port}`;
512
+ if (platform === 'win32') {
513
+ const script = `Stop-Process -Id ${pid} -Force -ErrorAction SilentlyContinue; Get-CimInstance Win32_Process -Filter "Name='dolt.exe'" -ErrorAction SilentlyContinue | Where-Object { $_.CommandLine -match '--port ${port}' } | ForEach-Object { Stop-Process -Id $_.ProcessId -Force -ErrorAction SilentlyContinue }`;
514
+ const wrapped = getSeCommands({ os: platform, shell }).wrapPowerShellScript(script, 'dolt-settle killServerAndVerify');
515
+ await command(
516
+ wrapped,
517
+ { member_name: member, silent: true, failSoft: true, label: `settle: kill ephemeral sql-server pid ${pid} on '${member}'` },
518
+ );
519
+ } else {
520
+ await command(`kill ${pid} 2>/dev/null; pkill -f '${matcher}' 2>/dev/null; true`, { member_name: member, silent: true, failSoft: true, label: `settle: kill ephemeral sql-server pid ${pid} on '${member}'` });
521
+ }
522
+ for (let i = 0; i < 6; i += 1) {
523
+ // eslint-disable-next-line no-await-in-loop -- bounded teardown-verify poll
524
+ const stillUp = await platformAwareTcpProbe({ command, member, platform, shell, host, port });
525
+ if (!stillUp) {
526
+ log(`[Dolt Settle] torn down ephemeral sql-server (pid ${pid}) for member '${member}'; port ${port} confirmed closed.`);
527
+ return;
528
+ }
529
+ // eslint-disable-next-line no-await-in-loop -- bounded teardown-verify poll
530
+ await new Promise((resolve) => { setTimeout(resolve, 300); });
531
+ }
532
+ log(`[Dolt Settle] WARNING: sent kill to pid ${pid} on member '${member}' but port ${port} still appears open after 6 checks -- the supervisor orphan sweep is the backstop for this (design doc Part 3.3).`);
533
+ }
534
+
535
+ // ---------------------------------------------------------------------------
536
+ // Section 5: raw dolt CLI query runner -- the exact live-verified flag set.
537
+ // ---------------------------------------------------------------------------
538
+
539
+ // apra-fleet-ka1u follow-up (bug #2): MSYS bash (Git for Windows -- the shell
540
+ // every gitbash member's command() dispatches through) SILENTLY TRUNCATES any
541
+ // `bash -c <string>` longer than this many characters, with no error at the
542
+ // truncation point itself -- the failure only surfaces later as a confusing
543
+ // "unexpected EOF while looking for matching '\"'" once the truncated string
544
+ // leaves an unterminated quote. Bisected empirically (byte-precise: 8186 ok,
545
+ // 8187 fails), identically for both the Git-bundled and the standalone MSYS
546
+ // bash on this class of Windows member. A live incident: resolveLwwTable()'s
547
+ // per-column CASE/SET UPDATE for a 53-column table (e.g. 'issues') built a
548
+ // 14,064-character query, well past the limit, and settle silently failed
549
+ // with no usable diagnostic. Kept well under the measured 8186 so escaping
550
+ // overhead (the preamble, and any character that doubles under
551
+ // escapeSqlForShell) can never push a chunk over the real limit.
552
+ const DOLT_SQL_INLINE_LIMIT = 6000;
553
+
554
+ /** Random-enough per-invocation suffix for a scratch SQL file name -- multiple
555
+ * concurrent settle calls on the same member must never collide. Not
556
+ * cryptographic; collision just needs to be practically impossible for one
557
+ * member's lifetime, not adversarially resistant. */
558
+ function randomFileSuffix() {
559
+ return `${Date.now().toString(36)}${Math.random().toString(36).slice(2, 8)}`;
560
+ }
561
+
562
+ /**
563
+ * Write `sql` to a scratch file on `member` in chunks that individually stay
564
+ * well under DOLT_SQL_INLINE_LIMIT (never one giant `-c` string, which is
565
+ * exactly the bug this exists to avoid), then return the file's path so the
566
+ * caller can pass it to `dolt sql -f <path>` instead of `-q "<query>"`.
567
+ * POSIX/gitbash writes under $HOME (both resolve it correctly; verified by
568
+ * runDoltSql's own pre-existing "$HOME/.apra-fleet/bin/dolt.exe" doltPath
569
+ * convention); PowerShell writes under $env:TEMP.
570
+ *
571
+ * @returns {Promise<string>} the scratch file's path, in the member's own dialect
572
+ */
573
+ async function writeDoltSqlScratchFile({ command, member, target, sql, log }) {
574
+ const seCommands = getSeCommands(target);
575
+ const isPowerShell = seCommands.shell === 'powershell';
576
+ const suffix = randomFileSuffix();
577
+ const filePath = isPowerShell
578
+ ? `$env:TEMP\\dolt-settle-${suffix}.sql`
579
+ : `$HOME/.apra-fleet-se-dolt-settle-${suffix}.sql`;
580
+
581
+ // Create/truncate the file first (a stale file from a killed prior
582
+ // attempt must never be silently appended to).
583
+ const createCmd = isPowerShell
584
+ ? `Set-Content -Path "${filePath}" -Value $null -NoNewline`
585
+ : `printf '' > "${filePath}"`;
586
+ const createRes = await command(createCmd, { member_name: member, silent: true, failSoft: true, label: `settle: create scratch SQL file for '${member}'` });
587
+ if (createRes && createRes.ok === false) {
588
+ throw new DoltSyncError(`[Dolt Settle] could not create scratch SQL file '${filePath}' for member '${member}': ${createRes.error}`, { member, doltOutput: createRes.error });
589
+ }
590
+
591
+ for (let offset = 0; offset < sql.length; offset += DOLT_SQL_INLINE_LIMIT) {
592
+ const chunk = sql.slice(offset, offset + DOLT_SQL_INLINE_LIMIT);
593
+ const escapedChunk = escapeSqlForShell(target, chunk);
594
+ const appendCmd = isPowerShell
595
+ ? `Add-Content -Path "${filePath}" -Value "${escapedChunk}" -NoNewline`
596
+ : `printf '%s' "${escapedChunk}" >> "${filePath}"`;
597
+ // eslint-disable-next-line no-await-in-loop -- each append MUST land
598
+ // before the next is issued (same file, sequential writes; a member's
599
+ // own shell has no ordering guarantee across concurrently-dispatched
600
+ // commands, only within one command() call's own execution).
601
+ const appendRes = await command(appendCmd, { member_name: member, silent: true, failSoft: true, label: `settle: append scratch SQL chunk for '${member}'` });
602
+ if (appendRes && appendRes.ok === false) {
603
+ throw new DoltSyncError(`[Dolt Settle] could not write scratch SQL file '${filePath}' for member '${member}': ${appendRes.error}`, { member, doltOutput: appendRes.error });
604
+ }
605
+ }
606
+ log(`[Dolt Settle] wrote ${sql.length}-char query to scratch file '${filePath}' for member '${member}' (${Math.ceil(sql.length / DOLT_SQL_INLINE_LIMIT)} chunk(s), staying under bash's ${DOLT_SQL_INLINE_LIMIT}-char -c limit).`);
607
+ return filePath;
608
+ }
609
+
610
+ /** Best-effort scratch-file cleanup -- never lets a delete failure surface as
611
+ * the query's own result; a leftover scratch file is a minor annoyance, not
612
+ * a correctness problem (the next writeDoltSqlScratchFile call for this
613
+ * member always creates/truncates its own uniquely-suffixed file anyway). */
614
+ async function cleanupDoltSqlScratchFile({ command, member, target, filePath, log }) {
615
+ const isPowerShell = getSeCommands(target).shell === 'powershell';
616
+ const rmCmd = isPowerShell ? `Remove-Item -Path "${filePath}" -ErrorAction SilentlyContinue` : `rm -f "${filePath}"`;
617
+ try {
618
+ await command(rmCmd, { member_name: member, silent: true, failSoft: true, label: `settle: remove scratch SQL file for '${member}'` });
619
+ } catch (err) {
620
+ log(`[Dolt Settle] WARNING: could not remove scratch SQL file '${filePath}' for member '${member}' (non-fatal): ${err && err.message ? err.message : err}`);
621
+ }
622
+ }
623
+
624
+ /**
625
+ * Runs a query against the ephemeral server via the raw `dolt` CLI, using
626
+ * the exact live-verified flag set: `--no-tls` BEFORE `--host`/`--port`
627
+ * (order-sensitive), NEVER `--user`/`--password` (both trigger an
628
+ * interactive credential prompt that fails non-interactively -- see
629
+ * apra-fleet-ga61). `-r json` for parseable output. `USE beads;` is
630
+ * prepended automatically.
631
+ *
632
+ * @returns {Promise<object[]>} parsed rows (empty array for statements with no result set)
633
+ */
634
+ export async function runDoltSql({ command, member, platform, doltPath, host, port, query, log = () => {}, shell = '' }) {
635
+ // EVERY invocation is its own SQL SESSION -- `dolt sql -q` connects,
636
+ // runs, and disconnects -- so session-scoped state does NOT carry over
637
+ // between calls. `@@dolt_allow_commit_conflicts` is therefore set on each
638
+ // one, not once up front: without it DOLT_MERGE fails outright with
639
+ // "Merge conflict detected, @autocommit transaction rolled back"
640
+ // (verified live on fleet-lin-dev1). The conflict data itself IS durable
641
+ // -- it lives in the working set -- which is what lets the subsequent
642
+ // resolve/commit statements run in later sessions.
643
+ const target = { os: platform, shell };
644
+ const preamble = 'USE beads; SET @@dolt_allow_commit_conflicts = 1;';
645
+ const rawFullQuery = `${preamble} ${query}`;
646
+ const fullQuery = escapeSqlForShell(target, rawFullQuery);
647
+
648
+ // apra-fleet-ka1u bug #2: never risk bash's silent >8186-char -c
649
+ // truncation. Below the limit, keep the exact live-verified -q "<query>"
650
+ // invocation byte-identical (no behavior change for the overwhelming
651
+ // majority of settle's queries, which are short). At/above it, write the
652
+ // RAW (pre-escaped) query to a chunked scratch file and run -f instead --
653
+ // dolt reads that file's contents literally, so it needs no shell
654
+ // escaping at all, sidestepping both the length limit and its escaping.
655
+ let scratchFilePath = null;
656
+ let cmd;
657
+ if (fullQuery.length >= DOLT_SQL_INLINE_LIMIT) {
658
+ scratchFilePath = await writeDoltSqlScratchFile({ command, member, target, sql: rawFullQuery, log });
659
+ cmd = invokeBinary(target, doltPath, `--no-tls --host=${host} --port=${port} sql -r json -f "${scratchFilePath}"`);
660
+ } else {
661
+ cmd = invokeBinary(target, doltPath, `--no-tls --host=${host} --port=${port} sql -r json -q "${fullQuery}"`);
662
+ }
663
+ const res = await command(cmd, { member_name: member, silent: true, failSoft: true, label: `settle: dolt sql for '${member}'` });
664
+ if (scratchFilePath) {
665
+ await cleanupDoltSqlScratchFile({ command, member, target, filePath: scratchFilePath, log });
666
+ }
667
+ if (res && res.ok === false) {
668
+ throw new DoltSyncError(`[Dolt Settle] dolt sql query failed for member '${member}': ${res.error}\nquery: ${query}`, { member, doltOutput: res.error });
669
+ }
670
+ return parseDoltJsonRows(res && res.output);
671
+ }
672
+
673
+ /**
674
+ * Parse the rows out of a `dolt sql -r json` batch.
675
+ *
676
+ * A multi-statement `-q` emits ONE JSON document PER STATEMENT, concatenated
677
+ * (`{}` for a statement with no result set, `{"rows": [...]}` for a SELECT),
678
+ * so a plain JSON.parse of the whole output throws and silently yielded []
679
+ * -- which made settle believe a genuinely conflicted clone had no conflicted
680
+ * tables at all, and then fail at DOLT_COMMIT with "the table(s) issues are
681
+ * in conflict". Verified live on fleet-lin-dev1. Every settle query carries a
682
+ * `USE beads; SET ...;` preamble, so this is the NORMAL shape, not an edge
683
+ * case: take the last row-bearing document.
684
+ *
685
+ * @param {string|null|undefined} output
686
+ * @returns {object[]}
687
+ */
688
+ export function parseDoltJsonRows(output) {
689
+ const raw = String(output || '').trim();
690
+ if (!raw) return [];
691
+ try {
692
+ const parsed = JSON.parse(raw);
693
+ if (Array.isArray(parsed)) return parsed;
694
+ if (Array.isArray(parsed && parsed.rows)) return parsed.rows;
695
+ } catch { /* the multi-document shape below is the common case */ }
696
+
697
+ let rows = [];
698
+ for (const line of raw.split('\n')) {
699
+ const text = line.trim();
700
+ if (!text.startsWith('{')) continue;
701
+ try {
702
+ const doc = JSON.parse(text);
703
+ if (Array.isArray(doc)) rows = doc;
704
+ else if (Array.isArray(doc.rows)) rows = doc.rows;
705
+ } catch { /* not a complete JSON document on this line */ }
706
+ }
707
+ return rows;
708
+ }
709
+
710
+ // ---------------------------------------------------------------------------
711
+ // Section 6: the settle rulebook -- TOTAL over every conflicted table.
712
+ // ---------------------------------------------------------------------------
713
+
714
+ async function tableColumns({ command, member, platform, doltPath, host, port, table, shell }) {
715
+ const rows = await runDoltSql({
716
+ command, member, platform, doltPath, host, port, shell,
717
+ query: `SELECT COLUMN_NAME FROM information_schema.columns WHERE TABLE_NAME = '${table}';`,
718
+ });
719
+ return rows.map((r) => r.COLUMN_NAME || r.column_name).filter(Boolean);
720
+ }
721
+
722
+ /** The table's REAL uniqueness key, read live from information_schema -- never
723
+ * a hardcoded column list. Used by the set-union resolver to decide whether a
724
+ * `their_*` row is already present on our side. Falls back to the full column
725
+ * list (whole-row identity) when a table declares no PRIMARY KEY, which is
726
+ * still a correct -- if conservative -- set-union identity. */
727
+ async function tablePrimaryKey({ command, member, platform, doltPath, host, port, table, shell }) {
728
+ const rows = await runDoltSql({
729
+ command, member, platform, doltPath, host, port, shell,
730
+ query: `SELECT COLUMN_NAME FROM information_schema.key_column_usage WHERE TABLE_NAME = '${table}' AND CONSTRAINT_NAME = 'PRIMARY' ORDER BY ORDINAL_POSITION;`,
731
+ });
732
+ return rows.map((r) => r.COLUMN_NAME || r.column_name).filter(Boolean);
733
+ }
734
+
735
+ /** Generic per-field last-writer-wins-by-updated_at, applicable to ANY table
736
+ * that has an `updated_at` column -- this is what makes settle TOTAL rather
737
+ * than gated to a fixed table list. Falls back to a plain `--theirs`
738
+ * resolve for a table with no `updated_at` column. */
739
+ async function resolveLwwTable({ command, member, platform, doltPath, host, port, table, log, shell = '' }) {
740
+ const bq = String.fromCharCode(96); // backtick, built at runtime -- avoids a literal backslash-backtick sequence in source
741
+ const cols = await tableColumns({ command, member, platform, doltPath, host, port, table, shell });
742
+ if (!cols.includes('updated_at')) {
743
+ log(`[Dolt Settle] table '${table}' has no updated_at column -- resolving via plain --theirs (no per-field merge possible).`);
744
+ await runDoltSql({ command, member, platform, doltPath, host, port, shell, query: `CALL DOLT_CONFLICTS_RESOLVE('--theirs', '${table}');` });
745
+ return;
746
+ }
747
+ const pk = cols.includes('id') ? 'id' : cols[0];
748
+ const mutable = cols.filter((c) => c !== pk);
749
+ // TRUE per-field merge, against the BASE row -- not the design doc's
750
+ // original whole-row "recency wins every column" simplification, which the
751
+ // live disjoint-fields scenario disproved on fleet-lin-dev1: with A
752
+ // changing `status` and B changing `priority`, B's row was simply newer,
753
+ // so every column took B's value and A's status change was silently lost.
754
+ //
755
+ // Per field, in order:
756
+ // 1. we did not touch it (ours == base) -> take theirs
757
+ // 2. they did not touch it (theirs == base) -> take ours
758
+ // 3. BOTH changed it -> last-writer-wins on updated_at, tie to theirs
759
+ // (consistent with first-successful-pusher-wins: the remote already
760
+ // published)
761
+ // `<=>` is null-safe equality, so a NULL base (add/add, no base row) falls
762
+ // through to the LWW branch rather than matching everything.
763
+ const setClauses = mutable
764
+ .map((c) => ` t.${bq}${c}${bq} = CASE`
765
+ + ` WHEN c.our_${c} <=> c.base_${c} THEN c.their_${c}`
766
+ + ` WHEN c.their_${c} <=> c.base_${c} THEN c.our_${c}`
767
+ + ` WHEN c.their_updated_at >= c.our_updated_at THEN c.their_${c}`
768
+ + ` ELSE c.our_${c} END`)
769
+ .join(',\n ');
770
+ const updateSql = `
771
+ UPDATE ${bq}${table}${bq} t
772
+ JOIN dolt_conflicts_${table} c ON t.${bq}${pk}${bq} = c.our_${pk}
773
+ SET
774
+ ${setClauses},
775
+ t.updated_at = GREATEST(c.our_updated_at, c.their_updated_at)
776
+ WHERE t.${bq}${pk}${bq} IN (SELECT our_${pk} FROM dolt_conflicts_${table});
777
+ `;
778
+ await runDoltSql({ command, member, platform, doltPath, host, port, shell, query: updateSql });
779
+
780
+ // Their-side-only rows (an add they made that we do not have) would be
781
+ // DROPPED by the --ours resolve below, so carry them over first.
782
+ const keyCols = (await tablePrimaryKey({ command, member, platform, doltPath, host, port, table, shell })).length > 0
783
+ ? await tablePrimaryKey({ command, member, platform, doltPath, host, port, table, shell })
784
+ : [pk];
785
+ await runDoltSql({ command, member, platform, doltPath, host, port, shell, query: buildTheirMissingInsert(table, cols, keyCols) });
786
+
787
+ // --ours, NOT --theirs. The design doc flagged this as the one step to
788
+ // validate live, and the live run settled it: DOLT_CONFLICTS_RESOLVE
789
+ // rewrites the working-set row from the chosen side, so '--theirs' after
790
+ // the LWW UPDATE CLOBBERS the merged row (verified on fleet-lin-dev1: a
791
+ // row whose later updated_at was ours came back with their older value).
792
+ // '--ours' keeps the row the UPDATE just merged, which is the whole point
793
+ // of computing it.
794
+ await runDoltSql({ command, member, platform, doltPath, host, port, shell, query: `CALL DOLT_CONFLICTS_RESOLVE('--ours', '${table}');` });
795
+ }
796
+
797
+ /**
798
+ * INSERT every `their_*` row from dolt_conflicts_<table> that is not already
799
+ * present on our side, keyed on `keyCols`. Shared by the LWW resolver (where
800
+ * it carries over their-side-only adds before an --ours resolve) and the
801
+ * set-union resolver (where it IS the union).
802
+ */
803
+ function buildTheirMissingInsert(table, cols, keyCols) {
804
+ const bq = String.fromCharCode(96);
805
+ const quote = (c) => `${bq}${c}${bq}`;
806
+ const insertCols = cols.map(quote).join(', ');
807
+ const selectCols = cols.map((c) => `c.their_${c}`).join(', ');
808
+ const notNullGuard = keyCols.map((c) => `c.their_${c} IS NOT NULL`).join(' AND ');
809
+ // NOTE: built by concatenation, not a template literal, purely so the
810
+ // source never contains a backtick immediately followed by 't' -- the
811
+ // repo's pre-commit PowerShell-escape guard flags that 2-char sequence.
812
+ const matchOnKey = keyCols.map((c) => 't.' + quote(c) + ` = c.their_${c}`).join(' AND ');
813
+ return `
814
+ INSERT INTO ${quote(table)} (${insertCols})
815
+ SELECT ${selectCols}
816
+ FROM dolt_conflicts_${table} c
817
+ WHERE ${notNullGuard}
818
+ AND NOT EXISTS (
819
+ SELECT 1 FROM ${quote(table)} t WHERE ${matchOnKey}
820
+ );
821
+ `;
822
+ }
823
+
824
+ /**
825
+ * Set-union for add/add conflicts (`labels`): BOTH sides' rows must survive,
826
+ * so a plain `--theirs`/`--ours` resolve is wrong on its own -- it keeps one
827
+ * side's row shape and drops the other side's added rows outright.
828
+ *
829
+ * Mechanism (design doc Part 3.2 step 4, "labels: set-union"): our side's rows
830
+ * are already in the working set by construction (they are what our clone
831
+ * committed), so the union reduces to inserting every `their_*` row from
832
+ * dolt_conflicts_<table> that is not already present on our side, keyed on the
833
+ * table's REAL uniqueness key -- read live from information_schema, never
834
+ * hardcoded (a schema change that renames/extends the key must not silently
835
+ * turn this into a no-op or a duplicate-row insert). The subsequent
836
+ * DOLT_CONFLICTS_RESOLVE only clears the conflict markers: the actual data
837
+ * reconciliation has already happened in the INSERT above.
838
+ *
839
+ * A table with no discoverable columns, or whose conflict view carries no
840
+ * `their_*` projection of the key, degrades to a plain `--theirs` resolve
841
+ * rather than issuing an INSERT it cannot construct correctly -- settle stays
842
+ * total either way.
843
+ */
844
+ async function resolveUnionTable({ command, member, platform, doltPath, host, port, table, log, shell = '' }) {
845
+ const cols = await tableColumns({ command, member, platform, doltPath, host, port, table, shell });
846
+ if (cols.length === 0) {
847
+ log(`[Dolt Settle] table '${table}' set-union: could not read its columns from information_schema -- falling back to a plain --theirs resolve.`);
848
+ await runDoltSql({ command, member, platform, doltPath, host, port, shell, query: `CALL DOLT_CONFLICTS_RESOLVE('--theirs', '${table}');` });
849
+ return;
850
+ }
851
+
852
+ const pkFromSchema = await tablePrimaryKey({ command, member, platform, doltPath, host, port, table, shell });
853
+ const keyCols = pkFromSchema.length > 0 ? pkFromSchema : cols;
854
+ log(`[Dolt Settle] table '${table}' conflict: resolving as a set-union (both sides' rows kept; identity = ${keyCols.join(' + ')}).`);
855
+
856
+ await runDoltSql({ command, member, platform, doltPath, host, port, shell, query: buildTheirMissingInsert(table, cols, keyCols) });
857
+ // --ours, not --theirs (same live finding as resolveLwwTable): the resolve
858
+ // rewrites the working-set row from the chosen side, so --theirs here
859
+ // would undo the union by dropping the rows only WE had. Their rows have
860
+ // just been inserted, so --ours is what actually keeps both sides.
861
+ await runDoltSql({ command, member, platform, doltPath, host, port, shell, query: `CALL DOLT_CONFLICTS_RESOLVE('--ours', '${table}');` });
862
+ }
863
+
864
+ /** Plain theirs -- machine-local/config rows, and append-only tables
865
+ * (comments/events) where both sides already survive by construction. */
866
+ async function resolveTheirsTable({ command, member, platform, doltPath, host, port, table, log, shell = '' }) {
867
+ log(`[Dolt Settle] table '${table}' conflict: resolving --theirs.`);
868
+ await runDoltSql({ command, member, platform, doltPath, host, port, shell, query: `CALL DOLT_CONFLICTS_RESOLVE('--theirs', '${table}');` });
869
+ }
870
+
871
+ /** Dispatch a single conflicted table to its rulebook entry, or the generic
872
+ * LWW fallback if it has no named entry -- this fallback is what makes
873
+ * settle total rather than an allowlist. */
874
+ async function resolveConflictedTable(ctx, table) {
875
+ const kind = NAMED_RULEBOOK[table] || 'lww';
876
+ if (kind === 'union') return resolveUnionTable({ ...ctx, table });
877
+ if (kind === 'theirs') return resolveTheirsTable({ ...ctx, table });
878
+ return resolveLwwTable({ ...ctx, table });
879
+ }
880
+
881
+ // ---------------------------------------------------------------------------
882
+ // Section 7: the orchestrator.
883
+ // ---------------------------------------------------------------------------
884
+
885
+ /**
886
+ * @typedef {Object} SettleOpts
887
+ * @property {(cmd: string, opts?: object) => Promise<{ok: boolean, output?: string, error?: string}>} command
888
+ * @property {(msg: string) => void} [log]
889
+ * @property {'win32'|'linux'|'darwin'} platform - the MEMBER's platform. REQUIRED -- never assume process.platform.
890
+ * @property {'x64'|'arm64'} [arch]
891
+ * @property {string} [shell] - the MEMBER's registered shell ('gitbash' on a Windows member running Git-for-Windows bash, '' otherwise). Resolved via runner.js's resolveMemberTarget; drives memberDoltPath/invokeBinary/escapeSqlForShell's dialect through se-os-commands.mjs's getSeCommands (apra-fleet-7dir.16). Defaults to '' (PowerShell dialect on Windows), matching pre-shell-aware behavior when unknown.
892
+ * @property {string} [remote]
893
+ * @property {string} [branch]
894
+ * @property {number} [portRangeStart]
895
+ * @property {number} [portRangeEnd]
896
+ */
897
+
898
+ /**
899
+ * Total, deterministic settle: resolves EVERY row-level Dolt conflict shape
900
+ * this data model can produce, no gates, no escalation. Only throws on a
901
+ * genuine operational failure (no usable dolt binary, server wouldn't
902
+ * start, a SQL statement errored for a reason unrelated to conflict
903
+ * content) -- callers treat that exactly like any other infra command
904
+ * failure (dolt-sync.mjs's existing degraded/fatal taxonomy), NOT as a
905
+ * ladder tier.
906
+ *
907
+ * @param {string} member
908
+ * @param {SettleOpts} opts
909
+ * @returns {Promise<{ ok: true, resolvedTables: string[], warnings: string[], doltVersionUsed: string }>}
910
+ */
911
+ export async function settleDoltConflicts(member, opts = {}) {
912
+ const {
913
+ command,
914
+ log = () => {},
915
+ platform,
916
+ arch = 'x64',
917
+ shell = '',
918
+ remote = 'origin',
919
+ branch = 'main',
920
+ portRangeStart = DEFAULT_PORT_RANGE.start,
921
+ portRangeEnd = DEFAULT_PORT_RANGE.end,
922
+ } = opts;
923
+
924
+ if (!member) throw new Error('settleDoltConflicts requires a member');
925
+ if (typeof command !== 'function') throw new Error('settleDoltConflicts requires an injected command() in opts');
926
+ if (!platform) throw new Error("settleDoltConflicts requires opts.platform ('win32'|'linux'|'darwin') -- the MEMBER's platform, never assumed");
927
+
928
+ let host = RECOVERY_SQL_SERVER_HOST;
929
+ let pid = null;
930
+ let port = null;
931
+ let weSpawnedTheServer = false;
932
+
933
+ try {
934
+ // Step 0: resolve the real data dir/mode -- never hardcoded.
935
+ const status = await resolveDoltStatus({ command, member, log });
936
+
937
+ // Step 1: ensure a correctly-pinned (or functionally-probed-fallback)
938
+ // dolt binary exists on the member.
939
+ const doltInfo = await ensurePinnedDolt({ command, member, platform, arch, shell, log });
940
+ const warnings = [...doltInfo.warnings];
941
+
942
+ if (status.mode === 'server' && status.host && status.port) {
943
+ // Reuse the member's own already-live server rather than spawning
944
+ // a second one against the same data dir (design doc Part 3.5/7.2).
945
+ host = status.host;
946
+ port = status.port;
947
+ log(`[Dolt Settle] member '${member}' already has a live server at ${status.host}:${status.port} -- targeting it instead of spawning a second one.`);
948
+ } else {
949
+ const dataDir = status.dataDir || DEFAULT_EMBEDDED_DATA_DIR;
950
+ port = await pickFreePort({ command, member, platform, shell, portRangeStart, portRangeEnd });
951
+
952
+ // A busy candidate port is SKIPPED, not killed-and-reused: pickFreePort
953
+ // only ever hands back a port nothing answers on (design doc Part 3.5,
954
+ // amended -- see pickFreePort's own docstring below for why). A
955
+ // stray already-listening server on/near our data dir is left for
956
+ // the supervisor's orphan sweep to reap; settle does not attempt to
957
+ // distinguish "genuinely orphaned residue" from "another concurrent
958
+ // settle legitimately in progress" inline, since getting that
959
+ // distinction wrong (killing a live settle) is worse than the
960
+ // bounded wait on the sweep.
961
+ // spawnEphemeralServer embeds doltPath inside a raw PowerShell/WMI
962
+ // script body on Windows (Section 4). The script body itself must
963
+ // keep receiving the PowerShell-dialect path (psDoltPath)
964
+ // regardless of the member's actual registered shell -- the
965
+ // dialect INSIDE the wrapped script is always PowerShell -- but
966
+ // the OUTER invocation is now routed through
967
+ // getSeCommands(...).wrapPowerShellScript via `shell`
968
+ // (apra-fleet-7dir.22), so a gitbash member gets it via
969
+ // `powershell -EncodedCommand` from bash instead of the raw
970
+ // PowerShell text being handed directly to bash.
971
+ const spawned = await spawnEphemeralServer({ command, member, platform, doltPath: doltInfo.psDoltPath, dataDir, host, port, shell, log });
972
+ pid = spawned.pid;
973
+ weSpawnedTheServer = true;
974
+ await waitForServerReady({ command, member, platform, shell, host, port, log });
975
+ }
976
+
977
+ // If not preflight-validated by the pin ladder, the fallback dolt
978
+ // must pass a harmless functional preflight before any real data is
979
+ // touched (Part 5.6 step 3). runDoltSql() already throws a
980
+ // DoltSyncError on any command failure (res.ok === false) and
981
+ // otherwise always returns an array (parseDoltJsonRows never returns
982
+ // a non-array) -- so that throw IS the gate; there is no reachable
983
+ // "succeeded but returned something unusable" case to additionally
984
+ // check here.
985
+ if (!doltInfo.pinned) {
986
+ await runDoltSql({ command, member, platform, doltPath: doltInfo.doltPath, host, port, query: 'SELECT 1;', log, shell });
987
+ }
988
+
989
+ // Step 3/4: re-open the merge, enumerate every conflicted table.
990
+ const ctx = { command, member, platform, doltPath: doltInfo.doltPath, host, port, log, shell };
991
+ await runDoltSql({ ...ctx, query: `CALL DOLT_MERGE('${remote}/${branch}');` });
992
+
993
+ // NOTE: `SELECT *`, not a backtick-quoted `table` column -- dolt_conflicts'
994
+ // only other column is num_conflicts, and avoiding the identifier quote
995
+ // keeps this one (very frequently issued) query free of the shell's
996
+ // backtick minefield entirely.
997
+ const conflictRows = await runDoltSql({ ...ctx, query: 'SELECT * FROM dolt_conflicts;' });
998
+ const tables = conflictRows.map((r) => r.table || r.TABLE).filter(Boolean);
999
+
1000
+ if (tables.length === 0) {
1001
+ log(`[Dolt Settle] no conflicted tables found for member '${member}' after DOLT_MERGE -- nothing to resolve (the clone may have already been fixed).`);
1002
+ }
1003
+
1004
+ for (const table of tables) {
1005
+ // eslint-disable-next-line no-await-in-loop -- sequential by design: each table's UPDATE must land before its own DOLT_CONFLICTS_RESOLVE
1006
+ await resolveConflictedTable(ctx, table);
1007
+ }
1008
+
1009
+ await runDoltSql({ ...ctx, query: `CALL DOLT_COMMIT('-m', 'settle: automated deterministic conflict resolution for ${member}');` });
1010
+
1011
+ const remaining = await runDoltSql({ ...ctx, query: 'SELECT COUNT(*) AS n FROM dolt_conflicts;' });
1012
+ const remainingCount = Number((remaining[0] && (remaining[0].n ?? remaining[0].N)) || 0);
1013
+ if (remainingCount !== 0) {
1014
+ throw new DoltSyncError(`[Dolt Settle] ${remainingCount} conflict(s) still remain for member '${member}' after resolving every enumerated table -- refusing to commit/push a partially-resolved clone.`, { member });
1015
+ }
1016
+
1017
+ // Step 5 (CORRECTED ORDER, design doc Part 7.2): tear the server down
1018
+ // BEFORE republishing -- embedded bd must not race the server's
1019
+ // exclusive chunk-journal lock on the same data dir.
1020
+ if (weSpawnedTheServer && pid) {
1021
+ await killServerAndVerify({ command, member, platform, shell, pid, host, port, log });
1022
+ pid = null;
1023
+ }
1024
+
1025
+ const pull = await command('bd dolt pull', { member_name: member, silent: true, failSoft: true, label: `settle: post-resolve D-pull for '${member}'` });
1026
+ if (pull && pull.ok === false) {
1027
+ throw new DoltDivergedError(`[Dolt Settle] post-resolve pull still failed for member '${member}': ${pull.error}`, { member, doltOutput: pull.error, operation: 'settle-pull' });
1028
+ }
1029
+ const push = await command('bd dolt push', { member_name: member, silent: true, failSoft: true, label: `settle: post-resolve D-push for '${member}'` });
1030
+ if (push && push.ok === false) {
1031
+ throw new DoltDivergedError(`[Dolt Settle] resolved every conflict but the republishing push was still rejected for member '${member}': ${push.error}`, { member, doltOutput: push.error, operation: 'settle-push' });
1032
+ }
1033
+
1034
+ log(`[Dolt Settle] SUCCEEDED for member '${member}': ${tables.length} table(s) resolved (${tables.join(', ') || 'none'}), republished.`);
1035
+ return { ok: true, resolvedTables: tables, warnings, doltVersionUsed: doltInfo.version };
1036
+ } finally {
1037
+ // Guaranteed teardown -- covers every throw path above. On the happy
1038
+ // path pid is already null (torn down before republish per 7.2).
1039
+ if (weSpawnedTheServer && pid) {
1040
+ await killServerAndVerify({ command, member, platform, shell, pid, host, port, log }).catch((err) => {
1041
+ log(`[Dolt Settle] WARNING: finally-block teardown failed for member '${member}': ${err.message}`);
1042
+ });
1043
+ }
1044
+ }
1045
+ }
1046
+
1047
+ // ---------------------------------------------------------------------------
1048
+ // Section 8: the wiring seam -- what dolt-sync.mjs/runner.js actually hold.
1049
+ // ---------------------------------------------------------------------------
1050
+
1051
+ /**
1052
+ * Resolve the MEMBER's platform/arch (never the orchestrator's -- see design
1053
+ * doc Part 5.3). Callers that already have registry metadata should pass
1054
+ * `platform`/`arch` explicitly; this probe is the fallback for callers (like
1055
+ * the sprint runner's sync brackets) that only hold a member name and a
1056
+ * command(). Members necessarily have node, since `bd` is npm-installed.
1057
+ *
1058
+ * @returns {Promise<{ platform: 'win32'|'linux'|'darwin', arch: string }>}
1059
+ */
1060
+ export async function detectMemberPlatform({ command, member }) {
1061
+ // Quote-free JS on purpose: PowerShell 5.1 mangles quotes inside native
1062
+ // arguments, so a snippet with no quotes at all is the one form that
1063
+ // survives every member shell unchanged.
1064
+ const res = await command("node -e 'console.log(process.platform,process.arch)'", {
1065
+ member_name: member, silent: true, failSoft: true, label: `settle: detect platform for '${member}'`,
1066
+ });
1067
+ const text = String((res && (res.output || res.error)) || '');
1068
+ const match = text.match(/\b(win32|linux|darwin)\b\s+(\S+)/);
1069
+ if (!match) {
1070
+ throw new DoltSyncError(
1071
+ `[Dolt Settle] could not detect the platform of member '${member}' -- settle refuses to assume the orchestrator's own platform. Raw: ${text.slice(0, 200)}`,
1072
+ { member, doltOutput: text },
1073
+ );
1074
+ }
1075
+ return { platform: match[1], arch: match[2] === 'arm64' ? 'arm64' : 'x64' };
1076
+ }
1077
+
1078
+ /**
1079
+ * Build the zero-argument settle callback the sync brackets hold at their
1080
+ * divergence terminals (`opts.settle` in dolt-sync.mjs). This is the single
1081
+ * seam that REPLACES buildDoltRecoveryLadder(): one deterministic function,
1082
+ * no tiers, no agent/model threading, and -- unlike the old ladder -- a
1083
+ * resolved promise IS a verified recovery, because settle republishes and
1084
+ * verifies before returning.
1085
+ *
1086
+ * The member's platform is resolved lazily on first invocation (nothing is
1087
+ * probed unless a divergence actually happens) and cached for the callback's
1088
+ * lifetime.
1089
+ *
1090
+ * @param {string} member
1091
+ * @param {{ command: Function, log?: Function, platform?: string, arch?: string, shell?: string }} opts
1092
+ * @returns {() => Promise<{ ok: true, resolvedTables: string[], warnings: string[], doltVersionUsed: string }>}
1093
+ */
1094
+ export function buildSettleCallback(member, opts = {}) {
1095
+ const { command, log = () => {}, platform, arch, shell = '' } = opts;
1096
+ if (!member) throw new Error('buildSettleCallback requires a member');
1097
+ if (typeof command !== 'function') throw new Error('buildSettleCallback requires an injected command() in opts');
1098
+
1099
+ let resolved = platform ? { platform, arch: arch || 'x64' } : null;
1100
+ return async () => {
1101
+ if (!resolved) resolved = await detectMemberPlatform({ command, member });
1102
+ // `shell` is resolved once by the CALLER (runner.js's
1103
+ // resolveMemberTarget, via member_detail) and closed over here --
1104
+ // detectMemberPlatform only probes process.platform/arch on the
1105
+ // member, which carries no shell information, so it cannot supply
1106
+ // this itself (apra-fleet-7dir.16).
1107
+ return settleDoltConflicts(member, { command, log, platform: resolved.platform, arch: resolved.arch, shell });
1108
+ };
1109
+ }
1110
+
1111
+ /**
1112
+ * Ephemeral port selection: find the first port in the range nothing is
1113
+ * answering on. Deliberately ONE dispatch that scans member-side rather than
1114
+ * one dispatch per candidate port -- a 100-port range would otherwise be 100
1115
+ * SSH round trips.
1116
+ *
1117
+ * A port already answering is NOT reused even though it might be an orphaned
1118
+ * settle server: per design doc Part 3.5, this is a DELIBERATE, accepted
1119
+ * trade-off, not the originally-sketched "kill it, then spawn fresh" -- a
1120
+ * same-data-dir orphan cannot be safely distinguished inline from another
1121
+ * concurrent settle legitimately in progress without risking killing a live
1122
+ * one, so settle always skips to the next free port and leaves reaping to the
1123
+ * supervisor's orphan sweep (dolt-orphan-sweep.mjs). Consequence: if the
1124
+ * orchestrator dies mid-settle, a fresh settle attempt against the SAME data
1125
+ * dir can be blocked (lock held / falls back read-only) for up to the sweep's
1126
+ * age threshold plus its run interval (~15 minutes with the current
1127
+ * defaults) until the sweep reaps the orphan.
1128
+ */
1129
+ async function pickFreePort({ command, member, platform, shell = '', portRangeStart, portRangeEnd }) {
1130
+ // Same node-based probe as tcpProbeScript, scanning the range member-side
1131
+ // in ONE dispatch: a round trip per candidate port would be 100 SSH
1132
+ // sessions, and no shell one-liner is portable across PowerShell 5.1,
1133
+ // bash and zsh (see tcpProbeScript for the live evidence). Dialect is
1134
+ // resolved off the member's registered shell, not bare platform, so a
1135
+ // gitbash member takes the POSIX (unescaped) nodeEval branch just like
1136
+ // tcpProbeScript (apra-fleet-7dir.22).
1137
+ const script = nodeEval({ os: platform, shell },
1138
+ `const net=require("net");const host="${RECOVERY_SQL_SERVER_HOST}";`
1139
+ + 'const free=(p)=>new Promise((r)=>{const s=net.connect(p,host);const done=(v)=>{try{s.destroy()}catch(e){};r(v)};'
1140
+ + 's.on("connect",()=>done(false));s.on("error",()=>done(true));setTimeout(()=>done(true),500)});'
1141
+ + `(async()=>{for(let p=${portRangeStart};p<${portRangeEnd};p++){if(await free(p)){console.log("FREEPORT:"+p);break}}})()`);
1142
+ const res = await command(script, { member_name: member, silent: true, failSoft: true, label: `settle: pick a free ephemeral port for '${member}'` });
1143
+ const match = String((res && res.output) || '').match(/FREEPORT:(\d+)/);
1144
+ if (!match) {
1145
+ throw new DoltSyncError(`[Dolt Settle] no free port in range [${portRangeStart}, ${portRangeEnd}) for member '${member}'.`, { member, doltOutput: (res && (res.output || res.error)) || '' });
1146
+ }
1147
+ return Number(match[1]);
1148
+ }