Skip to content

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.

51.5 KB
Raw Blame
/**
 * Shared-identity spine for Codex canvas nodes.
 *
 * WHY: a Codex terminal node used to spawn a full `codex` process tree per node — one app-server
 * each. A canvas with a dozen Codex nodes paid a dozen servers' worth of RAM for one account. With
 * this, every node on a machine talks to ONE `codex app-server` and owns one THREAD inside it, and
 * the node ↔ thread mapping is what survives resumes, in-pane restarts and app restarts.
 *
 * The mapping is a tiny file per thread under `<userDataDir>/codex-thread-nodes/`. It is read by
 * generated POSIX sh (the hook prelude in `codex-thread-identity-sh.ts`), so it is a flat
 * `key=value` text file — parsed as DATA, never sourced.
 *
 * WHY IT IS SIGNED: the records name a node id and a hook endpoint, and the hook prelude
 * re-exports both into the agent's environment. An attacker who could write one of these files
 * could aim a session's hook traffic at a node (or an endpoint) of their choosing. Every record
 * therefore carries an HMAC over (threadId, nodeId, endpoint) keyed by the same restart-stable
 * secret the hook server uses to mint per-node capabilities
 * (`src/core/agents/node-auth-secret.ts` — sealed via safeStorage on the desktop, raw 0600 bytes on
 * the Server Edition). Unsigned/mis-signed records are ignored, not repaired.
 *
 * ACCOUNT SCOPING (S6): managed Codex accounts add a directory level above the thread id. A
 * SYSTEM record still lives at the bare root (`<root>/<threadId>`), so a machine with no managed
 * accounts keeps the exact S4 layout and its legacy records keep resolving (Constraint 12). A
 * MANAGED record lives under `<root>/<accountId>/<threadId>`. The HMAC now binds the full 4-tuple
 * (threadId, accountScope, nodeId, hookEndpoint) — an empty account id is normalised to the scope
 * string `system`, and a record whose `accountId=` line disagrees with the directory it sits in is
 * rejected, so an account can never be edited to speak for another's threads. Records written
 * before this slice carry no `accountId=` line and are verified with the original 3-tuple preimage
 * at the system scope only — the one back-compat door, and it is a system-scope door.
 *
 * AGENT IDENTITY: a record also carries `agentId=` and `canvasControl=`, because the prelude
 * re-exports both into a tool shell and used to HARDCODE them (`codex`, granted). Hardcoding
 * mislabels every custom agent that inherits the codex harness (`custom:<uuid>`, not `codex`) and
 * asserts a grant the pane may not hold — `buildPtyEnv` gates it on `canControlCanvas`, and
 * `SHARED_IDENTITY_CAPABLE ⊆ CANVAS_CONTROL_CAPABLE` is the only reason the two agree today, a
 * coincidence the list's own comment invites the next agent to break. The HMAC therefore binds the
 * 6-tuple (threadId, accountScope, nodeId, hookEndpoint, agentId, canvasControl). A record with no
 * `agentId=` line is pre-agent and is read with the implied values `codex` + granted, which is
 * exactly what it meant when it was written; the preimages are SELECTED by shape, never tried in
 * turn, so a record that names an agent can never be verified by one that ignores it.
 */
import {
  chmodSync,
  mkdirSync,
  readFileSync,
  readdirSync,
  unlinkSync,
  writeFileSync
} from 'fs'
import path from 'path'
import { CODEX_NO_DAEMON_HELP_ERE } from '../shared/agents/codex-daemon'
import { createHmac, timingSafeEqual } from 'crypto'
import { renameAtomicSync } from './fs-atomic'
import { platform } from './platform'
import { ACCOUNT_ID_RE, isSafeAccountId } from '../shared/codex-account'

/**
 * The scope string for the SYSTEM account (`~/.codex`, no managed id). Empty/undefined account ids
 * normalise to this both in the HMAC preimage and — for the directory — to the bare record root.
 */
export const SYSTEM_ACCOUNT_SCOPE = 'system'

/**
 * The one shape of a safe managed account id, re-exported from the shared seam so there is a single
 * definition of the alphabet the path builders and this proxy both trust. Must start alphanumeric,
 * which blocks `.`/`..`/leading-separator ids at the door before an id becomes a directory scope.
 */
export const SAFE_ACCOUNT_ID = ACCOUNT_ID_RE

/**
 * The scope string for an account id: `system` for empty/undefined, else the validated id itself.
 * THROWS on an id that could escape the mapping directory (`..`, `a/b`, `/abs`, whitespace) — the
 * supply-chain guard, since account ids arrive from hand-editable `settings.json` / `project.json`.
 * A literal id of `system` is refused so the reserved bare-root scope can never be impersonated by
 * a managed subdirectory.
 */
export function accountScope(accountId?: string): string {
  if (!accountId) return SYSTEM_ACCOUNT_SCOPE
  if (accountId === SYSTEM_ACCOUNT_SCOPE || !isSafeAccountId(accountId)) {
    throw new Error('Invalid NodeTerm Codex account scope')
  }
  return accountId
}

/**
 * How long the SERVER gives itself to mint a thread (`startCodexThreadAt`'s default).
 *
 * The launcher's own curl budget is derived from this and is deliberately LARGER
 * (`CODEX_THREAD_START_CLIENT_MAX_S`), so the server is always the side that gives up first.
 * Get that ordering backwards and a slow app-server produces the worst outcome available: curl
 * quits, the launcher falls back to plain codex, and the server carries on to create a thread and
 * write a record for it that nothing will ever resume.
 */
export const CODEX_THREAD_START_TIMEOUT_MS = 20_000
const CODEX_THREAD_START_CLIENT_MAX_S = CODEX_THREAD_START_TIMEOUT_MS / 1000 + 10

const SAFE_NODE_ID = /^[A-Za-z0-9._-]+$/
const SAFE_ENDPOINT = /^\/[A-Za-z0-9._/ -]+$/
const THREAD_ID_CHARSET = /^[A-Za-z0-9._-]+$/
const MAX_THREAD_ID = 128

/**
 * The one predicate for a thread id — the twin of `isSafeNodeId` (core/agents/node-auth-token.ts),
 * for the same reason and against the same trap.
 *
 * The charset alone is NOT enough: `.` and `..` both MATCH `THREAD_ID_CHARSET`, and a thread id is
 * a PATH SEGMENT under `codexThreadIdentityRoot()` (`<root>/<threadId>`, plus the `.<threadId>.…`
 * tmp file beside it) as well as a signed field in the record. A `..` there resolves to the record
 * dir's PARENT. The id is caller-supplied — it arrives on `/codex-thread/bind` as a form field and
 * from a node's persisted state — so refuse `.` and `..` by name, refuse empty, refuse
 * over-length, BEFORE the id ever reaches a path join or a hash.
 *
 * Exported and shared deliberately: the hook routes and `codex-session-name.ts` used to carry
 * their own copies of the bare charset, and two copies of a rule is how one of them stays wrong.
 */
