claude-code-swarm 0.3.10 → 0.3.12

package/.claude-plugin/marketplace.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-swarm",
-  "version": "0.3.10",
+  "version": "0.3.12",
   "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,29 +1,34 @@
 {
   "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.10",
+  "version": "0.3.12",
   "author": {
     "name": "alexngai"
   },
   "mcpServers": {
     "opentasks": {
-      "command": "${CLAUDE_PLUGIN_ROOT}/.claude-plugin/run-opentasks-mcp.sh",
-      "args": [],
-      "env": {
-        "OPENTASKS_WORKING_DIR": "${workspaceFolder}"
-      }
+      "command": "node",
+      "args": [
+        "${CLAUDE_PLUGIN_ROOT}/.claude-plugin/mcp-launcher.mjs",
+        "opentasks"
+      ],
+      "env": {}
     },
     "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": [],
-      "env": {
-        "MINIMEM_WORKING_DIR": "${workspaceFolder}"
-      }
+      "command": "node",
+      "args": [
+        "${CLAUDE_PLUGIN_ROOT}/.claude-plugin/mcp-launcher.mjs",
+        "minimem"
+      ],
+      "env": {}
     }
   }
 }

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/hooks/hooks.json

@@ -7,6 +7,21 @@
           {
             "type": "command",
             "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/bootstrap.mjs\""
+          },
+          {
+            "type": "command",
+            "command": "if [ -f .swarm/claude-swarm/config.json ] && node -e \"const c=JSON.parse(require('fs').readFileSync('.swarm/claude-swarm/config.json','utf-8'));process.exit(c.sessionlog?.enabled?0:1)\" 2>/dev/null; then node \"${CLAUDE_PLUGIN_ROOT}/scripts/map-hook.mjs\" sessionlog-dispatch session-start; fi"
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "if [ -f .swarm/claude-swarm/config.json ] && node -e \"const c=JSON.parse(require('fs').readFileSync('.swarm/claude-swarm/config.json','utf-8'));process.exit(c.sessionlog?.enabled?0:1)\" 2>/dev/null; then node \"${CLAUDE_PLUGIN_ROOT}/scripts/map-hook.mjs\" sessionlog-dispatch session-end; fi"
           }
         ]
       }
@@ -18,6 +33,21 @@
           {
             "type": "command",
             "command": "if [ -f .swarm/claude-swarm/config.json ] && node -e \"const c=JSON.parse(require('fs').readFileSync('.swarm/claude-swarm/config.json','utf-8')).map||{};process.exit(c.enabled||c.server||process.env.SWARM_MAP_SERVER||process.env.SWARM_MAP_ENABLED?0:1)\" 2>/dev/null; then node \"${CLAUDE_PLUGIN_ROOT}/scripts/map-hook.mjs\" inject; fi"
+          },
+          {
+            "type": "command",
+            "command": "if [ -f .swarm/claude-swarm/config.json ] && node -e \"const c=JSON.parse(require('fs').readFileSync('.swarm/claude-swarm/config.json','utf-8'));process.exit(c.sessionlog?.enabled?0:1)\" 2>/dev/null; then node \"${CLAUDE_PLUGIN_ROOT}/scripts/map-hook.mjs\" sessionlog-dispatch user-prompt-submit; fi"
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Task",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "if [ -f .swarm/claude-swarm/config.json ] && node -e \"const c=JSON.parse(require('fs').readFileSync('.swarm/claude-swarm/config.json','utf-8'));process.exit(c.sessionlog?.enabled?0:1)\" 2>/dev/null; then node \"${CLAUDE_PLUGIN_ROOT}/scripts/map-hook.mjs\" sessionlog-dispatch pre-task; fi"
           }
         ]
       }
@@ -32,12 +62,25 @@
           }
         ]
       },
+      {
+        "matcher": "Task",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "if [ -f .swarm/claude-swarm/config.json ] && node -e \"const c=JSON.parse(require('fs').readFileSync('.swarm/claude-swarm/config.json','utf-8'));process.exit(c.sessionlog?.enabled?0:1)\" 2>/dev/null; then node \"${CLAUDE_PLUGIN_ROOT}/scripts/map-hook.mjs\" sessionlog-dispatch post-task; fi"
+          }
+        ]
+      },
       {
         "matcher": "TaskCreate",
         "hooks": [
           {
             "type": "command",
             "command": "if [ -f .swarm/claude-swarm/config.json ] && node -e \"const c=JSON.parse(require('fs').readFileSync('.swarm/claude-swarm/config.json','utf-8')).map||{};process.exit(c.enabled||c.server||process.env.SWARM_MAP_SERVER||process.env.SWARM_MAP_ENABLED?0:1)\" 2>/dev/null; then node \"${CLAUDE_PLUGIN_ROOT}/scripts/map-hook.mjs\" native-task-created; fi"
+          },
+          {
+            "type": "command",
+            "command": "if [ -f .swarm/claude-swarm/config.json ] && node -e \"const c=JSON.parse(require('fs').readFileSync('.swarm/claude-swarm/config.json','utf-8'));process.exit(c.sessionlog?.enabled?0:1)\" 2>/dev/null; then node \"${CLAUDE_PLUGIN_ROOT}/scripts/map-hook.mjs\" sessionlog-dispatch post-task-create; fi"
           }
         ]
       },
