@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
@@ -1,5 +1,6 @@
1
1
  import fs from 'fs';
2
2
  import path from 'path';
3
+ import { guardedModulePaths } from './guarded-modules.mjs';
3
4
 
4
5
  // =============================================================================
5
6
  // apra-fleet-eft.3.3 -- dispatch-safety guard checker, extracted so it is
@@ -19,6 +20,16 @@ import path from 'path';
19
20
  // Invariant under test (unchanged from eft.3.1): EVERY `command(` / `agent(`
20
21
  // call site in a scanned source file must supply an explicit `member_name`
21
22
  // (or `member_id`) in its options object.
23
+ //
24
+ // MODULE-LIST GENERALIZATION: this guard is no longer pointed at a single
25
+ // hard-coded file. checkModules() below reads the SHARED guarded-module list
26
+ // (./guarded-modules.mjs) -- the one place a newly extracted fleet-sprint
27
+ // module is registered -- so a dispatch that moves out of runner.js into a
28
+ // new module stays covered instead of silently falling out of scan scope.
29
+ // checkPath() remains exported and behaves exactly as before; it is still the
30
+ // right entry point for scanning one specific file (a fixture, or a module
31
+ // like dolt-sync.mjs that is deliberately not on the shared list). This
32
+ // module is the reference implementation the sibling guards follow.
22
33
  // =============================================================================
23
34
 