export function isSafeThreadId(id: string): boolean {
  return (
    typeof id === 'string' &&
    id.length > 0 &&
    id.length <= MAX_THREAD_ID &&
    id !== '.' &&
    id !== '..' &&
    THREAD_ID_CHARSET.test(id)
  )
}

/**
 * The agent identity a record may carry, and the canvas-control grant that goes with it.
 *
 * WHY THE RECORD CARRIES THIS AT ALL: the sh prelude re-exports a tool shell's `NODETERM_*`, and it
 * used to HARDCODE `NODETERM_AGENT_ID=codex` and `NODETERM_CANVAS_CONTROL=1`. Both are facts about
 * the PANE that only `hookServer.buildPtyEnv` knows — it sets `NODETERM_AGENT_ID` to the node's own
 * agent id (which is `custom:<uuid>` for a custom agent declaring `baseAgent: 'codex'`, not
 * `codex`) and gates the grant on `canControlCanvas`. A constant in the prelude is the prelude
 * asserting what it cannot know: it mislabels every custom codex-based agent, and it hands out a
 * grant the pane may not hold. Recording them is what lets the prelude EXPORT WHAT THE RECORD SAYS.
 *
 * The grant is not merely derived from the agent id here because the prelude is POSIX sh and cannot
 * evaluate `canControlCanvas` — the membership list plus the custom-agent base resolver live in
 * TypeScript. So the decision is made once, on the desktop, by the same predicate `buildPtyEnv`
 * uses, and travels as a boolean.
 *
 * BOTH FIELDS ARE INSIDE THE SIGNATURE. They name a capability the prelude then exports into an
 * agent's environment, which is exactly the class of field `identitySignature` exists to protect —
 * an unsigned `canvasControl=1` line would be a grant anyone who can write the file could add.
 */
export interface CodexThreadAgent {
  /** The node's own agent id — `codex`, or a `custom:<uuid>` inheriting it. */
  agentId: string
  /** Whether `canControlCanvas` granted this node canvas control at spawn. */
  canvasControl: boolean
}

/**
 * Agent ids are `codex` or `custom:<uuid>`, so the alphabet needs `:` on top of the node-id one.
 * Bounded and re-validated for the same reason every other recovered field is: the value becomes an
 * environment variable in an agent's shell, and the file it comes from is data we parse, not code.
 */
const AGENT_ID_CHARSET = /^[A-Za-z0-9._:-]+$/
const MAX_AGENT_ID = 128

export function isSafeCodexAgentId(id: string): boolean {
  return typeof id === 'string' && id.length > 0 && id.length <= MAX_AGENT_ID && AGENT_ID_CHARSET.test(id)
}

let identityAuthSecret: Buffer | null = null

/** Injected by the shell once, from the same keychain-backed secret the hook server signs with. */
export function setCodexThreadIdentityAuthSecret(secret: Uint8Array): void {
  if (secret.byteLength < 32) throw new Error('Invalid NodeTerm Codex identity-auth secret')
  identityAuthSecret = Buffer.from(secret)
}

/** Test-only: forget the injected secret so a suite can assert the unavailable path. */
export function resetCodexThreadIdentityAuthSecret(): void {
  identityAuthSecret = null
}

export function codexThreadIdentityAvailable(): boolean {
  return !!identityAuthSecret
}

/**
 * Where the thread → node records live. Through `CorePlatform`, NOT `homedir()`: this is state the
 * app owns, and the Server Edition's data dir is not `~`. The generated sh gets this exact path
 * baked in (quoted), so the two never disagree.
 */
export function codexThreadIdentityRoot(): string {
  return path.join(platform().userDataDir, 'codex-thread-nodes')
}

/**
 * The current 6-tuple preimage:
 * HMAC-SHA256(threadId ␀ accountScope ␀ nodeId ␀ hookEndpoint ␀ agentId ␀ canvasControl).
 *
 * The account scope binds the record to ONE account; without it a record for account A could be
 * moved, byte-for-byte, into account B's directory and still verify. The agent id and the grant
 * joined the preimage for the same reason they joined the record: the prelude exports both, so an
 * unsigned copy of either would be a capability anyone able to write the file could edit.
 */
function identitySignature(
  threadId: string,
  scope: string,
  nodeId: string,
  hookEndpoint: string,
  agent: CodexThreadAgent
): string {
  if (!identityAuthSecret) throw new Error('NodeTerm Codex identity authentication is unavailable')
  return createHmac('sha256', identityAuthSecret)
    .update(
      `${threadId}\0${scope}\0${nodeId}\0${hookEndpoint}\0${agent.agentId}\0${agent.canvasControl ? '1' : '0'}`
    )
    .digest('base64url')
}

/**
 * The pre-agent 4-tuple preimage (no agent dimension). Accepted ONLY for a record that carries no
 * `agentId=` line — one written before this slice. See `recordSignatureValid` for why the two
 * preimages are mutually exclusive rather than tried in turn.
 */
function accountScopedIdentitySignature(
  threadId: string,
  scope: string,
  nodeId: string,
  hookEndpoint: string
): string {
  if (!identityAuthSecret) throw new Error('NodeTerm Codex identity authentication is unavailable')
  return createHmac('sha256', identityAuthSecret)
    .update(`${threadId}\0${scope}\0${nodeId}\0${hookEndpoint}`)
    .digest('base64url')
}

/**
 * The pre-S6 3-tuple preimage (no account dimension). Accepted ONLY for a system-scope record that
 * carries no `accountId=` line — i.e. one written before this slice. Every record this slice writes
 * (system included) carries the account line and the 4-tuple, so the legacy door is system-only and
 * closes itself the first time a machine rewrites the record.
 */
function legacyIdentitySignature(threadId: string, nodeId: string, hookEndpoint: string): string {
  if (!identityAuthSecret) throw new Error('NodeTerm Codex identity authentication is unavailable')
  return createHmac('sha256', identityAuthSecret)
    .update(`${threadId}\0${nodeId}\0${hookEndpoint}`)
    .digest('base64url')
}

function signatureEquals(presented: string, expected: string): boolean {
  const a = Buffer.from(presented)
  const b = Buffer.from(expected)
  return a.length === b.length && timingSafeEqual(a, b)
}

