@apralabs/apra-fleet 0.4.4 → 0.4.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (268) hide show
  1. package/README.md +49 -4
  2. package/dist/agents/backlog-groomer.md +5 -0
  3. package/dist/agents/ci-watcher.md +5 -0
  4. package/dist/agents/deployer.md +20 -2
  5. package/dist/agents/doer.md +38 -2
  6. package/dist/agents/harvester.md +12 -9
  7. package/dist/agents/integ-test-runner.md +5 -0
  8. package/dist/agents/kb-reconciler.md +6 -0
  9. package/dist/agents/plan-reviewer.md +5 -0
  10. package/dist/agents/planner.md +5 -0
  11. package/dist/agents/regression-test-runner.md +5 -0
  12. package/dist/agents/reviewer.md +67 -15
  13. package/dist/agents/schemas/deployer-output.json +5 -0
  14. package/dist/agents/schemas/doer-output.json +78 -2
  15. package/dist/agents/schemas/reviewer-output.json +104 -2
  16. package/dist/cli/auth.js +5 -1
  17. package/dist/cli/beads-pin.js +6 -7
  18. package/dist/cli/claude-mod.d.ts +75 -0
  19. package/dist/cli/claude-mod.js +288 -0
  20. package/dist/cli/dolt-install.d.ts +1 -1
  21. package/dist/cli/dolt-install.js +5 -1
  22. package/dist/cli/fleet-se-guard.d.ts +8 -0
  23. package/dist/cli/fleet-se-guard.js +19 -3
  24. package/dist/cli/install-guard.d.ts +9 -0
  25. package/dist/cli/install-guard.js +24 -0
  26. package/dist/cli/install.d.ts +12 -0
  27. package/dist/cli/install.js +180 -20
  28. package/dist/cli/kb-profile.d.ts +16 -0
  29. package/dist/cli/kb-profile.js +81 -0
  30. package/dist/cli/start.js +3 -0
  31. package/dist/cli/uninstall.js +13 -3
  32. package/dist/cli/update.d.ts +4 -0
  33. package/dist/cli/update.js +19 -3
  34. package/dist/commands/kb-server.d.ts +10 -1
  35. package/dist/commands/kb-server.js +285 -11
  36. package/dist/index.js +22 -1
  37. package/dist/os/git-executable.d.ts +57 -0
  38. package/dist/os/git-executable.js +85 -0
  39. package/dist/os/go-concurrency.d.ts +44 -0
  40. package/dist/os/go-concurrency.js +53 -0
  41. package/dist/os/index.d.ts +1 -0
  42. package/dist/os/index.js +1 -0
  43. package/dist/os/linux.d.ts +2 -0
  44. package/dist/os/linux.js +10 -1
  45. package/dist/os/os-commands.d.ts +25 -0
  46. package/dist/os/os-commands.js +2 -0
  47. package/dist/os/windows-executable.d.ts +53 -0
  48. package/dist/os/windows-executable.js +185 -0
  49. package/dist/os/windows-gitbash.d.ts +23 -14
  50. package/dist/os/windows-gitbash.js +40 -16
  51. package/dist/os/windows.d.ts +2 -0
  52. package/dist/os/windows.js +37 -6
  53. package/dist/paths.d.ts +10 -1
  54. package/dist/paths.js +19 -2
  55. package/dist/services/agy-project.d.ts +7 -1
  56. package/dist/services/agy-project.js +7 -2
  57. package/dist/services/auth-socket.d.ts +18 -0
  58. package/dist/services/auth-socket.js +30 -4
  59. package/dist/services/credential-store.d.ts +33 -0
  60. package/dist/services/credential-store.js +79 -2
  61. package/dist/services/http-transport.d.ts +29 -0
  62. package/dist/services/http-transport.js +166 -37
  63. package/dist/services/kb-tool-profile.d.ts +36 -0
  64. package/dist/services/kb-tool-profile.js +88 -0
  65. package/dist/services/knowledge/bible-blob-id.js +10 -1
  66. package/dist/services/knowledge/bible-import.d.ts +108 -0
  67. package/dist/services/knowledge/bible-import.js +137 -4
  68. package/dist/services/knowledge/file-hash.js +6 -5
  69. package/dist/services/knowledge/http-provider.d.ts +303 -20
  70. package/dist/services/knowledge/http-provider.js +795 -125
  71. package/dist/services/knowledge/kb-config.d.ts +65 -1
  72. package/dist/services/knowledge/kb-config.js +143 -3
  73. package/dist/services/knowledge/kb-http-auth-state.d.ts +26 -0
  74. package/dist/services/knowledge/kb-http-auth-state.js +40 -0
  75. package/dist/services/knowledge/kb-providers.d.ts +9 -2
  76. package/dist/services/knowledge/kb-providers.js +67 -37
  77. package/dist/services/knowledge/kb-removed-scope-keys.js +1 -1
  78. package/dist/services/knowledge/kb-self.d.ts +122 -9
  79. package/dist/services/knowledge/kb-self.js +196 -36
  80. package/dist/services/knowledge/member-bible-view.js +16 -3
  81. package/dist/services/knowledge/path-validation.d.ts +7 -0
  82. package/dist/services/knowledge/path-validation.js +11 -0
  83. package/dist/services/knowledge/project-slug.js +3 -2
  84. package/dist/services/knowledge/repository-header.d.ts +77 -0
  85. package/dist/services/knowledge/repository-header.js +233 -0
  86. package/dist/services/knowledge/require-sqlite-project.d.ts +1 -1
  87. package/dist/services/knowledge/require-sqlite-project.js +1 -1
  88. package/dist/services/knowledge/sqlite-provider.d.ts +169 -0
  89. package/dist/services/knowledge/sqlite-provider.js +416 -4
  90. package/dist/services/knowledge/types.d.ts +15 -2
  91. package/dist/services/member-busy.d.ts +12 -0
  92. package/dist/services/member-busy.js +20 -0
  93. package/dist/services/member-config-io.d.ts +3 -2
  94. package/dist/services/member-config-io.js +7 -4
  95. package/dist/services/member-fleet-install.js +1 -0
  96. package/dist/services/member-tool-allowlist.d.ts +1 -1
  97. package/dist/services/member-tool-allowlist.js +8 -4
  98. package/dist/services/port-holder.js +2 -1
  99. package/dist/services/service-manager/types.d.ts +17 -1
  100. package/dist/services/service-manager/windows.d.ts +7 -2
  101. package/dist/services/service-manager/windows.js +28 -11
  102. package/dist/services/service-notice.d.ts +7 -0
  103. package/dist/services/service-notice.js +19 -0
  104. package/dist/services/session-registry.d.ts +13 -0
  105. package/dist/services/session-registry.js +13 -0
  106. package/dist/services/session-roots.d.ts +67 -0
  107. package/dist/services/session-roots.js +126 -0
  108. package/dist/services/statusline.d.ts +21 -0
  109. package/dist/services/statusline.js +97 -1
  110. package/dist/services/supervisor-service-cleanup.js +2 -1
  111. package/dist/services/tool-registry.js +108 -20
  112. package/dist/services/tool-scope.d.ts +34 -1
  113. package/dist/services/tool-scope.js +27 -2
  114. package/dist/services/vcs/azure-devops.js +10 -0
  115. package/dist/services/vcs/bitbucket.d.ts +22 -1
  116. package/dist/services/vcs/bitbucket.js +163 -17
  117. package/dist/services/vcs/types.d.ts +25 -2
  118. package/dist/services/watch/project-resolver.js +2 -1
  119. package/dist/skills/pm/cost.md +5 -1
  120. package/dist/skills/pm/index.md +9 -9
  121. package/dist/skills/pm/sprint.md +2 -1
  122. package/dist/tools/check-status.d.ts +51 -0
  123. package/dist/tools/check-status.js +124 -12
  124. package/dist/tools/code-intelligence-freshness.js +1 -1
  125. package/dist/tools/code-intelligence-gitnexus.d.ts +19 -0
  126. package/dist/tools/code-intelligence-gitnexus.js +166 -9
  127. package/dist/tools/code-intelligence-readiness.d.ts +58 -1
  128. package/dist/tools/code-intelligence-readiness.js +93 -8
  129. package/dist/tools/code-intelligence-reindex.d.ts +25 -1
  130. package/dist/tools/code-intelligence-reindex.js +76 -4
  131. package/dist/tools/code-intelligence.d.ts +1 -1
  132. package/dist/tools/code-intelligence.js +1 -1
  133. package/dist/tools/execute-command.js +14 -8
  134. package/dist/tools/execute-prompt.js +6 -2
  135. package/dist/tools/fleet-snapshot.d.ts +21 -0
  136. package/dist/tools/fleet-snapshot.js +78 -0
  137. package/dist/tools/kb-bible-commit.d.ts +25 -11
  138. package/dist/tools/kb-bible-commit.js +142 -33
  139. package/dist/tools/kb-capture.d.ts +2 -2
  140. package/dist/tools/kb-context.js +47 -27
  141. package/dist/tools/kb-demote.d.ts +27 -0
  142. package/dist/tools/kb-demote.js +37 -0
  143. package/dist/tools/kb-export.d.ts +35 -3
  144. package/dist/tools/kb-export.js +56 -13
  145. package/dist/tools/kb-feedback.d.ts +2 -0
  146. package/dist/tools/kb-feedback.js +17 -7
  147. package/dist/tools/kb-harvest.js +28 -9
  148. package/dist/tools/kb-import.d.ts +18 -2
  149. package/dist/tools/kb-import.js +24 -9
  150. package/dist/tools/kb-invalidate.d.ts +11 -3
  151. package/dist/tools/kb-invalidate.js +80 -7
  152. package/dist/tools/kb-list.js +38 -10
  153. package/dist/tools/kb-promote.js +6 -4
  154. package/dist/tools/kb-query.d.ts +3 -0
  155. package/dist/tools/kb-query.js +181 -37
  156. package/dist/tools/kb-session-prime.d.ts +4 -4
  157. package/dist/tools/kb-session-prime.js +89 -9
  158. package/dist/tools/kb-setup.d.ts +20 -0
  159. package/dist/tools/kb-setup.js +149 -11
  160. package/dist/tools/list-members.js +1 -1
  161. package/dist/tools/member-detail.js +7 -3
  162. package/dist/tools/provision-vcs-auth.d.ts +28 -3
  163. package/dist/tools/provision-vcs-auth.js +53 -7
  164. package/dist/tools/receive-files.js +7 -4
  165. package/dist/tools/send-files.js +5 -4
  166. package/dist/tools/send-message.d.ts +3 -0
  167. package/dist/tools/send-message.js +15 -2
  168. package/dist/tools/stop-prompt.js +3 -1
  169. package/dist/tools/vcs-credential-exec.d.ts +45 -3
  170. package/dist/tools/vcs-credential-exec.js +90 -11
  171. package/dist/utils/process-utils.js +5 -1
  172. package/dist/utils/redact-known-secrets.d.ts +17 -0
  173. package/dist/utils/redact-known-secrets.js +70 -0
  174. package/dist/utils/skill-matrix.js +1 -1
  175. package/dist/utils/vcs-provider-detect.js +2 -2
  176. package/dist/workflows/auto-sprint.js +245 -9
  177. package/package.json +10 -7
  178. package/packages/apra-fleet-client/package.json +1 -1
  179. package/packages/apra-fleet-client/src/client/api.mjs +172 -19
  180. package/packages/apra-fleet-client/src/client/reconnecting-transport.mjs +35 -2
  181. package/packages/apra-fleet-client/src/client/transport.mjs +6 -0
  182. package/packages/apra-fleet-se/apra-pm/agents/backlog-groomer.md +5 -0
  183. package/packages/apra-fleet-se/apra-pm/agents/ci-watcher.md +5 -0
  184. package/packages/apra-fleet-se/apra-pm/agents/deployer.md +20 -2
  185. package/packages/apra-fleet-se/apra-pm/agents/doer.md +38 -2
  186. package/packages/apra-fleet-se/apra-pm/agents/harvester.md +12 -9
  187. package/packages/apra-fleet-se/apra-pm/agents/integ-test-runner.md +5 -0
  188. package/packages/apra-fleet-se/apra-pm/agents/kb-reconciler.md +6 -0
  189. package/packages/apra-fleet-se/apra-pm/agents/plan-reviewer.md +5 -0
  190. package/packages/apra-fleet-se/apra-pm/agents/planner.md +5 -0
  191. package/packages/apra-fleet-se/apra-pm/agents/regression-test-runner.md +5 -0
  192. package/packages/apra-fleet-se/apra-pm/agents/reviewer.md +67 -15
  193. package/packages/apra-fleet-se/apra-pm/agents/schemas/deployer-output.json +5 -0
  194. package/packages/apra-fleet-se/apra-pm/agents/schemas/doer-output.json +78 -2
  195. package/packages/apra-fleet-se/apra-pm/agents/schemas/reviewer-output.json +104 -2
  196. package/packages/apra-fleet-se/apra-pm/skills/pm/cost.md +5 -1
  197. package/packages/apra-fleet-se/apra-pm/skills/pm/index.md +9 -9
  198. package/packages/apra-fleet-se/apra-pm/skills/pm/sprint.md +2 -1
  199. package/packages/apra-fleet-se/bin/cli.mjs +104 -31
  200. package/packages/apra-fleet-se/bin/serve.mjs +46 -8
  201. package/packages/apra-fleet-se/fleet-sprint/abort.mjs +184 -32
  202. package/packages/apra-fleet-se/fleet-sprint/bd-sync-command.mjs +69 -0
  203. package/packages/apra-fleet-se/fleet-sprint/beads-children.mjs +21 -0
  204. package/packages/apra-fleet-se/fleet-sprint/beads-lock-probe.mjs +176 -0
  205. package/packages/apra-fleet-se/fleet-sprint/beads-reachability.mjs +126 -0
  206. package/packages/apra-fleet-se/fleet-sprint/beads-scope.mjs +158 -1
  207. package/packages/apra-fleet-se/fleet-sprint/contracts.mjs +82 -2
  208. package/packages/apra-fleet-se/fleet-sprint/coordination.mjs +23 -6
  209. package/packages/apra-fleet-se/fleet-sprint/decision-notify.mjs +338 -0
  210. package/packages/apra-fleet-se/fleet-sprint/decision-wait.mjs +731 -0
  211. package/packages/apra-fleet-se/fleet-sprint/decisions.mjs +372 -0
  212. package/packages/apra-fleet-se/fleet-sprint/dispatch-role.mjs +44 -11
  213. package/packages/apra-fleet-se/fleet-sprint/docs/README.md +4 -1
  214. package/packages/apra-fleet-se/fleet-sprint/dolt-settle.mjs +9 -3
  215. package/packages/apra-fleet-se/fleet-sprint/dolt-sync.mjs +314 -19
  216. package/packages/apra-fleet-se/fleet-sprint/errors.mjs +72 -4
  217. package/packages/apra-fleet-se/fleet-sprint/git-sync.mjs +7 -1
  218. package/packages/apra-fleet-se/fleet-sprint/git-topology.mjs +112 -1
  219. package/packages/apra-fleet-se/fleet-sprint/guarded-modules.mjs +36 -2
  220. package/packages/apra-fleet-se/fleet-sprint/kb.mjs +736 -101
  221. package/packages/apra-fleet-se/fleet-sprint/member-init-probe.mjs +1 -1
  222. package/packages/apra-fleet-se/fleet-sprint/member-provisioning.mjs +7 -1
  223. package/packages/apra-fleet-se/fleet-sprint/phases/deploy.mjs +49 -2
  224. package/packages/apra-fleet-se/fleet-sprint/phases/develop.mjs +206 -3
  225. package/packages/apra-fleet-se/fleet-sprint/phases/final-review.mjs +61 -3
  226. package/packages/apra-fleet-se/fleet-sprint/phases/harvest.mjs +81 -31
  227. package/packages/apra-fleet-se/fleet-sprint/phases/plan.mjs +7 -3
  228. package/packages/apra-fleet-se/fleet-sprint/phases/publish-pr.mjs +39 -14
  229. package/packages/apra-fleet-se/fleet-sprint/phases/re-review.mjs +17 -1
  230. package/packages/apra-fleet-se/fleet-sprint/phases/review.mjs +18 -3
  231. package/packages/apra-fleet-se/fleet-sprint/pr-body.mjs +14 -1
  232. package/packages/apra-fleet-se/fleet-sprint/prompts.mjs +32 -5
  233. package/packages/apra-fleet-se/fleet-sprint/runner.js +824 -98
  234. package/packages/apra-fleet-se/fleet-sprint/se-os-commands.mjs +4 -2
  235. package/packages/apra-fleet-se/fleet-sprint/se-posix.mjs +54 -1
  236. package/packages/apra-fleet-se/fleet-sprint/se-windows.mjs +29 -2
  237. package/packages/apra-fleet-se/fleet-sprint/set-aside.mjs +288 -0
  238. package/packages/apra-fleet-se/fleet-sprint/skills/fleet-supervisor/SKILL.md +3 -2
  239. package/packages/apra-fleet-se/fleet-sprint/sprint-args.mjs +20 -0
  240. package/packages/apra-fleet-se/fleet-sprint/sprint-report.mjs +21 -0
  241. package/packages/apra-fleet-se/fleet-sprint/sprint-state.mjs +9 -0
  242. package/packages/apra-fleet-se/fleet-sprint/vcs-auth.mjs +605 -32
  243. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/bitbucket.mjs +811 -17
  244. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/index.mjs +89 -1
  245. package/packages/apra-fleet-se/fleet-sprint/viewer-extensions.mjs +225 -2
  246. package/packages/apra-fleet-se/fleet-sprint/worklists.mjs +59 -3
  247. package/packages/apra-fleet-se/src/supervisor/api.mjs +148 -8
  248. package/packages/apra-fleet-se/src/supervisor/dashboard.mjs +6 -3
  249. package/packages/apra-fleet-se/src/supervisor/dolt-mutex.mjs +30 -10
  250. package/packages/apra-fleet-se/src/supervisor/fleet-members.mjs +17 -4
  251. package/packages/apra-fleet-se/src/supervisor/history.mjs +8 -1
  252. package/packages/apra-fleet-se/src/supervisor/id-allocator.mjs +92 -2
  253. package/packages/apra-fleet-se/src/supervisor/proxy.mjs +26 -1
  254. package/packages/apra-fleet-se/src/supervisor/server.mjs +151 -8
  255. package/packages/apra-fleet-se/src/supervisor/spawner.mjs +11 -9
  256. package/packages/apra-fleet-se/src/supervisor/watchdog.mjs +7 -1
  257. package/packages/apra-fleet-workflow/package.json +2 -1
  258. package/packages/apra-fleet-workflow/src/viewer/index.mjs +86 -5
  259. package/packages/apra-fleet-workflow/src/viewer/request-guard.mjs +222 -0
  260. package/packages/apra-fleet-workflow/src/workflow/index.mjs +34 -2
  261. package/plugins/claude-code/fleet-status/.claude-plugin/plugin.json +7 -0
  262. package/plugins/claude-code/fleet-status/hooks/hooks.json +1 -0
  263. package/plugins/claude-code/fleet-status/hooks/register.tsx +906 -0
  264. package/plugins/claude-code/fleet-status/types/index.d.ts +88 -0
  265. package/skills/fleet/auth-bitbucket.md +47 -20
  266. package/skills/fleet/onboarding.md +1 -1
  267. package/skills/fleet/skill-matrix.md +3 -3
  268. package/version.json +1 -1
