Skip to content

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.

8.2 KB
Raw Blame
/**
 * THE ONE QUESTION EVERY MEMORY LEVER MUST ASK BEFORE IT KILLS A PTY CLIENT: would that kill end
 * work the user has running?
 *
 * The renderer reclaims terminal memory in four places, and all four are written as if dropping a
 * PTY client were free — "the tmux session keeps running and re-attach redraws". That sentence is
 * true only where tmux is actually underneath. On the plain-shell fallback (no tmux installed,
 * tmux switched off in settings, or an install path `findTmux` missed) the pty IS the shell, so
 * the identical call kills the shell and every process under it — an agent CLI mid-turn included.
 *
 * Reported as issue #126: switching projects terminated a working Claude agent, which then
 * auto-resumed from wherever the kill landed ("terminated mid action"). Three of the four levers
 * are the park's (window expiry, LRU cap, memory-pressure drop — see `park-budget.ts`); the fourth
 * is the offscreen viewer release (`offscreen-policy.ts`). They differ in everything except this
 * question, which is why it lives here on its own rather than in whichever module happened to
 * need it first.
 *
 * The predicate is deliberately the NARROWEST one that closes the bug: it takes both halves, and
 * either half alone leaves today's behavior untouched. A tmux-backed session is never protected
 * (the kill costs a redraw, and protecting it would forfeit real memory on the setups where
 * reclaiming it is free); a plain terminal is never protected either. An agent CLI still running
 * in the pane IS protected even when idle (`agentProcess`) — see `wouldKillLiveWork`.
 */
import { WORKING_STALE_MS } from '@shared/agents/stale'
import type { AgentState } from '@shared/agents/normalize'

/**
 * Agent states that mean the CLI is mid-task or holding something open for the user. The same set
 * hibernation refuses to `/exit` (`hibernation-policy.ts`) and for the same reasons: `working` is
 * a turn in flight, `waiting`/`blocked` is a question or a permission request the user is being
 * asked to come back for. `done` and unknown are not evidence of live work.
 */
const LIVE_AGENT_STATES: ReadonlySet<AgentState> = new Set<AgentState>([
  'working',
  'waiting',
  'blocked'
])

export interface LiveWorkInput {
  /**
   * The session survives losing this client — a tmux session, local or remote
   * (`PtyCreateResult.persistent`). False = the plain-shell fallback, where the pty is the shell.
   */
  tmuxBacked: boolean
  /** The node's live agent state (`agentStatus.byId[nodeId].state`); absent = a plain terminal, or
   *  no hook event seen for it yet. */
  agentState?: AgentState
  /**
   * Is an agent CLI believed to be running in this pane, whatever its turn state
   * (`agentProcessInPane`)? Absent = not known, which keeps the state-only rule.
   */
  agentProcess?: boolean
}

/**
 * Would tearing down this terminal's PTY client destroy work that is still running?
 *
 * On a non-persistent pty an IDLE agent is live work too. The CLI process is the conversation's
 * only live holder: killing it and letting cold restore `--resume` it on revive looks harmless, but
 * the resumed CLI fires `SessionStart:resume` and then sits at its prompt emitting nothing. The
 * status mirror commits that boundary as unverified-and-stateless, so agent messaging refuses the
 * node (`targetStatusStale`) for as long as it stays idle — and only a message could end the idle.
 * Measured 2026-09-13 on Windows native ptys: an architect node idle at 12:39, resumed at 13:13 with
 * no user turn, refused every send at 15:28 while its terminal showed Claude at the prompt.
 */
export function wouldKillLiveWork(i: LiveWorkInput): boolean {
  if (i.tmuxBacked) return false
  if (i.agentProcess) return true
  return !!i.agentState && LIVE_AGENT_STATES.has(i.agentState)
}

