tmux-ide 2.9.0-beta.21 → 2.9.0-beta.22

package/packages/daemon-client/src/scoped-tmux-server-transport.ts

@@ -0,0 +1,385 @@
+import {
+  ActionContractsZ,
+  ApplicationShellProjectionInputV2SchemaZ,
+  DesktopApplicationShellTargetSchemaZ,
+  TerminalRuntimeInventoryProjectionV1SchemaZ,
+  TmuxServerScopeSchemaZ,
+  WorkspaceCatalogResourceV2SchemaZ,
+  WorkspaceMultiplexerIntentSchemaZ,
+  WorkspacePaneCreateArgumentsSchemaZ,
+  type ActionResult,
+  type DesktopApplicationShellTarget,
+  type TerminalRuntimeInventoryProjectionV1,
+  type TmuxServerScope,
+} from "@tmux-ide/contracts";
+import type { TerminalFirstDaemonTransport } from "./direct-application-shell-transport.ts";
+import type { ApplicationShellEventHandlers } from "./application-shell-session.ts";
+import type { PreparedTerminalRuntimeInventory } from "./workspace-event-supervisor.ts";
+import type {
+  WorkspaceClientCatalogPort,
+  WorkspaceClientOwnerActionPort,
+} from "./workspace-client-types.ts";
+import { createTmuxServerClient, type TmuxServerClientOptions } from "./tmux-server-client.ts";
+
+export interface ScopedTmuxServerTransportOptions {
+  readonly clientOptions: TmuxServerClientOptions;
+  readonly scope: TmuxServerScope;
+  readonly target: DesktopApplicationShellTarget;
+  readonly sessionName: string;
+  readonly liveSessionId: string;
+}
+
+function abortable<T>(work: Promise<T>, signal: AbortSignal): Promise<T> {
+  signal.throwIfAborted();
+  return new Promise((resolve, reject) => {
+    const abort = () => reject(signal.reason);
+    signal.addEventListener("abort", abort, { once: true });
+    void work.then(resolve, reject).finally(() => signal.removeEventListener("abort", abort));
+  });
+}
+
+/** One selected incarnation and live session. No endpoint in this adapter can fall back to default. */
+export function createScopedTmuxServerTransport(
+  options: ScopedTmuxServerTransportOptions,
+): TerminalFirstDaemonTransport {
+  const scope = TmuxServerScopeSchemaZ.parse(options.scope);
+  const target = DesktopApplicationShellTargetSchemaZ.parse(options.target);
+  if (target.daemon.instanceId !== scope.generation)
+    throw new Error("Scoped owner generation mismatch");
+  const base = `/api/v1/tmux-servers/${scope.serverId}/${scope.generation}`;
+  const fetcher = options.clientOptions.fetch ?? fetch;
+  const lifetime = new AbortController();
+  let retired = false;
+  let revision = 0;
+  let ready: Promise<void> | null = null;
+  let sink: ((resource: TerminalRuntimeInventoryProjectionV1) => void) | null = null;
+  const handlers = new Set<ApplicationShellEventHandlers>();
+  const catalogListeners = new Set<() => void>();
+  let refreshing = false;
+  let refreshAgain = false;
+  const validateTarget = (input: unknown): DesktopApplicationShellTarget => {
+    const candidate = DesktopApplicationShellTargetSchemaZ.parse(input);
+    if (
+      retired ||
+      candidate.workspaceName !== target.workspaceName ||
+      candidate.daemon.instanceId !== scope.generation ||
+      candidate.daemon.protocolVersion !== target.daemon.protocolVersion ||
+      candidate.daemon.productVersion !== target.daemon.productVersion ||
+      candidate.daemon.startedAt !== target.daemon.startedAt
+    )
+      throw new Error("Retired or mismatched scoped target");
+    return candidate;
+  };
+  const checkEnvelope = (raw: unknown): Record<string, unknown> => {
+    if (
+      !raw ||
+      typeof raw !== "object" ||
+      !("version" in raw) ||
+      raw.version !== 1 ||
+      !("server" in raw)
+    )
+      throw new Error("Invalid scoped response");
+    const candidate = TmuxServerScopeSchemaZ.parse(raw.server);
+    if (
+      retired ||
+      candidate.serverId !== scope.serverId ||
+      candidate.generation !== scope.generation
+    )
+      throw new Error("Scoped response generation mismatch");
+    return raw as Record<string, unknown>;
+  };
+  const url = (path: string) => new URL(`${base}/${path}`, options.clientOptions.baseUrl);
+  const headers = { Authorization: `Bearer ${options.clientOptions.ownerToken}` };
+  const request = async (path: string, signal: AbortSignal) => {
+    validateTarget(target);
+    const response = await fetcher(url(path), {
+      headers,
+      redirect: "error",
+      cache: "no-store",
+      signal: AbortSignal.any([
+        signal,
+        lifetime.signal,
+        AbortSignal.timeout(options.clientOptions.timeoutMs ?? 5000),
+      ]),
+    });
+    if (!response.ok) throw new Error(`Scoped resource unavailable (${response.status})`);
+    return checkEnvelope(await response.json());
+  };
+  const workspacePath = (kind: string) =>
+    `${kind}/${encodeURIComponent(target.workspaceName)}?liveSessionId=${encodeURIComponent(options.liveSessionId)}`;
+  const readInventory = async (signal: AbortSignal) => {
+    const raw = await request(workspacePath("inventory"), signal);
+    const resource = TerminalRuntimeInventoryProjectionV1SchemaZ.parse(raw.resource);
+    if (resource.workspaceName !== target.workspaceName)
+      throw new Error("Scoped workspace mismatch");
+    return resource;
+  };
+  const refresh = () => {
+    if (!sink || retired) return;
+    if (refreshing) {
+      refreshAgain = true;
+      return;
+    }
+    refreshing = true;
+    void (async () => {
+      do {
+        refreshAgain = false;
+        const observed = revision;
+        const resource = await readInventory(lifetime.signal);
+        if (retired) return;
+        if (observed !== revision) {
+          refreshAgain = true;
+          continue;
+        }
+        sink?.({ ...resource, resourceRevision: revision });
+      } while (refreshAgain && !retired);
+    })()
+      .catch((error: unknown) => {
+        if (!retired) for (const listener of handlers) listener.onError(String(error));
+      })
+      .finally(() => {
+        refreshing = false;
+      });
+  };
+  const ensureEvents = (): Promise<void> => {
+    if (ready) return ready;
+    let resolveReady!: () => void;
+    let rejectReady!: (error: unknown) => void;
+    ready = new Promise<void>((resolve, reject) => {
+      resolveReady = resolve;
+      rejectReady = reject;
+    });
+    void ready.catch(() => undefined);
+    const deadline = setTimeout(() => {
+      rejectReady(new Error("Scoped subscription deadline exceeded"));
+      lifetime.abort();
+    }, options.clientOptions.timeoutMs ?? 5000);
+    void ready.then(
+      () => clearTimeout(deadline),
+      () => clearTimeout(deadline),
+    );
+    void (async () => {
+      const response = await fetcher(url(workspacePath("session-events")), {
+        headers,
+        redirect: "error",
+        cache: "no-store",
+        signal: lifetime.signal,
+      });
+      if (!response.ok || !response.body)
+        throw new Error(`Scoped event stream unavailable (${response.status})`);
+      const reader = response.body.getReader();
+      const decoder = new TextDecoder();
+      let buffer = "";
+      let opened = false;
+      try {
+        for (;;) {
+          const next = await reader.read();
+          if (next.done) throw new Error("Scoped event stream closed");
+          buffer += decoder.decode(next.value, { stream: true });
+          if (buffer.length > 65536) throw new Error("Scoped event frame too large");
+          for (;;) {
+            const end = buffer.indexOf("\n\n");
+            if (end < 0) break;
+            const event = buffer.slice(0, end);
+            buffer = buffer.slice(end + 2);
+            const data = event
+              .split("\n")
+              .filter((line) => line.startsWith("data:"))
+              .map((line) => line.slice(5).trimStart())
+              .join("\n");
+            if (!data) continue;
+            const frame = checkEnvelope(JSON.parse(data));
+            if (
+              !Number.isSafeInteger(frame.revision) ||
+              Number(frame.revision) < revision ||
+              !["ready", "invalidate", "heartbeat"].includes(String(frame.type))
+            )
+              throw new Error("Invalid scoped event frame");
+            if (!opened) {
+              if (frame.type !== "ready") throw new Error("Missing scoped subscription barrier");
+              opened = true;
+              revision = Number(frame.revision);
+              resolveReady();
+            } else if (frame.type === "ready")
+              throw new Error("Repeated scoped subscription barrier");
+            if (frame.type === "invalidate") {
+              revision = Number(frame.revision);
+              for (const listener of handlers) listener.onInvalidate();
+              for (const invalidate of catalogListeners) invalidate();
+              refresh();
+            }
+          }
+        }
+      } finally {
+        await reader.cancel().catch(() => undefined);
+        reader.releaseLock();
+      }
+    })().catch((error: unknown) => {
+      rejectReady(error);
+      if (retired) return;
+      retired = true;
+      sink = null;
+      lifetime.abort();
+      for (const listener of handlers) listener.onPeerMismatch(String(error));
+    });
+    return ready;
+  };
+  return {
+    validateTarget,
+    async fetchApplicationShell(candidate, signal) {
+      validateTarget(candidate);
+      await abortable(ensureEvents(), signal);
+      const raw = await request(workspacePath("application-shell"), signal);
+      return ApplicationShellProjectionInputV2SchemaZ.parse(raw.resource);
+    },
+    connectEvents(candidate, listener) {
+      validateTarget(candidate);
+      handlers.add(listener);
+      void ensureEvents().then(
+        () => {
+          if (handlers.has(listener) && !retired) listener.onVerifiedOpen();
+        },
+        () => undefined,
+      );
+      return {
+        close() {
+          handlers.delete(listener);
+        },
+      };
+    },
+    async prepareTerminalRuntimeInventory(candidate, signal) {
+      validateTarget(candidate);
+      await abortable(ensureEvents(), signal);
+      for (let attempt = 0; attempt < 4; attempt++) {
+        signal.throwIfAborted();
+        const observed = revision;
+        const resource = await readInventory(signal);
+        if (observed !== revision) continue;
+        let consumed = false;
+        return {
+          resource,
+          consume() {
+            if (consumed || retired || signal.aborted || observed !== revision) return null;
+            consumed = true;
+            return { ...resource, resourceRevision: revision };
+          },
+          dispose() {
+            consumed = true;
+          },
+        };
+      }
+      throw new Error("Scoped topology changed during preparation");
+    },
+    adoptTerminalRuntimeInventory(prepared: PreparedTerminalRuntimeInventory, onResource) {
+      const resource = prepared.consume();
+      if (resource) sink = onResource;
+      return resource;
+    },
+    refreshTerminalRuntimeInventory: refresh,
+    selectApplicationShellFallback() {
+      sink = null;
+    },
+    disposeEventSupervisor() {
+      retired = true;
+      sink = null;
+      handlers.clear();
+      catalogListeners.clear();
+      lifetime.abort();
+    },
+    connectWorkspaceCatalog(candidate, invalidate) {
+      validateTarget(candidate);
+      catalogListeners.add(invalidate);
+      return {
+        ready: ensureEvents(),
+        close() {
+          catalogListeners.delete(invalidate);
+        },
+      };
+    },
+  };
+}
+
+export function createScopedTmuxServerCatalogPort(
+  options: ScopedTmuxServerTransportOptions,
+  transport: TerminalFirstDaemonTransport,
+): WorkspaceClientCatalogPort {
+  return {
+    async read(target, signal) {
+      transport.validateTarget(target);
+      const barrier = transport.connectWorkspaceCatalog(target, () => undefined);
+      try {
+        await abortable(barrier.ready, signal);
+      } finally {
+        barrier.close();
+      }
+      const { scope, clientOptions } = options;
+      const response = await (clientOptions.fetch ?? fetch)(
+        new URL(
+          `/api/v1/tmux-servers/${scope.serverId}/${scope.generation}/catalog`,
+          clientOptions.baseUrl,
+        ),
+        {
+          headers: { Authorization: `Bearer ${clientOptions.ownerToken}` },
+          redirect: "error",
+          cache: "no-store",
+          signal,
+        },
+      );
+      if (!response.ok) throw new Error(`Scoped catalog unavailable (${response.status})`);
+      const envelope = (await response.json()) as {
+        version: number;
+        server: unknown;
+        resource: object;
+      };
+      const actual = TmuxServerScopeSchemaZ.parse(envelope.server);
+      if (
+        envelope.version !== 1 ||
+        actual.serverId !== scope.serverId ||
+        actual.generation !== scope.generation
+      )
+        throw new Error("Scoped catalog mismatch");
+      transport.validateTarget(target);
+      return WorkspaceCatalogResourceV2SchemaZ.parse({
+        ...envelope.resource,
+        version: 2,
+        daemon: target.daemon,
+      });
+    },
+    subscribe(target, invalidate) {
+      return transport.connectWorkspaceCatalog(target, invalidate);
+    },
+  };
+}
+
+export function createScopedTmuxServerOwnerActions(
+  options: ScopedTmuxServerTransportOptions,
+  transport: TerminalFirstDaemonTransport,
+): WorkspaceClientOwnerActionPort {
+  const client = createTmuxServerClient(options.clientOptions, options.scope);
+  return {
+    async dispatch(request) {
+      transport.validateTarget(request.target);
+      if (request.name === "workspace.pane.create") {
+        const intent = WorkspacePaneCreateArgumentsSchemaZ.parse(request.input);
+        if (intent.workspaceName !== options.target.workspaceName)
+          throw new Error("Scoped action workspace mismatch");
+        const result = await client.createPane(request.operationId, intent, options.liveSessionId);
+        transport.validateTarget(request.target);
+        transport.refreshTerminalRuntimeInventory();
+        return result as ActionResult<typeof request.name>;
+      }
+      const intent = WorkspaceMultiplexerIntentSchemaZ.parse({
+        ...request.input,
+        verb: request.name,
+      });
+      if (intent.workspaceName !== options.target.workspaceName)
+        throw new Error("Scoped action workspace mismatch");
+      const result = await client.mutate(request.operationId, intent, options.liveSessionId);
+      transport.validateTarget(request.target);
+      transport.refreshTerminalRuntimeInventory();
+      return ActionContractsZ[request.name].result.parse(result) as ActionResult<
+        typeof request.name
+      >;
+    },
+  };
+}