@@ -38,7 +38,7 @@
38
38
  // parsed (vcs-module.mjs's own header comment). These two names were imported
39
39
  // by runner.js for exactly this call before the move.
40
40
  import { classifyFailure, toGitVerdict, commandBinary } from './vcs-module.mjs';
41
- import { VCS_FAILURE_KINDS } from './errors.mjs';
41
+ import { VCS_FAILURE_KINDS, GitSyncError } from './errors.mjs';
42
42
 
43
43
  // ---------------------------------------------------------------------------
44
44
  // Multi-member topology precondition
@@ -541,3 +541,114 @@ export function commandResultToSoftGit(res) {
541
541
  const ok = exitCode !== undefined ? exitCode === 0 : !(res && res.isError);
542
542
  return { ok, stdout: text, error: ok ? undefined : (text || 'unknown error') };
543
543
  }
544
+
545
+ // ---------------------------------------------------------------------------
546
+ // Review diff base
547
+ // ---------------------------------------------------------------------------
548
+ //
549
+ // The reviewer prompts name a diff range. The member's LOCAL base branch is
550
+ // never updated by the engine (only origin/<base> is fetched), so on an old
551
+ // clone `<base>..<branch>` spans many unrelated commits; and a plain
552
+ // `origin/<base>..<branch>` is wrong too once origin/<base> moves during the
553
+ // sprint (a two-dot diff shows those base commits reversed). The fork point --
554
+ // `git merge-base origin/<base> <branch>` after a fresh fetch of <base> -- is
555
+ // the range that shows exactly the sprint's own changes.
556
+ //
557
+ // Runs on the REVIEWER's member (the checkout the reviewer diffs in), through
558
+ // runGitStep so an auth failure gets the same one-shot self-heal. Any failure
559
+ // throws: there is deliberately no fallback to the local base branch.
560
+
561
+ const REVIEW_BASE_SHA_RE = /^[0-9a-f]{40,64}$/i;
562
+
563
+ /**
564
+ * @param {{ command: Function, member: string, baseBranch: string, branch: string, log?: Function,
565
+ * onAuthFailure?: Function, resolveMemberProvider?: (member: string) => Promise<string|undefined> }} opts
566
+ * @returns {Promise<string>} the merge-base commit SHA
567
+ */
568
+ export async function resolveReviewMergeBase({ command, member, baseBranch, branch, log = () => {}, onAuthFailure, resolveMemberProvider }) {
569
+ if (typeof command !== 'function') throw new Error('resolveReviewMergeBase requires an injected command()');
570
+ if (!member || !baseBranch || !branch) {
571
+ throw new GitSyncError(
572
+ `[Review Base] cannot compute the review diff base: member, base branch and branch are all required (got member='${member}', base='${baseBranch}', branch='${branch}').`,
573
+ { member: member || null },
574
+ );
575
+ }
576
+ const provider = await resolveGitProviderForClassification(resolveMemberProvider, member, log);
577
+ const fetchCmd = `git fetch origin ${baseBranch}`;
578
+ const fetchRes = await runGitStep({
579
+ command, member, cmd: fetchCmd,
580
+ label: `Fetch base branch '${baseBranch}' for the review diff base`,
581
+ log, maxTransientRetries: 1, onAuthFailure, provider,
582
+ });
583
+ if (!fetchRes.ok) {
584
+ throw new GitSyncError(
585
+ `[Review Base] ${fetchCmd} failed on member '${member}', so the review diff base cannot be computed (no fallback to the local '${baseBranch}'): ${fetchRes.error}`,
586
+ { member, gitOutput: fetchRes.error, details: { baseBranch, branch, kind: fetchRes.kind } },
587
+ );
588
+ }
589
+ const mergeBaseCmd = `git merge-base origin/${baseBranch} ${branch}`;
590
+ const mbRes = await runGitStep({
591
+ command, member, cmd: mergeBaseCmd,
592
+ label: `Merge base of origin/${baseBranch} and '${branch}' for the review diff`,
593
+ log, maxTransientRetries: 1, onAuthFailure, provider,
594
+ });
595
+ if (!mbRes.ok) {
596
+ throw new GitSyncError(
597
+ `[Review Base] ${mergeBaseCmd} failed on member '${member}': ${mbRes.error}`,
598
+ { member, gitOutput: mbRes.error, details: { baseBranch, branch, kind: mbRes.kind } },
599
+ );
600
+ }
601
+ const raw = String(mbRes.output ?? '');
602
+ // The last SHA-shaped line: tolerates stderr/profile noise around it.
603
+ const shaLines = raw.split(/\r?\n/).map((l) => l.trim()).filter((l) => REVIEW_BASE_SHA_RE.test(l));
604
+ const sha = shaLines.length ? shaLines[shaLines.length - 1] : '';
605
+ if (!REVIEW_BASE_SHA_RE.test(sha)) {
606
+ throw new GitSyncError(
607
+ `[Review Base] ${mergeBaseCmd} on member '${member}' did not return a commit SHA (output: ${JSON.stringify(raw)}).`,
608
+ { member, gitOutput: raw, details: { baseBranch, branch } },
609
+ );
610
+ }
611
+ log(`[Review Base] review diff base for '${branch}' on member '${member}': ${sha} (merge-base with origin/${baseBranch}).`);
612
+ return sha;
613
+ }
614
+
615
+ /**
616
+ * Final Review's review diff base: `resolve(member)` (resolveReviewMergeBase
617
+ * bound to the sprint), retried ONCE on a GitSyncError (any other error,
618
+ * e.g. a CancelledError, propagates unchanged). A second failure throws a GitSyncError
619
+ * that says the Final Review was not dispatched, that the sprint's pushed
620
+ * work is untouched, and how to relaunch. Never falls back to a local base.
621
+ *
622
+ * @param {(member: string) => Promise<string>} resolve
623
+ * @param {{ member: string, branch: string, baseBranch: string, log?: Function }} opts
624
+ * @returns {Promise<string>}
625
+ */
626
+ export async function resolveFinalReviewMergeBase(resolve, { member, branch, baseBranch, log = () => {} }) {
627
+ try {
628
+ return await resolve(member);
629
+ } catch (first) {
630
+ // Only a git-sync failure is retried and re-worded. Anything else --
631
+ // an operator cancel (CancelledError), a budget stop, a bug --
632
+ // propagates unchanged and is not retried.
633
+ if (!(first instanceof GitSyncError)) throw first;
634
+ log(`[Review Base] Final Review: could not compute the review diff base on member '${member}' (${first.message}) -- retrying once.`);
635
+ try {
636
+ return await resolve(member);
637
+ } catch (second) {
638
+ if (!(second instanceof GitSyncError)) throw second;
639
+ const message =
640
+ `[Review Base] Final Review was NOT dispatched: the review diff base (git merge-base origin/${baseBranch} ${branch}) ` +
641
+ `could not be computed on member '${member}' after one retry, and the review never falls back to the local '${baseBranch}' branch. ` +
642
+ `Cause: ${second && second.message} ` +
643
+ `No work is lost: the sprint's commits are on the remote branch '${branch}' and closed beads stay closed. ` +
644
+ `Fix the fetch on member '${member}', then relaunch the sprint on the same branch '${branch}' with base '${baseBranch}'.`;
645
+ log(message);
646
+ throw new GitSyncError(message, {
647
+ member,
648
+ gitOutput: second && second.gitOutput ? second.gitOutput : null,
649
+ details: { baseBranch, branch, stage: 'final-review-base' },
650
+ cause: second,
651
+ });
652
+ }
653
+ }
654
+ }
@@ -209,11 +209,13 @@ export const GUARDED_MODULES = [
209
209
  // guard's `files` output against guardedModuleBasenames().
210
210
  //
211
211
  // harvest.mjs took NO member_name-bearing command() call site out of
212
- // runner.js -- the docs/sprint-analysis commits are made by the
212
+ // runner.js -- the docs/README commits are made by the
213
213
  // DISPATCHED harvester inside its own repo and published by the 'harvester'
214
214
  // policy row's pushCode/pushBeads bracket -- but it took ONE dispatchRole()
215
215
  // site (the harvester ladder), which is what dispatch-safety-guard and the
216
- // phase 3 dispatch census read.
216
+ // phase 3 dispatch census read. It later gained ONE member_name-bearing
217
+ // command() site of its own: the pre-dispatch git exclude of the
218
+ // uncommitted analysis document on the harvester's member.
217
219
  //
218
220
  // publish-pr.mjs is the opposite shape and the more urgent of the two to
219
221
  // register: it took TWO member_name-bearing command() call sites out of
@@ -416,6 +418,18 @@ export const GUARDED_MODULES = [
416
418
  // Per-dispatch kb_* and code_* accounting: reads session_stats through the
417
419
  // injected memberCall around each dispatch. No command() or agent() site.
418
420
  'dispatch-accounting.mjs',
421
+ // NEEDS-DECISION recording: member_name-bearing command() sites (the
422
+ // decision bead create and the work-bead note, each staged through
423
+ // stageCommandBodyMemberSide), no agent(), no push of its own (callers
424
+ // D-push through gitSync).
425
+ 'decisions.mjs',
426
+ // The NEEDS-DECISION wait: member_name-bearing command() sites (the
427
+ // decision-bead poll reads, bd human respond, the work-bead note), no
428
+ // agent(); its beads pull/push go through injected gitSync callbacks.
429
+ 'decision-wait.mjs',
430
+ // Operator notification for a pending decision: no command() or agent()
431
+ // site (sends through the injected fleet client), zero baseline.
432
+ 'decision-notify.mjs',
419
433
  // The per-member sprint-init probe: kb_*/code_* calls through the injected
420
434
  // memberCall, member_detail on the orchestrator session, and ONE
421
435
  // member-bound command channel (fleetApi.executeCommand, command strings
@@ -427,6 +441,12 @@ export const GUARDED_MODULES = [
427
441
  // Verify-block deadlock diagnosis (pure): no command() or agent() site;
428
442
  // runner.js owns the runbook probes, the stop and the mid-run exit.
429
443
  'verify-block.mjs',
444
+ // Pre-launch stale-claim rule, fresh-read gate and downstream naming
445
+ // (pure): no command() or agent() site; runner.js owns the read and write.
446
+ 'beads-reachability.mjs',
447
+ // Run-scoped set-aside stall decision and report section (pure): no
448
+ // command() or agent() site; runner.js owns the reads and the throw.
449
+ 'set-aside.mjs',
430
450
  'vcs-providers/azure-devops.mjs',
431
451
  'vcs-providers/bitbucket.mjs',
432
452
  'vcs-providers/dolt.mjs',
@@ -511,6 +531,20 @@ export const GUARD_REGISTRATION_EXEMPT = {
511
531
  'deliberately emits `$HOME`, `$env:USERPROFILE`, `$env:TEMP` and `$( )` because it IS the ' +
512
532
  'OS-branched command surface the shell-command invariant tells everyone else to route ' +
513
533
  'through; scanning it would report its entire reason for existing as violations.',
534
+ // beads-lock-probe.mjs: the per-OS/shell builder of the beads
535
+ // lock-holder probe (a POSIX script with `$( )` and a PowerShell script
536
+ // with `$_`), the same kind of OS-branched command surface.
537
+ 'beads-lock-probe.mjs':
538
+ 'deliberately emits `$( )` (POSIX) and `$_` (PowerShell) because it IS the OS-branched ' +
539
+ 'builder of the beads lock-holder probe; scanning it would report its entire reason for ' +
540
+ 'existing as violations.',
541
+ // bd-sync-command.mjs: the per-OS/shell builder of the bd sync command
542
+ // string (the Windows GOMAXPROCS assignment), the same kind of
543
+ // OS-branched command surface as the shell builders above.
544
+ 'bd-sync-command.mjs':
545
+ 'deliberately emits the PowerShell `$env:GOMAXPROCS=` assignment because it IS the ' +
546
+ 'OS-branched builder of the bd sync command string; scanning it would report its entire ' +
547
+ 'reason for existing as violations.',
514
548
  // dolt-sync.mjs -- reason reused verbatim from the same header (do not
515
549
  // re-derive it).
516
550
  'dolt-sync.mjs':