Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

99.6 KB
Raw Blame
#!/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)
  })