package/packages/daemon-client/src/tmux-server-client.test.ts

@@ -0,0 +1,279 @@
+import { describe, expect, it, mock } from "bun:test";
+import {
+  PANE_STREAM_PROTOCOL_VERSION,
+  PANE_STREAM_REDEEM_PATH,
+  PANE_STREAM_WEBSOCKET_SUBPROTOCOL,
+  tmuxServerPaneStreamPath,
+} from "@tmux-ide/contracts";
+import {
+  createTmuxServerClient,
+  listTmuxServers,
+  registerTmuxServer,
+  removeTmuxServer,
+} from "./tmux-server-client.ts";
+const scope = {
+  serverId: `tmux-server.${"a".repeat(32)}`,
+  generation: "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
+};
+const other = { ...scope, serverId: `tmux-server.${"b".repeat(32)}` };
+const requestId = "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb";
+const base = {
+  baseUrl: "http://127.0.0.1:4000",
+  ownerToken: "owner",
+  hostClientId: "client",
+  origin: "http://localhost:3000",
+};
+const sessions = (server = scope) => ({
+  version: 1,
+  server,
+  sessions: [
+    {
+      liveSessionId: `live-session.${"a".repeat(20)}`,
+      sessionName: "main",
+      workspaceName: "alias",
+      paneCount: 1,
+    },
+  ],
+});
+const stream = {
+  protocolVersion: PANE_STREAM_PROTOCOL_VERSION,
+  workspaceName: "main",
+  panes: ["pane.one"],
+  viewerMode: "interactive" as const,
+};
+const issued = () => ({
+  status: "issued",
+  descriptor: {
+    protocolVersion: PANE_STREAM_PROTOCOL_VERSION,
+    webSocketUrl: `ws://127.0.0.1:4000${tmuxServerPaneStreamPath(scope)}`,
+    subprotocol: PANE_STREAM_WEBSOCKET_SUBPROTOCOL,
+    redemptionTicket: `ps2_${"a".repeat(43)}`,
+    daemonInstanceId: scope.generation,
+    requestId,
+    expiresAt: Date.now() + 10000,
+    panes: ["pane.one"],
+    effectiveViewerMode: "interactive",
+  },
+});
+
+describe("explicit tmux server SDK client", () => {
+  it("validates versioned server listing without fallback", async () => {
+    const fetcher = mock(async (url: string | URL | Request, init?: RequestInit) => {
+      expect(String(url)).toBe(`${base.baseUrl}/api/v1/tmux-servers`);
+      expect(init?.headers).toMatchObject({ Authorization: "Bearer owner" });
+      return Response.json({
+        version: 1,
+        servers: [{ ...scope, state: "online", label: "default" }],
+      });
+    });
+    expect(
+      (await listTmuxServers({ ...base, fetch: fetcher as typeof fetch })).servers,
+    ).toHaveLength(1);
+    await expect(
+      listTmuxServers({
+        ...base,
+        fetch: mock(async () => Response.json({ version: 2, servers: [] })) as typeof fetch,
+      }),
+    ).rejects.toThrow();
+  });
+
+  it("binds copied inputs and cache keys to an immutable exact scope", async () => {
+    const input = { ...scope };
+    const fetcher = mock(async (url: string | URL | Request) => {
+      expect(String(url)).toContain(`/${scope.serverId}/${scope.generation}/sessions`);
+      return Response.json(sessions());
+    });
+    const client = createTmuxServerClient({ ...base, fetch: fetcher as typeof fetch }, input);
+    input.serverId = other.serverId;
+    expect((await client.sessions()).server).toEqual(scope);
+    expect(Object.isFrozen(client.scope)).toBe(true);
+    expect(client.cacheKey("pane", "%0")).not.toBe(
+      createTmuxServerClient(base, other).cacheKey("pane", "%0"),
+    );
+  });
+
+  it("rejects scope mismatches and stale HTTP refusal without retries", async () => {
+    const fetcher = mock(async () => Response.json(sessions(other)));
+    await expect(
+      createTmuxServerClient({ ...base, fetch: fetcher as typeof fetch }, scope).sessions(),
+    ).rejects.toMatchObject({ code: "scope-mismatch" });
+    const refused = mock(async () =>
+      Response.json({ error: { code: "stale-generation" } }, { status: 409 }),
+    );
+    await expect(
+      createTmuxServerClient({ ...base, fetch: refused as typeof fetch }, scope).sessions(),
+    ).rejects.toMatchObject({ status: 409 });
+    expect(refused).toHaveBeenCalledTimes(1);
+  });
+
+  it("drops an old selection's late response after disposal", async () => {
+    let resolve!: (response: Response) => void;
+    const pending = new Promise<Response>((done) => {
+      resolve = done;
+    });
+    const fetcher = mock(async () => pending);
+    const client = createTmuxServerClient({ ...base, fetch: fetcher as typeof fetch }, scope);
+    const result = client.sessions();
+    client.dispose();
+    resolve(Response.json(sessions()));
+    await expect(result).rejects.toMatchObject({ code: "disposed" });
+    await expect(client.sessions()).rejects.toMatchObject({ code: "disposed" });
+    expect(fetcher).toHaveBeenCalledTimes(1);
+  });
+
+  it("uses explicit owner authority for passive fleet close without a controller principal", async () => {
+    const fetcher = mock(async (_url: RequestInfo | URL, init?: RequestInit) => {
+      expect(new Headers(init?.headers).has("X-Tmux-Ide-Host-Client-Id")).toBe(false);
+      expect(new Headers(init?.headers).get("Authorization")).toBe("Bearer owner");
+      return Response.json({
+        operationId: requestId,
+        daemonInstanceId: scope.generation,
+        workspaceName: "same",
+        verb: "workspace.session.kill",
+        outcome: "applied",
+      });
+    });
+    await createTmuxServerClient({ ...base, fetch: fetcher as typeof fetch }, scope).mutate(
+      requestId,
+      {
+        verb: "workspace.session.kill",
+        workspaceName: "same",
+        fleetTarget: {
+          daemonInstanceId: scope.generation,
+          liveSessionId: `live-session.${"a".repeat(20)}`,
+          sessionName: "same",
+        },
+      },
+    );
+    expect(fetcher).toHaveBeenCalledTimes(1);
+  });
+
+  it("sends owner-scoped mutations and verifies generation and operation echoes", async () => {
+    const fetcher = mock(async (_url: string | URL | Request, init?: RequestInit) => {
+      const body = JSON.parse(String(init?.body));
+      expect(body.expectedDaemonInstanceId).toBe(scope.generation);
+      return Response.json({
+        operationId: body.operationId,
+        daemonInstanceId: scope.generation,
+        outcome: "applied",
+        workspaceName: "main",
+        verb: "workspace.pane.select",
+        semanticPaneId: "pane.one",
+      });
+    });
+    const client = createTmuxServerClient({ ...base, fetch: fetcher as typeof fetch }, scope);
+    const result = await client.mutate(requestId, {
+      verb: "workspace.pane.select",
+      workspaceName: "main",
+      semanticPaneId: "pane.one",
+    });
+    expect(result.daemonInstanceId).toBe(scope.generation);
+  });
+
+  it("sends exact issue headers and validates scoped redemption", async () => {
+    const fetcher = mock(async (url: string | URL | Request, init?: RequestInit) => {
+      expect(String(url)).toEndWith(`/${scope.serverId}/${scope.generation}/pane-streams/issue`);
+      expect(init?.headers).toMatchObject({
+        Authorization: "Bearer owner",
+        Origin: base.origin,
+        "X-Tmux-Ide-Request-Id": requestId,
+        "X-Tmux-Ide-Expected-Daemon-Instance-Id": scope.generation,
+        "X-Tmux-Ide-Host-Client-Id": "client",
+      });
+      return Response.json(issued());
+    });
+    expect(
+      (
+        await createTmuxServerClient(
+          { ...base, fetch: fetcher as typeof fetch },
+          scope,
+        ).issuePaneStream(requestId, stream)
+      ).status,
+    ).toBe("issued");
+    const wrong = issued();
+    wrong.descriptor.webSocketUrl = `ws://127.0.0.1:4000${tmuxServerPaneStreamPath(other)}`;
+    await expect(
+      createTmuxServerClient(
+        { ...base, fetch: mock(async () => Response.json(wrong)) as typeof fetch },
+        scope,
+      ).issuePaneStream(requestId, stream),
+    ).rejects.toMatchObject({ code: "scope-mismatch" });
+  });
+
+  it("rejects inventories from the wrong workspace", async () => {
+    const fetcher = mock(async () =>
+      Response.json({
+        version: 1,
+        server: scope,
+        resource: {
+          workspaceName: "other",
+          workspaceId: "workspace.0123456789abcdefabcd",
+          sessionId: "session.0123456789abcdefabcd",
+          resourceRevision: 0,
+          semanticPaneIds: ["pane.one"],
+        },
+      }),
+    );
+    await expect(
+      createTmuxServerClient({ ...base, fetch: fetcher as typeof fetch }, scope).inventory("main"),
+    ).rejects.toMatchObject({ code: "scope-mismatch" });
+  });
+});
+
+describe("server registration and adopted default", () => {
+  it("passes remote selector intent unchanged and removes by opaque registration", async () => {
+    const calls: Array<{ url: string; init?: RequestInit }> = [];
+    const fetcher = mock(async (url: string | URL | Request, init?: RequestInit) => {
+      calls.push({ url: String(url), init });
+      return Response.json(
+        init?.method === "DELETE"
+          ? { removed: true }
+          : { ...scope, label: "remote", state: "online" },
+      );
+    });
+    const options = { ...base, fetch: fetcher as typeof fetch };
+    await registerTmuxServer(options, {
+      label: "remote",
+      selector: { kind: "path", path: "/remote/socket" },
+    });
+    expect(JSON.parse(String(calls[0]?.init?.body)).selector).toEqual({
+      kind: "path",
+      path: "/remote/socket",
+    });
+    await removeTmuxServer(options, scope.serverId);
+    expect(calls[1]?.init?.method).toBe("DELETE");
+    expect(calls[1]?.url).toEndWith(`/${scope.serverId}`);
+    await expect(removeTmuxServer(options, "../default")).rejects.toThrow();
+    expect(fetcher).toHaveBeenCalledTimes(2);
+  });
+
+  it("accepts default redemption only with an exact generation and request echo", async () => {
+    const response = issued();
+    response.descriptor.webSocketUrl = `ws://127.0.0.1:4000${PANE_STREAM_REDEEM_PATH}`;
+    const fetcher = mock(async () => Response.json(response));
+    const client = createTmuxServerClient({ ...base, fetch: fetcher as typeof fetch }, scope);
+    expect((await client.issuePaneStream(requestId, stream)).status).toBe("issued");
+    response.descriptor.daemonInstanceId = requestId;
+    await expect(client.issuePaneStream(requestId, stream)).rejects.toMatchObject({
+      code: "scope-mismatch",
+    });
+  });
+
+  it("preserves authoritative workspace aliases and unavailable collisions", async () => {
+    const response = sessions();
+    const client = createTmuxServerClient(
+      { ...base, fetch: mock(async () => Response.json(response)) as typeof fetch },
+      scope,
+    );
+    expect((await client.sessions()).sessions[0]?.workspaceName).toBe("alias");
+    const unavailable = {
+      ...response,
+      sessions: response.sessions.map((session) => ({ ...session, workspaceName: null })),
+    };
+    const otherClient = createTmuxServerClient(
+      { ...base, fetch: mock(async () => Response.json(unavailable)) as typeof fetch },
+      scope,
+    );
+    expect((await otherClient.sessions()).sessions[0]?.workspaceName).toBeNull();
+  });
+});