@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
@@ -2,20 +2,37 @@
2
2
  * @typedef {Object} ExecutePromptOptions
3
3
  * @property {string} prompt - The prompt to send to the LLM on the remote member
4
4
  * @property {string} [agent] - Optional agent name to activate
5
- * @property {number} [max_total_s] - Hard ceiling in seconds
5
+ * @property {number} [max_total_s] - Hard ceiling in seconds, measured from when the server
6
+ * receives the call (setup counts); exceeding it returns reason 'max_total_time'
6
7
  * @property {number} [max_turns] - Max turns for claude -p (default: 50)
8
+ * @property {boolean} [fail_on_permission_denial] - Strict permission handling (default false).
9
+ * true: a refused tool call fails with reason 'permission_denied' (except a healable:false
10
+ * Claude refusal on a complete reply, which is a permissionWarning). Omitted/false: a complete
11
+ * Claude reply succeeds with the refusals in permissionWarning; AGY refusals still fail.
12
+ * A max_turns/auth/server/overloaded result keeps its own reason either way, with the
13
+ * refusals attached as permissionDenied.
7
14
  * @property {string} [member_id] - UUID of the member
8
15
  * @property {string} [member_name] - Friendly name of the member
9
16
  * @property {string} [model] - Model tier ("cheap", "standard", "premium") or a specific model ID
10
- * @property {boolean|string} [resume] - Resume the previous session if one exists. Defaults to
17
+ * @property {boolean|string} [resume] - Resume the previous session if one exists (`true` starts
18
+ * fresh instead when the stored session was recorded by a different server build). Defaults to
11
19
  * true at this client/transport layer when the field is omitted entirely. NOTE: the
12
20
  * FleetWorkflow.agent() workflow layer (packages/apra-fleet-workflow/src/workflow/index.mjs)
13
21
  * always sends this field explicitly, defaulting it to `false` for workflow-authored
14
22
  * prompts (see AgentOptions.resume there and apra-fleet-unw.3 / F10) -- so workflow
15
23
  * callers effectively opt out of this client-level default unless they ask for resume.
24
+ * CALLER OBLIGATION: anything reaching executePrompt() WITHOUT going through that
25
+ * workflow layer must set this field explicitly. Omitting it is never neutral -- the
26
+ * server resumes the member's stored last session, so a one-off instruction silently
27
+ * lands in whatever unrelated (and possibly very large) conversation that member last
28
+ * ran. This client deliberately does NOT inject a default of its own: doing so would
29
+ * change the documented tool contract for every existing caller. State the intent at
30
+ * the call site: `true` to continue that member's prior session, a session-id string
31
+ * to continue a specific one, `false` for a self-contained dispatch.
16
32
  * @property {string} [session_id] - Optional explicit session ID to resume (shorthand alias for resume: "<sessionId>")
33
+ * @property {boolean|string} [fork] - Branch a NEW session seeded from an existing one instead of continuing it in place. true = fork from the member's stored last session. A session-id STRING = fork from exactly that session. Mutually exclusive with resume (any non-default value) and with session_id.
17
34
  * @property {Record<string, string>} [substitutions] - Optional map of token name to replacement value
18
- * @property {number} [timeout_s] - Inactivity timeout in seconds (default: 300)
35
+ * @property {number} [timeout_s] - Inactivity timeout in seconds -- always drives the stall detector's per-dispatch baseline threshold, measured against the member's own session transcript activity (default: 300). Per-provider, it ALSO arms the exec-level rolling timer against this dispatch's stdout/stderr channel for Codex and Copilot, which have no pollable transcript; Claude and AGY take that exec-channel ceiling from max_total_s instead; and OpenCode keeps BOTH signals armed at once (this exec-channel timer plus coarse log-directory-mtime polling, combined with OR semantics -- either advancing counts as not-stalled), since its transcript signal is directory-level only, not a per-turn file (see ProviderAdapter.execTimeoutSource() server-side)
19
36
  * @property {number} [expected_context_tokens] - Optional estimate of how many
20
37
  * tokens this dispatch will add to the target session's context. When set (or context_size is
21
38
  * set), the server compares it against the session's remaining context-window headroom BEFORE
@@ -38,9 +55,144 @@
38
55
  * cannot cancel a job already accepted by the remote fleet-server (see client.mjs).
39
56
  */
40
57
 
58
+ /**
59
+ * apra-fleet-hzeb.2: a provider-agnostic "this dispatch cannot make progress until
60
+ * `resumeAt`" signal, mirroring src/providers/provider.ts's UsageLimitSignal exactly.
61
+ * @typedef {Object} UsageLimitSignal
62
+ * @property {'usage_limit'} type
63
+ * @property {string} resumeAt - ISO-8601 UTC instant at which work may resume. Never null:
64
+ * when the provider CLI exposes a real reset time it is parsed (resumeAtSource: 'parsed');
65
+ * otherwise it falls back to a guessed window (resumeAtSource: 'guessed').
66
+ * @property {'parsed'|'guessed'} resumeAtSource
67
+ * @property {string} message - The raw provider message/output that identified this as a
68
+ * usage/quota limit (for logging).
69
+ */
70
+
71
+ /**
72
+ * One tool call the member CLI refused, mirroring src/providers/provider.ts's PermissionDenialItem.
73
+ * @typedef {Object} PermissionDenialItem
74
+ * @property {string} action - Provider permission action, e.g. 'command', 'read_file', 'mcp'.
75
+ * @property {string} [target] - The concrete target when the CLI named it, e.g. 'git status --short --branch'.
76
+ * @property {string[]} [suggestedGrants] - compose_permissions grants that would allow this one
77
+ * call, primary first (empty when no grant maps to it).
78
+ */
79
+
80
+ /**
81
+ * execute_prompt's `permissionDenied` block, mirroring src/providers/provider.ts's PermissionDenial.
82
+ * @typedef {Object} PermissionDenied
83
+ * @property {string[]} actions - Unique denied actions, in first-seen order.
84
+ * @property {PermissionDenialItem[]} denials - Each refused call, with its target when known.
85
+ * @property {string[]} suggestedGrants - compose_permissions `grant` values that would allow the
86
+ * denied calls, primary first (for an agy command or unsandboxed denial, on any OS, a
87
+ * `Bash(<cmd>:*)` prefix grant, then the exact command as the narrow alternative); empty when no
88
+ * canonical mapping exists, and always empty when `healable` is false (never grant those).
89
+ * @property {string} hint - One-line remediation.
90
+ * @property {Array<'result_json'|'stderr'|'transcript'>} signals - Which CLI signals reported it.
91
+ * @property {string} [permissionMode] - The permission mode the session ran in, when the
92
+ * provider knows it (Claude: 'auto' | 'acceptEdits' | 'bypassPermissions').
93
+ * @property {boolean} [healable] - false when no grant may ever be added for these denials
94
+ * (Claude auto/bypass mode: the safety classifier or a deny rule refused the call, not a
95
+ * missing allow rule; or, in any mode, a fleet tool outside the member allowlist was refused
96
+ * -- see `cause`). Absent = a grant may heal it.
97
+ * @property {'policy_deny'} [cause] - 'policy_deny' when at least one refused call was a fleet
98
+ * tool outside the member allowlist, denied by the member's own permission config on purpose.
99
+ * Always comes with `healable: false`; never grant it.
100
+ */
101
+
102
+ /**
103
+ * Result-side shape of execute_prompt's `structuredContent` -- the single place callers
104
+ * should read the outcome of a dispatch rather than re-parsing the display text. This is
105
+ * NOT exhaustive of every `reason` value (see src/tools/execute-prompt.ts's
106
+ * ExecutePromptStructured for the full union); it documents the fields most callers key off.
107
+ * @typedef {Object} ExecutePromptStructured
108
+ * @property {boolean} [isError] - true on any failure path; absent/false on success.
109
+ * @property {string} [reason] - Machine-readable failure/status classification, e.g.
110
+ * 'busy' | 'nonzero_exit' | 'max_turns_exhausted' | 'empty_response' | 'overloaded' |
111
+ * 'usage_limit' | 'workspace_not_trusted' | 'session_not_found' | 'permission_denied' |
112
+ * 'stalled' (transcript froze past the stall threshold) |
113
+ * 'agent_never_started' (session log never appeared at its authoritative path within
114
+ * timeout_s; the process was killed) |
115
+ * 'max_total_time' (max_total_s, measured from the call including setup, ran out) |
116
+ * 'secret_delivery_unavailable' (the member's stored credentials cannot be delivered
117
+ * without a command line -- relay member or SFTP disabled; deterministic, do not retry;
118
+ * no LLM call was made) | ...
119
+ * @property {PermissionDenied} [permissionDenied] - Present when `reason === 'permission_denied'`:
120
+ * the member CLI refused tool calls (AGY headless mode auto-denies them and exits 0; Claude
121
+ * reports them in its result event's non-empty `permission_denials`). For Claude this needs the
122
+ * caller's `fail_on_permission_denial: true`; AGY fails this way either way. Pass
123
+ * `suggestedGrants` to compose_permissions `grant` to heal it; read it with
124
+ * {@link permissionDenialOf}. Any partial reply is in `response`. A healable:false Claude
125
+ * refusal (auto/bypass mode) on a complete reply is a `permissionWarning`, not this failure;
126
+ * on an incomplete one it fails here with `healable: false` and no suggested grants. Also
127
+ * present as an EXTRA field on a typed failure (max_turns_exhausted, auth, server,
128
+ * overloaded, ...) or a non-strict Claude failure whose turn carried refusals: the typed
129
+ * reason wins.
130
+ * @property {PermissionDenied} [permissionWarning] - Present on a SUCCESSFUL dispatch whose
131
+ * session refused tool calls without failing it: a healable:false refusal (never grant it),
132
+ * or any Claude refusal when `fail_on_permission_denial` was not set. A logged warning.
133
+ * @property {UsageLimitSignal} [usageLimit] - Present when `reason === 'usage_limit'`
134
+ * (apra-fleet-hzeb.2): the provider's detectUsageLimit() signal verbatim -- a 429/quota
135
+ * exhaustion that a fresh session cannot cure, so execute_prompt returns this INSTEAD of
136
+ * retrying via the stale-session or server-overloaded (529, reason: 'overloaded') retry
137
+ * paths. Read `usageLimit.resumeAt`/`resumeAtSource` to schedule a resume rather than
138
+ * re-parsing the failure text; `packages/apra-fleet-workflow` forwards this unchanged onto
139
+ * `AgentDispatchError.details.usageLimit`.
140
+ * @property {false} [dispatched] - false when nothing was sent to the member: a
141
+ * 'max_total_time' failure whose budget ran out during setup (cloud start, before the first
142
+ * attempt). No agent ran, so there is no partial work to publish. Absent on every other
143
+ * result (including a 'max_total_time' that stopped a running dispatch);
144
+ * `packages/apra-fleet-workflow` forwards it onto `AgentDispatchError.details.dispatched`.
145
+ * @property {string} [response] - The LLM's actual reply text on success.
146
+ * @property {string} [sessionId] - The session id this dispatch landed on, when known --
147
+ * present on success AND on a 'usage_limit' or typed-failure result ('max_turns_exhausted',
148
+ * 'empty_response', 'dispatch_failed', 'nonzero_exit', 'auth', 'server', 'overloaded') whenever
149
+ * the provider parsed one, so the SAME session can be resumed by explicit id later instead of
150
+ * losing context to a fresh one. The server also records it as a known session. Absent when
151
+ * the provider supplied none.
152
+ * @property {ExecutePromptUsage} [usage]
153
+ */
154
+
155
+ /**
156
+ * @typedef {Object} ExecutePromptUsage
157
+ * @property {number} input_tokens - Uncached prompt tokens.
158
+ * @property {number} output_tokens - Completion tokens.
159
+ * @property {number} cache_read_input_tokens - Prompt tokens served from the provider's
160
+ * prompt cache; billed, and NOT included in input_tokens (0 when the provider reports none).
161
+ * @property {number} cache_creation_input_tokens - Prompt tokens written to the provider's
162
+ * prompt cache; billed, and NOT included in input_tokens (0 when the provider reports none).
163
+ * @property {number} total_tokens - input_tokens + output_tokens only (the context-window
164
+ * figure context admission reads); it deliberately EXCLUDES the cache counts, so a cost
165
+ * figure must price all four counts rather than total_tokens.
166
+ * @property {number} [cost_usd] - USD this dispatch cost as the provider CLI reported it
167
+ * (Claude: the per-dispatch share of the cumulative total_cost_usd). Use it as-is when
168
+ * present; price the token counts only when it is absent.
169
+ */
170
+
171
+ /**
172
+ * @typedef {Object} ModelPrice
173
+ * @property {string} model - Concrete model the tier resolves to.
174
+ * @property {number} promptPrice - $/1M input_tokens.
175
+ * @property {number} completionPrice - $/1M output_tokens.
176
+ * @property {number} cacheReadPrice - $/1M cache_read_input_tokens (the model's own cache-hit rate).
177
+ * @property {number} cacheWritePrice - $/1M cache_creation_input_tokens (Claude: the 1-hour
178
+ * cache-write rate, 2x input, which the Claude Code CLI uses).
179
+ */
180
+
181
+ /**
182
+ * @typedef {Object} MemberModelPricingResult
183
+ * @property {string} member_id
184
+ * @property {string} member_name
185
+ * @property {string} llm_provider
186
+ * @property {{cheap: ModelPrice|null, standard: ModelPrice|null, premium: ModelPrice|null}} pricing
187
+ * - null for a tier whose resolved model has no known price.
188
+ */
189
+
41
190
  /**
42
191
  * @typedef {Object} ExecuteCommandOptions
43
- * @property {string} command - The shell command to execute
192
+ * @property {string} command - The shell command to execute. Multi-line commands and heredocs
193
+ * are supported. On POSIX members (linux, macos, windows Git Bash) the server passes it to its
194
+ * wrapper as data (`eval '<command>'`), so the work-folder `cd` covers the whole command and a
195
+ * syntax error in it surfaces on stderr as `eval: line N: ...` (not `-c: line N: ...`).
44
196
  * @property {boolean} [long_running] - Run as background task. Supported on linux and windows
45
197
  * members. Windows launches the task detached via `Invoke-CimMethod Win32_Process.Create`
46
198
  * (WMI provider host / session 0), independent of the SSH session's job object, since a plain
@@ -61,6 +213,50 @@
61
213
  * cannot cancel a job already accepted by the remote fleet-server (see client.mjs).
62
214
  */
