@apralabs/apra-fleet 0.3.6 → 0.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (826) hide show
  1. package/README.md +378 -252
  2. package/dist/agents/backlog-groomer.md +303 -0
  3. package/dist/agents/ci-watcher.md +13 -1
  4. package/dist/agents/deployer.md +66 -13
  5. package/dist/agents/doer.md +67 -8
  6. package/dist/agents/harvester.md +22 -3
  7. package/dist/agents/integ-test-runner.md +166 -60
  8. package/dist/agents/kb-reconciler.md +216 -0
  9. package/dist/agents/plan-reviewer.md +88 -18
  10. package/dist/agents/planner.md +182 -19
  11. package/dist/agents/regression-test-runner.md +234 -0
  12. package/dist/agents/reviewer.md +125 -9
  13. package/dist/agents/schemas/backlog-groomer-input.json +35 -0
  14. package/dist/agents/schemas/backlog-groomer-output.json +164 -0
  15. package/dist/agents/schemas/doer-output.json +63 -3
  16. package/dist/agents/schemas/harvester-output.json +59 -2
  17. package/dist/agents/schemas/integ-test-runner-output.json +34 -0
  18. package/dist/agents/schemas/kb-reconciler-output.json +87 -0
  19. package/dist/agents/schemas/planner-output.json +65 -0
  20. package/dist/agents/schemas/regression-test-runner-input.json +15 -0
  21. package/dist/agents/schemas/regression-test-runner-output.json +50 -0
  22. package/dist/agents/schemas/reviewer-output.json +108 -7
  23. package/dist/cli/agent-transform.d.ts +1 -0
  24. package/dist/cli/agent-transform.d.ts.map +1 -1
  25. package/dist/cli/agent-transform.js +77 -0
  26. package/dist/cli/agent-transform.js.map +1 -1
  27. package/dist/cli/auth.d.ts +3 -0
  28. package/dist/cli/auth.d.ts.map +1 -1
  29. package/dist/cli/auth.js +181 -5
  30. package/dist/cli/auth.js.map +1 -1
  31. package/dist/cli/config.d.ts +5 -1
  32. package/dist/cli/config.d.ts.map +1 -1
  33. package/dist/cli/config.js +7 -1
  34. package/dist/cli/config.js.map +1 -1
  35. package/dist/cli/dolt-install.d.ts +91 -0
  36. package/dist/cli/dolt-install.d.ts.map +1 -0
  37. package/dist/cli/dolt-install.js +334 -0
  38. package/dist/cli/dolt-install.js.map +1 -0
  39. package/dist/cli/install-guard.d.ts +29 -0
  40. package/dist/cli/install-guard.d.ts.map +1 -0
  41. package/dist/cli/install-guard.js +153 -0
  42. package/dist/cli/install-guard.js.map +1 -0
  43. package/dist/cli/install.d.ts +45 -3
  44. package/dist/cli/install.d.ts.map +1 -1
  45. package/dist/cli/install.js +736 -109
  46. package/dist/cli/install.js.map +1 -1
  47. package/dist/cli/join.d.ts +12 -0
  48. package/dist/cli/join.d.ts.map +1 -0
  49. package/dist/cli/join.js +87 -0
  50. package/dist/cli/join.js.map +1 -0
  51. package/dist/cli/kb-commit.d.ts +12 -0
  52. package/dist/cli/kb-commit.d.ts.map +1 -0
  53. package/dist/cli/kb-commit.js +53 -0
  54. package/dist/cli/kb-commit.js.map +1 -0
  55. package/dist/cli/kb-directives.d.ts +17 -0
  56. package/dist/cli/kb-directives.d.ts.map +1 -0
  57. package/dist/cli/kb-directives.js +146 -0
  58. package/dist/cli/kb-directives.js.map +1 -0
  59. package/dist/cli/kb-import.d.ts +13 -0
  60. package/dist/cli/kb-import.d.ts.map +1 -0
  61. package/dist/cli/kb-import.js +56 -0
  62. package/dist/cli/kb-import.js.map +1 -0
  63. package/dist/cli/register-member.d.ts +2 -0
  64. package/dist/cli/register-member.d.ts.map +1 -0
  65. package/dist/cli/register-member.js +193 -0
  66. package/dist/cli/register-member.js.map +1 -0
  67. package/dist/cli/restart.d.ts +2 -0
  68. package/dist/cli/restart.d.ts.map +1 -0
  69. package/dist/cli/restart.js +7 -0
  70. package/dist/cli/restart.js.map +1 -0
  71. package/dist/cli/spoke.d.ts +35 -0
  72. package/dist/cli/spoke.d.ts.map +1 -0
  73. package/dist/cli/spoke.js +212 -0
  74. package/dist/cli/spoke.js.map +1 -0
  75. package/dist/cli/start.d.ts +2 -0
  76. package/dist/cli/start.d.ts.map +1 -0
  77. package/dist/cli/start.js +92 -0
  78. package/dist/cli/start.js.map +1 -0
  79. package/dist/cli/status.d.ts +2 -0
  80. package/dist/cli/status.d.ts.map +1 -0
  81. package/dist/cli/status.js +83 -0
  82. package/dist/cli/status.js.map +1 -0
  83. package/dist/cli/stop.d.ts +2 -0
  84. package/dist/cli/stop.d.ts.map +1 -0
  85. package/dist/cli/stop.js +51 -0
  86. package/dist/cli/stop.js.map +1 -0
  87. package/dist/cli/uninstall.d.ts.map +1 -1
  88. package/dist/cli/uninstall.js +120 -9
  89. package/dist/cli/uninstall.js.map +1 -1
  90. package/dist/cli/update.d.ts.map +1 -1
  91. package/dist/cli/update.js +10 -1
  92. package/dist/cli/update.js.map +1 -1
  93. package/dist/cli/watch.d.ts +53 -4
  94. package/dist/cli/watch.d.ts.map +1 -1
  95. package/dist/cli/watch.js +118 -17
  96. package/dist/cli/watch.js.map +1 -1
  97. package/dist/cli/workflow-assets.d.ts +37 -0
  98. package/dist/cli/workflow-assets.d.ts.map +1 -0
  99. package/dist/cli/workflow-assets.js +144 -0
  100. package/dist/cli/workflow-assets.js.map +1 -0
  101. package/dist/cli/workflow.d.ts +75 -0
  102. package/dist/cli/workflow.d.ts.map +1 -0
  103. package/dist/cli/workflow.js +397 -0
  104. package/dist/cli/workflow.js.map +1 -0
  105. package/dist/commands/kb-server.d.ts +8 -0
  106. package/dist/commands/kb-server.d.ts.map +1 -0
  107. package/dist/commands/kb-server.js +221 -0
  108. package/dist/commands/kb-server.js.map +1 -0
  109. package/dist/hub-service/activity.d.ts +30 -0
  110. package/dist/hub-service/activity.d.ts.map +1 -0
  111. package/dist/hub-service/activity.js +20 -0
  112. package/dist/hub-service/activity.js.map +1 -0
  113. package/dist/hub-service/audit-log.d.ts +19 -0
  114. package/dist/hub-service/audit-log.d.ts.map +1 -0
  115. package/dist/hub-service/audit-log.js +13 -0
  116. package/dist/hub-service/audit-log.js.map +1 -0
  117. package/dist/hub-service/db/pool.d.ts +19 -0
  118. package/dist/hub-service/db/pool.d.ts.map +1 -0
  119. package/dist/hub-service/db/pool.js +53 -0
  120. package/dist/hub-service/db/pool.js.map +1 -0
  121. package/dist/hub-service/enrollment.d.ts +29 -0
  122. package/dist/hub-service/enrollment.d.ts.map +1 -0
  123. package/dist/hub-service/enrollment.js +48 -0
  124. package/dist/hub-service/enrollment.js.map +1 -0
  125. package/dist/hub-service/envelope-routes.d.ts +46 -0
  126. package/dist/hub-service/envelope-routes.d.ts.map +1 -0
  127. package/dist/hub-service/envelope-routes.js +94 -0
  128. package/dist/hub-service/envelope-routes.js.map +1 -0
  129. package/dist/hub-service/handlers/installers.d.ts +14 -0
  130. package/dist/hub-service/handlers/installers.d.ts.map +1 -0
  131. package/dist/hub-service/handlers/installers.js +8 -0
  132. package/dist/hub-service/handlers/installers.js.map +1 -0
  133. package/dist/hub-service/http-server.d.ts +31 -0
  134. package/dist/hub-service/http-server.d.ts.map +1 -0
  135. package/dist/hub-service/http-server.js +711 -0
  136. package/dist/hub-service/http-server.js.map +1 -0
  137. package/dist/hub-service/hub-jwt.d.ts +30 -0
  138. package/dist/hub-service/hub-jwt.d.ts.map +1 -0
  139. package/dist/hub-service/hub-jwt.js +105 -0
  140. package/dist/hub-service/hub-jwt.js.map +1 -0
  141. package/dist/hub-service/jwt-revocation.d.ts +20 -0
  142. package/dist/hub-service/jwt-revocation.d.ts.map +1 -0
  143. package/dist/hub-service/jwt-revocation.js +18 -0
  144. package/dist/hub-service/jwt-revocation.js.map +1 -0
  145. package/dist/hub-service/machines.d.ts +16 -0
  146. package/dist/hub-service/machines.d.ts.map +1 -0
  147. package/dist/hub-service/machines.js +14 -0
  148. package/dist/hub-service/machines.js.map +1 -0
  149. package/dist/hub-service/main.d.ts +3 -0
  150. package/dist/hub-service/main.d.ts.map +1 -0
  151. package/dist/hub-service/main.js +64 -0
  152. package/dist/hub-service/main.js.map +1 -0
  153. package/dist/hub-service/member-tokens.d.ts +11 -0
  154. package/dist/hub-service/member-tokens.d.ts.map +1 -0
  155. package/dist/hub-service/member-tokens.js +49 -0
  156. package/dist/hub-service/member-tokens.js.map +1 -0
  157. package/dist/hub-service/member-view.d.ts +20 -0
  158. package/dist/hub-service/member-view.d.ts.map +1 -0
  159. package/dist/hub-service/member-view.js +76 -0
  160. package/dist/hub-service/member-view.js.map +1 -0
  161. package/dist/hub-service/members.d.ts +44 -0
  162. package/dist/hub-service/members.d.ts.map +1 -0
  163. package/dist/hub-service/members.js +25 -0
  164. package/dist/hub-service/members.js.map +1 -0
  165. package/dist/hub-service/presence.d.ts +40 -0
  166. package/dist/hub-service/presence.d.ts.map +1 -0
  167. package/dist/hub-service/presence.js +44 -0
  168. package/dist/hub-service/presence.js.map +1 -0
  169. package/dist/hub-service/project-view.d.ts +12 -0
  170. package/dist/hub-service/project-view.d.ts.map +1 -0
  171. package/dist/hub-service/project-view.js +34 -0
  172. package/dist/hub-service/project-view.js.map +1 -0
  173. package/dist/hub-service/projects.d.ts +48 -0
  174. package/dist/hub-service/projects.d.ts.map +1 -0
  175. package/dist/hub-service/projects.js +80 -0
  176. package/dist/hub-service/projects.js.map +1 -0
  177. package/dist/hub-service/relay-queue.d.ts +115 -0
  178. package/dist/hub-service/relay-queue.d.ts.map +1 -0
  179. package/dist/hub-service/relay-queue.js +148 -0
  180. package/dist/hub-service/relay-queue.js.map +1 -0
  181. package/dist/hub-service/session-jwt.d.ts +10 -0
  182. package/dist/hub-service/session-jwt.d.ts.map +1 -0
  183. package/dist/hub-service/session-jwt.js +69 -0
  184. package/dist/hub-service/session-jwt.js.map +1 -0
  185. package/dist/hub-service/usage.d.ts +40 -0
  186. package/dist/hub-service/usage.d.ts.map +1 -0
  187. package/dist/hub-service/usage.js +25 -0
  188. package/dist/hub-service/usage.js.map +1 -0
  189. package/dist/hub-service/users.d.ts +56 -0
  190. package/dist/hub-service/users.d.ts.map +1 -0
  191. package/dist/hub-service/users.js +72 -0
  192. package/dist/hub-service/users.js.map +1 -0
  193. package/dist/hub-service/workspaces.d.ts +20 -0
  194. package/dist/hub-service/workspaces.d.ts.map +1 -0
  195. package/dist/hub-service/workspaces.js +10 -0
  196. package/dist/hub-service/workspaces.js.map +1 -0
  197. package/dist/index.js +254 -132
  198. package/dist/index.js.map +1 -1
  199. package/dist/os/linux.d.ts +14 -0
  200. package/dist/os/linux.d.ts.map +1 -1
  201. package/dist/os/linux.js +80 -4
  202. package/dist/os/linux.js.map +1 -1
  203. package/dist/os/os-commands.d.ts +15 -0
  204. package/dist/os/os-commands.d.ts.map +1 -1
  205. package/dist/os/windows.d.ts +36 -0
  206. package/dist/os/windows.d.ts.map +1 -1
  207. package/dist/os/windows.js +74 -18
  208. package/dist/os/windows.js.map +1 -1
  209. package/dist/paths.d.ts +23 -0
  210. package/dist/paths.d.ts.map +1 -1
  211. package/dist/paths.js +29 -0
  212. package/dist/paths.js.map +1 -1
  213. package/dist/providers/agy.d.ts +20 -2
  214. package/dist/providers/agy.d.ts.map +1 -1
  215. package/dist/providers/agy.js +259 -21
  216. package/dist/providers/agy.js.map +1 -1
  217. package/dist/providers/claude.d.ts +16 -2
  218. package/dist/providers/claude.d.ts.map +1 -1
  219. package/dist/providers/claude.js +283 -16
  220. package/dist/providers/claude.js.map +1 -1
  221. package/dist/providers/codex.d.ts +13 -2
  222. package/dist/providers/codex.d.ts.map +1 -1
  223. package/dist/providers/codex.js +36 -6
  224. package/dist/providers/codex.js.map +1 -1
  225. package/dist/providers/copilot.d.ts +13 -2
  226. package/dist/providers/copilot.d.ts.map +1 -1
  227. package/dist/providers/copilot.js +34 -7
  228. package/dist/providers/copilot.js.map +1 -1
  229. package/dist/providers/email/headers.d.ts +15 -0
  230. package/dist/providers/email/headers.d.ts.map +1 -0
  231. package/dist/providers/email/headers.js +42 -0
  232. package/dist/providers/email/headers.js.map +1 -0
  233. package/dist/providers/email/index.d.ts +18 -0
  234. package/dist/providers/email/index.d.ts.map +1 -0
  235. package/dist/providers/email/index.js +60 -0
  236. package/dist/providers/email/index.js.map +1 -0
  237. package/dist/providers/email/provider.d.ts +49 -0
  238. package/dist/providers/email/provider.d.ts.map +1 -0
  239. package/dist/providers/email/provider.js +2 -0
  240. package/dist/providers/email/provider.js.map +1 -0
  241. package/dist/providers/email/sendgrid.d.ts +12 -0
  242. package/dist/providers/email/sendgrid.d.ts.map +1 -0
  243. package/dist/providers/email/sendgrid.js +67 -0
  244. package/dist/providers/email/sendgrid.js.map +1 -0
  245. package/dist/providers/email/smtp.d.ts +65 -0
  246. package/dist/providers/email/smtp.d.ts.map +1 -0
  247. package/dist/providers/email/smtp.js +373 -0
  248. package/dist/providers/email/smtp.js.map +1 -0
  249. package/dist/providers/gemini.d.ts +13 -2
  250. package/dist/providers/gemini.d.ts.map +1 -1
  251. package/dist/providers/gemini.js +49 -5
  252. package/dist/providers/gemini.js.map +1 -1
  253. package/dist/providers/index.d.ts +1 -0
  254. package/dist/providers/index.d.ts.map +1 -1
  255. package/dist/providers/index.js +3 -0
  256. package/dist/providers/index.js.map +1 -1
  257. package/dist/providers/none.d.ts +61 -0
  258. package/dist/providers/none.d.ts.map +1 -0
  259. package/dist/providers/none.js +124 -0
  260. package/dist/providers/none.js.map +1 -0
  261. package/dist/providers/opencode.d.ts +14 -2
  262. package/dist/providers/opencode.d.ts.map +1 -1
  263. package/dist/providers/opencode.js +104 -4
  264. package/dist/providers/opencode.js.map +1 -1
  265. package/dist/providers/provider.d.ts +156 -1
  266. package/dist/providers/provider.d.ts.map +1 -1
  267. package/dist/providers/provider.js +54 -0
  268. package/dist/providers/provider.js.map +1 -1
  269. package/dist/services/agent-provisioner.d.ts +3 -3
  270. package/dist/services/agent-provisioner.d.ts.map +1 -1
  271. package/dist/services/agent-provisioner.js +11 -7
  272. package/dist/services/agent-provisioner.js.map +1 -1
  273. package/dist/services/auth-socket.d.ts.map +1 -1
  274. package/dist/services/auth-socket.js +2 -0
  275. package/dist/services/auth-socket.js.map +1 -1
  276. package/dist/services/budget-awareness.d.ts +130 -0
  277. package/dist/services/budget-awareness.d.ts.map +1 -0
  278. package/dist/services/budget-awareness.js +129 -0
  279. package/dist/services/budget-awareness.js.map +1 -0
  280. package/dist/services/cloud/lifecycle.d.ts.map +1 -1
  281. package/dist/services/cloud/lifecycle.js +3 -0
  282. package/dist/services/cloud/lifecycle.js.map +1 -1
  283. package/dist/services/cloud/task-wrapper.d.ts +18 -0
  284. package/dist/services/cloud/task-wrapper.d.ts.map +1 -1
  285. package/dist/services/cloud/task-wrapper.js +157 -0
  286. package/dist/services/cloud/task-wrapper.js.map +1 -1
  287. package/dist/services/cloud-sync.d.ts +35 -0
  288. package/dist/services/cloud-sync.d.ts.map +1 -0
  289. package/dist/services/cloud-sync.js +90 -0
  290. package/dist/services/cloud-sync.js.map +1 -0
  291. package/dist/services/context-admission.d.ts +82 -0
  292. package/dist/services/context-admission.d.ts.map +1 -0
  293. package/dist/services/context-admission.js +136 -0
  294. package/dist/services/context-admission.js.map +1 -0
  295. package/dist/services/event-bus.d.ts +27 -0
  296. package/dist/services/event-bus.d.ts.map +1 -0
  297. package/dist/services/event-bus.js +20 -0
  298. package/dist/services/event-bus.js.map +1 -0
  299. package/dist/services/file-chunker.d.ts +38 -0
  300. package/dist/services/file-chunker.d.ts.map +1 -0
  301. package/dist/services/file-chunker.js +63 -0
  302. package/dist/services/file-chunker.js.map +1 -0
  303. package/dist/services/file-transfer-relay.d.ts +55 -0
  304. package/dist/services/file-transfer-relay.d.ts.map +1 -0
  305. package/dist/services/file-transfer-relay.js +115 -0
  306. package/dist/services/file-transfer-relay.js.map +1 -0
  307. package/dist/services/github-app.d.ts.map +1 -1
  308. package/dist/services/github-app.js +12 -2
  309. package/dist/services/github-app.js.map +1 -1
  310. package/dist/services/http-transport.d.ts +25 -0
  311. package/dist/services/http-transport.d.ts.map +1 -0
  312. package/dist/services/http-transport.js +371 -0
  313. package/dist/services/http-transport.js.map +1 -0
  314. package/dist/services/hub-client.d.ts +69 -0
  315. package/dist/services/hub-client.d.ts.map +1 -0
  316. package/dist/services/hub-client.js +217 -0
  317. package/dist/services/hub-client.js.map +1 -0
  318. package/dist/services/jwt.d.ts +17 -0
  319. package/dist/services/jwt.d.ts.map +1 -0
  320. package/dist/services/jwt.js +70 -0
  321. package/dist/services/jwt.js.map +1 -0
  322. package/dist/services/knowledge/audn.d.ts +37 -0
  323. package/dist/services/knowledge/audn.d.ts.map +1 -0
  324. package/dist/services/knowledge/audn.js +219 -0
  325. package/dist/services/knowledge/audn.js.map +1 -0
  326. package/dist/services/knowledge/file-hash.d.ts +11 -0
  327. package/dist/services/knowledge/file-hash.d.ts.map +1 -0
  328. package/dist/services/knowledge/file-hash.js +123 -0
  329. package/dist/services/knowledge/file-hash.js.map +1 -0
  330. package/dist/services/knowledge/http-provider.d.ts +46 -0
  331. package/dist/services/knowledge/http-provider.d.ts.map +1 -0
  332. package/dist/services/knowledge/http-provider.js +254 -0
  333. package/dist/services/knowledge/http-provider.js.map +1 -0
  334. package/dist/services/knowledge/kb-providers.d.ts +15 -0
  335. package/dist/services/knowledge/kb-providers.d.ts.map +1 -0
  336. package/dist/services/knowledge/kb-providers.js +92 -0
  337. package/dist/services/knowledge/kb-providers.js.map +1 -0
  338. package/dist/services/knowledge/kb-scope-input.d.ts +5 -0
  339. package/dist/services/knowledge/kb-scope-input.d.ts.map +1 -0
  340. package/dist/services/knowledge/kb-scope-input.js +11 -0
  341. package/dist/services/knowledge/kb-scope-input.js.map +1 -0
  342. package/dist/services/knowledge/kb-service.d.ts +3 -0
  343. package/dist/services/knowledge/kb-service.d.ts.map +1 -0
  344. package/dist/services/knowledge/kb-service.js +2 -0
  345. package/dist/services/knowledge/kb-service.js.map +1 -0
  346. package/dist/services/knowledge/path-validation.d.ts +2 -0
  347. package/dist/services/knowledge/path-validation.d.ts.map +1 -0
  348. package/dist/services/knowledge/path-validation.js +13 -0
  349. package/dist/services/knowledge/path-validation.js.map +1 -0
  350. package/dist/services/knowledge/pre-init.d.ts +14 -0
  351. package/dist/services/knowledge/pre-init.d.ts.map +1 -0
  352. package/dist/services/knowledge/pre-init.js +147 -0
  353. package/dist/services/knowledge/pre-init.js.map +1 -0
  354. package/dist/services/knowledge/project-slug.d.ts +2 -0
  355. package/dist/services/knowledge/project-slug.d.ts.map +1 -0
  356. package/dist/services/knowledge/project-slug.js +49 -0
  357. package/dist/services/knowledge/project-slug.js.map +1 -0
  358. package/dist/services/knowledge/sqlite-provider.d.ts +147 -0
  359. package/dist/services/knowledge/sqlite-provider.d.ts.map +1 -0
  360. package/dist/services/knowledge/sqlite-provider.js +1646 -0
  361. package/dist/services/knowledge/sqlite-provider.js.map +1 -0
  362. package/dist/services/knowledge/types.d.ts +163 -0
  363. package/dist/services/knowledge/types.d.ts.map +1 -0
  364. package/dist/services/knowledge/types.js +9 -0
  365. package/dist/services/knowledge/types.js.map +1 -0
  366. package/dist/services/known-sessions.d.ts +8 -0
  367. package/dist/services/known-sessions.d.ts.map +1 -0
  368. package/dist/services/known-sessions.js +40 -0
  369. package/dist/services/known-sessions.js.map +1 -0
  370. package/dist/services/member-home.d.ts +89 -0
  371. package/dist/services/member-home.d.ts.map +1 -0
  372. package/dist/services/member-home.js +256 -0
  373. package/dist/services/member-home.js.map +1 -0
  374. package/dist/services/member-remote-url.d.ts +34 -0
  375. package/dist/services/member-remote-url.d.ts.map +1 -0
  376. package/dist/services/member-remote-url.js +39 -0
  377. package/dist/services/member-remote-url.js.map +1 -0
  378. package/dist/services/model-pricing.d.ts +36 -0
  379. package/dist/services/model-pricing.d.ts.map +1 -0
  380. package/dist/services/model-pricing.js +108 -0
  381. package/dist/services/model-pricing.js.map +1 -0
  382. package/dist/services/orphan-recovery.d.ts +59 -0
  383. package/dist/services/orphan-recovery.d.ts.map +1 -0
  384. package/dist/services/orphan-recovery.js +122 -0
  385. package/dist/services/orphan-recovery.js.map +1 -0
  386. package/dist/services/pending-responses.d.ts +23 -0
  387. package/dist/services/pending-responses.d.ts.map +1 -0
  388. package/dist/services/pending-responses.js +52 -0
  389. package/dist/services/pending-responses.js.map +1 -0
  390. package/dist/services/preflight-check.d.ts +56 -0
  391. package/dist/services/preflight-check.d.ts.map +1 -0
  392. package/dist/services/preflight-check.js +277 -0
  393. package/dist/services/preflight-check.js.map +1 -0
  394. package/dist/services/registry.d.ts +4 -1
  395. package/dist/services/registry.d.ts.map +1 -1
  396. package/dist/services/registry.js +3 -0
  397. package/dist/services/registry.js.map +1 -1
  398. package/dist/services/relay-context.d.ts +23 -0
  399. package/dist/services/relay-context.d.ts.map +1 -0
  400. package/dist/services/relay-context.js +8 -0
  401. package/dist/services/relay-context.js.map +1 -0
  402. package/dist/services/relay-executor.d.ts +68 -0
  403. package/dist/services/relay-executor.d.ts.map +1 -0
  404. package/dist/services/relay-executor.js +70 -0
  405. package/dist/services/relay-executor.js.map +1 -0
  406. package/dist/services/relay-request.d.ts +65 -0
  407. package/dist/services/relay-request.d.ts.map +1 -0
  408. package/dist/services/relay-request.js +129 -0
  409. package/dist/services/relay-request.js.map +1 -0
  410. package/dist/services/relay-strategy.d.ts +19 -0
  411. package/dist/services/relay-strategy.d.ts.map +1 -0
  412. package/dist/services/relay-strategy.js +111 -0
  413. package/dist/services/relay-strategy.js.map +1 -0
  414. package/dist/services/service-manager/index.d.ts +5 -0
  415. package/dist/services/service-manager/index.d.ts.map +1 -0
  416. package/dist/services/service-manager/index.js +66 -0
  417. package/dist/services/service-manager/index.js.map +1 -0
  418. package/dist/services/service-manager/linux.d.ts +10 -0
  419. package/dist/services/service-manager/linux.d.ts.map +1 -0
  420. package/dist/services/service-manager/linux.js +97 -0
  421. package/dist/services/service-manager/linux.js.map +1 -0
  422. package/dist/services/service-manager/macos.d.ts +10 -0
  423. package/dist/services/service-manager/macos.d.ts.map +1 -0
  424. package/dist/services/service-manager/macos.js +94 -0
  425. package/dist/services/service-manager/macos.js.map +1 -0
  426. package/dist/services/service-manager/types.d.ts +18 -0
  427. package/dist/services/service-manager/types.d.ts.map +1 -0
  428. package/dist/services/service-manager/types.js +5 -0
  429. package/dist/services/service-manager/types.js.map +1 -0
  430. package/dist/services/service-manager/windows.d.ts +10 -0
  431. package/dist/services/service-manager/windows.d.ts.map +1 -0
  432. package/dist/services/service-manager/windows.js +73 -0
  433. package/dist/services/service-manager/windows.js.map +1 -0
  434. package/dist/services/session-registry.d.ts +70 -0
  435. package/dist/services/session-registry.d.ts.map +1 -0
  436. package/dist/services/session-registry.js +91 -0
  437. package/dist/services/session-registry.js.map +1 -0
  438. package/dist/services/singleton.d.ts +15 -0
  439. package/dist/services/singleton.d.ts.map +1 -0
  440. package/dist/services/singleton.js +98 -0
  441. package/dist/services/singleton.js.map +1 -0
  442. package/dist/services/sprint-coordination.d.ts +168 -0
  443. package/dist/services/sprint-coordination.d.ts.map +1 -0
  444. package/dist/services/sprint-coordination.js +564 -0
  445. package/dist/services/sprint-coordination.js.map +1 -0
  446. package/dist/services/ssh.d.ts.map +1 -1
  447. package/dist/services/ssh.js +70 -3
  448. package/dist/services/ssh.js.map +1 -1
  449. package/dist/services/stall/log-path-resolver.d.ts +11 -8
  450. package/dist/services/stall/log-path-resolver.d.ts.map +1 -1
  451. package/dist/services/stall/log-path-resolver.js +17 -33
  452. package/dist/services/stall/log-path-resolver.js.map +1 -1
  453. package/dist/services/stall/stall-detector.d.ts +32 -0
  454. package/dist/services/stall/stall-detector.d.ts.map +1 -1
  455. package/dist/services/stall/stall-detector.js +187 -12
  456. package/dist/services/stall/stall-detector.js.map +1 -1
  457. package/dist/services/stall/stall-poller.d.ts +50 -0
  458. package/dist/services/stall/stall-poller.d.ts.map +1 -1
  459. package/dist/services/stall/stall-poller.js +268 -18
  460. package/dist/services/stall/stall-poller.js.map +1 -1
  461. package/dist/services/strategy.d.ts.map +1 -1
  462. package/dist/services/strategy.js +57 -7
  463. package/dist/services/strategy.js.map +1 -1
  464. package/dist/services/substitution-engine.d.ts +20 -0
  465. package/dist/services/substitution-engine.d.ts.map +1 -0
  466. package/dist/services/substitution-engine.js +92 -0
  467. package/dist/services/substitution-engine.js.map +1 -0
  468. package/dist/services/task-cleanup.d.ts.map +1 -1
  469. package/dist/services/task-cleanup.js +1 -9
  470. package/dist/services/task-cleanup.js.map +1 -1
  471. package/dist/services/token-issuer.d.ts +47 -0
  472. package/dist/services/token-issuer.d.ts.map +1 -0
  473. package/dist/services/token-issuer.js +63 -0
  474. package/dist/services/token-issuer.js.map +1 -0
  475. package/dist/services/tool-registry.d.ts +3 -0
  476. package/dist/services/tool-registry.d.ts.map +1 -0
  477. package/dist/services/tool-registry.js +225 -0
  478. package/dist/services/tool-registry.js.map +1 -0
  479. package/dist/services/user-config.d.ts +14 -0
  480. package/dist/services/user-config.d.ts.map +1 -1
  481. package/dist/services/user-config.js +55 -0
  482. package/dist/services/user-config.js.map +1 -1
  483. package/dist/services/vcs/github.d.ts.map +1 -1
  484. package/dist/services/vcs/github.js +32 -1
  485. package/dist/services/vcs/github.js.map +1 -1
  486. package/dist/services/vcs/types.d.ts +44 -0
  487. package/dist/services/vcs/types.d.ts.map +1 -1
  488. package/dist/services/version-check.d.ts +22 -0
  489. package/dist/services/version-check.d.ts.map +1 -0
  490. package/dist/services/version-check.js +103 -0
  491. package/dist/services/version-check.js.map +1 -0
  492. package/dist/skills/fleet-sprint-cli/SKILL.md +114 -0
  493. package/dist/skills/pm/beads.md +6 -0
  494. package/dist/skills/pm/cost.md +3 -0
  495. package/dist/skills/pm/doer-reviewer-loop.md +3 -0
  496. package/dist/skills/pm/fleet-addendum.md +6 -0
  497. package/dist/skills/pm/index.md +56 -0
  498. package/dist/skills/pm/kb-reconcile.md +132 -0
  499. package/dist/skills/pm/kb-review.md +109 -0
  500. package/dist/tools/check-status.d.ts +47 -0
  501. package/dist/tools/check-status.d.ts.map +1 -1
  502. package/dist/tools/check-status.js +250 -2
  503. package/dist/tools/check-status.js.map +1 -1
  504. package/dist/tools/child-id-allocator.d.ts +45 -0
  505. package/dist/tools/child-id-allocator.d.ts.map +1 -0
  506. package/dist/tools/child-id-allocator.js +62 -0
  507. package/dist/tools/child-id-allocator.js.map +1 -0
  508. package/dist/tools/cloud-control.d.ts +2 -2
  509. package/dist/tools/code-intelligence-codebase-memory.d.ts +11 -0
  510. package/dist/tools/code-intelligence-codebase-memory.d.ts.map +1 -0
  511. package/dist/tools/code-intelligence-codebase-memory.js +270 -0
  512. package/dist/tools/code-intelligence-codebase-memory.js.map +1 -0
  513. package/dist/tools/code-intelligence-freshness.d.ts +2 -0
  514. package/dist/tools/code-intelligence-freshness.d.ts.map +1 -0
  515. package/dist/tools/code-intelligence-freshness.js +26 -0
  516. package/dist/tools/code-intelligence-freshness.js.map +1 -0
  517. package/dist/tools/code-intelligence-gitnexus.d.ts +14 -0
  518. package/dist/tools/code-intelligence-gitnexus.d.ts.map +1 -0
  519. package/dist/tools/code-intelligence-gitnexus.js +475 -0
  520. package/dist/tools/code-intelligence-gitnexus.js.map +1 -0
  521. package/dist/tools/code-intelligence-kb-enrich.d.ts +2 -0
  522. package/dist/tools/code-intelligence-kb-enrich.d.ts.map +1 -0
  523. package/dist/tools/code-intelligence-kb-enrich.js +65 -0
  524. package/dist/tools/code-intelligence-kb-enrich.js.map +1 -0
  525. package/dist/tools/code-intelligence-reindex.d.ts +7 -0
  526. package/dist/tools/code-intelligence-reindex.d.ts.map +1 -0
  527. package/dist/tools/code-intelligence-reindex.js +106 -0
  528. package/dist/tools/code-intelligence-reindex.js.map +1 -0
  529. package/dist/tools/code-intelligence-telemetry.d.ts +5 -0
  530. package/dist/tools/code-intelligence-telemetry.d.ts.map +1 -0
  531. package/dist/tools/code-intelligence-telemetry.js +52 -0
  532. package/dist/tools/code-intelligence-telemetry.js.map +1 -0
  533. package/dist/tools/code-intelligence-tests.d.ts +2 -0
  534. package/dist/tools/code-intelligence-tests.d.ts.map +1 -0
  535. package/dist/tools/code-intelligence-tests.js +24 -0
  536. package/dist/tools/code-intelligence-tests.js.map +1 -0
  537. package/dist/tools/code-intelligence.d.ts +114 -0
  538. package/dist/tools/code-intelligence.d.ts.map +1 -0
  539. package/dist/tools/code-intelligence.js +124 -0
  540. package/dist/tools/code-intelligence.js.map +1 -0
  541. package/dist/tools/compose-permissions.d.ts +38 -4
  542. package/dist/tools/compose-permissions.d.ts.map +1 -1
  543. package/dist/tools/compose-permissions.js +295 -33
  544. package/dist/tools/compose-permissions.js.map +1 -1
  545. package/dist/tools/dolt-push-mutex.d.ts +44 -0
  546. package/dist/tools/dolt-push-mutex.d.ts.map +1 -0
  547. package/dist/tools/dolt-push-mutex.js +83 -0
  548. package/dist/tools/dolt-push-mutex.js.map +1 -0
  549. package/dist/tools/execute-command.d.ts +13 -1
  550. package/dist/tools/execute-command.d.ts.map +1 -1
  551. package/dist/tools/execute-command.js +108 -21
  552. package/dist/tools/execute-command.js.map +1 -1
  553. package/dist/tools/execute-prompt.d.ts +84 -12
  554. package/dist/tools/execute-prompt.d.ts.map +1 -1
  555. package/dist/tools/execute-prompt.js +1191 -88
  556. package/dist/tools/execute-prompt.js.map +1 -1
  557. package/dist/tools/get-member-model-pricing.d.ts +21 -0
  558. package/dist/tools/get-member-model-pricing.d.ts.map +1 -0
  559. package/dist/tools/get-member-model-pricing.js +29 -0
  560. package/dist/tools/get-member-model-pricing.js.map +1 -0
  561. package/dist/tools/kb-capture.d.ts +53 -0
  562. package/dist/tools/kb-capture.d.ts.map +1 -0
  563. package/dist/tools/kb-capture.js +130 -0
  564. package/dist/tools/kb-capture.js.map +1 -0
  565. package/dist/tools/kb-context.d.ts +17 -0
  566. package/dist/tools/kb-context.d.ts.map +1 -0
  567. package/dist/tools/kb-context.js +29 -0
  568. package/dist/tools/kb-context.js.map +1 -0
  569. package/dist/tools/kb-export.d.ts +19 -0
  570. package/dist/tools/kb-export.d.ts.map +1 -0
  571. package/dist/tools/kb-export.js +344 -0
  572. package/dist/tools/kb-export.js.map +1 -0
  573. package/dist/tools/kb-feedback.d.ts +23 -0
  574. package/dist/tools/kb-feedback.d.ts.map +1 -0
  575. package/dist/tools/kb-feedback.js +43 -0
  576. package/dist/tools/kb-feedback.js.map +1 -0
  577. package/dist/tools/kb-freshness-sweep.d.ts +14 -0
  578. package/dist/tools/kb-freshness-sweep.d.ts.map +1 -0
  579. package/dist/tools/kb-freshness-sweep.js +29 -0
  580. package/dist/tools/kb-freshness-sweep.js.map +1 -0
  581. package/dist/tools/kb-harvest.d.ts +20 -0
  582. package/dist/tools/kb-harvest.d.ts.map +1 -0
  583. package/dist/tools/kb-harvest.js +143 -0
  584. package/dist/tools/kb-harvest.js.map +1 -0
  585. package/dist/tools/kb-import.d.ts +44 -0
  586. package/dist/tools/kb-import.d.ts.map +1 -0
  587. package/dist/tools/kb-import.js +239 -0
  588. package/dist/tools/kb-import.js.map +1 -0
  589. package/dist/tools/kb-invalidate.d.ts +19 -0
  590. package/dist/tools/kb-invalidate.d.ts.map +1 -0
  591. package/dist/tools/kb-invalidate.js +34 -0
  592. package/dist/tools/kb-invalidate.js.map +1 -0
  593. package/dist/tools/kb-list.d.ts +32 -0
  594. package/dist/tools/kb-list.d.ts.map +1 -0
  595. package/dist/tools/kb-list.js +43 -0
  596. package/dist/tools/kb-list.js.map +1 -0
  597. package/dist/tools/kb-promote.d.ts +20 -0
  598. package/dist/tools/kb-promote.d.ts.map +1 -0
  599. package/dist/tools/kb-promote.js +20 -0
  600. package/dist/tools/kb-promote.js.map +1 -0
  601. package/dist/tools/kb-query.d.ts +35 -0
  602. package/dist/tools/kb-query.d.ts.map +1 -0
  603. package/dist/tools/kb-query.js +111 -0
  604. package/dist/tools/kb-query.js.map +1 -0
  605. package/dist/tools/kb-reconcile-prefilter.d.ts +14 -0
  606. package/dist/tools/kb-reconcile-prefilter.d.ts.map +1 -0
  607. package/dist/tools/kb-reconcile-prefilter.js +26 -0
  608. package/dist/tools/kb-reconcile-prefilter.js.map +1 -0
  609. package/dist/tools/kb-resolve-contradiction.d.ts +23 -0
  610. package/dist/tools/kb-resolve-contradiction.d.ts.map +1 -0
  611. package/dist/tools/kb-resolve-contradiction.js +37 -0
  612. package/dist/tools/kb-resolve-contradiction.js.map +1 -0
  613. package/dist/tools/kb-session-prime.d.ts +26 -0
  614. package/dist/tools/kb-session-prime.d.ts.map +1 -0
  615. package/dist/tools/kb-session-prime.js +392 -0
  616. package/dist/tools/kb-session-prime.js.map +1 -0
  617. package/dist/tools/kb-setup.d.ts +20 -0
  618. package/dist/tools/kb-setup.d.ts.map +1 -0
  619. package/dist/tools/kb-setup.js +49 -0
  620. package/dist/tools/kb-setup.js.map +1 -0
  621. package/dist/tools/kb-stats.d.ts +20 -0
  622. package/dist/tools/kb-stats.d.ts.map +1 -0
  623. package/dist/tools/kb-stats.js +115 -0
  624. package/dist/tools/kb-stats.js.map +1 -0
  625. package/dist/tools/list-members.d.ts.map +1 -1
  626. package/dist/tools/list-members.js +39 -7
  627. package/dist/tools/list-members.js.map +1 -1
  628. package/dist/tools/member-detail.d.ts +1 -1
  629. package/dist/tools/member-detail.d.ts.map +1 -1
  630. package/dist/tools/member-detail.js +16 -2
  631. package/dist/tools/member-detail.js.map +1 -1
  632. package/dist/tools/member-reservation.d.ts +29 -0
  633. package/dist/tools/member-reservation.d.ts.map +1 -0
  634. package/dist/tools/member-reservation.js +71 -0
  635. package/dist/tools/member-reservation.js.map +1 -0
  636. package/dist/tools/monitor-task.d.ts.map +1 -1
  637. package/dist/tools/monitor-task.js +21 -3
  638. package/dist/tools/monitor-task.js.map +1 -1
  639. package/dist/tools/provision-auth.d.ts.map +1 -1
  640. package/dist/tools/provision-auth.js +10 -3
  641. package/dist/tools/provision-auth.js.map +1 -1
  642. package/dist/tools/provision-vcs-auth.d.ts +7 -7
  643. package/dist/tools/provision-vcs-auth.js +1 -1
  644. package/dist/tools/provision-vcs-auth.js.map +1 -1
  645. package/dist/tools/register-member.d.ts +20 -5
  646. package/dist/tools/register-member.d.ts.map +1 -1
  647. package/dist/tools/register-member.js +174 -6
  648. package/dist/tools/register-member.js.map +1 -1
  649. package/dist/tools/remove-member.d.ts +1 -1
  650. package/dist/tools/remove-member.d.ts.map +1 -1
  651. package/dist/tools/remove-member.js +17 -3
  652. package/dist/tools/remove-member.js.map +1 -1
  653. package/dist/tools/report-status.d.ts +33 -0
  654. package/dist/tools/report-status.d.ts.map +1 -0
  655. package/dist/tools/report-status.js +45 -0
  656. package/dist/tools/report-status.js.map +1 -0
  657. package/dist/tools/respond-to-message.d.ts +21 -0
  658. package/dist/tools/respond-to-message.d.ts.map +1 -0
  659. package/dist/tools/respond-to-message.js +23 -0
  660. package/dist/tools/respond-to-message.js.map +1 -0
  661. package/dist/tools/send-email.d.ts +69 -0
  662. package/dist/tools/send-email.d.ts.map +1 -0
  663. package/dist/tools/send-email.js +177 -0
  664. package/dist/tools/send-email.js.map +1 -0
  665. package/dist/tools/send-files.d.ts +3 -0
  666. package/dist/tools/send-files.d.ts.map +1 -1
  667. package/dist/tools/send-files.js +88 -8
  668. package/dist/tools/send-files.js.map +1 -1
  669. package/dist/tools/send-message.d.ts +27 -0
  670. package/dist/tools/send-message.d.ts.map +1 -0
  671. package/dist/tools/send-message.js +46 -0
  672. package/dist/tools/send-message.js.map +1 -0
  673. package/dist/tools/setup-ssh-key.d.ts.map +1 -1
  674. package/dist/tools/setup-ssh-key.js +2 -0
  675. package/dist/tools/setup-ssh-key.js.map +1 -1
  676. package/dist/tools/shutdown-server.d.ts +2 -0
  677. package/dist/tools/shutdown-server.d.ts.map +1 -1
  678. package/dist/tools/shutdown-server.js +19 -0
  679. package/dist/tools/shutdown-server.js.map +1 -1
  680. package/dist/tools/update-member.d.ts +11 -8
  681. package/dist/tools/update-member.d.ts.map +1 -1
  682. package/dist/tools/update-member.js +36 -2
  683. package/dist/tools/update-member.js.map +1 -1
  684. package/dist/types.d.ts +16 -3
  685. package/dist/types.d.ts.map +1 -1
  686. package/dist/utils/agent-helpers.d.ts +2 -1
  687. package/dist/utils/agent-helpers.d.ts.map +1 -1
  688. package/dist/utils/agent-helpers.js +7 -2
  689. package/dist/utils/agent-helpers.js.map +1 -1
  690. package/dist/utils/pid-helpers.d.ts +15 -0
  691. package/dist/utils/pid-helpers.d.ts.map +1 -1
  692. package/dist/utils/pid-helpers.js +23 -0
  693. package/dist/utils/pid-helpers.js.map +1 -1
  694. package/dist/utils/process-utils.d.ts +3 -0
  695. package/dist/utils/process-utils.d.ts.map +1 -0
  696. package/dist/utils/process-utils.js +42 -0
  697. package/dist/utils/process-utils.js.map +1 -0
  698. package/dist/utils/prompt-errors.d.ts +2 -1
  699. package/dist/utils/prompt-errors.d.ts.map +1 -1
  700. package/dist/utils/prompt-errors.js +13 -3
  701. package/dist/utils/prompt-errors.js.map +1 -1
  702. package/dist/utils/session-caller.d.ts +28 -0
  703. package/dist/utils/session-caller.d.ts.map +1 -0
  704. package/dist/utils/session-caller.js +24 -0
  705. package/dist/utils/session-caller.js.map +1 -0
  706. package/dist/utils/work-folder-validation.d.ts +39 -0
  707. package/dist/utils/work-folder-validation.d.ts.map +1 -0
  708. package/dist/utils/work-folder-validation.js +60 -0
  709. package/dist/utils/work-folder-validation.js.map +1 -0
  710. package/dist/utils/workspace-trust.d.ts +24 -0
  711. package/dist/utils/workspace-trust.d.ts.map +1 -0
  712. package/dist/utils/workspace-trust.js +35 -0
  713. package/dist/utils/workspace-trust.js.map +1 -0
  714. package/dist/workflows/auto-sprint.js +994 -91
  715. package/package.json +40 -9
  716. package/packages/apra-fleet-client/package.json +26 -0
  717. package/packages/apra-fleet-client/src/client/api.mjs +510 -0
  718. package/packages/apra-fleet-client/src/client/client.mjs +146 -0
  719. package/packages/apra-fleet-client/src/client/errors.mjs +71 -0
  720. package/packages/apra-fleet-client/src/client/factory.mjs +65 -0
  721. package/packages/apra-fleet-client/src/client/server-resolution.mjs +265 -0
  722. package/packages/apra-fleet-client/src/client/transport.mjs +327 -0
  723. package/packages/apra-fleet-se/apra-pm/agents/backlog-groomer.md +303 -0
  724. package/packages/apra-fleet-se/apra-pm/agents/ci-watcher.md +101 -0
  725. package/packages/apra-fleet-se/apra-pm/agents/deployer.md +151 -0
  726. package/packages/apra-fleet-se/apra-pm/agents/doer.md +259 -0
  727. package/packages/apra-fleet-se/apra-pm/agents/harvester.md +188 -0
  728. package/packages/apra-fleet-se/apra-pm/agents/integ-test-runner.md +332 -0
  729. package/packages/apra-fleet-se/apra-pm/agents/kb-reconciler.md +216 -0
  730. package/packages/apra-fleet-se/apra-pm/agents/plan-reviewer.md +201 -0
  731. package/packages/apra-fleet-se/apra-pm/agents/planner.md +322 -0
  732. package/packages/apra-fleet-se/apra-pm/agents/regression-test-runner.md +234 -0
  733. package/packages/apra-fleet-se/apra-pm/agents/reviewer.md +275 -0
  734. package/packages/apra-fleet-se/apra-pm/agents/schemas/backlog-groomer-input.json +35 -0
  735. package/packages/apra-fleet-se/apra-pm/agents/schemas/backlog-groomer-output.json +164 -0
  736. package/packages/apra-fleet-se/apra-pm/agents/schemas/ci-watcher-input.json +26 -0
  737. package/packages/apra-fleet-se/apra-pm/agents/schemas/ci-watcher-output.json +18 -0
  738. package/packages/apra-fleet-se/apra-pm/agents/schemas/deployer-input.json +19 -0
  739. package/packages/apra-fleet-se/apra-pm/agents/schemas/deployer-output.json +17 -0
  740. package/packages/apra-fleet-se/apra-pm/agents/schemas/doer-input.json +25 -0
  741. package/packages/apra-fleet-se/apra-pm/agents/schemas/doer-output.json +82 -0
  742. package/packages/apra-fleet-se/apra-pm/agents/schemas/harvester-input.json +31 -0
  743. package/packages/apra-fleet-se/apra-pm/agents/schemas/harvester-output.json +75 -0
  744. package/packages/apra-fleet-se/apra-pm/agents/schemas/integ-test-runner-input.json +20 -0
  745. package/packages/apra-fleet-se/apra-pm/agents/schemas/integ-test-runner-output.json +61 -0
  746. package/packages/apra-fleet-se/apra-pm/agents/schemas/kb-reconciler-output.json +87 -0
  747. package/packages/apra-fleet-se/apra-pm/agents/schemas/plan-reviewer-input.json +15 -0
  748. package/packages/apra-fleet-se/apra-pm/agents/schemas/plan-reviewer-output.json +30 -0
  749. package/packages/apra-fleet-se/apra-pm/agents/schemas/planner-output.json +65 -0
  750. package/packages/apra-fleet-se/apra-pm/agents/schemas/regression-test-runner-input.json +15 -0
  751. package/packages/apra-fleet-se/apra-pm/agents/schemas/regression-test-runner-output.json +50 -0
  752. package/packages/apra-fleet-se/apra-pm/agents/schemas/reviewer-input.json +25 -0
  753. package/packages/apra-fleet-se/apra-pm/agents/schemas/reviewer-output.json +135 -0
  754. package/packages/apra-fleet-se/apra-pm/skills/pm/SKILL.md +402 -0
  755. package/packages/apra-fleet-se/apra-pm/skills/pm/beads.md +148 -0
  756. package/packages/apra-fleet-se/apra-pm/skills/pm/cost.md +157 -0
  757. package/packages/apra-fleet-se/apra-pm/skills/pm/doer-reviewer-loop.md +300 -0
  758. package/packages/apra-fleet-se/apra-pm/skills/pm/fleet-addendum.md +127 -0
  759. package/packages/apra-fleet-se/apra-pm/skills/pm/index.md +56 -0
  760. package/packages/apra-fleet-se/apra-pm/skills/pm/kb-reconcile.md +132 -0
  761. package/packages/apra-fleet-se/apra-pm/skills/pm/kb-review.md +109 -0
  762. package/packages/apra-fleet-se/apra-pm/skills/pm/simple-sprint.md +65 -0
  763. package/packages/apra-fleet-se/apra-pm/skills/pm/sprint.md +327 -0
  764. package/packages/apra-fleet-se/apra-pm/skills/pm/worktrees.md +92 -0
  765. package/packages/apra-fleet-se/apra-pm/version.json +3 -0
  766. package/packages/apra-fleet-se/bin/cli.mjs +864 -0
  767. package/packages/apra-fleet-se/bin/serve.mjs +395 -0
  768. package/packages/apra-fleet-se/fleet-sprint/conflict-ladder.mjs +178 -0
  769. package/packages/apra-fleet-se/fleet-sprint/contracts.mjs +940 -0
  770. package/packages/apra-fleet-se/fleet-sprint/dispatch-safety-guard.mjs +177 -0
  771. package/packages/apra-fleet-se/fleet-sprint/docs/README.md +191 -0
  772. package/packages/apra-fleet-se/fleet-sprint/docs/coach-role-design.md +23 -0
  773. package/packages/apra-fleet-se/fleet-sprint/docs/dolt-manual-recovery-verified.md +256 -0
  774. package/packages/apra-fleet-se/fleet-sprint/docs/dolt-sync-redesign.md +1482 -0
  775. package/packages/apra-fleet-se/fleet-sprint/docs/escalate-to-llm-design.md +908 -0
  776. package/packages/apra-fleet-se/fleet-sprint/docs/fleet-sprint-diagram.md +94 -0
  777. package/packages/apra-fleet-se/fleet-sprint/docs/shared-orchestrator-reservation-design.md +399 -0
  778. package/packages/apra-fleet-se/fleet-sprint/docs/stabilization-log.md +1125 -0
  779. package/packages/apra-fleet-se/fleet-sprint/dolt-literal-guard.mjs +72 -0
  780. package/packages/apra-fleet-se/fleet-sprint/dolt-settle.mjs +972 -0
  781. package/packages/apra-fleet-se/fleet-sprint/dolt-sync.mjs +1310 -0
  782. package/packages/apra-fleet-se/fleet-sprint/errors.mjs +616 -0
  783. package/packages/apra-fleet-se/fleet-sprint/full-db-fetch-guard.mjs +118 -0
  784. package/packages/apra-fleet-se/fleet-sprint/runner.js +10747 -0
  785. package/packages/apra-fleet-se/fleet-sprint/skills/fleet-sprint-cli/SKILL.md +114 -0
  786. package/packages/apra-fleet-se/fleet-sprint/skills/fleet-supervisor/SKILL.md +350 -0
  787. package/packages/apra-fleet-se/fleet-sprint/sprint-lock.mjs +140 -0
  788. package/packages/apra-fleet-se/fleet-sprint/sprint-progress.mjs +101 -0
  789. package/packages/apra-fleet-se/fleet-sprint/vcs-module.mjs +435 -0
  790. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/azure-devops.mjs +68 -0
  791. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/bitbucket.mjs +53 -0
  792. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/dolt.mjs +146 -0
  793. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/generic-git.mjs +176 -0
  794. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/github.mjs +235 -0
  795. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/index.mjs +218 -0
  796. package/packages/apra-fleet-se/fleet-sprint/viewer-extensions.mjs +942 -0
  797. package/packages/apra-fleet-se/package.json +29 -0
  798. package/packages/apra-fleet-se/workflow.json +1 -0
  799. package/packages/apra-fleet-workflow/package.json +30 -0
  800. package/packages/apra-fleet-workflow/src/viewer/command-output-cap.mjs +112 -0
  801. package/packages/apra-fleet-workflow/src/viewer/debounced-writer.mjs +153 -0
  802. package/packages/apra-fleet-workflow/src/viewer/html-utils.mjs +31 -0
  803. package/packages/apra-fleet-workflow/src/viewer/index.mjs +1439 -0
  804. package/packages/apra-fleet-workflow/src/viewer/lean-state.mjs +237 -0
  805. package/packages/apra-fleet-workflow/src/viewer/run-state-paths.mjs +130 -0
  806. package/packages/apra-fleet-workflow/src/viewer/run-title.mjs +60 -0
  807. package/packages/apra-fleet-workflow/src/viewer/sprint-state-paths.mjs +29 -0
  808. package/packages/apra-fleet-workflow/src/workflow/engine.mjs +200 -0
  809. package/packages/apra-fleet-workflow/src/workflow/errors.mjs +146 -0
  810. package/packages/apra-fleet-workflow/src/workflow/index.mjs +1727 -0
  811. package/packages/apra-fleet-workflow/src/workflow/journal.mjs +291 -0
  812. package/packages/apra-fleet-workflow/src/workflow/pricing.mjs +99 -0
  813. package/packages/apra-fleet-workflow/src/workflow/vetting.mjs +111 -0
  814. package/scripts/agy-transcript-reader.js +1 -0
  815. package/scripts/fleet-statusline.sh +17 -13
  816. package/skills/fleet/SKILL.md +37 -2
  817. package/skills/fleet/beads.md +14 -7
  818. package/skills/fleet/knowledge-agent.md +66 -0
  819. package/skills/fleet/permissions.md +76 -2
  820. package/skills/fleet/profiles/base-dev.json +11 -1
  821. package/skills/fleet/profiles/base-reviewer.json +9 -1
  822. package/skills/fleet/profiles/node.json +2 -2
  823. package/skills/fleet/profiles/tag-kb-reconciler.json +20 -0
  824. package/version.json +1 -1
  825. package/scripts/agy-settings-merge.js +0 -27
  826. /package/{dist → packages/apra-fleet-se/apra-pm}/agents/_shared/GRAPH-SEMANTICS.md +0 -0
