@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
@@ -33,6 +33,8 @@ export interface FleetSeProbes {
33
33
  commandLine: (pid: number) => string | null;
34
34
  /** Parsed JSON body of a 200 response, or null (refused, timeout, non-200, bad JSON). */
35
35
  getJson: (url: string) => Promise<unknown>;
36
+ /** This process's own pid; a lock holding it is never a running sprint. */
37
+ selfPid: () => number;
36
38
  }
37
39
  export declare const realFleetSeProbes: FleetSeProbes;
38
40
  /**
@@ -40,6 +42,12 @@ export declare const realFleetSeProbes: FleetSeProbes;
40
42
  * unexpected detection error (the caller then warns and proceeds).
41
43
  */
42
44
  export declare function detectRunningFleetSe(probes?: FleetSeProbes): Promise<RunningFleetSe>;
45
+ /**
46
+ * The args of the step-3 rerun line. When a live apra-fleet server is recorded
47
+ * the rerun must carry --force (once), or the running-server check refuses the
48
+ * copied command again; with no live server the args are unchanged.
49
+ */
50
+ export declare function fleetSeRerunArgs(args: string[], liveServer: boolean): string[];
43
51
  /** The refusal printed when fleet-se work is running. */
44
52
  export declare function fleetSeRefusalText(found: RunningFleetSe, opts: {
45
53
  platform: NodeJS.Platform;
@@ -72,6 +72,7 @@ export const realFleetSeProbes = {
72
72
  isPidAlive,
73
73
  commandLine: processCommandLine,
74
74
  getJson: getJsonWithTimeout,
75
+ selfPid: () => process.pid,
75
76
  };
76
77
  function isEnoent(err) {
77
78
  return err?.code === 'ENOENT';
@@ -118,7 +119,7 @@ export async function detectRunningFleetSe(probes = realFleetSeProbes) {
118
119
  continue;
119
120
  throw err;
120
121
  }
121
- if (!Number.isInteger(pid) || pid <= 0 || pid === process.pid || !probes.isPidAlive(pid))
122
+ if (!Number.isInteger(pid) || pid <= 0 || pid === probes.selfPid() || !probes.isPidAlive(pid))
122
123
  continue;
123
124
  const cmd = probes.commandLine(pid);
124
125
  if (cmd === null) {
@@ -152,10 +153,22 @@ export async function detectRunningFleetSe(probes = realFleetSeProbes) {
152
153
  }
153
154
  return { supervisor, sprints: [...sprints.values()], warnings };
154
155
  }
156
+ /**
157
+ * The args of the step-3 rerun line. When a live apra-fleet server is recorded
158
+ * the rerun must carry --force (once), or the running-server check refuses the
159
+ * copied command again; with no live server the args are unchanged.
160
+ */
161
+ export function fleetSeRerunArgs(args, liveServer) {
162
+ return liveServer && !args.includes('--force') ? [...args, '--force'] : args;
163
+ }
155
164
  /** The refusal printed when fleet-se work is running. */
156
165
  export function fleetSeRefusalText(found, opts) {
157
166
  const serveScript = opts.serveScript ?? INSTALLED_SERVE_SCRIPT;
158
167
  const curl = opts.platform === 'win32' ? 'curl.exe' : 'curl';
168
+ // The supervisor refuses a mutating request without a JSON content type
169
+ // (cross-site request guard); the double-quoted header works unchanged in
170
+ // cmd.exe, PowerShell and POSIX shells.
171
+ const jsonHeader = '-H "Content-Type: application/json"';
159
172
  const sup = found.supervisor;
160
173
  const base = sup ? `http://localhost:${sup.port}` : `http://localhost:${DEFAULT_SUPERVISOR_PORT}`;
161
174
  const running = [];
@@ -170,19 +183,22 @@ export function fleetSeRefusalText(found, opts) {
170
183
  steps.push(' 1. Stop the running sprints or let them finish.');
171
184
  for (const s of found.sprints) {
172
185
  if (sup && s.sprintId)
173
- steps.push(` ${curl} -X POST ${base}/api/sprints/${s.sprintId}/stop`);
186
+ steps.push(` ${curl} -X POST ${base}/api/sprints/${s.sprintId}/stop ${jsonHeader}`);
174
187
  }
175
188
  if (found.sprints.some(s => !(sup && s.sprintId))) {
176
189
  steps.push(' A sprint started directly (apra-fleet workflow fleet-sprint) is stopped with Ctrl-C in its');
177
190
  steps.push(' console, or by ending its pid shown above. If that pid is not a fleet-sprint (a stale');
178
191
  steps.push(' lock whose pid was reused), delete the lock file instead.');
179
192
  }
193
+ steps.push(' A sprint stopped by an older fleet (0.4.3 and earlier) keeps its dashboard child alive for');
194
+ steps.push(' up to 300 seconds and holds its lock meanwhile, so this check keeps refusing until that');
195
+ steps.push(' child exits: wait up to 5 minutes and re-run, or end the pid shown above.');
180
196
  }
181
197
  else {
182
198
  steps.push(' 1. No sprint is running.');
183
199
  }
184
200
  steps.push(sup
185
- ? ` 2. Stop the supervisor:\n ${curl} -X POST ${base}/api/shutdown`
201
+ ? ` 2. Stop the supervisor:\n ${curl} -X POST ${base}/api/shutdown ${jsonHeader}`
186
202
  : ' 2. No supervisor is running.');
187
203
  steps.push(' 3. Upgrade:');
188
204
  for (const l of opts.rerunLines)
@@ -51,6 +51,15 @@ export declare function hasMemberInstallMarker(): boolean;
51
51
  * on (the server reads it back at launch, see resolveServerPort, and the
52
52
  * orchestrator reads it to build the member's MCP URL). */
53
53
  export declare function writeMemberInstallMarker(version: string, port?: number): void;
54
+ /**
55
+ * Records the port a FULL install was run with so `apra-fleet start`, the
56
+ * service launch and logon autostart (none of which carry APRA_FLEET_PORT)
57
+ * bind the port the MCP registration points at. A full install run without a
58
+ * valid APRA_FLEET_PORT removes the record: install is declarative, and a
59
+ * surviving record would keep serving a stale port while the registration it
60
+ * just wrote points at the default.
61
+ */
62
+ export declare function recordFullInstallPort(version: string, env?: string | undefined): void;
54
63
  export declare function clearMemberInstallMarker(): void;
55
64
  /**
56
65
  * Whether a `--member --force` install may stop the relevant running server.
@@ -39,6 +39,7 @@ import fs from 'node:fs';
39
39
  import path from 'node:path';
40
40
  import os from 'node:os';
41
41
  import { execSync } from 'node:child_process';
42
+ import { FULL_INSTALL_PORT_FILE, validPort } from '../paths.js';
42
43
  import { isPidAlive, isApraFleetProcess } from '../utils/process-utils.js';
43
44
  /** Data dir this process would use -- mirrors services/singleton.ts getFleetDir(). */
44
45
  export function getInstallDataDir() {
@@ -224,6 +225,29 @@ export function writeMemberInstallMarker(version, port) {
224
225
  // Best effort: a missing marker only makes the next forced member install refuse loudly.
225
226
  }
226
227
  }
228
+ /**
229
+ * Records the port a FULL install was run with so `apra-fleet start`, the
230
+ * service launch and logon autostart (none of which carry APRA_FLEET_PORT)
231
+ * bind the port the MCP registration points at. A full install run without a
232
+ * valid APRA_FLEET_PORT removes the record: install is declarative, and a
233
+ * surviving record would keep serving a stale port while the registration it
234
+ * just wrote points at the default.
235
+ */
236
+ export function recordFullInstallPort(version, env = process.env.APRA_FLEET_PORT) {
237
+ const file = path.join(getInstallDataDir(), FULL_INSTALL_PORT_FILE);
238
+ const port = validPort(env ?? '');
239
+ try {
240
+ if (port === undefined) {
241
+ fs.rmSync(file, { force: true });
242
+ return;
243
+ }
244
+ fs.mkdirSync(getInstallDataDir(), { recursive: true });
245
+ fs.writeFileSync(file, JSON.stringify({ version, installedAt: new Date().toISOString(), port }) + '\n');
246
+ }
247
+ catch {
248
+ // Best effort: without the record start falls back to the default port.
249
+ }
250
+ }
227
251
  export function clearMemberInstallMarker() {
228
252
  try {
229
253
  fs.rmSync(memberInstallMarkerPath(), { force: true });
@@ -24,6 +24,8 @@ export declare function _resetFleetSePrereqProbes(): void;
24
24
  export declare function _setFleetSeProbes(overrides: Partial<FleetSeProbes>): void;
25
25
  /** Test-only: restore the real running fleet-sprint guard probes. */
26
26
  export declare function _resetFleetSeProbes(): void;
27
+ /** Test-only: replace the live-server probe used by the fleet-sprint refusal. */
28
+ export declare function _setLiveServerProbe(probe: (() => boolean) | null): void;
27
29
  /** The probes the running fleet-sprint guard uses (shared with update.ts). */
28
30
  export declare function currentFleetSeProbes(): FleetSeProbes;
29
31
  export declare function fleetSeGuardEnabled(): boolean;
@@ -67,6 +69,7 @@ interface AssetManifest {
67
69
  autoSprintArgsSkill?: Record<string, string>;
68
70
  fleetSprintCliSkill?: Record<string, string>;
69
71
  fleetSupervisorSkill?: Record<string, string>;
72
+ claudePlugins?: Record<string, string>;
70
73
  }
71
74
  export declare function buildDevManifest(root: string): AssetManifest;
72
75
  /** Inject a manifest for tests - avoids SEA asset extraction. Pass null to restore default. */
@@ -179,5 +182,14 @@ export declare function resolveMemberInstallPort(args: string[], envPort: string
179
182
  } | {
180
183
  error: string;
181
184
  };
185
+ /** Restart-sessions text shown after an install that changed an MCP registration (ASCII only). */
186
+ export declare const ACCESS_RESTART_NOTE = "[!] Restart every open LLM CLI session (Claude Code, Codex, ...): sessions started before this install keep their old MCP registration without the access secret, and the server refuses them (Claude Code shows \"Dynamic Client Registration rejected (HTTP 404)\").";
187
+ /**
188
+ * Persist ACCESS_RESTART_NOTE as a pending service notice when an install
189
+ * changed a (non-member) registration. `shownInline` (stdout is a console)
190
+ * marks it already shown, so an interactive install does not repeat it on the
191
+ * next service verb; a detached install (apra-fleet update) leaves it pending.
192
+ */
193
+ export declare function recordAccessRestartNotice(changed: boolean, shownInline: boolean, file?: string): void;
182
194
  export declare function runInstall(args: string[]): Promise<void>;
183
195
  //# sourceMappingURL=install.d.ts.map
@@ -14,12 +14,14 @@ import { FLEET_DIR } from '../paths.js';
14
14
  import { extractWorkflowSubsystemAssets } from './workflow-assets.js';
15
15
  import { downloadAndExtractDolt, verifyDolt } from './dolt-install.js';
16
16
  import { installBeads } from './beads-install.js';
17
- import { classifyRunningServer, relevantServerPids, getInstallDataDir, memberForceMayStop, fullInstallRefusalText, selfInvocationLines, writeMemberInstallMarker, clearMemberInstallMarker, FORCE_STOP_FULL_INSTALL_FLAG, } from './install-guard.js';
18
- import { detectRunningFleetSe, fleetSeRefusalText, realFleetSeProbes, IGNORE_RUNNING_SPRINTS_FLAG } from './fleet-se-guard.js';
19
- import { writeServiceNotice, clearServiceNoticeContaining } from '../services/service-notice.js';
17
+ import { classifyRunningServer, relevantServerPids, getInstallDataDir, memberForceMayStop, fullInstallRefusalText, selfInvocationLines, writeMemberInstallMarker, clearMemberInstallMarker, recordFullInstallPort, FORCE_STOP_FULL_INSTALL_FLAG, } from './install-guard.js';
18
+ import { detectRunningFleetSe, fleetSeRefusalText, fleetSeRerunArgs, realFleetSeProbes, IGNORE_RUNNING_SPRINTS_FLAG } from './fleet-se-guard.js';
19
+ import { writeServiceNotice, appendServiceNotice, clearServiceNoticeContaining, SERVICE_NOTICE_PATH } from '../services/service-notice.js';
20
20
  import { convertClaudeAllowToAgyPermissions, formatAgyPermissionRules } from '../providers/agy.js';
21
+ import { isPidAlive } from '../utils/process-utils.js';
21
22
  import { codeIntelPathWarning } from '../utils/find-on-path.js';
22
23
  import { gitBashCandidates } from '../os/git-bash-candidates.js';
24
+ import { CLAUDE_MOD_PLUGIN, CLAUDE_MOD_SOURCE_DIR, claudeModRegistered, claudeModStepEnabled, installClaudeMod, isApraFleetStatusLine, isClaudeModRuntimeFile, removeApraFleetStatusLine, } from './claude-mod.js';
23
25
  const realDoltStepDeps = { downloadAndExtractDolt, verifyDolt };
24
26
  let doltStepDeps = realDoltStepDeps;
25
27
  /** Test-only: inject fakes for the dolt CLI install step's download/verify calls. */
@@ -86,6 +88,24 @@ export function _setFleetSeProbes(overrides) {
86
88
  export function _resetFleetSeProbes() {
87
89
  fleetSeProbes = realFleetSeProbes;
88
90
  }
91
+ /**
92
+ * True when a live apra-fleet server relevant to THIS install is recorded -- the
93
+ * same classification the running-server guard uses. The fleet-sprint refusal
94
+ * reads it to put --force on its rerun line. Overridable for tests.
95
+ */
96
+ function realLiveServerProbe() {
97
+ try {
98
+ return (isSea() || isNpmGlobalInstall()) && isApraFleetRunning() && classifyRunningServer(BIN_DIR)?.relevant === true;
99
+ }
100
+ catch {
101
+ return false;
102
+ }
103
+ }
104
+ let liveServerProbe = realLiveServerProbe;
105
+ /** Test-only: replace the live-server probe used by the fleet-sprint refusal. */
106
+ export function _setLiveServerProbe(probe) {
107
+ liveServerProbe = probe ?? realLiveServerProbe;
108
+ }
89
109
  /** The probes the running fleet-sprint guard uses (shared with update.ts). */
90
110
  export function currentFleetSeProbes() { return fleetSeProbes; }
91
111
  export function fleetSeGuardEnabled() {
@@ -444,11 +464,19 @@ export function buildDevManifest(root) {
444
464
  ...(fs.existsSync(helloWorldDir) ? collectPackageTree(root, helloWorldDir, 'hello-world') : {}),
445
465
  };
446
466
  }
467
+ // fleet-status Claude Code mod (mirrors scripts/gen-sea-config.mjs's
468
+ // claudePlugins section): runtime files only, keyed '<plugin>/<rel path>'.
469
+ const claudePlugins = {};
470
+ const modRaw = collectFilesRec(path.join(root, ...CLAUDE_MOD_SOURCE_DIR.split('/')), CLAUDE_MOD_SOURCE_DIR, CLAUDE_MOD_SOURCE_DIR);
471
+ for (const [rel, diskPath] of Object.entries(modRaw)) {
472
+ if (isClaudeModRuntimeFile(rel))
473
+ claudePlugins[`${CLAUDE_MOD_PLUGIN}/${rel}`] = diskPath;
474
+ }
447
475
  const vf = JSON.parse(fs.readFileSync(path.join(root, 'version.json'), 'utf-8'));
448
476
  return {
449
477
  version: vf.version, hooks, scripts, skills, fleetSkills, agents, workflows,
450
478
  workflowRuntime, agentSchemas, builtinWorkflows, autoSprintArgsSkill,
451
- fleetSprintCliSkill, fleetSupervisorSkill,
479
+ fleetSprintCliSkill, fleetSupervisorSkill, claudePlugins,
452
480
  };
453
481
  }
454
482
  let _manifestOverride = null;
@@ -629,8 +657,16 @@ function mergePermissions(paths, extraPerms = []) {
629
657
  }
630
658
  writeConfig(paths, settings);
631
659
  }
660
+ /**
661
+ * Point the provider's statusLine at apra-fleet's statusline script -- unless
662
+ * the user already has a statusLine of their own (one whose command is not
663
+ * apra-fleet's script), which is never overwritten. Returns 'kept-foreign'
664
+ * in that case so the caller can say so.
665
+ */
632
666
  function configureStatusline(paths, scriptPath, llm) {
633
667
  const settings = readConfig(paths);
668
+ if (settings.statusLine && !isApraFleetStatusLine(settings.statusLine))
669
+ return 'kept-foreign';
634
670
  let command;
635
671
  if (process.platform === 'win32') {
636
672
  if (llm === 'agy') {
@@ -657,6 +693,17 @@ function configureStatusline(paths, scriptPath, llm) {
657
693
  command,
658
694
  };
659
695
  writeConfig(paths, settings);
696
+ return 'written';
697
+ }
698
+ /**
699
+ * The fleet-status mod's runtime files from the asset manifest (SEA or dev),
700
+ * relative to the mod folder. Empty when this build does not package the mod.
701
+ */
702
+ function claudeModFiles(manifest) {
703
+ const prefix = `${CLAUDE_MOD_PLUGIN}/`;
704
+ return Object.entries(manifest.claudePlugins ?? {})
705
+ .filter(([key]) => key.startsWith(prefix))
706
+ .map(([key, assetKey]) => ({ relPath: key.slice(prefix.length), content: extractAssetBuffer(assetKey) }));
660
707
  }
661
708
  function mergeAgyConfig(paths, mcpConfig) {
662
709
  const configDir = path.join(os.homedir(), '.gemini', 'config');
@@ -1091,6 +1138,20 @@ export function resolveMemberInstallPort(args, envPort, recordedPort) {
1091
1138
  }
1092
1139
  return { port: env ?? recordedPort ?? BUILTIN_DEFAULT_PORT, explicit: false };
1093
1140
  }
1141
+ /** Restart-sessions text shown after an install that changed an MCP registration (ASCII only). */
1142
+ export const ACCESS_RESTART_NOTE = '[!] Restart every open LLM CLI session (Claude Code, Codex, ...): sessions started before this install keep their old MCP registration without the access secret, and the server refuses them (Claude Code shows "Dynamic Client Registration rejected (HTTP 404)").';
1143
+ /**
1144
+ * Persist ACCESS_RESTART_NOTE as a pending service notice when an install
1145
+ * changed a (non-member) registration. `shownInline` (stdout is a console)
1146
+ * marks it already shown, so an interactive install does not repeat it on the
1147
+ * next service verb; a detached install (apra-fleet update) leaves it pending.
1148
+ */
1149
+ export function recordAccessRestartNotice(changed, shownInline, file = SERVICE_NOTICE_PATH) {
1150
+ if (!changed)
1151
+ return;
1152
+ // Append, never overwrite: registration may have left unshown legacy-task guidance.
1153
+ appendServiceNotice(ACCESS_RESTART_NOTE, file, new Date(), shownInline);
1154
+ }
1094
1155
  export async function runInstall(args) {
1095
1156
  // --help / -h guard - must come first, before any side effects (#142)
1096
1157
  if (args.includes('--help') || args.includes('-h')) {
@@ -1312,7 +1373,7 @@ Options:
1312
1373
  });
1313
1374
  const text = fleetSeRefusalText(found, {
1314
1375
  platform: process.platform,
1315
- rerunLines: self(args),
1376
+ rerunLines: self(fleetSeRerunArgs(args, liveServerProbe())),
1316
1377
  ignoreLines: self([...args, IGNORE_RUNNING_SPRINTS_FLAG]),
1317
1378
  });
1318
1379
  console.error(text);
@@ -1372,6 +1433,11 @@ Nothing was installed.
1372
1433
  // binary-copy step can bring it back up instead of leaving it down.
1373
1434
  let guardServiceMgr = null;
1374
1435
  let guardStoppedService = false;
1436
+ // The service manager's stop() resolved false: a server pid was left running
1437
+ // because it could not be verified as apra-fleet (so it was not killed).
1438
+ let guardStopLeftRunning = false;
1439
+ // The guard restarted the service itself (no final service step to do it).
1440
+ let guardRestartedService = false;
1375
1441
  if (runningScope?.relevant) {
1376
1442
  if (!force) {
1377
1443
  const killHint = process.platform === 'win32'
@@ -1416,8 +1482,10 @@ ${killHint}
1416
1482
  // A service is registered: stop the SERVICE, never pkill first.
1417
1483
  console.log(' Registered service detected -- stopping it through the service manager.');
1418
1484
  try {
1419
- await guardServiceMgr.stop();
1485
+ const stopped = await guardServiceMgr.stop({ reason: 'install' });
1420
1486
  guardStoppedService = true;
1487
+ if (stopped === false)
1488
+ guardStopLeftRunning = true;
1421
1489
  }
1422
1490
  catch (err) {
1423
1491
  console.warn(` Service stop failed: ${err.message}`);
@@ -1458,9 +1526,28 @@ ${manualStopHint(pidsAfterStop)}
1458
1526
  `);
1459
1527
  process.exit(1);
1460
1528
  }
1461
- console.log(pidsBeforeStop.length > 0 || guardStoppedService
1462
- ? ' Stopped running server.'
1463
- : ' No running server process of this install was found to stop.');
1529
+ // The stop reported a pid it would not force-kill: do not claim it stopped --
1530
+ // but only say it is still running if a candidate pid actually is. It may
1531
+ // have exited while waiting for the service stop, in which case the normal
1532
+ // message is the truthful one.
1533
+ let stillRunningWho = null;
1534
+ if (guardStopLeftRunning) {
1535
+ const { readServerInfoPid } = await import('../services/singleton.js');
1536
+ const leftPid = readServerInfoPid();
1537
+ const candidates = [...(leftPid !== undefined ? [String(leftPid)] : []), ...pidsBeforeStop]
1538
+ .filter((pid, i, all) => all.indexOf(pid) === i)
1539
+ .filter(pid => isPidAlive(Number(pid)));
1540
+ if (candidates.length > 0)
1541
+ stillRunningWho = `pid ${candidates.join(', ')}`;
1542
+ }
1543
+ if (stillRunningWho) {
1544
+ console.warn(` The server ${stillRunningWho} is still running: it did not exit after the stop request and could not be verified as an apra-fleet process, so it was not force-killed. Install continues without stopping it; check ${stillRunningWho} yourself.`);
1545
+ }
1546
+ else {
1547
+ console.log(pidsBeforeStop.length > 0 || guardStoppedService
1548
+ ? ' Stopped running server.'
1549
+ : ' No running server process of this install was found to stop.');
1550
+ }
1464
1551
  }
1465
1552
  console.log(`\nInstalling Apra Fleet ${serverVersion} for ${paths.name}...\n`);
1466
1553
  // Installing is an explicit (re)start intent: end a previous 'apra-fleet stop'.
@@ -1495,14 +1582,29 @@ ${manualStopHint(pidsAfterStop)}
1495
1582
  // the exact restart command is printed, so a failure at any later step stays
1496
1583
  // recoverable by hand.
1497
1584
  if (guardStoppedService && guardServiceMgr) {
1498
- console.log(` The registered service was stopped by --force. Restart command: ${serviceRestartCommand()}`);
1585
+ if (serviceStep) {
1586
+ console.log(` The registered service was stopped by --force; the final install step re-registers and starts it. (Only if a later step fails, restart it with: ${serviceRestartCommand()})`);
1587
+ }
1588
+ else {
1589
+ console.log(` The registered service was stopped by --force; restarting it now. (If that fails -- Restart command: ${serviceRestartCommand()})`);
1590
+ }
1499
1591
  if (!serviceStep) {
1500
1592
  try {
1501
1593
  await guardServiceMgr.start();
1594
+ guardRestartedService = true;
1502
1595
  console.log(' Restarted the registered service.');
1503
1596
  }
1504
1597
  catch (err) {
1505
1598
  console.warn(` [WARN] Could not restart the registered service: ${err.message}`);
1599
+ // No service step ran, so nothing else prints the legacy-task guidance
1600
+ // (the install-reason stop suppressed it): print it once here.
1601
+ let guidance = null;
1602
+ try {
1603
+ guidance = guardServiceMgr.legacyGuidance?.() ?? null;
1604
+ }
1605
+ catch { /* generic warning stands */ }
1606
+ if (guidance)
1607
+ console.warn(guidance);
1506
1608
  }
1507
1609
  }
1508
1610
  }
@@ -1528,6 +1630,7 @@ ${manualStopHint(pidsAfterStop)}
1528
1630
  }
1529
1631
  }
1530
1632
  // --- Step 4: Configure hooks + statusline in settings.json ---
1633
+ let claudeModResult = null;
1531
1634
  console.log(` [4/${totalSteps}] Configuring ${paths.name} settings...`);
1532
1635
  // OpenCode has a strict config schema -- hooks/statusLine/defaultModel are not valid keys
1533
1636
  if (memberMode) {
@@ -1536,8 +1639,33 @@ ${manualStopHint(pidsAfterStop)}
1536
1639
  else if (llm !== 'opencode') {
1537
1640
  const installedHooksConfig = JSON.parse(fs.readFileSync(path.join(HOOKS_DIR, 'hooks-config.json'), 'utf-8'));
1538
1641
  mergeHooksConfig(paths, installedHooksConfig, llm);
1539
- const statuslineScript = path.join(SCRIPTS_DIR, 'fleet-statusline.sh');
1540
- configureStatusline(paths, statuslineScript, llm);
1642
+ // Claude: install the fleet-status mod (status line entry + /fleet-status
1643
+ // pane). Only when it installed does the statusLine script go away (and
1644
+ // only apra-fleet's own entry); otherwise today's statusLine stays.
1645
+ // Runs before configureStatusline and between the settings writes: the
1646
+ // claude CLI edits the same settings.json, and every helper re-reads it.
1647
+ if (llm === 'claude' && claudeModStepEnabled()) {
1648
+ let modFiles = [];
1649
+ try {
1650
+ modFiles = claudeModFiles(manifest);
1651
+ }
1652
+ catch { /* unreadable asset -> reported as not packaged */ }
1653
+ claudeModResult = installClaudeMod(modFiles, { alreadyRegistered: claudeModRegistered(paths) });
1654
+ }
1655
+ if (claudeModResult?.status === 'installed') {
1656
+ if (removeApraFleetStatusLine(paths)) {
1657
+ console.log(' Removed the apra-fleet statusLine entry (the fleet-status mod replaces it).');
1658
+ }
1659
+ }
1660
+ else {
1661
+ if (claudeModResult?.status === 'skipped') {
1662
+ console.log(` fleet-status mod not installed: ${claudeModResult.reason} -- keeping the statusLine script.`);
1663
+ }
1664
+ const statuslineScript = path.join(SCRIPTS_DIR, 'fleet-statusline.sh');
1665
+ if (configureStatusline(paths, statuslineScript, llm) === 'kept-foreign') {
1666
+ console.log(` Kept your existing statusLine in ${paths.settingsFile} (not apra-fleet's; left unchanged).`);
1667
+ }
1668
+ }
1541
1669
  const standardModel = PROVIDER_STANDARD_MODELS[llm] ?? PROVIDER_STANDARD_MODELS['claude'];
1542
1670
  writeDefaultModel(paths, standardModel);
1543
1671
  }
@@ -2021,6 +2149,10 @@ ${manualStopHint(pidsAfterStop)}
2021
2149
  // "auto" recognises its own half-finished install and retries.
2022
2150
  if (memberMode)
2023
2151
  writeMemberInstallMarker(serverVersion, memberPort);
2152
+ // A full install records its port (or clears the record) the same way, so
2153
+ // start / service launch / logon autostart bind what the MCP registration says.
2154
+ else
2155
+ recordFullInstallPort(serverVersion);
2024
2156
  // Every install holds a member access secret (owner-only, in its data dir):
2025
2157
  // its server accepts a ?member= session only with it, so another local
2026
2158
  // user's session cannot use this install. Created once, kept on reinstall
@@ -2073,6 +2205,9 @@ ${manualStopHint(pidsAfterStop)}
2073
2205
  console.error(`
2074
2206
  Error: ${conflict.message}
2075
2207
  `);
2208
+ // The registrations are already rewritten: keep the restart notice
2209
+ // pending (never shown inline on this exit) for the next verb.
2210
+ recordAccessRestartNotice(registrationChanged && !memberMode, false);
2076
2211
  process.exitCode = 1;
2077
2212
  return;
2078
2213
  }
@@ -2126,14 +2261,32 @@ not start automatically.
2126
2261
  }
2127
2262
  // --force stopped the server; reporting success would leave it down silently.
2128
2263
  if (force && (runningScope?.relevant || guardStoppedService)) {
2129
- const restartHint = guardStoppedService
2130
- ? `Start it with:\n ${serviceRestartCommand()}\nthen run 'apra-fleet status' for how to repair the service (apra-fleet never needs an elevated install).`
2131
- : 'Start it with:\n apra-fleet start';
2264
+ // A reused legacy (e.g. elevated) task refused the start; 'apra-fleet start'
2265
+ // hits the same refusal, so give the upgrade guidance instead.
2266
+ let legacyHint = null;
2267
+ if (serviceReused) {
2268
+ try {
2269
+ legacyHint = svcMgr.legacyGuidance?.() ?? null;
2270
+ }
2271
+ catch { /* keep the generic hint */ }
2272
+ }
2273
+ // register() already printed the full guidance for a reused legacy task:
2274
+ // point at it instead of repeating it, so it appears once per install.
2275
+ const alreadyShown = legacyHint !== null && (svcMgr.legacyGuidanceShown?.() ?? false);
2276
+ const restartHint = alreadyShown ? 'The task could not be started; follow the steps printed above for the existing scheduled task, then re-run install --force.'
2277
+ : legacyHint ? legacyHint
2278
+ : guardStoppedService
2279
+ ? `Start it with:\n ${serviceRestartCommand()}\nthen run 'apra-fleet status' for how to repair the service (apra-fleet never needs an elevated install).`
2280
+ : 'Start it with:\n apra-fleet start';
2132
2281
  console.error(`
2133
2282
  Error: install --force stopped the running apra-fleet server, but the service
2134
2283
  could not be registered/started, so the server is NOT running.
2135
2284
  ${restartHint}
2136
2285
  `);
2286
+ // After register() (which may clear a stale notice): the registrations
2287
+ // changed, so the restart notice must survive this exit. Not shown
2288
+ // inline here, so it stays pending for the next status/start/update.
2289
+ recordAccessRestartNotice(registrationChanged && !memberMode, false);
2137
2290
  process.exit(1);
2138
2291
  }
2139
2292
  }
@@ -2151,19 +2304,26 @@ ${restartHint}
2151
2304
  ? MEMBER_INSTALL_NEXT_STEP
2152
2305
  : llm === 'claude' ? 'Run /mcp in Claude Code to load the server.' : `Restart ${paths.name} to load the server.`;
2153
2306
  const forceNote = force && !memberMode ? `\nRestart ${clientName} to reload the MCP server.` : '';
2154
- const accessNote = registrationChanged && !memberMode
2155
- ? '\n[!] Restart every open LLM CLI session (Claude Code, Codex, ...): sessions started before this install keep their old MCP registration without the access secret, and the server refuses them (Claude Code shows "Dynamic Client Registration rejected (HTTP 404)").'
2156
- : '';
2307
+ const accessNote = registrationChanged && !memberMode ? `
2308
+ ${ACCESS_RESTART_NOTE}` : '';
2309
+ // apra-fleet update runs install detached with stdio ignored, so the note above
2310
+ // never reaches that user: persist it for the next status/start/update.
2311
+ recordAccessRestartNotice(registrationChanged && !memberMode, Boolean(process.stdout.isTTY));
2157
2312
  const settingsLine = memberMode ? '' : `\n Settings: ${paths.settingsFile}`;
2158
2313
  const serviceState = serviceHealthy === true ? 'registered and running' : serviceHealthy === false ? 'registered, but NOT answering /health (see the warning above)' : 'registered (health not checked)';
2159
- const serviceLine = serviceStep ? `\n Service: ${serviceRegistered ? `${serviceState}${serviceReused ? ' (existing task reused)' : ''}${serviceRunKey ? ' (logon autostart via HKCU Run, no automatic restart)' : ''}` : 'registration skipped'}` : '';
2314
+ const claudeModLine = claudeModResult
2315
+ ? `\n Claude mod: fleet-status ${claudeModResult.status === 'installed' ? `installed (${claudeModResult.dir}${claudeModResult.note ? `; ${claudeModResult.note}` : ''})` : `skipped: ${claudeModResult.reason}`}`
2316
+ : '';
2317
+ const serviceLine = !serviceStep && guardStoppedService
2318
+ ? `\n Service: ${guardRestartedService ? 'restarted after --force stop' : 'NOT restarted (see the warning above; start it with ' + serviceRestartCommand() + ')'}`
2319
+ : serviceStep ? `\n Service: ${serviceRegistered ? `${serviceState}${serviceReused ? ' (existing task reused)' : ''}${serviceRunKey ? ' (logon autostart via HKCU Run, no automatic restart)' : ''}` : 'registration skipped'}` : '';
2160
2320
  console.log(`
2161
2321
  Apra Fleet ${serverVersion} installed successfully for ${paths.name}.
2162
2322
  Binary: ${BIN_DIR}
2163
2323
  Hooks: ${HOOKS_DIR}
2164
2324
  Scripts: ${SCRIPTS_DIR}${settingsLine}${installFleet ? `\n Fleet Skill: ${paths.fleetSkillsDir}` : ''}${installPm ? `\n PM Skill: ${paths.skillsDir}` : ''}${installAgents ? `\n Agents: ${paths.agentsDir}` : ''}
2165
2325
  Beads: ${beadsVersion}
2166
- Dolt: ${doltVersion}${serviceLine}
2326
+ Dolt: ${doltVersion}${claudeModLine}${serviceLine}
2167
2327
 
2168
2328
  ${instructions}${forceNote}${accessNote}
2169
2329
  `);
@@ -0,0 +1,16 @@
1
+ import { type KbToolProfile } from '../services/kb-tool-profile.js';
2
+ export declare const KB_PROFILE_USAGE = "Usage: apra-fleet kb profile [full | developer | custom <tool1,tool2,...>]";
3
+ interface Io {
4
+ log: (msg: string) => void;
5
+ error: (msg: string) => void;
6
+ }
7
+ /**
8
+ * Parse the arguments after `kb profile` into a profile to set, or null to
9
+ * print the current one. Throws an Error with a usage-ready message on bad
10
+ * input or an unknown tool name.
11
+ */
12
+ export declare function parseKbProfileArgs(args: string[]): KbToolProfile | null;
13
+ /** Run the verb; returns the process exit code. */
14
+ export declare function runKbProfile(args: string[], io?: Io): number;
15
+ export {};
16
+ //# sourceMappingURL=kb-profile.d.ts.map
@@ -0,0 +1,81 @@
1
+ // `apra-fleet kb profile [full | developer | custom <tool1,tool2,...>]`
2
+ //
3
+ // Shows or sets the install-wide KB tool profile (src/services/kb-tool-profile.ts)
4
+ // stored in the KB config. This verb exists because the developer profile hides
5
+ // kb_setup from interactive sessions: the CLI is always a way back to full.
6
+ // The profile applies to FULL (non-member) sessions only and takes effect when
7
+ // a session reconnects. It is a usability control, not a security boundary.
8
+ import { readKbToolProfileFromDisk, KB_CONFIG_PATH, KB_CONFIG_HAND_FIX, KbConfigUnreadableError } from '../services/knowledge/kb-config.js';
9
+ import { describeKbToolProfile, makeKbToolProfile, registeredKbToolNames } from '../services/kb-tool-profile.js';
10
+ import { writeKbToolProfile } from '../tools/kb-setup.js';
11
+ export const KB_PROFILE_USAGE = 'Usage: apra-fleet kb profile [full | developer | custom <tool1,tool2,...>]';
12
+ const defaultIo = {
13
+ log: (msg) => console.log(msg),
14
+ error: (msg) => console.error(msg),
15
+ };
16
+ /**
17
+ * Parse the arguments after `kb profile` into a profile to set, or null to
18
+ * print the current one. Throws an Error with a usage-ready message on bad
19
+ * input or an unknown tool name.
20
+ */
21
+ export function parseKbProfileArgs(args) {
22
+ if (args.length === 0)
23
+ return null;
24
+ const [name, ...rest] = args;
25
+ if (name === 'full' || name === 'developer') {
26
+ if (rest.length > 0)
27
+ throw new Error(`"${name}" takes no tool list`);
28
+ return makeKbToolProfile(name);
29
+ }
30
+ if (name === 'custom') {
31
+ const tools = rest.join(',').split(',').map(t => t.trim()).filter(t => t.length > 0);
32
+ if (tools.length === 0) {
33
+ throw new Error(`"custom" needs a comma-separated kb_* tool list. Valid names: ${registeredKbToolNames().join(', ')}`);
34
+ }
35
+ return makeKbToolProfile('custom', tools);
36
+ }
37
+ throw new Error(`unknown profile "${name}"`);
38
+ }
39
+ /** Run the verb; returns the process exit code. */
40
+ export function runKbProfile(args, io = defaultIo) {
41
+ if (args.includes('--help') || args.includes('-h')) {
42
+ io.log(KB_PROFILE_USAGE);
43
+ return 0;
44
+ }
45
+ let profile;
46
+ try {
47
+ profile = parseKbProfileArgs(args);
48
+ }
49
+ catch (err) {
50
+ io.error(`Error: ${err.message}`);
51
+ io.error(KB_PROFILE_USAGE);
52
+ return 1;
53
+ }
54
+ if (profile === null) {
55
+ try {
56
+ io.log(`KB tool profile: ${describeKbToolProfile(readKbToolProfileFromDisk())}`);
57
+ return 0;
58
+ }
59
+ catch (err) {
60
+ io.error(`Error: ${err.message}`);
61
+ io.error(err instanceof KbConfigUnreadableError ? KB_CONFIG_HAND_FIX : 'Fix it with: apra-fleet kb profile full');
62
+ return 1;
63
+ }
64
+ }
65
+ let steps;
66
+ try {
67
+ ({ steps } = writeKbToolProfile(profile));
68
+ }
69
+ catch (err) {
70
+ if (!(err instanceof KbConfigUnreadableError))
71
+ throw err;
72
+ io.error(`Error: ${err.message}; nothing was written.`);
73
+ io.error(KB_CONFIG_HAND_FIX);
74
+ return 1;
75
+ }
76
+ for (const s of steps)
77
+ io.log(s);
78
+ io.log(`Config: ${KB_CONFIG_PATH}. Applies to interactive (non-member) sessions only; reconnect to see the change.`);
79
+ return 0;
80
+ }
81
+ //# sourceMappingURL=kb-profile.js.map
package/dist/cli/start.js CHANGED
@@ -10,6 +10,7 @@ import { ensureOwnerOnlyDir, openOwnerOnlyAppend } from '../utils/owner-only-fs.
10
10
  import { BIN_DIR } from './config.js';
11
11
  import { serverVersion } from '../version.js';
12
12
  import { clearStoppedMarker, readStoppedMarker } from '../services/stopped-marker.js';
13
+ import { showPendingServiceNotice } from '../services/service-notice.js';
13
14
  const __filename = fileURLToPath(import.meta.url);
14
15
  const __dirname = dirname(__filename);
15
16
  function isSea() {
@@ -63,6 +64,8 @@ function directSpawn() {
63
64
  console.log('Server starting...');
64
65
  }
65
66
  export async function runStart(_args) {
67
+ // Guidance a detached install (apra-fleet update) could not show.
68
+ showPendingServiceNotice();
66
69
  // An explicit start ends a user stop: clients may auto-start again. A start
67
70
  // launched BY a client auto-start (APRA_FLEET_AUTOSTART=1) must never erase
68
71
  // a stop that raced it -- it refuses instead.