sensorium-mcp 3.1.2 → 3.1.3-board.10

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 (625) hide show
  1. package/Install-Sensorium.ps1 +257 -43
  2. package/README.md +2 -0
  3. package/dist/board/api/api.js +84 -0
  4. package/dist/board/api/api.test.ts +23 -0
  5. package/dist/board/api/client.js +113 -0
  6. package/dist/board/components/BottomNav.js +32 -0
  7. package/dist/board/components/Card.js +78 -0
  8. package/dist/board/components/Combobox.js +79 -0
  9. package/dist/board/components/CommentComposer.js +29 -0
  10. package/dist/board/components/CommentList.js +42 -0
  11. package/dist/board/components/DirTreePicker.js +128 -0
  12. package/dist/board/components/Dropdown.js +67 -0
  13. package/dist/board/components/Lane.js +47 -0
  14. package/dist/board/components/PriorityChip.js +20 -0
  15. package/dist/board/components/ProfileSummary.js +89 -0
  16. package/dist/board/components/StateBanner.js +24 -0
  17. package/dist/board/components/StatusChip.js +26 -0
  18. package/dist/board/components/rateLimit.js +32 -0
  19. package/dist/board/components/rateLimit.test.ts +16 -0
  20. package/dist/board/components/time.js +14 -0
  21. package/dist/board/config.js +56 -0
  22. package/dist/board/index.html +18 -0
  23. package/dist/board/main.js +37 -0
  24. package/dist/board/mock/api.mock.js +491 -0
  25. package/dist/board/mock/api.mock.test.ts +460 -0
  26. package/dist/board/mock/fixtures.js +512 -0
  27. package/dist/board/schema/policy.js +261 -0
  28. package/dist/board/state/recur.js +24 -0
  29. package/dist/board/state/recur.test.ts +24 -0
  30. package/dist/board/state/useBoard.js +161 -0
  31. package/dist/board/state/useBuilder.js +357 -0
  32. package/dist/board/state/useBuilder.test.ts +468 -0
  33. package/dist/board/state/useCard.js +193 -0
  34. package/dist/board/state/useCard.test.ts +435 -0
  35. package/dist/board/state/useDirBrowser.js +23 -0
  36. package/dist/board/styles/board.css +2885 -0
  37. package/dist/board/styles/tokens.css +72 -0
  38. package/dist/board/vendor/vue.esm-browser.js +9 -0
  39. package/dist/board/views/App.js +61 -0
  40. package/dist/board/views/BoardView.js +153 -0
  41. package/dist/board/views/BuilderView.js +582 -0
  42. package/dist/board/views/CardView.js +382 -0
  43. package/dist/board/views/SettingsView.js +152 -0
  44. package/dist/config/agent-settings.d.ts +11 -0
  45. package/dist/config/agent-settings.d.ts.map +1 -1
  46. package/dist/config/agent-settings.js +79 -0
  47. package/dist/config/agent-settings.js.map +1 -1
  48. package/dist/config/detail-grant.d.ts +7 -16
  49. package/dist/config/detail-grant.d.ts.map +1 -1
  50. package/dist/config/detail-grant.js +12 -35
  51. package/dist/config/detail-grant.js.map +1 -1
  52. package/dist/config/index.d.ts +2 -0
  53. package/dist/config/index.d.ts.map +1 -1
  54. package/dist/config/index.js +17 -0
  55. package/dist/config/index.js.map +1 -1
  56. package/dist/config/mcp-settings.d.ts +7 -1
  57. package/dist/config/mcp-settings.d.ts.map +1 -1
  58. package/dist/config/mcp-settings.js +9 -0
  59. package/dist/config/mcp-settings.js.map +1 -1
  60. package/dist/config/misc-settings.d.ts +22 -1
  61. package/dist/config/misc-settings.d.ts.map +1 -1
  62. package/dist/config/misc-settings.js +93 -3
  63. package/dist/config/misc-settings.js.map +1 -1
  64. package/dist/config/operator-grant.d.ts +9 -0
  65. package/dist/config/operator-grant.d.ts.map +1 -0
  66. package/dist/config/operator-grant.js +24 -0
  67. package/dist/config/operator-grant.js.map +1 -0
  68. package/dist/config/voice-grant.d.ts +10 -0
  69. package/dist/config/voice-grant.d.ts.map +1 -0
  70. package/dist/config/voice-grant.js +18 -0
  71. package/dist/config/voice-grant.js.map +1 -0
  72. package/dist/dashboard/board-static.d.ts +22 -0
  73. package/dist/dashboard/board-static.d.ts.map +1 -0
  74. package/dist/dashboard/board-static.js +130 -0
  75. package/dist/dashboard/board-static.js.map +1 -0
  76. package/dist/dashboard/presets.d.ts +1 -1
  77. package/dist/dashboard/presets.d.ts.map +1 -1
  78. package/dist/dashboard/presets.js +1 -1
  79. package/dist/dashboard/presets.js.map +1 -1
  80. package/dist/dashboard/routes/agent-templates.d.ts.map +1 -1
  81. package/dist/dashboard/routes/agent-templates.js +6 -9
  82. package/dist/dashboard/routes/agent-templates.js.map +1 -1
  83. package/dist/dashboard/routes/board-body.d.ts +8 -0
  84. package/dist/dashboard/routes/board-body.d.ts.map +1 -0
  85. package/dist/dashboard/routes/board-body.js +20 -0
  86. package/dist/dashboard/routes/board-body.js.map +1 -0
  87. package/dist/dashboard/routes/board-dir-listing.d.ts +70 -0
  88. package/dist/dashboard/routes/board-dir-listing.d.ts.map +1 -0
  89. package/dist/dashboard/routes/board-dir-listing.js +192 -0
  90. package/dist/dashboard/routes/board-dir-listing.js.map +1 -0
  91. package/dist/dashboard/routes/board-lane-groups.d.ts +6 -0
  92. package/dist/dashboard/routes/board-lane-groups.d.ts.map +1 -0
  93. package/dist/dashboard/routes/board-lane-groups.js +52 -0
  94. package/dist/dashboard/routes/board-lane-groups.js.map +1 -0
  95. package/dist/dashboard/routes/board-policy.d.ts +224 -0
  96. package/dist/dashboard/routes/board-policy.d.ts.map +1 -0
  97. package/dist/dashboard/routes/board-policy.js +214 -0
  98. package/dist/dashboard/routes/board-policy.js.map +1 -0
  99. package/dist/dashboard/routes/board-profile-parse.d.ts +32 -0
  100. package/dist/dashboard/routes/board-profile-parse.d.ts.map +1 -0
  101. package/dist/dashboard/routes/board-profile-parse.js +338 -0
  102. package/dist/dashboard/routes/board-profile-parse.js.map +1 -0
  103. package/dist/dashboard/routes/board.d.ts +90 -0
  104. package/dist/dashboard/routes/board.d.ts.map +1 -0
  105. package/dist/dashboard/routes/board.js +721 -0
  106. package/dist/dashboard/routes/board.js.map +1 -0
  107. package/dist/dashboard/routes/codex.d.ts +14 -0
  108. package/dist/dashboard/routes/codex.d.ts.map +1 -0
  109. package/dist/dashboard/routes/codex.js +92 -0
  110. package/dist/dashboard/routes/codex.js.map +1 -0
  111. package/dist/dashboard/routes/prompts.d.ts +2 -2
  112. package/dist/dashboard/routes/prompts.d.ts.map +1 -1
  113. package/dist/dashboard/routes/prompts.js +2 -2
  114. package/dist/dashboard/routes/prompts.js.map +1 -1
  115. package/dist/dashboard/routes/settings.d.ts +2 -0
  116. package/dist/dashboard/routes/settings.d.ts.map +1 -1
  117. package/dist/dashboard/routes/settings.js +24 -1
  118. package/dist/dashboard/routes/settings.js.map +1 -1
  119. package/dist/dashboard/routes/skills.d.ts +7 -1
  120. package/dist/dashboard/routes/skills.d.ts.map +1 -1
  121. package/dist/dashboard/routes/skills.js +6 -6
  122. package/dist/dashboard/routes/skills.js.map +1 -1
  123. package/dist/dashboard/routes/snapshots.d.ts +2 -1
  124. package/dist/dashboard/routes/snapshots.d.ts.map +1 -1
  125. package/dist/dashboard/routes/snapshots.js +24 -18
  126. package/dist/dashboard/routes/snapshots.js.map +1 -1
  127. package/dist/dashboard/routes/templates.js +5 -5
  128. package/dist/dashboard/routes/templates.js.map +1 -1
  129. package/dist/dashboard/routes/threads-create.d.ts +17 -0
  130. package/dist/dashboard/routes/threads-create.d.ts.map +1 -1
  131. package/dist/dashboard/routes/threads-create.js +32 -10
  132. package/dist/dashboard/routes/threads-create.js.map +1 -1
  133. package/dist/dashboard/routes/threads-helpers.d.ts +11 -2
  134. package/dist/dashboard/routes/threads-helpers.d.ts.map +1 -1
  135. package/dist/dashboard/routes/threads-helpers.js +20 -3
  136. package/dist/dashboard/routes/threads-helpers.js.map +1 -1
  137. package/dist/dashboard/routes/threads-read.d.ts +16 -4
  138. package/dist/dashboard/routes/threads-read.d.ts.map +1 -1
  139. package/dist/dashboard/routes/threads-read.js +61 -55
  140. package/dist/dashboard/routes/threads-read.js.map +1 -1
  141. package/dist/dashboard/routes/threads.d.ts +2 -2
  142. package/dist/dashboard/routes/threads.d.ts.map +1 -1
  143. package/dist/dashboard/routes/threads.js +143 -29
  144. package/dist/dashboard/routes/threads.js.map +1 -1
  145. package/dist/dashboard/routes/types.d.ts +6 -0
  146. package/dist/dashboard/routes/types.d.ts.map +1 -1
  147. package/dist/dashboard/routes/types.js.map +1 -1
  148. package/dist/dashboard/routes.d.ts +2 -2
  149. package/dist/dashboard/routes.d.ts.map +1 -1
  150. package/dist/dashboard/routes.js +85 -7
  151. package/dist/dashboard/routes.js.map +1 -1
  152. package/dist/dashboard/spa.html +15 -12
  153. package/dist/data/board/board-schema.d.ts +29 -0
  154. package/dist/data/board/board-schema.d.ts.map +1 -0
  155. package/dist/data/board/board-schema.js +202 -0
  156. package/dist/data/board/board-schema.js.map +1 -0
  157. package/dist/data/board/board-types.d.ts +175 -0
  158. package/dist/data/board/board-types.d.ts.map +1 -0
  159. package/dist/data/board/board-types.js +9 -0
  160. package/dist/data/board/board-types.js.map +1 -0
  161. package/dist/data/board/card.repository.d.ts +137 -0
  162. package/dist/data/board/card.repository.d.ts.map +1 -0
  163. package/dist/data/board/card.repository.js +470 -0
  164. package/dist/data/board/card.repository.js.map +1 -0
  165. package/dist/data/board/comment.repository.d.ts +14 -0
  166. package/dist/data/board/comment.repository.d.ts.map +1 -0
  167. package/dist/data/board/comment.repository.js +42 -0
  168. package/dist/data/board/comment.repository.js.map +1 -0
  169. package/dist/data/board/lane-group.repository.d.ts +19 -0
  170. package/dist/data/board/lane-group.repository.d.ts.map +1 -0
  171. package/dist/data/board/lane-group.repository.js +66 -0
  172. package/dist/data/board/lane-group.repository.js.map +1 -0
  173. package/dist/data/board/profile-defaults.d.ts +17 -0
  174. package/dist/data/board/profile-defaults.d.ts.map +1 -0
  175. package/dist/data/board/profile-defaults.js +107 -0
  176. package/dist/data/board/profile-defaults.js.map +1 -0
  177. package/dist/data/interfaces.d.ts +1 -0
  178. package/dist/data/interfaces.d.ts.map +1 -1
  179. package/dist/data/memory/bootstrap.d.ts +1 -8
  180. package/dist/data/memory/bootstrap.d.ts.map +1 -1
  181. package/dist/data/memory/bootstrap.js +27 -37
  182. package/dist/data/memory/bootstrap.js.map +1 -1
  183. package/dist/data/memory/consolidation.d.ts +9 -31
  184. package/dist/data/memory/consolidation.d.ts.map +1 -1
  185. package/dist/data/memory/consolidation.js +22 -32
  186. package/dist/data/memory/consolidation.js.map +1 -1
  187. package/dist/data/memory/db-maintenance.d.ts +54 -0
  188. package/dist/data/memory/db-maintenance.d.ts.map +1 -0
  189. package/dist/data/memory/db-maintenance.js +81 -0
  190. package/dist/data/memory/db-maintenance.js.map +1 -0
  191. package/dist/data/memory/episodes.d.ts +2 -1
  192. package/dist/data/memory/episodes.d.ts.map +1 -1
  193. package/dist/data/memory/episodes.js +5 -1
  194. package/dist/data/memory/episodes.js.map +1 -1
  195. package/dist/data/memory/index.d.ts +0 -4
  196. package/dist/data/memory/index.d.ts.map +1 -1
  197. package/dist/data/memory/index.js +0 -4
  198. package/dist/data/memory/index.js.map +1 -1
  199. package/dist/data/memory/key-knowledge.d.ts +51 -0
  200. package/dist/data/memory/key-knowledge.d.ts.map +1 -0
  201. package/dist/data/memory/key-knowledge.js +128 -0
  202. package/dist/data/memory/key-knowledge.js.map +1 -0
  203. package/dist/data/memory/migration-runner.d.ts +1 -1
  204. package/dist/data/memory/migration-runner.d.ts.map +1 -1
  205. package/dist/data/memory/migration-runner.js +407 -1
  206. package/dist/data/memory/migration-runner.js.map +1 -1
  207. package/dist/data/memory/narrative-lint.d.ts +2 -2
  208. package/dist/data/memory/narrative-lint.d.ts.map +1 -1
  209. package/dist/data/memory/narrative-lint.js +23 -13
  210. package/dist/data/memory/narrative-lint.js.map +1 -1
  211. package/dist/data/memory/narrative-resolutions.d.ts +9 -2
  212. package/dist/data/memory/narrative-resolutions.d.ts.map +1 -1
  213. package/dist/data/memory/narrative-resolutions.js +9 -8
  214. package/dist/data/memory/narrative-resolutions.js.map +1 -1
  215. package/dist/data/memory/narrative-sources.d.ts +1 -1
  216. package/dist/data/memory/narrative-sources.d.ts.map +1 -1
  217. package/dist/data/memory/narrative-sources.js +8 -3
  218. package/dist/data/memory/narrative-sources.js.map +1 -1
  219. package/dist/data/memory/narrative-store.d.ts +24 -0
  220. package/dist/data/memory/narrative-store.d.ts.map +1 -1
  221. package/dist/data/memory/narrative-store.js +73 -35
  222. package/dist/data/memory/narrative-store.js.map +1 -1
  223. package/dist/data/memory/narrative.d.ts.map +1 -1
  224. package/dist/data/memory/narrative.js +47 -29
  225. package/dist/data/memory/narrative.js.map +1 -1
  226. package/dist/data/memory/note-archival.d.ts +1 -1
  227. package/dist/data/memory/note-archival.d.ts.map +1 -1
  228. package/dist/data/memory/note-archival.js +7 -3
  229. package/dist/data/memory/note-archival.js.map +1 -1
  230. package/dist/data/memory/note-embeddings.d.ts +7 -0
  231. package/dist/data/memory/note-embeddings.d.ts.map +1 -1
  232. package/dist/data/memory/note-embeddings.js +6 -2
  233. package/dist/data/memory/note-embeddings.js.map +1 -1
  234. package/dist/data/memory/passive-notice.repository.d.ts +70 -0
  235. package/dist/data/memory/passive-notice.repository.d.ts.map +1 -0
  236. package/dist/data/memory/passive-notice.repository.js +85 -0
  237. package/dist/data/memory/passive-notice.repository.js.map +1 -0
  238. package/dist/data/memory/schema-ddl.d.ts +120 -1
  239. package/dist/data/memory/schema-ddl.d.ts.map +1 -1
  240. package/dist/data/memory/schema-ddl.js +171 -4
  241. package/dist/data/memory/schema-ddl.js.map +1 -1
  242. package/dist/data/memory/schema-guard.d.ts.map +1 -1
  243. package/dist/data/memory/schema-guard.js +5 -41
  244. package/dist/data/memory/schema-guard.js.map +1 -1
  245. package/dist/data/memory/schema.d.ts.map +1 -1
  246. package/dist/data/memory/schema.js +10 -34
  247. package/dist/data/memory/schema.js.map +1 -1
  248. package/dist/data/memory/semantic-notes.d.ts +13 -8
  249. package/dist/data/memory/semantic-notes.d.ts.map +1 -1
  250. package/dist/data/memory/semantic-notes.js +12 -17
  251. package/dist/data/memory/semantic-notes.js.map +1 -1
  252. package/dist/data/memory/thread-registry.d.ts +330 -15
  253. package/dist/data/memory/thread-registry.d.ts.map +1 -1
  254. package/dist/data/memory/thread-registry.js +523 -67
  255. package/dist/data/memory/thread-registry.js.map +1 -1
  256. package/dist/data/memory/utils.d.ts +6 -0
  257. package/dist/data/memory/utils.d.ts.map +1 -1
  258. package/dist/data/memory/utils.js +13 -0
  259. package/dist/data/memory/utils.js.map +1 -1
  260. package/dist/data/memory/worker-lifecycle.repository.d.ts +308 -0
  261. package/dist/data/memory/worker-lifecycle.repository.d.ts.map +1 -0
  262. package/dist/data/memory/worker-lifecycle.repository.js +428 -0
  263. package/dist/data/memory/worker-lifecycle.repository.js.map +1 -0
  264. package/dist/data/optional.d.ts +16 -0
  265. package/dist/data/optional.d.ts.map +1 -0
  266. package/dist/data/optional.js +47 -0
  267. package/dist/data/optional.js.map +1 -0
  268. package/dist/index.js +156 -24
  269. package/dist/index.js.map +1 -1
  270. package/dist/integrations/openai/speech.d.ts.map +1 -1
  271. package/dist/integrations/openai/speech.js +52 -19
  272. package/dist/integrations/openai/speech.js.map +1 -1
  273. package/dist/integrations/openai/video.d.ts +1 -1
  274. package/dist/integrations/openai/video.d.ts.map +1 -1
  275. package/dist/integrations/openai/video.js +13 -8
  276. package/dist/integrations/openai/video.js.map +1 -1
  277. package/dist/integrations/telegram/types.d.ts +11 -0
  278. package/dist/integrations/telegram/types.d.ts.map +1 -1
  279. package/dist/lib/http-retry.d.ts +91 -0
  280. package/dist/lib/http-retry.d.ts.map +1 -0
  281. package/dist/lib/http-retry.js +177 -0
  282. package/dist/lib/http-retry.js.map +1 -0
  283. package/dist/lib/mcp-http-port.d.ts +12 -0
  284. package/dist/lib/mcp-http-port.d.ts.map +1 -0
  285. package/dist/lib/mcp-http-port.js +19 -0
  286. package/dist/lib/mcp-http-port.js.map +1 -0
  287. package/dist/lib/paths.d.ts +29 -4
  288. package/dist/lib/paths.d.ts.map +1 -1
  289. package/dist/lib/paths.js +31 -4
  290. package/dist/lib/paths.js.map +1 -1
  291. package/dist/lib/types.d.ts +2 -0
  292. package/dist/lib/types.d.ts.map +1 -1
  293. package/dist/lib/usage-metering/pricing.js +1 -1
  294. package/dist/lib/usage-metering/pricing.js.map +1 -1
  295. package/dist/lib/usage-metering/sink.d.ts +4 -0
  296. package/dist/lib/usage-metering/sink.d.ts.map +1 -1
  297. package/dist/lib/usage-metering/sink.js +6 -4
  298. package/dist/lib/usage-metering/sink.js.map +1 -1
  299. package/dist/lib/utils.d.ts +31 -0
  300. package/dist/lib/utils.d.ts.map +1 -1
  301. package/dist/lib/utils.js +49 -0
  302. package/dist/lib/utils.js.map +1 -1
  303. package/dist/llm/prompts/narrative.d.ts.map +1 -1
  304. package/dist/llm/prompts/narrative.js +27 -86
  305. package/dist/llm/prompts/narrative.js.map +1 -1
  306. package/dist/log-parsing/log-events.d.ts +38 -0
  307. package/dist/log-parsing/log-events.d.ts.map +1 -0
  308. package/dist/log-parsing/log-events.js +2 -0
  309. package/dist/log-parsing/log-events.js.map +1 -0
  310. package/dist/log-parsing/parser-registry.d.ts +4 -0
  311. package/dist/log-parsing/parser-registry.d.ts.map +1 -0
  312. package/dist/log-parsing/parser-registry.js +18 -0
  313. package/dist/log-parsing/parser-registry.js.map +1 -0
  314. package/dist/log-parsing/parsers/claude.d.ts +6 -0
  315. package/dist/log-parsing/parsers/claude.d.ts.map +1 -0
  316. package/dist/log-parsing/parsers/claude.js +100 -0
  317. package/dist/log-parsing/parsers/claude.js.map +1 -0
  318. package/dist/log-parsing/parsers/codex.d.ts +6 -0
  319. package/dist/log-parsing/parsers/codex.d.ts.map +1 -0
  320. package/dist/log-parsing/parsers/codex.js +116 -0
  321. package/dist/log-parsing/parsers/codex.js.map +1 -0
  322. package/dist/log-parsing/parsers/copilot.d.ts +6 -0
  323. package/dist/log-parsing/parsers/copilot.d.ts.map +1 -0
  324. package/dist/log-parsing/parsers/copilot.js +65 -0
  325. package/dist/log-parsing/parsers/copilot.js.map +1 -0
  326. package/dist/log-parsing/parsers/json-lines.d.ts +9 -0
  327. package/dist/log-parsing/parsers/json-lines.d.ts.map +1 -0
  328. package/dist/log-parsing/parsers/json-lines.js +25 -0
  329. package/dist/log-parsing/parsers/json-lines.js.map +1 -0
  330. package/dist/log-parsing/render.d.ts +33 -0
  331. package/dist/log-parsing/render.d.ts.map +1 -0
  332. package/dist/log-parsing/render.js +113 -0
  333. package/dist/log-parsing/render.js.map +1 -0
  334. package/dist/log-parsing/text.d.ts +8 -0
  335. package/dist/log-parsing/text.d.ts.map +1 -0
  336. package/dist/log-parsing/text.js +20 -0
  337. package/dist/log-parsing/text.js.map +1 -0
  338. package/dist/server/http-server.d.ts +8 -1
  339. package/dist/server/http-server.d.ts.map +1 -1
  340. package/dist/server/http-server.js +41 -19
  341. package/dist/server/http-server.js.map +1 -1
  342. package/dist/server/port-holder.d.ts +94 -0
  343. package/dist/server/port-holder.d.ts.map +1 -0
  344. package/dist/server/port-holder.js +122 -0
  345. package/dist/server/port-holder.js.map +1 -0
  346. package/dist/services/agent-spawn.service.d.ts +50 -5
  347. package/dist/services/agent-spawn.service.d.ts.map +1 -1
  348. package/dist/services/agent-spawn.service.js +59 -66
  349. package/dist/services/agent-spawn.service.js.map +1 -1
  350. package/dist/services/background-runner.d.ts +0 -1
  351. package/dist/services/background-runner.d.ts.map +1 -1
  352. package/dist/services/background-runner.js +0 -58
  353. package/dist/services/background-runner.js.map +1 -1
  354. package/dist/services/board/board-signals.d.ts +45 -0
  355. package/dist/services/board/board-signals.d.ts.map +1 -0
  356. package/dist/services/board/board-signals.js +170 -0
  357. package/dist/services/board/board-signals.js.map +1 -0
  358. package/dist/services/board/card-briefing.d.ts +24 -0
  359. package/dist/services/board/card-briefing.d.ts.map +1 -0
  360. package/dist/services/board/card-briefing.js +132 -0
  361. package/dist/services/board/card-briefing.js.map +1 -0
  362. package/dist/services/board/card-diagnostics.d.ts +25 -0
  363. package/dist/services/board/card-diagnostics.d.ts.map +1 -0
  364. package/dist/services/board/card-diagnostics.js +50 -0
  365. package/dist/services/board/card-diagnostics.js.map +1 -0
  366. package/dist/services/board/live-root-thread.d.ts +8 -0
  367. package/dist/services/board/live-root-thread.d.ts.map +1 -0
  368. package/dist/services/board/live-root-thread.js +2 -0
  369. package/dist/services/board/live-root-thread.js.map +1 -0
  370. package/dist/services/board/orchestrator.service.d.ts +119 -0
  371. package/dist/services/board/orchestrator.service.d.ts.map +1 -0
  372. package/dist/services/board/orchestrator.service.js +387 -0
  373. package/dist/services/board/orchestrator.service.js.map +1 -0
  374. package/dist/services/board/release-worker.d.ts +43 -0
  375. package/dist/services/board/release-worker.d.ts.map +1 -0
  376. package/dist/services/board/release-worker.js +96 -0
  377. package/dist/services/board/release-worker.js.map +1 -0
  378. package/dist/services/board/report-capture.d.ts +94 -0
  379. package/dist/services/board/report-capture.d.ts.map +1 -0
  380. package/dist/services/board/report-capture.js +398 -0
  381. package/dist/services/board/report-capture.js.map +1 -0
  382. package/dist/services/board/worker-spawn.d.ts +89 -0
  383. package/dist/services/board/worker-spawn.d.ts.map +1 -0
  384. package/dist/services/board/worker-spawn.js +177 -0
  385. package/dist/services/board/worker-spawn.js.map +1 -0
  386. package/dist/services/board/worktree.d.ts +45 -0
  387. package/dist/services/board/worktree.d.ts.map +1 -0
  388. package/dist/services/board/worktree.js +183 -0
  389. package/dist/services/board/worktree.js.map +1 -0
  390. package/dist/services/broker-client.d.ts +84 -2
  391. package/dist/services/broker-client.d.ts.map +1 -1
  392. package/dist/services/broker-client.js +72 -6
  393. package/dist/services/broker-client.js.map +1 -1
  394. package/dist/services/claude-spawn.service.d.ts +5 -0
  395. package/dist/services/claude-spawn.service.d.ts.map +1 -1
  396. package/dist/services/claude-spawn.service.js +37 -21
  397. package/dist/services/claude-spawn.service.js.map +1 -1
  398. package/dist/services/codex-spawn.service.d.ts +8 -3
  399. package/dist/services/codex-spawn.service.d.ts.map +1 -1
  400. package/dist/services/codex-spawn.service.js +84 -67
  401. package/dist/services/codex-spawn.service.js.map +1 -1
  402. package/dist/services/consolidation.service.d.ts.map +1 -1
  403. package/dist/services/consolidation.service.js +5 -49
  404. package/dist/services/consolidation.service.js.map +1 -1
  405. package/dist/services/copilot-spawn.service.d.ts +1 -1
  406. package/dist/services/copilot-spawn.service.d.ts.map +1 -1
  407. package/dist/services/copilot-spawn.service.js +10 -5
  408. package/dist/services/copilot-spawn.service.js.map +1 -1
  409. package/dist/services/daily-session.d.ts +24 -11
  410. package/dist/services/daily-session.d.ts.map +1 -1
  411. package/dist/services/daily-session.js +113 -33
  412. package/dist/services/daily-session.js.map +1 -1
  413. package/dist/services/death-alert.service.d.ts +55 -0
  414. package/dist/services/death-alert.service.d.ts.map +1 -0
  415. package/dist/services/death-alert.service.js +64 -0
  416. package/dist/services/death-alert.service.js.map +1 -0
  417. package/dist/services/dispatcher/broker.d.ts +66 -0
  418. package/dist/services/dispatcher/broker.d.ts.map +1 -1
  419. package/dist/services/dispatcher/broker.js +60 -52
  420. package/dist/services/dispatcher/broker.js.map +1 -1
  421. package/dist/services/dispatcher/poller.d.ts.map +1 -1
  422. package/dist/services/dispatcher/poller.js +31 -24
  423. package/dist/services/dispatcher/poller.js.map +1 -1
  424. package/dist/services/http-retry.d.ts +1 -90
  425. package/dist/services/http-retry.d.ts.map +1 -1
  426. package/dist/services/http-retry.js +1 -176
  427. package/dist/services/http-retry.js.map +1 -1
  428. package/dist/services/intent.d.ts +15 -1
  429. package/dist/services/intent.d.ts.map +1 -1
  430. package/dist/services/intent.js +39 -27
  431. package/dist/services/intent.js.map +1 -1
  432. package/dist/services/keeper.service.d.ts +76 -3
  433. package/dist/services/keeper.service.d.ts.map +1 -1
  434. package/dist/services/keeper.service.js +112 -35
  435. package/dist/services/keeper.service.js.map +1 -1
  436. package/dist/services/mcp-config.service.d.ts.map +1 -1
  437. package/dist/services/mcp-config.service.js +14 -1
  438. package/dist/services/mcp-config.service.js.map +1 -1
  439. package/dist/services/memory-briefing.service.d.ts +1 -1
  440. package/dist/services/memory-briefing.service.d.ts.map +1 -1
  441. package/dist/services/memory-briefing.service.js +28 -73
  442. package/dist/services/memory-briefing.service.js.map +1 -1
  443. package/dist/services/passive-notice.service.d.ts +56 -0
  444. package/dist/services/passive-notice.service.d.ts.map +1 -0
  445. package/dist/services/passive-notice.service.js +92 -0
  446. package/dist/services/passive-notice.service.js.map +1 -0
  447. package/dist/services/predefined-prompts.d.ts +11 -0
  448. package/dist/services/predefined-prompts.d.ts.map +1 -0
  449. package/dist/services/predefined-prompts.js +25 -0
  450. package/dist/services/predefined-prompts.js.map +1 -0
  451. package/dist/services/process.service.d.ts +111 -27
  452. package/dist/services/process.service.d.ts.map +1 -1
  453. package/dist/services/process.service.js +245 -173
  454. package/dist/services/process.service.js.map +1 -1
  455. package/dist/services/spawn-common.d.ts +281 -5
  456. package/dist/services/spawn-common.d.ts.map +1 -1
  457. package/dist/services/spawn-common.js +884 -188
  458. package/dist/services/spawn-common.js.map +1 -1
  459. package/dist/services/spawn-exit-watcher.d.ts +45 -35
  460. package/dist/services/spawn-exit-watcher.d.ts.map +1 -1
  461. package/dist/services/spawn-exit-watcher.js +120 -100
  462. package/dist/services/spawn-exit-watcher.js.map +1 -1
  463. package/dist/services/telegram.d.ts +31 -8
  464. package/dist/services/telegram.d.ts.map +1 -1
  465. package/dist/services/telegram.js +58 -26
  466. package/dist/services/telegram.js.map +1 -1
  467. package/dist/services/thread-health.service.d.ts +8 -0
  468. package/dist/services/thread-health.service.d.ts.map +1 -1
  469. package/dist/services/thread-health.service.js +14 -10
  470. package/dist/services/thread-health.service.js.map +1 -1
  471. package/dist/services/thread-lifecycle.service.d.ts +17 -1
  472. package/dist/services/thread-lifecycle.service.d.ts.map +1 -1
  473. package/dist/services/thread-lifecycle.service.js +47 -6
  474. package/dist/services/thread-lifecycle.service.js.map +1 -1
  475. package/dist/services/thread-log-reader.d.ts +81 -0
  476. package/dist/services/thread-log-reader.d.ts.map +1 -0
  477. package/dist/services/thread-log-reader.js +141 -0
  478. package/dist/services/thread-log-reader.js.map +1 -0
  479. package/dist/services/thread-purge.service.d.ts +200 -0
  480. package/dist/services/thread-purge.service.d.ts.map +1 -0
  481. package/dist/services/thread-purge.service.js +644 -0
  482. package/dist/services/thread-purge.service.js.map +1 -0
  483. package/dist/services/topic.service.d.ts +44 -2
  484. package/dist/services/topic.service.d.ts.map +1 -1
  485. package/dist/services/topic.service.js +74 -13
  486. package/dist/services/topic.service.js.map +1 -1
  487. package/dist/services/usage/usage-inbox-notifier.d.ts +50 -0
  488. package/dist/services/usage/usage-inbox-notifier.d.ts.map +1 -0
  489. package/dist/services/usage/usage-inbox-notifier.js +118 -0
  490. package/dist/services/usage/usage-inbox-notifier.js.map +1 -0
  491. package/dist/services/usage/usage-poller.service.d.ts +41 -0
  492. package/dist/services/usage/usage-poller.service.d.ts.map +1 -0
  493. package/dist/services/usage/usage-poller.service.js +67 -0
  494. package/dist/services/usage/usage-poller.service.js.map +1 -0
  495. package/dist/services/usage/usage-snapshot-provider.d.ts +40 -0
  496. package/dist/services/usage/usage-snapshot-provider.d.ts.map +1 -0
  497. package/dist/services/usage/usage-snapshot-provider.js +89 -0
  498. package/dist/services/usage/usage-snapshot-provider.js.map +1 -0
  499. package/dist/services/usage/usage-types.d.ts +28 -0
  500. package/dist/services/usage/usage-types.d.ts.map +1 -0
  501. package/dist/services/usage/usage-types.js +14 -0
  502. package/dist/services/usage/usage-types.js.map +1 -0
  503. package/dist/services/worker-birth.d.ts +154 -0
  504. package/dist/services/worker-birth.d.ts.map +1 -0
  505. package/dist/services/worker-birth.js +274 -0
  506. package/dist/services/worker-birth.js.map +1 -0
  507. package/dist/services/worker-cleanup.service.d.ts +242 -19
  508. package/dist/services/worker-cleanup.service.d.ts.map +1 -1
  509. package/dist/services/worker-cleanup.service.js +893 -355
  510. package/dist/services/worker-cleanup.service.js.map +1 -1
  511. package/dist/services/worker-lifecycle-executor.d.ts +42 -0
  512. package/dist/services/worker-lifecycle-executor.d.ts.map +1 -0
  513. package/dist/services/worker-lifecycle-executor.js +63 -0
  514. package/dist/services/worker-lifecycle-executor.js.map +1 -0
  515. package/dist/services/worker-single-use.d.ts +92 -0
  516. package/dist/services/worker-single-use.d.ts.map +1 -0
  517. package/dist/services/worker-single-use.js +155 -0
  518. package/dist/services/worker-single-use.js.map +1 -0
  519. package/dist/sessions/mcp-registry.d.ts +33 -2
  520. package/dist/sessions/mcp-registry.d.ts.map +1 -1
  521. package/dist/sessions/mcp-registry.js +153 -30
  522. package/dist/sessions/mcp-registry.js.map +1 -1
  523. package/dist/test-bootstrap.d.ts +19 -12
  524. package/dist/test-bootstrap.d.ts.map +1 -1
  525. package/dist/test-bootstrap.js +69 -21
  526. package/dist/test-bootstrap.js.map +1 -1
  527. package/dist/test-tripwire.test-support.d.ts +75 -0
  528. package/dist/test-tripwire.test-support.d.ts.map +1 -0
  529. package/dist/test-tripwire.test-support.js +353 -0
  530. package/dist/test-tripwire.test-support.js.map +1 -0
  531. package/dist/tools/defs/memory-defs.d.ts.map +1 -1
  532. package/dist/tools/defs/memory-defs.js +12 -4
  533. package/dist/tools/defs/memory-defs.js.map +1 -1
  534. package/dist/tools/defs/session-defs.d.ts.map +1 -1
  535. package/dist/tools/defs/session-defs.js +26 -10
  536. package/dist/tools/defs/session-defs.js.map +1 -1
  537. package/dist/tools/defs/utility-defs.js +1 -1
  538. package/dist/tools/defs/utility-defs.js.map +1 -1
  539. package/dist/tools/delegate-tool.d.ts +81 -1
  540. package/dist/tools/delegate-tool.d.ts.map +1 -1
  541. package/dist/tools/delegate-tool.js +840 -219
  542. package/dist/tools/delegate-tool.js.map +1 -1
  543. package/dist/tools/memory-tools.d.ts.map +1 -1
  544. package/dist/tools/memory-tools.js +66 -9
  545. package/dist/tools/memory-tools.js.map +1 -1
  546. package/dist/tools/response-builders.d.ts.map +1 -1
  547. package/dist/tools/response-builders.js +12 -8
  548. package/dist/tools/response-builders.js.map +1 -1
  549. package/dist/tools/session-tools.d.ts.map +1 -1
  550. package/dist/tools/session-tools.js +3 -32
  551. package/dist/tools/session-tools.js.map +1 -1
  552. package/dist/tools/skill-tools.js +1 -1
  553. package/dist/tools/skill-tools.js.map +1 -1
  554. package/dist/tools/start-session-tool.d.ts.map +1 -1
  555. package/dist/tools/start-session-tool.js +66 -20
  556. package/dist/tools/start-session-tool.js.map +1 -1
  557. package/dist/tools/utility-tools.d.ts.map +1 -1
  558. package/dist/tools/utility-tools.js +38 -3
  559. package/dist/tools/utility-tools.js.map +1 -1
  560. package/dist/tools/wait/auto-forward.d.ts.map +1 -1
  561. package/dist/tools/wait/auto-forward.js +8 -3
  562. package/dist/tools/wait/auto-forward.js.map +1 -1
  563. package/dist/tools/wait/consolidation-strategy.d.ts +42 -0
  564. package/dist/tools/wait/consolidation-strategy.d.ts.map +1 -0
  565. package/dist/tools/wait/consolidation-strategy.js +50 -0
  566. package/dist/tools/wait/consolidation-strategy.js.map +1 -0
  567. package/dist/tools/wait/drive-handler.d.ts +5 -7
  568. package/dist/tools/wait/drive-handler.d.ts.map +1 -1
  569. package/dist/tools/wait/drive-handler.js +45 -59
  570. package/dist/tools/wait/drive-handler.js.map +1 -1
  571. package/dist/tools/wait/media-processor.d.ts.map +1 -1
  572. package/dist/tools/wait/media-processor.js +8 -4
  573. package/dist/tools/wait/media-processor.js.map +1 -1
  574. package/dist/tools/wait/message-delivery.d.ts +9 -6
  575. package/dist/tools/wait/message-delivery.d.ts.map +1 -1
  576. package/dist/tools/wait/message-delivery.js +77 -58
  577. package/dist/tools/wait/message-delivery.js.map +1 -1
  578. package/dist/tools/wait/message-processing.d.ts.map +1 -1
  579. package/dist/tools/wait/message-processing.js +2 -1
  580. package/dist/tools/wait/message-processing.js.map +1 -1
  581. package/dist/tools/wait/poll-loop.d.ts.map +1 -1
  582. package/dist/tools/wait/poll-loop.js +339 -239
  583. package/dist/tools/wait/poll-loop.js.map +1 -1
  584. package/package.json +4 -3
  585. package/templates/azure-devops-securevault.default.md +20 -6
  586. package/templates/board-quality-checklist.default.md +121 -0
  587. package/templates/buildless-vue-preview.default.md +47 -0
  588. package/templates/expert-code-review.default.md +12 -0
  589. package/templates/handoff.default.md +41 -18
  590. package/templates/increment-pr-pipeline.default.md +79 -0
  591. package/templates/swarm.default.md +1 -0
  592. package/templates/worker-autonomous.default.md +1 -0
  593. package/templates/worker-delegate.default.md +1 -0
  594. package/dist/dashboard/log-parser.d.ts +0 -65
  595. package/dist/dashboard/log-parser.d.ts.map +0 -1
  596. package/dist/dashboard/log-parser.js +0 -219
  597. package/dist/dashboard/log-parser.js.map +0 -1
  598. package/dist/data/memory/reflection-dedup.d.ts +0 -17
  599. package/dist/data/memory/reflection-dedup.d.ts.map +0 -1
  600. package/dist/data/memory/reflection-dedup.js +0 -55
  601. package/dist/data/memory/reflection-dedup.js.map +0 -1
  602. package/dist/data/memory/reflection-gates.d.ts +0 -40
  603. package/dist/data/memory/reflection-gates.d.ts.map +0 -1
  604. package/dist/data/memory/reflection-gates.js +0 -220
  605. package/dist/data/memory/reflection-gates.js.map +0 -1
  606. package/dist/data/memory/reflection-sources.d.ts +0 -13
  607. package/dist/data/memory/reflection-sources.d.ts.map +0 -1
  608. package/dist/data/memory/reflection-sources.js +0 -115
  609. package/dist/data/memory/reflection-sources.js.map +0 -1
  610. package/dist/data/memory/reflection.d.ts +0 -43
  611. package/dist/data/memory/reflection.d.ts.map +0 -1
  612. package/dist/data/memory/reflection.js +0 -329
  613. package/dist/data/memory/reflection.js.map +0 -1
  614. package/dist/llm/prompts/reflection.d.ts +0 -6
  615. package/dist/llm/prompts/reflection.d.ts.map +0 -1
  616. package/dist/llm/prompts/reflection.js +0 -77
  617. package/dist/llm/prompts/reflection.js.map +0 -1
  618. package/dist/services/memory-pruning.service.d.ts +0 -12
  619. package/dist/services/memory-pruning.service.d.ts.map +0 -1
  620. package/dist/services/memory-pruning.service.js +0 -179
  621. package/dist/services/memory-pruning.service.js.map +0 -1
  622. package/templates/daily-review.default.md +0 -26
  623. package/templates/fire-and-forget.default.md +0 -76
  624. package/templates/offload.default.md +0 -33
  625. package/templates/sensorium-repair.default.md +0 -114
