@elizaos/agent 0.25.8 → 2.0.0-alpha.144

package/packages/typescript/src/features/orchestrator/services/swarm-coordinator.js

@@ -0,0 +1,2356 @@
+/**
+ * Swarm Coordinator — Event Bridge & Autonomous Coordination Loop
+ *
+ * Bridges PTY session events to:
+ * 1. SSE clients (frontend dashboard) for real-time status
+ * 2. LLM coordination decisions for unhandled blocking prompts
+ *
+ * The coordinator subscribes to PTYService session events and:
+ * - Skips events already handled by auto-response rules (autoResponded=true)
+ * - Routes unhandled blocking prompts through supervision levels:
+ *   - autonomous: LLM decides immediately
+ *   - confirm: queued for human approval
+ *   - notify: broadcast only (no action)
+ *
+ * Heavy logic is extracted into:
+ * - swarm-decision-loop.ts  (blocked, turn-complete, LLM decisions)
+ * - swarm-idle-watchdog.ts  (idle session scanning)
+ *
+ * @module services/swarm-coordinator
+ */
+import { logger } from "@elizaos/core";
+import { buildAgentCredentials } from "./agent-credentials.js";
+import { cleanForFailoverContext, extractDevServerUrl } from "./ansi-utils.js";
+import { normalizeCoordinatorEvent, } from "./coordinator-event-normalizer.js";
+import { normalizeAgentType } from "./pty-types.js";
+import { checkAllTasksComplete, clearDeferredTurnCompleteTimers, executeDecision as execDecision, handleBlocked, handleTurnComplete, } from "./swarm-decision-loop.js";
+import { SwarmHistory } from "./swarm-history.js";
+import { scanIdleSessions } from "./swarm-idle-watchdog.js";
+import { deriveTaskAcceptanceCriteria } from "./task-acceptance.js";
+import { isUsageExhaustedTaskAgentError, markTaskAgentFrameworkHealthy, markTaskAgentFrameworkUnavailable, } from "./task-agent-frameworks.js";
+import { inferTaskThreadKind } from "./task-kind.js";
+import { TaskRegistry, } from "./task-registry.js";
+// ─── Constants ───
+/** Time to buffer events for unregistered sessions (ms). */
+/** Exponential backoff delays for unregistered session buffer retries. */
+const UNREGISTERED_RETRY_DELAYS = [2000, 4000, 8000, 16000];
+/** Absolute maximum wait time before discarding unregistered events. */
+const UNREGISTERED_MAX_TOTAL_MS = 30_000;
+/** Coalesce rapid turn-complete events within this window (ms). */
+const TURN_COMPLETE_COALESCE_MS = 500;
+/** How often the idle watchdog scans for idle sessions (ms). */
+const IDLE_SCAN_INTERVAL_MS = 60 * 1000; // 1 minute
+/** How long to wait before auto-resuming a paused coordinator (ms). */
+const PAUSE_TIMEOUT_MS = 30_000;
+/** Max events to buffer before WS bridge is wired. */
+const MAX_PRE_BRIDGE_BUFFER = 100;
+/** Grace window where a late task_complete can recover a recently-stopped task. */
+const STOPPED_RECOVERY_WINDOW_MS = 90_000;
+const FAILOVER_OUTPUT_MAX_CHARS = 4_000;
+const MAX_AUTOMATIC_ERROR_RECOVERIES = 2;
+const ALTERNATE_FRAMEWORK_ERROR_RE = /\b(auth|login|credential|401|403|unauthorized|forbidden|token|api key|not found|enoent|missing executable|command not found)\b/i;
+function inferProviderSource(framework) {
+    if (framework.subscriptionReady) {
+        return "subscription";
+    }
+    if (framework.id === "pi") {
+        return framework.installed ? "local-cli" : null;
+    }
+    return framework.authReady ? "credentials" : null;
+}
+// ─── Service ───
+export class SwarmCoordinator {
+    static serviceType = "SWARM_COORDINATOR";
+    runtime;
+    taskRegistry;
+    ptyService = null;
+    unsubscribeEvents = null;
+    /** Per-session task context. */
+    tasks = new Map();
+    /** SSE clients receiving live events. */
+    sseClients = new Set();
+    /** Supervision level (default: autonomous). */
+    supervisionLevel = "autonomous";
+    /** Pending confirmations for "confirm" mode. */
+    pendingDecisions = new Map();
+    /** In-flight decision lock — prevents parallel LLM calls for same session. */
+    inFlightDecisions = new Set();
+    /** Buffered task_complete events that arrived while an in-flight decision was running. */
+    pendingTurnComplete = new Map();
+    /** Fingerprint of the last blocked prompt per session — for re-render dedup. */
+    lastBlockedPromptFingerprint = new Map();
+    /** Buffered blocked events that arrived while an in-flight decision was running. */
+    pendingBlocked = new Map();
+    /** Callback to send chat messages to the user's conversation UI. */
+    chatCallback = null;
+    /** Callback to relay coordinator events to WebSocket clients. */
+    wsBroadcast = null;
+    /** Callback to route coordinator events through Milaidy's full pipeline. */
+    agentDecisionCb = null;
+    /** Callback fired when all swarm tasks complete — for synthesis. */
+    swarmCompleteCb = null;
+    /** Buffer for events arriving before task registration. */
+    unregisteredBuffer = new Map();
+    /** Idle watchdog timer handle. */
+    idleWatchdogTimer = null;
+    /** Last-seen output snapshot per session — used by idle watchdog to detect data flow. */
+    lastSeenOutput = new Map();
+    /** Timestamp of last tool_running chat notification per session — for throttling. */
+    lastToolNotification = new Map();
+    /** Whether LLM decisions are paused (user sent a chat message). */
+    _paused = false;
+    /** Significant decisions shared across the swarm (Layer 2). */
+    sharedDecisions = [];
+    /** Shared context brief generated during swarm planning phase. */
+    _swarmContext = "";
+    /** @see SwarmCoordinatorContext.swarmCompleteNotified */
+    swarmCompleteNotified = false;
+    /** Buffered events during pause — replayed on resume. */
+    pauseBuffer = [];
+    /** Buffered broadcasts waiting for wsBroadcast to be wired. */
+    preBridgeBroadcastBuffer = [];
+    /** Auto-resume timeout handle. */
+    pauseTimeout = null;
+    /** Coordinator startup timestamp — ignore events from sessions created before this. */
+    startedAt = Date.now();
+    /** Active retry timers for unregistered session buffers. */
+    unregisteredRetryTimers = new Map();
+    /** Turn-complete coalescing timers — debounces rapid events per session. */
+    turnCompleteCoalesceTimers = new Map();
+    /** Persistent swarm history — JSONL log that survives restarts. */
+    history = new SwarmHistory();
+    constructor(runtime) {
+        this.runtime = runtime;
+        this.taskRegistry = new TaskRegistry(runtime);
+    }
+    // ─── Chat Callback ───
+    /** Inject a callback (from server.ts) to route messages to the user's chat UI. */
+    /** Track whether we've already wired the scratch decision callback. */
+    scratchDecisionWired = false;
+    setChatCallback(cb) {
+        this.chatCallback = cb;
+        this.log("Chat callback wired");
+        // Try wiring scratch decision callback now, retry lazily if service not ready
+        this.wireScratchDecisionCallback();
+    }
+    /**
+     * Wire the scratch workspace save prompt callback.
+     * Called eagerly from setChatCallback and lazily from handleSessionEvent
+     * in case the workspace service wasn't ready at chat-callback time.
+     */
+    wireScratchDecisionCallback() {
+        if (this.scratchDecisionWired || !this.chatCallback)
+            return;
+        const wsService = this.runtime.getService("CODING_WORKSPACE_SERVICE");
+        if (wsService?.setScratchDecisionCallback) {
+            const chatCb = this.chatCallback;
+            wsService.setScratchDecisionCallback(async (record) => {
+                const ttlNote = record.expiresAt
+                    ? (() => {
+                        const remainMs = record.expiresAt - Date.now();
+                        const hours = Math.round(remainMs / (60 * 60 * 1000));
+                        return hours >= 1
+                            ? `It will be automatically cleaned up in ~${hours} hour${hours === 1 ? "" : "s"}.`
+                            : `It will be automatically cleaned up shortly.`;
+                    })()
+                    : "It will be automatically cleaned up after the configured retention period.";
+                await chatCb(`Task "${record.label}" finished. Code is at \`${record.path}\`.\n` +
+                    `${ttlNote} To keep it, say "keep the workspace" or manage it in Settings -> Task Agents.`, "task-agent");
+            });
+            this.scratchDecisionWired = true;
+            this.log("Scratch decision callback wired");
+        }
+    }
+    /** Inject a callback (from server.ts) to relay events to WebSocket clients. */
+    setWsBroadcast(cb) {
+        this.wsBroadcast = cb;
+        // Replay any events that were broadcast before the bridge was wired
+        if (this.preBridgeBroadcastBuffer.length > 0) {
+            this.log(`WS broadcast callback wired — replaying ${this.preBridgeBroadcastBuffer.length} buffered event(s)`);
+            for (const event of this.preBridgeBroadcastBuffer) {
+                cb(event);
+            }
+            this.preBridgeBroadcastBuffer.length = 0;
+        }
+        else {
+            this.log("WS broadcast callback wired");
+        }
+    }
+    /** Inject a callback fired when all swarm tasks reach terminal state. */
+    setSwarmCompleteCallback(cb) {
+        this.swarmCompleteCb = cb;
+        this.log("Swarm complete callback wired");
+    }
+    /** Return the swarm complete callback (if wired). */
+    getSwarmCompleteCallback() {
+        return this.swarmCompleteCb;
+    }
+    /** Set the shared context brief for this swarm. */
+    setSwarmContext(context) {
+        this._swarmContext = context;
+        this.log(`Swarm context set (${context.length} chars)`);
+    }
+    /** Return the swarm planning context (if set). */
+    getSwarmContext() {
+        return this._swarmContext;
+    }
+    /** Inject a callback (from server.ts) to route events through Milaidy's pipeline. */
+    setAgentDecisionCallback(cb) {
+        this.agentDecisionCb = cb;
+        this.log("Agent decision callback wired — events will route through Milaidy");
+    }
+    /** Return the agent decision callback (if wired). */
+    getAgentDecisionCallback() {
+        return this.agentDecisionCb;
+    }
+    /** Null-safe wrapper — sends a message to the user's conversation if callback is set. */
+    sendChatMessage(text, source) {
+        if (!this.chatCallback)
+            return;
+        this.chatCallback(text, source).catch((err) => {
+            this.log(`Failed to send chat message: ${err}`);
+        });
+    }
+    // ─── Lifecycle ───
+    /**
+     * Initialize the coordinator by subscribing to PTY session events.
+     * Called from plugin init after services are ready.
+     */
+    async start(ptyService) {
+        await this.taskRegistry.ensureSchema();
+        await this.taskRegistry.recoverInterruptedTasks();
+        await this.rehydratePendingDecisions();
+        this.ptyService = ptyService;
+        this.unsubscribeEvents = ptyService.onNormalizedSessionEvent((normalized) => {
+            this.handleNormalizedSessionEvent(normalized).catch((err) => {
+                this.log(`Error handling event: ${err}`);
+            });
+        });
+        // Start idle watchdog
+        this.idleWatchdogTimer = setInterval(() => {
+            scanIdleSessions(this).catch((err) => {
+                this.log(`Idle watchdog error: ${err}`);
+            });
+        }, IDLE_SCAN_INTERVAL_MS);
+        this.log("SwarmCoordinator started");
+    }
+    restorePendingTaskContext(record) {
+        const raw = record.taskContext;
+        const status = (() => {
+            switch (typeof raw.status === "string" ? raw.status : "") {
+                case "active":
+                case "blocked":
+                case "tool_running":
+                case "completed":
+                case "error":
+                case "stopped":
+                    return raw.status;
+                default:
+                    return "blocked";
+            }
+        })();
+        return {
+            threadId: typeof raw.threadId === "string" && raw.threadId.trim().length > 0
+                ? raw.threadId
+                : record.threadId,
+            ...(typeof raw.taskNodeId === "string" && raw.taskNodeId.trim().length > 0
+                ? { taskNodeId: raw.taskNodeId }
+                : {}),
+            sessionId: record.sessionId,
+            agentType: typeof raw.agentType === "string" && raw.agentType.trim().length > 0
+                ? raw.agentType
+                : "claude",
+            label: typeof raw.label === "string" && raw.label.trim().length > 0
+                ? raw.label
+                : `agent-${record.sessionId.slice(-8)}`,
+            originalTask: typeof raw.originalTask === "string"
+                ? raw.originalTask
+                : record.promptText,
+            workdir: typeof raw.workdir === "string" ? raw.workdir : "",
+            ...(typeof raw.repo === "string" && raw.repo.trim().length > 0
+                ? { repo: raw.repo }
+                : {}),
+            status,
+            decisions: Array.isArray(raw.decisions)
+                ? raw.decisions.filter((entry) => Boolean(entry && typeof entry === "object"))
+                : [],
+            autoResolvedCount: typeof raw.autoResolvedCount === "number" ? raw.autoResolvedCount : 0,
+            registeredAt: typeof raw.registeredAt === "number"
+                ? raw.registeredAt
+                : record.createdAt,
+            lastActivityAt: typeof raw.lastActivityAt === "number"
+                ? raw.lastActivityAt
+                : record.createdAt,
+            idleCheckCount: typeof raw.idleCheckCount === "number" ? raw.idleCheckCount : 0,
+            taskDelivered: raw.taskDelivered === true,
+            ...(typeof raw.completionSummary === "string"
+                ? { completionSummary: raw.completionSummary }
+                : {}),
+            lastSeenDecisionIndex: typeof raw.lastSeenDecisionIndex === "number"
+                ? raw.lastSeenDecisionIndex
+                : 0,
+            ...(typeof raw.lastInputSentAt === "number"
+                ? { lastInputSentAt: raw.lastInputSentAt }
+                : {}),
+            ...(typeof raw.stoppedAt === "number"
+                ? { stoppedAt: raw.stoppedAt }
+                : {}),
+        };
+    }
+    restorePendingLlmDecision(record) {
+        const raw = record.llmDecision;
+        const action = typeof raw.action === "string" &&
+            ["respond", "escalate", "ignore", "complete"].includes(raw.action)
+            ? raw.action
+            : "escalate";
+        return {
+            action,
+            ...(typeof raw.response === "string" ? { response: raw.response } : {}),
+            ...(raw.useKeys === true ? { useKeys: true } : {}),
+            ...(Array.isArray(raw.keys)
+                ? {
+                    keys: raw.keys.filter((entry) => typeof entry === "string"),
+                }
+                : {}),
+            reasoning: typeof raw.reasoning === "string" && raw.reasoning.trim().length > 0
+                ? raw.reasoning
+                : "Recovered pending confirmation from persisted coordinator state.",
+        };
+    }
+    async rehydratePendingDecisions() {
+        const records = await this.taskRegistry.listPendingDecisions();
+        for (const record of records) {
+            const taskContext = this.restorePendingTaskContext(record);
+            this.tasks.set(record.sessionId, taskContext);
+            this.pendingDecisions.set(record.sessionId, {
+                sessionId: record.sessionId,
+                promptText: record.promptText,
+                recentOutput: record.recentOutput,
+                llmDecision: this.restorePendingLlmDecision(record),
+                taskContext,
+                createdAt: record.createdAt,
+            });
+        }
+    }
+    async stop() {
+        const persistOnShutdown = Array.from(this.tasks.values())
+            .filter((task) => task.status === "active" ||
+            task.status === "blocked" ||
+            task.status === "tool_running")
+            .map(async (task) => {
+            task.status = "stopped";
+            task.stoppedAt = Date.now();
+            await this.taskRegistry.updateSession(task.sessionId, {
+                status: "interrupted",
+                lastActivityAt: task.lastActivityAt,
+                idleCheckCount: task.idleCheckCount,
+                taskDelivered: task.taskDelivered,
+                autoResolvedCount: task.autoResolvedCount,
+                decisionCount: task.decisions.length,
+                completionSummary: task.completionSummary ?? null,
+                lastSeenDecisionIndex: task.lastSeenDecisionIndex,
+                lastInputSentAt: task.lastInputSentAt,
+                stoppedAt: task.stoppedAt,
+            });
+            await this.taskRegistry.appendEvent({
+                threadId: task.threadId,
+                sessionId: task.sessionId,
+                eventType: "session_interrupted",
+                summary: "Session interrupted during coordinator shutdown",
+                data: { reason: "coordinator_shutdown" },
+            });
+        });
+        await Promise.allSettled(persistOnShutdown);
+        if (this.idleWatchdogTimer) {
+            clearInterval(this.idleWatchdogTimer);
+            this.idleWatchdogTimer = null;
+        }
+        if (this.unsubscribeEvents) {
+            this.unsubscribeEvents();
+            this.unsubscribeEvents = null;
+        }
+        // Close all SSE connections
+        for (const client of this.sseClients) {
+            if (!client.writableEnded) {
+                client.end();
+            }
+        }
+        this.sseClients.clear();
+        this.tasks.clear();
+        this.pendingDecisions.clear();
+        this.inFlightDecisions.clear();
+        this.pendingTurnComplete.clear();
+        clearDeferredTurnCompleteTimers();
+        this.lastBlockedPromptFingerprint.clear();
+        this.pendingBlocked.clear();
+        this.unregisteredBuffer.clear();
+        for (const timer of this.unregisteredRetryTimers.values()) {
+            clearTimeout(timer);
+        }
+        this.unregisteredRetryTimers.clear();
+        for (const timer of this.turnCompleteCoalesceTimers.values()) {
+            clearTimeout(timer);
+        }
+        this.turnCompleteCoalesceTimers.clear();
+        this.lastSeenOutput.clear();
+        this.lastToolNotification.clear();
+        this.agentDecisionCb = null;
+        this.sharedDecisions.length = 0;
+        this._swarmContext = "";
+        this.swarmCompleteNotified = false;
+        // Clear pause state
+        this._paused = false;
+        if (this.pauseTimeout) {
+            clearTimeout(this.pauseTimeout);
+            this.pauseTimeout = null;
+        }
+        this.pauseBuffer = [];
+        this.preBridgeBroadcastBuffer.length = 0;
+        this.log("SwarmCoordinator stopped");
+    }
+    // ─── Pause / Resume ───
+    /** Whether the coordinator is currently paused. */
+    get isPaused() {
+        return this._paused;
+    }
+    /** Pause LLM-based decisions. Auto-responses and broadcasts continue. */
+    pause() {
+        if (this._paused)
+            return;
+        this._paused = true;
+        this.log("Coordinator paused — buffering LLM decisions until user message is processed");
+        this.broadcast({
+            type: "coordinator_paused",
+            sessionId: "",
+            timestamp: Date.now(),
+            data: {},
+        });
+        // Safety: auto-resume after timeout
+        this.pauseTimeout = setTimeout(() => {
+            if (this._paused) {
+                this.log("Coordinator auto-resuming after timeout");
+                this.resume();
+            }
+        }, PAUSE_TIMEOUT_MS);
+    }
+    /** Resume LLM-based decisions and replay buffered events. */
+    resume() {
+        if (!this._paused)
+            return;
+        this._paused = false;
+        if (this.pauseTimeout) {
+            clearTimeout(this.pauseTimeout);
+            this.pauseTimeout = null;
+        }
+        this.log(`Coordinator resumed — replaying ${this.pauseBuffer.length} buffered events`);
+        this.broadcast({
+            type: "coordinator_resumed",
+            sessionId: "",
+            timestamp: Date.now(),
+            data: {},
+        });
+        // Replay buffered events
+        const buffered = [...this.pauseBuffer];
+        this.pauseBuffer = [];
+        for (const entry of buffered) {
+            this.handleNormalizedSessionEvent(entry).catch((err) => {
+                this.log(`Error replaying buffered event: ${err}`);
+            });
+        }
+    }
+    // ─── Task Registration ───
+    async registerTask(sessionId, context) {
+        const threadId = context.threadId?.trim() || sessionId;
+        // Reset swarm state when the first task of a new swarm is registered.
+        // Check for terminal-only tasks (all previous tasks in completed/stopped/error)
+        // rather than empty map, so reuse without stop() works.
+        const allPreviousTerminal = this.tasks.size === 0 ||
+            Array.from(this.tasks.values()).every((t) => t.status === "completed" ||
+                t.status === "stopped" ||
+                t.status === "error");
+        if (allPreviousTerminal) {
+            this.swarmCompleteNotified = false;
+            // Clear stale tasks and shared context from previous swarm
+            if (this.tasks.size > 0) {
+                this.tasks.clear();
+                this.sharedDecisions.length = 0;
+                this._swarmContext = "";
+                this.log("Cleared stale swarm state for new swarm");
+            }
+        }
+        const taskNodeId = context.taskNodeId?.trim() || `node-${sessionId}`;
+        this.tasks.set(sessionId, {
+            threadId,
+            taskNodeId,
+            sessionId,
+            agentType: context.agentType,
+            label: context.label,
+            originalTask: context.originalTask,
+            workdir: context.workdir,
+            repo: context.repo,
+            status: "active",
+            decisions: [],
+            autoResolvedCount: 0,
+            registeredAt: Date.now(),
+            lastActivityAt: Date.now(),
+            idleCheckCount: 0,
+            taskDelivered: false,
+            lastSeenDecisionIndex: 0,
+        });
+        // Persist last used repo so it survives task cleanup
+        if (context.repo) {
+            this._lastUsedRepo = context.repo;
+        }
+        // Log to persistent history (fire-and-forget)
+        this.history
+            .append({
+            timestamp: Date.now(),
+            type: "task_registered",
+            sessionId,
+            label: context.label,
+            agentType: context.agentType,
+            repo: context.repo,
+            workdir: context.workdir,
+            originalTask: context.originalTask,
+        })
+            .catch((err) => {
+            this.log(`Failed to append task registration history for ${sessionId}: ${err}`);
+        });
+        const taskCtx = this.tasks.get(sessionId);
+        const persistPromise = taskCtx
+            ? (async () => {
+                const existingThread = await this.taskRegistry.getThreadRecord(threadId);
+                if (!existingThread) {
+                    await this.createTaskThread({
+                        id: threadId,
+                        title: context.label,
+                        originalRequest: context.originalTask,
+                        metadata: {
+                            repo: context.repo ?? null,
+                            source: "register-task-fallback",
+                        },
+                    });
+                }
+                const existingNode = await this.taskRegistry.getTaskNode(taskNodeId);
+                if (!existingNode) {
+                    await this.taskRegistry.createTaskNode({
+                        id: taskNodeId,
+                        threadId: taskCtx.threadId,
+                        kind: "execution",
+                        status: "running",
+                        title: context.label,
+                        instructions: context.originalTask,
+                        requiredCapabilities: [context.agentType],
+                        assignedSessionId: sessionId,
+                        assignedLabel: context.label,
+                        agentType: context.agentType,
+                        workdir: context.workdir,
+                        repo: context.repo,
+                        createdFrom: context.taskNodeId
+                            ? "register-task-existing-node"
+                            : "register-task-fallback",
+                        metadata: {
+                            providerSource: context.providerSource ?? null,
+                        },
+                    });
+                }
+                else if (existingNode.threadId !== taskCtx.threadId) {
+                    throw new Error(`Task node ${taskNodeId} belongs to ${existingNode.threadId}, expected ${taskCtx.threadId}`);
+                }
+                await Promise.all([
+                    this.taskRegistry.registerSession({
+                        threadId: taskCtx.threadId,
+                        sessionId,
+                        framework: context.agentType,
+                        providerSource: context.providerSource,
+                        label: context.label,
+                        originalTask: context.originalTask,
+                        workdir: context.workdir,
+                        repo: context.repo,
+                        status: "active",
+                        decisionCount: 0,
+                        autoResolvedCount: 0,
+                        registeredAt: taskCtx.registeredAt,
+                        lastActivityAt: taskCtx.lastActivityAt,
+                        idleCheckCount: taskCtx.idleCheckCount,
+                        taskDelivered: false,
+                        lastSeenDecisionIndex: 0,
+                        metadata: {
+                            ...(context.metadata ?? {}),
+                            taskNodeId,
+                        },
+                    }),
+                    this.taskRegistry.updateTaskNode(taskNodeId, {
+                        status: "running",
+                        title: context.label,
+                        instructions: context.originalTask,
+                        assignedSessionId: sessionId,
+                        assignedLabel: context.label,
+                        agentType: context.agentType,
+                        workdir: context.workdir,
+                        repo: context.repo,
+                        metadata: {
+                            providerSource: context.providerSource ?? null,
+                        },
+                    }),
+                    this.taskRegistry.createTaskClaim({
+                        threadId,
+                        nodeId: taskNodeId,
+                        sessionId,
+                        claimType: "execution",
+                        status: "active",
+                        metadata: {
+                            label: context.label,
+                        },
+                    }),
+                    this.taskRegistry.appendEvent({
+                        threadId,
+                        sessionId,
+                        eventType: "task_registered",
+                        timestamp: Date.now(),
+                        summary: `Registered task "${context.label}"`,
+                        data: {
+                            label: context.label,
+                            originalTask: context.originalTask,
+                            repo: context.repo ?? null,
+                            taskNodeId,
+                        },
+                    }),
+                ]);
+            })()
+            : Promise.resolve();
+        void persistPromise.catch((err) => {
+            this.log(`Failed to persist task registration for ${sessionId}: ${err}`);
+        });
+        this.broadcast({
+            type: "task_registered",
+            sessionId,
+            timestamp: Date.now(),
+            data: {
+                agentType: context.agentType,
+                label: context.label,
+                originalTask: context.originalTask,
+            },
+        });
+        // Cancel any pending retry timer and flush buffered events
+        const retryTimer = this.unregisteredRetryTimers.get(sessionId);
+        if (retryTimer) {
+            clearTimeout(retryTimer);
+            this.unregisteredRetryTimers.delete(sessionId);
+        }
+        const buffered = this.unregisteredBuffer.get(sessionId);
+        if (buffered) {
+            this.unregisteredBuffer.delete(sessionId);
+            for (const entry of buffered) {
+                this.handleNormalizedSessionEvent(entry.normalized).catch((err) => {
+                    this.log(`Error replaying buffered event: ${err}`);
+                });
+            }
+        }
+        await persistPromise;
+    }
+    /**
+     * Return the repo URL from the most recently registered task that had one.
+     * Useful as a fallback when the user says "in the same repo" without a URL.
+     */
+    /**
+     * Persisted separately from tasks so it survives task cleanup.
+     * Updated whenever a task with a repo is registered.
+     */
+    _lastUsedRepo;
+    getLastUsedRepo() {
+        // Check active tasks first (freshest), fall back to in-memory persisted value
+        let latest;
+        for (const task of this.tasks.values()) {
+            if (task.repo && (!latest || task.registeredAt > latest.registeredAt)) {
+                latest = task;
+            }
+        }
+        return latest?.repo ?? this._lastUsedRepo;
+    }
+    /**
+     * Async version that also checks disk history — survives process restarts.
+     * Callers that can await should prefer this over the sync version.
+     */
+    async getLastUsedRepoAsync() {
+        const memoryRepo = this.getLastUsedRepo();
+        if (memoryRepo)
+            return memoryRepo;
+        try {
+            return ((await this.taskRegistry.getLastUsedRepo()) ??
+                (await this.history.getLastUsedRepo()));
+        }
+        catch {
+            return undefined;
+        }
+    }
+    getTaskContext(sessionId) {
+        return this.tasks.get(sessionId);
+    }
+    mapDecisionRecord(record) {
+        return {
+            timestamp: record.timestamp,
+            event: record.event,
+            promptText: record.promptText,
+            decision: record.decision,
+            ...(record.response ? { response: record.response } : {}),
+            reasoning: record.reasoning,
+        };
+    }
+    mapSessionStatus(status) {
+        switch (status) {
+            case "blocked":
+            case "waiting_on_user":
+                return "blocked";
+            case "tool_running":
+                return "tool_running";
+            case "completed":
+                return "completed";
+            case "error":
+                return "error";
+            case "stopped":
+            case "interrupted":
+                return "stopped";
+            default:
+                return "active";
+        }
+    }
+    mapTaskContextStatusToNodeStatus(status) {
+        switch (status) {
+            case "blocked":
+                return "blocked";
+            case "completed":
+                return "completed";
+            case "error":
+                return "failed";
+            case "stopped":
+                return "interrupted";
+            case "tool_running":
+                return "running";
+            default:
+                return "running";
+        }
+    }
+    buildTaskContextFromSession(session, decisions) {
+        return {
+            threadId: session.threadId,
+            ...(typeof session.metadata.taskNodeId === "string" &&
+                session.metadata.taskNodeId.trim().length > 0
+                ? { taskNodeId: session.metadata.taskNodeId }
+                : {}),
+            sessionId: session.sessionId,
+            agentType: session.framework,
+            label: session.label,
+            originalTask: session.originalTask,
+            workdir: session.workdir,
+            ...(session.repo ? { repo: session.repo } : {}),
+            status: this.mapSessionStatus(session.status),
+            decisions: decisions.map((decision) => this.mapDecisionRecord(decision)),
+            autoResolvedCount: session.autoResolvedCount,
+            registeredAt: session.registeredAt,
+            lastActivityAt: session.lastActivityAt,
+            idleCheckCount: session.idleCheckCount,
+            taskDelivered: session.taskDelivered,
+            ...(session.completionSummary
+                ? { completionSummary: session.completionSummary }
+                : {}),
+            lastSeenDecisionIndex: session.lastSeenDecisionIndex,
+            ...(session.lastInputSentAt !== null
+                ? { lastInputSentAt: session.lastInputSentAt }
+                : {}),
+            ...(session.stoppedAt !== null ? { stoppedAt: session.stoppedAt } : {}),
+        };
+    }
+    async getTaskContextSnapshot(sessionId) {
+        const live = this.tasks.get(sessionId);
+        if (live)
+            return live;
+        const session = await this.taskRegistry.getSession(sessionId);
+        if (!session)
+            return null;
+        const decisions = await this.taskRegistry.listDecisionsForSession(sessionId);
+        return this.buildTaskContextFromSession(session, decisions);
+    }
+    getAllTaskContexts() {
+        return Array.from(this.tasks.values());
+    }
+    async createTaskThread(input) {
+        const normalizedInput = {
+            ...input,
+            kind: inferTaskThreadKind(input),
+        };
+        const acceptance = await deriveTaskAcceptanceCriteria(this.runtime, normalizedInput);
+        const thread = await this.taskRegistry.createThread({
+            ...normalizedInput,
+            acceptanceCriteria: acceptance.criteria,
+            metadata: {
+                ...(normalizedInput.metadata ?? {}),
+                acceptanceCriteriaSource: acceptance.source,
+            },
+        });
+        const summary = await this.taskRegistry.getThreadSummary(thread.id);
+        if (!summary) {
+            throw new Error(`Failed to load task thread ${thread.id}`);
+        }
+        return summary;
+    }
+    async planTaskThreadGraph(input) {
+        const thread = await this.taskRegistry.getThreadRecord(input.threadId);
+        if (!thread) {
+            throw new Error(`Task thread ${input.threadId} not found`);
+        }
+        const rootNode = await this.taskRegistry.createTaskNode({
+            threadId: input.threadId,
+            parentNodeId: null,
+            kind: "goal",
+            status: "planned",
+            title: input.title,
+            instructions: input.originalRequest,
+            acceptanceCriteria: thread.acceptanceCriteria,
+            priority: 100,
+            depth: 0,
+            sequence: 0,
+            createdFrom: "planner",
+            metadata: {
+                threadKind: thread.kind,
+                source: "swarm-planner",
+            },
+        });
+        // The acceptance verifier is a code-completion safety check: it asks the
+        // LLM whether file/test evidence in the workspace matches the criteria,
+        // catching agents that lie about completing code work. It's only useful
+        // when there is real artifact evidence to verify (a repo) AND real
+        // criteria to check against (provided or model-generated, not the
+        // baseline placeholder fallback). For chat / question-answering tasks
+        // (no repo, response IS the deliverable) the verifier produces false
+        // failures because there are no files to inspect.
+        const acceptanceCriteriaSource = typeof thread.metadata?.acceptanceCriteriaSource === "string"
+            ? thread.metadata.acceptanceCriteriaSource
+            : null;
+        const hasRepo = typeof thread.metadata?.repo === "string" &&
+            thread.metadata.repo.trim().length > 0;
+        if (thread.acceptanceCriteria.length > 0 &&
+            acceptanceCriteriaSource !== "baseline" &&
+            hasRepo) {
+            await this.taskRegistry.createTaskVerifierJob({
+                threadId: input.threadId,
+                nodeId: rootNode.id,
+                status: "pending",
+                verifierType: "acceptance_criteria",
+                title: `Verify acceptance criteria for ${input.title}`,
+                instructions: thread.acceptanceCriteria.join("\n"),
+                config: {
+                    acceptanceCriteria: thread.acceptanceCriteria,
+                },
+                metadata: {
+                    source: "thread-acceptance",
+                },
+            });
+        }
+        if (input.sharedContext?.trim()) {
+            await this.taskRegistry.appendTaskMailboxMessage({
+                threadId: input.threadId,
+                nodeId: rootNode.id,
+                sender: "planner",
+                recipient: "all-workers",
+                subject: "shared-context",
+                body: input.sharedContext.trim(),
+                deliveryState: "delivered",
+                deliveredAt: new Date().toISOString(),
+                metadata: {
+                    source: "swarm-planner",
+                },
+            });
+        }
+        const workerNodes = [];
+        for (const [index, subtask] of input.subtasks.entries()) {
+            const node = await this.taskRegistry.createTaskNode({
+                threadId: input.threadId,
+                parentNodeId: rootNode.id,
+                kind: "execution",
+                status: "ready",
+                title: subtask.label,
+                instructions: subtask.originalTask,
+                requiredCapabilities: [subtask.agentType],
+                repo: subtask.repo,
+                priority: 10,
+                depth: 1,
+                sequence: index + 1,
+                createdFrom: "planner",
+                metadata: {
+                    agentType: subtask.agentType,
+                    source: "swarm-planner",
+                },
+            });
+            await this.taskRegistry.createTaskDependency({
+                threadId: input.threadId,
+                fromNodeId: node.id,
+                toNodeId: rootNode.id,
+                dependencyKind: "parent_child",
+                requiredStatus: "completed",
+                metadata: {
+                    source: "swarm-planner",
+                },
+            });
+            if (input.sharedContext?.trim()) {
+                await this.taskRegistry.appendTaskMailboxMessage({
+                    threadId: input.threadId,
+                    nodeId: node.id,
+                    sender: "planner",
+                    recipient: subtask.label,
+                    subject: "task-brief",
+                    body: input.sharedContext.trim(),
+                    deliveryState: "delivered",
+                    deliveredAt: new Date().toISOString(),
+                    metadata: {
+                        task: subtask.originalTask,
+                        agentType: subtask.agentType,
+                    },
+                });
+            }
+            workerNodes.push(node);
+        }
+        await this.taskRegistry.updateThread(input.threadId, {
+            currentPlan: {
+                ...thread.currentPlan,
+                rootTaskNodeId: rootNode.id,
+                taskNodeIds: workerNodes.map((node) => node.id),
+                taskNodeCount: workerNodes.length + 1,
+            },
+        });
+        return { rootNode, workerNodes };
+    }
+    async listTaskThreads(options) {
+        return this.taskRegistry.listThreads(options);
+    }
+    async getTaskThread(threadId) {
+        return this.taskRegistry.getThread(threadId);
+    }
+    async archiveTaskThread(threadId) {
+        await this.taskRegistry.archiveThread(threadId);
+    }
+    async reopenTaskThread(threadId) {
+        await this.taskRegistry.reopenThread(threadId);
+    }
+    async countTaskThreads(options) {
+        return this.taskRegistry.countThreads(options);
+    }
+    getLiveTaskContextsForThread(threadId) {
+        return Array.from(this.tasks.values())
+            .filter((task) => task.threadId === threadId)
+            .sort((left, right) => right.lastActivityAt - left.lastActivityAt);
+    }
+    async stopLiveThreadSessions(threadId, force) {
+        if (!this.ptyService) {
+            return [];
+        }
+        const sessionIds = this.getLiveTaskContextsForThread(threadId)
+            .filter((task) => task.status === "active" ||
+            task.status === "blocked" ||
+            task.status === "tool_running")
+            .map((task) => task.sessionId);
+        for (const sessionId of sessionIds) {
+            const taskCtx = this.tasks.get(sessionId);
+            if (taskCtx) {
+                taskCtx.status = "stopped";
+                taskCtx.stoppedAt = Date.now();
+                await this.syncTaskContext(taskCtx);
+            }
+            try {
+                await this.ptyService.stopSession(sessionId, force);
+            }
+            catch (error) {
+                this.log(`Failed to stop session ${sessionId} for thread ${threadId}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        return sessionIds;
+    }
+    clipText(value, limit) {
+        if (value.length <= limit)
+            return value;
+        return `${value.slice(0, limit)}…`;
+    }
+    formatResumePrompt(thread, instruction) {
+        const acceptanceCriteria = (thread.acceptanceCriteria ?? [])
+            .map((item) => `- ${item}`)
+            .join("\n");
+        const recentDecisions = (thread.decisions ?? [])
+            .slice(-6)
+            .map((decision, index) => `${index + 1}. ${decision.event}: ${decision.reasoning}${decision.response ? ` (response: ${decision.response})` : ""}`)
+            .join("\n");
+        const recentEvents = (thread.events ?? [])
+            .slice(-8)
+            .map((event, index) => `${index + 1}. ${event.eventType}: ${this.clipText(event.summary, 180)}`)
+            .join("\n");
+        const transcriptExcerpt = (thread.transcripts ?? [])
+            .slice(-20)
+            .map((entry) => `${entry.direction.toUpperCase()}: ${this.clipText(entry.content.trim(), 220)}`)
+            .filter((line) => line.length > 0)
+            .join("\n");
+        const latestSession = (thread.sessions ?? [])
+            .slice()
+            .sort((left, right) => right.lastActivityAt - left.lastActivityAt)[0];
+        return [
+            "Resume an existing Eliza coordinator task thread.",
+            "",
+            `Thread: ${thread.title}`,
+            `Original request: ${thread.originalRequest}`,
+            latestSession?.workdir ? `Workspace: ${latestSession.workdir}` : "",
+            latestSession?.repo ? `Repository: ${latestSession.repo}` : "",
+            thread.summary ? `Current summary: ${thread.summary}` : "",
+            acceptanceCriteria ? `Acceptance criteria:\n${acceptanceCriteria}` : "",
+            instruction?.trim()
+                ? `Latest user instruction:\n${instruction.trim()}`
+                : "Continue from the current workspace state without starting over.",
+            recentDecisions
+                ? `Recent coordinator decisions:\n${recentDecisions}`
+                : "",
+            recentEvents ? `Recent task events:\n${recentEvents}` : "",
+            transcriptExcerpt
+                ? `Recent transcript excerpt:\n${transcriptExcerpt}`
+                : "",
+            "Inspect the current workspace, continue the task, run the relevant verification, and summarize what changed.",
+        ]
+            .filter(Boolean)
+            .join("\n\n");
+    }
+    async pauseTaskThread(threadId, note) {
+        const thread = await this.getTaskThread(threadId);
+        if (!thread) {
+            throw new Error(`Task thread ${threadId} not found`);
+        }
+        const stoppedSessionIds = await this.stopLiveThreadSessions(threadId, true);
+        const nowIso = new Date().toISOString();
+        await this.taskRegistry.updateThread(threadId, {
+            status: "waiting_on_user",
+            closedAt: null,
+            lastCoordinatorTurnAt: nowIso,
+            metadata: {
+                controlState: "paused",
+                pauseNote: note ?? null,
+                pauseRequestedAt: nowIso,
+            },
+        });
+        await this.taskRegistry.appendEvent({
+            threadId,
+            eventType: "task_paused",
+            summary: note?.trim()
+                ? `Paused task thread: ${note.trim()}`
+                : "Paused task thread for user review",
+            data: {
+                note: note ?? null,
+                stoppedSessionIds,
+            },
+        });
+        return { threadId, stoppedSessionIds };
+    }
+    async stopTaskThread(threadId, note) {
+        const thread = await this.getTaskThread(threadId);
+        if (!thread) {
+            throw new Error(`Task thread ${threadId} not found`);
+        }
+        const stoppedSessionIds = await this.stopLiveThreadSessions(threadId, true);
+        const nowIso = new Date().toISOString();
+        await this.taskRegistry.updateThread(threadId, {
+            status: "interrupted",
+            closedAt: nowIso,
+            lastCoordinatorTurnAt: nowIso,
+            metadata: {
+                controlState: "stopped",
+                stopNote: note ?? null,
+                stoppedByUserAt: nowIso,
+            },
+        });
+        await this.taskRegistry.appendEvent({
+            threadId,
+            eventType: "task_stopped",
+            summary: note?.trim()
+                ? `Stopped task thread: ${note.trim()}`
+                : "Stopped task thread at user request",
+            data: {
+                note: note ?? null,
+                stoppedSessionIds,
+            },
+        });
+        return { threadId, stoppedSessionIds };
+    }
+    async resumeTaskThread(threadId, instruction, agentType) {
+        const thread = await this.getTaskThread(threadId);
+        if (!thread) {
+            throw new Error(`Task thread ${threadId} not found`);
+        }
+        if (!this.ptyService) {
+            throw new Error("PTY Service is not available");
+        }
+        const activeTask = this.getLiveTaskContextsForThread(threadId).find((task) => task.status !== "stopped" &&
+            task.status !== "completed" &&
+            task.status !== "error");
+        if (activeTask) {
+            if (instruction?.trim()) {
+                await this.ptyService.sendToSession(activeTask.sessionId, instruction.trim());
+                activeTask.lastInputSentAt = Date.now();
+                activeTask.status = "active";
+                await this.syncTaskContext(activeTask);
+            }
+            const nowIso = new Date().toISOString();
+            await this.taskRegistry.updateThread(threadId, {
+                status: "active",
+                closedAt: null,
+                lastCoordinatorTurnAt: nowIso,
+                metadata: {
+                    controlState: null,
+                    resumedAt: nowIso,
+                },
+            });
+            await this.taskRegistry.appendEvent({
+                threadId,
+                sessionId: activeTask.sessionId,
+                eventType: "task_resumed",
+                summary: "Continued the active task thread",
+                data: {
+                    reusedSession: true,
+                    instruction: instruction ?? null,
+                },
+            });
+            return {
+                threadId,
+                sessionId: activeTask.sessionId,
+                reusedSession: true,
+                framework: activeTask.agentType,
+            };
+        }
+        const latestSession = (thread.sessions ?? [])
+            .slice()
+            .sort((left, right) => right.lastActivityAt - left.lastActivityAt)[0];
+        const workdir = latestSession?.workdir ?? thread.latestWorkdir;
+        if (!workdir) {
+            throw new Error(`Task thread ${threadId} has no resumable workspace`);
+        }
+        const requestedFramework = agentType
+            ? normalizeAgentType(agentType)
+            : latestSession?.framework
+                ? normalizeAgentType(latestSession.framework)
+                : normalizeAgentType(await this.ptyService.resolveAgentType());
+        const frameworkState = await this.ptyService.getFrameworkState();
+        const framework = frameworkState.frameworks.find((entry) => entry.id === requestedFramework);
+        const resolvedFramework = framework?.installed &&
+            framework.authReady &&
+            !framework.temporarilyDisabled
+            ? requestedFramework
+            : normalizeAgentType(await this.ptyService.resolveAgentType());
+        const resolvedAvailability = frameworkState.frameworks.find((entry) => entry.id === resolvedFramework);
+        const session = await this.ptyService.spawnSession({
+            name: `task-resume-${thread.id.slice(-8)}`,
+            agentType: resolvedFramework,
+            workdir,
+            initialTask: this.formatResumePrompt(thread, instruction),
+            credentials: buildAgentCredentials(this.runtime),
+            approvalPreset: this.ptyService.defaultApprovalPreset,
+            skipAdapterAutoResponse: true,
+            metadata: {
+                threadId,
+                label: thread.title,
+                requestedType: resolvedFramework,
+                resumedFromThreadId: threadId,
+                resumedFromSessionId: latestSession?.sessionId ?? null,
+                resumeInstruction: instruction ?? null,
+                resumedAt: Date.now(),
+            },
+        });
+        await this.registerTask(session.id, {
+            threadId,
+            taskNodeId: typeof latestSession?.metadata.taskNodeId === "string"
+                ? latestSession.metadata.taskNodeId
+                : undefined,
+            agentType: resolvedFramework,
+            label: latestSession?.label ?? thread.title,
+            originalTask: instruction?.trim() || thread.originalRequest,
+            workdir,
+            repo: latestSession?.repo ?? thread.latestRepo ?? undefined,
+            providerSource: resolvedAvailability
+                ? inferProviderSource(resolvedAvailability)
+                : null,
+            metadata: session.metadata &&
+                typeof session.metadata === "object" &&
+                !Array.isArray(session.metadata)
+                ? session.metadata
+                : undefined,
+        });
+        const nowIso = new Date().toISOString();
+        await this.taskRegistry.updateThread(threadId, {
+            status: "active",
+            closedAt: null,
+            lastCoordinatorTurnAt: nowIso,
+            metadata: {
+                controlState: null,
+                resumedAt: nowIso,
+                lastResumedSessionId: session.id,
+            },
+        });
+        await this.taskRegistry.appendEvent({
+            threadId,
+            sessionId: session.id,
+            eventType: "task_resumed",
+            summary: "Resumed the task thread on a new session",
+            data: {
+                reusedSession: false,
+                fromSessionId: latestSession?.sessionId ?? null,
+                toSessionId: session.id,
+                instruction: instruction ?? null,
+                framework: resolvedFramework,
+            },
+        });
+        return {
+            threadId,
+            sessionId: session.id,
+            reusedSession: false,
+            framework: resolvedFramework,
+        };
+    }
+    async continueTaskThread(threadId, instruction, agentType) {
+        const latestLiveTask = this.getLiveTaskContextsForThread(threadId).find((task) => task.status === "active" ||
+            task.status === "blocked" ||
+            task.status === "tool_running");
+        if (latestLiveTask && this.ptyService) {
+            await this.ptyService.sendToSession(latestLiveTask.sessionId, instruction);
+            latestLiveTask.lastInputSentAt = Date.now();
+            latestLiveTask.status = "active";
+            await this.syncTaskContext(latestLiveTask);
+            const nowIso = new Date().toISOString();
+            await this.taskRegistry.updateThread(threadId, {
+                status: "active",
+                closedAt: null,
+                lastCoordinatorTurnAt: nowIso,
+                metadata: {
+                    controlState: null,
+                    continuedAt: nowIso,
+                },
+            });
+            await this.taskRegistry.appendEvent({
+                threadId,
+                sessionId: latestLiveTask.sessionId,
+                eventType: "task_resumed",
+                summary: "Sent follow-up instructions to the active task thread",
+                data: {
+                    reusedSession: true,
+                    instruction,
+                },
+            });
+            return {
+                threadId,
+                sessionId: latestLiveTask.sessionId,
+                reusedSession: true,
+                framework: latestLiveTask.agentType,
+            };
+        }
+        return this.resumeTaskThread(threadId, instruction, agentType);
+    }
+    async syncTaskContext(taskCtx) {
+        await this.taskRegistry.updateSession(taskCtx.sessionId, {
+            status: taskCtx.status === "completed"
+                ? "completed"
+                : taskCtx.status === "error"
+                    ? "error"
+                    : taskCtx.status === "stopped"
+                        ? "stopped"
+                        : taskCtx.status === "blocked"
+                            ? "blocked"
+                            : taskCtx.status === "tool_running"
+                                ? "tool_running"
+                                : "active",
+            decisionCount: taskCtx.decisions.length,
+            autoResolvedCount: taskCtx.autoResolvedCount,
+            lastActivityAt: taskCtx.lastActivityAt,
+            idleCheckCount: taskCtx.idleCheckCount,
+            taskDelivered: taskCtx.taskDelivered,
+            completionSummary: taskCtx.completionSummary ?? null,
+            lastSeenDecisionIndex: taskCtx.lastSeenDecisionIndex,
+            lastInputSentAt: taskCtx.lastInputSentAt,
+            stoppedAt: taskCtx.stoppedAt,
+        });
+        if (!taskCtx.taskNodeId) {
+            return;
+        }
+        const nodeStatus = this.mapTaskContextStatusToNodeStatus(taskCtx.status);
+        await this.taskRegistry.updateTaskNode(taskCtx.taskNodeId, {
+            status: nodeStatus,
+            title: taskCtx.label,
+            instructions: taskCtx.originalTask,
+            assignedSessionId: taskCtx.sessionId,
+            assignedLabel: taskCtx.label,
+            agentType: taskCtx.agentType,
+            workdir: taskCtx.workdir,
+            repo: taskCtx.repo ?? null,
+            metadata: {
+                completionSummary: taskCtx.completionSummary ?? null,
+            },
+        });
+        const activeClaim = await this.taskRegistry.findActiveTaskClaim(taskCtx.taskNodeId, taskCtx.sessionId);
+        if (taskCtx.status === "completed" ||
+            taskCtx.status === "error" ||
+            taskCtx.status === "stopped") {
+            if (activeClaim) {
+                await this.taskRegistry.updateTaskClaim(activeClaim.id, {
+                    status: taskCtx.status === "completed"
+                        ? "completed"
+                        : taskCtx.status === "error"
+                            ? "failed"
+                            : "interrupted",
+                    releasedAt: new Date().toISOString(),
+                    metadata: {
+                        completionSummary: taskCtx.completionSummary ?? null,
+                    },
+                });
+            }
+            return;
+        }
+        if (!activeClaim) {
+            await this.taskRegistry.createTaskClaim({
+                threadId: taskCtx.threadId,
+                nodeId: taskCtx.taskNodeId,
+                sessionId: taskCtx.sessionId,
+                claimType: "execution",
+                status: "active",
+                metadata: {
+                    label: taskCtx.label,
+                },
+            });
+        }
+    }
+    isAutomaticFailoverFramework(agentType) {
+        return (agentType === "claude" ||
+            agentType === "codex" ||
+            agentType === "gemini" ||
+            agentType === "aider");
+    }
+    getFailoverCandidates(frameworks, failedFramework, preferredFrameworkId) {
+        const preferred = frameworks.find((framework) => framework.id === preferredFrameworkId);
+        const remainder = frameworks.filter((framework) => framework.id !== preferredFrameworkId);
+        return [preferred, ...remainder].filter((framework) => Boolean(framework &&
+            framework.id !== failedFramework &&
+            framework.installed &&
+            framework.authReady &&
+            !framework.temporarilyDisabled));
+    }
+    getRecoveryCandidates(frameworks, currentFramework, preferredFrameworkId, preferAlternative) {
+        const healthy = frameworks.filter((framework) => framework.installed &&
+            framework.authReady &&
+            !framework.temporarilyDisabled);
+        const byId = new Map(healthy.map((framework) => [framework.id, framework]));
+        const orderedIds = [];
+        if (!preferAlternative) {
+            orderedIds.push(currentFramework);
+        }
+        orderedIds.push(preferredFrameworkId);
+        for (const framework of healthy) {
+            orderedIds.push(framework.id);
+        }
+        const seen = new Set();
+        const candidates = [];
+        for (const id of orderedIds) {
+            if (seen.has(id)) {
+                continue;
+            }
+            seen.add(id);
+            if (preferAlternative && id === currentFramework) {
+                continue;
+            }
+            const framework = byId.get(id);
+            if (framework) {
+                candidates.push(framework);
+            }
+        }
+        return candidates;
+    }
+    shouldPreferAlternativeFrameworkForError(reason) {
+        return ALTERNATE_FRAMEWORK_ERROR_RE.test(reason);
+    }
+    formatFailoverPrompt(taskCtx, failedFramework, reason, recentOutput) {
+        const cleanedOutput = cleanForFailoverContext(recentOutput, taskCtx.workdir);
+        const trimmedOutput = cleanedOutput.trim();
+        const clippedOutput = trimmedOutput.length > FAILOVER_OUTPUT_MAX_CHARS
+            ? trimmedOutput.slice(-FAILOVER_OUTPUT_MAX_CHARS)
+            : trimmedOutput;
+        const recentDecisions = taskCtx.decisions
+            .slice(-5)
+            .map((decision, index) => `${index + 1}. ${decision.event}: ${decision.reasoning}${decision.response ? ` (response: ${decision.response})` : ""}`)
+            .join("\n");
+        return [
+            `Continue an in-progress task after the previous ${failedFramework} session became unavailable because of a quota or credit failure.`,
+            "",
+            "Original task:",
+            taskCtx.originalTask,
+            "",
+            `Failure reason: ${reason}`,
+            `Workspace: ${taskCtx.workdir}`,
+            "",
+            recentDecisions
+                ? `Recent coordinator decisions:\n${recentDecisions}\n`
+                : "",
+            clippedOutput
+                ? `Recent terminal output from the failed session:\n${clippedOutput}\n`
+                : "",
+            "Use the existing workspace state instead of starting from scratch. Inspect the files, continue the task, run the needed validation, and then report what changed and how you verified it.",
+        ]
+            .filter(Boolean)
+            .join("\n");
+    }
+    formatErrorRecoveryPrompt(taskCtx, recoveryFramework, reason, recentOutput) {
+        const cleanedOutput = cleanForFailoverContext(recentOutput, taskCtx.workdir);
+        const trimmedOutput = cleanedOutput.trim();
+        const clippedOutput = trimmedOutput.length > FAILOVER_OUTPUT_MAX_CHARS
+            ? trimmedOutput.slice(-FAILOVER_OUTPUT_MAX_CHARS)
+            : trimmedOutput;
+        const recentDecisions = taskCtx.decisions
+            .slice(-5)
+            .map((decision, index) => `${index + 1}. ${decision.event}: ${decision.reasoning}${decision.response ? ` (response: ${decision.response})` : ""}`)
+            .join("\n");
+        const recoveryMode = recoveryFramework === taskCtx.agentType
+            ? `a fresh ${recoveryFramework} session`
+            : `a ${recoveryFramework} recovery session`;
+        return [
+            `Continue an in-progress task after the previous session terminated unexpectedly. Eliza started ${recoveryMode} for recovery.`,
+            "",
+            "Original task:",
+            taskCtx.originalTask,
+            "",
+            `Failure reason: ${reason}`,
+            `Workspace: ${taskCtx.workdir}`,
+            "",
+            recentDecisions
+                ? `Recent coordinator decisions:\n${recentDecisions}\n`
+                : "",
+            clippedOutput
+                ? `Recent terminal output from the failed session:\n${clippedOutput}\n`
+                : "",
+            "Use the existing workspace state instead of starting over. Inspect the current files, recover from the failure, continue the task, run the needed validation, and then report exactly what changed and how you verified it.",
+        ]
+            .filter(Boolean)
+            .join("\n");
+    }
+    async handleFrameworkDepletion(taskCtx, sessionId, reason) {
+        if (!this.isAutomaticFailoverFramework(taskCtx.agentType) ||
+            !isUsageExhaustedTaskAgentError(reason)) {
+            return null;
+        }
+        markTaskAgentFrameworkUnavailable(taskCtx.agentType, reason);
+        await this.taskRegistry.appendEvent({
+            threadId: taskCtx.threadId,
+            sessionId,
+            eventType: "framework_unavailable",
+            summary: `${taskCtx.agentType} temporarily disabled after provider depletion`,
+            data: {
+                framework: taskCtx.agentType,
+                reason,
+            },
+        });
+        let failoverResult = null;
+        try {
+            failoverResult = await this.attemptTaskFailover(taskCtx, reason);
+        }
+        catch (failoverError) {
+            this.log(`Automatic failover failed for "${taskCtx.label}": ${failoverError instanceof Error ? failoverError.message : String(failoverError)}`);
+        }
+        if (failoverResult) {
+            this.sendChatMessage(`"${taskCtx.label}" ran into a ${taskCtx.agentType} quota/credit failure. Eliza is continuing the same task on ${failoverResult.replacementFramework}.`, "coding-agent");
+        }
+        else {
+            this.sendChatMessage(`"${taskCtx.label}" ran into a ${taskCtx.agentType} quota/credit failure. Eliza will prefer another task-agent framework until ${taskCtx.agentType} is healthy again.`, "coding-agent");
+        }
+        return failoverResult;
+    }
+    async attemptTaskFailover(taskCtx, errorMsg) {
+        if (!this.ptyService ||
+            !this.isAutomaticFailoverFramework(taskCtx.agentType)) {
+            return null;
+        }
+        const frameworkState = await this.ptyService.getFrameworkState();
+        const candidates = this.getFailoverCandidates(frameworkState.frameworks, taskCtx.agentType, frameworkState.preferred.id);
+        const nextFramework = candidates[0];
+        if (!nextFramework) {
+            return null;
+        }
+        const failedSession = this.ptyService.getSession(taskCtx.sessionId);
+        const priorMetadata = failedSession?.metadata &&
+            typeof failedSession.metadata === "object" &&
+            !Array.isArray(failedSession.metadata)
+            ? failedSession.metadata
+            : {};
+        const failoverOrdinal = typeof priorMetadata.failoverOrdinal === "number"
+            ? priorMetadata.failoverOrdinal + 1
+            : 1;
+        const priorOutput = await Promise.race([
+            this.ptyService.getSessionOutput(taskCtx.sessionId, 200),
+            new Promise((resolve) => setTimeout(() => resolve(""), 5_000)),
+        ]);
+        const replacementLabel = `${taskCtx.label} (${nextFramework.id} failover ${failoverOrdinal})`;
+        const replacementSession = await this.ptyService.spawnSession({
+            name: failedSession?.name ??
+                `task-failover-${Date.now()}-${nextFramework.id}`,
+            agentType: nextFramework.id,
+            workdir: taskCtx.workdir,
+            initialTask: this.formatFailoverPrompt(taskCtx, taskCtx.agentType, errorMsg, priorOutput),
+            approvalPreset: this.ptyService.defaultApprovalPreset,
+            skipAdapterAutoResponse: true,
+            metadata: {
+                ...priorMetadata,
+                threadId: taskCtx.threadId,
+                requestedType: nextFramework.id,
+                label: replacementLabel,
+                failoverOrdinal,
+                failoverFromFramework: taskCtx.agentType,
+                failoverFromSessionId: taskCtx.sessionId,
+                failoverReason: errorMsg,
+                failoverAt: Date.now(),
+            },
+        });
+        await this.registerTask(replacementSession.id, {
+            threadId: taskCtx.threadId,
+            taskNodeId: taskCtx.taskNodeId,
+            agentType: nextFramework.id,
+            label: replacementLabel,
+            originalTask: taskCtx.originalTask,
+            workdir: taskCtx.workdir,
+            repo: taskCtx.repo,
+            providerSource: inferProviderSource(nextFramework),
+            metadata: replacementSession.metadata &&
+                typeof replacementSession.metadata === "object" &&
+                !Array.isArray(replacementSession.metadata)
+                ? replacementSession.metadata
+                : undefined,
+        });
+        await this.taskRegistry.appendEvent({
+            threadId: taskCtx.threadId,
+            sessionId: replacementSession.id,
+            eventType: "framework_failover_started",
+            summary: `Continuing "${taskCtx.label}" on ${nextFramework.label}`,
+            data: {
+                fromFramework: taskCtx.agentType,
+                fromSessionId: taskCtx.sessionId,
+                toFramework: nextFramework.id,
+                toSessionId: replacementSession.id,
+                reason: errorMsg,
+            },
+        });
+        return {
+            replacementSessionId: replacementSession.id,
+            replacementFramework: nextFramework.id,
+            replacementLabel,
+        };
+    }
+    async attemptTaskRecovery(taskCtx, errorMsg) {
+        if (!this.ptyService) {
+            return null;
+        }
+        const failedSession = this.ptyService.getSession(taskCtx.sessionId);
+        const priorMetadata = failedSession?.metadata &&
+            typeof failedSession.metadata === "object" &&
+            !Array.isArray(failedSession.metadata)
+            ? failedSession.metadata
+            : {};
+        const recoveryOrdinal = typeof priorMetadata.recoveryOrdinal === "number"
+            ? priorMetadata.recoveryOrdinal + 1
+            : 1;
+        if (recoveryOrdinal > MAX_AUTOMATIC_ERROR_RECOVERIES) {
+            return null;
+        }
+        let recoveryFramework = taskCtx.agentType;
+        let recoveryAvailability = null;
+        if (this.isAutomaticFailoverFramework(taskCtx.agentType)) {
+            const frameworkState = await this.ptyService.getFrameworkState();
+            const candidates = this.getRecoveryCandidates(frameworkState.frameworks, taskCtx.agentType, frameworkState.preferred.id, this.shouldPreferAlternativeFrameworkForError(errorMsg));
+            const selected = candidates[0];
+            if (!selected) {
+                return null;
+            }
+            recoveryFramework = selected.id;
+            recoveryAvailability = selected;
+        }
+        const priorOutput = await Promise.race([
+            this.ptyService.getSessionOutput(taskCtx.sessionId, 200),
+            new Promise((resolve) => setTimeout(() => resolve(""), 5_000)),
+        ]);
+        const replacementLabel = `${taskCtx.label} (${recoveryFramework} recovery ${recoveryOrdinal})`;
+        const replacementSession = await this.ptyService.spawnSession({
+            name: failedSession?.name ??
+                `task-recovery-${Date.now()}-${recoveryFramework}`,
+            agentType: recoveryFramework,
+            workdir: taskCtx.workdir,
+            initialTask: this.formatErrorRecoveryPrompt(taskCtx, recoveryFramework, errorMsg, priorOutput),
+            credentials: buildAgentCredentials(this.runtime),
+            approvalPreset: this.ptyService.defaultApprovalPreset,
+            skipAdapterAutoResponse: true,
+            metadata: {
+                ...priorMetadata,
+                threadId: taskCtx.threadId,
+                requestedType: recoveryFramework,
+                label: replacementLabel,
+                recoveryOrdinal,
+                recoveredFromFramework: taskCtx.agentType,
+                recoveredFromSessionId: taskCtx.sessionId,
+                recoveryReason: errorMsg,
+                recoveryAt: Date.now(),
+            },
+        });
+        await this.registerTask(replacementSession.id, {
+            threadId: taskCtx.threadId,
+            taskNodeId: taskCtx.taskNodeId,
+            agentType: recoveryFramework,
+            label: replacementLabel,
+            originalTask: taskCtx.originalTask,
+            workdir: taskCtx.workdir,
+            repo: taskCtx.repo,
+            providerSource: recoveryAvailability
+                ? inferProviderSource(recoveryAvailability)
+                : null,
+            metadata: replacementSession.metadata &&
+                typeof replacementSession.metadata === "object" &&
+                !Array.isArray(replacementSession.metadata)
+                ? replacementSession.metadata
+                : undefined,
+        });
+        await this.taskRegistry.appendEvent({
+            threadId: taskCtx.threadId,
+            sessionId: replacementSession.id,
+            eventType: "task_error_recovery_started",
+            summary: `Continuing "${taskCtx.label}" after an agent error`,
+            data: {
+                fromFramework: taskCtx.agentType,
+                fromSessionId: taskCtx.sessionId,
+                toFramework: recoveryFramework,
+                toSessionId: replacementSession.id,
+                reason: errorMsg,
+                recoveryOrdinal,
+            },
+        });
+        this.broadcast({
+            type: "task_recovery_started",
+            sessionId: replacementSession.id,
+            timestamp: Date.now(),
+            data: {
+                fromSessionId: taskCtx.sessionId,
+                fromFramework: taskCtx.agentType,
+                toFramework: recoveryFramework,
+                reason: errorMsg,
+            },
+        });
+        return {
+            replacementSessionId: replacementSession.id,
+            replacementFramework: recoveryFramework,
+            replacementLabel,
+        };
+    }
+    async resumeTaskAfterProviderAuth(sessionId, reason) {
+        const taskCtx = this.tasks.get(sessionId);
+        if (!taskCtx) {
+            return null;
+        }
+        if (taskCtx.status === "completed" ||
+            taskCtx.status === "error" ||
+            taskCtx.status === "stopped") {
+            return null;
+        }
+        const replacement = await this.attemptTaskRecovery(taskCtx, reason);
+        if (!replacement) {
+            return null;
+        }
+        taskCtx.suppressStopNotice = true;
+        taskCtx.status = "stopped";
+        try {
+            await this.ptyService?.stopSession(sessionId, true);
+        }
+        catch (error) {
+            this.log(`Failed to stop superseded auth-blocked session ${sessionId}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        this.sendChatMessage(`"${taskCtx.label}" recovered after provider authentication and is continuing on ${replacement.replacementFramework}.`, "coding-agent");
+        return replacement;
+    }
+    async markTaskResumedAfterProviderAuth(sessionId) {
+        const taskCtx = this.tasks.get(sessionId);
+        if (!taskCtx) {
+            return false;
+        }
+        if (taskCtx.status === "completed" ||
+            taskCtx.status === "error" ||
+            taskCtx.status === "stopped") {
+            return false;
+        }
+        taskCtx.status = "active";
+        taskCtx.stoppedAt = undefined;
+        taskCtx.lastActivityAt = Date.now();
+        taskCtx.idleCheckCount = 0;
+        if (taskCtx.agentType === "claude" ||
+            taskCtx.agentType === "codex" ||
+            taskCtx.agentType === "gemini" ||
+            taskCtx.agentType === "aider") {
+            markTaskAgentFrameworkHealthy(taskCtx.agentType);
+        }
+        this.broadcast({
+            type: "ready",
+            sessionId,
+            timestamp: Date.now(),
+            data: {
+                reason: "provider_auth_recovered",
+                source: "auth_recovery",
+            },
+        });
+        await this.taskRegistry.appendEvent({
+            threadId: taskCtx.threadId,
+            sessionId,
+            eventType: "task_status_changed",
+            summary: `Task "${taskCtx.label}" resumed after provider authentication`,
+            data: {
+                status: "active",
+                reason: "provider_auth_recovered",
+            },
+        });
+        this.sendChatMessage(`"${taskCtx.label}" refreshed provider authentication and is continuing automatically.`, "coding-agent");
+        return true;
+    }
+    async recordDecision(taskCtx, decision) {
+        taskCtx.decisions.push(decision);
+        await this.taskRegistry.recordDecision({
+            threadId: taskCtx.threadId,
+            sessionId: taskCtx.sessionId,
+            timestamp: decision.timestamp,
+            event: decision.event,
+            promptText: decision.promptText,
+            decision: decision.decision,
+            response: decision.response,
+            reasoning: decision.reasoning,
+        });
+        await this.syncTaskContext(taskCtx);
+    }
+    async setTaskDelivered(sessionId) {
+        const taskCtx = this.tasks.get(sessionId);
+        if (!taskCtx)
+            return;
+        taskCtx.taskDelivered = true;
+        await this.syncTaskContext(taskCtx);
+    }
+    // ─── Unregistered Buffer Retry ───
+    /**
+     * Schedule a retry check for buffered events from an unregistered session.
+     * Uses exponential backoff: 2s → 4s → 8s → 16s, max 30s total.
+     */
+    scheduleUnregisteredRetry(sessionId, attempt) {
+        const delay = UNREGISTERED_RETRY_DELAYS[Math.min(attempt, UNREGISTERED_RETRY_DELAYS.length - 1)];
+        const timer = setTimeout(() => {
+            this.unregisteredRetryTimers.delete(sessionId);
+            const stillBuffered = this.unregisteredBuffer.get(sessionId);
+            if (!stillBuffered || stillBuffered.length === 0)
+                return;
+            const ctx = this.tasks.get(sessionId);
+            if (ctx) {
+                // Task was registered — flush
+                this.unregisteredBuffer.delete(sessionId);
+                for (const entry of stillBuffered) {
+                    this.handleNormalizedSessionEvent(entry.normalized).catch((err) => {
+                        this.log(`Failed to replay buffered event for ${sessionId}: ${err}`);
+                    });
+                }
+                return;
+            }
+            // Check if we've exceeded the absolute max wait
+            const oldest = stillBuffered[0].receivedAt;
+            const totalElapsed = Date.now() - oldest;
+            if (totalElapsed >= UNREGISTERED_MAX_TOTAL_MS) {
+                this.unregisteredBuffer.delete(sessionId);
+                this.log(`Discarding ${stillBuffered.length} buffered events for unregistered session ${sessionId} after ${Math.round(totalElapsed / 1000)}s`);
+                return;
+            }
+            // Schedule next retry
+            this.log(`Retry ${attempt + 1} for unregistered session ${sessionId} (next in ${delay}ms)`);
+            this.scheduleUnregisteredRetry(sessionId, attempt + 1);
+        }, delay);
+        this.unregisteredRetryTimers.set(sessionId, timer);
+    }
+    // ─── SSE Client Management ───
+    /**
+     * Register an SSE client. Returns an unsubscribe function.
+     * Sends a snapshot of current state on connect.
+     */
+    addSseClient(res) {
+        this.sseClients.add(res);
+        // Send snapshot on connect
+        const snapshot = {
+            type: "snapshot",
+            sessionId: "*",
+            timestamp: Date.now(),
+            data: {
+                tasks: this.getAllTaskContexts(),
+                supervisionLevel: this.supervisionLevel,
+                pendingCount: this.pendingDecisions.size,
+            },
+        };
+        this.writeSseEvent(res, snapshot);
+        // Remove on close
+        const cleanup = () => {
+            this.sseClients.delete(res);
+        };
+        res.on("close", cleanup);
+        return cleanup;
+    }
+    broadcast(event) {
+        const dead = [];
+        for (const client of this.sseClients) {
+            if (client.writableEnded) {
+                dead.push(client);
+                continue;
+            }
+            this.writeSseEvent(client, event);
+        }
+        // Cleanup dead connections
+        for (const d of dead) {
+            this.sseClients.delete(d);
+        }
+        // Relay to WebSocket clients — buffer if bridge isn't wired yet
+        if (this.wsBroadcast) {
+            this.wsBroadcast(event);
+        }
+        else if (this.preBridgeBroadcastBuffer.length < MAX_PRE_BRIDGE_BUFFER) {
+            this.preBridgeBroadcastBuffer.push(event);
+        }
+    }
+    writeSseEvent(res, event) {
+        try {
+            res.write(`data: ${JSON.stringify(event)}\n\n`);
+        }
+        catch {
+            // Connection may have closed
+        }
+    }
+    // ─── Event Handling ───
+    async handleSessionEvent(sessionId, event, data) {
+        const normalized = normalizeCoordinatorEvent(sessionId, event, data);
+        if (!normalized) {
+            this.broadcast({
+                type: event,
+                sessionId,
+                timestamp: Date.now(),
+                data,
+            });
+            return;
+        }
+        await this.handleNormalizedSessionEvent(normalized);
+    }
+    async handleNormalizedSessionEvent(normalized) {
+        const sessionId = normalized.sessionId;
+        const event = normalized.name;
+        const data = normalized.rawData;
+        // Lazy-wire scratch decision callback if not yet connected
+        if (!this.scratchDecisionWired) {
+            this.wireScratchDecisionCallback();
+        }
+        // Ignore events from sessions created before this coordinator started.
+        // Session IDs are formatted as "pty-{timestamp}-{hex}" — extract the timestamp.
+        const tsMatch = sessionId.match(/^pty-(\d+)-/);
+        if (tsMatch) {
+            const sessionCreatedAt = Number(tsMatch[1]);
+            if (sessionCreatedAt < this.startedAt - 60_000) {
+                // Session is from before this coordinator's lifetime (with 1min grace)
+                return;
+            }
+        }
+        const taskCtx = this.tasks.get(sessionId);
+        // Buffer events for unregistered sessions with exponential backoff retry.
+        // Events arriving before registerTask() are buffered and retried at
+        // 2s → 4s → 8s → 16s intervals (max 30s total) before being discarded.
+        if (!taskCtx) {
+            if (event === "blocked" ||
+                event === "task_complete" ||
+                event === "error") {
+                let buffer = this.unregisteredBuffer.get(sessionId);
+                if (!buffer) {
+                    buffer = [];
+                    this.unregisteredBuffer.set(sessionId, buffer);
+                }
+                buffer.push({ normalized, receivedAt: Date.now() });
+                // Only schedule retry if not already retrying for this session
+                if (!this.unregisteredRetryTimers.has(sessionId)) {
+                    this.scheduleUnregisteredRetry(sessionId, 0);
+                }
+            }
+            return;
+        }
+        // Skip decision-making events for terminal states, but always allow
+        // "stopped" and "error" through — they're definitive lifecycle signals
+        // that the frontend needs to close consoles and clean up.
+        // Exception: allow a late "task_complete" to recover a recently-stopped task.
+        let recoveredFromStopped = false;
+        if (taskCtx.status === "stopped" ||
+            taskCtx.status === "error" ||
+            taskCtx.status === "completed") {
+            if (taskCtx.status === "stopped" && event === "task_complete") {
+                const stoppedAt = taskCtx.stoppedAt ?? 0;
+                const ageMs = Date.now() - stoppedAt;
+                if (stoppedAt > 0 && ageMs <= STOPPED_RECOVERY_WINDOW_MS) {
+                    this.log(`Recovering "${taskCtx.label}" from stopped on late task_complete (${Math.round(ageMs / 1000)}s old)`);
+                    taskCtx.status = "active";
+                    taskCtx.stoppedAt = undefined;
+                    recoveredFromStopped = true;
+                }
+                else {
+                    this.log(`Ignoring "${event}" for ${taskCtx.label} (status: stopped, age=${Math.round(ageMs / 1000)}s)`);
+                    return;
+                }
+            }
+            if (!recoveredFromStopped && event !== "stopped" && event !== "error") {
+                this.log(`Ignoring "${event}" for ${taskCtx.label} (status: ${taskCtx.status})`);
+                return;
+            }
+        }
+        // Update activity timestamp — resets idle watchdog for this session.
+        // This runs before buffering so buffered events still reset the idle timer.
+        taskCtx.lastActivityAt = Date.now();
+        taskCtx.idleCheckCount = 0;
+        // Buffer decision-making events when paused (user sent a chat message).
+        // Auto-responses still flow through handleBlocked — only LLM decisions are deferred.
+        if (this._paused && (event === "blocked" || event === "task_complete")) {
+            // Auto-responded blocked events don't need LLM — let them through
+            const blockedAutoResponded = event === "blocked" &&
+                normalized.autoResponded === true;
+            if (!blockedAutoResponded) {
+                // Broadcast buffered state for dashboard visibility
+                this.broadcast({
+                    type: event === "blocked" ? "blocked_buffered" : "turn_complete_buffered",
+                    sessionId,
+                    timestamp: Date.now(),
+                    data,
+                });
+                this.pauseBuffer.push(normalized);
+                this.log(`Buffered "${event}" for ${taskCtx.label} (coordinator paused)`);
+                return;
+            }
+            // Auto-responded: fall through to normal handling below
+        }
+        // Route by event type
+        switch (event) {
+            case "blocked": {
+                const blockedEvent = normalized;
+                const blockedPrompt = blockedEvent.promptText;
+                if (this.isAutomaticFailoverFramework(taskCtx.agentType) &&
+                    isUsageExhaustedTaskAgentError(blockedPrompt)) {
+                    const failoverResult = await this.handleFrameworkDepletion(taskCtx, sessionId, blockedPrompt);
+                    taskCtx.status = "error";
+                    taskCtx.stoppedAt = Date.now();
+                    this.broadcast({
+                        type: "error",
+                        sessionId,
+                        timestamp: Date.now(),
+                        data: {
+                            message: blockedPrompt,
+                            source: "blocked_prompt",
+                        },
+                    });
+                    await this.taskRegistry.appendEvent({
+                        threadId: taskCtx.threadId,
+                        sessionId,
+                        eventType: "task_status_changed",
+                        summary: `Task "${taskCtx.label}" errored`,
+                        data: {
+                            status: "error",
+                            message: blockedPrompt,
+                            source: "blocked_prompt",
+                        },
+                    });
+                    this.ptyService?.stopSession(sessionId, true).catch((err) => {
+                        this.log(`Failed to stop exhausted session "${taskCtx.label}": ${err}`);
+                    });
+                    if (!failoverResult) {
+                        checkAllTasksComplete(this);
+                    }
+                    break;
+                }
+                await handleBlocked(this, sessionId, taskCtx, data);
+                break;
+            }
+            case "task_complete": {
+                // Broadcast immediately for UI visibility, but coalesce the
+                // expensive LLM assessment — rapid turn-complete events within
+                // 500ms are debounced so only the last one triggers an LLM call.
+                this.broadcast({
+                    type: "turn_complete",
+                    sessionId,
+                    timestamp: Date.now(),
+                    data,
+                });
+                const existingCoalesce = this.turnCompleteCoalesceTimers.get(sessionId);
+                if (existingCoalesce)
+                    clearTimeout(existingCoalesce);
+                const coalescedData = data;
+                const coalesceTimer = setTimeout(() => {
+                    this.turnCompleteCoalesceTimers.delete(sessionId);
+                    const currentTask = this.tasks.get(sessionId);
+                    // Accept both "active" and "tool_running" as live pre-validation
+                    // states. Subagents that use tools (curl, file ops, etc.) sit in
+                    // "tool_running" almost continuously, so by the time task_complete
+                    // arrives the status is usually "tool_running" — the prior strict
+                    // "=== active" check meant validation never ran for tool-heavy
+                    // scratch tasks, leaving them stuck and propagating goal failure
+                    // through the watchdog.
+                    if (currentTask &&
+                        (currentTask.status === "active" ||
+                            currentTask.status === "tool_running")) {
+                        handleTurnComplete(this, sessionId, currentTask, coalescedData).catch((err) => {
+                            this.log(`Coalesced turn-complete failed: ${err}`);
+                        });
+                    }
+                }, TURN_COMPLETE_COALESCE_MS);
+                this.turnCompleteCoalesceTimers.set(sessionId, coalesceTimer);
+                break;
+            }
+            case "error": {
+                this.broadcast({
+                    type: "error",
+                    sessionId,
+                    timestamp: Date.now(),
+                    data,
+                });
+                // Send error message to chat UI
+                const errorMsg = data.message ?? "unknown error";
+                const failoverResult = await this.handleFrameworkDepletion(taskCtx, sessionId, errorMsg);
+                let recoveryResult = null;
+                if (!failoverResult) {
+                    try {
+                        recoveryResult = await this.attemptTaskRecovery(taskCtx, errorMsg);
+                    }
+                    catch (recoveryError) {
+                        this.log(`Automatic error recovery failed for "${taskCtx.label}": ${recoveryError instanceof Error ? recoveryError.message : String(recoveryError)}`);
+                    }
+                }
+                if (recoveryResult) {
+                    this.sendChatMessage(`"${taskCtx.label}" hit an error: ${errorMsg}. Eliza is continuing the same task on ${recoveryResult.replacementFramework}.`, "coding-agent");
+                }
+                else if (!failoverResult) {
+                    this.sendChatMessage(`"${taskCtx.label}" hit an error and needs your attention: ${errorMsg}`, "coding-agent");
+                }
+                taskCtx.status = "error";
+                await this.taskRegistry.appendEvent({
+                    threadId: taskCtx.threadId,
+                    sessionId,
+                    eventType: "task_status_changed",
+                    summary: `Task "${taskCtx.label}" errored`,
+                    data: { status: "error", message: errorMsg },
+                });
+                if (!failoverResult && !recoveryResult) {
+                    checkAllTasksComplete(this);
+                }
+                break;
+            }
+            case "stopped": {
+                const alreadyTerminal = taskCtx.status === "completed" || taskCtx.status === "error";
+                // Don't downgrade "completed" or "error" to "stopped" — the async
+                // stopSession fires after executeDecision already marked the task.
+                if (taskCtx.status !== "completed" && taskCtx.status !== "error") {
+                    taskCtx.status = "stopped";
+                    taskCtx.stoppedAt = Date.now();
+                }
+                this.inFlightDecisions.delete(sessionId);
+                this.broadcast({
+                    type: "stopped",
+                    sessionId,
+                    timestamp: Date.now(),
+                    data,
+                });
+                await this.taskRegistry.appendEvent({
+                    threadId: taskCtx.threadId,
+                    sessionId,
+                    eventType: "task_status_changed",
+                    summary: `Task "${taskCtx.label}" stopped`,
+                    data: { status: taskCtx.status },
+                });
+                if (!alreadyTerminal && !taskCtx.suppressStopNotice) {
+                    this.sendChatMessage(`"${taskCtx.label}" stopped before completion.`, "coding-agent");
+                }
+                checkAllTasksComplete(this);
+                break;
+            }
+            case "ready":
+                taskCtx.status = "active";
+                if (taskCtx.agentType === "claude" ||
+                    taskCtx.agentType === "codex" ||
+                    taskCtx.agentType === "gemini" ||
+                    taskCtx.agentType === "aider") {
+                    markTaskAgentFrameworkHealthy(taskCtx.agentType);
+                }
+                this.broadcast({
+                    type: "ready",
+                    sessionId,
+                    timestamp: Date.now(),
+                    data,
+                });
+                await this.taskRegistry.appendEvent({
+                    threadId: taskCtx.threadId,
+                    sessionId,
+                    eventType: "session_updated",
+                    summary: `Session "${taskCtx.label}" ready`,
+                    data: { status: "ready" },
+                });
+                break;
+            case "login_required": {
+                const loginEvent = normalized;
+                let recoveryResult = null;
+                try {
+                    if (this.ptyService &&
+                        (taskCtx.agentType === "claude" ||
+                            taskCtx.agentType === "codex" ||
+                            taskCtx.agentType === "gemini" ||
+                            taskCtx.agentType === "aider")) {
+                        recoveryResult = await this.ptyService.startSessionAuthRecovery(sessionId, taskCtx.agentType, {
+                            instructions: loginEvent.instructions,
+                            url: loginEvent.url,
+                            deviceCode: loginEvent.deviceCode,
+                            method: loginEvent.method,
+                            promptSnippet: loginEvent.promptSnippet,
+                        });
+                    }
+                }
+                catch (error) {
+                    this.log(`Provider auth recovery failed for "${taskCtx.label}": ${error instanceof Error ? error.message : String(error)}`);
+                }
+                if (recoveryResult?.status === "recovered") {
+                    if (recoveryResult.recoveryTarget === "replacement_session") {
+                        break;
+                    }
+                    await this.markTaskResumedAfterProviderAuth(sessionId);
+                    break;
+                }
+                taskCtx.status = "blocked";
+                this.broadcast({
+                    type: "login_required",
+                    sessionId,
+                    timestamp: Date.now(),
+                    data,
+                });
+                await this.taskRegistry.appendEvent({
+                    threadId: taskCtx.threadId,
+                    sessionId,
+                    eventType: "task_status_changed",
+                    summary: `Task "${taskCtx.label}" is waiting for login`,
+                    data: {
+                        status: "blocked",
+                        reason: "login_required",
+                        instructions: loginEvent.instructions ?? null,
+                        url: loginEvent.url ?? null,
+                        deviceCode: loginEvent.deviceCode ?? null,
+                        method: loginEvent.method ?? null,
+                        recoveryStatus: recoveryResult?.status ?? null,
+                    },
+                });
+                const loginParts = [
+                    recoveryResult?.status === "recovering"
+                        ? `"${taskCtx.label}" needs provider authentication, and Eliza has started the recovery flow. It will continue automatically when sign-in completes.`
+                        : `"${taskCtx.label}" needs a provider login before it can continue.`,
+                    recoveryResult?.instructions?.trim() ||
+                        loginEvent.instructions?.trim() ||
+                        "",
+                    recoveryResult?.deviceCode || loginEvent.deviceCode
+                        ? `Device code: ${recoveryResult?.deviceCode ?? loginEvent.deviceCode}`
+                        : "",
+                    recoveryResult?.browserDetail || "",
+                    loginEvent.url ? `Login link: ${loginEvent.url}` : "",
+                    recoveryResult?.url && recoveryResult.url !== loginEvent.url
+                        ? `Login link: ${recoveryResult.url}`
+                        : "",
+                ].filter(Boolean);
+                this.sendChatMessage(loginParts.join(" "), "coding-agent");
+                break;
+            }
+            case "tool_running": {
+                // Agent is actively working via an external tool — keep watchdog happy
+                taskCtx.status = "tool_running";
+                taskCtx.lastActivityAt = Date.now();
+                taskCtx.idleCheckCount = 0;
+                this.broadcast({
+                    type: "tool_running",
+                    sessionId,
+                    timestamp: Date.now(),
+                    data,
+                });
+                // Hook-sourced tool_running events fire for every tool call.
+                // Only broadcast to SSE (for activity box) — skip chat messages.
+                const toolData = data;
+                if (toolData.source === "hook") {
+                    break;
+                }
+                // Throttle chat notifications: at most one per 30s per session.
+                // Suppress during the first 10s after registration — startup status
+                // lines (e.g. "Claude in Chrome enabled") can trigger tool_running
+                // before the agent has actually begun working.
+                const now = Date.now();
+                const STARTUP_GRACE_MS = 10_000;
+                if (now - taskCtx.registeredAt < STARTUP_GRACE_MS) {
+                    break;
+                }
+                const lastNotif = this.lastToolNotification.get(sessionId) ?? 0;
+                if (now - lastNotif > 30_000) {
+                    this.lastToolNotification.set(sessionId, now);
+                    const toolDesc = toolData.description ?? toolData.toolName ?? "an external tool";
+                    // Try to extract a dev server URL from recent output
+                    let urlSuffix = "";
+                    if (this.ptyService) {
+                        try {
+                            const recentOutput = await this.ptyService.getSessionOutput(sessionId, 50);
+                            const devUrl = extractDevServerUrl(recentOutput);
+                            if (devUrl) {
+                                urlSuffix = ` Dev server running at ${devUrl}`;
+                            }
+                        }
+                        catch {
+                            // Best-effort — don't block on failure
+                        }
+                    }
+                    const message = `[${taskCtx.label}] Running ${toolDesc}.${urlSuffix} The agent is working outside the terminal.`;
+                    this.log(message);
+                    this.sendChatMessage(message, "coding-agent");
+                }
+                break;
+            }
+            default:
+                // Broadcast unknown events for observability
+                this.broadcast({
+                    type: event,
+                    sessionId,
+                    timestamp: Date.now(),
+                    data,
+                });
+        }
+        await this.syncTaskContext(taskCtx);
+    }
+    // ─── LLM Decision (delegated) ───
+    async makeCoordinationDecision(taskCtx, promptText, recentOutput) {
+        // Re-export for backward compatibility — delegates to module function
+        const { makeCoordinationDecision: mkDecision } = await import("./swarm-decision-loop.js");
+        return mkDecision(this, taskCtx, promptText, recentOutput);
+    }
+    async executeDecision(sessionId, decision) {
+        return execDecision(this, sessionId, decision);
+    }
+    /**
+     * Public entry point for external callers (e.g. server.ts) to execute
+     * a coordination decision on a session. Wraps the internal executeDecision.
+     */
+    async executeEventDecision(sessionId, decision) {
+        return execDecision(this, sessionId, decision);
+    }
+    // ─── Supervision ───
+    setSupervisionLevel(level) {
+        this.supervisionLevel = level;
+        this.broadcast({
+            type: "supervision_changed",
+            sessionId: "*",
+            timestamp: Date.now(),
+            data: { level },
+        });
+        this.log(`Supervision level set to: ${level}`);
+    }
+    getSupervisionLevel() {
+        return this.supervisionLevel;
+    }
+    // ─── Confirmation Queue ───
+    getPendingConfirmations() {
+        return Array.from(this.pendingDecisions.values());
+    }
+    async confirmDecision(sessionId, approved, override) {
+        const pending = this.pendingDecisions.get(sessionId);
+        if (!pending) {
+            throw new Error(`No pending decision for session ${sessionId}`);
+        }
+        const taskCtx = this.tasks.get(sessionId);
+        if (approved) {
+            // Use override if provided, otherwise use LLM suggestion
+            const decision = override
+                ? {
+                    action: "respond",
+                    response: override.response,
+                    useKeys: override.useKeys,
+                    keys: override.keys,
+                    reasoning: "Human-approved (with override)",
+                }
+                : pending.llmDecision;
+            if (taskCtx) {
+                taskCtx.status = "active";
+                taskCtx.autoResolvedCount = 0;
+                await this.recordDecision(taskCtx, {
+                    timestamp: Date.now(),
+                    event: "blocked",
+                    promptText: pending.promptText,
+                    decision: decision.action,
+                    response: decision.action === "respond"
+                        ? decision.useKeys
+                            ? `keys:${decision.keys?.join(",")}`
+                            : decision.response
+                        : undefined,
+                    reasoning: `Human-approved: ${decision.reasoning}`,
+                });
+                await this.syncTaskContext(taskCtx);
+            }
+            await this.executeDecision(sessionId, decision);
+            this.pendingDecisions.delete(sessionId);
+            await this.taskRegistry.deletePendingDecision(sessionId);
+            if (taskCtx) {
+                await this.taskRegistry.appendEvent({
+                    threadId: taskCtx.threadId,
+                    sessionId,
+                    eventType: "confirmation_approved",
+                    summary: `Approved pending confirmation for "${taskCtx.label}"`,
+                    data: {
+                        action: decision.action,
+                        response: decision.response ?? null,
+                    },
+                });
+            }
+            this.broadcast({
+                type: "confirmation_approved",
+                sessionId,
+                timestamp: Date.now(),
+                data: {
+                    action: decision.action,
+                    response: decision.response,
+                    useKeys: decision.useKeys,
+                    keys: decision.keys,
+                },
+            });
+            if (taskCtx) {
+                this.sendChatMessage(`"${taskCtx.label}" was approved. Eliza is continuing the task now.`, "coding-agent");
+            }
+        }
+        else {
+            // Rejected — record and broadcast
+            if (taskCtx) {
+                taskCtx.status = "blocked";
+                await this.recordDecision(taskCtx, {
+                    timestamp: Date.now(),
+                    event: "blocked",
+                    promptText: pending.promptText,
+                    decision: "escalate",
+                    reasoning: "Human rejected the suggested action",
+                });
+                await this.syncTaskContext(taskCtx);
+            }
+            this.pendingDecisions.delete(sessionId);
+            await this.taskRegistry.deletePendingDecision(sessionId);
+            if (pending.taskContext.threadId) {
+                await this.taskRegistry.appendEvent({
+                    threadId: pending.taskContext.threadId,
+                    sessionId,
+                    eventType: "confirmation_rejected",
+                    summary: `Rejected pending confirmation for "${pending.taskContext.label}"`,
+                    data: { prompt: pending.promptText },
+                });
+            }
+            this.broadcast({
+                type: "confirmation_rejected",
+                sessionId,
+                timestamp: Date.now(),
+                data: { prompt: pending.promptText },
+            });
+            this.sendChatMessage(`"${pending.taskContext.label}" remains blocked after the suggested action was rejected. Prompt: ${pending.promptText}`, "coding-agent");
+        }
+    }
+    // ─── Internal ───
+    log(message) {
+        logger.info(`[SwarmCoordinator] ${message}`);
+    }
+}