test(FN-705): add comprehensive unit tests for IpcHost and IpcWorker

- Add IpcHost tests: constructor, sendCommand correlation, ping, event forwarding, malformed message handling, disconnection cascade, explicit cleanup
- Add IpcWorker tests: constructor validation, PING auto-response, command handler registration/dispatch, OK/ERROR responses, sendEvent/sendErrorEvent, shutdown idempotency
- Fix TypeScript type mismatch in mock ChildProcess.send signature
- Mock logger and process IPC to enable isolated unit testing without real child processes
- Cover edge cases: timeouts, disconnected sends, unknown commands, malformed messages

packages/engine/src/ipc/ipc-host.test.ts

@@ -0,0 +1,471 @@
+/**
+ * Unit tests for IpcHost — the parent-side IPC handler that sends commands
+ * to a child process worker and correlates responses.
+ *
+ * Coverage:
+ * - Constructor: listener setup, options, initial state
+ * - sendCommand: serialization, response correlation (OK/ERROR/PONG), timeout, disconnection
+ * - ping: convenience wrapper for sendCommand("PING")
+ * - Event forwarding: worker events emitted on IpcHost
+ * - Malformed/unknown messages: silently ignored
+ * - Disconnection cascade: child error/exit/disconnect → pending commands rejected
+ * - disconnect(): explicit cleanup and listener removal
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { EventEmitter } from "node:events";
+import type { ChildProcess } from "node:child_process";
+import { IpcHost } from "./ipc-host.js";
+import { OK, ERROR, PONG, TASK_CREATED } from "./ipc-protocol.js";
+
+// ── Mock logger to suppress console output ──────────────────────────────
+vi.mock("../logger.js", () => ({
+  ipcLog: {
+    log: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+  },
+}));
+
+// ── Mock ChildProcess factory ───────────────────────────────────────────
+
+/**
+ * Creates a mock ChildProcess that is an EventEmitter with the required
+ * properties for IpcHost: `send`, `connected`, `disconnect`.
+ */
+function createMockChildProcess(
+  overrides: {
+    connected?: boolean;
+    send?: ((...args: any[]) => any) | undefined;
+  } = {}
+): ChildProcess {
+  const emitter = new EventEmitter();
+  const mock = emitter as unknown as ChildProcess & EventEmitter;
+
+  // Default: connected with a working send
+  Object.defineProperty(mock, "connected", {
+    get: () => overrides.connected ?? true,
+    configurable: true,
+  });
+
+  if (overrides.send === undefined && !("send" in overrides)) {
+    // Default: working send that invokes callback with no error
+    (mock as any).send = vi.fn((...args: any[]) => {
+      const callback = args.find((a: unknown) => typeof a === "function");
+      if (callback) callback(null);
+      return true;
+    });
+  } else {
+    (mock as any).send = overrides.send;
+  }
+
+  (mock as any).disconnect = vi.fn();
+  (mock as any).kill = vi.fn();
+  (mock as any).killed = false;
+  (mock as any).pid = 12345;
+
+  return mock;
+}
+
+// ── Tests ────────────────────────────────────────────────────────────────
+
+describe("IpcHost", () => {
+  let child: ChildProcess & EventEmitter;
+  let host: IpcHost;
+
+  beforeEach(() => {
+    child = createMockChildProcess() as ChildProcess & EventEmitter;
+    host = new IpcHost(child);
+  });
+
+  afterEach(() => {
+    host.removeAllListeners();
+  });
+
+  // ── Constructor & initial state ──────────────────────────────────────
+
+  describe("constructor and initial state", () => {
+    it("registers listeners on child process for message, error, exit, disconnect events", () => {
+      // EventEmitter.listenerCount shows listeners were added
+      expect(child.listenerCount("message")).toBeGreaterThanOrEqual(1);
+      expect(child.listenerCount("error")).toBeGreaterThanOrEqual(1);
+      expect(child.listenerCount("exit")).toBeGreaterThanOrEqual(1);
+      expect(child.listenerCount("disconnect")).toBeGreaterThanOrEqual(1);
+    });
+
+    it("isConnected() returns true when child is connected and not disconnected", () => {
+      expect(host.isConnected()).toBe(true);
+    });
+
+    it("isConnected() returns false after disconnection", () => {
+      child.emit("disconnect");
+      expect(host.isConnected()).toBe(false);
+    });
+
+    it("getChildProcess() returns the child process instance", () => {
+      expect(host.getChildProcess()).toBe(child);
+    });
+
+    it("getPendingCommandCount() returns 0 initially", () => {
+      expect(host.getPendingCommandCount()).toBe(0);
+    });
+
+    it("accepts custom commandTimeoutMs option", () => {
+      // We verify this indirectly in the timeout test in Step 2
+      const customHost = new IpcHost(child, { commandTimeoutMs: 500 });
+      expect(customHost).toBeInstanceOf(IpcHost);
+      customHost.removeAllListeners();
+    });
+  });
+
+  // ── sendCommand and response correlation ────────────────────────────
+
+  describe("sendCommand", () => {
+    it("sends a valid IpcMessage via childProcess.send() with correct type, unique id, and payload", async () => {
+      const sendFn = child.send as ReturnType<typeof vi.fn>;
+      const commandPromise = host.sendCommand("GET_STATUS", { foo: "bar" });
+
+      // Extract the message from the mock send call
+      expect(sendFn).toHaveBeenCalledTimes(1);
+      const sentMessage = sendFn.mock.calls[0][0];
+      expect(sentMessage.type).toBe("GET_STATUS");
+      expect(typeof sentMessage.id).toBe("string");
+      expect(sentMessage.id.length).toBeGreaterThan(0);
+      expect(sentMessage.payload).toEqual({ foo: "bar" });
+
+      // Respond to resolve the promise
+      child.emit("message", { type: OK, id: sentMessage.id, payload: { data: "result" } });
+      await expect(commandPromise).resolves.toBe("result");
+    });
+
+    it("resolves with data when child responds with OK matching the correlation ID", async () => {
+      const sendFn = child.send as ReturnType<typeof vi.fn>;
+      const promise = host.sendCommand("GET_METRICS", {});
+
+      const sentId = sendFn.mock.calls[0][0].id;
+      child.emit("message", { type: OK, id: sentId, payload: { data: { tasks: 5 } } });
+
+      await expect(promise).resolves.toEqual({ tasks: 5 });
+    });
+
+    it("rejects with an Error (including message and code) when child responds with ERROR", async () => {
+      const sendFn = child.send as ReturnType<typeof vi.fn>;
+      const promise = host.sendCommand("GET_STATUS", {});
+
+      const sentId = sendFn.mock.calls[0][0].id;
+      child.emit("message", {
+        type: ERROR,
+        id: sentId,
+        payload: { message: "Something went wrong", code: "HANDLER_ERROR" },
+      });
+
+      await expect(promise).rejects.toThrow("Something went wrong");
+      try {
+        await promise;
+      } catch (err: any) {
+        expect(err.code).toBe("HANDLER_ERROR");
+      }
+    });
+
+    it("resolves with pong payload when child responds with PONG", async () => {
+      const sendFn = child.send as ReturnType<typeof vi.fn>;
+      const promise = host.sendCommand("PING", {});
+
+      const sentId = sendFn.mock.calls[0][0].id;
+      child.emit("message", {
+        type: PONG,
+        id: sentId,
+        payload: { timestamp: "2026-04-01T00:00:00.000Z" },
+      });
+
+      await expect(promise).resolves.toEqual({ timestamp: "2026-04-01T00:00:00.000Z" });
+    });
+
+    it("rejects after timeout using fake timers", async () => {
+      vi.useFakeTimers();
+      try {
+        const promise = host.sendCommand("GET_STATUS", {}, 1000);
+
+        // Advance past the timeout
+        vi.advanceTimersByTime(1001);
+
+        await expect(promise).rejects.toThrow("timed out after 1000ms");
+      } finally {
+        vi.useRealTimers();
+      }
+    });
+
+    it("uses custom commandTimeoutMs when no per-call override provided", async () => {
+      vi.useFakeTimers();
+      try {
+        const shortHost = new IpcHost(child, { commandTimeoutMs: 200 });
+        const promise = shortHost.sendCommand("GET_STATUS", {});
+
+        vi.advanceTimersByTime(201);
+
+        await expect(promise).rejects.toThrow("timed out after 200ms");
+        shortHost.removeAllListeners();
+      } finally {
+        vi.useRealTimers();
+      }
+    });
+
+    it("clears pending command on successful response (getPendingCommandCount returns 0)", async () => {
+      const sendFn = child.send as ReturnType<typeof vi.fn>;
+      const promise = host.sendCommand("GET_STATUS", {});
+
+      expect(host.getPendingCommandCount()).toBe(1);
+
+      const sentId = sendFn.mock.calls[0][0].id;
+      child.emit("message", { type: OK, id: sentId, payload: { data: null } });
+      await promise;
+
+      expect(host.getPendingCommandCount()).toBe(0);
+    });
+
+    it("rejects immediately when IPC is already disconnected", async () => {
+      child.emit("disconnect");
+
+      await expect(host.sendCommand("GET_STATUS", {})).rejects.toThrow(
+        "Cannot send command: IPC channel disconnected"
+      );
+    });
+
+    it("rejects when childProcess.send is undefined (no IPC channel)", async () => {
+      const noSendChild = createMockChildProcess({ send: undefined }) as ChildProcess & EventEmitter;
+      const noSendHost = new IpcHost(noSendChild);
+
+      await expect(noSendHost.sendCommand("GET_STATUS", {})).rejects.toThrow(
+        "Child process does not have IPC channel"
+      );
+      noSendHost.removeAllListeners();
+    });
+
+    it("rejects when childProcess.send callback returns an error", async () => {
+      const errChild = createMockChildProcess({
+        send: vi.fn((...args: any[]) => {
+          // Find the callback argument (last function arg)
+          const callback = args.find((a: unknown) => typeof a === "function");
+          if (callback) callback(new Error("Send failed"));
+          return false;
+        }) as any,
+      }) as ChildProcess & EventEmitter;
+      const errHost = new IpcHost(errChild);
+
+      await expect(errHost.sendCommand("GET_STATUS", {})).rejects.toThrow("Failed to send command: Send failed");
+      errHost.removeAllListeners();
+    });
+  });
+
+  // ── ping ─────────────────────────────────────────────────────────────
+
+  describe("ping", () => {
+    it("calls sendCommand('PING', {}, 5000) and resolves with timestamp", async () => {
+      const sendFn = child.send as ReturnType<typeof vi.fn>;
+      const promise = host.ping();
+
+      const sentMessage = sendFn.mock.calls[0][0];
+      expect(sentMessage.type).toBe("PING");
+
+      child.emit("message", {
+        type: PONG,
+        id: sentMessage.id,
+        payload: { timestamp: "2026-04-01T12:00:00.000Z" },
+      });
+
+      const result = await promise;
+      expect(result).toEqual({ timestamp: "2026-04-01T12:00:00.000Z" });
+    });
+  });
+
+  // ── Event forwarding ────────────────────────────────────────────────
+
+  describe("event forwarding", () => {
+    it("incoming event messages are emitted on IpcHost with the event type and payload", () => {
+      const handler = vi.fn();
+      host.on(TASK_CREATED, handler);
+
+      const payload = { task: { id: "KB-001", title: "Test" } };
+      child.emit("message", {
+        type: TASK_CREATED,
+        id: "evt-1",
+        payload,
+      });
+
+      expect(handler).toHaveBeenCalledTimes(1);
+      expect(handler).toHaveBeenCalledWith(payload);
+    });
+
+    it('generic "message" event is also emitted for every incoming event message', () => {
+      const handler = vi.fn();
+      host.on("message", handler);
+
+      const message = { type: TASK_CREATED, id: "evt-2", payload: { task: {} } };
+      child.emit("message", message);
+
+      expect(handler).toHaveBeenCalledTimes(1);
+      expect(handler).toHaveBeenCalledWith(message);
+    });
+  });
+
+  // ── Malformed messages ──────────────────────────────────────────────
+
+  describe("malformed messages", () => {
+    it("silently ignores message missing type", () => {
+      const handler = vi.fn();
+      host.on("message", handler);
+
+      // Missing type
+      child.emit("message", { id: "x", payload: {} });
+      expect(handler).not.toHaveBeenCalled();
+    });
+
+    it("silently ignores message missing id", () => {
+      const handler = vi.fn();
+      host.on("message", handler);
+
+      child.emit("message", { type: "SOME_TYPE", payload: {} });
+      expect(handler).not.toHaveBeenCalled();
+    });
+
+    it("silently ignores message missing payload", () => {
+      const handler = vi.fn();
+      host.on("message", handler);
+
+      child.emit("message", { type: "SOME_TYPE", id: "x" });
+      expect(handler).not.toHaveBeenCalled();
+    });
+
+    it("silently ignores non-object messages", () => {
+      const handler = vi.fn();
+      host.on("message", handler);
+
+      child.emit("message", "not an object");
+      child.emit("message", null);
+      child.emit("message", 42);
+      expect(handler).not.toHaveBeenCalled();
+    });
+
+    it("ignores response for unknown correlation ID without crashing", () => {
+      // Should not throw
+      child.emit("message", {
+        type: OK,
+        id: "unknown-correlation-id",
+        payload: { data: "phantom" },
+      });
+
+      expect(host.getPendingCommandCount()).toBe(0);
+    });
+  });
+
+  // ── Disconnection cascade ───────────────────────────────────────────
+
+  describe("disconnection", () => {
+    it("child error event rejects all pending commands with 'IPC disconnected' error and emits 'disconnect'", async () => {
+      vi.useFakeTimers();
+      try {
+        const disconnectHandler = vi.fn();
+        host.on("disconnect", disconnectHandler);
+
+        const promise = host.sendCommand("GET_STATUS", {});
+        expect(host.getPendingCommandCount()).toBe(1);
+
+        child.emit("error", new Error("child crash"));
+
+        await expect(promise).rejects.toThrow("IPC disconnected");
+        expect(host.getPendingCommandCount()).toBe(0);
+        expect(disconnectHandler).toHaveBeenCalledTimes(1);
+      } finally {
+        vi.useRealTimers();
+      }
+    });
+
+    it("child exit event (with code) triggers disconnection", async () => {
+      vi.useFakeTimers();
+      try {
+        const disconnectHandler = vi.fn();
+        host.on("disconnect", disconnectHandler);
+
+        const promise = host.sendCommand("GET_STATUS", {});
+
+        child.emit("exit", 1, null);
+
+        await expect(promise).rejects.toThrow("IPC disconnected");
+        expect(disconnectHandler).toHaveBeenCalledTimes(1);
+      } finally {
+        vi.useRealTimers();
+      }
+    });
+
+    it("child exit event (with signal) triggers disconnection", async () => {
+      vi.useFakeTimers();
+      try {
+        const disconnectHandler = vi.fn();
+        host.on("disconnect", disconnectHandler);
+
+        const promise = host.sendCommand("GET_STATUS", {});
+
+        child.emit("exit", null, "SIGTERM");
+
+        await expect(promise).rejects.toThrow("IPC disconnected");
+        expect(disconnectHandler).toHaveBeenCalledTimes(1);
+      } finally {
+        vi.useRealTimers();
+      }
+    });
+
+    it("child disconnect event triggers disconnection", async () => {
+      vi.useFakeTimers();
+      try {
+        const disconnectHandler = vi.fn();
+        host.on("disconnect", disconnectHandler);
+
+        const promise = host.sendCommand("GET_STATUS", {});
+
+        child.emit("disconnect");
+
+        await expect(promise).rejects.toThrow("IPC disconnected");
+        expect(disconnectHandler).toHaveBeenCalledTimes(1);
+      } finally {
+        vi.useRealTimers();
+      }
+    });
+
+    it("double disconnection is idempotent (no re-reject or double-emit)", () => {
+      const disconnectHandler = vi.fn();
+      host.on("disconnect", disconnectHandler);
+
+      child.emit("disconnect");
+      child.emit("disconnect");
+
+      expect(disconnectHandler).toHaveBeenCalledTimes(1);
+    });
+
+    it("disconnect() method rejects pending commands, calls childProcess.disconnect(), removes all listeners", async () => {
+      vi.useFakeTimers();
+      try {
+        const promise = host.sendCommand("GET_STATUS", {});
+        expect(host.getPendingCommandCount()).toBe(1);
+
+        host.disconnect();
+
+        await expect(promise).rejects.toThrow("IPC disconnected");
+        expect(host.getPendingCommandCount()).toBe(0);
+        expect((child as any).disconnect).toHaveBeenCalled();
+      } finally {
+        vi.useRealTimers();
+      }
+    });
+
+    it("disconnect() skips childProcess.disconnect() when already disconnected", () => {
+      // Simulate child already disconnected
+      Object.defineProperty(child, "connected", {
+        get: () => false,
+        configurable: true,
+      });
+
+      host.disconnect();
+      // disconnect() should not call child.disconnect() since connected is false
+      expect((child as any).disconnect).not.toHaveBeenCalled();
+    });
+  });
+});

