@mclawnet/swarm 0.1.3 → 0.1.5

package/dist/swarm-coordinator.js

@@ -1,35 +1,90 @@
 import { loadRole, buildRolePrompt } from "./roles/role-loader.js";
+import { resolveRoleTools } from "./roles/role-tools.js";
 import { loadTemplate } from "./templates/template-loader.js";
-import { LocalMessageRouter } from "./message-router.js";
-import { parseSwarmActions, parsePlanFromText } from "./action-parser.js";
+import { parsePlanFromText } from "./action-parser.js";
 import { BUILTIN_ROLES, initDatabase, syncToAutoMemory } from "@mclawnet/memory";
-import { saveSwarmSnapshot, deleteSwarmSnapshot, appendMessageLog, loadSwarmSnapshot, readMessageLog } from "./persistence.js";
+import { saveSwarmSnapshot, deleteSwarmSnapshot, appendMessageLog, loadSwarmSnapshot, readMessageLog, listRecoverableSwarmIds } from "./persistence.js";
 import { runRetrospective } from "./retrospective.js";
+import { InboxRelay } from "./inbox-relay.js";
+import { InboxStore } from "./inbox-store.js";
+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 { existsSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { createLogger } from "@mclawnet/logger";
-import { randomUUID } from "node:crypto";
 const log = createLogger({ module: "swarm" });
 const QUEEN_CHECK_INTERVAL_MS = 300_000; // 5min when workers active
 const QUEEN_CHECK_IDLE_INTERVAL_MS = 300_000; // 5min when all roles idle
-const SEND_MAX_RETRIES = 3;
-const SEND_RETRY_BASE_MS = 1_000; // 1s, 2s, 4s exponential backoff
-const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/**
+ * Hard deadline for the "reviewing" plan-status. If the reviewer fails to
+ * submit a verdict within this window the coordinator auto-approves with a
+ * warning so the queen is not deadlocked. Cleared on any explicit
+ * submitPlanReview call.
+ */
+const PLAN_REVIEW_TIMEOUT_MS = 10 * 60 * 1000;
 /**
  * SwarmCoordinator — orchestrates multi-role Claude CLI swarms.
  *
  * Composes (not replaces) SessionAdapter. Each role instance is a separate
- * session in SessionAdapter. Communication between roles goes through
- * MessageRouter (currently LocalMessageRouter using stdin/stdout).
+ * session in SessionAdapter. Communication between roles flows through
+ * file-based InboxStore + InboxRelay.
  */
 export class SwarmCoordinator {
     sessionAdapter;
     hub;
+    taskStoreFactory;
+    home;
     swarms = new Map();
-    constructor(sessionAdapter, hub) {
+    inboxRelay;
+    inboxWatcher;
+    constructor(sessionAdapter, hub, 
+    /**
+     * Optional factory that resolves a per-swarm TaskStore (workDir-scoped).
+     * When present, spawnRole appends a "### 任务上下文" briefing section to
+     * the role's system prompt. Failures are best-effort logged.
+     *
+     * Backward compat: also accepts a pre-built single TaskStore instance.
+     */
+    taskStoreFactory, 
+    /**
+     * Optional override for the user-home root (no `.clawnet` suffix).
+     * Threaded to InboxRelay and to inline `new InboxStore(...)` / `TaskStore`
+     * calls so test harnesses pinned to a tmpdir don't fall through to
+     * `homedir()` and write files into the real `~/.clawnet`. When omitted,
+     * inline call sites still honour `CLAWNET_HOME` env var as before.
+     */
+    home) {
         this.sessionAdapter = sessionAdapter;
         this.hub = hub;
+        this.taskStoreFactory = taskStoreFactory;
+        this.home = home;
+        this.inboxRelay = new InboxRelay(sessionAdapter, (id) => this.swarms.get(id), (swarmId, instanceId, msg) => this.handleInterceptedMessage(swarmId, instanceId, msg), home);
+        this.inboxWatcher = new InboxWatcher(this.inboxRelay);
+    }
+    /** Resolve the user-home root used for InboxStore / TaskStore lookups. */
+    resolveHome() {
+        return this.home ?? process.env.CLAWNET_HOME ?? homedir();
+    }
+    /**
+     * Resolve the TaskStore for a given swarm's workDir.
+     * Returns undefined if no factory was wired or if the factory returned undefined.
+     */
+    resolveTaskStore(workDir) {
+        if (!this.taskStoreFactory)
+            return undefined;
+        if (typeof this.taskStoreFactory === "function") {
+            try {
+                return this.taskStoreFactory(workDir);
+            }
+            catch (err) {
+                log.warn({ err, workDir }, "taskStoreFactory threw — skipping briefing");
+                return undefined;
+            }
+        }
+        return this.taskStoreFactory;
     }
     // ── Public API ──────────────────────────────────────────────────────
     /** Create a new swarm with two-phase initialization. */
@@ -46,11 +101,11 @@ export class SwarmCoordinator {
         else {
             roleSpecs = options.roles ?? [];
         }
-        const router = new LocalMessageRouter(this.sessionAdapter);
         const swarm = {
             id: swarmSessionId,
             hubSessionId: swarmSessionId,
             workDir: options.workDir,
+            teamName: options.templateName,
             roles: new Map(),
             plan: null,
             nextInstanceSeq: new Map(),
@@ -60,66 +115,89 @@ export class SwarmCoordinator {
             status: "creating",
             planStatus: "none",
         };
-        // Attach the router to the swarm for internal access
-        swarm._router = router;
         // Store pending role specs for on-demand spawning
         swarm._pendingRoleSpecs = roleSpecs;
         this.swarms.set(swarmSessionId, swarm);
-        // ── Phase 1: spawn eager roles (non-queen first, queen last) ────
-        const eagerSpecs = roleSpecs.filter((r) => r.roleName === "queen" || r.eager === true);
-        // Sort: queen last so her roleList includes all already-spawned roles
-        eagerSpecs.sort((a, b) => {
-            if (a.roleName === "queen")
-                return 1;
-            if (b.roleName === "queen")
-                return -1;
-            return 0;
-        });
-        for (const spec of eagerSpecs) {
-            const count = spec.count ?? 1;
-            for (let i = 0; i < count; i++) {
-                await this.spawnRole(swarmSessionId, spec.roleName, router, undefined, spec.customPrompt, spec.customDefinition);
-            }
-        }
-        // Start Queen periodic check
-        this.startQueenCheck(swarmSessionId);
-        // ── Phase 2: mark running + notify queen + send task ────────────
-        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
-            router.send(queen.instanceId, {
-                from: "system",
-                type: "system",
-                data: `[系统] 蜂群初始化完成。当前成员：\n${roleList}\n\n等待任务分配。`,
-                timestamp: Date.now(),
+        // Snapshot may already exist from a prior run (continuation, or
+        // restart-after-crash with the same swarmId). Record this BEFORE any
+        // spawnRole writes a new one — cleanup must not delete what wasn't ours.
+        const snapshotPreexisted = options.workDir
+            ? existsSync(join(projectRoot(options.workDir, this.resolveHome()), "swarms", swarmSessionId, "recovery.json"))
+            : false;
+        // Track opened sessions so cleanupPartialCreate() can close them on failure.
+        const openedSessionIds = [];
+        const trackOpen = (role) => {
+            if (role?.roleSessionId)
+                openedSessionIds.push(role.roleSessionId);
+        };
+        try {
+            // ── Phase 1: spawn eager roles (non-queen first, queen last) ────
+            const eagerSpecs = roleSpecs.filter((r) => r.roleName === "queen" || r.eager === true);
+            // Sort: queen last so her roleList includes all already-spawned roles
+            eagerSpecs.sort((a, b) => {
+                if (a.roleName === "queen")
+                    return 1;
+                if (b.roleName === "queen")
+                    return -1;
+                return 0;
             });
-            // Inject continuation context from previous run if applicable
-            if (options.isContinuation) {
-                const summary = this.buildContinuationSummary(swarmSessionId);
-                if (summary) {
-                    router.send(queen.instanceId, {
-                        from: "system",
-                        type: "system",
-                        data: `[系统] 这是对之前蜂群任务的继续。以下是之前的工作摘要：\n${summary}\n\n请基于已有成果继续执行新的改进指令。`,
-                        timestamp: Date.now(),
-                    });
+            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);
+                    trackOpen(role);
                 }
             }
-            // Send user task
-            if (options.task) {
-                router.send(queen.instanceId, {
-                    from: "user",
-                    type: "task",
-                    data: options.task,
-                    timestamp: Date.now(),
+            // Start Queen periodic check
+            this.startQueenCheck(swarmSessionId);
+            // ── Phase 2: mark running + notify queen + send task ────────────
+            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等待任务分配。`,
                 });
+                // Inject continuation context from previous run if applicable
+                if (options.isContinuation) {
+                    const summary = this.buildContinuationSummary(swarmSessionId);
+                    if (summary) {
+                        await this.deliverInbox(swarm, queen.instanceId, {
+                            from: "system",
+                            type: "system",
+                            data: `[系统] 这是对之前蜂群任务的继续。以下是之前的工作摘要：\n${summary}\n\n请基于已有成果继续执行新的改进指令。`,
+                        });
+                    }
+                }
+                // Send user task
+                if (options.task) {
+                    await this.deliverInbox(swarm, queen.instanceId, {
+                        from: "user",
+                        type: "task",
+                        data: options.task,
+                    });
+                }
+            }
+            log.info({ swarmId: swarmSessionId, roleCount: swarm.roles.size }, "swarm created");
+            // Persistence: save initial snapshot
+            saveSwarmSnapshot(swarm);
+            // Start inbox watcher to react to inbox file changes (best-effort).
+            if (options.workDir) {
+                try {
+                    this.inboxWatcher.watch(swarmSessionId, options.workDir);
+                }
+                catch (err) {
+                    log.warn({ err, swarmId: swarmSessionId }, "inboxWatcher.watch failed (best-effort)");
+                }
             }
         }
-        log.info({ swarmId: swarmSessionId, roleCount: swarm.roles.size }, "swarm created");
-        // Persistence: save initial snapshot
-        saveSwarmSnapshot(swarm);
+        catch (err) {
+            await this.cleanupPartialCreate(swarmSessionId, openedSessionIds, snapshotPreexisted, err);
+            throw err;
+        }
     }
     /** Handle user message directed at the swarm. */
     async handleUserMessage(swarmSessionId, content, targetInstance) {
@@ -128,12 +206,10 @@ export class SwarmCoordinator {
             log.error({ swarmId: swarmSessionId }, "handleUserMessage: swarm not found");
             return;
         }
-        const router = swarm._router;
         const message = {
             from: "user",
             type: "task",
             data: content,
-            timestamp: Date.now(),
         };
         // Auto-resume if paused
         if (swarm.status === "paused") {
@@ -142,21 +218,28 @@ export class SwarmCoordinator {
             swarm.idleCheckCount = 0;
             this.startQueenCheck(swarmSessionId);
             log.info({ swarmId: swarmSessionId }, "swarm resumed");
+            for (const r of swarm.roles.values()) {
+                if (r.status === "spawning" || r.status === "stopped")
+                    continue;
+                void this.inboxRelay.deliver(swarmSessionId, r.instanceId);
+            }
         }
         if (targetInstance) {
             // Directed at a specific instance
-            router.send(targetInstance, message);
-            appendMessageLog(swarmSessionId, { type: "user_message", from: "user", to: targetInstance, data: content, timestamp: Date.now() });
+            await this.deliverInbox(swarm, targetInstance, message);
+            if (swarm.workDir) {
+                appendMessageLog(swarm.workDir, swarmSessionId, { type: "user_message", from: "user", to: targetInstance, data: content, timestamp: Date.now() });
+            }
         }
         else {
             // Default: send to Queen
             const queen = this.findQueen(swarm);
             if (queen) {
-                router.send(queen.instanceId, message);
+                await this.deliverInbox(swarm, queen.instanceId, message);
             }
             else {
                 // No queen — broadcast to all
-                router.broadcast(message);
+                await this.broadcastInbox(swarm, message);
             }
         }
     }
@@ -170,14 +253,22 @@ export class SwarmCoordinator {
         const { swarm, role } = this.findByRoleSessionId(roleSessionId);
         if (!swarm || !role)
             return false;
-        const router = swarm._router;
         // Extract text content from the streaming event
         const text = extractTextFromEvent(data);
         // Parse swarm action blocks
         if (text) {
-            // Log when assistant event contains meaningful text (not every streaming chunk)
-            if (text.includes("```swarm")) {
-                log.info({ instanceId: role.instanceId, textLen: text.length }, "assistant output contains swarm block");
+            // Legacy-format safety net: if a reviewer regresses to the old
+            // `{"action":"report", "taskId":"plan_review", ...}` block while we are
+            // waiting on a verdict, warn loudly so the regression is diagnosable.
+            // The action-parser no longer consumes these blocks, so the swarm would
+            // otherwise silently wait until the 10-min auto-approve timer fires.
+            // We do NOT try to translate the block — reviewer must call
+            // `mcp__clawnet__plan_review_submit` instead. See PR plan-review-mcp-migration.
+            if (role.roleName === "reviewer" &&
+                swarm.planStatus === "reviewing" &&
+                /"action"\s*:\s*"report"/.test(text) &&
+                /"taskId"\s*:\s*"plan_review"/.test(text)) {
+                log.warn({ swarmId: swarm.id, instanceId: role.instanceId }, 'reviewer emitted legacy {"action":"report","taskId":"plan_review"} block — ignored. Call mcp__clawnet__plan_review_submit instead.');
             }
             // For queen: parse plan BEFORE executing actions, so review can gate task assignment
             if (role.definition.type === "queen") {
@@ -192,27 +283,14 @@ export class SwarmCoordinator {
                     saveSwarmSnapshot(swarm);
                     this.sendStatusUpdate(swarm);
                     log.info({ swarmId: swarm.id, instanceId: role.instanceId }, "plan updated (draft)");
-                    this.requestPlanReview(swarm, plan);
+                    this.requestPlanReview(swarm, plan).catch((err) => {
+                        log.warn({ err, swarmId: swarm.id }, "requestPlanReview failed (best-effort)");
+                    });
                 }
                 else if (hasPlanKeyword) {
                     log.warn({ instanceId: role.instanceId, textSnippet: text.substring(0, 500) }, "queen output has plan keyword but parsePlanFromText returned null");
                 }
             }
-            const { actions } = parseSwarmActions(text);
-            if (text.includes("```swarm") && actions.length === 0) {
-                log.warn({ instanceId: role.instanceId, textSnippet: text.substring(0, 500) }, "swarm block found but parse failed");
-            }
-            // Execute actions sequentially — spawn must complete before subsequent sends
-            (async () => {
-                for (const action of actions) {
-                    try {
-                        await this.executeAction(swarm, role, router, action);
-                    }
-                    catch (err) {
-                        log.error({ err, swarmId: swarm.id, action: action.action }, "executeAction failed");
-                    }
-                }
-            })();
         }
         // Forward full output to Hub for UI display + DB storage
         this.hub.send({
@@ -234,6 +312,22 @@ export class SwarmCoordinator {
             return false;
         // Update role status
         role.status = "idle";
+        // Persist per-role claudeSessionId — 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;
+            // saveSwarmSnapshot is sync-fire (proper-lockfile internally async);
+            // call directly — failures should not break turn completion.
+            try {
+                saveSwarmSnapshot(swarm);
+            }
+            catch (err) {
+                log.warn({ err, swarmId: swarm.id, instanceId: role.instanceId }, "failed to persist claudeSessionId on turn complete");
+            }
+        }
+        // Settle inbox echoes for this turn (fire-and-forget).
+        void this.inboxRelay.onAgentTurnSettled(swarm.id, role.instanceId);
         // Forward to Hub
         this.hub.send({
             type: "swarm.turn_complete",
@@ -245,8 +339,38 @@ export class SwarmCoordinator {
         });
         return true;
     }
+    /**
+     * Persist the per-role claudeSessionId 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) {
+        const swarm = this.swarms.get(swarmId);
+        if (!swarm)
+            return false;
+        const role = swarm.roles.get(instanceId);
+        if (!role)
+            return false;
+        if (role.claudeSessionId === claudeSessionId)
+            return true;
+        role.claudeSessionId = claudeSessionId;
+        try {
+            saveSwarmSnapshot(swarm);
+        }
+        catch (err) {
+            log.warn({ err, swarmId, instanceId }, "failed to persist claudeSessionId");
+        }
+        return true;
+    }
+    /** Convenience: same as setRoleClaudeSessionId but takes the `${swarmId}::${instanceId}` roleSessionId. */
+    setRoleClaudeSessionIdBySession(roleSessionId, claudeSessionId) {
+        const { swarm, role } = this.findByRoleSessionId(roleSessionId);
+        if (!swarm || !role)
+            return false;
+        return this.setRoleClaudeSessionId(swarm.id, role.instanceId, claudeSessionId);
+    }
     /** Spawn a new role instance in a swarm. */
-    async spawnRole(swarmId, roleName, router, taskPrompt, customPrompt, customDefinition, additionalDirs) {
+    async spawnRole(swarmId, roleName, taskPrompt, customPrompt, customDefinition, additionalDirs, resumeId, presetInstanceId) {
         const swarm = this.swarms.get(swarmId);
         if (!swarm)
             throw new Error(`Swarm ${swarmId} not found`);
@@ -270,9 +394,17 @@ export class SwarmCoordinator {
         if (customPrompt) {
             definition.promptBody = customPrompt;
         }
-        const seq = swarm.nextInstanceSeq.get(roleName) ?? 0;
-        swarm.nextInstanceSeq.set(roleName, seq + 1);
-        const instanceId = `${definition.shortName}-${seq}`;
+        let instanceId;
+        if (presetInstanceId) {
+            // Recovery path: preserve the original instanceId so per-role state
+            // (logs, inbox, claudeSessionId) lines up with prior snapshot.
+            instanceId = presetInstanceId;
+        }
+        else {
+            const seq = swarm.nextInstanceSeq.get(roleName) ?? 0;
+            swarm.nextInstanceSeq.set(roleName, seq + 1);
+            instanceId = `${definition.shortName}-${seq}`;
+        }
         const roleSessionId = `${swarmId}::${instanceId}`;
         const roleInstance = {
             instanceId,
@@ -281,32 +413,159 @@ export class SwarmCoordinator {
             roleSessionId,
             status: "spawning",
             currentTask: taskPrompt,
+            claudeSessionId: resumeId,
         };
         swarm.roles.set(instanceId, roleInstance);
         // Build role list for prompt
         const roleList = this.buildRoleListString(swarm);
-        const systemPrompt = buildRolePrompt(definition, instanceId, roleList);
+        const systemPrompt = buildRolePrompt(definition, instanceId, roleList, {
+            swarmId,
+            workDir: swarm.workDir,
+        });
         const roleId = BUILTIN_ROLES[roleName]?.id ?? `role-${roleName}`;
+        // Boot-time briefing injection (Phase 7-E). Best-effort: failures here
+        // must not abort role spawn — log and continue with the bare prompt.
+        let finalPrompt = systemPrompt;
+        const taskStore = swarm.workDir
+            ? this.resolveTaskStore(swarm.workDir)
+            : undefined;
+        if (taskStore) {
+            try {
+                const briefingSection = this.buildBriefingSection(taskStore, swarmId, instanceId, definition);
+                if (briefingSection)
+                    finalPrompt = systemPrompt + "\n\n" + briefingSection;
+            }
+            catch (err) {
+                log.warn({ err, instanceId }, "briefing injection failed (non-fatal)");
+            }
+        }
         // 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,
+            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,
         });
         roleInstance.status = "active";
-        // Persistence: save snapshot after role spawned
-        saveSwarmSnapshot(swarm);
-        // Register in router
-        const r = router ?? swarm._router;
-        r.register(instanceId, { kind: "local", roleSessionId });
+        // 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);
+        }
         // Send swarm status update to Hub
         this.sendStatusUpdate(swarm);
+        // Flush any pending inbox messages (fire-and-forget).
+        void this.inboxRelay.deliver(swarmId, instanceId);
         log.info({ swarmId, instanceId, roleName, roleId }, "role spawned");
         return roleInstance;
     }
+    /**
+     * 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`
+     * (when present) so the per-role conversation continues. Roles without a
+     * stored claudeSessionId 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.
+     *
+     * Recovered swarms start in `paused` state — caller must explicitly resume
+     * (matches existing behaviour in `recoverSwarm` helper).
+     */
+    async recover(swarmId) {
+        if (this.swarms.has(swarmId)) {
+            log.warn({ swarmId }, "recover: swarm already loaded — skipping");
+            return;
+        }
+        // Locate snapshot file across all known project workDirs.
+        const entry = listRecoverableSwarmIds().find((e) => e.swarmId === swarmId);
+        if (!entry) {
+            throw new Error(`recover: no snapshot found for swarm ${swarmId}`);
+        }
+        const snapshot = loadSwarmSnapshot(entry.workDir, swarmId);
+        if (!snapshot) {
+            throw new Error(`recover: snapshot for ${swarmId} could not be loaded`);
+        }
+        // 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.
+        const swarm = {
+            id: swarmId,
+            hubSessionId: snapshot.hubSessionId,
+            workDir: snapshot.workDir,
+            teamName: snapshot.teamName,
+            roles: new Map(),
+            plan: snapshot.plan ?? null,
+            nextInstanceSeq: new Map(Object.entries(snapshot.nextInstanceSeq ?? {})),
+            idleCheckCount: 0,
+            maxIdleChecks: 10,
+            isPaused: true,
+            status: "paused",
+            planStatus: snapshot.planStatus ?? "none",
+        };
+        this.swarms.set(swarmId, swarm);
+        // Respawn each role with the same instanceId, passing claudeSessionId
+        // 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).
+        swarm._suppressSnapshot = true;
+        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);
+            }
+            catch (err) {
+                partialRecover = true;
+                log.warn({ err, swarmId, instanceId: r.instanceId }, "recover: failed to spawn role");
+            }
+        }
+        delete swarm._suppressSnapshot;
+        swarm.partialRecover = partialRecover;
+        saveSwarmSnapshot(swarm);
+        // Drain offline inboxes — best-effort per role.
+        for (const role of swarm.roles.values()) {
+            try {
+                await this.inboxRelay.deliver(swarmId, role.instanceId);
+            }
+            catch (err) {
+                log.warn({ err, swarmId, instanceId: role.instanceId }, "recover: inbox drain failed (best-effort)");
+            }
+        }
+        log.info({ swarmId, roleCount: swarm.roles.size }, "swarm recovered");
+        // Re-arm plan-review timeout on recovery: planReviewTimer is runtime-only
+        // (see types.ts), so a snapshot persisted while planStatus="reviewing"
+        // would otherwise resume with no timer and deadlock the queen indefinitely
+        // if the reviewer never replies. Re-arm with the full PLAN_REVIEW_TIMEOUT_MS
+        // (we don't persist the original deadline; worst case the swarm waits one
+        // additional timeout window past restart, which is bounded — vs. the
+        // previous unbounded hang).
+        if (swarm.planStatus === "reviewing") {
+            this.armPlanReviewTimeout(swarm);
+            log.info({ swarmId, timeoutMs: PLAN_REVIEW_TIMEOUT_MS }, "recover: re-armed plan_review timeout");
+        }
+        // Start inbox watcher for the recovered swarm (best-effort).
+        if (swarm.workDir) {
+            try {
+                this.inboxWatcher.watch(swarmId, swarm.workDir);
+            }
+            catch (err) {
+                log.warn({ err, swarmId }, "inboxWatcher.watch failed (best-effort)");
+            }
+        }
+    }
     /** Stop a role instance. */
     async stopRole(swarmId, instanceId) {
         const swarm = this.swarms.get(swarmId);
@@ -316,8 +575,6 @@ export class SwarmCoordinator {
         if (!role)
             return;
         role.status = "stopped";
-        const router = swarm._router;
-        router.unregister(instanceId);
         await this.sessionAdapter.closeSession(role.roleSessionId);
         swarm.roles.delete(instanceId);
         // Persistence: save snapshot after role stopped
@@ -325,6 +582,68 @@ export class SwarmCoordinator {
         this.sendStatusUpdate(swarm);
         log.info({ swarmId, instanceId }, "role stopped");
     }
+    /**
+     * Roll back side-effects from a partially-completed `create()`.
+     *
+     * Called from create()'s catch block. Mirrors `destroy()` but is
+     * deliberately tolerant of partial state (timer may not exist, snapshot
+     * may not exist, sessions list comes from the caller's accumulator
+     * because `swarm.roles` may not yet contain every opened session).
+     *
+     * Best-effort: every step is wrapped — we never throw out of cleanup.
+     * Logs a warn so operators see WHY a swarm was rolled back.
+     */
+    async cleanupPartialCreate(swarmId, openedSessionIds, snapshotPreexisted, cause) {
+        const swarm = this.swarms.get(swarmId);
+        // 1. Stop the queen check timer if it was started.
+        if (swarm?.checkTimer) {
+            try {
+                clearTimeout(swarm.checkTimer);
+            }
+            catch { /* ignore */ }
+            swarm.checkTimer = undefined;
+        }
+        if (swarm?.planReviewTimer) {
+            try {
+                clearTimeout(swarm.planReviewTimer);
+            }
+            catch { /* ignore */ }
+            swarm.planReviewTimer = undefined;
+        }
+        // 2. Close every Claude session we managed to open.
+        for (const sid of openedSessionIds) {
+            try {
+                await this.sessionAdapter.closeSession(sid);
+            }
+            catch (err) {
+                log.warn({ err, swarmId, sessionId: sid }, "cleanupPartialCreate: closeSession failed");
+            }
+        }
+        // 3. Delete recovery.json ONLY if this create() call wrote it.
+        //    If a snapshot existed before we started (continuation path, or
+        //    agent restart while a previous snapshot is still on disk),
+        //    leave it untouched — it belongs to a prior run.
+        if (swarm?.workDir) {
+            if (!snapshotPreexisted) {
+                try {
+                    deleteSwarmSnapshot(swarm.workDir, swarmId);
+                }
+                catch (err) {
+                    log.warn({ err, swarmId }, "cleanupPartialCreate: deleteSwarmSnapshot failed");
+                }
+            }
+            else {
+                log.warn({ swarmId }, "cleanupPartialCreate: preserved pre-existing recovery.json");
+            }
+        }
+        // 4. Remove from in-memory registry so the same id can be retried.
+        try {
+            this.inboxWatcher.unwatch(swarmId);
+        }
+        catch { /* ignore */ }
+        this.swarms.delete(swarmId);
+        log.warn({ swarmId, openedCount: openedSessionIds.length, snapshotPreexisted, err: cause instanceof Error ? cause.message : String(cause) }, "cleanupPartialCreate: rolled back partial swarm state");
+    }
     /** Destroy an entire swarm. */
     async destroy(swarmId) {
         const swarm = this.swarms.get(swarmId);
@@ -332,12 +651,30 @@ export class SwarmCoordinator {
             return;
         if (swarm.checkTimer)
             clearTimeout(swarm.checkTimer);
+        if (swarm.planReviewTimer) {
+            clearTimeout(swarm.planReviewTimer);
+            swarm.planReviewTimer = undefined;
+        }
         for (const role of swarm.roles.values()) {
             await this.sessionAdapter.closeSession(role.roleSessionId).catch(() => { });
         }
+        // Detach tasks before removing the snapshot — keeps task index consistent
+        // even if snapshot deletion fails. Best-effort: never block destroy.
+        await this.detachTasks(swarmId, swarm.workDir);
+        try {
+            this.inboxWatcher.unwatch(swarmId);
+        }
+        catch (err) {
+            log.warn({ err, swarmId }, "inboxWatcher.unwatch failed (best-effort)");
+        }
         this.swarms.delete(swarmId);
         // Persistence: remove snapshot
-        deleteSwarmSnapshot(swarmId);
+        if (swarm.workDir) {
+            deleteSwarmSnapshot(swarm.workDir, swarmId);
+        }
+        else {
+            log.warn({ swarmId }, "destroy: swarm.workDir missing, cannot delete snapshot");
+        }
         log.info({ swarmId }, "swarm destroyed");
     }
     /** Check if a session ID belongs to any swarm. */
@@ -363,6 +700,10 @@ export class SwarmCoordinator {
             clearTimeout(swarm.checkTimer);
             swarm.checkTimer = undefined;
         }
+        if (swarm.planReviewTimer) {
+            clearTimeout(swarm.planReviewTimer);
+            swarm.planReviewTimer = undefined;
+        }
         await this.runRetroAndCleanup(swarmId, swarm);
         log.info({ swarmId }, "swarm completed — all resources released");
     }
@@ -377,16 +718,204 @@ export class SwarmCoordinator {
             clearTimeout(swarm.checkTimer);
             swarm.checkTimer = undefined;
         }
+        if (swarm.planReviewTimer) {
+            clearTimeout(swarm.planReviewTimer);
+            swarm.planReviewTimer = undefined;
+        }
         await this.runRetroAndCleanup(swarmId, swarm);
         log.info({ swarmId }, "swarm failed — all resources released");
     }
+    /**
+     * InboxRelay messageInterceptor hook. Consumes `plan_review_result`
+     * envelopes (written by the `plan_review_submit` MCP tool out-of-process)
+     * and converts them into the normalized `submitPlanReview()` flow:
+     * planStatus flip, timer clear, plan_approved/plan_rejected to queen.
+     *
+     * Returning `true` removes the raw message from the LLM payload and marks
+     * it delivered so it doesn't re-fire. Returning `false` lets the relay
+     * push the message normally.
+     *
+     * Failures (parse error, invalid verdict) are logged + consumed to avoid a
+     * tight reload loop on a malformed file. The submitPlanReview call is
+     * idempotent so duplicate reviewer envelopes (e.g. retries) are safe.
+     */
+    async handleInterceptedMessage(swarmId, instanceId, msg) {
+        if (msg.type !== "plan_review_result")
+            return false;
+        // Authorization: only reviewer instances may flip planStatus via this path.
+        // The MCP tool's `from.startsWith("reviewer")` guard is advisory across the
+        // process boundary — a malicious worker could call `message_send` directly
+        // with type:"plan_review_result". Enforce again here so the interceptor is
+        // the actual source of truth, mirroring the server-side check in the
+        // `plan_review_submit` tool handler.
+        //
+        // We deliberately do NOT allow `from: "system"` here: the timeout fallback
+        // calls `submitPlanReview` directly in-process, never via the inbox, so
+        // accepting "system" here would only widen the spoofing surface (any worker
+        // with `message_send` could forge `from:"system"` since `message_send` does
+        // not authenticate the sender).
+        if (!msg.from.startsWith("reviewer")) {
+            log.warn({ swarmId, instanceId, msgId: msg.id, from: msg.from }, "plan_review_result interceptor: rejected non-reviewer sender — consuming");
+            return true;
+        }
+        // Two-stage parse:
+        //   1. Try the canonical JSON envelope (what the `plan_review_submit` MCP
+        //      tool always emits): `{ verdict, body }`.
+        //   2. Fall back to a markdown regex `^verdict:\s*(approved|rejected)`
+        //      against the raw `data`. Reviewers in misconfigured environments
+        //      (e.g. their Claude session is missing the clawnet-mcp tools because
+        //      of the legacy mcp.json bug fixed in PR #102) sometimes hand-write a
+        //      plan_review_result envelope by direct file write, leaving `data`
+        //      as a markdown blob. Without this fallback the verdict is lost and
+        //      the swarm waits the full 10-minute timeout.
+        //
+        // Spoofing surface is unchanged: the from-prefix check above runs BEFORE
+        // either parse path, so a malicious worker cannot forge an approval just
+        // by writing markdown.
+        let verdict;
+        let body = "";
+        try {
+            const parsed = JSON.parse(msg.data);
+            if (parsed.verdict === "approved" || parsed.verdict === "rejected") {
+                verdict = parsed.verdict;
+                body = typeof parsed.body === "string" ? parsed.body : "";
+            }
+        }
+        catch {
+            // Fall through to markdown fallback below.
+        }
+        if (!verdict && typeof msg.data === "string") {
+            const m = msg.data.match(/^\s*verdict\s*:\s*(approved|rejected)\b/im);
+            if (m) {
+                verdict = m[1].toLowerCase();
+                // Carry the entire markdown blob as the body so the queen sees the
+                // reviewer's full commentary, not just the verdict line.
+                body = msg.data;
+                log.info({ swarmId, instanceId, msgId: msg.id, verdict }, "plan_review_result interceptor: markdown verdict fallback used");
+            }
+        }
+        if (!verdict) {
+            log.warn({ swarmId, instanceId, msgId: msg.id }, "plan_review_result interceptor: no parsable verdict (neither JSON nor markdown) — consuming");
+            return true;
+        }
+        // IMPORTANT: schedule submitPlanReview asynchronously instead of awaiting.
+        // The interceptor runs *inside* InboxRelay.runDeliver for (swarmId, queen),
+        // and submitPlanReview internally calls deliverInbox → inboxRelay.deliver
+        // for the same (swarmId, queen). Single-flight would coalesce that nested
+        // call onto the in-flight promise we are currently inside, and awaiting it
+        // here would deadlock. Returning true synchronously consumes the message
+        // so the outer runDeliver can finish, releasing the single-flight slot
+        // before the deferred submitPlanReview resumes and fires its delivery.
+        void this.submitPlanReview({
+            swarmId,
+            from: msg.from,
+            verdict,
+            body,
+        }).catch((err) => log.warn({ err, swarmId, instanceId, msgId: msg.id, verdict }, "plan_review_result interceptor: deferred submitPlanReview failed"));
+        return true;
+    }
+    /**
+     * Apply a plan review verdict from a reviewer (or system on timeout).
+     * Idempotent: when planStatus is already "approved" or "rejected", logs and
+     * returns. Clears any pending planReviewTimer.
+     *
+     * Wired to the `plan_review_submit` MCP tool by the host (Task 3); this
+     * method itself does not call back into MCP.
+     */
+    async submitPlanReview(args) {
+        const swarm = this.swarms.get(args.swarmId);
+        if (!swarm)
+            throw new Error(`swarm not found: ${args.swarmId}`);
+        // Idempotency guard — a late reviewer submission after the timeout fired,
+        // or a duplicate MCP call, must not double-notify the queen.
+        if (swarm.planStatus === "approved" || swarm.planStatus === "rejected") {
+            log.warn({
+                swarmId: args.swarmId,
+                currentStatus: swarm.planStatus,
+                attemptedVerdict: args.verdict,
+            }, "plan review already finalised, ignoring duplicate submission");
+            return;
+        }
+        if (swarm.planStatus !== "reviewing") {
+            // Refuse out-of-band submissions (planStatus = none / draft / approved /
+            // rejected). The `approved` / `rejected` cases were already short-circuited
+            // above; the remaining states (`none`, `draft`) mean either the queen has
+            // not yet asked for review (premature/spoofed call), or the swarm is in a
+            // state where flipping planStatus would silently overwrite real progress.
+            // No-op + warn instead of "proceeding anyway" so a misbehaving reviewer
+            // can't corrupt state by submitting before requestPlanReview ever ran.
+            log.warn({ swarmId: args.swarmId, currentStatus: swarm.planStatus, attemptedVerdict: args.verdict, from: args.from }, "submitPlanReview: planStatus !== reviewing — refusing to apply verdict");
+            return;
+        }
+        if (swarm.planReviewTimer) {
+            clearTimeout(swarm.planReviewTimer);
+            swarm.planReviewTimer = undefined;
+        }
+        swarm.planStatus = args.verdict === "approved" ? "approved" : "rejected";
+        saveSwarmSnapshot(swarm);
+        this.sendStatusUpdate(swarm);
+        const queen = this.findQueen(swarm);
+        if (!queen) {
+            log.warn({ swarmId: args.swarmId, verdict: args.verdict }, "submitPlanReview: no queen found — verdict recorded but queen not notified");
+            return;
+        }
+        const messageType = args.verdict === "approved" ? "plan_approved" : "plan_rejected";
+        const data = JSON.stringify({
+            verdict: args.verdict,
+            body: args.body ?? "",
+            from: args.from,
+        });
+        await this.deliverInbox(swarm, queen.instanceId, {
+            from: "system",
+            type: messageType,
+            data,
+        });
+        log.info({ swarmId: args.swarmId, verdict: args.verdict, from: args.from }, "plan review submitted");
+    }
+    /**
+     * Defensive recovery: re-emit plan_approved / plan_rejected to the queen if
+     * planStatus is finalised but no matching system envelope exists in the
+     * queen's inbox. Called from the queen check-in tick.
+     *
+     * Catches the case where the deferred submitPlanReview's call to
+     * deliverInbox() threw (e.g. transient fs error or lockfile contention) and
+     * only logged a warning — leaving planStatus = "approved" but the queen
+     * never receiving plan_approved, which would otherwise wedge the swarm.
+     *
+     * Idempotent: if a system plan_approved/plan_rejected already exists in the
+     * queen inbox (delivered or undelivered), we do nothing.
+     */
+    async reconcilePlanStatusForQueen(swarm, queenInstanceId) {
+        if (swarm.planStatus !== "approved" && swarm.planStatus !== "rejected") {
+            return;
+        }
+        if (!swarm.workDir)
+            return;
+        const expectedType = swarm.planStatus === "approved" ? "plan_approved" : "plan_rejected";
+        const store = new InboxStore(swarm.workDir, swarm.id, this.resolveHome());
+        const queueAll = await store.readAll(queenInstanceId);
+        const existing = queueAll.find((m) => m.type === expectedType && m.from === "system");
+        if (existing)
+            return; // Already delivered (or queued).
+        log.warn({ swarmId: swarm.id, planStatus: swarm.planStatus }, `reconcilePlanStatus: queen missing ${expectedType} despite finalised planStatus — re-emitting`);
+        const data = JSON.stringify({
+            verdict: swarm.planStatus,
+            body: "[reconcile] previous notification was lost; re-issued by queen check-in",
+            from: "system",
+        });
+        await this.deliverInbox(swarm, queenInstanceId, {
+            from: "system",
+            type: expectedType,
+            data,
+        });
+    }
     // ── Private helpers ─────────────────────────────────────────────────
     /** Run retrospective analysis then clean up swarm resources. */
     async runRetroAndCleanup(swarmId, swarm) {
         // 1. Run retrospective (best-effort)
         try {
-            const messages = readMessageLog(swarmId);
-            const snapshot = loadSwarmSnapshot(swarmId);
+            const messages = swarm.workDir ? readMessageLog(swarm.workDir, swarmId) : [];
+            const snapshot = swarm.workDir ? loadSwarmSnapshot(swarm.workDir, swarmId) : null;
             if (snapshot && messages.length > 0) {
                 const retroResult = await runRetrospective({
                     swarmId,
@@ -442,10 +971,142 @@ export class SwarmCoordinator {
             await this.sessionAdapter.closeSession(role.roleSessionId).catch(() => { });
         }
         // 4. Delete recovery.json (keep messages.jsonl)
-        deleteSwarmSnapshot(swarmId);
+        if (swarm.workDir) {
+            // Detach tasks before deleting snapshot — keeps task index consistent
+            // even if snapshot removal fails. Best-effort: never abort cleanup.
+            await this.detachTasks(swarmId, swarm.workDir);
+            deleteSwarmSnapshot(swarm.workDir, swarmId);
+        }
         // 5. Remove from memory
         this.swarms.delete(swarmId);
     }
+    /**
+     * Detach all tasks owned by a swarm: clear their swarmId and owner so they
+     * survive the swarm's lifecycle and can be reassigned. Best-effort — any
+     * failure is logged and swallowed; never blocks destroy/complete/fail.
+     *
+     * Tasks belonging to other swarms are not touched.
+     */
+    async detachTasks(swarmId, workDir) {
+        if (!workDir)
+            return;
+        try {
+            // TaskStore.projectRoot() prepends ".clawnet/" itself, so `home` here
+            // must be the user home (no `.clawnet` suffix). Previously this used
+            // `process.env.CLAWNET_DIR ?? join(homedir(), ".clawnet")`, producing
+            // a `~/.clawnet/.clawnet/projects/...` ghost layout for every detach.
+            const home = this.resolveHome();
+            const store = new TaskStore({ workDir, home });
+            const entries = store.listBySwarm(swarmId);
+            for (const entry of entries) {
+                try {
+                    await store.update(entry.id, { swarmId: null, owner: null });
+                }
+                catch (err) {
+                    log.warn({ err, swarmId, taskId: entry.id }, "detachTasks: update failed for task (best-effort)");
+                }
+            }
+        }
+        catch (err) {
+            log.warn({ err, swarmId }, "detachTasks: failed (best-effort)");
+        }
+    }
+    /**
+     * Build the boot-time "### 任务上下文" section appended to a role's system
+     * prompt. Returns null when no taskStore is wired (caller already gates on
+     * that, but we double-check here for safety).
+     *
+     * Queen vs. worker contract:
+     *   - queen → lead briefing (queenInstanceId is this role itself) + member briefing
+     *   - other → task briefing (owner-scoped) + member briefing
+     *
+     * The "### 任务上下文" anchor and inner section anchors are load-bearing
+     * (matched verbatim by tests and by the agent itself).
+     */
+    buildBriefingSection(taskStore, swarmId, instanceId, definition) {
+        const isQueen = definition.type === "queen";
+        if (isQueen) {
+            const leadBody = computeLeadBriefing(taskStore, swarmId, instanceId);
+            const memberBody = computeMemberBriefing({ swarmId, instanceId, roleType: "queen" });
+            return ("### 任务上下文\n\n" +
+                formatLeadBriefing(leadBody) +
+                "\n\n" +
+                formatMemberBriefing(memberBody));
+        }
+        const taskBody = computeTaskBriefing(taskStore, swarmId, instanceId);
+        const memberBody = computeMemberBriefing({ swarmId, instanceId, roleType: "worker" });
+        return ("### 任务上下文\n\n" +
+            formatTaskBriefing(taskBody, { instanceId }) +
+            "\n\n" +
+            formatMemberBriefing(memberBody));
+    }
+    // ── Inbox-based message delivery (Task 6 / PR4) ─────────────────────
+    /**
+     * Append a message to a target instance's inbox file then trigger
+     * InboxRelay.deliver to push it through the agent's stdin (single-flight).
+     * Best-effort: returns silently when the swarm has no workDir (in-memory
+     * fixtures used by tests), keeping behaviour compatible with the previous
+     * router.send path.
+     */
+    async deliverInbox(swarm, targetInstanceId, msg) {
+        if (!swarm.workDir)
+            return;
+        const store = new InboxStore(swarm.workDir, swarm.id, this.resolveHome());
+        const full = {
+            id: `${msg.type}-${randomUUID()}`,
+            from: msg.from,
+            type: msg.type,
+            data: msg.data,
+            ...(msg.taskId ? { taskId: msg.taskId } : {}),
+            timestamp: Date.now(),
+            delivered: false,
+        };
+        await store.append(targetInstanceId, full);
+        // Lifecycle short-circuit: InboxRelay.runDeliver gates on
+        // `spawning`/`stopped` and would no-op anyway. Looping past it just burns
+        // cycles for messages that will be drained later — `stopped` is terminal
+        // (the inbox row stays for any successor); `spawning` is drained by the
+        // post-spawn `inboxRelay.deliver` invoked once the role flips to active.
+        const role = swarm.roles.get(targetInstanceId);
+        if (!role || role.status === "stopped" || role.status === "spawning")
+            return;
+        // InboxRelay uses single-flight per instance: a deliver() call invoked
+        // while another pass is in-flight is coalesced into the existing promise
+        // and may NOT see our just-appended row (the in-flight pass already
+        // ran readUndelivered before our append landed). Loop a few iterations,
+        // each preceded by a microtask hop so the in-flight slot has cleared,
+        // until our id is no longer undelivered (or a lifecycle gate trips).
+        for (let attempt = 0; attempt < 4; attempt++) {
+            await this.inboxRelay.deliver(swarm.id, targetInstanceId);
+            // Yield once so InboxRelay's `.finally(delete inFlight)` runs before we
+            // attempt the follow-up deliver — otherwise the next call would join
+            // the still-in-flight promise instead of starting a fresh pass.
+            await new Promise((r) => setImmediate(r));
+            const remaining = await store.readUndelivered(targetInstanceId);
+            if (!remaining.some((m) => m.id === full.id))
+                return;
+            // Re-check lifecycle: if the role transitioned to stopped between
+            // attempts (e.g. shutdown raced with delivery), don't keep spinning.
+            const cur = swarm.roles.get(targetInstanceId);
+            if (!cur || cur.status === "stopped")
+                return;
+        }
+        log.warn({ swarmId: swarm.id, instanceId: targetInstanceId, msgId: full.id, type: msg.type }, "deliverInbox: message remained undelivered after 4 attempts");
+    }
+    /**
+     * Broadcast helper: deliverInbox to every role in the swarm except those
+     * already stopped. Includes `spawning` roles intentionally — the inbox file
+     * is durable, so the relay (or runPostStart drain in the spawn path) will
+     * deliver the message once the role's stdin opens. Matches the legacy
+     * router.broadcast behaviour, which never gated on "spawning".
+     */
+    async broadcastInbox(swarm, msg) {
+        for (const role of swarm.roles.values()) {
+            if (role.status === "stopped")
+                continue;
+            await this.deliverInbox(swarm, role.instanceId, msg);
+        }
+    }
     findQueen(swarm) {
         for (const role of swarm.roles.values()) {
             if (role.definition.type === "queen" && role.status !== "stopped")
@@ -453,6 +1114,18 @@ export class SwarmCoordinator {
         }
         return undefined;
     }
+    /**
+     * Public lookup: returns the active queen role instance for a swarm, or
+     * undefined when the swarm/queen is not present. Identifies the queen by
+     * `definition.type === "queen"` (not by roleName) so custom queen roles
+     * with non-default names are also recognised.
+     */
+    findQueenInstance(swarmId) {
+        const swarm = this.swarms.get(swarmId);
+        if (!swarm)
+            return undefined;
+        return this.findQueen(swarm);
+    }
     findReviewer(swarm) {
         for (const role of swarm.roles.values()) {
             if (role.roleName === "reviewer" && role.status !== "stopped")
@@ -462,7 +1135,10 @@ export class SwarmCoordinator {
     }
     /** Build a summary of the previous swarm run from messages.jsonl for continuation. */
     buildContinuationSummary(swarmId) {
-        const messages = readMessageLog(swarmId);
+        const swarm = this.swarms.get(swarmId);
+        if (!swarm?.workDir)
+            return null;
+        const messages = readMessageLog(swarm.workDir, swarmId);
         if (messages.length === 0)
             return null;
         const MAX_LEN = 2000;
@@ -492,7 +1168,7 @@ export class SwarmCoordinator {
         return summary;
     }
     /** Send plan to reviewer for review. Auto-approves if no reviewer available. */
-    requestPlanReview(swarm, plan) {
+    async requestPlanReview(swarm, plan) {
         const reviewer = this.findReviewer(swarm);
         if (!reviewer) {
             // No reviewer — auto-approve
@@ -505,9 +1181,8 @@ export class SwarmCoordinator {
         swarm.planStatus = "reviewing";
         saveSwarmSnapshot(swarm);
         this.sendStatusUpdate(swarm);
-        const router = swarm._router;
         const planJson = JSON.stringify(plan, null, 2);
-        router.send(reviewer.instanceId, {
+        await this.deliverInbox(swarm, reviewer.instanceId, {
             from: "system",
             type: "plan_review",
             data: `[系统] 请审查以下执行计划，评估其可行性和风险。
@@ -523,48 +1198,38 @@ export class SwarmCoordinator {
 ${planJson}
 \`\`\`
 
-审查完成后，请用 report action 回复（taskId="plan_review"）：
-- 如果批准：status="completed"，output 中包含 "approved" 和你的审查意见
-- 如果拒绝：status="failed"，output 中说明拒绝原因和改进建议`,
+审查完成后，请通过 \`mcp__clawnet__plan_review_submit\` 工具提交结果（不要再用 report action）：
+- 工具入参：\`{ workDir, swarmId, from: "<你的 instanceId，必须 reviewer-* 开头>", verdict: "approved" | "rejected", body?: "审查意见或拒绝原因" }\`
+- 批准：verdict="approved"，body 中可补充意见
+- 拒绝：verdict="rejected"，body 中说明拒绝原因和改进建议
+- 系统会在 10 分钟内未收到 verdict 时自动批准（带 timeout 警告），请尽快回复。`,
             taskId: "plan_review",
-            timestamp: Date.now(),
         });
         log.info({ swarmId: swarm.id, reviewer: reviewer.instanceId }, "plan sent to reviewer");
+        // Register a timeout fallback so a non-responsive reviewer cannot deadlock
+        // the queen. Cleared on submitPlanReview (success path) and on swarm
+        // shutdown / recover. Idempotent — safe to call multiple times.
+        this.armPlanReviewTimeout(swarm);
     }
-    /** Handle plan review result from reviewer. */
-    handlePlanReviewResult(swarm, fromRole, action) {
-        const router = swarm._router;
-        const queen = this.findQueen(swarm);
-        if (action.status === "completed" && action.output?.toLowerCase().includes("approved")) {
-            swarm.planStatus = "approved";
-            saveSwarmSnapshot(swarm);
-            this.sendStatusUpdate(swarm);
-            log.info({ swarmId: swarm.id, reviewer: fromRole.instanceId }, "plan approved by reviewer");
-            // Notify queen to start task assignment
-            if (queen) {
-                router.send(queen.instanceId, {
-                    from: "system",
-                    type: "plan_approved",
-                    data: `[系统] 你的执行计划已通过审查。审查意见：${action.output}\n\n请开始按计划分配任务。`,
-                    timestamp: Date.now(),
-                });
-            }
-        }
-        else {
-            swarm.planStatus = "rejected";
-            saveSwarmSnapshot(swarm);
-            this.sendStatusUpdate(swarm);
-            log.info({ swarmId: swarm.id, reviewer: fromRole.instanceId }, "plan rejected by reviewer");
-            // Notify queen to revise the plan
-            if (queen) {
-                router.send(queen.instanceId, {
-                    from: "system",
-                    type: "plan_rejected",
-                    data: `[系统] 你的执行计划未通过审查，请根据反馈修改。\n\n审查反馈：${action.output ?? "未提供具体原因"}`,
-                    timestamp: Date.now(),
-                });
-            }
-        }
+    /**
+     * (Re)arm the plan-review timeout fallback. Clears any prior timer first so
+     * call sites don't need to. The fire path delegates to submitPlanReview so
+     * its idempotency guard protects against reviewer/timer races.
+     */
+    armPlanReviewTimeout(swarm) {
+        if (swarm.planReviewTimer)
+            clearTimeout(swarm.planReviewTimer);
+        swarm.planReviewTimer = setTimeout(() => {
+            if (swarm.planStatus !== "reviewing")
+                return;
+            log.warn({ swarmId: swarm.id }, "plan review timed out — auto-approving with warning");
+            void this.submitPlanReview({
+                swarmId: swarm.id,
+                from: "system",
+                verdict: "approved",
+                body: "[timeout] reviewer 未在 10 分钟内提交审查结果，已自动通过；请人工复核。",
+            }).catch((err) => log.error({ err, swarmId: swarm.id }, "auto-approve on timeout failed"));
+        }, PLAN_REVIEW_TIMEOUT_MS);
     }
     findByRoleSessionId(roleSessionId) {
         // roleSessionId format: "{swarmId}::{instanceId}"
@@ -579,240 +1244,68 @@ ${planJson}
         const role = swarm.roles.get(instanceId);
         return { swarm, role };
     }
-    async executeAction(swarm, fromRole, router, action) {
-        log.info({ swarmId: swarm.id, from: fromRole.instanceId, action: action.action }, "executing action");
-        switch (action.action) {
-            case "send": {
-                // Gate: queen cannot send task to workers while plan is under review
-                if (fromRole.definition.type === "queen" &&
-                    action.type === "task" &&
-                    (swarm.planStatus === "draft" || swarm.planStatus === "reviewing")) {
-                    log.info({ swarmId: swarm.id, to: action.to, planStatus: swarm.planStatus }, "queen task send blocked: plan under review");
-                    const router2 = swarm._router;
-                    router2.send(fromRole.instanceId, {
-                        from: "system",
-                        type: "system",
-                        data: `[系统] 任务分配被拦截。当前计划状态为「${swarm.planStatus}」，请等待审查完成后再分配任务。`,
-                        timestamp: Date.now(),
-                    });
-                    break;
-                }
-                const msg = {
-                    messageId: randomUUID(),
-                    from: fromRole.instanceId,
-                    type: action.type,
-                    data: action.data,
-                    taskId: action.taskId,
-                    timestamp: Date.now(),
-                };
-                // On-demand spawn: if target not started yet, spawn it first
-                if (!router.has(action.to)) {
-                    await this.ensureRoleStarted(swarm, action.to, router);
-                }
-                // Retry with exponential backoff
-                this.sendWithRetry(swarm, fromRole, router, action.to, msg);
-                break;
-            }
-            case "report": {
-                // Update role status
-                if (action.status === "completed" || action.status === "failed") {
-                    fromRole.currentTask = undefined;
-                }
-                // Release worker process on task completion (queen always stays alive)
-                if (action.status === "completed" &&
-                    fromRole.definition.type !== "queen") {
-                    this.stopRole(swarm.id, fromRole.instanceId).catch((err) => {
-                        log.warn({ err, instanceId: fromRole.instanceId }, "failed to release worker after completion");
-                    });
-                }
-                // Check for plan review result
-                if (action.taskId === "plan_review") {
-                    this.handlePlanReviewResult(swarm, fromRole, action);
-                    break;
+    startQueenCheck(swarmId) {
+        const swarm = this.swarms.get(swarmId);
+        if (!swarm)
+            return;
+        const tick = async () => {
+            try {
+                // Stop ticking if swarm is no longer active
+                if (swarm.status === "completed" || swarm.status === "failed" || swarm.status === "paused") {
+                    return;
                 }
-                // Notify queen about the report (so she can coordinate next steps)
                 const queen = this.findQueen(swarm);
-                if (queen && queen.instanceId !== fromRole.instanceId) {
-                    const reportMsg = {
-                        from: fromRole.instanceId,
-                        type: "report",
-                        data: `[${action.status}] ${action.output ?? "任务状态更新"}`,
-                        taskId: action.taskId,
-                        timestamp: Date.now(),
-                    };
-                    router.send(queen.instanceId, reportMsg);
-                    appendMessageLog(swarm.id, { type: "action", action: "report", from: fromRole.instanceId, to: queen.instanceId, status: action.status, data: action.output, timestamp: Date.now() });
-                    log.info({ swarmId: swarm.id, from: fromRole.instanceId, status: action.status, taskId: action.taskId }, "report forwarded to queen");
-                }
-                // Queen reporting completed/failed = swarm lifecycle transition
-                if (fromRole.definition.type === "queen") {
-                    if (action.status === "completed") {
-                        this.complete(swarm.id).catch((err) => {
-                            log.error({ err, swarmId: swarm.id }, "failed to complete swarm");
-                        });
-                    }
-                    else if (action.status === "failed") {
-                        this.fail(swarm.id).catch((err) => {
-                            log.error({ err, swarmId: swarm.id }, "failed to mark swarm as failed");
-                        });
-                    }
+                if (!queen || queen.status === "stopped")
+                    return;
+                // Reconcile planStatus vs queen inbox: if planStatus is finalised
+                // (approved/rejected) but the queen never received the corresponding
+                // plan_approved / plan_rejected envelope, re-emit it. This recovers
+                // from the rare case where the deferred submitPlanReview's call to
+                // deliverInbox() failed and only logged a warning (the reviewer saw
+                // {submitted:true} but the queen never woke up).
+                await this.reconcilePlanStatusForQueen(swarm, queen.instanceId).catch((err) => log.warn({ err, swarmId }, "reconcilePlanStatus failed (best-effort)"));
+                // Adaptive interval: slow down when only queen is left or all roles idle
+                const activeWorkers = [...swarm.roles.values()].filter((r) => r.definition.type !== "queen" && r.status === "active");
+                // Track consecutive idle checks
+                if (activeWorkers.length > 0) {
+                    swarm.idleCheckCount = 0;
                 }
-                // Forward status to Hub
-                this.sendStatusUpdate(swarm);
-                break;
-            }
-            case "broadcast": {
-                const msg = {
-                    from: fromRole.instanceId,
-                    type: "broadcast",
-                    data: action.data,
-                    timestamp: Date.now(),
-                };
-                router.broadcast(msg, fromRole.instanceId);
-                break;
-            }
-            case "spawn_role": {
-                // Only queen can spawn roles — await to ensure route is registered before subsequent sends
-                if (fromRole.definition.type === "queen") {
-                    await this.spawnRole(swarm.id, action.roleName, router, action.task);
+                else {
+                    swarm.idleCheckCount++;
                 }
-                break;
-            }
-            case "stop_role": {
-                // Only queen can stop roles
-                if (fromRole.definition.type === "queen") {
-                    this.stopRole(swarm.id, action.instanceId).catch((err) => {
-                        log.error({ err, instanceId: action.instanceId }, "failed to stop role");
+                // Auto-pause if idle too long
+                if (swarm.idleCheckCount >= swarm.maxIdleChecks) {
+                    swarm.isPaused = true;
+                    swarm.status = "paused";
+                    saveSwarmSnapshot(swarm);
+                    this.sendStatusUpdate(swarm);
+                    await this.deliverInbox(swarm, queen.instanceId, {
+                        from: "system",
+                        type: "system",
+                        data: `[系统] 蜂群已自动暂停。连续${swarm.maxIdleChecks}次巡查发现所有成员空闲，已暂停任务释放资源。用户可以resume恢复。`,
                     });
+                    log.info({ swarmId, idleChecks: swarm.maxIdleChecks }, "swarm auto-paused");
+                    return; // Don't schedule next tick
                 }
-                break;
-            }
-        }
-    }
-    /** On-demand spawn: start a role instance if it's not currently running. */
-    async ensureRoleStarted(swarm, instanceId, router) {
-        // Already running?
-        if (router.has(instanceId))
-            return;
-        // Determine role name from instanceId prefix (e.g. "dev-1" → "developer")
-        const prefix = instanceId.replace(/-\d+$/, "");
-        const pendingSpecs = swarm._pendingRoleSpecs;
-        // Try to find matching role spec from the pending specs
-        let roleName;
-        let customPrompt;
-        let customDefinition;
-        if (pendingSpecs) {
-            for (const spec of pendingSpecs) {
-                const def = spec.customDefinition
-                    ? { shortName: spec.customDefinition.shortName }
-                    : (() => { try {
-                        return loadRole(spec.roleName);
-                    }
-                    catch {
-                        return null;
-                    } })();
-                if (def && def.shortName === prefix) {
-                    roleName = spec.roleName;
-                    customPrompt = spec.customPrompt;
-                    customDefinition = spec.customDefinition;
-                    break;
-                }
-            }
-        }
-        if (!roleName) {
-            log.warn({ swarmId: swarm.id, instanceId }, "cannot on-demand spawn: unknown role for instanceId");
-            return;
-        }
-        log.info({ swarmId: swarm.id, instanceId, roleName }, "on-demand spawning role");
-        await this.spawnRole(swarm.id, roleName, router, undefined, customPrompt, customDefinition);
-    }
-    /** Send a message with exponential backoff retry. Fire-and-forget (async). */
-    async sendWithRetry(swarm, fromRole, router, targetInstanceId, msg) {
-        for (let attempt = 0; attempt <= SEND_MAX_RETRIES; attempt++) {
-            const result = router.send(targetInstanceId, msg);
-            if (result.delivered) {
-                appendMessageLog(swarm.id, {
-                    type: "action", action: "send",
-                    from: fromRole.instanceId, to: targetInstanceId,
-                    data: msg.data, messageId: msg.messageId,
-                    timestamp: Date.now(),
-                });
-                return;
-            }
-            log.warn({ swarmId: swarm.id, to: targetInstanceId, attempt, reason: result.reason, messageId: msg.messageId }, "message delivery failed");
-            if (attempt < SEND_MAX_RETRIES) {
-                await sleep(SEND_RETRY_BASE_MS * 2 ** attempt);
-            }
-        }
-        // All retries exhausted — notify Queen
-        log.error({ swarmId: swarm.id, to: targetInstanceId, messageId: msg.messageId }, "message delivery failed after all retries");
-        appendMessageLog(swarm.id, {
-            type: "action", action: "send",
-            from: fromRole.instanceId, to: targetInstanceId,
-            data: msg.data, messageId: msg.messageId,
-            delivered: false,
-            timestamp: Date.now(),
-        });
-        const queen = this.findQueen(swarm);
-        if (queen) {
-            router.send(queen.instanceId, {
-                from: "system",
-                type: "system",
-                data: `[系统] 消息发送给 ${targetInstanceId} 失败（已重试 ${SEND_MAX_RETRIES} 次）。原始消息来自 ${fromRole.instanceId}。`,
-                timestamp: Date.now(),
-            });
-        }
-    }
-    startQueenCheck(swarmId) {
-        const swarm = this.swarms.get(swarmId);
-        if (!swarm)
-            return;
-        const tick = () => {
-            // Stop ticking if swarm is no longer active
-            if (swarm.status === "completed" || swarm.status === "failed" || swarm.status === "paused") {
-                return;
-            }
-            const queen = this.findQueen(swarm);
-            if (!queen || queen.status === "stopped")
-                return;
-            const router = swarm._router;
-            // Adaptive interval: slow down when only queen is left or all roles idle
-            const activeWorkers = [...swarm.roles.values()].filter((r) => r.definition.type !== "queen" && r.status === "active");
-            // Track consecutive idle checks
-            if (activeWorkers.length > 0) {
-                swarm.idleCheckCount = 0;
-            }
-            else {
-                swarm.idleCheckCount++;
-            }
-            // Auto-pause if idle too long
-            if (swarm.idleCheckCount >= swarm.maxIdleChecks) {
-                swarm.isPaused = true;
-                swarm.status = "paused";
-                saveSwarmSnapshot(swarm);
-                this.sendStatusUpdate(swarm);
-                router.send(queen.instanceId, {
+                const statusJson = JSON.stringify(this.buildStatusPayload(swarm), null, 2);
+                await this.deliverInbox(swarm, queen.instanceId, {
                     from: "system",
                     type: "system",
-                    data: `[系统] 蜂群已自动暂停。连续${swarm.maxIdleChecks}次巡查发现所有成员空闲，已暂停任务释放资源。用户可以resume恢复。`,
-                    timestamp: Date.now(),
+                    data: `[系统] 定时巡查触发。请查看当前蜂群状态，判断是否需要采取行动。\n\n当前蜂群成员及状态：\n${statusJson}`,
                 });
-                log.info({ swarmId, idleChecks: swarm.maxIdleChecks }, "swarm auto-paused");
-                return; // Don't schedule next tick
+                const nextInterval = activeWorkers.length > 0
+                    ? QUEEN_CHECK_INTERVAL_MS
+                    : QUEEN_CHECK_IDLE_INTERVAL_MS;
+                swarm.checkTimer = setTimeout(() => { void tick().catch((err) => log.error({ err, swarmId }, "queen tick failed (best-effort)")); }, nextInterval);
+            }
+            catch (err) {
+                // deliverInbox / disk-IO failures must not surface as unhandled
+                // rejection from the setTimeout fire-and-forget. Log and swallow;
+                // the next tick (if any) will retry on its own schedule.
+                log.error({ err, swarmId }, "queen tick failed (best-effort)");
             }
-            const statusJson = JSON.stringify(this.buildStatusPayload(swarm), null, 2);
-            router.send(queen.instanceId, {
-                from: "system",
-                type: "system",
-                data: `[系统] 定时巡查触发。请查看当前蜂群状态，判断是否需要采取行动。\n\n当前蜂群成员及状态：\n${statusJson}`,
-                timestamp: Date.now(),
-            });
-            const nextInterval = activeWorkers.length > 0
-                ? QUEEN_CHECK_INTERVAL_MS
-                : QUEEN_CHECK_IDLE_INTERVAL_MS;
-            swarm.checkTimer = setTimeout(tick, nextInterval);
         };
-        swarm.checkTimer = setTimeout(tick, QUEEN_CHECK_INTERVAL_MS);
+        swarm.checkTimer = setTimeout(() => { void tick().catch((err) => log.error({ err, swarmId }, "queen tick failed (best-effort)")); }, QUEEN_CHECK_INTERVAL_MS);
     }
     buildRoleListString(swarm) {
         const lines = [];