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

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

@@ -0,0 +1,105 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { createHash, randomUUID } from "node:crypto";
+import {
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  writeFileSync,
+  realpathSync,
+  unlinkSync,
+} from "node:fs";
+import { dirname } from "node:path";
+import { z } from "zod";
+import { tmuxClientEnvironment } from "./tmux-client-execution.ts";
+import {
+  captureUnixSocketIdentity,
+  revalidateUnixSocketIdentity,
+} from "./unix-socket-authority.ts";
+import {
+  MAX_TMUX_SERVER_OWNERS,
+  TmuxServerRegistrationSchemaZ,
+  type TmuxServerObservation,
+  type TmuxServerRegistration,
+} from "./tmux-server-owners.ts";
+
+const exec = promisify(execFile);
+const FileSchema = z
+  .object({
+    version: z.literal(1),
+    servers: z.array(TmuxServerRegistrationSchemaZ).max(MAX_TMUX_SERVER_OWNERS),
+  })
+  .strict()
+  .superRefine((file, ctx) => {
+    if (new Set(file.servers.map((server) => server.serverId)).size !== file.servers.length)
+      ctx.addIssue({ code: "custom", message: "Duplicate server registration" });
+  });
+export function readTmuxServerRegistrations(path: string): readonly TmuxServerRegistration[] {
+  try {
+    return FileSchema.parse(JSON.parse(readFileSync(path, "utf8"))).servers;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
+    throw error;
+  }
+}
+export function writeTmuxServerRegistrations(
+  path: string,
+  registrations: readonly TmuxServerRegistration[],
+): void {
+  const file = FileSchema.parse({ version: 1, servers: registrations });
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  const temporary = `${path}.${randomUUID()}.tmp`;
+  try {
+    writeFileSync(temporary, `${JSON.stringify(file, null, 2)}\n`, { mode: 0o600, flag: "wx" });
+    renameSync(temporary, path);
+  } finally {
+    try {
+      unlinkSync(temporary);
+    } catch {
+      /* rename already removed it */
+    }
+  }
+}
+/** Discovery never creates a server, loads configuration, or attaches a client. */
+export function createTmuxServerProbe(
+  executable: string,
+): (selector: TmuxServerRegistration["selector"]) => Promise<TmuxServerObservation | null> {
+  const executablePath = realpathSync(executable);
+  const env = tmuxClientEnvironment(process.env);
+  return async (selector) => {
+    const args = selector.kind === "path" ? ["-S", selector.path] : ["-L", selector.name];
+    const read = async (selection: readonly string[]) =>
+      (
+        await exec(
+          executablePath,
+          [...selection, "-N", "display-message", "-p", "#{socket_path}|#{pid}|#{start_time}"],
+          { env, encoding: "utf8", timeout: 500, maxBuffer: 8192 },
+        )
+      ).stdout.trimEnd();
+    try {
+      const first = await read(args);
+      const match = /^(.*)\|([1-9][0-9]*)\|([1-9][0-9]*)$/u.exec(first);
+      if (!match) return null;
+      const socket = captureUnixSocketIdentity(match[1]!);
+      if ((await read(["-S", socket.path])) !== first) return null;
+      revalidateUnixSocketIdentity(socket);
+      return {
+        nativeServerIdentity: { pid: match[2]!, startTime: match[3]! },
+        fingerprint: createHash("sha256")
+          .update(JSON.stringify([socket.path, match[2], match[3]]))
+          .digest("hex"),
+        authority: { executablePath, socketSelector: { kind: "path", path: socket.path } },
+        valid: () => {
+          try {
+            revalidateUnixSocketIdentity(socket);
+            return true;
+          } catch {
+            return false;
+          }
+        },
+      };
+    } catch {
+      return null;
+    }
+  };
+}

package/packages/daemon/src/lib/tmux-server-session-create.ts