63
215
 
216
+ /**
217
+ * @typedef {Object} SessionStatsOptions
218
+ * @property {string} [member_id] - Member uuid to read; omit on a member session (the calling member is used), required on a non-member session
219
+ */
220
+
221
+ /**
222
+ * @typedef {Object} SessionStatsResult
223
+ * @property {string} member_id - Member uuid the counts belong to
224
+ * @property {string} since - ISO time counting started (server start); a change between two snapshots means the server restarted
225
+ * @property {number} kb - kb_* calls counted
226
+ * @property {number} code - code_* calls counted
227
+ * @property {number} total - kb + code
228
+ * @property {Object<string, number>} tools - Per-tool counts (tools called at least once)
229
+ */
230
+
231
+ /**
232
+ * Result-side shape of execute_command's `structuredContent`. Mirrors
233
+ * src/tools/execute-command.ts's ExecuteCommandStructured. A command that ran
234
+ * reports its real `exitCode` (isError absent). A command that never produced an
235
+ * exit code -- the exec timed out, the transport failed, a cloud member could
236
+ * not be started, or the pre-dispatch check failed -- reports `isError: true`,
237
+ * a `reason`, and `exitCode: -1` (never a fake 0). Read it with
238
+ * {@link commandFailureOf}.
239
+ * @typedef {Object} ExecuteCommandStructured
240
+ * @property {number} exitCode - Exit code of the command; -1 when it never produced one.
241
+ * @property {string} stdout - Command stdout (credential values redacted).
242
+ * @property {string} stderr - Command stderr, or the failure detail when isError is true.
243
+ * @property {boolean} [isError] - true when the command did not run to an exit code.
244
+ * @property {string} [reason] - Present with isError: 'timeout' (inactivity timeout) |
245
+ * 'max_total_time' (hard total-time cap) | 'transport_error' (connection/channel failure) |
246
+ * 'cloud_start_failed' | 'preflight_offline' | 'preflight_auth_expired' |
247
+ * 'preflight_auth_missing'.
248
+ * @property {'secret_delivery_unavailable'} [storedEnvNotDelivered] - Present when the
249
+ * command ran WITHOUT the member's stored credential env vars because no
250
+ * owner-only file channel exists to deliver them (SFTP disabled, relay member).
251
+ */
252
+
253
+ /**
254
+ * @typedef {Object} ExecuteCommandFailure
255
+ * @property {string} reason - The structured reason, or 'unflagged_failure' for a failure
256
+ * recognized only from the text of an older server that sent no structuredContent.
257
+ * @property {string} message - Human-readable failure text.
258
+ */
259
+
64
260
  /**
65
261
  * @typedef {Object} ListMembersOptions
66
262
  * @property {"compact" | "json"} [format] - Output format
@@ -70,6 +266,7 @@
70
266
  /**
71
267
  * @typedef {Object} FleetStatusOptions
72
268
  * @property {"compact" | "json"} [format] - Output format
269
+ * @property {string} [repo_path] - Absolute path to a repo checkout; adds that repo's code-intelligence index health and its KB scope's bible drift. The server's own cwd is never used. KB health itself always covers every project KB scope plus the global KB.
73
270
  */
74
271
 
75
272
  /**
@@ -92,7 +289,7 @@
92
289
  /**
93
290
  * @typedef {Object} RegisterMemberOptions
94
291
  * @property {string} friendly_name - Human-friendly name for this member (required)
95
- * @property {string} work_folder - Working directory on the target machine (required). For remote members, must be a fully-qualified/absolute path -- "~" and relative paths are rejected.
292
+ * @property {string} work_folder - Working directory on the target machine (required). For remote members, must be a fully-qualified/absolute path -- "~" and relative paths are rejected. A folder may hold at most one LLM member and one LLM-less (llm_provider none) member.
96
293
  * @property {"local" | "remote"} [member_type] - Member type (default: "remote")
97
294
  * @property {string} [host] - IP address or hostname of the remote machine
98
295
  * @property {string} [username] - SSH username
@@ -102,6 +299,7 @@
102
299
  * @property {string} [key_path] - Path to SSH private key
103
300
  * @property {"read" | "push" | "admin" | "issues" | "full"} [git_access] - Git access level for this member
104
301
  * @property {string[]} [git_repos] - Git repositories this member can access (e.g. ["Apra-Labs/ApraPipes"])
302
+ * @property {"github" | "bitbucket" | "azure-devops" | "none"} [vcs_provider] - VCS provider this member pushes to and opens pull requests against. Omit to auto-detect it from the member's git "origin" remote; "none" declares the member deliberately has no VCS provider.
105
303
  * @property {"aws"} [cloud_provider] - Cloud provider. When set, cloud_instance_id and key_path are required.
106
304
  * @property {string} [cloud_instance_id] - EC2 instance ID (e.g. "i-0abc123def456789a"). Required when cloud_provider is set.
107
305
  * @property {string} [cloud_region] - AWS region (default: "us-east-1")
@@ -109,15 +307,17 @@
109
307
  * @property {number} [cloud_idle_timeout_min] - Minutes of inactivity before auto-stop (default: 30)
110
308
  * @property {string} [cloud_activity_command] - Custom shell command for workload detection. Must output "busy" or "idle" on stdout.
111
309
  * @property {"claude" | "codex" | "copilot" | "agy" | "opencode" | "none"} [llm_provider] - LLM provider for this member (default: "claude")
112
- * @property {"gpt-oss-120b" | "gpt-120" | "gemini-3.5-flash-lite" | "haiku" | "gpt-5.4-mini"} [model_cheap] - Custom cheap model choice from a curated list
113
- * @property {"gemini-3.5-flash" | "gpt-oss-120b" | "gpt-120" | "sonnet" | "gpt-5.4"} [model_standard] - Custom standard model choice from a curated list
114
- * @property {"sonnet" | "opus" | "gpt-oss-120b"} [model_premium] - Custom premium model choice from a curated list
310
+ * @property {"gpt-oss-120b" | "gpt-120" | "gemini-3.8-flash-low" | "haiku" | "gpt-5.4-mini"} [model_cheap] - Custom cheap model choice from a curated list
311
+ * @property {"gemini-3.8-flash-high" | "gemini-3.8-flash-medium" | "gemini-3.1-pro-low" | "gpt-oss-120b" | "gpt-120" | "sonnet" | "gpt-5.4"} [model_standard] - Custom standard model choice from a curated list
312
+ * @property {"sonnet" | "opus" | "gemini-3.1-pro-high" | "claude-opus-4-6-thinking" | "gpt-oss-120b"} [model_premium] - Custom premium model choice from a curated list
115
313
  * @property {{cheap?: string, standard?: string, premium?: string}} [model_tiers] - Per-member model tier map. A single model fills all tiers.
116
314
  * @property {"codebase-memory" | "gitnexus" | "none"} [code_intel_provider] - Code-intelligence provider for this member (default: fleet-wide config)
117
315
  * @property {string} [category] - Optional group label
118
316
  * @property {string[]} [tags] - Optional list of free-form labels
119
317
  * @property {"false" | "auto" | "dangerous"} [unattended] - Permission mode for unattended execution
120
- * @property {boolean} [unreservable] - Mark this member as never exclusively reservable, so it can be shared by more than one sprint at once (e.g. fleet-sprint's shared "orchestrator" role)
318
+ * ("auto" on a Claude model without auto-mode support, such as Haiku, runs acceptEdits)
319
+ * @property {boolean} [unreservable] - Mark this member as never exclusively reservable, so it can be shared by more than one sprint at once (e.g. fleet-sprint's shared "backlog" role)
320
+ * @property {"auto" | "skip" | "replace-full"} [fleet_install] - Whether registration installs/updates apra-fleet on the member, writes its per-folder apra-fleet MCP entry and verifies it (default "auto"; local members only get the MEMBER-session probe; a full install without the member-install marker is never touched). "replace-full": also explicitly opts in to replacing such a full install with a member install (backup of data and fleet.key, uninstall, member install, self-register). "skip" performs no install and reports the probe result only. Registration succeeds either way; the result reports fleetMcp, plus a WARNING (consequence, exact reason, OS-correct manual install steps; also fleetMcp.manualInstall) when a requested install/upgrade did not happen.
121
321
  * @property {"gitbash" | "pwsh7" | "powershell5"} [shell] - Override the probed Windows shell for this member. Windows members only -- ignored for non-windows members.
122
322
  */
