@apralabs/apra-fleet 0.4.3 → 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 (951) hide show
  1. package/README.md +66 -30
  2. package/dist/agents/backlog-groomer.md +75 -27
  3. package/dist/agents/ci-watcher.md +37 -22
  4. package/dist/agents/deployer.md +39 -22
  5. package/dist/agents/doer.md +74 -40
  6. package/dist/agents/harvester.md +49 -40
  7. package/dist/agents/integ-test-runner.md +40 -23
  8. package/dist/agents/kb-reconciler.md +28 -7
  9. package/dist/agents/plan-reviewer.md +49 -24
  10. package/dist/agents/planner.md +66 -43
  11. package/dist/agents/regression-test-runner.md +101 -78
  12. package/dist/agents/reviewer.md +117 -56
  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/planner-output.json +1 -1
  17. package/dist/agents/schemas/regression-test-runner-output.json +41 -7
  18. package/dist/agents/schemas/reviewer-output.json +62 -3
  19. package/dist/cli/agent-transform.d.ts +7 -0
  20. package/dist/cli/agent-transform.js +46 -1
  21. package/dist/cli/auth.d.ts +1 -0
  22. package/dist/cli/auth.js +38 -8
  23. package/dist/cli/beads-install.d.ts +35 -0
  24. package/dist/cli/beads-install.js +125 -0
  25. package/dist/cli/beads-pin.d.ts +5 -0
  26. package/dist/cli/beads-pin.js +27 -0
  27. package/dist/cli/call.d.ts +27 -0
  28. package/dist/cli/call.js +177 -0
  29. package/dist/cli/config.d.ts +24 -1
  30. package/dist/cli/config.js +69 -2
  31. package/dist/cli/dolt-install.d.ts +18 -2
  32. package/dist/cli/dolt-install.js +46 -15
  33. package/dist/cli/fleet-se-guard.d.ts +51 -0
  34. package/dist/cli/fleet-se-guard.js +215 -0
  35. package/dist/cli/install-guard.d.ts +54 -0
  36. package/dist/cli/install-guard.js +132 -4
  37. package/dist/cli/install.d.ts +77 -21
  38. package/dist/cli/install.js +610 -152
  39. package/dist/cli/kb-commit.d.ts +2 -1
  40. package/dist/cli/kb-commit.js +1 -1
  41. package/dist/cli/kb-import.d.ts +2 -1
  42. package/dist/cli/kb-import.js +1 -1
  43. package/dist/cli/register-member.js +20 -3
  44. package/dist/cli/remove-member.d.ts +4 -0
  45. package/dist/cli/remove-member.js +63 -0
  46. package/dist/cli/secret.js +9 -0
  47. package/dist/cli/start.js +59 -4
  48. package/dist/cli/status.d.ts +3 -0
  49. package/dist/cli/status.js +45 -12
  50. package/dist/cli/stop.js +64 -9
  51. package/dist/cli/uninstall.js +101 -15
  52. package/dist/cli/update.js +33 -2
  53. package/dist/cli/watch.js +1 -1
  54. package/dist/cli/workflow.js +3 -2
  55. package/dist/commands/kb-server.js +9 -2
  56. package/dist/hub-service/http-server.d.ts +5 -1
  57. package/dist/hub-service/http-server.js +55 -5
  58. package/dist/index.js +155 -8
  59. package/dist/os/child-env-bound.d.ts +77 -0
  60. package/dist/os/child-env-bound.js +171 -0
  61. package/dist/os/linux.d.ts +7 -2
  62. package/dist/os/linux.js +40 -14
  63. package/dist/os/macos.d.ts +1 -1
  64. package/dist/os/macos.js +2 -11
  65. package/dist/os/os-commands.d.ts +17 -2
  66. package/dist/os/windows-gitbash.d.ts +1 -0
  67. package/dist/os/windows-gitbash.js +17 -3
  68. package/dist/os/windows-wrapper.d.ts +0 -4
  69. package/dist/os/windows-wrapper.js +2 -1
  70. package/dist/os/windows.d.ts +5 -2
  71. package/dist/os/windows.js +75 -29
  72. package/dist/paths.d.ts +21 -0
  73. package/dist/paths.js +35 -0
  74. package/dist/providers/agy.d.ts +6 -2
  75. package/dist/providers/agy.js +245 -106
  76. package/dist/providers/claude-permission-denial.d.ts +7 -0
  77. package/dist/providers/claude-permission-denial.js +137 -0
  78. package/dist/providers/claude.d.ts +86 -38
  79. package/dist/providers/claude.js +426 -164
  80. package/dist/providers/codex.js +5 -1
  81. package/dist/providers/copilot.js +5 -1
  82. package/dist/providers/opencode.d.ts +10 -2
  83. package/dist/providers/opencode.js +114 -53
  84. package/dist/providers/provider.d.ts +171 -33
  85. package/dist/providers/provider.js +164 -3
  86. package/dist/services/agent-provisioner.d.ts +29 -0
  87. package/dist/services/agent-provisioner.js +107 -0
  88. package/dist/services/agent-shadow.d.ts +96 -0
  89. package/dist/services/agent-shadow.js +479 -0
  90. package/dist/services/agy-project.d.ts +2 -1
  91. package/dist/services/agy-project.js +15 -17
  92. package/dist/services/auth-socket.d.ts +25 -0
  93. package/dist/services/auth-socket.js +68 -23
  94. package/dist/services/auth-web.js +1 -1
  95. package/dist/services/budget-awareness.d.ts +11 -11
  96. package/dist/services/budget-awareness.js +15 -3
  97. package/dist/services/claude-local-scope-mcp.d.ts +19 -0
  98. package/dist/services/claude-local-scope-mcp.js +91 -0
  99. package/dist/services/cloud/aws.js +2 -1
  100. package/dist/services/cloud/lifecycle.js +19 -2
  101. package/dist/services/cloud/task-wrapper.d.ts +0 -9
  102. package/dist/services/cloud/task-wrapper.js +15 -6
  103. package/dist/services/event-loop-watchdog.d.ts +32 -0
  104. package/dist/services/event-loop-watchdog.js +140 -0
  105. package/dist/services/http-transport.d.ts +49 -1
  106. package/dist/services/http-transport.js +190 -24
  107. package/dist/services/in-flight-agents.d.ts +2 -0
  108. package/dist/services/in-flight-agents.js +4 -0
  109. package/dist/services/knowledge/bible-basis-filter.d.ts +53 -0
  110. package/dist/services/knowledge/bible-basis-filter.js +134 -0
  111. package/dist/services/knowledge/bible-blob-id.d.ts +44 -0
  112. package/dist/services/knowledge/bible-blob-id.js +113 -0
  113. package/dist/services/knowledge/bible-import.d.ts +65 -0
  114. package/dist/services/knowledge/bible-import.js +211 -0
  115. package/dist/services/knowledge/file-hash.d.ts +31 -0
  116. package/dist/services/knowledge/file-hash.js +153 -23
  117. package/dist/services/knowledge/http-provider.d.ts +4 -3
  118. package/dist/services/knowledge/http-provider.js +17 -5
  119. package/dist/services/knowledge/kb-maintainer-grant.d.ts +15 -0
  120. package/dist/services/knowledge/kb-maintainer-grant.js +34 -0
  121. package/dist/services/knowledge/kb-providers.d.ts +4 -0
  122. package/dist/services/knowledge/kb-providers.js +8 -0
  123. package/dist/services/knowledge/kb-removed-scope-keys.d.ts +28 -0
  124. package/dist/services/knowledge/kb-removed-scope-keys.js +59 -0
  125. package/dist/services/knowledge/kb-scopes.d.ts +14 -0
  126. package/dist/services/knowledge/kb-scopes.js +47 -0
  127. package/dist/services/knowledge/kb-self.d.ts +91 -0
  128. package/dist/services/knowledge/kb-self.js +198 -0
  129. package/dist/services/knowledge/member-bible-view.d.ts +21 -0
  130. package/dist/services/knowledge/member-bible-view.js +194 -0
  131. package/dist/services/knowledge/pre-init.js +1 -0
  132. package/dist/services/knowledge/project-slug.js +2 -2
  133. package/dist/services/knowledge/sqlite-provider.d.ts +64 -11
  134. package/dist/services/knowledge/sqlite-provider.js +303 -41
  135. package/dist/services/knowledge/types.d.ts +45 -2
  136. package/dist/services/member-access-secret.d.ts +70 -0
  137. package/dist/services/member-access-secret.js +195 -0
  138. package/dist/services/member-call-counts.d.ts +24 -0
  139. package/dist/services/member-call-counts.js +58 -0
  140. package/dist/services/member-config-io.d.ts +192 -0
  141. package/dist/services/member-config-io.js +443 -0
  142. package/dist/services/member-fleet-install.d.ts +710 -0
  143. package/dist/services/member-fleet-install.js +1895 -0
  144. package/dist/services/member-secret-env.d.ts +42 -0
  145. package/dist/services/member-secret-env.js +68 -0
  146. package/dist/services/member-tool-allowlist.d.ts +49 -0
  147. package/dist/services/member-tool-allowlist.js +111 -0
  148. package/dist/services/model-pricing.d.ts +19 -0
  149. package/dist/services/model-pricing.js +54 -8
  150. package/dist/services/port-holder.d.ts +86 -0
  151. package/dist/services/port-holder.js +351 -0
  152. package/dist/services/preflight-check.js +2 -0
  153. package/dist/services/registry.d.ts +13 -2
  154. package/dist/services/registry.js +27 -1
  155. package/dist/services/relay-strategy.d.ts +2 -0
  156. package/dist/services/relay-strategy.js +8 -0
  157. package/dist/services/server-lifecycle.d.ts +26 -0
  158. package/dist/services/server-lifecycle.js +85 -0
  159. package/dist/services/service-manager/index.d.ts +7 -1
  160. package/dist/services/service-manager/index.js +17 -4
  161. package/dist/services/service-manager/linux.d.ts +1 -1
  162. package/dist/services/service-manager/linux.js +15 -7
  163. package/dist/services/service-manager/macos.d.ts +11 -1
  164. package/dist/services/service-manager/macos.js +45 -7
  165. package/dist/services/service-manager/service-path.d.ts +24 -0
  166. package/dist/services/service-manager/service-path.js +55 -0
  167. package/dist/services/service-manager/types.d.ts +38 -3
  168. package/dist/services/service-manager/types.js +29 -0
  169. package/dist/services/service-manager/windows.d.ts +181 -2
  170. package/dist/services/service-manager/windows.js +666 -49
  171. package/dist/services/service-notice.d.ts +14 -0
  172. package/dist/services/service-notice.js +62 -0
  173. package/dist/services/service-start-guard.d.ts +20 -0
  174. package/dist/services/service-start-guard.js +86 -0
  175. package/dist/services/session-cost.d.ts +24 -0
  176. package/dist/services/session-cost.js +105 -0
  177. package/dist/services/session-mcp-config.d.ts +83 -0
  178. package/dist/services/session-mcp-config.js +211 -0
  179. package/dist/services/sftp.d.ts +34 -0
  180. package/dist/services/sftp.js +304 -76
  181. package/dist/services/shell-probe.d.ts +0 -24
  182. package/dist/services/shell-probe.js +28 -3
  183. package/dist/services/singleton.d.ts +68 -2
  184. package/dist/services/singleton.js +168 -11
  185. package/dist/services/sprint-coordination.js +9 -3
  186. package/dist/services/ssh.d.ts +27 -0
  187. package/dist/services/ssh.js +229 -38
  188. package/dist/services/stall/find-log-file.js +12 -5
  189. package/dist/services/stall/index.d.ts +1 -1
  190. package/dist/services/stall/read-log-tail.d.ts +23 -0
  191. package/dist/services/stall/read-log-tail.js +33 -2
  192. package/dist/services/stall/stall-detector.d.ts +25 -1
  193. package/dist/services/stall/stall-detector.js +85 -6
  194. package/dist/services/stall/stall-poller.d.ts +16 -0
  195. package/dist/services/stall/stall-poller.js +50 -6
  196. package/dist/services/stopped-marker.d.ts +16 -0
  197. package/dist/services/stopped-marker.js +55 -0
  198. package/dist/services/strategy.d.ts +33 -1
  199. package/dist/services/strategy.js +86 -17
  200. package/dist/services/supervisor-service-cleanup.d.ts +52 -0
  201. package/dist/services/supervisor-service-cleanup.js +332 -0
  202. package/dist/services/tool-registry.d.ts +8 -1
  203. package/dist/services/tool-registry.js +160 -59
  204. package/dist/services/tool-scope.d.ts +58 -0
  205. package/dist/services/tool-scope.js +99 -0
  206. package/dist/services/watch/project-resolver.js +1 -0
  207. package/dist/skills/auto-sprint-args/SKILL.md +2 -2
  208. package/dist/skills/fleet-sprint-cli/SKILL.md +39 -15
  209. package/dist/skills/pm/SKILL.md +3 -3
  210. package/dist/skills/pm/index.md +4 -2
  211. package/dist/skills/pm/kb-reconcile.md +29 -14
  212. package/dist/skills/pm/kb-review.md +1 -0
  213. package/dist/skills/pm/sprint.md +5 -5
  214. package/dist/tools/check-status.d.ts +53 -5
  215. package/dist/tools/check-status.js +210 -53
  216. package/dist/tools/child-id-allocator.d.ts +2 -2
  217. package/dist/tools/child-id-allocator.js +1 -1
  218. package/dist/tools/code-index-heal.d.ts +8 -0
  219. package/dist/tools/code-index-heal.js +21 -0
  220. package/dist/tools/code-index-state.d.ts +45 -0
  221. package/dist/tools/code-index-state.js +115 -0
  222. package/dist/tools/code-intelligence-codebase-memory.js +6 -33
  223. package/dist/tools/code-intelligence-freshness.js +1 -1
  224. package/dist/tools/code-intelligence-gitnexus.d.ts +30 -0
  225. package/dist/tools/code-intelligence-gitnexus.js +333 -57
  226. package/dist/tools/code-intelligence-kb-enrich.js +7 -6
  227. package/dist/tools/code-intelligence-readiness.d.ts +99 -0
  228. package/dist/tools/code-intelligence-readiness.js +206 -0
  229. package/dist/tools/code-intelligence-reindex.d.ts +195 -0
  230. package/dist/tools/code-intelligence-reindex.js +530 -50
  231. package/dist/tools/code-intelligence-telemetry.d.ts +6 -1
  232. package/dist/tools/code-intelligence-telemetry.js +12 -3
  233. package/dist/tools/code-intelligence.d.ts +81 -31
  234. package/dist/tools/code-intelligence.js +156 -52
  235. package/dist/tools/compose-permissions.d.ts +57 -2
  236. package/dist/tools/compose-permissions.js +497 -44
  237. package/dist/tools/execute-command.d.ts +11 -0
  238. package/dist/tools/execute-command.js +80 -12
  239. package/dist/tools/execute-prompt.d.ts +59 -15
  240. package/dist/tools/execute-prompt.js +544 -133
  241. package/dist/tools/kb-bible-commit.d.ts +65 -0
  242. package/dist/tools/kb-bible-commit.js +239 -0
  243. package/dist/tools/kb-capture.d.ts +13 -9
  244. package/dist/tools/kb-capture.js +42 -11
  245. package/dist/tools/kb-context.d.ts +27 -7
  246. package/dist/tools/kb-context.js +60 -9
  247. package/dist/tools/kb-export.d.ts +96 -7
  248. package/dist/tools/kb-export.js +228 -65
  249. package/dist/tools/kb-feedback.d.ts +13 -9
  250. package/dist/tools/kb-feedback.js +13 -7
  251. package/dist/tools/kb-freshness-sweep.d.ts +11 -7
  252. package/dist/tools/kb-freshness-sweep.js +7 -7
  253. package/dist/tools/kb-harvest.d.ts +11 -7
  254. package/dist/tools/kb-harvest.js +7 -7
  255. package/dist/tools/kb-import.d.ts +26 -10
  256. package/dist/tools/kb-import.js +169 -159
  257. package/dist/tools/kb-invalidate.d.ts +17 -10
  258. package/dist/tools/kb-invalidate.js +41 -8
  259. package/dist/tools/kb-list.d.ts +14 -10
  260. package/dist/tools/kb-list.js +30 -10
  261. package/dist/tools/kb-promote.d.ts +11 -7
  262. package/dist/tools/kb-promote.js +14 -8
  263. package/dist/tools/kb-query.d.ts +21 -11
  264. package/dist/tools/kb-query.js +76 -13
  265. package/dist/tools/kb-reconcile-prefilter.d.ts +11 -7
  266. package/dist/tools/kb-reconcile-prefilter.js +10 -8
  267. package/dist/tools/kb-resolve-contradiction.d.ts +11 -7
  268. package/dist/tools/kb-resolve-contradiction.js +7 -7
  269. package/dist/tools/kb-session-prime.d.ts +14 -7
  270. package/dist/tools/kb-session-prime.js +44 -44
  271. package/dist/tools/kb-setup.d.ts +11 -4
  272. package/dist/tools/kb-setup.js +25 -11
  273. package/dist/tools/kb-stats.d.ts +11 -10
  274. package/dist/tools/kb-stats.js +22 -41
  275. package/dist/tools/list-members.js +5 -2
  276. package/dist/tools/member-detail.d.ts +3 -0
  277. package/dist/tools/member-detail.js +88 -17
  278. package/dist/tools/member-reservation.d.ts +2 -2
  279. package/dist/tools/provision-auth.d.ts +39 -1
  280. package/dist/tools/provision-auth.js +269 -47
  281. package/dist/tools/provision-vcs-auth.d.ts +2 -2
  282. package/dist/tools/receive-files.js +3 -1
  283. package/dist/tools/register-member.d.ts +34 -8
  284. package/dist/tools/register-member.js +76 -58
  285. package/dist/tools/remove-member.js +110 -32
  286. package/dist/tools/send-email.d.ts +2 -2
  287. package/dist/tools/send-files.js +6 -4
  288. package/dist/tools/session-stats.d.ts +17 -0
  289. package/dist/tools/session-stats.js +27 -0
  290. package/dist/tools/shutdown-server.js +5 -0
  291. package/dist/tools/update-agent-cli.d.ts +19 -0
  292. package/dist/tools/update-agent-cli.js +59 -2
  293. package/dist/tools/update-member.d.ts +13 -10
  294. package/dist/tools/update-member.js +138 -7
  295. package/dist/tools/vcs-credential-exec.js +8 -2
  296. package/dist/types.d.ts +98 -1
  297. package/dist/utils/agent-helpers.js +2 -0
  298. package/dist/utils/auth-env.d.ts +15 -4
  299. package/dist/utils/auth-env.js +52 -23
  300. package/dist/utils/find-on-path.d.ts +37 -0
  301. package/dist/utils/find-on-path.js +85 -0
  302. package/dist/utils/log-helpers.d.ts +37 -0
  303. package/dist/utils/log-helpers.js +106 -20
  304. package/dist/utils/owner-only-fs.d.ts +56 -0
  305. package/dist/utils/owner-only-fs.js +98 -0
  306. package/dist/utils/process-utils.d.ts +28 -0
  307. package/dist/utils/process-utils.js +68 -0
  308. package/dist/utils/prompt-errors.js +4 -1
  309. package/dist/utils/session-caller.d.ts +4 -2
  310. package/dist/utils/session-caller.js +3 -2
  311. package/dist/utils/shell-escape.d.ts +42 -3
  312. package/dist/utils/shell-escape.js +70 -4
  313. package/dist/utils/ssh-error-messages.js +3 -0
  314. package/dist/utils/workspace-trust.d.ts +24 -1
  315. package/dist/utils/workspace-trust.js +21 -17
  316. package/dist/workflows/auto-sprint.js +223 -43
  317. package/package.json +11 -8
  318. package/packages/apra-fleet-client/package.json +2 -2
  319. package/packages/apra-fleet-client/src/client/api.mjs +558 -27
  320. package/packages/apra-fleet-client/src/client/auto-start.mjs +434 -0
  321. package/packages/apra-fleet-client/src/client/client.mjs +9 -0
  322. package/packages/apra-fleet-client/src/client/factory.mjs +23 -4
  323. package/packages/apra-fleet-client/src/client/reconnecting-transport.mjs +137 -0
  324. package/packages/apra-fleet-client/src/client/server-resolution.mjs +267 -30
  325. package/packages/apra-fleet-client/src/client/transport.mjs +37 -3
  326. package/packages/apra-fleet-se/apra-pm/agents/backlog-groomer.md +75 -27
  327. package/packages/apra-fleet-se/apra-pm/agents/ci-watcher.md +37 -22
  328. package/packages/apra-fleet-se/apra-pm/agents/deployer.md +39 -22
  329. package/packages/apra-fleet-se/apra-pm/agents/doer.md +74 -40
  330. package/packages/apra-fleet-se/apra-pm/agents/harvester.md +49 -40
  331. package/packages/apra-fleet-se/apra-pm/agents/integ-test-runner.md +40 -23
  332. package/packages/apra-fleet-se/apra-pm/agents/kb-reconciler.md +28 -7
  333. package/packages/apra-fleet-se/apra-pm/agents/plan-reviewer.md +49 -24
  334. package/packages/apra-fleet-se/apra-pm/agents/planner.md +66 -43
  335. package/packages/apra-fleet-se/apra-pm/agents/regression-test-runner.md +101 -78
  336. package/packages/apra-fleet-se/apra-pm/agents/reviewer.md +117 -56
  337. package/packages/apra-fleet-se/apra-pm/agents/schemas/backlog-groomer-output.json +1 -1
  338. package/packages/apra-fleet-se/apra-pm/agents/schemas/doer-output.json +32 -0
  339. package/packages/apra-fleet-se/apra-pm/agents/schemas/harvester-input.json +1 -5
  340. package/packages/apra-fleet-se/apra-pm/agents/schemas/planner-output.json +1 -1
  341. package/packages/apra-fleet-se/apra-pm/agents/schemas/regression-test-runner-output.json +41 -7
  342. package/packages/apra-fleet-se/apra-pm/agents/schemas/reviewer-output.json +62 -3
  343. package/packages/apra-fleet-se/apra-pm/skills/pm/SKILL.md +3 -3
  344. package/packages/apra-fleet-se/apra-pm/skills/pm/index.md +4 -2
  345. package/packages/apra-fleet-se/apra-pm/skills/pm/kb-reconcile.md +29 -14
  346. package/packages/apra-fleet-se/apra-pm/skills/pm/kb-review.md +1 -0
  347. package/packages/apra-fleet-se/apra-pm/skills/pm/sprint.md +5 -5
  348. package/packages/apra-fleet-se/bin/cli.mjs +184 -54
  349. package/packages/apra-fleet-se/bin/serve.mjs +143 -10
  350. package/packages/apra-fleet-se/fleet-sprint/abort.mjs +56 -20
  351. package/packages/apra-fleet-se/fleet-sprint/backlog-role.mjs +93 -0
  352. package/packages/apra-fleet-se/fleet-sprint/beads-children.mjs +208 -53
  353. package/packages/apra-fleet-se/fleet-sprint/beads-identity-check.mjs +576 -33
  354. package/packages/apra-fleet-se/fleet-sprint/beads-identity.mjs +9 -0
  355. package/packages/apra-fleet-se/fleet-sprint/beads-memory-hygiene.mjs +201 -0
  356. package/packages/apra-fleet-se/fleet-sprint/beads-scope.mjs +114 -7
  357. package/packages/apra-fleet-se/fleet-sprint/beads-transitions.mjs +154 -8
  358. package/packages/apra-fleet-se/fleet-sprint/ci-gate.mjs +353 -0
  359. package/packages/apra-fleet-se/fleet-sprint/conflict-ladder.mjs +12 -0
  360. package/packages/apra-fleet-se/fleet-sprint/contracts.mjs +60 -1
  361. package/packages/apra-fleet-se/fleet-sprint/coordination.mjs +25 -2
  362. package/packages/apra-fleet-se/fleet-sprint/dispatch-accounting.mjs +270 -0
  363. package/packages/apra-fleet-se/fleet-sprint/dispatch-failure.mjs +22 -2
  364. package/packages/apra-fleet-se/fleet-sprint/dispatch-role.mjs +205 -16
  365. package/packages/apra-fleet-se/fleet-sprint/docs/README.md +52 -14
  366. package/packages/apra-fleet-se/fleet-sprint/docs/dolt-sync-redesign.md +6 -1
  367. package/packages/apra-fleet-se/fleet-sprint/docs/fleet-sprint-diagram.md +3 -3
  368. package/packages/apra-fleet-se/fleet-sprint/dolt-sync.mjs +339 -20
  369. package/packages/apra-fleet-se/fleet-sprint/errors.mjs +210 -11
  370. package/packages/apra-fleet-se/fleet-sprint/explicit-id-create-guard.mjs +4 -4
  371. package/packages/apra-fleet-se/fleet-sprint/git-sync.mjs +200 -9
  372. package/packages/apra-fleet-se/fleet-sprint/git-topology.mjs +57 -9
  373. package/packages/apra-fleet-se/fleet-sprint/guarded-modules.mjs +53 -4
  374. package/packages/apra-fleet-se/fleet-sprint/kb-hints.mjs +181 -0
  375. package/packages/apra-fleet-se/fleet-sprint/kb-injection.mjs +64 -0
  376. package/packages/apra-fleet-se/fleet-sprint/kb-maintainer.mjs +298 -0
  377. package/packages/apra-fleet-se/fleet-sprint/kb.mjs +1257 -301
  378. package/packages/apra-fleet-se/fleet-sprint/lower-quality.mjs +39 -0
  379. package/packages/apra-fleet-se/fleet-sprint/member-align.mjs +391 -0
  380. package/packages/apra-fleet-se/fleet-sprint/member-call.mjs +374 -0
  381. package/packages/apra-fleet-se/fleet-sprint/member-init-probe.mjs +644 -0
  382. package/packages/apra-fleet-se/fleet-sprint/member-provisioning.mjs +447 -0
  383. package/packages/apra-fleet-se/fleet-sprint/member-sync.mjs +250 -29
  384. package/packages/apra-fleet-se/fleet-sprint/orphan-reclaim.mjs +153 -0
  385. package/packages/apra-fleet-se/fleet-sprint/phases/deploy.mjs +82 -0
  386. package/packages/apra-fleet-se/fleet-sprint/phases/develop.mjs +97 -50
  387. package/packages/apra-fleet-se/fleet-sprint/phases/ensure-sprint-branch.mjs +1 -0
  388. package/packages/apra-fleet-se/fleet-sprint/phases/final-review.mjs +81 -18
  389. package/packages/apra-fleet-se/fleet-sprint/phases/harvest.mjs +43 -11
  390. package/packages/apra-fleet-se/fleet-sprint/phases/integ-test.mjs +6 -6
  391. package/packages/apra-fleet-se/fleet-sprint/phases/plan.mjs +20 -15
  392. package/packages/apra-fleet-se/fleet-sprint/phases/publish-pr.mjs +60 -38
  393. package/packages/apra-fleet-se/fleet-sprint/phases/re-review.mjs +42 -10
  394. package/packages/apra-fleet-se/fleet-sprint/phases/regression-test.mjs +16 -11
  395. package/packages/apra-fleet-se/fleet-sprint/phases/replan.mjs +36 -3
  396. package/packages/apra-fleet-se/fleet-sprint/phases/review.mjs +72 -12
  397. package/packages/apra-fleet-se/fleet-sprint/pr-body.mjs +259 -0
  398. package/packages/apra-fleet-se/fleet-sprint/prompts.mjs +83 -25
  399. package/packages/apra-fleet-se/fleet-sprint/role-policies.mjs +19 -1
  400. package/packages/apra-fleet-se/fleet-sprint/runner.js +834 -142
  401. package/packages/apra-fleet-se/fleet-sprint/se-os-commands.mjs +24 -0
  402. package/packages/apra-fleet-se/fleet-sprint/se-posix.mjs +130 -0
  403. package/packages/apra-fleet-se/fleet-sprint/se-windows.mjs +111 -0
  404. package/packages/apra-fleet-se/fleet-sprint/shell-command-guard.mjs +44 -1
  405. package/packages/apra-fleet-se/fleet-sprint/skills/fleet-sprint-cli/SKILL.md +39 -15
  406. package/packages/apra-fleet-se/fleet-sprint/skills/fleet-supervisor/SKILL.md +84 -30
  407. package/packages/apra-fleet-se/fleet-sprint/sprint-args.mjs +138 -2
  408. package/packages/apra-fleet-se/fleet-sprint/sprint-report.mjs +111 -11
  409. package/packages/apra-fleet-se/fleet-sprint/sprint-state.mjs +22 -0
  410. package/packages/apra-fleet-se/fleet-sprint/usage-limit-controller.mjs +7 -0
  411. package/packages/apra-fleet-se/fleet-sprint/vcs-auth.mjs +180 -14
  412. package/packages/apra-fleet-se/fleet-sprint/vcs-module.mjs +134 -7
  413. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/azure-devops.mjs +99 -0
  414. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/github.mjs +223 -0
  415. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/index.mjs +49 -0
  416. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/shell-helpers.mjs +8 -4
  417. package/packages/apra-fleet-se/fleet-sprint/verify-block.mjs +152 -0
  418. package/packages/apra-fleet-se/fleet-sprint/viewer-extensions.mjs +235 -21
  419. package/packages/apra-fleet-se/package.json +2 -2
  420. package/packages/apra-fleet-se/src/supervisor/api.mjs +919 -0
  421. package/packages/apra-fleet-se/src/supervisor/backlog-member.mjs +332 -0
  422. package/packages/apra-fleet-se/src/supervisor/backlog.mjs +982 -0
  423. package/packages/apra-fleet-se/src/supervisor/beads-identity.mjs +246 -0
  424. package/packages/apra-fleet-se/src/supervisor/beads-view.mjs +438 -0
  425. package/packages/apra-fleet-se/src/supervisor/child-port.mjs +36 -0
  426. package/packages/apra-fleet-se/src/supervisor/dashboard.mjs +1659 -0
  427. package/packages/apra-fleet-se/src/supervisor/dolt-mutex.mjs +350 -0
  428. package/packages/apra-fleet-se/src/supervisor/dolt-orphan-sweep.mjs +338 -0
  429. package/packages/apra-fleet-se/src/supervisor/fleet-members.mjs +279 -0
  430. package/packages/apra-fleet-se/src/supervisor/history-view.mjs +276 -0
  431. package/packages/apra-fleet-se/src/supervisor/history.mjs +328 -0
  432. package/packages/apra-fleet-se/src/supervisor/id-allocator.mjs +521 -0
  433. package/packages/apra-fleet-se/src/supervisor/launch-form.mjs +444 -0
  434. package/packages/apra-fleet-se/src/supervisor/ledger.mjs +629 -0
  435. package/packages/apra-fleet-se/src/supervisor/lib/exec-bd.mjs +303 -0
  436. package/packages/apra-fleet-se/src/supervisor/log-timestamp.mjs +51 -0
  437. package/packages/apra-fleet-se/src/supervisor/log-view.mjs +159 -0
  438. package/packages/apra-fleet-se/src/supervisor/proxy.mjs +474 -0
  439. package/packages/apra-fleet-se/src/supervisor/readopt.mjs +136 -0
  440. package/packages/apra-fleet-se/src/supervisor/reconcile.mjs +263 -0
  441. package/packages/apra-fleet-se/src/supervisor/rename-with-retry.mjs +87 -0
  442. package/packages/apra-fleet-se/src/supervisor/scope-overlap.mjs +327 -0
  443. package/packages/apra-fleet-se/src/supervisor/self-log.mjs +133 -0
  444. package/packages/apra-fleet-se/src/supervisor/server.mjs +399 -0
  445. package/packages/apra-fleet-se/src/supervisor/spawner.mjs +542 -0
  446. package/packages/apra-fleet-se/src/supervisor/sprint-identity.mjs +96 -0
  447. package/packages/apra-fleet-se/src/supervisor/watchdog.mjs +987 -0
  448. package/packages/apra-fleet-workflow/package.json +1 -1
  449. package/packages/apra-fleet-workflow/src/viewer/index.mjs +64 -9
  450. package/packages/apra-fleet-workflow/src/viewer/run-summary.mjs +127 -0
  451. package/packages/apra-fleet-workflow/src/workflow/index.mjs +71 -5
  452. package/packages/apra-fleet-workflow/src/workflow/pricing.mjs +75 -25
  453. package/skills/fleet/permissions.md +9 -0
  454. package/skills/fleet/profiles/tag-kb-reconciler.json +2 -6
  455. package/version.json +1 -1
  456. package/dist/cli/agent-transform.d.ts.map +0 -1
  457. package/dist/cli/agent-transform.js.map +0 -1
  458. package/dist/cli/auth.d.ts.map +0 -1
  459. package/dist/cli/auth.js.map +0 -1
  460. package/dist/cli/config.d.ts.map +0 -1
  461. package/dist/cli/config.js.map +0 -1
  462. package/dist/cli/dolt-install.d.ts.map +0 -1
  463. package/dist/cli/dolt-install.js.map +0 -1
  464. package/dist/cli/install-guard.d.ts.map +0 -1
  465. package/dist/cli/install-guard.js.map +0 -1
  466. package/dist/cli/install.d.ts.map +0 -1
  467. package/dist/cli/install.js.map +0 -1
  468. package/dist/cli/join.d.ts.map +0 -1
  469. package/dist/cli/join.js.map +0 -1
  470. package/dist/cli/kb-commit.d.ts.map +0 -1
  471. package/dist/cli/kb-commit.js.map +0 -1
  472. package/dist/cli/kb-directives.d.ts.map +0 -1
  473. package/dist/cli/kb-directives.js.map +0 -1
  474. package/dist/cli/kb-import.d.ts.map +0 -1
  475. package/dist/cli/kb-import.js.map +0 -1
  476. package/dist/cli/register-member.d.ts.map +0 -1
  477. package/dist/cli/register-member.js.map +0 -1
  478. package/dist/cli/restart.d.ts.map +0 -1
  479. package/dist/cli/restart.js.map +0 -1
  480. package/dist/cli/secret.d.ts.map +0 -1
  481. package/dist/cli/secret.js.map +0 -1
  482. package/dist/cli/spoke.d.ts.map +0 -1
  483. package/dist/cli/spoke.js.map +0 -1
  484. package/dist/cli/start.d.ts.map +0 -1
  485. package/dist/cli/start.js.map +0 -1
  486. package/dist/cli/status.d.ts.map +0 -1
  487. package/dist/cli/status.js.map +0 -1
  488. package/dist/cli/stop.d.ts.map +0 -1
  489. package/dist/cli/stop.js.map +0 -1
  490. package/dist/cli/uninstall.d.ts.map +0 -1
  491. package/dist/cli/uninstall.js.map +0 -1
  492. package/dist/cli/update.d.ts.map +0 -1
  493. package/dist/cli/update.js.map +0 -1
  494. package/dist/cli/watch.d.ts.map +0 -1
  495. package/dist/cli/watch.js.map +0 -1
  496. package/dist/cli/workflow-assets.d.ts.map +0 -1
  497. package/dist/cli/workflow-assets.js.map +0 -1
  498. package/dist/cli/workflow.d.ts.map +0 -1
  499. package/dist/cli/workflow.js.map +0 -1
  500. package/dist/commands/kb-server.d.ts.map +0 -1
  501. package/dist/commands/kb-server.js.map +0 -1
  502. package/dist/delivery-mode.d.ts.map +0 -1
  503. package/dist/delivery-mode.js.map +0 -1
  504. package/dist/hub-service/activity.d.ts.map +0 -1
  505. package/dist/hub-service/activity.js.map +0 -1
  506. package/dist/hub-service/audit-log.d.ts.map +0 -1
  507. package/dist/hub-service/audit-log.js.map +0 -1
  508. package/dist/hub-service/db/pool.d.ts.map +0 -1
  509. package/dist/hub-service/db/pool.js.map +0 -1
  510. package/dist/hub-service/enrollment.d.ts.map +0 -1
  511. package/dist/hub-service/enrollment.js.map +0 -1
  512. package/dist/hub-service/envelope-routes.d.ts.map +0 -1
  513. package/dist/hub-service/envelope-routes.js.map +0 -1
  514. package/dist/hub-service/handlers/installers.d.ts.map +0 -1
  515. package/dist/hub-service/handlers/installers.js.map +0 -1
  516. package/dist/hub-service/http-server.d.ts.map +0 -1
  517. package/dist/hub-service/http-server.js.map +0 -1
  518. package/dist/hub-service/hub-jwt.d.ts.map +0 -1
  519. package/dist/hub-service/hub-jwt.js.map +0 -1
  520. package/dist/hub-service/jwt-revocation.d.ts.map +0 -1
  521. package/dist/hub-service/jwt-revocation.js.map +0 -1
  522. package/dist/hub-service/machines.d.ts.map +0 -1
  523. package/dist/hub-service/machines.js.map +0 -1
  524. package/dist/hub-service/main.d.ts.map +0 -1
  525. package/dist/hub-service/main.js.map +0 -1
  526. package/dist/hub-service/member-tokens.d.ts.map +0 -1
  527. package/dist/hub-service/member-tokens.js.map +0 -1
  528. package/dist/hub-service/member-view.d.ts.map +0 -1
  529. package/dist/hub-service/member-view.js.map +0 -1
  530. package/dist/hub-service/members.d.ts.map +0 -1
  531. package/dist/hub-service/members.js.map +0 -1
  532. package/dist/hub-service/presence.d.ts.map +0 -1
  533. package/dist/hub-service/presence.js.map +0 -1
  534. package/dist/hub-service/project-view.d.ts.map +0 -1
  535. package/dist/hub-service/project-view.js.map +0 -1
  536. package/dist/hub-service/projects.d.ts.map +0 -1
  537. package/dist/hub-service/projects.js.map +0 -1
  538. package/dist/hub-service/relay-queue.d.ts.map +0 -1
  539. package/dist/hub-service/relay-queue.js.map +0 -1
  540. package/dist/hub-service/session-jwt.d.ts.map +0 -1
  541. package/dist/hub-service/session-jwt.js.map +0 -1
  542. package/dist/hub-service/usage.d.ts.map +0 -1
  543. package/dist/hub-service/usage.js.map +0 -1
  544. package/dist/hub-service/users.d.ts.map +0 -1
  545. package/dist/hub-service/users.js.map +0 -1
  546. package/dist/hub-service/workspaces.d.ts.map +0 -1
  547. package/dist/hub-service/workspaces.js.map +0 -1
  548. package/dist/index.d.ts.map +0 -1
  549. package/dist/index.js.map +0 -1
  550. package/dist/onboarding/text.d.ts.map +0 -1
  551. package/dist/onboarding/text.js.map +0 -1
  552. package/dist/os/git-bash-candidates.d.ts.map +0 -1
  553. package/dist/os/git-bash-candidates.js.map +0 -1
  554. package/dist/os/index.d.ts.map +0 -1
  555. package/dist/os/index.js.map +0 -1
  556. package/dist/os/linux.d.ts.map +0 -1
  557. package/dist/os/linux.js.map +0 -1
  558. package/dist/os/macos.d.ts.map +0 -1
  559. package/dist/os/macos.js.map +0 -1
  560. package/dist/os/os-commands.d.ts.map +0 -1
  561. package/dist/os/os-commands.js.map +0 -1
  562. package/dist/os/windows-gitbash.d.ts.map +0 -1
  563. package/dist/os/windows-gitbash.js.map +0 -1
  564. package/dist/os/windows-wrapper.d.ts.map +0 -1
  565. package/dist/os/windows-wrapper.js.map +0 -1
  566. package/dist/os/windows.d.ts.map +0 -1
  567. package/dist/os/windows.js.map +0 -1
  568. package/dist/paths.d.ts.map +0 -1
  569. package/dist/paths.js.map +0 -1
  570. package/dist/providers/agy.d.ts.map +0 -1
  571. package/dist/providers/agy.js.map +0 -1
  572. package/dist/providers/claude.d.ts.map +0 -1
  573. package/dist/providers/claude.js.map +0 -1
  574. package/dist/providers/codex.d.ts.map +0 -1
  575. package/dist/providers/codex.js.map +0 -1
  576. package/dist/providers/copilot.d.ts.map +0 -1
  577. package/dist/providers/copilot.js.map +0 -1
  578. package/dist/providers/email/headers.d.ts.map +0 -1
  579. package/dist/providers/email/headers.js.map +0 -1
  580. package/dist/providers/email/index.d.ts.map +0 -1
  581. package/dist/providers/email/index.js.map +0 -1
  582. package/dist/providers/email/provider.d.ts.map +0 -1
  583. package/dist/providers/email/provider.js.map +0 -1
  584. package/dist/providers/email/sendgrid.d.ts.map +0 -1
  585. package/dist/providers/email/sendgrid.js.map +0 -1
  586. package/dist/providers/email/smtp.d.ts.map +0 -1
  587. package/dist/providers/email/smtp.js.map +0 -1
  588. package/dist/providers/index.d.ts.map +0 -1
  589. package/dist/providers/index.js.map +0 -1
  590. package/dist/providers/none.d.ts.map +0 -1
  591. package/dist/providers/none.js.map +0 -1
  592. package/dist/providers/opencode.d.ts.map +0 -1
  593. package/dist/providers/opencode.js.map +0 -1
  594. package/dist/providers/provider.d.ts.map +0 -1
  595. package/dist/providers/provider.js.map +0 -1
  596. package/dist/services/agent-provisioner.d.ts.map +0 -1
  597. package/dist/services/agent-provisioner.js.map +0 -1
  598. package/dist/services/agy-project.d.ts.map +0 -1
  599. package/dist/services/agy-project.js.map +0 -1
  600. package/dist/services/auth-socket.d.ts.map +0 -1
  601. package/dist/services/auth-socket.js.map +0 -1
  602. package/dist/services/auth-web.d.ts.map +0 -1
  603. package/dist/services/auth-web.js.map +0 -1
  604. package/dist/services/budget-awareness.d.ts.map +0 -1
  605. package/dist/services/budget-awareness.js.map +0 -1
  606. package/dist/services/cloud/activity.d.ts.map +0 -1
  607. package/dist/services/cloud/activity.js.map +0 -1
  608. package/dist/services/cloud/aws.d.ts.map +0 -1
  609. package/dist/services/cloud/aws.js.map +0 -1
  610. package/dist/services/cloud/cost.d.ts.map +0 -1
  611. package/dist/services/cloud/cost.js.map +0 -1
  612. package/dist/services/cloud/idle-manager.d.ts.map +0 -1
  613. package/dist/services/cloud/idle-manager.js.map +0 -1
  614. package/dist/services/cloud/lifecycle.d.ts.map +0 -1
  615. package/dist/services/cloud/lifecycle.js.map +0 -1
  616. package/dist/services/cloud/task-wrapper.d.ts.map +0 -1
  617. package/dist/services/cloud/task-wrapper.js.map +0 -1
  618. package/dist/services/cloud/types.d.ts.map +0 -1
  619. package/dist/services/cloud/types.js.map +0 -1
  620. package/dist/services/cloud-sync.d.ts.map +0 -1
  621. package/dist/services/cloud-sync.js.map +0 -1
  622. package/dist/services/context-admission.d.ts.map +0 -1
  623. package/dist/services/context-admission.js.map +0 -1
  624. package/dist/services/credential-cleanup.d.ts.map +0 -1
  625. package/dist/services/credential-cleanup.js.map +0 -1
  626. package/dist/services/credential-store.d.ts.map +0 -1
  627. package/dist/services/credential-store.js.map +0 -1
  628. package/dist/services/event-bus.d.ts.map +0 -1
  629. package/dist/services/event-bus.js.map +0 -1
  630. package/dist/services/exit-drain.d.ts.map +0 -1
  631. package/dist/services/exit-drain.js.map +0 -1
  632. package/dist/services/file-chunker.d.ts.map +0 -1
  633. package/dist/services/file-chunker.js.map +0 -1
  634. package/dist/services/file-transfer-relay.d.ts.map +0 -1
  635. package/dist/services/file-transfer-relay.js.map +0 -1
  636. package/dist/services/file-transfer.d.ts.map +0 -1
  637. package/dist/services/file-transfer.js.map +0 -1
  638. package/dist/services/git-config.d.ts.map +0 -1
  639. package/dist/services/git-config.js.map +0 -1
  640. package/dist/services/github-app.d.ts.map +0 -1
  641. package/dist/services/github-app.js.map +0 -1
  642. package/dist/services/http-transport.d.ts.map +0 -1
  643. package/dist/services/http-transport.js.map +0 -1
  644. package/dist/services/hub-client.d.ts.map +0 -1
  645. package/dist/services/hub-client.js.map +0 -1
  646. package/dist/services/icons.d.ts.map +0 -1
  647. package/dist/services/icons.js.map +0 -1
  648. package/dist/services/jwt.d.ts.map +0 -1
  649. package/dist/services/jwt.js.map +0 -1
  650. package/dist/services/knowledge/audn.d.ts.map +0 -1
  651. package/dist/services/knowledge/audn.js.map +0 -1
  652. package/dist/services/knowledge/file-hash.d.ts.map +0 -1
  653. package/dist/services/knowledge/file-hash.js.map +0 -1
  654. package/dist/services/knowledge/http-provider.d.ts.map +0 -1
  655. package/dist/services/knowledge/http-provider.js.map +0 -1
  656. package/dist/services/knowledge/kb-config.d.ts.map +0 -1
  657. package/dist/services/knowledge/kb-config.js.map +0 -1
  658. package/dist/services/knowledge/kb-providers.d.ts.map +0 -1
  659. package/dist/services/knowledge/kb-providers.js.map +0 -1
  660. package/dist/services/knowledge/kb-scope-input.d.ts +0 -5
  661. package/dist/services/knowledge/kb-scope-input.d.ts.map +0 -1
  662. package/dist/services/knowledge/kb-scope-input.js +0 -11
  663. package/dist/services/knowledge/kb-scope-input.js.map +0 -1
  664. package/dist/services/knowledge/kb-service.d.ts.map +0 -1
  665. package/dist/services/knowledge/kb-service.js.map +0 -1
  666. package/dist/services/knowledge/path-validation.d.ts.map +0 -1
  667. package/dist/services/knowledge/path-validation.js.map +0 -1
  668. package/dist/services/knowledge/pre-init.d.ts.map +0 -1
  669. package/dist/services/knowledge/pre-init.js.map +0 -1
  670. package/dist/services/knowledge/project-slug.d.ts.map +0 -1
  671. package/dist/services/knowledge/project-slug.js.map +0 -1
  672. package/dist/services/knowledge/require-sqlite-project.d.ts.map +0 -1
  673. package/dist/services/knowledge/require-sqlite-project.js.map +0 -1
  674. package/dist/services/knowledge/sqlite-provider.d.ts.map +0 -1
  675. package/dist/services/knowledge/sqlite-provider.js.map +0 -1
  676. package/dist/services/knowledge/types.d.ts.map +0 -1
  677. package/dist/services/knowledge/types.js.map +0 -1
  678. package/dist/services/known-hosts.d.ts.map +0 -1
  679. package/dist/services/known-hosts.js.map +0 -1
  680. package/dist/services/known-sessions.d.ts.map +0 -1
  681. package/dist/services/known-sessions.js.map +0 -1
  682. package/dist/services/member-home.d.ts.map +0 -1
  683. package/dist/services/member-home.js.map +0 -1
  684. package/dist/services/member-remote-url.d.ts.map +0 -1
  685. package/dist/services/member-remote-url.js.map +0 -1
  686. package/dist/services/model-pricing.d.ts.map +0 -1
  687. package/dist/services/model-pricing.js.map +0 -1
  688. package/dist/services/onboarding.d.ts.map +0 -1
  689. package/dist/services/onboarding.js.map +0 -1
  690. package/dist/services/orphan-recovery.d.ts.map +0 -1
  691. package/dist/services/orphan-recovery.js.map +0 -1
  692. package/dist/services/pending-responses.d.ts.map +0 -1
  693. package/dist/services/pending-responses.js.map +0 -1
  694. package/dist/services/preflight-check.d.ts.map +0 -1
  695. package/dist/services/preflight-check.js.map +0 -1
  696. package/dist/services/registry.d.ts.map +0 -1
  697. package/dist/services/registry.js.map +0 -1
  698. package/dist/services/relay-context.d.ts.map +0 -1
  699. package/dist/services/relay-context.js.map +0 -1
  700. package/dist/services/relay-executor.d.ts.map +0 -1
  701. package/dist/services/relay-executor.js.map +0 -1
  702. package/dist/services/relay-request.d.ts.map +0 -1
  703. package/dist/services/relay-request.js.map +0 -1
  704. package/dist/services/relay-strategy.d.ts.map +0 -1
  705. package/dist/services/relay-strategy.js.map +0 -1
  706. package/dist/services/secret-token.d.ts.map +0 -1
  707. package/dist/services/secret-token.js.map +0 -1
  708. package/dist/services/service-manager/index.d.ts.map +0 -1
  709. package/dist/services/service-manager/index.js.map +0 -1
  710. package/dist/services/service-manager/linux.d.ts.map +0 -1
  711. package/dist/services/service-manager/linux.js.map +0 -1
  712. package/dist/services/service-manager/macos.d.ts.map +0 -1
  713. package/dist/services/service-manager/macos.js.map +0 -1
  714. package/dist/services/service-manager/types.d.ts.map +0 -1
  715. package/dist/services/service-manager/types.js.map +0 -1
  716. package/dist/services/service-manager/windows.d.ts.map +0 -1
  717. package/dist/services/service-manager/windows.js.map +0 -1
  718. package/dist/services/session-registry.d.ts.map +0 -1
  719. package/dist/services/session-registry.js.map +0 -1
  720. package/dist/services/sftp.d.ts.map +0 -1
  721. package/dist/services/sftp.js.map +0 -1
  722. package/dist/services/shell-probe.d.ts.map +0 -1
  723. package/dist/services/shell-probe.js.map +0 -1
  724. package/dist/services/singleton.d.ts.map +0 -1
  725. package/dist/services/singleton.js.map +0 -1
  726. package/dist/services/sprint-coordination.d.ts.map +0 -1
  727. package/dist/services/sprint-coordination.js.map +0 -1
  728. package/dist/services/ssh.d.ts.map +0 -1
  729. package/dist/services/ssh.js.map +0 -1
  730. package/dist/services/stall/find-log-file.d.ts.map +0 -1
  731. package/dist/services/stall/find-log-file.js.map +0 -1
  732. package/dist/services/stall/index.d.ts.map +0 -1
  733. package/dist/services/stall/index.js.map +0 -1
  734. package/dist/services/stall/log-path-resolver.d.ts.map +0 -1
  735. package/dist/services/stall/log-path-resolver.js.map +0 -1
  736. package/dist/services/stall/read-log-tail.d.ts.map +0 -1
  737. package/dist/services/stall/read-log-tail.js.map +0 -1
  738. package/dist/services/stall/stall-detector.d.ts.map +0 -1
  739. package/dist/services/stall/stall-detector.js.map +0 -1
  740. package/dist/services/stall/stall-poller.d.ts.map +0 -1
  741. package/dist/services/stall/stall-poller.js.map +0 -1
  742. package/dist/services/stall/time-utils.d.ts.map +0 -1
  743. package/dist/services/stall/time-utils.js.map +0 -1
  744. package/dist/services/statusline.d.ts.map +0 -1
  745. package/dist/services/statusline.js.map +0 -1
  746. package/dist/services/strategy.d.ts.map +0 -1
  747. package/dist/services/strategy.js.map +0 -1
  748. package/dist/services/substitution-engine.d.ts.map +0 -1
  749. package/dist/services/substitution-engine.js.map +0 -1
  750. package/dist/services/task-cleanup.d.ts.map +0 -1
  751. package/dist/services/task-cleanup.js.map +0 -1
  752. package/dist/services/token-issuer.d.ts.map +0 -1
  753. package/dist/services/token-issuer.js.map +0 -1
  754. package/dist/services/tool-registry.d.ts.map +0 -1
  755. package/dist/services/tool-registry.js.map +0 -1
  756. package/dist/services/update-check.d.ts.map +0 -1
  757. package/dist/services/update-check.js.map +0 -1
  758. package/dist/services/user-config.d.ts.map +0 -1
  759. package/dist/services/user-config.js.map +0 -1
  760. package/dist/services/vcs/azure-devops.d.ts.map +0 -1
  761. package/dist/services/vcs/azure-devops.js.map +0 -1
  762. package/dist/services/vcs/bitbucket.d.ts.map +0 -1
  763. package/dist/services/vcs/bitbucket.js.map +0 -1
  764. package/dist/services/vcs/constants.d.ts.map +0 -1
  765. package/dist/services/vcs/constants.js.map +0 -1
  766. package/dist/services/vcs/github.d.ts.map +0 -1
  767. package/dist/services/vcs/github.js.map +0 -1
  768. package/dist/services/vcs/types.d.ts.map +0 -1
  769. package/dist/services/vcs/types.js.map +0 -1
  770. package/dist/services/version-check.d.ts.map +0 -1
  771. package/dist/services/version-check.js.map +0 -1
  772. package/dist/services/watch/fleet-log.d.ts.map +0 -1
  773. package/dist/services/watch/fleet-log.js.map +0 -1
  774. package/dist/services/watch/project-resolver.d.ts.map +0 -1
  775. package/dist/services/watch/project-resolver.js.map +0 -1
  776. package/dist/services/watch/transcript-formatter.d.ts.map +0 -1
  777. package/dist/services/watch/transcript-formatter.js.map +0 -1
  778. package/dist/smoke-test.d.ts.map +0 -1
  779. package/dist/smoke-test.js.map +0 -1
  780. package/dist/tools/check-status.d.ts.map +0 -1
  781. package/dist/tools/check-status.js.map +0 -1
  782. package/dist/tools/child-id-allocator.d.ts.map +0 -1
  783. package/dist/tools/child-id-allocator.js.map +0 -1
  784. package/dist/tools/cloud-control.d.ts.map +0 -1
  785. package/dist/tools/cloud-control.js.map +0 -1
  786. package/dist/tools/code-intelligence-codebase-memory.d.ts.map +0 -1
  787. package/dist/tools/code-intelligence-codebase-memory.js.map +0 -1
  788. package/dist/tools/code-intelligence-freshness.d.ts.map +0 -1
  789. package/dist/tools/code-intelligence-freshness.js.map +0 -1
  790. package/dist/tools/code-intelligence-gitnexus.d.ts.map +0 -1
  791. package/dist/tools/code-intelligence-gitnexus.js.map +0 -1
  792. package/dist/tools/code-intelligence-kb-enrich.d.ts.map +0 -1
  793. package/dist/tools/code-intelligence-kb-enrich.js.map +0 -1
  794. package/dist/tools/code-intelligence-reindex.d.ts.map +0 -1
  795. package/dist/tools/code-intelligence-reindex.js.map +0 -1
  796. package/dist/tools/code-intelligence-telemetry.d.ts.map +0 -1
  797. package/dist/tools/code-intelligence-telemetry.js.map +0 -1
  798. package/dist/tools/code-intelligence-tests.d.ts.map +0 -1
  799. package/dist/tools/code-intelligence-tests.js.map +0 -1
  800. package/dist/tools/code-intelligence.d.ts.map +0 -1
  801. package/dist/tools/code-intelligence.js.map +0 -1
  802. package/dist/tools/compose-permissions.d.ts.map +0 -1
  803. package/dist/tools/compose-permissions.js.map +0 -1
  804. package/dist/tools/credential-store-delete.d.ts.map +0 -1
  805. package/dist/tools/credential-store-delete.js.map +0 -1
  806. package/dist/tools/credential-store-list.d.ts.map +0 -1
  807. package/dist/tools/credential-store-list.js.map +0 -1
  808. package/dist/tools/credential-store-set.d.ts.map +0 -1
  809. package/dist/tools/credential-store-set.js.map +0 -1
  810. package/dist/tools/credential-store-update.d.ts.map +0 -1
  811. package/dist/tools/credential-store-update.js.map +0 -1
  812. package/dist/tools/dolt-push-mutex.d.ts.map +0 -1
  813. package/dist/tools/dolt-push-mutex.js.map +0 -1
  814. package/dist/tools/execute-command.d.ts.map +0 -1
  815. package/dist/tools/execute-command.js.map +0 -1
  816. package/dist/tools/execute-prompt.d.ts.map +0 -1
  817. package/dist/tools/execute-prompt.js.map +0 -1
  818. package/dist/tools/get-member-model-pricing.d.ts.map +0 -1
  819. package/dist/tools/get-member-model-pricing.js.map +0 -1
  820. package/dist/tools/kb-capture.d.ts.map +0 -1
  821. package/dist/tools/kb-capture.js.map +0 -1
  822. package/dist/tools/kb-context.d.ts.map +0 -1
  823. package/dist/tools/kb-context.js.map +0 -1
  824. package/dist/tools/kb-export.d.ts.map +0 -1
  825. package/dist/tools/kb-export.js.map +0 -1
  826. package/dist/tools/kb-feedback.d.ts.map +0 -1
  827. package/dist/tools/kb-feedback.js.map +0 -1
  828. package/dist/tools/kb-freshness-sweep.d.ts.map +0 -1
  829. package/dist/tools/kb-freshness-sweep.js.map +0 -1
  830. package/dist/tools/kb-harvest.d.ts.map +0 -1
  831. package/dist/tools/kb-harvest.js.map +0 -1
  832. package/dist/tools/kb-import.d.ts.map +0 -1
  833. package/dist/tools/kb-import.js.map +0 -1
  834. package/dist/tools/kb-invalidate.d.ts.map +0 -1
  835. package/dist/tools/kb-invalidate.js.map +0 -1
  836. package/dist/tools/kb-list.d.ts.map +0 -1
  837. package/dist/tools/kb-list.js.map +0 -1
  838. package/dist/tools/kb-promote.d.ts.map +0 -1
  839. package/dist/tools/kb-promote.js.map +0 -1
  840. package/dist/tools/kb-query.d.ts.map +0 -1
  841. package/dist/tools/kb-query.js.map +0 -1
  842. package/dist/tools/kb-reconcile-prefilter.d.ts.map +0 -1
  843. package/dist/tools/kb-reconcile-prefilter.js.map +0 -1
  844. package/dist/tools/kb-resolve-contradiction.d.ts.map +0 -1
  845. package/dist/tools/kb-resolve-contradiction.js.map +0 -1
  846. package/dist/tools/kb-session-prime.d.ts.map +0 -1
  847. package/dist/tools/kb-session-prime.js.map +0 -1
  848. package/dist/tools/kb-setup.d.ts.map +0 -1
  849. package/dist/tools/kb-setup.js.map +0 -1
  850. package/dist/tools/kb-stats.d.ts.map +0 -1
  851. package/dist/tools/kb-stats.js.map +0 -1
  852. package/dist/tools/list-members.d.ts.map +0 -1
  853. package/dist/tools/list-members.js.map +0 -1
  854. package/dist/tools/member-detail.d.ts.map +0 -1
  855. package/dist/tools/member-detail.js.map +0 -1
  856. package/dist/tools/member-reservation.d.ts.map +0 -1
  857. package/dist/tools/member-reservation.js.map +0 -1
  858. package/dist/tools/monitor-task.d.ts.map +0 -1
  859. package/dist/tools/monitor-task.js.map +0 -1
  860. package/dist/tools/provision-auth.d.ts.map +0 -1
  861. package/dist/tools/provision-auth.js.map +0 -1
  862. package/dist/tools/provision-vcs-auth.d.ts.map +0 -1
  863. package/dist/tools/provision-vcs-auth.js.map +0 -1
  864. package/dist/tools/receive-files.d.ts.map +0 -1
  865. package/dist/tools/receive-files.js.map +0 -1
  866. package/dist/tools/register-member.d.ts.map +0 -1
  867. package/dist/tools/register-member.js.map +0 -1
  868. package/dist/tools/remove-member.d.ts.map +0 -1
  869. package/dist/tools/remove-member.js.map +0 -1
  870. package/dist/tools/report-status.d.ts.map +0 -1
  871. package/dist/tools/report-status.js.map +0 -1
  872. package/dist/tools/respond-to-message.d.ts.map +0 -1
  873. package/dist/tools/respond-to-message.js.map +0 -1
  874. package/dist/tools/revoke-vcs-auth.d.ts.map +0 -1
  875. package/dist/tools/revoke-vcs-auth.js.map +0 -1
  876. package/dist/tools/send-email.d.ts.map +0 -1
  877. package/dist/tools/send-email.js.map +0 -1
  878. package/dist/tools/send-files.d.ts.map +0 -1
  879. package/dist/tools/send-files.js.map +0 -1
  880. package/dist/tools/send-message.d.ts.map +0 -1
  881. package/dist/tools/send-message.js.map +0 -1
  882. package/dist/tools/setup-git-app.d.ts.map +0 -1
  883. package/dist/tools/setup-git-app.js.map +0 -1
  884. package/dist/tools/setup-ssh-key.d.ts.map +0 -1
  885. package/dist/tools/setup-ssh-key.js.map +0 -1
  886. package/dist/tools/shutdown-server.d.ts.map +0 -1
  887. package/dist/tools/shutdown-server.js.map +0 -1
  888. package/dist/tools/stop-prompt.d.ts.map +0 -1
  889. package/dist/tools/stop-prompt.js.map +0 -1
  890. package/dist/tools/update-agent-cli.d.ts.map +0 -1
  891. package/dist/tools/update-agent-cli.js.map +0 -1
  892. package/dist/tools/update-member.d.ts.map +0 -1
  893. package/dist/tools/update-member.js.map +0 -1
  894. package/dist/tools/vcs-credential-exec.d.ts.map +0 -1
  895. package/dist/tools/vcs-credential-exec.js.map +0 -1
  896. package/dist/tools/version.d.ts.map +0 -1
  897. package/dist/tools/version.js.map +0 -1
  898. package/dist/types.d.ts.map +0 -1
  899. package/dist/types.js.map +0 -1
  900. package/dist/utils/agent-helpers.d.ts.map +0 -1
  901. package/dist/utils/agent-helpers.js.map +0 -1
  902. package/dist/utils/ansi.d.ts.map +0 -1
  903. package/dist/utils/ansi.js.map +0 -1
  904. package/dist/utils/auth-env.d.ts.map +0 -1
  905. package/dist/utils/auth-env.js.map +0 -1
  906. package/dist/utils/collect-secret.d.ts.map +0 -1
  907. package/dist/utils/collect-secret.js.map +0 -1
  908. package/dist/utils/credential-validation.d.ts.map +0 -1
  909. package/dist/utils/credential-validation.js.map +0 -1
  910. package/dist/utils/crypto.d.ts.map +0 -1
  911. package/dist/utils/crypto.js.map +0 -1
  912. package/dist/utils/deep-merge.d.ts.map +0 -1
  913. package/dist/utils/deep-merge.js.map +0 -1
  914. package/dist/utils/file-permissions.d.ts.map +0 -1
  915. package/dist/utils/file-permissions.js.map +0 -1
  916. package/dist/utils/gpu-parser.d.ts.map +0 -1
  917. package/dist/utils/gpu-parser.js.map +0 -1
  918. package/dist/utils/log-helpers.d.ts.map +0 -1
  919. package/dist/utils/log-helpers.js.map +0 -1
  920. package/dist/utils/oob-timeout.d.ts.map +0 -1
  921. package/dist/utils/oob-timeout.js.map +0 -1
  922. package/dist/utils/opencode-model-validation.d.ts.map +0 -1
  923. package/dist/utils/opencode-model-validation.js.map +0 -1
  924. package/dist/utils/pid-helpers.d.ts.map +0 -1
  925. package/dist/utils/pid-helpers.js.map +0 -1
  926. package/dist/utils/platform.d.ts.map +0 -1
  927. package/dist/utils/platform.js.map +0 -1
  928. package/dist/utils/process-utils.d.ts.map +0 -1
  929. package/dist/utils/process-utils.js.map +0 -1
  930. package/dist/utils/prompt-errors.d.ts.map +0 -1
  931. package/dist/utils/prompt-errors.js.map +0 -1
  932. package/dist/utils/resolve-member.d.ts.map +0 -1
  933. package/dist/utils/resolve-member.js.map +0 -1
  934. package/dist/utils/secure-input.d.ts.map +0 -1
  935. package/dist/utils/secure-input.js.map +0 -1
  936. package/dist/utils/session-caller.d.ts.map +0 -1
  937. package/dist/utils/session-caller.js.map +0 -1
  938. package/dist/utils/shell-escape.d.ts.map +0 -1
  939. package/dist/utils/shell-escape.js.map +0 -1
  940. package/dist/utils/skill-matrix.d.ts.map +0 -1
  941. package/dist/utils/skill-matrix.js.map +0 -1
  942. package/dist/utils/ssh-error-messages.d.ts.map +0 -1
  943. package/dist/utils/ssh-error-messages.js.map +0 -1
  944. package/dist/utils/vcs-provider-detect.d.ts.map +0 -1
  945. package/dist/utils/vcs-provider-detect.js.map +0 -1
  946. package/dist/utils/work-folder-validation.d.ts.map +0 -1
  947. package/dist/utils/work-folder-validation.js.map +0 -1
  948. package/dist/utils/workspace-trust.d.ts.map +0 -1
  949. package/dist/utils/workspace-trust.js.map +0 -1
  950. package/dist/version.d.ts.map +0 -1
  951. package/dist/version.js.map +0 -1