@@ -47,6 +90,46 @@
           {
             "type": "command",
             "command": "if [ -f .swarm/claude-swarm/config.json ] && node -e \"const c=JSON.parse(require('fs').readFileSync('.swarm/claude-swarm/config.json','utf-8')).map||{};process.exit(c.enabled||c.server||process.env.SWARM_MAP_SERVER||process.env.SWARM_MAP_ENABLED?0:1)\" 2>/dev/null; then node \"${CLAUDE_PLUGIN_ROOT}/scripts/map-hook.mjs\" native-task-updated; fi"
+          },
+          {
+            "type": "command",
+            "command": "if [ -f .swarm/claude-swarm/config.json ] && node -e \"const c=JSON.parse(require('fs').readFileSync('.swarm/claude-swarm/config.json','utf-8'));process.exit(c.sessionlog?.enabled?0:1)\" 2>/dev/null; then node \"${CLAUDE_PLUGIN_ROOT}/scripts/map-hook.mjs\" sessionlog-dispatch post-task-update; fi"
+          }
+        ]
+      },
+      {
+        "matcher": "TodoWrite",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "if [ -f .swarm/claude-swarm/config.json ] && node -e \"const c=JSON.parse(require('fs').readFileSync('.swarm/claude-swarm/config.json','utf-8'));process.exit(c.sessionlog?.enabled?0:1)\" 2>/dev/null; then node \"${CLAUDE_PLUGIN_ROOT}/scripts/map-hook.mjs\" sessionlog-dispatch post-todo; fi"
+          }
+        ]
+      },
+      {
+        "matcher": "EnterPlanMode",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "if [ -f .swarm/claude-swarm/config.json ] && node -e \"const c=JSON.parse(require('fs').readFileSync('.swarm/claude-swarm/config.json','utf-8'));process.exit(c.sessionlog?.enabled?0:1)\" 2>/dev/null; then node \"${CLAUDE_PLUGIN_ROOT}/scripts/map-hook.mjs\" sessionlog-dispatch post-plan-enter; fi"
+          }
+        ]
+      },
+      {
+        "matcher": "ExitPlanMode",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "if [ -f .swarm/claude-swarm/config.json ] && node -e \"const c=JSON.parse(require('fs').readFileSync('.swarm/claude-swarm/config.json','utf-8'));process.exit(c.sessionlog?.enabled?0:1)\" 2>/dev/null; then node \"${CLAUDE_PLUGIN_ROOT}/scripts/map-hook.mjs\" sessionlog-dispatch post-plan-exit; fi"
+          }
+        ]
+      },
+      {
+        "matcher": "Skill",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "if [ -f .swarm/claude-swarm/config.json ] && node -e \"const c=JSON.parse(require('fs').readFileSync('.swarm/claude-swarm/config.json','utf-8'));process.exit(c.sessionlog?.enabled?0:1)\" 2>/dev/null; then node \"${CLAUDE_PLUGIN_ROOT}/scripts/map-hook.mjs\" sessionlog-dispatch post-skill; fi"
           }
         ]
       }
@@ -62,6 +145,10 @@
           {
             "type": "command",
             "command": "if [ -f .swarm/claude-swarm/config.json ] && node -e \"const c=JSON.parse(require('fs').readFileSync('.swarm/claude-swarm/config.json','utf-8'));const m=c.map||{};process.exit((m.enabled||m.server||process.env.SWARM_MAP_SERVER||process.env.SWARM_MAP_ENABLED)&&c.sessionlog?.sync&&c.sessionlog.sync!=='off'?0:1)\" 2>/dev/null; then node \"${CLAUDE_PLUGIN_ROOT}/scripts/map-hook.mjs\" sessionlog-sync; fi"
+          },
+          {
+            "type": "command",
+            "command": "if [ -f .swarm/claude-swarm/config.json ] && node -e \"const c=JSON.parse(require('fs').readFileSync('.swarm/claude-swarm/config.json','utf-8'));process.exit(c.sessionlog?.enabled?0:1)\" 2>/dev/null; then node \"${CLAUDE_PLUGIN_ROOT}/scripts/map-hook.mjs\" sessionlog-dispatch stop; fi"
           }
         ]
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-swarm",
-  "version": "0.3.10",
+  "version": "0.3.12",
   "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"

package/scripts/map-hook.mjs

@@ -19,6 +19,7 @@
  *   teammate-idle       — Update teammate state to idle
  *   task-completed      — Complete task in opentasks + emit bridge event
  *   opentasks-mcp-used  — Bridge opentasks MCP tool use → MAP task sync payload
+ *   sessionlog-dispatch — Dispatch a sessionlog lifecycle hook via programmatic API
  *
  * Usage: node map-hook.mjs <action>
  *        Hook event data is read from stdin (JSON).
