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
#!/usr/bin/env node
/**
* Pane-scoped session hook shared by the supported hook-capable engines.
*
* Self-contained — node built-ins only, no dependency on the adapter's
* node_modules (it runs inside the user's `claude` process).
*
* SessionStart: registers terminal hints plus session metadata with the adapter,
* but only from an authenticated tmux context.
* SessionEnd: asks the adapter to reconcile the terminal; process discovery remains
* the authority for whether the agent exists.
*
* Always exits 0 quickly and swallows every error, so it can never block or
* delay claude's session start/teardown.
*/
import http from 'node:http'
import { execFile, execFileSync } from 'node:child_process'
import { createHash, createHmac, randomBytes, randomUUID, timingSafeEqual } from 'node:crypto'
import {
accessSync,
closeSync,
constants,
fchmodSync,
fstatSync,
fsyncSync,
mkdirSync,
lstatSync,
openSync,
readFileSync,
readdirSync,
readSync,
realpathSync,
renameSync,
rmSync,
statSync,
writeFileSync,
} from 'node:fs'
import { basename, delimiter, dirname, isAbsolute, join, relative, resolve, sep, win32 } from 'node:path'
import { homedir, uptime } from 'node:os'
import { fileURLToPath } from 'node:url'
const BOOT_TOLERANCE_SEC = 120
const HOOK_STARTED_AT = performance.now()
// Self-imposed budget, well under the 10s timeout the vendor hook entries carry: a hook that overruns
// stalls the user's turn, so every optional step checks `remainingBudget()` and gives up rather than
// block. The override exists because that budget is a wall-clock assumption — on a loaded machine (a
// parallel test run, a busy CI box) a cold Node start plus lock retries can eat it before the offline
// registry fallback is reached, and the fallback then silently does nothing. Tests set it explicitly so
// they measure behaviour instead of the host's load. Clamped, and never below the shipped default.
const SHIPPED_DEADLINE_MS = 4500
const HOOK_DEADLINE_MS = Math.min(60_000, Math.max(SHIPPED_DEADLINE_MS, Number(process.env.HARNESS_HOOK_DEADLINE_MS) || 0))
// Each step's own limit (`execFileText`: tmux 2 s, ps and sqlite3 3 s, lsof 1.5 s) is a wall-clock assumption too, and
// the override has to move them with the budget or it does not do what it says: under a loaded full test
// run (load 36, six workers) the Hermes fallback's fake tmux, ps and sqlite3 each took longer than their
// step's limit with 30 s of budget left, the lookup read as no answer, and no registry was written
// (hookNotify.spec.ts, 3 of 3 Hermes cases). 1 with the shipped budget: a hook as shipped is unchanged.
const STEP_SCALE = HOOK_DEADLINE_MS / SHIPPED_DEADLINE_MS
/** A step's limit under the budget in force. Whole milliseconds: child_process refuses a fractional timeout. */
function stepLimit(ms) {
return Math.round(ms * STEP_SCALE)
}
const EXIT_RESERVE_MS = 500
const LOCK_RETRIES = 60
const LOCK_RETRY_MS = 25
const CURSOR_TASK_MAX_AGE_MS = 10 * 60_000
const CURSOR_TASK_MAX_ENTRIES = 64
const CURSOR_TASK_MAX_INPUT_BYTES = 128 * 1024
const CODEX_META_MAX_BYTES = 128 * 1024
function remainingBudget(reserve = EXIT_RESERVE_MS) {
return Math.max(0, HOOK_DEADLINE_MS - (performance.now() - HOOK_STARTED_AT) - reserve)
}
// Claude Code reports the model as {id, display_name}; Codex/Cursor as a plain string. The registry stores
// a string, so pick the id rather than shipping the object.
function modelName(value) {
if (typeof value === 'string') return value
return typeof value?.id === 'string' ? value.id : null
}
/**
* The daemon this hook reports to, once the pane it came from has named it (`routeToPaneOwner`): its data
* folder and port, in place of the `--data-dir` and `--port` the installed command carries.
*/
let routed = null
function argPort() {
if (routed) return routed.port
const i = process.argv.indexOf('--port')
if (i !== -1 && process.argv[i + 1]) return parseInt(process.argv[i + 1], 10)
return parseInt(process.env.AGENT_ADAPTER_PORT || '18473', 10)
}
function argValue(name, fallback) {
const i = process.argv.indexOf(name)
if (i !== -1 && process.argv[i + 1]) return process.argv[i + 1]
return fallback
}
function argEngine() {
const i = process.argv.indexOf('--engine')
const value = i !== -1 ? process.argv[i + 1] : ''
return value === 'codex' || value === 'cursor' || value === 'hermes' || value === 'commandcode' || value === 'devin' || value === 'muse' || value === 'grok' || value === 'agy' || value === 'copilot' ? value : 'claude'
}
/** Copilot names its hook event only on the command line, like agy. */
function argCopilotEvent() {
const i = process.argv.indexOf('--copilot-event')
const value = i !== -1 ? process.argv[i + 1] : ''
return ['sessionStart', 'userPromptSubmitted', 'agentStop', 'sessionEnd'].includes(value) ? value : ''
}
/**
* agy names its hook event nowhere in the payload, so the installer puts it on the command line.
*
* Everything else in the payload is camelCase (protojson): `conversationId`, `workspacePaths`,
* `transcriptPath`, `modelName`, and on Stop `terminationReason` / `fullyIdle`.
*/
function argAgyEvent() {
const i = process.argv.indexOf('--agy-event')
const value = i !== -1 ? process.argv[i + 1] : ''
return value === 'PreInvocation' || value === 'Stop' ? value : ''
}
function paths() {
const cliDir = join(homedir(), '.harness', 'cli')
const dataDir = routed?.dataDir ?? argValue('--data-dir', process.env.ADAPTER_DATA_DIR || join(cliDir, 'data'))
const claudeProjectsDir = argValue('--claude-projects-dir', process.env.CLAUDE_PROJECTS_DIR || join(homedir(), '.claude', 'projects'))
const codexHome = argValue('--codex-home', process.env.CODEX_HOME || join(homedir(), '.codex'))
const grokHome = argValue('--grok-home', process.env.GROK_HOME || join(homedir(), '.grok'))
const cursorHome = process.env.CURSOR_DATA_DIR?.trim() || argValue('--cursor-home', process.env.CURSOR_HOME || join(homedir(), '.cursor'))
const hermesHome = argValue('--hermes-home', process.env.HERMES_HOME || join(homedir(), '.hermes'))
const commandcodeHome = argValue('--commandcode-home', process.env.COMMANDCODE_HOME || join(homedir(), '.commandcode'))
const devinHome = argValue('--devin-home', process.env.DEVIN_HOME || join(homedir(), '.local', 'share', 'devin', 'cli'))
const copilotHome = argValue('--copilot-home', process.env.COPILOT_HOME || join(homedir(), '.copilot'))
const agyHome = argValue('--agy-home', process.env.AGY_HOME || join(homedir(), '.gemini', 'antigravity-cli'))
return {
dataDir,
registryFile: join(dataDir, 'registry.json'),
bootFile: join(dataDir, 'registry-boot'),
claudeProjectsDir,
codexSessionsDir: join(codexHome, 'sessions'),
grokHome,
grokSessionsDir: join(grokHome, 'sessions'),
cursorProjectsDir: join(cursorHome, 'projects'),
hermesDb: join(hermesHome, 'state.db'),
commandcodeProjectsDir: join(commandcodeHome, 'projects'),
devinHome,
devinLocksDir: join(devinHome, 'session_locks'),
agyHome,
agyBrainDir: join(agyHome, 'brain'),
agyPresenceDir: join(agyHome, 'presence'),
copilotHome,
copilotSessionsDir: join(copilotHome, 'session-state'),
}
}
/** Copilot's deterministic transcript layout, duplicated here because the hook cannot import src/. */
function copilotTranscriptPath(p, sessionId) {
if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(sessionId || '')) return undefined
return join(p.copilotSessionsDir, sessionId, 'events.jsonl')
}
/**
* Is this agy conversation the PANE's, or a sub-agent's?
*
* agy gives every sub-agent its own conversation id, its own transcript AND its own hooks — fired with
* the parent's `TMUX_PANE`. Registering those rebinds the pane to whichever child announced last:
* measured on a three-sub-agent run as one agent attaching to three different sessions in four
* seconds, after which the web pane showed the CHILDREN's messages and the parent's `Task` rows never
* rendered at all.
*
* The discriminator is `presence/<id>.lock`, which agy creates only for a top-level conversation —
* measured: four locks on this machine, all parents; the six sub-agent conversations have none. It is
* also ordered safely, created BEFORE the first hook of that conversation (lock 17:57:14, first hook
* 17:57:15, transcript not until 17:57:17), so a real new session is never mistaken for a child.
*/
function agyIsPaneConversation(p, conversationId) {
if (!conversationId) return false
try {
return statSync(join(p.agyPresenceDir, `${conversationId}.lock`)).isFile()
} catch {
return false
}
}
/** agy's deterministic transcript layout, duplicated here because the hook cannot import from src/. */
function agyTranscriptPath(p, conversationId) {
if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(conversationId || '')) return undefined
return join(p.agyBrainDir, conversationId, '.system_generated', 'logs', 'transcript_full.jsonl')
}
/** True when the path is a real file on disk right now (undefined/missing → false). */
function existsPath(file) {
if (typeof file !== 'string' || !file) return false
try { return statSync(file).isFile() } catch { return false }
}
/** Resolve Grok's authoritative update log. Normal paths use URL-encoded cwd; very long paths use a
* hashed directory with a `.cwd` sidecar, so scan only that one level as a bounded fallback. */
function grokTranscriptPath(p, cwd, sessionId) {
if (typeof cwd !== 'string' || !cwd || typeof sessionId !== 'string'
|| !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(sessionId)) return ''
const direct = join(p.grokSessionsDir, encodeURIComponent(cwd), sessionId, 'updates.jsonl')
if (existsPath(direct)) return direct
try {
for (const entry of readdirSync(p.grokSessionsDir, { withFileTypes: true })) {
if (!entry.isDirectory()) continue
const group = join(p.grokSessionsDir, entry.name)
let recorded = ''
try { recorded = readFileSync(join(group, '.cwd'), 'utf8').trim() } catch { continue }
if (recorded !== cwd) continue
const candidate = join(group, sessionId, 'updates.jsonl')
if (existsPath(candidate)) return candidate
}
} catch { /* state root may not exist yet */ }
return ''
}
function grokHookEvent(value) {
const key = String(value || '')
.replace(/([a-z0-9])([A-Z])/g, '$1_$2')
.replace(/-/g, '_')
.toLowerCase()
return ({
session_start: 'SessionStart',
session_end: 'SessionEnd',
user_prompt_submit: 'UserPromptSubmit',
stop: 'Stop',
stop_failure: 'StopFailure',
})[key] || ''
}
/**
* True when a hook payload came from Devin rather than the engine the hook was armed for. Devin session
* ids are lowercase word slugs (`blue-agustinia`) and every live session holds
* `<DEVIN_HOME>/session_locks/<id>.lock`, while claude's are UUIDs — so the lock file is the tell.
*/
function isDevinSession(input, p) {
const id = typeof input?.session_id === 'string' ? input.session_id : ''
if (!id || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(id) || id.length > 64) return false
try { return statSync(join(p.devinLocksDir, `${id}.lock`)).isFile() } catch { return false }
}
function readStdin() {
return new Promise((resolve) => {
let data = ''
process.stdin.setEncoding('utf8')
process.stdin.on('data', (c) => (data += c))
process.stdin.on('end', () => resolve(data))
process.stdin.on('error', () => resolve(data))
// Safety: if stdin never ends, don't hang.
setTimeout(() => resolve(data), 1000)
})
}
function boundedPrompt(prompt) {
// An oversized/escape-heavy prompt must still announce its submission so the daemon
// clears earlier scope. Keep the serialized field within the hook receiver's bounds.
return Buffer.byteLength(JSON.stringify(prompt)) <= 128 * 1024 ? prompt : ''
}
/**
* POST one hook event to the daemon. Resolves true when it answered 2xx, false when it could not be
* reached or refused, 'held' for live admission backpressure, and 'late' when it took the request but
* did not answer within the budget. Neither live hold is permission for an offline registry write.
*
* 'late' is not "the daemon is down", and nothing may be written behind its back for it: the request is
* in its socket, and it handles it once it gets to it. A daemon whose event loop is held for a few
* seconds (or one simply slow to answer a session-start, which waits for a discovery pass) used to get
* the offline fallback on every hook meanwhile, each a registry row rebuilt without the name, launch,
* permission mode or close plan the daemon kept, merged over its own at its next save
* (e2e/stall.e2e.ts).
*/
/** This process's start, epoch ms: the engine ran the hook then. */
const DELIVERY_ID = randomUUID()
const FIRED_AT = Date.now() - Math.round(process.uptime() * 1000)
/** Mirrors MAX_SOCKET_PATH_BYTES in src/lib/localSocket.ts. */
const MAX_SOCKET_PATH_BYTES = 96
/** A socket file only this account could have made: never send the credential to anything else. */
function privateSocket(file) {
try {
const entry = lstatSync(file)
const uid = typeof process.getuid === 'function' ? process.getuid() : null
return entry.isSocket() && (entry.mode & 0o077) === 0 && (uid === null || entry.uid === uid)
} catch { return false }
}
/**
* The daemon's socket in this data folder. It is named for the daemon's configured port, and this hook's port may be
* the one the daemon was given instead when another account held that one, so the daemon's records say which
* (mirrors localSocketRoute in src/lib/localTransport.ts).
*/
function socketIn(dataDir, port) {
const beside = join(dataDir, `daemon-${port}.sock`)
if (Buffer.byteLength(beside) <= MAX_SOCKET_PATH_BYTES) return beside
const short = join(homedir(), '.harness', 's', createHash('sha256').update(dataDir).digest('hex').slice(0, 16), `daemon-${port}.sock`)
return Buffer.byteLength(short) <= MAX_SOCKET_PATH_BYTES ? short : null
}
function daemonSocket(port, dataDir) {
const named = socketIn(dataDir, port)
if (named && privateSocket(named)) return named
try {
for (const name of readdirSync(dataDir)) {
const configured = /^daemon-(\d+)\.json$/.exec(name)?.[1]
if (!configured) continue
const socket = socketIn(dataDir, Number(configured))
if (socket && JSON.parse(readPrivateStateFile(join(dataDir, name), 4096))?.port === port && privateSocket(socket)) return socket
}
} catch { /* An unreadable folder has no socket to offer. */ }
return null
}
/** Mirrors LOCAL_PIPE_RE in src/lib/windows/pipeAuth.ts: a pipe on this computer named harness-<id>, nothing else. A
* file, or another computer's pipe (an SMB connection that can carry this user's NTLM credentials), is none. */
const LOCAL_PIPE_RE = /^\\\\\.\\pipe\\harness-([0-9a-f]{32})$/
/** Mirrors TOKEN_TEXT in src/lib/windows/pipeAuth.ts. */
const DAEMON_TOKEN_RE = /^[0-9a-f]{64}\n?$/
/**
* The record's daemon still runs. Once it is gone, any account can create a pipe of the recorded name, and would hear
* this request, the prompt in it, before its answer can fail the proof. The daemon is this account's, so a pid that
* answers EPERM is another account's process now, one that took the pid since: no daemon (Quinn 2's review of #2605).
* Unlike processProof.ts pidAlive, which counts it alive for callers that also read the process table.
*/
function pidRuns(pid) {
try { process.kill(pid, 0); return true } catch { return false }
}
/**
* The daemon's pipe on Windows, as the CLI finds it (src/lib/windows/daemonPipe.ts): the record the core writes,
* `daemon-<configured port>.json`, names the pipe and the core's pid, both new on each start. This hook's port may be the
* one the daemon was given instead, so the records say which. Null with no record of a local pipe, no token, or a core
* that has exited. The pipe auth (src/lib/windows/pipeAuth.ts) proves the token without sending it, and the answer must
* prove it back.
*/
function windowsDaemonPipe(port, dataDir) {
const read = (name) => { try { return JSON.parse(readWindowsStateFile(dataDir, join(dataDir, name), 4096)) } catch { return null } }
let record = read(`daemon-${port}.json`)
if (!record) {
try {
for (const name of readdirSync(dataDir)) {
if (!/^daemon-\d+\.json$/.test(name)) continue
const candidate = read(name)
if (candidate?.port === port) { record = candidate; break }
}
} catch { /* An unreadable folder has no record to offer. */ }
}
const id = typeof record?.pipe === 'string' ? LOCAL_PIPE_RE.exec(record.pipe)?.[1] : null
if (!id || !Number.isSafeInteger(record.pid) || record.pid <= 0 || !pidRuns(record.pid)) return null
let text = ''
try { text = readWindowsStateFile(dataDir, join(dataDir, 'daemon-token'), 128) } catch { return null }
if (!DAEMON_TOKEN_RE.test(text)) return null
const token = Buffer.from(text.slice(0, 64), 'hex')
const nonce = id + randomBytes(16).toString('hex')
const mac = (separator) => createHmac('sha256', token).update(Buffer.of(separator)).update(nonce, 'utf8').digest('hex')
const proof = Buffer.from(mac(0x00), 'hex')
return {
address: { socketPath: record.pipe },
headers: { 'X-Harness-Auth': `${nonce}.${mac(0x01)}` },
proven: (value) => typeof value === 'string' && /^[0-9a-f]{64}$/.test(value) && timingSafeEqual(Buffer.from(value, 'hex'), proof),
}
}
/**
* How this hook reaches the daemon, and what it shows. Any account can bind the TCP port while the daemon restarts (audit
* H1, docs/security/2026-11-02-team-account-boundary.md), and whoever holds it would hear this request, the user's
* prompt in it included. So on macOS and Linux it goes over the 0600 socket; with none there the daemon is down, and
* this is the same as a failed post. A data folder too long to hold a socket has one under the home folder (socketIn). A
* home too long as well is the one case with no way but TCP, and then the hook-only token goes, never the credential. Over the socket the credential still goes because a daemon from
* before the hook token (an update not yet handed over) checks it there. On Windows it goes over the daemon's pipe, and
* never to the port: the Team account's daemon starts at boot, before the owner's, and could hold it (audit W1,
* docs/security/2026-11-02-team-account-windows.md).
*/
function hookRoute(port) {
const dataDir = paths().dataDir
if (process.platform === 'win32') return windowsDaemonPipe(port, dataDir)
const tokenRoute = (address, token) => token ? { address, headers: { 'X-Harness-Hook-Token': token } } : null
if (!socketIn(dataDir, port)) return tokenRoute({ host: '127.0.0.1', port }, readHookCredential('hook-token'))
const socketPath = daemonSocket(port, dataDir)
return socketPath ? tokenRoute({ socketPath }, readHookCredential()) : null
}
function post(port, path, body, onResponse) {
return new Promise((resolve) => {
const payload = JSON.stringify(body)
const route = hookRoute(port)
if (!route) { resolve(false); return }
let connected = false
const req = http.request(
{
...route.address,
path,
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Content-Length': Buffer.byteLength(payload),
...route.headers,
// When the engine ran this hook: this process's start, not its arrival, which can be seconds later on
// a loaded machine, after the engine has moved on to its next prompt (src/hookServer.ts hookFiredAt).
'X-Harness-Hook-Fired-At': String(FIRED_AT),
'X-Harness-Hook-Delivery-Id': DELIVERY_ID,
},
timeout: Math.max(1, Math.min(500, remainingBudget())),
},
(res) => {
// Before the body is read: an answer on the pipe without the daemon's proof is whatever took its name, not the
// daemon, and is never taken (src/lib/windows/pipeClient.ts pipeRequest).
if (route.proven && !route.proven(res.headers['x-harness-proof'])) { resolve(false); req.destroy(); return }
let response = ''
res.setEncoding('utf8')
res.on('data', (chunk) => { if (response.length < 16_384) response += chunk })
res.on('end', () => {
const ok = (res.statusCode || 0) >= 200 && (res.statusCode || 0) < 300
let reply
try { if (response.length <= 16_384) reply = JSON.parse(response) } catch { /* no structured reply */ }
if (res.statusCode === 429 || (res.statusCode === 202 && reply?.retry === true)) { resolve('held'); return }
if (path === '/api/hook/turn-stop' && ok && reply?.pending === true) { resolve('held'); return }
if (path === '/api/hook/turn-stop' && ok && reply?.duplicate === true) { resolve('duplicate'); return }
if (ok && onResponse && response.length <= 16_384) {
try { onResponse(JSON.parse(response)) } catch { /* Unavailable context never blocks a turn. */ }
}
resolve(ok)
})
}
)
req.on('socket', (socket) => {
if (!socket.connecting) connected = true
else socket.once('connect', () => { connected = true })
})
req.on('error', () => resolve(false))
req.on('timeout', () => {
req.destroy()
resolve(connected ? 'late' : false)
})
req.write(payload)
req.end()
})
}
/** Mirrors syncStateDirectory in src/lib/secureState.ts: Windows cannot flush a directory handle (EPERM), and NTFS
* journals the rename itself. */
function syncStateDirectory(directory) {
if (process.platform === 'win32') return
const fd = openSync(directory, 'r')
try { fsyncSync(fd) } finally { closeSync(fd) }
}
function secureStateDirectory(directory, create = true) {
if (create) mkdirSync(directory, { recursive: true, mode: 0o700 })
const fd = openSync(directory, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW)
try {
const stat = fstatSync(fd)
const uid = typeof process.getuid === 'function' ? process.getuid() : null
if (!stat.isDirectory() || (uid !== null && stat.uid !== uid)) {
throw new Error('state directory has unsafe owner or type')
}
const mode = stat.mode & 0o777
if (mode & 0o022) throw new Error('state directory is group/world writable')
if (mode !== 0o700) {
fchmodSync(fd, 0o700)
if ((fstatSync(fd).mode & 0o777) !== 0o700) {
throw new Error('state directory permissions could not be tightened')
}
}
} finally { closeSync(fd) }
}
function inspectPrivateStateFile(fd, maxBytes = Number.MAX_SAFE_INTEGER) {
const stat = fstatSync(fd)
const uid = typeof process.getuid === 'function' ? process.getuid() : null
if (!stat.isFile() || (uid !== null && stat.uid !== uid)) throw new Error('state file has unsafe owner or type')
if (stat.size > maxBytes) throw new Error('state file exceeds its size limit')
const mode = stat.mode & 0o777
if (mode & 0o022) throw new Error('state file is group/world writable')
if (mode !== 0o600) {
fchmodSync(fd, 0o600)
if ((fstatSync(fd).mode & 0o777) !== 0o600) {
throw new Error('state file permissions could not be tightened')
}
}
}
function readPrivateStateFile(file, maxBytes = Number.MAX_SAFE_INTEGER) {
const fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK)
try {
inspectPrivateStateFile(fd, maxBytes)
return readFileSync(fd, 'utf8')
} finally { closeSync(fd) }
}
function hardenPrivateStateFileIfPresent(file, maxBytes = Number.MAX_SAFE_INTEGER) {
let fd
try {
fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK)
} catch (error) {
if (error?.code === 'ENOENT') return false
throw error
}
try {
inspectPrivateStateFile(fd, maxBytes)
return true
} finally { closeSync(fd) }
}
function readHookCredential(name = 'hook-credential') {
let fd = null
try {
const dataDir = paths().dataDir
if (process.platform === 'win32') {
const value = readWindowsStateFile(dataDir, join(dataDir, name), 128).trim()
return /^[A-Za-z0-9_-]{43}$/.test(value) ? value : ''
}
secureStateDirectory(dataDir, false)
const uid = typeof process.getuid === 'function' ? process.getuid() : null
const file = join(dataDir, name)
fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK)
const stat = fstatSync(fd)
if (!stat.isFile() || stat.size > 128 || (stat.mode & 0o777) !== 0o600) return ''
if (uid !== null && stat.uid !== uid) return ''
const value = readFileSync(fd, 'utf8').trim()
return /^[A-Za-z0-9_-]{43}$/.test(value) ? value : ''
} catch { return '' } finally {
if (fd !== null) closeSync(fd)
}
}
/**
* NTFS gives Node no owner or mode bits, so on Windows the hook trusts its own data folder (the --data-dir it was
* installed with) and the profile. Below the data folder, a state file (the credential, the daemon's token and record)
* must be a plain file, not a link or junction (lstat does not call one a file): that check is what protects it. Its
* real path must also lie inside the profile or the data folder, as defence in depth. The file is opened and must be the
* very file lstat saw, so it cannot be swapped between the check and the read. Throws when there is none; '' when it is
* refused.
*/
function readWindowsStateFile(dataDir, file, maxBytes) {
const roots = [homedir(), dataDir].flatMap((root) => { try { return [realpathSync.native(root)] } catch { return [] } })
const inside = (target) => roots.some((root) => {
const rel = win32.relative(root, target)
return rel === '' || (rel !== '..' && !rel.startsWith('..\\') && !win32.isAbsolute(rel))
})
const link = lstatSync(file, { bigint: true })
if (!link.isFile() || link.size > BigInt(maxBytes) || !inside(realpathSync.native(file))) return ''
let fd = null
try {
fd = openSync(file, 'r')
const opened = fstatSync(fd, { bigint: true })
if (!opened.isFile() || opened.dev !== link.dev || opened.ino !== link.ino) return ''
return readFileSync(fd, 'utf8')
} finally {
if (fd !== null) closeSync(fd)
}
}
/**
* A Harness pty host pane names itself `HARNESS_PANE=<instance>:%N` (pty/src/panes.rs), as a tmux pane has
* `TMUX_PANE`. It is read only when there is no TMUX_PANE: a tmux pane inside a pty host pane is still the tmux pane.
* The instance is `p<protocol>` or `p<protocol>-<build>`, as cli/src/lib/ptyHost/instance.ts `PTY_HOST_INSTANCE`.
*/
function ptyHostPane(environment = process.env) {
if (environment.TMUX_PANE) return null
const match = /^(p\d{1,4}(?:-(?:[0-9A-Za-z.-]{1,32}|h[0-9a-f]{12}))?):(%\d{1,9})$/.exec(environment.HARNESS_PANE || '')
return match ? { instance: match[1], paneId: match[2] } : null
}
const PTY_PANE = ptyHostPane()
function terminalHookFields(tmuxPane) {
const runtimeHints = []
if (tmuxPane) runtimeHints.push({ backend: 'tmux', paneId: tmuxPane })
else if (PTY_PANE) runtimeHints.push({ backend: 'ptyhost', instance: PTY_PANE.instance, paneId: PTY_PANE.paneId })
return { tmuxPane, runtimeHints, callerPid: process.ppid }
}
function sleep(ms) {
return new Promise((resolve) => setTimeout(resolve, ms))
}
function execFileText(cmd, args, timeout, env, options = {}) {
return new Promise((resolve) => {
// Whole milliseconds. What is left of the budget is a fraction off the whole (performance.now()),
// and `execFile` throws ERR_OUT_OF_RANGE on a fractional timeout: once less was left than a step's
// own limit, as on the shipped 4.5 s budget after a second of earlier steps on a loaded machine, the
// step threw, and the offline registration it was part of was dropped.
const budget = Math.floor(Math.min(stepLimit(timeout), remainingBudget()))
if (budget < 50) { resolve(null); return }
execFile(cmd, args, { timeout: budget, ...(env && { env }), ...options }, (err, stdout) => {
resolve(err ? null : stdout)
})
})
}
/**
* Mirrors ensureUtf8Locale in src/lib/childLocale.ts. This process is spawned by the ENGINE, not by the
* daemon, so it inherits the engine's environment and has to set its own — and a hook child launched by
* an engine under systemd/docker/ssh usually has no locale at all. It shells out to both `tmux` and
* `ps`, and Linux mangles both without a UTF-8 locale: tmux turns the `-F` TAB separator into `_`, and
* procps substitutes `?` for every byte it cannot print. Measured on Ubuntu 24.04 + procps-ng 4.0.4,
* `⌘ <title>` reads back as `??? <title>` in BOTH comm and args, which kills both halves of the Command
* Code marker in processMatchScore. macOS never substitutes, so this is Linux-only and cannot regress
* it. Applied only when nothing usable is configured.
*/
function ensureUtf8Locale(env = process.env) {
if (process.platform !== 'linux') return
const configured = env.LC_ALL || env.LC_CTYPE || env.LANG
if (configured && /utf-?8/i.test(configured)) return
env.LC_ALL = 'C.UTF-8'
}
ensureUtf8Locale()
/**
* Mirrors psEnv in src/lib/childLocale.ts. `processRows` below anchors on the `lstart` column, whose
* shape belongs to LC_TIME, not to `ps`: only C and en_US produce `DOW MON DD HH:MM:SS YYYY`. en_GB and
* en_AU swap day and month, de_DE/fr_FR do that and add dots, ja_JP prints `火 9/15`, ru_RU puts the
* year before the time. Every one of those parses ZERO rows, the hook concludes the machine has no
* processes, and the engine it was launched by goes unrecognised. LC_ALL has to be cleared because it
* outranks both categories; LC_CTYPE stays UTF-8 so Linux procps keeps returning raw bytes.
*/
function psEnv(env = process.env) {
const configured = env.LC_ALL || env.LC_CTYPE || env.LANG
const ctype = configured && /utf-?8/i.test(configured) ? configured : 'C.UTF-8'
return { ...env, LC_ALL: '', LC_CTYPE: ctype, LC_TIME: 'C' }
}
/** Second line of defence: /proc is raw bytes, so a glibc without C.UTF-8 still resolves correctly. */
function repairMangledRows(rows) {
if (process.platform !== 'linux') return rows
return rows.map((row) => {
if (!row.executable.includes('?') && !row.args.includes('?')) return row
const args = readProcField(row.pid, 'cmdline')?.replace(/\0/g, ' ').trimEnd()
const executable = readProcField(row.pid, 'comm')?.trimEnd()
return { ...row, ...(executable && { executable }), ...(args && { args }) }
})
}
function readProcField(pid, field) {
try { return readFileSync(`/proc/${pid}/${field}`, 'utf8') } catch { return null }
}
// The tag a daemon puts on every pane it creates, and the name it gives their sessions (both in
// src/lib/harnessSessionLabel.ts, which hookNotify.spec.ts keeps these equal to). Before tmux 3.0 there
// are no pane options, and the tag rides in the pane's start command instead (`ownerCommand`); this format
// reads it there first and from the option otherwise, as the daemon's listing does on such a tmux
// (`paneOwnerFormat(false)`), and on a newer one a pane's start command never carries it.
const HARNESS_OWNER_OPTION = '@harness_daemon'
const HARNESS_SESSION_PREFIX = 'harness-'
const OWNER_COMMAND_PREFIX = '/usr/bin/env HARNESS_DAEMON='
// A pane's owner, read as the daemon reads it (harnessSessionLabel.ts paneOwnerFormat): from tmux 3.0 the
// pane's own option, which stays with the pane wherever the person moves it; before 3.0 the tag in its start
// command, or its window's tag in a session Harness named only, since elsewhere the window's tag names a
// pane the person split into, or joined into, an agent's window.
const PANE_OWNER_FORMAT = `#{${HARNESS_OWNER_OPTION}}`
const PANE_OWNER_FORMAT_OLD_TMUX = `#{?#{m:${OWNER_COMMAND_PREFIX}*,#{pane_start_command}},#{=${OWNER_COMMAND_PREFIX.length + 16}:pane_start_command},`
+ `#{?#{m:${HARNESS_SESSION_PREFIX}*,#{session_name}},#{${HARNESS_OWNER_OPTION}},}}`
let paneOptions
/** Whether this tmux has pane options (3.0+). A version it cannot read counts as new, as the daemon reads it (tmuxVersion.ts). */
async function tmuxHasPaneOptions() {
if (paneOptions === undefined) {
const version = /(\d+)\.(\d+)/.exec((await execFileText('tmux', ['-V'], 2000)) || '')
paneOptions = !version || Number(version[1]) >= 3
}
return paneOptions
}
/** A daemon's tag: its data folder, symlinks resolved, hashed — `harnessPaneOwner` in the daemon. */
function daemonPaneOwner(dataDir) {
let canonical = resolve(dataDir)
try { canonical = realpathSync(dataDir) } catch { /* not there: as given */ }
return createHash('sha256').update(canonical).digest('hex').slice(0, 16)
}
/**
* The pane, as tmux describes it, in one call: its root process, its session, and the tag of the daemon
* that made it (from the pane's option, or before tmux 3.0 from its start command). Read once per hook:
* the route to the daemon is chosen from it first, and the offline fallback reads it again. Undefined
* when tmux could not answer.
*/
const paneDescriptions = new Map()
function describePane(pane) {
if (!paneDescriptions.has(pane)) paneDescriptions.set(pane, readPaneDescription(pane))
return paneDescriptions.get(pane)
}
async function readPaneDescription(pane) {
const format = (await tmuxHasPaneOptions()) ? PANE_OWNER_FORMAT : PANE_OWNER_FORMAT_OLD_TMUX
const stdout = await execFileText('tmux', ['display-message', '-p', '-t', pane, `#{pane_pid}|#{session_name}|${format}`], 2000)
if (stdout === null) return undefined
const line = (stdout || '').trim()
const first = line.indexOf('|')
const last = line.lastIndexOf('|')
if (first < 0 || last <= first) return undefined
const pid = Number(line.slice(0, first))
const session = line.slice(first + 1, last)
const field = line.slice(last + 1)
const owner = field.startsWith(OWNER_COMMAND_PREFIX) ? field.slice(OWNER_COMMAND_PREFIX.length).split(' ')[0] : field
return { pid: Number.isSafeInteger(pid) && pid > 0 ? pid : null, session, owner }
}
/**
* Whether the daemon this hook writes for takes the pane for one of its agents at all, by the rule its
* discovery reads panes with (`ownedHere`): one it tagged, wherever the person moved it; an untagged one
* only in a session Harness named, or one an older build named (`<engine>-<ms>`) that its registry
* already holds (`taken: 'if-held'`); another daemon's, never. A session the person opened by hand is not
* an agent: with the daemon up, its hook is turned away. The offline fallback wrote a row for one all the
* same, and the daemon came back with an agent it would never have made and could not drive, "offline"
* for good (e2e/hookclient.e2e.ts). Undefined when tmux could not answer.
*/
async function paneFacts(pane, dataDir) {
const described = await describePane(pane)
if (!described) return undefined
const { pid, session, owner } = described
const taken = owner ? (owner === daemonPaneOwner(dataDir) ? 'yes' : 'no')
: session.startsWith(HARNESS_SESSION_PREFIX) ? 'yes'
: /^[a-z][a-z0-9]*-\d{13}$/.test(session) ? 'if-held' : 'no'
return { pid, taken }
}
/**
* Where every daemon on this computer says it listens, one file per pane tag (src/lib/hookRoutes.ts,
* which hookNotify.spec.ts keeps this equal to).
*/
function hookRoutesDir() {
return process.env.HARNESS_HOOK_ROUTES_DIR || join(homedir(), '.harness', 'hook-routes')
}
/**
* Report to the daemon that made the pane, not to the one whose command this is.
*
* Claude Code's and Codex's hooks are installed once per computer, in ~/.claude/settings.json and
* $CODEX_HOME/hooks.json, and each daemon wrote its own port and data folder into them as it started. With
* a dev daemon beside the release one, the last to start owned every hook: the other daemon's agents'
* hooks went to it, it turned them away (the pane was not its own), and their turn ends and session
* starts were lost. Each daemon now records its data folder and port under the tag it puts on its panes
* (`publishHookRoute`), and the hook looks the pane's tag up: a record whose data folder hashes to that tag
* routes this hook, its credential, and any offline write to that daemon. A record still names a daemon
* that is down: the hook's post fails and its offline write lands in that daemon's own registry, where it
* will read it. A pane with no tag, or a tag with no record (a daemon from before the records), keeps the
* command's own `--port` and `--data-dir`, as every installed command did.
*/
async function routeToPaneOwner(pane) {
if (!/^%\d+$/.test(pane || '')) return null
const described = await describePane(pane)
const tag = described?.owner
if (!tag || !/^[0-9a-f]{16}$/.test(tag)) return null
try {
const dir = hookRoutesDir()
secureStateDirectory(dir, false)
const record = JSON.parse(readPrivateStateFile(join(dir, `${tag}.json`), 4096))
const dataDir = record?.dataDir
const port = record?.port
if (typeof dataDir !== 'string' || !isAbsolute(dataDir) || !Number.isInteger(port) || port < 1 || port > 65535) return null
// The record must be the tag's own, and its folder still there: a folder since removed would be
// created again by the offline write, for a daemon that will never read it.
if (daemonPaneOwner(dataDir) !== tag || !statSync(dataDir).isDirectory()) return null
routed = { dataDir, port }
return routed
} catch { return null }
}
function argvTokens(args) {
return (String(args || '').match(/"[^"]*"|'[^']*'|\S+/g) || []).map((token) => {
const quoted = (token.startsWith('"') && token.endsWith('"')) || (token.startsWith("'") && token.endsWith("'"))
return quoted ? token.slice(1, -1) : token
})
}
/**
* Mirrors programName in src/lib/processTable.ts: the file name, lower-cased, without a Windows image's `.exe` or
* `.com` (`claude.exe`, `node.exe` read as `claude`, `node`; a `.cmd`/`.bat`/`.ps1` script is never a process image),
* either separator ending a folder; `cmd.exe` keeps its, since it is the Windows command processor, not Command
* Code's `cmd`.
*/
function programName(token) {
const path = String(token || '').replace(/[\\/]+$/, '')
const name = path.slice(Math.max(path.lastIndexOf('/'), path.lastIndexOf('\\')) + 1).toLowerCase()
return name === 'cmd.exe' ? name : name.replace(/\.(?:exe|com)$/, '')
}
function processEntrypoint(args) {
const tokens = argvTokens(args)
if (!tokens.length) return ''
let index = 0
let command = programName(tokens[index])
if (command === 'env') {
index++
while (index < tokens.length && (tokens[index].startsWith('-') || /^[A-Za-z_][A-Za-z0-9_]*=/.test(tokens[index]))) index++
command = programName(tokens[index] || '')
}
if (!/^(?:node|nodejs|bun|deno|python(?:\d+(?:\.\d+)*)?|bash|zsh|sh)$/.test(command)) return tokens[index] || ''
index++
const optionsWithValue = new Set(['-r', '--require', '--loader', '--import', '--conditions', '--inspect-port'])
const inlineCodeOptions = new Set(['-c', '--command', '-e', '--eval', '--print'])
while (index < tokens.length) {
const token = tokens[index]
if (token === '--') { index++; break }
if (token === '-m' && index + 1 < tokens.length) return tokens[index + 1]
if (inlineCodeOptions.has(token)) return ''
if (!token.startsWith('-')) break
index += optionsWithValue.has(token) && index + 1 < tokens.length ? 2 : 1
}
return tokens[index] || ''
}
/** Hermes' managed launchers exec Python -I -c with a path bootstrap, then either import main
* or run it through runpy. Require that executable prefix and actual code, never a script argument
* or a quoted mention. argv[0] is authoritative here: macOS can truncate an absolute `comm` path.
* Keep the standalone hook's copy in sync. */
/** macOS `ps` prints argv through vis(3): a newline as `\\012`, a backslash as `\\\\`. Read those back
* so a multi-line `-c` source is the source it runs. Linux `ps` prints argv as it is, without them. */
function unvisArgs(args) {
return args.replace(/\\([0-7]{3}|\\)/g, (_, code) => code === '\\' ? '\\' : String.fromCharCode(parseInt(code, 8)))
}
function hermesInlineLauncher(row) {
const args = unvisArgs(row.args).trim()
if (!/^python(?:\d+(?:\.\d+)*)?$/.test(programName(argvTokens(args)[0] ?? ''))) return false
const prefix = /^(?:"[^"]+"|'[^']+'|\S+)(?:\s+-(?:I|E|s|S|u|B|O{1,2}|q))*\s+-c\s+/.exec(args)
if (!prefix) return false
const source = args.slice(prefix[0].length).replace(/^["']/, '')
// Mask string literals before looking for Python statements. A print/prompt containing a whole
// launcher is still data. Keep literal values only to identify runpy's exact entry module.
const literals = []
const code = source.replace(/(['"])(?:\\[\s\S]|(?!\1)[^\\])*?\1/g, (literal) => {
literals.push(literal.slice(1, -1))
return `__literal${literals.length - 1}__`
})
if (!/^import\s+(?:(?:os|re|sys|runpy)\s*,\s*)*(?:sys|runpy)[;\s]+(?:os\.environ\.pop\(__literal\d+__,\s*None\)[;\s]+)*sys\.path\.insert\(\s*0,\s*__literal\d+__\s*\)/.test(code)) return false
if (/\bimport\s+hermes_bootstrap\b/.test(code)
&& /\bfrom\s+hermes_cli\.main\s+import\s+main\b/.test(code)
&& /\bsys\.exit\(\s*main\(\)\s*\)/.test(code)) return true
const run = /\brunpy\.run_module\(\s*__literal(\d+)__\s*,\s*run_name\s*=\s*__literal(\d+)__(?:\s*,\s*alter_sys\s*=\s*True)?\s*\)/.exec(code)
return !!run && literals[Number(run[1])] === 'hermes_cli.main' && literals[Number(run[2])] === '__main__'
}
const ENGINE_COMMANDS = {
claude: 'claude', codex: 'codex', cursor: 'agent', hermes: 'hermes', commandcode: 'cmd',
devin: 'devin', muse: 'muse', grok: 'grok', agy: 'agy', copilot: 'copilot',
}
const ENGINE_PATH_ENV = {
claude: 'CLAUDE_PATH', codex: 'CODEX_PATH', cursor: 'CURSOR_PATH', hermes: 'HERMES_PATH',
commandcode: 'COMMANDCODE_PATH', devin: 'DEVIN_PATH', muse: 'MUSE_PATH', grok: 'GROK_PATH',
agy: 'AGY_PATH', copilot: 'COPILOT_PATH',
}
function executableIdentity(path) {
try {
const realPath = realpathSync(path)
const stat = statSync(realPath)
return stat.isFile() ? { realPath, fileKey: `${String(stat.dev)}:${String(stat.ino)}` } : null
} catch {
return null
}
}
function commandIdentity(command) {
if (!command) return null
if (isAbsolute(command) || command.includes('/') || command.includes('\\')) {
try { accessSync(command, constants.X_OK) } catch { return null }
return executableIdentity(command)
}
for (const dir of String(process.env.PATH || '').split(delimiter).filter(Boolean)) {
const path = join(dir, command)
try { accessSync(path, constants.X_OK) } catch { continue }
const identity = executableIdentity(path)
if (identity) return identity
}
return null
}
function hookCommandOwnership(p) {
const agent = commandIdentity('agent')
const cursor = commandIdentity(process.env.CURSOR_PATH || 'cursor-agent')
const grok = commandIdentity(process.env.GROK_PATH || 'grok') || commandIdentity(join(p.grokHome, 'bin', 'grok'))
const cursorKeys = new Set(cursor ? [cursor.fileKey] : [])
const grokKeys = new Set(grok ? [grok.fileKey] : [])
if (agent && /\/cursor-agent\/versions\/[^/]+\/cursor-agent$/.test(agent.realPath.split(sep).join('/'))) {
cursorKeys.add(agent.fileKey)
}
return { agentFileKey: agent?.fileKey, cursorKeys, grokKeys }
}
function hookFileOwner(fileKey, ownership) {
if (!fileKey) return 'unknown'
const isCursor = ownership.cursorKeys.has(fileKey)
const isGrok = ownership.grokKeys.has(fileKey)
if (isCursor && isGrok) return 'conflict'
if (isCursor) return 'cursor'
if (isGrok) return 'grok'
return 'unknown'
}
/** Mirrors commTruncatedPrefixOf in src/lib/tmux.ts: Linux caps `comm` at 15 bytes (TASK_COMM_LEN). */
function commTruncatedPrefixOf(seen, want) {
if (process.platform !== 'linux' || !seen || !want) return false
return Buffer.byteLength(seen) === 15 && want.length > seen.length && want.startsWith(seen)
}
function processMatchScore(row, engine, ownership, allowAgentHint = false) {
const executable = programName(row.executable)
const entrypoint = processEntrypoint(row.args).toLowerCase()
const entrybase = programName(entrypoint)
const explicit = process.env[ENGINE_PATH_ENV[engine]]
const configured = String(explicit || ENGINE_COMMANDS[engine] || '').toLowerCase()
const configuredBase = programName(configured)
// Linux's `comm` cap is in bytes of the name as the kernel holds it: compared unstripped.
if (configuredBase && configuredBase !== 'agent' && (row.executable.toLowerCase() === configured
|| entrypoint === configured || executable === configuredBase || entrybase === configuredBase
|| commTruncatedPrefixOf(basename(row.executable).toLowerCase(), basename(configured).toLowerCase()))) return 4
if (engine === 'codex') return /@openai[\/\\]codex[\/\\]bin[\/\\]codex(?:\.js)?$/.test(entrypoint) ? 2 : 0
if (engine === 'cursor') {
if (executable === 'cursor-agent' || entrybase === 'cursor-agent') return 3
if (argvTokens(row.args).slice(0, 8).some((token) =>
/cursor-agent[\/\\]versions[\/\\][^/\\]+[\/\\]index\.js$/i.test(token))) return 3
if (executable === 'agent' || entrybase === 'agent') {
const aliasOwner = hookFileOwner(row.imageFileKey, ownership) !== 'unknown'
? hookFileOwner(row.imageFileKey, ownership)
: hookFileOwner(ownership.agentFileKey, ownership)
if (aliasOwner === 'cursor') return 4
if (aliasOwner === 'grok' || aliasOwner === 'conflict') return 0
return allowAgentHint ? 1 : 0
}
return 0
}
if (engine === 'commandcode') {
if (/^\s*⌘(?:\s|$)/.test(row.executable) || /^\s*⌘(?:\s|$)/.test(row.args)
|| executable === 'commandcode' || executable === 'command-code'
|| entrybase === 'commandcode' || entrybase === 'command-code') return 3
return /command-code[\/\\]dist[\/\\]index\.mjs$/.test(entrypoint) ? 2 : 0
}
if (engine === 'devin') return /devin[\/\\]cli[\/\\]_versions[\/\\][^/\\]+[\/\\]bin[\/\\]devin$/.test(entrypoint) ? 2 : 0
if (engine === 'hermes' && hermesInlineLauncher(row)) return 2
if (engine === 'hermes') return /hermes-agent[\/\\]hermes$/.test(entrypoint)
|| /^(?:hermes|hermes_cli)(?:\.|$)/.test(entrypoint) ? 2 : 0
if (engine === 'muse') return /^muse-bin-/.test(executable) || /^muse-bin-/.test(entrybase) ? 3 : 0
if (engine === 'grok') {
if (executable === 'grok' || entrybase === 'grok') return 3
if (executable === 'agent' || entrybase === 'agent') {
const aliasOwner = hookFileOwner(row.imageFileKey, ownership) !== 'unknown'
? hookFileOwner(row.imageFileKey, ownership)
: hookFileOwner(ownership.agentFileKey, ownership)
if (aliasOwner === 'grok') return 4
if (aliasOwner === 'cursor' || aliasOwner === 'conflict') return 0
return allowAgentHint ? 1 : 0
}
return /\.grok[\/\\]bin[\/\\]grok$/.test(entrypoint) ? 2 : 0
}
return /@anthropic-ai[\/\\]claude-code[\/\\]cli\.js$/.test(entrypoint) ? 2 : 0
}
/** Mirrors compareVersions in src/lib/ptyHost/launch.ts. */
/**
* Mirrors ptyHostBinary in src/lib/ptyHost/launch.ts: `HARNESS_PTY_BIN` as it is, else
* `<runtime>/pty/<version>/harness-pty.exe` for the version `<runtime>/pty/current-pty` names (the installed CLI's;
* a version name alone), else the one in `pty/` beside this script (the bundle's).
*/
function ptyHostBinary() {
const override = process.env.HARNESS_PTY_BIN?.trim()
if (override) return override
const binary = 'harness-pty.exe'
const root = join(process.env.ADAPTER_RUNTIME_DIR || join(homedir(), '.harness', 'runtime'), 'pty')
let version = ''
try { version = readFileSync(join(root, 'current-pty'), 'utf8').trim() } catch { /* none installed */ }
if (/^\d+(\.\d+)*$/.test(version)) {
const file = join(root, version, binary)
try { accessSync(file, constants.F_OK); return file } catch { /* the bundle's, then */ }
}
const beside = join(dirname(fileURLToPath(import.meta.url)), 'pty', binary)
try { accessSync(beside, constants.F_OK); return beside } catch { return null }
}
/**
* Windows has no `ps`: the PTY host lists the processes (`harness-pty ps --json`, pty/src/ps.rs), and the rows
* map as the daemon maps them (src/lib/windows/processTable.ts). A row without a start marker (a process the
* host could not open) can never be an identity and is dropped; a read that names nobody failed.
*/
async function windowsProcessRows() {
const binary = ptyHostBinary()
if (!binary) return null
// A busy machine's table is a few hundred KB of JSON: the daemon's own limit (src/lib/windows/processTable.ts).
const stdout = await execFileText(binary, ['ps', '--json'], 3000, undefined, { maxBuffer: 64 * 1024 * 1024, windowsHide: true })
if (stdout === null) return null
let table
try { table = JSON.parse(stdout) } catch { return null }
if (!table || !Array.isArray(table.rows)) return null
const rows = []
for (const row of table.rows) {
if (!row || typeof row !== 'object') continue
const { pid, parentPid, executable, startMarker, args, nativeArgv } = row
if (!Number.isSafeInteger(pid) || pid <= 0 || !Number.isSafeInteger(parentPid) || parentPid < 0) continue
if (typeof executable !== 'string' || typeof args !== 'string' || typeof startMarker !== 'string' || !startMarker) continue
rows.push({
pid, parentPid, executable, startMarker, args,
...(Array.isArray(nativeArgv) && nativeArgv.every((item) => typeof item === 'string') ? { nativeArgv } : {}),
})
}
return rows.length ? rows : null
}
async function processRows() {
if (process.platform === 'win32') return windowsProcessRows()
const stdout = await execFileText('ps', ['-axo', 'pid=,ppid=,comm=,lstart=,args='], 3000, psEnv())
if (stdout === null) return null
const rows = []
for (const line of stdout.split('\n')) {
const match = /^\s*(\d+)\s+(\d+)\s+(.+?)\s+(\S+\s+\S+\s+\d{1,2}\s+\d{1,2}:\d{2}:\d{2}\s+\d{4})\s*(.*)$/.exec(line)
if (!match) continue
rows.push({
pid: Number(match[1]),
parentPid: Number(match[2]),
executable: match[3],
startMarker: match[4],
args: match[5],
})
}
return repairMangledRows(rows)
}
function aliasRows(rows) {
return rows.filter((row) => programName(row.executable) === 'agent'
|| programName(processEntrypoint(row.args)) === 'agent')
}
async function enrichProcessImages(rows) {
const candidates = aliasRows(rows)
if (!candidates.length) return rows
const images = new Map()
if (process.platform === 'linux') {
for (const row of candidates) {
const identity = executableIdentity(`/proc/${row.pid}/exe`)
if (identity) images.set(row.pid, identity.fileKey)
}
} else if (process.platform === 'darwin') {
const stdout = await execFileText('lsof', ['-a', '-p', candidates.map((row) => row.pid).join(','), '-d', 'txt', '-Fn'], 1500)
let pid = null
let textFile = false
for (const line of String(stdout || '').split('\n')) {
if (/^p\d+$/.test(line)) {
pid = Number(line.slice(1))
textFile = false
} else if (line === 'ftxt') {
textFile = true
} else if (textFile && pid && line.startsWith('n') && !images.has(pid)) {
const identity = executableIdentity(line.slice(1).replace(/ \(deleted\)$/, ''))
if (identity) images.set(pid, identity.fileKey)
textFile = false
}
}
}
return rows.map((row) => images.has(row.pid) ? { ...row, imageFileKey: images.get(row.pid) } : row)
}
async function rootEngineProcess(rootPid, engine) {
const rawRows = await processRows()
if (!rawRows) return { state: 'unknown' }
const rows = await enrichProcessImages(rawRows)
const ownership = hookCommandOwnership(paths())
const children = new Map()
const byPid = new Map(rows.map((row) => [row.pid, row]))
for (const row of rows) {
const list = children.get(row.parentPid) || []
list.push(row)
children.set(row.parentPid, list)
}
const queue = [{ pid: rootPid, depth: 0 }]
let best = null
while (queue.length > 0) {
const current = queue.shift()
const row = byPid.get(current.pid)
const score = row ? processMatchScore(row, engine, ownership, true) : 0
if (row && score > 0 && (!best || current.depth < best.depth || (current.depth === best.depth && score > best.score))) {
best = { row, depth: current.depth, score }
}
for (const child of children.get(current.pid) || []) queue.push({ pid: child.pid, depth: current.depth + 1 })
}
if (!best) return { state: 'gone' }
const identity = { pid: best.row.pid, executable: best.row.executable, startMarker: best.row.startMarker }
let native = null
if (process.platform === 'linux') {
native = linuxOwnerBirth(identity.pid)
if (!native) return { state: 'unknown' }
identity.startTicks = native.startTicks
}
// Retain kernel facts across the registry lock and durable staging. A live PID with the
// same ticks can still have changed its command or parent since the pane/caller walk.
const current = () => {
if (!native) return true
const now = linuxOwnerBirth(identity.pid)
return !!now && now.startTicks === native.startTicks && now.parentPid === native.parentPid && now.command === native.command
}
return { state: 'alive', identity, current }
}
/**
* Hermes delegation children execute the same pane-scoped hook as the visible CLI session. During
* daemon downtime the regular hook server cannot apply its source guard, so consult Hermes' own store
* before writing the offline registry. Unknown is deliberately fail-closed: the startup reconciler can
* still create the process-owned agent and session repair can bind it once the daemon returns, whereas
* accepting an unknown row can replace the parent's session with a child.
*/
async function hermesTopLevelSession(dbPath, sessionId) {
if (!/^[0-9]{8}_[0-9]{6}_[0-9a-fA-F]{4,16}$/.test(String(sessionId || ''))) return false
// EVERY home on this machine, this one first. `hermes -p <name>` keeps its sessions in
// `~/.hermes/profiles/<name>/state.db`, and the block in a profile's config.yaml may still name the
// DEFAULT home (Hermes copies the config when it creates a profile, and older installs baked the
// default path into it) — so a profile session looked unknown here and was dropped, silently, on
// every registration the daemon was not up for (openharness#191). The extra stores are asked only
// when this one has no row, which on a single-home machine is never.
const homes = hermesHomes(dbPath)
for (let attempt = 0; attempt < 4; attempt++) {
if (attempt > 0) await sleep(75)
let sawStore = false
for (const db of homes) {
const raw = await execFileText('sqlite3', [
'-json', '-cmd', '.timeout 500', '-cmd', 'PRAGMA query_only=1', `file:${db}?mode=ro`,
`SELECT source FROM sessions WHERE id = '${sessionId}';`,
// As long as the process scan gets: on a loaded machine a second is not always enough to
// spawn sqlite3, and a lookup cut short drops a real session's registration.
], 3000)
if (raw === null) continue // unreadable store — another home may still hold the row
sawStore = true
try {
const rows = JSON.parse(raw.trim() || '[]')
if (!Array.isArray(rows) || rows.length === 0) continue
const source = typeof rows[0]?.source === 'string' ? rows[0].source : ''
return (source === '' || source === 'cli' || source === 'tui') ? db : false
} catch {
return false
}
}
if (!sawStore) return false
}
return false
}
/** `dbPath` and every sibling profile store, deduped, the given one first. */
function hermesHomes(dbPath) {
const home = dirname(dbPath)
const roots = [home]
// A profile store sits at <default home>/profiles/<name>/state.db, so the default home is two
// levels up from one and the profiles folder is beside the other. Both spellings are cheap to try.
const base = basename(dirname(home)) === 'profiles' ? dirname(dirname(home)) : home
if (base !== home) roots.push(base)
const out = roots.map((root) => join(root, 'state.db'))
let names = []
try { names = readdirSync(join(base, 'profiles')) } catch { return [...new Set(out)] }
for (const name of names.slice(0, 64)) out.push(join(base, 'profiles', name, 'state.db'))
return [...new Set(out)]
}
function bootTimeSec() {
return Math.round(Date.now() / 1000 - uptime())
}
// Which boot this is, named as src/lib/bootId.ts names it: the two read and write the same boot file, so
// they must agree. macOS has a per-boot id too; without it a boot was named by the moment it began, which
// moves with every step of the wall clock, and a hook that fell back to the registry after an NTP step
// or a long sleep took the step for a reboot and wrote a registry of its one agent (round 29).
let bootId = null
function currentBootId() {
if (bootId) return bootId
try {
const value = readFileSync('/proc/sys/kernel/random/boot_id', 'utf8').trim()
if (/^[0-9a-f-]{36}$/i.test(value)) return (bootId = `linux:${value}`)
} catch { /* not Linux */ }
if (process.platform === 'darwin') {
try {
const value = execFileSync('/usr/sbin/sysctl', ['-n', 'kern.bootsessionuuid'], { encoding: 'utf8', timeout: 1000 }).trim()
if (/^[0-9a-f-]{36}$/i.test(value)) return (bootId = `macos:${value}`)
} catch { /* sysctl unavailable: the moment the boot began, below */ }
}
return (bootId = `time:${bootTimeSec()}`)
}
function readSavedBoot(bootFile) {
try {
secureStateDirectory(dirname(bootFile), false)
const raw = readPrivateStateFile(bootFile, 256).trim()
if (!raw) return null
try {
const parsed = JSON.parse(raw)
return typeof parsed === 'string' ? parsed : raw
} catch { return raw }
} catch {
return null
}
}
function writeBoot(bootFile) {
let tmp = ''
let renamed = false
try {
secureStateDirectory(dirname(bootFile))
hardenPrivateStateFileIfPresent(bootFile, 256)
tmp = `${bootFile}.${process.pid}.${randomUUID()}.tmp`
const fd = openSync(tmp, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600)
try { writeFileSync(fd, currentBootId()); fsyncSync(fd) } finally { closeSync(fd) }
renameSync(tmp, bootFile)
renamed = true
syncStateDirectory(dirname(bootFile))
} catch {
// best effort
} finally {
if (tmp && !renamed) {
try { rmSync(tmp, { force: true }) } catch { /* best effort */ }
}
}
}
function rebootedSinceSnapshot(bootFile) {
const saved = readSavedBoot(bootFile)
if (saved === null) return false
const current = currentBootId()
if (saved.startsWith('linux:')) return saved !== current
// A macOS id that cannot be read now is no evidence of a reboot.
if (saved.startsWith('macos:')) return !current.startsWith('time:') && saved !== current
const savedNumber = Number(saved.replace(/^time:/, ''))
const currentNumber = current.startsWith('time:') ? Number(current.slice(5)) : bootTimeSec()
return !Number.isFinite(savedNumber) || Math.abs(currentNumber - savedNumber) > BOOT_TOLERANCE_SEC
}
function isWithin(root, file) {
const rel = relative(root, file)
return rel === '' || (!rel.startsWith('..') && !rel.startsWith('/') && !rel.startsWith('\\'))
}
function validTranscriptPath(engine, filePath, p) {
try {
const actual = realpathSync(filePath)
const root = realpathSync(
engine === 'codex' ? p.codexSessionsDir
: engine === 'grok' ? p.grokSessionsDir
: engine === 'agy' ? p.agyBrainDir
: engine === 'copilot' ? p.copilotSessionsDir
: engine === 'cursor' ? p.cursorProjectsDir
: engine === 'commandcode' ? p.commandcodeProjectsDir
: p.claudeProjectsDir,
)
const st = statSync(actual)
if (!st.isFile() || !isWithin(root, actual)) return false
if (engine === 'cursor') {
const id = basename(actual).replace(/\.jsonl$/, '')
if (!id || basename(dirname(actual)) !== id || basename(dirname(dirname(actual))) !== 'agent-transcripts') return false
}
const uid = typeof process.getuid === 'function' ? process.getuid() : null
return uid === null || st.uid === uid
} catch {
return false
}
}
function isCodexSubagent(input, p) {
const source = input && typeof input.source === 'object' && !Array.isArray(input.source)
? input.source
: null
if (source && source.subagent != null) return true
const file = typeof input.transcript_path === 'string' ? input.transcript_path : ''
if (!file || !validTranscriptPath('codex', file, p)) return false
let fd = null
try {
fd = openSync(file, 'r')
const buffer = Buffer.alloc(CODEX_META_MAX_BYTES)
const bytes = readSync(fd, buffer, 0, buffer.length, 0)
const firstLine = buffer.subarray(0, bytes).toString('utf8').split('\n').find((line) => line.trim())
if (!firstLine) return false
const record = JSON.parse(firstLine)
return record?.type === 'session_meta' && record?.payload?.source?.subagent != null
} catch {
return false
} finally {
if (fd !== null) {
try { closeSync(fd) } catch { /* best effort */ }
}
}
}
function removeLockOwnedBy(lockDir, token) {
try {
const owner = JSON.parse(readFileSync(join(lockDir, 'owner.json'), 'utf8'))
if (owner?.token === token) rmSync(lockDir, { recursive: true, force: true })
} catch { /* another owner or unsafe artifact must not be removed */ }
}
function processStartMarker(pid) {
if (!Number.isSafeInteger(pid) || pid <= 0) return null
try {
const stat = readFileSync(`/proc/${pid}/stat`, 'utf8')
const fields = stat.slice(stat.lastIndexOf(')') + 2).trim().split(/\s+/)
if (fields[19]) return `linux:${fields[19]}`
} catch { /* non-Linux or exited process; use ps below */ }
try {
const started = execFileSync('ps', ['-p', String(pid), '-o', 'lstart='], {
encoding: 'utf8', timeout: 1000, env: { ...psEnv(), TZ: 'UTC' },
}).trim()
return started ? `ps-c:${started}` : null
} catch { return null }
}
function processAlive(pid, startMarker = '') {
if (!Number.isSafeInteger(pid) || pid <= 0) return false
try { process.kill(pid, 0) } catch (error) { if (error?.code !== 'EPERM') return false }
if (!startMarker) return true
const current = processStartMarker(pid)
// Pre-upgrade ps markers may use another locale; a mismatch is not death.
const comparable = current !== null && ['linux:', 'ps-c:'].some(
(prefix) => startMarker.startsWith(prefix) && current.startsWith(prefix),
)
return !comparable || current === startMarker
}
// The legacy field stays empty for ps-c so old readers fall back to PID liveness during upgrade.
function processLockIdentity(pid) {
const generationMarker = processStartMarker(pid) || ''
return { startMarker: generationMarker.startsWith('ps-c:') ? '' : generationMarker, generationMarker }
}
function lockStartMarker(owner) {
return typeof owner?.generationMarker === 'string' ? owner.generationMarker
: typeof owner?.startMarker === 'string' ? owner.startMarker : ''
}
async function withRegistryLock(registryFile, fn) {
const lockDir = `${registryFile}.lock`
const dataDir = dirname(registryFile)
try {
secureStateDirectory(dataDir)
} catch { return }
const processIdentity = processLockIdentity(process.pid)
for (let i = 0; i < LOCK_RETRIES; i++) {
if (remainingBudget(750) < 50) return
const token = randomUUID()
let created = false
try {
mkdirSync(lockDir, { mode: 0o700 })
created = true
const ownerFile = join(lockDir, 'owner.json')
const ownerFd = openSync(ownerFile, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600)
try {
writeFileSync(ownerFd, JSON.stringify({ pid: process.pid, ...processIdentity, token }))
fsyncSync(ownerFd)
} finally { closeSync(ownerFd) }
try {
return fn()
} finally {
removeLockOwnedBy(lockDir, token)
}
} catch (error) {
if (created) removeLockOwnedBy(lockDir, token)
if (error?.code !== 'EEXIST') return
try {
const uid = typeof process.getuid === 'function' ? process.getuid() : null
const st = lstatSync(lockDir)
const ownerStat = lstatSync(join(lockDir, 'owner.json'))
if (!st.isDirectory() || st.isSymbolicLink() || (uid !== null && st.uid !== uid) || (st.mode & 0o777) !== 0o700
|| !ownerStat.isFile() || ownerStat.isSymbolicLink() || (uid !== null && ownerStat.uid !== uid)
|| (ownerStat.mode & 0o777) !== 0o600) return
const owner = JSON.parse(readFileSync(join(lockDir, 'owner.json'), 'utf8'))
const ownerPid = Number(owner?.pid)
const ownerStartMarker = lockStartMarker(owner)
const ownerToken = typeof owner?.token === 'string' ? owner.token : ''
if (!processAlive(ownerPid, ownerStartMarker) && ownerPid > 0 && ownerToken) {
const current = JSON.parse(readFileSync(join(lockDir, 'owner.json'), 'utf8'))
if (Number(current?.pid) === ownerPid
&& lockStartMarker(current) === ownerStartMarker
&& current?.token === ownerToken
&& !processAlive(ownerPid, ownerStartMarker)) {
rmSync(lockDir, { recursive: true, force: true })
continue
}
}
} catch {
// Lock disappeared or is still being initialized; wait without stealing it.
}
await sleep(LOCK_RETRY_MS)
}
}
}
function readJsonArray(file) {
try {
secureStateDirectory(dirname(file), false)
const arr = JSON.parse(readPrivateStateFile(file))
return Array.isArray(arr) ? arr : []
} catch (error) {
return error?.code === 'ENOENT' ? [] : null
}
}
function readRegistryState(file) {
try {
secureStateDirectory(dirname(file), false)
const rows = JSON.parse(readPrivateStateFile(file))
if (!Array.isArray(rows)) return null
if (rows.some((row) => row && typeof row === 'object'
&& Object.hasOwn(row, 'schemaVersion') && row.schemaVersion !== 2)) return null
const legacyRows = rows.filter((row) => !row || typeof row !== 'object' || !Object.hasOwn(row, 'schemaVersion'))
if (legacyRows.some((row) => !validLegacyRegistryRow(row))) return null
const v2Rows = rows.filter((row) => row && typeof row === 'object' && row.schemaVersion === 2)
if (v2Rows.length && !validV2Registry(v2Rows)) return null
return rows
} catch (error) {
return error?.code === 'ENOENT' ? [] : null
}
}
function writeRegistry(file, sessions, current = () => true) {
secureStateDirectory(dirname(file))
hardenPrivateStateFileIfPresent(file)
const tmp = `${file}.${process.pid}.${randomUUID()}.tmp`
let renamed = false
try {
const fd = openSync(tmp, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600)
try {
writeFileSync(fd, JSON.stringify(sessions, null, 2))
fchmodSync(fd, 0o600)
fsyncSync(fd)
} finally { closeSync(fd) }
if (!current()) return false
renameSync(tmp, file)
renamed = true
syncStateDirectory(dirname(file))
return true
} finally {
if (!renamed) {
try { rmSync(tmp, { force: true }) } catch { /* ignore */ }
}
}
}
function cursorPendingFile() {
return join(paths().dataDir, 'cursor-pending-tasks.json')
}
function boundedJson(value) {
try {
const serialized = JSON.stringify(value ?? {})
if (Buffer.byteLength(serialized) <= CURSOR_TASK_MAX_INPUT_BYTES) return JSON.parse(serialized)
} catch {
// use the bounded fallback
}
const input = value && typeof value === 'object' && !Array.isArray(value) ? value : {}
return {
description: typeof input.description === 'string' ? input.description.slice(0, 2_000) : '',
prompt: typeof input.prompt === 'string' ? input.prompt.slice(0, 16_000) : '',
model: typeof input.model === 'string' ? input.model.slice(0, 200) : '',
}
}
async function persistCursorTask(input) {
const sessionId = input.session_id || input.conversation_id
const toolUseId = input.tool_use_id
if (typeof sessionId !== 'string' || !sessionId || typeof toolUseId !== 'string' || !toolUseId) return
const file = cursorPendingFile()
await withRegistryLock(file, () => {
const now = Date.now()
const current = readJsonArray(file)
if (current === null) return
const existing = current.filter((item) =>
item
&& typeof item.sessionId === 'string'
&& typeof item.toolUseId === 'string'
&& typeof item.createdAt === 'number'
&& now - item.createdAt <= CURSOR_TASK_MAX_AGE_MS
&& item.toolUseId !== toolUseId)
existing.push({ sessionId, toolUseId, input: boundedJson(input.tool_input), createdAt: now })
writeRegistry(file, existing.slice(-CURSOR_TASK_MAX_ENTRIES))
})
}
async function clearCursorTasks(sessionId) {
if (typeof sessionId !== 'string' || !sessionId) return
const file = cursorPendingFile()
await withRegistryLock(file, () => {
const current = readJsonArray(file)
if (current === null) return
const next = current.filter((item) => !item || item.sessionId !== sessionId)
if (next.length) writeRegistry(file, next)
else {
try { rmSync(file, { force: true }) } catch { /* best effort */ }
}
})
}
function runtimeRouteKey(runtime) {
return `tmux\u0000${runtime.paneId}`
}
function runtimePlacementKey(runtime) {
return runtimeRouteKey(runtime)
}
function mergeRuntimes(current, observed) {
const merged = new Map()
for (const runtime of [...(Array.isArray(current) ? current : []), ...observed]) {
if (runtime?.backend === 'tmux') merged.set(runtimePlacementKey(runtime), runtime)
}
return [...merged.values()].sort((a, b) => runtimePlacementKey(a).localeCompare(runtimePlacementKey(b)))
}
// Every engine a registry row can name: the daemon's own list (src/engines/types.ts ENGINES), which
// hookNotify.spec.ts keeps this one equal to. A row naming one missing here made the whole registry read
// as damaged, and a hook while the daemon was down then registered nothing at all: `terminal` was
// missing, so one terminal open on the machine was enough (e2e/hookclient.e2e.ts).
const REGISTRY_ENGINES = new Set([
'claude', 'codex', 'cursor', 'opencode', 'pi', 'omp', 'hermes', 'commandcode', 'devin', 'muse', 'amp', 'kilo', 'grok',
'agy', 'copilot', 'terminal',
])
function validRegistryString(value, max = 4096) {
return typeof value === 'string' && value.length <= max && !/[\u0000-\u001f\u007f]/.test(value)
}
function validRegistryRuntime(runtime) {
return !!runtime && typeof runtime === 'object'
&& runtime.backend === 'tmux' && typeof runtime.paneId === 'string' && /^%\d+$/.test(runtime.paneId)
}
function validRegistryProcess(identity) {
return identity === null || (!!identity && typeof identity === 'object'
&& Number.isSafeInteger(identity.pid) && identity.pid > 0
&& validRegistryString(identity.executable, 1000)
&& validRegistryString(identity.startMarker, 200) && identity.startMarker.length > 0
&& (identity.startTicks === undefined || Number.isSafeInteger(identity.startTicks) && identity.startTicks >= 0))
}
function validV2Registry(rows) {
const agents = new Set()
const sessions = new Set()
const processes = new Set()
const routes = new Set()
for (const row of rows) {
if (row.schemaVersion !== 2 || row.active !== true && row.active !== false
|| !validRegistryString(row.agentId, 200) || !row.agentId
|| !validRegistryString(row.sessionId, 200)
|| !REGISTRY_ENGINES.has(row.engine)
|| !validRegistryString(row.projectDir)
|| !Array.isArray(row.runtimes) || !row.runtimes.length || !row.runtimes.every(validRegistryRuntime)
|| typeof row.primaryRuntimeKey !== 'string'
|| !validRegistryProcess(row.processIdentity)) return false
const placementKeys = row.runtimes.map(runtimePlacementKey)
if (new Set(placementKeys).size !== placementKeys.length) return false
const routeKeys = row.runtimes.map(runtimeRouteKey)
if (row.active ? !routeKeys.includes(row.primaryRuntimeKey) : row.primaryRuntimeKey !== '') return false
const tmuxProjection = row.runtimes.find((runtime) => runtime.backend === 'tmux')?.paneId
if (tmuxProjection ? row.tmuxPane !== tmuxProjection : Object.hasOwn(row, 'tmuxPane')) return false
if (agents.has(row.agentId)) return false
agents.add(row.agentId)
if (row.sessionId) {
if (sessions.has(row.sessionId)) return false
sessions.add(row.sessionId)
}
if (row.processIdentity) {
const processKey = `${row.engine}\u0000${row.processIdentity.pid}\u0000${row.processIdentity.startMarker}`
if (processes.has(processKey)) return false
processes.add(processKey)
}
for (const route of routeKeys) {
if (routes.has(route)) return false
routes.add(route)
}
}
return true
}
function validLegacyRegistryRow(row) {
if (!row || typeof row !== 'object' || Array.isArray(row) || Object.hasOwn(row, 'schemaVersion')) return false
const id = typeof row.agentId === 'string' && row.agentId ? row.agentId : row.launcherId
if (!validRegistryString(id, 200) || !id) return false
if (row.engine !== undefined && !REGISTRY_ENGINES.has(row.engine)) return false
if (row.tmuxPane !== undefined && (typeof row.tmuxPane !== 'string' || !/^%\d+$/.test(row.tmuxPane))) return false
if (row.runtimes !== undefined
&& (!Array.isArray(row.runtimes) || !row.runtimes.length || !row.runtimes.every(validRegistryRuntime))) return false
return /^%\d+$/.test(row.tmuxPane || '') || (Array.isArray(row.runtimes) && row.runtimes.length > 0)
}
function linuxOwnerBirth(pid) {
try {
// /proc stat is a kernel-sized record; accept only complete evidence for this exact live PID.
const text = readFileSync(`/proc/${pid}/stat`, 'utf8')
const start = text.indexOf('('), end = text.lastIndexOf(')')
if (text.length > 8192 || !text.endsWith('\n') || start < 1 || end <= start
|| Number(text.slice(0, start).trim()) !== pid) return null
const fields = text.slice(end + 1).trim().split(/\s+/)
if (!/^[RSDTtKWPI]$/.test(fields[0] || '') || !/^\d+$/.test(fields[1] || '')
|| !/^\d+$/.test(fields[19] || '')) return null
const parentPid = Number(fields[1]), startTicks = Number(fields[19])
if (!Number.isSafeInteger(parentPid) || parentPid > 0x7fffffff || !Number.isSafeInteger(startTicks)) return null
return { parentPid, startTicks, command: text.slice(start + 1, end) }
} catch { return null }
}
async function callerOwns(identity, current) {
const rows = await processRows()
if (!rows) return false
const parents = new Map(rows.map((row) => [row.pid, row.parentPid]))
let pid = process.ppid
const visited = new Set()
while (pid > 0 && !visited.has(pid)) {
if (pid === identity.pid) return current()
visited.add(pid)
pid = parents.get(pid) || 0
}
return false
}
async function fallbackRegister(input, engine, tmuxPane) {
const p = paths()
const transcriptPath = typeof input.transcript_path === 'string' ? input.transcript_path : ''
const rawSessionId = input.session_id || input.conversation_id
const sessionId = typeof rawSessionId === 'string' && rawSessionId
? rawSessionId
: (transcriptPath ? basename(transcriptPath).replace(/\.jsonl$/, '') : '')
if (!sessionId) return
const transcriptOptional = ['cursor', 'opencode', 'kilo', 'pi', 'hermes', 'commandcode', 'devin', 'grok', 'agy', 'copilot'].includes(engine)
if (!transcriptOptional && !transcriptPath) return
if (transcriptPath && !validTranscriptPath(engine, transcriptPath, p)) return
const observations = []
const pane = /^%\d+$/.test(tmuxPane || '') ? await paneFacts(tmuxPane, p.dataDir) : undefined
const taken = pane?.taken ?? 'no'
if (taken === 'no' || !pane.pid) return
const tmux = await rootEngineProcess(pane.pid, engine)
if (tmux.state === 'alive' && tmux.identity && await callerOwns(tmux.identity, tmux.current)) {
observations.push({ identity: tmux.identity, current: tmux.current, runtime: { backend: 'tmux', paneId: tmuxPane } })
}
if (!observations.length) return
const process = observations[0]
if (observations.some((observation) => observation.identity.pid !== process.identity.pid
|| observation.identity.startMarker !== process.identity.startMarker
|| observation.identity.startTicks !== process.identity.startTicks)) return
const observedRuntimes = observations.map((observation) => observation.runtime)
// The store that turned out to hold it — recorded below, so the daemon's mirror reads this agent's
// OWN history when it comes back up rather than the default home's.
let hermesHome = null
if (engine === 'hermes') {
const db = await hermesTopLevelSession(p.hermesDb, sessionId)
if (!db) return
hermesHome = dirname(db)
}
await withRegistryLock(p.registryFile, () => {
if (remainingBudget(600) < 50 || !process.current()) return
const loaded = rebootedSinceSnapshot(p.bootFile) ? [] : readRegistryState(p.registryFile)
// Corrupt/non-array/unknown-schema/unsafe bytes are operator-owned recovery data. Never turn them
// into an empty registry merely because the daemon is down.
if (loaded === null) return
let sessions = loaded
const routeKeys = new Set(observedRuntimes.map(runtimeRouteKey))
const onRoute = (s) => !!s && !!(Array.isArray(s.runtimes)
? s.runtimes.some((runtime) => routeKeys.has(runtimeRouteKey(runtime)))
: s.tmuxPane && routeKeys.has(runtimeRouteKey({ backend: 'tmux', paneId: s.tmuxPane })))
// A session an older build named is the daemon's only while its registry holds an agent there.
if (taken === 'if-held' && !sessions.some(onRoute)) return
const now = Date.now()
const sameRuntime = (s) => s && s.engine === engine
&& s.processIdentity?.pid === process.identity.pid
&& (s.processIdentity?.startTicks !== undefined && process.identity.startTicks !== undefined
? s.processIdentity.startTicks === process.identity.startTicks
: s.processIdentity?.startMarker === process.identity.startMarker)
let existingIndex = sessions.findIndex(sameRuntime)
// An engine typed into a terminal is that terminal's agent from then on, as the daemon adopts it
// (registry.adoptEngine): the same agent, its name and its tile, now this engine's. Taken for a
// stranger on its pane, the terminal's row was dropped for a new agent, and the tile the person had
// open was gone when the daemon came back (e2e/hookclient.e2e.ts).
if (existingIndex < 0) existingIndex = sessions.findIndex((s) => s?.engine === 'terminal' && onRoute(s))
const existing = existingIndex >= 0 ? sessions[existingIndex] : null
// A resumed session moves to this process agent; the previous process remains visible but unbound.
sessions = sessions.map((s) => s && s.sessionId === sessionId && !sameRuntime(s)
? { ...s, sessionId: '', boundAt: null, transcriptPath: null, source: null, updatedAt: now }
: s)
if (existingIndex < 0) sessions = sessions.filter((s) => !onRoute(s))
const agentId = typeof existing?.agentId === 'string' && existing.agentId ? existing.agentId : randomUUID()
const runtimes = mergeRuntimes(existing?.runtimes, observedRuntimes)
const tmuxProjection = runtimes.find((runtime) => runtime.backend === 'tmux')?.paneId || ''
// What the daemon chose for this agent at launch and cannot re-derive from the process — the
// grid launch (credential included), the Codex profile, the bypass flag, the observed grid and
// gateway — is carried forward, in the shapes `registry.register()` gives them. A hook arriving
// while the daemon is down must not be the one write that strips the row of them. `launch` is not:
// like there, a hook means the engine is up, whatever the launch was.
const carried = {
gateway: existing?.gateway === 'ori' ? 'ori' : null,
grid: existing?.grid ?? null,
...(existing && Object.hasOwn(existing, 'gridLaunch') ? { gridLaunch: existing.gridLaunch ?? null } : {}),
codexHome: typeof existing?.codexHome === 'string' && existing.codexHome ? existing.codexHome : null,
// …and the Hermes home this session's store turned out to be in — see hermesTopLevelSession.
// Fill-only, exactly as the daemon's own registry treats it.
hermesHome: hermesHome || (typeof existing?.hermesHome === 'string' && existing.hermesHome ? existing.hermesHome : null),
...(existing?.bypassPermission === true ? { bypassPermission: true } : {}),
// When an app last opened this agent (RegisteredSession.lastOpenedAt): a fact about the person,
// not the process, and the daemon's own rebuild carries it the same way.
...(Number.isSafeInteger(existing?.lastOpenedAt) && existing.lastOpenedAt > 0 ? { lastOpenedAt: existing.lastOpenedAt } : {}),
// A pane that was a terminal goes back to being one when this engine exits.
...(existing?.engine === 'terminal' || existing?.terminalHost === true ? { terminalHost: true } : {}),
}
// Everything else the daemon kept on the row goes on as it stands: the agent's name, permission mode,
// harness (DSH) and its runtime, named agent, subscription model, the web search a grid launch decided,
// the close planned for after the task (#812), whether it is a terminal, that a stop must be resumed
// and not started over, and whatever the daemon keeps there next. Named fields alone were the row
// rebuilt without them, which the daemon then loaded as its own: a hook in the seconds an update or a
// restart leaves the daemon down relaunched a harness as a plain engine, out of the mode it was made
// in and under another name, and never closed an agent its person had asked to close (#831;
// e2e/hookclient.e2e.ts). The launch is over once a hook comes, as `registry.register()` has it:
// left behind, or `ready` on a row that may only be resumed.
const { launch: _launch, ...kept } = existing ?? {}
const entry = {
...kept,
...(existing?.resumeOnly === true ? { launch: { state: 'ready' } } : {}),
schemaVersion: 2,
active: true,
...carried,
agentId,
sessionId,
engine,
boundAt: Date.now(),
transcriptPath: transcriptPath || existing?.transcriptPath || null,
projectDir: engine === 'grok'
? basename(typeof input.cwd === 'string' ? input.cwd : '') || sessionId
: transcriptPath
? basename(dirname(transcriptPath))
: basename(typeof input.cwd === 'string' ? input.cwd : '') || sessionId,
// The row's folder outranks the hook's for the session the row already holds: Claude reports
// its tracked shell directory, which follows every Bash `cd`, and a resume or restore `cd`s
// wherever this says. Same rule as `registry.register()`.
cwd: existing && existing.sessionId === sessionId && typeof existing.cwd === 'string' && existing.cwd
? existing.cwd
: typeof input.cwd === 'string' ? input.cwd : (existing?.cwd ?? null),
runtimes,
primaryRuntimeKey: existing?.primaryRuntimeKey && runtimes.some((runtime) => runtimeRouteKey(runtime) === existing.primaryRuntimeKey)
? existing.primaryRuntimeKey
: runtimeRouteKey(observedRuntimes[0]),
tmuxPane: tmuxProjection,
source: typeof input.source === 'string' ? input.source : (existing?.source ?? null),
title: typeof input.session_title === 'string' ? input.session_title : (existing?.title ?? null),
model: typeof input.model === 'string' ? input.model : (existing?.model ?? null),
cliVersion: typeof (input.cli_version || input.version) === 'string' ? (input.cli_version || input.version) : (existing?.cliVersion ?? null),
processIdentity: process.identity,
registeredAt: typeof existing?.registeredAt === 'number' ? existing.registeredAt : now,
// A bind is a change to the row, as the daemon stamps one; `updatedAt` is that stamp's name for
// a daemon from before 2026-09-27.
updatedAt: now,
touchedAt: now,
lastHookAt: now,
lastTranscriptAt: typeof existing?.lastTranscriptAt === 'number' ? existing.lastTranscriptAt : now,
}
if (!tmuxProjection) delete entry.tmuxPane
if (existingIndex >= 0) sessions[existingIndex] = entry
else sessions.push(entry)
if (!process.current()) return
// Commit rows before advancing their boot authority. If the native fence or durability
// fails, an old registry must not become current-boot evidence. A failed boot write
// after this commit leaves the old marker, so recovery cannot accept those rows as current.
if (writeRegistry(p.registryFile, sessions, process.current)) writeBoot(p.bootFile)
})
}
async function fallbackSessionEnd(sessionId, reason, engine, tmuxPane) {
// SessionEnd is not process-lifetime authority. If the daemon is down, its startup scan will reconcile
// the actual tmux process; deleting the offline record here would hide a still-running CLI.
void sessionId; void reason; void engine; void tmuxPane
}
async function main() {
let port = argPort()
const engine = argEngine()
const raw = await readStdin()
let input = {}
try {
input = JSON.parse(raw)
} catch {
return
}
const event = input.hook_event_name || input.hookEventName
const tmuxPane = process.env.TMUX_PANE
// A pane is required: tmux's, or a pty host's (Windows). Routing to another daemon and the offline registry
// fallback read tmux; from a pty host pane they find nothing and the daemon's own scan reconciles.
if (!tmuxPane && !PTY_PANE) return
// Before anything reads the data folder or posts: which daemon this pane is (routeToPaneOwner).
if (await routeToPaneOwner(tmuxPane)) port = argPort()
const mutationFields = { engine, ...terminalHookFields(tmuxPane) }
if (engine === 'cursor' && input.is_background_agent === true) return
if (engine === 'codex' && isCodexSubagent(input, paths())) return
// Devin's documented user-level hook locations include ~/.claude.json and ~/.claude/settings.json, so a
// Devin session can fire the machine's CLAUDE hook and register itself as claude (wrong engine, and a
// session id claude's path validation then rejects). Devin has its own hook installed with
// `--engine devin`; drop the claude-armed duplicate. Cheap and scoped: a real claude session has a UUID
// session id and no Devin lock file.
if (engine === 'claude' && isDevinSession(input, paths())) return
// Grok's hook payload and event records are camelCase, while every Claude-compatible engine above is
// snake_case. Its Stop hook is deliberately NOT installed: Grok persists that hook_execution before
// the final assistant chunk, so treating Stop as authoritative would close the turn too early. The
// transcript's `turn_completed` record closes normal turns; only StopFailure is needed as an error
// fallback here.
// Copilot: every event carries `sessionId` and `cwd`, and `agentStop` additionally names the
// transcript. `sessionStart` fires AFTER the first prompt (measured: userPromptSubmitted at
// …796411, sessionStart at …798963), so registration is driven by whichever arrives first —
// both are idempotent.
if (engine === 'copilot') {
const copilotEvent = argCopilotEvent()
if (!copilotEvent) return
const sessionId = input.sessionId
const p = paths()
const transcriptPath = existsPath(input.transcriptPath) ? input.transcriptPath : copilotTranscriptPath(p, sessionId)
const cwd = input.cwd
if (copilotEvent === 'sessionEnd') {
const ok = await post(port, '/api/hook/session-end', { sessionId, reason: input.reason, ...mutationFields })
if (ok === false) await fallbackSessionEnd(sessionId, input.reason, engine, tmuxPane)
return
}
if (copilotEvent === 'agentStop') {
// `stopReason` is `end_turn` on a clean finish; anything else ended the loop early.
const failed = typeof input.stopReason === 'string' && input.stopReason !== '' && input.stopReason !== 'end_turn'
await post(port, '/api/hook/turn-stop', {
sessionId, transcriptPath, status: failed ? 'error' : undefined, ...mutationFields,
})
return
}
const body = {
engine,
hookEvent: 'SessionStart',
sessionId,
transcriptPath,
cwd,
...terminalHookFields(tmuxPane),
}
const registered = await post(port, '/api/hook/session-start', body)
if (registered === false) {
await fallbackRegister({
...input, hook_event_name: 'SessionStart', session_id: sessionId, transcript_path: transcriptPath, cwd,
}, engine, tmuxPane)
}
return
}
// agy: the hook is the whole binding. Its `PreInvocation` fires before every model round-trip, so the
// FIRST one of a turn is the session announce; `Stop` fires exactly once when the execution loop ends
// and is the authoritative turn boundary (the transcript records no closing marker of its own, and a
// backgrounded step stays `status: RUNNING` forever because the file is append-only).
if (engine === 'agy') {
const agyEvent = argAgyEvent()
if (!agyEvent) return
const sessionId = input.conversationId
const p = paths()
// A sub-agent's hooks carry the parent's pane; only the pane's own conversation may register.
if (!agyIsPaneConversation(p, sessionId)) return
// Trust the payload's path when it resolves; agy's own docs show a workspace-scoped example that
// does not match what the CLI actually writes, so the derived path is the fallback that does.
const transcriptPath = existsPath(input.transcriptPath) ? input.transcriptPath : agyTranscriptPath(p, sessionId)
const cwd = Array.isArray(input.workspacePaths) ? input.workspacePaths[0] : undefined
if (agyEvent === 'Stop') {
// agy stops its execution loop as soon as the MODEL has nothing left to say — including the moment
// it has launched sub-agents and is waiting on them. Measured on a two-sub-agent run: the parent
// fired Stop twice, first `fullyIdle: false` at the "standing by for their reports" point, then
// again `fullyIdle: true` when the reports were in. Closing on the first one ended the turn and
// ran the recap while the work was still going ("chưa done đã recap").
//
// So `fullyIdle` is the turn boundary, not Stop itself. A build that omits the field is treated as
// idle, which is the pre-existing behaviour.
//
// A waiting Stop is still REPORTED, as `status: 'waiting'`, rather than swallowed: one measured run
// finished its sub-agents and never sent another Stop at all, leaving the turn open with nothing
// coming to close it. The daemon uses this to arm a pane-idle backstop.
// `terminationReason` is NO_TOOL_CALL on a clean finish; anything else ended the loop early.
const failed = typeof input.terminationReason === 'string'
&& input.terminationReason !== ''
&& input.terminationReason !== 'NO_TOOL_CALL'
&& input.terminationReason !== 'model_stop'
const status = input.fullyIdle === false ? 'waiting' : failed || input.error ? 'error' : undefined
await post(port, '/api/hook/turn-stop', { sessionId, transcriptPath, status, ...mutationFields })
return
}
const body = {
engine,
hookEvent: 'SessionStart',
sessionId,
transcriptPath,
cwd,
...terminalHookFields(tmuxPane),
model: modelName(input.modelName),
}
const registered = await post(port, '/api/hook/session-start', body)
if (registered === false) {
await fallbackRegister({
...input,
hook_event_name: 'SessionStart',
session_id: sessionId,
transcript_path: transcriptPath,
cwd,
}, engine, tmuxPane)
}
return
}
if (engine === 'grok') {
const grokEventName = grokHookEvent(event)
const sessionId = input.sessionId || input.session_id
const cwd = input.cwd || input.workspaceRoot
const transcriptPath = grokTranscriptPath(paths(), cwd, sessionId)
if (grokEventName === 'SessionEnd') {
const ok = await post(port, '/api/hook/session-end', { sessionId, reason: input.reason, ...mutationFields })
if (ok === false) await fallbackSessionEnd(sessionId, input.reason, engine, tmuxPane)
return
}
if (grokEventName === 'StopFailure') {
await post(port, '/api/hook/turn-stop', { sessionId, transcriptPath, status: 'error', ...mutationFields })
return
}
if (grokEventName !== 'SessionStart' && grokEventName !== 'UserPromptSubmit') return
const body = {
engine,
hookEvent: grokEventName,
sessionId,
...(grokEventName === 'UserPromptSubmit' && typeof input.prompt === 'string' ? { prompt: boundedPrompt(input.prompt) } : {}),
transcriptPath,
cwd,
...terminalHookFields(tmuxPane),
model: modelName(input.model),
cliVersion: input.cliVersion || input.version,
}
const registered = await post(port, '/api/hook/session-start', body)
if (registered === false) {
await fallbackRegister({
...input,
hook_event_name: grokEventName,
session_id: sessionId,
transcript_path: transcriptPath,
cwd,
cli_version: input.cliVersion || input.version,
}, engine, tmuxPane)
}
return
}
if (((engine === 'claude' || engine === 'devin') && event === 'SessionEnd') || (engine === 'cursor' && event === 'sessionEnd')) {
const ok = await post(port, '/api/hook/session-end', {
sessionId: input.session_id || input.conversation_id,
reason: input.reason,
...mutationFields,
})
if (ok === false) await fallbackSessionEnd(input.session_id || input.conversation_id, input.reason, engine, tmuxPane)
// Only once the daemon has taken the end in: a reply that did not come in time ('late') is no answer,
// and the tasks it would have settled are still the daemon's to settle.
if (engine === 'cursor' && ok === true) await clearCursorTasks(input.session_id || input.conversation_id)
return
}
// Command Code's only live signal that a turn is running. Fired per tool call, so the adapter side is
// idempotent (see onTurnStart) — this opens a turn at the FIRST tool of a turn and is a no-op after.
if (engine === 'commandcode' && (event === 'PreToolUse' || event === 'preToolUse')) {
await post(port, '/api/hook/turn-start', {
sessionId: input.session_id || input.conversation_id,
...mutationFields,
})
return
}
if (engine === 'cursor' && event === 'preToolUse') {
if (input.tool_name === 'Task' && typeof input.tool_use_id === 'string') {
await persistCursorTask(input)
await post(port, '/api/hook/tool-start', {
sessionId: input.session_id || input.conversation_id,
toolUseId: input.tool_use_id,
toolName: input.tool_name,
input: input.tool_input,
...mutationFields,
})
}
return
}
if (engine === 'cursor' && event === 'stop') {
const sessionId = input.session_id || input.conversation_id
const body = {
engine,
hookEvent: event,
sessionId,
status: input.status,
transcriptPath: input.transcript_path,
cwd: Array.isArray(input.workspace_roots) ? input.workspace_roots[0] : input.cwd,
...terminalHookFields(tmuxPane),
model: modelName(input.model),
cliVersion: input.cursor_version || input.version,
}
const registered = await post(port, '/api/hook/session-start', body)
if (registered === false) await fallbackRegister(input, engine, tmuxPane)
const stopped = await post(port, '/api/hook/turn-stop', {
sessionId,
status: input.status,
transcriptPath: input.transcript_path,
...mutationFields,
})
if (stopped === true) await clearCursorTasks(sessionId)
return
}
// Stop / StopFailure (claude): the authoritative turn-close signal, independent of JSONL parsing.
// Stop fires when Claude finishes responding (incl. max_tokens / refusal); StopFailure fires when the
// turn ends on an API error (Stop does NOT fire then). Both → tell the adapter to close the turn. We
// write nothing to stdout so Claude stops normally (only exit 2 / decision:block would continue it).
// Command Code exposes no UserPromptSubmit, so Stop is its only turn-close signal (same shape as claude's).
if ((engine === 'claude' || engine === 'commandcode' || engine === 'devin') && (event === 'Stop' || event === 'StopFailure')) {
// Command Code's whole hook set is PreToolUse/PostToolUse/Stop/SessionStart — no UserPromptSubmit, so
// Stop is also its ONLY catch hook. Without re-registering here, a session that left the registry for
// any reason (a reaper miss, a daemon restart, a fresh data dir) can never come back while the CLI
// keeps running: the web/device just show nothing until the user quits and relaunches commandcode.
// Registration is idempotent, and this is also where a session first announced without a transcript
// (Command Code fires SessionStart before creating the file) finally gets its real path.
if (engine === 'commandcode') {
const registered = await post(port, '/api/hook/session-start', {
engine,
hookEvent: event,
sessionId: input.session_id,
status: event === 'StopFailure' ? 'error' : undefined,
transcriptPath: existsPath(input.transcript_path) ? input.transcript_path : undefined,
cwd: input.cwd,
...terminalHookFields(tmuxPane),
title: input.session_title,
model: modelName(input.model),
cliVersion: input.cli_version || input.version,
})
if (registered === false) await fallbackRegister(input, engine, tmuxPane)
}
await post(port, '/api/hook/turn-stop', {
sessionId: input.session_id,
transcriptPath: input.transcript_path,
status: event === 'StopFailure' ? 'error' : undefined,
...mutationFields,
})
return
}
// SessionStart or UserPromptSubmit (the catch hook) → register the session. Registration is
// idempotent, so re-registering on every prompt is cheap. The adapter verifies the process.
// Command Code fires SessionStart BEFORE it writes the transcript, and the daemon validates the path
// (realpath) — sending one that isn't on disk yet gets the whole registration rejected. Announce
// without it; the session is registered again with the real path on the first Stop. Scoped to
// commandcode: every other engine REQUIRES a transcriptPath, so dropping it would break them.
// Devin keeps history in sessions.db and writes no transcript file (unless the user passes --export),
// so it registers with none — like opencode/pi/hermes.
const transcriptPath = engine === 'devin'
? undefined
: engine === 'commandcode' && !existsPath(input.transcript_path)
? undefined
: input.transcript_path
const body = {
engine,
hookEvent: event,
sessionId: input.session_id || input.conversation_id,
...(event === 'UserPromptSubmit' && (engine === 'claude' || engine === 'codex') && typeof input.prompt === 'string'
? { prompt: boundedPrompt(input.prompt) } : {}),
transcriptPath,
// Devin's payload carries no cwd; the hook process inherits the session's working directory.
cwd: Array.isArray(input.workspace_roots) ? input.workspace_roots[0] : (input.cwd || (engine === 'devin' ? process.cwd() : undefined)),
source: input.source,
...terminalHookFields(tmuxPane),
title: input.session_title,
model: modelName(input.model),
cliVersion: input.cli_version || input.cursor_version || input.version,
}
let ok = await post(port, '/api/hook/session-start', body)
let held = ok === 'held'
// A live core's bounded admission queue owns the existing candidates. Retry this
// delivery within the hook budget, never reconstruct registry state behind it.
for (let attempt = 0; engine === 'hermes' && ok === 'held' && attempt < 3 && remainingBudget() > 750; attempt++) {
await new Promise(resolve => setTimeout(resolve, 250))
ok = await post(port, '/api/hook/session-start', body)
held ||= ok === 'held'
}
if (held && ok !== true) process.stderr.write('[harness] Hermes admission is held; this delivery could not be confirmed. The current conversation is unchanged.\n')
if (ok === false && !held) await fallbackRegister(input, engine, tmuxPane)
}
main()
.catch(() => {})
.finally(() => {
// Cursor and Hermes parse the hook's stdout as JSON; `{}` is the explicit no-op (for Hermes it also
// guarantees a pre_llm_call hook never injects context). Claude/Codex want no stdout at all.
const e = argEngine()
// agy REQUIRES a JSON object on stdout. `{}` is the safe no-op for both events it fires: on Stop,
// only `{"decision":"continue"}` would block the stop. It is also why PreToolUse is never installed
// — there `decision` is required, and `{}` reads as a denial (measured: every tool call of the turn
// came back "Tool call denied by pre-tool hook").
// Copilot parses stdout as JSON too; `{}` is the documented no-op for every event installed here.
if (e === 'cursor' || e === 'hermes' || e === 'agy' || e === 'copilot') process.stdout.write('{}\n', () => process.exit(0))
else process.exit(0)
})