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.

78.7 KB
Raw Blame
import { randomBytes } from 'node:crypto'
import { request, type Server } from 'node:http'
import { afterAll, afterEach, describe, expect, it, vi } from 'vitest'
import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { startHookServer, type HookServerHandlers, chooseHookAgent, hookFiredAt, knownTranscriptFor } from './hookServer.js'
import { registry, type RegisteredSession } from './lib/registry.js'
import { env } from './config/env.js'
import { readHookCredential } from './lib/hookAuth.js'
import { ENGINES } from './engines/types.js'
import { engineHooks } from './engines/hooks.js'
import { pipeRequest } from './lib/windows/pipeClient.js'

let server: Server | null = null

/** The fetch a test's calls go through: this OS user's process, so over the loopback port it shows the daemon's
 *  local credential (lib/localCredential.ts) — unless the test names its own `x-harness-local`. */
const realFetch = globalThis.fetch
function credentialedFetch(base: string, credential: string): void {
  vi.spyOn(globalThis, 'fetch').mockImplementation((input: string | URL | Request, init?: RequestInit) => {
    const url = typeof input === 'string' ? input : input instanceof URL ? input.href : input.url
    if (!url.startsWith(base)) return realFetch(input, init)
    const headers = new Headers(init?.headers)
    if (!headers.has('x-harness-local')) headers.set('x-harness-local', credential)
    return realFetch(input, { ...init, headers })
  })
}

afterEach(async () => {
  vi.restoreAllMocks()
  if (!server) return
  await new Promise<void>((resolve) => server!.close(() => resolve()))
  server = null
})

async function start(overrides: Partial<HookServerHandlers> = {}) {
  const handlers: HookServerHandlers = {
    onRegistered: vi.fn(),
    onSessionEnd: vi.fn(),
    ...overrides,
  }
  const started = await startHookServer(0, handlers)
  server = started.server
  const credential = readHookCredential(env.ADAPTER_DATA_DIR)
  if (!credential) throw new Error('hook credential was not created')
  credentialedFetch(`http://127.0.0.1:${started.port}`, credential)
  return {
    handlers,
    base: `http://127.0.0.1:${started.port}`,
    headers: { 'content-type': 'application/json', 'x-harness-hook-token': credential },
  }
}

