@draht/coding-agent 2026.7.30 → 2026.9.5-1

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 (459) hide show
  1. package/CHANGELOG.md +154 -0
  2. package/README.md +46 -2
  3. package/agents/debugger.md +12 -1
  4. package/agents/git-committer.md +1 -0
  5. package/agents/implementer.md +20 -0
  6. package/agents/investigator.md +75 -0
  7. package/agents/reviewer.md +7 -0
  8. package/agents/spec-reviewer.md +66 -0
  9. package/agents/verifier.md +4 -3
  10. package/bin/draht-tools.cjs +472 -41
  11. package/dist/agents/debugger.md +12 -1
  12. package/dist/agents/git-committer.md +1 -0
  13. package/dist/agents/implementer.md +20 -0
  14. package/dist/agents/investigator.md +75 -0
  15. package/dist/agents/reviewer.md +7 -0
  16. package/dist/agents/spec-reviewer.md +66 -0
  17. package/dist/agents/verifier.md +4 -3
  18. package/dist/cli/args.d.ts +10 -0
  19. package/dist/cli/args.d.ts.map +1 -1
  20. package/dist/cli/args.js +69 -2
  21. package/dist/cli/args.js.map +1 -1
  22. package/dist/cli/attach-mode.d.ts +61 -0
  23. package/dist/cli/attach-mode.d.ts.map +1 -1
  24. package/dist/cli/attach-mode.js +243 -5
  25. package/dist/cli/attach-mode.js.map +1 -1
  26. package/dist/cli/credential-print.d.ts +1 -1
  27. package/dist/cli/credential-print.d.ts.map +1 -1
  28. package/dist/cli/credential-print.js +5 -4
  29. package/dist/cli/credential-print.js.map +1 -1
  30. package/dist/config.d.ts +9 -0
  31. package/dist/config.d.ts.map +1 -1
  32. package/dist/config.js +31 -4
  33. package/dist/config.js.map +1 -1
  34. package/dist/core/agent-session-runtime.d.ts +17 -1
  35. package/dist/core/agent-session-runtime.d.ts.map +1 -1
  36. package/dist/core/agent-session-runtime.js +87 -30
  37. package/dist/core/agent-session-runtime.js.map +1 -1
  38. package/dist/core/agent-session-services.d.ts +1 -1
  39. package/dist/core/agent-session-services.d.ts.map +1 -1
  40. package/dist/core/agent-session-services.js +1 -0
  41. package/dist/core/agent-session-services.js.map +1 -1
  42. package/dist/core/agent-session.d.ts +35 -16
  43. package/dist/core/agent-session.d.ts.map +1 -1
  44. package/dist/core/agent-session.js +149 -64
  45. package/dist/core/agent-session.js.map +1 -1
  46. package/dist/core/auth-storage.d.ts +5 -1
  47. package/dist/core/auth-storage.d.ts.map +1 -1
  48. package/dist/core/auth-storage.js +72 -15
  49. package/dist/core/auth-storage.js.map +1 -1
  50. package/dist/core/builtins/checkpoints.d.ts +20 -0
  51. package/dist/core/builtins/checkpoints.d.ts.map +1 -0
  52. package/dist/core/builtins/checkpoints.js +161 -0
  53. package/dist/core/builtins/checkpoints.js.map +1 -0
  54. package/dist/core/builtins/duet.d.ts +26 -0
  55. package/dist/core/builtins/duet.d.ts.map +1 -0
  56. package/dist/core/builtins/duet.js +660 -0
  57. package/dist/core/builtins/duet.js.map +1 -0
  58. package/dist/core/builtins/index.d.ts.map +1 -1
  59. package/dist/core/builtins/index.js +7 -1
  60. package/dist/core/builtins/index.js.map +1 -1
  61. package/dist/core/builtins/subagent.d.ts +24 -4
  62. package/dist/core/builtins/subagent.d.ts.map +1 -1
  63. package/dist/core/builtins/subagent.js +278 -35
  64. package/dist/core/builtins/subagent.js.map +1 -1
  65. package/dist/core/checkpoints/checkpoint-cli.d.ts +17 -0
  66. package/dist/core/checkpoints/checkpoint-cli.d.ts.map +1 -0
  67. package/dist/core/checkpoints/checkpoint-cli.js +78 -0
  68. package/dist/core/checkpoints/checkpoint-cli.js.map +1 -0
  69. package/dist/core/checkpoints/checkpoint-manager.d.ts +294 -0
  70. package/dist/core/checkpoints/checkpoint-manager.d.ts.map +1 -0
  71. package/dist/core/checkpoints/checkpoint-manager.js +865 -0
  72. package/dist/core/checkpoints/checkpoint-manager.js.map +1 -0
  73. package/dist/core/checkpoints/rewind.d.ts +141 -0
  74. package/dist/core/checkpoints/rewind.d.ts.map +1 -0
  75. package/dist/core/checkpoints/rewind.js +246 -0
  76. package/dist/core/checkpoints/rewind.js.map +1 -0
  77. package/dist/core/compaction/branch-summarization.d.ts +1 -1
  78. package/dist/core/compaction/branch-summarization.d.ts.map +1 -1
  79. package/dist/core/compaction/branch-summarization.js +9 -4
  80. package/dist/core/compaction/branch-summarization.js.map +1 -1
  81. package/dist/core/compaction/compaction.d.ts +5 -0
  82. package/dist/core/compaction/compaction.d.ts.map +1 -1
  83. package/dist/core/compaction/compaction.js +25 -4
  84. package/dist/core/compaction/compaction.js.map +1 -1
  85. package/dist/core/extensions/index.d.ts +1 -1
  86. package/dist/core/extensions/index.d.ts.map +1 -1
  87. package/dist/core/extensions/index.js.map +1 -1
  88. package/dist/core/extensions/loader.d.ts.map +1 -1
  89. package/dist/core/extensions/loader.js +83 -20
  90. package/dist/core/extensions/loader.js.map +1 -1
  91. package/dist/core/extensions/runner.d.ts +13 -2
  92. package/dist/core/extensions/runner.d.ts.map +1 -1
  93. package/dist/core/extensions/runner.js +37 -2
  94. package/dist/core/extensions/runner.js.map +1 -1
  95. package/dist/core/extensions/types.d.ts +189 -6
  96. package/dist/core/extensions/types.d.ts.map +1 -1
  97. package/dist/core/extensions/types.js.map +1 -1
  98. package/dist/core/http-dispatcher.d.ts.map +1 -1
  99. package/dist/core/http-dispatcher.js +7 -0
  100. package/dist/core/http-dispatcher.js.map +1 -1
  101. package/dist/core/index.d.ts +1 -1
  102. package/dist/core/index.d.ts.map +1 -1
  103. package/dist/core/index.js.map +1 -1
  104. package/dist/core/keybindings.d.ts +5 -0
  105. package/dist/core/keybindings.d.ts.map +1 -1
  106. package/dist/core/keybindings.js +1 -0
  107. package/dist/core/keybindings.js.map +1 -1
  108. package/dist/core/model-registry.d.ts +3 -2
  109. package/dist/core/model-registry.d.ts.map +1 -1
  110. package/dist/core/model-registry.js +8 -8
  111. package/dist/core/model-registry.js.map +1 -1
  112. package/dist/core/model-resolver.d.ts.map +1 -1
  113. package/dist/core/model-resolver.js +34 -7
  114. package/dist/core/model-resolver.js.map +1 -1
  115. package/dist/core/model-runtime.d.ts +7 -1
  116. package/dist/core/model-runtime.d.ts.map +1 -1
  117. package/dist/core/model-runtime.js +30 -10
  118. package/dist/core/model-runtime.js.map +1 -1
  119. package/dist/core/multi-agent/permission-gate.d.ts.map +1 -1
  120. package/dist/core/multi-agent/permission-gate.js +4 -3
  121. package/dist/core/multi-agent/permission-gate.js.map +1 -1
  122. package/dist/core/multi-agent/worktree.d.ts +2 -0
  123. package/dist/core/multi-agent/worktree.d.ts.map +1 -1
  124. package/dist/core/multi-agent/worktree.js +2 -2
  125. package/dist/core/multi-agent/worktree.js.map +1 -1
  126. package/dist/core/package-manager.d.ts +7 -1
  127. package/dist/core/package-manager.d.ts.map +1 -1
  128. package/dist/core/package-manager.js +21 -44
  129. package/dist/core/package-manager.js.map +1 -1
  130. package/dist/core/permission-relay/index.d.ts +19 -0
  131. package/dist/core/permission-relay/index.d.ts.map +1 -0
  132. package/dist/core/permission-relay/index.js +49 -0
  133. package/dist/core/permission-relay/index.js.map +1 -0
  134. package/dist/core/permission-relay/relay-ui-context.d.ts +39 -0
  135. package/dist/core/permission-relay/relay-ui-context.d.ts.map +1 -0
  136. package/dist/core/permission-relay/relay-ui-context.js +788 -0
  137. package/dist/core/permission-relay/relay-ui-context.js.map +1 -0
  138. package/dist/core/permission-relay/types.d.ts +222 -0
  139. package/dist/core/permission-relay/types.d.ts.map +1 -0
  140. package/dist/core/permission-relay/types.js +15 -0
  141. package/dist/core/permission-relay/types.js.map +1 -0
  142. package/dist/core/pi-manifest.d.ts +14 -0
  143. package/dist/core/pi-manifest.d.ts.map +1 -0
  144. package/dist/core/pi-manifest.js +35 -0
  145. package/dist/core/pi-manifest.js.map +1 -0
  146. package/dist/core/project-trust.js +2 -2
  147. package/dist/core/project-trust.js.map +1 -1
  148. package/dist/core/resource-loader.d.ts +21 -0
  149. package/dist/core/resource-loader.d.ts.map +1 -1
  150. package/dist/core/resource-loader.js +101 -24
  151. package/dist/core/resource-loader.js.map +1 -1
  152. package/dist/core/sandbox/bash-operations.d.ts +149 -0
  153. package/dist/core/sandbox/bash-operations.d.ts.map +1 -0
  154. package/dist/core/sandbox/bash-operations.js +163 -0
  155. package/dist/core/sandbox/bash-operations.js.map +1 -0
  156. package/dist/core/sandbox/env.d.ts +83 -0
  157. package/dist/core/sandbox/env.d.ts.map +1 -0
  158. package/dist/core/sandbox/env.js +123 -0
  159. package/dist/core/sandbox/env.js.map +1 -0
  160. package/dist/core/sandbox/executor.d.ts +104 -0
  161. package/dist/core/sandbox/executor.d.ts.map +1 -0
  162. package/dist/core/sandbox/executor.js +92 -0
  163. package/dist/core/sandbox/executor.js.map +1 -0
  164. package/dist/core/sandbox/index.d.ts +36 -0
  165. package/dist/core/sandbox/index.d.ts.map +1 -0
  166. package/dist/core/sandbox/index.js +36 -0
  167. package/dist/core/sandbox/index.js.map +1 -0
  168. package/dist/core/sandbox/linux.d.ts +121 -0
  169. package/dist/core/sandbox/linux.d.ts.map +1 -0
  170. package/dist/core/sandbox/linux.js +260 -0
  171. package/dist/core/sandbox/linux.js.map +1 -0
  172. package/dist/core/sandbox/policy.d.ts +142 -0
  173. package/dist/core/sandbox/policy.d.ts.map +1 -0
  174. package/dist/core/sandbox/policy.js +297 -0
  175. package/dist/core/sandbox/policy.js.map +1 -0
  176. package/dist/core/sandbox/real-path.d.ts +112 -0
  177. package/dist/core/sandbox/real-path.d.ts.map +1 -0
  178. package/dist/core/sandbox/real-path.js +158 -0
  179. package/dist/core/sandbox/real-path.js.map +1 -0
  180. package/dist/core/sandbox/seatbelt-profile.d.ts +95 -0
  181. package/dist/core/sandbox/seatbelt-profile.d.ts.map +1 -0
  182. package/dist/core/sandbox/seatbelt-profile.js +239 -0
  183. package/dist/core/sandbox/seatbelt-profile.js.map +1 -0
  184. package/dist/core/sandbox/seatbelt.d.ts +95 -0
  185. package/dist/core/sandbox/seatbelt.d.ts.map +1 -0
  186. package/dist/core/sandbox/seatbelt.js +154 -0
  187. package/dist/core/sandbox/seatbelt.js.map +1 -0
  188. package/dist/core/sandbox/self-test.d.ts +109 -0
  189. package/dist/core/sandbox/self-test.d.ts.map +1 -0
  190. package/dist/core/sandbox/self-test.js +369 -0
  191. package/dist/core/sandbox/self-test.js.map +1 -0
  192. package/dist/core/sandbox/spawn.d.ts +33 -0
  193. package/dist/core/sandbox/spawn.d.ts.map +1 -0
  194. package/dist/core/sandbox/spawn.js +87 -0
  195. package/dist/core/sandbox/spawn.js.map +1 -0
  196. package/dist/core/sdk.d.ts.map +1 -1
  197. package/dist/core/sdk.js +3 -1
  198. package/dist/core/sdk.js.map +1 -1
  199. package/dist/core/session-manager.d.ts +60 -1
  200. package/dist/core/session-manager.d.ts.map +1 -1
  201. package/dist/core/session-manager.js +53 -6
  202. package/dist/core/session-manager.js.map +1 -1
  203. package/dist/core/settings-manager.d.ts +21 -0
  204. package/dist/core/settings-manager.d.ts.map +1 -1
  205. package/dist/core/settings-manager.js +36 -16
  206. package/dist/core/settings-manager.js.map +1 -1
  207. package/dist/core/skills.d.ts +3 -1
  208. package/dist/core/skills.d.ts.map +1 -1
  209. package/dist/core/skills.js +19 -6
  210. package/dist/core/skills.js.map +1 -1
  211. package/dist/core/slash-commands.d.ts.map +1 -1
  212. package/dist/core/slash-commands.js +1 -0
  213. package/dist/core/slash-commands.js.map +1 -1
  214. package/dist/core/soak/soak-log.d.ts +298 -0
  215. package/dist/core/soak/soak-log.d.ts.map +1 -0
  216. package/dist/core/soak/soak-log.js +660 -0
  217. package/dist/core/soak/soak-log.js.map +1 -0
  218. package/dist/core/soak/soak-reader.d.ts +60 -0
  219. package/dist/core/soak/soak-reader.d.ts.map +1 -0
  220. package/dist/core/soak/soak-reader.js +106 -0
  221. package/dist/core/soak/soak-reader.js.map +1 -0
  222. package/dist/core/socket-server/discovery.d.ts +78 -1
  223. package/dist/core/socket-server/discovery.d.ts.map +1 -1
  224. package/dist/core/socket-server/discovery.js +356 -37
  225. package/dist/core/socket-server/discovery.js.map +1 -1
  226. package/dist/core/socket-server/index.d.ts +10 -4
  227. package/dist/core/socket-server/index.d.ts.map +1 -1
  228. package/dist/core/socket-server/index.js +6 -3
  229. package/dist/core/socket-server/index.js.map +1 -1
  230. package/dist/core/socket-server/permission-delivery.d.ts +125 -0
  231. package/dist/core/socket-server/permission-delivery.d.ts.map +1 -0
  232. package/dist/core/socket-server/permission-delivery.js +152 -0
  233. package/dist/core/socket-server/permission-delivery.js.map +1 -0
  234. package/dist/core/socket-server/permission-registry.d.ts +301 -0
  235. package/dist/core/socket-server/permission-registry.d.ts.map +1 -0
  236. package/dist/core/socket-server/permission-registry.js +410 -0
  237. package/dist/core/socket-server/permission-registry.js.map +1 -0
  238. package/dist/core/socket-server/permission-relay.d.ts +81 -0
  239. package/dist/core/socket-server/permission-relay.d.ts.map +1 -0
  240. package/dist/core/socket-server/permission-relay.js +528 -0
  241. package/dist/core/socket-server/permission-relay.js.map +1 -0
  242. package/dist/core/socket-server/safe-text.d.ts +83 -0
  243. package/dist/core/socket-server/safe-text.d.ts.map +1 -0
  244. package/dist/core/socket-server/safe-text.js +277 -0
  245. package/dist/core/socket-server/safe-text.js.map +1 -0
  246. package/dist/core/socket-server/session-integration.d.ts +65 -2
  247. package/dist/core/socket-server/session-integration.d.ts.map +1 -1
  248. package/dist/core/socket-server/session-integration.js +434 -32
  249. package/dist/core/socket-server/session-integration.js.map +1 -1
  250. package/dist/core/socket-server/socket-client.d.ts +21 -2
  251. package/dist/core/socket-server/socket-client.d.ts.map +1 -1
  252. package/dist/core/socket-server/socket-client.js +52 -1
  253. package/dist/core/socket-server/socket-client.js.map +1 -1
  254. package/dist/core/socket-server/socket-server.d.ts +152 -1
  255. package/dist/core/socket-server/socket-server.d.ts.map +1 -1
  256. package/dist/core/socket-server/socket-server.js +775 -26
  257. package/dist/core/socket-server/socket-server.js.map +1 -1
  258. package/dist/core/socket-server/types.d.ts +106 -2
  259. package/dist/core/socket-server/types.d.ts.map +1 -1
  260. package/dist/core/socket-server/types.js +13 -1
  261. package/dist/core/socket-server/types.js.map +1 -1
  262. package/dist/core/system-prompt.d.ts.map +1 -1
  263. package/dist/core/system-prompt.js +8 -9
  264. package/dist/core/system-prompt.js.map +1 -1
  265. package/dist/core/tools/bash.d.ts +1 -1
  266. package/dist/core/tools/bash.d.ts.map +1 -1
  267. package/dist/core/tools/bash.js +5 -2
  268. package/dist/core/tools/bash.js.map +1 -1
  269. package/dist/core/tools/edit.d.ts.map +1 -1
  270. package/dist/core/tools/edit.js +17 -2
  271. package/dist/core/tools/edit.js.map +1 -1
  272. package/dist/core/tools/find.d.ts +3 -0
  273. package/dist/core/tools/find.d.ts.map +1 -1
  274. package/dist/core/tools/find.js +11 -18
  275. package/dist/core/tools/find.js.map +1 -1
  276. package/dist/core/trust-manager.d.ts +6 -4
  277. package/dist/core/trust-manager.d.ts.map +1 -1
  278. package/dist/core/trust-manager.js +55 -21
  279. package/dist/core/trust-manager.js.map +1 -1
  280. package/dist/extensions/index.d.ts.map +1 -1
  281. package/dist/extensions/index.js +5 -1
  282. package/dist/extensions/index.js.map +1 -1
  283. package/dist/extensions/llama/provider.d.ts.map +1 -1
  284. package/dist/extensions/llama/provider.js +5 -1
  285. package/dist/extensions/llama/provider.js.map +1 -1
  286. package/dist/extensions/stub-provider/index.d.ts +9 -0
  287. package/dist/extensions/stub-provider/index.d.ts.map +1 -0
  288. package/dist/extensions/stub-provider/index.js +13 -0
  289. package/dist/extensions/stub-provider/index.js.map +1 -0
  290. package/dist/extensions/stub-provider/provider.d.ts +77 -0
  291. package/dist/extensions/stub-provider/provider.d.ts.map +1 -0
  292. package/dist/extensions/stub-provider/provider.js +193 -0
  293. package/dist/extensions/stub-provider/provider.js.map +1 -0
  294. package/dist/hooks/gsd/draht-quality-gate.js +3 -3
  295. package/dist/index.d.ts +1 -1
  296. package/dist/index.d.ts.map +1 -1
  297. package/dist/index.js.map +1 -1
  298. package/dist/main.d.ts.map +1 -1
  299. package/dist/main.js +242 -45
  300. package/dist/main.js.map +1 -1
  301. package/dist/modes/interactive/components/config-selector.d.ts.map +1 -1
  302. package/dist/modes/interactive/components/config-selector.js +3 -2
  303. package/dist/modes/interactive/components/config-selector.js.map +1 -1
  304. package/dist/modes/interactive/components/extension-selector.d.ts +49 -0
  305. package/dist/modes/interactive/components/extension-selector.d.ts.map +1 -1
  306. package/dist/modes/interactive/components/extension-selector.js +202 -5
  307. package/dist/modes/interactive/components/extension-selector.js.map +1 -1
  308. package/dist/modes/interactive/components/session-selector.d.ts.map +1 -1
  309. package/dist/modes/interactive/components/session-selector.js +10 -2
  310. package/dist/modes/interactive/components/session-selector.js.map +1 -1
  311. package/dist/modes/interactive/components/settings-selector.d.ts +2 -0
  312. package/dist/modes/interactive/components/settings-selector.d.ts.map +1 -1
  313. package/dist/modes/interactive/components/settings-selector.js +10 -0
  314. package/dist/modes/interactive/components/settings-selector.js.map +1 -1
  315. package/dist/modes/interactive/components/tool-execution.d.ts.map +1 -1
  316. package/dist/modes/interactive/components/tool-execution.js +10 -1
  317. package/dist/modes/interactive/components/tool-execution.js.map +1 -1
  318. package/dist/modes/interactive/components/tree-selector.d.ts +20 -2
  319. package/dist/modes/interactive/components/tree-selector.d.ts.map +1 -1
  320. package/dist/modes/interactive/components/tree-selector.js +21 -5
  321. package/dist/modes/interactive/components/tree-selector.js.map +1 -1
  322. package/dist/modes/interactive/interactive-mode.d.ts +97 -3
  323. package/dist/modes/interactive/interactive-mode.d.ts.map +1 -1
  324. package/dist/modes/interactive/interactive-mode.js +394 -24
  325. package/dist/modes/interactive/interactive-mode.js.map +1 -1
  326. package/dist/modes/rpc/rpc-mode.d.ts.map +1 -1
  327. package/dist/modes/rpc/rpc-mode.js +165 -7
  328. package/dist/modes/rpc/rpc-mode.js.map +1 -1
  329. package/dist/modes/rpc/rpc-types.d.ts +68 -1
  330. package/dist/modes/rpc/rpc-types.d.ts.map +1 -1
  331. package/dist/modes/rpc/rpc-types.js.map +1 -1
  332. package/dist/prompts/commands/atomic-commit.md +1 -12
  333. package/dist/prompts/commands/brainstorm.md +12 -15
  334. package/dist/prompts/commands/create-verification-skill.md +108 -0
  335. package/dist/prompts/commands/discuss-phase.md +3 -14
  336. package/dist/prompts/commands/execute-phase.md +3 -11
  337. package/dist/prompts/commands/fix.md +41 -18
  338. package/dist/prompts/commands/grill.md +66 -0
  339. package/dist/prompts/commands/init-project.md +5 -15
  340. package/dist/prompts/commands/map-codebase.md +1 -13
  341. package/dist/prompts/commands/new-project.md +5 -15
  342. package/dist/prompts/commands/next-milestone.md +1 -13
  343. package/dist/prompts/commands/orchestrate.md +1 -1
  344. package/dist/prompts/commands/pause-work.md +1 -13
  345. package/dist/prompts/commands/plan-phase.md +2 -11
  346. package/dist/prompts/commands/progress.md +0 -13
  347. package/dist/prompts/commands/quick.md +3 -11
  348. package/dist/prompts/commands/resolve-conflicts.md +71 -0
  349. package/dist/prompts/commands/resume-work.md +0 -13
  350. package/dist/prompts/commands/review.md +4 -13
  351. package/dist/prompts/commands/triage.md +159 -0
  352. package/dist/prompts/commands/verify-work.md +4 -14
  353. package/dist/prompts/commands/why.md +135 -0
  354. package/dist/skills/atomic-reasoning/SKILL.md +115 -0
  355. package/dist/skills/blast-radius/SKILL.md +55 -0
  356. package/dist/skills/epistemics/SKILL.md +99 -0
  357. package/dist/skills/hexagon-animation/SKILL.md +49 -0
  358. package/dist/skills/hexagon-animation/generate.mjs +81 -0
  359. package/dist/skills/hexagon-animation/template.html +361 -0
  360. package/dist/skills/typescript-discipline/SKILL.md +50 -0
  361. package/dist/skills/typescript-discipline/references/patterns.md +294 -0
  362. package/dist/skills/unslop/SKILL.md +101 -0
  363. package/dist/utils/canonical-path.d.ts +28 -0
  364. package/dist/utils/canonical-path.d.ts.map +1 -0
  365. package/dist/utils/canonical-path.js +90 -0
  366. package/dist/utils/canonical-path.js.map +1 -0
  367. package/dist/utils/child-process.d.ts +12 -1
  368. package/dist/utils/child-process.d.ts.map +1 -1
  369. package/dist/utils/child-process.js +25 -8
  370. package/dist/utils/child-process.js.map +1 -1
  371. package/dist/utils/clipboard.d.ts +1 -1
  372. package/dist/utils/clipboard.d.ts.map +1 -1
  373. package/dist/utils/clipboard.js +22 -2
  374. package/dist/utils/clipboard.js.map +1 -1
  375. package/dist/utils/exif-orientation.d.ts.map +1 -1
  376. package/dist/utils/exif-orientation.js +2 -3
  377. package/dist/utils/exif-orientation.js.map +1 -1
  378. package/dist/utils/paths.d.ts +2 -7
  379. package/dist/utils/paths.d.ts.map +1 -1
  380. package/dist/utils/paths.js +13 -15
  381. package/dist/utils/paths.js.map +1 -1
  382. package/dist/utils/shell.d.ts.map +1 -1
  383. package/dist/utils/shell.js +6 -4
  384. package/dist/utils/shell.js.map +1 -1
  385. package/dist/utils/tools-manager.d.ts.map +1 -1
  386. package/dist/utils/tools-manager.js +3 -5
  387. package/dist/utils/tools-manager.js.map +1 -1
  388. package/docs/attachable-sessions.md +79 -0
  389. package/docs/compaction.md +21 -21
  390. package/docs/containerization.md +23 -23
  391. package/docs/custom-provider.md +16 -16
  392. package/docs/development.md +9 -9
  393. package/docs/docs.json +6 -2
  394. package/docs/duet.md +42 -0
  395. package/docs/extensions.md +58 -58
  396. package/docs/index.md +10 -10
  397. package/docs/json.md +7 -7
  398. package/docs/keybindings.md +6 -5
  399. package/docs/llama-cpp.md +6 -6
  400. package/docs/models.md +6 -6
  401. package/docs/packages.md +43 -43
  402. package/docs/prompt-templates.md +4 -4
  403. package/docs/providers.md +12 -12
  404. package/docs/quickstart.md +32 -32
  405. package/docs/rpc.md +83 -12
  406. package/docs/sdk.md +15 -15
  407. package/docs/security.md +18 -18
  408. package/docs/session-format.md +35 -13
  409. package/docs/sessions.md +17 -14
  410. package/docs/settings.md +25 -18
  411. package/docs/shell-aliases.md +2 -2
  412. package/docs/skills.md +12 -11
  413. package/docs/terminal-setup.md +12 -12
  414. package/docs/termux.md +6 -6
  415. package/docs/themes.md +11 -11
  416. package/docs/tmux.md +4 -4
  417. package/docs/tui.md +5 -5
  418. package/docs/usage.md +50 -50
  419. package/docs/windows.md +2 -2
  420. package/examples/extensions/overlay-qa-tests.ts +3 -3
  421. package/hooks/gsd/draht-quality-gate.js +3 -3
  422. package/package.json +11 -10
  423. package/prompts/commands/atomic-commit.md +1 -12
  424. package/prompts/commands/brainstorm.md +12 -15
  425. package/prompts/commands/create-verification-skill.md +108 -0
  426. package/prompts/commands/discuss-phase.md +3 -14
  427. package/prompts/commands/execute-phase.md +3 -11
  428. package/prompts/commands/fix.md +41 -18
  429. package/prompts/commands/grill.md +66 -0
  430. package/prompts/commands/init-project.md +5 -15
  431. package/prompts/commands/map-codebase.md +1 -13
  432. package/prompts/commands/new-project.md +5 -15
  433. package/prompts/commands/next-milestone.md +1 -13
  434. package/prompts/commands/orchestrate.md +1 -1
  435. package/prompts/commands/pause-work.md +1 -13
  436. package/prompts/commands/plan-phase.md +2 -11
  437. package/prompts/commands/progress.md +0 -13
  438. package/prompts/commands/quick.md +3 -11
  439. package/prompts/commands/resolve-conflicts.md +71 -0
  440. package/prompts/commands/resume-work.md +0 -13
  441. package/prompts/commands/review.md +4 -13
  442. package/prompts/commands/triage.md +159 -0
  443. package/prompts/commands/verify-work.md +4 -14
  444. package/prompts/commands/why.md +135 -0
  445. package/skills/atomic-reasoning/SKILL.md +115 -0
  446. package/skills/blast-radius/SKILL.md +55 -0
  447. package/skills/epistemics/SKILL.md +99 -0
  448. package/skills/hexagon-animation/SKILL.md +49 -0
  449. package/skills/hexagon-animation/generate.mjs +81 -0
  450. package/skills/hexagon-animation/template.html +361 -0
  451. package/skills/typescript-discipline/SKILL.md +50 -0
  452. package/skills/typescript-discipline/references/patterns.md +294 -0
  453. package/skills/unslop/SKILL.md +101 -0
  454. package/dist/prompts/agents/build.md +0 -86
  455. package/dist/prompts/agents/plan.md +0 -79
  456. package/dist/prompts/agents/verify.md +0 -69
  457. package/prompts/agents/build.md +0 -86
  458. package/prompts/agents/plan.md +0 -79
  459. package/prompts/agents/verify.md +0 -69