packages/engine/src/ipc/ipc-worker.test.ts

@@ -0,0 +1,492 @@
+/**
+ * Unit tests for IpcWorker — the child-process-side IPC handler that receives
+ * commands from a host, dispatches to registered handlers, and sends responses/events.
+ *
+ * Coverage:
+ * - Constructor: process.send validation, listener registration, initial state
+ * - PING auto-response (no handler needed)
+ * - onCommand / offCommand: handler registration and dispatch
+ * - Command execution: OK response, ERROR response (Error and non-Error), NO_HANDLER, UNKNOWN_COMMAND, MALFORMED_MESSAGE
+ * - sendEvent / sendErrorEvent: event message construction
+ * - sendResponse: response message construction
+ * - shutdown: idempotent, suppresses further sends, emits event
+ * - disconnect event forwarding
+ * - Edge cases: process.send undefined after construction, graceful fallback
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { PING, PONG, OK, ERROR, TASK_CREATED, ERROR_EVENT } from "./ipc-protocol.js";
+
+// ── Mock logger to suppress console output ──────────────────────────────
+vi.mock("../logger.js", () => ({
+  ipcLog: {
+    log: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+  },
+}));
+
+// ── Process mock utilities ──────────────────────────────────────────────
+
+/**
+ * We need to mock process.send and intercept process.on("message") handlers
+ * without breaking the real process. Strategy:
+ * - Set process.send to a vi.fn() before creating IpcWorker
+ * - Track message handlers registered via process.on("message")
+ * - Simulate incoming messages by calling those handlers directly
+ */
+
+// Store the original process.send to restore after tests
+const originalProcessSend = process.send;
+
+// Track registered message/disconnect handlers so we can invoke them
+let messageHandlers: Array<(msg: unknown) => void> = [];
+let disconnectHandlers: Array<() => void> = [];
+
+// Spies for process.on and process.removeAllListeners
+let processOnSpy: ReturnType<typeof vi.fn>;
+
+function setupProcessMocks() {
+  // Set up process.send as a mock function
+  process.send = vi.fn((_msg: unknown, _handle?: unknown, _options?: unknown, callback?: (err: Error | null) => void) => {
+    if (typeof callback === "function") callback(null);
+    return true;
+  });
+
+  messageHandlers = [];
+  disconnectHandlers = [];
+
+  // Intercept process.on to capture message/disconnect handlers
+  const originalProcessOn = process.on.bind(process);
+  processOnSpy = vi.fn((event: string, handler: (...args: any[]) => void) => {
+    if (event === "message") {
+      messageHandlers.push(handler);
+    } else if (event === "disconnect") {
+      disconnectHandlers.push(handler);
+    }
+    // Don't register signal handlers on real process during tests
+    if (event === "SIGTERM" || event === "SIGINT" || event === "uncaughtException" || event === "unhandledRejection") {
+      return process;
+    }
+    return originalProcessOn(event, handler);
+  });
+  process.on = processOnSpy as any;
+}
+
+function teardownProcessMocks() {
+  // Restore process.send
+  if (originalProcessSend === undefined) {
+    delete (process as any).send;
+  } else {
+    process.send = originalProcessSend;
+  }
+
+  // Remove any listeners we added during the test
+  for (const handler of messageHandlers) {
+    process.removeListener("message", handler);
+  }
+  for (const handler of disconnectHandlers) {
+    process.removeListener("disconnect", handler);
+  }
+  messageHandlers = [];
+  disconnectHandlers = [];
+}
+
+/** Simulate an incoming message from the host */
+function simulateMessage(msg: unknown) {
+  for (const handler of messageHandlers) {
+    handler(msg);
+  }
+}
+
+/** Simulate a disconnect event */
+function simulateDisconnect() {
+  for (const handler of disconnectHandlers) {
+    handler();
+  }
+}
+
+// ── Tests ────────────────────────────────────────────────────────────────
+
+describe("IpcWorker", () => {
+  // We need to dynamically import IpcWorker after mocks are set up
+  let IpcWorker: typeof import("./ipc-worker.js").IpcWorker;
+
+  beforeEach(async () => {
+    setupProcessMocks();
+    // Dynamic import to get fresh module (the mock setup needs to be in place)
+    const mod = await import("./ipc-worker.js");
+    IpcWorker = mod.IpcWorker;
+  });
+
+  afterEach(() => {
+    teardownProcessMocks();
+  });
+
+  // ── Constructor & initial state ──────────────────────────────────────
+
+  describe("constructor and initial state", () => {
+    it("throws when process.send is undefined", async () => {
+      teardownProcessMocks(); // Remove mock
+      // Ensure process.send is undefined
+      delete (process as any).send;
+
+      expect(() => new IpcWorker()).toThrow(
+        "IpcWorker can only be instantiated in a forked child process"
+      );
+
+      // Re-set up for afterEach
+      setupProcessMocks();
+      const mod = await import("./ipc-worker.js");
+      IpcWorker = mod.IpcWorker;
+    });
+
+    it("registers listeners on process for message and disconnect events", () => {
+      const worker = new IpcWorker();
+      expect(messageHandlers.length).toBeGreaterThanOrEqual(1);
+      expect(disconnectHandlers.length).toBeGreaterThanOrEqual(1);
+      worker.removeAllListeners();
+    });
+
+    it("getHandlerCount() returns 0 initially", () => {
+      const worker = new IpcWorker();
+      expect(worker.getHandlerCount()).toBe(0);
+      worker.removeAllListeners();
+    });
+
+    it("isShuttingDown() returns false initially", () => {
+      const worker = new IpcWorker();
+      expect(worker.isShuttingDown()).toBe(false);
+      worker.removeAllListeners();
+    });
+  });
+
+  /**
+   * Helper: creates a worker and returns it along with its dedicated message handler.
+   * Also clears the process.send mock so each test starts fresh.
+   */
+  function createWorker() {
+    const msgCountBefore = messageHandlers.length;
+    const discCountBefore = disconnectHandlers.length;
+    const worker = new IpcWorker();
+    const sendFn = process.send as ReturnType<typeof vi.fn>;
+    sendFn.mockClear();
+
+    // The worker's handlers are the ones added after the counts
+    const workerMsgHandler = messageHandlers[messageHandlers.length - 1];
+    const workerDiscHandler = disconnectHandlers[disconnectHandlers.length - 1];
+
+    /** Send a message to this worker's handler */
+    const sendMessage = (msg: unknown) => workerMsgHandler(msg);
+
+    /** Simulate disconnect for this specific worker */
+    const triggerDisconnect = () => workerDiscHandler?.();
+
+    /** Get all messages sent to parent via process.send since last clear */
+    const getSentMessages = () => sendFn.mock.calls.map((call: any[]) => call[0]);
+
+    /** Find the first sent message matching a type */
+    const findSent = (type: string) =>
+      sendFn.mock.calls.find((call: any[]) => call[0]?.type === type)?.[0];
+
+    return { worker, sendMessage, triggerDisconnect, sendFn, getSentMessages, findSent };
+  }
+
+  // ── PING auto-response ──────────────────────────────────────────────
+
+  describe("PING handling", () => {
+    it("incoming PING message automatically responds with PONG containing a timestamp", async () => {
+      const { worker, sendMessage, findSent } = createWorker();
+
+      sendMessage({ type: PING, id: "ping-1", payload: {} });
+
+      // handleMessage is async, give it a tick
+      await vi.waitFor(() => {
+        expect(findSent(PONG)).toBeDefined();
+      });
+
+      const response = findSent(PONG);
+      expect(response.type).toBe(PONG);
+      expect(response.id).toBe("ping-1");
+      expect(typeof response.payload.timestamp).toBe("string");
+      worker.removeAllListeners();
+    });
+  });
+
+  // ── Command handling ────────────────────────────────────────────────
+
+  describe("command handling", () => {
+    it("onCommand() registers a handler: getHandlerCount() increments", () => {
+      const { worker } = createWorker();
+      expect(worker.getHandlerCount()).toBe(0);
+
+      worker.onCommand("START_RUNTIME", async () => ({ success: true }));
+      expect(worker.getHandlerCount()).toBe(1);
+
+      worker.onCommand("STOP_RUNTIME", async () => {});
+      expect(worker.getHandlerCount()).toBe(2);
+      worker.removeAllListeners();
+    });
+
+    it("offCommand() removes a handler: getHandlerCount() decrements", () => {
+      const { worker } = createWorker();
+      worker.onCommand("START_RUNTIME", async () => {});
+      expect(worker.getHandlerCount()).toBe(1);
+
+      worker.offCommand("START_RUNTIME");
+      expect(worker.getHandlerCount()).toBe(0);
+      worker.removeAllListeners();
+    });
+
+    it("receiving a registered command invokes the handler with the message payload", async () => {
+      const handler = vi.fn().mockResolvedValue("ok");
+      const { worker, sendMessage } = createWorker();
+      worker.onCommand("GET_STATUS", handler);
+
+      const payload = { detail: "test" };
+      sendMessage({ type: "GET_STATUS", id: "cmd-1", payload });
+
+      await vi.waitFor(() => {
+        expect(handler).toHaveBeenCalledWith(payload);
+      });
+      worker.removeAllListeners();
+    });
+
+    it("handler returning a value sends OK response with { data: returnValue }", async () => {
+      const { worker, sendMessage, findSent } = createWorker();
+      worker.onCommand("GET_METRICS", async () => ({ tasks: 10 }));
+
+      sendMessage({ type: "GET_METRICS", id: "cmd-2", payload: {} });
+
+      await vi.waitFor(() => {
+        expect(findSent(OK)).toBeDefined();
+      });
+
+      const response = findSent(OK);
+      expect(response.type).toBe(OK);
+      expect(response.id).toBe("cmd-2");
+      expect(response.payload).toEqual({ data: { tasks: 10 } });
+      worker.removeAllListeners();
+    });
+
+    it("handler throwing an error sends ERROR response with { message, code: 'HANDLER_ERROR' }", async () => {
+      const { worker, sendMessage, findSent } = createWorker();
+      worker.onCommand("GET_STATUS", async () => {
+        throw new Error("Something broke");
+      });
+
+      sendMessage({ type: "GET_STATUS", id: "cmd-3", payload: {} });
+
+      await vi.waitFor(() => {
+        expect(findSent(ERROR)).toBeDefined();
+      });
+
+      const response = findSent(ERROR);
+      expect(response.type).toBe(ERROR);
+      expect(response.id).toBe("cmd-3");
+      expect(response.payload.message).toBe("Something broke");
+      expect(response.payload.code).toBe("HANDLER_ERROR");
+      worker.removeAllListeners();
+    });
+
+    it("handler throwing a non-Error value still sends ERROR response with stringified message", async () => {
+      const { worker, sendMessage, findSent } = createWorker();
+      worker.onCommand("GET_STATUS", async () => {
+        throw "string error"; // eslint-disable-line no-throw-literal
+      });
+
+      sendMessage({ type: "GET_STATUS", id: "cmd-4", payload: {} });
+
+      await vi.waitFor(() => {
+        expect(findSent(ERROR)).toBeDefined();
+      });
+
+      const response = findSent(ERROR);
+      expect(response.type).toBe(ERROR);
+      expect(response.id).toBe("cmd-4");
+      expect(response.payload.message).toBe("string error");
+      worker.removeAllListeners();
+    });
+
+    it("receiving a command with no registered handler sends ERROR with code: 'NO_HANDLER'", async () => {
+      const { worker, sendMessage, findSent } = createWorker();
+      // Don't register any handler for START_RUNTIME
+      sendMessage({ type: "START_RUNTIME", id: "cmd-5", payload: {} });
+
+      await vi.waitFor(() => {
+        expect(findSent(ERROR)).toBeDefined();
+      });
+
+      const response = findSent(ERROR);
+      expect(response.payload.code).toBe("NO_HANDLER");
+      expect(response.id).toBe("cmd-5");
+      worker.removeAllListeners();
+    });
+
+    it("receiving a non-command (unknown type) sends ERROR with code: 'UNKNOWN_COMMAND'", async () => {
+      const { worker, sendMessage, findSent } = createWorker();
+      sendMessage({ type: "TOTALLY_UNKNOWN", id: "cmd-6", payload: {} });
+
+      await vi.waitFor(() => {
+        expect(findSent(ERROR)).toBeDefined();
+      });
+
+      const response = findSent(ERROR);
+      expect(response.payload.code).toBe("UNKNOWN_COMMAND");
+      expect(response.id).toBe("cmd-6");
+      worker.removeAllListeners();
+    });
+
+    it("receiving a malformed message (not a valid IpcMessage) sends ERROR with code: 'MALFORMED_MESSAGE'", async () => {
+      const { worker, sendMessage, findSent } = createWorker();
+      sendMessage({ noType: true }); // Missing type, id, payload
+
+      await vi.waitFor(() => {
+        expect(findSent(ERROR)).toBeDefined();
+      });
+
+      const response = findSent(ERROR);
+      expect(response.payload.code).toBe("MALFORMED_MESSAGE");
+      worker.removeAllListeners();
+    });
+  });
+
+  // ── sendEvent / sendErrorEvent ──────────────────────────────────────
+
+  describe("sendEvent and sendErrorEvent", () => {
+    it("sendEvent() sends an IpcMessage with the given event type, a generated correlation ID, and payload", () => {
+      const { worker, sendFn } = createWorker();
+
+      worker.sendEvent(TASK_CREATED, { task: { id: "KB-001" } });
+
+      expect(sendFn).toHaveBeenCalledTimes(1);
+      const msg = sendFn.mock.calls[0][0];
+      expect(msg.type).toBe(TASK_CREATED);
+      expect(typeof msg.id).toBe("string");
+      expect(msg.id.length).toBeGreaterThan(0);
+      expect(msg.payload).toEqual({ task: { id: "KB-001" } });
+      worker.removeAllListeners();
+    });
+
+    it("sendErrorEvent() sends an ERROR_EVENT typed message with error message and code", () => {
+      const { worker, sendFn } = createWorker();
+
+      const err = new Error("Runtime crashed");
+      (err as any).code = "RUNTIME_ERROR";
+      worker.sendErrorEvent(err);
+
+      expect(sendFn).toHaveBeenCalledTimes(1);
+      const msg = sendFn.mock.calls[0][0];
+      expect(msg.type).toBe(ERROR_EVENT);
+      expect(msg.payload).toEqual({
+        message: "Runtime crashed",
+        code: "RUNTIME_ERROR",
+      });
+      worker.removeAllListeners();
+    });
+  });
+
+  // ── Shutdown ────────────────────────────────────────────────────────
+
+  describe("shutdown", () => {
+    it("sets isShuttingDown() to true", () => {
+      const { worker } = createWorker();
+      expect(worker.isShuttingDown()).toBe(false);
+      worker.shutdown();
+      expect(worker.isShuttingDown()).toBe(true);
+      worker.removeAllListeners();
+    });
+
+    it("sends a SHUTDOWN message to parent via process.send", () => {
+      const { worker, sendFn } = createWorker();
+      worker.shutdown();
+
+      expect(sendFn).toHaveBeenCalledTimes(1);
+      const msg = sendFn.mock.calls[0][0];
+      expect(msg.type).toBe("SHUTDOWN");
+      expect(typeof msg.id).toBe("string");
+      expect(msg.payload).toEqual({});
+      worker.removeAllListeners();
+    });
+
+    it('emits "shutdown" event on the IpcWorker instance', () => {
+      const { worker } = createWorker();
+      const handler = vi.fn();
+      worker.on("shutdown", handler);
+      worker.shutdown();
+      expect(handler).toHaveBeenCalledTimes(1);
+      worker.removeAllListeners();
+    });
+
+    it("is idempotent (calling twice only sends one SHUTDOWN message)", () => {
+      const { worker, sendFn } = createWorker();
+      worker.shutdown();
+      worker.shutdown();
+
+      // Only one SHUTDOWN message should be sent
+      expect(sendFn).toHaveBeenCalledTimes(1);
+      worker.removeAllListeners();
+    });
+
+    it("after shutdown(), sendEvent() and sendResponse() are no-ops", () => {
+      const { worker, sendFn } = createWorker();
+      worker.shutdown();
+      sendFn.mockClear();
+
+      worker.sendEvent(TASK_CREATED, { task: {} });
+      worker.sendResponse(OK, "some-id", { data: null });
+
+      expect(sendFn).not.toHaveBeenCalled();
+      worker.removeAllListeners();
+    });
+  });
+
+  // ── Disconnect ──────────────────────────────────────────────────────
+
+  describe("disconnect", () => {
+    it('process disconnect event emits "disconnect" on IpcWorker', () => {
+      const { worker, triggerDisconnect } = createWorker();
+      const handler = vi.fn();
+      worker.on("disconnect", handler);
+
+      triggerDisconnect();
+
+      expect(handler).toHaveBeenCalledTimes(1);
+      worker.removeAllListeners();
+    });
+  });
+
+  // ── Edge cases ──────────────────────────────────────────────────────
+
+  describe("edge cases", () => {
+    it("sendEvent() when process.send is undefined does not throw (graceful fallback)", () => {
+      const { worker } = createWorker();
+
+      // Remove process.send after construction
+      const savedSend = process.send;
+      delete (process as any).send;
+
+      expect(() => {
+        worker.sendEvent(TASK_CREATED, { task: {} });
+      }).not.toThrow();
+
+      // Restore
+      process.send = savedSend;
+      worker.removeAllListeners();
+    });
+
+    it("sendResponse() sends correctly structured IpcMessage with type, id, and payload", () => {
+      const { worker, sendFn } = createWorker();
+
+      worker.sendResponse(OK, "resp-id-1", { data: { status: "active" } });
+
+      expect(sendFn).toHaveBeenCalledTimes(1);
+      const msg = sendFn.mock.calls[0][0];
+      expect(msg).toEqual({
+        type: OK,
+        id: "resp-id-1",
+        payload: { data: { status: "active" } },
+      });
+      worker.removeAllListeners();
+    });
+  });
+});