describe('process-owned hook server', () => {

  it('honors engine admission before registering or announcing a prompt, including a failed check', async () => {
    const admit = vi.spyOn(engineHooks.codex, 'admit')
      .mockReturnValueOnce({ accepted: false, reason: 'codex_subagent' })
      .mockImplementation(() => { throw new Error('rollout unavailable') })
    const agent = { engine: 'codex', agentId: 'parent', runtimes: [{ backend: 'tmux', paneId: '%41' }], primaryRuntimeKey: 'tmux\u0000%41', processIdentity: { pid: 4242, startMarker: 'fixture', executable: '<codex>' } } as RegisteredSession
    const byAgent = vi.spyOn(registry, 'byAgent').mockReturnValue(agent)
    try {
      const onPromptSubmitted = vi.fn()
      const { handlers, base, headers } = await start({
        resolveHookAgent: async () => agent,
        onPromptSubmitted,
      })
      for (const reason of ['codex_subagent', 'engine_hook_failed']) {
        const response = await fetch(`${base}/api/hook/session-start`, {
          method: 'POST', headers,
          body: JSON.stringify({ engine: 'codex', tmuxPane: '%41', sessionId: 'child', hookEvent: 'UserPromptSubmit' }),
        })
        expect(await response.json()).toEqual(reason === 'engine_hook_failed' ? { pending: true } : { ignored: true, reason })
      }
      expect(handlers.onRegistered).not.toHaveBeenCalled()
      expect(onPromptSubmitted).not.toHaveBeenCalled()
    } finally { admit.mockRestore(); byAgent.mockRestore() }
  })

  it('keeps both hints of a mixed tmux and pty host array', async () => {
    const resolveHookAgent = vi.fn(async () => null)
    const { base, headers } = await start({ resolveHookAgent })
    const runtimeHints = [{ backend: 'tmux', paneId: '%5' }, { backend: 'ptyhost', instance: 'p2', paneId: '%1003' }]
    await fetch(`${base}/api/hook/session-start`, { method: 'POST', headers,
      body: JSON.stringify({ engine: 'claude', sessionId: 'session-1', runtimeHints, callerPid: 4242 }) })
    expect(resolveHookAgent).toHaveBeenCalledWith(expect.objectContaining({ runtimeHints }))
  })

  it('holds a hook whose pty host pane is another host instance\'s pane with the same id', async () => {
    const admit = vi.spyOn(engineHooks.codex, 'admit').mockReturnValue({ accepted: false, reason: 'codex_subagent' })
    const runtime = { backend: 'ptyhost', instance: 'p1', paneId: '%1' }
    const agent = { engine: 'codex', agentId: 'parent', runtimes: [runtime], primaryRuntimeKey: 'ptyhost\u0000p1\u0000%1', processIdentity: { pid: 4242, startMarker: 'fixture', executable: '<codex>' } } as unknown as RegisteredSession
    const byAgent = vi.spyOn(registry, 'byAgent').mockReturnValue(agent)
    try {
      const { base, headers } = await start({ resolveHookAgent: async () => agent })
      const post = async (instance: string) => (await fetch(`${base}/api/hook/session-start`, {
        method: 'POST', headers,
        body: JSON.stringify({ engine: 'codex', runtimeHints: [{ backend: 'ptyhost', instance, paneId: '%1' }], sessionId: `child-${instance}`, hookEvent: 'UserPromptSubmit' }),
      })).json()
      expect(await post('p2')).toEqual({ pending: true })
      expect(await post('p1')).toEqual({ ignored: true, reason: 'codex_subagent' })
    } finally { admit.mockRestore(); byAgent.mockRestore() }
  })

  it('runs targeted resolution and rejects a hook without a matching pane engine process', async () => {
    const resolveHookAgent = vi.fn(async () => null)
    const { handlers, base, headers } = await start({ resolveHookAgent })
    const response = await fetch(`${base}/api/hook/session-start`, {
      method: 'POST',
      headers,
      body: JSON.stringify({
        engine: 'codex',
        tmuxPane: '%41',
        sessionId: '019fea92-e31a-7692-9c35-f616e9d458b7',
        cwd: '/work/demo',
      }),
    })

    expect(await response.json()).toEqual({ ignored: true, reason: 'no_matching_engine_process' })
    expect(resolveHookAgent).toHaveBeenCalledWith({
      engine: 'codex', tmuxPane: '%41', runtimeHints: [{ backend: 'tmux', paneId: '%41' }], callerPid: undefined,
      onWait: expect.any(Function),
    })
    expect(handlers.onRegistered).not.toHaveBeenCalled()
  })

  it('accepts a Herdr hint from a hook installed by an earlier build, and resolves by its tmux pane only', async () => {
    const resolveHookAgent = vi.fn(async () => null)
    const { base, headers } = await start({ resolveHookAgent })
    const response = await fetch(`${base}/api/hook/session-start`, {
      method: 'POST',
      headers,
      body: JSON.stringify({
        engine: 'codex',
        tmuxPane: '%41',
        sessionId: '019fea92-e31a-7692-9c35-f616e9d458b7',
        runtimeHints: [
          { backend: 'tmux', paneId: '%41' },
          { backend: 'herdr', paneId: 'w1:p1', sessionName: 'default', socketPath: '/tmp/herdr.sock' },
        ],
      }),
    })

    expect(response.status).toBe(200)
    expect(resolveHookAgent).toHaveBeenCalledWith({
      engine: 'codex', tmuxPane: '%41', runtimeHints: [{ backend: 'tmux', paneId: '%41' }], callerPid: undefined,
      onWait: expect.any(Function),
    })
  })

  it('resolves a hook from a pty host pane (Windows) by its instance and pane', async () => {
    const resolveHookAgent = vi.fn(async () => null)
    const { base, headers } = await start({ resolveHookAgent })
    const response = await fetch(`${base}/api/hook/session-start`, {
      method: 'POST',
      headers,
      body: JSON.stringify({
        engine: 'claude',
        sessionId: '7f3b1c2e-0a4d-4e5f-9a6b-1c2d3e4f5a6b',
        runtimeHints: [{ backend: 'ptyhost', instance: 'p2', paneId: '%1003' }],
        callerPid: 4242,
      }),
    })

    expect(response.status).toBe(200)
    expect(resolveHookAgent).toHaveBeenCalledWith({
      engine: 'claude', tmuxPane: undefined, runtimeHints: [{ backend: 'ptyhost', instance: 'p2', paneId: '%1003' }], callerPid: 4242,
      onWait: expect.any(Function),
    })
  })

  it.each(['p2-0.4.21-dev.win1', 'p2-h0123456789ab'])('resolves a hook from a versioned pty host\'s pane by its instance: %s', async (instance) => {
    const resolveHookAgent = vi.fn(async () => null)
    const { base, headers } = await start({ resolveHookAgent })
    const runtimeHints = [{ backend: 'ptyhost', instance, paneId: '%7' }]
    const response = await fetch(`${base}/api/hook/session-start`, {
      method: 'POST', headers, body: JSON.stringify({ engine: 'claude', sessionId: 'session-1', runtimeHints, callerPid: 4242 }),
    })
    expect(response.status).toBe(200)
    expect(resolveHookAgent).toHaveBeenCalledWith(expect.objectContaining({ runtimeHints }))
  })

  it('answers a hook whose agent has yet to record its process before the wait, and only logs what the wait finds', async () => {
    // The engine's hook command gives up on a reply after 500ms and then writes the registry itself, as for
    // a daemon that is down (hook/notify.mjs, fallbackRegister): held for the wait, its own row took the
    // agent's place under the running daemon. Answered first, it writes nothing.
    let found!: (agent: RegisteredSession | null) => void
    const resolveHookAgent = vi.fn(({ onWait }: { onWait?: () => void }) => {
      onWait?.()
      return new Promise<RegisteredSession | null>((resolve) => { found = resolve })
    })
    const { handlers, base, headers } = await start({ resolveHookAgent: resolveHookAgent as HookServerHandlers['resolveHookAgent'] })
    const log = vi.spyOn(console, 'log').mockImplementation(() => {})
    try {
      const reply = await Promise.race([
        fetch(`${base}/api/hook/session-start`, {
          method: 'POST',
          headers,
          body: JSON.stringify({ engine: 'claude', tmuxPane: '%7', sessionId: 'session-7', callerPid: 4242 }),
        }),
        new Promise<'held'>((resolve) => setTimeout(() => resolve('held'), 2_000)),
      ])
      expect(reply).not.toBe('held')
      expect((reply as Response).status).toBe(202)
      expect(await (reply as Response).json()).toMatchObject({ pending: false, retry: true })
      // The wait ends with no agent for it: said in the log, and nothing is answered twice.
      found(null)
      await vi.waitFor(() => expect(log).toHaveBeenCalledWith('[hooks] session- session-start ignored · no_matching_engine_process'))
      expect(handlers.onRegistered).not.toHaveBeenCalled()
    } finally { log.mockRestore() }
  })

  it('ignores a hook whose only terminal is a Herdr pane', async () => {
    const resolveHookAgent = vi.fn(async () => null)
    const { base, headers } = await start({ resolveHookAgent })
    const response = await fetch(`${base}/api/hook/session-start`, {
      method: 'POST',
      headers,
      body: JSON.stringify({
        engine: 'claude',
        sessionId: 'session-1',
        runtimeHints: [{ backend: 'herdr', paneId: 'w1:p1', sessionName: 'default' }],
      }),
    })

    expect(await response.json()).toEqual({ ignored: true, reason: 'not_in_terminal' })
    expect(resolveHookAgent).not.toHaveBeenCalled()
  })

  it('rejects hooks outside configured terminal contexts before attempting process resolution', async () => {
    const resolveHookAgent = vi.fn(async () => null)
    const { handlers, base, headers } = await start({ resolveHookAgent })
    const response = await fetch(`${base}/api/hook/session-start`, {
      method: 'POST',
      headers,
      body: JSON.stringify({ engine: 'claude', sessionId: 'session-1', cwd: '/work/demo' }),
    })

    expect(await response.json()).toEqual({ ignored: true, reason: 'not_in_terminal' })
    expect(resolveHookAgent).not.toHaveBeenCalled()
    expect(handlers.onRegistered).not.toHaveBeenCalled()
  })

  it('treats SessionEnd as a reconciliation hint and exposes no launcher websocket endpoint', async () => {
    const onSessionEnd = vi.fn()
    const agent = { engine: 'claude', sessionId: 'session-1', agentId: 'agent-1', runtimes: [], processIdentity: null } as unknown as RegisteredSession
    vi.spyOn(registry, 'bySession').mockReturnValue(agent)
    vi.spyOn(registry, 'byAgent').mockReturnValue(agent)
    const resolveHookAgent = vi.fn(async () => agent)
    const { base, headers } = await start({ onSessionEnd, resolveHookAgent })
    const ended = await fetch(`${base}/api/hook/session-end`, {
      method: 'POST',
      headers,
      body: JSON.stringify({
        engine: 'claude', sessionId: 'session-1', reason: 'clear', tmuxPane: '%1', callerPid: 123,
      }),
    })
    expect(await ended.json()).toEqual({ ok: true })
    expect(onSessionEnd).toHaveBeenCalledWith('session-1', 'clear')

    const legacy = await fetch(`${base}/api/machine-ws`)
    expect(legacy.status).toBe(404)
  })

  it('rejects every unauthenticated mutating hook request', async () => {
    const { base, handlers } = await start()
    const response = await fetch(`${base}/api/hook/session-end`, {
      method: 'POST',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify({ sessionId: 'session-1' }),
    })
    expect(response.status).toBe(401)
    expect(await response.json()).toEqual({ error: 'UNAUTHORIZED' })
    expect(handlers.onSessionEnd).not.toHaveBeenCalled()
  })

  it.each([
    [{ engine: 'claude', sessionId: 'session-1', tmuxPane: '%1', unknown: true }],
    [{ engine: 'claude', sessionId: 'session-1', runtimeHints: [{ backend: 'tmux', paneId: '%1', extra: true }] }],
    [{ engine: 'claude', sessionId: 'session-1', runtimeHints: [{ backend: 'ptyhost', instance: 'p1', paneId: '%1', extra: true }] }],
    [{ engine: 'claude', sessionId: 'session-1', runtimeHints: [{ backend: 'ptyhost', instance: 'host', paneId: '%1' }] }],
    [{ engine: 'claude', sessionId: 'session-1', runtimeHints: [{ backend: 'ptyhost', instance: 'p2-0.4.21 x', paneId: '%1' }] }],
    [{ engine: 'claude', sessionId: 'session-1', runtimeHints: [{ backend: 'ptyhost', instance: 'p2-', paneId: '%1' }] }],
    [{ engine: 'claude', sessionId: 'session-1', runtimeHints: [{ backend: 'ptyhost', instance: 'p1', paneId: '1' }] }],
    [{ engine: 'claude', sessionId: 'session-1', runtimeHints: [{ backend: 'ptyhost', instance: 'p1' }] }],
    [{ engine: 'claude', sessionId: 'session-1', runtimeHints: [{ backend: 'ptyhost', instance: 1, paneId: '%1' }] }],
    [{ engine: 'claude', sessionId: 'session-1', runtimeHints: [{ backend: 'ptyhost', instance: 'p1', paneId: '%1\n' }] }],
    [{ engine: 'claude', sessionId: 'session-1', tmuxPane: '%1', source: { forged: true } }],
    [{ engine: 'claude', sessionId: 'session-1', tmuxPane: '%1', input: 'x'.repeat(128 * 1024 + 1) }],
    [null],
  ])('rejects malformed or unknown hook fields before process resolution', async (body) => {
    const resolveHookAgent = vi.fn(async () => null)
    const { base, headers } = await start({ resolveHookAgent })
    const response = await fetch(`${base}/api/hook/session-start`, {
      method: 'POST', headers, body: JSON.stringify(body),
    })
    expect(response.status).toBe(400)
    expect(await response.json()).toEqual({ error: 'invalid hook body' })
    expect(resolveHookAgent).not.toHaveBeenCalled()
  })

  it.each([
    ['/api/hook/session-end', { reason: 'clear' }, 'onSessionEnd'],
    ['/api/hook/turn-start', {}, 'onTurnStart'],
    ['/api/hook/tool-start', { toolUseId: 'tool-1', toolName: 'Task' }, 'onToolStart'],
    ['/api/hook/turn-stop', { status: 'error' }, 'onTurnStop'],
  ] as const)('rejects a forged bound-session mutation on %s', async (path, extra, handlerName) => {
    const handler = vi.fn()
    const resolveHookAgent = vi.fn(async () => ({
      engine: 'claude', sessionId: 'real-session', agentId: 'agent-1',
    } as never))
    const { base, headers } = await start({ [handlerName]: handler, resolveHookAgent })
    const response = await fetch(`${base}${path}`, {
      method: 'POST',
      headers,
      body: JSON.stringify({
        engine: 'claude', sessionId: 'forged-session', tmuxPane: '%1', callerPid: 123, ...extra,
      }),
    })

    expect(response.status).toBe(403)
    expect(await response.json()).toEqual({ error: 'UNBOUND_HOOK' })
    expect(handler).not.toHaveBeenCalled()
  })

  it('hands a Stop on with when its engine ran it, and holds it as long as a test asks', async () => {
    const onTurnStop = vi.fn()
    const agent = { engine: 'claude', sessionId: 'real-session', agentId: 'agent-1', runtimes: [], processIdentity: null } as unknown as RegisteredSession
    vi.spyOn(registry, 'bySession').mockReturnValue(agent)
    vi.spyOn(registry, 'byAgent').mockReturnValue(agent)
    const resolveHookAgent = vi.fn(async () => agent)
    const stop = (base: string, headers: Record<string, string>) => fetch(`${base}/api/hook/turn-stop`, {
      method: 'POST', headers, body: JSON.stringify({ engine: 'claude', sessionId: 'real-session', tmuxPane: '%1', callerPid: 123 }),
    })
    const { base, headers } = await start({ onTurnStop, resolveHookAgent })
    expect((await stop(base, { ...headers, 'x-harness-hook-fired-at': '1700000000000' })).status).toBe(200)
    expect(onTurnStop).toHaveBeenLastCalledWith({ sessionId: 'real-session', status: undefined, transcriptPath: undefined, firedAt: 1_700_000_000_000 })
    // A hook client too old to say: as before.
    expect((await stop(base, headers)).status).toBe(200)
    expect(onTurnStop).toHaveBeenLastCalledWith({ sessionId: 'real-session', status: undefined, transcriptPath: undefined })
    server?.close()
    const held = await start({ onTurnStop, resolveHookAgent, stopHookDelayMs: 50 })
    onTurnStop.mockClear()
    expect((await stop(held.base, held.headers)).status).toBe(200)
    expect(onTurnStop).not.toHaveBeenCalled()
    await vi.waitFor(() => expect(onTurnStop).toHaveBeenCalledOnce())
  })

  it('reads when a hook was run from its header, and nothing else as that', () => {
    expect(hookFiredAt({ headers: { 'x-harness-hook-fired-at': '1700000000000' } })).toBe(1_700_000_000_000)
    for (const value of [undefined, '', 'soon', '-5', '0', '1.5', '1e400']) {
      expect(hookFiredAt({ headers: { 'x-harness-hook-fired-at': value } })).toBeUndefined()
    }
  })

  it('answers a proxied control-plane read whose handler throws, instead of hanging it', async () => {
    // The handler is a void-discarded async: a throw used to be an unhandledRejection and a request
    // with no response, which the desktop app reported 30s later as its own receive timeout.
    const { base } = await start({ onMachinesList: async () => { throw new TypeError('fetch failed') } })
    const response = await fetch(`${base}/api/machines`)
    expect(response.status).toBe(502)
    expect(await response.json()).toEqual({ success: false, error: { code: 'PROXY_FAILED', message: 'fetch failed' } })
  })

  it('forwards a proxied answer verbatim, status and body alike', async () => {
    const { base } = await start({
      onAuthMe: async () => ({ status: 504, body: { success: false, error: { code: 'BACKEND_TIMEOUT', message: 'slow' } } }),
    })
    const response = await fetch(`${base}/api/auth/me`)
    expect(response.status).toBe(504)
    expect(await response.json()).toEqual({ success: false, error: { code: 'BACKEND_TIMEOUT', message: 'slow' } })
  })
})

