@selesai/code 0.5.28 → 0.6.1

package/dist/extensions/pi-intercom/broker/framing.ts

@@ -1,15 +1,18 @@
 import type { Socket } from "net";
 
+export const MAX_FRAME_BYTES = 1024 * 1024;
+
 /**
  * Write a length-prefixed message to a socket.
  * Format: 4-byte big-endian length + JSON payload
  */
 export function writeMessage(socket: Socket, msg: unknown): void {
   const json = JSON.stringify(msg);
-  const payload = Buffer.from(json, "utf-8");
-  const header = Buffer.alloc(4);
-  header.writeUInt32BE(payload.length, 0);
-  socket.write(Buffer.concat([header, payload]));
+  const payloadLength = Buffer.byteLength(json, "utf-8");
+  const frame = Buffer.allocUnsafe(4 + payloadLength);
+  frame.writeUInt32BE(payloadLength, 0);
+  frame.write(json, 4, payloadLength, "utf-8");
+  socket.write(frame);
 }
 
 /**
@@ -20,36 +23,91 @@ export function writeMessage(socket: Socket, msg: unknown): void {
 export function createMessageReader(
   onMessage: (msg: unknown) => void,
   onError: (error: Error) => void,
+  maxFrameBytes = MAX_FRAME_BYTES,
 ) {
-  let buffer = Buffer.alloc(0);
+  const header = Buffer.allocUnsafe(4);
+  let headerBytes = 0;
+  let payload: Buffer | null = null;
+  let payloadBytes = 0;
+  let payloadLength = 0;
+
+  function reportMessage(framePayload: Buffer): boolean {
+    let msg: unknown;
+    try {
+      msg = JSON.parse(framePayload.toString("utf-8"));
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      onError(new Error(`Failed to parse intercom message: ${message}`, { cause: error }));
+      return false;
+    }
+
+    try {
+      onMessage(msg);
+      return true;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      onError(new Error(`Failed to handle intercom message: ${message}`, { cause: error }));
+      return false;
+    }
+  }
 
   return (data: Buffer) => {
-    buffer = Buffer.concat([buffer, data]);
+    let offset = 0;
 
-    while (buffer.length >= 4) {
-      const length = buffer.readUInt32BE(0);
-      
-      if (buffer.length < 4 + length) {
-        break;
+    while (offset < data.length) {
+      if (headerBytes < 4) {
+        const bytes = Math.min(4 - headerBytes, data.length - offset);
+        data.copy(header, headerBytes, offset, offset + bytes);
+        headerBytes += bytes;
+        offset += bytes;
+        if (headerBytes < 4) {
+          return;
+        }
+
+        payloadLength = header.readUInt32BE(0);
+        if (payloadLength > maxFrameBytes) {
+          headerBytes = 0;
+          onError(new Error(`Intercom frame length ${payloadLength} exceeds maximum ${maxFrameBytes} bytes`));
+          return;
+        }
+      }
+
+      // Fast path: the whole payload is already in this chunk, so parse it
+      // in place without copying into a reassembly buffer.
+      if (payloadBytes === 0 && data.length - offset >= payloadLength) {
+        const framePayload = data.subarray(offset, offset + payloadLength);
+        offset += payloadLength;
+        headerBytes = 0;
+        payload = null;
+        payloadLength = 0;
+        if (!reportMessage(framePayload)) {
+          return;
+        }
+        continue;
       }
 
-      const payload = buffer.subarray(4, 4 + length);
-      buffer = buffer.subarray(4 + length);
+      // A buffer allocated for a previous frame (e.g. when a chunk ended
+      // exactly on a header boundary) must not be reused for a frame of a
+      // different size, so the reassembly buffer is size-checked, not just
+      // presence-checked.
+      if (payload === null || payload.length !== payloadLength) {
+        payload = Buffer.allocUnsafe(payloadLength);
+      }
+      const bytes = Math.min(payloadLength - payloadBytes, data.length - offset);
+      data.copy(payload, payloadBytes, offset, offset + bytes);
+      payloadBytes += bytes;
+      offset += bytes;
 
-      let msg: unknown;
-      try {
-        msg = JSON.parse(payload.toString("utf-8"));
-      } catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        onError(new Error(`Failed to parse intercom message: ${message}`, { cause: error }));
+      if (payloadBytes < payloadLength) {
         return;
       }
 
-      try {
-        onMessage(msg);
-      } catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        onError(new Error(`Failed to handle intercom message: ${message}`, { cause: error }));
+      const framePayload = payload;
+      headerBytes = 0;
+      payload = null;
+      payloadBytes = 0;
+      payloadLength = 0;
+      if (!reportMessage(framePayload)) {
         return;
       }
     }

package/dist/extensions/pi-intercom/broker/paths.test.ts

@@ -0,0 +1,153 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { chmodSync, mkdtempSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { getAgentDir } from "@selesai/code";
+import {
+  ensureIntercomRuntimeDir,
+  getAgentDirPath,
+  getBrokerConnectTarget,
+  getBrokerListenTarget,
+  getBrokerPortFilePath,
+  getBrokerSocketPath,
+  getIntercomDirPath,
+  INTERCOM_DIR_MODE,
+  INTERCOM_RUNTIME_FILE_MODE,
+  INTERCOM_TCP_HOST,
+  restrictIntercomRuntimeFile,
+  shouldUseWindowsTcpTransport,
+} from "./paths.ts";
+
+test("getAgentDirPath defaults to Selesai's configured agent directory", () => {
+  assert.equal(getAgentDirPath({}), getAgentDir());
+});
+
+test("getAgentDirPath honors SELESAI_CODING_AGENT_DIR", () => {
+  assert.equal(getAgentDirPath({ SELESAI_CODING_AGENT_DIR: "/tmp/selesai-agent" }), "/tmp/selesai-agent");
+});
+
+test("getAgentDirPath resolves relative SELESAI_CODING_AGENT_DIR values from the caller cwd", () => {
+  const cwd = join(tmpdir(), "workspace", "project");
+  assert.equal(
+    getAgentDirPath({ SELESAI_CODING_AGENT_DIR: "relative-agent" }, cwd),
+    join(cwd, "relative-agent"),
+  );
+});
+
+test("getIntercomDirPath points at the intercom runtime directory under the agent dir", () => {
+  assert.equal(getIntercomDirPath("/tmp/selesai-agent"), join("/tmp/selesai-agent", "intercom"));
+});
+
+test("getBrokerSocketPath uses named pipe on Windows", () => {
+  const pipePath = getBrokerSocketPath("win32", "C:/Users/rcroh/.selesai/agent");
+  assert.match(pipePath, /^\\\\\.\\pipe\\pi-intercom-/);
+  assert.doesNotMatch(pipePath, /broker\.sock$/);
+});
+
+test("getBrokerSocketPath uses broker.sock under SELESAI_CODING_AGENT_DIR on non-Windows", () => {
+  const socketPath = getBrokerSocketPath("linux", "/tmp/selesai-agent");
+  assert.equal(socketPath, join("/tmp/selesai-agent", "intercom", "broker.sock"));
+});
+
+test("Windows TCP transport is opt-in", () => {
+  assert.equal(shouldUseWindowsTcpTransport("win32", {}), false);
+  assert.equal(shouldUseWindowsTcpTransport("win32", { PI_INTERCOM_TRANSPORT: "tcp" }), true);
+  assert.equal(shouldUseWindowsTcpTransport("win32", { PI_INTERCOM_TCP: "1" }), true);
+  assert.equal(shouldUseWindowsTcpTransport("linux", { PI_INTERCOM_TRANSPORT: "tcp" }), false);
+});
+
+test("getBrokerListenTarget uses dynamic localhost TCP only when opted in on Windows", () => {
+  assert.deepEqual(getBrokerListenTarget("win32", { PI_INTERCOM_TRANSPORT: "tcp" }), {
+    transport: "tcp",
+    host: INTERCOM_TCP_HOST,
+    port: 0,
+  });
+  assert.equal(getBrokerListenTarget("win32", {}), getBrokerSocketPath("win32", getAgentDirPath({})));
+});
+
+test("getBrokerConnectTarget reads opt-in Windows TCP endpoint from intercom state", () => {
+  const root = mkdtempSync(join(tmpdir(), "pi-intercom-paths-"));
+  const intercomDir = join(root, "intercom");
+
+  try {
+    ensureIntercomRuntimeDir(intercomDir, "win32");
+    writeFileSync(getBrokerPortFilePath(intercomDir), JSON.stringify({
+      transport: "tcp",
+      host: "127.0.0.1",
+      port: 41234,
+      stateId: "state-1",
+    }));
+    assert.deepEqual(getBrokerConnectTarget("win32", { PI_INTERCOM_TRANSPORT: "tcp" }, intercomDir), {
+      transport: "tcp",
+      host: "127.0.0.1",
+      port: 41234,
+      stateId: "state-1",
+    });
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("getBrokerConnectTarget rejects non-local TCP endpoint hosts", () => {
+  const root = mkdtempSync(join(tmpdir(), "pi-intercom-paths-"));
+  const intercomDir = join(root, "intercom");
+
+  try {
+    ensureIntercomRuntimeDir(intercomDir, "win32");
+    writeFileSync(getBrokerPortFilePath(intercomDir), JSON.stringify({
+      transport: "tcp",
+      host: "10.0.0.5",
+      port: 41234,
+      stateId: "state-1",
+    }));
+    assert.throws(
+      () => getBrokerConnectTarget("win32", { PI_INTERCOM_TRANSPORT: "tcp" }, intercomDir),
+      /Invalid intercom TCP endpoint/,
+    );
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("ensureIntercomRuntimeDir creates and repairs restrictive Unix directory permissions", { skip: process.platform === "win32" }, () => {
+  const root = mkdtempSync(join(tmpdir(), "pi-intercom-paths-"));
+  const intercomDir = join(root, "intercom");
+
+  try {
+    ensureIntercomRuntimeDir(intercomDir, "linux");
+    assert.equal(statSync(intercomDir).mode & 0o777, INTERCOM_DIR_MODE);
+
+    chmodSync(intercomDir, 0o755);
+    ensureIntercomRuntimeDir(intercomDir, "linux");
+    assert.equal(statSync(intercomDir).mode & 0o777, INTERCOM_DIR_MODE);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("restrictIntercomRuntimeFile applies restrictive Unix file permissions", { skip: process.platform === "win32" }, () => {
+  const root = mkdtempSync(join(tmpdir(), "pi-intercom-paths-"));
+  const filePath = join(root, "broker.pid");
+
+  try {
+    writeFileSync(filePath, "123", { mode: 0o644 });
+    restrictIntercomRuntimeFile(filePath, "linux");
+    assert.equal(statSync(filePath).mode & 0o777, INTERCOM_RUNTIME_FILE_MODE);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("runtime permission helpers skip chmod on Windows paths", () => {
+  const root = mkdtempSync(join(tmpdir(), "pi-intercom-paths-"));
+  const filePath = join(root, "broker.pid");
+
+  try {
+    ensureIntercomRuntimeDir(root, "win32");
+    writeFileSync(filePath, "123");
+    assert.doesNotThrow(() => restrictIntercomRuntimeFile(filePath, "win32"));
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});

package/dist/extensions/pi-intercom/broker/paths.ts

@@ -1,6 +1,22 @@
-import { join } from "path";
+import { chmodSync, mkdirSync, readFileSync } from "fs";
+import { isAbsolute, join, resolve } from "path";
 import { getAgentDir } from "@selesai/code";
 
+export const INTERCOM_DIR_MODE = 0o700;
+export const INTERCOM_RUNTIME_FILE_MODE = 0o600;
+export const INTERCOM_TCP_HOST = "127.0.0.1";
+export const INTERCOM_PROTOCOL_NAME = "pi-intercom";
+export const INTERCOM_PROTOCOL_VERSION = 1;
+
+export interface BrokerTcpEndpoint {
+  transport: "tcp";
+  host: string;
+  port: number;
+  stateId?: string;
+}
+
+export type BrokerConnectTarget = string | BrokerTcpEndpoint;
+
 function sanitizePipeSegment(value: string): string {
   return value
     .replace(/[^a-zA-Z0-9]+/g, "-")
@@ -8,18 +24,111 @@ function sanitizePipeSegment(value: string): string {
     .toLowerCase() || "default";
 }
 
-/** selesai config dir (~/.selesai/agent on the selesai fork, ~/.pi/agent upstream). */
-export function getIntercomDir(): string {
-  return join(getAgentDir(), "intercom");
+export function getAgentDirPath(
+  env: NodeJS.ProcessEnv = process.env,
+  cwd: string = process.cwd(),
+): string {
+  const configured = env.SELESAI_CODING_AGENT_DIR?.trim();
+  if (!configured) {
+    return getAgentDir();
+  }
+
+  return isAbsolute(configured) ? configured : resolve(cwd, configured);
+}
+
+export function getIntercomDirPath(agentDir: string = getAgentDirPath()): string {
+  return join(agentDir, "intercom");
+}
+
+export function shouldUseWindowsTcpTransport(
+  platform: NodeJS.Platform = process.platform,
+  env: NodeJS.ProcessEnv = process.env,
+): boolean {
+  if (platform !== "win32") {
+    return false;
+  }
+
+  const transport = env.PI_INTERCOM_TRANSPORT?.trim().toLowerCase();
+  if (transport === "tcp") {
+    return true;
+  }
+
+  const legacyOptIn = env.PI_INTERCOM_TCP?.trim().toLowerCase();
+  return legacyOptIn === "1" || legacyOptIn === "true";
+}
+
+export function getBrokerPortFilePath(intercomDir: string = getIntercomDirPath()): string {
+  return join(intercomDir, "broker.port.json");
 }
 
 export function getBrokerSocketPath(
   platform: NodeJS.Platform = process.platform,
-  intercomDir: string = getIntercomDir(),
+  agentDir: string = getAgentDirPath(),
 ): string {
   if (platform === "win32") {
-    return `\\\\.\\pipe\\pi-intercom-${sanitizePipeSegment(intercomDir)}`;
+    return `\\\\.\\pipe\\pi-intercom-${sanitizePipeSegment(agentDir)}`;
   }
 
-  return join(intercomDir, "broker.sock");
-}
+  return join(getIntercomDirPath(agentDir), "broker.sock");
+}
+
+export function getBrokerConnectTarget(
+  platform: NodeJS.Platform = process.platform,
+  env: NodeJS.ProcessEnv = process.env,
+  intercomDir: string = getIntercomDirPath(getAgentDirPath(env)),
+): BrokerConnectTarget {
+  if (shouldUseWindowsTcpTransport(platform, env)) {
+    const endpointFile = getBrokerPortFilePath(intercomDir);
+    const raw = readFileSync(endpointFile, "utf-8");
+    const parsed: unknown = JSON.parse(raw);
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+      throw new Error(`Invalid intercom TCP endpoint at ${endpointFile}: expected a JSON object`);
+    }
+    const endpoint = parsed as Record<string, unknown>;
+    if (
+      endpoint.transport !== "tcp"
+      || endpoint.host !== INTERCOM_TCP_HOST
+      || typeof endpoint.port !== "number"
+      || !Number.isSafeInteger(endpoint.port)
+      || endpoint.port <= 0
+      || endpoint.port > 65535
+      || typeof endpoint.stateId !== "string"
+      || endpoint.stateId.length === 0
+    ) {
+      throw new Error(`Invalid intercom TCP endpoint at ${endpointFile}`);
+    }
+    return { transport: "tcp", host: endpoint.host, port: endpoint.port, stateId: endpoint.stateId };
+  }
+
+  return getBrokerSocketPath(platform, getAgentDirPath(env));
+}
+
+export function getBrokerListenTarget(
+  platform: NodeJS.Platform = process.platform,
+  env: NodeJS.ProcessEnv = process.env,
+): BrokerConnectTarget {
+  if (shouldUseWindowsTcpTransport(platform, env)) {
+    return { transport: "tcp", host: INTERCOM_TCP_HOST, port: 0 };
+  }
+
+  return getBrokerSocketPath(platform, getAgentDirPath(env));
+}
+
+export function ensureIntercomRuntimeDir(
+  intercomDir: string = getIntercomDirPath(),
+  platform: NodeJS.Platform = process.platform,
+): void {
+  mkdirSync(intercomDir, { recursive: true, mode: INTERCOM_DIR_MODE });
+  if (platform !== "win32") {
+    chmodSync(intercomDir, INTERCOM_DIR_MODE);
+  }
+}
+
+export function restrictIntercomRuntimeFile(
+  filePath: string,
+  platform: NodeJS.Platform = process.platform,
+): void {
+  if (platform !== "win32") {
+    chmodSync(filePath, INTERCOM_RUNTIME_FILE_MODE);
+  }
+}

