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 @@
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
+ };
@@ -0,0 +1,321 @@
1
+ /**
2
+ * @file src/core-isomorphic/coach/resumeToolsetAuditor.mjs
3
+ * Session-resume MCP / tool-set change auditor (`Item 6`).
4
+ *
5
+ * Evidence (`t6_layers.csv` arm `CC-T`):
6
+ * Resuming a warm session with a changed `--mcp-config` / tool definition list invalidated
7
+ * the entire KV prefix (`0` cache read tokens on turn 6).
8
+ *
9
+ * Hook visibility on Claude Code `2.1.325` (`$0` verified):
10
+ * `SessionStart:resume` stdin includes `session_id`, `transcript_path`, `cwd`, `source`,
11
+ * `seconds_since_last_response`, `context_tokens`, `prompt_cache_likely_expired`, and
12
+ * `estimated_cache_write_usd` — it does NOT pass `tools` or `mcp_servers` directly, and
13
+ * `deferred_tools_delta` is appended to `.jsonl` after `SessionStart` during `system/init`.
14
+ * Therefore this auditor hashes MCP & tool configuration from `.mcp.json`, `.claude/settings*.json`,
15
+ * `~/.claude.json`, explicit CLI `--mcp-config`/`--tools` flags if supplied, and optional host
16
+ * `event.tools`/`event.mcp_servers` arrays (using pure runtime I/O adapters per Mod Law 4).
17
+ */
18
+
19
+ import {
20
+ basenamePath,
21
+ fileExists,
22
+ getCwd,
23
+ getHomeDir,
24
+ joinPath,
25
+ readJsonSafe,
26
+ readTextSafe,
27
+ resolvePath,
28
+ sha256Hex
29
+ } from '../utils/runtime.mjs';
30
+ import {
31
+ isKnownCatalogModel,
32
+ normalizeModelId,
33
+ resolveEffectiveRates
34
+ } from '../config/catalogLoader.mjs';
35
+
36
+ function normalizeServerEntry(entry) {
37
+ if (!entry || typeof entry !== 'object') return null;
38
+ const envKeys =
39
+ entry.env && typeof entry.env === 'object' ? Object.keys(entry.env).sort() : [];
40
+ return {
41
+ type: String(entry.type || (entry.url ? 'http' : 'stdio')),
42
+ command: entry.command ? String(entry.command) : null,
43
+ args: Array.isArray(entry.args) ? entry.args.map(String) : [],
44
+ url: entry.url ? String(entry.url) : null,
45
+ envKeys,
46
+ disabled: Boolean(entry.disabled)
47
+ };
48
+ }
49
+
50
+ function mergeMcpServers(target, sourceObj) {
51
+ if (!sourceObj || typeof sourceObj !== 'object' || Array.isArray(sourceObj)) return;
52
+ for (const [name, cfg] of Object.entries(sourceObj)) {
53
+ const cleanName = String(name || '').trim();
54
+ if (!cleanName) continue;
55
+ const normalized = normalizeServerEntry(cfg);
56
+ if (normalized) {
57
+ target[cleanName] = normalized;
58
+ }
59
+ }
60
+ }
61
+
62
+ function parseCliMcpFlags(cliArgs = []) {
63
+ const args = Array.isArray(cliArgs) ? cliArgs.map(String) : [];
64
+ const mcpConfigs = [];
65
+ const toolFlags = [];
66
+ for (let i = 0; i < args.length; i += 1) {
67
+ const tok = args[i];
68
+ if (tok === '--mcp-config' && i + 1 < args.length) {
69
+ mcpConfigs.push(args[i + 1]);
70
+ i += 1;
71
+ } else if (tok.startsWith('--mcp-config=')) {
72
+ mcpConfigs.push(tok.slice('--mcp-config='.length));
73
+ } else if (
74
+ (tok === '--tools' || tok === '--allowedTools' || tok === '--disallowedTools') &&
75
+ i + 1 < args.length
76
+ ) {
77
+ toolFlags.push(`${tok}:${args[i + 1]}`);
78
+ i += 1;
79
+ } else if (
80
+ tok.startsWith('--tools=') ||
81
+ tok.startsWith('--allowedTools=') ||
82
+ tok.startsWith('--disallowedTools=')
83
+ ) {
84
+ toolFlags.push(tok);
85
+ }
86
+ }
87
+ return { mcpConfigs, toolFlags: toolFlags.sort() };
88
+ }
89
+
90
+ function tryReadParentProcCmdline(options = {}) {
91
+ try {
92
+ const proc = globalThis.process;
93
+ if (proc?.platform === 'linux' && proc?.ppid) {
94
+ const cmdlinePath = `/proc/${proc.ppid}/cmdline`;
95
+ if (fileExists(cmdlinePath, options)) {
96
+ const raw = readTextSafe(cmdlinePath, '', options);
97
+ if (typeof raw === 'string' && raw.length > 0) {
98
+ return raw.split('\0').filter(Boolean);
99
+ }
100
+ }
101
+ }
102
+ } catch {
103
+ // Fail-open; zero subprocess spawning in hot hook path
104
+ }
105
+ return null;
106
+ }
107
+
108
+ /**
109
+ * Computes a deterministic SHA-256 hash of observable active MCP server & tool configuration.
110
+ * Strictly read-only, excludes secret env values, and never throws on malformed files.
111
+ *
112
+ * @param {object} [event={}]
113
+ * @param {object} [options={}]
114
+ * @returns {{ hash: string, serverNames: string[], toolCount: number, toolNames: string[], cliFlags: string[], sourcesInspected: string[], recordedAt: string }}
115
+ */
116
+ export function computeActiveToolsetHash(event = {}, options = {}) {
117
+ const cwd = event.cwd || getCwd(options);
118
+ const homeDir = options.homeDir || event.homeDir || getHomeDir(options);
119
+ const ioOpts = { ...options, cwd, homeDir };
120
+ const mcpServers = {};
121
+ const toolSet = new Set();
122
+ const sourcesInspected = [];
123
+
124
+ // 1. Optional host-provided arrays (in case host or future CLI includes them)
125
+ if (Array.isArray(event.tools)) {
126
+ sourcesInspected.push('event.tools');
127
+ for (const t of event.tools) {
128
+ const name = typeof t === 'string' ? t : t?.name || t?.id;
129
+ if (name) toolSet.add(String(name));
130
+ }
131
+ }
132
+ if (event.mcp_servers && typeof event.mcp_servers === 'object') {
133
+ sourcesInspected.push('event.mcp_servers');
134
+ if (Array.isArray(event.mcp_servers)) {
135
+ for (const s of event.mcp_servers) {
136
+ const sName = typeof s === 'string' ? s : s?.name;
137
+ if (sName) {
138
+ mcpServers[String(sName)] = normalizeServerEntry(
139
+ typeof s === 'object' ? s : { type: 'configured' }
140
+ );
141
+ }
142
+ }
143
+ } else {
144
+ mergeMcpServers(mcpServers, event.mcp_servers);
145
+ }
146
+ }
147
+ if (event.mcpServers && typeof event.mcpServers === 'object') {
148
+ sourcesInspected.push('event.mcpServers');
149
+ mergeMcpServers(mcpServers, event.mcpServers);
150
+ }
151
+
152
+ // 2. ~/.claude.json user + workspace project MCP config
153
+ if (options.includeUserClaudeJson !== false && homeDir) {
154
+ const userClaudePath = joinPath(homeDir, '.claude.json');
155
+ const userClaude = readJsonSafe(userClaudePath, null, ioOpts);
156
+ if (userClaude && typeof userClaude === 'object') {
157
+ sourcesInspected.push('home:.claude.json');
158
+ mergeMcpServers(mcpServers, userClaude.mcpServers);
159
+ if (cwd && userClaude.projects && typeof userClaude.projects === 'object') {
160
+ const normCwd = resolvePath(cwd).toLowerCase();
161
+ for (const [projPath, projCfg] of Object.entries(userClaude.projects)) {
162
+ if (
163
+ resolvePath(projPath).toLowerCase() === normCwd &&
164
+ projCfg &&
165
+ typeof projCfg === 'object'
166
+ ) {
167
+ mergeMcpServers(mcpServers, projCfg.mcpServers);
168
+ }
169
+ }
170
+ }
171
+ }
172
+ }
173
+
174
+ // 3. Project .mcp.json and .claude/settings*.json
175
+ const projectFiles = [
176
+ { rel: '.mcp.json', label: 'project:.mcp.json' },
177
+ { rel: '.claude/settings.json', label: 'project:.claude/settings.json' },
178
+ { rel: '.claude/settings.local.json', label: 'project:.claude/settings.local.json' }
179
+ ];
180
+ for (const pf of projectFiles) {
181
+ const fullPath = cwd ? joinPath(cwd, pf.rel) : null;
182
+ const parsed = fullPath ? readJsonSafe(fullPath, null, ioOpts) : null;
183
+ if (parsed && typeof parsed === 'object') {
184
+ sourcesInspected.push(pf.label);
185
+ mergeMcpServers(mcpServers, parsed.mcpServers);
186
+ if (Array.isArray(parsed.tools)) {
187
+ for (const t of parsed.tools) {
188
+ if (typeof t === 'string' && t.trim()) toolSet.add(t.trim());
189
+ }
190
+ }
191
+ if (Array.isArray(parsed.enabledMcpjsonServers)) {
192
+ for (const s of parsed.enabledMcpjsonServers) {
193
+ toolSet.add(`mcp_enabled:${String(s)}`);
194
+ }
195
+ }
196
+ if (Array.isArray(parsed.disabledMcpjsonServers)) {
197
+ for (const s of parsed.disabledMcpjsonServers) {
198
+ toolSet.add(`mcp_disabled:${String(s)}`);
199
+ }
200
+ }
201
+ }
202
+ }
203
+
204
+ // 4. Explicit CLI args or readable parent cmdline (--mcp-config / --tools / --allowedTools)
205
+ const rawCliArgs =
206
+ options.cliArgs ?? event.cliArgs ?? event.cli_args ?? tryReadParentProcCmdline(ioOpts) ?? [];
207
+ const { mcpConfigs, toolFlags } = parseCliMcpFlags(rawCliArgs);
208
+ for (const cfgArg of mcpConfigs) {
209
+ const resolved = cwd ? resolvePath(cwd, cfgArg) : resolvePath(cfgArg);
210
+ const parsedCfg = readJsonSafe(resolved, null, ioOpts);
211
+ if (parsedCfg && typeof parsedCfg === 'object') {
212
+ sourcesInspected.push(`cli:--mcp-config(${basenamePath(resolved)})`);
213
+ mergeMcpServers(mcpServers, parsedCfg.mcpServers || parsedCfg);
214
+ } else {
215
+ toolFlags.push(`mcp-config:${basenamePath(cfgArg)}`);
216
+ }
217
+ }
218
+
219
+ const orderedServers = {};
220
+ for (const name of Object.keys(mcpServers).sort()) {
221
+ orderedServers[name] = mcpServers[name];
222
+ }
223
+ const toolNames = Array.from(toolSet).sort();
224
+ const payload = {
225
+ mcpServers: orderedServers,
226
+ tools: toolNames,
227
+ cliFlags: toolFlags
228
+ };
229
+
230
+ const hash = sha256Hex(JSON.stringify(payload), options);
231
+
232
+ return {
233
+ hash,
234
+ serverNames: Object.keys(orderedServers),
235
+ toolNames,
236
+ toolCount: toolNames.length,
237
+ cliFlags: toolFlags,
238
+ sourcesInspected,
239
+ recordedAt: new Date().toISOString()
240
+ };
241
+ }
242
+
243
+ /**
244
+ * Evaluates whether a changed tool-set / MCP config on `SessionStart:resume` warrants a one-line
245
+ * cache-rewrite advisory (`Item 6`, citing `t6_layers.csv` arm `CC-T`).
246
+ *
247
+ * @param {object} [params={}]
248
+ * @param {object} [options={}]
249
+ * @returns {object}
250
+ */
251
+ export function evaluateResumeToolsetChange(params = {}, options = {}) {
252
+ const prev = params.previousHashRecord || null;
253
+ const curr = params.currentHashRecord || null;
254
+ const contextTokens = Math.max(0, Number(params.contextTokens ?? 0));
255
+ const minTokens = Math.max(0, Number(params.minContextTokens ?? 10_000));
256
+ const cacheExpired = Boolean(params.cacheExpired);
257
+ const ttlTier = params.cacheTtlTier === '1h' ? '1h' : '5m';
258
+ const rawModel = params.modelId || 'claude-sonnet-5-5';
259
+
260
+ if (!prev?.hash || !curr?.hash) {
261
+ return { changed: false, shouldWarn: false, reason: 'no_baseline', advisory: null };
262
+ }
263
+ if (prev.hash === curr.hash) {
264
+ return { changed: false, shouldWarn: false, reason: 'unchanged', advisory: null };
265
+ }
266
+ if (cacheExpired) {
267
+ return { changed: true, shouldWarn: false, reason: 'cache_already_expired', advisory: null };
268
+ }
269
+ if (contextTokens < minTokens) {
270
+ return { changed: true, shouldWarn: false, reason: 'small_or_cold_context', advisory: null };
271
+ }
272
+
273
+ const prevSet = new Set(Array.isArray(prev.serverNames) ? prev.serverNames : []);
274
+ const currSet = new Set(Array.isArray(curr.serverNames) ? curr.serverNames : []);
275
+ const added = [...currSet].filter((s) => !prevSet.has(s));
276
+ const removed = [...prevSet].filter((s) => !currSet.has(s));
277
+ const diffParts = [];
278
+ if (added.length > 0) diffParts.push(`+${added.join(',+')}`);
279
+ if (removed.length > 0) diffParts.push(`-${removed.join(',-')}`);
280
+ const diffSummary = diffParts.length > 0 ? diffParts.join(' ') : 'MCP/tool definitions updated';
281
+
282
+ const knownModel = isKnownCatalogModel(rawModel, options);
283
+ if (!knownModel) {
284
+ const advisory =
285
+ `[Highbeam Resume Toolset Advisory] Active MCP/tool set changed (${diffSummary}); ` +
286
+ `prices are unknown for ${String(rawModel)}, and the first turn will rewrite ~${Math.round(contextTokens).toLocaleString()} cached tokens (t6_layers CC-T).`;
287
+ return {
288
+ changed: true,
289
+ shouldWarn: true,
290
+ unknownModel: true,
291
+ estimatedWriteCostUSD: null,
292
+ diffSummary,
293
+ advisory
294
+ };
295
+ }
296
+
297
+ const modelId = normalizeModelId(rawModel, options);
298
+ const rates = resolveEffectiveRates(modelId, contextTokens, options);
299
+ const writeRate = ttlTier === '1h' ? rates.write1hPer1M : rates.write5mPer1M;
300
+ const estimatedWriteCostUSD = Number(((contextTokens / 1_000_000) * writeRate).toFixed(4));
301
+
302
+ const advisory =
303
+ `[Highbeam Resume Toolset Advisory] Active MCP/tool set changed (${diffSummary}); ` +
304
+ `the first turn will rewrite ~${Math.round(contextTokens).toLocaleString()} cached tokens ` +
305
+ `(~$${estimatedWriteCostUSD.toFixed(4)} at ${modelId} ${ttlTier} write rate, t6_layers CC-T).`;
306
+
307
+ return {
308
+ changed: true,
309
+ shouldWarn: true,
310
+ unknownModel: false,
311
+ modelId,
312
+ estimatedWriteCostUSD,
313
+ diffSummary,
314
+ advisory
315
+ };
316
+ }
317
+
318
+ export default {
319
+ computeActiveToolsetHash,
320
+ evaluateResumeToolsetChange
321
+ };