describe('the account name proxy', () => {
  it('passes the signed-in person\'s new name on only with the local header, body and answer verbatim', async () => {
    const update = vi.fn(async (body: unknown) => ({ status: 200, body: { success: true, data: { user: { id: 'u1', name: 'Elvis' }, echo: body } } }))
    const { base } = await start({ onAuthMeUpdate: update })
    const refused = await fetch(`${base}/api/auth/me`, { method: 'PATCH', headers: { 'content-type': 'application/json' }, body: '{"name":"Elvis"}' })
    expect(refused.status).toBe(403)
    expect(update).not.toHaveBeenCalled()

    const saved = await fetch(`${base}/api/auth/me`, { method: 'PATCH', headers: { 'content-type': 'application/json', 'x-adapter-local': '1' }, body: '{"name":"Elvis"}' })
    expect(saved.status).toBe(200)
    expect(((await saved.json()) as { data: unknown }).data).toEqual({ user: { id: 'u1', name: 'Elvis' }, echo: { name: 'Elvis' } })
    expect(update).toHaveBeenCalledWith({ name: 'Elvis' })

    const bad = await fetch(`${base}/api/auth/me`, { method: 'PATCH', headers: { 'content-type': 'application/json', 'x-adapter-local': '1' }, body: '{nope' })
    expect(bad.status).toBe(400)
    expect(update).toHaveBeenCalledTimes(1)
  })

  it('answers a refusal as the backend gave it, so the app can say why', async () => {
    const { base } = await start({
      onAuthMeUpdate: async () => ({ status: 400, body: { success: false, error: { code: 'INVALID_NAME', message: 'Use 1 to 60 characters, with no hidden ones.' } } }),
    })
    const response = await fetch(`${base}/api/auth/me`, { method: 'PATCH', headers: { 'content-type': 'application/json', 'x-adapter-local': '1' }, body: '{"name":" "}' })
    expect(response.status).toBe(400)
    expect(((await response.json()) as { error: { code: string } }).error.code).toBe('INVALID_NAME')
  })
})

describe('the desk proxy', () => {
  it('reads the desk ungated and writes its ops only with the local header, body passed through', async () => {
    const ops = vi.fn(async (body: unknown) => ({ status: 200, body: { success: true, data: { revision: 2, tabs: [], echo: body } } }))
    const { base } = await start({
      onDeskRead: async () => ({ status: 200, body: { success: true, data: { revision: 1, tabs: [] } } }),
      onDeskOps: ops,
    })
    const read = await fetch(`${base}/api/desk`)
    expect(await read.json()).toEqual({ success: true, data: { revision: 1, tabs: [] } })

    const refused = await fetch(`${base}/api/desk/ops`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: '{"ops":[]}' })
    expect(refused.status).toBe(403)
    expect(ops).not.toHaveBeenCalled()

    const body = { ops: [{ op: 'tab.create', id: 'a', name: 'Local' }] }
    const written = await fetch(`${base}/api/desk/ops`, { method: 'POST', headers: { 'content-type': 'application/json', 'x-adapter-local': '1' }, body: JSON.stringify(body) })
    expect(((await written.json()) as { data: unknown }).data).toMatchObject({ revision: 2, echo: body })
    expect(ops).toHaveBeenCalledWith(body)

    const bad = await fetch(`${base}/api/desk/ops`, { method: 'POST', headers: { 'content-type': 'application/json', 'x-adapter-local': '1' }, body: '{nope' })
    expect(bad.status).toBe(400)
  })
})

describe('the Agent Messages proxy', () => {
  it('reads which tabs have Agent Messages on ungated, and sets one tab only with the local header', async () => {
    const write = vi.fn(async (tabId: string, body: unknown) => ({ status: 200, body: { success: true, data: { tabId, echo: body } } }))
    const { base } = await start({
      onAgentMessagesRead: async () => ({ status: 200, body: { success: true, data: { revision: 1, machines: [], tabs: [] } } }),
      onAgentMessagesWrite: write,
    })
    expect(await (await fetch(`${base}/api/agent-messages`)).json()).toEqual({ success: true, data: { revision: 1, machines: [], tabs: [] } })
    const patch = (path: string, body: string, local = true) => fetch(`${base}${path}`, { method: 'PATCH', headers: { 'content-type': 'application/json', ...(local ? { 'x-adapter-local': '1' } : {}) }, body })
    expect((await patch('/api/agent-messages/tabs/app', '{"enabled":true}', false)).status).toBe(403)
    expect(write).not.toHaveBeenCalled()
    const saved = await patch('/api/agent-messages/tabs/app', '{"enabled":true}')
    expect(((await saved.json()) as { data: unknown }).data).toEqual({ tabId: 'app', echo: { enabled: true } })
    expect(write).toHaveBeenCalledExactlyOnceWith('app', { enabled: true })
    expect((await patch('/api/agent-messages/tabs/app', '{nope')).status).toBe(400)
    expect((await patch('/api/agent-messages/tabs/bad.tab', '{}')).status).toBe(404)
  })

  it('answers UNAVAILABLE where the daemon has no handler for it', async () => {
    const { base } = await start({})
    expect((await fetch(`${base}/api/agent-messages`)).status).toBe(503)
    expect((await fetch(`${base}/api/agent-messages/tabs/app`, { method: 'PATCH', headers: { 'content-type': 'application/json', 'x-adapter-local': '1' }, body: '{}' })).status).toBe(503)
  })
})

// The desktop and web apps approve a device that says its code aloud (a lamp, #1410), as the phone does:
// the daemon passes the phone half of a sign-in through with its own session, and nothing else.
describe('sign-in approval proxy', () => {
  it('passes lookup, approve and deny through with the code only, guarded from cross-origin requests', async () => {
    const send = vi.fn(async () => ({ status: 200, body: { success: true, data: { ok: true } } }))
    const { base } = await start({ onSignInAnswer: send })
    const headers = { 'x-adapter-local': '1', 'content-type': 'application/json' }
    for (const h of [{}, { ...headers, origin: 'https://untrusted.example' }]) {
      expect((await fetch(`${base}/api/auth/qr/approve`, { method: 'POST', headers: h, body: JSON.stringify({ code: '12345678' }) })).status).toBe(403)
    }
    for (const invalid of [{}, { code: '' }, { code: 5 }, { code: 'x'.repeat(129) }, { code: '12345678', userId: 'u2' }]) {
      expect((await fetch(`${base}/api/auth/qr/approve`, { method: 'POST', headers, body: JSON.stringify(invalid) })).status).toBe(400)
    }
    expect((await fetch(`${base}/api/auth/qr/claim`, { method: 'POST', headers, body: JSON.stringify({ code: '12345678' }) })).status).toBe(404)
    expect(send).not.toHaveBeenCalled()
    for (const action of ['lookup', 'approve', 'deny'] as const) {
      expect((await fetch(`${base}/api/auth/qr/${action}`, { method: 'POST', headers, body: JSON.stringify({ code: '1234 5678' }) })).status).toBe(200)
      expect(send).toHaveBeenLastCalledWith(action, { code: '1234 5678' })
    }
  })

  it('is unavailable on a daemon that cannot reach the backend for it', async () => {
    const { base } = await start({})
    const r = await fetch(`${base}/api/auth/qr/lookup`, { method: 'POST', headers: { 'x-adapter-local': '1', 'content-type': 'application/json' }, body: JSON.stringify({ code: '12345678' }) })
    expect(r.status).toBe(503)
  })
})