@@ -0,0 +1,660 @@
1
+ /**
2
+ * SOAK LOG — the append-only, rotating, restart-surviving JSONL that a long-run
3
+ * verdict reads back weeks later.
4
+ *
5
+ * ─────────────────────────────────────────────────────────────────────────────
6
+ * FILE FORMAT CONTRACT (v1)
7
+ * ─────────────────────────────────────────────────────────────────────────────
8
+ * This comment is the contract, not a description of this implementation. A
9
+ * second writer — the daemon half, which lives on the far side of a package
10
+ * boundary that forbids importing this package — must be implementable from
11
+ * this section alone. Do NOT export a shared module across that boundary; the
12
+ * two halves agree on these bytes and on nothing else.
13
+ *
14
+ * LOCATION
15
+ * <agentDir>/soak/ directory, mode 0700
16
+ * <agentDir>/soak/<stem>.jsonl the ACTIVE file, mode 0600
17
+ * <agentDir>/soak/<stem>-<gen>.jsonl a ROTATED generation, mode 0600
18
+ * <agentDir>/soak/<stem>.rotate.lock the rotation lock, mode 0600
19
+ *
20
+ * `<agentDir>` is the coding agent's config dir (honours DRAHT_CODING_AGENT_DIR).
21
+ * `<stem>` names the WRITING HALF, one file per half: "session" for a session
22
+ * process, "daemon" for the gateway/daemon process. The halves observe
23
+ * different events from different lifecycles; they are never interleaved into
24
+ * one file and are joined by `sessionId`/`wall` at verdict time.
25
+ * `<gen>` is `<compact-utc>-<pid>-<counter>` and is UNIQUE FOREVER — a
26
+ * generation name is never reused, so a rotation can never clobber evidence.
27
+ * Example: `session-20260822T114530123Z-40321-0.jsonl`.
28
+ *
29
+ * RECORDS
30
+ * One JSON object per line, UTF-8, terminated by "\n". No trailing commas, no
31
+ * pretty printing, no multi-line values. Every record carries:
32
+ * level "info" | "warn" | "error" (matches the gateway logger shape)
33
+ * timestamp ISO-8601 string (matches the gateway logger shape)
34
+ * event string (see SOAK_EVENTS)
35
+ * v 1 (this format version)
36
+ * wall Date.now() milliseconds
37
+ * mono performance.now() milliseconds
38
+ * uptimeMs process.uptime() * 1000
39
+ * pid writing process id
40
+ * rss process.memoryUsage().rss bytes
41
+ * plus whatever fields the event carries. The fields above are stamped LAST,
42
+ * after the event's own: a caller field that collides with one of them is
43
+ * dropped rather than honoured, because a record whose `pid` or `wall` came
44
+ * from a call site is a record the reader classifies as malformed and drops.
45
+ * `sessionId` is present on every
46
+ * record a session process writes; prompt/permission records additionally
47
+ * carry `requestId`, so this stream can be JOINED against the durable
48
+ * per-session permission rows without duplicating any decision here.
49
+ *
50
+ * All three clocks are recorded on every record on purpose. A frozen process
51
+ * (SIGSTOP/SIGCONT, and by extension a suspended host) shows up as a WALL-CLOCK
52
+ * GAP between consecutive heartbeats, not as divergence between the clocks —
53
+ * measured, all three advanced identically across a 2,677 ms stop. Recording
54
+ * all three costs nothing and leaves the question answerable if a real lid-close
55
+ * behaves differently.
56
+ *
57
+ * APPENDING
58
+ * One open("a", 0600) / write / close per record. NOT a held descriptor: this
59
+ * writer reports an fd gauge, and holding its own fd would perturb the metric
60
+ * it publishes. Concurrent appends from many processes are safe because each
61
+ * record is a single write() to an O_APPEND descriptor.
62
+ *
63
+ * NO fsync. Measured 4.0–4.7 ms per record under Node against 0.017–0.025 ms
64
+ * under Bun; on seams that fire per client attach and per prompt that is a
65
+ * hot-path cost, and it would give materially different guarantees on the
66
+ * runtime this product actually ships as (a Bun-compiled binary). The tolerated
67
+ * failure is the loss of the last few records on a hard power cut; the reader
68
+ * is torn-tail tolerant, so that loss costs one line, never the file.
69
+ *
70
+ * ROTATION (the part that loses data if done naively — measured)
71
+ * A two-slot `rename(f, f.1)` scheme under 8 concurrent writers lost 11,148 of
72
+ * 12,000 records. The scheme below lost ZERO across 8 generations. Implement
73
+ * EXACTLY this order:
74
+ * 1. after appending, fstat the descriptor you just wrote through: that
75
+ * yields both the size and the INODE you filled;
76
+ * 2. if size < maxFileBytes, stop;
77
+ * 3. open(lockPath, "wx", 0600). EEXIST means another writer is rotating:
78
+ * give up silently and let the next append retry. (A lock whose mtime is
79
+ * older than the stale window is debris and may be removed once.)
80
+ * 4. stat the active path again and COMPARE THE INODE against step 1. A
81
+ * different inode means another writer already rotated the file you
82
+ * filled: release the lock and stop. This comparison is the whole
83
+ * correctness argument — without it, two writers rotate in sequence and
84
+ * the second one renames away a fresh file that other writers are still
85
+ * appending to.
86
+ * 5. rename the active path to a UNIQUE generation name.
87
+ * 6. prune (see RETENTION), then append ONE `rotation` record to the new
88
+ * active file naming the generation just closed and everything pruned.
89
+ * 7. unlink the lock.
90
+ *
91
+ * A writer holding a descriptor across step 5 keeps writing into the renamed
92
+ * inode. That is not loss: the reader reads every generation, so those records
93
+ * are still found. It is why generation files may keep growing after rotation
94
+ * and why file order — not byte order across files — is the only ordering the
95
+ * reader promises.
96
+ *
97
+ * RETENTION
98
+ * Two gates, BOTH must permit a delete:
99
+ * • a byte cap over the directory (maxTotalBytes), and
100
+ * • a retention FLOOR: a generation whose newest write is younger than
101
+ * `retentionFloorMs` (default 14 days) is NEVER pruned, even when the byte
102
+ * cap says prune.
103
+ * A byte-only cap sized for a quiet week silently rotates away the first days
104
+ * of a busy one, and a multi-week soak verdict would destroy its own evidence.
105
+ * When the floor blocks a prune the log simply grows; that is the intended
106
+ * trade. Every prune is named in the `rotation` record written into the
107
+ * surviving file, so a gap in the evidence is VISIBLE rather than invisible.
108
+ *
109
+ * HARD RULES FOR ANY IMPLEMENTATION
110
+ * • NEVER write to stdout or stderr. Not a warning, not a stack trace. The TUI
111
+ * owns the terminal, and a default-on session's streams are asserted
112
+ * byte-identical to a feature-off run; one stray line breaks that.
113
+ * • NEVER throw into a caller. Every failure is swallowed; the last one is
114
+ * retained on the instance for a debugger to look at, and that is all.
115
+ * • The soak directory is OUTSIDE the session store on purpose, which is what
116
+ * exempts it from the byte-identity claim.
117
+ */
118
+ import { closeSync, fstatSync, mkdirSync, openSync, readdirSync, renameSync, statSync, unlinkSync, writeSync, } from "node:fs";
119
+ import { join } from "node:path";
120
+ import { getAgentDir } from "../../config.js";
121
+ /** Format version stamped on every record as `v`. */
122
+ export const SOAK_FORMAT_VERSION = 1;
123
+ /** Directory under the agent dir that holds every soak file. */
124
+ export const SOAK_DIR_NAME = "soak";
125
+ /** File stem for the half a session process writes. */
126
+ export const SOAK_STEM_SESSION = "session";
127
+ /** File stem for the half the daemon writes (a separate implementation of this same contract). */
128
+ export const SOAK_STEM_DAEMON = "daemon";
129
+ /**
130
+ * Canonical event names. Kept as a frozen map rather than a union type so a call
131
+ * site can add a field — or a new event — without editing this file.
132
+ */
133
+ export const SOAK_EVENTS = Object.freeze({
134
+ SOCKET_BIND: "socket_bind",
135
+ SOCKET_REBIND: "socket_rebind",
136
+ SOCKET_TEARDOWN: "socket_teardown",
137
+ CLIENT_ATTACH: "client_attach",
138
+ CLIENT_DETACH: "client_detach",
139
+ CLIENT_REJECTED: "client_rejected",
140
+ PROMPT_REJECTED: "prompt_rejected",
141
+ SOCKETS_REAPED: "sockets_reaped",
142
+ HEARTBEAT: "heartbeat",
143
+ ROTATION: "rotation",
144
+ });
145
+ /** 4 MiB per generation: ~20k records of the size these events produce. */
146
+ const DEFAULT_MAX_FILE_BYTES = 4 * 1024 * 1024;
147
+ /** 64 MiB across the whole directory before the byte gate opens. */
148
+ const DEFAULT_MAX_TOTAL_BYTES = 64 * 1024 * 1024;
149
+ /** 14 days: a 7-day soak plus a full week of slack before its first day can be pruned. */
150
+ const DEFAULT_RETENTION_FLOOR_MS = 14 * 24 * 60 * 60 * 1000;
151
+ /** One heartbeat a minute: fine enough to see a sleep/wake gap, coarse enough to be free. */
152
+ const DEFAULT_HEARTBEAT_MS = 60_000;
153
+ /** A rotation lock older than this was left by a process that died mid-rotation. */
154
+ const LOCK_STALE_MS = 30_000;
155
+ /** Every soak file — active and rotated alike — carries this suffix. */
156
+ const GENERATION_SUFFIX = ".jsonl";
157
+ /** `process.memoryUsage().rss`, or 0 if the runtime refuses. Works under Node and Bun. */
158
+ export function currentRss() {
159
+ try {
160
+ return process.memoryUsage().rss;
161
+ }
162
+ catch {
163
+ return 0;
164
+ }
165
+ }
166
+ /**
167
+ * Milliseconds since this process started, from `process.uptime()`.
168
+ *
169
+ * The in-tree `time()` helper cannot supply this: it compiles itself out unless
170
+ * DRAHT_TIMING=1, so a soak run would carry no startup delta at all.
171
+ */
172
+ export function startupDeltaMs() {
173
+ try {
174
+ return Math.round(process.uptime() * 1000);
175
+ }
176
+ catch {
177
+ return 0;
178
+ }
179
+ }
180
+ /**
181
+ * Open descriptor gauge: open /dev/null, record the descriptor number POSIX hands
182
+ * back (always the lowest free one), close it. 0.04 ms, and it tracks fd growth
183
+ * exactly.
184
+ *
185
+ * Deliberately NOT `lsof` (176–200 ms, 4,000x more — and `lsof -p <pid> -U` ORs
186
+ * its selectors and returns every socket on the machine; the correct form is
187
+ * `lsof -a -p <pid> -U`). Deliberately NOT `process.getActiveResourcesInfo()`,
188
+ * which reports 20 under Node with 20 live listeners and 0 under Bun with the
189
+ * same 20 — and the shipped draht is a Bun-compiled binary.
190
+ */
191
+ export function fdGauge() {
192
+ let fd;
193
+ try {
194
+ fd = openSync("/dev/null", "r");
195
+ return fd;
196
+ }
197
+ catch {
198
+ return -1;
199
+ }
200
+ finally {
201
+ if (fd !== undefined) {
202
+ try {
203
+ closeSync(fd);
204
+ }
205
+ catch {
206
+ /* swallowed: the gauge must never disturb the caller */
207
+ }
208
+ }
209
+ }
210
+ }
211
+ /** Counts `.sock` and `.lock` entries with one readdir. Never `lsof`. */
212
+ export function socketDirCounts(socketsDir) {
213
+ let sockCount = 0;
214
+ let lockCount = 0;
215
+ try {
216
+ for (const entry of readdirSync(socketsDir)) {
217
+ if (entry.endsWith(".sock"))
218
+ sockCount++;
219
+ else if (entry.endsWith(".lock"))
220
+ lockCount++;
221
+ }
222
+ }
223
+ catch {
224
+ /* no sockets dir yet: both gauges are honestly zero */
225
+ }
226
+ return { sockCount, lockCount };
227
+ }
228
+ /** Default soak directory for this process. */
229
+ export function getSoakDir() {
230
+ return join(getAgentDir(), SOAK_DIR_NAME);
231
+ }
232
+ /**
233
+ * The rotating soak writer.
234
+ *
235
+ * Every public method swallows every failure — a soak log that can break a
236
+ * session is worse than no soak log — and NOTHING here writes to stdout or
237
+ * stderr under any condition.
238
+ */
239
+ export class SoakLog {
240
+ #maxFileBytes;
241
+ #maxTotalBytes;
242
+ #retentionFloorMs;
243
+ #heartbeatMs;
244
+ #socketsDir;
245
+ #now;
246
+ #onRotateWindow;
247
+ #sessionId;
248
+ #clientCount;
249
+ #dirReady = false;
250
+ #generationCounter = 0;
251
+ #timer;
252
+ constructor(options = {}) {
253
+ let dir;
254
+ let socketsDir;
255
+ try {
256
+ dir = options.dir ?? getSoakDir();
257
+ socketsDir = options.socketsDir ?? join(getAgentDir(), "sockets");
258
+ }
259
+ catch (error) {
260
+ // getAgentDir() reads the environment and can in principle throw; a
261
+ // constructor that throws would take the session with it.
262
+ this.lastError = error;
263
+ dir = options.dir ?? join(".", SOAK_DIR_NAME);
264
+ socketsDir = options.socketsDir ?? join(".", "sockets");
265
+ }
266
+ this.dir = dir;
267
+ this.stem = options.stem ?? SOAK_STEM_SESSION;
268
+ this.activePath = join(this.dir, `${this.stem}${GENERATION_SUFFIX}`);
269
+ this.lockPath = join(this.dir, `${this.stem}.rotate.lock`);
270
+ this.#maxFileBytes = options.maxFileBytes ?? DEFAULT_MAX_FILE_BYTES;
271
+ this.#maxTotalBytes = options.maxTotalBytes ?? DEFAULT_MAX_TOTAL_BYTES;
272
+ this.#retentionFloorMs = options.retentionFloorMs ?? DEFAULT_RETENTION_FLOOR_MS;
273
+ this.#heartbeatMs = options.heartbeatMs ?? DEFAULT_HEARTBEAT_MS;
274
+ this.#socketsDir = socketsDir;
275
+ this.#now = options.now ?? Date.now;
276
+ this.#sessionId = options.sessionId;
277
+ this.#clientCount = options.clientCount;
278
+ this.#onRotateWindow = options.onRotateWindow;
279
+ }
280
+ /** Stamp every subsequent record with this session id. */
281
+ setSessionId(sessionId) {
282
+ this.#sessionId = sessionId;
283
+ }
284
+ /** Supply a live client count for the heartbeat. */
285
+ setClientCountProvider(provider) {
286
+ this.#clientCount = provider;
287
+ }
288
+ /**
289
+ * Append one record. This is the whole write API: a new event or a new field
290
+ * needs no change to this file.
291
+ *
292
+ * `fields` may therefore carry ANY name, including one the contract reserves.
293
+ * A collision loses: the contract's value is stamped over it. The one
294
+ * exception is `sessionId` on a writer that has none of its own — the daemon
295
+ * half writes about sessions it does not belong to — where the caller's value
296
+ * stands.
297
+ */
298
+ record(event, fields = {}, level = "info") {
299
+ try {
300
+ this.#write(event, fields, level, true);
301
+ }
302
+ catch (error) {
303
+ this.lastError = error;
304
+ }
305
+ }
306
+ /**
307
+ * Write one heartbeat now.
308
+ *
309
+ * Edge events cannot answer "how many days did this run", "did the host
310
+ * sleep", or "did fds grow" — only a periodic record can, so the heartbeat is
311
+ * part of the record set, not a nicety.
312
+ */
313
+ heartbeat(fields = {}) {
314
+ try {
315
+ const counts = socketDirCounts(this.#socketsDir);
316
+ let clientCount;
317
+ try {
318
+ clientCount = this.#clientCount?.();
319
+ }
320
+ catch (error) {
321
+ this.lastError = error;
322
+ }
323
+ this.#write(SOAK_EVENTS.HEARTBEAT, {
324
+ // Same rule as #write: the measured gauges are stamped over a
325
+ // caller field of the same name, never under it. A heartbeat whose
326
+ // fdGauge came from its call site measures nothing.
327
+ ...fields,
328
+ fdGauge: fdGauge(),
329
+ sockCount: counts.sockCount,
330
+ lockCount: counts.lockCount,
331
+ ...(clientCount === undefined ? {} : { clientCount }),
332
+ }, "info", true);
333
+ }
334
+ catch (error) {
335
+ this.lastError = error;
336
+ }
337
+ }
338
+ /**
339
+ * Start the periodic heartbeat. The timer is `unref`'d, so it fires while the
340
+ * process is alive and does not by itself keep the process alive — the idiom
341
+ * the fleet route already uses. Idempotent.
342
+ */
343
+ startHeartbeat(intervalMs = this.#heartbeatMs) {
344
+ try {
345
+ if (this.#timer)
346
+ return;
347
+ const timer = setInterval(() => this.heartbeat(), intervalMs);
348
+ timer.unref?.();
349
+ this.#timer = timer;
350
+ }
351
+ catch (error) {
352
+ this.lastError = error;
353
+ }
354
+ }
355
+ /** Stop the periodic heartbeat. Idempotent. */
356
+ stopHeartbeat() {
357
+ try {
358
+ if (!this.#timer)
359
+ return;
360
+ clearInterval(this.#timer);
361
+ this.#timer = undefined;
362
+ }
363
+ catch (error) {
364
+ this.lastError = error;
365
+ }
366
+ }
367
+ // ── internals ────────────────────────────────────────────────────────────
368
+ #write(event, fields, level, mayRotate) {
369
+ this.#ensureDir();
370
+ const record = {
371
+ // CALLER FIELDS FIRST, and the contract's fields last, so a caller can
372
+ // never shadow one. `record()` promises that a new event or a new field
373
+ // needs no edit to this file, which makes every call site free to pick a
374
+ // field name — and `pid` is an entirely plausible one at a socket seam,
375
+ // where the `.lock` files already carry one. Spread the other way round,
376
+ // `record("client_attach", { pid: "not-a-pid" })` writes a line the
377
+ // reader then rejects as malformed and drops: the seam that reported the
378
+ // event disappears from the evidence instead of failing loudly.
379
+ ...fields,
380
+ level,
381
+ timestamp: new Date(this.#now()).toISOString(),
382
+ event,
383
+ v: SOAK_FORMAT_VERSION,
384
+ wall: this.#now(),
385
+ mono: Math.round(performance.now() * 1000) / 1000,
386
+ uptimeMs: startupDeltaMs(),
387
+ pid: process.pid,
388
+ rss: currentRss(),
389
+ ...(this.#sessionId === undefined ? {} : { sessionId: this.#sessionId }),
390
+ };
391
+ const line = `${JSON.stringify(record)}\n`;
392
+ const filled = this.#append(line);
393
+ if (mayRotate && filled && filled.size >= this.#maxFileBytes) {
394
+ this.#rotate(filled.ino);
395
+ }
396
+ }
397
+ /**
398
+ * One open/write/close. The fstat before the close is what makes rotation
399
+ * safe: it yields the size AND the inode of the file this record actually
400
+ * landed in, so the rotator can prove it is renaming the file it filled.
401
+ */
402
+ #append(line) {
403
+ let fd;
404
+ try {
405
+ fd = openSync(this.activePath, "a", 0o600);
406
+ const buf = Buffer.from(line, "utf8");
407
+ let offset = 0;
408
+ while (offset < buf.length) {
409
+ const written = writeSync(fd, buf, offset, buf.length - offset);
410
+ if (written <= 0)
411
+ break;
412
+ offset += written;
413
+ }
414
+ const st = fstatSync(fd);
415
+ return { size: st.size, ino: Number(st.ino) };
416
+ }
417
+ catch (error) {
418
+ this.lastError = error;
419
+ return undefined;
420
+ }
421
+ finally {
422
+ if (fd !== undefined) {
423
+ try {
424
+ closeSync(fd);
425
+ }
426
+ catch (error) {
427
+ this.lastError = error;
428
+ }
429
+ }
430
+ }
431
+ }
432
+ #ensureDir() {
433
+ if (this.#dirReady)
434
+ return;
435
+ mkdirSync(this.dir, { recursive: true, mode: 0o700 });
436
+ this.#dirReady = true;
437
+ }
438
+ /**
439
+ * Lock-guarded, inode-checked, unique-generation rotation. See the contract at
440
+ * the top of this file; the ORDER of the steps is the correctness argument and
441
+ * must not be rearranged.
442
+ */
443
+ #rotate(filledIno) {
444
+ let lockFd;
445
+ try {
446
+ lockFd = this.#claimRotationLock();
447
+ if (lockFd === undefined)
448
+ return; // another writer is rotating; next append retries
449
+ if (this.#onRotateWindow) {
450
+ try {
451
+ this.#onRotateWindow();
452
+ }
453
+ catch (error) {
454
+ this.lastError = error;
455
+ }
456
+ }
457
+ let current;
458
+ try {
459
+ const st = statSync(this.activePath);
460
+ current = { size: st.size, ino: Number(st.ino) };
461
+ }
462
+ catch {
463
+ return; // already renamed away by someone else
464
+ }
465
+ // THE INODE CHECK: rotate the file THIS record landed in, or rotate
466
+ // nothing. Another writer that rotated while we queued for the lock has
467
+ // already replaced the active path, and renaming its fresh file away is
468
+ // closing a generation nobody filled.
469
+ //
470
+ // Honest note on its weight: with unique generation names the size guard
471
+ // below covers the common case, so this line is defence in depth rather
472
+ // than the thing standing between the log and data loss. It is what keeps
473
+ // the scheme correct if the cap is ever raised at runtime or the size
474
+ // guard is ever relaxed, and `onRotateWindow` exists so it can be killed
475
+ // by a test instead of surviving as unfalsifiable code.
476
+ if (current.ino !== filledIno)
477
+ return;
478
+ if (current.size < this.#maxFileBytes)
479
+ return;
480
+ const generation = this.#nextGenerationPath();
481
+ renameSync(this.activePath, generation);
482
+ const pruned = this.#prune();
483
+ // Into the SURVIVING file, so a pruned gap is visible rather than invisible.
484
+ this.#write(SOAK_EVENTS.ROTATION, {
485
+ rotatedTo: generation.slice(this.dir.length + 1),
486
+ rotatedBytes: current.size,
487
+ maxFileBytes: this.#maxFileBytes,
488
+ maxTotalBytes: this.#maxTotalBytes,
489
+ retentionFloorMs: this.#retentionFloorMs,
490
+ pruned: pruned.names,
491
+ prunedBytes: pruned.bytes,
492
+ retainedByFloor: pruned.retainedByFloor,
493
+ }, "info", false);
494
+ }
495
+ catch (error) {
496
+ this.lastError = error;
497
+ }
498
+ finally {
499
+ if (lockFd !== undefined) {
500
+ try {
501
+ closeSync(lockFd);
502
+ }
503
+ catch (error) {
504
+ this.lastError = error;
505
+ }
506
+ try {
507
+ unlinkSync(this.lockPath);
508
+ }
509
+ catch (error) {
510
+ this.lastError = error;
511
+ }
512
+ }
513
+ }
514
+ }
515
+ /** `wx` exclusive create — the idiom the socket lock already uses. Undefined means "someone else holds it". */
516
+ #claimRotationLock() {
517
+ for (let attempt = 0; attempt < 2; attempt++) {
518
+ try {
519
+ const fd = openSync(this.lockPath, "wx", 0o600);
520
+ try {
521
+ writeSync(fd, `${process.pid}\n${new Date(this.#now()).toISOString()}\n`);
522
+ }
523
+ catch (error) {
524
+ this.lastError = error;
525
+ }
526
+ return fd;
527
+ }
528
+ catch (error) {
529
+ if (error?.code !== "EEXIST") {
530
+ this.lastError = error;
531
+ return undefined;
532
+ }
533
+ }
534
+ // A lock that has sat far longer than any rotation takes was left by a
535
+ // process that died mid-rotation. Remove it once, then retry.
536
+ try {
537
+ const st = statSync(this.lockPath);
538
+ if (this.#now() - st.mtimeMs < LOCK_STALE_MS)
539
+ return undefined;
540
+ unlinkSync(this.lockPath);
541
+ }
542
+ catch {
543
+ return undefined;
544
+ }
545
+ }
546
+ return undefined;
547
+ }
548
+ /** Unique forever: compact UTC stamp + pid + a per-process counter, and never an existing path. */
549
+ #nextGenerationPath() {
550
+ for (;;) {
551
+ const stamp = new Date(this.#now()).toISOString().replace(/[-:.]/g, "");
552
+ const name = `${this.stem}-${stamp}-${process.pid}-${this.#generationCounter++}${GENERATION_SUFFIX}`;
553
+ const candidate = join(this.dir, name);
554
+ try {
555
+ statSync(candidate);
556
+ }
557
+ catch {
558
+ return candidate; // does not exist
559
+ }
560
+ }
561
+ }
562
+ /**
563
+ * Byte cap AND retention floor, both of which must permit a delete. Returns
564
+ * what went, what it weighed, and how many generations the floor saved — all
565
+ * of which land in the rotation record.
566
+ */
567
+ #prune() {
568
+ const names = [];
569
+ let bytes = 0;
570
+ let retainedByFloor = 0;
571
+ try {
572
+ const generations = listGenerationFiles(this.dir, this.stem);
573
+ let total = 0;
574
+ for (const gen of generations)
575
+ total += gen.size;
576
+ try {
577
+ total += statSync(this.activePath).size;
578
+ }
579
+ catch {
580
+ /* no active file right now; it is about to be created */
581
+ }
582
+ const now = this.#now();
583
+ for (const gen of generations) {
584
+ if (total <= this.#maxTotalBytes)
585
+ break;
586
+ if (now - gen.mtimeMs < this.#retentionFloorMs) {
587
+ // The floor wins over the byte cap, always. Growing is the intended
588
+ // trade: a soak verdict that prunes its own first days is worthless.
589
+ retainedByFloor++;
590
+ continue;
591
+ }
592
+ try {
593
+ unlinkSync(gen.path);
594
+ names.push(gen.name);
595
+ bytes += gen.size;
596
+ total -= gen.size;
597
+ }
598
+ catch (error) {
599
+ this.lastError = error;
600
+ }
601
+ }
602
+ }
603
+ catch (error) {
604
+ this.lastError = error;
605
+ }
606
+ return { names, bytes, retainedByFloor };
607
+ }
608
+ }
609
+ /**
610
+ * Every rotated generation for `stem`, oldest first.
611
+ *
612
+ * Ordered by the timestamp embedded in the NAME, not by mtime: a straggler
613
+ * writer still holding a descriptor keeps appending to a generation after it was
614
+ * renamed, which moves its mtime but not its place in the sequence.
615
+ */
616
+ export function listGenerationFiles(dir, stem) {
617
+ const prefix = `${stem}-`;
618
+ const files = [];
619
+ let entries;
620
+ try {
621
+ entries = readdirSync(dir);
622
+ }
623
+ catch {
624
+ return files;
625
+ }
626
+ for (const name of entries) {
627
+ if (!name.startsWith(prefix) || !name.endsWith(GENERATION_SUFFIX))
628
+ continue;
629
+ const path = join(dir, name);
630
+ try {
631
+ const st = statSync(path);
632
+ if (!st.isFile())
633
+ continue;
634
+ files.push({ name, path, size: st.size, mtimeMs: st.mtimeMs });
635
+ }
636
+ catch {
637
+ /* vanished between readdir and stat; another writer pruned it */
638
+ }
639
+ }
640
+ files.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
641
+ return files;
642
+ }
643
+ let singleton;
644
+ /**
645
+ * Process-wide soak log for the session half.
646
+ *
647
+ * Constructed lazily so importing this module costs nothing and creates no
648
+ * directory; the first record makes the directory.
649
+ */
650
+ export function getSoakLog() {
651
+ if (!singleton)
652
+ singleton = new SoakLog();
653
+ return singleton;
654
+ }
655
+ /** Replace the process-wide log (tests, and the daemon half if it ever shares a process). */
656
+ export function setSoakLog(log) {
657
+ singleton?.stopHeartbeat();
658
+ singleton = log;
659
+ }
660
+ //# sourceMappingURL=soak-log.js.map