@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
@@ -1,4 +1,5 @@
1
1
  import type { CodeIntelligenceProvider } from './code-intelligence.js';
2
+ import { type ScheduleReindexOutcome } from './code-index-heal.js';
2
3
  export interface ResolvedSymbol {
3
4
  name?: string;
4
5
  id?: string;
@@ -29,6 +30,24 @@ export declare function resolvesToRequested(requested: string, resolved: Resolve
29
30
  * error, or is not the JSON shape gitnexus returns.
30
31
  */
31
32
  export declare function flagResolutionMismatch(result: unknown, requested: unknown, kind: 'impact' | 'context'): unknown;
33
+ export declare const INDEX_ID_UNIQUENESS_QUERY = "MATCH (n) RETURN count(n) AS total, count(DISTINCT n.id) AS distinct_ids";
34
+ export interface IndexIntegrity {
35
+ corrupt: true;
36
+ /** Rows in the index beyond one per distinct id: overwritten symbols. */
37
+ damaged_rows: number;
38
+ /** Whether an automatic rebuild started, or why not. */
39
+ rebuild: ScheduleReindexOutcome;
40
+ }
41
+ /** The name a code_impact / code_context result reports as not found, or null. */
42
+ export declare function notFoundName(result: unknown): string | null;
43
+ /**
44
+ * When a code_impact / code_context answer is "not found" and `repo`'s index
45
+ * holds overwritten rows (ids that are not unique), return the answer marked as unreliable (payload
46
+ * index_integrity + confidence LOW, plus a warning naming the cause and what
47
+ * happens next) and ask for a rebuild. Any other result, or one whose
48
+ * index checks out, is returned unchanged.
49
+ */
50
+ export declare function flagCorruptIndexNotFound(result: unknown, repo: unknown): Promise<unknown>;
32
51
  export type MarkdownTableRow = Record<string, string>;
33
52
  export declare function parseMarkdownTable(markdown: string): MarkdownTableRow[];
34
53
  export declare function asciiSanitizeLabel(label: string): string;
@@ -3,13 +3,17 @@ import { execFileSync } from 'child_process';
3
3
  import { join } from 'path';
4
4
  import { Client } from '@modelcontextprotocol/sdk/client/index.js';
5
5
  import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
6
+ import { ErrorCode } from '@modelcontextprotocol/sdk/types.js';
6
7
  import { freshnessNote } from './code-intelligence-freshness.js';
7
8
  import { maybeScheduleReindex, GITNEXUS_PACKAGE_SPEC } from './code-intelligence-reindex.js';
9
+ import { scheduleIndexBuild } from './code-index-heal.js';
8
10
  import { isTestPath } from './code-intelligence-tests.js';
9
11
  import { codeIndexReadiness, ensureGitNexusIndexReady, indexChangedDuringCallError } from './code-intelligence-readiness.js';
10
12
  import { indexGeneration, readGitNexusIndexState } from './code-index-state.js';
11
13
  import { logError } from '../utils/log-helpers.js';
12
14
  import { missingOnServerPathMessage, npxUnavailableReason } from '../utils/find-on-path.js';
15
+ import { gitExecutable } from '../os/git-executable.js';
16
+ import { redactKnownSecrets } from '../utils/redact-known-secrets.js';
13
17
  let sharedEntry = null;
14
18
  let connectionPromise = null;
15
19
  // Index generation (indexGeneration: meta lastCommit|indexedAt) each repo had
@@ -22,12 +26,39 @@ let connectionPromise = null;
22
26
  // result (content array of text plus isError) so callers never receive an
23
27
  // unhandled throw or a silent empty result -- mirrors the F3.1 error shape.
24
28
  const OFFLINE_MESSAGE = "Code intelligence is offline: the gitnexus service could not be reached. " +
25
- "Start or reinstall it by running 'npx gitnexus analyze --index-only' in the repo " +
29
+ "Start or reinstall it by running 'npx gitnexus analyze --index-only --force' in the repo " +
26
30
  "(or /pm index), then retry.";
27
31
  function offlineResult(detail) {
28
32
  const text = detail ? `${OFFLINE_MESSAGE} (${detail})` : OFFLINE_MESSAGE;
29
33
  return { content: [{ type: 'text', text }], isError: true };
30
34
  }
35
+ // The child's stderr is the only record of why it failed (npx install errors,
36
+ // a crash on start). Reading it also keeps an unread pipe from stalling the
37
+ // child. Only the end is kept, and it is scrubbed before it is cut, so a cut
38
+ // cannot leave half a credential that the patterns no longer recognise.
39
+ const STDERR_KEEP_CHARS = 8000;
40
+ const STDERR_REPORT_CHARS = 2000;
41
+ function scrubChildText(text) {
42
+ return redactKnownSecrets(text, [])
43
+ .replace(/\x1b\[[0-9;]*[A-Za-z]/g, '')
44
+ .replace(/(_auth(?:Token)?|_password)(\s*[=:]\s*)\S+/gi, '$1$2****')
45
+ .replace(/(:\/\/)[^\s/@]+@/g, '$1****@')
46
+ .replace(/\b(?:npm_[A-Za-z0-9]{20,}|sk-ant-[A-Za-z0-9_-]+)/g, '****')
47
+ .replace(/[^\x20-\x7E]+/g, ' ');
48
+ }
49
+ function captureChildStderr(transport) {
50
+ let kept = '';
51
+ transport.stderr?.on('data', (chunk) => {
52
+ kept = (kept + String(chunk)).slice(-STDERR_KEEP_CHARS);
53
+ });
54
+ return () => scrubChildText(kept).slice(-STDERR_REPORT_CHARS);
55
+ }
56
+ /** Why the child failed: timeout or not, in which stage, how long it took, and its stderr. */
57
+ function childFailureDetail(err, stage, startedAt, stderr) {
58
+ const message = scrubChildText(err instanceof Error ? err.message : String(err));
59
+ const outcome = err?.code === ErrorCode.RequestTimeout ? 'TIMEOUT' : 'failed';
60
+ return `${outcome} during ${stage} after ${Date.now() - startedAt} ms: ${message}; child stderr: ${stderr || '(empty)'}`;
61
+ }
31
62
  function closeEntry(entry) {
32
63
  if (entry.closed)
33
64
  return;
@@ -83,8 +114,9 @@ async function getGitNexusEntry() {
83
114
  args: ['-y', GITNEXUS_PACKAGE_SPEC, 'mcp'],
84
115
  stderr: 'pipe',
85
116
  });
117
+ const stderrTail = captureChildStderr(transport);
86
118
  const client = new Client({ name: 'apra-fleet', version: '1.0.0' }, { capabilities: {} });
87
- const entry = { client, inFlight: 0, retired: false, closed: false, servedGeneration: new Map() };
119
+ const entry = { client, inFlight: 0, retired: false, closed: false, servedGeneration: new Map(), stderrTail };
88
120
  // Transport death reset: if the child process dies (close) or the
89
121
  // transport/client errors after a successful connect, stop handing it
90
122
  // out so the next call reconnects. Guard on identity so a late handler
@@ -98,7 +130,14 @@ async function getGitNexusEntry() {
98
130
  transport.onerror = onDeath;
99
131
  client.onclose = onDeath;
100
132
  client.onerror = onDeath;
101
- await client.connect(transport);
133
+ const connectStart = Date.now();
134
+ try {
135
+ await client.connect(transport);
136
+ }
137
+ catch (err) {
138
+ // No entry reaches callGitNexus on this path, so the reason travels in the error.
139
+ throw new Error(childFailureDetail(err, 'connect', connectStart, stderrTail()), { cause: err });
140
+ }
102
141
  if (connectionPromise === pending) {
103
142
  // A child that died while connecting is never shared; clear the
104
143
  // resolved promise too, or every later call would get it back.
@@ -133,16 +172,18 @@ async function getGitNexusEntry() {
133
172
  */
134
173
  const GITNEXUS_ACQUIRE_ATTEMPTS = 3;
135
174
  async function acquireGitNexusEntry() {
175
+ let lastStderr = '';
136
176
  for (let attempt = 1; attempt <= GITNEXUS_ACQUIRE_ATTEMPTS; attempt++) {
137
177
  const entry = await getGitNexusEntry();
138
178
  if (!entry.retired) {
139
179
  entry.inFlight += 1;
140
180
  return entry;
141
181
  }
182
+ lastStderr = entry.stderrTail();
142
183
  if (entry.inFlight === 0)
143
184
  closeEntry(entry);
144
185
  }
145
- throw new Error(`gitnexus child exited or was retired ${GITNEXUS_ACQUIRE_ATTEMPTS} times in a row before it could serve a call (it is crashing on start or being recycled repeatedly)`);
186
+ throw new Error(`gitnexus child exited or was retired ${GITNEXUS_ACQUIRE_ATTEMPTS} times in a row before it could serve a call (it is crashing on start or being recycled repeatedly); child stderr: ${lastStderr || '(empty)'}`);
146
187
  }
147
188
  // Freshness metadata (F2.2): when a call carries a `repo` param and the index
148
189
  // exists, compare meta.json's lastCommit against the repo's current
@@ -161,7 +202,7 @@ function computeFreshnessNote(repo) {
161
202
  try {
162
203
  const metaPath = join(repo, '.gitnexus', 'meta.json');
163
204
  const meta = JSON.parse(readFileSync(metaPath, 'utf-8'));
164
- const head = execFileSync('git', ['rev-parse', 'HEAD'], {
205
+ const head = execFileSync(gitExecutable(), ['rev-parse', 'HEAD'], {
165
206
  cwd: repo, encoding: 'utf-8', timeout: 3000, stdio: ['ignore', 'pipe', 'ignore'], windowsHide: true,
166
207
  }).trim();
167
208
  const diverged = freshnessNote(meta.lastCommit, head) !== null;
@@ -230,8 +271,10 @@ async function callGitNexus(name, params) {
230
271
  }
231
272
  let result;
232
273
  let entry = null;
274
+ let callStart = 0;
233
275
  try {
234
276
  entry = await acquireGitNexusEntry();
277
+ callStart = Date.now();
235
278
  result = await entry.client.callTool({ name, arguments: params });
236
279
  }
237
280
  catch (err) {
@@ -240,9 +283,16 @@ async function callGitNexus(name, params) {
240
283
  // path already cleared its poisoned promise.
241
284
  if (entry)
242
285
  retireEntry(entry);
243
- let detail = err instanceof Error ? err.message : String(err);
244
- if (/\bENOENT\b/.test(detail) && /npx/.test(detail))
286
+ let detail = entry
287
+ ? childFailureDetail(err, `call of ${name}`, callStart, entry.stderrTail())
288
+ : err instanceof Error ? err.message : String(err);
289
+ // Only the spawn error itself means npx is missing. The detail also holds child
290
+ // stderr, where ENOENT next to an _npx cache path says nothing about PATH. Only
291
+ // a failed connect carries the spawn error, as the cause of its wrapper.
292
+ const cause = err instanceof Error ? err.cause : undefined;
293
+ if (!entry && cause instanceof Error && /\bspawn npx ENOENT\b/.test(cause.message)) {
245
294
  detail = `${detail}: ${missingOnServerPathMessage('npx')}`;
295
+ }
246
296
  return offlineResult(detail);
247
297
  }
248
298
  finally {
@@ -433,6 +483,111 @@ export function flagResolutionMismatch(result, requested, kind) {
433
483
  confidence: 'LOW',
434
484
  };
435
485
  }
486
+ // ---------------------------------------------------------------------------
487
+ // Corrupt-index check (code_impact / code_context "not found"). gitnexus
488
+ // 1.6.12's incremental analyze of a large repo rewrites rows of files it did
489
+ // not change. Reproduced with one one-line edit on a repo of 43297 nodes: the
490
+ // total stayed about the same, but only 34011 distinct ids were left (9287
491
+ // rows now duplicate another row, and an earlier run left 7774 blank ones).
492
+ // Every symbol whose row was overwritten answers "Target 'x' not found" /
493
+ // "Symbol 'x' not found" although it exists, and the index stays broken until
494
+ // a full rebuild. A healthy index has one row per id. Fleet-run analyzes are
495
+ // full rebuilds (GITNEXUS_ANALYZE_ARGS carries --force), but an index corrupted
496
+ // before that, or by an incremental analyze run by hand, still answers this
497
+ // way. So a not-found answer is cross-checked: when ids are not unique, the
498
+ // answer is marked as unreliable and a rebuild is asked for
499
+ // (scheduleIndexBuild: config-, cooldown- and single-flight-gated).
500
+ // ---------------------------------------------------------------------------
501
+ const NOT_FOUND_ERROR = /^(?:Target|Symbol) '([\s\S]*)' not found\.?$/;
502
+ // Every node of a healthy index has its own id ('<Label>:<path>[:<name>]').
503
+ // count(DISTINCT) folds duplicated and blank ids and skips null ones, so the
504
+ // difference covers all three.
505
+ export const INDEX_ID_UNIQUENESS_QUERY = 'MATCH (n) RETURN count(n) AS total, count(DISTINCT n.id) AS distinct_ids';
506
+ /** The name a code_impact / code_context result reports as not found, or null. */
507
+ export function notFoundName(result) {
508
+ const parts = splitPayload(result);
509
+ if (!parts)
510
+ return null;
511
+ const error = parts.payload.error;
512
+ if (typeof error !== 'string')
513
+ return null;
514
+ const m = NOT_FOUND_ERROR.exec(error.trim());
515
+ return m ? m[1] : null;
516
+ }
517
+ function splitPayload(result) {
518
+ if (isErrorResult(result) || !result || typeof result !== 'object' || !('content' in result))
519
+ return null;
520
+ const content = result.content;
521
+ if (!Array.isArray(content) || content.length === 0)
522
+ return null;
523
+ const first = content[0];
524
+ if (!first || typeof first.text !== 'string')
525
+ return null;
526
+ const sep = '\n\n---\n';
527
+ const cut = first.text.indexOf(sep);
528
+ try {
529
+ const parsed = JSON.parse(cut >= 0 ? first.text.slice(0, cut) : first.text);
530
+ if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
531
+ return null;
532
+ return { payload: parsed, suffix: cut >= 0 ? first.text.slice(cut) : '', first, content };
533
+ }
534
+ catch {
535
+ return null;
536
+ }
537
+ }
538
+ /** Rows beyond one per distinct id in `repo`'s index, or null when it cannot be read. */
539
+ async function damagedRows(repo) {
540
+ let result;
541
+ try {
542
+ result = await callGitNexus('cypher', { query: INDEX_ID_UNIQUENESS_QUERY, repo });
543
+ }
544
+ catch {
545
+ return null;
546
+ }
547
+ const payload = extractCypherPayload(result);
548
+ if (!payload)
549
+ return null;
550
+ const row = parseMarkdownTable(payload.markdown)[0];
551
+ if (!row || row.total === undefined || row.distinct_ids === undefined)
552
+ return null;
553
+ const n = Number(row.total) - Number(row.distinct_ids);
554
+ return Number.isFinite(n) ? n : null;
555
+ }
556
+ /**
557
+ * When a code_impact / code_context answer is "not found" and `repo`'s index
558
+ * holds overwritten rows (ids that are not unique), return the answer marked as unreliable (payload
559
+ * index_integrity + confidence LOW, plus a warning naming the cause and what
560
+ * happens next) and ask for a rebuild. Any other result, or one whose
561
+ * index checks out, is returned unchanged.
562
+ */
563
+ export async function flagCorruptIndexNotFound(result, repo) {
564
+ if (typeof repo !== 'string' || repo === '')
565
+ return result;
566
+ const name = notFoundName(result);
567
+ if (name === null)
568
+ return result;
569
+ const damaged = await damagedRows(repo);
570
+ if (damaged === null || damaged <= 0)
571
+ return result;
572
+ const rebuild = scheduleIndexBuild(repo);
573
+ const integrity = { corrupt: true, damaged_rows: damaged, rebuild };
574
+ const parts = splitPayload(result);
575
+ const next = rebuild.started
576
+ ? 'A full rebuild of the index has started; retry once code_status reports it ready.'
577
+ : `No rebuild started (${rebuild.reason}${rebuild.detail ? `: ${rebuild.detail}` : ''}); run code_reindex, which always rebuilds the index in full.`;
578
+ const warning = `[code-intelligence] INDEX CORRUPT: '${name}' was not found, but ${damaged} rows in this code index ` +
579
+ 'have overwritten other symbols, so this is NOT evidence that the symbol does not exist. ' +
580
+ `${next} Until then, use a text search for this symbol.`;
581
+ const patched = { ...parts.payload, index_integrity: integrity, confidence: 'LOW' };
582
+ return {
583
+ ...result,
584
+ content: [
585
+ { ...parts.first, text: JSON.stringify(patched, null, 2) + parts.suffix },
586
+ ...parts.content.slice(1),
587
+ { type: 'text', text: warning },
588
+ ],
589
+ };
590
+ }
436
591
  // Small, pure, exported so both T2.1 (code_map) and T2.2 (code_flow) can reuse
437
592
  // it and it can be unit tested directly without mocking the MCP client.
438
593
  export function parseMarkdownTable(markdown) {
@@ -677,13 +832,15 @@ export class GitNexusProvider {
677
832
  });
678
833
  }
679
834
  async impact(params) {
680
- return flagResolutionMismatch(await callGitNexus('impact', params), params.target, 'impact');
835
+ const result = await callGitNexus('impact', params);
836
+ return flagResolutionMismatch(await flagCorruptIndexNotFound(result, params.repo), params.target, 'impact');
681
837
  }
682
838
  async query(params) {
683
839
  return callGitNexus('query', params);
684
840
  }
685
841
  async context(params) {
686
- return flagResolutionMismatch(await callGitNexus('context', params), params.name, 'context');
842
+ const result = await callGitNexus('context', params);
843
+ return flagResolutionMismatch(await flagCorruptIndexNotFound(result, params.repo), params.name, 'context');
687
844
  }
688
845
  // T2.1: architectural map via Community nodes (rung 2 -- compose over cypher;
689
846
  // no direct communities/map tool exists on gitnexus 1.6.7). See Decisions
@@ -1,10 +1,67 @@
1
+ import { type AnalyzeProgress } from './code-intelligence-reindex.js';
1
2
  import { type ScheduleReindexOutcome } from './code-index-heal.js';
2
3
  export { readGitNexusIndexState, type GitNexusIndexState } from './code-index-state.js';
3
4
  export type CodeIntelErrorCode = 'E-CODE-INDEX-NOT-READY' | 'E-CODE-INTEL-DISABLED';
4
5
  export declare class CodeIntelError extends Error {
5
6
  readonly code: CodeIntelErrorCode;
6
7
  readonly remediation: string;
7
- constructor(code: CodeIntelErrorCode, problem: string, remediation: string);
8
+ /**
9
+ * Machine-readable detail returned beside the one-line message as the error
10
+ * tool result's `structuredContent` (the tool wrapper in
11
+ * src/services/tool-registry.ts maps any thrown error carrying it). Set on
12
+ * every E-CODE-INDEX-NOT-READY (IndexNotReadyData); absent otherwise.
13
+ */
14
+ readonly structuredContent?: Record<string, unknown>;
15
+ /**
16
+ * The text the tool result carries. An MCP client may hand its model only
17
+ * the text of an error result (Claude Code does), so the retry guidance and
18
+ * build progress in structuredContent are repeated here, still on one line.
19
+ */
20
+ readonly toolText: string;
21
+ constructor(code: CodeIntelErrorCode, problem: string, remediation: string, structuredContent?: Record<string, unknown>);
22
+ }
23
+ /**
24
+ * Suggested wait before the single retry while a build runs or was just
25
+ * requested, when the folder has no earlier build to estimate from: every
26
+ * fleet-run analyze is a full rebuild, measured at 126-261 s on a repo of about
27
+ * 43000 graph nodes. With an earlier build the wait is what should remain of
28
+ * it (expectedBuildRemainingMs).
29
+ */
30
+ export declare const RETRY_AFTER_BUILDING_MS = 180000;
31
+ /** Suggested wait when a build finished moments ago (the scheduler's cooldown). */
32
+ export declare const RETRY_AFTER_COOLDOWN_MS = 60000;
33
+ /** Suggested wait when the index changed under a call (a rebuild may already be done). */
34
+ export declare const RETRY_AFTER_CHANGED_MS = 5000;
35
+ /**
36
+ * The structured data on every E-CODE-INDEX-NOT-READY tool result
37
+ * (`structuredContent`), also rendered into the one-line result text
38
+ * (CodeIntelError.toolText):
39
+ *
40
+ * retry_after_ms -- always a number: how long to wait before ONE retry.
41
+ * 0 together with retry_will_help: false when no build
42
+ * is running and none could be requested, so waiting
43
+ * and retrying will not help (follow the remediation or
44
+ * fall back).
45
+ * retry_will_help -- false when no build is running and none was requested.
46
+ * state -- the readiness state ('changed' for an answer discarded
47
+ * because the index changed while the call ran).
48
+ * build -- 'running' (an analyze is live), 'requested' (one was
49
+ * just started for this call), or 'none'.
50
+ * heal -- the automatic build outcome when one was attempted
51
+ * ('started' or the scheduler's not-started reason).
52
+ * progress -- the live analyze's phase, elapsed time, last log line
53
+ * and line count (as code_status shows) when one is
54
+ * recorded for the folder.
55
+ */
56
+ export interface IndexNotReadyData {
57
+ code: 'E-CODE-INDEX-NOT-READY';
58
+ provider: CodeIndexProvider;
59
+ state: CodeIndexNotReadyState | 'changed';
60
+ retry_after_ms: number;
61
+ retry_will_help: boolean;
62
+ build: 'running' | 'requested' | 'none';
63
+ heal?: string;
64
+ progress?: AnalyzeProgress;
8
65
  }
9
66
  export type CodeIndexProvider = 'gitnexus' | 'codebase-memory';
10
67
  /**
@@ -14,7 +14,7 @@
14
14
  import { existsSync, readdirSync } from 'fs';
15
15
  import { homedir } from 'os';
16
16
  import { join } from 'path';
17
- import { isRecordedAnalyzeAlive, isReindexRunning, recordedIndexBuild } from './code-intelligence-reindex.js';
17
+ import { analyzeProgress, expectedBuildRemainingMs, isRecordedAnalyzeAlive, isReindexRunning, recordedIndexBuild } from './code-intelligence-reindex.js';
18
18
  import { indexInconsistency, readGitNexusIndexState } from './code-index-state.js';
19
19
  import { scheduleIndexBuild } from './code-index-heal.js';
20
20
  import { missingOnServerPathMessage } from '../utils/find-on-path.js';
@@ -22,13 +22,80 @@ export { readGitNexusIndexState } from './code-index-state.js';
22
22
  export class CodeIntelError extends Error {
23
23
  code;
24
24
  remediation;
25
- constructor(code, problem, remediation) {
25
+ /**
26
+ * Machine-readable detail returned beside the one-line message as the error
27
+ * tool result's `structuredContent` (the tool wrapper in
28
+ * src/services/tool-registry.ts maps any thrown error carrying it). Set on
29
+ * every E-CODE-INDEX-NOT-READY (IndexNotReadyData); absent otherwise.
30
+ */
31
+ structuredContent;
32
+ /**
33
+ * The text the tool result carries. An MCP client may hand its model only
34
+ * the text of an error result (Claude Code does), so the retry guidance and
35
+ * build progress in structuredContent are repeated here, still on one line.
36
+ */
37
+ toolText;
38
+ constructor(code, problem, remediation, structuredContent) {
26
39
  super(`${code}: ${problem} Remediation: ${remediation}`);
27
40
  this.name = 'CodeIntelError';
28
41
  this.code = code;
29
42
  this.remediation = remediation;
43
+ if (structuredContent)
44
+ this.structuredContent = structuredContent;
45
+ this.toolText = this.message + retryGuidanceText(structuredContent);
30
46
  }
31
47
  }
48
+ /** One-line rendering of IndexNotReadyData for the tool result text ('' when there is none). */
49
+ function retryGuidanceText(data) {
50
+ if (!data || typeof data.retry_after_ms !== 'number')
51
+ return '';
52
+ const fields = [`retry_after_ms=${data.retry_after_ms}`, `retry_will_help=${data.retry_will_help}`, `build=${data.build}`, `state=${data.state}`];
53
+ if (typeof data.heal === 'string')
54
+ fields.push(`heal=${data.heal}`);
55
+ const p = data.progress;
56
+ if (p) {
57
+ const last = String(p.last_line ?? '').replace(/\s+/g, ' ').trim().slice(0, 200);
58
+ fields.push(`progress: phase=${p.phase} elapsed_ms=${p.elapsed_ms} line_count=${p.line_count} last_line='${last}'`);
59
+ }
60
+ const advice = data.retry_after_ms > 0
61
+ ? 'Wait retry_after_ms once, retry once, then fall back to text search; do not poll code_status in a loop.'
62
+ : 'Waiting and retrying will not help: follow the remediation or fall back to text search.';
63
+ return ` ${advice} [${fields.join(' ')}]`;
64
+ }
65
+ /**
66
+ * Suggested wait before the single retry while a build runs or was just
67
+ * requested, when the folder has no earlier build to estimate from: every
68
+ * fleet-run analyze is a full rebuild, measured at 126-261 s on a repo of about
69
+ * 43000 graph nodes. With an earlier build the wait is what should remain of
70
+ * it (expectedBuildRemainingMs).
71
+ */
72
+ export const RETRY_AFTER_BUILDING_MS = 180_000;
73
+ /** Suggested wait when a build finished moments ago (the scheduler's cooldown). */
74
+ export const RETRY_AFTER_COOLDOWN_MS = 60_000;
75
+ /** Suggested wait when the index changed under a call (a rebuild may already be done). */
76
+ export const RETRY_AFTER_CHANGED_MS = 5_000;
77
+ /** The wait for a build that is running or was just requested for `repo`. */
78
+ function buildingRetryMs(repo) {
79
+ return (repo ? expectedBuildRemainingMs(repo) : null) ?? RETRY_AFTER_BUILDING_MS;
80
+ }
81
+ function notReadyData(provider, repo, state, build, retryAfterMs, heal) {
82
+ const data = {
83
+ code: 'E-CODE-INDEX-NOT-READY',
84
+ provider,
85
+ state,
86
+ retry_after_ms: retryAfterMs,
87
+ retry_will_help: retryAfterMs > 0,
88
+ build,
89
+ };
90
+ if (heal !== undefined)
91
+ data.heal = heal;
92
+ if (provider === 'gitnexus' && repo) {
93
+ const progress = analyzeProgress(repo);
94
+ if (progress)
95
+ data.progress = progress;
96
+ }
97
+ return data;
98
+ }
32
99
  // codebase-memory-mcp's default database storage directory (its README
33
100
  // "Persistence" section: SQLite databases under ~/.cache/codebase-memory-mcp/).
34
101
  export const CODEBASE_MEMORY_CACHE_DIR = join(homedir(), '.cache', 'codebase-memory-mcp');
@@ -90,15 +157,17 @@ export function codeIndexReadiness(provider, repo) {
90
157
  return { ready: false, state: 'missing' };
91
158
  }
92
159
  }
93
- const RETRY_SOON = 'Retry the same call in a minute or so (code_status shows the build progress).';
160
+ const RETRY_SOON = 'Retry the same call in a few minutes (code_status shows the build progress).';
94
161
  /** The typed error for a readiness result that is not ready. */
95
162
  export function indexNotReadyError(provider, repo, state, heal, detail) {
96
163
  const where = repo ? ` for '${repo}'` : '';
97
164
  if (provider === 'codebase-memory') {
98
- return new CodeIntelError('E-CODE-INDEX-NOT-READY', `No codebase-memory code index found${where}.`, `Say "Index this project" to your agent (or run 'codebase-memory-mcp cli index_repository' on the repo), then retry.`);
165
+ // codebase-memory exposes no building signal and fleet never builds its
166
+ // index: waiting will not help until someone indexes the project.
167
+ return new CodeIntelError('E-CODE-INDEX-NOT-READY', `No codebase-memory code index found${where}.`, `Say "Index this project" to your agent (or run 'codebase-memory-mcp cli index_repository' on the repo), then retry.`, notReadyData(provider, repo, state, 'none', 0));
99
168
  }
100
169
  if (state === 'building') {
101
- return new CodeIntelError('E-CODE-INDEX-NOT-READY', `The gitnexus code index${where} is still being built.`, RETRY_SOON);
170
+ return new CodeIntelError('E-CODE-INDEX-NOT-READY', `The gitnexus code index${where} is still being built.`, RETRY_SOON, notReadyData(provider, repo, state, 'running', buildingRetryMs(repo)));
102
171
  }
103
172
  const problem = state === 'interrupted'
104
173
  ? `The gitnexus code index${where} is marked incomplete and no running analyze was found.`
@@ -106,7 +175,9 @@ export function indexNotReadyError(provider, repo, state, heal, detail) {
106
175
  ? `The gitnexus code index${where} has inconsistent metadata${detail ? ` (${detail})` : ''}, so its answers cannot be trusted.`
107
176
  : `No gitnexus code index found${where}.`;
108
177
  const [what, remediation] = healText(heal);
109
- return new CodeIntelError('E-CODE-INDEX-NOT-READY', `${problem}${what}`, remediation);
178
+ const [build, retryAfterMs] = healRetry(heal, repo);
179
+ const healName = heal ? (heal.started ? 'started' : heal.reason) : undefined;
180
+ return new CodeIntelError('E-CODE-INDEX-NOT-READY', `${problem}${what}`, remediation, notReadyData(provider, repo, state, build, retryAfterMs, healName));
110
181
  }
111
182
  /** [sentence appended to the problem, remediation] for a heal outcome. */
112
183
  function healText(heal) {
@@ -156,6 +227,18 @@ function healText(heal) {
156
227
  ];
157
228
  }
158
229
  }
230
+ /** [build, retry_after_ms] for a heal outcome: only a running/requested build or a cooldown is worth waiting for. */
231
+ function healRetry(heal, repo) {
232
+ if (!heal)
233
+ return ['none', 0];
234
+ if (heal.started)
235
+ return ['requested', buildingRetryMs(repo)];
236
+ if (heal.reason === 'already-running')
237
+ return ['running', buildingRetryMs(repo)];
238
+ if (heal.reason === 'cooldown')
239
+ return ['none', RETRY_AFTER_COOLDOWN_MS];
240
+ return ['none', 0];
241
+ }
159
242
  /**
160
243
  * The typed error for an answer discarded because the index changed while the
161
244
  * call ran: `after` is readiness re-read once the call returned. Not ready ->
@@ -164,10 +247,12 @@ function healText(heal) {
164
247
  */
165
248
  export function indexChangedDuringCallError(repo, after) {
166
249
  if (!after.ready && after.state !== 'building') {
167
- return new CodeIntelError('E-CODE-INDEX-NOT-READY', `The gitnexus code index for '${repo}' changed while this call was answered and is now ${after.state}${after.detail ? ` (${after.detail})` : ''}; the answer was discarded.`, 'Retry the same call; it requests a rebuild if one is needed (code_status shows the index state).');
250
+ return new CodeIntelError('E-CODE-INDEX-NOT-READY', `The gitnexus code index for '${repo}' changed while this call was answered and is now ${after.state}${after.detail ? ` (${after.detail})` : ''}; the answer was discarded.`, 'Retry the same call; it requests a rebuild if one is needed (code_status shows the index state).', notReadyData('gitnexus', repo, 'changed', 'none', RETRY_AFTER_CHANGED_MS));
168
251
  }
169
252
  const why = after.ready ? 'was replaced by an index build' : 'started being rebuilt';
170
- return new CodeIntelError('E-CODE-INDEX-NOT-READY', `The gitnexus code index for '${repo}' ${why} while this call was answered; the answer was discarded.`, RETRY_SOON);
253
+ return new CodeIntelError('E-CODE-INDEX-NOT-READY', `The gitnexus code index for '${repo}' ${why} while this call was answered; the answer was discarded.`, RETRY_SOON, after.ready
254
+ ? notReadyData('gitnexus', repo, 'changed', 'none', RETRY_AFTER_CHANGED_MS)
255
+ : notReadyData('gitnexus', repo, 'changed', 'running', buildingRetryMs(repo)));
171
256
  }
172
257
  /** Throw E-CODE-INDEX-NOT-READY unless the provider's index for `repo` is ready. Never starts a build. */
173
258
  export function assertCodeIndexReady(provider, repo) {
@@ -33,6 +33,8 @@ export interface AnalyzeStatus {
33
33
  failureCause?: AnalyzeFailureCause;
34
34
  /** meta.json lastCommit when the run finished (fleet's own record of the build). */
35
35
  indexedCommit?: string;
36
+ /** How long the last finished build of this folder took (estimates the wait for this one). */
37
+ previousBuildMs?: number;
36
38
  }
37
39
  export type NotStartedReason = 'already-running' | 'npx-not-found' | 'gitnexus-not-found' | 'spawn-failed' | 'remote-member' | 'gitnexus-too-old';
38
40
  /** Directory holding analyze.log + status.json for `repo`. */
@@ -88,7 +90,7 @@ export type SpawnAnalyzeOutcome = {
88
90
  detail?: string;
89
91
  };
90
92
  /**
91
- * Synchronously start `npx -y gitnexus analyze --index-only` in `repoPath` (detached off win32), with
93
+ * Synchronously start `npx -y gitnexus analyze --index-only --force` in `repoPath` (detached off win32), with
92
94
  * stdout+stderr going straight to analyze.log (a file descriptor, so the run
93
95
  * outlives this server) and status.json kept current until exit. Never
94
96
  * throws. Does NOT apply config/cooldown -- callers decide whether to start.
@@ -130,6 +132,28 @@ export declare const RECORDED_ANALYZE_MAX_AGE_MS: number;
130
132
  * throws.
131
133
  */
132
134
  export declare function isRecordedAnalyzeAlive(repoPath: string, now?: number): boolean;
135
+ /**
136
+ * Progress of the analyze run recorded for `repo` (status.json) while it has
137
+ * not finished -- the same data code_status reports under `analyze`, reduced
138
+ * to what a caller waiting on the index needs. null when no run is recorded
139
+ * for this folder or the recorded run is done. The last line and line count
140
+ * are read from analyze.log, so they are current even for a run started by an
141
+ * earlier server instance. Never throws.
142
+ */
143
+ export interface AnalyzeProgress {
144
+ phase: AnalyzePhase;
145
+ /** Milliseconds since the run started; null when its start time is unknown. */
146
+ elapsed_ms: number | null;
147
+ last_line: string;
148
+ line_count: number;
149
+ }
150
+ export declare function analyzeProgress(repoPath: string, now?: number): AnalyzeProgress | null;
151
+ /**
152
+ * How long the live build of `repo` should still take, from the folder's last
153
+ * finished build (bounded, with a margin); null when nothing is running or no
154
+ * earlier build is recorded.
155
+ */
156
+ export declare function expectedBuildRemainingMs(repoPath: string, now?: number): number | null;
133
157
  export declare const FIRST_TICK_BOUND_MS = 8000;
134
158
  /** Every code_reindex response carries the commit the index is built at (null when none/remote). */
135
159
  export type CodeReindexResult = {