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.

13.8 KB
Raw Blame
/**
 * POSIX-sh prelude prepended to every managed hook script.
 *
 * WHY IT EXISTS: with the shared app-server, the shell a Codex TOOL runs in is spawned by that
 * server, not by the TUI client NodeTerm launched. It therefore inherits `CODEX_THREAD_ID` but
 * none of the `NODETERM_*` env we set on the pane — so the hook it runs has no idea which canvas
 * node it belongs to, and the node's badge/status would simply never move. This recovers the node
 * binding from the thread id.
 *
 * The mapping file is parsed as DATA (a `read` loop — no process per field), never sourced as shell code, and both recovered
 * fields are re-validated before they are exported. The record itself is HMAC-signed by
 * `codex-identity-proxy.ts`; this prelude cannot verify that signature (no key in an agent's
 * shell), which is why the charset re-validation below is not redundant.
 *
 * ACCOUNT SCOPING (S6): a SYSTEM record lives at the bare root (`<root>/<threadId>`) and a MANAGED
 * record under `<root>/<accountId>/<threadId>`. This prelude reads `NODETERM_CODEX_ACCOUNT_ID` from
 * the daemon's env to pick the scope:
 *   - a known, safe account id ⇒ read ONLY that account's record, and require the record's
 *     `accountId=` line to agree with the daemon scope;
 *   - an EMPTY account id (the classic shared tool shell that knows only a bare thread id) ⇒ scan
 *     EVERY scope (bare-root system + each managed subdir) and bind ONLY when exactly one candidate
 *     matches (`nt_codex_matches -eq 1`). Two accounts holding the same thread id ⇒ ambiguous ⇒
 *     change nothing (Property 3 / Constraint 8, the same fail-closed posture as the TypeScript
 *     `resolveCodexThreadNodeIdentity`).
 *
 * WHAT IT EXPORTS IS WHAT THE RECORD SAYS — it does not decide. `NODETERM_AGENT_ID` and
 * `NODETERM_CANVAS_CONTROL` used to be constants here (`codex`, granted), and both are facts only
 * `hookServer.buildPtyEnv` knows: it labels the node with its OWN agent id, which for a custom
 * agent inheriting the codex harness is `custom:<uuid>`, and it gates the grant on
 * `canControlCanvas`. Asserting them here mislabelled every such node, and asserted a grant that
 * agrees with the pane today only because `SHARED_IDENTITY_CAPABLE ⊆ CANVAS_CONTROL_CAPABLE` — a
 * coincidence that list's own comment invites the next shared-identity agent to break. So the pair
 * is recorded at bind time and read back here. A PRE-AGENT record (written before those fields
 * existed) carries neither and means `codex` with the grant, which is precisely what it meant when
 * it was written; a record that names an agent is exported as it stands, grant included, and never
 * falls back to the guess.
 *
 * Inert for every other agent: without `CODEX_THREAD_ID` (or, in the codex HOOK script only, the
 * payload's `session_id` — see HOOK_PAYLOAD_THREAD_SH) the whole block is skipped. A machine with
 * no managed accounts has no subdirs, so the scan reduces to the one bare-root read S4 did — the
 * legacy layout keeps resolving byte-for-byte (Constraint 12).
 *
 * Deliberately free of Node/Electron imports beyond the path it is given: the generated-script
 * cores are shared by the desktop and the Server Edition.
 */
import { posixQuote } from '../shared/ssh'

/**
 * The HOOK variant (#1150, #1175). MEASURED on codex-cli 0.162.0, 2026-10-16 (private CODEX_HOME,
 * private tmux socket, a hook that dumped its env and stdin): under the shared app-server a hook
 * process is a child of the DAEMON, carries the daemon's environment and NEVER `CODEX_THREAD_ID`
 * (only tool shells get that). So:
 *   - a daemon our launcher started (scrubbed) runs hooks with no node id at all and the gate
 *     below exits silently: every managed Codex node stayed dark (#1150);
 *   - a daemon a plain `codex` pane started keeps THAT pane's `NODETERM_NODE_ID` and runs every
 *     later node's hooks under it: events land on a stale node (#1175).
 * What a hook does carry is its payload, whose first key is `session_id` = the thread id (the
 * rollout file is named after it). The managed script reads stdin first and hands this block the
 * id in `nt_hook_thread`; it is still validated by the case below before it names a file.
 *
 * The payload's thread is this EVENT's own, so a record for it outranks an INHERITED node id — but
 * only an inherited one. A pane whose own env is authoritative (our launcher's plain-codex exit,
 * which runs codex in-process with `--no-daemon`) is marked `NODETERM_CODEX_PLAIN=1`, and there the
 * env id stands: that is the bind-refused fallback that legitimately runs a thread another node's
 * record names. A thread with no record changes nothing either way.
 *
 * A forged payload buys nothing: the record only names a node whose 0600 token file the same user
 * can already read, and the event is still verified against that token (docs/node-identity.md).
 */