@@ -2,12 +2,20 @@
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
@@ -65,6 +73,8 @@
65
73
  * @typedef {Object} PermissionDenialItem
66
74
  * @property {string} action - Provider permission action, e.g. 'command', 'read_file', 'mcp'.
67
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).
68
78
  */
69
79
 
70
80
  /**
@@ -75,9 +85,18 @@
75
85
  * @property {string[]} suggestedGrants - compose_permissions `grant` values that would allow the
76
86
  * denied calls, primary first (for an agy command or unsandboxed denial, on any OS, a
77
87
  * `Bash(<cmd>:*)` prefix grant, then the exact command as the narrow alternative); empty when no
78
- * canonical mapping exists.
88
+ * canonical mapping exists, and always empty when `healable` is false (never grant those).
79
89
  * @property {string} hint - One-line remediation.
80
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.
81
100
  */
82
101
 
83
102
  /**
@@ -89,12 +108,28 @@
89
108
  * @property {boolean} [isError] - true on any failure path; absent/false on success.
90
109
  * @property {string} [reason] - Machine-readable failure/status classification, e.g.
91
110
  * 'busy' | 'nonzero_exit' | 'max_turns_exhausted' | 'empty_response' | 'overloaded' |
92
- * 'usage_limit' | 'workspace_not_trusted' | 'session_not_found' | 'permission_denied' | ...
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) | ...
93
119
  * @property {PermissionDenied} [permissionDenied] - Present when `reason === 'permission_denied'`:
94
- * the member CLI refused tool calls for lack of a grant (AGY headless mode auto-denies them
95
- * and exits 0, which used to surface as 'empty_response'). Pass `suggestedGrants` to
96
- * compose_permissions `grant` to heal it; read it with {@link permissionDenialOf}. Any partial
97
- * reply is in `response`.
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.
98
133
  * @property {UsageLimitSignal} [usageLimit] - Present when `reason === 'usage_limit'`
99
134
  * (apra-fleet-hzeb.2): the provider's detectUsageLimit() signal verbatim -- a 429/quota
100
135
  * exhaustion that a fresh session cannot cure, so execute_prompt returns this INSTEAD of
@@ -102,16 +137,62 @@
102
137
  * paths. Read `usageLimit.resumeAt`/`resumeAtSource` to schedule a resume rather than
103
138
  * re-parsing the failure text; `packages/apra-fleet-workflow` forwards this unchanged onto
104
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`.
105
145
  * @property {string} [response] - The LLM's actual reply text on success.
106
146
  * @property {string} [sessionId] - The session id this dispatch landed on, when known --
107
- * present on success AND on a 'usage_limit'/'max_turns_exhausted' failure so the SAME
108
- * session can be resumed later instead of losing context to a fresh one.
109
- * @property {{input_tokens:number, output_tokens:number, total_tokens:number}} [usage]
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.
110
188
  */