@@ -0,0 +1,52 @@
+import {
+  WorkspaceSessionCreateArgumentsSchemaZ,
+  type WorkspaceSessionCreateArguments,
+  type WorkspaceSessionCreateResult,
+} from "@tmux-ide/contracts";
+import { FleetLifecycleAuthority } from "./fleet-lifecycle-authority.ts";
+import type { WorkspaceRegistry } from "./workspace-registry.ts";
+
+/** Bounded online-server creation. The existing lifecycle owns idempotency and workspace naming. */
+export function createNativeTmuxSessionCreator(options: {
+  generation: string;
+  registry: WorkspaceRegistry;
+  run(args: readonly string[]): string;
+  assertOpen(): void;
+}) {
+  let disposed = false;
+  const pending = new Set<Promise<WorkspaceSessionCreateResult>>();
+  const assertOpen = () => {
+    options.assertOpen();
+    if (disposed) throw new Error("Session creation is retired");
+  };
+  const authority = new FleetLifecycleAuthority({
+    daemonInstanceId: options.generation,
+    productVersion: "scoped-owner",
+    startedAt: new Date().toISOString(),
+    registry: options.registry,
+    runTmux(args) {
+      assertOpen();
+      return options.run(args);
+    },
+    readFleet: () => [],
+    ensureChromeUpdater: false,
+  });
+  return {
+    createSession(operationId: string, input: WorkspaceSessionCreateArguments) {
+      assertOpen();
+      const parsed = WorkspaceSessionCreateArgumentsSchemaZ.parse(input);
+      if (parsed.expectedDaemonInstanceId && parsed.expectedDaemonInstanceId !== options.generation)
+        throw new Error("Selected tmux server generation changed");
+      if (pending.size >= 16) throw new Error("Session creation capacity reached");
+      const operation = authority
+        .createSession(operationId, options.generation, parsed)
+        .finally(() => pending.delete(operation));
+      pending.add(operation);
+      return operation;
+    },
+    async dispose() {
+      disposed = true;
+      await Promise.allSettled([...pending]);
+    },
+  };
+}

package/packages/daemon/src/lib/tmux-server-session-open.ts

@@ -0,0 +1,106 @@
+import { randomUUID } from "node:crypto";
+import { WorkspaceCatalogLiveSessionIdSchemaZ } from "@tmux-ide/contracts";
+import { liveSessionIdForNativeIdentity } from "../terminal/protocol/live-session-identity.ts";
+import { fleetSessionIdForName } from "../command-center/resources/fleet-catalog.ts";
+import { isVisibleFleetSession } from "../command-center/discovery.ts";
+import { WorkspacePromotionAuthority } from "./workspace-promotion.ts";
+import type { WorkspaceRegistry } from "./workspace-registry.ts";
+import { shellEscape } from "./shell.ts";
+
+/** Owner-local bounded admission; all native IO must already fence the server generation. */
+export function createNativeTmuxSessionOpener(options: {
+  generation: string;
+  registry: WorkspaceRegistry;
+  run(args: readonly string[]): Promise<string>;
+  assertOpen(): void;
+}) {
+  let disposed = false;
+  let tail: Promise<unknown> = Promise.resolve();
+  const pending = new Map<string, Promise<{ workspaceName: string; liveSessionId: string }>>();
+  const assertOpen = () => {
+    options.assertOpen();
+    if (disposed) throw new Error("Session admission is retired");
+  };
+  const open = async (liveSessionId: string) => {
+    assertOpen();
+    const records = await options.run([
+      "list-sessions",
+      "-F",
+      "#{pid}\t#{session_id}\t#{session_created}\t#{session_name}",
+    ]);
+    const matches = records
+      .trim()
+      .split("\n")
+      .map((line) => line.split("\t"))
+      .filter(
+        ([pid, id, created, name]) =>
+          pid &&
+          /^\d+$/.test(pid) &&
+          id &&
+          /^\$\d+$/.test(id) &&
+          created &&
+          /^\d+$/.test(created) &&
+          name &&
+          isVisibleFleetSession(name) &&
+          liveSessionIdForNativeIdentity(pid, id, created) === liveSessionId,
+      );
+    if (matches.length !== 1) throw new Error("Selected live tmux session is no longer available");
+    const [, nativeSessionId, created, name] = matches[0]!;
+    // Each command checks the exact native session on the server accepting it.
+    // A name-only validation followed by stamping would cross a session replacement.
+    const run = async (args: readonly string[]) => {
+      assertOpen();
+      const sentinel = `tmux-session-stale.${randomUUID()}`;
+      const condition = `#{&&:#{==:#{session_id},${nativeSessionId}},#{==:#{session_created},${created}}}`;
+      const command = args.map((arg) => (arg === ";" ? ";" : shellEscape(arg))).join(" ");
+      const output = await options.run([
+        "if-shell",
+        "-t",
+        nativeSessionId!,
+        "-F",
+        condition,
+        command,
+        `display-message -p '${sentinel}'`,
+      ]);
+      assertOpen();
+      if (output.trim() === sentinel)
+        throw new Error("Selected live tmux session changed during admission");
+      return output;
+    };
+    const promotion = new WorkspacePromotionAuthority({
+      daemonInstanceId: options.generation,
+      registry: options.registry,
+      io: { runTmux: run },
+    });
+    try {
+      const result = await promotion.promote({
+        operationId: randomUUID(),
+        expectedDaemonInstanceId: options.generation,
+        intent: { sessionId: fleetSessionIdForName(name!) },
+      });
+      await run(["display-message", "-p", "-t", nativeSessionId!, "#{session_id}"]);
+      return { workspaceName: result.resource.workspaceName, liveSessionId };
+    } finally {
+      await promotion.dispose();
+    }
+  };
+  return {
+    openSession(liveSessionId: string) {
+      WorkspaceCatalogLiveSessionIdSchemaZ.parse(liveSessionId);
+      assertOpen();
+      const previous = pending.get(liveSessionId);
+      if (previous) return previous;
+      if (pending.size >= 16) throw new Error("Session admission capacity reached");
+      const operation = tail
+        .then(() => open(liveSessionId))
+        .finally(() => pending.delete(liveSessionId));
+      pending.set(liveSessionId, operation);
+      tail = operation.catch(() => {});
+      return operation;
+    },
+    async dispose() {
+      disposed = true;
+      await tail;
+    },
+  };
+}