24
35
  /**
@@ -63,18 +74,177 @@ export function skipStringLiteral(src, start, quoteChar) {
63
74
  return i;
64
75
  }
65
76
 
77
+ // A `/` that opens a REGEX literal (as opposed to a division/`/=` operator)
78
+ // is only ever preceded -- skipping whitespace -- by one of these punctuation
79
+ // characters, by the start of the file, or by one of the listed keywords.
80
+ // This is the same heuristic real tokenizers use to disambiguate the two: a
81
+ // division operator always follows a value (an identifier, number, `)`, `]`,
82
+ // `}`, or a closing quote), never one of these. Good enough for source text
83
+ // that is valid, already-linted JS (this repo's own modules), which is the
84
+ // only input maskComments() is ever run against.
85
+ const REGEX_PRECEDING_PUNCT_CHARS = new Set('([{,;:=!&|?+-*%^~<>'.split(''));
86
+ const REGEX_PRECEDING_KEYWORDS = new Set([
87
+ 'return', 'typeof', 'instanceof', 'in', 'of', 'new', 'delete', 'void',
88
+ 'yield', 'throw', 'case', 'do', 'else', 'await',
89
+ ]);
90
+
91
+ /**
92
+ * True when a `/` at position `idx` in `text` opens a regex literal rather
93
+ * than a division or `/=` operator. Scans backward from `idx` (skipping
94
+ * whitespace) to the last significant character/word and checks it against
95
+ * REGEX_PRECEDING_PUNCT_CHARS/REGEX_PRECEDING_KEYWORDS above. `text` must
96
+ * already have comments masked to whitespace at every position before `idx`
97
+ * (both maskComments()'s own in-progress `out` buffer and its finished
98
+ * return value satisfy this), so a `/` right after where a comment used to
99
+ * be correctly sees whatever preceded the comment, not the comment itself.
100
+ * EXPORTED so any OTHER walk over an already-masked copy of source (e.g. a
101
+ * depth-count loop that must not miscount a quote or bracket embedded in a
102
+ * regex body) can reuse the exact same regex-vs-division heuristic instead
103
+ * of re-deriving it -- see extractBalancedCall() below and
104
+ * unbracketed-push-guard.mjs's findFunctionBodyRange() for two consumers
105
+ * that got this wrong before apra-fleet-btj9.10.
106
+ */
107
+ export function canStartRegex(text, idx) {
108
+ let j = idx - 1;
109
+ while (j >= 0 && /\s/.test(text[j])) j--;
110
+ if (j < 0) return true; // start of file
111
+ if (REGEX_PRECEDING_PUNCT_CHARS.has(text[j])) return true;
112
+ let k = j;
113
+ while (k >= 0 && /[A-Za-z0-9_$]/.test(text[k])) k--;
114
+ const word = text.slice(k + 1, j + 1);
115
+ return REGEX_PRECEDING_KEYWORDS.has(word);
116
+ }
117
+
118
+ /**
119
+ * Returns the index of the closing `/` of a regex literal that opens at
120
+ * `start`, or -1 if none is found before end-of-line/end-of-file (a regex
121
+ * literal can never span a raw newline in valid JS, so hitting one means the
122
+ * leading `/` was misclassified as a regex start -- the caller falls back to
123
+ * treating it as an ordinary character). Tracks bracket-expression state
124
+ * (`[...]`) because a `/` inside a character class does not close the regex
125
+ * (this is exactly what SAFE_TEXT_RE = /^[A-Za-z0-9 .,:;!?()'_/+[\]-]+$/ in
126
+ * newtask-text.mjs relies on), and skips backslash-escaped characters
127
+ * (inside or outside the class) the same way skipStringLiteral() does.
128
+ * EXPORTED for the same reason as canStartRegex() above.
129
+ */
130
+ export function skipRegexLiteral(src, start) {
131
+ let inClass = false;
132
+ for (let i = start + 1; i < src.length; i++) {
133
+ const ch = src[i];
134
+ if (ch === '\\') { i++; continue; }
135
+ if (ch === '\n') return -1;
136
+ if (inClass) {
137
+ if (ch === ']') inClass = false;
138
+ continue;
139
+ }
140
+ if (ch === '[') { inClass = true; continue; }
141
+ if (ch === '/') return i;
142
+ }
143
+ return -1;
144
+ }
145
+
146
+ /**
147
+ * Replaces every comment's characters with spaces (newlines preserved), so
148
+ * the result has the SAME length and line numbering as `src` but no comment
149
+ * text -- mirrors test/helpers/dispatch-pin-scanner.mjs's maskComments()
150
+ * (that file's stripComments() helper is NOT length-preserving, which would
151
+ * corrupt the positional index math extractBalancedCall depends on).
152
+ *
153
+ * WHY THIS EXISTS (apra-fleet-3swo.34): extractBalancedCall()'s depth walk
154
+ * skips over string literals but, before this fix, did not skip comments.
155
+ * runner.js's prose comments are full of apostrophes (e.g. "the streak's
156
+ * scope"); an unmasked walk reads that apostrophe as an opening quote and
157
+ * swallows everything -- including real closing parens -- until the next
158
+ * apostrophe, so a call site's balanced range can silently run away to the
159
+ * end of the file. Masking comments out before walking parens/quotes is what
160
+ * makes the balanced range trustworthy; the returned callText is still
161
+ * sliced from the ORIGINAL (unmasked) src so callers keep seeing real
162
+ * comment text, just with correct boundaries.
163
+ *
164
+ * REGEX LITERALS (apra-fleet-btj9.10): a regex whose body contains a quote or
165
+ * apostrophe -- e.g. newtask-text.mjs's
166
+ * `SAFE_TEXT_RE = /^[A-Za-z0-9 .,:;!?()'_/+[\]-]+$/` or branch-ensure.mjs's
167
+ * `/couldn't find remote ref/i` -- used to open the SAME kind of phantom
168
+ * string the comment-blindness fix above closed for apostrophes in prose: the
169
+ * string branch below would treat that quote as opening a real string and
170
+ * copy everything up to the next matching quote through UNMASKED, including
171
+ * any real comment in between (whose stray parens could then desync a later
172
+ * extractBalancedCall() depth walk). Regex literals are recognized (via
173
+ * canStartRegex()/skipRegexLiteral() above) and copied through verbatim --
174
+ * like a string, not stripped -- BEFORE the string branch gets a chance to
175
+ * misread the quote inside one.
176
+ *
177
+ * @param {string} src
178
+ * @returns {string}
179
+ */
180
+ export function maskComments(src) {
181
+ let out = '';
182
+ for (let i = 0; i < src.length; i++) {
183
+ const ch = src[i];
184
+ if (ch === '/' && src[i + 1] === '/') {
185
+ while (i < src.length && src[i] !== '\n') { out += ' '; i++; }
186
+ out += '\n';
187
+ continue;
188
+ }
189
+ if (ch === '/' && src[i + 1] === '*') {
190
+ const end = src.indexOf('*/', i + 2);
191
+ const stop = end < 0 ? src.length - 1 : end + 1;
192
+ for (; i <= stop; i++) out += src[i] === '\n' ? '\n' : ' ';
193
+ i--;
194
+ continue;
195
+ }
196
+ if (ch === '/' && canStartRegex(out, out.length)) {
197
+ const end = skipRegexLiteral(src, i);
198
+ if (end !== -1) {
199
+ let flagEnd = end;
200
+ while (flagEnd + 1 < src.length && /[a-zA-Z]/.test(src[flagEnd + 1])) flagEnd++;
201
+ out += src.slice(i, flagEnd + 1);
202
+ i = flagEnd;
203
+ continue;
204
+ }
205
+ // Not actually a regex (no closing `/` before end of line) --
206
+ // fall through and let the default branch below copy the `/`
207
+ // as an ordinary character.
208
+ }
209
+ if (ch === '"' || ch === "'" || ch === '`') {
210
+ const end = skipStringLiteral(src, i, ch);
211
+ out += src.slice(i, end + 1);
212
+ i = end;
213
+ continue;
214
+ }
215
+ out += ch;
216
+ }
217
+ return out;
218
+ }
219
+
66
220
  /**
67
221
  * Given the index of an opening '(' in `src`, returns the full call-site
68
222
  * text from that '(' through its matching ')', tracking paren depth and
69
223
  * skipping over string/template-literal contents (so parens embedded in
70
224
  * string/template content, e.g. `bd show ${ids.join(' ')}`, never disturb
71
- * the depth count).
225
+ * the depth count) AND over comment spans (so an apostrophe in prose, e.g.
226
+ * "the streak's scope", is never misread as opening a string -- see
227
+ * maskComments() above). The depth/quote walk runs over a comment-masked
228
+ * copy of `src`, but the returned text is sliced from the ORIGINAL `src` so
229
+ * real comment content is preserved in the output.
230
+ *
231
+ * ALSO skips over regex literals in this SAME walk (apra-fleet-btj9.10):
232
+ * maskComments() copies a regex literal's body through verbatim (like a
233
+ * string's), so a quote/apostrophe inside one (e.g. a call argument written
234
+ * `/it's ok/`) is still sitting right there in `masked`. Without this,
235
+ * THIS walk's own quote branch below would re-discover that apostrophe and
236
+ * misread it as opening a real string, potentially running the depth walk
237
+ * away past the call's real closing paren. Uses the same
238
+ * canStartRegex()/skipRegexLiteral() maskComments() itself uses, so a
239
+ * `/` is only ever treated as a regex open here in the exact cases it would
240
+ * have been treated as one during masking.
72
241
  */
