vouchington-tooling 0.53.0 → 0.55.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (197) hide show
  1. package/README.md +99 -12
  2. package/dist/agent-blackboard/index.d.mts +0 -1
  3. package/dist/agent-blackboard/index.mjs +0 -23
  4. package/dist/cli/commands/agent-blackboard-flags.d.mts +0 -1
  5. package/dist/cli/commands/agent-blackboard-flags.mjs +0 -9
  6. package/dist/cli/commands/agent-blackboard.d.mts +0 -2
  7. package/dist/cli/commands/agent-blackboard.mjs +7 -121
  8. package/dist/cli/commands/story-coverage.d.mts +2 -0
  9. package/dist/cli/commands/story-coverage.mjs +56 -0
  10. package/dist/cli/index.mjs +6 -0
  11. package/dist/cli/optional-peer.d.mts +5 -0
  12. package/dist/cli/optional-peer.mjs +17 -0
  13. package/dist/cli/parse-forwarded-commands.d.mts +3 -0
  14. package/dist/cli/parse-forwarded-commands.mjs +2 -0
  15. package/dist/cli/parse-story-coverage-fields.d.mts +19 -0
  16. package/dist/cli/parse-story-coverage-fields.mjs +69 -0
  17. package/dist/cli/parse-story-coverage.d.mts +8 -0
  18. package/dist/cli/parse-story-coverage.mjs +34 -0
  19. package/dist/cli/parse.d.mts +5 -1
  20. package/dist/cli/parse.mjs +3 -0
  21. package/dist/cli/story-coverage-lazy.d.mts +3 -0
  22. package/dist/cli/story-coverage-lazy.mjs +6 -0
  23. package/dist/cli/usage.d.mts +1 -1
  24. package/dist/cli/usage.mjs +8 -7
  25. package/dist/host-storage/check.d.mts +38 -0
  26. package/dist/host-storage/check.mjs +109 -0
  27. package/dist/host-storage/cli.d.mts +7 -0
  28. package/dist/host-storage/cli.mjs +102 -0
  29. package/dist/host-storage/host-storage.test-helpers.d.mts +26 -0
  30. package/dist/host-storage/host-storage.test-helpers.mjs +58 -0
  31. package/dist/host-storage/index.d.mts +3 -0
  32. package/dist/host-storage/index.mjs +3 -0
  33. package/dist/host-storage/preflight.d.mts +22 -0
  34. package/dist/host-storage/preflight.mjs +105 -0
  35. package/dist/index.d.mts +2 -0
  36. package/dist/index.mjs +1 -0
  37. package/dist/playwright/assertions.d.mts +1 -0
  38. package/dist/playwright/assertions.mjs +5 -0
  39. package/dist/playwright/blocked-external-network.d.mts +15 -0
  40. package/dist/playwright/blocked-external-network.mjs +73 -0
  41. package/dist/playwright/browser-dialog-issues.d.mts +12 -0
  42. package/dist/playwright/browser-dialog-issues.mjs +29 -0
  43. package/dist/playwright/browser-errors.d.mts +23 -0
  44. package/dist/playwright/browser-errors.mjs +130 -0
  45. package/dist/playwright/browser-issue-monitor.test-helpers.d.mts +31 -0
  46. package/dist/playwright/browser-issue-monitor.test-helpers.mjs +51 -0
  47. package/dist/playwright/browser-issue-records.d.mts +42 -0
  48. package/dist/playwright/browser-issue-records.mjs +148 -0
  49. package/dist/playwright/browser-test.d.mts +22 -0
  50. package/dist/playwright/browser-test.mjs +68 -0
  51. package/dist/playwright/expect-no-broken-images.d.mts +17 -0
  52. package/dist/playwright/expect-no-broken-images.mjs +39 -0
  53. package/dist/playwright/index.d.mts +32 -0
  54. package/dist/playwright/index.mjs +22 -0
  55. package/dist/playwright/mobile-assertions.d.mts +14 -0
  56. package/dist/playwright/mobile-assertions.mjs +43 -0
  57. package/dist/playwright/monitored-test-info.d.mts +14 -0
  58. package/dist/playwright/monitored-test-info.mjs +1 -0
  59. package/dist/playwright/navigate-to.d.mts +27 -0
  60. package/dist/playwright/navigate-to.mjs +39 -0
  61. package/dist/playwright/radix-select.d.mts +18 -0
  62. package/dist/playwright/radix-select.mjs +19 -0
  63. package/dist/playwright/random-id.d.mts +34 -0
  64. package/dist/playwright/random-id.mjs +37 -0
  65. package/dist/playwright/retry-on-connection-lost.d.mts +7 -0
  66. package/dist/playwright/retry-on-connection-lost.mjs +107 -0
  67. package/dist/playwright/scroll-to-load-more.d.mts +37 -0
  68. package/dist/playwright/scroll-to-load-more.mjs +158 -0
  69. package/dist/playwright/storybook.d.mts +2 -0
  70. package/dist/playwright/storybook.mjs +13 -0
  71. package/dist/playwright/test-fixtures.d.mts +1 -0
  72. package/dist/playwright/test-fixtures.mjs +2 -0
  73. package/dist/playwright/test-lifecycle-reporter.d.mts +27 -0
  74. package/dist/playwright/test-lifecycle-reporter.mjs +57 -0
  75. package/dist/playwright/totp.d.mts +6 -0
  76. package/dist/playwright/totp.mjs +37 -0
  77. package/dist/playwright/turnstile-stub.d.mts +8 -0
  78. package/dist/playwright/turnstile-stub.mjs +61 -0
  79. package/dist/playwright/viewport-constants.d.mts +30 -0
  80. package/dist/playwright/viewport-constants.mjs +9 -0
  81. package/dist/playwright/virtual-authenticator.d.mts +5 -0
  82. package/dist/playwright/virtual-authenticator.mjs +15 -0
  83. package/dist/playwright/wait-for-hydration.d.mts +29 -0
  84. package/dist/playwright/wait-for-hydration.mjs +81 -0
  85. package/dist/shell-parse/ansi-c-string.d.mts +12 -0
  86. package/dist/shell-parse/ansi-c-string.mjs +80 -0
  87. package/dist/shell-parse/index.d.mts +20 -0
  88. package/dist/shell-parse/index.mjs +15 -0
  89. package/dist/shell-parse/shell-command-substitution-reads.d.mts +8 -0
  90. package/dist/shell-parse/shell-command-substitution-reads.mjs +53 -0
  91. package/dist/shell-parse/shell-command-substitutions.d.mts +8 -0
  92. package/dist/shell-parse/shell-command-substitutions.mjs +52 -0
  93. package/dist/shell-parse/shell-command-wrappers.d.mts +26 -0
  94. package/dist/shell-parse/shell-command-wrappers.mjs +143 -0
  95. package/dist/shell-parse/shell-commands.d.mts +24 -0
  96. package/dist/shell-parse/shell-commands.mjs +155 -0
  97. package/dist/shell-parse/shell-heredoc-delimiter.d.mts +5 -0
  98. package/dist/shell-parse/shell-heredoc-delimiter.mjs +52 -0
  99. package/dist/shell-parse/shell-heredoc-parser.d.mts +7 -0
  100. package/dist/shell-parse/shell-heredoc-parser.mjs +49 -0
  101. package/dist/shell-parse/shell-heredoc-quote-state.d.mts +19 -0
  102. package/dist/shell-parse/shell-heredoc-quote-state.mjs +40 -0
  103. package/dist/shell-parse/shell-heredoc.d.mts +10 -0
  104. package/dist/shell-parse/shell-heredoc.mjs +90 -0
  105. package/dist/shell-parse/shell-redirections.d.mts +5 -0
  106. package/dist/shell-parse/shell-redirections.mjs +34 -0
  107. package/dist/shell-parse/shell-script-operand.d.mts +13 -0
  108. package/dist/shell-parse/shell-script-operand.mjs +103 -0
  109. package/dist/shell-parse/shell-stdin-script.d.mts +6 -0
  110. package/dist/shell-parse/shell-stdin-script.mjs +61 -0
  111. package/dist/shell-parse/shell-token-utils.d.mts +9 -0
  112. package/dist/shell-parse/shell-token-utils.mjs +33 -0
  113. package/dist/shell-parse/shell-tokenizer-comments.d.mts +1 -0
  114. package/dist/shell-parse/shell-tokenizer-comments.mjs +57 -0
  115. package/dist/shell-parse/shell-tokenizer-operators.d.mts +14 -0
  116. package/dist/shell-parse/shell-tokenizer-operators.mjs +47 -0
  117. package/dist/shell-parse/shell-tokenizer.d.mts +12 -0
  118. package/dist/shell-parse/shell-tokenizer.mjs +104 -0
  119. package/dist/story-coverage/analyze.d.mts +8 -0
  120. package/dist/story-coverage/analyze.mjs +24 -0
  121. package/dist/story-coverage/check.d.mts +11 -0
  122. package/dist/story-coverage/check.mjs +42 -0
  123. package/dist/story-coverage/components.d.mts +10 -0
  124. package/dist/story-coverage/components.mjs +40 -0
  125. package/dist/story-coverage/coverage.d.mts +10 -0
  126. package/dist/story-coverage/coverage.mjs +43 -0
  127. package/dist/story-coverage/index.d.mts +13 -0
  128. package/dist/story-coverage/index.mjs +7 -0
  129. package/dist/story-coverage/messages.d.mts +10 -0
  130. package/dist/story-coverage/messages.mjs +42 -0
  131. package/dist/story-coverage/options.d.mts +27 -0
  132. package/dist/story-coverage/options.mjs +51 -0
  133. package/dist/story-coverage/workspace.d.mts +2 -0
  134. package/dist/story-coverage/workspace.mjs +27 -0
  135. package/dist/test-helpers/cancel-runs.test-helpers.d.mts +39 -0
  136. package/dist/test-helpers/cancel-runs.test-helpers.mjs +124 -0
  137. package/dist/test-helpers/run-bounded-exit-observer.test-helpers.d.mts +12 -0
  138. package/dist/test-helpers/run-bounded-exit-observer.test-helpers.mjs +68 -0
  139. package/dist/test-helpers/run-bounded-output-fixture.test-helpers.d.mts +18 -0
  140. package/dist/test-helpers/run-bounded-output-fixture.test-helpers.mjs +162 -0
  141. package/dist/vitest-diagnostics/browser.d.mts +2 -0
  142. package/dist/vitest-diagnostics/browser.mjs +6 -0
  143. package/dist/vitest-diagnostics/index.d.mts +14 -23
  144. package/dist/vitest-diagnostics/index.mjs +8 -124
  145. package/dist/vitest-diagnostics/report-summary.d.mts +22 -0
  146. package/dist/vitest-diagnostics/report-summary.mjs +123 -0
  147. package/dist/vitest-diagnostics/vitest-fake-timer-guard.d.mts +6 -0
  148. package/dist/vitest-diagnostics/vitest-fake-timer-guard.mjs +34 -0
  149. package/dist/vitest-diagnostics/vitest-fork-leak-detection.d.mts +1 -0
  150. package/dist/vitest-diagnostics/vitest-fork-leak-detection.mjs +8 -0
  151. package/dist/vitest-diagnostics/vitest-fork-leak-diagnostics.d.mts +17 -1
  152. package/dist/vitest-diagnostics/vitest-fork-leak-diagnostics.mjs +44 -2
  153. package/dist/vitest-diagnostics/vitest-fork-leak-handshake-samples.d.mts +55 -0
  154. package/dist/vitest-diagnostics/vitest-fork-leak-handshake-samples.mjs +74 -0
  155. package/dist/vitest-diagnostics/vitest-fork-leak-handshake.d.mts +19 -0
  156. package/dist/vitest-diagnostics/vitest-fork-leak-handshake.mjs +136 -0
  157. package/dist/vitest-diagnostics/vitest-network-allowlist-dns.d.mts +7 -0
  158. package/dist/vitest-diagnostics/vitest-network-allowlist-dns.mjs +54 -0
  159. package/dist/vitest-diagnostics/vitest-network-allowlist-host.d.mts +8 -0
  160. package/dist/vitest-diagnostics/vitest-network-allowlist-host.mjs +48 -0
  161. package/dist/vitest-diagnostics/vitest-network-allowlist-socket.d.mts +14 -0
  162. package/dist/vitest-diagnostics/vitest-network-allowlist-socket.mjs +39 -0
  163. package/dist/vitest-diagnostics/vitest-network-allowlist.d.mts +7 -0
  164. package/dist/vitest-diagnostics/vitest-network-allowlist.mjs +72 -0
  165. package/dist/vitest-diagnostics/vitest-process-resources.d.mts +10 -0
  166. package/dist/vitest-diagnostics/vitest-process-resources.mjs +54 -0
  167. package/dist/vitest-effective-timeout/cap.d.mts +9 -0
  168. package/dist/vitest-effective-timeout/cap.mjs +28 -0
  169. package/dist/vitest-effective-timeout/check-profiles.d.mts +15 -0
  170. package/dist/vitest-effective-timeout/check-profiles.mjs +52 -0
  171. package/dist/vitest-effective-timeout/config-file.d.mts +6 -0
  172. package/dist/vitest-effective-timeout/config-file.mjs +23 -0
  173. package/dist/vitest-effective-timeout/fixtures.d.mts +2 -0
  174. package/dist/vitest-effective-timeout/fixtures.mjs +18 -0
  175. package/dist/vitest-effective-timeout/index.d.mts +7 -0
  176. package/dist/vitest-effective-timeout/index.mjs +4 -0
  177. package/dist/vitest-effective-timeout/profiles.d.mts +10 -0
  178. package/dist/vitest-effective-timeout/profiles.mjs +33 -0
  179. package/dist/vitest-effective-timeout/run-profile.d.mts +31 -0
  180. package/dist/vitest-effective-timeout/run-profile.mjs +95 -0
  181. package/docs/mcp-server.md +2 -13
  182. package/package.json +37 -2
  183. package/scripts/__pycache__/run_bounded_process.cpython-312.pyc +0 -0
  184. package/scripts/chromium-launch-probe.d.mts +7 -0
  185. package/scripts/chromium-launch-probe.mjs +101 -0
  186. package/scripts/run-bounded-fixtures/run-bounded-backpressure.py +186 -0
  187. package/scripts/run-bounded-fixtures/run-bounded-merged-output.py +75 -0
  188. package/scripts/run-bounded-fixtures/run-bounded-reset-socket.py +25 -0
  189. package/scripts/run-bounded.py +199 -0
  190. package/scripts/run_bounded_process.py +129 -0
  191. package/scripts/worktree/git-index-lock.sh +16 -0
  192. package/scripts/worktree/git-worktrees.sh +23 -20
  193. package/scripts/worktree/reset-worktree-run.sh +199 -0
  194. package/scripts/worktree/reset-worktree.sh +122 -0
  195. package/skills/blackboard/SKILL.md +4 -64
  196. package/skills/stacked-prs/SKILL.md +1 -1
  197. package/skills/stacked-prs/references/drain.md +2 -2
