@apralabs/apra-fleet 0.4.4 → 0.4.5

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 (268) hide show
  1. package/README.md +49 -4
  2. package/dist/agents/backlog-groomer.md +5 -0
  3. package/dist/agents/ci-watcher.md +5 -0
  4. package/dist/agents/deployer.md +20 -2
  5. package/dist/agents/doer.md +38 -2
  6. package/dist/agents/harvester.md +12 -9
  7. package/dist/agents/integ-test-runner.md +5 -0
  8. package/dist/agents/kb-reconciler.md +6 -0
  9. package/dist/agents/plan-reviewer.md +5 -0
  10. package/dist/agents/planner.md +5 -0
  11. package/dist/agents/regression-test-runner.md +5 -0
  12. package/dist/agents/reviewer.md +67 -15
  13. package/dist/agents/schemas/deployer-output.json +5 -0
  14. package/dist/agents/schemas/doer-output.json +78 -2
  15. package/dist/agents/schemas/reviewer-output.json +104 -2
  16. package/dist/cli/auth.js +5 -1
  17. package/dist/cli/beads-pin.js +6 -7
  18. package/dist/cli/claude-mod.d.ts +75 -0
  19. package/dist/cli/claude-mod.js +288 -0
  20. package/dist/cli/dolt-install.d.ts +1 -1
  21. package/dist/cli/dolt-install.js +5 -1
  22. package/dist/cli/fleet-se-guard.d.ts +8 -0
  23. package/dist/cli/fleet-se-guard.js +19 -3
  24. package/dist/cli/install-guard.d.ts +9 -0
  25. package/dist/cli/install-guard.js +24 -0
  26. package/dist/cli/install.d.ts +12 -0
  27. package/dist/cli/install.js +180 -20
  28. package/dist/cli/kb-profile.d.ts +16 -0
  29. package/dist/cli/kb-profile.js +81 -0
  30. package/dist/cli/start.js +3 -0
  31. package/dist/cli/uninstall.js +13 -3
  32. package/dist/cli/update.d.ts +4 -0
  33. package/dist/cli/update.js +19 -3
  34. package/dist/commands/kb-server.d.ts +10 -1
  35. package/dist/commands/kb-server.js +285 -11
  36. package/dist/index.js +22 -1
  37. package/dist/os/git-executable.d.ts +57 -0
  38. package/dist/os/git-executable.js +85 -0
  39. package/dist/os/go-concurrency.d.ts +44 -0
  40. package/dist/os/go-concurrency.js +53 -0
  41. package/dist/os/index.d.ts +1 -0
  42. package/dist/os/index.js +1 -0
  43. package/dist/os/linux.d.ts +2 -0
  44. package/dist/os/linux.js +10 -1
  45. package/dist/os/os-commands.d.ts +25 -0
  46. package/dist/os/os-commands.js +2 -0
  47. package/dist/os/windows-executable.d.ts +53 -0
  48. package/dist/os/windows-executable.js +185 -0
  49. package/dist/os/windows-gitbash.d.ts +23 -14
  50. package/dist/os/windows-gitbash.js +40 -16
  51. package/dist/os/windows.d.ts +2 -0
  52. package/dist/os/windows.js +37 -6
  53. package/dist/paths.d.ts +10 -1
  54. package/dist/paths.js +19 -2
  55. package/dist/services/agy-project.d.ts +7 -1
  56. package/dist/services/agy-project.js +7 -2
  57. package/dist/services/auth-socket.d.ts +18 -0
  58. package/dist/services/auth-socket.js +30 -4
  59. package/dist/services/credential-store.d.ts +33 -0
  60. package/dist/services/credential-store.js +79 -2
  61. package/dist/services/http-transport.d.ts +29 -0
  62. package/dist/services/http-transport.js +166 -37
  63. package/dist/services/kb-tool-profile.d.ts +36 -0
  64. package/dist/services/kb-tool-profile.js +88 -0
  65. package/dist/services/knowledge/bible-blob-id.js +10 -1
  66. package/dist/services/knowledge/bible-import.d.ts +108 -0
  67. package/dist/services/knowledge/bible-import.js +137 -4
  68. package/dist/services/knowledge/file-hash.js +6 -5
  69. package/dist/services/knowledge/http-provider.d.ts +303 -20
  70. package/dist/services/knowledge/http-provider.js +795 -125
  71. package/dist/services/knowledge/kb-config.d.ts +65 -1
  72. package/dist/services/knowledge/kb-config.js +143 -3
  73. package/dist/services/knowledge/kb-http-auth-state.d.ts +26 -0
  74. package/dist/services/knowledge/kb-http-auth-state.js +40 -0
  75. package/dist/services/knowledge/kb-providers.d.ts +9 -2
  76. package/dist/services/knowledge/kb-providers.js +67 -37
  77. package/dist/services/knowledge/kb-removed-scope-keys.js +1 -1
  78. package/dist/services/knowledge/kb-self.d.ts +122 -9
  79. package/dist/services/knowledge/kb-self.js +196 -36
  80. package/dist/services/knowledge/member-bible-view.js +16 -3
  81. package/dist/services/knowledge/path-validation.d.ts +7 -0
  82. package/dist/services/knowledge/path-validation.js +11 -0
  83. package/dist/services/knowledge/project-slug.js +3 -2
  84. package/dist/services/knowledge/repository-header.d.ts +77 -0
  85. package/dist/services/knowledge/repository-header.js +233 -0
  86. package/dist/services/knowledge/require-sqlite-project.d.ts +1 -1
  87. package/dist/services/knowledge/require-sqlite-project.js +1 -1
  88. package/dist/services/knowledge/sqlite-provider.d.ts +169 -0
  89. package/dist/services/knowledge/sqlite-provider.js +416 -4
  90. package/dist/services/knowledge/types.d.ts +15 -2
  91. package/dist/services/member-busy.d.ts +12 -0
  92. package/dist/services/member-busy.js +20 -0
  93. package/dist/services/member-config-io.d.ts +3 -2
  94. package/dist/services/member-config-io.js +7 -4
  95. package/dist/services/member-fleet-install.js +1 -0
  96. package/dist/services/member-tool-allowlist.d.ts +1 -1
  97. package/dist/services/member-tool-allowlist.js +8 -4
  98. package/dist/services/port-holder.js +2 -1
  99. package/dist/services/service-manager/types.d.ts +17 -1
  100. package/dist/services/service-manager/windows.d.ts +7 -2
  101. package/dist/services/service-manager/windows.js +28 -11
  102. package/dist/services/service-notice.d.ts +7 -0
  103. package/dist/services/service-notice.js +19 -0
  104. package/dist/services/session-registry.d.ts +13 -0
  105. package/dist/services/session-registry.js +13 -0
  106. package/dist/services/session-roots.d.ts +67 -0
  107. package/dist/services/session-roots.js +126 -0
  108. package/dist/services/statusline.d.ts +21 -0
  109. package/dist/services/statusline.js +97 -1
  110. package/dist/services/supervisor-service-cleanup.js +2 -1
  111. package/dist/services/tool-registry.js +108 -20
  112. package/dist/services/tool-scope.d.ts +34 -1
  113. package/dist/services/tool-scope.js +27 -2
  114. package/dist/services/vcs/azure-devops.js +10 -0
  115. package/dist/services/vcs/bitbucket.d.ts +22 -1
  116. package/dist/services/vcs/bitbucket.js +163 -17
  117. package/dist/services/vcs/types.d.ts +25 -2
  118. package/dist/services/watch/project-resolver.js +2 -1
  119. package/dist/skills/pm/cost.md +5 -1
  120. package/dist/skills/pm/index.md +9 -9
  121. package/dist/skills/pm/sprint.md +2 -1
  122. package/dist/tools/check-status.d.ts +51 -0
  123. package/dist/tools/check-status.js +124 -12
  124. package/dist/tools/code-intelligence-freshness.js +1 -1
  125. package/dist/tools/code-intelligence-gitnexus.d.ts +19 -0
  126. package/dist/tools/code-intelligence-gitnexus.js +166 -9
  127. package/dist/tools/code-intelligence-readiness.d.ts +58 -1
  128. package/dist/tools/code-intelligence-readiness.js +93 -8
  129. package/dist/tools/code-intelligence-reindex.d.ts +25 -1
  130. package/dist/tools/code-intelligence-reindex.js +76 -4
  131. package/dist/tools/code-intelligence.d.ts +1 -1
  132. package/dist/tools/code-intelligence.js +1 -1
  133. package/dist/tools/execute-command.js +14 -8
  134. package/dist/tools/execute-prompt.js +6 -2
  135. package/dist/tools/fleet-snapshot.d.ts +21 -0
  136. package/dist/tools/fleet-snapshot.js +78 -0
  137. package/dist/tools/kb-bible-commit.d.ts +25 -11
  138. package/dist/tools/kb-bible-commit.js +142 -33
  139. package/dist/tools/kb-capture.d.ts +2 -2
  140. package/dist/tools/kb-context.js +47 -27
  141. package/dist/tools/kb-demote.d.ts +27 -0
  142. package/dist/tools/kb-demote.js +37 -0
  143. package/dist/tools/kb-export.d.ts +35 -3
  144. package/dist/tools/kb-export.js +56 -13
  145. package/dist/tools/kb-feedback.d.ts +2 -0
  146. package/dist/tools/kb-feedback.js +17 -7
  147. package/dist/tools/kb-harvest.js +28 -9
  148. package/dist/tools/kb-import.d.ts +18 -2
  149. package/dist/tools/kb-import.js +24 -9
  150. package/dist/tools/kb-invalidate.d.ts +11 -3
  151. package/dist/tools/kb-invalidate.js +80 -7
  152. package/dist/tools/kb-list.js +38 -10
  153. package/dist/tools/kb-promote.js +6 -4
  154. package/dist/tools/kb-query.d.ts +3 -0
  155. package/dist/tools/kb-query.js +181 -37
  156. package/dist/tools/kb-session-prime.d.ts +4 -4
  157. package/dist/tools/kb-session-prime.js +89 -9
  158. package/dist/tools/kb-setup.d.ts +20 -0
  159. package/dist/tools/kb-setup.js +149 -11
  160. package/dist/tools/list-members.js +1 -1
  161. package/dist/tools/member-detail.js +7 -3
  162. package/dist/tools/provision-vcs-auth.d.ts +28 -3
  163. package/dist/tools/provision-vcs-auth.js +53 -7
  164. package/dist/tools/receive-files.js +7 -4
  165. package/dist/tools/send-files.js +5 -4
  166. package/dist/tools/send-message.d.ts +3 -0
  167. package/dist/tools/send-message.js +15 -2
  168. package/dist/tools/stop-prompt.js +3 -1
  169. package/dist/tools/vcs-credential-exec.d.ts +45 -3
  170. package/dist/tools/vcs-credential-exec.js +90 -11
  171. package/dist/utils/process-utils.js +5 -1
  172. package/dist/utils/redact-known-secrets.d.ts +17 -0
  173. package/dist/utils/redact-known-secrets.js +70 -0
  174. package/dist/utils/skill-matrix.js +1 -1
  175. package/dist/utils/vcs-provider-detect.js +2 -2
  176. package/dist/workflows/auto-sprint.js +245 -9
  177. package/package.json +10 -7
  178. package/packages/apra-fleet-client/package.json +1 -1
  179. package/packages/apra-fleet-client/src/client/api.mjs +172 -19
  180. package/packages/apra-fleet-client/src/client/reconnecting-transport.mjs +35 -2
  181. package/packages/apra-fleet-client/src/client/transport.mjs +6 -0
  182. package/packages/apra-fleet-se/apra-pm/agents/backlog-groomer.md +5 -0
  183. package/packages/apra-fleet-se/apra-pm/agents/ci-watcher.md +5 -0
  184. package/packages/apra-fleet-se/apra-pm/agents/deployer.md +20 -2
  185. package/packages/apra-fleet-se/apra-pm/agents/doer.md +38 -2
  186. package/packages/apra-fleet-se/apra-pm/agents/harvester.md +12 -9
  187. package/packages/apra-fleet-se/apra-pm/agents/integ-test-runner.md +5 -0
  188. package/packages/apra-fleet-se/apra-pm/agents/kb-reconciler.md +6 -0
  189. package/packages/apra-fleet-se/apra-pm/agents/plan-reviewer.md +5 -0
  190. package/packages/apra-fleet-se/apra-pm/agents/planner.md +5 -0
  191. package/packages/apra-fleet-se/apra-pm/agents/regression-test-runner.md +5 -0
  192. package/packages/apra-fleet-se/apra-pm/agents/reviewer.md +67 -15
  193. package/packages/apra-fleet-se/apra-pm/agents/schemas/deployer-output.json +5 -0
  194. package/packages/apra-fleet-se/apra-pm/agents/schemas/doer-output.json +78 -2
  195. package/packages/apra-fleet-se/apra-pm/agents/schemas/reviewer-output.json +104 -2
  196. package/packages/apra-fleet-se/apra-pm/skills/pm/cost.md +5 -1
  197. package/packages/apra-fleet-se/apra-pm/skills/pm/index.md +9 -9
  198. package/packages/apra-fleet-se/apra-pm/skills/pm/sprint.md +2 -1
  199. package/packages/apra-fleet-se/bin/cli.mjs +104 -31
  200. package/packages/apra-fleet-se/bin/serve.mjs +46 -8
  201. package/packages/apra-fleet-se/fleet-sprint/abort.mjs +184 -32
  202. package/packages/apra-fleet-se/fleet-sprint/bd-sync-command.mjs +69 -0
  203. package/packages/apra-fleet-se/fleet-sprint/beads-children.mjs +21 -0
  204. package/packages/apra-fleet-se/fleet-sprint/beads-lock-probe.mjs +176 -0
  205. package/packages/apra-fleet-se/fleet-sprint/beads-reachability.mjs +126 -0
  206. package/packages/apra-fleet-se/fleet-sprint/beads-scope.mjs +158 -1
  207. package/packages/apra-fleet-se/fleet-sprint/contracts.mjs +82 -2
  208. package/packages/apra-fleet-se/fleet-sprint/coordination.mjs +23 -6
  209. package/packages/apra-fleet-se/fleet-sprint/decision-notify.mjs +338 -0
  210. package/packages/apra-fleet-se/fleet-sprint/decision-wait.mjs +731 -0
  211. package/packages/apra-fleet-se/fleet-sprint/decisions.mjs +372 -0
  212. package/packages/apra-fleet-se/fleet-sprint/dispatch-role.mjs +44 -11
  213. package/packages/apra-fleet-se/fleet-sprint/docs/README.md +4 -1
  214. package/packages/apra-fleet-se/fleet-sprint/dolt-settle.mjs +9 -3
  215. package/packages/apra-fleet-se/fleet-sprint/dolt-sync.mjs +314 -19
  216. package/packages/apra-fleet-se/fleet-sprint/errors.mjs +72 -4
  217. package/packages/apra-fleet-se/fleet-sprint/git-sync.mjs +7 -1
  218. package/packages/apra-fleet-se/fleet-sprint/git-topology.mjs +112 -1
  219. package/packages/apra-fleet-se/fleet-sprint/guarded-modules.mjs +36 -2
  220. package/packages/apra-fleet-se/fleet-sprint/kb.mjs +736 -101
  221. package/packages/apra-fleet-se/fleet-sprint/member-init-probe.mjs +1 -1
  222. package/packages/apra-fleet-se/fleet-sprint/member-provisioning.mjs +7 -1
  223. package/packages/apra-fleet-se/fleet-sprint/phases/deploy.mjs +49 -2
  224. package/packages/apra-fleet-se/fleet-sprint/phases/develop.mjs +206 -3
  225. package/packages/apra-fleet-se/fleet-sprint/phases/final-review.mjs +61 -3
  226. package/packages/apra-fleet-se/fleet-sprint/phases/harvest.mjs +81 -31
  227. package/packages/apra-fleet-se/fleet-sprint/phases/plan.mjs +7 -3
  228. package/packages/apra-fleet-se/fleet-sprint/phases/publish-pr.mjs +39 -14
  229. package/packages/apra-fleet-se/fleet-sprint/phases/re-review.mjs +17 -1
  230. package/packages/apra-fleet-se/fleet-sprint/phases/review.mjs +18 -3
  231. package/packages/apra-fleet-se/fleet-sprint/pr-body.mjs +14 -1
  232. package/packages/apra-fleet-se/fleet-sprint/prompts.mjs +32 -5
  233. package/packages/apra-fleet-se/fleet-sprint/runner.js +824 -98
  234. package/packages/apra-fleet-se/fleet-sprint/se-os-commands.mjs +4 -2
  235. package/packages/apra-fleet-se/fleet-sprint/se-posix.mjs +54 -1
  236. package/packages/apra-fleet-se/fleet-sprint/se-windows.mjs +29 -2
  237. package/packages/apra-fleet-se/fleet-sprint/set-aside.mjs +288 -0
  238. package/packages/apra-fleet-se/fleet-sprint/skills/fleet-supervisor/SKILL.md +3 -2
  239. package/packages/apra-fleet-se/fleet-sprint/sprint-args.mjs +20 -0
  240. package/packages/apra-fleet-se/fleet-sprint/sprint-report.mjs +21 -0
  241. package/packages/apra-fleet-se/fleet-sprint/sprint-state.mjs +9 -0
  242. package/packages/apra-fleet-se/fleet-sprint/vcs-auth.mjs +605 -32
  243. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/bitbucket.mjs +811 -17
  244. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/index.mjs +89 -1
  245. package/packages/apra-fleet-se/fleet-sprint/viewer-extensions.mjs +225 -2
  246. package/packages/apra-fleet-se/fleet-sprint/worklists.mjs +59 -3
  247. package/packages/apra-fleet-se/src/supervisor/api.mjs +148 -8
  248. package/packages/apra-fleet-se/src/supervisor/dashboard.mjs +6 -3
  249. package/packages/apra-fleet-se/src/supervisor/dolt-mutex.mjs +30 -10
  250. package/packages/apra-fleet-se/src/supervisor/fleet-members.mjs +17 -4
  251. package/packages/apra-fleet-se/src/supervisor/history.mjs +8 -1
  252. package/packages/apra-fleet-se/src/supervisor/id-allocator.mjs +92 -2
  253. package/packages/apra-fleet-se/src/supervisor/proxy.mjs +26 -1
  254. package/packages/apra-fleet-se/src/supervisor/server.mjs +151 -8
  255. package/packages/apra-fleet-se/src/supervisor/spawner.mjs +11 -9
  256. package/packages/apra-fleet-se/src/supervisor/watchdog.mjs +7 -1
  257. package/packages/apra-fleet-workflow/package.json +2 -1
  258. package/packages/apra-fleet-workflow/src/viewer/index.mjs +86 -5
  259. package/packages/apra-fleet-workflow/src/viewer/request-guard.mjs +222 -0
  260. package/packages/apra-fleet-workflow/src/workflow/index.mjs +34 -2
  261. package/plugins/claude-code/fleet-status/.claude-plugin/plugin.json +7 -0
  262. package/plugins/claude-code/fleet-status/hooks/hooks.json +1 -0
  263. package/plugins/claude-code/fleet-status/hooks/register.tsx +906 -0
  264. package/plugins/claude-code/fleet-status/types/index.d.ts +88 -0
  265. package/skills/fleet/auth-bitbucket.md +47 -20
  266. package/skills/fleet/onboarding.md +1 -1
  267. package/skills/fleet/skill-matrix.md +3 -3
  268. package/version.json +1 -1