package/packages/daemon/src/lib/tmux-servers-cli.ts

@@ -0,0 +1,186 @@
+import { randomUUID } from "node:crypto";
+import {
+  SavedMachineSchema,
+  TmuxServerIdSchemaZ,
+  TmuxServerRegistrationRequestSchemaZ,
+  WorkspaceSessionCreateArgumentsSchemaZ,
+  type TmuxServerRegistrationRequest,
+} from "@tmux-ide/contracts";
+import {
+  createTmuxServerClient,
+  listTmuxServers,
+  registerTmuxServer,
+  removeTmuxServer,
+  TmuxServerClientError,
+  type TmuxServerClientOptions,
+} from "@tmux-ide/daemon-client/tmux-server-client";
+import { canonicalDaemonUrl } from "./canonical-daemon.ts";
+import { ensureCanonicalDaemon } from "./canonical-daemon-bootstrap.ts";
+import { openSshDaemonTransport } from "./ssh-daemon-transport.ts";
+import { loadSavedMachines } from "./saved-machines.ts";
+
+export interface TmuxServersCliOptions {
+  readonly command?: string;
+  readonly serverId?: string;
+  readonly socketName?: string;
+  readonly socketPath?: string;
+  readonly label?: string;
+  readonly sessionName?: string;
+  readonly cwd?: string;
+  readonly ssh?: string;
+}
+type Operation =
+  | { command: "list" }
+  | { command: "add"; registration: TmuxServerRegistrationRequest }
+  | { command: "remove" | "sessions"; serverId: string }
+  | { command: "create"; serverId: string; input: { displayName: string; cwd?: string } };
+
+/** Parse before acquiring a transport; invalid input cannot start a daemon. */
+export function parseTmuxServersOperation(options: TmuxServersCliOptions): Operation {
+  const command = options.command ?? "list";
+  if (options.ssh !== undefined) SavedMachineSchema.shape.sshTarget.parse(options.ssh);
+  if (command === "create") {
+    if (
+      options.socketName !== undefined ||
+      options.socketPath !== undefined ||
+      options.label !== undefined
+    )
+      throw new Error("servers create requires a registered server ID and --session-name NAME");
+    return {
+      command,
+      serverId: TmuxServerIdSchemaZ.parse(options.serverId),
+      input: WorkspaceSessionCreateArgumentsSchemaZ.parse({
+        displayName: options.sessionName,
+        ...(options.cwd ? { cwd: options.cwd } : {}),
+      }),
+    };
+  }
+  if (options.sessionName !== undefined || options.cwd !== undefined)
+    throw new Error("--session-name and --dir are only supported by servers create");
+  if (command === "add") {
+    if (
+      options.serverId ||
+      (options.socketName === undefined) === (options.socketPath === undefined)
+    )
+      throw new Error(
+        "servers add requires exactly one of --socket-name NAME or --socket-path /PATH",
+      );
+    return {
+      command,
+      registration: TmuxServerRegistrationRequestSchemaZ.parse({
+        label: options.label ?? options.socketName ?? "Custom server",
+        selector:
+          options.socketName !== undefined
+            ? { kind: "name", name: options.socketName }
+            : { kind: "path", path: options.socketPath },
+      }),
+    };
+  }
+  if (
+    options.socketName !== undefined ||
+    options.socketPath !== undefined ||
+    options.label !== undefined
+  )
+    throw new Error("Socket selectors and --name are only supported by servers add");
+  if (command === "list" && options.serverId === undefined) return { command };
+  if (command === "remove" || command === "sessions")
+    return { command, serverId: TmuxServerIdSchemaZ.parse(options.serverId) };
+  throw new Error(
+    "Usage: tmux-ide servers list|add|remove <server-id>|sessions <server-id>|create <server-id> --session-name NAME [--ssh HOST] [--json]",
+  );
+}
+
+export interface TmuxServersCliConnection {
+  readonly client: TmuxServerClientOptions;
+  dispose(): void;
+}
+export async function connectTmuxServersCli(options: {
+  readonly ssh?: string;
+  readonly entryPath: string;
+  readonly expectedProductVersion?: string;
+}): Promise<TmuxServersCliConnection> {
+  const hostClientId = randomUUID();
+  if (options.ssh !== undefined) {
+    const transport = await openSshDaemonTransport({ alias: options.ssh });
+    try {
+      const expected = loadSavedMachines().machines.find(
+        (machine) => machine.sshTarget === options.ssh,
+      )?.expectedEnvironmentId;
+      if (expected && transport.daemon.environmentId !== expected)
+        throw new Error("SSH route reached a different environment than the saved profile");
+      return {
+        client: {
+          baseUrl: transport.baseUrl,
+          ownerToken: transport.daemon.authToken,
+          hostClientId,
+          origin: transport.baseUrl,
+        },
+        dispose: () => transport.dispose(),
+      };
+    } catch (error) {
+      transport.dispose();
+      throw error;
+    }
+  }
+  // Server registration addresses the daemon, not the invoking shell's tmux server.
+  const { candidate } = await ensureCanonicalDaemon({
+    entryPath: options.entryPath,
+    expectedProductVersion: options.expectedProductVersion,
+    tmuxServerIntent: null,
+  });
+  if (!candidate.authToken)
+    throw new Error("Daemon owner authority is unavailable; update the local daemon");
+  const baseUrl = canonicalDaemonUrl("http", candidate.bindHostname, candidate.port);
+  return {
+    client: { baseUrl, ownerToken: candidate.authToken, hostClientId, origin: baseUrl },
+    dispose() {},
+  };
+}
+
+export async function runTmuxServersCli(
+  options: TmuxServersCliOptions,
+  connect: () => Promise<TmuxServersCliConnection>,
+): Promise<unknown> {
+  const operation = parseTmuxServersOperation(options);
+  const connection = await connect();
+  try {
+    // Probe the versioned resource before writes. An older daemon is unsupported,
+    // never a reason to execute a raw command against a default server.
+    let catalog;
+    try {
+      catalog = await listTmuxServers(connection.client);
+    } catch (error) {
+      if (error instanceof TmuxServerClientError && [404, 405, 426].includes(error.status ?? 0))
+        throw new Error(
+          "This daemon does not support tmux server selection; update the selected machine's daemon",
+          { cause: error },
+        );
+      throw error;
+    }
+    if (operation.command === "list") return catalog;
+    if (operation.command === "add")
+      return await registerTmuxServer(connection.client, operation.registration);
+    const server = catalog.servers.find((candidate) => candidate.serverId === operation.serverId);
+    if (!server)
+      throw new Error("Selected tmux server is not registered; run tmux-ide servers list");
+    if (operation.command === "remove") {
+      await removeTmuxServer(connection.client, server.serverId);
+      return { removed: true, serverId: server.serverId };
+    }
+    if (server.state !== "online")
+      throw new Error("Selected tmux server is offline; no session operation was attempted");
+    const client = createTmuxServerClient(connection.client, {
+      serverId: server.serverId,
+      generation: server.generation,
+    });
+    try {
+      return operation.command === "create"
+        ? await client.createSession(randomUUID(), operation.input)
+        : await client.sessions();
+    } finally {
+      client.dispose();
+    }
+  } finally {
+    connection.dispose();
+  }
+}

