@fnclaude/cli 1.1.1 → 2.0.0

package/src/mcp/jsonrpc-server.ts

@@ -0,0 +1,154 @@
+/**
+ * JSON-RPC 2.0 server scaffold for the MCP subprocess.
+ *
+ * The fnclaude MCP subprocess (spawned by claude via the injected
+ * `--mcp-config`) is a Model Context Protocol server that speaks
+ * newline-delimited JSON-RPC 2.0 over stdio. This module is the pure
+ * routing layer — transport (read stdin lines, write stdout lines) is the
+ * subprocess entry point's job (§7.5); per-call dialing of the parent
+ * socket is the tool handler's job (§7.6 / §8).
+ *
+ * Methods routed:
+ *   - "initialize"        → returns the injected initializeResponse
+ *   - "tools/list"        → returns { tools: [{name, description, inputSchema}, ...] }
+ *                           in registration order (Object.entries order on
+ *                           the tools record)
+ *   - "tools/call"        → dispatches to tools[name].handler(args), wraps
+ *                           the return value in MCP's content shape
+ *                           ({ content: [{ type: "text", text: <json> }] })
+ *   - anything else       → JSON-RPC error -32601 (method not found)
+ *
+ * Notifications (requests with no `id` field) are processed but produce no
+ * response — handle() returns null.
+ *
+ * Error codes follow the JSON-RPC 2.0 spec:
+ *   -32700 Parse error       (malformed JSON)
+ *   -32600 Invalid Request   (not an object, missing method)
+ *   -32601 Method not found  (unknown method or unknown tool name)
+ *   -32603 Internal error    (handler throw)
+ *
+ * Per design.mcp.md §3, the wire format is one JSON object per line; this
+ * function takes one line and returns one line (or null for
+ * notifications). Pipelining is not used.
+ *
+ * Tool registration is by injection — the four real tools (fnc_restart,
+ * fnc_switch_project, fnc_spawn_session, fnc_copy_to_clipboard) come in
+ * §8; tests use fakes.
+ */
+
+export type JsonRpcId = number | string | null;
+
+export interface McpTool {
+  description: string;
+  inputSchema: object;
+  handler: (args: unknown) => Promise<object>;
+}
+
+export interface CreateJsonRpcServerArgs {
+  tools: Record<string, McpTool>;
+  initializeResponse: object;
+}
+
+export interface JsonRpcServer {
+  handle(line: string): Promise<string | null>;
+}
+
+interface JsonRpcRequest {
+  jsonrpc?: unknown;
+  id?: JsonRpcId | undefined;
+  method?: unknown;
+  params?: unknown;
+}
+
+export function createJsonRpcServer(
+  args: CreateJsonRpcServerArgs,
+): JsonRpcServer {
+  return {
+    async handle(line: string): Promise<string | null> {
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(line);
+      } catch {
+        return serializeError(null, -32700, 'Parse error: malformed JSON');
+      }
+
+      if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        return serializeError(null, -32600, 'Invalid Request: not a JSON-RPC object');
+      }
+
+      const req = parsed as JsonRpcRequest;
+      const id = normalizeId(req.id);
+      const isNotification = req.id === undefined;
+
+      if (typeof req.method !== 'string') {
+        if (isNotification) return null;
+        return serializeError(id, -32600, 'Invalid Request: missing method');
+      }
+
+      const method = req.method;
+
+      if (isNotification) {
+        // Notifications are processed but produce no response.
+        return null;
+      }
+
+      if (method === 'initialize') {
+        return serializeResult(id, args.initializeResponse);
+      }
+
+      if (method === 'tools/list') {
+        const tools = Object.entries(args.tools).map(([name, tool]) => ({
+          name,
+          description: tool.description,
+          inputSchema: tool.inputSchema,
+        }));
+        return serializeResult(id, { tools });
+      }
+
+      if (method === 'tools/call') {
+        const params = (req.params ?? {}) as { name?: unknown; arguments?: unknown };
+        const name = typeof params.name === 'string' ? params.name : '';
+        if (!name || !(name in args.tools)) {
+          return serializeError(id, -32601, `Unknown tool: ${name || '(missing name)'}`);
+        }
+        const tool = args.tools[name]!;
+        const toolArgs =
+          params.arguments !== undefined && params.arguments !== null
+            ? params.arguments
+            : {};
+        let result: object;
+        try {
+          result = await tool.handler(toolArgs);
+        } catch (err) {
+          const msg = err instanceof Error ? err.message : String(err);
+          return serializeError(id, -32603, `Internal error: ${msg}`);
+        }
+        return serializeResult(id, {
+          content: [
+            {
+              type: 'text',
+              text: JSON.stringify(result),
+            },
+          ],
+        });
+      }
+
+      return serializeError(id, -32601, `Method not found: ${method}`);
+    },
+  };
+}
+
+function normalizeId(id: unknown): JsonRpcId {
+  if (typeof id === 'number' || typeof id === 'string' || id === null) {
+    return id;
+  }
+  return null;
+}
+
+function serializeResult(id: JsonRpcId, result: object): string {
+  return JSON.stringify({ jsonrpc: '2.0', id, result });
+}
+
+function serializeError(id: JsonRpcId, code: number, message: string): string {
+  return JSON.stringify({ jsonrpc: '2.0', id, error: { code, message } });
+}

