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
// `/hook/*` learns to LABEL an event with the identity of the node that posted it.
//
// Two properties are pinned here, and the second one is the load-bearing one:
//
// 1. A valid per-node token makes the event `verified` — the flag reaches BOTH the normalized
// listener and the raw listener.
// 2. NO token is `legacy`, and legacy must behave EXACTLY as it does today: 204, listeners fired,
// never a 403. The phone, a cross-instance failover and any future spawner legitimately have no
// token to present. This route fails OPEN by contract; only `forged` (our own kid with a bad
// mac — a thing nothing legitimate can produce) is refused.
//
// Plus a source-level parity assertion: BOTH shells must register a 4-arg raw listener. This repo
// has shipped a hook-server signature change to one shell only three times; the guard is cheap.
import { describe, it, expect, beforeAll, afterAll, beforeEach } from 'vitest'
import { mkdtempSync, rmSync, readFileSync } from 'node:fs'
import { tmpdir } from 'node:os'
import { join, resolve } from 'node:path'
import { hookServer } from './hook-server'
import { reduceEntry } from '../agent-status-mirror'
import { nodeAuthToken } from './node-auth-token'
import { initPlatform, resetPlatformForTests } from '../platform'
import { fakePlatform } from '../platform-fake'
import type { NormalizedAgentEvent } from '../../shared/agents/normalize'
// Fixed so the tokens below are derivable in the test; length is what setNodeAuthSecret demands.
const SECRET = Buffer.alloc(32, 7)
const OTHER_SECRET = Buffer.alloc(32, 9)
const NODE = 'node-verified-1'
let dir = ''
let events: NormalizedAgentEvent[] = []
let raws: { agentId: string; nodeId: string; meta: { verified: boolean; contextWindow?: number | null } | undefined }[] = []
function post(nodeId: string, token?: string, contextWindow?: string): Promise<Response> {
const headers: Record<string, string> = {
'X-Nodeterm-Hook-Token': hookServer.getToken(),
'content-type': 'application/x-www-form-urlencoded'
}
// A10 teaches the CLIENTS to send this; until then the test is the only caller that does.
if (token !== undefined) headers['X-Nodeterm-Node-Token'] = token
const payload = JSON.stringify({ hook_event_name: 'UserPromptSubmit', session_id: 's1', prompt: 'hi' })
return fetch(`http://127.0.0.1:${hookServer.getPort()}/hook/claude`, {
method: 'POST',
headers,
body: `nodeId=${encodeURIComponent(nodeId)}&payload=${encodeURIComponent(payload)}${contextWindow === undefined ? "" : `&nodeterm_context_window=${encodeURIComponent(contextWindow)}`}`
})
}
beforeAll(async () => {
dir = mkdtempSync(join(tmpdir(), 'hooksrv-verified-'))
resetPlatformForTests()
initPlatform(fakePlatform({ userDataDir: dir }))
await hookServer.start()
hookServer.setNodeAuthSecret(SECRET)
hookServer.setListener((e) => {
events.push(e)
})
hookServer.setRawListener((agentId, nodeId, _payload, meta) => {
raws.push({ agentId, nodeId, meta })
})
})
afterAll(() => {
hookServer.clearNodeAuthSecretForTests()
hookServer.stop()
rmSync(dir, { recursive: true, force: true })
})
beforeEach(() => {
events = []
raws = []
})
describe('hook server: the verified label on /hook/*', () => {
it('labels an event verified when the node presents its own token', async () => {
const res = await post(NODE, nodeAuthToken(SECRET, NODE))
expect(res.status).toBe(204)
expect(events).toHaveLength(1)
expect(events[0].verified).toBe(true)
expect(raws).toEqual([{ agentId: 'claude', nodeId: NODE, meta: { verified: true } }])
})
it('remembers a node that has proven itself', async () => {
await post(NODE, nodeAuthToken(SECRET, NODE))
expect(hookServer.isNodeProven(NODE)).toBe(true)
expect(hookServer.isNodeProven('some-other-node')).toBe(false)
})
// THE FAIL-OPEN CONTRACT. Do not "tighten" this into a 403.
it('accepts a tokenless post exactly as before and labels it unverified — NEVER 403', async () => {
const res = await post(NODE)
expect(res.status).toBe(204)
expect(events).toHaveLength(1)
expect(events[0].verified).toBe(false)
expect(events[0].nodeId).toBe(NODE)
expect(raws).toEqual([{ agentId: 'claude', nodeId: NODE, meta: { verified: false } }])
expect(hookServer.isNodeProven('untokened-node')).toBe(false)
})
it('refuses a forged token — our kid, a mutated mac — with 403 and no listener call', async () => {
const good = nodeAuthToken(SECRET, NODE)
const forged = good.slice(0, -1) + (good.endsWith('A') ? 'B' : 'A')
const res = await post(NODE, forged)
expect(res.status).toBe(403)
expect(events).toEqual([])
expect(raws).toEqual([])
})
it('refuses a token minted for a DIFFERENT node by this instance (same kid, wrong mac)', async () => {
const res = await post(NODE, nodeAuthToken(SECRET, 'some-other-node'))
expect(res.status).toBe(403)
expect(events).toEqual([])
})
// The documented cross-instance failover: another instance's token is unjudgeable, not hostile.
it('treats a foreign kid as legacy — succeeds, unverified, never 403', async () => {
const res = await post(NODE, nodeAuthToken(OTHER_SECRET, NODE))
expect(res.status).toBe(204)
expect(events).toHaveLength(1)
expect(events[0].verified).toBe(false)
expect(raws[0].meta).toEqual({ verified: false })
})
it('is legacy — not forged — for every node when the server has no secret at all', async () => {
hookServer.clearNodeAuthSecretForTests()
try {
const res = await post(NODE, nodeAuthToken(SECRET, NODE))
expect(res.status).toBe(204)
expect(events[0].verified).toBe(false)
} finally {
hookServer.setNodeAuthSecret(SECRET)
}
})
})
describe('both shells register a 4-arg raw listener', () => {
const root = resolve(__dirname, '../../..')
const shells = ['src/main/index.ts', 'src/server/agent-status.ts']
/** Source with comments removed — a comment that mentions `meta.verified` (both shells have one,
* saying why they do NOT read it) is documentation, not a branch.
*
* KNOWN BLIND SPOT, deliberately not fixed with a hand-rolled lexer: this also truncates at a
* `//` inside a string literal, so a real branch sharing a line with a URL would be invisible.
* The cost of missing that is a parity check that passes; the cost of a bespoke JS tokenizer
* here is a guard nobody trusts. If it ever matters, put the branch on its own line. */
const code = (rel: string): string =>
readFileSync(join(root, rel), 'utf8').replace(/\/\/.*|\/\*[\s\S]*?\*\//g, '')
// The rule this repo keeps re-learning: a hook-server change that lands on ONE shell.
// `verified` reaches the mirror through the NORMALIZED listener, so neither raw listener needs
// to read it — and that is a state worth pinning, because "neither" is as easy to break as
// "both". If a future change teaches one raw listener to branch on the flag, the other must
// change in the same commit or this fails.
it('neither raw listener branches on meta.verified — and if one ever does, both must', () => {
const branches = (s: string): boolean => /_?meta(\.verified|\?\.verified)/.test(s)
expect(branches(code('src/main/index.ts'))).toBe(branches(code('src/server/agent-status.ts')))
})
// Same one-shell-drift rule, next instance: the codex subagent branch (spawn_agent fan-out).
// Both raw listeners must (a) tail the child rollout off SubagentStart via trackFile and
// (b) skip the context-meter track for agent_id-tagged child events — a shell missing (a)
// silently has no live activity, and one missing (b) re-points the parent's meter at the
// child's rollout (SubagentStart carries the parent session_id with the CHILD's path).
// Same rule, grok's instance. Three things must be in BOTH shells or the feature is silently
// half-present: (a) the card is keyed by `subagentId` — the only id the start and the stop share,
// since the start's `sessionId` is the PARENT's; (b) the child's transcript is DERIVED from that
// id, never taken from the payload's path, which on the start belongs to the parent; and (c) a
// `session_end` carrying `subagentType` returns early, or a child finishing tears down the
// PARENT's session state and the node goes quiet mid-turn.
it('both raw listeners carry the grok subagent branch (subagentId + derived path + child-end guard)', () => {
for (const rel of ['src/main/index.ts', 'src/server/agent-status.ts']) {
const src = code(rel)
expect(src, `${rel} misses the grok subagent trackFile branch`).toMatch(
/subagentTail\.trackFile\(\s*g\.subagentId/
)
expect(src, `${rel} derives the child path from the payload instead of the subagentId`).toMatch(
/sessionId: g\.subagentId/
)
expect(src, `${rel} misses the child session_end guard`).toMatch(
/g\.event === 'sessionend' && g\.subagentType/
)
}
})
// Same rule, Claude's native SubagentStart/SubagentStop (core/claude-subagent-lifecycle.ts). Five
// things must be in BOTH shells, and each one missing is silent: (a) every normalized event goes
// through the lifecycle before any consumer (else the tool card and the native card are drawn
// twice); (b) the <task-notification> end does too (else it ends nothing in a native session);
// (c) SubagentStart starts the child's tail at the DERIVED path; (d) that branch sits BEFORE the
// child-event gate, which ignores every agent_id-tagged payload and would swallow it; (e) the
// tool-keyed tail is skipped once the session is native, and (f) the lifecycle's release stops
// tails.
it('both shells route Claude subagent events through the ONE lifecycle, and tail natively', () => {
for (const rel of ['src/main/index.ts', 'src/server/agent-status.ts']) {
const src = code(rel)
expect(src, `${rel}: (a) normalized events bypass the lifecycle`).toMatch(/claudeSubagents\.apply\(e\)/)
expect(src, `${rel}: (b) the task-notification end bypasses the lifecycle`).toMatch(
/claudeSubagents\.apply\(taskDoneEvent\)/
)
expect(src, `${rel}: (b) the task-notification end is not labelled`).toMatch(/subagentSignal: 'transcript'/)
expect(src, `${rel}: (c) no native tail at the derived path`).toMatch(
/subagentTail\.trackFile\(\s*agentChild|subagentTail\.trackFile\(\s*native\.agent_id/
)
expect(src, `${rel}: (c) the derived path helper is not used`).toMatch(/claudeSubagentTranscriptPath\(/)
const nativeAt = src.indexOf("native.hook_event_name === 'SubagentStart' || native.hook_event_name === 'SubagentStop'")
const gateAt = src.indexOf('if (ignoreQuestionHook(nodeId, payload)) return')
expect(nativeAt, `${rel}: (d) no native branch`).toBeGreaterThan(-1)
expect(nativeAt, `${rel}: (d) the native branch sits after the child-event gate`).toBeLessThan(gateAt)
expect(src, `${rel}: (e) the tool tail is not skipped for a native session`).toMatch(
/claudeSubagents\.isNative\(nodeId, p\.session_id\)/
)
expect(src, `${rel}: (f) released cards keep their tail`).toMatch(
/new ClaudeSubagentLifecycle\(\{\s*onRelease:[\s\S]{0,40}subagentTail\.finish\(key\)/
)
expect(src, `${rel}: node teardown forgets the lifecycle`).toMatch(/claudeSubagents\.forgetNode\(nodeId\)/)
}
})
// Same rule, Claude's interrupt marker: no hook fires for an Esc/Ctrl+C, so the transcript marker is
// the only end signal. A shell whose claude tail is not handed `onTurnInterrupted` (or whose handler
// does not go through the mirror's `recordTurnInterrupt`) leaves that shell's nodes on RUNNING
// after every interrupt, and nothing else would notice.
it('both shells end an interrupted Claude turn from the transcript marker, through the mirror', () => {
for (const rel of ['src/main/index.ts', 'src/server/agent-status.ts']) {
const src = code(rel)
expect(src, `${rel}: the claude context tail is not given onTurnInterrupted`).toMatch(
/createContextTail\(pushContextUpdate, \{ onTaskNotification, onToolResult, onTurnInterrupted(?:, \w+)* \}\)/
)
// The event must go through the shell's ONE hook-event path (mirror + every tap), not be
// broadcast on the side.
expect(src, `${rel}: the handler does not ask the mirror`).toMatch(
/const ev = turnInterruptEvent\(nodeId, sessionId, turnId\)/
)
expect(src, `${rel}: the interrupt bypasses the shell's hook-event path`).toMatch(
rel.includes('main') ? /if \(ev\) emitAgentStatus\(ev\)/ : /if \(ev\) emit\(ev\)/
)
}
expect(code('src/main/index.ts'), 'the desktop remote (SSH) tail is not given onTurnInterrupted').toMatch(
/createRemoteContextTail\(win, remoteFile, \{ onTaskNotification, onToolResult, onTurnInterrupted(?:, \w+)* \}\)/
)
})
it('both raw listeners carry the codex subagent branch (trackFile + agent_id gate)', () => {
for (const rel of ['src/main/index.ts', 'src/server/agent-status.ts']) {
const src = code(rel)
expect(src, `${rel} misses the SubagentStart trackFile branch`).toMatch(
/SubagentStart'\s*\)\s*\{\s*subagentTail\.trackFile/
)
expect(src, `${rel} misses the agent_id child-event gate`).toMatch(
/agentId === 'codex' && p\.agent_id/
)
}
})
it('the normalized listener is where verified travels, and it is the only gate input', () => {
// Both shells subscribe to the SAME src/core hook server, so this one line is what carries the
// flag to the src/core mirror on both of them. A refactor that drops it here would leave the
// gate reading a field nothing writes — silently, and identically on both shells, which is
// exactly the failure the parity assertion above cannot see.
const hs = readFileSync(join(root, 'src/core/agents/hook-server.ts'), 'utf8')
expect(hs).toMatch(/const labelled = normalized\s*\?\s*\{\s*\.\.\.normalized,\s*verified/)
// Grok events reach the same listener through the permission gate, which receives the
// LABELLED event — so `verified` rides a gated grok event exactly as it rides every other.
expect(hs).toMatch(/this\.grokGate\(\)\.handle\(nodeId, payload, labelled\)/)
expect(hs).toMatch(/this\.listener\(labelled\)/)
})
it('the src/core mirror is the consumer, on both shells', () => {
// The gate reads MirrorEntry.stateVerified. It is only true evidence if the reducer that
// writes it runs wherever hook events land — i.e. if both shells feed the same mirror. The
// SHELL ENTRYPOINTS are what must import it; `server/agent-status.ts` is a module the server
// entrypoint wires up, so it is deliberately not in this list (an earlier version iterated
// `shells` and then `continue`d past it, which checked two files while reading like three).
for (const rel of ['src/main/index.ts', 'src/server/index.ts']) {
const src = readFileSync(join(root, rel), 'utf8')
expect(src, `${rel} does not import the status mirror`).toMatch(/agent-status-mirror/)
}
// Asserted by RUNNING the reducer, not by grepping it: the first version of this line matched
// an exact source string and went red on a pure refactor of the same behaviour, which is a
// guard that trains people to edit the guard.
const proven = reduceEntry(
undefined,
{ kind: 'state', state: 'done', nodeId: 'n1', agentId: 'claude', verified: true } as NormalizedAgentEvent,
1
)
expect(proven.stateVerified).toBe(true)
})
for (const rel of shells) {
it(`${rel} takes the meta argument`, () => {
const src = readFileSync(join(root, rel), 'utf8')
const m = /setRawListener\(\s*(?:async\s*)?\(([^)]*)\)/.exec(src)
expect(m, `${rel} registers no raw listener at all`).toBeTruthy()
const params = m![1]
.split(',')
.map((s) => s.trim())
.filter(Boolean)
expect(params).toHaveLength(4)
expect(params[3]).toMatch(/meta/)
})
}
})
describe('which claude may speak for a node (#1112, #1153)', () => {
const root = resolve(__dirname, '../../..')
// Both shell ENTRYPOINTS wire the pane-tty half of the origin gate (claude-pane-origin.ts). A
// shell that forgets it compiles, passes every unit test and still drops a detached `claude -p`
// — but delivers a daemon-hosted fork's events as the node's, which is #1153 in that shell only.
for (const rel of ['src/main/index.ts', 'src/server/index.ts']) {
it(`${rel} wires the pane tty from its own PtyManager`, () => {
const src = readFileSync(join(root, rel), 'utf8').replace(/\/\/.*|\/\*[\s\S]*?\*\//g, '')
expect(src).toMatch(/wireClaudePaneOrigin\(\{[\s\S]*?hooks:\s*hookServer[\s\S]*?ptyManager\.paneOwner\(/)
})
}
})
describe('session window metadata', () => {
it('accepts validated configuration only from this node identity', async () => {
await post(NODE, nodeAuthToken(SECRET, NODE), '1048576')
expect(raws[0].meta?.contextWindow).toBe(1048576)
await post('legacy', undefined, '32000')
expect(raws[1].meta?.contextWindow).toBeUndefined()
})
it('explicitly invalidates missing or malformed current configuration', async () => {
for (const value of ['', '0', '1e6', '32000oops']) {
await post(NODE, nodeAuthToken(SECRET, NODE), value)
expect(raws.at(-1)?.meta?.contextWindow).toBeNull()
}
})
})