@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
@@ -42,14 +42,16 @@ The embedded `bd` binary does NOT ship enough of the Dolt CLI to drive a
42
42
  merge-conflict resolution over SQL -- that requires the real `dolt` binary and
43
43
  a real `dolt sql-server` process, temporarily, against the SAME data directory.
44
44
 
45
- CORRECTED 2026-08-13 (`dolt-sync-redesign.md` Part 5, Precondition V2). This
46
- step previously said `winget install --id DoltHub.Dolt` on Windows, plus
47
- `apt`/`brew` on POSIX. That was a genuine mistake and must not be repeated:
48
- winget delivered a STALE 1.86.3 build while this repo carries its own version
49
- pin, so an OS package manager is a second, unpinned version channel -- banned
50
- from every code path and runbook this design owns. It also created a PATH
51
- problem of its own: a winget-installed binary is invisible to processes that
52
- started before the install, which is every SSH-dispatched session.
45
+ **Never install it with an OS package manager** (`winget`, `apt`, `brew`).
46
+ Two independent reasons, both load-bearing (see `dolt-sync-redesign.md`
47
+ Part 5, Precondition V2):
48
+
49
+ - A package manager is a second, unpinned version channel. It will happily
50
+ deliver a build older than this repo's own version pin, and the landmines
51
+ this procedure works around are version-specific.
52
+ - A freshly package-manager-installed binary is invisible to processes that
53
+ started before the install -- which is every SSH-dispatched session, so the
54
+ install appears to succeed and the binary still cannot be found.
53
55
 
54
56
  The fleet's ONE pinned channel is the same GitHub release asset
55
57
  `src/cli/dolt-install.ts` uses (`DOLT_VERSION`, currently `v2.2.0`), landed at
@@ -1,13 +1,18 @@
1
1
  # Dolt sync redesign: from a 3-tier recovery ladder to one deterministic settle step
2
2
 
3
- Status: BEING IMPLEMENTED on branch `fix/dolt-settle-recovery` (written
4
- 2026-08-13). Per-part implementation status is tracked in "Implementation
5
- status" immediately below; Part 4's verification table is the live-run record.
3
+ Status: IMPLEMENTED. Every part of this design has landed. The document is
4
+ retained as the reference for WHY the system is shaped this way, and the
5
+ source cites its Part numbers directly (`dolt-settle.mjs`, `dolt-sync.mjs`,
6
+ `runner.js`, `bin/serve.mjs`, `src/supervisor/server.mjs`,
7
+ `dolt-orphan-sweep.mjs`, `dolt-mutex.mjs`, `fleet-members.mjs`, and several
8
+ tests), so **the Part numbering here is load-bearing -- do not renumber it.**
9
+ Part 4's table is the live-run verification record.
10
+
6
11
  See `dolt-manual-recovery-verified.md` for the live-verified mechanical spec
7
12
  (exact flags, exact commands, exact OS-specific detachment technique) this
8
13
  design's `settle()` step is built from.
9
14
 
10
- ### Implementation status
15
+ ### What landed, part by part
11
16
 
12
17
  | Part | Item | Status |
13
18
  |------|------|--------|
@@ -7,8 +7,8 @@ Status: design -- not yet implemented. Last updated: 2026-08-10.
7
7
  auto-repair, then resume) or a cleanly dead one (abort with a diagnosis report and, where needed,
8
8
  a specific human referral) -- never leave it wedged, silently burning tokens, or ambiguous.
9
9
 
