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.

15.6 KB
Raw Blame
// Hook files on real Windows (Phase B4): the path walk, the writers, the recognizers, and the lines run the way Claude
// Code, Codex, Command Code and Copilot run them. Windows only. It writes only below its own temporary folder, with
// explicit homes: os.homedir() is USERPROFILE there, which vitest.setup.ts does not redirect, so no engine default is
// written. No wall-clock bound: every wait ends on an event.
//   cd cli && npx vitest run src/lib/windows/hookFiles.real.spec.ts
import { execFileSync, spawnSync, type SpawnSyncReturns } from 'node:child_process'
import { closeSync, existsSync, mkdirSync, mkdtempSync, openSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { afterAll, afterEach, describe, expect, it, vi } from 'vitest'
import { hooks as codexContract } from '../../engines/codex/hookContract.js'
import { COMMANDCODE_HOOK_SETTINGS } from '../../engines/commandcode/contract.js'
import { COPILOT_HOOK_SETTINGS } from '../../engines/copilot/contract.js'
import { engineHooks } from '../../engines/hooks.js'
import { createHomeAdopter, readAdoptedHomes } from '../../engines/kit/homeAdoption.js'
import { NativeEvidenceBudget } from '../../engines/kit/nativeEvidence.js'
import { HookPreparationHeld, inspectHookFile, runHookPreparation } from '../../engines/kit/nativeHookFiles.js'
import { NativePaths } from '../../engines/kit/nativePaths.js'
import { HOOK_SCRIPT, hookArgv, isOurs, quoteHookCommand } from '../../engines/kit/notifyHooks.js'
import { installCommandCodeHooks, installCopilotHooks } from '../../engines/nativeHooks.js'

const enabled = process.platform === 'win32'
const root = enabled ? mkdtempSync(join(tmpdir(), 'hook-files-')) : ''
afterAll(() => { if (root) rmSync(root, { recursive: true, force: true }) })
afterEach(() => { vi.restoreAllMocks() })

const PORT = 19473
const stamp = (file: string) => { const info = statSync(file, { bigint: true }); return [readFileSync(file, 'utf8'), info.ino, info.mtimeNs] }
/** A profile folder under the temporary root, with a fake notify.mjs that prints its arguments (base64 JSON). */
function profile(name: string): { home: string; echo: string; environment: Record<string, string> } {
  const home = join(root, name), echo = join(home, 'echo notify.mjs')
  mkdirSync(home, { recursive: true })
  // Base64, so a console code page or PowerShell's re-encoding of a native program's output cannot change what is compared.
  writeFileSync(echo, "process.stdout.write(Buffer.from(JSON.stringify(process.argv.slice(2))).toString('base64'))\n")
  return { home, echo, environment: { HOME: home } }
}
/** What the program the line started got as its arguments. */
function delivered(result: SpawnSyncReturns<string>): string[] {
  expect(result.error).toBeUndefined()
  expect(result.status, result.stderr).toBe(0)
  return JSON.parse(Buffer.from(result.stdout.trim(), 'base64').toString('utf8'))
}
/** The installed line with notify.mjs swapped for the echo script; every other byte is the one the file holds. */
function withEcho(line: string, echo: string): string {
  expect(line.split(HOOK_SCRIPT)).toHaveLength(2)
  return line.replace(HOOK_SCRIPT, () => echo)
}
// Each engine's own way to run a hook line on Windows.
// Codex 0.162.1 (codex-rs): its Windows session shell, `powershell.exe -NoProfile -Command <line>`, the line one argument
// that Rust quotes as Node does (core/src/session/mod.rs `build_hooks_config`; seen on the VM in B4.15).
const codexRuns = (line: string) => spawnSync('powershell.exe', ['-NoProfile', '-Command', line], { encoding: 'utf8' })
// Codex prefers PowerShell 7 when it is installed (B4.15), `pwsh -NoProfile -Command <line>`. pwsh 7.3 and later pass
// a native program's arguments by their own rules ($PSNativeCommandArgumentPassing), so the same line is run there too.
// The VM has no pwsh; windows-latest has it.
const pwshInstalled = enabled && spawnSync('where.exe', ['pwsh'], { stdio: 'ignore' }).status === 0
const codexRunsPwsh = (line: string) => spawnSync('pwsh', ['-NoProfile', '-Command', line], { encoding: 'utf8' })
// Command Code: Node's spawn(line, { shell: true }), which is cmd.exe /d /s /c "<line>".
const commandCodeRuns = (line: string) => spawnSync(line, { shell: true, encoding: 'utf8' })
// Copilot CLI copies `command` to its `powershell` field and runs it in Windows PowerShell. Its exact flags are not
// documented; these are the ones a Node program passes to run a command line (assumption, B4.10 report).
const copilotRuns = (line: string) => spawnSync('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', line], { encoding: 'utf8' })

