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
// The hook prelude, run by the real /bin/sh. It is prepended to every managed hook script, so a
// quoting slip here does not break "codex identity recovery" — it breaks every agent's hooks on
// every machine. It is also the one place where a data file's contents become environment
// variables, which is why the negative cases below matter as much as the positive one.
import { describe, it, expect, beforeAll, beforeEach, afterAll } from 'vitest'
import { execFile } from 'node:child_process'
import fs from 'node:fs'
import os from 'node:os'
import path from 'node:path'
import { promisify } from 'node:util'
import { codexThreadIdentityResolverSh } from './codex-thread-identity-sh'
const run = promisify(execFile)
let dir = ''
let root = ''
let script = ''
beforeAll(() => {
// A space in the path on purpose: the real one is macOS's "Application Support".
dir = fs.mkdtempSync(path.join(os.tmpdir(), 'nodeterm codex prelude '))
root = path.join(dir, 'codex-thread-nodes')
fs.mkdirSync(root, { recursive: true })
script = path.join(dir, 'prelude.sh')
fs.writeFileSync(
script,
`#!/bin/sh\n${codexThreadIdentityResolverSh(root)}\n` +
`printf '%s|%s|%s\\n' "\${NODETERM_NODE_ID-}" "\${NODETERM_HOOK_ENDPOINT-}" "\${NODETERM_CANVAS_CONTROL-}"\n`,
{ mode: 0o755 }
)
})
afterAll(() => fs.rmSync(dir, { recursive: true, force: true }))
function record(threadId: string, body: string): void {
fs.writeFileSync(path.join(root, threadId), body)
}
/** Write a managed-scope record under `<root>/<accountId>/<threadId>`. */
function scopedRecord(accountId: string, threadId: string, body: string): void {
fs.mkdirSync(path.join(root, accountId), { recursive: true })
fs.writeFileSync(path.join(root, accountId, threadId), body)
}
/** A well-formed record body for a scope (empty account = system, no accountId line = legacy). */
function body(nodeId: string, accountId?: string): string {
const acct = accountId === undefined ? '' : `accountId=${accountId}\n`
return `${acct}nodeId=${nodeId}\nendpoint=${dir}/hook-endpoint.env\nsignature=x\n`
}
async function resolve(env: Record<string, string>): Promise<string> {
const { stdout } = await run('/bin/sh', [script], {
env: { PATH: process.env.PATH ?? '', HOME: dir, ...env }
})
return stdout.trim()
}
describe('codex thread identity prelude', () => {
it('is valid POSIX sh', async () => {
await expect(run('/bin/sh', ['-n', script])).resolves.toBeTruthy()
})
it('recovers the node binding a tool shell never inherited', async () => {
record('thread-1', `nodeId=node-7\nendpoint=${dir}/hook-endpoint.env\nsignature=x\n`)
expect(await resolve({ CODEX_THREAD_ID: 'thread-1' })).toBe(
`node-7|${dir}/hook-endpoint.env|1`
)
})
it('changes nothing when the session already knows its node', async () => {
record('thread-1', `nodeId=node-7\nendpoint=${dir}/hook-endpoint.env\nsignature=x\n`)
expect(await resolve({ CODEX_THREAD_ID: 'thread-1', NODETERM_NODE_ID: 'node-own' })).toBe(
'node-own||'
)
})
// #350, at the resolver: two projects, a codex node in each with its OWN thread. A daemon-spawned
// tool shell for Project B's thread — with the daemon env CLEAN (no leaked NODETERM_NODE_ID, which
// is what the launcher fix guarantees) — must recover B's node and NEVER A's. This is the
// cross-project isolation the confused-deputy broke: when the daemon leaked node-A's id the guard
// above no-opped and B's tool shell stayed node-A, so B listed A's links and routed to A.
it('cross-project isolation: a clean tool shell for project B resolves B, never A (#350)', async () => {
record('thread-A', `nodeId=node-A\nendpoint=${dir}/hook-endpoint.env\nsignature=x\n`)
record('thread-B', `nodeId=node-B\nendpoint=${dir}/hook-endpoint.env\nsignature=x\n`)
const resolvedB = await resolve({ CODEX_THREAD_ID: 'thread-B' })
expect(resolvedB).toBe(`node-B|${dir}/hook-endpoint.env|1`)
expect(resolvedB).not.toContain('node-A')
// And symmetrically, A's thread never resolves to B.
expect(await resolve({ CODEX_THREAD_ID: 'thread-A' })).toBe(
`node-A|${dir}/hook-endpoint.env|1`
)
})
it('is inert for every other agent (no CODEX_THREAD_ID, no record)', async () => {
expect(await resolve({})).toBe('||')
expect(await resolve({ CODEX_THREAD_ID: 'unknown-thread' })).toBe('||')
})
it('refuses a thread id that could escape the record directory', async () => {
expect(await resolve({ CODEX_THREAD_ID: '../../etc/passwd' })).toBe('||')
})
it('exports nothing when a record carries a node id or endpoint it should not', async () => {
record('thread-bad-node', `nodeId=node 7; rm -rf /\nendpoint=${dir}/e\n`)
expect(await resolve({ CODEX_THREAD_ID: 'thread-bad-node' })).toBe('||')
record('thread-bad-ep', 'nodeId=node-7\nendpoint=relative/e\n')
expect(await resolve({ CODEX_THREAD_ID: 'thread-bad-ep' })).toBe('||')
record('thread-bad-ep2', 'nodeId=node-7\nendpoint=/etc/$(id)\n')
expect(await resolve({ CODEX_THREAD_ID: 'thread-bad-ep2' })).toBe('||')
})
})
// ── S6 PR 2: the account-scoped sh resolver, proven under real /bin/sh (Property 8, Constraint 8) ──
describe('codex thread identity prelude — account scoping', () => {
// The subdir layout differs per test; clear the record store before each so scopes never bleed.
beforeEach(() => {
fs.rmSync(root, { recursive: true, force: true })
fs.mkdirSync(root, { recursive: true })
})
it('binds the one matching managed scope when the daemon carries that account id', async () => {
scopedRecord('acct-A', 'thr-1', body('node-A', 'acct-A'))
expect(
await resolve({ CODEX_THREAD_ID: 'thr-1', NODETERM_CODEX_ACCOUNT_ID: 'acct-A' })
).toBe(`node-A|${dir}/hook-endpoint.env|1`)
})
it('binds the single candidate across scopes when no account id is present (system record)', async () => {
record('thr-1', body('node-sys')) // bare-root legacy/system record, no account line
expect(await resolve({ CODEX_THREAD_ID: 'thr-1' })).toBe(`node-sys|${dir}/hook-endpoint.env|1`)
})
it('binds the single candidate across scopes when no account id is present (one managed record)', async () => {
scopedRecord('acct-A', 'thr-1', body('node-A', 'acct-A'))
expect(await resolve({ CODEX_THREAD_ID: 'thr-1' })).toBe(`node-A|${dir}/hook-endpoint.env|1`)
})
it('fails closed: two scopes hold the same thread id and no account env clears the map', async () => {
scopedRecord('acct-A', 'thr-1', body('node-A', 'acct-A'))
scopedRecord('acct-B', 'thr-1', body('node-B', 'acct-B'))
// MUTATION TARGET: bind on the first match (drop `-eq 1`) ⇒ this exports node-A and reddens.
expect(await resolve({ CODEX_THREAD_ID: 'thr-1' })).toBe('||')
})
it('fails closed: a system record and a managed record collide with no account env', async () => {
record('thr-1', body('node-sys'))
scopedRecord('acct-A', 'thr-1', body('node-A', 'acct-A'))
expect(await resolve({ CODEX_THREAD_ID: 'thr-1' })).toBe('||')
})
it('clears the map when the record account line disagrees with its directory scope', async () => {
// A record physically under acct-B but whose own line still claims acct-A: not honoured as B.
scopedRecord('acct-B', 'thr-1', body('node-A', 'acct-A'))
expect(
await resolve({ CODEX_THREAD_ID: 'thr-1', NODETERM_CODEX_ACCOUNT_ID: 'acct-B' })
).toBe('||')
// And the unscoped scan skips it too (the scope check fails), so nothing binds.
expect(await resolve({ CODEX_THREAD_ID: 'thr-1' })).toBe('||')
})
it('reads only the named account, not a same-thread record in another scope', async () => {
scopedRecord('acct-A', 'thr-1', body('node-A', 'acct-A'))
scopedRecord('acct-B', 'thr-1', body('node-B', 'acct-B'))
// With the account id pinned, the scan never touches the other account — no ambiguity, binds B.
expect(
await resolve({ CODEX_THREAD_ID: 'thr-1', NODETERM_CODEX_ACCOUNT_ID: 'acct-B' })
).toBe(`node-B|${dir}/hook-endpoint.env|1`)
})
it('resolves nothing for a daemon account id that could escape the mapping directory', async () => {
scopedRecord('acct-A', 'thr-1', body('node-A', 'acct-A'))
expect(
await resolve({ CODEX_THREAD_ID: 'thr-1', NODETERM_CODEX_ACCOUNT_ID: '../acct-A' })
).toBe('||')
expect(
await resolve({ CODEX_THREAD_ID: 'thr-1', NODETERM_CODEX_ACCOUNT_ID: 'system' })
).toBe('||')
})
})
// ── The prelude EXPORTS WHAT THE RECORD SAYS ─────────────────────────────────────────────────
//
// `NODETERM_AGENT_ID=codex` and `NODETERM_CANVAS_CONTROL=1` used to be constants here. Both are
// `buildPtyEnv`'s answers about the pane — it labels a node with its OWN agent id (`custom:<uuid>`
// for a custom agent inheriting the codex harness) and gates the grant on `canControlCanvas` — so
// the constants mislabelled every such node and asserted a grant the pane might not hold.
//
// A SECOND script, deliberately, rather than widening the printf above: every expectation in this
// file is a pin on behaviour that must not change for a pre-agent record, and rewriting them all to
// carry a new field would destroy that evidence.
let agentScript = ''
beforeAll(() => {
agentScript = path.join(dir, 'prelude-agent.sh')
fs.writeFileSync(
agentScript,
`#!/bin/sh\n${codexThreadIdentityResolverSh(root)}\n` +
`printf '%s|%s|%s\\n' "\${NODETERM_NODE_ID-}" "\${NODETERM_AGENT_ID-}" "\${NODETERM_CANVAS_CONTROL-}"\n`,
{ mode: 0o755 }
)
})
/** node|agentId|canvasControl, so the exported label and grant can both be asserted. */
async function resolveAgent(env: Record<string, string>): Promise<string> {
const { stdout } = await run('/bin/sh', [agentScript], {
env: { PATH: process.env.PATH ?? '', HOME: dir, ...env }
})
return stdout.trim()
}
/** A record body that NAMES its agent and grant, as every record written now does. */
function agentBody(nodeId: string, agentId: string, grant: boolean): string {
return (
`accountId=\nnodeId=${nodeId}\nendpoint=${dir}/hook-endpoint.env\n` +
`agentId=${agentId}\ncanvasControl=${grant ? '1' : '0'}\nsignature=x\n`
)
}
describe('codex thread identity prelude — the exported agent label and grant', () => {
it('exports the recorded agent id, not the constant codex', async () => {
record('thr-a', agentBody('node-7', 'custom:abc', true))
expect(await resolveAgent({ CODEX_THREAD_ID: 'thr-a' })).toBe('node-7|custom:abc|1')
})
it('leaves the grant UNSET when the record withholds it', async () => {
// Absent, never '0' — both shims gate on `[ -z "$NODETERM_CANVAS_CONTROL" ]`, and this is the
// shape `buildPtyEnv` produces for an agent `canControlCanvas` refuses.
record('thr-b', agentBody('node-7', 'custom:abc', false))
expect(await resolveAgent({ CODEX_THREAD_ID: 'thr-b' })).toBe('node-7|custom:abc|')
})
it('falls back to codex WITH the grant for a pre-agent record', async () => {
// The back-compat contract, exercised end to end: a record written before these fields existed
// came from this same Codex spine, and codex is unconditionally canvas-control-capable.
record('thr-c', body('node-7'))
expect(await resolveAgent({ CODEX_THREAD_ID: 'thr-c' })).toBe('node-7|codex|1')
})
it('resolves NOTHING when the recorded agent id is outside the alphabet', async () => {
// Re-validated here because this prelude cannot check the signature (no key in an agent's
// shell), and the value becomes an environment variable. A bad shape resolves nothing at all
// rather than falling back to codex — the record is not one we wrote, so none of it is trusted.
record('thr-d', agentBody('node-7', 'bad id', true))
expect(await resolveAgent({ CODEX_THREAD_ID: 'thr-d' })).toBe('||')
})
it('carries the agent label through a managed account scope', async () => {
scopedRecord(
'acct-A',
'thr-e',
`accountId=acct-A\nnodeId=node-A\nendpoint=${dir}/hook-endpoint.env\n` +
`agentId=custom:abc\ncanvasControl=0\nsignature=x\n`
)
expect(
await resolveAgent({ CODEX_THREAD_ID: 'thr-e', NODETERM_CODEX_ACCOUNT_ID: 'acct-A' })
).toBe('node-A|custom:abc|')
})
it('is valid POSIX sh', async () => {
await expect(run('/bin/sh', ['-n', agentScript])).resolves.toBeTruthy()
})
})
// The record is parsed by ONE `read` loop rather than a `sed | head` pair per field (a process
// budget: this prelude runs on every hook event). These pin that the loop reads it the way the
// pipelines did: the FIRST line per key wins, even when its value is empty, and a last line with
// no newline still counts. The one deliberate difference is CRLF, asserted on its own below.
describe('codex thread identity prelude — record parsing edge cases', () => {
const endpoint = (): string => `${dir}/hook-endpoint.env`
it('takes the FIRST line of a repeated key', async () => {
record('thread-dup', `nodeId=node-first\nnodeId=node-second\nendpoint=${endpoint()}\n`)
expect(await resolve({ CODEX_THREAD_ID: 'thread-dup' })).toBe(`node-first|${endpoint()}|1`)
})
it('an EMPTY first occurrence still wins, so the record resolves nothing', async () => {
record('thread-empty', `nodeId=\nnodeId=node-late\nendpoint=${endpoint()}\n`)
expect(await resolve({ CODEX_THREAD_ID: 'thread-empty' })).toBe('||')
})
it('reads a last line that has no trailing newline', async () => {
const body = `nodeId=node-u\nendpoint=${endpoint()}`
expect(body.endsWith('\n')).toBe(false)
record('thread-unterminated', body)
expect(await resolve({ CODEX_THREAD_ID: 'thread-unterminated' })).toBe(`node-u|${endpoint()}|1`)
})
it('accepts a CRLF record — the one deliberate widening', async () => {
// Git for Windows' text-mode `sed` dropped the CR, so the old pipelines resolved a CRLF record
// there; GNU/BSD `sed` kept it and the charset checks refused the value. One trailing CR per
// line is now dropped on every platform, BEFORE the same checks run, so nothing outside the
// value alphabets can get through — a record otherwise valid simply resolves everywhere.
const body = `nodeId=node-c\r\nendpoint=${endpoint()}\r\nsignature=x\r\n`
expect(body.split('\r\n')).toHaveLength(4) // the fixture really is CRLF
record('thread-crlf', body)
expect(await resolve({ CODEX_THREAD_ID: 'thread-crlf' })).toBe(`node-c|${endpoint()}|1`)
})
})