@@ -15,7 +15,8 @@ import {
15
15
  createFleetHttpTransport,
16
16
  getServerInfoPath,
17
17
  } from '@apralabs/apra-fleet-client/server-resolution';
18
- import { beadsExtension, kbCodeIntelExtension } from '../fleet-sprint/viewer-extensions.mjs';
18
+ import { beadsExtension, kbCodeIntelExtension, decisionsExtension } from '../fleet-sprint/viewer-extensions.mjs';
19
+ import { DECISION_PAUSE_SOURCE } from '../fleet-sprint/decision-wait.mjs';
19
20
  import { validateIssueId, validateBranchName, validateBranchPair, createMemberReservationClient, resyncReacquiredMember, commandResultToSoftGit } from '../fleet-sprint/runner.js';
20
21
  import { normalizeRole } from '../fleet-sprint/contracts.mjs';
21
22
  import { prepareLaunchTopology, toAlignCommandResult } from '../fleet-sprint/member-align.mjs';
@@ -163,6 +164,9 @@ export function buildOptionsSpec() {
163
164
  // env fallback FLEET_SPRINT_EXPECT_BEADS. Omitted (direct launch):
164
165
  // the runner takes the expectation from the backlog member.
165
166
  'expect-beads': { type: 'string' },
167
+ // Operator-notification config for a pending decision (JSON; env
168
+ // fallback FLEET_SPRINT_DECISION_NOTIFY). See decision-notify.mjs.
169
+ 'decision-notify': { type: 'string' },
166
170
  budget: { type: 'string' },
167
171
  // Stabilization Issue 32: per-dispatch time budget in seconds
168
172
  // (timeout_s == max_total_s at every dispatch; integ ceiling 2x).
@@ -181,6 +185,9 @@ export function buildOptionsSpec() {
181
185
  // body's phases.regression:"skip"). Never silent: logged, and reported in
182
186
  // the sprint analysis and the PR body.
183
187
  'skip-regression': { type: 'boolean' },
188
+ // Reviewer KB demotion loop switch: on (default) or off. Forwarded as the
189
+ // runner's kb_demotion_loop arg, which rejects any other value loudly.
190
+ 'kb-demotion-loop': { type: 'string' },
184
191
  // --ci-gate is DELIBERATELY NOT WIRED (2026-10-01): the runner's
185
192
  // ci_gate arg is disabled until the CI-as-quality-resource epic
186
193
  // (apra-fleet-dv8i) designs the flow -- see fleet-sprint/sprint-args.mjs.
@@ -219,6 +226,12 @@ Options:
219
226
  the supervisor; env fallback FLEET_SPRINT_EXPECT_BEADS. Omitted: the
220
227
  backlog member's own 'bd where' becomes the expectation and every
221
228
  other member must match it. A mismatch aborts before any bd mutation.
229
+ --decision-notify <json> Where to notify the operator of a pending decision, as JSON
230
+ ({"message_member","email":{provider,from,to,host,port,user,secure},
231
+ "dashboard_url","timeout_s"}); env fallback FLEET_SPRINT_DECISION_NOTIFY.
232
+ Credentials stay in the fleet credential store. message_member
233
+ defaults to "orchestrator" (the operator's channel-capable
234
+ session); a channel with no target is logged once at launch.
222
235
  --budget <usd> USD ceiling for this run's total estimated spend. Optional;
223
236
  omitted (the default) means unlimited, identical to prior behavior.
224
237
  --dispatch-timeout-s <s> Per-dispatch time budget in seconds (default 9000). The hard ceiling
@@ -237,6 +250,10 @@ Options:
237
250
  uses legacy shared-workspace mode (all members on the same HEAD).
238
251
  --skip-regression Skip the once-per-sprint regression pass. Logged, and stated in the
239
252
  sprint analysis and the PR body. Integration tests still run.
253
+ --kb-demotion-loop <on|off>
254
+ Reviewer KB demotion loop (default: on). 'off' offers the reviewer no
255
+ demotion candidates and issues no kb_demote; the log says so. Any
256
+ other value is rejected.
240
257
  -h, --help Show this help message.
241
258
  `.trim();
242
259
 
@@ -353,7 +370,7 @@ export async function resolveRoleMapWithWarnings(rawValue, deps = {}) {
353
370
  * }} opts
354
371
  * @returns {object}
355
372
  */
356
- export function buildRunnerArgs({ targetIssues, members, branch, baseBranch, goal, maxCycles, requirementsFile, roleMap, roleMapWarnings, budget, dispatchTimeoutS, usageLimitMaxWaitS, usageLimitMaxReprobes, serviceUrl, runId, expectBeads, skipRegression, ciGate }) {
373
+ export function buildRunnerArgs({ targetIssues, members, branch, baseBranch, goal, maxCycles, requirementsFile, roleMap, roleMapWarnings, budget, dispatchTimeoutS, usageLimitMaxWaitS, usageLimitMaxReprobes, serviceUrl, runId, expectBeads, skipRegression, kbDemotionLoop, ciGate, decisionNotify }) {
357
374
  const args = {
358
375
  target_issues: targetIssues,
359
376
  members,
@@ -385,9 +402,12 @@ export function buildRunnerArgs({ targetIssues, members, branch, baseBranch, goa
385
402
  if (runId !== undefined) args.run_id = runId;
386
403
  // Only forwarded when set, so a default launch's runner args are unchanged.
387
404
  if (skipRegression === true) args.skip_regression = true;
405
+ // Forwarded verbatim when set; validateArgs rejects anything but on/off.
406
+ if (kbDemotionLoop !== undefined) args.kb_demotion_loop = kbDemotionLoop;
388
407
  // The raw --expect-beads JSON, forwarded verbatim; runner.js's
389
408
  // validateArgs() parses it (validateExpectBeads) and rejects bad JSON.
390
409
  if (expectBeads !== undefined) args.expect_beads = expectBeads;
410
+ if (decisionNotify !== undefined) args.decision_notify = decisionNotify;
391
411
  // --ci-gate is not wired (apra-fleet-dv8i); ci_gate is never forwarded.
392
412
  // if (ciGate !== undefined) args.ci_gate = ciGate;
393
413
  return args;
@@ -632,6 +652,46 @@ export async function reReserveOnResume({ sprintReservation, resyncMember, reque
632
652
  }
633
653
  }
634
654
 
655
+ // Reservation handling across a cooperative pause/resume, by pause source.
656
+ // A pause hands every member reservation back (so another sprint may use the
657
+ // members while this one is parked) and the matching resume re-acquires them
658
+ // owner-checked and resyncs each one -- EXCEPT the paused-awaiting-decision
659
+ // pause (source 'needs_decision', fleet-sprint/decision-wait.mjs): that run is
660
+ // waiting on an operator, not on a member, and may wait hours, so it keeps
661
+ // every reservation (no other sprint can take a member meanwhile) and touches
662
+ // no member; its resume then has nothing to re-acquire or resync. The source
663
+ // comes from the 'pause:requested' payload ('paused' carries none). The
664
+ // re-reserve runs only for a pause whose 'paused' handler actually released.
665
+ // Exported so the per-source behaviour is unit-testable without a live engine.
666
+ export function wirePauseReservations({ workflow, releaseForPause, reReserve, log = () => {} }) {
667
+ let pauseSource = null;
668
+ let released = false;
669
+ workflow.on('pause:requested', (payload) => {
670
+ pauseSource = payload && payload.source ? payload.source : null;
671
+ });
672
+ workflow.on('paused', () => {
673
+ if (pauseSource === DECISION_PAUSE_SOURCE) {
674
+ log('[member-reservation] paused awaiting an operator decision: keeping every member reservation for the wait.');
675
+ return;
676
+ }
677
+ released = true;
678
+ // Started synchronously in the 'paused' event, as before; best-effort
679
+ // (a release hiccup must never fail a pause).
680
+ const failed = (err) => console.error('[member-reservation] release-on-pause failed:', err && err.message ? err.message : err);
681
+ try {
682
+ Promise.resolve(releaseForPause()).catch(failed);
683
+ } catch (err) {
684
+ failed(err);
685
+ }
686
+ });
687
+ workflow.setPreResumeHook(async (reason) => {
688
+ if (!released) return undefined;
689
+ const result = await reReserve(reason);
690
+ released = false;
691
+ return result;
692
+ });
693
+ }
694
+
635
695
  async function main() {
636
696
  const { values } = parseCliArgs(process.argv.slice(2));
637
697
 
@@ -791,6 +851,9 @@ async function main() {
791
851
  // is retried once only when it provably never reached the server.
792
852
  const transport = createFleetHttpTransport(connection, { dirname: __dirname, exists: existsSync });
793
853
  await transport.start();
854
+ // Every exit below releases the server session first: stop() alone leaves
855
+ // it (and its McpServer) open on the fleet server until idle eviction.
856
+ const closeFleetTransport = () => transport.close().catch(() => { /* best effort */ });
794
857
  const mcpClient = new McpClient(transport);
795
858
 
796
859
  const fleetApi = new ApraFleet(mcpClient);
@@ -813,14 +876,14 @@ async function main() {
813
876
  const result = resolveMemberValidation({ rawMembers, registeredNames, allowMissingMembers });
814
877
  if (!result.ok) {
815
878
  console.error(result.message);
816
- transport.stop();
879
+ await closeFleetTransport();
817
880
  process.exit(1);
818
881
  }
819
882
  if (result.message) console.warn(result.message);
820
883
  validMembers = result.validMembers;
821
884
  } catch (err) {
822
885
  console.error(`Error: Failed to list fleet members: ${err.message}`);
823
- transport.stop();
886
+ await closeFleetTransport();
824
887
  process.exit(1);
825
888
  }
826
889
 
@@ -865,7 +928,7 @@ async function main() {
865
928
  });
866
929
  if (!issueCheck.ok) {
867
930
  console.error(issueCheck.message);
868
- transport.stop();
931
+ await closeFleetTransport();
869
932
  process.exit(1);
870
933
  }
871
934
 
@@ -951,7 +1014,10 @@ async function main() {
951
1014
  const onLaunchSigint = () => {
952
1015
  sprintReservation.releaseAll()
953
1016
  .catch((err) => console.error('[member-reservation] release-on-SIGINT failed:', err))
954
- .finally(() => process.exit(130));
1017
+ .finally(async () => {
1018
+ await closeFleetTransport();
1019
+ process.exit(130);
1020
+ });
955
1021
  };
956
1022
  process.once('SIGINT', onLaunchSigint);
957
1023
  const topology = await reserveThenAlign({ sprintReservation, align: () => prepareLaunchTopology({
@@ -967,7 +1033,7 @@ async function main() {
967
1033
  }) });
968
1034
  if (!topology.ok) {
969
1035
  console.error(`Error: ${topology.message}`);
970
- transport.stop();
1036
+ await closeFleetTransport();
971
1037
  process.exit(1);
972
1038
  }
973
1039
  if (!topology.singleMember) {
@@ -993,7 +1059,7 @@ async function main() {
993
1059
  name: 'Fleet-Sprint',
994
1060
  // kbCodeIntelExtension: its own tab (per-member, per-dispatch kb_* and
995
1061
  // code_* call counts), separate from the Tasks tab.
996
- dashboardExtensions: [beadsExtension, kbCodeIntelExtension],
1062
+ dashboardExtensions: [beadsExtension, kbCodeIntelExtension, decisionsExtension],
997
1063
  // apra-fleet-eft.37.1/37.2: the core viewer now speaks opts.runId
998
1064
  // (opts.sprintId is a deprecated BOUNDARY-COMPAT alias -- never use
999
1065
  // it from here).
@@ -1037,14 +1103,14 @@ async function main() {
1037
1103
  console.error(`Error: ${message}`);
1038
1104
  sprintReservation.releaseAll()
1039
1105
  .catch((err) => console.error('[member-reservation] release on viewer failure failed:', err && err.message ? err.message : err))
1040
- .finally(() => {
1041
- transport.stop();
1106
+ .finally(async () => {
1107
+ await closeFleetTransport();
1042
1108
  process.exit(1);
1043
1109
  });
1044
1110
  },
1045
1111
  });
1046
1112
 
1047
- console.log(`Dashboard live at http://localhost:${viewerPort}`);
1113
+ console.log(`Dashboard live at http://127.0.0.1:${viewerPort}`);
1048
1114
 
1049
1115
  if (viewerFailed) return; // onError releases the reservations, then exits
1050
1116
 
@@ -1083,10 +1149,6 @@ async function main() {
1083
1149
  const res = await fleetApi.executeCommand({ command: cmd, member_name: member });
1084
1150
  return commandResultToSoftGit(res);
1085
1151
  };
1086
- workflow.on('paused', () => {
1087
- sprintReservation.releaseForPause().catch((err) =>
1088
- console.error('[member-reservation] release-on-pause failed:', err && err.message ? err.message : err));
1089
- });
1090
1152
  // (apra-fleet-p2to.1.3) The re-reserve + per-member resync is registered as
1091
1153
  // an AWAITABLE pre-resume hook, not a fire-and-forget 'resumed' listener.
1092
1154
  // requestResume() drains this hook as a hard barrier -- while the run is
@@ -1104,19 +1166,25 @@ async function main() {
1104
1166
  // sees exactly which members block the resume. requestPause() is still
1105
1167
  // passed for the exported helper's standalone contract; here it is a no-op
1106
1168
  // because the run has not yet been unpaused.
1107
- workflow.setPreResumeHook(() => reReserveOnResume({
1108
- sprintReservation,
1109
- resyncMember: (member) => resyncReacquiredMember({
1110
- member,
1111
- branch: branchName,
1112
- baseBranch,
1113
- runGit: (cmd) => runGitSoft(cmd, member),
1114
- doltPull: (m) => runCommand('bd dolt pull', m),
1115
- log: (msg) => console.log(msg),
1169
+ // A decision pause keeps its reservations (see wirePauseReservations).
1170
+ wirePauseReservations({
1171
+ workflow,
1172
+ releaseForPause: () => sprintReservation.releaseForPause(),
1173
+ log: (msg) => console.log(msg),
1174
+ reReserve: () => reReserveOnResume({
1175
+ sprintReservation,
1176
+ resyncMember: (member) => resyncReacquiredMember({
1177
+ member,
1178
+ branch: branchName,
1179
+ baseBranch,
1180
+ runGit: (cmd) => runGitSoft(cmd, member),
1181
+ doltPull: (m) => runCommand('bd dolt pull', m),
1182
+ log: (msg) => console.log(msg),
1183
+ }),
1184
+ requestPause: (reason) => workflow.requestPause(reason),
1185
+ log: (msg) => console.error(msg),
1116
1186
  }),
1117
- requestPause: (reason) => workflow.requestPause(reason),
1118
- log: (msg) => console.error(msg),
1119
- }));
1187
+ });
1120
1188
 
1121
1189
  let reservationReleased = false;
1122
1190
  const releaseReservationOnce = async () => {
@@ -1133,7 +1201,10 @@ async function main() {
1133
1201
  const onSigint = () => {
1134
1202
  releaseReservationOnce()
1135
1203
  .catch((err) => console.error('[member-reservation] release-on-SIGINT failed:', err))
1136
- .finally(() => process.exit(130));
1204
+ .finally(async () => {
1205
+ await closeFleetTransport();
1206
+ process.exit(130);
1207
+ });
1137
1208
  };
1138
1209
  process.removeListener('SIGINT', onLaunchSigint);
1139
1210
  process.once('SIGINT', onSigint);
@@ -1158,7 +1229,9 @@ async function main() {
1158
1229
  serviceUrl,
1159
1230
  runId: effectiveRunId,
1160
1231
  expectBeads,
1232
+ decisionNotify: (values['decision-notify'] || process.env.FLEET_SPRINT_DECISION_NOTIFY || '').trim() || undefined,
1161
1233
  skipRegression: Boolean(values['skip-regression']),
1234
+ kbDemotionLoop: values['kb-demotion-loop'],
1162
1235
  // ciGate: values['ci-gate'], -- not wired (apra-fleet-dv8i)
1163
1236
  }),
1164
1237
  // apra-fleet-eft.75.1: wires this already-connected mcpClient
@@ -1174,7 +1247,7 @@ async function main() {
1174
1247
  await releaseReservationOnce();
1175
1248
  console.log('Sprint finished:', res);
1176
1249
  server.close();
1177
- transport.stop();
1250
+ await closeFleetTransport();
1178
1251
  process.exit(0);
1179
1252
  } catch (err) {
1180
1253
  process.removeListener('SIGINT', onSigint);
@@ -1194,7 +1267,7 @@ async function main() {
1194
1267
  const graceMs = Number(process.env.AUTO_SPRINT_FAILURE_GRACE_MS ?? 5 * 60 * 1000);
1195
1268
  if (graceMs > 0) {
1196
1269
  console.log(
1197
- `Sprint FAILED. Dashboard remains live at http://localhost:${viewerPort} for ` +
1270
+ `Sprint FAILED. Dashboard remains live at http://127.0.0.1:${viewerPort} for ` +
1198
1271
  `${Math.round(graceMs / 1000)}s so you can inspect the final state -- press Ctrl-C to exit sooner.`
1199
1272
  );
1200
1273
  await new Promise((resolve) => {
@@ -1207,7 +1280,7 @@ async function main() {
1207
1280
  });
1208
1281
  }
1209
1282
  server.close();
1210
- transport.stop();
1283
+ await closeFleetTransport();
1211
1284
  process.exit(process.exitCode || 1);
1212
1285
  }
1213
1286
  }
@@ -21,7 +21,7 @@ import { parseArgs } from 'node:util';
21
21
  import path from 'node:path';
22
22
  import fs from 'node:fs';
23
23
  import { pathToFileURL, fileURLToPath } from 'node:url';
24
- import { createSupervisor, DEFAULT_SERVICE_PORT, readJsonBody, sendJson } from '../src/supervisor/server.mjs';
24
+ import { createSupervisor, DEFAULT_SERVICE_PORT, DEFAULT_SERVICE_HOST, SUPERVISOR_ALLOWED_HOSTS_ENV, readJsonBody, sendJson } from '../src/supervisor/server.mjs';
25
25
  import { createLedger } from '../src/supervisor/ledger.mjs';
26
26
  import { createHistory, HISTORY_EVENTS } from '../src/supervisor/history.mjs';
27
27
  import { createSpawner } from '../src/supervisor/spawner.mjs';
@@ -32,7 +32,7 @@ import { createChildPortResolver } from '../src/supervisor/child-port.mjs';
32
32
  import { createHistoryView, registerHistoryViewRoutes } from '../src/supervisor/history-view.mjs';
33
33
  import { createLogView, registerLogViewRoutes } from '../src/supervisor/log-view.mjs';
34
34
  import { installSelfLogTee, createSelfLogView, registerSelfLogRoutes } from '../src/supervisor/self-log.mjs';
35
- import { createIdAllocator, registerIdAllocatorRoutes } from '../src/supervisor/id-allocator.mjs';
35
+ import { createIdAllocator, registerIdAllocatorRoutes, defaultDataDir as defaultAllocatorDataDir } from '../src/supervisor/id-allocator.mjs';
36
36
  import { createDoltMutex, registerDoltMutexRoutes } from '../src/supervisor/dolt-mutex.mjs';
37
37
  // eft.4.8.1: the operator-facing surface -- PID-liveness watchdog (eft.4.3),
38
38
  // dashboard/backlog/launch-form (eft.6.*), and the six sprint/member/backlog
@@ -68,6 +68,16 @@ termination signal (Ctrl-C / SIGTERM).
68
68
 
69
69
  Options:
70
70
  --port <port> HTTP service port for the supervisor API. Default: ${DEFAULT_SERVICE_PORT}.
71
+ --host <addr> Interface the supervisor API binds. Default: ${DEFAULT_SERVICE_HOST}
72
+ (loopback only). Pass 0.0.0.0 to expose it off-box;
73
+ the API has no authentication, so that is an explicit
74
+ opt-in.
75
+ --allowed-host <name> Extra Host header name the supervisor answers to
76
+ (repeatable, or comma-separated). Loopback names, IP
77
+ literals and --host are always accepted; any other
78
+ name is refused (DNS-rebinding defence), so add the
79
+ DNS name operators use for an off-box bind. Also
80
+ read from FLEET_SUPERVISOR_ALLOWED_HOSTS.
71
81
  --beads-dir <path> Project folder (or its .beads dir) whose beads tracker
72
82
  this supervisor runs against. Default: discovered by
73
83
  walking up from the current directory, exactly like
@@ -78,7 +88,8 @@ Options:
78
88
  -h, --help Show this help message.
79
89
 
80
90
  Environment:
81
- FLEET_SE_DATA_DIR Service data dir (ledger/history/logs).
91
+ FLEET_SE_DATA_DIR Service data dir (ledger/history/logs and
92
+ child-id-allocator.json).
82
93
  FLEET_SE_SWEEP_OWNER_DATA_DIR Scope the dolt-orphan-sweep to ephemeral
83
94
  dolt sql-servers whose --data-dir is under
84
95
  this path, so an isolated supervisor
@@ -179,6 +190,8 @@ export function parseServeArgs(argv) {
179
190
  args: argv,
180
191
  options: {
181
192
  port: { type: 'string' },
193
+ host: { type: 'string' },
194
+ 'allowed-host': { type: 'string', multiple: true },
182
195
  'beads-dir': { type: 'string' },
183
196
  help: { type: 'boolean', short: 'h' },
184
197
  },
@@ -231,6 +244,7 @@ export async function serveMain(argv = process.argv.slice(2), deps = {}) {
231
244
  process.once('exit', () => selfLog.stop());
232
245
 
233
246
  let port = DEFAULT_SERVICE_PORT;
247
+ const host = values.host !== undefined && values.host !== '' ? values.host : DEFAULT_SERVICE_HOST;
234
248
  if (values.port !== undefined) {
235
249
  port = Number(values.port);
236
250
  if (!Number.isInteger(port) || port < 1 || port > 65535) {
@@ -372,7 +386,7 @@ export async function serveMain(argv = process.argv.slice(2), deps = {}) {
372
386
  // see createSprintController's launch()), but history's own copy stays
373
387
  // discoverable even after the reservation is eventually released.
374
388
  const spawner = createSpawner({
375
- serviceUrl: `http://localhost:${port}`,
389
+ serviceUrl: `http://${host === '0.0.0.0' || host === '::' ? '127.0.0.1' : host}:${port}`,
376
390
  // Sprint children run from the project root (the folder holding the
377
391
  // discovered .beads, not whatever subfolder the operator started in)
378
392
  // and carry the resolved identity so the engine can verify every
@@ -415,7 +429,7 @@ export async function serveMain(argv = process.argv.slice(2), deps = {}) {
415
429
  // (load persisted high-water marks + the abandoned-reservation sweep) is
416
430
  // driven by the seam machinery; its HTTP routes let detached sprint children
417
431
  // mint collision-free child ids under a shared parent (constraint C.4).
418
- const idAllocator = createIdAllocator();
432
+ const idAllocator = createIdAllocator({ dataDir: defaultAllocatorDataDir() });
419
433
 
420
434
  // eft.9.2: the supervisor-owned global dolt push mutex -- a LOAD-BEARING v1
421
435
  // requirement (PoC constraints C.2/C.3). Every cross-sprint `bd dolt push`
@@ -498,7 +512,29 @@ export async function serveMain(argv = process.argv.slice(2), deps = {}) {
498
512
  ownerDataDirPrefix: sweepOwnerDataDir,
499
513
  });
500
514
 
501
- const supervisor = createSupervisor({ port, ledger, spawner, watchdog, dashboard, idAllocator, doltMutex, doltOrphanSweep, beadsIdentity, backlogMember });
515
+ // Shutdown bounds (see server.mjs stop()): each seam's stop() is bounded and
516
+ // the process is force-exited FORCE_EXIT ms after shutdown starts, naming any
517
+ // hung seam. Test-only hook FLEET_SE_TEST_HANG_SEAM=<seam name> makes that
518
+ // seam's stop() never settle so the bound can be exercised end to end.
519
+ const envMs = (name, dflt) => {
520
+ const n = Number(process.env[name]);
521
+ return Number.isFinite(n) && n > 0 ? n : dflt;
522
+ };
523
+ const hangSeam = process.env.FLEET_SE_TEST_HANG_SEAM;
524
+ const hangable = { dashboard, watchdog, doltOrphanSweep };
525
+ if (hangSeam && hangable[hangSeam]) {
526
+ hangable[hangSeam] = { ...hangable[hangSeam], name: hangSeam, stop: () => new Promise(() => {}) };
527
+ console.warn(`[supervisor] TEST HOOK: seam '${hangSeam}' stop() will never settle`);
528
+ }
529
+ const supervisor = createSupervisor({
530
+ port, host,
531
+ // CLI names add to (not replace) the env var's list.
532
+ allowedHosts: [...(values['allowed-host'] ?? []), ...String(process.env[SUPERVISOR_ALLOWED_HOSTS_ENV] ?? '').split(/[\s,]+/).filter(Boolean)],
533
+ ledger, spawner, watchdog: hangable.watchdog, dashboard: hangable.dashboard, idAllocator, doltMutex,
534
+ doltOrphanSweep: hangable.doltOrphanSweep, beadsIdentity, backlogMember,
535
+ seamStopTimeoutMs: envMs('FLEET_SE_SHUTDOWN_SEAM_TIMEOUT_MS', 3000),
536
+ forcedExitMs: envMs('FLEET_SE_SHUTDOWN_FORCE_EXIT_MS', 10_000),
537
+ });
502
538
  registerIdAllocatorRoutes(supervisor, idAllocator, { readJsonBody, sendJson });
503
539
  registerDoltMutexRoutes(supervisor, doltMutex, { readJsonBody, sendJson });
504
540
 
@@ -616,8 +652,10 @@ export async function serveMain(argv = process.argv.slice(2), deps = {}) {
616
652
  // Keep the process alive until an explicit shutdown resolves. Awaiting this
617
653
  // is what makes `fleet-se serve` "always-on" -- nothing else drives exit.
618
654
  await supervisor.shutdownRequested;
619
- beadsView.stop();
620
- if (typeof backlogMember.stop === 'function') backlogMember.stop();
655
+ try { beadsView.stop(); } catch (err) { console.error('[supervisor] beadsView stop failed:', err); }
656
+ try { if (typeof backlogMember.stop === 'function') backlogMember.stop(); } catch (err) { console.error('[supervisor] backlogMember stop failed:', err); }
657
+ const hung = supervisor.hungSeams;
658
+ console.log(`[supervisor] exiting (code 0)${hung.length ? `; seams that did not stop in time: ${hung.join(', ')}` : ''}`);
621
659
  return { exitCode: 0 };
622
660
  }
623
661