@apralabs/apra-fleet 0.4.1 → 0.4.2

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 (276) hide show
  1. package/README.md +16 -8
  2. package/dist/agents/backlog-groomer.md +17 -21
  3. package/dist/agents/ci-watcher.md +3 -0
  4. package/dist/agents/deployer.md +22 -44
  5. package/dist/agents/doer.md +131 -132
  6. package/dist/agents/harvester.md +20 -32
  7. package/dist/agents/integ-test-runner.md +81 -113
  8. package/dist/agents/kb-reconciler.md +31 -42
  9. package/dist/agents/plan-reviewer.md +32 -44
  10. package/dist/agents/planner.md +51 -63
  11. package/dist/agents/regression-test-runner.md +65 -80
  12. package/dist/agents/reviewer.md +56 -83
  13. package/dist/agents/schemas/integ-test-runner-output.json +1 -1
  14. package/dist/agents/schemas/regression-test-runner-output.json +4 -17
  15. package/dist/cli/auth.d.ts.map +1 -1
  16. package/dist/cli/auth.js +1 -2
  17. package/dist/cli/auth.js.map +1 -1
  18. package/dist/cli/config.d.ts +3 -3
  19. package/dist/cli/config.d.ts.map +1 -1
  20. package/dist/cli/config.js +4 -13
  21. package/dist/cli/config.js.map +1 -1
  22. package/dist/cli/install.d.ts.map +1 -1
  23. package/dist/cli/install.js +5 -39
  24. package/dist/cli/install.js.map +1 -1
  25. package/dist/cli/register-member.js +1 -1
  26. package/dist/cli/start.d.ts.map +1 -1
  27. package/dist/cli/start.js +7 -0
  28. package/dist/cli/start.js.map +1 -1
  29. package/dist/cli/uninstall.d.ts.map +1 -1
  30. package/dist/cli/uninstall.js +5 -3
  31. package/dist/cli/uninstall.js.map +1 -1
  32. package/dist/cli/watch.d.ts +26 -3
  33. package/dist/cli/watch.d.ts.map +1 -1
  34. package/dist/cli/watch.js +41 -9
  35. package/dist/cli/watch.js.map +1 -1
  36. package/dist/os/git-bash-candidates.d.ts +35 -0
  37. package/dist/os/git-bash-candidates.d.ts.map +1 -0
  38. package/dist/os/git-bash-candidates.js +46 -0
  39. package/dist/os/git-bash-candidates.js.map +1 -0
  40. package/dist/os/index.d.ts +13 -4
  41. package/dist/os/index.d.ts.map +1 -1
  42. package/dist/os/index.js +17 -2
  43. package/dist/os/index.js.map +1 -1
  44. package/dist/os/linux.js +1 -1
  45. package/dist/os/linux.js.map +1 -1
  46. package/dist/os/os-commands.d.ts +7 -0
  47. package/dist/os/os-commands.d.ts.map +1 -1
  48. package/dist/os/os-commands.js.map +1 -1
  49. package/dist/os/windows-gitbash.d.ts +93 -0
  50. package/dist/os/windows-gitbash.d.ts.map +1 -0
  51. package/dist/os/windows-gitbash.js +244 -0
  52. package/dist/os/windows-gitbash.js.map +1 -0
  53. package/dist/os/windows.d.ts.map +1 -1
  54. package/dist/os/windows.js +27 -5
  55. package/dist/os/windows.js.map +1 -1
  56. package/dist/providers/agy.d.ts +3 -2
  57. package/dist/providers/agy.d.ts.map +1 -1
  58. package/dist/providers/agy.js +11 -2
  59. package/dist/providers/agy.js.map +1 -1
  60. package/dist/providers/claude.d.ts +3 -2
  61. package/dist/providers/claude.d.ts.map +1 -1
  62. package/dist/providers/claude.js +22 -3
  63. package/dist/providers/claude.js.map +1 -1
  64. package/dist/providers/codex.d.ts +3 -2
  65. package/dist/providers/codex.d.ts.map +1 -1
  66. package/dist/providers/codex.js +5 -2
  67. package/dist/providers/codex.js.map +1 -1
  68. package/dist/providers/copilot.d.ts +3 -2
  69. package/dist/providers/copilot.d.ts.map +1 -1
  70. package/dist/providers/copilot.js +7 -2
  71. package/dist/providers/copilot.js.map +1 -1
  72. package/dist/providers/index.d.ts +0 -1
  73. package/dist/providers/index.d.ts.map +1 -1
  74. package/dist/providers/index.js +0 -3
  75. package/dist/providers/index.js.map +1 -1
  76. package/dist/providers/none.d.ts +3 -2
  77. package/dist/providers/none.d.ts.map +1 -1
  78. package/dist/providers/none.js +5 -2
  79. package/dist/providers/none.js.map +1 -1
  80. package/dist/providers/opencode.d.ts +3 -2
  81. package/dist/providers/opencode.d.ts.map +1 -1
  82. package/dist/providers/opencode.js +5 -2
  83. package/dist/providers/opencode.js.map +1 -1
  84. package/dist/providers/provider.d.ts +16 -7
  85. package/dist/providers/provider.d.ts.map +1 -1
  86. package/dist/providers/provider.js +2 -2
  87. package/dist/providers/provider.js.map +1 -1
  88. package/dist/services/agent-provisioner.js +2 -2
  89. package/dist/services/agent-provisioner.js.map +1 -1
  90. package/dist/services/cloud/activity.js +2 -2
  91. package/dist/services/cloud/activity.js.map +1 -1
  92. package/dist/services/context-admission.d.ts.map +1 -1
  93. package/dist/services/context-admission.js +9 -7
  94. package/dist/services/context-admission.js.map +1 -1
  95. package/dist/services/credential-cleanup.d.ts.map +1 -1
  96. package/dist/services/credential-cleanup.js +22 -3
  97. package/dist/services/credential-cleanup.js.map +1 -1
  98. package/dist/services/member-home.d.ts +1 -1
  99. package/dist/services/member-home.d.ts.map +1 -1
  100. package/dist/services/member-home.js +15 -12
  101. package/dist/services/member-home.js.map +1 -1
  102. package/dist/services/model-pricing.d.ts.map +1 -1
  103. package/dist/services/model-pricing.js +0 -5
  104. package/dist/services/model-pricing.js.map +1 -1
  105. package/dist/services/orphan-recovery.d.ts +6 -3
  106. package/dist/services/orphan-recovery.d.ts.map +1 -1
  107. package/dist/services/orphan-recovery.js +17 -14
  108. package/dist/services/orphan-recovery.js.map +1 -1
  109. package/dist/services/preflight-check.js +2 -2
  110. package/dist/services/preflight-check.js.map +1 -1
  111. package/dist/services/shell-probe.d.ts +131 -0
  112. package/dist/services/shell-probe.d.ts.map +1 -0
  113. package/dist/services/shell-probe.js +210 -0
  114. package/dist/services/shell-probe.js.map +1 -0
  115. package/dist/services/singleton.d.ts +2 -0
  116. package/dist/services/singleton.d.ts.map +1 -1
  117. package/dist/services/singleton.js +1 -1
  118. package/dist/services/singleton.js.map +1 -1
  119. package/dist/services/ssh.js +2 -2
  120. package/dist/services/ssh.js.map +1 -1
  121. package/dist/services/stall/find-log-file.d.ts.map +1 -1
  122. package/dist/services/stall/find-log-file.js +22 -16
  123. package/dist/services/stall/find-log-file.js.map +1 -1
  124. package/dist/services/stall/read-log-tail.d.ts.map +1 -1
  125. package/dist/services/stall/read-log-tail.js +6 -5
  126. package/dist/services/stall/read-log-tail.js.map +1 -1
  127. package/dist/services/stall/stall-poller.d.ts.map +1 -1
  128. package/dist/services/stall/stall-poller.js +35 -42
  129. package/dist/services/stall/stall-poller.js.map +1 -1
  130. package/dist/services/strategy.d.ts +9 -0
  131. package/dist/services/strategy.d.ts.map +1 -1
  132. package/dist/services/strategy.js +40 -6
  133. package/dist/services/strategy.js.map +1 -1
  134. package/dist/services/user-config.js +1 -1
  135. package/dist/services/user-config.js.map +1 -1
  136. package/dist/services/vcs/azure-devops.d.ts +1 -1
  137. package/dist/services/vcs/azure-devops.d.ts.map +1 -1
  138. package/dist/services/vcs/azure-devops.js +105 -10
  139. package/dist/services/vcs/azure-devops.js.map +1 -1
  140. package/dist/services/vcs/bitbucket.d.ts.map +1 -1
  141. package/dist/services/vcs/bitbucket.js +16 -0
  142. package/dist/services/vcs/bitbucket.js.map +1 -1
  143. package/dist/services/vcs/github.d.ts.map +1 -1
  144. package/dist/services/vcs/github.js +24 -0
  145. package/dist/services/vcs/github.js.map +1 -1
  146. package/dist/services/vcs/types.d.ts +123 -2
  147. package/dist/services/vcs/types.d.ts.map +1 -1
  148. package/dist/skills/fleet-sprint-cli/SKILL.md +2 -1
  149. package/dist/skills/pm/SKILL.md +0 -1
  150. package/dist/skills/pm/cost.md +0 -1
  151. package/dist/skills/pm/fleet-addendum.md +0 -1
  152. package/dist/tools/check-status.js +3 -3
  153. package/dist/tools/check-status.js.map +1 -1
  154. package/dist/tools/cloud-control.js +2 -2
  155. package/dist/tools/cloud-control.js.map +1 -1
  156. package/dist/tools/compose-permissions.d.ts.map +1 -1
  157. package/dist/tools/compose-permissions.js +37 -24
  158. package/dist/tools/compose-permissions.js.map +1 -1
  159. package/dist/tools/execute-command.d.ts.map +1 -1
  160. package/dist/tools/execute-command.js +28 -12
  161. package/dist/tools/execute-command.js.map +1 -1
  162. package/dist/tools/execute-prompt.d.ts.map +1 -1
  163. package/dist/tools/execute-prompt.js +55 -18
  164. package/dist/tools/execute-prompt.js.map +1 -1
  165. package/dist/tools/list-members.d.ts.map +1 -1
  166. package/dist/tools/list-members.js +6 -2
  167. package/dist/tools/list-members.js.map +1 -1
  168. package/dist/tools/member-detail.d.ts.map +1 -1
  169. package/dist/tools/member-detail.js +5 -3
  170. package/dist/tools/member-detail.js.map +1 -1
  171. package/dist/tools/member-reservation.d.ts.map +1 -1
  172. package/dist/tools/member-reservation.js +13 -1
  173. package/dist/tools/member-reservation.js.map +1 -1
  174. package/dist/tools/monitor-task.d.ts.map +1 -1
  175. package/dist/tools/monitor-task.js +17 -2
  176. package/dist/tools/monitor-task.js.map +1 -1
  177. package/dist/tools/provision-auth.js +5 -5
  178. package/dist/tools/provision-auth.js.map +1 -1
  179. package/dist/tools/provision-vcs-auth.d.ts +5 -2
  180. package/dist/tools/provision-vcs-auth.d.ts.map +1 -1
  181. package/dist/tools/provision-vcs-auth.js +58 -52
  182. package/dist/tools/provision-vcs-auth.js.map +1 -1
  183. package/dist/tools/register-member.d.ts +18 -12
  184. package/dist/tools/register-member.d.ts.map +1 -1
  185. package/dist/tools/register-member.js +42 -4
  186. package/dist/tools/register-member.js.map +1 -1
  187. package/dist/tools/remove-member.js +2 -2
  188. package/dist/tools/remove-member.js.map +1 -1
  189. package/dist/tools/revoke-vcs-auth.js +2 -2
  190. package/dist/tools/revoke-vcs-auth.js.map +1 -1
  191. package/dist/tools/setup-ssh-key.d.ts.map +1 -1
  192. package/dist/tools/setup-ssh-key.js +2 -1
  193. package/dist/tools/setup-ssh-key.js.map +1 -1
  194. package/dist/tools/stop-prompt.js +2 -2
  195. package/dist/tools/stop-prompt.js.map +1 -1
  196. package/dist/tools/update-agent-cli.js +2 -2
  197. package/dist/tools/update-agent-cli.js.map +1 -1
  198. package/dist/tools/update-member.d.ts +18 -12
  199. package/dist/tools/update-member.d.ts.map +1 -1
  200. package/dist/tools/update-member.js +18 -1
  201. package/dist/tools/update-member.js.map +1 -1
  202. package/dist/types.d.ts +11 -1
  203. package/dist/types.d.ts.map +1 -1
  204. package/dist/utils/agent-helpers.d.ts +36 -0
  205. package/dist/utils/agent-helpers.d.ts.map +1 -1
  206. package/dist/utils/agent-helpers.js +39 -1
  207. package/dist/utils/agent-helpers.js.map +1 -1
  208. package/dist/utils/platform.d.ts +7 -0
  209. package/dist/utils/platform.d.ts.map +1 -1
  210. package/dist/utils/platform.js +11 -1
  211. package/dist/utils/platform.js.map +1 -1
  212. package/dist/utils/workspace-trust.d.ts.map +1 -1
  213. package/dist/utils/workspace-trust.js +5 -1
  214. package/dist/utils/workspace-trust.js.map +1 -1
  215. package/dist/workflows/auto-sprint.js +4 -17
  216. package/package.json +2 -2
  217. package/packages/apra-fleet-client/src/client/api.mjs +92 -3
  218. package/packages/apra-fleet-se/apra-pm/agents/backlog-groomer.md +17 -21
  219. package/packages/apra-fleet-se/apra-pm/agents/ci-watcher.md +3 -0
  220. package/packages/apra-fleet-se/apra-pm/agents/deployer.md +22 -44
  221. package/packages/apra-fleet-se/apra-pm/agents/doer.md +131 -132
  222. package/packages/apra-fleet-se/apra-pm/agents/harvester.md +20 -32
  223. package/packages/apra-fleet-se/apra-pm/agents/integ-test-runner.md +81 -113
  224. package/packages/apra-fleet-se/apra-pm/agents/kb-reconciler.md +31 -42
  225. package/packages/apra-fleet-se/apra-pm/agents/plan-reviewer.md +32 -44
  226. package/packages/apra-fleet-se/apra-pm/agents/planner.md +51 -63
  227. package/packages/apra-fleet-se/apra-pm/agents/regression-test-runner.md +65 -80
  228. package/packages/apra-fleet-se/apra-pm/agents/reviewer.md +56 -83
  229. package/packages/apra-fleet-se/apra-pm/agents/schemas/integ-test-runner-output.json +1 -1
  230. package/packages/apra-fleet-se/apra-pm/agents/schemas/regression-test-runner-output.json +4 -17
  231. package/packages/apra-fleet-se/apra-pm/skills/pm/SKILL.md +0 -1
  232. package/packages/apra-fleet-se/apra-pm/skills/pm/cost.md +0 -1
  233. package/packages/apra-fleet-se/apra-pm/skills/pm/fleet-addendum.md +0 -1
  234. package/packages/apra-fleet-se/bin/cli.mjs +132 -3
  235. package/packages/apra-fleet-se/bin/serve.mjs +36 -1
  236. package/packages/apra-fleet-se/fleet-sprint/contracts.mjs +151 -33
  237. package/packages/apra-fleet-se/fleet-sprint/docs/README.md +22 -7
  238. package/packages/apra-fleet-se/fleet-sprint/docs/dolt-manual-recovery-verified.md +10 -8
  239. package/packages/apra-fleet-se/fleet-sprint/docs/dolt-sync-redesign.md +9 -4
  240. package/packages/apra-fleet-se/fleet-sprint/docs/escalate-to-llm-design.md +2 -2
  241. package/packages/apra-fleet-se/fleet-sprint/docs/shared-orchestrator-reservation-design.md +12 -12
  242. package/packages/apra-fleet-se/fleet-sprint/docs/stabilization-log.md +14 -4
  243. package/packages/apra-fleet-se/fleet-sprint/dolt-settle.mjs +275 -99
  244. package/packages/apra-fleet-se/fleet-sprint/dolt-sync.mjs +67 -16
  245. package/packages/apra-fleet-se/fleet-sprint/errors.mjs +41 -0
  246. package/packages/apra-fleet-se/fleet-sprint/runner.js +1140 -209
  247. package/packages/apra-fleet-se/fleet-sprint/se-os-commands.mjs +134 -0
  248. package/packages/apra-fleet-se/fleet-sprint/se-posix.mjs +154 -0
  249. package/packages/apra-fleet-se/fleet-sprint/se-windows-gitbash.mjs +97 -0
  250. package/packages/apra-fleet-se/fleet-sprint/se-windows.mjs +143 -0
  251. package/packages/apra-fleet-se/fleet-sprint/skills/fleet-sprint-cli/SKILL.md +2 -1
  252. package/packages/apra-fleet-se/fleet-sprint/vcs-module.mjs +51 -0
  253. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/azure-devops.mjs +657 -12
  254. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/dolt.mjs +33 -4
  255. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/github.mjs +60 -43
  256. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/index.mjs +205 -2
  257. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/shell-helpers.mjs +164 -0
  258. package/packages/apra-fleet-se/fleet-sprint/viewer-extensions.mjs +92 -37
  259. package/packages/apra-fleet-workflow/src/viewer/index.mjs +167 -1
  260. package/packages/apra-fleet-workflow/src/workflow/index.mjs +435 -31
  261. package/skills/fleet/SKILL.md +20 -9
  262. package/skills/fleet/auth-azdevops.md +44 -5
  263. package/skills/fleet/auth-bitbucket.md +3 -3
  264. package/skills/fleet/auth-github.md +2 -2
  265. package/skills/fleet/beads-conflict-resolution.md +141 -0
  266. package/skills/fleet/beads.md +16 -12
  267. package/skills/fleet/onboarding.md +4 -4
  268. package/skills/fleet/permissions.md +6 -6
  269. package/skills/fleet/skill-matrix.md +1 -1
  270. package/skills/fleet/troubleshooting.md +2 -1
  271. package/version.json +1 -1
  272. package/dist/providers/gemini.d.ts +0 -52
  273. package/dist/providers/gemini.d.ts.map +0 -1
  274. package/dist/providers/gemini.js +0 -236
  275. package/dist/providers/gemini.js.map +0 -1
  276. package/packages/apra-fleet-se/fleet-sprint/docs/coach-role-design.md +0 -23
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "$schema": "http://json-schema.org/draft-07/schema#",
3
3
  "$id": "apra-pm/regression-test-runner-output@1",
