pi-braid 0.0.0-stage → 0.40.1

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 (1011) hide show
  1. package/AGENTS.md +195 -0
  2. package/CONTRIBUTING.md +302 -0
  3. package/LICENSE +21 -0
  4. package/README.md +266 -2
  5. package/TOOLS.md +147 -0
  6. package/dist/extensions/cognitive/mars-reflector/index.d.ts +82 -0
  7. package/dist/extensions/cognitive/mars-reflector/index.js +327 -0
  8. package/dist/extensions/cognitive/metacognition/handlers/claim-verification.d.ts +23 -0
  9. package/dist/extensions/cognitive/metacognition/handlers/claim-verification.js +233 -0
  10. package/dist/extensions/cognitive/metacognition/handlers/finalize.d.ts +27 -0
  11. package/dist/extensions/cognitive/metacognition/handlers/finalize.js +557 -0
  12. package/dist/extensions/cognitive/metacognition/handlers/hypothesize.d.ts +19 -0
  13. package/dist/extensions/cognitive/metacognition/handlers/hypothesize.js +291 -0
  14. package/dist/extensions/cognitive/metacognition/handlers/scoring.d.ts +28 -0
  15. package/dist/extensions/cognitive/metacognition/handlers/scoring.js +173 -0
  16. package/dist/extensions/cognitive/metacognition/handlers/think-budget.d.ts +85 -0
  17. package/dist/extensions/cognitive/metacognition/handlers/think-budget.js +164 -0
  18. package/dist/extensions/cognitive/metacognition/handlers/think.d.ts +27 -0
  19. package/dist/extensions/cognitive/metacognition/handlers/think.js +374 -0
  20. package/dist/extensions/cognitive/metacognition/handlers/verify.d.ts +53 -0
  21. package/dist/extensions/cognitive/metacognition/handlers/verify.js +321 -0
  22. package/dist/extensions/cognitive/metacognition/index.d.ts +10 -0
  23. package/dist/extensions/cognitive/metacognition/index.js +90 -0
  24. package/dist/extensions/cognitive/reasoning/index.d.ts +43 -0
  25. package/dist/extensions/cognitive/reasoning/index.js +99 -0
  26. package/dist/extensions/cognitive/sycophancy-detector/index.d.ts +16 -0
  27. package/dist/extensions/cognitive/sycophancy-detector/index.js +203 -0
  28. package/dist/extensions/cognitive/topic-drift/index.d.ts +51 -0
  29. package/dist/extensions/cognitive/topic-drift/index.js +346 -0
  30. package/dist/extensions/cognitive/turn-outcome/index.d.ts +35 -0
  31. package/dist/extensions/cognitive/turn-outcome/index.js +163 -0
  32. package/dist/extensions/context-management/index.d.ts +77 -0
  33. package/dist/extensions/context-management/index.js +339 -0
  34. package/dist/extensions/core/agent-environment/index.d.ts +30 -0
  35. package/dist/extensions/core/agent-environment/index.js +89 -0
  36. package/dist/extensions/core/polyfill/index.d.ts +28 -0
  37. package/dist/extensions/core/polyfill/index.js +474 -0
  38. package/dist/extensions/core/prompt-builder/awareness-whisper.d.ts +74 -0
  39. package/dist/extensions/core/prompt-builder/awareness-whisper.js +116 -0
  40. package/dist/extensions/core/prompt-builder/context-section.d.ts +41 -0
  41. package/dist/extensions/core/prompt-builder/context-section.js +101 -0
  42. package/dist/extensions/core/prompt-builder/custom-sections.d.ts +21 -0
  43. package/dist/extensions/core/prompt-builder/custom-sections.js +11 -0
  44. package/dist/extensions/core/prompt-builder/external-tool-guidelines.d.ts +23 -0
  45. package/dist/extensions/core/prompt-builder/external-tool-guidelines.js +37 -0
  46. package/dist/extensions/core/prompt-builder/identity.d.ts +33 -0
  47. package/dist/extensions/core/prompt-builder/identity.js +77 -0
  48. package/dist/extensions/core/prompt-builder/index.d.ts +33 -0
  49. package/dist/extensions/core/prompt-builder/index.js +496 -0
  50. package/dist/extensions/core/prompt-builder/inspect.d.ts +58 -0
  51. package/dist/extensions/core/prompt-builder/inspect.js +182 -0
  52. package/dist/extensions/core/prompt-builder/instance-composition.d.ts +101 -0
  53. package/dist/extensions/core/prompt-builder/instance-composition.js +416 -0
  54. package/dist/extensions/core/prompt-builder/memory-section.d.ts +20 -0
  55. package/dist/extensions/core/prompt-builder/memory-section.js +60 -0
  56. package/dist/extensions/core/prompt-builder/pi-reference-section.d.ts +17 -0
  57. package/dist/extensions/core/prompt-builder/pi-reference-section.js +11 -0
  58. package/dist/extensions/core/prompt-builder/project-docs-section.d.ts +42 -0
  59. package/dist/extensions/core/prompt-builder/project-docs-section.js +72 -0
  60. package/dist/extensions/core/prompt-builder/section-parity.d.ts +36 -0
  61. package/dist/extensions/core/prompt-builder/section-parity.js +66 -0
  62. package/dist/extensions/core/prompt-builder/section-publish.d.ts +30 -0
  63. package/dist/extensions/core/prompt-builder/section-publish.js +16 -0
  64. package/dist/extensions/core/prompt-builder/section.d.ts +75 -0
  65. package/dist/extensions/core/prompt-builder/section.js +127 -0
  66. package/dist/extensions/core/prompt-builder/surface-discipline-section.d.ts +18 -0
  67. package/dist/extensions/core/prompt-builder/surface-discipline-section.js +20 -0
  68. package/dist/extensions/core/prompt-builder/system-info-tool.d.ts +27 -0
  69. package/dist/extensions/core/prompt-builder/system-info-tool.js +67 -0
  70. package/dist/extensions/core/prompt-builder/tool-description-trim.d.ts +56 -0
  71. package/dist/extensions/core/prompt-builder/tool-description-trim.js +129 -0
  72. package/dist/extensions/core/prompt-builder/tool-guidelines.d.ts +80 -0
  73. package/dist/extensions/core/prompt-builder/tool-guidelines.js +179 -0
  74. package/dist/extensions/core/prompt-builder/tool-pipelines.d.ts +50 -0
  75. package/dist/extensions/core/prompt-builder/tool-pipelines.js +69 -0
  76. package/dist/extensions/core/prompt-builder/top-level-extensions.d.ts +44 -0
  77. package/dist/extensions/core/prompt-builder/top-level-extensions.js +300 -0
  78. package/dist/extensions/core/skills-tool/auto-inject.d.ts +333 -0
  79. package/dist/extensions/core/skills-tool/auto-inject.js +817 -0
  80. package/dist/extensions/core/skills-tool/index.d.ts +56 -0
  81. package/dist/extensions/core/skills-tool/index.js +200 -0
  82. package/dist/extensions/core/skills-tool/loading-guidance.d.ts +50 -0
  83. package/dist/extensions/core/skills-tool/loading-guidance.js +87 -0
  84. package/dist/extensions/core/skills-tool/session-records.d.ts +114 -0
  85. package/dist/extensions/core/skills-tool/session-records.js +268 -0
  86. package/dist/extensions/core/skills-tool/skill-triggers.d.ts +48 -0
  87. package/dist/extensions/core/skills-tool/skill-triggers.js +113 -0
  88. package/dist/extensions/enforcement/detection/malformed.d.ts +9 -0
  89. package/dist/extensions/enforcement/detection/malformed.js +30 -0
  90. package/dist/extensions/enforcement/detection/verification.d.ts +10 -0
  91. package/dist/extensions/enforcement/detection/verification.js +34 -0
  92. package/dist/extensions/enforcement/enforcement-types.d.ts +33 -0
  93. package/dist/extensions/enforcement/enforcement-types.js +24 -0
  94. package/dist/extensions/enforcement/handler-registry.d.ts +12 -0
  95. package/dist/extensions/enforcement/handler-registry.js +196 -0
  96. package/dist/extensions/enforcement/handlers/analysis/bpe-handler.d.ts +10 -0
  97. package/dist/extensions/enforcement/handlers/analysis/bpe-handler.js +37 -0
  98. package/dist/extensions/enforcement/handlers/analysis/dreamer-handler.d.ts +6 -0
  99. package/dist/extensions/enforcement/handlers/analysis/dreamer-handler.js +60 -0
  100. package/dist/extensions/enforcement/handlers/analysis/drift-handler.d.ts +6 -0
  101. package/dist/extensions/enforcement/handlers/analysis/drift-handler.js +75 -0
  102. package/dist/extensions/enforcement/handlers/analysis/feedback-handler.d.ts +6 -0
  103. package/dist/extensions/enforcement/handlers/analysis/feedback-handler.js +19 -0
  104. package/dist/extensions/enforcement/handlers/analysis/mars-handler.d.ts +14 -0
  105. package/dist/extensions/enforcement/handlers/analysis/mars-handler.js +99 -0
  106. package/dist/extensions/enforcement/handlers/analysis/reflection-handler.d.ts +6 -0
  107. package/dist/extensions/enforcement/handlers/analysis/reflection-handler.js +16 -0
  108. package/dist/extensions/enforcement/handlers/blocking.d.ts +16 -0
  109. package/dist/extensions/enforcement/handlers/blocking.js +33 -0
  110. package/dist/extensions/enforcement/handlers/message-analysis.d.ts +25 -0
  111. package/dist/extensions/enforcement/handlers/message-analysis.js +70 -0
  112. package/dist/extensions/enforcement/handlers/orphan-chains.d.ts +14 -0
  113. package/dist/extensions/enforcement/handlers/orphan-chains.js +44 -0
  114. package/dist/extensions/enforcement/handlers/over-correction-gate.d.ts +73 -0
  115. package/dist/extensions/enforcement/handlers/over-correction-gate.js +565 -0
  116. package/dist/extensions/enforcement/handlers/probe-handler.d.ts +31 -0
  117. package/dist/extensions/enforcement/handlers/probe-handler.js +111 -0
  118. package/dist/extensions/enforcement/handlers/register-adherence-meter.d.ts +52 -0
  119. package/dist/extensions/enforcement/handlers/register-adherence-meter.js +158 -0
  120. package/dist/extensions/enforcement/handlers/register-agent-end-api-error.d.ts +3 -0
  121. package/dist/extensions/enforcement/handlers/register-agent-end-api-error.js +69 -0
  122. package/dist/extensions/enforcement/handlers/register-input-handler.d.ts +10 -0
  123. package/dist/extensions/enforcement/handlers/register-input-handler.js +35 -0
  124. package/dist/extensions/enforcement/handlers/register-message-end.d.ts +6 -0
  125. package/dist/extensions/enforcement/handlers/register-message-end.js +388 -0
  126. package/dist/extensions/enforcement/handlers/register-post-cycle-hygiene.d.ts +25 -0
  127. package/dist/extensions/enforcement/handlers/register-post-cycle-hygiene.js +143 -0
  128. package/dist/extensions/enforcement/handlers/register-session-compact.d.ts +50 -0
  129. package/dist/extensions/enforcement/handlers/register-session-compact.js +207 -0
  130. package/dist/extensions/enforcement/handlers/register-session-shutdown-resumption.d.ts +21 -0
  131. package/dist/extensions/enforcement/handlers/register-session-shutdown-resumption.js +116 -0
  132. package/dist/extensions/enforcement/handlers/register-session-shutdown.d.ts +6 -0
  133. package/dist/extensions/enforcement/handlers/register-session-shutdown.js +38 -0
  134. package/dist/extensions/enforcement/handlers/register-session-start-discoverability.d.ts +34 -0
  135. package/dist/extensions/enforcement/handlers/register-session-start-discoverability.js +240 -0
  136. package/dist/extensions/enforcement/handlers/register-session-start.d.ts +16 -0
  137. package/dist/extensions/enforcement/handlers/register-session-start.js +198 -0
  138. package/dist/extensions/enforcement/handlers/register-tool-call.d.ts +6 -0
  139. package/dist/extensions/enforcement/handlers/register-tool-call.js +132 -0
  140. package/dist/extensions/enforcement/handlers/register-tool-result-formatting.d.ts +18 -0
  141. package/dist/extensions/enforcement/handlers/register-tool-result-formatting.js +56 -0
  142. package/dist/extensions/enforcement/handlers/register-tool-result.d.ts +6 -0
  143. package/dist/extensions/enforcement/handlers/register-tool-result.js +91 -0
  144. package/dist/extensions/enforcement/handlers/register-turn-end-hygiene.d.ts +35 -0
  145. package/dist/extensions/enforcement/handlers/register-turn-end-hygiene.js +385 -0
  146. package/dist/extensions/enforcement/handlers/routing-handler.d.ts +42 -0
  147. package/dist/extensions/enforcement/handlers/routing-handler.js +135 -0
  148. package/dist/extensions/enforcement/handlers/tool-tracker.d.ts +9 -0
  149. package/dist/extensions/enforcement/handlers/tool-tracker.js +122 -0
  150. package/dist/extensions/enforcement/handlers/turn-analysis.d.ts +41 -0
  151. package/dist/extensions/enforcement/handlers/turn-analysis.js +109 -0
  152. package/dist/extensions/enforcement/handlers/turn-end-handler.d.ts +9 -0
  153. package/dist/extensions/enforcement/handlers/turn-end-handler.js +451 -0
  154. package/dist/extensions/enforcement/index.d.ts +15 -0
  155. package/dist/extensions/enforcement/index.js +22 -0
  156. package/dist/extensions/enforcement/judge-utils.d.ts +73 -0
  157. package/dist/extensions/enforcement/judge-utils.js +83 -0
  158. package/dist/extensions/enforcement/nudge-manager.d.ts +106 -0
  159. package/dist/extensions/enforcement/nudge-manager.js +203 -0
  160. package/dist/extensions/enforcement/self-state-claims.d.ts +79 -0
  161. package/dist/extensions/enforcement/self-state-claims.js +167 -0
  162. package/dist/extensions/enforcement/session-health.d.ts +107 -0
  163. package/dist/extensions/enforcement/session-health.js +251 -0
  164. package/dist/extensions/enforcement/signals.d.ts +54 -0
  165. package/dist/extensions/enforcement/signals.js +47 -0
  166. package/dist/extensions/enforcement/similarity.d.ts +16 -0
  167. package/dist/extensions/enforcement/similarity.js +64 -0
  168. package/dist/extensions/enforcement/state.d.ts +40 -0
  169. package/dist/extensions/enforcement/state.js +74 -0
  170. package/dist/extensions/enforcement/substate/context-hygiene-state.d.ts +88 -0
  171. package/dist/extensions/enforcement/substate/context-hygiene-state.js +119 -0
  172. package/dist/extensions/enforcement/substate/error-tracking-state.d.ts +20 -0
  173. package/dist/extensions/enforcement/substate/error-tracking-state.js +37 -0
  174. package/dist/extensions/enforcement/substate/memory-hygiene-state.d.ts +24 -0
  175. package/dist/extensions/enforcement/substate/memory-hygiene-state.js +37 -0
  176. package/dist/extensions/enforcement/substate/session-state.d.ts +34 -0
  177. package/dist/extensions/enforcement/substate/session-state.js +45 -0
  178. package/dist/extensions/enforcement/substate/thought-chain-state.d.ts +23 -0
  179. package/dist/extensions/enforcement/substate/thought-chain-state.js +43 -0
  180. package/dist/extensions/enforcement/substate/tool-tracking-state.d.ts +71 -0
  181. package/dist/extensions/enforcement/substate/tool-tracking-state.js +99 -0
  182. package/dist/extensions/enforcement/substate/verification-judge-state.d.ts +17 -0
  183. package/dist/extensions/enforcement/substate/verification-judge-state.js +39 -0
  184. package/dist/extensions/enforcement/task-evidence.d.ts +108 -0
  185. package/dist/extensions/enforcement/task-evidence.js +335 -0
  186. package/dist/extensions/enforcement/types.d.ts +35 -0
  187. package/dist/extensions/enforcement/types.js +5 -0
  188. package/dist/extensions/enforcement/validation.d.ts +12 -0
  189. package/dist/extensions/enforcement/validation.js +151 -0
  190. package/dist/extensions/enforcement/verification-judge.d.ts +110 -0
  191. package/dist/extensions/enforcement/verification-judge.js +214 -0
  192. package/dist/extensions/enforcement/whisper.d.ts +46 -0
  193. package/dist/extensions/enforcement/whisper.js +104 -0
  194. package/dist/extensions/heartbeat/analytics/ab-variant.d.ts +19 -0
  195. package/dist/extensions/heartbeat/analytics/ab-variant.js +86 -0
  196. package/dist/extensions/heartbeat/analytics/core.d.ts +12 -0
  197. package/dist/extensions/heartbeat/analytics/core.js +201 -0
  198. package/dist/extensions/heartbeat/analytics/format.d.ts +7 -0
  199. package/dist/extensions/heartbeat/analytics/format.js +111 -0
  200. package/dist/extensions/heartbeat/analytics/index.d.ts +14 -0
  201. package/dist/extensions/heartbeat/analytics/index.js +352 -0
  202. package/dist/extensions/heartbeat/analytics/shared.d.ts +85 -0
  203. package/dist/extensions/heartbeat/analytics/shared.js +69 -0
  204. package/dist/extensions/heartbeat/heartbeat-scheduler/index.d.ts +31 -0
  205. package/dist/extensions/heartbeat/heartbeat-scheduler/index.js +881 -0
  206. package/dist/extensions/heartbeat/heartbeat-scheduler/meta-learning.d.ts +10 -0
  207. package/dist/extensions/heartbeat/heartbeat-scheduler/meta-learning.js +49 -0
  208. package/dist/extensions/heartbeat/heartbeat-scheduler/modules/behavioral-drift.d.ts +17 -0
  209. package/dist/extensions/heartbeat/heartbeat-scheduler/modules/behavioral-drift.js +161 -0
  210. package/dist/extensions/heartbeat/heartbeat-scheduler/modules/budget.d.ts +13 -0
  211. package/dist/extensions/heartbeat/heartbeat-scheduler/modules/budget.js +101 -0
  212. package/dist/extensions/heartbeat/heartbeat-scheduler/modules/context-hygiene.d.ts +10 -0
  213. package/dist/extensions/heartbeat/heartbeat-scheduler/modules/context-hygiene.js +221 -0
  214. package/dist/extensions/heartbeat/heartbeat-scheduler/modules/evolver.d.ts +9 -0
  215. package/dist/extensions/heartbeat/heartbeat-scheduler/modules/evolver.js +65 -0
  216. package/dist/extensions/heartbeat/heartbeat-scheduler/modules/measurement.d.ts +8 -0
  217. package/dist/extensions/heartbeat/heartbeat-scheduler/modules/measurement.js +32 -0
  218. package/dist/extensions/heartbeat/heartbeat-scheduler/modules/recaller.d.ts +9 -0
  219. package/dist/extensions/heartbeat/heartbeat-scheduler/modules/recaller.js +75 -0
  220. package/dist/extensions/heartbeat/heartbeat-scheduler/modules/reflection-consolidator.d.ts +9 -0
  221. package/dist/extensions/heartbeat/heartbeat-scheduler/modules/reflection-consolidator.js +98 -0
  222. package/dist/extensions/heartbeat/heartbeat-scheduler/policies.d.ts +14 -0
  223. package/dist/extensions/heartbeat/heartbeat-scheduler/policies.js +149 -0
  224. package/dist/extensions/heartbeat/heartbeat-scheduler/state.d.ts +22 -0
  225. package/dist/extensions/heartbeat/heartbeat-scheduler/state.js +82 -0
  226. package/dist/extensions/heartbeat/heartbeat-scheduler/types.d.ts +124 -0
  227. package/dist/extensions/heartbeat/heartbeat-scheduler/types.js +7 -0
  228. package/dist/extensions/heartbeat/heartbeat-scheduler/whisper-batcher.d.ts +52 -0
  229. package/dist/extensions/heartbeat/heartbeat-scheduler/whisper-batcher.js +83 -0
  230. package/dist/extensions/manifest.d.ts +32 -0
  231. package/dist/extensions/manifest.js +251 -0
  232. package/dist/extensions/memory/context-lifecycle/helpers.d.ts +55 -0
  233. package/dist/extensions/memory/context-lifecycle/helpers.js +142 -0
  234. package/dist/extensions/memory/context-lifecycle/index.d.ts +17 -0
  235. package/dist/extensions/memory/context-lifecycle/index.js +977 -0
  236. package/dist/extensions/memory/context-lifecycle/policy-engine.d.ts +50 -0
  237. package/dist/extensions/memory/context-lifecycle/policy-engine.js +196 -0
  238. package/dist/extensions/memory/context-lifecycle/signal-detector.d.ts +28 -0
  239. package/dist/extensions/memory/context-lifecycle/signal-detector.js +224 -0
  240. package/dist/extensions/memory/context-lifecycle/state.d.ts +98 -0
  241. package/dist/extensions/memory/context-lifecycle/state.js +90 -0
  242. package/dist/extensions/memory/context-lifecycle/types.d.ts +132 -0
  243. package/dist/extensions/memory/context-lifecycle/types.js +273 -0
  244. package/dist/extensions/memory/context-manager/analysis.d.ts +47 -0
  245. package/dist/extensions/memory/context-manager/analysis.js +264 -0
  246. package/dist/extensions/memory/context-manager/handlers/compaction-chunked.d.ts +159 -0
  247. package/dist/extensions/memory/context-manager/handlers/compaction-chunked.js +658 -0
  248. package/dist/extensions/memory/context-manager/handlers/compaction-retry.d.ts +29 -0
  249. package/dist/extensions/memory/context-manager/handlers/compaction-retry.js +410 -0
  250. package/dist/extensions/memory/context-manager/handlers/compaction-trace.d.ts +74 -0
  251. package/dist/extensions/memory/context-manager/handlers/compaction-trace.js +180 -0
  252. package/dist/extensions/memory/context-manager/handlers/compaction-watchdog.d.ts +69 -0
  253. package/dist/extensions/memory/context-manager/handlers/compaction-watchdog.js +297 -0
  254. package/dist/extensions/memory/context-manager/handlers/compaction.d.ts +37 -0
  255. package/dist/extensions/memory/context-manager/handlers/compaction.js +2150 -0
  256. package/dist/extensions/memory/context-manager/handlers/context-emergency.d.ts +124 -0
  257. package/dist/extensions/memory/context-manager/handlers/context-emergency.js +364 -0
  258. package/dist/extensions/memory/context-manager/handlers/events.d.ts +5 -0
  259. package/dist/extensions/memory/context-manager/handlers/events.js +314 -0
  260. package/dist/extensions/memory/context-manager/handlers/navigation.d.ts +5 -0
  261. package/dist/extensions/memory/context-manager/handlers/navigation.js +86 -0
  262. package/dist/extensions/memory/context-manager/handlers/offload.d.ts +94 -0
  263. package/dist/extensions/memory/context-manager/handlers/offload.js +248 -0
  264. package/dist/extensions/memory/context-manager/handlers/rotation.d.ts +6 -0
  265. package/dist/extensions/memory/context-manager/handlers/rotation.js +304 -0
  266. package/dist/extensions/memory/context-manager/handlers/shared.d.ts +410 -0
  267. package/dist/extensions/memory/context-manager/handlers/shared.js +579 -0
  268. package/dist/extensions/memory/context-manager/handlers/tool-batch-boundary.d.ts +55 -0
  269. package/dist/extensions/memory/context-manager/handlers/tool-batch-boundary.js +190 -0
  270. package/dist/extensions/memory/context-manager/handlers/toolresult-capture-cap.d.ts +21 -0
  271. package/dist/extensions/memory/context-manager/handlers/toolresult-capture-cap.js +155 -0
  272. package/dist/extensions/memory/context-manager/handlers/tools/context-compress.d.ts +90 -0
  273. package/dist/extensions/memory/context-manager/handlers/tools/context-compress.js +1156 -0
  274. package/dist/extensions/memory/context-manager/handlers/tools/context-inspect.d.ts +16 -0
  275. package/dist/extensions/memory/context-manager/handlers/tools/context-inspect.js +276 -0
  276. package/dist/extensions/memory/context-manager/handlers/tools/context-navigate.d.ts +19 -0
  277. package/dist/extensions/memory/context-manager/handlers/tools/context-navigate.js +378 -0
  278. package/dist/extensions/memory/context-manager/handlers/tools/offload-recover.d.ts +13 -0
  279. package/dist/extensions/memory/context-manager/handlers/tools/offload-recover.js +181 -0
  280. package/dist/extensions/memory/context-manager/index.d.ts +3 -0
  281. package/dist/extensions/memory/context-manager/index.js +88 -0
  282. package/dist/extensions/memory/context-manager/pruning.d.ts +47 -0
  283. package/dist/extensions/memory/context-manager/pruning.js +406 -0
  284. package/dist/extensions/memory/context-manager/semantic-compress.d.ts +71 -0
  285. package/dist/extensions/memory/context-manager/semantic-compress.js +279 -0
  286. package/dist/extensions/memory/memory-agent-bridge/conflict-qa-tool.d.ts +20 -0
  287. package/dist/extensions/memory/memory-agent-bridge/conflict-qa-tool.js +71 -0
  288. package/dist/extensions/memory/memory-agent-bridge/explore-paths.d.ts +30 -0
  289. package/dist/extensions/memory/memory-agent-bridge/explore-paths.js +231 -0
  290. package/dist/extensions/memory/memory-agent-bridge/index.d.ts +28 -0
  291. package/dist/extensions/memory/memory-agent-bridge/index.js +124 -0
  292. package/dist/extensions/memory/memory-agent-bridge/memory-store-tool.d.ts +21 -0
  293. package/dist/extensions/memory/memory-agent-bridge/memory-store-tool.js +194 -0
  294. package/dist/extensions/memory/memory-agent-bridge/memory-tool.d.ts +22 -0
  295. package/dist/extensions/memory/memory-agent-bridge/memory-tool.js +548 -0
  296. package/dist/extensions/memory/scratchpad/format.d.ts +19 -0
  297. package/dist/extensions/memory/scratchpad/format.js +135 -0
  298. package/dist/extensions/memory/scratchpad/handlers.d.ts +53 -0
  299. package/dist/extensions/memory/scratchpad/handlers.js +469 -0
  300. package/dist/extensions/memory/scratchpad/index.d.ts +17 -0
  301. package/dist/extensions/memory/scratchpad/index.js +168 -0
  302. package/dist/extensions/memory/scratchpad/persistence.d.ts +46 -0
  303. package/dist/extensions/memory/scratchpad/persistence.js +343 -0
  304. package/dist/extensions/memory/scratchpad/types.d.ts +124 -0
  305. package/dist/extensions/memory/scratchpad/types.js +8 -0
  306. package/dist/extensions/memory/scratchpad/utils.d.ts +76 -0
  307. package/dist/extensions/memory/scratchpad/utils.js +236 -0
  308. package/dist/extensions/memory/session-recall/analyze.d.ts +58 -0
  309. package/dist/extensions/memory/session-recall/analyze.js +478 -0
  310. package/dist/extensions/memory/session-recall/context-aggregate.d.ts +117 -0
  311. package/dist/extensions/memory/session-recall/context-aggregate.js +315 -0
  312. package/dist/extensions/memory/session-recall/index.d.ts +29 -0
  313. package/dist/extensions/memory/session-recall/index.js +820 -0
  314. package/dist/extensions/memory/session-recall/query.d.ts +15 -0
  315. package/dist/extensions/memory/session-recall/query.js +38 -0
  316. package/dist/extensions/memory/session-recall/rank.d.ts +71 -0
  317. package/dist/extensions/memory/session-recall/rank.js +85 -0
  318. package/dist/extensions/memory/session-recall/search.d.ts +159 -0
  319. package/dist/extensions/memory/session-recall/search.js +682 -0
  320. package/dist/extensions/memory/session-recall/stats.d.ts +34 -0
  321. package/dist/extensions/memory/session-recall/stats.js +67 -0
  322. package/dist/extensions/memory/session-recall/text-utils.d.ts +82 -0
  323. package/dist/extensions/memory/session-recall/text-utils.js +184 -0
  324. package/dist/extensions/memory/three-memory-stores/episodes-disk.d.ts +43 -0
  325. package/dist/extensions/memory/three-memory-stores/episodes-disk.js +125 -0
  326. package/dist/extensions/memory/three-memory-stores/episodes.d.ts +46 -0
  327. package/dist/extensions/memory/three-memory-stores/episodes.js +299 -0
  328. package/dist/extensions/memory/three-memory-stores/handlers/whisper-recall.d.ts +25 -0
  329. package/dist/extensions/memory/three-memory-stores/handlers/whisper-recall.js +112 -0
  330. package/dist/extensions/memory/three-memory-stores/heuristics.d.ts +19 -0
  331. package/dist/extensions/memory/three-memory-stores/heuristics.js +89 -0
  332. package/dist/extensions/memory/three-memory-stores/index.d.ts +34 -0
  333. package/dist/extensions/memory/three-memory-stores/index.js +436 -0
  334. package/dist/extensions/memory/three-memory-stores/tool-reliability.d.ts +11 -0
  335. package/dist/extensions/memory/three-memory-stores/tool-reliability.js +38 -0
  336. package/dist/extensions/memory/three-memory-stores/types.d.ts +69 -0
  337. package/dist/extensions/memory/three-memory-stores/types.js +2 -0
  338. package/dist/extensions/memory/workspace-snapshot/index.d.ts +19 -0
  339. package/dist/extensions/memory/workspace-snapshot/index.js +363 -0
  340. package/dist/extensions/orchestrator/index.d.ts +19 -0
  341. package/dist/extensions/orchestrator/index.js +796 -0
  342. package/dist/extensions/scheduling/timer/fire-timing.d.ts +25 -0
  343. package/dist/extensions/scheduling/timer/fire-timing.js +28 -0
  344. package/dist/extensions/scheduling/timer/index.d.ts +102 -0
  345. package/dist/extensions/scheduling/timer/index.js +1143 -0
  346. package/dist/extensions/scheduling/timer/poller.d.ts +52 -0
  347. package/dist/extensions/scheduling/timer/poller.js +135 -0
  348. package/dist/extensions/scheduling/timer/recovery.d.ts +145 -0
  349. package/dist/extensions/scheduling/timer/recovery.js +445 -0
  350. package/dist/extensions/scheduling/timer/store-file.d.ts +38 -0
  351. package/dist/extensions/scheduling/timer/store-file.js +59 -0
  352. package/dist/extensions/scheduling/timer/timer-manager.d.ts +21 -0
  353. package/dist/extensions/scheduling/timer/timer-manager.js +143 -0
  354. package/dist/extensions/scheduling/timer/wake-retry.d.ts +455 -0
  355. package/dist/extensions/scheduling/timer/wake-retry.js +872 -0
  356. package/dist/extensions/self/auto-recovery/index.d.ts +20 -0
  357. package/dist/extensions/self/auto-recovery/index.js +89 -0
  358. package/dist/extensions/self/error-tracking/index.d.ts +3 -0
  359. package/dist/extensions/self/error-tracking/index.js +244 -0
  360. package/dist/extensions/self/health-maintenance/format.d.ts +3 -0
  361. package/dist/extensions/self/health-maintenance/format.js +60 -0
  362. package/dist/extensions/self/health-maintenance/handlers/session-health-tool.d.ts +23 -0
  363. package/dist/extensions/self/health-maintenance/handlers/session-health-tool.js +158 -0
  364. package/dist/extensions/self/health-maintenance/helpers.d.ts +25 -0
  365. package/dist/extensions/self/health-maintenance/helpers.js +67 -0
  366. package/dist/extensions/self/health-maintenance/index.d.ts +6 -0
  367. package/dist/extensions/self/health-maintenance/index.js +238 -0
  368. package/dist/extensions/self/health-maintenance/types.d.ts +14 -0
  369. package/dist/extensions/self/health-maintenance/types.js +2 -0
  370. package/dist/extensions/self/latent-activator/index.d.ts +12 -0
  371. package/dist/extensions/self/latent-activator/index.js +173 -0
  372. package/dist/extensions/self/latent-activator/mixes.d.ts +9 -0
  373. package/dist/extensions/self/latent-activator/mixes.js +20 -0
  374. package/dist/extensions/self/latent-activator/signals.d.ts +17 -0
  375. package/dist/extensions/self/latent-activator/signals.js +228 -0
  376. package/dist/extensions/self/latent-activator/state.d.ts +43 -0
  377. package/dist/extensions/self/latent-activator/state.js +59 -0
  378. package/dist/extensions/self/latent-activator/types.d.ts +8 -0
  379. package/dist/extensions/self/latent-activator/types.js +8 -0
  380. package/dist/extensions/self/watchdog/config.d.ts +4 -0
  381. package/dist/extensions/self/watchdog/config.js +79 -0
  382. package/dist/extensions/self/watchdog/engine.d.ts +256 -0
  383. package/dist/extensions/self/watchdog/engine.js +935 -0
  384. package/dist/extensions/self/watchdog/index.d.ts +23 -0
  385. package/dist/extensions/self/watchdog/index.js +485 -0
  386. package/dist/index.d.ts +25 -0
  387. package/dist/index.js +81 -0
  388. package/dist/lib/ai/consolidated-claim-critic.d.ts +84 -0
  389. package/dist/lib/ai/consolidated-claim-critic.js +191 -0
  390. package/dist/lib/ai/cost-report.d.ts +83 -0
  391. package/dist/lib/ai/cost-report.js +116 -0
  392. package/dist/lib/ai/critic-cache.d.ts +57 -0
  393. package/dist/lib/ai/critic-cache.js +100 -0
  394. package/dist/lib/ai/critic-fallbacks.d.ts +37 -0
  395. package/dist/lib/ai/critic-fallbacks.js +75 -0
  396. package/dist/lib/ai/critic-gate.d.ts +75 -0
  397. package/dist/lib/ai/critic-gate.js +81 -0
  398. package/dist/lib/ai/critic-helpers.d.ts +26 -0
  399. package/dist/lib/ai/critic-helpers.js +131 -0
  400. package/dist/lib/ai/critic-registry.d.ts +417 -0
  401. package/dist/lib/ai/critic-registry.js +639 -0
  402. package/dist/lib/ai/critic-stats.d.ts +78 -0
  403. package/dist/lib/ai/critic-stats.js +90 -0
  404. package/dist/lib/ai/judge-budget.d.ts +138 -0
  405. package/dist/lib/ai/judge-budget.js +143 -0
  406. package/dist/lib/ai/language-hint.d.ts +21 -0
  407. package/dist/lib/ai/language-hint.js +58 -0
  408. package/dist/lib/ai/llm-call.d.ts +141 -0
  409. package/dist/lib/ai/llm-call.js +745 -0
  410. package/dist/lib/ai/model-resolver.d.ts +90 -0
  411. package/dist/lib/ai/model-resolver.js +185 -0
  412. package/dist/lib/ai/models-init.d.ts +46 -0
  413. package/dist/lib/ai/models-init.js +65 -0
  414. package/dist/lib/ai/payload-hygiene.d.ts +74 -0
  415. package/dist/lib/ai/payload-hygiene.js +240 -0
  416. package/dist/lib/ai/post-loop-classify.d.ts +128 -0
  417. package/dist/lib/ai/post-loop-classify.js +87 -0
  418. package/dist/lib/ai/text-classifier.d.ts +142 -0
  419. package/dist/lib/ai/text-classifier.js +548 -0
  420. package/dist/lib/cognitive/hints.d.ts +33 -0
  421. package/dist/lib/cognitive/hints.js +223 -0
  422. package/dist/lib/cognitive/openspec.d.ts +29 -0
  423. package/dist/lib/cognitive/openspec.js +108 -0
  424. package/dist/lib/config/braid-paths.d.ts +188 -0
  425. package/dist/lib/config/braid-paths.js +340 -0
  426. package/dist/lib/config/braid-settings.d.ts +489 -0
  427. package/dist/lib/config/braid-settings.js +938 -0
  428. package/dist/lib/config/per-tool-settings.d.ts +95 -0
  429. package/dist/lib/config/per-tool-settings.js +161 -0
  430. package/dist/lib/config/session-profiles.d.ts +68 -0
  431. package/dist/lib/config/session-profiles.js +143 -0
  432. package/dist/lib/constants/injection-details.d.ts +30 -0
  433. package/dist/lib/constants/injection-details.js +30 -0
  434. package/dist/lib/constants/session-thresholds.d.ts +42 -0
  435. package/dist/lib/constants/session-thresholds.js +54 -0
  436. package/dist/lib/constants/tool-constants.d.ts +11 -0
  437. package/dist/lib/constants/tool-constants.js +12 -0
  438. package/dist/lib/core/event-names.d.ts +23 -0
  439. package/dist/lib/core/event-names.js +26 -0
  440. package/dist/lib/core/logger.d.ts +102 -0
  441. package/dist/lib/core/logger.js +274 -0
  442. package/dist/lib/detection/compression-strategy.d.ts +38 -0
  443. package/dist/lib/detection/compression-strategy.js +147 -0
  444. package/dist/lib/detection/consolidated-topic-critic.d.ts +51 -0
  445. package/dist/lib/detection/consolidated-topic-critic.js +132 -0
  446. package/dist/lib/detection/context-density.d.ts +70 -0
  447. package/dist/lib/detection/context-density.js +193 -0
  448. package/dist/lib/detection/context-thresholds.d.ts +88 -0
  449. package/dist/lib/detection/context-thresholds.js +107 -0
  450. package/dist/lib/detection/context-tiers.d.ts +80 -0
  451. package/dist/lib/detection/context-tiers.js +144 -0
  452. package/dist/lib/detection/context-usage.d.ts +75 -0
  453. package/dist/lib/detection/context-usage.js +209 -0
  454. package/dist/lib/detection/degradation-detector.d.ts +74 -0
  455. package/dist/lib/detection/degradation-detector.js +454 -0
  456. package/dist/lib/detection/test-burst.d.ts +77 -0
  457. package/dist/lib/detection/test-burst.js +126 -0
  458. package/dist/lib/detection/tool-loop-detector.d.ts +125 -0
  459. package/dist/lib/detection/tool-loop-detector.js +302 -0
  460. package/dist/lib/detection/topic-drift-detector.d.ts +80 -0
  461. package/dist/lib/detection/topic-drift-detector.js +252 -0
  462. package/dist/lib/enforcement/adherence-meter.d.ts +240 -0
  463. package/dist/lib/enforcement/adherence-meter.js +420 -0
  464. package/dist/lib/enforcement/turn-dedup.d.ts +106 -0
  465. package/dist/lib/enforcement/turn-dedup.js +195 -0
  466. package/dist/lib/errors/llm-error.d.ts +79 -0
  467. package/dist/lib/errors/llm-error.js +241 -0
  468. package/dist/lib/events/consolidation-channel.d.ts +109 -0
  469. package/dist/lib/events/consolidation-channel.js +374 -0
  470. package/dist/lib/events/consolidation-scoring.d.ts +59 -0
  471. package/dist/lib/events/consolidation-scoring.js +95 -0
  472. package/dist/lib/events/event-bus.d.ts +123 -0
  473. package/dist/lib/events/event-bus.js +108 -0
  474. package/dist/lib/events/event-types.d.ts +39 -0
  475. package/dist/lib/events/event-types.js +30 -0
  476. package/dist/lib/events/timer-bus.d.ts +21 -0
  477. package/dist/lib/events/timer-bus.js +41 -0
  478. package/dist/lib/events/timer-types.d.ts +64 -0
  479. package/dist/lib/events/timer-types.js +8 -0
  480. package/dist/lib/events/turn-end-coordinator.d.ts +52 -0
  481. package/dist/lib/events/turn-end-coordinator.js +89 -0
  482. package/dist/lib/harness/failure-trace-collector.d.ts +31 -0
  483. package/dist/lib/harness/failure-trace-collector.js +114 -0
  484. package/dist/lib/harness/index.d.ts +20 -0
  485. package/dist/lib/harness/index.js +21 -0
  486. package/dist/lib/harness/types.d.ts +85 -0
  487. package/dist/lib/harness/types.js +20 -0
  488. package/dist/lib/harness/weakness-miner.d.ts +29 -0
  489. package/dist/lib/harness/weakness-miner.js +165 -0
  490. package/dist/lib/memory/constants.d.ts +11 -0
  491. package/dist/lib/memory/constants.js +29 -0
  492. package/dist/lib/memory/index.d.ts +147 -0
  493. package/dist/lib/memory/index.js +564 -0
  494. package/dist/lib/memory/lifecycle.d.ts +50 -0
  495. package/dist/lib/memory/lifecycle.js +139 -0
  496. package/dist/lib/memory/past-insights.d.ts +35 -0
  497. package/dist/lib/memory/past-insights.js +189 -0
  498. package/dist/lib/memory/storage.d.ts +38 -0
  499. package/dist/lib/memory/storage.js +167 -0
  500. package/dist/lib/memory/store-lock.d.ts +23 -0
  501. package/dist/lib/memory/store-lock.js +69 -0
  502. package/dist/lib/memory/store-merge.d.ts +38 -0
  503. package/dist/lib/memory/store-merge.js +73 -0
  504. package/dist/lib/memory/types.d.ts +65 -0
  505. package/dist/lib/memory/types.js +5 -0
  506. package/dist/lib/memory/utils.d.ts +35 -0
  507. package/dist/lib/memory/utils.js +156 -0
  508. package/dist/lib/memory/write-log.d.ts +85 -0
  509. package/dist/lib/memory/write-log.js +124 -0
  510. package/dist/lib/memory/write-quality.d.ts +197 -0
  511. package/dist/lib/memory/write-quality.js +314 -0
  512. package/dist/lib/orchestrator/branch.d.ts +63 -0
  513. package/dist/lib/orchestrator/branch.js +192 -0
  514. package/dist/lib/orchestrator/index.d.ts +14 -0
  515. package/dist/lib/orchestrator/index.js +11 -0
  516. package/dist/lib/orchestrator/locks.d.ts +46 -0
  517. package/dist/lib/orchestrator/locks.js +122 -0
  518. package/dist/lib/orchestrator/slop-scanner.d.ts +31 -0
  519. package/dist/lib/orchestrator/slop-scanner.js +207 -0
  520. package/dist/lib/orchestrator/workers.d.ts +453 -0
  521. package/dist/lib/orchestrator/workers.js +1001 -0
  522. package/dist/lib/public.d.ts +18 -0
  523. package/dist/lib/public.js +23 -0
  524. package/dist/lib/reasoning/advice-tracker.d.ts +51 -0
  525. package/dist/lib/reasoning/advice-tracker.js +177 -0
  526. package/dist/lib/reasoning/belief-policy-engine.d.ts +48 -0
  527. package/dist/lib/reasoning/belief-policy-engine.js +268 -0
  528. package/dist/lib/reasoning/belief-types.d.ts +32 -0
  529. package/dist/lib/reasoning/belief-types.js +8 -0
  530. package/dist/lib/reasoning/classifier-offline.d.ts +72 -0
  531. package/dist/lib/reasoning/classifier-offline.js +75 -0
  532. package/dist/lib/reasoning/dreamer.d.ts +37 -0
  533. package/dist/lib/reasoning/dreamer.js +169 -0
  534. package/dist/lib/reasoning/nudge-analytics.d.ts +18 -0
  535. package/dist/lib/reasoning/nudge-analytics.js +62 -0
  536. package/dist/lib/reasoning/policy-rules.d.ts +18 -0
  537. package/dist/lib/reasoning/policy-rules.js +153 -0
  538. package/dist/lib/reasoning/reasoning-metrics.d.ts +42 -0
  539. package/dist/lib/reasoning/reasoning-metrics.js +174 -0
  540. package/dist/lib/reasoning/reasoning-summary.d.ts +34 -0
  541. package/dist/lib/reasoning/reasoning-summary.js +122 -0
  542. package/dist/lib/reasoning/tool-usage-analyzer.d.ts +50 -0
  543. package/dist/lib/reasoning/tool-usage-analyzer.js +188 -0
  544. package/dist/lib/state/async-storage.d.ts +52 -0
  545. package/dist/lib/state/async-storage.js +171 -0
  546. package/dist/lib/state/extension-state.d.ts +184 -0
  547. package/dist/lib/state/extension-state.js +373 -0
  548. package/dist/lib/state/global-state.d.ts +358 -0
  549. package/dist/lib/state/global-state.js +741 -0
  550. package/dist/lib/state/metacognitive-state.d.ts +21 -0
  551. package/dist/lib/state/metacognitive-state.js +50 -0
  552. package/dist/lib/state/session-manager.d.ts +32 -0
  553. package/dist/lib/state/session-manager.js +11 -0
  554. package/dist/lib/state/session-start-queue.d.ts +42 -0
  555. package/dist/lib/state/session-start-queue.js +105 -0
  556. package/dist/lib/state/state-checkpoint.d.ts +72 -0
  557. package/dist/lib/state/state-checkpoint.js +252 -0
  558. package/dist/lib/state/telegram-poller-liveness.d.ts +54 -0
  559. package/dist/lib/state/telegram-poller-liveness.js +67 -0
  560. package/dist/lib/state/tool-provenance.d.ts +22 -0
  561. package/dist/lib/state/tool-provenance.js +25 -0
  562. package/dist/lib/state/workspace-snapshot.d.ts +111 -0
  563. package/dist/lib/state/workspace-snapshot.js +372 -0
  564. package/dist/lib/store/belief-store.d.ts +112 -0
  565. package/dist/lib/store/belief-store.js +252 -0
  566. package/dist/lib/store/bidirectional-verifier.d.ts +87 -0
  567. package/dist/lib/store/bidirectional-verifier.js +242 -0
  568. package/dist/lib/store/claim-tracker.d.ts +66 -0
  569. package/dist/lib/store/claim-tracker.js +276 -0
  570. package/dist/lib/store/conflict-qa.d.ts +96 -0
  571. package/dist/lib/store/conflict-qa.js +283 -0
  572. package/dist/lib/store/evidence-pool.d.ts +185 -0
  573. package/dist/lib/store/evidence-pool.js +598 -0
  574. package/dist/lib/telemetry/context-heartbeat.d.ts +122 -0
  575. package/dist/lib/telemetry/context-heartbeat.js +449 -0
  576. package/dist/lib/telemetry/drift-signals.d.ts +46 -0
  577. package/dist/lib/telemetry/drift-signals.js +75 -0
  578. package/dist/lib/telemetry/rss-telemetry.d.ts +41 -0
  579. package/dist/lib/telemetry/rss-telemetry.js +53 -0
  580. package/dist/lib/types/episode-types.d.ts +31 -0
  581. package/dist/lib/types/episode-types.js +9 -0
  582. package/dist/lib/types/standard-result.d.ts +32 -0
  583. package/dist/lib/types/standard-result.js +22 -0
  584. package/dist/lib/utils/async-fs.d.ts +17 -0
  585. package/dist/lib/utils/async-fs.js +22 -0
  586. package/dist/lib/utils/bounded.d.ts +38 -0
  587. package/dist/lib/utils/bounded.js +59 -0
  588. package/dist/lib/utils/dedup.d.ts +40 -0
  589. package/dist/lib/utils/dedup.js +43 -0
  590. package/dist/lib/utils/error-guard.d.ts +15 -0
  591. package/dist/lib/utils/error-guard.js +22 -0
  592. package/dist/lib/utils/extension-utils.d.ts +36 -0
  593. package/dist/lib/utils/extension-utils.js +65 -0
  594. package/dist/lib/utils/extract-json.d.ts +23 -0
  595. package/dist/lib/utils/extract-json.js +90 -0
  596. package/dist/lib/utils/file-mutation-queue.d.ts +33 -0
  597. package/dist/lib/utils/file-mutation-queue.js +150 -0
  598. package/dist/lib/utils/filter-safe-to-remove.d.ts +26 -0
  599. package/dist/lib/utils/filter-safe-to-remove.js +256 -0
  600. package/dist/lib/utils/format-tool-result.d.ts +47 -0
  601. package/dist/lib/utils/format-tool-result.js +88 -0
  602. package/dist/lib/utils/id.d.ts +44 -0
  603. package/dist/lib/utils/id.js +59 -0
  604. package/dist/lib/utils/injection-tracker.d.ts +317 -0
  605. package/dist/lib/utils/injection-tracker.js +840 -0
  606. package/dist/lib/utils/local-time.d.ts +57 -0
  607. package/dist/lib/utils/local-time.js +181 -0
  608. package/dist/lib/utils/memory-fence.d.ts +55 -0
  609. package/dist/lib/utils/memory-fence.js +66 -0
  610. package/dist/lib/utils/sop-extractor.d.ts +75 -0
  611. package/dist/lib/utils/sop-extractor.js +259 -0
  612. package/dist/lib/utils/sop-suggestion.d.ts +34 -0
  613. package/dist/lib/utils/sop-suggestion.js +336 -0
  614. package/dist/lib/utils/wake-gate.d.ts +151 -0
  615. package/dist/lib/utils/wake-gate.js +265 -0
  616. package/dist/lib/utils/whisper-format.d.ts +95 -0
  617. package/dist/lib/utils/whisper-format.js +115 -0
  618. package/dist/lib/verification/coordination-checker.d.ts +72 -0
  619. package/dist/lib/verification/coordination-checker.js +126 -0
  620. package/dist/loader/api.d.ts +19 -0
  621. package/dist/loader/api.js +114 -0
  622. package/dist/loader/loader.d.ts +85 -0
  623. package/dist/loader/loader.js +534 -0
  624. package/docs/BEGINNERS.md +166 -0
  625. package/docs/COMPACTION-LOSS-INVESTIGATION.md +179 -0
  626. package/docs/CONTEXT-MAP.md +220 -0
  627. package/docs/CONTEXT-POLICY.md +86 -0
  628. package/docs/HISTORY.md +110 -0
  629. package/docs/LOCAL_DEV.md +246 -0
  630. package/docs/ROADMAP.md +107 -0
  631. package/docs/SETUP.md +502 -0
  632. package/package.json +97 -4
  633. package/skills/agent-testing/SKILL.md +214 -0
  634. package/skills/braid-reference/SKILL.md +88 -0
  635. package/skills/code-refactoring/SKILL.md +211 -0
  636. package/skills/code-search/SKILL.md +14 -0
  637. package/skills/documentation/SKILL.md +89 -0
  638. package/skills/dox/AGENTS.md.template +83 -0
  639. package/skills/dox/SKILL.md +86 -0
  640. package/skills/healthcheck/SKILL.md +65 -0
  641. package/skills/herdr-topology/SKILL.md +269 -0
  642. package/skills/meta-cognition/SKILL.md +24 -0
  643. package/skills/meta-improvement/SKILL.md +180 -0
  644. package/skills/misdirection-audit/SKILL.md +66 -0
  645. package/skills/pi-reference/SKILL.md +104 -0
  646. package/skills/placement-discipline/SKILL.md +69 -0
  647. package/skills/probe-evaluation/SKILL.md +85 -0
  648. package/skills/release-pipeline/SKILL.md +191 -0
  649. package/skills/research/SKILL.md +166 -0
  650. package/skills/skill-usage/SKILL.md +81 -0
  651. package/skills/software-engineer/SKILL.md +83 -0
  652. package/skills/subagent-orchestration/SKILL.md +454 -0
  653. package/skills/subagent-orchestration/scripts/workers.mjs +283 -0
  654. package/skills/subagent-verification/SKILL.md +127 -0
  655. package/skills/tone-quality/SKILL.md +176 -0
  656. package/skills/voice-replies/SKILL.md +125 -0
  657. package/src/AGENTS.md +111 -0
  658. package/src/extensions/cognitive/AGENTS.md +29 -0
  659. package/src/extensions/cognitive/mars-reflector/index.ts +415 -0
  660. package/src/extensions/cognitive/metacognition/handlers/AGENTS.md +30 -0
  661. package/src/extensions/cognitive/metacognition/handlers/claim-verification.ts +295 -0
  662. package/src/extensions/cognitive/metacognition/handlers/finalize.ts +648 -0
  663. package/src/extensions/cognitive/metacognition/handlers/hypothesize.ts +368 -0
  664. package/src/extensions/cognitive/metacognition/handlers/scoring.ts +242 -0
  665. package/src/extensions/cognitive/metacognition/handlers/think-budget.ts +199 -0
  666. package/src/extensions/cognitive/metacognition/handlers/think.ts +489 -0
  667. package/src/extensions/cognitive/metacognition/handlers/verify.ts +440 -0
  668. package/src/extensions/cognitive/metacognition/index.ts +109 -0
  669. package/src/extensions/cognitive/reasoning/index.ts +168 -0
  670. package/src/extensions/cognitive/sycophancy-detector/index.ts +286 -0
  671. package/src/extensions/cognitive/topic-drift/index.ts +429 -0
  672. package/src/extensions/cognitive/turn-outcome/index.ts +209 -0
  673. package/src/extensions/context-management/README.md +102 -0
  674. package/src/extensions/context-management/index.ts +383 -0
  675. package/src/extensions/core/AGENTS.md +34 -0
  676. package/src/extensions/core/agent-environment/index.ts +135 -0
  677. package/src/extensions/core/polyfill/index.ts +617 -0
  678. package/src/extensions/core/prompt-builder/AGENTS.md +151 -0
  679. package/src/extensions/core/prompt-builder/awareness-whisper.ts +162 -0
  680. package/src/extensions/core/prompt-builder/context-section.ts +120 -0
  681. package/src/extensions/core/prompt-builder/custom-sections.ts +27 -0
  682. package/src/extensions/core/prompt-builder/external-tool-guidelines.ts +41 -0
  683. package/src/extensions/core/prompt-builder/identity.ts +98 -0
  684. package/src/extensions/core/prompt-builder/index.ts +602 -0
  685. package/src/extensions/core/prompt-builder/inspect.ts +227 -0
  686. package/src/extensions/core/prompt-builder/instance-composition.ts +515 -0
  687. package/src/extensions/core/prompt-builder/memory-section.ts +76 -0
  688. package/src/extensions/core/prompt-builder/pi-reference-section.ts +26 -0
  689. package/src/extensions/core/prompt-builder/project-docs-section.ts +105 -0
  690. package/src/extensions/core/prompt-builder/section-parity.ts +108 -0
  691. package/src/extensions/core/prompt-builder/section-publish.ts +43 -0
  692. package/src/extensions/core/prompt-builder/section.ts +150 -0
  693. package/src/extensions/core/prompt-builder/surface-discipline-section.ts +21 -0
  694. package/src/extensions/core/prompt-builder/system-info-tool.ts +87 -0
  695. package/src/extensions/core/prompt-builder/tool-description-trim.ts +127 -0
  696. package/src/extensions/core/prompt-builder/tool-guidelines.ts +226 -0
  697. package/src/extensions/core/prompt-builder/tool-pipelines.ts +78 -0
  698. package/src/extensions/core/prompt-builder/top-level-extensions.ts +338 -0
  699. package/src/extensions/core/skills-tool/auto-inject.ts +1004 -0
  700. package/src/extensions/core/skills-tool/index.ts +240 -0
  701. package/src/extensions/core/skills-tool/loading-guidance.ts +89 -0
  702. package/src/extensions/core/skills-tool/session-records.ts +328 -0
  703. package/src/extensions/core/skills-tool/skill-triggers.ts +119 -0
  704. package/src/extensions/enforcement/AGENTS.md +69 -0
  705. package/src/extensions/enforcement/detection/malformed.ts +42 -0
  706. package/src/extensions/enforcement/detection/verification.ts +52 -0
  707. package/src/extensions/enforcement/enforcement-types.ts +42 -0
  708. package/src/extensions/enforcement/handler-registry.ts +225 -0
  709. package/src/extensions/enforcement/handlers/AGENTS.md +68 -0
  710. package/src/extensions/enforcement/handlers/analysis/AGENTS.md +40 -0
  711. package/src/extensions/enforcement/handlers/analysis/bpe-handler.ts +53 -0
  712. package/src/extensions/enforcement/handlers/analysis/dreamer-handler.ts +73 -0
  713. package/src/extensions/enforcement/handlers/analysis/drift-handler.ts +100 -0
  714. package/src/extensions/enforcement/handlers/analysis/feedback-handler.ts +22 -0
  715. package/src/extensions/enforcement/handlers/analysis/mars-handler.ts +121 -0
  716. package/src/extensions/enforcement/handlers/analysis/reflection-handler.ts +22 -0
  717. package/src/extensions/enforcement/handlers/blocking.ts +50 -0
  718. package/src/extensions/enforcement/handlers/message-analysis.ts +95 -0
  719. package/src/extensions/enforcement/handlers/orphan-chains.ts +53 -0
  720. package/src/extensions/enforcement/handlers/over-correction-gate.ts +634 -0
  721. package/src/extensions/enforcement/handlers/probe-handler.ts +133 -0
  722. package/src/extensions/enforcement/handlers/register-adherence-meter.ts +216 -0
  723. package/src/extensions/enforcement/handlers/register-agent-end-api-error.ts +82 -0
  724. package/src/extensions/enforcement/handlers/register-input-handler.ts +36 -0
  725. package/src/extensions/enforcement/handlers/register-message-end.ts +477 -0
  726. package/src/extensions/enforcement/handlers/register-post-cycle-hygiene.ts +166 -0
  727. package/src/extensions/enforcement/handlers/register-session-compact.ts +248 -0
  728. package/src/extensions/enforcement/handlers/register-session-shutdown-resumption.ts +138 -0
  729. package/src/extensions/enforcement/handlers/register-session-shutdown.ts +46 -0
  730. package/src/extensions/enforcement/handlers/register-session-start-discoverability.ts +270 -0
  731. package/src/extensions/enforcement/handlers/register-session-start.ts +240 -0
  732. package/src/extensions/enforcement/handlers/register-tool-call.ts +160 -0
  733. package/src/extensions/enforcement/handlers/register-tool-result-formatting.ts +73 -0
  734. package/src/extensions/enforcement/handlers/register-tool-result.ts +108 -0
  735. package/src/extensions/enforcement/handlers/register-turn-end-hygiene.ts +456 -0
  736. package/src/extensions/enforcement/handlers/routing-handler.ts +191 -0
  737. package/src/extensions/enforcement/handlers/tool-tracker.ts +145 -0
  738. package/src/extensions/enforcement/handlers/turn-analysis.ts +156 -0
  739. package/src/extensions/enforcement/handlers/turn-end-handler.ts +538 -0
  740. package/src/extensions/enforcement/index.ts +28 -0
  741. package/src/extensions/enforcement/judge-utils.ts +106 -0
  742. package/src/extensions/enforcement/nudge-manager.ts +298 -0
  743. package/src/extensions/enforcement/self-state-claims.ts +204 -0
  744. package/src/extensions/enforcement/session-health.ts +317 -0
  745. package/src/extensions/enforcement/signals.ts +88 -0
  746. package/src/extensions/enforcement/similarity.ts +76 -0
  747. package/src/extensions/enforcement/state.ts +115 -0
  748. package/src/extensions/enforcement/substate/context-hygiene-state.ts +212 -0
  749. package/src/extensions/enforcement/substate/error-tracking-state.ts +50 -0
  750. package/src/extensions/enforcement/substate/memory-hygiene-state.ts +54 -0
  751. package/src/extensions/enforcement/substate/session-state.ts +79 -0
  752. package/src/extensions/enforcement/substate/thought-chain-state.ts +62 -0
  753. package/src/extensions/enforcement/substate/tool-tracking-state.ts +166 -0
  754. package/src/extensions/enforcement/substate/verification-judge-state.ts +52 -0
  755. package/src/extensions/enforcement/task-evidence.ts +436 -0
  756. package/src/extensions/enforcement/types.ts +38 -0
  757. package/src/extensions/enforcement/validation.ts +194 -0
  758. package/src/extensions/enforcement/verification-judge.ts +317 -0
  759. package/src/extensions/enforcement/whisper.ts +120 -0
  760. package/src/extensions/heartbeat/AGENTS.md +47 -0
  761. package/src/extensions/heartbeat/analytics/AGENTS.md +57 -0
  762. package/src/extensions/heartbeat/analytics/ab-variant.ts +106 -0
  763. package/src/extensions/heartbeat/analytics/core.ts +222 -0
  764. package/src/extensions/heartbeat/analytics/format.ts +144 -0
  765. package/src/extensions/heartbeat/analytics/index.ts +373 -0
  766. package/src/extensions/heartbeat/analytics/shared.ts +149 -0
  767. package/src/extensions/heartbeat/heartbeat-scheduler/AGENTS.md +84 -0
  768. package/src/extensions/heartbeat/heartbeat-scheduler/index.ts +1095 -0
  769. package/src/extensions/heartbeat/heartbeat-scheduler/meta-learning.ts +75 -0
  770. package/src/extensions/heartbeat/heartbeat-scheduler/modules/behavioral-drift.ts +200 -0
  771. package/src/extensions/heartbeat/heartbeat-scheduler/modules/budget.ts +113 -0
  772. package/src/extensions/heartbeat/heartbeat-scheduler/modules/context-hygiene.ts +288 -0
  773. package/src/extensions/heartbeat/heartbeat-scheduler/modules/evolver.ts +88 -0
  774. package/src/extensions/heartbeat/heartbeat-scheduler/modules/measurement.ts +47 -0
  775. package/src/extensions/heartbeat/heartbeat-scheduler/modules/recaller.ts +99 -0
  776. package/src/extensions/heartbeat/heartbeat-scheduler/modules/reflection-consolidator.ts +114 -0
  777. package/src/extensions/heartbeat/heartbeat-scheduler/policies.ts +193 -0
  778. package/src/extensions/heartbeat/heartbeat-scheduler/state.ts +88 -0
  779. package/src/extensions/heartbeat/heartbeat-scheduler/types.ts +128 -0
  780. package/src/extensions/heartbeat/heartbeat-scheduler/whisper-batcher.ts +98 -0
  781. package/src/extensions/manifest.ts +293 -0
  782. package/src/extensions/memory/AGENTS.md +93 -0
  783. package/src/extensions/memory/context-lifecycle/AGENTS.md +62 -0
  784. package/src/extensions/memory/context-lifecycle/helpers.ts +167 -0
  785. package/src/extensions/memory/context-lifecycle/index.ts +1232 -0
  786. package/src/extensions/memory/context-lifecycle/policy-engine.ts +287 -0
  787. package/src/extensions/memory/context-lifecycle/signal-detector.ts +293 -0
  788. package/src/extensions/memory/context-lifecycle/state.ts +165 -0
  789. package/src/extensions/memory/context-lifecycle/types.ts +441 -0
  790. package/src/extensions/memory/context-manager/analysis.ts +344 -0
  791. package/src/extensions/memory/context-manager/handlers/AGENTS.md +37 -0
  792. package/src/extensions/memory/context-manager/handlers/compaction-chunked.ts +800 -0
  793. package/src/extensions/memory/context-manager/handlers/compaction-retry.ts +556 -0
  794. package/src/extensions/memory/context-manager/handlers/compaction-trace.ts +243 -0
  795. package/src/extensions/memory/context-manager/handlers/compaction-watchdog.ts +366 -0
  796. package/src/extensions/memory/context-manager/handlers/compaction.ts +2552 -0
  797. package/src/extensions/memory/context-manager/handlers/context-emergency.ts +470 -0
  798. package/src/extensions/memory/context-manager/handlers/events.ts +430 -0
  799. package/src/extensions/memory/context-manager/handlers/navigation.ts +94 -0
  800. package/src/extensions/memory/context-manager/handlers/offload.ts +330 -0
  801. package/src/extensions/memory/context-manager/handlers/rotation.ts +363 -0
  802. package/src/extensions/memory/context-manager/handlers/shared.ts +961 -0
  803. package/src/extensions/memory/context-manager/handlers/tool-batch-boundary.ts +219 -0
  804. package/src/extensions/memory/context-manager/handlers/toolresult-capture-cap.ts +176 -0
  805. package/src/extensions/memory/context-manager/handlers/tools/context-compress.ts +1333 -0
  806. package/src/extensions/memory/context-manager/handlers/tools/context-inspect.ts +343 -0
  807. package/src/extensions/memory/context-manager/handlers/tools/context-navigate.ts +423 -0
  808. package/src/extensions/memory/context-manager/handlers/tools/offload-recover.ts +234 -0
  809. package/src/extensions/memory/context-manager/index.ts +111 -0
  810. package/src/extensions/memory/context-manager/pruning.ts +479 -0
  811. package/src/extensions/memory/context-manager/semantic-compress.ts +321 -0
  812. package/src/extensions/memory/memory-agent-bridge/AGENTS.md +62 -0
  813. package/src/extensions/memory/memory-agent-bridge/conflict-qa-tool.ts +106 -0
  814. package/src/extensions/memory/memory-agent-bridge/explore-paths.ts +283 -0
  815. package/src/extensions/memory/memory-agent-bridge/index.ts +163 -0
  816. package/src/extensions/memory/memory-agent-bridge/memory-store-tool.ts +284 -0
  817. package/src/extensions/memory/memory-agent-bridge/memory-tool.ts +746 -0
  818. package/src/extensions/memory/scratchpad/AGENTS.md +148 -0
  819. package/src/extensions/memory/scratchpad/format.ts +161 -0
  820. package/src/extensions/memory/scratchpad/handlers.ts +601 -0
  821. package/src/extensions/memory/scratchpad/index.ts +230 -0
  822. package/src/extensions/memory/scratchpad/persistence.ts +374 -0
  823. package/src/extensions/memory/scratchpad/types.ts +149 -0
  824. package/src/extensions/memory/scratchpad/utils.ts +268 -0
  825. package/src/extensions/memory/session-recall/AGENTS.md +104 -0
  826. package/src/extensions/memory/session-recall/analyze.ts +605 -0
  827. package/src/extensions/memory/session-recall/context-aggregate.ts +381 -0
  828. package/src/extensions/memory/session-recall/index.ts +956 -0
  829. package/src/extensions/memory/session-recall/query.ts +44 -0
  830. package/src/extensions/memory/session-recall/rank.ts +121 -0
  831. package/src/extensions/memory/session-recall/search.ts +801 -0
  832. package/src/extensions/memory/session-recall/stats.ts +93 -0
  833. package/src/extensions/memory/session-recall/text-utils.ts +209 -0
  834. package/src/extensions/memory/three-memory-stores/AGENTS.md +66 -0
  835. package/src/extensions/memory/three-memory-stores/episodes-disk.ts +138 -0
  836. package/src/extensions/memory/three-memory-stores/episodes.ts +371 -0
  837. package/src/extensions/memory/three-memory-stores/handlers/whisper-recall.ts +132 -0
  838. package/src/extensions/memory/three-memory-stores/heuristics.ts +109 -0
  839. package/src/extensions/memory/three-memory-stores/index.ts +549 -0
  840. package/src/extensions/memory/three-memory-stores/tool-reliability.ts +58 -0
  841. package/src/extensions/memory/three-memory-stores/types.ts +74 -0
  842. package/src/extensions/memory/workspace-snapshot/AGENTS.md +19 -0
  843. package/src/extensions/memory/workspace-snapshot/index.ts +455 -0
  844. package/src/extensions/orchestrator/index.ts +1141 -0
  845. package/src/extensions/scheduling/AGENTS.md +26 -0
  846. package/src/extensions/scheduling/timer/AGENTS.md +259 -0
  847. package/src/extensions/scheduling/timer/fire-timing.ts +46 -0
  848. package/src/extensions/scheduling/timer/index.ts +1331 -0
  849. package/src/extensions/scheduling/timer/poller.ts +138 -0
  850. package/src/extensions/scheduling/timer/recovery.ts +462 -0
  851. package/src/extensions/scheduling/timer/store-file.ts +59 -0
  852. package/src/extensions/scheduling/timer/timer-manager.ts +161 -0
  853. package/src/extensions/scheduling/timer/wake-retry.ts +1057 -0
  854. package/src/extensions/self/AGENTS.md +30 -0
  855. package/src/extensions/self/auto-recovery/index.ts +112 -0
  856. package/src/extensions/self/error-tracking/AGENTS.md +38 -0
  857. package/src/extensions/self/error-tracking/index.ts +299 -0
  858. package/src/extensions/self/health-maintenance/AGENTS.md +42 -0
  859. package/src/extensions/self/health-maintenance/format.ts +87 -0
  860. package/src/extensions/self/health-maintenance/handlers/session-health-tool.ts +182 -0
  861. package/src/extensions/self/health-maintenance/helpers.ts +78 -0
  862. package/src/extensions/self/health-maintenance/index.ts +308 -0
  863. package/src/extensions/self/health-maintenance/types.ts +14 -0
  864. package/src/extensions/self/latent-activator/AGENTS.md +64 -0
  865. package/src/extensions/self/latent-activator/index.ts +206 -0
  866. package/src/extensions/self/latent-activator/mixes.ts +22 -0
  867. package/src/extensions/self/latent-activator/signals.ts +237 -0
  868. package/src/extensions/self/latent-activator/state.ts +79 -0
  869. package/src/extensions/self/latent-activator/types.ts +47 -0
  870. package/src/extensions/self/watchdog/AGENTS.md +27 -0
  871. package/src/extensions/self/watchdog/config.ts +73 -0
  872. package/src/extensions/self/watchdog/engine.ts +1246 -0
  873. package/src/extensions/self/watchdog/index.ts +577 -0
  874. package/src/index.ts +93 -0
  875. package/src/lib/AGENTS.md +39 -0
  876. package/src/lib/ai/AGENTS.md +37 -0
  877. package/src/lib/ai/consolidated-claim-critic.ts +287 -0
  878. package/src/lib/ai/cost-report.ts +206 -0
  879. package/src/lib/ai/critic-cache.ts +122 -0
  880. package/src/lib/ai/critic-fallbacks.ts +74 -0
  881. package/src/lib/ai/critic-gate.ts +135 -0
  882. package/src/lib/ai/critic-helpers.ts +135 -0
  883. package/src/lib/ai/critic-registry.ts +754 -0
  884. package/src/lib/ai/critic-stats.ts +158 -0
  885. package/src/lib/ai/judge-budget.ts +241 -0
  886. package/src/lib/ai/language-hint.ts +70 -0
  887. package/src/lib/ai/llm-call.ts +975 -0
  888. package/src/lib/ai/model-resolver.ts +224 -0
  889. package/src/lib/ai/models-init.ts +68 -0
  890. package/src/lib/ai/payload-hygiene.ts +265 -0
  891. package/src/lib/ai/post-loop-classify.ts +185 -0
  892. package/src/lib/ai/text-classifier.ts +746 -0
  893. package/src/lib/cognitive/AGENTS.md +40 -0
  894. package/src/lib/cognitive/hints.ts +254 -0
  895. package/src/lib/cognitive/openspec.ts +124 -0
  896. package/src/lib/config/AGENTS.md +17 -0
  897. package/src/lib/config/braid-paths.ts +401 -0
  898. package/src/lib/config/braid-settings.ts +1442 -0
  899. package/src/lib/config/per-tool-settings.ts +197 -0
  900. package/src/lib/config/session-profiles.ts +165 -0
  901. package/src/lib/constants/AGENTS.md +15 -0
  902. package/src/lib/constants/injection-details.ts +32 -0
  903. package/src/lib/constants/session-thresholds.ts +64 -0
  904. package/src/lib/constants/tool-constants.ts +16 -0
  905. package/src/lib/core/AGENTS.md +23 -0
  906. package/src/lib/core/event-names.ts +31 -0
  907. package/src/lib/core/logger.ts +334 -0
  908. package/src/lib/detection/AGENTS.md +21 -0
  909. package/src/lib/detection/compression-strategy.ts +183 -0
  910. package/src/lib/detection/consolidated-topic-critic.ts +188 -0
  911. package/src/lib/detection/context-density.ts +237 -0
  912. package/src/lib/detection/context-thresholds.ts +132 -0
  913. package/src/lib/detection/context-tiers.ts +201 -0
  914. package/src/lib/detection/context-usage.ts +270 -0
  915. package/src/lib/detection/degradation-detector.ts +583 -0
  916. package/src/lib/detection/test-burst.ts +170 -0
  917. package/src/lib/detection/tool-loop-detector.ts +364 -0
  918. package/src/lib/detection/topic-drift-detector.ts +323 -0
  919. package/src/lib/enforcement/AGENTS.md +20 -0
  920. package/src/lib/enforcement/adherence-meter.ts +578 -0
  921. package/src/lib/enforcement/turn-dedup.ts +246 -0
  922. package/src/lib/errors/llm-error.ts +288 -0
  923. package/src/lib/events/AGENTS.md +23 -0
  924. package/src/lib/events/consolidation-channel.ts +493 -0
  925. package/src/lib/events/consolidation-scoring.ts +112 -0
  926. package/src/lib/events/event-bus.ts +213 -0
  927. package/src/lib/events/event-types.ts +53 -0
  928. package/src/lib/events/timer-bus.ts +53 -0
  929. package/src/lib/events/timer-types.ts +64 -0
  930. package/src/lib/events/turn-end-coordinator.ts +108 -0
  931. package/src/lib/harness/AGENTS.md +20 -0
  932. package/src/lib/harness/failure-trace-collector.ts +157 -0
  933. package/src/lib/harness/index.ts +41 -0
  934. package/src/lib/harness/types.ts +122 -0
  935. package/src/lib/harness/weakness-miner.ts +209 -0
  936. package/src/lib/memory/AGENTS.md +36 -0
  937. package/src/lib/memory/constants.ts +34 -0
  938. package/src/lib/memory/index.ts +705 -0
  939. package/src/lib/memory/lifecycle.ts +159 -0
  940. package/src/lib/memory/past-insights.ts +221 -0
  941. package/src/lib/memory/storage.ts +187 -0
  942. package/src/lib/memory/store-lock.ts +70 -0
  943. package/src/lib/memory/store-merge.ts +100 -0
  944. package/src/lib/memory/types.ts +82 -0
  945. package/src/lib/memory/utils.ts +173 -0
  946. package/src/lib/memory/write-log.ts +174 -0
  947. package/src/lib/memory/write-quality.ts +383 -0
  948. package/src/lib/orchestrator/branch.ts +193 -0
  949. package/src/lib/orchestrator/index.ts +78 -0
  950. package/src/lib/orchestrator/locks.ts +160 -0
  951. package/src/lib/orchestrator/slop-scanner.ts +258 -0
  952. package/src/lib/orchestrator/workers.ts +1382 -0
  953. package/src/lib/public.ts +43 -0
  954. package/src/lib/reasoning/AGENTS.md +25 -0
  955. package/src/lib/reasoning/advice-tracker.ts +244 -0
  956. package/src/lib/reasoning/belief-policy-engine.ts +342 -0
  957. package/src/lib/reasoning/belief-types.ts +45 -0
  958. package/src/lib/reasoning/classifier-offline.ts +111 -0
  959. package/src/lib/reasoning/dreamer.ts +215 -0
  960. package/src/lib/reasoning/nudge-analytics.ts +85 -0
  961. package/src/lib/reasoning/policy-rules.ts +172 -0
  962. package/src/lib/reasoning/reasoning-metrics.ts +202 -0
  963. package/src/lib/reasoning/reasoning-summary.ts +154 -0
  964. package/src/lib/reasoning/tool-usage-analyzer.ts +248 -0
  965. package/src/lib/state/AGENTS.md +192 -0
  966. package/src/lib/state/async-storage.ts +189 -0
  967. package/src/lib/state/extension-state.ts +419 -0
  968. package/src/lib/state/global-state.ts +1046 -0
  969. package/src/lib/state/metacognitive-state.ts +65 -0
  970. package/src/lib/state/session-manager.ts +43 -0
  971. package/src/lib/state/session-start-queue.ts +135 -0
  972. package/src/lib/state/state-checkpoint.ts +352 -0
  973. package/src/lib/state/telegram-poller-liveness.ts +75 -0
  974. package/src/lib/state/tool-provenance.ts +26 -0
  975. package/src/lib/state/workspace-snapshot.ts +466 -0
  976. package/src/lib/store/AGENTS.md +24 -0
  977. package/src/lib/store/belief-store.ts +325 -0
  978. package/src/lib/store/bidirectional-verifier.ts +316 -0
  979. package/src/lib/store/claim-tracker.ts +382 -0
  980. package/src/lib/store/conflict-qa.ts +385 -0
  981. package/src/lib/store/evidence-pool.ts +779 -0
  982. package/src/lib/telemetry/AGENTS.md +28 -0
  983. package/src/lib/telemetry/context-heartbeat.ts +555 -0
  984. package/src/lib/telemetry/drift-signals.ts +105 -0
  985. package/src/lib/telemetry/rss-telemetry.ts +57 -0
  986. package/src/lib/types/AGENTS.md +21 -0
  987. package/src/lib/types/episode-types.ts +31 -0
  988. package/src/lib/types/standard-result.ts +40 -0
  989. package/src/lib/utils/AGENTS.md +30 -0
  990. package/src/lib/utils/async-fs.ts +23 -0
  991. package/src/lib/utils/bounded.ts +58 -0
  992. package/src/lib/utils/dedup.ts +44 -0
  993. package/src/lib/utils/error-guard.ts +27 -0
  994. package/src/lib/utils/extension-utils.ts +72 -0
  995. package/src/lib/utils/extract-json.ts +89 -0
  996. package/src/lib/utils/file-mutation-queue.ts +172 -0
  997. package/src/lib/utils/filter-safe-to-remove.ts +301 -0
  998. package/src/lib/utils/format-tool-result.ts +109 -0
  999. package/src/lib/utils/id.ts +64 -0
  1000. package/src/lib/utils/injection-tracker.ts +1014 -0
  1001. package/src/lib/utils/local-time.ts +196 -0
  1002. package/src/lib/utils/memory-fence.ts +70 -0
  1003. package/src/lib/utils/sop-extractor.ts +329 -0
  1004. package/src/lib/utils/sop-suggestion.ts +426 -0
  1005. package/src/lib/utils/wake-gate.ts +318 -0
  1006. package/src/lib/utils/whisper-format.ts +120 -0
  1007. package/src/lib/verification/coordination-checker.ts +183 -0
  1008. package/src/loader/AGENTS.md +32 -0
  1009. package/src/loader/api.ts +138 -0
  1010. package/src/loader/loader.ts +600 -0
  1011. package/src/types/extension-context.d.ts +85 -0
