tmux-ide 2.9.4 → 2.9.5

package/packages/daemon/src/tui/mirror/testing/styled-frame-oracle.ts

@@ -0,0 +1,209 @@
+/** Tiny independent visual oracle for the SSH fixture; no production decoder. */
+export type VisualCell = { text: string; width: number; fg: string; bg: string; bold: boolean };
+export type VisualFrame = {
+  cells: VisualCell[][];
+  cursor: { x: number; y: number; visible: boolean };
+};
+export type CompletedFrame = {
+  cols: number;
+  rows: number;
+  char: number[];
+  fg: number[];
+  bg: number[];
+  attributes: number[];
+  text: string;
+  cursor: { x: number; y: number; visible: boolean };
+};
+function check(condition: unknown, message: string): asserts condition {
+  if (!condition) throw Error(message);
+}
+const blank = (): VisualCell => ({ text: "", width: 1, fg: "ffffff", bg: "000000", bold: false });
+export function literalStyledFrame(marker: string, cols: 24 | 40 = 40): VisualFrame {
+  check(cols === 24 || cols === 40, "literal geometry");
+  check(marker.length <= cols, "marker width");
+  const cells = Array.from({ length: 8 }, () => Array.from({ length: cols }, blank));
+  [...marker].forEach((text, x) => (cells[0]![x] = { ...blank(), text }));
+  const initial = marker === "BEFORE_SSH";
+  const glyphs = initial ? ["X", "界", "", "é", "Z"] : ["Y", "q", "", "é", "R"];
+  glyphs.forEach(
+    (text, x) =>
+      (cells[1]![x] = {
+        text,
+        width: initial ? (x === 1 ? 2 : x === 2 ? 0 : 1) : 1,
+        fg: text ? "123456" : "ffffff",
+        bg: "214365",
+        bold: !!text,
+      }),
+  );
+  for (let x = 0; x < cols; x++)
+    cells[3]![x] = { ...blank(), text: x < 2 ? String(x + 1) : "", bg: "445566" };
+  return { cells, cursor: { x: 4, y: 2, visible: true } };
+}
+export function styledBytes(marker: string): string {
+  return `\x1b[0m\x1b[2J\x1b[H${marker}\x1b[2;1H\x1b[1;38;2;18;52;86;48;2;33;67;101m${marker === "BEFORE_SSH" ? "X界éZ" : "Yq éR"}\x1b[0m\x1b[4;1H\x1b[48;2;68;85;102m123456\x1b[4;3H\x1b[K\x1b[0m\x1b[3;5H\x1b]2;${marker}\x07`;
+}
+export function readCompletedFrame(raw: CompletedFrame): VisualFrame {
+  check((raw.cols === 24 || raw.cols === 40) && raw.rows === 8, "geometry");
+  const size = raw.cols * raw.rows;
+  check(
+    raw.char.length === size &&
+      raw.attributes.length === size &&
+      raw.fg.length === size * 4 &&
+      raw.bg.length === size * 4,
+    "buffer lengths",
+  );
+  const lines = raw.text.replace(/\n$/u, "").split("\n");
+  check(lines.length === 8, "line count");
+  const segmenter = new Intl.Segmenter("en", { granularity: "grapheme" });
+  const rgb = (a: number[], i: number) => {
+    const c = a.slice(i * 4, i * 4 + 4);
+    check(
+      c.length === 4 && c.every((v) => Number.isInteger(v) && v >= 0 && v <= 255) && c[3] === 255,
+      "RGBA",
+    );
+    return c
+      .slice(0, 3)
+      .map((v) => v.toString(16).padStart(2, "0"))
+      .join("");
+  };
+  const continuation = (n: number) => n === 0 || n >>> 30 === 3;
+  const cells = lines.map((line, y) => {
+    const text = [...segmenter.segment(line)].map((s) => s.segment);
+    let pos = 0;
+    const row = Array.from({ length: raw.cols }, (_, x) => {
+      const i = y * raw.cols + x,
+        cp = raw.char[i]!;
+      const cont =
+        continuation(cp) && x > 0 && !continuation(raw.char[i - 1]!) && raw.char[i - 1] !== 32;
+      let glyph = "";
+      if (cont) {
+        if (cp === 0) {
+          check(text[pos] === " ", "direct continuation text");
+          pos++;
+        }
+      } else {
+        glyph = text[pos++] ?? "";
+        check(/^(?:[\x20-\x7e]|界|é)$/u.test(glyph), "unsupported grapheme");
+      }
+      const width = cont ? 0 : x < raw.cols - 1 && continuation(raw.char[i + 1]!) ? 2 : 1;
+      const kind = cp >>> 30;
+      if (cont) {
+        const prev = raw.char[i - 1]!;
+        check(
+          prev === 0x754c || (prev >>> 30 === 2 && ((prev >>> 28) & 3) === 1),
+          "continuation owner",
+        );
+        if (kind === 3)
+          check(
+            ((cp >>> 26) & 3) === 1 &&
+              ((cp >>> 28) & 3) === 0 &&
+              (cp & 0x03ffffff) === (prev & 0x03ffffff),
+            "interned continuation",
+          );
+      } else if (kind === 0) {
+        check(
+          cp !== 0 && glyph.codePointAt(0) === cp && [...glyph].length === 1,
+          "direct codepoint mismatch",
+        );
+        check(width === (glyph === "界" ? 2 : 1), "direct width");
+      } else if (kind === 2) {
+        check(
+          glyph === "é" && ((cp >>> 26) & 3) === 0 && ((cp >>> 28) & 3) === 0 && width === 1,
+          "interned grapheme shape",
+        );
+      } else check(false, "unsupported raw char flags");
+      const visible = glyph !== " " && glyph !== "";
+      check((raw.attributes[i]! & ~1) === 0, "unsupported attributes");
+      return {
+        text: visible ? glyph : "",
+        width,
+        fg: visible ? rgb(raw.fg, i) : "ffffff",
+        bg: rgb(raw.bg, i),
+        bold: visible && (raw.attributes[i]! & 1) !== 0,
+      };
+    });
+    check(pos === text.length, "unconsumed text");
+    return row;
+  });
+  return {
+    cells,
+    cursor: { x: raw.cursor.x - 1, y: raw.cursor.y - 1, visible: raw.cursor.visible },
+  };
+}
+export function compareVisual(actual: VisualFrame, expected: VisualFrame): void {
+  check(JSON.stringify(actual.cursor) === JSON.stringify(expected.cursor), "cursor mismatch");
+  check(actual.cells.length === expected.cells.length, "rows mismatch");
+  actual.cells.forEach((row, y) => {
+    check(row.length === expected.cells[y]!.length, "cols mismatch");
+    row.forEach((cell, x) => {
+      for (const key of ["text", "width", "fg", "bg", "bold"] as const)
+        check(cell[key] === expected.cells[y]![x]![key], `${y}:${x}.${key} mismatch`);
+    });
+  });
+}
+
+export function nativeVisualFrame(frame: {
+  cols: number;
+  rows: number;
+  cursor: number[];
+  cells: {
+    text: string;
+    width: number;
+    foreground: string;
+    background: string;
+    attributes: string[];
+  }[][];
+}): VisualFrame {
+  check((frame.cols === 24 || frame.cols === 40) && frame.rows === 8, "native geometry");
+  const color = (value: string, defaultValue: string) => {
+    if (value === "default") return defaultValue;
+    check(/^rgb:[0-9a-f]{6}$/u.test(value), "native color vocabulary");
+    return value.slice(4);
+  };
+  return {
+    cells: frame.cells.map((row) =>
+      row.map((c) => {
+        const visible = c.text !== "" && c.text !== " ";
+        check(
+          c.attributes.every((a) => a === "bold"),
+          "native attribute vocabulary",
+        );
+        return {
+          text: visible ? c.text : "",
+          width: c.width,
+          fg: visible ? color(c.foreground, "ffffff") : "ffffff",
+          bg: color(c.background, "000000"),
+          bold: visible && c.attributes.includes("bold"),
+        };
+      }),
+    ),
+    cursor: { x: frame.cursor[0]!, y: frame.cursor[1]!, visible: true },
+  };
+}
+
+/** Declared workspace chrome: one tab row plus one title row, then eight native rows. */
+export function cropWorkspaceCompletedFrame(raw: CompletedFrame): CompletedFrame {
+  check((raw.cols === 24 || raw.cols === 40) && raw.rows === 10, "workspace geometry");
+  const size = raw.cols * raw.rows;
+  check(
+    raw.char.length === size &&
+      raw.attributes.length === size &&
+      raw.fg.length === size * 4 &&
+      raw.bg.length === size * 4,
+    "workspace buffer lengths",
+  );
+  const lines = raw.text.replace(/\n$/u, "").split("\n");
+  check(lines.length === 10, "workspace line count");
+  check(raw.cursor.y >= 3 && raw.cursor.y <= 10, "workspace cursor outside content");
+  const offset = 2 * raw.cols;
+  return {
+    cols: raw.cols,
+    rows: 8,
+    char: raw.char.slice(offset),
+    attributes: raw.attributes.slice(offset),
+    fg: raw.fg.slice(offset * 4),
+    bg: raw.bg.slice(offset * 4),
+    text: lines.slice(2).join("\n"),
+    cursor: { ...raw.cursor, y: raw.cursor.y - 2 },
+  };
+}

