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 { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
import fs from 'fs'
import os from 'os'
import path from 'path'
import { initPlatform, resetPlatformForTests } from './platform'
import { fakePlatform, type FakePlatform } from './platform-fake'
import { IPC } from '../shared/ipc'
import { DEFAULT_SETTINGS } from '../shared/types'
import { TMUX_SOCKET, sessionName } from './tmux-naming'
import { REAP_IDLE_MS, REAP_SWEEP_MS } from './pty-reap'
import type { ControlSpawn } from './tmux-control-client'
import type { PtyDevices } from './pty-devices'
import {
setRemoteNodeTokenWriter,
forgetRemoteNodeTokens,
REMOTE_TOKEN_COALESCE_MS
} from './agents/node-token-service'
/**
* SHADOW CLIENTS: a tmux control-mode (`-C`) client over plain pipes, attached to the tmux session
* of a node whose PAINTER pty client has already been released — the idle reap's stranded ones, and
* the ones a plain `pty:kill` (last subscriber out, offscreen dispose) let go immediately. It holds
* ZERO pty devices, which is what lets a background feature reach a node nobody is watching without
* respawning a terminal (a pty device, a tmux client, an ssh child and a full redraw).
*
* Two invariants carry the whole design, and most of what follows asserts one of them:
* - a node never has a live painter AND a live shadow at the same time;
* - a shadow is INVISIBLE to everything that asks "is somebody watching" — the reap sweep (which
* decides against `platform().clientIds()`), the renderer's park and the 10-minute
* offscreen dispose. It is not a subscriber, not a `Session`, and not a renderer client id.
*/
/** One fake pty per spawn. `killed` is what a released client pty looks like from here. */
interface FakePty {
onDataCb?: (d: string) => void
onExitCb?: (e: { exitCode: number }) => void
killed: boolean
}
const spawned: FakePty[] = []
/** Spawn/dispose events across BOTH child kinds, so a test can assert their relative ORDER. */
const log: string[] = []
// Pin the persistence backend: `sessionHostSupported()` only asks whether
// out/session-host/host.cjs exists on disk, so whether this suite exercises the mocked
// `node-pty` spawn below or a real session-host shim depended on whether anyone had run
// `npm run build` (or `npm run host:build`). See src/core/__fixtures__/no-session-host.ts.
vi.mock('./session-host-backend', async () =>
(await import('./__fixtures__/no-session-host')).noSessionHost()
)
vi.mock('node-pty', () => ({
spawn: () => {
const p: FakePty = { killed: false }
spawned.push(p)
log.push('pty-spawn')
return {
onData: (cb: (d: string) => void) => {
p.onDataCb = cb
},
onExit: (cb: (e: { exitCode: number }) => void) => {
p.onExitCb = cb
},
write: () => {},
resize: () => {},
pause: () => {},
resume: () => {},
kill: () => {
p.killed = true
},
pid: 1
}
}
}))
/** Every tmux side-call goes through child_process; `liveTmuxSessions` answers `has-session`. */
const liveTmuxSessions = new Set<string>()
vi.mock('child_process', () => {
type Cb = (err: Error | null, res?: { stdout: string; stderr: string }) => void
const execFile = (file: string, args: string[], a?: unknown, b?: unknown): unknown => {
const cb = (typeof a === 'function' ? a : b) as Cb | undefined
const ok = (stdout: string): void => cb?.(null, { stdout, stderr: '' })
if (args.includes('has-session')) {
// Production asks with the EXACT form (`=nt-…`); tmux matches it against the bare name.
const raw = args[args.indexOf('-t') + 1]
const target = raw.startsWith('=') ? raw.slice(1).replace(/:$/, '') : raw
if (liveTmuxSessions.has(target)) ok('')
else cb?.(Object.assign(new Error('no such session'), { code: 1 }))
} else if (args[0] === '-ilc') {
ok('__NT_PATH_START__/usr/bin:/bin__NT_PATH_END__')
} else {
ok('')
}
return {}
}
return { execFile, execFileSync: (): string => '' }
})
/** One fake control-mode child per shadow: what was written to it, and whether it was killed. */
interface FakeControlChild {
writes: string[]
killed: number
exit(code: number | null): void
feed(latin1: string): void
}
/**
* The injected `ControlSpawn`. It answers commands like a healthy tmux does — ASYNCHRONOUSLY (a
* reply delivered inside the `write` call would arrive before the client had queued its resolver,
* which is not a thing the real protocol can do) — and `autoReply = false` plays the wedged tmux
* that takes a command and never answers.
*/
class FakeControlSpawn implements ControlSpawn {
calls: Array<{ bin: string; args: string[] }> = []
children: FakeControlChild[] = []
autoReply = true
/** `child_process.spawn` throws SYNCHRONOUSLY (EMFILE, a bad cwd) — this plays that. */
throwOnSpawn = false
private num = 0
spawn(bin: string, args: string[]) {
if (this.throwOnSpawn) throw new Error('spawn EMFILE')
this.calls.push({ bin, args })
log.push('control-spawn')
let onData: ((b: Buffer) => void) | undefined
let onExit: ((code: number | null) => void) | undefined
const child: FakeControlChild = {
writes: [],
killed: 0,
exit: (code) => onExit?.(code),
feed: (s) => onData?.(Buffer.from(s, 'latin1'))
}
this.children.push(child)
return {
stdin: {
write: (s: string) => {
child.writes.push(s)
// `detach-client` is the disposal handshake, not a command with a reply.
if (!this.autoReply || s.startsWith('detach-client')) return
const n = ++this.num
// A real microtask (not a timer): tests run under fake timers.
void Promise.resolve().then(() =>
child.feed(`%begin 1700 ${n} 0\n%end 1700 ${n} 0\n`)
)
}
},
stdout: {
on: (_ev: 'data', cb: (b: Buffer) => void) => {
onData = cb
}
},
on: (_ev: 'exit', cb: (code: number | null) => void) => {
onExit = cb
},
kill: () => {
child.killed++
log.push('control-kill')
}
}
}
get only(): FakeControlChild {
return this.children[0]
}
}
/**
* A machine with pty devices to spare by default.
*
* Without this the real probe runs a `readdir('/dev')` against the DEVELOPER's host, and
* `spawnSession`'s pre-flight refuses every create once that host is within `PTY_DEVICE_HEADROOM`
* of its own `kern.tty.ptmx_max` — which a machine running this app all day genuinely reaches (511
* on macOS; this one sits in the 480s). Settable, because one test below is about what a REFUSED
* create does to a shadow.
*/
const devices = vi.hoisted(() => ({ current: { ceiling: 511, inUse: 8 } as PtyDevices }))
vi.mock('./pty-devices', async (importOriginal) => ({
...(await importOriginal<typeof import('./pty-devices')>()),
readPtyDevices: () => devices.current
}))
const ALICE = 1
const BOB = 2
describe('control-mode shadow clients for released sessions', () => {
let fake: FakePlatform
let userDataDir: string
let control: FakeControlSpawn
beforeEach(() => {
spawned.length = 0
log.length = 0
devices.current = { ceiling: 511, inUse: 8 }
liveTmuxSessions.clear()
control = new FakeControlSpawn()
userDataDir = fs.mkdtempSync(path.join(os.tmpdir(), 'nt-shadow-'))
fake = fakePlatform({ userDataDir })
initPlatform(fake)
vi.useFakeTimers()
})
afterEach(() => {
vi.useRealTimers()
vi.restoreAllMocks()
resetPlatformForTests()
// Best effort, as in pty-idle-reap.test.ts: a fired-and-forgotten scrollback snapshot can still
// be landing here, and a cleanup that fails the suite is worse than a leftover dir.
try {
fs.rmSync(userDataDir, { recursive: true, force: true, maxRetries: 10, retryDelay: 20 })
} catch {
/* a temp dir we could not remove is not a test result */
}
})
/** A manager WITH init(): tmux-backed, which is what a real user always gets. */
async function tmuxManager() {
const { PtyManager } = await import('./pty-manager')
const m = new PtyManager({ controlSpawn: control })
m.init(() => DEFAULT_SETTINGS)
m.registerIpc()
return m
}
/** A manager WITHOUT init(): no tmux, so there is no tmux session to shadow. */
async function plainManager() {
const { PtyManager } = await import('./pty-manager')
const m = new PtyManager({ controlSpawn: control })
m.registerIpc()
return m
}
const create = (clientId: number, persistKey = 'node-1', cols = 80, rows = 24) =>
fake.handlers[IPC.ptyCreate](clientId, { cols, rows, persistKey }) as Promise<{
sessionId: string
fresh: boolean
}>
/** pty:kill is sender-aware: it unsubscribes ONE view, and the last one out releases the pty. */
const kill = (clientId: number, sessionId: string) =>
fake.senderListeners[IPC.ptyKill](clientId, sessionId)
/** Run the sweep past the idle threshold (it only decides on its own ticks). */
const idle = (ms = REAP_IDLE_MS + REAP_SWEEP_MS) => vi.advanceTimersByTime(ms)
// Exact (`=name`): a bare target prefix-matches a longer session when this one is gone.
const attachArgs = (key: string) => ['-L', TMUX_SOCKET, '-C', 'attach-session', '-t', `=${sessionName(key)}`]
it('shadows a session the reap stranded — over pipes, taking no pty device', async () => {
const m = await tmuxManager()
await create(ALICE) // …and Alice's window is then destroyed without a pty:kill ever arriving
idle()
expect(spawned[0].killed).toBe(true) // the sweep released her client pty
const shadow = await m.shadowAttach('node-1')
expect(shadow).not.toBeNull()
expect(control.calls).toEqual([{ bin: m.getTmuxBin(), args: attachArgs('node-1') }])
// The whole point: reaching the session cost no second pty.
expect(spawned).toHaveLength(1)
})
it('shadows a session released the instant its last subscriber left (the offscreen path)', async () => {
const m = await tmuxManager()
const { sessionId } = await create(ALICE)
kill(ALICE, sessionId) // offscreen dispose / node unmount: zero subscribers, released at once
expect(spawned[0].killed).toBe(true)
expect(await m.shadowAttach('node-1')).not.toBeNull()
expect(control.calls).toHaveLength(1)
})
it('refuses while the painter pty client is attached — never both at once', async () => {
const m = await tmuxManager()
await create(ALICE)
expect(await m.shadowAttach('node-1')).toBeNull()
expect(control.calls).toHaveLength(0)
})
it('leaves the shadow ALIVE when the create is refused for want of pty devices', async () => {
// The swap-out below retires the shadow to make way for an arriving painter. If a create that
// never spawns anything still ran it, a machine at its pty ceiling would silently kill the
// background client of every node it refused — and nothing re-attaches one (`shadowAttach` is
// driven by release/reap, not by a failed create), so the node would go dark until the user
// reopened it. Hence the pre-flight runs BEFORE the swap-out, not next to `pty.spawn`.
const m = await tmuxManager()
const { sessionId } = await create(ALICE)
kill(ALICE, sessionId)
const shadow = await m.shadowAttach('node-1')
expect(shadow).not.toBeNull()
devices.current = { ceiling: 511, inUse: 515 } // the machine fills up
await expect(create(ALICE)).rejects.toThrow(/out of pty devices/)
expect(control.only.killed).toBe(0) // not retired…
expect(await m.shadowAttach('node-1')).toBe(shadow) // …and still the live one, re-used
expect(control.calls).toHaveLength(1) // no second control client either
expect(spawned).toHaveLength(1) // and, of course, no second pty
})
it('re-uses a live shadow instead of spawning a second control client', async () => {
const m = await tmuxManager()
const { sessionId } = await create(ALICE)
kill(ALICE, sessionId)
const first = await m.shadowAttach('node-1')
const second = await m.shadowAttach('node-1')
expect(second).toBe(first)
expect(control.calls).toHaveLength(1)
})
it('re-asserts the size the painter last enforced — a control client sizes the pane', async () => {
const m = await tmuxManager()
const { sessionId } = await create(ALICE, 'node-1', 100, 30)
kill(ALICE, sessionId)
await m.shadowAttach('node-1')
// With only a control client attached the pane follows `refresh-client -C`; without this push
// the user would come back to a pane reflowed to somebody else's default.
expect(control.only.writes).toContain('refresh-client -C 100x30\n')
})
it('pushes no size when the released session never recorded one', async () => {
const m = await tmuxManager()
// A relay-served (detached) pty: its sink reports no size at create time, so this manager never
// enforced one. Pushing an invented size would reflow a pane that is perfectly fine.
const sessionId = m.attachDetached('node-1', { onData: () => {}, onExit: () => {} })
m.kill(null, sessionId)
await m.shadowAttach('node-1')
expect(control.only.writes.some((w) => w.startsWith('refresh-client'))).toBe(false)
})
it('is invisible to the reaper: not a watcher, and never swept up itself', async () => {
const m = await tmuxManager()
await create(ALICE, 'node-1')
idle()
await m.shadowAttach('node-1')
// A second node is opened and abandoned the same way. If the shadow had registered anywhere the
// sweep looks — a client id, a subscriber, a Session — it would show here: as a session that
// never becomes reapable, or as a shadow the sweep tore down.
await create(BOB, 'node-2')
idle()
expect(spawned[1].killed).toBe(true) // node-2 still reaps ⇒ clientIds() is unpolluted
expect(control.only.killed).toBe(0) // the sweep does not touch a shadow…
expect(control.calls).toHaveLength(1) // …and never attaches one either
})
it('disposes the shadow BEFORE spawning the painter when the node comes back', async () => {
const m = await tmuxManager()
const { sessionId } = await create(ALICE)
kill(ALICE, sessionId)
await m.shadowAttach('node-1')
liveTmuxSessions.add(sessionName('node-1')) // tmux kept it running, as it does across a detach
log.length = 0
await create(ALICE) // the node scrolls back into view / the user reopens the project
// Order is the assertion: the painter attaches with `-D` and would kick the shadow off anyway,
// but only after tmux has processed both attaches — so the shadow goes first, and exactly one
// client of ours is ever negotiating the pane.
expect(log).toEqual(['control-kill', 'pty-spawn'])
expect(control.only.writes).toContain('detach-client\n') // detached politely, then killed
expect(spawned[1].killed).toBe(false) // the painter is live and untouched
})
it('leaves the session alone when its shadow dies, and re-attaches lazily on the next ask', async () => {
const m = await tmuxManager()
await create(ALICE)
idle()
await m.shadowAttach('node-1')
control.children[0].exit(1) // the control client died on its own (tmux restart, OOM kill)
// Nothing is resurrected on its behalf — no pty, no session, no eager re-attach.
expect(spawned).toHaveLength(1)
expect(control.calls).toHaveLength(1)
const again = await m.shadowAttach('node-1')
expect(again).not.toBeNull()
expect(control.calls).toEqual([
{ bin: m.getTmuxBin(), args: attachArgs('node-1') },
{ bin: m.getTmuxBin(), args: attachArgs('node-1') }
])
})
it('disposes a shadow whose reply never comes — a lost reply desyncs the FIFO forever', async () => {
const { SHADOW_CMD_TIMEOUT_MS } = await import('./pty-manager')
const m = await tmuxManager()
const { sessionId } = await create(ALICE, 'node-1', 100, 30)
kill(ALICE, sessionId)
control.autoReply = false // tmux takes the command and never answers
const attaching = m.shadowAttach('node-1')
await vi.advanceTimersByTimeAsync(SHADOW_CMD_TIMEOUT_MS)
expect(await attaching).toBeNull()
expect(control.only.killed).toBe(1)
// …and the entry is gone, so the next ask gets a fresh client rather than a desynced one.
control.autoReply = true
expect(await m.shadowAttach('node-1')).not.toBeNull()
expect(control.calls).toHaveLength(2)
})
it('destroying a node takes its shadow with it — the tmux session is going away', async () => {
const m = await tmuxManager()
const { sessionId } = await create(ALICE)
kill(ALICE, sessionId)
await m.shadowAttach('node-1')
await m.destroySession(ALICE, 'node-1')
expect(control.only.killed).toBe(1)
})
it('app quit disposes every shadow', async () => {
const m = await tmuxManager()
const a = await create(ALICE, 'node-1')
const b = await create(BOB, 'node-2')
kill(ALICE, a.sessionId)
kill(BOB, b.sessionId)
await m.shadowAttach('node-1')
await m.shadowAttach('node-2')
await m.killAll()
expect(control.children.map((c) => c.killed)).toEqual([1, 1])
expect(control.children.every((c) => c.writes.includes('detach-client\n'))).toBe(true)
})
it('stays reapable by the SESSION BUDGET, which reads tmux’s own attached flag', async () => {
// The one attachment check a shadow really is visible to: `session-budget.ts` culls idle
// DETACHED `nt-*` sessions under memory pressure, and a held `-C attach` flips
// `#{session_attached}` to 1 — so a shadowed session would be permanently exempt from the
// memory-pressure safety valve. It runs in production from BOTH shells against this socket.
const { createSessionReaper } = await import('./session-budget')
const m = await tmuxManager()
const { sessionId } = await create(ALICE)
kill(ALICE, sessionId)
await m.shadowAttach('node-1')
const NOW = 1_000_000
const OLD = NOW - 100_000 // well past the 6h grace window: no PANE OUTPUT since then
// `#{session_activity}` stays FRESH, the shape a live host always has — the reaper gates on
// last pane output now, not on when a client last attached. See SessionInfo.activitySec.
const FRESH = NOW - 60
const listings: Record<string, string> = {
// `nt-node-1` reads as attached because our shadow IS a real tmux client; `nt-node-9` is a
// genuinely attached session (somebody is looking at it) and must survive.
'node-terminal': `nt-node-1|1|${FRESH}|${OLD}\nnt-node-9|1|${FRESH}|${OLD}`,
// The SAME NAME on the SSH-remote socket, attached for real. Shadows only ever live on the
// local socket, so the exclusion must not follow the name across sockets.
'nodeterm-rmt': `nt-node-1|1|${FRESH}|${OLD}`
}
const killed: Array<{ socket: string; target: string }> = []
const reaper = createSessionReaper({
tmuxBin: () => m.getTmuxBin(),
shadowed: (socket) => m.shadowedTmuxSessions(socket),
exec: async (_bin: string, args: string[]) => {
const socket = args[args.indexOf('-L') + 1]
if (args.includes('kill-session')) {
killed.push({ socket, target: args[args.indexOf('-t') + 1] })
return ''
}
return listings[socket] ?? ''
},
readMem: () => ({ availableMb: 100, totalMb: 8000 }), // under the watermark: real pressure
env: {},
nowSec: () => NOW
})
expect(await reaper.sweep()).toBe(1)
expect(killed).toEqual([{ socket: 'node-terminal', target: '=nt-node-1' }])
})
it('leaves a session somebody is really watching alone — the attached flag is a client COUNT', async () => {
// `#{session_attached}` counts clients. Subtracting our shadow by forcing the flag to false
// would report a session that has our shadow PLUS a real client — the user's own
// `tmux -L node-terminal attach`, or a second nodeterm process on the same socket — as
// detached, and the budget would then kill a session out from under a live user, inverting its
// one hard rule in the state-destroying direction. The shadow comes off the COUNT.
const { createSessionReaper } = await import('./session-budget')
const m = await tmuxManager()
const a = await create(ALICE, 'node-1')
const b = await create(BOB, 'node-2')
kill(ALICE, a.sessionId)
kill(BOB, b.sessionId)
await m.shadowAttach('node-1')
await m.shadowAttach('node-2')
const NOW = 1_000_000
const OLD = NOW - 100_000 // no PANE OUTPUT since then
const FRESH = NOW - 60 // …while `#{session_activity}` stays fresh, as it always is in production
const killed: string[] = []
let listings = 0
const reaper = createSessionReaper({
tmuxBin: () => m.getTmuxBin(),
sockets: ['node-terminal'],
shadowed: (socket) => m.shadowedTmuxSessions(socket),
exec: async (_bin: string, args: string[]) => {
if (args.includes('kill-session')) {
killed.push(args[args.indexOf('-t') + 1])
return ''
}
// nt-node-1 carries the user's own client the whole time (2 = theirs + ours), so the PLAN
// must never name it. nt-node-2 is shadow-only when the plan is made and gains a real
// client before the kill — precisely what the kill-time re-verify exists for.
const nodeTwo = listings++ === 0 ? 1 : 2
return `nt-node-1|2|${FRESH}|${OLD}\nnt-node-2|${nodeTwo}|${FRESH}|${OLD}`
},
readMem: () => ({ availableMb: 100, totalMb: 8000 }), // under the watermark: real pressure
env: {},
nowSec: () => NOW
})
expect(await reaper.sweep()).toBe(0)
expect(killed).toEqual([])
})
it('refuses a released REMOTE node — its tmux lives on the far host, not on our socket', async () => {
const m = await tmuxManager()
const res = (await fake.handlers[IPC.ptyCreate](ALICE, {
cols: 80,
rows: 24,
persistKey: 'node-r',
sshRemote: { conn: { host: 'h1', user: 'u' }, controlPath: '/tmp/cm', remoteCwd: '/srv/app' }
})) as { sessionId: string }
expect(m.sshRemoteForNode('node-r')).toBeDefined() // the spawn really did take the remote branch
kill(ALICE, res.sessionId)
// `nt-node-r` on OUR socket is either nothing at all or — worse — the local orphan a create
// issued with the master down once left behind. Neither is this node's session.
expect(await m.shadowAttach('node-r')).toBeNull()
expect(control.calls).toHaveLength(0)
})
it('materialises the spawning node token ON THE HOST (a node created after connect)', async () => {
// The connect writes a token for every node the canvas had THEN. Without this leg a node
// created afterwards has no token file on the host until the next reconnect — which for a
// long-lived SSH project is never — and spends that whole time on `legacy`.
const seen: [string, string[]][] = []
setRemoteNodeTokenWriter((controlPath, nodeIds) => seen.push([controlPath, [...nodeIds]]))
try {
await tmuxManager()
await fake.handlers[IPC.ptyCreate](ALICE, {
cols: 80,
rows: 24,
persistKey: 'node-r2',
sshRemote: { conn: { host: 'h1', user: 'u' }, controlPath: '/tmp/cm', remoteCwd: '/srv/app' }
})
// Coalesced: the spawn path collects a burst and writes once (REMOTE_TOKEN_COALESCE_MS).
// Fake timers are in force for this suite, so advance rather than wait.
await vi.advanceTimersByTimeAsync(REMOTE_TOKEN_COALESCE_MS + 20)
expect(seen).toEqual([['/tmp/cm', ['node-r2']]])
// ...and a LOCAL node never asks a host for anything.
seen.length = 0
await fake.handlers[IPC.ptyCreate](ALICE, { cols: 80, rows: 24, persistKey: 'node-local' })
expect(seen).toEqual([])
} finally {
setRemoteNodeTokenWriter(null)
forgetRemoteNodeTokens('/tmp/cm')
}
})
it('returns null (never rejects) when the control client cannot even be spawned', async () => {
const m = await tmuxManager()
const { sessionId } = await create(ALICE)
kill(ALICE, sessionId)
control.throwOnSpawn = true
expect(await m.shadowAttach('node-1')).toBeNull()
// …and no half-attached entry is left behind: the next ask spawns a real one.
control.throwOnSpawn = false
expect(await m.shadowAttach('node-1')).not.toBeNull()
expect(control.calls).toHaveLength(1)
})
it('keeps a shadow whose command was refused before anything was written', async () => {
const m = await tmuxManager()
const { sessionId } = await create(ALICE)
kill(ALICE, sessionId)
const shadow = await m.shadowAttach('node-1')
// A malformed line is refused CLIENT-side, before a byte is written, so the FIFO cannot have
// desynced — tearing the shadow (and its tmux client) down over it would be pure collateral.
expect(await m.shadowCommand('node-1', 'display-message -p x\nkill-server')).toBeNull()
expect(control.only.killed).toBe(0)
expect(await m.shadowAttach('node-1')).toBe(shadow)
})
it('does nothing with tmux switched off in settings — no session is tmux-backed', async () => {
const { PtyManager } = await import('./pty-manager')
const m = new PtyManager({ controlSpawn: control })
m.init(() => ({ ...DEFAULT_SETTINGS, tmuxEnabled: false }))
m.registerIpc()
const { sessionId } = await create(ALICE)
kill(ALICE, sessionId)
// The binary is right there, so `tmuxPath` alone would say yes — but nothing spawned a tmux
// session, so a shadow would attach to a name that does not exist and die on arrival.
expect(await m.shadowAttach('node-1')).toBeNull()
expect(control.calls).toHaveLength(0)
})
it('spawns nothing with ptyShadowClients switched off — the kill switch', async () => {
const { PtyManager } = await import('./pty-manager')
const m = new PtyManager({ controlSpawn: control })
m.init(() => ({ ...DEFAULT_SETTINGS, ptyShadowClients: false }))
m.registerIpc()
const { sessionId } = await create(ALICE)
kill(ALICE, sessionId)
// Everything else about this session is exactly as it is with the flag on: tmux is there, the
// session is released, the record is ours. The flag is the ONE reason nothing attaches, which
// is what makes "switch it off" a truthful instruction in a field report.
expect(await m.shadowAttach('node-1')).toBeNull()
expect(control.calls).toHaveLength(0)
})
it('logs one greppable line per swap direction', async () => {
const lines: string[] = []
vi.spyOn(console, 'log').mockImplementation((...a: unknown[]) => void lines.push(a.join(' ')))
const m = await tmuxManager()
const { sessionId } = await create(ALICE)
kill(ALICE, sessionId)
await m.shadowAttach('node-1')
await m.shadowAttach('node-1') // re-used, not re-attached — so no second line
expect(lines.filter((l) => l === `[pty] shadow attach ${sessionName('node-1')}`)).toHaveLength(1)
liveTmuxSessions.add(sessionName('node-1')) // tmux kept the session across the detach
await create(ALICE)
// The other direction. "My terminal came back blank" is answerable from these two lines alone:
// they name the session, the direction, and (by their order) which client held it when.
expect(lines.filter((l) => l === `[pty] painter attach ${sessionName('node-1')}`)).toHaveLength(
1
)
})
it('says nothing when a painter spawns with no control client to retire', async () => {
const lines: string[] = []
vi.spyOn(console, 'log').mockImplementation((...a: unknown[]) => void lines.push(a.join(' ')))
const m = await tmuxManager()
await create(ALICE) // the ordinary case: opening a terminal retires nothing
// One line per SWAP, not per terminal anyone ever opens: a log nobody can read is a log that
// answers no field report.
expect(lines.some((l) => l.startsWith('[pty] painter attach'))).toBe(false)
})
it('does nothing without tmux — there is no tmux session to shadow', async () => {
const m = await plainManager()
const { sessionId } = await create(ALICE)
kill(ALICE, sessionId)
expect(await m.shadowAttach('node-1')).toBeNull()
expect(control.calls).toHaveLength(0)
})
})