claude-code-swarm 0.3.3 → 0.3.5

package/src/agent-generator.mjs

@@ -45,24 +45,23 @@ export function parseBasicYaml(content) {
 /**
  * Determine which tools an agent needs based on role name, manifest, and position.
  */
-export function determineTools(roleName, manifest, position) {
+export function determineTools(roleName, manifest, position, options = {}) {
   const tools = ["Read", "Glob", "Grep", "Bash"];
 
-  // All team agents get native team coordination tools
-  tools.push("TaskList", "TaskUpdate", "SendMessage");
-
-  // Root and companions get full tool access + Agent spawning + task creation
-  if (position === "root" || position === "companion") {
-    tools.push("Write", "Edit", "Agent", "TaskCreate");
+  if (options.opentasksEnabled) {
+    tools.push("SendMessage");
+  } else {
+    tools.push("TaskList", "TaskUpdate", "SendMessage");
+    if (position === "root" || position === "companion") {
+      tools.push("TaskCreate");
+    }
   }
 
-  // Check spawn rules — if this role can spawn others, it needs Agent tool
-  const spawnRules = manifest.topology?.spawn_rules?.[roleName];
-  if (spawnRules && spawnRules.length > 0 && !tools.includes("Agent")) {
-    tools.push("Agent");
+  if (position === "root" || position === "companion") {
+    tools.push("Write", "Edit");
   }
 
-  // Roles that sound like they write code get write tools
+  // Keep existing writeRoles logic for code-writing roles
   const writeRoles = [
     "executor",
     "developer",
@@ -89,6 +88,9 @@ export function generateAgentMd({
   tools,
   skillContent,
   manifest,
+  opentasksEnabled,
+  minimemEnabled,
+  skillLoadout,
 }) {
   const lines = [];
 
@@ -177,26 +179,69 @@ export function generateAgentMd({
     lines.push("");
   }
 
-  // Task management via native tools
-  lines.push("### Task Management");
-  lines.push("");
-  lines.push("Use Claude Code's native task tools:");
-  lines.push(
-    "- **TaskList** — check available tasks and their status"
-  );
-  lines.push(
-    "- **TaskUpdate** — claim tasks (set owner to your name), update status to in_progress or completed"
-  );
-  if (position === "root" || position === "companion") {
+  // Task management section
+  if (opentasksEnabled) {
+    lines.push("### Task Management (via opentasks)");
+    lines.push("");
+    lines.push("Use **opentasks MCP tools** for all task management:");
+    lines.push(
+      "- **opentasks__list_tasks** — check available tasks and their status"
+    );
+    lines.push(
+      "- **opentasks__update_task** — claim tasks (set assignee to your name), update status"
+    );
+    if (position === "root" || position === "companion") {
+      lines.push(
+        "- **opentasks__create_task** — create new tasks for the team when you identify additional work"
+      );
+    }
+    lines.push("");
+    lines.push(
+      "After completing a task, mark it completed via opentasks__update_task, then check opentasks__list_tasks for your next assignment."
+    );
+    lines.push("");
+  } else {
+    lines.push("### Task Management");
+    lines.push("");
+    lines.push("Use Claude Code's native task tools:");
     lines.push(
-      "- **TaskCreate** — create new tasks for the team when you identify additional work"
+      "- **TaskList** — check available tasks and their status"
     );
+    lines.push(
+      "- **TaskUpdate** — claim tasks (set owner to your name), update status to in_progress or completed"
+    );
+    if (position === "root" || position === "companion") {
+      lines.push(
+        "- **TaskCreate** — create new tasks for the team when you identify additional work"
+      );
+    }
+    lines.push("");
+    lines.push(
+      "After completing a task, mark it completed with TaskUpdate, then check TaskList for your next assignment."
+    );
+    lines.push("");
+  }
+
+  // Memory section (minimem)
+  if (minimemEnabled) {
+    lines.push("### Memory");
+    lines.push("");
+    lines.push("Use **minimem MCP tools** to recall and store knowledge:");
+    lines.push("- **minimem__memory_search** — search past decisions, context, patterns");
+    lines.push("- **minimem__memory_get_details** — get full text for a search result");
+    lines.push("- **minimem__knowledge_search** — search with domain/entity filters");
+    lines.push("");
+    lines.push("Before starting major work, search memory for relevant prior context.");
+    lines.push("");
+  }
+
+  // Skills section (skill-tree loadout)
+  if (skillLoadout) {
+    lines.push("## Skills");
+    lines.push("");
+    lines.push(skillLoadout);
+    lines.push("");
   }
-  lines.push("");
-  lines.push(
-    "After completing a task, mark it completed with TaskUpdate, then check TaskList for your next assignment."
-  );
-  lines.push("");
 
   // Optional MAP note
   lines.push("### External Observability (MAP)");
@@ -216,7 +261,7 @@ export function generateAgentMd({
  * Uses openteams TemplateLoader when available, falls back to basic YAML parsing.
  * Returns { success, roles: string[], error? }.
  */
-export async function generateAllAgents(templateDir, outputDir) {
+export async function generateAllAgents(templateDir, outputDir, options = {}) {
   const absTemplateDir = path.resolve(templateDir);
   const absOutputDir = path.resolve(outputDir);
 
@@ -236,13 +281,26 @@ export async function generateAllAgents(templateDir, outputDir) {
     TemplateLoader = null;
   }
 
+  // Load skill loadouts if available (compiled by skilltree-client during team loading)
+  let skillLoadouts = {};
+  const loadoutsPath = path.join(absOutputDir, "..", "skill-loadouts.json");
+  if (fs.existsSync(loadoutsPath)) {
+    try {
+      skillLoadouts = JSON.parse(fs.readFileSync(loadoutsPath, "utf-8"));
+    } catch { /* ignore */ }
+  }
+
   const generatedRoles = [];
 
   if (TemplateLoader) {
     const template = TemplateLoader.load(absTemplateDir);
     const teamName = template.manifest.name;
     const manifest = template.manifest;
-    const roleSkillMds = generateAllRoleSkillMds(template, { teamName });
+    const roleSkillMds = generateAllRoleSkillMds(template, {
+      teamName,
+      includeSpawnSection: false,
+      includeCliSection: false,
+    });
 
     for (const roleSkill of roleSkillMds) {
       const roleName = roleSkill.role;
@@ -261,7 +319,7 @@ export async function generateAllAgents(templateDir, outputDir) {
         model = comp?.config?.model;
       }
 
-      const tools = determineTools(roleName, manifest, position);
+      const tools = determineTools(roleName, manifest, position, options);
 
       const agentMd = generateAgentMd({
         roleName,
@@ -272,6 +330,9 @@ export async function generateAllAgents(templateDir, outputDir) {
         tools,
         skillContent: roleSkill.content,
         manifest,
+        opentasksEnabled: options.opentasksEnabled,
+        minimemEnabled: options.minimemEnabled,
+        skillLoadout: skillLoadouts[roleName] || "",
       });
 
       const agentDir = path.join(absOutputDir, roleName);
@@ -302,12 +363,22 @@ export async function generateAllAgents(templateDir, outputDir) {
         prompt = fs.readFileSync(promptFile, "utf-8");
       }
 
+      const fallbackTools = ["Read", "Write", "Edit", "Bash", "Glob", "Grep", "Agent"];
+      if (options.opentasksEnabled) {
+        fallbackTools.push("SendMessage");
+      } else {
+        fallbackTools.push("TaskList", "TaskUpdate", "TaskCreate", "SendMessage");
+      }
+
       const agentMd = generateAgentMd({
         roleName,
         teamName: manifest.name,
         position: "spawned",
         description: `${roleName} agent in the ${manifest.name} team`,
-        tools: ["Read", "Write", "Edit", "Bash", "Glob", "Grep", "Agent", "TaskList", "TaskUpdate", "TaskCreate", "SendMessage"],
+        tools: fallbackTools,
+        opentasksEnabled: options.opentasksEnabled,
+        minimemEnabled: options.minimemEnabled,
+        skillLoadout: skillLoadouts[roleName] || "",
         skillContent: prompt
           ? `# Role: ${roleName}\n\nMember of the **${manifest.name}** team.\n\n## Instructions\n\n${prompt}`
           : `# Role: ${roleName}\n\nMember of the **${manifest.name}** team.`,

package/src/bootstrap.mjs

@@ -5,12 +5,17 @@
  * packages via swarmkit (openteams, MAP SDK, sessionlog), starts MAP
  * sidecar if configured, runs initial sessionlog sync.
  * Returns context object for formatting.
+ *
+ * Supports per-session sidecars: when sessionId is provided, each session
+ * gets its own sidecar process with isolated socket/pid/inbox paths.
  */
 
 import fs from "fs";
 import { execSync } from "child_process";
 import { readConfig, resolveScope } from "./config.mjs";
-import { SOCKET_PATH, PID_PATH, MAP_DIR, SIDECAR_LOG_PATH, pluginDir, ensureSwarmDir } from "./paths.mjs";
+import { SOCKET_PATH, MAP_DIR, pluginDir, ensureSwarmDir, ensureOpentasksDir, ensureSessionDir, listSessionDirs } from "./paths.mjs";
+import { findSocketPath, isDaemonAlive, ensureDaemon } from "./opentasks-client.mjs";
+import { loadTeam } from "./template.mjs";
 import { killSidecar, startSidecar } from "./sidecar-client.mjs";
 import { checkSessionlogStatus, syncSessionlog } from "./sessionlog.mjs";
 import { resolveSwarmkit, configureNodePath } from "./swarmkit-resolver.mjs";
@@ -47,6 +52,21 @@ function getRequiredGlobalPackages(config) {
   if (config.sessionlog.enabled) {
     packages.push("sessionlog");
   }
+  if (config.opentasks?.enabled) {
+    packages.push("opentasks");
+  }
+  if (config.inbox?.enabled) {
+    packages.push("agent-inbox");
+  }
+  if (config.minimem?.enabled) {
+    packages.push("minimem");
+  }
+  if (config.skilltree?.enabled) {
+    packages.push("skill-tree");
+  }
+  if (config.mesh?.enabled) {
+    packages.push("agentic-mesh");
+  }
   return packages;
 }
 
@@ -142,6 +162,33 @@ async function initSwarmProject(config) {
     }
   }
 
+  // Init opentasks project dir (.swarm/opentasks/) if enabled
+  if (config.opentasks?.enabled && !swarmkit.isProjectInit(cwd, "opentasks")) {
+    try {
+      await swarmkit.initProjectPackage("opentasks", ctx);
+    } catch {
+      // best-effort
+    }
+  }
+
+  // Init minimem project dir (.swarm/minimem/) if enabled
+  if (config.minimem?.enabled && !swarmkit.isProjectInit(cwd, "minimem")) {
+    try {
+      await swarmkit.initProjectPackage("minimem", ctx);
+    } catch {
+      // best-effort
+    }
+  }
+
+  // Init skill-tree project dir (.swarm/skill-tree/) if enabled
+  if (config.skilltree?.enabled && !swarmkit.isProjectInit(cwd, "skill-tree")) {
+    try {
+      await swarmkit.initProjectPackage("skill-tree", ctx);
+    } catch {
+      // best-effort
+    }
+  }
+
   // Init claude-code-swarm project dir (.swarm/claude-swarm/)
   if (!swarmkit.isProjectInit(cwd, "claude-code-swarm")) {
     try {
@@ -153,16 +200,42 @@ async function initSwarmProject(config) {
   }
 }
 
+/**
+ * Clean up stale session directories whose sidecar processes have died.
+ * Scans MAP_DIR/sessions/ and removes directories with dead PIDs.
+ * Best-effort: never throws.
+ */
+function cleanupStaleSessions() {
+  try {
+    for (const { dir, pidPath } of listSessionDirs()) {
+      try {
+        const pid = parseInt(fs.readFileSync(pidPath, "utf-8").trim());
+        process.kill(pid, 0); // throws if process is dead
+        // Process is alive — leave this session alone
+      } catch {
+        // Process is dead or PID file unreadable — clean up
+        try {
+          fs.rmSync(dir, { recursive: true, force: true });
+        } catch {
+          // ignore cleanup failures
+        }
+      }
+    }
+  } catch {
+    // Non-critical
+  }
+}
+
 /**
  * Start the MAP sidecar in session mode.
- * Kills any existing sidecar first, then starts a new one.
+ * Only kills this session's sidecar (if any), not other sessions'.
  * Returns status string.
  */
-async function startSessionSidecar(config, scope, dir) {
-  // Kill any existing sidecar from a previous session
-  killSidecar();
+async function startSessionSidecar(config, scope, dir, sessionId) {
+  // Kill only this session's sidecar (if somehow already running)
+  killSidecar(sessionId);
 
-  const ok = await startSidecar(config, dir);
+  const ok = await startSidecar(config, dir, sessionId);
   if (ok) {
     return `connected (scope: ${scope})`;
   }
@@ -182,8 +255,9 @@ function checkPersistentSidecar(scope) {
 
 /**
  * Full bootstrap flow. Returns context object for formatting.
+ * When sessionId is provided, uses per-session sidecar paths.
  */
-export async function bootstrap(pluginDirOverride) {
+export async function bootstrap(pluginDirOverride, sessionId) {
   const dir = pluginDirOverride || pluginDir();
 
   // 0. Install local dependencies (js-yaml, swarmkit)
@@ -203,6 +277,21 @@ export async function bootstrap(pluginDirOverride) {
 
   const scope = resolveScope(config);
 
+  // 1e. Load team template if configured (resolve, generate/cache, write roles.json)
+  let team = null;
+  if (config.template) {
+    try {
+      const result = await loadTeam(config.template);
+      if (result.success) {
+        team = result;
+      } else {
+        process.stderr.write(`[bootstrap] Warning: failed to load template '${config.template}': ${result.error}\n`);
+      }
+    } catch (err) {
+      process.stderr.write(`[bootstrap] Warning: template loading failed: ${err.message}\n`);
+    }
+  }
+
   // 2. Check sessionlog status
   let sessionlogStatus = "not installed";
   if (config.sessionlog.enabled) {
@@ -212,10 +301,16 @@ export async function bootstrap(pluginDirOverride) {
   // 3. Start MAP sidecar if configured
   let mapStatus = "disabled";
   if (config.map.enabled) {
-    fs.mkdirSync(MAP_DIR, { recursive: true });
+    if (sessionId) {
+      ensureSessionDir(sessionId);
+    } else {
+      fs.mkdirSync(MAP_DIR, { recursive: true });
+    }
 
     if (config.map.sidecar === "session") {
-      mapStatus = await startSessionSidecar(config, scope, dir);
+      // Clean up stale sessions before starting new one
+      cleanupStaleSessions();
+      mapStatus = await startSessionSidecar(config, scope, dir, sessionId);
     } else if (config.map.sidecar === "persistent") {
       mapStatus = checkPersistentSidecar(scope);
     }
@@ -223,15 +318,60 @@ export async function bootstrap(pluginDirOverride) {
 
   // 3b. Initial sessionlog sync (fire and forget)
   if (config.map.enabled && config.sessionlog.sync !== "off") {
-    syncSessionlog(config).catch(() => {});
+    syncSessionlog(config, sessionId).catch(() => {});
+  }
+
+  // 4. Start opentasks daemon if configured
+  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)";
+    }
+  }
+
+  // 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";
+    }
+  }
+
+  // 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";
+    }
   }
 
   return {
     template: config.template,
+    team,
     mapEnabled: config.map.enabled,
     mapStatus,
+    meshEnabled: config.mesh?.enabled,
     sessionlogEnabled: config.sessionlog.enabled,
     sessionlogStatus,
     sessionlogSync: config.sessionlog.sync,
+    opentasksEnabled: config.opentasks?.enabled,
+    opentasksStatus,
+    inboxEnabled: config.inbox?.enabled,
+    minimemEnabled: config.minimem?.enabled,
+    minimemStatus,
+    skilltreeEnabled: config.skilltree?.enabled,
+    skilltreeStatus,
+    sessionId,
   };
 }

package/src/config.mjs

@@ -1,12 +1,14 @@
 /**
  * config.mjs — Shared configuration parsing for claude-code-swarm
  *
- * Reads .swarm/claude/config.json and provides normalized config with defaults.
+ * Reads config with priority: env vars > project config > global config > defaults.
+ * Project config: .swarm/claude-swarm/config.json (in cwd)
+ * Global config:  ~/.claude-swarm/config.json
  * Used by bootstrap, hooks, sidecar, and team-loader.
  */
 
 import fs from "fs";
-import { CONFIG_PATH } from "./paths.mjs";
+import { CONFIG_PATH, GLOBAL_CONFIG_PATH } from "./paths.mjs";
 
 export const DEFAULTS = {
   mapServer: "ws://localhost:8080",
@@ -34,40 +36,102 @@ function envStr(name) {
 }
 
 /**
- * Read and normalize .swarm/claude/config.json config.
- * Priority: SWARM_* env vars > config file > defaults.
- * Never throws — returns defaults on any error.
+ * Read a JSON config file. Returns empty object on any error.
  */
-export function readConfig(configPath = CONFIG_PATH) {
-  let raw = {};
+function readJsonFile(filePath) {
   try {
-    raw = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+    return JSON.parse(fs.readFileSync(filePath, "utf-8"));
   } catch {
-    // Missing or invalid config file — raw stays empty, defaults apply
+    return {};
   }
+}
 
-  const server = envStr("SWARM_MAP_SERVER") ?? raw.map?.server ?? undefined;
-  const explicitEnabled = envBool("SWARM_MAP_ENABLED") ?? (raw.map?.enabled === true ? true : undefined);
+/**
+ * Read and normalize config with tiered resolution.
+ * Priority: SWARM_* env vars > project config file > global config file > defaults.
+ * Never throws — returns defaults on any error.
+ */
+export function readConfig(configPath = CONFIG_PATH, globalConfigPath = GLOBAL_CONFIG_PATH) {
+  const global = readJsonFile(globalConfigPath);
+  const project = readJsonFile(configPath);
+
+  // Project overrides global for each field (not deep merge — per-field fallthrough)
+  const server = envStr("SWARM_MAP_SERVER") ?? project.map?.server ?? global.map?.server ?? undefined;
+  const explicitEnabled = envBool("SWARM_MAP_ENABLED") ?? (project.map?.enabled === true ? true : undefined) ?? (global.map?.enabled === true ? true : undefined);
 
   // MAP is enabled if explicitly set OR if a server is configured
   const mapEnabled = explicitEnabled ?? (server !== undefined);
 
   return {
-    template: envStr("SWARM_TEMPLATE") ?? raw.template ?? "",
+    template: envStr("SWARM_TEMPLATE") ?? project.template ?? global.template ?? "",
     map: {
       enabled: mapEnabled,
       server: server || DEFAULTS.mapServer,
-      scope: envStr("SWARM_MAP_SCOPE") ?? raw.map?.scope ?? "",
-      systemId: envStr("SWARM_MAP_SYSTEM_ID") ?? raw.map?.systemId ?? DEFAULTS.mapSystemId,
-      sidecar: envStr("SWARM_MAP_SIDECAR") ?? raw.map?.sidecar ?? DEFAULTS.mapSidecar,
+      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,
+      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",
+      },
     },
     sessionlog: {
-      enabled: envBool("SWARM_SESSIONLOG_ENABLED") ?? Boolean(raw.sessionlog?.enabled),
-      sync: envStr("SWARM_SESSIONLOG_SYNC") ?? raw.sessionlog?.sync ?? DEFAULTS.sessionlogSync,
+      enabled: envBool("SWARM_SESSIONLOG_ENABLED") ?? Boolean(project.sessionlog?.enabled ?? global.sessionlog?.enabled),
+      sync: envStr("SWARM_SESSIONLOG_SYNC") ?? project.sessionlog?.sync ?? global.sessionlog?.sync ?? DEFAULTS.sessionlogSync,
+    },
+    opentasks: {
+      enabled: envBool("SWARM_OPENTASKS_ENABLED") ?? Boolean(project.opentasks?.enabled ?? global.opentasks?.enabled),
+      autoStart: envBool("SWARM_OPENTASKS_AUTOSTART") ?? (project.opentasks?.autoStart ?? global.opentasks?.autoStart) !== false,
+      scope: envStr("SWARM_OPENTASKS_SCOPE") ?? project.opentasks?.scope ?? global.opentasks?.scope ?? "tasks",
+    },
+    inbox: {
+      enabled: envBool("SWARM_INBOX_ENABLED") ?? project.inbox?.enabled ?? global.inbox?.enabled ?? mapEnabled,
+      sqlite: envStr("SWARM_INBOX_SQLITE") ?? project.inbox?.sqlite ?? global.inbox?.sqlite ?? "",
+      httpPort: parseInt(envStr("SWARM_INBOX_HTTP_PORT") ?? project.inbox?.httpPort ?? "0", 10) || 0,
+      webhooks: project.inbox?.webhooks ?? global.inbox?.webhooks ?? [],
+      federation: {
+        peers: project.inbox?.federation?.peers ?? global.inbox?.federation?.peers ?? [],
+        routing: project.inbox?.federation?.routing ?? global.inbox?.federation?.routing ?? undefined,
+        trust: project.inbox?.federation?.trust ?? global.inbox?.federation?.trust ?? undefined,
+      },
+    },
+    minimem: {
+      enabled: envBool("SWARM_MINIMEM_ENABLED") ?? Boolean(project.minimem?.enabled ?? global.minimem?.enabled),
+      provider: envStr("SWARM_MINIMEM_PROVIDER") ?? project.minimem?.provider ?? global.minimem?.provider ?? "auto",
+      global: envBool("SWARM_MINIMEM_GLOBAL") ?? Boolean(project.minimem?.global ?? global.minimem?.global),
+      dir: envStr("SWARM_MINIMEM_DIR") ?? project.minimem?.dir ?? global.minimem?.dir ?? "",
+    },
+    skilltree: {
+      enabled: envBool("SWARM_SKILLTREE_ENABLED") ?? Boolean(project.skilltree?.enabled ?? global.skilltree?.enabled),
+      basePath: envStr("SWARM_SKILLTREE_BASE_PATH") ?? project.skilltree?.basePath ?? global.skilltree?.basePath ?? "",
+      defaultProfile: envStr("SWARM_SKILLTREE_DEFAULT_PROFILE") ?? project.skilltree?.defaultProfile ?? global.skilltree?.defaultProfile ?? "",
+    },
+    mesh: {
+      enabled: envBool("SWARM_MESH_ENABLED") ?? Boolean(project.mesh?.enabled ?? global.mesh?.enabled),
+      peerId: envStr("SWARM_MESH_PEER_ID") ?? project.mesh?.peerId ?? global.mesh?.peerId ?? "",
+      mapServer: envStr("SWARM_MESH_MAP_SERVER") ?? project.mesh?.mapServer ?? global.mesh?.mapServer ?? "",
     },
   };
 }
 
+/**
+ * Build the MAP server URL with auth query param if configured.
+ * If the token is already in the server URL, returns as-is.
+ */
+export function resolveMapServer(config) {
+  const server = config.map?.server || DEFAULTS.mapServer;
+  const token = config.map?.auth?.token;
+  if (!token) return server;
+
+  // 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;
+
+  url.searchParams.set(param, token);
+  return url.toString();
+}
+
 /**
  * Derive MAP scope from config.
  * Priority: explicit scope > swarm:<template> > swarm:default