// The native desktop's chat files: its REST client has no account token, so the daemon streams the upload on with its own.
describe('Super Tab attachment pass-through', () => {
  it('hands a local multipart POST to the pass-through as a stream, guarded like the other writes', async () => {
    const forward = vi.fn(async (req: import('node:http').IncomingMessage, res: import('node:http').ServerResponse, path: string) => {
      let bytes = 0
      for await (const chunk of req) bytes += (chunk as Buffer).byteLength
      res.writeHead(201, { 'Content-Type': 'application/json' })
      res.end(JSON.stringify({ path, bytes }))
    })
    const { base } = await start({ onSuperTabAttachment: forward })
    const headers = { 'x-adapter-local': '1', 'content-type': 'multipart/form-data; boundary=x' }
    const body = Buffer.alloc(300 * 1024, 1)
    for (const h of [{ 'content-type': headers['content-type'] }, { ...headers, origin: 'https://untrusted.example' }]) {
      expect((await fetch(`${base}/api/super-tabs/tab-1/attachments`, { method: 'POST', headers: h, body })).status).toBe(403)
    }
    expect((await fetch(`${base}/api/super-tabs/../attachments`, { method: 'POST', headers, body })).status).toBe(404)
    expect((await fetch(`${base}/api/super-tabs/tab-1/commands`, { method: 'POST', headers, body })).status).toBe(404)
    expect(forward).not.toHaveBeenCalled()
    // Past the 256 KiB the JSON routes read: the body reaches the pass-through whole, as a stream.
    const r = await fetch(`${base}/api/super-tabs/tab-1/attachments?asAgentId=agent-1&other=x`, { method: 'POST', headers, body })
    expect(r.status).toBe(201)
    // An agent's own `post --attach` names it; nothing else in the query goes on.
    expect(await r.json()).toEqual({ path: '/api/super-tabs/tab-1/attachments?asAgentId=agent-1', bytes: body.byteLength })
    const person = await fetch(`${base}/api/super-tabs/tab-1/attachments?asAgentId=../x`, { method: 'POST', headers, body: 'x' })
    expect(await person.json()).toEqual({ path: '/api/super-tabs/tab-1/attachments', bytes: 1 })
  })

  // A profile picture goes the same way (Desktop's Upload picture…); before this, the daemon answered 404 and Desktop
  // showed only "Could not upload the file".
  it('hands an avatar picture to the pass-through, guarded the same way', async () => {
    const forward = vi.fn(async (req: import('node:http').IncomingMessage, res: import('node:http').ServerResponse, path: string) => {
      let bytes = 0
      for await (const chunk of req) bytes += (chunk as Buffer).byteLength
      res.writeHead(200, { 'Content-Type': 'application/json' })
      res.end(JSON.stringify({ path, bytes }))
    })
    const { base } = await start({ onSuperTabAttachment: forward })
    const headers = { 'x-adapter-local': '1', 'content-type': 'multipart/form-data; boundary=x' }
    expect((await fetch(`${base}/api/super-tabs/tab-1/avatars`, { method: 'POST',
      headers: { ...headers, origin: 'https://untrusted.example' }, body: 'x' })).status).toBe(403)
    expect(forward).not.toHaveBeenCalled()
    const r = await fetch(`${base}/api/super-tabs/tab-1/avatars`, { method: 'POST', headers, body: 'picture' })
    expect(r.status).toBe(200)
    expect(await r.json()).toEqual({ path: '/api/super-tabs/tab-1/avatars', bytes: 7 })
  })

  // Files over 10 MB go straight to storage (contract of group 1604): the daemon asks the backend for the link and says the
  // upload is complete, with the account's token; the bytes never pass through it.
  it('passes a direct upload\'s link request and completion on, guarded like the other writes', async () => {
    const forward = vi.fn(async (path: string, body: unknown) => ({ status: 200, body: { success: true, data: { path, body } } }))
    const { base } = await start({ onSuperTabAttachmentUpload: forward })
    const headers = { 'x-adapter-local': '1', 'content-type': 'application/json' }
    const ask = { conversationId: 'c1', name: 'AC4 - 26 Oct v2.step', mime: 'application/octet-stream', size: 123456789 }
    const link = `${base}/api/super-tabs/tab-1/attachments/uploads`, complete = `${link}/0123456789abcdef01234567/complete`
    for (const url of [link, complete]) {
      for (const h of [{ 'content-type': 'application/json' }, { ...headers, origin: 'https://untrusted.example' }]) {
        expect((await fetch(url, { method: 'POST', headers: h, body: JSON.stringify(ask) })).status).toBe(403)
      }
    }
    // Only the two upload paths: no other path, encoded or not, reaches the backend with this account's token.
    for (const url of [`${base}/api/super-tabs/../attachments/uploads`, `${link}/../x/complete`, `${link}/u1`, `${link}/u1/complete/x`,
      `${link}/u1%2F..%2F..%2Fcommands/complete`, `${base}/api/super-tabs/tab-1%2Fcommands%3F/attachments/uploads`, `${link}/%2e%2e/complete`,
      `${base}/api/super-tabs/tab-1/commands`, `${base}/api/super-tabs/tab-1/attachments/uploads/u1/complete/../../../commands`]) {
      expect((await fetch(url, { method: 'POST', headers, body: '{}' })).status).toBe(404)
    }
    expect((await fetch(link, { method: 'POST', headers, body: 'not json' })).status).toBe(400)
    expect((await fetch(link, { method: 'POST', headers, body: '[1]' })).status).toBe(400)
    expect(forward).not.toHaveBeenCalled()
    const asked = await fetch(`${link}?asAgentId=agent-1&other=x`, { method: 'POST', headers, body: JSON.stringify({ ...ask, command: { type: 'member.remove' } }) })
    expect(asked.status).toBe(200)
    expect(await asked.json()).toEqual({ success: true, data: { path: '/api/super-tabs/tab-1/attachments/uploads?asAgentId=agent-1', body: ask } })
    // Completion's body is {}, and an empty one is read as that.
    const done = await fetch(`${complete}?asAgentId=../x`, { method: 'POST', headers })
    expect(await done.json()).toEqual({ success: true, data: { path: '/api/super-tabs/tab-1/attachments/uploads/0123456789abcdef01234567/complete', body: {} } })
    // The backend's refusal, as it said it.
    forward.mockResolvedValueOnce({ status: 413, body: { success: false, error: { code: 'ATTACHMENT_TOO_LARGE', message: 'Files can be up to 256 MB.' } } } as never)
    const refused = await fetch(link, { method: 'POST', headers, body: JSON.stringify({ ...ask, size: 256 * 1024 * 1024 + 1 }) })
    expect(refused.status).toBe(413)
    expect(await refused.json()).toEqual({ success: false, error: { code: 'ATTACHMENT_TOO_LARGE', message: 'Files can be up to 256 MB.' } })
  })

  it('is unavailable on a daemon without it', async () => {
    const { base } = await start({})
    expect((await fetch(`${base}/api/super-tabs/tab-1/attachments/uploads`, { method: 'POST',
      headers: { 'x-adapter-local': '1', 'content-type': 'application/json' }, body: '{}' })).status).toBe(503)
    expect((await fetch(`${base}/api/super-tabs/tab-1/attachments`, { method: 'POST',
      headers: { 'x-adapter-local': '1', 'content-type': 'multipart/form-data; boundary=x' }, body: 'x' })).status).toBe(503)
  })
})

describe('account Experimental settings proxy', () => {
  it('proxies only voluntary fixed-choice feedback and guards it from cross-origin requests', async () => {
    const send = vi.fn(async () => ({ status: 200, body: { success: true, data: { accepted: true } } }))
    const { base } = await start({ onProductFeedback: send })
    const path = `${base}/api/product-usage/feedback`
    const body = { id: '12345678-1234-4234-8234-123456789012', answer: 'useful' }
    const headers = { 'x-adapter-local': '1', 'content-type': 'application/json' }
    for (const h of [{}, { ...headers, origin: 'https://untrusted.example' }]) {
      expect((await fetch(path, { method: 'POST', headers: h, body: JSON.stringify(body) })).status).toBe(403)
    }
    for (const invalid of [{ ...body, text: 'PRIVATE_CANARY' }, { ...body, answer: 'PRIVATE_CANARY' }, { ...body, id: 'PRIVATE_CANARY' }]) {
      expect((await fetch(path, { method: 'POST', headers, body: JSON.stringify(invalid) })).status).toBe(400)
    }
    expect(send).not.toHaveBeenCalled()
    expect((await fetch(path, { method: 'POST', headers, body: JSON.stringify(body) })).status).toBe(200)
    expect(send).toHaveBeenCalledExactlyOnceWith(body)
  })
  it('accepts only bounded fixed app counts through the local gateway proxy', async () => {
    const send = vi.fn(async () => ({ status: 200, body: { success: true, data: { accepted: true } } }))
    const { base } = await start({ onProductUsageReport: send })
    const body = { schemaVersion: 1, revision: 0, id: '12345678-1234-4234-8234-123456789012', day: '2026-10-14', counters: { ui_desktop_sign_in_ok: 1 } }
    const headers = { 'x-adapter-local': '1', 'content-type': 'application/json' }
    const post = (value: unknown, h = headers) => fetch(`${base}/api/product-usage/report`, { method: 'POST', headers: h, body: JSON.stringify(value) })
    expect((await post(body, { ...headers, origin: 'https://untrusted.example' } as typeof headers)).status).toBe(403)
    for (const bad of [{ ...body, prompt: 'PRIVATE_CANARY' }, { ...body, counters: { turns_started: 1 } },
      { ...body, counters: { ui_desktop_sign_in_ok: -1 } }, { ...body, counters: { ui_desktop_sign_in_ok: 'PRIVATE_CANARY' } },
      { ...body, counters: { 'PRIVATE_CANARY': 1 } }, { ...body, prompt: 'PRIVATE_CANARY'.repeat(1000) }]) {
      const response = await post(bad)
      expect(response.status).toBe(400)
      expect(await response.text()).not.toContain('PRIVATE_CANARY')
    }
    expect(send).not.toHaveBeenCalled()
    expect((await post(body)).status).toBe(200)
    expect(send).toHaveBeenCalledExactlyOnceWith(body)
    send.mockRejectedValueOnce(new Error('PRIVATE_CANARY'))
    const failed = await post(body)
    expect(failed.status).toBe(502)
    expect(await failed.text()).not.toContain('PRIVATE_CANARY')
    // The backend's busy answer reaches the Desktop with its Retry-After, which the Desktop waits out.
    const busy = { success: false, error: { code: 'USAGE_WRITE_CONFLICT', message: 'Usage measurement busy' } }
    send.mockResolvedValueOnce({ status: 429, body: busy, retryAfterMs: 90_500 } as never)
    const refused = await post(body)
    expect(refused.status).toBe(429)
    expect(refused.headers.get('retry-after')).toBe('91')
    expect(await refused.json()).toEqual(busy)
    expect((await post(body)).headers.get('retry-after')).toBeNull()
  })
  it('forwards the current Desktop health report intact while rejecting private context', async () => {
    const body = JSON.parse(readFileSync(new URL('../../tests/fixtures/desktop-product-usage-report.json', import.meta.url), 'utf8'))
    const send = vi.fn(async () => ({ status: 200, body: { success: true, data: { accepted: true } } }))
    const { base } = await start({ onProductUsageReport: send })
    const headers = { 'content-type': 'application/json', 'x-adapter-local': '1' }
    const post = (value: unknown, h = headers) => fetch(`${base}/api/product-usage/report`, { method: 'POST', headers: h, body: JSON.stringify(value) })
    expect((await post(body, { ...headers, origin: 'https://untrusted.example' } as typeof headers)).status).toBe(403)
    for (const bad of [{ ...body, context: { ...body.context, path: 'PRIVATE_CANARY' } },
      { ...body, context: { ...body.context, release: 'PRIVATE_CANARY' } },
      { ...body, counters: { health_cli_report_failure_auth: 1 } }]) {
      const refused = await post(bad)
      expect(refused.status).toBe(400); expect(await refused.text()).not.toContain('PRIVATE_CANARY')
    }
    expect(send).not.toHaveBeenCalled()
    expect((await post(body)).status).toBe(200)
    expect(send).toHaveBeenCalledExactlyOnceWith(body)
  })
  it('forwards a newer Desktop report without the names it does not know, and says which it knows', async () => {
    // Refused whole before: the Desktop drops a refused packet for good, so one new name lost all of it.
    const body = JSON.parse(readFileSync(new URL('../../tests/fixtures/desktop-product-usage-report.json', import.meta.url), 'utf8'))
    const send = vi.fn(async () => ({ status: 200, body: { success: true, data: { accepted: true } } }))
    const { base } = await start({ onProductUsageReport: send })
    const headers = { 'content-type': 'application/json', 'x-adapter-local': '1' }
    const post = (value: unknown, h: Record<string, string> = headers) =>
      fetch(`${base}/api/product-usage/report`, { method: 'POST', headers: h, body: JSON.stringify(value) })
    const newer = { ...body, counters: { ...body.counters, health_desktop_frame_slow_wait: 2, health_desktop_PRIVATE_CANARY: 1 } }
    const kept = await post(newer)
    expect(kept.status).toBe(200)
    expect(kept.headers.get('x-harness-usage-vocabulary')).toBe('7')
    expect(send).toHaveBeenCalledExactlyOnceWith({ ...body,
      counters: { ...body.counters, health_desktop_frame_slow_wait: 2, health_desktop_report_unknown_metric: 1 } })
    expect(JSON.stringify(send.mock.calls)).not.toContain('PRIVATE_CANARY')
    // Everything else is refused as before, and every answer names the vocabulary.
    for (const [refused, h] of [
      [{ ...body, counters: { health_desktop_PRIVATE_CANARY: 1 } }, headers],
      [{ ...newer, counters: { ...newer.counters, turns_started: 1 } }, headers],
      [{ ...newer, prompt: 'PRIVATE_CANARY' }, headers],
      [newer, { 'content-type': 'application/json' }],
    ] as const) {
      const response = await post(refused, h)
      expect(response.status).toBe('x-adapter-local' in h ? 400 : 403)
      expect(response.headers.get('x-harness-usage-vocabulary')).toBe('7')
      expect(await response.text()).not.toContain('PRIVATE_CANARY')
    }
    expect(send).toHaveBeenCalledOnce()
  })
  it('serves the Privacy switch and rejects cross-origin, extra-field and malformed writes', async () => {
    const write = vi.fn(async () => ({ status: 200, body: { success: true, data: { enabled: false, revision: 1 } } }))
    const { base } = await start({ onProductUsageRead: async () => ({ status: 200, body: { success: true, data: { enabled: true, revision: 0 } } }), onProductUsageWrite: write })
    expect((await (await fetch(`${base}/api/product-usage/settings`)).json())).toMatchObject({ data: { enabled: true } })
    const path = `${base}/api/product-usage/settings`
    expect((await fetch(path, { method: 'POST', body: '{"enabled":false}' })).status).toBe(403)
    const headers = { 'x-adapter-local': '1', 'content-type': 'application/json' }
    expect((await fetch(path, { method: 'POST', headers: { ...headers, origin: 'https://untrusted.example' }, body: '{"enabled":false}' })).status).toBe(403)
    expect((await fetch(path, { method: 'POST', headers, body: '{"enabled":false,"userId":"other"}' })).status).toBe(400)
    expect((await fetch(path, { method: 'POST', headers, body: '{"enabled":false}' })).status).toBe(200)
    expect(write).toHaveBeenCalledExactlyOnceWith({ enabled: false })
  })
  it('reads through the account proxy and guards writes with the local header', async () => {
    const snapshot = { accountId: 'owner', revision: 0, features: { focus_bar_creature: false, share_button: false } }
    const write = vi.fn(async (body: unknown) => ({ status: 200, body: { success: true, data: { ...snapshot, echo: body } } }))
    const { base } = await start({ onExperimentalRead: async () => ({ status: 200, body: { success: true, data: snapshot } }), onExperimentalWrite: write })
    expect((await (await fetch(`${base}/api/experimental-settings`)).json())).toEqual({ success: true, data: snapshot })
    const body = { accountId: 'owner', feature: 'share_button', enabled: true }
    expect((await fetch(`${base}/api/experimental-settings`, { method: 'PATCH', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body) })).status).toBe(403)
    expect(write).not.toHaveBeenCalled()
    const saved = await fetch(`${base}/api/experimental-settings`, { method: 'PATCH', headers: { 'content-type': 'application/json', 'x-adapter-local': '1' }, body: JSON.stringify(body) })
    expect(saved.status).toBe(200)
    expect(write).toHaveBeenCalledExactlyOnceWith(body)
    expect((await fetch(`${base}/api/experimental-settings`, { method: 'PATCH', headers: { 'x-adapter-local': '1' }, body: '{bad' })).status).toBe(400)
  })
})