@@ -9,46 +9,297 @@
9
9
  * lifecycle plumbing.
10
10
  */
11
11
  import { spawn, spawnSync } from "node:child_process";
12
- import { closeSync, existsSync, fstatSync, openSync, readSync, unlinkSync, writeFileSync, readFileSync, } from "node:fs";
12
+ import { randomBytes } from "node:crypto";
13
+ import { closeSync, existsSync, openSync, readFileSync, writeFileSync } from "node:fs";
14
+ import { open, readFile, unlink } from "node:fs/promises";
13
15
  import { tmpdir } from "node:os";
14
16
  import { join } from "node:path";
15
17
  import { log } from "../lib/logger.js";
16
- import { getMaxConcurrentThreads, getAgentType } from "../config/index.js";
18
+ import { getAgentType, getClaudeCustomEnvVars, getClaudeOauthToken, getCopilotCustomEnvVars, getCopilotSpawnEnv, getMaxConcurrentThreads, } from "../config/index.js";
17
19
  import { initMemoryDb } from "../data/memory/schema.js";
18
- import { getThread } from "../data/memory/thread-registry.js";
20
+ import { clearWorkerGrace, isWorkerReleased, wasWorkerTaskConsumed, } from "../data/memory/worker-lifecycle.repository.js";
21
+ import { getThread, threadRepository } from "../data/memory/thread-registry.js";
19
22
  import { sendTelegramMessage } from "./telegram.js";
