claude-code-swarm 0.3.7 → 0.3.8

package/src/bootstrap.mjs

@@ -1,10 +1,9 @@
 /**
  * bootstrap.mjs — SessionStart orchestration for claude-code-swarm
  *
- * Reads config, installs local deps (js-yaml, swarmkit), ensures global
- * packages via swarmkit (openteams, MAP SDK, sessionlog), starts MAP
- * sidecar if configured, runs initial sessionlog sync.
- * Returns context object for formatting.
+ * Two-phase bootstrap: a fast synchronous path returns context immediately
+ * (config + cached team artifacts), while slow operations (package version
+ * checks, sidecar startup, project init, status probes) run in the background.
  *
  * Supports per-session sidecars: when sessionId is provided, each session
  * gets its own sidecar process with isolated socket/pid/inbox paths.
@@ -14,10 +13,13 @@ import fs from "fs";
 import { execSync } from "child_process";
 import { readConfig, resolveScope, resolveTeamName } from "./config.mjs";
 import { SOCKET_PATH, MAP_DIR, pluginDir, ensureSwarmDir, ensureOpentasksDir, ensureSessionDir, listSessionDirs } from "./paths.mjs";
+import { createLogger, init as initLog } from "./log.mjs";
+
+const log = createLogger("bootstrap");
 import { findSocketPath, isDaemonAlive, ensureDaemon } from "./opentasks-client.mjs";
 import { loadTeam } from "./template.mjs";
 import { killSidecar, startSidecar, sendToInbox } from "./sidecar-client.mjs";
-import { checkSessionlogStatus, syncSessionlog } from "./sessionlog.mjs";
+import { checkSessionlogStatus, syncSessionlog, annotateSwarmSession } from "./sessionlog.mjs";
 import { resolveSwarmkit, configureNodePath } from "./swarmkit-resolver.mjs";
 
 /**
@@ -29,14 +31,14 @@ function installLocalDeps(dir) {
   const nodeModules = `${dir}/node_modules`;
   if (fs.existsSync(nodeModules)) return;
 
-  process.stderr.write("Installing claude-code-swarm dependencies...\n");
+  log.info("installing local dependencies");
   try {
     execSync("npm install --production", {
       cwd: dir,
       stdio: ["ignore", "ignore", "pipe"],
     });
   } catch (err) {
-    process.stderr.write(`Warning: npm install failed: ${err.message}\n`);
+    log.warn("npm install failed", { error: err.message });
   }
 }
 
@@ -78,34 +80,38 @@ function getRequiredGlobalPackages(config) {
 async function ensureGlobalPackages(config) {
   const swarmkit = await resolveSwarmkit();
   if (!swarmkit) {
-    process.stderr.write("[bootstrap] swarmkit not available, skipping global package check\n");
+    log.warn("swarmkit not available, skipping global package check");
     return;
   }
 
   const required = getRequiredGlobalPackages(config);
-  const missing = [];
 
-  for (const pkg of required) {
-    try {
-      const version = await swarmkit.getInstalledVersion(pkg);
-      if (!version) {
-        missing.push(pkg);
+  // Check all versions in parallel (~850ms each sequential → ~850ms total)
+  const checks = await Promise.allSettled(
+    required.map(async (pkg) => {
+      try {
+        const version = await swarmkit.getInstalledVersion(pkg);
+        return { pkg, version };
+      } catch {
+        return { pkg, version: null };
       }
-    } catch {
-      missing.push(pkg);
-    }
-  }
+    })
+  );
+  const missing = checks
+    .map((r) => r.status === "fulfilled" ? r.value : { pkg: "unknown", version: null })
+    .filter((r) => !r.version)
+    .map((r) => r.pkg);
 
   if (missing.length === 0) return;
 
-  process.stderr.write(`[bootstrap] Installing missing packages: ${missing.join(", ")}...\n`);
+  log.info("installing missing packages", { packages: missing });
   try {
     const results = await swarmkit.installPackages(missing);
     for (const r of results) {
       if (r.success) {
-        process.stderr.write(`[bootstrap] Installed ${r.package}@${r.version}\n`);
+        log.info("installed package", { package: r.package, version: r.version });
       } else {
-        process.stderr.write(`[bootstrap] Warning: failed to install ${r.package}: ${r.error}\n`);
+        log.warn("failed to install package", { package: r.package, error: r.error });
       }
     }
     const installed = results.filter((r) => r.success).map((r) => r.package);
@@ -117,7 +123,7 @@ async function ensureGlobalPackages(config) {
       }
     }
   } catch (err) {
-    process.stderr.write(`[bootstrap] Warning: global package install failed: ${err.message}\n`);
+    log.warn("global package install failed", { error: err.message });
   }
 }
 
@@ -253,31 +259,113 @@ function checkPersistentSidecar(scope) {
   return `WARNING: persistent sidecar not running at ${SOCKET_PATH}`;
 }
 
+/**
+ * Background work: package checks, sidecar startup, project init, status probes.
+ * Fire-and-forget — errors go to stderr, never block the session.
+ * Hooks have auto-recovery logic if sidecar isn't ready yet.
+ */
+export async function backgroundInit(config, scope, dir, sessionId) {
+  try {
+    // Parallelize: version checks + project init + sidecar startup
+    const tasks = [];
+
+    // Package version checks (slowest: ~1.7s sequential, runs in parallel here)
+    tasks.push(ensureGlobalPackages(config));
+
+    // Project directory init
+    tasks.push(initSwarmProject(config));
+
+    // MAP sidecar startup
+    if (config.map.enabled) {
+      if (sessionId) {
+        ensureSessionDir(sessionId);
+      } else {
+        fs.mkdirSync(MAP_DIR, { recursive: true });
+      }
+
+      if (config.map.sidecar === "session") {
+        cleanupStaleSessions();
+        tasks.push(
+          startSessionSidecar(config, scope, dir, sessionId).then((status) => {
+            log.info("MAP sidecar status", { status });
+          })
+        );
+      }
+    }
+
+    // Inbox registration
+    if (config.map.enabled && config.inbox?.enabled) {
+      const teamName = resolveTeamName(config);
+      const sPaths = sessionId
+        ? (await import("./paths.mjs")).sessionPaths(sessionId)
+        : { inboxSocketPath: (await import("./paths.mjs")).INBOX_SOCKET_PATH };
+      tasks.push(
+        sendToInbox({
+          action: "notify",
+          event: {
+            type: "agent.spawn",
+            agent: {
+              agentId: `${teamName}-main`,
+              name: `${teamName}-main`,
+              role: "orchestrator",
+              scopes: [scope],
+              metadata: { isMain: true, sessionId },
+            },
+          },
+        }, sPaths.inboxSocketPath).catch(() => {})
+      );
+    }
+
+    // Sessionlog sync + swarm annotation
+    if (config.map.enabled && config.sessionlog.sync !== "off") {
+      tasks.push(syncSessionlog(config, sessionId).catch(() => {}));
+    }
+    if (config.sessionlog.enabled) {
+      tasks.push(annotateSwarmSession(config, sessionId).catch(() => {}));
+    }
+
+    // OpenTasks daemon
+    if (config.opentasks?.enabled) {
+      ensureOpentasksDir();
+      if (config.opentasks?.autoStart) {
+        tasks.push(ensureDaemon(config).catch(() => {}));
+      }
+    }
+
+    await Promise.allSettled(tasks);
+  } catch (err) {
+    log.error("background init failed", { error: err.message });
+  }
+}
+
 /**
  * Full bootstrap flow. Returns context object for formatting.
+ *
+ * Fast path (~100ms): reads config, loads cached team artifacts, returns immediately.
+ * Background path (fire-and-forget): package checks, sidecar, project init.
  * When sessionId is provided, uses per-session sidecar paths.
  */
 export async function bootstrap(pluginDirOverride, sessionId) {
   const dir = pluginDirOverride || pluginDir();
 
-  // 0. Install local dependencies (js-yaml, swarmkit)
+  // ── Fast path: must complete before returning context ──────────────
+
+  // 0. Install local dependencies (js-yaml, swarmkit) — skipped if node_modules exists
   installLocalDeps(dir);
 
-  // 1. Read config (before ensureGlobalPackages so we know what's needed)
+  // 1. Read config
   const config = readConfig();
 
+  // 1a. Initialize logger from config (env vars still take priority)
+  initLog({ ...config.log, sessionId });
+  log.info("session started", { sessionId, template: config.template || "(none)" });
+
   // 1b. Configure NODE_PATH (global + local node_modules)
   configureNodePath(dir);
 
-  // 1c. Ensure global packages are installed via swarmkit (async, best-effort)
-  await ensureGlobalPackages(config);
-
-  // 1d. Initialize swarmkit project directories (.swarm/openteams/, .swarm/sessionlog/, .swarm/claude-swarm/)
-  await initSwarmProject(config);
-
   const scope = resolveScope(config);
 
-  // 1e. Load team template if configured (resolve, generate/cache, write roles.json)
+  // 2. Load team template if configured (fast if cached)
   let team = null;
   if (config.template) {
     try {
@@ -285,96 +373,43 @@ export async function bootstrap(pluginDirOverride, sessionId) {
       if (result.success) {
         team = result;
       } else {
-        process.stderr.write(`[bootstrap] Warning: failed to load template '${config.template}': ${result.error}\n`);
+        log.warn("failed to load template", { template: config.template, error: result.error });
       }
     } catch (err) {
-      process.stderr.write(`[bootstrap] Warning: template loading failed: ${err.message}\n`);
+      log.warn("template loading failed", { error: err.message });
     }
   }
 
-  // 2. Check sessionlog status
+  // 3. Sessionlog status — actual check is slow (execSync), defer to background
   let sessionlogStatus = "not installed";
   if (config.sessionlog.enabled) {
-    sessionlogStatus = checkSessionlogStatus();
+    sessionlogStatus = "checking";
   }
 
-  // 3. Start MAP sidecar if configured
+  // 4. Quick MAP status — report "starting" for session sidecars (actual startup is background)
   let mapStatus = "disabled";
   if (config.map.enabled) {
-    if (sessionId) {
-      ensureSessionDir(sessionId);
-    } else {
-      fs.mkdirSync(MAP_DIR, { recursive: true });
-    }
-
     if (config.map.sidecar === "session") {
-      // Clean up stale sessions before starting new one
-      cleanupStaleSessions();
-      mapStatus = await startSessionSidecar(config, scope, dir, sessionId);
+      mapStatus = `starting (scope: ${scope})`;
     } else if (config.map.sidecar === "persistent") {
       mapStatus = checkPersistentSidecar(scope);
     }
   }
 
-  // 3b. Register main agent in inbox for message routing
-  if (config.map.enabled && config.inbox?.enabled) {
-    const teamName = resolveTeamName(config);
-    const sPaths = sessionId
-      ? (await import("./paths.mjs")).sessionPaths(sessionId)
-      : { inboxSocketPath: (await import("./paths.mjs")).INBOX_SOCKET_PATH };
-    sendToInbox({
-      action: "notify",
-      event: {
-        type: "agent.spawn",
-        agent: {
-          agentId: `${teamName}-main`,
-          name: `${teamName}-main`,
-          role: "orchestrator",
-          scopes: [scope],
-          metadata: { isMain: true, sessionId },
-        },
-      },
-    }, sPaths.inboxSocketPath).catch(() => {});
-  }
-
-  // 3c. Initial sessionlog sync (fire and forget)
-  if (config.map.enabled && config.sessionlog.sync !== "off") {
-    syncSessionlog(config, sessionId).catch(() => {});
-  }
-
-  // 4. Start opentasks daemon if configured
+  // 5. Quick status for optional integrations (actual probes are too slow for fast path)
   let opentasksStatus = "disabled";
   if (config.opentasks?.enabled) {
-    ensureOpentasksDir();
-    if (config.opentasks?.autoStart) {
-      const ok = await ensureDaemon(config);
-      opentasksStatus = ok ? "connected" : "starting";
-    } else {
-      const alive = await isDaemonAlive(findSocketPath());
-      opentasksStatus = alive ? "connected" : "not running (autoStart: false)";
-    }
+    opentasksStatus = "enabled";
   }
 
-  // 5. Check minimem status if enabled
   let minimemStatus = "disabled";
   if (config.minimem?.enabled) {
-    try {
-      execSync("minimem status", { stdio: "pipe", timeout: 5000 });
-      minimemStatus = "ready";
-    } catch {
-      minimemStatus = "installed";
-    }
+    minimemStatus = "enabled";
   }
 
-  // 6. Check skill-tree status if enabled
   let skilltreeStatus = "disabled";
   if (config.skilltree?.enabled) {
-    try {
-      execSync("skill-tree list --json", { stdio: "pipe", timeout: 5000 });
-      skilltreeStatus = "ready";
-    } catch {
-      skilltreeStatus = "installed";
-    }
+    skilltreeStatus = "enabled";
   }
 
   return {

package/src/config.mjs

@@ -15,6 +15,7 @@ export const DEFAULTS = {
   mapScope: "swarm:default",
   mapSystemId: "system-claude-swarm",
   mapSidecar: "session",
+  mapReconnectIntervalMs: 60000,
   sessionlogSync: "off",
 };
 
@@ -70,9 +71,14 @@ export function readConfig(configPath = CONFIG_PATH, globalConfigPath = GLOBAL_C
       scope: envStr("SWARM_MAP_SCOPE") ?? project.map?.scope ?? global.map?.scope ?? "",
       systemId: envStr("SWARM_MAP_SYSTEM_ID") ?? project.map?.systemId ?? global.map?.systemId ?? DEFAULTS.mapSystemId,
       sidecar: envStr("SWARM_MAP_SIDECAR") ?? project.map?.sidecar ?? global.map?.sidecar ?? DEFAULTS.mapSidecar,
+      reconnectIntervalMs: parseInt(envStr("SWARM_MAP_RECONNECT_INTERVAL") ?? project.map?.reconnectIntervalMs ?? global.map?.reconnectIntervalMs ?? DEFAULTS.mapReconnectIntervalMs, 10) || DEFAULTS.mapReconnectIntervalMs,
+      swarmId: envStr("SWARM_MAP_SWARM_ID") ?? project.map?.swarmId ?? global.map?.swarmId ?? "",
       auth: {
         token: envStr("SWARM_MAP_AUTH_TOKEN") ?? project.map?.auth?.token ?? global.map?.auth?.token ?? "",
         param: envStr("SWARM_MAP_AUTH_PARAM") ?? project.map?.auth?.param ?? global.map?.auth?.param ?? "token",
+        // Opaque credential presented when server challenges with map/authenticate.
+        // The client doesn't know the type — the server tells it what method to use.
+        credential: envStr("AGENT_TOKEN") ?? envStr("SWARM_MAP_AUTH_CREDENTIAL") ?? project.map?.auth?.credential ?? global.map?.auth?.credential ?? "",
       },
     },
     sessionlog: {
@@ -111,24 +117,45 @@ export function readConfig(configPath = CONFIG_PATH, globalConfigPath = GLOBAL_C
       peerId: envStr("SWARM_MESH_PEER_ID") ?? project.mesh?.peerId ?? global.mesh?.peerId ?? "",
       mapServer: envStr("SWARM_MESH_MAP_SERVER") ?? project.mesh?.mapServer ?? global.mesh?.mapServer ?? "",
     },
+    log: {
+      level: envStr("SWARM_LOG_LEVEL") ?? project.log?.level ?? global.log?.level ?? "warn",
+      file: envStr("SWARM_LOG_FILE") ?? project.log?.file ?? global.log?.file ?? "",
+      dir: envStr("SWARM_LOG_DIR") ?? project.log?.dir ?? global.log?.dir ?? "",
+      stderr: envBool("SWARM_LOG_STDERR") ?? project.log?.stderr ?? global.log?.stderr ?? true,
+    },
   };
 }
 
 /**
- * Build the MAP server URL with auth query param if configured.
- * If the token is already in the server URL, returns as-is.
+ * Build the MAP server URL with auth query params.
+ *
+ * Always appends the API key (?token=) for hub access (both open + verified modes).
+ * Appends swarm_id for stable identity in open mode.
+ * The auth credential (for verified mode) is sent via map/authenticate, not here.
+ *
+ * @param config  Parsed config from readConfig()
+ * @param sessionId  Optional session ID used as default swarm_id for stable identity
  */
-export function resolveMapServer(config) {
+export function resolveMapServer(config, sessionId) {
   const server = config.map?.server || DEFAULTS.mapServer;
+  const url = new URL(server);
+
+  // API key for hub access (both modes)
   const token = config.map?.auth?.token;
-  if (!token) return server;
+  if (token) {
+    const param = config.map?.auth?.param || "token";
+    if (!url.searchParams.has(param)) url.searchParams.set(param, token);
+  }
 
-  // Don't double-add if token is already in the URL
-  const url = new URL(server);
-  const param = config.map?.auth?.param || "token";
-  if (url.searchParams.has(param)) return server;
+  // Swarm ID for stable identity (open mode — in verified mode, identity comes from credential)
+  const hasCredential = !!config.map?.auth?.credential;
+  if (!hasCredential) {
+    const swarmId = config.map?.swarmId || sessionId;
+    if (swarmId) {
+      url.searchParams.set("swarm_id", swarmId);
+    }
+  }
 
-  url.searchParams.set(param, token);
   return url.toString();
 }
 

package/src/index.mjs

@@ -83,6 +83,7 @@ export {
   findActiveSession,
   buildTrajectoryCheckpoint,
   syncSessionlog,
+  annotateSwarmSession,
 } from "./sessionlog.mjs";
 
 // Template
@@ -127,5 +128,8 @@ export {
   inferProfileFromRole,
 } from "./skilltree-client.mjs";
 
+// Logging
+export { createLogger, init as initLog } from "./log.mjs";
+
 // Bootstrap
 export { bootstrap } from "./bootstrap.mjs";

package/src/log.mjs

@@ -0,0 +1,152 @@
+/**
+ * log.mjs — Structured logging for claude-code-swarm
+ *
+ * Provides leveled, module-tagged logging with JSON Lines file output
+ * and human-readable stderr output. Supports per-session log files.
+ *
+ * Usage:
+ *   import { createLogger } from "./log.mjs";
+ *   const log = createLogger("bootstrap");
+ *   log.info("template loaded", { template: "gsd" });
+ *
+ * Configuration (env vars take priority over init() values):
+ *   SWARM_LOG_LEVEL  — error | warn | info | debug (default: warn)
+ *   SWARM_LOG_FILE   — explicit log file path (overrides everything)
+ *   SWARM_LOG_DIR    — log directory for per-session files (default: ~/.claude-swarm/tmp/logs/)
+ *   SWARM_LOG_STDERR — true | false (default: true)
+ *
+ * Per-session logs:
+ *   When init() is called with a sessionId, logs go to <dir>/<sessionId>.log.
+ *   Default dir is ~/.claude-swarm/tmp/logs/ (always global).
+ *   SWARM_LOG_FILE overrides per-session paths entirely.
+ */
+
+import fs from "fs";
+import path from "path";
+import { LOG_PATH, LOGS_DIR } from "./paths.mjs";
+
+const LEVELS = { error: 0, warn: 1, info: 2, debug: 3 };
+
+// Resolved lazily on first log call
+let _level;
+let _logFile;
+let _logsDir;
+let _stderr;
+let _initialized = false;
+
+/**
+ * Resolve config from env vars (called lazily on first write).
+ * Env vars are always authoritative — init() only fills in gaps.
+ */
+function resolveFromEnv() {
+  if (_initialized) return;
+  _initialized = true;
+  _level = LEVELS[process.env.SWARM_LOG_LEVEL?.toLowerCase()] ?? LEVELS.warn;
+  _logFile = process.env.SWARM_LOG_FILE || LOG_PATH;
+  _logsDir = process.env.SWARM_LOG_DIR || LOGS_DIR;
+  _stderr = process.env.SWARM_LOG_STDERR !== "false";
+}
+
+/**
+ * Resolve the log file path for a session.
+ * Returns <logsDir>/<timestamp>_<sessionId>.log, creating the directory if needed.
+ * Timestamp prefix (YYYYMMDD-HHmmss) makes files sortable chronologically.
+ */
+function sessionLogPath(sessionId, logsDir) {
+  const dir = logsDir || _logsDir || LOGS_DIR;
+  const now = new Date();
+  const ts = now.toISOString().replace(/[-:]/g, "").replace("T", "-").slice(0, 15);
+  const logPath = path.join(dir, `${ts}_${sessionId}.log`);
+  try {
+    fs.mkdirSync(dir, { recursive: true });
+  } catch {
+    // Best-effort — write() will also silently fail if dir doesn't exist
+  }
+  return logPath;
+}
+
+/**
+ * Apply config-file values and session context after readConfig() completes.
+ * Call from bootstrap / hook entry points. Env vars still take priority.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.level] - "error" | "warn" | "info" | "debug"
+ * @param {string} [opts.file]  - Log file path (overrides session-based path)
+ * @param {string} [opts.dir]   - Log directory for per-session files
+ * @param {boolean} [opts.stderr] - Also write to stderr
+ * @param {string} [opts.sessionId] - Session ID for per-session log files
+ */
+export function init({ level, file, dir, stderr, sessionId } = {}) {
+  resolveFromEnv();
+  if (!process.env.SWARM_LOG_LEVEL && level && LEVELS[level] !== undefined) {
+    _level = LEVELS[level];
+  }
+  if (!process.env.SWARM_LOG_DIR && dir) {
+    _logsDir = dir;
+  }
+  if (process.env.SWARM_LOG_FILE) {
+    // Env var is authoritative — don't override
+  } else if (file) {
+    _logFile = file;
+  } else if (sessionId) {
+    _logFile = sessionLogPath(sessionId, _logsDir);
+  }
+  if (process.env.SWARM_LOG_STDERR === undefined && stderr !== undefined) {
+    _stderr = Boolean(stderr);
+  }
+}
+
+/**
+ * Reset internal state. Exported for testing only.
+ */
+export function _reset() {
+  _level = undefined;
+  _logFile = undefined;
+  _logsDir = undefined;
+  _stderr = undefined;
+  _initialized = false;
+}
+
+/**
+ * Write a log entry. Best-effort — never throws.
+ */
+function write(level, mod, msg, data) {
+  resolveFromEnv();
+  if (LEVELS[level] > _level) return;
+
+  // JSON Lines to file
+  if (_logFile) {
+    const base = { ts: new Date().toISOString(), level, mod, msg };
+    const entry = data && Object.keys(data).length > 0
+      ? JSON.stringify({ ...base, data })
+      : JSON.stringify(base);
+    try {
+      fs.appendFileSync(_logFile, entry + "\n");
+    } catch {
+      // Best-effort — dir may not exist yet during early bootstrap
+    }
+  }
+
+  // Human-readable to stderr
+  if (_stderr) {
+    const extra = data && Object.keys(data).length > 0
+      ? " " + JSON.stringify(data)
+      : "";
+    process.stderr.write(`[${mod}:${level}] ${msg}${extra}\n`);
+  }
+}
+
+/**
+ * Create a logger scoped to a module name.
+ *
+ * @param {string} mod - Module identifier (e.g. "bootstrap", "sidecar", "mesh")
+ * @returns {{ error, warn, info, debug }} Logger methods
+ */
+export function createLogger(mod) {
+  return {
+    error: (msg, data) => write("error", mod, msg, data),
+    warn:  (msg, data) => write("warn",  mod, msg, data),
+    info:  (msg, data) => write("info",  mod, msg, data),
+    debug: (msg, data) => write("debug", mod, msg, data),
+  };
+}

package/src/map-connection.mjs

@@ -6,19 +6,31 @@
  */
 
 import { resolveScope, resolveTeamName, resolveMapServer, DEFAULTS } from "./config.mjs";
+import { createLogger } from "./log.mjs";
+
+const log = createLogger("map");
 
 /**
  * Connect to a MAP server as an agent.
  * Returns the AgentConnection or null on failure. Never throws.
  */
-export async function connectToMAP({ server, scope, systemId, onMessage }) {
+/**
+ * Connect to a MAP server as an agent.
+ *
+ * @param credential  Opaque credential for server-driven auth negotiation.
+ *   When the server requires auth (verified mode), uses the SDK's connectOnly()
+ *   + authenticate() + register() flow. The client responds to the server's
+ *   authRequired challenge with the server's preferred method + this credential.
+ *   When absent, uses the standard SDK connect() for open mode servers.
+ */
+export async function connectToMAP({ server, scope, systemId, onMessage, credential }) {
   try {
     const { AgentConnection } = await import("@multi-agent-protocol/sdk");
 
     const teamName = scope.replace("swarm:", "");
     const agentName = `${teamName}-sidecar`;
 
-    const connection = await AgentConnection.connect(server, {
+    const connectOpts = {
       name: agentName,
       role: "sidecar",
       scopes: [scope],
@@ -36,20 +48,39 @@ export async function connectToMAP({ server, scope, systemId, onMessage }) {
         baseDelayMs: 1000,
         maxDelayMs: 30000,
       },
-    });
+    };
+
+    let connection;
+
+    if (credential && typeof AgentConnection.createConnection === "function") {
+      // Verified mode: use the split flow (connectOnly → authenticate → register).
+      // The server drives the auth method — we just respond with our credential.
+      connection = await AgentConnection.createConnection(server, connectOpts);
+      const connectResult = await connection.connectOnly();
+
+      if (connectResult.authRequired && connectResult.authRequired.required) {
+        const method = connectResult.authRequired.methods[0];
+        const authResult = await connection.authenticate({ method, token: credential });
+        if (!authResult.success) {
+          log.error("authentication failed", { error: authResult.error?.message || "unknown error" });
+          return null;
+        }
+      }
+
+      await connection.register();
+    } else {
+      // Open mode (or SDK without createConnection): standard connect + register
+      connection = await AgentConnection.connect(server, connectOpts);
+    }
 
     if (onMessage) {
       connection.onMessage(onMessage);
     }
 
-    process.stderr.write(
-      `[map] Connected to ${server} as ${agentName} in scope ${scope}\n`
-    );
+    log.info("connected", { server, agent: agentName, scope });
     return connection;
   } catch (err) {
-    process.stderr.write(
-      `[map] Failed to connect to MAP server: ${err.message}\n`
-    );
+    log.error("failed to connect to MAP server", { error: err.message });
     return null;
   }
 }