package/packages/daemon/src/lib/tmux-session-mutation-fence.ts

@@ -0,0 +1,62 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { randomUUID } from "node:crypto";
+import { WorkspaceCatalogLiveSessionIdSchemaZ } from "@tmux-ide/contracts";
+import { liveSessionIdForNativeIdentity } from "../terminal/protocol/live-session-identity.ts";
+import { shellEscape } from "./shell.ts";
+
+/** Session identity travels with the mutation lane, never in global mutable selection. */
+export function createTmuxSessionMutationFence() {
+  const context = new AsyncLocalStorage<{ id: string; created: string; name: string }>();
+  return {
+    wrap(run: (args: readonly string[]) => string) {
+      return (args: readonly string[]) => {
+        const selected = context.getStore();
+        if (!selected) return run(args);
+        const sentinel = `tmux-session-stale.${randomUUID()}`;
+        const output = run([
+          "if-shell",
+          "-t",
+          `=${selected.name}`,
+          "-F",
+          `#{&&:#{==:#{session_id},${selected.id}},#{==:#{session_created},${selected.created}}}`,
+          args.map((arg) => (arg === ";" ? ";" : shellEscape(arg))).join(" "),
+          `display-message -p '${sentinel}'`,
+        ]);
+        if (output.trim() === sentinel)
+          throw new Error("Selected live tmux session changed before mutation");
+        return output;
+      };
+    },
+    async execute<T>(options: {
+      liveSessionId: string;
+      sessionName: string;
+      run(args: readonly string[]): Promise<string>;
+      mutate(): Promise<T>;
+    }): Promise<T> {
+      WorkspaceCatalogLiveSessionIdSchemaZ.parse(options.liveSessionId);
+      const raw = await options.run([
+        "list-sessions",
+        "-F",
+        "#{pid}\t#{session_id}\t#{session_created}\t#{session_name}",
+      ]);
+      const rows = raw
+        .trim()
+        .split("\n")
+        .map((line) => line.split("\t"))
+        .filter(
+          ([pid, id, created, name]) =>
+            pid &&
+            /^\d+$/.test(pid) &&
+            id &&
+            /^\$\d+$/.test(id) &&
+            created &&
+            /^\d+$/.test(created) &&
+            name === options.sessionName &&
+            liveSessionIdForNativeIdentity(pid, id, created) === options.liveSessionId,
+        );
+      if (rows.length !== 1) throw new Error("Selected live tmux session is no longer available");
+      const [, id, created] = rows[0]!;
+      return context.run({ id: id!, created: created!, name: options.sessionName }, options.mutate);
+    },
+  };
+}