@@ -0,0 +1,48 @@
1
+ import { isIP } from 'node:net';
2
+ export function normalizeHost(host) {
3
+ let value = host.trim().toLowerCase();
4
+ if (value.startsWith('[') && value.endsWith(']'))
5
+ value = value.slice(1, -1);
6
+ if (value.endsWith('.'))
7
+ value = value.slice(0, -1);
8
+ return value;
9
+ }
10
+ function isLoopbackHost(host) {
11
+ if (host === 'localhost' || host.endsWith('.localhost'))
12
+ return true;
13
+ if (host === '::' || host === '::1' || host === '0:0:0:0:0:0:0:1' || host === '0.0.0.0')
14
+ return true;
15
+ if (host.startsWith('::ffff:'))
16
+ return isLoopbackHost(host.slice('::ffff:'.length));
17
+ const parts = host.split('.');
18
+ if (parts.length !== 4 || parts.some((part) => !/^\d{1,3}$/.test(part)))
19
+ return false;
20
+ const octets = parts.map(Number);
21
+ return octets[0] === 127 && octets.every((part) => part <= 255);
22
+ }
23
+ export function isAllowedHost(host, current) {
24
+ if (current.isExempt())
25
+ return true;
26
+ const normalized = normalizeHost(host);
27
+ return (current.allowedHosts.has(normalized) ||
28
+ isLoopbackHost(normalized) ||
29
+ current.allowedIps.has(normalized));
30
+ }
31
+ export function rememberAddresses(value, ips) {
32
+ const visit = (item) => {
33
+ if (typeof item === 'string') {
34
+ if (isIP(item) !== 0)
35
+ ips.add(normalizeHost(item));
36
+ return;
37
+ }
38
+ if (Array.isArray(item)) {
39
+ for (const entry of item)
40
+ visit(entry);
41
+ return;
42
+ }
43
+ if (typeof item === 'object' && item !== null && 'address' in item) {
44
+ visit(item.address);
45
+ }
46
+ };
47
+ visit(value);
48
+ }
@@ -0,0 +1,14 @@
1
+ import type { DnsFn } from './vitest-network-allowlist-dns.mts';
2
+ export type NetModule = {
3
+ isIP: (host: string) => number;
4
+ Socket: {
5
+ prototype: {
6
+ connect: DnsFn;
7
+ };
8
+ };
9
+ };
10
+ export type SocketAllowlistHooks = {
11
+ isAllowedHost: (host: string) => boolean;
12
+ blockConnection: (host: string) => Error;
13
+ };
14
+ export declare function patchSocketConnect(net: NetModule, hooks: SocketAllowlistHooks): void;
@@ -0,0 +1,39 @@
1
+ import { normalizeHost } from "./vitest-network-allowlist-host.mjs";
2
+ function isRecord(value) {
3
+ return typeof value === 'object' && value !== null;
4
+ }
5
+ function connectHost(args) {
6
+ const list = Array.isArray(args[0]) ? args[0] : args;
7
+ const first = list[0];
8
+ if (typeof first === 'number') {
9
+ return { host: typeof list[1] === 'string' ? list[1] : 'localhost', options: null };
10
+ }
11
+ if (!isRecord(first))
12
+ return { host: null, options: null };
13
+ const rawHost = first.host ?? first.hostname;
14
+ if (typeof rawHost === 'string' && rawHost.length > 0)
15
+ return { host: rawHost, options: first };
16
+ if (typeof first.path === 'string')
17
+ return { host: null, options: null };
18
+ if (first.port != null)
19
+ return { host: 'localhost', options: first };
20
+ return { host: null, options: null };
21
+ }
22
+ export function patchSocketConnect(net, hooks) {
23
+ const original = net.Socket.prototype.connect;
24
+ net.Socket.prototype.connect = function connect(...args) {
25
+ const target = connectHost(args);
26
+ if (target.host === null || hooks.isAllowedHost(target.host))
27
+ return Reflect.apply(original, this, args);
28
+ const error = hooks.blockConnection(target.host);
29
+ // IP literals skip lookup, so reject them here. Hostnames still call connect so TLS can start.
30
+ if (!target.options || net.isIP(normalizeHost(target.host)) !== 0)
31
+ throw error;
32
+ target.options.lookup = (_hostname, second, third) => {
33
+ const callback = typeof third === 'function' ? third : second;
34
+ if (typeof callback === 'function')
35
+ callback(error);
36
+ };
37
+ return Reflect.apply(original, this, args);
38
+ };
39
+ }
@@ -0,0 +1,7 @@
1
+ export type TestNetworkAllowlistOptions = {
2
+ allowedHosts?: readonly string[];
3
+ isExempt?: () => boolean;
4
+ stateKey?: string;
5
+ };
6
+ export declare function installTestNetworkAllowlist(options?: TestNetworkAllowlistOptions): void;
7
+ export declare function consumeTestNetworkAllowlistViolation(stateKey?: string): string | null;
@@ -0,0 +1,72 @@
1
+ import { patchDnsSurface } from "./vitest-network-allowlist-dns.mjs";
2
+ import { isAllowedHost, normalizeHost, rememberAddresses, } from "./vitest-network-allowlist-host.mjs";
3
+ import { patchSocketConnect } from "./vitest-network-allowlist-socket.mjs";
4
+ const DEFAULT_HOSTS = ['example.com', 'example.net', 'example.org'];
5
+ const DEFAULT_STATE_KEY = 'test.networkAllowlist';
6
+ function defaultExempt() {
7
+ return false;
8
+ }
9
+ function state(key = DEFAULT_STATE_KEY) {
10
+ return (globalThis[Symbol.for(key)] ??=
11
+ {
12
+ installed: false,
13
+ violations: [],
14
+ allowedIps: new Set(),
15
+ allowedHosts: new Set(DEFAULT_HOSTS),
16
+ isExempt: defaultExempt,
17
+ });
18
+ }
19
+ class TestNetworkAllowlistError extends Error {
20
+ code;
21
+ constructor(message) {
22
+ super(message);
23
+ this.name = 'TestNetworkAllowlistError';
24
+ this.code = 'TEST_NETWORK_ALLOWLIST';
25
+ }
26
+ }
27
+ function block(key, kind, host) {
28
+ const action = kind === 'dns' ? 'a DNS lookup for' : 'a connection to';
29
+ const current = state(key);
30
+ const allowed = [...current.allowedHosts].toSorted().join(', ');
31
+ const message = `Test network allowlist blocked ${action} "${normalizeHost(host)}". Tests may only reach ${allowed}, and loopback.`;
32
+ current.violations.push(message);
33
+ return new TestNetworkAllowlistError(message);
34
+ }
35
+ export function installTestNetworkAllowlist(options = {}) {
36
+ const key = options.stateKey ?? DEFAULT_STATE_KEY;
37
+ const current = state(key);
38
+ if (current.installed)
39
+ return;
40
+ current.installed = true;
41
+ current.allowedHosts = new Set(options.allowedHosts ?? DEFAULT_HOSTS);
42
+ current.isExempt = options.isExempt ?? defaultExempt;
43
+ if (typeof process.getBuiltinModule !== 'function')
44
+ return;
45
+ const dns = process.getBuiltinModule('node:dns');
46
+ const net = process.getBuiltinModule('node:net');
47
+ if (typeof net.Socket !== 'function')
48
+ return;
49
+ const hooks = {
50
+ isAllowedHost: (host) => isAllowedHost(host, state(key)),
51
+ blockDns: (host) => block(key, 'dns', host),
52
+ rememberAddresses: (value) => rememberAddresses(value, state(key).allowedIps),
53
+ };
54
+ patchDnsSurface(dns, false, hooks);
55
+ patchDnsSurface(dns.promises, true, hooks);
56
+ patchDnsSurface(dns.Resolver?.prototype, false, hooks);
57
+ patchDnsSurface(dns.promises?.Resolver?.prototype, true, hooks);
58
+ patchSocketConnect(net, {
59
+ isAllowedHost: hooks.isAllowedHost,
60
+ blockConnection: (host) => block(key, 'connection', host),
61
+ });
62
+ const nodeModule = process.getBuiltinModule('node:module');
63
+ nodeModule.syncBuiltinESMExports?.();
64
+ }
65
+ export function consumeTestNetworkAllowlistViolation(stateKey = DEFAULT_STATE_KEY) {
66
+ const violations = state(stateKey).violations;
67
+ if (violations.length === 0)
68
+ return null;
69
+ const message = violations.join('\n');
70
+ violations.length = 0;
71
+ return message;
72
+ }
@@ -0,0 +1,10 @@
1
+ export declare function formatProcessResources(): string;
2
+ export declare function formatActiveResources(): string;
3
+ /**
4
+ * Counts how many times each resource type appears, such as the names returned by
5
+ * `process.getActiveResourcesInfo()`. Pass the result to a fork leak detector's `record`.
6
+ */
7
+ export declare function countResourcesByType(resources: readonly string[]): Map<string, number>;
8
+ export declare function formatResourceCounts(counts: ReadonlyMap<string, number>): string;
9
+ export declare function formatBytes(bytes: number): string;
10
+ export declare function formatPercent(numerator: number, denominator: number): string;
@@ -0,0 +1,54 @@
1
+ // Used by the teardown-overrun diagnostics (onProcessTimeout) to snapshot the main process's
2
+ // resource usage at the boundary where Vitest force-exits.
3
+ import { getHeapStatistics } from 'node:v8';
4
+ export function formatProcessResources() {
5
+ const usage = process.resourceUsage();
6
+ const memory = process.memoryUsage();
7
+ const heapLimitBytes = getHeapStatistics().heap_size_limit;
8
+ return [
9
+ `pid=${process.pid}`,
10
+ `rssMB=${formatBytes(memory.rss)}`,
11
+ `heapUsedMB=${formatBytes(memory.heapUsed)}`,
12
+ `heapTotalMB=${formatBytes(memory.heapTotal)}`,
13
+ // heap_size_limit and its ratio to heapUsed — not heapTotal, which is steady-state V8
14
+ // bookkeeping and was previously misread as "occupancy" against a limit it never carried.
15
+ `heapLimitMB=${formatBytes(heapLimitBytes)}`,
16
+ `heapPctOfLimit=${formatPercent(memory.heapUsed, heapLimitBytes)}`,
17
+ `userCpuMs=${Math.round(usage.userCPUTime / 1000)}`,
18
+ `systemCpuMs=${Math.round(usage.systemCPUTime / 1000)}`,
19
+ ].join(' ');
20
+ }
21
+ export function formatActiveResources() {
22
+ const resources = process.getActiveResourcesInfo?.();
23
+ if (!resources || resources.length === 0)
24
+ return '(none)';
25
+ return resources.slice(0, 20).join(', ');
26
+ }
27
+ /**
28
+ * Counts how many times each resource type appears, such as the names returned by
29
+ * `process.getActiveResourcesInfo()`. Pass the result to a fork leak detector's `record`.
30
+ */
31
+ export function countResourcesByType(resources) {
32
+ const counts = new Map();
33
+ for (const resource of resources) {
34
+ counts.set(resource, (counts.get(resource) ?? 0) + 1);
35
+ }
36
+ return counts;
37
+ }
38
+ export function formatResourceCounts(counts) {
39
+ if (counts.size === 0)
40
+ return '(none)';
41
+ return [...counts.entries()]
42
+ .toSorted(([a], [b]) => a.localeCompare(b))
43
+ .map(([type, count]) => `${type}=${count}`)
44
+ .join(' ');
45
+ }
46
+ // Rounding shared by the main-process resource line and its unit test.
47
+ export function formatBytes(bytes) {
48
+ return (bytes / (1024 * 1024)).toFixed(1);
49
+ }
50
+ export function formatPercent(numerator, denominator) {
51
+ if (denominator <= 0)
52
+ return '0.0';
53
+ return ((numerator / denominator) * 100).toFixed(1);
54
+ }
@@ -0,0 +1,9 @@
1
+ import type { Plugin } from 'vitest/config';
2
+ export declare const DEFAULT_EFFECTIVE_TIMEOUT_MS = 30000;
3
+ export declare const DEFAULT_EFFECTIVE_TIMEOUT_PLUGIN = "effective-test-timeout-cap";
4
+ export type EffectiveTimeoutCapOptions = {
5
+ maxTimeoutMs?: number;
6
+ name?: string;
7
+ };
8
+ export declare function assertEffectiveTimeoutCap(maxTimeoutMs: number): number;
9
+ export declare function effectiveTimeoutCap(options?: EffectiveTimeoutCapOptions): Plugin;
@@ -0,0 +1,28 @@
1
+ export const DEFAULT_EFFECTIVE_TIMEOUT_MS = 30_000;
2
+ export const DEFAULT_EFFECTIVE_TIMEOUT_PLUGIN = 'effective-test-timeout-cap';
3
+ const MIN_FIXTURE_TIMEOUT_MS = 5_000;
4
+ export function assertEffectiveTimeoutCap(maxTimeoutMs) {
5
+ if (!Number.isFinite(maxTimeoutMs) || maxTimeoutMs < MIN_FIXTURE_TIMEOUT_MS) {
6
+ throw new RangeError(`effective timeout cap must be finite and at least ${MIN_FIXTURE_TIMEOUT_MS}ms; received ${maxTimeoutMs}`);
7
+ }
8
+ return maxTimeoutMs;
9
+ }
10
+ // Validate selected projects after framework normalization, before global setup imports.
11
+ export function effectiveTimeoutCap(options = {}) {
12
+ const maxTimeoutMs = assertEffectiveTimeoutCap(options.maxTimeoutMs ?? DEFAULT_EFFECTIVE_TIMEOUT_MS);
13
+ const name = options.name ?? DEFAULT_EFFECTIVE_TIMEOUT_PLUGIN;
14
+ return {
15
+ name,
16
+ configureVitest({ project }) {
17
+ for (const field of ['testTimeout', 'hookTimeout']) {
18
+ const value = project.config[field];
19
+ if (typeof value !== 'number' ||
20
+ !Number.isFinite(value) ||
21
+ value <= 0 ||
22
+ value > maxTimeoutMs) {
23
+ throw new RangeError(`Project ${project.config.name}: effective ${field} must be finite, positive, and at most ${maxTimeoutMs}ms; received ${value}`);
24
+ }
25
+ }
26
+ },
27
+ };
28
+ }
@@ -0,0 +1,15 @@
1
+ import { type CliOptions } from 'vitest/node';
2
+ import { type OpenTimeoutRun, type TimeoutProfileRow } from './run-profile.mts';
3
+ export type FiniteTimeoutProfileOptions = {
4
+ maxTimeoutMs?: number;
5
+ pluginName?: string;
6
+ scratchDir?: string;
7
+ open?: OpenTimeoutRun;
8
+ removeScratch?: (path: string) => Promise<void>;
9
+ };
10
+ export declare function openVitestTimeoutRun(input: {
11
+ root: string;
12
+ configFile: string;
13
+ cli: CliOptions;
14
+ }): Promise<Awaited<ReturnType<OpenTimeoutRun>>>;
15
+ export declare function checkFiniteTimeoutProfiles(repoRoot: string, options?: FiniteTimeoutProfileOptions): Promise<TimeoutProfileRow[]>;
@@ -0,0 +1,52 @@
1
+ import { mkdir, mkdtemp, rm } from 'node:fs/promises';
2
+ import { join } from 'node:path';
3
+ import { createVitest } from 'vitest/node';
4
+ import { assertEffectiveTimeoutCap, DEFAULT_EFFECTIVE_TIMEOUT_MS, DEFAULT_EFFECTIVE_TIMEOUT_PLUGIN, } from "./cap.mjs";
5
+ import { timeoutProfiles } from "./profiles.mjs";
6
+ import { runTimeoutProfile } from "./run-profile.mjs";
7
+ export async function openVitestTimeoutRun(input) {
8
+ const context = await createVitest({
9
+ root: input.root,
10
+ config: input.configFile,
11
+ watch: false,
12
+ run: true,
13
+ reporters: [],
14
+ ...input.cli,
15
+ });
16
+ return { start: () => context.start(), close: () => context.close() };
17
+ }
18
+ export async function checkFiniteTimeoutProfiles(repoRoot, options = {}) {
19
+ const maxTimeoutMs = assertEffectiveTimeoutCap(options.maxTimeoutMs ?? DEFAULT_EFFECTIVE_TIMEOUT_MS);
20
+ const pluginName = options.pluginName ?? DEFAULT_EFFECTIVE_TIMEOUT_PLUGIN;
21
+ const open = options.open ?? openVitestTimeoutRun;
22
+ const removeScratch = options.removeScratch ?? ((path) => rm(path, { recursive: true, force: true }));
23
+ const scratchParent = options.scratchDir ?? join(repoRoot, '.cache');
24
+ await mkdir(scratchParent, { recursive: true });
25
+ const scratch = await mkdtemp(join(scratchParent, 'effective-timeout-cap-'));
26
+ const rows = [];
27
+ let failed = false;
28
+ let primary;
29
+ const cleanup = [];
30
+ try {
31
+ for (const profile of timeoutProfiles(maxTimeoutMs)) {
32
+ rows.push(await runTimeoutProfile(profile, { scratch, maxTimeoutMs, pluginName, open }));
33
+ }
34
+ }
35
+ catch (err) {
36
+ failed = true;
37
+ primary = err;
38
+ }
39
+ finally {
40
+ try {
41
+ await removeScratch(scratch);
42
+ }
43
+ catch (err) {
44
+ cleanup.push(err);
45
+ }
46
+ }
47
+ if (failed || cleanup.length) {
48
+ const errors = [...(failed ? [primary] : []), ...cleanup];
49
+ throw new AggregateError(errors, 'Finite timeout admission failed', { cause: errors[0] });
50
+ }
51
+ return rows;
52
+ }
@@ -0,0 +1,6 @@
1
+ export declare const DEFAULT_ROOT_VITEST_CONFIG = "vitest.config.mts";
2
+ export declare function assertCanonicalRootVitestConfig(files: readonly string[], configFileName?: string): void;
3
+ export declare function checkCanonicalRootVitestConfigControls(configFileName?: string): {
4
+ name: string;
5
+ admitted: boolean;
6
+ }[];
@@ -0,0 +1,23 @@
1
+ import assert from 'node:assert/strict';
2
+ export const DEFAULT_ROOT_VITEST_CONFIG = 'vitest.config.mts';
3
+ export function assertCanonicalRootVitestConfig(files, configFileName = DEFAULT_ROOT_VITEST_CONFIG) {
4
+ assert.deepEqual(files.filter((file) => file.startsWith('vitest.config.')).toSorted(), [
5
+ configFileName,
6
+ ]);
7
+ }
8
+ export function checkCanonicalRootVitestConfigControls(configFileName = DEFAULT_ROOT_VITEST_CONFIG) {
9
+ const alternate = configFileName.endsWith('.mts') ? 'vitest.config.ts' : 'vitest.config.mts';
10
+ const cases = [
11
+ { name: 'canonical', files: ['README.md', configFileName], admitted: true },
12
+ { name: 'missing', files: ['README.md'], admitted: false },
13
+ { name: 'alternate', files: [alternate], admitted: false },
14
+ { name: 'additional', files: [configFileName, alternate], admitted: false },
15
+ ];
16
+ for (const control of cases) {
17
+ if (control.admitted)
18
+ assertCanonicalRootVitestConfig(control.files, configFileName);
19
+ else
20
+ assert.throws(() => assertCanonicalRootVitestConfig(control.files, configFileName), assert.AssertionError);
21
+ }
22
+ return cases.map(({ name, admitted }) => ({ name, admitted }));
23
+ }
@@ -0,0 +1,2 @@
1
+ export declare const EFFECTIVE_TIMEOUT_CASE = "import { readFile, writeFile } from 'node:fs/promises'\nimport { describe, expect, it } from 'vitest'\n\ndescribe('effective timeout admission', () => {\n it('runs its owned setup before the body', async () => {\n expect(await readFile(new URL('./setup-call.marker', import.meta.url), 'utf8')).toBe('called')\n await writeFile(new URL('./body.marker', import.meta.url), 'ran')\n })\n})\n";
2
+ export declare const EFFECTIVE_TIMEOUT_SETUP = "import { writeFileSync } from 'node:fs'\n\nwriteFileSync(new URL('./setup-import.marker', import.meta.url), 'imported')\n\nexport default function setup() {\n writeFileSync(new URL('./setup-call.marker', import.meta.url), 'called')\n}\n";
@@ -0,0 +1,18 @@
1
+ export const EFFECTIVE_TIMEOUT_CASE = `import { readFile, writeFile } from 'node:fs/promises'
2
+ import { describe, expect, it } from 'vitest'
3
+
4
+ describe('effective timeout admission', () => {
5
+ it('runs its owned setup before the body', async () => {
6
+ expect(await readFile(new URL('./setup-call.marker', import.meta.url), 'utf8')).toBe('called')
7
+ await writeFile(new URL('./body.marker', import.meta.url), 'ran')
8
+ })
9
+ })
10
+ `;
11
+ export const EFFECTIVE_TIMEOUT_SETUP = `import { writeFileSync } from 'node:fs'
12
+
13
+ writeFileSync(new URL('./setup-import.marker', import.meta.url), 'imported')
14
+
15
+ export default function setup() {
16
+ writeFileSync(new URL('./setup-call.marker', import.meta.url), 'called')
17
+ }
18
+ `;
@@ -0,0 +1,7 @@
1
+ export { assertEffectiveTimeoutCap, DEFAULT_EFFECTIVE_TIMEOUT_MS, DEFAULT_EFFECTIVE_TIMEOUT_PLUGIN, effectiveTimeoutCap, } from './cap.mts';
2
+ export type { EffectiveTimeoutCapOptions } from './cap.mts';
3
+ export { assertCanonicalRootVitestConfig, checkCanonicalRootVitestConfigControls, DEFAULT_ROOT_VITEST_CONFIG, } from './config-file.mts';
4
+ export { checkFiniteTimeoutProfiles, openVitestTimeoutRun } from './check-profiles.mts';
5
+ export type { FiniteTimeoutProfileOptions } from './check-profiles.mts';
6
+ export { effectiveTimeoutGuardHref } from './run-profile.mts';
7
+ export type { OpenTimeoutRun, TimeoutProfileRow } from './run-profile.mts';
@@ -0,0 +1,4 @@
1
+ export { assertEffectiveTimeoutCap, DEFAULT_EFFECTIVE_TIMEOUT_MS, DEFAULT_EFFECTIVE_TIMEOUT_PLUGIN, effectiveTimeoutCap, } from "./cap.mjs";
2
+ export { assertCanonicalRootVitestConfig, checkCanonicalRootVitestConfigControls, DEFAULT_ROOT_VITEST_CONFIG, } from "./config-file.mjs";
3
+ export { checkFiniteTimeoutProfiles, openVitestTimeoutRun } from "./check-profiles.mjs";
4
+ export { effectiveTimeoutGuardHref } from "./run-profile.mjs";
@@ -0,0 +1,10 @@
1
+ import type { CliOptions } from 'vitest/node';
2
+ export type TimeoutProfile = {
3
+ name: string;
4
+ admitted: boolean;
5
+ options?: CliOptions;
6
+ configHookTimeout?: number;
7
+ child?: boolean;
8
+ withoutGuard?: boolean;
9
+ };
10
+ export declare function timeoutProfiles(maxTimeoutMs: number): readonly TimeoutProfile[];
@@ -0,0 +1,33 @@
1
+ export function timeoutProfiles(maxTimeoutMs) {
2
+ const midCap = maxTimeoutMs >= 15_000
3
+ ? [{ name: 'bounded-fifteen', options: { testTimeout: 15_000 }, admitted: true }]
4
+ : [];
5
+ return [
6
+ { name: 'bounded-five', admitted: true },
7
+ ...midCap,
8
+ { name: 'bounded-thirty', options: { testTimeout: maxTimeoutMs }, admitted: true },
9
+ { name: 'oversized-cli', options: { testTimeout: maxTimeoutMs + 1 }, admitted: false },
10
+ { name: 'disabled-test', options: { testTimeout: 0 }, admitted: false },
11
+ { name: 'infinite-test', options: { testTimeout: Infinity }, admitted: false },
12
+ { name: 'disabled-hook', configHookTimeout: 0, admitted: false },
13
+ { name: 'infinite-hook', configHookTimeout: Infinity, admitted: false },
14
+ { name: 'unused-root-zero', child: true, admitted: true },
15
+ {
16
+ name: 'reporter-does-not-bypass',
17
+ options: { testTimeout: maxTimeoutMs + 1, reporters: ['json'] },
18
+ admitted: false,
19
+ },
20
+ {
21
+ name: 'normalized-child-hook-zero',
22
+ options: { hookTimeout: 0 },
23
+ child: true,
24
+ admitted: true,
25
+ },
26
+ {
27
+ name: 'removed-guard-negative',
28
+ options: { testTimeout: maxTimeoutMs + 1 },
29
+ withoutGuard: true,
30
+ admitted: true,
31
+ },
32
+ ];
33
+ }
@@ -0,0 +1,31 @@
1
+ import type { CliOptions } from 'vitest/node';
2
+ import type { TimeoutProfile } from './profiles.mts';
3
+ type StartedTimeoutRun = {
4
+ testModules: readonly {
5
+ ok: () => boolean;
6
+ }[];
7
+ unhandledErrors: readonly unknown[];
8
+ };
9
+ export type OpenTimeoutRun = (input: {
10
+ root: string;
11
+ configFile: string;
12
+ cli: CliOptions;
13
+ }) => Promise<{
14
+ start: () => Promise<StartedTimeoutRun>;
15
+ close: () => Promise<void>;
16
+ }>;
17
+ export type TimeoutProfileRow = {
18
+ profile: string;
19
+ body: boolean;
20
+ setupImport: boolean;
21
+ setupCall: boolean;
22
+ rejected: boolean;
23
+ };
24
+ export declare function effectiveTimeoutGuardHref(moduleUrl?: string): string;
25
+ export declare function runTimeoutProfile(profile: TimeoutProfile, input: {
26
+ scratch: string;
27
+ maxTimeoutMs: number;
28
+ pluginName: string;
29
+ open: OpenTimeoutRun;
30
+ }): Promise<TimeoutProfileRow>;
31
+ export {};
@@ -0,0 +1,95 @@
1
+ import assert from 'node:assert/strict';
2
+ import { access, mkdir, writeFile } from 'node:fs/promises';
3
+ import { join } from 'node:path';
4
+ import { EFFECTIVE_TIMEOUT_CASE, EFFECTIVE_TIMEOUT_SETUP } from "./fixtures.mjs";
5
+ export function effectiveTimeoutGuardHref(moduleUrl = import.meta.url) {
6
+ const fileName = moduleUrl.endsWith('.mjs') ? 'cap.mjs' : 'cap.mts';
7
+ return new URL(fileName, moduleUrl).href;
8
+ }
9
+ function renderConfig(input) {
10
+ const test = {
11
+ name: 'owned-effective-timeout',
12
+ include: ['case.mts'],
13
+ testTimeout: 5000,
14
+ hookTimeout: 5000,
15
+ globalSetup: [join(input.root, 'setup.mts')],
16
+ };
17
+ const plugins = input.profile.withoutGuard
18
+ ? '[]'
19
+ : `[effectiveTimeoutCap(${JSON.stringify({ maxTimeoutMs: input.maxTimeoutMs, name: input.pluginName })})]`;
20
+ const testConfig = input.profile.child
21
+ ? '{ testTimeout: 0, hookTimeout: 0, projects: [{ extends: true, test }] }'
22
+ : 'test';
23
+ return `import { effectiveTimeoutCap } from ${JSON.stringify(effectiveTimeoutGuardHref())};
24
+ const test = { ...${JSON.stringify(test)}, hookTimeout: ${String(input.profile.configHookTimeout ?? 5000)} };
25
+ export default {
26
+ root: ${JSON.stringify(input.root)},
27
+ plugins: ${plugins},
28
+ test: ${testConfig},
29
+ };
30
+ `;
31
+ }
32
+ async function markerExists(path) {
33
+ try {
34
+ await access(path);
35
+ return true;
36
+ }
37
+ catch (err) {
38
+ if (err instanceof Error && 'code' in err && err.code === 'ENOENT')
39
+ return false;
40
+ throw err;
41
+ }
42
+ }
43
+ export async function runTimeoutProfile(profile, input) {
44
+ const root = join(input.scratch, profile.name);
45
+ await mkdir(root, { recursive: true });
46
+ await writeFile(join(root, 'case.mts'), EFFECTIVE_TIMEOUT_CASE);
47
+ await writeFile(join(root, 'setup.mts'), EFFECTIVE_TIMEOUT_SETUP);
48
+ const configFile = join(root, 'vitest.config.mts');
49
+ await writeFile(configFile, renderConfig({ root, profile, maxTimeoutMs: input.maxTimeoutMs, pluginName: input.pluginName }));
50
+ let opened;
51
+ let rejected = false;
52
+ let rejection;
53
+ let result;
54
+ const closeErrors = [];
55
+ try {
56
+ opened = await input.open({ root, configFile, cli: profile.options ?? {} });
57
+ result = await opened.start();
58
+ }
59
+ catch (err) {
60
+ rejected = true;
61
+ rejection = err;
62
+ }
63
+ finally {
64
+ try {
65
+ await opened?.close();
66
+ }
67
+ catch (err) {
68
+ closeErrors.push(err);
69
+ }
70
+ }
71
+ if (closeErrors.length) {
72
+ const errors = [...(rejected ? [rejection] : []), ...closeErrors];
73
+ throw new AggregateError(errors, 'Profile context close failed', { cause: errors[0] });
74
+ }
75
+ const row = {
76
+ profile: profile.name,
77
+ body: await markerExists(join(root, 'body.marker')),
78
+ setupImport: await markerExists(join(root, 'setup-import.marker')),
79
+ setupCall: await markerExists(join(root, 'setup-call.marker')),
80
+ rejected,
81
+ };
82
+ for (const field of ['body', 'setupImport', 'setupCall']) {
83
+ assert.equal(row[field], profile.admitted, JSON.stringify(row));
84
+ }
85
+ assert.equal(rejected, !profile.admitted, String(rejection));
86
+ if (profile.admitted) {
87
+ assert.equal(result?.testModules.length, 1);
88
+ assert.equal(result?.testModules[0]?.ok(), true);
89
+ assert.equal(result?.unhandledErrors.length, 0);
90
+ }
91
+ else {
92
+ assert.match(String(rejection), /effective (testTimeout|hookTimeout) must be/);
93
+ }
94
+ return row;
95
+ }
@@ -38,17 +38,6 @@ status 1.
38
38
  The connection comes from `AGENT_BLACKBOARD_URL` and `AGENT_BLACKBOARD_TOKEN` in the server's
