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 type { Socket } from 'net'
import { createHash, randomUUID } from 'crypto'
import * as pty from 'node-pty'
import { TerminalEmulator } from './terminal-emulator'
import { CwdReportScanner } from './cwd-report'
import { windowsConptySpawnOptions } from '../core/windows-conpty-dll'
import type {
CaptureVisibleResult,
ExecuteLaunchResult,
SessionHostShellDialect,
SessionHostSpawnOptions
} from './protocol'
const MAX_LAUNCH_LEDGER_ENTRIES = 256
const SHELL_QUIET_MS = 200
const SHELL_QUIET_CAP_MS = 1_500
const POST_LAUNCH_READY_CAP_MS = 5_000
const LAUNCH_READINESS_POLL_MS = 100
const VERIFY_TIMEOUT_MS = 2_000
const ECHO_EDGE_CHARS = 24
const DELIVERY_ATTEMPTS = 3
import {
KILL_LINE,
WINDOWS_KILL_LINE,
shellKillLineSequence
} from '../shared/shell-kill-line'
export { KILL_LINE, WINDOWS_KILL_LINE, shellKillLineSequence }
const UUID_V4 = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
// eslint-disable-next-line no-control-regex
const ESC_SEQ = /\x1b\[[0-9;?]*[ -/]*[@-~]|\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)|\x1b[@-_]/g
function cleanEcho(chunk: string): string {
// eslint-disable-next-line no-control-regex
return chunk.replace(ESC_SEQ, '').replace(/[\r\n]/g, '')
}
interface LaunchLedgerEntry {
fingerprint: string
outcome: Promise<{ ok: true } | { ok: false }>
}
interface HostSessionOverrides {
proc?: pty.IPty
term?: TerminalEmulator
}
function launchFingerprint(command: string, stdinAfterStart: string | undefined): string {
const hash = createHash('sha256')
hash.update(command, 'utf8')
hash.update('\0', 'utf8')
if (stdinAfterStart !== undefined) hash.update(stdinAfterStart, 'utf8')
return hash.digest('hex')
}
function replacementAttachFingerprint(
spawn: SessionHostSpawnOptions,
scrollback: number
): string {
const canonical = {
cwd: spawn.cwd,
shell: spawn.shell,
args: [...spawn.args],
env: Object.fromEntries(Object.entries(spawn.env).sort(([a], [b]) => a.localeCompare(b))),
cols: spawn.cols,
rows: spawn.rows,
launchDialect: spawn.launchDialect ?? null,
initialLaunch: spawn.initialLaunch ?? null,
scrollback
}
return createHash('sha256').update(JSON.stringify(canonical), 'utf8').digest('hex')
}
/** Pause before the asynchronous headless terminal retains more than this many queued UTF-8
* bytes. node-pty can still have a bounded amount already in flight, but it cannot keep feeding an
* unbounded promise chain while xterm is behind. */
export const SESSION_EMULATOR_OUTPUT_HIGH_WATER_BYTES = 4 * 1024 * 1024
/** Resume only after the queued emulator tail drains this far, leaving hysteresis so a producer
* hovering around the high-water boundary cannot chatter node-pty's global pause actuator. */
export const SESSION_EMULATOR_OUTPUT_LOW_WATER_BYTES = 1 * 1024 * 1024
interface Geometry {
cols: number
rows: number
}
interface HostSessionOverrides {
proc?: pty.IPty
term?: TerminalEmulator
}
interface AttachmentState {
geometry?: Geometry
explicitPaused: boolean
subscribed: boolean
watching: boolean
}
/** A warm attach must temporarily claim geometry and (on reconnect) restore its explicit pause
* before reading a screen. The transaction makes a failed/retried attach restore only its own
* prior socket state instead of leaking a claim or erasing an already-live duplicate attach. */
export interface PreparedHostAttachment {
isCurrent(): boolean
/** False means a concurrent detach/close cancelled this exact socket+name transaction. */
commit(): boolean
rollback(): Promise<void>
}
function normalizedGeometry(cols: number, rows: number): Geometry {
if (
!Number.isInteger(cols) ||
!Number.isFinite(cols) ||
cols <= 0 ||
!Number.isInteger(rows) ||
!Number.isFinite(rows) ||
rows <= 0
) {
throw new Error('terminal geometry must use finite positive integer cols and rows')
}
return { cols, rows }
}
/**
* One persisted session, owned by the host process for as long as it lives — this is the
* Windows-and-anywhere-else-tmux-is-missing analogue of a tmux session: it survives every
* connecting client detaching, and outlives the app that spawned it.
*/
export class HostSession {
readonly name: string
/** Opaque identity for this exact process generation. Same-name replacement gets a new value. */
readonly generation = randomUUID()
readonly launchDialect?: SessionHostShellDialect
readonly shellExecutableName: string
/** Operation that created this generation after consuming a replacement lease. Retained only
* with the live generation so a lost attach reply can be replayed idempotently with that token. */
readonly createdByReplacementToken?: string
private readonly replacementFingerprint: string
readonly proc: pty.IPty
private readonly term: TerminalEmulator
/** The tail of every emulator mutation accepted so far. `@xterm/headless` applies writes
* asynchronously, so warm attach/capture/resize/exit all cross this barrier. Rejections heal the
* shared tail while the individual recordOutput caller still observes its own failure. */
private outputTail: Promise<void> = Promise.resolve()
private queuedOutputBytes = 0
/** Explicit protocol flow and named-pipe transport flow drain independently. Collapsing them by
* socket lets a `drain` event cancel a renderer pause that is still owed. */
private readonly explicitPauseOwners = new Set<Socket>()
private readonly transportPauseOwners = new Set<Socket>()
/** The emulator queue is session-global, not owned by a connection. */
private emulatorPauseOwner = false
/** Each app connection contributes one componentwise geometry claim. The effective PTY size is
* the minimum across live claims so every viewer fits; removing the smallest claim grows it. */
private readonly geometryClaims = new Map<Socket, Geometry>()
/** Subscribed connections attached in `watch` mode (`watch-attach` feature): they receive output
* but hold NO geometry claim, so a relay viewer can never size the pty. A claim-
* carrying attach on the same connection takes it out of this set again. */
private readonly watchers = new Set<Socket>()
/** The cwd the pane last REPORTED in its output (OSC 7 / 9;9 / 633 — see cwd-report.ts). Null
* until one arrives; deliberately never seeded with the spawn cwd. */
private reportedCwd: string | null = null
private readonly cwdScanner = new CwdReportScanner()
/** A detach/close increments the socket epoch before clearing state. A delayed prepare/rollback
* from the prior epoch can then observe cancellation instead of resurrecting a ghost socket. */
private readonly attachmentEpochs = new WeakMap<Socket, number>()
private appliedGeometry: Geometry
/** Told every time the pty is actually resized — the host pushes it to the connections that
* negotiated the `geometry` feature, so each viewer can render the size the pty really has
* instead of the one it asked for (issue #914). Called inside the emulator tail, after both
* actuators succeeded; it must not throw back into it. */
onGeometryApplied?: (geometry: Geometry) => void
/** The size the pty runs at right now. */
get geometry(): Geometry {
return { ...this.appliedGeometry }
}
/** Consecutive callers asking for the same effective target share one acknowledgement. If that
* actuator attempt fails, every waiter sees the failure; a later exact retry starts a new one. */
private pendingGeometry: { key: string; promise: Promise<void> } | null = null
/** Sockets currently receiving `data`/`exit` push frames for this session — the same "N
* subscribers, one underlying process" shape `pty-manager.ts` already implements for tmux
* co-attach, one level further down the stack. */
readonly subscribers = new Set<Socket>()
readonly createdAt = Date.now()
/** When the pty last produced output (epoch ms) — the session reaper's idleness clock, reported
* by `listSessions` to `sessionDetails` connections. Starts at creation, like tmux's
* `window_activity`; host.ts stamps it on every pty `data` callback and nothing else moves it. */
lastOutputAt = this.createdAt
/** Set once, by whichever path (natural pty exit or an explicit `killSession`) ends this
* session first — guards against double-dispose/double-broadcast when both could race. */
exited = false
/** Generation-local exactly-once ledger. Promise insertion happens before command delivery, so
* another app process repeating a launch whose first reply was lost observes the same result. */
private readonly launchLedger = new Map<string, LaunchLedgerEntry>()
/** Different launch ids must not type over one another in the same interactive prompt. */
private launchQueue: Promise<void> = Promise.resolve()
/** While trusted private input is being echo-verified, host.ts must neither broadcast it nor
* write it into the reconstructable emulator screen. */
private privateLaunchOutput = false
get suppressingPrivateLaunchOutput(): boolean {
return this.privateLaunchOutput
}
get killLineSequence(): string {
return shellKillLineSequence(this.launchDialect, this.shellExecutableName)
}
/** True once a successful explicit kill has claimed the name but before node-pty proves process
* death with onExit. Same-name attach waits behind `ending` instead of joining this generation. */
retiring = false
/** Shared completion for the natural-exit / explicit-kill race. A second caller waits for the
* first caller's output drain instead of acknowledging while teardown is still in flight. */
ending: Promise<void> | null = null
private processExitCode: number | null = null
private readonly processExit: Promise<number>
private resolveProcessExit!: (exitCode: number) => void
constructor(
name: string,
spawn: SessionHostSpawnOptions,
scrollback: number,
createdByReplacementTokenOrOverrides?: string | HostSessionOverrides,
maybeOverrides?: HostSessionOverrides
) {
const createdByReplacementToken =
typeof createdByReplacementTokenOrOverrides === 'string'
? createdByReplacementTokenOrOverrides
: undefined
const overrides =
typeof createdByReplacementTokenOrOverrides === 'object'
? createdByReplacementTokenOrOverrides
: maybeOverrides
this.name = name
this.launchDialect = spawn.launchDialect
this.shellExecutableName = (spawn.shell.replace(/\\/g, '/').split('/').pop() ?? '').toLowerCase()
this.createdByReplacementToken = createdByReplacementToken
this.replacementFingerprint = replacementAttachFingerprint(spawn, scrollback)
this.processExit = new Promise<number>((resolve) => {
this.resolveProcessExit = resolve
})
this.appliedGeometry = normalizedGeometry(spawn.cols, spawn.rows)
this.proc =
overrides?.proc ??
pty.spawn(spawn.shell, spawn.args, {
name: 'xterm-256color',
cols: this.appliedGeometry.cols,
rows: this.appliedGeometry.rows,
cwd: spawn.cwd,
env: spawn.env,
// Win32: node-pty's bundled ConPTY when it is installed (mouse + alt-screen modes reach
// the emulator on Windows 10). `{}` everywhere else — byte-identical options.
...windowsConptySpawnOptions()
})
this.term =
overrides?.term ??
new TerminalEmulator({
cols: this.appliedGeometry.cols,
rows: this.appliedGeometry.rows,
scrollback
})
}
/** Queue one PTY-output chunk into the headless emulator, preserving arrival order and bounding
* the retained byte tail. Accounting happens before chaining because promises not yet started
* still retain their chunk strings and therefore count against the memory bound. */
recordOutput(data: string): Promise<void> {
const bytes = Buffer.byteLength(data, 'utf8')
this.queuedOutputBytes += bytes
if (this.queuedOutputBytes >= SESSION_EMULATOR_OUTPUT_HIGH_WATER_BYTES) {
this.setEmulatorPause(true)
}
const applied = this.outputTail.then(() => this.term.write(data))
const settled = applied.finally(() => {
this.queuedOutputBytes = Math.max(0, this.queuedOutputBytes - bytes)
if (this.queuedOutputBytes <= SESSION_EMULATOR_OUTPUT_LOW_WATER_BYTES) {
this.setEmulatorPause(false)
}
})
this.outputTail = settled.catch(() => {})
return settled
}
/** Scan one PTY-output chunk for a cwd report. Synchronous and independent of the emulator queue:
* it is called for every chunk, including private launch echo (a cwd is not launch material). */
noteOutput(data: string): void {
const cwd = this.cwdScanner.push(data)
if (cwd !== undefined) this.reportedCwd = cwd
}
/** `paneCwd`: the last REPORTED cwd, or null when the pane never reported one. */
get paneCwd(): string | null {
return this.reportedCwd
}
/** Is this connection subscribed in watch mode (no geometry claim)? */
isWatching(socket: Socket): boolean {
return this.watchers.has(socket)
}
/** The visible-screen keyframe, behind the same output barrier as `serialize`. */
async captureVisible(): Promise<CaptureVisibleResult> {
await this.outputTail
return this.term.captureVisible()
}
/** Wait until every PTY-output chunk observed before this call has reached xterm. */
settleOutput(): Promise<void> {
return this.outputTail
}
/** Record the one authoritative process-death observation. A kill syscall returning is not this
* event; only node-pty's onExit resolves the barrier and permits retirement acknowledgement. */
observeProcessExit(exitCode: number): void {
if (this.processExitCode !== null) return
this.processExitCode = exitCode
this.exited = true
this.resolveProcessExit(exitCode)
}
waitForProcessExit(): Promise<number> {
return this.processExit
}
/** Serialize only after prior asynchronous writes and geometry changes have landed. */
async serialize(scrollback?: number): Promise<string> {
await this.outputTail
return this.term.serialize(scrollback)
}
/**
* Has the app in this pane requested bracketed paste? Behind `outputTail` for the same reason
* `serialize` is: xterm applies writes asynchronously, so a mode set by output we have already
* observed is not in `modes` yet. Reading it early answers "no" for the turn that just enabled
* it — which is exactly the injected-prompt delivery this gates (see send-keys-delivery.ts).
*/
async bracketedPasteRequested(): Promise<boolean> {
await this.outputTail
return this.term.bracketedPasteRequested()
}
/** The pane app's mouse-tracking protocol, behind `outputTail` for the same reason. */
async mouseTrackingMode(): Promise<'none' | 'x10' | 'vt200' | 'drag' | 'any'> {
await this.outputTail
return this.term.mouseTrackingMode()
}
/** Agent messaging's stricter form of the same read: the pane must also still be alive and not
* inside a private launch, because the envelope is only ever written as a framed paste. */
async messagePasteReady(): Promise<boolean> {
await this.outputTail
return !this.exited && !this.suppressingPrivateLaunchOutput && this.term.bracketedPasteRequested()
}
/** Stage an attach's explicit flow state and per-socket geometry before the warm screen barrier.
* The returned commit is the only operation that activates live delivery. */
async prepareAttachment(
socket: Socket,
cols: number,
rows: number,
paused: boolean
): Promise<PreparedHostAttachment> {
return this.stageAttachment(socket, normalizedGeometry(cols, rows), paused)
}
/** `watch-attach`: the same transaction with NO geometry claim. A connection that held one gives
* it up (its last voting subscriber left), and the pty's size is re-derived from the remaining
* claims — with none left it keeps the size it has. Never spawns: callers reach this only for an
* existing generation. Any explicit pause the connection held is returned. */
prepareWatchAttachment(socket: Socket): Promise<PreparedHostAttachment> {
// Never paused: a viewer holds no flow ticket on the shared pty (see `pauseFor`).
return this.stageAttachment(socket, null, false)
}
private async stageAttachment(
socket: Socket,
claim: Geometry | null,
paused: boolean
): Promise<PreparedHostAttachment> {
const epoch = (this.attachmentEpochs.get(socket) ?? 0) + 1
this.attachmentEpochs.set(socket, epoch)
const previous: AttachmentState = {
geometry: this.geometryClaims.get(socket),
explicitPaused: this.explicitPauseOwners.has(socket),
subscribed: this.subscribers.has(socket),
watching: this.watchers.has(socket)
}
this.setSocketPauseOwner(this.explicitPauseOwners, socket, paused)
try {
if (claim) await this.setGeometryClaim(socket, claim.cols, claim.rows)
else if (this.geometryClaims.delete(socket)) await this.applyEffectiveGeometry()
} catch (error) {
await this.restoreAttachment(socket, previous, epoch)
throw error
}
let finished = false
return {
isCurrent: () => this.attachmentEpochs.get(socket) === epoch && !socket.destroyed,
commit: () => {
if (finished) return false
finished = true
if (this.attachmentEpochs.get(socket) !== epoch || socket.destroyed) return false
this.subscribers.add(socket)
if (claim) this.watchers.delete(socket)
else this.watchers.add(socket)
// A response written before this attach may already have filled the socket. The new
// session must inherit that socket-wide transport ticket before any live frame can add to
// the same queue.
if (socket.writableNeedDrain) this.setSocketPauseOwner(this.transportPauseOwners, socket, true)
return true
},
rollback: async () => {
if (finished) return
finished = true
await this.restoreAttachment(socket, previous, epoch)
}
}
}
/** Warm no-spawn attach used by a generation-checked reconnect. New clients carry their current
* aggregate geometry; older v2 clients safely reuse the generation's last applied size. */
prepareExistingAttachment(
socket: Socket,
paused: boolean,
cols?: number,
rows?: number
): Promise<PreparedHostAttachment> {
if ((cols === undefined) !== (rows === undefined)) {
throw new Error('existing attachment geometry requires both cols and rows')
}
const geometry =
cols === undefined || rows === undefined ? this.appliedGeometry : normalizedGeometry(cols, rows)
return this.prepareAttachment(socket, geometry.cols, geometry.rows, paused)
}
/** Update only the requesting subscriber's geometry claim. */
async resizeFor(socket: Socket, cols: number, rows: number): Promise<void> {
if (!this.subscribers.has(socket)) return
// A watch-mode connection has no claim to update, and must never acquire one by resizing.
if (this.watchers.has(socket)) throw new Error('a watch attachment cannot resize the terminal')
await this.setGeometryClaim(socket, cols, rows)
}
pauseFor(socket: Socket): void {
if (!this.subscribers.has(socket)) return
// A viewer never slows the owner's terminal: a watch-mode connection takes no pause ticket.
if (this.watchers.has(socket)) return
this.setSocketPauseOwner(this.explicitPauseOwners, socket, true)
}
resumeFor(socket: Socket): void {
if (!this.subscribers.has(socket)) return
this.setSocketPauseOwner(this.explicitPauseOwners, socket, false)
}
pauseTransportFor(socket: Socket): void {
if (!this.subscribers.has(socket)) return
this.setSocketPauseOwner(this.transportPauseOwners, socket, true)
}
resumeTransportFor(socket: Socket): void {
this.setSocketPauseOwner(this.transportPauseOwners, socket, false)
}
/** A protocol detach and a transport close mean the same thing for ownership: this socket can
* never return either flow ticket or its geometry claim, so release all three unconditionally. */
async detach(socket: Socket): Promise<void> {
this.attachmentEpochs.set(socket, (this.attachmentEpochs.get(socket) ?? 0) + 1)
const wasPaused = this.hasPauseOwner()
this.subscribers.delete(socket)
this.watchers.delete(socket)
this.explicitPauseOwners.delete(socket)
this.transportPauseOwners.delete(socket)
this.reconcileProcFlow(wasPaused)
if (!this.geometryClaims.delete(socket)) return
await this.applyEffectiveGeometry()
}
async executeInitialLaunch(
spawn: SessionHostSpawnOptions,
readinessProbe?: () => Promise<boolean>
): Promise<ExecuteLaunchResult | undefined> {
const initial = spawn.initialLaunch
if (!initial) return undefined
return this.executeLaunch(
initial.launchId,
initial.command,
initial.stdinAfterStart,
readinessProbe
)
}
matchesReplacementReplay(spawn: SessionHostSpawnOptions, scrollback: number): boolean {
return this.replacementFingerprint === replacementAttachFingerprint(spawn, scrollback)
}
dispose(): void {
this.explicitPauseOwners.clear()
this.transportPauseOwners.clear()
this.emulatorPauseOwner = false
this.geometryClaims.clear()
this.watchers.clear()
this.term.dispose()
}
async executeLaunch(
launchId: string,
command: string,
stdinAfterStart?: string,
readinessProbe?: () => Promise<boolean>
): Promise<ExecuteLaunchResult> {
if (!this.launchDialect) {
throw new Error('session-host terminal has no trusted launch dialect')
}
if (!UUID_V4.test(launchId)) throw new Error('session-host launch id is invalid')
if (!command || command.length > 128 * 1024 || command.includes('\0')) {
throw new Error('session-host launch input is invalid')
}
if (
stdinAfterStart !== undefined &&
(stdinAfterStart.length > 1024 * 1024 || stdinAfterStart.includes('\0'))
) {
throw new Error('session-host launch follow-up input is invalid')
}
const fingerprint = launchFingerprint(command, stdinAfterStart)
const existing = this.launchLedger.get(launchId)
if (existing) {
if (existing.fingerprint !== fingerprint) {
throw new Error('session-host launch id was reused with different input')
}
const outcome = await existing.outcome
if (!outcome.ok) throw new Error('session-host launch delivery previously failed')
return { status: 'already-executed' }
}
// Never evict within a live generation. Eviction would make an old lost-reply retry execute a
// second time; at the bounded cap, fail new ids closed until this generation ends.
if (this.launchLedger.size >= MAX_LAUNCH_LEDGER_ENTRIES) {
throw new Error('session-host launch ledger is full for this terminal generation')
}
const execution = this.launchQueue
.catch(() => {
// A failed older launch must not poison the serialization queue for a distinct id.
})
.then(() => this.deliverLaunch(command, stdinAfterStart, readinessProbe))
const outcome = execution.then(
() => ({ ok: true }) as const,
() => ({ ok: false }) as const
)
const entry: LaunchLedgerEntry = { fingerprint, outcome }
// Insert before the queued work can begin. This is the exactly-once commit point.
this.launchLedger.set(launchId, entry)
this.launchQueue = execution.catch(() => {})
const result = await outcome
if (!result.ok) throw new Error('session-host launch delivery failed')
return { status: 'executed' }
}
private async deliverLaunch(
command: string,
stdinAfterStart?: string,
readinessProbe?: () => Promise<boolean>
): Promise<void> {
await this.waitForOutputQuiet(SHELL_QUIET_CAP_MS)
await this.deliverVerifiedCommand(command)
if (stdinAfterStart !== undefined) {
// Time/quiet alone is not readiness: a short-lived failed agent can already have returned to
// the shell prompt. Require the host's process-tree probe to observe a non-shell descendant
// before literal follow-up input is allowed anywhere near the terminal.
if (!readinessProbe) throw new Error('session-host has no launch readiness probe')
await this.waitForLaunchReadiness(readinessProbe)
await this.waitForOutputQuiet(SHELL_QUIET_MS)
if (this.exited) throw new Error('session-host terminal exited during launch delivery')
try {
this.privateLaunchOutput = true
this.proc.write(stdinAfterStart)
this.proc.write('\r')
// Keep any asynchronous terminal echo private through one bounded settle window.
await this.waitForOutputQuiet(SHELL_QUIET_CAP_MS)
} catch {
throw new Error('session-host could not deliver launch follow-up input')
} finally {
this.privateLaunchOutput = false
}
}
}
private async waitForLaunchReadiness(probe: () => Promise<boolean>): Promise<void> {
const deadline = Date.now() + POST_LAUNCH_READY_CAP_MS
while (!this.exited && Date.now() < deadline) {
try {
if (await probe()) return
} catch {
// A failed read is uncertainty, never readiness. Keep polling within the fixed bound.
}
await new Promise<void>((resolve) => {
const timer = setTimeout(resolve, LAUNCH_READINESS_POLL_MS)
timer.unref?.()
})
}
if (this.exited) throw new Error('session-host terminal exited during launch delivery')
throw new Error('session-host could not confirm launched agent readiness')
}
private waitForOutputQuiet(capMs: number): Promise<void> {
if (this.exited) return Promise.reject(new Error('session-host terminal exited during launch delivery'))
return new Promise<void>((resolve, reject) => {
let done = false
let quietTimer: ReturnType<typeof setTimeout> | undefined
let dataSub: { dispose(): void } | undefined
let exitSub: { dispose(): void } | undefined
const capTimer = setTimeout(() => finish(), capMs)
capTimer.unref?.()
const cleanup = (): void => {
clearTimeout(capTimer)
if (quietTimer) clearTimeout(quietTimer)
dataSub?.dispose()
exitSub?.dispose()
}
const finish = (error?: Error): void => {
if (done) return
done = true
cleanup()
if (error) reject(error)
else resolve()
}
dataSub = this.proc.onData(() => {
if (quietTimer) clearTimeout(quietTimer)
quietTimer = setTimeout(() => finish(), SHELL_QUIET_MS)
quietTimer.unref?.()
})
exitSub = this.proc.onExit(() =>
finish(new Error('session-host terminal exited during launch delivery'))
)
})
}
private deliverVerifiedCommand(command: string): Promise<void> {
if (this.exited) return Promise.reject(new Error('session-host terminal exited during launch delivery'))
return new Promise<void>((resolve, reject) => {
this.privateLaunchOutput = true
let done = false
let attempt = 0
let echoed = ''
// The head is STICKY, because `echoed` below is a bounded window. A tail match is safe under
// that truncation by construction — the tail is what the window keeps — but a head is not:
// once a window's worth of bytes has arrived after it, the head is evicted and the two
// substrings need never coexist in the buffer even though both were genuinely echoed. This
// leg REFUSES on exhausted retries rather than failing open, so an evicted head would not
// merely retry, it would stop the node from starting.
let sawHead = false
let timer: ReturnType<typeof setTimeout> | undefined
let dataSub: { dispose(): void } | undefined
let exitSub: { dispose(): void } | undefined
const cleanup = (): void => {
if (timer) clearTimeout(timer)
dataSub?.dispose()
exitSub?.dispose()
}
const finish = (error?: Error): void => {
if (done) return
done = true
this.privateLaunchOutput = false
cleanup()
if (error) reject(error)
else resolve()
}
const write = (data: string): boolean => {
try {
this.proc.write(data)
return true
} catch {
finish(new Error('session-host could not deliver launch input'))
return false
}
}
const submit = (): void => {
if (!write('\r')) return
finish()
}
const tryOnce = (): void => {
if (done) return
attempt++
echoed = ''
sawHead = false
timer = setTimeout(() => {
if (done) return
if (attempt >= DELIVERY_ATTEMPTS) {
// Never submit an unverified/mangled command. Clear it so the terminal remains
// recoverable, cache the fixed failure, and let explicit user action decide next.
write(this.killLineSequence)
finish(new Error('session-host could not verify launch command delivery'))
return
}
if (!write(this.killLineSequence)) return
tryOnce()
}, VERIFY_TIMEOUT_MS)
timer.unref?.()
write(command)
}
dataSub = this.proc.onData((chunk) => {
if (done) return
// BOTH ends, not just the tail — see echoedIntact in the renderer's command-delivery for
// why a tail match let a head-truncated command through (#556), and why requiring the
// whole command contiguously would be too strict on this leg in particular: the retry
// exhaustion below REFUSES the launch rather than failing open.
const merged = echoed + cleanEcho(chunk)
// Tested BEFORE the window is trimmed, so a head that arrived in an earlier chunk still
// counts once it has scrolled out. Same memory bound as before.
sawHead ||= merged.includes(command.slice(0, ECHO_EDGE_CHARS))
echoed = merged.slice(-Math.max(command.length + 256, 512))
if (sawHead && echoed.includes(command.slice(-ECHO_EDGE_CHARS))) submit()
})
exitSub = this.proc.onExit(() =>
finish(new Error('session-host terminal exited during launch delivery'))
)
tryOnce()
})
}
/** Release node-pty's Windows ConPTY handle after the independently verified `/T /F` process
* tree termination. `WindowsTerminal.kill()` cannot be used here: node-pty defers that public
* method until the first output byte, so a valid silent process would keep its host-parented
* conhost alive forever. The internal agent call is the narrow upstream-compatible primitive
* that closes the ConPTY handle; the host still waits for this pty's real `onExit` before ack. */
releaseWindowsPtyAfterExternalTreeKill(): void {
if (process.platform !== 'win32') {
throw new Error('external ConPTY release is Windows-only')
}
const internal = this.proc as unknown as {
_close?: () => void
_agent?: { kill?: () => void }
}
if (typeof internal._close !== 'function' || typeof internal._agent?.kill !== 'function') {
throw new Error('installed node-pty does not expose the required ConPTY release primitive')
}
internal._close()
internal._agent.kill()
}
private async restoreAttachment(
socket: Socket,
previous: AttachmentState,
epoch: number
): Promise<void> {
if (this.attachmentEpochs.get(socket) !== epoch) return
const wasPaused = this.hasPauseOwner()
if (previous.explicitPaused) this.explicitPauseOwners.add(socket)
else this.explicitPauseOwners.delete(socket)
if (previous.subscribed) this.subscribers.add(socket)
else this.subscribers.delete(socket)
if (previous.watching) this.watchers.add(socket)
else this.watchers.delete(socket)
this.reconcileProcFlow(wasPaused)
if (previous.geometry) this.geometryClaims.set(socket, previous.geometry)
else this.geometryClaims.delete(socket)
await this.applyEffectiveGeometry()
}
private setGeometryClaim(socket: Socket, cols: number, rows: number): Promise<void> {
this.geometryClaims.set(socket, normalizedGeometry(cols, rows))
return this.applyEffectiveGeometry()
}
private applyEffectiveGeometry(): Promise<void> {
const requested = this.effectiveGeometry()
const key = requested ? `${requested.cols}x${requested.rows}` : 'unclaimed'
if (this.pendingGeometry?.key === key) return this.pendingGeometry.promise
// Recompute inside the serialized emulator tail, not when the request arrives. Concurrent
// resize/detach calls can change the claim ledger while an earlier xterm write is pending; a
// captured target would land stale after the newer operation. `appliedGeometry` advances only
// after both real actuators succeed, so identical waiters share a real failure and a later
// exact retry cannot false-no-op on a marker that never reached the terminal.
const reconciled = this.outputTail.then(() => {
const target = this.effectiveGeometry()
if (!target) return
if (
target.cols === this.appliedGeometry.cols &&
target.rows === this.appliedGeometry.rows
) {
return
}
this.proc.resize(target.cols, target.rows)
this.term.resize(target.cols, target.rows)
this.appliedGeometry = target
try {
this.onGeometryApplied?.({ ...target })
} catch {
// A notification failure must not turn a successful resize into a failed one.
}
})
const pending = { key, promise: reconciled }
this.pendingGeometry = pending
void reconciled.then(
() => {
if (this.pendingGeometry === pending) this.pendingGeometry = null
},
() => {
if (this.pendingGeometry === pending) this.pendingGeometry = null
}
)
this.outputTail = reconciled.catch(() => {})
return reconciled
}
private effectiveGeometry(): Geometry | null {
if (this.geometryClaims.size === 0) return null
let cols = Number.MAX_SAFE_INTEGER
let rows = Number.MAX_SAFE_INTEGER
for (const claim of this.geometryClaims.values()) {
cols = Math.min(cols, claim.cols)
rows = Math.min(rows, claim.rows)
}
return { cols, rows }
}
private hasPauseOwner(): boolean {
return (
this.emulatorPauseOwner ||
this.explicitPauseOwners.size > 0 ||
this.transportPauseOwners.size > 0
)
}
private setSocketPauseOwner(owners: Set<Socket>, socket: Socket, held: boolean): void {
const wasPaused = this.hasPauseOwner()
if (held) owners.add(socket)
else owners.delete(socket)
this.reconcileProcFlow(wasPaused)
}
private setEmulatorPause(held: boolean): void {
const wasPaused = this.hasPauseOwner()
this.emulatorPauseOwner = held
this.reconcileProcFlow(wasPaused)
}
private reconcileProcFlow(wasPaused: boolean): void {
const isPaused = this.hasPauseOwner()
if (wasPaused === isPaused) return
try {
if (isPaused) this.proc.pause()
else this.proc.resume()
} catch {
/* pty may have exited between the session lookup and the actuator call */
}
}
}