@vibe-agent-toolkit/cli 0.1.42 → 0.2.0-rc.10

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 (504) hide show
  1. package/README.md +4 -5
  2. package/dist/bin/vat +95 -28
  3. package/dist/bin/vat.js +95 -28
  4. package/dist/bin/vat.js.map +1 -1
  5. package/dist/bin.js +137 -76
  6. package/dist/bin.js.map +1 -1
  7. package/dist/command-loaders.d.ts +44 -0
  8. package/dist/command-loaders.d.ts.map +1 -0
  9. package/dist/command-loaders.js +60 -0
  10. package/dist/command-loaders.js.map +1 -0
  11. package/dist/commands/agent/build.d.ts.map +1 -1
  12. package/dist/commands/agent/build.js +2 -1
  13. package/dist/commands/agent/build.js.map +1 -1
  14. package/dist/commands/agent/import.d.ts.map +1 -1
  15. package/dist/commands/agent/import.js +3 -2
  16. package/dist/commands/agent/import.js.map +1 -1
  17. package/dist/commands/agent/index.js +1 -1
  18. package/dist/commands/agent/install-path.d.ts +36 -0
  19. package/dist/commands/agent/install-path.d.ts.map +1 -0
  20. package/dist/commands/agent/install-path.js +44 -0
  21. package/dist/commands/agent/install-path.js.map +1 -0
  22. package/dist/commands/agent/install.d.ts.map +1 -1
  23. package/dist/commands/agent/install.js +66 -13
  24. package/dist/commands/agent/install.js.map +1 -1
  25. package/dist/commands/agent/installed.d.ts.map +1 -1
  26. package/dist/commands/agent/installed.js +22 -12
  27. package/dist/commands/agent/installed.js.map +1 -1
  28. package/dist/commands/agent/list.d.ts.map +1 -1
  29. package/dist/commands/agent/list.js +2 -1
  30. package/dist/commands/agent/list.js.map +1 -1
  31. package/dist/commands/agent/run.d.ts.map +1 -1
  32. package/dist/commands/agent/run.js +2 -1
  33. package/dist/commands/agent/run.js.map +1 -1
  34. package/dist/commands/agent/uninstall.d.ts.map +1 -1
  35. package/dist/commands/agent/uninstall.js +13 -6
  36. package/dist/commands/agent/uninstall.js.map +1 -1
  37. package/dist/commands/agent/validate.d.ts.map +1 -1
  38. package/dist/commands/agent/validate.js +3 -2
  39. package/dist/commands/agent/validate.js.map +1 -1
  40. package/dist/commands/ard/emit.d.ts +153 -0
  41. package/dist/commands/ard/emit.d.ts.map +1 -0
  42. package/dist/commands/ard/emit.js +276 -0
  43. package/dist/commands/ard/emit.js.map +1 -0
  44. package/dist/commands/ard/index.d.ts +12 -0
  45. package/dist/commands/ard/index.d.ts.map +1 -0
  46. package/dist/commands/ard/index.js +80 -0
  47. package/dist/commands/ard/index.js.map +1 -0
  48. package/dist/commands/ard/surfaces.d.ts +56 -0
  49. package/dist/commands/ard/surfaces.d.ts.map +1 -0
  50. package/dist/commands/ard/surfaces.js +150 -0
  51. package/dist/commands/ard/surfaces.js.map +1 -0
  52. package/dist/commands/audit/distributed-tree.d.ts +60 -2
  53. package/dist/commands/audit/distributed-tree.d.ts.map +1 -1
  54. package/dist/commands/audit/distributed-tree.js +73 -1
  55. package/dist/commands/audit/distributed-tree.js.map +1 -1
  56. package/dist/commands/audit/git-url-clone.d.ts +1 -1
  57. package/dist/commands/audit/git-url-clone.d.ts.map +1 -1
  58. package/dist/commands/audit/git-url-clone.js.map +1 -1
  59. package/dist/commands/audit/hierarchical-output.d.ts +1 -1
  60. package/dist/commands/audit/hierarchical-output.d.ts.map +1 -1
  61. package/dist/commands/audit/hierarchical-output.js +1 -1
  62. package/dist/commands/audit/hierarchical-output.js.map +1 -1
  63. package/dist/commands/audit/provenance.d.ts.map +1 -1
  64. package/dist/commands/audit/provenance.js +4 -3
  65. package/dist/commands/audit/provenance.js.map +1 -1
  66. package/dist/commands/audit/scan-population.d.ts +158 -0
  67. package/dist/commands/audit/scan-population.d.ts.map +1 -0
  68. package/dist/commands/audit/scan-population.js +292 -0
  69. package/dist/commands/audit/scan-population.js.map +1 -0
  70. package/dist/commands/audit-settings.d.ts.map +1 -1
  71. package/dist/commands/audit-settings.js +6 -5
  72. package/dist/commands/audit-settings.js.map +1 -1
  73. package/dist/commands/audit.d.ts +98 -8
  74. package/dist/commands/audit.d.ts.map +1 -1
  75. package/dist/commands/audit.js +1133 -395
  76. package/dist/commands/audit.js.map +1 -1
  77. package/dist/commands/build.d.ts +1 -1
  78. package/dist/commands/build.d.ts.map +1 -1
  79. package/dist/commands/build.js +40 -36
  80. package/dist/commands/build.js.map +1 -1
  81. package/dist/commands/cache/cache-control.d.ts +82 -0
  82. package/dist/commands/cache/cache-control.d.ts.map +1 -0
  83. package/dist/commands/cache/cache-control.js +86 -0
  84. package/dist/commands/cache/cache-control.js.map +1 -0
  85. package/dist/commands/cache/clear.d.ts +105 -0
  86. package/dist/commands/cache/clear.d.ts.map +1 -0
  87. package/dist/commands/cache/clear.js +248 -0
  88. package/dist/commands/cache/clear.js.map +1 -0
  89. package/dist/commands/cache/index.d.ts +18 -0
  90. package/dist/commands/cache/index.d.ts.map +1 -0
  91. package/dist/commands/cache/index.js +94 -0
  92. package/dist/commands/cache/index.js.map +1 -0
  93. package/dist/commands/claude/claude-config.d.ts.map +1 -1
  94. package/dist/commands/claude/claude-config.js +6 -0
  95. package/dist/commands/claude/claude-config.js.map +1 -1
  96. package/dist/commands/claude/context.d.ts +340 -0
  97. package/dist/commands/claude/context.d.ts.map +1 -0
  98. package/dist/commands/claude/context.js +1080 -0
  99. package/dist/commands/claude/context.js.map +1 -0
  100. package/dist/commands/claude/index.d.ts +14 -0
  101. package/dist/commands/claude/index.d.ts.map +1 -1
  102. package/dist/commands/claude/index.js +22 -2
  103. package/dist/commands/claude/index.js.map +1 -1
  104. package/dist/commands/claude/marketplace/changelog-utils.d.ts +1 -1
  105. package/dist/commands/claude/marketplace/changelog-utils.d.ts.map +1 -1
  106. package/dist/commands/claude/marketplace/changelog-utils.js +1 -2
  107. package/dist/commands/claude/marketplace/changelog-utils.js.map +1 -1
  108. package/dist/commands/claude/marketplace/git-publish.d.ts.map +1 -1
  109. package/dist/commands/claude/marketplace/git-publish.js +40 -31
  110. package/dist/commands/claude/marketplace/git-publish.js.map +1 -1
  111. package/dist/commands/claude/marketplace/license-utils.d.ts.map +1 -1
  112. package/dist/commands/claude/marketplace/license-utils.js +0 -1
  113. package/dist/commands/claude/marketplace/license-utils.js.map +1 -1
  114. package/dist/commands/claude/marketplace/publish-tree.d.ts.map +1 -1
  115. package/dist/commands/claude/marketplace/publish-tree.js +0 -6
  116. package/dist/commands/claude/marketplace/publish-tree.js.map +1 -1
  117. package/dist/commands/claude/marketplace/publish.d.ts.map +1 -1
  118. package/dist/commands/claude/marketplace/publish.js +2 -1
  119. package/dist/commands/claude/marketplace/publish.js.map +1 -1
  120. package/dist/commands/claude/marketplace/validate.d.ts +73 -22
  121. package/dist/commands/claude/marketplace/validate.d.ts.map +1 -1
  122. package/dist/commands/claude/marketplace/validate.js +407 -72
  123. package/dist/commands/claude/marketplace/validate.js.map +1 -1
  124. package/dist/commands/claude/org/api-keys.d.ts +0 -3
  125. package/dist/commands/claude/org/api-keys.d.ts.map +1 -1
  126. package/dist/commands/claude/org/api-keys.js +2 -1
  127. package/dist/commands/claude/org/api-keys.js.map +1 -1
  128. package/dist/commands/claude/org/helpers.d.ts +54 -1
  129. package/dist/commands/claude/org/helpers.d.ts.map +1 -1
  130. package/dist/commands/claude/org/helpers.js +42 -7
  131. package/dist/commands/claude/org/helpers.js.map +1 -1
  132. package/dist/commands/claude/org/index.d.ts.map +1 -1
  133. package/dist/commands/claude/org/index.js +24 -16
  134. package/dist/commands/claude/org/index.js.map +1 -1
  135. package/dist/commands/claude/org/invites.d.ts +0 -3
  136. package/dist/commands/claude/org/invites.d.ts.map +1 -1
  137. package/dist/commands/claude/org/invites.js +3 -2
  138. package/dist/commands/claude/org/invites.js.map +1 -1
  139. package/dist/commands/claude/org/skills.d.ts +527 -0
  140. package/dist/commands/claude/org/skills.d.ts.map +1 -1
  141. package/dist/commands/claude/org/skills.js +1414 -108
  142. package/dist/commands/claude/org/skills.js.map +1 -1
  143. package/dist/commands/claude/org/users.d.ts +0 -3
  144. package/dist/commands/claude/org/users.d.ts.map +1 -1
  145. package/dist/commands/claude/org/users.js +6 -3
  146. package/dist/commands/claude/org/users.js.map +1 -1
  147. package/dist/commands/claude/org/workspaces.d.ts +0 -3
  148. package/dist/commands/claude/org/workspaces.d.ts.map +1 -1
  149. package/dist/commands/claude/org/workspaces.js +11 -7
  150. package/dist/commands/claude/org/workspaces.js.map +1 -1
  151. package/dist/commands/claude/plugin/build.d.ts +41 -3
  152. package/dist/commands/claude/plugin/build.d.ts.map +1 -1
  153. package/dist/commands/claude/plugin/build.js +147 -80
  154. package/dist/commands/claude/plugin/build.js.map +1 -1
  155. package/dist/commands/claude/plugin/helpers.d.ts.map +1 -1
  156. package/dist/commands/claude/plugin/helpers.js +2 -7
  157. package/dist/commands/claude/plugin/helpers.js.map +1 -1
  158. package/dist/commands/claude/plugin/install.d.ts +12 -0
  159. package/dist/commands/claude/plugin/install.d.ts.map +1 -1
  160. package/dist/commands/claude/plugin/install.js +93 -62
  161. package/dist/commands/claude/plugin/install.js.map +1 -1
  162. package/dist/commands/claude/plugin/list.d.ts.map +1 -1
  163. package/dist/commands/claude/plugin/list.js +3 -2
  164. package/dist/commands/claude/plugin/list.js.map +1 -1
  165. package/dist/commands/claude/plugin/marketplace-json.d.ts +24 -9
  166. package/dist/commands/claude/plugin/marketplace-json.d.ts.map +1 -1
  167. package/dist/commands/claude/plugin/marketplace-json.js +10 -9
  168. package/dist/commands/claude/plugin/marketplace-json.js.map +1 -1
  169. package/dist/commands/claude/plugin/plugin-changelog.d.ts.map +1 -1
  170. package/dist/commands/claude/plugin/plugin-changelog.js +0 -2
  171. package/dist/commands/claude/plugin/plugin-changelog.js.map +1 -1
  172. package/dist/commands/claude/plugin/plugin-files.d.ts.map +1 -1
  173. package/dist/commands/claude/plugin/plugin-files.js +3 -6
  174. package/dist/commands/claude/plugin/plugin-files.js.map +1 -1
  175. package/dist/commands/claude/plugin/plugin-validators.d.ts.map +1 -1
  176. package/dist/commands/claude/plugin/plugin-validators.js +3 -6
  177. package/dist/commands/claude/plugin/plugin-validators.js.map +1 -1
  178. package/dist/commands/claude/plugin/tree-copy.d.ts +73 -0
  179. package/dist/commands/claude/plugin/tree-copy.d.ts.map +1 -1
  180. package/dist/commands/claude/plugin/tree-copy.js +221 -14
  181. package/dist/commands/claude/plugin/tree-copy.js.map +1 -1
  182. package/dist/commands/claude/plugin/uninstall.d.ts.map +1 -1
  183. package/dist/commands/claude/plugin/uninstall.js +4 -4
  184. package/dist/commands/claude/plugin/uninstall.js.map +1 -1
  185. package/dist/commands/consistency-check.d.ts +17 -15
  186. package/dist/commands/consistency-check.d.ts.map +1 -1
  187. package/dist/commands/consistency-check.js +152 -106
  188. package/dist/commands/consistency-check.js.map +1 -1
  189. package/dist/commands/corpus/index.d.ts.map +1 -1
  190. package/dist/commands/corpus/index.js +3 -0
  191. package/dist/commands/corpus/index.js.map +1 -1
  192. package/dist/commands/corpus/report.d.ts +1 -2
  193. package/dist/commands/corpus/report.d.ts.map +1 -1
  194. package/dist/commands/corpus/report.js +1 -3
  195. package/dist/commands/corpus/report.js.map +1 -1
  196. package/dist/commands/corpus/runner.d.ts +58 -1
  197. package/dist/commands/corpus/runner.d.ts.map +1 -1
  198. package/dist/commands/corpus/runner.js +95 -41
  199. package/dist/commands/corpus/runner.js.map +1 -1
  200. package/dist/commands/corpus/scan.d.ts.map +1 -1
  201. package/dist/commands/corpus/scan.js +20 -12
  202. package/dist/commands/corpus/scan.js.map +1 -1
  203. package/dist/commands/corpus/seed.d.ts +4 -4
  204. package/dist/commands/corpus/seed.d.ts.map +1 -1
  205. package/dist/commands/corpus/seed.js +1 -3
  206. package/dist/commands/corpus/seed.js.map +1 -1
  207. package/dist/commands/doctor.d.ts +50 -0
  208. package/dist/commands/doctor.d.ts.map +1 -1
  209. package/dist/commands/doctor.js +245 -52
  210. package/dist/commands/doctor.js.map +1 -1
  211. package/dist/commands/inventory.d.ts +13 -1
  212. package/dist/commands/inventory.d.ts.map +1 -1
  213. package/dist/commands/inventory.js +128 -17
  214. package/dist/commands/inventory.js.map +1 -1
  215. package/dist/commands/mcp/collections.d.ts +1 -1
  216. package/dist/commands/mcp/collections.d.ts.map +1 -1
  217. package/dist/commands/mcp/list-collections.d.ts.map +1 -1
  218. package/dist/commands/mcp/list-collections.js +2 -1
  219. package/dist/commands/mcp/list-collections.js.map +1 -1
  220. package/dist/commands/mcp/serve.d.ts.map +1 -1
  221. package/dist/commands/mcp/serve.js +3 -2
  222. package/dist/commands/mcp/serve.js.map +1 -1
  223. package/dist/commands/okf/index.d.ts +11 -0
  224. package/dist/commands/okf/index.d.ts.map +1 -0
  225. package/dist/commands/okf/index.js +114 -0
  226. package/dist/commands/okf/index.js.map +1 -0
  227. package/dist/commands/okf/validate.d.ts +191 -0
  228. package/dist/commands/okf/validate.d.ts.map +1 -0
  229. package/dist/commands/okf/validate.js +190 -0
  230. package/dist/commands/okf/validate.js.map +1 -0
  231. package/dist/commands/phase-utils.d.ts +182 -114
  232. package/dist/commands/phase-utils.d.ts.map +1 -1
  233. package/dist/commands/phase-utils.js +154 -163
  234. package/dist/commands/phase-utils.js.map +1 -1
  235. package/dist/commands/positional-args.d.ts.map +1 -1
  236. package/dist/commands/positional-args.js +3 -2
  237. package/dist/commands/positional-args.js.map +1 -1
  238. package/dist/commands/rag/clear-command.d.ts.map +1 -1
  239. package/dist/commands/rag/clear-command.js +2 -1
  240. package/dist/commands/rag/clear-command.js.map +1 -1
  241. package/dist/commands/rag/index-command.d.ts +64 -0
  242. package/dist/commands/rag/index-command.d.ts.map +1 -1
  243. package/dist/commands/rag/index-command.js +72 -6
  244. package/dist/commands/rag/index-command.js.map +1 -1
  245. package/dist/commands/rag/index.d.ts.map +1 -1
  246. package/dist/commands/rag/index.js +23 -10
  247. package/dist/commands/rag/index.js.map +1 -1
  248. package/dist/commands/rag/query-command.d.ts.map +1 -1
  249. package/dist/commands/rag/query-command.js +2 -1
  250. package/dist/commands/rag/query-command.js.map +1 -1
  251. package/dist/commands/rag/stats-command.d.ts.map +1 -1
  252. package/dist/commands/rag/stats-command.js +2 -1
  253. package/dist/commands/rag/stats-command.js.map +1 -1
  254. package/dist/commands/resources/builtin-help.d.ts +27 -0
  255. package/dist/commands/resources/builtin-help.d.ts.map +1 -0
  256. package/dist/commands/resources/builtin-help.js +46 -0
  257. package/dist/commands/resources/builtin-help.js.map +1 -0
  258. package/dist/commands/resources/check-progress.d.ts +154 -0
  259. package/dist/commands/resources/check-progress.d.ts.map +1 -0
  260. package/dist/commands/resources/check-progress.js +222 -0
  261. package/dist/commands/resources/check-progress.js.map +1 -0
  262. package/dist/commands/resources/check-supervisor.d.ts +465 -0
  263. package/dist/commands/resources/check-supervisor.d.ts.map +1 -0
  264. package/dist/commands/resources/check-supervisor.js +573 -0
  265. package/dist/commands/resources/check-supervisor.js.map +1 -0
  266. package/dist/commands/resources/check.d.ts +593 -0
  267. package/dist/commands/resources/check.d.ts.map +1 -0
  268. package/dist/commands/resources/check.js +1365 -0
  269. package/dist/commands/resources/check.js.map +1 -0
  270. package/dist/commands/resources/index.d.ts.map +1 -1
  271. package/dist/commands/resources/index.js +425 -6
  272. package/dist/commands/resources/index.js.map +1 -1
  273. package/dist/commands/resources/query.d.ts +106 -0
  274. package/dist/commands/resources/query.d.ts.map +1 -0
  275. package/dist/commands/resources/query.js +177 -0
  276. package/dist/commands/resources/query.js.map +1 -0
  277. package/dist/commands/resources/scan.d.ts +24 -0
  278. package/dist/commands/resources/scan.d.ts.map +1 -1
  279. package/dist/commands/resources/scan.js +17 -8
  280. package/dist/commands/resources/scan.js.map +1 -1
  281. package/dist/commands/resources/validate.d.ts +57 -4
  282. package/dist/commands/resources/validate.d.ts.map +1 -1
  283. package/dist/commands/resources/validate.js +224 -56
  284. package/dist/commands/resources/validate.js.map +1 -1
  285. package/dist/commands/skill/review-checklist.d.ts +3 -2
  286. package/dist/commands/skill/review-checklist.d.ts.map +1 -1
  287. package/dist/commands/skill/review-checklist.js +40 -2
  288. package/dist/commands/skill/review-checklist.js.map +1 -1
  289. package/dist/commands/skill/review.d.ts +247 -0
  290. package/dist/commands/skill/review.d.ts.map +1 -1
  291. package/dist/commands/skill/review.js +99 -62
  292. package/dist/commands/skill/review.js.map +1 -1
  293. package/dist/commands/skill/test/configure.d.ts +56 -0
  294. package/dist/commands/skill/test/configure.d.ts.map +1 -1
  295. package/dist/commands/skill/test/configure.js +75 -16
  296. package/dist/commands/skill/test/configure.js.map +1 -1
  297. package/dist/commands/skill/test/run.d.ts +63 -10
  298. package/dist/commands/skill/test/run.d.ts.map +1 -1
  299. package/dist/commands/skill/test/run.js +258 -77
  300. package/dist/commands/skill/test/run.js.map +1 -1
  301. package/dist/commands/skills/build.d.ts +94 -4
  302. package/dist/commands/skills/build.d.ts.map +1 -1
  303. package/dist/commands/skills/build.js +325 -97
  304. package/dist/commands/skills/build.js.map +1 -1
  305. package/dist/commands/skills/install.d.ts +2 -1
  306. package/dist/commands/skills/install.d.ts.map +1 -1
  307. package/dist/commands/skills/install.js +20 -31
  308. package/dist/commands/skills/install.js.map +1 -1
  309. package/dist/commands/skills/list.d.ts +2 -1
  310. package/dist/commands/skills/list.d.ts.map +1 -1
  311. package/dist/commands/skills/list.js +44 -26
  312. package/dist/commands/skills/list.js.map +1 -1
  313. package/dist/commands/skills/package.d.ts +24 -3
  314. package/dist/commands/skills/package.d.ts.map +1 -1
  315. package/dist/commands/skills/package.js +42 -17
  316. package/dist/commands/skills/package.js.map +1 -1
  317. package/dist/commands/skills/scope-guard.d.ts.map +1 -1
  318. package/dist/commands/skills/scope-guard.js +3 -5
  319. package/dist/commands/skills/scope-guard.js.map +1 -1
  320. package/dist/commands/skills/shared.d.ts.map +1 -1
  321. package/dist/commands/skills/shared.js +2 -4
  322. package/dist/commands/skills/shared.js.map +1 -1
  323. package/dist/commands/skills/skill-discovery.d.ts +47 -6
  324. package/dist/commands/skills/skill-discovery.d.ts.map +1 -1
  325. package/dist/commands/skills/skill-discovery.js +66 -16
  326. package/dist/commands/skills/skill-discovery.js.map +1 -1
  327. package/dist/commands/skills/source-resolvers.d.ts +15 -0
  328. package/dist/commands/skills/source-resolvers.d.ts.map +1 -1
  329. package/dist/commands/skills/source-resolvers.js +25 -4
  330. package/dist/commands/skills/source-resolvers.js.map +1 -1
  331. package/dist/commands/skills/validate-command.d.ts.map +1 -1
  332. package/dist/commands/skills/validate-command.js +11 -3
  333. package/dist/commands/skills/validate-command.js.map +1 -1
  334. package/dist/commands/skills/validate.d.ts +140 -4
  335. package/dist/commands/skills/validate.d.ts.map +1 -1
  336. package/dist/commands/skills/validate.js +224 -67
  337. package/dist/commands/skills/validate.js.map +1 -1
  338. package/dist/commands/validate.d.ts +1 -1
  339. package/dist/commands/validate.d.ts.map +1 -1
  340. package/dist/commands/validate.js +63 -27
  341. package/dist/commands/validate.js.map +1 -1
  342. package/dist/commands/verify.d.ts +119 -15
  343. package/dist/commands/verify.d.ts.map +1 -1
  344. package/dist/commands/verify.js +357 -142
  345. package/dist/commands/verify.js.map +1 -1
  346. package/dist/index.d.ts +0 -1
  347. package/dist/index.d.ts.map +1 -1
  348. package/dist/index.js +5 -1
  349. package/dist/index.js.map +1 -1
  350. package/dist/report-schemas.d.ts +45 -0
  351. package/dist/report-schemas.d.ts.map +1 -0
  352. package/dist/report-schemas.js +100 -0
  353. package/dist/report-schemas.js.map +1 -0
  354. package/dist/skill-resolution/classify.js +2 -2
  355. package/dist/skill-resolution/classify.js.map +1 -1
  356. package/dist/skill-resolution/packaging-config.d.ts +49 -5
  357. package/dist/skill-resolution/packaging-config.d.ts.map +1 -1
  358. package/dist/skill-resolution/packaging-config.js +59 -19
  359. package/dist/skill-resolution/packaging-config.js.map +1 -1
  360. package/dist/skill-resolution/resolve-skill-reference.d.ts.map +1 -1
  361. package/dist/skill-resolution/resolve-skill-reference.js +55 -57
  362. package/dist/skill-resolution/resolve-skill-reference.js.map +1 -1
  363. package/dist/utils/agent-discovery.d.ts.map +1 -1
  364. package/dist/utils/agent-discovery.js +22 -11
  365. package/dist/utils/agent-discovery.js.map +1 -1
  366. package/dist/utils/agent-runner.d.ts.map +1 -1
  367. package/dist/utils/agent-runner.js +7 -4
  368. package/dist/utils/agent-runner.js.map +1 -1
  369. package/dist/utils/claude-context-lens.d.ts +34 -0
  370. package/dist/utils/claude-context-lens.d.ts.map +1 -0
  371. package/dist/utils/claude-context-lens.js +39 -0
  372. package/dist/utils/claude-context-lens.js.map +1 -0
  373. package/dist/utils/command-error.d.ts +144 -7
  374. package/dist/utils/command-error.d.ts.map +1 -1
  375. package/dist/utils/command-error.js +179 -16
  376. package/dist/utils/command-error.js.map +1 -1
  377. package/dist/utils/config-loader.d.ts +2 -1
  378. package/dist/utils/config-loader.d.ts.map +1 -1
  379. package/dist/utils/config-loader.js +40 -14
  380. package/dist/utils/config-loader.js.map +1 -1
  381. package/dist/utils/corpus-target.d.ts +26 -0
  382. package/dist/utils/corpus-target.d.ts.map +1 -0
  383. package/dist/utils/corpus-target.js +35 -0
  384. package/dist/utils/corpus-target.js.map +1 -0
  385. package/dist/utils/edge-lens-evaluation.d.ts +83 -0
  386. package/dist/utils/edge-lens-evaluation.d.ts.map +1 -0
  387. package/dist/utils/edge-lens-evaluation.js +110 -0
  388. package/dist/utils/edge-lens-evaluation.js.map +1 -0
  389. package/dist/utils/help-loader.d.ts.map +1 -1
  390. package/dist/utils/help-loader.js +0 -1
  391. package/dist/utils/help-loader.js.map +1 -1
  392. package/dist/utils/issue-anchor.d.ts +2 -2
  393. package/dist/utils/issue-anchor.d.ts.map +1 -1
  394. package/dist/utils/issue-anchor.js +1 -1
  395. package/dist/utils/issue-rendering.d.ts +3 -3
  396. package/dist/utils/issue-rendering.d.ts.map +1 -1
  397. package/dist/utils/issue-rendering.js +3 -3
  398. package/dist/utils/issue-rendering.js.map +1 -1
  399. package/dist/utils/issue-severity.d.ts +12 -5
  400. package/dist/utils/issue-severity.d.ts.map +1 -1
  401. package/dist/utils/issue-severity.js +1 -1
  402. package/dist/utils/issue-severity.js.map +1 -1
  403. package/dist/utils/optional-backend.d.ts +78 -0
  404. package/dist/utils/optional-backend.d.ts.map +1 -0
  405. package/dist/utils/optional-backend.js +117 -0
  406. package/dist/utils/optional-backend.js.map +1 -0
  407. package/dist/utils/output.d.ts +26 -0
  408. package/dist/utils/output.d.ts.map +1 -1
  409. package/dist/utils/output.js +35 -0
  410. package/dist/utils/output.js.map +1 -1
  411. package/dist/utils/package-json.d.ts +24 -0
  412. package/dist/utils/package-json.d.ts.map +1 -0
  413. package/dist/utils/package-json.js +49 -0
  414. package/dist/utils/package-json.js.map +1 -0
  415. package/dist/utils/population-wiring.d.ts +100 -0
  416. package/dist/utils/population-wiring.d.ts.map +1 -0
  417. package/dist/utils/population-wiring.js +98 -0
  418. package/dist/utils/population-wiring.js.map +1 -0
  419. package/dist/utils/project-root-policy.d.ts +20 -0
  420. package/dist/utils/project-root-policy.d.ts.map +1 -1
  421. package/dist/utils/project-root-policy.js +30 -0
  422. package/dist/utils/project-root-policy.js.map +1 -1
  423. package/dist/utils/projection-lenses.d.ts +98 -0
  424. package/dist/utils/projection-lenses.d.ts.map +1 -0
  425. package/dist/utils/projection-lenses.js +203 -0
  426. package/dist/utils/projection-lenses.js.map +1 -0
  427. package/dist/utils/projection-query.d.ts +324 -0
  428. package/dist/utils/projection-query.d.ts.map +1 -0
  429. package/dist/utils/projection-query.js +357 -0
  430. package/dist/utils/projection-query.js.map +1 -0
  431. package/dist/utils/projection-store.d.ts +335 -0
  432. package/dist/utils/projection-store.d.ts.map +1 -0
  433. package/dist/utils/projection-store.js +522 -0
  434. package/dist/utils/projection-store.js.map +1 -0
  435. package/dist/utils/relation-limits.d.ts +50 -0
  436. package/dist/utils/relation-limits.d.ts.map +1 -0
  437. package/dist/utils/relation-limits.js +50 -0
  438. package/dist/utils/relation-limits.js.map +1 -0
  439. package/dist/utils/repeatable-option.d.ts +37 -0
  440. package/dist/utils/repeatable-option.d.ts.map +1 -0
  441. package/dist/utils/repeatable-option.js +39 -0
  442. package/dist/utils/repeatable-option.js.map +1 -0
  443. package/dist/utils/resource-loader.d.ts +132 -2
  444. package/dist/utils/resource-loader.d.ts.map +1 -1
  445. package/dist/utils/resource-loader.js +288 -27
  446. package/dist/utils/resource-loader.js.map +1 -1
  447. package/dist/utils/root-argv.d.ts +53 -0
  448. package/dist/utils/root-argv.d.ts.map +1 -0
  449. package/dist/utils/root-argv.js +215 -0
  450. package/dist/utils/root-argv.js.map +1 -0
  451. package/dist/utils/run-integrity.d.ts +95 -0
  452. package/dist/utils/run-integrity.d.ts.map +1 -0
  453. package/dist/utils/run-integrity.js +102 -0
  454. package/dist/utils/run-integrity.js.map +1 -0
  455. package/dist/utils/skill-discovery.d.ts.map +1 -1
  456. package/dist/utils/skill-discovery.js +2 -1
  457. package/dist/utils/skill-discovery.js.map +1 -1
  458. package/dist/utils/skill-packaging-config.d.ts +63 -1
  459. package/dist/utils/skill-packaging-config.d.ts.map +1 -1
  460. package/dist/utils/skill-packaging-config.js +56 -1
  461. package/dist/utils/skill-packaging-config.js.map +1 -1
  462. package/dist/utils/sqlite-experimental-warning.d.ts +69 -0
  463. package/dist/utils/sqlite-experimental-warning.d.ts.map +1 -0
  464. package/dist/utils/sqlite-experimental-warning.js +144 -0
  465. package/dist/utils/sqlite-experimental-warning.js.map +1 -0
  466. package/dist/utils/url-redact.d.ts.map +1 -1
  467. package/dist/utils/url-redact.js +4 -6
  468. package/dist/utils/url-redact.js.map +1 -1
  469. package/dist/utils/user-context-scanner.d.ts +8 -0
  470. package/dist/utils/user-context-scanner.d.ts.map +1 -1
  471. package/dist/utils/user-context-scanner.js +4 -2
  472. package/dist/utils/user-context-scanner.js.map +1 -1
  473. package/dist/utils/validate-help-files.d.ts.map +1 -1
  474. package/dist/utils/validate-help-files.js +12 -6
  475. package/dist/utils/validate-help-files.js.map +1 -1
  476. package/dist/utils/vat-bin-path.d.ts +36 -0
  477. package/dist/utils/vat-bin-path.d.ts.map +1 -0
  478. package/dist/utils/vat-bin-path.js +48 -0
  479. package/dist/utils/vat-bin-path.js.map +1 -0
  480. package/dist/utils/verdict-helpers.d.ts +1 -1
  481. package/dist/utils/verdict-helpers.d.ts.map +1 -1
  482. package/dist/utils/verdict-helpers.js +1 -1
  483. package/dist/utils/verdict-helpers.js.map +1 -1
  484. package/dist/version.d.ts.map +1 -1
  485. package/dist/version.js +1 -3
  486. package/dist/version.js.map +1 -1
  487. package/docs/agent.md +2 -2
  488. package/docs/audit.md +141 -37
  489. package/docs/doctor.md +7 -6
  490. package/docs/index.md +40 -12
  491. package/docs/mcp.md +2 -2
  492. package/docs/rag.md +3 -2
  493. package/docs/resources.md +13 -3
  494. package/docs/skill-test.md +10 -9
  495. package/docs/skills.md +53 -69
  496. package/package.json +38 -27
  497. package/schemas/ard-emit.json +149 -0
  498. package/schemas/okf-validate.json +170 -0
  499. package/schemas/resources-check.json +229 -0
  500. package/schemas/skill-review.json +230 -0
  501. package/dist/commands/resources/command-helpers.d.ts +0 -5
  502. package/dist/commands/resources/command-helpers.d.ts.map +0 -1
  503. package/dist/commands/resources/command-helpers.js +0 -6
  504. package/dist/commands/resources/command-helpers.js.map +0 -1