111
189
 
112
190
  /**
113
191
  * @typedef {Object} ExecuteCommandOptions
114
- * @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: ...`).
115
196
  * @property {boolean} [long_running] - Run as background task. Supported on linux and windows
116
197
  * members. Windows launches the task detached via `Invoke-CimMethod Win32_Process.Create`
117
198
  * (WMI provider host / session 0), independent of the SSH session's job object, since a plain
@@ -132,6 +213,50 @@
132
213
  * cannot cancel a job already accepted by the remote fleet-server (see client.mjs).
133
214
  */
134
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
+
135
260
  /**
136
261
  * @typedef {Object} ListMembersOptions
137
262
  * @property {"compact" | "json"} [format] - Output format
@@ -141,6 +266,7 @@
141
266
  /**
142
267
  * @typedef {Object} FleetStatusOptions
143
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.
144
270
  */
145
271
 
146
272
  /**
@@ -163,7 +289,7 @@
163
289
  /**
164
290
  * @typedef {Object} RegisterMemberOptions
165
291
  * @property {string} friendly_name - Human-friendly name for this member (required)
166
- * @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.
167
293
  * @property {"local" | "remote"} [member_type] - Member type (default: "remote")
168
294
  * @property {string} [host] - IP address or hostname of the remote machine
169
295
  * @property {string} [username] - SSH username
@@ -189,7 +315,9 @@
189
315
  * @property {string} [category] - Optional group label
190
316
  * @property {string[]} [tags] - Optional list of free-form labels
191
317
  * @property {"false" | "auto" | "dangerous"} [unattended] - Permission mode for unattended execution
192
- * @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.
193
321
  * @property {"gitbash" | "pwsh7" | "powershell5"} [shell] - Override the probed Windows shell for this member. Windows members only -- ignored for non-windows members.
194
322
  */
