@apralabs/apra-fleet 0.4.2 → 0.4.4

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 (997) hide show
  1. package/README.md +103 -34
  2. package/dist/agents/backlog-groomer.md +87 -14
  3. package/dist/agents/ci-watcher.md +35 -9
  4. package/dist/agents/deployer.md +63 -11
  5. package/dist/agents/doer.md +99 -41
  6. package/dist/agents/harvester.md +47 -27
  7. package/dist/agents/integ-test-runner.md +38 -10
  8. package/dist/agents/kb-reconciler.md +37 -7
  9. package/dist/agents/plan-reviewer.md +145 -32
  10. package/dist/agents/planner.md +180 -69
  11. package/dist/agents/regression-test-runner.md +98 -64
  12. package/dist/agents/reviewer.md +117 -45
  13. package/dist/agents/schemas/backlog-groomer-output.json +1 -1
  14. package/dist/agents/schemas/doer-output.json +32 -0
  15. package/dist/agents/schemas/harvester-input.json +1 -5
  16. package/dist/agents/schemas/plan-reviewer-output.json +37 -0
  17. package/dist/agents/schemas/planner-output.json +1 -1
  18. package/dist/agents/schemas/regression-test-runner-output.json +41 -7
  19. package/dist/agents/schemas/reviewer-output.json +62 -3
  20. package/dist/cli/agent-transform.d.ts +90 -2
  21. package/dist/cli/agent-transform.js +310 -20
  22. package/dist/cli/auth.d.ts +1 -0
  23. package/dist/cli/auth.js +66 -17
  24. package/dist/cli/beads-install.d.ts +35 -0
  25. package/dist/cli/beads-install.js +125 -0
  26. package/dist/cli/beads-pin.d.ts +5 -0
  27. package/dist/cli/beads-pin.js +27 -0
  28. package/dist/cli/call.d.ts +27 -0
  29. package/dist/cli/call.js +177 -0
  30. package/dist/cli/config.d.ts +31 -6
  31. package/dist/cli/config.js +113 -36
  32. package/dist/cli/dolt-install.d.ts +18 -2
  33. package/dist/cli/dolt-install.js +46 -15
  34. package/dist/cli/fleet-se-guard.d.ts +51 -0
  35. package/dist/cli/fleet-se-guard.js +215 -0
  36. package/dist/cli/install-guard.d.ts +54 -0
  37. package/dist/cli/install-guard.js +132 -4
  38. package/dist/cli/install.d.ts +100 -11
  39. package/dist/cli/install.js +864 -139
  40. package/dist/cli/kb-commit.d.ts +2 -1
  41. package/dist/cli/kb-commit.js +1 -1
  42. package/dist/cli/kb-directives.js +2 -1
  43. package/dist/cli/kb-import.d.ts +2 -1
  44. package/dist/cli/kb-import.js +1 -1
  45. package/dist/cli/register-member.js +26 -5
  46. package/dist/cli/remove-member.d.ts +4 -0
  47. package/dist/cli/remove-member.js +63 -0
  48. package/dist/cli/secret.js +9 -0
  49. package/dist/cli/start.js +59 -4
  50. package/dist/cli/status.d.ts +3 -0
  51. package/dist/cli/status.js +45 -12
  52. package/dist/cli/stop.js +64 -9
  53. package/dist/cli/uninstall.js +101 -15
  54. package/dist/cli/update.js +33 -2
  55. package/dist/cli/watch.js +1 -1
  56. package/dist/cli/workflow.js +3 -2
  57. package/dist/commands/kb-server.d.ts +3 -0
  58. package/dist/commands/kb-server.js +52 -5
  59. package/dist/hub-service/http-server.d.ts +5 -1
  60. package/dist/hub-service/http-server.js +55 -5
  61. package/dist/index.js +158 -11
  62. package/dist/os/child-env-bound.d.ts +77 -0
  63. package/dist/os/child-env-bound.js +171 -0
  64. package/dist/os/linux.d.ts +13 -2
  65. package/dist/os/linux.js +75 -16
  66. package/dist/os/macos.d.ts +1 -1
  67. package/dist/os/macos.js +2 -11
  68. package/dist/os/os-commands.d.ts +78 -4
  69. package/dist/os/windows-gitbash.d.ts +6 -0
  70. package/dist/os/windows-gitbash.js +32 -3
  71. package/dist/os/windows-wrapper.d.ts +0 -4
  72. package/dist/os/windows-wrapper.js +2 -1
  73. package/dist/os/windows.d.ts +11 -2
  74. package/dist/os/windows.js +121 -32
  75. package/dist/paths.d.ts +21 -0
  76. package/dist/paths.js +35 -0
  77. package/dist/providers/agy.d.ts +120 -7
  78. package/dist/providers/agy.js +741 -86
  79. package/dist/providers/claude-permission-denial.d.ts +7 -0
  80. package/dist/providers/claude-permission-denial.js +137 -0
  81. package/dist/providers/claude.d.ts +132 -6
  82. package/dist/providers/claude.js +644 -48
  83. package/dist/providers/codex.d.ts +4 -2
  84. package/dist/providers/codex.js +23 -2
  85. package/dist/providers/copilot.d.ts +4 -2
  86. package/dist/providers/copilot.js +24 -2
  87. package/dist/providers/none.d.ts +4 -2
  88. package/dist/providers/none.js +17 -2
  89. package/dist/providers/opencode.d.ts +12 -2
  90. package/dist/providers/opencode.js +135 -54
  91. package/dist/providers/provider.d.ts +368 -35
  92. package/dist/providers/provider.js +219 -2
  93. package/dist/services/agent-provisioner.d.ts +29 -0
  94. package/dist/services/agent-provisioner.js +107 -0
  95. package/dist/services/agent-shadow.d.ts +96 -0
  96. package/dist/services/agent-shadow.js +479 -0
  97. package/dist/services/agy-project.d.ts +103 -0
  98. package/dist/services/agy-project.js +354 -0
  99. package/dist/services/auth-socket.d.ts +25 -0
  100. package/dist/services/auth-socket.js +72 -27
  101. package/dist/services/auth-web.js +2 -2
  102. package/dist/services/budget-awareness.d.ts +11 -11
  103. package/dist/services/budget-awareness.js +15 -3
  104. package/dist/services/claude-local-scope-mcp.d.ts +19 -0
  105. package/dist/services/claude-local-scope-mcp.js +91 -0
  106. package/dist/services/cloud/aws.js +2 -1
  107. package/dist/services/cloud/lifecycle.js +52 -6
  108. package/dist/services/cloud/task-wrapper.d.ts +0 -9
  109. package/dist/services/cloud/task-wrapper.js +15 -6
  110. package/dist/services/credential-cleanup.js +35 -17
  111. package/dist/services/event-loop-watchdog.d.ts +32 -0
  112. package/dist/services/event-loop-watchdog.js +140 -0
  113. package/dist/services/exit-drain.d.ts +44 -0
  114. package/dist/services/exit-drain.js +52 -0
  115. package/dist/services/github-app.js +32 -4
  116. package/dist/services/http-transport.d.ts +50 -1
  117. package/dist/services/http-transport.js +238 -25
  118. package/dist/services/in-flight-agents.d.ts +2 -0
  119. package/dist/services/in-flight-agents.js +4 -0
  120. package/dist/services/knowledge/bible-basis-filter.d.ts +53 -0
  121. package/dist/services/knowledge/bible-basis-filter.js +134 -0
  122. package/dist/services/knowledge/bible-blob-id.d.ts +44 -0
  123. package/dist/services/knowledge/bible-blob-id.js +113 -0
  124. package/dist/services/knowledge/bible-import.d.ts +65 -0
  125. package/dist/services/knowledge/bible-import.js +211 -0
  126. package/dist/services/knowledge/file-hash.d.ts +31 -0
  127. package/dist/services/knowledge/file-hash.js +153 -23
  128. package/dist/services/knowledge/http-provider.d.ts +4 -3
  129. package/dist/services/knowledge/http-provider.js +17 -5
  130. package/dist/services/knowledge/kb-config.d.ts +42 -0
  131. package/dist/services/knowledge/kb-config.js +54 -0
  132. package/dist/services/knowledge/kb-maintainer-grant.d.ts +15 -0
  133. package/dist/services/knowledge/kb-maintainer-grant.js +34 -0
  134. package/dist/services/knowledge/kb-providers.d.ts +11 -1
  135. package/dist/services/knowledge/kb-providers.js +199 -17
  136. package/dist/services/knowledge/kb-removed-scope-keys.d.ts +28 -0
  137. package/dist/services/knowledge/kb-removed-scope-keys.js +59 -0
  138. package/dist/services/knowledge/kb-scopes.d.ts +14 -0
  139. package/dist/services/knowledge/kb-scopes.js +47 -0
  140. package/dist/services/knowledge/kb-self.d.ts +91 -0
  141. package/dist/services/knowledge/kb-self.js +198 -0
  142. package/dist/services/knowledge/member-bible-view.d.ts +21 -0
  143. package/dist/services/knowledge/member-bible-view.js +194 -0
  144. package/dist/services/knowledge/pre-init.js +1 -0
  145. package/dist/services/knowledge/project-slug.js +2 -2
  146. package/dist/services/knowledge/require-sqlite-project.d.ts +32 -0
  147. package/dist/services/knowledge/require-sqlite-project.js +38 -0
  148. package/dist/services/knowledge/sqlite-provider.d.ts +64 -11
  149. package/dist/services/knowledge/sqlite-provider.js +303 -41
  150. package/dist/services/knowledge/types.d.ts +45 -2
  151. package/dist/services/member-access-secret.d.ts +70 -0
  152. package/dist/services/member-access-secret.js +195 -0
  153. package/dist/services/member-call-counts.d.ts +24 -0
  154. package/dist/services/member-call-counts.js +58 -0
  155. package/dist/services/member-config-io.d.ts +192 -0
  156. package/dist/services/member-config-io.js +443 -0
  157. package/dist/services/member-fleet-install.d.ts +710 -0
  158. package/dist/services/member-fleet-install.js +1895 -0
  159. package/dist/services/member-secret-env.d.ts +42 -0
  160. package/dist/services/member-secret-env.js +68 -0
  161. package/dist/services/member-tool-allowlist.d.ts +49 -0
  162. package/dist/services/member-tool-allowlist.js +111 -0
  163. package/dist/services/model-pricing.d.ts +19 -0
  164. package/dist/services/model-pricing.js +60 -10
  165. package/dist/services/port-holder.d.ts +86 -0
  166. package/dist/services/port-holder.js +351 -0
  167. package/dist/services/preflight-check.js +2 -0
  168. package/dist/services/registry.d.ts +13 -2
  169. package/dist/services/registry.js +27 -1
  170. package/dist/services/relay-strategy.d.ts +2 -0
  171. package/dist/services/relay-strategy.js +8 -0
  172. package/dist/services/secret-token.d.ts +38 -0
  173. package/dist/services/secret-token.js +51 -0
  174. package/dist/services/server-lifecycle.d.ts +26 -0
  175. package/dist/services/server-lifecycle.js +85 -0
  176. package/dist/services/service-manager/index.d.ts +7 -1
  177. package/dist/services/service-manager/index.js +17 -4
  178. package/dist/services/service-manager/linux.d.ts +1 -1
  179. package/dist/services/service-manager/linux.js +15 -7
  180. package/dist/services/service-manager/macos.d.ts +11 -1
  181. package/dist/services/service-manager/macos.js +45 -7
  182. package/dist/services/service-manager/service-path.d.ts +24 -0
  183. package/dist/services/service-manager/service-path.js +55 -0
  184. package/dist/services/service-manager/types.d.ts +39 -2
  185. package/dist/services/service-manager/types.js +29 -0
  186. package/dist/services/service-manager/windows.d.ts +194 -3
  187. package/dist/services/service-manager/windows.js +705 -30
  188. package/dist/services/service-notice.d.ts +14 -0
  189. package/dist/services/service-notice.js +62 -0
  190. package/dist/services/service-start-guard.d.ts +20 -0
  191. package/dist/services/service-start-guard.js +86 -0
  192. package/dist/services/session-cost.d.ts +24 -0
  193. package/dist/services/session-cost.js +105 -0
  194. package/dist/services/session-mcp-config.d.ts +83 -0
  195. package/dist/services/session-mcp-config.js +211 -0
  196. package/dist/services/sftp.d.ts +34 -0
  197. package/dist/services/sftp.js +304 -76
  198. package/dist/services/shell-probe.d.ts +0 -24
  199. package/dist/services/shell-probe.js +28 -3
  200. package/dist/services/singleton.d.ts +68 -2
  201. package/dist/services/singleton.js +168 -11
  202. package/dist/services/sprint-coordination.js +9 -3
  203. package/dist/services/ssh.d.ts +27 -0
  204. package/dist/services/ssh.js +287 -40
  205. package/dist/services/stall/find-log-file.js +12 -5
  206. package/dist/services/stall/index.d.ts +1 -1
  207. package/dist/services/stall/read-log-tail.d.ts +23 -0
  208. package/dist/services/stall/read-log-tail.js +53 -12
  209. package/dist/services/stall/stall-detector.d.ts +78 -5
  210. package/dist/services/stall/stall-detector.js +296 -39
  211. package/dist/services/stall/stall-poller.d.ts +16 -0
  212. package/dist/services/stall/stall-poller.js +50 -6
  213. package/dist/services/stopped-marker.d.ts +16 -0
  214. package/dist/services/stopped-marker.js +55 -0
  215. package/dist/services/strategy.d.ts +33 -1
  216. package/dist/services/strategy.js +165 -19
  217. package/dist/services/substitution-engine.js +2 -2
  218. package/dist/services/supervisor-service-cleanup.d.ts +52 -0
  219. package/dist/services/supervisor-service-cleanup.js +332 -0
  220. package/dist/services/tool-registry.d.ts +8 -1
  221. package/dist/services/tool-registry.js +164 -61
  222. package/dist/services/tool-scope.d.ts +58 -0
  223. package/dist/services/tool-scope.js +99 -0
  224. package/dist/services/vcs/azure-devops.d.ts +66 -1
  225. package/dist/services/vcs/azure-devops.js +192 -21
  226. package/dist/services/vcs/types.d.ts +1 -1
  227. package/dist/services/watch/project-resolver.js +1 -0
  228. package/dist/skills/auto-sprint-args/SKILL.md +2 -2
  229. package/dist/skills/fleet-sprint-cli/SKILL.md +48 -6
  230. package/dist/skills/pm/SKILL.md +4 -4
  231. package/dist/skills/pm/cost.md +0 -3
  232. package/dist/skills/pm/fleet-addendum.md +2 -2
  233. package/dist/skills/pm/index.md +4 -2
  234. package/dist/skills/pm/kb-reconcile.md +29 -14
  235. package/dist/skills/pm/kb-review.md +1 -0
  236. package/dist/skills/pm/sprint.md +5 -5
  237. package/dist/tools/check-status.d.ts +60 -9
  238. package/dist/tools/check-status.js +211 -52
  239. package/dist/tools/child-id-allocator.d.ts +2 -2
  240. package/dist/tools/child-id-allocator.js +1 -1
  241. package/dist/tools/code-index-heal.d.ts +8 -0
  242. package/dist/tools/code-index-heal.js +21 -0
  243. package/dist/tools/code-index-state.d.ts +45 -0
  244. package/dist/tools/code-index-state.js +115 -0
  245. package/dist/tools/code-intelligence-codebase-memory.js +6 -33
  246. package/dist/tools/code-intelligence-freshness.js +1 -1
  247. package/dist/tools/code-intelligence-gitnexus.d.ts +30 -0
  248. package/dist/tools/code-intelligence-gitnexus.js +333 -57
  249. package/dist/tools/code-intelligence-kb-enrich.js +7 -6
  250. package/dist/tools/code-intelligence-readiness.d.ts +99 -0
  251. package/dist/tools/code-intelligence-readiness.js +206 -0
  252. package/dist/tools/code-intelligence-reindex.d.ts +195 -0
  253. package/dist/tools/code-intelligence-reindex.js +530 -50
  254. package/dist/tools/code-intelligence-telemetry.d.ts +6 -1
  255. package/dist/tools/code-intelligence-telemetry.js +12 -3
  256. package/dist/tools/code-intelligence.d.ts +81 -31
  257. package/dist/tools/code-intelligence.js +156 -52
  258. package/dist/tools/compose-permissions.d.ts +63 -2
  259. package/dist/tools/compose-permissions.js +673 -72
  260. package/dist/tools/credential-store-set.js +1 -1
  261. package/dist/tools/execute-command.d.ts +11 -0
  262. package/dist/tools/execute-command.js +111 -32
  263. package/dist/tools/execute-prompt.d.ts +69 -12
  264. package/dist/tools/execute-prompt.js +1610 -895
  265. package/dist/tools/kb-bible-commit.d.ts +65 -0
  266. package/dist/tools/kb-bible-commit.js +239 -0
  267. package/dist/tools/kb-capture.d.ts +15 -11
  268. package/dist/tools/kb-capture.js +71 -16
  269. package/dist/tools/kb-context.d.ts +27 -7
  270. package/dist/tools/kb-context.js +60 -9
  271. package/dist/tools/kb-export.d.ts +98 -9
  272. package/dist/tools/kb-export.js +230 -92
  273. package/dist/tools/kb-feedback.d.ts +13 -9
  274. package/dist/tools/kb-feedback.js +16 -8
  275. package/dist/tools/kb-freshness-sweep.d.ts +11 -7
  276. package/dist/tools/kb-freshness-sweep.js +10 -8
  277. package/dist/tools/kb-harvest.d.ts +11 -7
  278. package/dist/tools/kb-harvest.js +7 -7
  279. package/dist/tools/kb-import.d.ts +26 -10
  280. package/dist/tools/kb-import.js +170 -159
  281. package/dist/tools/kb-invalidate.d.ts +17 -10
  282. package/dist/tools/kb-invalidate.js +41 -8
  283. package/dist/tools/kb-list.d.ts +14 -10
  284. package/dist/tools/kb-list.js +33 -11
  285. package/dist/tools/kb-promote.d.ts +11 -7
  286. package/dist/tools/kb-promote.js +14 -8
  287. package/dist/tools/kb-query.d.ts +21 -11
  288. package/dist/tools/kb-query.js +76 -13
  289. package/dist/tools/kb-reconcile-prefilter.d.ts +11 -7
  290. package/dist/tools/kb-reconcile-prefilter.js +13 -9
  291. package/dist/tools/kb-resolve-contradiction.d.ts +11 -7
  292. package/dist/tools/kb-resolve-contradiction.js +10 -8
  293. package/dist/tools/kb-session-prime.d.ts +14 -7
  294. package/dist/tools/kb-session-prime.js +44 -44
  295. package/dist/tools/kb-setup.d.ts +11 -4
  296. package/dist/tools/kb-setup.js +146 -27
  297. package/dist/tools/kb-stats.d.ts +11 -10
  298. package/dist/tools/kb-stats.js +84 -82
  299. package/dist/tools/list-members.d.ts +2 -2
  300. package/dist/tools/list-members.js +6 -2
  301. package/dist/tools/member-detail.d.ts +5 -2
  302. package/dist/tools/member-detail.js +105 -17
  303. package/dist/tools/member-reservation.d.ts +60 -3
  304. package/dist/tools/member-reservation.js +61 -20
  305. package/dist/tools/provision-auth.d.ts +118 -1
  306. package/dist/tools/provision-auth.js +402 -92
  307. package/dist/tools/provision-vcs-auth.d.ts +93 -3
  308. package/dist/tools/provision-vcs-auth.js +209 -49
  309. package/dist/tools/receive-files.js +3 -1
  310. package/dist/tools/register-member.d.ts +44 -15
  311. package/dist/tools/register-member.js +175 -70
  312. package/dist/tools/remove-member.js +118 -15
  313. package/dist/tools/send-email.d.ts +2 -2
  314. package/dist/tools/send-files.js +6 -4
  315. package/dist/tools/session-stats.d.ts +17 -0
  316. package/dist/tools/session-stats.js +27 -0
  317. package/dist/tools/setup-git-app.js +11 -7
  318. package/dist/tools/shutdown-server.d.ts +2 -0
  319. package/dist/tools/shutdown-server.js +28 -1
  320. package/dist/tools/update-agent-cli.d.ts +19 -0
  321. package/dist/tools/update-agent-cli.js +59 -2
  322. package/dist/tools/update-member.d.ts +23 -17
  323. package/dist/tools/update-member.js +181 -18
  324. package/dist/tools/vcs-credential-exec.d.ts +127 -0
  325. package/dist/tools/vcs-credential-exec.js +203 -0
  326. package/dist/types.d.ts +111 -1
  327. package/dist/utils/agent-helpers.js +2 -0
  328. package/dist/utils/auth-env.d.ts +15 -4
  329. package/dist/utils/auth-env.js +52 -23
  330. package/dist/utils/find-on-path.d.ts +37 -0
  331. package/dist/utils/find-on-path.js +85 -0
  332. package/dist/utils/log-helpers.d.ts +37 -0
  333. package/dist/utils/log-helpers.js +108 -22
  334. package/dist/utils/owner-only-fs.d.ts +56 -0
  335. package/dist/utils/owner-only-fs.js +98 -0
  336. package/dist/utils/process-utils.d.ts +28 -0
  337. package/dist/utils/process-utils.js +68 -0
  338. package/dist/utils/prompt-errors.js +11 -2
  339. package/dist/utils/session-caller.d.ts +4 -2
  340. package/dist/utils/session-caller.js +3 -2
  341. package/dist/utils/shell-escape.d.ts +58 -3
  342. package/dist/utils/shell-escape.js +91 -5
  343. package/dist/utils/ssh-error-messages.js +3 -0
  344. package/dist/utils/vcs-provider-detect.d.ts +65 -0
  345. package/dist/utils/vcs-provider-detect.js +109 -0
  346. package/dist/utils/workspace-trust.d.ts +26 -0
  347. package/dist/utils/workspace-trust.js +91 -1
  348. package/dist/workflows/auto-sprint.js +397 -56
  349. package/package.json +15 -10
  350. package/packages/apra-fleet-client/package.json +2 -2
  351. package/packages/apra-fleet-client/src/client/api.mjs +864 -31
  352. package/packages/apra-fleet-client/src/client/auto-start.mjs +434 -0
  353. package/packages/apra-fleet-client/src/client/client.mjs +9 -0
  354. package/packages/apra-fleet-client/src/client/errors.mjs +6 -2
  355. package/packages/apra-fleet-client/src/client/factory.mjs +23 -4
  356. package/packages/apra-fleet-client/src/client/reconnecting-transport.mjs +137 -0
  357. package/packages/apra-fleet-client/src/client/server-resolution.mjs +267 -30
  358. package/packages/apra-fleet-client/src/client/transport.mjs +37 -3
  359. package/packages/apra-fleet-se/apra-pm/agents/_shared/GRAPH-SEMANTICS.md +10 -2
  360. package/packages/apra-fleet-se/apra-pm/agents/backlog-groomer.md +87 -14
  361. package/packages/apra-fleet-se/apra-pm/agents/ci-watcher.md +35 -9
  362. package/packages/apra-fleet-se/apra-pm/agents/deployer.md +63 -11
  363. package/packages/apra-fleet-se/apra-pm/agents/doer.md +99 -41
  364. package/packages/apra-fleet-se/apra-pm/agents/harvester.md +47 -27
  365. package/packages/apra-fleet-se/apra-pm/agents/integ-test-runner.md +38 -10
  366. package/packages/apra-fleet-se/apra-pm/agents/kb-reconciler.md +37 -7
  367. package/packages/apra-fleet-se/apra-pm/agents/plan-reviewer.md +145 -32
  368. package/packages/apra-fleet-se/apra-pm/agents/planner.md +180 -69
  369. package/packages/apra-fleet-se/apra-pm/agents/regression-test-runner.md +98 -64
  370. package/packages/apra-fleet-se/apra-pm/agents/reviewer.md +117 -45
  371. package/packages/apra-fleet-se/apra-pm/agents/schemas/backlog-groomer-output.json +1 -1
  372. package/packages/apra-fleet-se/apra-pm/agents/schemas/doer-output.json +32 -0
  373. package/packages/apra-fleet-se/apra-pm/agents/schemas/harvester-input.json +1 -5
  374. package/packages/apra-fleet-se/apra-pm/agents/schemas/plan-reviewer-output.json +37 -0
  375. package/packages/apra-fleet-se/apra-pm/agents/schemas/planner-output.json +1 -1
  376. package/packages/apra-fleet-se/apra-pm/agents/schemas/regression-test-runner-output.json +41 -7
  377. package/packages/apra-fleet-se/apra-pm/agents/schemas/reviewer-output.json +62 -3
  378. package/packages/apra-fleet-se/apra-pm/skills/pm/SKILL.md +4 -4
  379. package/packages/apra-fleet-se/apra-pm/skills/pm/cost.md +0 -3
  380. package/packages/apra-fleet-se/apra-pm/skills/pm/fleet-addendum.md +2 -2
  381. package/packages/apra-fleet-se/apra-pm/skills/pm/index.md +4 -2
  382. package/packages/apra-fleet-se/apra-pm/skills/pm/kb-reconcile.md +29 -14
  383. package/packages/apra-fleet-se/apra-pm/skills/pm/kb-review.md +1 -0
  384. package/packages/apra-fleet-se/apra-pm/skills/pm/sprint.md +5 -5
  385. package/packages/apra-fleet-se/bin/cli.mjs +326 -48
  386. package/packages/apra-fleet-se/bin/serve.mjs +218 -11
  387. package/packages/apra-fleet-se/fleet-sprint/abort.mjs +517 -0
  388. package/packages/apra-fleet-se/fleet-sprint/backlog-role.mjs +93 -0
  389. package/packages/apra-fleet-se/fleet-sprint/beads-children.mjs +646 -0
  390. package/packages/apra-fleet-se/fleet-sprint/beads-identity-check.mjs +825 -0
  391. package/packages/apra-fleet-se/fleet-sprint/beads-identity.mjs +217 -0
  392. package/packages/apra-fleet-se/fleet-sprint/beads-memory-hygiene.mjs +201 -0
  393. package/packages/apra-fleet-se/fleet-sprint/beads-scope.mjs +745 -0
  394. package/packages/apra-fleet-se/fleet-sprint/beads-transitions.mjs +447 -0
  395. package/packages/apra-fleet-se/fleet-sprint/branch-ensure.mjs +96 -0
  396. package/packages/apra-fleet-se/fleet-sprint/ci-gate.mjs +353 -0
  397. package/packages/apra-fleet-se/fleet-sprint/conflict-ladder.mjs +20 -0
  398. package/packages/apra-fleet-se/fleet-sprint/contracts.mjs +121 -15
  399. package/packages/apra-fleet-se/fleet-sprint/coordination.mjs +539 -0
  400. package/packages/apra-fleet-se/fleet-sprint/dispatch-accounting.mjs +270 -0
  401. package/packages/apra-fleet-se/fleet-sprint/dispatch-failure.mjs +204 -0
  402. package/packages/apra-fleet-se/fleet-sprint/dispatch-role.mjs +1310 -0
  403. package/packages/apra-fleet-se/fleet-sprint/dispatch-safety-guard.mjs +216 -4
  404. package/packages/apra-fleet-se/fleet-sprint/docs/README.md +53 -15
  405. package/packages/apra-fleet-se/fleet-sprint/docs/dolt-sync-redesign.md +281 -0
  406. package/packages/apra-fleet-se/fleet-sprint/docs/escalate-to-llm-design.md +1 -1
  407. package/packages/apra-fleet-se/fleet-sprint/docs/fleet-sprint-diagram.md +3 -3
  408. package/packages/apra-fleet-se/fleet-sprint/docs/run-sprint-cycle-prelude-decision.md +215 -0
  409. package/packages/apra-fleet-se/fleet-sprint/dolt-literal-guard.mjs +56 -1
  410. package/packages/apra-fleet-se/fleet-sprint/dolt-sync.mjs +1327 -44
  411. package/packages/apra-fleet-se/fleet-sprint/errors.mjs +470 -4
  412. package/packages/apra-fleet-se/fleet-sprint/explicit-id-create-guard.mjs +501 -0
  413. package/packages/apra-fleet-se/fleet-sprint/fatal-diagnostics.mjs +134 -0
  414. package/packages/apra-fleet-se/fleet-sprint/full-db-fetch-guard.mjs +102 -0
  415. package/packages/apra-fleet-se/fleet-sprint/git-sync.mjs +747 -0
  416. package/packages/apra-fleet-se/fleet-sprint/git-topology.mjs +543 -0
  417. package/packages/apra-fleet-se/fleet-sprint/guarded-modules.mjs +613 -0
  418. package/packages/apra-fleet-se/fleet-sprint/inline-ladder-guard.mjs +216 -0
  419. package/packages/apra-fleet-se/fleet-sprint/kb-hints.mjs +181 -0
  420. package/packages/apra-fleet-se/fleet-sprint/kb-injection.mjs +64 -0
  421. package/packages/apra-fleet-se/fleet-sprint/kb-maintainer.mjs +298 -0
  422. package/packages/apra-fleet-se/fleet-sprint/kb.mjs +1684 -0
  423. package/packages/apra-fleet-se/fleet-sprint/lower-quality.mjs +39 -0
  424. package/packages/apra-fleet-se/fleet-sprint/mcp-result.mjs +75 -0
  425. package/packages/apra-fleet-se/fleet-sprint/member-align.mjs +391 -0
  426. package/packages/apra-fleet-se/fleet-sprint/member-call.mjs +374 -0
  427. package/packages/apra-fleet-se/fleet-sprint/member-init-probe.mjs +644 -0
  428. package/packages/apra-fleet-se/fleet-sprint/member-provisioning.mjs +699 -0
  429. package/packages/apra-fleet-se/fleet-sprint/member-sync.mjs +802 -0
  430. package/packages/apra-fleet-se/fleet-sprint/member-target.mjs +93 -0
  431. package/packages/apra-fleet-se/fleet-sprint/newtask-text.mjs +266 -0
  432. package/packages/apra-fleet-se/fleet-sprint/orphan-reclaim.mjs +153 -0
  433. package/packages/apra-fleet-se/fleet-sprint/parent-notes-staleness.mjs +201 -0
  434. package/packages/apra-fleet-se/fleet-sprint/phases/deploy.mjs +218 -0
  435. package/packages/apra-fleet-se/fleet-sprint/phases/develop.mjs +869 -0
  436. package/packages/apra-fleet-se/fleet-sprint/phases/ensure-sprint-branch.mjs +295 -0
  437. package/packages/apra-fleet-se/fleet-sprint/phases/final-review.mjs +466 -0
  438. package/packages/apra-fleet-se/fleet-sprint/phases/harvest.mjs +212 -0
  439. package/packages/apra-fleet-se/fleet-sprint/phases/integ-test.mjs +358 -0
  440. package/packages/apra-fleet-se/fleet-sprint/phases/plan.mjs +395 -0
  441. package/packages/apra-fleet-se/fleet-sprint/phases/publish-pr.mjs +345 -0
  442. package/packages/apra-fleet-se/fleet-sprint/phases/re-review.mjs +264 -0
  443. package/packages/apra-fleet-se/fleet-sprint/phases/regression-test.mjs +179 -0
  444. package/packages/apra-fleet-se/fleet-sprint/phases/replan.mjs +230 -0
  445. package/packages/apra-fleet-se/fleet-sprint/phases/review.mjs +365 -0
  446. package/packages/apra-fleet-se/fleet-sprint/pr-body.mjs +259 -0
  447. package/packages/apra-fleet-se/fleet-sprint/prompts.mjs +617 -0
  448. package/packages/apra-fleet-se/fleet-sprint/role-policies.mjs +1434 -0
  449. package/packages/apra-fleet-se/fleet-sprint/round-session.mjs +100 -0
  450. package/packages/apra-fleet-se/fleet-sprint/runner.js +2289 -9928
  451. package/packages/apra-fleet-se/fleet-sprint/se-os-commands.mjs +24 -0
  452. package/packages/apra-fleet-se/fleet-sprint/se-posix.mjs +147 -12
  453. package/packages/apra-fleet-se/fleet-sprint/se-windows.mjs +111 -0
  454. package/packages/apra-fleet-se/fleet-sprint/shell-command-guard.mjs +347 -0
  455. package/packages/apra-fleet-se/fleet-sprint/skills/fleet-sprint-cli/SKILL.md +48 -6
  456. package/packages/apra-fleet-se/fleet-sprint/skills/fleet-supervisor/SKILL.md +98 -25
  457. package/packages/apra-fleet-se/fleet-sprint/sprint-args.mjs +590 -0
  458. package/packages/apra-fleet-se/fleet-sprint/sprint-report.mjs +339 -0
  459. package/packages/apra-fleet-se/fleet-sprint/sprint-state.mjs +185 -0
  460. package/packages/apra-fleet-se/fleet-sprint/unbracketed-push-guard.mjs +234 -0
  461. package/packages/apra-fleet-se/fleet-sprint/usage-limit-controller.mjs +218 -0
  462. package/packages/apra-fleet-se/fleet-sprint/vcs-auth.mjs +1445 -0
  463. package/packages/apra-fleet-se/fleet-sprint/vcs-module.mjs +284 -23
  464. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/azure-devops.mjs +170 -21
  465. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/bitbucket.mjs +28 -0
  466. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/github.mjs +354 -0
  467. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/index.mjs +189 -16
  468. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/shell-helpers.mjs +9 -4
  469. package/packages/apra-fleet-se/fleet-sprint/verify-block.mjs +152 -0
  470. package/packages/apra-fleet-se/fleet-sprint/viewer-extensions.mjs +311 -22
  471. package/packages/apra-fleet-se/fleet-sprint/worklists.mjs +559 -0
  472. package/packages/apra-fleet-se/package.json +2 -2
  473. package/packages/apra-fleet-se/src/supervisor/api.mjs +919 -0
  474. package/packages/apra-fleet-se/src/supervisor/backlog-member.mjs +332 -0
  475. package/packages/apra-fleet-se/src/supervisor/backlog.mjs +982 -0
  476. package/packages/apra-fleet-se/src/supervisor/beads-identity.mjs +246 -0
  477. package/packages/apra-fleet-se/src/supervisor/beads-view.mjs +438 -0
  478. package/packages/apra-fleet-se/src/supervisor/child-port.mjs +36 -0
  479. package/packages/apra-fleet-se/src/supervisor/dashboard.mjs +1659 -0
  480. package/packages/apra-fleet-se/src/supervisor/dolt-mutex.mjs +350 -0
  481. package/packages/apra-fleet-se/src/supervisor/dolt-orphan-sweep.mjs +338 -0
  482. package/packages/apra-fleet-se/src/supervisor/fleet-members.mjs +279 -0
  483. package/packages/apra-fleet-se/src/supervisor/history-view.mjs +276 -0
  484. package/packages/apra-fleet-se/src/supervisor/history.mjs +328 -0
  485. package/packages/apra-fleet-se/src/supervisor/id-allocator.mjs +521 -0
  486. package/packages/apra-fleet-se/src/supervisor/launch-form.mjs +444 -0
  487. package/packages/apra-fleet-se/src/supervisor/ledger.mjs +629 -0
  488. package/packages/apra-fleet-se/src/supervisor/lib/exec-bd.mjs +303 -0
  489. package/packages/apra-fleet-se/src/supervisor/log-timestamp.mjs +51 -0
  490. package/packages/apra-fleet-se/src/supervisor/log-view.mjs +159 -0
  491. package/packages/apra-fleet-se/src/supervisor/proxy.mjs +474 -0
  492. package/packages/apra-fleet-se/src/supervisor/readopt.mjs +136 -0
  493. package/packages/apra-fleet-se/src/supervisor/reconcile.mjs +263 -0
  494. package/packages/apra-fleet-se/src/supervisor/rename-with-retry.mjs +87 -0
  495. package/packages/apra-fleet-se/src/supervisor/scope-overlap.mjs +327 -0
  496. package/packages/apra-fleet-se/src/supervisor/self-log.mjs +133 -0
  497. package/packages/apra-fleet-se/src/supervisor/server.mjs +399 -0
  498. package/packages/apra-fleet-se/src/supervisor/spawner.mjs +542 -0
  499. package/packages/apra-fleet-se/src/supervisor/sprint-identity.mjs +96 -0
  500. package/packages/apra-fleet-se/src/supervisor/watchdog.mjs +987 -0
  501. package/packages/apra-fleet-workflow/package.json +1 -1
  502. package/packages/apra-fleet-workflow/src/viewer/index.mjs +81 -15
  503. package/packages/apra-fleet-workflow/src/viewer/run-summary.mjs +127 -0
  504. package/packages/apra-fleet-workflow/src/workflow/index.mjs +118 -10
  505. package/packages/apra-fleet-workflow/src/workflow/pricing.mjs +75 -25
  506. package/skills/fleet/SKILL.md +8 -8
  507. package/skills/fleet/auth-azdevops.md +14 -3
  508. package/skills/fleet/auth-bitbucket.md +2 -2
  509. package/skills/fleet/auth-github.md +5 -4
  510. package/skills/fleet/onboarding.md +3 -3
  511. package/skills/fleet/permissions.md +14 -1
  512. package/skills/fleet/profiles/node.json +1 -1
  513. package/skills/fleet/profiles/tag-kb-reconciler.json +2 -6
  514. package/skills/fleet/troubleshooting.md +3 -3
  515. package/version.json +1 -1
  516. package/dist/cli/agent-transform.d.ts.map +0 -1
  517. package/dist/cli/agent-transform.js.map +0 -1
  518. package/dist/cli/auth.d.ts.map +0 -1
  519. package/dist/cli/auth.js.map +0 -1
  520. package/dist/cli/config.d.ts.map +0 -1
  521. package/dist/cli/config.js.map +0 -1
  522. package/dist/cli/dolt-install.d.ts.map +0 -1
  523. package/dist/cli/dolt-install.js.map +0 -1
  524. package/dist/cli/install-guard.d.ts.map +0 -1
  525. package/dist/cli/install-guard.js.map +0 -1
  526. package/dist/cli/install.d.ts.map +0 -1
  527. package/dist/cli/install.js.map +0 -1
  528. package/dist/cli/join.d.ts.map +0 -1
  529. package/dist/cli/join.js.map +0 -1
  530. package/dist/cli/kb-commit.d.ts.map +0 -1
  531. package/dist/cli/kb-commit.js.map +0 -1
  532. package/dist/cli/kb-directives.d.ts.map +0 -1
  533. package/dist/cli/kb-directives.js.map +0 -1
  534. package/dist/cli/kb-import.d.ts.map +0 -1
  535. package/dist/cli/kb-import.js.map +0 -1
  536. package/dist/cli/register-member.d.ts.map +0 -1
  537. package/dist/cli/register-member.js.map +0 -1
  538. package/dist/cli/restart.d.ts.map +0 -1
  539. package/dist/cli/restart.js.map +0 -1
  540. package/dist/cli/secret.d.ts.map +0 -1
  541. package/dist/cli/secret.js.map +0 -1
  542. package/dist/cli/spoke.d.ts.map +0 -1
  543. package/dist/cli/spoke.js.map +0 -1
  544. package/dist/cli/start.d.ts.map +0 -1
  545. package/dist/cli/start.js.map +0 -1
  546. package/dist/cli/status.d.ts.map +0 -1
  547. package/dist/cli/status.js.map +0 -1
  548. package/dist/cli/stop.d.ts.map +0 -1
  549. package/dist/cli/stop.js.map +0 -1
  550. package/dist/cli/uninstall.d.ts.map +0 -1
  551. package/dist/cli/uninstall.js.map +0 -1
  552. package/dist/cli/update.d.ts.map +0 -1
  553. package/dist/cli/update.js.map +0 -1
  554. package/dist/cli/watch.d.ts.map +0 -1
  555. package/dist/cli/watch.js.map +0 -1
  556. package/dist/cli/workflow-assets.d.ts.map +0 -1
  557. package/dist/cli/workflow-assets.js.map +0 -1
  558. package/dist/cli/workflow.d.ts.map +0 -1
  559. package/dist/cli/workflow.js.map +0 -1
  560. package/dist/commands/kb-server.d.ts.map +0 -1
  561. package/dist/commands/kb-server.js.map +0 -1
  562. package/dist/delivery-mode.d.ts.map +0 -1
  563. package/dist/delivery-mode.js.map +0 -1
  564. package/dist/hub-service/activity.d.ts.map +0 -1
  565. package/dist/hub-service/activity.js.map +0 -1
  566. package/dist/hub-service/audit-log.d.ts.map +0 -1
  567. package/dist/hub-service/audit-log.js.map +0 -1
  568. package/dist/hub-service/db/pool.d.ts.map +0 -1
  569. package/dist/hub-service/db/pool.js.map +0 -1
  570. package/dist/hub-service/enrollment.d.ts.map +0 -1
  571. package/dist/hub-service/enrollment.js.map +0 -1
  572. package/dist/hub-service/envelope-routes.d.ts.map +0 -1
  573. package/dist/hub-service/envelope-routes.js.map +0 -1
  574. package/dist/hub-service/handlers/installers.d.ts.map +0 -1
  575. package/dist/hub-service/handlers/installers.js.map +0 -1
  576. package/dist/hub-service/http-server.d.ts.map +0 -1
  577. package/dist/hub-service/http-server.js.map +0 -1
  578. package/dist/hub-service/hub-jwt.d.ts.map +0 -1
  579. package/dist/hub-service/hub-jwt.js.map +0 -1
  580. package/dist/hub-service/jwt-revocation.d.ts.map +0 -1
  581. package/dist/hub-service/jwt-revocation.js.map +0 -1
  582. package/dist/hub-service/machines.d.ts.map +0 -1
  583. package/dist/hub-service/machines.js.map +0 -1
  584. package/dist/hub-service/main.d.ts.map +0 -1
  585. package/dist/hub-service/main.js.map +0 -1
  586. package/dist/hub-service/member-tokens.d.ts.map +0 -1
  587. package/dist/hub-service/member-tokens.js.map +0 -1
  588. package/dist/hub-service/member-view.d.ts.map +0 -1
  589. package/dist/hub-service/member-view.js.map +0 -1
  590. package/dist/hub-service/members.d.ts.map +0 -1
  591. package/dist/hub-service/members.js.map +0 -1
  592. package/dist/hub-service/presence.d.ts.map +0 -1
  593. package/dist/hub-service/presence.js.map +0 -1
  594. package/dist/hub-service/project-view.d.ts.map +0 -1
  595. package/dist/hub-service/project-view.js.map +0 -1
  596. package/dist/hub-service/projects.d.ts.map +0 -1
  597. package/dist/hub-service/projects.js.map +0 -1
  598. package/dist/hub-service/relay-queue.d.ts.map +0 -1
  599. package/dist/hub-service/relay-queue.js.map +0 -1
  600. package/dist/hub-service/session-jwt.d.ts.map +0 -1
  601. package/dist/hub-service/session-jwt.js.map +0 -1
  602. package/dist/hub-service/usage.d.ts.map +0 -1
  603. package/dist/hub-service/usage.js.map +0 -1
  604. package/dist/hub-service/users.d.ts.map +0 -1
  605. package/dist/hub-service/users.js.map +0 -1
  606. package/dist/hub-service/workspaces.d.ts.map +0 -1
  607. package/dist/hub-service/workspaces.js.map +0 -1
  608. package/dist/index.d.ts.map +0 -1
  609. package/dist/index.js.map +0 -1
  610. package/dist/onboarding/text.d.ts.map +0 -1
  611. package/dist/onboarding/text.js.map +0 -1
  612. package/dist/os/git-bash-candidates.d.ts.map +0 -1
  613. package/dist/os/git-bash-candidates.js.map +0 -1
  614. package/dist/os/index.d.ts.map +0 -1
  615. package/dist/os/index.js.map +0 -1
  616. package/dist/os/linux.d.ts.map +0 -1
  617. package/dist/os/linux.js.map +0 -1
  618. package/dist/os/macos.d.ts.map +0 -1
  619. package/dist/os/macos.js.map +0 -1
  620. package/dist/os/os-commands.d.ts.map +0 -1
  621. package/dist/os/os-commands.js.map +0 -1
  622. package/dist/os/windows-gitbash.d.ts.map +0 -1
  623. package/dist/os/windows-gitbash.js.map +0 -1
  624. package/dist/os/windows-wrapper.d.ts.map +0 -1
  625. package/dist/os/windows-wrapper.js.map +0 -1
  626. package/dist/os/windows.d.ts.map +0 -1
  627. package/dist/os/windows.js.map +0 -1
  628. package/dist/paths.d.ts.map +0 -1
  629. package/dist/paths.js.map +0 -1
  630. package/dist/providers/agy.d.ts.map +0 -1
  631. package/dist/providers/agy.js.map +0 -1
  632. package/dist/providers/claude.d.ts.map +0 -1
  633. package/dist/providers/claude.js.map +0 -1
  634. package/dist/providers/codex.d.ts.map +0 -1
  635. package/dist/providers/codex.js.map +0 -1
  636. package/dist/providers/copilot.d.ts.map +0 -1
  637. package/dist/providers/copilot.js.map +0 -1
  638. package/dist/providers/email/headers.d.ts.map +0 -1
  639. package/dist/providers/email/headers.js.map +0 -1
  640. package/dist/providers/email/index.d.ts.map +0 -1
  641. package/dist/providers/email/index.js.map +0 -1
  642. package/dist/providers/email/provider.d.ts.map +0 -1
  643. package/dist/providers/email/provider.js.map +0 -1
  644. package/dist/providers/email/sendgrid.d.ts.map +0 -1
  645. package/dist/providers/email/sendgrid.js.map +0 -1
  646. package/dist/providers/email/smtp.d.ts.map +0 -1
  647. package/dist/providers/email/smtp.js.map +0 -1
  648. package/dist/providers/index.d.ts.map +0 -1
  649. package/dist/providers/index.js.map +0 -1
  650. package/dist/providers/none.d.ts.map +0 -1
  651. package/dist/providers/none.js.map +0 -1
  652. package/dist/providers/opencode.d.ts.map +0 -1
  653. package/dist/providers/opencode.js.map +0 -1
  654. package/dist/providers/provider.d.ts.map +0 -1
  655. package/dist/providers/provider.js.map +0 -1
  656. package/dist/services/agent-provisioner.d.ts.map +0 -1
  657. package/dist/services/agent-provisioner.js.map +0 -1
  658. package/dist/services/auth-socket.d.ts.map +0 -1
  659. package/dist/services/auth-socket.js.map +0 -1
  660. package/dist/services/auth-web.d.ts.map +0 -1
  661. package/dist/services/auth-web.js.map +0 -1
  662. package/dist/services/budget-awareness.d.ts.map +0 -1
  663. package/dist/services/budget-awareness.js.map +0 -1
  664. package/dist/services/cloud/activity.d.ts.map +0 -1
  665. package/dist/services/cloud/activity.js.map +0 -1
  666. package/dist/services/cloud/aws.d.ts.map +0 -1
  667. package/dist/services/cloud/aws.js.map +0 -1
  668. package/dist/services/cloud/cost.d.ts.map +0 -1
  669. package/dist/services/cloud/cost.js.map +0 -1
  670. package/dist/services/cloud/idle-manager.d.ts.map +0 -1
  671. package/dist/services/cloud/idle-manager.js.map +0 -1
  672. package/dist/services/cloud/lifecycle.d.ts.map +0 -1
  673. package/dist/services/cloud/lifecycle.js.map +0 -1
  674. package/dist/services/cloud/task-wrapper.d.ts.map +0 -1
  675. package/dist/services/cloud/task-wrapper.js.map +0 -1
  676. package/dist/services/cloud/types.d.ts.map +0 -1
  677. package/dist/services/cloud/types.js.map +0 -1
  678. package/dist/services/cloud-sync.d.ts.map +0 -1
  679. package/dist/services/cloud-sync.js.map +0 -1
  680. package/dist/services/context-admission.d.ts.map +0 -1
  681. package/dist/services/context-admission.js.map +0 -1
  682. package/dist/services/credential-cleanup.d.ts.map +0 -1
  683. package/dist/services/credential-cleanup.js.map +0 -1
  684. package/dist/services/credential-store.d.ts.map +0 -1
  685. package/dist/services/credential-store.js.map +0 -1
  686. package/dist/services/event-bus.d.ts.map +0 -1
  687. package/dist/services/event-bus.js.map +0 -1
  688. package/dist/services/file-chunker.d.ts.map +0 -1
  689. package/dist/services/file-chunker.js.map +0 -1
  690. package/dist/services/file-transfer-relay.d.ts.map +0 -1
  691. package/dist/services/file-transfer-relay.js.map +0 -1
  692. package/dist/services/file-transfer.d.ts.map +0 -1
  693. package/dist/services/file-transfer.js.map +0 -1
  694. package/dist/services/git-config.d.ts.map +0 -1
  695. package/dist/services/git-config.js.map +0 -1
  696. package/dist/services/github-app.d.ts.map +0 -1
  697. package/dist/services/github-app.js.map +0 -1
  698. package/dist/services/http-transport.d.ts.map +0 -1
  699. package/dist/services/http-transport.js.map +0 -1
  700. package/dist/services/hub-client.d.ts.map +0 -1
  701. package/dist/services/hub-client.js.map +0 -1
  702. package/dist/services/icons.d.ts.map +0 -1
  703. package/dist/services/icons.js.map +0 -1
  704. package/dist/services/jwt.d.ts.map +0 -1
  705. package/dist/services/jwt.js.map +0 -1
  706. package/dist/services/knowledge/audn.d.ts.map +0 -1
  707. package/dist/services/knowledge/audn.js.map +0 -1
  708. package/dist/services/knowledge/file-hash.d.ts.map +0 -1
  709. package/dist/services/knowledge/file-hash.js.map +0 -1
  710. package/dist/services/knowledge/http-provider.d.ts.map +0 -1
  711. package/dist/services/knowledge/http-provider.js.map +0 -1
  712. package/dist/services/knowledge/kb-providers.d.ts.map +0 -1
  713. package/dist/services/knowledge/kb-providers.js.map +0 -1
  714. package/dist/services/knowledge/kb-scope-input.d.ts +0 -5
  715. package/dist/services/knowledge/kb-scope-input.d.ts.map +0 -1
  716. package/dist/services/knowledge/kb-scope-input.js +0 -11
  717. package/dist/services/knowledge/kb-scope-input.js.map +0 -1
  718. package/dist/services/knowledge/kb-service.d.ts.map +0 -1
  719. package/dist/services/knowledge/kb-service.js.map +0 -1
  720. package/dist/services/knowledge/path-validation.d.ts.map +0 -1
  721. package/dist/services/knowledge/path-validation.js.map +0 -1
  722. package/dist/services/knowledge/pre-init.d.ts.map +0 -1
  723. package/dist/services/knowledge/pre-init.js.map +0 -1
  724. package/dist/services/knowledge/project-slug.d.ts.map +0 -1
  725. package/dist/services/knowledge/project-slug.js.map +0 -1
  726. package/dist/services/knowledge/sqlite-provider.d.ts.map +0 -1
  727. package/dist/services/knowledge/sqlite-provider.js.map +0 -1
  728. package/dist/services/knowledge/types.d.ts.map +0 -1
  729. package/dist/services/knowledge/types.js.map +0 -1
  730. package/dist/services/known-hosts.d.ts.map +0 -1
  731. package/dist/services/known-hosts.js.map +0 -1
  732. package/dist/services/known-sessions.d.ts.map +0 -1
  733. package/dist/services/known-sessions.js.map +0 -1
  734. package/dist/services/member-home.d.ts.map +0 -1
  735. package/dist/services/member-home.js.map +0 -1
  736. package/dist/services/member-remote-url.d.ts.map +0 -1
  737. package/dist/services/member-remote-url.js.map +0 -1
  738. package/dist/services/model-pricing.d.ts.map +0 -1
  739. package/dist/services/model-pricing.js.map +0 -1
  740. package/dist/services/onboarding.d.ts.map +0 -1
  741. package/dist/services/onboarding.js.map +0 -1
  742. package/dist/services/orphan-recovery.d.ts.map +0 -1
  743. package/dist/services/orphan-recovery.js.map +0 -1
  744. package/dist/services/pending-responses.d.ts.map +0 -1
  745. package/dist/services/pending-responses.js.map +0 -1
  746. package/dist/services/preflight-check.d.ts.map +0 -1
  747. package/dist/services/preflight-check.js.map +0 -1
  748. package/dist/services/registry.d.ts.map +0 -1
  749. package/dist/services/registry.js.map +0 -1
  750. package/dist/services/relay-context.d.ts.map +0 -1
  751. package/dist/services/relay-context.js.map +0 -1
  752. package/dist/services/relay-executor.d.ts.map +0 -1
  753. package/dist/services/relay-executor.js.map +0 -1
  754. package/dist/services/relay-request.d.ts.map +0 -1
  755. package/dist/services/relay-request.js.map +0 -1
  756. package/dist/services/relay-strategy.d.ts.map +0 -1
  757. package/dist/services/relay-strategy.js.map +0 -1
  758. package/dist/services/service-manager/index.d.ts.map +0 -1
  759. package/dist/services/service-manager/index.js.map +0 -1
  760. package/dist/services/service-manager/linux.d.ts.map +0 -1
  761. package/dist/services/service-manager/linux.js.map +0 -1
  762. package/dist/services/service-manager/macos.d.ts.map +0 -1
  763. package/dist/services/service-manager/macos.js.map +0 -1
  764. package/dist/services/service-manager/types.d.ts.map +0 -1
  765. package/dist/services/service-manager/types.js.map +0 -1
  766. package/dist/services/service-manager/windows.d.ts.map +0 -1
  767. package/dist/services/service-manager/windows.js.map +0 -1
  768. package/dist/services/session-registry.d.ts.map +0 -1
  769. package/dist/services/session-registry.js.map +0 -1
  770. package/dist/services/sftp.d.ts.map +0 -1
  771. package/dist/services/sftp.js.map +0 -1
  772. package/dist/services/shell-probe.d.ts.map +0 -1
  773. package/dist/services/shell-probe.js.map +0 -1
  774. package/dist/services/singleton.d.ts.map +0 -1
  775. package/dist/services/singleton.js.map +0 -1
  776. package/dist/services/sprint-coordination.d.ts.map +0 -1
  777. package/dist/services/sprint-coordination.js.map +0 -1
  778. package/dist/services/ssh.d.ts.map +0 -1
  779. package/dist/services/ssh.js.map +0 -1
  780. package/dist/services/stall/find-log-file.d.ts.map +0 -1
  781. package/dist/services/stall/find-log-file.js.map +0 -1
  782. package/dist/services/stall/index.d.ts.map +0 -1
  783. package/dist/services/stall/index.js.map +0 -1
  784. package/dist/services/stall/log-path-resolver.d.ts.map +0 -1
  785. package/dist/services/stall/log-path-resolver.js.map +0 -1
  786. package/dist/services/stall/read-log-tail.d.ts.map +0 -1
  787. package/dist/services/stall/read-log-tail.js.map +0 -1
  788. package/dist/services/stall/stall-detector.d.ts.map +0 -1
  789. package/dist/services/stall/stall-detector.js.map +0 -1
  790. package/dist/services/stall/stall-poller.d.ts.map +0 -1
  791. package/dist/services/stall/stall-poller.js.map +0 -1
  792. package/dist/services/stall/time-utils.d.ts.map +0 -1
  793. package/dist/services/stall/time-utils.js.map +0 -1
  794. package/dist/services/statusline.d.ts.map +0 -1
  795. package/dist/services/statusline.js.map +0 -1
  796. package/dist/services/strategy.d.ts.map +0 -1
  797. package/dist/services/strategy.js.map +0 -1
  798. package/dist/services/substitution-engine.d.ts.map +0 -1
  799. package/dist/services/substitution-engine.js.map +0 -1
  800. package/dist/services/task-cleanup.d.ts.map +0 -1
  801. package/dist/services/task-cleanup.js.map +0 -1
  802. package/dist/services/token-issuer.d.ts.map +0 -1
  803. package/dist/services/token-issuer.js.map +0 -1
  804. package/dist/services/tool-registry.d.ts.map +0 -1
  805. package/dist/services/tool-registry.js.map +0 -1
  806. package/dist/services/update-check.d.ts.map +0 -1
  807. package/dist/services/update-check.js.map +0 -1
  808. package/dist/services/user-config.d.ts.map +0 -1
  809. package/dist/services/user-config.js.map +0 -1
  810. package/dist/services/vcs/azure-devops.d.ts.map +0 -1
  811. package/dist/services/vcs/azure-devops.js.map +0 -1
  812. package/dist/services/vcs/bitbucket.d.ts.map +0 -1
  813. package/dist/services/vcs/bitbucket.js.map +0 -1
  814. package/dist/services/vcs/constants.d.ts.map +0 -1
  815. package/dist/services/vcs/constants.js.map +0 -1
  816. package/dist/services/vcs/github.d.ts.map +0 -1
  817. package/dist/services/vcs/github.js.map +0 -1
  818. package/dist/services/vcs/types.d.ts.map +0 -1
  819. package/dist/services/vcs/types.js.map +0 -1
  820. package/dist/services/version-check.d.ts.map +0 -1
  821. package/dist/services/version-check.js.map +0 -1
  822. package/dist/services/watch/fleet-log.d.ts.map +0 -1
  823. package/dist/services/watch/fleet-log.js.map +0 -1
  824. package/dist/services/watch/project-resolver.d.ts.map +0 -1
  825. package/dist/services/watch/project-resolver.js.map +0 -1
  826. package/dist/services/watch/transcript-formatter.d.ts.map +0 -1
  827. package/dist/services/watch/transcript-formatter.js.map +0 -1
  828. package/dist/smoke-test.d.ts.map +0 -1
  829. package/dist/smoke-test.js.map +0 -1
  830. package/dist/tools/check-status.d.ts.map +0 -1
  831. package/dist/tools/check-status.js.map +0 -1
  832. package/dist/tools/child-id-allocator.d.ts.map +0 -1
  833. package/dist/tools/child-id-allocator.js.map +0 -1
  834. package/dist/tools/cloud-control.d.ts.map +0 -1
  835. package/dist/tools/cloud-control.js.map +0 -1
  836. package/dist/tools/code-intelligence-codebase-memory.d.ts.map +0 -1
  837. package/dist/tools/code-intelligence-codebase-memory.js.map +0 -1
  838. package/dist/tools/code-intelligence-freshness.d.ts.map +0 -1
  839. package/dist/tools/code-intelligence-freshness.js.map +0 -1
  840. package/dist/tools/code-intelligence-gitnexus.d.ts.map +0 -1
  841. package/dist/tools/code-intelligence-gitnexus.js.map +0 -1
  842. package/dist/tools/code-intelligence-kb-enrich.d.ts.map +0 -1
  843. package/dist/tools/code-intelligence-kb-enrich.js.map +0 -1
  844. package/dist/tools/code-intelligence-reindex.d.ts.map +0 -1
  845. package/dist/tools/code-intelligence-reindex.js.map +0 -1
  846. package/dist/tools/code-intelligence-telemetry.d.ts.map +0 -1
  847. package/dist/tools/code-intelligence-telemetry.js.map +0 -1
  848. package/dist/tools/code-intelligence-tests.d.ts.map +0 -1
  849. package/dist/tools/code-intelligence-tests.js.map +0 -1
  850. package/dist/tools/code-intelligence.d.ts.map +0 -1
  851. package/dist/tools/code-intelligence.js.map +0 -1
  852. package/dist/tools/compose-permissions.d.ts.map +0 -1
  853. package/dist/tools/compose-permissions.js.map +0 -1
  854. package/dist/tools/credential-store-delete.d.ts.map +0 -1
  855. package/dist/tools/credential-store-delete.js.map +0 -1
  856. package/dist/tools/credential-store-list.d.ts.map +0 -1
  857. package/dist/tools/credential-store-list.js.map +0 -1
  858. package/dist/tools/credential-store-set.d.ts.map +0 -1
  859. package/dist/tools/credential-store-set.js.map +0 -1
  860. package/dist/tools/credential-store-update.d.ts.map +0 -1
  861. package/dist/tools/credential-store-update.js.map +0 -1
  862. package/dist/tools/dolt-push-mutex.d.ts.map +0 -1
  863. package/dist/tools/dolt-push-mutex.js.map +0 -1
  864. package/dist/tools/execute-command.d.ts.map +0 -1
  865. package/dist/tools/execute-command.js.map +0 -1
  866. package/dist/tools/execute-prompt.d.ts.map +0 -1
  867. package/dist/tools/execute-prompt.js.map +0 -1
  868. package/dist/tools/get-member-model-pricing.d.ts.map +0 -1
  869. package/dist/tools/get-member-model-pricing.js.map +0 -1
  870. package/dist/tools/kb-capture.d.ts.map +0 -1
  871. package/dist/tools/kb-capture.js.map +0 -1
  872. package/dist/tools/kb-context.d.ts.map +0 -1
  873. package/dist/tools/kb-context.js.map +0 -1
  874. package/dist/tools/kb-export.d.ts.map +0 -1
  875. package/dist/tools/kb-export.js.map +0 -1
  876. package/dist/tools/kb-feedback.d.ts.map +0 -1
  877. package/dist/tools/kb-feedback.js.map +0 -1
  878. package/dist/tools/kb-freshness-sweep.d.ts.map +0 -1
  879. package/dist/tools/kb-freshness-sweep.js.map +0 -1
  880. package/dist/tools/kb-harvest.d.ts.map +0 -1
  881. package/dist/tools/kb-harvest.js.map +0 -1
  882. package/dist/tools/kb-import.d.ts.map +0 -1
  883. package/dist/tools/kb-import.js.map +0 -1
  884. package/dist/tools/kb-invalidate.d.ts.map +0 -1
  885. package/dist/tools/kb-invalidate.js.map +0 -1
  886. package/dist/tools/kb-list.d.ts.map +0 -1
  887. package/dist/tools/kb-list.js.map +0 -1
  888. package/dist/tools/kb-promote.d.ts.map +0 -1
  889. package/dist/tools/kb-promote.js.map +0 -1
  890. package/dist/tools/kb-query.d.ts.map +0 -1
  891. package/dist/tools/kb-query.js.map +0 -1
  892. package/dist/tools/kb-reconcile-prefilter.d.ts.map +0 -1
  893. package/dist/tools/kb-reconcile-prefilter.js.map +0 -1
  894. package/dist/tools/kb-resolve-contradiction.d.ts.map +0 -1
  895. package/dist/tools/kb-resolve-contradiction.js.map +0 -1
  896. package/dist/tools/kb-session-prime.d.ts.map +0 -1
  897. package/dist/tools/kb-session-prime.js.map +0 -1
  898. package/dist/tools/kb-setup.d.ts.map +0 -1
  899. package/dist/tools/kb-setup.js.map +0 -1
  900. package/dist/tools/kb-stats.d.ts.map +0 -1
  901. package/dist/tools/kb-stats.js.map +0 -1
  902. package/dist/tools/list-members.d.ts.map +0 -1
  903. package/dist/tools/list-members.js.map +0 -1
  904. package/dist/tools/member-detail.d.ts.map +0 -1
  905. package/dist/tools/member-detail.js.map +0 -1
  906. package/dist/tools/member-reservation.d.ts.map +0 -1
  907. package/dist/tools/member-reservation.js.map +0 -1
  908. package/dist/tools/monitor-task.d.ts.map +0 -1
  909. package/dist/tools/monitor-task.js.map +0 -1
  910. package/dist/tools/provision-auth.d.ts.map +0 -1
  911. package/dist/tools/provision-auth.js.map +0 -1
  912. package/dist/tools/provision-vcs-auth.d.ts.map +0 -1
  913. package/dist/tools/provision-vcs-auth.js.map +0 -1
  914. package/dist/tools/receive-files.d.ts.map +0 -1
  915. package/dist/tools/receive-files.js.map +0 -1
  916. package/dist/tools/register-member.d.ts.map +0 -1
  917. package/dist/tools/register-member.js.map +0 -1
  918. package/dist/tools/remove-member.d.ts.map +0 -1
  919. package/dist/tools/remove-member.js.map +0 -1
  920. package/dist/tools/report-status.d.ts.map +0 -1
  921. package/dist/tools/report-status.js.map +0 -1
  922. package/dist/tools/respond-to-message.d.ts.map +0 -1
  923. package/dist/tools/respond-to-message.js.map +0 -1
  924. package/dist/tools/revoke-vcs-auth.d.ts.map +0 -1
  925. package/dist/tools/revoke-vcs-auth.js.map +0 -1
  926. package/dist/tools/send-email.d.ts.map +0 -1
  927. package/dist/tools/send-email.js.map +0 -1
  928. package/dist/tools/send-files.d.ts.map +0 -1
  929. package/dist/tools/send-files.js.map +0 -1
  930. package/dist/tools/send-message.d.ts.map +0 -1
  931. package/dist/tools/send-message.js.map +0 -1
  932. package/dist/tools/setup-git-app.d.ts.map +0 -1
  933. package/dist/tools/setup-git-app.js.map +0 -1
  934. package/dist/tools/setup-ssh-key.d.ts.map +0 -1
  935. package/dist/tools/setup-ssh-key.js.map +0 -1
  936. package/dist/tools/shutdown-server.d.ts.map +0 -1
  937. package/dist/tools/shutdown-server.js.map +0 -1
  938. package/dist/tools/stop-prompt.d.ts.map +0 -1
  939. package/dist/tools/stop-prompt.js.map +0 -1
  940. package/dist/tools/update-agent-cli.d.ts.map +0 -1
  941. package/dist/tools/update-agent-cli.js.map +0 -1
  942. package/dist/tools/update-member.d.ts.map +0 -1
  943. package/dist/tools/update-member.js.map +0 -1
  944. package/dist/tools/version.d.ts.map +0 -1
  945. package/dist/tools/version.js.map +0 -1
  946. package/dist/types.d.ts.map +0 -1
  947. package/dist/types.js.map +0 -1
  948. package/dist/utils/agent-helpers.d.ts.map +0 -1
  949. package/dist/utils/agent-helpers.js.map +0 -1
  950. package/dist/utils/ansi.d.ts.map +0 -1
  951. package/dist/utils/ansi.js.map +0 -1
  952. package/dist/utils/auth-env.d.ts.map +0 -1
  953. package/dist/utils/auth-env.js.map +0 -1
  954. package/dist/utils/collect-secret.d.ts.map +0 -1
  955. package/dist/utils/collect-secret.js.map +0 -1
  956. package/dist/utils/credential-validation.d.ts.map +0 -1
  957. package/dist/utils/credential-validation.js.map +0 -1
  958. package/dist/utils/crypto.d.ts.map +0 -1
  959. package/dist/utils/crypto.js.map +0 -1
  960. package/dist/utils/deep-merge.d.ts.map +0 -1
  961. package/dist/utils/deep-merge.js.map +0 -1
  962. package/dist/utils/file-permissions.d.ts.map +0 -1
  963. package/dist/utils/file-permissions.js.map +0 -1
  964. package/dist/utils/gpu-parser.d.ts.map +0 -1
  965. package/dist/utils/gpu-parser.js.map +0 -1
  966. package/dist/utils/log-helpers.d.ts.map +0 -1
  967. package/dist/utils/log-helpers.js.map +0 -1
  968. package/dist/utils/oob-timeout.d.ts.map +0 -1
  969. package/dist/utils/oob-timeout.js.map +0 -1
  970. package/dist/utils/opencode-model-validation.d.ts.map +0 -1
  971. package/dist/utils/opencode-model-validation.js.map +0 -1
  972. package/dist/utils/pid-helpers.d.ts.map +0 -1
  973. package/dist/utils/pid-helpers.js.map +0 -1
  974. package/dist/utils/platform.d.ts.map +0 -1
  975. package/dist/utils/platform.js.map +0 -1
  976. package/dist/utils/process-utils.d.ts.map +0 -1
  977. package/dist/utils/process-utils.js.map +0 -1
  978. package/dist/utils/prompt-errors.d.ts.map +0 -1
  979. package/dist/utils/prompt-errors.js.map +0 -1
  980. package/dist/utils/resolve-member.d.ts.map +0 -1
  981. package/dist/utils/resolve-member.js.map +0 -1
  982. package/dist/utils/secure-input.d.ts.map +0 -1
  983. package/dist/utils/secure-input.js.map +0 -1
  984. package/dist/utils/session-caller.d.ts.map +0 -1
  985. package/dist/utils/session-caller.js.map +0 -1
  986. package/dist/utils/shell-escape.d.ts.map +0 -1
  987. package/dist/utils/shell-escape.js.map +0 -1
  988. package/dist/utils/skill-matrix.d.ts.map +0 -1
  989. package/dist/utils/skill-matrix.js.map +0 -1
  990. package/dist/utils/ssh-error-messages.d.ts.map +0 -1
  991. package/dist/utils/ssh-error-messages.js.map +0 -1
  992. package/dist/utils/work-folder-validation.d.ts.map +0 -1
  993. package/dist/utils/work-folder-validation.js.map +0 -1
  994. package/dist/utils/workspace-trust.d.ts.map +0 -1
  995. package/dist/utils/workspace-trust.js.map +0 -1
  996. package/dist/version.d.ts.map +0 -1
  997. package/dist/version.js.map +0 -1