123
323
 
@@ -125,14 +325,15 @@
125
325
  * @typedef {Object} UpdateMemberOptions
126
326
  * @property {string} [member_id] - UUID of the member
127
327
  * @property {string} [member_name] - Friendly name of the member
328
+ * @property {"auto" | "skip" | "replace-full"} [fleet_install] - "auto": for a remote member, install/upgrade the member's own apra-fleet when missing or older (build-aware), self-register, write its per-folder apra-fleet MCP entry and verify, even when nothing else changed; an install/upgrade that ran (or an install that only now became available) also adds the member apra-fleet tool rules to a claude member's permission allow-list through compose_permissions grant mode, keeping its role and grants (a NOTICE says so; a failure is a WARNING); a full install without the member-install marker is never touched. "replace-full": "auto" plus an explicit opt-in to replace such a full install with a member install (backup of data and fleet.key, uninstall, member install, self-register). "skip": never install. Omit: install only on a provider change. A requested install/upgrade that cannot happen never fails the update: the result adds a WARNING (consequence, exact reason, OS-correct manual install steps; also fleetMcp.manualInstall). Unknown input keys are rejected by the server.
128
329
  * @property {string} [friendly_name] - New friendly name
129
- * @property {string} [work_folder] - New working directory. For non-local (remote/relay) members, must be a fully-qualified/absolute path -- "~" and relative paths are rejected.
330
+ * @property {string} [work_folder] - New working directory. For non-local (remote/relay) members, must be a fully-qualified/absolute path -- "~" and relative paths are rejected. A folder may hold at most one LLM member and one LLM-less (llm_provider none) member.
130
331
  * @property {string} [host] - New host
131
332
  * @property {string} [username] - New SSH username
132
333
  * @property {number} [port] - New SSH port
133
334
  * @property {"password" | "key"} [auth_type] - New auth method
134
335
  * @property {string} [password] - New SSH password
135
- * @property {boolean} [rotate_password] - Trigger secure out-of-band password re-entry for a member already using password auth. Ignored if auth_type is not password.
336
+ * @property {boolean} [rotate_password] - Trigger out-of-band password re-entry for a member already using password auth. Ignored if auth_type is not password.
136
337
  * @property {string} [key_path] - New SSH private key path
137
338
  * @property {"read" | "push" | "admin" | "issues" | "full"} [git_access] - Git access level for this member
138
339
  * @property {string[]} [git_repos] - Git repositories this member can access (e.g. ["Apra-Labs/ApraPipes"])
@@ -142,16 +343,46 @@
142
343
  * @property {number} [cloud_idle_timeout_min] - Minutes of inactivity before auto-stop
143
344
  * @property {string} [cloud_activity_command] - Custom shell command for workload detection. Must output "busy" or "idle". Pass empty string to clear.
144
345
  * @property {"claude" | "codex" | "copilot" | "agy" | "opencode"} [llm_provider] - Change the LLM provider
145
- * @property {"gpt-oss-120b" | "gpt-120" | "gemini-3.5-flash-lite" | "haiku" | "gpt-5.4-mini"} [model_cheap] - Change custom cheap model
146
- * @property {"gemini-3.5-flash" | "gpt-oss-120b" | "gpt-120" | "sonnet" | "gpt-5.4"} [model_standard] - Change custom standard model
147
- * @property {"sonnet" | "opus" | "gpt-oss-120b"} [model_premium] - Change custom premium model
346
+ * @property {"gpt-oss-120b" | "gpt-120" | "gemini-3.8-flash-low" | "haiku" | "gpt-5.4-mini"} [model_cheap] - Change custom cheap model
347
+ * @property {"gemini-3.8-flash-high" | "gemini-3.8-flash-medium" | "gemini-3.1-pro-low" | "gpt-oss-120b" | "gpt-120" | "sonnet" | "gpt-5.4"} [model_standard] - Change custom standard model
348
+ * @property {"sonnet" | "opus" | "gemini-3.1-pro-high" | "claude-opus-4-6-thinking" | "gpt-oss-120b"} [model_premium] - Change custom premium model
148
349
  * @property {{cheap?: string, standard?: string, premium?: string}} [model_tiers] - Per-member model tier map with free-form model IDs. A single model fills all tiers.
149
350
  * @property {"codebase-memory" | "gitnexus" | "none"} [code_intel_provider] - Change the code-intelligence provider for this member
150
351
  * @property {string} [category] - Group label
151
352
  * @property {string[]} [tags] - Free-form labels
152
- * @property {"false" | "auto" | "dangerous"} [unattended] - Permission mode
353
+ * @property {"false" | "auto" | "dangerous"} [unattended] - Permission mode ("auto" on a
354
+ * Claude model without auto-mode support, such as Haiku, runs acceptEdits)
153
355
  * @property {boolean} [unreservable] - Mark/unmark this member as shared/never exclusively reservable
154
356
  * @property {"gitbash" | "pwsh7" | "powershell5"} [shell] - Override the probed Windows shell for this member. Windows members only -- ignored for non-windows members.
357
+ * @property {"github" | "bitbucket" | "azure-devops" | "none"} [vcs_provider] - Directly set (override) this member's VCS provider. An explicit operator value, never auto-detected -- use this to correct a wrong auto-detect from register_member, or to set the provider without provisioning credentials. "none" clears it.
358
+ */
359
+
360
+ /**
361
+ * A member's own apra-fleet MCP observation (src/types.ts FleetMcpStatus).
362
+ * @typedef {Object} FleetMcpStatus
363
+ * @property {"available" | "unavailable"} state
364
+ * @property {string} [reason] - Machine-readable cause when unavailable (e.g. install-too-old, E-FOLDER-TAKEN, mcp-entry-missing, role-agents-hide-member-tools, no-per-project-mcp)
365
+ * @property {string} [version] - apra-fleet version the member's own install reports
366
+ * @property {string} checkedAt - ISO 8601 time of the probe
367
+ * @property {string} [detail] - Human-readable diagnostic
368
+ * @property {boolean} [unverified] - KB/code tools could not be verified (e.g. agy)
369
+ * @property {string} [fleetInstalledAt] - ISO 8601 time this fleet's own install run last succeeded on the member; carried across later probes; absent when the fleet never installed it (a refusal or observation-only probe never sets it)
370
+ * @property {{reason: string, detail?: string}} [installFailure] - A requested apra-fleet upgrade that failed before the member was touched while the older install stayed in use; present on available and unavailable statuses, also named in detail
371
+ * @property {{state: "missing" | "broken", detail: string, fix: string}} [beads] - Present only when the beads CLI (bd) is not usable on a remote member (not on its PATH nor in <home>/.apra-fleet/bin); independent of state; absent when bd works or could not be probed
372
+ * @property {number} [port] - Remote members: the port of the member's own apra-fleet install, resolved from its member-install marker; the member MCP URL (per-folder entry and per-session config) uses it
373
+ * @property {"marker" | "default"} [portSource] - Where port came from: the member-install marker, or the built-in default because the install recorded no port (detail says so)
374
+ * @property {{previousVersion: string, removed: string[], backupPath: string}} [replacedFullInstall] - Set by the probe that replaced a full install with a member install (fleet_install "replace-full"): replaced version, what was removed or moved, and the timestamped backup directory on the member
375
+ * @property {string} [manualInstall] - Set when a requested apra-fleet install/upgrade on the member did not happen (any install reason, e.g. no-matching-release, checksum-unavailable, download-failed): OS-correct manual steps to install the orchestrator build on the member by hand (anonymous release download URL, SHA-256 check, member-mode install, then update_member); register_member/update_member print them in a WARNING and still succeed
376
+ * @property {{tag: string, wantedBuild: string, why: string}} [sameCoreFallback] - Set when no release carries the orchestrator's exact build and the member had no apra-fleet or an older core, so the signed stable release of the same core (tag) was installed instead of wantedBuild; register_member/update_member print a NOTICE
377
+ */
378
+
379
+ /**
380
+ * Code intelligence availability reported by member_detail.
381
+ * @typedef {Object} CodeIntelStatus
382
+ * @property {string|null} provider - 'gitnexus' | 'codebase-memory' | 'none' (null when it could not be resolved)
383
+ * @property {boolean} available
384
+ * @property {string} [cause] - Why it is unavailable; absent when available
385
+ * @property {string} [remedy] - What to do about the cause; absent when available
155
386
  */
