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.

20.7 KB
Raw Blame
import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs'
import { tmpdir } from 'node:os'
import { dirname, join } from 'node:path'
import { afterEach, describe, expect, it, vi } from 'vitest'
import { parse as parseYaml } from 'yaml'
import { AGY_HOOK_SETTINGS } from '../agy/contract.js'
import { hooks as claude } from '../claude/hookContract.js'
import { hooks as codex } from '../codex/hookContract.js'
import { COMMANDCODE_HOOK_SETTINGS } from '../commandcode/contract.js'
import { COPILOT_HOOK_SETTINGS } from '../copilot/contract.js'
import { CURSOR_HOOK_SETTINGS } from '../cursor/contract.js'
import { DEVIN_HOOK_SETTINGS } from '../devin/contract.js'
import { GROK_HOOK_SETTINGS } from '../grok/contract.js'
import { managedNodePath } from '../../lib/nodeRuntime.js'
import { installHermesHooks } from '../nativeHooks.js'
import { installHookSettings, notifyHookEntry } from './hookSettings.js'
import { HookPreparationHeld } from './nativeHookFiles.js'
import { installNativeHookSettings } from './nativeHookSettings.js'
import { hookArgv, hookScriptCandidates, identitySettings, quoteHookCommand } from './notifyHooks.js'

const dirs: string[] = []
afterEach(() => { vi.restoreAllMocks(); for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true }) })
const argv = ['C:\\h\\node.exe', 'C:\\h\\cli\\notify.mjs', '--port', '18473', '--data-dir', 'C:\\h\\cli\\data']

describe('the hook each engine runs on Windows', () => {
  it('is declared for every engine whose hooks Harness installs there, and for no other', () => {
    expect(claude.settings.win32Runner).toBe('argv')
    expect(codex.settings.win32Runner).toBe('powershell')
    expect(COPILOT_HOOK_SETTINGS.win32Runner).toBe('powershell')
    expect(COMMANDCODE_HOOK_SETTINGS.win32Runner).toBe('cmd')
    for (const rule of [CURSOR_HOOK_SETTINGS, DEVIN_HOOK_SETTINGS, GROK_HOOK_SETTINGS, AGY_HOOK_SETTINGS]) expect('win32Runner' in rule).toBe(false)
  })

  it('writes Claude Code exec form on Windows: node.exe and its arguments, no shell', () => {
    expect(notifyHookEntry(claude.settings, argv, 'win32')).toEqual({ command: argv[0], args: argv.slice(1) })
  })

  // Codex 0.162.1 runs a hook in the session's shell, which on Windows is PowerShell: `powershell.exe -NoProfile -Command
  // <line>` (codex-rs core/src/session/mod.rs `build_hooks_config`, shell-command/src/shell_detect.rs). A line quoted for
  // cmd.exe is a PowerShell parse error there, and every hook exited 1 (B4.15, the Windows VM).
  it('writes Codex a line PowerShell reads', () => {
    expect(notifyHookEntry(codex.settings, argv, 'win32'))
      .toEqual({ command: "& 'C:\\h\\node.exe' 'C:\\h\\cli\\notify.mjs' --port 18473 --data-dir 'C:\\h\\cli\\data'" })
  })

  it('keeps the POSIX line for both off Windows', () => {
    const posix = ['/h/node', '/h/notify.mjs', '--port', '1']
    expect(notifyHookEntry(claude.settings, posix, 'darwin')).toEqual({ command: "'/h/node' '/h/notify.mjs' --port 1" })
    expect(notifyHookEntry(codex.settings, posix, 'linux')).toEqual({ command: "'/h/node' '/h/notify.mjs' --port 1" })
  })

  it('installs nothing for an engine with no Windows runner, and says so', async () => {
    const dir = mkdtempSync(join(tmpdir(), 'win-hooks-')); dirs.push(dir)
    const log = vi.spyOn(console, 'log').mockImplementation(() => {})
    expect(await installNativeHookSettings({ ...GROK_HOOK_SETTINGS, file: join(dir, 'grok', 'hooks', 'harness.json') }, 19473, {}, 'win32')).toBe(true)
    expect(existsSync(join(dir, 'grok'))).toBe(false)
    expect(log).toHaveBeenCalledWith('[hooks] grok hooks are not installed on Windows yet')
  })
})

