parasor 0.1.0

package/server/ws/events.d.ts

@@ -0,0 +1,45 @@
+import { type AgentState, type AppState, type GitState, type Notification, type PortInfo, type Worktree, type WsEventMessage } from "@parasor/shared";
+import type { WSContext } from "hono/ws";
+export interface HydrationSources {
+    getState: () => Readonly<AppState>;
+    getAgentStates: () => Record<string, AgentState>;
+    getNotifications: () => Notification[];
+    getPorts: () => Record<string, PortInfo[]>;
+    getGitStates: () => Record<string, Record<string, GitState | null>>;
+    /**
+     * Per-project worktree snapshot. Sync because it reads from a
+     * runtime-maintained `WorktreeCache` -- see `wireRuntime`. Keeping
+     * this synchronous lets `addClient` capture seq + state + worktrees
+     * atomically in one tick, avoiding the broadcast/snapshot race that
+     * would otherwise leak events to a connecting client.
+     */
+    getWorktrees: () => Record<string, Worktree[]>;
+}
+export type ClientCountListener = (count: number) => void;
+export declare class EventBus {
+    private clients;
+    private seq;
+    private lock;
+    private sources;
+    private notifications;
+    private clientCountListeners;
+    setHydrationSources(sources: HydrationSources): void;
+    addNotification(n: Notification): void;
+    getNotifications(): Notification[];
+    getClientCount(): number;
+    onClientCountChanged(listener: ClientCountListener): () => void;
+    addClient(ws: WSContext): Promise<void>;
+    removeClient(ws: WSContext): void;
+    private emitClientCount;
+    broadcast(message: WsEventMessage): void;
+}
+/**
+ * Handle a single client->server frame on `/ws/events`. The browser
+ * cannot issue WS-protocol pings from JS, so we offer an app-layer
+ * ping that detects silent-dead TCP paths (NAT idle timeout, mobile
+ * background freeze) where neither side observes a close. Echoes
+ * `pong` with the same `ts`. Unknown / malformed frames are ignored
+ * -- forward-compat for future client->server messages.
+ */
+export declare function handleEventClientMessage(ws: Pick<WSContext, "send">, raw: unknown): void;
+//# sourceMappingURL=events.d.ts.map

package/server/ws/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/ws/events.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,UAAU,EACf,KAAK,QAAQ,EAGb,KAAK,QAAQ,EAEb,KAAK,YAAY,EACjB,KAAK,QAAQ,EACb,KAAK,QAAQ,EAEb,KAAK,cAAc,EACpB,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAGzC,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,QAAQ,CAAC,QAAQ,CAAC,CAAC;IACnC,cAAc,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACjD,gBAAgB,EAAE,MAAM,YAAY,EAAE,CAAC;IACvC,QAAQ,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC;IAC3C,YAAY,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,GAAG,IAAI,CAAC,CAAC,CAAC;IACpE;;;;;;OAMG;IACH,YAAY,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC;CAChD;AAED,MAAM,MAAM,mBAAmB,GAAG,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;AAM1D,qBAAa,QAAQ;IACnB,OAAO,CAAC,OAAO,CAAwB;IACvC,OAAO,CAAC,GAAG,CAAK;IAChB,OAAO,CAAC,IAAI,CAAsB;IAClC,OAAO,CAAC,OAAO,CAAiC;IAChD,OAAO,CAAC,aAAa,CAAsB;IAC3C,OAAO,CAAC,oBAAoB,CAAkC;IAE9D,mBAAmB,CAAC,OAAO,EAAE,gBAAgB,GAAG,IAAI;IAIpD,eAAe,CAAC,CAAC,EAAE,YAAY,GAAG,IAAI;IAMtC,gBAAgB,IAAI,YAAY,EAAE;IAIlC,cAAc,IAAI,MAAM;IAIxB,oBAAoB,CAAC,QAAQ,EAAE,mBAAmB,GAAG,MAAM,IAAI;IAOzD,SAAS,CAAC,EAAE,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IA8C7C,YAAY,CAAC,EAAE,EAAE,SAAS,GAAG,IAAI;IAKjC,OAAO,CAAC,eAAe;IAOvB,SAAS,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI;CAiBzC;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CACtC,EAAE,EAAE,IAAI,CAAC,SAAS,EAAE,MAAM,CAAC,EAC3B,GAAG,EAAE,OAAO,GACX,IAAI,CAiBN"}

package/server/ws/events.js