4
- "version": 1,
4
+ "version": 2,
5
5
  "title": "regression-test-runner output",
6
6
  "description": "Canonical machine-readable output contract for the regression-test-runner role. See agents/regression-test-runner.md Step 4 for the prose contract this mirrors. This result is informational: it never gates the current sprint's PASS/FAIL verdict -- failures carry over to a future sprint as parent-less [regression][carry-over] beads.",
7
7
  "type": "object",
@@ -17,7 +17,7 @@
17
17
  },
18
18
  "smokePassed": {
19
19
  "type": "boolean",
20
- "description": "Result of playbook Part 2 -- the toy-sprint smoke test."
20
+ "description": "Result of playbook Part 2 -- the sandbox smoke test."
21
21
  },
22
22
  "bugsFiled": {
23
23
  "type": "array",
@@ -30,21 +30,8 @@
30
30
  },
31
31
  "smokeEvidence": {
32
32
  "type": "object",
33
- "description": "Optional structured evidence from Part 2 (the toy-sprint smoke test), so the result is machine-checkable instead of self-reported prose.",
34
- "properties": {
35
- "versionStdout": {
36
- "type": "string",
37
- "description": "Verbatim stdout of running the toy CLI's --version on the sprint branch."
38
- },
39
- "canaryStatus": {
40
- "type": "string",
41
- "description": "The status field from `bd show gh-toy-4ef` (e.g. \"closed\")."
42
- },
43
- "toyRepoHeadSha": {
44
- "type": "string",
45
- "description": "The toy repo's head commit SHA after the toy sprint."
46
- }
47
- }
33
+ "additionalProperties": true,
34
+ "description": "Optional structured evidence from Part 2 (the target repo's own smoke test), so the result is machine-checkable instead of self-reported prose. This schema does not define its shape -- the target repo's regression-test-playbook.md (Part 2 / smoke test section) does. Omit if that playbook defines no structured evidence."
48
35
  }