package/src/mcp/listener.ts

@@ -0,0 +1,141 @@
+/**
+ * AF_UNIX MCP listener — parent half of the in-process transport.
+ *
+ * Per docs/design.mcp.md §2.1, the launcher binds + listens BEFORE
+ * spawning claude, so the MCP subprocess (which claude spawns from the
+ * injected --mcp-config) can dial back via $FNC_SOCKET on every tool
+ * call. The accept loop runs `onConnection` per incoming dial; the
+ * caller (parent-side dispatch in §7.7) wires per-connection
+ * read-one-request / write-one-response logic onto each socket.
+ *
+ * Today the listener is generic: it doesn't parse requests itself. That
+ * lets §7.2 ship in isolation — wire-format + JSON-RPC scaffolding land
+ * in §7.3 and §7.6.
+ *
+ * Cleanup contract (matches Go canonical and design.mcp.md §7):
+ *   - Best-effort unlink of any stale socket file before bind. Covers
+ *     unclean shutdowns from a prior PID-colliding fnclaude.
+ *   - On stop(), close the listener and best-effort unlink the file.
+ *     Bun.listen.stop() already removes the file on Linux, but the
+ *     explicit unlink mirrors the design's defense-in-depth posture.
+ *   - stop() is idempotent — calling it twice is a no-op the second
+ *     time (the listener is null after first stop).
+ *
+ * Cross-platform: throws NotImplementedYet on win32. AF_UNIX over
+ * Bun.listen({ unix }) is Unix-only today; the Windows named-pipe path
+ * is a sibling §7 follow-up. Callers (main.ts) skip listener startup
+ * entirely on win32 so the launcher still works without self-MCP.
+ */
+
+import { unlink } from 'node:fs/promises';
+import type { Socket, SocketHandler } from 'bun';
+
+/**
+ * Per-connection socket exposed to onConnection. The `handlers` field is
+ * a writable wrapper around the static Bun socket handlers so per-call
+ * code can install its own data() / close() / error() implementations
+ * without each implementation having to be re-registered as a separate
+ * Bun.listen call. The dispatch layer (§7.7) overrides these to drive
+ * the newline-delimited JSON protocol.
+ */
+export interface AcceptedSocket {
+  socket: Socket<undefined>;
+  handlers: {
+    data?: (socket: Socket<undefined>, data: Buffer) => void;
+    close?: (socket: Socket<undefined>) => void;
+    error?: (socket: Socket<undefined>, error: Error) => void;
+  };
+}
+
+export interface StartMcpListenerArgs {
+  socketPath: string;
+  onConnection: (accepted: AcceptedSocket) => void;
+}
+
+export interface McpListener {
+  socketPath: string;
+  stop: () => Promise<void>;
+}
+
+export async function startMcpListener(args: StartMcpListenerArgs): Promise<McpListener> {
+  if (process.platform === 'win32') {
+    throw new Error(
+      'startMcpListener: win32 not yet supported (AF_UNIX path only); see build-plan §7 follow-up',
+    );
+  }
+
+  // Best-effort unlink of a stale socket file from a prior crashed run.
+  // ENOENT is the normal "no leftover" case — swallow it; anything else
+  // is also swallowed because bind() will surface a clearer error in a
+  // moment (EADDRINUSE if the file's still there as a real bound socket,
+  // EACCES if perms are wrong, etc.).
+  try {
+    await unlink(args.socketPath);
+  } catch {
+    // intentionally ignored
+  }
+
+  // Per-connection routing table. Bun.listen takes a single static
+  // handler block; we route per-socket via a WeakMap keyed on the
+  // Socket object so each connection's onConnection callback can hang
+  // its own handlers without affecting siblings.
+  const perSocketHandlers = new WeakMap<Socket<undefined>, AcceptedSocket['handlers']>();
+
+  const handler: SocketHandler<undefined> = {
+    open(socket) {
+      const handlers: AcceptedSocket['handlers'] = {};
+      perSocketHandlers.set(socket, handlers);
+      args.onConnection({ socket, handlers });
+    },
+    data(socket, data) {
+      const h = perSocketHandlers.get(socket);
+      h?.data?.(socket, data);
+    },
+    close(socket) {
+      const h = perSocketHandlers.get(socket);
+      h?.close?.(socket);
+      perSocketHandlers.delete(socket);
+    },
+    error(socket, error) {
+      const h = perSocketHandlers.get(socket);
+      h?.error?.(socket, error);
+    },
+  };
+
+  // Bun.listen throws synchronously on bind failure (verified empirically
+  // against Bun 1.3.14 — ENOENT for bad parent dir, EADDRINUSE for
+  // already-bound). Wrap in try/catch + reject so the contract matches a
+  // promise-returning startup; main.ts treats rejection as fatal.
+  let bunListener;
+  try {
+    bunListener = Bun.listen<undefined>({
+      unix: args.socketPath,
+      socket: handler,
+    });
+  } catch (err) {
+    throw new Error(
+      `startMcpListener: failed to bind ${args.socketPath}: ${(err as Error).message}`,
+      { cause: err },
+    );
+  }
+
+  let stopped = false;
+  const stop = async (): Promise<void> => {
+    if (stopped) return;
+    stopped = true;
+    bunListener.stop();
+    // Defense-in-depth unlink. Bun.listen.stop() already removes the
+    // file on Linux, but design.mcp.md §7 calls for an explicit unlink
+    // so platforms that don't auto-clean still get covered.
+    try {
+      await unlink(args.socketPath);
+    } catch {
+      // already gone — expected on Linux/macOS
+    }
+  };
+
+  return {
+    socketPath: args.socketPath,
+    stop,
+  };
+}