package/packages/daemon-client/src/terminal-fast-lane.ts

@@ -29,6 +29,7 @@ export interface TerminalFastLaneSourcePort {
       update: CanonicalTerminalReplicaUpdate,
       metadata?: TerminalReplicaDeliveryMetadata,
     ) => void,
+    onUnavailable?: (message: string) => void,
   ): () => void;
 }
 
@@ -40,6 +41,7 @@ export interface CanonicalTerminalSubscriptionPort {
       update: CanonicalTerminalReplicaUpdate,
       metadata?: TerminalReplicaDeliveryMetadata,
     ) => void,
+    onUnavailable?: (message: string) => void,
   ) => () => void;
 }
 
@@ -173,7 +175,9 @@ export interface TerminalFastLane {
   subscribePane(
     semanticPaneId: string,
     listener: (publication: TerminalFastLanePublication) => void,
+    onUnavailable?: (message: string) => void,
   ): () => void;
+  paneUnavailable(semanticPaneId: string): string | null;
   paneState(semanticPaneId: string): TerminalReplicaState | null;
   paneLastAcceptedUpdateType(semanticPaneId: string): CanonicalTerminalReplicaUpdate["type"] | null;
   /** Request one coalesced generation repair for a pane whose retained state vanished. */
@@ -193,6 +197,8 @@ interface PaneInterest {
   readonly semanticPaneId: string;
   readonly listeners: Set<(publication: TerminalFastLanePublication) => void>;
   state: TerminalReplicaState | null;
+  unavailable: string | null;
+  readonly unavailableListeners: Set<(message: string) => void>;
   lastAcceptedUpdateType: CanonicalTerminalReplicaUpdate["type"] | null;
   repairPending: boolean;
   release: (() => void) | null;
@@ -384,7 +390,7 @@ export function createTerminalFastLane(options: TerminalFastLaneOptions): Termin
     update: CanonicalTerminalReplicaUpdate,
     metadata?: TerminalReplicaDeliveryMetadata,
   ): void => {
-    if (disposed) return;
+    if (disposed || interest.unavailable) return;
     const traceEnabled = Boolean(metadata?.performanceTraceId && options.onTraceStage);
     const identity = traceEnabled
       ? {
@@ -480,6 +486,25 @@ export function createTerminalFastLane(options: TerminalFastLaneOptions): Termin
       (update, metadata) => {
         if (!disposed && epoch === generationEpoch) accept(interest, update, metadata);
       },
+      (message) => {
+        if (
+          disposed ||
+          epoch !== generationEpoch ||
+          panes.get(interest.semanticPaneId) !== interest
+        )
+          return;
+        interest.unavailable = message;
+        interest.state = null;
+        interest.repairPending = false;
+        for (const listener of [...interest.unavailableListeners]) {
+          try {
+            listener(message);
+          } catch {
+            /* Availability observers cannot interrupt sibling delivery. */
+          }
+        }
+        drainInput();
+      },
     );
   };
 
@@ -506,6 +531,8 @@ export function createTerminalFastLane(options: TerminalFastLaneOptions): Termin
         semanticPaneId,
         listeners: new Set(),
         state: null,
+        unavailable: null,
+        unavailableListeners: new Set<(message: string) => void>(),
         lastAcceptedUpdateType: null,
         repairPending: false,
         release: null,
@@ -587,6 +614,10 @@ export function createTerminalFastLane(options: TerminalFastLaneOptions): Termin
           rejectInput(input, "retired");
           continue;
         }