@@ -0,0 +1,134 @@
+import { DEFAULT_DROP_SIZE_HARD_MAX_BYTES, DEFAULT_DROP_SIZE_MAX_BYTES, } from "@parasor/shared";
+import { PromiseMutex } from "../lib/promise-mutex.js";
+// Cap retained notifications so a long-running daemon does not grow the
+// hydration payload without bound (every reconnect ships the full list).
+const NOTIFICATION_RETENTION_LIMIT = 200;
+export class EventBus {
+    clients = new Set();
+    seq = 0;
+    lock = new PromiseMutex();
+    sources = null;
+    notifications = [];
+    clientCountListeners = new Set();
+    setHydrationSources(sources) {
+        this.sources = sources;
+    }
+    addNotification(n) {
+        this.notifications.push(n);
+        const overflow = this.notifications.length - NOTIFICATION_RETENTION_LIMIT;
+        if (overflow > 0)
+            this.notifications.splice(0, overflow);
+    }
+    getNotifications() {
+        return this.notifications;
+    }
+    getClientCount() {
+        return this.clients.size;
+    }
+    onClientCountChanged(listener) {
+        this.clientCountListeners.add(listener);
+        return () => {
+            this.clientCountListeners.delete(listener);
+        };
+    }
+    async addClient(ws) {
+        const release = await this.lock.acquire();
+        const snapshotSeq = this.seq;
+        const payload = this.sources
+            ? {
+                seq: snapshotSeq,
+                state: structuredClone(this.sources.getState()),
+                agentStates: this.sources.getAgentStates(),
+                notifications: this.sources.getNotifications(),
+                ports: this.sources.getPorts(),
+                gitStates: this.sources.getGitStates(),
+                worktrees: this.sources.getWorktrees(),
+                hostPlatform: process.platform,
+            }
+            : {
+                seq: snapshotSeq,
+                state: {
+                    version: 1,
+                    projects: [],
+                    projectStates: {},
+                    sessions: [],
+                    sessionRecords: [],
+                    ideCommands: [],
+                    paneCommands: [],
+                    serviceConfig: {
+                        preventIdleSleep: false,
+                        portDetection: "all-interfaces",
+                        dropSizeMaxBytes: DEFAULT_DROP_SIZE_MAX_BYTES,
+                        dropSizeHardMaxBytes: DEFAULT_DROP_SIZE_HARD_MAX_BYTES,
+                    },
+                },
+                agentStates: {},
+                notifications: [],
+                ports: {},
+                gitStates: {},
+                worktrees: {},
+                hostPlatform: process.platform,
+            };
+        this.clients.add(ws);
+        ws.send(JSON.stringify({ type: "app-state-snapshot", payload }));
+        release();
+        this.emitClientCount();
+    }
+    removeClient(ws) {
+        const had = this.clients.delete(ws);
+        if (had)
+            this.emitClientCount();
+    }
+    emitClientCount() {
+        const count = this.clients.size;
+        for (const listener of this.clientCountListeners) {
+            listener(count);
+        }
+    }
+    broadcast(message) {
+        this.seq++;
+        const envelope = { seq: this.seq, message };
+        const data = JSON.stringify(envelope);
+        let dropped = false;
+        for (const client of this.clients) {
+            if (client.readyState === 1) {
+                try {
+                    client.send(data);
+                }
+                catch {
+                    this.clients.delete(client);
+                    dropped = true;
+                }
+            }
+        }
+        if (dropped)
+            this.emitClientCount();
+    }
+}
+/**
+ * Handle a single client->server frame on `/ws/events`. The browser
+ * cannot issue WS-protocol pings from JS, so we offer an app-layer
+ * ping that detects silent-dead TCP paths (NAT idle timeout, mobile
+ * background freeze) where neither side observes a close. Echoes
+ * `pong` with the same `ts`. Unknown / malformed frames are ignored
+ * -- forward-compat for future client->server messages.
+ */
+export function handleEventClientMessage(ws, raw) {
+    if (typeof raw !== "string")
+        return;
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return;
+    }
+    if (parsed === null ||
+        typeof parsed !== "object" ||
+        parsed.type !== "ping" ||
+        !Number.isFinite(parsed.ts)) {
+        return;
+    }
+    ws.send(JSON.stringify({ type: "pong", ts: parsed.ts }));
+}
+//# sourceMappingURL=events.js.map

package/server/ws/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../src/ws/events.ts"],"names":[],"mappings":"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"}