/**
 * Verify a parsed record sitting in the `dirScope` directory (Property 7). Two checks, in order:
 *  1. the record's own `accountId=` line must AGREE with the directory it was found in, and
 *  2. the HMAC must match — the 4-tuple for any record with an account line, with a system-only
 *     3-tuple fallback for a legacy record that has no line at all.
 *
 * Check (1) (line-vs-directory) is defence in depth, kept legible rather than removed. What carries
 * Property 7 is the SCOPE-bound HMAC in check (2): a record signed for `acct-A` verifies only with
 * the preimage scope `acct-A`, so re-filing it under `acct-B` fails the MAC regardless of the line
 * check. The legacy 3-tuple fallback is the ONE back-compat door and is restricted to the SYSTEM
 * scope, so a scope-less signature can never be honoured under a managed account. (The mutations
 * that redden these tests are the HMAC one and the `scope === SYSTEM_ACCOUNT_SCOPE` fallback guard;
 * check (1) is redundant with the scope-bound HMAC and is documented as such.)
 *
 * THREE PREIMAGE GENERATIONS, SELECTED — NOT TRIED IN TURN. Which one applies is decided by which
 * LINES the record carries, and exactly one branch runs:
 *   - an `agentId=` line ⇒ the current 6-tuple, and ONLY that;
 *   - no agent line but an `accountId=` line ⇒ the 4-tuple (an S6-era record);
 *   - neither, at the system scope ⇒ the 3-tuple (a pre-S6 record).
 * Selecting rather than falling through is the load-bearing part. A record that DOES name an agent
 * must never verify under a preimage that ignores the agent: that is the door through which an
 * `agentId=custom:…` line could be stripped or rewritten and the record still accepted, putting the
 * prelude back to guessing `codex` — the precise defect this generation exists to close. A caller
 * that wants the old behaviour must present an old-SHAPED record, and an old-shaped record gets the
 * documented implied values (see `parseCodexThreadIdentity`), never a mix of the two.
 */
function recordSignatureValid(threadId: string, dirScope: string, record: ParsedRecord): boolean {
  if (!record.signature || !identityAuthSecret) return false
  const scope = dirScope || SYSTEM_ACCOUNT_SCOPE
  if (record.accountLinePresent) {
    const lineScope = record.accountId || SYSTEM_ACCOUNT_SCOPE
    if (lineScope !== scope) return false
  }
  try {
    if (record.agentDeclared) {
      return signatureEquals(
        record.signature,
        identitySignature(threadId, scope, record.nodeId, record.hookEndpoint, {
          agentId: record.agentId,
          canvasControl: record.canvasControl
        })
      )
    }
    if (record.accountLinePresent) {
      return signatureEquals(
        record.signature,
        accountScopedIdentitySignature(threadId, scope, record.nodeId, record.hookEndpoint)
      )
    }
    return (
      scope === SYSTEM_ACCOUNT_SCOPE &&
      signatureEquals(
        record.signature,
        legacyIdentitySignature(threadId, record.nodeId, record.hookEndpoint)
      )
    )
  } catch {
    return false
  }
}

export interface CodexThreadIdentity extends CodexThreadAgent {
  /** '' for the system account; a managed account id otherwise. */
  accountId: string
  nodeId: string
  hookEndpoint: string
  signature: string
  /**
   * Whether the record NAMED its agent, as opposed to implying `codex` by being pre-agent. Callers
   * that rewrite a record need the difference: re-writing an implication as a signed claim is how a
   * custom codex-based node's guess would become permanent (see `bindCodexThreadIdentity`).
   */
  agentDeclared: boolean
}

interface ParsedRecord extends CodexThreadIdentity {
  accountLinePresent: boolean
}

export function validCodexIdentity(nodeId: string, hookEndpoint: string): boolean {
  return SAFE_NODE_ID.test(nodeId) && SAFE_ENDPOINT.test(hookEndpoint)
}

/** The absolute path of a record for a thread under a scope (`system` ⇒ bare root). */
function recordFilePath(root: string, scope: string, threadId: string): string {
  return scope && scope !== SYSTEM_ACCOUNT_SCOPE
    ? path.join(root, scope, threadId)
    : path.join(root, threadId)
}

function identityFile(threadId: string, scope: string, root = codexThreadIdentityRoot()): string {
  if (!isSafeThreadId(threadId)) throw new Error('Invalid NodeTerm Codex thread identity')
  return recordFilePath(root, scope, threadId)
}

function parseCodexThreadIdentity(raw: string): ParsedRecord {
  const values: Record<string, string> = {}
  for (const line of raw.split('\n')) {
    const separator = line.indexOf('=')
    if (separator < 1) continue
    const key = line.slice(0, separator)
    // First occurrence wins, matching the `head -n 1` the sh prelude uses: a second `accountId=`
    // line cannot be smuggled in to disagree with the first.
    if (!(key in values)) values[key] = line.slice(separator + 1)
  }
  // THE IMPLIED VALUES OF A PRE-AGENT RECORD, and why they are safe. Every record written before
  // this slice was written by this same Codex identity spine, so its node ran the codex CLI —
  // `codex` is the right agent id for it, and `codex` is unconditionally in
  // `CANVAS_CONTROL_CAPABLE`, so its implied grant reproduces today's behaviour exactly. This is
  // therefore a faithful reading of an old record, not a guess about a new one.
  //
  // The fallback is keyed on the LINE BEING ABSENT (`'agentId' in values`), never on the value
  // being empty or unparseable. A record that names an agent is read as naming that agent; there is
  // no input that carries an agent id and still lands on `codex`.
  const agentLinePresent = 'agentId' in values
  return {
    accountId: values.accountId ?? '',
    nodeId: values.nodeId ?? '',
    hookEndpoint: values.endpoint ?? '',
    signature: values.signature ?? '',
    agentId: agentLinePresent ? (values.agentId ?? '') : 'codex',
    canvasControl: agentLinePresent ? values.canvasControl === '1' : true,
    agentDeclared: agentLinePresent,
    accountLinePresent: 'accountId' in values
  }
}

/**
 * Read and verify the record for a thread AT A SPECIFIC SCOPE (`system` = bare root). Returns
 * undefined when it is absent, malformed, badly signed, or its account line disagrees with the
 * directory. The scope itself is validated so a hostile scan entry can never escape the root.
 */
export function readIdentityCandidate(
  threadId: string,
  scope: string,
  root = codexThreadIdentityRoot()
): CodexThreadIdentity | undefined {
  if (!isSafeThreadId(threadId)) return undefined
  const norm = scope || SYSTEM_ACCOUNT_SCOPE
  if (norm !== SYSTEM_ACCOUNT_SCOPE && !isSafeAccountId(norm)) return undefined
  let raw: string
  try {
    raw = readFileSync(recordFilePath(root, norm, threadId), 'utf8')
  } catch {
    return undefined
  }
  const record = parseCodexThreadIdentity(raw)
  if (!validCodexIdentity(record.nodeId, record.hookEndpoint)) return undefined
  // An agent id that reached the record is re-validated before the signature check, exactly as the
  // node id and endpoint are: the value becomes an environment variable in an agent's shell, and a
  // valid signature only proves WE wrote the bytes, not that they are still a shape we accept.
  if (record.agentDeclared && !isSafeCodexAgentId(record.agentId)) return undefined
  if (!recordSignatureValid(threadId, norm, record)) return undefined
  return {
    accountId: record.accountId,
    nodeId: record.nodeId,
    hookEndpoint: record.hookEndpoint,
    signature: record.signature,
    agentId: record.agentId,
    canvasControl: record.canvasControl,
    agentDeclared: record.agentDeclared
  }
}