@@ -0,0 +1,465 @@
1
+ /**
2
+ * The time bound on `vat resources check`, enforced from OUTSIDE the process
3
+ * doing the work.
4
+ *
5
+ * ## ðŸšĻ Why an external process, and not any of the cheaper things
6
+ *
7
+ * This verb runs adopter-authored SQL as an unattended CI gate. An accidental
8
+ * cross join, or a `WITH RECURSIVE` with no termination, runs forever — and
9
+ * every in-process lever was tried and MEASURED on Node 24.13.1 before this
10
+ * shape was chosen. Do not re-derive them:
11
+ *
12
+ * - **A worker thread does not work.** `worker.terminate()` never resolves
13
+ * against a thread blocked in native SQLite, and the parent's own
14
+ * `process.exit()` does not exit either. V8 can unwind a worker spinning in
15
+ * JS — which is why the parse pool's `terminate()` genuinely works — but a
16
+ * thread inside a synchronous native call is not spinning in JS. Do NOT
17
+ * "align" this design with the parse pool's.
18
+ * - **A signal handler is a REGRESSION.** A process blocked in synchronous
19
+ * `node:sqlite` dies INSTANTLY on SIGINT while no handler is installed, and
20
+ * SURVIVES both SIGINT and SIGTERM once one is — the handler is a JS callback,
21
+ * and the event loop that would schedule it is the resource that is blocked.
22
+ * Installing one removes the operator's Ctrl-C. There is no
23
+ * `process.on('SIGINT')` here and there must never be.
24
+ * - **The kill is `SIGKILL` because SIGKILL cannot be REGRESSED.** No code the
25
+ * child runs, now or after any future edit, can handle, ignore or block it.
26
+ *
27
+ * ⚠ïļ This header used to claim, as measured fact, that "SIGTERM does not kill
28
+ * the child either, for the same reason". **That is false and was measured to
29
+ * be false**: `kill -TERM` on a child blocked inside synchronous `node:sqlite`
30
+ * `.all()` killed it instantly. The measurement above is about a process that
31
+ * HAS a JS handler installed — a handler is a JS callback and the blocked
32
+ * event loop is what would schedule it — and with no handler installed
33
+ * SIGTERM's default disposition is kernel-delivered termination that needs no
34
+ * cooperation at all. So SIGTERM works today only because nothing here
35
+ * installs a handler, which is a property one future edit could silently
36
+ * remove; SIGKILL is not a property anything can remove. The design did not
37
+ * change, only the reason for it — recorded because a false claim is at its
38
+ * worst in a section that tells the next reader not to re-derive it.
39
+ * - **The database cannot be handed over.** `DatabaseSync` has no `serialize()`
40
+ * and `:memory:` is per-CONNECTION, so whoever runs the SQL populates its own
41
+ * projection. That is why the child is a whole `vat resources check` run and
42
+ * not a query executor.
43
+ *
44
+ * ## 🔑 The budget is ABSENCE OF PROGRESS, not total runtime
45
+ *
46
+ * A total-runtime bound has to be set above the slowest legitimate run on the
47
+ * largest adopter tree, which makes it useless as a hang detector, and it kills
48
+ * healthy runs that are merely large. So the parent watches the child's progress
49
+ * log and resets its clock on every new line — INCLUDING the population line,
50
+ * which is what bounds the population itself without charging it the first
51
+ * check's budget. A gate that can hang forever is the thing being fixed, and
52
+ * that includes hanging before the first statement.
53
+ *
54
+ * ⚠ïļ **That property holds for the CHECKS. It does NOT hold for the population,
55
+ * and the difference is not a detail.** The population emits exactly ONE line,
56
+ * at its end, so for the single longest unit in a cold run the budget degrades
57
+ * to precisely the total-runtime bound this section argues against: a population
58
+ * that takes longer than the budget is killed however healthily it is working.
59
+ *
60
+ * That is not cheap to fix and a half-fix would be worse than saying so.
61
+ * `onContributorTiming` does fire per contributor, but ~88% of a cold population
62
+ * is the BLOB stage — one call, remark-parsing every document, 33-35 s of the
63
+ * 35 s — and it emits nothing. Per-contributor lines would therefore bound the
64
+ * cheap part, leave the expensive part exactly as unbounded as it is now, and
65
+ * make the whole thing LOOK instrumented. So the population stays one
66
+ * un-instrumented unit, the default budget is set well above a cold one, and the
67
+ * per-unit property is claimed only where it is true.
68
+ *
69
+ * ## Why the child is the CLI itself
70
+ *
71
+ * The child is `vat resources check` with a hidden `--cost-log` flag, running
72
+ * the ordinary in-process path. Forking the logic would give the supervised lane
73
+ * and the unsupervised one two implementations of the same gate — and the one
74
+ * nobody runs interactively is the one that would rot.
75
+ */
76
+ /** What the watchdog remembers between polls. */
77
+ export interface WatchdogState {
78
+ /** How large the progress log was when it last changed. */
79
+ readonly bytesSeen: number;
80
+ /** When that was — the instant the budget is counted from. */
81
+ readonly quietSince: number;
82
+ }
83
+ /**
84
+ * Decide whether the child has gone quiet for longer than the budget.
85
+ *
86
+ * Pure, and separated from the timer for exactly that reason: the interesting
87
+ * behaviour is "a run that keeps making progress is never killed, however long
88
+ * it takes", and a test of that against a real timer would be a twenty-second
89
+ * test that flakes. Here it is twenty function calls.
90
+ *
91
+ * ðŸŠĪ Growth is measured in BYTES rather than parsed lines. A partially written
92
+ * line also grows the file, and treating that as progress is the safe direction:
93
+ * the child is demonstrably alive and writing. Counting lines instead would mean
94
+ * a very slow write could look like silence.
95
+ *
96
+ * @param state - What the previous poll saw
97
+ * @param observation - The run
98
+ * @param observation.bytes - The progress log's current size
99
+ * @param observation.now - The clock, in milliseconds
100
+ * @param observation.budgetMs - How long silence is allowed to last
101
+ * @returns The state to carry forward, and whether the budget was blown
102
+ */
103
+ export declare function pollWatchdog(state: WatchdogState, observation: {
104
+ bytes: number;
105
+ now: number;
106
+ budgetMs: number;
107
+ }): {
108
+ state: WatchdogState;
109
+ breach: boolean;
110
+ };
111
+ /**
112
+ * Read `--budget`, or supply the default.
113
+ *
114
+ * ðŸŠĪ A typo is REFUSED rather than defaulted. `--budget 2O` (letter O) would
115
+ * otherwise run with a five-minute bound while the operator believed they had
116
+ * set two seconds — and they would only find out from a CI job that hung for
117
+ * five minutes instead of two. Thrown, so it exits 2 as an operator error, in
118
+ * line with this command's existing contract for an unknown `--check` name.
119
+ *
120
+ * ðŸšĻ **A BLANK value is refused before `Number` ever sees it, and that is the
121
+ * more important half.** `Number('')`, `Number(' ')` and `Number('\n')` are all
122
+ * `0` — finite, non-negative, and therefore accepted by the range guard below —
123
+ * and `0` is this flag's documented escape hatch meaning *no bound at all*. So
124
+ * `--budget "$CHECK_BUDGET"` with the variable unset did not shorten the bound
125
+ * and did not complain: it silently REMOVED it, on the one flag whose entire
126
+ * purpose is to stop an unattended job hanging forever. An unset shell variable
127
+ * is a far more common CI accident than the typo the guard was written for.
128
+ *
129
+ * ðŸšĻ **The blank string was only the visible half of the hazard, and the guard
130
+ * below it is the rest.** What actually removes the bound is `Number(raw) === 0`
131
+ * for a raw string nobody would recognise as a zero — `--budget 1e-400`
132
+ * underflows to `0`, and `--budget -0` is negative zero, which sails past the
133
+ * `seconds < 0` test because `-0 < 0` is false. Both were MEASURED to run
134
+ * completely unbounded, in process, exiting 0 with no supervision and no word
135
+ * said. So a value that PARSES to zero is refused unless the operator literally
136
+ * wrote a zero: `raw.trim() !== '0'` and it is an operator error. The escape
137
+ * hatch is still there, it just has to be spelled the one unambiguous way.
138
+ *
139
+ * ⚠ïļ That deliberately refuses `0.0` and `0x0` as well. They are not accidents
140
+ * an operator can fall into, they cost one character to rewrite, and a guard
141
+ * with an exception list is a guard whose next exception nobody argues about.
142
+ *
143
+ * 🔑 **Non-zero hex is deliberately KEPT.** `Number('0x10')` is 16 and
144
+ * `--budget 0x10` runs with a sixteen-second bound. That is unambiguous, it
145
+ * cannot arise by accident the way an empty variable can, and refusing it would
146
+ * buy nothing — recorded here so the next reader does not "fix" it into a
147
+ * refusal.
148
+ *
149
+ * @param raw - Whatever Commander parsed, or undefined
150
+ * @returns The budget in seconds; 0 means no bound
151
+ * @throws When the value is blank, means zero without saying so, or is not a
152
+ * non-negative number
153
+ */
154
+ export declare function parseBudgetSeconds(raw: string | undefined): number;
155
+ /**
156
+ * Does this process do the work, or supervise a child that does?
157
+ *
158
+ * ðŸšĻ **The recursion guard, and the reason it is a named function.** `--cost-log`
159
+ * is what a supervising parent hands its child, and it must WIN against the
160
+ * budget — a child that consulted the budget first would spawn a child of its
161
+ * own, which would spawn a child of its own. A condition inline in the command
162
+ * would be a fork bomb one refactor away with nothing asserting on it.
163
+ *
164
+ * `--budget 0` also runs here: there is nothing to supervise, and a spawn would
165
+ * cost a second process startup to buy no bound at all.
166
+ *
167
+ * @param options - The run
168
+ * @param options.costLog - The hidden `--cost-log` value, or undefined
169
+ * @param options.budgetSecs - The bound in seconds; 0 means none
170
+ * @returns True when the checks run in this process
171
+ */
172
+ export declare function runsInThisProcess(options: {
173
+ costLog: string | undefined;
174
+ budgetSecs: number;
175
+ }): boolean;
176
+ /**
177
+ * Refuse a combination where one flag the operator passed would do nothing.
178
+ *
179
+ * ðŸšĻ **The defect: `--cost-log` wins the fork above unconditionally**, so
180
+ * `vat resources check --budget 60 --cost-log /tmp/x` ran entirely UNBOUNDED and
181
+ * said nothing about it. That is harmless to the recursion guard — a child must
182
+ * keep winning — but an explicitly-passed, documented flag that is silently
183
+ * inert is exactly the shape an operator never discovers until the hang it was
184
+ * meant to prevent.
185
+ *
186
+ * ⚠ïļ **The real spawn path must survive this.** {@link runsInThisProcess}'s
187
+ * caller builds the child's argv with `--cost-log` and does NOT forward
188
+ * `--budget` — which is why the RAW flag is the discriminator here rather than
189
+ * the parsed seconds: the child's `budgetSecs` is the 300 s default, not
190
+ * anything the operator typed.
191
+ *
192
+ * `--budget 0` alongside `--cost-log` is allowed: both say "nobody is
193
+ * supervising this", so there is no contradiction to report.
194
+ *
195
+ * @param options - The run
196
+ * @param options.costLog - The hidden `--cost-log` value, or undefined
197
+ * @param options.budgetRaw - What the operator actually typed for `--budget`
198
+ * @param options.budgetSecs - The parsed bound; 0 means none
199
+ * @throws When both flags were passed and the budget could not be honoured
200
+ */
201
+ export declare function requireSupervisableFlags(options: {
202
+ costLog: string | undefined;
203
+ budgetRaw: string | undefined;
204
+ budgetSecs: number;
205
+ }): void;
206
+ /**
207
+ * Why a child ended without completing.
208
+ *
209
+ * Structured rather than a prose string because the two common signals point at
210
+ * DIFFERENT remedies — `SIGABRT` is Node's own heap abort and wants a narrower
211
+ * statement, `SIGKILL` from outside wants a bigger runner — and the message that
212
+ * says so belongs beside the other findings, not here.
213
+ */
214
+ export type AbnormalDeath = {
215
+ readonly kind: 'signal';
216
+ readonly signal: string;
217
+ } | {
218
+ readonly kind: 'spawn-failed';
219
+ readonly binary: string;
220
+ readonly detail: string;
221
+ }
222
+ /**
223
+ * The watchdog fired and the KILL WAS REFUSED — so the child is, as far as
224
+ * this process can tell, still running.
225
+ *
226
+ * ðŸšĻ Distinct from `spawn-failed` and that distinction is the whole point.
227
+ * Both arrive on `child.on('error')` and the handler used to read every one of
228
+ * them as a spawn failure, which reported the exact opposite of what happened:
229
+ * "could not be started at all", "nothing ran at all", "the watchdog never
230
+ * fired". It started, it ran past its budget, the watchdog fired, and it would
231
+ * not die.
232
+ *
233
+ * `pid` is carried because it is the only handle the operator has left on a
234
+ * process this command could not stop.
235
+ */
236
+ | {
237
+ readonly kind: 'kill-failed';
238
+ readonly detail: string;
239
+ readonly pid: number | undefined;
240
+ } | {
241
+ readonly kind: 'no-status';
242
+ }
243
+ /**
244
+ * The child exited with a CODE, and published nothing at all.
245
+ *
246
+ * ðŸšĻ The Windows half of the signal-death defect, and it survived the fix for
247
+ * the POSIX half. A fatal abort — Node's own heap limit among them — has no
248
+ * signal to report on a platform that has none, so `close` fires with
249
+ * `(134, null)` where macOS and Linux give `(null, 'SIGABRT')`. That shape is
250
+ * indistinguishable from an ordinary nonzero exit to
251
+ * {@link resolveChildEnding}, which read it as a COMPLETED run and handed the
252
+ * parent an empty string to forward. Measured on `windows-latest`: exit 134,
253
+ * zero bytes of stdout, on precisely the runaway the bound exists to catch.
254
+ *
255
+ * It did not fail OPEN — 134 is not 0 — so a gate still went red. But the
256
+ * report was absent, which is the other half of what the original defect did.
257
+ *
258
+ * `code` is carried because it is the only thing left that says HOW the child
259
+ * died: 128 + n is the conventional encoding of a fatal signal, and
260
+ * `deathRemedy` reads the signal back out of it.
261
+ */
262
+ | {
263
+ readonly kind: 'no-output';
264
+ readonly code: number;
265
+ };
266
+ /** What a child's ending MEANT, once the watchdog's belief is reconciled with it. */
267
+ export type RunResolution = {
268
+ readonly kind: 'completed';
269
+ readonly code: number;
270
+ } | {
271
+ readonly kind: 'killed';
272
+ } | {
273
+ readonly kind: 'abnormal';
274
+ readonly death: AbnormalDeath;
275
+ };
276
+ /**
277
+ * Read `close`'s two arguments, and the watchdog's belief, into one answer.
278
+ *
279
+ * ## ðŸšĻ The defect this closes: a signal death READ AS SUCCESS
280
+ *
281
+ * `close` fires with `(code, signal)`, and a process that dies from a signal has
282
+ * `code === null` with `signal` set. This handler used to read only the code and
283
+ * coerce it — `resolve(exitCode ?? 0)` — so every signal death became a
284
+ * COMPLETED run with exit code 0. The parent then forwarded an empty stdout and
285
+ * exited 0, and a CI gate reads that as a clean pass.
286
+ *
287
+ * It needed no external actor. A check whose statement materialises an unbounded
288
+ * result set — `SELECT i FROM <infinite recursive CTE>`, the row-returning twin
289
+ * of the aggregate this whole module exists for — makes `.all()` fill the heap
290
+ * until V8 gives up and Node ABORTS. Measured: `PARENT_EXIT=0`, zero bytes of
291
+ * stdout, on precisely the input the bound exists to catch. Through the
292
+ * unsupervised lane the identical input exits 134.
293
+ *
294
+ * Every memory death arrives here: Node's own heap abort, a kernel OOM killer on
295
+ * a memory-capped runner (which picks the large CHILD, never the idle parent),
296
+ * and a container limit. `?? 0` turned all of them into a pass.
297
+ *
298
+ * ## ðŸŠĪ A kill only counts if it LANDED
299
+ *
300
+ * `killed` says the watchdog fired, not that the child died of it. libuv runs
301
+ * timers BEFORE the poll phase that reaps the child, so the timer can fire in
302
+ * the same loop turn as a child that has already exited cleanly. A NORMAL ending
303
+ * — a non-null code with no signal — is therefore honoured whatever `killed`
304
+ * says: that run finished on its own terms and its answer is real. Reporting it
305
+ * as killed fails closed, but it discards a correct result, which is its own
306
+ * kind of wrong.
307
+ *
308
+ * ## ðŸšĻ The ORDER of the tests below is load-bearing
309
+ *
310
+ * `spawnError` used to be tested FIRST, so `killed` was never consulted on that
311
+ * branch — and `child.on('error')` is not only a spawn-failure listener. Node
312
+ * emits `error` on the ChildProcess when `subprocess.kill()` itself fails, so a
313
+ * refused SIGKILL landed on the spawn-failure branch and the report said the
314
+ * child "could not be started at all", that "nothing ran at all, so this is an
315
+ * installation or PATH problem", and that "the watchdog never fired". Three
316
+ * statements, all false, about a runaway that was still executing.
317
+ *
318
+ * So: a real ending first, then what the SUPERVISOR did (a refused kill, then a
319
+ * kill), and only then a failure to start. A run whose kill was refused must
320
+ * never claim the watchdog was uninvolved.
321
+ *
322
+ * @param ending - What `close` reported, plus what the supervisor did and saw
323
+ * @param ending.code - `close`'s first argument
324
+ * @param ending.signal - `close`'s second argument
325
+ * @param ending.killed - Whether the watchdog sent SIGKILL
326
+ * @param ending.spawnError - Set when the child never started at all
327
+ * @param ending.killFailure - Set when the watchdog's SIGKILL was REFUSED
328
+ * @returns What actually happened
329
+ */
330
+ export declare function resolveChildEnding(ending: {
331
+ code: number | null;
332
+ signal: string | null;
333
+ killed: boolean;
334
+ spawnError?: {
335
+ binary: string;
336
+ detail: string;
337
+ } | undefined;
338
+ killFailure?: {
339
+ detail: string;
340
+ pid: number | undefined;
341
+ } | undefined;
342
+ }): RunResolution;
343
+ /**
344
+ * Reconcile "how the process ended" with "what it left behind".
345
+ *
346
+ * ## ðŸšĻ A completion that PUBLISHED NOTHING did not complete
347
+ *
348
+ * {@link resolveChildEnding} answers a question about the process — what `close`
349
+ * reported, reconciled with what the supervisor did. This answers a DIFFERENT
350
+ * one, about the artifact, and the two disagree in exactly one place: a child
351
+ * that exited with a code and wrote no document.
352
+ *
353
+ * Every in-process path through `checkCommand` ends at `emitCheckDocument` or at
354
+ * `handleCommandError`, and both write to stdout — a clean pass, a violation, a
355
+ * bricked config, a mistyped `--check`. There is no exit this command can take
356
+ * that legitimately publishes nothing. So an empty stdout is not a quiet run, it
357
+ * is a run that was cut off before it could say anything, and forwarding its
358
+ * exit code verbatim tells the operator a number and nothing else.
359
+ *
360
+ * ## ðŸŠĪ Why this is not folded into {@link resolveChildEnding}
361
+ *
362
+ * That function's branch ORDER is load-bearing and reasoned entirely about
363
+ * process endings and supervisor beliefs. The emptiness of stdout belongs to
364
+ * neither, and threading it through would put an artifact test inside an
365
+ * ordering argument that has already been got wrong twice. It runs AFTER, on the
366
+ * one branch it can change, and it changes no other.
367
+ *
368
+ * ⚠ïļ **Blank, not unparseable.** The parent forwards the child's document
369
+ * verbatim precisely so it stays `--format`-agnostic, so it cannot ask whether
370
+ * the bytes parse without learning the format. A truncated document — an abort
371
+ * that landed mid-write — therefore still forwards, and that is the honest
372
+ * limit of this test rather than an oversight.
373
+ *
374
+ * @param resolution - How the process ended
375
+ * @param stdout - Everything the child wrote to stdout
376
+ * @returns The resolution, with a silent completion re-read as abnormal
377
+ */
378
+ export declare function resolveSilentCompletion(resolution: RunResolution, stdout: string): RunResolution;
379
+ /** How a supervised run ended. */
380
+ export type SupervisedRun = {
381
+ readonly outcome: 'completed';
382
+ readonly code: number;
383
+ readonly stdout: string;
384
+ } | {
385
+ readonly outcome: 'killed';
386
+ readonly log: string;
387
+ readonly elapsedMs: number;
388
+ } | {
389
+ readonly outcome: 'abnormal';
390
+ readonly death: AbnormalDeath;
391
+ readonly log: string;
392
+ readonly elapsedMs: number;
393
+ };
394
+ /**
395
+ * Run `vat resources check` as a child, bounded by the budget.
396
+ *
397
+ * `stdio` is `['ignore', 'pipe', 'inherit']`: the child's stdout is accumulated
398
+ * so the parent can forward the document verbatim, and its stderr is INHERITED
399
+ * so warnings and blob-stage refusals stream live exactly as they do today.
400
+ *
401
+ * ⚠ïļ Asynchronous `spawn`, never `spawnSync`. The parent's event loop is the
402
+ * thing holding the watchdog timer; a synchronous spawn would block it for
403
+ * precisely as long as the run it is supposed to be bounding.
404
+ *
405
+ * ðŸšĻ There is an `error` listener as well as a `close` one, and it is not
406
+ * optional politeness: without it an unspawnable binary is an unhandled `error`
407
+ * event, which Node turns into a stack dump instead of a report. It fails
408
+ * closed, so this is legibility — but a stack dump is not a report.
409
+ *
410
+ * ## ðŸšĻ `error` is NOT only a spawn-failure listener, and reading it as one
411
+ * ABANDONED A LIVE CHILD
412
+ *
413
+ * Node emits `error` on the ChildProcess when `subprocess.kill()` itself fails.
414
+ * The shipped function ends `else { /* Other error, almost certainly EPERM. *\/
415
+ * this.emit('error', new ErrnoException(err, 'kill')); }`. So: the watchdog
416
+ * breached, `killed` was set, the SIGKILL was refused, `error` fired, the
417
+ * handler recorded a SPAWN failure and resolved immediately — which cleared the
418
+ * watchdog timer, so no further kill could ever be attempted — and the parent
419
+ * published a report saying the child "could not be started at all" and "the
420
+ * watchdog never fired" while the runaway was still executing. The bound this
421
+ * module exists to enforce became an orphaned unbounded hang, described as its
422
+ * own opposite.
423
+ *
424
+ * The handler therefore forks on `killed`, and the two arms are deliberately
425
+ * asymmetric:
426
+ *
427
+ * - **Before the watchdog fired**, an `error` means the child never started.
428
+ * Resolve at once: there is nothing alive to wait for.
429
+ * - **After it fired**, an `error` means the KILL failed and the child is,
430
+ * as far as this process can tell, still running. Do NOT resolve. Resolving
431
+ * is what clears the timer, and clearing the timer is what makes the failure
432
+ * permanent. The poll keeps breaching (the log is not growing and
433
+ * `quietSince` is not reset), so it keeps re-sending SIGKILL, and a transient
434
+ * refusal still lands. Only after {@link KILL_ATTEMPTS_BEFORE_REPORTING}
435
+ * refusals does it give up — and it gives up by REPORTING, naming the pid,
436
+ * never by claiming the child never started.
437
+ *
438
+ * ⚠ïļ Reachability of `EPERM` on one's own child is REASONED rather than
439
+ * reproduced — it is rare on macOS and Linux. Nothing in production was
440
+ * contorted to make it testable; the branch ordering and the message
441
+ * composition are pure functions and are pinned as such.
442
+ *
443
+ * @param options - The run
444
+ * @param options.args - The child's argv after the node binary, `--cost-log` included
445
+ * @param options.logPath - The progress log both sides agreed on
446
+ * @param options.budgetMs - How long silence is allowed to last
447
+ * @returns How the child ended, and what it left behind
448
+ */
449
+ export declare function superviseCheck(options: {
450
+ args: readonly string[];
451
+ logPath: string;
452
+ budgetMs: number;
453
+ }): Promise<SupervisedRun>;
454
+ /**
455
+ * Run `work` with a fresh progress log, and remove it however that ends.
456
+ *
457
+ * ⚠ïļ Ephemeral, per run, and it carries NO format version — see
458
+ * `check-progress.ts`. It is written and read by one process pair within one run
459
+ * of one build, so the reader's own `.strict()` schema is the entire contract.
460
+ *
461
+ * @param work - Given the log's path
462
+ * @returns Whatever `work` returned
463
+ */
464
+ export declare function withProgressLog<T>(work: (logPath: string) => Promise<T>): Promise<T>;
465
+ //# sourceMappingURL=check-supervisor.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"check-supervisor.d.ts","sourceRoot":"","sources":["../../../src/commands/resources/check-supervisor.ts"],"names":[],"mappings":"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"}