orca/src/main/codex/codex-app-server-client.test.ts

import { EventEmitter } from 'node:events'
import type { ChildProcess, spawn } from 'node:child_process'
import { afterEach, describe, expect, it, vi, type TestContext } from 'vitest'
import { mkdtempSync, readFileSync, rmSync, writeFileSync, existsSync } from 'node:fs'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import {
  CodexAppServerTimeoutError,
  CodexAppServerUnsupportedError,
  isCodexAppServerUnsupportedError,
  runCodexHookTrustGrantSession,
  type CodexHookTrustGrantRequest
} from './codex-app-server-client'
import { killCodexAppServerProcessTree } from './codex-app-server-process-tree-kill'
import {
  PROVIDER_SIGTERM_GRACE_MS,
  PROVIDER_SUPERVISOR_MAX_STOP_MS
} from '../provider-process/provider-process-supervisor'
import { runCodexAppServerSession } from './codex-app-server-session'

// The orphan guard's process reads add timers of their own; the timer audit below is the session's.
vi.mock('../provider-process/provider-group-orphan-guard', () => ({
  guardSupervisedProviderGroup: () => false
}))

const STUB_SERVER_SOURCE = `
const config = JSON.parse(process.env.STUB_CONFIG)
// A wedged server ignores SIGTERM and its stdin end, so only SIGKILL ends it.
if (config.scenario === 'wedged') {
  process.on('SIGTERM', () => {})
  setInterval(() => {}, 60000)
}
require('node:fs').writeFileSync(config.pidFile, String(process.pid))
const trusted = new Set(config.hooks.filter(h => h.trustStatus === 'trusted').map(h => h.key))
let buffer = ''
function send(message) {
  const serialized = Buffer.from(JSON.stringify(message) + '\\n')
  if (config.scenario === 'split-unicode') {
    const marker = Buffer.from('é')
    const markerIndex = serialized.indexOf(marker)
    if (markerIndex !== -1) {
      process.stdout.write(serialized.subarray(0, markerIndex + 1))
      setTimeout(() => process.stdout.write(serialized.subarray(markerIndex + 1)), 5)
      return
    }
  }
  process.stdout.write(serialized)
}
function listing() {
  return {
    data: [{
      cwd: config.cwd,
      hooks: config.hooks.map(h => ({ ...h, trustStatus: trusted.has(h.key) ? 'trusted' : h.trustStatus })),
      warnings: [],
      errors: []
    }]
  }
}
if (config.scenario === 'no-subcommand') {
  process.stderr.write("error: unrecognized subcommand 'app-server'\\n")
  process.exit(2)
}
if (config.scenario === 'transient-stderr') {
  process.stderr.write('config loader: unexpected argument in value\\n')
  process.exit(1)
}
if (config.scenario === 'silent-exit-0') process.exit(0)
process.stdin.setEncoding('utf8')
process.stdin.on('data', (chunk) => {
  buffer += chunk
  let index
  while ((index = buffer.indexOf('\\n')) !== -1) {
    const line = buffer.slice(0, index).trim()
    buffer = buffer.slice(index + 1)
    if (!line) continue
    const message = JSON.parse(line)
    if (message.method === 'initialize') {
      send({ id: message.id, result: { userAgent: 'stub/0.0.0' } })
      continue
    }
    if (message.method === 'initialized') continue
    if (config.scenario === 'hang' || config.scenario === 'wedged') continue
    if (message.method === 'hooks/list') {
      if (config.scenario === 'unknown-method') {
        send({ id: message.id, error: { code: -32601, message: 'Method not found' } })
        continue
      }
      send({ id: message.id, result: listing() })
      continue
    }
    if (message.method === 'config/batchWrite') {
      if (config.scenario === 'reject-write') {
        process.exit(9)
      }
      writeFileSyncSafe(config.recordFile, JSON.stringify(message.params))
      for (const key of Object.keys(message.params.edits[0].value)) trusted.add(key)
      send({ id: message.id, result: { status: 'ok', version: 'v1', filePath: config.cwd + '/config.toml' } })
      continue
    }
  }
})
process.stdin.on('end', () => { if (config.scenario !== 'wedged') process.exit(0) })
function writeFileSyncSafe(file, contents) { require('node:fs').writeFileSync(file, contents) }
`

