@apralabs/apra-fleet 0.4.2 → 0.4.3

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 (370) hide show
  1. package/README.md +38 -5
  2. package/dist/agents/backlog-groomer.md +25 -0
  3. package/dist/agents/ci-watcher.md +11 -0
  4. package/dist/agents/deployer.md +37 -2
  5. package/dist/agents/doer.md +36 -12
  6. package/dist/agents/harvester.md +11 -0
  7. package/dist/agents/integ-test-runner.md +11 -0
  8. package/dist/agents/kb-reconciler.md +9 -0
  9. package/dist/agents/plan-reviewer.md +110 -22
  10. package/dist/agents/planner.md +125 -37
  11. package/dist/agents/regression-test-runner.md +11 -0
  12. package/dist/agents/reviewer.md +13 -2
  13. package/dist/agents/schemas/plan-reviewer-output.json +37 -0
  14. package/dist/cli/agent-transform.d.ts +83 -2
  15. package/dist/cli/agent-transform.d.ts.map +1 -1
  16. package/dist/cli/agent-transform.js +266 -21
  17. package/dist/cli/agent-transform.js.map +1 -1
  18. package/dist/cli/auth.d.ts.map +1 -1
  19. package/dist/cli/auth.js +28 -9
  20. package/dist/cli/auth.js.map +1 -1
  21. package/dist/cli/config.d.ts +7 -5
  22. package/dist/cli/config.d.ts.map +1 -1
  23. package/dist/cli/config.js +44 -34
  24. package/dist/cli/config.js.map +1 -1
  25. package/dist/cli/install.d.ts +33 -0
  26. package/dist/cli/install.d.ts.map +1 -1
  27. package/dist/cli/install.js +290 -23
  28. package/dist/cli/install.js.map +1 -1
  29. package/dist/cli/kb-directives.d.ts.map +1 -1
  30. package/dist/cli/kb-directives.js +2 -1
  31. package/dist/cli/kb-directives.js.map +1 -1
  32. package/dist/cli/register-member.d.ts.map +1 -1
  33. package/dist/cli/register-member.js +6 -2
  34. package/dist/cli/register-member.js.map +1 -1
  35. package/dist/commands/kb-server.d.ts +3 -0
  36. package/dist/commands/kb-server.d.ts.map +1 -1
  37. package/dist/commands/kb-server.js +43 -3
  38. package/dist/commands/kb-server.js.map +1 -1
  39. package/dist/index.js +3 -3
  40. package/dist/os/linux.d.ts +6 -0
  41. package/dist/os/linux.d.ts.map +1 -1
  42. package/dist/os/linux.js +35 -2
  43. package/dist/os/linux.js.map +1 -1
  44. package/dist/os/os-commands.d.ts +61 -2
  45. package/dist/os/os-commands.d.ts.map +1 -1
  46. package/dist/os/windows-gitbash.d.ts +5 -0
  47. package/dist/os/windows-gitbash.d.ts.map +1 -1
  48. package/dist/os/windows-gitbash.js +15 -0
  49. package/dist/os/windows-gitbash.js.map +1 -1
  50. package/dist/os/windows.d.ts +6 -0
  51. package/dist/os/windows.d.ts.map +1 -1
  52. package/dist/os/windows.js +46 -3
  53. package/dist/os/windows.js.map +1 -1
  54. package/dist/providers/agy.d.ts +115 -6
  55. package/dist/providers/agy.d.ts.map +1 -1
  56. package/dist/providers/agy.js +569 -53
  57. package/dist/providers/agy.js.map +1 -1
  58. package/dist/providers/claude.d.ts +81 -3
  59. package/dist/providers/claude.d.ts.map +1 -1
  60. package/dist/providers/claude.js +344 -10
  61. package/dist/providers/claude.js.map +1 -1
  62. package/dist/providers/codex.d.ts +4 -2
  63. package/dist/providers/codex.d.ts.map +1 -1
  64. package/dist/providers/codex.js +19 -2
  65. package/dist/providers/codex.js.map +1 -1
  66. package/dist/providers/copilot.d.ts +4 -2
  67. package/dist/providers/copilot.d.ts.map +1 -1
  68. package/dist/providers/copilot.js +20 -2
  69. package/dist/providers/copilot.js.map +1 -1
  70. package/dist/providers/none.d.ts +4 -2
  71. package/dist/providers/none.d.ts.map +1 -1
  72. package/dist/providers/none.js +17 -2
  73. package/dist/providers/none.js.map +1 -1
  74. package/dist/providers/opencode.d.ts +3 -1
  75. package/dist/providers/opencode.d.ts.map +1 -1
  76. package/dist/providers/opencode.js +22 -2
  77. package/dist/providers/opencode.js.map +1 -1
  78. package/dist/providers/provider.d.ts +201 -6
  79. package/dist/providers/provider.d.ts.map +1 -1
  80. package/dist/providers/provider.js +56 -0
  81. package/dist/providers/provider.js.map +1 -1
  82. package/dist/services/agy-project.d.ts +102 -0
  83. package/dist/services/agy-project.d.ts.map +1 -0
  84. package/dist/services/agy-project.js +356 -0
  85. package/dist/services/agy-project.js.map +1 -0
  86. package/dist/services/auth-socket.js +4 -4
  87. package/dist/services/auth-web.js +1 -1
  88. package/dist/services/cloud/lifecycle.d.ts.map +1 -1
  89. package/dist/services/cloud/lifecycle.js +33 -4
  90. package/dist/services/cloud/lifecycle.js.map +1 -1
  91. package/dist/services/credential-cleanup.d.ts.map +1 -1
  92. package/dist/services/credential-cleanup.js +35 -17
  93. package/dist/services/credential-cleanup.js.map +1 -1
  94. package/dist/services/exit-drain.d.ts +44 -0
  95. package/dist/services/exit-drain.d.ts.map +1 -0
  96. package/dist/services/exit-drain.js +52 -0
  97. package/dist/services/exit-drain.js.map +1 -0
  98. package/dist/services/github-app.d.ts.map +1 -1
  99. package/dist/services/github-app.js +32 -4
  100. package/dist/services/github-app.js.map +1 -1
  101. package/dist/services/http-transport.d.ts +1 -0
  102. package/dist/services/http-transport.d.ts.map +1 -1
  103. package/dist/services/http-transport.js +48 -1
  104. package/dist/services/http-transport.js.map +1 -1
  105. package/dist/services/knowledge/kb-config.d.ts +42 -0
  106. package/dist/services/knowledge/kb-config.d.ts.map +1 -0
  107. package/dist/services/knowledge/kb-config.js +54 -0
  108. package/dist/services/knowledge/kb-config.js.map +1 -0
  109. package/dist/services/knowledge/kb-providers.d.ts +7 -1
  110. package/dist/services/knowledge/kb-providers.d.ts.map +1 -1
  111. package/dist/services/knowledge/kb-providers.js +191 -17
  112. package/dist/services/knowledge/kb-providers.js.map +1 -1
  113. package/dist/services/knowledge/require-sqlite-project.d.ts +32 -0
  114. package/dist/services/knowledge/require-sqlite-project.d.ts.map +1 -0
  115. package/dist/services/knowledge/require-sqlite-project.js +38 -0
  116. package/dist/services/knowledge/require-sqlite-project.js.map +1 -0
  117. package/dist/services/model-pricing.d.ts.map +1 -1
  118. package/dist/services/model-pricing.js +7 -3
  119. package/dist/services/model-pricing.js.map +1 -1
  120. package/dist/services/secret-token.d.ts +38 -0
  121. package/dist/services/secret-token.d.ts.map +1 -0
  122. package/dist/services/secret-token.js +51 -0
  123. package/dist/services/secret-token.js.map +1 -0
  124. package/dist/services/service-manager/types.d.ts +3 -1
  125. package/dist/services/service-manager/types.d.ts.map +1 -1
  126. package/dist/services/service-manager/windows.d.ts +14 -2
  127. package/dist/services/service-manager/windows.d.ts.map +1 -1
  128. package/dist/services/service-manager/windows.js +65 -7
  129. package/dist/services/service-manager/windows.js.map +1 -1
  130. package/dist/services/ssh.d.ts.map +1 -1
  131. package/dist/services/ssh.js +58 -2
  132. package/dist/services/ssh.js.map +1 -1
  133. package/dist/services/stall/read-log-tail.d.ts.map +1 -1
  134. package/dist/services/stall/read-log-tail.js +20 -10
  135. package/dist/services/stall/read-log-tail.js.map +1 -1
  136. package/dist/services/stall/stall-detector.d.ts +53 -4
  137. package/dist/services/stall/stall-detector.d.ts.map +1 -1
  138. package/dist/services/stall/stall-detector.js +212 -34
  139. package/dist/services/stall/stall-detector.js.map +1 -1
  140. package/dist/services/strategy.d.ts.map +1 -1
  141. package/dist/services/strategy.js +79 -2
  142. package/dist/services/strategy.js.map +1 -1
  143. package/dist/services/substitution-engine.js +2 -2
  144. package/dist/services/substitution-engine.js.map +1 -1
  145. package/dist/services/tool-registry.d.ts.map +1 -1
  146. package/dist/services/tool-registry.js +5 -3
  147. package/dist/services/tool-registry.js.map +1 -1
  148. package/dist/services/vcs/azure-devops.d.ts +66 -1
  149. package/dist/services/vcs/azure-devops.d.ts.map +1 -1
  150. package/dist/services/vcs/azure-devops.js +192 -21
  151. package/dist/services/vcs/azure-devops.js.map +1 -1
  152. package/dist/services/vcs/types.d.ts +1 -1
  153. package/dist/skills/fleet-sprint-cli/SKILL.md +18 -0
  154. package/dist/skills/pm/SKILL.md +1 -1
  155. package/dist/skills/pm/cost.md +0 -3
  156. package/dist/skills/pm/fleet-addendum.md +2 -2
  157. package/dist/tools/check-status.d.ts +7 -4
  158. package/dist/tools/check-status.d.ts.map +1 -1
  159. package/dist/tools/check-status.js +2 -0
  160. package/dist/tools/check-status.js.map +1 -1
  161. package/dist/tools/compose-permissions.d.ts +6 -0
  162. package/dist/tools/compose-permissions.d.ts.map +1 -1
  163. package/dist/tools/compose-permissions.js +182 -34
  164. package/dist/tools/compose-permissions.js.map +1 -1
  165. package/dist/tools/credential-store-set.js +1 -1
  166. package/dist/tools/execute-command.d.ts.map +1 -1
  167. package/dist/tools/execute-command.js +31 -20
  168. package/dist/tools/execute-command.js.map +1 -1
  169. package/dist/tools/execute-prompt.d.ts +15 -2
  170. package/dist/tools/execute-prompt.d.ts.map +1 -1
  171. package/dist/tools/execute-prompt.js +1196 -892
  172. package/dist/tools/execute-prompt.js.map +1 -1
  173. package/dist/tools/kb-capture.d.ts +2 -2
  174. package/dist/tools/kb-capture.d.ts.map +1 -1
  175. package/dist/tools/kb-capture.js +29 -5
  176. package/dist/tools/kb-capture.js.map +1 -1
  177. package/dist/tools/kb-export.d.ts +2 -2
  178. package/dist/tools/kb-export.d.ts.map +1 -1
  179. package/dist/tools/kb-export.js +3 -28
  180. package/dist/tools/kb-export.js.map +1 -1
  181. package/dist/tools/kb-feedback.d.ts.map +1 -1
  182. package/dist/tools/kb-feedback.js +3 -1
  183. package/dist/tools/kb-feedback.js.map +1 -1
  184. package/dist/tools/kb-freshness-sweep.d.ts.map +1 -1
  185. package/dist/tools/kb-freshness-sweep.js +3 -1
  186. package/dist/tools/kb-freshness-sweep.js.map +1 -1
  187. package/dist/tools/kb-import.d.ts.map +1 -1
  188. package/dist/tools/kb-import.js +2 -1
  189. package/dist/tools/kb-import.js.map +1 -1
  190. package/dist/tools/kb-list.d.ts.map +1 -1
  191. package/dist/tools/kb-list.js +3 -1
  192. package/dist/tools/kb-list.js.map +1 -1
  193. package/dist/tools/kb-query.d.ts +2 -2
  194. package/dist/tools/kb-reconcile-prefilter.d.ts.map +1 -1
  195. package/dist/tools/kb-reconcile-prefilter.js +3 -1
  196. package/dist/tools/kb-reconcile-prefilter.js.map +1 -1
  197. package/dist/tools/kb-resolve-contradiction.d.ts.map +1 -1
  198. package/dist/tools/kb-resolve-contradiction.js +3 -1
  199. package/dist/tools/kb-resolve-contradiction.js.map +1 -1
  200. package/dist/tools/kb-setup.d.ts.map +1 -1
  201. package/dist/tools/kb-setup.js +125 -20
  202. package/dist/tools/kb-setup.js.map +1 -1
  203. package/dist/tools/kb-stats.d.ts.map +1 -1
  204. package/dist/tools/kb-stats.js +64 -43
  205. package/dist/tools/kb-stats.js.map +1 -1
  206. package/dist/tools/list-members.d.ts +2 -2
  207. package/dist/tools/list-members.d.ts.map +1 -1
  208. package/dist/tools/list-members.js +1 -0
  209. package/dist/tools/list-members.js.map +1 -1
  210. package/dist/tools/member-detail.d.ts +2 -2
  211. package/dist/tools/member-detail.d.ts.map +1 -1
  212. package/dist/tools/member-detail.js +17 -0
  213. package/dist/tools/member-detail.js.map +1 -1
  214. package/dist/tools/member-reservation.d.ts +58 -1
  215. package/dist/tools/member-reservation.d.ts.map +1 -1
  216. package/dist/tools/member-reservation.js +61 -20
  217. package/dist/tools/member-reservation.js.map +1 -1
  218. package/dist/tools/provision-auth.d.ts +80 -1
  219. package/dist/tools/provision-auth.d.ts.map +1 -1
  220. package/dist/tools/provision-auth.js +142 -54
  221. package/dist/tools/provision-auth.js.map +1 -1
  222. package/dist/tools/provision-vcs-auth.d.ts +91 -1
  223. package/dist/tools/provision-vcs-auth.d.ts.map +1 -1
  224. package/dist/tools/provision-vcs-auth.js +209 -49
  225. package/dist/tools/provision-vcs-auth.js.map +1 -1
  226. package/dist/tools/register-member.d.ts +12 -9
  227. package/dist/tools/register-member.d.ts.map +1 -1
  228. package/dist/tools/register-member.js +99 -12
  229. package/dist/tools/register-member.js.map +1 -1
  230. package/dist/tools/remove-member.d.ts.map +1 -1
  231. package/dist/tools/remove-member.js +27 -2
  232. package/dist/tools/remove-member.js.map +1 -1
  233. package/dist/tools/send-email.d.ts +2 -2
  234. package/dist/tools/setup-git-app.d.ts.map +1 -1
  235. package/dist/tools/setup-git-app.js +11 -7
  236. package/dist/tools/setup-git-app.js.map +1 -1
  237. package/dist/tools/shutdown-server.d.ts +2 -0
  238. package/dist/tools/shutdown-server.d.ts.map +1 -1
  239. package/dist/tools/shutdown-server.js +23 -1
  240. package/dist/tools/shutdown-server.js.map +1 -1
  241. package/dist/tools/update-member.d.ts +12 -9
  242. package/dist/tools/update-member.d.ts.map +1 -1
  243. package/dist/tools/update-member.js +43 -11
  244. package/dist/tools/update-member.js.map +1 -1
  245. package/dist/tools/vcs-credential-exec.d.ts +127 -0
  246. package/dist/tools/vcs-credential-exec.d.ts.map +1 -0
  247. package/dist/tools/vcs-credential-exec.js +197 -0
  248. package/dist/tools/vcs-credential-exec.js.map +1 -0
  249. package/dist/types.d.ts +13 -0
  250. package/dist/types.d.ts.map +1 -1
  251. package/dist/utils/log-helpers.d.ts.map +1 -1
  252. package/dist/utils/log-helpers.js +2 -2
  253. package/dist/utils/log-helpers.js.map +1 -1
  254. package/dist/utils/prompt-errors.d.ts.map +1 -1
  255. package/dist/utils/prompt-errors.js +7 -1
  256. package/dist/utils/prompt-errors.js.map +1 -1
  257. package/dist/utils/shell-escape.d.ts +16 -0
  258. package/dist/utils/shell-escape.d.ts.map +1 -1
  259. package/dist/utils/shell-escape.js +22 -2
  260. package/dist/utils/shell-escape.js.map +1 -1
  261. package/dist/utils/vcs-provider-detect.d.ts +65 -0
  262. package/dist/utils/vcs-provider-detect.d.ts.map +1 -0
  263. package/dist/utils/vcs-provider-detect.js +109 -0
  264. package/dist/utils/vcs-provider-detect.js.map +1 -0
  265. package/dist/utils/workspace-trust.d.ts +20 -17
  266. package/dist/utils/workspace-trust.d.ts.map +1 -1
  267. package/dist/utils/workspace-trust.js +87 -1
  268. package/dist/utils/workspace-trust.js.map +1 -1
  269. package/dist/workflows/auto-sprint.js +176 -15
  270. package/package.json +6 -4
  271. package/packages/apra-fleet-client/src/client/api.mjs +319 -17
  272. package/packages/apra-fleet-client/src/client/errors.mjs +6 -2
  273. package/packages/apra-fleet-se/apra-pm/agents/_shared/GRAPH-SEMANTICS.md +10 -2
  274. package/packages/apra-fleet-se/apra-pm/agents/backlog-groomer.md +25 -0
  275. package/packages/apra-fleet-se/apra-pm/agents/ci-watcher.md +11 -0
  276. package/packages/apra-fleet-se/apra-pm/agents/deployer.md +37 -2
  277. package/packages/apra-fleet-se/apra-pm/agents/doer.md +36 -12
  278. package/packages/apra-fleet-se/apra-pm/agents/harvester.md +11 -0
  279. package/packages/apra-fleet-se/apra-pm/agents/integ-test-runner.md +11 -0
  280. package/packages/apra-fleet-se/apra-pm/agents/kb-reconciler.md +9 -0
  281. package/packages/apra-fleet-se/apra-pm/agents/plan-reviewer.md +110 -22
  282. package/packages/apra-fleet-se/apra-pm/agents/planner.md +125 -37
  283. package/packages/apra-fleet-se/apra-pm/agents/regression-test-runner.md +11 -0
  284. package/packages/apra-fleet-se/apra-pm/agents/reviewer.md +13 -2
  285. package/packages/apra-fleet-se/apra-pm/agents/schemas/plan-reviewer-output.json +37 -0
  286. package/packages/apra-fleet-se/apra-pm/skills/pm/SKILL.md +1 -1
  287. package/packages/apra-fleet-se/apra-pm/skills/pm/cost.md +0 -3
  288. package/packages/apra-fleet-se/apra-pm/skills/pm/fleet-addendum.md +2 -2
  289. package/packages/apra-fleet-se/bin/cli.mjs +149 -1
  290. package/packages/apra-fleet-se/bin/serve.mjs +78 -4
  291. package/packages/apra-fleet-se/fleet-sprint/abort.mjs +481 -0
  292. package/packages/apra-fleet-se/fleet-sprint/beads-children.mjs +491 -0
  293. package/packages/apra-fleet-se/fleet-sprint/beads-identity-check.mjs +282 -0
  294. package/packages/apra-fleet-se/fleet-sprint/beads-identity.mjs +208 -0
  295. package/packages/apra-fleet-se/fleet-sprint/beads-scope.mjs +638 -0
  296. package/packages/apra-fleet-se/fleet-sprint/beads-transitions.mjs +301 -0
  297. package/packages/apra-fleet-se/fleet-sprint/branch-ensure.mjs +96 -0
  298. package/packages/apra-fleet-se/fleet-sprint/conflict-ladder.mjs +8 -0
  299. package/packages/apra-fleet-se/fleet-sprint/contracts.mjs +61 -14
  300. package/packages/apra-fleet-se/fleet-sprint/coordination.mjs +516 -0
  301. package/packages/apra-fleet-se/fleet-sprint/dispatch-failure.mjs +184 -0
  302. package/packages/apra-fleet-se/fleet-sprint/dispatch-role.mjs +1121 -0
  303. package/packages/apra-fleet-se/fleet-sprint/dispatch-safety-guard.mjs +216 -4
  304. package/packages/apra-fleet-se/fleet-sprint/docs/README.md +1 -1
  305. package/packages/apra-fleet-se/fleet-sprint/docs/dolt-sync-redesign.md +276 -0
  306. package/packages/apra-fleet-se/fleet-sprint/docs/escalate-to-llm-design.md +1 -1
  307. package/packages/apra-fleet-se/fleet-sprint/docs/run-sprint-cycle-prelude-decision.md +215 -0
  308. package/packages/apra-fleet-se/fleet-sprint/dolt-literal-guard.mjs +56 -1
  309. package/packages/apra-fleet-se/fleet-sprint/dolt-sync.mjs +996 -32
  310. package/packages/apra-fleet-se/fleet-sprint/errors.mjs +267 -0
  311. package/packages/apra-fleet-se/fleet-sprint/explicit-id-create-guard.mjs +501 -0
  312. package/packages/apra-fleet-se/fleet-sprint/fatal-diagnostics.mjs +134 -0
  313. package/packages/apra-fleet-se/fleet-sprint/full-db-fetch-guard.mjs +102 -0
  314. package/packages/apra-fleet-se/fleet-sprint/git-sync.mjs +556 -0
  315. package/packages/apra-fleet-se/fleet-sprint/git-topology.mjs +495 -0
  316. package/packages/apra-fleet-se/fleet-sprint/guarded-modules.mjs +564 -0
  317. package/packages/apra-fleet-se/fleet-sprint/inline-ladder-guard.mjs +216 -0
  318. package/packages/apra-fleet-se/fleet-sprint/kb.mjs +728 -0
  319. package/packages/apra-fleet-se/fleet-sprint/mcp-result.mjs +75 -0
  320. package/packages/apra-fleet-se/fleet-sprint/member-provisioning.mjs +252 -0
  321. package/packages/apra-fleet-se/fleet-sprint/member-sync.mjs +581 -0
  322. package/packages/apra-fleet-se/fleet-sprint/member-target.mjs +93 -0
  323. package/packages/apra-fleet-se/fleet-sprint/newtask-text.mjs +266 -0
  324. package/packages/apra-fleet-se/fleet-sprint/parent-notes-staleness.mjs +201 -0
  325. package/packages/apra-fleet-se/fleet-sprint/phases/deploy.mjs +136 -0
  326. package/packages/apra-fleet-se/fleet-sprint/phases/develop.mjs +822 -0
  327. package/packages/apra-fleet-se/fleet-sprint/phases/ensure-sprint-branch.mjs +294 -0
  328. package/packages/apra-fleet-se/fleet-sprint/phases/final-review.mjs +403 -0
  329. package/packages/apra-fleet-se/fleet-sprint/phases/harvest.mjs +180 -0
  330. package/packages/apra-fleet-se/fleet-sprint/phases/integ-test.mjs +358 -0
  331. package/packages/apra-fleet-se/fleet-sprint/phases/plan.mjs +390 -0
  332. package/packages/apra-fleet-se/fleet-sprint/phases/publish-pr.mjs +323 -0
  333. package/packages/apra-fleet-se/fleet-sprint/phases/re-review.mjs +232 -0
  334. package/packages/apra-fleet-se/fleet-sprint/phases/regression-test.mjs +174 -0
  335. package/packages/apra-fleet-se/fleet-sprint/phases/replan.mjs +197 -0
  336. package/packages/apra-fleet-se/fleet-sprint/phases/review.mjs +305 -0
  337. package/packages/apra-fleet-se/fleet-sprint/prompts.mjs +559 -0
  338. package/packages/apra-fleet-se/fleet-sprint/role-policies.mjs +1416 -0
  339. package/packages/apra-fleet-se/fleet-sprint/round-session.mjs +100 -0
  340. package/packages/apra-fleet-se/fleet-sprint/runner.js +1467 -9798
  341. package/packages/apra-fleet-se/fleet-sprint/se-posix.mjs +17 -12
  342. package/packages/apra-fleet-se/fleet-sprint/shell-command-guard.mjs +304 -0
  343. package/packages/apra-fleet-se/fleet-sprint/skills/fleet-sprint-cli/SKILL.md +18 -0
  344. package/packages/apra-fleet-se/fleet-sprint/skills/fleet-supervisor/SKILL.md +21 -2
  345. package/packages/apra-fleet-se/fleet-sprint/sprint-args.mjs +454 -0
  346. package/packages/apra-fleet-se/fleet-sprint/sprint-report.mjs +239 -0
  347. package/packages/apra-fleet-se/fleet-sprint/sprint-state.mjs +163 -0
  348. package/packages/apra-fleet-se/fleet-sprint/unbracketed-push-guard.mjs +234 -0
  349. package/packages/apra-fleet-se/fleet-sprint/usage-limit-controller.mjs +211 -0
  350. package/packages/apra-fleet-se/fleet-sprint/vcs-auth.mjs +1279 -0
  351. package/packages/apra-fleet-se/fleet-sprint/vcs-module.mjs +153 -19
  352. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/azure-devops.mjs +71 -21
  353. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/bitbucket.mjs +28 -0
  354. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/github.mjs +131 -0
  355. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/index.mjs +140 -16
  356. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/shell-helpers.mjs +1 -0
  357. package/packages/apra-fleet-se/fleet-sprint/viewer-extensions.mjs +77 -2
  358. package/packages/apra-fleet-se/fleet-sprint/worklists.mjs +559 -0
  359. package/packages/apra-fleet-se/package.json +1 -1
  360. package/packages/apra-fleet-workflow/src/viewer/index.mjs +17 -6
  361. package/packages/apra-fleet-workflow/src/workflow/index.mjs +49 -7
  362. package/skills/fleet/SKILL.md +8 -8
  363. package/skills/fleet/auth-azdevops.md +14 -3
  364. package/skills/fleet/auth-bitbucket.md +2 -2
  365. package/skills/fleet/auth-github.md +5 -4
  366. package/skills/fleet/onboarding.md +3 -3
  367. package/skills/fleet/permissions.md +5 -1
  368. package/skills/fleet/profiles/node.json +1 -1
  369. package/skills/fleet/troubleshooting.md +3 -3
  370. package/version.json +1 -1