156
387
 
157
388
  /**
@@ -171,9 +402,29 @@
171
402
  * @property {string} folder - Working directory on the target machine
172
403
  * @property {string} [repo_remote_url] - Origin URL of the git repo in `folder`, when known
173
404
  * @property {string} [vcsProvider] - VCS provider configured for this member
405
+ * @property {"read" | "push" | "push+pr" | "admin" | "issues" | "full"} [gitAccess] - Git access level
406
+ * this member's VCS credentials are minted at (register_member/update_member's git_access). Absent
407
+ * when the member was registered without an explicit level. Consumers that need to know whether a
408
+ * minted token carries a given permission (e.g. GitHub's 'workflows', required to push any
409
+ * .github/workflows/** change) must read THIS, not their own provisioning default -- the two differ
410
+ * exactly for the members at risk.
411
+ * @property {string[]} [permissionConfigPaths] - The member's provider permission config file(s)
412
+ * that compose_permissions writes (work-folder-relative, or home-anchored "~/..."), e.g.
413
+ * ['.claude/settings.local.json'] for Claude. [] when the provider cannot name them yet (agy before
414
+ * its project is provisioned). Reported even for an offline member. Absent on older servers.
174
415
  * @property {Object} connectivity - Connectivity check result (status, latencyMs, auth, keyPath, or error)
175
416
  * @property {boolean} [offline] - Set when the member could not be reached
176
417
  * @property {string} llmProvider - LLM provider for this member (default: "claude")
418
+ * @property {string|null} [agyProjectId] - agy members only: id of the member's own agy project
419
+ * (~/.gemini/config/projects/<id>.json), passed as `--project <id>` on every dispatch; null until
420
+ * provisioned (compose_permissions/execute_prompt provision it on first use)
421
+ * @property {FleetMcpStatus|null} fleetMcp - Last recorded state of the member's own apra-fleet MCP
422
+ * server (null when never probed). Recoverable: `member_detail { refresh: true }` re-probes and records.
423
+ * @property {string|null} [fleetMcpFix] - One-line operator fix for `fleetMcp` when the member's KB/code tools are
424
+ * not usable (state "unavailable" or `unverified`); null when available and verified
425
+ * @property {CodeIntelStatus|null} [codeIntel] - Whether code intelligence (code_* tools) can run for this member,
426
+ * with the cause and remedy when it cannot (e.g. npx/node missing from the apra-fleet service PATH). null for
427
+ * remote members: their code tools run on the member host, not on this server.
177
428
  * @property {Object} [llm_cli] - LLM CLI info: { version, auth }
178
429
  * @property {Object|string} [tokenUsage] - Cumulative token usage, or "compute only" for llmProvider "none"
179
430
  * @property {Object} [session] - Session info: { id, lastActivity, lastLlmActivityAt, status, idleSecs }
@@ -189,13 +440,155 @@
189
440
  * @property {boolean} [force] - Remove even if the member is currently busy
190
441
  */
191
442
 
443
+ /**
444
+ * @typedef {Object} MemberReservationOptions
445
+ * @property {string} [member_id] - UUID of the member
446
+ * @property {string} [member_name] - Friendly name of the member
447
+ * @property {"reserve" | "release" | "force_release"} action - "reserve" claims the member for
448
+ * sprint_id (fails if already reserved by someone else); "release" clears it only if sprint_id
449
+ * matches the current holder; "force_release" clears it regardless of owner.
450
+ * @property {string} [sprint_id] - Sprint/session id claiming or releasing the reservation.
451
+ * Required for "reserve" and "release", ignored for "force_release".
452
+ */
453
+
454
+ /**
455
+ * @typedef {Object} MemberReservationStructured
456
+ * @property {"reserved" | "reservation_refreshed" | "released" | "force_released" |
457
+ * "already_reserved_by_other" | "not_reserved" | "unreservable" | "invalid_input" |
458
+ * "member_not_found" | "failed"} outcome - Machine-readable outcome discriminator. Branch on
459
+ * this field; never string-match the human-readable summary text.
460
+ * @property {boolean} ok - True when the requested operation took effect (or was already true).
461
+ * @property {"reserve" | "release" | "force_release"} action - The action that was requested.
462
+ * @property {string|null} memberId - Registry id of the resolved member, null when none resolved.
463
+ * @property {string|null} memberName - Friendly name of the resolved member, null when none resolved.
464
+ * @property {string|null} sprintId - The sprint id supplied by the caller, null when none.
465
+ * @property {string|null} ownerSprintId - The sprint that held the reservation when the call
466
+ * arrived, null when the member was unreserved. On "already_reserved_by_other" this is the
467
+ * blocking owner.
468
+ *
469
+ * Mirrors src/tools/member-reservation.ts's MemberReservationStructured field-for-field
470
+ * (apra-fleet-3swo.7.1). The tool still returns the same human-readable summary in
471
+ * `content[0].text`; this shape is the machine-readable half of the same response.
472
+ */
473
+
192
474
  /**
193
475
  * @typedef {Object} ProvisionLlmAuthOptions
194
476
  * @property {string} [member_id] - UUID of the member
195
477
  * @property {string} [member_name] - Friendly name of the member
196
- * @property {string} [api_key] - AI provider API key. If omitted, the local OAuth
197
- * session is copied to the member instead. Supports {{secure.NAME}} token --
198
- * resolved from the credential store server-side before use.
478
+ * @property {string} [api_key] - AI provider API key or Claude Code OAuth token
479
+ * (sk-ant-oat..., from `claude setup-token`; routed to CLAUDE_CODE_OAUTH_TOKEN). If
480
+ * omitted, a credential already stored for the member is re-deployed, else the local
481
+ * OAuth session is copied to the member. Supports {{secret.NAME}} token -- resolved
482
+ * from the credential store server-side before use.
483
+ * @property {boolean} [force_oauth_copy] - Only without api_key: copy the local OAuth
484
+ * session even when the member has a stored env credential, and clear that credential
485
+ * (ANTHROPIC_API_KEY / CLAUDE_CODE_OAUTH_TOKEN) so the copied login applies.
486
+ * @property {boolean} [clear_stored_credentials] - Remove ALL credential env vars stored for
487
+ * the member in the fleet registry and do nothing else (registry only; works for relay,
488
+ * offline and local members). The recovery for reason secret_delivery_unavailable.
489
+ * Cannot be combined with api_key or force_oauth_copy.
490
+ */
491
+
492
+ /**
493
+ * @typedef {Object} VcsCredentialExecOptions
494
+ * @property {string} [member_id] - UUID of the member
495
+ * @property {string} [member_name] - Friendly name of the member
496
+ * @property {string} command - The credential-requiring command to run on the member. MUST
497
+ * contain at least one of two placeholders where the credential belongs (both may appear in
498
+ * the same command): {{vcs_token}}, referenced BARE (never inside your own quotes) -- the
499
+ * server substitutes it with the value ALREADY escaped AND quoted for that member's shell, so
500
+ * wrapping it in your own quotes double-escapes it and surfaces as a false 401; or
501
+ * {{vcs_token_inline}}, referenced INSIDE your own single quotes -- the server substitutes it
502
+ * with the value escaped for the interior of a single-quoted string, with no quotes of its
503
+ * own, for interpolating the token into a larger already-quoted value (e.g. an Authorization
504
+ * header) where a bare, self-quoting substitution cannot compose.
505
+ * @property {string} [label] - Credential label provision_vcs_auth deployed the helper under
506
+ * (it defaults to the provider name there, e.g. "github" or "azure-devops"). Omit for the
507
+ * unlabelled helper.
508
+ * @property {number} [timeout_s] - Inactivity timeout in seconds for the command (default: 120).
509
+ * On expiry the command's remote process tree is killed and the result is reason
510
+ * 'dispatch_failed' with a "Command timed out" message.
511
+ */
512
+
513
+ /**
514
+ * @typedef {Object} VcsCredentialExecStructured
515
+ * @property {boolean} ok - True when the credential-requiring command was dispatched. Read
516
+ * exitCode for the command's own outcome.
517
+ * @property {"ok" | "member_not_found" | "placeholder_missing" | "unsupported_member_os" |
518
+ * "credential_read_failed" | "credential_empty" | "dispatch_failed"} reason - Machine-readable
519
+ * outcome code. Branch on this, never on the text.
520
+ * @property {number|null} exitCode - Exit code of the dispatched command, null if it never ran.
521
+ * @property {string} stdout - Command stdout, with every occurrence of the credential redacted.
522
+ * @property {string} stderr - Command stderr, with every occurrence of the credential redacted.
523
+ * @property {number} tokenRedactions - How many times the credential had to be redacted out of
524
+ * stdout+stderr. Normally 0; nonzero means the command echoed its own credential back.
525
+ * @property {string|null} credentialLabel - Credential label used, or null for the unlabelled helper.
526
+ * @property {string|null} memberId - Registry id of the resolved member, or null.
527
+ * @property {string|null} memberName - Friendly name of the resolved member, or null.
528
+ *
529
+ * Mirrors src/tools/vcs-credential-exec.ts's VcsCredentialExecStructured field-for-field
530
+ * (apra-fleet-3swo.7.3). The plaintext credential appears in NO field of this payload.
531
+ */
532
+
533
+ /**
534
+ * @typedef {Object} ProvisionAuthStructured
535
+ * @property {boolean} ok - True when credentials were deployed (verified or not).
536
+ * @property {"ok" | "deployed_unverified" | "deployed_with_errors" | "skipped_local_member" |
537
+ * "member_not_found" | "member_offline" | "secret_variable_not_found" |
538
+ * "secret_variable_denied" | "secret_variable_expired" | "oauth_not_supported" |
539
+ * "oauth_token_expired_no_refresh" | "oauth_credential_file_missing" |
540
+ * "oauth_credential_write_failed" | "oauth_settings_merge_failed" | "oauth_copy_failed" |
541
+ * "oob_cancelled" | "secret_delivery_unavailable" | "stored_credentials_cleared" |
542
+ * "invalid_arguments"} reason - Machine-readable outcome code.
543
+ * Branch on this, never on the text. secret_delivery_unavailable: the member has no channel
544
+ * that delivers the key without a command line (relay member, SFTP unavailable).
545
+ * stored_credentials_cleared: clear_stored_credentials removed the stored env vars (ok=true).
546
+ * @property {string|null} provider - The resolved ProviderAdapter's own name (claude, codex,
547
+ * copilot, agy, opencode or none -- there is no gemini adapter), null when unresolved.
548
+ * @property {string|null} credentialLabel - What was deployed, never the secret: the env var
549
+ * name for the API-key flow (e.g. ANTHROPIC_API_KEY) or "oauth" for the file-copy flow.
550
+ * @property {string|null} expiresAt - Credential expiry as an ISO timestamp, or null meaning
551
+ * "no expiry tracked -> OK".
552
+ * @property {boolean} verified - True when the post-deploy auth check confirmed working auth.
553
+ * @property {string|null} memberId - Registry id of the resolved member, or null.
554
+ * @property {string|null} memberName - Friendly name of the resolved member, or null.
555
+ *
556
+ * Mirrors src/tools/provision-auth.ts's ProvisionAuthStructured field-for-field
557
+ * (apra-fleet-3swo.7.2). Carries no plaintext credential of any kind.
558
+ */
559
+
560
+ /**
561
+ * @typedef {Object} ProvisionVcsAuthStructured
562
+ * @property {boolean} ok - True when the credential was actually deployed onto the member.
563
+ * @property {"ok" | "deployed_unverified" | "deployed_verification_skipped" |
564
+ * "member_not_found" | "member_offline" | "secret_variable_not_found" |
565
+ * "secret_variable_denied" | "secret_variable_expired" | "oob_cancelled" |
566
+ * "credential_assembly_unsupported" | "credential_assembly_failed" | "deploy_threw" |
567
+ * "deploy_failed"} reason - Machine-readable outcome code. Branch on this, never on the text.
568
+ * @property {string} provider - The VCS provider requested.
569
+ * @property {string} credentialLabel - Credential label the helper was deployed under
570
+ * (defaults to the provider name).
571
+ * @property {string|null} scopeUrl - Git credential scope URL the helper was registered for.
572
+ * @property {string|null} expiresAt - Token expiry as an ISO timestamp, or null meaning "no
573
+ * expiry tracked -> OK" (the reading checkVcsTokenExpiry applies server-side). Read this
574
+ * instead of scraping an "expiresAt:" line out of the summary text.
575
+ * @property {boolean} verified - True only when testConnectivity() actually ran AND succeeded.
576
+ * @property {boolean} verificationSkipped - True when the connectivity check was not performed.
577
+ * @property {Record<string, string>|null} metadata - The provider's own deploy metadata,
578
+ * filtered through a server-side key allowlist before it reaches this field (an unrecognised
579
+ * key is dropped, never passed through). Providers additionally mask the token value here to
580
+ * its first four characters plus asterisks, so this never carries the plaintext token.
581
+ * @property {string|null} expiryWarning - Near-expiry warning text when one applies, else null.
582
+ * @property {string|null} memberId - Registry id of the resolved member, or null.
583
+ * @property {string|null} memberName - Friendly name of the resolved member, or null.
584
+ * @property {string|null} message - Human-readable cause of a non-ok outcome (e.g. "No repos
585
+ * specified and none on agent config."), or null when ok is true. Previously this text only
586
+ * reached the caller inside the tool's `text` content, so a caller reading only
587
+ * structuredContent saw nothing but the bare `reason` code. Read this instead of parsing the
588
+ * `[FAIL] ...` prefix out of `text`.
589
+ *
590
+ * Mirrors src/tools/provision-vcs-auth.ts's ProvisionVcsAuthStructured field-for-field
591
+ * (apra-fleet-3swo.7.2).
199
592
  */
