Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.
TypeScript adhdagent-orchestrationai-agentscanvasclaude-codecodexcoding-agentsdeveloper-toolselectrongeminilinuxmacosmultiplexeropencodeparallel-agentsterminalterminal-emulatorterminal-multiplexertmuxworkspace-manager
import { REPORT_OUTCOME_CONTROL_REFUSAL } from '../../shared/station-outcome'
import { sessionContextWindow } from '../model-window'
import { labelHeldForRevision } from './permission-decision'
import { createCursorApprovalWatch, type CursorApprovalWatch } from './cursor-approval'
import { createServer, type IncomingMessage, type Server, type ServerResponse } from 'http'
import { randomUUID, timingSafeEqual } from 'crypto'
import { readFileSync, mkdirSync, chmodSync, unlinkSync } from 'fs'
import { assertHookEndpointAvailable, clearStaleHookSocket, HookSocketOwnedError } from './hook-socket-owner'
import { homedir } from 'os'
import path from 'path'
import { platform } from '../platform'
import { writeFileAtomic } from '../fs-atomic'
import { parseEndpointEnv } from './hook-endpoint-parse'
import { hookSockPath } from './hook-sock-path'
import { browserRequestRefusal } from './hook-browser-guard'
import { canControlCanvas, type AgentId } from '../../shared/agents/config'
import { normalizeFor, type NormalizedAgentEvent } from '../../shared/agents/normalize'
import {
createGrokPermissionGate,
defaultGrokPermissionGateDeps,
type GrokPermissionGate,
type GrokPermissionGateDeps
} from './grok-permission-gate'
import {
createCodexPermissionGate,
defaultCodexPermissionGateDeps,
type CodexPermissionGate,
type CodexPermissionGateDeps
} from './codex-permission-gate'
import { classifyClaudeConfigDir, configDirFromTranscriptPath } from '../claude-accounts-core'
import { claudeAccountsSnapshot } from '../claude-config-dir'
import type { CodexIdentityEvent, ObservedClaudeAccount } from '../../shared/types'
import type { NodeTokenVerdict } from './node-auth-token'
import { nodeTokenDir } from './node-token-files'
import { isForeignKidToken, isSafeNodeId, verifyNodeToken } from './node-auth-token'
import { isSafeCodexAgentId, isSafeThreadId, type CodexThreadAgent } from '../codex-identity-proxy'
import { isSafeAccountId } from '../../shared/codex-account'
import {
controlPolicy,
CONTEXT_LINK_POLICY_VERB,
IDENTITY_REFUSED_NOTE,
IDENTITY_RESTART_NOTE,
IDENTITY_UNMINTABLE_NOTE,
IDENTITY_UNMINTABLE_WARN_NOTE,
STRICT_CONTROL_REFUSAL,
STRICT_CONTROL_VERBS,
type IdentityDecision
} from './node-identity-policy'
import { posixQuote } from '../../shared/ssh'
import { dryRunRequested } from '../../shared/control-verbs'
import {
ControlRequestLedger,
REQUEST_ID_RETRYABLE,
REQUEST_ID_UNVERIFIED_NOTE,
controlCallFingerprint,
requestIdGate,
requestIdOutcomeMessage,
requestIdReplayLine,
requestIdRetryHint,
type LedgerClaim,
CONTROL_REQUEST_FACT,
type PersistedLedgerRow
} from '../control-request-ledger'
import { DurableFactFile } from '../durable-state'
import { createPaneOriginGate, parseClaudeHookOrigin, type PaneOriginGate } from './claude-pane-origin'
// v2 advertises NODETERM_NODE_TOKEN_DIR so clients read their per-node capability from a file
// rather than receiving it in argv. Nothing consumes the posted version server-side, so the bump
// is free; it is a marker a client can key on.
export const NODETERM_HOOK_PROTOCOL_VERSION = '2'
const SLOWLORIS_MS = 2000
// Once the body is fully read the slowloris guard has done its job — it exists for the RECEIVE
// phase (a client that dribbles bytes to pin a socket), not for the handler. But it is replaced
// with a HIGHER ceiling, never removed: a confirmation-gated control verb legitimately parks
// while the renderer waits for the user's answer, yet nothing may park forever. The desktop shell
// bounds a control request at 120s (`createControlForwarder`, src/main/control-forward.ts) — a
// bound that lives OUTSIDE core, so a future core-side handler with no bound of its own would
// inherit an unbounded socket if this were `setTimeout(0)`. 130s sits comfortably above that, so
// in the desktop the handler's own timeout always wins and this only ever fires as a backstop.
// Exported so a caller that parks on this socket can assert its own deadline sits under it by
// RUNNING the comparison rather than by copying the number into a comment (the delivery receipt,
// `agent-message.ts`, does exactly that).
export const CONTROL_CEILING_MS = 130_000
// The context-link handler has no timeout of its own, and its remote leg reads over an SSH
// ControlMaster that can wedge (ConnectTimeout only covers the connect). Race it so the agent
// gets the same prose failure it would get from any other read error, instead of a session that
// blocks indefinitely — pre-fix the 2s destroy at least unblocked the agent's curl.
const CONTEXT_LINK_READ_MS = 30_000
const CONTEXT_LINK_TIMEOUT_TEXT = 'Could not read linked context.'
// Default seconds the managed permission hook holds for a phone/canvas answer before falling
// through to Claude's interactive prompt (must stay under Claude's own hook timeout). Injected
// into a claude session's env as NODETERM_PERM_WAIT_SECS when hook-reply approvals are enabled.
// See docs/hook-reply-approvals.md.
export const PERM_WAIT_SECS_DEFAULT = 45
function readBody(req: IncomingMessage): Promise<string> {
return new Promise((resolve) => {
// Collect Buffers and decode ONCE at the end: `data += chunk` coerced every chunk through
// a string concat (quadratic churn on big bodies) and could split a multibyte UTF-8
// sequence at a chunk boundary, corrupting the decoded text.
const chunks: Buffer[] = []
let bytes = 0
req.on('data', (c: Buffer) => {
chunks.push(c)
bytes += c.length
if (bytes > 5_000_000) req.destroy() // cap absurd bodies
})
req.on('end', () => resolve(Buffer.concat(chunks).toString('utf-8')))
req.on('error', () => resolve(''))
})
}
/**
* Resolve to `fallback` if `p` has not settled within `ms`. The timer is always cleared, so a
* losing race never holds the process open. There is nothing to cancel in a read already in
* flight, so a rejection must be swallowed either way — otherwise it surfaces as an unhandled
* rejection once the timeout has already answered. A rejection that loses no race therefore also
* yields `fallback`, which for the context-link route means the caller reads the same prose
* failure it gets from any other read error instead of a bare 204.
*/
function withTimeout<T>(p: Promise<T>, ms: number, fallback: T): Promise<T> {
let timer: NodeJS.Timeout
return Promise.race([
p.catch(() => fallback),
new Promise<T>((resolve) => {
timer = setTimeout(() => resolve(fallback), ms)
})
]).finally(() => clearTimeout(timer))
}
const CP1252 = new TextDecoder('windows-1252')
/**
* `decodeURIComponent`, except it never throws. On Windows the shims run under Git Bash but post
* through a NATIVE curl, which reads its argv in the ANSI code page: `--data-urlencode "arg.prompt=é"`
* goes out as `%E9`, not `%C3%A9`. `decodeURIComponent` rejects that with a URIError, which escaped
* the request handler and came back as an empty 204 — the shim exited 1 with no message, and every
* `open-claude --prompt` holding one accented letter failed silently. Bytes that are not UTF-8 are
* read as windows-1252, the code page that produced them; characters outside it were already lost
* to `?` by the argv conversion, before the request existed.
*/
function decodeFormComponent(s: string): string {
try {
return decodeURIComponent(s)
} catch {
const latin1 = s.replace(/%([0-9a-fA-F]{2})/g, (_, hex: string) => String.fromCharCode(parseInt(hex, 16)))
return CP1252.decode(Buffer.from(latin1, 'latin1'))
}
}
// Parses application/x-www-form-urlencoded bodies (what the managed script posts). Field names come
// from the request, so they go into a Map and out through `Object.fromEntries`, which defines own
// properties: a `__proto__` field is an ordinary key, never a prototype write.
function parseForm(body: string): Record<string, string> {
const out = new Map<string, string>()
for (const pair of body.split('&')) {
const i = pair.indexOf('=')
if (i < 0) continue
out.set(decodeFormComponent(pair.slice(0, i)), decodeFormComponent(pair.slice(i + 1).replace(/\+/g, ' ')))
}
return Object.fromEntries(out)
}
/**
* Read a /control/ request body in either dialect. The POSIX-sh shim — since it retired the Node
* CLI, the only client there is — sends form-urlencoded: `nodeId` plus one `arg.<name>` field per
* flag, because `curl --data-urlencode` is the only escaping sh can be trusted with (hand-built
* JSON would break on the first quote in a `--prompt` or `--html` value). The JSON dialect is
* kept because the route is a stable local API that a session predating an app upgrade may still
* be holding a copy of. Exported for tests.
*/
export function parseControlBody(
raw: string,
contentType: string
): { nodeId: string; args: Record<string, string>; requestId?: string } {
if (contentType.includes('application/x-www-form-urlencoded')) {
const form = parseForm(raw)
const args: Record<string, string> = Object.fromEntries(
Object.entries(form)
.filter(([k]) => k.startsWith('arg.') && k.length > 4)
.map(([k, v]) => [k.slice(4), v])
)
// `requestId` is the id the shim generates once per RUN (not the caller's `--request-id`,
// which arrives as `arg.request-id`): what lets the shim's own endpoint-walk re-post be
// recognised as the same call. See control-request-ledger.ts.
return { nodeId: form.nodeId ?? '', args, ...(form.requestId ? { requestId: form.requestId } : {}) }
}
try {
const parsed = JSON.parse(raw) as { nodeId?: string; args?: Record<string, string>; requestId?: unknown }
return {
nodeId: parsed.nodeId ?? '',
args: parsed.args ?? {},
...(typeof parsed.requestId === 'string' && parsed.requestId ? { requestId: parsed.requestId } : {})
}
} catch {
return { nodeId: '', args: {} }
}
}
/**
* `X-Nodeterm-Hook-Client` → the posting script's revision, or `undefined`.
*
* Strict on purpose: only an unsigned decimal integer counts. Anything else — a version string
* someone thought would be friendlier, a duplicated header (node hands those over as an array,
* which is not a string and so lands here as undefined), an empty value — is "no stamp", which is
* the same answer a pre-#195 script gives. Guessing a number out of "v3-beta" would be inventing
* evidence for a gate.
*/
function parseClientRevision(raw: string | string[] | undefined): number | undefined {
if (typeof raw !== 'string' || !/^\d+$/.test(raw.trim())) return undefined
const n = Number(raw.trim())
return Number.isSafeInteger(n) ? n : undefined
}
/**
* The `account` LABEL for a claude hook payload: `transcript_path` →
* `<configDir>/projects/…` → which account that dir is. Undefined for every other agent and for a
* payload with no usable `transcript_path` — "we did not observe an account" and "the system
* account" are different facts and must stay distinguishable (CONTRIBUTING: a failed read is never
* evidence of absence), so an absent field is the honest answer, not a synthesized system row.
*
* NEVER throws: this sits on the 204 path, and a classification failure — a settings store mid-
* write, a platform seam not yet initialized in an odd boot order — must cost the label, not the
* event. NO filesystem access happens here: the dir is classified as a string, so a forged
* POST naming `~/.ssh/projects/x.jsonl` gets a `known: false` label and nothing is opened.
*/
function observedClaudeAccount(
agentId: string,
payload: Record<string, unknown>
): ObservedClaudeAccount | undefined {
if (agentId !== 'claude') return undefined
const tp = payload.transcript_path
if (typeof tp !== 'string' || !tp) return undefined
try {
const dir = configDirFromTranscriptPath(tp)
if (!dir) return undefined
return classifyClaudeConfigDir(dir, {
homeDir: homedir(),
userDataDir: platform().userDataDir,
accounts: claudeAccountsSnapshot()
})
} catch {
return undefined
}
}
/**
* What the hook server knows about the POST an event arrived on, beyond the event itself.
*
* `verified` = the caller presented a per-node token THIS instance minted for THAT node id. It is
* a LABEL, nothing more: `false` is the overwhelmingly common, entirely legitimate case (any client
* that predates the token, the phone, a cross-instance failover), so nothing may gate behaviour on
* it. A later task makes the label useful; until then, false must cost a caller nothing.
*/
export interface HookEventMeta {
/** undefined: old/unverified client; null: observed env has no valid override. */
contextWindow?: number | null
verified: boolean
}
/**
* Control verbs that admit ONLY a `verified` caller — the agent-messaging verbs, plus `sticky`.
*
* `sticky` is here because its whole accountability story is the byline: it is deliberately not
* confirm-gated, and the note's "↻ <agent> · when" stamp is what replaces the dialog — a stamp
* forged by any bearer-holding process naming someone else's node id would be worse than no stamp.
* Like the messaging verbs it is NEW, so fail-closed from day one strands nobody.
*
* A route that admits only `verified` is untouched by the foreign-kid escape: an invented kid is
* FOREIGN, therefore `legacy` (invariant 3, required or cross-instance failover dies), therefore
* never `verified` (node-identity-policy.ts, `verifyNodeToken`'s foreign-kid rule). The escape
* defeats the latch and the window. It does not defeat this.
*
* Deliberately NOT routed through controlPolicy: `settings.hookIdentityStrict: false` releases the
* latch and the dated cutoff, and it must never release these. There is no upgrade population to
* protect — the routes are new — which is the one place in the whole control surface where
* fail-closed from day one costs nobody anything.
*
* `open-project` (issue #338) is here for the same class of reason as `sticky`: the main-side
* grant ledger (src/core/project-grants.ts) mints per-caller targeting rights off a successful
* `open-project`, and a grant recorded for an unverifiable caller would authorize whoever can
* name that caller's node id. NEW verb, so fail-closed from day one strands nobody.
*
* `settings` (@shared/settings-verb) joins for the same reason again: its `--set` raises a dialog
* that names the requesting node, and the user's click grants what the requester asked for — a
* requester nobody can verify is a requester the dialog would be lying about. NEW verb.
*
* Consulted in the `/control/` route BEFORE `identityGate`'s decision is, so no future change to
* the policy table can widen it; `messaging-verified-only.test.ts` drives the route on both sides
* of every hatch and is the test that fails if either half of this comment stops being true.
*/
export const requiresVerified: ReadonlySet<string> = new Set([
'send',
'reply',
'notify',
'sticky',
'open-project',
'settings',
// Publishes text from this machine to a repository. `legacy` means "we cannot judge this
// caller", and an unjudgeable caller must never be the one that files.
'report-issue',
// Starts a process the user is not watching (#925).
'run',
// A station's own task outcome (@shared/station-outcome): a reported success RELEASES every
// dependent armed with `--after-success`, so the claim must come from the node it is about — and
// only a verified caller is provably that node.
'report-outcome',
// The board's GitHub lane (core/github/control-read.ts). The project read is resolved from the
// CALLER's node, so a caller nobody can verify could name any node and read another project's
// lane — bound sessions and dispatch state included. NEW verbs: fail-closed strands nobody.
'issues',
'prs'
])
/**
* The refusal for a messaging verb: one sentence, no diagnosis, no hint about tokens or restarts —
* the same posture as STRICT_CONTROL_REFUSAL, for the same reason. Advice here is advice to an
* attacker and a lie to nobody else.
*/
export const MESSAGING_CONTROL_REFUSAL = 'Agent messaging refused.'
/** Same one-sentence posture for the verified-only sticky verb — named for what was refused,
* because "agent messaging refused" answering a note write is a diagnosis-delaying lie. */
export const STICKY_CONTROL_REFUSAL = 'Sticky write refused.'
/** Same posture again for `open-project` (issue #338): one sentence naming what was refused, no
* diagnosis, no token or restart advice — a designed refusal, not a rollout accident. */
export const OPEN_PROJECT_CONTROL_REFUSAL = 'Project open refused.'
/** Same posture for `settings`: a caller that cannot prove which node it is must not read this
* machine's settings, and must never be the one a settings dialog names as the requester. */
export const SETTINGS_CONTROL_REFUSAL = 'Settings access refused.'
/** One sentence, names what was refused, no diagnosis — house style for every refusal here. */
export const REPORT_ISSUE_CONTROL_REFUSAL = 'Issue reporting refused.'
/** Same posture for `run` (#925): it starts a queued session the user is not watching, and the
* refusal says only that the run was refused. */
export const RUN_CONTROL_REFUSAL = 'Run refused.'
/** Same posture for `report-outcome` (defined beside its grammar, @shared/station-outcome). */
export { REPORT_OUTCOME_CONTROL_REFUSAL }
/** The flat refusal for an unverified `issues` / `prs` read (core/github/control-read.ts). */
export const GITHUB_READ_CONTROL_REFUSAL = 'GitHub lane read refused.'
/**
* Issue #1088: appended to a verified-only refusal when THIS INSTANCE has no node-auth secret, so no
* session on the machine can ever be `verified`. The flat refusals deliberately carry no per-node
* diagnosis (advice to a prober), but this is not one: it is a fact about the instance that no
* caller can change, and leaving it out made the refusal permanent AND causeless — the reporter
* had only a `console.warn` in a log they could not see. It names no token and no restart, because
* neither helps; the cause is fixed on the machine, then NodeTerm is restarted.
*/
export function identityUnavailableNote(reason: string | null): string {
const why = reason ? ` (${reason.replace(/\s+/g, ' ').trim().slice(0, 200)})` : ''
return (
`Node identity is unavailable in this NodeTerm instance: it could not load its node-identity key at startup${why}, ` +
'so no session on this machine can be verified and restarting a node will not help. ' +
'Fix the cause and restart NodeTerm; details are in its log under [node-identity].'
)
}
/** The verified-only refusal, worded for the verb that was refused. */
export function verifiedRefusalFor(verb: string): string {
if (verb === 'open-terminal') return 'Terminal command refused.'
if (verb === 'settings') return SETTINGS_CONTROL_REFUSAL
if (verb === 'report-issue') return REPORT_ISSUE_CONTROL_REFUSAL
if (verb === 'sticky') return STICKY_CONTROL_REFUSAL
if (verb === 'open-project') return OPEN_PROJECT_CONTROL_REFUSAL
if (verb === 'run') return RUN_CONTROL_REFUSAL
if (verb === 'report-outcome') return REPORT_OUTCOME_CONTROL_REFUSAL
if (verb === 'issues' || verb === 'prs') return GITHUB_READ_CONTROL_REFUSAL
return MESSAGING_CONTROL_REFUSAL
}
export class HookServer {
private server: Server | null = null
private starting: Promise<void> | null = null
/**
* The unix-domain twin of the loopback TCP listener (issue #367). Same HTTP handler, same
* bearer + per-node token auth — the whole identity machinery is transport-agnostic (nothing
* in the handler reads `remoteAddress`), so the socket is never an auth bypass. Two reasons it
* exists: it lets a sandboxed macOS Codex regain hook connectivity via codex's
* `network.allow_unix_sockets` allowlist (the TCP loopback can never be allowlisted), and it
* gives local traffic a filesystem-permissioned path (0700 dir, 0600 socket) that a
* defense-in-depth follow-up to #195 can eventually make the ONLY door. It does not close #195
* on its own: the TCP listener STAYS (existing tmux panes hold pre-socket env, and the Linux
* codex sandbox blocks unix sockets anyway), so any local user can still reach the (bearer-gated)
* TCP port until that port is retired. Best-effort: if the socket cannot bind,
* nothing advertises it and everything runs on TCP exactly as before.
*/
private unixServer: Server | null = null
private sockPath = ''
private port = 0
private token = ''
private listener: ((e: NormalizedAgentEvent) => void) | null = null
private rawListener:
| ((
agentId: string,
nodeId: string,
payload: Record<string, unknown>,
meta: HookEventMeta
) => void)
| null = null
/**
* Nodes that have presented a token this instance minted for THAT node id. In memory only and
* deliberately so: it is a record of what happened on this process's socket, not a durable claim,
* and a restart must re-earn it. Bounded by the number of node ids that ever post here.
*/
private provenNodes = new Set<string>()
/** Node ids the materialiser refuses to mint for (see `markNodeIdentityUnmintable`). */
private unmintableNodes = new Set<string>()
private controlHandler:
| ((cmd: {
verb: string
nodeId: string
args: Record<string, string>
// The caller's IDENTITY verdict for THIS request, decided at the gate above and passed on
// rather than re-derived in main. `true` only when the caller presented a per-node token
// this instance minted for this node id. The browser ownership ledger (PR 4 Task 4.3)
// claims a node ONLY when this is true — a `legacy`/warned caller opens a browser but owns
// nothing, so it can drive nothing. `browser-ownership-source.test.ts` guards the source.
verified: boolean
// Present only when the request CLAIMED a row in the request ledger. A handler that gives
// up before its effect is known (desktop main's 120s wait on the renderer) answers with
// `indeterminate: true` and may hand the real answer back here when it arrives: the
// ledger then replays it to a retry instead of refusing it as unknown.
onLateAnswer?: (reply: { ok: boolean; message?: string; result?: unknown; error?: string }) => void
}) => Promise<{
ok: boolean
message?: string
result?: unknown
error?: string
// The handler could not tell whether its effect happened (see control-request-ledger.ts).
indeterminate?: boolean
// Set by the route, never a handler: the id an indeterminate call is filed under.
requestId?: string
}>)
| null = null
/**
* Retried control calls (`--request-id`, or the shim's per-run id). Durable: `start()` loads it
* from `<userData>/orchestration-state/control-requests.json` and every change is mirrored there,
* so a retry after an app restart is answered from the row instead of opening a second node (the
* header of control-request-ledger.ts states what a restart does to each row). `stop()` flushes.
*/
private requestLedger = this.newRequestLedger()
private requestLedgerFile: DurableFactFile<PersistedLedgerRow> | null = null
// Context-link reads. Same shape as the control handler, but it answers with TEXT (a rendered
// transcript / summary / terminal capture) rather than acting on the canvas.
private contextLinkHandler:
| ((req: { verb: string; nodeId: string; args: Record<string, string> }) => Promise<string>)
| null = null
/**
* The shared-identity spine's handlers (see core/codex-identity-proxy.ts). Both are injected by
* the shell, and BOTH routes below additionally require a per-node capability — see
* `nodeTokenVerified`.
*/
private codexThreadStartHandler:
| ((req: {
nodeId: string
cwd: string
hookEndpoint: string
accountId?: string
agent?: CodexThreadAgent
}) => Promise<string>)
| null = null
private codexThreadBindHandler:
| ((req: {
nodeId: string
threadId: string
hookEndpoint: string
accountId?: string
agent?: CodexThreadAgent
}) => Promise<void>)
| null = null
private codexIdentityListener: ((e: CodexIdentityEvent) => void) | null = null
private previousEndpointToken = ''
getPreviousEndpointToken(): string { return this.previousEndpointToken }
private endpointPath = ''
private publishedEndpoint = ''
private nodeAuthSecret: Buffer | null = null
/** Why the shell could not arm a secret, when it tried and failed (see `setNodeIdentityUnavailable`). */
private nodeIdentityUnavailableReason: string | null = null
/**
* `settings.hookIdentityStrict`, read LIVE (a getter, not a snapshot) so flipping it in Settings
* takes effect on the next request rather than the next launch. `undefined` — the default, and
* what an un-wired shell gets — means "follow NODE_IDENTITY_STRICT_AFTER".
*/
private identityStrict: () => boolean | undefined = () => undefined
/** The clock the cutoff is read against. A seam, so a suite can stand on either side of a DATE
* without touching the machine's own. */
private identityNow: () => Date = () => new Date()
endpointFilePath(): string {
if (!this.endpointPath) this.endpointPath = path.join(platform().userDataDir, 'hook-endpoint.env')
return this.endpointPath
}
getPort(): number {
return this.port
}
/** The unix listener's socket path, or '' when it is not live (bind failed, win32). */
getSockPath(): string {
return this.sockPath
}
getToken(): string {
return this.token
}
getVersion(): string {
return NODETERM_HOOK_PROTOCOL_VERSION
}
setListener(cb: (e: NormalizedAgentEvent) => void): void {
this.listener = cb
}
/** Cursor's approval prompt has no hook, so a pending tool call earns up to three pane reads
* (CURSOR_APPROVAL_READS_MS, core/agents/cursor-approval.ts). Both shells pass their pty manager's `captureSession`;
* unset = cursor never shows NEEDS YOU, as before. The synthetic `blocked` rides `listener`. */
private cursorWatch: CursorApprovalWatch | null = null
setPaneReader(readPane: (nodeId: string) => Promise<string | null>): void {
this.cursorWatch = createCursorApprovalWatch({ readPane, emit: (e) => this.listener?.(e) })
}
/** A node was closed or recycled: its pending pane reads must not resurrect it as `blocked`. */
releaseCursorNode(nodeId: string): void {
this.cursorWatch?.release(nodeId)
}
private grokPermissionGate: GrokPermissionGate | null = null
private grokGateDeps: GrokPermissionGateDeps | undefined
/** Test seam: the grok permission gate's file/timer deps. */
setGrokPermissionGateDeps(deps: GrokPermissionGateDeps): void {
this.grokPermissionGate?.dispose()
this.grokPermissionGate = null
this.grokGateDeps = deps
}
private grokGate(): GrokPermissionGate {
if (!this.grokPermissionGate) {
this.grokPermissionGate = createGrokPermissionGate(
(e) => this.listener?.(e),
this.grokGateDeps ?? defaultGrokPermissionGateDeps()
)
}
return this.grokPermissionGate
}
private codexPermissionGate: CodexPermissionGate | null = null
private codexGateDeps: CodexPermissionGateDeps | undefined
/** Test seam: the codex permission gate's file/timer deps. */
setCodexPermissionGateDeps(deps: CodexPermissionGateDeps): void {
this.codexPermissionGate?.dispose()
this.codexPermissionGate = null
this.codexGateDeps = deps
}
private codexGate(): CodexPermissionGate {
if (!this.codexPermissionGate) {
this.codexPermissionGate = createCodexPermissionGate(
(e) => this.listener?.(e),
this.codexGateDeps ?? defaultCodexPermissionGateDeps()
)
}
return this.codexPermissionGate
}
/**
* Which claude may speak for a node (issues #1112, #1153 — claude-pane-origin.ts). Created
* eagerly: the "not the foreground of any terminal" half needs no shell at all, so a shell that
* never wires a resolver still drops a detached `claude -p`. The pane-tty half needs
* `setPaneTtyResolver`, which BOTH shells call (hook-verified-parity.test.ts pins it).
*/
private readonly paneOrigin: PaneOriginGate = createPaneOriginGate()
/** The node's pane tty, read by each shell from its own PtyManager (`paneOwner(...).tty`). */
setPaneTtyResolver(fn: ((nodeId: string) => Promise<string | null>) | undefined): void {
this.paneOrigin.setPaneTtyResolver(fn)
}
/** Drop the cached pane tty of a node whose session ended or was recycled (new pane, new tty). */
forgetPaneOrigin(nodeId: string): void {
this.paneOrigin.forgetNode(nodeId)
}
// Raw payload listener: receives the parsed (un-normalized) hook JSON. Drives the
// contextTail/subagentTail features, which need transcript_path (not in NormalizedAgentEvent).
// `meta` carries what the transport knows about the caller (see HookEventMeta).
setRawListener(
cb: (
agentId: string,
nodeId: string,
payload: Record<string, unknown>,
meta: HookEventMeta
) => void
): void {
this.rawListener = cb
}
/** Has this node ever posted with a token this instance minted for it? Read by the routing task
* that consumes the label; never a gate on /hook/* itself. */
isNodeProven(nodeId: string): boolean {
return this.provenNodes.has(nodeId)
}
/**
* Drop a node from the latch — called whenever its token file is SWEPT
* (`node-token-service.ts`), local or remote.
*
* The latch says "this node can authenticate, so a caller that cannot is not it". Sweeping the
* token takes that ability away, and a latch left standing over a node that no longer has a token
* to read is a hard 403 on every canvas-control call for the life of the session, with no window
* and no advice that works. The two ways in are both real: a case-folding collision (a hostile or
* merely careless `project.json` adds `term-1` beside a `Term-1` that had already proven itself,
* and the whole colliding set is refused tokens by design), and a node deleted and re-created
* with the same id.
*
* Un-proving is cheap to get wrong in the other direction and it does not matter: the node
* re-proves on its very next hook event carrying a valid token, which is the same ceremony a
* restart performs. Fail-open is the designed state of this whole series.
*/
forgetProvenNode(nodeId: string): void {
this.provenNodes.delete(nodeId)
}
/**
* Node ids the materialiser has REFUSED to mint for, and will keep refusing until a file on disk
* changes — today, the members of a case-folding collision group (`node-token-service.ts`).
*
* It exists only to pick the right refusal SENTENCE. `IDENTITY_REFUSED_NOTE` tells the user to
* reopen the node to pick up an identity; for these nodes there is nothing to pick up, so that
* advice sends them round a loop while the only other signal is a `console.warn` in a log they
* are not reading. The other unmintable population — an id outside `isSafeNodeId`, which reaches
* the canvas because `fileToProject` does not validate ids out of `project.json` — needs no
* registration: this server can see it in the id itself.
*
* Marked/cleared rather than recomputed because the collision is a property of the whole CANVAS,
* which the hook server has no view of.
*/
markNodeIdentityUnmintable(nodeId: string): void {
this.unmintableNodes.add(nodeId)
}
/** The twin left the canvas (or the id was fixed): this node can be minted for again. */
clearNodeIdentityUnmintable(nodeId: string): void {
this.unmintableNodes.delete(nodeId)
}
/**
* Can this node id NEVER hold a token, however often it is restarted?
*
* Two sources, and neither is recomputed here: the collision set the materialiser registers, and
* the id itself — `isSafeNodeId` is precisely the predicate `nodeAuthToken` refuses on, so an id
* it rejects mints '' forever.
*/
private identityUnmintable(nodeId: string): boolean {
return !isSafeNodeId(nodeId) || this.unmintableNodes.has(nodeId)
}
/**
* Which refusal sentence this node should hear. `IDENTITY_UNMINTABLE_NOTE` names the real cause
* and deliberately does NOT advise a restart; see it for why that distinction is worth a Set.
*/
private identityRefusalNote(nodeId: string): string {
return this.identityUnmintable(nodeId) ? IDENTITY_UNMINTABLE_NOTE : IDENTITY_REFUSED_NOTE
}
/**
* The same choice for the WARNING WINDOW, and the reason the unmintable sentence is reachable at
* all before the cutoff.
*
* An unmintable node is `allow-with-warning` for the whole window — `controlPolicy` cannot see
* that it is unmintable, and would not change its verdict if it could, because running is the
* right answer there. So the window was the ONE period in which these nodes were guaranteed to be
* told to "Close and reopen this node to pick one up", which is the loop
* `IDENTITY_UNMINTABLE_NOTE` was written to end. The note was unreachable exactly while it was
* needed.
*/
private identityWarningNote(nodeId: string): string {
return this.identityUnmintable(nodeId) ? IDENTITY_UNMINTABLE_WARN_NOTE : IDENTITY_RESTART_NOTE
}
setControlHandler(cb: NonNullable<HookServer['controlHandler']>): void {
this.controlHandler = cb
}
setContextLinkHandler(cb: NonNullable<HookServer['contextLinkHandler']>): void {
this.contextLinkHandler = cb
}
setCodexThreadStartHandler(cb: NonNullable<HookServer['codexThreadStartHandler']>): void {
this.codexThreadStartHandler = cb
}
setCodexThreadBindHandler(cb: NonNullable<HookServer['codexThreadBindHandler']>): void {
this.codexThreadBindHandler = cb
}
/** Where a node's identity mode goes on its way to the UI (both shells forward it). */
setCodexIdentityListener(cb: (e: CodexIdentityEvent) => void): void {
this.codexIdentityListener = cb
}
/**
* The shell injects a restart-stable node-auth secret before any identity-scoped PTY is created —
* sealed via safeStorage on the desktop, raw 0600 bytes on the Server Edition (see
* core/agents/node-auth-secret.ts). Called on BOTH shells at boot. Rejects a secret under 32
* bytes so a truncated/garbage load can never arm a weak identity.
*/
setNodeAuthSecret(secret: Uint8Array): void {
if (secret.byteLength < 32) throw new Error('Invalid NodeTerm node-auth secret')
this.nodeAuthSecret = Buffer.from(secret)
this.nodeIdentityUnavailableReason = null
}
/**
* The shell's boot-time arming FAILED (issue #1088). Recorded so a verified-only refusal can say
* the cause is the instance, not the node — see `identityUnavailableNote`. Both shells call it
* from the catch around their arming; a later successful `setNodeAuthSecret` supersedes it.
*/
setNodeIdentityUnavailable(reason: unknown): void {
this.nodeIdentityUnavailableReason =
reason instanceof Error ? reason.message : typeof reason === 'string' ? reason : 'unknown error'
}
/** True once a valid secret is set; false before, and after a failed load (nothing was set). The
* later routing tasks gate every identity-scoped decision on this. */
identityAvailable(): boolean {
return !!this.nodeAuthSecret
}
/** The raw secret for the routing tasks that must derive/verify per-node capabilities themselves,
* or null when identity is unavailable (legacy mode). Callers must handle null — never throw. */
nodeAuthSecretOrNull(): Buffer | null {
return this.nodeAuthSecret
}
/** Test seam only: this server is a module singleton, so its secret otherwise leaks across tests. */
clearNodeAuthSecretForTests(): void {
this.nodeAuthSecret = null
this.nodeIdentityUnavailableReason = null
}
/**
* The escape hatch, injected by the shell from `settings.hookIdentityStrict`.
*
* `undefined` follows the dated constant. `true` opts in early. `false` keeps the warning window
* open past the cutoff AND releases the trust-on-first-proof latch — so a user whose upgrade goes
* wrong gets their canvas back without downgrading the app. Never releases `forged`.
*/
setIdentityStrictOverride(read: () => boolean | undefined): void {
this.identityStrict = read
}
/** Test seam only: see `identityNow`. */
setIdentityClockForTests(now: () => Date): void {
this.identityNow = now
}
/** Shell boot must continue even when optional hooks cannot safely take ownership. */
async startForApp(): Promise<string | null> {
try {
await this.start()
return null
} catch {
this.stop()
// Do not include raw errors: an invalid HTTP header may contain the bearer.
return `Agent hooks are disabled because their endpoint is occupied, malformed, or unavailable. ` +
`The application can still run, but agent status and canvas commands may be unavailable. ` +
`Close any other nodeterm instance using this data directory. If none is running, inspect ` +
`${this.endpointFilePath()} and its advertised listener; back up and remove a stale file, ` +
`then restart nodeterm. No other owner's endpoint was replaced.`
}
}
async start(): Promise<void> {
if (this.starting) return this.starting
if (this.server) return
this.starting = this.startOwnedEndpoint()
try {
await this.starting
} finally {
this.starting = null
}
}
private newRequestLedger(): ControlRequestLedger {
return new ControlRequestLedger({
inFlightStaleMs: CONTROL_CEILING_MS,
onChange: () => this.requestLedgerFile?.save(this.requestLedger.exportRows())
})
}
/** Load the durable request ledger for this data dir (start), replacing the in-memory one. */
private attachRequestLedgerFile(userDataDir: string): void {
this.requestLedgerFile?.dispose()
const file = new DurableFactFile(CONTROL_REQUEST_FACT, { userDataDir })
const ledger = this.newRequestLedger()
ledger.restore(file.load())
this.requestLedger = ledger
this.requestLedgerFile = file
}
private async startOwnedEndpoint(): Promise<void> {
await assertHookEndpointAvailable(this.endpointFilePath())
this.attachRequestLedgerFile(platform().userDataDir)
this.previousEndpointToken = ''
try {
const previous = parseEndpointEnv(readFileSync(this.endpointFilePath(), 'utf8'))
// Only our conventional local endpoint supplies upgrade proof, never a tunnel record.
if (previous.NODETERM_HOOK_SOCK === hookSockPath(platform().userDataDir)) {
this.previousEndpointToken = previous.NODETERM_HOOK_TOKEN ?? ''
}
} catch { /* a first run has no prior bearer */ }
this.token = randomUUID()
// ONE handler, shared verbatim by the TCP and the unix-socket listeners: every gate (bearer,
// per-node verdict, verified-only verbs) runs identically on both transports.
const handler = async (req: IncomingMessage, res: ServerResponse): Promise<void> => {
// Hooks fail open: any error path still ends 204 so a broken hook never blocks the agent.
try {
if (req.method !== 'POST') {
res.writeHead(404)
res.end()
return
}
// Belt-and-braces BEFORE the bearer: a browser page (DNS rebinding included) is refused
// on the Origin / Host it cannot help sending, and learns nothing about the bearer — not
// even the 403-vs-421 distinction below. The bearer stays the real gate; every client we
// ship passes this unchanged (measured list in hook-browser-guard.ts).
const browserRefusal = browserRequestRefusal(req.headers)
if (browserRefusal) {
res.writeHead(403, { 'Content-Type': 'text/plain; charset=utf-8' })
res.end(`${browserRefusal}\n`)
return
}
if (!this.tokenMatches(req.headers['x-nodeterm-hook-token'])) {
if (!req.headers['x-nodeterm-hook-token']) {
res.writeHead(403)
res.end()
return
}
res.writeHead(421, { 'Content-Type': 'text/plain; charset=utf-8' })
res.end(
'hook-endpoint-wrong-owner: This endpoint does not own the presented bearer. ' +
'Retry after endpoint discovery; this is not an unsupported capability.\n'
)
return
}
req.setTimeout(SLOWLORIS_MS, () => req.destroy())
const reqUrl = new URL(req.url ?? '/', 'http://127.0.0.1')
// THE TUNNEL PROBE. `RemoteHooks.verifyTunnel` curls this through the reverse socket and
// requires exactly 204 before it will write the remote endpoint file or install a single
// hook script. It proves ONE thing — the socket reaches this server — and it must answer on
// the bearer alone, with no node identity of any kind, permanently: the caller is the
// desktop itself, `verify` is not a node id, and a 403 here would silently cost that host
// its whole remote hook + skill install.
//
// Until this route existed, `/hook/verify` 204'd only because the probe sends no `payload`
// field and fell out of the generic branch — a coincidence that the identity label on
// `/hook/*` would have turned into a 403 for any probe carrying a token. `/hook/verify`
// therefore stays answering forever: a host connected by an older desktop still has that
// path baked into the script on its disk.
if (reqUrl.pathname === '/verify' || reqUrl.pathname === '/hook/verify') {
await readBody(req) // drain, so the probe's body is never left unread on the socket
res.writeHead(204)
res.end()
return
}
if (reqUrl.pathname.startsWith('/codex-thread/')) {
await this.handleCodexThread(reqUrl.pathname, req, res)
return
}
if (reqUrl.pathname.startsWith('/control/')) {
const verb = decodeURIComponent(reqUrl.pathname.replace(/^\/control\//, ''))
const {
nodeId,
args: rawArgs,
requestId: cliRequestId
} = parseControlBody(await readBody(req), String(req.headers['content-type'] ?? ''))
// Body fully received: hand the socket from the receive-phase guard to the much larger
// handler ceiling. A destructive control verb parks here for as long as the user takes
// to answer the confirmation dialog, and the 2s guard used to destroy the socket mid-
// dialog — the caller saw "endpoint unreachable" while the dialog was still up, and a
// late confirm still delivered, so the agent was told nothing happened when it had.
req.setTimeout(CONTROL_CEILING_MS, () => req.destroy())
const wantsText = String(req.headers.accept ?? '').includes('text/plain')
// The request id is not an argument of any verb: take it out here, once, so no handler
// (and no parser that refuses flags it does not know) ever meets it. A bad EXPLICIT id is
// refused below, after identity — the order every other refusal on this route keeps.
const idGate = requestIdGate(verb, rawArgs, cliRequestId)
const args = idGate.kind === 'pass' ? idGate.args : rawArgs
// IDENTITY, and it runs BEFORE the handler: the promise of a refusal is that nothing
// happened, and a check after the handler is a check that happened too late.
const { verdict, decision } = this.identityGate(
nodeId,
verb,
req.headers['x-nodeterm-node-token']
)
if (verdict === 'forged') {
res.writeHead(403)
res.end()
return
}
// VERIFIED-ONLY VERBS, decided on the VERDICT and never on the decision: the policy's
// `decision` is what the escape hatch and the warning window can reach, and neither may
// reach these. See `requiresVerified` for the whole argument.
// Issue #653: command execution requires proof even when rollout policy allows
// legacy callers. Presence (including empty --cmd and dry runs) decides this;
// plain terminals keep their existing policy. Both shells and transports use this gate.
const commandOpen = verb === 'open-terminal' && args.cmd !== undefined
if ((requiresVerified.has(verb) || commandOpen) && verdict !== 'verified') {
const refusal = this.identityAvailable()
? verifiedRefusalFor(verb)
: `${verifiedRefusalFor(verb)} ${identityUnavailableNote(this.nodeIdentityUnavailableReason)}`
if (wantsText) {
res.writeHead(403, { 'content-type': 'text/plain; charset=utf-8' })
res.end(`${refusal}\n`)
} else {
res.writeHead(403, { 'content-type': 'application/json' })
res.end(JSON.stringify({ ok: false, error: refusal }))
}
return
}
if (decision === 'refuse') {
// The route's own refusal shape, so the sh shim (which prints any non-200 body to
// stderr and exits 1) shows the sentence and nothing else.
// Which sentence: a node in a case-folding collision group, or with an id
// `isSafeNodeId` refuses, can NEVER pick up an identity, and telling it to restart is
// an instruction to loop forever. See `identityRefusalNote`.
//
// A STRICT verb answers with its own flat sentence instead: those refusals are not a
// rollout accident to be talked through, they are the designed state for anything but
// a verified caller, and naming tokens or restarts there is advice to whoever is
// probing. See STRICT_CONTROL_VERBS.
const note = STRICT_CONTROL_VERBS.has(verb)
? STRICT_CONTROL_REFUSAL
: this.identityRefusalNote(nodeId)
if (wantsText) {
res.writeHead(403, { 'content-type': 'text/plain; charset=utf-8' })
res.end(`${note}\n`)
} else {
res.writeHead(403, { 'content-type': 'application/json' })
res.end(JSON.stringify({ ok: false, error: note }))
}
return
}
if (idGate.kind === 'refuse') {
const refusal = requestIdOutcomeMessage(idGate.outcome, { verb })
this.writeControlReply(res, wantsText, 400, { ok: false, error: idGate.outcome, message: refusal })
return
}
// RETRIED CALLS. Claimed HERE, before the handler, because from this instant the truthful
// answer to "did it happen?" is "it may have" — and here is the one place both shells'
// handlers pass. Keyed by the VERIFIED caller only: an unverified caller's id would share
// a bucket with anyone claiming its node id, so it gets no dedupe at all (and is told, when
// it asked for one). A dry run creates nothing, so it neither claims nor answers from a row.
let claim: LedgerClaim | undefined
let idNote = ''
if (idGate.requestId && !dryRunRequested(args)) {
if (verdict === 'verified') {
const decided = this.requestLedger.begin(
nodeId,
idGate.requestId,
controlCallFingerprint(verb, args)
)
if (decided.kind === 'replay') {
const stored = decided.reply
const lead = requestIdReplayLine(idGate.requestId, Date.now() - decided.firstRunAt)
if (wantsText) {
const text = stored.ok
? stored.message ?? JSON.stringify(stored.result ?? {})
: stored.message ?? stored.error ?? 'control request failed'
res.writeHead(stored.ok ? 200 : 400, { 'content-type': 'text/plain; charset=utf-8' })
res.end(`${lead}\n${text}\n`)
} else {
res.writeHead(stored.ok ? 200 : 400, { 'content-type': 'application/json' })
res.end(JSON.stringify({ ...stored, replayed: true, requestId: idGate.requestId }))
}
return
}
if (decided.kind === 'refuse') {
const refusal = requestIdOutcomeMessage(decided.outcome, {
verb,
requestId: idGate.requestId,
ageMs: Date.now() - decided.firstRunAt
})
this.writeControlReply(res, wantsText, 409, {
ok: false,
error: decided.outcome,
message: refusal,
retryable: REQUEST_ID_RETRYABLE[decided.outcome]
})
return
}
claim = decided.claim
} else if (idGate.explicit) {
idNote = REQUEST_ID_UNVERIFIED_NOTE
}
}
const held = claim
let result: Awaited<ReturnType<NonNullable<HookServer['controlHandler']>>>
try {
result = this.controlHandler
? await this.controlHandler({
verb,
nodeId,
args,
verified: verdict === 'verified',
...(held ? { onLateAnswer: (late) => held.settleLate(late) } : {})
})
: { ok: false, error: 'control unavailable' }
} catch (e) {
// Nobody can say what a handler that threw got done: the id stays unknown, and its retry
// is refused rather than run a second time.
held?.settleUnknown()
throw e
}
held?.settle(result)
// A call that may still complete names the id it is filed under, and how to pass it back:
// for the shim's per-run id this is the only place the caller ever sees it.
if (held && idGate.requestId && result.indeterminate) {
const hint = requestIdRetryHint(idGate.requestId)
result = {
...result,
message: `${result.message ?? result.error ?? 'control request failed'}\n${hint}`,
requestId: idGate.requestId
}
}
// Which note, not whether: an unmintable node warned with the restart line is sent round
// the same loop the refusal path already knows better than to send it round.
const note = [decision === 'allow-with-warning' ? this.identityWarningNote(nodeId) : '', idNote]
.filter(Boolean)
.join('\n')
// The POSIX-sh shim asks for text/plain: it has no JSON parser, so the server does the
// rendering the Node CLI used to do client-side. Everything else keeps the JSON shape.
if (wantsText) {
// A FAILURE may now carry both: `error` is the machine-readable name a JSON client
// keys on, `message` the sentence a human (or a language model) reads. The text
// dialect has no fields, so it prefers the sentence and falls back to the name — which
// is what every existing handler still sends, so this is inert for all of them.
const text = result.ok
? result.message ?? JSON.stringify(result.result ?? {})
: result.message ?? result.error ?? 'control request failed'
res.writeHead(result.ok ? 200 : 400, { 'content-type': 'text/plain; charset=utf-8' })
res.end(note ? `${note}\n${text}\n` : `${text}\n`)
return
}
res.writeHead(result.ok ? 200 : 400, { 'content-type': 'application/json' })
// A field, not a prefix: the JSON dialect is a STRUCTURED reply a legacy client parses,
// and folding the note into `message` would either hide `result` (text rendering falls
// back to it only when `message` is absent) or corrupt a field somebody reads.
res.end(JSON.stringify(note ? { ...result, warning: note } : result))
return
}
if (reqUrl.pathname.startsWith('/context-link/')) {
const verb = decodeURIComponent(reqUrl.pathname.replace(/^\/context-link\//, ''))
const { nodeId, args } = parseControlBody(
await readBody(req),
String(req.headers['content-type'] ?? '')
)
// Same hand-off as /control/: the receive phase is over, so raise the guard to the
// handler ceiling rather than dropping it. The effective bound here is the race below;
// the socket ceiling is only the backstop behind it.
req.setTimeout(CONTROL_CEILING_MS, () => req.destroy())
// Same latch as /control/, and every verb here is a READ, so it is presented to the
// policy as the tolerant verb: an unproven legacy caller keeps its transcript.
const gate = this.identityGate(
nodeId,
CONTEXT_LINK_POLICY_VERB,
req.headers['x-nodeterm-node-token']
)
if (gate.verdict === 'forged') {
res.writeHead(403)
res.end()
return
}
if (gate.decision === 'refuse') {
// PROSE, not a 403. The agent explicitly asked for a read; the shim turns any non-200
// into "Could not read linked context (nodeterm unreachable)", which would be a lie and
// tells it nothing it can act on. A sentence it can act on is the better failure.
res.writeHead(200, { 'content-type': 'text/plain; charset=utf-8' })
res.end(`${this.identityRefusalNote(nodeId)}\n`)
return
}
// Always text: the caller is the sh shim, and the payload IS prose (a rendered
// transcript). The handler owns the authorization — see context-link.ts.
const text = this.contextLinkHandler
? await withTimeout(
this.contextLinkHandler({ verb, nodeId, args }),
CONTEXT_LINK_READ_MS,
CONTEXT_LINK_TIMEOUT_TEXT
)
: 'Context link is unavailable in this session.'
res.writeHead(200, { 'content-type': 'text/plain; charset=utf-8' })
res.end(`${text}\n`)
return
}
const agentId = decodeURIComponent(reqUrl.pathname.replace(/^\/hook\//, ''))
const form = parseForm(await readBody(req))
const nodeId = form.nodeId ?? ''
// Identity is a LABEL here, not a gate. The three-way verdict maps to:
// forged — our own kid with a mac that is not this node's ⇒ 403. Nothing legitimate can
// produce it (only a holder of a token for ANOTHER node, or a mutation of one),
// so it is the single case this route refuses.
// legacy — no token, or another instance's kid. THE COMMON CASE, and it must keep
// behaving exactly as it did before this label existed: 204, listeners fired.
// Every client that predates the token, the phone, and the documented
// cross-instance failover land here. Do not gate this on identityAvailable(),
// on the agent, or on anything else — the fail-open is the contract.
// verified — the caller holds this node's token; remember the node and pass the flag on.
const verdict = verifyNodeToken(
this.nodeAuthSecretOrNull(),
nodeId,
req.headers['x-nodeterm-node-token']
)
if (verdict === 'forged') {
res.writeHead(403)
res.end()
return
}
const verified = verdict === 'verified'
if (verified) this.provenNodes.add(nodeId)
// WHICH CLIENT posted. A LABEL like `verified`, and for the same reason a second one was
// needed: an old managed script and a current one whose token file is missing send exactly
// the same bytes otherwise (the `version` form field is sourced from the endpoint file, so
// it reports OUR protocol version, not the client's). Absent or unparseable stays
// `undefined` — never 0 — because "no stamp" and "revision zero" are different claims and
// only the first one is true of a pre-#195 script.
const clientRevision = parseClientRevision(req.headers['x-nodeterm-hook-client'])
if (agentId && nodeId && form.payload) {
let payload: Record<string, unknown> = {}
try {
payload = JSON.parse(form.payload) as Record<string, unknown>
} catch {
payload = {}
}
// Deterministic-approval ticket: the managed permission hook adds `nodeterm_pending_id`
// as a separate form field (it can't edit the agent's JSON payload in POSIX sh). Merge it
// into the payload object so both the raw listener and the normalizers see it as if it
// rode inside the hook JSON. See docs/hook-reply-approvals.md.
if (form.nodeterm_pending_id) payload.nodeterm_pending_id = form.nodeterm_pending_id
// Same treatment for the "answered" signal the wait branch fires on a valid allow/deny
// answer (a separate form field it can't fold into the agent's JSON in POSIX sh). Merged
// so the normalizer sees it and maps it to a synthetic working transition. See
// docs/hook-reply-approvals.md.
if (form.nodeterm_answered) payload.nodeterm_answered = form.nodeterm_answered
// The EVENT NAME, for an agent whose hook payload does not carry one. Antigravity (`agy`)
// sends five events with no name in any of them, and two of them (Pre/PostInvocation) have
// identical keys, so the managed command exports the name and the script sends it as this
// field. Assigned AFTER JSON.parse, so the form wins over a value planted in the agent's
// JSON. Deliberately NOT `hook_event_name`: that is a real payload field for claude, codex,
// gemini and copilot, and a name of our own cannot collide with any of them. The value is
// only ever compared against a closed set (normalizeAntigravity), never interpolated.
// Antigravity only: no other normalizer reads it, and for antigravity the form is the ONE
// source — an empty field DELETES a value planted in the JSON rather than letting it stand.
if (agentId === 'antigravity') {
if (form.nodeterm_hook_event) payload.nodeterm_hook_event = form.nodeterm_hook_event
else delete payload.nodeterm_hook_event
}
// A claude event from a process that merely INHERITED this node's id — a detached
// `claude -p`, Claude's own daemon hosting a fork — is not the node's, and must reach
// NEITHER listener: the raw one rebinds the node's session, meter and context-link
// transcript, the normalized one the mirror's session id, title and badge (#1112,
// #1153). Decided per node in arrival order; see claude-pane-origin.ts for the rule and
// the measurement behind it. Every claude event goes through the gate, with or without
// an origin, so an event waiting for a pane read is never overtaken by the next one.
if (agentId === 'claude' && !(await this.paneOrigin.admit(nodeId, parseClaudeHookOrigin(form)))) {
res.writeHead(204)
res.end()
return
}
// Raw listener first: it drives the transcript-tailing features (which need
// transcript_path). Inside the try so a throwing raw listener still ends 204.
this.rawListener?.(agentId, nodeId, payload, {
verified,
...(verified && agentId === 'claude' && form.nodeterm_context_window !== undefined
? { contextWindow: sessionContextWindow(form.nodeterm_context_window) }
: {})
})
// WHICH CLAUDE ACCOUNT this session is on. A third LABEL alongside
// `verified`/`clientRevision`, computed HERE so ONE implementation serves both shells —
// the "both raw listeners change together" rule is sidestepped rather than violated,
// because neither raw listener changes. Claude only: `transcript_path` means a config
// dir for claude alone (codex rollouts and gemini chats live in unrelated trees, and
// those agents have their own identity spine).
const account = observedClaudeAccount(agentId, payload)
// A held request keeps its `held` ticket only when the posting script can honor a
// structured answer (core/agents/permission-decision.ts, MIN_STRUCTURED_ANSWER_REVISION).
const raw = normalizeFor(agentId, { nodeId, agentId, payload })
const normalized = raw ? labelHeldForRevision(raw, clientRevision) : raw
const labelled = normalized
? { ...normalized, verified, clientRevision, ...(account ? { account } : {}) }
: null
// Grok's permission prompt is confirmed against grok's own event log before it is
// published, and cleared from it once answered (core/agents/grok-permission-gate.ts).
// Every grok event goes through the gate so their order is kept per node.
if (agentId === 'grok') this.grokGate().handle(nodeId, payload, labelled)
// Codex's PermissionRequest is checked against the session rollout: under codex's own
// auto-reviewer nobody is asked, so it must not read as NEEDS YOU (issue #1171,
// core/agents/codex-permission-gate.ts). Every codex event goes through the gate so their
// order is kept per node.
else if (agentId === 'codex') this.codexGate().handle(nodeId, payload, labelled)
else if (labelled && this.listener) this.listener(labelled)
if (agentId === 'cursor') this.cursorWatch?.observe(nodeId, payload, verified)
}
res.writeHead(204)
res.end()
} catch {
res.writeHead(204)
res.end()
}
}
this.server = createServer(handler)
await new Promise<void>((resolve, reject) => {
const onErr = (e: Error): void => {
this.server?.off('listening', onOk)
// A failed listen must not WEDGE the singleton (issue #445): `this.server` was assigned
// before the bind, so leaving it set makes every later start() a silent early-return with
// port 0 — while a previous run's endpoint file keeps advertising a dead port to every
// tmux session on the machine. Reset to the clean never-started state so start() can be
// retried without restarting the app. Only an advertisement this run actually published
// may be removed; a file found on disk can belong to a different live instance.
this.server?.close()
this.server = null
this.port = 0
this.token = ''
this.removeEndpointFile()
reject(e)
}
const onOk = (): void => {
this.server?.off('error', onErr)
this.server?.on('error', (e) => console.error('[agent-hooks] server error', e))
const addr = this.server!.address()
if (addr && typeof addr === 'object') this.port = addr.port
resolve()
}
this.server!.once('error', onErr)
this.server!.listen(0, '127.0.0.1', onOk)
})
// Second leg, then ONE endpoint write that advertises whatever actually came up. A failed
// unavailable transport can fall back to TCP, but a different owner must refuse the boot.
try {
await this.startUnixListener(handler)
} catch (e) {
this.server?.close()
this.server = null
this.port = 0
this.token = ''
throw e // Never publish over the listener whose ownership check refused this boot.
}
await this.writeEndpointFile()
}
/** Bind the Unix twin. Transport unavailability can degrade to TCP; ownership conflicts throw
* so a second instance cannot replace the first instance's endpoint advertisement. */
private async startUnixListener(
handler: (req: IncomingMessage, res: ServerResponse) => Promise<void>
): Promise<void> {
// Node's AF_UNIX support on Windows is not the discipline this path was built around, and no
// generated sh client runs there anyway.
if (process.platform === 'win32') return
const p = hookSockPath(platform().userDataDir)
try {
const dir = path.dirname(p)
mkdirSync(dir, { recursive: true, mode: 0o700 })
// mkdir's mode is ignored when the dir already exists — enforce it, because the DIRECTORY
// mode is what actually keeps other local users off the socket (the file chmod below only
// lands after listen, and the socket is world-connectable for that instant otherwise).
chmodSync(dir, 0o700)
// A filesystem path is not proof of ownership: another live instance may hold it.
await clearStaleHookSocket(p)
const srv = createServer(handler)
await new Promise<void>((resolve, reject) => {
const onErr = (e: Error): void => {
srv.off('listening', onOk)
reject(e)
}
const onOk = (): void => {
srv.off('error', onErr)
resolve()
}
srv.once('error', onErr)
srv.once('listening', onOk)
srv.listen(p)
})
chmodSync(p, 0o600)
srv.on('error', (e) => console.error('[agent-hooks] unix listener error', e))
this.unixServer = srv
this.sockPath = p
} catch (e) {
if (e instanceof HookSocketOwnedError || (e as NodeJS.ErrnoException).code === 'EADDRINUSE') throw e
console.warn('[agent-hooks] unix hook socket unavailable, staying TCP-only', e)
this.unixServer = null
this.sockPath = ''
}
}
// Constant-time bearer-token check (avoids a timing side channel on the compare).
private tokenMatches(provided: string | string[] | undefined): boolean {
if (typeof provided !== 'string' || !this.token) return false
const a = Buffer.from(provided)
const b = Buffer.from(this.token)
return a.length === b.length && timingSafeEqual(a, b)
}
/**
* The identity routes' gate: ONE derivation, the same `verifyNodeToken` /hook/* is labelled by.
*
* These routes are STRICT — only `verified` proceeds. `legacy` (no token, an empty header,
* another instance's kid, no secret at all) is refused here, deliberately and unlike /hook/*:
* they were strict from the day they existed, so there is no upgrade population to protect. A
* session that predates the per-node capability has no launcher that calls `/codex-thread/*` at
* all; failing it open would buy nothing and hand back the authorization hole the capability
* exists to close (any session holding the shared bearer binding its own codex thread to a
* SIBLING node — reparenting that node's status and, through the hook prelude which re-exports
* the recorded node id and endpoint, aiming that node's hook traffic).
*/
private nodeTokenVerified(nodeId: string, provided: string | string[] | undefined): boolean {
return verifyNodeToken(this.nodeAuthSecretOrNull(), nodeId, provided) === 'verified'
}
/**
* One control reply in either dialect, for the route's own answers (the request-id outcomes):
* the sentence for the POSIX-sh shim, which prints one line and has no JSON parser; the whole
* object for a structured client, which keys on `error`.
*/
private writeControlReply(
res: ServerResponse,
wantsText: boolean,
status: number,
body: { ok: false; error: string; message: string; retryable?: boolean }
): void {
if (wantsText) {
res.writeHead(status, { 'content-type': 'text/plain; charset=utf-8' })
res.end(`${body.message}\n`)
return
}
res.writeHead(status, { 'content-type': 'application/json' })
res.end(JSON.stringify(body))
}
/**
* The identity gate for `/control/*` and `/context-link/*` — one call site for the verdict, the
* latch and the policy, so the two routes cannot drift into two different rules.
*
* Both halves of the answer come back: the routes agree on the POLICY but not on the SHAPE of a
* refusal (a 403 on control, prose on context-link), and `forged` is a bare 403 on both — it is
* an attack signal, and handing it "restart this node" would be advice to an attacker and a lie
* to nobody else.
*/
private identityGate(
nodeId: string,
verb: string,
presented: string | string[] | undefined
): { verdict: NodeTokenVerdict; decision: IdentityDecision } {
const secret = this.nodeAuthSecretOrNull()
// NO SECRET ⇒ NO GATE, ever. This instance cannot mint a token, so nothing can be `verified`,
// so a policy that warns or refuses `legacy` here would warn or refuse EVERY caller on the
// machine — and the advice it would give ("restart this node to pick up an identity") is
// advice that cannot work, because there is no identity to pick up. This is the state a
// desktop lands in when safeStorage is unavailable and the state a Server Edition lands in
// when the key file cannot be created; both must keep working exactly as they did.
if (!secret) return { verdict: 'legacy', decision: 'allow' }
const verdict = verifyNodeToken(secret, nodeId, presented)
// Proof is earned on ANY route that can present a valid token, not just /hook/*: a session's
// first act may well be a canvas-control call.
if (verdict === 'verified') this.provenNodes.add(nodeId)
return {
verdict,
decision: controlPolicy({
verdict,
// A FOREIGN kid is the documented cross-instance failover. It never proved this node (only
// `verified` adds to the set) and it must never be caught by the latch either, or the
// first day a second instance exists is the day failover stops working.
proven: this.provenNodes.has(nodeId) && !isForeignKidToken(secret, presented),
verb,
now: this.identityNow(),
override: this.identityStrict()
})
}
}
/**
* `/codex-thread/{start,bind,fallback}`.
*
* start/bind are the identity spine and require the per-node capability on top of the shared
* bearer. `fallback` deliberately does NOT: it is the launcher telling us it gave up and is
* running plain codex, it grants nothing, and requiring a token there would silence the report
* in exactly the case (no token) it exists to surface.
*/
private async handleCodexThread(
pathname: string,
req: IncomingMessage,
res: ServerResponse
): Promise<void> {
const verb = pathname.replace(/^\/codex-thread\//, '')
const form = parseForm(await readBody(req))
// SAME HAND-OFF as /control/ and /context-link/, and for the same reason — this route needs it
// MOST. The receive phase is over, so the 2s slowloris guard has done its job; leaving it armed
// destroys the socket while the HANDLER is still working. `/codex-thread/start` mints a thread
// through a five-step conversation with the app-server (initialize, start, a turn, an
// interrupt, a fork, a delete) against a server that is typically COLD — the first codex node
// after boot is the common case, not the edge one. At 2s that fails every time, and it fails in
// the worst possible way: curl gives up, the launcher falls back to plain codex, and main goes
// on to create the thread and write a record for it — an orphan thread plus an orphan record
// per attempt. The client budget is deliberately set ABOVE the server's own (see
// CODEX_THREAD_START_TIMEOUT_MS / the launcher's --max-time) so the server is always the one
// that gives up first and can clean up after itself.
req.setTimeout(CONTROL_CEILING_MS, () => req.destroy())
const nodeId = form.nodeId ?? ''
// `isSafeNodeId`, not a local regex: the same predicate the token derivation and the token
// FILE path use, so an id one of them would refuse can never reach the other two.
if (!isSafeNodeId(nodeId)) {
res.writeHead(400)
res.end()
return
}
if (verb === 'fallback') {
// This is the ONE route that may be called without the per-node capability, because the
// commonest thing it reports is "there was no capability to present" — requiring one would
// silence it in exactly the case it exists for. So only `forged` is refused here, the same
// rule /hook/* follows and the one the per-route table documents.
//
// It used to refuse anything that was not `verified`, which caught the CROSS-INSTANCE
// FAILOVER: another instance's token is `legacy`, and invariant 3 says a foreign kid is
// never refused anywhere. That check also bought nothing it was meant to buy — a hostile
// sibling wanting to flag another node as fallen back simply omits the header, which was
// always accepted — so it only ever silenced a legitimate report.
if (verifyNodeToken(this.nodeAuthSecretOrNull(), nodeId, req.headers['x-nodeterm-node-token']) === 'forged') {
res.writeHead(403)
res.end()
return
}
// A reason is free text from a generated script we wrote; bound it and let the UI show it.
const reason = (form.reason ?? '').slice(0, 64).replace(/[^A-Za-z0-9._-]/g, '') || 'unknown'
this.codexIdentityListener?.({ nodeId, mode: 'plain', reason })
res.writeHead(204)
res.end()
return
}
if (verb !== 'start' && verb !== 'bind') {
res.writeHead(404)
res.end()
return
}
if (!this.nodeTokenVerified(nodeId, req.headers['x-nodeterm-node-token'])) {
res.writeHead(403)
res.end()
return
}
// The account scope for this thread's ownership record (S6). Absent ⇒ system account. A
// non-empty id that is not a safe account id is refused BEFORE it reaches the record store,
// where it would become a directory component (Supply-chain guard, Constraint 7). Both routes
// share the same normalisation so a managed thread is never mis-filed under `system`.
const rawAccountId = form.accountId ?? ''
if (rawAccountId !== '' && !isSafeAccountId(rawAccountId)) {
res.writeHead(400)
res.end()
return
}
const accountId = rawAccountId || undefined
// THE PANE'S OWN AGENT LABEL, echoed back so the ownership record can carry it.
//
// Why the client is asked at all, when `hookEndpoint` below is deliberately the server's own
// answer: the agent id is a fact about a tmux session that OUTLIVES this process, and the
// launcher POSTing here runs inside that pane with the `NODETERM_AGENT_ID` `buildPtyEnv` put
// there. Nothing on the server side is as durable — an in-memory map from `buildPtyEnv` is
// empty for every node whose pane predates this app run, which is the norm after a restart and
// permanent for a node in a project the user has not opened.
//
// It is not a capability claim. A caller only reaches this line by presenting a token this
// instance minted FOR THIS NODE (`nodeTokenVerified` above, strict), so it is the node; the
// record it shapes is re-exported into that same node's own tool shells and nowhere else; and
// the env var it sets is not what authorizes anything (see `identityGate` — the per-node token
// is). Lying about it buys the liar the label they already had.
//
// THE GRANT IS NOT ECHOED. It is derived here by `canControlCanvas` — the same predicate, in
// the same process, that `buildPtyEnv` used to gate the pane — so there is exactly ONE decider
// and a forged agent id cannot manufacture a grant the table would refuse. An unparseable or
// absent id writes a PRE-AGENT record, which reads back with the documented implied values:
// the behaviour that shipped before this field existed.
const rawAgentId = form.agentId ?? ''
const agent: CodexThreadAgent | undefined = isSafeCodexAgentId(rawAgentId)
? { agentId: rawAgentId, canvasControl: canControlCanvas(rawAgentId) }
: undefined
if (verb === 'start') {
const cwd = form.cwd ?? ''
if (!path.isAbsolute(cwd)) {
res.writeHead(400)
res.end()
return
}
try {
if (!this.codexThreadStartHandler) throw new Error('start handler unavailable')
const threadId = await this.codexThreadStartHandler({
nodeId,
cwd,
hookEndpoint: this.endpointFilePath(),
accountId,
agent
})
// Same predicate the record store gates on, so a thread id the store would refuse can
// never be handed back to a launcher that will then `resume` it.
if (!isSafeThreadId(threadId)) throw new Error('invalid thread id')
this.codexIdentityListener?.({ nodeId, mode: 'shared' })
res.writeHead(200, { 'content-type': 'text/plain; charset=utf-8' })
res.end(`${threadId}\n`)
} catch {
res.writeHead(503)
res.end()
}
return
}
const threadId = form.threadId ?? ''
// `isSafeThreadId`, not a local regex — the twin of the `isSafeNodeId` gate above and for the
// same reason. This id is caller-supplied and becomes a PATH SEGMENT under the record store;
// the bare charset the route used to carry accepts `.` and `..`.
if (!isSafeThreadId(threadId)) {
res.writeHead(400)
res.end()
return
}
try {
if (!this.codexThreadBindHandler) throw new Error('bind handler unavailable')
await this.codexThreadBindHandler({
nodeId,
threadId,
hookEndpoint: this.endpointFilePath(),
accountId,
agent
})
this.codexIdentityListener?.({ nodeId, mode: 'shared' })
res.writeHead(204)
res.end()
} catch {
res.writeHead(409)
res.end()
}
}
// The managed script sources this file at invocation to get the LIVE port/token.
// tmux sessions outlive the app, so env-baked coords go stale after a restart.
private async writeEndpointFile(): Promise<void> {
try {
const p = this.endpointFilePath()
mkdirSync(path.dirname(p), { recursive: true })
const contents =
// Every value is `posixQuote`d: the managed script SOURCES this file (`. "$file"`) under
// /bin/sh, so an unquoted space or shell metachar in a path or token would break the source
// (issue #351: macOS userDataDir lives under "Application Support" — the space made sh try
// to run the tail of the path, exit 127, and the hook fell back to plain mode for EVERY
// macOS user). Quoting all four keeps the file a valid POSIX assignment list regardless.
`NODETERM_HOOK_PORT=${posixQuote(String(this.port))}\n` +
`NODETERM_HOOK_TOKEN=${posixQuote(this.token)}\n` +
`NODETERM_HOOK_VERSION=${posixQuote(NODETERM_HOOK_PROTOCOL_VERSION)}\n` +
// Where clients read their PER-NODE capability from, keyed by $NODETERM_NODE_ID.
// Advertised (not compiled in) so a failover that sources ANOTHER instance's endpoint
// file also picks up THAT instance's token dir: it then finds a token that instance can
// verify, or none — never a mismatched one.
`NODETERM_NODE_TOKEN_DIR=${posixQuote(nodeTokenDir())}\n` +
// The unix-socket twin, only when it actually bound. Every generated client (managed
// hook script, both sh shims, opencode plugin, codex launcher) is already sock-first —
// `[ -n "$NODETERM_HOOK_SOCK" ]` — so advertising it moves local hook traffic off the
// TCP port; the PORT line stays above for sessions holding a pre-socket script. Quoted
// like every other value (#351/#358): macOS data dirs carry a space.
(this.sockPath ? `NODETERM_HOOK_SOCK=${posixQuote(this.sockPath)}\n` : '')
await writeFileAtomic(
p,
contents,
// 0o600: this file holds the bearer token — owner read/write only so another local user
// can't read it and forge hook events.
{ mode: 0o600 }
)
this.publishedEndpoint = contents
} catch (e) {
console.warn('[agent-hooks] could not write endpoint file', e)
}
}
/**
* Best-effort unlink of the endpoint file, so the advertisement on disk reflects listener
* liveness (issue #445): a file that outlives its listener sends every generated client to a
* dead port first — and before the shims learned the endpoint failover, stopped canvas-control
* cold. Run on stop() and on a failed start(). A crash cannot run it, which is exactly why the
* clients still carry the failover walk; this only closes the windows we CAN close.
*/
private removeEndpointFile(): void {
try {
// A failed/unstarted instance must not erase another run's advertisement.
if (!this.publishedEndpoint || readFileSync(this.endpointFilePath(), 'utf8') !== this.publishedEndpoint) return
unlinkSync(this.endpointFilePath())
this.publishedEndpoint = ''
} catch {
/* nothing to remove — or no booted platform to name the path (tests); both are fine */
}
}
// `permWaitSecs > 0` opts this session into the deterministic hook-reply approval flow: the
// managed permission hook holds for that many seconds for a phone/canvas answer file before
// falling through to Claude's interactive prompt. 0/undefined ⇒ NODETERM_PERM_WAIT_SECS absent ⇒
// the hook's wait-branch is inert (exact legacy behavior). See docs/hook-reply-approvals.md.
buildPtyEnv(nodeId: string, agentId?: AgentId, permWaitSecs = 0): Record<string, string> {
if (this.port <= 0 || !this.token) return {}
return {
// NO NODETERM_HOOK_TOKEN, NO NODETERM_HOOK_PORT — measured 2026-08-13: these ride the tmux
// `-e` argv into a long-lived tmux CLIENT process whose /proc/<pid>/cmdline is mode 444 on a
// stock Linux (no hidepid), so any unprivileged local user read a live app-wide bearer and
// could drive canvas control — including `open-terminal --cmd`, which is NOT in the
// confirm-gated DESTRUCTIVE_VERBS set (src/shared/control-verbs.ts). Every client already
// sources the 0600 endpoint file FIRST
// and prefers it, so nothing legitimate loses anything: the only regression surface is a
// session whose endpoint file is unreadable AND whose env held a good token, a state that
// means the data dir has vanished and the hook is meant to be inert anyway.
NODETERM_HOOK_VERSION: NODETERM_HOOK_PROTOCOL_VERSION,
NODETERM_HOOK_ENDPOINT: this.endpointFilePath(),
// The socket PATH is fine on the tmux -e argv where the token/port were not: it is an
// address, not a credential — connecting still takes the bearer from the 0600 endpoint
// file, and the socket itself sits in a 0700 dir. Advertised in env (not only the endpoint
// file) so the codex sandbox shim can name the exact path in its macOS
// `network.allow_unix_sockets` remedy line (issue #367) even when the endpoint file is
// what a sandboxed sh could not read.
...(this.sockPath ? { NODETERM_HOOK_SOCK: this.sockPath } : {}),
NODETERM_NODE_ID: nodeId,
...(agentId ? { NODETERM_AGENT_ID: agentId } : {}),
...(agentId && permWaitSecs > 0 ? { NODETERM_PERM_WAIT_SECS: String(permWaitSecs) } : {}),
...(agentId && canControlCanvas(agentId) ? { NODETERM_CANVAS_CONTROL: '1' } : {})
// NO NODETERM_CODEX_NODE_TOKEN either. The per-node capability is the same class of leak as
// the app-wide bearer above, and a worse one to reason about: it is the credential that
// proves WHICH node is calling, so a sibling uid reading it off /proc/<pid>/cmdline could
// bind its own codex thread to that node — the exact reparenting this capability exists to
// prevent. It reaches the client through the 0600 token file instead (nodeTokenDir(), keyed
// by $NODETERM_NODE_ID and advertised in the endpoint file) — where the launcher
// (core/codex-identity-proxy.ts) reads it, exactly as the managed script and both sh shims
// do, so shared identity is LIVE with no credential in anyone's argv.
}
}
stop(): void {
// Write what the ledger learned before the process can go: an awaited write races exit.
this.requestLedgerFile?.dispose()
this.requestLedgerFile = null
this.grokPermissionGate?.dispose()
this.grokPermissionGate = null
this.codexPermissionGate?.dispose()
this.codexPermissionGate = null
this.server?.close()
this.server = null
// The file must not advertise a listener that no longer exists (issue #445): a stopped server
// whose endpoint file survives sends every long-lived tmux session's client to a dead port.
// The next start() rewrites it; between the two, clients fail over or say "stale" honestly.
this.removeEndpointFile()
this.unixServer?.close()
this.unixServer = null
// Unlink so the NEXT bind is clean even if close() lost the race with process exit; the
// startup probe can reclaim a confirmed stale socket after a crash.
if (this.sockPath) {
try {
unlinkSync(this.sockPath)
} catch {
/* already gone */
}
this.sockPath = ''
}
this.port = 0
this.token = ''
// Forget the memoized path only now, after removeEndpointFile() used it: the next start()
// re-derives it from the platform it runs under. A process that boots a second core (the
// server e2e suites do, each on its own dataDir) otherwise advertised into the FIRST core's
// directory — recreating a dataDir its test had already removed.
this.endpointPath = ''
}
}
export const hookServer = new HookServer()