@@ -0,0 +1,1382 @@
1
+ /**
2
+ * Worker registry for multi-agent orchestration.
3
+ *
4
+ * Admission, lifecycle, and result-location records for agent workers.
5
+ * The parent registers a worker before spawning it, updates the handle as
6
+ * pane/session facts arrive, and closes the entry with an outcome and gate
7
+ * evidence. `checkWorker` computes a verdict from evidence (output file,
8
+ * session growth, branch commits, result schema) — never from the worker's
9
+ * own claim alone.
10
+ *
11
+ * Registry file location: ~/.pi/agent/braid/projects/<sanitized-cwd>/workers.json
12
+ * (per-CWD, beside locks.json, shared across all agents on the same project).
13
+ *
14
+ * A terminal completion is also judged for effect evidence — a deliverable
15
+ * written during the run, a branch advance or recorded merge, or a gate that
16
+ * exited 0. A completed close with none of the three is flagged, not refused:
17
+ * the flag travels on the close result and the check verdict.
18
+ *
19
+ * Writes are atomic (temp file + rename) with mode 0600. Reads tolerate a
20
+ * missing or corrupt file by returning an empty registry, like locks.ts.
21
+ */
22
+
23
+ import {
24
+ chmodSync,
25
+ existsSync,
26
+ mkdirSync,
27
+ readFileSync,
28
+ readdirSync,
29
+ renameSync,
30
+ rmSync,
31
+ statSync,
32
+ writeFileSync,
33
+ } from "node:fs";
34
+ import { execFileSync } from "node:child_process";
35
+ import { dirname, join } from "node:path";
36
+ import { getWorkersFilePath, projectsDir } from "../config/braid-paths.js";
37
+ import { getAllLocks, releaseLock } from "./locks.js";
38
+
39
+ // ── Types ──────────────────────────────────────────────────────────────────
40
+
41
+ export type WorkerStatus =
42
+ | "admitted"
43
+ | "working"
44
+ | "merged"
45
+ | "completed"
46
+ | "error"
47
+ | "stalled"
48
+ | "false-done"
49
+ | "closed";
50
+
51
+ /** Terminal outcomes accepted by closeWorker. */
52
+ export type WorkerOutcome = "completed" | "error" | "stalled" | "false-done" | "closed";
53
+
54
+ export interface WorkerGate {
55
+ cmd: string;
56
+ exit: number;
57
+ at: string;
58
+ }
59
+
60
+ /** One duplicate admission a live entry turned away, and the request it refused. */
61
+ export interface WorkerAdmissionRefusal {
62
+ /** The request id whose admission this entry refused. */
63
+ requestId: string;
64
+ /** When the refusal was recorded. */
65
+ at: string;
66
+ }
67
+
68
+ /**
69
+ * Checkpoint fields a caller supplies. The registry stamps `at`, so a writer
70
+ * cannot backdate a resume point.
71
+ */
72
+ export interface WorkerCheckpointInput {
73
+ /** Lifecycle phase the worker is in (e.g. "impl", "gates"). */
74
+ phase: string;
75
+ /** Last completed step within that phase (e.g. "commit", "typecheck"). */
76
+ step: string;
77
+ }
78
+
79
+ export interface WorkerCheckpoint extends WorkerCheckpointInput {
80
+ /** When the checkpoint was written. */
81
+ at: string;
82
+ }
83
+
84
+ export interface WorkerEntry {
85
+ workerId: string;
86
+ spec: string;
87
+ status: WorkerStatus;
88
+ cwd: string;
89
+ pane: string | null;
90
+ workspace: string | null;
91
+ workerSession: string | null;
92
+ outputFile: string | null;
93
+ branch: string | null;
94
+ files: string[];
95
+ spawnedAt: string;
96
+ lastSeenAt: string | null;
97
+ resultAt: string | null;
98
+ /** Base tip this worker's work merges into; null until a merge lands. */
99
+ mergeSha: string | null;
100
+ /** When that merge landed. */
101
+ mergedAt: string | null;
102
+ closedAt: string | null;
103
+ gates: WorkerGate[];
104
+ /**
105
+ * Duplicate admissions this row turned away while it was live: each records
106
+ * the request id that was refused and when. Summed for the fleet's refusal
107
+ * count, so the number is registry fact rather than an inference.
108
+ */
109
+ admissionRefusals: WorkerAdmissionRefusal[];
110
+ /**
111
+ * Exactly-once identity of the unit of work this entry admits, keyed by
112
+ * `(workerId, step)` — see deriveRequestId. Null on a row admitted before
113
+ * request ids existed, and no request ever matches such a row.
114
+ */
115
+ requestId: string | null;
116
+ /**
117
+ * Where the work stood when the entry was last written: the phase and the
118
+ * last step completed in it. Null when the worker never recorded one, which
119
+ * leaves the row with no resume point.
120
+ */
121
+ checkpoint: WorkerCheckpoint | null;
122
+ }
123
+
124
+ export interface WorkerRegistry {
125
+ version: number;
126
+ workers: Record<string, WorkerEntry>;
127
+ }
128
+
129
+ export interface RegisterWorkerInput {
130
+ workerId: string;
131
+ spec: string;
132
+ cwd: string;
133
+ files?: string[];
134
+ branch?: string;
135
+ outputFile?: string;
136
+ /**
137
+ * Worker handle, when the caller already has it at admission time. Absent
138
+ * stays null: a handle is never invented, and a pane is a place to look, not
139
+ * evidence that anything runs there.
140
+ */
141
+ pane?: string;
142
+ /** Path to the worker's session .jsonl; the only liveness evidence the
143
+ * registry holds, read as file mtime by evaluateWorker. */
144
+ workerSession?: string;
145
+ /**
146
+ * Exactly-once request id for this submission. Defaults to the derived
147
+ * `(workerId, step)` key for step 1, so a retried admission of the same work
148
+ * resolves to the same request and reuses the entry it already admitted.
149
+ */
150
+ requestId?: string;
151
+ }
152
+
153
+ export interface RegisterWorkerResult {
154
+ ok: boolean;
155
+ entry?: WorkerEntry;
156
+ reason?: string;
157
+ /** True when a live entry already admitted this request and was reused. */
158
+ reused?: boolean;
159
+ }
160
+
161
+ export interface UpdateWorkerPatch {
162
+ pane?: string;
163
+ workspace?: string;
164
+ workerSession?: string;
165
+ outputFile?: string;
166
+ branch?: string;
167
+ files?: string[];
168
+ status?: WorkerStatus;
169
+ /** Resume point to record; stamped with the write time. */
170
+ checkpoint?: WorkerCheckpointInput;
171
+ }
172
+
173
+ export interface WorkerCheckOptions {
174
+ /** herdr lifecycle state (idle|working|blocked|done|unknown), passed by the parent. */
175
+ liveStatus?: string;
176
+ /** Git repo root used for the branch-ahead count. */
177
+ cwd?: string;
178
+ /**
179
+ * Branch recorded on this worker's lock rows. Used only when the entry has
180
+ * no branch of its own (`entry.branch ?? fallbackBranch`); when omitted,
181
+ * checkWorker reads the project lock table itself.
182
+ */
183
+ fallbackBranch?: string;
184
+ /** Clock override for tests; defaults to Date.now(). */
185
+ now?: number;
186
+ /** Frozen-session threshold in seconds; defaults to 600. */
187
+ stalledAfterSec?: number;
188
+ }
189
+
190
+ export interface WorkerCheckResult {
191
+ workerId: string;
192
+ status: WorkerVerdictStatus;
193
+ reason: string;
194
+ outputFile: string | null;
195
+ outputExists: boolean;
196
+ outputAgeSec: number | null;
197
+ sessionGrowthAgeSec: number | null;
198
+ branchAhead: number | null;
199
+ schemaValid: boolean;
200
+ /**
201
+ * How many assistant messages back from the newest the result block was
202
+ * found (0 = the last assistant message), or null when none was valid
203
+ * within the scan window. Lets a parent tell a terminal block from a
204
+ * near-terminal one.
205
+ */
206
+ resultSchemaMessageOffset: number | null;
207
+ /** Request id the entry was admitted under, when it recorded one. */
208
+ requestId: string | null;
209
+ /** Resume point the entry carries, when it has one. */
210
+ checkpoint: WorkerCheckpoint | null;
211
+ gateSummary: string;
212
+ /**
213
+ * Effect evidence for a terminal completion, or null when the row is not
214
+ * one (unclosed, or closed with a non-completed outcome). `none` true is
215
+ * the no-effect-evidence flag: the close recorded a completion while the
216
+ * row shows none of the three evidence kinds.
217
+ */
218
+ effectEvidence: WorkerEffectEvidence | null;
219
+ }
220
+
221
+ /**
222
+ * A status the registry reports. `resumable` is derived, never stored: it says
223
+ * the entry is mid-flight with a checkpoint to resume from, which is a
224
+ * statement about evidence rather than a lifecycle state a caller sets. No
225
+ * stored row carries it, so the on-disk status set is unchanged.
226
+ */
227
+ export type WorkerVerdictStatus = WorkerStatus | "resumable";
228
+
229
+ // ── Constants ──────────────────────────────────────────────────────────────
230
+
231
+ export const WORKER_REGISTRY_VERSION = 1;
232
+
233
+ /**
234
+ * Spec names a worker result may declare: the accepted set, and the one source
235
+ * the tool schema renders from. `project` is in the set; the tool prose listed
236
+ * only four before it rendered from here, which is the drift this list ends.
237
+ */
238
+ export const WORKER_SPECS: readonly string[] = ["research", "impl", "verify", "audit", "project"];
239
+
240
+ export const WORKER_STATUSES: readonly WorkerStatus[] = [
241
+ "admitted",
242
+ "working",
243
+ "merged",
244
+ "completed",
245
+ "error",
246
+ "stalled",
247
+ "false-done",
248
+ "closed",
249
+ ];
250
+
251
+ export const WORKER_OUTCOMES: readonly WorkerOutcome[] = [
252
+ "completed",
253
+ "error",
254
+ "stalled",
255
+ "false-done",
256
+ "closed",
257
+ ];
258
+
259
+ /** Statuses check-worker may report: the stored statuses plus `resumable`. */
260
+ export const WORKER_VERDICT_STATUSES: readonly WorkerVerdictStatus[] = [
261
+ ...WORKER_STATUSES,
262
+ "resumable",
263
+ ];
264
+
265
+ /** Statuses a worker's result schema may self-report. */
266
+ export const RESULT_SCHEMA_STATUSES: readonly string[] = [
267
+ "completed",
268
+ "partial",
269
+ "blocked",
270
+ "error",
271
+ ];
272
+
273
+ /**
274
+ * The four roles a worker lifecycle's values can play. They are distinct
275
+ * vocabularies that share words: `completed` is a stored status, a close
276
+ * outcome, a computed verdict and a result attestation, so a bare value
277
+ * means nothing until the layer names which one it is.
278
+ */
279
+ export type WorkerStatusLayerRole =
280
+ | "stored status"
281
+ | "close outcome"
282
+ | "computed verdict"
283
+ | "result attestation";
284
+
285
+ /** One vocabulary in the status-layer table: its role, writer, and values. */
286
+ export interface WorkerStatusLayer {
287
+ /** The role the values play; the four layers are never interchangeable. */
288
+ role: WorkerStatusLayerRole;
289
+ /** Who writes values in this layer. */
290
+ owner: string;
291
+ /** Accepted values, in reporting order. */
292
+ values: readonly string[];
293
+ /** What one value in this layer states, as a clause the tool schema reuses. */
294
+ states: string;
295
+ }
296
+
297
+ /**
298
+ * The four vocabularies a worker lifecycle speaks in, each with its values and
299
+ * its writer. Readers (the tool schema, the tests, the report) render from this
300
+ * table rather than restating the values, so a value added here reaches every
301
+ * reader at once.
302
+ */
303
+ export const WORKER_STATUS_LAYERS: readonly WorkerStatusLayer[] = [
304
+ {
305
+ role: "stored status",
306
+ owner: "registry row (spawn admission, update-worker, close and merge writes)",
307
+ values: WORKER_STATUSES,
308
+ states: "the lifecycle state the registry row carries",
309
+ },
310
+ {
311
+ role: "close outcome",
312
+ owner: "close-worker call",
313
+ values: WORKER_OUTCOMES,
314
+ states: "the terminal outcome a close records",
315
+ },
316
+ {
317
+ role: "computed verdict",
318
+ owner: "check-worker",
319
+ values: WORKER_VERDICT_STATUSES,
320
+ states: "what check-worker derives from evidence, resumable never stored",
321
+ },
322
+ {
323
+ role: "result attestation",
324
+ owner: "worker's own result block",
325
+ values: RESULT_SCHEMA_STATUSES,
326
+ states: "what the worker's result block claims about its own result",
327
+ },
328
+ ];
329
+
330
+ const DEFAULT_STALLED_AFTER_SEC = 600;
331
+
332
+ /**
333
+ * How many assistant messages back from the newest a result block may sit.
334
+ * A worker that emits its validated block and then one closing prose line is
335
+ * still terminal; a parent must be able to tell that block from a progress
336
+ * note, so the offset is recorded in the verdict.
337
+ */
338
+ const RESULT_SCHEMA_MAX_MESSAGES_BACK = 3;
339
+
340
+ // ── Status parsing ─────────────────────────────────────────────────────────
341
+
342
+ export function parseWorkerStatus(raw: string): WorkerStatus {
343
+ const value = raw.trim() as WorkerStatus;
344
+ if (!WORKER_STATUSES.includes(value)) {
345
+ throw new Error(
346
+ `Unknown worker status "${raw}". Expected one of: ${WORKER_STATUSES.join(", ")}`,
347
+ );
348
+ }
349
+ return value;
350
+ }
351
+
352
+ export function parseWorkerOutcome(raw: string): WorkerOutcome {
353
+ const value = raw.trim() as WorkerOutcome;
354
+ if (!WORKER_OUTCOMES.includes(value)) {
355
+ throw new Error(
356
+ `Unknown worker outcome "${raw}". Expected one of: ${WORKER_OUTCOMES.join(", ")}`,
357
+ );
358
+ }
359
+ return value;
360
+ }
361
+
362
+ // ── Registry I/O ───────────────────────────────────────────────────────────
363
+
364
+ function emptyRegistry(): WorkerRegistry {
365
+ return { version: WORKER_REGISTRY_VERSION, workers: {} };
366
+ }
367
+
368
+ /**
369
+ * Fill in what a row written before these fields existed lacks. The read path
370
+ * writes nothing back: an entry with no request id or checkpoint reports null
371
+ * for both and keeps every other fact it has, so reading a legacy registry
372
+ * migrates nothing.
373
+ */
374
+ function normalizeEntry(raw: WorkerEntry): WorkerEntry {
375
+ const requestId =
376
+ typeof raw.requestId === "string" && raw.requestId.length > 0 ? raw.requestId : null;
377
+ return {
378
+ ...raw,
379
+ requestId,
380
+ checkpoint: isCheckpoint(raw.checkpoint) ? raw.checkpoint : null,
381
+ admissionRefusals: Array.isArray(raw.admissionRefusals) ? raw.admissionRefusals : [],
382
+ };
383
+ }
384
+
385
+ function isCheckpoint(raw: unknown): raw is WorkerCheckpoint {
386
+ if (!raw || typeof raw !== "object") return false;
387
+ const value = raw as { phase?: unknown; step?: unknown; at?: unknown };
388
+ return (
389
+ typeof value.phase === "string" &&
390
+ value.phase.length > 0 &&
391
+ typeof value.step === "string" &&
392
+ value.step.length > 0 &&
393
+ typeof value.at === "string"
394
+ );
395
+ }
396
+
397
+ function loadRegistryFile(file: string): WorkerRegistry {
398
+ try {
399
+ if (!existsSync(file)) return emptyRegistry();
400
+ const raw = readFileSync(file, "utf-8").trim();
401
+ if (!raw) return emptyRegistry();
402
+ const parsed = JSON.parse(raw) as WorkerRegistry;
403
+ if (
404
+ !parsed ||
405
+ typeof parsed !== "object" ||
406
+ !parsed.workers ||
407
+ typeof parsed.workers !== "object"
408
+ ) {
409
+ return emptyRegistry();
410
+ }
411
+ const workers: Record<string, WorkerEntry> = {};
412
+ for (const [id, entry] of Object.entries(parsed.workers)) {
413
+ if (entry && typeof entry === "object") workers[id] = normalizeEntry(entry);
414
+ }
415
+ return {
416
+ version: typeof parsed.version === "number" ? parsed.version : WORKER_REGISTRY_VERSION,
417
+ workers,
418
+ };
419
+ } catch {
420
+ return emptyRegistry();
421
+ }
422
+ }
423
+
424
+ /** Read the registry for a project cwd (defaults to process.cwd()). */
425
+ export function readWorkers(cwd?: string): WorkerRegistry {
426
+ return loadRegistryFile(getWorkersFilePath(cwd ?? process.cwd()));
427
+ }
428
+
429
+ /**
430
+ * Persist the registry atomically: temp file in the same directory, then
431
+ * rename. Writes fail loudly (unlike lock writes) — a registry that
432
+ * silently drops admissions is worse than a visible error.
433
+ */
434
+ export function writeWorkers(registry: WorkerRegistry, cwd?: string): void {
435
+ const file = getWorkersFilePath(cwd ?? process.cwd());
436
+ mkdirSync(dirname(file), { recursive: true });
437
+ const tmp = `${file}.tmp-${process.pid}-${Math.random().toString(36).slice(2, 8)}`;
438
+ try {
439
+ writeFileSync(tmp, JSON.stringify(registry, null, 2), { encoding: "utf-8", mode: 0o600 });
440
+ chmodSync(tmp, 0o600);
441
+ renameSync(tmp, file);
442
+ } finally {
443
+ if (existsSync(tmp)) rmSync(tmp, { force: true });
444
+ }
445
+ }
446
+
447
+ // ── Worker lookup ──────────────────────────────────────────────────────────
448
+
449
+ /**
450
+ * Locate a worker entry. With an explicit cwd the lookup is scoped to that
451
+ * project. Without one, the process cwd is tried first, then every project
452
+ * registry under ~/.pi/agent/braid/projects — the parent often runs in its
453
+ * own workspace while the worker's registry lives under the target repo.
454
+ * Returns the registry plus the key used for writes (the entry's own cwd).
455
+ */
456
+ function locateWorker(
457
+ workerId: string,
458
+ cwd?: string,
459
+ ): { registry: WorkerRegistry; key: string } | null {
460
+ const key = cwd ?? process.cwd();
461
+ const registry = readWorkers(key);
462
+ if (registry.workers[workerId]) return { registry, key };
463
+
464
+ // A miss in the caller's own project is not proof the worker is unknown. A
465
+ // project can be named differently by different callers while being one
466
+ // directory, and an id-addressed action (check/update/close) that answered
467
+ // "unknown" for a live row would leave it stranded. Walk every project
468
+ // registry first; the caller's own key still wins when it has the row.
469
+ const projectsRoot = projectsDir();
470
+ try {
471
+ for (const dirent of readdirSync(projectsRoot, { withFileTypes: true })) {
472
+ if (!dirent.isDirectory()) continue;
473
+ const other = loadRegistryFile(join(projectsRoot, dirent.name, "workers.json"));
474
+ const entry = other.workers[workerId];
475
+ if (entry) return { registry: other, key: entry.cwd };
476
+ }
477
+ } catch {
478
+ /* no projects dir yet */
479
+ }
480
+ return null;
481
+ }
482
+
483
+ // ── Request identity ───────────────────────────────────────────────────────
484
+
485
+ /**
486
+ * The exactly-once identity of a unit of work: `(workerId, step)`. The step is
487
+ * the submission attempt — 1 for the first — so a caller that retries the same
488
+ * submission composes the same id and is recognized, while work admitted under
489
+ * a later step gets its own id. Admission records the id on the entry, and a
490
+ * submission whose id matches a live entry reuses that entry rather than
491
+ * admitting a second one.
492
+ */
493
+ export function deriveRequestId(workerId: string, step = 1): string {
494
+ return `${workerId}:${step}`;
495
+ }
496
+
497
+ /** The request id an admission carries: the caller's, or the derived key. */
498
+ export function resolveRequestId(workerId: string, requestId?: string): string {
499
+ const explicit = requestId?.trim();
500
+ return explicit ? explicit : deriveRequestId(workerId);
501
+ }
502
+
503
+ /**
504
+ * True when this entry admits the same request. A row with no recorded id
505
+ * predates request identity, so nothing matches it: a legacy live entry keeps
506
+ * refusing re-admission instead of being adopted silently by a new request.
507
+ */
508
+ function isSameRequest(entry: WorkerEntry, requestId: string): boolean {
509
+ return typeof entry.requestId === "string" && entry.requestId === requestId;
510
+ }
511
+
512
+ /** What a request states about the work, against what the entry recorded. */
513
+ function requestDifferences(
514
+ entry: WorkerEntry,
515
+ request: { spec?: string; files?: string[] },
516
+ ): string[] {
517
+ const differences: string[] = [];
518
+ if (request.spec !== undefined && request.spec !== entry.spec) {
519
+ differences.push(`spec "${entry.spec}" vs "${request.spec}"`);
520
+ }
521
+ if (request.files !== undefined) {
522
+ const recorded = [...entry.files].sort();
523
+ const requested = [...request.files].sort();
524
+ const same =
525
+ recorded.length === requested.length && recorded.every((file, i) => file === requested[i]);
526
+ if (!same) {
527
+ differences.push(`files [${recorded.join(", ")}] vs [${requested.join(", ")}]`);
528
+ }
529
+ }
530
+ return differences;
531
+ }
532
+
533
+ export interface WorkerAdmissionDecision {
534
+ action: "admit" | "reuse" | "refuse";
535
+ entry?: WorkerEntry;
536
+ reason?: string;
537
+ }
538
+
539
+ /**
540
+ * What admitting `requestId` does to the live entry that may hold this worker.
541
+ * Reuse only when the ids match *and* the request describes the same work: a
542
+ * second live row for one worker is the duplicate this identity prevents, and
543
+ * the same id carrying a different payload is a contradiction, not a retry. A
544
+ * closed entry is no obstacle — retries past a close are countable.
545
+ */
546
+ export function decideAdmission(
547
+ existing: WorkerEntry | undefined,
548
+ requestId: string,
549
+ request: { spec?: string; files?: string[] },
550
+ ): WorkerAdmissionDecision {
551
+ if (!existing || existing.closedAt) return { action: "admit" };
552
+ if (!isSameRequest(existing, requestId)) {
553
+ return {
554
+ action: "refuse",
555
+ entry: existing,
556
+ reason:
557
+ `worker ${existing.workerId} is live (status ${existing.status}, ` +
558
+ `${existing.requestId ? `requestId ${existing.requestId}` : "no requestId recorded"}); ` +
559
+ `requestId ${requestId} is a different request — close the live entry to admit it`,
560
+ };
561
+ }
562
+ const differences = requestDifferences(existing, request);
563
+ if (differences.length > 0) {
564
+ return {
565
+ action: "refuse",
566
+ entry: existing,
567
+ reason:
568
+ `requestId ${requestId} is already admitted and describes different work ` +
569
+ `(${differences.join("; ")}) — a retry carries the same payload; close the live ` +
570
+ `entry before admitting changed work`,
571
+ };
572
+ }
573
+ return { action: "reuse", entry: existing };
574
+ }
575
+
576
+ /** Append a refusal to the live entry it was made against; no I/O. */
577
+ function appendAdmissionRefusal(entry: WorkerEntry, requestId: string): void {
578
+ const refusals = Array.isArray(entry.admissionRefusals) ? entry.admissionRefusals : [];
579
+ refusals.push({ requestId, at: new Date().toISOString() });
580
+ entry.admissionRefusals = refusals;
581
+ }
582
+
583
+ /**
584
+ * Persist a refused admission against the live worker that refused it. A
585
+ * refusal leaves the row's lifecycle untouched — no status, no handle, no
586
+ * lastSeenAt — and records only the request id and the time, so the count of
587
+ * turned-away duplicates is readable from the registry instead of inferred.
588
+ * Returns false when the worker is unknown or already closed: a closed row
589
+ * refuses nothing.
590
+ */
591
+ export function recordAdmissionRefusal(workerId: string, requestId: string, cwd?: string): boolean {
592
+ const located = locateWorker(workerId, cwd);
593
+ if (!located) return false;
594
+ const entry = located.registry.workers[workerId];
595
+ if (entry.closedAt) return false;
596
+ appendAdmissionRefusal(entry, requestId);
597
+ writeWorkers(located.registry, located.key);
598
+ return true;
599
+ }
600
+
601
+ // ── CRUD ───────────────────────────────────────────────────────────────────
602
+
603
+ /**
604
+ * Admit a worker. Refuses when a live (not closed) entry exists for the
605
+ * same workerId; a closed entry is rolled over (retries are countable).
606
+ */
607
+ export function registerWorker(input: RegisterWorkerInput, cwd?: string): RegisterWorkerResult {
608
+ if (!input.workerId) throw new Error("workerId is required");
609
+ if (!input.spec) throw new Error("spec is required");
610
+ if (!input.cwd) throw new Error("cwd is required");
611
+
612
+ const key = cwd ?? input.cwd;
613
+ const registry = readWorkers(key);
614
+ const existing = registry.workers[input.workerId];
615
+ const requestId = resolveRequestId(input.workerId, input.requestId);
616
+ const decision = decideAdmission(existing, requestId, { spec: input.spec, files: input.files });
617
+ if (decision.action === "reuse") {
618
+ return { ok: true, entry: decision.entry, reused: true };
619
+ }
620
+ if (decision.action === "refuse") {
621
+ // Record the refusal on the live entry so the fleet's refusal count is a
622
+ // registry fact; a refusal changes no lifecycle field.
623
+ if (existing && !existing.closedAt) {
624
+ appendAdmissionRefusal(existing, requestId);
625
+ writeWorkers(registry, key);
626
+ }
627
+ return { ok: false, reason: decision.reason, entry: decision.entry };
628
+ }
629
+
630
+ const nowIso = new Date().toISOString();
631
+ const entry: WorkerEntry = {
632
+ workerId: input.workerId,
633
+ spec: input.spec,
634
+ status: "admitted",
635
+ cwd: input.cwd,
636
+ pane: input.pane ?? null,
637
+ workspace: null,
638
+ workerSession: input.workerSession ?? null,
639
+ outputFile: input.outputFile ?? null,
640
+ branch: input.branch ?? null,
641
+ files: input.files ?? [],
642
+ spawnedAt: nowIso,
643
+ lastSeenAt: nowIso,
644
+ resultAt: null,
645
+ mergeSha: null,
646
+ mergedAt: null,
647
+ closedAt: null,
648
+ gates: [],
649
+ admissionRefusals: [],
650
+ requestId,
651
+ checkpoint: null,
652
+ };
653
+ registry.workers[input.workerId] = entry;
654
+ writeWorkers(registry, key);
655
+ return { ok: true, entry };
656
+ }
657
+
658
+ /** Stamp a caller's checkpoint with the write time; reject an empty phase/step. */
659
+ function stampCheckpoint(input: WorkerCheckpointInput): WorkerCheckpoint {
660
+ const phase = input.phase?.trim();
661
+ const step = input.step?.trim();
662
+ if (!phase) throw new Error("checkpoint.phase is required");
663
+ if (!step) throw new Error("checkpoint.step is required");
664
+ return { phase, step, at: new Date().toISOString() };
665
+ }
666
+
667
+ /** Merge handle fields into an entry; refreshes lastSeenAt. Null when unknown. */
668
+ export function updateWorker(
669
+ workerId: string,
670
+ patch: UpdateWorkerPatch,
671
+ cwd?: string,
672
+ ): WorkerEntry | null {
673
+ const located = locateWorker(workerId, cwd);
674
+ if (!located) return null;
675
+ const entry = located.registry.workers[workerId];
676
+
677
+ if (patch.pane !== undefined) entry.pane = patch.pane;
678
+ if (patch.workspace !== undefined) entry.workspace = patch.workspace;
679
+ if (patch.workerSession !== undefined) entry.workerSession = patch.workerSession;
680
+ if (patch.outputFile !== undefined) entry.outputFile = patch.outputFile;
681
+ if (patch.branch !== undefined) entry.branch = patch.branch;
682
+ if (patch.files !== undefined) entry.files = patch.files;
683
+ if (patch.status !== undefined) entry.status = parseWorkerStatus(patch.status);
684
+ if (patch.checkpoint !== undefined) entry.checkpoint = stampCheckpoint(patch.checkpoint);
685
+ entry.lastSeenAt = new Date().toISOString();
686
+
687
+ writeWorkers(located.registry, located.key);
688
+ return entry;
689
+ }
690
+
691
+ /**
692
+ * Record that this worker's work was merged into a base branch.
693
+ *
694
+ * The write goes to the row's own project key rather than to the caller's
695
+ * cwd, so the mark cannot land beside the row instead of on it. Returns null
696
+ * when the worker has no row at all: a merge records what admission already
697
+ * established and never invents an entry, because `spec` and `outputFile` are
698
+ * facts only admission knows.
699
+ */
700
+ export function recordWorkerMerge(
701
+ workerId: string,
702
+ info: { mergeSha: string; cwd?: string },
703
+ ): WorkerEntry | null {
704
+ const located = locateWorker(workerId, info.cwd);
705
+ if (!located) return null;
706
+ const entry = located.registry.workers[workerId];
707
+
708
+ const nowIso = new Date().toISOString();
709
+ // A closed row keeps its terminal status: the merge is recorded on it, but
710
+ // the outcome of the close stands.
711
+ if (!entry.closedAt) entry.status = "merged";
712
+ entry.mergeSha = info.mergeSha;
713
+ entry.mergedAt = nowIso;
714
+ entry.lastSeenAt = nowIso;
715
+ if (!entry.resultAt) entry.resultAt = nowIso;
716
+
717
+ writeWorkers(located.registry, located.key);
718
+ return entry;
719
+ }
720
+
721
+ /**
722
+ * Refuse close-time gate evidence that cannot describe a real run: a
723
+ * completed close with nothing recorded, a non-array value, or an entry whose
724
+ * `cmd` is not a non-empty string or whose `exit` is not a number. Throws on
725
+ * the first violation, before the caller writes anything.
726
+ */
727
+ function assertGateEvidence(
728
+ workerId: string,
729
+ outcome: WorkerOutcome,
730
+ gates: Array<{ cmd: string; exit: number }> | undefined,
731
+ ): void {
732
+ if (gates !== undefined && !Array.isArray(gates)) {
733
+ throw new Error(
734
+ `closeWorker: gates must be an array of { cmd, exit } entries (worker ${workerId})`,
735
+ );
736
+ }
737
+ if (outcome === "completed" && (!gates || gates.length === 0)) {
738
+ throw new Error(
739
+ `closeWorker: a completed close requires non-empty gate evidence (worker ${workerId})`,
740
+ );
741
+ }
742
+ if (!gates) return;
743
+ for (let i = 0; i < gates.length; i++) {
744
+ const gate: unknown = gates[i];
745
+ if (!gate || typeof gate !== "object" || Array.isArray(gate)) {
746
+ throw new Error(
747
+ `closeWorker: gates[${i}] must be an object carrying cmd and exit (worker ${workerId})`,
748
+ );
749
+ }
750
+ const { cmd, exit } = gate as { cmd?: unknown; exit?: unknown };
751
+ if (typeof cmd !== "string" || cmd.trim() === "") {
752
+ throw new Error(
753
+ `closeWorker: gates[${i}].cmd must be a non-empty string (worker ${workerId})`,
754
+ );
755
+ }
756
+ if (typeof exit !== "number" || !Number.isFinite(exit)) {
757
+ throw new Error(`closeWorker: gates[${i}].exit must be a number (worker ${workerId})`);
758
+ }
759
+ }
760
+ }
761
+
762
+ /**
763
+ * Close an entry with a terminal outcome and optional gate evidence.
764
+ * Already-closed entries are left untouched (first close wins); the checks
765
+ * below run only on a close that would actually stamp the row, so a retried
766
+ * close stays a silent no-op and an unknown worker still returns null.
767
+ *
768
+ * A completed close carries evidence: the reporter contract requires a
769
+ * non-empty `gate_evidence` block, and a probe measured this path storing a
770
+ * bare `completed` with no gates at all. That contradiction is refused now,
771
+ * and each provided gate is shape-checked (non-empty `cmd`, numeric `exit`)
772
+ * before any write — a violation leaves the row and the lock table untouched.
773
+ *
774
+ * Releases the worker's file locks: close is terminal, and a lock that
775
+ * survives it blocks the next spawn on the same files. The release runs with
776
+ * the entry's own project key so the lock table read is the same one
777
+ * `acquireLock` wrote; `release-locks` stays the explicit override.
778
+ */
779
+ export function closeWorker(
780
+ workerId: string,
781
+ outcome: WorkerOutcome,
782
+ gates?: Array<{ cmd: string; exit: number }>,
783
+ cwd?: string,
784
+ ): WorkerEntry | null {
785
+ const parsed = parseWorkerOutcome(outcome);
786
+ const located = locateWorker(workerId, cwd);
787
+ if (!located) return null;
788
+ const entry = located.registry.workers[workerId];
789
+ if (entry.closedAt) return entry;
790
+
791
+ assertGateEvidence(workerId, parsed, gates);
792
+
793
+ releaseLock(workerId, located.key);
794
+
795
+ const nowIso = new Date().toISOString();
796
+ entry.status = parsed;
797
+ entry.closedAt = nowIso;
798
+ entry.lastSeenAt = nowIso;
799
+ if (parsed === "completed" && !entry.resultAt) entry.resultAt = nowIso;
800
+ if (gates && gates.length > 0) {
801
+ for (const gate of gates) {
802
+ entry.gates.push({ cmd: gate.cmd, exit: gate.exit, at: nowIso });
803
+ }
804
+ }
805
+
806
+ writeWorkers(located.registry, located.key);
807
+ return entry;
808
+ }
809
+
810
+ // ── Result schema ──────────────────────────────────────────────────────────
811
+
812
+ function tryParseObject(raw: string): Record<string, unknown> | null {
813
+ try {
814
+ const parsed = JSON.parse(raw);
815
+ if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
816
+ return parsed as Record<string, unknown>;
817
+ }
818
+ return null;
819
+ } catch {
820
+ return null;
821
+ }
822
+ }
823
+
824
+ function isResultSchema(obj: Record<string, unknown>): boolean {
825
+ return (
826
+ typeof obj.worker === "string" &&
827
+ obj.worker.length > 0 &&
828
+ typeof obj.spec === "string" &&
829
+ obj.spec.length > 0 &&
830
+ typeof obj.status === "string" &&
831
+ RESULT_SCHEMA_STATUSES.includes(obj.status) &&
832
+ typeof obj.output_file === "string" &&
833
+ obj.output_file.length > 0
834
+ );
835
+ }
836
+
837
+ /**
838
+ * Pull the newest valid result block out of one assistant message, or null.
839
+ * Fenced ```json blocks are tried newest-first, then a bare JSON body.
840
+ */
841
+ function extractResultBlock(content: unknown): Record<string, unknown> | null {
842
+ const texts: string[] = [];
843
+ if (Array.isArray(content)) {
844
+ for (const part of content) {
845
+ if (part && typeof part === "object" && (part as { type?: unknown }).type === "text") {
846
+ const text = (part as { text?: unknown }).text;
847
+ if (typeof text === "string") texts.push(text);
848
+ }
849
+ }
850
+ } else if (typeof content === "string") {
851
+ texts.push(content);
852
+ }
853
+ const joined = texts.join("\n");
854
+
855
+ const blocks = [...joined.matchAll(/```json[ \t]*\r?\n([\s\S]*?)```/gi)].map((m) => m[1]);
856
+ for (let b = blocks.length - 1; b >= 0; b--) {
857
+ const parsed = tryParseObject(blocks[b]);
858
+ if (parsed && isResultSchema(parsed)) return parsed;
859
+ }
860
+ const bare = tryParseObject(joined.trim());
861
+ if (bare && isResultSchema(bare)) return bare;
862
+ return null;
863
+ }
864
+
865
+ /** A located result block plus where it sat in the assistant-message tail. */
866
+ export interface ResultSchemaLocation {
867
+ schema: Record<string, unknown>;
868
+ /** Assistant messages back from the newest (0 = the last assistant message). */
869
+ messageOffset: number;
870
+ }
871
+
872
+ /**
873
+ * Locate the worker's result-schema block in the session file.
874
+ *
875
+ * Scans the last assistant message first. A worker that emits its validated
876
+ * block and then one closing prose line still produced a terminal result, so
877
+ * when that message yields no block the scan continues through at most
878
+ * `maxMessagesBack` assistant messages and takes the most recent valid one.
879
+ * The offset is returned so a caller can distinguish a terminal block (0) from
880
+ * a near-terminal one. No valid block within the window is still a failure.
881
+ */
882
+ export function locateResultSchema(
883
+ sessionPath: string | null,
884
+ maxMessagesBack = RESULT_SCHEMA_MAX_MESSAGES_BACK,
885
+ ): ResultSchemaLocation | null {
886
+ if (!sessionPath || !existsSync(sessionPath)) return null;
887
+ try {
888
+ const lines = readFileSync(sessionPath, "utf-8").split("\n");
889
+ let seen = 0;
890
+ for (let i = lines.length - 1; i >= 0 && seen < maxMessagesBack; i--) {
891
+ const line = lines[i].trim();
892
+ if (!line) continue;
893
+ let record: Record<string, unknown>;
894
+ try {
895
+ record = JSON.parse(line) as Record<string, unknown>;
896
+ } catch {
897
+ continue;
898
+ }
899
+ const message = record.message as { role?: string; content?: unknown } | undefined;
900
+ if (record.type !== "message" || message?.role !== "assistant") continue;
901
+
902
+ const offset = seen;
903
+ seen++;
904
+ const parsed = extractResultBlock(message.content);
905
+ if (parsed) return { schema: parsed, messageOffset: offset };
906
+ }
907
+ return null;
908
+ } catch {
909
+ return null;
910
+ }
911
+ }
912
+
913
+ /** True when the session carries a valid result block within the scan window. */
914
+ export function validateResultSchema(sessionPath: string | null): boolean {
915
+ return locateResultSchema(sessionPath) !== null;
916
+ }
917
+
918
+ // ── Effect evidence ────────────────────────────────────────────────────────
919
+
920
+ /**
921
+ * The phrase a terminal completion without effect evidence is flagged with,
922
+ * in the close-worker result and in check-worker's verdict output. One
923
+ * declared source: the renderers and the tests read it from here, so the
924
+ * phrase cannot drift between the two surfaces.
925
+ */
926
+ export const WORKER_EFFECT_EVIDENCE_FLAG = "no effect evidence";
927
+
928
+ /**
929
+ * The three kinds of effect evidence a terminal completion is judged by. A
930
+ * completion that produced none of them — no deliverable written during the
931
+ * run, no commit landed, no gate reproduced — is the claims-without-artifacts
932
+ * class the flag names.
933
+ */
934
+ export interface WorkerEffectEvidence {
935
+ /** The deliverable exists and its mtime is not before the worker spawned. */
936
+ outputWritten: boolean;
937
+ /** The worker's branch is ahead of its base, or a merge sha is recorded. */
938
+ branchAdvanced: boolean;
939
+ /** At least one recorded gate exited 0. */
940
+ gatePassed: boolean;
941
+ /** True when none of the three kinds holds. */
942
+ none: boolean;
943
+ }
944
+
945
+ /** The facts effect evidence needs that the registry row alone cannot supply. */
946
+ export interface WorkerEffectFacts {
947
+ /** The output file's mtime in ms, or null when it does not exist. */
948
+ outputMtimeMs: number | null;
949
+ /** Commits on the worker's branch beyond its base, or null when uncountable. */
950
+ branchAhead: number | null;
951
+ }
952
+
953
+ /**
954
+ * Judge a terminal completion's effect evidence. Pure over the entry and the
955
+ * gathered facts: the deliverable was written during the run (mtime not
956
+ * before spawnedAt), the branch advanced (ahead >= 1) or a merge sha stands
957
+ * in for it, or a recorded gate exited 0. Any one kind is evidence; none is
958
+ * the flag.
959
+ */
960
+ export function workerEffectEvidence(
961
+ entry: Pick<WorkerEntry, "spawnedAt" | "mergeSha" | "gates">,
962
+ facts: WorkerEffectFacts,
963
+ ): WorkerEffectEvidence {
964
+ const spawnedAt = Date.parse(entry.spawnedAt);
965
+ const outputWritten =
966
+ facts.outputMtimeMs !== null && Number.isFinite(spawnedAt)
967
+ ? facts.outputMtimeMs >= spawnedAt
968
+ : false;
969
+ const branchAdvanced =
970
+ (typeof facts.branchAhead === "number" && facts.branchAhead >= 1) || Boolean(entry.mergeSha);
971
+ const gatePassed = Array.isArray(entry.gates)
972
+ ? entry.gates.some(
973
+ (gate) =>
974
+ gate !== null &&
975
+ typeof gate === "object" &&
976
+ typeof gate.exit === "number" &&
977
+ Number.isFinite(gate.exit) &&
978
+ gate.exit === 0,
979
+ )
980
+ : false;
981
+ return {
982
+ outputWritten,
983
+ branchAdvanced,
984
+ gatePassed,
985
+ none: !outputWritten && !branchAdvanced && !gatePassed,
986
+ };
987
+ }
988
+
989
+ /**
990
+ * Gather the facts effect evidence needs and judge the entry: one stat for
991
+ * the deliverable's mtime, one git rev-list for the branch count. The branch
992
+ * is the entry's own — the worker's lock rows are released before a close is
993
+ * judged, and a merge sha stands in for an advanced branch once the work
994
+ * landed.
995
+ */
996
+ export function workerEffectEvidenceForEntry(
997
+ entry: WorkerEntry,
998
+ opts: { cwd?: string } = {},
999
+ ): WorkerEffectEvidence {
1000
+ return workerEffectEvidence(entry, {
1001
+ outputMtimeMs: fileMtimeMs(entry.outputFile),
1002
+ branchAhead: countBranchAhead(entry.branch, opts.cwd),
1003
+ });
1004
+ }
1005
+
1006
+ // ── Verdict computation ────────────────────────────────────────────────────
1007
+
1008
+ function fileAgeSec(file: string | null, now: number): number | null {
1009
+ if (!file) return null;
1010
+ try {
1011
+ return Math.max(0, Math.round((now - statSync(file).mtimeMs) / 1000));
1012
+ } catch {
1013
+ return null;
1014
+ }
1015
+ }
1016
+
1017
+ /** The file's mtime in ms, or null when it does not exist. */
1018
+ function fileMtimeMs(file: string | null): number | null {
1019
+ if (!file) return null;
1020
+ try {
1021
+ return statSync(file).mtimeMs;
1022
+ } catch {
1023
+ return null;
1024
+ }
1025
+ }
1026
+
1027
+ function countBranchAhead(branch: string | null, cwd?: string): number | null {
1028
+ if (!branch || !cwd) return null;
1029
+ try {
1030
+ const out = execFileSync("git", ["rev-list", "--count", `HEAD..${branch}`], {
1031
+ cwd,
1032
+ encoding: "utf-8",
1033
+ stdio: ["ignore", "pipe", "ignore"],
1034
+ });
1035
+ const count = Number.parseInt(out.trim(), 10);
1036
+ return Number.isFinite(count) ? count : null;
1037
+ } catch {
1038
+ return null;
1039
+ }
1040
+ }
1041
+
1042
+ function summarizeGates(gates: WorkerGate[]): string {
1043
+ if (!gates || gates.length === 0) return "no gates recorded";
1044
+ const failed = gates.filter((gate) => gate.exit !== 0);
1045
+ if (failed.length === 0) return `${gates.length}/${gates.length} passed`;
1046
+ return `${gates.length - failed.length}/${gates.length} passed; failing: ${failed
1047
+ .map((gate) => gate.cmd)
1048
+ .join(", ")}`;
1049
+ }
1050
+
1051
+ function normalizeLiveStatus(raw?: string): "working" | "blocked" | "done" | "idle" | null {
1052
+ if (!raw) return null;
1053
+ const value = raw.trim().toLowerCase();
1054
+ if (value === "working" || value === "blocked" || value === "done" || value === "idle") {
1055
+ return value;
1056
+ }
1057
+ return null;
1058
+ }
1059
+
1060
+ /**
1061
+ * Compute the verdict for a worker entry. `completed` requires the output
1062
+ * file to exist and the result schema to parse (impl spec also requires at
1063
+ * least one commit on the worker branch); a live "done"/"idle" status with
1064
+ * missing evidence is encoded as `false-done`, never `completed`.
1065
+ *
1066
+ * The branch-ahead count uses `entry.branch`, falling back to the branch on
1067
+ * this worker's lock rows (`opts.fallbackBranch`) when the entry has none, so
1068
+ * an entry with a stale null branch does not hide a branch that carries the
1069
+ * worker's commit.
1070
+ *
1071
+ * Liveness, when the parent passes no live state, comes from the recorded
1072
+ * session file's mtime: written within the stall window reads as `working`,
1073
+ * frozen without an output reads as `stalled`, and no recorded session leaves
1074
+ * an admitted row as `admitted`. The pane is never read as liveness.
1075
+ *
1076
+ * A checkpoint changes only the two verdicts that would otherwise leave the
1077
+ * parent guessing: a frozen session, or no session evidence at all, reads as
1078
+ * `resumable` — never as a stale `working` — and the verdict carries the
1079
+ * phase, the last completed step, and the request id to resume under. A
1080
+ * recorded stall or false-done mark and a live status the parent passed stay
1081
+ * as they are: those are decisions and direct observations, not inferences a
1082
+ * checkpoint may override. Evidence of completion still wins over the resume
1083
+ * point.
1084
+ *
1085
+ * A row closed as `completed` also carries its effect evidence: whether the
1086
+ * deliverable was written during the run (mtime not before spawnedAt),
1087
+ * whether the branch advanced or a merge sha is recorded, and whether any
1088
+ * recorded gate exited 0. None of the three is the no-effect-evidence flag;
1089
+ * the flag is a field on the verdict, never a different status, and a row
1090
+ * that is not a terminal completion carries null.
1091
+ */
1092
+ export function evaluateWorker(
1093
+ entry: WorkerEntry,
1094
+ opts: WorkerCheckOptions = {},
1095
+ ): WorkerCheckResult {
1096
+ const now = opts.now ?? Date.now();
1097
+ const stalledAfterSec = opts.stalledAfterSec ?? DEFAULT_STALLED_AFTER_SEC;
1098
+
1099
+ const outputExists =
1100
+ typeof entry.outputFile === "string" &&
1101
+ entry.outputFile.length > 0 &&
1102
+ existsSync(entry.outputFile);
1103
+ const outputAgeSec = outputExists ? fileAgeSec(entry.outputFile, now) : null;
1104
+ const sessionGrowthAgeSec = fileAgeSec(entry.workerSession, now);
1105
+ const locatedResult = locateResultSchema(entry.workerSession);
1106
+ const schemaValid = locatedResult !== null;
1107
+ const resultSchemaMessageOffset = locatedResult?.messageOffset ?? null;
1108
+ const effectiveBranch = entry.branch ?? opts.fallbackBranch ?? null;
1109
+ const branchAhead = countBranchAhead(effectiveBranch, opts.cwd);
1110
+ const gateSummary = summarizeGates(entry.gates);
1111
+ const effectEvidence =
1112
+ entry.closedAt && entry.status === "completed"
1113
+ ? workerEffectEvidence(entry, {
1114
+ outputMtimeMs: fileMtimeMs(entry.outputFile),
1115
+ branchAhead,
1116
+ })
1117
+ : null;
1118
+ // The stall window is read once: a session written inside it is liveness a
1119
+ // checkpoint must not outrank, and it is the only case where a checkpoint
1120
+ // changes the verdict.
1121
+ const frozen = sessionGrowthAgeSec !== null && sessionGrowthAgeSec > stalledAfterSec;
1122
+ const requestId = entry.requestId ?? null;
1123
+ const checkpoint = entry.checkpoint ?? null;
1124
+
1125
+ const base = {
1126
+ workerId: entry.workerId,
1127
+ outputFile: entry.outputFile,
1128
+ outputExists,
1129
+ outputAgeSec,
1130
+ sessionGrowthAgeSec,
1131
+ branchAhead,
1132
+ schemaValid,
1133
+ resultSchemaMessageOffset,
1134
+ requestId,
1135
+ checkpoint,
1136
+ gateSummary,
1137
+ effectEvidence,
1138
+ };
1139
+
1140
+ const blockers: string[] = [];
1141
+ if (!outputExists) blockers.push("output file missing");
1142
+ if (!schemaValid) blockers.push("result schema missing");
1143
+ if (entry.spec === "impl" && !(typeof branchAhead === "number" && branchAhead > 0)) {
1144
+ blockers.push("no commit on worker branch");
1145
+ }
1146
+ const commitNote = entry.spec === "impl" ? " + commit present" : "";
1147
+
1148
+ if (entry.closedAt) {
1149
+ return {
1150
+ ...base,
1151
+ status: "closed",
1152
+ reason: `closed ${entry.closedAt} with outcome ${entry.status}`,
1153
+ };
1154
+ }
1155
+ if (entry.status === "error") {
1156
+ return { ...base, status: "error", reason: "registry marked error" };
1157
+ }
1158
+
1159
+ const live = normalizeLiveStatus(opts.liveStatus);
1160
+ if (live === "working") {
1161
+ return { ...base, status: "working", reason: "live status working" };
1162
+ }
1163
+ if (live === "blocked") {
1164
+ return { ...base, status: "stalled", reason: "live status blocked" };
1165
+ }
1166
+ if (live === "done" || live === "idle") {
1167
+ if (blockers.length === 0) {
1168
+ return {
1169
+ ...base,
1170
+ status: "completed",
1171
+ reason: `live status ${live}; output + schema verified${commitNote}`,
1172
+ };
1173
+ }
1174
+ return {
1175
+ ...base,
1176
+ status: "false-done",
1177
+ reason: `live status ${live} but ${blockers.join("; ")}`,
1178
+ };
1179
+ }
1180
+
1181
+ // No usable live status: evidence wins over registry declarations.
1182
+ if (blockers.length === 0) {
1183
+ return { ...base, status: "completed", reason: `output + schema verified${commitNote}` };
1184
+ }
1185
+ if (entry.status === "stalled") {
1186
+ return {
1187
+ ...base,
1188
+ status: "stalled",
1189
+ reason: `registry marked stalled; ${blockers.join("; ")}`,
1190
+ };
1191
+ }
1192
+ if (entry.status === "false-done") {
1193
+ return {
1194
+ ...base,
1195
+ status: "false-done",
1196
+ reason: `registry marked false-done; ${blockers.join("; ")}`,
1197
+ };
1198
+ }
1199
+ if (entry.status === "merged") {
1200
+ // The work landed, so the row is not "in flight": an unclosed merged row
1201
+ // reports what is still missing from its record instead.
1202
+ return {
1203
+ ...base,
1204
+ status: "merged",
1205
+ reason: `merged at ${entry.mergedAt ?? "unknown"} but ${blockers.join("; ")}`,
1206
+ };
1207
+ }
1208
+ // A frozen session is where a crash leaves a row. With a checkpoint on disk
1209
+ // the resume point survives the crash, so the row reads as resumable rather
1210
+ // than stalled: where the work stopped is on record, not guessed.
1211
+ if (frozen) {
1212
+ if (checkpoint) {
1213
+ return {
1214
+ ...base,
1215
+ status: "resumable",
1216
+ reason:
1217
+ `no live status; session frozen for ${sessionGrowthAgeSec}s` +
1218
+ `${outputExists ? "" : " with no output"}; resume from checkpoint ` +
1219
+ `${checkpoint.phase}/${checkpoint.step} (${checkpoint.at})` +
1220
+ `${requestId ? ` under requestId ${requestId}` : ""}`,
1221
+ };
1222
+ }
1223
+ if (!outputExists) {
1224
+ return {
1225
+ ...base,
1226
+ status: "stalled",
1227
+ reason: `worker session frozen for ${sessionGrowthAgeSec}s with no output`,
1228
+ };
1229
+ }
1230
+ }
1231
+ // A recorded session file that is still being written is the one liveness
1232
+ // signal the registry owns: the parent does not have to hand a live state to
1233
+ // check-worker before an admitted row reads as more than "not yet observed".
1234
+ // The pane is deliberately not consulted: it is a place to look, not proof
1235
+ // that a process runs there, and the tool never queries herdr itself.
1236
+ if (sessionGrowthAgeSec !== null) {
1237
+ return {
1238
+ ...base,
1239
+ status: "working",
1240
+ reason: `session file active ${sessionGrowthAgeSec}s ago${entry.pane ? ` (pane ${entry.pane})` : ""}`,
1241
+ };
1242
+ }
1243
+ // No session handle, or the recorded one is gone: there is no liveness
1244
+ // evidence at all. A checkpoint still says where the work stopped, so the
1245
+ // row reads as resumable; without one it is only "not yet observed".
1246
+ if (checkpoint) {
1247
+ return {
1248
+ ...base,
1249
+ status: "resumable",
1250
+ reason:
1251
+ `no live status and ${
1252
+ entry.workerSession
1253
+ ? `recorded session ${entry.workerSession} is gone`
1254
+ : "no session handle recorded (register-worker/update-worker `workerSession`)"
1255
+ }; resume from checkpoint ${checkpoint.phase}/${checkpoint.step} (${checkpoint.at})` +
1256
+ `${requestId ? ` under requestId ${requestId}` : ""}`,
1257
+ };
1258
+ }
1259
+ if (entry.status === "admitted") {
1260
+ return {
1261
+ ...base,
1262
+ status: "admitted",
1263
+ reason:
1264
+ "no live status and no session handle recorded (register-worker/update-worker `workerSession`); not yet observed running",
1265
+ };
1266
+ }
1267
+ return { ...base, status: "working", reason: "no live status; in flight" };
1268
+ }
1269
+
1270
+ /**
1271
+ * The branch recorded on this worker's lock rows in the given project, or
1272
+ * undefined. Used as the branch fallback when the registry entry has none:
1273
+ * every lock row carries the branch `acquireLock` was given.
1274
+ */
1275
+ function lockBranchFor(workerId: string, projectCwd: string): string | undefined {
1276
+ for (const lock of Object.values(getAllLocks(projectCwd))) {
1277
+ if (lock.workerId === workerId) return lock.branch;
1278
+ }
1279
+ return undefined;
1280
+ }
1281
+
1282
+ /**
1283
+ * Read the registry and compute the verdict; null when the worker is unknown.
1284
+ * Resolves the branch fallback from the lock table at the entry's own project
1285
+ * key, so a worker located across registries still reads its own locks.
1286
+ */
1287
+ export function checkWorker(
1288
+ workerId: string,
1289
+ opts: WorkerCheckOptions = {},
1290
+ ): WorkerCheckResult | null {
1291
+ const located = locateWorker(workerId, opts.cwd);
1292
+ if (!located) return null;
1293
+ const fallbackBranch = opts.fallbackBranch ?? lockBranchFor(workerId, located.key);
1294
+ return evaluateWorker(located.registry.workers[workerId], { ...opts, fallbackBranch });
1295
+ }
1296
+
1297
+ // ── Fleet statistics ───────────────────────────────────────────────────────
1298
+
1299
+ /** Spawn→result latency over the entries that recorded a result time. */
1300
+ export interface WorkerLatencySummary {
1301
+ /** How many entries contributed a delta; the sample the median is over. */
1302
+ sample: number;
1303
+ /** Median delta in milliseconds, or null when the sample is empty. */
1304
+ medianMs: number | null;
1305
+ minMs: number | null;
1306
+ maxMs: number | null;
1307
+ }
1308
+
1309
+ /** A registry's fleet numbers: what a seat needs to judge its own health. */
1310
+ export interface WorkerStats {
1311
+ /** Every row in the registry. */
1312
+ total: number;
1313
+ /** Rows with no close time — still in flight, or never closed. */
1314
+ live: number;
1315
+ /** Rows with a close time; the denominator of the completion rate. */
1316
+ closed: number;
1317
+ /** Closed rows whose terminal status is `completed`. */
1318
+ completed: number;
1319
+ /** completed / closed, or null when nothing is closed — no rate to state. */
1320
+ completionRate: number | null;
1321
+ /** Spawn→result latency; the sample is stated, never implied by a number. */
1322
+ latency: WorkerLatencySummary;
1323
+ /** Duplicate admissions refused across all rows, summed from their records. */
1324
+ admissionRefusals: number;
1325
+ }
1326
+
1327
+ /** Median of a non-empty list; the mean of the middle pair on an even count. */
1328
+ function median(values: number[]): number | null {
1329
+ if (values.length === 0) return null;
1330
+ const sorted = [...values].sort((a, b) => a - b);
1331
+ const mid = Math.floor(sorted.length / 2);
1332
+ return sorted.length % 2 === 0 ? Math.round((sorted[mid - 1] + sorted[mid]) / 2) : sorted[mid];
1333
+ }
1334
+
1335
+ /**
1336
+ * The spawn→result delta an entry recorded, or null when it has none. A row
1337
+ * with no result time — a worker still in flight, or one that closed without a
1338
+ * result — contributes nothing: it must not enter the median. A malformed or
1339
+ * backwards pair is no delta either.
1340
+ */
1341
+ function resultLatencyMs(entry: WorkerEntry): number | null {
1342
+ if (!entry.spawnedAt || !entry.resultAt) return null;
1343
+ const spawned = Date.parse(entry.spawnedAt);
1344
+ const result = Date.parse(entry.resultAt);
1345
+ if (!Number.isFinite(spawned) || !Number.isFinite(result)) return null;
1346
+ const delta = result - spawned;
1347
+ return delta >= 0 ? delta : null;
1348
+ }
1349
+
1350
+ /**
1351
+ * Compute a registry's fleet statistics. Pure over the registry value: no
1352
+ * clock, no disk, no verdicts. The latency sample is the entries that recorded
1353
+ * a result time, so an in-flight row is excluded rather than counted at its
1354
+ * close; the completion rate is over closed rows. Every number states its own
1355
+ * denominator, so a small sample reads as small.
1356
+ */
1357
+ export function computeWorkerStats(registry: WorkerRegistry): WorkerStats {
1358
+ const entries = Object.values(registry.workers);
1359
+ const closed = entries.filter((entry) => Boolean(entry.closedAt));
1360
+ const completed = closed.filter((entry) => entry.status === "completed").length;
1361
+ const latencies: number[] = [];
1362
+ let admissionRefusals = 0;
1363
+ for (const entry of entries) {
1364
+ const delta = resultLatencyMs(entry);
1365
+ if (delta !== null) latencies.push(delta);
1366
+ if (Array.isArray(entry.admissionRefusals)) admissionRefusals += entry.admissionRefusals.length;
1367
+ }
1368
+ return {
1369
+ total: entries.length,
1370
+ live: entries.length - closed.length,
1371
+ closed: closed.length,
1372
+ completed,
1373
+ completionRate: closed.length === 0 ? null : completed / closed.length,
1374
+ latency: {
1375
+ sample: latencies.length,
1376
+ medianMs: median(latencies),
1377
+ minMs: latencies.length === 0 ? null : Math.min(...latencies),
1378
+ maxMs: latencies.length === 0 ? null : Math.max(...latencies),
1379
+ },
1380
+ admissionRefusals,
1381
+ };
1382
+ }