@apralabs/apra-fleet 0.3.5 → 0.4.0

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