describe('a hook preparation\'s identity', () => {
  // installHookSettings and installNativeHookSettings name a preparation by JSON.stringify of the settings, among
  // others. Off Windows that string must be byte for byte what it was before win32Runner existed (mac/Linux unchanged).
  it('is the settings without win32Runner off Windows, byte for byte, and the whole declaration on Windows', () => {
    const { win32Runner: _claude, ...claudeBefore } = claude.settings
    const { win32Runner: _copilot, ...copilotBefore } = COPILOT_HOOK_SETTINGS
    expect(JSON.stringify(identitySettings(claude.settings, 'darwin'))).toBe(JSON.stringify(claudeBefore))
    expect(JSON.stringify(identitySettings(codex.settings, 'linux'))).not.toContain('win32Runner')
    expect(JSON.stringify(identitySettings(COPILOT_HOOK_SETTINGS, 'darwin'))).toBe(JSON.stringify(copilotBefore))
    expect(JSON.stringify(identitySettings(CURSOR_HOOK_SETTINGS, 'darwin'))).toBe(JSON.stringify(CURSOR_HOOK_SETTINGS))
    expect(identitySettings(COPILOT_HOOK_SETTINGS, 'win32')).toBe(COPILOT_HOOK_SETTINGS)
    expect(JSON.stringify(identitySettings(claude.settings, 'win32'))).toContain('"win32Runner":"argv"')
  })
})

describe('the notify.mjs a hook line names', () => {
  const root = 'C:\\Users\\u\\.harness\\cli'
  it('is the stable cli\\notify.mjs when the CLI runs from its Windows install', () => {
    expect(hookScriptCandidates(`${root}\\0.5.0`, `${root}\\0.5.0\\cli.js`, 'win32', root)[0]).toBe(`${root}\\notify.mjs`)
  })
  it('is the sibling for a CLI run from anywhere else, and always off Windows', () => {
    expect(hookScriptCandidates('C:\\work\\e2e\\dist', 'C:\\work\\e2e\\dist\\cli.js', 'win32', root)[0]).toBe(join('C:\\work\\e2e\\dist', 'notify.mjs'))
    expect(hookScriptCandidates('/Users/u/.harness/cli', '/Users/u/.harness/cli/cli.js', 'darwin', '/Users/u/.harness/cli'))
      // join, not literals: on a Windows host the path module writes backslashes, whatever platform is asked about.
      .toEqual([join('/Users/u/.harness/cli', 'notify.mjs'), join('/Users/u/.harness/cli', 'notify.mjs'), join('/Users/u/.harness/cli', '..', '..', '..', 'hook', 'notify.mjs')])
  })
})