/**
 * Every verified record for a thread, across every scope present on disk: the bare-root system
 * record plus one per managed-account subdirectory. Unsafe scope names are skipped, never read.
 */
export function identityCandidates(
  threadId: string,
  root = codexThreadIdentityRoot()
): Array<{ scope: string; identity: CodexThreadIdentity }> {
  const out: Array<{ scope: string; identity: CodexThreadIdentity }> = []
  const system = readIdentityCandidate(threadId, SYSTEM_ACCOUNT_SCOPE, root)
  if (system) out.push({ scope: SYSTEM_ACCOUNT_SCOPE, identity: system })
  let entries: Array<{ name: string; isDirectory(): boolean }>
  try {
    entries = readdirSync(root, { withFileTypes: true })
  } catch {
    return out
  }
  for (const entry of entries) {
    if (!entry.isDirectory()) continue
    if (entry.name === SYSTEM_ACCOUNT_SCOPE || !isSafeAccountId(entry.name)) continue
    const identity = readIdentityCandidate(threadId, entry.name, root)
    if (identity) out.push({ scope: entry.name, identity })
  }
  return out
}

/** The record for a thread at a scope (`accountId` empty/undefined ⇒ system), or undefined. */
export function readCodexThreadIdentity(
  threadId: string,
  root = codexThreadIdentityRoot(),
  accountId?: string
): CodexThreadIdentity | undefined {
  let scope: string
  try {
    scope = accountScope(accountId)
  } catch {
    return undefined
  }
  return readIdentityCandidate(threadId, scope, root)
}

/**
 * Recover a thread's owning node after the app restarts. tmux sessions outlive the app, so a
 * running Codex client can outlive every in-memory map we hold; the file is the only thing that
 * still knows which node it belongs to.
 *
 * With `accountId` given the answer is that one scope's record. WITHOUT it — the shared-app-server
 * tool shell that only knows a bare thread id — every scope is scanned and an owner is returned
 * ONLY when it is unambiguous (`owners.size === 1`). The same thread id owned by two accounts is
 * NOT resolved: ambiguous ownership fails closed (Property 3), the same posture as an unproven pane
 * claim in `pane-ownership.ts`.
 */
export function resolveCodexThreadNodeIdentity(
  threadId: string,
  root = codexThreadIdentityRoot(),
  accountId?: string
): string | undefined {
  if (accountId !== undefined) {
    return readCodexThreadIdentity(threadId, root, accountId)?.nodeId
  }
  const candidates = identityCandidates(threadId, root)
  const owners = new Set(candidates.map((c) => c.identity.nodeId))
  return owners.size === 1 ? candidates[0].identity.nodeId : undefined
}

/**
 * Whether a thread id is owned by MORE THAN ONE currently-live node across scopes — a genuine
 * ownership conflict the caller must refuse rather than pick a winner for. A single live owner (or
 * none) is not a conflict. Fail-closed twin of the single-live-owner rule in `bindCodexThreadIdentity`.
 */
export function codexThreadIdentityHasLiveConflict(
  threadId: string,
  isNodeLive: (nodeId: string) => boolean,
  root = codexThreadIdentityRoot()
): boolean {
  const liveOwners = new Set(
    identityCandidates(threadId, root)
      .map((c) => c.identity.nodeId)
      .filter(isNodeLive)
  )
  return liveOwners.size > 1
}

/**
 * Write (or replace) the record for `threadId` under its account scope, atomically.
 *
 * `agent` is what the prelude will export as this thread's `NODETERM_AGENT_ID` /
 * `NODETERM_CANVAS_CONTROL`. Omitting it writes a PRE-AGENT record — the old shape, read back with
 * the documented implied values (`codex`, grant on). That is the honest degrade for a caller that
 * genuinely does not know the node's agent id, and it reproduces the behaviour this slice replaced;
 * it is not a default to reach for when the id IS available.
 */
export function writeCodexThreadIdentity(
  threadId: string,
  nodeId: string,
  hookEndpoint: string,
  root = codexThreadIdentityRoot(),
  accountId?: string,
  agent?: CodexThreadAgent
): void {
  if (!isSafeThreadId(threadId) || !validCodexIdentity(nodeId, hookEndpoint)) {
    throw new Error('Invalid NodeTerm Codex thread identity')
  }
  if (agent && !isSafeCodexAgentId(agent.agentId)) {
    throw new Error('Invalid NodeTerm Codex thread identity')
  }
  const scope = accountScope(accountId) // throws on an id that could escape the mapping directory
  const signature = agent
    ? identitySignature(threadId, scope, nodeId, hookEndpoint, agent)
    : accountScopedIdentitySignature(threadId, scope, nodeId, hookEndpoint)
  const agentLines = agent
    ? `agentId=${agent.agentId}\ncanvasControl=${agent.canvasControl ? '1' : '0'}\n`
    : ''
  const file = identityFile(threadId, scope, root)
  const dir = path.dirname(file)
  const tmp = path.join(dir, `.${threadId}.${process.pid}.${Date.now()}`)
  mkdirSync(dir, { recursive: true, mode: 0o700 })
  let renamed = false
  try {
    writeFileSync(
      tmp,
      `accountId=${accountId ?? ''}\nnodeId=${nodeId}\nendpoint=${hookEndpoint}\n${agentLines}signature=${signature}\n`,
      {
        encoding: 'utf8',
        mode: 0o600
      }
    )
    renameAtomicSync(tmp, file)
    renamed = true
  } finally {
    if (!renamed) {
      try {
        unlinkSync(tmp)
      } catch {
        /* best effort */
      }
    }
  }
}

/**
 * One canvas node owns one Codex conversation, and one conversation belongs to one node. A resume
 * that would steal a thread from a node that is still LIVE is refused — the caller (the launcher)
 * then falls back to a plain `codex`, which is a working session rather than two clients fighting
 * over one thread. A STALE owner (node deleted, app restarted without it) is simply replaced.
 */