;(enabled ? describe : describe.skip)('hook files on Windows', () => {
  it('walks a drive path, and refuses a junction on the way rather than following it', () => {
    const real = join(root, 'real'), link = join(root, 'junction')
    mkdirSync(real)
    writeFileSync(join(real, 'settings.json'), '{}')
    execFileSync('cmd.exe', ['/d', '/c', 'mklink', '/J', link, real], { stdio: 'ignore' })
    try {
      expect(new NativePaths(new NativeEvidenceBudget()).resolveSync(join(real, 'settings.json'))?.path).toBe(join(real, 'settings.json'))
      expect(() => new NativePaths(new NativeEvidenceBudget()).resolveSync(join(link, 'settings.json'), true)).toThrow(/reparse point/)
    } finally { rmSync(link) } // the junction only, never what it points to
  })

  it('installs Claude Code exec form and a Codex line for PowerShell, and finds both current the second time', async () => {
    const log = vi.spyOn(console, 'log').mockImplementation(() => {})
    vi.spyOn(console, 'warn').mockImplementation(() => {})
    // An explicit profile, so no engine home of the real USERPROFILE is named in the lines.
    const { home, environment } = profile('defaults'), claudeHome = join(home, '.claude'), codexHome = join(home, '.codex')
    expect(await engineHooks.claude.installIn(PORT, claudeHome, { environment })).toBe(true)
    expect(await engineHooks.codex.installIn(PORT, codexHome, { environment })).toBe(true)
    const claude = JSON.parse(readFileSync(join(claudeHome, 'settings.json'), 'utf8'))
    const hook = claude.hooks.SessionStart[0].hooks[0]
    expect(hook.command).toMatch(/\\node\.exe$/i)
    expect(hook.args[0]).toMatch(/\\notify\.mjs$/)
    expect(isOurs({ hooks: [hook] })).toBe(true)
    // Agent Messages' block is a POSIX line and is not installed on Windows yet.
    expect(claude.hooks.PostToolUse).toBeUndefined()
    const codex = JSON.parse(readFileSync(join(codexHome, 'hooks.json'), 'utf8'))
    expect(codex.hooks.SessionStart[0].hooks[0].command).toMatch(new RegExp(`^& '[^']+node\\.exe' '[^']+notify\\.mjs' --port ${PORT} `, 'i'))
    expect(isOurs(codex.hooks.SessionStart[0])).toBe(true)
    // No ~\.grok, ~\.cursor, … of the person running the spec.
    const realHomes = `${process.env.USERPROFILE}\\.`
    expect([...hook.args, codex.hooks.SessionStart[0].hooks[0].command].filter((text: string) => text.includes(realHomes))).toEqual([])
    expect(readFileSync(join(codexHome, 'config.toml'), 'utf8')).toContain('trusted_hash')
    const files = [join(claudeHome, 'settings.json'), join(codexHome, 'hooks.json'), join(codexHome, 'config.toml')]
    const before = files.map(stamp)
    log.mockClear()
    expect(await engineHooks.claude.installIn(PORT, claudeHome, { environment })).toBe(true)
    expect(await engineHooks.codex.installIn(PORT, codexHome, { environment })).toBe(true)
    expect(files.map(stamp)).toEqual(before)
    expect(log).toHaveBeenCalledWith('[hooks] Claude session + turn (Stop/StopFailure) hooks already installed')
    expect(log).toHaveBeenCalledWith(codexContract.settings.messages.current.replace('{file}', join(codexHome, 'hooks.json')))
  })

  it('installs Copilot\'s PowerShell lines and Command Code\'s nested cmd.exe line, and leaves both alone the second time', async () => {
    const log = vi.spyOn(console, 'log').mockImplementation(() => {})
    const { home, environment } = profile('round trip')
    const copilot = join(home, '.copilot', 'hooks', 'harness.json'), commandCode = join(home, '.commandcode', 'settings.json')
    expect(await installCopilotHooks(PORT, { environment })).toBe(true)
    expect(await installCommandCodeHooks(PORT, { environment })).toBe(true)
    const powershell = quoteHookCommand('powershell', hookArgv(PORT, 'copilot', undefined, undefined, environment)) as string
    const cmd = quoteHookCommand('cmd', hookArgv(PORT, 'commandcode', undefined, undefined, environment)) as string
    expect(JSON.parse(readFileSync(copilot, 'utf8'))).toEqual({ version: 1, hooks: Object.fromEntries(COPILOT_HOOK_SETTINGS.events.map(event =>
      [event, [{ type: 'command', command: `${powershell} --copilot-event ${event}` }]])) })
    expect(JSON.parse(readFileSync(commandCode, 'utf8')).hooks).toEqual(Object.fromEntries(COMMANDCODE_HOOK_SETTINGS.events.map(event =>
      [event, [{ hooks: [{ type: 'command', command: cmd, timeout: COMMANDCODE_HOOK_SETTINGS.timeout }] }]])))
    const before = [stamp(copilot), stamp(commandCode)]
    log.mockClear()
    expect(await installCopilotHooks(PORT, { environment })).toBe(true)
    expect(await installCommandCodeHooks(PORT, { environment })).toBe(true)
    expect(log.mock.calls).toEqual([[COPILOT_HOOK_SETTINGS.messages.current], [COMMANDCODE_HOOK_SETTINGS.messages.current]])
    expect([stamp(copilot), stamp(commandCode)]).toEqual(before)
  })

  it('delivers every argument whole the way each engine runs its line, from a profile named Thảo Nguyễn', async () => {
    vi.spyOn(console, 'log').mockImplementation(() => {})
    vi.spyOn(console, 'warn').mockImplementation(() => {})
    const { home, echo, environment } = profile('Thảo Nguyễn')
    const homes = { claude: join(home, '.claude'), codex: join(home, '.codex') }
    expect(await engineHooks.claude.installIn(PORT, homes.claude, { environment })).toBe(true)
    expect(await engineHooks.codex.installIn(PORT, homes.codex, { environment })).toBe(true)
    expect(await installCommandCodeHooks(PORT, { environment })).toBe(true)
    expect(await installCopilotHooks(PORT, { environment })).toBe(true)
    const read = (file: string) => JSON.parse(readFileSync(join(home, file), 'utf8')).hooks
    const flags = (engine: 'claude' | 'codex' | 'commandcode' | 'copilot') => hookArgv(PORT, engine, engine === 'codex' ? homes.codex : undefined, undefined, environment).slice(2)
    expect(flags('codex')).toContain(homes.codex)

    // Claude Code exec form: the program and its arguments, no shell.
    const exec = read('.claude\\settings.json').SessionStart[0].hooks[0]
    expect(delivered(spawnSync(exec.command, exec.args.map((arg: string) => arg === HOOK_SCRIPT ? echo : arg), { encoding: 'utf8' }))).toEqual(flags('claude'))
    expect(delivered(codexRuns(withEcho(read('.codex\\hooks.json').SessionStart[0].hooks[0].command, echo)))).toEqual(flags('codex'))
    expect(delivered(commandCodeRuns(withEcho(read('.commandcode\\settings.json').SessionStart[0].hooks[0].command, echo)))).toEqual(flags('commandcode'))
    expect(delivered(copilotRuns(withEcho(read('.copilot\\hooks\\harness.json').sessionStart[0].command, echo))))
      .toEqual([...flags('copilot'), '--copilot-event', 'sessionStart'])
  }, 60_000) // a ceiling for the slow arm64 runner's process starts, not a timing assertion

  it('refuses a home with & ( ) for the cmd.exe engine with its reason, and the PowerShell engines pass it whole', async () => {
    vi.spyOn(console, 'log').mockImplementation(() => {})
    vi.spyOn(console, 'warn').mockImplementation(() => {})
    const error = vi.spyOn(console, 'error').mockImplementation(() => {})
    const { home, echo, environment } = profile('Thảo & co (1)')
    expect(await installCommandCodeHooks(PORT, { environment })).toBe(false)
    // One line, no stack.
    expect(error.mock.calls).toEqual([
      ['[hooks] Command Code hooks are not installed: a hook argument holds one of " % ! & | < > ^ ( ), which cmd.exe reads as more than text'],
    ])
    expect(existsSync(join(home, '.commandcode'))).toBe(false)
    // Inside PowerShell's single quotes these are text: Copilot's line, and Codex's.
    expect(await installCopilotHooks(PORT, { environment })).toBe(true)
    const line = JSON.parse(readFileSync(join(home, '.copilot', 'hooks', 'harness.json'), 'utf8')).hooks.agentStop[0].command
    expect(delivered(copilotRuns(withEcho(line, echo))))
      .toEqual([...hookArgv(PORT, 'copilot', undefined, undefined, environment).slice(2), '--copilot-event', 'agentStop'])
    const codexHome = join(home, '.codex')
    expect(await engineHooks.codex.installIn(PORT, codexHome, { environment })).toBe(true)
    const codexLine = JSON.parse(readFileSync(join(codexHome, 'hooks.json'), 'utf8')).hooks.SessionStart[0].hooks[0].command
    expect(delivered(codexRuns(withEcho(codexLine, echo)))).toEqual(hookArgv(PORT, 'codex', codexHome, undefined, environment).slice(2))
  }, 60_000)

  it.skipIf(!pwshInstalled)('delivers every argument of the Codex line whole under pwsh 7, from a profile named Thảo & co (1)', async () => {
    vi.spyOn(console, 'log').mockImplementation(() => {})
    vi.spyOn(console, 'warn').mockImplementation(() => {})
    const { home, echo, environment } = profile('pwsh Thảo & co (1)')
    const codexHome = join(home, '.codex')
    expect(await engineHooks.codex.installIn(PORT, codexHome, { environment })).toBe(true)
    const line = JSON.parse(readFileSync(join(codexHome, 'hooks.json'), 'utf8')).hooks.SessionStart[0].hooks[0].command
    expect(delivered(codexRunsPwsh(withEcho(line, echo)))).toEqual(hookArgv(PORT, 'codex', codexHome, undefined, environment).slice(2))
  }, 60_000)

  it('replaces a settings file another handle holds open once it lets go, and keeps it whole while it does not', async () => {
    mkdirSync(join(root, 'held'))
    const file = join(root, 'held', 'settings.json'), leftovers = () => readdirSync(join(root, 'held')).filter(name => name.endsWith('.tmp'))
    writeFileSync(file, '{}\n')
    // An open handle, as an engine reading its settings has. Observed on the VM: a rename over an open handle fails
    // (EPERM on Windows 11), from another process or this one, until it closes.
    let held: number | null = openSync(file, 'r')
    try {
      // Still held after every try: the reason, not the errno (any of EPERM, EACCES, EBUSY can be the last one).
      await expect(runHookPreparation([file], async (attempt) => (await inspectHookFile(file).replace('{"held":true}\n', attempt)).verify()))
        .rejects.toThrow(new HookPreparationHeld('the settings file is open in another program'))
      expect([readFileSync(file, 'utf8'), leftovers()]).toEqual(['{}\n', []])
      // Let go at the first retry: verify runs once before the rename after the flush, and again before each retry.
      let flushed = false, checks = 0, released = false
      await runHookPreparation([file], async (attempt) => {
        const watched = {
          ...attempt,
          flush: async (fd: number) => { await attempt.flush(fd); flushed = true },
          verify: () => { attempt.verify(); if (flushed && ++checks === 2 && held !== null) { closeSync(held); held = null; released = true } },
        }
        return (await inspectHookFile(file).replace('{"ok":true}\n', watched)).verify()
      })
      expect(released).toBe(true)
      expect([readFileSync(file, 'utf8'), leftovers()]).toEqual(['{"ok":true}\n', []])
    } finally { if (held !== null) closeSync(held) }
  }, 60_000)

  it('adopts a moved Claude Code home with a Windows path', () => {
    const file = join(root, 'engine-homes.json'), home = join(root, 'claude-work')
    expect(createHomeAdopter(file).adopt({ claude: [home], codex: [] }).claude).toContain(home)
    expect(readAdoptedHomes(file).homes.claude).toContain(home)
  })
})