ctxtop 4.1.0 → 4.1.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 (318) hide show
  1. package/.antigravity-plugin/plugin.json +1 -1
  2. package/.claude-plugin/plugin.json +21 -18
  3. package/CHECKSUMS.sha256 +51 -44
  4. package/LICENSE +27 -27
  5. package/README.md +90 -56
  6. package/SECURITY.md +7 -1
  7. package/assets/hero-demo.svg +1 -1
  8. package/bin/ctxtop.mjs +267 -54
  9. package/config/modelCatalog.json +847 -273
  10. package/hooks/handlers/hookIpcClient.mjs +8 -4
  11. package/hooks/handlers/post-model-switch.mjs +39 -2
  12. package/hooks/handlers/post-tool-use-core.mjs +394 -0
  13. package/hooks/handlers/post-tool-use.mjs +54 -321
  14. package/hooks/handlers/pre-model-switch.mjs +115 -5
  15. package/hooks/handlers/pre-tool-use-core.mjs +680 -0
  16. package/hooks/handlers/pre-tool-use.mjs +61 -571
  17. package/hooks/handlers/stop-gate.mjs +20 -8
  18. package/hooks/handlers/user-prompt-submit.mjs +111 -2
  19. package/hooks/post_tool_use.mjs +17 -4
  20. package/hooks/pre_tool_use.mjs +84 -54
  21. package/hooks.json +56 -56
  22. package/package.json +4 -3
  23. package/packages/antigravity/package.json +10 -3
  24. package/packages/antigravity/src/adapter.mjs +109 -0
  25. package/packages/antigravity/src/index.mjs +7 -1
  26. package/packages/claude-code/package.json +10 -3
  27. package/packages/claude-code/src/adapter.mjs +194 -0
  28. package/packages/claude-code/src/index.mjs +8 -2
  29. package/packages/claude-code/src/register.js +726 -0
  30. package/packages/core/package.json +6 -2
  31. package/packages/core/src/catalog/detectorCatalog.mjs +558 -0
  32. package/packages/core/src/catalog/index.mjs +1 -0
  33. package/packages/core/src/catalog/safeguardGuide.mjs +412 -0
  34. package/packages/core/src/coach/cacheGravityRouter.mjs +1547 -0
  35. package/packages/core/src/coach/effortShiftDetector.mjs +316 -0
  36. package/packages/core/src/coach/microSkills.mjs +1 -0
  37. package/packages/core/src/coach/promptHygieneGovernor.mjs +1 -0
  38. package/packages/core/src/coach/repoCalibration.mjs +254 -0
  39. package/packages/core/src/coach/resumeToolsetAuditor.mjs +321 -0
  40. package/packages/core/src/coach/savedQuotaLedger.mjs +527 -0
  41. package/packages/core/src/coach/smartCompactAdvisor.mjs +339 -0
  42. package/packages/core/src/coach/stateBatonHydrator.mjs +810 -0
  43. package/packages/core/src/coach/ttlWatchdog.mjs +464 -0
  44. package/packages/core/src/config/anthropicModelCatalog.json +607 -0
  45. package/packages/core/src/config/catalogLoader.mjs +1271 -0
  46. package/packages/core/src/config/horizonConfig.mjs +1055 -0
  47. package/packages/core/src/control/callTree.mjs +338 -0
  48. package/packages/core/src/control/coachLatches.mjs +126 -0
  49. package/packages/core/src/control/controlStateMachine.mjs +205 -0
  50. package/packages/core/src/control/index.mjs +49 -0
  51. package/packages/core/src/control/swarmWorktree.mjs +109 -0
  52. package/packages/core/src/control/toolSuspension.mjs +197 -0
  53. package/packages/core/src/diagnostics/drift_guard.mjs +382 -0
  54. package/packages/core/src/diagnostics/index.mjs +9 -0
  55. package/packages/core/src/diagnostics/micro_skills.mjs +471 -0
  56. package/packages/core/src/diagnostics/prompt_hygiene_governor.mjs +888 -0
  57. package/packages/core/src/economics/billingBlocks.mjs +251 -0
  58. package/packages/core/src/economics/cacheGravity.mjs +371 -0
  59. package/packages/core/src/economics/cliffBreaker.mjs +256 -0
  60. package/packages/core/src/economics/driftLatency.mjs +433 -0
  61. package/packages/core/src/economics/dualTtl.mjs +198 -0
  62. package/packages/core/src/economics/index.mjs +47 -0
  63. package/packages/core/src/economics/retentionRadar.mjs +348 -0
  64. package/packages/core/src/economics/shadowAutoModel.mjs +228 -0
  65. package/packages/core/src/guards/bucketBAlphaBeta.mjs +860 -0
  66. package/packages/core/src/guards/bucketBGamma.mjs +442 -0
  67. package/packages/core/src/guards/bucketBHeuristics.mjs +37 -0
  68. package/packages/core/src/guards/circuitBreakers.mjs +1202 -0
  69. package/packages/core/src/guards/det01_03_shell_secret.mjs +1184 -0
  70. package/packages/core/src/guards/det04_12_thrash_rot.mjs +572 -0
  71. package/packages/core/src/guards/det13_20_mcp_scope.mjs +913 -0
  72. package/packages/core/src/guards/docIndexCore.mjs +446 -0
  73. package/packages/core/src/guards/losslessPostSanitizer.mjs +317 -0
  74. package/packages/core/src/guards/slopsquatGate.mjs +551 -0
  75. package/packages/core/src/index.js +27 -0
  76. package/packages/core/src/index.mjs +25 -1
  77. package/packages/core/src/telemetry/otelExporter.mjs +187 -0
  78. package/packages/core/src/telemetry/scopeLockRegistry.mjs +522 -0
  79. package/packages/core/src/telemetry/sprintMetrics.mjs +327 -0
  80. package/packages/core/src/telemetry/swarmTopology.mjs +152 -0
  81. package/packages/core/src/telemetry/telemetryBridge.mjs +1232 -0
  82. package/packages/core/src/ui/brailleSparkline.mjs +142 -0
  83. package/packages/core/src/ui/costRadarSvg.mjs +276 -0
  84. package/packages/core/src/ui/horizonGrid.mjs +475 -0
  85. package/packages/core/src/ui/horizonPanelHtml.mjs +1502 -0
  86. package/packages/core/src/ui/modViews.mjs +1558 -0
  87. package/packages/core/src/ui/pdfReceiptGenerator.mjs +329 -0
  88. package/packages/core/src/ustf/index.mjs +7 -0
  89. package/packages/core/src/ustf/normalizer.mjs +512 -0
  90. package/packages/core/src/ustf/schema.mjs +186 -0
  91. package/packages/core/src/utils/runtime.mjs +962 -0
  92. package/packages/engine-node/package.json +6 -2
  93. package/packages/engine-node/src/db/index.mjs +58 -0
  94. package/packages/engine-node/src/db/jsonl_fallback.mjs +184 -0
  95. package/packages/engine-node/src/db/probe.mjs +342 -0
  96. package/packages/engine-node/src/db/sqlite_wrapper.mjs +122 -0
  97. package/packages/engine-node/src/index.mjs +11 -1
  98. package/packages/engine-node/src/ipc/client.mjs +447 -0
  99. package/packages/engine-node/src/ipc/fast_client.mjs +191 -0
  100. package/packages/engine-node/src/ipc/index.mjs +24 -0
  101. package/packages/engine-node/src/ipc/protocol.mjs +177 -0
  102. package/packages/engine-node/src/ipc/server.mjs +445 -0
  103. package/packages/engine-node/src/multi_host_mcp.mjs +168 -0
  104. package/packages/engine-node/src/offloader/index.mjs +6 -0
  105. package/packages/engine-node/src/offloader/tool_offloader.mjs +241 -0
  106. package/packages/engine-node/src/rsl/index.mjs +3 -0
  107. package/packages/engine-node/src/sensors/blindspots.mjs +376 -0
  108. package/packages/engine-node/src/sensors/git_merge_tree.mjs +223 -0
  109. package/packages/engine-node/src/sensors/index.mjs +7 -0
  110. package/packages/engine-node/src/vendor/config/default_flightcheck.json +133 -0
  111. package/packages/engine-node/src/vendor/config/modelCatalog.json +1359 -0
  112. package/packages/engine-node/src/vendor/config/platformQuirks.json +19 -0
  113. package/packages/engine-node/src/vendor/core/atomic_io.mjs +124 -0
  114. package/packages/engine-node/src/vendor/core/constants.mjs +2150 -0
  115. package/packages/engine-node/src/vendor/core/doc_indexer.mjs +338 -0
  116. package/packages/engine-node/src/vendor/core/rsl_clash_auditor.mjs +423 -0
  117. package/packages/engine-node/src/vendor/core/rsl_distiller.mjs +394 -0
  118. package/packages/engine-node/src/vendor/core/rsl_ledger.mjs +1029 -0
  119. package/packages/engine-node/src/vendor/core/rsl_triage.mjs +1051 -0
  120. package/packages/engine-node/src/vendor/core/shield_manager.mjs +1417 -0
  121. package/packages/engine-node/src/vendor/core-isomorphic/catalog/detectorCatalog.mjs +558 -0
  122. package/packages/engine-node/src/vendor/core-isomorphic/catalog/index.mjs +1 -0
  123. package/packages/engine-node/src/vendor/core-isomorphic/catalog/safeguardGuide.mjs +412 -0
  124. package/packages/engine-node/src/vendor/core-isomorphic/coach/cacheGravityRouter.mjs +1547 -0
  125. package/packages/engine-node/src/vendor/core-isomorphic/coach/effortShiftDetector.mjs +316 -0
  126. package/packages/engine-node/src/vendor/core-isomorphic/coach/microSkills.mjs +1 -0
  127. package/packages/engine-node/src/vendor/core-isomorphic/coach/promptHygieneGovernor.mjs +1 -0
  128. package/packages/engine-node/src/vendor/core-isomorphic/coach/repoCalibration.mjs +254 -0
  129. package/packages/engine-node/src/vendor/core-isomorphic/coach/resumeToolsetAuditor.mjs +321 -0
  130. package/packages/engine-node/src/vendor/core-isomorphic/coach/savedQuotaLedger.mjs +527 -0
  131. package/packages/engine-node/src/vendor/core-isomorphic/coach/smartCompactAdvisor.mjs +339 -0
  132. package/packages/engine-node/src/vendor/core-isomorphic/coach/stateBatonHydrator.mjs +810 -0
  133. package/packages/engine-node/src/vendor/core-isomorphic/coach/ttlWatchdog.mjs +464 -0
  134. package/packages/engine-node/src/vendor/core-isomorphic/config/anthropicModelCatalog.json +607 -0
  135. package/packages/engine-node/src/vendor/core-isomorphic/config/catalogLoader.mjs +1271 -0
  136. package/packages/engine-node/src/vendor/core-isomorphic/config/horizonConfig.mjs +1055 -0
  137. package/packages/engine-node/src/vendor/core-isomorphic/control/callTree.mjs +338 -0
  138. package/packages/engine-node/src/vendor/core-isomorphic/control/coachLatches.mjs +126 -0
  139. package/packages/engine-node/src/vendor/core-isomorphic/control/controlStateMachine.mjs +205 -0
  140. package/packages/engine-node/src/vendor/core-isomorphic/control/index.mjs +49 -0
  141. package/packages/engine-node/src/vendor/core-isomorphic/control/swarmWorktree.mjs +109 -0
  142. package/packages/engine-node/src/vendor/core-isomorphic/control/toolSuspension.mjs +197 -0
  143. package/packages/engine-node/src/vendor/core-isomorphic/diagnostics/drift_guard.mjs +382 -0
  144. package/packages/engine-node/src/vendor/core-isomorphic/diagnostics/index.mjs +9 -0
  145. package/packages/engine-node/src/vendor/core-isomorphic/diagnostics/micro_skills.mjs +471 -0
  146. package/packages/engine-node/src/vendor/core-isomorphic/diagnostics/prompt_hygiene_governor.mjs +888 -0
  147. package/packages/engine-node/src/vendor/core-isomorphic/economics/billingBlocks.mjs +251 -0
  148. package/packages/engine-node/src/vendor/core-isomorphic/economics/cacheGravity.mjs +371 -0
  149. package/packages/engine-node/src/vendor/core-isomorphic/economics/cliffBreaker.mjs +256 -0
  150. package/packages/engine-node/src/vendor/core-isomorphic/economics/driftLatency.mjs +433 -0
  151. package/packages/engine-node/src/vendor/core-isomorphic/economics/dualTtl.mjs +198 -0
  152. package/packages/engine-node/src/vendor/core-isomorphic/economics/index.mjs +47 -0
  153. package/packages/engine-node/src/vendor/core-isomorphic/economics/retentionRadar.mjs +348 -0
  154. package/packages/engine-node/src/vendor/core-isomorphic/economics/shadowAutoModel.mjs +228 -0
  155. package/packages/engine-node/src/vendor/core-isomorphic/guards/bucketBAlphaBeta.mjs +860 -0
  156. package/packages/engine-node/src/vendor/core-isomorphic/guards/bucketBGamma.mjs +442 -0
  157. package/packages/engine-node/src/vendor/core-isomorphic/guards/bucketBHeuristics.mjs +37 -0
  158. package/packages/engine-node/src/vendor/core-isomorphic/guards/circuitBreakers.mjs +1202 -0
  159. package/packages/engine-node/src/vendor/core-isomorphic/guards/det01_03_shell_secret.mjs +1184 -0
  160. package/packages/engine-node/src/vendor/core-isomorphic/guards/det04_12_thrash_rot.mjs +572 -0
  161. package/packages/engine-node/src/vendor/core-isomorphic/guards/det13_20_mcp_scope.mjs +913 -0
  162. package/packages/engine-node/src/vendor/core-isomorphic/guards/docIndexCore.mjs +446 -0
  163. package/packages/engine-node/src/vendor/core-isomorphic/guards/losslessPostSanitizer.mjs +317 -0
  164. package/packages/engine-node/src/vendor/core-isomorphic/guards/slopsquatGate.mjs +551 -0
  165. package/packages/engine-node/src/vendor/core-isomorphic/index.js +27 -0
  166. package/packages/engine-node/src/vendor/core-isomorphic/telemetry/otelExporter.mjs +187 -0
  167. package/packages/engine-node/src/vendor/core-isomorphic/telemetry/scopeLockRegistry.mjs +522 -0
  168. package/packages/engine-node/src/vendor/core-isomorphic/telemetry/sprintMetrics.mjs +327 -0
  169. package/packages/engine-node/src/vendor/core-isomorphic/telemetry/swarmTopology.mjs +152 -0
  170. package/packages/engine-node/src/vendor/core-isomorphic/telemetry/telemetryBridge.mjs +1232 -0
  171. package/packages/engine-node/src/vendor/core-isomorphic/ui/brailleSparkline.mjs +142 -0
  172. package/packages/engine-node/src/vendor/core-isomorphic/ui/costRadarSvg.mjs +276 -0
  173. package/packages/engine-node/src/vendor/core-isomorphic/ui/horizonGrid.mjs +475 -0
  174. package/packages/engine-node/src/vendor/core-isomorphic/ui/horizonPanelHtml.mjs +1502 -0
  175. package/packages/engine-node/src/vendor/core-isomorphic/ui/modViews.mjs +1558 -0
  176. package/packages/engine-node/src/vendor/core-isomorphic/ui/pdfReceiptGenerator.mjs +329 -0
  177. package/packages/engine-node/src/vendor/core-isomorphic/ustf/index.mjs +7 -0
  178. package/packages/engine-node/src/vendor/core-isomorphic/ustf/normalizer.mjs +512 -0
  179. package/packages/engine-node/src/vendor/core-isomorphic/ustf/schema.mjs +186 -0
  180. package/packages/engine-node/src/vendor/core-isomorphic/utils/runtime.mjs +962 -0
  181. package/packages/mcp/package.json +7 -3
  182. package/packages/mcp/src/server.mjs +115 -14
  183. package/packages/mcp/src/vendor/config/default_flightcheck.json +133 -0
  184. package/packages/mcp/src/vendor/config/modelCatalog.json +1359 -0
  185. package/packages/mcp/src/vendor/config/platformQuirks.json +19 -0
  186. package/packages/mcp/src/vendor/core/atomic_io.mjs +124 -0
  187. package/packages/mcp/src/vendor/core/coach/saved_quota_ledger.mjs +615 -0
  188. package/packages/mcp/src/vendor/core/constants.mjs +2150 -0
  189. package/packages/mcp/src/vendor/core/doc_indexer.mjs +338 -0
  190. package/packages/mcp/src/vendor/core/fts5_output_compressor.mjs +596 -0
  191. package/packages/mcp/src/vendor/core/hook_diagnostics.mjs +158 -0
  192. package/packages/mcp/src/vendor/core/paths.mjs +311 -0
  193. package/packages/mcp/src/vendor/core/session_auditor.mjs +1109 -0
  194. package/packages/mcp/src/vendor/core/sqlite_client.mjs +289 -0
  195. package/packages/mcp/src/vendor/core/telemetry/scope_lock_registry.mjs +578 -0
  196. package/packages/mcp/src/vendor/core-isomorphic/catalog/detectorCatalog.mjs +558 -0
  197. package/packages/mcp/src/vendor/core-isomorphic/catalog/index.mjs +1 -0
  198. package/packages/mcp/src/vendor/core-isomorphic/catalog/safeguardGuide.mjs +412 -0
  199. package/packages/mcp/src/vendor/core-isomorphic/coach/cacheGravityRouter.mjs +1547 -0
  200. package/packages/mcp/src/vendor/core-isomorphic/coach/effortShiftDetector.mjs +316 -0
  201. package/packages/mcp/src/vendor/core-isomorphic/coach/microSkills.mjs +1 -0
  202. package/packages/mcp/src/vendor/core-isomorphic/coach/promptHygieneGovernor.mjs +1 -0
  203. package/packages/mcp/src/vendor/core-isomorphic/coach/repoCalibration.mjs +254 -0
  204. package/packages/mcp/src/vendor/core-isomorphic/coach/resumeToolsetAuditor.mjs +321 -0
  205. package/packages/mcp/src/vendor/core-isomorphic/coach/savedQuotaLedger.mjs +527 -0
  206. package/packages/mcp/src/vendor/core-isomorphic/coach/smartCompactAdvisor.mjs +339 -0
  207. package/packages/mcp/src/vendor/core-isomorphic/coach/stateBatonHydrator.mjs +810 -0
  208. package/packages/mcp/src/vendor/core-isomorphic/coach/ttlWatchdog.mjs +464 -0
  209. package/packages/mcp/src/vendor/core-isomorphic/config/anthropicModelCatalog.json +607 -0
  210. package/packages/mcp/src/vendor/core-isomorphic/config/catalogLoader.mjs +1271 -0
  211. package/packages/mcp/src/vendor/core-isomorphic/config/horizonConfig.mjs +1055 -0
  212. package/packages/mcp/src/vendor/core-isomorphic/control/callTree.mjs +338 -0
  213. package/packages/mcp/src/vendor/core-isomorphic/control/coachLatches.mjs +126 -0
  214. package/packages/mcp/src/vendor/core-isomorphic/control/controlStateMachine.mjs +205 -0
  215. package/packages/mcp/src/vendor/core-isomorphic/control/index.mjs +49 -0
  216. package/packages/mcp/src/vendor/core-isomorphic/control/swarmWorktree.mjs +109 -0
  217. package/packages/mcp/src/vendor/core-isomorphic/control/toolSuspension.mjs +197 -0
  218. package/packages/mcp/src/vendor/core-isomorphic/diagnostics/drift_guard.mjs +382 -0
  219. package/packages/mcp/src/vendor/core-isomorphic/diagnostics/index.mjs +9 -0
  220. package/packages/mcp/src/vendor/core-isomorphic/diagnostics/micro_skills.mjs +471 -0
  221. package/packages/mcp/src/vendor/core-isomorphic/diagnostics/prompt_hygiene_governor.mjs +888 -0
  222. package/packages/mcp/src/vendor/core-isomorphic/economics/billingBlocks.mjs +251 -0
  223. package/packages/mcp/src/vendor/core-isomorphic/economics/cacheGravity.mjs +371 -0
  224. package/packages/mcp/src/vendor/core-isomorphic/economics/cliffBreaker.mjs +256 -0
  225. package/packages/mcp/src/vendor/core-isomorphic/economics/driftLatency.mjs +433 -0
  226. package/packages/mcp/src/vendor/core-isomorphic/economics/dualTtl.mjs +198 -0
  227. package/packages/mcp/src/vendor/core-isomorphic/economics/index.mjs +47 -0
  228. package/packages/mcp/src/vendor/core-isomorphic/economics/retentionRadar.mjs +348 -0
  229. package/packages/mcp/src/vendor/core-isomorphic/economics/shadowAutoModel.mjs +228 -0
  230. package/packages/mcp/src/vendor/core-isomorphic/guards/bucketBAlphaBeta.mjs +860 -0
  231. package/packages/mcp/src/vendor/core-isomorphic/guards/bucketBGamma.mjs +442 -0
  232. package/packages/mcp/src/vendor/core-isomorphic/guards/bucketBHeuristics.mjs +37 -0
  233. package/packages/mcp/src/vendor/core-isomorphic/guards/circuitBreakers.mjs +1202 -0
  234. package/packages/mcp/src/vendor/core-isomorphic/guards/det01_03_shell_secret.mjs +1184 -0
  235. package/packages/mcp/src/vendor/core-isomorphic/guards/det04_12_thrash_rot.mjs +572 -0
  236. package/packages/mcp/src/vendor/core-isomorphic/guards/det13_20_mcp_scope.mjs +913 -0
  237. package/packages/mcp/src/vendor/core-isomorphic/guards/docIndexCore.mjs +446 -0
  238. package/packages/mcp/src/vendor/core-isomorphic/guards/losslessPostSanitizer.mjs +317 -0
  239. package/packages/mcp/src/vendor/core-isomorphic/guards/slopsquatGate.mjs +551 -0
  240. package/packages/mcp/src/vendor/core-isomorphic/index.js +27 -0
  241. package/packages/mcp/src/vendor/core-isomorphic/telemetry/otelExporter.mjs +187 -0
  242. package/packages/mcp/src/vendor/core-isomorphic/telemetry/scopeLockRegistry.mjs +522 -0
  243. package/packages/mcp/src/vendor/core-isomorphic/telemetry/sprintMetrics.mjs +327 -0
  244. package/packages/mcp/src/vendor/core-isomorphic/telemetry/swarmTopology.mjs +152 -0
  245. package/packages/mcp/src/vendor/core-isomorphic/telemetry/telemetryBridge.mjs +1232 -0
  246. package/packages/mcp/src/vendor/core-isomorphic/ui/brailleSparkline.mjs +142 -0
  247. package/packages/mcp/src/vendor/core-isomorphic/ui/costRadarSvg.mjs +276 -0
  248. package/packages/mcp/src/vendor/core-isomorphic/ui/horizonGrid.mjs +475 -0
  249. package/packages/mcp/src/vendor/core-isomorphic/ui/horizonPanelHtml.mjs +1502 -0
  250. package/packages/mcp/src/vendor/core-isomorphic/ui/modViews.mjs +1558 -0
  251. package/packages/mcp/src/vendor/core-isomorphic/ui/pdfReceiptGenerator.mjs +329 -0
  252. package/packages/mcp/src/vendor/core-isomorphic/ustf/index.mjs +7 -0
  253. package/packages/mcp/src/vendor/core-isomorphic/ustf/normalizer.mjs +512 -0
  254. package/packages/mcp/src/vendor/core-isomorphic/ustf/schema.mjs +186 -0
  255. package/packages/mcp/src/vendor/core-isomorphic/utils/runtime.mjs +962 -0
  256. package/packages/mcp/src/vendor/engine-node/db/probe.mjs +342 -0
  257. package/packages/mcp/src/vendor/pro/pro_license.mjs +547 -0
  258. package/packages/pro/package.json +23 -16
  259. package/packages/pro/src/index.mjs +9 -3
  260. package/packages/pro/src/pro_license.mjs +547 -0
  261. package/packages/pro/src/team_finops_pack.mjs +241 -241
  262. package/packages/pro/workers/polar_webhook_worker.mjs +219 -215
  263. package/plugin.json +1 -1
  264. package/sidecars/horizon-daemon/server.mjs +482 -44
  265. package/src/cli/doctor.mjs +11 -2
  266. package/src/cli/horizon_hud.mjs +31 -15
  267. package/src/cli/init.mjs +46 -13
  268. package/src/config/modelCatalog.json +886 -231
  269. package/src/core/classifier.mjs +25 -11
  270. package/src/core/coach/circuit_breakers.mjs +84 -6
  271. package/src/core/coach/task_quota_router.mjs +8 -0
  272. package/src/core/code_fold_lite.mjs +169 -0
  273. package/src/core/config.mjs +44 -0
  274. package/src/core/constants.mjs +175 -12
  275. package/src/core/detectors_det01_to_16.mjs +44 -3
  276. package/src/core/fts5_output_compressor.mjs +272 -35
  277. package/src/core/horizon_config.mjs +42 -0
  278. package/src/core/parser.mjs +86 -11
  279. package/src/core/pro_license.mjs +174 -12
  280. package/src/core/pruner.mjs +7 -146
  281. package/src/core/quota.mjs +14 -2
  282. package/src/core/rsl_distiller.mjs +31 -9
  283. package/src/core/rsl_ledger.mjs +66 -6
  284. package/src/core/rsl_triage.mjs +159 -17
  285. package/src/core/session_auditor.mjs +476 -25
  286. package/src/core/shadow_auto_ledger.mjs +205 -0
  287. package/src/core/sqlite_client.mjs +10 -4
  288. package/src/core/subagents.mjs +18 -2
  289. package/src/core/task_quota_router.mjs +61 -4
  290. package/src/core-isomorphic/catalog/safeguardGuide.mjs +412 -0
  291. package/src/core-isomorphic/coach/effortShiftDetector.mjs +316 -0
  292. package/src/core-isomorphic/coach/smartCompactAdvisor.mjs +54 -20
  293. package/src/core-isomorphic/config/anthropicModelCatalog.json +1 -0
  294. package/src/core-isomorphic/config/catalogLoader.mjs +6 -3
  295. package/src/core-isomorphic/config/horizonConfig.mjs +1 -1
  296. package/src/core-isomorphic/economics/cacheGravity.mjs +3 -1
  297. package/src/core-isomorphic/economics/shadowAutoModel.mjs +228 -0
  298. package/src/core-isomorphic/guards/bucketBGamma.mjs +1 -1
  299. package/src/core-isomorphic/telemetry/telemetryBridge.mjs +77 -1
  300. package/src/core-isomorphic/ui/horizonPanelHtml.mjs +395 -130
  301. package/src/core-isomorphic/ui/modViews.mjs +62 -8
  302. package/src/diagnostics/claudeHookCapabilities.mjs +32 -2
  303. package/src/diagnostics/doctorEngine.mjs +28 -2
  304. package/src/engine-node/ipc/fast_client.mjs +191 -0
  305. package/src/engine-node/ipc/index.mjs +2 -0
  306. package/src/engine-node/multi_host_mcp.mjs +168 -0
  307. package/src/hooks/antigravity_rsl_hook.mjs +24 -2
  308. package/src/hooks/claude_rsl_hook.mjs +22 -2
  309. package/src/hooks/daemon_hook_bridge.mjs +256 -0
  310. package/src/hooks/fast_hook_ipc.mjs +295 -0
  311. package/src/hooks/post_invocation.mjs +37 -597
  312. package/src/hooks/post_invocation_core.mjs +623 -0
  313. package/src/hooks/pre_invocation.mjs +103 -1668
  314. package/src/hooks/pre_invocation_core.mjs +1830 -0
  315. package/src/utils/sessionCalibration.mjs +52 -5
  316. package/src/webview/advanced_view.html +34 -18
  317. package/src/webview/horizon_panel.html +3233 -675
  318. package/src/webview/simple_view.html +1 -1
