@vibe-agent-toolkit/cli 0.2.0-rc.1 → 0.2.0-rc.11

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