@@ -48,7 +49,7 @@ import {
   handleNativeTaskCreatedEvent,
   handleNativeTaskUpdatedEvent,
 } from "../src/map-events.mjs";
-import { syncSessionlog } from "../src/sessionlog.mjs";
+import { syncSessionlog, dispatchSessionlogHook } from "../src/sessionlog.mjs";
 import { findSocketPath, pushSyncEvent } from "../src/opentasks-client.mjs";
 
 const action = process.argv[2];
@@ -184,6 +185,15 @@ async function handleNativeTaskUpdated(hookData, sessionId) {
   await handleNativeTaskUpdatedEvent(config, hookData, sessionId);
 }
 
+async function handleSessionlogDispatch(hookData) {
+  const sessionlogHookName = process.argv[3];
+  if (!sessionlogHookName) {
+    log.warn("sessionlog-dispatch: missing hook name argument");
+    return;
+  }
+  await dispatchSessionlogHook(sessionlogHookName, hookData);
+}
+
 // ── Main ──────────────────────────────────────────────────────────────────────
 
 async function main() {
@@ -204,6 +214,7 @@ async function main() {
       case "opentasks-mcp-used": await handleOpentasksMcpUsed(hookData, sessionId); break;
       case "native-task-created": await handleNativeTaskCreated(hookData, sessionId); break;
       case "native-task-updated": await handleNativeTaskUpdated(hookData, sessionId); break;
+      case "sessionlog-dispatch": await handleSessionlogDispatch(hookData); break;
       default:
         log.warn("unknown action", { action });
     }

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,8 +16,14 @@ 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"),
+  ensureSessionlogEnabled: vi.fn().mockResolvedValue(false),
+  hasStandaloneHooks: vi.fn().mockReturnValue(false),
   syncSessionlog: vi.fn().mockResolvedValue(undefined),
   annotateSwarmSession: vi.fn().mockResolvedValue(undefined),
 }));
@@ -81,7 +87,8 @@ 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 { checkSessionlogStatus, syncSessionlog, annotateSwarmSession } = await import("../sessionlog.mjs");
+const { sendCommand } = await import("../map-events.mjs");
+const { checkSessionlogStatus, ensureSessionlogEnabled, hasStandaloneHooks, syncSessionlog, annotateSwarmSession } = await import("../sessionlog.mjs");
 const { pluginDir, ensureOpentasksDir, ensureSessionDir, listSessionDirs } = await import("../paths.mjs");
 const { findSocketPath, isDaemonAlive, ensureDaemon } = await import("../opentasks-client.mjs");
 const { resolveSwarmkit, configureNodePath } = await import("../swarmkit-resolver.mjs");
@@ -156,16 +163,43 @@ describe("bootstrap", () => {
     });
 
     describe("sessionlog", () => {
-      it("returns 'checking' when sessionlog enabled (actual check is in background)", async () => {
+      it("defers to standalone when standalone hooks are present", async () => {
+        hasStandaloneHooks.mockReturnValue(true);
         readConfig.mockReturnValue(makeConfig({ sessionlogEnabled: true }));
         const result = await bootstrap();
-        expect(result.sessionlogStatus).toBe("checking");
+        expect(result.sessionlogStatus).toBe("active (standalone)");
+        expect(ensureSessionlogEnabled).not.toHaveBeenCalled();
+      });
+
+      it("enables sessionlog when no standalone hooks", async () => {
+        hasStandaloneHooks.mockReturnValue(false);
+        ensureSessionlogEnabled.mockResolvedValue(true);
+        readConfig.mockReturnValue(makeConfig({ sessionlogEnabled: true }));
+        const result = await bootstrap();
+        expect(result.sessionlogStatus).toBe("active");
+        expect(ensureSessionlogEnabled).toHaveBeenCalled();
       });
 
-      it("does not call checkSessionlogStatus synchronously", async () => {
+      it("reports status when enable fails", async () => {
+        hasStandaloneHooks.mockReturnValue(false);
+        ensureSessionlogEnabled.mockResolvedValue(false);
         readConfig.mockReturnValue(makeConfig({ sessionlogEnabled: true }));
+        const result = await bootstrap();
+        expect(result.sessionlogStatus).toBe("installed but not enabled");
+      });
+
+      it("returns 'checking' when hasStandaloneHooks throws", async () => {
+        hasStandaloneHooks.mockImplementation(() => { throw new Error("unexpected"); });
+        readConfig.mockReturnValue(makeConfig({ sessionlogEnabled: true }));
+        const result = await bootstrap();
+        expect(result.sessionlogStatus).toBe("checking");
+      });
+
+      it("does not check standalone when disabled", async () => {
+        readConfig.mockReturnValue(makeConfig({ sessionlogEnabled: false }));
         await bootstrap();
-        expect(checkSessionlogStatus).not.toHaveBeenCalled();
+        expect(hasStandaloneHooks).not.toHaveBeenCalled();
+        expect(ensureSessionlogEnabled).not.toHaveBeenCalled();
       });
     });
 
@@ -398,6 +432,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", () => {