Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

Deterministic CLI unit tests: a temporary folder per worker, Hermes hook lines in home order (#1190)

Deeb4f55183b992
diff --git a/cli/src/engines/kit/nativeHookYaml.spec.ts b/cli/src/engines/kit/nativeHookYaml.spec.ts
new file mode 100644
index 000000000..3842f2bfa
--- /dev/null
+++ b/cli/src/engines/kit/nativeHookYaml.spec.ts
@@ -0,0 +1,60 @@
+import { mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, beforeEach, expect, it, vi } from 'vitest'
+import { HERMES_HOOK_SETTINGS } from '../hermes/contract.js'
+import { installNativeYamlHooks } from './nativeHookYaml.js'
+
+// A home's preparation can be held before it starts, so the homes finish in the order a test chooses.
+const gate = vi.hoisted(() => ({
+ before: undefined as undefined | ((files: readonly string[]) => Promise<void>),
+ after: undefined as undefined | ((files: readonly string[]) => void),
+}))
+vi.mock('./nativeHookFiles.js', async original => {
+ const actual = await original<typeof import('./nativeHookFiles.js')>()
+ return { ...actual, runHookPreparation: async (...args: Parameters<typeof actual.runHookPreparation>) => {
+ await gate.before?.(args[0])
+ try { return await actual.runHookPreparation(...args) } finally { gate.after?.(args[0]) }
+ } }
+})
+
+let root: string, home: string, profile: string
+beforeEach(() => {
+ root = realpathSync(mkdtempSync(join(tmpdir(), 'native-hook-yaml-')))
+ home = join(root, 'hermes'); profile = join(home, 'profiles', 'work')
+ mkdirSync(profile, { recursive: true })
+ writeFileSync(join(home, 'config.yaml'), 'model: x\n'); writeFileSync(join(profile, 'config.yaml'), 'model: y\n')
+})
+afterEach(() => { gate.before = undefined; gate.after = undefined; vi.restoreAllMocks(); rmSync(root, { recursive: true, force: true }) })
+
+/** The default home starts only once the profile is done, as it happened on a busy CI shard. */
+function profileFirst(): void {
+ let done!: () => void
+ const profileDone = new Promise<void>(resolve => { done = resolve })
+ gate.before = async files => { if (files[0] === join(home, 'config.yaml')) await profileDone }
+ gate.after = files => { if (files[0] === join(profile, 'config.yaml')) done() }
+}
+
+it('says what each home did in the homes\' order, whichever home finishes first', async () => {
+ const lines: string[] = []
+ vi.spyOn(console, 'log').mockImplementation((...args: unknown[]) => { lines.push(args.join(' ')) })
+ vi.spyOn(console, 'error').mockImplementation((...args: unknown[]) => { lines.push(args.join(' ')) })
+ const rule = { ...HERMES_HOOK_SETTINGS, home }
+ const command = (at: string) => `node /fixture/notify.mjs --port 4242 --data-dir /fixture/data --hermes-home ${at} --engine hermes`
+
+ profileFirst()
+ expect(await installNativeYamlHooks(rule, command)).toBe(true)
+ expect(readFileSync(join(home, 'config.yaml'), 'utf8')).toContain(`--hermes-home ${home}`)
+ expect(readFileSync(join(profile, 'config.yaml'), 'utf8')).toContain(`--hermes-home ${profile}`)
+ expect(lines).toEqual([
+ `[hooks] installed Hermes session hooks → ${join(home, 'config.yaml')}`,
+ '[hooks] (takes effect on the next hermes session start)',
+ `[hooks] installed Hermes session hooks → ${join(profile, 'config.yaml')}`,
+ '[hooks] (takes effect on the next hermes session start)',
+ ])
+
+ lines.length = 0
+ profileFirst()
+ expect(await installNativeYamlHooks(rule, command)).toBe(true)
+ expect(lines).toEqual(['[hooks] Hermes session hooks already installed', '[hooks] Hermes session hooks already installed (work)'])
+})
diff --git a/cli/src/engines/kit/nativeHookYaml.ts b/cli/src/engines/kit/nativeHookYaml.ts
index 32dfe84ed..78aafbb0f 100644
--- a/cli/src/engines/kit/nativeHookYaml.ts
+++ b/cli/src/engines/kit/nativeHookYaml.ts
@@ -111,14 +111,29 @@ function stripOwnedBlocks(rule: NativeYamlHooks, config: string, hookLines: Read
return { cleaned: out.join('\n').replace(/\n{3,}$/, '\n'), foreignHooks, removed }
}
+/** What one home's installation said, held until every home before it has said its own. */
+type HomeLines = Array<{ stream: 'log' | 'error'; args: unknown[] }>
+
/** Installs only homes with a config, each with its own command and allowlist. */
export async function installNativeYamlHooks(rule: NativeYamlHooks, commandForHome: (home: string) => string, selectedHome?: string, options: HookPreparationOptions & { createMissing?: boolean } = {}): Promise<boolean> {
const homes = selectedHome ? [selectedHome] : nativeHookHomes(rule.homes, rule.home)
- let next = 0, installed = true
+ // Homes are prepared four at a time, but what each says is printed in the homes' order: the default
+ // home, then its profiles. Printed as each finished, a profile's lines came before the default home's
+ // whenever its disk confirmation returned first, which the Hermes golden (otherHooks.golden.spec.ts)
+ // caught on busy CI shards. Before the pool (#1158) the homes were installed, and logged, in order.
+ const lines: HomeLines[] = homes.map(() => []), finished = homes.map(() => false)
+ let next = 0, printed = 0, installed = true
+ const print = () => {
+ for (; printed < homes.length && finished[printed]; printed++) {
+ for (const { stream, args } of lines[printed]) console[stream](...args)
+ }
+ }
const worker = async () => {
while (next < homes.length) {
- const home = homes[next++]
- if (!await installIn(rule, commandForHome(home), home, options)) installed = false
+ const index = next++, home = homes[index]
+ try {
+ if (!await installIn(rule, commandForHome(home), home, options, lines[index])) installed = false
+ } finally { finished[index] = true; print() }
}
}
// The declared catalog includes up to 64 profiles. Starting them all at once
@@ -127,12 +142,14 @@ export async function installNativeYamlHooks(rule: NativeYamlHooks, commandForHo
return installed
}
-async function installIn(rule: NativeYamlHooks, cmd: string, home: string, options: HookPreparationOptions & { createMissing?: boolean }): Promise<boolean> {
+async function installIn(rule: NativeYamlHooks, cmd: string, home: string, options: HookPreparationOptions & { createMissing?: boolean }, lines: HomeLines): Promise<boolean> {
+ const log = (...args: unknown[]) => { lines.push({ stream: 'log', args }) }
+ const error = (...args: unknown[]) => { lines.push({ stream: 'error', args }) }
const configPath = join(home, rule.homes.file)
try { return await runHookPreparation([configPath, join(home, rule.allowlist)], async attempt => {
const observed = inspectHookFile(configPath)
if (observed.content === null && !options.createMissing) {
- if (home === rule.home) console.log(message(rule.messages.missing, { file: configPath }))
+ if (home === rule.home) log(message(rule.messages.missing, { file: configPath }))
return false
}
// A captured launch owns preparation of its selected home, including its
@@ -165,9 +182,9 @@ async function installIn(rule: NativeYamlHooks, cmd: string, home: string, optio
throw new HookPreparationHeld('the YAML configuration is not a complete mapping')
}
if (foreignHooks || document.has('hooks')) {
- console.error(message(rule.messages.foreign, { file: configPath }))
- console.error(rule.messages.manual)
- for (const event of rule.events) console.error(`[hooks] ${event}: [{ command: ${JSON.stringify(cmd)}, timeout: ${rule.timeout} }]`)
+ error(message(rule.messages.foreign, { file: configPath }))
+ error(rule.messages.manual)
+ for (const event of rule.events) error(`[hooks] ${event}: [{ command: ${JSON.stringify(cmd)}, timeout: ${rule.timeout} }]`)
return false
}
@@ -182,21 +199,21 @@ async function installIn(rule: NativeYamlHooks, cmd: string, home: string, optio
if (next === config) {
const installed = await observed.replace(config, attempt), approved = await approve(attempt)
installed.verify(); approved.verify()
- console.log(rule.messages.current + (home === rule.home ? '' : ` (${basename(home)})`))
+ log(rule.messages.current + (home === rule.home ? '' : ` (${basename(home)})`))
return true
}
const installed = await observed.replace(next, attempt), approved = await approve(attempt)
installed.verify(); approved.verify()
- console.log(
+ log(
removed > 1
? message(rule.messages.collapsed, { removed: String(removed), file: configPath })
: message(rule.messages.installed, { file: configPath }),
)
- console.log(rule.messages.after)
+ log(rule.messages.after)
return true
}, { ...options, identity: JSON.stringify([rule, cmd, home]) }) } catch (err) {
- console.error(rule.messages.failed, err)
+ error(rule.messages.failed, err)
return false
}
}
diff --git a/cli/vitest.config.ts b/cli/vitest.config.ts
index e16ae431e..0a422a50b 100644
--- a/cli/vitest.config.ts
+++ b/cli/vitest.config.ts
@@ -4,7 +4,7 @@ import { defineConfig } from 'vitest/config'
export default defineConfig({
test: {
environment: 'node',
- setupFiles: ['./vitest.setup.ts'],
+ setupFiles: ['./vitest.tmpdir.ts', './vitest.setup.ts'],
include: ['src/**/*.test.ts', 'src/**/*.spec.ts'],
// These suites spawn real shells, hooks and tmux helpers with bounded
// deadlines. One worker per CPU starves those children on busy hosts, so
diff --git a/cli/vitest.tmpdir.ts b/cli/vitest.tmpdir.ts
new file mode 100644
index 000000000..dafd7c799
--- /dev/null
+++ b/cli/vitest.tmpdir.ts
@@ -0,0 +1,24 @@
+/**
+ * A temporary folder for each Vitest worker, set before anything asks for one (vitest.setup.ts runs next).
+ *
+ * The native evidence readers hold a directory listing when any ancestor of the folder they list changes
+ * while they list it (engines/kit/nativeFiles.ts): an ancestor moved away and back around opendir looks
+ * exactly like that, so the hold is deliberate. Every spec's fixtures sit under os.tmpdir(). With one
+ * temporary folder for the whole run, any other worker's mkdtemp or rm there changed an ancestor of every
+ * fixture, and the listing a spec was waiting on came back held instead. On CI's Linux shards that failed
+ * 2 of 3 PR runs on 2026-10-11, in whichever spec was listing at the time: nativeInstall wrote no claim
+ * (ENOENT on claims/00000000.json), transcriptBindings and agentHandoff read "a binding directory or
+ * ancestor changed during enumeration". A worker runs its files one at a time, so a folder of its own
+ * changes only under the spec that is running.
+ *
+ * The name is short on purpose: vitest.setup.ts puts the daemon's data folder, which holds its Unix socket,
+ * in here, a socket's path has 96 bytes (lib/localSocket.ts), and macOS's temporary folder takes 48.
+ * The end-to-end suite runs one file at a time, with its own socket budget, and does not load this.
+ */
+import { mkdirSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+const folder = join(tmpdir(), `vw${process.env.VITEST_POOL_ID ?? process.pid}`)
+mkdirSync(folder, { recursive: true, mode: 0o700 })
+process.env.TMPDIR = folder