195
323
 
@@ -197,8 +325,9 @@
197
325
  * @typedef {Object} UpdateMemberOptions
198
326
  * @property {string} [member_id] - UUID of the member
199
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.
200
329
  * @property {string} [friendly_name] - New friendly name
201
- * @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.
202
331
  * @property {string} [host] - New host
203
332
  * @property {string} [username] - New SSH username
204
333
  * @property {number} [port] - New SSH port
@@ -221,12 +350,41 @@
221
350
  * @property {"codebase-memory" | "gitnexus" | "none"} [code_intel_provider] - Change the code-intelligence provider for this member
222
351
  * @property {string} [category] - Group label
223
352
  * @property {string[]} [tags] - Free-form labels
224
- * @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)
225
355
  * @property {boolean} [unreservable] - Mark/unmark this member as shared/never exclusively reservable
226
356
  * @property {"gitbash" | "pwsh7" | "powershell5"} [shell] - Override the probed Windows shell for this member. Windows members only -- ignored for non-windows members.
227
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.
228
358
  */
229
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
386
+ */
387
+
230
388
  /**
231
389
  * Structured result returned by memberDetail() when called with format: 'json'
232
390
  * (src/tools/member-detail.ts). When format is 'compact' (the default), memberDetail()
@@ -250,12 +408,23 @@
250
408
  * minted token carries a given permission (e.g. GitHub's 'workflows', required to push any
251
409
  * .github/workflows/** change) must read THIS, not their own provisioning default -- the two differ
252
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.
253
415
  * @property {Object} connectivity - Connectivity check result (status, latencyMs, auth, keyPath, or error)
254
416
  * @property {boolean} [offline] - Set when the member could not be reached
255
417
  * @property {string} llmProvider - LLM provider for this member (default: "claude")
256
418
  * @property {string|null} [agyProjectId] - agy members only: id of the member's own agy project
257
419
  * (~/.gemini/config/projects/<id>.json), passed as `--project <id>` on every dispatch; null until
258
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.
259
428
  * @property {Object} [llm_cli] - LLM CLI info: { version, auth }
260
429
  * @property {Object|string} [tokenUsage] - Cumulative token usage, or "compute only" for llmProvider "none"
261
430
  * @property {Object} [session] - Session info: { id, lastActivity, lastLlmActivityAt, status, idleSecs }
@@ -306,9 +475,18 @@
306
475
  * @typedef {Object} ProvisionLlmAuthOptions
307
476
  * @property {string} [member_id] - UUID of the member
308
477
  * @property {string} [member_name] - Friendly name of the member
309
- * @property {string} [api_key] - AI provider API key. If omitted, the local OAuth
310
- * session is copied to the member instead. Supports {{secret.NAME}} token --
311
- * 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.
312
490
  */
