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.

Merge branch 'feat/win-10-live-links' into feat/windows-parity

reviewced67641d7c1
diff --cc docs/windows-session-host.md
index 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.ts
index 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(): Record
sessionHostKillSession: 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.ts
index 1c6269a17,2d985f69a..591fdd760
--- a/src/core/pty-manager.ts
+++ b/src/core/pty-manager.ts
@@@ -215,14 -213,15 +215,19 @@@ import
sessionHostMessageEnvelope,
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 (which
diff --cc src/core/session-host-backend.ts
index 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 './platform
import {
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 sessionHostKillSe
return 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`) but
diff --cc src/core/session-host-client.ts
index 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 SessionHostClient
const 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.ts
index a6ee6676a,a5d1b77a8..e11b710e2
--- a/src/session-host/host.ts
+++ b/src/session-host/host.ts
@@@ -29,10 -29,10 +29,12 @@@ import
type 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.ts
index 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.ts
index 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: number
cmd: 'executeLaunch'
@@@ -213,8 -216,14 +224,21 @@@ export interface AttachResult
geometry?: { 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 TerminateOwnerResult
export 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
}
/**