49
36
  }
50
37
  }
@@ -335,7 +335,6 @@ filename -- each provider expects a different name:
335
335
  |----------|-------------|
336
336
  | Claude | CLAUDE.md |
337
337
  | Antigravity (agy) | AGY.md |
338
- | Gemini | GEMINI.md |
339
338
  | Codex | AGENTS.md |
340
339
  | Copilot | COPILOT.md |
341
340
  | OpenCode | OPENCODE.md |
@@ -33,7 +33,6 @@ Replace `__SKILL_DIR__` with the absolute path for your provider:
33
33
  | Provider | `__SKILL_DIR__` |
34
34
  |----------|----------------|
35
35
  | Claude | `~/.claude/skills/pm` |
36
- | Gemini | `~/.gemini/skills/pm` |
37
36
  | AGY | `~/.gemini/antigravity-cli/skills/pm` |
38
37
  | OpenCode | `~/.config/opencode/skills/pm` |
39
38
 
@@ -89,7 +89,6 @@ Use member_detail -> llmProvider to determine the target filename:
89
89
  |----------|----------|
90
90
  | Claude | CLAUDE.md |
91
91
  | Antigravity (agy) | AGY.md |
92
- | Gemini | GEMINI.md |
93
92
  | Codex | AGENTS.md |