const HOOK_PAYLOAD_THREAD_SH = `# A HOOK never gets CODEX_THREAD_ID; its payload's session_id is this event's thread.
if [ -n "\${nt_hook_thread-}" ]; then
  nt_codex_tid=$nt_hook_thread
  [ "\${NODETERM_CODEX_PLAIN-}" = 1 ] || nt_codex_rebind=1
fi
`

/**
 * PROBE U5 (Codex 0.146.0, 2026-08-19 — docs/superpowers/probes/2026-08-codex-tool-shell-env.md):
 * a shared `app-server`-spawned tool shell carries `CODEX_THREAD_ID` (measured — a fresh id per
 * thread) and NOT the per-pane `NODETERM_*` (the tool shell forks from the shared daemon, not the
 * connecting client; corroborated by the deployed S4 resolver that depends on exactly this). The
 * premise HOLDS, so the account-scoped scan below is warranted. Caveat: an in-process app-server
 * (`codex exec`) leaks `NODETERM_*`, but the outer `[ -z "$NODETERM_NODE_ID" ]` guard no-ops there.
 *
 * @param identityRoot absolute path of the thread → node record directory
 *   (`codexThreadIdentityRoot()`, i.e. under `CorePlatform.userDataDir` — NOT `~`).
 */
export function codexThreadIdentityResolverSh(
  identityRoot: string,
  opts: { hookPayloadThread?: boolean } = {}
): string {
  return `# A shared-app-server Codex tool shell inherits CODEX_THREAD_ID, not the TUI client's
# NODETERM_* env. Recover this thread's exact node binding (account-scoped), or change nothing.
nt_codex_tid=\${CODEX_THREAD_ID-}
nt_codex_rebind=0
${opts.hookPayloadThread ? HOOK_PAYLOAD_THREAD_SH : ''}if { [ -z "\${NODETERM_NODE_ID-}" ] || [ "$nt_codex_rebind" = 1 ]; } && [ -n "$nt_codex_tid" ]; then
  case "$nt_codex_tid" in
    # '.' and '..' MATCH the charset and are path segments: "$identityRoot"/.. is the record dir's
    # PARENT. Refused by name here for the same reason isSafeThreadId refuses them in TypeScript.
    ''|.|..|*[!A-Za-z0-9._-]*) ;;
    *)
      nt_codex_root=${posixQuote(identityRoot)}
      nt_codex_matches=0
      nt_codex_node=''
      nt_codex_endpoint=''
      nt_codex_agent=''
      nt_codex_grant=''
      # Validate one candidate record file for an expected scope, parsed as DATA. On success it
      # records the node/endpoint/agent/grant and counts the match. $1=file, $2=expected scope
      # ('' = system).
      nt_codex_try() {
        [ -r "$1" ] || return 0
        # ONE PASS, by the shell itself. This used to be five \`sed | head\` command substitutions —
        # fifteen processes per record, on every hook event of every tool shell — and it is the
        # same read: the FIRST line that starts with each key wins (what \`head -n 1\` took, and what
        # \`codex-identity-proxy.ts\` matches on the TypeScript side), the value is everything after
        # the first \`=\`, and a record whose last line has no newline still counts (\`read\` answers
        # non-zero there but has already assigned the line, hence the \`|| [ -n … ]\`). \`IFS=\` and
        # \`-r\` keep the value byte-for-byte: no trimming, no backslash processing. Still DATA, never
        # sourced. The \`nt_s*\` flags are what make "first" mean first even for an empty value.
        nt_a='' nt_n='' nt_e='' nt_g='' nt_c=''
        nt_sa='' nt_sn='' nt_se='' nt_sg='' nt_sc=''
        while IFS= read -r nt_l || [ -n "$nt_l" ]; do
          # A CRLF record. Git for Windows' \`sed\` reads in text mode and dropped the CR, so the old
          # pipeline resolved such a record on Windows; \`read\` keeps it and every charset check
          # below would then refuse the value. Drop ONE trailing CR to keep that working. (On
          # Linux/macOS the old \`sed\` kept the CR and the record was refused, so this is the one
          # place the rewrite is more lenient — harmlessly: the values are validated AFTER the
          # strip, exactly as before.) The \`printf\` costs a process only for a line that really
          # ends in a control character, which no record we write does.
          case "$nt_l" in
            *[[:cntrl:]]) nt_cr=$(printf '\\r'); nt_l=\${nt_l%"$nt_cr"} ;;
          esac
          case "$nt_l" in
            accountId=*) [ -n "$nt_sa" ] || { nt_a=\${nt_l#accountId=}; nt_sa=1; } ;;
            nodeId=*) [ -n "$nt_sn" ] || { nt_n=\${nt_l#nodeId=}; nt_sn=1; } ;;
            endpoint=*) [ -n "$nt_se" ] || { nt_e=\${nt_l#endpoint=}; nt_se=1; } ;;
            agentId=*) [ -n "$nt_sg" ] || { nt_g=\${nt_l#agentId=}; nt_sg=1; } ;;
            canvasControl=*) [ -n "$nt_sc" ] || { nt_c=\${nt_l#canvasControl=}; nt_sc=1; } ;;
          esac
        done < "$1" 2>/dev/null
        # The record's own account line must AGREE with the directory it was found in. A system
        # record's line is empty or the reserved word 'system'; a managed record's line is its id.
        case "$2" in
          '') case "$nt_a" in ''|system) ;; *) return 0 ;; esac ;;
          *) [ "$nt_a" = "$2" ] || return 0 ;;
        esac
        case "$nt_n" in ''|*[!A-Za-z0-9._-]*) return 0 ;; esac
        case "$nt_e" in /*) ;; *) return 0 ;; esac
        # SPACES ARE ADMITTED DELIBERATELY, and this line is the reason to say so. The endpoint is
        # this app's own data-dir path, which on macOS is "~/Library/Application Support/…" — a
        # filter without the space would reject every macOS record and silently disable the whole
        # recovery there. What the value is used FOR is what makes that safe: both shims DOT-SOURCE
        # it with the dot command (canvas-control-core.ts / context-link-core.ts) and the
        # socket it names then reaches curl --unix-socket "$NODETERM_HOOK_SOCK" — every expansion
        # inside double quotes, so a space cannot split into extra arguments. The charset is what
        # keeps quoting and command substitution out; the leading slash above keeps it absolute.
        # The same alphabet as a negated \`case\` class — the idiom the node id and the agent id use
        # two lines away — instead of a \`tr -cd\` round-trip compared with the original: identical
        # verdict, no command substitution and no pipeline. The space is the one character that
        # needs quoting inside the class.
        case "$nt_e" in *[!A-Za-z0-9._/\\ -]*) return 0 ;; esac
        # A PRE-AGENT record (no agentId line, or an empty one) means codex with canvas control:
        # every record written before the agent fields existed was written by this same Codex
        # spine, and codex is unconditionally canvas-control-capable, so the implied pair
        # reproduces what this prelude hardcoded. A record that DOES name an agent is exported as
        # it stands and never falls back to the guess — including its grant, which is then the
        # canControlCanvas answer the pane itself got, not an assumption made here.
        case "$nt_g" in
          '')
            nt_g=codex
            nt_c=1
            ;;
          *[!A-Za-z0-9._:-]*) return 0 ;;
        esac
        nt_codex_node=$nt_n
        nt_codex_endpoint=$nt_e
        nt_codex_agent=$nt_g
        nt_codex_grant=$nt_c
        nt_codex_matches=$((nt_codex_matches + 1))
      }
      case "\${NODETERM_CODEX_ACCOUNT_ID-}" in
        '')
          # Unknown account: scan every scope, bind only if exactly one candidate matches.
          nt_codex_try "$nt_codex_root/$nt_codex_tid" ''
          for nt_codex_dir in "$nt_codex_root"/*/; do
            [ -d "$nt_codex_dir" ] || continue
            nt_codex_scope=\${nt_codex_dir%/}
            nt_codex_scope=\${nt_codex_scope##*/}
            case "$nt_codex_scope" in
              ''|.|..|system|*[!A-Za-z0-9._-]*) continue ;;
            esac
            nt_codex_try "$nt_codex_dir$nt_codex_tid" "$nt_codex_scope"
          done
          ;;
        # A daemon scope that could escape the mapping directory, or the reserved system word used
        # as a managed id: resolve nothing.
        .|..|system|*[!A-Za-z0-9._-]*) ;;
        *)
          nt_codex_try "$nt_codex_root/\${NODETERM_CODEX_ACCOUNT_ID}/$nt_codex_tid" \\
            "$NODETERM_CODEX_ACCOUNT_ID"
          ;;
      esac
      if [ "$nt_codex_matches" -eq 1 ] && [ -n "$nt_codex_node" ] && [ -n "$nt_codex_endpoint" ]
      then
        # The endpoint's own values come from sourcing the RECORD's endpoint file below; anything
        # left over belongs to the env this shell inherited (a stale daemon's, when rebinding).
        unset NODETERM_HOOK_PORT NODETERM_HOOK_TOKEN NODETERM_HOOK_SOCK NODETERM_NODE_TOKEN_DIR \\
          NODETERM_CANVAS_CONTROL
        NODETERM_NODE_ID="$nt_codex_node"
        NODETERM_HOOK_ENDPOINT="$nt_codex_endpoint"
        NODETERM_AGENT_ID="$nt_codex_agent"
        export NODETERM_NODE_ID NODETERM_HOOK_ENDPOINT NODETERM_AGENT_ID
        # The grant is EXPORTED ONLY WHEN THE RECORD CARRIES IT, and is left UNSET otherwise —
        # absent, never '0', the same shape buildPtyEnv produces, because both shims gate on
        # \`[ -z "$NODETERM_CANVAS_CONTROL" ]\`. Withholding is the honest degrade: the tool shell
        # loses a verb its pane still has, whereas asserting a grant the pane was denied is the
        # widening this file must never do.
        if [ "$nt_codex_grant" = 1 ]; then
          NODETERM_CANVAS_CONTROL=1
          export NODETERM_CANVAS_CONTROL
        fi
      fi
      ;;
  esac
fi`
}