// B4.1 review: a hook line a runner would misread is refused (quoteHookCommand). That refusal is an install that
// failed, logged with its reason like any other, never a rejected promise the daemon reports with a stack trace.
describe('a hook argument the Windows runner refuses', () => {
  it('fails the install with its reason for PowerShell (Codex): a typographic quote in the home it names', async () => {
    const dir = mkdtempSync(join(tmpdir(), 'win-hooks-')); dirs.push(dir)
    const home = join(dir, 'co\u2019dex')
    const error = vi.spyOn(console, 'error').mockImplementation(() => {})
    vi.spyOn(console, 'log').mockImplementation(() => {})
    expect(await installHookSettings('codex', codex.settings, 19473, home, {}, 'win32')).toBe(false)
    // One line, no stack (B4.10 review).
    expect(error.mock.calls).toEqual([['[hooks] Codex hooks are not installed: a hook argument holds a double or typographic quote, which PowerShell passes on differently']])
    expect(existsSync(home)).toBe(false)
  })

  it('fails the install with its reason for PowerShell (Copilot): a typographic quote in its home', async () => {
    const dir = mkdtempSync(join(tmpdir(), 'win-hooks-')); dirs.push(dir)
    const copilotHome = join(dir, 'O\u2019Brien')
    const error = vi.spyOn(console, 'error').mockImplementation(() => {})
    vi.spyOn(console, 'log').mockImplementation(() => {})
    const rule = { ...COPILOT_HOOK_SETTINGS, file: join(copilotHome, 'hooks', 'harness.json') }
    expect(await installNativeHookSettings(rule, 19473, { environment: { HOME: dir, COPILOT_HOME: copilotHome } }, 'win32')).toBe(false)
    expect(error.mock.calls).toEqual([['[hooks] Copilot hooks are not installed: a hook argument holds a double or typographic quote, which PowerShell passes on differently']])
    expect(existsSync(copilotHome)).toBe(false)
  })

  // Any held preparation is one line on Windows; off Windows the log is what it always was: the failure line and the error.
  it('is one line on Windows for any held install, and the failure line with its error off Windows', async () => {
    const dir = mkdtempSync(join(tmpdir(), 'win-hooks-')); dirs.push(dir)
    const error = vi.spyOn(console, 'error').mockImplementation(() => {})
    vi.spyOn(console, 'log').mockImplementation(() => {})
    const claudeHome = join(dir, 'claude'), rule = { ...COMMANDCODE_HOOK_SETTINGS, file: join(dir, 'commandcode', 'settings.json') }
    for (const file of [join(claudeHome, claude.settings.file), rule.file]) {
      mkdirSync(dirname(file), { recursive: true }); writeFileSync(file, '{"hooks":[]}\n')
    }
    expect(await installHookSettings('claude', claude.settings, 19473, claudeHome, {}, 'win32')).toBe(false)
    expect(await installNativeHookSettings(rule, 19473, {}, 'win32')).toBe(false)
    expect(error.mock.calls).toEqual([
      ['[hooks] Claude Code hooks are not installed: the hook settings do not have the declared object shape'],
      ['[hooks] Command Code hooks are not installed: the hooks member is not an object'],
    ])
    error.mockClear()
    expect(await installHookSettings('claude', claude.settings, 19473, claudeHome, {}, 'linux')).toBe(false)
    expect(await installNativeHookSettings(rule, 19473, {}, 'linux')).toBe(false)
    expect(error.mock.calls.map(([line, reason]) => [line, (reason as Error).message])).toEqual([
      [claude.settings.messages.failed, 'Hook preparation is waiting: the hook settings do not have the declared object shape'],
      [COMMANDCODE_HOOK_SETTINGS.messages.failed, 'Hook preparation is waiting: the hooks member is not an object'],
    ])
    expect(error.mock.calls.every(([, reason]) => reason instanceof HookPreparationHeld)).toBe(true)
  })
})

