feat(ipc): extract socket watchdog into shared @vellumai/ipc-server-utils + wire into assistant & skill servers

assistant/Dockerfile

@@ -22,6 +22,7 @@ COPY packages/service-contracts ./packages/service-contracts
 COPY packages/credential-storage ./packages/credential-storage
 COPY packages/egress-proxy ./packages/egress-proxy
 COPY packages/gateway-client ./packages/gateway-client
+COPY packages/ipc-server-utils ./packages/ipc-server-utils
 COPY packages/skill-host-contracts ./packages/skill-host-contracts
 COPY packages/slack-text ./packages/slack-text
 COPY packages/twilio-client ./packages/twilio-client

assistant/knip.json

@@ -11,6 +11,7 @@
     "@vellumai/credential-storage",
     "@vellumai/egress-proxy",
     "@vellumai/gateway-client",
+    "@vellumai/ipc-server-utils",
     "@vellumai/service-contracts",
     "@vellumai/slack-text",
     "@vellumai/twilio-client",

assistant/package.json

@@ -44,6 +44,7 @@
     "@vellumai/credential-storage": "file:../packages/credential-storage",
     "@vellumai/egress-proxy": "file:../packages/egress-proxy",
     "@vellumai/gateway-client": "file:../packages/gateway-client",
+    "@vellumai/ipc-server-utils": "file:../packages/ipc-server-utils",
     "@vellumai/service-contracts": "file:../packages/service-contracts",
     "@vellumai/skill-host-contracts": "file:../packages/skill-host-contracts",
     "@vellumai/slack-text": "file:../packages/slack-text",
@@ -78,6 +79,7 @@
     "@vellumai/service-contracts",
     "@vellumai/egress-proxy",
     "@vellumai/gateway-client",
+    "@vellumai/ipc-server-utils",
     "@vellumai/skill-host-contracts",
     "@vellumai/slack-text",
     "@vellumai/twilio-client"

assistant/src/ipc/assistant-server.ts

@@ -28,9 +28,13 @@
  * back to a shorter deterministic path so CLI commands can still connect.
  */
 
-import { existsSync, mkdirSync, unlinkSync } from "node:fs";
+import { existsSync, unlinkSync } from "node:fs";
 import { createServer, type Server, type Socket } from "node:net";
-import { dirname } from "node:path";
+
+import {
+  ensureSocketDir,
+  SocketWatchdog,
+} from "@vellumai/ipc-server-utils";
 
 import { findLocalGuardianPrincipalId } from "../runtime/local-actor-identity.js";
 import { RouteError } from "../runtime/routes/errors.js";