+        if (panes.get(input.semanticPaneId)?.unavailable) {
+          rejectInput(input, "authority-lost");
+          continue;
+        }
         dispatchInput(input, epoch);
       }
       return;
@@ -635,6 +666,7 @@ export function createTerminalFastLane(options: TerminalFastLaneOptions): Termin
         interest.release?.();
         interest.release = null;
         interest.state = null;
+        interest.unavailable = null;
         interest.lastAcceptedUpdateType = null;
         interest.repairPending = false;
         open(interest);
@@ -669,7 +701,7 @@ export function createTerminalFastLane(options: TerminalFastLaneOptions): Termin
         }
       };
     },
-    subscribePane(semanticPaneId, listener) {
+    subscribePane(semanticPaneId, listener, onUnavailable) {
       if (disposed) return () => undefined;
       if (retainedPaneIds !== null && !retainedPaneIds.has(semanticPaneId)) return () => undefined;
       const interest =
@@ -678,18 +710,31 @@ export function createTerminalFastLane(options: TerminalFastLaneOptions): Termin
           semanticPaneId,
           listeners: new Set(),
           state: null,
+          unavailable: null,
+          unavailableListeners: new Set<(message: string) => void>(),
           lastAcceptedUpdateType: null,
           repairPending: false,
           release: null,
         } satisfies PaneInterest);
       panes.set(semanticPaneId, interest);
       interest.listeners.add(listener);
