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.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
import { execFileSync, spawn, spawnSync } from 'child_process'
import { randomBytes } from 'crypto'
import { createServer } from 'http'
import { connect as netConnect, createServer as createNetServer } from 'net'
import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, statSync, symlinkSync, writeFileSync } from 'fs'
import { tmpdir } from 'os'
import { dirname, join } from 'path'
import { fileURLToPath, pathToFileURL } from 'url'
import { afterEach, describe, expect, it, vi } from 'vitest'
import { ENGINES } from './engines/types.js'
import { HARNESS_OWNER_OPTION, HARNESS_SESSION_PREFIX, harnessPaneOwner, ownerCommand, paneOwnerFormat } from './lib/harnessSessionLabel.js'
import { hookRouteFile, publishHookRoute } from './lib/hookRoutes.js'
import { hookTokenPath } from './lib/hookAuth.js'
import { isTrustedLocal, listenLocalSocket, localSocketName, socketPathIn } from './lib/localSocket.js'
// Every case here spawns the real hook as a child process, and several spawn shell shims for tmux, ps
// and sqlite3 on top of that. On a loaded machine — this file runs alongside 88 others — that chain
// takes well over vitest's 5s default, and the failure looks like a product bug rather than what it is.
// The hook's own budget still bounds it; this only stops the harness from calling time first.
vi.setConfig({ testTimeout: 30_000, hookTimeout: 30_000 })
const HOOK = fileURLToPath(new URL('../hook/notify.mjs', import.meta.url))
/** A preload that moves `Date` by the milliseconds in a file (e2e/harness/clockShift.mjs). */
const CLOCK_SHIFT = fileURLToPath(new URL('../e2e/harness/clockShift.mjs', import.meta.url))
const servers: ReturnType<typeof createServer>[] = []
const netServers: ReturnType<typeof createNetServer>[] = []
const tmpDirs: string[] = []
/** The daemon's pipe servers of the Windows cases, each closed with its own close. */
const pipeServers: Array<() => Promise<void>> = []
/** A pid that ran and has exited: a daemon that is gone. */
function exitedPid(): number {
return spawnSync(process.execPath, ['-e', '']).pid!
}
function writeLegacyStateFile(path: string, value: string): void {
writeFileSync(path, value, { mode: 0o644 })
chmodSync(path, 0o644)
}
afterEach(async () => {
await Promise.all(servers.splice(0).map((server) => new Promise<void>((resolve) => server.close(() => resolve()))))
await Promise.all(netServers.splice(0).map((server) => new Promise<void>((resolve) => server.close(() => resolve()))))
await Promise.all(pipeServers.splice(0).map((close) => close()))
for (const dir of tmpDirs.splice(0)) rmSync(dir, { recursive: true, force: true })
})
/**
* The daemon's socket, as the hook now reaches it (audit H1), in front of a test's fake daemon on [port]. A connection
* to a port nobody holds is cut, as a daemon that is down. A folder that does not exist yet stays without one.
*/
/** A home short enough to hold the hook's socket folder (lib/localSocket.ts shortSocketFolder) on any machine, even under
* an agent's long TMPDIR, so a case about the socket route takes it. */
function shortHome(): string {
const home = mkdtempSync('/tmp/hh-')
tmpDirs.push(home)
return home
}
/** The daemon's way in, where the hook looks for it (lib/localSocket.ts socketPathIn, mirrored in hook/notify.mjs): its
* socket beside the data, or in a short folder under `home` when that path is too long for a socket. With no path short
* enough the hook posts to the port with the hook-only token, which the daemon keeps beside its data. */
async function daemonSocketFor(port: number, dataDir: string | undefined, home?: string): Promise<void> {
if (!dataDir || !existsSync(dataDir)) return
const path = socketPathIn(dataDir, localSocketName(port), home)
if (!path) {
try { writeFileSync(hookTokenPath(dataDir), `${'b'.repeat(43)}\n`, { mode: 0o600, flag: 'wx' }) } catch { /* already exists */ }
return
}
if (existsSync(path)) return
mkdirSync(dirname(path), { recursive: true, mode: 0o700 })
const proxy = createNetServer((client) => {
const upstream = netConnect(port, '127.0.0.1')
client.on('error', () => upstream.destroy())
upstream.on('error', () => client.destroy())
client.pipe(upstream).pipe(client)
})
netServers.push(proxy)
await new Promise<void>((resolve) => { proxy.listen(path, resolve) })
chmodSync(path, 0o600)
}
interface RunHookOpts {
port: number
tmuxPane?: string
/** Legacy environment noise: process-owned hooks must behave the same with or without it. */
launcherId?: string | null
/** Install deterministic tmux/ps fixtures so an offline fallback can prove process ownership. */
processEngine?: 'claude' | 'codex' | 'cursor' | 'hermes' | 'devin' | 'commandcode' | 'grok'
/** The tmux session the pane is in, and the daemon tag on it (`@harness_daemon`). */
paneSession?: string
paneOwner?: string
/** How long the fake tmux takes to answer each call, in seconds: a hook that spent its budget early. */
tmuxDelaySeconds?: number
/** Override the fixture's ps `comm` and full argv to exercise install-root-independent matching. */
processExecutable?: string
processArgs?: string
/** Kernel birth evidence for the synthetic process; never read an unrelated host pid. */
nativeProcess?: 'linux' | 'missing' | 'changed' | 'lock-replaced' | 'boot-replaced' | 'registry-replaced'
| 'zombie' | 'registry-zombie' | 'registry-command' | 'registry-reparented' | 'short' | 'wrong-pid'
engine?: 'claude' | 'codex' | 'cursor' | 'hermes' | 'devin' | 'commandcode' | 'grok'
/** Run as on Windows: the process table comes from `harness-pty ps --json` (a fake), and `ps` fails. */
windowsProcessTable?: boolean
env?: Record<string, string>
dataDir?: string
claudeProjectsDir?: string
codexHome?: string
cursorHome?: string
hermesHome?: string
/** Fake Hermes SQLite source; null means the session row has not appeared. */
hermesSource?: 'cli' | 'tui' | 'subagent' | null
/** How long Hermes' store takes to answer, in the shipped hook's seconds: a loaded machine. Stretched
* as the hook stretches its own step limits under HARNESS_HOOK_DEADLINE_MS (notify.mjs STEP_SCALE),
* so the delay keeps the same share of the sqlite3 limit whatever the budget. */
hermesDelaySeconds?: number
grokHome?: string
devinHome?: string
input?: Record<string, unknown>
}
function runHook(opts: RunHookOpts): Promise<string> {
return new Promise((resolve, reject) => {
const env = { ...process.env }
delete env.HARNESS_PANE
// The hook abandons its optional work (including the offline registry fallback) when its 4.5s
// wall-clock budget runs out. Under a full parallel run that budget is spent on host load, not on
// the hook, and the assertion below then reads a registry nobody wrote — measured as roughly one
// failure in five full-suite runs. Give the child room so these specs test behaviour, not the load
// on the machine running them.
env.HARNESS_HOOK_DEADLINE_MS = '30000'
if (opts.env) Object.assign(env, opts.env)
delete env.TMUX_PANE
if (opts.tmuxPane) env.TMUX_PANE = opts.tmuxPane
// Every hook asks tmux whose pane it is (notify.mjs routeToPaneOwner). Without a shim below, that
// question must reach no server at all, least of all the developer's: TMUX outranks TMUX_TMPDIR, and
// TMUX_TMPDIR has to exist or tmux falls back to the default socket.
delete env.TMUX
env.TMUX_TMPDIR = mkdtempSync(join(tmpdir(), 'adapter-hook-tmux-'))
tmpDirs.push(env.TMUX_TMPDIR)
delete env.MACHINE_ID
if (opts.launcherId !== null) env.MACHINE_ID = opts.launcherId ?? '11111111-2222-4333-8444-555555555555'
if (opts.processEngine || opts.paneOwner !== undefined || opts.paneSession !== undefined) {
const binDir = mkdtempSync(join(tmpdir(), 'adapter-hook-bin-'))
tmpDirs.push(binDir)
const shellQuote = (value: string) => "'" + value.replace(/'/g, "'\\''") + "'"
// The pane as tmux describes it: its root process, and the session and tag that say whose agent it
// is (a Harness session, untagged, unless the test says otherwise).
const paneFacts = `${opts.paneSession ?? 'harness-claude-1790000000000'}|${opts.paneOwner ?? ''}`
const tmuxDelay = opts.tmuxDelaySeconds ? `sleep ${opts.tmuxDelaySeconds}\n` : ''
writeFileSync(join(binDir, 'tmux'), `#!/bin/sh\n${tmuxDelay}printf '%s\\n' ${shellQuote(`7000|${paneFacts}`)}\n`, { mode: 0o755 })
env.PATH = `${binDir}:${env.PATH ?? ''}`
}
if (opts.processEngine) {
const binDir = mkdtempSync(join(tmpdir(), 'adapter-hook-bin-'))
tmpDirs.push(binDir)
const executable = opts.processExecutable ?? (opts.processEngine === 'cursor' ? 'agent' : opts.processEngine)
const processArgs = opts.processArgs ?? executable
const shellQuote = (value: string) => "'" + value.replace(/'/g, "'\\''") + "'"
if (opts.windowsProcessTable) {
// The same three processes as the `ps` below, as the host lists them, with one it could not open.
const table = { rows: [
{ pid: 4, parentPid: 0, executable: 'System', startMarker: '', args: 'System', nativeArgv: ['System'] },
{ pid: 7000, parentPid: 1, executable: 'pwsh.exe', startMarker: 'w:133000000000000000', args: 'pwsh.exe', nativeArgv: ['pwsh.exe'] },
{ pid: 7001, parentPid: 7000, executable, startMarker: 'w:133000000000000001', args: processArgs, nativeArgv: processArgs.split(' ') },
{ pid: process.pid, parentPid: 7001, executable: 'node.exe', startMarker: 'w:133000000000000002', args: 'hook-parent', nativeArgv: ['hook-parent'] },
] }
writeFileSync(join(binDir, 'harness-pty'), `#!/bin/sh\n[ "$1 $2" = "ps --json" ] || exit 2\nprintf '%s\\n' ${shellQuote(JSON.stringify(table))}\n`, { mode: 0o755 })
env.HARNESS_PTY_BIN = join(binDir, 'harness-pty')
writeFileSync(join(binDir, 'ps'), '#!/bin/sh\nexit 1\n', { mode: 0o755 })
} else {
writeFileSync(join(binDir, 'ps'), `#!/bin/sh\nprintf '%s\\n' '7000 1 zsh Mon Aug 10 10:00:00 2026 -zsh' ${shellQuote(`7001 7000 ${executable} Mon Aug 10 10:00:01 2026 ${processArgs}`)} '${process.pid} 7001 node Mon Aug 10 10:00:02 2026 hook-parent'\n`, { mode: 0o755 })
}
const nativeFixture = join(binDir, 'native-process.mjs')
writeFileSync(nativeFixture, `import fs from 'node:fs'; import { syncBuiltinESMExports } from 'node:module';
${opts.nativeProcess ? "Object.defineProperty(process, 'platform', { value: 'linux' });" : ''}
${opts.windowsProcessTable ? "Object.defineProperty(process, 'platform', { value: 'win32' });" : ''}
const original = fs.readFileSync, open = fs.openSync, close = fs.closeSync, sync = fs.fsyncSync;
const opened = new Map(), fault = ${JSON.stringify(opts.nativeProcess ?? '')}; let reads = 0, replaced = false;
fs.openSync = (path, ...args) => { const fd = open(path, ...args); opened.set(fd, String(path)); return fd; };
fs.closeSync = (fd, ...args) => { opened.delete(fd); return close(fd, ...args); };
fs.fsyncSync = (fd, ...args) => {
const result = sync(fd, ...args), path = opened.get(fd) || '';
if (fault === 'lock-replaced' && path.endsWith('/registry.json.lock/owner.json')
|| fault === 'boot-replaced' && path.includes('/registry-boot.') && path.endsWith('.tmp')
|| fault.startsWith('registry-') && path.includes('/registry.json.') && path.endsWith('.tmp')) replaced = true;
return result;
};
fs.readFileSync = (path, ...args) => {
if (String(path) !== '/proc/7001/stat') return original(path, ...args);
if (fault === 'missing') throw Object.assign(Error('fixture process unavailable'), { code: 'ENOENT' });
if (fault === 'short') return '7001 (claude) S 7000\\n';
const ticks = fault === 'changed' && reads++ > 0 || replaced && fault.endsWith('-replaced') ? 12346 : 12345;
const state = fault === 'zombie' || fault === 'registry-zombie' && replaced ? 'Z' : 'S';
const command = fault === 'registry-command' && replaced ? 'replacement' : ${JSON.stringify(executable)};
const parent = fault === 'registry-reparented' && replaced ? 1 : 7000;
return (fault === 'wrong-pid' ? '7002' : '7001') + ' (' + command + ') ' + state
+ ' ' + parent + ' ' + Array(17).fill(0).join(' ') + ' ' + ticks + ' ' + Array(30).fill(0).join(' ') + '\\n';
}; syncBuiltinESMExports();\n`)
env.NODE_OPTIONS = `${env.NODE_OPTIONS ?? ''} --import ${nativeFixture}`.trim()
if (opts.processEngine === 'cursor') {
const target = join(binDir, 'cursor-agent-target')
writeFileSync(target, '#!/bin/sh\n', { mode: 0o755 })
symlinkSync(target, join(binDir, 'agent'))
symlinkSync(target, join(binDir, 'cursor-agent'))
} else if (opts.processEngine === 'grok') {
const target = join(binDir, 'grok-target')
writeFileSync(target, '#!/bin/sh\n', { mode: 0o755 })
symlinkSync(target, join(binDir, 'agent'))
symlinkSync(target, join(binDir, 'grok'))
}
if (opts.hermesSource !== undefined) {
const rows = opts.hermesSource === null ? '[]' : JSON.stringify([{ source: opts.hermesSource }])
const stepScale = Number(env.HARNESS_HOOK_DEADLINE_MS) / 4500
const delay = opts.hermesDelaySeconds ? `sleep ${opts.hermesDelaySeconds * stepScale}\n` : ''
writeFileSync(join(binDir, 'sqlite3'), `#!/bin/sh\n${delay}printf '%s\\n' '${rows}'\n`, { mode: 0o755 })
}
env.PATH = `${binDir}:${env.PATH ?? ''}`
}
const args = [HOOK, '--port', String(opts.port)]
if (opts.engine && opts.engine !== 'claude') args.push('--engine', opts.engine)
if (opts.dataDir) args.push('--data-dir', opts.dataDir)
if (opts.claudeProjectsDir) args.push('--claude-projects-dir', opts.claudeProjectsDir)
if (opts.codexHome) args.push('--codex-home', opts.codexHome)
if (opts.cursorHome) args.push('--cursor-home', opts.cursorHome)
if (opts.hermesHome) args.push('--hermes-home', opts.hermesHome)
if (opts.grokHome) args.push('--grok-home', opts.grokHome)
if (opts.devinHome) args.push('--devin-home', opts.devinHome)
const hookDataDir = opts.dataDir || process.env.ADAPTER_DATA_DIR
if (hookDataDir) {
mkdirSync(hookDataDir, { recursive: true, mode: 0o700 })
try { writeFileSync(join(hookDataDir, 'hook-credential'), `${'a'.repeat(43)}\n`, { mode: 0o600, flag: 'wx' }) } catch { /* already exists */ }
}
daemonSocketFor(opts.port, hookDataDir, env.HOME).then(() => {
const child = spawn(process.execPath, args, {
env,
stdio: ['pipe', 'pipe', 'inherit'],
})
let stdout = ''
child.stdout.setEncoding('utf8')
child.stdout.on('data', (chunk) => { stdout += chunk })
child.on('error', reject)
child.on('close', (code) => code === 0 ? resolve(stdout) : reject(new Error(`notify.mjs exited ${code}`)))
child.stdin.end(JSON.stringify(opts.input ?? {
hook_event_name: 'SessionEnd',
session_id: 'session-test',
reason: 'logout',
}))
}, reject)
})
}
/** A throwaway localhost adapter that records every hook POST. */
async function collect(response: Record<string, unknown> = {}, credential?: string): Promise<{ port: number; requests: Array<{ url: string; body: Record<string, unknown> }>; firedAts: Array<string | undefined> }> {
const requests: Array<{ url: string; body: Record<string, unknown> }> = []
const firedAts: Array<string | undefined> = []
const server = createServer((req, res) => {
// Local service discovery may probe a test port. Only hook POSTs belong to this fixture.
if (req.method !== 'POST') { res.writeHead(405).end(); return }
if (credential && req.headers['x-harness-hook-token'] !== credential) { req.resume(); res.writeHead(401).end(); return }
let raw = ''
req.on('data', (chunk) => { raw += chunk.toString() })
req.on('end', () => {
requests.push({ url: req.url ?? '', body: JSON.parse(raw) as Record<string, unknown> })
firedAts.push(req.headers['x-harness-hook-fired-at'] as string | undefined)
res.end(JSON.stringify(response))
})
})
servers.push(server)
await new Promise<void>((resolve, reject) => {
server.once('error', reject)
server.listen(0, '127.0.0.1', () => resolve())
})
const address = server.address()
if (!address || typeof address === 'string') throw new Error('test server did not bind a TCP port')
return { port: address.port, requests, firedAts }
}
describe('hook notify terminal scope', () => {
it.each(['claude', 'codex'] as const)('ignores a stale %s memory response and only reports ordinary session registration', async engine => {
const additionalContext = 'Historical coding memory: keep review changes small.'
const memoryReceiptId = 'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee'
const { port, requests } = await collect({ ok: true, additionalContext, memoryReceiptId })
const recordings = JSON.parse(readFileSync(new URL('./lib/__fixtures__/swarm-prompt-hooks.json', import.meta.url), 'utf8'))
const input = recordings[engine].input
const stdout = await runHook({ port, engine, tmuxPane: '%42', input })
expect(stdout).toBe('')
expect(requests.map(request => request.url)).toEqual(['/api/hook/session-start'])
})
it('never acknowledges a receipt without emitted user-turn context', async () => {
const { port, requests } = await collect({ ok: true, memoryReceiptId: 'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee' })
const recordings = JSON.parse(readFileSync(new URL('./lib/__fixtures__/swarm-prompt-hooks.json', import.meta.url), 'utf8'))
expect(await runHook({ port, engine: 'claude', tmuxPane: '%42', input: recordings.claude.input })).toBe('')
expect(requests.map(request => request.url)).toEqual(['/api/hook/session-start'])
})
it.each(['claude', 'codex'] as const)('does not inject companion context returned by an older adapter into a %s user turn', async engine => {
const additionalContext = 'Companions collection context: selected GNU; retain this conversation.'
const { port, requests } = await collect({ ok: true, additionalContext })
const recordings = JSON.parse(readFileSync(new URL('./lib/__fixtures__/swarm-prompt-hooks.json', import.meta.url), 'utf8'))
const input = recordings[engine].input
const stdout = await runHook({ port, engine, tmuxPane: '%42', input })
expect(stdout).toBe('')
expect(requests[0]?.body.prompt).toBe(input.prompt)
expect(await runHook({ port, engine, tmuxPane: '%42', input: { ...input, hook_event_name: 'SessionStart' } })).toBe('')
})
// What tells a late Stop from the turn the next prompt opened (src/hookServer.ts hookFiredAt).
it('says when its engine ran it: its own start, no later than it sends', async () => {
const { port, firedAts } = await collect()
const recordings = JSON.parse(readFileSync(new URL('./lib/__fixtures__/swarm-prompt-hooks.json', import.meta.url), 'utf8'))
const before = Date.now()
await runHook({ port, engine: 'claude', tmuxPane: '%42', input: recordings.claude.input })
const firedAt = Number(firedAts[0])
expect(Number.isSafeInteger(firedAt)).toBe(true)
expect(firedAt).toBeGreaterThanOrEqual(before - 1_000)
expect(firedAt).toBeLessThanOrEqual(Date.now())
})
it.each(['claude', 'codex', 'grok'] as const)('forwards the actual %s accepted prompt without changing the model input', async engine => {
const { port, requests } = await collect()
const recordings = JSON.parse(readFileSync(new URL('./lib/__fixtures__/swarm-prompt-hooks.json', import.meta.url), 'utf8'))
const input = recordings[engine].input
const stdout = await runHook({ port, engine, tmuxPane: '%42', input })
expect(requests).toContainEqual({ url: '/api/hook/session-start', body: expect.objectContaining({
hookEvent: 'UserPromptSubmit', prompt: input.prompt, engine,
}) })
expect(stdout).toBe('')
})
it.each(['claude', 'codex', 'grok'] as const)('still announces an oversized %s prompt so earlier scope is cleared', async engine => {
const { port, requests } = await collect()
const recordings = JSON.parse(readFileSync(new URL('./lib/__fixtures__/swarm-prompt-hooks.json', import.meta.url), 'utf8'))
for (const prompt of ['x'.repeat(140_000), '\u0000'.repeat(30_000)]) {
const stdout = await runHook({ port, engine, tmuxPane: '%42', input: { ...recordings[engine].input, prompt } })
expect(stdout).toBe('')
}
expect(requests).toHaveLength(2)
for (const request of requests) expect(request).toMatchObject({ url: '/api/hook/session-start', body: {
hookEvent: 'UserPromptSubmit', prompt: '', engine,
} })
})
it('refuses a symlinked hook credential instead of authenticating with its target', async () => {
const dir = mkdtempSync(join(tmpdir(), 'adapter-hook-credential-link-'))
tmpDirs.push(dir)
const dataDir = join(dir, 'data')
const target = join(dir, 'credential-target')
mkdirSync(dataDir, { recursive: true })
writeFileSync(target, `${'a'.repeat(43)}\n`, { mode: 0o600 })
symlinkSync(target, join(dataDir, 'hook-credential'))
const { port, requests } = await collect()
// The credential goes only over the socket: a home that holds one, whatever this machine's TMPDIR.
await runHook({ port, tmuxPane: '%42', dataDir, env: { HOME: shortHome() } })
expect(requests).toEqual([])
})
it('rejects a hook credential FIFO without blocking', () => {
const dir = mkdtempSync(join(tmpdir(), 'adapter-hook-credential-fifo-'))
tmpDirs.push(dir)
const dataDir = join(dir, 'data')
mkdirSync(dataDir, { mode: 0o700 })
const credential = join(dataDir, 'hook-credential')
execFileSync('mkfifo', [credential])
const result = spawnSync(process.execPath, [HOOK, '--port', '9', '--data-dir', dataDir], {
encoding: 'utf8',
env: { ...process.env, TMUX_PANE: '%42' },
input: JSON.stringify({ hook_event_name: 'SessionEnd', session_id: 'fifo', reason: 'logout' }),
timeout: 1_500,
})
expect(result.error).toBeUndefined()
expect(result.status).toBe(0)
expect(statSync(credential).isFIFO()).toBe(true)
})
it.each(['applied', 'pending', 'duplicate'])('forwards Cursor Task/stop hooks and retains tasks unless completion was applied: %s', async acknowledgement => {
const dir = mkdtempSync(join(tmpdir(), 'adapter-hook-cursor-'))
tmpDirs.push(dir)
const dataDir = join(dir, 'data')
const cursorHome = join(dir, 'cursor')
const requests: Array<{ url: string; body: Record<string, unknown> }> = []
const deliveries: unknown[] = []
const server = createServer((req, res) => {
if (req.method !== 'POST') { res.writeHead(405).end(); return }
let raw = ''
req.on('data', (chunk) => { raw += chunk.toString() })
req.on('end', () => {
requests.push({ url: req.url ?? '', body: JSON.parse(raw) as Record<string, unknown> })
deliveries.push([req.headers['x-harness-hook-delivery-id'], req.headers['x-harness-hook-fired-at']])
res.end(req.url === '/api/hook/turn-stop' && acknowledgement !== 'applied'
? JSON.stringify({ [acknowledgement]: true }) : '{}')
})
})
servers.push(server)
await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', () => resolve()))
const address = server.address()
if (!address || typeof address === 'string') throw new Error('test server did not bind a TCP port')
const stdout = await runHook({
port: address.port,
tmuxPane: '%21',
engine: 'cursor',
dataDir,
cursorHome,
input: {
hook_event_name: 'preToolUse',
session_id: 'cursor-session',
tool_name: 'Task',
tool_use_id: 'call-1',
tool_input: { description: 'Inspect', prompt: 'Read code', model: 'inherit' },
user_email: '[email protected]',
},
})
expect(stdout).toBe('{}\n')
expect(requests).toEqual([{
url: '/api/hook/tool-start',
body: {
sessionId: 'cursor-session',
toolUseId: 'call-1',
toolName: 'Task',
input: { description: 'Inspect', prompt: 'Read code', model: 'inherit' },
engine: 'cursor',
tmuxPane: '%21',
runtimeHints: [{ backend: 'tmux', paneId: '%21' }],
callerPid: expect.any(Number),
},
}])
expect(JSON.parse(readFileSync(join(dataDir, 'cursor-pending-tasks.json'), 'utf8'))).toMatchObject([{
sessionId: 'cursor-session',
toolUseId: 'call-1',
}])
requests.splice(0)
deliveries.splice(0)
await runHook({
port: address.port,
tmuxPane: '%21',
engine: 'cursor',
dataDir,
cursorHome,
input: {
hook_event_name: 'stop',
status: 'error',
session_id: 'cursor-session',
workspace_roots: ['/tmp/cursor-workspace'],
cursor_version: '2026.07.20-8cc9c0b',
},
})
expect(requests.map((request) => request.url)).toEqual([
'/api/hook/session-start',
'/api/hook/turn-stop',
])
expect(requests.map(request => request.body.status)).toEqual(['error', 'error'])
expect(deliveries[0]).toEqual(deliveries[1])
if (acknowledgement !== 'applied') {
expect(() => readFileSync(join(dataDir, 'cursor-pending-tasks.json'), 'utf8')).not.toThrow()
expect(JSON.parse(readFileSync(join(dataDir, 'cursor-pending-tasks.json'), 'utf8'))).toHaveLength(1)
}
else expect(() => readFileSync(join(dataDir, 'cursor-pending-tasks.json'), 'utf8')).toThrow()
})
it('keeps a Cursor session\'s tasks when its end was not answered in time', async () => {
const dir = mkdtempSync(join(tmpdir(), 'adapter-hook-cursor-late-'))
tmpDirs.push(dir)
const dataDir = join(dir, 'data')
const cursorHome = join(dir, 'cursor')
let slow = false
const server = createServer((req, res) => {
if (slow) { setTimeout(() => { try { res.end('{}') } catch { /* the hook has gone */ } }, 2_000).unref(); return }
req.resume()
req.on('end', () => res.end('{}'))
})
servers.push(server)
await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', () => resolve()))
const address = server.address()
if (!address || typeof address === 'string') throw new Error('test server did not bind a TCP port')
const hook = (input: Record<string, unknown>) => runHook({ port: address.port, tmuxPane: '%21', engine: 'cursor', dataDir, cursorHome, input })
await hook({ hook_event_name: 'preToolUse', session_id: 'cursor-session', tool_name: 'Task', tool_use_id: 'call-1', tool_input: { description: 'Inspect', prompt: 'Read code' } })
const tasks = () => JSON.parse(readFileSync(join(dataDir, 'cursor-pending-tasks.json'), 'utf8')) as unknown[]
expect(tasks()).toHaveLength(1)
slow = true
await hook({ hook_event_name: 'sessionEnd', session_id: 'cursor-session', reason: 'logout' })
expect(tasks()).toHaveLength(1)
})
it('ignores Cursor background agents without leaking them into the registry', async () => {
const dir = mkdtempSync(join(tmpdir(), 'adapter-hook-cursor-background-'))
tmpDirs.push(dir)
const dataDir = join(dir, 'data')
const output = await runHook({
port: 9,
tmuxPane: '%22',
engine: 'cursor',
dataDir,
cursorHome: join(dir, 'cursor'),
input: {
hook_event_name: 'sessionStart',
session_id: 'background',
is_background_agent: true,
},
})
expect(output).toBe('{}\n')
expect(() => readFileSync(join(dataDir, 'registry.json'), 'utf8')).toThrow()
})
it('ignores Codex subagent rollouts instead of replacing the parent transcript', async () => {
const dir = mkdtempSync(join(tmpdir(), 'adapter-hook-codex-subagent-'))
tmpDirs.push(dir)
const dataDir = join(dir, 'data')
const codexHome = join(dir, 'codex')
const childId = '019f8dae-e5f4-7c11-90d1-600854063b2c'
const parentId = '019f7f1b-195d-70f2-861b-de5d54a3e141'
const transcriptPath = join(codexHome, 'sessions', '2026', '07', `rollout-${childId}.jsonl`)
mkdirSync(join(transcriptPath, '..'), { recursive: true })
writeFileSync(transcriptPath, JSON.stringify({
type: 'session_meta',
payload: {
id: childId,
source: { subagent: { thread_spawn: { parent_thread_id: parentId, depth: 1 } } },
},
}) + '\n')
const requests: string[] = []
const server = createServer((req, res) => {
requests.push(req.url ?? '')
req.resume()
res.end('{}')
})
servers.push(server)
await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', () => resolve()))
const address = server.address()
if (!address || typeof address === 'string') throw new Error('test server did not bind a TCP port')
await runHook({
port: address.port,
tmuxPane: '%8',
engine: 'codex',
dataDir,
codexHome,
input: {
hook_event_name: 'SessionStart',
session_id: parentId,
transcript_path: transcriptPath,
cwd: '/tmp/codex',
},
})
expect(requests).toEqual([])
expect(() => readFileSync(join(dataDir, 'registry.json'), 'utf8')).toThrow()
})
it('forwards tmux events regardless of legacy MACHINE_ID', async () => {
const requests: Array<{ url: string; body: Record<string, unknown> }> = []
const server = createServer((req, res) => {
if (req.method !== 'POST') { res.writeHead(405).end(); return }
let raw = ''
req.on('data', (chunk) => { raw += chunk.toString() })
req.on('end', () => {
requests.push({ url: req.url ?? '', body: JSON.parse(raw) as Record<string, unknown> })
res.end('{}')
})
})
servers.push(server)
await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', () => resolve()))
const address = server.address()
if (!address || typeof address === 'string') throw new Error('test server did not bind a TCP port')
await runHook({ port: address.port, tmuxPane: '%42', launcherId: null })
expect(requests).toHaveLength(1)
await runHook({ port: address.port, tmuxPane: '%42' })
expect(requests).toHaveLength(2)
expect(requests.map((request) => request.url)).toEqual(['/api/hook/session-end', '/api/hook/session-end'])
})
// An agent's temporary folder on a Mac (~/.harness/cli/data/agent-tmp/…) leaves no room for a socket beside a test's
// data folder. The hook then looks where the daemon would have put it (#4381): in a short folder under home, or, with
// home too long as well, nowhere, and it posts to the port with the hook-only token.
it.each([['a short folder under home', 'short'], ['the port with the hook token', 'tcp']] as const)(
'reaches the daemon through %s when its data folder is too long for a socket', async (_route, route) => {
const { port, requests } = await collect()
const dir = mkdtempSync(join(tmpdir(), 'hl-'))
tmpDirs.push(dir)
const dataDir = join(dir, 'd'.repeat(100))
const home = route === 'short' ? shortHome() : join(dir, 'h'.repeat(100))
mkdirSync(home, { recursive: true })
await runHook({ port, tmuxPane: '%42', dataDir, env: { HOME: home } })
expect(requests.map((request) => request.url)).toEqual(['/api/hook/session-end'])
})
it('drops standalone SessionEnd but forwards tmux SessionEnd', async () => {
const requests: Array<{ url: string; body: Record<string, unknown> }> = []
const server = createServer((req, res) => {
if (req.method !== 'POST') { res.writeHead(405).end(); return }
let raw = ''
req.on('data', (chunk) => { raw += chunk.toString() })
req.on('end', () => {
requests.push({ url: req.url ?? '', body: JSON.parse(raw) as Record<string, unknown> })
res.end('{}')
})
})
servers.push(server)
await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', () => resolve()))
const address = server.address()
if (!address || typeof address === 'string') throw new Error('test server did not bind a TCP port')
await runHook({ port: address.port })
expect(requests).toEqual([])
await runHook({ port: address.port, tmuxPane: '%42' })
expect(requests).toEqual([{
url: '/api/hook/session-end',
body: {
sessionId: 'session-test',
reason: 'logout',
engine: 'claude',
tmuxPane: '%42',
runtimeHints: [{ backend: 'tmux', paneId: '%42' }],
callerPid: expect.any(Number),
},
}])
})
it.each(['linux', 'missing', 'changed', 'lock-replaced', 'boot-replaced', 'registry-replaced',
'zombie', 'registry-zombie', 'registry-command', 'registry-reparented', 'short', 'wrong-pid'] as const)('retains exact offline process birth evidence: %s', async nativeProcess => {
const dir = mkdtempSync(join(tmpdir(), 'adapter-hook-native-birth-')); tmpDirs.push(dir)
const claudeProjectsDir = join(dir, 'claude-projects'), dataDir = join(dir, 'data')
const transcriptPath = join(claudeProjectsDir, 'demo', 'session-birth.jsonl')
mkdirSync(dirname(transcriptPath), { recursive: true }); mkdirSync(dataDir)
writeLegacyStateFile(join(dataDir, 'registry.json'), '[]'); writeFileSync(transcriptPath, '{}\n')
await runHook({ port: 9, tmuxPane: '%7', processEngine: 'claude', nativeProcess, dataDir, claudeProjectsDir,
input: { hook_event_name: 'SessionStart', session_id: 'session-birth', transcript_path: transcriptPath, cwd: '/tmp/demo' } })
const rows = JSON.parse(readFileSync(join(dataDir, 'registry.json'), 'utf8'))
// Boot confirmation follows the registry's durable commit; a later native change cannot
// retroactively invalidate the already-published snapshot of that process.
if (nativeProcess === 'linux' || nativeProcess === 'boot-replaced') expect(rows).toMatchObject([{ sessionId: 'session-birth', processIdentity: { pid: 7001, startTicks: 12345 } }])
else expect(readFileSync(join(dataDir, 'registry.json'), 'utf8')).toBe('[]')
})
it('keeps old boot authority unchanged when native ownership expires during registry staging', async () => {
const dir = mkdtempSync(join(tmpdir(), 'adapter-hook-native-boot-')); tmpDirs.push(dir)
const claudeProjectsDir = join(dir, 'claude-projects'), dataDir = join(dir, 'data')
const transcriptPath = join(claudeProjectsDir, 'demo', 'session-current.jsonl')
mkdirSync(dirname(transcriptPath), { recursive: true }); mkdirSync(dataDir)
const registryFile = join(dataDir, 'registry.json'), bootFile = join(dataDir, 'registry-boot')
const oldBoot = 'linux:00000000-0000-0000-0000-000000000000'
const oldRows = JSON.stringify([{ agentId: 'old-boot-agent', sessionId: 'old-boot-session', engine: 'claude', tmuxPane: '%7',
processIdentity: { pid: 7001, executable: 'claude', startMarker: 'Mon Aug 10 10:00:01 2026', startTicks: 12345 } }])
writeLegacyStateFile(registryFile, oldRows); writeLegacyStateFile(bootFile, oldBoot); writeFileSync(transcriptPath, '{}\n')
const input = { hook_event_name: 'SessionStart', session_id: 'session-current', transcript_path: transcriptPath, cwd: '/tmp/demo' }
await runHook({ port: 9, tmuxPane: '%7', processEngine: 'claude', nativeProcess: 'registry-replaced', dataDir, claudeProjectsDir, input })
expect(readFileSync(registryFile, 'utf8')).toBe(oldRows)
expect(readFileSync(bootFile, 'utf8')).toBe(oldBoot)
await runHook({ port: 9, tmuxPane: '%7', processEngine: 'claude', nativeProcess: 'linux', dataDir, claudeProjectsDir, input })
const rows = JSON.parse(readFileSync(registryFile, 'utf8'))
expect(rows).toHaveLength(1)
expect(rows[0]).toMatchObject({ sessionId: 'session-current', processIdentity: { startTicks: 12345 } })
expect(rows[0].agentId).not.toBe('old-boot-agent')
expect(readFileSync(bootFile, 'utf8')).not.toBe(oldBoot)
})
it('retains the offline agent and launch choices when precise birth ticks survive a clock adjustment', async () => {
const dir = mkdtempSync(join(tmpdir(), 'adapter-hook-native-clock-')); tmpDirs.push(dir)
const claudeProjectsDir = join(dir, 'claude-projects'), dataDir = join(dir, 'data')
const transcriptPath = join(claudeProjectsDir, 'demo', 'session-clock.jsonl')
mkdirSync(dirname(transcriptPath), { recursive: true }); mkdirSync(dataDir)
writeLegacyStateFile(join(dataDir, 'registry.json'), JSON.stringify([{
agentId: 'kept-agent', engine: 'claude', sessionId: 'session-before', tmuxPane: '%7',
processIdentity: { pid: 7001, executable: 'claude', startMarker: 'Mon Aug 10 09:00:01 2026', startTicks: 12345 },
dsh: 'fixture-harness', defaultName: 'Kept name', permissionMode: 'plan',
}]))
writeFileSync(transcriptPath, '{}\n')
await runHook({ port: 9, tmuxPane: '%7', processEngine: 'claude', nativeProcess: 'linux', dataDir, claudeProjectsDir,
input: { hook_event_name: 'SessionStart', session_id: 'session-clock', transcript_path: transcriptPath, cwd: '/tmp/demo' } })
expect(JSON.parse(readFileSync(join(dataDir, 'registry.json'), 'utf8'))).toMatchObject([{
agentId: 'kept-agent', sessionId: 'session-clock', dsh: 'fixture-harness', defaultName: 'Kept name', permissionMode: 'plan',
processIdentity: { pid: 7001, startTicks: 12345, startMarker: 'Mon Aug 10 10:00:01 2026' },
}])
// Invalid saved birth evidence is recovery data, not permission to replace the existing row.
const rows = JSON.parse(readFileSync(join(dataDir, 'registry.json'), 'utf8'))
rows[0].processIdentity.startTicks = 'unreadable'
const invalid = JSON.stringify(rows)
writeFileSync(join(dataDir, 'registry.json'), invalid)
await runHook({ port: 9, tmuxPane: '%7', processEngine: 'claude', nativeProcess: 'linux', dataDir, claudeProjectsDir,
input: { hook_event_name: 'SessionStart', session_id: 'session-clock', transcript_path: transcriptPath, cwd: '/tmp/demo' } })
expect(readFileSync(join(dataDir, 'registry.json'), 'utf8')).toBe(invalid)
})
it('falls back to registry.json when SessionStart cannot reach the adapter', async () => {
const dir = mkdtempSync(join(tmpdir(), 'adapter-hook-offline-'))
tmpDirs.push(dir)
const claudeProjectsDir = join(dir, 'claude-projects')
const dataDir = join(dir, 'data')
const transcriptPath = join(claudeProjectsDir, 'demo', 'session-1.jsonl')
mkdirSync(join(claudeProjectsDir, 'demo'), { recursive: true })
mkdirSync(dataDir, { recursive: true })
chmodSync(dataDir, 0o755)
writeLegacyStateFile(join(dataDir, 'registry.json'), '[]')
writeFileSync(transcriptPath, '{}\n')
await runHook({
port: 9,
tmuxPane: '%7',
processEngine: 'claude',
dataDir,
claudeProjectsDir,
input: {
hook_event_name: 'SessionStart',
session_id: 'session-1',
transcript_path: transcriptPath,
cwd: '/tmp/demo',
session_title: 'Demo',
model: 'sonnet',
cli_version: '1.0.0',
},
})
const registry = JSON.parse(readFileSync(join(dataDir, 'registry.json'), 'utf-8'))
expect(registry).toMatchObject([{
sessionId: 'session-1',
engine: 'claude',
transcriptPath,
projectDir: 'demo',
cwd: '/tmp/demo',
tmuxPane: '%7',
title: 'Demo',
model: 'sonnet',
cliVersion: '1.0.0',
}])
expect(statSync(dataDir).mode & 0o777).toBe(0o700)
expect(statSync(join(dataDir, 'registry.json')).mode & 0o777).toBe(0o600)
expect(statSync(join(dataDir, 'registry-boot')).mode & 0o777).toBe(0o600)
})
it('reads the process table from harness-pty on Windows, and registers offline with its identity', async () => {
const dir = mkdtempSync(join(tmpdir(), 'adapter-hook-offline-windows-'))
tmpDirs.push(dir)
const claudeProjectsDir = join(dir, 'claude-projects')
const dataDir = join(dir, 'data')
const transcriptPath = join(claudeProjectsDir, 'demo', 'session-w.jsonl')
mkdirSync(join(claudeProjectsDir, 'demo'), { recursive: true })
mkdirSync(dataDir, { recursive: true, mode: 0o700 })
writeFileSync(join(dataDir, 'registry.json'), '[]', { mode: 0o600 })
writeFileSync(transcriptPath, '{}\n')
await runHook({
port: 9, tmuxPane: '%7', processEngine: 'claude', windowsProcessTable: true, dataDir, claudeProjectsDir,
input: { hook_event_name: 'SessionStart', session_id: 'session-w', transcript_path: transcriptPath, cwd: '/tmp/demo' },
})
expect(JSON.parse(readFileSync(join(dataDir, 'registry.json'), 'utf-8'))).toMatchObject([{
sessionId: 'session-w',
engine: 'claude',
processIdentity: { pid: 7001, executable: 'claude', startMarker: 'w:133000000000000001' },
}])
})
it('knows Claude Code\'s native exe on Windows by its name without the extension', async () => {
const dir = mkdtempSync(join(tmpdir(), 'adapter-hook-offline-windows-exe-'))
tmpDirs.push(dir)
const claudeProjectsDir = join(dir, 'claude-projects')
const dataDir = join(dir, 'data')
const transcriptPath = join(claudeProjectsDir, 'demo', 'session-x.jsonl')
mkdirSync(join(claudeProjectsDir, 'demo'), { recursive: true })
mkdirSync(dataDir, { recursive: true, mode: 0o700 })
writeFileSync(join(dataDir, 'registry.json'), '[]', { mode: 0o600 })
writeFileSync(transcriptPath, '{}\n')
// The row harness-pty lists for Claude Code's native install (Windows 11, 2026-10-15).
await runHook({
port: 9, tmuxPane: '%7', processEngine: 'claude', windowsProcessTable: true, dataDir, claudeProjectsDir,
processExecutable: 'claude.exe', processArgs: 'C:\\Users\\admin\\.local\\bin\\claude.exe',
input: { hook_event_name: 'SessionStart', session_id: 'session-x', transcript_path: transcriptPath, cwd: '/tmp/demo' },
})
expect(JSON.parse(readFileSync(join(dataDir, 'registry.json'), 'utf-8'))).toMatchObject([{
sessionId: 'session-x',
engine: 'claude',
processIdentity: { pid: 7001, executable: 'claude.exe', startMarker: 'w:133000000000000001' },
}])
})
it('leaves a corrupt offline registry byte-identical instead of replacing it', async () => {
const dir = mkdtempSync(join(tmpdir(), 'adapter-hook-offline-corrupt-'))
tmpDirs.push(dir)
const claudeProjectsDir = join(dir, 'claude-projects')
const dataDir = join(dir, 'data')
const transcriptPath = join(claudeProjectsDir, 'demo', 'session-corrupt.jsonl')
const registryFile = join(dataDir, 'registry.json')
const corrupt = '[{"schemaVersion":2'
mkdirSync(join(claudeProjectsDir, 'demo'), { recursive: true })
mkdirSync(dataDir, { recursive: true })
writeFileSync(transcriptPath, '{}\n')
writeFileSync(registryFile, corrupt, { mode: 0o600 })
await runHook({
port: 9,
tmuxPane: '%70',
processEngine: 'claude',
dataDir,
claudeProjectsDir,
input: {
hook_event_name: 'SessionStart',
session_id: 'session-corrupt',
transcript_path: transcriptPath,
cwd: '/tmp/demo',
},
})
expect(readFileSync(registryFile, 'utf8')).toBe(corrupt)
})
it('leaves malformed current, future, and legacy rows byte-identical while offline', async () => {
const dir = mkdtempSync(join(tmpdir(), 'adapter-hook-offline-invalid-v2-'))
tmpDirs.push(dir)
const claudeProjectsDir = join(dir, 'claude-projects')
const dataDir = join(dir, 'data')
const transcriptPath = join(claudeProjectsDir, 'demo', 'session-invalid-v2.jsonl')
const registryFile = join(dataDir, 'registry.json')
mkdirSync(join(claudeProjectsDir, 'demo'), { recursive: true })
mkdirSync(dataDir, { recursive: true })
writeFileSync(transcriptPath, '{}\n')
for (const bytes of [
JSON.stringify([{ schemaVersion: 2, agentId: 'damaged' }]),
JSON.stringify([{ schemaVersion: '3', agentId: 'future' }]),
JSON.stringify([{}]),
JSON.stringify([7]),
JSON.stringify([{ agentId: 'legacy-agent' }]),
]) {
writeFileSync(registryFile, bytes, { mode: 0o600 })
await runHook({
port: 9,
tmuxPane: '%71',
processEngine: 'claude',
dataDir,
claudeProjectsDir,
input: {
hook_event_name: 'SessionStart',
session_id: 'session-invalid-v2',
transcript_path: transcriptPath,
cwd: '/tmp/demo',
},
})
expect(readFileSync(registryFile, 'utf8')).toBe(bytes)
}
})
// A step's limit is cut to what is left of the hook's budget, and what is left is a fraction of a
// millisecond off the whole: `execFile` refuses a fractional timeout (ERR_OUT_OF_RANGE), so once the
// budget left was under a step's own limit, that step threw, and the offline registration with it.
// On the shipped 4.5 s budget that is any hook whose earlier steps took a second, as a loaded machine's
// do. Here tmux answers each of its two calls in 1.5 s of a 9 s budget, which leaves the process scan
// under its 6 s limit.
it('still registers offline when its earlier steps took a third of its budget', async () => {
const dir = mkdtempSync(join(tmpdir(), 'adapter-hook-late-'))
tmpDirs.push(dir)
const claudeProjectsDir = join(dir, 'claude-projects')
const dataDir = join(dir, 'data')
const transcriptPath = join(claudeProjectsDir, 'demo', 'session-late.jsonl')
mkdirSync(join(claudeProjectsDir, 'demo'), { recursive: true })
writeFileSync(transcriptPath, '{}\n')
await runHook({
port: 9,
tmuxPane: '%7',
processEngine: 'claude',
tmuxDelaySeconds: 1.5,
env: { HARNESS_HOOK_DEADLINE_MS: '9000' },
dataDir,
claudeProjectsDir,
input: { hook_event_name: 'SessionStart', session_id: 'session-late', transcript_path: transcriptPath, cwd: '/tmp/demo' },
})
expect(JSON.parse(readFileSync(join(dataDir, 'registry.json'), 'utf-8'))).toMatchObject([{ sessionId: 'session-late', tmuxPane: '%7' }])
})
it('falls back with Codex engine under CODEX_HOME/sessions', async () => {
const dir = mkdtempSync(join(tmpdir(), 'adapter-hook-codex-'))
tmpDirs.push(dir)
const codexHome = join(dir, 'codex')
const dataDir = join(dir, 'data')
const transcriptPath = join(codexHome, 'sessions', '2026', 'rollout.jsonl')
mkdirSync(join(codexHome, 'sessions', '2026'), { recursive: true })
writeFileSync(transcriptPath, '{}\n')
await runHook({
port: 9,
tmuxPane: '%8',
engine: 'codex',
processEngine: 'codex',
processExecutable: 'node',
processArgs: 'node /nix/store/codex-cli/lib/node_modules/@openai/codex/bin/codex.js',
dataDir,
codexHome,
input: {
hook_event_name: 'SessionStart',
session_id: 'codex-session',
transcript_path: transcriptPath,
cwd: '/tmp/codex',
},
})
const registry = JSON.parse(readFileSync(join(dataDir, 'registry.json'), 'utf-8'))
expect(registry).toMatchObject([{ sessionId: 'codex-session', engine: 'codex', tmuxPane: '%8' }])
})
it('does not treat engine names in unrelated process arguments as an offline agent', async () => {
const dir = mkdtempSync(join(tmpdir(), 'adapter-hook-process-false-positive-'))
tmpDirs.push(dir)
const claudeProjectsDir = join(dir, 'claude-projects')
const dataDir = join(dir, 'data')
const transcriptPath = join(claudeProjectsDir, 'demo', 'session-false.jsonl')
mkdirSync(join(transcriptPath, '..'), { recursive: true })
writeFileSync(transcriptPath, '{}\n')
await runHook({
port: 9,
tmuxPane: '%81',
processEngine: 'claude',
processExecutable: 'python3',
processArgs: 'python3 /work/runner.py compare claude codex agent hermes',
dataDir,
claudeProjectsDir,
input: {
hook_event_name: 'SessionStart',
session_id: 'session-false',
transcript_path: transcriptPath,
},
})
expect(() => readFileSync(join(dataDir, 'registry.json'), 'utf8')).toThrow()
})
it.each(['cli', 'tui'] as const)('offline Hermes fallback binds source=%s and rejects delegation children or unknown rows', async (interactiveSource) => {
const dir = mkdtempSync(join(tmpdir(), 'adapter-hook-hermes-source-'))
tmpDirs.push(dir)
const hermesHome = join(dir, 'hermes')
const cliData = join(dir, 'cli-data')
const common = {
port: 9,
tmuxPane: '%82',
engine: 'hermes' as const,
processEngine: 'hermes' as const,
processExecutable: 'python3',
processArgs: 'python3 /opt/venvs/hermes/lib/python3.12/site-packages/hermes-agent/hermes',
hermesHome,
}
await runHook({
...common,
dataDir: cliData,
hermesSource: interactiveSource,
input: { hook_event_name: 'on_session_start', session_id: '20260810_120000_a1b2c3' },
})
expect(JSON.parse(readFileSync(join(cliData, 'registry.json'), 'utf8'))).toMatchObject([{
sessionId: '20260810_120000_a1b2c3', engine: 'hermes', tmuxPane: '%82',
}])
for (const [name, source] of [['child', 'subagent'], ['unknown', null]] as const) {
const dataDir = join(dir, `${name}-data`)
await runHook({
...common,
dataDir,
hermesSource: source,
input: { hook_event_name: 'on_session_start', session_id: `20260810_12000${name === 'child' ? '1' : '2'}_a1b2c3` },
})
expect(() => readFileSync(join(dataDir, 'registry.json'), 'utf8')).toThrow()
}
})
it.each(['recovers', 'full', 'resolving', 'disconnects'] as const)('Hermes live admission %s retries within a bound and never writes an offline registry', async outcome => {
const dir = mkdtempSync(join(tmpdir(), 'adapter-hook-hermes-held-'))
tmpDirs.push(dir)
const dataDir = join(dir, 'data')
mkdirSync(dataDir)
writeLegacyStateFile(join(dataDir, 'registry.json'), '[]')
let attempts = 0
const firedAt: unknown[] = []
const deliveryIds: unknown[] = []
const server = createServer((req, res) => {
if (req.method !== 'POST') { req.resume(); res.writeHead(405).end(); return }
req.resume()
req.on('end', () => {
attempts++
firedAt.push(req.headers['x-harness-hook-fired-at'])
deliveryIds.push(req.headers['x-harness-hook-delivery-id'])
if (outcome === 'disconnects' && attempts > 1) { res.destroy(); return }
if (outcome === 'recovers' && attempts === 3) { res.end(JSON.stringify({ pending: true })); return }
res.writeHead(outcome === 'resolving' ? 202 : 429)
res.end(JSON.stringify({ pending: false, retry: true, error: 'HOOK_ADMISSION_BUSY' }))
})
})
servers.push(server)
await new Promise<void>(resolve => server.listen(0, '127.0.0.1', resolve))
const address = server.address()
if (!address || typeof address === 'string') throw new Error('private fixture did not bind')
expect(await runHook({ port: address.port, tmuxPane: '%82', engine: 'hermes', processEngine: 'hermes',
processExecutable: 'python3', processArgs: 'python3 /opt/venvs/hermes/lib/python3.12/site-packages/hermes-agent/hermes',
dataDir, hermesHome: join(dir, 'hermes'), hermesSource: 'cli',
input: { hook_event_name: 'on_session_start', session_id: '20260810_120000_a1b2c3' },
})).toBe('{}\n')
expect(attempts).toBe(outcome === 'recovers' ? 3 : outcome === 'disconnects' ? 2 : 4)
expect(new Set(firedAt).size).toBe(1)
expect(new Set(deliveryIds).size).toBe(1)
expect(deliveryIds[0]).toMatch(/^[a-f0-9-]{36}$/)
expect(readFileSync(join(dataDir, 'registry.json'), 'utf8')).toBe('[]')
expect(() => statSync(join(dataDir, 'registry-boot'))).toThrow()
})
it.each([
"import sys, runpy; sys.path.insert(0, '/opt/custom'); runpy.run_module('hermes_cli.main', run_name='__main__')",
"import os, re, sys; sys.path.insert(0, '/opt/custom'); import hermes_bootstrap; from hermes_cli.main import main; sys.exit(main())",
"import os, sys, runpy; os.environ.pop('PYTHONHOME', None); sys.path.insert(0, '/opt/custom'); os.environ['HERMES_HOME'] = os.environ.get('HERMES_HOME') or '/home/demo/.hermes'; import hermes_bootstrap; runpy.run_module('hermes_cli.main', run_name='__main__', alter_sys=True)",
// 0.21.5's multi-line launcher as macOS `ps` prints it: every newline as the four characters `\012`.
["import os, re, sys", "os.environ.pop('PYTHONHOME', None)", "sys.path.insert(0, '/opt/custom')",
'import hermes_bootstrap', 'from hermes_cli.main import main', 'sys.exit(main())'].join('\\012') + '\\012',
])('offline Hermes discovery follows a managed Python bootstrap: %s', async (source) => {
const dir = mkdtempSync(join(tmpdir(), 'adapter-hook-hermes-launcher-'))
tmpDirs.push(dir)
const common = {
port: 9, tmuxPane: '%82', engine: 'hermes' as const, processEngine: 'hermes' as const,
processExecutable: '/home/demo/.her', hermesHome: join(dir, 'hermes'), hermesSource: 'cli' as const,
input: { hook_event_name: 'on_session_start', session_id: '20260810_120000_a1b2c3' },
}
await runHook({ ...common, dataDir: join(dir, 'data'), processArgs: `/opt/python3 -I -I -c ${source}` })
expect(JSON.parse(readFileSync(join(dir, 'data', 'registry.json'), 'utf8'))).toMatchObject([
{ engine: 'hermes', tmuxPane: '%82', processIdentity: { pid: 7001 } },
])
await runHook({ ...common, dataDir: join(dir, 'unrelated'), processArgs: `python3 worker.py -c ${source}` })
expect(() => readFileSync(join(dir, 'unrelated', 'registry.json'), 'utf8')).toThrow()
})
it('still binds a CLI Hermes session when its store is slow to answer, as on a loaded machine', async () => {
const dir = mkdtempSync(join(tmpdir(), 'adapter-hook-hermes-slow-'))
tmpDirs.push(dir)
const dataDir = join(dir, 'data')
await runHook({
port: 9,
tmuxPane: '%83',
engine: 'hermes',
processEngine: 'hermes',
processExecutable: 'python3',
processArgs: 'python3 /opt/venvs/hermes/lib/python3.12/site-packages/hermes-agent/hermes',
hermesHome: join(dir, 'hermes'),
dataDir,
hermesSource: 'cli',
// 1.2 s against the shipped 3 s limit: a store slower than the old 1 s limit still binds. Four times
// the shipped budget stretches all three (4.8 s against 12 s; the old limit would be 4 s, so this
// still tells them apart) and leaves a loaded machine over 7 s for what is not the store: starting
// the hook's fake tmux, ps and sqlite3. At twice the budget (3 s against 6 s, 9 s in all) the earlier
// steps under a full run at load 110 left sqlite3 less than its 3 s, and nothing was registered.
hermesDelaySeconds: 1.2,
env: { HARNESS_HOOK_DEADLINE_MS: '18000' },
input: { hook_event_name: 'on_session_start', session_id: '20260810_120003_a1b2c3' },
})
expect(JSON.parse(readFileSync(join(dataDir, 'registry.json'), 'utf8'))).toMatchObject([{
sessionId: '20260810_120003_a1b2c3', engine: 'hermes', tmuxPane: '%83',
}])
})
it('does not fallback when the adapter accepts the hook event', async () => {
const dir = mkdtempSync(join(tmpdir(), 'adapter-hook-online-'))
tmpDirs.push(dir)
const claudeProjectsDir = join(dir, 'claude-projects')
const dataDir = join(dir, 'data')
const transcriptPath = join(claudeProjectsDir, 'demo', 'session-online.jsonl')
mkdirSync(join(claudeProjectsDir, 'demo'), { recursive: true })
writeFileSync(transcriptPath, '{}\n')
const server = createServer((_req, res) => res.end('{}'))
servers.push(server)
await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', () => resolve()))
const address = server.address()
if (!address || typeof address === 'string') throw new Error('test server did not bind a TCP port')
await runHook({
port: address.port,
tmuxPane: '%9',
dataDir,
claudeProjectsDir,
input: {
hook_event_name: 'SessionStart',
session_id: 'session-online',
transcript_path: transcriptPath,
},
})
expect(() => readFileSync(join(dataDir, 'registry.json'), 'utf-8')).toThrow()
})
it('does not fall back when the daemon took the event but answers late, as a held daemon does', async () => {
// A daemon whose event loop is held, or one slow to answer a session-start: the request is in its
// socket and it handles it once it gets to it. A registry row written behind its back meanwhile was
// merged over the row the daemon kept, without its name, launch or close plan (e2e/stall.e2e.ts).
const dir = mkdtempSync(join(tmpdir(), 'adapter-hook-late-'))
tmpDirs.push(dir)
const claudeProjectsDir = join(dir, 'claude-projects')
const dataDir = join(dir, 'data')
const transcriptPath = join(claudeProjectsDir, 'demo', 'session-late.jsonl')
mkdirSync(join(claudeProjectsDir, 'demo'), { recursive: true })
mkdirSync(dataDir, { recursive: true })
chmodSync(dataDir, 0o755)
writeLegacyStateFile(join(dataDir, 'registry.json'), '[]')
writeFileSync(transcriptPath, '{}\n')
const received: string[] = []
// Takes every request and answers none of them in time.
const server = createServer((req, res) => {
received.push(req.url ?? '')
setTimeout(() => { try { res.end('{}') } catch { /* the hook has gone */ } }, 2_000).unref()
})
servers.push(server)
await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', () => resolve()))
const address = server.address()
if (!address || typeof address === 'string') throw new Error('test server did not bind a TCP port')
await runHook({
port: address.port,
tmuxPane: '%7',
processEngine: 'claude',
dataDir,
claudeProjectsDir,
input: { hook_event_name: 'SessionStart', session_id: 'session-late', transcript_path: transcriptPath, cwd: '/tmp/demo' },
})
expect(received).toContain('/api/hook/session-start')
expect(JSON.parse(readFileSync(join(dataDir, 'registry.json'), 'utf-8'))).toEqual([])
})
it('does not write fallback registry entries outside tmux or outside the transcript root', async () => {
const dir = mkdtempSync(join(tmpdir(), 'adapter-hook-invalid-'))
tmpDirs.push(dir)
const claudeProjectsDir = join(dir, 'claude-projects')
const dataDir = join(dir, 'data')
const outside = join(dir, 'outside.jsonl')
mkdirSync(claudeProjectsDir, { recursive: true })
writeFileSync(outside, '{}\n')
await runHook({
port: 9,
dataDir,
claudeProjectsDir,
input: {
hook_event_name: 'SessionStart',
session_id: 'no-tmux',
transcript_path: outside,
},
})
await runHook({
port: 9,
tmuxPane: '%10',
dataDir,
claudeProjectsDir,
input: {
hook_event_name: 'SessionStart',
session_id: 'outside',
transcript_path: outside,
},
})
expect(() => readFileSync(join(dataDir, 'registry.json'), 'utf-8')).toThrow()
})
it('leaves offline registry ownership unchanged on SessionEnd', async () => {
const dir = mkdtempSync(join(tmpdir(), 'adapter-hook-end-'))
tmpDirs.push(dir)
const dataDir = join(dir, 'data')
mkdirSync(dataDir, { recursive: true })
writeFileSync(join(dataDir, 'registry.json'), JSON.stringify([{ sessionId: 'keep' }, { sessionId: 'ended' }]))
await runHook({
port: 9,
tmuxPane: '%11',
dataDir,
input: { hook_event_name: 'SessionEnd', session_id: 'ended', reason: 'logout' },
})
expect(JSON.parse(readFileSync(join(dataDir, 'registry.json'), 'utf-8'))).toEqual([{ sessionId: 'keep' }, { sessionId: 'ended' }])
await runHook({
port: 9,
tmuxPane: '%11',
dataDir,
input: { hook_event_name: 'SessionEnd', session_id: 'keep', reason: 'clear' },
})
expect(JSON.parse(readFileSync(join(dataDir, 'registry.json'), 'utf-8'))).toEqual([{ sessionId: 'keep' }, { sessionId: 'ended' }])
})
it('keeps fallback registry entries when SessionEnd cannot prove the tmux app exited', async () => {
const dir = mkdtempSync(join(tmpdir(), 'adapter-hook-end-unknown-'))
tmpDirs.push(dir)
const dataDir = join(dir, 'data')
const binDir = join(dir, 'bin')
mkdirSync(dataDir, { recursive: true })
mkdirSync(binDir, { recursive: true })
writeFileSync(join(dataDir, 'registry.json'), JSON.stringify([{ sessionId: 'maybe-alive' }]))
writeFileSync(join(binDir, 'tmux'), '#!/bin/sh\nexit 1\n', { mode: 0o755 })
await runHook({
port: 9,
tmuxPane: '%13',
dataDir,
env: { PATH: `${binDir}:${process.env.PATH ?? ''}` },
input: { hook_event_name: 'SessionEnd', session_id: 'maybe-alive', reason: 'logout' },
})
expect(JSON.parse(readFileSync(join(dataDir, 'registry.json'), 'utf-8'))).toEqual([{ sessionId: 'maybe-alive' }])
})
/** What the daemon chose for an agent and keeps on its row, beyond what the process shows (registry.ts
* `register()` carries every one): a hook while the daemon is down must not be the write that drops it. */
const CHOSEN = {
dsh: 'cad-designer', dshRuntime: '/tmp/dsh/cad-designer/1.2.0', agent: 'reviewer', permissionMode: 'plan',
subscriptionModel: 'opus', defaultName: 'Claude Code 3', gridWebSearch: true,
closePlan: { id: 'plan-1', requestedAt: 1_790_000_000_001, identity: 'claude\u0000agent-created', state: 'waiting' },
}
it('carries what the daemon chose at launch through an offline re-register', async () => {
// A hook arriving while the daemon is down rebuilds the row. The grid launch (key included), the
// Codex profile, the bypass flag and the observed grid are not on the process or in the hook body
// — they must come from the row being replaced, or this becomes the one write that strips them
// and the next restart relaunches the agent on the wrong login.
const dir = mkdtempSync(join(tmpdir(), 'adapter-hook-carry-'))
tmpDirs.push(dir)
const claudeProjectsDir = join(dir, 'claude-projects')
const dataDir = join(dir, 'data')
const transcriptPath = join(claudeProjectsDir, 'demo', 'session-1.jsonl')
mkdirSync(join(claudeProjectsDir, 'demo'), { recursive: true })
mkdirSync(dataDir, { recursive: true })
chmodSync(dataDir, 0o755)
writeFileSync(transcriptPath, '{}\n')
const gridLaunch = { networkId: 'grid-abc', networkName: 'Team grid', baseUrl: 'https://grid.example/grid-abc/relay/v1', apiKey: 'gridkey-abc123' }
writeLegacyStateFile(join(dataDir, 'registry.json'), JSON.stringify([{
schemaVersion: 2,
active: true,
launch: { state: 'starting' },
agentId: 'agent-created',
sessionId: '',
boundAt: null,
engine: 'claude',
gateway: null,
grid: { baseUrl: gridLaunch.baseUrl, model: null },
gridLaunch,
codexHome: null,
bypassPermission: true,
transcriptPath: null,
projectDir: 'demo',
cwd: '/tmp/demo',
runtimes: [{ backend: 'tmux', paneId: '%7' }],
primaryRuntimeKey: 'tmux\u0000%7',
tmuxPane: '%7',
source: null,
title: null,
model: null,
cliVersion: null,
processIdentity: { pid: 7001, executable: 'claude', startMarker: 'Mon Aug 10 10:00:01 2026' },
registeredAt: 1,
updatedAt: 1,
lastHookAt: 1,
lastTranscriptAt: 1,
// When an app last opened it — every app's "last used" order reads this, so a hook that lands
// while the daemon is down must not be the write that forgets it.
lastOpenedAt: 1_790_000_000_000,
...CHOSEN,
}]))
await runHook({
port: 9,
tmuxPane: '%7',
processEngine: 'claude',
dataDir,
claudeProjectsDir,
input: { hook_event_name: 'SessionStart', session_id: 'session-1', transcript_path: transcriptPath, cwd: '/tmp/demo' },
})
const registry = JSON.parse(readFileSync(join(dataDir, 'registry.json'), 'utf-8'))
expect(registry).toHaveLength(1)
expect(registry[0]).toMatchObject({
agentId: 'agent-created',
sessionId: 'session-1',
grid: { baseUrl: gridLaunch.baseUrl, model: null },
gridLaunch,
bypassPermission: true,
lastOpenedAt: 1_790_000_000_000,
...CHOSEN,
})
expect(registry[0]).not.toHaveProperty('launch')
// A row whose launch was a resume only: as the daemon has it, a hook ends that launch.
const rows = JSON.parse(readFileSync(join(dataDir, 'registry.json'), 'utf-8'))
rows[0] = { ...rows[0], resumeOnly: true, launch: { state: 'starting' } }
writeLegacyStateFile(join(dataDir, 'registry.json'), JSON.stringify(rows))
await runHook({
port: 9, tmuxPane: '%7', processEngine: 'claude', dataDir, claudeProjectsDir,
input: { hook_event_name: 'UserPromptSubmit', session_id: 'session-1', transcript_path: transcriptPath, cwd: '/tmp/demo', prompt: 'next' },
})
expect(JSON.parse(readFileSync(join(dataDir, 'registry.json'), 'utf-8'))[0]).toMatchObject({ resumeOnly: true, launch: { state: 'ready' }, ...CHOSEN })
})
it('reads every engine the daemon can write a row for: its list is the daemon\'s', () => {
// The hook cannot import the daemon's list (it runs without the adapter's modules), so it keeps a copy,
// and a copy drifts: `terminal` was missing from it, and one terminal tile made the hook read the whole
// registry as damaged and register nothing while the daemon was down.
const source = readFileSync(HOOK, 'utf8')
const literal = /const REGISTRY_ENGINES = new Set\(\[([^\]]*)\]\)/.exec(source)?.[1]
expect(literal, 'REGISTRY_ENGINES in hook/notify.mjs').toBeDefined()
const listed = [...literal!.matchAll(/'([^']+)'/g)].map((match) => match[1])
expect([...listed].sort()).toEqual([...ENGINES].sort())
expect(new Set(listed).size).toBe(listed.length)
})
it('registers an agent offline beside a terminal tile, and leaves the tile as it was', async () => {
const dir = mkdtempSync(join(tmpdir(), 'adapter-hook-terminal-'))
tmpDirs.push(dir)
const claudeProjectsDir = join(dir, 'claude-projects')
const dataDir = join(dir, 'data')
const transcriptPath = join(claudeProjectsDir, 'demo', 'session-new.jsonl')
mkdirSync(join(claudeProjectsDir, 'demo'), { recursive: true })
mkdirSync(dataDir, { recursive: true })
chmodSync(dataDir, 0o755)
writeFileSync(transcriptPath, '{}\n')
// A terminal tile as the daemon saves one: no conversation and, until a scan sees its shell, no process.
const tile = {
schemaVersion: 2, active: true, defaultName: 'Terminal', agentId: 'agent-terminal', sessionId: '', boundAt: null,
engine: 'terminal', terminalHost: true, gateway: null, grid: null, codexHome: null, transcriptPath: null,
projectDir: 'demo', cwd: '/tmp/demo', runtimes: [{ backend: 'tmux', paneId: '%3' }], primaryRuntimeKey: 'tmux\u0000%3',
tmuxPane: '%3', source: null, title: null, model: null, cliVersion: null, processIdentity: null,
registeredAt: 1, touchedAt: 1, lastHookAt: 0, lastTranscriptAt: 1,
}
writeLegacyStateFile(join(dataDir, 'registry.json'), JSON.stringify([tile]))
await runHook({
port: 9, tmuxPane: '%7', processEngine: 'claude', dataDir, claudeProjectsDir,
input: { hook_event_name: 'SessionStart', session_id: 'session-new', transcript_path: transcriptPath, cwd: '/tmp/demo', source: 'startup' },
})
const rows = JSON.parse(readFileSync(join(dataDir, 'registry.json'), 'utf-8'))
expect(rows).toHaveLength(2)
expect(rows[0]).toEqual(tile)
expect(rows[1]).toMatchObject({ engine: 'claude', sessionId: 'session-new', tmuxPane: '%7', processIdentity: { pid: 7001 } })
})
it('names a daemon\'s panes as the daemon does', () => {
const source = readFileSync(HOOK, 'utf8')
expect(/const HARNESS_OWNER_OPTION = '([^']+)'/.exec(source)?.[1]).toBe(HARNESS_OWNER_OPTION)
expect(/const HARNESS_SESSION_PREFIX = '([^']+)'/.exec(source)?.[1]).toBe(HARNESS_SESSION_PREFIX)
// The tag in a pane's start command, before tmux 3.0, read with the format the daemon reads it with.
const prefix = /const OWNER_COMMAND_PREFIX = '([^']+)'/.exec(source)?.[1]
expect(`${ownerCommand('0123456789abcdef', ['zsh']).slice(0, 2).join(' ')} zsh`.startsWith(`${prefix}0123456789abcdef`)).toBe(true)
const format = `#{?#{m:${prefix}*,#{pane_start_command}},#{=${prefix!.length + 16}:pane_start_command},`
+ `#{?#{m:${HARNESS_SESSION_PREFIX}*,#{session_name}},#{${HARNESS_OWNER_OPTION}},}}`
expect(format).toBe(paneOwnerFormat(false))
// And the hook's own, read out of its source, are the daemon's: the old tmux one with the session check,
// and from 3.0 the pane's own option.
expect(source).toContain('#{?#{m:${HARNESS_SESSION_PREFIX}*,#{session_name}},#{${HARNESS_OWNER_OPTION}},}}')
expect(source).toContain('const PANE_OWNER_FORMAT = `#{${HARNESS_OWNER_OPTION}}`')
expect(paneOwnerFormat(true)).toBe(`#{${HARNESS_OWNER_OPTION}}`)
})
it('registers offline only a pane its daemon takes for an agent: never a session opened by hand or another daemon\'s', async () => {
// With the daemon up, the hook of an engine in such a pane is turned away (discovery reads only the
// daemon's own panes). Offline, the hook wrote a row for it anyway, and the daemon came back with an
// agent it would never have made, offline for good.
const dir = mkdtempSync(join(tmpdir(), 'adapter-hook-owned-'))
tmpDirs.push(dir)
const claudeProjectsDir = join(dir, 'claude-projects')
mkdirSync(join(claudeProjectsDir, 'demo'), { recursive: true })
const register = async (name: string, pane: { paneSession: string; paneOwner?: string }, rows?: unknown[]) => {
const dataDir = join(dir, name)
mkdirSync(dataDir, { recursive: true, mode: 0o700 })
if (rows) writeFileSync(join(dataDir, 'registry.json'), JSON.stringify(rows), { mode: 0o600 })
const transcriptPath = join(claudeProjectsDir, 'demo', `${name}.jsonl`)
writeFileSync(transcriptPath, '{}\n')
await runHook({
port: 9, tmuxPane: '%7', processEngine: 'claude', dataDir, claudeProjectsDir, ...pane,
input: { hook_event_name: 'SessionStart', session_id: name, transcript_path: transcriptPath, cwd: '/tmp/demo', source: 'startup' },
})
try { return (JSON.parse(readFileSync(join(dataDir, 'registry.json'), 'utf8')) as Array<{ sessionId: string }>).map((row) => row.sessionId) } catch { return null }
}
expect(await register('by-hand', { paneSession: 'mine' })).toBeNull()
expect(await register('another-daemon', { paneSession: 'harness-claude-1790000000000', paneOwner: 'abcdef0123456789' })).toBeNull()
// Its own pane, wherever the person moved it, and an untagged one in a session Harness named.
expect(await register('moved', { paneSession: 'mine', paneOwner: harnessPaneOwner(join(dir, 'moved')) })).toEqual(['moved'])
expect(await register('untagged', { paneSession: 'harness-claude-1790000000000' })).toEqual(['untagged'])
// Before tmux 3.0 the tag rides in the pane's start command, cut to its prefix and the tag.
const startCommand = (dataDir: string) => ownerCommand(harnessPaneOwner(dataDir), []).join(' ')
expect(await register('old-tmux', { paneSession: 'mine', paneOwner: startCommand(join(dir, 'old-tmux')) })).toEqual(['old-tmux'])
expect(await register('old-tmux-other', { paneSession: 'harness-claude-1790000000000', paneOwner: startCommand(join(dir, 'elsewhere')) })).toBeNull()
// A session an older build named, only while the registry holds an agent on that pane.
expect(await register('legacy-new', { paneSession: 'claude-1790000000000' })).toBeNull()
const held = {
schemaVersion: 2, active: true, agentId: 'agent-legacy', sessionId: 'before', boundAt: 1, engine: 'claude',
gateway: null, grid: null, codexHome: null, transcriptPath: null, projectDir: 'demo', cwd: '/tmp/demo',
runtimes: [{ backend: 'tmux', paneId: '%7' }], primaryRuntimeKey: 'tmux\u0000%7', tmuxPane: '%7',
source: null, title: null, model: null, cliVersion: null,
processIdentity: { pid: 7001, executable: 'claude', startMarker: 'Mon Aug 10 10:00:01 2026' },
registeredAt: 1, touchedAt: 1, lastHookAt: 1, lastTranscriptAt: 1,
}
expect(await register('legacy-held', { paneSession: 'claude-1790000000000' }, [held])).toEqual(['legacy-held'])
})
it('takes an engine typed into a terminal tile for that tile, as the daemon does', async () => {
// The daemon adopts the tile (registry.adoptEngine): the same agent and name, now the engine's, and a
// terminal again when the engine exits. The hook dropped the tile's row for a new agent instead.
const dir = mkdtempSync(join(tmpdir(), 'adapter-hook-terminal-adopt-'))
tmpDirs.push(dir)
const claudeProjectsDir = join(dir, 'claude-projects')
const dataDir = join(dir, 'data')
const transcriptPath = join(claudeProjectsDir, 'demo', 'session-typed.jsonl')
mkdirSync(join(claudeProjectsDir, 'demo'), { recursive: true })
mkdirSync(dataDir, { recursive: true })
chmodSync(dataDir, 0o755)
writeFileSync(transcriptPath, '{}\n')
writeLegacyStateFile(join(dataDir, 'registry.json'), JSON.stringify([{
schemaVersion: 2, active: true, defaultName: 'Terminal 10-5 9:41', agentId: 'agent-terminal', sessionId: '', boundAt: null,
engine: 'terminal', gateway: null, grid: null, codexHome: null, transcriptPath: null,
projectDir: 'demo', cwd: '/tmp/demo', runtimes: [{ backend: 'tmux', paneId: '%7' }], primaryRuntimeKey: 'tmux\u0000%7',
tmuxPane: '%7', source: null, title: null, model: null, cliVersion: null,
processIdentity: { pid: 7000, executable: 'zsh', startMarker: 'Mon Aug 10 10:00:00 2026' },
registeredAt: 1, touchedAt: 1, lastHookAt: 0, lastTranscriptAt: 1,
}]))
await runHook({
port: 9, tmuxPane: '%7', processEngine: 'claude', dataDir, claudeProjectsDir,
input: { hook_event_name: 'SessionStart', session_id: 'session-typed', transcript_path: transcriptPath, cwd: '/tmp/demo', source: 'startup' },
})
const rows = JSON.parse(readFileSync(join(dataDir, 'registry.json'), 'utf-8'))
expect(rows).toHaveLength(1)
expect(rows[0]).toMatchObject({
agentId: 'agent-terminal', defaultName: 'Terminal 10-5 9:41', engine: 'claude', terminalHost: true,
sessionId: 'session-typed', tmuxPane: '%7', processIdentity: { pid: 7001 },
})
})
it('keeps everything else the daemon kept on the row through an offline re-register, a new conversation included', async () => {
// The hook rebuilt the row from the fields it named, and the daemon, back, loaded that as its own:
// the agent came back under another name and relaunched out of the mode it was made in, its harness,
// named agent and close plan gone (e2e/hookclient.e2e.ts, the daemon down while a conversation began).
const dir = mkdtempSync(join(tmpdir(), 'adapter-hook-kept-'))
tmpDirs.push(dir)
const claudeProjectsDir = join(dir, 'claude-projects')
const dataDir = join(dir, 'data')
mkdirSync(join(claudeProjectsDir, 'demo'), { recursive: true })
mkdirSync(dataDir, { recursive: true })
chmodSync(dataDir, 0o755)
const transcript = (sessionId: string) => {
const path = join(claudeProjectsDir, 'demo', `${sessionId}.jsonl`)
writeFileSync(path, '{}\n')
return path
}
const kept = {
defaultName: 'release notes',
permissionMode: 'plan',
dsh: 'acme/reviewer',
dshRuntime: 'harness-runtime-1',
agent: 'reviewer',
terminalHost: true,
resumeOnly: true,
subscriptionModel: 'claude-opus-5-5',
gridWebSearch: 'on',
closePlan: { id: 'close-1', requestedAt: 1_790_000_000_000, identity: 'session-1', state: 'waiting' },
forkedFrom: { agentId: 'agent-source', name: 'source', sessionId: 'session-0' },
}
writeLegacyStateFile(join(dataDir, 'registry.json'), JSON.stringify([{
schemaVersion: 2, active: true, launch: { state: 'starting' }, agentId: 'agent-kept', sessionId: 'session-1', boundAt: 1,
engine: 'claude', gateway: null, grid: null, codexHome: null, transcriptPath: transcript('session-1'), projectDir: 'demo',
cwd: '/tmp/demo', runtimes: [{ backend: 'tmux', paneId: '%7' }], primaryRuntimeKey: 'tmux\u0000%7', tmuxPane: '%7',
source: null, title: null, model: null, cliVersion: null,
processIdentity: { pid: 7001, executable: 'claude', startMarker: 'Mon Aug 10 10:00:01 2026' },
registeredAt: 1, touchedAt: 1, lastHookAt: 1, lastTranscriptAt: 1,
...kept,
}]))
for (const [event, sessionId, source] of [['UserPromptSubmit', 'session-1', undefined], ['SessionStart', 'session-2', 'clear']] as const) {
await runHook({
port: 9, tmuxPane: '%7', processEngine: 'claude', dataDir, claudeProjectsDir,
input: { hook_event_name: event, session_id: sessionId, transcript_path: transcript(sessionId), cwd: '/tmp/demo', ...(source ? { source } : {}) },
})
const rows = JSON.parse(readFileSync(join(dataDir, 'registry.json'), 'utf-8'))
expect(rows).toHaveLength(1)
expect(rows[0]).toMatchObject({ agentId: 'agent-kept', sessionId, ...kept })
// A hook means the engine is up, whatever the launch was: over, as `register()` has it, which on a
// row that may only be resumed reads `ready`.
expect(rows[0].launch).toEqual({ state: 'ready' })
expect(rows[0].touchedAt).toBeGreaterThan(1)
}
})
it('an offline re-register of the session a row already holds keeps the row\'s folder', async () => {
// Claude's UserPromptSubmit carries the tracked shell directory — wherever the agent last
// `cd`'d — and a daemon-down rebuild must not move the row there any more than the daemon does.
const dir = mkdtempSync(join(tmpdir(), 'adapter-hook-cwd-'))
tmpDirs.push(dir)
const claudeProjectsDir = join(dir, 'claude-projects')
const dataDir = join(dir, 'data')
const transcriptPath = join(claudeProjectsDir, 'demo', 'session-1.jsonl')
mkdirSync(join(claudeProjectsDir, 'demo'), { recursive: true })
mkdirSync(dataDir, { recursive: true })
chmodSync(dataDir, 0o755)
writeFileSync(transcriptPath, '{}\n')
const row = {
schemaVersion: 2, active: true, agentId: 'agent-bound', sessionId: 'session-1', boundAt: 1, engine: 'claude',
gateway: null, grid: null, codexHome: null, transcriptPath, projectDir: 'demo', cwd: '/tmp/demo',
runtimes: [{ backend: 'tmux', paneId: '%7' }], primaryRuntimeKey: 'tmux\u0000%7', tmuxPane: '%7',
source: null, title: null, model: null, cliVersion: null,
processIdentity: { pid: 7001, executable: 'claude', startMarker: 'Mon Aug 10 10:00:01 2026' },
registeredAt: 1, updatedAt: 1, lastHookAt: 1, lastTranscriptAt: 1,
}
writeLegacyStateFile(join(dataDir, 'registry.json'), JSON.stringify([row]))
await runHook({
port: 9, tmuxPane: '%7', processEngine: 'claude', dataDir, claudeProjectsDir,
input: { hook_event_name: 'UserPromptSubmit', session_id: 'session-1', transcript_path: transcriptPath, cwd: '/tmp/demo/cli' },
})
expect(JSON.parse(readFileSync(join(dataDir, 'registry.json'), 'utf-8'))[0]).toMatchObject({ agentId: 'agent-bound', sessionId: 'session-1', cwd: '/tmp/demo' })
// A rotation is a new session and takes the folder it reports.
const rotated = join(claudeProjectsDir, 'demo', 'session-2.jsonl')
writeFileSync(rotated, '{}\n')
await runHook({
port: 9, tmuxPane: '%7', processEngine: 'claude', dataDir, claudeProjectsDir,
input: { hook_event_name: 'SessionStart', session_id: 'session-2', transcript_path: rotated, cwd: '/tmp/demo/cli' },
})
expect(JSON.parse(readFileSync(join(dataDir, 'registry.json'), 'utf-8'))[0]).toMatchObject({ agentId: 'agent-bound', sessionId: 'session-2', cwd: '/tmp/demo/cli' })
})
it('drops stale registry entries when boot marker predates this boot', async () => {
const dir = mkdtempSync(join(tmpdir(), 'adapter-hook-reboot-'))
tmpDirs.push(dir)
const claudeProjectsDir = join(dir, 'claude-projects')
const dataDir = join(dir, 'data')
const transcriptPath = join(claudeProjectsDir, 'demo', 'fresh.jsonl')
mkdirSync(join(claudeProjectsDir, 'demo'), { recursive: true })
mkdirSync(dataDir, { recursive: true })
chmodSync(dataDir, 0o755)
writeFileSync(transcriptPath, '{}\n')
writeLegacyStateFile(join(dataDir, 'registry-boot'), '1')
writeLegacyStateFile(join(dataDir, 'registry.json'), JSON.stringify([{ sessionId: 'stale', tmuxPane: '%1' }]))
await runHook({
port: 9,
tmuxPane: '%12',
processEngine: 'claude',
dataDir,
claudeProjectsDir,
input: {
hook_event_name: 'SessionStart',
session_id: 'fresh',
transcript_path: transcriptPath,
},
})
expect(JSON.parse(readFileSync(join(dataDir, 'registry.json'), 'utf-8'))).toMatchObject([
{ sessionId: 'fresh', tmuxPane: '%12' },
])
})
it('does not take a step of the wall clock for a reboot, and keeps every other agent', async () => {
// A boot named by the moment it began moved with the clock, and a hook that fell back to the
// registry hours after a laptop slept, or after an NTP step, took it for a reboot and wrote a
// registry of its one agent (round 29).
const dir = mkdtempSync(join(tmpdir(), 'adapter-hook-clock-'))
tmpDirs.push(dir)
const claudeProjectsDir = join(dir, 'claude-projects')
const dataDir = join(dir, 'data')
mkdirSync(join(claudeProjectsDir, 'demo'), { recursive: true })
mkdirSync(dataDir, { recursive: true })
chmodSync(dataDir, 0o755)
const otherTranscript = join(claudeProjectsDir, 'demo', 'other.jsonl')
writeFileSync(otherTranscript, '{}\n')
writeLegacyStateFile(join(dataDir, 'registry.json'), JSON.stringify([{
schemaVersion: 2, active: true, agentId: 'agent-other', sessionId: 'other', boundAt: 1, engine: 'claude',
gateway: null, grid: null, codexHome: null, transcriptPath: otherTranscript, projectDir: 'demo', cwd: '/tmp/demo',
runtimes: [{ backend: 'tmux', paneId: '%1' }], primaryRuntimeKey: 'tmux\u0000%1', tmuxPane: '%1',
source: null, title: null, model: null, cliVersion: null,
processIdentity: { pid: 5001, executable: 'claude', startMarker: 'Mon Aug 10 09:00:00 2026' },
registeredAt: 1, updatedAt: 1, lastHookAt: 1, lastTranscriptAt: 1,
}]))
const register = (sessionId: string, env?: Record<string, string>) => {
const transcriptPath = join(claudeProjectsDir, 'demo', `${sessionId}.jsonl`)
writeFileSync(transcriptPath, '{}\n')
return runHook({
port: 9, tmuxPane: '%12', processEngine: 'claude', dataDir, claudeProjectsDir, env,
input: { hook_event_name: 'SessionStart', session_id: sessionId, transcript_path: transcriptPath },
})
}
// This boot's mark is written by the first offline write; then the clock moves three hours on, in
// the hook as in the engine that runs it.
await register('before')
expect(statSync(join(dataDir, 'registry-boot')).isFile()).toBe(true)
const shift = join(dir, 'shift')
writeFileSync(shift, String(3 * 3_600_000))
await register('after', { NODE_OPTIONS: `--import ${CLOCK_SHIFT}`, E2E_CLOCK_SHIFT_FILE: shift })
const rows = JSON.parse(readFileSync(join(dataDir, 'registry.json'), 'utf-8')) as Array<{ sessionId: string }>
expect(rows.map((row) => row.sessionId).sort()).toEqual(['after', 'other'])
})
})
describe('hook notify Grok lifecycle', () => {
it('resolves updates.jsonl, registers lifecycle events, and uses only StopFailure as a close fallback', async () => {
const dir = mkdtempSync(join(tmpdir(), 'adapter-hook-grok-'))
tmpDirs.push(dir)
const grokHome = join(dir, 'grok')
const cwd = '/tmp/grok workspace'
const sessionId = '8184b11d-175e-46cb-9cee-cf41cafe70d2'
const transcript = join(grokHome, 'sessions', encodeURIComponent(cwd), sessionId, 'updates.jsonl')
mkdirSync(join(transcript, '..'), { recursive: true })
writeFileSync(transcript, '{}\n')
const { port, requests } = await collect()
await runHook({
port, tmuxPane: '%44', engine: 'grok', grokHome,
input: { hookEventName: 'session_start', sessionId, cwd, model: 'grok-4.5', cliVersion: '1.0.0' },
})
expect(requests).toEqual([{
url: '/api/hook/session-start',
body: expect.objectContaining({
engine: 'grok', hookEvent: 'SessionStart', sessionId, transcriptPath: transcript,
cwd, tmuxPane: '%44', model: 'grok-4.5', cliVersion: '1.0.0',
}),
}])
requests.splice(0)
await runHook({ port, tmuxPane: '%44', engine: 'grok', grokHome, input: { hookEventName: 'stop', sessionId, cwd } })
expect(requests).toEqual([])
await runHook({ port, tmuxPane: '%44', engine: 'grok', grokHome, input: { hookEventName: 'stop_failure', sessionId, cwd } })
expect(requests).toEqual([{
url: '/api/hook/turn-stop',
body: {
sessionId,
transcriptPath: transcript,
status: 'error',
engine: 'grok',
tmuxPane: '%44',
runtimeHints: [{ backend: 'tmux', paneId: '%44' }],
callerPid: expect.any(Number),
},
}])
})
it('writes an offline fallback registry entry under the trusted Grok root', async () => {
const dir = mkdtempSync(join(tmpdir(), 'adapter-hook-grok-offline-'))
tmpDirs.push(dir)
const grokHome = join(dir, 'grok')
const dataDir = join(dir, 'data')
const cwd = '/tmp/grok-offline'
const sessionId = '98ee3dac-175e-46cb-9cee-cf41cafe70d2'
const transcript = join(grokHome, 'sessions', encodeURIComponent(cwd), sessionId, 'updates.jsonl')
mkdirSync(join(transcript, '..'), { recursive: true })
writeFileSync(transcript, '{}\n')
await runHook({
port: 9, tmuxPane: '%45', engine: 'grok', processEngine: 'grok',
processExecutable: 'agent', processArgs: 'agent', grokHome, dataDir,
input: { hookEventName: 'session_start', sessionId, cwd },
})
expect(JSON.parse(readFileSync(join(dataDir, 'registry.json'), 'utf8'))).toMatchObject([{
sessionId, engine: 'grok', transcriptPath: transcript, projectDir: 'grok-offline', cwd, tmuxPane: '%45',
}])
const rejectedDataDir = join(dir, 'cursor-owned-agent-data')
await runHook({
port: 9, tmuxPane: '%46', engine: 'grok', processEngine: 'cursor',
processExecutable: 'agent', processArgs: 'agent', grokHome, dataDir: rejectedDataDir,
input: { hookEventName: 'session_start', sessionId, cwd },
})
expect(() => readFileSync(join(rejectedDataDir, 'registry.json'), 'utf8')).toThrow()
})
})
/**
* Devin's documented user-level hook locations include `~/.claude/settings.json`, so the machine's CLAUDE
* hook can fire inside a Devin session and register it under the wrong engine. The claude arm bails out
* on a payload whose session id is a Devin slug holding a live `session_locks/<id>.lock`.
*/
describe('hook notify Devin/claude disambiguation', () => {
it('ignores a Devin session that fired the claude hook, but still registers a real claude session', async () => {
const dir = mkdtempSync(join(tmpdir(), 'adapter-hook-devin-'))
tmpDirs.push(dir)
const devinHome = join(dir, 'devin')
const projectsDir = join(dir, 'projects')
mkdirSync(join(devinHome, 'session_locks'), { recursive: true })
writeFileSync(join(devinHome, 'session_locks', 'classy-tourmaline.lock'), '21988')
mkdirSync(projectsDir, { recursive: true })
const transcript = join(projectsDir, 'a3f1c2d4-0000-4000-8000-000000000001.jsonl')
writeFileSync(transcript, '')
const { port, requests } = await collect()
// Devin's SessionStart, arriving on the claude-armed hook → dropped.
await runHook({
port,
tmuxPane: '%30',
dataDir: join(dir, 'data'),
claudeProjectsDir: projectsDir,
devinHome,
input: { hook_event_name: 'SessionStart', session_id: 'classy-tourmaline', source: 'startup' },
})
expect(requests).toEqual([])
// A genuine claude session is unaffected.
await runHook({
port,
tmuxPane: '%30',
dataDir: join(dir, 'data'),
claudeProjectsDir: projectsDir,
devinHome,
input: {
hook_event_name: 'SessionStart',
session_id: 'a3f1c2d4-0000-4000-8000-000000000001',
transcript_path: transcript,
cwd: '/tmp/claude-workspace',
source: 'startup',
},
})
expect(requests).toHaveLength(1)
expect(requests[0].url).toBe('/api/hook/session-start')
expect(requests[0].body).toMatchObject({ engine: 'claude', sessionId: 'a3f1c2d4-0000-4000-8000-000000000001' })
})
it('registers a Devin session with no transcript path and the hook process cwd', async () => {
const dir = mkdtempSync(join(tmpdir(), 'adapter-hook-devin2-'))
tmpDirs.push(dir)
const { port, requests } = await collect()
await runHook({
port,
tmuxPane: '%31',
engine: 'devin',
dataDir: join(dir, 'data'),
devinHome: join(dir, 'devin'),
input: { hook_event_name: 'SessionStart', session_id: 'blue-agustinia', source: 'startup' },
})
expect(requests).toHaveLength(1)
expect(requests[0].url).toBe('/api/hook/session-start')
expect(requests[0].body).toMatchObject({
engine: 'devin',
sessionId: 'blue-agustinia',
tmuxPane: '%31',
cwd: process.cwd(),
})
expect(requests[0].body.transcriptPath).toBeUndefined()
})
it('routes a Devin Stop to turn-stop', async () => {
const dir = mkdtempSync(join(tmpdir(), 'adapter-hook-devin3-'))
tmpDirs.push(dir)
const { port, requests } = await collect()
await runHook({
port,
tmuxPane: '%32',
engine: 'devin',
dataDir: join(dir, 'data'),
devinHome: join(dir, 'devin'),
input: { hook_event_name: 'Stop', session_id: 'blue-agustinia', stop_hook_active: false, prompt_id: 'p1' },
})
expect(requests).toHaveLength(1)
expect(requests[0].url).toBe('/api/hook/turn-stop')
expect(requests[0].body).toMatchObject({ sessionId: 'blue-agustinia' })
})
})
describe('hook notify Command Code re-registration', () => {
// Command Code's hook set is PreToolUse/PostToolUse/Stop/SessionStart — Stop doubles as its only catch
// hook, so it must register as well as close the turn. Without that, a session dropped from the registry
// stays invisible on web/device until the user quits and relaunches the CLI.
it('re-registers on Stop, with the transcript path, before closing the turn', async () => {
const dir = mkdtempSync(join(tmpdir(), 'adapter-hook-cc-'))
tmpDirs.push(dir)
const transcript = join(dir, '53955d6d.jsonl')
writeFileSync(transcript, '{}\n')
const { port, requests } = await collect()
await runHook({
port,
tmuxPane: '%3',
engine: 'commandcode',
dataDir: join(dir, 'data'),
input: {
hook_event_name: 'Stop',
session_id: '53955d6d',
transcript_path: transcript,
cwd: '/tmp/demo',
session_title: 'Greeting',
},
})
expect(requests.map((r) => r.url)).toEqual(['/api/hook/session-start', '/api/hook/turn-stop'])
expect(requests[0].body).toMatchObject({
engine: 'commandcode',
hookEvent: 'Stop',
sessionId: '53955d6d',
transcriptPath: transcript,
tmuxPane: '%3',
cwd: '/tmp/demo',
title: 'Greeting',
})
})
it('omits a transcript path that does not exist yet', async () => {
const dir = mkdtempSync(join(tmpdir(), 'adapter-hook-cc2-'))
tmpDirs.push(dir)
const { port, requests } = await collect()
await runHook({
port,
tmuxPane: '%3',
engine: 'commandcode',
dataDir: join(dir, 'data'),
input: { hook_event_name: 'Stop', session_id: '53955d6d', transcript_path: join(dir, 'nope.jsonl') },
})
expect(requests).toHaveLength(2)
expect(requests[0].body.transcriptPath).toBeUndefined()
})
it('leaves the claude Stop path as a turn-stop only', async () => {
const dir = mkdtempSync(join(tmpdir(), 'adapter-hook-cc3-'))
tmpDirs.push(dir)
const transcript = join(dir, 'projects', 'demo', 'abc.jsonl')
mkdirSync(join(dir, 'projects', 'demo'), { recursive: true })
writeFileSync(transcript, '{}\n')
const { port, requests } = await collect()
await runHook({
port,
tmuxPane: '%4',
dataDir: join(dir, 'data'),
claudeProjectsDir: join(dir, 'projects'),
input: { hook_event_name: 'Stop', session_id: 'abc', transcript_path: transcript },
})
expect(requests.map((r) => r.url)).toEqual(['/api/hook/turn-stop'])
})
})
describe('a hook reaches the daemon that made its pane', () => {
// A computer has one Claude Code entry and one Codex entry, and each daemon writes its own --port and
// --data-dir into them as it starts. With a dev daemon beside the release one, the last to start took
// every hook and turned the other's away. Each daemon records where it listens under its pane tag
// (lib/hookRoutes.ts), and the hook follows the pane's tag there (notify.mjs routeToPaneOwner).
function computer() {
const dir = realpathSync(mkdtempSync(join(tmpdir(), 'adapter-hook-routes-')))
tmpDirs.push(dir)
const routes = join(dir, 'hook-routes')
const daemon = (name: string) => {
const dataDir = join(dir, name)
mkdirSync(dataDir, { recursive: true, mode: 0o700 })
const credential = name[0].repeat(43)
writeFileSync(join(dataDir, 'hook-credential'), `${credential}\n`, { mode: 0o600 })
return { dataDir, tag: harnessPaneOwner(dataDir), credential }
}
return { dir, routes, release: daemon('release'), dev: daemon('dev') }
}
const sessionEnd = { hook_event_name: 'SessionEnd', session_id: 'session-routed', reason: 'logout' }
it('follows the pane\'s tag to its daemon, whichever daemon\'s command ran it', async () => {
const { routes, release, dev } = computer()
const atRelease = await collect({}, release.credential)
const atDev = await collect({}, dev.credential)
publishHookRoute(release.dataDir, atRelease.port, routes)
publishHookRoute(dev.dataDir, atDev.port, routes)
await daemonSocketFor(atRelease.port, release.dataDir)
// The dev daemon started last: the command is its own. The pane is the release daemon's.
await runHook({
port: atDev.port, dataDir: dev.dataDir, tmuxPane: '%7', paneOwner: release.tag,
env: { HARNESS_HOOK_ROUTES_DIR: routes }, input: sessionEnd,
})
expect(atRelease.requests.map((r) => r.url)).toEqual(['/api/hook/session-end'])
expect(atDev.requests).toEqual([])
// Its own pane, through its own command, as before.
await runHook({
port: atDev.port, dataDir: dev.dataDir, tmuxPane: '%8', paneOwner: dev.tag,
env: { HARNESS_HOOK_ROUTES_DIR: routes }, input: sessionEnd,
})
expect(atDev.requests.map((r) => r.url)).toEqual(['/api/hook/session-end'])
// Before tmux 3.0 the tag rides in the pane's start command.
await runHook({
port: atDev.port, dataDir: dev.dataDir, tmuxPane: '%9', paneOwner: ownerCommand(release.tag, []).join(' '),
env: { HARNESS_HOOK_ROUTES_DIR: routes }, input: sessionEnd,
})
expect(atRelease.requests).toHaveLength(2)
})
it('the actual hook rejects malformed route records and uses its installed command', async () => {
// These checks used to exercise an unused TypeScript reader, not the hook that consumes the file.
const { routes, release, dev } = computer()
const atRelease = await collect({}, release.credential)
const atDev = await collect({}, dev.credential)
publishHookRoute(release.dataDir, atRelease.port, routes)
const bodies = ['broken', 'null', '{}', JSON.stringify({ dataDir: release.dataDir, port: 0 }),
JSON.stringify({ dataDir: release.dataDir, port: 65_536 }),
JSON.stringify({ dataDir: release.dataDir, port: String(atRelease.port) }),
JSON.stringify({ dataDir: 7, port: atRelease.port }),
JSON.stringify({ dataDir: dev.dataDir, port: atRelease.port })]
for (const body of bodies) {
writeFileSync(hookRouteFile(release.tag, routes), body, { mode: 0o600 })
await runHook({ port: atDev.port, dataDir: dev.dataDir, tmuxPane: '%7', paneOwner: release.tag,
env: { HARNESS_HOOK_ROUTES_DIR: routes }, input: sessionEnd })
}
expect(atRelease.requests).toEqual([])
expect(atDev.requests).toHaveLength(bodies.length)
})
it('keeps the command\'s own --port and --data-dir, as every installed command carried them, when the pane names no daemon it can trust', async () => {
const { dir, routes, release, dev } = computer()
const atRelease = await collect()
const atDev = await collect()
const hook = (paneOwner: string, extra: Partial<RunHookOpts> = {}) => runHook({
port: atDev.port, dataDir: dev.dataDir, tmuxPane: '%7', paneOwner, env: { HARNESS_HOOK_ROUTES_DIR: routes }, input: sessionEnd, ...extra,
})
const record = hookRouteFile(release.tag, routes)
// An untagged pane in a session Harness named (a pane from before the tag), and a tag with no record
// (a daemon from before the records).
await hook('')
await hook(release.tag)
// A record that is not the tag's own: another daemon's folder under this tag.
publishHookRoute(release.dataDir, atRelease.port, routes)
writeFileSync(record, JSON.stringify({ dataDir: dev.dataDir, port: atRelease.port }), { mode: 0o600 })
await hook(release.tag)
// A record others could have written, in a folder others could write, and one whose folder is gone.
publishHookRoute(release.dataDir, atRelease.port, routes)
chmodSync(record, 0o666)
await hook(release.tag)
publishHookRoute(release.dataDir, atRelease.port, routes)
chmodSync(routes, 0o777)
await hook(release.tag)
chmodSync(routes, 0o700)
const gone = join(dir, 'gone')
mkdirSync(gone)
publishHookRoute(gone, atRelease.port, routes)
rmSync(gone, { recursive: true })
await hook(harnessPaneOwner(gone))
expect(atRelease.requests).toEqual([])
expect(atDev.requests).toHaveLength(6)
// And with the record in order, the same hook goes to the release daemon.
publishHookRoute(release.dataDir, atRelease.port, routes)
await daemonSocketFor(atRelease.port, release.dataDir)
await hook(release.tag)
expect(atRelease.requests).toHaveLength(1)
})
it('offline, writes its registry row into the daemon that made the pane, which reads it when it is back', async () => {
const { dir, routes, release, dev } = computer()
const claudeProjectsDir = join(dir, 'claude-projects')
mkdirSync(join(claudeProjectsDir, 'demo'), { recursive: true })
const transcriptPath = join(claudeProjectsDir, 'demo', 'session-offline.jsonl')
writeFileSync(transcriptPath, '{}\n')
// The release daemon is down: nothing listens on port 9.
publishHookRoute(release.dataDir, 9, routes)
await runHook({
port: 9, dataDir: dev.dataDir, tmuxPane: '%7', processEngine: 'claude', claudeProjectsDir,
paneSession: 'mine', paneOwner: release.tag, env: { HARNESS_HOOK_ROUTES_DIR: routes },
input: { hook_event_name: 'SessionStart', session_id: 'session-offline', transcript_path: transcriptPath, cwd: '/tmp/demo', source: 'startup' },
})
const rows = (folder: string) => { try { return JSON.parse(readFileSync(join(folder, 'registry.json'), 'utf8')) as Array<{ sessionId: string }> } catch { return null } }
expect(rows(release.dataDir)?.map((row) => row.sessionId)).toEqual(['session-offline'])
expect(rows(dev.dataDir)).toBeNull()
})
it('looks where the daemons record by default', () => {
// lib/hookRoutes.ts writes under env.HARNESS_HOOK_ROUTES_DIR, whose default is the product root's.
expect(readFileSync(HOOK, 'utf8')).toContain("process.env.HARNESS_HOOK_ROUTES_DIR || join(homedir(), '.harness', 'hook-routes')")
})
})
describe('hook notify in a Harness pty host pane (Windows)', () => {
const sessionStart = () => {
const recordings = JSON.parse(readFileSync(new URL('./lib/__fixtures__/swarm-prompt-hooks.json', import.meta.url), 'utf8'))
return { ...recordings.claude.input, hook_event_name: 'SessionStart' }
}
it('names its pane by HARNESS_PANE when there is no TMUX_PANE', async () => {
const { port, requests } = await collect()
await runHook({ port, env: { HARNESS_PANE: 'p3:%1007' }, input: sessionStart() })
expect(requests.map((request) => request.url)).toEqual(['/api/hook/session-start'])
expect(requests[0].body.runtimeHints).toEqual([{ backend: 'ptyhost', instance: 'p3', paneId: '%1007' }])
expect(requests[0].body.tmuxPane).toBeUndefined()
})
it.each(['p2-0.4.21-dev.win1', 'p2-h0123456789ab'])('names a versioned pty host\'s pane by HARNESS_PANE: %s', async (instance) => {
const { port, requests } = await collect()
await runHook({ port, env: { HARNESS_PANE: `${instance}:%7` }, input: sessionStart() })
expect(requests[0].body.runtimeHints).toEqual([{ backend: 'ptyhost', instance, paneId: '%7' }])
})
it('keeps naming a tmux pane by TMUX_PANE, and ignores a HARNESS_PANE that is not one', async () => {
const { port, requests } = await collect()
await runHook({ port, tmuxPane: '%42', env: { HARNESS_PANE: 'p3:%1007' }, input: sessionStart() })
expect(requests[0].body.runtimeHints).toEqual([{ backend: 'tmux', paneId: '%42' }])
const bad = await collect()
await runHook({ port: bad.port, env: { HARNESS_PANE: 'p3:1007' }, input: sessionStart() })
expect(bad.requests).toEqual([])
const odd = await collect()
await runHook({ port: odd.port, env: { HARNESS_PANE: 'p2-0.4.21 x:%7' }, input: sessionStart() })
expect(odd.requests).toEqual([])
const empty = await collect()
await runHook({ port: empty.port, env: { HARNESS_PANE: '' }, input: sessionStart() })
expect(empty.requests).toEqual([])
})
})
/**
* Audit W1 (docs/security/2026-11-02-team-account-windows.md): on Windows the hook posted the full local credential to
* the daemon's TCP port, which the Team account's daemon can hold from boot. It now posts over the daemon's pipe, proving
* the daemon's token, and with no live pipe it posts nothing, as on macOS with no socket. Node on a Mac cannot open a
* Windows pipe, so a preload sets the platform to win32 and dials a Unix socket named for the pipe's id instead.
*/
describe('hook notify posts over the daemon\'s pipe on Windows (W1)', () => {
const sessionStart = () => {
const recordings = JSON.parse(readFileSync(new URL('./lib/__fixtures__/swarm-prompt-hooks.json', import.meta.url), 'utf8'))
return { ...recordings.claude.input, hook_event_name: 'SessionStart' }
}
/** A data folder short enough for a socket, with the daemon's token, and a preload that runs the hook as on Windows. */
function windowsData(): { dataDir: string; token: Buffer; id: string; socket: string; preload: string } {
const dataDir = mkdtempSync('/tmp/hkp-'); tmpDirs.push(dataDir)
const token = randomBytes(32), id = randomBytes(16).toString('hex')
writeFileSync(join(dataDir, 'daemon-token'), `${token.toString('hex')}\n`, { mode: 0o644 })
const preload = join(dataDir, 'win32-pipe.mjs')
writeFileSync(preload, [
"import http from 'node:http'",
"Object.defineProperty(process, 'platform', { value: 'win32' })",
'const dial = http.Agent.prototype.createConnection',
'http.Agent.prototype.createConnection = function (options, ...rest) {',
// Any name ending in harness-<id>, local pipe or not: the hook's own check is what refuses one.
' const id = /harness-([0-9a-f]{32})$/.exec(options.socketPath ?? "")?.[1]',
` const socket = id && ${JSON.stringify(dataDir)} + '/harness-' + id`,
' return dial.call(this, socket ? { ...options, socketPath: socket, path: socket } : options, ...rest)',
'}',
].join('\n') + '\n')
return { dataDir, token, id, socket: join(dataDir, `harness-${id}`), preload }
}
function record(dataDir: string, port: number, fields: Record<string, unknown>): void {
writeFileSync(join(dataDir, `daemon-${port}.json`), JSON.stringify({ port, ...fields }) + '\n', { mode: 0o644 })
}
/** The daemon's pipe server, as the daemon serves it (lib/localSocket.ts): every request proves the token. */
async function pipeDaemon(socket: string, token: Buffer, answer: (res: import('http').ServerResponse) => void = (res) => res.end('{}')) {
const requests: Array<{ url: string; trusted: boolean; hookToken: unknown; credential: unknown }> = []
const server = await listenLocalSocket((req, res) => {
req.resume()
req.on('end', () => {
requests.push({ url: req.url ?? '', trusted: isTrustedLocal(req), hookToken: req.headers['x-harness-hook-token'], credential: req.headers['x-harness-local'] })
answer(res)
})
}, socket, { token })
pipeServers.push(server.close)
return requests
}
const run = (port: number, dataDir: string, preload: string, extra: Partial<RunHookOpts> = {}) =>
runHook({ port, dataDir, env: { HARNESS_PANE: 'p1:%1', NODE_OPTIONS: `--import ${pathToFileURL(preload).href}` }, input: sessionStart(), ...extra })
it('posts over the daemon\'s pipe, with the pipe auth and no credential, and nothing to the port', async () => {
const { dataDir, token, id, socket, preload } = windowsData()
const tcp = await collect()
record(dataDir, tcp.port, { pipe: `\\\\.\\pipe\\harness-${id}`, pid: process.pid })
const requests = await pipeDaemon(socket, token)
await run(tcp.port, dataDir, preload)
expect(requests).toEqual([{ url: '/api/hook/session-start', trusted: true, hookToken: undefined, credential: undefined }])
expect(tcp.requests).toEqual([])
})
it('finds the daemon by its record when the hook was given the port it bound, not the one it was configured with', async () => {
const { dataDir, token, id, socket, preload } = windowsData()
const tcp = await collect()
writeFileSync(join(dataDir, 'daemon-18473.json'), JSON.stringify({ port: tcp.port, pipe: `\\\\.\\pipe\\harness-${id}`, pid: process.pid }))
const requests = await pipeDaemon(socket, token)
await run(tcp.port, dataDir, preload)
expect(requests.map((request) => request.url)).toEqual(['/api/hook/session-start'])
expect(tcp.requests).toEqual([])
})
it.each([
['no record', () => undefined],
['a record with no pipe', () => ({ pid: process.pid })],
['a record with no pid', (id: string) => ({ pipe: `\\\\.\\pipe\\harness-${id}` })],
['a pipe on another computer', (id: string) => ({ pipe: `\\\\fileserver\\pipe\\harness-${id}`, pid: process.pid })],
['a file named as a pipe', (id: string) => ({ pipe: `C:\\Users\\Public\\harness-${id}`, pid: process.pid })],
['a daemon that has exited', (id: string) => ({ pipe: `\\\\.\\pipe\\harness-${id}`, pid: exitedPid() })],
// The daemon is this account's: a pid another account runs (EPERM; pid 1 is root's) is one reused since it exited,
// and whoever has it may have created the pipe of the recorded name (Quinn 2's review of #2605).
...(process.getuid?.() === 0 ? [] : [['a pid another account runs now', (id: string) => ({ pipe: `\\\\.\\pipe\\harness-${id}`, pid: 1 })] as const]),
] as const)('posts nothing, to the pipe or the port, with %s', async (_name, fields) => {
const { dataDir, token, id, socket, preload } = windowsData()
const tcp = await collect()
const value = fields(id)
if (value) record(dataDir, tcp.port, value)
const requests = await pipeDaemon(socket, token)
await run(tcp.port, dataDir, preload)
expect(requests).toEqual([])
expect(tcp.requests).toEqual([])
})
it.each(['missing', 'linked', 'not a token'] as const)('posts nothing, to the pipe or the port, when the daemon\'s token is %s', async (fault) => {
const { dataDir, token, id, socket, preload } = windowsData()
const tcp = await collect()
record(dataDir, tcp.port, { pipe: `\\\\.\\pipe\\harness-${id}`, pid: process.pid })
rmSync(join(dataDir, 'daemon-token'))
if (fault === 'linked') {
// A link is refused even to a token file inside the data folder: NTFS gives the hook no owner to check.
writeFileSync(join(dataDir, 'token'), `${token.toString('hex')}\n`)
symlinkSync(join(dataDir, 'token'), join(dataDir, 'daemon-token'))
}
if (fault === 'not a token') writeFileSync(join(dataDir, 'daemon-token'), `${token.toString('hex').toUpperCase()}\n`)
const requests = await pipeDaemon(socket, token)
await run(tcp.port, dataDir, preload)
expect(requests).toEqual([])
expect(tcp.requests).toEqual([])
})
// What the hook does with an answer: a held Hermes admission is retried (four posts in all). Whatever answers on the
// pipe without the daemon's proof is not the daemon, and its answer is not taken: one post, then the hook moves on.
it.each([['the daemon\'s proof', 4], ['a wrong proof', 1]] as const)('takes an answer only with the daemon\'s proof: %s', async (proof, posts) => {
const { dataDir, token, id, socket, preload } = windowsData()
const tcp = await collect()
record(dataDir, tcp.port, { pipe: `\\\\.\\pipe\\harness-${id}`, pid: process.pid })
const held = (res: import('http').ServerResponse) => { res.writeHead(202); res.end(JSON.stringify({ pending: false, retry: true })) }
let attempts = 0
if (proof === 'a wrong proof') {
const impostor = createServer((req, res) => {
req.resume()
req.on('end', () => { attempts++; res.setHeader('x-harness-proof', 'a'.repeat(64)); held(res) })
})
servers.push(impostor)
await new Promise<void>((resolve) => { impostor.listen(socket, resolve) })
} else {
const requests = await pipeDaemon(socket, token, (res) => { attempts++; held(res) })
void requests
}
await run(tcp.port, dataDir, preload, {
tmuxPane: '%82', engine: 'hermes', processEngine: 'hermes', windowsProcessTable: true,
processExecutable: 'python3', processArgs: 'python3 /opt/venvs/hermes/lib/python3.12/site-packages/hermes-agent/hermes',
hermesHome: join(dataDir, 'hermes'), hermesSource: 'cli',
input: { hook_event_name: 'on_session_start', session_id: '20260810_120000_a1b2c3' },
})
expect(attempts).toBe(posts)
expect(tcp.requests).toEqual([])
})
})