package/src/mcp/parent-dispatch.ts

@@ -0,0 +1,154 @@
+/**
+ * §7.7 — Per-tool dispatch on the parent side of the MCP socket.
+ *
+ * `createParentDispatcher` returns the `onConnection` callback that
+ * `startMcpListener` (§7.2) invokes for every accepted AF_UNIX dial. For
+ * each connection it:
+ *
+ *   1. Buffers inbound bytes until the first '\n'.
+ *   2. Parses the line as a WireRequest (§7.6 — newline-delimited JSON,
+ *      one request per connection).
+ *   3. Routes by the `op` field to one of the four per-tool handlers.
+ *   4. Awaits the handler's WireResponse, writes it back as one
+ *      newline-delimited JSON line, then closes the socket.
+ *
+ * Concurrency: each accepted connection drives its own handler chain —
+ * the listener's data() pump is itself per-socket, so a slow handler on
+ * one connection can't block sibling dispatches. We deliberately do not
+ * await handler completion in the listener thread (the listener doesn't
+ * have a "thread" — Bun.listen calls our data() then returns
+ * immediately); the handler chain runs as a floating Promise that ends
+ * by writing + closing on its own socket.
+ *
+ * Stub handlers from §8.1–§8.5 fill in the real per-tool behavior. Until
+ * then, default stubs return a placeholder `{ action: 'done',
+ * message: '§8.X not yet implemented' }` so the wire still round-trips.
+ *
+ * Design: docs/design.mcp.md §2.3, §3.
+ */
+
+import type { AcceptedSocket } from './listener.ts';
+import type { WireOp, WireRequest, WireResponse } from './wire.ts';
+
+export type ParentDispatchHandler = (req: WireRequest) => Promise<WireResponse>;
+
+export type ParentDispatchHandlers = Record<WireOp, ParentDispatchHandler>;
+
+export interface CreateParentDispatcherArgs {
+  handlers: ParentDispatchHandlers;
+}
+
+/**
+ * Default per-tool stub handlers — the wire round-trips cleanly so the
+ * full §7 chain can be exercised before §8 lands the real implementations.
+ * Each returns `action: 'done'` plus a marker `message` that names the
+ * §8.x slot that will replace it.
+ */
+export const stubParentHandlers: ParentDispatchHandlers = {
+  restart: async (_req) => ({ action: 'done', message: '§8.1 fnc_restart not yet implemented' }),
+  switch: async (_req) => ({ action: 'done', message: '§8.2 fnc_switch_project not yet implemented' }),
+  spawn: async (_req) => ({ action: 'done', message: '§8.3 fnc_spawn_session not yet implemented' }),
+  copy_to_clipboard: async (_req) => ({
+    action: 'done',
+    message: '§8.4 fnc_copy_to_clipboard not yet implemented',
+  }),
+};
+
+const KNOWN_OPS = new Set<WireOp>(['restart', 'switch', 'spawn', 'copy_to_clipboard']);
+
+function isWireOp(value: unknown): value is WireOp {
+  return typeof value === 'string' && KNOWN_OPS.has(value as WireOp);
+}
+
+/**
+ * Build the `onConnection` callback shape that `startMcpListener` expects.
+ * The returned function is invoked once per accepted dial; the listener
+ * passes both the underlying `Socket` and the per-connection `handlers`
+ * slot, which we populate with our data/close/error implementations.
+ */
+export function createParentDispatcher(args: CreateParentDispatcherArgs): (accepted: AcceptedSocket) => void {
+  return (accepted) => {
+    let buffered = '';
+    let consumed = false;
+
+    const reply = async (response: WireResponse): Promise<void> => {
+      // Wire-protocol contract: write exactly one ndjson line, then close.
+      // Wrap write/end in try/catch — the peer may already have closed the
+      // half-duplex link by the time we finish the handler.
+      try {
+        accepted.socket.write(JSON.stringify(response) + '\n');
+      } catch {
+        // ignore — socket may be gone
+      }
+      try {
+        accepted.socket.end();
+      } catch {
+        // ignore
+      }
+    };
+
+    const errorReply = (err: string): Promise<void> => reply({ action: 'error', error: err });
+
+    accepted.handlers.data = (_socket, chunk) => {
+      if (consumed) {
+        // Per design.mcp.md §3 we read exactly one request per connection.
+        // Discard any pipelined bytes — subprocess never sends two on one dial.
+        return;
+      }
+      buffered += chunk.toString('utf8');
+      const nl = buffered.indexOf('\n');
+      if (nl === -1) return;
+      consumed = true;
+      const line = buffered.slice(0, nl);
+
+      // Float the handler chain — listener doesn't await us, and we don't
+      // need to block sibling sockets on this connection's handler latency.
+      void dispatchOne(line, args.handlers, reply, errorReply);
+    };
+
+    accepted.handlers.error = (_socket, _err) => {
+      // Nothing useful to do here — the subprocess errored its half of
+      // the connection. We've either already responded (in which case our
+      // .end() raced) or we're past the point of writing back anyway.
+      // §8 may want to log; for now stay quiet.
+    };
+
+    accepted.handlers.close = (_socket) => {
+      // Peer closed before we finished. Nothing to clean up — the
+      // dispatcher's state is per-call and goes out of scope on close.
+    };
+  };
+}
+
+async function dispatchOne(
+  line: string,
+  handlers: ParentDispatchHandlers,
+  reply: (r: WireResponse) => Promise<void>,
+  errorReply: (msg: string) => Promise<void>,
+): Promise<void> {
+  let request: unknown;
+  try {
+    request = JSON.parse(line);
+  } catch (err) {
+    await errorReply(`malformed request: ${(err as Error).message}`);
+    return;
+  }
+  if (request === null || typeof request !== 'object' || Array.isArray(request)) {
+    await errorReply('malformed request: expected JSON object');
+    return;
+  }
+  const op = (request as { op?: unknown }).op;
+  if (!isWireOp(op)) {
+    await errorReply(`unknown op: ${typeof op === 'string' ? op : '<missing>'}`);
+    return;
+  }
+  const handler = handlers[op];
+  let response: WireResponse;
+  try {
+    response = await handler(request as WireRequest);
+  } catch (err) {
+    await errorReply(`handler error: ${(err as Error).message}`);
+    return;
+  }
+  await reply(response);
+}