/**
 * Is an agent CLI believed to be running in the pane? An agent node whose CLI we already exited
 * (`hibernated`, `paused`), that we observed die (`dropped`) or that announced its own exit
 * (`sessionEnded`) holds only a shell — killing that costs nothing a revive cannot restore, so it
 * stays reclaimable.
 *
 * An agent whose hooks never report a session end (codex, opencode: see `SESSION_END_CAPABLE`)
 * keeps reading as running after a deliberate quit. That is the safe direction: memory held, no
 * work lost.
 */
export function agentProcessInPane(
  agentId: string | undefined,
  status:
    | { hibernated?: boolean; paused?: boolean; dropped?: boolean; sessionEnded?: boolean }
    | undefined
): boolean {
  return (
    !!agentId &&
    status?.hibernated !== true &&
    status?.paused !== true &&
    status?.dropped !== true &&
    status?.sessionEnded !== true
  )
}

/**
 * The state to judge a PARKED terminal by: the live store read, with the state captured at park
 * time as a FLOOR under it.
 *
 * A snapshot alone would be stale and a live read alone is not available — because the unmount
 * that parks a terminal is the same unmount that CLEARS its agent status. TerminalNode's
 * departure-only effect exists so a project switch doesn't leave a stale RUNNING badge behind, and
 * it runs right after the lifecycle cleanup that created the park. Every park lever reads the
 * store later than that — the LRU in a microtask, the expiry minutes on — so every one of them saw
 * `undefined` and called a working agent disposable. That is the reported #126 case (a project
 * switch past `PARK_MAX`) and, worse, it made `waiting`/`blocked` parks unprotectable in
 * principle: an agent holding a question open emits no further hook events, so nothing would ever
 * repopulate the store for it.
 *
 * The floor is only a floor, never a latch: hook events for a parked node still land in the store
 * (Canvas's `agent:status` listener is keyed by node id, not by what is mounted), so a turn that
 * ENDS while parked releases the protection on the next re-check, and one that starts adds it.
 * Live truth always wins; the snapshot only answers when there is no live truth to have.
 */
export function effectiveAgentState(
  live: AgentState | undefined,
  atParkTime: AgentState | undefined
): AgentState | undefined {
  return live ?? atParkTime
}

/**
 * The park-time snapshot, AGED: a `working` snapshot stops counting once it is older than
 * `WORKING_STALE_MS`; every other state keeps counting indefinitely.
 *
 * WHY THE SNAPSHOT NEEDS AN EXPIRY THE LIVE STATE DOES NOT. A `working` session that dies without
 * saying so is an ordinary event (Esc during a tool call runs no Stop hook, a killed CLI, a slept
 * machine, a dropped link), and the product already has one answer for it: the stale-working
 * sweep. Neither copy of that sweep can reach a PARKED node's snapshot, though — the renderer's
 * matches `state === 'working'` in the store, and the departure clear on the parking unmount has
 * already blanked that entry; the core's mirror fires an `onNodeStateChange` edge that reaches its
 * own consumers but never the renderer's `agent:status` IPC. So nothing would ever retire this
 * evidence, and the park would re-arm its expiry for the rest of the run, permanently holding one
 * of `PARK_MAX` slots for a session that no longer exists.
 *
 * The window is the SHARED constant, not a new number: this is the same judgment call about the
 * same signal ("a working node this quiet is presumed gone"), and two numbers for one question
 * drift apart. A LIVE `working` reading is deliberately never aged here — the store still knows
 * about that node, so the renderer sweep can and does correct it, and second-guessing a store that
 * says "working" right now would kill a real turn.
 *
 * `waiting`/`blocked` never expires, and that asymmetry is the point: a question held open is not
 * a stale signal, it is a session waiting for the user, and no elapsed time makes ending it right.
 * A snapshot with no timestamp cannot be aged and is treated as fresh — the safe direction, since
 * the alternative drops a live agent's protection over a bookkeeping omission.
 */
export function parkedStateFloor(
  atParkTime: AgentState | undefined,
  parkedAt: number | undefined,
  now: number
): AgentState | undefined {
  if (atParkTime !== 'working' || parkedAt === undefined) return atParkTime
  return now - parkedAt > WORKING_STALE_MS ? undefined : atParkTime
}