// B4.2 review: exec form keeps its arguments in `args`. A drift check that compared `command` alone saw every exec-form
// hook as current, whatever its port; one that compared the line saw none, and rewrote the file at every start.
describe('Claude Code\'s exec-form hook already in place', () => {
  it('is left alone: a second install writes nothing and says it is current', async () => {
    const dir = mkdtempSync(join(tmpdir(), 'win-hooks-')); dirs.push(dir)
    const home = join(dir, 'claude'), file = join(home, claude.settings.file)
    const log = vi.spyOn(console, 'log').mockImplementation(() => {})
    expect(await installHookSettings('claude', claude.settings, 19473, home, {}, 'win32')).toBe(true)
    const written = readFileSync(file, 'utf8'), before = statSync(file, { bigint: true })
    const hook = JSON.parse(written).hooks.Stop[0].hooks[0]
    expect(hook.args).toEqual(expect.arrayContaining(['--port', '19473']))
    expect(hook.command).toBe(managedNodePath())
    log.mockClear()
    expect(await installHookSettings('claude', claude.settings, 19473, home, {}, 'win32')).toBe(true)
    expect(log.mock.calls.map(([line]) => line)).toEqual([claude.settings.messages.current])
    const after = statSync(file, { bigint: true })
    expect(readFileSync(file, 'utf8')).toBe(written)
    expect([after.ino, after.mtimeNs]).toEqual([before.ino, before.mtimeNs])
  })

  it('is rewritten when only its arguments changed (another port)', async () => {
    const dir = mkdtempSync(join(tmpdir(), 'win-hooks-')); dirs.push(dir)
    const home = join(dir, 'claude'), file = join(home, claude.settings.file)
    const log = vi.spyOn(console, 'log').mockImplementation(() => {})
    expect(await installHookSettings('claude', claude.settings, 19473, home, {}, 'win32')).toBe(true)
    log.mockClear()
    expect(await installHookSettings('claude', claude.settings, 19474, home, {}, 'win32')).toBe(true)
    expect(log.mock.calls[0]![0]).toMatch(/^\[hooks\] updated/)
    const events = JSON.parse(readFileSync(file, 'utf8')).hooks as Record<string, Array<{ hooks: Array<{ args: string[] }> }>>
    for (const blocks of Object.values(events)) {
      expect(blocks).toHaveLength(1)
      expect(blocks[0]!.hooks[0]!.args).toEqual(expect.arrayContaining(['--port', '19474']))
    }
  })
})

// The B3.21 VM log: every start printed a stack trace for each of these engines' files. With no runner verified
// there, each is one line, and nothing is an error.
describe('an engine with no hooks on Windows', () => {
  it.each([CURSOR_HOOK_SETTINGS, DEVIN_HOOK_SETTINGS, GROK_HOOK_SETTINGS, AGY_HOOK_SETTINGS])('logs one line for $engine, no error', async (rule) => {
    const dir = mkdtempSync(join(tmpdir(), 'win-hooks-')); dirs.push(dir)
    const log = vi.spyOn(console, 'log').mockImplementation(() => {})
    const error = vi.spyOn(console, 'error').mockImplementation(() => {})
    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
    expect(await installNativeHookSettings({ ...rule, file: join(dir, 'x', 'hooks.json') }, 19473, {}, 'win32')).toBe(true)
    expect(log.mock.calls).toEqual([[`[hooks] ${rule.engine} hooks are not installed on Windows yet`]])
    expect(error).not.toHaveBeenCalled(); expect(warn).not.toHaveBeenCalled()
    expect(existsSync(join(dir, 'x'))).toBe(false)
  })

  // Hermes starts the program itself, from `shlex.split(posix=False)` of the line: double quotes hold a word, backslashes stay.
  it('writes Hermes a line it splits into the program and its arguments', async () => {
    const dir = mkdtempSync(join(tmpdir(), 'win-hooks-')); dirs.push(dir)
    const home = join(dir, 'hermes')
    mkdirSync(home)
    writeFileSync(join(home, 'config.yaml'), 'model: x\n')
    vi.spyOn(console, 'log').mockImplementation(() => {})
    expect(await installHermesHooks(19473, home, {}, 'win32')).toBe(true)
    const written = parseYaml(readFileSync(join(home, 'config.yaml'), 'utf8')) as { hooks: { on_session_start: Array<{ command: string }> } }
    const line = written.hooks.on_session_start[0]!.command
    expect(line).toContain(`"${managedNodePath()}"`)
    expect(line).toContain('--engine hermes')
    expect(line).not.toContain("'")
    // Approved by the exact line, or Hermes skips the hook.
    const approvals = JSON.parse(readFileSync(join(home, 'shell-hooks-allowlist.json'), 'utf8')) as { approvals: Array<{ command: string }> }
    expect(approvals.approvals.map((approval) => approval.command)).toContain(line)
  })
})