package/server/ws/keepalive.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Minimal shape of the `ws` package WebSocket we rely on. Declared locally so
+ * the server package does not need a direct dependency on `ws` (it arrives
+ * transitively through @hono/node-ws).
+ */
+export interface KeepaliveSocket {
+    readyState: number;
+    readonly OPEN: number;
+    ping(): void;
+    terminate(): void;
+    on(event: "pong", listener: () => void): void;
+    off(event: "pong", listener: () => void): void;
+}
+export interface KeepaliveOptions {
+    pingIntervalMs: number;
+    pongTimeoutMs: number;
+    onTimeout?: () => void;
+}
+/**
+ * Attach ping/pong keepalive to a ws WebSocket. Mobile carriers, corporate
+ * proxies, and Tailscale can silently drop idle TCP connections; without a
+ * keepalive the client thinks the socket is healthy while the server sees
+ * nothing. The interval ping forces a half-open state to surface, and the
+ * pong deadline tears the connection down so the client reconnects.
+ */
+export declare function attachKeepalive(raw: KeepaliveSocket, options: KeepaliveOptions): () => void;
+//# sourceMappingURL=keepalive.d.ts.map

package/server/ws/keepalive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keepalive.d.ts","sourceRoot":"","sources":["../../src/ws/keepalive.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,IAAI,IAAI,IAAI,CAAC;IACb,SAAS,IAAI,IAAI,CAAC;IAClB,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;IAC9C,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;CAChD;AAED,MAAM,WAAW,gBAAgB;IAC/B,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;CACxB;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,GAAG,EAAE,eAAe,EACpB,OAAO,EAAE,gBAAgB,GACxB,MAAM,IAAI,CAmDZ"}

package/server/ws/keepalive.js

@@ -0,0 +1,63 @@
+/**
+ * Attach ping/pong keepalive to a ws WebSocket. Mobile carriers, corporate
+ * proxies, and Tailscale can silently drop idle TCP connections; without a
+ * keepalive the client thinks the socket is healthy while the server sees
+ * nothing. The interval ping forces a half-open state to surface, and the
+ * pong deadline tears the connection down so the client reconnects.
+ */
+export function attachKeepalive(raw, options) {
+    const { pingIntervalMs, pongTimeoutMs, onTimeout } = options;
+    if (pingIntervalMs <= 0)
+        return () => { };
+    let disposed = false;
+    let pongDeadline = null;
+    const clearDeadline = () => {
+        if (pongDeadline !== null) {
+            clearTimeout(pongDeadline);
+            pongDeadline = null;
+        }
+    };
+    const onPong = () => {
+        clearDeadline();
+    };
+    raw.on("pong", onPong);
+    const pingTimer = setInterval(() => {
+        if (disposed)
+            return;
+        if (raw.readyState !== raw.OPEN)
+            return;
+        if (pongDeadline !== null)
+            return;
+        try {
+            raw.ping();
+        }
+        catch {
+            return;
+        }
+        if (pongTimeoutMs <= 0)
+            return;
+        pongDeadline = setTimeout(() => {
+            pongDeadline = null;
+            if (disposed)
+                return;
+            onTimeout?.();
+            try {
+                raw.terminate();
+            }
+            catch {
+                // already closed; nothing to do
+            }
+        }, pongTimeoutMs);
+        pongDeadline.unref?.();
+    }, pingIntervalMs);
+    pingTimer.unref?.();
+    return () => {
+        if (disposed)
+            return;
+        disposed = true;
+        clearInterval(pingTimer);
+        clearDeadline();
+        raw.off("pong", onPong);
+    };
+}
+//# sourceMappingURL=keepalive.js.map

