@bitkyc08/opencodex 2.52.0 → 2.53.0-preview.20260913

package/src/remote-control/workspace-sessions.ts

@@ -0,0 +1,799 @@
+import { randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, statSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { atomicWriteFile } from "../config/atomic-write";
+import { getConfigDir } from "../config/paths";
+import { workspaceSecretFileExists, workspaceSecretPermissions, type WorkspaceSecretPermissions } from "./workspace-secret-store";
+import { RemoteWorkspaceCoordinator, type RemoteWorkspaceTransport } from "./workspace-coordinator";
+import type { RemoteWorkspaceHub } from "./workspace-hub";
+import { isRemoteWorkspaceAgentProfile, type RemoteWorkspaceAgentProfile } from "./workspace-agent-protocol";
+import type { RemoteWorkspaceExecutionRequest } from "./workspace-executor";
+import { runRemoteWorkspaceCleanupSteps } from "./workspace-process";
+import { truncateRemoteWorkspaceUtf8 } from "./workspace-utf8";
+import { REMOTE_CONTROL_MAX_SESSIONS_PER_DEVICE } from "./protocol";
+import {
+  parseRemoteWorkspaceCapabilities,
+  remoteWorkspaceToolsForCapabilities,
+  type RemoteWorkspaceCapability,
+  type RemoteWorkspaceToolName,
+  type RemoteWorkspaceToolResult,
+} from "./workspace-tools";
+
+export const REMOTE_WORKSPACE_SESSION_STATE_VERSION = 1 as const;
+
+export type RemoteWorkspaceSessionStatus =
+  | "starting"
+  | "ready"
+  | "running"
+  | "waiting_for_executor"
+  | "failed"
+  | "stopped";
+
+export type RemoteWorkspaceAccessMode = "read-only" | "workspace";
+
+export interface RemoteWorkspaceSessionEvent {
+  sequence: number;
+  at: string;
+  type: "status" | "assistant" | "tool" | "error";
+  text: string;
+}
+
+export interface RemoteWorkspaceSessionSummary {
+  id: string;
+  profile: RemoteWorkspaceAgentProfile;
+  accessMode: RemoteWorkspaceAccessMode;
+  deviceId: string;
+  deviceName: string;
+  rootId: string;
+  rootLabel: string;
+  capabilities: RemoteWorkspaceCapability[];
+  tools: RemoteWorkspaceToolName[];
+  threadId: string | null;
+  /** True only after the runtime has created durable history that can be resumed. */
+  resumable: boolean;
+  status: RemoteWorkspaceSessionStatus;
+  createdAt: string;
+  updatedAt: string;
+  events: RemoteWorkspaceSessionEvent[];
+}
+
+export interface RemoteWorkspaceRuntimeHandle {
+  threadId: string;
+  canResume?(): boolean;
+  prompt(text: string): Promise<void>;
+  stop(): Promise<void>;
+}
+
+export interface RemoteWorkspaceRuntimeFactory {
+  profile: RemoteWorkspaceAgentProfile;
+  available(): Promise<{ available: boolean; version?: string; reason?: string }>;
+  start(options: {
+    sessionId: string;
+    deviceId: string;
+    deviceName: string;
+    rootId: string;
+    rootLabel: string;
+    capabilities: RemoteWorkspaceCapability[];
+    tools: RemoteWorkspaceToolName[];
+    resumeThreadId?: string;
+    coordinator: RemoteWorkspaceCoordinator;
+    emit(type: RemoteWorkspaceSessionEvent["type"], text: string): void;
+  }): Promise<RemoteWorkspaceRuntimeHandle>;
+}
+
+export interface RemoteWorkspaceSessionState {
+  version: typeof REMOTE_WORKSPACE_SESSION_STATE_VERSION;
+  sessions: RemoteWorkspaceSessionSummary[];
+}
+
+export interface RemoteWorkspaceSessionStateStore {
+  load(): RemoteWorkspaceSessionState | null;
+  save(state: RemoteWorkspaceSessionState): void;
+}
+
+interface LiveSession extends RemoteWorkspaceSessionSummary {
+  handle: RemoteWorkspaceRuntimeHandle | null;
+  unregister: (() => void) | null;
+  closeTransport: (() => Promise<void>) | null;
+  operation: Promise<void>;
+  stopOperation: Promise<boolean> | null;
+  remoteTransport: SwitchableRemoteWorkspaceTransport | null;
+  turnActive: boolean;
+}
+
+const MAX_EVENTS_PER_SESSION = 100;
+const MAX_EVENT_TEXT_BYTES = 8 * 1024;
+const MAX_PROMPT_BYTES = 256 * 1024;
+const MAX_LIVE_SESSIONS = 8;
+const MAX_RETAINED_SESSIONS = 64;
+const MAX_LIST_EVENTS_PER_SESSION = 20;
+const MAX_PERSISTED_EVENTS_PER_SESSION = 40;
+const MAX_PERSISTED_EVENT_TEXT_BYTES = 4 * 1024;
+const MAX_SESSION_STATE_BYTES = 16 * 1024 * 1024;
+const AVAILABILITY_CACHE_MS = 30_000;
+type RuntimeAvailability = Record<RemoteWorkspaceAgentProfile, { available: boolean; version?: string; reason?: string }>;
+
+class SwitchableRemoteWorkspaceTransport implements RemoteWorkspaceTransport {
+  constructor(private current: RemoteWorkspaceTransport) {}
+
+  replace(next: RemoteWorkspaceTransport): void {
+    this.current = next;
+  }
+
+  isOnline(deviceId: string): boolean {
+    return this.current.isOnline(deviceId);
+  }
+
+  invoke(request: RemoteWorkspaceExecutionRequest): Promise<RemoteWorkspaceToolResult> {
+    return this.current.invoke(request);
+  }
+}
+
+function boundedPrompt(value: unknown): string {
+  if (typeof value !== "string" || value.trim().length < 1 || Buffer.byteLength(value, "utf8") > MAX_PROMPT_BYTES) {
+    throw new Error("remote workspace prompt must contain 1 to 262144 UTF-8 bytes");
+  }
+  return value;
+}
+
+function boundedEventText(value: string): string {
+  if (Buffer.byteLength(value, "utf8") <= MAX_EVENT_TEXT_BYTES) return value;
+  const marker = "\n[truncated]";
+  return `${truncateRemoteWorkspaceUtf8(value, MAX_EVENT_TEXT_BYTES - Buffer.byteLength(marker, "utf8"))}${marker}`;
+}
+
+function boundedPersistedEventText(value: string): string {
+  if (Buffer.byteLength(value, "utf8") <= MAX_PERSISTED_EVENT_TEXT_BYTES) return value;
+  const marker = "\n[truncated for restart snapshot]";
+  const maximum = MAX_PERSISTED_EVENT_TEXT_BYTES - Buffer.byteLength(marker, "utf8");
+  return `${truncateRemoteWorkspaceUtf8(value, maximum)}${marker}`;
+}
+
+function boundedString(value: unknown, label: string, maximum = 256): string {
+  if (typeof value !== "string" || value.length < 1 || value.length > maximum || /[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/.test(value)) {
+    throw new Error(`invalid remote workspace ${label}`);
+  }
+  return value;
+}
+
+function timestamp(value: unknown): string {
+  const result = boundedString(value, "timestamp", 64);
+  if (!Number.isFinite(Date.parse(result))) throw new Error("invalid remote workspace timestamp");
+  return result;
+}
+
+function parseStatus(value: unknown): RemoteWorkspaceSessionStatus {
+  if (value === "starting" || value === "ready" || value === "running"
+    || value === "waiting_for_executor" || value === "failed" || value === "stopped") return value;
+  throw new Error("invalid remote workspace session status");
+}
+
+function parseAccessMode(value: unknown): RemoteWorkspaceAccessMode {
+  if (value === undefined || value === "workspace") return "workspace";
+  if (value === "read-only") return value;
+  throw new Error("invalid remote workspace access mode");
+}
+
+function parseEvent(value: unknown): RemoteWorkspaceSessionEvent {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("invalid remote workspace session event");
+  const raw = value as Record<string, unknown>;
+  if (typeof raw.sequence !== "number" || !Number.isSafeInteger(raw.sequence) || raw.sequence < 1) {
+    throw new Error("invalid remote workspace event sequence");
+  }
+  if (raw.type !== "status" && raw.type !== "assistant" && raw.type !== "tool" && raw.type !== "error") {
+    throw new Error("invalid remote workspace event type");
+  }
+  return {
+    sequence: raw.sequence,
+    at: timestamp(raw.at),
+    type: raw.type,
+    text: boundedString(raw.text, "event text", MAX_EVENT_TEXT_BYTES),
+  };
+}
+
+function parseSession(value: unknown): RemoteWorkspaceSessionSummary {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("invalid remote workspace session");
+  const raw = value as Record<string, unknown>;
+  if (!isRemoteWorkspaceAgentProfile(raw.profile)) throw new Error("invalid remote workspace session profile");
+  const accessMode = parseAccessMode(raw.accessMode);
+  const capabilities = parseRemoteWorkspaceCapabilities(raw.capabilities);
+  if (accessMode === "read-only"
+    && (capabilities.length !== 1 || capabilities[0] !== "workspace.read")) {
+    throw new Error("read-only remote workspace state contains write capabilities");
+  }
+  const tools = remoteWorkspaceToolsForCapabilities(capabilities);
+  if (!Array.isArray(raw.events) || raw.events.length > MAX_EVENTS_PER_SESSION) {
+    throw new Error("invalid remote workspace session events");
+  }
+  if (raw.threadId !== null && typeof raw.threadId !== "string") throw new Error("invalid remote workspace thread ID");
+  const resumable = raw.resumable === undefined
+    ? raw.threadId !== null
+    : raw.resumable === true;
+  if (raw.resumable !== undefined && typeof raw.resumable !== "boolean") {
+    throw new Error("invalid remote workspace resumable state");
+  }
+  if (resumable && raw.threadId === null) throw new Error("resumable remote workspace session has no thread ID");
+  return {
+    id: boundedString(raw.id, "session ID"),
+    profile: raw.profile,
+    accessMode,
+    deviceId: boundedString(raw.deviceId, "device ID"),
+    deviceName: boundedString(raw.deviceName, "device name", 80),
+    rootId: boundedString(raw.rootId, "root ID"),
+    rootLabel: boundedString(raw.rootLabel, "root label", 80),
+    capabilities,
+    tools,
+    threadId: raw.threadId === null ? null : boundedString(raw.threadId, "thread ID"),
+    resumable,
+    status: parseStatus(raw.status),
+    createdAt: timestamp(raw.createdAt),
+    updatedAt: timestamp(raw.updatedAt),
+    events: raw.events.map(parseEvent),
+  };
+}
+
+export function parseRemoteWorkspaceSessionState(value: unknown): RemoteWorkspaceSessionState {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("invalid remote workspace session state");
+  const raw = value as Record<string, unknown>;
+  if (raw.version !== REMOTE_WORKSPACE_SESSION_STATE_VERSION || !Array.isArray(raw.sessions)) {
+    throw new Error("unsupported remote workspace session state");
+  }
+  if (raw.sessions.length > MAX_RETAINED_SESSIONS) throw new Error("remote workspace retained session limit exceeded");
+  const ids = new Set<string>();
+  const sessions = raw.sessions.map(item => {
+    const session = parseSession(item);
+    if (ids.has(session.id)) throw new Error("duplicate remote workspace session ID");
+    ids.add(session.id);
+    return session;
+  });
+  return { version: REMOTE_WORKSPACE_SESSION_STATE_VERSION, sessions };
+}
+
+export class RemoteWorkspaceSessionFileStore implements RemoteWorkspaceSessionStateStore {
+  constructor(
+    private readonly path = join(getConfigDir(), "remote-workspace-sessions.json"),
+    private readonly permissions: WorkspaceSecretPermissions = workspaceSecretPermissions,
+  ) {}
+
+  load(): RemoteWorkspaceSessionState | null {
+    if (!workspaceSecretFileExists(this.path)) return null;
+    this.permissions.prepareDirectory(dirname(this.path));
+    this.permissions.hardenFile(this.path);
+    const metadata = statSync(this.path);
+    if (!metadata.isFile() || metadata.size > MAX_SESSION_STATE_BYTES) {
+      throw new Error("remote workspace session state is too large");
+    }
+    return parseRemoteWorkspaceSessionState(JSON.parse(readFileSync(this.path, "utf8")));
+  }
+
+  save(state: RemoteWorkspaceSessionState): void {
+    const parsed = parseRemoteWorkspaceSessionState(state);
+    const body = `${JSON.stringify(parsed, null, 2)}\n`;
+    if (Buffer.byteLength(body, "utf8") > MAX_SESSION_STATE_BYTES) {
+      throw new Error("remote workspace session state is too large");
+    }
+    this.permissions.prepareDirectory(dirname(this.path));
+    if (workspaceSecretFileExists(this.path)) this.permissions.hardenFile(this.path);
+    atomicWriteFile(this.path, body);
+  }
+}
+
+export class RemoteWorkspaceSessionService {
+  private shuttingDown = false;
+  private readonly pendingCreates = new Set<Promise<RemoteWorkspaceSessionSummary>>();
+  private startupCleanupFailure: Error | null = null;
+  private readonly sessions = new Map<string, LiveSession>();
+  private readonly runtimeReservations = new Map<string, string>();
+  private readonly runtimes = new Map<RemoteWorkspaceAgentProfile, RemoteWorkspaceRuntimeFactory>();
+  private sequence = 0;
+  private availabilityCache: { at: number; value: RuntimeAvailability } | null = null;
+  private availabilityFlight: Promise<RuntimeAvailability> | null = null;
+
+  constructor(
+    private readonly hub: RemoteWorkspaceHub,
+    factories: readonly RemoteWorkspaceRuntimeFactory[],
+    private readonly now: () => number = Date.now,
+    private readonly store?: RemoteWorkspaceSessionStateStore,
+  ) {
+    for (const factory of factories) {
+      if (this.runtimes.has(factory.profile)) throw new Error("duplicate remote workspace runtime profile");
+      this.runtimes.set(factory.profile, factory);
+    }
+    for (const summary of this.store?.load()?.sessions ?? []) {
+      const restoredStatus = summary.status === "stopped"
+        ? "stopped"
+        : summary.threadId && summary.resumable
+          ? "waiting_for_executor"
+          : "failed";
+      this.sessions.set(summary.id, {
+        ...summary,
+        status: restoredStatus,
+        handle: null,
+        unregister: null,
+        closeTransport: null,
+        operation: Promise.resolve(),
+        stopOperation: null,
+        remoteTransport: null,
+        turnActive: false,
+      });
+      for (const event of summary.events) this.sequence = Math.max(this.sequence, event.sequence);
+    }
+  }
+
+  async availability(): Promise<RuntimeAvailability> {
+    if (this.availabilityCache && this.now() - this.availabilityCache.at < AVAILABILITY_CACHE_MS) {
+      return structuredClone(this.availabilityCache.value);
+    }
+    if (this.availabilityFlight) return structuredClone(await this.availabilityFlight);
+    this.availabilityFlight = (async () => {
+      const probe = async (profile: RemoteWorkspaceAgentProfile) => {
+        const factory = this.runtimes.get(profile);
+        if (!factory) return { available: false, reason: "runtime adapter is not installed" };
+        try { return await factory.available(); }
+        catch { return { available: false, reason: "runtime availability probe failed" }; }
+      };
+      const [codex, claude, pi] = await Promise.all([
+        probe("codex"),
+        probe("claude"),
+        probe("pi"),
+      ]);
+      const value: RuntimeAvailability = { codex, claude, pi };
+      this.availabilityCache = { at: this.now(), value };
+      return value;
+    })();
+    try { return structuredClone(await this.availabilityFlight); }
+    finally { this.availabilityFlight = null; }
+  }
+
+  list(): RemoteWorkspaceSessionSummary[] {
+    this.refreshOfflineStates();
+    return [...this.sessions.values()].map(session => this.publicSession(session, MAX_LIST_EVENTS_PER_SESSION));
+  }
+
+  get(sessionId: string): RemoteWorkspaceSessionSummary | null {
+    this.refreshOfflineStates();
+    const session = this.sessions.get(sessionId);
+    return session ? this.publicSession(session) : null;
+  }
+
+  private reserveRuntime(deviceId: string): () => void {
+    const live = [...this.sessions.values()].filter(session => session.handle !== null);
+    const pending = [...this.runtimeReservations.values()];
+    if (live.length + pending.length >= MAX_LIVE_SESSIONS) {
+      throw new Error("remote workspace active session limit reached");
+    }
+    if (live.filter(session => session.deviceId === deviceId).length
+      + pending.filter(device => device === deviceId).length >= REMOTE_CONTROL_MAX_SESSIONS_PER_DEVICE) {
+      throw new Error("remote workspace executor session limit reached");
+    }
+    const reservation = randomUUID();
+    this.runtimeReservations.set(reservation, deviceId);
+    return () => { this.runtimeReservations.delete(reservation); };
+  }
+
+  create(input: {
+    profile: RemoteWorkspaceAgentProfile;
+    deviceId: string;
+    rootId: string;
+    accessMode?: RemoteWorkspaceAccessMode;
+  }): Promise<RemoteWorkspaceSessionSummary> {
+    const operation = this.createSession(input);
+    this.pendingCreates.add(operation);
+    void operation.then(() => this.pendingCreates.delete(operation), () => this.pendingCreates.delete(operation));
+    return operation;
+  }
+
+  private async createSession(input: {
+    profile: RemoteWorkspaceAgentProfile;
+    deviceId: string;
+    rootId: string;
+    accessMode?: RemoteWorkspaceAccessMode;
+  }): Promise<RemoteWorkspaceSessionSummary> {
+    if (this.shuttingDown) throw new Error("remote workspace hub is stopping");
+    this.pruneRetainedSessions();
+    const releaseRuntime = this.reserveRuntime(input.deviceId);
+    try {
+      const factory = this.runtimes.get(input.profile);
+      if (!factory) throw new Error(`remote workspace ${input.profile} runtime is not installed on the hub`);
+      const available = await factory.available();
+      if (this.shuttingDown) throw new Error("remote workspace hub is stopping");
+      if (!available.available) throw new Error(available.reason ?? `remote workspace ${input.profile} runtime is unavailable`);
+      const device = this.hub.listDevices().find(candidate => candidate.id === input.deviceId);
+      if (!device) throw new Error("remote workspace device not found");
+      const root = device.roots.find(candidate => candidate.id === input.rootId);
+      if (!root) throw new Error("remote workspace root not found on the selected device");
+      const connection = this.hub.connection(device.id);
+      if (!connection) throw new Error("remote workspace executor is offline");
+      const id = randomUUID();
+      const accessMode = parseAccessMode(input.accessMode ?? "read-only");
+      const deviceCapabilities = parseRemoteWorkspaceCapabilities(device.capabilities);
+      const capabilities = accessMode === "read-only"
+        ? parseRemoteWorkspaceCapabilities(["workspace.read"])
+        : deviceCapabilities;
+      const tools = remoteWorkspaceToolsForCapabilities(capabilities);
+      const connectionCapabilities = connection.capabilities();
+      if (capabilities.some(capability => !connectionCapabilities.includes(capability))) {
+        throw new Error("remote workspace executor capability advertisement is stale; refresh and try again");
+      }
+      const timestamp = new Date(this.now()).toISOString();
+      const session: LiveSession = {
+        id,
+        profile: input.profile,
+        accessMode,
+        deviceId: device.id,
+        deviceName: device.name,
+        rootId: root.id,
+        rootLabel: root.label,
+        capabilities,
+        tools,
+        threadId: null,
+        resumable: false,
+        status: "starting",
+        createdAt: timestamp,
+        updatedAt: timestamp,
+        events: [],
+        handle: null,
+        unregister: null,
+        closeTransport: null,
+        operation: Promise.resolve(),
+        stopOperation: null,
+        remoteTransport: null,
+        turnActive: false,
+      };
+      this.sessions.set(id, session);
+      this.emit(session, "status", `Starting ${input.profile} on ${device.name}/${root.label}`);
+      try {
+        this.persist();
+      } catch (error) {
+        this.sessions.delete(id);
+        throw error;
+      }
+      try {
+        session.closeTransport = () => connection.closeSession(id);
+        const transport = await connection.openSession({ sessionId: id, rootId: root.id, profile: input.profile, capabilities });
+        if (session.stopOperation) {
+          await session.closeTransport().catch(() => {});
+          session.closeTransport = null;
+          throw new Error("remote workspace session was stopped while starting");
+        }
+        const remoteTransport = new SwitchableRemoteWorkspaceTransport(transport);
+        session.remoteTransport = remoteTransport;
+        const coordinator = new RemoteWorkspaceCoordinator(remoteTransport);
+        const handle = await factory.start({
+          sessionId: id,
+          deviceId: device.id,
+          deviceName: device.name,
+          rootId: root.id,
+          rootLabel: root.label,
+          capabilities,
+          tools,
+          coordinator,
+          emit: (type, text) => this.emit(session, type, text),
+        });
+        if (session.stopOperation || this.shuttingDown) {
+          await this.stopLateRuntime(handle);
+          throw new Error("remote workspace session was stopped while starting");
+        }
+        session.threadId = handle.threadId;
+        session.resumable = handle.canResume?.() ?? true;
+        session.handle = handle;
+        session.unregister = coordinator.register({
+          sessionId: id,
+          threadId: handle.threadId,
+          executorDeviceId: device.id,
+          executorName: device.name,
+          rootId: root.id,
+          capabilities,
+          tools,
+        });
+        this.status(session, "ready", `${input.profile} is ready on ${device.name}/${root.label}`);
+        return this.publicSession(session);
+      } catch (error) {
+        let reported = error;
+        if (session.status !== "stopped") {
+          try {
+            this.status(session, "failed", error instanceof Error ? error.message : "remote workspace session failed to start");
+          } catch (persistenceError) {
+            reported = persistenceError;
+          }
+        }
+        session.unregister?.();
+        session.unregister = null;
+        await session.handle?.stop().catch(() => {});
+        session.handle = null;
+        await session.closeTransport?.().catch(() => {});
+        session.closeTransport = null;
+        session.remoteTransport = null;
+        throw reported;
+      }
+    } finally {
+      releaseRuntime();
+    }
+  }
+
+  async prompt(sessionId: string, value: unknown): Promise<RemoteWorkspaceSessionSummary> {
+    const session = this.startPrompt(sessionId, value);
+    await session.operation;
+    return this.publicSession(session);
+  }
+
+  submitPrompt(sessionId: string, value: unknown): RemoteWorkspaceSessionSummary {
+    return this.publicSession(this.startPrompt(sessionId, value));
+  }
+
+  private startPrompt(sessionId: string, value: unknown): LiveSession {
+    const prompt = boundedPrompt(value);
+    const session = this.sessions.get(sessionId);
+    if (!session || session.status === "stopped") throw new Error("remote workspace session is not ready");
+    if (!session.handle && (!session.threadId || !session.resumable)) {
+      throw new Error("remote workspace session cannot be resumed");
+    }
+    if (session.turnActive) throw new Error("remote workspace session already has an active turn");
+    if (session.stopOperation) throw new Error("remote workspace session is stopping");
+    session.turnActive = true;
+    const run = async () => {
+      try {
+        this.status(session, "running", "Turn accepted");
+        await this.ensureRemoteTransport(session);
+        await this.ensureRuntime(session);
+        if (session.stopOperation) throw new Error("remote workspace session is stopping");
+        this.status(session, "running", "Turn started");
+        await session.handle!.prompt(prompt);
+        session.resumable = session.handle!.canResume?.() ?? true;
+        if (!this.hub.connection(session.deviceId)
+          || !session.remoteTransport?.isOnline(session.deviceId)) {
+          this.status(session, "waiting_for_executor", "Turn completed; reconnect the remote executor before continuing.");
+        } else {
+          this.status(session, "ready", "Turn completed");
+        }
+      } catch (error) {
+        const message = error instanceof Error ? error.message : "remote workspace turn failed";
+        this.status(session, this.hub.connection(session.deviceId) ? "failed" : "waiting_for_executor", message);
+        throw error;
+      } finally {
+        session.turnActive = false;
+      }
+    };
+    session.operation = run();
+    // Polling observes the stored terminal status; awaited callers and cleanup retain
+    // the original rejecting promise, with an observer attached before detachment.
+    void session.operation.catch(() => {});
+    return session;
+  }
+
+  async stop(sessionId: string): Promise<boolean> {
+    const session = this.sessions.get(sessionId);
+    if (!session) return false;
+    if (session.stopOperation) return session.stopOperation;
+    session.stopOperation = (async () => {
+      const handle = session.handle;
+      const activeOperation = session.operation;
+      // Cancellation has to run before waiting for the active turn. Waiting first makes
+      // Stop unable to interrupt a model request or remote command that never completes.
+      try {
+        await runRemoteWorkspaceCleanupSteps([
+          async () => { if (handle) await handle.stop(); },
+          () => activeOperation.catch(() => {}),
+          async () => { if (session.handle && session.handle !== handle) await session.handle.stop(); },
+          () => { session.unregister?.(); session.unregister = null; },
+          async () => { if (session.closeTransport) await session.closeTransport(); },
+          () => {
+            session.closeTransport = null;
+            session.handle = null;
+            session.remoteTransport = null;
+          },
+        ]);
+      } catch (error) {
+        this.status(session, "failed", "Session cleanup failed; one or more owned resources did not close.");
+        throw error;
+      }
+      this.status(session, "stopped", "Session stopped");
+      return true;
+    })();
+    return session.stopOperation;
+  }
+
+  async stopAll(): Promise<void> {
+    const active = [...this.sessions.values()].filter(session => session.status !== "stopped");
+    await Promise.all(active.map(session => this.stop(session.id).then(() => undefined)));
+    this.persist();
+  }
+
+  async shutdown(): Promise<void> {
+    this.shuttingDown = true;
+    const active = [...this.sessions.values()].filter(session => session.status !== "stopped");
+    const results = await Promise.allSettled(active.map(async session => {
+      if (session.stopOperation) {
+        await session.stopOperation;
+        return;
+      }
+      session.stopOperation = (async () => {
+        const handle = session.handle;
+        const activeOperation = session.operation;
+        try {
+          await runRemoteWorkspaceCleanupSteps([
+            async () => { if (handle) await handle.stop(); },
+            () => activeOperation.catch(() => {}),
+          async () => { if (session.handle && session.handle !== handle) await session.handle.stop(); },
+            () => { session.unregister?.(); session.unregister = null; },
+            async () => { if (session.closeTransport) await session.closeTransport(); },
+            () => {
+              session.closeTransport = null;
+              session.handle = null;
+              session.remoteTransport = null;
+            },
+          ]);
+        } catch (error) {
+          this.status(session, "failed", "Hub shutdown could not close every Remote Workspace resource.");
+          throw error;
+        }
+        this.status(
+          session,
+          session.threadId && session.resumable ? "waiting_for_executor" : "failed",
+          session.threadId && session.resumable
+            ? "Hub stopped; reconnect the executor to resume this session."
+            : "Hub stopped before the model session was created.",
+        );
+        return true;
+      })();
+      await session.stopOperation;
+    }));
+    await Promise.allSettled([...this.pendingCreates]);
+    if (this.startupCleanupFailure) throw this.startupCleanupFailure;
+    const failed = results.find(result => result.status === "rejected");
+    if (failed?.status === "rejected") throw failed.reason;
+    this.persist();
+  }
+
+  private async stopLateRuntime(handle: RemoteWorkspaceRuntimeHandle): Promise<void> {
+    try { await handle.stop(); }
+    catch (error) {
+      this.startupCleanupFailure = error instanceof Error ? error : new Error("remote workspace startup cleanup failed");
+      throw this.startupCleanupFailure;
+    }
+  }
+
+  private status(session: LiveSession, status: RemoteWorkspaceSessionStatus, text: string): void {
+    session.status = status;
+    this.emit(session, status === "failed" ? "error" : "status", text);
+    this.persist();
+  }
+
+  private emit(session: LiveSession, type: RemoteWorkspaceSessionEvent["type"], text: string): void {
+    const at = new Date(this.now()).toISOString();
+    session.updatedAt = at;
+    session.events.push({ sequence: ++this.sequence, at, type, text: boundedEventText(text) });
+    if (session.events.length > MAX_EVENTS_PER_SESSION) {
+      session.events.splice(0, session.events.length - MAX_EVENTS_PER_SESSION);
+    }
+  }
+
+  private publicSession(session: LiveSession, eventLimit = MAX_EVENTS_PER_SESSION): RemoteWorkspaceSessionSummary {
+    const {
+      handle: _handle,
+      unregister: _unregister,
+      closeTransport: _close,
+      operation: _operation,
+      stopOperation: _stopOperation,
+      remoteTransport: _remoteTransport,
+      turnActive: _turnActive,
+      ...publicState
+    } = session;
+    return structuredClone({ ...publicState, events: publicState.events.slice(-eventLimit) });
+  }
+
+  private async ensureRemoteTransport(session: LiveSession): Promise<void> {
+    if (session.remoteTransport?.isOnline(session.deviceId)) return;
+    const connection = this.hub.connection(session.deviceId);
+    if (!connection) {
+      this.status(session, "waiting_for_executor", "Remote executor is offline; local fallback is disabled.");
+      throw new Error("remote workspace executor is offline");
+    }
+    const connectionCapabilities = connection.capabilities();
+    if (session.capabilities.some(capability => !connectionCapabilities.includes(capability))) {
+      throw new Error("remote workspace executor capabilities changed; start a new session for this computer");
+    }
+    this.status(session, "starting", `Reconnecting ${session.deviceName}/${session.rootLabel}`);
+    const transport = await connection.openSession({
+      sessionId: session.id,
+      rootId: session.rootId,
+      profile: session.profile,
+      capabilities: session.capabilities,
+    });
+    if (session.stopOperation) {
+      await connection.closeSession(session.id).catch(() => {});
+      throw new Error("remote workspace session is stopping");
+    }
+    await session.closeTransport?.().catch(() => {});
+    if (session.remoteTransport) session.remoteTransport.replace(transport);
+    else session.remoteTransport = new SwitchableRemoteWorkspaceTransport(transport);
+    session.closeTransport = () => connection.closeSession(session.id);
+    this.status(session, session.turnActive ? "running" : "ready", `${session.profile} reconnected to ${session.deviceName}/${session.rootLabel}`);
+  }
+
+  private async ensureRuntime(session: LiveSession): Promise<void> {
+    if (session.handle) return;
+    if (!session.threadId || !session.resumable || !session.remoteTransport) {
+      throw new Error("remote workspace session cannot be resumed");
+    }
+    const factory = this.runtimes.get(session.profile);
+    if (!factory) throw new Error(`remote workspace ${session.profile} runtime is not installed on the hub`);
+    const releaseRuntime = this.reserveRuntime(session.deviceId);
+    try {
+      const available = await factory.available();
+      if (this.shuttingDown) throw new Error("remote workspace hub is stopping");
+      if (!available.available) throw new Error(available.reason ?? `remote workspace ${session.profile} runtime is unavailable`);
+      const coordinator = new RemoteWorkspaceCoordinator(session.remoteTransport);
+      const handle = await factory.start({
+        sessionId: session.id,
+        deviceId: session.deviceId,
+        deviceName: session.deviceName,
+        rootId: session.rootId,
+        rootLabel: session.rootLabel,
+        capabilities: [...session.capabilities],
+        tools: [...session.tools],
+        resumeThreadId: session.threadId,
+        coordinator,
+        emit: (type, text) => this.emit(session, type, text),
+      });
+      if (this.shuttingDown || session.stopOperation) {
+        // Stop/shutdown awaits this resume and must observe any late-handle cleanup failure.
+        session.handle = handle;
+        throw new Error("remote workspace session was stopped while resuming");
+      }
+      try {
+        session.unregister = coordinator.register({
+          sessionId: session.id,
+          threadId: handle.threadId,
+          executorDeviceId: session.deviceId,
+          executorName: session.deviceName,
+          rootId: session.rootId,
+          capabilities: [...session.capabilities],
+          tools: [...session.tools],
+        });
+      } catch (error) {
+        await handle.stop().catch(() => {});
+        throw error;
+      }
+      session.threadId = handle.threadId;
+      session.handle = handle;
+      this.status(session, session.turnActive ? "running" : "ready", `${session.profile} resumed on ${session.deviceName}/${session.rootLabel}`);
+    } finally {
+      releaseRuntime();
+    }
+  }
+
+  private refreshOfflineStates(): void {
+    for (const session of this.sessions.values()) {
+      if (session.status !== "ready" || this.hub.connection(session.deviceId)) continue;
+      this.status(session, "waiting_for_executor", "Remote executor is offline; local fallback is disabled.");
+    }
+  }
+
+  private pruneRetainedSessions(): void {
+    if (this.sessions.size < MAX_RETAINED_SESSIONS) return;
+    for (const [id, session] of this.sessions) {
+      if (session.status !== "stopped" && !(session.status === "failed" && session.handle === null)) continue;
+      this.sessions.delete(id);
+      if (this.sessions.size < MAX_RETAINED_SESSIONS) return;
+    }
+    if (this.sessions.size >= MAX_RETAINED_SESSIONS) {
+      throw new Error("remote workspace retained session limit reached; stop an active session first");
+    }
+  }
+
+  private persist(): void {
+    if (!this.store) return;
+    const sessions = [...this.sessions.values()].map(session => {
+      const summary = this.publicSession(session);
+      return {
+        ...summary,
+        events: summary.events.slice(-MAX_PERSISTED_EVENTS_PER_SESSION).map(event => ({
+          ...event,
+          text: boundedPersistedEventText(event.text),
+        })),
+      };
+    });
+    this.store.save({ version: REMOTE_WORKSPACE_SESSION_STATE_VERSION, sessions });
+  }
+}