@vellumai/credential-executor 0.11.2-dev.202608060701.ede4331 → 0.11.2-dev.202608062308.5442cf1

package/Dockerfile

@@ -56,6 +56,7 @@ COPY --from=builder --chown=ces:ces /app /app
 COPY --chown=ces:ces packages/service-contracts /app/packages/service-contracts
 COPY --chown=ces:ces packages/credential-storage /app/packages/credential-storage
 COPY --chown=ces:ces packages/egress-proxy /app/packages/egress-proxy
+COPY --chown=ces:ces packages/ipc-server-utils /app/packages/ipc-server-utils
 COPY --chown=ces:ces credential-executor ./
 
 # Pre-create /ces-data so the non-root ces user can write to it

package/knip.json

@@ -4,6 +4,7 @@
   "ignoreDependencies": [
     "@vellumai/service-contracts",
     "@vellumai/credential-storage",
-    "@vellumai/egress-proxy"
+    "@vellumai/egress-proxy",
+    "@vellumai/ipc-server-utils"
   ]
 }

package/node_modules/@vellumai/ipc-server-utils/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@vellumai/ipc-server-utils",
+  "version": "0.0.1",
+  "private": true,
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "typecheck": "bunx tsc --noEmit",
+    "test": "bun test src/"
+  },
+  "devDependencies": {
+    "@types/bun": "1.3.10",
+    "typescript": "5.9.3"
+  }
+}