package/server/ws/keepalive.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keepalive.js","sourceRoot":"","sources":["../../src/ws/keepalive.ts"],"names":[],"mappings":"AAoBA;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAC7B,GAAoB,EACpB,OAAyB;IAEzB,MAAM,EAAE,cAAc,EAAE,aAAa,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC;IAC7D,IAAI,cAAc,IAAI,CAAC;QAAE,OAAO,GAAG,EAAE,GAAE,CAAC,CAAC;IAEzC,IAAI,QAAQ,GAAG,KAAK,CAAC;IACrB,IAAI,YAAY,GAAyC,IAAI,CAAC;IAE9D,MAAM,aAAa,GAAG,GAAG,EAAE;QACzB,IAAI,YAAY,KAAK,IAAI,EAAE,CAAC;YAC1B,YAAY,CAAC,YAAY,CAAC,CAAC;YAC3B,YAAY,GAAG,IAAI,CAAC;QACtB,CAAC;IACH,CAAC,CAAC;IAEF,MAAM,MAAM,GAAG,GAAG,EAAE;QAClB,aAAa,EAAE,CAAC;IAClB,CAAC,CAAC;IAEF,GAAG,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAEvB,MAAM,SAAS,GAAG,WAAW,CAAC,GAAG,EAAE;QACjC,IAAI,QAAQ;YAAE,OAAO;QACrB,IAAI,GAAG,CAAC,UAAU,KAAK,GAAG,CAAC,IAAI;YAAE,OAAO;QACxC,IAAI,YAAY,KAAK,IAAI;YAAE,OAAO;QAClC,IAAI,CAAC;YACH,GAAG,CAAC,IAAI,EAAE,CAAC;QACb,CAAC;QAAC,MAAM,CAAC;YACP,OAAO;QACT,CAAC;QACD,IAAI,aAAa,IAAI,CAAC;YAAE,OAAO;QAC/B,YAAY,GAAG,UAAU,CAAC,GAAG,EAAE;YAC7B,YAAY,GAAG,IAAI,CAAC;YACpB,IAAI,QAAQ;gBAAE,OAAO;YACrB,SAAS,EAAE,EAAE,CAAC;YACd,IAAI,CAAC;gBACH,GAAG,CAAC,SAAS,EAAE,CAAC;YAClB,CAAC;YAAC,MAAM,CAAC;gBACP,gCAAgC;YAClC,CAAC;QACH,CAAC,EAAE,aAAa,CAAC,CAAC;QAClB,YAAY,CAAC,KAAK,EAAE,EAAE,CAAC;IACzB,CAAC,EAAE,cAAc,CAAC,CAAC;IACnB,SAAS,CAAC,KAAK,EAAE,EAAE,CAAC;IAEpB,OAAO,GAAG,EAAE;QACV,IAAI,QAAQ;YAAE,OAAO;QACrB,QAAQ,GAAG,IAAI,CAAC;QAChB,aAAa,CAAC,SAAS,CAAC,CAAC;QACzB,aAAa,EAAE,CAAC;QAChB,GAAG,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1B,CAAC,CAAC;AACJ,CAAC"}

package/server/ws/terminal-attach.d.ts

@@ -0,0 +1,13 @@
+import { type WsTerminalClientMessage } from "@parasor/shared";
+import type { RelayContext } from "./terminal.js";
+type WsTerminalInitMessage = Extract<WsTerminalClientMessage, {
+    type: "init";
+}>;
+/**
+ * First-frame attach: choose the binary or legacy path from declared
+ * capabilities. The caller ({@link handleInitFrame}) has already validated that
+ * `msg` is the mandatory `init` and recorded the handshake.
+ */
+export declare function attachClient(ctx: RelayContext, msg: WsTerminalInitMessage): Promise<void>;
+export {};
+//# sourceMappingURL=terminal-attach.d.ts.map

package/server/ws/terminal-attach.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal-attach.d.ts","sourceRoot":"","sources":["../../src/ws/terminal-attach.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,uBAAuB,EAE7B,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EAAE,YAAY,EAAc,MAAM,eAAe,CAAC;AAG9D,KAAK,qBAAqB,GAAG,OAAO,CAAC,uBAAuB,EAAE;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAmFhF;;;;GAIG;AACH,wBAAsB,YAAY,CAChC,GAAG,EAAE,YAAY,EACjB,GAAG,EAAE,qBAAqB,GACzB,OAAO,CAAC,IAAI,CAAC,CAOf"}

package/server/ws/terminal-attach.js