describe('what the person lets agents do', () => {
  it('reads the agents\' settings as this computer keeps them, and writes a change through, guarded by the local header', async () => {
    // The account's experiments (core/experiments.ts `createAgentSettingsSync` answers both): every one off by default.
    const off = { agentsStartAgents: false, pullRequestLine: false, agentMessages: false, signedIn: true }
    const writes: unknown[] = []
    const { base } = await start({
      onAgentSettingsRead: async () => ({ status: 200, body: off }),
      onAgentSettingsWrite: async (body) => { writes.push(body); return { status: 200, body: { ...off, ...(body as object) } } },
    })
    const patch = (body: string, local = true) => fetch(`${base}/api/agent-settings`, { method: 'PATCH', headers: { 'content-type': 'application/json', ...(local ? { 'x-adapter-local': '1' } : {}) }, body })
    expect(await (await fetch(`${base}/api/agent-settings`)).json()).toEqual(off)
    expect((await patch('{"agentMessages":true}', false)).status).toBe(403)
    expect(await (await patch('{"agentMessages":true}')).json()).toEqual({ ...off, agentMessages: true })
    expect((await patch('{bad')).status).toBe(400)
    expect(writes).toEqual([{ agentMessages: true }])
  })

  it('answers UNAVAILABLE without a handler', async () => {
    const { base } = await start({})
    expect((await fetch(`${base}/api/agent-settings`)).status).toBe(503)
    expect((await fetch(`${base}/api/agent-settings`, { method: 'PATCH', headers: { 'x-adapter-local': '1' }, body: '{}' })).status).toBe(503)
  })
})

describe('optional feature routes are absent from core', () => {
  it.each(['/api/zoo', '/api/zoo/ops', '/api/hook/memory-context', '/api/hook/memory-emitted', '/api/hook/opencode-memory-runtime'])(
    'does not handle %s or consult account metadata', async path => {
      const me = vi.fn(async () => ({ status: 200, body: {} }))
      const { base } = await start({ onAuthMe: me })
      const response = await fetch(`${base}${path}`, {
        method: path === '/api/zoo' ? 'GET' : 'POST', headers: { 'x-adapter-local': '1' }, body: path === '/api/zoo' ? undefined : '{}',
      })
      expect(response.status).toBe(404)
      expect(me).not.toHaveBeenCalled()
    },
  )
})

describe('the Harness Store proxy', () => {
  it('forwards a store read with its path and query, and a store write only with the local header', async () => {
    const calls: Array<[string, string, unknown]> = []
    const { base } = await start({
      onStore: async (method, path, body) => { calls.push([method, path, body]); return { status: 200, body: { success: true, data: { ok: method } } } },
    })
    const read = await fetch(`${base}/api/store/harnesses/autonomous/marp/reviews?limit=5`)
    expect(read.status).toBe(200)
    expect(await read.json()).toEqual({ success: true, data: { ok: 'GET' } })

    const crossOrigin = await fetch(`${base}/api/store/harnesses/autonomous/marp/review`, { method: 'PUT', body: JSON.stringify({ rating: 5 }) })
    expect(crossOrigin.status).toBe(403)

    const write = await fetch(`${base}/api/store/harnesses/autonomous/marp/review`, {
      method: 'PUT', headers: { 'x-adapter-local': '1', 'content-type': 'application/json' }, body: JSON.stringify({ rating: 5, title: 'Keynote' }),
    })
    expect(write.status).toBe(200)
    const gone = await fetch(`${base}/api/store/harnesses/autonomous/marp/review`, { method: 'DELETE', headers: { 'x-adapter-local': '1' } })
    expect(gone.status).toBe(200)
    expect(calls).toEqual([
      ['GET', '/api/store/harnesses/autonomous/marp/reviews?limit=5', undefined],
      ['PUT', '/api/store/harnesses/autonomous/marp/review', { rating: 5, title: 'Keynote' }],
      ['DELETE', '/api/store/harnesses/autonomous/marp/review', undefined],
    ])
  })

  it('refuses a store path with anything but id characters in it', async () => {
    const { base } = await start({ onStore: async () => ({ status: 200, body: {} }) })
    expect((await fetch(`${base}/api/store/harnesses/a%20b/reviews`)).status).toBe(400)
    expect((await fetch(`${base}/api/store/ratings`, { method: 'POST', headers: { 'x-adapter-local': '1' } })).status).toBe(405)
  })
})

describe('knownTranscriptFor', () => {
  const sessionId = 'eae0ba40-3d0a-4340-9dd5-0a56ecbc080c'
  const root = mkdtempSync(join(tmpdir(), 'hook-transcript-'))
  const known = join(root, 'openharness', `${sessionId}.jsonl`)
  const announced = join(root, 'openharness-cli', `${sessionId}.jsonl`)
  mkdirSync(join(root, 'openharness'))
  writeFileSync(known, '{}\n')
  const row = { sessionId, transcriptPath: known } as RegisteredSession
  afterAll(() => rmSync(root, { recursive: true, force: true }))

  it('takes the resumed row\'s transcript when Claude Code announced one under the wrong project dir', () => {
    expect(knownTranscriptFor({ engine: 'claude', sessionId, transcriptPath: announced }, row)).toBe(known)
  })

  it('keeps an announced transcript that exists', () => {
    expect(knownTranscriptFor({ engine: 'claude', sessionId, transcriptPath: known }, { ...row, transcriptPath: join(root, 'other.jsonl') })).toBe(known)
  })

  it('retains a failed native correction as unavailable evidence', () => {
    const lookup = vi.spyOn(engineHooks.claude, 'transcriptFor')
      .mockImplementationOnce(() => { throw new Error('lookup failed') })
      .mockImplementationOnce(() => { throw 'lookup failed again' })
    try {
      expect(() => knownTranscriptFor({ sessionId, transcriptPath: announced }, row)).toThrow()
      expect(() => knownTranscriptFor({ sessionId, transcriptPath: announced }, row)).toThrow()
    } finally { lookup.mockRestore() }
  })

  it.each<[string, Parameters<typeof knownTranscriptFor>[0], RegisteredSession | undefined]>([
    ['another conversation', { engine: 'claude', sessionId: 'other-conversation', transcriptPath: announced }, row],
    ['another engine', { engine: 'codex', sessionId, transcriptPath: announced }, row],
    ['a row whose file is not named by the conversation', { engine: 'claude', sessionId, transcriptPath: announced }, { ...row, transcriptPath: join(root, 'openharness', 'renamed.jsonl') }],
    ['a row whose file is gone', { engine: 'claude', sessionId, transcriptPath: announced }, { ...row, transcriptPath: join(root, 'gone', `${sessionId}.jsonl`) }],
    ['no row', { engine: 'claude', sessionId, transcriptPath: announced }, undefined],
    ['no announcement', { engine: 'claude', sessionId }, row],
    ['no conversation id', { engine: 'claude', transcriptPath: announced }, row],
  ])('leaves the announcement alone for %s', (_case, body, agent) => {
    expect(knownTranscriptFor(body, agent)).toBe(body.transcriptPath)
  })
})

