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 context-link read path, end to end: the REAL POSIX-sh shim, run by the real /bin/sh,
// against the real hook server and the real renderer. This replaces an identical suite that
// exercised the retired Node CLI — same fixtures and same expectations, so the rewrite answers
// for the behavior it inherited, plus the remote (SSH) case the old shape could not express.
import { describe, it, expect, beforeAll, afterAll } from 'vitest'
import { execFile } from 'node:child_process'
import { mkdirSync, mkdtempSync, readFileSync, writeFileSync, rmSync, chmodSync } from 'node:fs'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { promisify } from 'node:util'
import { CONTEXT_SHIM_SCRIPT, type LinkDoc } from './context-link-core'
import { renderContextLink, type ContextLinkFetch, type ContextLinkVerb } from './context-link-render'
import { hookServer } from './agents/hook-server'
import { initPlatform, resetPlatformForTests } from './platform'
import { fakePlatform } from './platform-fake'
const run = promisify(execFile)
let dir = ''
let shim = ''
let doc: LinkDoc
/** What the fetchers were asked for — how the remote-routing assertions see the difference. */
const asked: { transcripts: string[]; terminals: string[]; exports: string[] } = {
transcripts: [],
terminals: [],
exports: []
}
beforeAll(async () => {
dir = mkdtempSync(join(tmpdir(), 'ctxlink-'))
resetPlatformForTests()
initPlatform(fakePlatform({ userDataDir: dir }))
shim = join(dir, 'context.sh')
writeFileSync(shim, CONTEXT_SHIM_SCRIPT, { mode: 0o755 })
chmodSync(shim, 0o755)
const claudeTranscript = [
JSON.stringify({ type: 'user', message: { content: 'deploy the app' } }),
JSON.stringify({
type: 'assistant',
message: {
content: [
{ type: 'text', text: 'On it.' },
{ type: 'tool_use', name: 'Bash', input: { command: 'npm run build' } }
]
}
})
].join('\n')
const codexTranscript = [
JSON.stringify({ type: 'session_meta', payload: { id: 'sess-x' } }),
JSON.stringify({
type: 'response_item',
payload: { type: 'message', role: 'user', content: [{ type: 'input_text', text: 'fix the tests' }] }
}),
JSON.stringify({
type: 'response_item',
payload: { type: 'message', role: 'assistant', content: [{ type: 'output_text', text: 'Sure, running them.' }] }
}),
JSON.stringify({
type: 'response_item',
payload: { type: 'function_call', name: 'shell', arguments: '{"command":["npm","test"]}' }
}),
JSON.stringify({ type: 'response_item', payload: { type: 'function_call_output', output: '2 passed' } })
].join('\n')
const geminiTranscript = [
JSON.stringify({ sessionId: 'g-sess', projectHash: 'abc' }),
JSON.stringify({ $set: { messages: [{ type: 'user', content: 'hello gemini' }] } }),
JSON.stringify({ $push: { messages: { type: 'gemini', content: 'hello back' } } })
].join('\n')
const opencodeExport = JSON.stringify({
messages: [
{ role: 'user', parts: [{ type: 'text', text: 'add rerank' }] },
{
role: 'assistant',
parts: [
{ type: 'text', text: 'done, added rerank.ts' },
{ type: 'tool', tool: 'bash', state: { input: { command: 'npm test' } } }
]
}
]
})
const bodies: Record<string, string> = {
'node-B': claudeTranscript,
'node-X': codexTranscript,
'node-G': geminiTranscript,
// A REMOTE node: this fixture stands in for bytes fetched over the ControlMaster.
'node-R': claudeTranscript
}
doc = {
self: { id: 'node-A' },
links: [
{ id: 'node-B', title: 'Builder', cwd: '', transcriptPath: join(dir, 'b.jsonl'), tmux: 'nt-node-B' },
{ id: 'node-X', title: 'Coder', cwd: '', transcriptPath: join(dir, 'codex.jsonl'), tmux: 'nt-node-X', agent: 'codex' },
{ id: 'node-G', title: 'Gem', cwd: '', transcriptPath: join(dir, 'gemini.jsonl'), tmux: 'nt-node-G', agent: 'gemini' },
{ id: 'node-Y', title: 'ColdCoder', cwd: '/nowhere', transcriptPath: '', tmux: 'nt-node-Y', agent: 'codex' },
{ id: 'node-O', title: 'OpenCoder', cwd: '', transcriptPath: '', tmux: 'nt-node-O', agent: 'opencode', sessionId: 'ses_abc' },
{ id: 'node-O2', title: 'NoSession', cwd: '', transcriptPath: '', tmux: 'nt-node-O2', agent: 'opencode' },
{ id: 'node-R', title: 'RemoteBuilder', cwd: '', transcriptPath: '/home/u/.claude/projects/x/r.jsonl', tmux: 'nt-node-R' },
{ id: 'note-1', title: 'Deploy notes', cwd: '', transcriptPath: '', tmux: '', note: 'use the staging key' }
],
tmuxBin: null,
tmuxSocket: 'node-terminal'
}
// Fetchers standing in for the real ones (local fs / ssh / tmux): what is under test here is
// the shim ⇄ route ⇄ renderer path, not the filesystem.
const fetchers: ContextLinkFetch = {
transcript: async (node) => {
asked.transcripts.push(node.id)
return bodies[node.id] ?? null
},
terminal: async (node) => {
asked.terminals.push(node.id)
return node.id === 'node-B' ? 'last build ok\n' : ''
},
opencodeExport: async (node) => {
asked.exports.push(node.id)
return node.id === 'node-O' ? opencodeExport : null
}
}
await hookServer.start()
hookServer.setContextLinkHandler(async (req) => {
// Mirrors handleContextLinkRequest's authorization: the document is chosen by the REQUESTER's
// id, never by anything in the request body.
if (req.nodeId !== 'node-A') {
return 'No linked nodes. Draw a context-link edge from this node to another on the canvas.'
}
return renderContextLink(doc, req.verb as ContextLinkVerb, req.args, fetchers)
})
})
afterAll(() => {
hookServer.stop()
rmSync(dir, { recursive: true, force: true })
})
async function shimRun(nodeId: string, args: string[]): Promise<string> {
const { stdout } = await run('/bin/sh', [shim, ...args], {
env: {
PATH: process.env.PATH ?? '',
NODETERM_NODE_ID: nodeId,
NODETERM_HOOK_PORT: String(hookServer.getPort()),
NODETERM_HOOK_TOKEN: hookServer.getToken()
},
maxBuffer: 10 * 1024 * 1024
})
return stdout
}
describe('context-link CLI', () => {
it('list shows the linked node', async () => {
const out = await shimRun('node-A', ['list'])
expect(out).toContain('Builder')
expect(out).toContain('node-B')
})
it('summary prints recent conversation lines', async () => {
const out = await shimRun('node-A', ['summary', '-n', '10', '--node', 'node-B'])
expect(out).toContain('deploy the app')
expect(out).toContain('On it.')
expect(out).toContain('npm run build')
})
it('transcript prints the full conversation', async () => {
const out = await shimRun('node-A', ['transcript', '--node', 'node-B'])
expect(out).toContain('full transcript')
expect(out).toContain('deploy the app')
})
it('terminal prints the captured pane', async () => {
const out = await shimRun('node-A', ['terminal', '--node', 'node-B'])
expect(out).toContain('Builder — terminal')
expect(out).toContain('last build ok')
})
it('terminal reports a session that is not running', async () => {
const out = await shimRun('node-A', ['terminal', '--node', 'node-X'])
expect(out).toContain('not running')
})
it('is a no-op without NODETERM_NODE_ID', async () => {
const out = await shimRun('', ['list'])
expect(out).toContain('Not a nodeterm session')
})
it('list marks sticky notes', async () => {
const out = await shimRun('node-A', ['list'])
expect(out).toContain('Deploy notes (note)')
})
it('summary of a note prints its text', async () => {
const out = await shimRun('node-A', ['summary', '--node', 'note-1'])
expect(out).toContain('Deploy notes — note')
expect(out).toContain('use the staging key')
})
it('transcript of a note prints its text too', async () => {
const out = await shimRun('node-A', ['transcript', '--node', 'Deploy notes'])
expect(out).toContain('use the staging key')
})
it('terminal of a note explains there is no terminal', async () => {
const out = await shimRun('node-A', ['terminal', '--node', 'note-1'])
expect(out).toContain('sticky note')
expect(out).toContain('no terminal')
})
it('renders a codex rollout transcript', async () => {
const out = await shimRun('node-A', ['summary', '-n', '20', '--node', 'node-X'])
expect(out).toContain('user: fix the tests')
expect(out).toContain('assistant: Sure, running them.')
expect(out).toContain('$ shell')
expect(out).toContain('= 2 passed')
})
it('renders a gemini chat transcript (event-sourced replay)', async () => {
const out = await shimRun('node-A', ['transcript', '--node', 'node-G'])
expect(out).toContain('user: hello gemini')
expect(out).toContain('assistant: hello back')
})
it('non-claude agent without a resolved path gets no cwd fallback', async () => {
const out = await shimRun('node-A', ['summary', '--node', 'node-Y'])
expect(out).toContain('no conversation transcript yet')
})
it('renders an opencode transcript via the export', async () => {
const out = await shimRun('node-A', ['transcript', '--node', 'node-O'])
expect(out).toContain('user: add rerank')
expect(out).toContain('assistant: done, added rerank.ts')
expect(out).toContain('$ bash npm test')
})
it('opencode without a session id reports friendly, does not throw', async () => {
const out = await shimRun('node-A', ['summary', '--node', 'node-O2'])
expect(out).toContain('has no session id yet')
})
// The whole point of Phase 2: the transcript is on another machine, and the desktop serves the
// read over the project's ControlMaster. The command an agent types is unchanged.
it('reads a REMOTE node through the same command', async () => {
const out = await shimRun('node-A', ['summary', '--node', 'node-R'])
expect(out).toContain('deploy the app')
expect(asked.transcripts).toContain('node-R')
})
it('matches a node by title, case-insensitively', async () => {
const out = await shimRun('node-A', ['summary', '--node', 'builder'])
expect(out).toContain('deploy the app')
})
it('lists what IS linked when the target is unknown', async () => {
const out = await shimRun('node-A', ['summary', '--node', 'nope'])
expect(out).toContain('No linked node matches')
expect(out).toContain('Builder')
})
// Authorization: a caller holding the hook token still only ever gets ITS OWN document.
it('gives an unlinked node nothing, whatever it asks for', async () => {
const out = await shimRun('node-Z', ['transcript', '--node', 'node-B'])
expect(out).toContain('No linked nodes')
expect(out).not.toContain('deploy the app')
})
})
// The per-node token (task A10). Same shape as every other client: read the file the endpoint
// advertises, keyed by this node's id, present it on BOTH transports.
//
// curl DROPS a header whose value is empty (`-H "X: ${empty}"` sends nothing at all) — which is
// the contract we want, since the server reads absent and empty identically as `legacy`. So
// "empty token" below is read as `headers[...] ?? ''`.
describe('context-link shim presents the per-node token', () => {
const seen: { path: string; nodeToken: string }[] = []
let tcp: import('node:http').Server
let unix: import('node:http').Server
let tcpPort = 0
let sock = ''
let tokenDir = ''
beforeAll(async () => {
const http = await import('node:http')
const handler = (req: import('node:http').IncomingMessage, res: import('node:http').ServerResponse): void => {
req.resume()
req.on('end', () => {
seen.push({ path: req.url ?? '', nodeToken: String(req.headers['x-nodeterm-node-token'] ?? '') })
res.writeHead(200, { 'content-type': 'text/plain; charset=utf-8' })
res.end('ok\n')
})
}
tcp = http.createServer(handler)
unix = http.createServer(handler)
await new Promise<void>((r) => tcp.listen(0, '127.0.0.1', r))
tcpPort = (tcp.address() as { port: number }).port
sock = join(dir, 'ctx-token-probe.sock')
await new Promise<void>((r) => unix.listen(sock, r))
tokenDir = join(dir, 'node-tokens')
mkdirSync(tokenDir, { recursive: true })
writeFileSync(join(tokenDir, 'node-A'), 'CONTEXT-NODE-TOKEN\n', { mode: 0o600 })
})
afterAll(() => {
tcp.close()
unix.close()
})
function probe(nodeId: string, env: Record<string, string>): Promise<unknown> {
return run('/bin/sh', [shim, 'list'], {
env: { PATH: process.env.PATH ?? '', NODETERM_NODE_ID: nodeId, NODETERM_HOOK_TOKEN: 'x', ...env }
})
}
it('sends it over the TCP branch when the file exists', async () => {
seen.length = 0
await probe('node-A', { NODETERM_HOOK_PORT: String(tcpPort), NODETERM_NODE_TOKEN_DIR: tokenDir })
expect(seen).toEqual([{ path: '/context-link/list', nodeToken: 'CONTEXT-NODE-TOKEN' }])
})
it('sends it over the unix-socket branch too (the SSH path)', async () => {
seen.length = 0
await probe('node-A', { NODETERM_HOOK_SOCK: sock, NODETERM_NODE_TOKEN_DIR: tokenDir })
expect(seen).toEqual([{ path: '/context-link/list', nodeToken: 'CONTEXT-NODE-TOKEN' }])
})
it('reads the dir out of the endpoint file, not only the env', async () => {
seen.length = 0
const endpoint = join(dir, 'ctx-token-endpoint.env')
writeFileSync(
endpoint,
`NODETERM_HOOK_PORT=${tcpPort}\nNODETERM_HOOK_TOKEN=whatever\nNODETERM_HOOK_VERSION=2\nNODETERM_NODE_TOKEN_DIR=${tokenDir}\n`
)
await probe('node-A', { NODETERM_HOOK_ENDPOINT: endpoint })
expect(seen).toEqual([{ path: '/context-link/list', nodeToken: 'CONTEXT-NODE-TOKEN' }])
})
it('still reads, with an empty token, when no token file exists', async () => {
seen.length = 0
await probe('node-A', { NODETERM_HOOK_PORT: String(tcpPort), NODETERM_NODE_TOKEN_DIR: join(dir, 'nope') })
expect(seen).toEqual([{ path: '/context-link/list', nodeToken: '' }])
})
it('never presents ANOTHER node\'s token file — the path is keyed by $NODETERM_NODE_ID', async () => {
seen.length = 0
await probe('node-Z', { NODETERM_HOOK_PORT: String(tcpPort), NODETERM_NODE_TOKEN_DIR: tokenDir })
expect(seen).toEqual([{ path: '/context-link/list', nodeToken: '' }])
})
})
// `ps` and /proc/<pid>/cmdline are world-readable, so a credential passed as `curl -H …` is
// published to every other account on the host for the life of that curl — and this shim is
// installed on SSH hosts, where the other accounts are strangers. Both headers go in on stdin.
//
// The recording curl is a PASSTHROUGH (log argv + stdin, then run the real curl), so each case
// proves the credential left argv AND that it still reached the server. Checking only the server's
// headers would pass with the leak entirely intact.
describe('context-link shim keeps credentials off curl\'s command line', () => {
const seen: { hookToken: string; nodeToken: string }[] = []
let tcp: import('node:http').Server
let unix: import('node:http').Server
let tcpPort = 0
let sock = ''
let binDir = ''
let tokenDir = ''
let argvLog = ''
let stdinLog = ''
beforeAll(async () => {
const http = await import('node:http')
const handler = (req: import('node:http').IncomingMessage, res: import('node:http').ServerResponse): void => {
req.resume()
req.on('end', () => {
seen.push({
hookToken: String(req.headers['x-nodeterm-hook-token'] ?? ''),
nodeToken: String(req.headers['x-nodeterm-node-token'] ?? '')
})
res.writeHead(200, { 'content-type': 'text/plain; charset=utf-8' })
res.end('ok\n')
})
}
tcp = http.createServer(handler)
unix = http.createServer(handler)
await new Promise<void>((r) => tcp.listen(0, '127.0.0.1', r))
tcpPort = (tcp.address() as { port: number }).port
sock = join(dir, 'ctx-argv-probe.sock')
await new Promise<void>((r) => unix.listen(sock, r))
tokenDir = join(dir, 'ctx-argv-tokens')
mkdirSync(tokenDir, { recursive: true })
writeFileSync(join(tokenDir, 'node-A'), 'SECRET-NODE-TOKEN\n', { mode: 0o600 })
binDir = join(dir, 'ctx-argv-bin')
mkdirSync(binDir, { recursive: true })
argvLog = join(binDir, 'argv.log')
stdinLog = join(binDir, 'stdin.log')
const realCurl = (await run('/bin/sh', ['-c', 'command -v curl'])).stdout.trim()
writeFileSync(
join(binDir, 'curl'),
[
'#!/bin/sh',
`printf '%s\\n' "$*" >> ${JSON.stringify(argvLog)}`,
// Only a curl told to read its config from stdin gets a reader. A regression that put the
// headers back on argv would otherwise leave `tee` waiting on a stdin nobody ever closes,
// and the failure would read as a timeout instead of the assertion it really is.
'case "$*" in',
` *"--config -"*) tee -a ${JSON.stringify(stdinLog)} | ${JSON.stringify(realCurl)} "$@" ;;`,
` *) ${JSON.stringify(realCurl)} "$@" </dev/null ;;`,
'esac',
''
].join('\n'),
{ mode: 0o755 }
)
})
afterAll(() => {
tcp.close()
unix.close()
})
async function record(env: Record<string, string>): Promise<{ argv: string; stdin: string }> {
// Truncated, not deleted: a regression must fail on the assertion below, not on a missing file.
writeFileSync(argvLog, '')
writeFileSync(stdinLog, '')
seen.length = 0
await run('/bin/sh', [shim, 'list'], {
env: {
PATH: `${binDir}:${process.env.PATH ?? ''}`,
NODETERM_NODE_ID: 'node-A',
NODETERM_HOOK_TOKEN: 'SECRET-BEARER',
NODETERM_NODE_TOKEN_DIR: tokenDir,
...env
}
})
return { argv: readFileSync(argvLog, 'utf8'), stdin: readFileSync(stdinLog, 'utf8') }
}
it('names no credential header in the generated source at all', () => {
expect(CONTEXT_SHIM_SCRIPT).not.toContain('-H "X-Nodeterm-Hook-Token')
expect(CONTEXT_SHIM_SCRIPT).not.toContain('-H "X-Nodeterm-Node-Token')
// Every curl call site reads its headers from stdin: the POST over each transport, and the
// fallback liveness probe over each transport (hook-endpoint-failover-sh.ts).
const calls = CONTEXT_SHIM_SCRIPT.match(/\bcurl -s/g) ?? []
expect(calls).toHaveLength(4)
expect((CONTEXT_SHIM_SCRIPT.match(/--config -/g) ?? []).length).toBe(calls.length)
})
it('over TCP: neither token is in argv, both arrive on stdin and reach the server', async () => {
const { argv, stdin } = await record({ NODETERM_HOOK_PORT: String(tcpPort) })
expect(seen).toEqual([{ hookToken: 'SECRET-BEARER', nodeToken: 'SECRET-NODE-TOKEN' }])
expect(argv).not.toContain('SECRET-BEARER')
expect(argv).not.toContain('SECRET-NODE-TOKEN')
expect(argv).not.toContain('X-Nodeterm-Hook-Token')
expect(argv).not.toContain('X-Nodeterm-Node-Token')
expect(stdin).toContain('header = "X-Nodeterm-Hook-Token: SECRET-BEARER"')
expect(stdin).toContain('header = "X-Nodeterm-Node-Token: SECRET-NODE-TOKEN"')
})
// The SSH transport — the one where the process table belongs to somebody else.
it('over the unix socket: neither token is in argv, both arrive on stdin', async () => {
const { argv, stdin } = await record({ NODETERM_HOOK_PORT: '', NODETERM_HOOK_SOCK: sock })
expect(seen).toEqual([{ hookToken: 'SECRET-BEARER', nodeToken: 'SECRET-NODE-TOKEN' }])
expect(argv).toContain('--unix-socket')
expect(argv).not.toContain('SECRET-BEARER')
expect(argv).not.toContain('SECRET-NODE-TOKEN')
expect(stdin).toContain('header = "X-Nodeterm-Hook-Token: SECRET-BEARER"')
expect(stdin).toContain('header = "X-Nodeterm-Node-Token: SECRET-NODE-TOKEN"')
})
// "No token" still means legacy: curl sends no header at all when there is nothing after the
// colon, exactly as the `-H` form behaved, and the server reads absent and empty alike.
it('still calls with no node token at all when the file is missing', async () => {
const { argv, stdin } = await record({
NODETERM_HOOK_PORT: String(tcpPort),
NODETERM_NODE_TOKEN_DIR: join(dir, 'ctx-argv-none')
})
expect(seen).toEqual([{ hookToken: 'SECRET-BEARER', nodeToken: '' }])
expect(stdin).toContain('header = "X-Nodeterm-Node-Token: "')
expect(argv).not.toContain('X-Nodeterm-Node-Token')
})
})
// Issue #367, context-link leg. The sh fragment is the SAME one the canvas-control shim embeds
// (hook-sandbox-hint-sh.ts) and the full platform/transport matrix lives in
// canvas-control-shim.test.ts; what this suite pins is that the CONTEXT shim wired it into ITS
// failure tail — with its own generic sentence kept byte-for-byte for the non-sandbox case.
describe('codex-sandbox self-diagnosis (issue #367)', () => {
function deadRun(env: Record<string, string>): Promise<{ stderr: string; code?: number }> {
return run('/bin/sh', [shim, 'list'], {
env: {
PATH: process.env.PATH ?? '',
NODETERM_NODE_ID: 'node-A',
NODETERM_HOOK_SOCK: join(dir, 'nobody-listens.sock'),
NODETERM_HOOK_TOKEN: 'x',
...env
}
}).then(
() => ({ stderr: '' }),
(e) => e as { stderr: string; code?: number }
)
}
it('under the sandbox, a dead transport names the sandbox + escalated retry, not "unreachable"', async () => {
const err = await deadRun({ CODEX_SANDBOX_NETWORK_DISABLED: '1' })
expect(err.code).toBe(1)
expect(err.stderr).toContain("Codex's sandbox blocked this connection to nodeterm")
expect(err.stderr).toContain('escalated permissions')
expect(err.stderr).not.toContain('Could not read linked context (nodeterm unreachable).')
})
// The mutation guard: drop the env-var branch and the case above reddens; invert it and this does.
it('without the env var the original genuine-unreachable sentence stands', async () => {
const err = await deadRun({})
expect(err.stderr).toContain('Could not read linked context (nodeterm unreachable).')
expect(err.stderr).not.toContain("Codex's sandbox")
})
it('a healthy endpoint is untouched by the sandbox var (failure-path only)', async () => {
const out = await run('/bin/sh', [shim, 'list'], {
env: {
PATH: process.env.PATH ?? '',
NODETERM_NODE_ID: 'node-A',
NODETERM_HOOK_PORT: String(hookServer.getPort()),
NODETERM_HOOK_TOKEN: hookServer.getToken(),
CODEX_SANDBOX_NETWORK_DISABLED: '1'
}
})
expect(out.stdout).toContain('Builder')
})
})