39
39
  environment. The server never searches for, prints, or mints them.
40
40
 
41
- ## CLI fallback
42
-
43
- MCP is the supported path. If it is unavailable, restore it first as the blackboard skill describes.
44
- As a last resort, use `vouchington agent-blackboard journal append|entries|flush|status` as described
45
- there; sandboxed Claude Code and Codex withhold the token, so it can only retain records in the
46
- outbox the server later flushes. Record the fallback and delivery status in the journal and tell the human. The CLI resolves its
47
- client from its own installation, so install `agent-blackboard` alongside that trusted CLI.
48
- Run the script with a verified absolute `node` and a cleared environment (`env -i`), never through
49
- its `#!/usr/bin/env node` line, which takes `node` from a possibly repository-controlled `PATH`.
50
- A missing MCP connection does not waive persistence or readback requirements.
51
-
52
41
  ## Launch
53
42
 
54
43
  ```bash
@@ -118,7 +107,7 @@ whatever its timestamp, is a conflict.
118
107
 
119
108
  A session that already exists with a different `version` (an agent upgrade, or a session another
120
109
  writer created) is not a conflict: the entry is delivered into it and the result reports
121
- `storedVersion`, in `journal_append` and in `vouchington agent-blackboard journal append`. A
110
+ `storedVersion`, in `journal_append`. A
122
111
  different `parentSessionId` or `agent` is an `identity-conflict`, and the error names each
123
112
  differing field with its stored and supplied value, for example
124
113
  `identity-conflict: agent stored "claude", supplied "codex"`.
@@ -128,7 +117,7 @@ client returns (`sessionId`, `createdAt`, `data`), so `data` keeps its envelope
128
117
  `repositories`, `sourceEventId`, `workOutcome`, and `feedbackCoverage`. Entries of every type come
129
118
  back, including `retrospective` and legacy entries without an envelope. The client documents no
130
119
  order, so they are sorted stably by `createdAt`, oldest first. An empty session returns
131
- `entries: []`. `vouchington agent-blackboard journal entries` still prints journal markdown only.
120
+ `entries: []`.
132
121
 
133
122
  `sessionId` on `outbox_status`, `outbox_flush`, and `snapshot_export` only identifies the caller.
134
123
  The outbox is per worktree, so the results name two counts apart. `pendingCount` is the number of