describe('chooseHookAgent', () => {
  it('prefers caller ancestry, the evidence that cannot be guessed at', () => {
    expect(chooseHookAgent(['strong'], ['weak'], 'codex')).toEqual({ agent: 'strong', reason: 'ancestry' })
  })

  it('accepts the runtime alone when ancestry is unavailable and the pane is unambiguous', () => {
    // Cursor posts its hooks from outside the pane's process tree — on tmux and on Herdr alike — so
    // demanding ancestry rejected every hook it ever sent and no session bound. The pane is the proof:
    // the hook named a runtime, and that runtime carries exactly one agent of this engine.
    expect(chooseHookAgent([], ['only-agent-on-that-pane'], 'cursor')).toEqual({
      agent: 'only-agent-on-that-pane', reason: 'runtime',
    })
  })

  it('answers nothing rather than guessing', () => {
    expect(chooseHookAgent([], [], 'cursor')).toEqual({ agent: null, reason: 'none' })
    expect(chooseHookAgent([], ['a', 'b'], 'cursor')).toEqual({ agent: null, reason: 'ambiguous' })
    expect(chooseHookAgent(['a', 'b'], ['c'], 'cursor')).toEqual({ agent: null, reason: 'ambiguous' })
  })

  it.each(ENGINES.filter((engine) => engine !== 'cursor'))(
    'rejects a late %s hook when the pane now belongs to a replacement process',
    (engine) => {
      const replacement = { agentId: 'replacement-agent', sessionId: 'new-session' }
      expect(chooseHookAgent([], [replacement], engine)).toEqual({ agent: null, reason: 'none' })
      expect(chooseHookAgent([replacement], [replacement], engine))
        .toEqual({ agent: replacement, reason: 'ancestry' })
    },
  )
})

describe('/api/status', () => {
  it('serves whatever the daemon reports — including the pid the desktop uses to tell daemons apart', async () => {
    const { base } = await start({
      onStatus: () => ({ pid: process.pid, connected: false, restarting: false, discoveryReady: true }),
    })
    const response = await fetch(`${base}/api/status`)
    expect(response.status).toBe(200)
    expect(await response.json()).toEqual({ pid: process.pid, connected: false, restarting: false, discoveryReady: true })
  })
})

describe('browser setup links are gone', () => {
  // They served the retired web client; the route that minted them must not come back.
  it('mints nothing at the old /api/e2ee/setup-link route', async () => {
    const { base } = await start()
    const response = await fetch(`${base}/api/e2ee/setup-link`, { method: 'POST', headers: { 'x-adapter-local': '1' } })
    expect(response.status).not.toBe(200)
    expect(await response.text()).not.toContain('setup=browser')
  })
})

describe('requests must name this server', () => {
  // A page that re-points its hostname at 127.0.0.1 is same-origin to this port; only its Host gives it away.
  async function send(base: string, method: string, path: string, headers: Record<string, string>): Promise<number> {
    const url = new URL(path, base)
    // This OS user's process: it shows the local credential, as every route but liveness wants over the port.
    const credentialed = { 'x-harness-local': readHookCredential(env.ADAPTER_DATA_DIR) ?? '', ...headers }
    return new Promise((resolve, reject) => {
      const r = request({ host: '127.0.0.1', port: url.port, path: url.pathname, method, headers: credentialed }, (res) => { res.resume(); resolve(res.statusCode ?? 0) })
      r.on('error', reject)
      r.end()
    })
  }

  it('refuses every route, reads included, when Host is not a loopback name for this port', async () => {
    const onStatus = vi.fn(() => ({ ok: true }))
    const { base } = await start({ onStatus })
    const evil = { host: 'rebind.evil.example:' + new URL(base).port }
    for (const [method, path, extra] of [
      ['GET', '/api/status', {}], ['GET', '/', {}], ['GET', '/api/machines', {}],
      ['POST', '/api/remote-password/set', { 'x-adapter-local': '1' }], ['POST', '/api/group/sync', { 'x-adapter-local': '1' }],
    ] as const) {
      expect(await send(base, method, path, { ...evil, ...extra }), `${method} ${path}`).toBe(403)
    }
    expect(onStatus).not.toHaveBeenCalled()
  })

  it('serves no web dashboard: its page, log tail and stop button are gone', async () => {
    // Nothing opened the page (no app, website, script or the backend), and the web client that linked to
    // it retired with the browser setup links (#348). `harness stop` stops the daemon by its pid.
    const { base } = await start({ onStatus: () => ({ ok: true }) })
    for (const [method, path] of [['GET', '/'], ['GET', '/index.html'], ['GET', '/api/logs'], ['POST', '/api/stop']] as const) {
      expect(await send(base, method, path, { 'x-adapter-local': '1' }), `${method} ${path}`).toBe(404)
    }
  })

  it('answers every request even when its handler throws, instead of leaving the caller waiting', async () => {
    const error = vi.spyOn(console, 'error').mockImplementation(() => {})
    let failing: 'read' | 'body' = 'read'
    const { base, headers } = await start({
      // A status that cannot be read, then one that cannot be written once its headers went out.
      onStatus: async () => { if (failing === 'read') throw new Error('status read failed'); return { n: 1n } },
      // A hook told "pending" before its resolution failed.
      resolveHookAgent: async ({ onWait }) => { onWait?.(); throw 'resolution failed after the answer' },
    })
    // Before the answer: a 500 the caller can act on, at once.
    const status = await fetch(`${base}/api/status`)
    expect(status.status).toBe(500)
    expect(await status.json()).toEqual({ error: 'INTERNAL' })
    // After the headers went out: the response is ended, not left open.
    failing = 'body'
    const unwritable = await fetch(`${base}/api/status`)
    expect(unwritable.status).toBe(200)
    expect(await unwritable.text()).toBe('')
    // After the response ended: nothing more to send, and nothing breaks.
    const hook = await fetch(`${base}/api/hook/session-start`, {
      method: 'POST', headers, body: JSON.stringify({ engine: 'codex', tmuxPane: '%41', sessionId: '019fea92-e31a-7692-9c35-f616e9d458b7' }),
    })
    expect(hook.status).toBe(202)
    expect(await hook.json()).toMatchObject({ pending: false, retry: true })
    expect(error).toHaveBeenCalledWith('[hooks] GET /api/status failed:', 'status read failed')
    expect(error).toHaveBeenCalledWith('[hooks] GET /api/status failed:', expect.stringContaining('BigInt'))
    await vi.waitFor(() => expect(error).toHaveBeenCalledWith('[hooks] POST /api/hook/session-start failed:', 'resolution failed after the answer'))
    error.mockRestore()
  })

  it('serves a status that has to read before it answers', async () => {
    // A harness's `updatedAt` is when its conversation last moved, which is read from its transcript.
    const { base } = await start({ onStatus: async () => ({ sessions: [{ id: 'a', updatedAt: 42 }] }) })
    const res = await fetch(`${base}/api/status`)
    expect(res.status).toBe(200)
    expect(await res.json()).toEqual({ sessions: [{ id: 'a', updatedAt: 42 }] })
  })

  it('still serves loopback names, and a page from the daemon\'s own origin', async () => {
    const { base } = await start({ onStatus: () => ({ ok: true }) })
    const port = new URL(base).port
    for (const host of [`127.0.0.1:${port}`, `localhost:${port}`, `[::1]:${port}`]) {
      expect(await send(base, 'GET', '/api/status', { host }), host).toBe(200)
    }
    expect(await send(base, 'GET', '/api/status', { host: `localhost:${port}`, origin: `http://localhost:${port}` })).toBe(200)
    expect(await send(base, 'GET', '/api/status', { host: `127.0.0.1:${port}`, origin: 'http://evil.example' })).toBe(403)
  })
})

describe('the trust group endpoints', () => {
  const local = { 'x-adapter-local': '1', 'content-type': 'application/json' }
  const key = Buffer.alloc(32, 7).toString('base64')
  const machineId = 'a'.repeat(32)

  it('trust-peer takes only a real key and machine id, and trims the label', async () => {
    const onTrustLinkedPeer = vi.fn(() => ({ status: 200, body: { ok: true } }))
    const { base } = await start({ onTrustLinkedPeer })
    const post = (body: unknown, headers: Record<string, string> = local) =>
      fetch(`${base}/api/link/trust-peer`, { method: 'POST', headers, body: JSON.stringify(body) })
    for (const bad of [{ pub: 'x', machineId }, { pub: key, machineId: 'nope' }, { machineId }, { pub: `${key}AA`, machineId }]) {
      expect((await post(bad)).status, JSON.stringify(bad)).toBe(400)
    }
    expect((await post({ pub: key, machineId }, { 'content-type': 'application/json' })).status).toBe(403)
    expect((await post({ pub: key, machineId, label: `  ${'n'.repeat(80)} ` })).status).toBe(200)
    expect(onTrustLinkedPeer).toHaveBeenCalledTimes(1)
    expect(onTrustLinkedPeer).toHaveBeenCalledWith({ pub: key, machineId, label: 'n'.repeat(60) })
  })

  it('group remove and sync are local writes; list is readable', async () => {
    const onGroupRemove = vi.fn(() => ({ status: 200, body: { label: 'b', fingerprint: 'fp' } }))
    const onGroupSync = vi.fn(() => ({ status: 200, body: { ok: true } }))
    const onGroupList = vi.fn(() => ({ status: 200, body: { members: [] } }))
    const { base } = await start({ onGroupRemove, onGroupSync, onGroupList })
    expect((await fetch(`${base}/api/group/remove`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: '{"selector":"1"}' })).status).toBe(403)
    expect((await fetch(`${base}/api/group/sync`, { method: 'POST' })).status).toBe(403)
    expect((await fetch(`${base}/api/group/remove`, { method: 'POST', headers: local, body: '{"selector":"  "}' })).status).toBe(400)
    expect((await fetch(`${base}/api/group/remove`, { method: 'POST', headers: local, body: '{"selector":" 1 "}' })).status).toBe(200)
    expect(onGroupRemove).toHaveBeenCalledWith('1')
    expect((await fetch(`${base}/api/group/sync`, { method: 'POST', headers: local })).status).toBe(200)
    expect(await (await fetch(`${base}/api/group`)).json()).toEqual({ members: [] })
  })
})