@@ -0,0 +1,233 @@
+import { encodeExitFrame, encodeOutputFrame, } from "@parasor/shared";
+import { applyServerBackpressure } from "./terminal-flow.js";
+const OUTPUT_TRACE_SAMPLE_CHUNKS = 100;
+const OUTPUT_TRACE_SAMPLE_BYTES = 64 * 1024;
+const OUTPUT_TRACE_SAMPLE_MS = 1000;
+function sendJson(ws, msg) {
+    if (ws.readyState === 1)
+        ws.send(JSON.stringify(msg));
+}
+class OutputTraceSampler {
+    ctx;
+    wire;
+    chunks = 0;
+    bytes = 0;
+    firstAt = 0;
+    firstGeneration = null;
+    lastGeneration = null;
+    firstSeq = null;
+    lastSeq = null;
+    emittedFirst = false;
+    constructor(ctx, wire) {
+        this.ctx = ctx;
+        this.wire = wire;
+    }
+    record(chunk) {
+        if (!this.ctx.traceRecorder?.isEnabled())
+            return;
+        const now = performance.now();
+        if (this.chunks === 0) {
+            this.firstAt = now;
+            this.firstGeneration = chunk.generation ?? null;
+            this.firstSeq = chunk.seq === undefined ? null : String(chunk.seq);
+        }
+        this.chunks += 1;
+        this.bytes += chunk.byteLength;
+        this.lastGeneration = chunk.generation ?? this.lastGeneration;
+        this.lastSeq = chunk.seq === undefined ? this.lastSeq : String(chunk.seq);
+        if (!this.emittedFirst ||
+            this.chunks >= OUTPUT_TRACE_SAMPLE_CHUNKS ||
+            this.bytes >= OUTPUT_TRACE_SAMPLE_BYTES ||
+            now - this.firstAt >= OUTPUT_TRACE_SAMPLE_MS) {
+            this.flush(now);
+        }
+    }
+    flush(now) {
+        if (this.chunks === 0)
+            return;
+        this.ctx.traceRecorder?.record("ws-output", {
+            wire: this.wire,
+            chunks: this.chunks,
+            byteLength: this.bytes,
+            windowMs: Math.round((now - this.firstAt) * 10) / 10,
+            firstGeneration: this.firstGeneration,
+            lastGeneration: this.lastGeneration,
+            firstSeq: this.firstSeq,
+            lastSeq: this.lastSeq,
+        }, { sessionId: this.ctx.sessionId, clientId: this.ctx.clientId });
+        this.emittedFirst = true;
+        this.chunks = 0;
+        this.bytes = 0;
+        this.firstAt = 0;
+        this.firstGeneration = null;
+        this.lastGeneration = null;
+        this.firstSeq = null;
+        this.lastSeq = null;
+    }
+}
+/**
+ * First-frame attach: choose the binary or legacy path from declared
+ * capabilities. The caller ({@link handleInitFrame}) has already validated that
+ * `msg` is the mandatory `init` and recorded the handshake.
+ */
+export async function attachClient(ctx, msg) {
+    const declared = msg.capabilities;
+    if (declared?.binary) {
+        await attachBinaryClient(ctx, msg, declared);
+        return;
+    }
+    await attachLegacyClient(ctx, msg);
+}
+/**
+ * Binary capability path: atomically attach (replay decision + chunk listener
+ * registered under the host mutex), ack, then flush full/delta replay. Honors
+ * the attach fencing mid-await close race by releasing the freshly minted entry.
+ */
+async function attachBinaryClient(ctx, msg, declared) {
+    const { ws, state, sessionId, clientId, ptyManager, traceRecorder } = ctx;
+    const outputTrace = new OutputTraceSampler(ctx, "binary");
+    // -- the host method holds
+    // its own mutex while computing the replay decision and registering
+    // the chunk listener, so init-ack / replay / live OUTPUT cannot
+    // interleave on the wire.
+    traceRecorder?.record("pty-attach-start", { mode: "binary", cols: msg.cols, rows: msg.rows }, { sessionId, clientId });
+    const attachStart = performance.now();
+    const result = await ptyManager.attachClient(sessionId, clientId, msg.cols, msg.rows, {
+        binary: declared.binary,
+        chunkedReplay: declared.chunkedReplay,
+        lastSeen: declared.lastSeen,
+    }, {
+        onChunk: (generation, seq, data) => {
+            outputTrace.record({ byteLength: data.byteLength, generation, seq });
+            if (ws.readyState === 1) {
+                ws.send(encodeOutputFrame(generation, seq, data));
+                applyServerBackpressure(ws, state, sessionId, clientId, ptyManager);
+            }
+        },
+        onExit: (exitCode) => {
+            if (ws.readyState === 1) {
+                ws.send(encodeExitFrame(exitCode));
+            }
+        },
+    });
+    if (!result.ok) {
+        traceRecorder?.record("pty-attach-failed", {
+            mode: "binary",
+            durationMs: Math.round((performance.now() - attachStart) * 10) / 10,
+            reason: "unavailable",
+        }, { sessionId, clientId });
+        ws.close(1008, "Session unavailable");
+        traceRecorder?.record("ws-close", { code: 1008, reason: "Session unavailable" }, { sessionId, clientId });
+        return;
+    }
+    state.attachToken = result.attachToken;
+    traceRecorder?.record("pty-attach-complete", {
+        mode: "binary",
+        durationMs: Math.round((performance.now() - attachStart) * 10) / 10,
+        replay: result.replay,
+        binary: result.capabilities.binary,
+        chunkedReplay: result.capabilities.chunkedReplay,
+        ...(result.replayDiagnostics
+            ? { replayDiagnostics: result.replayDiagnostics }
+            : {}),
+    }, { sessionId, clientId });
+    // Attach fencing: WS may have closed while attachClient() was awaiting.
+    // The host has already minted a fresh entry under our token; if we
+    // skip the cleanup detach (no init-ack will fire), the entry leaks
+    // forever. Release it now using the just-captured token so a future
+    // reconnect with the same clientId is not blocked by ghost state.
+    if (ws.readyState !== 1) {
+        ptyManager.detachClient(sessionId, clientId, result.attachToken);
+        traceRecorder?.record("pty-attach-abandoned", {
+            mode: "binary",
+            durationMs: Math.round((performance.now() - attachStart) * 10) / 10,
+            attachToken: result.attachToken,
+        }, { sessionId, clientId });
+        return;
+    }
+    sendJson(ws, {
+        type: "init-ack",
+        capabilities: result.capabilities,
+        serverState: result.serverState,
+        replay: result.replay,
+    });
+    traceRecorder?.record("ws-init-ack", {
+        replay: result.replay,
+        generation: result.serverState.generation,
+        binary: result.capabilities.binary,
+        chunkedReplay: result.capabilities.chunkedReplay,
+    }, { sessionId, clientId });
+    if (result.replay === "full" && result.fullReplay) {
+        const fullReplay = result.fullReplay;
+        traceRecorder?.recordLazy("ws-replay", () => ({
+            replay: "full",
+            dataLength: fullReplay.length,
+            ...(result.replayDiagnostics
+                ? { replayDiagnostics: result.replayDiagnostics }
+                : {}),
+        }), { sessionId, clientId });
+        sendJson(ws, { type: "replay", data: fullReplay });
+    }
+    else if (result.replay === "delta" && result.chunks) {
+        for (const chunk of result.chunks) {
+            if (ws.readyState !== 1)
+                break;
+            traceRecorder?.recordLazy("ws-replay", () => ({
+                replay: "delta",
+                byteLength: chunk.data.byteLength,
+                generation: chunk.generation,
+                seq: String(chunk.seq),
+            }), { sessionId, clientId });
+            ws.send(encodeOutputFrame(chunk.generation, chunk.seq, chunk.data));
+        }
+    }
+    // If the negotiated path turned out to be legacy (server doesn't
+    // support binary, e.g. RemotePtyHost), `binaryAttached` stays
+    // false so subsequent JSON input/resize/refresh keeps working.
+    state.binaryAttached = result.capabilities.binary;
+}
+/**
+ * Legacy path -- old client without capabilities. String OUTPUT is relayed
+ * verbatim via the host's `initClient` listener. Honors the same attach fencing
+ * mid-await close race as the binary path.
+ */
+async function attachLegacyClient(ctx, msg) {
+    const { ws, state, sessionId, clientId, ptyManager, traceRecorder } = ctx;
+    const outputTrace = new OutputTraceSampler(ctx, "legacy");
+    traceRecorder?.record("pty-attach-start", { mode: "legacy", cols: msg.cols, rows: msg.rows }, { sessionId, clientId });
+    const legacyAttachStart = performance.now();
+    const initResult = await ptyManager.initClient(sessionId, clientId, msg.cols, msg.rows, (data) => {
+        outputTrace.record({ byteLength: Buffer.byteLength(data, "utf8") });
+        if (ws.readyState === 1) {
+            ws.send(data);
+            applyServerBackpressure(ws, state, sessionId, clientId, ptyManager);
+        }
+    });
+    if (!initResult.ok) {
+        traceRecorder?.record("pty-attach-failed", {
+            mode: "legacy",
+            durationMs: Math.round((performance.now() - legacyAttachStart) * 10) / 10,
+            reason: "unavailable",
+        }, { sessionId, clientId });
+        ws.close(1008, "Session unavailable");
+        traceRecorder?.record("ws-close", { code: 1008, reason: "Session unavailable" }, { sessionId, clientId });
+        return;
+    }
+    state.attachToken = initResult.attachToken;
+    traceRecorder?.record("pty-attach-complete", {
+        mode: "legacy",
+        durationMs: Math.round((performance.now() - legacyAttachStart) * 10) / 10,
+    }, { sessionId, clientId });
+    // Attach fencing: same race as the binary path -- release the freshly-
+    // minted entry if the WS closed mid-await so we do not leak a ghost
+    // listener under this clientId.
+    if (ws.readyState !== 1) {
+        ptyManager.detachClient(sessionId, clientId, initResult.attachToken);
+        traceRecorder?.record("pty-attach-abandoned", {
+            mode: "legacy",
+            durationMs: Math.round((performance.now() - legacyAttachStart) * 10) / 10,
+            attachToken: initResult.attachToken,
+        }, { sessionId, clientId });
+    }
+}
+//# sourceMappingURL=terminal-attach.js.map