313
491
 
314
492
  /**
@@ -327,7 +505,9 @@
327
505
  * @property {string} [label] - Credential label provision_vcs_auth deployed the helper under
328
506
  * (it defaults to the provider name there, e.g. "github" or "azure-devops"). Omit for the
329
507
  * unlabelled helper.
330
- * @property {number} [timeout_s] - Timeout in seconds for the command (default: 120).
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.
331
511
  */
332
512
 
333
513
  /**
@@ -358,7 +538,11 @@
358
538
  * "secret_variable_denied" | "secret_variable_expired" | "oauth_not_supported" |
359
539
  * "oauth_token_expired_no_refresh" | "oauth_credential_file_missing" |
360
540
  * "oauth_credential_write_failed" | "oauth_settings_merge_failed" | "oauth_copy_failed" |
361
- * "oob_cancelled"} reason - Machine-readable outcome code. Branch on this, never on the text.
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).
362
546
  * @property {string|null} provider - The resolved ProviderAdapter's own name (claude, codex,
363
547
  * copilot, agy, opencode or none -- there is no gemini adapter), null when unresolved.
364
548
  * @property {string|null} credentialLabel - What was deployed, never the secret: the env var
@@ -480,6 +664,86 @@
480
664
  * shell-chaining metacharacter (| ; && backtick $() are rejected outright,
481
665
  * for every caller.
482
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.
483
747
  */
