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,49 @@
1
+ /**
2
+ * @file src/core-isomorphic/control/index.mjs
3
+ * Execution Control Plane Unified Barrel (Milestone 4 — Features 24–28).
4
+ * Pure ESM with strictly 0 node:* imports adhering to Claude Mod Laws 1–5.
5
+ */
6
+
7
+ export {
8
+ createSpan,
9
+ endSpan,
10
+ closeUnclosedSpans,
11
+ buildCallTree,
12
+ computeCriticalPath,
13
+ renderCallTree,
14
+ buildFlamegraphData
15
+ } from './callTree.mjs';
16
+
17
+ export {
18
+ parseWorktreePorcelain,
19
+ extractAgentLocation,
20
+ applySubagentLifecycle,
21
+ computeSwarmSummary,
22
+ formatSwarmCompact,
23
+ toCostRadarTopology,
24
+ SWARM_LIFECYCLE_CONSTANTS,
25
+ acquireScopeLock,
26
+ evaluateScopeAndQuotaBrake,
27
+ matchesScopePattern
28
+ } from './swarmWorktree.mjs';
29
+
30
+ export {
31
+ CONTROL_STATES,
32
+ createInitialControlState,
33
+ transitionControlState,
34
+ parseControlFile,
35
+ serializeControlFile,
36
+ evaluateToolBoundaryLatch
37
+ } from './controlStateMachine.mjs';
38
+
39
+ export {
40
+ evaluateCoachLatch,
41
+ renderCoachPill
42
+ } from './coachLatches.mjs';
43
+
44
+ export {
45
+ SUSPENSION_CONSTANTS,
46
+ waitForSuspensionResume,
47
+ toProtoSafePreHookOutput,
48
+ wrapSafeToolBoundary
49
+ } from './toolSuspension.mjs';
@@ -0,0 +1,109 @@
1
+ /**
2
+ * @file src/core-isomorphic/control/swarmWorktree.mjs
3
+ * Swarm & Worktree Observability (Feature 25).
4
+ *
5
+ * Implements Git worktree porcelain parsing, subagent roster tracking,
6
+ * lifecycle state monitoring, and DET-20 scope collision detection.
7
+ * Pure ESM with strictly 0 node:* imports adhering to Claude Mod Laws 1–5.
8
+ */
9
+
10
+ import {
11
+ extractAgentLocation,
12
+ applySubagentLifecycle,
13
+ computeSwarmSummary,
14
+ formatSwarmCompact,
15
+ toCostRadarTopology,
16
+ SWARM_LIFECYCLE_CONSTANTS
17
+ } from '../telemetry/swarmTopology.mjs';
18
+
19
+ import {
20
+ acquireScopeLock,
21
+ evaluateScopeAndQuotaBrake,
22
+ matchesScopePattern
23
+ } from '../telemetry/scopeLockRegistry.mjs';
24
+
25
+ /**
26
+ * Parses `git worktree list --porcelain` stdout into structured objects.
27
+ * Pure string parsing with zero node:path dependency.
28
+ *
29
+ * @param {string} text
30
+ * @returns {Array<object>}
31
+ */
32
+ export function parseWorktreePorcelain(text = '') {
33
+ if (!text || typeof text !== 'string') return [];
34
+
35
+ const entries = [];
36
+ const blocks = text.trim().split(/\n\s*\n/);
37
+ let isFirst = true;
38
+
39
+ for (const block of blocks) {
40
+ if (!block.trim()) continue;
41
+ const lines = block.split(/\r?\n/);
42
+ let worktree = null;
43
+ let head = null;
44
+ let branch = null;
45
+ let bare = false;
46
+ let detached = false;
47
+ let locked = false;
48
+ let prunable = false;
49
+
50
+ for (const rawLine of lines) {
51
+ const line = rawLine.trim();
52
+ if (!line) continue;
53
+ if (line.startsWith('worktree ')) {
54
+ worktree = line.slice(9).trim();
55
+ } else if (line.startsWith('HEAD ')) {
56
+ head = line.slice(5).trim();
57
+ } else if (line.startsWith('branch ')) {
58
+ branch = line.slice(7).trim();
59
+ } else if (line === 'bare') {
60
+ bare = true;
61
+ } else if (line === 'detached') {
62
+ detached = true;
63
+ } else if (line.startsWith('locked')) {
64
+ const reason = line.slice(6).trim();
65
+ locked = reason || true;
66
+ } else if (line.startsWith('prunable')) {
67
+ const reason = line.slice(8).trim();
68
+ prunable = reason || true;
69
+ }
70
+ }
71
+
72
+ if (worktree) {
73
+ // Extract basename without node:path, handling spaces and Unicode
74
+ const normalizedPath = worktree.replace(/[\\/]+$/, '');
75
+ const parts = normalizedPath.split(/[\\/]/);
76
+ const name = parts[parts.length - 1] || 'worktree';
77
+ const shortBranch = branch ? branch.replace(/^refs\/heads\//, '') : null;
78
+
79
+ entries.push({
80
+ worktree,
81
+ name,
82
+ head,
83
+ branch: shortBranch,
84
+ fullBranch: branch,
85
+ bare,
86
+ detached,
87
+ locked,
88
+ prunable,
89
+ isMain: isFirst
90
+ });
91
+ isFirst = false;
92
+ }
93
+ }
94
+
95
+ return entries;
96
+ }
97
+
98
+ // Re-export telemetry and scope registry APIs for unified control surface
99
+ export {
100
+ extractAgentLocation,
101
+ applySubagentLifecycle,
102
+ computeSwarmSummary,
103
+ formatSwarmCompact,
104
+ toCostRadarTopology,
105
+ SWARM_LIFECYCLE_CONSTANTS,
106
+ acquireScopeLock,
107
+ evaluateScopeAndQuotaBrake,
108
+ matchesScopePattern
109
+ };
@@ -0,0 +1,197 @@
1
+ /**
2
+ * @file src/core-isomorphic/control/toolSuspension.mjs
3
+ * Atomic Tool-Boundary Suspension (Feature 28).
4
+ *
5
+ * Implements non-spinning tool-boundary suspension, 600,000ms safety timeout release,
6
+ * and fail-closed Mod Law 5 wrapper output normalization.
7
+ * Pure ESM with strictly 0 node:* imports adhering to Claude Mod Laws 1–5.
8
+ */
9
+
10
+ import { CONTROL_STATES, evaluateToolBoundaryLatch } from './controlStateMachine.mjs';
11
+
12
+ export const SUSPENSION_CONSTANTS = Object.freeze({
13
+ DEFAULT_SAFETY_TIMEOUT_MS: 600000, // 10 minutes
14
+ DEFAULT_POLL_INTERVAL_MS: 50
15
+ });
16
+
17
+ /**
18
+ * Non-spinning asynchronous wait loop for suspended execution boundaries.
19
+ * Uses event loop timers (setTimeout) with 0% CPU consumption while suspended.
20
+ *
21
+ * @param {object} options
22
+ * @param {Function} options.checkControlStateFn - Pure getter returning current ControlState
23
+ * @param {number} [options.pollIntervalMs=50] - Interval between state checks
24
+ * @param {number} [options.timeoutMs=600000] - Safety timeout ceiling in ms
25
+ * @param {AbortSignal} [options.signal=null] - Optional AbortSignal
26
+ * @returns {Promise<object>} Outcome of suspension wait
27
+ */
28
+ export function waitForSuspensionResume({
29
+ checkControlStateFn,
30
+ pollIntervalMs = SUSPENSION_CONSTANTS.DEFAULT_POLL_INTERVAL_MS,
31
+ timeoutMs = SUSPENSION_CONSTANTS.DEFAULT_SAFETY_TIMEOUT_MS,
32
+ signal = null
33
+ } = {}) {
34
+ return new Promise((resolve) => {
35
+ const startMs = Date.now();
36
+ let timer = null;
37
+
38
+ const cleanup = () => {
39
+ if (timer) clearTimeout(timer);
40
+ if (signal && onAbort) signal.removeEventListener('abort', onAbort);
41
+ };
42
+
43
+ const onAbort = () => {
44
+ cleanup();
45
+ resolve({
46
+ resumed: false,
47
+ aborted: true,
48
+ decision: 'deny',
49
+ reason: 'Suspension aborted via signal'
50
+ });
51
+ };
52
+
53
+ if (signal) {
54
+ if (signal.aborted) {
55
+ return resolve({
56
+ resumed: false,
57
+ aborted: true,
58
+ decision: 'deny',
59
+ reason: 'Suspension aborted via signal'
60
+ });
61
+ }
62
+ signal.addEventListener('abort', onAbort, { once: true });
63
+ }
64
+
65
+ const check = () => {
66
+ const now = Date.now();
67
+ const elapsed = now - startMs;
68
+
69
+ // 1. Safety timeout release
70
+ if (elapsed >= timeoutMs) {
71
+ cleanup();
72
+ return resolve({
73
+ resumed: false,
74
+ timeout: true,
75
+ decision: 'deny',
76
+ reason: `timeout: suspended execution exceeded ${timeoutMs}ms safety ceiling`
77
+ });
78
+ }
79
+
80
+ // 2. Query state
81
+ let currentState = null;
82
+ try {
83
+ currentState = typeof checkControlStateFn === 'function' ? checkControlStateFn() : null;
84
+ } catch (err) {
85
+ cleanup();
86
+ return resolve({
87
+ resumed: false,
88
+ error: true,
89
+ decision: 'deny',
90
+ reason: `Failed to query control state: ${err.message}`
91
+ });
92
+ }
93
+
94
+ const state = currentState?.state || CONTROL_STATES.RUNNING;
95
+
96
+ // 3. Terminal state: ABORTED cancels immediately
97
+ if (state === CONTROL_STATES.ABORTED) {
98
+ cleanup();
99
+ return resolve({
100
+ resumed: false,
101
+ aborted: true,
102
+ decision: 'deny',
103
+ reason: currentState?.reason || 'Session aborted by user'
104
+ });
105
+ }
106
+
107
+ // 4. Resume states: RUNNING or STEP allows execution to proceed
108
+ if (state === CONTROL_STATES.RUNNING) {
109
+ cleanup();
110
+ return resolve({
111
+ resumed: true,
112
+ decision: 'allow',
113
+ state: CONTROL_STATES.RUNNING,
114
+ reason: currentState?.reason || 'Execution resumed'
115
+ });
116
+ }
117
+
118
+ if (state === CONTROL_STATES.STEP) {
119
+ cleanup();
120
+ return resolve({
121
+ resumed: true,
122
+ decision: 'allow',
123
+ consumeStep: true,
124
+ state: CONTROL_STATES.STEP,
125
+ stepRemaining: currentState?.stepRemaining ?? 1,
126
+ reason: currentState?.reason || 'Single step execution'
127
+ });
128
+ }
129
+
130
+ // Still paused/rewinding: schedule next check non-spinning
131
+ timer = setTimeout(check, pollIntervalMs);
132
+ };
133
+
134
+ // Execute first check immediately
135
+ check();
136
+ });
137
+ }
138
+
139
+ /**
140
+ * Normalizes tool boundary hook output to Claude Code proto-safe schema.
141
+ * Enforces Mod Law 5 fail-closed behavior on exceptions or invalid inputs.
142
+ *
143
+ * @param {*} output - Hook evaluation output
144
+ * @param {object} [options]
145
+ * @returns {object} Normalized proto-safe result
146
+ */
147
+ export function toProtoSafePreHookOutput(output, options = {}) {
148
+ if (!output || typeof output !== 'object') {
149
+ return {
150
+ decision: 'deny',
151
+ reason: options.fallbackReason || 'Tool boundary check failed closed'
152
+ };
153
+ }
154
+
155
+ const rawDecision = String(output.decision || output.permissionDecision || '').toLowerCase();
156
+ let decision = 'allow';
157
+
158
+ if (['deny', 'block', 'reject'].includes(rawDecision)) {
159
+ decision = 'deny';
160
+ } else if (['ask', 'defer'].includes(rawDecision)) {
161
+ decision = 'ask';
162
+ } else if (rawDecision === 'suspend') {
163
+ decision = 'suspend';
164
+ } else {
165
+ decision = 'allow';
166
+ }
167
+
168
+ const result = {
169
+ ...output,
170
+ decision
171
+ };
172
+
173
+ if (output.reason || output.permissionDecisionReason) {
174
+ result.reason = String(output.reason || output.permissionDecisionReason);
175
+ }
176
+
177
+ return result;
178
+ }
179
+
180
+ /**
181
+ * Wraps a tool hook execution function in a Mod Law 5 compliant try-catch block,
182
+ * guaranteeing zero crashes and fail-closed security.
183
+ *
184
+ * @param {Function} fn
185
+ * @returns {Promise<object>}
186
+ */
187
+ export async function wrapSafeToolBoundary(fn) {
188
+ try {
189
+ const res = await fn();
190
+ return toProtoSafePreHookOutput(res);
191
+ } catch (err) {
192
+ return toProtoSafePreHookOutput(null, {
193
+ fallbackReason: `[Highbeam Fail-Closed] ${err.message}`
194
+ });
195
+ }
196
+ }
197
+