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

package/packages/contracts/src/fleet-lifecycle.ts

@@ -1,3 +1,4 @@
+import { WorkspaceCatalogLiveSessionIdSchemaZ } from "./workspace-catalog-resource.ts";
 import { z } from "zod";
 import {
   FleetAgentIdSchemaZ,
@@ -29,6 +30,8 @@ const OwnerPathSchemaZ = z
 export const WorkspaceSessionCreateArgumentsSchemaZ = z
   .object({
     displayName: SafeDisplayNameSchemaZ,
+    /** Opt in to an incarnation-bearing receipt; legacy clients keep their strict result shape. */
+    includeLiveSessionId: z.boolean().optional(),
     cwd: OwnerPathSchemaZ.optional(),
     expectedDaemonInstanceId: z.uuid().optional(),
   })
@@ -42,6 +45,8 @@ export const WorkspaceSessionCreateResultSchemaZ = z
     operationId: z.uuid(),
     daemonInstanceId: z.uuid(),
     outcome: z.enum(["created", "adopted", "replayed"]),
+    /** Captured atomically by new-session; absent from older daemons and adopted routes. */
+    liveSessionId: WorkspaceCatalogLiveSessionIdSchemaZ.optional(),
     fleetSessionId: FleetSessionIdSchemaZ,
     /** Canonical registered route; displayName is presentation only. */
     workspaceName: DesktopWorkspaceNameSchemaZ,

package/packages/contracts/src/index.ts

@@ -65,6 +65,7 @@ export * from "./workspace-open.ts";
 export * from "./workspace-open-handoff.ts";
 export * from "./workspace-promotion.ts";
 export * from "./workspace-multiplexer.ts";
+export * from "./window-links.ts";
 export * from "./interaction-receipts.ts";
 export * from "./multiplexer-verbs.ts";
 export * from "./visual-tokens.ts";
@@ -97,3 +98,4 @@ export * from "./saved-machines.ts";
 export * from "./semantic-icons.ts";
 
 export * from "./workspace-admission.ts";
+export * from "./tmux-server-scope.ts";

package/packages/contracts/src/interaction-receipts.ts

@@ -1,3 +1,4 @@
+import { WindowLinkTargetSchemaZ } from "./window-links.ts";
 import { z } from "zod";
 
 import { DesktopWorkspaceNameSchemaZ } from "./desktop-workspace-name.ts";
@@ -14,6 +15,8 @@ export type AuthoredInteractionOrigin = z.infer<typeof AuthoredInteractionOrigin
 
 /** Every semantic session-runtime verb; raw tmux addresses never enter this vocabulary. */
 export const InteractionOperationKindSchemaZ = z.enum([
+  "workspace.window.link.select",
+  "workspace.window.link.unlink",
   "workspace.window.split",
   "workspace.window.kill",
   "workspace.pane.kill",
@@ -46,6 +49,7 @@ const InteractionWindowReferenceSchemaZ = z.discriminatedUnion("by", [
 
 /** Stable semantic target retained even when the operation removes or renames it. */
 export const InteractionTargetSchemaZ = z.discriminatedUnion("kind", [
+  z.object({ kind: z.literal("window-link"), target: WindowLinkTargetSchemaZ }).strict(),
   z.object({ kind: z.literal("session") }).strict(),
   z.object({ kind: z.literal("window"), target: InteractionWindowReferenceSchemaZ }).strict(),
   z
@@ -63,6 +67,8 @@ const MutationOutcomeSchemaZ = z.enum(["applied", "unchanged", "replayed"]);
  * different verb.
  */
 export const InteractionSafeSummarySchemaZ = z.union([
+  z.object({ operationKind: z.literal("workspace.window.link.unlink") }).strict(),
+  z.object({ operationKind: z.literal("workspace.window.link.select") }).strict(),
   z
     .object({
       operationKind: z.literal("workspace.window.split"),
@@ -129,6 +135,20 @@ export type PaneReadSafeSummary = Extract<
  * terminal bytes never enter the replay journal.
  */
 export const InteractionProofSchemaZ = z.discriminatedUnion("operationKind", [
+  z
+    .object({
+      operationKind: z.literal("workspace.window.link.unlink"),
+      outcome: MutationOutcomeSchemaZ,
+      target: WindowLinkTargetSchemaZ,
+    })
+    .strict(),
+  z
+    .object({
+      operationKind: z.literal("workspace.window.link.select"),
+      outcome: MutationOutcomeSchemaZ,
+      target: WindowLinkTargetSchemaZ,
+    })
+    .strict(),
   z
     .object({
       operationKind: z.literal("workspace.window.split"),
@@ -280,6 +300,25 @@ export const InteractionReceiptSchemaZ = z
         message: "external observations require a presence-only summary",
       });
     }
+    if (receipt.operationKind.startsWith("workspace.window.link.")) {
+      if (receipt.target.kind !== "window-link") {
+        context.addIssue({
+          code: "custom",
+          path: ["target"],
+          message: "Window link verbs require a link target",
+        });
+      } else if (
+        receipt.proof &&
+        "target" in receipt.proof &&
+        JSON.stringify(receipt.proof.target) !== JSON.stringify(receipt.target.target)
+      ) {
+        context.addIssue({
+          code: "custom",
+          path: ["proof"],
+          message: "Window link proof must match its target",
+        });
+      }
+    }
     const paneVerb = receipt.operationKind.startsWith("workspace.pane.");
     if (paneVerb && receipt.target.kind !== "pane") {
       context.addIssue({

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

@@ -84,7 +84,7 @@ export const RendererSafeIssueReasonSchemaZ = z
   .max(240)
   .refine(
     (reason) =>
-      !/(?:authorization|bearer\s+|owner.?token|redemptionticket|ps1_|ta1_)/iu.test(reason),
+      !/(?:authorization|bearer\s+|owner.?token|redemptionticket|ps[12]_|ta1_)/iu.test(reason),
     "issue error reason must be credential-redacted",
   );
 

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

@@ -118,6 +118,29 @@ function deepFreeze<Value>(value: Value): Value {
 }
 
 const ENTRIES: readonly MultiplexerVerbEntry[] = [
+  {
+    version: MULTIPLEXER_VERB_TABLE_VERSION,
+    id: "window.link.select",
+    label: "Select window link",
+    description: "Select this link without changing the shared window's active pane.",
+    scope: "window",
+    execution: { kind: "daemon-action", action: "workspace.window.link.select" },
+    availabilityInputs: ["workspaceConnected"],
+    destructive: false,
+    tmuxKeyHint: null,
+  },
+  {
+    version: MULTIPLEXER_VERB_TABLE_VERSION,
+    id: "window.link.unlink",
+    label: "Unlink window",
+    description:
+      "Remove this session link; preserve other links and their panes. Native last-link restrictions apply.",
+    scope: "window",
+    execution: { kind: "daemon-action", action: "workspace.window.link.unlink" },
+    availabilityInputs: ["workspaceConnected"],
+    destructive: true,
+    tmuxKeyHint: null,
+  },
   {
     version: MULTIPLEXER_VERB_TABLE_VERSION,
     id: "session.new",
@@ -179,7 +202,8 @@ const ENTRIES: readonly MultiplexerVerbEntry[] = [
     version: MULTIPLEXER_VERB_TABLE_VERSION,
     id: "window.kill",
     label: "Close window",
-    description: "Kill this tmux window and every pane in it. Refused for a session's last window.",
+    description:
+      "Kill this shared tmux window and its panes in every linked session. Refused for a session's last window.",
     scope: "window",
     execution: { kind: "daemon-action", action: "workspace.window.kill" },
     availabilityInputs: ["workspaceConnected", "sessionWindowCount"],

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

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { isTmuxServerPaneStreamPath } from "./tmux-server-scope.ts";
 import {
   CausalCellCapabilitySchemaZ,
   CausalCellFailureV1SchemaZ,
@@ -41,6 +42,7 @@ import {
   SessionRuntimeTerminalTextInputSchemaZ,
 } from "./session-runtime.ts";
 import { WorkspaceMultiplexerMutationResultSchemaZ } from "./workspace-multiplexer.ts";
+import { WindowLinkTopologySchemaZ } from "./window-links.ts";
 
 export const PANE_STREAM_CLOCK_BOUNDS_CAPABILITY_V1 = "clock-bounds-v1" as const;
 export const PaneStreamDiagnosticCapabilitySchemaZ = z.union([
@@ -55,7 +57,7 @@ export type PaneStreamDiagnosticCapability = z.infer<typeof PaneStreamDiagnostic
  *
  * The discipline is the terminal-attachment one, applied to mirror streams:
  * semantic identity only (runtime `%N`/`@N`/`$N` addresses never cross this
- * boundary), a one-time `ps1_` redemption ticket bound to one daemon
+ * boundary), a one-time `ps2_` redemption ticket bound to one daemon
  * generation, and bounded shapes everywhere. Two deliberate differences,
  * both recorded product decisions:
  *
@@ -65,11 +67,11 @@ export type PaneStreamDiagnosticCapability = z.infer<typeof PaneStreamDiagnostic
  *    (the control client casts no size vote), so a renderer has no geometry
  *    to declare.
  */
-export const PANE_STREAM_PROTOCOL_VERSION = 1 as const;
+export const PANE_STREAM_PROTOCOL_VERSION = 2 as const;
 
-export const PANE_STREAM_ISSUE_PATH = "/api/v1/terminal/pane-streams/issue" as const;
-export const PANE_STREAM_REDEEM_PATH = "/v1/terminal/pane-streams/redeem" as const;
-export const PANE_STREAM_WEBSOCKET_SUBPROTOCOL = "tmux-ide-pane-stream.v1" as const;
+export const PANE_STREAM_ISSUE_PATH = "/api/v2/terminal/pane-streams/issue" as const;
+export const PANE_STREAM_REDEEM_PATH = "/v2/terminal/pane-streams/redeem" as const;
+export const PANE_STREAM_WEBSOCKET_SUBPROTOCOL = "tmux-ide-pane-stream.v2" as const;
 
 /** Perf-plan ceiling (~16-24 live nodes) with headroom; enforced at issue. */
 export const PANE_STREAM_MAX_PANES = 24;
@@ -115,7 +117,7 @@ export const PaneStreamLeaseRequestSchemaZ = z
   .strict();
 export type PaneStreamLeaseRequest = z.infer<typeof PaneStreamLeaseRequestSchemaZ>;
 
-export const PaneStreamRedemptionTicketSchemaZ = z.string().regex(/^ps1_[A-Za-z0-9_-]{43}$/u);
+export const PaneStreamRedemptionTicketSchemaZ = z.string().regex(/^ps2_[A-Za-z0-9_-]{43}$/u);
 
 /** Same canonical loopback discipline as the terminal-attachment endpoint. */
 export const PaneStreamLoopbackWebSocketUrlSchemaZ = z
@@ -129,7 +131,7 @@ export const PaneStreamLoopbackWebSocketUrlSchemaZ = z
       url.port.length > 0 &&
       url.username.length === 0 &&
       url.password.length === 0 &&
-      url.pathname === PANE_STREAM_REDEEM_PATH &&
+      (url.pathname === PANE_STREAM_REDEEM_PATH || isTmuxServerPaneStreamPath(url.pathname)) &&
       url.search.length === 0 &&
       url.hash.length === 0 &&
       url.toString() === value
@@ -471,7 +473,7 @@ export const PaneStreamLayoutFrameSchemaZ = z
   })
   .strict();
 
-export const PaneStreamLayoutSnapshotFrameSchemaZ = z
+export const PaneStreamLayoutSnapshotV1FrameSchemaZ = z
   .object({
     type: z.literal("layout-snapshot"),
     topologyEpoch: z.number().int().nonnegative(),
@@ -526,6 +528,47 @@ export const PaneStreamLayoutSnapshotFrameSchemaZ = z
     }
   });
 
+/**
+ * Atomic v2 grammar: backing layouts and session links share one snapshot.
+ */
+export const PaneStreamLayoutSnapshotV2FrameSchemaZ =
+  PaneStreamLayoutSnapshotV1FrameSchemaZ.safeExtend({
+    windowLinks: WindowLinkTopologySchemaZ,
+  }).superRefine((snapshot, context) => {
+    const backings = new Map(snapshot.layouts.map((layout) => [layout.semanticWindowId, layout]));
+    const linkedBackings = new Set<string>();
+    for (const [index, link] of snapshot.windowLinks.links.entries()) {
+      linkedBackings.add(link.semanticWindowId);
+      const backing = backings.get(link.semanticWindowId);
+      if (!backing) {
+        context.addIssue({
+          code: "custom",
+          message: "Window links require a known backing layout",
+          path: ["windowLinks", "links", index, "semanticWindowId"],
+        });
+      } else if (link.linkId === snapshot.windowLinks.activeLinkId && !backing.currentWindow) {
+        context.addIssue({
+          code: "custom",
+          message: "The current backing must own the active window link",
+          path: ["windowLinks", "activeLinkId"],
+        });
+      }
+    }
+    for (const [index, layout] of snapshot.layouts.entries()) {
+      if (layout.semanticWindowId !== null && !linkedBackings.has(layout.semanticWindowId)) {
+        context.addIssue({
+          code: "custom",
+          message: "Every backing layout requires a window link",
+          path: ["layouts", index, "semanticWindowId"],
+        });
+      }
+    }
+  });
+export const PaneStreamLayoutSnapshotFrameSchemaZ = PaneStreamLayoutSnapshotV2FrameSchemaZ;
+export type PaneStreamLayoutSnapshotV2Frame = z.infer<
+  typeof PaneStreamLayoutSnapshotV2FrameSchemaZ
+>;
+
 export const PaneStreamFlowFrameSchemaZ = z
   .object({
     type: z.literal("flow"),

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

@@ -0,0 +1,172 @@
+import { z } from "zod";
+import {
+  TerminalAttachmentSemanticPaneIdSchemaZ,
+  TerminalAttachmentSemanticWindowIdSchemaZ,
+} from "./semantic-identity.ts";
+import { WorkspaceCatalogLiveSessionIdSchemaZ } from "./workspace-catalog-resource.ts";
+
+/** Stable registration identity. Never derive it from a socket path or native ID. */
+export const TmuxServerIdSchemaZ = z.string().regex(/^tmux-server\.[a-f0-9]{32}$/u);
+/** Fresh live authority incarnation, independently retired for each server owner. */
+export const TmuxServerGenerationSchemaZ = z.uuid();
+export const TmuxServerScopeSchemaZ = z
+  .object({ serverId: TmuxServerIdSchemaZ, generation: TmuxServerGenerationSchemaZ })
+  .strict();
+
+const descriptorShape = {
+  serverId: TmuxServerIdSchemaZ,
+  label: z
+    .string()
+    .trim()
+    .min(1)
+    .max(160)
+    .refine(
+      (value) =>
+        [...value].every(
+          (character) => character.charCodeAt(0) >= 32 && character.charCodeAt(0) !== 127,
+        ),
+      "server label contains control characters",
+    ),
+};
+export const TmuxServerDescriptorSchemaZ = z.discriminatedUnion("state", [
+  z
+    .object({
+      ...descriptorShape,
+      state: z.literal("online"),
+      generation: TmuxServerGenerationSchemaZ,
+    })
+    .strict(),
+  z.object({ ...descriptorShape, state: z.literal("offline"), generation: z.null() }).strict(),
+]);
+
+/** Explicitly versioned endpoint; this is not an additive field on legacy wire resources. */
+export const TMUX_SERVERS_API_PATH = "/api/v1/tmux-servers" as const;
+export const TmuxServersResourceSchemaZ = z
+  .object({
+    version: z.literal(1),
+    servers: z.array(TmuxServerDescriptorSchemaZ),
+  })
+  .strict()
+  .superRefine((resource, context) => {
+    const seen = new Set<string>();
+    for (const [index, server] of resource.servers.entries()) {
+      if (seen.has(server.serverId))
+        context.addIssue({
+          code: "custom",
+          path: ["servers", index, "serverId"],
+          message: "Server registrations must be unique",
+        });
+      seen.add(server.serverId);
+    }
+  });
+export const TmuxServerSessionTargetSchemaZ = z
+  .object({
+    server: TmuxServerScopeSchemaZ,
+    liveSessionId: WorkspaceCatalogLiveSessionIdSchemaZ,
+  })
+  .strict();
+export const TmuxServerWindowTargetSchemaZ = TmuxServerSessionTargetSchemaZ.extend({
+  semanticWindowId: TerminalAttachmentSemanticWindowIdSchemaZ,
+});
+export const TmuxServerPaneTargetSchemaZ = TmuxServerSessionTargetSchemaZ.extend({
+  semanticPaneId: TerminalAttachmentSemanticPaneIdSchemaZ,
+});
+
+export type TmuxServerId = z.infer<typeof TmuxServerIdSchemaZ>;
+export type TmuxServerGeneration = z.infer<typeof TmuxServerGenerationSchemaZ>;
+export type TmuxServerScope = z.infer<typeof TmuxServerScopeSchemaZ>;
+export type TmuxServerDescriptor = z.infer<typeof TmuxServerDescriptorSchemaZ>;
+export type TmuxServersResource = z.infer<typeof TmuxServersResourceSchemaZ>;
+export type TmuxServerSessionTarget = z.infer<typeof TmuxServerSessionTargetSchemaZ>;
+export type TmuxServerWindowTarget = z.infer<typeof TmuxServerWindowTargetSchemaZ>;
+export type TmuxServerPaneTarget = z.infer<typeof TmuxServerPaneTargetSchemaZ>;
+
+export type TmuxServerScopeResolution =
+  | { status: "matched"; scope: TmuxServerScope }
+  | { status: "not-found" | "offline" | "stale-generation" | "ambiguous" };
+
+/**
+ * Legacy adaptation considers every registration, including offline ones. Losing
+ * one connection must not redirect an old unscoped request to a different server.
+ * Explicit callers never fall back when their registration or incarnation is gone.
+ */
+export function resolveTmuxServerScope(
+  registrations: readonly TmuxServerDescriptor[],
+  requested?: TmuxServerScope,
+): TmuxServerScopeResolution {
+  const candidates = requested
+    ? registrations.filter((entry) => entry.serverId === requested.serverId)
+    : registrations;
+  if (candidates.length === 0) return { status: "not-found" };
+  if (candidates.length !== 1) return { status: "ambiguous" };
+  const candidate = candidates[0]!;
+  if (candidate.state === "offline") return { status: "offline" };
+  if (requested && requested.generation !== candidate.generation) {
+    return { status: "stale-generation" };
+  }
+  return {
+    status: "matched",
+    scope: { serverId: candidate.serverId, generation: candidate.generation },
+  };
+}
+
+/** Namespaces copied stamps/native IDs and retires keys on authority replacement. */
+export function tmuxServerScopedResourceKey(
+  scope: TmuxServerScope,
+  kind: string,
+  resourceId: string,
+): string {
+  return JSON.stringify([scope.serverId, scope.generation, kind, resourceId]);
+}
+
+/** Server and generation are part of the upgrade address, never query authority. */
+export function tmuxServerPaneStreamPath(scope: TmuxServerScope): string {
+  const parsed = TmuxServerScopeSchemaZ.parse(scope);
+  return `/v2/tmux-servers/${parsed.serverId}/${parsed.generation}/pane-streams/redeem`;
+}
+
+export function isTmuxServerPaneStreamPath(path: string): boolean {
+  const match = /^\/v2\/tmux-servers\/([^/]+)\/([^/]+)\/pane-streams\/redeem$/u.exec(path);
+  if (!match) return false;
+  return TmuxServerScopeSchemaZ.safeParse({ serverId: match[1], generation: match[2] }).success;
+}
+
+export const TmuxServerSessionsResourceSchemaZ = z
+  .object({
+    version: z.literal(1),
+    server: TmuxServerScopeSchemaZ,
+    sessions: z.array(
+      z
+        .object({
+          liveSessionId: WorkspaceCatalogLiveSessionIdSchemaZ,
+          sessionName: z.string().min(1).max(160),
+          workspaceName: z.string().min(1).max(160).nullable(),
+          paneCount: z.number().int().nonnegative(),
+        })
+        .strict(),
+    ),
+  })
+  .strict();
+
+/** Selector intent is interpreted only by the daemon on its own host. */
+export const TmuxServerRegistrationRequestSchemaZ = z
+  .object({
+    label: descriptorShape.label.max(128),
+    selector: z.discriminatedUnion("kind", [
+      z
+        .object({
+          kind: z.literal("path"),
+          path: z
+            .string()
+            .min(1)
+            .max(4096)
+            .refine((path) => path.startsWith("/") && !/[\0\r\n]/u.test(path)),
+        })
+        .strict(),
+      z
+        .object({ kind: z.literal("name"), name: z.string().regex(/^[A-Za-z0-9_.-]{1,128}$/u) })
+        .strict(),
+    ]),
+  })
+  .strict();
+export type TmuxServerRegistrationRequest = z.infer<typeof TmuxServerRegistrationRequestSchemaZ>;

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

@@ -0,0 +1,76 @@
+import { z } from "zod";
+import { TerminalAttachmentSemanticWindowIdSchemaZ } from "./semantic-identity.ts";
+import { WorkspaceCatalogLiveSessionIdSchemaZ } from "./workspace-catalog-resource.ts";
+
+/** Schema bound, not a measured runtime resource budget. */
+export const WINDOW_LINK_MAX_LINKS = 256;
+
+/** Random daemon/session-generation-scoped handle; never a native index or ID. */
+export const WindowLinkIdSchemaZ = z.string().regex(/^window-link\.[a-f0-9]{32}$/u);
+export const WindowLinkRevisionSchemaZ = z
+  .number()
+  .int()
+  .nonnegative()
+  .max(Number.MAX_SAFE_INTEGER);
+
+/** Shape validation only: the authority must validate session, revision and backing. */
+export const WindowLinkTargetSchemaZ = z
+  .object({
+    liveSessionId: WorkspaceCatalogLiveSessionIdSchemaZ,
+    linkId: WindowLinkIdSchemaZ,
+    expectedSemanticWindowId: TerminalAttachmentSemanticWindowIdSchemaZ,
+    linkRevision: WindowLinkRevisionSchemaZ,
+  })
+  .strict();
+
+export const WindowLinkObservationSchemaZ = z
+  .object({
+    linkId: WindowLinkIdSchemaZ,
+    semanticWindowId: TerminalAttachmentSemanticWindowIdSchemaZ,
+    /** Display only. Mutations resolve the opaque handle under live authority. */
+    displayIndex: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER),
+  })
+  .strict();
+
+export const WindowLinkTopologySchemaZ = z
+  .object({
+    liveSessionId: WorkspaceCatalogLiveSessionIdSchemaZ,
+    linkRevision: WindowLinkRevisionSchemaZ,
+    activeLinkId: WindowLinkIdSchemaZ,
+    links: z.array(WindowLinkObservationSchemaZ).min(1).max(WINDOW_LINK_MAX_LINKS),
+  })
+  .strict()
+  .superRefine((topology, context) => {
+    const ids = new Set<string>();
+    const indexes = new Set<number>();
+    for (const [index, link] of topology.links.entries()) {
+      if (ids.has(link.linkId)) {
+        context.addIssue({
+          code: "custom",
+          message: "Window link handles must be unique",
+          path: ["links", index, "linkId"],
+        });
+      }
+      if (indexes.has(link.displayIndex)) {
+        context.addIssue({
+          code: "custom",
+          message: "Window link display indexes must be unique",
+          path: ["links", index, "displayIndex"],
+        });
+      }
+      ids.add(link.linkId);
+      indexes.add(link.displayIndex);
+    }
+    if (!ids.has(topology.activeLinkId)) {
+      context.addIssue({
+        code: "custom",
+        message: "The active window link must be present",
+        path: ["activeLinkId"],
+      });
+    }
+  });
+
+export type WindowLinkId = z.infer<typeof WindowLinkIdSchemaZ>;
+export type WindowLinkTarget = z.infer<typeof WindowLinkTargetSchemaZ>;
+export type WindowLinkObservation = z.infer<typeof WindowLinkObservationSchemaZ>;
+export type WindowLinkTopology = z.infer<typeof WindowLinkTopologySchemaZ>;

package/packages/contracts/src/workspace-multiplexer.ts

@@ -27,6 +27,7 @@ import {
   WorkspacePaneDisplayTitleSchemaZ,
 } from "./workspace-pane-creation.ts";
 import { AuthoredInteractionOriginSchemaZ } from "./interaction-receipts.ts";
+import { WindowLinkTargetSchemaZ } from "./window-links.ts";
 
 /**
  * A tmux window named either by its own durable stamp or by a pane inside it.
@@ -130,10 +131,40 @@ export type WorkspacePaneZoomToggleArguments = z.infer<
 >;
 
 export const WorkspacePaneSelectArgumentsSchemaZ = WorkspaceScopedSchemaZ.extend({
+  windowLink: WindowLinkTargetSchemaZ.optional(),
   semanticPaneId: TerminalAttachmentSemanticPaneIdSchemaZ,
 }).strict();
 export type WorkspacePaneSelectArguments = z.infer<typeof WorkspacePaneSelectArgumentsSchemaZ>;
 
+/**
+ * Link-aware arguments use opaque observed authority.
+ * Execution requires daemon/session generation fencing and
+ * execution-time native link guards. These shapes carry no executable target.
+ */
+export const WorkspaceWindowLinkSelectArgumentsSchemaZ = WorkspaceScopedSchemaZ.extend({
+  target: WindowLinkTargetSchemaZ,
+}).strict();
+export type WorkspaceWindowLinkSelectArguments = z.infer<
+  typeof WorkspaceWindowLinkSelectArgumentsSchemaZ
+>;
+
+/** Ordinary unlink semantics; no forced unlink or implicit backing destruction. */
+export const WorkspaceWindowLinkUnlinkArgumentsSchemaZ = WorkspaceScopedSchemaZ.extend({
+  target: WindowLinkTargetSchemaZ,
+}).strict();
+export type WorkspaceWindowLinkUnlinkArguments = z.infer<
+  typeof WorkspaceWindowLinkUnlinkArgumentsSchemaZ
+>;
+
+/** Future explicit-link pane selection; runtime must verify pane/backing membership. */
+export const WorkspacePaneSelectWithWindowLinkArgumentsSchemaZ =
+  WorkspacePaneSelectArgumentsSchemaZ.extend({
+    windowLink: WindowLinkTargetSchemaZ,
+  }).strict();
+export type WorkspacePaneSelectWithWindowLinkArguments = z.infer<
+  typeof WorkspacePaneSelectWithWindowLinkArgumentsSchemaZ
+>;
+
 /**
  * Deliver literal terminal input through daemon authority. The text exists only
  * on the mutation request; neither the result nor the interaction receipt can
@@ -197,6 +228,12 @@ export type WorkspacePaneResizeArguments = z.infer<typeof WorkspacePaneResizeArg
 
 /** Every multiplexer intent, discriminated by the route that carries it. */
 export const WorkspaceMultiplexerIntentSchemaZ = z.discriminatedUnion("verb", [
+  WorkspaceWindowLinkSelectArgumentsSchemaZ.extend({
+    verb: z.literal("workspace.window.link.select"),
+  }).strict(),
+  WorkspaceWindowLinkUnlinkArgumentsSchemaZ.extend({
+    verb: z.literal("workspace.window.link.unlink"),
+  }).strict(),
   WorkspaceWindowSplitArgumentsSchemaZ.extend({
     verb: z.literal("workspace.window.split"),
   }).strict(),
@@ -273,6 +310,21 @@ const MutationEnvelopeSchemaZ = z.object({
   workspaceName: WorkspacePaneCreationWorkspaceNameSchemaZ,
 });
 
+export const WorkspaceWindowLinkSelectResultSchemaZ = MutationEnvelopeSchemaZ.extend({
+  verb: z.literal("workspace.window.link.select"),
+  target: WindowLinkTargetSchemaZ,
+}).strict();
+export type WorkspaceWindowLinkSelectResult = z.infer<
+  typeof WorkspaceWindowLinkSelectResultSchemaZ
+>;
+export const WorkspaceWindowLinkUnlinkResultSchemaZ = MutationEnvelopeSchemaZ.extend({
+  verb: z.literal("workspace.window.link.unlink"),
+  target: WindowLinkTargetSchemaZ,
+}).strict();
+export type WorkspaceWindowLinkUnlinkResult = z.infer<
+  typeof WorkspaceWindowLinkUnlinkResultSchemaZ
+>;
+
 export const WorkspaceWindowSplitResultSchemaZ = MutationEnvelopeSchemaZ.extend({
   verb: z.literal("workspace.window.split"),
   direction: WorkspaceSplitDirectionSchemaZ,
@@ -355,6 +407,8 @@ export const WorkspacePaneResizeResultSchemaZ = MutationEnvelopeSchemaZ.extend({
 export type WorkspacePaneResizeResult = z.infer<typeof WorkspacePaneResizeResultSchemaZ>;
 
 export const WorkspaceMultiplexerMutationResultSchemaZ = z.discriminatedUnion("verb", [
+  WorkspaceWindowLinkSelectResultSchemaZ,
+  WorkspaceWindowLinkUnlinkResultSchemaZ,
   WorkspaceWindowSplitResultSchemaZ,
   WorkspaceWindowKillResultSchemaZ,
   WorkspacePaneKillResultSchemaZ,

package/packages/core/src/interaction-receipts.ts

@@ -121,6 +121,10 @@ export function interactionSummaryLabel(
 ): string {
   const observed = phase === "observed";
   switch (operationKind) {
+    case "workspace.window.link.select":
+      return observed ? "window link selected" : "select window link";
+    case "workspace.window.link.unlink":
+      return observed ? "window unlinked" : "unlink window";
     case "workspace.window.split":
       return `split ${summary.operationKind === operationKind ? summary.direction : "window"}`;
     case "workspace.window.kill":

package/packages/daemon/dist/command-center/actions/command-definitions.js

@@ -34,6 +34,12 @@ const ACTION_COMMAND_METADATA = {
     "workspace.open.cancel": { label: "Cancel workspace handoff", category: "workspace" },
     "workspace.promote": { label: "Promote live session to workspace", category: "workspace" },
     "workspace.app-window.mutate": { label: "Mutate application window", category: "workspace" },
+    "workspace.window.link.select": { label: "Focus window link", category: "workspace" },
+    "workspace.window.link.unlink": {
+        label: "Unlink window",
+        category: "workspace",
+        dangerous: true,
+    },
     "workspace.window.split": { label: "Split pane", category: "workspace" },
     "workspace.window.kill": { label: "Close window", category: "workspace", dangerous: true },
     "workspace.pane.kill": { label: "Close pane", category: "workspace", dangerous: true },

package/packages/daemon/dist/command-center/actions/handlers/workspace-multiplexer.js

@@ -43,6 +43,8 @@ async function runVerb(verb, input, context, deps) {
 function verbHandler(verb) {
     return async (input, context = {}, deps = {}) => (await runVerb(verb, input, context, deps));
 }
+export const workspaceWindowLinkSelectHandler = verbHandler("workspace.window.link.select");
+export const workspaceWindowLinkUnlinkHandler = verbHandler("workspace.window.link.unlink");
 export const workspaceWindowSplitHandler = verbHandler("workspace.window.split");
 export const workspaceWindowKillHandler = verbHandler("workspace.window.kill");
 export const workspacePaneKillHandler = verbHandler("workspace.pane.kill");