10
- > **Supersedes `coach-role-design.md`** (the 2026-07-20 "coach role: just-in-time error
11
- > resolution" design note, now reduced to a pointer here). sprint-doctor is the same core idea --
10
+ > **Supersedes the earlier "coach role" design note** ("coach role: just-in-time error
11
+ > resolution"), which this doc replaces in full. sprint-doctor is the same core idea --
12
12
  > an in-workflow LLM layer for failures the deterministic engine did not foresee, positioned
13
13
  > strictly AFTER typed handlers/ladders, failing loudly when it cannot fix -- carried further.
14
14
  > Ideas incorporated directly from coach, credited inline where they appear: the three-layer
@@ -6,19 +6,19 @@ Source doc path: `packages/apra-fleet-se/fleet-sprint/docs/shared-orchestrator-r
6
6
 
7
7
  ## Problem recap
8
8
 
9
- Every fleet-sprint launch resolves an `orchestrator` pseudo-role (runner.js:73
10
- `ROLE_ORCHESTRATOR`, runner.js:4938 `orchestratorMember = getMemberForRole(ROLE_ORCHESTRATOR)`)
9
+ Every fleet-sprint launch resolves an `orchestrator` pseudo-role
10
+ (`ROLE_ORCHESTRATOR` / `getMemberForRole(ROLE_ORCHESTRATOR)` in `runner.js`)
11
11
  whose beads clone is the sprint's ground truth for all scope reads and bd mutations. Absent an
12
12
  explicit `--role-map '{"orchestrator":[...]}'`, this silently defaults to
13
- `unmappedRoleFallbackPool[0]` (runner.js:4915-4920) -- for a single-member sprint, the dispatch
13
+ `unmappedRoleFallbackPool[0]` -- for a single-member sprint, the dispatch
14
14
  member itself. Two production incidents followed: beads created on the interactive operator
15
15
  machine's clone were invisible to sprints whose accidental orchestrator was a different,
16
16
  never-synced member.
17
17
 
18
18
  The naive fix (role-map a hub member as orchestrator on every launch) deadlocks concurrency:
19
19
  the launch overlap guard unions `--members` with every roleMap value INCLUDING orchestrator
20
- (api.mjs:103-117 `memberUnion`, api.mjs:133-141), so a shared orchestrator member would 409
21
- every second concurrent launch (api.mjs:202-207). The operator's proposal: the supervisor holds
20
+ (`memberUnion` in `src/supervisor/api.mjs`), so a shared orchestrator member would 409
21
+ every second concurrent launch. The operator's proposal: the supervisor holds
22
22
  a standing, shared, orchestrator-role-only reservation on one designated member and injects it
23
23
  as the default orchestrator into every launch.
24
24
 
@@ -116,8 +116,8 @@ exclusivity was never what protected orchestrator-role dolt writes; the mutex wa
116
116
 
117
117
  - **Supervisor ledger** (src/supervisor/ledger.mjs): per-sprint entries
118
118
  `{ members, issueRoots, childPid, reservedAt, branch, base, goal, exit*, logPath }`
119
- (ledger.mjs:65-108), claimed and released in exact lockstep with the sprint lifecycle
120
- (ledger.mjs:21-29, claim at 461-477, release at 485-499), atomically persisted, PID-probe
119
+ -- claimed and released in exact lockstep with the sprint lifecycle
120
+ (`claim()`/`release()` in `ledger.mjs`), atomically persisted, PID-probe
121
121
  reconciled on restart. Everything about it is sprint-lifecycle-scoped.
122
122
  - **Launch overlap guard** (api.mjs:162-209): all-or-nothing 409 on any member of the incoming
123
123
  union (members + every roleMap value, orchestrator included) overlapping any live ledger
@@ -138,7 +138,7 @@ exclusivity was never what protected orchestrator-role dolt writes; the mutex wa
138
138
 
139
139
  ### A4. Interaction with in-flight work (pause/resume `apra-fleet-p2to`, sprint-doctor `apra-fleet-iiny`)
140
140
 
141
- Pause/resume's reservation logic (escalate-to-llm-design.md:520-533) releases each member via
141
+ Pause/resume's reservation logic (escalate-to-llm-design.md) releases each member via
142
142
  owner-checked `member_reservation release` on pause and re-reserves on resume, failing resume
143
143
  cleanly when a member was taken. This operates on the sprint's OWN per-sprint reservation set.
144
144
  Under this design the pinned member is deliberately NOT in that set (D1), so pause/resume never
@@ -149,7 +149,7 @@ points**:
149
149
 
150
150
  1. **Sprint-doctor's wedged-reservation remedy is NOT orthogonal.** The doctor's remedy table
151
151
  allows `member_reservation force_release` when a member is "reserved by a sprint id whose
152
- pid/ledger entry is dead" (escalate-to-llm-design.md:679). The pin sentinel has no pid and
152
+ pid/ledger entry is dead" (escalate-to-llm-design.md). The pin sentinel has no pid and
153
153
  no ledger entry -- to that heuristic it looks exactly like a wedged dead reservation, and a
154
154
  doctor run would strip the pin. The doctor rule must learn: a reservation whose owner
155
155
  matches the supervisor pin sentinel prefix is never force-releasable (and the supervisor
@@ -204,9 +204,9 @@ After D0, the orchestrator's entire command surface is `bd`/`bd dolt` via execut
204
204
 
205
205
  **Why not a shared/`exclusive:false` reservation TYPE in the ledger:** every ledger invariant
206
206
  is sprint-lifecycle-shaped -- claim/release in lockstep with one sprint's launch/terminal
207
- events (ledger.mjs:21-29), a `childPid` for restart PID-probe reconciliation (ledger.mjs:70-71),
207
+ events, a `childPid` for restart PID-probe reconciliation,
208
208
  release driven by watchdog/reconcile/Stop (`POST /api/reservations/:sprintId/force-release`,
209
- dashboard.mjs:279-282 per escalate-to-llm-design.md:521). A permanent, sprint-less, shared
209
+ `src/supervisor/dashboard.mjs`, per escalate-to-llm-design.md). A permanent, sprint-less, shared
210
210
  entry violates all of it: it has no pid to probe, must survive every reconciliation pass, must
211
211
  be skipped by the overlap guard, and must never be force-released by the Stop path. That is
212
212
  not a reservation with a flag -- it is a different object with a different lifecycle, and
@@ -286,7 +286,7 @@ is a documented follow-up, not a blocker.
286
286
  (`FLEET_SE_DATA_DIR`, default `~/.apra-fleet-se`, ledger.mjs:177-181), e.g.
287
287
  `supervisor-config.json`: `{ "pinnedRoles": { "orchestrator": ["memberA", "memberB"] } }`.
288
288
  Generic shape (role -> ordered member list); only `orchestrator` is honored initially.
289
- - **Flag**: `fleet-se serve --pin-orchestrator <member[,member...]>` overriding the file
289
+ - **Flag**: `fleet-se-serve --pin-orchestrator <member[,member...]>` overriding the file
290
290
  (serve.mjs currently takes only `--port`, serve.mjs:52-62 -- room to grow).
291
291
  - **API**: `GET /api/config/pinned-roles` (consumed by dashboard, launch form, and the CLI
292
292
  follow-up) and `PUT` for runtime changes (re-runs sentinel reserve/release accordingly).
@@ -1,9 +1,19 @@
1
1
  # Auto-Sprint Stabilization Log
2
2
 
3
- Running log of issues found while driving the real `apra-fleet-eft` sprint
4
- (member: fleet-rev, branch `auto-sprint/eft-service`, base `feat/fleet-reorg`)
5
- per `docs/README.md`, and the fixes made for each. Newest entries at the
6
- bottom. Each entry: symptom -> root cause -> fix -> evidence.
3
+ A closed historical log from the stabilization push that first drove
4
+ fleet-sprint against a real sprint end to end. Each numbered entry records
5
+ one defect as symptom -> root cause -> fix -> evidence, and most carry a
6
+ **Lesson** paragraph -- that is the durable part.
7
+
8
+ Read it as an archive, not as current documentation: entries name the
9
+ branches, commits and beads of the run they were written during, and the code
10
+ they describe has moved on since. It is kept for two reasons -- those Lesson
11
+ paragraphs, and the fact that regression tests elsewhere in this repo cite
12
+ these entries by number as the reason they exist (for example
13
+ `packages/apra-fleet-client/test/transport-idle-timeout-guard.test.mjs` cites
14
+ Issue 8). **The Issue numbering is therefore load-bearing: do not renumber or
15
+ remove entries.** New findings belong in the relevant design doc or a bead,
16
+ not appended here.
7
17
 
8
18
  ## Loop iteration 1 (2026-07-19)
9
19