ctxtop 0.0.0-stage → 4.1.0

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 (262) hide show
  1. package/.antigravity-plugin/plugin.json +36 -0
  2. package/.claude-plugin/plugin.json +18 -0
  3. package/CHECKSUMS.sha256 +166 -0
  4. package/LICENSE +27 -0
  5. package/README.md +350 -2
  6. package/SECURITY.md +22 -0
  7. package/agents/ah-flash-scout.md +25 -0
  8. package/assets/advanced_view_loaded_420px.png +0 -0
  9. package/assets/hero-demo.svg +188 -0
  10. package/assets/logo.svg +19 -0
  11. package/assets/simple_view_lean_420px.png +0 -0
  12. package/assets/simple_view_loaded_420px.png +0 -0
  13. package/assets/social-preview.svg +72 -0
  14. package/assets/zone_c_step3_shield_full.png +0 -0
  15. package/bin/ah-statusline.mjs +175 -0
  16. package/bin/cli.mjs +3 -0
  17. package/bin/ctxtop.mjs +1799 -0
  18. package/commands/cost-radar.md +11 -0
  19. package/commands/evolve.md +10 -0
  20. package/commands/handoff.md +10 -0
  21. package/commands/horizon.md +10 -0
  22. package/commands/inspect.md +10 -0
  23. package/commands/precheck.md +10 -0
  24. package/config/default_flightcheck.json +133 -0
  25. package/config/modelCatalog.json +785 -0
  26. package/config/platformQuirks.json +19 -0
  27. package/hooks/handlers/compact-lifecycle.mjs +577 -0
  28. package/hooks/handlers/config-change.mjs +402 -0
  29. package/hooks/handlers/hookIo.mjs +311 -0
  30. package/hooks/handlers/hookIpcClient.mjs +83 -0
  31. package/hooks/handlers/post-model-switch.mjs +111 -0
  32. package/hooks/handlers/post-tool-use.mjs +366 -0
  33. package/hooks/handlers/pre-model-switch.mjs +1048 -0
  34. package/hooks/handlers/pre-tool-use.mjs +632 -0
  35. package/hooks/handlers/stop-gate.mjs +526 -0
  36. package/hooks/handlers/user-prompt-submit.mjs +367 -0
  37. package/hooks/hooks.json +131 -0
  38. package/hooks/post_invocation.mjs +13 -0
  39. package/hooks/post_tool_use.mjs +25 -0
  40. package/hooks/pre_invocation.mjs +14 -0
  41. package/hooks/pre_tool_use.mjs +97 -0
  42. package/hooks/register.js +726 -0
  43. package/hooks/session_start.mjs +24 -0
  44. package/hooks/stop.mjs +23 -0
  45. package/hooks.json +56 -0
  46. package/package.json +110 -4
  47. package/packages/antigravity/package.json +14 -0
  48. package/packages/antigravity/src/index.mjs +1 -0
  49. package/packages/claude-code/package.json +14 -0
  50. package/packages/claude-code/src/index.mjs +2 -0
  51. package/packages/core/package.json +14 -0
  52. package/packages/core/src/index.mjs +1 -0
  53. package/packages/engine-node/package.json +14 -0
  54. package/packages/engine-node/src/index.mjs +1 -0
  55. package/packages/mcp/package.json +17 -0
  56. package/packages/mcp/src/server.mjs +396 -0
  57. package/packages/pro/LICENSE-COMMERCIAL.md +19 -0
  58. package/packages/pro/README-SIGNING.md +30 -0
  59. package/packages/pro/package.json +16 -0
  60. package/packages/pro/src/index.mjs +3 -0
  61. package/packages/pro/src/team_finops_pack.mjs +241 -0
  62. package/packages/pro/workers/polar_webhook_worker.mjs +215 -0
  63. package/plugin.json +36 -0
  64. package/rules/AGENTS.md +10 -0
  65. package/sidecars/horizon-daemon/ipcServer.mjs +24 -0
  66. package/sidecars/horizon-daemon/server.mjs +2038 -0
  67. package/sidecars/horizon-daemon/sidecar.json +19 -0
  68. package/skills/cost-radar/SKILL.md +21 -0
  69. package/skills/evolve/SKILL.md +21 -0
  70. package/skills/handoff/SKILL.md +50 -0
  71. package/skills/horizon/SKILL.md +17 -0
  72. package/skills/inspect/SKILL.md +18 -0
  73. package/skills/precheck/SKILL.md +44 -0
  74. package/src/adapters/antigravity/index.mjs +109 -0
  75. package/src/adapters/claude-code/index.mjs +194 -0
  76. package/src/cli/cost_radar.mjs +70 -0
  77. package/src/cli/doctor.mjs +351 -0
  78. package/src/cli/horizon_hud.mjs +888 -0
  79. package/src/cli/init.mjs +425 -0
  80. package/src/cli/postmortem.mjs +515 -0
  81. package/src/coach/cacheGravityRouter.mjs +12 -0
  82. package/src/config/modelCatalog.json +704 -0
  83. package/src/config/platformQuirks.json +19 -0
  84. package/src/core/action_queue.mjs +264 -0
  85. package/src/core/ag_bridge.mjs +346 -0
  86. package/src/core/atomic_io.mjs +124 -0
  87. package/src/core/baseline.mjs +607 -0
  88. package/src/core/blindspot_sensors.mjs +399 -0
  89. package/src/core/bucket_b_runtime.mjs +1200 -0
  90. package/src/core/classifier.mjs +1757 -0
  91. package/src/core/coach/circuit_breakers.mjs +650 -0
  92. package/src/core/coach/contradiction_auditor.mjs +239 -0
  93. package/src/core/coach/effort_advisor.mjs +143 -0
  94. package/src/core/coach/handoff_hydrator.mjs +483 -0
  95. package/src/core/coach/progressive_checkpointer.mjs +551 -0
  96. package/src/core/coach/prompt_decomposer_coach.mjs +141 -0
  97. package/src/core/coach/reflector_queue.mjs +505 -0
  98. package/src/core/coach/saved_quota_ledger.mjs +615 -0
  99. package/src/core/coach/subagent_ipi_sanitizer.mjs +200 -0
  100. package/src/core/coach/subagent_phantom_auditor.mjs +261 -0
  101. package/src/core/coach/task_quota_router.mjs +955 -0
  102. package/src/core/coach/turn_zero_gate.mjs +574 -0
  103. package/src/core/compaction_coach.mjs +1126 -0
  104. package/src/core/config.mjs +214 -0
  105. package/src/core/constants.mjs +1987 -0
  106. package/src/core/detectors_det01_to_16.mjs +1523 -0
  107. package/src/core/doc_indexer.mjs +338 -0
  108. package/src/core/episodic_memory.mjs +135 -0
  109. package/src/core/fts5_output_compressor.mjs +359 -0
  110. package/src/core/git_ledger.mjs +189 -0
  111. package/src/core/handoff_audit.mjs +558 -0
  112. package/src/core/history.mjs +221 -0
  113. package/src/core/hook_diagnostics.mjs +158 -0
  114. package/src/core/horizon_classifier.mjs +326 -0
  115. package/src/core/horizon_config.mjs +802 -0
  116. package/src/core/host_watchdog.mjs +200 -0
  117. package/src/core/layer5_hygiene.mjs +1084 -0
  118. package/src/core/log_resolver.mjs +231 -0
  119. package/src/core/mcp_auditor.mjs +138 -0
  120. package/src/core/micro_skills_store.mjs +91 -0
  121. package/src/core/offenders.mjs +161 -0
  122. package/src/core/parser.mjs +1997 -0
  123. package/src/core/path_canonicalizer.mjs +73 -0
  124. package/src/core/paths.mjs +311 -0
  125. package/src/core/prefix_cache_shield.mjs +386 -0
  126. package/src/core/pro_license.mjs +385 -0
  127. package/src/core/prompt_rubric.mjs +518 -0
  128. package/src/core/pruner.mjs +433 -0
  129. package/src/core/quota.mjs +1860 -0
  130. package/src/core/rsi_instinct_engine.mjs +1197 -0
  131. package/src/core/rsl_clash_auditor.mjs +423 -0
  132. package/src/core/rsl_distiller.mjs +372 -0
  133. package/src/core/rsl_ledger.mjs +969 -0
  134. package/src/core/rsl_triage.mjs +909 -0
  135. package/src/core/sanitizer.mjs +121 -0
  136. package/src/core/session_auditor.mjs +658 -0
  137. package/src/core/session_forensics.mjs +303 -0
  138. package/src/core/session_timeline.mjs +358 -0
  139. package/src/core/settings.mjs +99 -0
  140. package/src/core/shared/detectors.mjs +1342 -0
  141. package/src/core/shared/fnv1a64.mjs +85 -0
  142. package/src/core/shared/handoff_schema.mjs +123 -0
  143. package/src/core/shared/index.mjs +5 -0
  144. package/src/core/shared/ipi_sanitizer.mjs +165 -0
  145. package/src/core/shared/micro_skills.mjs +1 -0
  146. package/src/core/shared/plugin_validator.mjs +202 -0
  147. package/src/core/shared/prompt_hygiene_governor.mjs +1 -0
  148. package/src/core/shield_manager.mjs +1417 -0
  149. package/src/core/sidecar_store.mjs +302 -0
  150. package/src/core/sprint_metrics.mjs +366 -0
  151. package/src/core/sqlite_client.mjs +283 -0
  152. package/src/core/storage_doctor.mjs +358 -0
  153. package/src/core/subagents.mjs +609 -0
  154. package/src/core/swarm_topology.mjs +360 -0
  155. package/src/core/task_quota_router.mjs +1656 -0
  156. package/src/core/telemetry/cache_ttl_watchdog.mjs +284 -0
  157. package/src/core/telemetry/scope_lock_registry.mjs +578 -0
  158. package/src/core/telemetry/shadow_file_detector.mjs +291 -0
  159. package/src/core/telemetry/trajectory_watcher.mjs +259 -0
  160. package/src/core/timeline_svg.mjs +236 -0
  161. package/src/core/tool_surgeon.mjs +305 -0
  162. package/src/core/trajectory_stitcher.mjs +645 -0
  163. package/src/core/u_shaped_optimizer.mjs +789 -0
  164. package/src/core/wal_hygiene.mjs +233 -0
  165. package/src/core-isomorphic/catalog/detectorCatalog.mjs +558 -0
  166. package/src/core-isomorphic/catalog/index.mjs +1 -0
  167. package/src/core-isomorphic/coach/cacheGravityRouter.mjs +1547 -0
  168. package/src/core-isomorphic/coach/microSkills.mjs +1 -0
  169. package/src/core-isomorphic/coach/promptHygieneGovernor.mjs +1 -0
  170. package/src/core-isomorphic/coach/repoCalibration.mjs +254 -0
  171. package/src/core-isomorphic/coach/resumeToolsetAuditor.mjs +321 -0
  172. package/src/core-isomorphic/coach/savedQuotaLedger.mjs +527 -0
  173. package/src/core-isomorphic/coach/smartCompactAdvisor.mjs +305 -0
  174. package/src/core-isomorphic/coach/stateBatonHydrator.mjs +810 -0
  175. package/src/core-isomorphic/coach/ttlWatchdog.mjs +464 -0
  176. package/src/core-isomorphic/config/anthropicModelCatalog.json +606 -0
  177. package/src/core-isomorphic/config/catalogLoader.mjs +1268 -0
  178. package/src/core-isomorphic/config/horizonConfig.mjs +1055 -0
  179. package/src/core-isomorphic/control/callTree.mjs +338 -0
  180. package/src/core-isomorphic/control/coachLatches.mjs +126 -0
  181. package/src/core-isomorphic/control/controlStateMachine.mjs +205 -0
  182. package/src/core-isomorphic/control/index.mjs +49 -0
  183. package/src/core-isomorphic/control/swarmWorktree.mjs +109 -0
  184. package/src/core-isomorphic/control/toolSuspension.mjs +197 -0
  185. package/src/core-isomorphic/diagnostics/drift_guard.mjs +382 -0
  186. package/src/core-isomorphic/diagnostics/index.mjs +9 -0
  187. package/src/core-isomorphic/diagnostics/micro_skills.mjs +471 -0
  188. package/src/core-isomorphic/diagnostics/prompt_hygiene_governor.mjs +888 -0
  189. package/src/core-isomorphic/economics/billingBlocks.mjs +251 -0
  190. package/src/core-isomorphic/economics/cacheGravity.mjs +369 -0
  191. package/src/core-isomorphic/economics/cliffBreaker.mjs +256 -0
  192. package/src/core-isomorphic/economics/driftLatency.mjs +433 -0
  193. package/src/core-isomorphic/economics/dualTtl.mjs +198 -0
  194. package/src/core-isomorphic/economics/index.mjs +47 -0
  195. package/src/core-isomorphic/economics/retentionRadar.mjs +348 -0
  196. package/src/core-isomorphic/guards/bucketBAlphaBeta.mjs +860 -0
  197. package/src/core-isomorphic/guards/bucketBGamma.mjs +442 -0
  198. package/src/core-isomorphic/guards/bucketBHeuristics.mjs +37 -0
  199. package/src/core-isomorphic/guards/circuitBreakers.mjs +1202 -0
  200. package/src/core-isomorphic/guards/det01_03_shell_secret.mjs +1184 -0
  201. package/src/core-isomorphic/guards/det04_12_thrash_rot.mjs +572 -0
  202. package/src/core-isomorphic/guards/det13_20_mcp_scope.mjs +913 -0
  203. package/src/core-isomorphic/guards/docIndexCore.mjs +446 -0
  204. package/src/core-isomorphic/guards/losslessPostSanitizer.mjs +317 -0
  205. package/src/core-isomorphic/guards/slopsquatGate.mjs +551 -0
  206. package/src/core-isomorphic/index.js +27 -0
  207. package/src/core-isomorphic/telemetry/otelExporter.mjs +187 -0
  208. package/src/core-isomorphic/telemetry/scopeLockRegistry.mjs +522 -0
  209. package/src/core-isomorphic/telemetry/sprintMetrics.mjs +327 -0
  210. package/src/core-isomorphic/telemetry/swarmTopology.mjs +152 -0
  211. package/src/core-isomorphic/telemetry/telemetryBridge.mjs +1156 -0
  212. package/src/core-isomorphic/ui/brailleSparkline.mjs +142 -0
  213. package/src/core-isomorphic/ui/costRadarSvg.mjs +276 -0
  214. package/src/core-isomorphic/ui/horizonGrid.mjs +475 -0
  215. package/src/core-isomorphic/ui/horizonPanelHtml.mjs +1237 -0
  216. package/src/core-isomorphic/ui/modViews.mjs +1504 -0
  217. package/src/core-isomorphic/ui/pdfReceiptGenerator.mjs +329 -0
  218. package/src/core-isomorphic/ustf/index.mjs +7 -0
  219. package/src/core-isomorphic/ustf/normalizer.mjs +512 -0
  220. package/src/core-isomorphic/ustf/schema.mjs +186 -0
  221. package/src/core-isomorphic/utils/runtime.mjs +962 -0
  222. package/src/demo/synthetic_states.mjs +661 -0
  223. package/src/diagnostics/bugReportGenerator.mjs +253 -0
  224. package/src/diagnostics/claudeHookCapabilities.mjs +396 -0
  225. package/src/diagnostics/doctorEngine.mjs +295 -0
  226. package/src/engine-node/db/index.mjs +58 -0
  227. package/src/engine-node/db/jsonl_fallback.mjs +184 -0
  228. package/src/engine-node/db/probe.mjs +342 -0
  229. package/src/engine-node/db/sqlite_wrapper.mjs +122 -0
  230. package/src/engine-node/index.mjs +12 -0
  231. package/src/engine-node/ipc/client.mjs +447 -0
  232. package/src/engine-node/ipc/index.mjs +22 -0
  233. package/src/engine-node/ipc/protocol.mjs +177 -0
  234. package/src/engine-node/ipc/server.mjs +445 -0
  235. package/src/engine-node/offloader/index.mjs +6 -0
  236. package/src/engine-node/offloader/tool_offloader.mjs +241 -0
  237. package/src/engine-node/sensors/blindspots.mjs +376 -0
  238. package/src/engine-node/sensors/git_merge_tree.mjs +223 -0
  239. package/src/engine-node/sensors/index.mjs +7 -0
  240. package/src/hooks/antigravity_rsl_hook.mjs +250 -0
  241. package/src/hooks/claude_rsl_hook.mjs +288 -0
  242. package/src/hooks/portfolio_runtime.mjs +858 -0
  243. package/src/hooks/post_invocation.mjs +611 -0
  244. package/src/hooks/pre_invocation.mjs +1725 -0
  245. package/src/hooks/session_start.mjs +199 -0
  246. package/src/shims/agy_cli_compressor.mjs +705 -0
  247. package/src/shims/agy_git_guard.mjs +749 -0
  248. package/src/shims/ah_log_query.mjs +39 -0
  249. package/src/ui/costRadarSvg.mjs +6 -0
  250. package/src/ui/horizonGrid.mjs +1 -0
  251. package/src/ui/horizonPanelHtml.mjs +1 -0
  252. package/src/ui/horizon_panel.css +167 -0
  253. package/src/ui/horizon_panel.js +212 -0
  254. package/src/ui/modViews.mjs +1 -0
  255. package/src/utils/modelSwitchTelemetry.mjs +308 -0
  256. package/src/utils/nodeIo.mjs +59 -0
  257. package/src/utils/runtime.mjs +1 -0
  258. package/src/utils/sessionCalibration.mjs +657 -0
  259. package/src/webview/advanced_view.html +1808 -0
  260. package/src/webview/horizon_panel.html +12397 -0
  261. package/src/webview/registry.mjs +80 -0
  262. package/src/webview/simple_view.html +1370 -0