package/src/mcp/socket-path.ts

@@ -0,0 +1,48 @@
+/**
+ * AF_UNIX socket path computation for the parent fnclaude MCP listener.
+ *
+ * Pure function — takes the env map and a pid, returns the resolved path.
+ * Used by §7.2 to bind/listen, and by §6.1's env composition to set
+ * FNC_SOCKET on the child claude.
+ *
+ * Path formula (per design.md §14, design.mcp.md §1–2):
+ *
+ *   <base>/fnclaude-mcp-<pid>.sock
+ *
+ * Base directory preference (highest precedence first):
+ *   1. $XDG_RUNTIME_DIR — Linux/systemd tmpfs, mode 700, cleared on logout
+ *   2. $TMPDIR          — honored on Unix when XDG isn't set
+ *   3. /tmp             — final Unix fallback
+ *
+ * Empty-string env vars are treated as unset (matches Go canonical's
+ * `os.Getenv("X") != ""` check at src/handoff.go:55–82).
+ *
+ * Windows: throws. The Windows path (named pipe) is a §7 follow-up; for
+ * now the design.mcp.md §1 invariant — AF_UNIX with a PID-suffixed file
+ * under XDG_RUNTIME_DIR/TMPDIR — is Unix-only, so failing loudly beats
+ * returning a path the listener can't bind to.
+ */
+
+export interface ComputeSocketPathArgs {
+  env: Record<string, string | undefined>;
+  pid: number;
+  platform: NodeJS.Platform;
+}
+
+export function computeSocketPath(args: ComputeSocketPathArgs): string {
+  if (args.platform === 'win32') {
+    throw new Error(
+      'computeSocketPath: win32 not yet supported (AF_UNIX path only); see build-plan §7 follow-up',
+    );
+  }
+  const base = resolveBaseDir(args.env);
+  return `${base}/fnclaude-mcp-${args.pid}.sock`;
+}
+
+function resolveBaseDir(env: Record<string, string | undefined>): string {
+  const xdg = env.XDG_RUNTIME_DIR;
+  if (xdg !== undefined && xdg !== '') return xdg;
+  const tmp = env.TMPDIR;
+  if (tmp !== undefined && tmp !== '') return tmp;
+  return '/tmp';
+}