let tempRoots: string[] = []

afterEach(() => {
  vi.restoreAllMocks()
  for (const root of tempRoots) {
    rmSync(root, { recursive: true, force: true })
  }
  tempRoots = []
})

type StubHook = {
  key: string
  command: string | null
  currentHash: string
  trustStatus: string
}

function createStubRequest(
  options: {
    scenario: string
    hooks: StubHook[]
    expectedTrustKeys: string[]
    managedCommand: string
    timeoutMs?: number
  },
  onTestFinished?: TestContext['onTestFinished']
): { request: CodexHookTrustGrantRequest; recordFile: string; pidFile: string } {
  const root = mkdtempSync(join(tmpdir(), 'orca-codex-stub-'))
  if (onTestFinished) {
    onTestFinished(() => rmSync(root, { recursive: true, force: true }))
  } else {
    tempRoots.push(root)
  }
  const stubPath = join(root, 'stub-app-server.cjs')
  writeFileSync(stubPath, STUB_SERVER_SOURCE)
  const recordFile = join(root, 'batch-write-params.json')
  const pidFile = join(root, 'app-server.pid')
  return {
    recordFile,
    pidFile,
    request: {
      invocation: {
        command: process.execPath,
        cliPath: null,
        args: [stubPath],
        env: {
          STUB_CONFIG: JSON.stringify({
            scenario: options.scenario,
            hooks: options.hooks,
            cwd: root,
            recordFile,
            pidFile
          })
        },
        timeoutMs: options.timeoutMs ?? 10_000
      },
      hooksListCwd: root,
      expectedTrustKeys: options.expectedTrustKeys,
      managedCommand: options.managedCommand
    }
  }
}

const MANAGED_COMMAND = "/bin/sh '/tmp/orca/codex-hook.sh'"
// Allow loaded hosts to start the supervisor and stub before the spawn-time deadline expires.
const STUB_START_DEADLINE_MS = 8_000

function managedHook(key: string, trustStatus = 'untrusted'): StubHook {
  return { key, command: MANAGED_COMMAND, currentHash: `sha256:hash-of-${key}`, trustStatus }
}

describe('killCodexAppServerProcessTree', () => {
  it('kills the Windows wrapper and all app-server descendants', () => {
    const child = {
      pid: 1234,
      kill: vi.fn(() => true) as ChildProcess['kill']
    }
    const killer = new EventEmitter() as EventEmitter & { unref: ReturnType<typeof vi.fn> }
    killer.unref = vi.fn()
    const spawnImpl = vi.fn(() => killer) as unknown as typeof spawn

    killCodexAppServerProcessTree(child, { platform: 'win32', spawnImpl })

    expect(spawnImpl).toHaveBeenCalledWith('taskkill', ['/pid', '1234', '/t', '/f'], {
      stdio: 'ignore',
      windowsHide: true
    })
    expect(killer.unref).toHaveBeenCalledOnce()
    expect(child.kill).not.toHaveBeenCalled()

    killer.emit('error', new Error('taskkill unavailable'))
    expect(child.kill).toHaveBeenCalledWith('SIGKILL')
  })

  it('falls back when taskkill starts but cannot terminate the process tree', () => {
    const child = {
      pid: 1234,
      kill: vi.fn(() => true) as ChildProcess['kill']
    }
    const killer = new EventEmitter() as EventEmitter & { unref: ReturnType<typeof vi.fn> }
    killer.unref = vi.fn()
    const spawnImpl = vi.fn(() => killer) as unknown as typeof spawn

    killCodexAppServerProcessTree(child, { platform: 'win32', spawnImpl })
    killer.emit('exit', 1)

    expect(child.kill).toHaveBeenCalledWith('SIGKILL')
  })

  it('kills the launcher descendants before the direct process on non-Windows hosts', () => {
    const child = {
      pid: 1234,
      kill: vi.fn(() => true) as ChildProcess['kill']
    }
    const descendants = { unref: vi.fn(), on: vi.fn() }
    const spawnImpl = vi.fn(() => descendants) as unknown as typeof spawn

    killCodexAppServerProcessTree(child, { platform: 'linux', spawnImpl })

    expect(spawnImpl).toHaveBeenCalledWith('pkill', ['-KILL', '-P', '1234'], { stdio: 'ignore' })
    // Missing pkill emits an async error that must not crash the main process.
    expect(descendants.on).toHaveBeenCalledWith('error', expect.any(Function))
    expect(descendants.unref).toHaveBeenCalledOnce()
    expect(child.kill).toHaveBeenCalledWith('SIGKILL')
  })
})