package/packages/daemon/src/lib/tmux-window-link-guard.ts

@@ -0,0 +1,112 @@
+/** Private native boundary: callers must resolve opaque link handles and fence
+ * daemon/server/session generation before using this command. Never accept native
+ * addresses from clients. Execute argv through the pinned runner without a shell.
+ */
+export interface NativeWindowLinkAddress {
+  sessionId: string;
+  windowIndex: number;
+  expectedWindowId: string;
+  expectedServerPid?: string;
+  expectedSessionCreated?: string;
+}
+
+export const WINDOW_LINK_GUARD_APPLIED = "link-guard.ok";
+export const WINDOW_LINK_GUARD_STALE = "link-guard.stale";
+
+/** if-shell -F and its first branch command do not yield in tmux's command queue.
+ * Keep the mutation first and synchronous. Do not insert run-shell/wait-for/UI.
+ * This checks a current tuple, not an immutable historical winlink (tmux has none).
+ * Use buildNativeWindowLinkPaneSelectGuard for guarded compound pane selection.
+ */
+export function buildNativeWindowLinkGuard(
+  address: NativeWindowLinkAddress,
+  action: "select" | "unlink",
+): string[] {
+  const { sessionId, windowIndex, expectedWindowId } = address;
+  if (
+    !/^\$(?:0|[1-9]\d{0,15})$/u.test(sessionId) ||
+    !/^@(?:0|[1-9]\d{0,15})$/u.test(expectedWindowId) ||
+    !Number.isSafeInteger(Number(sessionId.slice(1))) ||
+    !Number.isSafeInteger(Number(expectedWindowId.slice(1))) ||
+    !Number.isSafeInteger(windowIndex) ||
+    windowIndex < 0 ||
+    (address.expectedServerPid !== undefined &&
+      !/^[1-9][0-9]{0,15}$/u.test(address.expectedServerPid)) ||
+    (address.expectedSessionCreated !== undefined &&
+      !/^(?:0|[1-9][0-9]{0,15})$/u.test(address.expectedSessionCreated)) ||
+    (action !== "select" && action !== "unlink")
+  ) {
+    throw new Error("Invalid native window link guard address or action");
+  }
+  const target = `${sessionId}:${windowIndex}`;
+  // CANFAIL target lookup makes all three comparisons necessary for missing targets.
+  let condition = `#{&&:#{==:#{session_id},${sessionId}},#{&&:#{==:#{window_index},${windowIndex}},#{==:#{window_id},${expectedWindowId}}}}`;
+  if (address.expectedServerPid !== undefined)
+    condition = `#{&&:#{==:#{pid},${address.expectedServerPid}},${condition}}`;
+  if (address.expectedSessionCreated !== undefined)
+    condition = `#{&&:#{==:#{session_created},${address.expectedSessionCreated}},${condition}}`;
+  const verb = action === "select" ? "select-window" : "unlink-window";
+  // Validated native IDs/index contain no quote, separator, or format syntax.
+  return [
+    "if-shell",
+    "-F",
+    "-t",
+    target,
+    condition,
+    `${verb} -t '${target}' ; display-message -p '${WINDOW_LINK_GUARD_APPLIED}'`,
+    `display-message -p '${WINDOW_LINK_GUARD_STALE}'`,
+  ];
+}
+
+/** Select an exact link and pane while preserving native user hooks. The window
+ * selection hook may yield or move topology, so revalidate after it. A failed
+ * second check is indeterminate: the window selection may already have happened.
+ */
+export function buildNativeWindowLinkPaneSelectGuard(
+  address: NativeWindowLinkAddress,
+  paneId: string,
+): string[] {
+  const windowGuard = buildNativeWindowLinkGuard(address, "select");
+  if (!/^%(?:0|[1-9]\d{0,15})$/u.test(paneId) || !Number.isSafeInteger(Number(paneId.slice(1)))) {
+    throw new Error("Invalid native pane guard address");
+  }
+  const target = `${address.sessionId}:${address.windowIndex}`;
+  const paneCondition = `#{&&:#{==:#{pane_id},${paneId}},#{==:#{window_id},${address.expectedWindowId}}}`;
+  const stale = `display-message -p '${WINDOW_LINK_GUARD_STALE}'`;
+  const interrupted = "display-message -p 'link-guard.interrupted'";
+  // All interpolated IDs are canonical numeric native identities. Braces are
+  // tmux command groups, not a host shell or a caller-provided command language.
+  const linkCheck = (yes: string, no: string) =>
+    `if-shell -F -t '${target}' '${windowGuard[4]!}' { ${yes} } { ${no} }`;
+  const paneCheck = (yes: string, no: string) =>
+    `if-shell -F -t '${paneId}' '${paneCondition}' { ${yes} } { ${no} }`;
+  const selectPane = `select-pane -t '${paneId}' ; display-message -p '${WINDOW_LINK_GUARD_APPLIED}'`;
+  const afterHook = paneCheck(linkCheck(selectPane, interrupted), interrupted);
+  return [
+    "if-shell",
+    "-F",
+    "-t",
+    paneId,
+    paneCondition,
+    linkCheck(`select-window -t '${target}' ; ${afterHook}`, stale),
+    stale,
+  ];
+}
+
+/** Consume only output associated with this request's own native command boundary.
+ * Nonzero completion reports native failure, including last-link unlink refusal.
+ * For compound selection this can follow partial mutation; it is not rollback proof.
+ * Missing/extra output or interrupted completion is indeterminate, never success;
+ * it must not trigger an automatic retry of a potentially completed mutation.
+ */
+export function classifyNativeWindowLinkGuardResult(
+  status: number | null,
+  stdout: string,
+): "applied" | "stale" | "native-refused" | "indeterminate" {
+  if (status === null) return "indeterminate";
+  if (status !== 0) return "native-refused";
+  const output = stdout.trim();
+  if (output === WINDOW_LINK_GUARD_APPLIED) return "applied";
+  if (output === WINDOW_LINK_GUARD_STALE) return "stale";
+  return "indeterminate";
+}

package/packages/daemon/src/lib/workspace-config-loader.ts

@@ -1,3 +1,6 @@
+// Consumers outside the daemon tsconfig need the bundled declaration as well.
+// eslint-disable-next-line @typescript-eslint/triple-slash-reference
+/// <reference path="../js-yaml.d.ts" />
 /**
  * Side-effect-free loader for repository-scoped WorkspaceConfigV1 files.
  *