+      if (onUnavailable) {
+        interest.unavailableListeners.add(onUnavailable);
+        if (interest.unavailable) {
+          try {
+            onUnavailable(interest.unavailable);
+          } catch {
+            /* Availability observers cannot interrupt sibling delivery. */
+          }
+        }
+      }
       open(interest);
       let active = true;
       return () => {
         if (!active) return;
         active = false;
         interest.listeners.delete(listener);
+        if (onUnavailable) interest.unavailableListeners.delete(onUnavailable);
         // Renderer visibility is not terminal-replica lifetime. A pane surface
         // unmounts when its tmux window is not selected, but output can keep
         // arriving while hidden. Retain the one canonical pane replica and its
@@ -699,19 +744,22 @@ export function createTerminalFastLane(options: TerminalFastLaneOptions): Termin
         // bounded by the runtime inventory.
       };
     },
+    paneUnavailable: (semanticPaneId) => panes.get(semanticPaneId)?.unavailable ?? null,
     paneState: (semanticPaneId) => panes.get(semanticPaneId)?.state ?? null,
     paneLastAcceptedUpdateType: (semanticPaneId) =>
       panes.get(semanticPaneId)?.lastAcceptedUpdateType ?? null,
     requestRepair(semanticPaneId, reason) {
       if (disposed) return false;
       const interest = panes.get(semanticPaneId);
-      if (!interest || !isRetainedOrStaged(semanticPaneId)) return false;
+      if (!interest || interest.unavailable || !isRetainedOrStaged(semanticPaneId)) return false;
       const revision = interest.state?.revision ?? 0;
       queueRepair(interest, reason, revision, revision);
       return interest.repairPending;
     },
     sendInput(semanticPaneId, rawInput, performanceTraceId, causalProbe) {
       if (disposed) return Promise.resolve({ status: "rejected", reason: "disposed" });
+      if (panes.get(semanticPaneId)?.unavailable)
+        return Promise.resolve({ status: "rejected", reason: "authority-lost" });
       const parsed = SessionRuntimeTerminalInputSchemaZ.safeParse(rawInput);
       if (!parsed.success) {
         mutableCounters.inputRejected += 1;
@@ -809,13 +857,14 @@ export function createWorkspaceClientTerminalSource(
   client: CanonicalTerminalSubscriptionPort,
 ): TerminalFastLaneSourcePort {
   return {
-    subscribe(address, listener) {
+    subscribe(address, listener, onUnavailable) {
       return client.subscribeTerminal(
         {
           workspaceName: address.workspaceName,
           semanticPaneId: address.semanticPaneId,
         },
         listener,
+        onUnavailable,
       );
     },
   };

package/packages/daemon-client/src/workspace-client-types.ts

@@ -263,6 +263,7 @@ export interface WorkspaceClient<
       update: TerminalReplicaUpdate<TerminalSnapshot, TerminalPatch, TerminalTombstone>,
       metadata?: TerminalReplicaDeliveryMetadata,
     ) => void,
+    onUnavailable?: (message: string) => void,
   ): () => void;
   requestTerminalRepair(
     target: TerminalReplicaAddress,

package/packages/daemon-client/src/workspace-client.ts

@@ -75,6 +75,9 @@ interface TerminalInterest<Snapshot, Patch, Tombstone> {
     ReturnType<WorkspaceClientRuntimePort<Snapshot, Patch, Tombstone>["subscribeTerminal"]>
   > | null;
   unsubscribeUpdate: (() => void) | null;
+  unsubscribeUnavailable: (() => void) | null;
+  unavailable: string | null;
+  readonly unavailableListeners: Set<(message: string) => void>;
   opening: boolean;
 }
 
@@ -89,6 +92,8 @@ interface PreparedTerminalBinding<Snapshot, Patch, Tombstone> {
     ReturnType<WorkspaceClientRuntimePort<Snapshot, Patch, Tombstone>["subscribeTerminal"]>
   >;
   readonly unsubscribeUpdate: () => void;
+  readonly unsubscribeUnavailable: () => void;
+  unavailable: string | null;
   readonly pending: Array<{
     readonly update: TerminalReplicaUpdate<Snapshot, Patch, Tombstone>;
     readonly metadata?: TerminalReplicaDeliveryMetadata;
@@ -518,6 +523,9 @@ export function createWorkspaceClient<
     interest: TerminalInterest<TerminalSnapshot, TerminalPatch, TerminalTombstone>,
   ): Promise<void> => {
     interest.opening = false;
+    interest.unsubscribeUnavailable?.();
+    interest.unsubscribeUnavailable = null;
+    interest.unavailable = null;
     interest.unsubscribeUpdate?.();
     interest.unsubscribeUpdate = null;
     const subscription = interest.subscription;
@@ -534,6 +542,7 @@ export function createWorkspaceClient<
     const closing: Promise<void>[] = [];
     for (const binding of prepared.bindings.values()) {
       binding.unsubscribeUpdate();
+      binding.unsubscribeUnavailable();
       closing.push(closeSubscription(binding.subscription));
     }
     prepared.bindings.clear();
@@ -562,6 +571,19 @@ export function createWorkspaceClient<
       }
     }
   };
+  const publishUnavailable = (
+    interest: TerminalInterest<TerminalSnapshot, TerminalPatch, TerminalTombstone>,
+    message: string,
+  ): void => {
+    interest.unavailable = message;
+    for (const listener of [...interest.unavailableListeners]) {
+      try {
+        listener(message);
+      } catch {
+        /* One pane observer cannot interrupt siblings. */
+      }
+    }
+  };
   const openTerminal = (
     interest: TerminalInterest<TerminalSnapshot, TerminalPatch, TerminalTombstone>,
   ): void => {
@@ -591,8 +613,19 @@ export function createWorkspaceClient<
           return closeSubscription(subscription);
         }
         interest.subscription = subscription;
+        interest.unsubscribeUnavailable =
+          subscription.onUnavailable?.((message) => {
+            if (
+              disposed ||
+              generation !== expectedGeneration ||
+              runtime !== expectedRuntime ||
+              interest.subscription !== subscription
+            )
+              return;
+            publishUnavailable(interest, message);
+          }) ?? null;
         interest.unsubscribeUpdate = subscription.onUpdate((update, metadata) => {
-          if (generation !== expectedGeneration) return;
+          if (generation !== expectedGeneration || interest.unavailable) return;
           publishTerminalUpdate(interest, expectedRuntime, update, metadata);
         });
       })