// Fix round 1 of the B4.6 review: an install that succeeds on Windows, and is then left alone.
describe('Codex\'s PowerShell hook on Windows', () => {
  it('is written as the line PowerShell reads, and a second install writes nothing', async () => {
    const dir = mkdtempSync(join(tmpdir(), 'win-hooks-')); dirs.push(dir)
    const home = join(dir, 'codex'), file = join(home, codex.settings.file), config = join(home, codex.settings.reviewed!.file)
    const log = vi.spyOn(console, 'log').mockImplementation(() => {})
    vi.spyOn(console, 'warn').mockImplementation(() => {})
    expect(await installHookSettings('codex', codex.settings, 19473, home, {}, 'win32')).toBe(true)
    const line = notifyHookEntry(codex.settings, hookArgv(19473, 'codex', home), 'win32')!
    expect(line.args).toBeUndefined()
    const events = JSON.parse(readFileSync(file, 'utf8')).hooks as Record<string, Array<{ hooks: Array<{ command: string; args?: string[] }> }>>
    expect(Object.keys(events)).toEqual(codex.settings.events.map(({ event }) => event))
    for (const blocks of Object.values(events)) expect(blocks.map(block => block.hooks)).toEqual([[expect.objectContaining({ command: line.command })]])
    expect(JSON.stringify(events)).not.toContain('"args"')
    const stamp = (path: string) => { const info = statSync(path, { bigint: true }); return [readFileSync(path, 'utf8'), info.ino, info.mtimeNs] }
    const before = [stamp(file), stamp(config)]
    log.mockClear()
    expect(await installHookSettings('codex', codex.settings, 19473, home, {}, 'win32')).toBe(true)
    expect(log.mock.calls[0]![0]).toBe(codex.settings.messages.current.replace('{file}', file))
    expect([stamp(file), stamp(config)]).toEqual(before)
  })
})

// B4.10 (the B4.6 carries): the Copilot (PowerShell) and Command Code (cmd.exe, nested schema) installs that succeed on
// Windows, and are then left alone. hookFiles.real.spec.ts runs the same round trips on NTFS.
describe('Copilot\'s PowerShell and Command Code\'s cmd.exe hooks on Windows', () => {
  const stamp = (path: string) => { const info = statSync(path, { bigint: true }); return [readFileSync(path, 'utf8'), info.ino, info.mtimeNs] }

  it('writes Copilot a PowerShell line per event, and a second install writes nothing', async () => {
    const dir = mkdtempSync(join(tmpdir(), 'win-hooks-')); dirs.push(dir)
    const rule = { ...COPILOT_HOOK_SETTINGS, file: join(dir, 'copilot', 'hooks', 'harness.json') }
    const log = vi.spyOn(console, 'log').mockImplementation(() => {})
    expect(await installNativeHookSettings(rule, 19473, {}, 'win32')).toBe(true)
    const line = quoteHookCommand('powershell', hookArgv(19473, 'copilot')) as string
    expect(line.startsWith('& ')).toBe(true)
    expect(JSON.parse(readFileSync(rule.file, 'utf8'))).toEqual({ version: 1, hooks: Object.fromEntries(COPILOT_HOOK_SETTINGS.events.map(event =>
      [event, [{ type: 'command', command: `${line} --copilot-event ${event}` }]])) })
    const before = stamp(rule.file)
    log.mockClear()
    expect(await installNativeHookSettings(rule, 19473, {}, 'win32')).toBe(true)
    expect(log.mock.calls).toEqual([[COPILOT_HOOK_SETTINGS.messages.current]])
    expect(stamp(rule.file)).toEqual(before)
  })

  it('writes Command Code one cmd.exe line in each nested block, and a second install writes nothing', async () => {
    const dir = mkdtempSync(join(tmpdir(), 'win-hooks-')); dirs.push(dir)
    const rule = { ...COMMANDCODE_HOOK_SETTINGS, file: join(dir, 'commandcode', 'settings.json') }
    const log = vi.spyOn(console, 'log').mockImplementation(() => {})
    expect(await installNativeHookSettings(rule, 19473, {}, 'win32')).toBe(true)
    const line = quoteHookCommand('cmd', hookArgv(19473, 'commandcode')) as string
    expect(line.startsWith('"')).toBe(true)
    expect(JSON.parse(readFileSync(rule.file, 'utf8')).hooks).toEqual(Object.fromEntries(COMMANDCODE_HOOK_SETTINGS.events.map(event =>
      [event, [{ hooks: [{ type: 'command', command: line, timeout: COMMANDCODE_HOOK_SETTINGS.timeout }] }]])))
    const before = stamp(rule.file)
    log.mockClear()
    expect(await installNativeHookSettings(rule, 19473, {}, 'win32')).toBe(true)
    expect(log.mock.calls).toEqual([[COMMANDCODE_HOOK_SETTINGS.messages.current]])
    expect(stamp(rule.file)).toEqual(before)
  })
})