export function bindCodexThreadIdentity(
  threadId: string,
  nodeId: string,
  hookEndpoint: string,
  isNodeLive: (nodeId: string) => boolean,
  root = codexThreadIdentityRoot(),
  accountId?: string,
  agent?: CodexThreadAgent
): void {
  if (!isSafeThreadId(threadId) || !validCodexIdentity(nodeId, hookEndpoint)) {
    throw new Error('Invalid NodeTerm Codex thread identity')
  }
  accountScope(accountId) // reject an escaping account id before any read or write
  const existing = readCodexThreadIdentity(threadId, root, accountId)
  if (existing && existing.nodeId !== nodeId && isNodeLive(existing.nodeId)) {
    throw new Error('Codex thread is already bound to another live node')
  }
  // NEVER DOWNGRADE A RECORD THAT ALREADY NAMES ITS AGENT. A rebind arriving without an agent id
  // (an older client, or a pane whose NODETERM_AGENT_ID did not survive) must not strip the line
  // and send the prelude back to guessing `codex` — the same rule `recordSignatureValid` enforces
  // at the signature, applied at the write. What we already know is kept; only what we are told
  // replaces it. `agentDeclared` and not a truthy `agentId` is the test, because a PRE-AGENT record
  // reads back as `codex` by implication and re-writing that implication as a signed claim is
  // exactly the mislabel — for a custom codex-based node it would make the guess permanent.
  const carried =
    agent ??
    (existing?.agentDeclared
      ? { agentId: existing.agentId, canvasControl: existing.canvasControl }
      : undefined)
  // A rebind that would change nothing writes nothing. The agent identity is part of "nothing" now,
  // so a caller that learns the id later still upgrades a pre-agent record in place.
  if (
    existing &&
    existing.nodeId === nodeId &&
    existing.hookEndpoint === hookEndpoint &&
    existing.agentDeclared === !!carried &&
    (!carried ||
      (existing.agentId === carried.agentId && existing.canvasControl === carried.canvasControl))
  ) {
    return
  }
  writeCodexThreadIdentity(threadId, nodeId, hookEndpoint, root, accountId, carried)
}

/**
 * Drop every record naming `nodeId`, when that node is permanently deleted.
 *
 * Two reasons this is not just housekeeping. The directory would otherwise grow one file per
 * thread forever, and — worse — a dead node's record keeps re-exporting its node id and hook
 * endpoint into any tool shell that still carries the thread id, so a deleted node's identity
 * outlives it. Keyed by node, not by thread, because the caller (`destroySession`) knows the node
 * id and nothing else; the directory is one flat level, so the scan is a single readdir.
 *
 * Best effort throughout: a record we cannot read or remove must never fail a node deletion.
 */
export function forgetCodexThreadIdentitiesForNode(
  nodeId: string,
  root = codexThreadIdentityRoot()
): void {
  if (!SAFE_NODE_ID.test(nodeId)) return
  const forgetInScope = (scope: string, dir: string): void => {
    let entries: Array<{ name: string; isFile(): boolean }>
    try {
      entries = readdirSync(dir, { withFileTypes: true })
    } catch {
      return
    }
    for (const entry of entries) {
      if (!entry.isFile()) continue // a managed-scope SUBDIRECTORY at the root is not a thread id
      const threadId = entry.name
      if (!isSafeThreadId(threadId)) continue
      // Reads through the signature check, so a record we do not trust is also one we do not delete.
      if (readIdentityCandidate(threadId, scope, root)?.nodeId !== nodeId) continue
      try {
        unlinkSync(path.join(dir, threadId))
      } catch {
        /* nothing to forget */
      }
    }
  }
  // System records live at the bare root; managed records one directory down, per account scope.
  forgetInScope(SYSTEM_ACCOUNT_SCOPE, root)
  let scopes: Array<{ name: string; isDirectory(): boolean }>
  try {
    scopes = readdirSync(root, { withFileTypes: true })
  } catch {
    return
  }
  for (const entry of scopes) {
    if (!entry.isDirectory()) continue
    if (entry.name === SYSTEM_ACCOUNT_SCOPE || !isSafeAccountId(entry.name)) continue
    forgetInScope(entry.name, path.join(root, entry.name))
  }
}

export function codexLauncherDir(): string {
  return path.join(platform().userDataDir, 'codex-bin')
}

/**
 * The directory a LOCAL shared-identity session gets prepended to its PATH, or null where there is
 * none to reach. Windows answers null: shared identity is gated off there (`refreshCodexIdentityCaps`
 * returns `unsupported-platform`), the launcher is an extensionless sh script cmd/PowerShell could
 * not resolve anyway, and a session's PATH should be exactly the user's.
 */
export function codexLauncherPathDir(platformName: NodeJS.Platform | string = process.platform): string | null {
  return platformName === 'win32' ? null : codexLauncherDir()
}

export const CODEX_LAUNCHER_NAME = 'nodeterm-codex'

export function codexLauncherPath(): string {
  return path.join(codexLauncherDir(), CODEX_LAUNCHER_NAME)
}

/**
 * The generated launcher.
 *
 * Every identity-setup failure path here ends in plain codex (`nt_exec_plain`) — the caller's
 * arguments untouched, plus `--no-daemon` when that codex advertises it (see the function). That is the owner's decision and it follows the repo's own precedent
 * (`gatePermissionMode`: an unknown or failed probe degrades to the bare command, never to a
 * blocked launch). The upstream version of this script exited 69 "identity unavailable", which
 * turns a missing app-server, an older `codex`, a stale tmux session or a locked-down `$HOME` into
 * a DEAD node. Once a shared thread is bound, the launcher remains as its transport supervisor.
 *
 * The fallback is not silent: before exec'ing plain codex the script POSTs `/codex-thread/fallback`
 * with a machine-readable reason, and the desktop marks the node. Nothing is injected into a live
 * agent TUI — text injected into an agent's terminal is prompt injection, which this repo forbids.
 * The supervisor may print a transport status only after the TUI has exited.
 *
 * `appServerStartCommand` and `appServerProbeCommand` are injected so the test suite can run this
 * script for real under `/bin/sh` (the discipline `canvas-control-shim.test.ts` and
 * `remote-claude-usage.test.ts` set).
 */
