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
Merge branch 'feat/win-10-live-links' into feat/windows-parity
reviewced67641d7c1
diff --cc docs/windows-session-host.mdindex bd110d82d,b03de0a46..550eb2917--- a/docs/windows-session-host.md+++ b/docs/windows-session-host.md@@@ -147,8 -145,16 +147,16 @@@ long-lived connection (no positional-FI| `capture` | `capture-pane -p -e [-S -N]` | full, and strictly more (mode restoration — tmux's plain-text capture carries none) || `killSession` | `kill-session -t <name>` | full || `detach` | a client's own `tmux detach-client` | full |-| `listSessions` | `list-sessions -F '#{session_name}'` | full |+| `listSessions` | `list-sessions -F '#{session_name}'` — plus, with `sessionDetails`, `list-windows`/`list-panes` | full; see "Observability" below || `ping` | (liveness probe used during the startup race) | full |+ | `attachExisting {watch: true}` | `attach-session -E -f ignore-size,read-only` (a live link watcher's client) | feature `watch-attach`: subscribes with NO geometry claim and no pause ticket, refuses `write`/`resize` from that connection, never spawns; on an already-attached connection it withdraws the claim (its last voting subscriber left) |+ | `captureVisible` | `capture-pane -p -e` + `display-message '#{cursor_x} #{cursor_y}'` | feature `captureVisible`: visible rows of the ACTIVE buffer only (never history), viewport cursor, `altScreen` — a live link's keyframe |+ | `paneCwd` | `display-message -p '#{pane_current_path}'` | feature `paneCwd`: the cwd the pane last REPORTED (OSC 7 / 9;9 / 633, parsed by `cwd-report.ts`), null until one arrives — never the spawn cwd |++ The last three are **negotiated at hello** (`SESSION_HOST_FEATURES`) like `geometry`/`shutdown`: the+ client never sends one to a host that did not advertise it (an older, long-lived host keeps serving+ everything else and is never replaced for them). Without them: a live link viewer of a node this app+ does not hold is refused (`join-only`), there is no keyframe (R36), and `paneCwd` is null.**Not implemented — deliberately out of scope for this pass:**diff --cc src/core/__fixtures__/no-session-host.tsindex 7f8dc8556,b9b80ea66..3df9eadcd--- a/src/core/__fixtures__/no-session-host.ts+++ b/src/core/__fixtures__/no-session-host.ts@@@ -48,6 -48,10 +48,19 @@@ export function noSessionHost(): RecordsessionHostKillSession: async () => {},sessionHostListSessions: async () => [],sessionHostPaneCommand: async () => null,- sessionHostSendKeys: async () => false+ sessionHostSendKeys: async () => false,+ sessionHostCaptureVisible: async () => null,+ sessionHostPaneCwd: async () => null,+ sessionHostSupportsWatch: async () => false,- sessionHostWatchKnown: () => undefined++ sessionHostWatchKnown: () => undefined,++ sessionHostListSessionsDetailed: async () => null,++ sessionHostMessageOwner: async () => null,++ sessionHostMessagePasteReady: async () => false,++ sessionHostMessageEnvelope: async () => false,++ sessionHostTerminateOwner: async () => 'unsupported',++ sessionHostWriteDetached: async () => false,++ // Error classes are read by `instanceof` checks on catch paths; a fresh class never matches.++ SessionHostProtocolCompatibilityError: class extends Error {},++ SessionHostWatchUnsupportedError: class extends Error {}}}diff --cc src/core/pty-manager.tsindex 1c6269a17,2d985f69a..591fdd760--- a/src/core/pty-manager.ts+++ b/src/core/pty-manager.ts@@@ -215,14 -213,15 +215,19 @@@ importsessionHostMessageEnvelope,sessionHostSendKeys,sessionHostSupported,+ sessionHostTerminateOwner,+ sessionHostWriteDetached,- SessionHostProtocolCompatibilityError+ SessionHostProtocolCompatibilityError,+ watchExistingSessionHostPty,+ sessionHostSupportsWatch,+ sessionHostWatchKnown,+ sessionHostCaptureVisible,+ sessionHostPaneCwd} from './session-host-backend'import type { SessionHostPty } from './session-host-pty'+import type { SessionHostReaperBackend, SessionInfo } from './session-budget'import { NativeWindowsPane } from './native-windows-pane'+import { terminatePaneOwner } from '../session-host/terminate-owner'import type { ProjectSpawnOverrides, ProjectSpawnOverridesReader } from './project-spawn-overrides'// How often we snapshot a live tmux session's scrollback to disk, so a machine reboot (whichdiff --cc src/core/session-host-backend.tsindex e6ae2078a,639b0d195..4eed46d3a--- a/src/core/session-host-backend.ts+++ b/src/core/session-host-backend.ts@@@ -11,9 -11,9 +11,10 @@@ import { platform } from './platformimport {SessionHostClient,SessionHostProtocolCompatibilityError,+ SessionHostWatchUnsupportedError,type HostShutdownOutcome,- type HostUpdateInspection+ type HostUpdateInspection,+ type SessionHostListing} from './session-host-client'import { SessionHostPty } from './session-host-pty'import { ensureStagedHostRuntime } from './session-host-runtime'@@@ -169,8 -190,7 +204,8 @@@ export async function sessionHostKillSereturn getClient().killSession(name, options)}- export { SessionHostProtocolCompatibilityError }+ export { SessionHostProtocolCompatibilityError, SessionHostWatchUnsupportedError }+export type { SessionHostListing }/** `tmux has-session`'s equivalent — currently unused by the create path (which gets `fresh`* straight from the real attach-or-create round trip instead, via `SessionHostPty.ready`) butdiff --cc src/core/session-host-client.tsindex fb0bbb783,162c970f0..a072af405--- a/src/core/session-host-client.ts+++ b/src/core/session-host-client.ts@@@ -2130,38 -2138,4 +2279,38 @@@ export class SessionHostClientconst result = await this.request<ListSessionsResult>({ cmd: 'listSessions' })return result.names}++ /**+ * The observability read (see `SessionHostListing`). Like `inspectForUpdate` it never launches a+ * host when nothing is published — a session reaper, a memory panel or a ports chip asking a+ * question must not start the process whose sessions it is asking about. Every failure (a+ * request that threw, a reply without `names`) is `null`, never an empty listing.+ */+ async listSessionsDetailed(): Promise<SessionHostListing | null> {+ try {+ const connected = !!this.socket && !this.socket.destroyed+ if (!connected) {+ const paths = sessionHostPaths(this.deps.userDataDir)+ const identity = readExistingSessionHostIdentity(paths.statePath, {+ expectedEndpoint: paths.endpoint,+ expectedTokenPath: paths.tokenPath+ })+ if (identity.kind === 'absent') return { running: false, names: [], sessions: [] }+ // Published state is not proof of a live host (a killed host, a reboot): connect only to+ // one that answers. Nothing answering is a FAILED read (null) — never a launch.+ await this.ensureConnected({ launch: false })+ }+ const result = await this.request<ListSessionsResult>({ cmd: 'listSessions' })+ if (!result || !Array.isArray(result.names) || !result.names.every((n) => typeof n === 'string')) {+ return null+ }+ // Read AFTER the request: `request()` is what establishes the connection on a cold client.- const sessions = this.hostSessionDetailsFeature && Array.isArray(result.sessions)++ const sessions = this.hostFeatures.has('sessionDetails') && Array.isArray(result.sessions)+ ? validSessionDetails(result.sessions).filter((row) => result.names.includes(row.name))+ : null+ return { running: true, names: result.names, sessions }+ } catch {+ return null+ }+ }}diff --cc src/session-host/host.tsindex a6ee6676a,a5d1b77a8..e11b710e2--- a/src/session-host/host.ts+++ b/src/session-host/host.ts@@@ -29,10 -29,10 +29,12 @@@ importtype HasSessionResult,type PaneCommandResult,type CaptureResult,+ type TerminateOwnerResult,+ type CaptureVisibleResult,+ type PaneCwdResult,type KillSessionResult,type ListSessionsResult,+ type SessionHostSessionDetail,type ShutdownResult} from './protocol'import { HostSession } from './session'@@@ -346,9 -344,10 +348,13 @@@ async function main(): Promise<void>* session and exit (issue #829): the command is destructive, so an app build that never asked* for it can never trigger it by accident. */const shutdownSockets = new WeakSet<net.Socket>()+ /** Connections that negotiated `sessionDetails`: only these get per-session rows (pid,+ * subscribers, output clock, generation) on `listSessions`. An older client reads `{names}`. */+ const sessionDetailsSockets = new WeakSet<net.Socket>()+ /** Connections that negotiated `watch-attach`: only these may subscribe without a geometry claim.+ * `captureVisible` / `paneCwd` are plain reads and need no per-socket gate — a client that did not+ * negotiate them never sends them, and an older host answers `unknown command`. */+ const watchSockets = new WeakSet<net.Socket>()/** Set while a `shutdown` is ending sessions. New sessions (attach / attachExisting / launches)* are refused for its duration; cleared again only if the shutdown could not end everything. */let shuttingDown = false@@@ -386,7 -385,7 +392,8 @@@: []if (features.includes('geometry')) geometrySockets.add(socket)if (features.includes('shutdown')) shutdownSockets.add(socket)+ if (features.includes('sessionDetails')) sessionDetailsSockets.add(socket)+ if (features.includes('watch-attach')) watchSockets.add(socket)return features.length > 0? { protocolVersion: currentProtocolVersion(), features }: { protocolVersion: currentProtocolVersion() }@@@ -472,8 -471,7 +479,9 @@@// node-pty may flush a queued data callback after its exit callback. Once endSession has// disposed the emulator and broadcast exit, no data may touch or appear after that boundary.if (session.exited) return+ // Output is output whether or not it is shown: the reaper's idleness clock (sessionDetails).+ session.lastOutputAt = Date.now()+ session.noteOutput(data)// Trusted launch input is typed through the same ConPTY and therefore echoed by the shell.// While HostSession verifies that echo, keep the entire chunk out of both renderer push// frames and the reconstructable screen so executable/argv/prompt material stays core-only.diff --cc src/session-host/protocol.test.tsindex d418d38b7,472559950..e0f565477--- a/src/session-host/protocol.test.ts+++ b/src/session-host/protocol.test.ts@@@ -38,27 -31,3 +38,32 @@@ describe('LineFramer', () =>expect(framer.push<any>('{"ok":true}\n')).toEqual([{ ok: true }])})})++describe('agent-operation verbs', () => {+ it('round-trip raw control bytes and the expected owner unchanged through the framer', () => {+ const requests: SessionHostRequest[] = [+ { id: 7, cmd: 'writeDetachedV1', name: 'nt-a', data: '\x1b[A\r\n\u0003' },+ {+ id: 8,+ cmd: 'terminateOwnerV1',+ name: 'nt-a',+ expected: {+ panePid: 1, tty: 'win32-console:1', paneId: 'win32:g:b', command: 'node',+ argv: ['claude'], pids: [2], processBirths: ['b']+ }+ }+ ]+ const framer = new LineFramer()+ expect(framer.push(requests.map(encodeFrame).join(''))).toEqual(requests)+ })++ it('are negotiated by command name, not by a hello feature (an older host answers unknown command)', () => {+ // Features gate PUSH frames an older client would misread; these are plain requests.- expect(SESSION_HOST_FEATURES).toEqual(['geometry', 'shutdown'])++ // (The listed features come from other extensions; these two verbs must never join them.)++ expect(SESSION_HOST_FEATURES).not.toContain('terminateOwnerV1')++ expect(SESSION_HOST_FEATURES).not.toContain('writeDetachedV1')++ expect(SESSION_HOST_FEATURES).toEqual([++ 'geometry', 'shutdown', 'sessionDetails', 'watch-attach', 'captureVisible', 'paneCwd'++ ])+ })+})diff --cc src/session-host/protocol.tsindex 8bfb0f89e,e90d4082c..ad241c322--- a/src/session-host/protocol.ts+++ b/src/session-host/protocol.ts@@@ -98,15 -103,13 +103,21 @@@ export type SessionHostRequest| { id: number; cmd: 'messageOwnerV1'; name: string }| { id: number; cmd: 'messagePasteReadyV1'; name: string }| { id: number; cmd: 'messageEnvelopeV1'; name: string; envelope: string; expected: PaneOwner }+ /** End the proven agent process tree (`expected`, from `messageOwnerV1`) without touching the+ * console root. Result: `TerminateOwnerResult`. Additive like the messaging extension: an older+ * live host answers `unknown command`, which the client reports as unsupported. */+ | { id: number; cmd: 'terminateOwnerV1'; name: string; expected: PaneOwner }+ /** Raw, verbatim keystroke bytes into a session this connection need NOT be attached to — the+ * `tmux send-keys -H` of a released node. No framing, no sanitizing, no Enter. An older host+ * answers `unknown command`; the client then fails closed and never falls back to sendKeys. */+ | { id: number; cmd: 'writeDetachedV1'; name: string; data: string }| { id: number; cmd: 'capture'; name: string; full: boolean }+ /** `captureVisible` feature only: the VISIBLE rows (no history) plus cursor + active buffer — a+ * live link's keyframe. Never sent to a host that did not advertise it. */+ | { id: number; cmd: 'captureVisible'; name: string }+ /** `paneCwd` feature only: the last cwd the pane REPORTED (OSC 7 / 9;9 / 633), never the spawn+ * cwd. */+ | { id: number; cmd: 'paneCwd'; name: string }| {id: numbercmd: 'executeLaunch'@@@ -213,8 -216,14 +224,21 @@@ export interface AttachResultgeometry?: { cols: number; rows: number }}/** Additive, independently negotiated capabilities (see the `hello` request). */- export type SessionHostFeature = 'geometry' | 'shutdown' | 'sessionDetails'- export const SESSION_HOST_FEATURES: readonly SessionHostFeature[] = ['geometry', 'shutdown', 'sessionDetails']-export type SessionHostFeature = 'geometry' | 'shutdown' | 'watch-attach' | 'captureVisible' | 'paneCwd'++export type SessionHostFeature =++ | 'geometry'++ | 'shutdown'++ | 'sessionDetails'++ | 'watch-attach'++ | 'captureVisible'++ | 'paneCwd'+ export const SESSION_HOST_FEATURES: readonly SessionHostFeature[] = [+ 'geometry',+ 'shutdown',++ 'sessionDetails',+ 'watch-attach',+ 'captureVisible',+ 'paneCwd'+ ]/** `result` of a successful `shutdown`: the session names whose process trees were ended. The* host exits right after this reply is flushed. A shutdown that could not confirm every kill@@@ -252,30 -258,19 +276,41 @@@ export interface TerminateOwnerResultexport interface CaptureResult {text: string}+ /** `result` of `captureVisible`. `screen` is one `\n`-terminated line per visible row with SGR (the+ * shape `capture-pane -p -e` prints), '' for a session that never painted; `cursor` is 0-based and+ * viewport-relative; `altScreen` is the emulator's ACTIVE buffer. A missing session is an error. */+ export interface CaptureVisibleResult {+ screen: string+ cursor: { x: number; y: number } | null+ altScreen: boolean+ }+ export interface PaneCwdResult {+ cwd: string | null+ }export interface ListSessionsResult {names: string[]+ /** One row per LIVE generation — present only for a connection that negotiated the+ * `sessionDetails` feature, so an older client keeps reading `{names}` byte-for-byte. A name in+ * `names` with no row here (a generation already retiring) is simply not described; a consumer+ * must never read that absence as "detached" or "no processes". */+ sessions?: SessionHostSessionDetail[]+}++/** What the observability surfaces (session reaper, session-memory panel, dev-server ports) need+ * to know about one host session — the session host's answer to tmux's `list-windows`/`list-panes`+ * formats. All stamps are epoch MILLISECONDS on the host's clock. */+export interface SessionHostSessionDetail {+ name: string+ /** The pty's own child (the pane's shell) — the root of the session's process tree. */+ pid: number+ /** Connections subscribed to this generation's output right now (tmux's `session_attached`). */+ subscribers: number+ /** When the pty last produced OUTPUT — the reaper's idleness clock (tmux's `window_activity`).+ * Starts at `createdMs`; nothing that only LOOKS at the session (attach, capture) moves it. */+ lastOutputMs: number+ createdMs: number+ /** Exact process generation, so a kill planned from this row cannot hit a same-name successor. */+ generation: string}/**