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

package/packages/daemon/src/lib/tmux-server-owner.ts

@@ -0,0 +1,336 @@
+import { createNativeTmuxSessionCreator } from "./tmux-server-session-create.ts";
+import type { WorkspacePaneCreateMutationRequest } from "@tmux-ide/contracts";
+import { createTmuxSessionMutationFence } from "./tmux-session-mutation-fence.ts";
+import { createNativeTmuxSessionOpener } from "./tmux-server-session-open.ts";
+import { randomUUID } from "node:crypto";
+import { mkdirSync } from "node:fs";
+import { z } from "zod";
+import type { WorkspaceMultiplexerBackend } from "../command-center/actions/handlers/workspace-multiplexer.ts";
+import { isVisibleFleetSession, type LiveSessionSummary } from "../command-center/discovery.ts";
+import { WorkspaceTerminalInventoryRuntime } from "../terminal/attachments/native-runtime.ts";
+import { createTmuxAgentStatusProbe } from "../terminal/attachments/agent-status-probe.ts";
+import { createPaneStreamRuntime } from "../terminal/pane-stream/runtime.ts";
+import { liveSessionIdForNativeIdentity } from "../terminal/protocol/live-session-identity.ts";
+import { SessionRuntimeRegistry } from "../terminal/session-runtime/registry.ts";
+import { createSessionRuntimeMultiplexerBackend } from "../terminal/session-runtime/multiplexer-backend.ts";
+import { TmuxExternalInteractionObserver } from "./tmux-external-interaction-observer.ts";
+import { WorkspaceMultiplexerAuthority } from "./workspace-multiplexer-verbs.ts";
+import {
+  WorkspacePaneCreationAuthority,
+  type WorkspacePaneTmuxAuthority,
+} from "./workspace-pane-creation.ts";
+import { WorkspaceRegistry } from "./workspace-registry.ts";
+import {
+  createServerGenerationFencedTmuxRunner,
+  createServerGenerationFencedTmuxAsyncRunner,
+  type NativeTmuxServerIdentity,
+} from "./tmux-server-generation-runner.ts";
+
+export interface NativeTmuxServerOwnerOptions {
+  readonly serverId: string;
+  readonly generation: string;
+  readonly tmuxAuthority: WorkspacePaneTmuxAuthority;
+  readonly stateDirectory: string;
+  readonly webSocketUrl: string;
+  readonly nativeServerIdentity?: NativeTmuxServerIdentity;
+}
+
+/** Refresh discovered live membership without changing durable workspace intent or aliases. */
+export function createNativeTmuxServerCatalog(
+  workspaceRegistry: WorkspaceRegistry,
+  run: (args: readonly string[], signal?: AbortSignal) => Promise<string>,
+  assertOpen: () => void = () => undefined,
+): () => Promise<LiveSessionSummary[]> {
+  return async (): Promise<LiveSessionSummary[]> => {
+    assertOpen();
+    const raw = await run(
+      [
+        "list-panes",
+        "-a",
+        "-F",
+        "#{pid}\t#{session_id}\t#{session_created}\t#{session_name}\t#{pane_id}\t#{session_path}",
+      ],
+      AbortSignal.timeout(2_000),
+    );
+    assertOpen();
+    const rows = new Map<
+      string,
+      { summary: LiveSessionSummary; panes: Set<string>; dir: string }
+    >();
+    for (const line of raw.trim().split("\n")) {
+      const [pid, id, created, name, pane, dir] = line.split("\t");
+      if (
+        !pid ||
+        !/^\d+$/.test(pid) ||
+        !id ||
+        !/^\$\d+$/.test(id) ||
+        !created ||
+        !/^\d+$/.test(created) ||
+        !name ||
+        !pane ||
+        !/^%\d+$/.test(pane) ||
+        !dir
+      )
+        throw new Error("Invalid native server catalog");
+      if (!isVisibleFleetSession(name)) continue;
+      const liveSessionId = liveSessionIdForNativeIdentity(pid, id, created);
+      const row = rows.get(liveSessionId) ?? {
+        summary: { liveSessionId, sessionName: name, paneCount: 0 },
+        panes: new Set<string>(),
+        dir,
+      };
+      row.panes.add(pane);
+      rows.set(liveSessionId, row);
+    }
+    const names = new Set([...rows.values()].map(({ summary }) => summary.sessionName));
+    for (const workspace of workspaceRegistry.list())
+      if (workspaceRegistry.isVolatile(workspace.name) && !names.has(workspace.sessionName))
+        workspaceRegistry.remove(workspace.name);
+    for (const { summary, dir } of rows.values())
+      if (
+        !workspaceRegistry.has(summary.sessionName) &&
+        !workspaceRegistry.list().some((workspace) => workspace.sessionName === summary.sessionName)
+      )
+        workspaceRegistry.add({
+          name: summary.sessionName,
+          sessionName: summary.sessionName,
+          projectDir: dir,
+          persistence: "volatile",
+        });
+    return [...rows.values()].map(({ summary, panes }) => ({ ...summary, paneCount: panes.size }));
+  };
+}
+
+/** One proven server incarnation. Never elects an endpoint or changes ambient tmux authority. */
+export async function createNativeTmuxServerOwner(options: NativeTmuxServerOwnerOptions) {
+  const generation = z.uuid().parse(options.generation);
+  const authority = options.tmuxAuthority;
+  if (authority.socketSelector.kind !== "path") {
+    throw new Error("A server owner requires a proven direct socket authority");
+  }
+  const socketPath = authority.socketSelector.path;
+  mkdirSync(options.stateDirectory, { recursive: true, mode: 0o700 });
+  const workspaceRegistry = new WorkspaceRegistry({
+    dir: options.stateDirectory,
+    listSessions: () => [],
+  });
+  const sessionMutationFence = createTmuxSessionMutationFence();
+  const generationRun = sessionMutationFence.wrap(
+    createServerGenerationFencedTmuxRunner(authority, options.nativeServerIdentity),
+  );
+  const identityParts = generationRun(["display-message", "-p", "#{pid}\t#{start_time}"]).split(
+    "\t",
+  );
+  const nativeServerIdentity = options.nativeServerIdentity ?? {
+    pid: identityParts[0]!,
+    startTime: identityParts[1]!,
+  };
+  const generationRunAsync = createServerGenerationFencedTmuxAsyncRunner(
+    authority,
+    nativeServerIdentity,
+  );
+  const multiplexer = new WorkspaceMultiplexerAuthority({
+    daemonInstanceId: generation,
+    registry: workspaceRegistry,
+    tmuxAuthority: authority,
+    io: { runTmux: generationRun },
+  });
+  const paneCreation = new WorkspacePaneCreationAuthority({
+    daemonInstanceId: generation,
+    registry: workspaceRegistry,
+    tmuxAuthority: authority,
+    io: { runTmux: generationRun },
+  });
+  let disposed = false;
+  let disposePromise: Promise<void> | null = null;
+  let observerStarted: Promise<void> | null = null;
+  let receiptSequence = 0;
+  const assertOpen = () => {
+    if (disposed) throw new Error("Tmux server owner is retired");
+  };
+  const sessionRuntimeRegistry: SessionRuntimeRegistry = new SessionRuntimeRegistry({
+    generation,
+    semanticMutations: {
+      resolveSession: (name) => workspaceRegistry.get(name)?.sessionName ?? null,
+      execute: (operationId, intent, timing) => {
+        assertOpen();
+        if (intent.verb === "workspace.pane.read") return multiplexer.readPane(operationId, intent);
+        if (
+          intent.verb === "workspace.window.link.select" ||
+          intent.verb === "workspace.window.link.unlink" ||
+          intent.verb === "workspace.pane.select"
+        ) {
+          return multiplexer.mutateWindowLink(
+            { operationId, expectedDaemonInstanceId: generation, intent },
+            (session, action) => sessionRuntimeRegistry.executeWindowLinkAction(session, action),
+          );
+        }
+        return multiplexer.mutate(
+          { operationId, expectedDaemonInstanceId: generation, intent },
+          timing,
+        );
+      },
+      publishReceipt: (receipt) => ({
+        ...receipt,
+        type: "interaction.receipt",
+        sequence: ++receiptSequence,
+      }),
+      traceAuthority: { generation, incarnation: null },
+    },
+    mirror: {
+      executable: authority.executablePath,
+      socketPath,
+      resolveSocketPath: () => generationRun(["display-message", "-p", "#{socket_path}"]),
+      nativeServerIdentity,
+      internalReadHookEmission: (pane, marker) => observer.internalReadHookEmission(pane, marker),
+    },
+  });
+  const terminalInventoryRuntime = new WorkspaceTerminalInventoryRuntime({
+    registry: workspaceRegistry,
+    sessionRuntimeRegistry,
+    tmuxAuthority: { ...authority, trustedCwd: options.stateDirectory, nativeServerIdentity },
+    agentStatusProbeFactory: ({ run }) => createTmuxAgentStatusProbe({ run }),
+    onInventory: (snapshot) => multiplexer.adoptPaneInventory(snapshot.panes),
+    onSessionInventory: (session, snapshot) =>
+      multiplexer.adoptSessionPaneInventory(session, snapshot?.panes ?? []),
+  });
+  const observer: TmuxExternalInteractionObserver = new TmuxExternalInteractionObserver({
+    daemonInstanceId: generation,
+    internalReadOwnerToken: randomUUID(),
+    registry: workspaceRegistry,
+    tmuxAuthority: authority,
+    io: { runTmux: generationRunAsync },
+    onGap: () => terminalInventoryRuntime.invalidate(),
+    onObserved: ({ workspaceName, semanticPaneId, operationKind, operationId }) =>
+      operationId !== null &&
+      sessionRuntimeRegistry.observeTmuxInteraction({
+        workspaceName,
+        semanticPaneId,
+        operationKind,
+        operationId,
+      }),
+  });
+  const paneStreamRuntime = createPaneStreamRuntime({
+    daemonInstanceId: generation,
+    webSocketUrl: options.webSocketUrl,
+    sessionRuntimeRegistry,
+    semanticPaneCatalog: terminalInventoryRuntime.semanticPaneCatalog,
+  });
+  const backend = createSessionRuntimeMultiplexerBackend({
+    registry: sessionRuntimeRegistry,
+    resolveSession: (name) => workspaceRegistry.get(name)?.sessionName ?? null,
+  });
+  const catalog = createNativeTmuxServerCatalog(workspaceRegistry, generationRunAsync, assertOpen);
+  const sessionCreator = createNativeTmuxSessionCreator({
+    generation,
+    registry: workspaceRegistry,
+    run: generationRun,
+    assertOpen,
+  });
+  const sessionOpener = createNativeTmuxSessionOpener({
+    generation,
+    registry: workspaceRegistry,
+    run: generationRunAsync,
+    assertOpen,
+  });
+  const openSession = async (liveSessionId: string) => {
+    await catalog();
+    const result = await sessionOpener.openSession(liveSessionId);
+    terminalInventoryRuntime.invalidate();
+    return result;
+  };
+  const multiplexerBackend: WorkspaceMultiplexerBackend = {
+    mutate: async (...args) => {
+      assertOpen();
+      if (args[0].expectedDaemonInstanceId !== generation)
+        throw new Error("Tmux server generation mismatch");
+      await catalog();
+      observerStarted ??= observer.start();
+      await observerStarted;
+      assertOpen();
+      return backend.mutate(...args);
+    },
+  };
+  const dispose = (): Promise<void> => {
+    if (disposePromise) return disposePromise;
+    disposed = true;
+    disposePromise = (async () => {
+      await sessionOpener.dispose();
+      await sessionCreator.dispose();
+      await paneCreation.dispose();
+      try {
+        await paneStreamRuntime.dispose();
+      } finally {
+        try {
+          await observer.dispose();
+        } finally {
+          terminalInventoryRuntime.dispose();
+          try {
+            await multiplexer.dispose();
+          } finally {
+            await sessionRuntimeRegistry.dispose();
+          }
+        }
+      }
+    })();
+    return disposePromise;
+  };
+  try {
+    await terminalInventoryRuntime.whenReady();
+    await catalog();
+  } catch (error) {
+    await dispose();
+    throw error;
+  }
+  return {
+    serverId: options.serverId,
+    generation,
+    catalog,
+    openSession,
+    createSession: sessionCreator.createSession,
+    createSessionPane: async (
+      liveSessionId: string,
+      request: WorkspacePaneCreateMutationRequest,
+    ) => {
+      assertOpen();
+      await catalog();
+      const sessionName = workspaceRegistry.get(request.intent.workspaceName)?.sessionName;
+      if (!sessionName) throw new Error("Selected workspace is unavailable");
+      const result = await sessionMutationFence.execute({
+        liveSessionId,
+        sessionName,
+        run: generationRunAsync,
+        mutate: () => paneCreation.create(request),
+      });
+      terminalInventoryRuntime.invalidate();
+      return result;
+    },
+    mutateSession: async (
+      liveSessionId: string,
+      request: Parameters<WorkspaceMultiplexerBackend["mutate"]>[0],
+      authenticatedHostClientId?: string,
+    ) => {
+      assertOpen();
+      await catalog();
+      const sessionName = workspaceRegistry.get(request.intent.workspaceName)?.sessionName;
+      if (!sessionName) throw new Error("Selected workspace is unavailable");
+      observerStarted ??= observer.start();
+      await observerStarted;
+      return sessionMutationFence.execute({
+        liveSessionId,
+        sessionName,
+        run: generationRunAsync,
+        mutate: () =>
+          multiplexerBackend.mutate(request, authenticatedHostClientId, undefined, true),
+      });
+    },
+    workspaceRegistry,
+    multiplexerBackend,
+    sessionRuntimeRegistry,
+    terminalInventoryRuntime,
+    paneStreamRuntime,
+    dispose,
+  };
+}
+
+export type NativeTmuxServerOwner = Awaited<ReturnType<typeof createNativeTmuxServerOwner>>;

