claude-code-swarm 0.3.9 → 0.3.11

package/.claude-plugin/marketplace.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-swarm",
-  "version": "0.3.9",
+  "version": "0.3.11",
   "description": "Launch Claude Code with swarmkit capabilities, including team orchestration, MAP observability, and session tracking.",
   "owner": {
     "name": "alexngai"

package/.claude-plugin/mcp-launcher.mjs

@@ -0,0 +1,176 @@
+#!/usr/bin/env node
+/**
+ * Unified MCP server launcher for claude-code-swarm plugin.
+ *
+ * Usage: node mcp-launcher.mjs <server>
+ *   server: opentasks | minimem | agent-inbox
+ *
+ * Reads .swarm/claude-swarm/config.json once, checks enablement,
+ * resolves CLI args, and exec's the real server or falls back to noop.
+ */
+
+import { readFileSync, existsSync, statSync, readdirSync } from 'node:fs';
+import { execFileSync, execSync } from 'node:child_process';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createInterface } from 'node:readline';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const server = process.argv[2];
+
+if (!server) {
+  process.stderr.write('Usage: mcp-launcher.mjs <opentasks|minimem|agent-inbox>\n');
+  process.exit(1);
+}
+
+// --- Config ---
+
+function readConfig() {
+  const configPath = '.swarm/claude-swarm/config.json';
+  try {
+    return JSON.parse(readFileSync(configPath, 'utf-8'));
+  } catch {
+    return {};
+  }
+}
+
+function envBool(key) {
+  const v = (process.env[key] || '').toLowerCase();
+  return ['true', '1', 'yes'].includes(v);
+}
+
+function env(key) {
+  return process.env[key] || '';
+}
+
+const config = readConfig();
+
+// --- Noop ---
+
+function runNoop() {
+  const rl = createInterface({ input: process.stdin, crlfDelay: Infinity });
+  rl.on('line', (line) => {
+    line = line.trim();
+    if (!line) return;
+    let msg;
+    try { msg = JSON.parse(line); } catch { return; }
+    const respond = (result) => process.stdout.write(JSON.stringify({ jsonrpc: '2.0', id: msg.id, result }) + '\n');
+    if (msg.method === 'initialize') {
+      respond({ protocolVersion: '2024-11-05', capabilities: { tools: {} }, serverInfo: { name: 'noop-mcp', version: '1.0.0' } });
+    } else if (msg.method === 'tools/list') {
+      respond({ tools: [] });
+    } else if (msg.method === 'resources/list') {
+      respond({ resources: [] });
+    } else if (msg.method === 'prompts/list') {
+      respond({ prompts: [] });
+    } else if (msg.id !== undefined && !msg.method?.startsWith('notifications/')) {
+      process.stdout.write(JSON.stringify({ jsonrpc: '2.0', id: msg.id, error: { code: -32601, message: 'Method not found' } }) + '\n');
+    }
+  });
+  rl.on('close', () => process.exit(0));
+}
+
+// --- CLI resolution ---
+
+function which(cmd) {
+  try {
+    return execFileSync('which', [cmd], { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+  } catch {
+    return null;
+  }
+}
+
+function findSocket(paths) {
+  for (const p of paths) {
+    try {
+      if (existsSync(p) && statSync(p).isSocket?.()) return p;
+    } catch {}
+  }
+  return null;
+}
+
+// --- Server definitions ---
+
+const servers = {
+  opentasks: {
+    enabled: () => envBool('SWARM_OPENTASKS_ENABLED') || config.opentasks?.enabled === true,
+    launch: () => {
+      const scope = env('SWARM_OPENTASKS_SCOPE') || config.opentasks?.scope || 'tasks';
+      const socket = findSocket([
+        '.swarm/opentasks/daemon.sock',
+        '.opentasks/daemon.sock',
+        '.git/opentasks/daemon.sock',
+      ]);
+      const args = ['mcp', '--scope', scope];
+      if (socket) args.push('--socket', socket);
+      return { cmd: 'opentasks', args };
+    },
+  },
+
+  minimem: {
+    enabled: () => envBool('SWARM_MINIMEM_ENABLED') || config.minimem?.enabled === true,
+    launch: () => {
+      const provider = env('SWARM_MINIMEM_PROVIDER') || config.minimem?.provider || 'auto';
+      let dir = env('SWARM_MINIMEM_DIR') || config.minimem?.dir || '';
+      if (!dir) {
+        dir = existsSync('.swarm/minimem') ? '.swarm/minimem' : '.';
+      }
+      const useGlobal = envBool('SWARM_MINIMEM_GLOBAL') || config.minimem?.global === true;
+      const args = ['mcp', '--dir', dir, '--provider', provider];
+      if (useGlobal) args.push('--global');
+      return { cmd: 'minimem', args };
+    },
+  },
+
+  'agent-inbox': {
+    enabled: () => envBool('SWARM_INBOX_ENABLED') || config.inbox?.enabled === true,
+    launch: () => {
+      const scope = env('SWARM_INBOX_SCOPE') || config.inbox?.scope || config.map?.scope || 'default';
+      process.env.INBOX_SCOPE = scope;
+
+      // Discover sidecar inbox socket for proxy mode
+      let inboxSock = findSocket(['.swarm/claude-swarm/tmp/map/inbox.sock']);
+      if (!inboxSock) {
+        const sessDir = '.swarm/claude-swarm/tmp/map/sessions';
+        try {
+          if (existsSync(sessDir)) {
+            for (const d of readdirSync(sessDir)) {
+              const sock = join(sessDir, d, 'inbox.sock');
+              if (existsSync(sock)) { inboxSock = sock; break; }
+            }
+          }
+        } catch {}
+      }
+      if (inboxSock) {
+        process.env.INBOX_SOCKET_PATH = inboxSock;
+      }
+
+      return { cmd: 'agent-inbox', args: ['mcp'] };
+    },
+  },
+};
+
+// --- Main ---
+
+const def = servers[server];
+if (!def) {
+  process.stderr.write(`Unknown server: ${server}\n`);
+  process.exit(1);
+}
+
+if (!def.enabled()) {
+  runNoop();
+} else {
+  const { cmd, args } = def.launch();
+  if (which(cmd)) {
+    // Replace this process with the real server
+    const { execFileSync: _ , ...rest } = await import('node:child_process');
+    const child = (await import('node:child_process')).spawn(cmd, args, {
+      stdio: 'inherit',
+    });
+    child.on('exit', (code) => process.exit(code ?? 0));
+  } else {
+    process.stderr.write(`[${server}-mcp] ${cmd} CLI not found\n`);
+    runNoop();
+  }
+}

package/.claude-plugin/plugin.json

@@ -1,26 +1,35 @@
 {
   "name": "claude-code-swarm",
   "description": "Spin up Claude Code agent teams from openteams YAML topologies with optional MAP (Multi-Agent Protocol) observability and coordination. Provides hooks for session lifecycle, agent spawn/complete tracking, and a /swarm skill to launch team configurations.",
-  "version": "0.3.9",
+  "version": "0.3.11",
   "author": {
     "name": "alexngai"
   },
   "mcpServers": {
     "opentasks": {
-      "command": "${CLAUDE_PLUGIN_ROOT}/.claude-plugin/run-opentasks-mcp.sh",
-      "args": [],
+      "command": "node",
+      "args": [
+        "${CLAUDE_PLUGIN_ROOT}/.claude-plugin/mcp-launcher.mjs",
+        "opentasks"
+      ],
       "env": {
         "OPENTASKS_WORKING_DIR": "${workspaceFolder}"
       }
     },
     "agent-inbox": {
-      "command": "${CLAUDE_PLUGIN_ROOT}/.claude-plugin/run-agent-inbox-mcp.sh",
-      "args": [],
+      "command": "node",
+      "args": [
+        "${CLAUDE_PLUGIN_ROOT}/.claude-plugin/mcp-launcher.mjs",
+        "agent-inbox"
+      ],
       "env": {}
     },
     "minimem": {
-      "command": "${CLAUDE_PLUGIN_ROOT}/.claude-plugin/run-minimem-mcp.sh",
-      "args": [],
+      "command": "node",
+      "args": [
+        "${CLAUDE_PLUGIN_ROOT}/.claude-plugin/mcp-launcher.mjs",
+        "minimem"
+      ],
       "env": {
         "MINIMEM_WORKING_DIR": "${workspaceFolder}"
       }

package/CLAUDE.md

@@ -461,6 +461,16 @@ Runtime:
 - **Claude Code agent teams** — enabled via `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` in settings.json
 
 ## Development notes
+
+### Debugging with logs
+When logging is enabled, per-session log files (JSON Lines format) are written to:
+- **Default location**: `~/.claude-swarm/tmp/logs/<timestamp>_<sessionId>.log`
+- **Custom location**: set `log.dir` in config or `SWARM_LOG_DIR` env var
+- **Explicit file**: set `log.file` in config or `SWARM_LOG_FILE` env var
+
+To enable verbose logging: `SWARM_LOG_LEVEL=debug claude` (or `info` for lifecycle events only). The default level is `warn`. Each session may produce multiple log files (e.g., one from bootstrap, one from the sidecar) sharing the same session ID in the filename.
+
+### General notes
 - Templates are provided by the openteams package (installed via swarmkit), not bundled with the plugin
 - `.swarm/` directory is managed by swarmkit for ecosystem packages (openteams, sessionlog) via `initProjectPackage()`
 - Plugin-specific state lives under `.swarm/claude-swarm/` (config, `.gitignore` ignoring `tmp/`). Runtime artifacts go in `.swarm/claude-swarm/tmp/` (per-template caches, MAP files)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-swarm",
-  "version": "0.3.9",
+  "version": "0.3.11",
   "description": "Claude Code plugin for launching agent teams from openteams topologies with MAP observability",
   "type": "module",
   "exports": {
@@ -45,9 +45,6 @@
     "test:e2e:tier4": "vitest run --config e2e/vitest.config.e2e.mjs -t tier4",
     "test:e2e:tier5": "vitest run --config e2e/vitest.config.e2e.mjs -t tier5",
     "test:e2e:tier7": "vitest run --config e2e/vitest.config.e2e.mjs -t tier7",
-    "dev:link": "node scripts/dev-link.mjs link",
-    "dev:unlink": "node scripts/dev-link.mjs unlink",
-    "dev:status": "node scripts/dev-link.mjs status",
     "version:patch": "npm version patch --no-git-tag-version && node scripts/sync-version.mjs",
     "version:minor": "npm version minor --no-git-tag-version && node scripts/sync-version.mjs",
     "version:major": "npm version major --no-git-tag-version && node scripts/sync-version.mjs"
@@ -56,7 +53,6 @@
     "node": ">=18.0.0"
   },
   "devDependencies": {
-    "@multi-agent-protocol/sdk": "^0.1.4",
     "agent-inbox": "^0.1.9",
     "minimem": "^0.1.0",
     "opentasks": "^0.0.6",

package/scripts/map-sidecar.mjs

@@ -26,7 +26,7 @@ import { createMeshPeer, createMeshInbox } from "../src/mesh-connection.mjs";
 import { createSocketServer, createCommandHandler } from "../src/sidecar-server.mjs";
 import { readConfig } from "../src/config.mjs";
 import { createLogger, init as initLog } from "../src/log.mjs";
-import { configureNodePath } from "../src/swarmkit-resolver.mjs";
+import { configureNodePath, resolvePackage } from "../src/swarmkit-resolver.mjs";
 
 const log = createLogger("sidecar");
 
@@ -329,7 +329,9 @@ async function startLegacyAgentInbox(mapConnection) {
   if (!INBOX_CONFIG) return null;
 
   try {
-    const { createAgentInbox } = await import("agent-inbox");
+    const agentInboxMod = await resolvePackage("agent-inbox");
+    if (!agentInboxMod) throw new Error("agent-inbox not available");
+    const { createAgentInbox } = agentInboxMod;
 
     const peers = INBOX_CONFIG.federation?.peers || [];
     const federationConfig = peers.length > 0

package/src/__tests__/bootstrap.test.mjs

@@ -16,6 +16,10 @@ vi.mock("../sidecar-client.mjs", () => ({
   sendToInbox: vi.fn().mockResolvedValue(undefined),
 }));
 
+vi.mock("../map-events.mjs", () => ({
+  sendCommand: vi.fn().mockResolvedValue(undefined),
+}));
+
 vi.mock("../sessionlog.mjs", () => ({
   checkSessionlogStatus: vi.fn(() => "not installed"),
   syncSessionlog: vi.fn().mockResolvedValue(undefined),
@@ -81,6 +85,7 @@ vi.mock("../swarmkit-resolver.mjs", () => ({
 const { bootstrap, backgroundInit } = await import("../bootstrap.mjs");
 const { readConfig } = await import("../config.mjs");
 const { killSidecar, startSidecar } = await import("../sidecar-client.mjs");
+const { sendCommand } = await import("../map-events.mjs");
 const { checkSessionlogStatus, syncSessionlog, annotateSwarmSession } = await import("../sessionlog.mjs");
 const { pluginDir, ensureOpentasksDir, ensureSessionDir, listSessionDirs } = await import("../paths.mjs");
 const { findSocketPath, isDaemonAlive, ensureDaemon } = await import("../opentasks-client.mjs");
@@ -398,6 +403,47 @@ describe("bootstrap", () => {
           "session-xyz"
         );
       });
+
+      it("registers main agent via spawn command after sidecar starts", async () => {
+        startSidecar.mockResolvedValue(true);
+        const config = makeConfig({ mapEnabled: true, sidecar: "session" });
+        await backgroundInit(config, "swarm:test", pluginDir(), "session-main");
+        // Allow fire-and-forget promise to settle
+        await new Promise((r) => setTimeout(r, 50));
+        expect(sendCommand).toHaveBeenCalledWith(
+          expect.anything(),
+          expect.objectContaining({
+            action: "spawn",
+            agent: expect.objectContaining({
+              agentId: "session-main",
+              name: "test-team-main",
+              role: "orchestrator",
+              metadata: expect.objectContaining({ isMain: true, sessionId: "session-main" }),
+            }),
+          }),
+          "session-main"
+        );
+      });
+
+      it("uses sessionId as agentId for main agent", async () => {
+        startSidecar.mockResolvedValue(true);
+        const config = makeConfig({ mapEnabled: true, sidecar: "session" });
+        await backgroundInit(config, "swarm:test", pluginDir(), "abc-123-def");
+        await new Promise((r) => setTimeout(r, 50));
+        const spawnCall = sendCommand.mock.calls.find(
+          (c) => c[1]?.action === "spawn"
+        );
+        expect(spawnCall).toBeDefined();
+        expect(spawnCall[1].agent.agentId).toBe("abc-123-def");
+      });
+
+      it("does not register main agent when sidecar fails to start", async () => {
+        startSidecar.mockResolvedValue(false);
+        const config = makeConfig({ mapEnabled: true, sidecar: "session" });
+        await backgroundInit(config, "swarm:test", pluginDir(), "session-fail");
+        await new Promise((r) => setTimeout(r, 50));
+        expect(sendCommand).not.toHaveBeenCalled();
+      });
     });
 
     describe("sessionlog sync", () => {

package/src/__tests__/e2e-main-agent-registration.test.mjs

@@ -0,0 +1,229 @@
+/**
+ * E2E test: Main agent registration on bootstrap
+ *
+ * Verifies that when the sidecar starts successfully, the bootstrap
+ * sends a spawn command to register the main Claude Code session agent.
+ *
+ * Uses a real TestServer + AgentConnection (no mocks on MAP layer).
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import net from "net";
+import path from "path";
+import { createStreamPair, AgentConnection } from "@multi-agent-protocol/sdk";
+import { TestServer } from "@multi-agent-protocol/sdk/testing";
+import { createSocketServer, createCommandHandler } from "../sidecar-server.mjs";
+import { makeTmpDir, cleanupTmpDir } from "./helpers.mjs";
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+function sendSocketCommand(socketPath, command) {
+  return new Promise((resolve, reject) => {
+    const client = net.createConnection(socketPath);
+    let data = "";
+    client.on("connect", () => {
+      client.write(JSON.stringify(command) + "\n");
+    });
+    client.on("data", (chunk) => {
+      data += chunk.toString();
+      try {
+        const parsed = JSON.parse(data.trim().split("\n").pop());
+        client.destroy();
+        resolve(parsed);
+      } catch {
+        // wait for more data
+      }
+    });
+    client.on("error", reject);
+    setTimeout(() => {
+      client.destroy();
+      try {
+        resolve(JSON.parse(data.trim().split("\n").pop()));
+      } catch {
+        reject(new Error("Timeout waiting for response"));
+      }
+    }, 3000);
+  });
+}
+
+async function createLiveMapConnection(agentName = "sidecar-agent") {
+  const server = new TestServer({ name: "test-map-server" });
+  const [clientStream, serverStream] = createStreamPair();
+  server.acceptConnection(serverStream);
+
+  const conn = new AgentConnection(clientStream, {
+    name: agentName,
+    role: "sidecar",
+  });
+
+  await conn.connect();
+
+  return { server, conn };
+}
+
+// ── Tests ────────────────────────────────────────────────────────────────────
+
+describe("Main agent registration via spawn", () => {
+  let tmpDir;
+  let socketPath;
+  let socketServer;
+  let mapServer;
+  let conn;
+  let registeredAgents;
+
+  const SCOPE = "swarm:test-team";
+  const SESSION_ID = "test-session-abc-123";
+
+  beforeEach(async () => {
+    tmpDir = makeTmpDir("e2e-main-agent-");
+    socketPath = path.join(tmpDir, "sidecar.sock");
+
+    const live = await createLiveMapConnection("test-team-sidecar");
+    mapServer = live.server;
+    conn = live.conn;
+
+    registeredAgents = new Map();
+    const handler = createCommandHandler(conn, SCOPE, registeredAgents);
+    socketServer = createSocketServer(socketPath, handler);
+    await new Promise((resolve) => socketServer.on("listening", resolve));
+  });
+
+  afterEach(async () => {
+    if (socketServer) {
+      await new Promise((resolve) => socketServer.close(resolve));
+      socketServer = null;
+    }
+    if (conn && conn.isConnected) {
+      try { await conn.disconnect(); } catch { /* ignore */ }
+    }
+    cleanupTmpDir(tmpDir);
+  });
+
+  it("registers main agent with sessionId as agentId", async () => {
+    // This is the exact command bootstrap sends after sidecar starts
+    const resp = await sendSocketCommand(socketPath, {
+      action: "spawn",
+      agent: {
+        agentId: SESSION_ID,
+        name: "test-team-main",
+        role: "orchestrator",
+        scopes: [SCOPE],
+        metadata: { isMain: true, sessionId: SESSION_ID },
+      },
+    });
+
+    expect(resp.ok).toBe(true);
+    expect(resp.agent?.agent?.id).toBe(SESSION_ID);
+
+    // Verify in TestServer
+    const mainAgent = mapServer.agents.get(SESSION_ID);
+    expect(mainAgent).toBeDefined();
+    expect(mainAgent.name).toBe("test-team-main");
+    expect(mainAgent.role).toBe("orchestrator");
+
+    // Verify in local tracking
+    expect(registeredAgents.has(SESSION_ID)).toBe(true);
+    expect(registeredAgents.get(SESSION_ID).role).toBe("orchestrator");
+    expect(registeredAgents.get(SESSION_ID).metadata.isMain).toBe(true);
+  });
+
+  it("main agent coexists with spawned subagents", async () => {
+    // Register main agent
+    await sendSocketCommand(socketPath, {
+      action: "spawn",
+      agent: {
+        agentId: SESSION_ID,
+        name: "test-team-main",
+        role: "orchestrator",
+        scopes: [SCOPE],
+        metadata: { isMain: true, sessionId: SESSION_ID },
+      },
+    });
+
+    // Spawn a subagent (like SubagentStart hook would)
+    const subResp = await sendSocketCommand(socketPath, {
+      action: "spawn",
+      agent: {
+        agentId: "subagent-xyz-456",
+        name: "Explore",
+        role: "subagent",
+        scopes: [SCOPE],
+        metadata: { agentType: "Explore", sessionId: "subagent-xyz-456" },
+      },
+    });
+
+    expect(subResp.ok).toBe(true);
+
+    // Both should exist in TestServer
+    expect(mapServer.agents.has(SESSION_ID)).toBe(true);
+    expect(mapServer.agents.has("subagent-xyz-456")).toBe(true);
+
+    // Both in local tracking
+    expect(registeredAgents.size).toBe(2);
+    expect(registeredAgents.get(SESSION_ID).role).toBe("orchestrator");
+    expect(registeredAgents.get("subagent-xyz-456").role).toBe("subagent");
+  });
+
+  it("main agent survives subagent lifecycle", async () => {
+    // Register main
+    await sendSocketCommand(socketPath, {
+      action: "spawn",
+      agent: {
+        agentId: SESSION_ID,
+        name: "test-team-main",
+        role: "orchestrator",
+        scopes: [SCOPE],
+        metadata: { isMain: true, sessionId: SESSION_ID },
+      },
+    });
+
+    // Spawn and kill a subagent
+    await sendSocketCommand(socketPath, {
+      action: "spawn",
+      agent: {
+        agentId: "ephemeral-sub",
+        name: "Explore",
+        role: "subagent",
+        scopes: [SCOPE],
+        metadata: {},
+      },
+    });
+
+    await sendSocketCommand(socketPath, {
+      action: "done",
+      agentId: "ephemeral-sub",
+      reason: "completed",
+    });
+
+    // Main agent should still be registered
+    expect(registeredAgents.has(SESSION_ID)).toBe(true);
+    expect(registeredAgents.has("ephemeral-sub")).toBe(false);
+    expect(mapServer.agents.has(SESSION_ID)).toBe(true);
+  });
+
+  it("main agent appears in TestServer event history as agent_registered", async () => {
+    await sendSocketCommand(socketPath, {
+      action: "spawn",
+      agent: {
+        agentId: SESSION_ID,
+        name: "test-team-main",
+        role: "orchestrator",
+        scopes: [SCOPE],
+        metadata: { isMain: true, sessionId: SESSION_ID },
+      },
+    });
+
+    const registeredEvents = mapServer.eventHistory.filter(
+      (e) => e.event.type === "agent_registered"
+    );
+
+    // At least sidecar + main agent
+    expect(registeredEvents.length).toBeGreaterThanOrEqual(2);
+
+    const mainEvent = registeredEvents.find(
+      (e) => e.event.data?.name === "test-team-main" ||
+             e.event.data?.agentId === SESSION_ID
+    );
+    expect(mainEvent).toBeDefined();
+  });
+});

package/src/__tests__/e2e-reconnection.test.mjs

@@ -102,7 +102,7 @@ describe("E2E: sidecar reconnection after MAP connection loss", () => {
     socketPath = path.join(tmpDir, "sidecar.sock");
     mockConn = createMockMapConnection();
     registeredAgents = new Map();
-    handler = createCommandHandler(mockConn, SCOPE, registeredAgents);
+    handler = createCommandHandler(mockConn, SCOPE, registeredAgents, { connWaitTimeoutMs: 500 });
     server = createSocketServer(socketPath, handler);
     await new Promise((resolve) => server.on("listening", resolve));
   });
@@ -191,7 +191,7 @@ describe("E2E: sidecar reconnection after MAP connection loss", () => {
       expect(mockConn.send).not.toHaveBeenCalled();
     });
 
-    it("spawn responds ok:false with error when connection is null", async () => {
+    it("spawn responds ok:false with error when connection is null (after wait timeout)", async () => {
       handler.setConnection(null);
 
       const resp = await sendSocketCommand(socketPath, {
@@ -206,10 +206,10 @@ describe("E2E: sidecar reconnection after MAP connection loss", () => {
       });
 
       expect(resp.ok).toBe(false);
-      expect(resp.error).toBe("no connection");
+      expect(resp.error).toContain("timed out waiting");
     });
 
-    it("trajectory-checkpoint responds ok:false when connection is null", async () => {
+    it("trajectory-checkpoint responds ok:false when connection is null (after wait timeout)", async () => {
       handler.setConnection(null);
 
       const resp = await sendSocketCommand(socketPath, {
@@ -218,7 +218,7 @@ describe("E2E: sidecar reconnection after MAP connection loss", () => {
       });
 
       expect(resp.ok).toBe(false);
-      expect(resp.error).toBe("no connection");
+      expect(resp.error).toContain("timed out waiting");
     });
 
     it("ping still works with null connection", async () => {

package/src/__tests__/sidecar-server.test.mjs

@@ -168,7 +168,7 @@ describe("sidecar-server", () => {
       });
 
       it("responds {ok: false} when no connection", async () => {
-        const nullHandler = createCommandHandler(null, "swarm:test", registeredAgents);
+        const nullHandler = createCommandHandler(null, "swarm:test", registeredAgents, { connWaitTimeoutMs: 0 });
         await nullHandler({
           action: "spawn",
           agent: { agentId: "a", name: "a", role: "r", scopes: [], metadata: {} },
@@ -240,7 +240,7 @@ describe("sidecar-server", () => {
       });
 
       it("responds {ok: false} when no connection", async () => {
-        const nullHandler = createCommandHandler(null, "swarm:test", registeredAgents);
+        const nullHandler = createCommandHandler(null, "swarm:test", registeredAgents, { connWaitTimeoutMs: 0 });
         await nullHandler({ action: "trajectory-checkpoint", checkpoint: {} }, mockClient);
         const written = JSON.parse(mockClient.write.mock.calls[0][0]);
         expect(written.ok).toBe(false);
@@ -264,7 +264,7 @@ describe("sidecar-server", () => {
       });
 
       it("responds {ok: true} even without connection", async () => {
-        const nullHandler = createCommandHandler(null, "swarm:test", registeredAgents);
+        const nullHandler = createCommandHandler(null, "swarm:test", registeredAgents, { connWaitTimeoutMs: 0 });
         await nullHandler({
           action: "bridge-task-created",
           task: { id: "t-1" },
@@ -360,7 +360,7 @@ describe("sidecar-server", () => {
       });
 
       it("responds {ok: true} without connection", async () => {
-        const nullHandler = createCommandHandler(null, "swarm:test", registeredAgents);
+        const nullHandler = createCommandHandler(null, "swarm:test", registeredAgents, { connWaitTimeoutMs: 0 });
         await nullHandler({
           action: "bridge-task-assigned",
           taskId: "t-1",