20
- import { errorMessage } from "../lib/utils.js";
23
+ import { deliverDeathAlert } from "./death-alert.service.js";
24
+ import { syncKeepAliveToSettings } from "./keep-alive-sync.service.js";
25
+ import { ALERT_NAME_MAX_CHARS, errorMessage, escapeHtmlWithin, TELEGRAM_MESSAGE_MAX_CHARS, } from "../lib/utils.js";
26
+ import { Optional } from "../data/optional.js";
27
+ import { isMcpHttpPort, parseMcpHttpPort } from "../lib/mcp-http-port.js";
28
+ import { extractDeathCause } from "../log-parsing/render.js";
29
+ import { parserForAgent } from "../log-parsing/parser-registry.js";
30
+ import { agentTypeFromLogPath, recordedThreadLogPath, resolveThreadLogPath, } from "./thread-log-reader.js";
21
31
  import { deleteTelegramTopicByBotApi } from "./topic.service.js";
22
- import { PROCESS_PIDS_DIR, PENDING_TASKS_DIR, THREAD_LOGS_DIR, spawnedThreads, wasTaskConsumed, clearTaskConsumed, } from "./process.service.js";
32
+ import { PROCESS_PIDS_DIR, PENDING_TASKS_DIR, THREAD_LOGS_DIR, findAliveThreadViaPidFile, isThreadAlive, killThreadTree, readPidFiles, spawnedThreadFromPidFile, } from "./process.service.js";
23
33
  import { ThreadState } from "./thread-lifecycle.service.js";