package/packages/daemon/src/lib/tmux-server-owners.ts

@@ -0,0 +1,228 @@
+import { randomUUID } from "node:crypto";
+import { z } from "zod";
+import {
+  TmuxServerIdSchemaZ,
+  TmuxServerRegistrationRequestSchemaZ,
+  TmuxServerScopeSchemaZ,
+  type TmuxServerScope,
+  type TmuxServerDescriptor,
+} from "@tmux-ide/contracts";
+import type { WorkspacePaneTmuxAuthority } from "./workspace-pane-creation.ts";
+
+// Admission limits, not performance claims. Discovery is explicit/on-demand.
+export const MAX_TMUX_SERVER_OWNERS = 16;
+export const TmuxServerSelectorSchemaZ = TmuxServerRegistrationRequestSchemaZ.shape.selector;
+export const TmuxServerRegistrationSchemaZ = TmuxServerRegistrationRequestSchemaZ.extend({
+  serverId: TmuxServerIdSchemaZ,
+}).strict();
+export type TmuxServerRegistration = z.infer<typeof TmuxServerRegistrationSchemaZ>;
+export interface TmuxServerObservation {
+  /** Private canonical path/server PID/start-time proof, never a public identity. */
+  readonly fingerprint: string;
+  readonly nativeServerIdentity?: { readonly pid: string; readonly startTime: string };
+  readonly authority: WorkspacePaneTmuxAuthority;
+  /** Synchronous socket fence. No subprocess on input or rendering paths. */
+  readonly valid: () => boolean;
+}
+export interface DisposableTmuxServerOwner {
+  dispose(): Promise<void>;
+}
+export class TmuxServerScopeError extends Error {
+  constructor(
+    readonly code: "not-found" | "offline" | "stale-generation" | "capacity" | "disposed",
+  ) {
+    super(`tmux server ${code}`);
+    this.name = "TmuxServerScopeError";
+  }
+}
+type Entry<T> = {
+  registration: TmuxServerRegistration;
+  observation: TmuxServerObservation | null;
+  scope: TmuxServerScope | null;
+  owner: T | null;
+};
+export interface TmuxServerOwnersOptions<T extends DisposableTmuxServerOwner> {
+  readonly probe: (
+    selector: TmuxServerRegistration["selector"],
+  ) => Promise<TmuxServerObservation | null>;
+  readonly create: (
+    registration: TmuxServerRegistration,
+    scope: TmuxServerScope,
+    observation: TmuxServerObservation,
+  ) => Promise<T>;
+  readonly persist?: (registrations: readonly TmuxServerRegistration[]) => void;
+}
+/** One process; no shared mutable tmux authority, runtime cache or retry ledger. */
+export class TmuxServerOwners<T extends DisposableTmuxServerOwner> {
+  readonly #entries = new Map<string, Entry<T>>();
+  #tail: Promise<unknown> = Promise.resolve();
+  #disposed = false;
+  #disposePromise: Promise<void> | null = null;
+  constructor(readonly options: TmuxServerOwnersOptions<T>) {}
+  #serial<R>(work: () => Promise<R>): Promise<R> {
+    const run = this.#tail.then(() => {
+      if (this.#disposed) throw new TmuxServerScopeError("disposed");
+      return work();
+    });
+    this.#tail = run.catch(() => undefined);
+    return run;
+  }
+  #descriptor(entry: Entry<T>): TmuxServerDescriptor {
+    return entry.scope
+      ? { ...entry.scope, label: entry.registration.label, state: "online" }
+      : {
+          serverId: entry.registration.serverId,
+          generation: null,
+          label: entry.registration.label,
+          state: "offline",
+        };
+  }
+  list(): readonly TmuxServerDescriptor[] {
+    return [...this.#entries.values()].map((entry) => this.#descriptor(entry));
+  }
+  registrations(): readonly TmuxServerRegistration[] {
+    return [...this.#entries.values()].map((entry) => structuredClone(entry.registration));
+  }
+  #save(): void {
+    this.options.persist?.(this.registrations());
+  }
+  async #retire(entry: Entry<T>): Promise<void> {
+    const owner = entry.owner;
+    entry.owner = null;
+    entry.scope = null;
+    entry.observation = null;
+    if (owner) await owner.dispose();
+  }
+  async #refresh(entry: Entry<T>, observed?: TmuxServerObservation | null): Promise<void> {
+    const next =
+      observed === undefined ? await this.options.probe(entry.registration.selector) : observed;
+    if (next && entry.observation?.fingerprint === next.fingerprint && entry.observation.valid())
+      return;
+    // Absence revokes command/stream leases without claiming native server death.
+    // Socket recreation also needs a fresh connection authority, even if PID survived.
+    await this.#retire(entry);
+    if (this.#disposed || !next || !next.valid()) return;
+    const duplicate = [...this.#entries.values()].find(
+      (other) =>
+        other !== entry &&
+        other.observation?.fingerprint === next.fingerprint &&
+        other.observation.valid(),
+    );
+    if (duplicate) return; // Never construct a second owner for a proven live alias.
+    const scope = { serverId: entry.registration.serverId, generation: randomUUID() };
+    let owner: T;
+    try {
+      owner = await this.options.create(entry.registration, scope, next);
+    } catch {
+      return;
+    } // Registration remains visible/offline; explicit refresh retries.
+    if (this.#disposed || !next.valid()) {
+      await owner.dispose();
+      return;
+    }
+    entry.observation = next;
+    entry.scope = scope;
+    entry.owner = owner;
+  }
+  register(
+    input: Omit<TmuxServerRegistration, "serverId"> & { serverId?: string },
+  ): Promise<TmuxServerDescriptor> {
+    return this.#serial(async () => {
+      const registration = TmuxServerRegistrationSchemaZ.parse({
+        ...input,
+        serverId: input.serverId ?? `tmux-server.${randomUUID().replaceAll("-", "")}`,
+      });
+      const sameSelector = [...this.#entries.values()].find(
+        (entry) =>
+          JSON.stringify(entry.registration.selector) === JSON.stringify(registration.selector),
+      );
+      if (sameSelector) {
+        await this.#refresh(sameSelector);
+        return this.#descriptor(sameSelector);
+      }
+      if (this.#entries.has(registration.serverId))
+        throw new TypeError("Server registration already exists");
+      const observation = await this.options.probe(registration.selector);
+      if (this.#disposed) throw new TmuxServerScopeError("disposed");
+      const alias =
+        observation &&
+        [...this.#entries.values()].find(
+          (entry) =>
+            entry.observation?.fingerprint === observation.fingerprint && entry.observation.valid(),
+        );
+      if (alias) return this.#descriptor(alias);
+      if (this.#entries.size >= MAX_TMUX_SERVER_OWNERS) throw new TmuxServerScopeError("capacity");
+      const entry: Entry<T> = { registration, observation: null, scope: null, owner: null };
+      this.#entries.set(registration.serverId, entry);
+      try {
+        this.#save();
+      } catch (error) {
+        this.#entries.delete(registration.serverId);
+        throw error;
+      }
+      await this.#refresh(entry, observation);
+      return this.#descriptor(entry);
+    });
+  }
+  /** Adopt the existing default owner rather than creating a duplicate mirror. */
+  adopt(
+    registrationInput: TmuxServerRegistration,
+    scopeInput: TmuxServerScope,
+    observation: TmuxServerObservation,
+    owner: T,
+  ): void {
+    const registration = TmuxServerRegistrationSchemaZ.parse(registrationInput);
+    const scope = TmuxServerScopeSchemaZ.parse(scopeInput);
+    if (scope.serverId !== registration.serverId || this.#entries.size || this.#disposed)
+      throw new TypeError("Invalid default owner adoption");
+    this.#entries.set(scope.serverId, { registration, scope, observation, owner });
+  }
+  refresh(): Promise<readonly TmuxServerDescriptor[]> {
+    return this.#serial(async () => {
+      // Sequential admission bounds subprocess work and avoids alias races.
+      for (const entry of this.#entries.values()) await this.#refresh(entry);
+      return this.list();
+    });
+  }
+  current(scopeInput: TmuxServerScope): T {
+    const scope = TmuxServerScopeSchemaZ.parse(scopeInput);
+    if (this.#disposed) throw new TmuxServerScopeError("disposed");
+    const entry = this.#entries.get(scope.serverId);
+    if (!entry) throw new TmuxServerScopeError("not-found");
+    if (!entry.scope || !entry.owner) throw new TmuxServerScopeError("offline");
+    if (entry.scope.generation !== scope.generation || !entry.observation?.valid())
+      throw new TmuxServerScopeError("stale-generation");
+    return entry.owner;
+  }
+  async withOwner<R>(scope: TmuxServerScope, work: (owner: T) => Promise<R>): Promise<R> {
+    const owner = this.current(scope);
+    const result = await work(owner);
+    if (this.current(scope) !== owner) throw new TmuxServerScopeError("stale-generation");
+    return result;
+  }
+  remove(serverId: string): Promise<void> {
+    return this.#serial(async () => {
+      const entry = this.#entries.get(TmuxServerIdSchemaZ.parse(serverId));
+      if (!entry) throw new TmuxServerScopeError("not-found");
+      this.#entries.delete(serverId);
+      try {
+        this.#save();
+      } catch (error) {
+        this.#entries.set(serverId, entry);
+        throw error;
+      }
+      await this.#retire(entry); // never kill-server or kill-session
+    });
+  }
+  dispose(): Promise<void> {
+    if (this.#disposePromise) return this.#disposePromise;
+    this.#disposed = true;
+    this.#disposePromise = (async () => {
+      await this.#tail;
+      const entries = [...this.#entries.values()];
+      this.#entries.clear();
+      await Promise.allSettled(entries.map((entry) => this.#retire(entry)));
+    })();
+    return this.#disposePromise;
+  }
+}

package/packages/daemon/src/lib/tmux-server-proof.ts

@@ -0,0 +1,95 @@
+import { realpathSync, statSync } from "node:fs";
+import { isNamedSocketAuthorityUnbound } from "./tmux-named-socket-fence.ts";
+import type { WorkspacePaneTmuxAuthority } from "./workspace-pane-creation.ts";
+import { createHash } from "node:crypto";
+import {
+  captureUnixSocketIdentity,
+  revalidateUnixSocketIdentity,
+} from "./unix-socket-authority.ts";
+
+export interface TmuxServerProof {
+  readonly version: 1;
+  readonly kind: "live" | "unbound-name";
+  readonly digest: string;
+}
+
+/** Two read-only, no-start queries fence the socket and server incarnation. */
+export function captureTmuxServerProof(
+  run: (args: readonly string[]) => string,
+): TmuxServerProof | null {
+  const args = ["-N", "display-message", "-p", "#{socket_path}|#{pid}|#{start_time}"];
+  try {
+    const raw = run(args).trimEnd();
+    const match = /^(.*)\|([1-9][0-9]*)\|([1-9][0-9]*)$/u.exec(raw);
+    if (!match || raw.length > 8192) return null;
+    const socket = captureUnixSocketIdentity(match[1]!);
+    if (run(args).trimEnd() !== raw) return null;
+    revalidateUnixSocketIdentity(socket);
+    return {
+      version: 1,
+      kind: "live",
+      digest: createHash("sha256")
+        .update(JSON.stringify([socket.path, match[2], match[3]]))
+        .digest("hex"),
+    };
+  } catch {
+    return null;
+  }
+}
+
+export async function captureTmuxServerProofAsync(
+  run: (args: readonly string[]) => Promise<string>,
+): Promise<TmuxServerProof | null> {
+  const args = ["-N", "display-message", "-p", "#{socket_path}|#{pid}|#{start_time}"];
+  try {
+    const raw = (await run(args)).trimEnd();
+    const match = /^(.*)\|([1-9][0-9]*)\|([1-9][0-9]*)$/u.exec(raw);
+    if (!match || raw.length > 8192) return null;
+    const socket = captureUnixSocketIdentity(match[1]!);
+    if ((await run(args)).trimEnd() !== raw) return null;
+    revalidateUnixSocketIdentity(socket);
+    return {
+      version: 1,
+      kind: "live",
+      digest: createHash("sha256")
+        .update(JSON.stringify([socket.path, match[2], match[3]]))
+        .digest("hex"),
+    };
+  } catch {
+    return null;
+  }
+}
+
+/** A selector commitment is not evidence of an absent or live server. */
+export function captureUnboundTmuxSelectorProof(
+  authority: WorkspacePaneTmuxAuthority,
+): TmuxServerProof | null {
+  if (!isNamedSocketAuthorityUnbound(authority) || authority.socketSelector.kind !== "name")
+    return null;
+  try {
+    const executable = realpathSync(authority.executablePath);
+    const stat = statSync(executable, { bigint: true });
+    const uid = process.getuid?.();
+    if (uid === undefined || !stat.isFile()) return null;
+    return {
+      version: 1,
+      kind: "unbound-name",
+      digest: createHash("sha256")
+        .update(
+          JSON.stringify([
+            "sanitized-tmux-environment-v1",
+            executable,
+            String(stat.dev),
+            String(stat.ino),
+            String(stat.mtimeNs),
+            String(stat.size),
+            uid,
+            authority.socketSelector.name,
+          ]),
+        )
+        .digest("hex"),
+    };
+  } catch {
+    return null;
+  }
+}