package/server/ws/terminal-attach.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal-attach.js","sourceRoot":"","sources":["../../src/ws/terminal-attach.ts"],"names":[],"mappings":"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"}

package/server/ws/terminal-flow.d.ts

@@ -0,0 +1,17 @@
+import type { PtyHost } from "../pty/host.js";
+import type { TerminalRelayState, TerminalWs } from "./terminal.js";
+/**
+ * Reconcile the host's single per-client `flowPaused` bit against the relay's
+ * two independent pause reasons. Pause when either the client or the server
+ * wants it; resume only when both are clear. Idempotent -- the host no-ops a
+ * repeated pause/resume -- so it is safe to call after any reason flips.
+ */
+export declare function syncPtyFlow(state: TerminalRelayState, sessionId: string, clientId: string, ptyManager: PtyHost): void;
+/**
+ * Apply send backpressure after relaying a chunk to {@link ws}. Pauses the PTY
+ * when the socket's send buffer is congested and starts a drain poll that
+ * resumes it once the buffer empties; closes 1013 if the buffer blows past the
+ * hard ceiling. No-op when the transport does not expose `bufferedAmount`.
+ */
+export declare function applyServerBackpressure(ws: TerminalWs, state: TerminalRelayState, sessionId: string, clientId: string, ptyManager: PtyHost): void;
+//# sourceMappingURL=terminal-flow.d.ts.map

