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
import { afterEach, describe, expect, it } from 'vitest'
import { spawn, type ChildProcess } from 'child_process'
import {
existsSync,
mkdirSync,
mkdtempSync,
readFileSync,
rmSync,
statSync,
utimesSync,
writeFileSync
} from 'fs'
import net from 'net'
import os from 'os'
import path from 'path'
import { build, type Plugin } from 'esbuild'
import { sessionHostPaths } from './paths'
import { SESSION_HOST_PROTOCOL_VERSION } from './protocol'
interface ExitOutcome {
code: number | null
signal: NodeJS.Signals | null
timedOut: boolean
}
function waitForExit(child: ChildProcess, timeoutMs: number): Promise<ExitOutcome> {
return new Promise((resolve) => {
let timedOut = false
const timer = setTimeout(() => {
timedOut = true
child.kill()
}, timeoutMs)
child.once('exit', (code, signal) => {
clearTimeout(timer)
resolve({ code, signal, timedOut })
})
})
}
function endpointAcceptsConnections(endpoint: string): Promise<boolean> {
return new Promise((resolve) => {
const socket = net.connect(endpoint)
let settled = false
const finish = (connected: boolean): void => {
if (settled) return
settled = true
socket.destroy()
resolve(connected)
}
socket.once('connect', () => finish(true))
socket.once('error', () => finish(false))
socket.setTimeout(500, () => finish(false))
})
}
function failureInjectionPlugin(): Plugin {
return {
name: 'session-host-startup-failure',
setup(bundle) {
bundle.onResolve({ filter: /^\.\/state-file$/ }, () => ({
path: 'injected-state-file',
namespace: 'startup-failure'
}))
bundle.onResolve({ filter: /^node-pty$/ }, () => ({
path: 'node-pty',
namespace: 'startup-failure'
}))
bundle.onLoad(
{ filter: /^injected-state-file$/, namespace: 'startup-failure' },
() => ({
loader: 'js',
contents: `
export function publishSessionHostState() {
const error = new Error('injected state publication failure')
error.code = 'ENOSPC'
throw error
}
`
})
)
bundle.onLoad({ filter: /^node-pty$/, namespace: 'startup-failure' }, () => ({
loader: 'js',
contents: `export function spawn() { throw new Error('node-pty must not spawn') }`
}))
}
}
}
function inertPtyPlugin(): Plugin {
return {
name: 'session-host-inert-pty',
setup(bundle) {
bundle.onResolve({ filter: /^node-pty$/ }, () => ({
path: 'node-pty',
namespace: 'startup-failure'
}))
bundle.onLoad({ filter: /^node-pty$/, namespace: 'startup-failure' }, () => ({
loader: 'js',
contents: `export function spawn() { throw new Error('node-pty must not spawn') }`
}))
}
}
}
async function buildAndStartHost(
fixtureDir: string,
dataDir: string,
plugins: Plugin[]
): Promise<{ child: ChildProcess; bundlePath: string }> {
const bundlePath = path.join(fixtureDir, 'host.cjs')
await build({
absWorkingDir: process.cwd(),
entryPoints: ['src/session-host/host.ts'],
outfile: bundlePath,
bundle: true,
platform: 'node',
format: 'cjs',
plugins,
logLevel: 'silent'
})
return {
bundlePath,
child: spawn(process.execPath, [bundlePath, dataDir], {
cwd: process.cwd(),
stdio: 'ignore',
windowsHide: true
})
}
}
const cleanupPaths: string[] = []
afterEach(() => {
for (const target of cleanupPaths.splice(0)) rmSync(target, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 })
})
describe('session-host startup publication failure', () => {
it('exits nonzero and leaves no listener, token, or startup lock behind', async () => {
const fixtureDir = mkdtempSync(path.join(os.tmpdir(), 'nt-session-host-process-'))
cleanupPaths.push(fixtureDir)
const dataDir = path.join(fixtureDir, 'user-data')
mkdirSync(dataDir)
const paths = sessionHostPaths(dataDir)
if (process.platform !== 'win32') cleanupPaths.push(paths.endpoint)
const { child } = await buildAndStartHost(fixtureDir, dataDir, [failureInjectionPlugin()])
const outcome = await waitForExit(child, 5_000)
expect(outcome.timedOut).toBe(false)
expect(outcome.signal).toBeNull()
expect(outcome.code).not.toBeNull()
expect(outcome.code).not.toBe(0)
expect(existsSync(paths.statePath)).toBe(false)
expect(existsSync(paths.tokenPath)).toBe(false)
await expect(endpointAcceptsConnections(paths.endpoint)).resolves.toBe(false)
}, 15_000)
})
describe('session-host startup ownership reads', () => {
it('does not reclaim a corrupt state file as though it were absent', async () => {
const fixtureDir = mkdtempSync(path.join(os.tmpdir(), 'nt-session-host-corrupt-state-'))
cleanupPaths.push(fixtureDir)
const dataDir = path.join(fixtureDir, 'user-data')
mkdirSync(dataDir)
const paths = sessionHostPaths(dataDir)
if (process.platform !== 'win32') cleanupPaths.push(paths.endpoint)
const original = '{broken ownership state'
writeFileSync(paths.statePath, original)
const { child } = await buildAndStartHost(fixtureDir, dataDir, [inertPtyPlugin()])
const outcome = await waitForExit(child, 5_000)
expect(outcome.timedOut).toBe(false)
expect(outcome.code).not.toBe(0)
expect(readFileSync(paths.statePath, 'utf8')).toBe(original)
await expect(endpointAcceptsConnections(paths.endpoint)).resolves.toBe(false)
}, 15_000)
it('does not reclaim valid ownership whose token is empty/unreadable', async () => {
const fixtureDir = mkdtempSync(path.join(os.tmpdir(), 'nt-session-host-empty-token-'))
cleanupPaths.push(fixtureDir)
const dataDir = path.join(fixtureDir, 'user-data')
mkdirSync(dataDir)
const paths = sessionHostPaths(dataDir)
if (process.platform !== 'win32') cleanupPaths.push(paths.endpoint)
const state = JSON.stringify({
pid: 42,
endpoint: paths.endpoint,
tokenPath: paths.tokenPath,
startedAt: 1234,
protocolVersion: SESSION_HOST_PROTOCOL_VERSION
})
writeFileSync(paths.statePath, state)
writeFileSync(paths.tokenPath, '')
const { child } = await buildAndStartHost(fixtureDir, dataDir, [inertPtyPlugin()])
const outcome = await waitForExit(child, 5_000)
expect(outcome.timedOut).toBe(false)
expect(outcome.code).not.toBe(0)
expect(readFileSync(paths.statePath, 'utf8')).toBe(state)
expect(readFileSync(paths.tokenPath, 'utf8')).toBe('')
await expect(endpointAcceptsConnections(paths.endpoint)).resolves.toBe(false)
}, 15_000)
it('leaves a directory occupying the ownership path untouched', async () => {
const fixtureDir = mkdtempSync(path.join(os.tmpdir(), 'nt-session-host-state-dir-'))
cleanupPaths.push(fixtureDir)
const dataDir = path.join(fixtureDir, 'user-data')
mkdirSync(dataDir)
const paths = sessionHostPaths(dataDir)
if (process.platform !== 'win32') cleanupPaths.push(paths.endpoint)
mkdirSync(paths.statePath)
const { child } = await buildAndStartHost(fixtureDir, dataDir, [inertPtyPlugin()])
const outcome = await waitForExit(child, 5_000)
expect(outcome.timedOut).toBe(false)
expect(outcome.code).not.toBe(0)
expect(statSync(paths.statePath).isDirectory()).toBe(true)
await expect(endpointAcceptsConnections(paths.endpoint)).resolves.toBe(false)
}, 15_000)
})
/** Poll until `check` is true, or fail after `budgetMs`. */
async function waitUntil(check: () => boolean, budgetMs: number, what: string): Promise<void> {
const deadline = Date.now() + budgetMs
while (Date.now() < deadline) {
if (check()) return
await new Promise((r) => setTimeout(r, 100))
}
throw new Error(`timed out waiting for ${what}`)
}
const publishedState = (statePath: string): boolean =>
existsSync(statePath) && statSync(statePath).size > 0
describe('session-host startup lock liveness (issue #783)', () => {
it('reclaims an EMPTY lock nothing has touched — the host that died mid-startup', async () => {
// Before this, the fail-closed reader could only say "file is empty" about such a lock, so the
// probe threw on all 10 attempts and every later launch exited fatally. The app then could not
// start a terminal again until someone deleted the file by hand.
const fixtureDir = mkdtempSync(path.join(os.tmpdir(), 'nt-session-host-abandoned-lock-'))
cleanupPaths.push(fixtureDir)
const dataDir = path.join(fixtureDir, 'user-data')
mkdirSync(dataDir)
const paths = sessionHostPaths(dataDir)
if (process.platform !== 'win32') cleanupPaths.push(paths.endpoint)
writeFileSync(paths.statePath, '')
const longAgo = new Date(Date.now() - 60_000)
utimesSync(paths.statePath, longAgo, longAgo)
const { child } = await buildAndStartHost(fixtureDir, dataDir, [inertPtyPlugin()])
try {
await waitUntil(() => publishedState(paths.statePath), 10_000, 'the host to publish its state')
const state = JSON.parse(readFileSync(paths.statePath, 'utf8'))
expect(state.endpoint).toBe(paths.endpoint)
await expect(endpointAcceptsConnections(paths.endpoint)).resolves.toBe(true)
} finally {
child.kill()
}
}, 30_000)
it('still refuses a FRESH empty lock — another host may be seconds from publishing', async () => {
const fixtureDir = mkdtempSync(path.join(os.tmpdir(), 'nt-session-host-fresh-lock-'))
cleanupPaths.push(fixtureDir)
const dataDir = path.join(fixtureDir, 'user-data')
mkdirSync(dataDir)
const paths = sessionHostPaths(dataDir)
if (process.platform !== 'win32') cleanupPaths.push(paths.endpoint)
writeFileSync(paths.statePath, '')
const { child } = await buildAndStartHost(fixtureDir, dataDir, [inertPtyPlugin()])
const outcome = await waitForExit(child, 15_000)
expect(outcome.timedOut).toBe(false)
expect(outcome.code).not.toBe(0)
// The lock is left exactly as found: it is not ours to delete.
expect(existsSync(paths.statePath)).toBe(true)
expect(statSync(paths.statePath).size).toBe(0)
await expect(endpointAcceptsConnections(paths.endpoint)).resolves.toBe(false)
}, 30_000)
// Occupying the endpoint differs per platform, the failure does not: `listen` answers
// EADDRINUSE and the host must wait rather than die. On Windows that is another server holding
// the named pipe — the shape #783 actually hit, where the killed host's pipe stayed busy for
// ~1.5 min. On POSIX a squatting server would NOT reproduce it (the host unlinks a stale socket
// path before binding), so a DIRECTORY takes the path instead: the unlink fails, and listen
// answers EADDRINUSE just the same.
const occupyEndpoint = async (endpoint: string): Promise<() => Promise<void>> => {
if (process.platform === 'win32') {
const squatter = net.createServer()
await new Promise<void>((resolve, reject) => {
squatter.once('error', reject)
squatter.listen(endpoint, () => resolve())
})
return () => new Promise<void>((resolve) => squatter.close(() => resolve()))
}
mkdirSync(endpoint, { recursive: true })
return async () => rmSync(endpoint, { recursive: true, force: true })
}
it('waits out an endpoint someone else still holds, instead of dying on it', async () => {
const fixtureDir = mkdtempSync(path.join(os.tmpdir(), 'nt-session-host-busy-endpoint-'))
cleanupPaths.push(fixtureDir)
const dataDir = path.join(fixtureDir, 'user-data')
mkdirSync(dataDir)
const paths = sessionHostPaths(dataDir)
if (process.platform !== 'win32') cleanupPaths.push(paths.endpoint)
const release = await occupyEndpoint(paths.endpoint)
const { child } = await buildAndStartHost(fixtureDir, dataDir, [inertPtyPlugin()])
try {
// Alive, lock held and empty, and its mtime moving: the heartbeat is what tells other
// launches (and the client) that this is a live starter rather than a corpse.
//
// `exitCode` is the load-bearing assertion. The first version of this retry unref'd its
// timer, so with `listen` failed the server held no handle, the event loop emptied, and the
// host exited 0 while its log still said it was retrying — a silent no-retry.
await waitUntil(() => existsSync(paths.statePath), 10_000, 'the startup lock')
const firstTouch = statSync(paths.statePath).mtimeMs
await new Promise((r) => setTimeout(r, 3_000))
expect(child.exitCode).toBeNull()
expect(statSync(paths.statePath).size).toBe(0)
expect(statSync(paths.statePath).mtimeMs).toBeGreaterThan(firstTouch)
// Release it: the host must take the endpoint without being restarted.
await release()
await waitUntil(() => publishedState(paths.statePath), 20_000, 'the host to bind and publish')
await expect(endpointAcceptsConnections(paths.endpoint)).resolves.toBe(true)
} finally {
child.kill()
await release().catch(() => undefined)
}
}, 60_000)
})