package/src/mcp/wire.ts

@@ -0,0 +1,181 @@
+/**
+ * §7.6 — Newline-delimited JSON wire format for the AF_UNIX MCP socket.
+ *
+ * One request → one response per connection. Subprocess dials, writes
+ * one JSON line, reads one JSON line, closes. Connections are not
+ * reused (per design.mcp.md §3). Each tool call gets a fresh dial.
+ *
+ * Timeouts (per design.mcp.md §3.3):
+ *   - 10s dial timeout: connect() must complete in 10s
+ *   - 10s per-call deadline: covers the open-connection write+read window
+ *
+ * On either timeout, the dial/call is rejected. Callers (the four tool
+ * handlers in §8) surface the rejection to claude as a tool-level error
+ * — i.e. a successful MCP response containing an error-shaped payload,
+ * NOT a JSON-RPC protocol error.
+ *
+ * Types are intentionally permissive: the wire shape is defined by the
+ * parent server in §7.7, so the subprocess only needs to carry fields
+ * through. WireRequest's `op` field is the one we constrain.
+ */
+
+export type WireOp = 'restart' | 'switch' | 'spawn' | 'copy_to_clipboard';
+
+export interface WireRequest {
+  op: WireOp;
+  [key: string]: unknown;
+}
+
+export interface WireResponse {
+  ok?: boolean;
+  action?: 'done' | 'paste_flow' | 'error' | string;
+  message?: string;
+  command?: string;
+  clipboard_ok?: boolean;
+  error?: string;
+  [key: string]: unknown;
+}
+
+export interface DialAndCallArgs {
+  socketPath: string;
+  request: WireRequest;
+  /** Connect timeout in milliseconds. Default 10s per design.mcp.md §3.3. */
+  dialTimeoutMs?: number;
+  /** Write+read deadline once the socket is open. Default 10s. */
+  callTimeoutMs?: number;
+}
+
+const DEFAULT_DIAL_TIMEOUT_MS = 10_000;
+const DEFAULT_CALL_TIMEOUT_MS = 10_000;
+
+/**
+ * Dial the AF_UNIX socket at `socketPath`, write `request` as one JSON
+ * line, read back one JSON line, close. Rejects on dial timeout, call
+ * timeout, malformed JSON in the response, or any underlying socket
+ * error (ECONNREFUSED, ENOENT, EPIPE, etc).
+ *
+ * The connection lifetime is bounded by the call timeout — even an
+ * actively-writing server can't keep us pinned past callTimeoutMs.
+ */
+export async function dialAndCall(args: DialAndCallArgs): Promise<WireResponse> {
+  const dialTimeoutMs = args.dialTimeoutMs ?? DEFAULT_DIAL_TIMEOUT_MS;
+  const callTimeoutMs = args.callTimeoutMs ?? DEFAULT_CALL_TIMEOUT_MS;
+  const payload = JSON.stringify(args.request) + '\n';
+
+  return new Promise<WireResponse>((resolve, reject) => {
+    let settled = false;
+    let dialTimer: ReturnType<typeof setTimeout> | undefined;
+    let callTimer: ReturnType<typeof setTimeout> | undefined;
+    let buffered = '';
+    // The Bun.connect Promise resolves with a Socket once the OS-level
+    // connect completes; we keep a handle here so the timeout branches
+    // can close it.
+    let socketHandle: { end: () => unknown } | undefined;
+
+    const cleanup = () => {
+      if (dialTimer !== undefined) clearTimeout(dialTimer);
+      if (callTimer !== undefined) clearTimeout(callTimer);
+      try {
+        socketHandle?.end();
+      } catch {
+        // ignore — socket may already be closed
+      }
+    };
+
+    const settleResolve = (value: WireResponse) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      resolve(value);
+    };
+
+    const settleReject = (err: Error) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      reject(err);
+    };
+
+    dialTimer = setTimeout(() => {
+      settleReject(
+        new Error(
+          `dialAndCall: dial timeout after ${dialTimeoutMs}ms connecting to ${args.socketPath}`,
+        ),
+      );
+    }, dialTimeoutMs);
+
+    Bun.connect({
+      unix: args.socketPath,
+      socket: {
+        open(socket) {
+          if (settled) {
+            socket.end();
+            return;
+          }
+          if (dialTimer !== undefined) clearTimeout(dialTimer);
+          dialTimer = undefined;
+          socketHandle = socket;
+          callTimer = setTimeout(() => {
+            settleReject(
+              new Error(
+                `dialAndCall: call timeout after ${callTimeoutMs}ms (socket ${args.socketPath})`,
+              ),
+            );
+          }, callTimeoutMs);
+          socket.write(payload);
+        },
+        data(socket, chunk) {
+          buffered += chunk.toString('utf8');
+          const nl = buffered.indexOf('\n');
+          if (nl === -1) return;
+          const line = buffered.slice(0, nl);
+          let parsed: WireResponse;
+          try {
+            parsed = JSON.parse(line) as WireResponse;
+          } catch (err) {
+            settleReject(
+              new Error(
+                `dialAndCall: malformed JSON response: ${(err as Error).message}`,
+              ),
+            );
+            return;
+          }
+          // Resolve BEFORE closing — Bun fires `close` synchronously
+          // from `end()`, which would otherwise race the settle flag.
+          settleResolve(parsed);
+          try {
+            socket.end();
+          } catch {
+            // ignore
+          }
+        },
+        error(_socket, err) {
+          settleReject(
+            new Error(
+              `dialAndCall: socket error (${args.socketPath}): ${(err as Error).message ?? err}`,
+            ),
+          );
+        },
+        close(_socket) {
+          if (!settled) {
+            settleReject(
+              new Error(
+                `dialAndCall: connection closed before response (${args.socketPath})`,
+              ),
+            );
+          }
+        },
+      },
+    }).catch((err: unknown) => {
+      // Bun.connect's returned Promise rejects on synchronous connect
+      // failures (ENOENT for a missing socket file, ECONNREFUSED if no
+      // listener, etc.). The `error` handler above covers post-open
+      // breaks; this catches the rest.
+      settleReject(
+        new Error(
+          `dialAndCall: connect failed (${args.socketPath}): ${(err as Error).message ?? err}`,
+        ),
+      );
+    });
+  });
+}