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
// Source-text guards over the gates in `TerminalNode.tsx` that no test can reach behaviourally.
//
// Two families live here, for the same reason: neither `TerminalNode.tsx` nor `Canvas.tsx` is
// unit-rendered anywhere in this repo, so a wrong gate compiles, ships, and leaves the whole suite
// green. Both were verified by MUTATION — revert a gate and the matching test below fails.
// 1. the TWO TITLE gates (read vs write), below;
// 2. the CLAUDE-TRANSCRIPT gates (meter rehydration, find-bar transcript index, and the search
// tooltip that describes them) at the bottom of this file.
//
// A guard over the TWO title gates, because the split is the whole point of the title lists.
//
// Reading a session's own name (`TITLE_READ_CAPABLE` — claude, grok, gemini) and PUSHING a name into
// a session (`RENAME_CAPABLE` — claude, grok) are different capabilities. Gating the poll on the
// write list costs gemini the title it names itself; gating a push on the read list types
// `/rename <name>` into a CLI that has no such command, in front of the user, on every rename.
//
// Neither `TerminalNode.tsx` nor `Canvas.tsx` is unit-rendered anywhere in this repo, so there is no
// behavioural test to catch either mistake — these are asserted over the SOURCE TEXT, the same
// technique `core/no-electron.test.ts` uses for the shell boundary. If a refactor moves a gate, the
// invariant is what matters: the poll reads, the push writes.
import { describe, it, expect } from 'vitest'
import fs from 'fs'
import path from 'path'
const read = (rel: string): string => fs.readFileSync(path.join(__dirname, '..', rel), 'utf8')
const terminalNode = read('nodes/TerminalNode.tsx')
const canvas = read('canvas/Canvas.tsx')
const sessionRename = read('lib/sessionRename.ts')
describe('session-name title gates', () => {
it('the node-title poll is gated on the READ capability', () => {
// The effect that adopts the agent's own session name into data.title.
expect(terminalNode).toContain('const canReadTitleNode = !!agentId && canReadTitle(agentId)')
expect(terminalNode).toContain('if (!canReadTitleNode || data.titleAuto === false) return')
// The pre-split gate must be gone from that effect — with it, a gemini node never polls.
expect(terminalNode).not.toContain('if (!canRenameNode || data.titleAuto === false) return')
})
it('the `/rename` push is gated on the WRITE capability', () => {
// Matched on `pushSessionRename(`: the push is delegated to the shared helper,
// which owns both the pane probe and renameCommand composition.
const pushes = terminalNode
.split('\n')
.filter((l) => l.includes('pushSessionRename('))
expect(pushes.length).toBe(1)
expect(pushes[0]).toContain('canRenameNode')
})
it('SECURITY: nobody composes the `/rename` line by hand — it comes from `renameCommand`', () => {
// `renameCommand` is where the title is stripped to ONE line (`@shared/one-line`), because
// `sendText` appends Enter and a `\n`/`\r` in the title would submit a SECOND line — a command
// the agent's operator never typed. The title is agent-supplied (the canvas-control `rename`
// verb's `--title`) and model-supplied (✦ Name with AI), so a second, hand-rolled composition
// site would be a second hole. This is the guard that keeps the strip un-bypassable; a
// behavioural test cannot see it, because neither file is unit-rendered.
for (const [name, src] of [
['nodes/TerminalNode.tsx', terminalNode],
['canvas/Canvas.tsx', canvas]
] as const) {
// The composition shape specifically — a template literal interpolating the name — not the
// string `/rename`, which both files mention in prose.
expect(src.includes('`/rename ${'), `${name} composes the rename line itself`).toBe(false)
}
expect(sessionRename).toContain('export function renameCommand')
expect(sessionRename).toContain('oneLine(name)')
})
it('no rename-WRITE site gates on the read capability', () => {
// These three files hold every push of a node title into a live session (the node header /
// ✦ AI-name funnel, the canvas-control `rename` verb, `renameSession`, and the pane-probing
// helper they all use). None of them may ever consult the READ list: an agent that names its
// own sessions does not necessarily accept a rename.
// TerminalNode's own push is covered by the test above (it holds both gates, so a
// whole-file scan would say nothing); these are the files that hold ONLY write paths.
for (const [name, src] of [
['Canvas.tsx', canvas],
['lib/sessionRename.ts', sessionRename]
] as const) {
expect(src.includes('canReadTitle'), name).toBe(false)
}
})
it('every canvas rename push is compared against the name the node already carries', () => {
// Issues #582 and #569 §2: an orchestrator re-asserts its node's name on startup and after
// every context reset, and the canvas-control `rename` verb pushed `/rename <same title>`
// into the pane every single time — 32 identical injections over six hours in the report,
// each costing the working session a transcript entry plus a `<system-reminder>` claiming the
// USER had renamed it. `pushSessionRename` now REQUIRES the previous name, so the compiler
// catches an omitted argument; what it cannot catch is a call site passing something that is
// not the node's own title, which is what this asserts.
const lines = canvas.split('\n')
const calls = lines.map((l, i) => [l, i] as const).filter(([l]) => l.includes('pushSessionRename('))
expect(calls.length).toBeGreaterThan(0)
for (const [line, i] of calls) {
expect(line.includes('prevTitle'), `${i + 1}: ${line.trim()}`).toBe(true)
}
// …and `prevTitle` is read off the NODE (before the rename lands), never restated from the
// incoming title — comparing the new name against itself would answer "unchanged" always.
const assigned = lines.filter((l) => l.includes('const prevTitle ='))
expect(assigned.length).toBe(calls.length)
for (const line of assigned) expect(line, line.trim()).toContain('data.title')
})
it('every canvas rename push sits behind a canRename guard', () => {
const lines = canvas.split('\n')
const calls = lines.map((l, i) => [l, i] as const).filter(([l]) => l.includes('pushSessionRename('))
expect(calls.length).toBeGreaterThan(0)
for (const [line, i] of calls) {
// The guard is an `if (agentId && canRename(agentId) && …)` a few lines above the call.
const window = lines.slice(Math.max(0, i - 8), i + 1).join('\n')
expect(window.includes('canRename('), `${i + 1}: ${line.trim()}`).toBe(true)
}
})
})
/**
* The claude-transcript gate: `claudeTranscript` (`readsClaudeTranscript(agentId)`), NOT `showUsage`
* (`hasUsage(agentId)`).
*
* `USAGE_CAPABLE` grew to claude + codex + gemini + grok, so `showUsage` is now true for four agents
* while only ONE of them has a claude transcript. The reader behind this gate resolves a session id
* through claude's `resolveTranscript`, whose cwd fallback answers *the newest claude transcript for
* that cwd* — so on a codex or gemini node it resolves an UNRELATED claude session and searches it
* under this node's session id. That was this branch's own Critical fix, and reverting the gate to
* `showUsage` left the full suite green: nothing in this repo renders `TerminalNode`, so this file
* is the only thing standing between the bug and a re-landing.
*
* `context.ensure` USED to be gated here too and deliberately is not any more — see its own test
* below. Its handler stopped resolving every agent through claude's resolver, which is the only
* thing that ever made the shared gate necessary; the find bar's index still does, so it stays.
*
* Asserted per LINE rather than with `toContain` over a 6000-line file: a whole-file `toContain`
* failure dumps the file as its diff, and a per-line assertion names the site instead.
*/
describe('claude-transcript gates', () => {
const lines = terminalNode.split('\n')
/** The lines mentioning `needle`, 1-indexed, as `[lineNo, text]`. */
const sites = (needle: string): [number, string][] =>
lines.map((l, i) => [i + 1, l] as [number, string]).filter(([, l]) => l.includes(needle))
it('is derived from the agent, not from the meter', () => {
// The fact itself, kept separate from `showUsage` one line above it.
expect(terminalNode).toContain('const claudeTranscript = readsClaudeTranscript(agentId)')
expect(terminalNode).toContain('const showUsage = !!agentId && hasUsage(agentId)')
})
/**
* `context.ensure` is the ONE site that legitimately left this gate, and what makes that safe is
* the argument it now passes instead.
*
* The gate never protected the meter; it protected against a HANDLER that resolved every agent
* through claude's `resolveTranscript`. That handler is now `core/context-ensure.ts`, which
* routes on `agentId` to each agent's own locator and tail — so the renderer can gate on the
* meter's own capability (`showUsage`), and a codex node reaches codex's locator rather than
* nothing at all.
*
* The pin therefore moves with the mechanism rather than being deleted: `agentId` MUST reach the
* call, because a widened gate that does not pass it is precisely the original bug (every agent
* resolving as claude, on claude's cwd fallback, adopting a stranger's session). `id` is pinned
* for the same reason on the remote leg: without it the handler cannot tell an SSH-project node
* from a local one, which is what issue #813 reported. `core/context-ensure.test.ts` pins the
* routing itself.
*/
it('gates the find bar’s transcript index (`searchTranscript`)', () => {
const found = sites('searchTranscript:')
expect(found.length).toBe(1)
const [lineNo, text] = found[0]
expect(text, `${lineNo}: ${text.trim()}`).toContain('claudeTranscript')
expect(text, `${lineNo}: ${text.trim()}`).not.toContain('showUsage')
})
it('describes the search the node actually runs, in the button tooltip', () => {
// A tooltip keyed on `showUsage` promises a codex/gemini node "Search terminal + conversation"
// while its transcript leg is off — the copy has to follow the gate, not the meter.
const found = sites("'Search terminal + conversation'")
expect(found.length).toBe(1)
const [lineNo, text] = found[0]
expect(text, `${lineNo}: ${text.trim()}`).toContain('claudeTranscript ?')
expect(text, `${lineNo}: ${text.trim()}`).not.toContain('showUsage')
})
it('leaves the meter itself on the meter capability', () => {
// The inverse mistake: `USAGE_CAPABLE` is what decides whether a meter is shown at all, and
// narrowing THAT to claude would take codex's and gemini's meters away.
const found = sites('<ContextMeter')
expect(found.length).toBe(1)
const [lineNo, text] = found[0]
expect(text, `${lineNo}: ${text.trim()}`).toContain('showUsage &&')
})
})