@@ -702,12 +735,17 @@ export function createWorkspaceClient<
         for (const binding of bindings) {
           binding.interest.subscription = binding.subscription;
           binding.interest.unsubscribeUpdate = binding.unsubscribeUpdate;
+          binding.interest.unsubscribeUnavailable = binding.unsubscribeUnavailable;
           binding.interest.opening = false;
         }
         prepared.bindings.clear();
         owner.prepared = null;
         prepared.activated = true;
         for (const binding of bindings) {
+          if (binding.unavailable) {
+            publishUnavailable(binding.interest, binding.unavailable);
+            binding.pending.length = 0;
+          }
           for (const delivery of binding.pending) {
             publishTerminalUpdate(
               binding.interest,
@@ -778,8 +816,9 @@ export function createWorkspaceClient<
               TerminalPatch,
               TerminalTombstone
             >["pending"] = [];
+            let subscriptionUnavailable = false;
             const unsubscribeUpdate = subscription.onUpdate((update, metadata) => {
-              if (prepared.closed) return;
+              if (prepared.closed || subscriptionUnavailable) return;
               if (prepared.activated) {
                 publishTerminalUpdate(interest, nextRuntime, update, metadata);
                 return;
@@ -821,12 +860,31 @@ export function createWorkspaceClient<
               await closeSubscription(subscription);
               return;
             }
-            prepared.bindings.set(key, {
+            const binding = {
               interest,
               subscription,
               unsubscribeUpdate,
+              unsubscribeUnavailable: () => {},
+              unavailable: null as string | null,
               pending,
-            });
+            };
+            binding.unsubscribeUnavailable =
+              subscription.onUnavailable?.((message) => {
+                if (
+                  prepared.closed ||
+                  disposed ||
+                  generation !== owner.clientGeneration ||
+                  (activeRuntimeOwner !== owner && candidateRuntimeOwner !== owner) ||
+                  terminals.get(key) !== interest
+                )
+                  return;
+                subscriptionUnavailable = true;
+                binding.unavailable = message;
+                binding.pending.length = 0;
+                if (prepared.activated && runtime === nextRuntime)
+                  publishUnavailable(interest, message);
+              }) ?? (() => {});
+            prepared.bindings.set(key, binding);
           }),
         ];
       });
