@mclawnet/swarm 0.1.10 → 0.1.12

package/dist/swarm-coordinator.js

@@ -11,10 +11,12 @@ import { InboxWatcher } from "./inbox-watcher.js";
 import { randomUUID } from "node:crypto";
 import { EvolutionPipeline } from "@mclawnet/skill-manager";
 import { TaskStore, computeLeadBriefing, computeMemberBriefing, computeTaskBriefing, formatLeadBriefing, formatMemberBriefing, formatTaskBriefing, projectRoot } from "@mclawnet/task";
+import { pickStrongestStatus } from "./plan-sync.js";
 import { existsSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { createLogger } from "@mclawnet/logger";
+import { DEFAULT_SANDBOX } from "@mclawnet/shared";
 const log = createLogger({ module: "swarm" });
 // Queen periodic patrol: pure safety-net heartbeat now that crash detection
 // is event-driven via handleRoleCrashed. Worker `task_set_status` /
@@ -49,6 +51,18 @@ export class SwarmCoordinator {
     swarms = new Map();
     inboxRelay;
     inboxWatcher;
+    /**
+     * Per-swarm spawn mutex (PR#5). A simple Promise-chain serialises every
+     * `spawnRole` call against a given swarmId so the
+     * `nextInstanceSeq.get / set` read-modify-write pair is atomic from the
+     * caller's perspective. Without this, two concurrent dynamic adds (e.g.
+     * the UI clicking "+ 添加成员" twice quickly while a prior spawn awaits
+     * its backend createSession) both observe seq=N and collide on the
+     * resulting `dev-N` instanceId. The chain element is replaced on every
+     * call so completed entries garbage-collect naturally; we never delete
+     * the key (cheap one-entry-per-swarm and avoids races on cleanup).
+     */
+    spawnLocks = new Map();
     constructor(sessionAdapter, hub, 
     /**
      * Optional factory that resolves a per-swarm TaskStore (workDir-scoped).
@@ -95,6 +109,85 @@ export class SwarmCoordinator {
         }
         return this.taskStoreFactory;
     }
+    /**
+     * Persist swarm snapshot to recovery.json, first reconciling plan task
+     * statuses from the live TaskStore (Bug #2 方案 B). All save call sites
+     * MUST go through this wrapper instead of saveSwarmSnapshot directly so
+     * the on-disk plan never lies about task progress.
+     *
+     * Why this exists:
+     *   `swarm.plan` is a snapshot of queen's initial output — queen sets
+     *   each task.status to "pending" once and never updates the plan
+     *   object. Without this sync, recovery.json would keep showing
+     *   "pending" forever, misleading both the queen LLM (when re-reading
+     *   its own plan after compaction) and human readers.
+     */
+    persistSwarm(swarm) {
+        try {
+            this.syncPlanStatusFromTasks(swarm);
+        }
+        catch (err) {
+            // Sync failure must not block persistence — recovery.json is the
+            // critical artifact for kill+restart; a stale plan is far better
+            // than no snapshot at all.
+            log.warn({ err, swarmId: swarm.id }, "syncPlanStatusFromTasks failed, persisting anyway");
+        }
+        saveSwarmSnapshot(swarm);
+    }
+    /**
+     * Match plan tasks to live task store entries via the explicit
+     * `planTaskId` foreign key (PR#1). Live tasks without a planTaskId are
+     * ignored — the queen is now responsible for tagging plan-derived tasks
+     * when she calls `task_create` / `task_create_from_message`. When multiple
+     * live tasks share the same planTaskId (e.g. queen retried a failure),
+     * `pickStrongestStatus` folds them: completed > in_progress > pending >
+     * cancelled.
+     *
+     * Replaces the prior subject-prefix heuristic (PR #73 / Bug #2 方案 B),
+     * which was fragile to queens rephrasing subjects and t1↔t10 collisions.
+     */
+    syncPlanStatusFromTasks(swarm) {
+        const plan = swarm.plan;
+        if (!plan || !plan.phases || !swarm.workDir)
+            return;
+        const taskStore = this.resolveTaskStore(swarm.workDir);
+        // No-op when no TaskStore is wired (e.g. unit tests with bare
+        // construction, or callers that intentionally opted out of DI).
+        // Plan stays with queen's original statuses — a stale display is
+        // strictly better than a runtime crash here.
+        if (!taskStore)
+            return;
+        const liveTasks = taskStore.listBySwarm(swarm.id);
+        if (liveTasks.length === 0)
+            return;
+        // Group live tasks by planTaskId. Tasks without a planTaskId are
+        // intentionally skipped — they are ad-hoc work that doesn't belong to
+        // any plan node, and silently subject-matching them would re-introduce
+        // the very ambiguity this PR removes.
+        const byPlanId = new Map();
+        for (const t of liveTasks) {
+            if (!t.planTaskId)
+                continue;
+            const arr = byPlanId.get(t.planTaskId) ?? [];
+            arr.push(t);
+            byPlanId.set(t.planTaskId, arr);
+        }
+        let synced = 0;
+        let total = 0;
+        for (const phase of plan.phases) {
+            if (!phase.tasks)
+                continue;
+            for (const task of phase.tasks) {
+                total++;
+                const matches = byPlanId.get(task.id);
+                if (!matches || matches.length === 0)
+                    continue;
+                task.status = pickStrongestStatus(matches.map((t) => t.status));
+                synced++;
+            }
+        }
+        log.debug({ swarmId: swarm.id, planTasksTotal: total, planTasksSynced: synced }, "syncPlanStatusFromTasks");
+    }
     // ── Public API ──────────────────────────────────────────────────────
     /** Create a new swarm with two-phase initialization. */
     async create(swarmSessionId, options) {
@@ -106,6 +199,38 @@ export class SwarmCoordinator {
         if (options.templateName) {
             const tpl = loadTemplate(options.templateName);
             roleSpecs = tpl.roles.map((r) => ({ roleName: r.roleName, count: r.count, eager: r.eager }));
+            // Overlay per-role backend from options.roles (UI selector). To stay
+            // correct under duplicate roleNames in the template (e.g. two
+            // {roleName:"developer"} entries), walk options.roles in order and
+            // claim the FIRST template spec whose name matches AND whose backend
+            // hasn't been overlaid yet.
+            //
+            // Note on UI/coordinator asymmetry: SwarmConfigInline collapses duplicate
+            // roleNames in its selection list via `.find()`, so today the UI only
+            // ever sends one entry per roleName and at most one slot gets overlaid
+            // here. This positional-claim algorithm is intentionally more general so
+            // non-UI callers (tests, future bulk APIs) can pass multiple entries with
+            // the same roleName and get distinct overlays.
+            if (options.roles) {
+                const claimed = new Set();
+                for (const uiRole of options.roles) {
+                    const idx = roleSpecs.findIndex((s, i) => !claimed.has(i) && s.roleName === uiRole.roleName);
+                    if (idx >= 0) {
+                        claimed.add(idx);
+                        if (uiRole.backend) {
+                            roleSpecs[idx] = { ...roleSpecs[idx], backend: uiRole.backend };
+                        }
+                        // Mirror backend overlay for sandbox so user's per-role choice in
+                        // SwarmConfigInline reaches spawnRole → role.definition.sandbox →
+                        // persistence.json. Without this, only dynamically-added roles
+                        // ever carried `sandbox`; the 6 initial roles silently dropped to
+                        // undefined and recovery.json had no record of the user's pick.
+                        if (uiRole.sandbox) {
+                            roleSpecs[idx] = { ...roleSpecs[idx], sandbox: uiRole.sandbox };
+                        }
+                    }
+                }
+            }
         }
         else {
             roleSpecs = options.roles ?? [];
@@ -115,6 +240,7 @@ export class SwarmCoordinator {
             hubSessionId: swarmSessionId,
             workDir: options.workDir,
             teamName: options.templateName,
+            displayName: options.displayName,
             roles: new Map(),
             plan: null,
             nextInstanceSeq: new Map(),
@@ -125,7 +251,6 @@ export class SwarmCoordinator {
             planStatus: "none",
         };
         // Store pending role specs for on-demand spawning
-        swarm._pendingRoleSpecs = roleSpecs;
         this.swarms.set(swarmSessionId, swarm);
         // Snapshot may already exist from a prior run (continuation, or
         // restart-after-crash with the same swarmId). Record this BEFORE any
@@ -153,7 +278,12 @@ export class SwarmCoordinator {
             for (const spec of eagerSpecs) {
                 const count = spec.count ?? 1;
                 for (let i = 0; i < count; i++) {
-                    const role = await this.spawnRole(swarmSessionId, spec.roleName, undefined, spec.customPrompt, spec.customDefinition);
+                    const role = await this.spawnRole(swarmSessionId, spec.roleName, {
+                        customPrompt: spec.customPrompt,
+                        customDefinition: spec.customDefinition,
+                        backendOverride: spec.backend,
+                        sandboxOverride: spec.sandbox,
+                    });
                     trackOpen(role);
                 }
             }
@@ -163,13 +293,12 @@ export class SwarmCoordinator {
             swarm.status = "running";
             const queen = this.findQueen(swarm);
             if (queen) {
-                const roleList = this.buildRoleListString(swarm);
-                // Notify queen that initialization is complete with full member list
-                await this.deliverInbox(swarm, queen.instanceId, {
-                    from: "system",
-                    type: "system",
-                    data: `[系统] 蜂群初始化完成。当前成员：\n${roleList}\n\n等待任务分配。`,
-                });
+                // Initial spawn delivers a "成员变更" envelope listing every just-spawned
+                // role as "+ 新增". Refactored from the prior bespoke "蜂群初始化完成"
+                // envelope so dynamic adds (PR#5) reuse exactly the same protocol;
+                // queen-side handling stays uniform across init vs. runtime adds.
+                const initiallyAdded = [...swarm.roles.values()].filter((r) => r.definition.type !== "queen");
+                await this.notifyMembershipChange(swarm, { added: initiallyAdded });
                 // Inject continuation context from previous run if applicable
                 if (options.isContinuation) {
                     const summary = this.buildContinuationSummary(swarmSessionId);
@@ -192,7 +321,7 @@ export class SwarmCoordinator {
             }
             log.info({ swarmId: swarmSessionId, roleCount: swarm.roles.size }, "swarm created");
             // Persistence: save initial snapshot
-            saveSwarmSnapshot(swarm);
+            this.persistSwarm(swarm);
             // Start inbox watcher to react to inbox file changes (best-effort).
             if (options.workDir) {
                 try {
@@ -262,8 +391,11 @@ export class SwarmCoordinator {
         const { swarm, role } = this.findByRoleSessionId(roleSessionId);
         if (!swarm || !role)
             return false;
+        // Output is already normalized to Claude SDK shape by
+        // SessionManager's onOutput gateway (see normalize-backend-output.ts).
+        const event = data;
         // Extract text content from the streaming event
-        const text = extractTextFromEvent(data);
+        const text = extractTextFromEvent(event);
         // Parse swarm action blocks
         if (text) {
             // Legacy-format safety net: if a reviewer regresses to the old
@@ -289,7 +421,7 @@ export class SwarmCoordinator {
                 if (plan) {
                     swarm.plan = plan;
                     swarm.planStatus = "draft";
-                    saveSwarmSnapshot(swarm);
+                    this.persistSwarm(swarm);
                     this.sendStatusUpdate(swarm);
                     log.info({ swarmId: swarm.id, instanceId: role.instanceId }, "plan updated (draft)");
                     this.requestPlanReview(swarm, plan).catch((err) => {
@@ -307,7 +439,7 @@ export class SwarmCoordinator {
             sessionId: swarm.hubSessionId,
             instanceId: role.instanceId,
             roleName: role.roleName,
-            data,
+            data: event,
         });
         return true;
     }
@@ -321,18 +453,18 @@ export class SwarmCoordinator {
             return false;
         // Update role status
         role.status = "idle";
-        // Persist per-role claudeSessionId — turn_complete frame carries the
+        // Persist per-role backendSessionId — turn_complete frame carries the
         // backend's real session UUID. We need it so a future restart can
         // `--resume` this exact role's conversation (Task 4 / Phase 4-5).
-        if (info.claudeSessionId && role.claudeSessionId !== info.claudeSessionId) {
-            role.claudeSessionId = info.claudeSessionId;
+        if (info.backendSessionId && role.backendSessionId !== info.backendSessionId) {
+            role.backendSessionId = info.backendSessionId;
             // saveSwarmSnapshot is sync-fire (proper-lockfile internally async);
             // call directly — failures should not break turn completion.
             try {
-                saveSwarmSnapshot(swarm);
+                this.persistSwarm(swarm);
             }
             catch (err) {
-                log.warn({ err, swarmId: swarm.id, instanceId: role.instanceId }, "failed to persist claudeSessionId on turn complete");
+                log.warn({ err, swarmId: swarm.id, instanceId: role.instanceId }, "failed to persist backendSessionId on turn complete");
             }
         }
         // Settle inbox echoes for this turn (fire-and-forget).
@@ -349,37 +481,55 @@ export class SwarmCoordinator {
         return true;
     }
     /**
-     * Persist the per-role claudeSessionId immediately (e.g. from `system/init`
+     * Persist the per-role backendSessionId immediately (e.g. from `system/init`
      * frame, before the first turn_complete). Returns true if a role was found
      * and updated; false otherwise (no-op for non-swarm sessions).
      */
-    setRoleClaudeSessionId(swarmId, instanceId, claudeSessionId) {
+    setRoleBackendSessionId(swarmId, instanceId, backendSessionId) {
         const swarm = this.swarms.get(swarmId);
         if (!swarm)
             return false;
         const role = swarm.roles.get(instanceId);
         if (!role)
             return false;
-        if (role.claudeSessionId === claudeSessionId)
+        if (role.backendSessionId === backendSessionId)
             return true;
-        role.claudeSessionId = claudeSessionId;
+        role.backendSessionId = backendSessionId;
         try {
-            saveSwarmSnapshot(swarm);
+            this.persistSwarm(swarm);
         }
         catch (err) {
-            log.warn({ err, swarmId, instanceId }, "failed to persist claudeSessionId");
+            log.warn({ err, swarmId, instanceId }, "failed to persist backendSessionId");
         }
         return true;
     }
-    /** Convenience: same as setRoleClaudeSessionId but takes the `${swarmId}::${instanceId}` roleSessionId. */
-    setRoleClaudeSessionIdBySession(roleSessionId, claudeSessionId) {
+    /** Convenience: same as setRoleBackendSessionId but takes the `${swarmId}::${instanceId}` roleSessionId. */
+    setRoleBackendSessionIdBySession(roleSessionId, backendSessionId) {
         const { swarm, role } = this.findByRoleSessionId(roleSessionId);
         if (!swarm || !role)
             return false;
-        return this.setRoleClaudeSessionId(swarm.id, role.instanceId, claudeSessionId);
+        return this.setRoleBackendSessionId(swarm.id, role.instanceId, backendSessionId);
     }
-    /** Spawn a new role instance in a swarm. */
-    async spawnRole(swarmId, roleName, taskPrompt, customPrompt, customDefinition, additionalDirs, resumeId, presetInstanceId) {
+    /**
+     * Public spawnRole entry point. Wraps the real body in a per-swarm
+     * Promise-chain mutex (see `spawnLocks`) so concurrent calls against the
+     * same swarmId serialise — preventing nextInstanceSeq collisions on
+     * parallel dynamic adds. Calls against different swarmIds run in
+     * parallel as before.
+     */
+    async spawnRole(swarmId, roleName, opts = {}) {
+        const prev = this.spawnLocks.get(swarmId) ?? Promise.resolve();
+        // `.catch(() => {})` here ensures a previous spawn's rejection does NOT
+        // poison subsequent waiters — they only need ORDER guarantees, not
+        // shared success/failure semantics. Each call's own rejection still
+        // surfaces through `next` to its own awaiter.
+        const next = prev.catch(() => undefined).then(() => this.doSpawnRole(swarmId, roleName, opts));
+        this.spawnLocks.set(swarmId, next);
+        return next;
+    }
+    /** Spawn a new role instance in a swarm (real implementation, serialized by spawnRole). */
+    async doSpawnRole(swarmId, roleName, opts = {}) {
+        const { taskPrompt, customPrompt, customDefinition, additionalDirs, resumeId, presetInstanceId, backendOverride, sandboxOverride, isDynamicAdd, } = opts;
         const swarm = this.swarms.get(swarmId);
         if (!swarm)
             throw new Error(`Swarm ${swarmId} not found`);
@@ -394,6 +544,7 @@ export class SwarmCoordinator {
                 capabilities: customDefinition.capabilities ?? [],
                 color: customDefinition.color,
                 promptBody: customDefinition.promptBody,
+                backend: customDefinition.backend,
             };
         }
         else {
@@ -403,10 +554,36 @@ export class SwarmCoordinator {
         if (customPrompt) {
             definition.promptBody = customPrompt;
         }
+        // Per-spawn backend override (UI selector) takes precedence over the
+        // role definition's static backend. Frozen here for the lifetime of the
+        // role instance.
+        if (backendOverride) {
+            definition = { ...definition, backend: backendOverride };
+        }
+        // Per-spawn sandbox override — same precedence rule. Each adapter
+        // maps the abstract level to its own permission model (see
+        // SpawnOptions.sandbox in @mclawnet/agent).
+        if (sandboxOverride) {
+            definition = { ...definition, sandbox: sandboxOverride };
+        }
+        // Final default: role files don't currently declare `sandbox`, and not
+        // every caller passes an override (e.g. legacy recovery, programmatic
+        // spawns). Pin to DEFAULT_SANDBOX so snapshots and the membership-change
+        // envelope always show a concrete level instead of `undefined`.
+        if (!definition.sandbox) {
+            definition = { ...definition, sandbox: DEFAULT_SANDBOX };
+        }
+        log.info({
+            swarmId,
+            roleName,
+            backendOverride,
+            definitionBackend: definition.backend,
+            hasCustomDefinition: !!customDefinition,
+        }, "spawnRole: backend resolved");
         let instanceId;
         if (presetInstanceId) {
             // Recovery path: preserve the original instanceId so per-role state
-            // (logs, inbox, claudeSessionId) lines up with prior snapshot.
+            // (logs, inbox, backendSessionId) lines up with prior snapshot.
             instanceId = presetInstanceId;
         }
         else {
@@ -422,9 +599,12 @@ export class SwarmCoordinator {
             roleSessionId,
             status: "spawning",
             currentTask: taskPrompt,
-            claudeSessionId: resumeId,
+            backendSessionId: resumeId,
         };
         swarm.roles.set(instanceId, roleInstance);
+        // Track whether we successfully opened the backend session so the
+        // dynamic-add rollback (below) knows whether to also kill the adapter.
+        let sessionOpened = false;
         // Build role list for prompt
         const roleList = this.buildRoleListString(swarm);
         const systemPrompt = buildRolePrompt(definition, instanceId, roleList, {
@@ -451,29 +631,107 @@ export class SwarmCoordinator {
         // Spawn Claude CLI process via SessionAdapter
         // SessionManager handles memory injection (Pipeline A: memory prompt + roleId hint) via roleId
         const tools = resolveRoleTools(definition);
-        await this.sessionAdapter.createSession({
-            sessionId: roleSessionId,
-            workDir: swarm.workDir,
-            systemPrompt: finalPrompt,
-            roleId,
-            additionalDirs,
-            // Task 5: when recovering, the caller passes resumeId = role.claudeSessionId
-            // so the Claude conversation continues with `--resume`. Fresh spawns
-            // (Task 3 default) leave it undefined for a new conversation.
-            resumeId,
-            allowedTools: tools.allowedTools,
-            disallowedTools: tools.disallowedTools,
-        });
+        try {
+            await this.sessionAdapter.createSession({
+                sessionId: roleSessionId,
+                workDir: swarm.workDir,
+                systemPrompt: finalPrompt,
+                roleId,
+                additionalDirs,
+                // Task 5: when recovering, the caller passes resumeId = role.backendSessionId
+                // so the Claude conversation continues with `--resume`. Fresh spawns
+                // (Task 3 default) leave it undefined for a new conversation.
+                resumeId,
+                allowedTools: tools.allowedTools,
+                disallowedTools: tools.disallowedTools,
+                backend: definition.backend,
+                sandbox: definition.sandbox,
+            });
+            sessionOpened = true;
+        }
+        catch (err) {
+            // Wrap the underlying backend error with role context so the user can
+            // pinpoint which role failed when (for example) codex CLI is missing.
+            // M3.S5 #5 acceptance: "未装 codex CLI 时配 codex role → 启动报错指明
+            // 哪个 role 缺 codex". Without this wrap, the surfaced message is
+            // "Failed to spawn codex CLI: ENOENT" with no role identifier.
+            const backendLabel = definition.backend ?? "claude";
+            const cause = err instanceof Error ? err.message : String(err);
+            const wrapped = new Error(`role ${roleName} (${instanceId}, backend=${backendLabel}) failed to spawn: ${cause}`);
+            // Preserve original error for callers that inspect stack/cause
+            wrapped.cause = err;
+            // Dynamic-add rollback (PR#5): the caller invoked spawnRole at runtime
+            // via swarm_add_role, not as part of the initial create() batch. The
+            // outer create() does not run cleanupPartialCreate for these calls, so
+            // we MUST locally undo the in-memory mutations (role row + seq bump)
+            // and free the freshly allocated instanceId for reuse. Initial-batch
+            // callers (isDynamicAdd=false) keep the legacy behaviour where the row
+            // stays in place and cleanupPartialCreate at the create() layer tears
+            // it down on outer failure — mixing the two would double-cleanup.
+            if (isDynamicAdd) {
+                try {
+                    swarm.roles.delete(instanceId);
+                }
+                catch { /* ignore */ }
+                if (!presetInstanceId) {
+                    const cur = swarm.nextInstanceSeq.get(roleName) ?? 0;
+                    if (cur > 0)
+                        swarm.nextInstanceSeq.set(roleName, cur - 1);
+                }
+                await this.notifyMembershipChangeFailed(swarm, roleName, wrapped);
+            }
+            throw wrapped;
+        }
         roleInstance.status = "active";
         // Persistence: save snapshot after role spawned. Skipped during recover()
         // where the caller saves once at the end (avoids N writes for N roles).
         if (!swarm._suppressSnapshot) {
-            saveSwarmSnapshot(swarm);
+            try {
+                this.persistSwarm(swarm);
+            }
+            catch (err) {
+                // Dynamic-add rollback also covers persistSwarm failure — without
+                // this branch a disk-full / lockfile crash would leave an in-memory
+                // role with no snapshot, surfacing as a phantom worker on the next
+                // restart. Initial-batch callers continue to surface the error
+                // through cleanupPartialCreate.
+                if (isDynamicAdd) {
+                    if (sessionOpened) {
+                        try {
+                            await this.sessionAdapter.closeSession(roleSessionId);
+                        }
+                        catch { /* ignore */ }
+                    }
+                    try {
+                        swarm.roles.delete(instanceId);
+                    }
+                    catch { /* ignore */ }
+                    if (!presetInstanceId) {
+                        const cur = swarm.nextInstanceSeq.get(roleName) ?? 0;
+                        if (cur > 0)
+                            swarm.nextInstanceSeq.set(roleName, cur - 1);
+                    }
+                    await this.notifyMembershipChangeFailed(swarm, roleName, err);
+                }
+                throw err;
+            }
         }
         // Send swarm status update to Hub
         this.sendStatusUpdate(swarm);
         // Flush any pending inbox messages (fire-and-forget).
         void this.inboxRelay.deliver(swarmId, instanceId);
+        // Dynamic-add: notify the queen via the unified membership-change
+        // protocol so she can decide whether to dispatch the new worker.
+        // Best-effort — failure here must not unwind the spawn; the worker is
+        // already running and the swarm is in a consistent state.
+        if (isDynamicAdd) {
+            try {
+                await this.notifyMembershipChange(swarm, { added: [roleInstance] });
+            }
+            catch (err) {
+                log.warn({ err, swarmId, instanceId }, "notifyMembershipChange failed after dynamic spawn (non-fatal)");
+            }
+        }
         log.info({ swarmId, instanceId, roleName, roleId }, "role spawned");
         return roleInstance;
     }
@@ -481,9 +739,9 @@ export class SwarmCoordinator {
      * Recover a previously persisted swarm by id.
      *
      * Locates the snapshot via `listRecoverableSwarmIds()`, then for each role
-     * in the snapshot spawns a Claude session via `--resume role.claudeSessionId`
+     * in the snapshot spawns a Claude session via `--resume role.backendSessionId`
      * (when present) so the per-role conversation continues. Roles without a
-     * stored claudeSessionId start fresh.
+     * stored backendSessionId start fresh.
      *
      * After all roles are spawned, drains each role's offline inbox via
      * `inboxRelay.deliver`. Drain failures are best-effort: warn but never throw.
@@ -507,12 +765,13 @@ export class SwarmCoordinator {
         }
         // Bootstrap the swarm shell. We deliberately bypass create() because
         // create() would respawn eager roles from template defaults — losing the
-        // per-role instanceId / claudeSessionId from the snapshot.
+        // per-role instanceId / backendSessionId from the snapshot.
         const swarm = {
             id: swarmId,
             hubSessionId: snapshot.hubSessionId,
             workDir: snapshot.workDir,
             teamName: snapshot.teamName,
+            displayName: snapshot.displayName,
             roles: new Map(),
             plan: snapshot.plan ?? null,
             nextInstanceSeq: new Map(Object.entries(snapshot.nextInstanceSeq ?? {})),
@@ -523,7 +782,7 @@ export class SwarmCoordinator {
             planStatus: snapshot.planStatus ?? "none",
         };
         this.swarms.set(swarmId, swarm);
-        // Respawn each role with the same instanceId, passing claudeSessionId
+        // Respawn each role with the same instanceId, passing backendSessionId
         // through as resumeId so SessionAdapter can `--resume` the conversation.
         // Suppress per-role snapshot writes — we save once at the end with the
         // full role set (and partialRecover marker if any role failed).
@@ -531,10 +790,13 @@ export class SwarmCoordinator {
         let partialRecover = false;
         for (const r of snapshot.roles) {
             try {
-                await this.spawnRole(swarmId, r.roleName, r.currentTask, undefined, // customPrompt
-                undefined, // customDefinition
-                undefined, // additionalDirs
-                r.claudeSessionId, r.instanceId);
+                await this.spawnRole(swarmId, r.roleName, {
+                    taskPrompt: r.currentTask,
+                    resumeId: r.backendSessionId,
+                    presetInstanceId: r.instanceId,
+                    backendOverride: r.backend,
+                    sandboxOverride: r.sandbox,
+                });
             }
             catch (err) {
                 partialRecover = true;
@@ -543,7 +805,7 @@ export class SwarmCoordinator {
         }
         delete swarm._suppressSnapshot;
         swarm.partialRecover = partialRecover;
-        saveSwarmSnapshot(swarm);
+        this.persistSwarm(swarm);
         // Drain offline inboxes — best-effort per role.
         for (const role of swarm.roles.values()) {
             try {
@@ -587,7 +849,7 @@ export class SwarmCoordinator {
         await this.sessionAdapter.closeSession(role.roleSessionId);
         swarm.roles.delete(instanceId);
         // Persistence: save snapshot after role stopped
-        saveSwarmSnapshot(swarm);
+        this.persistSwarm(swarm);
         this.sendStatusUpdate(swarm);
         log.info({ swarmId, instanceId }, "role stopped");
     }
@@ -721,7 +983,7 @@ export class SwarmCoordinator {
         log.warn({ swarmId: swarm.id, instanceId: role.instanceId, roleName: role.roleName, reason }, "role crashed — flipping status and notifying queen");
         role.status = "stopped";
         try {
-            saveSwarmSnapshot(swarm);
+            this.persistSwarm(swarm);
         }
         catch (err) {
             log.warn({ err, swarmId: swarm.id }, "handleRoleCrashed: saveSwarmSnapshot failed");
@@ -969,7 +1231,7 @@ export class SwarmCoordinator {
             swarm.planReviewTimer = undefined;
         }
         swarm.planStatus = args.verdict === "approved" ? "approved" : "rejected";
-        saveSwarmSnapshot(swarm);
+        this.persistSwarm(swarm);
         this.sendStatusUpdate(swarm);
         const queen = this.findQueen(swarm);
         if (!queen) {
@@ -1224,6 +1486,60 @@ export class SwarmCoordinator {
             await this.deliverInbox(swarm, role.instanceId, msg);
         }
     }
+    /**
+     * Deliver a unified "成员变更" envelope to the queen describing one
+     * membership delta (added and/or removed roles) plus the post-change
+     * roster. Used both by the initial spawn flow (create()) and by the
+     * dynamic add path (spawnRole with isDynamicAdd:true) so queen-side
+     * handling is the same regardless of when membership changed.
+     *
+     * No-op when the swarm has no queen (e.g. mid-shutdown), matching the
+     * defensive behaviour of other helpers that target the queen.
+     */
+    async notifyMembershipChange(swarm, change) {
+        const queen = this.findQueen(swarm);
+        if (!queen)
+            return;
+        const lines = ["[系统] 成员变更："];
+        for (const r of change.added ?? []) {
+            const backend = r.definition?.backend ?? "claude";
+            const sandbox = r.definition?.sandbox ?? "workspace-write";
+            lines.push(`  + 新增 ${r.instanceId} (${r.roleName}, ${backend}, ${sandbox})`);
+        }
+        for (const id of change.removed ?? []) {
+            lines.push(`  - 移除 ${id}`);
+        }
+        lines.push("", "当前成员：", this.buildRoleListString(swarm));
+        await this.deliverInbox(swarm, queen.instanceId, {
+            from: "system",
+            type: "system",
+            data: lines.join("\n"),
+        });
+    }
+    /**
+     * Dynamic-add rollback companion to {@link notifyMembershipChange}: tell the
+     * queen a runtime "+ 添加成员" attempt failed and the roster did NOT change,
+     * so she does not sit waiting for a worker that never came online or assume
+     * her dispatch plan can target a not-yet-existent instanceId. Best-effort —
+     * any inbox failure is swallowed so the caller's `throw` (which surfaces the
+     * underlying spawn error to the UI) is preserved.
+     */
+    async notifyMembershipChangeFailed(swarm, roleName, err) {
+        try {
+            const queen = this.findQueen(swarm);
+            if (!queen)
+                return;
+            const reason = err instanceof Error ? err.message : String(err);
+            await this.deliverInbox(swarm, queen.instanceId, {
+                from: "system",
+                type: "system",
+                data: `[系统] 添加成员失败：尝试为蜂群添加 ${roleName} 角色失败，原因：${reason}。当前名单未变更。`,
+            });
+        }
+        catch (notifyErr) {
+            log.warn({ err: notifyErr, swarmId: swarm.id, roleName }, "notifyMembershipChangeFailed: deliverInbox to queen failed (non-fatal)");
+        }
+    }
     findQueen(swarm) {
         for (const role of swarm.roles.values()) {
             if (role.definition.type === "queen" && role.status !== "stopped")
@@ -1290,13 +1606,13 @@ export class SwarmCoordinator {
         if (!reviewer) {
             // No reviewer — auto-approve
             swarm.planStatus = "approved";
-            saveSwarmSnapshot(swarm);
+            this.persistSwarm(swarm);
             this.sendStatusUpdate(swarm);
             log.info({ swarmId: swarm.id }, "plan auto-approved (no reviewer)");
             return;
         }
         swarm.planStatus = "reviewing";
-        saveSwarmSnapshot(swarm);
+        this.persistSwarm(swarm);
         this.sendStatusUpdate(swarm);
         const planJson = JSON.stringify(plan, null, 2);
         await this.deliverInbox(swarm, reviewer.instanceId, {
@@ -1394,7 +1710,7 @@ ${planJson}
                 if (swarm.idleCheckCount >= swarm.maxIdleChecks) {
                     swarm.isPaused = true;
                     swarm.status = "paused";
-                    saveSwarmSnapshot(swarm);
+                    this.persistSwarm(swarm);
                     this.sendStatusUpdate(swarm);
                     await this.deliverInbox(swarm, queen.instanceId, {
                         from: "system",
@@ -1442,6 +1758,22 @@ ${planJson}
                 status: r.status,
                 currentTask: r.currentTask,
                 color: r.definition.color,
+                // CRITICAL: include backend so the hub's swarm.status handler stores
+                // the per-role backend in `crewConfig.roles` on the DB session. Hub
+                // overwrites the existing crewConfig.roles on each status update
+                // (chat-handler.ts), so omitting backend here silently corrupts the
+                // DB — any path that later recreates the swarm from crewConfig
+                // (continuation after finish, race during recovery) spawns roles
+                // with default backend=claude. Recovered codex roles were silently
+                // downgraded to claude with no error.
+                backend: r.definition.backend,
+                // Same anti-downgrade reasoning as `backend` above — without
+                // including sandbox in the wire payload, the hub's swarm.status
+                // handler writes crewConfig.roles WITHOUT sandbox, and any path
+                // that later recreates the swarm from crewConfig (continuation,
+                // race during recovery) would silently downgrade roles to the
+                // default workspace-write sandbox.
+                sandbox: r.definition.sandbox,
             })),
             plan: swarm.plan,
         };