The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
import { existsSync, mkdirSync, readFileSync, symlinkSync, writeFileSync } from 'node:fs'
import { basename, dirname, join } from 'node:path'
import { fileURLToPath } from 'node:url'
import { describe, expect, it, vi } from 'vitest'
import { isolatedTmux } from '../testing/isolatedTmux.js'
import { resolveBinaryOnPath } from '../lib/binaryOnPath.js'
import { processProbe, runningPane, systemTmuxPaths, windowsRunningPane } from './callerPane.js'
const CLI_ROOT = fileURLToPath(new URL('../..', import.meta.url))
const TSX = join(CLI_ROOT, 'node_modules', 'tsx', 'dist', 'cli.mjs')
const shellQuote = (value: string) => `'${value.replace(/'/g, `'\\''`)}'`
// This process is 900; its shell 800 runs in pane %42, whose process is 700, under the tmux server 600. Pane %7, another
// harness's, is 500.
const panes = [{ pane: '%7', pid: 500 }, { pane: '%42', pid: 700 }]
const chain = (...pids: number[]) => pids.map(pid => ({ pid, command: pid === 600 ? 'tmux' : pid === 1 ? '/sbin/launchd' : '/bin/zsh' }))
const probe = (over: { panes?: typeof panes | null; ancestors?: ReturnType<typeof chain> | null } = {}) => ({
panes: () => over.panes === undefined ? panes : over.panes,
ancestors: () => over.ancestors === undefined ? chain(900, 800, 700, 600, 1) : over.ancestors,
})
const UNPROVEN = { refused: 'Harness could not tell which pane this command runs in, so it did not run it. Run it as your harness gave it, in its own pane.' }
it('finds the pane this command runs in from its parent processes, whatever TMUX_PANE says', () => {
// With the parents its harness is held to (inDaemonPane).
expect(runningPane({ TMUX_PANE: '%42' }, probe(), 'darwin')).toEqual({ pane: '%42', ancestors: [900, 800, 700, 600, 1] })
// Unsetting TMUX_PANE does not hide the pane.
expect(runningPane({}, probe(), 'darwin')).toMatchObject({ pane: '%42' })
// tmux inside a harness's pane: the nearest pane is the one asking.
expect(runningPane({ TMUX_PANE: '%7' }, probe({ ancestors: chain(900, 500, 600, 800, 700, 600, 1) }), 'darwin')).toMatchObject({ pane: '%7' })
})
// The Lead's must on #904's plan: an allowed command can't claim another harness by typing its pane.
it('refuses a TMUX_PANE that names another pane than the one the command runs in', () => {
expect(runningPane({ TMUX_PANE: '%7' }, probe(), 'darwin'))
.toEqual({ refused: 'This command names a pane it does not run in. Run it as your harness gave it, without setting TMUX_PANE.' })
})
// Security review 2 of #2087, late finding: with no pane proven the command went on as a person's terminal. It fails closed
// now whenever it may be in a pane: ps unreadable, a tmux server among its parents, or TMUX or TMUX_PANE set.
it('refuses when it may run in a pane that cannot be proven', () => {
// TMUX pointing at a socket that does not exist: tmux answers nothing, and the server is still among its parents.
expect(runningPane({ TMUX: '/nowhere/default,1,0' }, probe({ panes: null }), 'darwin')).toEqual(UNPROVEN)
expect(runningPane({}, probe({ panes: null }), 'darwin')).toEqual(UNPROVEN)
// Another server's panes, none of them its parent.
expect(runningPane({}, probe({ panes: [{ pane: '%3', pid: 300 }] }), 'darwin')).toEqual(UNPROVEN)
// ps cannot be read: nothing proves where it runs.
expect(runningPane({}, probe({ ancestors: null }), 'darwin')).toEqual(UNPROVEN)
expect(runningPane({ TMUX_PANE: '%42' }, probe({ ancestors: null }), 'darwin')).toEqual(UNPROVEN)
// Detached from its pane by a double fork (its parent is launchd now), with TMUX or TMUX_PANE still set.
for (const env of [{ TMUX: '/private/tmp/tmux-501/default,1,0' }, { TMUX_PANE: '%42' }]) {
expect(runningPane(env, probe({ ancestors: chain(900, 1) }), 'darwin')).toEqual(UNPROVEN)
}
})
it('is no pane for a person\'s terminal outside tmux, nor for a command detached with TMUX and TMUX_PANE unset (the named gap)', () => {
expect(runningPane({}, probe({ ancestors: chain(900, 300, 1) }), 'darwin')).toEqual({})
expect(runningPane({}, probe({ ancestors: chain(900, 300, 1), panes: null }), 'darwin')).toEqual({})
expect(runningPane({}, probe({ ancestors: chain(900, 1) }), 'darwin')).toEqual({})
})
describe('windowsRunningPane', () => {
const UNPROVEN = 'Harness could not tell which pane this command runs in, so it did not run it. Run it as your harness gave it, in its own pane.'
const row = (pid: number, parentPid: number, startMarker: string, executable = 'node.exe') => ({ pid, parentPid, startMarker, executable, args: '' })
const table = (...rows: ReturnType<typeof row>[]) => async () => rows
it('gives the pane a command names, with its parents to hold it to', async () => {
const read = table(row(900, 700, 'w:30'), row(700, 600, 'w:20', 'claude.exe'), row(600, 1, 'w:10', 'harness-pty.exe'))
expect(await windowsRunningPane('p1:%3', read, 900)).toEqual({ pane: 'p1:%3', ancestors: [900, 700, 600] })
})
it('refuses a command under the PTY host that names no pane, whatever the case of its file name', async () => {
for (const host of ['harness-pty.exe', 'HARNESS-PTY.EXE', 'C:\\Users\\me\\.harness\\runtime\\pty\\1\\harness-pty.exe']) {
expect(await windowsRunningPane(undefined, table(row(900, 600, 'w:30'), row(600, 1, 'w:10', host)), 900)).toEqual({ refused: UNPROVEN })
}
})
it('takes a command outside any pane for a person\'s terminal', async () => {
expect(await windowsRunningPane(undefined, table(row(900, 800, 'w:30'), row(800, 1, 'w:10', 'powershell.exe')), 900)).toEqual({})
})
// Windows gives a freed pid to the next process and never reparents: a Builder's pid must not pass for a parent long gone.
it('ends the chain at a parent that started after its child', async () => {
const read = table(row(900, 700, 'w:30'), row(700, 600, 'w:99', 'claude.exe'), row(600, 1, 'w:10', 'harness-pty.exe'))
expect(await windowsRunningPane('p1:%3', read, 900)).toEqual({ pane: 'p1:%3', ancestors: [900] })
expect(await windowsRunningPane(undefined, read, 900)).toEqual({})
})
it('survives a loop in the table', async () => {
expect(await windowsRunningPane('p1:%3', table(row(900, 700, 'w:30'), row(700, 900, 'w:30')), 900))
.toEqual({ pane: 'p1:%3', ancestors: [900, 700] })
})
it('cannot prove a named pane with no table, or a table without this command', async () => {
expect(await windowsRunningPane('p1:%3', async () => null, 900)).toEqual({ refused: UNPROVEN })
expect(await windowsRunningPane('p1:%3', table(row(800, 1, 'w:10')), 900)).toEqual({ refused: UNPROVEN })
expect(await windowsRunningPane(undefined, async () => null, 900)).toEqual({})
})
})
// The second review of #2087: the real tmux and ps outputs, read as they come, and the late finding's three ways to leave
// a pane unproven, each run for real in a pane of a private tmux server.
describe('reading the real processes and panes', () => {
it('reads this process\'s own parents from ps, nearest first', () => {
const chain = processProbe().ancestors()!.map(row => row.pid)
expect(chain.slice(0, 2)).toEqual([process.pid, process.ppid])
expect(new Set(chain).size).toBe(chain.length)
})
// Re-check 1 of #2093 (critical): Harness's own tmux, which install.sh puts on Macs without Homebrew's and in Team
// accounts, was not looked for, so there every agent's Swarm command was refused. The daemon's tmux comes first.
it('reads the panes with the tmux the daemon uses: the managed one first, then the system\'s', async () => {
const tmux = await isolatedTmux()
try {
await tmux.run('new-session', '-d', '-s', 'probe', 'sleep 30')
const pane = await tmux.run('display-message', '-p', '-t', 'probe', '#{pane_id}')
const pid = Number(await tmux.run('display-message', '-p', '-t', 'probe', '#{pane_pid}'))
// A runtime folder as the installer leaves it: the build under it, and current-tmux naming it.
const runtime = join(tmux.root, 'runtime'), managed = join(runtime, 'tmux-3.5a', 'bin', 'tmux')
mkdirSync(dirname(managed), { recursive: true })
symlinkSync(resolveBinaryOnPath('tmux')!, managed)
writeFileSync(join(runtime, 'current-tmux'), `${managed}\n`)
const server = { pid: 0, command: 'tmux' }
// Only the managed tmux on this machine.
expect(processProbe(tmux.env, 'darwin', { runtimeDir: runtime, systemTmux: [] }).panes(server)).toContainEqual({ pane, pid })
// Another version where the system keeps tmux, which cannot talk to the daemon's server: the managed one is used.
const other = join(tmux.root, 'other-tmux')
writeFileSync(other, '#!/bin/sh\necho "protocol version mismatch (client 7, server 8)" >&2\nexit 1\n', { mode: 0o755 })
expect(processProbe(tmux.env, 'darwin', { runtimeDir: runtime, systemTmux: [other] }).panes(server)).toContainEqual({ pane, pid })
// No managed tmux: the system's is used, and one that cannot read the server reads as nothing.
const none = join(tmux.root, 'no-runtime')
expect(processProbe(tmux.env, 'darwin', { runtimeDir: none, systemTmux: [resolveBinaryOnPath('tmux')!] }).panes(server)).toContainEqual({ pane, pid })
expect(processProbe(tmux.env, 'darwin', { runtimeDir: none, systemTmux: [other] }).panes(server)).toBeNull()
// A record naming a tmux outside the runtime folder is not trusted.
writeFileSync(join(runtime, 'current-tmux'), `${other}\n`)
expect(processProbe(tmux.env, 'darwin', { runtimeDir: runtime, systemTmux: [] }).panes(server)).toBeNull()
} finally { await tmux.close() }
}, 30_000)
// Re-check 2 of #2093 (critical 5): MacPorts and the install folders Harness already trusts (tmuxOnPath.ts), after the
// managed tmux, and never PATH: the folders come from this account's home, whatever HOME or PATH say.
it('looks for the system\'s tmux where Harness installs and trusts it, and nowhere a command names', () => {
expect(systemTmuxPaths('darwin', '/Users/ken')).toEqual(['/Users/ken/.local/bin/tmux', '/opt/homebrew/bin/tmux', '/usr/local/bin/tmux',
'/opt/local/bin/tmux', '/usr/bin/tmux', '/bin/tmux', '/run/current-system/sw/bin/tmux'])
expect(systemTmuxPaths('linux', '/home/ken')).toEqual(['/home/ken/.local/bin/tmux', '/usr/local/bin/tmux', '/opt/local/bin/tmux',
'/usr/bin/tmux', '/bin/tmux', '/run/current-system/sw/bin/tmux'])
})
it('finds the pane a command runs in, whatever its environment says, and refuses when it cannot be proven', async () => {
const tmux = await isolatedTmux()
try {
// A tmux first on PATH that would claim this command for another harness's pane.
const fakeBin = join(tmux.root, 'fake-bin')
mkdirSync(fakeBin)
writeFileSync(join(fakeBin, 'tmux'), '#!/bin/sh\necho "%7 $PPID"\n', { mode: 0o755 })
const probeScript = (out: string, cases: string) => {
const script = join(tmux.root, `${basename(out)}.mts`)
writeFileSync(script, `import { writeFileSync } from 'node:fs'\nimport { runningPane } from ${JSON.stringify(join(CLI_ROOT, 'src/superTabs/callerPane.ts'))}\n`
+ `const env = process.env\nwriteFileSync(${JSON.stringify(out)}, JSON.stringify(${cases}))\n`)
return `${shellQuote(process.execPath)} ${shellQuote(TSX)} ${shellQuote(script)}`
}
const inPane = join(tmux.root, 'in-pane.json'), detached = join(tmux.root, 'detached.json')
const cases = `{ named: runningPane(env), unset: runningPane({ ...env, TMUX_PANE: '' }), other: runningPane({ ...env, TMUX_PANE: '%999' }),
badSocket: runningPane({ ...env, TMUX: '/nowhere/default,1,0', TMUX_PANE: '' }),
fakeTmux: runningPane({ ...env, TMUX_PANE: '', PATH: ${JSON.stringify(fakeBin)} + ':' + env.PATH }) }`
// The second probe forks twice and its middle shell exits, so launchd (or init) is its parent, TMUX still set.
await tmux.run('new-session', '-d', '-s', 'probe', '-x', '80', '-y', '20',
`${probeScript(inPane, cases)}; ( ( ${probeScript(detached, `{ detached: runningPane({ ...env, TMUX_PANE: '' }) }`)} & ) & ); sleep 30`)
const pane = await tmux.run('display-message', '-p', '-t', 'probe', '#{pane_id}')
const panePid = Number(await tmux.run('display-message', '-p', '-t', 'probe', '#{pane_pid}'))
expect(processProbe(tmux.env).panes({ pid: 0, command: 'tmux' })).toContainEqual({ pane, pid: panePid })
await vi.waitFor(() => expect(existsSync(inPane) && existsSync(detached)).toBe(true), { timeout: 25_000, interval: 100 })
const unproven = { refused: 'Harness could not tell which pane this command runs in, so it did not run it. Run it as your harness gave it, in its own pane.' }
const withParents = expect.objectContaining({ pane, ancestors: expect.arrayContaining([panePid]) })
expect(JSON.parse(readFileSync(inPane, 'utf8'))).toEqual({ named: withParents, unset: withParents,
other: { refused: 'This command names a pane it does not run in. Run it as your harness gave it, without setting TMUX_PANE.' },
badSocket: unproven, fakeTmux: withParents })
expect(JSON.parse(readFileSync(detached, 'utf8'))).toEqual({ detached: unproven })
} finally { await tmux.close() }
}, 40_000)
})