package/server/ws/terminal-flow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal-flow.d.ts","sourceRoot":"","sources":["../../src/ws/terminal-flow.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,KAAK,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAgBpE;;;;;GAKG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,kBAAkB,EACzB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,OAAO,GAClB,IAAI,CAMN;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,EAAE,EAAE,UAAU,EACd,KAAK,EAAE,kBAAkB,EACzB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,OAAO,GAClB,IAAI,CA6BN"}

package/server/ws/terminal-flow.js

@@ -0,0 +1,64 @@
+/*
+ * Server-side send backpressure for the terminal socket. A client that stops
+ * draining its socket (mobile background, slow link, frozen tab the keepalive
+ * has not yet reaped) would otherwise grow the server's per-socket send buffer
+ * without bound. When `bufferedAmount` reaches the high-water mark we pause the
+ * PTY via the existing flow-control path; a poll resumes it once the buffer
+ * drains to the low-water mark. The hard ceiling is the backstop: a socket that
+ * blows past it is closed (1013) and the client reconnects + replays.
+ */
+const BACKPRESSURE_HIGH_WATER = 1024 * 1024; // 1 MiB -- pause the PTY
+const BACKPRESSURE_LOW_WATER = 256 * 1024; // 256 KiB -- resume the PTY
+const BACKPRESSURE_HARD_LIMIT = 8 * 1024 * 1024; // 8 MiB -- give up, close 1013
+const BACKPRESSURE_DRAIN_POLL_MS = 100;
+/**
+ * Reconcile the host's single per-client `flowPaused` bit against the relay's
+ * two independent pause reasons. Pause when either the client or the server
+ * wants it; resume only when both are clear. Idempotent -- the host no-ops a
+ * repeated pause/resume -- so it is safe to call after any reason flips.
+ */
+export function syncPtyFlow(state, sessionId, clientId, ptyManager) {
+    if (state.clientPaused || state.serverPaused) {
+        ptyManager.pauseOutput(sessionId, clientId);
+    }
+    else {
+        ptyManager.resumeOutput(sessionId, clientId);
+    }
+}
+/**
+ * Apply send backpressure after relaying a chunk to {@link ws}. Pauses the PTY
+ * when the socket's send buffer is congested and starts a drain poll that
+ * resumes it once the buffer empties; closes 1013 if the buffer blows past the
+ * hard ceiling. No-op when the transport does not expose `bufferedAmount`.
+ */
+export function applyServerBackpressure(ws, state, sessionId, clientId, ptyManager) {
+    const buffered = ws.raw?.bufferedAmount ?? 0;
+    if (buffered > BACKPRESSURE_HARD_LIMIT) {
+        ws.close(1013, "backpressure");
+        return;
+    }
+    if (buffered < BACKPRESSURE_HIGH_WATER)
+        return;
+    if (state.serverPaused)
+        return;
+    state.serverPaused = true;
+    syncPtyFlow(state, sessionId, clientId, ptyManager);
+    const timer = setInterval(() => {
+        const depth = ws.raw?.bufferedAmount ?? 0;
+        if (ws.readyState !== 1 || depth <= BACKPRESSURE_LOW_WATER) {
+            clearInterval(timer);
+            state.drainTimer = undefined;
+            if (state.serverPaused) {
+                state.serverPaused = false;
+                // Honor a still-active client-driven pause: resume only if the client
+                // is not itself paused (syncPtyFlow ANDs the two reasons).
+                if (ws.readyState === 1) {
+                    syncPtyFlow(state, sessionId, clientId, ptyManager);
+                }
+            }
+        }
+    }, BACKPRESSURE_DRAIN_POLL_MS);
+    timer.unref?.();
+    state.drainTimer = timer;
+}
+//# sourceMappingURL=terminal-flow.js.map