describe('runCodexHookTrustGrantSession', () => {
  it('grants and verifies exactly the expected managed entries', async () => {
    const setTimeoutSpy = vi.spyOn(globalThis, 'setTimeout')
    const clearTimeoutSpy = vi.spyOn(globalThis, 'clearTimeout')
    const keys = [
      '/home/a/.codex/hooks.json:session_start:0:0',
      '/home/a/.codex/hooks.json:stop:0:0'
    ]
    const userHook: StubHook = {
      key: '/home/a/.codex/hooks.json:stop:1:0',
      command: 'echo user-hook',
      currentHash: 'sha256:user-hash',
      trustStatus: 'untrusted'
    }
    const { request, recordFile } = createStubRequest({
      scenario: 'happy',
      hooks: [...keys.map((key) => managedHook(key)), userHook],
      expectedTrustKeys: keys,
      managedCommand: MANAGED_COMMAND
    })

    const result = await runCodexHookTrustGrantSession(request)
    expect(result.outcome).toBe('granted')
    if (result.outcome !== 'granted') {
      return
    }
    expect(result.wroteTrust).toBe(true)
    expect(result.entries.map((entry) => entry.key).sort()).toEqual([...keys].sort())
    expect(result.entries.map((entry) => entry.trustedHash).sort()).toEqual(
      keys.map((key) => `sha256:hash-of-${key}`).sort()
    )

    const written = JSON.parse(readFileSync(recordFile, 'utf-8')) as {
      edits: {
        keyPath: string
        value: Record<string, { trusted_hash: string }>
        mergeStrategy: string
      }[]
      reloadUserConfig: boolean
    }
    expect(written.edits).toHaveLength(1)
    expect(written.edits[0].keyPath).toBe('hooks.state')
    expect(written.edits[0].mergeStrategy).toBe('upsert')
    expect(Object.keys(written.edits[0].value).sort()).toEqual([...keys].sort())
    expect(written.reloadUserConfig).toBe(true)
    // Leaked grace timers delay entry-process exit and synchronous launch preparation.
    const timerHandles = setTimeoutSpy.mock.results.map(({ value }) => value)
    expect(timerHandles).toHaveLength(2)
    expect(clearTimeoutSpy.mock.calls.map(([handle]) => handle)).toEqual(
      expect.arrayContaining(timerHandles)
    )
  })

  it('skips config/batchWrite when every expected entry is already trusted', async () => {
    const keys = ['/home/a/.codex/hooks.json:session_start:0:0']
    // The stub exits(9) on batchWrite, exposing any unintended write.
    const { request, recordFile } = createStubRequest({
      scenario: 'reject-write',
      hooks: keys.map((key) => managedHook(key, 'trusted')),
      expectedTrustKeys: keys,
      managedCommand: MANAGED_COMMAND
    })

    const result = await runCodexHookTrustGrantSession(request)
    expect(result).toMatchObject({ outcome: 'granted', wroteTrust: false })
    expect(existsSync(recordFile)).toBe(false)
  })

  it('reports verify-failed when expected entries are missing from the listing', async () => {
    const { request } = createStubRequest({
      scenario: 'happy',
      hooks: [managedHook('/home/a/.codex/hooks.json:session_start:0:0')],
      expectedTrustKeys: [
        '/home/a/.codex/hooks.json:session_start:0:0',
        '/home/a/.codex/hooks.json:stop:0:0'
      ],
      managedCommand: MANAGED_COMMAND
    })

    const result = await runCodexHookTrustGrantSession(request)
    expect(result).toMatchObject({ outcome: 'verify-failed', reasonClass: 'list-mismatch' })
  })

  it('rejects duplicate normalized aliases that conceal a missing expected key', async () => {
    const aliasedKey = 'C:\\Users\\Ada\\.codex\\hooks.json:session_start:0:0'
    const { request, recordFile } = createStubRequest({
      scenario: 'happy',
      hooks: [
        managedHook(aliasedKey),
        managedHook('c:/users/ada/.codex/hooks.json:session_start:0:0')
      ],
      expectedTrustKeys: [aliasedKey, 'C:\\Users\\Ada\\.codex\\hooks.json:stop:0:0'],
      managedCommand: MANAGED_COMMAND
    })

    await expect(runCodexHookTrustGrantSession(request)).resolves.toMatchObject({
      outcome: 'verify-failed',
      reasonClass: 'list-mismatch'
    })
    expect(existsSync(recordFile)).toBe(false)
  })

  it('decodes JSONL when a non-ASCII hook path is split across stdout chunks', async () => {
    const command = "/bin/sh '/tmp/rené/codex-hook.sh'"
    const key = '/home/rené/.codex/hooks.json:session_start:0:0'
    const { request } = createStubRequest({
      scenario: 'split-unicode',
      hooks: [{ ...managedHook(key), command }],
      expectedTrustKeys: [key],
      managedCommand: command,
      timeoutMs: 2_000
    })

    await expect(runCodexHookTrustGrantSession(request)).resolves.toMatchObject({
      outcome: 'granted',
      entries: [{ key }]
    })
  })

  it('throws the unsupported error class for unknown JSON-RPC methods', async () => {
    const keys = ['/home/a/.codex/hooks.json:session_start:0:0']
    const { request } = createStubRequest({
      scenario: 'unknown-method',
      hooks: keys.map((key) => managedHook(key)),
      expectedTrustKeys: keys,
      managedCommand: MANAGED_COMMAND
    })

    await expect(runCodexHookTrustGrantSession(request)).rejects.toBeInstanceOf(
      CodexAppServerUnsupportedError
    )
  })

  it('throws the unsupported error class when the CLI lacks the app-server subcommand', async () => {
    const keys = ['/home/a/.codex/hooks.json:session_start:0:0']
    const { request } = createStubRequest({
      scenario: 'no-subcommand',
      hooks: [],
      expectedTrustKeys: keys,
      managedCommand: MANAGED_COMMAND
    })

    const error = await runCodexHookTrustGrantSession(request).catch((caught: unknown) => caught)
    expect(isCodexAppServerUnsupportedError(error)).toBe(true)
  })

  it('does not classify unrelated stderr as a missing app-server capability', async () => {
    const { request } = createStubRequest({
      scenario: 'transient-stderr',
      hooks: [],
      expectedTrustKeys: ['k'],
      managedCommand: MANAGED_COMMAND
    })

    const error = await runCodexHookTrustGrantSession(request).catch((caught: unknown) => caught)
    expect(error).toBeInstanceOf(Error)
    expect(isCodexAppServerUnsupportedError(error)).toBe(false)
  })

  it('treats a silent exit zero before initialize as transient', async () => {
    const { request } = createStubRequest({
      scenario: 'silent-exit-0',
      hooks: [],
      expectedTrustKeys: ['k'],
      managedCommand: MANAGED_COMMAND
    })

    const error = await runCodexHookTrustGrantSession(request).catch((caught: unknown) => caught)
    expect(error).toBeInstanceOf(Error)
    expect(isCodexAppServerUnsupportedError(error)).toBe(false)
  })

  it.concurrent('kills a hung server at the session deadline', async (context) => {
    const { expect, onTestFinished } = context
    const keys = ['/home/a/.codex/hooks.json:session_start:0:0']
    const { request, pidFile } = createStubRequest(
      {
        scenario: 'hang',
        hooks: keys.map((key) => managedHook(key)),
        expectedTrustKeys: keys,
        managedCommand: MANAGED_COMMAND,
        timeoutMs: STUB_START_DEADLINE_MS
      },
      onTestFinished
    )

    const startedAt = Date.now()
    await expect(runCodexHookTrustGrantSession(request)).rejects.toBeInstanceOf(
      CodexAppServerTimeoutError
    )
    // This stub exits on stdin end or SIGTERM, so reaping must not add a grace delay.
    expect(Date.now() - startedAt - STUB_START_DEADLINE_MS).toBeLessThan(2_000)
    const childPid = Number(readFileSync(pidFile, 'utf8'))
    expect(() => process.kill(childPid, 0)).toThrow()
  })

  it.runIf(process.platform !== 'win32').concurrent(
    'stops a server that ignores its stdin end and SIGTERM after the SIGTERM grace',
    async ({ expect, onTestFinished }) => {
      const keys = ['/home/a/.codex/hooks.json:session_start:0:0']
      const { request, pidFile } = createStubRequest(
        {
          scenario: 'wedged',
          hooks: keys.map((key) => managedHook(key)),
          expectedTrustKeys: keys,
          managedCommand: MANAGED_COMMAND,
          timeoutMs: STUB_START_DEADLINE_MS
        },
        onTestFinished
      )

      const startedAt = Date.now()
      await expect(runCodexHookTrustGrantSession(request)).rejects.toBeInstanceOf(
        CodexAppServerTimeoutError
      )
      // The supervisor SIGTERMs its group at the deadline and SIGKILLs it after the grace.
      const pastDeadline = Date.now() - startedAt - STUB_START_DEADLINE_MS
      expect(pastDeadline).toBeGreaterThanOrEqual(PROVIDER_SIGTERM_GRACE_MS - 100)
      expect(pastDeadline).toBeLessThan(PROVIDER_SUPERVISOR_MAX_STOP_MS + 1_000)
      const childPid = Number(readFileSync(pidFile, 'utf8'))
      expect(() => process.kill(childPid, 0)).toThrow()
    }
  )

  it.concurrent('bounds a callback that stalls between RPC requests', async (context) => {
    const { expect, onTestFinished } = context
    const { request, pidFile } = createStubRequest(
      {
        scenario: 'happy',
        hooks: [],
        expectedTrustKeys: [],
        managedCommand: MANAGED_COMMAND,
        timeoutMs: STUB_START_DEADLINE_MS
      },
      onTestFinished
    )

    const startedAt = Date.now()
    await expect(
      runCodexAppServerSession(request.invocation, async () => new Promise<never>(() => {}))
    ).rejects.toBeInstanceOf(CodexAppServerTimeoutError)
    expect(Date.now() - startedAt - STUB_START_DEADLINE_MS).toBeLessThan(2_000)
    const childPid = Number(readFileSync(pidFile, 'utf8'))
    expect(() => process.kill(childPid, 0)).toThrow()
  })

  it('surfaces spawn failures as regular errors, not capability signals', async () => {
    const request: CodexHookTrustGrantRequest = {
      invocation: {
        command: join(tmpdir(), 'orca-codex-missing-binary-does-not-exist'),
        cliPath: null,
        args: [],
        timeoutMs: 2_000
      },
      hooksListCwd: tmpdir(),
      expectedTrustKeys: ['k'],
      managedCommand: MANAGED_COMMAND
    }
    const error = await runCodexHookTrustGrantSession(request).catch((caught: unknown) => caught)
    expect(error).toBeInstanceOf(Error)
    expect(isCodexAppServerUnsupportedError(error)).toBe(false)
  })
})