200
593
 
201
594
  /**
@@ -205,26 +598,29 @@
205
598
  * @property {"github" | "bitbucket" | "azure-devops"} provider - VCS provider to configure
206
599
  * @property {string} [label] - Credential label (slug, e.g. "work-github"). Defaults to provider name.
207
600
  * @property {string} [scope_url] - Git credential scope URL (e.g. "https://github.com/my-org").
208
- * Defaults to "https://<host>".
601
+ * Defaults to "https://<host>". For an Azure DevOps repo on the legacy host, pass
602
+ * "https://ORG.visualstudio.com" so the PAT is bound to the host the member pushes to.
209
603
  * @property {"github-app" | "pat"} [github_mode] - GitHub auth mode: github-app (mint via
210
604
  * configured app) or pat (personal access token)
211
605
  * @property {string} [token] - Personal access token (GitHub PAT or Azure DevOps PAT).
212
- * Supports {{secure.NAME}} token -- resolved from the credential store server-side before use.
606
+ * Supports {{secret.NAME}} token -- resolved from the credential store server-side before use.
213
607
  * @property {"read" | "push" | "push+pr" | "admin" | "issues" | "full"} [git_access] - GitHub App access
214
608
  * level override
215
609
  * @property {string[]} [repos] - GitHub App repository list override
216
610
  * @property {string} [email] - Bitbucket account email
217
- * @property {string} [api_token] - Bitbucket API token. Supports {{secure.NAME}} token --
611
+ * @property {string} [api_token] - Bitbucket API token. Supports {{secret.NAME}} token --
218
612
  * resolved from the credential store server-side before use.
219
613
  * @property {string} [workspace] - Bitbucket workspace slug
220
- * @property {string} [org_url] - Azure DevOps organization URL (e.g. https://dev.azure.com/myorg)
221
- * @property {string} [pat] - Azure DevOps personal access token. Supports {{secure.NAME}}
614
+ * @property {string} [org_url] - Azure DevOps organization URL (e.g. https://dev.azure.com/myorg,
615
+ * or the legacy https://myorg.visualstudio.com)
616
+ * @property {string} [pat] - Azure DevOps personal access token. Supports {{secret.NAME}}
222
617
  * token -- resolved from the credential store server-side before use.
223
618
  * @property {string} [pat_expires_at] - ISO 8601 date/time the Azure DevOps PAT expires, as
224
619
  * chosen when creating the token. Propagated to the member registry so provisioning can
225
620
  * warn when the PAT is nearing expiry. Must be parseable by Date.parse -- the server
226
621
  * REJECTS an unparseable value rather than storing it, because a NaN expiry silences the
227
- * warning and makes the credential-cleanup timer fall back to its 55-minute default.
622
+ * warning entirely (the credential-cleanup timer skips auto-revoke scheduling when no
623
+ * real expiry is known, rather than falling back to any default TTL).
228
624
  */
229
625
 
230
626
  /**
@@ -268,6 +664,86 @@
268
664
  * shell-chaining metacharacter (| ; && backtick $() are rejected outright,
269
665
  * for every caller.
270
666
  * @property {string} [grant_reason] - Reason for the grant (stored in ledger)
667
+ * @property {boolean} [dry_run] - Compose only: return the allow list the role/tags
668
+ * (plus detected stacks, plus the ledger when project_folder is given) would deliver, as
669
+ * JSON text `{"dry_run":true,"mode","stacks","allow"}`, without writing anything to the
670
+ * member. Ignored with `grant`. Use it to check whether a grant is within the member's
671
+ * composed policy.
672
+ */
673
+
674
+ /**
675
+ * @typedef {Object} KbExportOptions
676
+ * No scope key: the KB is the calling session's own. The removed repo_path, repo and
677
+ * repo_remote_url are refused with E-SCOPE-KEY-REMOVED (client-side and by the server).
678
+ * @property {"project" | "global"} [scope] - project (default): export the project KB to
679
+ * .fleet/kb-canonical.json. global: export the GLOBAL KB to .fleet/kb-canonical-global.json.
680
+ * @property {string} [baseBranch] - The target base branch (the branch the entries merge
681
+ * into), written to provenance.branch. Omitted: the export folder HEAD branch.
682
+ * @property {string} [baseCommit] - The base commit the entries were verified against,
683
+ * written to provenance.commit. Omitted: the export folder HEAD commit.
684
+ */
685
+
686
+ /**
687
+ * @typedef {Object} KbBibleCommitOptions
688
+ * @property {string[]} ids - Ids of the entries confirmed this round. Ids that are not
689
+ * live CONFIRMED entries are skipped (reason not_confirmed_or_unknown); a CONFIRMED id
690
+ * whose cited files at the repo's HEAD commit no longer match its recorded basis (the
691
+ * same rule kb_export applies; uncommitted edits never change the verdict) is skipped
692
+ * with reason basis_mismatch, and a CONFIRMED id citing no source file is skipped with
693
+ * reason no_source_files. Skips are reported in the result's skipped list.
694
+ * Independently of ids, bible entries the KB holds as superseded or invalidated are
695
+ * removed and reported in the result's removed list, and existing bible entries with
696
+ * no source_file_hashes gain the KB's stored basis for the same id when it passes the
697
+ * same rule (counted in the result's backfilled); an empty list with nothing to remove
698
+ * or backfill makes no commit.
699
+ * @property {string} baseBranch - The target base branch, written to provenance.branch.
700
+ * @property {string} baseCommit - The base commit the entries were verified against,
701
+ * written to provenance.commit.
702
+ */
703
+
704
+ /**
705
+ * One entry of the bible file (.fleet/kb-canonical.json) kb_export and
706
+ * kb_bible_commit write and kb_import reads -- bible format v3, described by
707
+ * memory-contract/v1/bible/kb-canonical.schema.json. The file itself is
708
+ * {version: 3, provenance: {commit, branch, entry_count}, entries: KbBibleEntry[]};
709
+ * readers also accept v2 (same envelope, no hashes) and v1 (a bare entry array).
710
+ * @typedef {Object} KbBibleEntry
711
+ * @property {string} id - Entry id (unique within the bible; writers refuse a duplicate id).
712
+ * @property {string} type - Content type (knowledge, learning, runbook, context-cache, user-directive).
713
+ * @property {string} title - Entry title.
714
+ * @property {string} summary - Entry summary.
715
+ * @property {string[]} symbols - Symbols the entry is about.
716
+ * @property {string[]} source_files - Repo-relative files the entry cites.
717
+ * @property {string} confidence - CONFIRMED, INFERRED or UNVERIFIED.
718
+ * @property {string} updated_at - Promotion (or creation) timestamp.
719
+ * @property {Object<string, string>} [source_file_hashes] - v3: the per-file hash basis
720
+ * (repo-relative path -> hash) the entry was admitted against, copied from the
721
+ * exporting KB's stored basis. kb_import stores it as the entry's basis exactly
722
+ * (never re-hashing local files); an entry without it gets a local
723
+ * freshness-only basis (it can go stale) that is never exported, so it is not
724
+ * re-published until recaptured.
725
+ * Because kb_import keeps an entry's bible confidence and carried basis, an
726
+ * import from an explicit `path` is equivalent to kb_promote: a member session
727
+ * without the kb_maintainer grant is refused one (E-KB-MAINTAINER-REQUIRED,
728
+ * nothing imported) unless the path is its own .fleet/kb-canonical.json. Even
729
+ * then (and without path) such a session imports its own bible only as
730
+ * committed at HEAD, never the work-tree file; the result adds
731
+ * bible_source "HEAD" and worktree_ignored, and with no committed copy the
732
+ * import fails with E-KB-MAINTAINER-REQUIRED. A committed copy is trusted
733
+ * only when the maintainer side recorded its git blob id in the hub-side KB
734
+ * (kb_bible_commit, or kb_import from the kb_maintainer or a FULL session,
735
+ * records every bible it writes or imports); a bible committed only in the
736
+ * member's own checkout fails with E-KB-MAINTAINER-REQUIRED (the message
737
+ * names the unrecorded blob id) and nothing is imported. The blob's bytes
738
+ * are hashed in-process and must equal the trusted id (a replace ref or
739
+ * overwritten object in the member's .git is refused).
740
+ * kb_import also takes an optional `ref` (a plain git ref name, e.g.
741
+ * "refs/remotes/origin/main"): the bible is then read as committed at that
742
+ * ref (hash-verified) instead of from disk, in any session; the result's
743
+ * bible_source is the ref, a ref without the bible fails with
744
+ * E-BIBLE-NOT-FOUND, and a kb_maintainer or FULL session records that
745
+ * verified blob as trusted. The engine's sprint-start priming seeds trust
746
+ * this way from the base branch, never from the maintainer's work tree.
271
747
  */