@@ -130,13 +134,29 @@ function isIpcBinaryResponse(value: unknown): value is IpcBinaryResponse {
 // Server
 // ---------------------------------------------------------------------------
 
+/** Optional configuration for {@link AssistantIpcServer}. */
+export interface AssistantIpcServerOptions {
+  /**
+   * How often the socket-file watchdog stats the listening socket path.
+   * Set to `0` to disable. Defaults to {@link SocketWatchdog}'s 5000ms.
+   */
+  watchdogIntervalMs?: number;
+}
+
 export class AssistantIpcServer {
   private server: Server | null = null;
   private clients = new Set<Socket>();
   private methods = new Map<string, RouteDefinition["handler"]>();
   private socketPath: string;
+  private watchdog: SocketWatchdog;
+  /**
+   * Servers whose listener path has been replaced by a re-bind. Kept around
+   * so already-connected sockets continue to work; closed gracefully once
+   * their accept loops drain.
+   */
+  private legacyServers = new Set<Server>();
 
-  constructor() {
+  constructor(options?: AssistantIpcServerOptions) {
     const resolution = resolveIpcSocketPath("assistant");
     this.socketPath = resolution.path;
     log.info(
@@ -154,62 +174,55 @@ export class AssistantIpcServer {
     this.methods.set("db_proxy", (params) =>
       handleDbProxy(params as unknown as DbProxyParams),
     );
+
+    this.watchdog = new SocketWatchdog({
+      socketPath: this.socketPath,
+      intervalMs: options?.watchdogIntervalMs,
+      getServer: () => this.server,
+      createServer: () => this.createListeningServer(),
+      onRebind: (newServer, oldServer) => {
+        this.server = newServer;
+        this.legacyServers.add(oldServer);
+        oldServer.close(() => {
+          this.legacyServers.delete(oldServer);
+        });
+      },
+      log,
+    });
   }
 
   /** Start listening on the Unix domain socket. */
   async start(): Promise<void> {
     // Ensure the parent directory exists before listening.
-    const socketDir = dirname(this.socketPath);
-    if (!existsSync(socketDir)) {
-      mkdirSync(socketDir, { recursive: true, mode: 0o700 });
-    }
+    ensureSocketDir(this.socketPath);
 
     // Probe before unlink so a second daemon can't silently orphan an active
     // listener (Unix lets you unlink a still-bound socket file). See
     // `ensureSocketPathFree` for the behavior matrix.
     await ensureSocketPathFree(this.socketPath);
 
-    this.server = createServer((socket) => {
-      this.clients.add(socket);
-      log.debug("IPC client connected");
-
-      const reader = new IpcFrameReader(
-        (envelope, binary) =>
-          this.handleEnvelope(socket, reader, envelope, binary),
-        (err) => log.warn({ err }, "IPC frame read error"),
-      );
-
-      socket.on("data", (chunk) => {
-        reader.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
-      });
-
-      socket.on("close", () => {
-        this.clients.delete(socket);
-        log.debug("IPC client disconnected");
-      });
-
-      socket.on("error", (err) => {
-        log.warn({ err }, "IPC client socket error");
-        this.clients.delete(socket);
-      });
-    });
-
-    this.server.on("error", (err) => {
-      log.error({ err }, "Assistant IPC server error");
-    });
-
+    this.server = this.createListeningServer();
     this.server.listen(this.socketPath, () => {
       log.info({ path: this.socketPath }, "Assistant IPC server listening");
     });
+
+    this.watchdog.start();
   }
 
   /** Stop the server and disconnect all clients. */
   stop(): void {
+    this.watchdog.stop();
+
     for (const client of this.clients) {
       if (!client.destroyed) client.destroy();
     }
     this.clients.clear();
 
+    for (const legacy of this.legacyServers) {
+      legacy.close();
+    }
+    this.legacyServers.clear();
+
     if (this.server) {
       this.server.close();
       this.server = null;
@@ -229,8 +242,52 @@ export class AssistantIpcServer {
     return this.socketPath;
   }
 
+  /**
+   * 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` otherwise.
+   */
+  async rebindIfMissing(): Promise<boolean> {
+    return this.watchdog.rebindIfMissing();
+  }
+
   // ── Internal ──────────────────────────────────────────────────────────
 
+  private createListeningServer(): Server {
+    const server = createServer((socket) => {
+      this.clients.add(socket);
+      log.debug("IPC client connected");
+
+      const reader = new IpcFrameReader(
+        (envelope, binary) =>
+          this.handleEnvelope(socket, reader, envelope, binary),
+        (err) => log.warn({ err }, "IPC frame read error"),
+      );
+
+      socket.on("data", (chunk) => {
+        reader.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+      });
+
+      socket.on("close", () => {
+        this.clients.delete(socket);
+        log.debug("IPC client disconnected");
+      });
+
+      socket.on("error", (err) => {
+        log.warn({ err }, "IPC client socket error");
+        this.clients.delete(socket);
+      });
+    });
+
+    server.on("error", (err) => {
+      log.error({ err }, "Assistant IPC server error");
+    });
+
+    return server;
+  }
+
   private handleEnvelope(
     socket: Socket,
     reader: IpcFrameReader,