@@ -194,32 +194,300 @@ export function classifyDoltFailure(output) {
194
194
  * @returns {Promise<boolean>}
195
195
  */
196
196
  export async function isMemberSyncRemoteConfigured(member, opts) {
197
- const { command, log = () => {} } = opts;
197
+ return (await readMemberSyncRemote(member, opts)).configured;
198
+ }
199
+
200
+ // ---------------------------------------------------------------------------
201
+ // sync.remote probe memoization (apra-fleet-akuv)
202
+ // ---------------------------------------------------------------------------
203
+ //
204
+ // `bd config get sync.remote --json` used to be spawned FRESH on every call --
205
+ // once per D-pull pre-gate, once per D-push pre-gate, once per status() probe,
206
+ // and every dispatch is bracketed -- which measured out at roughly 90-160
207
+ // spawns (about 0.6s each) per sprint re-reading a value that never changes
208
+ // mid-run. A codebase-wide search confirmed no production path in this package
209
+ // writes sync.remote during a live sprint; only test fixtures and one-time
210
+ // setup/seed scripts do. So the result is memoized PER MEMBER for the process
211
+ // lifetime, with explicit invalidation rather than a TTL (a TTL would re-add
212
+ // spawns for no real safety).
213
+ //
214
+ // WHAT IS CACHED, deliberately narrow: ONLY a positively parsed answer -- a
215
+ // clean JSON parse of the command's output. Every fail-safe path (command()
216
+ // threw, a failSoft error result, no output at all, unparseable output) reports
217
+ // "configured" WITHOUT caching, so a transient probe failure can never pin the
218
+ // fail-safe answer for the rest of the run; the next call re-probes. This
219
+ // preserves isMemberSyncRemoteConfigured's fail-CLOSED contract exactly.
220
+ //
221
+ // INVALIDATION -- three HARD seams that drop BOTH this memo and the member's
222
+ // recorded remote-tip fingerprint (see the invariant below), plus one SOFT
223
+ // seam that drops nothing and instead marks the member for a lazy re-check:
224
+ // 1. noteMemberCommand() -- called from the runner's central command()
225
+ // wrapper; drops the entry for any `bd config set` / `bd dolt remote` /
226
+ // `bd init` / `bd bootstrap` the ORCHESTRATOR issues against that member.
227
+ // 2. the auth self-heal path in runDoltStep(), when onAuthFailure fires for
228
+ // a member (re-provisioning credentials can rewire the remote).
229
+ // 3. repair(), the operator/tool remediation entry point.
230
+ // 4. (soft) noteMemberDispatchCompleted() -- called from the runner's
231
+ // central agent() wrapper the moment ANY dispatch to a member settles.
232
+ // A dispatched agent runs its `bd` commands in its own session on the
233
+ // member, never through the command() wrapper, so seam 1 cannot see an
234
+ // agent-side `bd config set sync.remote`. This seam therefore marks the
235
+ // member DISPATCHED-SINCE-VERIFIED; the memo stays, and is re-read
236
+ // (one `bd config get`, a plain config.yaml read) only at the one
237
+ // decision a stale answer could turn into stale DATA -- the moment a
238
+ // D-pull is about to be SKIPPED on the strength of the fingerprint. See
239
+ // noteMemberDispatchCompleted for why this is the right trigger and
240
+ // why an unconditional per-dispatch wipe was replaced.
241
+ //
242
+ // INVARIANT: the hard seams forget the two per-member memos (this one and
243
+ // lastSyncedTips) TOGETHER. Any event that can rewire a member's remote or
244
+ // replace its local clone invalidates both; a seam that dropped only one
245
+ // would leave a fingerprint that was minted against the other, stale, answer.
246
+ // The fingerprint additionally carries the URL it was minted against, so a
247
+ // memo that is later re-read to a DIFFERENT url can never validate it.
248
+ //
249
+ // The same cache entry carries the remote URL, which the remote-tip
250
+ // fingerprint (see readRemoteDoltTip below) needs -- one probe answers both
251
+ // questions, so the fingerprint costs no extra `bd config get`.
252
+
253
+ /** member -> { configured: boolean, url: string|null } (positively parsed only) */
254
+ const syncRemoteCache = new Map();
255
+
256
+ /** Members dispatched to since their sync.remote memo was last POSITIVELY
257
+ * read. Set by noteMemberDispatchCompleted(); cleared by any positive
258
+ * re-read of the memo and by the hard seams. Consulted only on the
259
+ * D-pull skip path (see confirmSkipAfterDispatch). */
260
+ const dispatchedSinceVerified = new Set();
261
+
262
+ /** Commands whose success can change a member's bd-level sync.remote wiring.
263
+ *
264
+ * Deliberately NOT left-anchored (dolt sync budget review round 2, item 5):
265
+ * member-bound command strings are routinely COMPOUND, because a member's cwd
266
+ * has to be established in the same string (its shell may be PowerShell or a
267
+ * POSIX shell). scripts/dolt-settle-integration.mjs already issues exactly
268
+ * that shape --
269
+ * cd "<dir>" && bd dolt remote add origin "<url>" && bd config set sync.remote "<url>"
270
+ * Set-Location "<dir>"; bd dolt remote add origin "<url>"; bd config set ...
271
+ * -- both of which the old `^\s*bd` anchor silently failed to recognize,
272
+ * leaving a rewired member answering from a stale memo. The leading
273
+ * `(?:^|[\s;&|(])` keeps the match word-bounded (so `abd bootstrap` or
274
+ * `--bd init` never match) while allowing anything to precede the invocation.
275
+ */
276
+ const SYNC_REMOTE_INVALIDATING_COMMAND_RE = /(?:^|[\s;&|(])bd\s+(?:config\s+set|dolt\s+remote|init|bootstrap)\b/i;
277
+
278
+ /**
279
+ * Drop the memoized sync.remote answer for `member` (or for every member when
280
+ * called with no argument -- test hygiene, and the operator-repair path).
281
+ *
282
+ * @param {string} [member]
283
+ * @returns {number} how many cache entries were dropped
284
+ */
285
+ export function invalidateSyncRemoteCache(member) {
286
+ if (member === undefined) {
287
+ const n = syncRemoteCache.size;
288
+ syncRemoteCache.clear();
289
+ return n;
290
+ }
291
+ return syncRemoteCache.delete(member) ? 1 : 0;
292
+ }
293
+
294
+ /**
295
+ * Invalidation seam for the runner's central command() wrapper: hand every
296
+ * member-bound command string here and the sync.remote memo is dropped when the
297
+ * command could have rewired that member's remote. A non-matching command (the
298
+ * overwhelming majority) is a cheap regex test and no cache change.
299
+ *
300
+ * The recorded remote-tip fingerprint is dropped alongside the memo (dolt sync
301
+ * budget review round 2, item 4): `bd init` / `bd bootstrap` can REPLACE the
302
+ * member's local Dolt clone outright, and a freshly recreated (empty) clone is
303
+ * not current with anything -- yet the remote tip it is compared against has
304
+ * not moved, so a surviving fingerprint would match and skip the very pull that
305
+ * clone needs most. Forgetting it only ever costs one real pull.
306
+ *
307
+ * @param {string} member
308
+ * @param {string} cmd
309
+ * @returns {boolean} whether the command invalidated the memo
310
+ */
311
+ export function noteMemberCommand(member, cmd) {
312
+ if (typeof member !== 'string' || member.length === 0) return false;
313
+ if (typeof cmd !== 'string') return false;
314
+ if (!SYNC_REMOTE_INVALIDATING_COMMAND_RE.test(cmd)) return false;
315
+ forgetMemberSyncState(member);
316
+ return true;
317
+ }
318
+
319
+ /**
320
+ * Drop BOTH per-member memos (the sync.remote answer and the recorded
321
+ * remote-tip fingerprint) for `member`. The one primitive every invalidation
322
+ * seam calls, so the two can never drift apart.
323
+ *
324
+ * @param {string} member
325
+ */
326
+ function forgetMemberSyncState(member) {
327
+ invalidateSyncRemoteCache(member);
328
+ clearLastSyncedTip(member);
329
+ dispatchedSinceVerified.delete(member);
330
+ tipProbeFailures.delete(member);
331
+ }
332
+
333
+ /**
334
+ * Soft invalidation seam for the runner's central agent() wrapper: called
335
+ * once per dispatch, the moment the dispatch settles (fulfilled OR rejected),
336
+ * and BEFORE the post-dispatch D-push bracket for that member runs. Marks
337
+ * `member` as dispatched-since-verified. It forgets NOTHING.
338
+ *
339
+ * THE DESIGN DECISION (dolt sync budget review round 4). Round 3 made this
340
+ * seam an unconditional wipe of both memos, on the argument that an agent
341
+ * runs its `bd` commands in its own session (invisible to noteMemberCommand)
342
+ * and might `bd bootstrap` / `bd init` / `bd config set sync.remote` the
343
+ * member's clone. Combined with "a push never mints a fingerprint" (correct,
344
+ * see doltPullBefore's section comment), that left the fingerprint EMPTY at
345
+ * the start of every dispatch bracket -- the module's primary path -- and
346
+ * re-spawned `bd config get` once per dispatch (the golden mock-sprint
347
+ * transcript went from 1 probe to 14). The primary path then paid one
348
+ * ls-remote MORE than before this feature existed and skipped nothing.
349
+ *
350
+ * The wipe was the wrong tool because the hazards it guarded are not what
351
+ * they were assumed to be. Taking each agent-side event in turn, against
352
+ * what bd actually does (verified against the beads source):
353
+ *
354
+ * * `bd bootstrap` -- the one self-heal this repo's agent instructions
355
+ * prescribe ("database exists" -> retry with `--database <name>`) -- is
356
+ * NON-DESTRUCTIVE. With a DB present it validates and reports; it never
357
+ * replaces the clone. Where it does create a DB it CLONES it from the
358
+ * configured sync.remote, i.e. the result is current with the remote by
359
+ * construction. In neither case can a fingerprint that still equals the
360
+ * remote's tip describe a clone that is not at that tip. A surviving
361
+ * fingerprint stays TRUE across a bootstrap.
362
+ * * `bd init` REFUSES on an existing DB unless forced (`--reinit-local` /
363
+ * `--force`). A forced re-init yields a clone with an UNRELATED history:
364
+ * no `bd dolt pull` can bring it current (there is nothing to
365
+ * fast-forward), so skipping that pull changes nothing, and the clone's
366
+ * next push diverges into the terminals that already forget the tip and
367
+ * run settle. The fingerprint is not the deciding factor there either.
368
+ * * `bd config set sync.remote <other>` -- the ONE event where a skip would
369
+ * suppress a pull that WOULD have helped (the clone should now follow a
370
+ * different remote). This is handled, not accepted: the fingerprint is
371
+ * bound to the URL it was minted against, and a member marked here has
372
+ * its sync.remote RE-READ before any skip is taken on its fingerprint
373
+ * (confirmSkipAfterDispatch). A changed URL forgets the fingerprint and
374
+ * forces a real pull; an unreadable answer forces a real pull too.
375
+ *
376
+ * WHY LAZY, AND WHY ONLY ON THE SKIP PATH. A stale memo can only turn into
377
+ * stale DATA at one decision: "skip this pull". Every other consumer fails
378
+ * closed -- a wrong "configured" answer merely issues a real pull/push
379
+ * against whatever remote bd itself has configured, which is the right
380
+ * remote regardless of what we cached. So the re-read is paid exactly where
381
+ * it buys correctness: once per skip-after-dispatch (one `bd config get`, a
382
+ * plain config.yaml read with no Dolt engine start, instead of a real pull
383
+ * that opens the whole chunk store), never per dispatch. A bracket whose
384
+ * remote tip MOVED pays nothing extra; consecutive orchestrator-side reads
385
+ * with no dispatch in between pay nothing extra. The golden transcript is
386
+ * back to one probe per member per process.
387
+ *
388
+ * THE ABSENT CASE (round-4 review, finding 1). A member whose sync.remote
389
+ * was positively ABSENT when first read never reaches the skip path -- both
390
+ * pre-gates take the no-remote exit first -- so the lazy re-check above
391
+ * cannot cover it, and a first cut of this design accepted that as
392
+ * residual. It is not acceptable: an agent that wires a remote mid-dispatch
393
+ * (a `bd init --remote` / `bd config set sync.remote` in its own session)
394
+ * would leave every later D-push of that member reporting `{ ok: true,
395
+ * skipped: true, reason: 'no-remote' }` -- success -- while its bead closes
396
+ * never left the clone, for the rest of the process. So a memoized ABSENT
397
+ * answer is re-read once after any dispatch to the member, at the next
398
+ * pre-gate (readMemberSyncRemote). Cost: one config.yaml read per dispatch,
399
+ * paid ONLY by members with no remote (sandboxes, the no-remote mock
400
+ * sprint -- whose golden transcript therefore shows one probe per dispatch);
401
+ * a member with a remote still pays one probe per process.
402
+ *
403
+ * @param {string} member
404
+ * @returns {boolean} whether the member was marked (false for a non-member)
405
+ */
406
+ export function noteMemberDispatchCompleted(member) {
407
+ if (typeof member !== 'string' || member.length === 0) return false;
408
+ dispatchedSinceVerified.add(member);
409
+ return true;
410
+ }
411
+
412
+ /**
413
+ * Has `member` been dispatched to since its sync.remote memo was last
414
+ * positively read? Exposed for tests and operator tooling.
415
+ * @param {string} member
416
+ * @returns {boolean}
417
+ */
418
+ export function isMemberDispatchedSinceVerified(member) {
419
+ return dispatchedSinceVerified.has(member);
420
+ }
421
+
422
+ /**
423
+ * Read `member`'s bd-level sync.remote, memoized per member (see the section
424
+ * comment above). Returns both the fail-closed boolean the pre-gates consult
425
+ * and the remote URL string the tip fingerprint needs.
426
+ *
427
+ * `configured: true` with `url: null` means "could not be positively read, so
428
+ * treated as configured" -- the fail-safe answer, never cached. `positive`
429
+ * says whether the answer came from a clean parse (live or memoized) rather
430
+ * than the fail-safe fallback.
431
+ *
432
+ * `opts.verify: true` bypasses the memo and re-reads the member (the lazy
433
+ * post-dispatch check, see confirmSkipAfterDispatch). Any positive read --
434
+ * a cache miss or a verify -- refreshes the memo and clears the member's
435
+ * dispatched-since-verified mark.
436
+ *
437
+ * @param {string} member
438
+ * @param {{ command: Function, log?: Function, verify?: boolean }} opts
439
+ * @returns {Promise<{ configured: boolean, url: string|null, positive: boolean }>}
440
+ */
441
+ export async function readMemberSyncRemote(member, opts) {
442
+ const { command, log = () => {}, verify = false } = opts;
443
+ const cached = verify ? undefined : syncRemoteCache.get(member);
444
+ // A memoized ABSENT answer is re-read once after any dispatch to the
445
+ // member (round-4 review, finding 1). Nothing downstream of a cached
446
+ // "absent" ever reaches the fingerprint's lazy re-check -- both pre-gates
447
+ // take the no-remote exit first -- so an agent that wires a remote
448
+ // mid-dispatch would otherwise leave every later D-push of that member
449
+ // reporting a benign no-remote skip while its bead closes never left the
450
+ // clone. A memoized PRESENT answer needs no re-read here: a wrong
451
+ // "configured" answer fails closed (a real pull/push against whatever
452
+ // remote bd itself has), and the skip path re-verifies on its own.
453
+ const absentAfterDispatch = cached && cached.configured === false && dispatchedSinceVerified.has(member);
454
+ if (cached && !absentAfterDispatch) return { ...cached, positive: true };
455
+
198
456
  let res;
199
457
  try {
200
458
  res = await command('bd config get sync.remote --json', { member_name: member, silent: true, failSoft: true });
201
459
  } catch (err) {
202
460
  log(`[Dolt] could not query bd-level sync.remote for member '${member}' (fail-safe: treating as configured): ${err.message}`);
203
- return true;
461
+ return { configured: true, url: null, positive: false };
204
462
  }
205
463
  if (res && typeof res === 'object' && res.ok === false) {
206
464
  log(`[Dolt] 'bd config get sync.remote' failed for member '${member}' (fail-safe: treating as configured): ${res.error}`);
207
- return true;
465
+ return { configured: true, url: null, positive: false };
208
466
  }
209
467
  const output = res && typeof res === 'object' ? res.output : res;
210
468
  if (!output) {
211
469
  // No output to positively parse (e.g. a no-op/unmocked command()):
212
470
  // sync.remote cannot be confirmed absent, so do not treat it as
213
- // neutralized.
214
- return true;
471
+ // neutralized -- and do not cache a non-answer.
472
+ return { configured: true, url: null, positive: false };
215
473
  }
474
+ let parsed;
216
475
  try {
217
- const parsed = JSON.parse(output);
218
- return !(typeof parsed.value === 'string' && parsed.value.trim().length === 0);
476
+ parsed = JSON.parse(output);
219
477
  } catch (err) {
220
478
  log(`[Dolt] could not parse 'bd config get sync.remote --json' output for member '${member}' (fail-safe: treating as configured): ${err.message}`);
221
- return true;
479
+ return { configured: true, url: null, positive: false };
222
480
  }
481
+ const value = typeof parsed.value === 'string' ? parsed.value.trim() : null;
482
+ const entry = {
483
+ configured: !(value !== null && value.length === 0),
484
+ url: value !== null && value.length > 0 ? value : null,
485
+ };
486
+ // Only a positively parsed answer is memoized -- and a positive read is
487
+ // by definition a verification, so the dispatch mark is cleared with it.
488
+ syncRemoteCache.set(member, entry);
489
+ dispatchedSinceVerified.delete(member);
490
+ return { ...entry, positive: true };
223
491
  }
224
492
 
225
493
  // Bounded exponential backoff between TRANSIENT retries (apra-fleet-417.3.1).
@@ -235,11 +503,117 @@ export async function isMemberSyncRemoteConfigured(member, opts) {
235
503
  // The original 8s cap meant even 5 retries covered at most ~15s of backoff,
236
504
  // structurally unable to span an outage an order of magnitude longer; the
237
505
  // sprint kept dying with retries correctly firing but exhausted. Raised to
238
- // 30s so a realistic retry budget (see maxTransientRetries below) can
239
- // actually outlast one of these windows instead of just softening it.
506
+ // 30s so a realistic retry budget can actually outlast one of these windows
507
+ // instead of just softening it.
508
+ //
509
+ // TIME-BOXED, NOT COUNT-BOXED (dolt sync budget review, section A.3)
510
+ // -------------------------------------------------------------------------
511
+ // Widening the ladder to `maxTransientRetries = 8` with a 30s cap fixed the
512
+ // spawn-outage case but applied that budget to EVERY transient kind, and the
513
+ // cost was demonstrated immediately: the unit suite went from 80s to 6m15s,
514
+ // because an ordinary transient in a test fixture now walked the full 8-retry
515
+ // x 30s-cap ladder (91.5s of pure sleep in one exhausted ladder, before
516
+ // counting the 600s per-attempt timeout). The retry budget was never really
517
+ // about a COUNT -- it was about spanning a wall-clock outage window.
518
+ //
519
+ // So the ladder is split by error CLASS, and only the class that motivated the
520
+ // widening gets the long budget:
521
+ //
522
+ // * SPAWN OUTAGE (`fork/exec ...`, "Not enough memory resources") -- the OS
523
+ // refused to start git.exe at all. Retried against a WALL-CLOCK budget
524
+ // (DOLT_SPAWN_OUTAGE_BUDGET_MS, 3 min, matching the measured 1-3 min
525
+ // window) with the 30s backoff cap. The bound is elapsed time, so it is
526
+ // the same 3 minutes whether each attempt returns instantly or sits on a
527
+ // long timeout -- the old count-based bound multiplied out to a worst case
528
+ // of 9 attempts x the 600s step timeout.
529
+ // * EVERY OTHER TRANSIENT (network blip, busy server, held row lock) keeps
530
+ // the short ladder it always had before the widening: 5 retries, 8s cap.
531
+ // These were never the failure the long budget was bought for, and giving
532
+ // them the long one is exactly what caused the suite regression.
533
+ //
534
+ // `maxTransientRetries` still bounds the generic class and is still honored
535
+ // when a caller passes it explicitly, so every existing test seam keeps
536
+ // working; only the DEFAULT drops back from 8 to the pre-widening 5.
537
+ //
538
+ // ROUND-3 CORRECTION (dolt sync budget review round 3, item 4): "honored when
539
+ // passed explicitly" now applies to BOTH classes. The round-2 cut let an
540
+ // explicit `maxTransientRetries` cap only the generic ladder while the
541
+ // spawn-outage ladder ignored it and always ran to its own wall-clock budget
542
+ // and 30-attempt backstop -- a caller asking for a tight bound could still sit
543
+ // in a 3-minute retry loop. An explicit value is now a hard attempt cap on the
544
+ // spawn-outage ladder too (min(explicit, DOLT_SPAWN_OUTAGE_MAX_RETRIES), with
545
+ // the wall-clock budget still applying on top). Left UNSPECIFIED -- the
546
+ // production default, since no runner call site passes it -- the spawn-outage
547
+ // class keeps the full wall-clock budget; the "hard attempt backstop" below is
548
+ // then the only count in play. runDoltStep() therefore distinguishes "not
549
+ // passed" (undefined) from "passed", which is why the bracket entry points no
550
+ // longer fill in the default themselves.
551
+ //
552
+ // ROUND-2 CORRECTION (dolt sync budget review round 2, item 3): the first cut
553
+ // of this split set the generic default to 2, describing it as "the ladder it
554
+ // always had before the widening". That was wrong -- `git show 3f49419b`
555
+ // (bump D-pull/D-push transient-retry budget from 1 to 5) shows the
556
+ // pre-widening default was 5 (~15.5s of backoff), not 2 (~1.5s). The suite
557
+ // regression that motivated the reduction came from the SPAWN-OUTAGE class's
558
+ // 3-minute wall-clock budget, a test-fixture problem (fixtures sleeping
559
+ // through real backoff), not from this ladder -- so the generic class is back
560
+ // at 5 and any slow test injects its own `sleep`/`backoffBaseMs` instead.
240
561
  const DOLT_BACKOFF_BASE_MS = 500;
241
562
  const DOLT_BACKOFF_MAX_MS = 30000;
242
563
 
564
+ /** Backoff cap for the ordinary transient class -- the pre-widening value. */
565
+ const DOLT_GENERIC_BACKOFF_MAX_MS = 8000;
566
+
567
+ /** Retry count for the ordinary transient class (the default for
568
+ * `maxTransientRetries`). The pre-widening baseline -- see the note above,
569
+ * including why the round-1 value of 2 was a mis-restoration. */
570
+ export const DOLT_GENERIC_TRANSIENT_MAX_RETRIES = 5;
571
+
572
+ /** Total wall-clock retry budget for the spawn-outage class, sized to the
573
+ * measured 1-3 minute Windows git.exe spawn outage with headroom. */
574
+ export const DOLT_SPAWN_OUTAGE_BUDGET_MS = 180000;
575
+
576
+ /** Hard attempt backstop for the spawn-outage ladder. The real bound is the
577
+ * wall-clock budget above (~10 retries at the 30s cap); this only keeps a
578
+ * non-advancing clock from spinning. */
579
+ const DOLT_SPAWN_OUTAGE_MAX_RETRIES = 30;
580
+
581
+ /** The spawn-outage class: the OS refused to START the git subprocess, as
582
+ * opposed to anything that happened once it was running. Deliberately broad
583
+ * on the `fork/exec` line: any process-spawn refusal is the same class
584
+ * regardless of the OS's phrasing for why it refused.
585
+ *
586
+ * Exactly ONE pattern, on purpose (dolt sync budget review round 3, item
587
+ * 5). An earlier cut also matched the Windows wording "Not enough memory
588
+ * resources" on its own, but that pattern was dead: isSpawnOutageFailure()
589
+ * only runs on a failure the 'dolt' provider already classified 'transient',
590
+ * and that provider's TRANSIENT table carries `fork/exec ` and NOT the
591
+ * memory-resources wording -- so a text with the wording but no fork/exec
592
+ * line classifies 'unknown', is never retried, and never reaches this
593
+ * check. It is also redundant in practice: Go's os/exec formats every spawn
594
+ * refusal as `fork/exec <path>: <os error>`, so the live incident text
595
+ * (test/dolt-remote-unreachable.test.mjs) always carries both halves on
596
+ * the same line. Matching fork/exec alone is therefore complete for the
597
+ * class, and this list stays in lock-step with what can actually arrive. */
598
+ const DOLT_SPAWN_OUTAGE_PATTERNS = [
599
+ /fork\/exec /i,
600
+ ];
601
+
602
+ /**
603
+ * Is this failure text the spawn-outage class that earns the long wall-clock
604
+ * retry budget? Callers must already have classified the failure as
605
+ * 'transient'; this only sub-classifies WITHIN that verdict and never widens
606
+ * what counts as retryable (see DOLT_SPAWN_OUTAGE_PATTERNS for why the list
607
+ * must not carry a pattern the provider's TRANSIENT table cannot deliver).
608
+ *
609
+ * @param {string} output - raw stderr/stdout of the failed command
610
+ * @returns {boolean}
611
+ */
612
+ export function isSpawnOutageFailure(output) {
613
+ const text = String(output == null ? '' : output);
614
+ return DOLT_SPAWN_OUTAGE_PATTERNS.some((re) => re.test(text));
615
+ }
616
+
243
617
  // apra-fleet-jxdf.2: every `bd dolt pull`/`bd dolt push` this module issues
244
618
  // used to inherit whatever generic default the injected command() primitive
245
619
  // falls back to when no timeout is specified (120s, sized for an ordinary
@@ -301,24 +675,59 @@ const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
301
675
  *
302
676
  * @returns {Promise<{ ok: boolean, output: string, error: string|null, kind?: 'no-remote'|'empty-remote'|'remote-unreachable'|'diverged'|'auth'|'transient'|'unknown' }>}
303
677
  */
304
- async function runDoltStep({ command, member, cmd, label, log, maxTransientRetries, onAuthFailure, sleep = defaultSleep, backoffBaseMs = DOLT_BACKOFF_BASE_MS, timeoutS = DOLT_STEP_TIMEOUT_S }) {
678
+ async function runDoltStep({ command, member, cmd, label, log, maxTransientRetries, onAuthFailure, sleep = defaultSleep, backoffBaseMs = DOLT_BACKOFF_BASE_MS, timeoutS = DOLT_STEP_TIMEOUT_S, spawnOutageBudgetMs = DOLT_SPAWN_OUTAGE_BUDGET_MS, now = Date.now }) {
305
679
  let attempt = 0;
306
680
  let authHealAttempted = false;
681
+ const startedAt = now();
682
+ // An explicitly passed `maxTransientRetries` caps BOTH ladders (see the
683
+ // ROUND-3 CORRECTION in the constants block); left undefined, the generic
684
+ // class gets its default and the spawn-outage class keeps its own
685
+ // backstop, bounded by wall clock.
686
+ const explicitRetryCap = maxTransientRetries !== undefined && maxTransientRetries !== null;
687
+ const genericMaxRetries = explicitRetryCap ? Number(maxTransientRetries) : DOLT_GENERIC_TRANSIENT_MAX_RETRIES;
688
+ const spawnOutageMaxRetries = explicitRetryCap
689
+ ? Math.min(Number(maxTransientRetries), DOLT_SPAWN_OUTAGE_MAX_RETRIES)
690
+ : DOLT_SPAWN_OUTAGE_MAX_RETRIES;
307
691
  // eslint-disable-next-line no-constant-condition
308
692
  while (true) {
309
693
  const res = await command(cmd, { member_name: member, silent: true, failSoft: true, label, timeout_s: timeoutS });
310
694
  if (res && res.ok) return res;
311
695
  const error = res ? res.error : 'unknown command failure';
312
696
  const kind = classifyDoltFailure(error);
313
- if (kind === 'transient' && attempt < maxTransientRetries) {
314
- attempt += 1;
315
- const delayMs = doltBackoffDelayMs(attempt, backoffBaseMs);
316
- log(`[Dolt] transient failure for member '${member}' (${label}); retry ${attempt}/${maxTransientRetries} after ${delayMs}ms backoff: ${error}`);
317
- if (delayMs > 0 && typeof sleep === 'function') await sleep(delayMs);
318
- continue;
697
+ if (kind === 'transient') {
698
+ // Sub-classify WITHIN the transient verdict: only the spawn-outage
699
+ // class gets the long wall-clock budget (see the constants block
700
+ // above for why the count-based ladder was replaced).
701
+ if (isSpawnOutageFailure(error)) {
702
+ const elapsedMs = now() - startedAt;
703
+ // The attempt ceiling is a backstop, not the policy: at the 30s
704
+ // backoff cap a 3-minute budget spends itself in ~10 retries, so
705
+ // this can only ever fire if the injected clock does not
706
+ // advance. It exists so a broken clock degrades to the old
707
+ // bounded ladder rather than spinning forever.
708
+ if (elapsedMs < spawnOutageBudgetMs && attempt < spawnOutageMaxRetries) {
709
+ attempt += 1;
710
+ const delayMs = doltBackoffDelayMs(attempt, backoffBaseMs, DOLT_BACKOFF_MAX_MS);
711
+ log(`[Dolt] transient SPAWN-OUTAGE failure for member '${member}' (${label}); retry ${attempt} after ${delayMs}ms backoff (${Math.round(elapsedMs / 1000)}s of a ${Math.round(spawnOutageBudgetMs / 1000)}s wall-clock budget used${explicitRetryCap ? `, capped at ${spawnOutageMaxRetries} retries by the caller` : ''}): ${error}`);
712
+ if (delayMs > 0 && typeof sleep === 'function') await sleep(delayMs);
713
+ continue;
714
+ }
715
+ log(`[Dolt] spawn-outage retry budget (${Math.round(spawnOutageBudgetMs / 1000)}s wall clock, ${spawnOutageMaxRetries} retries max) EXHAUSTED for member '${member}' (${label}) after ${attempt} retries; giving up: ${error}`);
716
+ } else if (attempt < genericMaxRetries) {
717
+ attempt += 1;
718
+ const delayMs = doltBackoffDelayMs(attempt, backoffBaseMs, DOLT_GENERIC_BACKOFF_MAX_MS);
719
+ log(`[Dolt] transient failure for member '${member}' (${label}); retry ${attempt}/${genericMaxRetries} after ${delayMs}ms backoff: ${error}`);
720
+ if (delayMs > 0 && typeof sleep === 'function') await sleep(delayMs);
721
+ continue;
722
+ }
319
723
  }
320
724
  if ((kind === 'auth' || kind === 'unknown') && typeof onAuthFailure === 'function' && !authHealAttempted) {
321
725
  authHealAttempted = true;
726
+ // Re-provisioning a member's VCS auth can rewire its remote, so
727
+ // neither memo may survive a self-heal: the sync.remote answer AND
728
+ // the remote-tip fingerprint minted against it (round 3, item 6 --
729
+ // this used to drop only the former, unlike repair()).
730
+ forgetMemberSyncState(member);
322
731
  log(`[Dolt] ${kind} failure for member '${member}' (${label}); invoking self-heal (provision_vcs_auth) once before a single bounded retry: ${error}`);
323
732
  try {
324
733
  await onAuthFailure({ member, label, cmd, error, kind: 'dolt' });
@@ -339,8 +748,19 @@ async function runDoltStep({ command, member, cmd, label, log, maxTransientRetri
339
748
  // through, so a degraded read/write is always visible to whoever is
340
749
  // watching a live sprint -- independent of whether the caller treats
341
750
  // it as fatal.
751
+ //
752
+ // `selfHealed` reports whether the bounded one-shot auth self-heal
753
+ // above actually RAN TO COMPLETION for this step -- i.e. credentials
754
+ // were re-provisioned and the command was then retried and STILL
755
+ // failed. It is deliberately false on the `catch (healErr)` path
756
+ // above (that returns early): a self-heal that THREW never
757
+ // re-provisioned anything, so a credential problem remains a live
758
+ // explanation there. Callers use this to tell "the credentials are
759
+ // stale" apart from "the credentials were just refreshed and the
760
+ // failure text is lying" -- see doltPushGuarded's post-reconcile
761
+ // re-push branch.
342
762
  log(`[Dolt] ${label} FAILED (${kind}) -- reads/writes for member '${member}' may be stale until this is resolved. Raw: ${error}`);
343
- return { ok: false, output: res ? res.output : '', error, kind };
763
+ return { ok: false, output: res ? res.output : '', error, kind, selfHealed: authHealAttempted };
344
764
  }
345
765
  }
346
766
 
@@ -363,7 +783,14 @@ async function runDoltStep({ command, member, cmd, label, log, maxTransientRetri
363
783
  * is never suppressed. Override the check with
364
784
  * `opts.checkSyncRemoteConfigured` (same test hook doltPushAfter exposes).
365
785
  *
366
- * Two distinct benign no-op skips return `{ ok: true, skipped: true }` rather
786
+ * A further benign skip is the REMOTE-TIP FINGERPRINT: `reason:
787
+ * 'remote-unchanged'` means `git ls-remote <sync.remote> refs/dolt/data`
788
+ * returned the exact SHA this member last synchronized to, so the pull is a
789
+ * provable no-op and is not spawned. See the section comment above this
790
+ * function for the correctness argument and the fail-open rules; disable it
791
+ * with `opts.remoteTipFingerprint: false`.
792
+ *
793
+ * Two further benign no-op skips return `{ ok: true, skipped: true }` rather
367
794
  * than throwing: `reason: 'no-remote'` (no dolt remote configured -- nothing
368
795
  * to pull) and `reason: 'empty-remote'` (a configured remote that has never
369
796
  * had anything pushed into it, i.e. Dolt's "no branches found in remote"
@@ -378,7 +805,7 @@ async function runDoltStep({ command, member, cmd, label, log, maxTransientRetri
378
805
  *
379
806
  * @param {string} member
380
807
  * @param {{ command: Function, log?: Function, maxTransientRetries?: number, checkSyncRemoteConfigured?: Function, skipPull?: boolean, onAuthFailure?: Function }} opts
381
- * @returns {Promise<{ ok: true, member: string, skipped?: true, reason?: 'no-remote'|'empty-remote'|'already-fresh' }>}
808
+ * @returns {Promise<{ ok: true, member: string, skipped?: true, reason?: 'no-remote'|'empty-remote'|'already-fresh'|'remote-unchanged' }>}
382
809
  */
383
810
  /**
384
811
  * Invoke the injected settle callback at a divergence terminal, if one is
@@ -414,8 +841,379 @@ async function attemptSettle({ settle, member, operation, error, log }) {
414
841
  return null;
415
842
  }
416
843
 
844
+ // ---------------------------------------------------------------------------
845
+ // Remote-tip fingerprint: skip a D-pull only when the remote provably has not
846
+ // moved (dolt sync budget review, section B.1)
847
+ // ---------------------------------------------------------------------------
848
+ //
849
+ // THE CORRECTNESS ANCHOR. The shared remote's `refs/dolt/data` ref is the ONLY
850
+ // channel through which beads state moves between machines. A member's clone
851
+ // can therefore be stale in exactly one way: that ref advanced since the member
852
+ // last pulled or pushed. "Is a D-pull needed?" is then a question with a cheap,
853
+ // EXACT answer -- compare the remote SHA now against the SHA this member last
854
+ // synchronized to -- rather than a policy bet about who else might be writing.
855
+ // That is why this supersedes the role-based and time-based skip policies that
856
+ // were considered: those trade real staleness for speed (a reviewer reading
857
+ // acceptance criteria a remote doer just pushed is the exact false-FAILED-streak
858
+ // failure the post-streak verify pull exists to prevent), whereas a tip-equal
859
+ // skip removes only pulls that are provably no-ops.
860
+ //
861
+ // The probe is `git ls-remote <sync.remote> refs/dolt/data`: one network round
862
+ // trip, no Dolt engine startup, no 548MB chunk store to open (~0.35s measured,
863
+ // against multi-minute real pulls).
864
+ //
865
+ // THE RECORDED TIP is minted in exactly ONE place, and only ever from a value
866
+ // this member's clone is PROVABLY current with:
867
+ // * after a successful PULL, record the SHA observed IMMEDIATELY BEFORE the
868
+ // pull -- never one read afterwards. A push racing in during the pull then
869
+ // simply forces the NEXT pull to be real, which is the safe error.
870
+ // * after a successful PUSH by this member, FORGET the recorded tip. A push
871
+ // never records anything -- see the block below for why.
872
+ //
873
+ // WHY A PUSH CANNOT MINT A FINGERPRINT (dolt sync budget review round 3,
874
+ // item 1 -- the correct redesign of two earlier attempts):
875
+ //
876
+ // Attempt 1 recorded the remote SHA read AFTER the push, "still under the
877
+ // push mutex". Attempt 2 read it before AND after, and recorded the post-push
878
+ // SHA only when the ref had advanced ("it advanced, so I must have moved
879
+ // it"). Both are wrong for the same reason: the push mutex serializes THIS
880
+ // FLEET's pushes against each other and nothing else. Any unrelated machine
881
+ // can push to the same shared remote in the gap between this member's push
882
+ // completing and its post-push `git ls-remote` returning. The post-push read
883
+ // then observes a stranger's newer commit that this clone has never seen,
884
+ // records it as "my lastSyncedTip", and the very next D-pull is wrongly
885
+ // skipped -- exactly the staleness this feature exists to prevent. A network
886
+ // read of "the remote's current tip" is NEVER a proxy for "what my push
887
+ // published".
888
+ //
889
+ // The obvious local alternative -- record this clone's own commit SHA, the
890
+ // thing a fast-forward push makes the remote ref equal to -- does not exist
891
+ // for THIS transport. bd's git-backed remote (`git+https://...`) is Dolt's
892
+ // git blobstore: a push wraps the chunk-store manifest in a FRESH git commit,
893
+ // built inside the push on top of the remote head it just fetched, and
894
+ // publishes it with a lease. That commit (and so the remote's new
895
+ // refs/dolt/data SHA) is minted by the push itself, is not a function of
896
+ // local Dolt state, is not printed by `bd dolt push` ("Pushing to Dolt
897
+ // remote... / Push complete." either way), and lands locally only in a
898
+ // per-process UUID-named ref (refs/dolt/blobstore/<remote>/dolt/data/<uuid>)
899
+ // inside a sha256-named cache dir under .beads/ -- reachable only by a
900
+ // shell-dialect-specific filesystem scan on the member, which is exactly the
901
+ // kind of doubt this module refuses to turn into a skip. (Verified against a
902
+ // live clone: the cache repo's tracking refs and FETCH_HEAD already disagreed
903
+ // with the remote's live tip, and no stable local ref names the pushed SHA.)
904
+ //
905
+ // So a successful push FORGETS the fingerprint. The remote is now at a SHA
906
+ // this module cannot know; the pusher's next D-pull runs one real pull (after
907
+ // one ls-remote that re-arms the skip for the pulls after it). That is the
908
+ // conservative direction by construction: a redundant pull is the safe
909
+ // error, a skipped needed pull is not. A NO-OP push (nothing local to
910
+ // publish) is indistinguishable from a real one at this layer and is treated
911
+ // the same way -- it proves nothing about the clone's freshness, so it may
912
+ // not keep a fingerprint either. As a side effect no `git ls-remote` is
913
+ // issued anywhere in the D-push bracket any more (round 3, item 3): the
914
+ // mutex hold is now exactly push + reconcile + settle.
915
+ //
916
+ // FAIL-OPEN, ALWAYS. Every uncertainty -- no recorded tip yet, ls-remote failed
917
+ // or timed out, unparseable output, a sync.remote that could not be positively
918
+ // read, a URL outside the strict safe charset -- falls through to a REAL pull.
919
+ // The skip is only ever taken on a positive SHA match. There is deliberately no
920
+ // path in which doubt produces a skip.
921
+
922
+ /** member -> { sha, url }: the remote refs/dolt/data SHA this member is known
923
+ * to be current with, and the ls-remote URL it was observed at. Bound to the
924
+ * URL so a fingerprint can never validate a skip against a remote other than
925
+ * the one it was minted from (round 4 -- an agent-side `bd config set
926
+ * sync.remote` is the one reset a surviving fingerprint would otherwise get
927
+ * wrong; see noteMemberDispatchCompleted). Process-lifetime, same scope as
928
+ * the sync.remote memo. */
929
+ const lastSyncedTips = new Map();
930
+
931
+ /** Short timeout for the tip probe: it is one ls-remote round trip, and must
932
+ * never inherit the 600s budget sized for a real Dolt sync -- a probe that
933
+ * hangs has to fall through to the real pull quickly, not stall the bracket. */
934
+ const DOLT_TIP_PROBE_TIMEOUT_S = 30;
935
+
936
+ /** The ref every `bd dolt push` advances on a git-transport Dolt remote. */
937
+ const DOLT_DATA_REF = 'refs/dolt/data';
938
+
939
+ /** Never let the probe wait on a human (round-4 review, finding 2). The
940
+ * probe URL carries no userinfo (see toGitLsRemoteUrl), so on a member
941
+ * whose only credential for the host is the one embedded in sync.remote
942
+ * git would otherwise try to PROMPT: on a Windows member Git Credential
943
+ * Manager can block on a dialog until the 30s probe timeout, on every
944
+ * bracket. `credential.interactive=never` is GCM's own no-UI switch;
945
+ * `core.askPass=` (empty) disables any askpass program, so with no terminal
946
+ * attached git fails immediately instead of waiting. Passed as `-c` config
947
+ * because the command string must not rely on shell-level env assignment
948
+ * (the member's shell may be PowerShell). */
949
+ const GIT_NO_PROMPT_FLAGS = '-c credential.interactive=never -c core.askPass=';
950
+
951
+ /** After this many CONSECUTIVE failed probes a member's probe is disabled
952
+ * for the process (cleared by the hard seams): a member that cannot
953
+ * authenticate ls-remote, or whose sync.remote is a Dolt-native remote git
954
+ * cannot list, would otherwise pay a failed round trip on every bracket.
955
+ * Two, not one, so a single network blip does not cost the feature. */
956
+ export const DOLT_TIP_PROBE_MAX_CONSECUTIVE_FAILURES = 2;
957
+
958
+ /** member -> consecutive probe failures (a success resets to 0). */
959
+ const tipProbeFailures = new Map();
960
+
961
+ /**
962
+ * Is `member`'s remote-tip probe currently disabled by the failure latch?
963
+ * @param {string} member
964
+ * @returns {boolean}
965
+ */
966
+ export function isTipProbeDisabled(member) {
967
+ return (tipProbeFailures.get(member) || 0) >= DOLT_TIP_PROBE_MAX_CONSECUTIVE_FAILURES;
968
+ }
969
+
970
+ /**
971
+ * Reset the probe failure latch for `member` (or every member -- test
972
+ * hygiene, alongside invalidateSyncRemoteCache() / clearLastSyncedTip()).
973
+ * @param {string} [member]
974
+ * @returns {number} how many entries were dropped
975
+ */
976
+ export function clearTipProbeFailures(member) {
977
+ if (member === undefined) {
978
+ const n = tipProbeFailures.size;
979
+ tipProbeFailures.clear();
980
+ return n;
981
+ }
982
+ return tipProbeFailures.delete(member) ? 1 : 0;
983
+ }
984
+
985
+ /**
986
+ * Strict safe-charset URL gate. The probe command string is handed to the
987
+ * member's own shell, which may be PowerShell OR a POSIX shell, so rather than
988
+ * trying to quote correctly for both this REFUSES any remote URL containing a
989
+ * character outside a conservative set (no whitespace, no quote, no shell
990
+ * metacharacter of either dialect). A rejected URL yields no fingerprint and a
991
+ * real pull -- the safe direction.
992
+ */
993
+ const SAFE_REMOTE_URL_RE = /^[A-Za-z0-9._~:/@+-]+$/;
994
+
995
+ /** A URL with an explicit scheme (`https://`, `ssh://`, `file://`, ...). */
996
+ const URL_SCHEME_RE = /^[a-z][a-z0-9+.-]*:\/\//i;
997
+
998
+ /** The userinfo (`user@` or `user:password@`) of an http(s) URL. */
999
+ const HTTP_USERINFO_RE = /^(https?:\/\/)[^/@]*@/i;
1000
+
1001
+ /**
1002
+ * Convert a bd `sync.remote` value into the URL `git ls-remote` should be
1003
+ * pointed at, or null when it cannot be used safely.
1004
+ *
1005
+ * bd spells a git-transport Dolt remote `git+https://host/org/repo.git`; the
1006
+ * `git+` scheme prefix is bd's own marker and is NOT part of the git URL, so it
1007
+ * is stripped. Anything failing the safe-charset gate returns null.
1008
+ *
1009
+ * NOTE: this deliberately derives the probe target from sync.remote and NEVER
1010
+ * from git's `origin`. The two can legitimately differ on a member, and probing
1011
+ * origin would compare this member's freshness against the wrong ref.
1012
+ *
1013
+ * SCHEME REQUIRED (round 4, fix A). sync.remote may legitimately hold a bare
1014
+ * Dolt remote NAME (`origin` -- the integration fixtures set exactly that),
1015
+ * which passes the charset gate but is not a URL at all: handed to
1016
+ * `git ls-remote origin` it silently resolves against GIT'S OWN origin, the
1017
+ * very thing the note above forbids. A scheme-less value -- a remote name,
1018
+ * or a bare filesystem path (a Dolt file remote, never a git repository) --
1019
+ * therefore yields null: no fingerprint, a real pull.
1020
+ *
1021
+ * USERINFO STRIPPED (round 4, fix B). The probe string is journaled VERBATIM
1022
+ * as a persisted, dashboard-visible command record (the workflow's command()
1023
+ * records the command text; `silent` only suppresses the console line). A
1024
+ * sync.remote of the shape `git+https://x-access-token:ghp_...@host/...`
1025
+ * would bake that token into the record, whereas before this feature it only
1026
+ * ever appeared as command OUTPUT. So an http(s) userinfo is removed before
1027
+ * the URL becomes part of any command. The stripped URL still authenticates:
1028
+ * every provisioned member carries a git credential helper for its VCS host
1029
+ * (provision_vcs_auth writes it; that is how `git push` works on members
1030
+ * today), and a member whose ONLY credential was the embedded userinfo gets
1031
+ * a failed probe, which is the fail-open real pull, not a wrong skip. ssh
1032
+ * URLs keep their userinfo: `git@` is the login name, not a secret.
1033
+ *
1034
+ * @param {string|null|undefined} syncRemote
1035
+ * @returns {string|null}
1036
+ */
1037
+ export function toGitLsRemoteUrl(syncRemote) {
1038
+ if (typeof syncRemote !== 'string') return null;
1039
+ const trimmed = syncRemote.trim();
1040
+ if (trimmed.length === 0) return null;
1041
+ let url = trimmed.startsWith('git+') ? trimmed.slice(4) : trimmed;
1042
+ if (url.length === 0) return null;
1043
+ if (!URL_SCHEME_RE.test(url)) return null;
1044
+ url = url.replace(HTTP_USERINFO_RE, '$1');
1045
+ if (!SAFE_REMOTE_URL_RE.test(url)) return null;
1046
+ return url;
1047
+ }
1048
+
1049
+ /**
1050
+ * Parse `git ls-remote` output for the refs/dolt/data SHA. Output lines are
1051
+ * `<sha>\t<ref>`. Returns null on anything unrecognized -- an empty result, a
1052
+ * malformed line, or a ref that is not exactly refs/dolt/data -- so the caller
1053
+ * falls through to a real pull.
1054
+ *
1055
+ * @param {string|null|undefined} output
1056
+ * @returns {string|null}
1057
+ */
1058
+ export function parseLsRemoteTip(output) {
1059
+ const text = String(output == null ? '' : output);
1060
+ for (const line of text.split(/\r?\n/)) {
1061
+ const m = line.match(/^([0-9a-f]{7,64})\s+(\S+)\s*$/i);
1062
+ if (m && m[2] === DOLT_DATA_REF) return m[1].toLowerCase();
1063
+ }
1064
+ return null;
1065
+ }
1066
+
1067
+ /**
1068
+ * Read the shared remote's current refs/dolt/data SHA for `member`, via one
1069
+ * `git ls-remote` on that member. Never throws: any failure returns null and
1070
+ * the caller treats that as "unknown", i.e. do the real thing.
1071
+ *
1072
+ * @param {string} member
1073
+ * @param {{ command: Function, log?: Function, url: string }} ctx
1074
+ * @returns {Promise<string|null>}
1075
+ */
1076
+ async function readRemoteDoltTip(member, { command, log = () => {}, url }) {
1077
+ const sha = await readRemoteDoltTipOnce(member, { command, log, url });
1078
+ if (sha) {
1079
+ tipProbeFailures.delete(member);
1080
+ return sha;
1081
+ }
1082
+ const failures = (tipProbeFailures.get(member) || 0) + 1;
1083
+ tipProbeFailures.set(member, failures);
1084
+ if (failures === DOLT_TIP_PROBE_MAX_CONSECUTIVE_FAILURES) {
1085
+ log(`[Dolt] remote-tip probe for member '${member}' failed ${failures} times in a row; disabling the probe for this member for the rest of the run (every D-pull is real, as before the fingerprint existed).`);
1086
+ }
1087
+ return null;
1088
+ }
1089
+
1090
+ async function readRemoteDoltTipOnce(member, { command, log, url }) {
1091
+ let res;
1092
+ try {
1093
+ res = await command(`git ${GIT_NO_PROMPT_FLAGS} ls-remote ${url} ${DOLT_DATA_REF}`, {
1094
+ member_name: member,
1095
+ silent: true,
1096
+ failSoft: true,
1097
+ label: `Dolt remote-tip probe for '${member}'`,
1098
+ timeout_s: DOLT_TIP_PROBE_TIMEOUT_S,
1099
+ });
1100
+ } catch (err) {
1101
+ log(`[Dolt] remote-tip probe for member '${member}' threw (falling through to a real pull): ${(err && err.message) || err}`);
1102
+ return null;
1103
+ }
1104
+ if (!res || res.ok === false) {
1105
+ log(`[Dolt] remote-tip probe for member '${member}' failed (falling through to a real pull): ${res ? res.error : 'no result'}`);
1106
+ return null;
1107
+ }
1108
+ const sha = parseLsRemoteTip(typeof res === 'object' ? res.output : res);
1109
+ if (!sha) {
1110
+ log(`[Dolt] remote-tip probe for member '${member}' returned no parseable ${DOLT_DATA_REF} SHA (falling through to a real pull).`);
1111
+ return null;
1112
+ }
1113
+ return sha;
1114
+ }
1115
+
1116
+ /**
1117
+ * Resolve the ls-remote URL for `member` from the MEMOIZED sync.remote probe,
1118
+ * or null when it cannot be positively read / is not safely usable. Returns
1119
+ * null without probing when `command` is missing.
1120
+ *
1121
+ * @param {string} member
1122
+ * @param {{ command: Function, log?: Function }} ctx
1123
+ * @returns {Promise<string|null>}
1124
+ */
1125
+ async function resolveTipProbeUrl(member, { command, log }) {
1126
+ if (typeof command !== 'function') return null;
1127
+ if (isTipProbeDisabled(member)) return null;
1128
+ const { url } = await readMemberSyncRemote(member, { command, log });
1129
+ return toGitLsRemoteUrl(url);
1130
+ }
1131
+
1132
+ /**
1133
+ * The SHA `member` is currently known to be synchronized with, or undefined.
1134
+ * @param {string} member
1135
+ * @returns {string|undefined}
1136
+ */
1137
+ export function getLastSyncedTip(member) {
1138
+ const entry = lastSyncedTips.get(member);
1139
+ return entry ? entry.sha : undefined;
1140
+ }
1141
+
1142
+ /**
1143
+ * Record the SHA `member` is now synchronized with, observed at ls-remote
1144
+ * URL `url`. Both are required: a tip with no URL to bind it to is doubt,
1145
+ * and doubt never produces a skip, so it is not recorded at all. Exported for
1146
+ * the tests and for any future call site that learns the tip out of band.
1147
+ * @param {string} member
1148
+ * @param {string} sha
1149
+ * @param {string} url - the exact `git ls-remote` target the SHA was read at
1150
+ */
1151
+ export function setLastSyncedTip(member, sha, url) {
1152
+ if (typeof sha !== 'string' || sha.length === 0) return;
1153
+ if (typeof url !== 'string' || url.length === 0) return;
1154
+ lastSyncedTips.set(member, { sha, url });
1155
+ }
1156
+
1157
+ /**
1158
+ * Decide whether `member`'s D-pull may be skipped: the observed remote tip
1159
+ * must equal the recorded one, at the same URL -- and if the member has been
1160
+ * dispatched to since its sync.remote memo was last positively read, that
1161
+ * memo is re-read FIRST and must still name the same URL. See
1162
+ * noteMemberDispatchCompleted for the reasoning.
1163
+ *
1164
+ * @param {string} member
1165
+ * @param {{ observedTip: string, probeUrl: string, command: Function, log: Function }} ctx
1166
+ * @returns {Promise<{ skip: boolean, reason?: 'remote-unchanged'|'no-remote', recordable: boolean }>}
1167
+ * `recordable` is false when the probe turned out to target the wrong
1168
+ * remote, so the caller must not mint a fingerprint from `observedTip`
1169
+ * after its pull. `reason: 'no-remote'` means the re-read found sync.remote
1170
+ * positively ABSENT: the pre-gate's own contract then applies (no `bd dolt`
1171
+ * command may be issued against a neutralized clone), so the caller takes
1172
+ * the no-remote exit rather than a real pull.
1173
+ */
1174
+ async function confirmSkipAfterDispatch(member, { observedTip, probeUrl, command, log }) {
1175
+ const recorded = lastSyncedTips.get(member);
1176
+ if (!recorded || recorded.sha !== observedTip || recorded.url !== probeUrl) {
1177
+ return { skip: false, recordable: true };
1178
+ }
1179
+ if (!dispatchedSinceVerified.has(member)) return { skip: true, reason: 'remote-unchanged', recordable: true };
1180
+ const fresh = await readMemberSyncRemote(member, { command, log, verify: true });
1181
+ if (!fresh.positive) {
1182
+ log(`[Dolt] D-pull for member '${member}': remote tip matches the recorded fingerprint, but sync.remote could not be re-read after a dispatch to this member -- pulling for real rather than skipping on an unconfirmed remote.`);
1183
+ return { skip: false, recordable: true };
1184
+ }
1185
+ if (!fresh.configured) {
1186
+ log(`[Dolt] D-pull for member '${member}': sync.remote was neutralized under a dispatch; forgetting the fingerprint -- no pull command issued`);
1187
+ clearLastSyncedTip(member);
1188
+ return { skip: true, reason: 'no-remote', recordable: false };
1189
+ }
1190
+ const freshUrl = toGitLsRemoteUrl(fresh.url);
1191
+ if (freshUrl === probeUrl) return { skip: true, reason: 'remote-unchanged', recordable: true };
1192
+ log(`[Dolt] D-pull for member '${member}': sync.remote changed under a dispatch (fingerprint was minted against a different remote); forgetting the fingerprint and pulling for real.`);
1193
+ clearLastSyncedTip(member);
1194
+ return { skip: false, recordable: false };
1195
+ }
1196
+
1197
+ /**
1198
+ * Forget `member`'s recorded tip (or every member's -- test hygiene). A
1199
+ * forgotten tip means the next D-pull is real, never skipped.
1200
+ * @param {string} [member]
1201
+ * @returns {number} how many entries were dropped
1202
+ */
1203
+ export function clearLastSyncedTip(member) {
1204
+ if (member === undefined) {
1205
+ const n = lastSyncedTips.size;
1206
+ lastSyncedTips.clear();
1207
+ return n;
1208
+ }
1209
+ return lastSyncedTips.delete(member) ? 1 : 0;
1210
+ }
1211
+
417
1212
  export async function doltPullBefore(member, opts = {}) {
418
- const { command, log = () => {}, maxTransientRetries = 8, checkSyncRemoteConfigured, skipPull = false, onAuthFailure, sleep, backoffBaseMs, timeoutS, settle } = opts;
1213
+ // `maxTransientRetries` is deliberately NOT defaulted here: runDoltStep()
1214
+ // must see whether the caller passed it (an explicit value caps both
1215
+ // retry ladders; undefined selects each ladder's own default).
1216
+ const { command, log = () => {}, maxTransientRetries, checkSyncRemoteConfigured, skipPull = false, onAuthFailure, sleep, backoffBaseMs, timeoutS, settle, remoteTipFingerprint = true, spawnOutageBudgetMs, now } = opts;
419
1217
  if (typeof command !== 'function') {
420
1218
  throw new Error("doltPullBefore requires an injected command() in opts");
421
1219
  }
@@ -436,9 +1234,32 @@ export async function doltPullBefore(member, opts = {}) {
436
1234
  return { ok: true, member, skipped: true, reason: 'already-fresh' };
437
1235
  }
438
1236
 
1237
+ // Remote-tip fingerprint (see the section comment above doltPullBefore).
1238
+ // `observedTip` is the SHA read BEFORE the pull; it is only committed to
1239
+ // lastSyncedTips once the pull below actually succeeds.
1240
+ let observedTip = null;
1241
+ let probeUrl = null;
1242
+ if (remoteTipFingerprint) {
1243
+ probeUrl = await resolveTipProbeUrl(member, { command, log });
1244
+ if (probeUrl) {
1245
+ observedTip = await readRemoteDoltTip(member, { command, log, url: probeUrl });
1246
+ if (observedTip) {
1247
+ const verdict = await confirmSkipAfterDispatch(member, { observedTip, probeUrl, command, log });
1248
+ if (verdict.skip && verdict.reason === 'no-remote') {
1249
+ return { ok: true, member, skipped: true, reason: 'no-remote' };
1250
+ }
1251
+ if (verdict.skip) {
1252
+ log(`[Dolt] D-pull for member '${member}' skipped: remote ${DOLT_DATA_REF} is unchanged at ${observedTip} since this member last synchronized -- the shared remote is the only cross-machine channel, so the clone is provably current.`);
1253
+ return { ok: true, member, skipped: true, reason: 'remote-unchanged', remoteTip: observedTip };
1254
+ }
1255
+ if (!verdict.recordable) observedTip = null;
1256
+ }
1257
+ }
1258
+ }
1259
+
439
1260
  const pull = await runDoltStep({
440
1261
  command, member, cmd: 'bd dolt pull',
441
- label: `D-pull for '${member}'`, log, maxTransientRetries, onAuthFailure, sleep, backoffBaseMs, timeoutS,
1262
+ label: `D-pull for '${member}'`, log, maxTransientRetries, onAuthFailure, sleep, backoffBaseMs, timeoutS, spawnOutageBudgetMs, now,
442
1263
  });
443
1264
  if (!pull.ok) {
444
1265
  if (pull.kind === 'no-remote') {
@@ -462,6 +1283,11 @@ export async function doltPullBefore(member, opts = {}) {
462
1283
  `[Dolt] D-pull for member '${member}' hit an unmergeable beads conflict and must not be auto-resolved by judgment: ${pull.error}`,
463
1284
  { member, doltOutput: pull.error, operation: 'pull' },
464
1285
  );
1286
+ // A divergence (and any settle that republishes to resolve it)
1287
+ // leaves this clone at a tip we did not observe -- forget the
1288
+ // recorded fingerprint so the next D-pull is unconditionally real
1289
+ // rather than skipped against a stale SHA.
1290
+ clearLastSyncedTip(member);
465
1291
  const settled = await attemptSettle({ settle, member, operation: 'D-pull', error: diverged, log });
466
1292
  if (settled) {
467
1293
  // settle ends with its own `bd dolt pull` + `bd dolt push`, so
@@ -494,6 +1320,13 @@ export async function doltPullBefore(member, opts = {}) {
494
1320
  );
495
1321
  }
496
1322
 
1323
+ // The pull landed, so this clone is current with the remote AS OF the SHA
1324
+ // read BEFORE it. Deliberately not a post-pull read: a push that raced in
1325
+ // during the pull is not included in what we just fetched, and recording
1326
+ // the later SHA would claim freshness this clone does not have. Recording
1327
+ // the earlier one can only cost one redundant future pull.
1328
+ if (observedTip && probeUrl) setLastSyncedTip(member, observedTip, probeUrl);
1329
+
497
1330
  return { ok: true, member };
498
1331
  }
499
1332
 
@@ -546,7 +1379,7 @@ export function extractConflictingTables(doltOutput) {
546
1379
  *
547
1380
  * @param {string} member
548
1381
  * @param {{ command: Function, log?: Function, maxTransientRetries?: number, checkSyncRemoteConfigured?: Function }} opts
549
- * @returns {Promise<{ ok: true, member: string, skipped?: true, reason?: 'no-remote'|'empty-remote'|'already-fresh' }>}
1382
+ * @returns {Promise<{ ok: true, member: string, skipped?: true, reason?: 'no-remote'|'empty-remote'|'already-fresh'|'remote-unchanged' }>}
550
1383
  */
551
1384
  export async function preflightBeadsHealthGate(member, opts = {}) {
552
1385
  const { command, log = () => {} } = opts;
@@ -618,6 +1451,11 @@ export async function preflightBeadsHealthGate(member, opts = {}) {
618
1451
  * (including the reconcile/re-push) -- see runDoltStep's AUTH SELF-HEAL
619
1452
  * CONTRACT.
620
1453
  *
1454
+ * REMOTE-TIP FINGERPRINT: a successful push (first attempt or the re-push
1455
+ * after the one reconcile) FORGETS this member's recorded tip and issues no
1456
+ * `git ls-remote` at all -- see "WHY A PUSH CANNOT MINT A FINGERPRINT" above
1457
+ * doltPullBefore. The pusher's next D-pull is therefore always real.
1458
+ *
621
1459
  * `opts.settle` is the optional deterministic conflict-settlement callback
622
1460
  * (buildSettleCallback, dolt-settle.mjs). When present, a divergence that
623
1461
  * outlives the bounded reconcile runs settle before the DoltDivergedError is
@@ -629,7 +1467,11 @@ export async function preflightBeadsHealthGate(member, opts = {}) {
629
1467
  * @returns {Promise<{ ok: true, member: string, pushed: boolean, reconciled: boolean, skipped?: true, reason?: 'no-remote', recovered?: true, settledTables?: string[] }>}
630
1468
  */
631
1469
  export async function doltPushAfter(member, opts = {}) {
632
- const { command, pushBeads = true, log = () => {}, maxTransientRetries = 8, mutex, sprintId, checkSyncRemoteConfigured, onAuthFailure, sleep, backoffBaseMs, timeoutS, settle, renewIntervalMs = DOLT_MUTEX_RENEW_INTERVAL_MS } = opts;
1470
+ // `maxTransientRetries` is deliberately NOT defaulted here -- see
1471
+ // doltPullBefore. `remoteTipFingerprint` is accepted for call-site parity
1472
+ // with doltPullBefore but has nothing to switch off on the push side any
1473
+ // more: a push never probes and never records (it only forgets).
1474
+ const { command, pushBeads = true, log = () => {}, maxTransientRetries, mutex, sprintId, checkSyncRemoteConfigured, onAuthFailure, sleep, backoffBaseMs, timeoutS, settle, renewIntervalMs = DOLT_MUTEX_RENEW_INTERVAL_MS, spawnOutageBudgetMs, now } = opts;
633
1475
  if (typeof command !== 'function') {
634
1476
  throw new Error("doltPushAfter requires an injected command() in opts");
635
1477
  }
@@ -713,6 +1555,10 @@ export async function doltPushAfter(member, opts = {}) {
713
1555
  // before returning. With no settle callback wired the behavior is
714
1556
  // unchanged: the DoltDivergedError propagates immediately.
715
1557
  async function surfaceDivergence(divergedError, operation) {
1558
+ // Either terminal leaves the remote at a SHA this member never
1559
+ // observed (settle republishes; an unrecovered divergence leaves the
1560
+ // clone wedged), so drop the fingerprint and force a real next pull.
1561
+ clearLastSyncedTip(member);
716
1562
  const settled = await attemptSettle({ settle, member, operation: `D-push (${operation})`, error: divergedError, log });
717
1563
  if (settled) {
718
1564
  return { ok: true, member, pushed: true, reconciled: true, recovered: true, settledTables: settled.resolvedTables || [] };
@@ -720,12 +1566,28 @@ export async function doltPushAfter(member, opts = {}) {
720
1566
  throw divergedError;
721
1567
  }
722
1568
 
1569
+ /**
1570
+ * A push landed. The remote's refs/dolt/data is now a SHA minted inside
1571
+ * the push that this module has no local, network-free way to learn (see
1572
+ * "WHY A PUSH CANNOT MINT A FINGERPRINT" above doltPullBefore), and any
1573
+ * post-push network read could observe an unrelated machine's later push
1574
+ * instead of ours. So the only correct bookkeeping is to FORGET whatever
1575
+ * fingerprint this member carried: the next D-pull is real. Local-only,
1576
+ * no command is issued.
1577
+ */
1578
+ function forgetTipAfterPush() {
1579
+ if (clearLastSyncedTip(member) > 0) {
1580
+ log(`[Dolt] D-push for member '${member}' landed; forgetting its remote-tip fingerprint (the remote is now at a SHA only the push knows) so the next D-pull is real.`);
1581
+ }
1582
+ }
1583
+
723
1584
  async function doltPushGuarded() {
724
1585
  let push = await runDoltStep({
725
1586
  command, member, cmd: 'bd dolt push',
726
- label: `D-push for '${member}'`, log, maxTransientRetries, onAuthFailure, sleep, backoffBaseMs, timeoutS,
1587
+ label: `D-push for '${member}'`, log, maxTransientRetries, onAuthFailure, sleep, backoffBaseMs, timeoutS, spawnOutageBudgetMs, now,
727
1588
  });
728
1589
  if (push.ok) {
1590
+ forgetTipAfterPush();
729
1591
  return { ok: true, member, pushed: true, reconciled: false };
730
1592
  }
731
1593
 
@@ -781,7 +1643,7 @@ export async function doltPushAfter(member, opts = {}) {
781
1643
  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).`);
782
1644
  const reconcile = await runDoltStep({
783
1645
  command, member, cmd: 'bd dolt pull',
784
- label: `D-push reconcile pull for '${member}'`, log, maxTransientRetries, onAuthFailure, sleep, backoffBaseMs, timeoutS,
1646
+ label: `D-push reconcile pull for '${member}'`, log, maxTransientRetries, onAuthFailure, sleep, backoffBaseMs, timeoutS, spawnOutageBudgetMs, now,
785
1647
  });
786
1648
  if (!reconcile.ok) {
787
1649
  if (reconcile.kind === 'diverged') {
@@ -801,23 +1663,105 @@ export async function doltPushAfter(member, opts = {}) {
801
1663
 
802
1664
  push = await runDoltStep({
803
1665
  command, member, cmd: 'bd dolt push',
804
- label: `D-push re-push after reconcile for '${member}'`, log, maxTransientRetries, onAuthFailure, sleep, backoffBaseMs, timeoutS,
1666
+ label: `D-push re-push after reconcile for '${member}'`, log, maxTransientRetries, onAuthFailure, sleep, backoffBaseMs, timeoutS, spawnOutageBudgetMs, now,
805
1667
  });
806
1668
  if (push.ok) {
1669
+ forgetTipAfterPush();
807
1670
  return { ok: true, member, pushed: true, reconciled: true };
808
1671
  }
809
1672
 
810
- if (push.kind === 'auth') {
1673
+ if (push.kind === 'auth' && !push.selfHealed) {
811
1674
  // apra-fleet-spp.3: same mislabel class as the first-push/pull paths,
812
1675
  // just reached via the post-reconcile re-push -- a credential that
813
1676
  // lapsed mid-reconcile is not a data divergence, so it must not be
814
1677
  // folded into DoltDivergedError below.
1678
+ //
1679
+ // Reached only when the bounded self-heal did NOT re-provision (no
1680
+ // onAuthFailure wired, or the self-heal itself threw). With no
1681
+ // evidence that the credentials were refreshed, a stale credential is
1682
+ // still the best explanation and this stays an auth terminal.
815
1683
  throw new DoltSyncError(
816
1684
  `[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}`,
817
1685
  { member, doltOutput: push.error, details: { kind: 'auth', operation: 'push-reconcile-repush' } },
818
1686
  );
819
1687
  }
820
1688
 
1689
+ if (push.kind === 'auth') {
1690
+ // AUTH-SHAPED BUT PROVABLY NOT AUTH (live 2026-09-11, fleet-lin-dev1).
1691
+ //
1692
+ // Reaching this line means ALL THREE of the following already
1693
+ // happened, in this order, against this same remote:
1694
+ // 1. the FIRST push was rejected non-fast-forward ('diverged') --
1695
+ // which is itself PROOF the remote authenticated this clone:
1696
+ // a remote cannot compare refs and reject a push it never let in;
1697
+ // 2. the bounded reconcile D-pull SUCCEEDED;
1698
+ // 3. the re-push failed auth-shaped, runDoltStep's one-shot
1699
+ // self-heal re-provisioned the credentials (`selfHealed`), and
1700
+ // the retry with the FRESH credentials failed identically.
1701
+ //
1702
+ // So the credentials are demonstrably fine and re-minting them again
1703
+ // cannot help. Dolt's chunk-upload phase ('addTableFiles,
1704
+ // updateManifestAddFiles') reports a stale/unfinished-reconcile push
1705
+ // with git's credential-prompt text ("could not read Username"),
1706
+ // which classifyDoltFailure -- correctly, in isolation -- reads as
1707
+ // auth. Treating it as auth here is what produced the observed
1708
+ // production pathology: the engine looped provision_vcs_auth (51
1709
+ // repeated failures across one run's logs, each reporting
1710
+ // "provision_vcs_auth succeeded" and then failing identically) and
1711
+ // terminated with the misleading "failed on VCS CREDENTIALS, not a
1712
+ // data divergence" reason, when the actual cause was a local Dolt
1713
+ // clone behind the remote that a plain pull-then-push cleared.
1714
+ //
1715
+ // Do NOT fix this by loosening the 'auth' patterns: each message
1716
+ // classifies correctly on its own, and widening them would regress
1717
+ // apra-fleet-spp (a real credential failure being read as
1718
+ // divergence). The signal is the SEQUENCE, so it is judged here.
1719
+ //
1720
+ // Remedy = the reconcile that did not finish: ONE more bounded
1721
+ // D-pull + re-push cycle, deliberately WITHOUT `onAuthFailure`, so
1722
+ // this path can never re-enter the credential-reprovision loop it
1723
+ // exists to break. Still bounded (two cycles total, never a loop),
1724
+ // keeping apra-fleet-417.3's first-successful-pusher-wins contract.
1725
+ log(`[Dolt] D-push re-push after reconcile for member '${member}' failed with auth-shaped text, but VCS credentials are provably NOT the cause: the first push's non-fast-forward rejection proves the remote authenticated this clone moments earlier, and the credentials have since been re-provisioned and still fail identically. Treating it as an unfinished reconcile (a local clone behind the remote) and running ONE more bounded D-pull + re-push, with credential self-heal disabled. Raw: ${push.error}`);
1726
+
1727
+ const secondReconcile = await runDoltStep({
1728
+ command, member, cmd: 'bd dolt pull',
1729
+ label: `D-push second reconcile pull for '${member}'`, log, maxTransientRetries, sleep, backoffBaseMs, timeoutS, spawnOutageBudgetMs, now,
1730
+ });
1731
+ if (!secondReconcile.ok) {
1732
+ if (secondReconcile.kind === 'diverged') {
1733
+ return await surfaceDivergence(
1734
+ new DoltDivergedError(
1735
+ `[Dolt] D-push second reconcile pull for member '${member}' hit an unmergeable beads conflict -- must not be retried blindly: ${secondReconcile.error}`,
1736
+ { member, doltOutput: secondReconcile.error, operation: 'push-reconcile' },
1737
+ ),
1738
+ 'push-reconcile',
1739
+ );
1740
+ }
1741
+ throw new DoltSyncError(
1742
+ `[Dolt] D-push second reconcile pull for member '${member}' failed: ${secondReconcile.error}`,
1743
+ { member, doltOutput: secondReconcile.error },
1744
+ );
1745
+ }
1746
+
1747
+ push = await runDoltStep({
1748
+ command, member, cmd: 'bd dolt push',
1749
+ label: `D-push second re-push after reconcile for '${member}'`, log, maxTransientRetries, sleep, backoffBaseMs, timeoutS, spawnOutageBudgetMs, now,
1750
+ });
1751
+ if (push.ok) {
1752
+ forgetTipAfterPush();
1753
+ return { ok: true, member, pushed: true, reconciled: true };
1754
+ }
1755
+
1756
+ return await surfaceDivergence(
1757
+ new DoltDivergedError(
1758
+ `[Dolt] D-push for member '${member}' still rejected after TWO bounded reconcile pulls -- refusing to retry further. The failure text names VCS credentials, but they were re-provisioned mid-ladder and the remote authenticated this clone earlier in the same ladder, so this is a stale/unmergeable clone, not a credential problem: ${push.error}`,
1759
+ { member, doltOutput: push.error, operation: 'push' },
1760
+ ),
1761
+ 'push',
1762
+ );
1763
+ }
1764
+
821
1765
  // Still rejected after the one bounded reconcile, and not an auth failure.
822
1766
  return await surfaceDivergence(
823
1767
  new DoltDivergedError(
@@ -852,8 +1796,8 @@ export async function doltPushAfter(member, opts = {}) {
852
1796
  //
853
1797
  // ok -- did the sync do what it was asked to do (a benign skip is ok)
854
1798
  // kind -- 'synced' | 'no-remote' | 'empty-remote' | 'already-fresh'
855
- // | 'diverged' | 'auth' | 'transient' | 'remote-unreachable'
856
- // | 'unknown'
1799
+ // | 'remote-unchanged' | 'diverged' | 'auth' | 'transient'
1800
+ // | 'remote-unreachable' | 'unknown'
857
1801
  // degraded -- true when the sync FAILED and the sprint is continuing anyway
858
1802
  // detail -- one human-readable line (the underlying error's message)
859
1803
  // error -- the underlying typed error, retained for later escalation
@@ -1137,16 +2081,19 @@ async function runDegradable(run, ctx) {
1137
2081
  */
1138
2082
  export async function syncBefore(member, opts = {}) {
1139
2083
  const { readinessGate = false, skipRefresh, fatal, onDegraded, healthGate, skipPull, ...rest } = opts;
2084
+ // Both renames (healthGate -> readinessGate, skipPull -> skipRefresh) came
2085
+ // from apra-fleet-417.5 (ADR Decision 2). The tracker id lives here, in a
2086
+ // comment, because the thrown messages below are runtime strings.
1140
2087
  if (healthGate !== undefined) {
1141
2088
  throw new Error(
1142
2089
  "DoltSync.syncBefore: opts.healthGate is retired -- pass opts.readinessGate instead " +
1143
- "(docs/adr-taskdb-backend-neutral-interface.md Decision 2, apra-fleet-417.5).",
2090
+ "(docs/adr-taskdb-backend-neutral-interface.md Decision 2).",
1144
2091
  );
1145
2092
  }
1146
2093
  if (skipPull !== undefined) {
1147
2094
  throw new Error(
1148
2095
  "DoltSync.syncBefore: opts.skipPull is retired -- pass opts.skipRefresh instead " +
1149
- "(docs/adr-taskdb-backend-neutral-interface.md Decision 2, apra-fleet-417.5).",
2096
+ "(docs/adr-taskdb-backend-neutral-interface.md Decision 2).",
1150
2097
  );
1151
2098
  }
1152
2099
  const adapterOpts = { ...rest, skipPull: skipRefresh };
@@ -1327,6 +2274,10 @@ export async function repair(member, opts = {}) {
1327
2274
  if (typeof command !== 'function') {
1328
2275
  return { repaired: false, escalation: 'not-configured: repair() requires an injected command() to run settle' };
1329
2276
  }
2277
+ // An operator/tool remediation can rewire this clone's remote and always
2278
+ // moves it off whatever tip we last observed, so drop both memos up front
2279
+ // (a repair must never be decided against, or leave behind, cached state).
2280
+ forgetMemberSyncState(member);
1330
2281
  const settle = typeof opts.settle === 'function'
1331
2282
  ? opts.settle
1332
2283
  : buildSettleCallback(member, { command, log, platform, arch, shell });
@@ -1356,6 +2307,19 @@ export const DoltSync = {
1356
2307
  capabilities,
1357
2308
  getDegradedSyncRecords,
1358
2309
  clearDegradedSyncRecords,
2310
+ // sync.remote memo (apra-fleet-akuv) -- noteMemberCommand() is the seam the
2311
+ // runner's central command() wrapper calls on every member-bound command;
2312
+ // noteMemberDispatchCompleted() is the soft seam its central agent()
2313
+ // wrapper calls once per settled dispatch (agent-side bd commands never
2314
+ // pass through command(), so this is how a member gets marked for the
2315
+ // lazy sync.remote re-check before any fingerprint skip).
2316
+ noteMemberCommand,
2317
+ noteMemberDispatchCompleted,
2318
+ invalidateSyncRemoteCache,
2319
+ // Remote-tip fingerprint state, exposed for tests and operator tooling.
2320
+ getLastSyncedTip,
2321
+ setLastSyncedTip,
2322
+ clearLastSyncedTip,
1359
2323
  };
1360
2324
 
1361
2325
  export default DoltSync;