24
34
  import { brokerSpawn, brokerListThread } from "./broker-client.js";
25
- import { watchBrokerSpawnExit } from "./spawn-exit-watcher.js";
26
- import { decommissionWorker, clearWorkerGrace } from "./worker-cleanup.service.js";
35
+ import { decommissionWorker, endingFor, notifyWorkerDeath, } from "./worker-cleanup.service.js";
36
+ import { ensureDecommissioned, isWorkerDecommissionInFlight } from "./worker-lifecycle-executor.js";
27
37
  import { writeThreadHeartbeatSync, clearThreadHeartbeat } from "../data/file-storage.js";
28
- // ── Worker respawn (failed MCP-handshake recovery) ──────────────────────────
29
- // A swarm worker is a headless `claude -p` process whose only useful tools come
30
- // from this server's MCP HTTP transport. Claude does NOT block its turn until MCP
31
- // servers finish connecting; under concurrent swarm spawns the handshake can
32
- // still be pending when the turn starts, so the worker boots with only built-in
33
- // tools, has no start_session/wait_for_instructions, answers "I don't have those
34
- // tools" into invisible stdout, and exits code 0 in ~25-35s — never consuming its
35
- // pre-queued task. The reliable "did no work" signal is that the worker NEVER
36
- // consumed a task (wasTaskConsumed === false) — NOT merely that the pending-task
37
- // file is present, because that file is a shared append-only mailbox that
38
- // report_progress and cross-thread sends can recreate AFTER a worker already did
39
- // its work. Respawning on "file present" re-ran finished workers → duplicate posts.
38
+ // ── Birth-death respawn (failed startup recovery) ───────────────────────────
39
+ // An agent child is a headless process whose only useful tools come from this
40
+ // server's MCP HTTP transport. Two failure modes kill one at BIRTH, before it
41
+ // ever does anything:
42
+ // • an API-level error — bad/unsupported model, auth, quota — exit code 1
43
+ // within seconds, the cause printed to the child's stdout log. Any CLI can
44
+ // hit this; it killed a Copilot root on 2026-08-12;
45
+ // • the turn-1 MCP tool-list race, Claude-specific: Claude does NOT block its
46
+ // turn until MCP servers finish connecting, so the child boots with only
47
+ // built-in tools, has no start_session/wait_for_instructions, answers "I
48
+ // don't have those tools" into invisible stdout and exits code 0 in ~25-35s.
49
+ // (CLAUDE_MCP_WAIT_INSTRUCTION below asks Claude — and only Claude, which is
50
+ // the only CLI with the tool — to wait it out; this net is the backstop for
51
+ // when that does not take.)
52
+ // The DETECTION is agent-agnostic either way: a thread that never started is one
53
+ // that never started. So the net is the same for every thread type, and only the
54
+ // "it never started" signal differs (see diedAtBirth):
55
+ // • worker: it NEVER consumed a task (worker_lifecycle.task_consumed_at IS
56
+ // NULL) — NOT merely that the pending-task file is present, because that file
57
+ // is a shared append-only mailbox that report_progress and cross-thread sends
58
+ // can recreate AFTER a worker already did its work. Respawning on "file
59
+ // present" re-ran finished workers → duplicate posts. The fact is read from
60
+ // the DATABASE and not from a process-local Set, because this net runs for a
61
+ // worker that outlived a server restart too (the exit watcher resolves it
62
+ // from its PID file): a Set is empty in that process, and an empty Set says
63
+ // "never did any work" about a worker that finished its own;
64
+ // • every other thread (root/branch): it never reached start_session, i.e.
65
+ // never registered a session for THIS spawn.
40
66
  // We respawn the same threadId (reusing its existing topic) up to
41
- // MAX_WORKER_RESPAWNS times ONLY for the never-consumed handshake race; a worker
42
- // that consumed its task is strictly single-use and is never respawned.
43
- const MAX_WORKER_RESPAWNS = 3;
44
- // Only respawn a task-unstarted worker whose life was short enough to match the
45
- // handshake-race signature — a long-lived worker that merely has a late second
46
- // task queued should not be blindly relaunched.
47
- const WORKER_RESPAWN_UPTIME_MS = 180_000;
48
- // Per-threadId respawn counter, cleared when the worker finally reaches
49
- // decommission (normal completion or give-up). In-memory only: after a server
50
- // restart workers are not resumed anyway, so a persisted counter buys nothing.
51
- const workerRespawnAttempts = new Map();
67
+ // MAX_BIRTH_DEATH_RESPAWNS times; a worker that consumed its task is strictly
68
+ // single-use and is never respawned.
69
+ export const MAX_BIRTH_DEATH_RESPAWNS = 3;
70
+ // Only respawn a thread whose life was short enough to match the born-dead
71
+ // signature — a long-lived worker that merely has a late second task queued, or
72
+ // a root that exits hours after its session ran, must not be blindly relaunched.
73
+ //
74
+ // This threshold is also what makes clean_shutdown a SOUND proxy for "never
75
+ // registered a session": a thread that is going to call start_session does so in
76
+ // its first seconds, so inside this window "not registered" means "never got
77
+ // there". Raise it far and the proxy rots — a long-lived thread whose
78
+ // registration write failed, or one restarted by an older code path, would start
79
+ // looking born-dead and be relaunched under a live topic.
80
+ const BIRTH_DEATH_RESPAWN_UPTIME_MS = 180_000;
81
+ // Per-threadId respawn counter, cleared when the thread finally reaches
82
+ // decommission / exit bookkeeping (normal completion or give-up). In-memory
83
+ // only: a server restart drops it, which costs at most one extra respawn round
84
+ // for a thread the keeper brings back — cheap enough that persisting it (and
85
+ // having to expire it) buys nothing.
86
+ const birthDeathRespawnAttempts = new Map();
87
+ /** True when the exited process died at birth and is worth relaunching once more. */
88
+ export function diedAtBirth(signal) {
89
+ if (signal.uptimeMs >= BIRTH_DEATH_RESPAWN_UPTIME_MS)
90
+ return false;
91
+ return signal.isWorker ? signal.taskPresent && !signal.taskConsumed : !signal.sessionRegistered;
92
+ }
93
+ // Bounded tail read: a long-lived agent's stdout log grows to megabytes, and
94
+ // what a crash report needs is only at its very end.
95
+ const LOG_TAIL_READ_BYTES = 8192;
96
+ // A segfault report only needs the last thing the agent was doing.
97
+ const SEGFAULT_TAIL_LINES = 3;
98
+ /** Enough lines to carry a death message no parser could reach, no more. */
99
+ const ALERT_TAIL_LINES = 8;
100
+ /** A wedge snapshot is a local forensic dump, not a chat quote, so it keeps far
101
+ * more of the log than the alert paths — and needs a matching byte window,
102
+ * because one stream-json event is a whole line and 30 of them do not fit in
103
+ * {@link LOG_TAIL_READ_BYTES}. */
104
+ export const WEDGE_TAIL_LINES = 30;
105
+ const WEDGE_TAIL_READ_BYTES = 262_144;
106
+ // Windows STATUS_ACCESS_VIOLATION — the exit code of an agent that segfaulted.
107
+ const ACCESS_VIOLATION_EXIT_CODE = 3221226505;
108
+ // Below this length an env value is too generic to replace text by (a bare "1",
109
+ // a host name) — replacing it would corrupt the quote instead of protecting it.
110
+ const MIN_REDACTABLE_SECRET_CHARS = 8;
111
+ const SECRET_ENV_KEY_RE = /TOKEN|SECRET|KEY|PASSWORD|CREDENTIAL/i;
112
+ /**
113
+ * Every secret this server can hand a child — NOT just the ones sitting in its
114
+ * own environment. The keys that matter most here are on ENV_DENYLIST precisely
115
+ * so they never reach process.env, and each is re-injected explicitly at spawn:
116
+ * the Claude OAuth token into EVERY Claude child (claude-spawn.service.ts), the
117
+ * Copilot BYOK key into every Copilot child, and operator custom env vars into
118
+ * both. An env-only scan would therefore miss exactly the credential an auth
119
+ * failure prints while dying at birth.
120
+ */
121
+ export function collectChildSecrets() {
122
+ const ambient = {};
123
+ // process.env is an external boundary: unset keys read as undefined.
124
+ for (const [key, value] of Object.entries(process.env))
125
+ if (value)
126
+ ambient[key] = value;
127
+ // Resolved the same way claude-spawn resolves it, so this is the value the
128
+ // child actually receives — not a second, unused copy from the other source.
129
+ const claudeOauthToken = process.env.CLAUDE_CODE_OAUTH_TOKEN ?? getClaudeOauthToken();
130
+ return {
131
+ ...ambient,
132
+ ...(claudeOauthToken ? { CLAUDE_CODE_OAUTH_TOKEN: claudeOauthToken } : {}),
133
+ ...getCopilotSpawnEnv(),
134
+ ...getClaudeCustomEnvVars(),
135
+ ...getCopilotCustomEnvVars(),
136
+ };
137
+ }
138
+ /**
139
+ * Blank out any secret this server holds before quoting process output. stderr
140
+ * shares the child's stdout fd, children run with permission checks skipped, and
141
+ * we hand some of them secrets explicitly — so a crash dump or an echoed env can
142
+ * put a live credential in the tail we are about to send to Telegram. Done HERE,
143
+ * at the single read, so no caller can forget it.
144
+ */
145
+ function redactSecrets(text, secrets) {
146
+ let out = text;
147
+ for (const [key, value] of Object.entries(secrets)) {
148
+ if (value.length < MIN_REDACTABLE_SECRET_CHARS)
149
+ continue;
150
+ if (!SECRET_ENV_KEY_RE.test(key))
151
+ continue;
152
+ out = out.replaceAll(value, `[redacted ${key}]`);
153
+ }
154
+ return out;
155
+ }
156
+ /**
157
+ * Why the process died, in its own words, secrets redacted — the one thing worth
158
+ * quoting to the operator.
159
+ *
160
+ * Prefers the shared agent log parsers (src/log-parsing): what the operator
161
+ * needs is the cause the CLI reported — "does not support this model", "I don't
162
+ * have those tools" — not an arbitrary window of stream-json. The agent type
163
+ * comes from the filename {@link buildThreadLogPath} encodes.
164
+ *
165
+ * Falls back to {@link readRawTail} whenever parsing yields no cause, because a
166
+ * parser is a whitelist and a dying CLI does not respect it. Real logs on this
167
+ * machine prove it: a Codex run out of quota ends in `{"type":"error",…}` /
168
+ * `turn.failed`, and a born-dead Copilot wrote the bare line "Package extraction
169
+ * took 12458ms" with no JSON at all. stdout and stderr share one fd, so ANY
170
+ * plain-text death message lands in this file unparsed. The fallback is what
171
+ * keeps this from ever quoting less than the byte tail it replaced.
172
+ *
173
+ * Empty only when the log is gone, unreadable, or truly silent — callers must
174
+ * handle that, so it is an Optional rather than an "" that reads like a
175
+ * successfully-silent process.
176
+ */
177
+ export async function readFinalAgentOutput(logFile, secrets) {
178
+ let resolved;
179
+ try {
180
+ // Resolved INSIDE a try, not as a default argument: collectChildSecrets
181
+ // reads settings.json, which THROWS on a corrupt file with no backup. Every
182
+ // caller here runs mid-teardown — the give-up alert, the keeper's death
183
+ // notice — and treats this function as total; a throw would escape past
184
+ // the exit path and skip markExited/decommission entirely. Without the
185
+ // map there is also nothing to redact WITH, so quoting anything at all would
186
+ // be unsafe: report the log as unreadable instead.
187
+ resolved = secrets ?? collectChildSecrets();
188
+ }
189
+ catch {
190
+ return Optional.empty();
191
+ }
192
+ try {
193
+ const cause = await parseDeathCause(logFile);
194
+ if (cause.length > 0)
195
+ return Optional.of(redactSecrets(cause, resolved));
196
+ }
197
+ catch {
198
+ // Expected, not exceptional: the log may be rotated, still empty, or gone.
199
+ // Not fatal either — the raw tail below reads it again and reports absence.
200
+ }
201
+ return readRawTail(logFile, ALERT_TAIL_LINES, resolved);
202
+ }
203
+ /**
204
+ * The cause the CLI named, or "" when no parser covers this log or it is silent.
205
+ *
206
+ * Reads the WHOLE file — the parsers need every event to know which failure was
207
+ * the last word — and does so asynchronously: an agent's stream-json log runs to
208
+ * megabytes, and both callers (the give-up alert, the keeper's death notice) are
209
+ * async paths where a multi-megabyte readFileSync would stall the event loop for
210
+ * the entire read.
211
+ */
212
+ async function parseDeathCause(logFile) {
213
+ const agentType = agentTypeFromLogPath(logFile);
214
+ if (!agentType.has())
215
+ return "";
216
+ const raw = await readFile(logFile, "utf-8");
217
+ return extractDeathCause(parserForAgent(agentType.get()).parse(raw));
218
+ }
219
+ /**
220
+ * Raw byte tail of a crashed process's log, secrets redacted.
221
+ *
222
+ * One caller: a segfault (0xC0000005) kills the CLI mid-write, so the last line
223
+ * is a truncated JSON fragment the parsers correctly discard — and that fragment
224
+ * is exactly the "what was it doing" this diagnostic wants. Anything
225
+ * operator-facing must go through {@link readFinalAgentOutput}, which tries the
226
+ * parsers first and only then falls back to the same raw tail.
227
+ */
228
+ export function readCrashLogTail(logFile, secrets) {
229
+ return readRawTail(logFile, SEGFAULT_TAIL_LINES, secrets);
230
+ }
231
+ /**
232
+ * Stdout tail for the keeper's wedge forensic snapshot, secrets redacted.
233
+ *
234
+ * The snapshot used to slice its 30 lines straight off disk with no redaction at
235
+ * all, and "local-only" was no defence: stderr shares the child's stdout fd, and
236
+ * children are handed the Claude OAuth token, the Copilot BYOK key and operator
237
+ * custom env vars — none of which sit in ambient env by design. One CLI echoing
238
+ * its config put a live credential in a file nobody prunes. Routing through
239
+ * {@link readRawTail} also buys the snapshot the mid-line-fragment drop, which is
240
+ * where a straddled secret would otherwise survive as a bare suffix.
241
+ */
242
+ export function readWedgeLogTail(logFile, secrets) {
243
+ return readRawTail(logFile, WEDGE_TAIL_LINES, secrets, WEDGE_TAIL_READ_BYTES);
244
+ }
245
+ /**
246
+ * Last `maxLines` non-empty lines of a log file, secrets redacted.
247
+ *
248
+ * Only the final `readBytes` are read, so on any larger file the
249
+ * window opens mid-line. That first fragment is dropped: a stream-json log is one
250
+ * huge line per event, so it is unreadable on its own AND is where a secret
251
+ * straddling the boundary would survive as a bare suffix the redactor cannot
252
+ * match. Private on purpose — the three exported readers above are the only ways
253
+ * in; each chooses the line count and byte window for its diagnostic, so callers
254
+ * cannot grow a second general-purpose tail parser.
255
+ *
256
+ * Async for the same reason as {@link parseDeathCause}: this runs on the exit
257
+ * teardown path, and the fd dance is no harder through a FileHandle than through
258
+ * the sync calls it replaced — the `finally` still closes it on every path,
259
+ * including a read that throws.
260
+ */
261
+ async function readRawTail(logFile, maxLines, secrets, readBytes = LOG_TAIL_READ_BYTES) {
262
+ try {
263
+ const resolved = secrets ?? collectChildSecrets();
264
+ const handle = await open(logFile, "r");
265
+ try {
266
+ const size = (await handle.stat()).size;
267
+ const readSize = Math.min(readBytes, size);
268
+ const buf = Buffer.alloc(readSize);
269
+ await handle.read(buf, 0, readSize, size - readSize);
270
+ const lines = buf.toString("utf-8").split(/\r?\n/);
271
+ if (size > readSize)
272
+ lines.shift();
273
+ const tail = lines.filter(Boolean).slice(-maxLines).join("\n");
274
+ return tail.length > 0 ? Optional.of(redactSecrets(tail, resolved)) : Optional.empty();
275
+ }
276
+ finally {
277
+ await handle.close();
278
+ }
279
+ }
280
+ catch {
281
+ // Expected, not exceptional: the log may be rotated, still empty, or gone.
282
+ return Optional.empty();
283
+ }
284
+ }
285
+ /**
286
+ * The give-up alert. It QUOTES the dead process's final output instead of
287
+ * guessing a cause: the real reason (unsupported model, auth, quota, "I don't
288
+ * have those tools") is always in that text, and every guess we shipped before
289
+ * sent the operator to check credits that were fine.
290
+ */
291
+ export function buildBirthDeathGiveUpAlert(opts) {
292
+ const missed = opts.isWorker ? "never consumed its task" : "never registered a session";
293
+ const keepAliveNote = opts.keepAliveCleared
294
+ ? " Its keep-alive is now OFF so it stops being restarted — turn it back on from the dashboard once the cause above is fixed."
295
+ : "";
296
+ const head = `⚠️ <b>${escapeHtmlWithin(opts.name, ALERT_NAME_MAX_CHARS)}</b> (thread ${opts.threadId}) ` +
297
+ `died at startup on all ${opts.respawns} relaunches — it ${missed}, so the ` +
298
+ `net is giving up.${keepAliveNote} Its final output:\n`;
299
+ const budget = TELEGRAM_MESSAGE_MAX_CHARS - head.length - "<pre></pre>".length;
300
+ const tail = escapeHtmlWithin(opts.finalOutput.orElse("(no output captured)"), budget);
301
+ return `${head}<pre>${tail}</pre>`;
302
+ }
52
303
  /**
53
304
  * Env vars that must never leak from the server's ambient environment into
54
305
  * spawned agent children. The COPILOT_PROVIDER_* keys carry the BYOK endpoint
@@ -63,6 +314,17 @@ const ENV_DENYLIST = new Set([
63
314
  "DASHBOARD_TOKEN",
64
315
  "MCP_START_COMMAND",
65
316
  "WATCHER_START_COMMAND",
317
+ // Isolated-runtime plumbing that must stay MCP-private. When IsolateMcpRuntime is
318
+ // on, the supervisor exports NPM_CONFIG_CACHE (a dedicated npm/npx cache) so the
319
+ // MCP's own `npx …@latest` restart resolves/stages under a private cache the dev
320
+ // repo never touches. That var is inherited all the way down to here — if it leaked
321
+ // into agent workers, a worker's `npm`/`npx` in the dev checkout would use the SAME
322
+ // private cache the MCP restarts from, re-introducing the exact shared-cache coupling
323
+ // the feature exists to sever. Deny it so workers fall back to the default cache.
324
+ // (No-op when the knob is off: the var is simply unset.) MCP_WORKING_DIR is the
325
+ // MCP's private cwd hint — meaningless to children, dropped for the same hygiene.
326
+ "NPM_CONFIG_CACHE",
327
+ "MCP_WORKING_DIR",
66
328
  "CLAUDE_CODE_OAUTH_TOKEN",
67
329
  "COPILOT_PROVIDER_BASE_URL",
68
330
  "COPILOT_PROVIDER_TYPE",
@@ -168,10 +430,14 @@ export function resolveWindowsCliPath(name) {
168
430
  cliPathCache.set(cacheKey, resolved);
169
431
  return resolved;
170
432
  }
433
+ /** Windows command shims must be launched through a shell. */
434
+ function usesWindowsCommandShell(cliPath) {
435
+ return process.platform === "win32" && /\.(cmd|bat)$/i.test(cliPath);
436
+ }
171
437
  /** Parse MCP transport from env. Returns null if port is not set or invalid. */