@@ -0,0 +1,36 @@
1
+ {
2
+ "$schema": "https://antigravity.google/schemas/v1/plugin.json",
3
+ "name": "attention-horizon-antigravity",
4
+ "displayName": "Highbeam",
5
+ "version": "4.1.0",
6
+ "description": "40-cell context window telemetry HUD, KV-Cache Gravity effort router, and zero-token pre-write guardrails.",
7
+ "author": {
8
+ "name": "Gizzant"
9
+ },
10
+ "icon": "./assets/logo.svg",
11
+ "hooks": "./hooks.json",
12
+ "rules": [
13
+ "./rules/AGENTS.md"
14
+ ],
15
+ "skills": [
16
+ "./skills/horizon",
17
+ "./skills/precheck",
18
+ "./skills/handoff",
19
+ "./skills/cost-radar",
20
+ "./skills/inspect",
21
+ "./skills/evolve"
22
+ ],
23
+ "agents": [
24
+ "./agents/ah-flash-scout.md"
25
+ ],
26
+ "sidecars": [
27
+ "./sidecars/horizon-daemon"
28
+ ],
29
+ "suggestedPrompts": [
30
+ "/horizon Inspect my 40-cell Highbeam and Wasted Tokens",
31
+ "/precheck Audit my next architecture refactor prompt and context hygiene",
32
+ "/handoff Audit and format State Baton before /compact or session handoff",
33
+ "/cost-radar Render my prefix-cache retention, thinking drift and swarm topology timeline",
34
+ "/evolve Audit static AGENTS.md token overhead and route skill deltas"
35
+ ]
36
+ }
@@ -0,0 +1,18 @@
1
+ {
2
+ "name": "attention-horizon",
3
+ "version": "4.1.0",
4
+ "description": "Highbeam KV-Cache & Context Governor for Claude Code",
5
+ "author": {
6
+ "name": "Highbeam Contributors"
7
+ },
8
+ "license": "MIT",
9
+ "hooks": "./hooks/hooks.json",
10
+ "commands": [
11
+ "./commands/horizon.md",
12
+ "./commands/cost-radar.md",
13
+ "./commands/inspect.md",
14
+ "./commands/handoff.md",
15
+ "./commands/precheck.md",
16
+ "./commands/evolve.md"
17
+ ]
18
+ }
@@ -0,0 +1,166 @@
1
+ ead192f474b661946b6dec1cb9ec8f664a9c81622b6d201119e5ef341c0175ba .claude-plugin/plugin.json
2
+ 63f907a6f8054221df7e9620365cc5153a76743d1121147d5e37210098767870 bin/ah-statusline.mjs
3
+ 22c8d41c19e98b76c3ab6bdf7bcb7f63e069d68932d148b01843cf75b6fcbfb1 bin/cli.mjs
4
+ 21766abc739a100ccf7ab8d13bcf9c05af98d48e3ce255eb636a5cac3bde0077 bin/ctxtop.mjs
5
+ 27f61277db70bdb7ad53e9c7b09e8213ef96a158314a9c2e9434721215c69c82 hooks.json
6
+ a21b17e9f261c7f1e54d81be124a344f203bbf9dd92cfc3aeca46f445aa957f0 hooks/handlers/compact-lifecycle.mjs
7
+ 3fd0cf0971e0edd0bacf79928867f0984ed26444a3ec3db1784ac7c360601aff hooks/handlers/config-change.mjs
8
+ c2cd7d9635df9ce84c16cafadb4263baa2b5a856649fded90d97cb592e567381 hooks/handlers/hookIo.mjs
9
+ 4176a52ceb973257ae80e00609daddcc5a03c791fbe55ca7419cc3c4ed0946ff hooks/handlers/hookIpcClient.mjs
10
+ 83383ac74a6ba912e4ac45517df998448fd091cdf02b0eeef9783490c9e53cf1 hooks/handlers/post-model-switch.mjs
11
+ 3bfbf7cd7f6c757b7daa151bd62f698b0a4e50d814fef89c6a2c2219b60cdeee hooks/handlers/post-tool-use.mjs
12
+ db57bcb05fa078784bc7da6b9562c3cf7e9cf07b4fad96cde34e5433e77f3b23 hooks/handlers/pre-model-switch.mjs
13
+ 7514408c669e0c982ad0785564068035d438bfc050e8b850ec0659aa85ba8a36 hooks/handlers/pre-tool-use.mjs
14
+ 2309e7a70b96f5cdb1be0c3ce3b2cb9a1414ee4a754b8d199fc2f88747e2dca9 hooks/handlers/stop-gate.mjs
15
+ 5d9fe60fc2185a9f902e0c46f421ee86e62f6155a83ec9a211e70faa2b7a0381 hooks/handlers/user-prompt-submit.mjs
16
+ 5c4261e03b000715603c3ff9335445e9f2de512255a8a5bd1c6a99a28cf11cb9 hooks/hooks.json
17
+ a0d8619335843c2b50684439a3c4d7735c74a4d1264cfb474e692ed8b5bcc51a hooks/post_invocation.mjs
18
+ ffffad9e71d8608d7f68cad6b4981064f8aceda64af315d9c7a10dac344f32f0 hooks/post_tool_use.mjs
19
+ bf72514288e5618f20d6a62808b7ba496701f6a475cc23f9d168cc7c6b29a0c7 hooks/pre_invocation.mjs
20
+ e23018a16b2d70be203c138b4fd6432eb32aa039d8822bff5b55a94ef43b697c hooks/pre_tool_use.mjs
21
+ f0c1f47035880067e9a42202ebf91f441b126f212676bd8926d68ba650b96303 hooks/register.js
22
+ 25a8f2b87ef95cda5e0a8ea935426ac2d0c0cd7c8bd667f43ec19269bba6ab33 hooks/session_start.mjs
23
+ e58de0d1dfe27ad261216167f2ca206b6c0abcdb3940a017c286fd96c7516254 hooks/stop.mjs
24
+ 22b70f8d04b610ae8af6650e229220d18167cc468507d3fa2994b1b46bf0bee4 package.json
25
+ 7215b5f9522f93dec180aa642f37c44ab0755e3291e066e991b191ea1be10f12 plugin.json
26
+ d9fb54e539f684d28eb11f15a0fbcd70bc0135e011fd2ff4a090b1bcd15291b6 src/core-isomorphic/catalog/detectorCatalog.mjs
27
+ 7a27626a1d278b16f43763ac1a8cb3e2bf0d136ecadcf27a0cd5293609896baa src/core-isomorphic/catalog/index.mjs
28
+ d75412a9f3ceedf4dfc569f059eada0c6ba3785fb458bd5f5e3a0dd61045a631 src/core-isomorphic/coach/cacheGravityRouter.mjs
29
+ eff25345c6ff2d2f6a2a76268c68125a77bd9061fffc76cc62c9045d34280c39 src/core-isomorphic/coach/microSkills.mjs
30
+ c4776ae105cbab042bc4a0da00607712fa37b70eecc8fef370dca5c111d7470f src/core-isomorphic/coach/promptHygieneGovernor.mjs
31
+ 7352055abc1158b585c48119034cfca874310517279d4ff3c4eed07baefae7f4 src/core-isomorphic/coach/repoCalibration.mjs
32
+ 204de1348b8f61c5b5a7c249d9834288bd1b93222a9e4b1815cbdb576c508545 src/core-isomorphic/coach/resumeToolsetAuditor.mjs
33
+ e1eb74a87049470e389de00a23badccb7d7d159bd118d1a19b26ad6b3710fc51 src/core-isomorphic/coach/savedQuotaLedger.mjs
34
+ 96cad410b8fdb69f34bca2dffb631be5883d7e71ea6ed3d673915c85672bac10 src/core-isomorphic/coach/smartCompactAdvisor.mjs
35
+ f2d152885288e4bf3bb670b05ff67a2a12f8de05e72fba1f338a55902a8af56f src/core-isomorphic/coach/stateBatonHydrator.mjs
36
+ e9555f5d8017e23e1a681383abb8ad13ba1f1826157ece20391fc7006416c5cd src/core-isomorphic/coach/ttlWatchdog.mjs
37
+ b6409918fa12749f49dd24d64cd37fdeae3fcf04b58158dea893761ebaa5fe20 src/core-isomorphic/config/anthropicModelCatalog.json
38
+ d4f23a60a0ebfe6492ca04836cdd924b6321c9d46bb66160b4cfa969e7ab8071 src/core-isomorphic/config/catalogLoader.mjs
39
+ f4b02130c1541859c17865979a46c3b57d5a5ddf8dac4970cb15bb20aa9c4c55 src/core-isomorphic/config/horizonConfig.mjs
40
+ 41f5a8fbb903efbb70ffe183b9646152f25ac397dfb299558a49601ed8124fe7 src/core-isomorphic/control/callTree.mjs
41
+ 9ab7b53172aaa44838823fb62c69f10f6084132c18be56535d7acd57bda0761a src/core-isomorphic/control/coachLatches.mjs
42
+ f004e367080f6f2ad8640d03111181a264e8d7cd6ed99bbd6ebbe8a53365641d src/core-isomorphic/control/controlStateMachine.mjs
43
+ 8b464583992562c54d6b44e2d88de2c23cd30e58f1d47236a061e5556c89a96c src/core-isomorphic/control/index.mjs
44
+ 8c32787061a2caa9b39fe15619ef2e8284e7b4a78d7fcd3d2ee2073eeca685ec src/core-isomorphic/control/swarmWorktree.mjs
45
+ eba94306f2d23381f78d58c333261db5e551517a21a2d0b29f0f9ccd2d3b8dac src/core-isomorphic/control/toolSuspension.mjs
46
+ e9523d7d0e9f09d99a5e43e4723d6662e9fb777ed8c8df066c6e68b57ad22de4 src/core-isomorphic/diagnostics/drift_guard.mjs
47
+ 7925a319fcc0f4021a00c55d0344bf01c6175b1139e3127469c59a96e03eee32 src/core-isomorphic/diagnostics/index.mjs
48
+ 2acb7a21d8000bbcfbafeb6b3406a4d04927b2b0c4888c08daad59fbc9d3dee8 src/core-isomorphic/diagnostics/micro_skills.mjs
49
+ d86952e411316bf1ae1ec06a4826f079c1f5f8404f98339c52754b1189a2fe0d src/core-isomorphic/diagnostics/prompt_hygiene_governor.mjs
50
+ dc20b5634ac51c46d2a4a806d31b6edc4bf39a85ff54d23576e5d3574537f5c8 src/core-isomorphic/economics/billingBlocks.mjs
51
+ 11686d2a1b9a1a1c07e300ef4dd714ef7f34e9697f35a03022c7f51aeaaf16dc src/core-isomorphic/economics/cacheGravity.mjs
52
+ 8935c72b4edba77dd8552161dbf88ee6e90f71d33164df990adb30d30106342c src/core-isomorphic/economics/cliffBreaker.mjs
53
+ 62933049add5d67283d270aa4bb9a3529cc3d5d710f2dd22ec9f58044e9a7421 src/core-isomorphic/economics/driftLatency.mjs
54
+ 6f5432302f73f49eb3b92521f4271e217d49c80aeec45dc925a7875cae1fde77 src/core-isomorphic/economics/dualTtl.mjs
55
+ 9004aeb262471812197ddebf559ae7afaa21a84a535d906aa17b4501b5d6039d src/core-isomorphic/economics/index.mjs
56
+ 2312c2f21e87506e07a2cbc1ce06c1a237dcc41d3f8c32e8d4b3c1144ab00cc1 src/core-isomorphic/economics/retentionRadar.mjs
57
+ 91250c14a16b2167f45f374dbe0cf84f1a1b0aa907754d98d6ea270384414576 src/core-isomorphic/guards/bucketBAlphaBeta.mjs
58
+ f9c7b2bfa749c8df94ded4e0c691e6bb924a5f8c9c33e016d7fe863e32b33105 src/core-isomorphic/guards/bucketBGamma.mjs
59
+ 2a3070c01deca6bd0669c2144ca04ec3addb2674905f63b1c989b750c83153d7 src/core-isomorphic/guards/bucketBHeuristics.mjs
60
+ 7f12e6f667a103a20d8a1b7c460d8783fbd222659bfb172cabecce7925646566 src/core-isomorphic/guards/circuitBreakers.mjs
61
+ 523f39b21344c3cab534f5400a85b093fdd4a3e4773af701d7df49d1b3dc4a93 src/core-isomorphic/guards/det01_03_shell_secret.mjs
62
+ e250205a50068d7bcf9450249b892ea30b76bf321d8712c6a8df7db6edad7ec3 src/core-isomorphic/guards/det04_12_thrash_rot.mjs
63
+ 0bc5ba122e448f134c1e83514e0e77014f550660b3b78a6986cc9f7b4f8e913a src/core-isomorphic/guards/det13_20_mcp_scope.mjs
64
+ b775f10e8149775d7baee538b9b3c3f8ef75bc0710bdefdab3a3fe628b5db59d src/core-isomorphic/guards/docIndexCore.mjs
65
+ 67e01dfc38c960f23b7cbd21ad83a2b638b9b0b2b7c70caee13ea1f2e6800659 src/core-isomorphic/guards/losslessPostSanitizer.mjs
66
+ a9121c43d447e5a84a261e55b0b342e0ad60425463633bb8353d09c6ae8df746 src/core-isomorphic/guards/slopsquatGate.mjs
67
+ b1210fca76b3ff17bd6da9c550ef38f71d7c8875136df47474789694e174fde2 src/core-isomorphic/index.js
68
+ e9faeb1eda3c574f734c409acbb0d16edf4a4979aefda834ab7891f6d57a5686 src/core-isomorphic/telemetry/otelExporter.mjs
69
+ 8a7591d95b7786be3c2941cbff28353fd0927d7e29e9ed232044812444be2c64 src/core-isomorphic/telemetry/scopeLockRegistry.mjs
70
+ 536b4a34d60617815ff9fa04364021e27bc80a3757bbdc6128bbd662b04b4858 src/core-isomorphic/telemetry/sprintMetrics.mjs
71
+ 13c28b7bbc6bbc73c3d20dc3da4c0540a2e5e4756d4b3e7a52df3bb5ad38927d src/core-isomorphic/telemetry/swarmTopology.mjs
72
+ 5d8a96637493ad668de194f564b0729c5ea0ef76d4b23f38c8c80b134601f813 src/core-isomorphic/telemetry/telemetryBridge.mjs
73
+ fed70137816b68b740db35fba65a443c63587d35f3b07777f9c8a17e62cf9ada src/core-isomorphic/ui/brailleSparkline.mjs
74
+ 0d1d31f9a28a31c0ae0b6d208bfd9baeb78889d69ea3e5f35427aa4ad76711b3 src/core-isomorphic/ui/costRadarSvg.mjs
75
+ 1f6afb2e454833c49f84aa5daa61d3c8c7b5a6bc6b1964aaf8992ae6fac01a5a src/core-isomorphic/ui/horizonGrid.mjs
76
+ 7991639a81f8b96985f133b10228626377e7fc59de997ce60fade39ed3913530 src/core-isomorphic/ui/horizonPanelHtml.mjs
77
+ f2b4934178898c36725a7b110b6bbf7ab9e7e5bd87b9fc099bfd067badc619e0 src/core-isomorphic/ui/modViews.mjs
78
+ 7e7d308c8d5d834ab6a181b31f626a060cebf85918a812f5cde8887f8f4922f8 src/core-isomorphic/ui/pdfReceiptGenerator.mjs
79
+ 7a472d600bfbfc1a705e436596d58ea29b2e453a0bee7017d9c89ceba6121010 src/core-isomorphic/ustf/index.mjs
80
+ 1b62f756c9fb0fe5bd5641b5a5db024893f81bc0b6962fdecc2fad240ee21d30 src/core-isomorphic/ustf/normalizer.mjs
81
+ 7daecbb735413a17e1ae6cf009643fc40c83e55090613f0ce8aa0d8eb058c779 src/core-isomorphic/ustf/schema.mjs
82
+ 4a7d57173431c64494bbfb72a81f17059648070e801c7dea027ae6321390ee46 src/core-isomorphic/utils/runtime.mjs
83
+ 677a7e03787344177a4efe2d058585c4e5b75fd5ba3e0244949b02c0107727d9 src/core/action_queue.mjs
84
+ 8195dcc055b9d497fcde6cdab1b9340c22a90c01416c70d1020d8430f5315dc3 src/core/ag_bridge.mjs
85
+ 1fce542cb95b6d84957d2a2481545101c380d94d564ed30900b6d31044c31c78 src/core/atomic_io.mjs
86
+ 548064c1de076f1c09d45e2892325b4029014b7b05b0bb9622bfee6721e51941 src/core/baseline.mjs
87
+ 62c4c4196cd6a7623aa3cbd392f32105e98ce5e2b8297dcdd953aacfda4af209 src/core/blindspot_sensors.mjs
88
+ 5f5d488403185455ecc8799102814e134d716db0503003ffdbcc53a38b993902 src/core/bucket_b_runtime.mjs
89
+ 07d52a736d4afad70fca36f976bd3003d1410c88d542d5e3413cc3e6183c00f0 src/core/classifier.mjs
90
+ d6a91e9952dc19e2e9329ac2bafaf70f244e887eb07557ab0527191d87f49ce7 src/core/coach/circuit_breakers.mjs
91
+ 76810a5bbadd720775a2c4673eedfcd31a5356e71837935a47f849b0c746834b src/core/coach/contradiction_auditor.mjs
92
+ 93d0f0e85f85af459a13141b50eaf36a0daeb18d18816e25baa69f99bff1c14c src/core/coach/effort_advisor.mjs
93
+ f16923aa9050bebf6c4d59f594ed65ef83239f8ca4064252bd7fa512cc76fff3 src/core/coach/handoff_hydrator.mjs
94
+ f39d5017fbfa4b74efb1de1246da0e12b1dae4b6d85a7db483a19fe779577cfb src/core/coach/progressive_checkpointer.mjs
95
+ c8c3548fc275e331d24d50d65e052d04cfc00d0006f8134ce0d9901f57d357c5 src/core/coach/prompt_decomposer_coach.mjs
96
+ 44d3b58b779f0aa5faa9bccbfe5b20ba909aac4cff101fe3e0812217faa6bdbe src/core/coach/reflector_queue.mjs
97
+ d4b689860b63f70542095506e2d0d3b3d70c7cbd6495e97c6e956a357e8fecc0 src/core/coach/saved_quota_ledger.mjs
98
+ 690940af3e38431c977c48f122a389afb423e2dd6915a117018a8e7c215d3e08 src/core/coach/subagent_ipi_sanitizer.mjs
99
+ 987594669fe0d185227236b014af678b876d7a406cc81fdee4d372278bc589d1 src/core/coach/subagent_phantom_auditor.mjs
100
+ a96b21a8ab36e38c0ab307f842fc7e9b09214ac872df558931edc13a1a3015b6 src/core/coach/task_quota_router.mjs
101
+ 4b71f8ce6c7ede11a3dea6a8be5a75078d28115ee16150e87c4bf6abd5760737 src/core/coach/turn_zero_gate.mjs
102
+ 67f931376e8b8821c37da79ea5414380a130e9a9a19cdd765cd8ad7c16dbb435 src/core/compaction_coach.mjs
103
+ ac22aa638bf981ec36bc8e09364107563e89d9e18c57f7a4275ec1ec7649578f src/core/config.mjs
104
+ 435679c280dae0da90efb6184d9931f4e6ac739442d896f78103d4b55115dbf8 src/core/constants.mjs
105
+ f26c5875043c567454427b43867bdcc109f592ccb5a8adbfc9f76073c1eae8f7 src/core/detectors_det01_to_16.mjs
106
+ 52bc082a7d36a489cc2c516137a9dc5046188a301fe13a5215d52c88035c9983 src/core/doc_indexer.mjs
107
+ deb44d1e64a5a69727eb8864ffffb0bba567e2e38bf2b895380e5cbf33bd9151 src/core/episodic_memory.mjs
108
+ e0db33ac41326b0c91a24d1f64194c0a7dc5fe722589b549cf6a972092c1197e src/core/fts5_output_compressor.mjs
109
+ 52a75ab19516dab060070dfa5335ab1c4cf4cbd08468b66063b6409160338a00 src/core/git_ledger.mjs
110
+ d3f0cde5e10060a722085fb5f11d2f4ee899ad8832d322839bce0db05b24fc7d src/core/handoff_audit.mjs
111
+ f3b4c3dfa134d7cdf8123c789a3417fb2abce10da5b910d39726e20695eb45b6 src/core/history.mjs
112
+ eecb252cb1bd2d80bf26bfedb2e13e9f3c9a8f9bf60174ebcbe0d86fb799a498 src/core/hook_diagnostics.mjs
113
+ ad723e47cc8602bc188727174c313ed01ea94394b15f657fb26fbd8a39c7e618 src/core/horizon_classifier.mjs
114
+ 750c588967df1df4bf2db0c7760697b5491b14890348f7e1889a0a176ceece14 src/core/horizon_config.mjs
115
+ d3b36209fe7e42a67b2dec35cac1581265a3579afc7082d9deaa4fce9d44771c src/core/host_watchdog.mjs
116
+ c5588b65a9b2fa5575398638c09f45246f845ac9ef0bfdb629471f4cbabaee8f src/core/layer5_hygiene.mjs
117
+ e919b3dea03f0fb8e372357519c35dc9feb3a1ad43ef269492dad4a6ed989ecc src/core/log_resolver.mjs
118
+ 51988df3611198f7178f0b3edc95b4be56604e2afd27615acee4cb941de6b6a4 src/core/mcp_auditor.mjs
119
+ 43a4e5f9886995a57a608a6825bd7ee4b6dc95b0b46f45e35ff4229e4ab76fe3 src/core/micro_skills_store.mjs
120
+ 31128ae45084833c135ddf4431d2442f9af13de01465cd8c5841c4289e1ede41 src/core/offenders.mjs
121
+ 86eb41bb9bcf85a0b44fb323b42e19914b64015d7194fae8aaae908eab5fe2f7 src/core/parser.mjs
122
+ a9e757aad5d464b629756233b8c2bceb25f3a46df99460c2061bc99de9e14bd3 src/core/path_canonicalizer.mjs
123
+ 640df0c91d782b60fad1c71c1767b5960c11f37f303838ff5cef8cde1bfb999f src/core/paths.mjs
124
+ 531c024cc5fcacd7739abfa883316d939e8d0dd47429963decb63044f2b6a652 src/core/prefix_cache_shield.mjs
125
+ 18d79c7ada6a6a7274ab26739249d8c2b698add780514d99cf013dc6af09f8a4 src/core/pro_license.mjs
126
+ 94bd4ee7610cd3578d30910234507b2ccfe2ef89d1b4979a071a5ad23482cc5a src/core/prompt_rubric.mjs
127
+ 8825df87bf1f5ab6ea7400aa40740850f46541ba102718d84977fa0f8c71a171 src/core/pruner.mjs
128
+ 725c6c882b68dd99b7c9b154db95f156054e813810f637c962e7cea4d5d1f3b1 src/core/quota.mjs
129
+ f99746d710ab7af8bf738b91b87555c497a1ff31dd9f294e4412d809481fb039 src/core/rsi_instinct_engine.mjs
130
+ 12399d33a302b20966465a40b723db31508fc6fb4319e48c784a438a30d61e5c src/core/rsl_clash_auditor.mjs
131
+ d1949696b83a35433f60352ea82da4378265c30c1e3ed125f2e1fffde96b375f src/core/rsl_distiller.mjs
132
+ 3d0c8967fab1995572b8f24b15e604276d88a782d4973705a8cf58ac19d9acd6 src/core/rsl_ledger.mjs
133
+ f35f7762f420abf341b3014b5627b70ca033bd04f85fec02fb0e8952a4f088bf src/core/rsl_triage.mjs
134
+ 116670ba24ab52c23139dfd292eb8c8c201114ca514c06ca9c24b22a2ceb28cc src/core/sanitizer.mjs
135
+ a177fa4b77124b165962eaf3f58be7d3f003444c6fd8133bd27f2f5b5f22576b src/core/session_auditor.mjs
136
+ b726765ac559c984f504c6b1bd1646114160b89e498d6badd7a3d207ec695741 src/core/session_forensics.mjs
137
+ f6d5573ef77460aacbeef10e0e3ce837d3502fb63c43bcab1c09c72f192939ad src/core/session_timeline.mjs
138
+ 368ef09a3aedadb636ab503c2bdccf4206504d6a3adca7f04c34a9e4c56f4c4a src/core/settings.mjs
139
+ 861218eb2570b2580e0fe998a50d26d401b5c0e99c4c2b6b428b0caa263e30e4 src/core/shared/detectors.mjs
140
+ 3276ebb0c4e751da8aeb5336f6c61c2ce42ae6214172372f7f927cfcce567d79 src/core/shared/fnv1a64.mjs
141
+ 6d435df003b7cc9c1d27ecd361a8a22de2d05c7008ac6ba38e46a0dcfb95c53d src/core/shared/handoff_schema.mjs
142
+ 0644d16bad3e4db27cab7cfd5705eb1f3f93b7478accfb7e73596bcc48ded28b src/core/shared/index.mjs
143
+ 256c38ad99927a0b9c0db84ad8359c8c09bdd71d917865da8bd687343c5e6676 src/core/shared/ipi_sanitizer.mjs
144
+ ba3319b700b0b1c09476f1f7410b61b3a1370bb131eb6e5912a2d8b9c00930fb src/core/shared/micro_skills.mjs
145
+ e2c09f60a3224e83e8190f4ea7896f4ffd6bcc910306d3100092be08b67ce037 src/core/shared/plugin_validator.mjs
146
+ 982fd5dedf5b0fd297e35d92bc8611188ae2bafc1d12bae32dcfbdf896e9bd7c src/core/shared/prompt_hygiene_governor.mjs
147
+ d0eebaa7c98348c84ace0d9fd909e83277f75596491530dd2704534ad3b121ff src/core/shield_manager.mjs
148
+ c53f2ef3ca76a9dd6133009b27c209e4fc2b6bc0cb5b8482011fd81036d56b6b src/core/sidecar_store.mjs
149
+ 79f9be94f34cc664d87f5e89a421bd66a90a9cace30500c5bb1586b17c955899 src/core/sprint_metrics.mjs
150
+ 4b2d8b9c989e7ca022f4497dcacd9e339b6db212d3e5c3fe0c0fa3f18c72d8fd src/core/sqlite_client.mjs
151
+ 85f2c168749240ac6dbe8c27b16edc2b80c16db92017b9b190bd7bf56519b602 src/core/storage_doctor.mjs
152
+ 75d1a51fb46ce0346d237c0828e45b3f5cb9a27ce92629f03878759ba0462a77 src/core/subagents.mjs
153
+ 61b60218c3a5e3d719d254efd09898fa1bf4056ded6738c48fc60a0eefed9839 src/core/swarm_topology.mjs
154
+ f9baf77ff02c758f746aa67339f615ac93f163e0e3bee2661c5bdb8ab4fdad78 src/core/task_quota_router.mjs
155
+ 74a43d9a841ddbf167001b65ed3d882383a39cad14b200808b9f27e5422d9a04 src/core/telemetry/cache_ttl_watchdog.mjs
156
+ fe59fb4d42855c014634e704951f8f69c759e548aff0efac125f263cd5a21b0d src/core/telemetry/scope_lock_registry.mjs
157
+ 2583112baedca067473c7fa0ca6e0450ef53e25b9ab6ed6b2e96c05233f93ea0 src/core/telemetry/shadow_file_detector.mjs
158
+ 2ae660f58a65183053292d7ac738cbbe5fdad88f59787358ed8e19b00f50d0c8 src/core/telemetry/trajectory_watcher.mjs
159
+ 79b256ede4196580e6cb8377f94a76deae30a697730d83630f4b5e124df6155c src/core/timeline_svg.mjs
160
+ f679fd3ec0650310de0021c3ac88592ba54789d04022e44876f021143b38a21b src/core/tool_surgeon.mjs
161
+ 7739201df50020de8084058e6d2318dc44a682b234ac8b2a845b5876cd7299af src/core/trajectory_stitcher.mjs
162
+ 8ce1e09cfa98d9618c38467cb910405948eaa628807ba3f92aa95eddcb3b48d2 src/core/u_shaped_optimizer.mjs
163
+ 8f5f7a639a5ed20004492f429c5868ffa48beea9f52776454a8a4f1cdb2f7694 src/core/wal_hygiene.mjs
164
+ 8b4206a242885fa77a94111fb48d25100598bc43ff90b3e8772ad57476a2d261 src/webview/advanced_view.html
165
+ 94ed044e3601ed2fe5fc72097a2ea0b7b192f3329bc5e009beba03f828f72015 src/webview/horizon_panel.html
166
+ e095af0f9df875970bc6a12fd688251ca7259955956a1b9a4a75f4317c17456d src/webview/simple_view.html
package/LICENSE ADDED
@@ -0,0 +1,27 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Gizzant (Antigravity Systems Architecture)
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
22
+
23
+ ---
24
+
25
+ Open-Core Dual-License Notice:
26
+ The MIT License above applies to `@ctxtop/core`, `@ctxtop/antigravity`, `@ctxtop/claude-code`, the 40-cell HUD, 5-minute TTL clock, `--roast`, and advisory `COACH` guards.
27
+ Commercial modules under `packages/pro/**` (`@ctxtop/pro`) and `src/core/pro_license.mjs` are governed by `packages/pro/LICENSE-COMMERCIAL.md`.
package/README.md CHANGED
@@ -1,3 +1,351 @@
1
- # Temporary Holding Version
1
+ <div align="center">
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ # Highbeam (ctxtop v4.0) — Active Context Surgeon, KV-Cache Shield & Token FinOps for Claude Code & Google Antigravity
4
+
5
+ **Local Context Window Profiler, KV-Cache TTL Monitor & Deterministic PreInvocation / PreToolUse Surgeon (`~0.18ms` Tier-1 In-Process / `~25–90ms` Tier-2 CLI Hook) for Claude Code & Google Antigravity**
6
+
7
+ [![Zero Runtime Dependencies](https://img.shields.io/badge/dependencies-0_runtime-brightgreen.svg)](#systems-architecture--zero-trust-security)
8
+ [![Hook Latency](https://img.shields.io/badge/Tier--1_in--process-~0.18ms_p95_%7C_Tier--2_CLI_hook-~25--90ms-00e5ff.svg)](#deterministic-preinvocation-router--6-local-sensors)
9
+ [![Node.js >= 20](https://img.shields.io/badge/node-%3E%3D20_zero_deps-339933.svg)](#quick-start)
10
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
11
+ [![Claude Code & Antigravity](https://img.shields.io/badge/Hosts-Claude_Code_%2B_Google_Antigravity-blueviolet.svg)](#-installation--quick-start)
12
+
13
+ [**Live Interactive Demo**](https://gizzant.github.io/attention-horizon-antigravity/) • [**Quick Start**](#-installation--quick-start) • [**Cookbook & Recipes**](docs/COOKBOOK.md) • [**Systems Architecture**](#systems-architecture--zero-trust-security)
14
+
15
+ <br/>
16
+
17
+ <img src="assets/hero-demo.svg" alt="Highbeam 40-Cell ANSI HUD & PreInvocation Router" width="100%" />
18
+
19
+ </div>
20
+
21
+ ---
22
+
23
+ ## ⚡ Installation & Quick Start
24
+
25
+ | **Google Antigravity** *(1-Line Install)* | **Claude Code** *(1-Line Install)* |
26
+ | :--- | :--- |
27
+ | ```bash
28
+ npx ctxtop init
29
+ ``` | ```bash
30
+ npx ctxtop install --claude
31
+ ``` |
32
+ | *Workspace-only*: `npx ctxtop init --workspace`<br/>*Health check*: `npx ctxtop doctor` | *StatusLine HUD*: `npx ah-statusline --demo`<br/>*In-chat pane*: `/horizon` · `/cost-radar` · `/handoff` |
33
+
34
+ ### Your First 5 Minutes After Installing
35
+
36
+ #### 1. Google Antigravity Workflow
37
+ 1. **Install hooks & sidecar**: Run `npx ctxtop init` in your project root (or globally).
38
+ 2. **Open the Highbeam Sidepane**: Launch the local telemetry WebView (`npx ctxtop --serve` or via the Antigravity sidepane) to view real-time context health:
39
+ - **Simple View (Default)**: 4 glanceable zones—**Zone A** (Safe Headroom & Warm KV Cache TTL), **Zone B** (`DO / AVOID / HOLD` Model & Effort switch guidance), **Zone C** (Live automated interventions), and **Zone D** (Verified tokens/USD saved + 1-click `/compact`).
40
+ - **Advanced View (1-Click Toggle)**: Expands the **40-Cell Chrono-Positional Recall Grid** (`Primacy 0–30%`, `Mid-Trough 30–70%`, `Recency 70–100%`), top token consumer file table, `Off / Coach / Auto-Pilot` mode switcher, and the full `DET-01..32` guard log.
41
+ 3. **Code normally**: Highbeam runs in **`COACH` mode** by default—automatically compressing verbose CLI test dumps via SQLite FTS5 and folding repeat file reads without interrupting your prompts.
42
+
43
+ #### 2. Claude Code Workflow
44
+ 1. **Install plugin & hooks**: Run `npx ctxtop install --claude` to wire `.claude-plugin/plugin.json`, `hooks/hooks.json`, and the live terminal `statusLine`.
45
+ 2. **Watch the Live Terminal `statusLine`**: At the bottom of your terminal, Highbeam renders an auto-adapting (`80 / 110 / 144` col) telemetry bar:
46
+ ```text
47
+ AH [SCCCCCCC................] sonnet-5-5 64k/200k (32%) · Cache 88% (4m12s) · COACH · Saved $1.84
48
+ ```
49
+ 3. **Open the In-Chat Docked HUD**: Type `/horizon` in chat (or run `npx ah-claude panel` for the standalone HTML workbench) to inspect cache gravity, active guards, and reclaimable tokens.
50
+
51
+ ---
52
+
53
+ ## 🧭 Built-In Slash Skills & In-Chat Commands (Both Hosts)
54
+
55
+ All 6 slash skills are registered identically in both **Google Antigravity** (`plugin.json`) and **Claude Code** (`.claude-plugin/plugin.json`):
56
+
57
+ | Slash Command / Skill | When to Use It | What It Outputs |
58
+ | :--- | :--- | :--- |
59
+ | **`/horizon`** | Anytime during a coding session | Renders the live 40-cell Context Health HUD, KV-Cache TTL countdown, active `DO / AVOID / HOLD` guidance, and reclaimable clutter breakdown. |
60
+ | **`/precheck`** | Before sending a complex refactor prompt or switching models | Audits prompt specificity (6-dimension rubric), checks horizon-aware KV-cache break-even (`C_max` & warm-request payback), and recommends the optimal Model & Effort tier. |
61
+ | **`/handoff`** | Before running `/compact` or `/clear` at `>=75%` context fill | Distills active plan checkboxes, modified files, and unresolved `stderr` into a compressed `<1,000`-token checkpoint (`task.md` / `.handoff.md`). |
62
+ | **`/cost-radar`** | When reviewing session token burn or cache busts | Generates an interactive HTML/SVG timeline of prefix-cache retention, `DET-30` thinking drift loops, and subagent worktree topology. |
63
+ | **`/inspect`** | When diagnosing slow tools or subagent fan-out | Visualizes session trajectory call-tree spans, per-tool latencies, and token attribution as a standalone artifact. |
64
+ | **`/evolve`** | After correcting agent mistakes across a session | Audits `AGENTS.md` / `CLAUDE.md` Turn-0 prefix budget (`<=20k` tok) and synthesizes validated session instincts via 1-click diff approval. |
65
+
66
+ **Quick In-Chat Prompt Prefixes:**
67
+ - `! <prompt>` — Bypass `PreInvocation` checks for a single turn.
68
+ - `!lock <prompt>` — Freeze current reasoning effort tier and prefix state for the remainder of the session.
69
+ - `#check <prompt>` — Force an explicit pre-flight scorecard and concrete prompt rewrite suggestion.
70
+
71
+ ---
72
+
73
+ ## 🛡️ Verified Token Receipt: `+164.0k` Tokens Saved in One 4-Step Coding Loop
74
+
75
+ Most CLI trackers passively count tokens *after* your quota is already burned. Highbeam intercepts redundant reads, compresses noisy test dumps via local SQLite FTS5, and shields warm KV prefixes **before** they hit your billing meter:
76
+
77
+ <div align="center">
78
+ <img src="assets/zone_c_step3_shield_full.png" alt="Highbeam Zone C Active Protection & Verified Token Receipt (+164.0k tokens saved)" width="460" />
79
+ </div>
80
+
81
+ | Step in Coding Loop | Developer / Agent Action | Highbeam Active Intervention (Zone C) | Verified Savings |
82
+ | :--- | :--- | :--- | :---: |
83
+ | **1. Warm KV Cache + Repeat Read** | Agent re-reads an unmodified 800-line source file on a `100k` warm cache | **GUARD-4** intercepts the duplicate read (`AST signature stub`) and preserves the `95%` warm KV cache discount | **`+95.0k` tok** *(KV cache)*<br/>**`+800` tok** *(deduped read)* |
84
+ | **2. Failing Test Suite Dump** | `npm test` dumps `120+` lines of verbose stdout (`~11.4k` tokens) | **SQLite FTS5 BM25 Compressor** indexes raw stdout locally and injects only the 160-token failing assertion digest | **`+11.2k` tok** |
85
+ | **3. Mid-Session Rule Edit** | Agent updates `AGENTS.md` / `CLAUDE.md` while `60k` prefix is warm (`2m 55s` TTL left) | **PrefixCacheShield** queues the rule delta until TTL expiry or `/compact`, preventing a cold prefix rebuild | **`+57.0k` tok** |
86
+ | **Total Verified Session Receipt** | **4-Step Feature / Bugfix Loop** | **Zero context dilution · 100% critical error retention** | **`+164.0k` tok (`~$0.33`)** |
87
+
88
+ ---
89
+
90
+ ## 💡 Why Saved Tokens Multiply (`O(N²)` Turn Compounding, Quota Life & Model IQ)
91
+
92
+ In agentic coding, every turn re-sends the entire prior conversation history. A single `15,000`-token raw test dump on Turn 5 is not billed once—it is re-sent on Turns 6 through 25, burning **`300,000` cumulative tokens** (`15,000 × 20`).
93
+
94
+ 1. **For Fixed-Subscription Users (`Claude Pro / Max`, `Antigravity OAuth Seats`) — Stop 2:00 PM Quota Lockouts & Context Rot**:
95
+ - Compressing noisy tool outputs and duplicate file reads on early turns prevents `O(N²)` history compounding, **stretching 5-hour sprint quotas by `30%–50%`**.
96
+ - Even more importantly, keeping your session below the **70% Safe Horizon** prevents **Context Rot** (middle-window attention decay where the model starts forgetting `AGENTS.md`/`CLAUDE.md` rules, hallucinating imports, and breaking working code).
97
+ 2. **For Metered API & Enterprise Teams — Self-Expensing FinOps ROI**:
98
+ - Preventing just two accidental warm-cache busts per day (switching models mid-TTL or editing rule files on a `100k` warm prefix) plus FTS5 log compression saves **`$3–$12/day` (`$60–$240/month`) per active seat**.
99
+ 3. **Daily Cockpit Decisions No Human Can Calculate in Their Head (Zone B)**:
100
+ - *"If I downshift from Opus/Argon to Sonnet/Flash right now, will I save quota or pay a 10x cold-prefill penalty?"* — Highbeam computes the horizon-aware KV-cache break-even limit (`C_max`) and post-switch warm-request payback in real time and displays a 1-line verdict: **`Model: Hold (03:34) — switching busts warm cache · Effort: changing busts warm cache`**.
101
+
102
+ ---
103
+
104
+ ## ⚙️ What Runs Automatically (Zero-Friction `COACH` Default)
105
+
106
+ Highbeam defaults to **`COACH` mode**—performing lossless token surgery silently in the background while never blocking your chat prompt unless a true 3-strike identical failure loop or destructive git command occurs:
107
+
108
+ | Automated Feature | How It Works Under the Hood | Developer Experience |
109
+ | :--- | :--- | :--- |
110
+ | **1. SQLite FTS5 CLI & Test Output Compression** (`PostToolUse`) | Strips ANSI/progress noise, indexes full stdout in local SQLite FTS5 (`porter unicode61`), and injects only the compact failing assertion digest | **100% automatic** — saves `50%–90%` of test/build log tokens with zero lost stack traces |
111
+ | **2. Post-Edit Delta Diffs & 3rd-Read AST Stubs** (`GUARD-4` in `PreToolUse`) | When the agent re-reads a file after editing 5 lines (or reads the same unclipped file `>=3` times), returns a unified line diff or function-signature AST stub | **100% automatic** — cuts repeat-read token burn by `80%+` without interrupting the agent |
112
+ | **3. `PrefixCacheShield` Warm Rule & Effort Deferral** (`DET-09`) | Intercepts mid-session edits to `AGENTS.md` / `CLAUDE.md` while a KV cache is warm, and checks `MODEL_EFFORT_CACHE_CAPABILITIES` on effort changes: defers on `4.6` models (`EF1_46` / article), stays silent on measured cache-preserving `claude-sonnet-5-5` (`r2_effort.csv`, `n = 3` with thinking expansion) and `claude-opus-5-5` (`currency_55.csv` `effort_only_55`, behaviour **unverified**), and warns with `"unverified for this model"` on untested models | **Model-aware cache protection** — prevents silent `4.6` / rule-file cold prefix rebuilds without false-positiving on `5.5` effort |
113
+ | **4. Live Model & Effort Switch Verdict** (`Zone B`) | Evaluates remaining KV cache TTL (`5m`/`1h`) and horizon break-even (`C_max` & warm-request payback) across `MODEL / HOLD / SWITCH / LOCK` states | **Instant visual guidance** — tells you when to hold vs. switch models or lower thinking effort |
114
+ | **5. Held Downshift & Boundary Lifecycle** (`SessionStart:compact` / `Stop`) | Surfaces held `pending_downshift` after compaction via `SessionStart:compact` `systemMessage` (`0` `/v1/messages` tokens leaked) without adding custom `PreCompact` or `SessionStart` preservation templates; optional task-boundary `/compact` advisor is gated **OFF by default** (`smartCompactBoundarySuggest: false`, boundary detector **unverified**) | **Post-compact downshift handoff** — reminds `/model <target>` once after compaction, when switching avoids full pre-compact rewrites |
115
+ | **6. Git Hook-Bypass & Destructive Shell Guard** (`DET-18` / `DET-19`) | Blocks `git commit --no-verify`, `-n`, `core.hooksPath` tampering, and unconfirmed `git reset --hard` | **Zero-config repo safety** — keeps frustrated agents from bypassing your pre-commit linters |
116
+ | **7. `PreModelSwitch` Warm KV-Cache Guard** (`DET-08`) | Evaluates KV-cache TTL (`5m`/`1h`), Stop-hook shrunk rolling-median `requestsPerTurn` (`R`, cold-start placeholder prior overridden once `>= 3` non-current, non-benchmark deduplicated sessions exist in `~/.claude/projects/**/*.jsonl`), Stop-hook rolling median prompt growth (`g` tok/turn, capped at `g = 0` until `n >= 5` observed turns and a stable regime; with `< 5` observed turns, the hook omits the net dollar figure and shows payback in requests first and turns in parentheses), horizon limit `C_max`, Stop-hook rolling output shrinkage, and warm-request payback (`AUTO_PILOT`). **Catalog-derived per-pair payback:** All break-even thresholds (`C*`, `C_max`), cold-write penalties, and warm-request paybacks (`~a / b` where `a = P_write,B - P_read,A` and `b = P_read,A - P_read,B`, less output credit and `R - 1` switch-turn reads) are derived at runtime from `anthropicModelCatalog.json` with no hard-coded constants. Unknown model IDs return explicit `unknownModel: true` with `null` USD fields, no price-based hold, a one-line unknown-price advisory, and a `ctxtop doctor` `WARN`. Under headless `claude -p`/SDK, `"ask"` becomes `blocked_by_hook`; override with `"DET-08": "warn"` or `expectedRemainingTurns`. | **Protects mid-session switches** — reports payback in post-switch warm requests (turns in parentheses), allows post-compaction splits cleanly, and never hallucinates fallback prices |
117
+
118
+ ---
119
+
120
+ ## Measured behaviour (Claude Code 2.1.325)
121
+
122
+ Empirical findings from the suite (every item cites its source file; unmeasured behaviors are labeled **unverified**):
123
+
124
+ - Editing `CLAUDE.md` before `--resume` does not invalidate the cache; the old and new versions both stay in context (`T6 CC-M`, `t6_layers.csv`).
125
+ - `--append-system-prompt` is ignored on `--resume` (`T6 CC-S`, `t6_layers.csv`).
126
+ - Changing MCP servers or the tool list on resume wipes the cache (`T6 CC-T`, `t6_layers.csv`).
127
+ - `PreCompact` instructions must be plain text on stdout; JSON is dropped (`Phase 0`, `$0` binary & mock-SSE audit; Highbeam emits zero custom `PreCompact` or `SessionStart` preservation templates since `summary_smart_compact.md` found `0/6` violations up to `28.10x` compression without them).
128
+ - Auto-memory added about `23.5%` to session cost in the smart-compact fixture (`n = 2 vs 2`, `summary_smart_compact.md`); this is a cost note, not a recommendation to disable it.
129
+ - On OpenRouter, `max_tokens: 0` still generates output; cache pre-warming with 0 output works on the direct API only (`Phase 0`, `T3b`).
130
+ - A 1-hour cache costs `2x` on writes and wins once a `5–60` minute pause occurs (`T3a`).
131
+
132
+ **SDK / `stream-json` host downshift pattern (`Item 4.2`):** Interactive hooks (`SessionStart:compact`, `PostCompact`) cannot set `mainLoopModel` (`Phase 0`). In interactive Claude Code, Highbeam emits a one-line `SessionStart:compact` `systemMessage` (`0` tokens injected into `/v1/messages`, verified at `$0` on `claude.exe@2.1.325`) naming `/model <target>`, and avoids invalid `PostCompact` `hookSpecificOutput`. In SDK or `stream-json` hosts, inspect stream frames for `compact_boundary` and call `set_model` on the host controller immediately afterward — never from inside a hook.
133
+
134
+ **Resume toolset visibility (`Item 6`):** On `claude.exe@2.1.325`, `SessionStart:resume` stdin supplies `context_tokens` and `prompt_cache_likely_expired` but does not expose `tools` or `mcp_servers` (and `deferred_tools_delta` is written to `.jsonl` after `SessionStart`). Highbeam therefore hashes observable config files (`.mcp.json`, `.claude/settings*.json`, `~/.claude.json`), CLI `--mcp-config`/`--tools` flags when provided, and optional host arrays, and warns when hashes differ on large non-expired resumes (`t6_layers.csv` `CC-T`).
135
+
136
+ **Unverified items explicitly labeled:** `claude-opus-5-5` effort-change behaviour (`currency_55.csv` verified cache preservation only; reasoning output change unverified), `DET-09` effort behaviour on non-`4.6`/non-`5.5` models (`"unverified for this model"`), and `evaluateTaskBoundaryTurn` compaction suggestions (`phase1_boundary_detector.csv`: `80.00%` precision on scripted plans, `0` organic boundaries; `smartCompactBoundarySuggest` defaults to `false` and suggests only with estimated `~2-minute` pause per `summary_smart_compact.md` H4/H7).
137
+
138
+ ---
139
+
140
+ ## 🌱 Zero-Waste AI Engineering: FinOps + GreenOps (Scope 3 Compute Efficiency)
141
+
142
+ For systems engineers, re-sending a 40,000-token test log 15 times is the AI equivalent of a memory leak—it wastes datacenter GPU prefill cycles, increases time-to-first-token (TTFT) latency, and degrades reasoning quality.
143
+
144
+ For **Engineering Managers and Enterprise FinOps / Sustainability teams**, every `1,000,000` redundant frontier LLM tokens prevented avoids approximately **`~0.65 kWh` (`650 Wh`) of datacenter GPU prefill energy** (`~247g CO₂e` and associated cooling water). Highbeam's local **Corporate PDF 1.4 Expense Receipt** (`npx ctxtop receipt --pdf`) automatically reports both **Verified USD Saved (FinOps)** and **Estimated GPU Compute Energy Avoided (GreenOps / Scope 3)** with a cryptographic SHA-256 audit digest—giving teams a dual cost-and-sustainability justification with zero cloud telemetry.
145
+
146
+ ---
147
+
148
+ ## Why Highbeam (`ctxtop`) Exists (vs. Cloud LLM Observability)
149
+
150
+ Cloud trace platforms (Langfuse, Helicone, Arize) require proxying API keys over the network and only observe HTTP request/response payloads. They have **zero visibility into the local filesystem, git working tree, IDE process table, or local SQLite/JSONL session stores**.
151
+
152
+ `ctxtop` is a zero-dependency local systems profiler built on Node.js built-ins (`node:sqlite`, `node:fs`, `node:http`). It correlates local session transcripts and SQLite databases with live disk state to catch concrete failure modes that cloud proxies cannot see:
153
+
154
+ | Failure Mode | Root Cause in Agentic Sessions | How `ctxtop` Detects & Remediates It Locally |
155
+ | :--- | :--- | :--- |
156
+ | **12.5x–80x Prompt Cache Tax & Overage TTL Cliffs** | Falling from a 1-hour prompt cache tier to a 5-minute overage/fallback tier, or mutating system/MCP blocks mid-session while holding `>50k` warm tokens, triggers an uncached prefix rebuild. | Tracks Dual-TTL windows (`1h` vs `5m` main + `5m` subagent), pinpoints the exact turn/component/byte offset of prefix mutations (`computePrefixMutationDiff`), and enforces a Cold-Session Cost Gate. |
157
+ | **Compaction Lobotomy & Post-Compact Re-Read Tax** | Autocompact at 80%–95% context wipes file line numbers, active `task.md` checklists, and unresolved `stderr`, forcing the agent to re-read the same unmodified files immediately after compaction. | Deterministically distills `.handoff.md` before compaction (`>=80%` saturation), tracks post-compaction re-reads of unmodified files, and synthesizes `<1,000`-token `[▶ RESUME HERE]` packs via SQLite FTS5 BM25 episodic memory. |
158
+ | **30GB–100GB Local IDE Storage Bloat (`state.vscdb`)** | Orphaned Cursor `bubbleId:*`, `checkpointId:*`, `messageRequestContext:*`, and unreferenced `agentKv:blob:*` rows accumulate in SQLite `cursorDiskKV` until disk space or `VACUUM` locks fail. | Audits and reclaims orphaned rows via streaming read-only SQLite export (`--gc-cursor` / `--storage-gc`) without requiring a 2x-disk-space in-place `VACUUM` lock, and recovers orphaned Antigravity `brain/` artifacts (`--recover-brain`). |
159
+ | **Stale File Overwrites (`DIRTY_SNAP`)** | Developer edits or runs `git pull` on a file the agent read 10 turns ago; the agent overwrites disk changes with its stale in-context snapshot. | Compares `fs.statSync(path).mtimeMs` on disk against the last `read_file` / `view_file` step timestamp in the JSONL transcript (`+1000ms` tolerance) and injects a pre-turn re-read guard. |
160
+ | **Unseen Call-Site Breakage (`UNSEEN_CALLERS`)** | Agent modifies an exported function signature without reading downstream callers in the repo. | Runs a bounded `<8ms` regex import scan (`import ... from`, `require()`, Python `from ... import`) across workspace files (up to 250 files) and flags callers absent from the active working set. |
161
+ | **Superseded Full-File Reads & Tool Sludge (`--prune-tools`)** | Agent reads the same 800-line file 6 times, runs unreferenced exploratory `grep` searches, or retains resolved test `stderr` traces, diluting middle-window recall. | Pairs `tool_use` and `tool_result` across Antigravity, Claude Code, and Cursor while pinning Turn 0 and the newest 6 turns; truncates stale tool outputs offline with an atomic `.pre_surgeon` backup. |
162
+ | **Turn-0 MCP Schema Bloat (`SCHEMA_TAX`)** | Eagerly loaded MCP servers inject 15k–40k tokens of JSON tool schemas on Turn 0 even when never invoked. | Computes per-server Token ROI (`calls / schemaTokens`, `IDLE_BLOAT_TAX`) and dynamic `deferred_tools_delta` expansion, flagging 0-call eager servers to switch to `"loading": "lazy"`. |
163
+
164
+ ---
165
+
166
+ ## Multi-Harness v4.0 Wedge Capabilities
167
+
168
+ 1. **Cross-Harness SQLite & Protobuf Trajectory Stitcher (`src/core/trajectory_stitcher.mjs`)**:
169
+ - **Google Antigravity (`[App]`, `[IDE]`, `[CLI]`)**: Zero-dependency protobuf wire-walker (`decodeProtobufWire`) inspects `conversations/<uuid>.db` (`steps` table binary `step_payload` and `metadata` blobs) in strict read-only mode to extract `file:///` workspace URIs and stitch with `transcript_full.jsonl` and `annotations/<uuid>.pbtxt`.
170
+ - **Claude Code**: Reconstructs the `uuid -> parentUuid` DAG up to the active `leafUuid`, isolating `/rewind` branches, `file-history-snapshot` restore points, and Turn-1 `cache_creation_input_tokens`.
171
+ - **Cursor**: Correlates `composerData:<id>`, `bubbleId:<id>:<bubble>`, `messageRequestContext`, and `agentKv:blob:*` (`requestId`) with `store.db` and timestamp-less `agent-transcripts/*.jsonl`.
172
+ 2. **Subagent Worktree & File Collision Detector (`src/core/subagents.mjs`)**:
173
+ - Builds a parent-to-child subagent DAG, tracks independent 5-minute child cache TTLs, and flags `SUBAGENT_FILE_COLLISION` when `>= 2` concurrent subagent branches edit the same canonical file path.
174
+ 3. **SQLite FTS5 Episodic Memory & Git Commit Token Ledger (`src/core/episodic_memory.mjs`, `src/core/git_ledger.mjs`)**:
175
+ - Indexes historical session decisions, modified files, and resolved bug signatures into a local SQLite FTS5 (`porter unicode61`) store (`~/.ctxtop/episodic_memory.sqlite`) for `<1,000`-token BM25 retrieval.
176
+ - Correlates `.git/logs/HEAD` commit timestamps against session windows to attribute input/output tokens, cache hit %, and USD cost per git commit.
177
+ 4. **Zero-PII Sanitizer & Forensic Snapshot Exporter (`src/core/sanitizer.mjs`)**:
178
+ - Scrubs API keys (`sk-ant-*`, `sk-proj-*`, `AIza*`), GitHub PATs (`ghp_*`, `github_pat_*`), AWS keys, Bearer tokens, `.env` values, and OS home paths (`<USER_HOME>`) before exporting shareable forensic JSON snapshots.
179
+
180
+ ---
181
+
182
+ ## Quick Start
183
+
184
+ ### 1. Inspect Live Sessions, Prune Tool Sludge, or Run Storage GC
185
+ ```bash
186
+ # Audit the last 5 local sessions for duplicate file reads, dead errors & MCP schema tax
187
+ node src/cli/postmortem.mjs --last 5
188
+
189
+ # Run environment & transcript health diagnostics (hooks, SQLite/JSONL confidence, 3-way mirror SHA-256)
190
+ node src/cli/doctor.mjs
191
+
192
+ # Run offline Prefix-Safe Tool-Output Surgeon on the active session transcript (with atomic backup)
193
+ node src/cli/doctor.mjs --prune-tools --dry-run
194
+
195
+ # Recover orphaned Antigravity brain/ directories or compact Cursor state.vscdb without VACUUM locks
196
+ node src/cli/doctor.mjs --recover-brain --gc-cursor --vscdb path/to/state.vscdb --dry-run
197
+
198
+ # Print the 40-cell ANSI status bar for the active session
199
+ node src/cli/horizon_hud.mjs --live
200
+ ```
201
+
202
+ ### 2. Launch the Local Telemetry WebView (`127.0.0.1`)
203
+ ```bash
204
+ # Start the loopback sidecar daemon and open the Tufte WebView
205
+ node sidecars/horizon-daemon/server.mjs
206
+ ```
207
+
208
+ ### 3. Install Lifecycle Hooks & CLI `statusLine`
209
+ ```bash
210
+ # Global install (~/.gemini/config/plugins/agy-horizon-flightcheck)
211
+ node src/cli/init.mjs init
212
+
213
+ # Workspace-local install (.agents/plugins/agy-horizon-flightcheck)
214
+ node src/cli/init.mjs init --workspace
215
+ ```
216
+
217
+ > [!TIP]
218
+ > Looking for copy-paste recipes for Cursor 50GB storage reclamation, offline tool pruning, Antigravity brain recovery, or programmatic Node.js API snippets? See the [**`ctxtop` Cookbook & Recipes**](docs/COOKBOOK.md).
219
+
220
+ ---
221
+
222
+ ## Systems Architecture & Zero-Trust Security
223
+
224
+ `ctxtop` is engineered for strict operational safety alongside live IDE/CLI database writers:
225
+
226
+ 1. **Zero Outbound Network Connections**:
227
+ - **0 runtime `npm` dependencies** (`package.json` has no `dependencies` block).
228
+ - **0 external HTTP/HTTPS requests, telemetry beacons, or remote API calls**. All parsing, classification, and routing run 100% in-memory on the local machine.
229
+ - The local WebView daemon (`sidecars/horizon-daemon/server.mjs`) binds strictly to `127.0.0.1` (loopback only) and rejects cross-origin `Origin` or non-local `Host` headers (`HTTP 403`) to prevent DNS rebinding and drive-by localhost CSRF.
230
+ 2. **Read-Only Database & Transcript Introspection (`SQLITE_OPEN_READONLY`)**:
231
+ - Every connection to Antigravity or Cursor SQLite databases (`conversations/<uuid>.db`, `conversation_summaries.db`, `state.vscdb`, `store.db`) is opened via Node's native `node:sqlite` `DatabaseSync` with `Object.freeze({ readOnly: true })` (`SQLITE_OPEN_READONLY`). `ctxtop` can never contend for write locks with an active IDE or CLI.
232
+ - Live JSONL transcripts (`transcript_full.jsonl` / `transcript.jsonl`) are read via `fs.openSync(filePath, 'r')` using byte-offset slicing (`O(Δbytes)` per turn), falling back to full re-parse only when a step-index regression (Undo/Rewind) is detected.
233
+ 3. **Ring 1 Security, Concurrency & Context Hygiene Boundaries**:
234
+ - **`DET-19` Git Hook-Bypass Guard**: Intercepts `git` execution via `.agents/shims/` wrappers, strips `.agents/shims` from `PATH` to eliminate recursion, blocks verification evasion (`--no-verify`, standalone `-n`, `-amn`, `--no-gpg-sign`, `core.hooksPath`), and allows bypass strictly via a 60-second single-use cryptographic human nonce.
235
+ - **Zero-Token Subagent IPI Sanitizer**: Deterministically strips Unicode Tag characters, zero-width spaces, bidi overrides, HTML comments, and delimiter breakouts in `<1ms`, framing external research digests safely at prompt tails under `<untrusted_subagent_data>`.
236
+ - **Pre-Threshold ANSI Normalization (`DET-14b`)**: Strips ANSI escape sequences and collapses carriage returns (`\r`) before the 4,096-char threshold and SQLite FTS5 archival, featuring specialized noise profiles for `cargo test` and `npm install` with Critical Error-Line Recovery.
237
+ - **Concurrent Scope Lockfile (`DET-20`)**: Manages `.agents/locks/active_scopes.json` with atomic writes, auto-evicting dead PIDs and expired leases (>300s), while alerting on multi-agent file collisions with 1-click `git worktree add` commands.
238
+ 4. **Locked v4.0 Edward Tufte UI Laws**:
239
+ - **Law 1 (Raw Physical Units Only)**: Displays `Tokens + %`, `Cache Hit %`, `Waste Tokens`, and `1h/5m TTL Countdown` side-by-side—never arbitrary `0–100` gamified scores.
240
+ - **Law 2 (40-Cell Hero + Top 3–5 Riskiest Cells)**: Surfaces the top 3–5 highest-risk context cells directly below the 40-cell flamegraph with exact file paths, attention recall %, and 1-click `[Re-Anchor / Prune]` actions.
241
+ - **Law 3 (Zero-Click Passive Workload Tag)**: Passively classifies sessions into `[Mode: Read-Heavy Audit]`, `[Mode: Multi-File Refactor]`, or `[Mode: Subagent Swarm]` from tool-call ratios.
242
+ - **Law 4 (Silent-When-Nominal Watchdog)**: Host RAM and orphan process counters remain completely hidden unless an anomaly (`orphanCount > 0` or `ZOMBIE_LEAK`) occurs.
243
+
244
+ ---
245
+
246
+ ## 🔧 Configuration, Flight Modes & MCP Server (`@ctxtop/mcp`)
247
+
248
+ ### 1. Customizing `.attention-horizon.json` (Flight Modes & Detector Overrides)
249
+ Highbeam works with zero configuration out of the box (`COACH` mode). To customize behavior per-repository or globally (`~/.attention-horizon.json`), use the CLI or create `.attention-horizon.json` in your workspace root:
250
+
251
+ ```bash
252
+ # Set a detector to warn-only, block, or off via CLI
253
+ npx ctxtop config DET-08 warn
254
+ npx ctxtop config DET-19 block
255
+ ```
256
+
257
+ ```json
258
+ {
259
+ "flightMode": "COACH",
260
+ "turnZeroTokenBudget": 20000,
261
+ "detectors": {
262
+ "DET-06": "block",
263
+ "DET-07": "block",
264
+ "DET-08": "warn",
265
+ "DET-09": "block",
266
+ "DET-19": "block",
267
+ "DET-20": "warn"
268
+ }
269
+ }
270
+ ```
271
+ - **`"COACH"` *(Default)***: Compresses CLI output (`DET-07`), folds repeat file reads (`GUARD-4`), and stages warm rule edits (`DET-09`) automatically while advising on model/cache switches without blocking normal flow.
272
+ - **`"AUTO_PILOT"`**: Enforces strict pre-turn & stop-gate verification locks (e.g., requiring tests to run after source edits before session completion).
273
+ - **`"SILENT"` / `"OFF"`**: Passive telemetry collection only.
274
+
275
+ ### 2. Using Highbeam as an MCP Server (`ctxtop-mcp`)
276
+ Any MCP-compatible client (**Google Antigravity**, **Claude Code**, **Cursor**, **Windsurf**, or **Claude Desktop**) can query Highbeam's telemetry and KV-cache advisor via standard JSON-RPC stdio:
277
+
278
+ ```json
279
+ {
280
+ "mcpServers": {
281
+ "highbeam": {
282
+ "command": "npx",
283
+ "args": ["-y", "ctxtop-mcp"]
284
+ }
285
+ }
286
+ }
287
+ ```
288
+ Exposes 4 read-only MCP tools (`<5ms` response): `get_context_telemetry`, `check_cache_gravity`, `get_savings_receipt`, and `inspect_detectors`.
289
+
290
+ ---
291
+
292
+ ## Deterministic `PreInvocation` Router & 6 Local Sensors
293
+
294
+ When registered in `hooks.json`, `src/hooks/pre_invocation.mjs` evaluates incoming prompts across 8 deterministic router states (**Tier-1 In-Process Router Evaluation: `~0.18ms p95`** inside a warm V8 isolate; **Tier-2 Spawned CLI Hook End-to-End Wall Time: `~25–45ms` POSIX / `~40–90ms` Windows PowerShell** including Node process startup):
295
+
296
+ 1. `ALLOW_SILENT`: Immediate pass-through (`{}`) on `!` bypass prefix or healthy turns.
297
+ 2. `ALLOW_ACTIVE_SET`: Silent pass-through when referenced files are already warm in the last 5 turns.
298
+ 3. `ALLOW_PLAN_OR_SUBAGENT`: Silent pass-through during `/plan` mode or subagent delegation.
299
+ 4. `INJECT_CONTEXT_GUARD`: Appends a `systemMessage` warning when target files were modified externally on disk (`DIRTY_SNAP`), have unseen callers (`UNSEEN_CALLERS`), or touch deprecated paths (`LEGACY_POISON`).
300
+ 5. `STEER_SUBAGENT`: Advises `invoke_subagent` when a broad exploratory prompt would pollute a warm `>30k`-token parent context window.
301
+ 6. `HALT_HYGIENE_OR_SAFETY`: Halts execution (or warns in `advisory` mode) on context ceiling breach, 3-strike identical command error loops, or severe duplicate-read dilution.
302
+ 7. `HALT_EFFORT_OR_QUOTA`: Warns when 5-hour/7-day quota falls below the configured floor (`10%`) or when `>600`-line single-shot file rewrites risk output stream truncation.
303
+ 8. `HALT_REWRITE_SCORECARD`: Triggered via `#check` or vague cold-start prompts (`Turn <= 2`), outputting a 4-line prompt rewrite scorecard.
304
+
305
+ ---
306
+
307
+ ## CLI Commands & Forensic Postmortem
308
+
309
+ | Command | Description |
310
+ | :--- | :--- |
311
+ | `npx ctxtop init [--workspace]` | Installs Google Antigravity plugin manifests, lifecycle hooks, and sidecar configuration. |
312
+ | `npx ctxtop install --claude` | Installs Claude Code `.claude-plugin` manifest, Tier-1/Tier-2 hooks, and terminal `statusLine`. |
313
+ | `npx ctxtop doctor [--diagnostic]` | Validates hook registration, config overlays, dynamic model ceilings, 3-way WebView SHA-256 parity, and SQLite/JSONL health. |
314
+ | `npx ctxtop postmortem [--last N] [--json]` | Scans the last `N` local sessions, classifies root causes (`CONTEXT_ROT_DECAY`, `VERIFICATION_CHURN`, `SPEC_AMBIGUITY`, `CLEAN`), lists top duplicate-read files, and audits Turn-0 MCP schema overhead. |
315
+ | `npx ctxtop receipt [--markdown \| --pdf]` | Exports a SHA-256 verified FinOps + GreenOps token/USD savings receipt for the active workspace. |
316
+ | `npx ctxtop verify [--json]` | Verifies cryptographic SHA-256 integrity of all 149 release files against `CHECKSUMS.sha256`. |
317
+ | `npx ctxtop --roast` | Prints a terminal forensic summary of recent sessions with top duplicate-read file offenders and copy-pasteable remediations. |
318
+ | `npx ctxtop --serve` | Launches the local HTTP/SSE telemetry daemon (`127.0.0.1`) and interactive WebView (`/` Simple, `/advanced` Advanced). |
319
+ | `npx ctxtop --demo-animate` | Plays the 5-stage terminal crisis simulation across synthetic fixtures. |
320
+
321
+ ---
322
+
323
+ ## Verification & Benchmarks
324
+
325
+ Run the full zero-dependency test and verification suite (**1,050+ tests across 215+ suites**):
326
+
327
+ ```bash
328
+ # Full Coach, UI, & 360° Capability-Proof suite (911+ tests across 183+ suites)
329
+ npm run test:coach
330
+
331
+ # Claude Code dual-tier Mod, CLI hooks, statusLine, and 5-category ledger suite (168 tests)
332
+ npm run test:claude
333
+
334
+ # Unit & Multi-Harness Wedge suite (89 tests across 31 suites)
335
+ npm run test:unit
336
+
337
+ # Architectural verification suite (Gates 0-6 & Phases 1-7: SQLite read-only locks, JSDOM UI, MCP audit)
338
+ npm run test:gates && npm run test:phases
339
+
340
+ # End-to-end context memory & live loopback daemon integration suite (7 layers)
341
+ npm run test:e2e
342
+
343
+ # Latency benchmark (200 iterations/path: Tier-1 ~3.0ms avg / <15ms SLA, Tier-2 CLI Hook, <45ms HUD)
344
+ npm run bench
345
+ ```
346
+
347
+ ---
348
+
349
+ ## License
350
+
351
+ MIT © [Gizzant](https://github.com/Gizzant)