ctxtop 0.0.0-stage → 4.0.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 (240) hide show
  1. package/.antigravity-plugin/plugin.json +36 -0
  2. package/.claude-plugin/plugin.json +18 -0
  3. package/CHECKSUMS.sha256 +149 -0
  4. package/LICENSE +27 -0
  5. package/README.md +330 -3
  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 +145 -0
  16. package/bin/cli.mjs +3 -0
  17. package/bin/ctxtop.mjs +1474 -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 +114 -0
  25. package/config/modelCatalog.json +620 -0
  26. package/config/platformQuirks.json +19 -0
  27. package/hooks/handlers/compact-lifecycle.mjs +262 -0
  28. package/hooks/handlers/hookIo.mjs +255 -0
  29. package/hooks/handlers/hookIpcClient.mjs +83 -0
  30. package/hooks/handlers/post-tool-use.mjs +265 -0
  31. package/hooks/handlers/pre-model-switch.mjs +249 -0
  32. package/hooks/handlers/pre-tool-use.mjs +365 -0
  33. package/hooks/handlers/stop-gate.mjs +240 -0
  34. package/hooks/handlers/user-prompt-submit.mjs +143 -0
  35. package/hooks/hooks.json +81 -0
  36. package/hooks/post_invocation.mjs +13 -0
  37. package/hooks/post_tool_use.mjs +17 -0
  38. package/hooks/pre_invocation.mjs +14 -0
  39. package/hooks/pre_tool_use.mjs +97 -0
  40. package/hooks/register.js +687 -0
  41. package/hooks/session_start.mjs +14 -0
  42. package/hooks/stop.mjs +13 -0
  43. package/hooks.json +56 -0
  44. package/package.json +103 -4
  45. package/packages/antigravity/package.json +14 -0
  46. package/packages/antigravity/src/index.mjs +1 -0
  47. package/packages/claude-code/package.json +14 -0
  48. package/packages/claude-code/src/index.mjs +2 -0
  49. package/packages/core/package.json +14 -0
  50. package/packages/core/src/index.mjs +1 -0
  51. package/packages/engine-node/package.json +14 -0
  52. package/packages/engine-node/src/index.mjs +1 -0
  53. package/packages/mcp/package.json +17 -0
  54. package/packages/mcp/src/server.mjs +396 -0
  55. package/packages/pro/LICENSE-COMMERCIAL.md +19 -0
  56. package/packages/pro/README-SIGNING.md +30 -0
  57. package/packages/pro/package.json +16 -0
  58. package/packages/pro/src/index.mjs +3 -0
  59. package/packages/pro/src/team_finops_pack.mjs +241 -0
  60. package/packages/pro/workers/polar_webhook_worker.mjs +215 -0
  61. package/plugin.json +36 -0
  62. package/rules/AGENTS.md +10 -0
  63. package/sidecars/horizon-daemon/ipcServer.mjs +24 -0
  64. package/sidecars/horizon-daemon/server.mjs +2002 -0
  65. package/sidecars/horizon-daemon/sidecar.json +19 -0
  66. package/skills/cost-radar/SKILL.md +21 -0
  67. package/skills/evolve/SKILL.md +21 -0
  68. package/skills/handoff/SKILL.md +42 -0
  69. package/skills/horizon/SKILL.md +17 -0
  70. package/skills/inspect/SKILL.md +18 -0
  71. package/skills/precheck/SKILL.md +44 -0
  72. package/src/adapters/antigravity/index.mjs +79 -0
  73. package/src/adapters/claude-code/index.mjs +155 -0
  74. package/src/cli/cost_radar.mjs +70 -0
  75. package/src/cli/doctor.mjs +351 -0
  76. package/src/cli/horizon_hud.mjs +686 -0
  77. package/src/cli/init.mjs +425 -0
  78. package/src/cli/postmortem.mjs +515 -0
  79. package/src/coach/cacheGravityRouter.mjs +12 -0
  80. package/src/config/modelCatalog.json +620 -0
  81. package/src/config/platformQuirks.json +19 -0
  82. package/src/core/action_queue.mjs +264 -0
  83. package/src/core/ag_bridge.mjs +346 -0
  84. package/src/core/atomic_io.mjs +124 -0
  85. package/src/core/baseline.mjs +607 -0
  86. package/src/core/blindspot_sensors.mjs +399 -0
  87. package/src/core/classifier.mjs +1757 -0
  88. package/src/core/coach/circuit_breakers.mjs +650 -0
  89. package/src/core/coach/contradiction_auditor.mjs +239 -0
  90. package/src/core/coach/effort_advisor.mjs +143 -0
  91. package/src/core/coach/handoff_hydrator.mjs +483 -0
  92. package/src/core/coach/progressive_checkpointer.mjs +551 -0
  93. package/src/core/coach/prompt_decomposer_coach.mjs +141 -0
  94. package/src/core/coach/reflector_queue.mjs +505 -0
  95. package/src/core/coach/saved_quota_ledger.mjs +615 -0
  96. package/src/core/coach/subagent_ipi_sanitizer.mjs +200 -0
  97. package/src/core/coach/subagent_phantom_auditor.mjs +261 -0
  98. package/src/core/coach/task_quota_router.mjs +955 -0
  99. package/src/core/coach/turn_zero_gate.mjs +574 -0
  100. package/src/core/compaction_coach.mjs +1126 -0
  101. package/src/core/config.mjs +214 -0
  102. package/src/core/constants.mjs +1800 -0
  103. package/src/core/detectors_det01_to_16.mjs +1474 -0
  104. package/src/core/episodic_memory.mjs +135 -0
  105. package/src/core/fts5_output_compressor.mjs +359 -0
  106. package/src/core/git_ledger.mjs +189 -0
  107. package/src/core/handoff_audit.mjs +558 -0
  108. package/src/core/history.mjs +221 -0
  109. package/src/core/hook_diagnostics.mjs +158 -0
  110. package/src/core/horizon_classifier.mjs +326 -0
  111. package/src/core/horizon_config.mjs +802 -0
  112. package/src/core/host_watchdog.mjs +200 -0
  113. package/src/core/layer5_hygiene.mjs +966 -0
  114. package/src/core/log_resolver.mjs +231 -0
  115. package/src/core/mcp_auditor.mjs +138 -0
  116. package/src/core/micro_skills_store.mjs +91 -0
  117. package/src/core/offenders.mjs +161 -0
  118. package/src/core/parser.mjs +1996 -0
  119. package/src/core/path_canonicalizer.mjs +73 -0
  120. package/src/core/paths.mjs +310 -0
  121. package/src/core/prefix_cache_shield.mjs +386 -0
  122. package/src/core/pro_license.mjs +385 -0
  123. package/src/core/prompt_rubric.mjs +518 -0
  124. package/src/core/pruner.mjs +433 -0
  125. package/src/core/quota.mjs +1860 -0
  126. package/src/core/rsi_instinct_engine.mjs +1197 -0
  127. package/src/core/sanitizer.mjs +121 -0
  128. package/src/core/session_forensics.mjs +303 -0
  129. package/src/core/session_timeline.mjs +358 -0
  130. package/src/core/settings.mjs +99 -0
  131. package/src/core/shared/detectors.mjs +1342 -0
  132. package/src/core/shared/fnv1a64.mjs +85 -0
  133. package/src/core/shared/handoff_schema.mjs +123 -0
  134. package/src/core/shared/index.mjs +5 -0
  135. package/src/core/shared/ipi_sanitizer.mjs +165 -0
  136. package/src/core/shared/micro_skills.mjs +1 -0
  137. package/src/core/shared/plugin_validator.mjs +202 -0
  138. package/src/core/shared/prompt_hygiene_governor.mjs +1 -0
  139. package/src/core/sidecar_store.mjs +302 -0
  140. package/src/core/sprint_metrics.mjs +366 -0
  141. package/src/core/sqlite_client.mjs +283 -0
  142. package/src/core/storage_doctor.mjs +358 -0
  143. package/src/core/subagents.mjs +609 -0
  144. package/src/core/swarm_topology.mjs +360 -0
  145. package/src/core/task_quota_router.mjs +1656 -0
  146. package/src/core/telemetry/cache_ttl_watchdog.mjs +284 -0
  147. package/src/core/telemetry/scope_lock_registry.mjs +578 -0
  148. package/src/core/telemetry/shadow_file_detector.mjs +291 -0
  149. package/src/core/telemetry/trajectory_watcher.mjs +259 -0
  150. package/src/core/timeline_svg.mjs +236 -0
  151. package/src/core/tool_surgeon.mjs +305 -0
  152. package/src/core/trajectory_stitcher.mjs +645 -0
  153. package/src/core/u_shaped_optimizer.mjs +789 -0
  154. package/src/core/wal_hygiene.mjs +233 -0
  155. package/src/core-isomorphic/catalog/detectorCatalog.mjs +558 -0
  156. package/src/core-isomorphic/catalog/index.mjs +1 -0
  157. package/src/core-isomorphic/coach/cacheGravityRouter.mjs +720 -0
  158. package/src/core-isomorphic/coach/microSkills.mjs +1 -0
  159. package/src/core-isomorphic/coach/promptHygieneGovernor.mjs +1 -0
  160. package/src/core-isomorphic/coach/repoCalibration.mjs +254 -0
  161. package/src/core-isomorphic/coach/savedQuotaLedger.mjs +527 -0
  162. package/src/core-isomorphic/coach/stateBatonHydrator.mjs +810 -0
  163. package/src/core-isomorphic/coach/ttlWatchdog.mjs +457 -0
  164. package/src/core-isomorphic/config/anthropicModelCatalog.json +203 -0
  165. package/src/core-isomorphic/config/catalogLoader.mjs +768 -0
  166. package/src/core-isomorphic/config/horizonConfig.mjs +1009 -0
  167. package/src/core-isomorphic/control/callTree.mjs +338 -0
  168. package/src/core-isomorphic/control/coachLatches.mjs +126 -0
  169. package/src/core-isomorphic/control/controlStateMachine.mjs +205 -0
  170. package/src/core-isomorphic/control/index.mjs +49 -0
  171. package/src/core-isomorphic/control/swarmWorktree.mjs +109 -0
  172. package/src/core-isomorphic/control/toolSuspension.mjs +197 -0
  173. package/src/core-isomorphic/diagnostics/drift_guard.mjs +382 -0
  174. package/src/core-isomorphic/diagnostics/index.mjs +9 -0
  175. package/src/core-isomorphic/diagnostics/micro_skills.mjs +471 -0
  176. package/src/core-isomorphic/diagnostics/prompt_hygiene_governor.mjs +622 -0
  177. package/src/core-isomorphic/economics/billingBlocks.mjs +251 -0
  178. package/src/core-isomorphic/economics/cacheGravity.mjs +351 -0
  179. package/src/core-isomorphic/economics/cliffBreaker.mjs +170 -0
  180. package/src/core-isomorphic/economics/driftLatency.mjs +319 -0
  181. package/src/core-isomorphic/economics/dualTtl.mjs +198 -0
  182. package/src/core-isomorphic/economics/index.mjs +47 -0
  183. package/src/core-isomorphic/economics/retentionRadar.mjs +348 -0
  184. package/src/core-isomorphic/guards/circuitBreakers.mjs +1202 -0
  185. package/src/core-isomorphic/guards/det01_03_shell_secret.mjs +1035 -0
  186. package/src/core-isomorphic/guards/det04_12_thrash_rot.mjs +480 -0
  187. package/src/core-isomorphic/guards/det13_20_mcp_scope.mjs +603 -0
  188. package/src/core-isomorphic/guards/losslessPostSanitizer.mjs +301 -0
  189. package/src/core-isomorphic/index.js +26 -0
  190. package/src/core-isomorphic/telemetry/otelExporter.mjs +187 -0
  191. package/src/core-isomorphic/telemetry/scopeLockRegistry.mjs +522 -0
  192. package/src/core-isomorphic/telemetry/sprintMetrics.mjs +327 -0
  193. package/src/core-isomorphic/telemetry/swarmTopology.mjs +152 -0
  194. package/src/core-isomorphic/telemetry/telemetryBridge.mjs +1132 -0
  195. package/src/core-isomorphic/ui/brailleSparkline.mjs +142 -0
  196. package/src/core-isomorphic/ui/costRadarSvg.mjs +276 -0
  197. package/src/core-isomorphic/ui/horizonGrid.mjs +475 -0
  198. package/src/core-isomorphic/ui/horizonPanelHtml.mjs +1181 -0
  199. package/src/core-isomorphic/ui/modViews.mjs +1478 -0
  200. package/src/core-isomorphic/ui/pdfReceiptGenerator.mjs +329 -0
  201. package/src/core-isomorphic/ustf/index.mjs +7 -0
  202. package/src/core-isomorphic/ustf/normalizer.mjs +512 -0
  203. package/src/core-isomorphic/ustf/schema.mjs +186 -0
  204. package/src/core-isomorphic/utils/runtime.mjs +962 -0
  205. package/src/demo/synthetic_states.mjs +661 -0
  206. package/src/diagnostics/bugReportGenerator.mjs +253 -0
  207. package/src/diagnostics/doctorEngine.mjs +203 -0
  208. package/src/engine-node/db/index.mjs +58 -0
  209. package/src/engine-node/db/jsonl_fallback.mjs +184 -0
  210. package/src/engine-node/db/probe.mjs +110 -0
  211. package/src/engine-node/db/sqlite_wrapper.mjs +122 -0
  212. package/src/engine-node/index.mjs +9 -0
  213. package/src/engine-node/ipc/client.mjs +447 -0
  214. package/src/engine-node/ipc/index.mjs +22 -0
  215. package/src/engine-node/ipc/protocol.mjs +177 -0
  216. package/src/engine-node/ipc/server.mjs +445 -0
  217. package/src/engine-node/offloader/index.mjs +6 -0
  218. package/src/engine-node/offloader/tool_offloader.mjs +241 -0
  219. package/src/engine-node/sensors/blindspots.mjs +369 -0
  220. package/src/engine-node/sensors/git_merge_tree.mjs +223 -0
  221. package/src/engine-node/sensors/index.mjs +7 -0
  222. package/src/hooks/portfolio_runtime.mjs +858 -0
  223. package/src/hooks/post_invocation.mjs +419 -0
  224. package/src/hooks/pre_invocation.mjs +1015 -0
  225. package/src/hooks/session_start.mjs +161 -0
  226. package/src/shims/agy_cli_compressor.mjs +705 -0
  227. package/src/shims/agy_git_guard.mjs +749 -0
  228. package/src/shims/ah_log_query.mjs +39 -0
  229. package/src/ui/costRadarSvg.mjs +6 -0
  230. package/src/ui/horizonGrid.mjs +1 -0
  231. package/src/ui/horizonPanelHtml.mjs +1 -0
  232. package/src/ui/horizon_panel.css +167 -0
  233. package/src/ui/horizon_panel.js +212 -0
  234. package/src/ui/modViews.mjs +1 -0
  235. package/src/utils/nodeIo.mjs +59 -0
  236. package/src/utils/runtime.mjs +1 -0
  237. package/src/webview/advanced_view.html +1808 -0
  238. package/src/webview/horizon_panel.html +11389 -0
  239. package/src/webview/registry.mjs +80 -0
  240. 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.0.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.0.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,149 @@