172
438
  function parseSensoriumTransport() {
173
- const raw = process.env.MCP_HTTP_PORT;
174
- const httpPort = raw && /^\d+$/.test(raw.trim()) ? parseInt(raw.trim(), 10) : 0;
439
+ const raw = process.env.MCP_HTTP_PORT ?? "";
440
+ const httpPort = isMcpHttpPort(raw) ? parseMcpHttpPort(raw) : 0;
175
441
  return httpPort > 0 ? { httpPort, secret: process.env.MCP_HTTP_SECRET || null } : null;
176
442
  }
177
443
  export const normalizeWorkingDirectory = (workingDirectory) => {
@@ -189,21 +455,24 @@ export const isStartupCleanupInProgress = () => startupCleanupInProgress;
189
455
  export const setStartupCleanupInProgress = (v) => {
190
456
  startupCleanupInProgress = v;
191
457
  };
192
- // ── Shared spawn choreography ───────────────────────────────────────────────
193
- // The pieces every agent spawn goes through in the same order: preflight
194
- // checks, log-path construction, common spawn options, and the launch/register
195
- // tail (launchAgent below — broker spawn with a flagged local fallback). Agent
196
- // modules keep only their own CLI quirks: env building, argument lists and
197
- // prompt delivery.
198
458
  /**
199
459
  * Shared spawn preflight: refuse when the dashboard's max-concurrent-threads
200
460
  * limit is already reached, then require the MCP HTTP transport. Kept here so
201
461
  * both checks and their error wording apply uniformly to Claude, Copilot and
202
462
  * Codex spawns rather than drifting per agent.
463
+ *
464
+ * The limit counts the LIVE processes the PID files record — the host's process
465
+ * record, so a process a predecessor spawned counts as much as one this process
466
+ * did. A PID file whose process is gone does not count: its removal waits on a
467
+ * confirmed death, which a broker that does not know the thread can withhold
468
+ * indefinitely. Liveness is thread-scoped, so an unreachable broker counts every
469
+ * file (fails closed).
203
470
  */
204
- export function checkSpawnPreconditions(agentLabel) {
205
- const maxConcurrent = getMaxConcurrentThreads();
206
- if (spawnedThreads.length >= maxConcurrent)
471
+ export async function checkSpawnPreconditions(agentLabel, deps = {}) {
472
+ const maxConcurrent = (deps.maxConcurrentThreads ?? getMaxConcurrentThreads)();
473
+ const isAlive = deps.isAlive ?? isThreadAlive;
474
+ const alive = await Promise.all((await readPidFiles()).map((e) => isAlive(e.threadId, e.pid, e.startedAt)));
475
+ if (alive.filter(Boolean).length >= maxConcurrent)
207
476
  return {
208
477
  error: `Concurrent thread limit reached (${maxConcurrent}). Wait for existing threads to finish.`,
209
478
  };
@@ -214,14 +483,85 @@ export function checkSpawnPreconditions(agentLabel) {
214
483
  };
215
484
  return { transport };
216
485
  }
217
- /** Per-thread log file: sanitized name + threadId + date under THREAD_LOGS_DIR. */
218
- export function buildThreadLogPath(name, threadId, ext) {
219
- const safeName = name.replace(/[^a-zA-Z0-9_-]/g, "_");
220
- return join(THREAD_LOGS_DIR, `${safeName}_${threadId}_${new Date().toISOString().slice(0, 10)}.${ext}`);
486
+ /**
487
+ * The marker that makes one SPAWN own one log file: the UTC time of day plus
488
+ * three random bytes, lowercase alphanumerics and a single dash so the whole
489
+ * marker stays one filename segment.
490
+ *
491
+ * It cannot be derived from the process it names. The path is an INPUT to the
492
+ * launch — the broker opens it itself (`FILE_APPEND_DATA | OPEN_ALWAYS` in
493
+ * `ChildProcessLauncher.LaunchSuspended`), `launchLocalChild` with
494
+ * `openSync(plan.logFilePath, "a")` — and a broker spawn's OS identity
495
+ * (`proc.startTimeMs`, the `startedAt` registered below) is reported back only
496
+ * AFTER that launch. So the name has to be settled before anything about the
497
+ * process is knowable, which is why the marker is minted here rather than
498
+ * passed in by the three `*-spawn.service.ts` callers.
499
+ *
500
+ * The clock half is for whoever reads the directory: it orders a thread's
501
+ * generations within their shared date. The RANDOM half is what SEPARATES two
502
+ * spawns the clock cannot — the birth-death net can respawn one thread id inside
503
+ * the same second, and a marker that were only a clock would hand the respawn its
504
+ * predecessor's file back, which is the whole defect.
505
+ *
506
+ * It does not GUARANTEE uniqueness, and nothing here reserves the name: three
507
+ * random bytes give 2^24 values, so two spawns landing in the same UTC second
508
+ * collide with probability ~1/16.7M per pair (the birthday bound reaches ~1% only
509
+ * around 580 same-second spawns of one thread id — a duplicate was produced in a
510
+ * 50,000-call synthetic loop, which no respawn path can approach). A collision
511
+ * costs exactly what the old scheme cost ALWAYS: those two spawns append to one
512
+ * file, and a death notice for one of them can quote the other. Bounded to that
513
+ * pair, and it does not spread to the thread's other generations.
514
+ */
515
+ function mintSpawnMarker(now) {
516
+ const timeOfDay = now.toISOString().slice(11, 19).replace(/:/g, "");
517
+ return `${timeOfDay}-${randomBytes(3).toString("hex")}`;
518
+ }
519
+ /**
520
+ * Per-SPAWN log file: sanitized name + agentType + threadId + UTC date +
521
+ * {@link mintSpawnMarker} under THREAD_LOGS_DIR. The agentType segment sits
522
+ * BEFORE threadId so each agent type writes to its own single-format file even
523
+ * when a thread's type is switched on the same day (otherwise claude
524
+ * stream-json and copilot plain-text lines interleave in one file and break the
525
+ * dashboard log stream). Placing it before threadId also preserves the
526
+ * `_<threadId>_<date>…` suffix that the mtime-based log consumers match on
527
+ * (`threadLogNameRe`).
528
+ *
529
+ * The marker is what keeps the name from naming a CHANNEL instead of a process.
530
+ * Both spawn paths APPEND to whatever already sits at this path, so while the
531
+ * name ended at the date a same-day respawn of one thread id wrote INTO its
532
+ * predecessor's file: `parseDeathCause` then read one file holding two
533
+ * generations, and `extractDeathCause`, walking back from the end, could
534
+ * announce a fresh worker's death with the PREVIOUS run's last words. One spawn,
535
+ * one file — to the collision bound {@link mintSpawnMarker} states, which nothing
536
+ * here reserves against.
537
+ *
538
+ * The date segment stays human-readable and in place: every transcript already
539
+ * on disk ends there, and nothing renames them.
540
+ */
541
+ export function buildThreadLogPath(name, agentType, threadId, ext) {
542
+ const sanitize = (s) => s.replace(/[^a-zA-Z0-9_-]/g, "_");
543
+ const safeName = sanitize(name);
544
+ const safeAgentType = sanitize(agentType);
545
+ const now = new Date();
546
+ return join(THREAD_LOGS_DIR, `${safeName}_${safeAgentType}_${threadId}_${now.toISOString().slice(0, 10)}_${mintSpawnMarker(now)}.${ext}`);
221
547
  }
548
+ /**
549
+ * Claude-ONLY escape hatch from the turn-1 MCP tool-list race: Claude freezes
550
+ * the turn's tool list while MCP servers are still connecting, so a new session
551
+ * can start with no sensorium tools at all. WaitForMcpServers forces a second
552
+ * request with a refreshed list. Codex and Copilot have no equivalent tool, so
553
+ * naming it in their prompts would only send them hunting for something that
554
+ * does not exist.
555
+ */
556
+ export const CLAUDE_MCP_WAIT_INSTRUCTION = "If the sensorium tools are not visible to you this turn, call the built-in WaitForMcpServers tool FIRST, then proceed.";
557
+ /** Agent types that run the Claude CLI. "fable" is a Claude thread pinned to a
558
+ * premium model (agent-spawn.service.ts), so it hits the same turn-1 race and
559
+ * needs the same escape hatch — a Copilot-shaped prompt would strand it. */
560
+ const CLAUDE_CLI_AGENT_TYPES = new Set(["claude", "fable"]);
222
561
  /** Session-bootstrap prompt shared by the Claude and Copilot CLIs (Codex
223
562
  * delivers its own autonomous-loop prompt over stdin instead). */
224
- export const buildSessionPrompt = (name, threadId) => `Start remote session with sensorium. Thread name = '${name}'. Use threadId=${threadId} when calling start_session.`;
563
+ export const buildSessionPrompt = (name, threadId, agentType) => `Start remote session with sensorium. Thread name = '${name}'. Use threadId=${threadId} when calling start_session.` +
564
+ (CLAUDE_CLI_AGENT_TYPES.has(agentType) ? ` ${CLAUDE_MCP_WAIT_INSTRUCTION}` : "");
225
565
  /**
226
566
  * Spawn options shared by every agent child: detached from this (ephemeral)
227
567
  * server process, stdout/stderr on the child-owned log fd, and .cmd/.bat
@@ -231,151 +571,386 @@ export const buildSessionPrompt = (name, threadId) => `Start remote session with
231
571
  function detachedChildOptions(cliPath, outFd, env, cwd, stdin = "ignore") {
232
572
  return {
233
573
  stdio: [stdin, outFd, outFd],
234
- shell: process.platform === "win32" && /\.(cmd|bat)$/i.test(cliPath),
574
+ shell: usesWindowsCommandShell(cliPath),
235
575
  detached: true,
236
576
  windowsHide: false,
237
577
  env,
238
578
  cwd: cwd || undefined,
239
579
  };
240
580
  }
241
- async function handleProcessExit(code, threadId, pid, pidFilePath, entry, processLabel, threadLifecycle) {
242
- const idx = spawnedThreads.indexOf(entry);
243
- if (idx !== -1)
244
- spawnedThreads.splice(idx, 1);
245
- // Only delete PID file if it still belongs to this process — a replacement
246
- // process may have already overwritten the file with its own PID.
247
- let stillOwnedPidFile = false;
581
+ /** Build the adapter used exclusively by worker process-exit teardown. */
582
+ export function createExitTelegramAdapter(token, sendMessage = sendTelegramMessage, deleteForumTopic = deleteTelegramTopicByBotApi) {
583
+ return {
584
+ deleteForumTopic: async (chatId, threadId) => {
585
+ if (token && chatId)
586
+ await deleteForumTopic(token, chatId, threadId);
587
+ },
588
+ sendMessage: async (chatId, text, parseMode, threadId) => {
589
+ if (token && chatId)
590
+ await sendMessage(token, chatId, text, { parseMode, threadId });
591
+ },
592
+ };
593
+ }
594
+ /**
595
+ * Construct the exit-path Telegram adapter and hand it to decommissionWorker.
596
+ * Extracted from the exit path as the single seam that WIRES the adapter
597
+ * (carrying deleteForumTopic AND sendMessage) into worker teardown, so the
598
+ * wiring is unit-testable: strip the adapter here and a preserved-dirty /
599
+ * remove-failed worktree warning is silently dropped — which a test asserts on.
600
+ */
601
+ export async function decommissionExitedWorker(ctx, overrides = {}) {
602
+ const telegram = createExitTelegramAdapter(ctx.token, overrides.sendMessage, overrides.deleteForumTopic);
603
+ const deps = {
604
+ db: ctx.db,
605
+ telegram,
606
+ chatId: ctx.chatId,
607
+ threadLifecycle: ctx.threadLifecycle,
608
+ };
609
+ if (overrides.killWorker)
610
+ deps.killWorker = overrides.killWorker;
611
+ if (overrides.isWorkerAlive)
612
+ deps.isWorkerAlive = overrides.isWorkerAlive;
613
+ if (overrides.removeWorktree)
614
+ deps.removeWorktree = overrides.removeWorktree;
615
+ await ensureDecommissioned(ctx.entry.threadId, "process-exit", () => decommissionWorker(ctx.entry, deps, ctx.exitCode));
616
+ }
617
+ /**
618
+ * Relaunch a process that died at birth, or tell the operator why we stopped.
619
+ *
620
+ * Runs for EVERY thread type: a root that never reached start_session was, until
621
+ * this net covered it, left to the keeper's blind backoff and a guessed alert.
622
+ */
623
+ export async function runBirthDeathNet(ctx, overrides = {}) {
624
+ const { entry, db, threadLifecycle } = ctx;
625
+ const threadId = entry.threadId;
626
+ const reg = getThread(db, threadId);
627
+ // clean_shutdown is the EXISTING record of session registration:
628
+ // registerSpawnedProcess resets it to 1 when a process is attached to the
629
+ // thread and start_session's markSessionRunning flips it to 0, so `=== false`
630
+ // means "THIS spawn reached start_session".
631
+ const signal = {
632
+ isWorker: entry.threadType === "worker",
633
+ uptimeMs: Date.now() - entry.startedAt,
634
+ taskPresent: existsSync(join(PENDING_TASKS_DIR, `${threadId}.txt`)),
635
+ taskConsumed: wasWorkerTaskConsumed(db, threadId),
636
+ sessionRegistered: reg?.cleanShutdown === false,
637
+ };
638
+ if (!diedAtBirth(signal)) {
639
+ warnOnLateWorkerMailbox(entry, signal);
640
+ return "passed";
641
+ }
642
+ const spent = birthDeathRespawnAttempts.get(threadId) ?? 0;
643
+ if (spent >= MAX_BIRTH_DEATH_RESPAWNS) {
644
+ await giveUpAtBirth(ctx, signal.isWorker, overrides, spent);
645
+ return "gave-up";
646
+ }
647
+ // The keeper restarts any keepAlive thread it finds with no live PID and no
648
+ // heartbeat — and the exit path dropped BOTH before calling us, while the spawn
649
+ // below can take minutes (broker budget plus reconcile rounds). Without this
650
+ // re-check the keeper and the net each start an agent on the same topic; on a
651
+ // local-spawn host nothing downstream deduplicates them. Checked BEFORE the
652
+ // budget is charged so a keeper-won race never spends a relaunch we never made.
653
+ const findAlive = overrides.findAlive ?? findAliveThreadViaPidFile;
654
+ const replacement = await findAlive(threadId);
655
+ if (replacement.has()) {
656
+ log.warn(`[respawn] thread ${threadId} already has a live PID ${replacement.get().pid} (the keeper got there first) — not spawning a second one`);
657
+ return "superseded";
658
+ }
659
+ birthDeathRespawnAttempts.set(threadId, spent + 1);
660
+ log.warn(`[respawn] thread ${threadId} ("${entry.name}") died at birth (code ${ctx.exitCode.orElse("none")}) after ${Math.round(signal.uptimeMs / 1000)}s — respawn attempt ${spent + 1}/${MAX_BIRTH_DEATH_RESPAWNS}`);
661
+ const dispatchSpawn = overrides.dispatchSpawn ?? (await import("./agent-spawn.service.js")).dispatchSpawn;
662
+ const memorySource = entry.memorySourceThreadId ?? reg?.rootThreadId;
663
+ const res = await dispatchSpawn((reg?.client ?? getAgentType()), entry.name, threadId, threadLifecycle, {
664
+ db,
665
+ ...(reg?.workingDirectory ? { workingDirectory: reg.workingDirectory } : {}),
666
+ ...(memorySource ? { memorySourceThreadId: memorySource } : {}),
667
+ ...(entry.threadType ? { runtimeThreadType: entry.threadType } : {}),
668
+ // The ONE exception the spawn choke point's refusal grants, and it grants it only
669
+ // after re-deriving this net's own verdict from state: a worker that never read
670
+ // its task, whose ending nobody has claimed, on a row that is not retired. The
671
+ // flag says WHICH exception is being asked for, never that it is allowed.
672
+ relaunchBornDead: true,
673
+ });
674
+ if ("pid" in res) {
675
+ log.info(`[respawn] thread ${threadId} relaunched as PID=${res.pid}`);
676
+ return "respawned";
677
+ }
678
+ // A relaunch that FAILS is ordinary and transient — the concurrent-thread
679
+ // limit, a supervisor mid-restart (an MCP self-update does exactly this), a CLI
680
+ // not yet on PATH. Giving up here would clear keepAlive after ZERO relaunches
681
+ // and leave the thread dead until the operator re-enabled it by hand. Fall
682
+ // through instead: the exit path marks it exited and the keeper retries.
683
+ log.warn(`[respawn] thread ${threadId} relaunch failed: ${res.error} — leaving the thread to the keeper's retry`);
684
+ return "passed";
685
+ }
686
+ /**
687
+ * A single-use worker that exited with content still in its mailbox: a late
688
+ * append (report_progress parent-forward / cross-thread send) after the task was
689
+ * already done. It must NOT be re-run, so make the reuse attempt visible instead
690
+ * of silently duplicating work — the mailbox is deleted by decommission moments
691
+ * later. Worker-only: a root keeps its mailbox across restarts, so the same state
692
+ * there is ordinary, not a reuse.
693
+ */
694
+ function warnOnLateWorkerMailbox(entry, signal) {
695
+ if (!signal.isWorker || !signal.taskPresent || !signal.taskConsumed)
696
+ return;
697
+ log.warn(`[respawn] worker thread ${entry.threadId} ("${entry.name}") exited with a non-empty mailbox after already consuming its task — NOT respawning (single-use); discarding late mailbox content.`);
698
+ }
699
+ /**
700
+ * Stop relaunching and say why, quoting the dead process's own last words.
701
+ *
702
+ * For anything but a worker this also clears keepAlive: otherwise the keeper
703
+ * relaunches the thread, the net gets a fresh budget (the counter is dropped by
704
+ * the exit path), and the two loop forever on a cause no restart can fix.
705
+ */
706
+ async function giveUpAtBirth(ctx, isWorker, overrides, respawns) {
707
+ const { entry, db } = ctx;
708
+ const threadId = entry.threadId;
709
+ log.error(`[respawn] thread ${threadId} ("${entry.name}") died at birth on all ${respawns} relaunches — giving up`);
710
+ // Only write the flag when it is actually set: a thread the operator already
711
+ // stopped must not be "changed" by the net, and the alert must not claim a
712
+ // keep-alive was turned off when none was on.
713
+ const keepAliveCleared = !isWorker && getThread(db, threadId)?.keepAlive === true;
714
+ if (keepAliveCleared) {
715
+ threadRepository.updateThread(db, threadId, { keepAlive: false });
716
+ // settings.json is the watcher's copy of keep-alive state, read at boot
717
+ // before this server is up. Every other keepAlive write mirrors it; skipping
718
+ // it here would leave the file still claiming the thread is keep-alive.
719
+ syncKeepAliveToSettings(db);
720
+ }
721
+ if (!ctx.token)
722
+ return;
723
+ const sendMessage = overrides.sendMessage ?? sendTelegramMessage;
724
+ const readFinalOutput = overrides.readFinalOutput ?? readFinalAgentOutput;
725
+ const text = buildBirthDeathGiveUpAlert({
726
+ name: entry.name,
727
+ threadId,
728
+ respawns,
729
+ // Through the shared rule, like every other reader of a dying process: this
730
+ // alert is the OPERATOR's copy of the cause, and a record with no path (an
731
+ // adopted registration, a pre-upgrade PID file) would otherwise make it say
732
+ // "(no output captured)" with the log sitting on disk.
733
+ finalOutput: await readFinalOutput((await resolveThreadLogPath(recordedThreadLogPath(entry.logFile), threadId)).orElse("")),
734
+ isWorker,
735
+ keepAliveCleared,
736
+ });
737
+ // Routing (worker → the orchestrator that spawned it, anything else → the
738
+ // operator) and the general-chat fallback both live in death-alert.service, so
739
+ // this alert and the keeper's death notice cannot drift apart.
740
+ await deliverDeathAlert({
741
+ db,
742
+ threadId,
743
+ isWorker,
744
+ text,
745
+ deliver: (body, topicId) => sendMessage(ctx.token, ctx.chatId, body, {
746
+ parseMode: "HTML",
747
+ ...(topicId.has() ? { threadId: topicId.get() } : {}),
748
+ }),
749
+ });
750
+ }
751
+ /** One line per exited process, plus crash context — ALWAYS, respawn or not.
752
+ * Async only for the segfault branch's log tail; the common path never awaits
753
+ * anything and returns after the single info line. */
754
+ async function logProcessExit(exitCode, threadId, pid, entry, processLabel) {
755
+ const uptimeSec = Math.round((Date.now() - entry.startedAt) / 1000);
756
+ const segfaulted = exitCode.has() && exitCode.get() === ACCESS_VIOLATION_EXIT_CODE;
757
+ const exitDesc = segfaulted
758
+ ? "ACCESS_VIOLATION (0xC0000005)"
759
+ : exitCode.has() && exitCode.get() === 1
760
+ ? "error (1)"
761
+ : `code ${exitCode.orElse("none (killed by signal)")}`;
762
+ log.info(`[start_thread] ${processLabel} PID=${pid} thread ${threadId} exited: ${exitDesc} — uptime ${uptimeSec}s`);
763
+ if (!segfaulted)
764
+ return;
765
+ // Detect batch crashes — how many process records remain beside this one.
766
+ const remaining = (await readPidFiles()).length;
767
+ log.warn(`[start_thread] SEGFAULT thread ${threadId} — ${remaining} PID file(s) remain, uptime was ${uptimeSec}s (${Math.round(uptimeSec / 3600)}h)`);
768
+ // Tail the thread log to see what the agent was doing when it crashed, through
769
+ // the same rule the notice paths use so a record with no path still has
770
+ // something to read. A missing log is normal here (the crash may have taken
771
+ // it), hence the default.
772
+ const tail = (await readCrashLogTail((await resolveThreadLogPath(recordedThreadLogPath(entry.logFile), threadId)).orElse(""))).orElse("(no log)");
773
+ log.warn(`[start_thread] SEGFAULT context (last log): ${tail.replaceAll("\n", " | ").substring(0, 300)}`);
774
+ }
775
+ /** The exit path for a process known only by its PID file — what the exit
776
+ * watcher resolves (spawn-exit-watcher.ts). */
777
+ export async function handlePidFileExit(entry, exitCode, threadLifecycle, db, overrides = {}) {
778
+ await handleProcessExit(exitCode, entry.filePath, spawnedThreadFromPidFile(entry, `Thread ${entry.threadId}`), entry.agentLabel ?? "restored agent", threadLifecycle, db, overrides);
779
+ }
780
+ /** True while the PID file still records this pid. A replacement process that
781
+ * registered on the thread id rewrites it with its own. */
782
+ async function pidFileStillOwned(pidFilePath, pid) {
248
783
  try {
249
- const raw = readFileSync(pidFilePath, "utf-8");
250
- const parsed = JSON.parse(raw);
251
- if (parsed.pid === pid) {
252
- unlinkSync(pidFilePath);
253
- stillOwnedPidFile = true;
254
- }
784
+ return JSON.parse(await readFile(pidFilePath, "utf-8")).pid === pid;
255
785
  }
256
786
  catch {
257
- /* file missing or unparseable — already cleaned up */
787
+ return false; // missing or unparseable — already cleaned up
258
788
  }
789
+ }
790
+ /**
791
+ * The one exit handler: every death — a broker-spawned one the exit watcher
792
+ * resolved, a local child's exit listener — runs here once. The PID file is the
793
+ * process's record and the watcher's list, so it is removed LAST: an exit cut
794
+ * short by a restart is found and run again by the next server's watcher.
795
+ */
796
+ async function handleProcessExit(exitCode, pidFilePath, entry, processLabel, threadLifecycle, db, overrides) {
797
+ const { threadId, pid } = entry;
259
798
  // Clear the heartbeat so a stale (spawn-time / last-activity) timestamp can't
260
- // make this now-dead thread look alive and block the keeper's restart. Only do
261
- // this if no replacement has taken over the PID file — otherwise the live
262
- // replacement owns the heartbeat and we must not delete it.
263
- if (stillOwnedPidFile)
799
+ // make this now-dead thread look alive and block the keeper's restart. Only
800
+ // while no replacement has taken over the PID file — a live replacement owns
801
+ // the heartbeat.
802
+ if (await pidFileStillOwned(pidFilePath, pid))
264
803
  clearThreadHeartbeat(threadId);
265
- let db;
804
+ // Log BEFORE the net: a born-dead process is relaunched and returns early, and
805
+ // a root crashing with 0xC0000005 three times over must not do so invisibly.
806
+ await logProcessExit(exitCode, threadId, pid, entry, processLabel);
266
807
  try {
267
- db = initMemoryDb();
268
- const currentState = threadLifecycle.getThreadState(db, threadId);
269
- const isTerminal = currentState === ThreadState.Archived || currentState === ThreadState.Expired;
270
- if (isTerminal) {
271
- // Row is already Archived/Expired — teardown already ran, so we skip
272
- // decommissionWorker. But a worker that self-exited DURING its TTL grace
273
- // still has a live grace-map entry; drop it here so the in-memory map does
274
- // not slowly leak deadlines for threads that will never be swept again.
275
- clearWorkerGrace(threadId);
276
- }
277
- else {
278
- if (entry.threadType === "worker") {
279
- const token = process.env.TELEGRAM_TOKEN || "";
280
- const chatId = process.env.TELEGRAM_CHAT_ID || "";
281
- // Handshake-race recovery: relaunch ONLY a worker that NEVER consumed a
282
- // task (wasTaskConsumed === false) and exited fast enough to match the
283
- // toolless-startup signature. A worker that already consumed its task is
284
- // single-use — never respawned — so a late mailbox append can't cause it
285
- // to re-run and duplicate its output.
286
- const uptimeMs = Date.now() - entry.startedAt;
287
- const taskFile = join(PENDING_TASKS_DIR, `${threadId}.txt`);
288
- const taskPresent = existsSync(taskFile);
289
- const consumed = wasTaskConsumed(threadId);
290
- if (taskPresent && !consumed && uptimeMs < WORKER_RESPAWN_UPTIME_MS) {
291
- const attempts = (workerRespawnAttempts.get(threadId) ?? 0) + 1;
292
- if (attempts <= MAX_WORKER_RESPAWNS) {
293
- workerRespawnAttempts.set(threadId, attempts);
294
- log.warn(`[respawn] worker thread ${threadId} ("${entry.name}") exited (code ${code}) after ${Math.round(uptimeMs / 1000)}s with task never consumed — respawn attempt ${attempts}/${MAX_WORKER_RESPAWNS}`);
295
- const reg = getThread(db, threadId);
296
- const agentType = (reg?.client ?? getAgentType());
297
- const { dispatchSpawn } = await import("./agent-spawn.service.js");
298
- const res = await dispatchSpawn(agentType, entry.name, threadId, threadLifecycle, reg?.workingDirectory ?? undefined, entry.memorySourceThreadId ?? reg?.rootThreadId ?? undefined, "worker", db);
299
- if ("pid" in res) {
300
- log.info(`[respawn] worker thread ${threadId} relaunched as PID=${res.pid}`);
301
- return; // task file preserved for the new process — skip decommission
302
- }
303
- log.warn(`[respawn] worker thread ${threadId} relaunch failed: ${res.error} — decommissioning`);
304
- }
305
- else {
306
- log.error(`[respawn] worker thread ${threadId} ("${entry.name}") exhausted ${MAX_WORKER_RESPAWNS} respawn attempts — giving up`);
307
- if (token) {
308
- const safeName = entry.name
309
- .replace(/&/g, "&amp;")
310
- .replace(/</g, "&lt;")
311
- .replace(/>/g, "&gt;");
312
- try {
313
- await sendTelegramMessage(token, chatId, `⚠️ Worker <b>${safeName}</b> (thread ${threadId}) failed to start its task after ${MAX_WORKER_RESPAWNS} respawns and was decommissioned.`, { parseMode: "HTML" });
314
- }
315
- catch (err) {
316
- log.warn(`[respawn] give-up alert failed for thread ${threadId}: ${errorMessage(err)}`);
317
- }
318
- }
319
- }
320
- }
321
- else if (taskPresent && consumed) {
322
- // A single-use worker exited with content still in its mailbox — a late
323
- // append (report_progress parent-forward / cross-thread send) after the
324
- // task was already done. Do NOT re-run it; warn so the reuse attempt is
325
- // visible instead of silently duplicating work. The mailbox is deleted
326
- // by decommissionWorker below.
327
- log.warn(`[respawn] worker thread ${threadId} ("${entry.name}") exited with a non-empty mailbox after already consuming its task — NOT respawning (single-use); discarding late mailbox content.`);
328
- }
329
- workerRespawnAttempts.delete(threadId);
330
- // Worker: fully decommission (delete topic, archive notes & DB entry, remove from registry)
331
- const telegramAdapter = {
332
- deleteForumTopic: async (cId, topicId) => {
333
- if (token && cId)
334
- await deleteTelegramTopicByBotApi(token, cId, topicId);
335
- },
336
- };
337
- await decommissionWorker(entry, { db, telegram: telegramAdapter, chatId, threadLifecycle });
338
- }
339
- else {
340
- // Non-worker (e.g., keepAlive thread): mark exited so KeeperService can restart.
341
- // Clear the consumed-task signal too so the in-memory Set stays bounded to
342
- // currently-live threads (a restarted thread re-marks it on next consume).
343
- threadLifecycle.markExited(db, threadId);
344
- clearTaskConsumed(threadId);
345
- }
346
- }
808
+ await runExitBookkeeping({
809
+ entry,
810
+ db,
811
+ threadLifecycle,
812
+ exitCode,
813
+ token: process.env.TELEGRAM_TOKEN || "",
814
+ chatId: process.env.TELEGRAM_CHAT_ID || "",
815
+ }, overrides);
347
816
  }
348
817
  catch (err) {
349
818
  log.warn(`[start_thread] Failed to update DB on exit for thread ${threadId}: ${errorMessage(err)}`);
350
819
  }
351
- const uptimeSec = Math.round((Date.now() - entry.startedAt) / 1000);
352
- const exitDesc = code === 3221226505
353
- ? "ACCESS_VIOLATION (0xC0000005)"
354
- : code === 1
355
- ? "error (1)"
356
- : `code ${code}`;
357
- log.info(`[start_thread] ${processLabel} PID=${pid} thread ${threadId} exited: ${exitDesc} — uptime ${uptimeSec}s`);
358
- if (code === 3221226505) {
359
- // Detect batch crashes — count how many other threads died in the last 30s
360
- const recentCrashes = spawnedThreads.length === 0 ? "all threads down" : `${spawnedThreads.length} still alive`;
361
- log.warn(`[start_thread] SEGFAULT thread ${threadId} — ${recentCrashes}, uptime was ${uptimeSec}s (${Math.round(uptimeSec / 3600)}h)`);
362
- // Tail the thread log to see what the agent was doing when it crashed
363
- try {
364
- const fd = openSync(entry.logFile, "r");
365
- const stat = fstatSync(fd);
366
- const readSize = Math.min(2048, stat.size);
367
- const buf = Buffer.alloc(readSize);
368
- readSync(fd, buf, 0, readSize, stat.size - readSize);
369
- closeSync(fd);
370
- const tail = buf.toString("utf-8").split("\n").filter(Boolean).slice(-3).join(" | ");
371
- log.warn(`[start_thread] SEGFAULT context (last log): ${tail.substring(0, 300)}`);
372
- }
373
- catch {
374
- /* log file may be gone */
375
- }
820
+ // Only delete the PID file if it still belongs to this process — a replacement
821
+ // may have already overwritten it with its own.
822
+ if (await pidFileStillOwned(pidFilePath, pid))
823
+ await unlink(pidFilePath).catch(() => undefined);
824
+ }
825
+ /**
826
+ * True when this thread's teardown is owned by someone other than this exit
827
+ * handler, so the process that just died must be neither relaunched nor
828
+ * decommissioned here.
829
+ *
830
+ * Archived/Expired mean teardown already RAN. The operator-release marker means
831
+ * it is running RIGHT NOW: the board writes it (releaseWorkerForCard) before
832
+ * decommissionWorker kills the worker, and that kill is what fires this very
833
+ * handler. Without it a worker the operator stopped before it consumed its task
834
+ * still matches the born-dead signature exactly, so the net relaunches the work
835
+ * that was just cancelled — and decommission's post-kill liveness probe then
836
+ * sees the REPLACEMENT alive, concludes the worker survived the kill and aborts
837
+ * teardown. End state: a live worker doing cancelled work under a card that
838
+ * reads "Stopped by operator", its topic and registry row still standing.
839
+ * A live in-process decommission claim, the durable operator-release marker, and
840
+ * an Archived or Expired row each prove another path owns teardown. A persisted
841
+ * Exiting state alone does not: it can outlive an aborted decommission, leaving a
842
+ * stranded worker that this exit path must finalize.
843
+ */
844
+ function teardownOwnedElsewhere(ctx) {
845
+ const state = ctx.threadLifecycle.getThreadState(ctx.db, ctx.entry.threadId);
846
+ if (state === ThreadState.Archived || state === ThreadState.Expired) {
847
+ return true;
376
848
  }
849
+ return (isWorkerDecommissionInFlight(ctx.entry.threadId) ||
850
+ (isWorkerReleased(ctx.db, ctx.entry.threadId) && state !== ThreadState.Exiting));
377
851
  }
378
- function registerSpawnedProcess(opts, threadLifecycle) {
852
+ /**
853
+ * Tell the orchestrator its worker is gone, FROM THE EXIT PATH — the one place
854
+ * that both learns the ending at the moment it happens and knows the exit code.
855
+ *
856
+ * This is the primary emitter (plan §8.7 / increment E2). The teardown sweeps
857
+ * still call notifyWorkerDeath and are still the net for deaths nothing watched
858
+ * (a worker that outlived a server restart, a stale registry row), but they only
859
+ * run when the ~5 min cleanup walks the registry: worker 55803 died at 15:36 Z
860
+ * and its teardown notice did not fire until 17:23 Z — 1 h 48 m of an
861
+ * orchestrator waiting on a reply that had already become impossible. The two
862
+ * cooperate through the durable claim inside notifyWorkerDeath, not a second
863
+ * dedup map: whichever arrives first reports, the other finds the claim taken.
864
+ *
865
+ * An operator release is NOT filtered here, and neither is an already-taken claim.
866
+ * Both are arbitrated INSIDE the claim, which is the only authority: its return
867
+ * value decides who reports. notifyWorkerDeath does repeat that read first, as an
868
+ * explicit fast-path pre-check — the notice text now has to be BUILT before the
869
+ * claim (a better-sqlite3 transaction is synchronous and the text awaits the log
870
+ * read), so the thunk handed in here is awaited by anyone the pre-check lets
871
+ * through, not only by the claim's winner. That pre-check is an optimization and
872
+ * nothing more: it can be stale, so two racing reporters can both pass it and both
873
+ * read the same worker's log, and exactly one of them still wins the claim.
874
+ *
875
+ * The tail is offered for EVERY exit code, code 0 included. A code-0 exit looks
876
+ * like the one ending with nothing to quote, and is in fact the ending where the
877
+ * quote matters most: Claude's turn-1 MCP race (see the birth-death note atop
878
+ * this file) prints "I don't have those tools" and exits 0, a born-dead worker
879
+ * that exhausts its respawn budget reaches here with code 0 while the OPERATOR's
880
+ * give-up alert already quotes that same log, and worker 55803 — the 1 h 48 m of
881
+ * silence this increment exists for — exited 0. Since this emitter WINS the
882
+ * claim, anything it leaves out can never be added by a later path.
883
+ *
884
+ * Total by construction: a throw here would skip decommission and leak the
885
+ * worker's slot, topic and registry row, so every failure is logged and
886
+ * swallowed.
887
+ */
888
+ async function notifyWorkerExit(ctx, readFinalOutput = readFinalAgentOutput) {
889
+ try {
890
+ await notifyWorkerDeath(ctx.db, ctx.entry.threadId, endingFor("confirmed-dead", ctx.exitCode), {
891
+ exitCode: ctx.exitCode,
892
+ // Through resolveThreadLogPath, like every other reader of a dying
893
+ // process. This emitter is the worst place to skip it: it WINS the
894
+ // once-only claim, so a bare headline here is final.
895
+ readLogTail: async () => readFinalOutput((await resolveThreadLogPath(recordedThreadLogPath(ctx.entry.logFile), ctx.entry.threadId)).orElse("")),
896
+ });
897
+ }
898
+ catch (err) {
899
+ log.warn(`[exit] worker exit notice failed for thread ${ctx.entry.threadId}: ${errorMessage(err)}`);
900
+ }
901
+ }
902
+ /**
903
+ * Registry-side exit bookkeeping, once the PID file and heartbeat are gone: run
904
+ * the birth-death net, then either hand the thread to its replacement, fully
905
+ * decommission a finished worker, or mark a root exited for the keeper.
906
+ *
907
+ * Exported so the hand-off branch is testable: skip it and the exit path
908
+ * decommissions (or marks exited) the thread a freshly spawned replacement is
909
+ * already running on, deleting its mailbox out from under it.
910
+ */
911
+ export async function runExitBookkeeping(ctx, overrides = {}) {
912
+ const { entry, db, threadLifecycle } = ctx;
913
+ const threadId = entry.threadId;
914
+ if (teardownOwnedElsewhere(ctx)) {
915
+ // Teardown is already done or already under way elsewhere, so we skip both
916
+ // the net and decommissionWorker. But a worker that self-exited DURING its
917
+ // TTL grace can retain a DB deadline; clear it here so the archived thread
918
+ // is no longer reported as winding down (idempotent: decommission clears it
919
+ // at step 0).
920
+ clearWorkerGrace(db, threadId);
921
+ return;
922
+ }
923
+ // An aborted operator teardown leaves Exiting and a durable release marker.
924
+ // Finalize it on exit, but never offer that deliberate stop to the respawn net.
925
+ const operatorRelease = isWorkerReleased(db, threadId);
926
+ const outcome = operatorRelease ? "passed" : await runBirthDeathNet(ctx, overrides.net);
927
+ // A replacement process owns the thread now — its pending task file and its
928
+ // registry row must survive untouched.
929
+ if (outcome === "respawned" || outcome === "superseded")
930
+ return;
931
+ birthDeathRespawnAttempts.delete(threadId);
932
+ if (entry.threadType === "worker") {
933
+ // Tell the orchestrator FIRST, before the teardown that can take seconds
934
+ // (kill, Telegram topic delete, worktree removal) or abort outright on a
935
+ // surviving kill. Unconditional: an operator release is a teardown rather
936
+ // than a death, and the claim inside is the single place that decides so.
937
+ await notifyWorkerExit(ctx, overrides.net?.readFinalOutput);
938
+ // Worker: fully decommission (delete topic, archive notes & DB entry, remove
939
+ // from registry). Pass the REAL exit code through — the board's exit safety
940
+ // net records it on the card, distinguishing a crash from a
941
+ // clean-exit-without-report. The adapter wiring lives in the seam.
942
+ await decommissionExitedWorker(ctx, overrides.decommission);
943
+ }
944
+ else {
945
+ // Non-worker: mark exited so KeeperService can restart it. When the net gave
946
+ // up it has already cleared keepAlive, so this records the exit without
947
+ // handing the thread back to the keeper.
948
+ threadLifecycle.markExited(db, threadId);
949
+ }
950
+ }
951
+ /** Exported for the birth-death tests: registration is where a new process
952
+ * clears the session-registration signal the net later reads. */
953
+ export function registerSpawnedProcess(opts, threadLifecycle, kill = killThreadTree) {
379
954
  const pid = opts.pid;
380
955
  if (pid === undefined)
381
956
  return {
@@ -388,31 +963,84 @@ function registerSpawnedProcess(opts, threadLifecycle) {
388
963
  name: opts.name,
389
964
  configPath: opts.configPath,
390
965
  startedAt: opts.startedAt,
966
+ // This process's OWN log, so a reader that outlives this server
967
+ // generation does not have to guess which of a reused thread id's files
968
+ // was its. Always the path the process opened: the minted one on a fresh
969
+ // spawn, and on an ADOPTED one whatever adoptedLogFilePath could prove
970
+ // belongs to it — "" where it could prove nothing, which every reader
971
+ // takes as unknown (recordedThreadLogPath).
972
+ logFile: opts.logFilePath,
391
973
  ...(opts.startTimeTicks ? { startTimeTicks: opts.startTimeTicks } : {}),
392
974
  ...(opts.threadType ? { threadType: opts.threadType } : {}),
393
- }), "utf-8");
975
+ ...(opts.memorySourceThreadId !== undefined
976
+ ? { memorySourceThreadId: opts.memorySourceThreadId }
977
+ : {}),
978
+ agentLabel: opts.agentLabel,
979
+ spawnedVia: opts.spawnedVia,
980
+ }));
394
981
  }
395
982
  catch (err) {
396
- log.debug(`[start_thread] Failed to write PID file: ${errorMessage(err)}`);
983
+ // The PID file is what every restore site rebuilds this process from after a
984
+ // restart, so a process without one is not registered at all.
985
+ //
986
+ // An ADOPTED process is the exception: it was running before this call, which
987
+ // did not create it, and killing a live agent mid-task over a failed rewrite
988
+ // of its record destroys work this call never started. It is registered as
989
+ // before, loudly.
990
+ if (opts.adopted) {
991
+ log.error(`[start_thread] Failed to write PID file for ADOPTED thread ${opts.threadId} (PID=${pid}) — keeping the already-running process: ${errorMessage(err)}`);
992
+ }
993
+ else {
994
+ log.error(`[start_thread] Failed to write PID file for thread ${opts.threadId} (PID=${pid}) — killing the process this call spawned: ${errorMessage(err)}`);
995
+ // Detached: registration is synchronous by design, so the kill is not awaited.
996
+ void kill(opts.threadId, "pid-file-write-failed", pid, opts.startedAt).catch((killErr) => log.warn(`[start_thread] kill of unrecorded thread ${opts.threadId} failed: ${errorMessage(killErr)}`));
997
+ return {
998
+ error: `${opts.agentLabel} process PID=${pid} spawned but its PID file could not be written (${errorMessage(err)}); its kill has been requested.`,
999
+ };
1000
+ }
397
1001
  }
398
1002
  // Reset heartbeat so keeper doesn't treat a freshly spawned thread as stuck
399
1003
  writeThreadHeartbeatSync(opts.threadId);
1004
+ // Clear the session-registration signal so it describes THIS process: only
1005
+ // start_session (markSessionRunning) may set clean_shutdown back to 0. Without
1006
+ // the reset a thread that registered once would look registered forever and
1007
+ // the birth-death net could never see it born dead again.
1008
+ //
1009
+ // An ADOPTION registers a process that has been running all along — it passed
1010
+ // start_session before we ever met it and will never call it again. Resetting
1011
+ // there would erase that registration and make a live, healthy agent look like
1012
+ // it never started, mislabelling its eventual real death (and inviting a
1013
+ // respawn for a startup failure that never happened).
1014
+ if (opts.adopted) {
1015
+ log.debug(`[start_thread] Adopted existing PID ${pid} for thread ${opts.threadId} — keeping its session-registration signal`);
1016
+ }
1017
+ else {
1018
+ try {
1019
+ threadRepository.updateThread(opts.db ?? initMemoryDb(), opts.threadId, {
1020
+ cleanShutdown: true,
1021
+ });
1022
+ }
1023
+ catch (err) {
1024
+ log.warn(`[start_thread] Failed to reset session-registration signal for thread ${opts.threadId}: ${errorMessage(err)}`);
1025
+ }
1026
+ }
400
1027
  const entry = {
401
1028
  pid,
402
1029
  threadId: opts.threadId,
403
1030
  name: opts.name,
404
1031
  startedAt: opts.startedAt,
405
- createdAt: Date.now(),
406
1032
  logFile: opts.logFilePath,
407
1033
  ...(opts.memorySourceThreadId !== undefined
408
1034
  ? { memorySourceThreadId: opts.memorySourceThreadId }
409
1035
  : {}),
1036
+ agentLabel: opts.agentLabel,
410
1037
  ...(opts.threadType ? { threadType: opts.threadType } : {}),
411
1038
  };
412
- spawnedThreads.push(entry);
413
- opts.attachExit((code) => {
414
- handleProcessExit(code, opts.threadId, pid, pidFilePath, entry, opts.agentLabel, threadLifecycle).catch((err) => log.warn(`[exit] cleanup failed: ${err}`));
415
- });
1039
+ if (opts.attachExit) {
1040
+ opts.attachExit((code) => {
1041
+ handleProcessExit(code, pidFilePath, entry, opts.agentLabel, threadLifecycle, opts.db ?? initMemoryDb(), opts.exitBookkeeping ?? {}).catch((err) => log.warn(`[exit] cleanup failed: ${err}`));
1042
+ });
1043
+ }
416
1044
  opts.unref?.();
417
1045
  log.info(`[start_thread] Spawned ${opts.agentLabel} process PID=${pid} for thread ${opts.threadId} ("${opts.name}") via ${opts.spawnedVia}`);
418
1046
  return { pid, logFile: opts.logFilePath };
@@ -455,22 +1083,83 @@ const envToStringRecord = (env) => {
455
1083
  out[k] = v;
456
1084
  return out;
457
1085
  };
1086
+ /**
1087
+ * The log path to publish for an ADOPTED process — one the broker reports as
1088
+ * already live (`existing: true`), so it never opened the path this plan minted.
1089
+ *
1090
+ * `plan.logFilePath` must NOT be published here. While the name ended at the UTC
1091
+ * date, a same-day idempotent hit minted a path BYTE-IDENTICAL to the file the
1092
+ * live process was already appending to, so publishing it was correct and the
1093
+ * death notice got a real tail. A per-spawn marker makes that same publish name
1094
+ * a path this adoption did not open, and the tail would go empty — a regression
1095
+ * on the one path where the old scheme happened to be right.
1096
+ *
1097
+ * So the answer is the path ALREADY RECORDED for this thread id, and only when
1098
+ * the record names THIS process: its pid, and — when the broker supplied a
1099
+ * startTimeTicks — the SAME ticks in the record, an absent one included, because
1100
+ * the OS recycles pid numbers. That identity test is
1101
+ * what keeps a predecessor's path from being asserted for a successor: a PID file
1102
+ * outlives a process whose kill never confirmed (killThreadTree deliberately
1103
+ * keeps it), and the exit path asks the same question — pid AND startedAt —
1104
+ * before it unlinks a file. It is also
1105
+ * what makes `reconcileUncertainSpawn`'s adopt arms right: the process they find
1106
+ * is usually the one OUR uncertain request created, which has no PID file of its
1107
+ * own yet, so no record matches and the empty answer below sends the reader to
1108
+ * the fallback — which picks the newest log for the id. That is the file such a
1109
+ * process is MOST LIKELY writing, not provably the one: mtime orders writes, and
1110
+ * nothing here ties a file to a process. The identity test costs the SAME answer
1111
+ * on a Windows launcher fork: the record holds the launcher pid the broker
1112
+ * reported at spawn, a later idempotent hit reports the surviving forked agent,
1113
+ * the two differ, and the fallback is left to pick for that agent too.
1114
+ *
1115
+ * Empty means "unknown", never "this path": a record that names a file nothing
1116
+ * opens cannot be recovered by any reader, while an empty one is what makes
1117
+ * the exit path's and `readWorkerLastWords`' explicit fallbacks reachable.
1118
+ */
1119
+ function adoptedLogFilePath(threadId, pid, startTimeTicks) {
1120
+ try {
1121
+ const parsed = JSON.parse(readFileSync(join(PROCESS_PIDS_DIR, `${threadId}.pid`), "utf-8"));
1122
+ if (parsed.pid !== pid)
1123
+ return "";
1124
+ // A pid alone is not an identity on Windows: the OS reuses the number, and
1125
+ // this record outlives its process whenever a kill went unconfirmed. So when
1126
+ // the CALLER knows its process's start time, the record must carry the same
1127
+ // one — an ABSENT one does not match either, because `launchLocalChild`
1128
+ // writes a log path with no ticks at all, and that tickless record is exactly
1129
+ // what a recycled pid would otherwise inherit. The alternative to rejecting
1130
+ // it is quoting another process's words with full confidence, which is worse
1131
+ // than the same-id guess the empty answer falls back to.
1132
+ //
1133
+ // Precision is not the weak term here: .NET ticks round to ~128 (12.8 µs) as
1134
+ // JS numbers at these magnitudes, so evading this check would need two starts
1135
+ // on one recycled pid inside that window.
1136
+ if (startTimeTicks !== undefined && parsed.startTimeTicks !== startTimeTicks)
1137
+ return "";
1138
+ return typeof parsed.logFile === "string" ? parsed.logFile : "";
1139
+ }
1140
+ catch {
1141
+ return ""; // no PID file, or unreadable — nothing is recorded
1142
+ }
1143
+ }
458
1144
  /** Register a broker-owned process (fresh spawn, idempotent hit, or a reconcile
459
- * adoption): PID file, spawnedThreads[], and the polling exit watcher. */
1145
+ * adoption): PID file and the polling exit watcher.
1146
+ * `proc.existing` is the broker's own idempotency answer — true means this
1147
+ * process was already live, so the registration adopts rather than spawns, and
1148
+ * the plan's freshly minted log path was never opened for it
1149
+ * ({@link adoptedLogFilePath}). */
460
1150
  function registerBrokerOwnedProcess(plan, proc, threadLifecycle) {
1151
+ const adopted = proc.existing === true;
461
1152
  return registerSpawnedProcess({
462
1153
  pid: proc.pid,
463
1154
  startedAt: proc.startTimeMs,
464
1155
  startTimeTicks: proc.startTimeTicks || undefined,
465
1156
  spawnedVia: "broker",
466
- attachExit: (onExit) => watchBrokerSpawnExit({
467
- pid: proc.pid,
468
- threadId: plan.threadId,
469
- onExit,
470
- }),
1157
+ adopted,
471
1158
  threadId: plan.threadId,
472
1159
  name: plan.name,
473
- logFilePath: plan.logFilePath,
1160
+ logFilePath: adopted
1161
+ ? adoptedLogFilePath(plan.threadId, proc.pid, proc.startTimeTicks || undefined)
1162
+ : plan.logFilePath,
474
1163
  configPath: plan.configPath,
475
1164
  agentLabel: plan.agentLabel,
476
1165
  memorySourceThreadId: plan.memorySourceThreadId,
@@ -510,7 +1199,14 @@ async function reconcileUncertainSpawn(plan, spec, threadLifecycle, firstDetail)
510
1199
  const root = list.processes[0];
511
1200
  if (root.startTimeTicks || root.startTimeMs) {
512
1201
  log.warn(`[spawn] reconcile attempt ${attempt}: broker has live pid ${root.pid} for thread ${plan.threadId} — adopting it as the agent (the uncertain spawn DID land)`);
513
- return registerBrokerOwnedProcess(plan, { pid: root.pid, startTimeTicks: root.startTimeTicks, startTimeMs: root.startTimeMs }, threadLifecycle);
1202
+ return registerBrokerOwnedProcess(plan, {
1203
+ pid: root.pid,
1204
+ startTimeTicks: root.startTimeTicks,
1205
+ startTimeMs: root.startTimeMs,
1206
+ // The registry listed it as already live: this is an adoption, not
1207
+ // a birth, whatever the uncertain spawn did.
1208
+ existing: true,
1209
+ }, threadLifecycle);
514
1210
  }
515
1211
  // Entry without identity: the pid vanished between the broker's job read
516
1212
  // and its snapshot — likely mid-death. Let the next attempt see clearly.
@@ -657,7 +1353,7 @@ function launchLocalChild(plan, threadLifecycle) {
657
1353
  pid: child.pid,
658
1354
  startedAt: Date.now(),
659
1355
  spawnedVia: "local",
660
- attachExit: (onExit) => child.on("exit", (code) => onExit(code)),
1356
+ attachExit: (onExit) => child.on("exit", (code) => onExit(Optional.fromNullable(code))),
661
1357
  unref: () => child.unref(),
662
1358
  threadId: plan.threadId,
663
1359
  name: plan.name,