package/dist/extensions/pi-intercom/broker/runtime-claim.test.ts

@@ -0,0 +1,34 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import path from "node:path";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { assertNoLiveBroker } from "./runtime-claim.ts";
+
+test("broker startup refuses to replace a live broker PID", () => {
+  const directory = mkdtempSync(path.join(tmpdir(), "pi-intercom-runtime-"));
+  const pidPath = path.join(directory, "broker.pid");
+  try {
+    writeFileSync(pidPath, `${process.pid}\n`);
+    assert.throws(
+      () => assertNoLiveBroker(pidPath),
+      new RegExp(`Refusing to replace live intercom broker process ${process.pid}`),
+    );
+  } finally {
+    rmSync(directory, { recursive: true, force: true });
+  }
+});
+
+test("broker startup tolerates absent, invalid, and stale PID files", () => {
+  const directory = mkdtempSync(path.join(tmpdir(), "pi-intercom-runtime-"));
+  const pidPath = path.join(directory, "broker.pid");
+  try {
+    assert.doesNotThrow(() => assertNoLiveBroker(pidPath));
+    writeFileSync(pidPath, "invalid\n");
+    assert.doesNotThrow(() => assertNoLiveBroker(pidPath));
+    writeFileSync(pidPath, "2147483647\n");
+    assert.doesNotThrow(() => assertNoLiveBroker(pidPath));
+  } finally {
+    rmSync(directory, { recursive: true, force: true });
+  }
+});