describe('the daemon socket', () => {
  function viaSocket(socketPath: string, method: string, path: string, headers: Record<string, string> = {}): Promise<number> {
    return new Promise((resolve, reject) => {
      const r = request({ socketPath, path, method, headers }, (res) => { res.resume(); resolve(res.statusCode ?? 0) })
      r.on('error', reject)
      r.end()
    })
  }

  it('serves the same routes with no loopback Host, and keeps every other guard', async () => {
    const dir = mkdtempSync('/tmp/hsock-')
    const socketPath = join(dir, 'daemon.sock')
    const onStatus = vi.fn(() => ({ ok: true }))
    const onAutonomousDeviceRequest = vi.fn(async () => ({ status: 200, body: { ok: true } }))
    const started = await startHookServer(0, { onRegistered: vi.fn(), onSessionEnd: vi.fn(), onStatus, onAutonomousDeviceRequest }, { socketPath })
    server = started.server
    try {
      expect(started.localSocket?.path).toBe(socketPath)
      // Node sends `Host: localhost` without a port over a socket — refused on TCP, fine here.
      expect(await viaSocket(socketPath, 'GET', '/api/status')).toBe(200)
      expect(await viaSocket(socketPath, 'GET', '/api/status', { host: 'rebind.evil.example' })).toBe(200)
      expect(onStatus).toHaveBeenCalledTimes(2)
      // The device routes ask for a loopback PEER; a socket peer has no address and is let in.
      const bearer = { authorization: `Bearer ${readHookCredential(env.ADAPTER_DATA_DIR)}` }
      expect(await viaSocket(socketPath, 'GET', '/api/autonomous-device/status', bearer)).toBe(200)
      expect(await viaSocket(socketPath, 'GET', '/api/autonomous-device/status')).toBe(403)
      expect(onAutonomousDeviceRequest).toHaveBeenCalledTimes(1)
      // Mutations still need the CSRF header, hooks still need their credential.
      expect(await viaSocket(socketPath, 'POST', '/api/group/sync')).toBe(403)
      expect(await viaSocket(socketPath, 'POST', '/api/hook/session-start')).not.toBe(200)
      // The TCP port is untouched: a foreign Host is still refused there.
      const port = (started.server.address() as { port: number }).port
      const tcp = await new Promise<number>((resolve, reject) => {
        const r = request({ host: '127.0.0.1', port, path: '/api/status', headers: { host: 'rebind.evil.example' } }, (res) => { res.resume(); resolve(res.statusCode ?? 0) })
        r.on('error', reject)
        r.end()
      })
      expect(tcp).toBe(403)
    } finally {
      await started.localSocket?.close()
      rmSync(dir, { recursive: true, force: true })
    }
  })

  it('hands out a phone sign-in code over the socket only — never on the loopback port', async () => {
    const dir = mkdtempSync('/tmp/hsock-')
    const socketPath = join(dir, 'daemon.sock')
    const onAuthHandoff = vi.fn(async () => ({ status: 200, body: { success: true, data: { code: 'hnh_x', expiresIn: 90 } } }))
    const started = await startHookServer(0, { onRegistered: vi.fn(), onSessionEnd: vi.fn(), onAuthHandoff }, { socketPath })
    server = started.server
    try {
      const local = { 'x-adapter-local': '1' }
      expect(await viaSocket(socketPath, 'POST', '/api/auth/handoff', local)).toBe(200)
      expect(await viaSocket(socketPath, 'POST', '/api/auth/handoff')).toBe(403)
      const port = (started.server.address() as { port: number }).port
      // Over the port: refused without the local credential, and still refused with it.
      const tcp = await fetch(`http://127.0.0.1:${port}/api/auth/handoff`, { method: 'POST', headers: local })
      expect(tcp.status).toBe(401)
      const credential = readHookCredential(env.ADAPTER_DATA_DIR) ?? ''
      const credentialed = await fetch(`http://127.0.0.1:${port}/api/auth/handoff`, { method: 'POST', headers: { ...local, 'x-harness-local': credential } })
      expect(credentialed.status).toBe(403)
      expect(onAuthHandoff).toHaveBeenCalledTimes(1)
    } finally {
      await started.localSocket?.close()
      rmSync(dir, { recursive: true, force: true })
    }
  })

  it('takes `harness stop` over the trusted endpoint only — never on the loopback port', async () => {
    const dir = mkdtempSync('/tmp/hsock-')
    const socketPath = join(dir, 'daemon.sock')
    const onDaemonStop = vi.fn(async () => ({ status: 202, body: { ok: true } }))
    const started = await startHookServer(0, { onRegistered: vi.fn(), onSessionEnd: vi.fn(), onDaemonStop }, { socketPath })
    server = started.server
    try {
      const local = { 'x-adapter-local': '1' }
      expect(await viaSocket(socketPath, 'POST', '/api/daemon/stop', local)).toBe(202)
      expect(await viaSocket(socketPath, 'POST', '/api/daemon/stop')).toBe(403)
      const port = (started.server.address() as { port: number }).port
      const tcp = await fetch(`http://127.0.0.1:${port}/api/daemon/stop`, { method: 'POST', headers: local })
      expect(tcp.status).toBe(401)
      const credential = readHookCredential(env.ADAPTER_DATA_DIR) ?? ''
      const credentialed = await fetch(`http://127.0.0.1:${port}/api/daemon/stop`, { method: 'POST', headers: { ...local, 'x-harness-local': credential } })
      expect(credentialed.status).toBe(403)
      expect(onDaemonStop).toHaveBeenCalledTimes(1)
    } finally {
      await started.localSocket?.close()
      rmSync(dir, { recursive: true, force: true })
    }
  })

  it('has no `harness stop` route where no handler is given: a Mac or Linux core, unchanged', async () => {
    const dir = mkdtempSync('/tmp/hsock-')
    const socketPath = join(dir, 'daemon.sock')
    const started = await startHookServer(0, { onRegistered: vi.fn(), onSessionEnd: vi.fn() }, { socketPath })
    server = started.server
    try {
      expect(await viaSocket(socketPath, 'POST', '/api/daemon/stop', { 'x-adapter-local': '1' })).toBe(404)
    } finally {
      await started.localSocket?.close()
      rmSync(dir, { recursive: true, force: true })
    }
  })

  it('over the Windows pipe, serves only requests that prove the token, and trusts those', async () => {
    const dir = mkdtempSync('/tmp/hsock-')
    const socketPath = join(dir, `harness-${randomBytes(16).toString('hex')}`)
    const token = randomBytes(32)
    const onAuthHandoff = vi.fn(async () => ({ status: 200, body: { success: true, data: { code: 'hnh_x', expiresIn: 90 } } }))
    const started = await startHookServer(0, { onRegistered: vi.fn(), onSessionEnd: vi.fn(), onAuthHandoff }, { socketPath, pipeToken: token })
    server = started.server
    try {
      const local = { 'x-adapter-local': '1' }
      // The route a Unix socket's file mode guards: here the token is what lets it through.
      expect((await pipeRequest({ pipe: socketPath, token }, { method: 'POST', path: '/api/auth/handoff', headers: local })).status).toBe(200)
      expect(await viaSocket(socketPath, 'POST', '/api/auth/handoff', local)).toBe(401)
      expect(onAuthHandoff).toHaveBeenCalledTimes(1)
    } finally {
      await started.localSocket?.close()
      rmSync(dir, { recursive: true, force: true })
    }
  })

  it('starts on TCP alone when the socket cannot be opened', async () => {
    const dir = mkdtempSync('/tmp/hsock-')
    const blocked = join(dir, 'daemon.sock')
    writeFileSync(blocked, 'not a socket')
    const started = await startHookServer(0, { onRegistered: vi.fn(), onSessionEnd: vi.fn() }, { socketPath: blocked })
    server = started.server
    expect(started.localSocket).toBeNull()
    expect(started.port).toBeGreaterThan(0)
    rmSync(dir, { recursive: true, force: true })
  })
})

describe('the device history and dismiss endpoints', () => {
  const local = { 'x-adapter-local': '1', 'content-type': 'application/json' }

  it('history needs the local header', async () => {
    const onDevicesHistory = vi.fn(async () => ({ status: 200, body: { rows: [], complete: true, frozen: null } }))
    const { base } = await start({ onDevicesHistory })
    expect((await fetch(`${base}/api/devices/history`)).status).toBe(403)
    expect(onDevicesHistory).not.toHaveBeenCalled()
    const ok = await fetch(`${base}/api/devices/history`, { headers: local })
    expect(ok.status).toBe(200)
    expect(await ok.json()).toEqual({ rows: [], complete: true, frozen: null })
  })

  it('dismiss needs the local header, parses the body and refuses bad JSON', async () => {
    const onDevicesDismiss = vi.fn(() => ({ status: 200, body: { ok: true } }))
    const { base } = await start({ onDevicesDismiss })
    const post = (body: string, headers: Record<string, string> = local) => fetch(`${base}/api/devices/dismiss`, { method: 'POST', headers, body })
    expect((await post('{}', { 'content-type': 'application/json' })).status).toBe(403)
    expect(onDevicesDismiss).not.toHaveBeenCalled()
    expect((await post('{bad')).status).toBe(400)
    expect((await post(JSON.stringify({ pub: 5 }))).status).toBe(400)
    expect((await post(JSON.stringify({ pub: 'k' }))).status).toBe(200)
    expect(onDevicesDismiss).toHaveBeenLastCalledWith({ pub: 'k' })
    expect((await post(JSON.stringify({ baseline: true }))).status).toBe(200)
    expect(onDevicesDismiss).toHaveBeenLastCalledWith({ baseline: true })
    expect((await post('{}')).status).toBe(200)
    expect(onDevicesDismiss).toHaveBeenLastCalledWith({})
    // The keys a window displayed: a list of strings, bounded.
    expect((await post(JSON.stringify({ pubs: ['a', 'b'] }))).status).toBe(200)
    expect(onDevicesDismiss).toHaveBeenLastCalledWith({ pubs: ['a', 'b'] })
    expect((await post(JSON.stringify({ pubs: 'a' }))).status).toBe(400)
    expect((await post(JSON.stringify({ pubs: ['a', 5] }))).status).toBe(400)
    expect((await post(JSON.stringify({ pubs: Array.from({ length: 257 }, (_, i) => `k${i}`) }))).status).toBe(400)
    // "It's mine": only a literal true asks for the other devices to be told.
    expect((await post(JSON.stringify({ pubs: ['a'], confirm: true }))).status).toBe(200)
    expect(onDevicesDismiss).toHaveBeenLastCalledWith({ pubs: ['a'], confirm: true })
    expect((await post(JSON.stringify({ pub: 'k', confirm: 'yes' }))).status).toBe(200)
    expect(onDevicesDismiss).toHaveBeenLastCalledWith({ pub: 'k' })
  })

  it('rebaseline passes the previewed head on, and refuses a malformed one', async () => {
    const onDevicesRebaseline = vi.fn(async () => ({ status: 200, body: {} }))
    const { base } = await start({ onDevicesRebaseline })
    const post = (body: unknown) => fetch(`${base}/api/devices/rebaseline`, { method: 'POST', headers: local, body: JSON.stringify(body) })
    expect((await post({ confirm: true, head: { seq: 3, hash: 'h' } })).status).toBe(200)
    expect(onDevicesRebaseline).toHaveBeenLastCalledWith(true, { seq: 3, hash: 'h' })
    expect((await post({ confirm: true })).status).toBe(200)
    expect(onDevicesRebaseline).toHaveBeenLastCalledWith(true, undefined)
    expect((await post({ confirm: true, head: { seq: -1, hash: 'h' } })).status).toBe(400)
    expect((await post({ confirm: true, head: 'x' })).status).toBe(400)
  })
})


