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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tmux-ide",
-  "version": "2.9.0-beta.21",
+  "version": "2.9.0-beta.26",
   "description": "A visual, agent-aware IDE for any tmux session, with optional workspace presets",
   "type": "module",
   "bin": {
@@ -64,7 +64,7 @@
     "postinstall": "node scripts/postinstall.js",
     "docs": "turbo run dev --filter=@tmux-ide/docs",
     "demo:tui": "bun --preload @opentui/solid/preload docs/scripts/render-tui-demo.tsx",
-    "test:tui-renderer": "bun test --preload @opentui/solid/preload --preload ./packages/daemon/test-support/opentui-renderer-preload.ts ./packages/daemon/src/tui/mirror/automatic-contrast-renderer.test.tsx ./packages/daemon/src/tui/mirror/pane-surface-renderer.test.tsx ./packages/daemon/src/tui/mirror/native-grid-projection-renderer.test.tsx ./packages/daemon/src/tui/mirror/widget-surface-renderer.test.tsx ./packages/daemon/src/tui/mirror/missions-surface-renderer.test.tsx ./packages/daemon/src/tui/mirror/recipes-gallery-renderer.test.tsx ./packages/daemon/src/tui/mirror/shell-chrome-renderer.test.tsx ./packages/daemon/src/tui/mirror/sidebar-renderer.test.tsx ./packages/daemon/src/tui/mirror/home-files-surface-renderer.test.tsx ./packages/daemon/src/tui/mirror/changes-terminal-surface-renderer.test.tsx ./packages/daemon/src/tui/mirror/activity-surface-renderer.test.tsx ./packages/daemon/src/tui/mirror/features/files/session-renderer.test.tsx ./packages/daemon/src/tui/mirror/runtime/application-terminal-workspace-renderer.test.tsx ./packages/daemon/src/tui/mirror/runtime/application-shell-view-renderer.test.tsx ./packages/daemon/src/tui/mirror/runtime/application-root-error-renderer.test.tsx ./packages/daemon/src/tui/mirror/runtime/application-backpressure-renderer.test.tsx ./packages/daemon/src/tui/mirror/runtime/application-demand-cadence-renderer.test.tsx ./packages/daemon/src/tui/mirror/runtime/files-optional-feature-renderer.test.tsx ./packages/daemon/src/tui/mirror/runtime/changes-optional-feature-renderer.test.tsx ./packages/daemon/src/tui/mirror/runtime/missions-activity-optional-feature-renderer.test.tsx ./packages/daemon/src/tui/mirror/runtime/dialogs-optional-feature-renderer.test.tsx ./packages/daemon/src/tui/mirror/runtime/optional-feature-registry-renderer.test.tsx ./packages/daemon/src/tui/mirror/runtime/palette-optional-feature-renderer.test.tsx ./packages/daemon/src/tui/mirror/runtime/pane-scoped-terminal-surface-renderer.test.tsx ./packages/daemon/src/tui/mirror/features/rich-preview/feature.test.ts ./packages/daemon/src/tui/mirror/runtime/rich-preview-optional-feature-renderer.test.tsx ./packages/daemon/src/tui/mirror/workspace/application-shell-renderer.test.tsx ./packages/daemon/src/tui/mirror/workspace/pane-frame-renderer.test.tsx ./packages/daemon/src/tui/mirror/workspace/terminal-pane-chrome-view.test.tsx ./packages/daemon/src/tui/mirror/workspace/terminal-window-strip-renderer.test.tsx ./packages/daemon/src/tui/mirror/workspace/workbench-shell-renderer.test.tsx ./packages/daemon/src/tui/mirror/workspace/workbench-dock-dual-host-renderer.test.tsx ./packages/daemon/src/tui/mirror/workspace/agent-terminal-canvas-renderer.test.tsx ./packages/daemon/src/tui/mirror/workspace/command-palette-surface-renderer.test.tsx ./packages/daemon/src/tui/mirror/workspace/opentui-insertion-stability-renderer.test.tsx ./packages/daemon/src/tui/mirror/runtime/application-shell-home-renderer.test.tsx ./packages/daemon/src/tui/mirror/workspace/terminal-pane-header-polish-renderer.test.tsx ./packages/daemon/src/tui/mirror/runtime/application-home-agent-roster-renderer.test.tsx ./packages/daemon/src/tui/mirror/runtime/application-home-agent-flow-renderer.test.tsx ./packages/daemon/src/tui/mirror/runtime/application-shell-sidebar-catalog-renderer.test.tsx ./packages/daemon/src/tui/mirror/ui/ui-renderer.test.tsx ./packages/daemon/src/tui/mirror/runtime/application-machine-sidebar-renderer.test.tsx ./packages/daemon/src/tui/mirror/runtime/application-add-machine-dialog-renderer.test.tsx ./packages/daemon/src/tui/mirror/runtime/application-fleet-switcher-renderer.test.tsx ./packages/daemon/src/tui/mirror/runtime/application-palette-preview-renderer.test.tsx ./packages/daemon/src/tui/mirror/runtime/application-fleet-palette-renderer.test.tsx ./packages/daemon/src/tui/mirror/runtime/application-fleet-session-actions-renderer.test.tsx",
+    "test:tui-renderer": "bun test --preload @opentui/solid/preload --preload ./packages/daemon/test-support/opentui-renderer-preload.ts ./packages/daemon/src/tui/mirror/automatic-contrast-renderer.test.tsx ./packages/daemon/src/tui/mirror/pane-surface-renderer.test.tsx ./packages/daemon/src/tui/mirror/native-grid-projection-renderer.test.tsx ./packages/daemon/src/tui/mirror/widget-surface-renderer.test.tsx ./packages/daemon/src/tui/mirror/missions-surface-renderer.test.tsx ./packages/daemon/src/tui/mirror/recipes-gallery-renderer.test.tsx ./packages/daemon/src/tui/mirror/shell-chrome-renderer.test.tsx ./packages/daemon/src/tui/mirror/sidebar-renderer.test.tsx ./packages/daemon/src/tui/mirror/home-files-surface-renderer.test.tsx ./packages/daemon/src/tui/mirror/changes-terminal-surface-renderer.test.tsx ./packages/daemon/src/tui/mirror/activity-surface-renderer.test.tsx ./packages/daemon/src/tui/mirror/features/files/session-renderer.test.tsx ./packages/daemon/src/tui/mirror/runtime/application-terminal-workspace-renderer.test.tsx ./packages/daemon/src/tui/mirror/runtime/application-shell-view-renderer.test.tsx ./packages/daemon/src/tui/mirror/runtime/application-root-error-renderer.test.tsx ./packages/daemon/src/tui/mirror/runtime/application-backpressure-renderer.test.tsx ./packages/daemon/src/tui/mirror/runtime/application-demand-cadence-renderer.test.tsx ./packages/daemon/src/tui/mirror/runtime/files-optional-feature-renderer.test.tsx ./packages/daemon/src/tui/mirror/runtime/changes-optional-feature-renderer.test.tsx ./packages/daemon/src/tui/mirror/runtime/missions-activity-optional-feature-renderer.test.tsx ./packages/daemon/src/tui/mirror/runtime/dialogs-optional-feature-renderer.test.tsx ./packages/daemon/src/tui/mirror/runtime/optional-feature-registry-renderer.test.tsx ./packages/daemon/src/tui/mirror/runtime/palette-optional-feature-renderer.test.tsx ./packages/daemon/src/tui/mirror/runtime/pane-scoped-terminal-surface-renderer.test.tsx ./packages/daemon/src/tui/mirror/features/rich-preview/feature.test.ts ./packages/daemon/src/tui/mirror/runtime/rich-preview-optional-feature-renderer.test.tsx ./packages/daemon/src/tui/mirror/workspace/application-shell-renderer.test.tsx ./packages/daemon/src/tui/mirror/workspace/pane-frame-renderer.test.tsx ./packages/daemon/src/tui/mirror/workspace/terminal-pane-chrome-view.test.tsx ./packages/daemon/src/tui/mirror/workspace/terminal-window-strip-renderer.test.tsx ./packages/daemon/src/tui/mirror/workspace/workbench-shell-renderer.test.tsx ./packages/daemon/src/tui/mirror/workspace/workbench-dock-dual-host-renderer.test.tsx ./packages/daemon/src/tui/mirror/workspace/agent-terminal-canvas-renderer.test.tsx ./packages/daemon/src/tui/mirror/workspace/command-palette-surface-renderer.test.tsx ./packages/daemon/src/tui/mirror/workspace/opentui-insertion-stability-renderer.test.tsx ./packages/daemon/src/tui/mirror/runtime/application-shell-home-renderer.test.tsx ./packages/daemon/src/tui/mirror/workspace/terminal-pane-header-polish-renderer.test.tsx ./packages/daemon/src/tui/mirror/runtime/application-home-agent-roster-renderer.test.tsx ./packages/daemon/src/tui/mirror/runtime/application-home-agent-flow-renderer.test.tsx ./packages/daemon/src/tui/mirror/runtime/guided-tour-renderer.test.tsx ./packages/daemon/src/tui/mirror/runtime/application-shell-sidebar-catalog-renderer.test.tsx ./packages/daemon/src/tui/mirror/ui/ui-renderer.test.tsx ./packages/daemon/src/tui/mirror/runtime/application-machine-sidebar-renderer.test.tsx ./packages/daemon/src/tui/mirror/runtime/application-add-machine-dialog-renderer.test.tsx ./packages/daemon/src/tui/mirror/runtime/application-fleet-switcher-renderer.test.tsx ./packages/daemon/src/tui/mirror/runtime/application-palette-preview-renderer.test.tsx ./packages/daemon/src/tui/mirror/runtime/application-fleet-palette-renderer.test.tsx ./packages/daemon/src/tui/mirror/runtime/application-fleet-session-actions-renderer.test.tsx",
     "test:tui-smoke": "bun scripts/smoke-tui-missions.mjs",
     "test:tui-live": "node scripts/tui-testdrive.mjs smoke",
     "test:tui-testdrive": "node --test scripts/lib/tui-testdrive-clipboard-hook.test.mjs scripts/lib/tui-testdrive-input.test.mjs",

package/packages/contracts/src/__tests__/daemon-wire.test.ts

@@ -13,10 +13,10 @@ import {
 } from "../daemon-wire.ts";
 import { WorkspaceCatalogResourceV1SchemaZ } from "../workspace-catalog-resource.ts";
 
-const fixturePath = fileURLToPath(new URL("./fixtures/daemon-wire-v2.json", import.meta.url));
+const fixturePath = fileURLToPath(new URL("./fixtures/daemon-wire-v3.json", import.meta.url));
 
 describe("daemon wire protocol", () => {
-  it("validates the shared desktop/TypeScript v2 fixture", () => {
+  it("validates the shared desktop/TypeScript v3 fixture", () => {
     const fixture = JSON.parse(readFileSync(fixturePath, "utf8")) as Record<string, unknown>;
 
     expect(CanonicalDaemonInfoSchema.parse(fixture.canonical).protocolVersion).toBe(

package/packages/contracts/src/__tests__/fixtures/daemon-wire-v3.json

@@ -0,0 +1,35 @@
+{
+  "canonical": {
+    "pid": 4312,
+    "port": 4010,
+    "protocolVersion": 3,
+    "productVersion": "0.0.1",
+    "instanceId": "9bcf33b0-c837-4a94-b5e8-c0977f54464f",
+    "startedAt": "2026-07-20T12:34:56.123Z",
+    "bindHostname": "127.0.0.1",
+    "authToken": "fixture-token"
+  },
+  "health": {
+    "ok": true,
+    "protocolVersion": 3,
+    "productVersion": "0.0.1",
+    "uptime": 42
+  },
+  "healthz": {
+    "ok": true,
+    "protocolVersion": 3,
+    "productVersion": "0.0.1",
+    "uptimeMs": 42000
+  },
+  "identity": {
+    "ok": true,
+    "pid": 4312,
+    "protocolVersion": 3,
+    "productVersion": "0.0.1",
+    "instanceId": "9bcf33b0-c837-4a94-b5e8-c0977f54464f",
+    "startedAt": "2026-07-20T12:34:56.123Z"
+  },
+  "sessions": {
+    "sessions": [{ "name": "fixture-project", "dir": "/work/fixture-project" }]
+  }
+}

package/packages/contracts/src/__tests__/issue-error.test.ts

@@ -65,7 +65,7 @@ describe("the shared issue-error vocabulary", () => {
     for (const reason of [
       "Authorization was Bearer owner-secret",
       `The redemptionTicket was ta1_${"A".repeat(43)}`,
-      `The redemptionTicket was ps1_${"A".repeat(43)}`,
+      `The redemptionTicket was ps2_${"A".repeat(43)}`,
       "ownerToken=secret",
     ]) {
       for (const schema of [TerminalAttachmentIssueErrorSchemaZ, PaneStreamIssueErrorSchemaZ]) {

package/packages/contracts/src/__tests__/multiplexer-verbs.test.ts

@@ -22,6 +22,8 @@ const verb = (id: string): MultiplexerVerbEntry => {
 describe("the multiplexer verb table", () => {
   it("carries every verb the milestone declares, and no others", () => {
     expect([...MULTIPLEXER_VERB_IDS]).toEqual([
+      "window.link.select",
+      "window.link.unlink",
       "session.new",
       "session.kill",
       "session.rename",
@@ -80,7 +82,7 @@ describe("the multiplexer verb table", () => {
     const destructive = MULTIPLEXER_VERB_TABLE.filter((entry) => entry.destructive).map(
       (entry) => entry.id,
     );
-    expect(destructive).toEqual(["session.kill", "window.kill", "pane.kill"]);
+    expect(destructive).toEqual(["window.link.unlink", "session.kill", "window.kill", "pane.kill"]);
   });
 
   it("leaves every tmux key hint unfilled until the keybinding bridge exists", () => {

package/packages/contracts/src/__tests__/pane-stream.test.ts

@@ -25,7 +25,7 @@ import {
   PaneStreamServerFrameSchemaZ,
 } from "../pane-stream.ts";
 
-const TICKET = `ps1_${"A".repeat(43)}`;
+const TICKET = `ps2_${"A".repeat(43)}`;
 const REQUEST_ID = "7f0f9a7e-9be0-4b6e-a3a3-0a15c9a7e0d1";
 const INSTANCE_ID = "3d3f8a52-77aa-4b3e-9a44-2f2f7b1c9d10";
 const WS_URL = `ws://127.0.0.1:6070${PANE_STREAM_REDEEM_PATH}`;
@@ -55,9 +55,9 @@ function descriptor() {
 
 describe("pane-stream lease contracts", () => {
   it("publishes one shared issue and redemption endpoint authority", () => {
-    expect(PANE_STREAM_ISSUE_PATH).toBe("/api/v1/terminal/pane-streams/issue");
-    expect(PANE_STREAM_REDEEM_PATH).toBe("/v1/terminal/pane-streams/redeem");
-    expect(PANE_STREAM_WEBSOCKET_SUBPROTOCOL).toBe("tmux-ide-pane-stream.v1");
+    expect(PANE_STREAM_ISSUE_PATH).toBe("/api/v2/terminal/pane-streams/issue");
+    expect(PANE_STREAM_REDEEM_PATH).toBe("/v2/terminal/pane-streams/redeem");
+    expect(PANE_STREAM_WEBSOCKET_SUBPROTOCOL).toBe("tmux-ide-pane-stream.v2");
   });
 
   it("accepts a viewport-free enumerated pane set", () => {
@@ -115,7 +115,7 @@ describe("pane-stream lease contracts", () => {
 
   it("accepts only ps1 tickets", () => {
     expect(PaneStreamRedemptionTicketSchemaZ.safeParse(TICKET).success).toBe(true);
-    for (const invalid of [`ta1_${"A".repeat(43)}`, `ps1_${"A".repeat(42)}`, "ps1_", "ps1"]) {
+    for (const invalid of [`ta1_${"A".repeat(43)}`, `ps2_${"A".repeat(42)}`, "ps2_", "ps1"]) {
       expect(PaneStreamRedemptionTicketSchemaZ.safeParse(invalid).success).toBe(false);
     }
   });
@@ -184,6 +184,18 @@ describe("pane-stream lease contracts", () => {
       type: "layout-snapshot" as const,
       topologyEpoch: 1,
       layouts: [layout("window.one", "pane.editor", true)],
+      windowLinks: {
+        liveSessionId: `live-session.${"a".repeat(20)}`,
+        linkRevision: 1,
+        activeLinkId: `window-link.${"a".repeat(32)}`,
+        links: [
+          {
+            linkId: `window-link.${"a".repeat(32)}`,
+            semanticWindowId: "window.one",
+            displayIndex: 0,
+          },
+        ],
+      },
     };
     expect(PaneStreamServerFrameSchemaZ.safeParse(snapshot).success).toBe(true);
     for (const layouts of [

package/packages/contracts/src/__tests__/tmux-server-scope.test.ts

@@ -0,0 +1,166 @@
+import { describe, expect, it } from "vitest";
+import {
+  TmuxServerScopeSchemaZ,
+  tmuxServerPaneStreamPath,
+  isTmuxServerPaneStreamPath,
+  TmuxServerDescriptorSchemaZ,
+  TmuxServersResourceSchemaZ,
+  TmuxServerPaneTargetSchemaZ,
+  resolveTmuxServerScope,
+  tmuxServerScopedResourceKey,
+  type TmuxServerScope,
+  type TmuxServerDescriptor,
+} from "../tmux-server-scope.ts";
+
+import { PaneStreamLoopbackWebSocketUrlSchemaZ, PANE_STREAM_REDEEM_PATH } from "../pane-stream.ts";
+
+const a: TmuxServerScope = {
+  serverId: `tmux-server.${"a".repeat(32)}`,
+  generation: "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
+};
+const b: TmuxServerScope = { ...a, serverId: `tmux-server.${"b".repeat(32)}` };
+const replacement: TmuxServerScope = { ...a, generation: "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb" };
+const online = (scope: TmuxServerScope): TmuxServerDescriptor => ({
+  ...scope,
+  label: "default",
+  state: "online",
+});
+const offline = (scope: TmuxServerScope): TmuxServerDescriptor => ({
+  serverId: scope.serverId,
+  label: "default",
+  state: "offline",
+  generation: null,
+});
+
+describe("server-scoped identities", () => {
+  it("keeps registration identity separate from each live incarnation", () => {
+    expect(TmuxServerScopeSchemaZ.parse(a)).toEqual(a);
+    expect(TmuxServerScopeSchemaZ.parse(replacement).serverId).toBe(a.serverId);
+    for (const serverId of ["/tmp/tmux/socket", "default", "%0", "tmux-server.short"]) {
+      expect(TmuxServerScopeSchemaZ.safeParse({ ...a, serverId }).success).toBe(false);
+    }
+    expect(TmuxServerScopeSchemaZ.safeParse({ ...a, socketPath: "/tmp/socket" }).success).toBe(
+      false,
+    );
+    expect(TmuxServerScopeSchemaZ.safeParse({ ...a, generation: "1234" }).success).toBe(false);
+  });
+
+  it("publishes no live generation for offline registrations", () => {
+    expect(TmuxServerDescriptorSchemaZ.parse(online(a))).toEqual(online(a));
+    expect(TmuxServerDescriptorSchemaZ.parse(offline(a))).toEqual(offline(a));
+    expect(TmuxServerDescriptorSchemaZ.safeParse({ ...online(a), generation: null }).success).toBe(
+      false,
+    );
+    expect(
+      TmuxServerDescriptorSchemaZ.safeParse({ ...offline(a), generation: a.generation }).success,
+    ).toBe(false);
+  });
+
+  it("versions the new resource explicitly and refuses duplicate registrations", () => {
+    expect(
+      TmuxServersResourceSchemaZ.safeParse({ version: 1, servers: [online(a), online(b)] }).success,
+    ).toBe(true);
+    expect(TmuxServersResourceSchemaZ.safeParse({ version: 2, servers: [] }).success).toBe(false);
+    expect(
+      TmuxServersResourceSchemaZ.safeParse({ version: 1, servers: [online(a), offline(a)] })
+        .success,
+    ).toBe(false);
+  });
+
+  it("requires complete server scope for copied pane stamps", () => {
+    const target = {
+      server: a,
+      liveSessionId: `live-session.${"a".repeat(20)}`,
+      semanticPaneId: "pane.copied",
+    };
+    expect(TmuxServerPaneTargetSchemaZ.safeParse(target).success).toBe(true);
+    expect(TmuxServerPaneTargetSchemaZ.safeParse({ ...target, server: undefined }).success).toBe(
+      false,
+    );
+    expect(TmuxServerPaneTargetSchemaZ.safeParse({ ...target, runtimePaneId: "%0" }).success).toBe(
+      false,
+    );
+  });
+
+  it("keys copied stamps, native IDs and generations without delimiter collisions", () => {
+    const keys = [
+      tmuxServerScopedResourceKey(a, "pane", "copied"),
+      tmuxServerScopedResourceKey(b, "pane", "copied"),
+      tmuxServerScopedResourceKey(replacement, "pane", "copied"),
+      tmuxServerScopedResourceKey(a, "window", "copied"),
+      tmuxServerScopedResourceKey(a, "pane:copied", ""),
+      tmuxServerScopedResourceKey(a, "pane", ":copied"),
+    ];
+    expect(new Set(keys).size).toBe(keys.length);
+    expect(tmuxServerScopedResourceKey(a, "pane", "%0")).not.toBe(
+      tmuxServerScopedResourceKey(b, "pane", "%0"),
+    );
+  });
+});
+
+describe("server selection authority", () => {
+  it("routes exact scope despite identical display labels", () => {
+    expect(resolveTmuxServerScope([online(a), online(b)], b)).toEqual({
+      status: "matched",
+      scope: b,
+    });
+  });
+
+  it("rejects old generations without falling back to another live server", () => {
+    expect(resolveTmuxServerScope([online(replacement), online(b)], a)).toEqual({
+      status: "stale-generation",
+    });
+    expect(resolveTmuxServerScope([online(b)], a)).toEqual({ status: "not-found" });
+    expect(resolveTmuxServerScope([offline(a), online(b)], a)).toEqual({ status: "offline" });
+  });
+
+  it("allows legacy selection only with one registered live owner", () => {
+    expect(resolveTmuxServerScope([online(a)])).toEqual({ status: "matched", scope: a });
+    expect(resolveTmuxServerScope([])).toEqual({ status: "not-found" });
+    expect(resolveTmuxServerScope([offline(a)])).toEqual({ status: "offline" });
+    expect(resolveTmuxServerScope([online(a), online(b)])).toEqual({ status: "ambiguous" });
+    expect(resolveTmuxServerScope([offline(a), online(b)])).toEqual({ status: "ambiguous" });
+  });
+
+  it("fails closed if malformed registry repeats an identity", () => {
+    expect(resolveTmuxServerScope([online(a), online(a)], a)).toEqual({ status: "ambiguous" });
+  });
+});
+
+describe("server-scoped pane stream addresses", () => {
+  it("separates owners and generations and accepts canonical loopback URLs", () => {
+    const paths = [a, b, replacement].map(tmuxServerPaneStreamPath);
+    expect(new Set(paths).size).toBe(3);
+    for (const path of [...paths, PANE_STREAM_REDEEM_PATH]) {
+      expect(
+        PaneStreamLoopbackWebSocketUrlSchemaZ.safeParse(`ws://127.0.0.1:1234${path}`).success,
+      ).toBe(true);
+    }
+  });
+
+  it("refuses unscoped, malformed, encoded and credentialed paths", () => {
+    const path = tmuxServerPaneStreamPath(a);
+    for (const badPath of [
+      path + "/",
+      path + "/other",
+      path.replace(a.serverId, "default"),
+      path.replace(a.generation, "old"),
+      path.replace("tmux-server.", "tmux-server%2e"),
+      "/v2/tmux-servers/pane-streams/redeem",
+    ]) {
+      expect(isTmuxServerPaneStreamPath(badPath)).toBe(false);
+      expect(
+        PaneStreamLoopbackWebSocketUrlSchemaZ.safeParse(`ws://127.0.0.1:1234${badPath}`).success,
+      ).toBe(false);
+    }
+    for (const url of [
+      `ws://127.0.0.1:1234${path}?generation=${b.generation}`,
+      `ws://127.0.0.1:1234${path}#fragment`,
+      `ws://user@127.0.0.1:1234${path}`,
+      `ws://example.com:1234${path}`,
+      `wss://127.0.0.1:1234${path}`,
+      `ws://127.0.0.1${path}`,
+    ])
+      expect(PaneStreamLoopbackWebSocketUrlSchemaZ.safeParse(url).success).toBe(false);
+  });
+});

package/packages/contracts/src/__tests__/window-links.test.ts

@@ -0,0 +1,243 @@
+import {
+  WorkspaceWindowLinkSelectArgumentsSchemaZ,
+  WorkspaceWindowLinkUnlinkArgumentsSchemaZ,
+  WorkspacePaneSelectWithWindowLinkArgumentsSchemaZ,
+  WorkspacePaneSelectArgumentsSchemaZ,
+  WorkspaceMultiplexerIntentSchemaZ,
+} from "../workspace-multiplexer.ts";
+import { describe, expect, it } from "vitest";
+import {
+  WINDOW_LINK_MAX_LINKS,
+  WindowLinkTargetSchemaZ,
+  WindowLinkTopologySchemaZ,
+} from "../window-links.ts";
+import {
+  PaneStreamLayoutSnapshotV2FrameSchemaZ,
+  PaneStreamLayoutSnapshotFrameSchemaZ,
+  PaneStreamLayoutSnapshotV1FrameSchemaZ,
+  PaneStreamServerFrameSchemaZ,
+  PANE_STREAM_PROTOCOL_VERSION,
+} from "../pane-stream.ts";
+
+const linkId = (index: number) => `window-link.${index.toString(16).padStart(32, "0")}`;
+const topology = () => ({
+  liveSessionId: `live-session.${"a".repeat(20)}`,
+  linkRevision: 1,
+  activeLinkId: linkId(1),
+  links: [
+    { linkId: linkId(1), semanticWindowId: "window.one", displayIndex: 0 },
+    { linkId: linkId(2), semanticWindowId: "window.one", displayIndex: 1 },
+  ],
+});
+const layout = (window = "window.one", pane: string | null = "pane.one", currentWindow = true) => ({
+  type: "layout" as const,
+  semanticWindowId: window,
+  windowName: "shell",
+  currentWindow,
+  cols: 80,
+  rows: 24,
+  zoomed: false,
+  panes: [{ pane, left: 0, top: 0, width: 80, height: 24, active: true }],
+});
+const snapshot = () => ({
+  type: "layout-snapshot" as const,
+  topologyEpoch: 1,
+  layouts: [layout()],
+  windowLinks: topology(),
+});
+
+describe("window link contracts", () => {
+  it("allows multiple links sharing one unique backing and pane", () => {
+    expect(WindowLinkTopologySchemaZ.safeParse(topology()).success).toBe(true);
+    expect(PaneStreamLayoutSnapshotV2FrameSchemaZ.safeParse(snapshot()).success).toBe(true);
+    expect(
+      PaneStreamLayoutSnapshotV2FrameSchemaZ.safeParse({
+        ...snapshot(),
+        windowLinks: { ...topology(), activeLinkId: linkId(2) },
+      }).success,
+    ).toBe(true);
+  });
+
+  it("rejects duplicate handles/indexes and missing active links", () => {
+    const original = topology();
+    for (const invalid of [
+      { ...original, links: [original.links[0], { ...original.links[1], linkId: linkId(1) }] },
+      { ...original, links: [original.links[0], { ...original.links[1], displayIndex: 0 }] },
+      { ...original, activeLinkId: linkId(3) },
+      { ...original, links: [] },
+    ])
+      expect(WindowLinkTopologySchemaZ.safeParse(invalid).success).toBe(false);
+  });
+
+  it("bounds topology size and integer revisions/indexes", () => {
+    const links = Array.from({ length: WINDOW_LINK_MAX_LINKS }, (_, index) => ({
+      linkId: linkId(index + 1),
+      semanticWindowId: "window.one",
+      displayIndex: index,
+    }));
+    expect(WindowLinkTopologySchemaZ.safeParse({ ...topology(), links }).success).toBe(true);
+    expect(
+      WindowLinkTopologySchemaZ.safeParse({
+        ...topology(),
+        links: [
+          ...links,
+          {
+            linkId: linkId(WINDOW_LINK_MAX_LINKS + 1),
+            semanticWindowId: "window.one",
+            displayIndex: WINDOW_LINK_MAX_LINKS,
+          },
+        ],
+      }).success,
+    ).toBe(false);
+    for (const value of [-1, 0.5, Number.MAX_SAFE_INTEGER + 1, Infinity]) {
+      expect(
+        WindowLinkTopologySchemaZ.safeParse({ ...topology(), linkRevision: value }).success,
+      ).toBe(false);
+      expect(
+        WindowLinkTopologySchemaZ.safeParse({
+          ...topology(),
+          links: [{ ...links[0], displayIndex: value }],
+        }).success,
+      ).toBe(false);
+    }
+  });
+
+  it("accepts only opaque targets and rejects native or display action addresses", () => {
+    const target = {
+      liveSessionId: topology().liveSessionId,
+      linkId: linkId(1),
+      expectedSemanticWindowId: "window.one",
+      linkRevision: 0,
+    };
+    expect(WindowLinkTargetSchemaZ.safeParse(target).success).toBe(true);
+    for (const invalid of [
+      { ...target, linkId: "@0" },
+      { ...target, linkId: "/tmp/tmux/socket" },
+      { ...target, linkId: "window-link.abc" },
+      { ...target, liveSessionId: "$0" },
+      { ...target, expectedSemanticWindowId: "@0" },
+      { ...target, displayIndex: 0 },
+      { ...target, linkRevision: -1 },
+      { ...target, linkRevision: Number.MAX_SAFE_INTEGER + 1 },
+    ])
+      expect(WindowLinkTargetSchemaZ.safeParse(invalid).success).toBe(false);
+  });
+
+  it("requires a complete join and a matching active backing", () => {
+    const second = layout("window.two", "pane.two", false);
+    for (const invalid of [
+      { ...snapshot(), layouts: [layout("window.two")] },
+      { ...snapshot(), layouts: [layout(), second] },
+      {
+        ...snapshot(),
+        layouts: [layout("window.one", "pane.one", false), { ...second, currentWindow: true }],
+        windowLinks: {
+          ...topology(),
+          links: [
+            ...topology().links,
+            { linkId: linkId(3), semanticWindowId: "window.two", displayIndex: 2 },
+          ],
+        },
+      },
+    ])
+      expect(PaneStreamLayoutSnapshotV2FrameSchemaZ.safeParse(invalid).success).toBe(false);
+  });
+
+  it("preserves unique backing/pane and exactly-one-current invariants", () => {
+    for (const layouts of [
+      [layout(), layout()],
+      [layout(), layout("window.two", "pane.one", false)],
+      [layout("window.one", null)],
+      [{ ...layout(), semanticWindowId: null }],
+      [layout("window.one", "pane.one", false)],
+      [layout(), layout("window.two", "pane.two", true)],
+    ])
+      expect(
+        PaneStreamLayoutSnapshotV2FrameSchemaZ.safeParse({ ...snapshot(), layouts }).success,
+      ).toBe(false);
+  });
+
+  it("requires v2 topology and refuses the old v1 shape", () => {
+    const v1 = { type: "layout-snapshot", topologyEpoch: 1, layouts: [layout()] };
+    expect(PANE_STREAM_PROTOCOL_VERSION).toBe(2);
+    expect(PaneStreamLayoutSnapshotV1FrameSchemaZ.safeParse(v1).success).toBe(true);
+    expect(PaneStreamLayoutSnapshotFrameSchemaZ.safeParse(v1).success).toBe(false);
+    expect(PaneStreamLayoutSnapshotV2FrameSchemaZ.safeParse(v1).success).toBe(false);
+    expect(PaneStreamLayoutSnapshotFrameSchemaZ.safeParse(snapshot()).success).toBe(true);
+    expect(PaneStreamServerFrameSchemaZ.safeParse(snapshot()).success).toBe(true);
+    expect(
+      PaneStreamLayoutSnapshotV2FrameSchemaZ.safeParse({ ...snapshot(), unexpected: true }).success,
+    ).toBe(false);
+  });
+});
+
+describe("window link action arguments", () => {
+  const target = () => ({
+    liveSessionId: topology().liveSessionId,
+    linkId: linkId(1),
+    expectedSemanticWindowId: "window.one",
+    linkRevision: 1,
+  });
+
+  it("accepts opaque select/unlink targets and explicit-link pane selection", () => {
+    for (const schema of [
+      WorkspaceWindowLinkSelectArgumentsSchemaZ,
+      WorkspaceWindowLinkUnlinkArgumentsSchemaZ,
+    ]) {
+      expect(schema.safeParse({ workspaceName: "project", target: target() }).success).toBe(true);
+    }
+    expect(
+      WorkspacePaneSelectWithWindowLinkArgumentsSchemaZ.safeParse({
+        workspaceName: "project",
+        semanticPaneId: "pane.one",
+        windowLink: target(),
+      }).success,
+    ).toBe(true);
+  });
+
+  it("rejects native addresses, display indexes, command/force flags and unknown fields", () => {
+    for (const schema of [
+      WorkspaceWindowLinkSelectArgumentsSchemaZ,
+      WorkspaceWindowLinkUnlinkArgumentsSchemaZ,
+    ]) {
+      const args = { workspaceName: "project", target: target() };
+      for (const invalid of [
+        { ...args, target: "@0" },
+        { ...args, target: { ...target(), linkId: "@0" } },
+        { ...args, target: { ...target(), expectedSemanticWindowId: "@0" } },
+        { ...args, target: { ...target(), displayIndex: 0 } },
+        { ...args, target: { ...target(), runtimeSessionId: "$0" } },
+        { ...args, displayIndex: 0 },
+        { ...args, command: "kill-server" },
+        { ...args, force: true },
+        { ...args, socketPath: "/tmp/tmux/socket" },
+        { ...args, workspaceName: "" },
+      ])
+        expect(schema.safeParse(invalid).success).toBe(false);
+    }
+    const args = { workspaceName: "project", semanticPaneId: "pane.one", windowLink: target() };
+    for (const invalid of [
+      { ...args, semanticPaneId: "%0" },
+      { ...args, command: "select-pane -t %0" },
+      { ...args, windowLink: { ...target(), linkId: "project:0" } },
+      { workspaceName: "project", semanticPaneId: "pane.one" },
+    ])
+      expect(WorkspacePaneSelectWithWindowLinkArgumentsSchemaZ.safeParse(invalid).success).toBe(
+        false,
+      );
+  });
+
+  it("accepts registered link verbs and explicit-link pane selection", () => {
+    const args = { workspaceName: "project", target: target() };
+    for (const verb of ["workspace.window.link.select", "workspace.window.link.unlink"]) {
+      expect(WorkspaceMultiplexerIntentSchemaZ.safeParse({ verb, ...args }).success).toBe(true);
+    }
+    expect(
+      WorkspacePaneSelectArgumentsSchemaZ.safeParse({
+        workspaceName: "project",
+        semanticPaneId: "pane.one",
+        windowLink: target(),
+      }).success,
+    ).toBe(true);
+  });
+});

package/packages/contracts/src/actions-contract.ts

@@ -42,6 +42,10 @@ import {
   AppWindowMutationResultSchemaZ,
 } from "./app-window-mutation.ts";
 import {
+  WorkspaceWindowLinkSelectArgumentsSchemaZ,
+  WorkspaceWindowLinkUnlinkArgumentsSchemaZ,
+  WorkspaceWindowLinkSelectResultSchemaZ,
+  WorkspaceWindowLinkUnlinkResultSchemaZ,
   WorkspacePaneKillArgumentsSchemaZ,
   WorkspacePaneKillResultSchemaZ,
   WorkspacePaneResizeArgumentsSchemaZ,
@@ -427,6 +431,14 @@ export const ActionContractsZ = {
     input: AppWindowMutationInputZ,
     result: AppWindowMutationResultZ,
   },
+  "workspace.window.link.select": {
+    input: WorkspaceWindowLinkSelectArgumentsSchemaZ,
+    result: WorkspaceWindowLinkSelectResultSchemaZ,
+  },
+  "workspace.window.link.unlink": {
+    input: WorkspaceWindowLinkUnlinkArgumentsSchemaZ,
+    result: WorkspaceWindowLinkUnlinkResultSchemaZ,
+  },
   "workspace.window.split": {
     input: WorkspaceWindowSplitInputZ,
     result: WorkspaceWindowSplitResultZ,

package/packages/contracts/src/daemon-resource-request.test.ts

@@ -84,7 +84,7 @@ const REQUESTS: readonly DaemonResourceRequest[] = [
   {
     resource: "issuePaneStream",
     request: {
-      protocolVersion: 1,
+      protocolVersion: 2,
       workspaceName: WORKSPACE,
       panes: ["pane.worker"],
       viewerMode: "read-only",

package/packages/contracts/src/daemon-wire.ts

@@ -5,11 +5,8 @@ import { z } from "zod";
  * health responses, REST resources, and WebSocket transports. This is
  * intentionally independent from npm/package marketing versions.
  */
-// v2 makes the daemon-minted fleet session identity mandatory on workspace
-// catalog v2 rows. A v1 daemon can otherwise pass the bootstrap handshake and
-// then fail a current client at the first catalog parse, so this is a real wire
-// boundary rather than an additive package-version change.
-export const DAEMON_WIRE_PROTOCOL_VERSION = 2 as const;
+// v3 requires link-aware terminal topology and actions; v2 peers must upgrade.
+export const DAEMON_WIRE_PROTOCOL_VERSION = 3 as const;
 
 /**
  * Discovery must retain unknown positive versions so a client can report an
@@ -96,7 +93,14 @@ export const DaemonProvenanceSchema = z.object({
 });
 export type DaemonProvenance = z.infer<typeof DaemonProvenanceSchema>;
 
+export const TmuxServerProofSchema = z.object({
+  version: z.literal(1),
+  kind: z.enum(["live", "unbound-name"]),
+  digest: z.string().regex(/^[a-f0-9]{64}$/u),
+});
+
 export const CanonicalDaemonInfoSchema = z.object({
+  tmuxServerProofVersion: z.literal(1).optional(),
   supervisionId: DaemonSupervisionIdSchema.optional(),
   pid: z.number().int().positive(),
   port: z.number().int().min(1).max(65_535),
@@ -133,6 +137,7 @@ export type DaemonHealthz = z.infer<typeof DaemonHealthzSchema>;
  * daemon.json record is the process instance which published that record.
  */
 export const DaemonIdentitySchema = z.object({
+  tmuxServerProof: TmuxServerProofSchema.nullable().optional(),
   ok: z.literal(true),
   pid: z.number().int().positive(),
   protocolVersion: DaemonWireProtocolVersionSchema,

package/packages/contracts/src/fleet-client-state.ts

@@ -1,3 +1,4 @@
+import { TmuxServerScopeSchemaZ } from "./tmux-server-scope.ts";
 import { z } from "zod";
 import { SavedMachineIdSchema } from "./saved-machines.ts";
 import { DaemonInstanceIdentitySchemaZ } from "./daemon-wire.ts";
@@ -16,6 +17,8 @@ export const FleetCacheRouteIdSchema = z.union([z.literal("local"), SavedMachine
 export const FleetCachedSessionSchema = z.strictObject({
   id: key,
   liveSessionId: key.optional(),
+  server: TmuxServerScopeSchemaZ.optional(),
+  serverLabel: label.optional(),
   name: label,
   paneCount: z.number().int().min(0).max(4096),
 });