484
748
 
485
749
  /**
@@ -577,6 +841,34 @@ export function parseToolJson(result) {
577
841
 
578
842
  const isStringArray = (v) => Array.isArray(v) && v.every((s) => typeof s === 'string');
579
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
+
580
872
  /**
581
873
  * Typed read of an execute_prompt permission denial. Accepts the raw executePrompt()
582
874
  * result or its `structuredContent`; returns the {@link PermissionDenied} block when
@@ -594,13 +886,106 @@ export function permissionDenialOf(result) {
594
886
  if (!Array.isArray(d.denials) || !d.denials.every((x) => x && typeof x.action === 'string' && (x.target === undefined || typeof x.target === 'string'))) return null;
595
887
  return {
596
888
  actions: [...d.actions],
597
- denials: d.denials.map((x) => (x.target === undefined ? { action: x.action } : { action: x.action, target: x.target })),
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
+ })),
598
894
  suggestedGrants: [...d.suggestedGrants],
599
895
  hint: d.hint,
600
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' } : {}),
601
900
  };
602
901
  }
603
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
+
604
989
  export class ApraFleet {
605
990
  /**
606
991
  * @param {{ callTool: (name: string, args: Record<string, any>, opts?: { timeoutMs?: number, signal?: AbortSignal }) => Promise<any> }} mcpClient
@@ -610,7 +995,9 @@ export class ApraFleet {
610
995
  }
611
996
 
612
997
  /**
613
- * 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.
614
1001
  * @param {ExecutePromptOptions} options
615
1002
  * @returns {Promise<{content?: {type: string, text: string}[], structuredContent?: ExecutePromptStructured}>}
616
1003
  * the raw callTool() result -- see the {@link ExecutePromptStructured} typedef above
@@ -627,6 +1014,9 @@ export class ApraFleet {
627
1014
  /**
628
1015
  * Run a shell command on a member.
629
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}.
630
1020
  */