@@ -1327,7 +1385,7 @@ export function createWorkspaceClient<
         throw error;
       }
     },
-    subscribeTerminal(nextTarget, listener) {
+    subscribeTerminal(nextTarget, listener, onUnavailable) {
       if (disposed) return () => undefined;
       const key = terminalKey(nextTarget);
       const interest =
@@ -1337,19 +1395,34 @@ export function createWorkspaceClient<
           listeners: new Set(),
           subscription: null,
           unsubscribeUpdate: null,
+          unsubscribeUnavailable: null,
+          unavailable: null,
+          unavailableListeners: new Set<(message: string) => void>(),
           opening: false,
         } satisfies TerminalInterest<TerminalSnapshot, TerminalPatch, TerminalTombstone>);
       terminals.set(key, interest);
       interest.listeners.add(listener);
+      if (onUnavailable) {
+        interest.unavailableListeners.add(onUnavailable);
+        if (interest.unavailable) {
+          try {
+            onUnavailable(interest.unavailable);
+          } catch {
+            /* Availability observers cannot interrupt sibling delivery. */
+          }
+        }
+      }
       openTerminal(interest);
       return () => {
         interest.listeners.delete(listener);
+        if (onUnavailable) interest.unavailableListeners.delete(onUnavailable);
         if (interest.listeners.size > 0) return;
         for (const owner of [activeRuntimeOwner, candidateRuntimeOwner]) {
           const prepared = owner?.prepared?.bindings.get(key);
           if (!prepared) continue;
           owner!.prepared!.bindings.delete(key);
           prepared.unsubscribeUpdate();
+          prepared.unsubscribeUnavailable();
           void closeSubscription(prepared.subscription);
         }
         terminals.delete(key);

package/packages/tmux-bridge/src/index.ts

@@ -1,6 +1,7 @@
 export { TmuxError } from "./errors.ts";
 export {
   runTmux,
+  configureTmuxClientResolver,
   runTmuxBinary,
   runTmuxBinaryAsync,
   classifyTmuxError,

package/packages/tmux-bridge/src/runner.ts

@@ -58,11 +58,35 @@ export function _getSpawner(): Spawner {
   return _spawner;
 }
 
+type TmuxClientResolver = (
+  environment: NodeJS.ProcessEnv,
+  cwd?: string | URL,
+) => {
+  executable: string;
+  environment: NodeJS.ProcessEnv;
+};
+
+let clientResolver: TmuxClientResolver | undefined;
+
+/** Configure ordinary clients at the host composition root; pinned runners are unaffected. */
+export function configureTmuxClientResolver(resolver: TmuxClientResolver): () => void {
+  const previous = clientResolver;
+  clientResolver = resolver;
+  return () => {
+    clientResolver = previous;
+  };
+}
+
 export function runTmux(args: string[], options: ExecFileSyncOptions = {}): string | Buffer {
   if ((options.env ?? process.env).TMUX_IDE_RUNTIME_MODE === "development") {
     throw new Error("Development tmux operations require an explicitly pinned namespace runner");
   }
-  return runTmuxBinary("tmux", args, options);
+  const resolved = clientResolver?.(options.env ?? process.env, options.cwd);
+  return runTmuxBinary(
+    resolved?.executable ?? "tmux",
+    args,
+    resolved ? { ...options, env: resolved.environment } : options,
+  );
 }
 
 /**