export function buildCodexLauncherScript(
  appServerStartCommand = 'codex app-server daemon start >/dev/null 2>&1',
  appServerProbeCommand =
    `codex app-server daemon version 2>/dev/null | ` +
    `grep -q '"status"[[:space:]]*:[[:space:]]*"running"'`
): string {
  return `#!/bin/sh
# Generated by NodeTerm. Do not edit — it is rewritten on every launch.
# Runs a Codex session against the ONE shared app-server, bound to this canvas node's thread.
# Anything missing => plain 'codex' with the same arguments. A node that cannot get a managed
# identity must still be a working node.

# Job control, from the top, for the whole script's life — not only inside nt_run_shared.
# Without it every 'codex ... resume' this script runs (the very first launch included, not just a
# post-reset resume) stays in THIS shell's own process group, so the pane's foreground group is the
# supervisor, never the client. Six call sites key off the pane's foreground command
# (agent-restart.ts's exit/resume phases, TerminalNode.tsx's hibernation wake, trigger-delivery.ts's
# shell-owned-pane gate, remote-ssh/agent-resync-decide.ts, pane-process.ts, pty-manager.ts) and every
# one misreads a supervised pane as shell-owned without this. 'set -m' gives the client its own
# process group and hands it the tty's foreground group (tcsetpgrp), restoring the pre-supervisor
# answer — and, as a side effect, keeps a tty SIGINT reaching only the client, which the existing
# 130 case below already assumes. Supported in dash (this script's usual /bin/sh) as well as bash.
set -m

nt_reason=''
nt_node_token=''
nt_fail() { nt_reason=$1; return 1; }

# The app-server is shared by every Codex node in this account scope. Keep ALL lifecycle starts in
# one scrubbed subshell: starting it with a pane's NODETERM_NODE_ID leaks that one node into every
# tool shell the persistent daemon later creates (#350). The account id is deliberately retained —
# one daemon serves one account scope.
nt_start_app_server() (
  unset NODETERM_NODE_ID NODETERM_HOOK_ENDPOINT NODETERM_HOOK_PORT NODETERM_HOOK_TOKEN \
    NODETERM_HOOK_SOCK NODETERM_AGENT_ID NODETERM_CANVAS_CONTROL NODETERM_NODE_TOKEN_DIR \
    NODETERM_PERM_WAIT_SECS
  ${appServerStartCommand}
)

nt_app_server_ready() (
  ${appServerProbeCommand}
)

# A successful remote TUI can still be severed later when the shared daemon is upgraded, repaired,
# or restarted. The Unix socket inode is the daemon generation we can observe without intercepting
# the TUI's terminal streams. A failed read is UNKNOWN, not evidence of a restart; it is useful only
# when a known pre-launch inode changes or the authoritative daemon probe fails.
nt_app_server_generation() (
  nt_socket="\${CODEX_HOME:-$HOME/.codex}/app-server-control/app-server-control.sock"
  [ -e "$nt_socket" ] || return 1
  ls -di "$nt_socket" 2>/dev/null | awk 'NR == 1 { print $1 }'
)

nt_epoch() {
  date +%s 2>/dev/null || printf '0\\n'
}

# Run a known thread under supervision. Normal exits and terminal signals return unchanged. An
# abnormal exit is resumed ONLY when the daemon probe failed or the known socket generation
# changed; a Codex crash against the same healthy daemon must not become a relaunch loop. The
# caller's prompt/options are one-shot and run only on the first launch — replaying an initial
# prompt after transport recovery would duplicate the user's turn.
nt_run_shared() {
  nt_shared_thread=$1
  shift
  nt_first_launch=1
  nt_rapid_resets=0

  # An approval OVERRIDE is refused on a remote resume, whatever its value:
  #
  #   codex --remote unix:// resume <thread> --ask-for-approval on-request
  #   Error: Permission overrides are not supported when resuming a remote task.
  #
  # MEASURED on codex-cli 0.154.0 (macOS 27.0, arm64) against a real thread on a running shared
  # app-server, under a pty. \`on-request\` is in that build's own enum and is its default policy,
  # and it dies exactly like \`never\`; the same command with the flag REMOVED resumes and the TUI
  # stays up; and \`-c approval_policy=never\` is refused identically. So the rule is about the
  # override, not about a value or a spelling, and there is no mapping of \`manual\`/\`auto\`/
  # \`bypassPermissions\` that survives this path. nodeterm appends the flag through
  # \`approvalFlags\` (src/shared/agents/approval-mode.ts), so every shared-identity Codex node
  # reached this line carrying it and died on its first turn, leaving the pane at a bare shell
  # (issue #811).
  #
  # Stripped HERE rather than in the TypeScript that builds the launch line, because the flag is
  # still valid on this script's OTHER exit: every identity-setup failure above ends in
  # \`exec codex "$@"\` — plain codex, no \`--remote\` — where 0.154 accepts it
  # (\`codex --ask-for-approval never --version\` prints the version). Suppressing it one layer up
  # would take the permission mode away from exactly the nodes that could not get a managed
  # identity, against this launcher's own rule that such a node must still be a working node.
  #
  # The \`else\` branch below has always resumed with NO caller options, so "a remote resume
  # carrying no approval flag" is behaviour this launcher already ships — this only makes the first
  # launch agree with the recovery sitting beside it. On an older codex that still accepts the flag
  # on a resume the cost is that the mode is not applied on the managed path, which after the first
  # daemon reset was already true. There is deliberately no capability gate: the refusal is a
  # runtime check (absent from \`--help\`, so \`codexCliSupportsRemote\`'s shape does not transfer)
  # and it fires AFTER the session lookup, so a throwaway thread id answers "no saved session"
  # whether or not the flag is present — probing costs a real resumable thread, which is the thing
  # we are trying to launch.
  #
  # Both spellings and both forms, because a user's \`settings.agentLaunchCommands\` wrapper may
  # spell the flag itself (\`withPermissionMode\` then suppresses ours and lets theirs through).
  # Rebuilt by rotating the positional list, which is the only way sh can edit "$@" without an array.
  nt_drop_next=0
  # The manual-resume hints below name the flag when the launch line carried it: a human resuming
  # by hand after the shared daemon failed must not start or join ANOTHER one with this pane's env.
  nt_hint_nd=''
  nt_left=$#
  while [ "$nt_left" -gt 0 ]; do
    nt_arg=$1
    shift
    nt_left=$((nt_left - 1))
    if [ "$nt_drop_next" -eq 1 ]; then
      nt_drop_next=0
      continue
    fi
    case "$nt_arg" in
      --ask-for-approval|-a) nt_drop_next=1; continue ;;
      --ask-for-approval=*|-a=*) continue ;;
      # Measured on 0.159.2: "ERROR: --no-daemon cannot be used with --remote." The launch line
      # carries it for the plain-codex exits below (nt_exec_plain); the managed thread IS a remote
      # client of the scrubbed shared daemon, so it must not.
      --no-daemon) nt_hint_nd=' --no-daemon'; continue ;;
    esac
    set -- "$@" "$nt_arg"
  done

  while :; do
    nt_generation_before=$(nt_app_server_generation) || nt_generation_before=''
    nt_run_started=$(nt_epoch)

    if [ "$nt_first_launch" -eq 1 ]; then
      codex --remote unix:// resume "$nt_shared_thread" "$@"
    else
      codex --remote unix:// resume "$nt_shared_thread"
    fi
    nt_status=$?

    case "$nt_status" in
      0|129|130|131|143) return "$nt_status" ;;
    esac

    nt_generation_after=$(nt_app_server_generation) || nt_generation_after=''
    # A restarted daemon that happens to land on the same socket inode while healthy answers "no
    # change" here, so a real reset can go undetected. That is a false NEGATIVE, and it fails safe:
    # the loop simply returns this exit status instead of resuming, the same outcome as if the
    # daemon genuinely had not reset. Left alone deliberately — do not "fix" this into a positive.
    nt_daemon_reset=0
    if ! nt_app_server_ready; then
      nt_daemon_reset=1
    elif [ -n "$nt_generation_before" ] && \
         [ "$nt_generation_before" != "$nt_generation_after" ]; then
      nt_daemon_reset=1
    fi
    [ "$nt_daemon_reset" -eq 1 ] || return "$nt_status"

    nt_run_ended=$(nt_epoch)
    # Not a ceiling on resets overall — any run that lasted >= 10s clears the counter, so a daemon
    # that flaps every 11s resumes forever. This only stops a *rapid* burst (four resets with no
    # run reaching 10s in between).
    if [ "$nt_run_started" -gt 0 ] && [ "$nt_run_ended" -ge "$nt_run_started" ] && \
       [ $((nt_run_ended - nt_run_started)) -ge 10 ]; then
      nt_rapid_resets=0
    fi
    nt_rapid_resets=$((nt_rapid_resets + 1))
    if [ "$nt_rapid_resets" -gt 3 ]; then
      printf '\\nNodeTerm: Codex daemon kept resetting; automatic resume stopped. Run: codex%s resume %s\\n' \
        "$nt_hint_nd" "$nt_shared_thread" >&2
      return "$nt_status"
    fi

    printf '\\nNodeTerm: shared Codex connection reset; restoring this session...\\n' >&2
    nt_start_try=0
    while ! nt_app_server_ready; do
      nt_start_app_server || :
      nt_app_server_ready && break
      nt_start_try=$((nt_start_try + 1))
      if [ "$nt_start_try" -ge 3 ]; then
        printf 'NodeTerm: shared Codex daemon did not recover. Run: codex%s resume %s\\n' \
          "$nt_hint_nd" "$nt_shared_thread" >&2
        return "$nt_status"
      fi
      sleep "$nt_start_try"
    done
    nt_first_launch=0
  done
}

# Every plain-codex exit of this script goes through here. From codex-cli 0.157.0 a plain TUI
# starts — or joins — ONE auto-started app-server per CODEX_HOME, and that daemon keeps the
# environment of the pane that started it: every hook process and tool shell of a LATER node then
# runs with the first node's NODETERM_NODE_ID (measured on 0.159.2), and a daemon started from
# here would also be the one our managed threads connect to. '--no-daemon' keeps the TUI
# in-process. The launch line normally carries it already (the desktop probed its own codex); on a
# host nobody probed (an SSH launcher) this asks the binary about to run, and a codex that does not
# advertise the flag gets the caller's arguments untouched — clap exits on an unknown option.
#
# Every IN-PROCESS exit is marked NODETERM_CODEX_PLAIN=1: its hooks run with THIS pane's env, which
# is authoritative even when the thread's record names another node (the bind-refused fallback).
# The hook prelude lets a thread record outrank only an INHERITED id — a daemon's (#1175). A
# --remote exit runs its hooks in the daemon, so it is not marked.
nt_exec_plain() {
  for nt_plain_arg in "$@"; do
    case "$nt_plain_arg" in --remote|--remote=*) exec codex "$@" ;; esac
  done
  NODETERM_CODEX_PLAIN=1
  export NODETERM_CODEX_PLAIN
  for nt_plain_arg in "$@"; do
    case "$nt_plain_arg" in --no-daemon) exec codex "$@" ;; esac
  done
  if codex --help 2>/dev/null | grep -q -E '${CODEX_NO_DAEMON_HELP_ERE}'; then
    exec codex --no-daemon "$@"
  fi
  exec codex "$@"
}

nt_hook_curl() { curl "$@"; }
if [ -n "\${NODETERM_HOOK_SOCK-}" ]; then
  case "$NODETERM_HOOK_SOCK" in
    /*) nt_hook_curl() { curl --unix-socket "$NODETERM_HOOK_SOCK" "$@"; } ;;
    *) nt_reason=broker-unreachable ;;
  esac
fi

# A path we are willing to source. Written with tr rather than a case bracket class because the
# endpoint lives under the app's data dir, which on macOS contains a space ("Application Support")
# — escaping a space inside a case pattern's bracket expression is exactly the kind of quoting
# that reads fine and matches nothing.
nt_safe_path() {
  case "\${1-}" in /*) ;; *) return 1 ;; esac
  [ "$(printf %s "$1" | tr -cd 'A-Za-z0-9._/ -')" = "$1" ]
}

# Runs in THIS shell, never a command substitution: it sources the endpoint file, and that file is
# what carries the live hook port/token. Sourcing it in a subshell would leave both unset here and
# every launch would "fall back" for the wrong reason.
nt_preflight() {
  case "\${NODETERM_NODE_ID-}" in ''|*[!A-Za-z0-9._-]*) nt_fail node-id-unavailable; return ;; esac
  nt_safe_path "\${NODETERM_HOOK_ENDPOINT-}" || { nt_fail hook-endpoint-unavailable; return; }
  [ -r "$NODETERM_HOOK_ENDPOINT" ] || { nt_fail hook-endpoint-unavailable; return; }
  . "$NODETERM_HOOK_ENDPOINT" 2>/dev/null || { nt_fail broker-unreachable; return; }
  case "\${NODETERM_HOOK_PORT-}" in ''|*[!0-9]*) nt_fail broker-unreachable; return ;; esac
  case "\${NODETERM_HOOK_TOKEN-}" in ''|*[!A-Za-z0-9-]*) nt_fail broker-unreachable; return ;; esac
  # The PER-NODE capability, read the way every other client reads it: the endpoint file (v2,
  # sourced just above) advertises the directory, and the token is one 0600 file in it named for
  # THIS node id — a lookup by name, never a scan, so a session can only ever present its own. It
  # is deliberately NOT an env var any more: that channel put the credential on the tmux \`-e\`
  # argv, world-readable on a stock Linux, and the credential's whole job is to prove WHICH node
  # is calling.
  #
  # There is deliberately NO \$NODETERM_CODEX_NODE_TOKEN fallback. One shipped, for a session the
  # previous build spawned, and it could never have worked: that build's value is the OLD
  # derivation — base64url(HMAC(secret, nodeId)), no dot — which the current verifier reads as a
  # foreign kid, i.e. \`legacy\`, and /codex-thread/{start,bind} demand \`verified\`. So it 403s and
  # the launcher degrades anyway, one round-trip later. A pre-upgrade codex session runs plain
  # codex until it is relaunched; that is the honest behaviour, not a regression from the fallback.
  if [ -n "\${NODETERM_NODE_TOKEN_DIR-}" ]; then
    nt_node_token=$(head -n 1 "$NODETERM_NODE_TOKEN_DIR/$NODETERM_NODE_ID" 2>/dev/null) || nt_node_token=''
  fi
  # The '.' IS the token: the wire shape is kid.mac (one derivation shared with /hook/*). A gate
  # without the dot rejects every token this app mints and degrades every codex node to plain
  # codex — silently, because falling back is what this script is built to do.
  case "$nt_node_token" in
    ''|*[!A-Za-z0-9._-]*) nt_fail node-token-unavailable; return ;;
  esac
  if [ "\${1-}" = resume ]; then
    case "\${2-}" in ''|*[!A-Za-z0-9._-]*) nt_fail thread-id-unavailable; return ;; esac
  fi
  # The account scope (S6). Empty ⇒ the system account. A non-empty id is validated to the SAME
  # shape the record store's accountScope() enforces — must START alphanumeric (so '.'/'..'/leading
  # separators can never become a directory scope) — BEFORE it rides a POST body onward. A bad id
  # falls back to plain codex rather than binding a thread under an attacker-shaped scope; the id
  # travels in the request body, never on argv (Constraint 6).
  case "\${NODETERM_CODEX_ACCOUNT_ID-}" in
    '') ;;
    [!A-Za-z0-9]*|*[!A-Za-z0-9._-]*) nt_fail codex-account-invalid; return ;;
  esac
  # The authoritative check runs FIRST and unchanged; the stat below only decides WHICH reason to
  # report. Ordering it the other way would let a codex that no longer needs the standalone runtime
  # fall back on a stat we had no business trusting more than the command itself.
  #
  # Two different facts wore one name before: an older CLI with no app-server at all, and a current
  # CLI installed off a channel that ships no standalone runtime (npm, snap) — where the daemon
  # refuses with "managed standalone Codex install not found at
  # <CODEX_HOME>/packages/standalone/current/codex". Caps normally keeps that second case away from
  # here entirely, but the pane resolves CODEX_HOME from its OWN environment (§8.5) and an install
  # can be removed after boot, so the launcher still has to be able to say which it hit.
  #
  # A responsive app-server is authoritative even when Codex's PID ownership record has gone stale.
  # Calling the lifecycle start first can reject that harmless orphan and degrade this node to plain
  # codex — or tempt a repair to kill infrastructure shared by every pane. Probe first; start only
  # when the protocol itself is not running. nt_start_app_server owns the environment scrub as well
  # as the later recovery path, so duplicating its unset list here would let one path drift into #350.
  if nt_app_server_ready || nt_start_app_server; then
    return 0
  fi
  if [ -x "\${CODEX_HOME:-$HOME/.codex}/packages/standalone/current/codex" ]; then
    nt_fail app-server-unavailable
  else
    nt_fail codex-standalone-missing
  fi
  return
}

# Best effort, and never fatal: tell the desktop this node is running plain codex, so the UI can
# say so without the user reading a log. Sent WITHOUT the per-node capability on purpose — the
# commonest thing it reports is that there was no capability to present. The server only trusts a
# TOKENLESS report on the node it names (see handleCodexThread), so a session that does hold a
# token cannot use this route to flag a sibling.
nt_report_fallback() {
  [ -n "\${NODETERM_HOOK_PORT-}" ] || return 0
  [ -n "\${NODETERM_HOOK_TOKEN-}" ] || return 0
  [ -n "\${NODETERM_NODE_ID-}" ] || return 0
  printf 'header = "X-NodeTerm-Hook-Token: %s"\\n' "$NODETERM_HOOK_TOKEN" |
    nt_hook_curl --silent --show-error --fail --max-time 3 --config - --request POST \\
      --data-urlencode "nodeId=$NODETERM_NODE_ID" \\
      --data-urlencode "reason=$1" \\
      "http://localhost:\${NODETERM_HOOK_PORT-0}/codex-thread/fallback" >/dev/null 2>&1 || :
}

[ -n "$nt_reason" ] || nt_preflight "$@" || :
if [ -n "$nt_reason" ]; then
  nt_report_fallback "$nt_reason"
  nt_exec_plain "$@"
fi

# $1 is the client budget in seconds; the rest is curl's. Start gets a budget LARGER than the
# server's own (CODEX_THREAD_START_TIMEOUT_MS) so the server, not curl, is what times out — a curl
# that quits first leaves behind a thread and a record nothing will ever resume.
nt_post() {
  nt_budget=$1
  shift
  printf 'header = "X-NodeTerm-Hook-Token: %s"\\nheader = "X-NodeTerm-Node-Token: %s"\\n' \\
    "$NODETERM_HOOK_TOKEN" "$nt_node_token" |
    nt_hook_curl --silent --show-error --fail --max-time "$nt_budget" --config - --request POST "$@"
}

if [ "\${1-}" = resume ]; then
  # Claim the caller-supplied thread for THIS node before Codex opens it. A refusal means another
  # live node owns it; two clients on one thread is worse than one plain session, so we fall back.
  if nt_post 20 --data-urlencode "nodeId=$NODETERM_NODE_ID" --data-urlencode "threadId=\${2-}" \\
      --data-urlencode "accountId=\${NODETERM_CODEX_ACCOUNT_ID-}" \\
      --data-urlencode "agentId=\${NODETERM_AGENT_ID-}" \\
      "http://localhost:\${NODETERM_HOOK_PORT-0}/codex-thread/bind" >/dev/null; then
    nt_bound_thread=$2
    shift 2
    nt_run_shared "$nt_bound_thread" "$@"
    exit $?
  fi
  nt_report_fallback thread-bind-refused
  nt_exec_plain "$@"
fi

# THIS PANE'S OWN LABEL travels with both calls, and the pane is the only durable holder of it:
# tmux sessions outlive the app, so a bind arriving after a restart is the common case and nothing
# server-side still remembers what agent this node runs. The server re-derives the canvas-control
# grant from it rather than trusting a claim (see handleCodexThread); an absent or unparseable
# value writes a pre-agent record and the prelude falls back to codex, i.e. the old behaviour.
nt_thread=$(nt_post ${CODEX_THREAD_START_CLIENT_MAX_S} --data-urlencode "nodeId=$NODETERM_NODE_ID" --data-urlencode "cwd=$PWD" \\
  --data-urlencode "accountId=\${NODETERM_CODEX_ACCOUNT_ID-}" \\
  --data-urlencode "agentId=\${NODETERM_AGENT_ID-}" \\
  "http://localhost:\${NODETERM_HOOK_PORT-0}/codex-thread/start") || nt_thread=''
nt_thread=$(printf %s "$nt_thread" | tr -d '\\r\\n')
case "$nt_thread" in
  ''|*[!A-Za-z0-9._-]*)
    nt_report_fallback thread-start-failed
    nt_exec_plain "$@"
    ;;
esac
nt_run_shared "$nt_thread" "$@"
exit $?
`
}

/**
 * Write the launcher and return its path, or null when it could not be installed (read-only home,
 * no permission). Null is a first-class answer: it is what makes `codexIdentityCaps()` say "no"
 * and every launch line stay the bare `codex` it has always been.
 */
export function installCodexLauncher(): string | null {
  try {
    const dir = codexLauncherDir()
    const file = path.join(dir, CODEX_LAUNCHER_NAME)
    mkdirSync(dir, { recursive: true, mode: 0o700 })
    writeFileSync(file, buildCodexLauncherScript(), { encoding: 'utf8', mode: 0o700 })
    chmodSync(file, 0o700)
    return file
  } catch {
    return null
  }
}