// Fix round 1 of the B4.6 review: mac and Linux do not change. Off Windows the line alone decides whether a hook of
// ours is current, as before Windows hooks: a stray `args` beside it is not drift there, and nothing is written.
// Off Windows only: on a Windows host the POSIX line these write holds drive paths, which is no line of Harness's there
// (carried B4.2, final review R2-1), so faking 'linux' on Windows would not install what macOS and Linux do.
describe.skipIf(process.platform === 'win32')('a hook of ours with a stray args key, off Windows', () => {
  const stray = (file: string) => {
    const settings = JSON.parse(readFileSync(file, 'utf8')) as { hooks: Record<string, Array<{ hooks: Array<{ command: string; args?: string[] }> }>> }
    for (const blocks of Object.values(settings.hooks)) for (const block of blocks) for (const hook of block.hooks) {
      if (hook.command.includes('notify.mjs')) hook.args = ['stray']
    }
    writeFileSync(file, JSON.stringify(settings, null, 2) + '\n')
  }
  const stamp = (path: string) => { const info = statSync(path, { bigint: true }); return [readFileSync(path, 'utf8'), info.ino, info.mtimeNs] }

  it('is current for Claude Code: no write', async () => {
    const dir = mkdtempSync(join(tmpdir(), 'win-hooks-')); dirs.push(dir)
    const home = join(dir, 'claude'), file = join(home, claude.settings.file)
    const log = vi.spyOn(console, 'log').mockImplementation(() => {})
    vi.spyOn(console, 'warn').mockImplementation(() => {})
    expect(await installHookSettings('claude', claude.settings, 19473, home, {}, 'linux')).toBe(true)
    stray(file)
    expect(readFileSync(file, 'utf8')).toContain('"stray"')
    const before = stamp(file)
    log.mockClear()
    expect(await installHookSettings('claude', claude.settings, 19473, home, {}, 'linux')).toBe(true)
    expect(log.mock.calls.map(([line]) => line)).toContain(claude.settings.messages.current)
    expect(stamp(file)).toEqual(before)
  })

  it('is current for Command Code\'s nested settings: no write', async () => {
    const dir = mkdtempSync(join(tmpdir(), 'win-hooks-')); dirs.push(dir)
    const rule = { ...COMMANDCODE_HOOK_SETTINGS, file: join(dir, 'commandcode', 'settings.json') }
    const log = vi.spyOn(console, 'log').mockImplementation(() => {})
    expect(await installNativeHookSettings(rule, 19473, {}, 'linux')).toBe(true)
    stray(rule.file)
    expect(readFileSync(rule.file, 'utf8')).toContain('"stray"')
    const before = stamp(rule.file)
    log.mockClear()
    expect(await installNativeHookSettings(rule, 19473, {}, 'linux')).toBe(true)
    expect(log.mock.calls).toEqual([[COMMANDCODE_HOOK_SETTINGS.messages.current]])
    expect(stamp(rule.file)).toEqual(before)
  })
})