@getpaseo/server 0.1.96 → 0.1.97-beta.1

package/dist/server/terminal/terminal-manager-factory.js

@@ -1,5 +1,5 @@
 import { createWorkerTerminalManager } from "./worker-terminal-manager.js";
-export function createConfiguredTerminalManager() {
-    return createWorkerTerminalManager();
+export function createConfiguredTerminalManager(options = {}) {
+    return createWorkerTerminalManager(options);
 }
 //# sourceMappingURL=terminal-manager-factory.js.map

package/dist/server/terminal/terminal-manager.d.ts

@@ -1,34 +1,60 @@
 import { type TerminalSession, type TerminalStateSnapshot, type TerminalStateSnapshotOptions } from "./terminal.js";
 import { type CaptureTerminalLinesResult } from "./terminal-capture.js";
+import type { TerminalActivity, TerminalActivityState } from "@getpaseo/protocol/terminal-activity";
 export interface TerminalListItem {
     id: string;
     name: string;
     cwd: string;
+    workspaceId: string;
     title?: string;
+    activity: TerminalActivity | null;
 }
 export interface TerminalsChangedEvent {
     cwd: string;
     terminals: TerminalListItem[];
 }
 export type TerminalsChangedListener = (input: TerminalsChangedEvent) => void;
+export interface TerminalActivityTransitionEvent {
+    terminalId: string;
+    name: string;
+    cwd: string;
+    workspaceId: string;
+    activity: TerminalActivity | null;
+    previous: TerminalActivity | null;
+}
+export type TerminalActivityListener = (event: TerminalActivityTransitionEvent) => void;
+export interface TerminalWorkspaceContributionChangedEvent {
+    terminalId: string;
+    cwd: string;
+    workspaceId: string;
+}
+export type TerminalWorkspaceContributionChangedListener = (event: TerminalWorkspaceContributionChangedEvent) => void;
 export interface TerminalManager {
-    getTerminals(cwd: string): Promise<TerminalSession[]>;
+    getTerminals(cwd: string, options?: {
+        workspaceId?: string;
+    }): Promise<TerminalSession[]>;
     createTerminal(options: {
         id?: string;
         cwd: string;
+        workspaceId: string;
         name?: string;
         title?: string;
         env?: Record<string, string>;
         command?: string;
         args?: string[];
+        activityToken?: string;
+        activityUrl?: string | null;
     }): Promise<TerminalSession>;
     registerCwdEnv(options: {
         cwd: string;
         env: Record<string, string>;
     }): void;
+    validateTerminalActivityToken(terminalId: string, token: string): "valid" | "unknown" | "invalid";
     getTerminal(id: string): TerminalSession | undefined;
     getTerminalState(id: string, options?: TerminalStateSnapshotOptions): Promise<TerminalStateSnapshot | null>;
     setTerminalTitle(id: string, title: string): boolean;
+    setTerminalActivity(id: string, state: TerminalActivityState): Promise<boolean>;
+    clearTerminalAttention(id: string): Promise<boolean>;
     killTerminal(id: string): void;
     killTerminalAndWait(id: string, options?: {
         gracefulTimeoutMs?: number;
@@ -42,6 +68,11 @@ export interface TerminalManager {
     listDirectories(): string[];
     killAll(): void;
     subscribeTerminalsChanged(listener: TerminalsChangedListener): () => void;
+    subscribeTerminalActivity(listener: TerminalActivityListener): () => void;
+    subscribeTerminalWorkspaceContributionChanged(listener: TerminalWorkspaceContributionChangedListener): () => void;
+}
+export interface TerminalManagerOptions {
+    getTerminalActivityUrl?: () => string | null;
 }
-export declare function createTerminalManager(): TerminalManager;
+export declare function createTerminalManager(managerOptions?: TerminalManagerOptions): TerminalManager;
 //# sourceMappingURL=terminal-manager.d.ts.map

package/dist/server/terminal/terminal-manager.js

@@ -1,19 +1,23 @@
 import { createTerminal, } from "./terminal.js";
 import { captureTerminalLines } from "./terminal-capture.js";
-import { resolve, sep, win32, posix } from "node:path";
-import { isSameOrDescendantPath } from "../server/path-utils.js";
-export function createTerminalManager() {
+import { randomBytes, randomUUID } from "node:crypto";
+import { resolve, sep } from "node:path";
+import { assertAbsolutePath, isSameOrDescendantPath } from "../server/path-utils.js";
+import { deriveTerminalActivityStatusBucket } from "@getpaseo/protocol/terminal-activity";
+function createActivityToken() {
+    return randomBytes(32).toString("base64url");
+}
+export function createTerminalManager(managerOptions = {}) {
     const terminalsByCwd = new Map();
     const terminalsById = new Map();
     const terminalExitUnsubscribeById = new Map();
     const terminalTitleUnsubscribeById = new Map();
+    const terminalActivityUnsubscribeById = new Map();
+    const terminalActivityTokenById = new Map();
     const terminalsChangedListeners = new Set();
+    const terminalActivityListeners = new Set();
+    const terminalWorkspaceContributionChangedListeners = new Set();
     const defaultEnvByRootCwd = new Map();
-    function assertAbsolutePath(cwd) {
-        if (!posix.isAbsolute(cwd) && !win32.isAbsolute(cwd)) {
-            throw new Error("cwd must be absolute path");
-        }
-    }
     function removeSessionById(id, options) {
         const session = terminalsById.get(id);
         if (!session) {
@@ -29,7 +33,13 @@ export function createTerminalManager() {
             unsubscribeTitle();
             terminalTitleUnsubscribeById.delete(id);
         }
+        const unsubscribeActivity = terminalActivityUnsubscribeById.get(id);
+        if (unsubscribeActivity) {
+            unsubscribeActivity();
+            terminalActivityUnsubscribeById.delete(id);
+        }
         terminalsById.delete(id);
+        terminalActivityTokenById.delete(id);
         const terminals = terminalsByCwd.get(session.cwd);
         if (terminals) {
             const index = terminals.findIndex((terminal) => terminal.id === id);
@@ -43,6 +53,15 @@ export function createTerminalManager() {
         if (options.kill) {
             session.kill();
         }
+        const previousActivity = session.getActivity();
+        const previousBucket = deriveTerminalActivityStatusBucket(previousActivity);
+        if (previousBucket !== null) {
+            emitTerminalWorkspaceContributionChanged({
+                terminalId: session.id,
+                cwd: session.cwd,
+                workspaceId: session.workspaceId,
+            });
+        }
         emitTerminalsChanged({ cwd: session.cwd });
     }
     function resolveDefaultEnvForCwd(cwd) {
@@ -67,8 +86,22 @@ export function createTerminalManager() {
         const unsubscribeTitle = session.onTitleChange(() => {
             emitTerminalsChanged({ cwd: session.cwd });
         });
+        const unsubscribeActivity = session.onActivityChange((transition) => {
+            emitTerminalActivityTransition({ session, transition });
+            emitTerminalsChanged({ cwd: session.cwd });
+            const previousBucket = deriveTerminalActivityStatusBucket(transition.previous);
+            const nextBucket = deriveTerminalActivityStatusBucket(transition.activity);
+            if (previousBucket !== nextBucket) {
+                emitTerminalWorkspaceContributionChanged({
+                    terminalId: session.id,
+                    cwd: session.cwd,
+                    workspaceId: session.workspaceId,
+                });
+            }
+        });
         terminalExitUnsubscribeById.set(session.id, unsubscribeExit);
         terminalTitleUnsubscribeById.set(session.id, unsubscribeTitle);
+        terminalActivityUnsubscribeById.set(session.id, unsubscribeActivity);
         return session;
     }
     function toTerminalListItem(input) {
@@ -76,7 +109,9 @@ export function createTerminalManager() {
             id: input.session.id,
             name: input.session.name,
             cwd: input.session.cwd,
+            workspaceId: input.session.workspaceId,
             title: input.session.getTitle(),
+            activity: input.session.getActivity(),
         };
     }
     function emitTerminalsChanged(input) {
@@ -97,8 +132,39 @@ export function createTerminalManager() {
             }
         }
     }
+    function emitTerminalActivityTransition(input) {
+        if (terminalActivityListeners.size === 0) {
+            return;
+        }
+        const event = {
+            terminalId: input.session.id,
+            name: input.session.name,
+            cwd: input.session.cwd,
+            workspaceId: input.session.workspaceId,
+            activity: input.transition.activity,
+            previous: input.transition.previous,
+        };
+        for (const listener of terminalActivityListeners) {
+            try {
+                listener(event);
+            }
+            catch {
+                // no-op
+            }
+        }
+    }
+    function emitTerminalWorkspaceContributionChanged(event) {
+        for (const listener of terminalWorkspaceContributionChangedListeners) {
+            try {
+                listener(event);
+            }
+            catch {
+                // no-op
+            }
+        }
+    }
     return {
-        async getTerminals(cwd) {
+        async getTerminals(cwd, options) {
             assertAbsolutePath(cwd);
             // Terminals are bucketed by exact cwd, but an agent can open a terminal in
             // a subdirectory of the workspace. A query for the workspace root must
@@ -109,6 +175,12 @@ export function createTerminalManager() {
                     sessions.push(...bucketSessions);
                 }
             }
+            // When the query carries a workspaceId, two workspaces sharing a cwd must
+            // not see each other's terminals. A missing owner is not workspace
+            // membership; unscoped callers can still list those legacy terminals.
+            if (options?.workspaceId !== undefined) {
+                return sessions.filter((session) => session.workspaceId === options.workspaceId);
+            }
             return sessions;
         },
         async createTerminal(options) {
@@ -117,15 +189,35 @@ export function createTerminalManager() {
             const defaultName = `Terminal ${terminals.length + 1}`;
             const inheritedEnv = resolveDefaultEnvForCwd(options.cwd);
             const mergedEnv = inheritedEnv || options.env ? { ...inheritedEnv, ...options.env } : undefined;
-            const session = registerSession(await createTerminal({
-                ...(options.id ? { id: options.id } : {}),
-                cwd: options.cwd,
-                name: options.name ?? defaultName,
-                ...(options.title ? { title: options.title } : {}),
-                ...(options.command ? { command: options.command } : {}),
-                ...(options.args ? { args: options.args } : {}),
-                ...(mergedEnv ? { env: mergedEnv } : {}),
-            }));
+            const terminalId = options.id ?? randomUUID();
+            const activityToken = options.activityToken ?? createActivityToken();
+            const terminalActivityUrl = options.activityUrl === undefined
+                ? (managerOptions.getTerminalActivityUrl?.() ?? null)
+                : options.activityUrl;
+            const activityEnv = {
+                PASEO_TERMINAL_ID: terminalId,
+                PASEO_ACTIVITY_TOKEN: activityToken,
+                ...(terminalActivityUrl ? { PASEO_TERMINAL_ACTIVITY_URL: terminalActivityUrl } : {}),
+            };
+            terminalActivityTokenById.set(terminalId, activityToken);
+            let session;
+            try {
+                session = registerSession(await createTerminal({
+                    id: terminalId,
+                    cwd: options.cwd,
+                    workspaceId: options.workspaceId,
+                    name: options.name ?? defaultName,
+                    ...(options.title ? { title: options.title } : {}),
+                    ...(options.command ? { command: options.command } : {}),
+                    ...(options.args ? { args: options.args } : {}),
+                    ...(mergedEnv ? { env: mergedEnv } : {}),
+                    activityEnv,
+                }));
+            }
+            catch (error) {
+                terminalActivityTokenById.delete(terminalId);
+                throw error;
+            }
             terminals.push(session);
             terminalsByCwd.set(options.cwd, terminals);
             emitTerminalsChanged({ cwd: options.cwd });
@@ -135,6 +227,13 @@ export function createTerminalManager() {
             assertAbsolutePath(options.cwd);
             defaultEnvByRootCwd.set(resolve(options.cwd), { ...options.env });
         },
+        validateTerminalActivityToken(terminalId, token) {
+            const expected = terminalActivityTokenById.get(terminalId);
+            if (!expected) {
+                return "unknown";
+            }
+            return expected === token ? "valid" : "invalid";
+        },
         getTerminal(id) {
             return terminalsById.get(id);
         },
@@ -149,6 +248,21 @@ export function createTerminalManager() {
             session.setTitle(title);
             return true;
         },
+        async setTerminalActivity(id, state) {
+            const session = terminalsById.get(id);
+            if (!session) {
+                return false;
+            }
+            session.setActivity(state);
+            return true;
+        },
+        async clearTerminalAttention(id) {
+            const session = terminalsById.get(id);
+            if (!session) {
+                return false;
+            }
+            return session.clearActivityAttention();
+        },
         killTerminal(id) {
             removeSessionById(id, { kill: true });
         },
@@ -188,6 +302,18 @@ export function createTerminalManager() {
                 terminalsChangedListeners.delete(listener);
             };
         },
+        subscribeTerminalActivity(listener) {
+            terminalActivityListeners.add(listener);
+            return () => {
+                terminalActivityListeners.delete(listener);
+            };
+        },
+        subscribeTerminalWorkspaceContributionChanged(listener) {
+            terminalWorkspaceContributionChangedListeners.add(listener);
+            return () => {
+                terminalWorkspaceContributionChangedListeners.delete(listener);
+            };
+        },
     };
 }
 //# sourceMappingURL=terminal-manager.js.map

package/dist/server/terminal/terminal-output-coalescer.d.ts

@@ -10,19 +10,23 @@ export interface TerminalOutputCoalescerFlush {
 export interface TerminalOutputCoalescerOptions {
     timers: TerminalOutputCoalescerTimers;
     flushDelayMs?: number;
+    now?: () => number;
     onFlush: (payload: TerminalOutputCoalescerFlush) => void;
 }
 export declare class TerminalOutputCoalescer {
     private readonly timers;
     private readonly flushDelayMs;
+    private readonly now;
     private readonly onFlush;
     private chunks;
     private bytes;
     private chars;
     private flushTimer;
+    private lastFlushAt;
     constructor(options: TerminalOutputCoalescerOptions);
     handle(data: string): void;
     flush(): void;
+    markFlushed(): void;
     dispose(): void;
     private clearTimer;
     private clearPending;

package/dist/server/terminal/terminal-output-coalescer.js

@@ -5,8 +5,10 @@ export class TerminalOutputCoalescer {
         this.bytes = 0;
         this.chars = 0;
         this.flushTimer = null;
+        this.lastFlushAt = null;
         this.timers = options.timers;
         this.flushDelayMs = options.flushDelayMs ?? DEFAULT_FLUSH_DELAY_MS;
+        this.now = options.now ?? Date.now;
         this.onFlush = options.onFlush;
     }
     handle(data) {
@@ -17,7 +19,15 @@ export class TerminalOutputCoalescer {
         this.chunks.push(chunk);
         this.bytes += chunk.byteLength;
         this.chars += data.length;
+        // Leading edge: if nothing is pending and no flush happened within the last
+        // flushDelayMs, flush immediately so interactive echo isn't delayed a full
+        // window. Otherwise accumulate and let the trailing timer drain the burst.
         if (!this.flushTimer) {
+            const elapsed = this.lastFlushAt === null ? Number.POSITIVE_INFINITY : this.now() - this.lastFlushAt;
+            if (elapsed >= this.flushDelayMs) {
+                this.flush();
+                return;
+            }
             this.flushTimer = this.timers.setTimeout(() => {
                 this.flushTimer = null;
                 this.flush();
@@ -33,8 +43,16 @@ export class TerminalOutputCoalescer {
         const bytes = this.bytes;
         const chars = this.chars;
         this.clearPending();
+        this.lastFlushAt = this.now();
         this.onFlush({ payload, bytes, chars });
     }
+    // Record that a frame was emitted out-of-band on this stream (e.g. a snapshot
+    // frame sent directly, bypassing the coalescer). This keeps the next handled
+    // chunk on the trailing path instead of leading-edge flushing it back-to-back
+    // with that frame, preserving the small gap consumers rely on after a snapshot.
+    markFlushed() {
+        this.lastFlushAt = this.now();
+    }
     dispose() {
         this.clearTimer();
         this.clearPending();

package/dist/server/terminal/terminal-restore.d.ts

@@ -1,6 +1,7 @@
 import type { SubscribeTerminalRequest } from "@getpaseo/protocol/messages";
 import type { TerminalStateSnapshot, TerminalStateSnapshotOptions } from "./terminal.js";
 export declare const MAX_TERMINAL_OUTPUT_FRAME_BYTES: number;
+export declare const MAX_CLIENT_BUFFERED_BYTES: number;
 export type TerminalRestoreOptions = NonNullable<SubscribeTerminalRequest["restore"]>;
 export type TerminalSubscriptionSnapshotMode = "state" | "ready";
 export declare function resolveTerminalSubscriptionSnapshotMode(restore: TerminalRestoreOptions | undefined): TerminalSubscriptionSnapshotMode;

package/dist/server/terminal/terminal-restore.js

@@ -1,6 +1,12 @@
 import { TerminalStreamOpcode, encodeTerminalSnapshotPayload, encodeTerminalStreamFrame, } from "@getpaseo/protocol/binary-frames/index";
 import { renderTerminalSnapshotToAnsi } from "@getpaseo/protocol/terminal-snapshot";
 export const MAX_TERMINAL_OUTPUT_FRAME_BYTES = 256 * 1024;
+// A client is only forced onto the snapshot catch-up path once its transport is
+// genuinely backed up — measured by the socket's bufferedAmount, not by how much
+// the terminal has produced. Set well above any normal in-flight burst (a
+// keeping-up client drains continuously and never approaches this) but low
+// enough that a stalled socket crosses it long before a large burst finishes.
+export const MAX_CLIENT_BUFFERED_BYTES = 4 * 1024 * 1024;
 const DEFAULT_VISIBLE_RESTORE_SCROLLBACK_LINES = 200;
 const MAX_VISIBLE_RESTORE_SCROLLBACK_LINES = 500;
 export function resolveTerminalSubscriptionSnapshotMode(restore) {

package/dist/server/terminal/terminal-session-controller.d.ts

@@ -11,6 +11,7 @@ export interface TerminalSessionControllerOptions {
     sessionLogger: pino.Logger;
     listTerminalWorkspaceRoots?: () => Promise<readonly string[]>;
     clientSupportsWrapReflow?: () => boolean;
+    getClientBufferedAmount?: () => number | null;
 }
 export interface TerminalSessionControllerMetrics {
     directorySubscriptionCount: number;
@@ -25,6 +26,7 @@ export declare class TerminalSessionController {
     private readonly sessionLogger;
     private readonly listTerminalWorkspaceRoots;
     private readonly clientSupportsWrapReflow;
+    private readonly getClientBufferedAmount;
     private readonly subscribedDirectories;
     private unsubscribeTerminalsChanged;
     private readonly exitSubscriptions;
@@ -40,7 +42,7 @@ export declare class TerminalSessionController {
         terminalId: string;
         success: boolean;
     };
-    killTerminalsUnderPath(rootPath: string): Promise<void>;
+    killTerminalsForWorkspace(workspaceId: string): Promise<void>;
     dispose(): void;
     private ensureExitSubscription;
     private handleTerminalExited;
@@ -49,7 +51,7 @@ export declare class TerminalSessionController {
     private handleTerminalsChanged;
     private handleSubscribeTerminalsRequest;
     private handleUnsubscribeTerminalsRequest;
-    private emitTerminalsSnapshotForRoot;
+    private emitTerminalsSnapshotForSubscription;
     private handleListTerminalsRequest;
     private getAllTerminalSessions;
     private getTerminalsForWorkspaceRoot;

package/dist/server/terminal/terminal-session-controller.js

@@ -1,7 +1,8 @@
-import { killTerminalsUnderPath as killWorktreeTerminalsUnderPath } from "../server/paseo-worktree-archive-service.js";
+import { killTerminalsForWorkspace as killWorkspaceTerminals } from "../server/workspace-archive-service.js";
 import { TerminalStreamOpcode, decodeTerminalResizePayload, encodeTerminalStreamFrame, } from "@getpaseo/protocol/binary-frames/index";
 import { TerminalOutputCoalescer } from "./terminal-output-coalescer.js";
-import { MAX_TERMINAL_OUTPUT_FRAME_BYTES, encodeLegacyTerminalSnapshotFrame, encodeTerminalRestoreFrame, resolveRestoreAfterOutputOverflow, resolveTerminalRestoreSnapshotOptions, resolveTerminalSubscriptionSnapshotMode, } from "./terminal-restore.js";
+import { MAX_CLIENT_BUFFERED_BYTES, MAX_TERMINAL_OUTPUT_FRAME_BYTES, encodeLegacyTerminalSnapshotFrame, encodeTerminalRestoreFrame, resolveRestoreAfterOutputOverflow, resolveTerminalRestoreSnapshotOptions, resolveTerminalSubscriptionSnapshotMode, } from "./terminal-restore.js";
+import { terminalSubscriptionKey } from "@getpaseo/protocol/terminal-subscription-key";
 const MAX_TERMINAL_STREAM_SLOTS = 256;
 const TERMINAL_MESSAGE_TYPES = new Set([
     "subscribe_terminals_request",
@@ -17,7 +18,11 @@ const TERMINAL_MESSAGE_TYPES = new Set([
 ]);
 export class TerminalSessionController {
     constructor(options) {
-        this.subscribedDirectories = new Set();
+        // A subscription is scoped to a (cwd, workspaceId) pair, keyed by
+        // terminalSubscriptionKey: two workspaces sharing a cwd subscribe and unsub
+        // independently, and each only receives its own workspace's terminals. The
+        // workspaceId is absent for old clients, which key to the cwd alone.
+        this.subscribedDirectories = new Map();
         this.unsubscribeTerminalsChanged = null;
         this.exitSubscriptions = new Map();
         this.activeStreams = new Map();
@@ -31,6 +36,7 @@ export class TerminalSessionController {
         this.sessionLogger = options.sessionLogger;
         this.listTerminalWorkspaceRoots = options.listTerminalWorkspaceRoots ?? (async () => []);
         this.clientSupportsWrapReflow = options.clientSupportsWrapReflow ?? (() => false);
+        this.getClientBufferedAmount = options.getClientBufferedAmount ?? (() => 0);
     }
     start() {
         if (!this.terminalManager) {
@@ -120,14 +126,12 @@ export class TerminalSessionController {
         this.killTracked(terminalId, { emitExit: true });
         return { terminalId, success: true };
     }
-    async killTerminalsUnderPath(rootPath) {
-        return killWorktreeTerminalsUnderPath({
-            isPathWithinRoot: (pathRoot, candidatePath) => this.isPathWithinRoot(pathRoot, candidatePath),
-            killTrackedTerminal: (terminalId, options) => this.killTracked(terminalId, options),
+    async killTerminalsForWorkspace(workspaceId) {
+        return killWorkspaceTerminals({
             detachTerminalStream: (terminalId, options) => void this.detachStream(terminalId, options),
             sessionLogger: this.sessionLogger,
             terminalManager: this.terminalManager,
-        }, rootPath);
+        }, workspaceId);
     }
     dispose() {
         if (this.unsubscribeTerminalsChanged) {
@@ -171,10 +175,13 @@ export class TerminalSessionController {
     }
     toTerminalInfo(terminal) {
         const title = terminal.getTitle();
+        const activity = terminal.getActivity();
         return {
             id: terminal.id,
             name: terminal.name,
+            workspaceId: terminal.workspaceId,
             ...(title ? { title } : {}),
+            activity,
         };
     }
     async handleTerminalsChanged(event) {
@@ -183,37 +190,39 @@ export class TerminalSessionController {
         // or above the terminal's cwd, keyed by that root, carrying the full
         // aggregated list — so the client's cache replacement doesn't drop the
         // terminals that live directly at the root.
-        const matchingRoots = Array.from(this.subscribedDirectories).filter((root) => this.isPathWithinRoot(root, event.cwd));
-        for (const root of matchingRoots) {
-            await this.emitTerminalsSnapshotForRoot(root);
+        const matchingSubscriptions = Array.from(this.subscribedDirectories.values()).filter((subscription) => this.isPathWithinRoot(subscription.cwd, event.cwd));
+        for (const subscription of matchingSubscriptions) {
+            await this.emitTerminalsSnapshotForSubscription(subscription);
         }
     }
     handleSubscribeTerminalsRequest(msg) {
-        this.subscribedDirectories.add(msg.cwd);
-        void this.emitTerminalsSnapshotForRoot(msg.cwd);
+        const subscription = { cwd: msg.cwd, workspaceId: msg.workspaceId };
+        this.subscribedDirectories.set(terminalSubscriptionKey(msg.cwd, msg.workspaceId), subscription);
+        void this.emitTerminalsSnapshotForSubscription(subscription);
     }
     handleUnsubscribeTerminalsRequest(msg) {
-        this.subscribedDirectories.delete(msg.cwd);
+        this.subscribedDirectories.delete(terminalSubscriptionKey(msg.cwd, msg.workspaceId));
     }
-    async emitTerminalsSnapshotForRoot(cwd) {
-        if (!this.terminalManager || !this.subscribedDirectories.has(cwd)) {
+    async emitTerminalsSnapshotForSubscription(subscription) {
+        const key = terminalSubscriptionKey(subscription.cwd, subscription.workspaceId);
+        if (!this.terminalManager || !this.subscribedDirectories.has(key)) {
             return;
         }
         try {
-            const terminals = await this.getTerminalsForWorkspaceRoot(cwd);
+            const terminals = await this.getTerminalsForWorkspaceRoot(subscription.cwd, subscription.workspaceId);
             for (const terminal of terminals) {
                 this.ensureExitSubscription(terminal);
             }
-            if (!this.subscribedDirectories.has(cwd)) {
+            if (!this.subscribedDirectories.has(key)) {
                 return;
             }
             this.emitTerminalsChangedSnapshot({
-                cwd,
+                cwd: subscription.cwd,
                 terminals: terminals.map((terminal) => this.toTerminalInfo(terminal)),
             });
         }
         catch (error) {
-            this.sessionLogger.warn({ err: error, cwd }, "Failed to emit initial terminal snapshot");
+            this.sessionLogger.warn({ err: error, cwd: subscription.cwd }, "Failed to emit initial terminal snapshot");
         }
     }
     async handleListTerminalsRequest(msg) {
@@ -230,7 +239,7 @@ export class TerminalSessionController {
         }
         try {
             const terminals = typeof msg.cwd === "string"
-                ? await this.getTerminalsForWorkspaceRoot(msg.cwd)
+                ? await this.getTerminalsForWorkspaceRoot(msg.cwd, msg.workspaceId)
                 : await this.getAllTerminalSessions();
             for (const terminal of terminals) {
                 this.ensureExitSubscription(terminal);
@@ -265,11 +274,11 @@ export class TerminalSessionController {
         const terminalsByDirectory = await Promise.all(directories.map((cwd) => manager.getTerminals(cwd)));
         return terminalsByDirectory.flat();
     }
-    async getTerminalsForWorkspaceRoot(cwd) {
+    async getTerminalsForWorkspaceRoot(cwd, workspaceId) {
         if (!this.terminalManager) {
             return [];
         }
-        const terminals = await this.terminalManager.getTerminals(cwd);
+        const terminals = await this.terminalManager.getTerminals(cwd, { workspaceId });
         const workspaceRoots = await this.listTerminalWorkspaceRoots();
         if (workspaceRoots.length === 0) {
             return terminals;
@@ -322,8 +331,20 @@ export class TerminalSessionController {
                 });
                 return;
             }
+            if (!msg.workspaceId) {
+                this.emit({
+                    type: "create_terminal_response",
+                    payload: {
+                        terminal: null,
+                        error: "workspaceId is required",
+                        requestId: msg.requestId,
+                    },
+                });
+                return;
+            }
             const session = await this.terminalManager.createTerminal({
                 cwd: msg.cwd,
+                workspaceId: msg.workspaceId,
                 name: msg.name,
                 command: msg.command,
                 args: msg.args,
@@ -336,7 +357,9 @@ export class TerminalSessionController {
                         id: session.id,
                         name: session.name,
                         cwd: session.cwd,
+                        workspaceId: session.workspaceId,
                         ...(session.getTitle() ? { title: session.getTitle() } : {}),
+                        activity: session.getActivity(),
                     },
                     error: null,
                     requestId: msg.requestId,
@@ -571,7 +594,19 @@ export class TerminalSessionController {
                         return;
                     }
                     activeStream.outputBytesSinceSnapshot += payload.byteLength;
-                    if (activeStream.outputBytesSinceSnapshot > MAX_TERMINAL_OUTPUT_FRAME_BYTES) {
+                    // Catch up via a snapshot only when the client is BOTH far behind in
+                    // produced output AND actually backed up on the wire. A client that
+                    // keeps draining reports ~0 buffered, so it streams continuously even
+                    // past the byte threshold. outputBytesSinceSnapshot keeps accumulating
+                    // in that case — it's harmless, it only gates the snapshot decision at
+                    // the instant backpressure appears, and trySendSnapshot resets it to 0.
+                    // A null reading means the transport exposes no backpressure signal
+                    // (e.g. the multiplexed relay socket); there we can't tell a slow client
+                    // from a fast one, so fall back unconditionally at the byte threshold to
+                    // keep a slow relay client from falling unboundedly behind.
+                    const clientBufferedAmount = this.getClientBufferedAmount();
+                    if (activeStream.outputBytesSinceSnapshot > MAX_TERMINAL_OUTPUT_FRAME_BYTES &&
+                        (clientBufferedAmount === null || clientBufferedAmount > MAX_CLIENT_BUFFERED_BYTES)) {
                         activeStream.restore = resolveRestoreAfterOutputOverflow(activeStream.restore);
                         activeStream.needsSnapshot = true;
                         void this.trySendSnapshot(activeStream);
@@ -671,6 +706,9 @@ export class TerminalSessionController {
             slot: activeStream.slot,
             snapshot,
         }));
+        // The snapshot frame went out-of-band; keep the replay that follows on the
+        // coalescer's trailing path so it doesn't flush back-to-back with it.
+        activeStream.outputCoalescer.markFlushed();
         return { shouldContinue: true, replayRevision: snapshot.revision };
     }
     async emitRestoreSnapshot(activeStream, terminalManager, restore) {
@@ -693,6 +731,9 @@ export class TerminalSessionController {
             slot: activeStream.slot,
             snapshot,
         }));
+        // The restore frame went out-of-band; keep the replay that follows on the
+        // coalescer's trailing path so it doesn't flush back-to-back with it.
+        activeStream.outputCoalescer.markFlushed();
         return { shouldContinue: true, replayRevision: snapshot.revision };
     }
     replayTerminalOutputAfterSnapshot(activeStream, terminal, replayRevision) {