1
+ 1228fd40f8df273b072f36dfb65511469df68c0156bdfe2499dd08d1ef426d22 .claude-plugin/plugin.json
2
+ 942ed93980fce95389d25be2fbefee742bf85dc572b25bf43c6f5478b2bfe73b bin/ah-statusline.mjs
3
+ 22c8d41c19e98b76c3ab6bdf7bcb7f63e069d68932d148b01843cf75b6fcbfb1 bin/cli.mjs
4
+ 91b28aac1972be733c26045e8280ec3e9cb326840353cfa01de1ecf5001af8b2 bin/ctxtop.mjs
5
+ 27f61277db70bdb7ad53e9c7b09e8213ef96a158314a9c2e9434721215c69c82 hooks.json
6
+ 269abf79f3436f2732294dc2f97a49c7be43027d840c2946391d9449a6f5689f hooks/handlers/compact-lifecycle.mjs
7
+ 542852a408e03b46e56f529fde6000fd50f90cf443f8d8412d06837389b4c044 hooks/handlers/hookIo.mjs
8
+ 4176a52ceb973257ae80e00609daddcc5a03c791fbe55ca7419cc3c4ed0946ff hooks/handlers/hookIpcClient.mjs
9
+ 0c77c7fc55cd93f70397d71b6863ae20f131cf1983f2e0299e7ee93fa5f77e9f hooks/handlers/post-tool-use.mjs
10
+ 25017293506771452d8ee57b94ee1955b8467d5288cf11ef99905bdbf00d4706 hooks/handlers/pre-model-switch.mjs
11
+ 0a8ec2261c1027f16c04bb0a3e96b62074cad65c3832bfd1615a9a7d4704b729 hooks/handlers/pre-tool-use.mjs
12
+ c78edf6a2ed4def4662a83ab3401bd8fa22ea188cf7f6268827e7012ada7734d hooks/handlers/stop-gate.mjs
13
+ ad065ed2225f5da3a5bba58ebfc33a014afd047227299ec03eaa2bab5e7fe8d2 hooks/handlers/user-prompt-submit.mjs
14
+ 2305cd31e8a677a85941b0f251323ae7a8e36b560fbbd8ab3c11efe7e6028e6d hooks/hooks.json
15
+ a0d8619335843c2b50684439a3c4d7735c74a4d1264cfb474e692ed8b5bcc51a hooks/post_invocation.mjs
16
+ 2bc710324462b482118c46c8eb9426187fd132928d969015ada70b8f5901cc96 hooks/post_tool_use.mjs
17
+ bf72514288e5618f20d6a62808b7ba496701f6a475cc23f9d168cc7c6b29a0c7 hooks/pre_invocation.mjs
18
+ e23018a16b2d70be203c138b4fd6432eb32aa039d8822bff5b55a94ef43b697c hooks/pre_tool_use.mjs
19
+ ea6c29ae1d7b0b82f0860174082bf382782c347b89f2cfa56b6e7cb1918e8724 hooks/register.js
20
+ a899abd9fbaec42410553e253fd8fd3a1ebb5ca498bbc24ae2028906301bbc4f hooks/session_start.mjs
21
+ e2725095d835bd99206e432666cc6a69f09d5ef0fb3336b1a4e0e1120d7e5d39 hooks/stop.mjs
22
+ 9f6b994d5c19977bfb99d26d0dd97095a0e6cd4bce943415e3e5da625cad5cc3 package.json
23
+ 4402964ddee27432db0f3c17bd5736ad03a11f350194be3203f3048b1dd969d3 plugin.json
24
+ d9fb54e539f684d28eb11f15a0fbcd70bc0135e011fd2ff4a090b1bcd15291b6 src/core-isomorphic/catalog/detectorCatalog.mjs
25
+ 7a27626a1d278b16f43763ac1a8cb3e2bf0d136ecadcf27a0cd5293609896baa src/core-isomorphic/catalog/index.mjs
26
+ 3200c66da39f6b2d6e169e045164b05573fc21185138312d324cef580ed6d6ae src/core-isomorphic/coach/cacheGravityRouter.mjs
27
+ eff25345c6ff2d2f6a2a76268c68125a77bd9061fffc76cc62c9045d34280c39 src/core-isomorphic/coach/microSkills.mjs
28
+ c4776ae105cbab042bc4a0da00607712fa37b70eecc8fef370dca5c111d7470f src/core-isomorphic/coach/promptHygieneGovernor.mjs
29
+ 7352055abc1158b585c48119034cfca874310517279d4ff3c4eed07baefae7f4 src/core-isomorphic/coach/repoCalibration.mjs
30
+ e1eb74a87049470e389de00a23badccb7d7d159bd118d1a19b26ad6b3710fc51 src/core-isomorphic/coach/savedQuotaLedger.mjs
31
+ f2d152885288e4bf3bb670b05ff67a2a12f8de05e72fba1f338a55902a8af56f src/core-isomorphic/coach/stateBatonHydrator.mjs
32
+ badbdae7a46db3733e839fa41edeca98a95fd1f0aaa7da7548bd3d23d131d9be src/core-isomorphic/coach/ttlWatchdog.mjs
33
+ d29f05d27267afd42da4510a455ef1dc74cc07ee104d738af79133f4c27c6b49 src/core-isomorphic/config/anthropicModelCatalog.json
34
+ e50490b908c533ef90bfb497dfaf22b8cfd117967c6288da94ec29178a6f7b90 src/core-isomorphic/config/catalogLoader.mjs
35
+ 402346530c715c85ac473b02d17fc4193aa7db33567fe2825ae0327b04b17c53 src/core-isomorphic/config/horizonConfig.mjs
36
+ 41f5a8fbb903efbb70ffe183b9646152f25ac397dfb299558a49601ed8124fe7 src/core-isomorphic/control/callTree.mjs
37
+ 9ab7b53172aaa44838823fb62c69f10f6084132c18be56535d7acd57bda0761a src/core-isomorphic/control/coachLatches.mjs
38
+ f004e367080f6f2ad8640d03111181a264e8d7cd6ed99bbd6ebbe8a53365641d src/core-isomorphic/control/controlStateMachine.mjs
39
+ 8b464583992562c54d6b44e2d88de2c23cd30e58f1d47236a061e5556c89a96c src/core-isomorphic/control/index.mjs
40
+ 8c32787061a2caa9b39fe15619ef2e8284e7b4a78d7fcd3d2ee2073eeca685ec src/core-isomorphic/control/swarmWorktree.mjs
41
+ eba94306f2d23381f78d58c333261db5e551517a21a2d0b29f0f9ccd2d3b8dac src/core-isomorphic/control/toolSuspension.mjs
42
+ e9523d7d0e9f09d99a5e43e4723d6662e9fb777ed8c8df066c6e68b57ad22de4 src/core-isomorphic/diagnostics/drift_guard.mjs
43
+ 7925a319fcc0f4021a00c55d0344bf01c6175b1139e3127469c59a96e03eee32 src/core-isomorphic/diagnostics/index.mjs
44
+ 2acb7a21d8000bbcfbafeb6b3406a4d04927b2b0c4888c08daad59fbc9d3dee8 src/core-isomorphic/diagnostics/micro_skills.mjs
45
+ 0a63a965a9d13bc3c62a9df8ffc53dff7050e583a0788204a0e2f825cbffe8dd src/core-isomorphic/diagnostics/prompt_hygiene_governor.mjs
46
+ dc20b5634ac51c46d2a4a806d31b6edc4bf39a85ff54d23576e5d3574537f5c8 src/core-isomorphic/economics/billingBlocks.mjs
47
+ 8d30593a5ea1c3dddcc1d28af0b769d4bde5f9e35ef0a217c89bd3a3dcd66003 src/core-isomorphic/economics/cacheGravity.mjs
48
+ 8e9acf7f16e82e87bed9903fe6bd119817dc711c6e0b47b0571ac39497a385c3 src/core-isomorphic/economics/cliffBreaker.mjs
49
+ 398ca8f8e96d1187309ba0ba5e69c91b180f3fa9a2c15754b8163d16f42f77af src/core-isomorphic/economics/driftLatency.mjs
50
+ 6f5432302f73f49eb3b92521f4271e217d49c80aeec45dc925a7875cae1fde77 src/core-isomorphic/economics/dualTtl.mjs
51
+ 9004aeb262471812197ddebf559ae7afaa21a84a535d906aa17b4501b5d6039d src/core-isomorphic/economics/index.mjs
52
+ 2312c2f21e87506e07a2cbc1ce06c1a237dcc41d3f8c32e8d4b3c1144ab00cc1 src/core-isomorphic/economics/retentionRadar.mjs
53
+ a9ebae69c07e3447dff72a31fce40dbd6b10811f4545b82c5b5b86d9a9959d8d src/core-isomorphic/guards/circuitBreakers.mjs
54
+ ee884c215aa72af78833127d9d39fadbf6b22567c029031139341bb76f058d03 src/core-isomorphic/guards/det01_03_shell_secret.mjs
55
+ 5c5c80e77f56a819df1cd2abeb49b3b70253134c20bea6721f9883d268d4f689 src/core-isomorphic/guards/det04_12_thrash_rot.mjs
56
+ 2225cdd1978a4feb942fa561f1d06837ca9013192eec39401c315fd2e991aafc src/core-isomorphic/guards/det13_20_mcp_scope.mjs
57
+ b3730b8b19f54a5a6b4b540885e8aeb463420607cd2eb163af7b1a3612fe5d6d src/core-isomorphic/guards/losslessPostSanitizer.mjs
58
+ 6fc8231716c0e930116b6cd46fbd94b5f1639a4cf6b567032d458c3072226c26 src/core-isomorphic/index.js
59
+ e9faeb1eda3c574f734c409acbb0d16edf4a4979aefda834ab7891f6d57a5686 src/core-isomorphic/telemetry/otelExporter.mjs
60
+ 8a7591d95b7786be3c2941cbff28353fd0927d7e29e9ed232044812444be2c64 src/core-isomorphic/telemetry/scopeLockRegistry.mjs
61
+ 536b4a34d60617815ff9fa04364021e27bc80a3757bbdc6128bbd662b04b4858 src/core-isomorphic/telemetry/sprintMetrics.mjs
62
+ 13c28b7bbc6bbc73c3d20dc3da4c0540a2e5e4756d4b3e7a52df3bb5ad38927d src/core-isomorphic/telemetry/swarmTopology.mjs
63
+ 0acd2d6e8b6e42e421f0175a3a3f4c2d2ef6c36c1762dfbeaf68dd86ca2e8b49 src/core-isomorphic/telemetry/telemetryBridge.mjs
64
+ fed70137816b68b740db35fba65a443c63587d35f3b07777f9c8a17e62cf9ada src/core-isomorphic/ui/brailleSparkline.mjs
65
+ 0d1d31f9a28a31c0ae0b6d208bfd9baeb78889d69ea3e5f35427aa4ad76711b3 src/core-isomorphic/ui/costRadarSvg.mjs
66
+ 1f6afb2e454833c49f84aa5daa61d3c8c7b5a6bc6b1964aaf8992ae6fac01a5a src/core-isomorphic/ui/horizonGrid.mjs
67
+ 11708f8ac9bddae8ec7e2d0e0f3cda1537b112ac56dfaae4afbe81da5bfc710a src/core-isomorphic/ui/horizonPanelHtml.mjs
68
+ 36c72c42a545952255c1ebc04b701d45331442785657ca331e7d915e38e042a8 src/core-isomorphic/ui/modViews.mjs
69
+ 7e7d308c8d5d834ab6a181b31f626a060cebf85918a812f5cde8887f8f4922f8 src/core-isomorphic/ui/pdfReceiptGenerator.mjs
70
+ 7a472d600bfbfc1a705e436596d58ea29b2e453a0bee7017d9c89ceba6121010 src/core-isomorphic/ustf/index.mjs
71
+ 1b62f756c9fb0fe5bd5641b5a5db024893f81bc0b6962fdecc2fad240ee21d30 src/core-isomorphic/ustf/normalizer.mjs
72
+ 7daecbb735413a17e1ae6cf009643fc40c83e55090613f0ce8aa0d8eb058c779 src/core-isomorphic/ustf/schema.mjs
73
+ 4a7d57173431c64494bbfb72a81f17059648070e801c7dea027ae6321390ee46 src/core-isomorphic/utils/runtime.mjs
74
+ 677a7e03787344177a4efe2d058585c4e5b75fd5ba3e0244949b02c0107727d9 src/core/action_queue.mjs
75
+ 8195dcc055b9d497fcde6cdab1b9340c22a90c01416c70d1020d8430f5315dc3 src/core/ag_bridge.mjs
76
+ 1fce542cb95b6d84957d2a2481545101c380d94d564ed30900b6d31044c31c78 src/core/atomic_io.mjs
77
+ 548064c1de076f1c09d45e2892325b4029014b7b05b0bb9622bfee6721e51941 src/core/baseline.mjs
78
+ 62c4c4196cd6a7623aa3cbd392f32105e98ce5e2b8297dcdd953aacfda4af209 src/core/blindspot_sensors.mjs
79
+ 07d52a736d4afad70fca36f976bd3003d1410c88d542d5e3413cc3e6183c00f0 src/core/classifier.mjs
80
+ d6a91e9952dc19e2e9329ac2bafaf70f244e887eb07557ab0527191d87f49ce7 src/core/coach/circuit_breakers.mjs
81
+ 76810a5bbadd720775a2c4673eedfcd31a5356e71837935a47f849b0c746834b src/core/coach/contradiction_auditor.mjs
82
+ 93d0f0e85f85af459a13141b50eaf36a0daeb18d18816e25baa69f99bff1c14c src/core/coach/effort_advisor.mjs
83
+ f16923aa9050bebf6c4d59f594ed65ef83239f8ca4064252bd7fa512cc76fff3 src/core/coach/handoff_hydrator.mjs
84
+ f39d5017fbfa4b74efb1de1246da0e12b1dae4b6d85a7db483a19fe779577cfb src/core/coach/progressive_checkpointer.mjs
85
+ c8c3548fc275e331d24d50d65e052d04cfc00d0006f8134ce0d9901f57d357c5 src/core/coach/prompt_decomposer_coach.mjs
86
+ 44d3b58b779f0aa5faa9bccbfe5b20ba909aac4cff101fe3e0812217faa6bdbe src/core/coach/reflector_queue.mjs
87
+ d4b689860b63f70542095506e2d0d3b3d70c7cbd6495e97c6e956a357e8fecc0 src/core/coach/saved_quota_ledger.mjs
88
+ 690940af3e38431c977c48f122a389afb423e2dd6915a117018a8e7c215d3e08 src/core/coach/subagent_ipi_sanitizer.mjs
89
+ 987594669fe0d185227236b014af678b876d7a406cc81fdee4d372278bc589d1 src/core/coach/subagent_phantom_auditor.mjs
90
+ a96b21a8ab36e38c0ab307f842fc7e9b09214ac872df558931edc13a1a3015b6 src/core/coach/task_quota_router.mjs
91
+ 4b71f8ce6c7ede11a3dea6a8be5a75078d28115ee16150e87c4bf6abd5760737 src/core/coach/turn_zero_gate.mjs
92
+ 67f931376e8b8821c37da79ea5414380a130e9a9a19cdd765cd8ad7c16dbb435 src/core/compaction_coach.mjs
93
+ ac22aa638bf981ec36bc8e09364107563e89d9e18c57f7a4275ec1ec7649578f src/core/config.mjs
94
+ 0044a0afefca20ab6a833a6ccf76195bc7762ba9dafe26a3f6afb3f8f4f2c54b src/core/constants.mjs
95
+ 27fd4c22c4b958ed0b3e2558bb595336423a1ac2d15092080ad8a8256dd98e22 src/core/detectors_det01_to_16.mjs
96
+ deb44d1e64a5a69727eb8864ffffb0bba567e2e38bf2b895380e5cbf33bd9151 src/core/episodic_memory.mjs
97
+ e0db33ac41326b0c91a24d1f64194c0a7dc5fe722589b549cf6a972092c1197e src/core/fts5_output_compressor.mjs
98
+ 52a75ab19516dab060070dfa5335ab1c4cf4cbd08468b66063b6409160338a00 src/core/git_ledger.mjs
99
+ d3f0cde5e10060a722085fb5f11d2f4ee899ad8832d322839bce0db05b24fc7d src/core/handoff_audit.mjs
100
+ f3b4c3dfa134d7cdf8123c789a3417fb2abce10da5b910d39726e20695eb45b6 src/core/history.mjs
101
+ eecb252cb1bd2d80bf26bfedb2e13e9f3c9a8f9bf60174ebcbe0d86fb799a498 src/core/hook_diagnostics.mjs
102
+ ad723e47cc8602bc188727174c313ed01ea94394b15f657fb26fbd8a39c7e618 src/core/horizon_classifier.mjs
103
+ 750c588967df1df4bf2db0c7760697b5491b14890348f7e1889a0a176ceece14 src/core/horizon_config.mjs
104
+ d3b36209fe7e42a67b2dec35cac1581265a3579afc7082d9deaa4fce9d44771c src/core/host_watchdog.mjs
105
+ 7d644aabc02edc5f233eb78c87a0a9df8db2b37d83cdd9b5830cac0e87701974 src/core/layer5_hygiene.mjs
106
+ e919b3dea03f0fb8e372357519c35dc9feb3a1ad43ef269492dad4a6ed989ecc src/core/log_resolver.mjs
107
+ 51988df3611198f7178f0b3edc95b4be56604e2afd27615acee4cb941de6b6a4 src/core/mcp_auditor.mjs
108
+ 43a4e5f9886995a57a608a6825bd7ee4b6dc95b0b46f45e35ff4229e4ab76fe3 src/core/micro_skills_store.mjs
109
+ 31128ae45084833c135ddf4431d2442f9af13de01465cd8c5841c4289e1ede41 src/core/offenders.mjs
110
+ 092da492097cd779764ba0123efa6c715217a0e42261ce7f03b9aa797674a0d0 src/core/parser.mjs
111
+ a9e757aad5d464b629756233b8c2bceb25f3a46df99460c2061bc99de9e14bd3 src/core/path_canonicalizer.mjs
112
+ 8a56b10b4d4048fb83ffbf41aea7ebb87102a207c26f37522fa73611d9bdc492 src/core/paths.mjs
113
+ 531c024cc5fcacd7739abfa883316d939e8d0dd47429963decb63044f2b6a652 src/core/prefix_cache_shield.mjs
114
+ 18d79c7ada6a6a7274ab26739249d8c2b698add780514d99cf013dc6af09f8a4 src/core/pro_license.mjs
115
+ 94bd4ee7610cd3578d30910234507b2ccfe2ef89d1b4979a071a5ad23482cc5a src/core/prompt_rubric.mjs
116
+ 8825df87bf1f5ab6ea7400aa40740850f46541ba102718d84977fa0f8c71a171 src/core/pruner.mjs
117
+ 725c6c882b68dd99b7c9b154db95f156054e813810f637c962e7cea4d5d1f3b1 src/core/quota.mjs
118
+ f99746d710ab7af8bf738b91b87555c497a1ff31dd9f294e4412d809481fb039 src/core/rsi_instinct_engine.mjs
119
+ 116670ba24ab52c23139dfd292eb8c8c201114ca514c06ca9c24b22a2ceb28cc src/core/sanitizer.mjs
120
+ b726765ac559c984f504c6b1bd1646114160b89e498d6badd7a3d207ec695741 src/core/session_forensics.mjs
121
+ f6d5573ef77460aacbeef10e0e3ce837d3502fb63c43bcab1c09c72f192939ad src/core/session_timeline.mjs
122
+ 368ef09a3aedadb636ab503c2bdccf4206504d6a3adca7f04c34a9e4c56f4c4a src/core/settings.mjs
123
+ 861218eb2570b2580e0fe998a50d26d401b5c0e99c4c2b6b428b0caa263e30e4 src/core/shared/detectors.mjs
124
+ 3276ebb0c4e751da8aeb5336f6c61c2ce42ae6214172372f7f927cfcce567d79 src/core/shared/fnv1a64.mjs
125
+ 6d435df003b7cc9c1d27ecd361a8a22de2d05c7008ac6ba38e46a0dcfb95c53d src/core/shared/handoff_schema.mjs
126
+ 0644d16bad3e4db27cab7cfd5705eb1f3f93b7478accfb7e73596bcc48ded28b src/core/shared/index.mjs
127
+ 256c38ad99927a0b9c0db84ad8359c8c09bdd71d917865da8bd687343c5e6676 src/core/shared/ipi_sanitizer.mjs
128
+ ba3319b700b0b1c09476f1f7410b61b3a1370bb131eb6e5912a2d8b9c00930fb src/core/shared/micro_skills.mjs
129
+ e2c09f60a3224e83e8190f4ea7896f4ffd6bcc910306d3100092be08b67ce037 src/core/shared/plugin_validator.mjs
130
+ 982fd5dedf5b0fd297e35d92bc8611188ae2bafc1d12bae32dcfbdf896e9bd7c src/core/shared/prompt_hygiene_governor.mjs
131
+ c53f2ef3ca76a9dd6133009b27c209e4fc2b6bc0cb5b8482011fd81036d56b6b src/core/sidecar_store.mjs
132
+ 79f9be94f34cc664d87f5e89a421bd66a90a9cace30500c5bb1586b17c955899 src/core/sprint_metrics.mjs
133
+ 4b2d8b9c989e7ca022f4497dcacd9e339b6db212d3e5c3fe0c0fa3f18c72d8fd src/core/sqlite_client.mjs
134
+ 85f2c168749240ac6dbe8c27b16edc2b80c16db92017b9b190bd7bf56519b602 src/core/storage_doctor.mjs
135
+ 75d1a51fb46ce0346d237c0828e45b3f5cb9a27ce92629f03878759ba0462a77 src/core/subagents.mjs
136
+ 61b60218c3a5e3d719d254efd09898fa1bf4056ded6738c48fc60a0eefed9839 src/core/swarm_topology.mjs
137
+ d10956e05890afc19a977f5f417c1428500d253db26cb406c7e41a2f280f7350 src/core/task_quota_router.mjs
138
+ 74a43d9a841ddbf167001b65ed3d882383a39cad14b200808b9f27e5422d9a04 src/core/telemetry/cache_ttl_watchdog.mjs
139
+ fe59fb4d42855c014634e704951f8f69c759e548aff0efac125f263cd5a21b0d src/core/telemetry/scope_lock_registry.mjs
140
+ 2583112baedca067473c7fa0ca6e0450ef53e25b9ab6ed6b2e96c05233f93ea0 src/core/telemetry/shadow_file_detector.mjs
141
+ 2ae660f58a65183053292d7ac738cbbe5fdad88f59787358ed8e19b00f50d0c8 src/core/telemetry/trajectory_watcher.mjs
142
+ 79b256ede4196580e6cb8377f94a76deae30a697730d83630f4b5e124df6155c src/core/timeline_svg.mjs
143
+ f679fd3ec0650310de0021c3ac88592ba54789d04022e44876f021143b38a21b src/core/tool_surgeon.mjs
144
+ 7739201df50020de8084058e6d2318dc44a682b234ac8b2a845b5876cd7299af src/core/trajectory_stitcher.mjs
145
+ 8ce1e09cfa98d9618c38467cb910405948eaa628807ba3f92aa95eddcb3b48d2 src/core/u_shaped_optimizer.mjs
146
+ 8f5f7a639a5ed20004492f429c5868ffa48beea9f52776454a8a4f1cdb2f7694 src/core/wal_hygiene.mjs
147
+ 8b4206a242885fa77a94111fb48d25100598bc43ff90b3e8772ad57476a2d261 src/webview/advanced_view.html
148
+ 3202ada7ff019ae4fc8e8d10f97f497a88c6eda667e50d6af65f12da9b420d77 src/webview/horizon_panel.html
149
+ 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,330 @@
1
- # Temporary Holding Version
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.
1
+ <div align="center">
2
+
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 algebraic KV-cache gravity (`C*`), 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 algebraic cross-model break-even threshold (`C*`) in real time and displays a 1-line verdict: **`Model: Hold (03:34) — switching busts warm cache · Effort: OK to change`**.
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 Deferral** (`DET-09`) | Intercepts mid-session edits to `AGENTS.md` / `CLAUDE.md` while a `>=15k` KV cache is warm (`TTL > 0s`) and queues the delta until Turn 0, `/compact`, or manual `[Apply]` | **Automatic protection** — prevents silent `50k–150k` cold prefix rebuilds |
113
+ | **4. Live Model & Effort Switch Verdict** (`Zone B`) | Evaluates remaining KV cache TTL (`5m`/`1h`) and algebraic break-even `C*` across `MODEL / HOLD / SWITCH / LOCK` states | **Instant visual guidance** — tells you when to hold vs. switch models or lower thinking effort |
114
+ | **5. Pre-Compact State Baton** (`task.md` / `HANDOFF.md`) | Distills active plan checkboxes, modified file paths, and unresolved errors before `/compact` (`>=80%` saturation) | **Eliminates post-compact amnesia** — stops the agent from re-reading the same 10 files after compacting |
115
+ | **6. Git Hook-Bypass & Destructive Shell Guard** (`DET-08` / `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
+
117
+ ---
118
+
119
+ ## 🌱 Zero-Waste AI Engineering: FinOps + GreenOps (Scope 3 Compute Efficiency)
120
+
121
+ 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.
122
+
123
+ 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.
124
+
125
+ ---
126
+
127
+ ## Why Highbeam (`ctxtop`) Exists (vs. Cloud LLM Observability)
128
+
129
+ 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**.
130
+
131
+ `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:
132
+
133
+ | Failure Mode | Root Cause in Agentic Sessions | How `ctxtop` Detects & Remediates It Locally |
134
+ | :--- | :--- | :--- |
135
+ | **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. |
136
+ | **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. |
137
+ | **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`). |
138
+ | **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. |
139
+ | **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. |
140
+ | **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. |
141
+ | **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"`. |
142
+
143
+ ---
144
+
145
+ ## Multi-Harness v4.0 Wedge Capabilities
146
+
147
+ 1. **Cross-Harness SQLite & Protobuf Trajectory Stitcher (`src/core/trajectory_stitcher.mjs`)**:
148
+ - **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`.
149
+ - **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`.
150
+ - **Cursor**: Correlates `composerData:<id>`, `bubbleId:<id>:<bubble>`, `messageRequestContext`, and `agentKv:blob:*` (`requestId`) with `store.db` and timestamp-less `agent-transcripts/*.jsonl`.
151
+ 2. **Subagent Worktree & File Collision Detector (`src/core/subagents.mjs`)**:
152
+ - 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.
153
+ 3. **SQLite FTS5 Episodic Memory & Git Commit Token Ledger (`src/core/episodic_memory.mjs`, `src/core/git_ledger.mjs`)**:
154
+ - 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.
155
+ - Correlates `.git/logs/HEAD` commit timestamps against session windows to attribute input/output tokens, cache hit %, and USD cost per git commit.
156
+ 4. **Zero-PII Sanitizer & Forensic Snapshot Exporter (`src/core/sanitizer.mjs`)**:
157
+ - 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.
158
+
159
+ ---
160
+
161
+ ## Quick Start
162
+
163
+ ### 1. Inspect Live Sessions, Prune Tool Sludge, or Run Storage GC
164
+ ```bash
165
+ # Audit the last 5 local sessions for duplicate file reads, dead errors & MCP schema tax
166
+ node src/cli/postmortem.mjs --last 5
167
+
168
+ # Run environment & transcript health diagnostics (hooks, SQLite/JSONL confidence, 3-way mirror SHA-256)
169
+ node src/cli/doctor.mjs
170
+
171
+ # Run offline Prefix-Safe Tool-Output Surgeon on the active session transcript (with atomic backup)
172
+ node src/cli/doctor.mjs --prune-tools --dry-run
173
+
174
+ # Recover orphaned Antigravity brain/ directories or compact Cursor state.vscdb without VACUUM locks
175
+ node src/cli/doctor.mjs --recover-brain --gc-cursor --vscdb path/to/state.vscdb --dry-run
176
+
177
+ # Print the 40-cell ANSI status bar for the active session
178
+ node src/cli/horizon_hud.mjs --live
179
+ ```
180
+
181
+ ### 2. Launch the Local Telemetry WebView (`127.0.0.1`)
182
+ ```bash
183
+ # Start the loopback sidecar daemon and open the Tufte WebView
184
+ node sidecars/horizon-daemon/server.mjs
185
+ ```
186
+
187
+ ### 3. Install Lifecycle Hooks & CLI `statusLine`
188
+ ```bash
189
+ # Global install (~/.gemini/config/plugins/agy-horizon-flightcheck)
190
+ node src/cli/init.mjs init
191
+
192
+ # Workspace-local install (.agents/plugins/agy-horizon-flightcheck)
193
+ node src/cli/init.mjs init --workspace
194
+ ```
195
+
196
+ > [!TIP]
197
+ > 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).
198
+
199
+ ---
200
+
201
+ ## Systems Architecture & Zero-Trust Security
202
+
203
+ `ctxtop` is engineered for strict operational safety alongside live IDE/CLI database writers:
204
+
205
+ 1. **Zero Outbound Network Connections**:
206
+ - **0 runtime `npm` dependencies** (`package.json` has no `dependencies` block).
207
+ - **0 external HTTP/HTTPS requests, telemetry beacons, or remote API calls**. All parsing, classification, and routing run 100% in-memory on the local machine.
208
+ - 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.
209
+ 2. **Read-Only Database & Transcript Introspection (`SQLITE_OPEN_READONLY`)**:
210
+ - 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.
211
+ - 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.
212
+ 3. **Ring 1 Security, Concurrency & Context Hygiene Boundaries**:
213
+ - **`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.
214
+ - **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>`.
215
+ - **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.
216
+ - **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.
217
+ 4. **Locked v4.0 Edward Tufte UI Laws**:
218
+ - **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.
219
+ - **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.
220
+ - **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.
221
+ - **Law 4 (Silent-When-Nominal Watchdog)**: Host RAM and orphan process counters remain completely hidden unless an anomaly (`orphanCount > 0` or `ZOMBIE_LEAK`) occurs.
222
+
223
+ ---
224
+
225
+ ## 🔧 Configuration, Flight Modes & MCP Server (`@ctxtop/mcp`)
226
+
227
+ ### 1. Customizing `.attention-horizon.json` (Flight Modes & Detector Overrides)
228
+ 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:
229
+
230
+ ```bash
231
+ # Set a detector to warn-only, block, or off via CLI
232
+ npx ctxtop config DET-08 warn
233
+ npx ctxtop config DET-19 block
234
+ ```
235
+
236
+ ```json
237
+ {
238
+ "flightMode": "COACH",
239
+ "turnZeroTokenBudget": 20000,
240
+ "detectors": {
241
+ "DET-06": "block",
242
+ "DET-07": "block",
243
+ "DET-08": "warn",
244
+ "DET-09": "block",
245
+ "DET-19": "block",
246
+ "DET-20": "warn"
247
+ }
248
+ }
249
+ ```
250
+ - **`"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.
251
+ - **`"AUTO_PILOT"`**: Enforces strict pre-turn & stop-gate verification locks (e.g., requiring tests to run after source edits before session completion).
252
+ - **`"SILENT"` / `"OFF"`**: Passive telemetry collection only.
253
+
254
+ ### 2. Using Highbeam as an MCP Server (`ctxtop-mcp`)
255
+ 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:
256
+
257
+ ```json
258
+ {
259
+ "mcpServers": {
260
+ "highbeam": {
261
+ "command": "npx",
262
+ "args": ["-y", "ctxtop-mcp"]
263
+ }
264
+ }
265
+ }
266
+ ```
267
+ Exposes 4 read-only MCP tools (`<5ms` response): `get_context_telemetry`, `check_cache_gravity`, `get_savings_receipt`, and `inspect_detectors`.
268
+
269
+ ---
270
+
271
+ ## Deterministic `PreInvocation` Router & 6 Local Sensors
272
+
273
+ 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):
274
+
275
+ 1. `ALLOW_SILENT`: Immediate pass-through (`{}`) on `!` bypass prefix or healthy turns.
276
+ 2. `ALLOW_ACTIVE_SET`: Silent pass-through when referenced files are already warm in the last 5 turns.
277
+ 3. `ALLOW_PLAN_OR_SUBAGENT`: Silent pass-through during `/plan` mode or subagent delegation.
278
+ 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`).
279
+ 5. `STEER_SUBAGENT`: Advises `invoke_subagent` when a broad exploratory prompt would pollute a warm `>30k`-token parent context window.
280
+ 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.
281
+ 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.
282
+ 8. `HALT_REWRITE_SCORECARD`: Triggered via `#check` or vague cold-start prompts (`Turn <= 2`), outputting a 4-line prompt rewrite scorecard.
283
+
284
+ ---
285
+
286
+ ## CLI Commands & Forensic Postmortem
287
+
288
+ | Command | Description |
289
+ | :--- | :--- |
290
+ | `npx ctxtop init [--workspace]` | Installs Google Antigravity plugin manifests, lifecycle hooks, and sidecar configuration. |
291
+ | `npx ctxtop install --claude` | Installs Claude Code `.claude-plugin` manifest, Tier-1/Tier-2 hooks, and terminal `statusLine`. |
292
+ | `npx ctxtop doctor [--diagnostic]` | Validates hook registration, config overlays, dynamic model ceilings, 3-way WebView SHA-256 parity, and SQLite/JSONL health. |
293
+ | `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. |
294
+ | `npx ctxtop receipt [--markdown \| --pdf]` | Exports a SHA-256 verified FinOps + GreenOps token/USD savings receipt for the active workspace. |
295
+ | `npx ctxtop verify [--json]` | Verifies cryptographic SHA-256 integrity of all 149 release files against `CHECKSUMS.sha256`. |
296
+ | `npx ctxtop --roast` | Prints a terminal forensic summary of recent sessions with top duplicate-read file offenders and copy-pasteable remediations. |
297
+ | `npx ctxtop --serve` | Launches the local HTTP/SSE telemetry daemon (`127.0.0.1`) and interactive WebView (`/` Simple, `/advanced` Advanced). |
298
+ | `npx ctxtop --demo-animate` | Plays the 5-stage terminal crisis simulation across synthetic fixtures. |
299
+
300
+ ---
301
+
302
+ ## Verification & Benchmarks
303
+
304
+ Run the full zero-dependency test and verification suite (**1,050+ tests across 215+ suites**):
305
+
306
+ ```bash
307
+ # Full Coach, UI, & 360° Capability-Proof suite (911+ tests across 183+ suites)
308
+ npm run test:coach
309
+
310
+ # Claude Code dual-tier Mod, CLI hooks, statusLine, and 5-category ledger suite (168 tests)
311
+ npm run test:claude
312
+
313
+ # Unit & Multi-Harness Wedge suite (89 tests across 31 suites)
314
+ npm run test:unit
315
+
316
+ # Architectural verification suite (Gates 0-6 & Phases 1-7: SQLite read-only locks, JSDOM UI, MCP audit)
317
+ npm run test:gates && npm run test:phases
318
+
319
+ # End-to-end context memory & live loopback daemon integration suite (7 layers)
320
+ npm run test:e2e
321
+
322
+ # Latency benchmark (200 iterations/path: Tier-1 ~3.0ms avg / <15ms SLA, Tier-2 CLI Hook, <45ms HUD)
323
+ npm run bench
324
+ ```
325
+
326
+ ---
327
+
328
+ ## License
329
+
330
+ MIT © [Gizzant](https://github.com/Gizzant)
package/SECURITY.md ADDED
@@ -0,0 +1,22 @@
1
+ # Security & Zero-Trust Open-Source Manifest (`attention-horizon-antigravity`)
2
+
3
+ ## 1. Zero-Trust Network Profile (100% Local In-Memory Telemetry)
4
+
5
+ **Highbeam** (`attention-horizon-antigravity` / `agy-horizon-flightcheck`) inspects sensitive local engineering artifacts (conversation transcripts, file paths, and tool usage). To guarantee enterprise and individual security for the Antigravity and Hacker News developer community:
6
+
7
+ 1. **100% In-Memory Local Telemetry Parsing:** All session token accounting, U-shaped attention curve modeling, and waste classification are computed 100% in-memory from local SQLite (`conversations/*.db`, `conversation_summaries.db`) and JSONL (`transcript_full.jsonl`) reads.
8
+ 2. **Zero Outbound Network Connections:** Neither the CLI HUD (`src/cli/horizon_hud.mjs`), the lifecycle hooks (`src/hooks/*.mjs`), nor the sidecar daemon (`sidecars/horizon-daemon/server.mjs`) opens any external HTTP, HTTPS, WebSocket, or DNS connections. There are **zero telemetry pings**, **zero analytics endpoints**, and **zero external LLM API keys required**.
9
+ 3. **Loopback-Only Binding (`127.0.0.1`):** The Edward Tufte WebView server binds exclusively to `127.0.0.1` (`BIND_HOST = '127.0.0.1'`) and rejects oversized POST payloads (`>4096` bytes). Optional local quota probes communicate strictly over `127.0.0.1` loopback with the local Antigravity `language_server` process.
10
+ 4. **Zero Third-Party npm Dependencies:** The runtime uses only built-in Node.js standard library modules (`node:fs`, `node:path`, `node:os`, `node:http`, `node:crypto`, `node:child_process`, `node:sqlite`, `node:url`), eliminating transitive npm supply-chain risk.
11
+
12
+ ## 2. Read-Only Filesystem Locks (`SQLITE_OPEN_READONLY`)
13
+
14
+ To eliminate any risk of database lock contention or corruption while Google Antigravity is actively streaming turns:
15
+
16
+ 1. **Strict `SQLITE_OPEN_READONLY` Database Access:** Every connection to Antigravity's active session databases (`~/.gemini/<surface>/conversations/*.db` and `conversation_summaries.db`) is opened with `SQLITE_OPEN_READONLY_OPTIONS` (`{ readOnly: true }`, mapping to `SQLITE_OPEN_READONLY`) and closed immediately in a `finally` block.
17
+ 2. **Read-Only JSONL File Descriptors (`'r'`):** Incremental transcript slicing (`transcript_full.jsonl` and `transcript.jsonl`) opens log files strictly with read-only flag `'r'` (`fs.openSync(filePath, 'r')`) and never acquires write locks on active Antigravity session databases.
18
+ 3. **Atomic Sidecar & Backup I/O:** Any optional user-triggered state (such as `docs/HANDOFF_<timestamp>.md` generation or `.bak` transcript backups prior to surgical pruning) is written atomically via PID-scoped temporary files and rename operations.
19
+
20
+ ## 3. Reporting a Vulnerability
21
+
22
+ If you discover a security or path-handling issue, please open a GitHub Security Advisory on the repository or contact `frankmiller@gmail.com`. We respond to security reports within 48 hours.