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 { elementOnScreen } from '../terminal/on-screen'
import { useContextEnsure } from '../terminal/useContextEnsure'
import { canPlainApprove, sendHeaderAnswer } from '../lib/approveGate'
import { isLocalOnSshCanvas } from '../lib/localOnSshCanvas'
import { FIND_DECORATIONS } from '../lib/palette'
import { ptyRefusal } from '@shared/pty-refusal'
import { patchImeModeSwitch } from '../terminal/ime-mode-switch'
import { installGlassCellBackgrounds, scheduleGlassCellAlpha, setGlassCellAlpha } from '../terminal/glass-cell-backgrounds'
import { deliverRelayInitialLaunch } from '../terminal/relay-initial-launch'
import { commitLaunch } from '../terminal/launch-attempt'
import { isLaunchShell } from '@shared/agents/pane'
import { createLaunchWriter, deliverInitialLaunch, launchCommand, registerLaunchWriter } from '../terminal/launch-command'
import { trustsFreshShell } from '@shared/launch-trust'
import { Suspense, lazy, useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react'
import { NODE_MIN_SIZES } from '../lib/nodeSizing'
import {
Handle,
NodeResizer,
Position,
useReactFlow,
useUpdateNodeInternals,
type NodeProps
} from '@xyflow/react'
import { Terminal } from '@xterm/xterm'
import { FitAddon } from '@xterm/addon-fit'
import { SearchAddon } from '@xterm/addon-search'
import { WebglAddon } from '@xterm/addon-webgl'
import { ChatPanelFallback } from './ChatPanelFallback'
// ChatPanel (the ⌘M transcript view) is code-split with the markdown renderer it uses: neither is
// on the path to painting a terminal, and both were in the startup chunk purely by being imported
// here. The fallback is the panel's own shell (`ChatPanelFallback`: bar + spinner + "Loading
// conversation…"), NOT null: a null fallback was chosen on the theory that the chunk arrives in a
// frame, but in use the ⌘M face sat blank long enough to be reported as broken (2026-09-26). The
// shell has the panel's exact geometry, so a fast load still reads as the panel appearing.
const ChatPanel = lazy(() => import('./ChatPanel').then((m) => ({ default: m.ChatPanel })))
import { LocalTransport } from '../terminal/local-transport'
import {
clipboardImages,
dropDialect,
droppedPaths,
pasteHasText,
pastedFiles,
type DropDialect
} from '../terminal/file-drop'
import type { TerminalTransport } from '../terminal/transport'
import { guardMiddleClickPaste } from '../terminal/middle-click'
import { attachCopyOnSelect } from '../terminal/copy-on-select'
import { patchTerminalScale } from '../terminal/scale-fix'
import { focusedNodeId, subscribeFocusedNode, focusSurfaceEl } from '../state/focusNode'
import { parseOsc52 } from '../terminal/osc52'
import { createOsc52Notice, dispatchOsc52Toast, handleOsc52Write } from '../terminal/osc52-policy'
import { activateUnicode11 } from '../terminal/unicode-width'
import {
createFileLinkProvider,
createOsc8LinkHandler,
createUrlLinkProvider,
installLinkClickFallback,
installLinkContextMenu,
cachedCwd,
findExistingPath,
fileMissMessage,
makeDirListingLookup,
type LinkHoverSink,
type UnverifiedPath
} from '../terminal/file-links'
import { linkMenuItems, resolveLinkTarget, type LinkMenuTarget } from '../terminal/link-menu'
import { ContextMenu } from '../components/ContextMenu'
import { DownloadStrip } from '../components/DownloadStrip'
import { canUseLocalShell, downloadRoute, type DownloadContext } from '../lib/download'
import {
createLinkHintTooltip,
fileLinkHint,
hideLinkHints,
systemOpenRefusal,
urlLinkHint
} from '../terminal/link-hover'
import { useDownloads } from '../lib/useDownloads'
import { fileLinkDialect } from '../terminal/file-link-dialect'
import { hostPlatformFor } from '../terminal/host-platform'
import { executeHeldLaunch } from '../terminal/launch-intent'
import { uuid } from '../lib/uuid'
import { sshFs } from '../terminal/ssh-fs'
import type { FsApi, PendingLaunch, PtyApi } from '@shared/types'
import {
attachReplay,
closedByLabel,
createDataGate,
cursorPlacementSeq,
disposalAction,
forgetNodeTermState,
letterboxFor,
markRecycled,
recycleAction,
repaintResync,
reportedSize,
seedPaint,
setFittedSize,
shouldApplyResync,
stripTrailingNewline,
takeRecycled,
terminalKey,
terminalKeyAction,
toXtermText,
applyLiveOptions,
xtermOptionsFromSettings,
SHIFT_ENTER_SEQ,
CO_ATTACH_MOUSE_SEQ,
CO_ATTACH_ALT_SCREEN_SEQ,
type SessionLife
} from '../terminal/terminal-config'
import { useXtermVisualSettings } from '../terminal/useXtermVisualSettings'
import {
FONT_ZOOM_NODE_ATTR,
leavesSharedGlyphAtlas,
requestTerminalFontZoom,
terminalFontZoomAction
} from '../terminal/terminal-font-zoom'
import { ensureProjectLaunchInfo } from '../state/projectLaunchInfo'
import { loseWebglContexts, registerWebglClient, type WebglClientHandle } from '../terminal/webgl-budget'
import {
backgroundReleaseMs,
effectiveVisible,
isWindowBackgrounded,
subscribeWindowBackgrounded
} from '../terminal/window-backgrounded'
import { quantizeCharSize } from '../terminal/char-size-quantize'
import { resyncDomRendererSpacing } from '../terminal/dom-renderer-spacing'
import { patchViewportScrollSync } from '../terminal/viewport-scroll-sync'
import { patchShrinkTrim } from '../terminal/shrink-trim'
import {
parkCap,
parkWindowMs,
armParkExpiry,
canDisposeParkedEntry,
disposableParks,
planParkEviction,
type ParkTimer
} from '../terminal/park-budget'
import { agentProcessInPane } from '../terminal/live-work'
import {
mayDisposeOffscreen,
offscreenCoreIsRemote,
offscreenDisposeMs,
planOffscreenVisibility,
releaseStillEnabled,
shouldDeferReleaseForEco,
shouldDeferReleaseForHeldLaunch,
shouldDeferReleaseForLiveWork,
OFFSCREEN_DEFER_RETRY_MS,
OFFSCREEN_DISPOSE_MS_DEFAULT
} from '../terminal/offscreen-policy'
import { attachGlyphGrid, type GlyphGridAttachment } from '../terminal/glyphgrid-attach'
import type { GridHandle } from '../glyphgrid/engine'
import {
getSharedGlyphContext,
nodeIsOpaque,
nodeZFor,
sharedGlyphActive,
sharedGlyphAvailable,
subscribeNodeZOrder,
subscribeOpaqueSet,
useSharedGlyph
} from '../canvas/SharedGlyphLayer'
import {
bodyPlateRect,
bodyWorldRect,
packThemeBg,
validCellSize,
type Vec2
} from '../lib/glyphGridNode'
import {
cleanEcho,
deliverCommand,
type DeliveryIo
} from '@shared/command-delivery'
import { terminalKillLine } from '../terminal/terminal-kill-line'
import {
RESUME_MISS_WINDOW_MS,
detectsResumeMiss,
resumeSessionMissing
} from '../terminal/resume-fallback'
import {
GEMINI_MIGRATION_URL,
GEMINI_RETIRED_TAIL_CHARS,
geminiRetiredIn,
watchesGeminiRetirement
} from '../terminal/gemini-retired'
import { MAX_LAUNCH_LINE_BYTES, lineBytes } from '@shared/canonical-line'
import { binariesFor, type PaneOwner } from '@shared/agents/pane-owner-predicate'
import {
captureWakeContext,
decideHibernateExit,
decideWakeResume,
wakeRefusalReason,
wakeVerdictIsTransient,
type WakeVerdict
} from '../terminal/wake-identity'
import {
agentHibernateFns,
exitSequence,
guardConcurrentRestart,
isShellCommand,
performExitPhase,
performRestartResume,
performResumePhase,
queryPaneWithin,
registerAgentHibernate,
registerAgentPause,
registerAgentUpdateExit,
registerAgentRestart,
clearEnvEligibility,
restartEligibility,
restartSessionId,
RESTART_EXIT_TIMEOUT_MS,
RESTART_LATE_EXIT_MS,
settleRecycledNode,
type ExitPhaseOutcome,
type PauseOutcome,
type RecyclePatch,
type ResumePhaseOutcome
} from '../terminal/agent-restart'
import { coldResumeDecision, shouldProbeTranscript } from '../terminal/cold-resume-session'
import type { TranscriptPresence } from '@shared/types'
import {
looksDropped,
looksDroppedCandidate,
LIVENESS_POLL_MS,
LIVENESS_QUERY_MS
} from '../terminal/agent-liveness'
import { shouldAutoWake, shouldColdResume } from '../terminal/hibernation-policy'
import { skipsColdResume, takeColdResumeSkip } from '../terminal/handed-off-resume'
import { coldSelfHealVerdict } from '../terminal/cold-self-heal'
import { WakeInputBuffer } from '../terminal/wake-input-buffer'
import { FindBar } from '../components/FindBar'
import { TerminalMarkdownView } from './TerminalMarkdownView'
import {
focusXtermUnlessCovered,
requestTerminalFocusOnExit,
terminalOwnsFileInput,
useMdModeFocus
} from '../terminal/useMdModeFocus'
import { canvasOwnsMarkdownChord } from '../lib/markdownChord'
import { carryDraftToChat, carryDraftToTerminal } from '../lib/chatDraftCarry'
import { IconChat, IconChevronDown, IconChevronRight, IconClose, IconEye, IconEyeOff, IconGrid, IconMic, IconMoveTo, IconPlay, IconReload, IconSearch, IconSparkle } from '../components/icons'
import { NodeLabels } from '../components/kanban/NodeLabels'
import { MdViewHintButton } from '../components/MdViewHintButton'
import { mdViewHint } from '../lib/mdViewHint'
import { transcriptSessionFor } from '../lib/transcriptSession'
import { Tooltip } from '../components/Tooltip'
import { useTerminalSearch } from '../terminal/useTerminalSearch'
import { useCopyFeedback } from '../terminal/useCopyFeedback'
import { pasteWithImageReceipt } from '../terminal/image-paste-confirm'
import { usePasteReceipt } from '../terminal/usePasteReceipt'
import { createBoardPauseSlot } from '../terminal/board-render-pause'
import { ContextMeter } from '../components/ContextMeter'
import { RemoteControlButton } from '../components/RemoteControlButton'
import { isZoomModifierHeld } from '../lib/zoomModifier'
import { HoverGuard } from './HoverGuard'
import {
dwellBlursForeignTerminal,
focusDrivesGuard,
hoverTakesKeyboard,
pointerLeaveRearmsGuard,
resolveFocusFollowsPointer
} from '../lib/terminalFocusMode'
import { XTERM_INPUT_CLASS } from '../lib/keyContext'
import { useClickToFocus } from './useClickToFocus'
import { reparentKeepingFocus } from './reparentKeepingFocus'
import { isHidden } from '../lib/ui-visibility'
import { useTerminalGlass } from '../lib/useTerminalGlass'
import { useFrostLayer } from '../canvas/GlassFrostSync'
import { isLiquidGlass } from '../lib/appTheme'
import { readsClaudeTranscript } from '../lib/transcriptGates'
import { liveProjectJumpTarget } from '../lib/projectJump'
import { pushSessionRename } from '../lib/sessionRename'
import { announceUserClosedSession } from '../lib/lastSessionClose'
import { useSettings } from '../state/settings'
import { useCodexIdentity, codexSharedIdentity, codexFallbackText } from '../state/codexIdentity'
import { ensureCodexLaunchCaps } from '../state/codexCli'
import { useLaunchDelivery } from '../state/launchDelivery'
import { erroredDeps, firstOpenInFlight as isFirstOpenInFlight, handedOverDeps, holdReason, interruptedDeps, launchTooltip } from '../lib/pendingLaunch'
import { useStationHandovers } from '../state/stationHandovers'
import { useSuccessWait } from '../lib/useSuccessWait'
import { StationFailedChip } from '../components/StationFailedChip'
import { prHoldExpired, prHoldSummary } from '../lib/prWait'
import { pullBoardFor, useGitHubIssues } from '../state/githubIssues'
import type { AgentState } from '@shared/agents/normalize'
import type { ClientId } from '@shared/presence'
import { PresenceChips } from '../components/PresenceChips'
import { useAgentNodes } from '../state/agentNodes'
import { useTerminalFocus } from '../state/terminalFocus'
import { useProjects } from '../state/projects'
import { markWorkspaceDirty } from '../state/workspaceDirty'
import { isGlobalKanbanOpen, isKanbanOpen, isOmniKanbanEnabled, openIssueOnBoard, useViewMode, viewFor } from '../state/viewMode'
import { useSshConn } from '../state/sshConn'
import { useWorktrees } from '../state/worktrees'
import { isRemoteSessionNode } from '@shared/worktree'
import { RunBar } from './RunBar'
import { isRemoteProjectId, useSession, useSessionStores, useActiveSessionPresence } from '../session/session'
import { relayStatusGates } from '../terminal/relay-status-gates'
import { isHostedReadOnly, useHostedReadOnly } from '../state/hostedTeams'
import { isBrowserRuntime } from '../bridge/runtime'
import { agentLaunchOverride, toggleCollapsed, type CanvasNode } from '../state/workspace'
import { NodeColorSwatches } from '../components/NodeColorSwatches'
import { AccountChip, useAccountChip } from '../components/AccountChip'
import { IssueRefChip } from '../components/IssueRefChip'
import { TeamProgressChip } from '../components/TeamProgressChip'
import { PortsChip } from '../components/PortsChip'
import { useTeamStations } from '../state/teamStations'
import { sessionNameRepeatsTitle } from '../lib/cardRedundancy'
import { effectiveAccountId } from '../lib/accountChip'
import {
hasHooks,
canRecur,
canSubagent,
canContextLink,
hasUsage,
canChat,
canResume,
canRename,
canRemoteControl,
canReadTitle,
createdAgentId,
reportsOwnCopy,
agentConfig,
capabilityAgentId,
type AgentId
} from '@shared/agents/config'
import { withPermissionMode } from '@shared/agents/approval-mode'
import { assembleResumeCommand } from '@shared/agents/launch'
import { agentEnvSnapshot } from '@renderer/lib/agentEnv'
import { normalizedAgentModel } from '@shared/agents/model-gateway'
import { ensureActivePermissionMode } from '../state/permissionMode'
import {
buildSshArgs,
sshChipRepeatsProject,
sshConnectionIdForProject,
sshHostKey,
type SshConnection
} from '@shared/ssh'
import {
chipFor,
commandTooltip,
effectiveBindings,
terminalChordBubbles,
terminalShortcutPolicy
} from '../lib/keybindingOverrides'
import { matchesShortcut } from '@shared/shortcut'
import { hintLabel, isWindowsPlatform, isMacPlatform } from '@shared/platform-utils'
import { ColumnPill } from '../components/kanban/ColumnPill'
import { NodeCommentsPanel } from '../components/kanban/NodeCommentsPanel'
import { AgentMascot } from './AgentMascot'
import { MaximizeButton } from './MaximizeButton'
import { NodeIconView } from '../components/NodeIcon'
import { nodeIconDialog } from '../components/NodeIconPicker'
import { applyIconChoice } from '../lib/nodeIconChoice'
import { normalizeNodeIcon } from '@shared/node-icon'
import { connectHostAttachment } from '../lib/sshAttachments'
import { projectMayDialSsh } from '../session/relay-ssh'
import { REMOTE_PROJECT_SPAWN_REFUSAL, spawnBelongsElsewhere, useOwningProjectId } from '../session/owning-project'
import { waitForSshRemote } from '../lib/sshRemoteWait'
/** Which physical modifier the registry's abstract `Cmd` resolves to for the find-bar chord. */
const isMac = isMacPlatform()
/** A station was picked from the header's team ring: frame it — Canvas's `focusNodeById`, the same
* path the Omni board's "Open on canvas" takes (it also handles a node in another project). */
function travelToStation(nodeId: string): void {
window.dispatchEvent(new CustomEvent('nodeterm:focus-node', { detail: { nodeId } }))
}
/** How long a remote terminal waits for its project's ControlMaster before giving up and showing
* the offline overlay. Sized for the SLOW-but-fine case (a cold app load whose connect is still
* authenticating, a passphrase prompt, a distant host), not for the unreachable one — the
* overlay it falls back to is cheap and self-healing, so waiting longer buys nothing. */
export const SSH_REMOTE_WAIT_MS = 20000
/** How long a REMOTE spawn may take before the node says out loud that it is waiting.
*
* Longer than a healthy attach by a wide margin — 18 parallel warm attaches at 50 ms RTT painted
* in a median of 0.16 s — so a normal switch never prints it, and short enough that a node held
* behind the spawn queue (or a contended master) is not blank for seconds with nothing to read. */
export const SLOW_REMOTE_SPAWN_NOTICE_MS = 1500
/**
* Which connection scope a remote node in the ACTIVE project runs over: the project's own id when
* the project IS that SSH endpoint, otherwise the project × endpoint host attachment — a remote
* node living in a local canvas (or in an SSH project pointed at a different host).
*
* A node only ever exists in the active project's React Flow, so the active project is its owner.
*/
export function sshConnectionScope(conn: SshConnection): string {
const { activeProjectId, getProject } = useProjects.getState()
return sshConnectionIdForProject(activeProjectId, conn, getProject(activeProjectId)?.ssh?.server)
}
/**
* Which ControlMaster a node's file uploads go over: its OWN connection's scope (for an attached
* node, the host attachment — not the local project), else the active project. ONE definition for
* the terminal drop, the card modal's live viewer and the ⌘M composer's attach, so the three can
* never upload one file to two different machines.
*/
export function nodeUploadScope(ssh: SshConnection | undefined): string {
return ssh ? sshConnectionScope(ssh) : useProjects.getState().activeProjectId
}
/**
* The project whose per-project settings apply to a node in THIS canvas — for the launch-command
* layer (`agentLaunchOverride`) on relaunch, restart and wake.
*
* The active project, deliberately, and NOT `sshConnectionScope`'s answer: that scope is a
* CONNECTION identity, which for a remote node attached to a foreign host is a synthetic
* project×host attachment id (`sshAttachmentId`) rather than a project id at all — passing it here
* would silently resolve to "no project settings" for exactly those nodes. A node only ever exists
* in the active project's React Flow (same reasoning `sshConnectionScope` states), so the active
* project is its owner; an SSH project's own nodes answer the same id either way.
*/
export function owningProjectId(): string {
return useProjects.getState().activeProjectId
}
/**
* The owning project id, with its launch-info snapshot WARM — for the three already-async relaunch
* paths below (cold restore, in-place restart, hibernation wake).
*
* `agentLaunchOverride` reads `projectLaunchInfoNow` SYNCHRONOUSLY and fails open to the global
* layer when the project is still cold. That is right for a fresh launch (it must never block), but
* on COLD RESTORE it silently dropped the project's wrapper at the one moment it matters most: the
* relaunch fires from a node's mount, racing the very first `ensureProjectLaunchInfo` of the
* session, so a whole canvas could come back through the bare CLI — no env, no account setup —
* with nothing to show for it. These paths are already asynchronous (they await the permission-mode
* probe), so one bounded warm-up costs them nothing they were not already paying.
*
* Bounded and never-rejecting BY CONSTRUCTION (see `ensureProjectLaunchInfo`: it resolves on its own
* ENSURE_WAIT_MS timeout and swallows every error), so this cannot hang or break a relaunch — a
* project that stays cold resolves exactly as it did before.
*
* The id is read ONCE, before the await, and returned — so the snapshot that was warmed and the
* project the override is resolved for are the same one even if the active project changes while
* the round trip is in flight. Deliberately NOT applied to the synchronous fresh-launch factory
* (`createAgentNode`), which has no await to hide this behind.
*/
async function warmOwningProjectId(): Promise<string> {
const projectId = owningProjectId()
await ensureProjectLaunchInfo(projectId)
return projectId
}
/** The live ControlMaster path a remote node would run over, if any. Lets the caller tell "we will
* resolve in a microtask" from "we are about to sit in the wait below" without duplicating the
* lookup. Without a `conn` it answers for the active project's own connection. */
export function currentControlPath(conn?: SshConnection): string | undefined {
return useSshConn
.getState()
.getControlPath(conn ? sshConnectionScope(conn) : useProjects.getState().activeProjectId)
}
/**
* Resolve the `sshRemote` create option for a remote terminal: its connection scope's live
* ControlMaster `controlPath` (set by Canvas's active-project effect on connect) plus the inline
* connection and remote cwd. The controlPath may not be ready yet on a cold app load (child
* effects run before the parent's connect resolves), so wait for it — briefly — before spawning.
*
* The scope is the OWNING PROJECT for an SSH project's own nodes and a HOST ATTACHMENT for a node
* whose endpoint isn't the project's — never a bare `activeProjectId`, which for an attached node
* would resolve the local project's (absent, or worse: a DIFFERENT host's) master.
*
* Returns undefined if no master appears within the window (connection failed). The caller must
* then spawn NOTHING — see `PtyCreateOptions.requireRemote`: a create without `sshRemote` does
* not degrade to "no session", it degrades to a LOCAL one wearing the remote node's identity.
*/
export async function resolveSshRemote(
conn: SshConnection,
cwd: string | undefined,
/**
* Opt in to the EARLY attach path: spawn as soon as the ControlMaster answers `-O check`,
* without waiting for the connect's remote setup chain — but ONLY once the host has positively
* listed this node's remote tmux session (see `waitForSshRemote`). Absent ⇒ the pre-feature
* behavior, wait for the full `connected`.
*
* `pty` is the CALLER'S SESSION-BOUND api, not the global: the confirmation has to be answered
* by the same core that will run `create` a moment later, or the two would consult different
* hosts — and the coalesced `tmux list-sessions` this shares with `create` would be two reads
* instead of one.
*/
early?: { nodeId: string; pty: Pick<PtyApi, 'remoteSessionConfirmed'> }
): Promise<
| {
controlPath: string
conn: SshConnection
remoteCwd: string
hookEndpointPath?: string
tmuxConfPath?: string
remoteHome?: string
}
| undefined
> {
const activeProjectId = useProjects.getState().activeProjectId
// A relay tab's node belongs to another machine: never dial or wait for a master for it here
// (session/relay-ssh.ts). The caller treats undefined as "no master"; the relay spawn path does
// not call this at all — this is the second half.
if (!projectMayDialSsh(useProjects.getState().getProject(activeProjectId))) return undefined
const projectId = sshConnectionScope(conn)
// A HOST ATTACHMENT dials for itself, HERE, because nothing else will. Canvas's active-project
// effect pre-warms the attachments it can SEE in the stored canvas, but a node created at
// runtime — the remote account-login retry drops one into whatever tab is active — never
// appears in that pass, and would otherwise wait out the window under a scope no master exists
// for and then sit offline forever. Idempotent and deduped, so the pre-warm and every node on
// the machine collapse into one connect; the wait below is what actually blocks on it.
if (projectId !== activeProjectId) {
void connectHostAttachment(
projectId,
{
conn,
hostKey: sshHostKey(conn),
remoteCwd: cwd,
ownerProjectId: activeProjectId
},
(scopeId, c, remoteCwd) => window.nodeTerminal.sshProject.connect(scopeId, c, remoteCwd),
(scopeId) => window.nodeTerminal.sshProject.disconnect(scopeId)
)
}
// The three optional facts below (remote hook endpoint, remote tmux.conf path, remote $HOME) are
// produced by the connect's SETUP chain and are read at session CREATION only — the tmux `-e`
// hook/account env and the `-f` config. That is exactly why a node whose session already exists
// may attach over the master before any of them exist; see `waitForSshRemote` for the full rule.
const outcome = await waitForSshRemote({
// Narrowed to the four fields a spawn takes. `SshConnInfo` also carries the Codex runtime paths
// and the claude-probe answer, and spreading the whole entry would put them on the wire in
// every `pty.create` — a payload change nothing reads, for no reason.
getFull: () => {
const info = useSshConn.getState().byProject[projectId]
if (!info) return undefined
return {
controlPath: info.controlPath,
hookEndpointPath: info.hookEndpointPath,
tmuxConfPath: info.tmuxConfPath,
remoteHome: info.remoteHome
}
},
getEarly: () => useSshConn.getState().getEarlyControlPath(projectId),
subscribe: (cb) => useSshConn.subscribe(cb),
confirmSession: early
? (controlPath) => early.pty.remoteSessionConfirmed(early.nodeId, { controlPath, conn })
: null,
waitMs: SSH_REMOTE_WAIT_MS
})
if (outcome.kind === 'none') return undefined
const remoteCwd = cwd || '~'
if (outcome.kind === 'early') {
// Warm attach over a master whose setup chain is still running. No setup facts by
// construction: `new-session -A` on a live session only attaches, so there is nothing for a
// `-f` or an `-e` to apply to, and passing a half-built value would be a lie about what the
// session carries.
return { controlPath: outcome.controlPath, conn, remoteCwd }
}
return { ...outcome.facts, conn, remoteCwd }
}
/**
* Move-into-worktree handler bridge. Like GroupNode's worktree-action bridge: React Flow
* instantiates custom nodes itself, so Canvas can't pass this callback through props. Canvas
* registers its handler here on mount; the "↪" header action calls it with the node id.
*/
let moveIntoWorktreeHandler: ((nodeId: string) => void) | null = null
export function setMoveIntoWorktreeHandler(fn: ((nodeId: string) => void) | null): void {
moveIntoWorktreeHandler = fn
}
/**
* SSH-drop handler bridge (same pattern as the move-into-worktree bridge above). Canvas
* registers the SshReconnector's reportDrop here; an SSH-project terminal whose ssh client
* exits 255 (connection drop — the remote tmux session survives) reports (projectId, nodeId)
* so the coordinator can re-establish the master and respawn the node.
*/
let sshDropHandler: ((projectId: string, nodeId: string) => void) | null = null
export function setSshDropHandler(fn: ((projectId: string, nodeId: string) => void) | null): void {
sshDropHandler = fn
}
/**
* Report a remote terminal that has no session to the reconnect coordinator. Also used by the
* kanban card modal, which spawns the same node through its own transport and hits the same
* "no master" refusal — both surfaces queue the node so ONE reconnect flushes them together.
*/
export function reportSshDrop(projectId: string, nodeId: string): void {
sshDropHandler?.(projectId, nodeId)
}
/**
* Manual "Reconnect" bridge (same pattern as the drop bridge above). Canvas registers the
* SshReconnector's `retryNow`; the offline overlay's button calls it with this node so the
* user's explicit ask jumps the backoff — and clears the node's respawn-refuse window, which
* exists to stop AUTOMATIC hot loops, not to make a person click twice.
*/
let sshRetryHandler: ((projectId: string, nodeIds: string[]) => void) | null = null
export function setSshRetryHandler(
fn: ((projectId: string, nodeIds: string[]) => void) | null
): void {
sshRetryHandler = fn
}
/**
* Parked terminals: when a node unmounts (project switch), its xterm instance and live PTY
* session are kept — the `.xterm` element is detached from the DOM and held here — so a remount
* within the park window (`settings.terminalParkMinutes`) re-adopts them instead of respawning.
* This makes switching back to a project instant AND exact: the tmux client never detaches, so the full terminal state
* (alternate screen, mouse-tracking modes, scrollback, cursor) carries over with no redraw and
* no mode re-negotiation to get wrong. After the window the entry is disposed for real (the
* PTY client detaches; the tmux session itself keeps running, as always). The park is bounded in
* COUNT as well as time — beyond `settings.terminalParkMax` the oldest entries are evicted early,
* local before remote (see `terminal/park-budget.ts`), so a remount past the cap is the same warm reattach as one past the
* window.
*
* "The PTY client detaches; the session keeps running" is true ONLY with tmux underneath. On the
* plain-shell fallback the pty IS the shell, so the same dispose kills the shell and whatever runs
* in it — which is how a project switch could terminate a working agent mid-task (issue #126).
* Every dispose driven purely by the BUDGET (window expiry, LRU cap, memory-pressure lever) is
* therefore gated on `canDisposePark`; a deliberate dispose (delete, respawn, dead session) is not.
*/
interface ParkedTerminal {
term: Terminal
fit: FitAddon
search: SearchAddon
transport: TerminalTransport
sessionId: string
/** `PtyCreateResult.persistent`: the session survives a client kill (tmux, local or remote).
* False = plain shell, where disposing this park ends the session for real. */
tmuxBacked: boolean
/** The node's agent state AT PARK TIME — the protection FLOOR. The unmount that parks is also
* the one that CLEARS this node's agent status (TerminalNode's departure effect), and every
* lever reads later than that, so without this snapshot every park looks agent-less. See
* `effectiveAgentState`. */
parkedAgentState?: AgentState
/** An agent CLI was in the pane at park time — see `ParkedEntryState.agentProcess`. */
agentProcess: boolean
/** Live read: has the CLI announced its exit since? The veto over `agentProcess`. */
readSessionEnded: () => boolean
/** When this entry was parked — what ages the snapshot above (`parkedStateFloor`). */
parkedAt: number
/** The node's agent state RIGHT NOW, read from the store of the session this node belongs to
* (a relay tab's status lives in its own instance, not the default one). Closed over at park
* time because the module-level levers have no access to the component's session. */
readAgentState: () => AgentState | undefined
/** Session-scoped teardown (transport/xterm listeners) — run only at final dispose. */
cleanups: Array<() => void>
/**
* Lifetime of the session itself, SHARED with the effect that created it (and with the effect
* that later adopts this entry). `dead` flips on the final dispose, `killed` guards the PTY kill
* so a session is killed at most once even when a still-in-flight spawn continuation, the effect
* cleanup and the park dispose all race for it.
*/
life: SessionLife & { killed: boolean }
/** The park window, which RE-ARMS while the entry is protected (see `armParkExpiry`). */
timer: ParkTimer
/** Rebuilding this session costs a network round trip — an SSH-project node (remote tmux over
* the ControlMaster) or a relay tab. The LRU cap evicts these LAST (`planParkEviction`). */
remote: boolean
}
const parkedTerminals = new Map<string, ParkedTerminal>()
// The park window is `settings.terminalParkMinutes` (default 10 — the old TERM_PARK_MS was 5; 0 =
// until the app quits) and the count cap `settings.terminalParkMax` (default PARK_MAX = 20), both
// read at PARK time through their validators (`parkWindowMs` / `parkCap`), so a change applies to
// the next switch-away without touching entries already parked. Issue #886.
/** May the BUDGET levers dispose this park? The entry carries both halves of the answer: the
* session's tmux-backedness, and a live read of the node's OWN agent-status store with the
* park-time snapshot as a floor under it (see `canDisposeParkedEntry`). An unknown key is
* disposable — there is nothing there to protect. */
function parkDisposable(key: string): boolean {
const p = parkedTerminals.get(key)
if (!p) return true
return canDisposeParkedEntry({
tmuxBacked: p.tmuxBacked,
parkedAgentState: p.parkedAgentState,
agentProcess: p.agentProcess,
liveSessionEnded: p.readSessionEnded(),
parkedAt: p.parkedAt,
liveAgentState: p.readAgentState()
})
}
function disposeParked(p: ParkedTerminal): void {
p.timer.cancel()
// Mark the session dead BEFORE tearing it down: a spawn continuation still awaiting its history
// seed reads this to see that the session it handed off no longer exists (→ teardown, not
// continue-parked), instead of wiring listeners onto a killed session.
p.life.dead = true
p.cleanups.forEach((fn) => fn())
if (!p.life.killed) {
p.life.killed = true
p.transport.kill(p.sessionId)
}
p.term.dispose()
}
/** Drop a node's parked terminal (if any), detaching its PTY client. `key` is the session-scoped
* `terminalKey(sessionId, nodeId)` — the module maps are keyed by it so a local and a relay node
* that share a bare id never collide. */
export function disposeParkedTerminal(key: string): void {
const p = parkedTerminals.get(key)
if (!p) return
parkedTerminals.delete(key)
disposeParked(p)
}
/** Memory-pressure lever: drop EVERY parked terminal now, without waiting out the park window. The
* park is a cache, not state — each dropped entry costs only its warm re-adopt, and the node
* re-mounts as an ordinary warm reattach (tmux redraws; the session and its scrollback are
* untouched). Idempotent; iterates a copy because `disposeParkedTerminal` mutates the map.
*
* EXCEPT the protected ones (`canDisposePark`): for a plain-shell session the sentence above is
* false — the dispose is not a re-adopt cost, it is the end of the session — so a park holding a
* working agent on a non-tmux shell is left alone and released by its own expiry re-check.
* Everything else still goes, which is the whole point of the lever. */
export function disposeAllParkedTerminals(): void {
for (const key of disposableParks([...parkedTerminals.keys()], parkDisposable)) {
disposeParkedTerminal(key)
}
}
/** Session-scoped keys (`terminalKey`) whose next unmount must dispose (not park) — set on permanent
* deletion, where the unmount runs AFTER the session was already destroyed, so parking would keep a
* dead xterm. */
const noParkIds = new Set<string>()
/** Canvas calls this when permanently deleting a terminal node: drops an already-parked entry
* AND makes the upcoming unmount (if the node is currently mounted) dispose instead of park. Takes
* the node's `sessionId` (the session its tab is bound to) so the composite key matches the one the
* mounted `TerminalNode` uses — a local node resolves to `'local'`, i.e. its historical bare-id
* behavior. `forgetNodeTermState` stays node-id keyed: `fittedByNode`/`recycledIds` are transient
* per-mount and only one node with a given id mounts at a time, so a cross-session collision there
* is benign. */
export function disposeTerminalOnUnmount(sessionId: string, nodeId: string): void {
const key = terminalKey(sessionId, nodeId)
noParkIds.add(key)
disposeParkedTerminal(key)
coStates.delete(key)
forgetNodeTermState(nodeId)
}
/**
* Resize the emulator the way `FitAddon.fit()` does — clearing the render service FIRST.
*
* We drive `term.resize()` ourselves (the pty, not the fit, is the authority on the grid under
* co-attach), and the `clear()` is not decoration: it forces a full repaint, without which
* shrinking a terminal can leave stale glyph rows behind in the area that was cut. That is a
* regression EVERY user would hit on a plain drag-resize, solo included — so we keep the addon's
* behavior byte for byte. Private API (`_core._renderService`), exactly as addon-fit uses it, so it
* is fail-soft: if xterm ever renames it, we still resize.
*/
function resizeTerm(term: Terminal, cols: number, rows: number): void {
if (term.cols === cols && term.rows === rows) return
try {
;(term as unknown as { _core: { _renderService: { clear(): void } } })._core._renderService.clear()
} catch {
// private API moved — the resize below still happens (worst case: a stale row until the next paint)
}
term.resize(cols, rows)
}
// ---------------------------------------------------------------------------------------------
// glyphgrid (experimental shared renderer) — the DOM reads that feed `lib/glyphGridNode`'s pure
// helpers. Nothing below runs for the default renderer modes: every caller sits behind
// `sharedGlyphActive()`.
// ---------------------------------------------------------------------------------------------
/** One `[glyphgrid]` line per distinct (node, reason). A generation bump re-runs the setup, and a
* machine that cannot register a grid cannot register it the second time either — the warning is
* a diagnostic, not a heartbeat. Never `failSharedGlyph`: one node's mismatch must not take the
* shared renderer away from every other terminal on the canvas. */
const glyphWarned = new Set<string>()
function glyphWarn(key: string, message: string): void {
if (glyphWarned.has(key)) return
glyphWarned.add(key)
console.warn(`[glyphgrid] ${message}`)
}
/**
* How far the terminal SCREEN sits inside its React Flow node, in layout px.
*
* Walks the `offsetParent` chain — each `offsetLeft/Top` is relative to the next positioned
* ancestor, so the running sum is the offset within the node — and stops at React Flow's own node
* element. LAYOUT coordinates deliberately: the canvas transform scales rendered pixels but never
* changes an offset, so this measurement is identical at every zoom, while a
* `getBoundingClientRect` would have to be un-zoomed and un-scrolled by hand.
*
* `.xterm-screen` is measured when present, so the host's asymmetric padding
* (`.term-node__xterm` is `4px 2px 2px 6px`) is already inside the chain and the caller never adds
* it. Null — "leave the grid where it is" rather than "move it somewhere guessed" — when the chain
* never reaches a `.react-flow__node` (a parked, detached element).
*/
function screenOffsetInNode(term: Terminal): Vec2 | null {
return offsetInNode(
(term.element?.querySelector('.xterm-screen') as HTMLElement | null) ?? term.element ?? null
)
}
/**
* The `offsetParent` walk itself — see `screenOffsetInNode` for the coordinate contract.
*
* Called with two different elements, which is why it is not folded back into that one:
* `.xterm-screen` places the grid, and the terminal HOST (`.term-node__xterm`, which stands in for
* the body — see `measurePlateRect` for the CSS invariant that makes it stand in) places the
* opaque PLATE.
*/
function offsetInNode(el: HTMLElement | null): Vec2 | null {
if (!el) return null
let x = 0
let y = 0
let cur: HTMLElement | null = el
// Bounded: a layout tree cannot cycle, but an unexpected DOM shape must not spin inside a
// ResizeObserver tick. The real chain is screen → .xterm → host → body → node (4 hops).
for (let depth = 0; cur && depth < 12; depth++) {
if (cur.classList.contains('react-flow__node')) return { x, y }
x += cur.offsetLeft
y += cur.offsetTop
cur = cur.offsetParent as HTMLElement | null
}
return null
}
/**
* xterm's CSS cell size, read off whatever renderer the render service currently holds.
*
* This — not `_charSizeService` — is the number a grid must be registered with: `css.cell` is
* derived from the DEVICE metrics (char size × dpr, ceil'd, then `letterSpacing`/`lineHeight`
* applied) and equals the raw char size ONLY at `lineHeight: 1, letterSpacing: 0`. It is also the
* value xterm maps mouse coordinates through, so registering anything else would drift selection
* away from the glyphs the shared canvas paints.
*
* Private API, fully guarded: null simply means "don't register", i.e. this terminal keeps the
* renderer it already has.
*/
/**
* Debug-only: what each node's grid was registered with, on `window.__glyphgridCells()`.
*
* The accessor is installed EAGERLY and always answers, because its absence was ambiguous in
* exactly the way a bad error message is: "not a function" could equally mean the build is old,
* the debug flag is off, or the canvas is not in shared mode, and the reader cannot tell which. It
* now reports that instead of throwing.
*/
const cellDebug = new Map<string, unknown>()
function glyphCellDebugOn(): boolean {
try {
return typeof window !== 'undefined' && localStorage.getItem('nodeterm.glyphgridDebug') === '1'
} catch {
return false
}
}
function currentDprForDebug(): number {
return typeof window !== 'undefined' ? window.devicePixelRatio || 1 : 1
}
function publishCellDebug(id: string, info: Record<string, unknown>): void {
if (!glyphCellDebugOn()) return
const css = info.css as { cellW: number; cellH: number } | null
const device = info.device as { cellW: number; cellH: number } | null
const dpr = info.dpr as number
cellDebug.set(id, {
...info,
// The ratio that matters: at zoom 1 `css * dpr` must equal `device`, so 1.00 means the glyph
// is drawn at exactly the size it was rasterized for and anything else IS the stretch factor.
stretchW: css && device ? (css.cellW * dpr) / device.cellW : null,
stretchH: css && device ? (css.cellH * dpr) / device.cellH : null
})
}
if (typeof window !== 'undefined') {
;(window as unknown as Record<string, unknown>).__glyphgridCells = (): unknown => {
if (!glyphCellDebugOn()) {
return { status: "debug flag off — localStorage.setItem('nodeterm.glyphgridDebug','1') then reload" }
}
if (cellDebug.size === 0) {
return {
status:
'no grid has registered yet — this only records in SHARED renderer mode (Settings → Terminal → Terminal rendering), after a terminal has laid out',
dpr: currentDprForDebug()
}
}
return Object.fromEntries(cellDebug)
}
}
function cssCellOf(term: Terminal): { cellW: number; cellH: number } | null {
return cellOf(term, 'css')
}
/**
* xterm's DEVICE cell — the number of physical pixels one cell occupies at zoom 1, which is what
* the shared ATLAS must rasterize into.
*
* The engine draws a cell as `css.cell × zoom` onto a dpr-scaled buffer, so at zoom 1 the quad is
* exactly this many device pixels; an atlas slot measured any other way is stretched over it and
* every glyph is resampled (see `DeviceCell` in the shared layer). Fractional by nature
* (`charWidth * dpr`) and deliberately handed over UNROUNDED — the atlas rounds only its slot
* PITCH, never the sampled extent.
*
* **It is read RAW, and the dpr rebuild does not change that.** A tie-break against the CSS cell
* scaled by `window.devicePixelRatio` was tried here (to guard the re-register that follows a
* display change against a measurement taken on the display we left) and reverted, for reasons
* worth keeping so it is not tried a third time:
* - There is no staleness window to guard. `CoreBrowserService.dpr` is a live getter over
* `window.devicePixelRatio` — nothing is cached — and the generation bump runs `teardownGlyph()`
* BEFORE it raises the epoch, which restores a fresh `DomRenderer` whose constructor recomputes
* the dimensions against that live dpr. By the time `setupGlyph` reads it, `device.cell` is the
* NEW display's.
* - `css × dpr` does not reproduce it anyway. xterm rounds the CSS canvas
* (`css.canvas.width = round(device.cell.width * cols / dpr)`) and divides that by `cols`, so
* the CSS cell carries a per-terminal residual — the same rounding `addon.ts` documents and
* reproduces.
* - Which made the reading GEOMETRY-dependent: two terminals with the same font on one retina
* display returned different "device cells", tripping `warnOnCellDrift`'s 0.01 threshold on an
* ordinary multi-terminal canvas. That is the line the device checklist arms the tester with,
* so the guard's only lasting effect would have been false positives on the platform being
* promoted.
*/
function deviceCellOf(term: Terminal): { cellW: number; cellH: number } | null {
return cellOf(term, 'device')
}
/** The guarded read behind both cell accessors. Private API, fully guarded: null simply means
* "don't register", i.e. this terminal keeps the renderer it already has. */
function cellOf(term: Terminal, space: 'css' | 'device'): { cellW: number; cellH: number } | null {
try {
const dims = (
term as unknown as {
_core?: {
_renderService?: {
dimensions?: Partial<
Record<'css' | 'device', { cell?: { width: number; height: number } }>
>
}
}
}
)._core?._renderService?.dimensions
const cell = dims?.[space]?.cell
if (!cell) return null
return validCellSize(cell.width, cell.height)
} catch {
return null
}
}
/** Sub-pixel slack when comparing the cell size we registered with against the addon's own. Below
* this a difference cannot move a glyph by a visible amount even across a 200-column row. */
const CELL_SIZE_EPS = 0.01
/**
* Co-attach UI state per node — kept OUTSIDE React on purpose.
*
* The transport listeners (onSize / onClosed / onResync) are wired ONCE, in the spawn
* continuation, and they SURVIVE a park: an adopted terminal carries its `cleanups` over and never
* re-subscribes. A remounted node is a NEW React instance, so a `setState` captured by those
* listeners would update a component that no longer exists. They publish here instead, and
* whichever instance is currently mounted subscribes.
*
* `closed` is also the respawn guard: once another client has DESTROYED this node's session
* (tmux kill-session — gone for everyone), a remount must NOT call `transport.create` again. Core
* can only make that respawn fresh, not impossible — it would resurrect a terminal its owner
* deliberately killed. Cleared only on permanent deletion (disposeTerminalOnUnmount).
*/
// GUARD_CLICK_SLOP (the click-vs-drag threshold on the hover guard) lives with the guard itself,
// in `HoverGuard.tsx`, beside the pointer-event handling that makes the click reachable at all.
interface CoState {
/** The pty runs at a SMALLER subscriber's grid than we could fit → center + letterbox. */
letterbox: boolean
/** Set once the session was destroyed by someone else. `by` is null for an unattributed destroy. */
closed: { by: ClientId | null } | null
/**
* The session ENDED under us and there is nothing to re-attach to, but the node is NOT deleted:
* the client that recycled it (moved it into a worktree) never registered a replacement session
* — its app quit or crashed mid-move — so core released us on the escape-hatch timeout.
*
* We must not respawn: our create options still carry the node's OLD cwd (the mover's cwd change
* is not broadcast to us), so we would spawn `nt-<id>` in the stale folder and the mover's own
* `new-session -A` would then reattach it — everyone's node claiming the worktree path with a
* shell sitting somewhere else. So the terminal ends and the user reopens it deliberately, which
* is recoverable and, unlike a silent stale-cwd respawn, honest. Cleared by that reopen.
*/
ended: boolean
/**
* This is an SSH-project terminal and its host is UNREACHABLE, so no session was spawned —
* neither here nor, crucially, locally (see `PtyCreateOptions.requireRemote`).
*
* Unlike `closed`/`ended` this is not a respawn guard: it is the state the node sits in until
* the project's ControlMaster comes back, and the reconnect coordinator (or the overlay's
* Reconnect button) is expected to bump `respawnNonce` and try again. The node is reported to
* that coordinator the moment it lands here, so an idle canvas heals itself.
*/
offline: boolean
/**
* The spawn REJECTED — core could not start a process at all (node-pty's `posix_spawnp failed`,
* a missing program, a resource limit).
*
* Before this existed the create promise had no rejection handler: the failure surfaced as an
* unhandled rejection in the main process log and the node sat there as an EMPTY xterm — a black
* rectangle with no explanation and no way back short of deleting the node. That is the
* 2026-08-06 report ("some terminals are black after coming back to the app"), and the black is
* not a rendering fault at all; it is a terminal that was never started.
*
* Holds core's own message, which names the program, the cwd and what it measured — the user is
* the one who can act on "out of file descriptors" or "host unreachable", and hiding it helps
* nobody.
*/
spawnError: string | null
/**
* A WARM reattach found the session's live working directory GONE (`PtyCreateResult.staleCwd`,
* issue #464): the folder was deleted — or deleted and re-created, which is a different inode,
* so the shell keeps printing `getcwd` errors forever. NOT an overlay state: the terminal is
* alive and possibly mid-work, so this only raises a slim banner offering an EXPLICIT
* recycle-and-respawn ("Restart in folder") plus a dismiss. Nothing is typed into the pane and
* nothing restarts on its own. Overwritten by every create result for this node, so a clean
* respawn clears it.
*/
staleCwd: boolean
/**
* This node COLD-STARTED and the conversation its persisted session id names is gone, so the
* agent was launched bare instead of resuming a dead id (see `cold-resume-session.ts`).
*
* A slim banner rather than an overlay, for the same reason `staleCwd` is one: the terminal
* underneath is alive and working — the agent started, it simply started fresh. Nothing to
* retry, so the only control is a dismiss. Announced at all because the alternative is what
* this fixes from the other side: a fresh conversation opened in silence, under a node whose
* title, badge and history all still describe the old one.
*/
lostSession: boolean
/**
* A one-shot launch command was REFUSED at delivery because it is longer than a canonical-mode
* tty line (`deliverCommand`'s `line-too-long`, issue #706). Holds the command's byte length,
* for the banner; `null` = nothing refused.
*
* NOT an overlay like `spawnError`: the terminal is alive and the user can run the command
* themselves — covering it would take away the only surface that can still be used. Same slim
* top banner as `staleCwd`, and for the same reason.
*/
launchTooLongBytes: number | null
/**
* A gemini node's pane printed Gemini CLI's own retirement refusal ("This client is no longer
* supported for Gemini Code Assist for individuals…", see `terminal/gemini-retired.ts`): the
* user's Google account is one Google stopped serving from Gemini CLI on 2026-06-18, and the
* sign-in screen will loop forever. A slim banner, like `lostSession`: the terminal is alive and
* nothing is typed or relaunched — it names the cause and offers an Antigravity node instead.
*/
geminiRetired: boolean
/**
* This node's cold-restore relaunch was skipped once because its project was just taken back from
* a hosted team ("Open here anyway", `terminal/handed-off-resume.ts`): the team's server may be
* running the same conversation, and resuming it here too would put two processes on one
* transcript. A slim banner, like `lostSession`: the shell is alive and nothing was typed.
*/
resumeSkipped: boolean
}
const NO_CO: CoState = {
letterbox: false,
closed: null,
ended: false,
offline: false,
spawnError: null,
staleCwd: false,
lostSession: false,
launchTooLongBytes: null,
geminiRetired: false,
resumeSkipped: false
}
const coStates = new Map<string, CoState>()
const coSubs = new Map<string, (s: CoState) => void>()
/**
* Restart hooks for a RECYCLED node — the other half of the destroy/recycle split.
*
* "Move into worktree" ends a node's tmux session so the same node id respawns in the new cwd. It
* is NOT a deletion: the node stays on every canvas. A co-viewer therefore must not land in the
* `closed` state above (permanent, un-respawnable) — it has to RESTART its terminal onto the
* replacement session, which core has already spawned by the time it tells us (so our re-create
* co-attaches to it rather than spawning the node in our own, stale cwd).
*
* The mounted instance publishes its respawn trigger here, for the same reason as `coSubs`: the
* transport listener is wired once, survives a park, and cannot hold a `setState` of a component
* that may since have unmounted. No entry = nobody is mounted, and the park (if any) is disposed
* instead — a parked terminal is holding the dead pty, and the next mount creates fresh.
*/
const restartSubs = new Map<string, () => void>()
/**
* Nodes whose terminal is up and settled enough to be TYPED INTO — the signal Canvas's armed-launch
* loop waits on before it delivers a held command (`pendingLaunch`).
*
* It exists because the loop used to wait on nothing at all: it fired `pty.sendText` the instant
* the canvas held the node and spent a flat 2 s retry budget while the session was still being
* spawned, then gave up in a `console.warn`. On a cold project switch that budget is gone before
* tmux has a session to paste into, which is issue #569 item 1 — a node stuck on QUEUED that only
* a manual click could start.
*
* "Ready" is deliberately the same moment `writeWhenShellReady` delivers an `initialCommand`: the
* session resolved AND its shell has gone quiet. Both paths type into the same pane, and a launch
* line written across zsh's rc-file tty flush is the mangled-command bug that helper exists for.
*
* ABSENT = not ready, which is the safe direction: it holds the launch (visibly — see
* `useLaunchDelivery`) instead of burning it against a session that is not there. Published by the
* node itself, since nothing else can see the spawn resolve. A PARKED session stays ready, and so
* does one whose viewer was RELEASED offscreen while tmux is underneath — both are still a live
* tmux session addressable by name; only a teardown that ends the session (respawn, delete, or the
* release of a plain-shell session) clears it.
*/
const sessionReadyNodes = new Set<string>()
const sessionReadySubs = new Set<(nodeId: string) => void>()
/** Is this node's session up and typeable? Unknown answers false — see the note above. */
export function isSessionReady(nodeId: string): boolean {
return sessionReadyNodes.has(nodeId)
}
/**
* Watch for nodes becoming ready. The callback is handed the node id rather than being a bare
* "something changed" ping: Canvas re-renders on it, and a canvas of forty terminals must not
* re-render forty times on load for the sake of the one node that is armed.
*/
export function subscribeSessionReady(cb: (nodeId: string) => void): () => void {
sessionReadySubs.add(cb)
return () => {
sessionReadySubs.delete(cb)
}
}
function setSessionReady(nodeId: string, ready: boolean): void {
if (sessionReadyNodes.has(nodeId) === ready) return
if (ready) sessionReadyNodes.add(nodeId)
else sessionReadyNodes.delete(nodeId)
for (const cb of sessionReadySubs) cb(nodeId)
}
/**
* Which mounted terminals are currently OUT of the viewport, published by the one visibility
* observer each node already runs (Phase 2's) — never a second observer, and never a second
* verdict: this map only mirrors what that callback decided.
*
* Read by Canvas's hibernation sweep, which asks about nodes it does not render itself. Keyed by
* NODE id (like `restartFns`, not like the session-scoped `termKey` maps) because that is the id
* the sweep, the plan and the registry all speak.
*
* ABSENT = not offscreen. A node that has not reported yet (its observer's first delivery is
* queued, or the environment has no IntersectionObserver at all) must never be read as "nobody is
* looking at it" — that is the direction that hibernates a session the user is staring at.
*/
const offscreenNodes = new Set<string>()
/**
* Nodes whose session runs on ANOTHER machine (SSH project terminal, relay/remote-server tab).
* Published by the node itself, because the answer is a union of two independent facts only it can
* see (`offscreenRemoteRef`). Read by the hibernation sweep at PLAN time — see the policy's
* `remote` field for why excluding these only at the exit was not enough.
*/
const remoteNodes = new Set<string>()
function setNodeRemote(nodeId: string, remote: boolean): void {
if (remote) remoteNodes.add(nodeId)
else remoteNodes.delete(nodeId)
}
/** Does this node's session live on another machine? Unknown answers `false` (a node that has not
* reported is local until it says otherwise; the exit closure re-asks at fire time regardless). */
export function isNodeRemote(nodeId: string): boolean {
return remoteNodes.has(nodeId)
}
/**
* The open kanban card modal's node, if any — the ONE thing that makes a node "being looked at"
* without the canvas observer knowing: the modal co-attaches the same tmux session over a canvas
* nobody can see, so its node is off-screen by every measurement and is nevertheless the session
* the user has open. Published by Canvas (which owns the modal), kept HERE so that the watched
* question has exactly one answer for all of its askers.
*/
let watchedNodeId: string | null = null
export function setWatchedNode(nodeId: string | null): void {
watchedNodeId = nodeId
}
/** How long a freshly mounted node waits before asking to be woken: the spawn its resume line is
* written into is still in flight at mount (no session id, no pane). */
const WAKE_MOUNT_DELAY_MS = 2000
/** Bounded retries for a wake that came back `'not-eligible'` — timing, not a standing refusal. */
const WAKE_ATTEMPTS = 3
const WAKE_RETRY_MS = 4000
function setNodeOffscreen(nodeId: string, offscreen: boolean): void {
if (offscreen) offscreenNodes.add(nodeId)
else offscreenNodes.delete(nodeId)
}
/**
* Node ids with a live relay (phone) viewer attached — fed by Canvas from `agent:remote-viewers`
* (main sends the full set each change, never a delta, so a dropped event cannot strand a stale
* entry). A phone viewer is a THIRD way to be watched, invisible to both of `isNodeWatched`'s
* older eyes (the canvas observer and the kanban modal) — before this, Eco could `/exit` a CLI
* someone was actively reading on their phone.
*/
const remotelyViewedNodes = new Set<string>()
/** Replace the remotely-viewed set (Canvas's `agent:remote-viewers` listener is the one caller). */
export function setRemotelyViewedNodes(nodeIds: readonly string[]): void {
remotelyViewedNodes.clear()
for (const id of nodeIds) remotelyViewedNodes.add(id)
}
/**
* "Is the user looking at this session RIGHT NOW?" — the one predicate behind every hibernation
* decision that turns on attention: the sweep's plan, the exit closure's fire-time re-ask, and the
* post-mark nudge. It has to be ONE function: the first version of this feature asked the question
* three times, and the fire-time copy was missing the modal clause — so a card modal opened
* mid-batch could still have `/exit` typed into it.
*
* Three ways to be watched, and only the first is visible to any observer: the node is on screen,
* its kanban card modal is open (see `watchedNodeId`), or a phone viewer is attached to its
* session over the relay (`remotelyViewedNodes`). Unknown answers WATCHED — a node whose observer
* has not delivered yet must never be read as "nobody is looking", which is the direction that
* quits a session out from under someone.
*/
export function isNodeWatched(nodeId: string): boolean {
return (
!offscreenNodes.has(nodeId) || watchedNodeId === nodeId || remotelyViewedNodes.has(nodeId)
)
}
/**
* Each mounted node publishes its wake trigger here, so anything that means "the user is looking
* at this session now" can ask for the conversation back without owning the machinery: the sweep
* itself (a node hibernated in the same tick the user panned back to it), and the kanban card
* modal (a second, equally real way of opening a session — the canvas visibility observer says
* nothing about it).
*
* Same park-surviving reason as `restartSubs`: no entry = nobody is mounted = nothing to wake.
*/
const wakeSubs = new Map<string, () => void>()
/** Ask a node to resume its hibernated CLI. No-op if it is not mounted, or not hibernated (the
* node re-reads the flag itself — this is a nudge, never an assertion). */
export function wakeHibernatedNode(nodeId: string): void {
wakeSubs.get(nodeId)?.()
}
/**
* The mounted instance publishes its copy-feedback sink here, for the same reason as
* `restartSubs`: the OSC 52 handler is registered ONCE per xterm instance and that instance
* SURVIVES A PARK (project switch → remount within the park window), so a handler holding this
* component's `setState` would be feeding a component that unmounted two projects ago. Looked up
* at call time instead. No entry = nobody is mounted = nothing to show.
*/
const copySubs = new Map<string, (text: string) => void>()
/** The right-click link menu's sink, published for the same reason as `copySubs`: the listener
* (`installLinkContextMenu`) is installed once per xterm instance and survives a park. */
const linkMenuSubs = new Map<string, (target: LinkMenuTarget, x: number, y: number) => void>()
function getCo(key: string): CoState {
return coStates.get(key) ?? NO_CO
}
function setCo(key: string, patch: Partial<CoState>): void {
const prev = getCo(key)
const next = { ...prev, ...patch }
// A no-op write must stay a no-op: applyFit clears the letterbox on every fit, and handing the
// node a fresh object each time would re-render it for nothing (and, solo, on every resize tick).
//
// EVERY field must be compared, not a hand-kept subset. The list used to stop at `offline`, so a
// patch that changed ONLY `spawnError` was swallowed here — the "terminal could not be started"
// overlay silently never rendered from a bare `{ spawnError }` write, and the new `staleCwd`
// banner would have been born with the same fault. If you add a CoState field, add it here.
if (
next.letterbox === prev.letterbox &&
next.closed === prev.closed &&
next.ended === prev.ended &&
next.offline === prev.offline &&
next.spawnError === prev.spawnError &&
next.staleCwd === prev.staleCwd &&
next.lostSession === prev.lostSession &&
next.launchTooLongBytes === prev.launchTooLongBytes &&
next.geminiRetired === prev.geminiRetired &&
next.resumeSkipped === prev.resumeSkipped
)
return
coStates.set(key, next)
coSubs.get(key)?.(next)
}
/**
* A single terminal node: header (collapse + color + title + close), optional tag chips,
* and a real xterm.js terminal. A hover guard delays entering the terminal so the canvas
* can be panned across terminals without grabbing focus. Cmd/Ctrl+M (while hovered)
* toggles a markdown view of the terminal's output. Files dropped from Finder are pasted
* as their (escaped) paths, like a native terminal — so Claude can read dropped images.
*/
export function TerminalNode({
id,
data,
selected,
parentId,
// True for the whole of a node drag, flipped synchronously by React Flow at gesture start and
// end. Read only by the glyphgrid participation decision below (a dragged terminal is about to
// be above other nodes, so it renders its OWN opaque pixels for the gesture); every other
// renderer mode destructures it and never looks at it again.
dragging,
// React Flow's own absolute position (a group parent's chain already resolved), updated per
// frame during a drag. Read only by the glyphgrid origin sync below; for every other renderer
// mode these two are destructured and never looked at again.
positionAbsoluteX,
positionAbsoluteY
}: NodeProps<CanvasNode>) {
const { updateNodeData, deleteElements, getZoom, setNodes, getNode } = useReactFlow()
// This node's core api (a context read — stable for the session's lifetime, so using it
// inside the once-mounted lifecycle effect is safe and never re-runs that effect). Core-bound
// namespaces (pty, fs) go through it; app-global ones (clipboard, shell) stay on the global.
const session = useSession()
const { api } = session
// The project whose nodes this node's subtree renders (Canvas: the project React Flow's store
// holds). Read by the create path in the once-mounted lifecycle effect, so a ref.
const owningProject = useOwningProjectId()
const owningProjectRef = useRef(owningProject)
owningProjectRef.current = owningProject
// A hosted team tab whose role is below Editor (false everywhere else): no "Restart in folder" —
// it recycles the session, which the host refuses for them.
const hostedReadOnly = useHostedReadOnly(session.id)
// The path dialect belongs to the core that owns this tab's filesystem, not necessarily this
// browser/window. Server Edition and relay tabs can be viewed from a different OS, so their
// core reports `process.platform` through the already-core-bound tmux status call. Keep it in a
// ref: resolving this fact must not tear down and respawn the terminal lifecycle effect.
const corePlatformRef = useRef<string | null>(null)
useEffect(() => {
let live = true
corePlatformRef.current = null
void hostPlatformFor(api).then((platform) => {
// A failed read is not evidence of Linux. fileLinkDialect fails closed for server/relay;
// only the local desktop may use its viewer as the host because they are the same process.
if (live) corePlatformRef.current = platform
})
return () => {
live = false
}
}, [api])
// The ACTIVE project's presence — where our focus/blur casts go. It follows the active project,
// not this node's provider: Canvas keys the node subtree's SessionProvider on the project React
// Flow's STORE holds (`useFlowStoreOwner`), which flips one commit after the active id. Usually a
// node mounts once its project is the active one, so the value the once-mounted lifecycle effect
// below captures is the presence of the core this node runs on: a relay tab reports focus over the
// relay core, a local tab hits `defaultPresence` (byte-identical to before). NOT always: when the
// last team tab closes, the welcome screen sets the active project to null while the store still
// holds the team project's nodes, and in a rapid A→B→C switch the store can hold B while C is
// active. In those windows this node's `useSession()` (its own core) and this presence (the active
// project's) can point at different cores. The effect is negligible today: those nodes cannot be
// focused (the welcome screen covers them; B's nodes unmount once C lands). Reading this node's
// own session's presence instead is a follow-up.
const presence = useActiveSessionPresence()
/**
* THIS node's agent-status store: the store of the session it renders under, i.e. the status
* table of the core it actually runs on. For the local session that is the default persisted
* instance — the exact object `useAgentStatus` exports — so a local node reads and writes what it
* always did. For a RELAY / team tab it is that session's keyless store, which the session's own
* `agent:status` subscription feeds (`wireRelayAgentStatus`, plus the join-time snapshot), so the
* node shows its HOST session's status: the badge, the unread dot, the session chip. Never the
* default store for a relay node: a handed-off SSH project shares its node ids with the team tab
* now serving them, and the two must not read or mark each other's status.
*
* EVERY agent-status read and write in this node goes through it; nothing here touches the
* default store (`useAgentStatus`) directly, and that is pinned
* (nodes/terminal-agent-status.source.test.ts). That covers: the badge (`status`) and everything
* derived from it, every focus mark (`setActive` / `clearUnread`: the dwell, a click, a "go to
* node" focus, selection, a file insert, the lifecycle teardown), the OSC session-title chip, the
* Esc / Ctrl-C interrupt inference (`agentStatusSession.inferInterruptAfterSettle`, bound to this
* same store), the memory levers that must not kill live work (`readAgentState`,
* `readAgentProcess`, the park's `readSessionEnded`), the in-place restart's busy check, pause
* (both depths), the hibernate / wake pair and its auto-wake triggers, the liveness check, the cold
* restore, the Eco viewer-release deferral and the held-launch dep tooltips (`erroredDepIds`,
* `interruptedDepIds`, `useSuccessWait`).
*
* Several of those RUN on a relay session, which is why none of them may read another table: the
* plain restart (only its clearEnv / model-switch / restartShell branches refuse relay), a SHALLOW
* pause (deliberately allowed over relay; only `deep` refuses), the wake / resume, the liveness
* poll (over the session api), the dep tooltips. Reading the default store there would judge the
* node by — and write into — the entry a handed-off SSH project holds under the same node id (a
* restart that saw `undefined` would quit a host session the badge shows as RUNNING). The rest are
* refused on relay before they act (the cold auto-resume: `session.source !== 'relay'`; the Eco exit:
* `offscreenRemoteRef`, true for a relay session; deep pause, restartShell, model switch,
* clearEnv), so reading the session store there changes nothing and keeps ONE rule. A relay
* node's own status also protects its park — `persistent:false` can arrive from a tmux-less relay
* HOST, i.e. a plain-shell agent session on someone else's machine. The status-driven readers that
* would act on THIS machine are switched off for a relay node by `gates` below
* (`relayStatusGates`).
*
* Stable for the session's lifetime (memoized by api identity), so the once-mounted lifecycle
* effect and the registered closures may close over it.
*/
const agentStatusSession = useSessionStores().agentStatus
const agentStatusStore = agentStatusSession.store
const readAgentState = useCallback(
(): AgentState | undefined => agentStatusStore.getState().byId[id]?.state,
[agentStatusStore, id]
)
/** Mirror for the mount-stable visibility observer, which is keyed on `termKey` alone and takes
* everything mutable through a ref (see its docblock). */
const readAgentStateRef = useRef(readAgentState)
readAgentStateRef.current = readAgentState
// Session-scope the module-global node-keyed maps (parkedTerminals / coStates / coSubs /
// restartSubs / noParkIds): a relay tab adopts the host's project KEEPING node ids, so a local
// node and a relay node can share a bare id. `session.id` is stable for this node's lifetime
// ('local' for the local session, relay-N for a relay tab — both survive project switches), so
// `termKey` is stable across a park→remount of the same terminal yet distinct across sessions.
const termKey = terminalKey(session.id, id)
// The transport is ALWAYS `LocalTransport` over THIS session's api — one protocol, no
// RemoteTransport. For the local session `api.pty` is the preload; for a relay tab it is Task 5's
// bridged pty (the relay tunnel), so LocalTransport over the bridged api IS the remote transport.
// The session's api is stable for the node's lifetime, so the instance is created once and held.
const transportRef = useRef<TerminalTransport | null>(null)
if (!transportRef.current) {
transportRef.current = new LocalTransport(api)
}
const transport = transportRef.current
// Scoped selectors (not the whole settings object) so this node only re-renders when a
// field it actually uses changes — not on every unrelated settings edit.
const panHoverDelay = useSettings((s) => s.settings.panHoverDelay)
// Issue #757: does the keyboard follow the pointer (hover dwell in, mouseleave out — the default)
// or a click (Mac-style: the clicked terminal keeps it until focus really moves elsewhere)? Read
// live, so toggling it in Settings applies to every mounted node without a remount.
const focusFollowsPointer = resolveFocusFollowsPointer(
useSettings((s) => s.settings.terminalFocusFollowsPointer)
)
// One shallow-compared subscription for the whole appearance slice — see useXtermVisualSettings.
// Scoped to the OWNING project so its `terminal.theme` / `terminal.fontFamily` layer over the
// global settings for this node, and for no other project's nodes.
// `data.terminalFontSize` is this node's own ⌘+ / ⌘− size (issue #915), layered last by the hook
// so the card modal (which passes the same value) re-options through the identical path.
const visual = useXtermVisualSettings(owningProjectId(), data.terminalFontSize)
// Mirrored for the lifecycle effect, which builds a NEW xterm on a refresh (`respawnNonce`) or an
// offscreen revive without remounting — the [visual, glass] live-options effect does not re-run
// then, so the instance must be born with the effective appearance (the node's font override, the
// project's theme/font), not the bare global settings (review round 2 of #915).
const visualRef = useRef(visual)
visualRef.current = visual
// The GLOBAL size the shared glyph atlas is rasterized for (see `fontLeavesAtlas`).
const globalFontSize = useSettings((s) => s.settings.fontSize)
// Glass terminals (Settings → Appearance): xterm paints no background and the node supplies a
// translucent tint of THIS node's effective theme (lib/useTerminalGlass.ts).
const { glass, tint, vars: glassVars } = useTerminalGlass(visual.terminalTheme)
const frostRef = useFrostLayer()
// The alpha app-painted cell backgrounds follow on this node (null = not glass, stock rendering).
// A ref too, because `acquireWebgl` (inside the lifecycle closure) syncs every fresh addon to it.
const glassCellAlphaRef = useRef<number | null>(null)
// The live WebGL addon, for the one job of installing the glass cell-background wrap when glass
// turns on after the context was granted. May point at a disposed addon; installing on one is a
// no-op (the wrap finds no renderer), and the next grant installs on the fresh one.
const webglAddonRef = useRef<WebglAddon | null>(null)
// The account list, for the chip and for the READERS below: a config dir the user links while
// this pane sits quiet must resolve to its new account immediately, not at the next hook event.
const claudeAccounts = useSettings((s) => s.settings.claudeAccounts)
// Header buttons the user chose to hide (Settings). A selector, so toggling one re-renders every
// mounted node right away instead of waiting for a remount. Search, Close and the worktree-move
// button are absent from `isHidden`'s inventory and stay put whatever the list says.
const hiddenHeaderButtons = useSettings((s) => s.settings.hiddenHeaderButtons)
const bodyRef = useRef<HTMLDivElement>(null)
const middleClickPaste = useSettings((st) => st.settings.terminalMiddleClickPaste)
// Chromium pastes the X PRIMARY selection into xterm's hidden textarea on middle click — a path
// this app never built and the user could not switch off (issue #84). Its own effect, keyed on
// the setting alone, so it applies to a PARKED terminal being re-adopted just as much as to a
// fresh one: the guard belongs to the host ELEMENT, not to the pty lifecycle.
useEffect(() => {
const host = bodyRef.current
if (!host) return
return guardMiddleClickPaste(host, () => middleClickPaste)
}, [middleClickPaste])
// OUR root (`.term-node`), not React Flow's wrapper — the element whose box changes when the
// node's CHROME changes (header chips, the find bar). Observed alongside the terminal host so a
// chrome change can never leave the glyph grid measured at its old offset; see the second
// ResizeObserver in the lifecycle effect.
const rootRef = useRef<HTMLDivElement>(null)
const termRef = useRef<Terminal | null>(null)
// Copy feedback: the `Copied` pill (fed by the OSC 52 handler below, through `copySubs`) and the
// one-time "hold ⌥ to select" hint for a pane whose app captured the mouse.
// The host is `bodyRef` (`.term-node__xterm`) and NOT the node body on purpose: the hover guard
// (`.term-hover-guard`) is a SIBLING of that element, so pre-dwell drags — the ones that MOVE the
// node — never reach this listener. Hosting it on `.term-node__body` would make every node-move
// drag a hint candidate and burn the once-per-installation hint on a gesture that has nothing to
// do with copying.
// OFF for an agent whose own CLI reports its copies (`reportsOwnCopy` — claude prints "copied N
// chars to tmux buffer" itself), so that terminal is byte-identical to before the feature.
// `createdAgentId` is called again here rather than reusing the `agentId` const below: this hook
// sits above it, and duplicating a pure read of `data` is cheaper than reordering declarations
// in this file's lifecycle block.
const copy = useCopyFeedback({
hostRef: bodyRef,
hasSelection: () => !!termRef.current?.hasSelection(),
enabled: !reportsOwnCopy(createdAgentId(data))
})
useEffect(() => {
copySubs.set(termKey, copy.notifyCopy)
return () => {
if (copySubs.get(termKey) === copy.notifyCopy) copySubs.delete(termKey)
}
}, [termKey, copy.notifyCopy])
// Right-click on a link in the output → open / reveal / download / copy (terminal/link-menu.ts).
// The listener lives in the lifecycle effect and reaches this state through `linkMenuSubs`.
const [linkMenu, setLinkMenu] = useState<{ x: number; y: number; target: LinkMenuTarget } | null>(
null
)
useEffect(() => {
const sink = (target: LinkMenuTarget, x: number, y: number): void => setLinkMenu({ x, y, target })
linkMenuSubs.set(termKey, sink)
return () => {
if (linkMenuSubs.get(termKey) === sink) linkMenuSubs.delete(termKey)
}
}, [termKey])
// The file links resolve against the ACTIVE project's filesystem (see `projectFs` in the
// lifecycle effect), so Download follows it too: an SSH project's file comes down over scp. Two
// primitive selectors, not the project object — that is rebuilt on every node serialization.
const activeProjectId = useProjects((s) => s.activeProjectId)
const activeIsSsh = useProjects((s) => !!s.projects.find((p) => p.id === s.activeProjectId)?.ssh)
const linkDlCtx = { browser: isBrowserRuntime(), ssh: activeIsSsh, source: session.source }
const linkDownloads = useDownloads({
route: downloadRoute(linkDlCtx),
projectId: activeProjectId || undefined,
files: api.files
})
/** The link menu's rows, read against the project as it is when the menu opens. Every action
* reuses the channel Cmd+click, the Explorer or the file-manager node already goes through. */
const linkMenuRows = (target: LinkMenuTarget) => {
const project = useProjects.getState().getProject(activeProjectId ?? '')
// Literal event names on purpose: nodeterm-events.test.ts pairs every dispatch with its
// listener by reading `new CustomEvent('nodeterm:…'` out of the source.
const send = (ev: CustomEvent): void => void window.dispatchEvent(ev)
return linkMenuItems(
target,
{
route: downloadRoute(linkDlCtx),
localShell: canUseLocalShell(linkDlCtx),
// The Explorer drawer's own root (ExplorerPanel: `ssh ? ssh.remoteCwd : project.cwd`).
explorerRoot: project?.ssh ? project.ssh.remoteCwd : project?.cwd,
terminals: session.source !== 'relay',
downloading: (p) => linkDownloads.rowDl[p] === 'running'
},
{
openUrl: (url) => window.nodeTerminal.shell.openExternal(url),
// A browser node is an Electron `<webview>`; in a browser tab it would render nothing.
openUrlInNode: linkDlCtx.browser
? undefined
: (url) =>
send(new CustomEvent('nodeterm:open-url-node', { detail: { url, sourceNodeId: id } })),
copy: (text) => window.nodeTerminal.clipboard.writeText(text),
openFile: (abs) =>
send(
new CustomEvent('nodeterm:open-file', { detail: { path: abs, ssh: activeIsSsh, view: true } })
),
revealInExplorer: (abs) =>
send(new CustomEvent('nodeterm:reveal-file', { detail: { path: abs } })),
revealInOs: (abs) => window.nodeTerminal.shell.reveal(abs),
openTerminal: (dir) =>
send(new CustomEvent('nodeterm:open-terminal', { detail: { cwd: dir } })),
download: (abs, dir, pickFolder) =>
void (pickFolder ? linkDownloads.downloadTo(abs, dir) : linkDownloads.download(abs, dir))
}
)
}
const fitRef = useRef<FitAddon | null>(null)
const searchAddonRef = useRef<SearchAddon | null>(null)
// The live session's "measure my grid, render it, report it" routine (set by the lifecycle
// effect), so effects outside that closure (font/cursor changes) resize through the same path.
const applyFitRef = useRef<(() => void) | null>(null)
// The lifecycle effect's guaranteed full-viewport repaint, reachable from the appearance effect
// outside that closure (a theme swap must not be left to a refresh that can be swallowed).
const fullRepaintRef = useRef<(() => void) | null>(null)
// This project shows the KANBAN board (an opaque overlay over the canvas). While it does, this
// canvas terminal is not visible — but it is still a co-attach subscriber, and its (often
// zoomed-small) grid would clamp a CARD-MODAL viewer of the same session to a tiny size, pushing
// an agent's input box off the bottom. So while the board is up we report "not viewing" (null),
// exactly like a park, and the visible modal drives the shared grid. A node only ever lives in the
// ACTIVE project's React Flow, so the active project's view is the one that matters.
const omniKanbanEnabled = useSettings((s) => isOmniKanbanEnabled(s.settings))
const boardOpen = useViewMode(
(s) =>
(omniKanbanEnabled && s.globalKanban) ||
viewFor(s, useProjects.getState().activeProjectId ?? '') === 'kanban'
)
const boardOpenRef = useRef(boardOpen)
// The live session's board render pause (attached by the lifecycle effect): while the board
// covers this node, xterm stops DRAWING but keeps parsing. Synced from the two effects that
// already re-run on what "covered" reads — the board flag and focus mode. See
// `terminal/board-render-pause.ts`.
const [boardPauseSlot] = useState(createBoardPauseSlot)
const dwellRef = useRef<ReturnType<typeof setTimeout> | null>(null)
const [showColors, setShowColors] = useState(false)
const [armed, setArmed] = useState(true)
const [dropping, setDropping] = useState(false)
// Overlay while dropped files upload to an SSH host (scp is seconds-long with zero feedback);
// doubles as a brief "Upload failed" flash when nothing made it.
const [uploadNote, setUploadNote] = useState<{ text: string; failed?: boolean } | null>(null)
const pasteReceipt = usePasteReceipt()
const uploadNoteTimer = useRef<ReturnType<typeof setTimeout> | null>(null)
useEffect(() => () => {
if (uploadNoteTimer.current) clearTimeout(uploadNoteTimer.current)
}, [])
const [naming, setNaming] = useState(false)
// Is a glyph grid attached RIGHT NOW? Drives the `term-node--glyphgrid` class on the node ROOT,
// which is what turns the node into a transparent window onto the shared canvas (see styles.css).
// React state, not an imperative `classList.add`: the root's className is recomputed from
// `selected`/`unread`/`working`/… on many renders and React rewrites the whole attribute when it
// changes, so a class added behind React's back would be wiped by the next selection change.
const [glyphMounted, setGlyphMounted] = useState(false)
// Bumped whenever the shared context was dropped and this node owes a re-registration. It exists
// to move the RE-SETUP out of the (synchronous) generation notification and into an effect that
// runs after the font options have reached xterm — see the participation effect below.
const [glyphEpoch, setGlyphEpoch] = useState(0)
// Is this node in the shared layer's OPAQUE SET — i.e. does its body currently sit over another
// node, so that a transparent glyph window would let that node show through? See the stacking
// rule at `opaqueNodeIds`.
//
// READ AT RENDER TIME, never mirrored into state, and that is the whole ordering fix. Canvas
// computes and stores the set during ITS render, and React renders a parent before its children —
// so this read always sees the answer for the same `nodes` array that produced the `dragging`
// prop and the position we are rendering with. Held in state instead, it lagged by a commit, and
// the lag was visible: on the commit that ended a drag this node re-attached a glyph against the
// stale set and tore it down again one pass later, flashing transparent over the node it had just
// been dropped on. Same window on create-into-overlap and project-load-with-overlaps.
//
// The subscription exists for the ONE case a render-time read cannot cover: this node's own
// object did not change (so it did not re-render) and something else slid underneath it. It
// forces a re-render, and only when OUR membership actually flipped — a set change elsewhere on
// the canvas must not re-render every terminal. `glyphOpaqueRef` is the last value we rendered
// with, written below on every render so the two paths cannot disagree.
const [, bumpGlyphOpaque] = useState(0)
const glyphOpaque = nodeIsOpaque(id)
const glyphOpaqueRef = useRef(glyphOpaque)
glyphOpaqueRef.current = glyphOpaque
useEffect(() => {
const read = (): void => {
const now = nodeIsOpaque(id)
if (now === glyphOpaqueRef.current) return
glyphOpaqueRef.current = now
bumpGlyphOpaque((n) => n + 1)
}
// Once on (re-)subscribe: the set can have been pushed between this node's render and this
// effect, and nothing would notify us about a change we were not yet listening for.
read()
return subscribeOpaqueSet(read)
}, [id])
// Focus mode (issue #78) — same render-time read + subscription shape as `glyphOpaque` above,
// for the same ordering reason: the `glyphOff` term computed this render must agree with the
// reparent this same commit performs, or the shared-glyph teardown runs a pass behind the DOM.
const [, bumpFocused] = useState(0)
const focused = focusedNodeId() === id
const focusedRef = useRef(focused)
/** True only while focus mode's reparent is moving the root (see reparentKeepingFocus). */
const reparentingRef = useRef(false)
focusedRef.current = focused
useEffect(() => {
const read = (): void => {
const now = focusedNodeId() === id
if (now === focusedRef.current) return
focusedRef.current = now
bumpFocused((n) => n + 1)
}
read()
return subscribeFocusedNode(read)
}, [id])
// The reparent itself: move the WHOLE node root into the focus surface, imperatively. Not a
// React portal — switching a portal container unmounts/remounts the subtree, which recreates
// the xterm host div while the lifecycle effect (keyed on respawnNonce) never re-runs; the
// terminal would go blank. Moving the host element is the operation park/adopt already proved
// safe: every listener the terminal owns is bound to `term.element` or the host, not to a
// position in the tree. useLayoutEffect + cleanup, so the node is back under React's recorded
// parent BEFORE React ever detaches it (the commit-phase removeChild would throw otherwise) —
// the cleanup runs on unfocus AND ahead of unmount (project switch while focused).
useLayoutEffect(() => {
if (!focused) return
const root = rootRef.current
const surface = focusSurfaceEl()
if (!root || !surface) return
// Shared mode: the grid teardown must land in THIS commit, before paint. The participation
// effect below is passive (after paint), so without this a fullscreen frame paints while the
// grid is still registered at the old on-canvas position and the node still wears the
// glyph-mode styling (transparent body, rows hidden) — one blank frame per ⌘⇧F. The passive
// effect then re-runs with the same answer and no-ops. (Review finding on #267.)
glyphSyncRef.current?.(false)
const home = root.parentElement
// The move blurs a focused xterm (MEASURED) — give it back, and tell click-to-focus the blur
// is ours, not the user leaving (reparentKeepingFocus).
const setMoving = (moving: boolean): void => {
reparentingRef.current = moving
}
reparentKeepingFocus(root, surface, setMoving)
return () => {
try {
if (home) reparentKeepingFocus(root, home, setMoving)
} catch {
/* home unmounted with the project — React already gave up on this subtree */
}
}
}, [focused])
const [editingTitle, setEditingTitle] = useState(false)
const hoveredRef = useRef(false)
// Render-fresh respawnNonce for the lifecycle cleanup: React updates this ref (render) before
// running the old effect's cleanup, so the cleanup can tell a respawn (nonce changed → dispose,
// spawn fresh) from a plain unmount (nonce unchanged → park for quick re-adoption).
const respawnNonceRef = useRef(data.respawnNonce)
respawnNonceRef.current = data.respawnNonce
// --- offscreen dispose (see terminal/offscreen-policy.ts) ---
// A terminal nobody has looked at for `settings.offscreenTerminalMinutes` gives its xterm buffer
// and its PTY client back: the node STAYS MOUNTED on the canvas and its tmux session keeps
// running, so coming back into view is a warm reattach (tmux redraws — the same contract as the
// Refresh action and the post-park remount). `offscreenDown` renders the plate and makes the
// lifecycle effect spawn nothing; `offscreenEpoch` is what re-runs that effect on BOTH edges
// (down → its cleanup disposes, up → it spawns fresh). The ref mirror exists because the
// decision is taken inside the lifecycle effect's IntersectionObserver closure, which cannot
// see fresh state.
const [offscreenDown, setOffscreenDown] = useState(false)
const offscreenDownRef = useRef(false)
const offscreenTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
/** When the current offscreen stretch began (null = on screen). The Eco deferral's cap is
* measured against it, so it is stamped once per stretch, not per observer callback. */
const offscreenSinceRef = useRef<number | null>(null)
const [offscreenEpoch, setOffscreenEpoch] = useState(0)
/** The visibility observer's last verdict. Component-level (not per-lifecycle-run) because it
* must survive an offscreen dispose and because a budget client registered by a later run needs
* the CURRENT answer — see `ensureWebglClient`. */
const wasVisibleRef = useRef(false)
/** What the CURRENT lifecycle run wants done with a visibility verdict (budget report + the
* hidden→visible repaint heal). Null exactly while this node has no terminal: between runs, and
* for the whole time it is offscreen-disposed. The observer that calls it is mount-stable. */
const visibilityReportRef = useRef<((visible: boolean) => void) | null>(null)
/** Is there a live session here that could be given back? Published by the lifecycle run
* (`restartTarget`), null between runs — the dispose timer refuses when it cannot ask. */
const offscreenLiveRef = useRef<(() => boolean) | null>(null)
/** Does the CURRENT session survive losing its client (tmux, local or remote)? Published by the
* lifecycle run from `PtyCreateResult.persistent` — the offscreen release reads it to decide
* whether disposing this terminal would end a running agent (`wouldKillLiveWork`). Read only
* AFTER `offscreenLiveRef` has confirmed a live session, so a value left over from a torn-down
* run is never acted on. Seeded `true`: the historical assumption, never a protection on a
* guess. */
const sessionPersistentRef = useRef(true)
// Selection is a live veto (`mayDisposeOffscreen`): a selected node is one the user is working
// with — it can be off-screen mid-drag or right after a ⌘K jump — so it is never taken down.
const selectedRef = useRef(selected)
selectedRef.current = selected
// Is this node holding a `--after` launch? Read at release FIRE time (see `fireRelease`) — the
// hold ends when the launch fires, and a plan made at arm time would not know.
const armedRef = useRef(!!data.pendingLaunch)
armedRef.current = !!data.pendingLaunch
// --- glyphgrid (experimental shared renderer) ---
// This node's registered grid, published by the lifecycle effect so the position effect can push
// an origin without re-running (and therefore respawning) the terminal. Null for every terminal
// in the default renderer modes, which is what makes the effects below a single null check.
const glyphGridRef = useRef<GridHandle | null>(null)
const glyphBodyOffsetRef = useRef<Vec2>({ x: 0, y: 0 })
/** The PLATE's box in NODE-relative layout coordinates — the body's offset inside the node plus
* its client size. Kept apart from `glyphBodyOffsetRef` (which tracks `.xterm-screen`) because
* plate and grid are independent rects; the position effect below re-derives the plate's world
* origin from this while the node is dragged, without re-measuring the DOM per frame. */
const glyphPlateBoxRef = useRef<{ offset: Vec2; w: number; h: number } | null>(null)
// Mutated (never reassigned) so the lifecycle effect's closures read the CURRENT position without
// re-running; a drag rewrites these two numbers per frame.
const nodePosRef = useRef<Vec2>({ x: positionAbsoluteX, y: positionAbsoluteY })
nodePosRef.current.x = positionAbsoluteX
nodePosRef.current.y = positionAbsoluteY
// Re-evaluate this node's participation in the shared canvas (set by the lifecycle effect).
const glyphSyncRef = useRef<((on: boolean) => void) | null>(null)
// Live mirrors for the once-mounted onTitleChange listener (its `[]`-deps closure can't see
// fresh props/state): whether the title still auto-tracks the session, whether the rename box
// is open (don't clobber mid-edit), and the current title (skip no-op updates).
const titleAutoRef = useRef(data.titleAuto !== false)
const editingTitleRef = useRef(false)
const titleRef = useRef(data.title as string)
// Rename-box bookkeeping: the value when editing began (for Escape-revert) and a one-shot
// flag so the blur that follows Enter/Escape doesn't commit a second time.
const titleEditStartRef = useRef('')
const skipBlurRef = useRef(false)
const mdMode = !!data.mdMode
// Read by the "take the keyboard" paths (dwell, click, sidebar jump), which are closures that
// outlive a render: while the ⌘M view covers the terminal they must not focus the hidden xterm.
const mdModeRef = useRef(mdMode)
mdModeRef.current = mdMode
const collapsed = !!data.collapsed
// "This node must NOT hold a grid on the shared canvas right now." Four states, two reasons:
//
// - NOT ON SCREEN — collapsed hides the body outright (`display: none`), the ⌘M view covers it
// with an opaque panel. A grid left registered through either would keep painting its last
// frame on the shared canvas at the node's world rect, with nothing of ours in front of it.
// - MUST BE OPAQUE — the node is stacked over another node (`glyphOpaque`), or it is being
// DRAGGED, which is the same thing a moment early. A shared-mode body is a transparent window,
// so a terminal that is on top of something has to paint its own pixels or the node beneath it
// shows through. See the stacking rule at `opaqueNodeIds`.
//
// Mirrored into a ref for the lifecycle effect's closures (which cannot see fresh props), and
// read by `setupGlyph` itself — the mount-time setup runs from that effect, not from the
// participation effect below, so the gate has to live where every caller passes through it.
// `focused` is a MUST-BE-OPAQUE reason (issue #78): a focus-mode node is reparented out of the
// React Flow viewport, so the shared layer's glyphs — positioned from on-canvas geometry —
// would paint somewhere the node no longer is. Routes through the same setup/teardown the
// collapse/⌘M/stacking/drag reasons always used; v1 deliberately forces the DOM/WebGL path.
// `fontLeavesAtlas` is a MUST-BE-OPAQUE reason too (issue #915 review): the shared atlas is
// rasterized for the GLOBAL font with a cell fixed at `register`, so a node rendering at its own
// ⌘+/⌘− size would keep painting old-size glyphs over a pty that was resized to the new cell.
// Holding it off the shared canvas makes it paint its own pixels; clearing the override rejoins.
// `visual` is declared above, so this reads the same effective size xterm is re-optioned with.
const fontLeavesAtlas = leavesSharedGlyphAtlas(visual.fontSize, globalFontSize)
const glyphOff = collapsed || mdMode || glyphOpaque || dragging || focused || fontLeavesAtlas
const glyphOffRef = useRef(glyphOff)
glyphOffRef.current = glyphOff
// The NOT-ON-SCREEN half on its own. `setupGlyph`'s gate needs to tell the two reasons apart:
// a terminal that is merely covered up has no pixels to accelerate, while one held opaque is
// fully visible and painting its own — so the latter must be a WebGL budget client, exactly like
// a default-mode terminal. That is the "never both renderers, and never NEITHER" invariant.
const glyphHiddenRef = useRef(collapsed || mdMode)
glyphHiddenRef.current = collapsed || mdMode
// Derive the node's agent once, through the shared helper — the canvas menu decides whether to
// offer this node's in-place restart from the SAME derivation, and a second copy drifting from
// this one yields a row whose closure refuses every click.
const agentId = createdAgentId(data)
/** Is an agent CLI believed to be running in this pane right now? The created agent, else one a
* hook event identified (a hand-launched CLI). Read through a ref by the release/park levers. */
const readAgentProcess = (): boolean => {
const st = agentStatusStore.getState().byId[id]
return agentProcessInPane(agentId ?? st?.agentId, st)
}
const readAgentProcessRef = useRef(readAgentProcess)
readAgentProcessRef.current = readAgentProcess
// Gate each former `isClaude` site by the capability it actually represents.
const showStatus = !!agentId && hasHooks(agentId) // status badge + session-title capture
const showLoop = !!agentId && canRecur(agentId) // /loop · /schedule · /cron chrome
const contextLinkCapable = !!agentId && canContextLink(agentId) // context-link tip wording only; handles render on all terminals
const showUsage = !!agentId && hasUsage(agentId) // per-node context-window meter
const showChat = !!agentId && canChat(agentId) // Cmd+M opens a chat panel instead of markdown
// Claude Remote Control toggle (header, right of the context meter). Not on a relay tab: the
// on/off signal is this machine's transcript tail, which never sees a guest core's session.
const showRemoteControl = !!agentId && canRemoteControl(agentId) && session.source !== 'relay'
// Everything that reads the conversation through CLAUDE's transcript readers (`context.ensure`'s
// mount-time meter rehydration, the find bar's transcript index) — deliberately NOT `showUsage`,
// which now spans three agents. See lib/transcriptGates.ts for what sharing that gate broke.
const claudeTranscript = readsClaudeTranscript(agentId)
// The header 💬 now opens the board-log comments flyout (right side); ⌘M keeps the markdown/chat view.
const [commentsOpen, setCommentsOpen] = useState(false)
const rawWriteRef = useRef<((data: string) => void) | null>(null)
const canRenameNode = !!agentId && canRename(agentId) // WRITE leg: push `/rename <name>` back
// READ leg: adopt the agent's own session name into the title. A superset of canRenameNode —
// gemini names its own sessions but has no rename command, so it polls and never pushes.
const canReadTitleNode = !!agentId && canReadTitle(agentId)
const agentLabel = (agentId ? agentConfig(agentId) : undefined)?.label ?? 'Agent'
// Could this node's CLI ever be hibernated — quit AND brought back? A durable property of the
// agent, not of its current state: the offscreen release consults it to decide whether waiting
// for Eco is even meaningful here (see `shouldDeferReleaseForEco`).
const hibernationTarget = !!agentId && canResume(agentId) && !!exitSequence(agentId)
const hibernationTargetRef = useRef(hibernationTarget)
hibernationTargetRef.current = hibernationTarget
// Keep the listener's mirrors current every render.
titleAutoRef.current = data.titleAuto !== false
editingTitleRef.current = editingTitle
titleRef.current = data.title as string
// "Move into worktree" affordance: shown only when this terminal is a child of a group that
// or one of its ancestor groups is bound to a worktree AND its current cwd differs from that
// worktree path (i.e. it's still running in the old folder). Reads the group chain from React
// Flow state (single source of truth); `parentId` is set by the group reparenting transforms.
// A STALE group (its worktree directory was deleted outside the app) must NOT offer the move:
// "move" destroys this node's tmux session — killing whatever is running in it — and respawns it
// in the worktree path, which no longer exists. pty-manager would silently fall back to $HOME and
// `data.cwd` would persist the dead path forever, which not even Unbind undoes. The chip already
// says "· missing"; the ↪ must agree with it.
const parentWorktree = (() => {
const seen = new Set<string>()
let groupId = parentId
while (groupId && !seen.has(groupId)) {
seen.add(groupId)
const group = getNode(groupId) as CanvasNode | undefined
const path = group?.data.worktree?.path as string | undefined
if (path) return { groupId, path }
groupId = group?.parentId
}
return undefined
})()
const parentWtPath = parentWorktree?.path
const parentWtStale = useWorktrees((s) =>
parentWorktree ? s.staleGroupIds.includes(parentWorktree.groupId) : false
)
// …and a session that runs on ANOTHER MACHINE must not offer it either. Worktrees are local-only
// in v1, so ↪ would end this node's REMOTE tmux session and respawn it in a local path that does
// not exist on the host. Both halves of "remote" are asked: the project (its terminals and its git
// run over ssh — a local project that LATER became an SSH one still carries the old binding, and
// its worktree directory may well still exist locally, so nothing else here would notice) and the
// node (`isRemoteSessionNode` — an SSH-project terminal carries `data.ssh`/`data.sshRemoteTmux`).
// The affordance is absent, not merely refused on click.
const sshProject = useProjects((s) => !!s.projects.find((p) => p.id === s.activeProjectId)?.ssh)
const portsProjectId = useProjects((s) => s.activeProjectId)
// The project's SSH endpoint, as two primitives: the project object is rebuilt on every node
// serialization, so selecting `ssh.server` itself would re-render this node on each canvas edit.
const projectSshHost = useProjects((s) => s.getProject(s.activeProjectId)?.ssh?.server.host)
const projectSshUser = useProjects((s) => s.getProject(s.activeProjectId)?.ssh?.server.user)
const showSshChip =
!!data.ssh &&
!sshChipRepeatsProject(
data.ssh as SshConnection,
!!data.sshRemoteTmux,
projectSshHost !== undefined ? { host: projectSshHost, user: projectSshUser ?? '' } : undefined
)
const remoteSession = sshProject || isRemoteSessionNode(data)
// "Does this node's session live on another machine?" for the offscreen-dispose gate — asked in
// TWO halves, because the two ways of being remote are independent facts:
// 1. the PROJECT is an SSH project / this node is an SSH-project terminal (`remoteSession`, the
// same question the ↪ affordance asks), and
// 2. the SESSION's core is elsewhere (`offscreenCoreIsRemote`): a RELAY tab's terminals run on
// the paired desktop, a remote-server tab's on that server. Nothing on the node's `data` says
// so — that is a property of the tab it renders under — which is why this half must be asked
// of `session.source` and not of a node field. (The Server Edition's own browser session is
// `'local'`: its core is the server it is served from, up whenever the UI is, so those nodes
// stay eligible — the whole point of the feature on that surface.)
// Both are excluded in v1 (offscreen-policy.ts): a revive re-runs the spawn path, and doing that
// while the ControlMaster or the relay link happens to be down surfaces the offline overlay / a
// spawn error on a node the user never touched.
//
// `isRemoteSessionNode` is deliberately NOT widened for this: it is the worktree gate, and
// worktrees exclude relay nodes on purpose (that gate asks a different question). The union
// belongs here, at the one call site that means it. A ref because a project can BECOME an SSH
// project long after the lifecycle run that would otherwise have captured the answer.
const offscreenRemoteRef = useRef(false)
offscreenRemoteRef.current = remoteSession || offscreenCoreIsRemote(session.source)
// …and published for the hibernation sweep, which needs the same answer at PLAN time (see the
// policy's `remote` field: excluding these only at the exit let two remote nodes occupy both
// batch slots forever). Re-published whenever it changes — a local project can become an SSH one.
const nodeIsRemote = offscreenRemoteRef.current
useEffect(() => {
setNodeRemote(id, nodeIsRemote)
return () => setNodeRemote(id, false)
}, [id, nodeIsRemote])
const canMoveIntoWorktree =
!!parentWtPath &&
!parentWtStale &&
!remoteSession &&
(data.cwd as string | undefined) !== parentWtPath
const getTerminalKillLine = (): string => {
return terminalKillLine({
source: session.source,
browserRuntime: isBrowserRuntime(),
viewerWindows: isWindowsPlatform(),
corePlatform: corePlatformRef.current,
remoteSession,
shell: data.shell || useSettings.getState().settings.defaultShell || undefined
})
}
const status = agentStatusStore((s) => s.byId[id])
// Which status-driven readers this node may run (see relay-status-gates.ts): all of them on the
// local session, none on a relay / team tab, whose status is its host's.
const gates = relayStatusGates(session.source)
/**
* Which Claude account this node is ACTUALLY on. `data.accountId` is what nodeterm launched
* it as and is immutable; `status.account` is what the session's hooks reported — the only
* identity a plain terminal running `CLAUDE_CONFIG_DIR=~/.claude-2 claude` ever has.
*
* The chip and every READER below use the effective id, so a node that was never created AS an
* account but runs as one reads that account's transcripts. NOT the spawn env: launch identity
* stays creation-time (`transport.create` keeps passing `data.accountId`).
*/
const observedAccount = status?.account
const accountChip = useAccountChip(
data.accountId,
observedAccount,
agentStatusStore,
data.ssh ? sshHostKey(data.ssh as SshConnection) : undefined
)
// This node's team (the stations it opened), published by Canvas from the live ropes. The store
// keeps each unchanged team's array identity, so this re-renders only when THIS team changes.
const team = useTeamStations((s) => s.byNode.get(id))
const accountForReads = effectiveAccountId(data.accountId, observedAccount, claudeAccounts)
/** Mirror for the session-name poll, whose effect must not restart when a late hook event
* finally reveals the account (see its comment). */
const accountForReadsRef = useRef(accountForReads)
accountForReadsRef.current = accountForReads
// Fan-out (subagent/loop card) visibility + tidy — any agent capable of either kind of card.
const fanoutCapable = !!agentId && (canSubagent(agentId) || canRecur(agentId))
const hideFanout = !!data.hideFanout
const fanoutCount = useAgentNodes(
(s) => Object.values(s.byId).filter((v) => v.parentNodeId === id).length
)
// Transient, per-launch: what this node's Codex launcher reported it actually got. Undefined for
// every non-codex node and for a codex node whose launcher never spoke.
const codexIdentity = useCodexIdentity((s) => s.byId[id])
// --- Eco / hibernation wake (see terminal/hibernation-policy.ts) ---
// A hibernated node's CLI was asked to `/exit` while nobody was looking; its tmux session, pane
// and scrollback are untouched, and the conversation comes back with the provider's own
// `--resume`. THREE things ask for that here, all through one function:
// 1. the visibility observer, on the offscreen→visible edge (the everyday path);
// 2. mount-while-already-visible — a node the canvas opens ON SCREEN never transitions, so
// after a relaunch (the flag is persisted) nothing would ever ask;
// 3. the SLEEPING chip's own click, which is also the escape hatch when the two above have
// given up.
// Never fired more than once at a time (`wakeInFlightRef`, plus `guardConcurrentRestart` inside
// the registered closure), and always re-reads the flag: a wake that raced another one, or a
// sweep that landed in between, must not deliver a second launch line into the same pane.
const wakeInFlightRef = useRef(false)
const wakeTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
// A wake types the resume line into this pane un-KILL_LINE'd (its "most fragile moment"), and the
// keyboard path writes straight to the transport throughout. This bounded buffer HOLDS anything
// the human types between `beginWake` and the resume's confirmed submit, then flushes it in order
// (a `resumed` outcome) or drops it (any other) — so nothing splices into the resume line. See
// wake-input-buffer.ts; the keyboard interception is in `term.onData` below, the writer is the
// session-scoped `restartIo.write` published here so the wake `.then` (component body) can reach it.
const wakeInputBufferRef = useRef(new WakeInputBuffer())
const paneWriteRef = useRef<(data: string) => void>(() => {})
const wakeRef = useRef<(attempt?: number) => void>(() => {})
/** The liveness check's own asker, published by its effect for the reveal edge to call. */
const livenessAskRef = useRef<(() => Promise<void>) | null>(null)
wakeRef.current = (attempt = 0): void => {
// A wake that could not run YET is retried a couple of times: at mount the spawn is still in
// flight, and a node coming back from an offscreen DISPOSE re-registers its pair one render
// later than the visibility edge that asked. Past the attempts it is a standing refusal (the
// pane belongs to something else now) and the chip's click is the way forward — nothing keeps
// typing into a pane on a timer.
const retryLater = (): void => {
if (attempt + 1 >= WAKE_ATTEMPTS) return
if (wakeTimerRef.current) clearTimeout(wakeTimerRef.current)
wakeTimerRef.current = setTimeout(() => wakeRef.current(attempt + 1), WAKE_RETRY_MS)
}
if (wakeInFlightRef.current) return
// Answers a manual Resume for BOTH pause depths, not only ordinary hibernation: a `paused`
// node may or may not also be `hibernated` (the deep "pause & end session" recycles the tmux
// session instead, leaving `hibernated` unset), but either flag means there is a conversation
// this closure knows how to bring back.
const stNow = agentStatusStore.getState().byId[id]
// `dropped` joins the two pause flags here because it is the same job with a different cause:
// the pane holds a bare shell and there is a conversation this closure knows how to bring back.
// The resume half is what makes it safe to admit — it re-reads the pane itself and refuses
// anything that is not a shell, so a node whose CLI came back on its own between the verdict
// and the click is declined rather than typed into.
if (!stNow?.hibernated && !stNow?.paused && !stNow?.dropped) return
const fns = agentHibernateFns(id)
if (!fns) return retryLater() // no terminal here yet (mid-spawn, or an offscreen revive)
wakeInFlightRef.current = true
// Hold keyboard input from HERE — before the resume line's first byte — until the resume
// resolves. `beginWake` is idempotent, so a retry that re-enters keeps what is already held.
wakeInputBufferRef.current.beginWake()
void fns
.resume()
.then((outcome) => {
// Flush on a confirmed resume (the held keystrokes land after the resume line submitted),
// drop on anything else (`expired` — the pane became something we did not resume into).
wakeInputBufferRef.current.endWake(outcome === 'resumed', paneWriteRef.current)
if (outcome === 'resumed') {
agentStatusStore.getState().setHibernated(id, false)
agentStatusStore.getState().setPaused(id, false)
// The resume line is in the pane; the CLI's own SessionStart will confirm it shortly, but
// the chip must not survive the click that answered it.
agentStatusStore.getState().setDropped(id, false)
return
}
// 'not-eligible' — usually timing, not a refusal that will stand: at mount the spawn is
// still in flight (no session id yet), and right after a reveal tmux may not have answered
// `paneCommand` yet. See `retryLater`.
//
// …unless the resume half wrote a REASON. That is its standing refusals only (the pane
// belongs to something else now, or the record predates the proof) — the transient one
// leaves the field null on purpose. Retrying a standing refusal only burns the attempts
// that the genuinely-transient cases need, and re-asks a question whose answer cannot
// change without the user doing something. The chip carries the sentence; its click is
// the way forward, and it re-checks.
if (agentStatusStore.getState().byId[id]?.wakeBlocked) return
retryLater()
})
.catch(() => {
// A transport that threw leaves the node hibernated (and the chip clickable). Reporting a
// wake here would clear the badge over a pane nothing was typed into — and the held input is
// dropped, never spliced into whatever the pane became.
wakeInputBufferRef.current.endWake(false, paneWriteRef.current)
})
.finally(() => {
wakeInFlightRef.current = false
})
}
// Ask once shortly after mount, for the node that is ALREADY visible: its observer reports
// `visible` with no preceding hidden verdict, and an environment without IntersectionObserver
// reports nothing at all. Delayed because the spawn this wake writes into is still in flight at
// mount. Skipped while the node is known-offscreen — the reveal edge owns that case.
useEffect(() => {
// Published for the two askers that are not this node: the sweep (a node hibernated in the
// very tick the user panned back to it) and the kanban card modal.
const trigger = (): void => wakeRef.current()
wakeSubs.set(id, trigger)
const t = setTimeout(() => {
// A `paused` node never auto-wakes, mount included — the trigger published above (and the
// chip's own click) remain the explicit way back. `hibernated`-only nodes are unaffected:
// this is the everyday Eco auto-resume-on-view path. See `shouldAutoWake`.
const stMount = agentStatusStore.getState().byId[id]
if (isNodeWatched(id) && shouldAutoWake(stMount?.hibernated, stMount?.paused)) wakeRef.current()
}, WAKE_MOUNT_DELAY_MS)
return () => {
clearTimeout(t)
if (wakeSubs.get(id) === trigger) wakeSubs.delete(id)
if (wakeTimerRef.current) {
clearTimeout(wakeTimerRef.current)
wakeTimerRef.current = null
}
// This node is leaving the canvas: it is nobody's hibernation candidate until it reports
// again. (Absent = not offscreen; see `offscreenNodes`.)
setNodeOffscreen(id, false)
}
}, [id, agentStatusStore])
/**
* LIVENESS — did this node's agent CLI die without telling us? (See `agent-liveness.ts` for the
* rule and every refusal in it; this effect only supplies the pane reading and records the
* verdict.)
*
* WHEN it asks is the whole cost story. `paneCommand` is one tmux `display-message` — measured at
* 4 ms against a local socket, one exec channel on an existing ControlMaster for an SSH project —
* but a canvas can hold fifty agent nodes, and fifty of anything on a timer is a background load
* nobody asked for. So this asks only for a node that is BOTH watched (on screen, or a kanban
* card modal is open on it) and already believed to be a parked agent: a `done` node that is
* neither hibernated nor paused. Everything else costs one map lookup and no I/O.
*
* The cadence is deliberately coarser than the badge feels: the verdict is about a process that
* is already gone and is not going to come back on its own, so re-asking fast buys nothing. The
* reveal edge is what makes it feel immediate — the user looks at the node, and a check runs then.
*
* `null` (a lapsed or failed read) leaves the previous verdict ALONE rather than clearing it: a
* ControlMaster that drops must not quietly retract a DROPPED chip and leave a dead session
* looking healthy. `looksDropped` already refuses to raise one on `null`; this is the other half.
*/
useEffect(() => {
let stopped = false
let asking = false
const ask = async (): Promise<void> => {
if (asking || stopped) return
const st = agentStatusStore.getState().byId[id]
// Cheap gate first, so a canvas of healthy or plain-terminal nodes never reaches the pane.
// Note it admits an ALREADY-dropped node too: that is how the chip clears itself when the
// user relaunches the CLI by hand (no hook has to arrive for the pane to answer).
if (!st?.dropped && !looksDroppedCandidate(agentId, st?.state, st?.hibernated, st?.paused))
return
if (!isNodeWatched(id)) return
asking = true
try {
const pane = await queryPaneWithin(() => api.pty.paneCommand(id), LIVENESS_QUERY_MS)
if (stopped || pane === null) return
// Re-read: the await is long enough for a turn to have started, or for the user to have
// paused the node from the menu.
const now = agentStatusStore.getState().byId[id]
agentStatusStore
.getState()
.setDropped(
id,
looksDropped({
agentId,
state: now?.state,
hibernated: now?.hibernated,
paused: now?.paused,
pane
})
)
} catch {
// Same contract as `null` — an unreadable pane is never evidence either way.
} finally {
asking = false
}
}
// Published for the reveal edge below (the visibility observer is not a subscribable store, so
// the edge calls this rather than this effect re-running on it). Identity-checked on clear.
livenessAskRef.current = ask
void ask()
const t = setInterval(() => void ask(), LIVENESS_POLL_MS)
return () => {
stopped = true
clearInterval(t)
if (livenessAskRef.current === ask) livenessAskRef.current = null
}
}, [id, agentId, api, agentStatusStore])
// Held launch (canvas-control `--after`). Canvas owns firing it; the node only surfaces that
// it is armed, and by WHAT it is blocked — dep titles read straight off the live canvas, since
// "waits for term-17" tells the user nothing.
const pendingLaunch = data.pendingLaunch as PendingLaunch | undefined
// What the delivery loop has to say about this node's held launch, if anything. Absent is the
// ordinary case (still waiting on a dependency); the two states it can carry are the ones that
// used to be invisible — see the store. Selected by id so an unarmed node never re-renders on
// another node's delivery.
const observedLaunchDelivery = useLaunchDelivery((s) => s.byId[id])
const launchDelivery = observedLaunchDelivery ?? (pendingLaunch?.manualOnly
? { kind: 'failed' as const, attempts: 1, at: 0 } : undefined)
// A headless start (#925) is typing this node's launch from core: the badge says so, without the
// warning, and ▶ stands aside — a click would splice a second copy into the pane.
const startingNow = launchDelivery?.kind === 'starting'
// A node's own first-open launch still in flight hides the chip (lib/pendingLaunch — the board
// card asks the same predicate).
const firstOpenInFlight = isFirstOpenInFlight(!!data.initialCommand, pendingLaunch, observedLaunchDelivery)
// `--after-success`: where the wait stands (lib/useSuccessWait — the hold through the shape rule,
// its stations, and the tooltip, which flips to EXPIRED on its own deadline tick).
const successWait = useSuccessWait(
pendingLaunch?.afterSuccess,
(depId) => {
const n = getNode(depId) as CanvasNode | undefined
return n ? ((n.data.title as string) || '') : undefined
},
agentStatusStore
)
// The stations a `--after-success` wait names are ALSO in `after`; the tooltip speaks of them in
// the success sentence, so the plain list leaves them out rather than naming them twice.
const successDepIds = successWait.depIds
const pendingWaitingOn = [
...(pendingLaunch?.after ?? []).filter((depId) => !successDepIds.includes(depId)).map(
(depId) => ((getNode(depId) as CanvasNode | undefined)?.data.title as string) || depId
),
// The other thing a launch can be held on: this worktree's project setup script. Named, or the
// tooltip on a setup-only hold would read "Waiting for to finish".
...(pendingLaunch?.awaitSetupGroup ? ['the project setup script'] : [])
].join(', ')
// Which of those deps are held because their last turn ERRORED (issue #521) — an errored station
// is idle, so without naming them the tooltip would promise a wait that will never end on its
// own. Selected as a joined string so the selector returns a primitive and an unarmed node never
// re-renders on another node's status.
const erroredDepIds = agentStatusStore((s) => {
const after = pendingLaunch?.after ?? []
if (!after.length) return ''
// Same liveness rule `depSatisfied` uses: a dep that is gone counts as satisfied, so it is
// not something this node is held on and must not be named as one.
const live = new Set(after.filter((d) => !!getNode(d)))
return erroredDeps({ id, data: { pendingLaunch } }, s.byId, live).join(',')
})
// Same selector shape for deps held because the user interrupted their last turn (Esc/Ctrl+C).
const interruptedDepIds = agentStatusStore((s) => {
const after = pendingLaunch?.after ?? []
if (!after.length) return ''
const live = new Set(after.filter((d) => !!getNode(d)))
return interruptedDeps({ id, data: { pendingLaunch } }, s.byId, live).join(',')
})
// `--after-pr`: what the pull requests this node waits on look like, from the same status the
// launch loop judges (the canvas's watch keeps it coming). Selected only for a node that has a
// PR wait, so no other node re-renders on a GitHub update.
const prHold = pendingLaunch?.afterPr
const prProjectId = useProjects((s) => (prHold ? s.activeProjectId : null))
const prBoard = useGitHubIssues((s) => (prHold && prProjectId ? pullBoardFor(s, prProjectId) : undefined))
// Nothing in any store changes when a deadline passes, so the badge sets its own timer to turn
// EXPIRED on time (one per armed node, cleared with it).
const [, setPrClock] = useState(0)
useEffect(() => {
if (!prHold || prHoldExpired(prHold, Date.now())) return
const t = setTimeout(() => setPrClock((v) => v + 1), Math.min(prHold.deadlineAt - Date.now() + 50, 2 ** 31 - 1))
return () => clearTimeout(t)
}, [prHold])
const prExpired = !!prHold && prHoldExpired(prHold, Date.now())
const prTooltip = prHold
? {
expired: prExpired,
summary: prHold.invalid ? 'a pull request wait that could not be read' : prHoldSummary(prHold, prBoard),
deadline: prHold.invalid ? 'the project file holds an unreadable one' : new Date(prHold.deadlineAt).toLocaleString()
}
: undefined
const successTooltip = successWait.tooltip
const successExpired = successTooltip?.status === 'expired'
const successBlocked = successTooltip?.status === 'blocked'
// Which deps were handed new work they have not finished (core/station-handover.ts): their `done`
// is from before it, so the tooltip says what the wait is really for. A primitive, like above.
const handedOverDepIds = useStationHandovers((s) => {
const after = pendingLaunch?.after ?? []
if (!after.length) return ''
const live = new Set(after.filter((d) => !!getNode(d)))
return handedOverDeps({ id, data: { pendingLaunch } }, live, s.byId)
.map((d) => `${d}:${holdReason(s.byId[d])}`)
.join(',')
})
const pendingHandedOverOn = handedOverDepIds
? handedOverDepIds
.split(',')
.map((entry) => {
const [depId, reason] = entry.split(':')
const title = ((getNode(depId) as CanvasNode | undefined)?.data.title as string) || depId
return reason === 'background'
? `${title} (tasks still running in its background)`
: `${title} (the work just handed to it)`
})
.join(', ')
: undefined
const pendingErroredOn = erroredDepIds
? erroredDepIds
.split(',')
.map((depId) => ((getNode(depId) as CanvasNode | undefined)?.data.title as string) || depId)
.join(', ')
: ''
const pendingInterruptedOn = interruptedDepIds
? interruptedDepIds
.split(',')
.map((depId) => ((getNode(depId) as CanvasNode | undefined)?.data.title as string) || depId)
.join(', ')
: ''
// Which session this node's transcript READERS look at: the hook-confirmed id, else the id the
// node was launched with (`data.agentSessionId`) — ONE rule shared with the kanban card modal
// (lib/transcriptSession.ts). A fallback reads strictly by id and says so in the chat panel.
const transcript = transcriptSessionFor({
live: status?.sessionId,
persisted: data.agentSessionId,
cwd: (data.cwd as string) || undefined
})
// Use the chat panel only for a chat-capable agent with a known session; otherwise the
// markdown-of-output view (computed in the capture effect below) is shown as a fallback.
// `chatAvailable` is split out because the label-row ⌘M hint names the face BEFORE it is open:
// one value feeds both, so the hint cannot say "Chat view" while the chord opens markdown.
// `gates.chatView`: a relay / team tab keeps the Markdown output view (its transcript reads are
// refused over the relay; the output view captures the host's pane).
const chatAvailable = showChat && !!transcript.sessionId && gates.chatView
const useChat = mdMode && chatAvailable
useContextEnsure(session.api.context, id, agentId, transcript.sessionId, transcript.cwd, accountForReads)
const updateNodeInternals = useUpdateNodeInternals()
const [searchOpen, setSearchOpen] = useState(false)
// Set when the session fell back to the system account because this node's account folder was
// missing at spawn (Task 3 fallback) — flags the account chip with a warning tint + tooltip.
const [accountFallback, setAccountFallback] = useState(false)
// Co-attach state published by the (park-surviving) transport listeners — see CoState.
const [co, setCo_] = useState<CoState>(() => getCo(termKey))
useEffect(() => {
coSubs.set(termKey, setCo_)
setCo_(getCo(termKey)) // catch up anything published while this instance was mounting
return () => {
if (coSubs.get(termKey) === setCo_) coSubs.delete(termKey)
}
}, [termKey])
// Publish this instance's restart trigger for the (park-surviving) onRecycled listener — see
// restartSubs. Bumping `respawnNonce` re-runs the lifecycle effect below, which is exactly what
// the mover's own canvas does; the transient nonce is never persisted.
useEffect(() => {
const restart = (): void =>
updateNodeData(id, (n) => ({
respawnNonce: ((n.data.respawnNonce as number | undefined) ?? 0) + 1
}))
restartSubs.set(termKey, restart)
return () => {
if (restartSubs.get(termKey) === restart) restartSubs.delete(termKey)
}
}, [termKey, id, updateNodeData])
// The name of the peer who closed this node. Read NON-reactively (getState, not a selector): the
// presence store is written at cursor rate and its perf contract reserves subscriptions for the
// presence components — a per-terminal subscriber would run on every one of those writes. The
// overlay is terminal state anyway, so resolving the name when `co.closed` appears is enough.
// `co.closed.by` is a ClientId from THIS node's active-session transport, and ClientIds are
// per-presence-session — so resolve the name against the ACTIVE session's peer table, not the
// local default (else a relay tab shows "another user" / a wrong name). Byte-identical on a
// local tab (active presence IS the default).
const closedName = co.closed ? closedByLabel(co.closed.by, presence.store.getState().peers) : ''
// "Session ended" (a recycle whose replacement never came — see CoState.ended): the user asks for
// a shell explicitly. Only now do we spawn, in THIS client's cwd — no silent stale-cwd respawn.
const reopenEnded = (): void => {
setCo(termKey, { ended: false })
updateNodeData(id, (n) => ({
respawnNonce: ((n.data.respawnNonce as number | undefined) ?? 0) + 1
}))
}
// A spawn that FAILED (CoState.spawnError): nothing was started, so there is nothing to detach
// from — just clear the message and re-run the lifecycle effect. Whether it works depends on
// whatever core reported (a freed file descriptor, a host that came back), which is exactly why
// the message is on screen rather than in a log.
const retrySpawn = (): void => {
setCo(termKey, { spawnError: null })
updateNodeData(id, (n) => ({
respawnNonce: ((n.data.respawnNonce as number | undefined) ?? 0) + 1
}))
}
// "Restart in folder" (CoState.staleCwd, issue #464): the warm-reattached shell sits on a
// DELETED directory inode, which no `cd` we could inject would be allowed to fix (text into a
// pane is injection) and which re-creating the folder can never heal. The recovery is the same
// recycle-then-respawn the model switch and "restart shell" use: core ends the tmux session
// (reserving the replacement for this client), the respawn re-validates `data.cwd` and starts a
// fresh shell in the re-created folder. Explicit user action only — the session may hold live
// work, which is exactly why nothing here runs on its own.
const restartInFolder = (): void => {
setCo(termKey, { staleCwd: false })
transport.recycle(id)
updateNodeData(id, (n) => ({
respawnNonce: ((n.data.respawnNonce as number | undefined) ?? 0) + 1
}))
}
const dismissStaleCwd = (): void => setCo(termKey, { staleCwd: false })
const dismissLostSession = (): void => setCo(termKey, { lostSession: false })
const dismissResumeSkipped = (): void => setCo(termKey, { resumeSkipped: false })
const dismissGeminiRetired = (): void => setCo(termKey, { geminiRetired: false })
// Canvas owns node creation; a terminal node has no direct line to it (same pattern as the
// file-manager's `nodeterm:open-terminal`). The new node lands beside this one, in its frame.
const openAntigravityNode = (): void => {
window.dispatchEvent(
new CustomEvent('nodeterm:open-agent', { detail: { agentId: 'antigravity', nearNodeId: id } })
)
}
const dismissLaunchTooLong = (): void => setCo(termKey, { launchTooLongBytes: null })
// "Not connected" (CoState.offline): the host was unreachable, so this node has no session
// anywhere. Ask the coordinator to re-establish the project's master NOW — it flushes the
// pending nodes (this one included) on success, which is what respawns them. We do NOT bump
// `respawnNonce` ourselves: a respawn before the master is back would just re-run the same
// 20s wait and land right back here.
const reconnectOffline = (): void => {
// The SCOPE, not the project: an attached node's master belongs to its host attachment, and
// retrying the local project's (nonexistent) connection would never bring this node back.
const conn = data.ssh as SshConnection | undefined
const projectId = conn ? sshConnectionScope(conn) : useProjects.getState().activeProjectId
if (projectId) sshRetryHandler?.(projectId, [id])
}
// Stable fallback reader: serialize the live xterm buffer when tmux capture is unavailable.
const readBuffer = useCallback(() => {
const t = termRef.current
if (!t) return ''
const b = t.buffer.active
// Array + join, not `s +=`: repeated concat over up to 50k lines churns O(n²) string bytes.
const lines = new Array<string>(b.length)
for (let i = 0; i < b.length; i++) lines[i] = b.getLine(i)?.translateToString() ?? ''
return lines.join('\n')
}, [])
const search = useTerminalSearch({
nodeId: id,
sessionId: status?.sessionId,
cwd: data.cwd as string | undefined,
// A READER: the search hits the transcript index under whichever account the session is
// actually running as, not the one the node was created with.
accountId: accountForReads,
// The transcript index reads claude's JSONL through the same resolver, so it is gated on the
// claude-transcript fact, NOT on the meter's `showUsage` — see lib/transcriptGates.ts. And on
// `gates.transcriptSearch`: it reads THIS machine's transcripts, never a relay host's.
searchTranscript: gates.transcriptSearch && claudeTranscript,
open: searchOpen,
readBuffer
})
// Single source of truth for the on-screen highlight colors (used by both the
// initial-highlight effect and the prev/next nav handlers below).
const findOpts = {
decorations: FIND_DECORATIONS
}
// Navigation steps the hook's authoritative cursor AND xterm's on-screen highlight.
// The two intentionally desync (the hook also counts transcript-only matches that
// xterm can't highlight) — that's expected; this only tracks navigation direction.
const handleNext = useCallback(() => {
search.next()
if (search.query.trim()) searchAddonRef.current?.findNext(search.query, findOpts)
}, [search])
const handlePrev = useCallback(() => {
search.prev()
if (search.query.trim()) searchAddonRef.current?.findPrevious(search.query, findOpts)
}, [search])
// The link handles are added/positioned dynamically; make React Flow re-measure them so edges
// anchor to the (centered) handle, not a stale position. Rendered on all terminal nodes now.
useEffect(() => {
updateNodeInternals(id)
}, [id, updateNodeInternals])
// Terminal lifecycle — set up once on mount, and again whenever `respawnNonce` is bumped
// (e.g. moving this terminal into a worktree). Bumping the nonce runs the cleanup below
// (kill the old session + dispose xterm), then recreates the session with the latest
// `data.cwd`. The node `id` (= tmux persistKey) is unchanged, so it's the same target.
useEffect(() => {
// Offscreen-disposed: this node gave its xterm + PTY client back and is showing the plate.
// Spawn NOTHING until it is approached again (the observer below clears the flag and bumps the
// epoch, which re-runs this effect). Returning no cleanup is deliberate: there is nothing of
// this effect's to tear down, and the down transition's own cleanup already ran.
if (offscreenDownRef.current) return
const container = bodyRef.current
if (!container) return
/**
* Kernel truth about this node's pane, within the same budget the pane-command polls use.
*
* One `display-message` plus one `ps` locally (one ControlMaster exec channel for a remote
* pane), and it is asked at most twice per hibernation — once before the exit, once after it —
* for at most `HIBERNATE_BATCH_MAX` nodes a sweep. It is deliberately NOT on any timer: the
* question it answers is only meaningful at the instant something is about to be written.
*
* `null` on anything that is not a clean answer, including the deadline: every caller treats
* that as "we cannot see this pane", which is a refusal on both sides of the pair.
*/
const readPaneOwner = async (): Promise<PaneOwner | null> => {
let lapse: ReturnType<typeof setTimeout> | undefined
try {
return await Promise.race([
api.pty.paneOwner(id),
new Promise<null>((r) => {
lapse = setTimeout(() => r(null), RESTART_EXIT_TIMEOUT_MS)
})
])
} catch {
return null
} finally {
clearTimeout(lapse)
}
}
/** The binary names this node's agent actually runs as. Passed explicitly so a CUSTOM agent is
* verifiable from its own launch command — without it `binariesFor` cannot name a
* `custom:<uuid>` and answers `unknown`, which here is a refusal, i.e. Eco silently off for
* every custom agent on the canvas. */
const paneBinaries = (): readonly string[] | null =>
agentId ? binariesFor(agentId, useSettings.getState().settings.customAgents) : null
// Adopt-or-create: a parked terminal (this node unmounted within the park window) is
// re-adopted with its live PTY session and full xterm state intact; otherwise a fresh
// xterm + session are built. `myNonce` vs the render-updated ref tells the cleanup below
// whether it runs for a respawn (worktree move — must NOT park) or a plain unmount.
const myNonce = data.respawnNonce
const parked = parkedTerminals.get(termKey)
if (parked) {
parkedTerminals.delete(termKey)
parked.timer.cancel()
}
// An ADOPTED terminal is already typeable — the same live session, the same settled shell —
// and its spawn continuation ran on a previous mount, so it will never reach the publish
// below. A fresh one starts NOT ready: this effect also re-runs for a respawn and for an
// offscreen revive, and both replace the session a stale `true` would describe.
setSessionReady(id, !!parked)
const s = useSettings.getState().settings
// Appearance comes from ONE place, shared with the kanban card modal's viewer of this same
// session (`ModalTerminal`) — see `xtermOptionsFromSettings`.
const term =
parked?.term ?? new Terminal(xtermOptionsFromSettings(visualRef.current, isLiquidGlass(s.appTheme)))
// A hosted team's Viewer/Commenter watches and never types: keystrokes and pastes are not taken
// at all (the host refuses pty:write for them anyway). Set only for such a tab — every other
// session never touches the option. The role is known before the session exists (relay-tab).
if (isHostedReadOnly(session.id)) term.options.disableStdin = true
// Only on a FRESH instance: a parked terminal already carries the table, and the buffer it kept
// alive was measured with it — re-registering under a live buffer buys nothing.
if (!parked) activateUnicode11(term)
const fit = parked ? parked.fit : new FitAddon()
const searchAddon = parked ? parked.search : new SearchAddon()
termRef.current = term
fitRef.current = fit
searchAddonRef.current = searchAddon
// GPU renderer: xterm's default DOM renderer doesn't scale to many terminals streaming
// at once. Must load after open(). Browsers cap live WebGL contexts (~16), and a busy canvas
// holds far more terminals than that, so a context is NOT acquired per mounted node. The
// module-level BUDGET COORDINATOR (`webgl-budget.ts`) owns the grant decision and all timing:
// this node reports viewport visibility (via the IntersectionObserver below), and the
// coordinator calls back into `acquireWebgl`/`releaseWebgl`, keeping the total contexts WE hold
// under `WEBGL_BUDGET` so the browser never has to force-evict (which is what flashed the dead
// "lost context" placeholder). The callbacks stay dumb and idempotent.
let webgl: WebglAddon | null = null
let webglHandle: WebglClientHandle | null = null
// (The observer's last verdict lives in the component-level `wasVisibleRef`: it must survive an
// offscreen dispose, and a budget client registered by a LATER run — this one included — needs
// the current answer, not `false`. See `visibilityReportRef`.)
// --- glyphgrid (experimental shared renderer) -----------------------------------------
// Live only while this terminal paints into the shared canvas instead of its own renderer.
// All four stay null for the default modes: `setupGlyph()` returns on its first gate without
// touching a store, a seam or the DOM.
let glyphGrid: GridHandle | null = null
let glyphAttach: GlyphGridAttachment | null = null
let glyphZUnsub: (() => void) | null = null
let glyphGenUnsub: (() => void) | null = null
// One guaranteed full-viewport repaint, deferred a frame. Heals a class of silently LOST
// full refreshes: xterm's own "refresh everything" (renderer swap via setRenderer, the
// deferred unpause refresh, the webgl addon's context-restore redraw) can be swallowed when
// it lands while the element is detached/paused/mid-swap — the webgl renderer's renderRows()
// returns without painting AND without remembering the range while !_isAttached, and the
// addon's webglcontextrestored handler re-inits with no error handling. After a swallowed
// refresh only newly-dirty rows paint: live output over an otherwise blank screen, stuck
// until something re-dirties every row (which is why only the manual refresh action's tmux
// redraw used to fix it). A refresh issued at a moment the element is attached and visible
// cannot be swallowed; on a healthy terminal it is one debounced repaint, and it composes
// with xterm's pause machinery (while hidden it just re-arms _needsFullRefresh).
const fullRepaint = (): void => {
requestAnimationFrame(() => {
if (disposed) return
try {
term.refresh(0, term.rows - 1)
} catch {
// a heal, never worth throwing for
}
})
}
// A palette swap repaints through exactly the path described above, so it is exposed to the
// same swallowed-refresh cases — and half a palette is the most visible way for one to fail.
fullRepaintRef.current = fullRepaint
// --- renderer-swap safety net ---------------------------------------------------------
// xterm treats a renderer swap as atomic; it is not. On macOS under GPU/canvas memory
// pressure, canvas allocation THROWS mid-swap (`throwIfFalsy(getContext('2d'))` in the
// addon's atlas/layers), and both directions strand the terminal BLACK with zero
// JS-visible events — which is why neither the repaint heals nor the zoom gate closed the
// field report alone:
// - activate: the render service is pointed at the webgl renderer BEFORE the parts that
// can throw, so a mid-activate throw leaves a half-built renderer with the DOM renderer
// already disposed (our catch used to just return false and believe we were on DOM);
// - dispose: the addon's canvas is removed INSIDE `setRenderer(createDomRenderer())`, so a
// throw there leaves the canvas attached — and our own loseWebglContexts then turns that
// stray into a permanently-black plate sitting OVER the freshly-painted DOM rows.
/** Put a fresh DOM renderer in place — exactly what the addon's own dispose closure does.
* Internal API, fully guarded; false = couldn't (fall through to the refresh heal). */
const restoreDomRenderer = (): boolean => {
try {
const core = (
term as unknown as {
_core?: {
_renderService?: { setRenderer(r: unknown): void; handleResize(c: number, r: number): void }
_createRenderer?: () => unknown
}
}
)._core
if (!core?._renderService || !core._createRenderer) return false
core._renderService.setRenderer(core._createRenderer())
core._renderService.handleResize(term.cols, term.rows)
return true
} catch {
return false
}
}
/** One automatic refresh (fresh xterm + reattach; tmux repaints) per mount, ever — the
* manual fix users discovered by hand, automated but capped so sustained GPU pressure
* can't respawn-loop a node. */
let swapHealRespawned = false
/** The last-resort heal: refresh this node (fresh xterm + reattach; tmux repaints). Shared by
* the webgl swap-heal and the glyphgrid detach path — one latch, so a node under sustained
* renderer trouble still refreshes at most once per mount. Silent unless a reason is given
* (the swap-heal warns with more context of its own). */
const escalateRespawn = (why?: string): void => {
if (swapHealRespawned) return
swapHealRespawned = true
if (why) console.warn(`[nodeterm] ${why} — refreshing the node`)
updateNodeData(id, (n) => ({
respawnNonce: ((n.data.respawnNonce as number | undefined) ?? 0) + 1
}))
}
/**
* Invariant check for every moment we believe NO webgl addon is active: the screen must
* hold ZERO canvases. A leftover one is the black-terminal signature above. Sweep strays,
* restore a DOM renderer, repaint; refresh the node as a last resort. The console.warn is
* deliberate — it is the field-diagnosable trace of which strand actually fired.
*
* SKIPPED while a glyphgrid attachment is live. This heal's cure is `setRenderer`, which
* silently DISPOSES whatever renderer it replaces — here that would be the glyph addon, and
* the node would go blank while its grid stayed registered and inert. A glyph-attached
* terminal also owns no canvas inside `.xterm-screen`, so there is nothing here to heal.
*/
const verifyCleanDomState = (context: string): void => {
if (disposed || webgl || glyphAttach) return
const strays = term.element
? Array.from(term.element.querySelectorAll('.xterm-screen canvas'))
: []
if (!strays.length) return
for (const c of strays) {
try {
c.remove()
} catch {
// detached mid-sweep — fine
}
}
const restored = restoreDomRenderer()
console.warn(
`[nodeterm] healed a broken webgl swap (${context}): removed ${strays.length} stray canvas(es), ` +
(restored ? 'DOM renderer restored' : 'DOM restore failed → refreshing the node')
)
if (restored) {
fullRepaint()
return
}
escalateRespawn()
}
// Has this terminal EVER gone through a renderer swap? Every stuck-blank strand needs one —
// a node that has only ever run the DOM renderer is covered by xterm's own pause/unpause
// bookkeeping, so the transition heals below skip it (a full DOM repaint per node entering
// the viewport during a pan is real jank, paid for nothing on a never-swapped node).
let everSwapped = false
const acquireWebgl = (): boolean => {
if (webgl) return true
everSwapped = true
let addon: WebglAddon | null = null
try {
const a = new WebglAddon()
addon = a
// The browser lost this context out from under us. Dispose + null the reference so the DOM
// renderer takes over, and tell the coordinator so its accounting drops this grant. The
// NODE never re-acquires from here (a per-node loop is the "Too many active WebGL
// contexts" storm this feature exists to stop) — the COORDINATOR schedules one delayed,
// budget-gated re-grant for a still-visible client (sleep/wake loses every context at
// once with no visibility change; see webgl-budget.ts contextLost).
a.onContextLoss(() => {
try {
a.dispose()
} catch {
// already disposed
}
if (webgl === a) webgl = null
webglHandle?.contextLost()
})
term.loadAddon(a)
webgl = a
// Glass: app-painted cell backgrounds become tinted glass (glass-cell-backgrounds.ts). A
// fresh addon starts from an empty model, so the repaint below already applies the alpha.
// The wrap patches the addon's SHARED renderer prototype, so it is installed only once a
// glass terminal needs it: a user who never turns glass on never runs a patched renderer.
webglAddonRef.current = a
if (glassCellAlphaRef.current !== null) installGlassCellBackgrounds(a)
setGlassCellAlpha(term, glassCellAlphaRef.current)
// THE RESTORE PATH — rebuild, never trust the addon's in-place recovery.
//
// When the GPU process resets (returning from a GPU-heavy app; sleep/wake; memory
// pressure) the browser loses EVERY context on the page and then restores them. That
// restore never reaches `onContextLoss`: the addon arms a 3s timer on
// `webglcontextlost` and CANCELS it when the restore lands, so the coordinator is never
// told and the terminal's recovery is entirely the addon's own handler — which
// re-initializes GL state while the previous context's objects are disposed against the
// NEW context. That is not a theory: forcing a page-wide lose+restore in the harness
// reproduces the field console exactly (`webglcontextrestored` per terminal, then a
// storm of `INVALID_OPERATION: delete: object does not belong to this context`), and in
// the field it left terminals painting their backgrounds with NO GLYPHS — a live
// rectangle renderer over a broken glyph atlas, which no repaint of ours can heal
// (`term.refresh` re-runs the same broken renderer).
//
// So a restore is treated as what it materially is — this context is gone: drop the
// addon (xterm falls back to its DOM renderer synchronously, text visible), sweep the
// stray canvas, and report the loss so the COORDINATOR re-grants a FRESH addon with a
// fresh atlas on its usual path — budget-gated, delayed by
// `WEBGL_REACQUIRE_AFTER_LOSS_MS`, and abandoned after `WEBGL_LOSS_STREAK_MAX` losses so
// an unstable GPU degrades to the DOM renderer instead of being hammered. The listener
// dies with the addon's canvas.
// …on the ADDON's canvas, which is not the first one in `.xterm-screen`: xterm appends its
// own `.xterm-link-layer` (a 2d canvas) ahead of it, so the obvious
// `querySelector('.xterm-screen canvas')` resolves to the LINK LAYER — a canvas that can
// never fire a WebGL event. That is what the listener this replaces was bound to, so the
// restore hook has never once run in the field; verified in the harness by enumerating
// the screen's canvases (index 0 `.xterm-link-layer`, no webgl2 context; index 1
// class-less, webgl2).
const addonCanvas = term.element
? Array.from(term.element.querySelectorAll<HTMLCanvasElement>('.xterm-screen canvas')).find(
(c) => !c.classList.contains('xterm-link-layer')
)
: undefined
addonCanvas?.addEventListener('webglcontextrestored', () => {
if (webgl !== a) return
try {
a.dispose()
} catch {
// the addon's own restore handler may have left it half-built — the sweep below is
// what actually guarantees the terminal is back on a renderer that paints.
}
webgl = null
verifyCleanDomState('context-restored')
fullRepaint()
webglHandle?.contextLost('restored')
})
// A fresh addon starts from an EMPTY model; the swap's own refresh is the exact one
// that gets swallowed when this grant races a park/pause. Repaint unconditionally.
fullRepaint()
return true
} catch {
// WebGL2 unavailable — or activate DIED MIDWAY (see the safety-net note above). The
// back-to-DOM disposable is registered in the same breath as activate's setRenderer, so
// for exactly the throws that got that far, a best-effort dispose restores the DOM
// renderer; the invariant check sweeps whatever a shallower throw left behind. Returning
// false tells the coordinator not to count this as a held context (no budget slot).
try {
addon?.dispose()
} catch {
// half-built beyond dispose — the verify below recovers
}
verifyCleanDomState('acquire-failed')
return false
}
}
const releaseWebgl = () => {
if (!webgl) return
// Capture the element BEFORE dispose (dispose detaches the addon's canvases). After the
// addon is gone, explicitly lose its context: addon dispose() alone leaves the context
// alive until GC, and Chromium counts un-GC'd contexts against its per-page cap — enough
// churn (fast pans cycling grants) and the zombies push the page past the cap, which is
// the "Too many active WebGL contexts" warning + force-evictions the budget exists to
// prevent. Not needed on the onContextLoss path: that context is already lost.
const canvases = term.element ? Array.from(term.element.querySelectorAll('canvas')) : null
try {
webgl.dispose()
} catch (err) {
// A second dispose after onContextLoss already ran is a silent no-op — a THROW here is
// never that. The addon's dispose is ALSO its put-xterm-back-on-a-DOM-renderer path (a
// disposable registered at activate), so a throw aborts the restore and would leave the
// terminal with NO renderer at all: zero canvases, zero `.xterm-rows`, a permanently
// black node no repaint can reach. Seen in the field as the zoom-out blackout when
// addon-webgl 0.19.0's dispose guard read xterm-5.6 internals (`_core._store`) on the
// 5.5 core and crashed on EVERY release. The renderer-less check below is the heal; the
// warn is its field trace.
console.warn('[nodeterm] webgl dispose threw mid-release', err)
}
webgl = null
loseWebglContexts(canvases)
// A dispose that died midway leaves its (now context-lost, permanently BLACK) canvas
// attached OVER the DOM rows — sweep it before the repaint (see the safety-net note).
verifyCleanDomState('release')
// The other way a dispose dies midway: canvases already gone but the DOM renderer never
// installed (the throw above). `verifyCleanDomState` cannot see that state — it keys on
// stray canvases, and here there are none — so probe for the renderer's row container
// directly and rebuild what the addon's aborted restore owed. Skipped while a glyph
// attachment owns the screen (no rows there by design, and `setRenderer` would dispose
// the glyph addon — see the both-renderers invariant).
if (!disposed && !glyphAttach && term.element && !term.element.querySelector('.xterm-rows')) {
if (restoreDomRenderer()) {
console.warn('[nodeterm] healed a renderer-less webgl release: DOM renderer restored')
} else {
escalateRespawn('webgl release left no renderer and the DOM restore failed')
return
}
}
// The DOM renderer that replaced the addon starts from an EMPTY row container, and this
// release almost always runs while the node is HIDDEN — the swap's own refresh defers
// behind xterm's pause flag, which is exactly where it can be lost. Re-arm it explicitly.
fullRepaint()
}
let sessionId: string | null = parked ? parked.sessionId : null
// Does this session survive losing its client (tmux, local or remote)? Read off the create
// result below, carried over when adopting a park. Seeded `true` — the historical assumption —
// so a session whose create has not answered yet, or a core too old to say
// (`PtyCreateResult.persistent` absent), behaves exactly as it always did rather than being
// protected on a guess. See `canDisposePark`.
let sessionPersistent = parked ? parked.tmuxBacked : true
sessionPersistentRef.current = sessionPersistent
let disposed = false
// Last cols/rows REPORTED to the pty (seeded at create): a resize IPC makes tmux redraw the
// whole pane, so a same-size fit (e.g. the ResizeObserver's initial tick right after mount)
// must not send one — on a bulk project load that redraw doubles per node.
// NOT carried over from the park entry: parking REPORTS "not viewing" (null, null), which drops
// this client out of the pty's size set. Keeping the old values would make the common same-size
// adopt send nothing at all — we would never re-enter the set, while still being told to render
// the other viewer's (larger) grid. Zeroed here, so an adopting client always re-reports.
let sentCols = 0
let sentRows = 0
// Whether we've already reported "not viewing" because the kanban board is up (see boardOpen).
// Guards against re-sending the null on every ResizeObserver tick while the board stays open.
let boardParked = false
// What we last REPORTED — the reference the letterbox is measured against — is published to a
// module-level registry (`setFittedSize`), NOT held here: the `onSize` listener that reads it is
// wired once and SURVIVES a park, so a closure variable would leave it comparing the pty's size
// against a previous mount's grid (see terminal-config's fittedByNode).
/**
* Co-attach sizing: we REPORT what we could render (`proposeDimensions`) and the pty tells us
* what it actually runs at — the smallest subscriber's grid (`onSize`).
*
* Two rules, both load-bearing:
* - a REPORTED fit is also applied locally, because that is exactly what the pty assumes we
* are showing (PtyManager.resize → `session.shown`). If it is not the effective size, the
* broadcast corrects us right back; solo, the min of a one-element set IS our fit, so no
* broadcast is ever sent and this is the old `fit.fit()` + report, unchanged.
* - an UNCHANGED fit resizes nothing. A sub-cell container change re-runs this with the same
* cols/rows, and resizing the emulator back up to our fit here would undo a letterbox with
* no report to correct it — the pty's state didn't change, so no `pty:size` would follow.
*/
const applyFit = () => {
try {
// A DOM renderer built while this node was unmeasurable — the park (its cleanup releases
// the webgl grant AFTER React detached the element) or a display:none wrapper — measured a
// 0-wide 'W' and baked a full extra cell into its row spacing. This is the first moment it
// can be re-derived; a no-op whenever the spacing already agrees. See the helper.
if (resyncDomRendererSpacing(term)) fullRepaint()
// Board up → this canvas terminal is hidden behind the overlay. Report "not viewing" (null)
// so a card-modal viewer of the same session drives the grid instead of being clamped to our
// (possibly zoomed-tiny) canvas size. No modal viewer → no size vote at all → the pty simply
// keeps its last size (the "parked SOLO subscriber leaves the pty alone" case). When the board
// closes, the boardOpen effect re-runs applyFit and the `sentCols/sentRows` reset below forces
// a fresh report of the real fit.
// Focus mode covers this node the same way the board does: the flow wrapper is
// display:none (so the WebGL budget can reclaim the hidden holders — review finding on
// #267), and a 0-sized container must vote "not viewing", never a clamped tiny grid.
const coveredByFocus = focusedNodeId() !== null && focusedNodeId() !== id
if (boardOpenRef.current || coveredByFocus) {
if (sessionId && !boardParked) {
boardParked = true
sentCols = 0
sentRows = 0
transport.resize(sessionId, null, null)
}
return
}
boardParked = false
const size = reportedSize(fit.proposeDimensions())
if (!size) return
if (size.cols === sentCols && size.rows === sentRows) return
setFittedSize(id, size)
sentCols = size.cols
sentRows = size.rows
resizeTerm(term, size.cols, size.rows)
setCo(termKey, { letterbox: false })
// Before the session exists we are the only voice: the size rides the initial `create()`.
if (sessionId) transport.resize(sessionId, size.cols, size.rows)
} catch {
// proposeDimensions can throw when the element is 0-sized (collapsed); ignore.
}
}
applyFitRef.current = applyFit
/**
* THE BOTH-RENDERERS INVARIANT, in two calls: a terminal is either a budget-coordinated
* per-node WebGL client or a grid on the shared canvas — never both, and never neither.
*
* Holding both is not a cosmetic overlap. The glyph addon's `setRenderer` silently disposes
* whatever renderer it replaces, so a webgl grant landing afterwards leaves the coordinator
* accounting for a context nobody paints with; and the reverse — `releaseWebgl` running while
* a glyph attachment is live — is worse: `WebglAddon.dispose()` puts xterm back on its own DOM
* renderer, which disposes OUR addon, and the DOM rows are `visibility: hidden` in glyph mode,
* so the node goes blank with a grid still registered.
*
* That is why `dropWebglClient` runs BEFORE `attachGlyphGrid` and not after it: disposing the
* handle releases any live grant synchronously, so xterm is back on its own renderer before we
* install ours.
*
* Both are idempotent, and both are called from the glyph setup/teardown as well as from the
* mode probes — the invariant must hold structurally, not because one probe happened to run at
* the right moment.
*/
const dropWebglClient = (): void => {
if (!webglHandle) return
webglHandle.dispose()
webglHandle = null
}
const ensureWebglClient = (): void => {
// `disposed` covers unmount/park/respawn, where the cleanup has already disposed the handle
// and a fresh registration would be a leak into a coordinator nothing will unregister from.
if (disposed || webglHandle) return
webglHandle = registerWebglClient(id, { acquire: acquireWebgl, release: releaseWebgl })
// Re-state the observer's last verdict: it will not fire again until visibility actually
// CHANGES, and a fresh client starts out believing it is hidden. The ref (not a per-run
// `let`) is what makes this true for a client registered by a REVIVE as well — no new
// intersection change follows one, so `false` there would leave a visible terminal on the
// DOM renderer until it was panned out and back.
webglHandle.setVisible(wasVisibleRef.current)
}
// --- glyphgrid (experimental shared renderer) -------------------------------------------
//
// Lives INSIDE the lifecycle effect, not in an effect of its own, for one reason: React runs
// cleanups in declaration order, so a later effect's cleanup would fire AFTER this one has
// already disposed (or parked) the terminal — and `attachment.dispose()` would then try to put
// a dead xterm back on its own renderer, report the failure it manufactured, and escalate a
// respawn for it. Teardown ordering is only correct while the grid's lifetime is nested inside
// the terminal's.
/**
* Push the grid to where the terminal screen actually is, and the PLATE to where the body is,
* re-measuring both offsets inside the node. One null check when this terminal holds no grid.
*
* Two independent rects on purpose (see `GridSpec.plateX`): the grid follows `.xterm-screen`,
* the plate follows the host box `.term-node__xterm` standing in for the body (`measurePlateRect`
* states the CSS invariant behind that). The plate is the larger of the two — the character
* matrix rarely divides the body exactly, and the leftover bands at the bottom/right are
* transparent node, i.e. raw canvas, unless the plate covers them. Both mutators change-gate
* themselves, so a settle tick that moved neither costs two comparisons.
*/
const syncGridOrigin = (): void => {
const grid = glyphGrid
if (!grid) return
const offset = screenOffsetInNode(term)
if (offset) {
glyphBodyOffsetRef.current = offset
const origin = bodyWorldRect(nodePosRef.current, offset)
grid.setOrigin(origin.x, origin.y)
}
const plate = measurePlateRect()
if (plate) grid.setPlateRect(plate.x, plate.y, plate.w, plate.h)
}
/**
* The plate's world rect. Null when the element is not laid out inside a React Flow node (a
* parked, detached element): leave the plate where it is rather than collapse it.
*
* **What is measured, and the invariant that makes it correct — the canonical statement; the
* other plate comments point here.** `container` is `bodyRef`, which is on
* **`.term-node__xterm`** — the HOST, not `.term-node__body`. The plate has to cover the BODY
* (that is the element `.term-node--glyphgrid` makes transparent, so every square of it the
* plate misses shows raw canvas), and the host's box is the body's box only because
* **`.term-node__xterm` is `position: absolute; inset: 0` inside a body that has no padding and
* no border**. Its own `4px 2px 2px 6px` padding is inside its border box and `clientWidth/
* Height` include it, so the two rects coincide exactly.
*
* That is a CSS coincidence, not a guarantee. **If the host stops being `inset: 0`, or
* `.term-node__body` gains padding or a border, this must measure `.term-node__body` instead**
* — otherwise the plate silently under-covers again, which is precisely the band this whole
* change removed, and every comment around it would still claim it cannot happen.
*/
const measurePlateRect = (): { x: number; y: number; w: number; h: number } | null => {
const offset = offsetInNode(container)
if (!offset) return null
// `clientWidth/Height` at the RO tick, the same measurement that positions the grid: LAYOUT
// px, so it is zoom-independent and already in world units (the canvas transform scales
// rendered pixels, never offsets or client boxes).
const w = container.clientWidth
const h = container.clientHeight
glyphPlateBoxRef.current = { offset, w, h }
return bodyPlateRect(nodePosRef.current, offset, w, h)
}
/**
* The plate's corner radius in WORLD units — how far the node's own bottom corners are
* rounded, so the opaque ground the shared canvas paints under this terminal stops reading
* square against it (limitation L4). 0 means "square", and every failure below answers 0: a
* merely rectangular plate is the shape this renderer has always drawn.
*
* READ FROM THE NODE'S OWN COMPUTED STYLE, never a literal. **This deliberately does not read
* the `--radius-lg` token**: `.term-node` is authored as a literal `border-radius: 10px` while
* the token is `12px`, so taking the token would round the plate MORE than the node clips
* itself and leave a crescent of canvas inside each bottom corner — the same class of artifact
* as L4, mirrored. Asking the element resolves whatever the stylesheet actually says (token,
* literal, or a future theme override) and cannot desync from it.
*
* The BORDER WIDTH is subtracted because `border-radius` describes the BORDER box while the
* plate is the body box, which sits one border inside it. CSS rounds that inner box by
* `radius - border`, so a plate rounded by the OUTER radius would curve slightly tighter than
* the node's own clip all the way round the corner.
*
* ONE RADIUS AND ONE BORDER — exact for this node, an approximation in general.
* `borderBottomLeftRadius` is the HORIZONTAL half of a corner CSS allows to be elliptical, and
* `borderBottomWidth` is one of the TWO borders that meet at a bottom corner. Both collapse to a
* single number because `.term-node` is authored with one uniform radius and `1px` side and
* bottom borders. An elliptical radius or asymmetric side borders would need the vertical half
* and the side width as well — and an elliptical corner would additionally need the SDF to take
* a `vec2` radius, so this is a two-file change, not a wider `parseFloat`. Same instinct as the
* `%` refusal below: this is not a CSS length engine.
*
* Only the bottom corners are shaped, and the GL layer owns that rule rather than this call
* site — see `GridDrawParams.plateRadius`. The body is the node's last child, so its top
* corners butt against opaque chrome and are not corners on screen at all.
*/
const measurePlateRadius = (): number => {
const root = rootRef.current
if (!root) return 0
const style = getComputedStyle(root)
// A computed `border-radius` is a px length here. A PERCENTAGE resolves as a percentage
// string, and parseFloat would turn it into a number that is not a radius at all — refused
// rather than guessed, the same way `packThemeBg` refuses a colour form it does not parse.
if (style.borderBottomLeftRadius.includes('%')) return 0
const radius = parseFloat(style.borderBottomLeftRadius)
const border = parseFloat(style.borderBottomWidth)
if (!Number.isFinite(radius) || radius <= 0) return 0
return Math.max(0, radius - (Number.isFinite(border) ? border : 0))
}
/**
* Hand the shared canvas back. Order is fixed: the ATTACHMENT first — it is the only thing
* that can still write into the grid, and disposing it is what puts xterm back on its own DOM
* renderer — then the grid itself.
*
* Returns whether xterm is back on a working renderer. FALSE means it is holding a disposed
* one and would paint nothing at all, which no caller may ignore: mid-life callers escalate a
* respawn, and the unmount path refuses to PARK the terminal (a parked-blank xterm would be
* adopted broken five minutes later).
*/
const teardownGlyph = (): boolean => {
glyphZUnsub?.()
glyphZUnsub = null
const attach = glyphAttach
const grid = glyphGrid
glyphAttach = null
glyphGrid = null
if (glyphGridRef.current === grid) glyphGridRef.current = null
if (!attach && !grid) return true
// INVARIANT: `glyphMounted` is true exactly while a grid is attached — teardown always clears
// it, `setupGlyph` sets it on success, and nothing else writes it. UNCONDITIONAL, never gated
// on `disposed`: that flag is also set for a RESPAWN, where the component SURVIVES and only
// this effect run ends. Gating left a respawned node whose fresh setup then failed showing
// its DOM text over a transparent body — i.e. over the canvas dot grid. On a real unmount
// this is a no-op (React 18 drops a setState on an unmounted component silently).
setGlyphMounted(false)
term.element?.classList.remove('glyphgrid-mode')
const restored = attach ? attach.dispose() : true
grid?.dispose()
// The other half of the both-renderers invariant: xterm owns its own pixels again, so it is
// a budget client again. Belt and braces — the generation handler and the participation
// effect also decide this from the MODE, and either may (correctly) dispose the client again
// a moment later. Skipped when the restore failed: that xterm paints nothing, and a webgl
// grant onto it would only add a second broken renderer to the first. `ensureWebglClient`
// itself refuses once `disposed` is set, which is every unmount/park/respawn path.
if (restored) ensureWebglClient()
return restored
}
/**
* Register this terminal's grid on the shared canvas and point xterm's render service at it.
*
* EVERY failure path is the same one: warn once and leave the terminal on the renderer it
* already has. Never `failSharedGlyph()` — that is the session-wide kill switch, and one
* node's unrecognised internals must not take the shared renderer away from every other
* terminal on the canvas (only the layer's own rAF/context-loss may do that).
*
* `forcedCell` is the one-shot cell-size correction; see the verification at the end.
*/
const setupGlyph = (forcedCell?: { cellW: number; cellH: number }): void => {
if (disposed || glyphAttach || glyphGrid) return
if (glyphOffRef.current) {
// Held OFF the shared canvas — and which half of `glyphOff` it is decides the budget
// client. Covered up (collapsed / ⌘M): nothing to draw, so no client, exactly as before.
// Held OPAQUE (stacked over another node, or in a gesture): this terminal is fully visible
// and painting its own pixels, so it is a WebGL client like any default-mode terminal.
//
// BE HONEST ABOUT WHAT THIS IS. Today it is BOOKKEEPING, not a behaviour change: in shared
// mode `sharedGlyphAvailable()` is true, so the mount path never registered a budget client
// for this node in the first place and an opaque terminal simply runs on xterm's DOM
// renderer — visibly fine, just unaccelerated. This line makes the accounting say what is
// actually true, which is what a future "shared mode with a live per-node WebGL budget"
// needs, and it is NOT yet invariant-complete: the paths that can still leave an opaque
// terminal without a client are the generation-bump handler (it tears down and defers to
// the participation effect, which lands here and now arms the client — covered), and the
// expand / ⌘M-exit transitions of a node that is ALSO opaque (collapsed→expanded while
// stacked: `glyphHiddenRef` has already flipped by the time we run, so this arms it —
// also covered), against the reverse order in a single commit where both flip at once,
// which is not. Finishing it means moving the budget decision out of these two gates and
// into one derivation; that is Phase 2's job, with the live budget.
if (!glyphHiddenRef.current) ensureWebglClient()
return
}
// The gate, re-evaluated on every call (mount, generation bump, expand): mode on, session not
// failed, and a context that actually exists — no WebGL2/OffscreenCanvas returns null here
// and this terminal simply stays where it is.
if (!sharedGlyphActive()) return
// The shared atlas rasterizes at xterm's DEVICE cell, and this is where that number enters
// the layer: the FIRST terminal to ask builds the context and fixes the atlas geometry for
// its lifetime (font settings are global, so every terminal computes the same cell). Passing
// it is not optional — with no live context and no cell there is nothing to build an atlas
// from, and `getSharedGlyphContext` answers null rather than guess metrics that would leave
// every glyph rescaled against the quad it is drawn onto.
const ctx = getSharedGlyphContext(deviceCellOf(term) ?? undefined)
// Nothing to paint into (no WebGL2, no OffscreenCanvas, no readable device cell): this
// terminal keeps its own renderer, so it must be a budget CLIENT — the other half of the
// both-renderers invariant, which is "never both" AND "never neither". Same on every failure
// path below.
if (!ctx) {
ensureWebglClient()
return
}
const host = term.element
const cell = forcedCell ?? cssCellOf(term)
const offset = host ? screenOffsetInNode(term) : null
if (!host || !cell || !offset) {
glyphWarn(
`${id}:geometry`,
`no grid for node ${id}: ${!host ? 'no xterm element' : !cell ? 'cell size unavailable' : 'terminal is not laid out inside a node'}`
)
ensureWebglClient()
return
}
// DEBUG-ONLY (see `publishCellDebug`): the CSS cell this grid is registered with, the DEVICE
// cell the atlas rasterizes into, and the ratio between them. At zoom 1 `css * dpr` must
// equal `device`; anything else is the factor every glyph is stretched by.
publishCellDebug(id, { css: cell, device: deviceCellOf(term), dpr: currentDprForDebug() })
glyphBodyOffsetRef.current = offset
const origin = bodyWorldRect(nodePosRef.current, offset)
// The plate is the BODY rect, measured here so the grid is never registered with a
// zero/absent plate that a later RO tick has to repair — a frame of un-plated terminal is a
// frame of dot grid showing through the node. Falls back to the CELL rect (the pre-fix
// behaviour, minus the padding) if the body cannot be measured; the RO tick corrects it.
const plate = measurePlateRect() ?? {
x: origin.x,
y: origin.y,
w: term.cols * cell.cellW,
h: term.rows * cell.cellH
}
let handle: GridHandle
try {
handle = ctx.engine.register({
// The SESSION-scoped key, not the bare node id: a relay tab adopts the host's project
// keeping node ids, and `register` throws on a duplicate. `nodeZFor` still takes the bare
// id — that is the canvas's own paint order, which is per-project, not per-session.
id: termKey,
cols: term.cols,
rows: term.rows,
cellW: cell.cellW,
cellH: cell.cellH,
originX: origin.x,
originY: origin.y,
z: nodeZFor(id),
// The theme background this xterm was built with — the colour the plate clears to, so a
// grid's own background matches the terminal it belongs to.
bgColor: packThemeBg(term.options.theme?.background),
// The opaque ground this terminal paints under itself: the BODY rect, not the character
// matrix. See `bodyPlateRect` for why the host's CSS padding no longer appears here.
plateX: plate.x,
plateY: plate.y,
plateW: plate.w,
plateH: plate.h,
// Registration-time only, and that is a property of the value rather than a shortcut:
// the radius is a stylesheet constant, so unlike the plate RECT nothing moves it while
// this node lives, and the paths that could change it (a font/theme generation bump)
// tear this grid down and register a fresh one. There is no `setPlateRadius` for the
// same reason — see `GridSpec.plateRadius`.
plateRadius: measurePlateRadius()
})
} catch (err) {
glyphWarn(`${id}:register`, `could not register a grid for node ${id}: ${String(err)}`)
ensureWebglClient()
return
}
// BEFORE the attach, never after: disposing the budget client releases any live grant
// synchronously, and `releaseWebgl` puts xterm back on its own DOM renderer — which, run a
// line later, would dispose the glyph addon we are about to install and leave the node blank.
// See the both-renderers invariant above.
dropWebglClient()
const attached = attachGlyphGrid(term, handle, ctx.atlas)
if (!attached) {
// Nothing was touched (the attach contract) — drop the grid we just made and stay put.
handle.dispose()
// …and this terminal is painting its own pixels after all, so it goes back to being a
// budget client. Without this the node would end up with NEITHER renderer coordinated.
ensureWebglClient()
glyphWarn(`${id}:attach`, `node ${id} stays on the DOM renderer: xterm internals not recognised`)
return
}
glyphGrid = handle
glyphAttach = attached
glyphGridRef.current = handle
host.classList.add('glyphgrid-mode')
// …and the node root gives up its background so the shared canvas shows through; the grid's
// own opaque plate is the terminal body's background from here on.
setGlyphMounted(true)
// Paint order. The engine change-gates `setZ`, so a reorder that does not move this node
// costs one comparison.
glyphZUnsub = subscribeNodeZOrder(() => handle.setZ(nodeZFor(id)))
// Cell-size verification, and the reason `forcedCell` exists. A grid's cell size is FIXED at
// registration (the shared context is torn down and everyone re-registers when it changes),
// but the authoritative number only exists once the addon is installed: `dimensions.css.cell`
// is now the ADDON's, and xterm maps mouse coordinates through it. Registration therefore
// uses the value from the renderer xterm was on — the DOM renderer, which runs the identical
// device-metric chain — and corrects itself here if the two ever disagree (an xterm bump
// changing that chain is exactly the drift this catches). Once, and never from a corrected
// pass, so a persistent disagreement cannot loop.
//
// This does NOT cover a FONT CHANGE: there both renderers agree, they are simply both still
// reporting the pre-change cell. That case is handled by WHEN this function is called — see
// the participation effect's ordering note — not by the check below.
if (forcedCell) return
const actual = cssCellOf(term)
if (!actual) return
if (
Math.abs(actual.cellW - cell.cellW) <= CELL_SIZE_EPS &&
Math.abs(actual.cellH - cell.cellH) <= CELL_SIZE_EPS
)
return
glyphWarn(
`${id}:cell`,
`re-registering node ${id}'s grid at the addon's cell size ` +
`(${actual.cellW}×${actual.cellH}, registered ${cell.cellW}×${cell.cellH})`
)
if (!teardownGlyph()) {
escalateRespawn('glyphgrid could not restore the DOM renderer')
return
}
setupGlyph(actual)
}
/** Re-evaluate participation: `on` is false while the node has no terminal on screen
* (collapsed, or the ⌘M view). Also the generation-bump path's re-entry point. */
const syncGlyph = (on: boolean): void => {
if (on) {
setupGlyph()
return
}
if (!teardownGlyph()) escalateRespawn('glyphgrid could not restore the DOM renderer')
}
glyphSyncRef.current = syncGlyph
if (parked) {
// Reattach the parked xterm's DOM element: the PTY never detached, so the screen is
// already current — no spawn, no tmux redraw, no terminal-mode re-negotiation.
if (term.element) container.appendChild(term.element)
// A link tooltip showing when the terminal parked would otherwise reappear where it was.
if (term.element) hideLinkHints(term.element)
patchViewportScrollSync(term)
applyFit()
} else {
term.loadAddon(fit)
term.loadAddon(searchAddon)
term.open(container)
patchImeModeSwitch(term)
// Renderer-parity: quantize the char measurement to the device-pixel grid, so a budget
// grant/release swaps renderers without the text visibly reflowing (see the helper).
quantizeCharSize(term)
patchViewportScrollSync(term)
// Before the first fit: a narrowing resize must trim the alternate buffer, or the find bar
// can crash this node (see the helper).
patchShrinkTrim(term)
applyFit()
// Reads the STORE, not the component's focusedRef: a parked terminal keeps the closure
// from the instance that created it, and a ref from a dead instance never updates — the
// store keyed by the stable node id is current across park/adopt (issue #78).
patchTerminalScale(term, () => (focusedNodeId() === id ? 1 : getZoom()))
// OSC 52 clipboard write: route the decoded text to the local clipboard. This is the PRIMARY
// copy path: tmux's mouse is ON, so a drag-select in copy-mode emits OSC 52 to us on the
// user's behalf (`set-clipboard on` + `terminal-features ",*:clipboard"`), and this handler is
// what receives it and writes the system clipboard — local and remote alike. Programs that
// emit OSC 52 themselves (vim "+y, gh, yazi) reach the clipboard through this same handler.
// The emulator's own Cmd+C / Ctrl+Shift+C chords (below) stay for a selection xterm owns.
// WRITE-ONLY — `parseOsc52` returns null for a `?` read query so a remote program can never
// read the local clipboard. Returning true swallows the sequence (also the read query).
// A RELAY tab's stream is another person's core: its writes are refused (osc52-policy.ts —
// paste-jacking). Local and SSH-project terminals (source 'local') are untouched.
const osc52Notice = createOsc52Notice()
term.parser.registerOscHandler(52, (data) => {
const text = parseOsc52(data)
if (text !== null) {
handleOsc52Write(text, session.source, {
write: (t) => window.nodeTerminal.clipboard.writeText(t),
// Through the registry, never a captured setState: this handler outlives a park.
notifyCopied: (t) => copySubs.get(termKey)?.(t),
shouldNotify: osc52Notice,
toast: dispatchOsc52Toast
})
}
return true
})
// Cmd (mac) / Ctrl+click link opening. URLs → default browser via createUrlLinkProvider
// (NOT the WebLinksAddon — the addon can't join the hard-wrapped rows a tmux repaint /
// agent TUI paints, so a long OAuth URL matched only its first row's fragment); file
// paths → editor node / Explorer reveal via the file provider. Both are modifier-gated
// inside their activate handlers, so plain clicks stay selections.
// Hovering a link names what a click will open — the RESOLVED path (the launch cwd or the
// pane's live cwd, whichever held it) and the gestures (link-hover.ts). One tooltip per xterm
// instance, inside its element, so it parks and dies with the terminal.
const linkHint = term.element ? createLinkHintTooltip(term.element) : null
// Read at hover/click time, never captured: the active project can change under a parked
// terminal. `projectFs` is declared below and only called after this block has run.
const shellCtx = (): DownloadContext => ({
browser: isBrowserRuntime(),
ssh: projectFs().ssh,
source: session.source
})
const hoverSink: LinkHoverSink | undefined = linkHint
? {
hover: (target, ev) =>
linkHint.show(
target.kind === 'url'
? urlLinkHint(target.url, isMac)
: fileLinkHint({
abs: target.abs,
dir: target.dir,
mac: isMac,
windows: isWindowsPlatform(),
systemOpen: systemOpenRefusal(shellCtx(), target.abs) === null
}),
ev.clientX,
ev.clientY
),
leave: () => linkHint.hide()
}
: undefined
term.registerLinkProvider(
createUrlLinkProvider(term, (uri) => window.nodeTerminal.shell.openExternal(uri), hoverSink)
)
// Not in xtermOptionsFromSettings: the handler closes over the shell bridge, which the
// pure options builder must not know.
term.options.linkHandler = createOsc8LinkHandler(
(uri) => window.nodeTerminal.shell.openExternal(uri),
hoverSink
)
const projectFs = (): { fs: FsApi; ssh: boolean } => {
const st = useProjects.getState()
const project = st.projects.find((p) => p.id === st.activeProjectId)
return project?.ssh ? { fs: sshFs(project.id), ssh: true } : { fs: api.fs, ssh: false }
}
const pathConvention = (): { windows?: boolean } | null => {
const st = useProjects.getState()
const project = st.projects.find((p) => p.id === st.activeProjectId)
const dialect = fileLinkDialect({
source: session.source,
browserRuntime: isBrowserRuntime(),
viewerWindows: isWindowsPlatform(),
corePlatform: corePlatformRef.current,
sshProject: !!project?.ssh,
// A standalone ssh terminal's output lives on the remote host, but its project's fs API
// is local. Disable file links rather than existence-checking a same-looking local path.
standaloneSsh: !project?.ssh && isRemoteSessionNode(data)
})
return dialect ? { windows: dialect === 'windows' } : null
}
const lookup = makeDirListingLookup(
async (dir) => projectFs().fs.list(dir),
3000,
pathConvention
)
const getCwd = (): string | undefined => (data.cwd as string | undefined) || undefined
// The pane's CURRENT directory — the second anchor for a relative path (see CwdSources).
const getLiveCwd = cachedCwd(() => api.pty.paneCwd(id))
// "Couldn't check" when any candidate could not be checked, "File not found" only for a
// verified absence (`fileMissMessage`).
const onMissingFile = (
token: string,
miss: { tried: string[]; unverified?: UnverifiedPath[] }
): void => {
window.dispatchEvent(
new CustomEvent('nodeterm:toast', {
detail: { kind: 'error', message: fileMissMessage(token, miss) }
})
)
}
const openFile = (abs: string, isDir: boolean): void => {
if (isDir) window.dispatchEvent(new CustomEvent('nodeterm:reveal-file', { detail: { path: abs } }))
else
window.dispatchEvent(
// `view`: a link asks to SEE the file, so a local .html renders as a page (Canvas.openFile).
new CustomEvent('nodeterm:open-file', {
detail: { path: abs, ssh: projectFs().ssh, view: true }
})
)
}
// Shift+Cmd/Ctrl+click → the OS default app (a directory → the OS file manager). The same
// `shell.openPath` the files node and ⌘K quick-open use, behind the same `canUseLocalShell`
// gate as the link menu's Reveal in Finder; anywhere it cannot act (SSH project, browser tab,
// relay) the click says why instead of doing nothing — see `systemOpenRefusal`.
const openWithSystem = (abs: string): void => {
const why = systemOpenRefusal(shellCtx(), abs)
if (why) {
window.dispatchEvent(new CustomEvent('nodeterm:toast', { detail: { kind: 'error', message: why } }))
return
}
window.nodeTerminal.shell.openPath(abs)
}
term.registerLinkProvider(
createFileLinkProvider(term, {
getCwd,
getLiveCwd,
lookup,
activate: openFile,
openWithSystem,
hoverSink,
convention: pathConvention
})
)
// Both providers above rely on xterm's own click handling, which
// tmux/agent mouse-reporting swallows. This capture-phase mouse-up fallback restores
// Cmd/Ctrl+click for both URLs and file paths in that mode. Attached to `term.element` so
// it travels with the terminal across park/adopt; it dies with the terminal on dispose.
if (term.element) {
installLinkClickFallback(term, term.element, {
getCwd,
getLiveCwd,
lookup,
activateFile: openFile,
openFileWithSystem: openWithSystem,
onMissing: onMissingFile,
openUrl: (uri) => window.nodeTerminal.shell.openExternal(uri),
fileEnabled: () => pathConvention() !== null,
convention: pathConvention
})
// Right-click on the same links → a menu (open / reveal / download / copy). Same hit-test,
// same routed lookup; the menu itself is state on whichever instance is mounted now.
installLinkContextMenu(term, term.element, {
getCwd,
getLiveCwd,
fileEnabled: () => pathConvention() !== null,
convention: pathConvention,
openMenu: (hit, x, y) =>
void resolveLinkTarget(hit, (token) =>
findExistingPath(token, pathConvention() ?? {}, { getCwd, getLiveCwd, lookup })
).then((target) =>
linkMenuSubs.get(termKey)?.(target, x, y)
)
})
}
}
// Board render pause — per effect run, NOT through `cleanups`: a park keeps the xterm but this
// run's closures die with it, so the wrapper is removed by this run's cleanup and the adopting
// run installs its own (the module also refuses to stack a second layer). Installed after
// open/reattach because the render service only exists once the terminal is open.
// Covered = the board is up AND this node is not the focus-mode node: the focus surface (z 40)
// sits ABOVE the board (z 25), so a node focused before the board opened is still on screen.
// Deliberately NOT folded into `reportVisible`: that verdict feeds the WebGL budget,
// hibernation and the offscreen teardown, and the board must not hibernate the sessions it
// shows cards for.
const releaseBoardPause = boardPauseSlot.attach(
term as unknown as Parameters<typeof boardPauseSlot.attach>[0],
{
covered: () => boardOpenRef.current && focusedNodeId() !== id,
onUncover: fullRepaint
}
)
// Cmd+C (mac) / Ctrl+Shift+C (Linux, Windows) / Ctrl+Insert copy the terminal selection — xterm
// renders to a canvas, so the DOM-selection copy used elsewhere can't see it. Plain Ctrl+C is
// left alone so it still sends SIGINT.
// The chord is swallowed whether or not there is a selection (`copyKeyAction`): with no
// selection, falling through would let xterm map ctrl+c to \x03 and SIGINT the foreground
// process — the exact opposite of the "copy" we advertise.
// Returning false only tells xterm to skip the key; the browser default still runs unless we
// preventDefault() ourselves. Note that in Chromium (Server Edition, or `npm run dev` with
// DevTools attached) Ctrl+Shift+C is ALSO the browser's inspect-element picker and that one is
// NOT preventable by a page — hence Ctrl+Insert, which no browser reserves.
// Shift+Enter is also intercepted here: xterm would send a plain \r (submit), so we remap it to
// ESC+CR (`SHIFT_ENTER_SEQ`) — agent CLIs read that as "insert newline" (see terminal-config.ts).
// Cmd/Ctrl+1-9 (jump to the Nth project) must be swallowed before xterm turns Ctrl+2..Ctrl+8
// into control bytes — but ONLY when the app owns the key: desktop shell, digit addressing an
// open project, AND app-first. Under terminal-first the user reserved every chord for the
// shell, so the digit must reach the PTY: this handler runs inside xterm, ahead of the window
// dispatcher that honors the policy for every other chord, so it owes the check itself.
// `liveProjectJumpTarget` is the same decision Canvas's handler makes.
term.attachCustomKeyEventHandler((e) => {
// ⌘+ / ⌘− / ⌘0 → THIS terminal's font size (issue #915), only when the user opted in
// (`terminalFontZoomKeys`). First, and swallowed: off-mac xterm would otherwise write ^_ for
// Ctrl+− to the pty, and a prevented event keeps the window dispatcher's canvas ⌘0 out of it.
// Canvas applies the step (the one writer — see terminal-font-zoom.ts); the live re-option
// effect below then re-fits and reports the new grid like any font change. The desktop ⌘0
// never arrives here (main's before-input-event claims it); Canvas resolves that one from
// focus via FONT_ZOOM_NODE_ATTR on the xterm host.
const fontZoom = terminalFontZoomAction(e, {
enabled: useSettings.getState().settings.terminalFontZoomKeys,
isMac
})
if (fontZoom) {
e.preventDefault()
requestTerminalFontZoom(id, fontZoom)
return false
}
const ownsProjectJump =
terminalShortcutPolicy() !== 'terminal-first' && liveProjectJumpTarget(e) !== null
const registryOwns = terminalChordBubbles(
e,
isGlobalKanbanOpen() || isKanbanOpen(useProjects.getState().activeProjectId ?? '')
)
const action = terminalKeyAction(e, term.hasSelection(), ownsProjectJump, registryOwns)
if (action === 'pass') return true
// 'bubble': the window dispatcher owns this chord (an allowInTerminal registry command).
// Return false so xterm skips its own keymap — which would consume e.g. Ctrl+Shift+Arrow
// into a CSI write and cancel the event — and DO NOT preventDefault: the dispatcher bails
// on defaultPrevented events, so a prevented bubble would kill the very dispatch this
// exists to reach.
// 'native': same mechanics, different owner — the PLATFORM's paste (Windows Ctrl+V, issue
// #562). xterm would map it to \x16 and cancel the keydown, which suppresses both
// Chromium's paste command and the Edit menu's Ctrl+V accelerator; leaving the event
// untouched lets the ordinary `paste` event reach xterm's textarea, exactly as ⌘V does on
// macOS (bracketed-paste framing included).
if (action === 'bubble' || action === 'native') return false
e.preventDefault()
if (action === 'copy') window.nodeTerminal.clipboard.writeText(term.getSelection())
// Shift+Enter → ESC+CR so agent CLIs insert a newline instead of submitting
// (see SHIFT_ENTER_SEQ in terminal-config.ts for the tmux rationale).
else if (action === 'shift-enter' && sessionId) transport.write(sessionId, SHIFT_ENTER_SEQ)
return false
})
// Shared with the park entry this session travels through: an adopted terminal keeps the very
// same PTY session, so its lifetime (and its kill-once guard) must be the same record.
const life: SessionLife & { killed: boolean } = parked
? parked.life
: { dead: false, killed: false }
// The park entry THIS effect's cleanup handed the session off to, if it parked one. Closure
// state on purpose: the parked-terminals MAP cannot answer "was this session handed off?" —
// an adoption deletes the entry, so park-then-adopt would read as "never parked".
let handedOff: ParkedTerminal | null = null
// Kill the PTY client at most once per session: the effect cleanup, a park dispose and a
// still-in-flight spawn continuation can all reach for it. `PtyManager.kill` tolerates a
// repeat, but the guard keeps the kill idempotent across all three callers.
const killSession = (sid: string): void => {
if (life.killed) return
life.killed = true
transport.kill(sid)
}
// Session-scoped teardown. An adopted terminal carries its listeners over (they were wired
// to the still-live session on first mount); everything below that pushes here is gated on
// `!parked` so nothing is wired twice.
const cleanups: Array<() => void> = parked ? parked.cleanups : []
// nodeterm itself just delivered this node's resume/relaunch line (in-place restart, wake from
// Pause/Eco, and the cold-restore relaunch a model switch or "restart agent and shell" recycles
// into). The exit our own quit recorded (`sessionEnded`) no longer describes the pane. Claude
// would clear it on its SessionStart anyway; cursor fires none on `--resume`, so without this the
// chat composer and the phone keep refusing a running CLI as "exited" until its next turn.
// note: a sessionEnd POST that lands after the relaunch re-sets it; none has been observed.
const markRelaunched = (): void => agentStatusStore.getState().setSessionEnded(id, false)
// Copy-on-select (issue #759). REGISTERED ONCE, at construction, and disposed WITH THE TERMINAL
// — the OSC 52 handler's lifecycle, not a per-mount one: its only persistent listener lives on
// `term.element`, which travels with the xterm across a park/adopt, so re-attaching on adopt
// would stack a second copy per remount. `cleanups` is exactly the right owner — carried over
// by a park, run only on the final teardown (both `disposeParked` and the real-teardown branch
// below). Both deps are read at EVENT time, never captured: the setting via the store (a
// toggle applies to every open terminal on its next drag, parked ones included), and the
// clipboard via the QUIET path (a failure toast per drag would be unusable). No `Copied` pill:
// that pill exists because tmux copy-mode CLEARS the highlight as it copies; an xterm
// selection stays highlighted, so there is no "did it copy?" doubt to answer, and on the
// quiet path the pill would claim success for a write that may have failed.
if (!parked) {
cleanups.push(
attachCopyOnSelect(term, {
enabled: () => useSettings.getState().settings.copyOnSelect,
write: (text) => window.nodeTerminal.clipboard.writeText(text, { quiet: true })
})
)
}
// Agent state (busy/idle/attention) comes from the agent's own hooks via the
// agent:status IPC (handled centrally in Canvas) — not from parsing the output here.
// We only surface the conversation topic from the terminal title, when the agent sets one.
if (!parked && showStatus) {
cleanups.push(
term.onTitleChange((t) => {
const title = t.trim()
// Ignore path/prompt-like titles (e.g. "user@host: ~/dir") which aren't session names.
// This feeds the `session` chip only; the node title is synced from the transcript's
// authoritative session name instead (see the readSessionName effect below).
if (title && !/[/:~]/.test(title)) agentStatusStore.getState().setSession(id, title)
}).dispose
)
}
const ssh = data.ssh as SshConnection | undefined
// An SSH-project node (`sshRemoteTmux`) runs its tmux on the remote host over the project's
// ControlMaster (`sshRemote`); a plain ssh-terminal node (createSshTerminalNode) instead runs
// `ssh` as a LOCAL pty program. Only the latter sets shell:'ssh' + buildSshArgs.
const sshRemoteTmux = !!data.sshRemoteTmux
const localSsh = !!ssh && !sshRemoteTmux
// A RELAY tab's SSH-project node lives on the HOST's side: this machine never dials for it
// (session/relay-ssh.ts). Its create goes to the host's core with `requireRemote`, which joins
// the session when the host holds it live and refuses otherwise — never a local spawn.
const dialsSsh = sshRemoteTmux && session.source !== 'relay'
// Connection SCOPE of a remote terminal, captured at spawn time for the exit-255 drop report
// below. Same choice `resolveSshRemote` makes: the owning project for an SSH project's own
// node, the host attachment for a node attached to another endpoint — so the reconnect
// coordinator re-establishes the master this node actually died on.
const sshProjectId = sshRemoteTmux && ssh ? sshConnectionScope(ssh) : null
// Prefetch the persisted scrollback in parallel with the spawn so it's ready to replay the
// instant the session resolves (a cold restart after a reboot recreates the tmux session
// empty — see the `fresh` handling below). Cheap no-op ('') when there's no snapshot.
const noSpawn = !!getCo(termKey).closed || getCo(termKey).ended
const scrollbackPromise =
parked || noSpawn
? Promise.resolve('')
: api.pty.readScrollback(id).catch(() => '')
// Consume the recycle-restart flag HERE, at the start of the spawn it belongs to — not in the
// create() continuation, which returns early when the node unmounted mid-spawn and would leave
// the flag set for some unrelated mount hours later ("session restarted by another user" out of
// nowhere). The banner is printed below once the session resolves.
const wasRecycled = takeRecycled(id)
void (async () => {
if (parked) return // adopted a live session — nothing to spawn or replay
// Another client DESTROYED this node's session (tmux kill-session — for everyone), or it was
// recycled with no replacement to re-attach to. Never spawn: `create(persistKey)` would
// happily start a brand-new tmux session — resurrecting a terminal its owner deliberately
// killed, or reviving this node in our STALE cwd. The overlay explains the state instead.
if (noSpawn) return
// A node of a REMOTE project (a relay / hosted team tab) under a session that is not a relay
// session — this desktop's own core — would create the host's node id HERE. Canvas keys the
// subtree on the project React Flow's store holds, and an unbound remote tab resolves to the
// offline relay session, so this is the last line: start nothing, before any SSH resolve.
// `isRemoteProjectId` is sessionForProject's own rule, so a tab the store deleted still counts.
if (spawnBelongsElsewhere(isRemoteProjectId(owningProjectRef.current ?? ''), session.source)) {
term.write(
`\r\n\x1b[90m${REMOTE_PROJECT_SPAWN_REFUSAL}\x1b[0m\r\n`
)
return
}
// SSH-project terminal: the project's live ControlMaster controlPath is established by
// Canvas's active-project effect. On a cold app load child effects run before that parent
// connect, so wait for it (briefly) before spawning. In Phase 1 a node only exists in the
// active project's React Flow, so the active project is its owner.
// Say so while we wait: the resolve below sits for up to SSH_REMOTE_WAIT_MS on a cold load
// or an unreachable host, and a terminal that is silently blank for that long reads as
// broken. Only when there is nothing to wait FOR is nothing printed (the common case: the
// master is already up and this resolves in a microtask).
if (dialsSsh && ssh && !currentControlPath(ssh)) {
// Drop the overlay for the duration of the attempt (this respawn IS the retry the user or
// the coordinator asked for) so the line below is visible; it comes back if we fail.
setCo(termKey, { offline: false })
term.write(`\x1b[90m[connecting to ${ssh.user}@${ssh.host}…]\x1b[0m\r\n`)
}
const sshRemote =
dialsSsh && ssh
? await resolveSshRemote(ssh, data.cwd as string | undefined, { nodeId: id, pty: api.pty })
: undefined
if (disposed) return
// The host is unreachable (no master within the window). SPAWN NOTHING: a create with no
// `sshRemote` lands in core's LOCAL tmux branch, and this node would come up as a local
// shell in the local $HOME wearing its `SSH user@host` chip — replaying the REMOTE session's
// scrollback snapshot, and (agent nodes) running the cold-restore `--resume` on the wrong
// machine. `requireRemote` below refuses the same thing core-side; this is the near half,
// which also saves the round-trip. Report the node so the reconnect coordinator retries.
if (dialsSsh && !sshRemote) {
setCo(termKey, { offline: true })
term.write(
`\r\n\x1b[90m[not connected — this session lives on ${ssh ? `${ssh.user}@${ssh.host}` : 'the remote host'}; nothing was started locally]\x1b[0m\r\n`
)
if (sshProjectId) reportSshDrop(sshProjectId, id)
return
}
setCo(termKey, { offline: false })
sentCols = term.cols
sentRows = term.rows
// A remote spawn can now WAIT, and a terminal that waits in silence reads as broken — the
// same reason the "[connecting…]" line above exists. Core paces remote spawns per
// ControlMaster (pty-spawn-gate.ts), so on a project switch the later nodes of a big canvas
// sit in a queue for a moment; a slow host or a contended master does the same thing without
// any queue. The wording claims only what is true from here: we are waiting for the host,
// whichever of those it is. Cleared the instant the create resolves (or the node tears down).
const slowSpawn =
sshRemoteTmux && ssh
? setTimeout(() => {
if (!disposed) term.write(`[90m[waiting for ${ssh.user}@${ssh.host}…][0m
`)
}, SLOW_REMOTE_SPAWN_NOTICE_MS)
: undefined
if (slowSpawn !== undefined) cleanups.push(() => clearTimeout(slowSpawn))
transport
.create({
cols: term.cols,
rows: term.rows,
shell: localSsh ? 'ssh' : data.shell,
shellArgs: localSsh ? buildSshArgs(ssh) : undefined,
cwd: data.cwd,
persistKey: id,
// The project that OWNS this node, for the runtime pane-ownership ledger (agent
// messaging, src/core/agents/pane-ownership.ts): the ssh project's own scope for a remote
// node, else the project whose nodes this subtree renders (`OwningProjectContext` — not
// necessarily the active one during a switch), else the active project. Recorded
// main-side ONLY on a genuine fresh spawn, so a second project opening another's live
// node id cannot claim it. Machine-local id, never the git-shared project.json id.
ownerProjectId: sshProjectId ?? owningProjectRef.current ?? useProjects.getState().activeProjectId,
// Only orders the remote spawn queue: on-screen terminals attach before offscreen ones
// on a project switch (terminal/on-screen.ts, core/remote-ssh/pty-spawn-gate.ts).
onScreen: elementOnScreen(container),
agentId: data.agentId,
agentModel: data.agentModel,
// "Restart on subscription": ride the spawn's env-strip path. Cleared below once the
// spawn resolves so an ordinary Restart re-applies the gateway (one-shot).
clearEnv: data.clearEnv === true,
accountId: data.accountId,
sshRemote,
// Belt AND braces: the guard above cannot see a `ssh` executable that has gone missing,
// which is core's other route into the local branch.
requireRemote: sshRemoteTmux,
// Same rule `attachReplay` applies below: a node with a one-shot launch command is being
// opened for the first time and has no history to restore.
restoreScrollback: !data.initialCommand,
// The one local terminal an SSH project's canvas may hold (issue #1186): core refuses
// every other local spawn owned by an SSH project. In-memory mark, never node data.
...(isLocalOnSshCanvas(id) ? { localOnSshCanvas: true } : {})
})
.then(
async ({
sessionId: sid,
fresh,
freshUnverified,
accountFallback: fellBack,
staleCwd,
closed,
screen,
cursor,
coAttachMouse,
coAttachAltScreen,
tmuxClient,
persistent,
sessionHost,
unavailable,
scrollbackSeeded
}) => {
// The spawn answered: whatever it says, we are no longer waiting on the host.
clearTimeout(slowSpawn)
// REFUSED: `requireRemote` and core could not spawn remotely (the master died inside our
// round-trip, or `ssh` is missing). Nothing was spawned — land in the same offline state
// the near-side guard above produces, retry included.
if (unavailable) {
const refusal = ptyRefusal(unavailable)
// A hosted-relay VIEWER opened a terminal it could not find running. Nothing failed and
// nothing is offline, so neither overlay applies — "Try again" would only respawn into the
// same refusal. What CAN still be on screen is state from an earlier run of this effect
// (a refresh re-enters here): a spawn-error overlay (only its own "Try again" clears it),
// the stale-cwd and lost-session banners (the success path resets them on every create
// result, and this path returns before it; "Restart in folder" would recycle a session
// this view does not hold), a refused-launch banner about a launch into a session that
// is not attached, and a letterbox sized to a pty that is not attached. Clear them the
// way the neighbouring refusals set theirs, say why the pane is empty, and stop;
// "Refresh terminal" re-asks on demand. `held-elsewhere` is the same shape: core found
// this remote node's id held by a session that is not on its host and did not join it —
// nothing is offline, and "Try again" would refuse again while that session runs.
// `new-only` too: a relay guest's create for a node it added found a session already
// running under that name and was refused (core/relay/scoped-guest-policy.ts).
if (unavailable === 'join-only' || unavailable === 'held-elsewhere' || unavailable === 'new-only') {
setCo(termKey, {
offline: false,
spawnError: null,
staleCwd: false,
lostSession: false,
launchTooLongBytes: null,
letterbox: false,
geminiRetired: false,
resumeSkipped: false
})
if (!disposed) term.write(`\r\n\x1b[90m[${refusal.message}]\x1b[0m\r\n`)
return
}
setCo(
termKey,
refusal.connectionLost
? { offline: true }
: { offline: false, spawnError: refusal.message }
)
if (!disposed) term.write(`\r\n\x1b[90m[${refusal.message}]\x1b[0m\r\n`)
if (refusal.connectionLost && sshProjectId && dialsSsh) reportSshDrop(sshProjectId, id)
return
}
// REFUSED: core's tombstone says another client deleted this node while we weren't
// subscribed (our project was closed/inactive, so no `pty:closed` could reach us). Nothing
// was spawned — land in the same "closed by <name>" state a subscribed co-viewer gets.
// BEFORE `onDisposed()`: there is no session here, so there is nothing to kill or unwire.
if (closed) {
setCo(termKey, { closed })
if (!disposed) term.write('\r\n\x1b[90m[session closed by another user]\x1b[0m\r\n')
return
}
// Disposal while the spawn/seed was in flight is NOT necessarily a teardown: an unmount
// with a live session PARKS it (same xterm, same PTY client, same `cleanups` array), and
// killing it here would leave the node permanently dead. That holds even if the user
// switched straight BACK: the remount adopts the entry and deliberately re-wires nothing —
// it relies on this continuation to finish the wiring (gate.open / onExit / onData). So the
// question is the closure's `handedOff`, not the (already emptied) parked-terminals map.
const onDisposed = (): boolean => {
const action = disposalAction({ disposed, handedOff: handedOff?.life })
if (action !== 'teardown') return false
offData?.()
killSession(sid)
return true
}
// Assigned below, once the data listener exists; before that there is nothing to detach.
let offData: (() => void) | undefined
if (onDisposed()) return
sessionId = sid
// `?? true`: an absent flag is an older core over the relay, not a plain shell.
sessionPersistent = persistent ?? true
// Published for the mount-stable observer effect, which cannot see this closure.
sessionPersistentRef.current = sessionPersistent
if (fellBack) setAccountFallback(true)
// Truthful on EVERY result, not only when set: a clean respawn ("Restart in folder", or
// any refresh that landed on a healthy session) must take the banner down with it.
setCo(termKey, { staleCwd: !!staleCwd })
// Same rule for the lost-conversation notice, and it is cleared HERE (before the
// cold-restore branch below can raise it) so a respawn that resumes cleanly — or any
// warm reattach, which never reaches that branch at all — takes the old banner down.
setCo(termKey, { lostSession: false })
// …and the skipped-resume notice, for the same reason.
setCo(termKey, { resumeSkipped: false })
// Catch up a size change that landed while the spawn was in flight (applyFit skips the
// IPC until sessionId is set, and the observer won't re-fire without another change).
applyFit()
// The pty is the authority on the grid: it runs at the SMALLEST subscriber's size, so
// render exactly that and letterbox the leftover space. With one subscriber the min is our
// own proposal, so a solo user is never sent this at all — nothing re-fits, nothing repaints.
if (transport.onSize) {
cleanups.push(
transport.onSize(sid, (size) => {
resizeTerm(term, size.cols, size.rows)
// Measured against the CURRENT mount's fit (the registry, not a closure): this
// listener outlives the mount that wired it — see terminal-config's fittedByNode.
setCo(termKey, { letterbox: letterboxFor(id, size) })
})
)
}
// Someone else permanently destroyed this node (tmux kill-session): show who, and make sure
// this component never respawns the session — see CoState.
if (transport.onClosed) {
cleanups.push(
transport.onClosed(sid, ({ by }) => {
setCo(termKey, { closed: { by } })
term.write('\r\n\x1b[90m[session closed by another user]\x1b[0m\r\n')
})
)
}
// Someone else RECYCLED this node (moved it into a worktree): our session id is dead. If a
// replacement is already live under the same node id (`ready`), restart onto it — the node
// is still on our canvas and still working, so the closed state above would be a lie, and
// parking this now-dead pty would hand a corpse to the next mount. If NO replacement ever
// came (the mover's app died mid-move), we must NOT respawn: our options still carry the
// node's stale cwd, and spawning it would silently undo the worktree move for everyone —
// the terminal ends instead, with a reopen (see CoState.ended / recycleAction).
if (transport.onRecycled) {
cleanups.push(
transport.onRecycled(sid, (info) => {
if (recycleAction(info) === 'ended') {
disposeParkedTerminal(termKey) // the park holds a dead pty either way
setCo(termKey, { ended: true })
term.write('\r\n\x1b[90m[session ended — reopen to restart]\x1b[0m\r\n')
return
}
const restart = restartSubs.get(termKey)
if (!restart) {
disposeParkedTerminal(termKey) // unmounted: drop the park, the next mount creates fresh
return
}
markRecycled(id)
restart()
})
)
}
// Flow control: track xterm's unprocessed write backlog (bytes handed to
// term.write but not yet parsed, plus anything still queued in the gate below). Past a
// high watermark we pause the source so a flood can't grow this buffer without bound;
// we resume once it drains.
let pending = 0
let paused = false
const HIGH_WATER = 1 << 20 // 1 MB
const LOW_WATER = 1 << 18 // 256 KB
// Bytes left the backlog (parsed by xterm, or dropped by a resync — see below). Both must
// return the flow ticket, or a discarded queue would leave `pending` permanently high and
// the source paused forever.
// Both callers are DEFERRED (an xterm write callback, or a resync's gate reset), so both
// can land after teardown — the write loop still runs the callbacks it holds even though
// `cleanups` has unsubscribed everything and the session is killed. `life.dead` (flipped
// before the teardown in BOTH paths: the effect cleanup and the park dispose) is the
// authority: past it there is no session left to un-pause, and `transport.setFlow` would
// address a dead one.
const relieve = (bytes: number): void => {
if (life.dead) return
pending -= bytes
if (paused && pending < LOW_WATER) {
paused = false
transport.setFlow(sid, true)
}
}
const writeChunk = (chunk: string): void => {
term.write(chunk, () => relieve(chunk.length))
}
// Subscribe BEFORE the seed below: main pushes pty data on a timer regardless of
// listeners and an IPC event with no listener is dropped, while tmux emits its attach
// redraw within tens of ms — i.e. inside the seed's subprocess/ssh round-trip. The gate
// queues those chunks until the seed is written, then drains them in order. Queued bytes
// still count towards `pending`, so a flood during the gap pauses the source.
const gate = createDataGate(writeChunk)
offData = transport.onData(sid, (chunk) => {
pending += chunk.length
if (!paused && pending > HIGH_WATER) {
paused = true
transport.setFlow(sid, false)
}
gate.push(chunk)
})
cleanups.push(offData)
// Gemini CLI refuses personal Google accounts since 2026-06-18, and the refusal comes
// BEFORE any session exists — no hook ever fires to report it, so the pane text is the only
// evidence. Watch a gemini-harness node's output for the CLI's own sentence and raise the
// banner once; it types nothing and relaunches nothing (see terminal/gemini-retired.ts).
// Stops at the first match; unsubscribed with the rest of the session on teardown.
if (agentId && watchesGeminiRetirement(capabilityAgentId(agentId))) {
let seen = ''
let offRetired: (() => void) | undefined = transport.onData(sid, (chunk) => {
seen = (seen + cleanEcho(chunk)).slice(-GEMINI_RETIRED_TAIL_CHARS)
if (!geminiRetiredIn(seen)) return
offRetired?.()
offRetired = undefined
setCo(termKey, { geminiRetired: true })
})
cleanups.push(() => {
offRetired?.()
offRetired = undefined
})
}
// We fell so far behind that the server discarded our queued output and redrew us from
// tmux. The capture IS the current screen, so reset the emulator and write it — writing it
// on top of a stale buffer would splice two different points in time. An EMPTY payload is
// ignored outright (shouldApplyResync): a wrongly cleared screen is unrecoverable, a
// skipped repaint is not. The separator mirrors the cold-restore one.
//
// It must go THROUGH THE GATE, not around it. A resync can land while the seed below is
// still awaiting its capture (both are exactly the "this client is slow" case), and the
// gate is holding chunks that PREDATE this redraw: draining them on top of it would splice
// the stale flood right back over the screen we just repainted, and the pending history
// seed would then write an even older screen over that. So the redraw SUPERSEDES both —
// `gate.reset()` drops the queue (returning its bytes to the flow accounting) and switches
// to pass-through, and `superseded` tells the seed its capture is now stale and to write
// nothing (it still wires the rest of the session — see seedPaint). Everything arriving
// after the capture streams straight through, in order.
//
// `repaintResync` sequences the reset behind a write callback: writes already handed to
// xterm (up to a megabyte of history seed) are parsed asynchronously, and an inline
// `term.reset()` would clear the buffer before they land — see terminal-config. That
// deferral outlives teardown, so the repaint is gated on `!life.dead`: this listener is
// unsubscribed and the xterm disposed, but a callback already inside xterm's write loop
// still fires and would reset/write a disposed core. `life` is the session-scoped record
// (shared with the park entry), so a PARK — which keeps the xterm and the PTY alive — does
// not trip the guard and a resync arriving at a parked terminal still repaints it.
let superseded = false
if (transport.onResync) {
cleanups.push(
transport.onResync(sid, (resyncScreen) => {
if (!shouldApplyResync(resyncScreen)) return
superseded = true
relieve(gate.reset())
repaintResync(term, resyncScreen, () => !life.dead, tmuxClient === true)
})
)
}
// Seed the (fresh) emulator — but only in the two cases where nothing else will paint it:
// a COLD restart (the machine rebooted, the tmux session is gone, so replay the persisted
// snapshot) and a co-attach JOINER (no redraw of its own — see below). A plain warm
// reattach seeds NOTHING: tmux is attached to this client, redraws it, and owns the
// history the wheel scrolls. Parked terminals seed nothing either — their buffer is still
// correct and writing to it would duplicate content.
// The gate MUST be opened whatever happens in here (`finally`): the data listener already
// exists, so a throw between it and `gate.open()` would queue chunks forever — the source
// pauses at the high-water mark and the terminal freezes silently and permanently. The
// only case that leaves it shut is a real teardown, where the xterm is disposed anyway.
let toreDown = false
try {
const replay = attachReplay({
parked: !!parked,
fresh,
hasInitialCommand: !!data.initialCommand
})
if (replay === 'cold-snapshot') {
const snapshot = await scrollbackPromise
if ((toreDown = onDisposed())) return
if (
seedPaint({ replay, superseded, snapshot, coreSeeded: scrollbackSeeded }) ===
'snapshot'
) {
// The snapshot comes from `capture-pane -p`: LF-separated, no CR bytes. xterm runs
// with convertEol:false, so writing it raw would render as a staircase.
term.write(toXtermText(snapshot))
term.write('\r\n\x1b[90m── session restored (process ended by a restart) ──\x1b[0m\r\n')
}
} else if (replay === 'warm-attach') {
// A joiner's xterm never saw tmux's attach-time `\e[?1049h` (PtyCreateResult
// .coAttachAltScreen). Before the paint: entering the alt buffer clears the display.
// Not once a resync has superseded the seed: its repaint (`term.reset()` + the capture)
// may already have landed, and entering the alt buffer now would blank it.
if (coAttachAltScreen && !superseded) term.write(CO_ATTACH_ALT_SCREEN_SEQ)
// tmux is attached to this client and paints it: the visible screen on attach, its own
// history under the wheel. So there is nothing to hydrate — EXCEPT for a CO-ATTACH
// JOINER, whose `screen` was captured inside `create()`: tmux only repaints on SIGWINCH,
// and a joiner that did not resize never gets one, so this capture is the only thing
// that paints it (see "Painting the joiner" in docs/team-presence.md).
// A resync that landed while we awaited the spawn is strictly newer, so `seedPaint` says
// 'none' and we write nothing. It is a CONDITION, never a `return`: everything below
// this try/finally — the onExit notice, `term.onData` (the KEYBOARD INPUT path) and the
// initialCommand / agent-resume — must still be wired, or the terminal streams output,
// looks alive, and silently accepts no input forever.
if (seedPaint({ replay, superseded, screen }) === 'create-screen') {
// Start from a known-clean SGR state; the capture is LF-separated (`capture-pane -p`)
// and xterm runs with convertEol:false, so the LFs have to become CRLFs.
term.write('\x1b[0m' + toXtermText(stripTrailingNewline(screen as string)))
// …and put the cursor back where the PANE has it. The capture is text, so the paint
// above left the cursor after its last character — see `cursorPlacementSeq`.
term.write(cursorPlacementSeq(cursor))
}
}
// A CO-ATTACH JOINER (a second window on this node — rare on the canvas, but possible)
// missed the mouse-tracking mode tmux only emits at its own attach, so it can't
// wheel-scroll tmux history. Enable it (see CO_ATTACH_MOUSE_SEQ). Only ever set on a join,
// so this never fires on the solo spawn / warm-reattach-with-own-tmux-client path.
if (coAttachMouse) term.write(CO_ATTACH_MOUSE_SEQ)
// A restart we did not ask for: say why once, before the new session's output lands (the
// gate below is still shut). We JOIN the replacement session, so tmux — which already has
// a client — does not redraw for us. AFTER the seed, never before it: a joiner enters the
// alternate buffer above (coAttachAltScreen), and a banner written earlier would sit in
// the normal buffer the user no longer sees — or be cleared by the switch.
if (wasRecycled)
term.write(
'\r\n\x1b[90m── session restarted by another user (moved to a new folder) ──\x1b[0m\r\n'
)
} catch (err) {
// Never let a seed failure freeze the terminal: the live stream matters more than the
// history. `finally` still opens the gate below.
console.error('[terminal] history seed failed', err)
} finally {
// Seed written — release the PTY output that arrived while it was in flight.
if (!toreDown) gate.open()
}
cleanups.push(
transport.onExit(sid, (code) => {
term.write(`\r\n\x1b[90m[process exited with code ${code}]\x1b[0m\r\n`)
// ssh exiting 255 on an SSH-project terminal is a CONNECTION drop (sleep/wake,
// network change, NAT idle) — the remote tmux session survives. Report it so the
// reconnect coordinator can re-establish the master and respawn this node.
if (code === 255 && sshProjectId && dialsSsh) sshDropHandler?.(sshProjectId, id)
})
)
cleanups.push(
term.onData((input) => {
// Lone Esc / Ctrl-C while the agent works: Claude Code fires NO hook on a user
// interrupt, so probe the cancelled turn (still-silent working → done). Exact
// match — arrow keys etc. arrive as multi-byte \x1b[… sequences.
// On THIS node's session store (the default one for a local node): a relay node's guess
// must never flip the entry a handed-off SSH project holds under the same node id.
if (showStatus && (input === '\x1b' || input === '\x03')) agentStatusSession.inferInterruptAfterSettle(id)
// While a wake is in flight, HOLD this input rather than write it: the resume line is
// sitting un-submitted in the pane and a keystroke would splice into it. The buffer is
// bounded — a `queueFull`/`buffered` verdict means "held, do not write". Flushed (or
// dropped) when the resume resolves; see `wakeInputBufferRef`. `passthrough` is the
// ordinary case and is byte-for-byte the old behaviour.
if (wakeInputBufferRef.current.offer(input).kind !== 'passthrough') return
transport.write(sid, input)
}).dispose
)
// Deliver a command only after the fresh shell settles, and never blind: zsh's init
// (rc files / ZLE setup) resets the tty with a FLUSH that can eat part of a queued
// line — a long agent launch line then sat at the prompt mangled (unbalanced quote →
// `quote>` on Enter) instead of running. The settle wait below minimizes wasted
// attempts; deliverCommand (echo-verify + retry, fail-open) guarantees a mangled
// line is never submitted. See command-delivery.ts.
const whenShellSettled = (run: () => void): void => {
let done = false
let timer: ReturnType<typeof setTimeout>
const fire = (): void => {
if (done) return
done = true
unsub()
run()
}
const unsub = transport.onData(sid, () => {
if (done) return
clearTimeout(timer)
timer = setTimeout(fire, 200) // quiet for 200ms after output → prompt is up
})
timer = setTimeout(fire, 1500) // silence cap: no output at all → write anyway
cleanups.push(() => {
done = true
clearTimeout(timer)
unsub()
})
}
const launchWriterOptions = {
io: { write: (d: string) => transport.write(sid, d), onData: (cb: (data: string) => void) => transport.onData(sid, cb) },
// A fresh shell is known at spawn; subsequent/manual deliveries must recheck the pane.
shellReady: async (manual: boolean) =>
trustsFreshShell({ manual, fresh, persistent: sessionPersistent, sessionHost }) || isLaunchShell(await queryPaneWithin(() => api.pty.paneCommand(id), RESTART_EXIT_TIMEOUT_MS)),
killLine: getTerminalKillLine(),
cleanup: (cancel: () => void) => { cleanups.push(cancel) }
}
const launchWriter = createLaunchWriter({ ...launchWriterOptions,
claimAttempt: (manual, command) => commitLaunch(api, id, command, manual),
// A local Windows session-host pane runs pwsh/cmd, where the POSIX launch line breaks on
// a quote in the prompt: execute the node's held semantic launch there instead. Every
// other pane answers 'fallback' without an IPC (terminal/launch-intent.ts).
execute: (command) =>
executeHeldLaunch(command, {
held: () => (getNode(id) as CanvasNode | undefined)?.data.launchIntent,
sessionHost: !!sessionHost,
source: session.source,
hostPlatform: () => hostPlatformFor(api),
executeLaunch: api.pty.executeLaunch
? (request) => api.pty.executeLaunch!(id, request)
: undefined,
newLaunchId: uuid
})
})
const writeWhenShellReady = (cmd: string): void => {
whenShellSettled(() => {
cleanups.push(
deliverCommand(
{
write: (d) => transport.write(sid, d),
onData: (cb) => transport.onData(sid, cb)
},
cmd,
(outcome) => {
// The one outcome the caller must act on: the line was longer than the pane's
// tty could take, so nothing was submitted (#706). Say so — a refusal that is
// only visible as an idle pane is the failure this replaces.
if (outcome === 'line-too-long') {
setCo(termKey, { launchTooLongBytes: lineBytes(cmd) })
}
if (outcome === 'submitted') markRelaunched()
},
{ killLine: getTerminalKillLine() }
)
)
})
}
// Tell the canvas this node can be typed into — the gate its armed-launch loop waits on.
// Through the SAME settle the two writers above use, and for the same reason: the held
// launch is an agent CLI command line, and a line delivered across zsh's rc-file tty flush
// comes out mangled. Published unconditionally (not only for an armed node): whether this
// node is armed is Canvas's question, it can change after the spawn resolves, and the
// subscribers filter by id anyway.
whenShellSettled(() => {
cleanups.push(registerLaunchWriter(id, launchWriter, api))
setSessionReady(id, true)
})
// Paused (see agentStatus.paused) is the ONE exception to the "a cold start always resumes"
// rule below: it exists precisely to survive a cold restart, so it must NOT be dropped, and
// the auto-resume branch must be skipped — only an explicit Resume (which reuses the same
// command-building path through the registered hibernate/wake pair) may relaunch it. Read
// HERE because the late cold-start check below is gated on it too: a paused node has
// nothing to relaunch, so it must not pay two probe round trips to find that out.
const pausedNow = !!agentStatusStore.getState().byId[id]?.paused
// LATE COLD-START DETECTION (see terminal/cold-self-heal.ts). `freshUnverified` says the
// create's `fresh:false` came from a freshness read that never completed, so "a session
// already exists" was a fold and not an answer — and `new-session -A` may have made the
// session we are now attached to. tmux can settle it after the fact, so ask ONCE, here,
// where the attach has landed: a session created within seconds of it is one WE created.
//
// Deliberately gated on there being something to DO with the answer: no `initialCommand`
// (that branch wins anyway and must not be delayed by two round trips), an agent we can
// resume, not armed, not paused. A plain terminal has no conversation to lose, and paying
// a probe to tell it so would be the channel pressure this whole area exists to reduce.
const canColdRestore =
session.source !== 'relay' && !!agentId && canResume(agentId) && !data.pendingLaunch && shouldColdResume(pausedNow)
let coldStart = fresh
if (!fresh && freshUnverified && !data.initialCommand && canColdRestore) {
// After the shell has settled, not at this instant: the attach is a network round trip
// and the session may not exist yet when the create promise resolves. This is the same
// settle the held-launch and initialCommand writers use, so by the time it fires the
// pane is alive and a shell has printed its prompt.
await new Promise<void>((resolve) => {
whenShellSettled(resolve)
// …and settle on a TEARDOWN too. `whenShellSettled`'s own cleanup marks itself done
// WITHOUT running the callback, so without this an unmount mid-wait would leave this
// continuation parked on a promise nothing can ever resolve — holding the xterm and
// every closure in it for the life of the app. `cleanups` does not run for a PARK
// (same array, same session), so the healthy re-adoption path is untouched.
cleanups.push(resolve)
})
if (onDisposed()) return
const [ageSeconds, paneCommand] = await Promise.all([
api.pty.sessionAge(id).catch(() => null),
api.pty.paneCommand(id).catch(() => null)
])
if (onDisposed()) return
coldStart =
coldSelfHealVerdict({
fresh,
freshUnverified: true,
ageSeconds,
paneCommand,
isShell: isShellCommand
}) === 'cold'
}
// Hibernation × cold restore. `hibernated` is PERSISTED, so it can outlive the very thing
// it describes:
// - a COLD start (the tmux session is GONE — a reboot, a reaped server, a first open, or
// the late detection above): the CLI it refers to died with the session. The node is not
// hibernated, it is simply gone, so the flag is dropped and the ORDINARY cold-restore
// auto-resume below brings the conversation back exactly as it does for any other node.
// Leaving it set would park a SLEEPING chip over a dead pane and hand the resume to the
// wake path, which (rightly) refuses a pane it cannot see a shell in.
// - a real warm attach: the shell we exited to is still sitting in the pane, by design.
// Nothing auto-resumes here and the wake path owns the relaunch. That is the feature.
if (coldStart && agentStatusStore.getState().byId[id]?.hibernated) {
agentStatusStore.getState().setHibernated(id, false)
}
// The clear-env strip is one-shot: once this spawn has applied it, clear the flag so a later
// ordinary Restart re-applies the gateway. (The recycle action re-sets it for its own spawn.)
if (data.clearEnv) {
updateNodeData(id, { clearEnv: undefined })
}
// A project just taken back from a hosted team ("Open here anyway") skips this relaunch
// ONCE (see terminal/handed-off-resume.ts). The mark is taken here, warm or cold, so it
// never outlives this mount; never by a relay tab's node, which shares the node id and is
// the team's own view of the same session.
const skipResume = skipsColdResume({
coldStart,
canColdRestore,
marked: session.source !== 'relay' && takeColdResumeSkip(id)
})
// Run a one-shot command on first open (e.g. "gh auth login" or the agent CLI), then
// forget it.
if (data.initialCommand) {
const command = data.initialCommand
if (session.source === 'relay') {
deliverRelayInitialLaunch({ scope: api, id, fresh, pending: data.pendingLaunch, command,
consume: () => updateNodeData(id, { initialCommand: undefined }),
whenReady: whenShellSettled, writer: launchWriterOptions,
onFailure: (outcome) => {
useLaunchDelivery.getState().markFailed(id, 1)
if (outcome === 'line-too-long') setCo(termKey, { launchTooLongBytes: lineBytes(command) })
}
})
} else deliverInitialLaunch(command, {
pending: data.pendingLaunch,
whenReady: whenShellSettled,
write: launchWriter,
update: (patch) => updateNodeData(id, patch),
onFailure: (outcome) => {
useLaunchDelivery.getState().markFailed(id, 1)
if (outcome === 'line-too-long') setCo(termKey, { launchTooLongBytes: lineBytes(command) })
}
})
} else if (skipResume) {
// Say so rather than leaving a bare shell under an agent badge in silence. Resuming stays
// the user's explicit choice.
if (!life.dead) setCo(termKey, { resumeSkipped: true })
} else if (coldStart && canColdRestore) {
// Cold restart of an agent node: the live agent is gone, so re-launch it. Resume the
// prior conversation by its session id when we have one; otherwise start the agent
// fresh. Plain terminals get nothing here — just the restored shell.
//
// An ARMED node (`pendingLaunch`) is excluded, and that is the point of arming: its
// launch — the very same agent CLI line, with the brief it was opened for — is being
// HELD until its dependencies finish. Launching a bare CLI here starts the session the
// hold exists to prevent, and Canvas's held launch then arrives as TEXT typed into the
// running CLI rather than as the command it is. A first open is `fresh` by definition,
// so this covered every `--after` / `verify` node; it was previously masked by the
// delivery race (the held launch usually lost it and was retried), and gating delivery
// on the shell settling would have made the collision deterministic.
//
// Two sources, in this order, and the order is the whole point:
// 1. the LIVE id from hooks, which tracks `/clear` and `--fork-session` minting a new
// one mid-conversation, so it is the only one that can be current;
// 2. the id nodeterm MINTED at node creation and persisted (`data.agentSessionId`).
// Falling back to (2) is what stops a cold start from opening a blank conversation when
// no hook ever landed. That is not hypothetical: hook POSTs from an SSH node ride the
// reverse tunnel, and after one host reboot 18 of 40 agent nodes had no id at all and
// relaunched empty while their transcripts sat on disk, unreachable.
const st = agentStatusStore.getState().byId[id]
const priorId = st?.sessionId || data.agentSessionId
// …and is that conversation still THERE? A persisted id outlives its transcript
// (claude's 30-day cleanup, a `/clear`, a removed account, an id minted for a session
// that never ran), and `claude --resume <dead id>` prints "No conversation found with
// session ID" and exits — leaving the pane at a bare shell with an agent badge over it.
// Measured on one host: 20 of 108 live sessions sat in exactly that state.
//
// Only a POSITIVE `absent` drops the id (see `coldResumeDecision` for why the two errors
// are not symmetric). `data.accountId` is the right scope and `accountForReads` is not:
// the question is whether the command we are about to type will find the conversation,
// and that command runs under the config dir `data.accountId` names.
const presence = shouldProbeTranscript(priorId, agentId)
? await api.chat
.transcriptExists(priorId!, data.accountId, id)
.catch((): TranscriptPresence => 'unknown')
: ('unknown' as TranscriptPresence)
const resume = coldResumeDecision(priorId, presence)
// Say so rather than starting a fresh conversation in silence. `life.dead` first, like
// the spawn-rejection handler below: a node unmounted mid-probe must not publish into a
// key the next mount reads.
if (resume.lostSession && !life.dead) setCo(termKey, { lostSession: true })
// Re-resolve the mode at relaunch: it's a property of how a session is launched, not
// a persisted property of the node, so the current setting wins after a reboot. Awaited
// (not the sync `activePermissionMode`) because this fires on mount: right after a machine
// reboot it can beat the CLI version probe, and an unanswered probe would conservatively
// drop `auto`. Gated on THIS node's agent: claude's `auto` version gate must not decide
// what a grok (or any other permission-mode-capable agent's) relaunch is flagged with.
//
// Inheritance-aware: assembleResumeCommand resolves a custom agent's baseAgent/args, so a
// claude-base proxy resumes with its own binary + claude's --resume grammar + its custom
// args — the SAME builder fresh launch uses, so cold restore and first launch can't drift.
// For a builtin this is byte-identical to the old resumeCommand + withPermissionMode path.
//
// Shared-identity agents (codex) resume THROUGH their launcher, so the cold-restored node
// re-claims its own thread instead of joining as an anonymous client. `data.ssh` /
// `data.sshRemoteTmux` keep a remote node on the bare command (no launcher on the host).
const mode = await ensureActivePermissionMode(agentId)
// …and the project's launch-info snapshot, for the same reason and with the same shape:
// this runs at MOUNT, so on a cold boot it is racing the session's very first fetch, and
// the synchronous `agentLaunchOverride` read below would answer "no project settings" for
// a whole canvas of restoring nodes. Bounded and never-rejecting (see the helper).
const ownerProjectId = await warmOwningProjectId()
const shared = codexSharedIdentity(data.ssh || data.sshRemoteTmux)
const customAgent = agentConfig(agentId)
? undefined
: useSettings.getState().settings.customAgents.find((c) => c.id === agentId)
const { command: cmd } = assembleResumeCommand(
{
agentId,
customAgent,
sessionId: resume.sessionId,
permissionMode: mode,
model: data.agentModel,
sharedIdentity: shared,
// Which `--ask-for-approval` values the codex that will run this node actually has.
// Same remoteness question `shared` just answered: an SSH node runs the HOST's codex,
// which this machine's probe never saw.
approvalCaps: await ensureCodexLaunchCaps(
capabilityAgentId(agentId),
data.ssh || data.sshRemoteTmux || session.source === 'relay'
),
// The launch-command override rides the relaunch too, so a wrapper user's node comes
// back through its wrapper after a reboot — the moment env/account setup matters.
// Scoped to the OWNING project (`warmOwningProjectId`) so a project-level wrapper does
// not vanish on cold restore, which is exactly where it is most needed.
launchCmdOverride: agentLaunchOverride(agentId, ownerProjectId)
},
// The boot-time desktop env snapshot — the same object fresh launch and the Settings
// preview expand against, so a ${env:…}-referencing custom agent cold-restores with
// the exact line it launched with. Empty on browser/relay by design.
agentEnvSnapshot()
)
/**
* Watch the pane for the CLI's own "that conversation does not exist" line and, if it
* comes, launch the agent FRESH in the same pane.
*
* Everything it does is a refusal until proven otherwise:
* - it only reads output for `RESUME_MISS_WINDOW_MS`, because the CLI answers at once;
* - it matches the message against THIS id, not a bare substring;
* - it re-reads the pane and requires a SHELL to own it before writing, the same gate
* the hibernation wake uses — the CLI exits after printing, so anything else in that
* pane is something we must not type into;
* - it fires at most once, and the fallback command carries NO session id, so it can
* never arm a second watcher.
* The dead id is forgotten on both sides afterwards (the live one from hooks and the
* minted one on the node), so the next cold restore does not replay it.
*/
const watchResumeMiss = (deadId: string): void => {
let fired = false
let seen = ''
// `unsub` is assigned on the line after the timer is armed, and `stop` is pushed to
// `cleanups` where an unmount can call it at any moment — a `const` read before its
// assignment would throw out of a teardown path. Optional call, idempotent.
let unsub: (() => void) | undefined
const stop = (): void => {
clearTimeout(timer)
unsub?.()
unsub = undefined
}
const timer = setTimeout(() => stop(), RESUME_MISS_WINDOW_MS)
unsub = transport.onData(sid, (chunk) => {
if (fired) return
// Escape sequences and line breaks removed: the CLI colours its own output and tmux
// re-wraps it at the pane width, so a raw match would miss a line that straddles a
// column boundary. Bounded, so a chatty pane cannot grow this without limit.
seen = (seen + cleanEcho(chunk)).slice(-4096)
if (!resumeSessionMissing(agentId, deadId, seen)) return
fired = true
stop()
void (async () => {
const pane = await queryPaneWithin(
() => api.pty.paneCommand(id),
RESTART_EXIT_TIMEOUT_MS
)
// `null` is "we could not see the pane", never "nothing is running in it" — the
// same contract every other reader of this query keeps.
if (!isShellCommand(pane)) return
const { command: fresh } = assembleResumeCommand(
{
agentId,
customAgent,
sessionId: undefined,
permissionMode: mode,
model: data.agentModel,
sharedIdentity: shared,
approvalCaps: await ensureCodexLaunchCaps(
capabilityAgentId(agentId),
data.ssh || data.sshRemoteTmux || session.source === 'relay'
),
launchCmdOverride: agentLaunchOverride(agentId, ownerProjectId)
},
agentEnvSnapshot()
)
if (!fresh) return
agentStatusStore.getState().setSessionId(id, undefined)
if (data.agentSessionId) updateNodeData(id, { agentSessionId: undefined })
writeWhenShellReady(fresh)
})()
})
cleanups.push(stop)
}
if (cmd) writeWhenShellReady(cmd) // same shell-startup race as initialCommand
// A resume can name a conversation that does not exist — the minted id whose launch
// never ran (an armed `--after` node, a truncated launch line), or a hook-fed id whose
// transcript is gone. The CLI then prints one line, exits, and the node keeps its agent
// badge over a pane sitting at a bare shell (issue #707). Watch for the CLI's own
// refusal, naming THIS id, and start the agent fresh instead. Armed only when we
// actually asked to resume something and only for an agent whose message we measured;
// everything else is byte-identical to before. See terminal/resume-fallback.ts.
if (cmd && priorId && detectsResumeMiss(agentId)) {
watchResumeMiss(priorId)
}
} else if (fresh && pausedNow) {
// The auto-resume above was skipped (that's the feature), but this mount's PANE is
// brand new either way — tmux respawned it, whether from the deep "pause & end session"
// recycle or from a genuine reboot that took a shallow-paused session's tmux with it.
// The later Resume's pane-recognition (see `decideWakeResume`) would otherwise refuse a
// user whose default shell sits outside the `isShellCommand` allowlist (xonsh/elvish/…)
// forever: a PAUSED chip that can never resume, with a live conversation on disk. Record
// what this fresh pane actually is, the same way the exit half does — replacing any
// stale record a pre-reboot shallow pause left behind, which described a pane that no
// longer exists.
//
// No ownership gate here, and none is owed: nothing is being QUIT: this pane was just
// respawned by tmux and holds a brand-new shell, which is the context the later resume
// is meant to launch into. The gate belongs where an exit is written.
agentStatusStore.getState().setHibernatedContext(id, captureWakeContext(await readPaneOwner()))
}
})
.catch((err: unknown) => {
// Same reason as the fulfilled path: we are no longer waiting on the host.
clearTimeout(slowSpawn)
// THE missing handler, and the answer to "some terminals are black" (2026-08-06).
//
// A rejected create means core started NOTHING: no session to tear down, no data gate to
// open, nothing to unwire. The only thing owed is telling the user — and until now nobody
// did. The rejection went nowhere, the node kept the empty xterm it had mounted with, and
// the result was a black rectangle with no message and no way back short of deleting the
// node. The failure was in the main-process log the whole time.
//
// `life.dead` first: a node unmounted while its spawn was in flight has no state worth
// writing, and `setCo` would publish into a key the next mount reads.
if (life.dead) return
setCo(termKey, { spawnError: err instanceof Error ? err.message : String(err) })
})
})()
// In-place agent restart (Canvas node menu / bulk palette): ask the CLI to quit, wait until a
// shell owns the pane again, then relaunch it with the provider's own `--resume` — so a newly
// released model shows up in the CLI's model list without losing the conversation.
//
// Registered HERE, in the effect body, not in the spawn continuation above: an ADOPTED terminal
// (park → remount) returns from that continuation immediately and never reaches it, yet its
// agent is just as restartable. The effect body runs on every mount, fresh or adopted.
//
// Everything the closure needs is read at CALL time. The provider session id and the agent
// state arrive asynchronously over the agent-status hooks — usually well after mount — and
// `sessionId` (this effect's PTY session) is still null while `create()` is in flight.
const restartIo: DeliveryIo = {
// The SAME write path the cold-restore delivery above uses, gated on the session's own
// lifetime: a delivery still running when this session is torn down must neither write into
// nor subscribe to a dead transport. A PARK deliberately does not trip `life.dead` — the PTY
// is alive and adoptable, so a restart that began before the unmount still lands in its pane.
write: (d) => {
if (sessionId && !life.dead) transport.write(sessionId, d)
},
onData: (cb) => (sessionId && !life.dead ? transport.onData(sessionId, cb) : () => {})
}
// Published for the header's Remote Control toggle (its one gated Enter). Never cleared: the
// write is already a no-op once this session is dead, and the next lifecycle run replaces it.
rawWriteRef.current = restartIo.write
// The wake buffer flushes held keystrokes through the SAME session-scoped, lifetime-gated write
// as the resume line — so a flush into a torn-down session no-ops instead of throwing. Published
// to the ref the wake `.then` (component body) reads; re-set on every mount, which is when a new
// `restartIo` closure captures a live `sessionId`/`life`.
paneWriteRef.current = restartIo.write
// Is there still a pane to restart in? A spawn in flight has no session yet; a real teardown
// flips `life.dead`; and a session another client DESTROYED (or one recycled with no
// replacement) is gone while this component happily stays mounted showing the overlay — the
// same states the park branch in the cleanup below refuses to park. Writing `/exit` into any of
// them reaches nothing and would be reported as a 6-second "failed (exit timeout)".
const restartTarget = (): boolean => {
const coNow = getCo(termKey)
return !!sessionId && !life.dead && !coNow.closed && !coNow.ended
}
const unregisterRestart = registerAgentRestart(
id,
guardConcurrentRestart(id, async (targetAgentId?: AgentId, targetModel?: string, restartShell?: boolean, clearEnv?: boolean, beforeRecycle?: () => Promise<RecyclePatch | void>) => {
const st = agentStatusStore.getState().byId[id]
const currentNode = getNode(id)
const agentSessionId = restartSessionId(st?.sessionId, currentNode?.data.agentSessionId)
// `data.agentId` can change after a successful same-base swap while this deliberately
// long-lived terminal effect stays mounted. Read the node NOW instead of trusting the
// value captured when the pane attached, or a later plain Restart would silently reopen
// the old agent again.
const sourceAgentId = createdAgentId(currentNode?.data)
// "Restart on subscription": recycle the session VANILLA — strip the gateway + inherited
// provider env so the agent falls back to its OWN default provider (Claude's subscription,
// Copilot's GitHub routing). No model change, no agent change: same agent, same
// conversation, resumed by the cold-restore path once the fresh shell is up. It recycles
// (not in-place `/exit`) for the same reason a model switch does — tmux env changes do not
// retroactively change an existing shell, so the gateway vars baked into the live session
// can only be dropped by respawning. Relay sessions belong to another core/settings store,
// so this Mac's gateway-stripped env must never be pushed into one.
//
// This branch is gated SEPARATELY from the shared `restartEligibility` below: clearEnv
// uses `terminateForeground` (SIGTERM the foreground group by PID — no `/exit` typed into
// the pane), so it is safe to interrupt a `working`/`blocked` session. Gateway overload —
// the scenario this exists for — shows up mid-turn, and "wait for the turn to finish" is
// impossible when the gateway is down. `clearEnvEligibility` permits busy for that reason;
// `restartEligibility` must NOT, because its `/exit` would answer a permission dialog.
if (clearEnv) {
if (session.source === 'relay') return 'not-eligible'
const clearGate = clearEnvEligibility(sourceAgentId, agentSessionId)
if (!clearGate.ok || !sourceAgentId) return 'not-eligible'
// Identity-gated (same as a model switch): core SIGTERMs the foreground group ONLY if
// this agent still owns it, so a stale menu can never kill vim or a build in this pane.
const stopped = await api.pty.terminateForeground(id, sourceAgentId)
if (stopped === 'unsupported') return 'host-unsupported'
if (!stopped) return 'not-eligible'
transport.recycle(id)
// `clearEnv` rides the respawn's `transport.create` (read from data above) to strip env at
// spawn; the cold-restore auto-resume relaunches the same agent against the default provider.
// The node's `agentModel` is a GATEWAY model id (the one a model switch stored, or the one a
// gateway node was created with): it only resolves through the gateway the strip just removed.
// Leaving it set would make the resume line append `--model <gateway-model>`, which the
// subscription CLI does not know — so the agent fails to launch against the subscription with
// a model name that does not exist there. Drop it: the CLI's own default model is what
// "subscription" means, and a later model switch (or plain Restart re-applying the gateway)
// sets it again.
updateNodeData(id, (node) => ({
clearEnv: true,
agentModel: undefined,
respawnNonce: ((node.data.respawnNonce as number | undefined) ?? 0) + 1
}))
return 'restarted'
}
const gate = restartEligibility(sourceAgentId, st?.state, agentSessionId)
if (!gate.ok || !sourceAgentId || !agentSessionId || !restartTarget())
return 'not-eligible'
const target = targetAgentId ?? sourceAgentId
const settings = useSettings.getState().settings
const builtinTarget = agentConfig(target)
const customTarget = builtinTarget
? undefined
: settings.customAgents.find((c) => c.id === target)
// Session ids are provider-specific. A stale context menu (or settings edit while it is
// open) must never feed a Claude id to Codex, nor launch a custom agent that was deleted.
if (
(!builtinTarget && !customTarget) ||
capabilityAgentId(target) !== capabilityAgentId(sourceAgentId)
)
return 'not-eligible'
const selectedModel = targetModel
? normalizedAgentModel(target, targetModel)
: normalizedAgentModel(
target,
getNode(id)?.data.agentModel as string | undefined
)
// A model switch must rebuild the terminal session: URL/key env was fixed when that shell
// was spawned and may have been configured AFTER this node was created. Do not type the
// harness's slash-exit command here — an agent composer can treat it as prompt text. Core
// instead SIGTERMs the pane's foreground non-shell process group, then recycling gives the
// replacement shell the current gateway env. Relay sessions belong to another
// core/settings store, so a local gateway must never be pushed into one.
if (targetModel) {
if (!selectedModel || session.source === 'relay') return 'not-eligible'
// Identity-gated: core SIGTERMs the foreground group ONLY if `target`'s harness still
// owns it, so a stale model-switch menu can never kill vim or a build in this pane.
const stopped = await api.pty.terminateForeground(id, target)
if (stopped === 'unsupported') return 'host-unsupported'
if (!stopped) return 'not-eligible'
transport.recycle(id)
updateNodeData(id, (node) => ({
agentId: target,
agentModel: selectedModel,
respawnNonce: ((node.data.respawnNonce as number | undefined) ?? 0) + 1
}))
return 'restarted'
}
// "Restart agent and shell": same quit + recycle as a model switch, but the agent and model
// are UNCHANGED — the point is a FRESH shell that re-sources the user's profile/env (a
// change to .zshrc, or an env var set after this node was created), which typing the resume
// line into the existing shell never picks up. The respawn's cold-restore auto-resume
// relaunches the agent (`--resume <sid>`), so the conversation continues in the fresh shell.
// Relay sessions are excluded for the same reason a model switch is: their shell env belongs
// to another core/settings store, and recycling here would respawn against this Mac's env.
if (restartShell) {
if (session.source === 'relay') return 'not-eligible'
// Read NOW, before the first await: this node is on the active canvas at call time, and
// the project may be switched while the CLI quits (see `settleRecycledNode`).
const ownerProjectId = owningProjectId()
const exited = await performExitPhase({
agentId: target,
sessionId: agentSessionId,
io: restartIo,
paneCommand: () => api.pty.paneCommand(id),
// A user-asked restart, like performRestartResume: a CLI that is slow to quit is
// waited on rather than left to quit unwatched (issue #899 was this exact action).
lateExitMs: RESTART_LATE_EXIT_MS,
isLive: restartTarget
})
if (exited !== 'exited') return exited
// Swallowed: a failed step must not strand the pane at a bare shell — the recycle below
// still brings the conversation back (on whatever account the node is bound to).
const patch = beforeRecycle ? await beforeRecycle().catch(() => undefined) : undefined
transport.recycle(id)
settleRecycledNode({
onCanvas: !!getNode(id),
agentId: target,
patch: patch ?? undefined,
updateLive: (rebind) =>
updateNodeData(id, (node) => ({
...rebind,
respawnNonce: ((node.data.respawnNonce as number | undefined) ?? 0) + 1
})),
updateStored: (rebind) => useProjects.getState().rebindNode(ownerProjectId, id, rebind),
dropPark: () => disposeParkedTerminal(termKey),
markDirty: markWorkspaceDirty
})
return 'restarted'
}
// Built HERE, not inside the choreography: the shared assembly builder is the single funnel
// for every CLI launch path (shared/agents/launch.ts) and the mode is a renderer-side, async
// read — exactly as the cold-restore relaunch above does it. Without it a canvas running
// in acceptEdits/plan would come back from a restart in the default mode, silently.
// Re-resolved at call time for the same reason as there: the mode is a property of how a
// session is launched, not of the node. Inheritance-aware: a custom agent's baseAgent/args
// are re-applied so a restart of a claude-base proxy resumes correctly.
// Env for ${env:…} substitution in launchCmd/args. `api` is session-scoped: a LOCAL pane
// resolves the desktop window's raw-ipcMain snapshot; a relay tab's host registers no
// env-snapshot handler at all (a host env dump must never cross to a peer — the PR #195
// leak class), so the request settles empty and the missingEnv gate below refuses instead
// of typing a mangled line. Builtins reference no env tokens, so they skip the round-trip.
const launchEnv = customTarget
? await api.agent.envSnapshot().catch(() => ({}))
: {}
// Warm the owning project before the SYNCHRONOUS override read below — a restart can be the
// first thing a user does after a boot, and a cold snapshot would silently relaunch through
// the bare CLI. Bounded and never-rejecting (see `warmOwningProjectId`).
const ownerProjectId = await warmOwningProjectId()
const { command, missingEnv } = assembleResumeCommand(
{
agentId: target,
customAgent: customTarget,
sessionId: agentSessionId,
permissionMode: await ensureActivePermissionMode(target),
approvalCaps: await ensureCodexLaunchCaps(
capabilityAgentId(target),
data.ssh || data.sshRemoteTmux || session.source === 'relay'
),
model: selectedModel ?? undefined,
// The launch-command override rides the restart too (the global layer is undefined for
// a custom target, which already owns its launchCmd) — it is a property of how the
// agent launches, so the owning project's own value applies here as well.
launchCmdOverride: agentLaunchOverride(target, ownerProjectId)
},
launchEnv
)
// Never type a knowingly mangled launch line (for example `--token ''`) into the pane.
// Settings already surfaces these missing names in its preview; a stale menu after an env
// change degrades to the ordinary not-eligible notice and leaves the shell untouched.
if (missingEnv.length) return 'not-eligible'
return performRestartResume({
// Source and target were proven to share one capability base above, so this resolves to
// the same exit + resume grammar while the explicit command selects the target binary.
agentId: target,
sessionId: agentSessionId,
io: restartIo,
// An unusable session id leaves this undefined and performRestartResume refuses the
// restart on its own `resumeCommand` gate — nothing is written either way.
command,
killLine: getTerminalKillLine(),
// Session-scoped (`api`, not the global preload), like readScrollback above: a relay
// tab's pane lives on the host, and only its own api can see it.
paneCommand: () => api.pty.paneCommand(id),
// Re-asked on every poll: a session that dies under the restart reports honestly instead
// of counting a phantom, and stops polling a pane that no longer exists.
isLive: restartTarget,
// The delivery has its own (echo-verify) lifetime, so hand it to the session: a real
// teardown runs `cleanups`, and a session that died while we waited for the shell cancels
// it outright rather than parking a timer on a corpse.
onDelivery: (cancel) => {
if (life.dead) cancel()
else cleanups.push(cancel)
},
onResumed: markRelaunched
})
})
)
// Eco / hibernation (`settings.agentHibernationEnabled`): the same two halves as the restart
// above, registered as a PAIR because they are driven far apart in time — Canvas's sweep quits
// an idle, offscreen CLI to reclaim its RAM, and the node's own wake resumes the conversation
// when the user comes back to it. Same `io`, same `paneCommand`, same `isLive`, same
// `guardConcurrentRestart` node id, so a sweep and a menu restart can never write into one pane
// at once. Registered in the effect BODY for the same reason as the restart closure: an adopted
// (parked → remounted) terminal never reaches the spawn continuation.
const unregisterHibernate = registerAgentHibernate(id, {
exit: guardConcurrentRestart(id, async (): Promise<ExitPhaseOutcome> => {
// "Is the user looking at this session STILL?" — re-asked at FIRE time, never trusted from
// the plan, the same discipline as `mayDisposeOffscreen`. A sweep can spend ~12 s working
// through its batch, and the node whose turn comes last may be one the user panned back to
// (or opened as a card modal) and is now typing in: KILL_LINE + `/exit` would land in a
// pane they are watching, taking their half-written prompt with it. Worse, the visible
// EDGE has already passed by then, so no wake trigger is left and the node would sit
// SLEEPING on screen until clicked. Deliberately the SAME `isNodeWatched` the plan and the
// nudge ask — a second copy of this question is how the modal clause went missing once.
if (isNodeWatched(id)) return 'not-eligible'
// SSH / relay sessions are excluded in v1, exactly as the offscreen dispose excludes them
// (offscreen-policy.ts): the exit and its much later resume would race the ControlMaster /
// relay lifecycle, and a wake that cannot reach the host leaves a dead conversation behind.
// Read at CALL time — a local project can BECOME an SSH project long after this mount.
if (offscreenRemoteRef.current) return 'not-eligible'
const st = agentStatusStore.getState().byId[id]
// Already paused (shallow OR deep — deep has `hibernated` unset, so this is the only
// thing that catches it): the plan already excludes this via `HibernationCandidate.paused`,
// but a dropped SessionEnd hook POST could otherwise leave a deep-paused node reading as
// an ordinary idle `done` candidate between the plan and this fire-time re-ask. The pane is
// already bare — see `alreadyExited` in the manual pause closure for the same rule.
if (st?.paused) return 'not-eligible'
const agentSessionId = st?.sessionId
// Re-asked here, not trusted from the plan: a node that started working between the sweep's
// decision and its turn must keep its turn (BUSY_STATES — an exit line typed into a
// permission prompt ANSWERS it).
const gate = restartEligibility(agentId, st?.state, agentSessionId)
if (!gate.ok || !agentId || !agentSessionId || !restartTarget()) return 'not-eligible'
// ── IS THE CLI ACTUALLY IN THIS PANE? (issue #823) ──────────────────────────────────────
// Everything above asks about the node's STATE; this asks about the pane, and it is the
// only question that makes "resume it where we exited it" a promise we can keep. `done`
// is a memory of the last hook event, and hooks arrive over a reverse tunnel from wherever
// the agent actually runs: a node whose agent was reached over an interactive `ssh` that
// has since died still reads `done`, and its pane is now the LOCAL login shell. Exiting it
// types `/exit` into that shell, records it as SLEEPING, and hands the later wake a pane
// in which the remote session id cannot resolve — which is exactly the reported bug.
//
// `isAgentPane` (via `decideHibernateExit`) answers from the kernel's foreground process
// group, so it sees through both disguises the name-based read cannot: `node` for every
// npm-installed CLI, and `ssh` for an agent on another machine. Refusing costs one sweep;
// being wrong costs a conversation.
const exitVerdict = decideHibernateExit(await readPaneOwner(), agentId, paneBinaries())
if (exitVerdict !== 'agent-owns-pane') {
// Only the TERMINAL verdict is recorded. `'unreadable'` is a probe that failed (no tmux,
// a pane mid-teardown, a lapsed deadline) and the next sweep re-asks; latching it would
// drop the node out of the plan for the rest of the run on no evidence at all.
agentStatusStore.getState().setPaneUnverified(id, exitVerdict === 'not-in-this-pane')
return 'not-eligible'
}
agentStatusStore.getState().setPaneUnverified(id, false)
const outcome = await performExitPhase({
agentId,
sessionId: agentSessionId,
io: restartIo,
paneCommand: () => api.pty.paneCommand(id),
isLive: restartTarget
})
if (outcome === 'exited') {
// Remember the pane we exited INTO — the proof the wake spends. It carries the command
// (the wake's recognition allowlist does not know `nu`, `xonsh` or `pwsh`, while the exit
// half accepts those through its allowlist-free "the command stopped being the CLI"
// signal, so without it the wake would be STRICTER than the exit that produced it and
// such a user would be hibernated and never woken) AND the pane's own identity, so a
// record cannot authorise a write into a pane it never described.
//
// One extra read rather than a value out of `performExitPhase`, whose behavior is pinned
// byte-for-byte by Task 8's tests. `null` (a pane we could not read) FORGETS the old
// record: absent is refused, and that is the correct answer for an exit whose landing we
// did not witness. A stale record must never stand in as permission to type into today's
// pane.
agentStatusStore.getState().setHibernatedContext(id, captureWakeContext(await readPaneOwner()))
}
return outcome
}),
resume: guardConcurrentRestart(id, async (): Promise<ResumePhaseOutcome> => {
const st = agentStatusStore.getState().byId[id]
const agentSessionId = st?.sessionId
if (!agentId || !agentSessionId || !restartTarget()) return 'not-eligible'
// Command FIRST, pane check LAST. Both of these awaits can take a moment (the claude
// version probe behind `ensureActivePermissionMode` most of all), and whatever is asked
// first is stale by the time the delivery runs — so the fact that must be freshest is the
// one asked last: what owns the pane we are about to type into.
// Same builder, same await, same reasoning as the restart closure above: the permission
// mode is a property of how a session is LAUNCHED, so it is re-resolved now (a wake can be
// hours after the exit, and days after the node was created). Inheritance-aware via the
// shared assembler, so a custom agent's baseAgent/args are re-applied on wake.
//
// Deliberately the BARE command, with no shared-identity launcher: this types into a pane
// that already exists, and a tmux session created before the launcher was installed does
// not carry its directory on PATH — naming it there would be `command not found` where a
// plain `codex resume` works. A restarted codex node therefore rejoins as a plain client
// until its next cold start. Fail open, same rule as everywhere else in this feature.
const customAgent = agentConfig(agentId)
? undefined
: useSettings.getState().settings.customAgents.find((c) => c.id === agentId)
// Same warm-up as the cold-restore and restart paths: the override read inside the builder
// is synchronous, and a wake can be the first launch after a boot. Bounded, never rejects.
const ownerProjectId = await warmOwningProjectId()
const { command } = assembleResumeCommand(
{
agentId,
customAgent,
sessionId: agentSessionId,
permissionMode: await ensureActivePermissionMode(agentId),
approvalCaps: await ensureCodexLaunchCaps(
capabilityAgentId(agentId),
data.ssh || data.sshRemoteTmux || session.source === 'relay'
),
sharedIdentity: false,
// The launch-command override lives on the user's own PATH (or is an absolute path),
// not in a generated launcher dir, so it rides the wake too — project layer included.
launchCmdOverride: agentLaunchOverride(agentId, ownerProjectId)
},
// Same boot-time env snapshot as fresh launch / cold restore, so a wake types the same
// line the node launched with (empty on browser/relay by design).
agentEnvSnapshot()
)
// Refused BEFORE anything is written. `performResumePhase` gates on this same bare command
// and would refuse too — but the KILL_LINE below is ours, so leaving this check to it
// meant an unusable session id erased the pane's line (three times, once per wake trigger)
// and then declined to resume.
if (!command) return 'not-eligible'
// THE load-bearing gate of the wake half. Hours can pass between the exit and this
// resume, and the pane is a REPL the user can type into: by now it may belong to vim, to
// `top`, or to a claude the user launched by hand — and a launch line typed into a live
// program is sent to that program, as a message or a mangled command. A pane we cannot
// READ is refused for the same reason.
//
// What this asks is not "is a shell here?" but "is this the pane we exited the CLI in?".
// The difference is the whole of issue #823: a name-based read cannot tell the local login
// shell that an agent's `ssh` died back to apart from the shell that agent would have left
// behind, so it typed the resume into the wrong machine. The proof travels with the
// hibernation record instead, taken at the exit while the difference was still visible
// (`decideHibernateExit`), and this is where it is spent. See wake-identity.ts for the
// measurements and for why a node with no proof — every node hibernated by the build that
// shipped the bug — is refused rather than guessed at.
//
// `exitedByUs` splits the two wake families: a deep "pause & end session" RECYCLES the tmux
// session and a `dropped` node's CLI died on its own, so neither has a pane of ours to
// match; both keep exactly the shell recognition they have today, and both gain the
// agent-running refusal they did not.
const stWake = agentStatusStore.getState().byId[id]
const verdict: WakeVerdict = decideWakeResume({
owner: await readPaneOwner(),
recorded: stWake?.hibernatedContext,
exitedByUs: !!stWake?.hibernated,
agentId,
binaries: paneBinaries()
})
// Always written, so a refusal that has since been fixed does not leave a stale sentence on
// the chip. `null` for `'resume'` and for the transient `'unreadable'` — the latter is
// timing, and the trigger's bounded retry (which reads this field) owns it.
agentStatusStore.getState().setWakeBlocked(id, wakeRefusalReason(verdict))
if (verdict !== 'resume') return 'not-eligible'
// Clear the line before the launch line goes in. The shell above is the one WE exited to,
// hours ago — nothing stops a passer-by (or a stray paste, or the user's own aborted
// command) from having left a half-typed line at its prompt, and `deliverCommand`'s first
// write is not preceded by a Ctrl-U. The exit half clears the line for exactly this
// reason; the wake half owes the same. Deliberately HERE and not inside
// `performResumePhase`: that function's output is pinned byte-for-byte by Task 8's tests,
// and the restart path (which just cleared the line itself) must not clear it twice.
const killLine = getTerminalKillLine()
restartIo.write(killLine)
return performResumePhase({
agentId,
sessionId: agentSessionId,
io: restartIo,
command,
killLine,
isLive: restartTarget,
onDelivery: (cancel) => {
if (life.dead) cancel()
else cleanups.push(cancel)
},
onResumed: markRelaunched
})
})
})
// Manual "Pause session" (the PAUSE action: node context menu only — shared by the canvas
// right-click and the sessions sidebar row menu, which reuses this same `selectionItems`
// builder; no command palette entry, no kanban-card pause button, deliberately deferred): quit
// the CLI and mark the node PAUSED so it does NOT auto-resume on the next reveal or cold
// restart — an explicit Resume (which reuses `agentHibernateFns(id).resume()` above, and now
// has a THIRD surface too — `CardModal`'s own clickable PAUSED chip) is the only way back.
// Deliberately its OWN closure rather than a call into `agentHibernateFns(id).exit()`:
// that one refuses a node the user is currently WATCHING (`isNodeWatched`) — exactly right for
// Eco's own sweep, exactly wrong for a manual pause of the node the user is looking at right now.
const unregisterPause = registerAgentPause(id, {
pause: guardConcurrentRestart(id, async (deep: boolean): Promise<PauseOutcome> => {
// Deep pause recycles the tmux session, which — like `restartShell`'s recycle — must not
// run on a relay session's core (its shell env belongs to the HOST, not this one). Shallow
// pause touches no shell env and is allowed over SSH/relay, same as ordinary Restart/exit.
if (deep && session.source === 'relay') return 'not-eligible'
const st = agentStatusStore.getState().byId[id]
const agentSessionId = st?.sessionId
const gate = restartEligibility(agentId, st?.state, agentSessionId)
if (!gate.ok || !agentId || !agentSessionId || !restartTarget()) return 'not-eligible'
// Already hibernated (Eco already exited this CLI, or a prior shallow pause): the pane is
// ALREADY a bare shell, so asking it to quit again would type `/exit` into that shell as a
// real command — junk output, and it would eat any half-typed line the user left there.
// Skip straight to marking (and, if deep, recycling) — there is nothing left to exit.
const alreadyExited = !!st?.hibernated
// The same pane-ownership question Eco's exit asks, and for the same reason: a manual pause
// ends in the same SLEEPING record and the same much-later wake, so a pause whose CLI is
// not in this pane would leave behind the exact record #823 is about. Skipped when the pane
// was ALREADY exited by us — there is no agent to find, and `alreadyExited` is precisely the
// case where that is expected rather than suspicious.
//
// Unlike the sweep this refusal is NOT latched into `paneUnverified`: that flag exists to
// keep a node out of the automatic plan, and a user who presses Pause is entitled to press
// it again. They get the ordinary `'not-eligible'`, which the menu already has wording for.
if (
!alreadyExited &&
decideHibernateExit(await readPaneOwner(), agentId, paneBinaries()) !== 'agent-owns-pane'
)
return 'not-eligible'
const outcome = alreadyExited
? 'exited'
: await performExitPhase({
agentId,
sessionId: agentSessionId,
io: restartIo,
paneCommand: () => api.pty.paneCommand(id),
isLive: restartTarget
})
if (outcome !== 'exited') return outcome
if (deep) {
// "Pause & end session": also recycle the tmux session for a fuller memory reclaim — the
// exact mechanism `restartAgentNode(…, restartShell: true)` uses, minus the auto-relaunch:
// the next mount is `fresh`, and `paused` (set below, before the recycle takes effect)
// is what keeps that mount's cold-restore auto-resume from firing.
agentStatusStore.getState().setPaused(id, true)
transport.recycle(id)
updateNodeData(id, (node) => ({
respawnNonce: ((node.data.respawnNonce as number | undefined) ?? 0) + 1
}))
} else if (alreadyExited) {
// The pane and its recorded `hibernatedPane` are already correct (Eco/a prior pause set
// them); only the durability changes.
agentStatusStore.getState().setPaused(id, true)
} else {
// Shallow "Pause": identical to an Eco exit — tmux/pane untouched, `hibernated` records
// it so the SLEEPING machinery (pane-recognition on wake) still applies — plus `paused`,
// which is the only thing that changes: no auto-wake on reveal, and no auto-resume should
// the tmux session itself later die and come back `fresh` (a reboot, e.g.).
agentStatusStore.getState().setHibernatedContext(id, captureWakeContext(await readPaneOwner()))
agentStatusStore.getState().setHibernated(id, true)
agentStatusStore.getState().setPaused(id, true)
}
return 'paused'
})
})
// Prepare-for-update (Windows session host, issue #829): ask an idle agent to quit cleanly so
// its conversation is saved before the host ends every session. The same exit half as Pause,
// with the same refusals (busy, not resumable, no session id, CLI not in this pane), but it
// records the node as SLEEPING rather than PAUSED: the update ends the session anyway, and on
// the next launch the cold restore (`fresh` clears `hibernated`) resumes it with `--resume`.
const unregisterUpdateExit = registerAgentUpdateExit(
id,
guardConcurrentRestart(id, async (): Promise<ExitPhaseOutcome> => {
const st = agentStatusStore.getState().byId[id]
const agentSessionId = st?.sessionId
const gate = restartEligibility(agentId, st?.state, agentSessionId)
if (!gate.ok || !agentId || !agentSessionId || !restartTarget()) return 'not-eligible'
if (!agentProcessInPane(agentId, st)) return 'exited'
if (decideHibernateExit(await readPaneOwner(), agentId, paneBinaries()) !== 'agent-owns-pane')
return 'not-eligible'
const outcome = await performExitPhase({
agentId,
sessionId: agentSessionId,
io: restartIo,
paneCommand: () => api.pty.paneCommand(id),
isLive: restartTarget
})
if (outcome === 'exited') {
agentStatusStore.getState().setHibernatedContext(id, captureWakeContext(await readPaneOwner()))
agentStatusStore.getState().setHibernated(id, true)
}
return outcome
})
)
// Coalesce observer bursts: dragging the NodeResizer fires per animation frame, and every
// call is a full cell-geometry measure + a resize IPC → node-pty → tmux (which redraws the
// whole pane). One trailing fit per settle is enough — the canvas node frame itself still
// tracks the drag live; only the terminal reflow waits for the pause.
let resizeTimer: ReturnType<typeof setTimeout> | null = null
const scheduleSettle = (): void => {
if (resizeTimer) clearTimeout(resizeTimer)
resizeTimer = setTimeout(() => {
applyFit()
// The node's chrome can change height without the node moving (tag chips appear, the find
// bar opens), which slides the terminal screen inside it. Re-measured on the same settled
// tick as the fit — a single null check when this terminal holds no grid.
syncGridOrigin()
}, 80)
}
const observer = new ResizeObserver(scheduleSettle)
observer.observe(container)
// The belt to that braces: the node ROOT, because the screen's offset inside the node is
// re-measured in exactly ONE place (`syncGridOrigin`) and the host is the only thing that has
// ever armed it. A chrome change normally resizes the host too — the body absorbs the header's
// height — so this is usually a duplicate tick, but "usually" is not an invariant, and a chrome
// change that repositions the screen WITHOUT changing the host's size would otherwise leave the
// grid drawn at the old offset with no path back (the drag path re-derives from the same stale
// cache). Deliberately the SAME coalescing timer, so a burst that moves both boxes is still one
// trailing tick rather than two fits.
const rootObserver = new ResizeObserver(scheduleSettle)
if (rootRef.current) rootObserver.observe(rootRef.current)
// Returning from another application is when a stale grid origin actually shows up (device
// report 2026-08-04: text and plate drawn down/right of the body, spilling onto the canvas,
// healed only by dragging the node). Electron's `backgroundThrottling` is on by default, so an
// occluded window's rendering lifecycle and timers are throttled — the 80 ms settle timer above
// is exactly the kind of thing that gets delayed or coalesced away, and both mutators are
// change-gated, so a tick that is lost is not retried. These therefore call `syncGridOrigin()`
// DIRECTLY: routing them through the timer would hang the heal off the mechanism being worked
// around. Cost is two DOM reads and two comparisons per window focus, and one null check for
// every terminal in the default renderer modes.
const resyncGridOnReturn = (): void => {
syncGridOrigin()
}
const onVisibilityChange = (): void => {
// Visible only: the hidden edge measures a window nobody is looking at, and an offset
// measured while the page is hidden is no fresher than the one already cached.
if (document.visibilityState === 'visible') resyncGridOnReturn()
}
window.addEventListener('focus', resyncGridOnReturn)
document.addEventListener('visibilitychange', onVisibilityChange)
// Viewport-scoped WebGL, coordinated by the module-level budget (`webgl-budget.ts`): the
// IntersectionObserver only REPORTS visibility to the coordinator, which owns the grant decision
// and all timing (acquire debounce, release delay, and LRU-hidden reclaim so we never exceed the
// budget). IntersectionObserver measures against the rendered box, so React Flow's pan/zoom CSS
// transform is accounted for natively — no coupling to the React Flow store, and it works
// identically in the browser Server Edition. `rootMargin` pre-announces a node panning into
// view. The observer's initial callback (queued shortly after `observe()`) is what reports
// visibility on mount/adopt — this replaces the old unconditional `loadWebgl()` calls in both
// the parked and fresh paths above; the DOM renderer covers the gap until a grant lands.
// (That observer is MOUNT-STABLE and lives in its own effect below — it has to outlive an
// offscreen dispose. This run reaches it by publishing `visibilityReportRef` at the bottom of
// this effect, and a client registered without a fresh verdict seeds itself from
// `wasVisibleRef` in `ensureWebglClient`.)
//
// …unless this terminal paints into the SHARED canvas. Then xterm never draws its pixels, so
// there is no per-terminal context to budget, nothing to acquire on approach and no DOM-strand
// heal to run — the whole webgl client is skipped rather than registered and left idle.
//
// The decision is made on the MODE, not on whether the grid registration then succeeded: a
// node that is collapsed right now registers nothing yet but will on expand, and a terminal
// cannot be allowed to end up holding both renderers (see `dropWebglClient`/`ensureWebglClient`
// for exactly how each half of that breaks). A registration that FAILS — unrecognised
// internals, no readable geometry — leaves this terminal on xterm's own DOM renderer and
// `setupGlyph` arms the budget client from inside that failure path, so it is coordinated
// rather than merely warned about. The mode itself is re-read on every generation bump (the
// subscription below), never only at mount.
//
// The probe asks `sharedGlyphAvailable()`, NOT "does a context object exist right now". The
// atlas is built from a live terminal's device cell, so the context is created by the first
// `setupGlyph` — "none yet" is the normal state at a fresh mount and after every font change,
// and reading it as "not shared" would register a budget client on a terminal that attaches a
// grid a moment later, i.e. both renderers at once. `setupGlyph`/`teardownGlyph` own the
// budget client too, so the invariant holds structurally even if this probe is ever wrong.
if (sharedGlyphAvailable()) setupGlyph()
else ensureWebglClient()
// ...but the mode can also change UNDER a mounted terminal — the user flips the Settings row
// with a canvas full of live sessions — so the subscription below is UNCONDITIONAL, not part
// of the glyph branch. `generation` is bumped for every event that invalidates the decision
// above: the mode turned on, a context disposal (font change, mode off), a session failure.
// A node that never held a grid pays one store subscription and a comparison per bump, which
// for a default-mode user is zero bumps.
//
// This handler TEARS DOWN ONLY. The re-setup is deferred to the participation effect via
// `glyphEpoch`, and the reason is the font-change case: this notification is SYNCHRONOUS
// inside `useSettings.setState` (settings change → the layer's settings subscription disposes
// the context and bumps the generation → we run), which is BEFORE React has committed the
// render that applies `term.options.fontSize` to xterm. Re-registering here would read a
// stale `dimensions.css.cell` and pin the grid to the OLD cell size while the rebuilt atlas
// rasterizes at the new one — and a grid's cell size cannot be changed afterwards, so the
// drift would be permanent until the node remounted. Tearing down early is always safe: the
// context these handles belong to is already gone.
let lastGen = useSharedGlyph.getState().generation
glyphGenUnsub = useSharedGlyph.subscribe((s) => {
if (disposed || s.generation === lastGen) return
lastGen = s.generation
// EVERY node on the canvas subscribes to this one store, and zustand notifies its listeners
// by iterating a Set — a listener that THROWS aborts that loop, so every node registered
// after the thrower never hears the bump at all and is stranded holding handles into a
// context that has just been disposed. One node's bad luck must not become the canvas's.
// Hence: contain the failure here, warn, and let the fan-out continue. This node then sits
// on whatever renderer the failed teardown left it with (a manual Refresh recovers it),
// which is strictly better than silently poisoning its neighbours.
try {
if (!teardownGlyph()) {
escalateRespawn('glyphgrid could not restore the DOM renderer')
return
}
// The budget client follows the mode, so this terminal never holds both renderers (the
// hazard spelled out above). Order matters in both directions and is already right: xterm
// is back on its own renderer by the line above before a budget client may grant it a
// context, and the grid is only (re-)registered by the participation effect the epoch bump
// below schedules — after this. `setVisible` re-states what the IntersectionObserver last
// reported, because it will not fire again until visibility actually changes and a fresh
// client starts out believing it is hidden.
// The SAME test the mount above makes, and it must stay non-creating HERE above all: this
// handler runs BEFORE React has applied a new font size to xterm, so a probe that built a
// context would rasterize the atlas at the OLD cell and pin every regrid to the new one.
// A machine without WebGL2 answers false (creation was attempted and produced nothing) and
// keeps its budget client instead of ending up with neither renderer coordinated.
if (sharedGlyphAvailable()) dropWebglClient()
else ensureWebglClient()
setGlyphEpoch((n) => n + 1)
} catch (err) {
console.warn(`[glyphgrid] generation handler failed for ${id} (continuing)`, err)
}
})
// What THIS session owes a visibility verdict. The IntersectionObserver itself is NOT ours: it
// lives in a mount-stable effect below, because an observer owned by this effect dies with the
// offscreen dispose it is supposed to reverse (the down transition runs this cleanup, and the
// re-run early-returns before ever constructing one — the node would then be blind, and the
// plate permanent). So this effect publishes a REPORT function instead, and the observer always
// calls the live one; `visibilityReportRef` is null exactly while there is no terminal here.
//
// `wasVisibleRef` is the observer's last verdict and is read as the PREVIOUS value here — the
// observer writes it after calling us, so the edge test below is intact.
const reportVisible = (visible: boolean): void => {
// A queued notification can still be delivered after this run's teardown (the observer is not
// disconnected by it, and Blink delivers already-queued entries anyway), and acquiring a
// context onto a parked/disposed terminal is the very leak the budget exists to prevent.
// Belt to the ref-clearing brace in the cleanup below.
if (disposed) return
webglHandle?.setVisible(visible)
// Hidden → visible: issue the one full repaint that cannot be swallowed (the element is
// attached and intersecting RIGHT NOW). This is the master heal for every "stuck blank /
// partial until manual refresh" strand accumulated while off-screen — whichever renderer
// is active, and whatever xterm's own deferred-refresh bookkeeping lost in the meantime.
// One-shot per transition (not per frame), so a zoom-out burst costs one repaint per node.
// The invariant check first: a stray black canvas left by a broken swap while hidden
// would otherwise cover everything the repaint draws (no-op when a webgl grant is live).
// Gated on everSwapped: a node that never swapped renderers has nothing to heal, and
// paying a full repaint per node entering the viewport is what made panning janky.
if (visible && !wasVisibleRef.current && everSwapped) {
verifyCleanDomState('visible')
fullRepaint()
}
}
visibilityReportRef.current = reportVisible
// Is there a live session here worth giving back? `restartTarget` asks exactly that question
// (spawn still in flight ⇒ no session id; a session another client closed, or one that ended
// with no replacement, must never be re-created — the overlays own those states and a revive
// would land on `noSpawn` with an empty screen), and they are the same states the park branch
// below refuses to park. Null while down / between runs ⇒ the timer refuses.
offscreenLiveRef.current = restartTarget
return () => {
disposed = true
// Nothing may restart a node that is no longer mounted — park, respawn and real teardown all
// pass through here. A remount re-registers (superseding, so a stale unregister is inert).
unregisterRestart()
// …and nothing may hibernate or wake one either: with no registration the sweep reads this
// node as unwired (`planHibernation` refuses it) and the wake finds nothing to resume into.
unregisterHibernate()
unregisterPause()
unregisterUpdateExit()
observer.disconnect()
rootObserver.disconnect()
// The visibility observer is NOT disconnected here — it is mount-stable and must outlive an
// offscreen dispose (see the effect below). What dies with this run is what it feeds: clear
// both published functions, but only if they are still OURS (a respawn's new run has already
// published its own by the time this cleanup executes).
if (visibilityReportRef.current === reportVisible) visibilityReportRef.current = null
if (offscreenLiveRef.current === restartTarget) offscreenLiveRef.current = null
// Torn down HERE, not through `cleanups`: that array is carried over by a park and only run
// at a real teardown, so pushing onto it would stack one more focus listener (closing over a
// dead effect's grid) on every park/adopt cycle. These belong to this effect run, exactly
// like the two observers above.
window.removeEventListener('focus', resyncGridOnReturn)
document.removeEventListener('visibilitychange', onVisibilityChange)
if (resizeTimer) clearTimeout(resizeTimer)
if (dwellRef.current) clearTimeout(dwellRef.current)
// The offscreen timer is deliberately NOT cleared here: it belongs to the mount-stable
// observer effect below, reads every input through a ref, and refuses on its own when
// `offscreenLiveRef` is null. Clearing it on a respawn would drop a window that has been
// counting down for minutes.
agentStatusStore.getState().setActive(id, false)
// Teammates stop seeing us in this node's header. releaseFocus, not reportFocus(null): on a
// project switch every node unmounts, and an unconditional clear could undo the focus the
// node we just moved into already published.
presence.releaseFocus(id)
// Subagent render overrides are cleared by the UNMOUNT-only effect below, not here: this
// cleanup also runs for a respawn and for an offscreen dispose. Live agent state survives
// both this cleanup and a project-switch unmount; hooks and explicit deletion own it.
termRef.current = null
fitRef.current = null
searchAddonRef.current = null
if (applyFitRef.current === applyFit) applyFitRef.current = null
if (fullRepaintRef.current === fullRepaint) fullRepaintRef.current = null
// Hand xterm its own pause back before the terminal is parked or disposed: a parked xterm
// must not carry a wrapper whose `covered` reads a dead mount's refs.
releaseBoardPause()
// Free the GPU context on unmount (park or teardown) either way, and unregister from the
// budget coordinator (which releases any held grant + cancels its timers). The park path must
// keep releasing it as it always has (contexts are capped ~16, and a parked terminal is
// off-screen); a remount re-registers a fresh handle and the observer re-reports visibility.
webglHandle?.dispose()
// Give the shared canvas back on the same terms: a parked terminal is off-canvas, so there is
// nothing for its grid to draw, and the adopting mount re-registers. Ordering inside is the
// attachment's contract (xterm back on its own renderer, THEN the grid). A restore that
// FAILED must not be parked — that xterm paints nothing and would be adopted broken — so it
// joins the no-park set the decision below reads. `glyphSyncRef` is cleared only if it is
// still ours: a respawn's new effect has already published its own.
glyphGenUnsub?.()
glyphGenUnsub = null
if (glyphSyncRef.current === syncGlyph) glyphSyncRef.current = null
if (!teardownGlyph()) noParkIds.add(termKey)
// A respawn (worktree move: the ref was bumped before this cleanup ran) needs a FRESH
// session in the new cwd — never park it. A plain unmount with a live session parks:
// the xterm (element detached) and its PTY stay alive so a remount re-adopts them. A session
// another client destroyed — or ended under us with no replacement — is gone: nothing to park
// (and nothing left to keep alive).
const isRespawn = respawnNonceRef.current !== myNonce
const co = getCo(termKey)
if (sessionId && !isRespawn && !co.closed && !co.ended && !noParkIds.delete(termKey)) {
// Park = "subscribed, but not viewing": report no size at all, so this window's (possibly
// small) grid stops clamping every other subscriber's terminal for as long as it stays parked.
// The subscription itself stays — output keeps streaming into the parked xterm — and the
// adopting mount re-reports its size (sentCols/sentRows are NOT carried over; see above).
transport.resize(sessionId, null, null)
term.element?.remove()
const entry: ParkedTerminal = {
term,
fit,
search: searchAddon,
transport,
sessionId,
tmuxBacked: sessionPersistent,
// Snapshot NOW, because the departure effect declared below this one clears this node's
// agent status on this very unmount — every lever reads later and would see nothing.
parkedAgentState: readAgentState(),
agentProcess: readAgentProcessRef.current(),
readSessionEnded: () => agentStatusStore.getState().byId[id]?.sessionEnded === true,
parkedAt: Date.now(),
readAgentState,
cleanups,
life,
// The window RE-ARMS (PARK_RECHECK_MS) while this park is protected, instead of killing a
// plain shell that is still running the user's agent — and instead of leaking the park,
// which is what a plain "skip the dispose" would do.
timer: armParkExpiry(
() => parkDisposable(termKey),
() => {
if (parkedTerminals.get(termKey) === entry) {
parkedTerminals.delete(termKey)
disposeParked(entry)
}
},
parkWindowMs(useSettings.getState().settings.terminalParkMinutes)
),
remote: sshRemoteTmux || session.source === 'relay'
}
disposeParkedTerminal(termKey) // defensive: never stack two entries for one node
parkedTerminals.set(termKey, entry)
// Enforce the park count cap: evict the OLDEST parks (their next remount becomes a warm
// tmux reattach — the post-window behavior, just earlier). Never the entry just parked,
// and never a PROTECTED one — the plan skips those and takes the next-oldest disposable
// park instead, and the cap is simply exceeded when every park is protected (see
// planParkEviction: a bounded cache overrun beats killing live work).
// Eviction MUST observe the POST-ADOPTION map: a project switch flushes every outgoing
// node's cleanup (parking each) BEFORE any incoming node's mount effect adopts its own
// park, so evicting inline would dispose the parks the incoming project is about to
// re-adopt. A microtask is what defers past the whole synchronous passive-effect flush
// (cleanups AND mounts); adoption has removed its entries from the map by then.
queueMicrotask(() => {
const cap = parkCap(useSettings.getState().settings.terminalParkMax)
const remoteKey = (k: string): boolean => parkedTerminals.get(k)?.remote ?? false
for (const k of planParkEviction(
[...parkedTerminals.keys()],
cap,
parkDisposable,
remoteKey
)) {
if (k !== termKey) disposeParkedTerminal(k)
}
})
// A spawn continuation still awaiting its history seed reads this to know the session
// survived this unmount (parked, or adopted by a remount) and must be finished, not killed.
handedOff = entry
return
}
// Real teardown (respawn / permanent delete). `life` is shared, so a spawn continuation of an
// EARLIER effect (this terminal may have been adopted from a park) sees the session die here
// and tears down instead of wiring listeners onto it; `killSession` keeps the kill single.
life.dead = true
// A real teardown (respawn, delete) ends the session this node published as ready. A PARK
// does not, and returns above without reaching here — a parked session is still a live tmux
// session addressable by name, so it stays typeable. An OFFSCREEN RELEASE of a tmux-backed
// session is the same fact from the other side: only the viewer goes, the session keeps
// running and `sendText` reaches it by name — so readiness is kept. MEASURED (2026-09-02):
// clearing it here held a released `--after` node's launch through its dependency going
// `done`, with the badge claiming the terminal "has not started yet", until a camera travel
// revived the node and it fired at once. The plain-shell fallback never reaches this branch
// armed — `shouldDeferReleaseForHeldLaunch` holds the release there — and a respawn while
// down is not a release (the effect early-returned, so there is no session to keep).
if (!(offscreenDownRef.current && sessionPersistent)) setSessionReady(id, false)
cleanups.forEach((fn) => fn())
if (sessionId) killSession(sessionId)
term.dispose()
}
// `offscreenEpoch` is bumped on BOTH offscreen edges: going down runs this effect's cleanup
// (which disposes rather than parks — see `noParkIds` above), coming back up runs the body
// again for a fresh warm attach. It carries no information itself; it is the trigger.
// eslint-disable-next-line react-hooks/exhaustive-deps
}, [data.respawnNonce, offscreenEpoch])
// A respawn asked for while this node is offscreen-disposed must not be swallowed. The effect
// above early-returns while down, so the bump alone would do nothing and the request (Refresh, a
// worktree move, a reconnect flush) would be lost until the user happened to pan back. Coming up
// here IS the respawn: the effect re-runs and creates the session with the node's current data.
// No-op on mount and on every bump of a node that is up, which is every node in the default case.
useEffect(() => {
if (!offscreenDownRef.current) return
offscreenDownRef.current = false
setOffscreenDown(false)
setOffscreenEpoch((n) => n + 1)
}, [data.respawnNonce])
/**
* Viewport visibility — ONE observer for this node's whole life, deliberately not owned by the
* lifecycle effect above.
*
* It feeds two consumers: the WebGL budget coordinator (which grants/reclaims contexts by
* viewport visibility, plus the hidden→visible repaint heal) and the offscreen-dispose state
* machine. The second is why the ownership had to move. An observer built by the lifecycle effect
* is disconnected by that effect's cleanup — and the down transition IS that cleanup, after which
* the re-run early-returns before constructing a new one. The node would be blind from that
* moment on: the revive branch unreachable, the plate permanent (only a header Refresh or a
* project switch could recover it), and the policy's "switching the setting to 0 can never strand
* a disposed terminal" promise false. Same reasoning, same shape as `useDiscardWhenHidden`.
*
* Everything mutable therefore arrives through a ref, read at CALL time: what the current
* lifecycle run wants done with a verdict (`visibilityReportRef` — always the LIVE webgl handle,
* never a disposed one, and null while there is no terminal), whether a session exists to give
* back (`offscreenLiveRef`), whether this node is remote or selected, and the setting itself
* (re-read on every callback, so switching the feature off disarms a timer armed minutes ago).
*
* IntersectionObserver measures the rendered box, so React Flow's pan/zoom transform is accounted
* for natively — no coupling to its store, and identical behavior in the browser Server Edition.
* `rootMargin` pre-announces a node panning into view. The `observe()` call's initial delivery is
* what reports visibility at mount.
*/
useEffect(() => {
const container = bodyRef.current
if (!container || typeof IntersectionObserver === 'undefined') return
// The observer's own latest verdict, kept so a window-backgrounded EDGE (which the observer
// never sees — a hidden window still has a viewport) can be re-stated through the same path.
let intersecting = false
let observed = false
// One verdict, whoever produced it: the observer, or the window being put away / brought back.
// `visible` is already the EFFECTIVE value (`effectiveVisible`) — while the window is
// backgrounded every node reports itself offscreen, so every consumer below (WebGL budget,
// hibernation sweep, liveness poll, offscreen release) sees "nobody is looking", and every
// fire-time gate of the release still applies unchanged.
const onVerdict = (visible: boolean): void => {
// The renderer half first: it reads `wasVisibleRef` as the PREVIOUS verdict for its
// hidden→visible edge test, so the write below must come after it.
visibilityReportRef.current?.(visible)
const wasVisible = wasVisibleRef.current
wasVisibleRef.current = visible
// Publish the same verdict for the hibernation sweep, which runs in Canvas and cannot see
// this node's box. One observer, two consumers — a second observer would be a second
// opinion about the same rectangle.
setNodeOffscreen(id, !visible)
// …and the wake edge: a hibernated node the user has just panned back to gets its
// conversation resumed before they can reach for the chip. No-op (one map lookup) for a
// node that is not hibernated, which is every node in the default case. A `paused` node is
// excluded — see the mount-timer trigger above for why (`shouldAutoWake`).
const stVisible = agentStatusStore.getState().byId[id]
if (visible && !wasVisible && shouldAutoWake(stVisible?.hibernated, stVisible?.paused))
wakeRef.current()
// …and the liveness check, for the same reason and on the same edge: a node whose CLI died
// while nobody was looking should say so by the time the user has finished panning to it,
// not on the interval's next tick. Cheap — the asker's own gate returns before any I/O for
// a node that is not a parked agent.
if (visible && !wasVisible) void livenessAskRef.current?.()
// A visible node is not in an offscreen stretch at all — the next hidden edge starts a
// fresh clock for the Eco deferral's cap.
if (visible) offscreenSinceRef.current = null
// …and the offscreen-dispose state machine. Every decision is the pure
// `planOffscreenVisibility`; this block only executes the plan.
// Backgrounded: the shorter of the user's window and the background dwell (`0 = never`
// still wins). Only a NEW timer picks this up — one already armed by an earlier pan keeps
// its own deadline, which is at most the ordinary offscreen window.
const disposeMs = backgroundReleaseMs(
offscreenDisposeMs(useSettings.getState().settings.offscreenTerminalMinutes),
isWindowBackgrounded()
)
const plan = planOffscreenVisibility({
visible,
down: offscreenDownRef.current,
timerArmed: !!offscreenTimerRef.current,
disposeMs
})
if (plan.cancelTimer && offscreenTimerRef.current) {
clearTimeout(offscreenTimerRef.current)
offscreenTimerRef.current = null
}
if (plan.revive) {
offscreenDownRef.current = false
setOffscreenDown(false)
setOffscreenEpoch((n) => n + 1) // re-run the lifecycle effect → fresh warm tmux attach
}
if (plan.armTimer && disposeMs !== null) {
// When this offscreen stretch began — the clock the Eco deferral's cap is measured
// against. Stamped only here, where a NEW timer is armed (the plan refuses to re-arm
// while one is pending), so a pan that keeps reporting hidden cannot keep pushing it out.
offscreenSinceRef.current = Date.now()
const fireRelease = (): void => {
offscreenTimerRef.current = null
// Every input re-asked at FIRE time, never at arm time: ten minutes is long enough for
// all of them to have changed. `wasVisibleRef` is the observer's own latest verdict.
if (
!mayDisposeOffscreen({
visible: wasVisibleRef.current,
remote: offscreenRemoteRef.current,
selected: selectedRef.current
})
)
return
// The setting can also have been switched OFF while this timer counted down; a fire
// that disposed anyway would take a buffer the user has just asked us to keep.
const liveSettings = useSettings.getState().settings
if (!releaseStillEnabled(liveSettings.offscreenTerminalMinutes)) return
// Nothing to give back (no session yet, or one that was closed/ended under us) ⇒ no
// dispose. A null ref means no lifecycle run is live at all, which answers the same way.
if (!offscreenLiveRef.current?.()) return
// LIVE WORK ON A PLAIN SHELL (issue #126): this release is only "give the buffer back,
// re-attach later" while tmux is underneath. Without it the pty is the shell, so
// disposing an offscreen agent node kills the CLI mid-turn — panning away is not a
// request to stop it. Defer on the same retry the Eco ordering uses, but with no cap:
// what this waits for (the turn ending) always comes, and giving up would BE the bug.
// Asked after `offscreenLiveRef`, so the persistence ref is only read for a session
// this run actually has.
if (
shouldDeferReleaseForLiveWork({
tmuxBacked: sessionPersistentRef.current,
agentState: readAgentStateRef.current(),
agentProcess: readAgentProcessRef.current()
})
) {
// Re-stamp the offscreen clock: this node is not RELEASABLE yet, and the Eco
// deferral's cap is measured from the start of the releasable stretch. Without this
// a long live-work wait would blow that cap outright, so the release that finally
// runs would skip the hibernate-first ordering and forfeit the CLI's hundreds of MB
// at the exact moment they became reclaimable. The stretch effectively begins when
// the work ends.
offscreenSinceRef.current = Date.now()
offscreenTimerRef.current = setTimeout(fireRelease, OFFSCREEN_DEFER_RETRY_MS)
return
}
// A HELD LAUNCH ON A PLAIN SHELL (the fifth lever): the `--after` launch this node holds
// is typed into the pane by session name, and without tmux the release destroys that
// pane. Nothing brings a released node back but the camera, so the launch would sit
// QUEUED until the user happened to pan over it. Same cadence, same drain: the hold
// ends when the launch fires. (Tmux-backed: released as normal — see the teardown,
// which keeps such a session READY because it stays typeable by name.)
if (
shouldDeferReleaseForHeldLaunch({
tmuxBacked: sessionPersistentRef.current,
armed: armedRef.current
})
) {
offscreenSinceRef.current = Date.now()
offscreenTimerRef.current = setTimeout(fireRelease, OFFSCREEN_DEFER_RETRY_MS)
return
}
// ECO ORDERING (see `shouldDeferReleaseForEco`): hibernate first, release second. This
// release would UNWIRE the node — the lifecycle effect tears down, the hibernate pair
// unregisters, and `planHibernation` then reads the node as unwired — and at the
// shipped defaults it fires at 10 minutes against a 30-minute idle window, so the
// canonical "finish a turn, pan away" session never hibernated at all. The viewer is
// ~15 MB; the CLI is hundreds. So wait for the big prize, on the sweep's own cadence,
// and only up to the capped total — a node that can never hibernate must not hold its
// viewer forever.
const ecoStatus = agentStatusStore.getState().byId[id]
if (
shouldDeferReleaseForEco({
ecoEnabled: liveSettings.agentHibernationEnabled,
resumableAgent: hibernationTargetRef.current,
hibernated: !!ecoStatus?.hibernated,
// Same "unknown idle is not idle" rule the policy applies: with no hook event seen
// in this run there is no idle clock, `planHibernation` refuses this node outright,
// and waiting for a hibernation that cannot come would hold every warm node's
// viewer for the full cap after each app restart.
idleKnown: ecoStatus?.lastEventAt !== undefined,
offscreenElapsedMs: Date.now() - (offscreenSinceRef.current ?? Date.now()),
idleMinutes: liveSettings.agentHibernationIdleMinutes,
offscreenMinutes:
liveSettings.offscreenTerminalMinutes ?? OFFSCREEN_DISPOSE_MS_DEFAULT / 60_000
})
) {
offscreenTimerRef.current = setTimeout(fireRelease, OFFSCREEN_DEFER_RETRY_MS)
return
}
offscreenDownRef.current = true
// The cleanup must DISPOSE, not park: parking keeps the very buffer this feature exists
// to give back. Set before the state flip, since that flip is what runs the cleanup.
noParkIds.add(termKey)
setOffscreenDown(true)
setOffscreenEpoch((n) => n + 1)
}
offscreenTimerRef.current = setTimeout(fireRelease, disposeMs)
}
}
const io = new IntersectionObserver(
(entries) => {
intersecting = entries[entries.length - 1]?.isIntersecting ?? false
observed = true
onVerdict(effectiveVisible(intersecting, isWindowBackgrounded()))
},
{ rootMargin: '256px' }
)
io.observe(container)
// Before the observer's first delivery there is no verdict to re-state; that first delivery
// reads the flag itself.
const offBackgrounded = subscribeWindowBackgrounded((bg) => {
if (observed) onVerdict(effectiveVisible(intersecting, bg))
})
return () => {
offBackgrounded()
io.disconnect()
if (offscreenTimerRef.current) {
clearTimeout(offscreenTimerRef.current)
offscreenTimerRef.current = null
}
}
// `termKey` is stable for this node's lifetime (see its declaration); listed so the effect is
// honestly keyed on what its closure captures.
}, [termKey])
// There is deliberately NO unmount-scoped store cleanup here (issue #402). Live agent status
// survives the unmount — selecting a session in another project swaps the whole active canvas,
// but the session we left is still alive and must remain Running or Waiting in the cross-project
// sidebar. The subagent fan-out survives for the same reason: an unmount says the COMPONENT went
// away, not that the work did, and a still-running subagent's card cleared here could never come
// back (`start` only fires from live hook events, and a subagent already past its PreToolUse
// emits no second one — the card was gone for the rest of its run). Canvas's ephemeral-node memo
// skips cards whose parent is not on the active canvas, so a kept entry renders nothing while
// away and simply reappears on switch-back. Clearing is owned by the signals that actually mean
// "this fan-out is over": a genuine new turn / `sessionPhase === 'end'` in Canvas's status
// listener, and every permanent-removal path (`deleteNodes`, cross-project `closeSession`,
// `deleteProject`), which must call `clearForParent` explicitly now that unmount does not.
// glyphgrid origin sync. React Flow rewrites these two props per frame while the node is
// dragged; `setOrigin` is change-gated inside the engine, and a drag is exactly the gesture the
// shared camera already handles at that rate, so there is deliberately no extra throttling here.
// Declared AFTER the lifecycle effect so the mount order is register-then-push (that first push
// is a no-op — the grid was registered at this same origin). For every terminal in the default
// renderer modes this whole effect is one null check per position change.
useEffect(() => {
const grid = glyphGridRef.current
if (!grid) return
const nodePos = { x: positionAbsoluteX, y: positionAbsoluteY }
const origin = bodyWorldRect(nodePos, glyphBodyOffsetRef.current)
grid.setOrigin(origin.x, origin.y)
// The PLATE travels with the node too, and from the SAME cached box — a drag moves the node,
// never the body's offset or size inside it, so this is arithmetic rather than a DOM
// measurement sixty times a second. Skipped until the body has been measured once (the
// register path does that), so a drag can never collapse the plate to a zero rect.
const box = glyphPlateBoxRef.current
if (!box) return
const plate = bodyPlateRect(nodePos, box.offset, box.w, box.h)
grid.setPlateRect(plate.x, plate.y, plate.w, plate.h)
// DO NOT "fix" this by measuring the DOM here. Reading the offset per frame is the obvious
// answer to a stale cache and it is the wrong one — this effect runs on every frame of a drag,
// for every dragged node. The cache is the right structure; what it needed was more occasions
// to be REFRESHED, which is what the lifecycle effect's two ResizeObservers and the window
// focus / visibilitychange listeners now provide.
}, [positionAbsoluteX, positionAbsoluteY])
// Glass cell backgrounds follow the node's tint alpha (slider, Reduce Transparency). Backgrounds
// are only recomputed for CHANGED cells, so an alpha change rebuilds the WebGL model — debounced
// while the slider is dragged (scheduleGlassCellAlpha); the shared glyph grid stands glass down,
// and so does this. Declared ABOVE the applyLiveOptions effect: the glyphgrid effect below that
// one must stay immediately after it (see its comment).
const glassCellAlpha = tint && !glyphMounted ? tint.alpha : null
useEffect(() => {
glassCellAlphaRef.current = glassCellAlpha
const term = termRef.current
if (!term) return
// Glass turned on after this terminal's WebGL grant: install the wrap now (idempotent).
if (glassCellAlpha !== null && webglAddonRef.current) installGlassCellBackgrounds(webglAddonRef.current)
return scheduleGlassCellAlpha(term, glassCellAlpha, () => term.clearTextureAtlas())
}, [glassCellAlpha])
// Live-apply the appearance settings to the running terminal, so a Settings change reaches the
// terminals already on the canvas instead of only the next fresh one.
//
// This must stay ONE effect that also runs on mount: a terminal ADOPTED from the park cache
// carries the options it was built with, and this pass is what brings it up to date. Splitting
// the new options into a second effect would work by accident today and break the moment one of
// them skips the mount run.
//
// A cell-geometry change (font, line height, letter spacing) means a different grid — route it
// through applyFit (not a bare fit.fit()) so the pty is told the new size like any other resize,
// instead of running at a grid nobody renders. Under co-attach applyFit is also what REPORTS our
// size, so it must go through it or this client would silently keep clamping the shared pty to
// its pre-change grid. A palette change costs no resize — just a repaint we force ourselves.
useEffect(() => {
const term = termRef.current
if (!term) return
const { metricsChanged, themeChanged } = applyLiveOptions(term, visual, glass)
if (metricsChanged) applyFitRef.current?.()
if (themeChanged) fullRepaintRef.current?.()
}, [visual, glass])
// glyphgrid participation — whether this node should hold a grid RIGHT NOW.
//
// ORDERING IS THE POINT, and it is why this effect is declared HERE, immediately after the one
// that writes `term.options.fontFamily/fontSize`. React runs a commit's effects in declaration
// order, so by the time this runs xterm has already re-measured its character cell and its
// renderer's `dimensions.css.cell` — the number `setupGlyph` registers the grid with — is the
// NEW one. A font change reaches us as a `glyphEpoch` bump raised synchronously from the
// generation notification, i.e. BEFORE that commit; re-registering there would pin the grid to
// the old cell size forever (a grid's cell size cannot be changed after `register`). The font
// settings are in the deps as well as the epoch, so the re-setup still lands after the options
// even if the two ever arrive in separate renders. Do not move this effect above the one above.
//
// It also owns every state in which this node must not be on the shared canvas although it is
// mounted — `glyphOff` names them all (collapsed, ⌘M, stacked over another node, being dragged)
// and the ref beside it carries the same answer to `setupGlyph`'s own gate. Each drops the grid
// and re-registers on the way back, through the SAME teardown/setup machinery that collapse and
// ⌘M have always used: `teardownGlyph` clears `glyphMounted` (so `term-node--glyphgrid` comes off
// the node root) and removes `glyphgrid-mode` from the xterm element, which is exactly what makes
// the body opaque and the DOM rows visible again. Nothing here is a special case for stacking.
//
// ORDERING, the second time: `glyphOff` is built from a RENDER-TIME read of the opaque set, which
// Canvas stores during its own render — i.e. before this component rendered at all. So on the
// commit that ends a drag, `dragging: false` and the post-drop overlap answer arrive TOGETHER,
// and this effect makes one decision instead of attaching a glyph and tearing it down again a
// pass later. Do not "simplify" that read into state; state is exactly what lagged.
//
// `dragging` (this node's own prop) is kept alongside because it flips synchronously at gesture
// start and needs nobody else. Children of a dragged GROUP frame never get it — React Flow's
// `getDragItems` excludes them — which is why the set carries `gestureTerminalIds` too, and why
// one gesture answer coming from two places is deliberate rather than redundant.
//
// No-op (one ref null check) unless this node participates in the shared canvas.
useEffect(() => {
glyphSyncRef.current?.(!glyphOff)
// `visual` stands in for what used to be the two font deps. It is the whole appearance bundle
// (family, size, line height, letter spacing, theme, cursor), so it changes on every setting
// that moves the character cell — and on a few that do not. A theme-only change therefore costs
// one grid re-register the old deps would have skipped; that is the safe direction, because the
// cost is a re-register on a rare user action while the miss would pin the grid to a stale cell
// size for the life of the context.
}, [glyphOff, glyphEpoch, visual])
// Kanban board opened/closed: re-evaluate our size vote. Open → applyFit reports null (yield the
// grid to a card-modal viewer); close → it re-reports the real fit. On the first run boardOpen
// matches the ref's init value, and applyFit is guarded (no-op when nothing changed), so this
// never fires a redundant resize at mount on the common canvas-view path.
useEffect(() => {
boardOpenRef.current = boardOpen
applyFitRef.current?.()
// …and stop (or resume) drawing under it. After the ref write: the pause reads it.
boardPauseSlot.sync()
}, [boardOpen])
// Focus mode engaged/exited anywhere on the canvas: re-run our size vote (applyFit reads
// focusedNodeId() live). Mount-stable — the focused-node subscription above only re-renders
// the node whose own membership flipped, and every OTHER terminal is the one being covered.
// The board pause reads focus too (a focus-mode node stays visible over the board).
useEffect(
() =>
subscribeFocusedNode(() => {
applyFitRef.current?.()
boardPauseSlot.sync()
}),
[]
)
const toggleCollapse = () => setNodes((ns) => toggleCollapsed(ns as CanvasNode[], [id]))
// ---- hover guard: dwell before entering the terminal ----
/**
* Take the keyboard: focus xterm, leave the guard, and report the node active.
*
* Split out of `onBodyEnter` so a deliberate CLICK can run it with no delay — see `onGuardClick`.
*
* `ack` (default true) says a human AIMED at this node, and two things follow from it. It marks
* the node's finish read, which reaches past this machine (`clearUnread` → `ackDone` → the notch
* capsule and the paired phone) on the local session; a relay session's store sends no ack, so
* reading a team tab's finish clears this desktop's mark alone. And it drops the hover guard,
* which is a POINTER contract: the guard makes a quick scroll pan the canvas until the dwell has
* elapsed, so a restore nobody pointed at must leave it armed, or the next pointer entry silently
* skips its dwell and the first wheel scrolls tmux instead. Keyboard focus does not need the guard down: it is an
* overlay, and a programmatic `focus()` is not hit-tested.
*
* Every gesture that reaches here aims at THIS node: a dwell, a click, a sidebar or notification
* jump. The one caller that passes false is the window-activation restore.
*/
const enterNow = (opts?: { ack?: boolean }) => {
const aimed = opts?.ack !== false
if (dwellRef.current) clearTimeout(dwellRef.current)
if (aimed) setArmed(false)
focusXtermUnlessCovered(termRef.current, mdModeRef.current)
useTerminalFocus.getState().remember(id)
agentStatusStore.getState().setActive(id, true)
if (aimed) {
agentStatusStore.getState().clearUnread(id)
}
presence.reportFocus(id)
}
// "Go to node" focus (a sidebar session click, a notification tap): the canvas frames the node
// but does not move keyboard focus into it — xterm only takes the keyboard on a hover-dwell or a
// click (the pan/hover guard). Without this the first keystroke after a sidebar click went
// nowhere until the user clicked or hovered the terminal. `enterNow()` takes the keyboard now,
// skipping the dwell. One-shot: the request is cleared on consume so a later remount cannot
// re-grab focus for a node the user has since left.
const focusReq = useTerminalFocus((s) => (s.nodeId === id ? s.nonce : 0))
const lastFocusReqRef = useRef(0)
useEffect(() => {
if (focusReq === 0 || focusReq === lastFocusReqRef.current) return
lastFocusReqRef.current = focusReq
const { ack } = useTerminalFocus.getState()
useTerminalFocus.setState({ nodeId: null })
enterNow({ ack })
// enterNow closes over live refs/setters; re-running on its identity would fire spuriously.
// eslint-disable-next-line react-hooks/exhaustive-deps
}, [focusReq])
const focusFollowsPointerRef = useRef(focusFollowsPointer)
focusFollowsPointerRef.current = focusFollowsPointer
// Switching to click to focus cancels a dwell that was already counting down.
useEffect(() => {
if (focusFollowsPointer) return
if (dwellRef.current) clearTimeout(dwellRef.current)
dwellRef.current = null
}, [focusFollowsPointer])
const onBodyEnter = () => {
if (dwellRef.current) clearTimeout(dwellRef.current)
// Click to focus (#757): hovering never takes the keyboard. A click still does, at once, through
// the guard (`onGuardClick` → `enterNow`); a drag that started on the guard comes back here and,
// correctly, arms nothing.
if (!hoverTakesKeyboard(focusFollowsPointer)) return
const enter = () => {
// The setting can flip while this dwell is pending; the closure's value would be stale.
if (!hoverTakesKeyboard(focusFollowsPointerRef.current)) return
// While Cmd/Ctrl is held the user is zooming the canvas — don't grab focus / enter the
// terminal; just keep checking until the modifier is released.
if (isZoomModifierHeld()) {
dwellRef.current = setTimeout(enter, 200)
return
}
setArmed(false)
// Sloppy focus: this dwell, not the pointer leaving, takes the keyboard off the terminal the
// user came from — even when the ⌘M view leaves nothing here that could take it.
const held = document.activeElement
if (
held instanceof HTMLElement &&
dwellBlursForeignTerminal({
covered: mdModeRef.current,
activeIsForeignXterm: held.classList.contains(XTERM_INPUT_CLASS) && !rootRef.current?.contains(held)
})
) {
held.blur()
}
focusXtermUnlessCovered(termRef.current, mdModeRef.current)
useTerminalFocus.getState().remember(id)
agentStatusStore.getState().setActive(id, true)
agentStatusStore.getState().clearUnread(id)
// "I am working in this node" — the same signal the agent-status active flag uses, i.e. the
// dwell has elapsed and the terminal actually took the keyboard (a mouse merely passing over
// never gets here). Deduped in the store, so re-entering the same node costs nothing.
presence.reportFocus(id)
}
dwellRef.current = setTimeout(enter, panHoverDelay)
}
const onBodyLeave = () => {
if (dwellRef.current) clearTimeout(dwellRef.current)
// The pointer wandering off — to the canvas, another card, the sidebar, a second display —
// never takes the keyboard away, in either mode: the terminal keeps it and the node stays
// active until another node takes it or the user clicks elsewhere (sloppy focus). That release
// is the focus-loss listener's below, which follows where the KEYBOARD goes rather than where
// the mouse goes. Strict focus-follows-pointer used to blur here, so typing with the mouse
// resting off the node silently went nowhere. Only the guard still follows the pointer while
// focus follows it: a pass-over scroll must pan the canvas until the next dwell.
if (pointerLeaveRearmsGuard(focusFollowsPointer)) setArmed(true)
}
// Who holds the keyboard follows DOM focus and deliberate presses, not the pointer, in BOTH modes
// — the whole mechanism, its measurements and its refusals live in `useClickToFocus` (#757). The
// modes differ in who owns the guard: focus here only in click to focus, the pointer otherwise.
// Every callback is read live from this render; the listeners are bound once, to the node root,
// which is the one element that survives focus mode's reparent.
useClickToFocus({
id,
root: () => rootRef.current,
xtermTextarea: () => termRef.current?.textarea,
mdMode: () => mdModeRef.current,
reparenting: () => reparentingRef.current,
acknowledge: () => enterNow(),
focusXterm: () => focusXtermUnlessCovered(termRef.current, mdModeRef.current),
setArmed: (armed) => {
if (focusDrivesGuard(focusFollowsPointer)) setArmed(armed)
},
remember: () => useTerminalFocus.getState().remember(id),
isActive: () => agentStatusStore.getState().activeId === id,
setActive: (active) => agentStatusStore.getState().setActive(id, active),
reportFocus: () => presence.reportFocus(id),
releaseFocus: () => presence.releaseFocus(id)
})
// While armed, a press might start a node drag — pause the dwell timer so the terminal doesn't
// grab focus mid-drag; the release decides what happens next (`onGuardClick` / `onBodyEnter`).
const onGuardPress = () => {
if (dwellRef.current) clearTimeout(dwellRef.current)
}
/**
* A release on the guard: focus NOW if it was a click, restart the dwell if it was a drag.
*
* Issue #87 — "selecting a terminal node doesn't reliably move keyboard focus; often I have to
* click several times". It was worse than unreliable, it was self-defeating: the release used to
* restart the full `panHoverDelay` (600 ms by default) and the next mousedown CANCELLED it, so
* clicking again — the natural response to "it didn't focus" — actively pushed focus further
* away. Only holding still for the whole dwell ever worked.
*
* The guard exists for a mouse PASSING OVER a terminal on its way somewhere (and for drags that
* start on one), which is why hovering has to wait. A click that did not move the node is not
* ambiguous at all, so it does not wait.
*
* The threshold is what separates the two (`GUARD_CLICK_SLOP`, applied by `HoverGuard`), and it
* is generous on purpose: a few pixels of travel between press and release is a hand, not an
* intent to drag. Past it the node HAS moved, and focusing a terminal the user just repositioned
* would be the old bug in the other direction — a drag lands in `onBodyEnter` instead.
*
* For years this never ran for a left click at all: the guard listened to mouse events, which
* React Flow's d3-drag swallows before React sees them, so only the dwell ever focused. With
* click to focus (#757) there is no dwell, which is how it surfaced. `HoverGuard` explains the
* event path.
*/
const onGuardClick = () => {
if (isZoomModifierHeld()) onBodyEnter()
else enterNow()
}
// ---- file drop: paste dropped file paths into the terminal (native-terminal behavior) ----
const onBodyDragOver = (e: React.DragEvent) => {
if (!terminalOwnsFileInput(mdModeRef.current)) return // the ⌘M view is on top: no drop overlay
if (!Array.from(e.dataTransfer.types).includes('Files')) return
e.preventDefault()
e.dataTransfer.dropEffect = 'copy'
if (!dropping) setDropping(true)
}
const onBodyDragLeave = (e: React.DragEvent) => {
const rt = e.relatedTarget as Node | null
if (!rt || !(e.currentTarget as HTMLElement).contains(rt)) setDropping(false)
}
// Uploads go over the master this node's PTY runs on (`nodeUploadScope`).
const dropProjectId = (): string => nodeUploadScope(data.ssh as SshConnection | undefined)
// How a LOCAL path is spelled for this pane: POSIX escapes everywhere except a Windows core,
// where `\` is the separator and the shell / agent CLI wants quotes. Same core-platform source
// as the file links and the kill line — the filesystem-owning core, never the viewer.
const dropDialectFor = (agentPane: boolean): DropDialect =>
dropDialect({
corePlatform: corePlatformRef.current,
remote: remoteSession,
shell: data.shell || useSettings.getState().settings.defaultShell || undefined,
agentPane,
localDesktop: session.source === 'local' && !isBrowserRuntime(),
viewerWindows: isWindowsPlatform()
})
/**
* Files arriving by DROP or by PASTE become paths in the terminal — what a native terminal does
* on a drop, and the only thing a shell (or an agent reading its prompt) can act on. Shared so
* Cmd/Ctrl+V behaves exactly like the drag, upload overlay included: the events differ only in
* how the files got here, and in whether our window needs raising afterwards.
*/
const insertFiles = async (files: File[], opts: { raiseWindow: boolean }) => {
const term = termRef.current
if (!term || !files.length) return
// Clipboard bytes (a screenshot) have never been a file anywhere, so something has to write
// one before there is a path to paste — worth the same "this is going somewhere" overlay the
// SSH upload gets, since neither is instant and both paste nothing until they finish.
const needsWrite = files.some((f) => !window.nodeTerminal.getPathForFile(f))
const st = agentStatusStore.getState().byId[id]
const paneAgent = agentId ?? st?.agentId
const agentPane = agentProcessInPane(paneAgent, st)
const dialect = dropDialectFor(agentPane)
let paths: string[]
if (data.sshRemoteTmux) {
// Remote terminal: uploading over the ControlMaster takes seconds and pastes nothing until
// it's done, so show an overlay while it runs — without it a drop looks like it silently did
// nothing. (The upload + REMOTE-path resolution itself lives in the shared droppedPaths.)
const projectId = dropProjectId()
if (uploadNoteTimer.current) clearTimeout(uploadNoteTimer.current)
setUploadNote({
text: `Uploading ${files.length === 1 ? files[0].name : `${files.length} files`}…`,
})
try {
paths = await droppedPaths(files, { sshRemoteTmux: true, projectId })
} finally {
setUploadNote(null)
}
if (!paths.length) {
setUploadNote({ text: 'Upload failed', failed: true })
uploadNoteTimer.current = setTimeout(() => setUploadNote(null), 2500)
}
} else if (needsWrite) {
if (uploadNoteTimer.current) clearTimeout(uploadNoteTimer.current)
setUploadNote({ text: 'Saving pasted file…' })
try {
paths = await droppedPaths(files, { sshRemoteTmux: false, projectId: '', dialect })
} finally {
setUploadNote(null)
}
if (!paths.length) {
setUploadNote({ text: 'Could not save the pasted file', failed: true })
uploadNoteTimer.current = setTimeout(() => setUploadNote(null), 2500)
}
} else {
paths = await droppedPaths(files, { sshRemoteTmux: false, projectId: '', dialect })
}
if (!paths.length) return
// Enter the terminal and paste the path(s) like a real drop (trailing space to continue).
if (dwellRef.current) clearTimeout(dwellRef.current)
setArmed(false)
// A drag-drop from another OS app doesn't bring our window forward (esp. macOS), so raise it
// FIRST — otherwise the drag-source keeps keyboard focus and the user types into the wrong app.
// A paste came from THIS window, which already has it.
if (opts.raiseWindow) window.nodeTerminal.focusWindow()
term.focus()
useTerminalFocus.getState().remember(id)
// A pasted image is only reported as attached once the agent's own pane shows it (claude's
// `[Image #N]`); otherwise the receipt says the path went in, unconfirmed.
pasteWithImageReceipt(
term,
paths.join(' ') + ' ',
paths,
agentPane ? paneAgent : undefined,
pasteReceipt.report
)
agentStatusStore.getState().setActive(id, true)
presence.reportFocus(id)
}
const onBodyDrop = async (e: React.DragEvent) => {
if (!terminalOwnsFileInput(mdModeRef.current)) return // covered by the ⌘M view (see predicate)
const files = Array.from(e.dataTransfer.files)
setDropping(false)
if (!files.length) return
e.preventDefault()
e.stopPropagation()
await insertFiles(files, { raiseWindow: true })
}
// Cmd/Ctrl+V of a FILE (copied in Finder/Explorer) or of raw image bytes (a screenshot). A paste
// carrying neither is ordinary text and belongs to xterm — hence the early return, and hence the
// CAPTURE phase: xterm listens on its own textarea below us, so stopping here is the only way to
// keep it from also pasting whatever text the clipboard happened to carry alongside the file.
const onBodyPaste = (e: React.ClipboardEvent) => {
if (!terminalOwnsFileInput(mdModeRef.current)) return // the ChatPanel composer takes its own paste
const files = pastedFiles(e.clipboardData)
if (files.length) {
e.preventDefault()
e.stopPropagation()
void insertFiles(files, { raiseWindow: false })
return
}
// Neither files NOR text: an image-only clipboard that Chromium filtered down to nothing on
// its way to xterm's textarea (see clipboardImages). Ask the async API, which isn't filtered.
// Deliberately NOT prevented/stopped — there is no text for xterm to paste either way, so a
// clipboard that turns out to hold no image is left exactly as the no-op it already was, and
// an ordinary text paste never reaches this branch at all.
if (pasteHasText(e.clipboardData)) return
void clipboardImages().then((images) => {
if (images.length) void insertFiles(images, { raiseWindow: false })
})
}
// The user took over the name (manual rename or ✦ AI-name): stop auto-tracking the session
// and, for rename-capable agents, push the chosen name back to the session.
// Pushing delegates to `pushSessionRename` (lib/sessionRename.ts), which probes the pane
// so `/rename` is never spliced into a typing shell or run in a bare shell, and refuses
// unchanged names via `sessionNameUnchanged` (issues #582, #714).
const applyManualTitle = (raw: string, current: string) => {
const name = raw.trim()
updateNodeData(id, { title: name, titleAuto: false })
if (canRenameNode && name) void pushSessionRename(api.pty, id, name, current)
}
// Close the rename box, committing only if the value actually changed (so just clicking in
// and out doesn't take ownership or fire a spurious /rename). For a manual edit, pass
// the title when the edit began; routing the push through pushSessionRename handles
// the unchanged-command check separately from the ownership change.
const commitTitleEdit = (value: string) => {
setEditingTitle(false)
if (value.trim() !== titleEditStartRef.current.trim()) {
applyManualTitle(value, titleEditStartRef.current)
}
}
// AI-generated names compare against the node's current title (issue #714): the model can
// return the same name back, and clicking "Name with AI" repeatedly must not spam /rename.
const nameWithAi = async () => {
setNaming(true)
const r = await api.pty.generateName(
id,
(data.cwd as string) ?? '',
data.accountId as string | undefined
)
setNaming(false)
if (r.ok) {
const current = titleRef.current ?? (data.title as string) ?? ''
applyManualTitle(r.message, current)
}
}
// Read state is separate from workflow state: selection clears the unread notification, while
// an agent whose turn is done remains "Waiting for your response" until its next prompt starts.
useEffect(() => {
if (selected) agentStatusStore.getState().clearUnread(id)
}, [selected, id, agentStatusStore])
// Keep the node title in sync with the agent session's display name — the name shown in
// `/resume` (`/rename` name, else auto name). This is the authoritative source: `/rename` doesn't
// update the OSC terminal title, so reading the agent's own session store is the only way the name
// shows up after a resume. Resolved strictly by THIS node's sessionId — we do NOT sync until it's
// known, otherwise same-folder nodes would adopt whichever session wrote last. Polls only while
// the title still auto-tracks the session (titleAuto) and stops once the user renames by hand.
// Gated on canReadTitleNode (TITLE_READ_CAPABLE), NOT on canRenameNode: reading a session's name
// and being able to set one are different capabilities, and gemini has only the first. `agentId`
// rides along so main picks the right reader: claude's transcript .jsonl vs grok's summary.json vs
// gemini's update_topic tool call. It is resolved at node creation and immutable thereafter, so
// it does not belong in the dep array.
//
// The ACCOUNT does not get that treatment any more: it is the EFFECTIVE one (the account the
// session is observed running as), which for a plain terminal arrives with the first hook event,
// i.e. AFTER this effect mounted. It rides a
// ref (`accountForReadsRef`, refreshed every render) rather than the deps so a late observation
// is picked up by the very next poll instead of tearing down and restarting the timer chain.
useEffect(() => {
// Not on a relay / team tab (`gates.titleSync`): the name would be read from the host and
// adopted into the title, i.e. this tab would write the host's canvas on a timer.
if (!gates.titleSync) return
if (!canReadTitleNode || data.titleAuto === false) return
const sid = status?.sessionId ?? ''
if (!sid) return
let cancelled = false
// Poll fast (4s) only until the session's name is first seen — a session is named once
// early and rarely renamed after, so back off to 15s then. Each poll is an IPC + a small
// transcript tail read in main, so N agent nodes each shave 3/4 of that steady load.
let delayMs = 4000
let timer: ReturnType<typeof setTimeout> | undefined
const sync = async () => {
if (!titleAutoRef.current || editingTitleRef.current) return
const name = await api.pty.readSessionName(sid, accountForReadsRef.current, agentId)
if (cancelled) return
if (name) delayMs = 15000
if (
name &&
titleAutoRef.current &&
!editingTitleRef.current &&
name !== titleRef.current
) {
updateNodeData(id, { title: name })
}
}
const tick = async () => {
await sync()
if (!cancelled) timer = setTimeout(() => void tick(), delayMs)
}
void tick()
return () => {
cancelled = true
if (timer) clearTimeout(timer)
}
}, [id, gates.titleSync, canReadTitleNode, status?.sessionId, data.titleAuto, updateNodeData])
// The user's own ⌘M flip (the chord, the header toggle) carries a half-typed draft across
// (lib/chatDraftCarry.ts): into the agent's input box before leaving the chat view, out of it
// after opening it. A flip the composer makes itself (`onShowTerminal`) carries nothing. While a
// draft is being typed into the terminal, further presses are ignored: a second carry would type
// it again.
const chatAvailableRef = useRef(chatAvailable)
chatAvailableRef.current = chatAvailable
const carryingRef = useRef(false)
const toggleMdView = useCallback(() => {
if (carryingRef.current) return
if (!mdModeRef.current) {
updateNodeData(id, () => ({ mdMode: true }))
if (chatAvailableRef.current) void carryDraftToChat(session.api.pty, id, agentId)
return
}
if (!chatAvailableRef.current) {
updateNodeData(id, () => ({ mdMode: false }))
return
}
carryingRef.current = true
void carryDraftToTerminal(session.api.pty, id, agentId).finally(() => {
carryingRef.current = false
updateNodeData(id, () => ({ mdMode: false }))
})
}, [id, agentId, session.api.pty, updateNodeData])
// Cmd/Ctrl+M toggles markdown view of this terminal's output — only when hovered, and never while
// a board is up (the card modal owns the chord there; see `canvasOwnsMarkdownChord`).
useEffect(() => {
return window.nodeTerminal.onMarkdownToggle(() => {
if (!canvasOwnsMarkdownChord(hoveredRef.current, isGlobalKanbanOpen() || isKanbanOpen(useProjects.getState().activeProjectId ?? ''))) return
toggleMdView()
})
}, [toggleMdView])
// Best-effort: highlight matches that are in the live xterm buffer (on-screen scrollback).
useEffect(() => {
const sa = searchAddonRef.current
if (!sa) return
if (!searchOpen || !search.query.trim()) {
sa.clearDecorations()
return
}
sa.findNext(search.query, findOpts)
}, [search.query, searchOpen])
// Cmd/Ctrl+F toggles the find-bar while this node is hovered. No main-process interception
// needed (the Electron renderer has no native find UI), unlike Cmd+M.
useEffect(() => {
const onKey = (e: KeyboardEvent) => {
if (hoveredRef.current && effectiveBindings('terminal.find').some((s) => matchesShortcut(e, s, isMac))) {
e.preventDefault()
setSearchOpen((v) => !v)
}
}
window.addEventListener('keydown', onKey, true)
return () => window.removeEventListener('keydown', onKey, true)
}, [])
// The ⌘M face (output view or ChatPanel) covers the xterm: blur it on entry so keystrokes stop
// reaching a pane nobody can see, and hand focus back on exit only if it had it on entry.
useMdModeFocus(mdMode, () => termRef.current, () => rootRef.current, id)
// Full-scrollback capture for the output view (TerminalMarkdownView owns the lifecycle: capture on
// mount, ↻, stale-answer guard, line cap, scroll-to-latest). Session-bound, so a relay tab
// captures the PEER's pane.
const captureFull = useCallback((nodeId: string) => api.pty.capture(nodeId, true), [api])
// Unread = the agent finished (not still working/waiting/blocked) while you weren't looking.
// Drives both the header badge and a node-wide glow so it's obvious at a glance.
const isUnread =
!!status?.unread &&
status?.state !== 'working' &&
status?.state !== 'waiting' &&
status?.state !== 'blocked'
// Whatever the markdown toggle is bound to; '' when the user unbound it, in which case the
// markdown view's hint names the action instead of promising a chord that never fires.
const mdChip = chipFor('node.toggleMarkdown')
const mdHint = mdViewHint({ chip: mdChip, open: mdMode, chatAvailable, hidden: hiddenHeaderButtons })
// The experimental shared glyph renderer paints text on a canvas BELOW the nodes, so a glass
// tint would sit on top of every glyph: glass stands down while a grid is mounted.
const glassOn = glassVars !== null && !glyphMounted
// The header's icon button is conditional, so it is gated on the NORMALIZED icon — the same
// answer NodeIconView gives. Gated on the raw value, an invalid stored icon left an empty button
// (and a flex gap) between the color swatch and the title.
const headerIcon = normalizeNodeIcon(data.icon)
return (
<>
{/* Sibling of the root: .term-node is overflow:hidden and would clip the half-pill. */}
<ColumnPill nodeId={id} />
<div
className={`term-node${selected ? ' selected' : ''}${collapsed ? ' collapsed' : ''}${
isUnread ? ' unread' : ''
}${status?.state === 'working' ? ' working' : ''}${
status?.state === 'waiting' || status?.state === 'blocked' ? ' attention' : ''
}${glyphMounted ? ' term-node--glyphgrid' : ''}${focused ? ' term-node--focused' : ''}${
glassOn ? ' term-node--glass' : ''
}`}
ref={rootRef}
style={glassOn ? { ...glassVars, borderTopColor: data.color } : { borderTopColor: data.color }}
onMouseEnter={() => (hoveredRef.current = true)}
onMouseLeave={() => (hoveredRef.current = false)}
>
{/* Liquid Glass static frost: a filtered copy of the wallpaper behind this node, under its
tint (canvas/GlassFrostSync.tsx). Shown only while the frost is on (styles.css). */}
{glassOn && (
<div
className="term-node__frost"
aria-hidden
ref={frostRef}
style={{ '--node-x': positionAbsoluteX, '--node-y': positionAbsoluteY } as React.CSSProperties}
/>
)}
{/* Paint only: the old resize box in its old place (see .nt-resize-ghost in styles.css). */}
<NodeResizer isVisible={selected && !collapsed && !focused} color="#0a84ff" lineClassName="nt-resize-ghost" handleClassName="nt-resize-ghost" />
{/* Invisible source handle so edges to subagent/loop nodes can attach. */}
<Handle
id="flow-out"
type="source"
position={Position.Bottom}
isConnectable={false}
style={{ opacity: 0, pointerEvents: 'none', bottom: 0 }}
/>
{/* Invisible target handle so a rope from an agent node that opened this can attach. */}
<Handle
id="flow-in"
type="target"
position={Position.Top}
isConnectable={false}
style={{ opacity: 0, pointerEvents: 'none', top: 0 }}
/>
<div className="term-node__header">
<Tooltip label={collapsed ? 'Expand' : 'Collapse'}>
<button
className="term-node__collapse"
aria-label={collapsed ? 'Expand' : 'Collapse'}
onClick={toggleCollapse}
>
{collapsed ? <IconChevronRight /> : <IconChevronDown />}
</button>
</Tooltip>
<Tooltip label="Color">
<button
className="term-node__color"
style={{ background: data.color }}
aria-label="Color"
onClick={() => setShowColors((v) => !v)}
/>
</Tooltip>
{showColors && (
<NodeColorSwatches
className="color-popover"
selected={data.color as string | undefined}
onPick={(c) => {
updateNodeData(id, { color: c })
setShowColors(false)
}}
/>
)}
{headerIcon ? (
<button
className="term-node__icon nodrag"
title="Change icon"
onClick={(e) => {
e.stopPropagation()
void nodeIconDialog({
nodeId: id,
title: (data.title as string) ?? '',
icon: headerIcon
}).then((choice) =>
applyIconChoice(choice, (icon) => updateNodeData(id, { icon }))
)
}}
>
<NodeIconView icon={headerIcon} size={15} />
</button>
) : null}
{editingTitle ? (
<input
className="term-node__title nodrag"
value={data.title}
spellCheck={false}
autoFocus
onChange={(e) => updateNodeData(id, { title: e.target.value })}
// Enter commits, Escape reverts to the value editing started with. The blur that
// follows either keypress is skipped (skipBlurRef) so we don't commit twice; a plain
// focus-loss blur still commits.
onBlur={(e) => {
if (skipBlurRef.current) {
skipBlurRef.current = false
return
}
commitTitleEdit(e.currentTarget.value)
}}
onKeyDown={(e) => {
if (e.key === 'Enter') {
skipBlurRef.current = true
commitTitleEdit(e.currentTarget.value)
} else if (e.key === 'Escape') {
skipBlurRef.current = true
updateNodeData(id, { title: titleEditStartRef.current })
setEditingTitle(false)
}
}}
/>
) : (
<span
className="term-node__title-text nodrag"
title="Click to rename"
onClick={() => {
titleEditStartRef.current = data.title as string
setEditingTitle(true)
}}
>
{data.title || 'Untitled'}
</span>
)}
{status?.session && !sessionNameRepeatsTitle(status.session, data.title) && (
<span className="term-node__session" title={status.session}>
{status.session}
</span>
)}
{/* The GitHub issue this session was started on — opens it on the board (the issue lane
lives there), the same thing the session's board card does with its own `#N`. */}
<IssueRefChip
issueRef={data.issueRef}
onOpen={(ref) => {
const store = useProjects.getState()
openIssueOnBoard(
store.activeProjectId,
ref,
!!store.getProject(store.activeProjectId)?.kanban?.github,
(url) => void api.shell.openExternal(url)
)
}}
/>
{/* Dev servers this session listens on (CLAUDE.md → Dev-server ports). On an SSH project a
row forwards the SAME port over the project's master before opening it. The card modal
draws the same component. */}
<PortsChip
nodeId={id}
projectId={portsProjectId}
remote={sshProject}
onOpenUrl={(url) =>
window.dispatchEvent(new CustomEvent('nodeterm:open-url-node', { detail: { url, sourceNodeId: id } }))
}
menuZIndex={60}
/>
{/* The stations this session opened, and how far along they are — the same ring its board
card and card modal draw (lib/teamProgress). A row travels to that station. */}
{team && <TeamProgressChip stations={team} onTravel={travelToStation} menuZIndex={60} statusStore={agentStatusStore} />}
{/* The fallback, made visible. A Codex node that could not get a managed shared identity
runs a perfectly good plain `codex` — but the user has to be able to SEE that it did,
without reading a log, so the chip states it and its tooltip says why. Absent (and the
node byte-identical to before this feature) whenever identity is shared or unknown. */}
{codexIdentity?.mode === 'plain' && (
<span
className="node-account-chip node-account-chip--warning"
title={codexFallbackText(codexIdentity.reason)}
>
plain codex
</span>
)}
{/* Which Claude account this pane is on — the same component the board card, the card
modal and the sessions sidebar render (CONTRIBUTING: two views of the same nodes).
The spawn-time fallback branch is kept: when the account folder was missing the session
IS on the system account, and the chip must say so rather than name the account we
failed to launch under. */}
<AccountChip
chip={
accountChip && accountFallback
? { ...accountChip, tooltip: 'Account folder missing — running on system account' }
: accountChip
}
warning={accountFallback}
/>
{/* Only where it says something the project tab does not — see `sshChipRepeatsProject`. */}
{showSshChip ? (
<span
className="term-ssh-chip"
title={`ssh ${(data.ssh as SshConnection).user}@${(data.ssh as SshConnection).host}`}
>
SSH {(data.ssh as SshConnection).user}@{(data.ssh as SshConnection).host}
</span>
) : null}
{showUsage && <ContextMeter sessionId={transcript.sessionId ?? null} fromLaunchId={transcript.fallback} nodeId={id} remote={!!remoteSession} agentId={agentId} />}
{showRemoteControl && (
<RemoteControlButton
className="term-node__remote-control"
nodeId={id}
sessionId={transcript.sessionId}
readState={() => agentStatusStore.getState().byId[id]?.state}
pty={session.api.pty}
write={(d) => rawWriteRef.current?.(d)}
/>
)}
{/* Who else is in this node. Subscribes to presence itself — see PresenceChips. */}
<PresenceChips nodeId={id} />
{status?.state === 'working' && (
<span className="term-node__status term-node__status--busy" title={`${agentLabel} is working`}>
<AgentMascot agentId={agentId} />
RUNNING
</span>
)}
{/* Eco: this node's CLI was exited to reclaim its RAM while nobody was looking. The tmux
session, the pane and the scrollback are untouched — only the process is gone — and
revealing the node resumes the conversation. Clickable because the automatic wake can
refuse (a pane that now belongs to something else, a spawn that is still coming up),
and a badge with no way forward is a dead end. Muted on purpose: nothing is wrong. */}
{/* DROPPED: the CLI left this pane and nothing accounted for it — on a busy host, almost
always the OOM killer. Unlike SLEEPING/PAUSED this is NOT a state we chose, so it reads
in the warning colour: the conversation is still on disk, but nothing is running and
nothing will resume it on its own. Clicking resumes it, through the same closure the
hibernation wake uses. Ranked ABOVE the two pause chips because they are mutually
exclusive by construction (`looksDropped` refuses a hibernated or paused node), so the
ordering is about reading the JSX, not about resolving a conflict. */}
{status?.dropped ? (
<button
className="term-node__status term-node__status--dropped nodrag"
title="This session's agent process is gone (it did not exit cleanly) — click to resume the conversation"
onClick={(e) => {
e.stopPropagation()
wakeRef.current()
}}
>
<span className="term-node__status-dot" />
DROPPED
</button>
) : status?.paused ? (
<button
className="term-node__status term-node__status--paused nodrag"
title="Session paused — click to resume"
onClick={(e) => {
e.stopPropagation()
wakeRef.current()
}}
>
<span className="term-node__status-dot" />
PAUSED
</button>
) : (
status?.hibernated && (
<button
className={
'term-node__status term-node__status--sleeping nodrag' +
(status.wakeBlocked ? ' term-node__status--wake-blocked' : '')
}
/* A refused wake used to be visible only as whatever the pane said afterwards — in
the reported case, claude's own red "No conversation found" in a shell the user
never asked to be typed into. The node believed it had woken. Now the refusal has
a sentence, and it lives on the chip that is already the way back: still clickable,
because a re-check is exactly what the user wants once they have fixed the pane
(ssh'd back in, quit whatever took it over). */
title={status.wakeBlocked ?? 'Agent hibernated to save memory — click to resume'}
onClick={(e) => {
e.stopPropagation()
wakeRef.current()
}}
>
<span className="term-node__status-dot" />
{status.wakeBlocked ? 'SLEEPING — NOT RESUMED' : 'SLEEPING'}
</button>
)
)}
{/* Dismissed (cron/schedule) entries are retained as a fact but hidden everywhere they
were shown before — chip included, so the × still does exactly what it always did to
the screen. See agentStatus's `loop.dismissed`. */}
{showLoop && status?.loop && !status.loop.dismissed && (
<span
className="term-node__status term-node__status--loop"
title={`Running /${status.loop.kind}`}
>
<span className="term-node__status-dot" />
{status.loop.kind.toUpperCase()}
{status.loop.count > 0 ? ` ×${status.loop.count}` : ''}
</span>
)}
{/* Armed by canvas-control `--after`: this node holds its launch until the stations it
waits on go idle. Shown because an armed node is otherwise indistinguishable from one
that simply failed to start — and it carries the manual escape, because agent state is
transient: after an app restart nothing will ever report `done` again, so without a
"run now" an armed node left over from before the restart would be a dead end. */}
{pendingLaunch && !firstOpenInFlight && (
<span
className={`term-node__status term-node__status--queued nodrag${
(launchDelivery || prExpired || successExpired || successBlocked) && !startingNow
? ' term-node__status--queued-warn'
: ''
}`}
title={launchTooltip(launchDelivery, pendingWaitingOn, pendingLaunch.command, pendingErroredOn, session.source === 'relay', prTooltip, successTooltip, pendingInterruptedOn, pendingHandedOverOn)}
>
<span className="term-node__status-dot" />
{startingNow
? 'STARTING'
: launchDelivery
? '⚠ QUEUED'
: prExpired || successExpired
? '⚠ EXPIRED'
: successBlocked
? '⚠ BLOCKED'
: 'QUEUED'}
<button
className="term-node__queued-run"
disabled={session.source === 'relay' || startingNow}
title={session.source === 'relay' ? "Open the host to run this command" : startingNow ? "Starting in the background" : pendingLaunch.manualOnly ? "Retry launch at a shell prompt" : "Run now without waiting"}
onClick={(e) => {
e.stopPropagation()
// Disarm only on a delivery that actually landed. Dropping `pendingLaunch`
// unconditionally threw the command away whenever the session was not up yet —
// and "not up yet" is precisely the state a user reaches for this button in, so
// the one escape hatch could destroy the thing it exists to rescue.
void launchCommand(id, pendingLaunch.command, true, api).then((outcome) => {
if (outcome === 'submitted') {
useLaunchDelivery.getState().clear(id)
updateNodeData(id, { initialCommand: undefined, pendingLaunch: undefined })
} else {
useLaunchDelivery.getState().markFailed(id, 1)
}
})
}}
>
<IconPlay />
</button>
</span>
)}
{/* Issue #521: the last turn ended on an API/model error (the agent's own `StopFailure`
hook). NOT a state — the station is idle, and the two facts coexist; this is the only
thing on any surface that tells an errored station apart from one that finished. It
clears itself on the next genuine turn. Shown beside a `done`/unknown state only: a
live RUNNING/NEEDS YOU is about the CURRENT turn and speaks for itself. */}
{/* STATION FAILED: a station THIS agent opened has stopped, and this agent was told
(src/core/agents/station-notice.ts). Shown on the orchestrator, not the station — the
station already wears its own TURN FAILED / DROPPED / NEEDS YOU. */}
<StationFailedChip
nodeId={id}
className="term-node__status term-node__status--station-failed nodrag"
dot
/>
{status?.lastTurnError && status?.state !== 'working' && (
<span
className="term-node__status term-node__status--errored"
title={`${agentLabel} ended its last turn on an error \u2014 it produced nothing this turn. Anything armed to wait on this node is held until a turn succeeds.`}
>
<span className="term-node__status-dot" />
TURN FAILED
</span>
)}
{(status?.state === 'waiting' || status?.state === 'blocked') && (
<span
className="term-node__status term-node__status--attention"
title={`${agentLabel} needs your input`}
>
<span className="term-node__status-dot" />
NEEDS YOU
</span>
)}
{/* Deterministic hook-reply approvals (docs/hook-reply-approvals.md): when the node is
blocked on a Claude permission request whose managed hook is holding open (pendingId
known), answer it in one click — no keystrokes into the prompt. Vanishes the moment the
state leaves `blocked` (the store clears pendingId). Never on a relay / team tab
(`gates.approvalButtons`): the answer goes to THIS machine's main, which holds no ticket
for the host's session. */}
{gates.approvalButtons && status?.state === 'blocked' && status?.pendingId && (
<span className="term-node__approve nodrag">
{/* Approve is hidden when THIS ticket is a held AskUserQuestion (lib/approveGate.ts);
Deny still declines it. A held ExitPlanMode keeps Approve: the hook maps a plain
allow to "restore the pre-plan mode" (docs/hook-reply-approvals.md). */}
{canPlainApprove(status) && (
<button
className="term-node__approve-btn term-node__approve-btn--allow"
title="Approve this permission request"
onClick={() =>
void sendHeaderAnswer(window.nodeTerminal.answerPermission, {
nodeId: id,
pendingId: status.pendingId!,
decision: 'allow'
})
}
>
✓ Approve
</button>
)}
<button
className="term-node__approve-btn term-node__approve-btn--deny"
title="Deny this permission request"
onClick={() =>
void sendHeaderAnswer(window.nodeTerminal.answerPermission, {
nodeId: id,
pendingId: status.pendingId!,
decision: 'deny'
})
}
>
✕ Deny
</button>
</span>
)}
{isUnread && (
<span
className="term-node__status term-node__status--unread"
title="Finished — click to mark read"
>
<span className="term-node__status-dot" />
unread
</span>
)}
{!editingTitle && <span className="term-node__spacer" />}
{canMoveIntoWorktree && (
<Tooltip label="Move this terminal into the group's worktree">
<button
className="term-node__move-worktree nodrag"
onClick={() => moveIntoWorktreeHandler?.(id)}
>
<IconMoveTo />
</button>
</Tooltip>
)}
{/* Refresh: rebuild THIS node's view and re-attach to the same session (the context
menu's "Refresh terminal", one click away). In the header because the cases that
need it are exactly the ones where the node is unusable — a pane that never painted,
a scroll that stopped responding after a long sleep — and a right-click on a dead
view is the last thing a user wants to hunt for. Distinct from "Restart agent",
which quits the CLI itself; this touches nothing but the viewer. */}
{!isHidden('refresh', hiddenHeaderButtons) && (
<Tooltip label="Refresh — rebuild this view; the session keeps running">
<button
className="term-node__refresh nodrag"
onClick={(e) => {
e.stopPropagation()
updateNodeData(id, (n) => ({
respawnNonce: ((n.data.respawnNonce as number | undefined) ?? 0) + 1
}))
}}
>
<IconReload />
</button>
</Tooltip>
)}
{/* `claudeTranscript`, NOT `showUsage`: the transcript leg of the search is gated on the
claude-transcript fact (see the `useTerminalSearch` call above), so keying the label on
the meter promised a codex/gemini node a conversation search it does not run. */}
<Tooltip
label={gates.transcriptSearch && claudeTranscript ? 'Search terminal + conversation' : 'Search this terminal'}
>
<button
className="term-node__search nodrag"
onClick={() => setSearchOpen((v) => !v)}
aria-pressed={searchOpen}
>
<IconSearch />
</button>
</Tooltip>
{!isHidden('mic', hiddenHeaderButtons) && (
<Tooltip label="Dictate into this terminal">
<button
className="term-node__mic nodrag"
onClick={(e) => {
e.stopPropagation()
window.dispatchEvent(new CustomEvent('nodeterm:dictate', { detail: { nodeId: id } }))
}}
>
<IconMic />
</button>
</Tooltip>
)}
{!isHidden('ai-name', hiddenHeaderButtons) && (
<Tooltip label="Name with AI (from terminal output)">
<button
className="term-node__ai nodrag"
aria-label="Name with AI"
disabled={naming}
onClick={nameWithAi}
>
{naming ? <span className="ui-spinner" /> : <IconSparkle />}
</button>
</Tooltip>
)}
{!isHidden('comments', hiddenHeaderButtons) && (
<Tooltip label="Comments & activity">
<button
className="term-node__chat nodrag"
aria-pressed={commentsOpen}
onClick={() => setCommentsOpen((v) => !v)}
>
<IconChat />
</button>
</Tooltip>
)}
{!isHidden('hide-fanout', hiddenHeaderButtons) && (
<Tooltip label={hideFanout ? 'Show cards & connections' : 'Hide cards & connections'}>
<button
className="term-node__hide-fanout nodrag"
aria-label={hideFanout ? 'Show cards & connections' : 'Hide cards & connections'}
aria-pressed={hideFanout}
onClick={(e) => {
e.stopPropagation()
updateNodeData(id, { hideFanout: !hideFanout })
}}
>
{hideFanout ? <IconEyeOff /> : <IconEye />}
</button>
</Tooltip>
)}
{fanoutCapable &&
!hideFanout &&
fanoutCount >= 2 &&
!isHidden('tidy-fanout', hiddenHeaderButtons) && (
<Tooltip label="Tidy subagent cards into a grid">
<button
className="term-node__tidy-fanout nodrag"
aria-label="Tidy subagent cards into a grid"
onClick={(e) => {
e.stopPropagation()
useAgentNodes.getState().tidyFanout(id)
}}
>
<IconGrid />
</button>
</Tooltip>
)}
{!collapsed && !isHidden('maximize', hiddenHeaderButtons) && (
<MaximizeButton id={id} maximized={!!data.premaxRect} />
)}
<Tooltip label="Close (ends the session)">
<button
className="term-node__close"
aria-label="Close"
onClick={() => {
transport.destroy(id)
// Issue #848: THIS click — and no other teardown — may offer to close the project
// when it removes the last session node. Announced before `deleteElements`, so
// Canvas still sees the node it is deciding about (lib/lastSessionClose).
announceUserClosedSession(id)
deleteElements({ nodes: [{ id }] })
}}
>
<IconClose />
</button>
</Tooltip>
</div>
{searchOpen && !collapsed && (
<FindBar
query={search.query}
onQueryChange={search.setQuery}
matchIndex={search.matchIndex}
matchCount={search.matchCount}
current={search.current}
onNext={handleNext}
onPrev={handlePrev}
onClose={() => setSearchOpen(false)}
/>
)}
{!collapsed && (
<NodeLabels
nodeId={id}
trailing={
mdHint && (
<MdViewHintButton
hint={mdHint}
tooltip={commandTooltip(mdMode ? 'Back to the terminal' : `Open ${mdHint.label.toLowerCase()}`, 'node.toggleMarkdown')}
// The same flip as the chord handler, draft carry included.
onToggle={toggleMdView}
/>
)
}
/>
)}
{/* Run node: launch.json run controls over this terminal (see RunBar). Local
sessions only — a relay tab's or an SSH node's terminal runs on another machine, whose
checkouts and devices this one cannot see. */}
{data.runConfig && session.source === 'local' && !data.ssh && !data.sshRemoteTmux && (
<RunBar nodeId={id} config={data.runConfig} autoStart={!!data.runAutoStart} simulator={data.runSimulator} browser={data.runBrowser} />
)}
{/* Body always mounted (keeps xterm alive); hidden via CSS when collapsed. */}
<div
className={`term-node__body${dropping ? ' dropping' : ''}`}
onMouseEnter={onBodyEnter}
onMouseLeave={onBodyLeave}
onDragOver={onBodyDragOver}
onDragLeave={onBodyDragLeave}
onDrop={onBodyDrop}
onPasteCapture={onBodyPaste}
>
<div
className={`term-node__xterm nodrag nowheel${co.letterbox ? ' letterboxed' : ''}`}
ref={bodyRef}
{...{ [FONT_ZOOM_NODE_ATTR]: id }}
/>
{uploadNote && (
<div className={`term-node__upload${uploadNote.failed ? ' failed' : ''}`}>
{!uploadNote.failed && <span className="term-node__upload-spin" />}
{uploadNote.text}
</div>
)}
{/* Copy receipt / selection hint — floated over the terminal's bottom-right rather than
worn as a header chip. It belongs where the user's eyes just were (the drag they
finished), and the header cannot hold it: on a narrow node with the SSH chip and
RUNNING already there, one more chip pushes the × under `.term-node`'s overflow.
Bottom-RIGHT specifically — every agent CLI writes its input line bottom-LEFT. */}
{copy.feedback && (
<div className={`term-copy-pill term-copy-pill--${copy.feedback.kind}`}>
{copy.feedback.label}
</div>
)}
{pasteReceipt.receipt && (
<div className={`term-paste-pill${pasteReceipt.receipt.ok ? '' : ' term-paste-pill--warn'}`}>
{pasteReceipt.receipt.text}
</div>
)}
{/* Downloads started from a link's right-click menu, reported on the terminal they were
clicked in (the same corner as the copy receipt) — not in a drawer that may be shut. */}
<DownloadStrip
downloads={linkDownloads.downloads}
onDismiss={linkDownloads.dismiss}
className="term-node__dls nodrag nowheel"
/>
{linkMenu && (
<ContextMenu
x={linkMenu.x}
y={linkMenu.y}
items={linkMenuRows(linkMenu.target)}
onClose={() => setLinkMenu(null)}
/>
)}
{/* Offscreen-disposed: the xterm and the PTY client are gone, the tmux session is not.
Deliberately above the overlays below it in the DOM but the least insistent of them —
it states a resting state, not a failure. Nobody is ever looking at it as it appears
(that is the precondition for appearing); it exists for the frame between coming into
view and the reattach redraw, and for a node parked at the edge of the viewport.
…with ONE case where it is seen head-on, and it is deliberate: a COLLAPSED node. The
body is `display: none` while collapsed, so the observed element reports
not-intersecting and a collapsed terminal is disposed after the window even though its
header sits in plain view. Expanding revives it — the display flip changes the
intersection, the observer fires, and the node reattaches. Collapsed is exactly the
state in which nobody is reading this terminal's output, which is why the WebGL budget
has always treated it as hidden too; this feature only agrees with it. Not a bug. */}
{offscreenDown && (
<div className="term-node__offscreen nodrag">
<span>Session running — reattaches on view</span>
</div>
)}
{co.closed && (
<div className="term-node__closed nodrag">
Closed by {closedName} — this session was ended.
</div>
)}
{!co.closed && co.ended && (
<div className="term-node__closed nodrag">
<span>Session ended — the node was moved and never came back.</span>
<button className="term-node__reopen" onClick={reopenEnded}>
Reopen
</button>
</div>
)}
{!co.closed && !co.ended && co.spawnError && (
<div className="term-node__closed nodrag">
<span>This terminal could not be started. {co.spawnError}</span>
<button className="term-node__reopen" onClick={retrySpawn}>
Try again
</button>
</div>
)}
{!co.closed && !co.ended && !co.spawnError && co.offline && (
<div className="term-node__closed nodrag">
<span>
Not connected to {data.ssh ? `${(data.ssh as SshConnection).user}@${(data.ssh as SshConnection).host}` : 'the host'} — this session was not started
locally.
</span>
<button className="term-node__reopen" onClick={reconnectOffline}>
Reconnect
</button>
</div>
)}
{/* Stale working directory (issue #464): a slim TOP banner, never an overlay — the
terminal underneath is alive and may be mid-work. Top edge on purpose: every shell
and agent CLI writes its input line at the BOTTOM, and covering the prompt would be
worse than covering the oldest visible output row. */}
{!co.closed && !co.ended && !co.spawnError && !co.offline && co.staleCwd && !offscreenDown && (
<div className="term-node__stalecwd nodrag">
<span className="term-node__stalecwd-text">
This terminal's folder was deleted (or replaced) — the shell's working
directory no longer exists.
</span>
{!hostedReadOnly && (
<button
className="term-node__stalecwd-restart"
onClick={restartInFolder}
title={`End this shell and start a fresh one in ${(data.cwd as string) || 'the project folder'}. Anything still running in this terminal will end.`}
>
Restart in folder
</button>
)}
<button
className="term-node__stalecwd-dismiss"
onClick={dismissStaleCwd}
title="Dismiss"
aria-label="Dismiss"
>
<IconClose />
</button>
</div>
)}
{/* Launch line refused (#706): same slim TOP banner as staleCwd, for the same reason —
the terminal is alive and the command can still be run by hand, so nothing is
covered. It reports what was measured and names the flag that avoids it; it does not
offer a retry, because retyping the identical line would be truncated identically. */}
{!co.closed && !co.ended && !co.spawnError && !co.offline && co.launchTooLongBytes !== null && !offscreenDown && (
<div className="term-node__stalecwd nodrag">
<span className="term-node__stalecwd-text">
This session's launch command ({co.launchTooLongBytes} bytes) is longer than a
terminal line can carry ({MAX_LAUNCH_LINE_BYTES}), so it was not run. Shorten the
prompt, or pass it with --prompt-file.
</span>
<button
className="term-node__stalecwd-dismiss"
onClick={dismissLaunchTooLong}
title="Dismiss"
aria-label="Dismiss"
>
×
</button>
</div>
)}
{/* Lost conversation: the cold restore could not find the transcript its persisted session
id names, so the agent was launched BARE. Same slim top banner as staleCwd above, and
for the same reason — the terminal underneath is alive; only its history is missing.
Yields to staleCwd (a dead working directory is the bigger problem, and two stacked
banners would cover the screen). No action button: there is nothing to retry, the
conversation is gone. */}
{!co.closed &&
!co.ended &&
!co.spawnError &&
!co.offline &&
!co.staleCwd &&
co.lostSession &&
!offscreenDown && (
<div className="term-node__stalecwd nodrag">
<span className="term-node__stalecwd-text">
The previous conversation could not be found — this agent started fresh.
</span>
<button
className="term-node__stalecwd-dismiss"
onClick={dismissLostSession}
title="Dismiss"
aria-label="Dismiss"
>
×
</button>
</div>
)}
{/* Resume skipped once after "Open here anyway" on a project handed to a hosted team: the
same slim banner as lostSession, and it yields to the same bigger problems. */}
{!co.closed &&
!co.ended &&
!co.spawnError &&
!co.offline &&
!co.staleCwd &&
co.resumeSkipped &&
!offscreenDown && (
<div className="term-node__stalecwd nodrag">
<span className="term-node__stalecwd-text">
Not resumed: this project was shared with a team, and its server may be running this
conversation. Resume it here only once it has stopped there.
</span>
<button
className="term-node__stalecwd-dismiss"
onClick={dismissResumeSkipped}
title="Dismiss"
aria-label="Dismiss"
>
×
</button>
</div>
)}
{/* Gemini CLI retired for personal accounts: the same slim banner as lostSession, and
yields to the same bigger problems. Two actions — an Antigravity node (Google's
replacement) beside this one, and Google's migration guide — plus dismiss. */}
{!co.closed &&
!co.ended &&
!co.spawnError &&
!co.offline &&
!co.staleCwd &&
co.geminiRetired &&
!offscreenDown && (
<div className="term-node__stalecwd nodrag">
<span className="term-node__stalecwd-text">
Google no longer serves Gemini CLI to personal accounts (free, AI Pro, AI Ultra);
Antigravity CLI replaces it. Code Assist licenses, Vertex AI and API keys still work.
</span>
<button
className="term-node__stalecwd-restart"
onClick={openAntigravityNode}
title="Open an Antigravity CLI (agy) node next to this one. Install agy first if it is not on this machine: curl -fsSL https://antigravity.google/cli/install.sh | bash"
>
Open Antigravity
</button>
<button
className="term-node__stalecwd-restart"
onClick={() => void window.nodeTerminal.shell.openExternal(GEMINI_MIGRATION_URL)}
title={GEMINI_MIGRATION_URL}
>
Migration guide
</button>
<button
className="term-node__stalecwd-dismiss"
onClick={dismissGeminiRetired}
title="Dismiss"
aria-label="Dismiss"
>
×
</button>
</div>
)}
{armed && !mdMode && (
<HoverGuard onPress={onGuardPress} onClick={onGuardClick} onDragEnd={onBodyEnter} />
)}
{mdMode &&
(useChat ? (
<Suspense fallback={<ChatPanelFallback />}>
<ChatPanel
nodeId={id}
sessionId={transcript.sessionId}
sessionFallback={transcript.fallback}
cwd={data.cwd as string | undefined}
// A READER (the ⌘M transcript view) takes the account the session actually RUNS
// as, never the creation-time one, so a plain terminal launched under
// `CLAUDE_CONFIG_DIR=~/.claude-2` reads ITS transcript instead of an empty
// system-root one. Spawn/env identity is unaffected — that stays creation-time.
accountId={accountForReads}
agentId={agentId}
// The composer's attach resolves files exactly as a drop onto THIS terminal does.
pathsForFiles={(files) =>
droppedPaths(files, {
sshRemoteTmux: !!data.sshRemoteTmux,
projectId: data.sshRemoteTmux ? dropProjectId() : '',
// The composer feeds the agent CLI, never the shell.
dialect: dropDialectFor(true)
})
}
// `@` lists this node's files where they live: the host's for an SSH node, over the
// same project scope the attach above uploads through.
sshProjectId={data.sshRemoteTmux ? dropProjectId() : undefined}
onShowTerminal={() => {
// An explicit "go to the terminal": the picker just opened there needs the keyboard.
requestTerminalFocusOnExit(id)
updateNodeData(id, () => ({ mdMode: false }))
}}
/>
</Suspense>
) : (
<TerminalMarkdownView
nodeId={id}
capture={captureFull}
hint={mdChip ? `${mdChip} to exit` : 'Exit'}
/>
))}
</div>
</div>
{/* Board-log comments flyout — a SIBLING of the root (overflow:hidden would clip it),
expanding to the node's right. Same feed/composer as the card modal's panel. */}
{commentsOpen && !collapsed && (
<div className="term-node__comments nodrag nowheel" onMouseDown={(e) => e.stopPropagation()}>
<NodeCommentsPanel id={id} />
</div>
)}
{/* Link handles (all terminal nodes): drag right→left to link. Between two context-capable
(Claude) nodes this shares context; from a sticky note it attaches the note as context.
Vertically centered on the side edges; raised above the body so they're never buried.
Siblings AFTER the root, like the resizer: inside a glass root (backdrop-filter = its own
stacking context) their z-index only counted inside it, so the resize controls covered
them and the outer half was clipped. */}
<Handle
id="link-out"
type="source"
position={Position.Right}
className="bridge-handle bridge-handle--out"
data-tip={
contextLinkCapable
? "Link out — drag to another Claude node so they can read each other's context"
: 'Link out — drag to a sticky note to attach it as context'
}
/>
<Handle
id="link-in"
type="target"
position={Position.Left}
className="bridge-handle bridge-handle--in"
data-tip={
contextLinkCapable
? 'Link in — drop a link here to share context with this Claude session'
: 'Link in — drop a sticky note link here to attach it as context'
}
/>
{/* Sibling of the root, not a child: under Liquid Glass the root has a backdrop-filter,
which makes it the containing block for these absolute edges, so they were clipped and
covered (only the top edge stayed grabbable). Out here they sit on the node wrapper.
AFTER the root, never before it: focus mode reparents the root out of this wrapper, and
React inserting a control "before the root" would then throw NotFoundError. */}
<NodeResizer minWidth={NODE_MIN_SIZES.terminal.width} minHeight={NODE_MIN_SIZES.terminal.height} isVisible={selected && !collapsed && !focused} color="#0a84ff" />
</>
)
}