631
1021
  async executeCommand(options) {
632
1022
  const { timeoutMs, signal, ...payload } = options;
@@ -654,7 +1044,7 @@ export class ApraFleet {
654
1044
 
655
1045
  /**
656
1046
  * Get detailed status for one member: connectivity, session, work folder, provider, registered shell (Windows).
657
- * @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
658
1048
  * @returns {Promise<string|MemberDetailResult>} A compact text summary when format is
659
1049
  * "compact" (default), or the structured MemberDetailResult object when format is "json".
660
1050
  */
@@ -665,6 +1055,7 @@ export class ApraFleet {
665
1055
  /**
666
1056
  * Get a member's cheap/standard/premium tier resolved to a concrete
667
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}.
668
1059
  * @param {{ member_id?: string, member_name?: string }} options
669
1060
  */
670
1061
  async getMemberModelPricing(options) {
@@ -696,7 +1087,10 @@ export class ApraFleet {
696
1087
  }
697
1088
 
698
1089
  /**
699
- * 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).
700
1094
  * @param {UpdateMemberOptions} options
701
1095
  */
702
1096
  async updateMember(options) {
@@ -704,7 +1098,12 @@ export class ApraFleet {
704
1098
  }
705
1099
 
706
1100
  /**
707
- * 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.
708
1107
  * @param {RemoveMemberOptions} options
709
1108
  */
710
1109
  async removeMember(options) {
@@ -784,13 +1183,73 @@ export class ApraFleet {
784
1183
  }
785
1184
 
786
1185
  /**
787
- * Compose and deliver a scoped permission profile to a member.
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.
788
1195
  * @param {ComposePermissionsOptions} options
789
1196
  */
790
1197
  async composePermissions(options) {
791
1198
  return this.mcpClient.callTool('compose_permissions', options);
792
1199
  }
793
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
+
794
1253
  /**
795
1254
  * Convert a remote member from password to SSH key authentication.
796
1255
  * @param {SetupSshKeyOptions} options
@@ -820,6 +1279,75 @@ export class ApraFleet {
820
1279
  return this.mcpClient.callTool('credential_store_set', options);
821
1280
  }
822
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
+
823
1351
  /**
824
1352
  * List stored credentials (names and metadata only -- no values).
825
1353
  * The result payload is a JSON array of { name, scope, ... } entries;
@@ -871,6 +1399,9 @@ export class ApraFleet {
871
1399
  * src/tools/child-id-allocator.ts). Mints globally-distinct child ids under
872
1400
  * a shared parent for sprints launched WITHOUT a supervisor, so two sprints
873
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.
874
1405
  *
875
1406
  * @param {{ action: 'allocate'|'confirm'|'release'|'status',
876
1407
  * parent_id?: string, token?: string, sprint_id?: string,