it.each(['/api/hook/session-end', '/api/hook/turn-start', '/api/hook/tool-start', '/api/hook/turn-stop'])(
  'refuses a binding changed during process resolution on %s', async path => {
    const row = { engine: 'claude', sessionId: 'race-session', agentId: 'race-agent', runtimes: [], processIdentity: null,
      evidenceRevision: 1 } as unknown as RegisteredSession
    vi.spyOn(registry, 'bySession').mockReturnValue(row)
    vi.spyOn(registry, 'byAgent').mockReturnValue(row)
    const mutation = vi.fn()
    const { base, headers } = await start({ onSessionEnd: mutation, onTurnStart: mutation, onToolStart: mutation, onTurnStop: mutation,
      resolveHookAgent: async () => { await Promise.resolve(); row.evidenceRevision = 2; return row } })
    const response = await fetch(`${base}${path}`, { method: 'POST', headers,
      body: JSON.stringify({ engine: 'claude', sessionId: row.sessionId, tmuxPane: '%1', callerPid: 4242,
        toolUseId: 'fixture-tool', toolName: 'Task' }) })
    expect(response.status).toBe(403)
    expect(mutation).not.toHaveBeenCalled()
  },
)

describe('audit H1: what a secret heard on the daemon\'s port can do', () => {
  const call = (port: number, path: string, headers: Record<string, string>, method = 'GET') =>
    fetch(`http://127.0.0.1:${port}${path}`, { method, headers, ...(method === 'POST' ? { body: '{}' } : {}) })

  const serve = async (peerAccount: () => Promise<boolean>) => {
    const started = await startHookServer(0, {
      onRegistered: vi.fn(), onSessionEnd: vi.fn(), onStatus: async () => ({ supported: true, secretDetail: 'x' }),
      onAutonomousDeviceRequest: async () => ({ status: 200, body: { ok: true } }),
    }, { peerAccount })
    return { port: started.port, close: () => new Promise<void>((resolve) => { started.server.closeAllConnections(); started.server.close(() => resolve()) }) }
  }
  const credential = () => readFileSync(join(env.ADAPTER_DATA_DIR, 'hook-credential'), 'utf8').trim()
  const hookToken = () => readFileSync(join(env.ADAPTER_DATA_DIR, 'hook-token'), 'utf8').trim()

  it('the credential opens nothing for a caller of another account', async () => {
    const asked = vi.fn(async () => false)
    const { port, close } = await serve(asked)
    try {
      const secret = credential()
      expect((await call(port, '/api/machines', { 'X-Harness-Local': secret })).status).toBe(401)
      expect((await call(port, '/api/machines', { Authorization: `Bearer ${secret}` })).status).toBe(401)
      expect(await (await call(port, '/api/status', { 'X-Harness-Local': secret })).json()).not.toHaveProperty('secretDetail')
      expect((await call(port, '/api/autonomous-device/status', { Authorization: `Bearer ${secret}` })).status).toBe(403)
      expect(asked).toHaveBeenCalled()
    } finally { await close() }
  })

  it('the credential works for a caller of this account', async () => {
    const { port, close } = await serve(async () => true)
    try {
      expect(await (await call(port, '/api/status', { 'X-Harness-Local': credential() })).json()).toHaveProperty('secretDetail')
      expect((await call(port, '/api/autonomous-device/status', { Authorization: `Bearer ${credential()}` })).status).toBe(200)
    } finally { await close() }
  })

  it('a wrong credential never makes the daemon ask who is calling', async () => {
    const asked = vi.fn(async () => true)
    const { port, close } = await serve(asked)
    try {
      expect((await call(port, '/api/machines', { 'X-Harness-Local': 'w'.repeat(43) })).status).toBe(401)
      expect(asked).not.toHaveBeenCalled()
    } finally { await close() }
  })

  it('the hook token opens the hook routes and nothing else', async () => {
    const { port, close } = await serve(async () => true)
    try {
      const token = hookToken()
      expect(token).not.toBe(credential())
      expect((await call(port, '/api/hook/session-start', { 'x-harness-hook-token': token }, 'POST')).status).not.toBe(401)
      const shown: Array<Record<string, string>> = [{ 'X-Harness-Local': token }, { Authorization: `Bearer ${token}` }, { 'x-harness-hook-token': token }]
      for (const headers of shown) {
        expect((await call(port, '/api/machines', headers)).status).toBe(401)
        expect(await (await call(port, '/api/status', headers)).json()).not.toHaveProperty('secretDetail')
        expect((await call(port, '/api/autonomous-device/status', headers)).status).toBe(403)
      }
    } finally { await close() }
  })

  it('a hook token or credential opens no hook route for a caller of another account', async () => {
    const { port, close } = await serve(async () => false)
    try {
      for (const secret of [hookToken(), credential()]) {
        expect((await call(port, '/api/hook/session-start', { 'x-harness-hook-token': secret }, 'POST')).status).toBe(401)
        expect((await call(port, '/api/hook/session-end', { 'x-harness-hook-token': secret }, 'POST')).status).toBe(401)
      }
    } finally { await close() }
  })

  it('an engine plugin loaded before the hook token keeps reporting with the credential', async () => {
    const { port, close } = await serve(async () => true)
    try {
      expect((await call(port, '/api/hook/session-start', { 'x-harness-hook-token': credential() }, 'POST')).status).not.toBe(401)
    } finally { await close() }
  })
})

describe('the loopback port wants this OS user\'s local credential', () => {
  // Another OS user's process reaches 127.0.0.1 too — a guest's harness running as its own user
  // (docs/plans/2026-10-19-guest-machine-sharing-plan.md). Only this user can read the 0600 credential.
  const raw = (port: number, method: string, path: string, headers: Record<string, string> = {}): Promise<{ status: number; body: string }> =>
    new Promise((resolve, reject) => {
      const r = request({ host: '127.0.0.1', port, path, method, headers }, (res) => {
        let body = ''
        res.setEncoding('utf8')
        res.on('data', (chunk: string) => { body += chunk })
        res.on('end', () => resolve({ status: res.statusCode ?? 0, body }))
      })
      r.on('error', reject)
      r.end()
    })

  it('refuses every route without it, takes it by header or bearer, and leaves liveness and the hook routes alone', async () => {
    const onMachinesList = vi.fn(async () => ({ status: 200, body: { success: true, data: { machines: [] } } }))
    const started = await startHookServer(0, {
      onRegistered: vi.fn(), onSessionEnd: vi.fn(), onMachinesList,
      onStatus: () => ({ version: '9.9.9', pid: 42, corePid: 43, computerId: 'c1', machineId: 'm1', dataDir: '/secret/data', signedIn: true, localWs: { path: '/api/local-ws' }, localSocket: null }),
    } as Partial<HookServerHandlers> as HookServerHandlers)
    server = started.server
    const port = started.port
    const credential = readHookCredential(env.ADAPTER_DATA_DIR)!
    // Without it: the account's routes, reads and writes alike, are refused.
    for (const [method, path] of [['GET', '/api/machines'], ['GET', '/api/pairs'], ['POST', '/api/revoke-all'], ['GET', '/api/agent-settings'], ['GET', '/nowhere']] as const) {
      const answer = await raw(port, method, path, { 'x-adapter-local': '1' })
      expect(answer.status, `${method} ${path}`).toBe(401)
      expect(JSON.parse(answer.body)).toEqual({ error: 'LOCAL_CREDENTIAL_REQUIRED' })
    }
    // A wrong one is no better.
    expect((await raw(port, 'GET', '/api/machines', { 'x-harness-local': 'x'.repeat(43) })).status).toBe(401)
    // With it, by its header or as a bearer.
    expect((await raw(port, 'GET', '/api/machines', { 'x-harness-local': credential })).status).toBe(200)
    expect((await raw(port, 'GET', '/api/machines', { authorization: `Bearer ${credential}` })).status).toBe(200)
    expect(onMachinesList).toHaveBeenCalledTimes(2)
    // Liveness answers anyone; the status, only who the daemon is and where its socket is.
    expect((await raw(port, 'GET', '/api/health')).status).toBe(200)
    const open = await raw(port, 'GET', '/api/status')
    expect(open.status).toBe(200)
    expect(JSON.parse(open.body)).toEqual({ credentialRequired: true, version: '9.9.9', pid: 42, corePid: 43, computerId: 'c1', localWs: { path: '/api/local-ws' }, localSocket: null })
    const whole = JSON.parse((await raw(port, 'GET', '/api/status', { 'x-harness-local': credential })).body)
    expect(whole).toMatchObject({ machineId: 'm1', dataDir: '/secret/data', signedIn: true })
    // A hook route keeps its own token: refused for want of it, not of the local credential.
    const hook = await raw(port, 'POST', '/api/hook/session-end')
    expect(hook.status).toBe(401)
    expect(JSON.parse(hook.body)).toEqual({ error: 'UNAUTHORIZED' })
  })

  const viaSocket = (socketPath: string, method: string, path: string): Promise<number> =>
    new Promise((resolve, reject) => {
      const r = request({ socketPath, path, method }, (res) => { res.resume(); resolve(res.statusCode ?? 0) })
      r.on('error', reject)
      r.end()
    })

  it('takes nothing over the daemon\'s own socket', async () => {
    const dir = mkdtempSync('/tmp/hsock-')
    const socketPath = join(dir, 'daemon.sock')
    const onMachinesList = vi.fn(async () => ({ status: 200, body: { success: true, data: { machines: [] } } }))
    const started = await startHookServer(0, { onRegistered: vi.fn(), onSessionEnd: vi.fn(), onMachinesList } as Partial<HookServerHandlers> as HookServerHandlers, { socketPath })
    server = started.server
    try {
      expect(await viaSocket(socketPath, 'GET', '/api/machines')).toBe(200)
      expect(onMachinesList).toHaveBeenCalledTimes(1)
    } finally {
      await started.localSocket?.close()
      rmSync(dir, { recursive: true, force: true })
    }
  })
})