@@ -0,0 +1,316 @@
1
+ /**
2
+ * @file src/core-isomorphic/coach/effortShiftDetector.mjs
3
+ * Passive Turn-Boundary Effort-Shift Detector (`PostEffortChange` equivalent).
4
+ *
5
+ * Pure zero-I/O module (safe for in-process Claude Code Mod runtime in `hooks/register.js`):
6
+ * - Tracks mid-session `/effort` shifts when Claude Code lacks `PreEffortChange`.
7
+ * - Attributes prefix rewrite penalties (`DET-09`) on cache-invalidating `4.6` models
8
+ * (both explicit effort changes and inferred whole-prefix rewrites).
9
+ * - Preserves zero-noise silence on cache-safe `5.5+` models for single high-effort turns,
10
+ * while flagging consecutive routine-turn thinking spikes (`DET-21`) with a 3-turn cooldown.
11
+ */
12
+
13
+ import {
14
+ isKnownCatalogModel,
15
+ normalizeModelId,
16
+ resolveEffectiveRates
17
+ } from '../config/catalogLoader.mjs';
18
+ import { getEffortMutationCacheCapability } from './cacheGravityRouter.mjs';
19
+
20
+ export const WARM_EFFORT_ATTRIBUTION_FLOOR_TOKENS = 50000;
21
+ export const ROUTINE_THINKING_SPIKE_MIN_TOKENS = 4000;
22
+ export const ROUTINE_THINKING_TO_OUTPUT_RATIO = 4;
23
+ export const EFFORT_ADVISORY_COOLDOWN_TURNS = 3;
24
+
25
+ const EFFORT_ALIASES = Object.freeze({
26
+ low: 'low',
27
+ medium: 'medium',
28
+ med: 'medium',
29
+ normal: 'medium',
30
+ high: 'high',
31
+ max: 'max',
32
+ xhigh: 'max'
33
+ });
34
+
35
+ /**
36
+ * Normalizes a raw effort string (`low | med | medium | normal | high | max | xhigh`)
37
+ * to canonical values (`low | medium | high | max`), or `null` if absent/unrecognized.
38
+ *
39
+ * @param {unknown} raw
40
+ * @returns {'low'|'medium'|'high'|'max'|null}
41
+ */
42
+ export function normalizeEffortLevel(raw) {
43
+ if (typeof raw !== 'string') return null;
44
+ const cleaned = raw.trim().toLowerCase();
45
+ return EFFORT_ALIASES[cleaned] || null;
46
+ }
47
+
48
+ /**
49
+ * Extracts normalized `{ effortLevel, thinkingBudget }` from Mod, `statusLine`,
50
+ * or `UserPromptSubmit` event payloads.
51
+ *
52
+ * @param {object} [payload={}]
53
+ * @returns {{ effortLevel: 'low'|'medium'|'high'|'max'|null, thinkingBudget: number|null }}
54
+ */
55
+ export function extractEventEffortObservation(payload = {}) {
56
+ if (!payload || typeof payload !== 'object') {
57
+ return { effortLevel: null, thinkingBudget: null };
58
+ }
59
+
60
+ const rawEffortCandidates = [
61
+ payload.effort,
62
+ payload.effortLevel,
63
+ payload.effort_level,
64
+ payload.reasoningEffort,
65
+ payload.reasoning_effort,
66
+ payload.model?.effort,
67
+ payload.config?.effortLevel,
68
+ payload.settings?.effortLevel,
69
+ payload.result?.effort
70
+ ];
71
+
72
+ let effortLevel = null;
73
+ for (const candidate of rawEffortCandidates) {
74
+ const normalized = normalizeEffortLevel(candidate);
75
+ if (normalized) {
76
+ effortLevel = normalized;
77
+ break;
78
+ }
79
+ }
80
+
81
+ const rawBudget =
82
+ payload.thinkingBudget ??
83
+ payload.thinking_budget ??
84
+ payload.thinking?.budget_tokens ??
85
+ null;
86
+ let thinkingBudget = null;
87
+ if (rawBudget !== null && rawBudget !== undefined && rawBudget !== '') {
88
+ const parsedBudget = Number(rawBudget);
89
+ if (Number.isFinite(parsedBudget) && parsedBudget >= 0) {
90
+ thinkingBudget = parsedBudget;
91
+ }
92
+ }
93
+
94
+ return { effortLevel, thinkingBudget };
95
+ }
96
+
97
+ /**
98
+ * Creates a clean initial effort-tracking state object for session telemetry.
99
+ *
100
+ * @returns {{
101
+ * currentEffort: string|null,
102
+ * previousEffort: string|null,
103
+ * currentThinkingBudget: number|null,
104
+ * shiftCount: number,
105
+ * highEffortRoutineStreak: number,
106
+ * lastShiftTurn: number|null,
107
+ * lastAdvisoryTurn: number|null,
108
+ * pendingAdvisory: object|null
109
+ * }}
110
+ */
111
+ export function createInitialEffortTrackingState() {
112
+ return {
113
+ currentEffort: null,
114
+ previousEffort: null,
115
+ currentThinkingBudget: null,
116
+ shiftCount: 0,
117
+ highEffortRoutineStreak: 0,
118
+ lastShiftTurn: null,
119
+ lastAdvisoryTurn: null,
120
+ pendingAdvisory: null
121
+ };
122
+ }
123
+
124
+ /**
125
+ * Updates turn-boundary effort tracking and evaluates `DET-09` rewrite attribution
126
+ * or `DET-21` routine-turn high-effort thinking spike advisories.
127
+ *
128
+ * @param {object|null|undefined} prevTracking
129
+ * @param {object} [observation={}]
130
+ * @param {object} [options={}]
131
+ * @returns {object} Updated effort tracking snapshot
132
+ */
133
+ export function applyTurnEffortObservation(prevTracking, observation = {}, options = {}) {
134
+ const tracking = {
135
+ ...createInitialEffortTrackingState(),
136
+ ...(prevTracking && typeof prevTracking === 'object' ? prevTracking : {})
137
+ };
138
+
139
+ const modelId = observation.modelId || observation.rawModelId || 'claude-sonnet-5-5';
140
+ const rawModelId = observation.rawModelId || modelId;
141
+ const normObserved = normalizeEffortLevel(observation.observedEffort);
142
+ const observedThinkingBudget =
143
+ observation.observedThinkingBudget !== undefined && observation.observedThinkingBudget !== null
144
+ ? Number(observation.observedThinkingBudget)
145
+ : null;
146
+ if (Number.isFinite(observedThinkingBudget) && observedThinkingBudget >= 0) {
147
+ tracking.currentThinkingBudget = observedThinkingBudget;
148
+ }
149
+
150
+ const turnIndex = Math.max(1, Number(observation.turnIndex ?? 1) || 1);
151
+ const priorTurnsCompleted = Math.max(0, Number(observation.priorTurnsCompleted ?? 0) || 0);
152
+ const priorModelId = observation.priorModelId || null;
153
+ const priorWarmPrefixTokens = Math.max(0, Number(observation.priorWarmPrefixTokens || 0));
154
+ const priorCacheWarm = Boolean(observation.priorCacheWarm);
155
+ const cacheReadTokens = Math.max(0, Number(observation.cacheReadTokens || 0));
156
+ const cacheWriteTokens = Math.max(0, Number(observation.cacheWriteTokens || 0));
157
+ const outputTokens = Math.max(0, Number(observation.outputTokens || 0));
158
+ const thinkingTokens = Math.max(0, Number(observation.thinkingTokens || 0));
159
+ const turnMutations = Number(observation.turnMutations ?? 0) || 0;
160
+ const ttlTier = observation.ttlTier === '1h' ? '1h' : '5m';
161
+
162
+ let explicitShift = false;
163
+ if (normObserved) {
164
+ if (tracking.currentEffort === null) {
165
+ if (priorTurnsCompleted >= 1 && options.treatFirstObservationAfterStartAsShift === true) {
166
+ explicitShift = true;
167
+ } else {
168
+ tracking.currentEffort = normObserved;
169
+ }
170
+ } else if (normObserved !== tracking.currentEffort) {
171
+ explicitShift = true;
172
+ }
173
+ }
174
+
175
+ const knownModel = isKnownCatalogModel(rawModelId, options);
176
+ const normalizedModel = knownModel
177
+ ? normalizeModelId(rawModelId, options)
178
+ : String(rawModelId || 'unknown');
179
+ const effortCap = getEffortMutationCacheCapability(rawModelId, options);
180
+
181
+ const normalizedPriorModel =
182
+ priorModelId && isKnownCatalogModel(priorModelId, options)
183
+ ? normalizeModelId(priorModelId, options)
184
+ : priorModelId
185
+ ? String(priorModelId)
186
+ : null;
187
+
188
+ const inferredLegacy46Rewrite = Boolean(
189
+ !explicitShift &&
190
+ effortCap.invalidatesCache === 'yes' &&
191
+ priorCacheWarm === true &&
192
+ priorWarmPrefixTokens >= WARM_EFFORT_ATTRIBUTION_FLOOR_TOKENS &&
193
+ normalizedPriorModel &&
194
+ normalizedPriorModel === normalizedModel &&
195
+ cacheReadTokens === 0 &&
196
+ cacheWriteTokens >= WARM_EFFORT_ATTRIBUTION_FLOOR_TOKENS * 0.8
197
+ );
198
+
199
+ if (explicitShift || inferredLegacy46Rewrite) {
200
+ const fromEffort = tracking.currentEffort;
201
+ const toEffort = normObserved || tracking.currentEffort;
202
+ tracking.shiftCount += 1;
203
+ tracking.previousEffort = fromEffort;
204
+ tracking.currentEffort = toEffort;
205
+ tracking.lastShiftTurn = turnIndex;
206
+
207
+ if (!knownModel || effortCap.invalidatesCache === 'unknown') {
208
+ if (priorWarmPrefixTokens >= WARM_EFFORT_ATTRIBUTION_FLOOR_TOKENS) {
209
+ tracking.pendingAdvisory = {
210
+ advisoryId: `eff-${turnIndex}-${tracking.shiftCount}`,
211
+ detectorId: 'DET-09',
212
+ subType: 'POST_EFFORT_UNVERIFIED',
213
+ modelId: String(rawModelId),
214
+ fromEffort,
215
+ toEffort,
216
+ cachePreserved: null,
217
+ rewritePenaltyUSD: null,
218
+ message: `[Highbeam DET-09] Interactive /effort shift (${fromEffort || 'prior'} -> ${toEffort || 'new'}) detected over ${(priorWarmPrefixTokens / 1000).toFixed(1)}k warm tokens on ${rawModelId} (effort cache behavior unverified; prices/impact unverified).`
219
+ };
220
+ }
221
+ } else if (effortCap.invalidatesCache === 'yes') {
222
+ if (priorWarmPrefixTokens >= WARM_EFFORT_ATTRIBUTION_FLOOR_TOKENS) {
223
+ const warmTokens = Math.max(priorWarmPrefixTokens, inferredLegacy46Rewrite ? cacheWriteTokens : 0);
224
+ const rates = resolveEffectiveRates(
225
+ rawModelId,
226
+ Math.max(priorWarmPrefixTokens, cacheWriteTokens),
227
+ options
228
+ );
229
+ const writeRate = ttlTier === '1h' ? rates.write1hPer1M : rates.write5mPer1M;
230
+ const rewritePenaltyUSD = Number(
231
+ Math.max(0, (warmTokens / 1_000_000) * (writeRate - rates.readPer1M)).toFixed(6)
232
+ );
233
+ tracking.pendingAdvisory = {
234
+ advisoryId: `eff-${turnIndex}-${tracking.shiftCount}`,
235
+ detectorId: 'DET-09',
236
+ subType: 'POST_EFFORT_CACHE_REWRITE',
237
+ modelId: normalizedModel,
238
+ fromEffort,
239
+ toEffort,
240
+ cachePreserved: false,
241
+ inferredFromRewrite: Boolean(inferredLegacy46Rewrite && !explicitShift),
242
+ rewritePenaltyUSD,
243
+ message: `[Highbeam DET-09] Mid-session /effort shift${explicitShift ? ` (${fromEffort} -> ${toEffort})` : ''} rewrote ${(warmTokens / 1000).toFixed(1)}k warm prefix tokens (+$${rewritePenaltyUSD.toFixed(2)} USD) on ${rates.label}. Batch /effort changes with /compact or upgrade to 5.5+ (99.3% cache-safe).`
244
+ };
245
+ }
246
+ } else if (
247
+ (toEffort === 'high' || toEffort === 'max') &&
248
+ priorWarmPrefixTokens >= WARM_EFFORT_ATTRIBUTION_FLOOR_TOKENS
249
+ ) {
250
+ tracking.lastCacheSafeShift = {
251
+ turnIndex,
252
+ fromEffort,
253
+ toEffort,
254
+ preservedTokens: priorWarmPrefixTokens
255
+ };
256
+ }
257
+ }
258
+
259
+ const hasUsageObservation =
260
+ observation.evaluateThinkingSpike !== false &&
261
+ (thinkingTokens > 0 || outputTokens > 0 || observation.hasTurnUsage === true);
262
+
263
+ const highEffortOrThinkingSpike =
264
+ tracking.currentEffort === 'high' ||
265
+ tracking.currentEffort === 'max' ||
266
+ thinkingTokens >= ROUTINE_THINKING_SPIKE_MIN_TOKENS * 1.5;
267
+
268
+ if (hasUsageObservation) {
269
+ if (highEffortOrThinkingSpike) {
270
+ const isRoutineSpike =
271
+ turnMutations <= 1 &&
272
+ thinkingTokens >= ROUTINE_THINKING_SPIKE_MIN_TOKENS &&
273
+ thinkingTokens >= ROUTINE_THINKING_TO_OUTPUT_RATIO * Math.max(1, outputTokens);
274
+
275
+ if (isRoutineSpike) {
276
+ tracking.highEffortRoutineStreak += 1;
277
+ } else {
278
+ tracking.highEffortRoutineStreak = 0;
279
+ }
280
+
281
+ if (
282
+ tracking.highEffortRoutineStreak >= 2 &&
283
+ (tracking.lastAdvisoryTurn === null ||
284
+ turnIndex - tracking.lastAdvisoryTurn >= EFFORT_ADVISORY_COOLDOWN_TURNS)
285
+ ) {
286
+ tracking.lastAdvisoryTurn = turnIndex;
287
+ tracking.pendingAdvisory = {
288
+ advisoryId: `spk-${turnIndex}-${tracking.highEffortRoutineStreak}`,
289
+ detectorId: 'DET-21',
290
+ subType: 'HIGH_EFFORT_ROUTINE_SPIKE',
291
+ modelId: normalizedModel,
292
+ fromEffort: tracking.previousEffort,
293
+ toEffort: tracking.currentEffort || 'high',
294
+ cachePreserved: effortCap.invalidatesCache === 'no',
295
+ rewritePenaltyUSD: 0,
296
+ message: `[Highbeam DET-21] ${tracking.highEffortRoutineStreak} consecutive routine turns burned ${(thinkingTokens / 1000).toFixed(1)}k thinking tokens vs ${outputTokens} output tokens at /effort ${tracking.currentEffort || 'high'}. Consider '/effort medium' for routine reads/edits (KV cache remains preserved on 5.5+).`
297
+ };
298
+ }
299
+ } else {
300
+ tracking.highEffortRoutineStreak = 0;
301
+ }
302
+ }
303
+
304
+ return tracking;
305
+ }
306
+
307
+ export default {
308
+ WARM_EFFORT_ATTRIBUTION_FLOOR_TOKENS,
309
+ ROUTINE_THINKING_SPIKE_MIN_TOKENS,
310
+ ROUTINE_THINKING_TO_OUTPUT_RATIO,
311
+ EFFORT_ADVISORY_COOLDOWN_TURNS,
312
+ normalizeEffortLevel,
313
+ extractEventEffortObservation,
314
+ createInitialEffortTrackingState,
315
+ applyTurnEffortObservation
316
+ };
@@ -0,0 +1 @@
1
+ export * from '../diagnostics/micro_skills.mjs';
@@ -0,0 +1 @@
1
+ export * from '../diagnostics/prompt_hygiene_governor.mjs';
@@ -0,0 +1,254 @@
1
+ /**
2
+ * @file src/coach/repoCalibration.mjs
3
+ * Empirical Repo-Calibrated Context Physics (`IDEA-03` — Technical Moat `A4`).
4
+ *
5
+ * Learns repository-specific context sinks across coding sessions:
6
+ * 1. Chronic file re-read hotspots (`fileReads` frequency & cumulative token drain across sessions)
7
+ * 2. Empirical post-compaction token survival ratio (`compactions.averageSurvivalRatio`)
8
+ * 3. Empirical KV-cache hit baseline (`cachePerformance.empiricalHitRatio`)
9
+ *
10
+ * Persisted locally in `.claude/horizon-state/repo_calibration.json` (100% zero-socket).
11
+ */
12
+
13
+ import { path, getCwd, readJsonSafe, writeJsonAtomic } from '../utils/runtime.mjs';
14
+
15
+ const DEFAULT_CALIBRATION_STATE = Object.freeze({
16
+ schemaVersion: '1.0.0',
17
+ updatedAt: null,
18
+ fileReads: {},
19
+ compactions: {
20
+ count: 0,
21
+ totalPreTokens: 0,
22
+ totalPostTokens: 0,
23
+ averageSurvivalRatio: 0.22
24
+ },
25
+ cachePerformance: {
26
+ totalTurns: 0,
27
+ warmHitTurns: 0,
28
+ empiricalHitRatio: 0
29
+ }
30
+ });
31
+
32
+ /**
33
+ * Resolves the path to `.claude/horizon-state/repo_calibration.json`.
34
+ * @param {object} [options={}]
35
+ * @returns {string}
36
+ */
37
+ export function getRepoCalibrationPath(options = {}) {
38
+ if (options.calibrationPath) return options.calibrationPath;
39
+ const cwd = getCwd(options);
40
+ const stateDir = options.stateDir || path.join(cwd, '.claude', 'horizon-state');
41
+ return path.join(stateDir, 'repo_calibration.json');
42
+ }
43
+
44
+ /**
45
+ * Normalizes a repository file path to a portable forward-slash key.
46
+ * @param {string} filePath
47
+ * @param {string} [cwd='.']
48
+ * @returns {string}
49
+ */
50
+ export function normalizeRepoFileKey(filePath, cwd = '.') {
51
+ const raw = String(filePath || '').trim();
52
+ if (!raw) return '';
53
+ try {
54
+ const rel = path.isAbsolute(raw) ? path.relative(cwd, raw) : raw;
55
+ const clean = rel.replace(/\\/g, '/').replace(/^\.\//, '');
56
+ return clean.startsWith('..') ? raw.replace(/\\/g, '/') : clean;
57
+ } catch (_err) {
58
+ return raw.replace(/\\/g, '/');
59
+ }
60
+ }
61
+
62
+ /**
63
+ * Loads the empirical calibration store for the current repository.
64
+ * @param {object} [options={}]
65
+ * @returns {object}
66
+ */
67
+ export function loadRepoCalibration(options = {}) {
68
+ const targetPath = getRepoCalibrationPath(options);
69
+ const raw = readJsonSafe(targetPath, null, options);
70
+ if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
71
+ return JSON.parse(JSON.stringify(DEFAULT_CALIBRATION_STATE));
72
+ }
73
+ return {
74
+ schemaVersion: '1.0.0',
75
+ updatedAt: raw.updatedAt || null,
76
+ fileReads: raw.fileReads && typeof raw.fileReads === 'object' ? { ...raw.fileReads } : {},
77
+ compactions: {
78
+ ...DEFAULT_CALIBRATION_STATE.compactions,
79
+ ...(raw.compactions || {})
80
+ },
81
+ cachePerformance: {
82
+ ...DEFAULT_CALIBRATION_STATE.cachePerformance,
83
+ ...(raw.cachePerformance || {})
84
+ }
85
+ };
86
+ }
87
+
88
+ /**
89
+ * Records a file read event in the repository calibration store and detects
90
+ * whether the file has become a chronic multi-read context sink.
91
+ *
92
+ * @param {{ filePath: string, estimatedTokens?: number, sessionId?: string }} event
93
+ * @param {object} [options={}]
94
+ * @returns {{
95
+ * fileKey: string,
96
+ * readCount: number,
97
+ * sessionCount: number,
98
+ * totalEstimatedTokens: number,
99
+ * isChronicSink: boolean,
100
+ * recommendation: string | null
101
+ * }}
102
+ */
103
+ export function recordRepoFileRead(event = {}, options = {}) {
104
+ const cwd = getCwd(options);
105
+ const fileKey = normalizeRepoFileKey(event.filePath, cwd);
106
+ if (!fileKey) {
107
+ return {
108
+ fileKey: '',
109
+ readCount: 0,
110
+ sessionCount: 0,
111
+ totalEstimatedTokens: 0,
112
+ isChronicSink: false,
113
+ recommendation: null
114
+ };
115
+ }
116
+
117
+ const tokens = Math.max(0, Math.round(Number(event.estimatedTokens ?? 0)));
118
+ const sessionId = String(event.sessionId || options.sessionId || 'default');
119
+ const state = loadRepoCalibration(options);
120
+
121
+ const existing = state.fileReads[fileKey] || {
122
+ readCount: 0,
123
+ totalEstimatedTokens: 0,
124
+ sessionsSeen: [],
125
+ lastReadAt: null
126
+ };
127
+
128
+ existing.readCount = Number(existing.readCount || 0) + 1;
129
+ existing.totalEstimatedTokens = Number(existing.totalEstimatedTokens || 0) + tokens;
130
+ const sessions = Array.isArray(existing.sessionsSeen) ? [...existing.sessionsSeen] : [];
131
+ if (!sessions.includes(sessionId)) {
132
+ sessions.push(sessionId);
133
+ }
134
+ existing.sessionsSeen = sessions.slice(-25);
135
+ existing.lastReadAt = new Date().toISOString();
136
+
137
+ state.fileReads[fileKey] = existing;
138
+ state.updatedAt = existing.lastReadAt;
139
+ writeJsonAtomic(getRepoCalibrationPath(options), state, options);
140
+
141
+ // Exclude small onboarding docs (e.g., README.md read <= 2x per chat) from false-positive sink status
142
+ const isOnboardingDoc = /^(?:README\.md|CLAUDE\.md|AGENTS\.md|LICENSE)$/i.test(
143
+ path.basename(fileKey)
144
+ );
145
+ const avgReadsPerSession = existing.readCount / Math.max(1, existing.sessionsSeen.length);
146
+
147
+ const isChronicSink = isOnboardingDoc
148
+ ? existing.readCount >= 6 && avgReadsPerSession >= 3
149
+ : existing.readCount >= 3 && existing.totalEstimatedTokens >= 6000;
150
+
151
+ const recommendation = isChronicSink
152
+ ? `Repo Calibration Alert: "${fileKey}" has been read ${existing.readCount}x (${existing.totalEstimatedTokens.toLocaleString()} cumulative tok across ${existing.sessionsSeen.length} session(s)). Use ranged line reads (offset/limit) or delegate to an Explore subagent.`
153
+ : null;
154
+
155
+ return {
156
+ fileKey,
157
+ readCount: existing.readCount,
158
+ sessionCount: existing.sessionsSeen.length,
159
+ totalEstimatedTokens: existing.totalEstimatedTokens,
160
+ isChronicSink,
161
+ recommendation
162
+ };
163
+ }
164
+
165
+ /**
166
+ * Records an observed compaction outcome (`preTokens` -> `postTokens`) to calibrate
167
+ * the repository's empirical post-compaction survival ratio.
168
+ *
169
+ * @param {{ preTokens: number, postTokens: number }} event
170
+ * @param {object} [options={}]
171
+ * @returns {object}
172
+ */
173
+ export function recordRepoCompactionOutcome(event = {}, options = {}) {
174
+ const pre = Math.max(0, Number(event.preTokens || 0));
175
+ const post = Math.max(0, Number(event.postTokens || 0));
176
+ const state = loadRepoCalibration(options);
177
+
178
+ if (pre > 0 && post > 0 && post <= pre) {
179
+ state.compactions.count += 1;
180
+ state.compactions.totalPreTokens += pre;
181
+ state.compactions.totalPostTokens += post;
182
+ state.compactions.averageSurvivalRatio = Number(
183
+ (state.compactions.totalPostTokens / state.compactions.totalPreTokens).toFixed(4)
184
+ );
185
+ state.updatedAt = new Date().toISOString();
186
+ writeJsonAtomic(getRepoCalibrationPath(options), state, options);
187
+ }
188
+
189
+ return state.compactions;
190
+ }
191
+
192
+ /**
193
+ * Records a turn's KV-cache read ratio to maintain an empirical cache-hit baseline for the repo.
194
+ *
195
+ * @param {{ cacheReadTokens: number, totalPromptTokens: number }} event
196
+ * @param {object} [options={}]
197
+ * @returns {object}
198
+ */
199
+ export function recordRepoCacheTurn(event = {}, options = {}) {
200
+ const readTok = Math.max(0, Number(event.cacheReadTokens || 0));
201
+ const totalTok = Math.max(0, Number(event.totalPromptTokens || 0));
202
+ const state = loadRepoCalibration(options);
203
+
204
+ if (totalTok > 0) {
205
+ state.cachePerformance.totalTurns += 1;
206
+ if (readTok / totalTok >= 0.5) {
207
+ state.cachePerformance.warmHitTurns += 1;
208
+ }
209
+ state.cachePerformance.empiricalHitRatio = Number(
210
+ (state.cachePerformance.warmHitTurns / state.cachePerformance.totalTurns).toFixed(4)
211
+ );
212
+ state.updatedAt = new Date().toISOString();
213
+ writeJsonAtomic(getRepoCalibrationPath(options), state, options);
214
+ }
215
+
216
+ return state.cachePerformance;
217
+ }
218
+
219
+ /**
220
+ * Returns the top chronic re-read context-sink files in this repository.
221
+ *
222
+ * @param {object} [options={}]
223
+ * @returns {Array<{
224
+ * fileKey: string,
225
+ * readCount: number,
226
+ * sessionCount: number,
227
+ * totalEstimatedTokens: number
228
+ * }>}
229
+ */
230
+ export function getTopChronicReadFiles(options = {}) {
231
+ const limit = Number(options.limit || 5);
232
+ const state = loadRepoCalibration(options);
233
+ const entries = Object.entries(state.fileReads || {}).map(([fileKey, info]) => ({
234
+ fileKey,
235
+ readCount: Number(info.readCount || 0),
236
+ sessionCount: Array.isArray(info.sessionsSeen) ? info.sessionsSeen.length : 1,
237
+ totalEstimatedTokens: Number(info.totalEstimatedTokens || 0)
238
+ }));
239
+
240
+ return entries
241
+ .filter((e) => e.readCount >= 2)
242
+ .sort((a, b) => b.totalEstimatedTokens - a.totalEstimatedTokens || b.readCount - a.readCount)
243
+ .slice(0, limit);
244
+ }
245
+
246
+ export default {
247
+ getRepoCalibrationPath,
248
+ normalizeRepoFileKey,
249
+ loadRepoCalibration,
250
+ recordRepoFileRead,
251
+ recordRepoCompactionOutcome,
252
+ recordRepoCacheTurn,
253
+ getTopChronicReadFiles
254
+ };