@@ -0,0 +1,347 @@
1
+ import fs from 'fs';
2
+ import path from 'path';
3
+
4
+ // =============================================================================
5
+ // shell-command guard checker -- fourth mechanical guard in this directory,
6
+ // modelled on dispatch-safety-guard.mjs, dolt-literal-guard.mjs and
7
+ // full-db-fetch-guard.mjs (same shape: a line scanner exported and
8
+ // parameterizable by path, with explicit carve-outs for full-line comments
9
+ // and import/require lines, so it can be pointed at BOTH the real guarded
10
+ // modules and a throwaway fixture that deliberately violates the invariant).
11
+ //
12
+ // INVARIANT UNDER TEST: a member-bound command string must NEVER rely on
13
+ // shell-level expansion performed in the orchestrator process's idea of a
14
+ // shell. The target member's shell may be PowerShell (or cmd.exe, or
15
+ // Git-for-Windows bash), not POSIX sh -- so none of the following may appear
16
+ // in a string this repo hands to command()/execute_command:
17
+ //
18
+ // - variable expansion, bare (`$HOME`, `$env:USERPROFILE`) or braced
19
+ // (a literal `${VAR}` reaching the member, i.e. one written inside a
20
+ // single/double-quoted JS string or escaped as `\${VAR}` in a template
21
+ // literal);
22
+ // - a leading tilde path (`~/...`) -- PowerShell and cmd.exe do not expand
23
+ // it the way POSIX sh does;
24
+ // - backtick command substitution (a literal backtick reaching the member),
25
+ // or its `$( ... )` POSIX equivalent;
26
+ // - a POSIX shell SPECIAL PARAMETER -- `$?` `$!` `$$` `$#` `$@` `$*` and
27
+ // `$0`-`$9` (apra-fleet-i4ku.8). BARE_VAR_RE alone never covered these:
28
+ // it requires a letter/underscore immediately after the `$`, so every one
29
+ // of them silently passed this guard. Exactly like a named variable, a
30
+ // special parameter is evaluated by WHATEVER shell the member happens to
31
+ // run, so the exact same PowerShell-vs-POSIX ambiguity applies -- it must
32
+ // be resolved in JavaScript before dispatch, UNLESS the construct is
33
+ // deliberately meant to be evaluated by the member's own shell right
34
+ // after a prior command in the same dispatch (e.g. that shell's own `$?`
35
+ // immediately after a `kill` it just ran) -- which is exactly what the
36
+ // `shell-guard-allow` carve-out below exists for.
37
+ //
38
+ // Paths must instead be resolved in JavaScript BEFORE the command string is
39
+ // built -- via probeCommandFor(targetOs, shell) in src/services/member-home.ts,
40
+ // or by branching on isPosixShell(agentOs, shell) in src/providers/claude.ts
41
+ // (see also fleet-sprint/se-os-commands.mjs's per-shell command classes,
42
+ // which are how this package does that branching).
43
+ //
44
+ // WHAT IS DELIBERATELY NOT FLAGGED
45
+ //
46
+ // 1. JS template interpolation. A bare `${expr}` inside a backtick template
47
+ // literal is resolved IN JAVASCRIPT before the string is ever dispatched;
48
+ // that is the prescribed fix, not the violation. Only a `${...}` that
49
+ // survives into the emitted text -- one inside a '...'/"..." string, or
50
+ // written `\${...}` inside a template -- is a violation.
51
+ // 2. Backticks used as JS template-literal delimiters. Only an ESCAPED
52
+ // backtick (`\`` -- a literal backtick surviving into the emitted
53
+ // string) is a violation. An UNescaped backtick inside a '...'/"..."
54
+ // JS string is DELIBERATELY NOT flagged, even though it sits inside a
55
+ // quoted string -- it is overwhelmingly a markdown code span in
56
+ // agent-prompt prose (runner.js has ~24 of them) or a JS fence-builder,
57
+ // not a dispatched shell substitution, so flagging those would make
58
+ // this guard pure noise. A reader should take away that a backtick-
59
+ // wrapped substitution written inside ordinary '...'/"..." quotes in a
60
+ // member-bound command string is UNGUARDED by this rule.
61
+ // 3. Secret token references. execute_command replaces each secret.NAME
62
+ // (or legacy secure.NAME) token with a value that has ALREADY been quoted for the target
63
+ // member's shell (escapePowerShellArg for windows members,
64
+ // escapeShellArg otherwise -- src/tools/execute-command.ts). Those
65
+ // tokens carry no `$`, `~/` or backtick, so they never match a rule
66
+ // here; a bare token reference is correct and must stay bare (wrapping
67
+ // one in extra quotes double-escapes the value and surfaces as a false
68
+ // 401 / invalid-token error). This guard must never push a caller toward
69
+ // adding those quotes.
70
+ //
71
+ // CARVE-OUTS (mirroring the sibling guards):
72
+ // - full-line comments (trimmed text starting with `//`, `*` or `/*`) --
73
+ // prose that merely DISCUSSES `$HOME`/`~/`/backticks is not a dispatch;
74
+ // runner.js's own RUNNER-WIDE POSIX-EXPANSION SWEEP note is exactly this;
75
+ // - `import`/`require` lines;
76
+ // - an explicit, documented per-line allow directive: a trailing
77
+ // `// shell-guard-allow: <reason>` comment on the offending line (or on
78
+ // the line immediately above it) suppresses that line, and the reason
79
+ // text is REQUIRED -- an allow with no reason is itself reported. This
80
+ // exists for the handful of genuinely deliberate cases where the member's
81
+ // own shell must do the expansion because the WRITE side used the same
82
+ // token (fleet-sprint/se-posix.mjs's `$HOME/...` credential-helper path
83
+ // is the canonical example: it must stay byte-identical to what
84
+ // src/os/linux.ts wrote).
85
+ // =============================================================================
86
+
87
+ /** Trailing/standalone directive that suppresses one line, with a required reason. */
88
+ const ALLOW_RE = /shell-guard-allow:\s*(\S.*)$/;
89
+ /** An allow directive with no reason text after the colon. */
90
+ const ALLOW_NO_REASON_RE = /shell-guard-allow:\s*$/;
91
+
92
+ function isCommentLine(text) {
93
+ const trimmed = text.trim();
94
+ return trimmed.startsWith('//') || trimmed.startsWith('*') || trimmed.startsWith('/*');
95
+ }
96
+
97
+ function isImportLine(text) {
98
+ return /^\s*(import\b|export\b.*\bfrom\b|(const|let|var)\s.*\brequire\s*\()/.test(text);
99
+ }
100
+
101
+ /**
102
+ * Splits `text` into segments tagged with the JS quoting context they sit in,
103
+ * scanning a single line left to right. Returns an array of
104
+ * { kind, start, end } where kind is one of 'code', 'single', 'double',
105
+ * 'template'. Deliberately single-line (like dispatch-safety-guard.mjs's
106
+ * isInsideSameLineString): a whole-file quote scan misfires on apostrophes in
107
+ * prose. A template literal that opens on this line and does not close is
108
+ * treated as running to end of line, which is the conservative choice -- the
109
+ * bytes on THIS line are what we classify.
110
+ */
111
+ export function segmentLine(text) {
112
+ const segments = [];
113
+ let kind = 'code';
114
+ let start = 0;
115
+ for (let i = 0; i < text.length; i++) {
116
+ const ch = text[i];
117
+ if (ch === '\\') { i++; continue; }
118
+ if (kind === 'code') {
119
+ if (ch === "'" || ch === '"' || ch === '`') {
120
+ segments.push({ kind: 'code', start, end: i });
121
+ kind = ch === "'" ? 'single' : ch === '"' ? 'double' : 'template';
122
+ start = i + 1;
123
+ }
124
+ } else {
125
+ const closer = kind === 'single' ? "'" : kind === 'double' ? '"' : '`';
126
+ if (ch === closer) {
127
+ segments.push({ kind, start, end: i });
128
+ kind = 'code';
129
+ start = i + 1;
130
+ }
131
+ }
132
+ }
133
+ segments.push({ kind, start, end: text.length });
134
+ return segments.filter((s) => s.end > s.start);
135
+ }
136
+
137
+ /** True when `col` sits inside a JS template literal opened earlier on the same line. */
138
+ function segmentKindAt(segments, col) {
139
+ for (const s of segments) {
140
+ if (col >= s.start && col < s.end) return s.kind;
141
+ }
142
+ return 'code';
143
+ }
144
+
145
+ // A shell variable expansion with no braces: `$HOME`, `$env:USERPROFILE`,
146
+ // `$pid`. Not preceded by a `$` (so `$$` is not double-counted) and not
147
+ // followed by `{`.
148
+ const BARE_VAR_RE = /(?<!\$)\$([A-Za-z_][A-Za-z0-9_:]*)/g;
149
+ // A brace expansion written so it SURVIVES into the emitted string.
150
+ const BRACED_VAR_RE = /\$\{/g;
151
+ // POSIX command substitution.
152
+ const CMD_SUBST_RE = /\$\(/g;
153
+ // A leading tilde path.
154
+ const TILDE_RE = /(^|[\s'"`=(,:])~\//g;
155
+ // A POSIX shell SPECIAL PARAMETER: $? $! $$ $# $@ $* and $0-$9
156
+ // (apra-fleet-i4ku.8). None of these match BARE_VAR_RE above (it requires a
157
+ // letter/underscore right after the `$`), so every one of them was
158
+ // previously invisible to this guard -- see this file's header for why they
159
+ // carry the same shell-ambiguity risk as a named variable.
160
+ //
161
+ // Two deliberate exclusions so this stays a real signal rather than noise:
162
+ // - `$$` only counts when NOT immediately followed by `{` -- that shape is
163
+ // `$` + the start of a `${...}` JS template interpolation (already
164
+ // handled, correctly, by NOT being flagged -- see BRACED_VAR_RE/the
165
+ // 'template' segment-kind check below), not a literal "$$" (shell pid).
166
+ // - a digit only counts when NOT immediately followed by another digit or
167
+ // a `.` -- a genuine POSIX positional parameter is always exactly ONE
168
+ // digit (`$1`, never `$12`), so this excludes a dollar-amount literal
169
+ // like `$5.00` or `$1234` (this package's own cost-report strings, e.g.
170
+ // sprint-report.mjs, are full of these and are never dispatched to a
171
+ // shell at all).
172
+ const SPECIAL_PARAM_RE = /\$([?!#@*]|\$(?!\{)|[0-9](?![0-9.]))/g;
173
+
174
+ /**
175
+ * Scans one line of source and returns an array of { column, reason } for
176
+ * every shell-expansion construct that would survive into a dispatched
177
+ * command string. Exported for direct unit testing.
178
+ */
179
+ export function findLineViolations(text) {
180
+ const segments = segmentLine(text);
181
+ const found = [];
182
+ const inString = (col) => segmentKindAt(segments, col) !== 'code';
183
+
184
+ let m;
185
+ BARE_VAR_RE.lastIndex = 0;
186
+ while ((m = BARE_VAR_RE.exec(text)) !== null) {
187
+ if (!inString(m.index)) continue;
188
+ found.push({
189
+ column: m.index + 1,
190
+ reason:
191
+ `bare shell variable expansion "$${m[1]}" in a command string -- the target member's shell may be ` +
192
+ `PowerShell, not POSIX; resolve the value in JavaScript first (probeCommandFor(targetOs, shell) in ` +
193
+ `src/services/member-home.ts, or branch on isPosixShell(agentOs, shell))`,
194
+ });
195
+ }
196
+
197
+ SPECIAL_PARAM_RE.lastIndex = 0;
198
+ while ((m = SPECIAL_PARAM_RE.exec(text)) !== null) {
199
+ if (!inString(m.index)) continue;
200
+ found.push({
201
+ column: m.index + 1,
202
+ reason:
203
+ `POSIX shell special parameter "$${m[1]}" in a command string -- the target member's shell may be ` +
204
+ 'PowerShell, not POSIX, and even on POSIX this is evaluated by WHATEVER shell runs the dispatch; ' +
205
+ 'resolve the value in JavaScript first, or if the MEMBER shell must evaluate it itself (e.g. its ' +
206
+ 'own "$?" immediately after a prior command in the same dispatch), add a documented ' + // shell-guard-allow: this guard's own violation-message text names the "$?" construct it detects; it is never dispatched as a command string.
207
+ '"// shell-guard-allow: <reason>" comment on this line',
208
+ });
209
+ }
210
+
211
+ CMD_SUBST_RE.lastIndex = 0;
212
+ while ((m = CMD_SUBST_RE.exec(text)) !== null) {
213
+ if (!inString(m.index)) continue;
214
+ found.push({
215
+ column: m.index + 1,
216
+ reason:
217
+ 'POSIX command substitution "$(" in a command string -- run the probe as its own dispatch and ' + // shell-guard-allow: this guard's own violation-message text names the "$(" construct it detects; it is never dispatched as a command string.
218
+ 'interpolate the result in JavaScript instead',
219
+ });
220
+ }
221
+
222
+ BRACED_VAR_RE.lastIndex = 0;
223
+ while ((m = BRACED_VAR_RE.exec(text)) !== null) {
224
+ const kind = segmentKindAt(segments, m.index);
225
+ const escaped = m.index > 0 && text[m.index - 1] === '\\';
226
+ // A bare `${...}` inside a template literal is JS interpolation --
227
+ // resolved before dispatch, which is the prescribed fix. Only a
228
+ // braced expansion that survives into the emitted text counts.
229
+ if (kind === 'template' && !escaped) continue;
230
+ if (kind === 'code') continue;
231
+ found.push({
232
+ column: m.index + 1,
233
+ reason:
234
+ 'braced shell variable expansion "${...}" survives into the dispatched command string -- ' + // shell-guard-allow: this guard's own violation-message text names the "${...}" construct it detects; it is never dispatched as a command string.
235
+ 'interpolate the value in JavaScript instead of leaving it for the member shell to expand',
236
+ });
237
+ }
238
+
239
+ TILDE_RE.lastIndex = 0;
240
+ while ((m = TILDE_RE.exec(text)) !== null) {
241
+ const col = m.index + m[1].length;
242
+ if (!inString(col)) continue;
243
+ found.push({
244
+ column: col + 1,
245
+ reason:
246
+ 'leading tilde path "~/" in a command string -- PowerShell and cmd.exe do not expand it; resolve ' + // shell-guard-allow: this guard's own violation-message text names the "~/" construct it detects; it is never dispatched as a command string.
247
+ "the member's home directory in JavaScript (probeCommandFor(targetOs, shell))",
248
+ });
249
+ }
250
+
251
+ // Backticks: only an ESCAPED backtick counts -- see the rule note in this
252
+ // file's header. An UNescaped backtick inside a '...'/"..." JS string is
253
+ // overwhelmingly a markdown code span in agent-prompt prose (runner.js has
254
+ // ~24 of them) or a JS fence-builder, not a dispatched shell substitution,
255
+ // so flagging those makes the guard pure noise. `\`` in a template literal
256
+ // is the deliberate "emit a literal backtick into this command string"
257
+ // spelling, which is the construct this rule exists to catch.
258
+ for (let i = 0; i < text.length; i++) {
259
+ if (text[i] !== '`') continue;
260
+ const escaped = i > 0 && text[i - 1] === '\\';
261
+ if (!escaped) continue;
262
+ found.push({
263
+ column: i + 1,
264
+ reason:
265
+ 'backtick command substitution in a command string -- run the probe as its own dispatch and ' +
266
+ 'interpolate the result in JavaScript instead',
267
+ });
268
+ break; // one report per line is enough; a pair of backticks is one construct
269
+ }
270
+
271
+ return found.sort((a, b) => a.column - b.column);
272
+ }
273
+
274
+ /**
275
+ * Scans whole-file source `src`, applying the carve-outs, and returns an
276
+ * array of { line, column, reason, text } violations.
277
+ */
278
+ export function findShellCommandViolations(src) {
279
+ const lines = src.split('\n');
280
+ const violations = [];
281
+ for (let i = 0; i < lines.length; i++) {
282
+ const text = lines[i];
283
+ const prev = i > 0 ? lines[i - 1] : '';
284
+ if (isCommentLine(text)) {
285
+ // A standalone allow directive with no reason is still reported,
286
+ // so a suppression can never be added without saying why.
287
+ if (ALLOW_NO_REASON_RE.test(text)) {
288
+ violations.push({
289
+ line: i + 1,
290
+ column: text.indexOf('shell-guard-allow') + 1,
291
+ reason: 'shell-guard-allow directive has no reason text -- state why the member shell must do the expansion',
292
+ text: text.trim(),
293
+ });
294
+ }
295
+ continue;
296
+ }
297
+ if (isImportLine(text)) continue;
298
+ const lineFindings = findLineViolations(text);
299
+ if (lineFindings.length === 0) continue;
300
+ if (ALLOW_NO_REASON_RE.test(text) || ALLOW_NO_REASON_RE.test(prev)) {
301
+ violations.push({
302
+ line: i + 1,
303
+ column: 1,
304
+ reason: 'shell-guard-allow directive has no reason text -- state why the member shell must do the expansion',
305
+ text: text.trim(),
306
+ });
307
+ continue;
308
+ }
309
+ if (ALLOW_RE.test(text) || ALLOW_RE.test(prev)) continue;
310
+ for (const f of lineFindings) {
311
+ violations.push({ line: i + 1, column: f.column, reason: f.reason, text: text.trim() });
312
+ }
313
+ }
314
+ return violations;
315
+ }
316
+
317
+ /**
318
+ * Reads and scans the source file at `filePath`, returning
319
+ * { violations } where each violation is { file, line, column, reason, text }
320
+ * -- `file` is the basename, matching how the sibling guards label a
321
+ * violation, so an aggregate run over several modules attributes each finding
322
+ * to the module it came from.
323
+ */
324
+ export function checkShellCommandPath(filePath) {
325
+ const src = fs.readFileSync(filePath, 'utf8');
326
+ const file = path.basename(filePath);
327
+ const violations = findShellCommandViolations(src).map((v) => ({ file, ...v }));
328
+ return { violations };
329
+ }
330
+
331
+ /**
332
+ * Aggregate entry point: scans EVERY path in `paths` (e.g. the shared guarded
333
+ * module list) and returns { violations, files } with each violation carrying
334
+ * the file it came from. Takes an explicit array so this module stays
335
+ * independent of any one registry.
336
+ */
337
+ export function checkShellCommandPaths(paths) {
338
+ if (!Array.isArray(paths)) throw new TypeError('checkShellCommandPaths(paths): paths must be an array of file paths');
339
+ const violations = [];
340
+ for (const p of paths) violations.push(...checkShellCommandPath(p).violations);
341
+ return { violations, files: paths.map((p) => path.basename(p)) };
342
+ }
343
+
344
+ /** Human-readable rendering of one violation, for assertion messages and logs. */
345
+ export function formatShellCommandViolation(v) {
346
+ return `${v.file || '<unknown>'}:${v.line}:${v.column} ${v.reason}`;
347
+ }
@@ -26,6 +26,9 @@ apra-fleet workflow fleet-sprint \
26
26
  [--viewer-port <port>] # default 8080
27
27
  [--budget <usd>] # default unlimited
28
28
  [--dispatch-timeout-s <s>] # default 9000
29
+ [--usage-limit-max-wait-s <s>] # usage-limit pause budget; default from role-policies
30
+ [--usage-limit-max-reprobes <n>]# usage-limit reprobe cap; default from role-policies
31
+ [--skip-regression] # skip the once-per-sprint regression pass
29
32
  [--sync] # synced-topology mode
30
33
  ```
31
34
 
@@ -42,6 +45,9 @@ on this list -- flags evolve and this skill can drift.
42
45
  is invisible to the scope filter no matter what you pass -- only true
43
46
  children are picked up. See the epics/manifest-bead guidance in
44
47
  `packages/apra-fleet-se/fleet-sprint/docs/README.md`.
48
+ - `--branch` must differ from `--base` (`main` vs `origin/main` or
49
+ `refs/heads/main` count as the same branch); an equal pair is rejected at
50
+ launch.
45
51
  - `--branch` is created from `--base` if it does not already exist. If it
46
52
  does exist (e.g. you are resuming), it is reused as-is.
47
53
  - **`--base` is resolved against the remote, not your local checkout.** A new
@@ -52,9 +58,20 @@ on this list -- flags evolve and this skill can drift.
52
58
  package.json script) fails in ways that look unrelated.
53
59
  - `--role-map` assigns specific members to specific roles, e.g.
54
60
  `--role-map '{"doer":["m1","m2"],"reviewer":["m3"]}'`. Accepts inline JSON
55
- or `@path/to/file.json`.
61
+ or `@path/to/file.json`. The `backlog` key names the member whose beads
62
+ clone the engine runs its own `bd`/`git` commands against. `orchestrator`
63
+ is its deprecated alias (works with a warning in 0.4.4, removed in v0.5) --
64
+ rename it to `backlog`. Without a `backlog` entry the engine picks a member
65
+ and logs `backlog: <member> (auto-selected: <reason>)`; check that line.
66
+ - `--skip-regression` skips the regression pass for this run. The skip is
67
+ logged and stated in the sprint analysis and the PR body.
56
68
  - `--goal` controls which bead priorities are in scope for the run.
57
69
  - `--budget` caps total spend in USD; the run aborts when it is exhausted.
70
+ - `--usage-limit-max-wait-s` / `--usage-limit-max-reprobes` bound how long a
71
+ dispatch that hit a provider usage/rate limit is paused (and re-probed on a
72
+ backoff ladder) before the run gives up with a typed abort. Both are
73
+ optional; omitted, the engine uses its own defaults. A resumed member
74
+ re-dispatches without consuming a retry attempt.
58
75
 
59
76
  ## Preconditions to check first
60
77
 
@@ -67,20 +84,45 @@ on this list -- flags evolve and this skill can drift.
67
84
  2. Every `--members` name is registered with the fleet (`list_members` /
68
85
  `mcp__apra-fleet__list_members`). An unregistered member aborts the
69
86
  sprint unless `--allow-missing-members` is passed.
70
- 3. Multi-member sprints require all members to share the same git topology
71
- unless `--sync` is passed. Stick to single-member unless that is
72
- verified -- see `fleet-sprint-diagram.md` in the package docs.
87
+ 3. Multi-member sprints align their members automatically: at launch every
88
+ member is fetched and checked out on the sprint branch (WIP preserved in a
89
+ named `fleet-sprint[<branch>]` stash, one `[Align]` line per member), so
90
+ do not align members by hand. The launch refuses, before moving any
91
+ member, only for an unreachable member, differing origin URLs, a base
92
+ missing on origin, a fetch auth failure or a diverged sprint branch --
93
+ fix what the message names and relaunch. See `fleet-sprint-diagram.md` in
94
+ the package docs.
73
95
  4. If a member's LLM session is stale or unauthenticated (dispatch fails
74
96
  with `empty_response`, or "member CLI likely died"), re-run
75
97
  `provision_llm_auth` for that member before retrying.
98
+ 5. Beads identity: before any `bd` mutation, the sprint probes every
99
+ member's `bd where`/`sync.remote`/git origin and prints a `Beads:`
100
+ banner plus one `beads ok: <member> ...` line per member. These abort
101
+ with `BeadsIdentityError` naming the member, cause and fix, before
102
+ anything is dispatched -- there is no bypass flag:
103
+ - MISMATCH: a field that resolved on both sides differs. Fix that
104
+ member's `workFolder` (wrong `.beads`) or its `sync.remote`.
105
+ - `bd` missing on a member (not installed or not on PATH). Fix: install
106
+ `bd` on that member or fix its PATH so `bd --version` works in its work
107
+ folder (re-running the member fleet install places it in the member's
108
+ fleet bin dir), then relaunch.
109
+ - BEADS_SETUP_FAILED: a member mapped to a beads-reading role had no beads
110
+ database (or no `sync.remote`), and setting it up from the expected
111
+ beads remote failed. Matching members are left untouched.
112
+ Any other probe failure (including no beads database on a member used
113
+ only for deployer/ci-watcher) is only a `[beads-identity] WARNING:` line (naming
114
+ the member, field, probe, error and the fix): that field is not compared
115
+ and the sprint proceeds -- read the warning and fix the member.
76
116
 
77
117
  ## Launching it
78
118
 
79
119
  Run this on your own orchestrating machine, not on a `--members` target --
80
120
  members are dispatch destinations, not where this command runs.
81
121
 
82
- Use the delivered `apra-fleet` binary (on PATH after `npm run build:binary`),
83
- and start it as a genuinely detached OS process. A harness-owned background
122
+ Use the installed `apra-fleet` binary. After `npm install -g` it is on
123
+ PATH; the standalone installer does not add it to PATH, so call it as
124
+ `~/.apra-fleet/bin/apra-fleet` (Windows: `$HOME\.apra-fleet\bin\apra-fleet.exe`).
125
+ Start it as a genuinely detached OS process. A harness-owned background
84
126
  task can be silently killed when its owning tool call's process group ends,
85
127
  which orphans the sprint mid-run.
86
128
 
@@ -15,22 +15,62 @@ Check first: `curl -s -m 5 http://localhost:8787/api/sprints`. Connection
15
15
  refused/timeout = not running. `{"sprints": [...]}` = already up, skip this.
16
16
 
17
17
  Start it detached (it runs indefinitely -- exits only on `POST
18
- /api/shutdown` or SIGINT/SIGTERM, never on its own):
18
+ /api/shutdown` or SIGINT/SIGTERM, never on its own). `apra-fleet install`
19
+ puts it under the user's home (needs Node.js 22.16+):
19
20
 
20
21
  ```bash
21
- node packages/apra-fleet-se/bin/serve.mjs # background/detached, from repo root
22
+ node ~/.apra-fleet/workflows/fleet-sprint/bin/serve.mjs # macOS / Linux
22
23
  ```
23
24
 
24
- `--port <n>` overrides the default (8787). Self-logs to
25
+ ```powershell
26
+ node "$HOME\.apra-fleet\workflows\fleet-sprint\bin\serve.mjs" # Windows PowerShell
27
+ ```
28
+
29
+ (From a source checkout of apra-fleet the same file is
30
+ `packages/apra-fleet-se/bin/serve.mjs`.)
31
+
32
+ Start it from INSIDE the target project (any folder under it): the
33
+ supervisor resolves the project's `.beads` by walking up from its cwd,
34
+ exactly like `bd`. Starting from elsewhere: pass `--beads-dir <project
35
+ folder or its .beads>` (a path that does not exist is a startup error). It
36
+ logs one `supervisor beads: <dir> | prefix=<p> | remote=<sync.remote>` line
37
+ at startup; the same identity is on `GET /api/health` (`beads`) and at the
38
+ top of the dashboard, and every sprint it launches is told to verify its
39
+ members against it. If NO `.beads` is found (or its probe fails) it still
40
+ starts, but logs `[supervisor] WARNING: no beads database found walking up
41
+ from <cwd> ... To fix: ...`, reports `beads: null` plus `beadsWarning` on
42
+ `/api/health`, and shows an amber `Beads: NOT RESOLVED -- ...` header on the
43
+ dashboard. With NO `.beads` found it also has no backlog member, so every
44
+ launch answers `503` until you restart it from the right folder or with
45
+ `--beads-dir`. With a `.beads` found but a failed probe, launches still
46
+ work (without `--expect-beads`); fix the environment and hit
47
+ `GET /api/health?refresh=1` to recover without a restart. `--port <n>`
48
+ overrides the default (8787). Self-logs to
25
49
  `<dataDir>/logs/supervisor.log` in addition to stdout.
26
50
 
51
+ **Backlog member.** At startup the supervisor ensures its own backlog
52
+ member: a local member with no LLM whose work folder is the project folder.
53
+ It adopts an LLM-less local member already registered for that folder (name
54
+ kept; adds the `backlog` tag and `unreservable` when missing), or registers
55
+ `backlog-<camelCaseFolderName>`. It logs `[supervisor] backlog member:
56
+ '<name>' (ready)`; `GET /api/health` reports `backlogMember: {status, name,
57
+ reason}`. It refuses to start (exit 1) if that name is taken by a member
58
+ for another folder. Fleet unreachable at startup is not fatal: status is
59
+ `degraded`, launches answer `503`, and a background retry fixes it.
60
+
27
61
  Smoke test (a few seconds after launch -- give it time to bind):
28
62
  ```bash
29
63
  curl -s -m 5 http://localhost:8787/api/sprints # expect {"sprints":[],...}
30
64
  curl -s -m 5 http://localhost:8787/api/members # expect the registered fleet, non-empty
65
+ curl -s -m 5 http://localhost:8787/api/health # check `beads.dir`/`beads.prefix` is the intended tracker, `backlogMember.status` is "ready"
31
66
  ```
67
+ (Windows PowerShell 5.1: `curl` is an alias of `Invoke-WebRequest`; use
68
+ `curl.exe` with the same arguments, or `Invoke-RestMethod <url>`.)
32
69
  Both must succeed before treating the supervisor as up -- a bound port with
33
- a 500 on `/api/members` still means something is broken.
70
+ a 500 on `/api/members` still means something is broken. A wrong
71
+ `beads.prefix` means it was started from the wrong folder: stop it and
72
+ restart with `--beads-dir`. `beads: null` with a `beadsWarning` means no
73
+ tracker was resolved at all: the warning text says what to do.
34
74
 
35
75
  ## Stop the supervisor
36
76
 
@@ -127,15 +167,24 @@ restart command exists:
127
167
  run its smoke test (`GET /api/sprints`, `GET /api/members`) to confirm the
128
168
  new process is actually serving before treating the restart as done.
129
169
 
170
+ **Upgrading apra-fleet.** A running supervisor keeps the code it started
171
+ with. Before upgrading, let running sprints finish (or stop them) and stop
172
+ the supervisor; start it again afterwards. A
173
+ supervisor started under 0.4.3 does not send the install's access secret, so
174
+ a 0.4.4 fleet server refuses its requests with HTTP 401. If a sprint was
175
+ still running during the upgrade, the first launch may 409 on its stale
176
+ member reservations -- see "Common launch-time crashes" below.
177
+
130
178
  ## Auto-start on login/boot
131
179
 
132
- Instead of a human running `node bin/serve.mjs` by hand each session, the
180
+ Instead of a human running `serve.mjs` by hand each session, the
133
181
  supervisor can be registered with the OS to start automatically on
134
182
  login/boot. Resolve commands per the target member's own OS (`agent.os`) --
135
183
  do not assume the orchestrator's shell; some members run PowerShell, not
136
- POSIX. Every example below assumes the repo root is
137
- `/path/to/apra-fleet` (POSIX) or `C:\path\to\apra-fleet` (Windows) --
138
- substitute the real path on the target member. After registering (any OS),
184
+ POSIX. A service manager does not start in your project folder, so every
185
+ example passes `--beads-dir`. Substitute the real paths: the user's home
186
+ (`/Users/<user>`, `/home/<user>` or `C:\Users\<user>`) and the target
187
+ project folder (`/path/to/project` or `C:\path\to\project`). After registering (any OS),
139
188
  run the same-process smoke test from section 0 above (`GET /api/sprints`,
140
189
  `GET /api/members`) against the newly auto-started instance to confirm it is
141
190
  actually serving, not just that the OS accepted the registration.
@@ -147,7 +196,7 @@ user's own session):
147
196
 
148
197
  Register:
149
198
  ```cmd
150
- schtasks /Create /TN "ApraFleetSupervisor" /TR "node C:\path\to\apra-fleet\packages\apra-fleet-se\bin\serve.mjs" /SC ONLOGON /RL LIMITED
199
+ schtasks /Create /TN "ApraFleetSupervisor" /TR "node C:\Users\<user>\.apra-fleet\workflows\fleet-sprint\bin\serve.mjs --beads-dir C:\path\to\project" /SC ONLOGON /RL LIMITED
151
200
  ```
152
201
  De-register:
153
202
  ```cmd
@@ -163,8 +212,8 @@ in; requires NSSM installed and on PATH):
163
212
 
164
213
  Register:
165
214
  ```cmd
166
- nssm install ApraFleetSupervisor node "C:\path\to\apra-fleet\packages\apra-fleet-se\bin\serve.mjs"
167
- nssm set ApraFleetSupervisor AppDirectory "C:\path\to\apra-fleet"
215
+ nssm install ApraFleetSupervisor node "C:\Users\<user>\.apra-fleet\workflows\fleet-sprint\bin\serve.mjs" --beads-dir "C:\path\to\project"
216
+ nssm set ApraFleetSupervisor AppDirectory "C:\path\to\project"
168
217
  nssm start ApraFleetSupervisor
169
218
  ```
170
219
  De-register:
@@ -187,7 +236,9 @@ Create `~/Library/LaunchAgents/com.apra-fleet.supervisor.plist`:
187
236
  <key>ProgramArguments</key>
188
237
  <array>
189
238
  <string>/usr/local/bin/node</string>
190
- <string>/path/to/apra-fleet/packages/apra-fleet-se/bin/serve.mjs</string>
239
+ <string>/Users/<user>/.apra-fleet/workflows/fleet-sprint/bin/serve.mjs</string>
240
+ <string>--beads-dir</string>
241
+ <string>/path/to/project</string>
191
242
  </array>
192
243
  <key>RunAtLoad</key>
193
244
  <true/>
@@ -227,9 +278,9 @@ Create `~/.config/systemd/user/apra-fleet-supervisor.service`:
227
278
  Description=Apra Fleet supervisor
228
279
 
229
280
  [Service]
230
- ExecStart=/usr/bin/node /path/to/apra-fleet/packages/apra-fleet-se/bin/serve.mjs
281
+ ExecStart=/usr/bin/node /home/<user>/.apra-fleet/workflows/fleet-sprint/bin/serve.mjs --beads-dir /path/to/project
231
282
  Restart=no
232
- WorkingDirectory=/path/to/apra-fleet
283
+ WorkingDirectory=/path/to/project
233
284
 
234
285
  [Install]
235
286
  WantedBy=default.target
@@ -260,9 +311,13 @@ start with no login (`loginctl enable-linger <username>`).
260
311
  `bd dolt commit` then `bd dolt push`. Members pull their own copy; a
261
312
  sprint launched before the push works from stale scope.
262
313
  2. Check no conflicting sprint is already running: `GET /api/sprints`.
263
- 3. Multi-member sprints need all members on the SAME git HEAD, or the
264
- launch crashes immediately with a topology error. If unsure, use ONE
265
- member. Don't guess a member list -- ask, or default to one.
314
+ 3. Multi-member sprints align their members to the sprint base
315
+ automatically at launch (WIP preserved in a named stash, one `[Align]`
316
+ line per member) -- do not align members by hand. The launch refuses only
317
+ for an unreachable member, differing origin URLs, a base missing on
318
+ origin, a fetch auth failure or a diverged sprint branch, naming the
319
+ member, cause and fix. Don't guess a member list -- ask, or default to
320
+ one.
266
321
 
267
322
  ## 2. Start a sprint
268
323
 
@@ -283,18 +338,24 @@ Field names, exactly as the API expects them:
283
338
  | Field | Required | Notes |
284
339
  |---|---|---|
285
340
  | `issue` | yes | comma-separated bead root IDs (parent/epic OR a standalone leaf bead). Alias: `target_issue`. |
286
- | `branch` | yes | created from `base` if it doesn't exist yet. |
341
+ | `branch` | yes | created from `base` if it doesn't exist yet. Must differ from `base` (an equal pair is a 400; case and `origin/`/`refs/heads/` prefixes are ignored). |
287
342
  | `base` | yes | alias: `base_branch`. This is what the sprint branches FROM -- pass the branch you actually want, not always `main`. |
288
343
  | `members` | yes | array of registered member names. One member = safest default. |
289
344
  | `goal` | no | `P1`, `P1/P2` (default), or `P1/P2/P3`. |
290
345
  | `maxCycles` | no | default 5. |
291
346
  | `allowMissingMembers` | no | bool. |
292
- | `requirementsFile` | no | path. |
293
- | `roleMap` | no | `{"doer":["m1","m2"], "reviewer":["m3"]}`. |
347
+ | `requirementsFile` | no | path on the supervisor's machine; a relative path resolves against the supervisor's project folder. Not found = a run-log warning only, so prefer an absolute path. |
348
+ | `roleMap` | no | `{"doer":["m1","m2"], "reviewer":["m3"]}`. Leave out `backlog`: the supervisor injects its own backlog member; naming any other member there is a 400. `orchestrator` is the deprecated alias of `backlog` (removed in v0.5). |
294
349
  | `budget` | no | USD cap. |
350
+ | `phases` | no | `{"regression": "skip"}` skips the regression pass (`"run"` is the default). Any other key or value is a 400. |
295
351
  | `overrideRelaunchGate` | no | bool. See below. |
296
352
 
297
- Response has `sprintId`, `pid`, `port` (its own dashboard), `logPath`.
353
+ Response has `sprintId`, `pid`, `port` (its own dashboard), `logPath`, and
354
+ `warnings` (e.g. the deprecation notice when `roleMap.orchestrator` was
355
+ used). A `503` means nothing was launched: the backlog member is not ready,
356
+ the fleet member list could not be read, the fleet server was stopped by its
357
+ user (`apra-fleet stop`), or the beads could not be verified fresh -- the
358
+ `error` says which.
298
359
  **A 201 response does NOT mean the sprint is alive** -- it can crash in the
299
360
  first few seconds (bad topology, bad member, etc). Always verify (step 3)
300
361
  a few seconds after launch.
@@ -331,13 +392,25 @@ only use it once you know why the prior run died.
331
392
 
332
393
  ## Common launch-time crashes
333
394
 
334
- - **Topology mismatch**: members are on different git commits. Fix: use one
335
- member, or align them first (`git fetch && git checkout <branch>` on
336
- each), or pass whatever sync option the engine currently exposes -- check
337
- `docs/architecture.md` "Multi-member topology" section, don't guess.
395
+ - **Topology refusal**: members are aligned automatically (section 1), so
396
+ this names what could not be reconciled -- an unreachable member,
397
+ differing origin URLs, a base missing on origin, a fetch auth failure or
398
+ a diverged sprint branch. Fix what it names and relaunch; do not align
399
+ members by hand.
400
+ - **Beads identity** (`BeadsIdentityError`, before any dispatch): `bd`
401
+ missing on a member, a member resolving to a different beads project, or
402
+ a failed automatic beads set-up on a beads-reading member. The message
403
+ names the member and the fix.
338
404
  - **Unregistered member**: `GET /api/members` to see valid names.
339
405
  - **Stale LLM auth**: dispatch fails with `empty_response`. Re-run
340
406
  `provision_llm_auth` for that member.
407
+ - **Stale member reservation** (`409 member overlap rejects launch: sprint
408
+ '<id or branch>' already claims [...]` while `GET /api/sprints` shows no
409
+ such sprint): a sprint died uncleanly (crash, or an upgrade with
410
+ `--ignore-running-sprints`) and left its members reserved on the fleet
411
+ server. Clear each listed member with the fleet MCP tool
412
+ `member_reservation {member_name: "<member>", action: "force_release"}`
413
+ (no supervisor HTTP route does this), then relaunch.
341
414
 
342
415
  ## Member layout: isolate deploy/test roles from dev roles
343
416