package/server/ws/terminal-flow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal-flow.js","sourceRoot":"","sources":["../../src/ws/terminal-flow.ts"],"names":[],"mappings":"AAGA;;;;;;;;GAQG;AACH,MAAM,uBAAuB,GAAG,IAAI,GAAG,IAAI,CAAC,CAAC,yBAAyB;AACtE,MAAM,sBAAsB,GAAG,GAAG,GAAG,IAAI,CAAC,CAAC,4BAA4B;AACvE,MAAM,uBAAuB,GAAG,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC,CAAC,+BAA+B;AAChF,MAAM,0BAA0B,GAAG,GAAG,CAAC;AAEvC;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CACzB,KAAyB,EACzB,SAAiB,EACjB,QAAgB,EAChB,UAAmB;IAEnB,IAAI,KAAK,CAAC,YAAY,IAAI,KAAK,CAAC,YAAY,EAAE,CAAC;QAC7C,UAAU,CAAC,WAAW,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;IAC9C,CAAC;SAAM,CAAC;QACN,UAAU,CAAC,YAAY,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;IAC/C,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CACrC,EAAc,EACd,KAAyB,EACzB,SAAiB,EACjB,QAAgB,EAChB,UAAmB;IAEnB,MAAM,QAAQ,GAAG,EAAE,CAAC,GAAG,EAAE,cAAc,IAAI,CAAC,CAAC;IAC7C,IAAI,QAAQ,GAAG,uBAAuB,EAAE,CAAC;QACvC,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,cAAc,CAAC,CAAC;QAC/B,OAAO;IACT,CAAC;IACD,IAAI,QAAQ,GAAG,uBAAuB;QAAE,OAAO;IAE/C,IAAI,KAAK,CAAC,YAAY;QAAE,OAAO;IAC/B,KAAK,CAAC,YAAY,GAAG,IAAI,CAAC;IAC1B,WAAW,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,UAAU,CAAC,CAAC;IAEpD,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,EAAE;QAC7B,MAAM,KAAK,GAAG,EAAE,CAAC,GAAG,EAAE,cAAc,IAAI,CAAC,CAAC;QAC1C,IAAI,EAAE,CAAC,UAAU,KAAK,CAAC,IAAI,KAAK,IAAI,sBAAsB,EAAE,CAAC;YAC3D,aAAa,CAAC,KAAK,CAAC,CAAC;YACrB,KAAK,CAAC,UAAU,GAAG,SAAS,CAAC;YAC7B,IAAI,KAAK,CAAC,YAAY,EAAE,CAAC;gBACvB,KAAK,CAAC,YAAY,GAAG,KAAK,CAAC;gBAC3B,sEAAsE;gBACtE,2DAA2D;gBAC3D,IAAI,EAAE,CAAC,UAAU,KAAK,CAAC,EAAE,CAAC;oBACxB,WAAW,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,UAAU,CAAC,CAAC;gBACtD,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC,EAAE,0BAA0B,CAAC,CAAC;IAC/B,KAAK,CAAC,KAAK,EAAE,EAAE,CAAC;IAChB,KAAK,CAAC,UAAU,GAAG,KAAK,CAAC;AAC3B,CAAC"}