272
748
 
273
749
  /**
@@ -316,8 +792,14 @@ const TIMEOUT_GRACE_MS = 30 * 1000;
316
792
 
317
793
  /**
318
794
  * Derives a client-side McpClient.request() timeout (ms) from a payload's
319
- * own timeout hints. Prefers max_total_s (a hard ceiling) over timeout_s
320
- * (an inactivity timeout) when both are present, then adds a grace margin.
795
+ * own timeout hints. Intentionally prefers max_total_s (a hard ceiling) over
796
+ * timeout_s (the stall-detector inactivity baseline) when both are present.
797
+ * This reflects the post-apra-fleet-25yl.2 contract: max_total_s is the
798
+ * primary exec deadline for Claude/AGY, while timeout_s drives only the stall
799
+ * detector's per-dispatch baseline (other providers have different exec-timer
800
+ * mappings per their own adapters). The client's own deadline thus uses the
801
+ * appropriate upper bound for the dispatch. Adds a grace margin to account
802
+ * for server-side retry overhead.
321
803
  * Returns undefined when neither hint is present, letting McpClient fall
322
804
  * back to its own conservative default (never infinite).
323
805
  *
@@ -357,6 +839,153 @@ export function parseToolJson(result) {
357
839
  throw new Error('No JSON payload in tool result');
358
840
  }
359
841
 
842
+ const isStringArray = (v) => Array.isArray(v) && v.every((s) => typeof s === 'string');
843
+
844
+ /**
845
+ * The pre-redesign kb_* scope keys. Every kb_* tool acts on the calling
846
+ * session's own KB, so the server refuses a call carrying any of these with
847
+ * E-SCOPE-KEY-REMOVED (src/services/knowledge/kb-removed-scope-keys.ts). The
848
+ * kb_* wrappers below refuse them client-side with the same code, so a stale
849
+ * caller fails fast and identically whichever side catches it.
850
+ */
851
+ export const KB_REMOVED_SCOPE_KEYS = Object.freeze(['repo_path', 'repo', 'repo_remote_url']);
852
+
853
+ /**
854
+ * Throw E-SCOPE-KEY-REMOVED when `options` carries a removed kb_* scope key
855
+ * (any value other than undefined).
856
+ * @param {string} tool - the kb_* tool name, for the message
857
+ * @param {Record<string, unknown>} [options]
858
+ */
859
+ export function assertNoRemovedKbScopeKeys(tool, options) {
860
+ if (!options || typeof options !== 'object') return;
861
+ const present = KB_REMOVED_SCOPE_KEYS.filter((k) => options[k] !== undefined);
862
+ if (present.length === 0) return;
863
+ const err = new Error(
864
+ `E-SCOPE-KEY-REMOVED: ${tool} no longer accepts ${present.map((k) => `'${k}'`).join(', ')} ` +
865
+ '(removed in the KB redesign); the call was not sent. Remediation: drop it -- every kb_* call acts on the ' +
866
+ "calling session's own KB (a member session's registered work folder; a FULL session's fleet server working folder).",
867
+ );
868
+ err.code = 'E-SCOPE-KEY-REMOVED';
869
+ throw err;
870
+ }
871
+
872
+ /**
873
+ * Typed read of an execute_prompt permission denial. Accepts the raw executePrompt()
874
+ * result or its `structuredContent`; returns the {@link PermissionDenied} block when
875
+ * `reason === 'permission_denied'` and the block is well-formed, else null.
876
+ *
877
+ * @param {{structuredContent?: ExecutePromptStructured} | ExecutePromptStructured | null | undefined} result
878
+ * @returns {PermissionDenied | null}
879
+ */
880
+ export function permissionDenialOf(result) {
881
+ const sc = result && typeof result === 'object' && 'structuredContent' in result ? result.structuredContent : result;
882
+ if (!sc || sc.reason !== 'permission_denied') return null;
883
+ const d = sc.permissionDenied;
884
+ if (!d || typeof d !== 'object') return null;
885
+ if (!isStringArray(d.actions) || !isStringArray(d.suggestedGrants) || typeof d.hint !== 'string') return null;
886
+ if (!Array.isArray(d.denials) || !d.denials.every((x) => x && typeof x.action === 'string' && (x.target === undefined || typeof x.target === 'string'))) return null;
887
+ return {
888
+ actions: [...d.actions],
889
+ denials: d.denials.map((x) => ({
890
+ action: x.action,
891
+ ...(x.target === undefined ? {} : { target: x.target }),
892
+ ...(isStringArray(x.suggestedGrants) ? { suggestedGrants: [...x.suggestedGrants] } : {}),
893
+ })),
894
+ suggestedGrants: [...d.suggestedGrants],
895
+ hint: d.hint,
896
+ signals: isStringArray(d.signals) ? [...d.signals] : [],
897
+ ...(typeof d.permissionMode === 'string' ? { permissionMode: d.permissionMode } : {}),
898
+ ...(typeof d.healable === 'boolean' ? { healable: d.healable } : {}),
899
+ ...(d.cause === 'policy_deny' ? { cause: 'policy_deny' } : {}),
900
+ };
901
+ }
902
+
903
+ /**
904
+ * Anchored text shapes of a fleet tool failure that reached the caller WITHOUT
905
+ * a structured error flag (an older server, or a plain-string tool result).
906
+ * Each pattern matches only at the START of the result text, so a genuine
907
+ * LLM reply that merely mentions "connection refused" mid-body never matches
908
+ * (a successful execute_prompt reply is display-wrapped or carried in
909
+ * structuredContent.response, never bare).
910
+ */
911
+ const FLEET_TOOL_FAILURE_TEXT_RES = Object.freeze([
912
+ /^\s*(?:\[FAIL\]\s*)?Failed to execute (?:command|prompt) on "/,
913
+ /^\s*\(SSH\)\s/,
914
+ /^\s*(?:Error:\s*)?(?:connect\s+)?(?:ECONNREFUSED|ECONNRESET|EHOSTUNREACH|ENETUNREACH|ETIMEDOUT|EPIPE)\b/,
915
+ /^\s*(?:Error:\s*)?(?:Timed out while waiting for handshake|Connection lost before handshake|All configured authentication methods failed|Not connected)\b/,
916
+ ]);
917
+
918
+ /**
919
+ * Typed read of a fleet TOOL/TRANSPORT failure on a raw callTool() result --
920
+ * as opposed to a successful tool call whose payload is the member's (or the
921
+ * LLM's) answer. Returns null for a successful result.
922
+ *
923
+ * Signals, strongest first:
924
+ * - 'isError': the MCP-level `result.isError === true` flag. This is what the
925
+ * MCP server returns when a tool handler THROWS (e.g. an SSH channel that
926
+ * could not be opened): `{ content: [{ text: err.message }], isError: true }`
927
+ * with no structuredContent, so the text is the bare transport error.
928
+ * - 'text': fallback for a result carrying no structured flag and no
929
+ * `structuredContent.response`, whose text starts with a recognisable
930
+ * fleet failure shape (FLEET_TOOL_FAILURE_TEXT_RES).
931
+ *
932
+ * A result whose `structuredContent.isError` is set is NOT reported here:
933
+ * that is the tool's own classified failure (it carries a `reason`), which
934
+ * callers already read directly.
935
+ *
936
+ * @param {{ isError?: boolean, content?: { text?: string }[], structuredContent?: Record<string, any> } | null | undefined} result
937
+ * @returns {{ source: 'isError' | 'text', text: string } | null}
938
+ */
939
+ export function fleetToolFailureOf(result) {
940
+ if (!result || typeof result !== 'object') return null;
941
+ const sc = result.structuredContent;
942
+ if (sc && sc.isError) return null;
943
+ const text = Array.isArray(result.content)
944
+ ? result.content.map((c) => (c && typeof c.text === 'string' ? c.text : '')).filter(Boolean).join('\n')
945
+ : '';
946
+ if (result.isError === true) return { source: 'isError', text };
947
+ if (sc && typeof sc.response === 'string') return null;
948
+ if (FLEET_TOOL_FAILURE_TEXT_RES.some((re) => re.test(text))) return { source: 'text', text };
949
+ return null;
950
+ }
951
+
952
+ // Older servers (before execute_command carried isError on its failure
953
+ // paths) returned a bare text with no structuredContent for a command that
954
+ // never ran. These are that text's two shapes.
955
+ const UNFLAGGED_COMMAND_FAILURE_RE = /^Failed to (execute command|launch task) on "/;
956
+
957
+ /**
958
+ * Typed read of an execute_command failure that never produced an exit code.
959
+ * Accepts the raw executeCommand() result. Returns `{ reason, message }` when the
960
+ * result is an isError failure (structuredContent.isError, or the MCP-level
961
+ * isError flag), or when an older server sent the bare "Failed to execute
962
+ * command on ..." / "Failed to launch task on ..." text with no
963
+ * structuredContent. Returns null for a command that ran (any exit code --
964
+ * callers check a non-zero exitCode separately).
965
+ *
966
+ * @param {{content?: {text?: string}[], structuredContent?: ExecuteCommandStructured, isError?: boolean} | null | undefined} result
967
+ * @returns {ExecuteCommandFailure | null}
968
+ */
969
+ export function commandFailureOf(result) {
970
+ if (!result || typeof result !== 'object') return null;
971
+ const text = Array.isArray(result.content) && result.content.length > 0 && typeof result.content[0]?.text === 'string'
972
+ ? result.content[0].text
973
+ : '';
974
+ const sc = result.structuredContent;
975
+ if (sc && typeof sc === 'object' && sc.isError) {
976
+ const reason = typeof sc.reason === 'string' && sc.reason ? sc.reason : 'unknown';
977
+ const detail = typeof sc.stderr === 'string' ? sc.stderr : '';
978
+ return { reason, message: text || detail || `execute_command failed (${reason})` };
979
+ }
980
+ if (result.isError) {
981
+ return { reason: 'unknown', message: text || 'execute_command failed' };
982
+ }
983
+ if (!sc && UNFLAGGED_COMMAND_FAILURE_RE.test(text)) {
984
+ return { reason: 'unflagged_failure', message: text };
985
+ }
986
+ return null;
987
+ }
988
+
360
989
  export class ApraFleet {
361
990
  /**
362
991
  * @param {{ callTool: (name: string, args: Record<string, any>, opts?: { timeoutMs?: number, signal?: AbortSignal }) => Promise<any> }} mcpClient
@@ -366,8 +995,13 @@ export class ApraFleet {
366
995
  }
367
996
 
368
997
  /**
369
- * Run an AI prompt on a member.
998
+ * Run an AI prompt on a member. A claude member's session gets the
999
+ * member-scoped `apra-fleet` server per session (`--mcp-config`); see
1000
+ * docs/api-reference.md.
370
1001
  * @param {ExecutePromptOptions} options
1002
+ * @returns {Promise<{content?: {type: string, text: string}[], structuredContent?: ExecutePromptStructured}>}
1003
+ * the raw callTool() result -- see the {@link ExecutePromptStructured} typedef above
1004
+ * for the structuredContent shape (reason, usageLimit, sessionId, usage, ...).
371
1005
  */
372
1006
  async executePrompt(options) {
373
1007
  const { timeoutMs, signal, ...payload } = options;
@@ -380,6 +1014,9 @@ export class ApraFleet {
380
1014
  /**
381
1015
  * Run a shell command on a member.
382
1016
  * @param {ExecuteCommandOptions} options
1017
+ * @returns {Promise<{content?: {type: string, text: string}[], structuredContent?: ExecuteCommandStructured}>}
1018
+ * the raw callTool() result. A command that never produced an exit code carries
1019
+ * `structuredContent.isError` and `reason` -- read it with {@link commandFailureOf}.
383
1020
  */
384
1021
  async executeCommand(options) {
385
1022
  const { timeoutMs, signal, ...payload } = options;
@@ -407,7 +1044,7 @@ export class ApraFleet {
407
1044
 
408
1045
  /**
409
1046
  * Get detailed status for one member: connectivity, session, work folder, provider, registered shell (Windows).
410
- * @param {{ member_id?: string, member_name?: string, format?: 'compact'|'json' }} options
1047
+ * @param {{ member_id?: string, member_name?: string, format?: 'compact'|'json', refresh?: boolean }} options
411
1048
  * @returns {Promise<string|MemberDetailResult>} A compact text summary when format is
412
1049
  * "compact" (default), or the structured MemberDetailResult object when format is "json".
413
1050
  */
@@ -418,6 +1055,7 @@ export class ApraFleet {
418
1055
  /**
419
1056
  * Get a member's cheap/standard/premium tier resolved to a concrete
420
1057
  * model and its real per-1M-token price (apra-fleet-dv5.5/dv5.6).
1058
+ * The tool result text is the JSON of a {@link MemberModelPricingResult}.
421
1059
  * @param {{ member_id?: string, member_name?: string }} options
422
1060
  */
423
1061
  async getMemberModelPricing(options) {
@@ -449,7 +1087,10 @@ export class ApraFleet {
449
1087
  }
450
1088
 
451
1089
  /**
452
- * Change a member's settings.
1090
+ * Change a member's settings. Changing `llm_provider` or `work_folder`
1091
+ * removes the composed permission/MCP config written for the old
1092
+ * provider/folder and re-composes for the member as updated (see
1093
+ * docs/api-reference.md).
453
1094
  * @param {UpdateMemberOptions} options
454
1095
  */
455
1096
  async updateMember(options) {
@@ -457,16 +1098,47 @@ export class ApraFleet {
457
1098
  }
458
1099
 
459
1100
  /**
460
- * Remove a member from the fleet.
1101
+ * Remove a member from the fleet. Member-side composed config (the
1102
+ * per-folder `apra-fleet` MCP entry, permission keys) is removed first;
1103
+ * what could not be removed is reported as a warning. The member-side registration on the
1104
+ * member's own apra-fleet install is removed only when that install carries the
1105
+ * member-install marker; otherwise (unmarked, or the marker probe failed) it is
1106
+ * skipped and the output says so and why.
461
1107
  * @param {RemoveMemberOptions} options
462
1108
  */
463
1109
  async removeMember(options) {
464
1110
  return this.mcpClient.callTool('remove_member', options);
465
1111
  }
466
1112
 
1113
+ /**
1114
+ * Reserve, release or force-release exclusive ownership of a member for a
1115
+ * sprint (src/tools/member-reservation.ts).
1116
+ *
1117
+ * The MCP result carries BOTH halves: `content[0].text` is the unchanged
1118
+ * human-readable summary, and `structuredContent` is a
1119
+ * MemberReservationStructured. Programmatic callers must branch on
1120
+ * `structuredContent.outcome` -- string-matching the prose is exactly what
1121
+ * apra-fleet-3swo.7.1 removed the need for.
1122
+ *
1123
+ * @param {MemberReservationOptions} options
1124
+ * @returns {Promise<{ content: Array<{type: string, text: string}>,
1125
+ * structuredContent: MemberReservationStructured }>}
1126
+ */
1127
+ async memberReservation(options) {
1128
+ return this.mcpClient.callTool('member_reservation', options);
1129
+ }
1130
+
467
1131
  /**
468
1132
  * Provision LLM auth (OAuth session copy or API key) onto a member.
1133
+ *
1134
+ * The MCP result carries both halves: `content[0].text` is the
1135
+ * human-readable summary (ASCII markers -- [OK]/[WARN]/[FAIL]/[SKIP], no
1136
+ * emoji) and `structuredContent` is a ProvisionAuthStructured. Branch on
1137
+ * `structuredContent.ok` / `.reason`, never on the summary text.
1138
+ *
469
1139
  * @param {ProvisionLlmAuthOptions} options
1140
+ * @returns {Promise<{ content: Array<{type: string, text: string}>,
1141
+ * structuredContent: ProvisionAuthStructured }>}
470
1142
  */
471
1143
  async provisionLlmAuth(options) {
472
1144
  return this.mcpClient.callTool('provision_llm_auth', options);
@@ -475,20 +1147,109 @@ export class ApraFleet {
475
1147
  /**
476
1148
  * Provision VCS (git host) auth -- GitHub App token / PAT, Bitbucket API
477
1149
  * token, or Azure DevOps PAT -- onto a member.
1150
+ *
1151
+ * Same two-halves result shape as provisionLlmAuth: read
1152
+ * `structuredContent.ok`/`.reason` for the outcome and
1153
+ * `structuredContent.expiresAt` for the token expiry, instead of parsing
1154
+ * an "expiresAt:" line out of the prose.
1155
+ *
478
1156
  * @param {ProvisionVcsAuthOptions} options
1157
+ * @returns {Promise<{ content: Array<{type: string, text: string}>,
1158
+ * structuredContent: ProvisionVcsAuthStructured }>}
479
1159
  */
480
1160
  async provisionVcsAuth(options) {
481
1161
  return this.mcpClient.callTool('provision_vcs_auth', options);
482
1162
  }
483
1163
 
484
1164
  /**
485
- * Compose and deliver a scoped permission profile to a member.
1165
+ * Run a credential-requiring git/VCS command on a member WITHOUT the
1166
+ * caller ever learning the credential (src/tools/vcs-credential-exec.ts).
1167
+ *
1168
+ * This is the server-side replacement for reading a token back out of the
1169
+ * deployed git-credential-helper: the server reads the credential
1170
+ * in-process, substitutes whichever placeholder(s) the command contains
1171
+ * -- {{vcs_token}} (bare, already quoted for the member's shell) and/or
1172
+ * {{vcs_token_inline}} (for use inside the caller's own single quotes,
1173
+ * escaped for that interior with no quotes of its own) -- dispatches the
1174
+ * command, and redacts the value from the returned stdout/stderr. The
1175
+ * plaintext appears in no field of the result.
1176
+ *
1177
+ * @param {VcsCredentialExecOptions} options
1178
+ * @returns {Promise<{ content: Array<{type: string, text: string}>,
1179
+ * structuredContent: VcsCredentialExecStructured }>}
1180
+ */
1181
+ async vcsCredentialExec(options) {
1182
+ return this.mcpClient.callTool('vcs_credential_exec', options);
1183
+ }
1184
+
1185
+ /**
1186
+ * Compose and deliver a scoped permission profile to a member. Also writes
1187
+ * the member's per-folder `apra-fleet` MCP entry (`?member=<uuid>`) through
1188
+ * the member provider's own per-project config (not for a local claude
1189
+ * member, whose dispatches get it per session: an entry an older compose
1190
+ * wrote for it is removed instead), with deny rules for every
1191
+ * fleet tool outside the member allowlist (claude, agy), merged by union
1192
+ * with any existing deny rules. The result states why a member config was
1193
+ * not edited (tracked by git, not strict JSON, unreadable) and when a stale
1194
+ * fleetMcp unavailable status was cleared; see docs/api-reference.md.
486
1195
  * @param {ComposePermissionsOptions} options
487
1196
  */
488
1197
  async composePermissions(options) {
489
1198
  return this.mcpClient.callTool('compose_permissions', options);
490
1199
  }
491
1200
 
1201
+ /**
1202
+ * Export the calling session's CONFIRMED KB entries to the canonical bible
1203
+ * file and auto-commit it locally (never pushed). Pass baseBranch/baseCommit
1204
+ * to record the target base branch and base commit in provenance. Writes
1205
+ * bible format v3: each added project entry is a KbBibleEntry carrying its
1206
+ * source_file_hashes basis; a bible holding a duplicate id is refused.
1207
+ * Result JSON: {exported, path, scope, committed}; extract with parseToolJson().
1208
+ * The removed scope keys (repo_path, repo, repo_remote_url) are refused
1209
+ * with E-SCOPE-KEY-REMOVED before anything is sent.
1210
+ * @param {KbExportOptions} [options]
1211
+ */
1212
+ async kbExport(options = {}) {
1213
+ assertNoRemovedKbScopeKeys('kb_export', options);
1214
+ return this.mcpClient.callTool('kb_export', options);
1215
+ }
1216
+
1217
+ /**
1218
+ * Merge exactly the given confirmed entry ids into the bible at entry level
1219
+ * (existing entries kept unless this KB holds them as superseded or
1220
+ * invalidated -- those are removed, also when ids is empty; each merged
1221
+ * entry is a v3 KbBibleEntry carrying its source_file_hashes basis; a bible
1222
+ * holding a duplicate id is refused), write baseBranch/baseCommit
1223
+ * provenance, and make a local commit scoped to the bible path whose message
1224
+ * lists each removal. Never pushes; re-running with the
1225
+ * same ids after resetting to a newer HEAD re-merges, so a rejected push can
1226
+ * be retried. Result JSON: {path, merged, skipped, removed, entry_count,
1227
+ * backfilled, committed}; extract with parseToolJson(). backfilled counts the
1228
+ * existing bible entries with no source_file_hashes (carried over from a
1229
+ * v1/v2 bible) that gained this KB's stored basis for the same id, because
1230
+ * it passes the same basis rule at HEAD and cites the same files (legacy
1231
+ * backfill; only that field changes, nothing is dropped); a backfill alone
1232
+ * makes a commit. Each skipped item is {id, reason}
1233
+ * with reason not_confirmed_or_unknown, no_source_files (a CONFIRMED id
1234
+ * citing no source file) or basis_mismatch. Each removed item is {id, reason}
1235
+ * with reason superseded or invalidated. A member session without the
1236
+ * kb_maintainer grant cannot retire a CONFIRMED entry through the kb_* tools:
1237
+ * kb_invalidate leaves CONFIRMED entries untouched, and kb_capture with
1238
+ * supersedes links to a CONFIRMED target (refines, both live) instead of
1239
+ * retiring it; both list such ids in their response's refused list. The
1240
+ * kb_maintainer session and FULL sessions are not limited, and the grant is
1241
+ * a routing guard for agent sessions, not a boundary against a local process
1242
+ * that can open a FULL session or write the KB directly.
1243
+ * A CONFIRMED id is admitted only if it passes the same basis rule as kb_export.
1244
+ * The removed scope keys (repo_path, repo, repo_remote_url) are refused
1245
+ * with E-SCOPE-KEY-REMOVED before anything is sent.
1246
+ * @param {KbBibleCommitOptions} options
1247
+ */
1248
+ async kbBibleCommit(options) {
1249
+ assertNoRemovedKbScopeKeys('kb_bible_commit', options);
1250
+ return this.mcpClient.callTool('kb_bible_commit', options);
1251
+ }
1252
+
492
1253
  /**
493
1254
  * Convert a remote member from password to SSH key authentication.
494
1255
  * @param {SetupSshKeyOptions} options
@@ -518,6 +1279,75 @@ export class ApraFleet {
518
1279
  return this.mcpClient.callTool('credential_store_set', options);
519
1280
  }
520
1281
 
1282
+ /**
1283
+ * code_reindex -- rebuild the code index of the calling session's own repo
1284
+ * (a member session's work folder, otherwise the fleet server's folder;
1285
+ * there is no repo argument). Starts gitnexus analyze detached with its
1286
+ * output captured to <data>/code-index/<slug>/analyze.log and returns
1287
+ * after the first tick. Extract the JSON with parseToolJson(): `outcome`
1288
+ * is 'started' | 'up-to-date' | 'starting' | 'already-running' |
1289
+ * 'not-started'; a not-started result carries a typed `reason`
1290
+ * ('npx-not-found' | 'gitnexus-not-found' | 'analyze-failed' |
1291
+ * 'spawn-failed' | 'remote-member' | 'gitnexus-too-old' |
1292
+ * 'provider-not-supported'); 'gitnexus-too-old' means the installed
1293
+ * gitnexus rejects --index-only and its `detail` names the upgrade fix.
1294
+ * Every result also carries `injectedBlockFiles` (repo-relative agent docs
1295
+ * still holding a gitnexus block injected by an earlier plain analyze run;
1296
+ * detection only, the work tree is never edited). Only the
1297
+ * gitnexus provider is supported: provider 'none' makes the tool fail with
1298
+ * E-CODE-INTEL-DISABLED, and any other provider (e.g. codebase-memory)
1299
+ * yields { outcome: 'not-started', reason: 'provider-not-supported',
1300
+ * provider, indexedCommit: null, detail }. Every result carries
1301
+ * `indexedCommit` (the commit the index is built at, or null when there
1302
+ * is no index or the folder is remote). Poll codeStatus() for completion.
1303
+ */
1304
+ async codeReindex() {
1305
+ return this.mcpClient.callTool('code_reindex', {});
1306
+ }
1307
+
1308
+ /**
1309
+ * code_status -- the calling session's own code index state: the last
1310
+ * analyze run (`analyze`: phase, result 'indexed' | 'up-to-date' |
1311
+ * 'incomplete' | 'failed', lastLine, ...), live `readiness`
1312
+ * ('ready' | 'building' | 'interrupted' | 'inconsistent' | 'missing';
1313
+ * 'building' also covers an analyze rewriting an existing index, which is
1314
+ * never served meanwhile; 'interrupted' = an analyze died mid-write and
1315
+ * none is running; 'inconsistent' = the gitnexus registry or the fleet
1316
+ * record of its last build names a different commit than meta.json, with
1317
+ * the reason in `inconsistency` (null otherwise) -- for both, the next
1318
+ * code_* call starts a rebuild), `indexedCommit`, `lockHeld`, and `logPath` (null
1319
+ * when no analyze log exists yet), and `autoReindexPaused` (null, or the
1320
+ * { result, lastLine, logPath, finished } of a failed automatic run --
1321
+ * automatic rebuilds stay paused until codeReindex() or a server
1322
+ * restart), `injectedBlockFiles` / `injectedBlockWarning` (agent docs still
1323
+ * holding a previously injected gitnexus block, and the one-line WARN with
1324
+ * the fix; [] / null when clean), and on a failed run
1325
+ * `analyze.failureCause` ('gitnexus-too-old' when gitnexus rejected
1326
+ * --index-only). A remote work folder returns { remote: true, repo,
1327
+ * indexedCommit: null, detail }. Same provider gate as codeReindex():
1328
+ * provider 'none' fails with E-CODE-INTEL-DISABLED; a non-gitnexus
1329
+ * provider returns the not-supported shape { outcome: 'not-started',
1330
+ * reason: 'provider-not-supported', provider, indexedCommit: null,
1331
+ * detail } rather than gitnexus readiness. Extract the JSON with
1332
+ * parseToolJson().
1333
+ */
1334
+ async codeStatus() {
1335
+ return this.mcpClient.callTool('code_status', {});
1336
+ }
1337
+
1338
+ /**
1339
+ * session_stats -- a member's kb_* / code_* tool call counts on this
1340
+ * server, aggregated across that member's sessions (engine-origin
1341
+ * sessions excluded). On a member session the calling member is reported
1342
+ * and `member_id` may be omitted; a non-member session must pass it.
1343
+ * Extract the JSON with parseToolJson(): a SessionStatsResult.
1344
+ *
1345
+ * @param {SessionStatsOptions} [options]
1346
+ */
1347
+ async sessionStats(options = {}) {
1348
+ return this.mcpClient.callTool('session_stats', options);
1349
+ }
1350
+
521
1351
  /**
522
1352
  * List stored credentials (names and metadata only -- no values).
523
1353
  * The result payload is a JSON array of { name, scope, ... } entries;
@@ -569,6 +1399,9 @@ export class ApraFleet {
569
1399
  * src/tools/child-id-allocator.ts). Mints globally-distinct child ids under
570
1400
  * a shared parent for sprints launched WITHOUT a supervisor, so two sprints
571
1401
  * creating children under the same parent never derive the same id.
1402
+ * `floor` (allocate) is the parent's highest existing child seq: the
1403
+ * counter is never below it and released ids at or below it are dropped
1404
+ * from the reuse pool on every allocate.
572
1405
  *
573
1406
  * @param {{ action: 'allocate'|'confirm'|'release'|'status',
574
1407
  * parent_id?: string, token?: string, sprint_id?: string,