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 @@
1
+ export * from '../diagnostics/micro_skills.mjs';
@@ -0,0 +1 @@
1
+ export * from '../diagnostics/prompt_hygiene_governor.mjs';
@@ -0,0 +1,254 @@
1
+ /**
2
+ * @file src/coach/repoCalibration.mjs
3
+ * Empirical Repo-Calibrated Context Physics (`IDEA-03` — Technical Moat `A4`).
4
+ *
5
+ * Learns repository-specific context sinks across coding sessions:
6
+ * 1. Chronic file re-read hotspots (`fileReads` frequency & cumulative token drain across sessions)
7
+ * 2. Empirical post-compaction token survival ratio (`compactions.averageSurvivalRatio`)
8
+ * 3. Empirical KV-cache hit baseline (`cachePerformance.empiricalHitRatio`)
9
+ *
10
+ * Persisted locally in `.claude/horizon-state/repo_calibration.json` (100% zero-socket).
11
+ */
12
+
13
+ import { path, getCwd, readJsonSafe, writeJsonAtomic } from '../utils/runtime.mjs';
14
+
15
+ const DEFAULT_CALIBRATION_STATE = Object.freeze({
16
+ schemaVersion: '1.0.0',
17
+ updatedAt: null,
18
+ fileReads: {},
19
+ compactions: {
20
+ count: 0,
21
+ totalPreTokens: 0,
22
+ totalPostTokens: 0,
23
+ averageSurvivalRatio: 0.22
24
+ },
25
+ cachePerformance: {
26
+ totalTurns: 0,
27
+ warmHitTurns: 0,
28
+ empiricalHitRatio: 0
29
+ }
30
+ });
31
+
32
+ /**
33
+ * Resolves the path to `.claude/horizon-state/repo_calibration.json`.
34
+ * @param {object} [options={}]
35
+ * @returns {string}
36
+ */
37
+ export function getRepoCalibrationPath(options = {}) {
38
+ if (options.calibrationPath) return options.calibrationPath;
39
+ const cwd = getCwd(options);
40
+ const stateDir = options.stateDir || path.join(cwd, '.claude', 'horizon-state');
41
+ return path.join(stateDir, 'repo_calibration.json');
42
+ }
43
+
44
+ /**
45
+ * Normalizes a repository file path to a portable forward-slash key.
46
+ * @param {string} filePath
47
+ * @param {string} [cwd='.']
48
+ * @returns {string}
49
+ */
50
+ export function normalizeRepoFileKey(filePath, cwd = '.') {
51
+ const raw = String(filePath || '').trim();
52
+ if (!raw) return '';
53
+ try {
54
+ const rel = path.isAbsolute(raw) ? path.relative(cwd, raw) : raw;
55
+ const clean = rel.replace(/\\/g, '/').replace(/^\.\//, '');
56
+ return clean.startsWith('..') ? raw.replace(/\\/g, '/') : clean;
57
+ } catch (_err) {
58
+ return raw.replace(/\\/g, '/');
59
+ }
60
+ }
61
+
62
+ /**
63
+ * Loads the empirical calibration store for the current repository.
64
+ * @param {object} [options={}]
65
+ * @returns {object}
66
+ */
67
+ export function loadRepoCalibration(options = {}) {
68
+ const targetPath = getRepoCalibrationPath(options);
69
+ const raw = readJsonSafe(targetPath, null, options);
70
+ if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
71
+ return JSON.parse(JSON.stringify(DEFAULT_CALIBRATION_STATE));
72
+ }
73
+ return {
74
+ schemaVersion: '1.0.0',
75
+ updatedAt: raw.updatedAt || null,
76
+ fileReads: raw.fileReads && typeof raw.fileReads === 'object' ? { ...raw.fileReads } : {},
77
+ compactions: {
78
+ ...DEFAULT_CALIBRATION_STATE.compactions,
79
+ ...(raw.compactions || {})
80
+ },
81
+ cachePerformance: {
82
+ ...DEFAULT_CALIBRATION_STATE.cachePerformance,
83
+ ...(raw.cachePerformance || {})
84
+ }
85
+ };
86
+ }
87
+
88
+ /**
89
+ * Records a file read event in the repository calibration store and detects
90
+ * whether the file has become a chronic multi-read context sink.
91
+ *
92
+ * @param {{ filePath: string, estimatedTokens?: number, sessionId?: string }} event
93
+ * @param {object} [options={}]
94
+ * @returns {{
95
+ * fileKey: string,
96
+ * readCount: number,
97
+ * sessionCount: number,
98
+ * totalEstimatedTokens: number,
99
+ * isChronicSink: boolean,
100
+ * recommendation: string | null
101
+ * }}
102
+ */
103
+ export function recordRepoFileRead(event = {}, options = {}) {
104
+ const cwd = getCwd(options);
105
+ const fileKey = normalizeRepoFileKey(event.filePath, cwd);
106
+ if (!fileKey) {
107
+ return {
108
+ fileKey: '',
109
+ readCount: 0,
110
+ sessionCount: 0,
111
+ totalEstimatedTokens: 0,
112
+ isChronicSink: false,
113
+ recommendation: null
114
+ };
115
+ }
116
+
117
+ const tokens = Math.max(0, Math.round(Number(event.estimatedTokens ?? 0)));
118
+ const sessionId = String(event.sessionId || options.sessionId || 'default');
119
+ const state = loadRepoCalibration(options);
120
+
121
+ const existing = state.fileReads[fileKey] || {
122
+ readCount: 0,
123
+ totalEstimatedTokens: 0,
124
+ sessionsSeen: [],
125
+ lastReadAt: null
126
+ };
127
+
128
+ existing.readCount = Number(existing.readCount || 0) + 1;
129
+ existing.totalEstimatedTokens = Number(existing.totalEstimatedTokens || 0) + tokens;
130
+ const sessions = Array.isArray(existing.sessionsSeen) ? [...existing.sessionsSeen] : [];
131
+ if (!sessions.includes(sessionId)) {
132
+ sessions.push(sessionId);
133
+ }
134
+ existing.sessionsSeen = sessions.slice(-25);
135
+ existing.lastReadAt = new Date().toISOString();
136
+
137
+ state.fileReads[fileKey] = existing;
138
+ state.updatedAt = existing.lastReadAt;
139
+ writeJsonAtomic(getRepoCalibrationPath(options), state, options);
140
+
141
+ // Exclude small onboarding docs (e.g., README.md read <= 2x per chat) from false-positive sink status
142
+ const isOnboardingDoc = /^(?:README\.md|CLAUDE\.md|AGENTS\.md|LICENSE)$/i.test(
143
+ path.basename(fileKey)
144
+ );
145
+ const avgReadsPerSession = existing.readCount / Math.max(1, existing.sessionsSeen.length);
146
+
147
+ const isChronicSink = isOnboardingDoc
148
+ ? existing.readCount >= 6 && avgReadsPerSession >= 3
149
+ : existing.readCount >= 3 && existing.totalEstimatedTokens >= 6000;
150
+
151
+ const recommendation = isChronicSink
152
+ ? `Repo Calibration Alert: "${fileKey}" has been read ${existing.readCount}x (${existing.totalEstimatedTokens.toLocaleString()} cumulative tok across ${existing.sessionsSeen.length} session(s)). Use ranged line reads (offset/limit) or delegate to an Explore subagent.`
153
+ : null;
154
+
155
+ return {
156
+ fileKey,
157
+ readCount: existing.readCount,
158
+ sessionCount: existing.sessionsSeen.length,
159
+ totalEstimatedTokens: existing.totalEstimatedTokens,
160
+ isChronicSink,
161
+ recommendation
162
+ };
163
+ }
164
+
165
+ /**
166
+ * Records an observed compaction outcome (`preTokens` -> `postTokens`) to calibrate
167
+ * the repository's empirical post-compaction survival ratio.
168
+ *
169
+ * @param {{ preTokens: number, postTokens: number }} event
170
+ * @param {object} [options={}]
171
+ * @returns {object}
172
+ */
173
+ export function recordRepoCompactionOutcome(event = {}, options = {}) {
174
+ const pre = Math.max(0, Number(event.preTokens || 0));
175
+ const post = Math.max(0, Number(event.postTokens || 0));
176
+ const state = loadRepoCalibration(options);
177
+
178
+ if (pre > 0 && post > 0 && post <= pre) {
179
+ state.compactions.count += 1;
180
+ state.compactions.totalPreTokens += pre;
181
+ state.compactions.totalPostTokens += post;
182
+ state.compactions.averageSurvivalRatio = Number(
183
+ (state.compactions.totalPostTokens / state.compactions.totalPreTokens).toFixed(4)
184
+ );
185
+ state.updatedAt = new Date().toISOString();
186
+ writeJsonAtomic(getRepoCalibrationPath(options), state, options);
187
+ }
188
+
189
+ return state.compactions;
190
+ }
191
+
192
+ /**
193
+ * Records a turn's KV-cache read ratio to maintain an empirical cache-hit baseline for the repo.
194
+ *
195
+ * @param {{ cacheReadTokens: number, totalPromptTokens: number }} event
196
+ * @param {object} [options={}]
197
+ * @returns {object}
198
+ */
199
+ export function recordRepoCacheTurn(event = {}, options = {}) {
200
+ const readTok = Math.max(0, Number(event.cacheReadTokens || 0));
201
+ const totalTok = Math.max(0, Number(event.totalPromptTokens || 0));
202
+ const state = loadRepoCalibration(options);
203
+
204
+ if (totalTok > 0) {
205
+ state.cachePerformance.totalTurns += 1;
206
+ if (readTok / totalTok >= 0.5) {
207
+ state.cachePerformance.warmHitTurns += 1;
208
+ }
209
+ state.cachePerformance.empiricalHitRatio = Number(
210
+ (state.cachePerformance.warmHitTurns / state.cachePerformance.totalTurns).toFixed(4)
211
+ );
212
+ state.updatedAt = new Date().toISOString();
213
+ writeJsonAtomic(getRepoCalibrationPath(options), state, options);
214
+ }
215
+
216
+ return state.cachePerformance;
217
+ }
218
+
219
+ /**
220
+ * Returns the top chronic re-read context-sink files in this repository.
221
+ *
222
+ * @param {object} [options={}]
223
+ * @returns {Array<{
224
+ * fileKey: string,
225
+ * readCount: number,
226
+ * sessionCount: number,
227
+ * totalEstimatedTokens: number
228
+ * }>}
229
+ */
230
+ export function getTopChronicReadFiles(options = {}) {
231
+ const limit = Number(options.limit || 5);
232
+ const state = loadRepoCalibration(options);
233
+ const entries = Object.entries(state.fileReads || {}).map(([fileKey, info]) => ({
234
+ fileKey,
235
+ readCount: Number(info.readCount || 0),
236
+ sessionCount: Array.isArray(info.sessionsSeen) ? info.sessionsSeen.length : 1,
237
+ totalEstimatedTokens: Number(info.totalEstimatedTokens || 0)
238
+ }));
239
+
240
+ return entries
241
+ .filter((e) => e.readCount >= 2)
242
+ .sort((a, b) => b.totalEstimatedTokens - a.totalEstimatedTokens || b.readCount - a.readCount)
243
+ .slice(0, limit);
244
+ }
245
+
246
+ export default {
247
+ getRepoCalibrationPath,
248
+ normalizeRepoFileKey,
249
+ loadRepoCalibration,
250
+ recordRepoFileRead,
251
+ recordRepoCompactionOutcome,
252
+ recordRepoCacheTurn,
253
+ getTopChronicReadFiles
254
+ };