73
242
  export function extractBalancedCall(src, openParenIdx) {
243
+ const masked = maskComments(src);
74
244
  let depth = 0;
75
245
  let i = openParenIdx;
76
- for (; i < src.length; i++) {
77
- const ch = src[i];
246
+ for (; i < masked.length; i++) {
247
+ const ch = masked[i];
78
248
  if (ch === '(') {
79
249
  depth++;
80
250
  } else if (ch === ')') {
@@ -82,8 +252,11 @@ export function extractBalancedCall(src, openParenIdx) {
82
252
  if (depth === 0) {
83
253
  return src.slice(openParenIdx, i + 1);
84
254
  }
255
+ } else if (ch === '/' && canStartRegex(masked, i)) {
256
+ const end = skipRegexLiteral(masked, i);
257
+ if (end !== -1) i = end;
85
258
  } else if (ch === '"' || ch === "'" || ch === '`') {
86
- i = skipStringLiteral(src, i, ch);
259
+ i = skipStringLiteral(masked, i, ch);
87
260
  }
88
261
  }
89
262
  // Unbalanced -- should never happen against real, syntactically-valid
@@ -175,3 +348,42 @@ export function checkPath(filePath) {
175
348
  const violations = findViolations(sites, fileLabel);
176
349
  return { sites, violations };
177
350
  }
351
+
352
+ /**
353
+ * Aggregate entry point: scans EVERY module in the shared guarded-module list
354
+ * (fleet-sprint/guarded-modules.mjs -- runner.js today, plus whatever is
355
+ * extracted from it) and returns the union of their call sites and
356
+ * violations. This is the reference implementation the other mechanical
357
+ * guards in this directory follow.
358
+ *
359
+ * Each violation string already carries the basename of the file it came
360
+ * from (findViolations' `fileLabel`), so an aggregate run over several
361
+ * modules attributes every finding to the correct module rather than to a
362
+ * single hard-coded runner.js label. `sitesByFile` gives per-module call-site
363
+ * counts for baseline assertions that need them.
364
+ *
365
+ * `paths` defaults to the shared list; callers pass
366
+ * guardedModulePaths([fixture]) to prove the list -- not a hard-coded name --
367
+ * is what the guard actually reads.
368
+ *
369
+ * @param {string[]} [paths]
370
+ * @returns {{ sites: object[], violations: string[], files: string[], sitesByFile: Record<string, object[]> }}
371
+ */
372
+ export function checkModules(paths = guardedModulePaths()) {
373
+ if (!Array.isArray(paths)) {
374
+ throw new TypeError('checkModules(paths): paths must be an array of file paths');
375
+ }
376
+ const sites = [];
377
+ const violations = [];
378
+ const files = [];
379
+ const sitesByFile = {};
380
+ for (const p of paths) {
381
+ const file = path.basename(p);
382
+ const result = checkPath(p);
383
+ files.push(file);
384
+ sitesByFile[file] = result.sites;
385
+ sites.push(...result.sites.map((s) => ({ ...s, file })));
386
+ violations.push(...result.violations);
387
+ }
388
+ return { sites, violations, files, sitesByFile };
389
+ }
@@ -90,7 +90,7 @@ Watch progress there rather than tailing raw stdout.
90
90
  | `--role-map <json\|@file>` | | no | -- | JSON object mapping role -> member[], e.g. `'{"doer":["m1","m2"]}'`. Inline JSON or `@path/to/file.json`. |
91
91
  | `--viewer-port <port>` | | no | `8080` | Port for the local dashboard viewer. |
92
92
  | `--budget <usd>` | | no | unlimited | USD ceiling for this run's total estimated spend. |
93
- | `--dispatch-timeout-s <s>` | | no | `9000` | Per-dispatch time budget in seconds, applied as both the inactivity timeout and the hard ceiling on every agent dispatch (integ-test dispatch ceiling is 2x, regression-test ceiling is 3x). Minimum 60. Lower it for small sprints so a hung dispatch costs minutes, not 2.5 hours. |
93
+ | `--dispatch-timeout-s <s>` | | no | `9000` | Per-dispatch total time budget in seconds -- the hard ceiling on every agent dispatch (integ-test dispatch ceiling is 2x, regression-test ceiling is 3x). Minimum 60. The inactivity/stall threshold used to detect a hung dispatch is derived from this value but capped separately at 30 minutes, so raising this budget for a large sprint does not also grant a stalled dispatch a correspondingly longer grace period before it is killed. Lower it for small sprints so a hung dispatch costs minutes, not 2.5 hours. |
94
94
  | `--sync` | | no | off | Synced topology mode (orchestrator-bracketed git sync): members may sit on differing HEADs but must share the same origin URL and pass a `bd dolt pull` probe. Omitted uses shared-workspace mode (all members on the same HEAD). |
95
95
  | `--help` | `-h` | | | Show the engine's help. |
96
96
 
@@ -1193,6 +1193,57 @@ For the target member M, starting from both clones at the same sandbox head:
1193
1193
  declared verified. It is intentionally NOT in any default CI pass, and no
1194
1194
  CI configuration should be added that pretends otherwise.
1195
1195
 
1196
+ ### 6.7 Re-affirmed CI-exclusion decision (apra-fleet-j918.5.3, current pass)
1197
+
1198
+ **Decided 2026-09-15, against tree `f4eda6e08e53412c5cffe5bae25d686280987cbd`
1199
+ (branch `chore/j918-test-suite-cleanup`).** A test-suite audit flagged that
1200
+ the merge-conflict recovery path (`settleDoltConflicts()`,
1201
+ `fleet-sprint/dolt-settle.mjs`) is exercised in `npm test` ONLY by
1202
+ `test/dolt-settle.test.mjs`'s hand-written SQL-string simulator -- a scripted
1203
+ `command()` mock that regex-matches emitted SQL text (`CALL DOLT_MERGE`,
1204
+ `SELECT * FROM dolt_conflicts`, `CALL DOLT_CONFLICTS_RESOLVE`, ...; see e.g.
1205
+ `test/dolt-settle.test.mjs:389-423`) rather than running a real `dolt`
1206
+ process. This 6.2/6.6 exclusion was decided in 2026-08 for a different
1207
+ reason (no generic CI runner has a live fleet server or SSH-reachable
1208
+ members) and never separately weighed against the fact that CI's only
1209
+ coverage of the real recovery path is that simulator. Re-examining now
1210
+ because the failure mode this path guards -- a Dolt-CLI/SQL-dialect
1211
+ regression silently corrupting or losing rows in the SHARED beads DB during
1212
+ a real merge -- is a data-loss risk, and an inherited justification for a
1213
+ different concern is not evidence this specific gap is acceptable.
1214
+
1215
+ **The header's exclusion claim was re-verified against the current file
1216
+ before writing this section** (`scripts/dolt-settle-integration.mjs:24-27`):
1217
+ it still requires a live `apra-fleet` server (`ApraFleet`/`McpClient` over
1218
+ `resolveFleetServerConnection`) plus SSH-reachable members
1219
+ (`createMemberReservationClient`, real `execute_command` dispatch) -- nothing
1220
+ about that dependency has changed since Part 6.2, so **this script itself
1221
+ stays excluded from `npm test`/`test:unit`/`test:slow`, unchanged.** Its
1222
+ live-fleet/SSH requirement is a hard blocker for any generic CI runner
1223
+ regardless of how cheap `dolt` itself is to run.
1224
+
1225
+ That said, the data-loss coverage gap is real and worth closing separately,
1226
+ because it does not actually require this script's live-fleet/SSH machinery:
1227
+ `dolt` is a single, statically-linked binary, already version-pinned
1228
+ (`DOLT_VERSION`, Part 5.1), and `settleDoltConflicts()` only needs an
1229
+ injected `command()` -- it never requires the fleet/SSH transport itself.
1230
+ A much narrower job -- two local `bd` clones on the CI runner, a local
1231
+ merge conflict manufactured directly (no fleet server, no member
1232
+ reservation, no SSH), and `settleDoltConflicts()` wired to a `command()`
1233
+ that shells out to the pinned local `dolt` binary -- is plausible without
1234
+ reproducing any of the live-fleet dependency that justifies excluding
1235
+ *this* script. Weighed against that: added CI runtime, and the blast
1236
+ radius of any CI job that manipulates real Dolt merge state (mitigated by
1237
+ running entirely in a disposable local temp dir, same isolation principle
1238
+ as Part 6.4, never touching a shared remote).
1239
+
1240
+ **Decision: add that narrower, local-only, live-`dolt` test as a follow-up,
1241
+ filed as apra-fleet-j918.9 (linked from this doc; not implemented by this
1242
+ task).** `scripts/dolt-settle-integration.mjs` remains excluded from CI as
1243
+ Part 6.2/6.6 already state -- this section adds the current-pass
1244
+ justification and the follow-up, it does not change the exclusion itself.
1245
+ No CI configuration is added by this task.
1246
+
1196
1247
  ---
1197
1248
 
1198
1249
  ## Part 7 -- persistent vs. ephemeral `dolt sql-server`, answered precisely
@@ -1485,3 +1536,228 @@ so the list below reads as history rather than as a pending action:
1485
1536
  integrity bug (a filed bead reference vanished), but not a sync/conflict
1486
1537
  issue and not something settle() affects. Left open, unrelated.
1487
1538
 
1539
+ ## Part 9 -- sync COST: fewer and cheaper syncs per sprint
1540
+
1541
+ Parts 1-8 are about sync CORRECTNESS (what happens when a sync conflicts).
1542
+ This part is about sync COST, from a separate read-only review of where a
1543
+ fleet-sprint actually spends its `bd dolt pull` / `bd dolt push` minutes. The
1544
+ measured shape on the reference machine: about 20 D-pull/D-push pairs per
1545
+ sprint, each bracketed by 1-2 uncached `bd config get sync.remote` probes
1546
+ (0.6s each), against a 548 MB embedded Dolt store whose full open-and-walk
1547
+ cost is paid on every invocation regardless of how little changed.
1548
+
1549
+ Three changes landed in `dolt-sync.mjs` (a fourth, in the supervisor's
1550
+ pre-launch scope guard, is described in `src/supervisor/scope-overlap.mjs`).
1551
+
1552
+ ### 9.1 The `sync.remote` probe is memoized per member
1553
+
1554
+ `isMemberSyncRemoteConfigured()` spawned a fresh `bd config get sync.remote
1555
+ --json` on every call -- the D-pull pre-gate, the D-push pre-gate, and
1556
+ `status()` -- which totals roughly 90-160 spawns per sprint for a value that
1557
+ never changes mid-run. A codebase search confirmed no production path in this
1558
+ package writes `sync.remote` during a live sprint; only test fixtures and
1559
+ one-time setup scripts do.
1560
+
1561
+ The result is now cached per member for the process lifetime (one runner
1562
+ process per sprint). Two properties matter:
1563
+
1564
+ - **Only a positively parsed answer is cached.** Every fail-safe path (the
1565
+ command threw, a `failSoft` error result, no output, unparseable output)
1566
+ still reports "configured" and is deliberately NOT cached, so one transient
1567
+ probe failure cannot pin the fail-safe answer for the rest of the run. The
1568
+ fail-CLOSED contract is unchanged.
1569
+ - **Explicit invalidation, not a TTL.** A TTL re-adds spawns for no real
1570
+ safety. Three HARD seams drop the memo, and every one of them drops the 9.3
1571
+ remote-tip fingerprint alongside it (the two are always forgotten
1572
+ together): `noteMemberCommand()`, called from the runner's central
1573
+ `command()` wrapper for any `bd config set` / `bd dolt remote` / `bd init` /
1574
+ `bd bootstrap` the orchestrator issues on that member; the auth self-heal
1575
+ firing inside `runDoltStep`; and `repair()`.
1576
+ - **The per-dispatch seam is SOFT (round 4).** A dispatched agent runs its
1577
+ `bd` commands in its own session on the member, never through the
1578
+ `command()` wrapper, so `noteMemberCommand()` cannot see them; the runner's
1579
+ central `agent()` wrapper calls `noteMemberDispatchCompleted()` the moment
1580
+ any dispatch settles. Round 3 made that an unconditional wipe of both
1581
+ memos. Combined with "a push never mints a fingerprint" (9.3), the
1582
+ fingerprint was then EMPTY at the start of every dispatch bracket -- the
1583
+ module's primary path -- so the primary path paid one `ls-remote` more
1584
+ than before the feature and skipped nothing, and the probe was re-spawned
1585
+ once per dispatch (golden mock-sprint transcript: 1 -> 14). The hazards
1586
+ the wipe guarded were checked against what bd actually does:
1587
+ `bd bootstrap` -- the one self-heal this repo's agent instructions
1588
+ prescribe -- is non-destructive (an existing DB is validated and reported,
1589
+ never replaced) and, where it creates a DB, CLONES it from `sync.remote`,
1590
+ so a surviving fingerprint that still equals the remote tip is still the
1591
+ truth; `bd init` refuses on an existing DB unless forced, and a forced
1592
+ re-init yields an unrelated history that no pull can fast-forward (its next
1593
+ push diverges into the terminals that already forget the tip and settle).
1594
+ The one event a surviving fingerprint would get WRONG is an agent-side
1595
+ `bd config set sync.remote <other>`. So the seam now MARKS the member as
1596
+ dispatched-since-verified and drops nothing; the fingerprint is bound to
1597
+ the URL it was minted against; and a marked member's `sync.remote` is
1598
+ re-read (one `bd config get`, a plain config.yaml read, no Dolt engine)
1599
+ only at the one decision a stale memo could turn into stale data -- the
1600
+ moment a D-pull is about to be SKIPPED on that fingerprint. Same URL:
1601
+ skip. Different or unreadable: fingerprint forgotten, real pull. Every
1602
+ other consumer of the memo fails closed anyway (a wrong "configured"
1603
+ answer just issues a real pull/push against whatever remote bd itself has
1604
+ configured). The re-read is therefore paid once per skip-after-dispatch,
1605
+ never per dispatch; a bracket whose tip moved pays nothing extra; a
1606
+ member with a remote is back to one probe per process. The one case that
1607
+ never reaches that check is a member memoized as having NO remote (both
1608
+ pre-gates exit on it first): its memo is re-read once after any dispatch,
1609
+ because an agent wiring a remote mid-dispatch would otherwise leave every
1610
+ later D-push of that member reporting a benign no-remote skip -- success
1611
+ -- while its bead closes never left the clone. That costs one config.yaml
1612
+ read per dispatch for no-remote members only (sandboxes; the no-remote
1613
+ mock sprint's golden transcript shows one probe per dispatch for exactly
1614
+ this reason).
1615
+ - **The probe never waits on a prompt, and switches itself off when it
1616
+ cannot work.** The probe URL carries no userinfo (9.3), so a member whose
1617
+ only credential for the host was URL-embedded would have git try to
1618
+ PROMPT -- under Git Credential Manager on Windows, a dialog that blocks
1619
+ until the 30s probe timeout, on every bracket. The probe runs with
1620
+ `-c credential.interactive=never -c core.askPass=` (config flags, never a
1621
+ shell env prefix -- the member's shell may be PowerShell) so it fails at
1622
+ once, and after two consecutive failed probes the member's probe is
1623
+ disabled for the process (re-armed by the hard seams), so every pull is
1624
+ simply real again. Two rather than one so a single blip does not cost the
1625
+ feature.
1626
+
1627
+ ### 9.2 The transient retry ladder is time-boxed, not count-boxed
1628
+
1629
+ The ladder was widened to 8 retries with a 30s backoff cap to survive a live
1630
+ Windows machine-wide `git.exe` spawn outage (`fork/exec ... "Not enough memory
1631
+ resources"`), measured at 1-3 minutes. That was the right diagnosis but the
1632
+ wrong bound: it applied the long budget to EVERY transient kind, and the unit
1633
+ suite went from 80s to 6m15s because ordinary transients in fixtures now
1634
+ walked the full ladder (91.5s of pure sleep in one exhausted ladder, before
1635
+ counting the 600s per-attempt timeout).
1636
+
1637
+ The budget was never really about a count -- it was about spanning a
1638
+ wall-clock outage window. So the ladder is split by error class:
1639
+
1640
+ | class | bound | backoff cap |
1641
+ |---|---|---|
1642
+ | spawn outage (`fork/exec`, "Not enough memory resources") | 3 min WALL CLOCK | 30s |
1643
+ | every other transient | 5 retries (`maxTransientRetries`) | 8s |
1644
+
1645
+ A wall-clock bound is the same 3 minutes whether each attempt returns
1646
+ instantly or sits on the 600s step timeout; the old count-based bound
1647
+ multiplied out to a worst case of 9 attempts x 600s. The generic default is
1648
+ the pre-widening 5 (a first cut mis-restored it as 2; corrected). An
1649
+ explicitly passed `maxTransientRetries` is honored by BOTH ladders: it bounds
1650
+ the generic class as before, and it is a hard attempt cap on the spawn-outage
1651
+ ladder too (the wall-clock budget still applies underneath it). Left unset --
1652
+ the production shape, since no runner call site passes one -- the spawn-outage
1653
+ class keeps its full wall-clock budget. A `diverged` classification is still
1654
+ never retried, under either ladder. The spawn-outage sub-classifier matches
1655
+ only the `fork/exec` line: the "Not enough memory resources" wording on its
1656
+ own never classifies `transient` in the first place (it is not in the dolt
1657
+ provider's TRANSIENT table), so a pattern for it was dead and was removed.
1658
+
1659
+ ### 9.3 Remote-tip fingerprint: skip a D-pull only when it is provably a no-op
1660
+
1661
+ **The correctness anchor.** The shared remote's `refs/dolt/data` is the ONLY
1662
+ channel through which beads state moves between machines. A member's clone can
1663
+ therefore be stale in exactly one way: that ref advanced since the member last
1664
+ pulled or pushed. "Is a D-pull needed?" then has a cheap, EXACT answer --
1665
+ compare the remote SHA now against the SHA this member last synchronized to --
1666
+ rather than a policy bet about who else might be writing.
1667
+
1668
+ This is why the alternatives were rejected. "Skip for read-only roles" and
1669
+ "skip within N seconds of the last pull" both trade real staleness for speed:
1670
+ a reviewer reads acceptance criteria a remote doer just pushed, and a
1671
+ plan-reviewer reads the planner's freshly pushed DAG. Any fixed bound is a
1672
+ guess about other writers, and a wrong guess produces exactly the
1673
+ false-FAILED-streak failure the post-streak verify pull exists to prevent. A
1674
+ tip-equal skip removes only pulls that are provably no-ops, so no operator has
1675
+ to pick a risk bound at all.
1676
+
1677
+ **Mechanism.** Before a real `bd dolt pull`, one `git ls-remote <sync.remote>
1678
+ refs/dolt/data` -- one network round trip, no Dolt engine startup, no 548 MB
1679
+ chunk store to open (0.35s measured, against multi-minute real pulls). On a
1680
+ match the pull is not spawned and the step returns `{ ok: true, member,
1681
+ skipped: true, reason: 'remote-unchanged', remoteTip }`.
1682
+
1683
+ **The recorded tip is minted in exactly one place, from a value the clone is
1684
+ provably current with:**
1685
+
1686
+ - after a successful PULL, record the SHA observed IMMEDIATELY BEFORE it --
1687
+ never one read afterwards. A push racing in during the pull is not in what
1688
+ was fetched, so recording the later SHA would claim freshness the clone does
1689
+ not have. Recording the earlier one can only cost one redundant future pull.
1690
+ - after a successful PUSH by this member, FORGET the recorded tip. A push never
1691
+ records anything.
1692
+
1693
+ **Why a push cannot mint a fingerprint.** Two earlier cuts recorded a SHA read
1694
+ from the remote after the push -- unconditionally at first, then only when the
1695
+ ref had "advanced" past a pre-push read. Both lose the same race: the push
1696
+ mutex serializes this fleet's pushes against each other and nothing else, so
1697
+ an unrelated machine can push in the gap between our push landing and our
1698
+ post-push `ls-remote` returning. That read then observes a stranger's commit
1699
+ this clone has never seen, records it as ours, and the next D-pull is wrongly
1700
+ skipped -- exactly the staleness the feature exists to prevent. A network read
1701
+ of "the remote's current tip" is never a proxy for "what my push published".
1702
+ Nor is there a local proxy for this transport: bd's git-backed remote is Dolt's
1703
+ git blobstore, where a push wraps the chunk-store manifest in a fresh git
1704
+ commit built inside the push on top of the remote head it just fetched. That
1705
+ commit -- the remote's new `refs/dolt/data` -- is not a function of local Dolt
1706
+ state, is not printed by `bd dolt push`, and lands locally only in a
1707
+ per-process UUID-named ref (`refs/dolt/blobstore/<remote>/dolt/data/<uuid>`)
1708
+ inside a sha256-named cache dir under `.beads/`, reachable only by a
1709
+ shell-dialect-specific scan of the member's disk (verified against a live
1710
+ clone: the cache repo's tracking refs and `FETCH_HEAD` already disagreed with
1711
+ the remote's live tip). So the pusher forgets its tip and pays one real pull
1712
+ at its next bracket, after which the skip is re-armed. A no-op push is treated
1713
+ identically -- it proves nothing about the clone's freshness. As a side
1714
+ effect no `ls-remote` is issued anywhere in the D-push bracket: the mutex hold
1715
+ is exactly push + reconcile + settle.
1716
+
1717
+ **Fail-open, always.** Every uncertainty falls through to a REAL pull: no
1718
+ recorded tip yet, an `ls-remote` failure or timeout, unparseable output, a
1719
+ `sync.remote` that could not be positively read, or a URL that fails the
1720
+ strict safe-charset gate. A divergence, a settle, a successful push, an auth
1721
+ self-heal, a `repair()`, an orchestrator-issued `bd init`/`bootstrap`/`config
1722
+ set`, and a `sync.remote` found changed under a dispatch (9.1) all FORGET the
1723
+ recorded tip rather than leave a stale one. The recorded tip is bound to the
1724
+ URL it was observed at and never validates a probe of any other URL. There
1725
+ is deliberately no path in which doubt produces a skip.
1726
+
1727
+ **Three implementation constraints worth restating:**
1728
+
1729
+ - The probe target is resolved from `sync.remote` (through the 9.1 memo, so it
1730
+ costs no extra `bd config get`), NEVER from git's `origin`. The two can
1731
+ legitimately differ on a member, and probing `origin` would compare this
1732
+ member's freshness against the wrong ref. bd spells a git-transport remote
1733
+ `git+https://...`; the `git+` prefix is bd's own scheme marker and is
1734
+ stripped before `ls-remote`. A `sync.remote` with NO scheme -- a bare Dolt
1735
+ remote NAME (`origin`, which the integration fixtures legitimately set) or
1736
+ a bare path (a Dolt file remote, never a git repository) -- yields no probe
1737
+ at all, because `git ls-remote origin` would silently resolve against
1738
+ git's origin, the exact target this rule forbids.
1739
+ - The probe command string is journaled VERBATIM into the persisted,
1740
+ dashboard-visible run transcript (`silent` only suppresses the console
1741
+ line). An http(s) userinfo (`user:token@`) in `sync.remote` is therefore
1742
+ stripped before the URL is interpolated into the command; previously such
1743
+ a token only ever appeared as command OUTPUT (`bd config get`). The
1744
+ stripped URL still authenticates through the git credential helper every
1745
+ provisioned member carries (that is how `git push` works on members); a
1746
+ member whose only credential was URL-embedded gets a failed probe, which is
1747
+ a real pull. ssh URLs keep their `git@` -- a login name, not a secret.
1748
+ - The probe string reaches the member's own shell, which may be PowerShell or
1749
+ a POSIX shell. Rather than trying to quote correctly for both, any remote URL
1750
+ containing a character outside a conservative safe charset (no whitespace,
1751
+ no quote, no metacharacter of either dialect) is REFUSED -- which yields no
1752
+ fingerprint and a real pull, the safe direction.
1753
+
1754
+ Disable per call site with `remoteTipFingerprint: false`.
1755
+
1756
+ ### 9.4 Not done here, on purpose
1757
+
1758
+ Two larger items from the same review are deliberately out of scope: squashing
1759
+ the Dolt history and re-bootstrapping every member clone (the largest per-op
1760
+ win, but a destructive operational change needing a quiescent window and its
1761
+ own runbook), and moving `sync.remote` off the git transport onto a native
1762
+ Dolt bucket remote.
1763
+
@@ -703,7 +703,7 @@ ENGINE's maintainers without silent uploads -- and its flow is adopted whole:
703
703
 
704
704
  - **Sanitize FIRST, locally, always** -- before the report is even written to disk: absolute
705
705
  paths -> stable placeholders (`<work-folder>/...`, `<home>/...`); hostnames/usernames/IPs/
706
- emails -> redacted tokens; anything matching secret patterns (keys, tokens, `{{secure.*}}`
706
+ emails -> redacted tokens; anything matching secret patterns (keys, tokens, `{{secret.*}}`
707
707
  values, env dumps) -> stripped outright, never placeholdered; target-repo identifiers (repo
708
708
  name, branch names, bead titles) -> anonymized to `<target-repo>`/`<sprint-branch>` by
709
709
  default, with an opt-in tier for internal users to keep them; code snippets excluded by