package/dist/extensions/pi-intercom/broker/runtime-claim.ts

@@ -0,0 +1,21 @@
+import { existsSync, readFileSync } from "node:fs";
+
+export function assertNoLiveBroker(pidPath: string): void {
+  if (!existsSync(pidPath)) return;
+
+  let pid: number;
+  try {
+    pid = Number.parseInt(readFileSync(pidPath, "utf8").trim(), 10);
+  } catch {
+    return;
+  }
+  if (!Number.isSafeInteger(pid) || pid <= 0) return;
+
+  try {
+    process.kill(pid, 0);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ESRCH") return;
+    throw error;
+  }
+  throw new Error(`Refusing to replace live intercom broker process ${pid}`);
+}

package/dist/extensions/pi-intercom/broker/spawn.test.ts

@@ -1,31 +1,168 @@
-import { createRequire } from "module";
-import { describe, expect, it } from "vitest";
-import { getBrokerLaunchSpec, getWindowsBrokerCommandLine } from "./spawn.ts";
+import test from "node:test";
+import assert from "node:assert/strict";
+import path from "node:path";
+import { existsSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import {
+  getBrokerLaunchSpec,
+  getBrokerSpawnOptions,
+  getTsxCliPath,
+  getWindowsHiddenLauncherScript,
+  getWindowsBrokerCommandLine,
+  getWindowsHiddenLauncherPath,
+  isBrokerHealthOkMessage,
+} from "./spawn.ts";
 
-const require = createRequire(import.meta.url);
-const brokerPath = "C:\\broker dir\\broker.ts";
-const extensionDir = "C:\\published-package\\dist\\extensions\\pi-intercom";
-const nodePath = "C:\\Program Files\\nodejs\\node.exe";
+test("getTsxCliPath resolves tsx cli via module resolution", () => {
+  const cliPath = getTsxCliPath("C:/repo");
+  // getTsxCliPath resolves the tsx package main entry and locates cli.mjs next
+  // to it, so the path reflects the real install location (bundled under
+  // extensionDir or hoisted by npm) rather than a hardcoded relative path.
+  assert.equal(path.basename(cliPath), "cli.mjs");
+  assert.equal(path.basename(path.dirname(cliPath)), "dist");
+  assert.equal(path.basename(path.dirname(path.dirname(cliPath))), "tsx");
+});
+
+test("getWindowsHiddenLauncherPath points at the broker launcher script", () => {
+  const launcherPath = getWindowsHiddenLauncherPath("C:/tmp/intercom");
+  assert.equal(launcherPath, path.join("C:/tmp/intercom", "broker-launch.vbs"));
+});
+
+test("getWindowsBrokerCommandLine wraps node, resolved tsx cli, and broker path", () => {
+  const commandLine = getWindowsBrokerCommandLine(
+    "C:/repo/broker.ts",
+    "C:/repo",
+    "C:/Program Files/nodejs/node.exe",
+  );
+  const expectedTsxPath = getTsxCliPath("C:/repo");
+  assert.equal(
+    commandLine,
+    `"C:/Program Files/nodejs/node.exe" "${expectedTsxPath}" "C:/repo/broker.ts"`,
+  );
+});
+
+test("getWindowsHiddenLauncherScript runs the broker command without showing a console", () => {
+  const script = getWindowsHiddenLauncherScript('"C:/Program Files/nodejs/node.exe" "C:/repo/node_modules/tsx/dist/cli.mjs" "C:/repo/broker.ts"');
+  assert.match(script, /WshShell\.Run/);
+  assert.match(script, /, 0, False/);
+});
 
-describe("intercom broker launch", () => {
-  it("resolves default Windows tsx launcher from installed dependencies", () => {
-    const tsxCliPath = require.resolve("tsx/cli");
+test("getBrokerLaunchSpec uses wscript launcher on Windows without writing files", () => {
+  const intercomDir = mkdtempSync(path.join(tmpdir(), "pi-intercom-"));
 
-    expect(getWindowsBrokerCommandLine(brokerPath, extensionDir, nodePath)).toBe(
-      `"${nodePath}" "${tsxCliPath}" "${brokerPath}"`,
+  try {
+    const spec = getBrokerLaunchSpec(
+      "C:/repo/broker.ts",
+      "npx",
+      ["--no-install", "tsx"],
+      "C:/repo",
+      "win32",
+      intercomDir,
+      "C:/Program Files/nodejs/node.exe",
     );
-    expect(getWindowsBrokerCommandLine(brokerPath, extensionDir, nodePath)).not.toContain(extensionDir);
-  });
+    assert.equal(spec.command, "wscript.exe");
+    assert.deepEqual(spec.args, [path.join(intercomDir, "broker-launch.vbs")]);
+    assert.equal(spec.kind, "windows-launcher");
+    const expectedTsxPath = getTsxCliPath("C:/repo");
+    assert.equal(spec.launcherCommandLine, `"C:/Program Files/nodejs/node.exe" "${expectedTsxPath}" "C:/repo/broker.ts"`);
+    assert.equal(existsSync(path.join(intercomDir, "broker-launch.vbs")), false);
+  } finally {
+    rmSync(intercomDir, { recursive: true, force: true });
+  }
+});
+
+test("getBrokerLaunchSpec falls back to PATH node for a standalone Selesai executable on Windows", () => {
+  const intercomDir = mkdtempSync(path.join(tmpdir(), "pi-intercom-"));
 
-  it("preserves custom broker commands on Windows and other platforms", () => {
-    expect(getWindowsBrokerCommandLine(brokerPath, extensionDir, nodePath, "broker-command", ["--port", "1234"])).toBe(
-      `"broker-command" "--port" "1234" "${brokerPath}"`,
+  try {
+    const spec = getBrokerLaunchSpec(
+      "C:/repo/broker.ts",
+      "npx",
+      ["--no-install", "tsx"],
+      "C:/repo",
+      "win32",
+      intercomDir,
+      "C:/Program Files/Selesai/selesai.exe",
     );
+    assert.equal(spec.kind, "windows-launcher");
+    assert.equal(spec.launcherCommandLine, `"node" "${getTsxCliPath("C:/repo")}" "C:/repo/broker.ts"`);
+  } finally {
+    rmSync(intercomDir, { recursive: true, force: true });
+  }
+});
+
+test("getBrokerLaunchSpec uses custom broker command on Windows", () => {
+  const intercomDir = mkdtempSync(path.join(tmpdir(), "pi-intercom-"));
+
+  try {
+    const spec = getBrokerLaunchSpec("C:/repo/broker.ts", "bun", ["--smol"], "C:/repo", "win32", intercomDir, "C:/Program Files/nodejs/node.exe");
+    assert.equal(spec.command, "wscript.exe");
+    assert.equal(spec.kind, "windows-launcher");
+    assert.equal(spec.launcherCommandLine, `"bun" "--smol" "C:/repo/broker.ts"`);
+  } finally {
+    rmSync(intercomDir, { recursive: true, force: true });
+  }
+});
+
+test("getBrokerLaunchSpec uses node + resolved tsx for the default non-Windows launch", () => {
+  const spec = getBrokerLaunchSpec("C:/repo/broker.ts", "npx", ["--no-install", "tsx"], "C:/repo", "linux", "/tmp/intercom", "/usr/bin/node");
+  assert.equal(spec.command, "/usr/bin/node");
+  assert.deepEqual(spec.args, [
+    getTsxCliPath("C:/repo"),
+    "C:/repo/broker.ts",
+  ]);
+  assert.equal(spec.kind, "direct");
+});
+
+test("getBrokerLaunchSpec falls back to PATH node for a standalone Selesai executable on non-Windows", () => {
+  const spec = getBrokerLaunchSpec(
+    "/repo/broker.ts",
+    "npx",
+    ["--no-install", "tsx"],
+    "/repo",
+    "darwin",
+    "/tmp/intercom",
+    "/Applications/Selesai.app/Contents/MacOS/selesai",
+  );
+  assert.equal(spec.command, "node");
+  assert.deepEqual(spec.args, [
+    getTsxCliPath("/repo"),
+    "/repo/broker.ts",
+  ]);
+  assert.equal(spec.kind, "direct");
+});
+
+test("getBrokerLaunchSpec uses custom broker command on non-Windows", () => {
+  const spec = getBrokerLaunchSpec("/repo/broker.ts", "bun", [], "/repo", "linux", "/tmp/intercom", "/usr/bin/node");
+  assert.equal(spec.command, "bun");
+  assert.deepEqual(spec.args, ["/repo/broker.ts"]);
+  assert.equal(spec.kind, "direct");
+});
+
+test("getBrokerSpawnOptions hides the broker console window on Windows", () => {
+  const options = getBrokerSpawnOptions("C:/repo");
+  assert.equal(options.windowsHide, true);
+  assert.equal(options.detached, true);
+  assert.equal(options.stdio, "ignore");
+  assert.equal(options.cwd, "C:/repo");
+});
+
+test("getBrokerSpawnOptions keeps portable defaults on non-Windows platforms", () => {
+  const options = getBrokerSpawnOptions("/repo");
+  assert.equal(options.windowsHide, true);
+  assert.equal(options.detached, true);
+  assert.equal(options.stdio, "ignore");
+  assert.equal(options.cwd, "/repo");
+});
+
+test("getBrokerSpawnOptions passes an absolute SELESAI_CODING_AGENT_DIR to the broker", () => {
+  const options = getBrokerSpawnOptions("/repo", { SELESAI_CODING_AGENT_DIR: "relative-agent" });
+  assert.equal(options.env.SELESAI_CODING_AGENT_DIR, path.resolve("relative-agent"));
+});
 
-    expect(getBrokerLaunchSpec(brokerPath, "broker-command", ["--port", "1234"], extensionDir, "linux")).toEqual({
-      kind: "direct",
-      command: "broker-command",
-      args: ["--port", "1234", brokerPath],
-    });
-  });
+test("isBrokerHealthOkMessage requires the intercom protocol marker", () => {
+  assert.equal(isBrokerHealthOkMessage({ type: "health_ok", requestId: "req-1", protocol: "pi-intercom", version: 1 }, "req-1"), true);
+  assert.equal(isBrokerHealthOkMessage({ type: "health_ok", requestId: "req-1" }, "req-1"), false);
+  assert.equal(isBrokerHealthOkMessage({ type: "health_ok", requestId: "req-2", protocol: "pi-intercom", version: 1 }, "req-1"), false);
+  assert.equal(isBrokerHealthOkMessage("ok", "req-1"), false);
 });