package/node_modules/@vellumai/ipc-server-utils/src/endpoint.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, test } from "bun:test";
+import { existsSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { removeIpcEndpointFile, resolveIpcEndpoint } from "./endpoint.js";
+const windowsEndpoint = (name: string, workspaceDir: string) => resolveIpcEndpoint(name, { workspaceDir, platform: "win32" });
+describe("resolveIpcEndpoint", () => {
+  test("keeps long POSIX fallbacks deterministic and bounded", () => {
+    const options = {
+      workspaceDir: `/tmp/${"a".repeat(120)}`,
+      platform: "darwin" as const,
+    };
+    const endpoint = resolveIpcEndpoint("assistant", options);
+    expect(resolveIpcEndpoint("assistant", options)).toEqual(endpoint);
+    expect(Buffer.byteLength(endpoint.path)).toBeLessThanOrEqual(103);
+  });
+  test("returns normalized, isolated, bounded Windows pipes", () => {
+    const first = windowsEndpoint("assistant", "C:\\one");
+    expect(resolveIpcEndpoint("assistant", { workspaceDir: "c:\\ONE\\", platform: "win32", env: { ASSISTANT_IPC_SOCKET_DIR: "C:\\ignored" } })).toEqual(first);
+    expect(first.path.length).toBeLessThanOrEqual(256);
+    expect(windowsEndpoint("assistant", "C:\\two").path).not.toBe(first.path);
+    expect(windowsEndpoint("gateway", "C:\\one").path).not.toBe(first.path);
+  });
+  test("cleans socket files but skips named pipes", () => {
+    const dir = mkdtempSync(join(tmpdir(), "vellum-ipc-cleanup-"));
+    const socketPath = join(dir, "assistant.sock");
+    try {
+      writeFileSync(socketPath, "stale");
+      removeIpcEndpointFile(socketPath);
+      expect(existsSync(socketPath)).toBe(false);
+      removeIpcEndpointFile("\\\\.\\pipe\\vellum-assistant-test");
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});

package/node_modules/@vellumai/ipc-server-utils/src/endpoint.ts

@@ -0,0 +1,142 @@
+import { createHash } from "node:crypto";
+import { unlinkSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { posix, win32 } from "node:path";
+
+const DARWIN_UNIX_SOCKET_MAX_PATH_BYTES = 103;
+const DEFAULT_UNIX_SOCKET_MAX_PATH_BYTES = 107;
+const IPC_TMP_DIR_NAME = "vellum-ipc";
+const join = posix.join;
+
+export type IpcSocketPathSource =
+  | "env-override"
+  | "workspace"
+  | "tmp-hash"
+  | "tmp-short-hash"
+  | "windows-named-pipe";
+
+export interface IpcSocketPathResolution {
+  path: string;
+  source: IpcSocketPathSource;
+}
+
+export interface IpcEndpointOptions {
+  workspaceDir: string;
+  env?: Record<string, string | undefined>;
+  platform?: NodeJS.Platform;
+}
+
+function getUnixSocketMaxPathBytes(platform: NodeJS.Platform): number {
+  return platform === "darwin"
+    ? DARWIN_UNIX_SOCKET_MAX_PATH_BYTES
+    : DEFAULT_UNIX_SOCKET_MAX_PATH_BYTES;
+}
+
+function isPathWithinSocketLimit(path: string, maxPathBytes: number): boolean {
+  return Buffer.byteLength(path, "utf8") <= maxPathBytes;
+}
+
+/**
+ * Derive the env var name and socket filename from a socket name.
+ *
+ * Examples (hyphens in the name become underscores in the env var):
+ */
+function deriveSocketNames(socketName: string): {
+  envVar: string;
+  fileName: string;
+} {
+  if (!/^[a-z][a-z0-9-]{0,63}$/.test(socketName)) {
+    throw new Error(`Invalid IPC endpoint name: ${socketName}`);
+  }
+  const envVar = `${socketName.toUpperCase().replace(/-/g, "_")}_IPC_SOCKET_DIR`;
+  const fileName = `${socketName}.sock`;
+  return { envVar, fileName };
+}
+
+function resolveWindowsNamedPipe(
+  socketName: string,
+  workspaceDir: string,
+): IpcSocketPathResolution {
+  const workspaceIdentity = win32
+    .normalize(workspaceDir)
+    .replace(/\\+$/, "")
+    .toLowerCase();
+  const hash = createHash("sha256")
+    .update(`${workspaceIdentity}\0${socketName}`)
+    .digest("hex")
+    .slice(0, 24);
+  return {
+    path: `\\\\.\\pipe\\vellum-${socketName}-${hash}`,
+    source: "windows-named-pipe",
+  };
+}
+
+export function isNamedPipePath(endpointPath: string): boolean {
+  return /^\\\\[.?]\\pipe\\/.test(endpointPath);
+}
+
+export function removeIpcEndpointFile(endpointPath: string): void {
+  if (isNamedPipePath(endpointPath)) {
+    return;
+  }
+  try {
+    unlinkSync(endpointPath);
+  } catch {
+    // Already absent.
+  }
+}
+
+/**
+ * Resolve the path to an IPC socket file.
+ *
+ * Resolution order:
+ * POSIX uses overrides, workspace paths, then bounded temporary paths.
+ * Windows uses deterministic named pipes.
+ */
+export function resolveIpcEndpoint(
+  socketName: string,
+  options: IpcEndpointOptions,
+): IpcSocketPathResolution {
+  const { envVar, fileName } = deriveSocketNames(socketName);
+  const platform = options.platform ?? process.platform;
+  if (platform === "win32") {
+    return resolveWindowsNamedPipe(socketName, options.workspaceDir);
+  }
+
+  // Explicit override via env var.
+  const envSocketDir = (options.env ?? process.env)[envVar]?.trim();
+  if (envSocketDir) {
+    return {
+      path: join(envSocketDir, fileName),
+      source: "env-override",
+    };
+  }
+
+  const maxPathBytes = getUnixSocketMaxPathBytes(platform);
+  const workspacePath = join(options.workspaceDir, fileName);
+
+  if (isPathWithinSocketLimit(workspacePath, maxPathBytes)) {
+    return {
+      path: workspacePath,
+      source: "workspace",
+    };
+  }
+
+  // Workspace path exceeds AF_UNIX limit - fall back to tmpdir.
+  const hash = createHash("sha256")
+    .update(workspacePath)
+    .digest("hex")
+    .slice(0, 12);
+  const hashedPath = join(tmpdir(), IPC_TMP_DIR_NAME, `${hash}-${fileName}`);
+  if (isPathWithinSocketLimit(hashedPath, maxPathBytes)) {
+    return {
+      path: hashedPath,
+      source: "tmp-hash",
+    };
+  }
+
+  return {
+    path: join(tmpdir(), `v-${hash}.sock`),
+    source: "tmp-short-hash",
+  };
+}

package/node_modules/@vellumai/ipc-server-utils/src/index.ts

@@ -0,0 +1,18 @@
+export {
+  SocketWatchdog,
+  ensureSocketDir,
+  type SocketWatchdogOptions,
+  type SocketWatchdogLogger,
+} from "./socket-watchdog.js";
+export { isNamedPipePath, removeIpcEndpointFile, resolveIpcEndpoint } from "./endpoint.js";
+export { ipcListenOptions } from "./listen-options.js";
+export {
+  IpcFrameReader,
+  writeLegacyMessage,
+  writeMessage,
+  writeStreamChunk,
+  writeStreamEnd,
+  type IpcEnvelope,
+  type OnMessageCallback,
+  type StreamCallbacks,
+} from "./ipc-framing.js";

package/node_modules/@vellumai/ipc-server-utils/src/ipc-framing.ts

@@ -0,0 +1,295 @@
+/**
+ * Length-prefixed binary framing for the IPC protocol.
+ *
+ * Wire format: [4-byte big-endian length][payload bytes]
+ *
+ * Messages use a JSON envelope. When the envelope's `headers` map contains
+ * a `content-length` key, a single binary data frame immediately follows
+ * the JSON frame.
+ *
+ * Chunked streaming: when `headers["transfer-encoding"]` is `"chunked"`,
+ * multiple binary data frames follow the JSON envelope. A zero-length
+ * frame (4 bytes of 0x00) terminates the stream. This enables streaming
+ * responses (e.g. audio, SSE) over IPC without buffering the full payload.
+ *
+ * Backward compatibility: the reader detects legacy newline-delimited JSON
+ * by checking if the first byte is `{` (0x7B). New-format frames always
+ * start with a 4-byte length prefix whose first byte is < 0x7B for any
+ * realistic message size (< 2 GB).
+ */
+
+import type { Socket } from "node:net";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface IpcEnvelope {
+  id: string;
+  // Request fields
+  method?: string;
+  params?: Record<string, unknown>;
+  // Response fields
+  result?: unknown;
+  error?: string;
+  // Shared — when headers["content-length"] is present, a binary frame follows.
+  // When headers["transfer-encoding"] is "chunked", multiple binary frames
+  // follow until a zero-length terminator.
+  headers?: Record<string, string>;
+}
+
+// ---------------------------------------------------------------------------
+// Writing
+// ---------------------------------------------------------------------------
+
+/** Write a length-prefixed frame to a socket. */
+function writeFrame(socket: Socket, data: Buffer | Uint8Array): void {
+  const header = Buffer.alloc(4);
+  header.writeUInt32BE(data.length, 0);
+  socket.write(header);
+  socket.write(data);
+}
+
+/**
+ * Write an IPC envelope, optionally followed by a binary data frame.
+ * If `binary` is provided, the envelope's headers must include content-length.
+ */
+export function writeMessage(
+  socket: Socket,
+  envelope: IpcEnvelope,
+  binary?: Uint8Array,
+): void {
+  const json = Buffer.from(JSON.stringify(envelope), "utf-8");
+  writeFrame(socket, json);
+  if (binary) {
+    writeFrame(socket, binary);
+  }
+}
+
+/**
+ * Write a legacy newline-delimited JSON message.
+ * Used when the client connected with the legacy protocol.
+ */
+export function writeLegacyMessage(
+  socket: Socket,
+  envelope: IpcEnvelope,
+): void {
+  socket.write(JSON.stringify(envelope) + "\n");
+}
+
+/**
+ * Write a single chunk in a chunked transfer stream.
+ * The envelope must have already been sent with transfer-encoding: chunked.
+ */
+export function writeStreamChunk(socket: Socket, chunk: Uint8Array): void {
+  writeFrame(socket, chunk);
+}
+
+/**
+ * Write a zero-length frame to signal the end of a chunked transfer stream.
+ */
+export function writeStreamEnd(socket: Socket): void {
+  const terminator = Buffer.alloc(4); // 4 bytes of 0x00 = length 0
+  socket.write(terminator);
+}
+
+// ---------------------------------------------------------------------------
+// Reading
+// ---------------------------------------------------------------------------
+
+/** Callback for complete messages (non-streaming). */
+export type OnMessageCallback = (
+  envelope: IpcEnvelope,
+  binary: Uint8Array | undefined,
+) => void;
+
+/** Callbacks for chunked streaming responses. */
+export interface StreamCallbacks {
+  onStreamStart: (envelope: IpcEnvelope) => void;
+  onStreamChunk: (chunk: Uint8Array) => void;
+  onStreamEnd: () => void;
+}
+
+/**
+ * Streaming reader that accumulates socket data and emits parsed messages.
+ * Handles both legacy newline-delimited JSON and new length-prefixed frames.
+ *
+ * Supports three response modes:
+ * 1. JSON-only: envelope with no binary follow-up
+ * 2. Binary: envelope with content-length → single binary frame
+ * 3. Chunked: envelope with transfer-encoding: chunked → multiple binary
+ *    frames terminated by a zero-length frame
+ */
+export class IpcFrameReader {
+  private buffer = Buffer.alloc(0);
+  private onMessage: OnMessageCallback;
+  private onError: (err: Error) => void;
+  private streamCallbacks: StreamCallbacks | undefined;
+
+  // State machine for length-prefixed reading
+  private state:
+    | "detect"
+    | "read-length"
+    | "read-payload"
+    | "read-binary"
+    | "read-stream-chunk-length"
+    | "read-stream-chunk" = "detect";
+  private pendingLength = 0;
+  private pendingEnvelope: IpcEnvelope | null = null;
+  private expectBinary = false;
+
+  /** Whether this connection uses the legacy newline-delimited protocol. */
+  isLegacy = false;
+
+  constructor(
+    onMessage: OnMessageCallback,
+    onError?: (err: Error) => void,
+    streamCallbacks?: StreamCallbacks,
+  ) {
+    this.onMessage = onMessage;
+    this.onError = onError ?? (() => {});
+    this.streamCallbacks = streamCallbacks;
+  }
+
+  /** Feed incoming socket data into the reader. */
+  push(chunk: Buffer): void {
+    this.buffer = Buffer.concat([this.buffer, chunk]);
+    this.drain();
+  }
+
+  private drain(): void {
+    while (true) {
+      if (this.state === "detect") {
+        if (this.buffer.length === 0) {
+          return;
+        }
+        // Legacy detection: first byte is '{' (0x7B)
+        if (this.buffer[0] === 0x7b) {
+          this.isLegacy = true;
+          this.drainLegacy();
+          return;
+        }
+        // New format — fall through to read-length
+        this.state = "read-length";
+      }
+
+      if (this.state === "read-length") {
+        if (this.buffer.length < 4) {
+          return;
+        }
+        this.pendingLength = this.buffer.readUInt32BE(0);
+        this.buffer = this.buffer.subarray(4);
+        this.state = this.expectBinary ? "read-binary" : "read-payload";
+      }
+
+      if (this.state === "read-payload") {
+        if (this.buffer.length < this.pendingLength) {
+          return;
+        }
+        const payload = this.buffer.subarray(0, this.pendingLength);
+        this.buffer = this.buffer.subarray(this.pendingLength);
+
+        let envelope: IpcEnvelope;
+        try {
+          envelope = JSON.parse(payload.toString("utf-8")) as IpcEnvelope;
+        } catch {
+          this.onError(new Error("Invalid JSON in IPC frame"));
+          this.state = "detect";
+          continue;
+        }
+
+        const transferEncoding = envelope.headers?.["transfer-encoding"];
+        if (transferEncoding === "chunked") {
+          // Chunked streaming — emit start, then read chunks until terminator
+          this.pendingEnvelope = envelope;
+          this.streamCallbacks?.onStreamStart(envelope);
+          this.state = "read-stream-chunk-length";
+          continue;
+        }
+
+        const contentLength = envelope.headers?.["content-length"];
+        if (contentLength != null) {
+          // Binary frame follows
+          this.pendingEnvelope = envelope;
+          this.expectBinary = true;
+          this.state = "read-length";
+        } else {
+          this.onMessage(envelope, undefined);
+          this.expectBinary = false;
+          this.state = "detect";
+        }
+        continue;
+      }
+
+      if (this.state === "read-binary") {
+        if (this.buffer.length < this.pendingLength) {
+          return;
+        }
+        const binary = new Uint8Array(
+          this.buffer.subarray(0, this.pendingLength),
+        );
+        this.buffer = this.buffer.subarray(this.pendingLength);
+
+        this.onMessage(this.pendingEnvelope!, binary);
+        this.pendingEnvelope = null;
+        this.expectBinary = false;
+        this.state = "detect";
+        continue;
+      }
+
+      // Chunked streaming states
+      if (this.state === "read-stream-chunk-length") {
+        if (this.buffer.length < 4) {
+          return;
+        }
+        this.pendingLength = this.buffer.readUInt32BE(0);
+        this.buffer = this.buffer.subarray(4);
+
+        if (this.pendingLength === 0) {
+          // Zero-length frame = end of stream
+          this.streamCallbacks?.onStreamEnd();
+          this.pendingEnvelope = null;
+          this.state = "detect";
+          continue;
+        }
+
+        this.state = "read-stream-chunk";
+      }
+
+      if (this.state === "read-stream-chunk") {
+        if (this.buffer.length < this.pendingLength) {
+          return;
+        }
+        const chunk = new Uint8Array(
+          this.buffer.subarray(0, this.pendingLength),
+        );
+        this.buffer = this.buffer.subarray(this.pendingLength);
+
+        this.streamCallbacks?.onStreamChunk(chunk);
+        this.state = "read-stream-chunk-length";
+        continue;
+      }
+    }
+  }
+
+  /**
+   * Legacy mode: parse newline-delimited JSON lines.
+   * Once we enter legacy mode, we stay in it for the lifetime of the connection.
+   */
+  private drainLegacy(): void {
+    let newlineIdx: number;
+    while ((newlineIdx = this.buffer.indexOf(0x0a)) !== -1) {
+      const line = this.buffer.subarray(0, newlineIdx).toString("utf-8").trim();
+      this.buffer = this.buffer.subarray(newlineIdx + 1);
+      if (!line) {
+        continue;
+      }
+      try {
+        const envelope = JSON.parse(line) as IpcEnvelope;
+        this.onMessage(envelope, undefined);
+      } catch {
+        this.onError(new Error("Invalid JSON in legacy IPC line"));
+      }
+    }
+  }
+}

package/node_modules/@vellumai/ipc-server-utils/src/listen-options.ts

@@ -0,0 +1,3 @@
+export function ipcListenOptions(path: string) {
+  return { path, readableAll: false, writableAll: false } as const;
+}

package/node_modules/@vellumai/ipc-server-utils/src/socket-watchdog.test.ts

@@ -0,0 +1,444 @@
+import {
+  afterAll,
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  test,
+} from "bun:test";
+import {
+  existsSync,
+  mkdtempSync,
+  rmSync,
+  unlinkSync,
+} from "node:fs";
+import { createConnection, createServer, type Server, type Socket } from "node:net";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { SocketWatchdog, type SocketWatchdogLogger } from "./socket-watchdog.js";
+
+// macOS caps Unix-socket paths at sizeof(sun_path)-1 == 103 bytes, so the
+// shared test-preload temp dir is too long. Mint a short path under tmpdir
+// for these tests.
+const shortRoot = mkdtempSync(join(tmpdir(), "vmw-"));
+const socketPath = join(shortRoot, "g.sock");
+
+afterAll(() => {
+  try {
+    rmSync(shortRoot, { recursive: true, force: true });
+  } catch {
+    // best-effort
+  }
+});
+
+interface TestHarness {
+  watchdog: SocketWatchdog;
+  /** Mutated by tests to simulate stop()/restart. */
+  serverRef: { current: Server | null };
+  /** Servers handed to onRebind, captured for assertions + cleanup. */
+  rebinds: Array<{ newServer: Server; oldServer: Server }>;
+  log: SocketWatchdogLogger;
+  loggedErrors: Array<{ obj: object; msg?: string }>;
+  /** Tracks every server the harness factory produced, for cleanup. */
+  spawnedServers: Server[];
+}
+
+interface BuildOptions {
+  intervalMs?: number;
+  socketPathOverride?: string;
+  createServerOverride?: () => Server;
+  /** Override `getServer` to simulate races. */
+  getServerOverride?: () => Server | null;
+}
+
+function buildHarness(opts: BuildOptions): TestHarness {
+  const serverRef: { current: Server | null } = { current: null };
+  const rebinds: Array<{ newServer: Server; oldServer: Server }> = [];
+  const loggedErrors: Array<{ obj: object; msg?: string }> = [];
+  const spawnedServers: Server[] = [];
+
+  const log: SocketWatchdogLogger = {
+    info: () => {},
+    warn: () => {},
+    error: (obj, msg) => {
+      loggedErrors.push({ obj, msg });
+    },
+  };
+
+  const defaultFactory = () => {
+    const s = createServer();
+    s.on("error", () => {
+      /* tests don't care; suppress */
+    });
+    spawnedServers.push(s);
+    return s;
+  };
+
+  const watchdog = new SocketWatchdog({
+    socketPath: opts.socketPathOverride ?? socketPath,
+    intervalMs: opts.intervalMs ?? 0,
+    getServer: opts.getServerOverride ?? (() => serverRef.current),
+    createServer: opts.createServerOverride ?? defaultFactory,
+    onRebind: (newServer, oldServer) => {
+      rebinds.push({ newServer, oldServer });
+      serverRef.current = newServer;
+      // Mirror gateway behavior: close old server gracefully so its
+      // accept-loop drains. Close errors are not the watchdog's concern.
+      oldServer.close(() => {
+        /* drained */
+      });
+    },
+    log,
+  });
+
+  return { watchdog, serverRef, rebinds, log, loggedErrors, spawnedServers };
+}
+
+/**
+ * Spin up a real listening server and install it into the harness. Returns
+ * once the kernel reports the socket file present on disk.
+ */
+async function startInitialServer(harness: TestHarness): Promise<Server> {
+  const server = createServer();
+  server.on("error", () => {
+    /* ignore */
+  });
+  harness.spawnedServers.push(server);
+  await new Promise<void>((resolve, reject) => {
+    server.once("error", reject);
+    server.once("listening", () => resolve());
+    server.listen(socketPath);
+  });
+  harness.serverRef.current = server;
+  return server;
+}
+
+function connectClient(path: string): Promise<Socket> {
+  return new Promise<Socket>((resolve, reject) => {
+    const client: Socket = createConnection(path, () => resolve(client));
+    client.on("error", reject);
+  });
+}
+
+async function closeServer(server: Server): Promise<void> {
+  await new Promise<void>((resolve) => {
+    server.close(() => resolve());
+  });
+}
+
+describe("SocketWatchdog", () => {
+  let harness: TestHarness | undefined;
+  const sockets: Socket[] = [];
+
+  beforeEach(() => {
+    harness = undefined;
+    // Defensive: clean up any leftover socket file from a previous test
+    // whose afterEach didn't fully drain.
+    if (existsSync(socketPath)) {
+      try {
+        unlinkSync(socketPath);
+      } catch {
+        /* ignore */
+      }
+    }
+  });
+
+  afterEach(async () => {
+    for (const s of sockets) {
+      if (!s.destroyed) s.destroy();
+    }
+    sockets.length = 0;
+
+    if (harness) {
+      harness.watchdog.stop();
+      // Close every server the harness produced, regardless of how the
+      // test left things. Closing an already-closed server is a no-op.
+      for (const s of harness.spawnedServers) {
+        try {
+          await closeServer(s);
+        } catch {
+          /* already closed */
+        }
+      }
+      harness = undefined;
+    }
+
+    if (existsSync(socketPath)) {
+      try {
+        unlinkSync(socketPath);
+      } catch {
+        /* ignore */
+      }
+    }
+  });
+
+  test("rebindIfMissing is a no-op when the socket path exists", async () => {
+    harness = buildHarness({});
+    await startInitialServer(harness);
+
+    const rebound = await harness.watchdog.rebindIfMissing();
+    expect(rebound).toBe(false);
+    expect(harness.rebinds).toHaveLength(0);
+    expect(existsSync(socketPath)).toBe(true);
+  });
+
+  test("rebindIfMissing is a no-op when getServer returns null", async () => {
+    harness = buildHarness({});
+    // serverRef.current stays null.
+    const rebound = await harness.watchdog.rebindIfMissing();
+    expect(rebound).toBe(false);
+    expect(harness.rebinds).toHaveLength(0);
+  });
+
+  test("named pipes skip filesystem watchdog behavior", async () => {
+    const server = createServer();
+    harness = buildHarness({
+      socketPathOverride: "\\\\.\\pipe\\vellum-assistant-test",
+      getServerOverride: () => server,
+      createServerOverride: () => {
+        throw new Error("must not rebind");
+      },
+    });
+    harness.spawnedServers.push(server);
+    expect(await harness.watchdog.rebindIfMissing()).toBe(false);
+  });
+
+  test("rebindIfMissing recreates the listener when the path is gone", async () => {
+    harness = buildHarness({});
+    const initial = await startInitialServer(harness);
+    expect(existsSync(socketPath)).toBe(true);
+
+    // Simulate the cleanup that wipes /run/* — unlink the path while the
+    // listener fd is still alive in the kernel.
+    unlinkSync(socketPath);
+    expect(existsSync(socketPath)).toBe(false);
+
+    const rebound = await harness.watchdog.rebindIfMissing();
+    expect(rebound).toBe(true);
+    expect(existsSync(socketPath)).toBe(true);
+    expect(harness.rebinds).toHaveLength(1);
+    expect(harness.rebinds[0]!.oldServer).toBe(initial);
+    expect(harness.serverRef.current).toBe(harness.rebinds[0]!.newServer);
+
+    // A fresh client can connect to the re-bound listener.
+    const client = await connectClient(socketPath);
+    sockets.push(client);
+    expect(client.destroyed).toBe(false);
+  });
+
+  test("connected clients survive a rebind", async () => {
+    harness = buildHarness({});
+    await startInitialServer(harness);
+
+    const survivor = await connectClient(socketPath);
+    sockets.push(survivor);
+    expect(survivor.destroyed).toBe(false);
+
+    unlinkSync(socketPath);
+    const rebound = await harness.watchdog.rebindIfMissing();
+    expect(rebound).toBe(true);
+
+    // Give the close-callback a moment to settle without churning the EL.
+    await new Promise((r) => setTimeout(r, 10));
+    expect(survivor.destroyed).toBe(false);
+  });
+
+  test("rebindIfMissing aborts when getServer changes mid-listen (shutdown race)", async () => {
+    // Drive the race deterministically by mutating what getServer returns
+    // between its first call (precondition check) and its second call
+    // (post-listen race guard).
+    const initial = createServer();
+    initial.on("error", () => {});
+    await new Promise<void>((r) => {
+      initial.once("listening", () => r());
+      initial.listen(socketPath);
+    });
+
+    let getServerCalls = 0;
+    const rebinds: Array<{ newServer: Server; oldServer: Server }> = [];
+    const spawnedNewServers: Server[] = [];
+
+    const watchdog = new SocketWatchdog({
+      socketPath,
+      intervalMs: 0,
+      getServer: () => {
+        getServerCalls++;
+        // First call: precondition — initialServer is still around.
+        // Subsequent calls (race guard): null, simulating stop().
+        return getServerCalls === 1 ? initial : null;
+      },
+      createServer: () => {
+        const s = createServer();
+        s.on("error", () => {});
+        spawnedNewServers.push(s);
+        return s;
+      },
+      onRebind: (n, o) => {
+        rebinds.push({ newServer: n, oldServer: o });
+      },
+      log: { info: () => {}, warn: () => {}, error: () => {} },
+    });
+
+    unlinkSync(socketPath);
+    expect(existsSync(socketPath)).toBe(false);
+
+    const rebound = await watchdog.rebindIfMissing();
+    expect(rebound).toBe(false);
+    expect(rebinds).toHaveLength(0);
+    // The race guard should have unlinked the path the discarded server
+    // recreated, so a future start() doesn't see a phantom listener.
+    expect(existsSync(socketPath)).toBe(false);
+    // getServer was called at least twice — once for precondition, once
+    // for the race guard.
+    expect(getServerCalls).toBeGreaterThanOrEqual(2);
+
+    // Cleanup: initial is still listening on the unlinked path; close it.
+    await closeServer(initial);
+    for (const s of spawnedNewServers) {
+      try {
+        await closeServer(s);
+      } catch {
+        /* already closed by race guard */
+      }
+    }
+  });
+
+  test("rebindIfMissing returns false and logs when listen() rejects", async () => {
+    // Provide a factory whose listen() always errors, so rebindIfMissing
+    // hits the catch branch.
+    const initial = createServer();
+    initial.on("error", () => {});
+    await new Promise<void>((r) => {
+      initial.once("listening", () => r());
+      initial.listen(socketPath);
+    });
+
+    const rebinds: Array<{ newServer: Server; oldServer: Server }> = [];
+    const loggedErrors: Array<{ obj: object; msg?: string }> = [];
+    const failingFactory = () => {
+      const s = createServer();
+      s.on("error", () => {});
+      // Replace listen to immediately error.
+      const realListen = s.listen.bind(s);
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      (s as any).listen = (_path: string) => {
+        queueMicrotask(() => s.emit("error", new Error("simulated EADDRINUSE")));
+        return s;
+      };
+      // Keep realListen reference alive so TS doesn't complain
+      void realListen;
+      return s;
+    };
+
+    const watchdog = new SocketWatchdog({
+      socketPath,
+      intervalMs: 0,
+      getServer: () => initial,
+      createServer: failingFactory,
+      onRebind: (n, o) => rebinds.push({ newServer: n, oldServer: o }),
+      log: {
+        info: () => {},
+        warn: () => {},
+        error: (obj, msg) => loggedErrors.push({ obj, msg }),
+      },
+    });
+
+    unlinkSync(socketPath);
+    const rebound = await watchdog.rebindIfMissing();
+    expect(rebound).toBe(false);
+    expect(rebinds).toHaveLength(0);
+    expect(loggedErrors.length).toBeGreaterThan(0);
+
+    await closeServer(initial);
+  });
+
+  test("watchdog timer catches synchronous rebind errors so unhandled rejections don't escape", async () => {
+    // createServer factory throws synchronously — simulates EACCES on
+    // mkdir / a broken factory dependency.
+    const throwingFactory = () => {
+      throw new Error("boom — synchronous factory failure");
+    };
+
+    const initial = createServer();
+    initial.on("error", () => {});
+    await new Promise<void>((r) => {
+      initial.once("listening", () => r());
+      initial.listen(socketPath);
+    });
+
+    const loggedErrors: Array<{ obj: object; msg?: string }> = [];
+    const watchdog = new SocketWatchdog({
+      socketPath,
+      intervalMs: 5,
+      getServer: () => initial,
+      createServer: throwingFactory,
+      onRebind: () => {},
+      log: {
+        info: () => {},
+        warn: () => {},
+        error: (obj, msg) => loggedErrors.push({ obj, msg }),
+      },
+    });
+
+    unlinkSync(socketPath);
+
+    const seenRejections: unknown[] = [];
+    const onRejection = (reason: unknown) => seenRejections.push(reason);
+    process.on("unhandledRejection", onRejection);
+
+    try {
+      watchdog.start();
+      // Let the timer fire several times.
+      await new Promise((r) => setTimeout(r, 30));
+      watchdog.stop();
+    } finally {
+      process.off("unhandledRejection", onRejection);
+    }
+
+    expect(seenRejections).toHaveLength(0);
+    expect(loggedErrors.length).toBeGreaterThan(0);
+
+    await closeServer(initial);
+  });
+
+  test("start() polls and rebinds without manual ticking", async () => {
+    harness = buildHarness({ intervalMs: 10 });
+    await startInitialServer(harness);
+    harness.watchdog.start();
+
+    unlinkSync(socketPath);
+
+    // Wait up to 500ms for the timer to recover.
+    const deadline = Date.now() + 500;
+    while (harness.rebinds.length === 0 && Date.now() < deadline) {
+      await new Promise((r) => setTimeout(r, 5));
+    }
+
+    expect(harness.rebinds).toHaveLength(1);
+    expect(existsSync(socketPath)).toBe(true);
+  });
+
+  test("stop() prevents future rebinds from firing", async () => {
+    harness = buildHarness({ intervalMs: 10 });
+    await startInitialServer(harness);
+    harness.watchdog.start();
+
+    // First recovery cycle.
+    unlinkSync(socketPath);
+    let deadline = Date.now() + 500;
+    while (harness.rebinds.length < 1 && Date.now() < deadline) {
+      await new Promise((r) => setTimeout(r, 5));
+    }
+    expect(harness.rebinds).toHaveLength(1);
+
+    harness.watchdog.stop();
+    const stoppedAt = harness.rebinds.length;
+
+    // Unlink again. Wait three intervals; no new rebind should appear.
+    unlinkSync(socketPath);
+    await new Promise((r) => setTimeout(r, 50));
+    expect(harness.rebinds).toHaveLength(stoppedAt);
+    expect(existsSync(socketPath)).toBe(false);
+  });
+});

package/node_modules/@vellumai/ipc-server-utils/src/socket-watchdog.ts

@@ -0,0 +1,236 @@
+/**
+ * Resilience helper for Unix-domain-socket IPC servers: re-binds the
+ * listening socket when its on-disk path entry has been removed (e.g. by a
+ * tmpfs sweep or rogue cleanup of `/run/*`).
+ *
+ * Existing connected sockets survive the re-bind because the kernel keeps
+ * connection inodes alive independently of the listener path; only new
+ * `connect()` calls require the path to exist.
+ *
+ * Consumers wire their `Server` reference into the watchdog via callbacks
+ * rather than passing the server directly so the watchdog can guard against
+ * shutdown/restart races mid-rebind.
+ */
+
+import { existsSync, mkdirSync, unlinkSync } from "node:fs";
+import type { Server } from "node:net";
+import { dirname } from "node:path";
+
+import { isNamedPipePath } from "./endpoint.js";
+import { ipcListenOptions } from "./listen-options.js";
+
+/**
+ * Minimal logger surface (pino-compatible). Each method receives a context
+ * object plus an optional human-readable message.
+ */
+export interface SocketWatchdogLogger {
+  info(obj: object, msg?: string): void;
+  warn(obj: object, msg?: string): void;
+  error(obj: object, msg?: string): void;
+}
+
+export interface SocketWatchdogOptions {
+  /** Absolute path to the Unix socket file the consumer is listening on. */
+  socketPath: string;
+  /**
+   * How often to stat the socket path. Set to `0` to disable. Defaults to
+   * 5000ms.
+   */
+  intervalMs?: number;
+  /**
+   * Returns the consumer's current listening server. The watchdog uses this
+   * both as a precondition (no rebind when null) and as a generation marker
+   * to detect shutdown/restart races mid-rebind.
+   */
+  getServer: () => Server | null;
+  /**
+   * Factory for a fresh listening Server. Called by the watchdog when a
+   * rebind is needed; the watchdog drives `.listen(socketPath)` and waits
+   * for the `listening` event before installing.
+   */
+  createServer: () => Server;
+  /**
+   * Invoked when a rebind succeeds. The consumer is responsible for
+   * swapping its primary server reference to `newServer` and disposing of
+   * `oldServer` (typically by tracking it as a legacy listener while
+   * in-flight clients drain, then closing it).
+   */
+  onRebind: (newServer: Server, oldServer: Server) => void;
+  /** Pino-compatible logger. */
+  log: SocketWatchdogLogger;
+}
+
+const DEFAULT_INTERVAL_MS = 5000;
+
+/**
+ * Ensure the directory containing `socketPath` exists. Created with mode
+ * `0o700` so a freshly-spawned dir on a tmpfs mount doesn't leak the IPC
+ * surface to other UIDs. Existing directories keep their permissions —
+ * `mkdir` only applies the mode to directories it creates.
+ */
+export function ensureSocketDir(socketPath: string): void {
+  if (isNamedPipePath(socketPath)) {
+    return;
+  }
+  const socketDir = dirname(socketPath);
+  if (!existsSync(socketDir)) {
+    mkdirSync(socketDir, { recursive: true, mode: 0o700 });
+  }
+}
+
+/**
+ * Watchdog that periodically stats a Unix socket file and re-binds the
+ * listener when the path has been removed.
+ *
+ * Lifecycle:
+ *   - Construct with the consumer's callbacks.
+ *   - Call {@link start} after the consumer's initial `listen()` succeeds.
+ *   - Call {@link stop} during shutdown (before closing the underlying
+ *     server) so an in-flight rebind doesn't resurrect the listener.
+ *
+ * The watchdog timer is `unref`-ed so it never keeps the event loop alive
+ * on its own.
+ */
+export class SocketWatchdog {
+  private readonly socketPath: string;
+  private readonly intervalMs: number;
+  private readonly getServer: () => Server | null;
+  private readonly createServer: () => Server;
+  private readonly onRebind: (newServer: Server, oldServer: Server) => void;
+  private readonly log: SocketWatchdogLogger;
+
+  private handle: ReturnType<typeof setInterval> | null = null;
+
+  constructor(options: SocketWatchdogOptions) {
+    this.socketPath = options.socketPath;
+    this.intervalMs = options.intervalMs ?? DEFAULT_INTERVAL_MS;
+    this.getServer = options.getServer;
+    this.createServer = options.createServer;
+    this.onRebind = options.onRebind;
+    this.log = options.log;
+  }
+
+  /**
+   * Begin polling the socket path. No-op if `intervalMs <= 0` or the
+   * watchdog is already running.
+   */
+  start(): void {
+    if (
+      this.intervalMs <= 0 ||
+      this.handle !== null ||
+      isNamedPipePath(this.socketPath)
+    ) {
+      return;
+    }
+    this.handle = setInterval(() => {
+      // The async entry path of rebindIfMissing performs filesystem work
+      // (ensureSocketDir, createServer) before its inner try/catch, so a
+      // synchronous throw — e.g. EACCES on a read-only fs — would surface
+      // as an unhandled rejection on every tick. Catch here so the timer
+      // stays quiet on persistent failure modes.
+      this.rebindIfMissing().catch((err) => {
+        this.log.error(
+          { err, path: this.socketPath },
+          "Watchdog rebind failed unexpectedly",
+        );
+      });
+    }, this.intervalMs);
+    this.handle.unref?.();
+  }
+
+  /** Stop the polling timer. Safe to call multiple times. */
+  stop(): void {
+    if (this.handle !== null) {
+      clearInterval(this.handle);
+      this.handle = null;
+    }
+  }
+
+  /**
+   * Re-bind the listening socket if its path entry is missing on disk.
+   *
+   * Public for tests so the watchdog can be exercised deterministically
+   * without waiting for the interval. Returns `true` when a re-bind was
+   * performed, `false` when the socket was already healthy, the consumer
+   * is not running, or a shutdown/restart raced the rebind.
+   */
+  async rebindIfMissing(): Promise<boolean> {
+    if (isNamedPipePath(this.socketPath)) {
+      return false;
+    }
+    const initialServer = this.getServer();
+    if (initialServer === null) return false;
+    if (existsSync(this.socketPath)) return false;
+
+    this.log.warn(
+      { path: this.socketPath },
+      "IPC socket path missing on disk — re-binding listener",
+    );
+
+    ensureSocketDir(this.socketPath);
+
+    const newServer = this.createServer();
+    try {
+      await new Promise<void>((resolve, reject) => {
+        const onError = (err: unknown) => {
+          newServer.off("listening", onListening);
+          reject(err);
+        };
+        const onListening = () => {
+          newServer.off("error", onError);
+          resolve();
+        };
+        newServer.once("error", onError);
+        newServer.once("listening", onListening);
+        newServer.listen(ipcListenOptions(this.socketPath));
+      });
+    } catch (err) {
+      this.log.error(
+        { err, path: this.socketPath },
+        "Failed to re-bind IPC socket — will retry on next watchdog tick",
+      );
+      try {
+        newServer.close();
+      } catch {
+        /* ignore */
+      }
+      return false;
+    }
+
+    // Race guard: while we were awaiting listen(), the consumer may have
+    // stopped, restarted, or otherwise replaced its server reference.
+    // Installing newServer would resurrect a listener after shutdown
+    // (keeping the process alive and accepting IPC again). Discard the
+    // new server instead.
+    if (this.getServer() !== initialServer) {
+      try {
+        newServer.close();
+      } catch {
+        /* ignore */
+      }
+      // newServer.listen() recreated the path on disk. If our listen won
+      // the race, the file is sitting there — clean it up so it doesn't
+      // shadow a future start().
+      if (existsSync(this.socketPath)) {
+        try {
+          unlinkSync(this.socketPath);
+        } catch {
+          /* ignore */
+        }
+      }
+      this.log.warn(
+        { path: this.socketPath },
+        "IPC server state changed during rebind — discarded new listener",
+      );
+      return false;
+    }
+
+    this.onRebind(newServer, initialServer);
+
+    this.log.info(
+      { path: this.socketPath },
+      "IPC socket re-bound after path loss",
+    );
+    return true;
+  }
+}

package/node_modules/@vellumai/ipc-server-utils/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "types": ["bun"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/node_modules/@vellumai/service-contracts/src/remote-web-pairing.ts

@@ -21,6 +21,12 @@
  * `Date#toISOString()`.
  */
 
+/**
+ * Pairing-challenge TTL in milliseconds (10 minutes): the gateway's challenge
+ * store enforces it and the `vellum pair` CLI renders it in user-facing copy.
+ */
+export const REMOTE_WEB_PAIRING_CODE_TTL_MS = 10 * 60 * 1000;
+
 /** `POST /v1/remote-web/pairing-challenge` request body. */
 export interface RemoteWebPairingChallengeRequest {
   /** Public https base URL the scanning device can reach the assistant at. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/credential-executor",
-  "version": "0.11.2-dev.202608060701.ede4331",
+  "version": "0.11.2-dev.202608062308.5442cf1",
   "license": "MIT",
   "type": "module",
   "exports": {
@@ -21,6 +21,7 @@
   "dependencies": {
     "@vellumai/credential-storage": "file:../packages/credential-storage",
     "@vellumai/egress-proxy": "file:../packages/egress-proxy",
+    "@vellumai/ipc-server-utils": "file:../packages/ipc-server-utils",
     "@vellumai/service-contracts": "file:../packages/service-contracts",
     "pino": "9.14.0",
     "pino-pretty": "13.1.3"
@@ -28,7 +29,8 @@
   "bundledDependencies": [
     "@vellumai/service-contracts",
     "@vellumai/credential-storage",
-    "@vellumai/egress-proxy"
+    "@vellumai/egress-proxy",
+    "@vellumai/ipc-server-utils"
   ],
   "devDependencies": {
     "@types/bun": "1.3.10",

package/src/main.ts

@@ -17,7 +17,7 @@
  * optional credential CRUD routes) for Kubernetes liveness/readiness probes.
  */
 
-import { mkdirSync, unlinkSync } from "node:fs";
+import { mkdirSync } from "node:fs";
 import { createServer as createNetServer, type Socket } from "node:net";
 import { dirname, join } from "node:path";
 import { Readable, Writable } from "node:stream";
@@ -27,6 +27,11 @@ import {
   CesRpcMethod,
 } from "@vellumai/service-contracts/credential-rpc";
 import type { SecureKeyBackend } from "@vellumai/credential-storage";
+import {
+  ipcListenOptions,
+  isNamedPipePath,
+  removeIpcEndpointFile,
+} from "@vellumai/ipc-server-utils";
 
 import { createLocalSecureKeyBackend } from "./materializers/local-secure-key-backend.js";
 import { initLogger, getLogger } from "./logger.js";
@@ -159,12 +164,10 @@ function serveStandaloneSocket(opts: {
     onApiKeyUpdate,
   } = opts;
 
-  mkdirSync(dirname(socketPath), { recursive: true });
-  try {
-    unlinkSync(socketPath);
-  } catch {
-    // stale or absent — fine
+  if (!isNamedPipePath(socketPath)) {
+    mkdirSync(dirname(socketPath), { recursive: true });
   }
+  removeIpcEndpointFile(socketPath);
 
   const netServer = createNetServer();
 
@@ -215,7 +218,7 @@ function serveStandaloneSocket(opts: {
       });
   });
 
-  netServer.listen(socketPath, () => {
+  netServer.listen(ipcListenOptions(socketPath), () => {
     log.info(`CES socket listening at ${socketPath}`);
   });
 
@@ -223,11 +226,7 @@ function serveStandaloneSocket(opts: {
     "abort",
     () => {
       netServer.close();
-      try {
-        unlinkSync(socketPath);
-      } catch {
-        // already removed
-      }
+      removeIpcEndpointFile(socketPath);
     },
     { once: true },
   );