@@ -0,0 +1,1310 @@
1
+ /**
2
+ * DoltSync -- the SINGLE permitted dolt command surface for fleet-sprint.
3
+ *
4
+ * SCOPE / INVARIANT (apra-fleet-417.2, apra-fleet-417.2.1)
5
+ * -------------------------------------------------------
6
+ * Every `bd dolt pull` / `bd dolt push` this orchestrator ever issues, and
7
+ * every dolt merge-conflict decision it ever takes, MUST go through this
8
+ * module. No other file -- runner.js included -- may spawn a `bd dolt ...`
9
+ * command directly, and no other file may re-implement classification, retry,
10
+ * gating, or conflict handling for one. runner.js keeps only purpose-level
11
+ * calls (syncBefore / syncAfter / status); the mechanics live here.
12
+ *
13
+ * WHY: before this module the same bracket logic was inlined in runner.js and
14
+ * reached from ~12 call sites, so a fix to retry/gating/conflict behavior had
15
+ * to be replayed at each of them and drifted in practice. One module with one
16
+ * documented entry point per PURPOSE (not per command) makes that impossible.
17
+ *
18
+ * PUBLIC API (the only supported entry points -- see the bottom of this file)
19
+ * --------------------------------------------------------------------------
20
+ * syncBefore(member, opts) -- freshen `member`'s beads clone before it is
21
+ * read from or dispatched (D-pull bracket).
22
+ * `opts.readinessGate: true` (apra-fleet-417.5
23
+ * rename of `healthGate`, ADR Decision 2)
24
+ * selects the pre-flight beads-health variant,
25
+ * which additionally composes the actionable
26
+ * "beads DB diverged" diagnosis line.
27
+ * syncAfter(member, opts) -- publish `member`'s beads mutations (D-push
28
+ * bracket, mutex-serialized, with the single
29
+ * bounded first-successful-pusher-wins
30
+ * reconcile).
31
+ * status(member, opts) -- read-only probe: is this clone actually wired
32
+ * to a shared beads remote? Issues no dolt
33
+ * command and never throws.
34
+ *
35
+ * FAULT-TOLERANCE POLICY (apra-fleet-417.3.1): syncBefore/syncAfter return a
36
+ * STRUCTURED OUTCOME `{ ok, kind, degraded, degradedKind, detail, ... }` and
37
+ * are DEGRADED BY DEFAULT -- an unresolved sync failure does not throw, it
38
+ * reports `degraded: true` (with `degradedKind` carrying the ADR's
39
+ * backend-neutral failure taxonomy, apra-fleet-417.5) and lets the sprint
40
+ * continue. A call site that must still hard-abort says so explicitly with
41
+ * `fatal: true` (and `readinessGate: true` implies it). See the "Structured
42
+ * outcomes and the bounded DEGRADED-BUT-NON-FATAL path" section near the
43
+ * bottom of this file.
44
+ *
45
+ * The lower-level primitives (doltPullBefore / preflightBeadsHealthGate /
46
+ * doltPushAfter / classifyDoltFailure / extract*) stay exported because the
47
+ * unit suites drive them directly and 417.2.2 migrates call sites onto the
48
+ * purpose-based API incrementally; they are IMPLEMENTATION DETAIL of the three
49
+ * entry points above, not a second supported surface.
50
+ *
51
+ * CONFLICT-RECOVERY DISPOSITION (docs/dolt-sync-redesign.md Parts 2.2/2.4)
52
+ * -------------------------------------------------------------------------
53
+ * The old 3-tier ladder (dolt-recovery.mjs Path A, dolt-recovery-path-b.mjs
54
+ * Path B, dolt-recovery-tier2.mjs Tier 2 + docs/dolt-tier2-runbook.md) is
55
+ * RETIRED, not merely rewired. In production it could never resolve anything:
56
+ * Path A threw its precondition guard on every invocation (no sql runtime was
57
+ * ever injected at its call site), Path B was hard-disabled for a correct
58
+ * reason, and Tier 2 only DISPATCHED an LLM -- it never verified, so
59
+ * recoverDoltConflict() returned `ok: false` by construction, 100% of the
60
+ * time. Worse, its teardown was an instruction step an agent could abandon
61
+ * mid-procedure (apra-fleet-5mqg).
62
+ *
63
+ * It is replaced by ONE deterministic function: settleDoltConflicts()
64
+ * (fleet-sprint/dolt-settle.mjs), total over every row-level conflict shape
65
+ * this data model can produce -- no gates, no allowlist, no escalation, no
66
+ * LLM -- with a real `finally` teardown. This module holds it as
67
+ * `opts.settle`: a zero-argument callback (buildSettleCallback(), same file)
68
+ * that RESOLVES on a verified recovery, because settle itself republishes and
69
+ * verifies before returning.
70
+ *
71
+ * Where it is wired -- BOTH divergence terminals, not just the push side:
72
+ * - doltPushAfter()'s terminal, where a divergence outlives the bounded
73
+ * first-successful-pusher-wins reconcile (where the ladder used to sit).
74
+ * - doltPullBefore()'s diverged terminal, which had NO recovery at all: a
75
+ * clone wedged by an earlier failed reconcile used to hard-abort the next
76
+ * sprint at the readiness gate (preflightBeadsHealthGate delegates here,
77
+ * so it inherits the same self-heal).
78
+ * - repair(), the operator/tool entry point -- same one implementation.
79
+ *
80
+ * Kept unchanged on purpose: with NO `settle` callback wired, both brackets
81
+ * behave exactly as before (the typed error propagates immediately), so the
82
+ * degraded-by-default path (apra-fleet-417.3.1) and every existing call site
83
+ * keep their prior semantics.
84
+ *
85
+ * ASCII only.
86
+ */
87
+
88
+ import { DoltDivergedError, DoltSyncError } from './errors.mjs';
89
+ import { classifyFailure, toDoltVerdict } from './vcs-module.mjs';
90
+ import { buildSettleCallback } from './dolt-settle.mjs';
91
+
92
+ // ---------------------------------------------------------------------------
93
+ // Dolt sync brackets: D-pull / D-push
94
+ // ---------------------------------------------------------------------------
95
+ //
96
+ // The beads database is a Dolt database that every member syncs through a
97
+ // shared remote, orthogonally to the git code branch. Where the git brackets
98
+ // keep each member's *code checkout* current, these keep each member's *beads
99
+ // clone* current: a D-pull before every dispatch/read that consumes beads
100
+ // state, and a D-push after every step that mutates it.
101
+ //
102
+ // The most divergence-sensitive read in the runner is the orchestrator's
103
+ // post-streak `bd show` verification (verifyDoerStreakClosed): a remote doer
104
+ // closes its beads in ITS OWN clone and D-pushes them, so without an
105
+ // orchestrator-side D-pull immediately before that read the orchestrator reads
106
+ // its own stale (still-open) copy and falsely marks every remote doer streak
107
+ // FAILED.
108
+ //
109
+ // Conflict policy, deliberately NOT per-conflict judgment: D-push is
110
+ // first-successful-pusher-wins. A member whose push is rejected is the loser
111
+ // and reconciles MECHANICALLY -- it D-pulls the winner's state (ours/theirs
112
+ // fixed by which clone is resolving, never a human/LLM decision) then re-pushes
113
+ // exactly once. A divergence that outlives that one bounded reconcile is a hard
114
+ // DoltDivergedError, never retried blindly -- the mirror of the git
115
+ // single-writer stance.
116
+ //
117
+ // Every `bd dolt` command is issued via the injected command() with an explicit
118
+ // member_name -- agents never sync beads themselves; the orchestrator brackets
119
+ // each dispatch. `command` is dependency-injected so unit tests can drive these
120
+ // helpers with a mock command() and no live Dolt server.
121
+
122
+ // apra-fleet-647.1.3.2: the DOLT_*_PATTERNS lists that used to live here
123
+ // (DOLT_NO_REMOTE_PATTERNS, DOLT_EMPTY_REMOTE_PATTERNS,
124
+ // DOLT_REMOTE_UNREACHABLE_PATTERNS, DOLT_AUTH_PATTERNS, DOLT_DIVERGED_PATTERNS,
125
+ // DOLT_TRANSIENT_PATTERNS) are GONE -- classifyDoltFailure() below delegates
126
+ // to VCSModule.classifyFailure(raw, { provider: 'dolt' }), the ONE place VCS
127
+ // stderr is parsed. The 'dolt' provider (./vcs-providers/dolt.mjs) carries
128
+ // every one of those six tables VERBATIM, plus their own precedence (auth
129
+ // checked BEFORE diverged -- see that file's header for the live incident
130
+ // this ordering prevents, apra-fleet-spp), so this is a delegation, not a
131
+ // behavior change.
132
+
133
+ /**
134
+ * Best-effort extraction of the remote URL named in a remote-unreachable
135
+ * `bd dolt` failure, for the named diagnosis message. Returns null when the
136
+ * output carries no recognizable URL.
137
+ *
138
+ * @param {string} output - the raw stderr/stdout of the failed `bd dolt` command
139
+ * @returns {string|null}
140
+ */
141
+ export function extractDoltRemoteUrl(output) {
142
+ const text = String(output == null ? '' : output);
143
+ const quoted = text.match(/the remote: \S+ '([^']+)' could not be accessed/i);
144
+ if (quoted) return quoted[1];
145
+ const scheme = text.match(/(?:file|https?|git\+https?|ssh):\/\/[^\s'"]+/i);
146
+ if (scheme) return scheme[0];
147
+ return null;
148
+ }
149
+
150
+ /**
151
+ * Classify a failed `bd dolt` command's output into the failure classes the
152
+ * Dolt brackets route differently. Thin adapter over
153
+ * VCSModule.classifyFailure(raw, { provider: 'dolt' }) + toDoltVerdict(),
154
+ * mapping the neutral kind taxonomy onto this module's legacy verdict
155
+ * vocabulary with NO verdict change from the deleted pattern-list classifier.
156
+ * The 'dolt' provider's own `precedence` (./vcs-providers/dolt.mjs) preserves
157
+ * this function's documented check order: no-remote, empty-remote,
158
+ * remote-unreachable, THEN auth (before diverged -- apra-fleet-spp /
159
+ * apra-fleet-417.3.1), THEN diverged, THEN transient.
160
+ *
161
+ * @param {string} output - the raw stderr/stdout of the failed `bd dolt` command
162
+ * @returns {'no-remote'|'empty-remote'|'remote-unreachable'|'auth'|'diverged'|'transient'|'unknown'}
163
+ */
164
+ export function classifyDoltFailure(output) {
165
+ return toDoltVerdict(classifyFailure(output, { provider: 'dolt' }).kind);
166
+ }
167
+
168
+ /**
169
+ * Query whether `member`'s bd-level `sync.remote` setting is currently
170
+ * configured.
171
+ *
172
+ * Deliberately independent of Dolt's raw remote wiring and of
173
+ * classifyDoltFailure's stderr pattern matching: a miswired Dolt-level remote
174
+ * can still make a real `bd dolt push` attempt and fail with a credentials
175
+ * error that classifies as 'auth' rather than 'no-remote', even when the
176
+ * bd-level sync.remote for this clone is neutralized and nothing is supposed to
177
+ * be pushed. Consulting the bd-level setting directly closes that gap
178
+ * regardless of what Dolt's own remote list says.
179
+ *
180
+ * Uses `bd config get sync.remote --json` via the injected command() with an
181
+ * explicit member_name, rather than reading config.yaml off disk, because
182
+ * command() is the only member-scoped I/O this runner has -- a member's clone
183
+ * is not assumed to be locally readable.
184
+ *
185
+ * Fails CLOSED: a failed command(), a failSoft error result, or output that
186
+ * cannot be positively parsed as `{ value: '' }` is all treated as CONFIGURED
187
+ * (returns true). "Not configured" is only ever reported on a positively
188
+ * confirmed empty `value` from a clean JSON parse, because a false positive
189
+ * here would silently swallow a genuine D-push failure on a real,
190
+ * actively-synced clone.
191
+ *
192
+ * @param {string} member
193
+ * @param {{ command: Function, log?: Function }} opts
194
+ * @returns {Promise<boolean>}
195
+ */
196
+ export async function isMemberSyncRemoteConfigured(member, opts) {
197
+ const { command, log = () => {} } = opts;
198
+ let res;
199
+ try {
200
+ res = await command('bd config get sync.remote --json', { member_name: member, silent: true, failSoft: true });
201
+ } catch (err) {
202
+ log(`[Dolt] could not query bd-level sync.remote for member '${member}' (fail-safe: treating as configured): ${err.message}`);
203
+ return true;
204
+ }
205
+ if (res && typeof res === 'object' && res.ok === false) {
206
+ log(`[Dolt] 'bd config get sync.remote' failed for member '${member}' (fail-safe: treating as configured): ${res.error}`);
207
+ return true;
208
+ }
209
+ const output = res && typeof res === 'object' ? res.output : res;
210
+ if (!output) {
211
+ // No output to positively parse (e.g. a no-op/unmocked command()):
212
+ // sync.remote cannot be confirmed absent, so do not treat it as
213
+ // neutralized.
214
+ return true;
215
+ }
216
+ try {
217
+ const parsed = JSON.parse(output);
218
+ return !(typeof parsed.value === 'string' && parsed.value.trim().length === 0);
219
+ } catch (err) {
220
+ log(`[Dolt] could not parse 'bd config get sync.remote --json' output for member '${member}' (fail-safe: treating as configured): ${err.message}`);
221
+ return true;
222
+ }
223
+ }
224
+
225
+ // Bounded exponential backoff between TRANSIENT retries (apra-fleet-417.3.1).
226
+ // A network blip, a busy dolt-server or a held row lock is not cleared by an
227
+ // instant re-issue -- the previous code retried with zero delay, which turned
228
+ // the bound into "fail twice as fast". Delay is attempt-indexed and capped, and
229
+ // `sleep` is injectable so unit suites never actually wait.
230
+ const DOLT_BACKOFF_BASE_MS = 500;
231
+ const DOLT_BACKOFF_MAX_MS = 8000;
232
+
233
+ /**
234
+ * Delay before transient retry #`attempt` (1-based): base * 2^(attempt-1),
235
+ * capped at DOLT_BACKOFF_MAX_MS.
236
+ *
237
+ * @param {number} attempt
238
+ * @param {number} [baseMs]
239
+ * @param {number} [maxMs]
240
+ * @returns {number}
241
+ */
242
+ /** How often the push mutex's lease is renewed while this bracket holds it.
243
+ * Well under the supervisor mutex's 60s lease (src/supervisor/dolt-mutex.mjs
244
+ * DEFAULT_LEASE_MS), so a legitimately long hold -- push + reconcile +
245
+ * settle -- never loses mutual exclusion to reclaimExpired(). Design doc
246
+ * Part 3.4. */
247
+ export const DOLT_MUTEX_RENEW_INTERVAL_MS = 20_000;
248
+
249
+ export function doltBackoffDelayMs(attempt, baseMs = DOLT_BACKOFF_BASE_MS, maxMs = DOLT_BACKOFF_MAX_MS) {
250
+ const n = Math.max(1, Number(attempt) || 1);
251
+ return Math.min(maxMs, baseMs * Math.pow(2, n - 1));
252
+ }
253
+
254
+ const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
255
+
256
+ /**
257
+ * Run a single `bd dolt` command via the injected command() with failSoft,
258
+ * retrying ONLY transient failures up to `maxTransientRetries` times, with a
259
+ * bounded exponential backoff between attempts (doltBackoffDelayMs; override
260
+ * the waiter with `sleep` in tests). A diverged (or unknown) failure is
261
+ * returned immediately, never retried.
262
+ *
263
+ * AUTH SELF-HEAL CONTRACT (the optional `onAuthFailure` param, threaded
264
+ * through by every caller below): a DISTINCT, bounded one-shot path, never
265
+ * folded into the `maxTransientRetries` loop. On an 'auth' classification (see
266
+ * classifyDoltFailure), `onAuthFailure` is called at most ONCE, and if it
267
+ * resolves without throwing the same `bd dolt` command is retried exactly once
268
+ * more. If `onAuthFailure` throws, or is omitted, the failed result is
269
+ * returned to the caller as-is.
270
+ *
271
+ * apra-fleet-647.1.3.3: an 'unknown' classification gets this SAME bounded
272
+ * one-shot self-heal + single retry, rather than failing immediately -- an
273
+ * unrecognized provider failure text is more likely a stale credential than a
274
+ * truly fatal condition, so it is worth exactly one bounded self-heal attempt
275
+ * before giving up. It shares the single `authHealAttempted` latch with the
276
+ * 'auth' path, so self-heal still fires AT MOST ONCE per runDoltStep call. A
277
+ * 'diverged' classification remains excluded and is still returned
278
+ * immediately, never retried.
279
+ *
280
+ * @returns {Promise<{ ok: boolean, output: string, error: string|null, kind?: 'no-remote'|'empty-remote'|'remote-unreachable'|'diverged'|'auth'|'transient'|'unknown' }>}
281
+ */
282
+ async function runDoltStep({ command, member, cmd, label, log, maxTransientRetries, onAuthFailure, sleep = defaultSleep, backoffBaseMs = DOLT_BACKOFF_BASE_MS }) {
283
+ let attempt = 0;
284
+ let authHealAttempted = false;
285
+ // eslint-disable-next-line no-constant-condition
286
+ while (true) {
287
+ const res = await command(cmd, { member_name: member, silent: true, failSoft: true, label });
288
+ if (res && res.ok) return res;
289
+ const error = res ? res.error : 'unknown command failure';
290
+ const kind = classifyDoltFailure(error);
291
+ if (kind === 'transient' && attempt < maxTransientRetries) {
292
+ attempt += 1;
293
+ const delayMs = doltBackoffDelayMs(attempt, backoffBaseMs);
294
+ log(`[Dolt] transient failure for member '${member}' (${label}); retry ${attempt}/${maxTransientRetries} after ${delayMs}ms backoff: ${error}`);
295
+ if (delayMs > 0 && typeof sleep === 'function') await sleep(delayMs);
296
+ continue;
297
+ }
298
+ if ((kind === 'auth' || kind === 'unknown') && typeof onAuthFailure === 'function' && !authHealAttempted) {
299
+ authHealAttempted = true;
300
+ log(`[Dolt] ${kind} failure for member '${member}' (${label}); invoking self-heal (provision_vcs_auth) once before a single bounded retry: ${error}`);
301
+ try {
302
+ await onAuthFailure({ member, label, cmd, error, kind: 'dolt' });
303
+ } catch (healErr) {
304
+ log(`[Dolt] self-heal for member '${member}' (${label}) failed; not retrying further: ${healErr.message}`);
305
+ return { ok: false, output: res ? res.output : '', error, kind };
306
+ }
307
+ log(`[Dolt] self-heal for member '${member}' (${label}) completed; retrying the failed dolt command once.`);
308
+ continue;
309
+ }
310
+ return { ok: false, output: res ? res.output : '', error, kind };
311
+ }
312
+ }
313
+
314
+ /**
315
+ * D-pull: bring `member`'s beads clone up to the shared remote before it reads
316
+ * or is dispatched -- `bd dolt pull`. Transient (network / server / lock)
317
+ * failures are retried up to `maxTransientRetries`; a divergence (a conflict
318
+ * that a plain pull cannot fast-forward) is a distinct typed
319
+ * DoltDivergedError, never retried blindly. Every command is issued via the
320
+ * injected command() with an explicit member_name.
321
+ *
322
+ * The pull is PRE-GATED on the member's own bd-level `sync.remote`: a clone
323
+ * whose sync.remote is positively confirmed absent issues no `bd dolt`
324
+ * command at all, because bd auto-provisions a Dolt-level remote from git's
325
+ * own origin as a side effect of any `bd dolt` invocation that needs one --
326
+ * an ungated pull would therefore re-arm a remote a sandbox had deliberately
327
+ * neutralized. The gate fails CLOSED (isMemberSyncRemoteConfigured reports
328
+ * "not configured" only on a positively-confirmed empty value; any
329
+ * inconclusive read lets the pull proceed), so a real, actively-synced clone
330
+ * is never suppressed. Override the check with
331
+ * `opts.checkSyncRemoteConfigured` (same test hook doltPushAfter exposes).
332
+ *
333
+ * Two distinct benign no-op skips return `{ ok: true, skipped: true }` rather
334
+ * than throwing: `reason: 'no-remote'` (no dolt remote configured -- nothing
335
+ * to pull) and `reason: 'empty-remote'` (a configured remote that has never
336
+ * had anything pushed into it, i.e. Dolt's "no branches found in remote"
337
+ * Error 1105 -- nothing to reconcile). `skipPull: true` skips the actual `bd
338
+ * dolt pull` spawn while still running the sync.remote pre-gate probe, and
339
+ * returns `reason: 'already-fresh'`; callers may only set it where the
340
+ * clone's freshness is already established, since it trades a redundant (and,
341
+ * against a slow or unreachable remote, hang-prone) pull for that assumption.
342
+ *
343
+ * `onAuthFailure` is threaded through to runDoltStep -- see its AUTH SELF-HEAL
344
+ * CONTRACT.
345
+ *
346
+ * @param {string} member
347
+ * @param {{ command: Function, log?: Function, maxTransientRetries?: number, checkSyncRemoteConfigured?: Function, skipPull?: boolean, onAuthFailure?: Function }} opts
348
+ * @returns {Promise<{ ok: true, member: string, skipped?: true, reason?: 'no-remote'|'empty-remote'|'already-fresh' }>}
349
+ */
350
+ /**
351
+ * Invoke the injected settle callback at a divergence terminal, if one is
352
+ * wired. Returns the settle result on a verified recovery, or null when there
353
+ * is no callback / settle itself failed -- in which case the caller surfaces
354
+ * its typed error exactly as it did before settle existed.
355
+ *
356
+ * A settle failure is an OPERATIONAL failure (no usable dolt binary, server
357
+ * would not start, a SQL statement errored), never "this conflict is
358
+ * unresolvable" -- there is no such outcome. It is logged and folded into the
359
+ * existing divergence terminal rather than being escalated anywhere.
360
+ *
361
+ * @param {{ settle?: Function, member: string, operation: string, error: Error, log: Function }} ctx
362
+ * @returns {Promise<object|null>}
363
+ */
364
+ async function attemptSettle({ settle, member, operation, error, log }) {
365
+ if (typeof settle !== 'function') return null;
366
+ log(`[Dolt] ${operation} for member '${member}' diverged; running settleDoltConflicts() (deterministic, no escalation) before surfacing BEADS_SYNC_CONFLICT.`);
367
+ let result = null;
368
+ try {
369
+ result = await settle({ operation, error });
370
+ } catch (settleErr) {
371
+ log(`[Dolt] settle itself failed operationally for member '${member}' (treated as unrecovered; this is an infra failure, NOT an unresolvable conflict): ${(settleErr && settleErr.message) || settleErr}`);
372
+ return null;
373
+ }
374
+ if (result && result.ok) {
375
+ const tables = (result.resolvedTables || []).join(', ') || 'none';
376
+ log(`[Dolt] settle RESOLVED the divergence for member '${member}' (tables: ${tables}) and republished; ${operation} reconciled.`);
377
+ for (const warning of result.warnings || []) log(`[Dolt] settle warning for member '${member}': ${warning}`);
378
+ return result;
379
+ }
380
+ log(`[Dolt] settle returned no verified recovery for member '${member}'; surfacing the divergence.`);
381
+ return null;
382
+ }
383
+
384
+ export async function doltPullBefore(member, opts = {}) {
385
+ const { command, log = () => {}, maxTransientRetries = 1, checkSyncRemoteConfigured, skipPull = false, onAuthFailure, sleep, backoffBaseMs, settle } = opts;
386
+ if (typeof command !== 'function') {
387
+ throw new Error("doltPullBefore requires an injected command() in opts");
388
+ }
389
+
390
+ // Gate BEFORE issuing, so a neutralized clone never lets `bd dolt` re-arm
391
+ // a Dolt-level remote as a side effect (see the doc comment above).
392
+ const preGateCheckFn = checkSyncRemoteConfigured || isMemberSyncRemoteConfigured;
393
+ if (!(await preGateCheckFn(member, { command, log }))) {
394
+ log(`[Dolt] D-pull for member '${member}' skipped pre-attempt: bd-level sync.remote neutralized/absent -- no pull command issued`);
395
+ return { ok: true, member, skipped: true, reason: 'no-remote' };
396
+ }
397
+
398
+ // skipPull suppresses only the `bd dolt pull` SPAWN; the pre-gate probe
399
+ // above still runs, so a sync.remote-absent clone issues an identical
400
+ // command sequence with or without this flag.
401
+ if (skipPull) {
402
+ log(`[Dolt] D-pull for member '${member}': skipping the 'bd dolt pull' spawn (beads clone already freshened by the orchestrator's pre-sprint D-pull, nothing mutated since -- first Planner dispatch).`);
403
+ return { ok: true, member, skipped: true, reason: 'already-fresh' };
404
+ }
405
+
406
+ const pull = await runDoltStep({
407
+ command, member, cmd: 'bd dolt pull',
408
+ label: `D-pull for '${member}'`, log, maxTransientRetries, onAuthFailure, sleep, backoffBaseMs,
409
+ });
410
+ if (!pull.ok) {
411
+ if (pull.kind === 'no-remote') {
412
+ log(`[Dolt] D-pull for member '${member}' skipped: no dolt remote configured (nothing to pull)`);
413
+ return { ok: true, member, skipped: true, reason: 'no-remote' };
414
+ }
415
+ if (pull.kind === 'empty-remote') {
416
+ // sync.remote IS configured but has never had anything pushed
417
+ // into it -- nothing to reconcile, so this is a benign no-op, not
418
+ // a divergence. Genuine conflicts still fall through to the
419
+ // DoltDivergedError branch below.
420
+ log(`[Dolt] D-pull for member '${member}' skipped: dolt remote has zero branches (nothing pushed yet, nothing to pull)`);
421
+ return { ok: true, member, skipped: true, reason: 'empty-remote' };
422
+ }
423
+ if (pull.kind === 'diverged') {
424
+ // The pull-side divergence terminal. Before this was wired
425
+ // (docs/dolt-sync-redesign.md Part 2.3), a clone wedged by an
426
+ // earlier failed reconcile had NO recovery seam here at all and
427
+ // hard-aborted the next sprint at its readiness gate.
428
+ const diverged = new DoltDivergedError(
429
+ `[Dolt] D-pull for member '${member}' hit an unmergeable beads conflict and must not be auto-resolved by judgment: ${pull.error}`,
430
+ { member, doltOutput: pull.error, operation: 'pull' },
431
+ );
432
+ const settled = await attemptSettle({ settle, member, operation: 'D-pull', error: diverged, log });
433
+ if (settled) {
434
+ // settle ends with its own `bd dolt pull` + `bd dolt push`, so
435
+ // a resolved settle means this clone is already current --
436
+ // there is nothing left for this bracket to pull.
437
+ return { ok: true, member, recovered: true, settledTables: settled.resolvedTables || [] };
438
+ }
439
+ throw diverged;
440
+ }
441
+ if (pull.kind === 'auth') {
442
+ // apra-fleet-spp: a credential failure is its own class. It is NOT
443
+ // a divergence (nothing conflicted) and must not be described as
444
+ // one; the remedy is re-provisioning this member's VCS auth, which
445
+ // the bounded one-shot onAuthFailure self-heal above already tried.
446
+ throw new DoltSyncError(
447
+ `[Dolt] D-pull for member '${member}' failed on VCS CREDENTIALS, not a data divergence -- re-provision the member's VCS auth (provision_vcs_auth) and retry. Raw: ${pull.error}`,
448
+ { member, doltOutput: pull.error, details: { kind: 'auth', operation: 'pull' } },
449
+ );
450
+ }
451
+ if (pull.kind === 'remote-unreachable') {
452
+ const url = extractDoltRemoteUrl(pull.error);
453
+ throw new DoltSyncError(
454
+ `[Dolt] member '${member}' beads sync remote is unreachable/misconfigured${url ? ` (${url})` : ''} -- the clone's sync.remote points at a path or URL that cannot be opened (e.g. a deleted test sandbox). Repair the member's .beads sync remote before re-running; retrying cannot succeed. Raw: ${pull.error}`,
455
+ { member, doltOutput: pull.error, remoteUrl: url },
456
+ );
457
+ }
458
+ throw new DoltSyncError(
459
+ `[Dolt] D-pull failed for member '${member}': ${pull.error}`,
460
+ { member, doltOutput: pull.error },
461
+ );
462
+ }
463
+
464
+ return { ok: true, member };
465
+ }
466
+
467
+ /**
468
+ * Best-effort extraction of the beads/dolt table name(s) implicated in a
469
+ * diverged `bd dolt pull`'s raw output, for preflightBeadsHealthGate()'s
470
+ * one-line cause. Dolt's conflict text has no single stable grammar (it
471
+ * varies with the conflict kind -- schema vs data, pull vs merge), so this
472
+ * matches several shapes (`table <name>`, `` `<name>` table``, `conflict in
473
+ * <name>`) rather than assuming a canonical format. Never throws; an output
474
+ * with no recognizable table name returns `[]` so the caller can say
475
+ * 'unknown' explicitly rather than silently omit the field.
476
+ *
477
+ * @param {string|null|undefined} doltOutput
478
+ * @returns {string[]}
479
+ */
480
+ export function extractConflictingTables(doltOutput) {
481
+ const text = String(doltOutput == null ? '' : doltOutput);
482
+ const tables = new Set();
483
+ const patterns = [
484
+ /\btables?\s+`?([A-Za-z_][\w.]*)`?/gi,
485
+ /`([A-Za-z_][\w.]*)`\s+table/gi,
486
+ /conflict(?:s|ed)? in\s+`?([A-Za-z_][\w.]*)`?/gi,
487
+ ];
488
+ for (const re of patterns) {
489
+ let m;
490
+ while ((m = re.exec(text)) !== null) {
491
+ tables.add(m[1]);
492
+ }
493
+ }
494
+ return [...tables];
495
+ }
496
+
497
+ /**
498
+ * Pre-flight beads-health gate: the same D-pull probe as doltPullBefore(),
499
+ * run before a sprint issues any mutating git or PR command, so a diverged
500
+ * beads clone aborts the run before setup has changed anything.
501
+ *
502
+ * On divergence it composes and logs a single actionable line matching
503
+ * /beads DB diverged/ naming the workspace path (a best-effort `pwd` probe on
504
+ * `member`, falling back to the member id -- diagnostics must never block the
505
+ * abort or throw a second, different error), the conflicting table(s) from
506
+ * extractConflictingTables() (or 'unknown'), and the remediation text. That
507
+ * composed string becomes the re-thrown DoltDivergedError's `.message`, which
508
+ * the typed-abort handling persists verbatim, so one string reaches both the
509
+ * main log and the dashboard.
510
+ *
511
+ * Any non-divergence outcome (DoltSyncError, or a benign skip) is passed
512
+ * through unchanged -- it already carries doltPullBefore()'s own message.
513
+ *
514
+ * @param {string} member
515
+ * @param {{ command: Function, log?: Function, maxTransientRetries?: number, checkSyncRemoteConfigured?: Function }} opts
516
+ * @returns {Promise<{ ok: true, member: string, skipped?: true, reason?: 'no-remote'|'empty-remote'|'already-fresh' }>}
517
+ */
518
+ export async function preflightBeadsHealthGate(member, opts = {}) {
519
+ const { command, log = () => {} } = opts;
520
+ try {
521
+ return await doltPullBefore(member, opts);
522
+ } catch (err) {
523
+ if (!(err instanceof DoltDivergedError)) {
524
+ throw err;
525
+ }
526
+ let workspace = member;
527
+ try {
528
+ const pwdRes = await command('pwd', {
529
+ member_name: member,
530
+ silent: true,
531
+ failSoft: true,
532
+ label: `Resolve workspace path for member '${member}' (beads-health gate diagnostics)`,
533
+ });
534
+ if (pwdRes && pwdRes.ok && String(pwdRes.output || '').trim()) {
535
+ workspace = String(pwdRes.output).trim();
536
+ }
537
+ } catch (pwdErr) {
538
+ log(`[Beads Health] could not resolve workspace path for member '${member}' (falling back to member id): ${(pwdErr && pwdErr.message) || pwdErr}`);
539
+ }
540
+ const tables = extractConflictingTables(err.doltOutput);
541
+ const tablesText = tables.length > 0 ? tables.join(', ') : 'unknown';
542
+ const cause =
543
+ `[Beads Health] beads DB diverged from the shared Dolt remote (member '${member}', workspace: ${workspace}; ` +
544
+ `conflicting table(s): ${tablesText}) -- local beads DB diverged from remote; resolve or re-init from the ` +
545
+ `shared remote, then relaunch.`;
546
+ log(cause);
547
+ throw new DoltDivergedError(cause, { member, doltOutput: err.doltOutput, operation: err.operation });
548
+ }
549
+ }
550
+
551
+ /**
552
+ * D-push: publish `member`'s committed beads changes to the shared remote
553
+ * after a beads-mutating step -- `bd dolt push` with a mechanical,
554
+ * first-successful-pusher-wins reconcile. If the push is rejected because the
555
+ * remote moved first, do EXACTLY ONE `bd dolt pull` (reconciling ours/theirs
556
+ * by which clone resolves -- never per-conflict judgment) and re-push once; if
557
+ * that is still rejected, raise a typed DoltDivergedError. Transient (network
558
+ * / server / lock) failures are retried up to `maxTransientRetries`; a
559
+ * divergence is never retried beyond the one bounded reconcile.
560
+ *
561
+ * `pushBeads: false` makes this a no-op (a read-only bracket has nothing to
562
+ * publish). Every command is issued via the injected command() with an
563
+ * explicit member_name.
564
+ *
565
+ * The actual push is serialized behind a GLOBAL push mutex because two
566
+ * concurrent dolt pushes can produce row-level conflicts, and a single
567
+ * unresolved conflict wedges an entire clone's sync. `opts.mutex` is a client
568
+ * with acquire()/release(); it is acquired before the first push attempt and
569
+ * released in a `finally` on EVERY terminal path -- success, transient
570
+ * exhaustion, and divergence -- so a failed push can never leak it. A crashed
571
+ * holder is reclaimed by the mutex's own lease expiry, not by this bracket.
572
+ *
573
+ * Two paths return the benign `{ ok: true, pushed: false, reconciled: false,
574
+ * skipped: true, reason: 'no-remote' }` instead of throwing: a 'no-remote'
575
+ * classification, and -- defense in depth -- any non-diverged failure
576
+ * classifyDoltFailure cannot recognize as 'no-remote' from stderr alone (e.g.
577
+ * a credentials error from a mis-wired Dolt-level remote) when `member`'s
578
+ * bd-level sync.remote is itself absent/neutralized, since nothing is
579
+ * supposed to leave such a clone. A clone with an actively configured
580
+ * sync.remote still throws DoltSyncError on that failure. Override the check
581
+ * with `opts.checkSyncRemoteConfigured` (same `(member, {command, log}) =>
582
+ * Promise<boolean>` shape) in tests.
583
+ *
584
+ * `onAuthFailure` is threaded through to every runDoltStep call below
585
+ * (including the reconcile/re-push) -- see runDoltStep's AUTH SELF-HEAL
586
+ * CONTRACT.
587
+ *
588
+ * `opts.settle` is the optional deterministic conflict-settlement callback
589
+ * (buildSettleCallback, dolt-settle.mjs). When present, a divergence that
590
+ * outlives the bounded reconcile runs settle before the DoltDivergedError is
591
+ * surfaced as BEADS_SYNC_CONFLICT; when absent the divergence propagates
592
+ * immediately (pre-settle behavior).
593
+ *
594
+ * @param {string} member
595
+ * @param {{ command: Function, pushBeads?: boolean, log?: Function, maxTransientRetries?: number, mutex?: { acquire: Function, release: Function }, sprintId?: string, checkSyncRemoteConfigured?: Function, onAuthFailure?: Function, settle?: () => Promise<{ ok: boolean, resolvedTables?: string[] }> }} opts
596
+ * @returns {Promise<{ ok: true, member: string, pushed: boolean, reconciled: boolean, skipped?: true, reason?: 'no-remote', recovered?: true, settledTables?: string[] }>}
597
+ */
598
+ export async function doltPushAfter(member, opts = {}) {
599
+ const { command, pushBeads = true, log = () => {}, maxTransientRetries = 1, mutex, sprintId, checkSyncRemoteConfigured, onAuthFailure, sleep, backoffBaseMs, settle, renewIntervalMs = DOLT_MUTEX_RENEW_INTERVAL_MS } = opts;
600
+ if (typeof command !== 'function') {
601
+ throw new Error("doltPushAfter requires an injected command() in opts");
602
+ }
603
+
604
+ if (!pushBeads) {
605
+ return { ok: true, member, pushed: false, reconciled: false };
606
+ }
607
+
608
+ // Gate BEFORE issuing: bd auto-provisions a Dolt-level remote from git's
609
+ // own origin on the push attempt itself, so merely ATTEMPTING the push on
610
+ // a clone with valid credentials can succeed against the real shared
611
+ // remote even though bd-level sync.remote is neutralized. The check fails
612
+ // CLOSED (any inconclusive read reports configured), so it can only ever
613
+ // suppress a push that was already declared must not happen. The
614
+ // failure-path downgrade below stays as defense in depth.
615
+ const preGateCheckFn = checkSyncRemoteConfigured || isMemberSyncRemoteConfigured;
616
+ if (!(await preGateCheckFn(member, { command, log }))) {
617
+ log(`[Dolt] D-push for member '${member}' skipped pre-attempt: bd-level sync.remote neutralized/absent -- no push command issued`);
618
+ return { ok: true, member, pushed: false, reconciled: false, skipped: true, reason: 'no-remote' };
619
+ }
620
+
621
+ // Serialize this push behind the global mutex: acquire (waiting our FIFO
622
+ // turn) before touching the remote; release on every exit.
623
+ //
624
+ // LEASE RENEWAL (docs/dolt-sync-redesign.md Part 3.4): the mutex lease is
625
+ // 60s and reclaimExpired() force-evicts at expiry EVEN IF the holder is
626
+ // alive. This bracket can legitimately outlive that -- a push, a reconcile
627
+ // pull, and now a full settle (ephemeral server spawn + merge + resolve +
628
+ // republish) -- so acquiring once and never renewing silently loses mutual
629
+ // exclusion mid-operation. Renew on an interval well under the lease while
630
+ // we hold it, and stop renewing in the same `finally` that releases.
631
+ let grant = null;
632
+ if (mutex && typeof mutex.acquire === 'function') {
633
+ grant = await mutex.acquire(sprintId || member, { pid: process.pid });
634
+ }
635
+ let renewTimer = null;
636
+ if (grant && mutex && typeof mutex.renew === 'function') {
637
+ renewTimer = setInterval(() => {
638
+ Promise.resolve()
639
+ .then(() => mutex.renew(grant.token))
640
+ .then((renewed) => {
641
+ if (renewed === false) {
642
+ log(`[Dolt] mutex lease renewal for member '${member}' was REFUSED (the lease was already reclaimed) -- another sprint may now hold the push mutex.`);
643
+ }
644
+ })
645
+ .catch((renewErr) => {
646
+ log(`[Dolt] mutex lease renewal for member '${member}' failed (non-fatal; the lease may expire): ${(renewErr && renewErr.message) || renewErr}`);
647
+ });
648
+ }, renewIntervalMs);
649
+ if (typeof renewTimer.unref === 'function') renewTimer.unref();
650
+ }
651
+ try {
652
+ return await doltPushGuarded();
653
+ } finally {
654
+ if (renewTimer) clearInterval(renewTimer);
655
+ if (grant && mutex && typeof mutex.release === 'function') {
656
+ try {
657
+ await mutex.release(grant.token);
658
+ } catch (relErr) {
659
+ log(`[Dolt] mutex release after D-push for member '${member}' failed (non-fatal; lease will expire): ${relErr.message}`);
660
+ }
661
+ }
662
+ }
663
+
664
+ // The push-side divergence terminal. A divergence that outlives the
665
+ // bounded first-successful-pusher-wins reconcile is exactly the
666
+ // wedged-clone failure settleDoltConflicts() exists for. When an
667
+ // `opts.settle` callback is wired (runner.js builds it via
668
+ // buildSettleCallback and threads it through DoltSync.syncAfter), this
669
+ // terminal runs it, and only surfaces the DoltDivergedError (which
670
+ // runner.js classifies as the terminal BEADS_SYNC_CONFLICT) if settle
671
+ // itself failed operationally. Unlike the retired Tier 2, a settle that
672
+ // resolves IS a verified recovery: it republishes and verifies the push
673
+ // before returning. With no settle callback wired the behavior is
674
+ // unchanged: the DoltDivergedError propagates immediately.
675
+ async function surfaceDivergence(divergedError, operation) {
676
+ const settled = await attemptSettle({ settle, member, operation: `D-push (${operation})`, error: divergedError, log });
677
+ if (settled) {
678
+ return { ok: true, member, pushed: true, reconciled: true, recovered: true, settledTables: settled.resolvedTables || [] };
679
+ }
680
+ throw divergedError;
681
+ }
682
+
683
+ async function doltPushGuarded() {
684
+ let push = await runDoltStep({
685
+ command, member, cmd: 'bd dolt push',
686
+ label: `D-push for '${member}'`, log, maxTransientRetries, onAuthFailure, sleep, backoffBaseMs,
687
+ });
688
+ if (push.ok) {
689
+ return { ok: true, member, pushed: true, reconciled: false };
690
+ }
691
+
692
+ if (push.kind === 'no-remote') {
693
+ log(`[Dolt] D-push for member '${member}' skipped: no dolt remote configured (nothing to push)`);
694
+ return { ok: true, member, pushed: false, reconciled: false, skipped: true, reason: 'no-remote' };
695
+ }
696
+
697
+ if (push.kind !== 'diverged') {
698
+ // Transient-exhausted or unknown failure -- not a divergence, so no
699
+ // reconcile. Before surfacing it as fatal, consult the member's OWN
700
+ // bd-level sync.remote, independent of Dolt's raw remote wiring and
701
+ // of classifyDoltFailure's stderr pattern matching (which can
702
+ // misclassify a neutralized-sandbox failure as 'unknown'). An
703
+ // absent sync.remote means nothing is supposed to be pushed from this
704
+ // clone, so the failure is the same benign no-remote skip.
705
+ const checkFn = checkSyncRemoteConfigured || isMemberSyncRemoteConfigured;
706
+ const syncRemoteConfigured = await checkFn(member, { command, log });
707
+ if (!syncRemoteConfigured) {
708
+ log(`[Dolt] D-push for member '${member}' skipped: no dolt remote configured (bd-level sync.remote neutralized/absent; push failure treated as benign: ${push.error})`);
709
+ return { ok: true, member, pushed: false, reconciled: false, skipped: true, reason: 'no-remote' };
710
+ }
711
+ if (push.kind === 'auth') {
712
+ // apra-fleet-spp: the live 2026-08-02 fleet-mac failure. This used
713
+ // to reach the reconcile ladder and end as DoltDivergedError
714
+ // ("still rejected after one reconcile pull"), which was simply
715
+ // false -- nothing had diverged. It is now its own terminal class,
716
+ // reached only after the bounded one-shot auth self-heal above.
717
+ throw new DoltSyncError(
718
+ `[Dolt] D-push for member '${member}' failed on VCS CREDENTIALS, not a data divergence -- re-provision the member's VCS auth (provision_vcs_auth) and retry. Raw: ${push.error}`,
719
+ { member, doltOutput: push.error, details: { kind: 'auth', operation: 'push' } },
720
+ );
721
+ }
722
+ if (push.kind === 'remote-unreachable') {
723
+ const url = extractDoltRemoteUrl(push.error);
724
+ throw new DoltSyncError(
725
+ `[Dolt] member '${member}' beads sync remote is unreachable/misconfigured${url ? ` (${url})` : ''} -- the clone's sync.remote points at a path or URL that cannot be opened (e.g. a deleted test sandbox). Repair the member's .beads sync remote before re-running; retrying cannot succeed. Raw: ${push.error}`,
726
+ { member, doltOutput: push.error, remoteUrl: url },
727
+ );
728
+ }
729
+ throw new DoltSyncError(
730
+ `[Dolt] D-push for member '${member}' failed: ${push.error}`,
731
+ { member, doltOutput: push.error },
732
+ );
733
+ }
734
+
735
+ // Push loser: reconcile MECHANICALLY with EXACTLY ONE D-pull (ours/theirs
736
+ // fixed by which clone resolves -- first-successful-pusher-wins), then one
737
+ // re-push.
738
+ log(`[Dolt] D-push for member '${member}' was rejected (another writer pushed first); reconciling with a single D-pull then one re-push (first-successful-pusher-wins).`);
739
+ const reconcile = await runDoltStep({
740
+ command, member, cmd: 'bd dolt pull',
741
+ label: `D-push reconcile pull for '${member}'`, log, maxTransientRetries, onAuthFailure, sleep, backoffBaseMs,
742
+ });
743
+ if (!reconcile.ok) {
744
+ if (reconcile.kind === 'diverged') {
745
+ return await surfaceDivergence(
746
+ new DoltDivergedError(
747
+ `[Dolt] D-push reconcile pull for member '${member}' hit an unmergeable beads conflict -- must not be retried blindly: ${reconcile.error}`,
748
+ { member, doltOutput: reconcile.error, operation: 'push-reconcile' },
749
+ ),
750
+ 'push-reconcile',
751
+ );
752
+ }
753
+ throw new DoltSyncError(
754
+ `[Dolt] D-push reconcile pull for member '${member}' failed: ${reconcile.error}`,
755
+ { member, doltOutput: reconcile.error },
756
+ );
757
+ }
758
+
759
+ push = await runDoltStep({
760
+ command, member, cmd: 'bd dolt push',
761
+ label: `D-push re-push after reconcile for '${member}'`, log, maxTransientRetries, onAuthFailure, sleep, backoffBaseMs,
762
+ });
763
+ if (push.ok) {
764
+ return { ok: true, member, pushed: true, reconciled: true };
765
+ }
766
+
767
+ if (push.kind === 'auth') {
768
+ // apra-fleet-spp.3: same mislabel class as the first-push/pull paths,
769
+ // just reached via the post-reconcile re-push -- a credential that
770
+ // lapsed mid-reconcile is not a data divergence, so it must not be
771
+ // folded into DoltDivergedError below.
772
+ throw new DoltSyncError(
773
+ `[Dolt] D-push re-push after reconcile for member '${member}' failed on VCS CREDENTIALS, not a data divergence -- re-provision the member's VCS auth (provision_vcs_auth) and retry. Raw: ${push.error}`,
774
+ { member, doltOutput: push.error, details: { kind: 'auth', operation: 'push-reconcile-repush' } },
775
+ );
776
+ }
777
+
778
+ // Still rejected after the one bounded reconcile, and not an auth failure.
779
+ return await surfaceDivergence(
780
+ new DoltDivergedError(
781
+ `[Dolt] D-push for member '${member}' still rejected after one reconcile pull -- refusing to retry further: ${push.error}`,
782
+ { member, doltOutput: push.error, operation: 'push' },
783
+ ),
784
+ 'push',
785
+ );
786
+ } // end doltPushGuarded
787
+ }
788
+
789
+ // ---------------------------------------------------------------------------
790
+ // Structured outcomes and the bounded DEGRADED-BUT-NON-FATAL path
791
+ // (apra-fleet-417.3.1 / apra-fleet-417.3)
792
+ // ---------------------------------------------------------------------------
793
+ //
794
+ // PRODUCT DECISION (417.3, do not relitigate): concurrent multi-agent dolt
795
+ // push/pull is a NORMAL condition, and a beads-sync hiccup must never
796
+ // hard-abort an otherwise healthy sprint. The primitives above still THROW --
797
+ // that is what the fatal call sites and the existing DoltDivergedError /
798
+ // DoltSyncError consumers (terminal-reason resolution, conflict-dump capture,
799
+ // PostDispatchSyncError wrapping) rely on. What changes here is the DEFAULT at
800
+ // the purpose-based entry points: syncBefore()/syncAfter() answer with a
801
+ // STRUCTURED OUTCOME instead of throwing, and a hard abort is now something a
802
+ // call site asks for EXPLICITLY (`fatal: true`), not what it gets by accident.
803
+ //
804
+ // Outcome shape (a superset of the primitives' old return objects, so every
805
+ // existing consumer of `.skipped` / `.reason` / `.pushed` / `.reconciled`
806
+ // keeps working unchanged):
807
+ //
808
+ // { ok, kind, degraded, detail, member, operation, error?, ...legacy fields }
809
+ //
810
+ // ok -- did the sync do what it was asked to do (a benign skip is ok)
811
+ // kind -- 'synced' | 'no-remote' | 'empty-remote' | 'already-fresh'
812
+ // | 'diverged' | 'auth' | 'transient' | 'remote-unreachable'
813
+ // | 'unknown'
814
+ // degraded -- true when the sync FAILED and the sprint is continuing anyway
815
+ // detail -- one human-readable line (the underlying error's message)
816
+ // error -- the underlying typed error, retained for later escalation
817
+ //
818
+ // VISIBILITY: a degraded outcome is never silent. It is logged loudly, passed
819
+ // to the optional `onDegraded` hook (the seam a caller uses to file a flagged
820
+ // follow-up bead), and appended to a module-level record list that
821
+ // getDegradedSyncRecords() exposes so a sprint can report "these syncs did not
822
+ // land". A record for `member` is retired when a later syncAfter() for the same
823
+ // member succeeds -- i.e. the NEXT bracket IS the queued retry; no separate
824
+ // retry timer exists or is wanted.
825
+
826
+ const degradedSyncRecords = [];
827
+
828
+ /**
829
+ * Append a degraded-sync record to the module-level visibility list.
830
+ *
831
+ * @param {{ member: string, operation: string, kind: string, detail: string }} record
832
+ * @returns {object} the stored record (timestamped)
833
+ */
834
+ export function recordDegradedSync(record) {
835
+ const stored = { at: new Date().toISOString(), pendingRetry: true, ...record };
836
+ degradedSyncRecords.push(stored);
837
+ return stored;
838
+ }
839
+
840
+ /**
841
+ * Every degraded sync recorded so far this process, oldest first. Optionally
842
+ * filtered to one member. Returns copies: callers cannot mutate the log.
843
+ *
844
+ * @param {{ member?: string, pendingOnly?: boolean }} [filter]
845
+ * @returns {object[]}
846
+ */
847
+ export function getDegradedSyncRecords(filter = {}) {
848
+ const { member, pendingOnly = false } = filter;
849
+ return degradedSyncRecords
850
+ .filter((r) => (member ? r.member === member : true))
851
+ .filter((r) => (pendingOnly ? r.pendingRetry : true))
852
+ .map((r) => ({ ...r }));
853
+ }
854
+
855
+ /**
856
+ * Retire this member's pending degraded records after a later sync for the
857
+ * same member succeeded (the queued retry landed). With no member, clears the
858
+ * whole list -- test hygiene only.
859
+ *
860
+ * @param {string} [member]
861
+ * @returns {number} how many records were retired
862
+ */
863
+ export function clearDegradedSyncRecords(member) {
864
+ if (member === undefined) {
865
+ const n = degradedSyncRecords.length;
866
+ degradedSyncRecords.length = 0;
867
+ return n;
868
+ }
869
+ let n = 0;
870
+ for (const r of degradedSyncRecords) {
871
+ if (r.member === member && r.pendingRetry) {
872
+ r.pendingRetry = false;
873
+ r.resolvedAt = new Date().toISOString();
874
+ n += 1;
875
+ }
876
+ }
877
+ return n;
878
+ }
879
+
880
+ /**
881
+ * Classify a thrown dolt-sync error into an outcome `kind`. A DoltDivergedError
882
+ * is 'diverged' by construction; anything else is re-derived from its captured
883
+ * raw dolt output, so a credential failure reports 'auth' (never 'diverged') --
884
+ * apra-fleet-spp.
885
+ *
886
+ * @param {Error} err
887
+ * @returns {string}
888
+ */
889
+ export function classifySyncError(err) {
890
+ if (err instanceof DoltDivergedError) return 'diverged';
891
+ const raw = err && err.doltOutput ? err.doltOutput : (err && err.message) || '';
892
+ const kind = classifyDoltFailure(raw);
893
+ return kind === 'unknown' && !(err instanceof DoltSyncError) ? 'error' : kind;
894
+ }
895
+
896
+ // ---------------------------------------------------------------------------
897
+ // Backend-neutral degraded.kind taxonomy (docs/adr-taskdb-backend-neutral-
898
+ // interface.md Decision 2, apra-fleet-417.5)
899
+ // ---------------------------------------------------------------------------
900
+ //
901
+ // The ADR's TaskDBModule contract carries failure classification in a
902
+ // backend-neutral vocabulary: 'transient', 'auth', 'conflict-resolvable',
903
+ // 'conflict-unresolvable', 'store-unreachable', 'no-store',
904
+ // 'coordination-unavailable', 'unknown'. The adapter-level `kind` this module
905
+ // already produces (classifyDoltFailure / classifySyncError) stays exactly as
906
+ // it is -- runner.js and the fault-tolerance/health-gate test suites branch on
907
+ // its Dolt-flavored values ('diverged', 'no-remote', 'remote-unreachable',
908
+ // ...) today, and `degraded` is a hard boolean those same suites assert with
909
+ // `assert.equal(outcome.degraded, true/false)`. Neither can change shape
910
+ // without breaking passing tests, so the neutral taxonomy is exposed as a
911
+ // SIBLING field, `degradedKind`, set only when `degraded: true`, rather than
912
+ // nesting it under `degraded` the way the ADR's prose literally shows.
913
+ //
914
+ // This mapping is the adapter's declaration of "which neutral kind is this
915
+ // Dolt-specific failure an instance of" -- the direct analogue of 647.1's
916
+ // classifyFailure() kind set. A diverged outcome only ever reaches the
917
+ // degraded path after the one bounded reconcile has already failed (see
918
+ // doltPushAfter), so it always maps to 'conflict-unresolvable' here, never
919
+ // 'conflict-resolvable' (that state exists only transiently, mid-reconcile,
920
+ // and is never itself reported as a degraded terminal outcome).
921
+ const NEUTRAL_KIND_MAP = {
922
+ diverged: 'conflict-unresolvable',
923
+ auth: 'auth',
924
+ transient: 'transient',
925
+ 'no-remote': 'no-store',
926
+ 'empty-remote': 'no-store',
927
+ 'remote-unreachable': 'store-unreachable',
928
+ unknown: 'unknown',
929
+ error: 'unknown',
930
+ };
931
+
932
+ /**
933
+ * Map an adapter-flavored outcome `kind` (classifySyncError's return value) to
934
+ * the ADR's backend-neutral failure taxonomy. Unrecognized kinds map to
935
+ * 'unknown' rather than throwing, since this runs on the degraded (already
936
+ * failure) path and must never itself raise.
937
+ *
938
+ * @param {string} kind
939
+ * @returns {'transient'|'auth'|'conflict-resolvable'|'conflict-unresolvable'|'store-unreachable'|'no-store'|'coordination-unavailable'|'unknown'}
940
+ */
941
+ export function toNeutralDegradedKind(kind) {
942
+ return NEUTRAL_KIND_MAP[kind] || 'unknown';
943
+ }
944
+
945
+ /**
946
+ * TaskDBModule capabilities descriptor (ADR Decision 2/3) for the Dolt/beads
947
+ * adapter: declares which neutral degraded.kind values this backend can ever
948
+ * produce, plus the booleans callers use instead of assuming Dolt semantics.
949
+ *
950
+ * `supportsRepair: true` reflects that `repair()` below runs the real
951
+ * deterministic settle (settleDoltConflicts, dolt-settle.mjs) rather than
952
+ * being a named seam only -- see the CONFLICT-RECOVERY DISPOSITION note in
953
+ * this file's header.
954
+ *
955
+ * @returns {{ wholeStatePublish: boolean, supportsRepair: boolean, supportsCoordinationLock: boolean, kinds: string[] }}
956
+ */
957
+ export function capabilities() {
958
+ return {
959
+ wholeStatePublish: true,
960
+ supportsRepair: true,
961
+ supportsCoordinationLock: true,
962
+ kinds: ['transient', 'auth', 'conflict-resolvable', 'conflict-unresolvable', 'store-unreachable', 'no-store', 'unknown'],
963
+ };
964
+ }
965
+
966
+ /**
967
+ * Normalize a primitive's successful return value into the structured outcome.
968
+ *
969
+ * @param {object} result
970
+ * @param {string} member
971
+ * @param {'pull'|'push'} operation
972
+ * @returns {object}
973
+ */
974
+ function successOutcome(result, member, operation) {
975
+ const res = result && typeof result === 'object' ? result : {};
976
+ const kind = res.skipped && res.reason ? res.reason : 'synced';
977
+ return {
978
+ ...res,
979
+ ok: true,
980
+ kind,
981
+ degraded: false,
982
+ detail: res.skipped
983
+ ? `[Dolt] D-${operation} for member '${member}' was a benign no-op (${kind}).`
984
+ : `[Dolt] D-${operation} for member '${member}' completed.`,
985
+ member,
986
+ operation,
987
+ };
988
+ }
989
+
990
+ /**
991
+ * Run one primitive bracket under the degraded-by-default policy.
992
+ *
993
+ * With `fatal: true` the primitive's typed error propagates untouched -- that
994
+ * is how the explicitly-fatal call sites (the pre-flight beads-health gate,
995
+ * the pre-dispatch D-pull, the post-dispatch sync bracket) keep their existing
996
+ * DoltDivergedError / DoltSyncError behavior and their terminal-reason
997
+ * plumbing. Hard abort is now the explicit last resort, not the default.
998
+ *
999
+ * @param {Function} run - () => Promise<object>, the throwing primitive
1000
+ * @param {{ member: string, operation: 'pull'|'push', fatal?: boolean, log?: Function, onDegraded?: Function }} ctx
1001
+ * @returns {Promise<object>} structured outcome
1002
+ */
1003
+ async function runDegradable(run, ctx) {
1004
+ const { member, operation, fatal = false, log = () => {}, onDegraded } = ctx;
1005
+ let result;
1006
+ try {
1007
+ result = await run();
1008
+ } catch (err) {
1009
+ if (fatal) throw err;
1010
+ const kind = classifySyncError(err);
1011
+ const outcome = {
1012
+ ok: false,
1013
+ kind,
1014
+ degraded: true,
1015
+ // Backend-neutral classification (ADR Decision 2, apra-fleet-417.5)
1016
+ // alongside the adapter-flavored `kind` above -- see the
1017
+ // NEUTRAL_KIND_MAP comment for why this is a sibling field rather
1018
+ // than nested under `degraded`.
1019
+ degradedKind: toNeutralDegradedKind(kind),
1020
+ detail: (err && err.message) || String(err),
1021
+ member,
1022
+ operation,
1023
+ error: err,
1024
+ };
1025
+ log(
1026
+ `[Dolt] DEGRADED (non-fatal): D-${operation} for member '${member}' did not land (${kind}). ` +
1027
+ `The sprint CONTINUES -- this member's beads mutations are safe in its local clone and the next ` +
1028
+ `D-${operation} bracket for '${member}' is the queued retry. Cause: ${outcome.detail}`,
1029
+ );
1030
+ const record = recordDegradedSync({ member, operation, kind, detail: outcome.detail });
1031
+ if (typeof onDegraded === 'function') {
1032
+ try {
1033
+ await onDegraded({ ...outcome, record });
1034
+ } catch (hookErr) {
1035
+ log(`[Dolt] degraded-sync onDegraded hook failed for member '${member}' (non-fatal): ${(hookErr && hookErr.message) || hookErr}`);
1036
+ }
1037
+ }
1038
+ return outcome;
1039
+ }
1040
+ const outcome = successOutcome(result, member, operation);
1041
+ // The next successful bracket IS the queued retry: retire this member's
1042
+ // outstanding degraded records once one lands.
1043
+ if (operation === 'push' && outcome.ok) {
1044
+ const retired = clearDegradedSyncRecords(member);
1045
+ if (retired > 0) {
1046
+ log(`[Dolt] D-push for member '${member}' succeeded; retired ${retired} previously degraded sync record(s) for this member.`);
1047
+ }
1048
+ }
1049
+ return outcome;
1050
+ }
1051
+
1052
+ // ---------------------------------------------------------------------------
1053
+ // Public API -- the only supported entry points (see the module header)
1054
+ // ---------------------------------------------------------------------------
1055
+
1056
+ /**
1057
+ * BEFORE bracket. Freshen `member`'s beads clone so whatever happens next --
1058
+ * a dispatch, or an orchestrator-side read of cross-member beads state --
1059
+ * sees the shared remote's current truth rather than a stale local copy.
1060
+ *
1061
+ * `opts.readinessGate: true` (apra-fleet-417.5 rename of `healthGate`, ADR
1062
+ * Decision 2) selects the pre-flight variant used once per run before any
1063
+ * mutating git/PR command: identical probe, but a divergence is re-thrown
1064
+ * with the composed, actionable "beads DB diverged" line (workspace path +
1065
+ * conflicting tables + remediation) that the dashboard persists.
1066
+ *
1067
+ * Returns a STRUCTURED OUTCOME ({ ok, kind, degraded, degradedKind, detail,
1068
+ * ... }) and, by default, does NOT throw: a sync failure the module cannot
1069
+ * resolve is surfaced as `degraded: true` (with `degradedKind` carrying the
1070
+ * ADR's backend-neutral taxonomy) so the sprint loop continues
1071
+ * (apra-fleet-417.3). Pass `fatal: true` to restore the throwing behavior at a
1072
+ * call site that genuinely must abort the run -- `readinessGate: true`
1073
+ * implies `fatal: true`, since that gate exists precisely to stop a run
1074
+ * before it mutates anything.
1075
+ *
1076
+ * `opts.skipRefresh` (apra-fleet-417.5 rename of `skipPull`, ADR Decision 2)
1077
+ * is threaded through to doltPullBefore()'s `skipPull` -- see that function's
1078
+ * doc comment for what it suppresses. The legacy spellings `healthGate` and
1079
+ * `skipPull` are REJECTED (thrown) rather than silently ignored: silently
1080
+ * dropping either into the `...rest` passthrough would leave a stale call
1081
+ * site with `fatal` quietly defaulting to `false`, turning a hard pre-flight
1082
+ * abort into a silent degrade.
1083
+ *
1084
+ * All other opts are passed through unchanged to doltPullBefore():
1085
+ * `command` (required), `log`, `maxTransientRetries`, `onAuthFailure`,
1086
+ * `checkSyncRemoteConfigured`, `sleep`, `backoffBaseMs`.
1087
+ *
1088
+ * @param {string} member
1089
+ * @param {{ command: Function, readinessGate?: boolean, fatal?: boolean, onDegraded?: Function, log?: Function, maxTransientRetries?: number, checkSyncRemoteConfigured?: Function, skipRefresh?: boolean, onAuthFailure?: Function, sleep?: Function, backoffBaseMs?: number }} opts
1090
+ * @returns {Promise<object>} structured outcome
1091
+ * @throws {DoltDivergedError|DoltSyncError} only when `fatal`/`readinessGate` is set
1092
+ */
1093
+ export async function syncBefore(member, opts = {}) {
1094
+ const { readinessGate = false, skipRefresh, fatal, onDegraded, healthGate, skipPull, ...rest } = opts;
1095
+ if (healthGate !== undefined) {
1096
+ throw new Error(
1097
+ "DoltSync.syncBefore: opts.healthGate is retired -- pass opts.readinessGate instead " +
1098
+ "(docs/adr-taskdb-backend-neutral-interface.md Decision 2, apra-fleet-417.5).",
1099
+ );
1100
+ }
1101
+ if (skipPull !== undefined) {
1102
+ throw new Error(
1103
+ "DoltSync.syncBefore: opts.skipPull is retired -- pass opts.skipRefresh instead " +
1104
+ "(docs/adr-taskdb-backend-neutral-interface.md Decision 2, apra-fleet-417.5).",
1105
+ );
1106
+ }
1107
+ const adapterOpts = { ...rest, skipPull: skipRefresh };
1108
+ const run = readinessGate
1109
+ ? () => preflightBeadsHealthGate(member, adapterOpts)
1110
+ : () => doltPullBefore(member, adapterOpts);
1111
+ return runDegradable(run, {
1112
+ member,
1113
+ operation: 'pull',
1114
+ fatal: fatal === undefined ? readinessGate : fatal,
1115
+ log: rest.log,
1116
+ onDegraded,
1117
+ });
1118
+ }
1119
+
1120
+ /**
1121
+ * AFTER bracket. Publish `member`'s committed beads mutations to the shared
1122
+ * remote, serialized behind the global push mutex, with the single bounded
1123
+ * first-successful-pusher-wins reconcile (one D-pull, one re-push).
1124
+ *
1125
+ * `pushBeads: false` makes it an explicit no-op, so a read-only bracket can
1126
+ * call the same entry point unconditionally instead of branching at the call
1127
+ * site. All opts are passed through unchanged to doltPushAfter().
1128
+ *
1129
+ * Returns a STRUCTURED OUTCOME ({ ok, kind, degraded, detail, pushed,
1130
+ * reconciled, ... }) and, by default, does NOT throw. A push that is still
1131
+ * unresolved after the bounded transient retries, the one-shot auth self-heal
1132
+ * and the single reconcile is reported as `degraded: true` and the sprint
1133
+ * CONTINUES: the member's beads mutations are already committed in its local
1134
+ * clone, and the next syncAfter() for that member is the queued retry. Pass
1135
+ * `fatal: true` at a call site that must still hard-abort (the post-dispatch
1136
+ * sync bracket does, so an unreachable close can never be advertised).
1137
+ *
1138
+ * This is the seam settle is wired behind: an `opts.settle` callback is passed
1139
+ * straight through to doltPushAfter(), whose divergence terminal invokes it --
1140
+ * see the CONFLICT-RECOVERY DISPOSITION note in the module header.
1141
+ *
1142
+ * `opts.mutatedItemIds` (ADR Decision 2/3, apra-fleet-417.5) is accepted per
1143
+ * the TaskDBModule contract but INTENTIONALLY NOT CONSUMED by this adapter:
1144
+ * the Dolt/beads backend publishes whole state (`capabilities().
1145
+ * wholeStatePublish === true`), so a later successful push always implicitly
1146
+ * carries any earlier one and a per-item publish ledger keyed on these ids
1147
+ * buys nothing here. A future non-whole-state backend (e.g. the ADR's Jira
1148
+ * walk-through) is the one that must thread `mutatedItemIds` into a real
1149
+ * per-item retry ledger -- this parameter exists on the interface today so
1150
+ * that backend does not need a signature change to land.
1151
+ *
1152
+ * @param {string} member
1153
+ * @param {{ command: Function, pushBeads?: boolean, fatal?: boolean, onDegraded?: Function, log?: Function, maxTransientRetries?: number, mutex?: { acquire: Function, release: Function }, sprintId?: string, checkSyncRemoteConfigured?: Function, onAuthFailure?: Function, sleep?: Function, backoffBaseMs?: number, mutatedItemIds?: string[] }} opts
1154
+ * @returns {Promise<object>} structured outcome
1155
+ * @throws {DoltDivergedError|DoltSyncError} only when `fatal: true` is set
1156
+ */
1157
+ export async function syncAfter(member, opts = {}) {
1158
+ const { fatal = false, onDegraded, mutatedItemIds, ...rest } = opts;
1159
+ void mutatedItemIds; // see doc comment: accepted for interface parity, not consumed by this whole-state-publish adapter
1160
+ return runDegradable(() => doltPushAfter(member, rest), {
1161
+ member,
1162
+ operation: 'push',
1163
+ fatal,
1164
+ log: rest.log,
1165
+ onDegraded,
1166
+ });
1167
+ }
1168
+
1169
+ /**
1170
+ * Read-only status probe: is `member`'s beads clone actually wired to a shared
1171
+ * remote? Issues NO `bd dolt` command (so it can never re-arm a deliberately
1172
+ * neutralized remote as a side effect) and never throws -- an inconclusive
1173
+ * read reports `syncRemoteConfigured: true`, matching the fail-closed stance
1174
+ * of the brackets themselves.
1175
+ *
1176
+ * @param {string} member
1177
+ * @param {{ command: Function, log?: Function, checkSyncRemoteConfigured?: Function }} opts
1178
+ * @returns {Promise<{ member: string, syncRemoteConfigured: boolean }>}
1179
+ */
1180
+ export async function status(member, opts = {}) {
1181
+ const { command, log = () => {}, checkSyncRemoteConfigured } = opts;
1182
+ if (typeof command !== 'function') {
1183
+ throw new Error('DoltSync.status requires an injected command() in opts');
1184
+ }
1185
+ const checkFn = checkSyncRemoteConfigured || isMemberSyncRemoteConfigured;
1186
+ return { member, syncRemoteConfigured: await checkFn(member, { command, log }) };
1187
+ }
1188
+
1189
+ // ---------------------------------------------------------------------------
1190
+ // TaskDBModule contract completion (docs/adr-taskdb-backend-neutral-
1191
+ // interface.md Decision 2, apra-fleet-417.5): refreshView / ensureReady /
1192
+ // flush / repair, each delegating to the machinery above rather than
1193
+ // introducing new dolt call sites -- this module remains the SINGLE permitted
1194
+ // dolt command surface (see the module header).
1195
+ // ---------------------------------------------------------------------------
1196
+
1197
+ /**
1198
+ * Make `member`'s local view current before the orchestrator reads task
1199
+ * state. Delegates to the same D-pull bracket syncBefore() uses, non-fatal by
1200
+ * default (a stale-but-present view is reported via `fresh: false`, not
1201
+ * thrown) -- ADR Decision 2: "Never throws; fresh:false means reads are
1202
+ * possibly stale, so callers treat verification as INCONCLUSIVE rather than
1203
+ * failed."
1204
+ *
1205
+ * `opts.purpose` is accepted for interface parity (a future backend may use
1206
+ * it to decide whether a cache invalidation is warranted) but this adapter's
1207
+ * refresh is unconditional, so it is not otherwise consulted.
1208
+ *
1209
+ * @param {string} member
1210
+ * @param {{ command: Function, purpose?: string, fatal?: boolean, log?: Function, [key: string]: any }} opts
1211
+ * @returns {Promise<{ fresh: boolean, degraded?: object }>}
1212
+ */
1213
+ export async function refreshView(member, opts = {}) {
1214
+ const { purpose, fatal = false, ...rest } = opts;
1215
+ void purpose; // interface parity only -- see doc comment
1216
+ const outcome = await syncBefore(member, { ...rest, fatal });
1217
+ return outcome.degraded ? { fresh: false, degraded: outcome } : { fresh: outcome.ok };
1218
+ }
1219
+
1220
+ /**
1221
+ * Sprint-start gate: bring `member`'s local view of the task store into a
1222
+ * usable state before any work is dispatched. The one method permitted to
1223
+ * refuse to start -- delegates to syncBefore's `readinessGate` (pre-flight
1224
+ * beads-health) variant, which is fatal by default, so a genuinely unusable
1225
+ * store still aborts the run rather than reporting `ready: false` and
1226
+ * continuing.
1227
+ *
1228
+ * @param {string} member
1229
+ * @param {{ command: Function, fatal?: boolean, log?: Function, [key: string]: any }} opts
1230
+ * @returns {Promise<{ ready: boolean, degraded?: object }>}
1231
+ */
1232
+ export async function ensureReady(member, opts = {}) {
1233
+ const outcome = await syncBefore(member, { ...opts, readinessGate: true });
1234
+ return outcome.degraded ? { ready: false, degraded: outcome } : { ready: outcome.ok };
1235
+ }
1236
+
1237
+ /**
1238
+ * End-of-run: report the degradation ledger a terminal summary is built from.
1239
+ *
1240
+ * This adapter does not attempt a fresh publish here -- the ADR's "attempt
1241
+ * publication for every view still marked unpublished" is already satisfied
1242
+ * incrementally by this adapter's own retry contract: the NEXT syncAfter()
1243
+ * bracket for a given member IS its queued retry (see the module-level
1244
+ * "Structured outcomes" section above), and getDegradedSyncRecords() already
1245
+ * retires a member's records the moment one of those retries lands. flush()
1246
+ * is therefore a read of that ledger, not a second retry mechanism.
1247
+ *
1248
+ * @param {{ member?: string }} [filter]
1249
+ * @returns {{ published: boolean, degradations: object[] }}
1250
+ */
1251
+ export function flush(filter = {}) {
1252
+ const degradations = getDegradedSyncRecords({ ...filter, pendingOnly: true });
1253
+ return { published: degradations.length === 0, degradations };
1254
+ }
1255
+
1256
+ /**
1257
+ * Explicit remediation entry point (ADR Decision 2): "recovery ladder plus
1258
+ * credential re-provisioning. Called by operators/tools and by ensureReady();
1259
+ * never inline from a per-operation sync path."
1260
+ *
1261
+ * WIRED: runs the real deterministic settle (settleDoltConflicts,
1262
+ * dolt-settle.mjs) against a wedged beads clone and reports whether it was
1263
+ * repaired. This is the operator/tool entry point onto the SAME function both
1264
+ * divergence terminals invoke -- one implementation, three callers -- so a
1265
+ * manual repair and an automatic one behave identically. `command` is
1266
+ * required (settle issues every `bd dolt`/`dolt` command through it);
1267
+ * `platform`/`arch` are optional and probed from the member when absent.
1268
+ * `opts.settle` may be supplied to override the callback (tests do this).
1269
+ *
1270
+ * @param {string} member
1271
+ * @param {{ command?: Function, log?: Function, platform?: string, arch?: string, settle?: Function, [key: string]: any }} [opts]
1272
+ * @returns {Promise<{ repaired: boolean, escalation?: string, result?: object }>}
1273
+ */
1274
+ export async function repair(member, opts = {}) {
1275
+ const { command, log = () => {}, platform, arch } = opts;
1276
+ if (typeof command !== 'function') {
1277
+ return { repaired: false, escalation: 'not-configured: repair() requires an injected command() to run settle' };
1278
+ }
1279
+ const settle = typeof opts.settle === 'function'
1280
+ ? opts.settle
1281
+ : buildSettleCallback(member, { command, log, platform, arch });
1282
+ let result = null;
1283
+ try {
1284
+ result = await settle({ operation: 'repair' });
1285
+ } catch (err) {
1286
+ log(`[Dolt] repair() failed operationally for member '${member}' (an infra failure, NOT an unresolvable conflict): ${(err && err.message) || err}`);
1287
+ return { repaired: false, escalation: 'settle-operational-failure', result: { error: (err && err.message) || String(err) } };
1288
+ }
1289
+ if (result && result.ok) {
1290
+ log(`[Dolt] repair() settled member '${member}' (tables: ${(result.resolvedTables || []).join(', ') || 'none'}).`);
1291
+ return { repaired: true, result };
1292
+ }
1293
+ log(`[Dolt] repair() did NOT settle member '${member}'.`);
1294
+ return { repaired: false, escalation: 'unrecovered', result };
1295
+ }
1296
+
1297
+ export const DoltSync = {
1298
+ syncBefore,
1299
+ syncAfter,
1300
+ status,
1301
+ refreshView,
1302
+ ensureReady,
1303
+ flush,
1304
+ repair,
1305
+ capabilities,
1306
+ getDegradedSyncRecords,
1307
+ clearDegradedSyncRecords,
1308
+ };
1309
+
1310
+ export default DoltSync;