94
93
  | Copilot | COPILOT.md |
95
94
  | OpenCode | OPENCODE.md |
@@ -16,7 +16,7 @@ import {
16
16
  getServerInfoPath,
17
17
  } from '@apralabs/apra-fleet-client/server-resolution';
18
18
  import { beadsExtension } from '../fleet-sprint/viewer-extensions.mjs';
19
- import { validateIssueId, validateBranchName, checkMemberTopology, createMemberReservationClient } from '../fleet-sprint/runner.js';
19
+ import { validateIssueId, validateBranchName, checkMemberTopology, createMemberReservationClient, resyncReacquiredMember, commandResultToSoftGit } from '../fleet-sprint/runner.js';
20
20
  import { normalizeRole } from '../fleet-sprint/contracts.mjs';
21
21
 
22
22
  const __filename = fileURLToPath(import.meta.url);
@@ -303,7 +303,7 @@ export async function resolveRoleMap(rawValue, deps = {}) {
303
303
  * }} opts
304
304
  * @returns {object}
305
305
  */
306
- export function buildRunnerArgs({ targetIssues, members, branch, baseBranch, goal, maxCycles, requirementsFile, roleMap, budget, dispatchTimeoutS, serviceUrl }) {
306
+ export function buildRunnerArgs({ targetIssues, members, branch, baseBranch, goal, maxCycles, requirementsFile, roleMap, budget, dispatchTimeoutS, serviceUrl, runId }) {
307
307
  const args = {
308
308
  target_issues: targetIssues,
309
309
  members,
@@ -321,6 +321,12 @@ export function buildRunnerArgs({ targetIssues, members, branch, baseBranch, goa
321
321
  // HTTP-backed dolt-mutex/id-allocator clients (fleet-sprint/runner.js
322
322
  // ~5013-5052). Omitted when not supplied -- unchanged fallback behavior.
323
323
  if (serviceUrl !== undefined) args.serviceUrl = serviceUrl;
324
+ // apra-fleet-5co8.37: this launch's reservation identity (the supervisor's
325
+ // --run-id, or the branch name for a direct launch -- the SAME key members
326
+ // are reserved under below). runner.js threads it into the deployer's
327
+ // dispatch so deploy.md's active-sprints gate can recognize this sprint's
328
+ // OWN reservation instead of stopping on it.
329
+ if (runId !== undefined) args.run_id = runId;
324
330
  return args;
325
331
  }
326
332
 
@@ -445,6 +451,39 @@ export function attachViewerErrorHandler(server, port, opts = {}) {
445
451
  return server;
446
452
  }
447
453
 
454
+ // (apra-fleet-p2to.4.2) Owner-checked re-reserve executed on the workflow's
455
+ // 'resumed' event. reReserveForResume() re-grabs every member released at pause
456
+ // and, on the happy path, re-syncs each; if any member was claimed by another
457
+ // sprint while we were paused it throws a MemberReservationResumeError that
458
+ // NAMES exactly those members.
459
+ //
460
+ // The prior review (PR #397) reopened this bead because the 'resumed' handler
461
+ // wrapped that call in `.catch(console.error)`, which SWALLOWED the naming
462
+ // throw: the sprint then resumed anyway while holding ZERO reservations, and
463
+ // the designed clean-failure path never fired. This helper is the fix -- it
464
+ // does NOT swallow. On failure it re-pauses the run (requestPause) so no further
465
+ // dispatch lands on a member this sprint no longer owns, and then RETHROWS so
466
+ // the failure -- and precisely which members block the resume -- is surfaced to
467
+ // the operator instead of lost to a console.error line. Extracted and exported
468
+ // so the rethrow-and-name behavior is unit-testable without a live engine.
469
+ export async function reReserveOnResume({ sprintReservation, resyncMember, requestPause, log = () => {} } = {}) {
470
+ try {
471
+ return await sprintReservation.reReserveForResume({ resyncMember });
472
+ } catch (err) {
473
+ const msg = err && err.message ? err.message : String(err);
474
+ // Re-park the run: the resume cannot proceed on a reservation set we no
475
+ // longer fully own. This keeps the sprint from silently continuing on
476
+ // zero reservations (the exact regression the review flagged).
477
+ if (typeof requestPause === 'function') {
478
+ requestPause(`resume blocked -- ${msg}`);
479
+ }
480
+ log(`[member-reservation] resume failed (run re-paused; free the named members and resume again): ${msg}`);
481
+ // Surface, do not swallow: the operator must see which members block the
482
+ // resume (MemberReservationResumeError.members names them).
483
+ throw err;
484
+ }
485
+ }
486
+
448
487
  async function main() {
449
488
  const { values } = parseCliArgs(process.argv.slice(2));
450
489
 
@@ -570,11 +609,19 @@ async function main() {
570
609
 
571
610
  // 2. Validate members exist via the fleet's list_members tool.
572
611
  let validMembers = [];
612
+ // apra-fleet: names flagged unreservable in the SAME list_members read --
613
+ // hoisted out of this try block so the topology filter below (item 4) can
614
+ // key on the actual unreservable flag, not on roleMap.orchestrator
615
+ // membership (which would also match a real, git-having dispatch member
616
+ // that is ADDITIONALLY role-mapped as orchestrator, and wrongly skip its
617
+ // legitimate same-HEAD topology check).
618
+ let unreservableNames = new Set();
573
619
  try {
574
620
  const listRes = await fleetApi.listMembers({ format: 'json' });
575
621
  const text = listRes && listRes.content && listRes.content[0] ? listRes.content[0].text : JSON.stringify(listRes);
576
622
  const parsed = JSON.parse(text);
577
623
  const registeredNames = new Set((parsed.members || []).map(m => m.name));
624
+ unreservableNames = new Set((parsed.members || []).filter(m => m && m.unreservable).map(m => m.name));
578
625
  const result = resolveMemberValidation({ rawMembers, registeredNames, allowMissingMembers });
579
626
  if (!result.ok) {
580
627
  console.error(result.message);
@@ -637,8 +684,31 @@ async function main() {
637
684
  }
638
685
  return res && res.content && res.content[0] ? res.content[0].text : '';
639
686
  };
687
+ // apra-fleet: exclude any member flagged `unreservable` from this
688
+ // git-identity/git-remote probe -- such a member (e.g. a shared
689
+ // fleet-sprint orchestrator, docs/design-orchestrator-worktree-model-v2.md)
690
+ // may have no real checkout at all, and `git rev-parse HEAD` on one
691
+ // hard-fails the launch (process.exit(1) just below). Deliberately keyed
692
+ // on the `unreservable` FLAG, not on roleMap.orchestrator membership: a
693
+ // real, git-having dispatch member that is ADDITIONALLY role-mapped as
694
+ // orchestrator (a supported topology, runner.js's branchEnsureMembers
695
+ // dedupe comment) must still pass its legitimate same-HEAD check against
696
+ // the other dispatch members -- filtering on roleMap.orchestrator alone
697
+ // would silently skip that check instead of just skipping a git-less
698
+ // member. This only matters when an operator also lists a shared member
699
+ // in --members (redundant with roleMap.orchestrator, and not required);
700
+ // a normal launch that passes the shared orchestrator ONLY via
701
+ // roleMap.orchestrator was never affected.
702
+ const topologyMembersFiltered = validMembers.filter((m) => !unreservableNames.has(m));
703
+ // Degrade back to the unfiltered list if excluding unreservable members
704
+ // would empty it out entirely -- checkMemberTopology refuses to start on
705
+ // an empty member list, and an operator who names ONLY unreservable
706
+ // members in --members (unusual, but not this check's job to forbid) gets
707
+ // the ORIGINAL single-member-trivial-pass behavior rather than a topology
708
+ // error about having no members at all.
709
+ const topologyMembers = topologyMembersFiltered.length > 0 ? topologyMembersFiltered : validMembers;
640
710
  const topology = await checkMemberTopology({
641
- members: validMembers,
711
+ members: topologyMembers,
642
712
  mode: syncedMode ? 'synced' : 'legacy',
643
713
  getIdentity: (member) => runCommand('git rev-parse HEAD', member),
644
714
  getOriginUrl: (member) => runCommand('git remote get-url origin', member),
@@ -735,6 +805,64 @@ async function main() {
735
805
  });
736
806
  await sprintReservation.reserveAll();
737
807
 
808
+ // apra-fleet-p2to.4.2: reservation handling across a cooperative
809
+ // pause/resume (apra-fleet-p2to.1's engine primitive). On 'paused' hand
810
+ // every member back so another sprint may use it while this one is parked;
811
+ // on 'resumed' re-acquire them OWNER-CHECKED (a member another sprint
812
+ // grabbed while we were paused fails the resume, NAMING it) and re-sync
813
+ // every re-acquired member (git fetch + decideEnsureBranchAction probe +
814
+ // bd dolt pull) unconditionally before work continues. The 'paused' handler
815
+ // is best-effort (a release hiccup must never fail a pause). The 'resumed'
816
+ // handler, by contrast, FAILS the resume when a member was taken while
817
+ // paused: reReserveForResume's throw (an unavailable member) is surfaced --
818
+ // the run is re-paused and the error rethrown -- so the operator sees
819
+ // exactly which members block the resume instead of the sprint silently
820
+ // continuing on zero reservations.
821
+ // `ok` is derived from the command's real exit code (via
822
+ // commandResultToSoftGit), NOT from an isError flag: execute_command never
823
+ // sets isError on a non-zero exit, so reading it here would make every git
824
+ // command -- including the `git merge-base --is-ancestor` tip comparison --
825
+ // look successful and silently reset committed-but-unpushed work. See
826
+ // commandResultToSoftGit()'s doc comment in runner.js.
827
+ const runGitSoft = async (cmd, member) => {
828
+ const res = await fleetApi.executeCommand({ command: cmd, member_name: member });
829
+ return commandResultToSoftGit(res);
830
+ };
831
+ workflow.on('paused', () => {
832
+ sprintReservation.releaseForPause().catch((err) =>
833
+ console.error('[member-reservation] release-on-pause failed:', err && err.message ? err.message : err));
834
+ });
835
+ // (apra-fleet-p2to.1.3) The re-reserve + per-member resync is registered as
836
+ // an AWAITABLE pre-resume hook, not a fire-and-forget 'resumed' listener.
837
+ // requestResume() drains this hook as a hard barrier -- while the run is
838
+ // still paused, so no post-resume agent()/command() dispatch can land ahead
839
+ // of it -- and only then releases the gate waiters and emits 'resumed'. The
840
+ // re-reserve therefore completes strictly BEFORE the first post-resume
841
+ // dispatch, closing the race the old 'resumed' handler left open.
842
+ //
843
+ // reReserveOnResume() does NOT swallow a re-reserve failure (the old
844
+ // `.catch(console.error)` did, silently resuming on zero reservations). It
845
+ // rethrows the MemberReservationResumeError that NAMES the unavailable
846
+ // members; because the hook runs before requestResume() clears pause state,
847
+ // that rejection leaves the run parked (still paused) and propagates out of
848
+ // requestResume() to the resume caller instead of being lost -- the operator
849
+ // sees exactly which members block the resume. requestPause() is still
850
+ // passed for the exported helper's standalone contract; here it is a no-op
851
+ // because the run has not yet been unpaused.
852
+ workflow.setPreResumeHook(() => reReserveOnResume({
853
+ sprintReservation,
854
+ resyncMember: (member) => resyncReacquiredMember({
855
+ member,
856
+ branch: branchName,
857
+ baseBranch,
858
+ runGit: (cmd) => runGitSoft(cmd, member),
859
+ doltPull: (m) => runCommand('bd dolt pull', m),
860
+ log: (msg) => console.log(msg),
861
+ }),
862
+ requestPause: (reason) => workflow.requestPause(reason),
863
+ log: (msg) => console.error(msg),
864
+ }));
865
+
738
866
  let reservationReleased = false;
739
867
  const releaseReservationOnce = async () => {
740
868
  if (reservationReleased) return;
@@ -769,6 +897,7 @@ async function main() {
769
897
  budget,
770
898
  dispatchTimeoutS,
771
899
  serviceUrl,
900
+ runId: effectiveRunId,
772
901
  }),
773
902
  // apra-fleet-eft.75.1: wires this already-connected mcpClient
774
903
  // through to runner.js's createMemberSessionGuard (see its doc
@@ -18,6 +18,8 @@
18
18
  // =============================================================================
19
19
 
20
20
  import { parseArgs } from 'node:util';
21
+ import path from 'node:path';
22
+ import fs from 'node:fs';
21
23
  import { pathToFileURL } from 'node:url';
22
24
  import { createSupervisor, DEFAULT_SERVICE_PORT, readJsonBody, sendJson } from '../src/supervisor/server.mjs';
23
25
  import { createLedger } from '../src/supervisor/ledger.mjs';
@@ -47,7 +49,7 @@ import { createDashboard, registerDashboardRoutes } from '../src/supervisor/dash
47
49
  import { createSprintController, registerSprintRoutes, defaultMemberOverlapGuard, ApiError } from '../src/supervisor/api.mjs';
48
50
  import { createScopeGuard, formatScopeConflict } from '../src/supervisor/scope-overlap.mjs';
49
51
  import { listFleetMembers, executeFleetCommand } from '../src/supervisor/fleet-members.mjs';
50
- import { createDoltOrphanSweep } from '../src/supervisor/dolt-orphan-sweep.mjs';
52
+ import { createDoltOrphanSweep, normalizeMsysPathForPlatform } from '../src/supervisor/dolt-orphan-sweep.mjs';
51
53
  import { resolveFleetServerConnection } from './cli.mjs';
52
54
 
53
55
  const SERVE_USAGE = `
@@ -59,6 +61,14 @@ termination signal (Ctrl-C / SIGTERM).
59
61
  Options:
60
62
  --port <port> HTTP service port for the supervisor API. Default: ${DEFAULT_SERVICE_PORT}.
61
63
  -h, --help Show this help message.
64
+
65
+ Environment:
66
+ FLEET_SE_DATA_DIR Service data dir (ledger/history/logs).
67
+ FLEET_SE_SWEEP_OWNER_DATA_DIR Scope the dolt-orphan-sweep to ephemeral
68
+ dolt sql-servers whose --data-dir is under
69
+ this path, so an isolated supervisor
70
+ instance never kills another instance's
71
+ server. Unset = machine-wide (default).
62
72
  `.trim();
63
73
 
64
74
  /**
@@ -259,9 +269,34 @@ export async function serveMain(argv = process.argv.slice(2)) {
259
269
  // collaborators use the same short-lived-MCP-connection pattern as
260
270
  // listFleetMembers -- the supervisor never holds a standing fleet
261
271
  // transport.
272
+ // apra-fleet-5co8.33: `FLEET_SE_SWEEP_OWNER_DATA_DIR` is the deps-level
273
+ // scope seam for that sweep. Unset (production default) the probe/kill
274
+ // command stays machine-wide -- it must be, because the ephemeral server's
275
+ // `--data-dir` belongs to the MEMBER (dolt-settle.mjs reads it from
276
+ // `bd dolt status` there), so a remote member's data dir has no relation to
277
+ // this supervisor's own FLEET_SE_DATA_DIR and deriving a prefix from the
278
+ // latter would silently make the sweep a no-op everywhere. Set (an isolated
279
+ // instance -- e.g. regression-test-playbook.md's sandbox supervisor, whose
280
+ // HOME and members all live under one root) it constrains candidates to
281
+ // processes whose `--data-dir` is under that root, so this instance can
282
+ // never kill another live supervisor's ephemeral server.
283
+ const sweepOwnerDataDir = process.env.FLEET_SE_SWEEP_OWNER_DATA_DIR
284
+ ? path.resolve(normalizeMsysPathForPlatform(process.env.FLEET_SE_SWEEP_OWNER_DATA_DIR))
285
+ : null;
286
+ if (sweepOwnerDataDir) {
287
+ console.log(`[dolt-orphan-sweep] owner-scoped to data dirs under '${sweepOwnerDataDir}' (FLEET_SE_SWEEP_OWNER_DATA_DIR).`);
288
+ // apra-fleet-5co8.36: a confident scope claim above is worse than
289
+ // useless if the resolved prefix does not actually exist -- that is
290
+ // exactly what an un-normalized MSYS path used to produce. Warn
291
+ // loudly rather than let the sweep silently match nothing.
292
+ if (!fs.existsSync(sweepOwnerDataDir)) {
293
+ console.warn(`[dolt-orphan-sweep] WARNING: FLEET_SE_SWEEP_OWNER_DATA_DIR resolved to '${sweepOwnerDataDir}', which does not exist on disk -- the owner-scoped sweep will match no process and silently degrade to matching nothing.`);
294
+ }
295
+ }
262
296
  const doltOrphanSweep = createDoltOrphanSweep({
263
297
  listMembers: () => listFleetMembers({ resolveConnection: resolveFleetServerConnection }),
264
298
  execCommand: ({ member, command }) => executeFleetCommand({ member, command, resolveConnection: resolveFleetServerConnection }),
299
+ ownerDataDirPrefix: sweepOwnerDataDir,
265
300
  });
266
301
 
267
302
  const supervisor = createSupervisor({ port, ledger, spawner, watchdog, dashboard, idAllocator, doltMutex, doltOrphanSweep });
@@ -94,31 +94,37 @@ export function validateRole(role) {
94
94
  // 2. Role-owned schema loader (apra-fleet-unw.22, packaging-safe per apra-fleet-bun)
95
95
  // ---------------------------------------------------------------------------
96
96
  //
97
- // Schema resolution is layout-aware and bundled-location-first (apra-fleet-
98
- // bun), because apra-fleet-se must resolve its apra-pm role schemas
99
- // correctly regardless of how it ended up on disk: a full monorepo git
100
- // clone (this repo, today), a standalone `npm install @apralabs/apra-fleet-
101
- // se`, or bundled into the root @apralabs/apra-fleet package's dist/auto-
102
- // sprint.mjs. `resolveSchemasDir()` below tries, in order:
97
+ // Schema resolution is layout-aware and freshness-first between the two
98
+ // bundled/local candidates (apra-fleet-ot2z.20), because apra-fleet-se must
99
+ // resolve its apra-pm role schemas correctly regardless of how it ended up
100
+ // on disk: a full monorepo git clone (this repo, today), a standalone `npm
101
+ // install @apralabs/apra-fleet-se`, or bundled into the root
102
+ // @apralabs/apra-fleet package's dist/auto-sprint.mjs. `resolveSchemasDir()`
103
+ // below tries, in order:
103
104
  //
104
105
  // 1. process.env.APRA_FLEET_SE_SCHEMAS_DIR, if set -- an explicit
105
- // override, used as-is with no further fallback. Tests use this to
106
- // point at a fixture directory; any deployment may also use it to pin
107
- // an exact schemas directory.
108
- // 2. <root>/dist/agents/schemas -- the sibling directory scripts/dist-
109
- // pm.mjs ALREADY populates at the root package's `prepublishOnly`
110
- // (cpSync of packages/apra-fleet-se/apra-pm/agents -> dist/agents, which includes its
111
- // schemas/ subdir). This is what a dist/fleet-sprint.mjs bundle
112
- // resolves once apra-fleet-3ns.2 ships it as a dist/ sibling -- no new
113
- // copy step needed, this artifact already exists today.
114
- // 3. packages/apra-fleet-se/apra-pm/agents/schemas -- the package-local apra-pm
115
- // directory. This is what a standalone install of @apralabs/apra-fleet-se
116
- // resolves, or a dev checkout.
106
+ // override, used as-is with no further fallback and no freshness
107
+ // lookup at all. Tests use this to point at a fixture directory; any
108
+ // deployment may also use it to pin an exact schemas directory.
109
+ // 2. If only one of <root>/dist/agents/schemas (the sibling directory
110
+ // scripts/dist-pm.mjs populates at the root package's
111
+ // `prepublishOnly`, cpSync of packages/apra-fleet-se/apra-pm/agents ->
112
+ // dist/agents, which includes its schemas/ subdir) or
113
+ // packages/apra-fleet-se/apra-pm/agents/schemas (the package-local
114
+ // apra-pm directory) exists, resolve that one. This is the path every
115
+ // real deployment (standalone install, dist bundle, clean CI checkout)
116
+ // takes.
117
+ // 3. If BOTH exist, resolve the NEWER one, where a directory's freshness
118
+ // is the MAXIMUM mtime over the .json files it contains, searched
119
+ // recursively (not the directory's own mtime, which only moves on
120
+ // entry create/delete/rename and would miss an in-place edit to an
121
+ // existing schema file). Ties resolve to dist, preserving the
122
+ // pre-apra-fleet-ot2z.20 behaviour.
117
123
  //
118
- // If none of 1-3 exist as a directory, `resolveSchemasDir()` returns `null`;
119
- // `loadVendorSchema` already treats a null/absent directory as the expected,
120
- // quiet graceful-degradation case (every schema falls back to its hand-
121
- // written literal in section 3) -- unchanged from before apra-fleet-bun.
124
+ // If neither candidate exists as a directory, `resolveSchemasDir()` returns
125
+ // `null`; `loadVendorSchema` already treats a null/absent directory as the
126
+ // expected, quiet graceful-degradation case (every schema falls back to its
127
+ // hand-written literal in section 3) -- unchanged from before apra-fleet-bun.
122
128
  const PACKAGE_ROOT = path.join(__dirname, '..');
123
129
  const REPO_ROOT = path.join(PACKAGE_ROOT, '..', '..');
124
130
  // Exported (not just module-local) so a drift guard test can compare the two
@@ -135,23 +141,65 @@ function isDirectory(candidate) {
135
141
  }
136
142
  }
137
143
 
144
+ /**
145
+ * Default freshness lookup for `resolveSchemasDir()`'s both-exist branch:
146
+ * the maximum mtime (ms) over every `.json` file found by a recursive walk
147
+ * of `dir`. Tolerates an unreadable or empty directory by treating it as
148
+ * freshness 0 rather than throwing -- a directory disappearing or being
149
+ * unreadable between the `exists()` check and this walk must not crash
150
+ * schema resolution.
151
+ * @param {string} dir
152
+ * @returns {number}
153
+ */
154
+ function newestJsonMtimeMs(dir) {
155
+ let newest = 0;
156
+ let entries;
157
+ try {
158
+ entries = fs.readdirSync(dir, { withFileTypes: true });
159
+ } catch {
160
+ return 0;
161
+ }
162
+ for (const entry of entries) {
163
+ const entryPath = path.join(dir, entry.name);
164
+ if (entry.isDirectory()) {
165
+ newest = Math.max(newest, newestJsonMtimeMs(entryPath));
166
+ } else if (entry.isFile() && entry.name.endsWith('.json')) {
167
+ try {
168
+ newest = Math.max(newest, fs.statSync(entryPath).mtimeMs);
169
+ } catch {
170
+ // Unreadable file between readdir and stat -- ignore it.
171
+ }
172
+ }
173
+ }
174
+ return newest;
175
+ }
176
+
138
177
  /**
139
178
  * Resolves the directory to load vendored role schemas from, per the
140
- * bundled-location-first precedence documented above. Exported (and
179
+ * freshness-first precedence documented above. Exported (and
141
180
  * side-effect-injectable via `deps`) so tests can exercise every branch in
142
181
  * isolation without needing real directories on disk for each case.
143
- * @param {{ env?: Record<string, string | undefined>, exists?: (candidate: string) => boolean }} [deps]
182
+ * @param {{ env?: Record<string, string | undefined>, exists?: (candidate: string) => boolean, newestJsonMtimeMs?: (dir: string) => number }} [deps]
144
183
  * @returns {string | null}
145
184
  */
146
185
  export function resolveSchemasDir(deps = {}) {
147
186
  const env = deps.env || process.env;
148
187
  const exists = deps.exists || isDirectory;
188
+ const freshnessOf = deps.newestJsonMtimeMs || newestJsonMtimeMs;
149
189
 
150
190
  const override = env.APRA_FLEET_SE_SCHEMAS_DIR;
151
191
  if (override) return override;
152
192
 
153
- if (exists(DIST_BUNDLED_SCHEMAS_DIR)) return DIST_BUNDLED_SCHEMAS_DIR;
154
- if (exists(PACKAGE_LOCAL_SCHEMAS_DIR)) return PACKAGE_LOCAL_SCHEMAS_DIR;
193
+ const distExists = exists(DIST_BUNDLED_SCHEMAS_DIR);
194
+ const localExists = exists(PACKAGE_LOCAL_SCHEMAS_DIR);
195
+
196
+ if (distExists && localExists) {
197
+ const localFreshness = freshnessOf(PACKAGE_LOCAL_SCHEMAS_DIR);
198
+ const distFreshness = freshnessOf(DIST_BUNDLED_SCHEMAS_DIR);
199
+ return localFreshness > distFreshness ? PACKAGE_LOCAL_SCHEMAS_DIR : DIST_BUNDLED_SCHEMAS_DIR;
200
+ }
201
+ if (distExists) return DIST_BUNDLED_SCHEMAS_DIR;
202
+ if (localExists) return PACKAGE_LOCAL_SCHEMAS_DIR;
155
203
 
156
204
  return null;
157
205
  }
@@ -533,11 +581,7 @@ const FALLBACK_regressionReport = {
533
581
  summary: { type: 'string' },
534
582
  smokeEvidence: {
535
583
  type: 'object',
536
- properties: {
537
- versionStdout: { type: 'string' },
538
- canaryStatus: { type: 'string' },
539
- toyRepoHeadSha: { type: 'string' },
540
- },
584
+ additionalProperties: true,
541
585
  },
542
586
  },
543
587
  required: ['passed', 'suitePassed', 'smokePassed', 'bugsFiled', 'summary'],
@@ -883,6 +927,50 @@ function longestBacktickRun(content) {
883
927
  return matches.reduce((max, run) => Math.max(max, run.length), 0);
884
928
  }
885
929
 
930
+ /**
931
+ * The pattern src/tools/execute-prompt.ts matches to reject a dispatch
932
+ * outright. Duplicated here as a literal rather than imported: this module
933
+ * deliberately has no dependency on the fleet server sources.
934
+ */
935
+ const SECURE_TOKEN_RE_G = /\{\{secure\.([a-zA-Z0-9_-]{1,64})\}\}/g;
936
+
937
+ const SECURE_REDACTION_NOTE = 'NOTE: secure-token braces were redacted from the block above '
938
+ + '(secure.NAME is shown without its surrounding double braces). Write the braced form when '
939
+ + 'you actually use the token in an execute_command call.';
940
+
941
+ /**
942
+ * Strips the surrounding double braces from any secure-token reference in
943
+ * untrusted content, keeping the token NAME so the text still reads.
944
+ *
945
+ * Why this must happen before the content reaches a prompt: execute_prompt
946
+ * rejects the ENTIRE dispatch -- no LLM call, an error string returned in
947
+ * place of a reply -- if the prompt matches that token pattern anywhere.
948
+ * The guard is right for caller-authored prompts, but injected content is
949
+ * not caller-authored: a knowledge-bank entry or an acceptance criterion
950
+ * that merely NAMES the token carries no secret, yet would silently fail
951
+ * every dispatch in a sprint. Redaction, not removal: the name is the part
952
+ * that makes the entry useful.
953
+ * @param {string} content
954
+ * @returns {{text: string, redacted: boolean}}
955
+ */
956
+ function redactSecureTokens(content) {
957
+ let text = content;
958
+ let redacted = false;
959
+ // Run to a fixed point rather than a single pass: replacing the inner
960
+ // token in `{{{{secure.A}}}}` leaves `{{secure.A}}`, so the surrounding
961
+ // braces close over the redacted name and rebuild exactly the pattern
962
+ // being removed. Untrusted content is attacker-influenced free-text, so
963
+ // one pass is not enough. Guaranteed to terminate -- every replacement
964
+ // removes four brace characters, so `text` strictly shrinks.
965
+ for (;;) {
966
+ const next = text.replace(SECURE_TOKEN_RE_G, (_match, name) => `secure.${name}`);
967
+ if (next === text) break;
968
+ text = next;
969
+ redacted = true;
970
+ }
971
+ return { text, redacted };
972
+ }
973
+
886
974
  /**
887
975
  * Wraps `content` in a clearly delimited fenced block labeled as untrusted
888
976
  * inter-agent output, per feedback.md finding A7. Pure function: no I/O,
@@ -908,14 +996,16 @@ export function wrapUntrustedBlock(sourceLabel, content) {
908
996
  if (typeof content !== 'string') {
909
997
  throw new TypeError('[contracts] wrapUntrustedBlock requires content to be a string');
910
998
  }
911
- const fenceLength = Math.max(MIN_FENCE_LENGTH, longestBacktickRun(content) + 1);
999
+ const { text: safeContent, redacted } = redactSecureTokens(content);
1000
+ const fenceLength = Math.max(MIN_FENCE_LENGTH, longestBacktickRun(safeContent) + 1);
912
1001
  const fence = '`'.repeat(fenceLength);
913
1002
  return [
914
1003
  UNTRUSTED_BLOCK_PREAMBLE,
915
1004
  `Source: ${sourceLabel}`,
916
1005
  `${fence}${UNTRUSTED_BLOCK_FENCE_LABEL}`,
917
- content,
1006
+ safeContent,
918
1007
  fence,
1008
+ ...(redacted ? [SECURE_REDACTION_NOTE] : []),
919
1009
  ].join('\n');
920
1010
  }
921
1011
 
@@ -938,3 +1028,31 @@ export function appendSchemaInstruction(prompt, schema) {
938
1028
  }
939
1029
  return `${prompt}\n\nOnly provide your response strictly as per this JSON schema:\n${JSON.stringify(schema, null, 2)}`;
940
1030
  }
1031
+
1032
+ // ---------------------------------------------------------------------------
1033
+ // 7. Credential-store name validation (apra-fleet-5co8.2.3)
1034
+ // ---------------------------------------------------------------------------
1035
+ //
1036
+ // Pattern for valid credential-store entry names, shared with src/tools/ (see
1037
+ // credential-store-set.ts). Used by the per-sprint Azure DevOps PAT secret
1038
+ // name override validation (runner.js's validateArgs).
1039
+
1040
+ const CREDENTIAL_STORE_NAME_PATTERN = /^[a-zA-Z0-9_-]{1,64}$/;
1041
+
1042
+ /**
1043
+ * Validates a credential-store entry name against the pattern used by
1044
+ * credential_store_set (alphanumeric, underscores, hyphens, 1-64 chars).
1045
+ * Throws with a clear message on rejection.
1046
+ * @param {unknown} name
1047
+ * @param {string} label - human-readable arg name, used in the error message
1048
+ * @returns {string}
1049
+ */
1050
+ export function validateCredentialStoreName(name, label) {
1051
+ if (typeof name !== 'string' || name.length === 0 || !CREDENTIAL_STORE_NAME_PATTERN.test(name)) {
1052
+ throw new Error(
1053
+ `[Arg Contract] Invalid ${label} "${name}": must match ${CREDENTIAL_STORE_NAME_PATTERN} ` +
1054
+ `(alphanumeric, underscores, hyphens, 1-64 chars).`
1055
+ );
1056
+ }
1057
+ return name;
1058
+ }
@@ -79,7 +79,7 @@ Watch progress there rather than tailing raw stdout.
79
79
 
80
80
  | Flag | Short | Required | Default | Description |
81
81
  |---|---|---|---|---|
82
- | `--issue <ids>` | `-i` | yes | -- | Target issue ID(s), comma separated (e.g. `epic-1,epic-2`). Scope resolves via `bd list --parent <id>` -- see the epics section below. |
82
+ | `--issue <ids>` | `-i` | yes | -- | Target issue ID(s), comma separated (e.g. `epic-1,epic-2`). Scope resolves to each id's full descendant subtree -- see the epics section below. |
83
83
  | `--members <ids>` | `-m` | yes | -- | Member IDs/names to use, comma separated. Members act as repo targets for parallelism. |
84
84
  | `--branch <name>` | `-b` | yes | -- | Sprint branch to develop on. Created from `--base` if it does not exist; reused as-is if it does. |
85
85
  | `--base <name>` | `-B` | yes | -- | Base branch the sprint branch is created from, and the branch the eventual PR targets. |
@@ -97,6 +97,17 @@ Watch progress there rather than tailing raw stdout.
97
97
  Unrecognized flags fail loudly rather than being silently ignored, so a typo
98
98
  like `--max-cycle` aborts instead of quietly applying the default.
99
99
 
100
+ **A shared/`unreservable` orchestrator member goes in `--role-map` ONLY, never
101
+ in `--members`.** `--members` (and `--role-map` values for git-having roles
102
+ like doer/reviewer/harvester) still get git-identity/topology-checked and, on
103
+ resume, git-resynced. A member registered `unreservable: true` (e.g. a
104
+ beads-only orchestrator shared across concurrent sprints) is exempted from
105
+ those checks only when it appears exclusively via `roleMap.orchestrator` --
106
+ listing it in `--members` too is redundant and not required, and defeats the
107
+ exemption for anything outside the topology precondition (e.g. a paused/
108
+ resumed sprint's resync step still runs real git commands against every
109
+ `--members` entry, unreservable or not).
110
+
100
111
  ## Preconditions worth checking first
101
112
 
102
113
  - The target issue (e.g. `apra-fleet-7pm`) must exist and be open:
@@ -143,15 +154,19 @@ bead that used `blocks` instead had `dependency_count: 5` and, once
143
154
  children were also parented under it, deadlocked completely.
144
155
 
145
156
  This also matters for launching a sprint: `fleet-sprint`'s `--issue <id>`
146
- flag resolves the sprint's scope via `bd list --parent <id>` internally --
147
- it only ever understands the `parent-child` hierarchy. A `blocked-by`-only
148
- manifest bead is invisible to fleet-sprint's scope filter no matter what you
149
- pass to `--issue`; only true children are picked up.
157
+ flag resolves the sprint's scope by walking the `parent-child` tree down from
158
+ `<id>` -- `bdListScoped()` fetches the whole project's beads once and does
159
+ the descendant walk in memory, so every descendant at any depth is in scope
160
+ (not just direct children), but nothing outside the parent-child hierarchy
161
+ ever is. A `blocked-by`-only manifest bead is invisible to fleet-sprint's
162
+ scope filter no matter what you pass to `--issue`; only true children are
163
+ picked up. See `packages/apra-fleet-se/docs/fleet-sprint-cli-contract.md` for
164
+ the full algorithm and worked examples.
150
165
 
151
166
  ## Recovering a wedged member reservation (launched via the supervisor)
152
167
 
153
- If a sprint was launched through the supervisor (`fleet-se serve`, `POST
154
- /api/sprints`) and its child process crashes or is killed, the supervisor's
168
+ If a sprint was launched through the supervisor (`bin/serve.mjs`, installed
169
+ as `fleet-se-serve`; `POST /api/sprints`) and its child process crashes or is killed, the supervisor's
155
170
  reservation ledger does **not** release that sprint's claim on its own during
156
171
  normal runtime -- only a supervisor restart, or an explicit operator call,
157
172
  clears it. Symptom: relaunching against the same member(s) is rejected with