@getforgeai/cli 0.1.0-beta.1

package/dist/orchestrator/agent-spawner.js

@@ -0,0 +1,1518 @@
+import { randomUUID } from "node:crypto";
+import { z } from "zod";
+import { TaskResumePayloadSchema, WorkflowStepDispatchPayloadSchema, } from "@getforgeai/protocol";
+import { dockerConnector } from "./connectors/docker-connector.js";
+import { StreamBatcher } from "./stream-batcher.js";
+import { StreamJsonExtractor } from "./stream-json-extractor.js";
+import { AgentRegistry } from "./agent-registry.js";
+import { handleResume } from "./resume-handler.js";
+import { pullSkill } from "../lib/skill-manager.js";
+import { getConfig } from "../config/config-manager.js";
+import { vmLog } from "../vm/log.js";
+/** Pending fallback REST calls (advanceTask/requeueTask) from agent exit handlers. */
+const pendingFallbacks = new Set();
+/** Wait for pending fallback REST calls to complete (with timeout). */
+export async function awaitPendingFallbacks(timeoutMs) {
+    if (pendingFallbacks.size === 0)
+        return;
+    const timeout = new Promise((resolve) => setTimeout(resolve, timeoutMs));
+    await Promise.race([Promise.all(pendingFallbacks), timeout]);
+}
+export const DEFAULT_SKILL_NAME = "execute-task";
+const IDLE_WINDOW_MS = 5 * 60 * 1000; // 5 minutes
+/** Tracks agents in their 5-minute idle window after process exit */
+const idleWindows = new Map();
+/** Agents dismissed by user while still RUNNING — skip idle window on exit */
+const dismissedWhileRunning = new Set();
+/** Board tasks that called forge_ask_human — save snapshot on exit for --continue resume */
+const pendingAskHuman = new Set();
+/** Mark a task as having called forge_ask_human (called from MCP tool) */
+export function markAskHuman(taskId) {
+    pendingAskHuman.add(taskId);
+}
+/**
+ * Clear all idle windows and their timers.
+ * Called on socket disconnect to prevent stale timers emitting on dead sockets.
+ * Also unregisters IDLE agents from registry to free slots on reconnect.
+ */
+export function clearAllIdleWindows(socket, agentSlots) {
+    const reg = getRegistry(agentSlots);
+    for (const [agentId, idleState] of idleWindows) {
+        clearTimeout(idleState.timer);
+        socket.off("workflow:message", idleState.messageHandler);
+        // Free the slot so reconnected CLI has full capacity
+        reg.unregister(agentId);
+        // Destroy container (no snapshot on disconnect — best effort cleanup)
+        void (async () => {
+            try {
+                const { getVmManager } = await import("../vm/vm-manager-facade.js");
+                await getVmManager().destroySession(agentId);
+            }
+            catch {
+                /* best effort */
+            }
+        })();
+        vmLog.dim("spawner", `Cleared idle window for step ${agentId} on disconnect (container destroyed, slot freed)`);
+    }
+    idleWindows.clear();
+}
+export const TaskDispatchSchema = z.object({
+    taskId: z.string(),
+    projectId: z.string(),
+    assigneeId: z.string(),
+    taskCommand: z.string().optional(),
+    skillSlug: z.string().optional(),
+    workflowBaseBranch: z.string().optional(),
+    taskBranch: z.string().optional(),
+    taskSlug: z.string().optional(),
+    projectSlug: z.string().optional(),
+    repoUrl: z.string().optional(),
+    metadata: z.record(z.string(), z.unknown()).optional(),
+});
+let registry = null;
+function getRegistry(agentSlots) {
+    registry ??= new AgentRegistry(agentSlots);
+    return registry;
+}
+/** Exported for testing */
+export function resetRegistry() {
+    registry = null;
+}
+export function getAgentRegistry(agentSlots) {
+    return getRegistry(agentSlots);
+}
+export function resolveConnector(agentTypeOrName) {
+    return dockerConnector;
+}
+/**
+ * Attach exit and error handlers to an agent process.
+ * Shared between spawnAgent and handleResume to deduplicate handler code.
+ */
+export function attachProcessHandlers(process, args) {
+    const { taskId, projectId, registry: reg, socketClient, restClient, queue, spawnAgentFn, label, } = args;
+    // Capture stdout/stderr via StreamBatcher (best-effort fire-and-forget)
+    const childProcess = process;
+    const batchers = [];
+    let jsonExtractorTask;
+    if (childProcess.stdout) {
+        const stdoutBatcher = new StreamBatcher((chunk) => {
+            socketClient.emitAgentStream({
+                agentId: taskId,
+                chunk,
+                projectId,
+                turnIndex: jsonExtractorTask?.turnIndex ?? 0,
+            });
+        });
+        // Parse stream-json output: extract text deltas + tool activity
+        jsonExtractorTask = new StreamJsonExtractor((textDelta) => {
+            stdoutBatcher.write(textDelta);
+        }, undefined, // onQuestion — not needed for task agents
+        (activity) => {
+            socketClient.emitAgentToolActivity({
+                agentId: taskId,
+                toolName: activity.toolName,
+                toolDetail: activity.toolDetail,
+                toolUseId: activity.toolUseId,
+                parentToolUseId: activity.parentToolUseId,
+                projectId,
+            });
+        }, undefined, // onTokenUsage
+        args.sessionId);
+        childProcess.stdout.on("data", (data) => jsonExtractorTask.write(data.toString()));
+        batchers.push(stdoutBatcher);
+    }
+    // Accumulate last 4 KB of stderr for billing error detection on exit
+    let stderrTail = "";
+    const STDERR_MAX = 4096;
+    if (childProcess.stderr) {
+        const stderrBatcher = new StreamBatcher((chunk) => {
+            socketClient.emitAgentStream({
+                agentId: taskId,
+                chunk,
+                projectId,
+            });
+        });
+        childProcess.stderr.on("data", (data) => {
+            const text = data.toString();
+            stderrTail += text;
+            if (stderrTail.length > STDERR_MAX) {
+                stderrTail = stderrTail.slice(-STDERR_MAX);
+            }
+            stderrBatcher.write(text);
+        });
+        batchers.push(stderrBatcher);
+    }
+    process.on("exit", (code) => {
+        const entry = reg.getByTaskId(taskId);
+        if (!entry)
+            return;
+        // Flush remaining stream data before emitting final status
+        if (jsonExtractorTask)
+            jsonExtractorTask.flush();
+        for (const batcher of batchers) {
+            batcher.destroy();
+        }
+        // Ask-human: save snapshot + destroy container immediately (no idle window).
+        // On resume, snapshot is restored with --continue for full context.
+        if (code === 0 && pendingAskHuman.has(taskId)) {
+            pendingAskHuman.delete(taskId);
+            vmLog.cyan(label, `Agent for task ${taskId} asked human — saving snapshot before destroy`);
+            // Save snapshot + destroy in background (non-blocking)
+            const savedOrgId = entry.orgId;
+            void (async () => {
+                try {
+                    const { getVmManager } = await import("../vm/vm-manager-facade.js");
+                    const sm = getVmManager();
+                    const session = sm.getSessionByTaskId(taskId);
+                    if (session) {
+                        const { autoSaveCode, createSessionSnapshot } = await import("../vm/session-snapshot.js");
+                        await autoSaveCode(session.containerId, session.id, session.gitCredentials);
+                        const snapshot = await createSessionSnapshot(session);
+                        if (snapshot) {
+                            socketClient.socket.emit("workflow:step:snapshot", {
+                                orgId: savedOrgId,
+                                workflowId: taskId,
+                                stepId: taskId,
+                                snapshot,
+                            });
+                            vmLog.cyan(label, `Board task snapshot saved for ${taskId}`);
+                        }
+                        await sm.destroySession(taskId);
+                    }
+                }
+                catch {
+                    try {
+                        const { getVmManager } = await import("../vm/vm-manager-facade.js");
+                        await getVmManager().destroySession(taskId);
+                    }
+                    catch {
+                        /* best effort */
+                    }
+                }
+            })();
+            // Free slot immediately (don't block on snapshot)
+            // Don't unregister/emit status here — let the normal exit flow handle it below
+        }
+        const status = code === 0 ? "COMPLETED" : "ERROR";
+        // Detect billing/token errors from agent output + stderr
+        const isBilling = status === "ERROR" &&
+            (jsonExtractorTask?.isBillingError(stderrTail) ?? false);
+        const errorReason = isBilling ? "TOKEN_EXHAUSTED" : undefined;
+        const resetAt = isBilling
+            ? (jsonExtractorTask?.extractResetTimestamp(stderrTail) ?? undefined)
+            : undefined;
+        entry.status = status;
+        reg.unregister(taskId);
+        // Emit updated heartbeat IMMEDIATELY so Cloud sees the freed slot.
+        // Without this, Redis heartbeat stays stale and Cloud's dispatch engine
+        // finds 0 available slots, delaying re-dispatch until the periodic heartbeat fires.
+        const cliCfg = getConfig();
+        socketClient.emitCliHeartbeat({
+            cliId: cliCfg.cliId ?? "unknown",
+            status: "CONNECTED",
+            name: cliCfg.cliName ?? "CLI",
+            agentSlots: args.agentSlots,
+            activeAgents: reg.getProvisionedCount(),
+            runningAgents: reg.getActiveCount(),
+        });
+        socketClient.emitAgentStatus({
+            agentId: taskId,
+            status,
+            projectId,
+            errorReason,
+        });
+        if (isBilling) {
+            const resetInfo = resetAt ? ` (limit resets at ${resetAt})` : "";
+            vmLog.error(label, `Agent for task ${taskId} exited with TOKEN_EXHAUSTED — CLI will enter cooldown${resetInfo}`);
+        }
+        vmLog.dim(label, `Agent for task ${taskId} exited (code: ${code}, status: ${status}, activeAgents: ${reg.getProvisionedCount()}, runningAgents: ${reg.getActiveCount()})`);
+        // Safety net: ensure task never stays stuck after agent exit.
+        //
+        // COMPLETED → fallback release via REST: if forge_column_done already
+        //   ran, the task's cliDeviceId is null and this is a no-op. Otherwise,
+        //   releases CLI device without advancing column so task gets re-dispatched.
+        //
+        // ERROR → requeue via REST so the task releases its cliDeviceId and
+        //   becomes eligible for re-dispatch. Without this, the card keeps its
+        //   agent dot and stays assigned to a dead agent indefinitely.
+        if (status === "COMPLETED") {
+            const fallbackPromise = restClient
+                .advanceTask(taskId, { fallback: true })
+                .then((result) => {
+                if (result.released) {
+                    vmLog.warn(label, `Released task ${taskId} for re-dispatch (fallback): staying on column ${result.column ?? "unknown"}`);
+                }
+                else if (result.advanced) {
+                    vmLog.warn(label, `Auto-advanced task ${taskId} (fallback): ${result.previousColumn} → ${result.newColumn}`);
+                }
+                else {
+                    vmLog.dim(label, `Fallback no-op for task ${taskId} (forge_column_done already ran)`);
+                }
+            })
+                .catch((err) => {
+                vmLog.warn(label, `Fallback for task ${taskId} failed: ${err instanceof Error ? err.message : String(err)}`);
+            })
+                .finally(() => {
+                pendingFallbacks.delete(fallbackPromise);
+            });
+            pendingFallbacks.add(fallbackPromise);
+        }
+        else if (status === "ERROR") {
+            const reason = isBilling
+                ? "Agent exited with billing/token error (TOKEN_EXHAUSTED)"
+                : "Agent exited with error — releasing for re-dispatch";
+            const requeuePromise = restClient
+                .requeueTask(taskId, reason, errorReason, resetAt)
+                .then((result) => {
+                if (result.allowed) {
+                    vmLog.warn(label, `Requeued task ${taskId} after agent error (${result.count}/${result.max})`);
+                }
+            })
+                .catch((err) => {
+                vmLog.warn(label, `Requeue fallback for task ${taskId} failed: ${err instanceof Error ? err.message : String(err)}`);
+            })
+                .finally(() => {
+                pendingFallbacks.delete(requeuePromise);
+            });
+            pendingFallbacks.add(requeuePromise);
+        }
+        // Auth error: clear queue + try token refresh (all tasks will fail with bad token)
+        const isAuthError = "isAuthError" in process &&
+            process.isAuthError === true;
+        // Auto-cycle: drain next queued dispatch.
+        // Skip for billing or auth errors — all queued tasks will fail the same way.
+        if (isBilling) {
+            queue.clear();
+            queue.pause(resetAt);
+        }
+        else if (isAuthError) {
+            queue.clear();
+            vmLog.error(label, "Auth error — queue cleared. Attempting token refresh from Keychain...");
+            void (async () => {
+                try {
+                    const { getVmManager } = await import("../vm/vm-manager-facade.js");
+                    const refreshed = await getVmManager().refreshToken();
+                    if (refreshed) {
+                        vmLog.cyan(label, "Token refreshed — next dispatch will use the new token");
+                    }
+                    else {
+                        vmLog.error(label, "No new token in Keychain. Run: forge auth setup-claude");
+                    }
+                }
+                catch {
+                    vmLog.error(label, "Token refresh failed. Run: forge auth setup-claude");
+                }
+            })();
+        }
+        else {
+            // Delay so the "slot freed" heartbeat propagates to Cloud → browser
+            // before a new spawn emits an eager heartbeat re-filling the slot.
+            setTimeout(() => {
+                queue.drainNext({ spawnAgent: spawnAgentFn }).catch((err) => {
+                    vmLog.warn(label, `Auto-cycle drain failed: ${err instanceof Error ? err.message : String(err)}`);
+                });
+            }, 500);
+        }
+    });
+    process.on("error", (err) => {
+        const entry = reg.getByTaskId(taskId);
+        if (!entry)
+            return;
+        reg.unregister(taskId);
+        // Emit updated heartbeat so Cloud sees the freed slot immediately
+        const cliCfg = getConfig();
+        socketClient.emitCliHeartbeat({
+            cliId: cliCfg.cliId ?? "unknown",
+            status: "CONNECTED",
+            name: cliCfg.cliName ?? "CLI",
+            agentSlots: args.agentSlots,
+            activeAgents: reg.getProvisionedCount(),
+            runningAgents: reg.getActiveCount(),
+        });
+        socketClient.emitAgentStatus({
+            agentId: taskId,
+            status: "ERROR",
+        });
+        vmLog.error(label, `Agent error for task ${taskId}: ${err.message}`);
+        // Auto-cycle on error too
+        queue.drainNext({ spawnAgent: spawnAgentFn }).catch((error_) => {
+            vmLog.warn(label, `Auto-cycle drain after error failed: ${error_ instanceof Error ? error_.message : String(error_)}`);
+        });
+    });
+}
+/**
+ * Attach exit and error handlers to a workflow step agent process.
+ * Dual-emits: workflow:stream (wizard chat) + agent:stream (activity monitoring).
+ * On exit, emits workflow:stream:end with accumulated content for persistence.
+ */
+export function attachWorkflowProcessHandlers(process, args) {
+    const { taskId, projectId, registry: reg, socketClient, queue, spawnAgentFn, label, workflowId, stepId, conversationId, } = args;
+    const childProcess = process;
+    const batchers = [];
+    const MAX_ACCUMULATED_BYTES = 256 * 1024; // 256KB limit for workflow:stream:end payload
+    let currentMessageId = randomUUID();
+    let chunkIndex = 0;
+    let accumulatedContent = "";
+    let contentTruncated = false;
+    // Parse stream-json output from Claude Code: extract only text deltas
+    let jsonExtractor;
+    if (childProcess.stdout) {
+        const stdoutBatcher = new StreamBatcher((chunk) => {
+            // Dual emit: wizard chat + activity monitoring
+            socketClient.emitWorkflowStream({
+                workflowId,
+                stepId,
+                conversationId,
+                messageId: currentMessageId,
+                chunk,
+                index: chunkIndex++,
+                turnIndex: jsonExtractor?.turnIndex ?? 0,
+            });
+            socketClient.emitAgentStream({
+                agentId: taskId,
+                chunk,
+                projectId,
+                turnIndex: jsonExtractor?.turnIndex ?? 0,
+            });
+            if (!contentTruncated) {
+                if (accumulatedContent.length + chunk.length > MAX_ACCUMULATED_BYTES) {
+                    accumulatedContent += chunk.slice(0, MAX_ACCUMULATED_BYTES - accumulatedContent.length);
+                    contentTruncated = true;
+                }
+                else {
+                    accumulatedContent += chunk;
+                }
+            }
+        });
+        // StreamJsonExtractor parses newline-delimited JSON from --output-format stream-json
+        // and emits only text_delta content to the batcher (no thinking, tool_use, system events)
+        // When AskUserQuestion is detected, emit structured questions via workflow:question
+        jsonExtractor = new StreamJsonExtractor((textDelta) => {
+            stdoutBatcher.write(textDelta);
+        }, (questions) => {
+            socketClient.emitWorkflowQuestion({
+                workflowId,
+                stepId,
+                conversationId,
+                questions,
+            });
+        }, (activity) => {
+            socketClient.emitWorkflowToolActivity({
+                workflowId,
+                stepId,
+                ...activity,
+            });
+            // Dual emit: task activity panel
+            socketClient.emitAgentToolActivity({
+                agentId: taskId,
+                toolName: activity.toolName,
+                toolDetail: activity.toolDetail,
+                toolUseId: activity.toolUseId,
+                parentToolUseId: activity.parentToolUseId,
+                projectId,
+            });
+        }, (usage) => {
+            socketClient.emitWorkflowTokenUsage({
+                workflowId,
+                stepId,
+                ...usage,
+            });
+        }, args.sessionId);
+        childProcess.stdout.on("data", (data) => jsonExtractor.write(data.toString()));
+        batchers.push(stdoutBatcher);
+    }
+    // Accumulate last 4 KB of stderr for billing error detection on exit
+    let workflowStderrTail = "";
+    const WORKFLOW_STDERR_MAX = 4096;
+    if (childProcess.stderr) {
+        const stderrBatcher = new StreamBatcher((chunk) => {
+            socketClient.emitAgentStream({
+                agentId: taskId,
+                chunk,
+                projectId,
+            });
+        });
+        childProcess.stderr.on("data", (data) => {
+            const text = data.toString();
+            workflowStderrTail += text;
+            if (workflowStderrTail.length > WORKFLOW_STDERR_MAX) {
+                workflowStderrTail = workflowStderrTail.slice(-WORKFLOW_STDERR_MAX);
+            }
+            stderrBatcher.write(text);
+        });
+        batchers.push(stderrBatcher);
+    }
+    const { onExit } = args;
+    process.on("exit", (code) => {
+        const entry = reg.getByTaskId(taskId);
+        if (!entry)
+            return;
+        // Flush remaining stream data (extractor first, then batchers)
+        if (jsonExtractor)
+            jsonExtractor.flush();
+        for (const batcher of batchers) {
+            batcher.destroy();
+        }
+        // Emit workflow:stream:end with accumulated content for persistence
+        if (accumulatedContent) {
+            socketClient.emitWorkflowStreamEnd({
+                workflowId,
+                stepId,
+                conversationId,
+                messageId: currentMessageId,
+                finalContent: accumulatedContent,
+            });
+        }
+        // If onExit callback provided (idle window), delegate cleanup
+        if (onExit) {
+            onExit(code, accumulatedContent);
+            return;
+        }
+        // Default behavior: unregister + drain
+        const status = code === 0 ? "COMPLETED" : "ERROR";
+        // Detect billing/token errors from agent output + stderr
+        const isBilling = status === "ERROR" &&
+            (jsonExtractor?.isBillingError(workflowStderrTail) ?? false);
+        const errorReason = isBilling ? "TOKEN_EXHAUSTED" : undefined;
+        const resetAt = isBilling
+            ? (jsonExtractor?.extractResetTimestamp(workflowStderrTail) ?? undefined)
+            : undefined;
+        entry.status = status;
+        reg.unregister(taskId);
+        // Emit updated heartbeat so Cloud sees the freed slot immediately
+        const cliCfg = getConfig();
+        socketClient.emitCliHeartbeat({
+            cliId: cliCfg.cliId ?? "unknown",
+            status: "CONNECTED",
+            name: cliCfg.cliName ?? "CLI",
+            agentSlots: args.agentSlots,
+            activeAgents: reg.getProvisionedCount(),
+            runningAgents: reg.getActiveCount(),
+        });
+        socketClient.emitAgentStatus({
+            agentId: taskId,
+            status,
+            projectId,
+            errorReason,
+        });
+        if (isBilling) {
+            const resetInfo = resetAt ? ` (limit resets at ${resetAt})` : "";
+            vmLog.error(label, `Workflow agent for step ${taskId} exited with TOKEN_EXHAUSTED${resetInfo}`);
+        }
+        vmLog.dim(label, `Agent for step ${taskId} exited (code: ${code}, status: ${status}, activeAgents: ${reg.getProvisionedCount()}, runningAgents: ${reg.getActiveCount()})`);
+        // Auto-cycle: drain next queued dispatch.
+        // Skip for billing errors — all queued tasks will fail the same way.
+        if (isBilling) {
+            queue.clear();
+            queue.pause(resetAt);
+        }
+        else {
+            // Delay so the "slot freed" heartbeat propagates to Cloud → browser
+            // before a new spawn emits an eager heartbeat re-filling the slot.
+            setTimeout(() => {
+                queue.drainNext({ spawnAgent: spawnAgentFn }).catch((err) => {
+                    vmLog.warn(label, `Auto-cycle drain failed: ${err instanceof Error ? err.message : String(err)}`);
+                });
+            }, 500);
+        }
+    });
+    process.on("error", (err) => {
+        const entry = reg.getByTaskId(taskId);
+        if (!entry)
+            return;
+        reg.unregister(taskId);
+        // Emit updated heartbeat so Cloud sees the freed slot immediately
+        const cliCfg2 = getConfig();
+        socketClient.emitCliHeartbeat({
+            cliId: cliCfg2.cliId ?? "unknown",
+            status: "CONNECTED",
+            name: cliCfg2.cliName ?? "CLI",
+            agentSlots: args.agentSlots,
+            activeAgents: reg.getProvisionedCount(),
+            runningAgents: reg.getActiveCount(),
+        });
+        socketClient.emitAgentStatus({
+            agentId: taskId,
+            status: "ERROR",
+        });
+        vmLog.error(label, `Agent error for step ${taskId}: ${err.message}`);
+        // Auto-cycle on error too
+        queue.drainNext({ spawnAgent: spawnAgentFn }).catch((error_) => {
+            vmLog.warn(label, `Auto-cycle drain after error failed: ${error_ instanceof Error ? error_.message : String(error_)}`);
+        });
+    });
+}
+/**
+ * Helper: Check if spawn is already in flight for taskId (race condition guard).
+ */
+function checkDuplicateSpawn(reg, taskId) {
+    if (reg.hasPendingReservation(taskId)) {
+        vmLog.dim("spawner", `Spawn already in flight for task ${taskId}, skipping duplicate`);
+        return true;
+    }
+    return false;
+}
+/**
+ * Helper: Stop running agent if one exists for taskId (stop-and-replace pattern).
+ */
+async function stopExistingAgent(reg, taskId) {
+    const existingEntry = reg.getByTaskId(taskId);
+    if (existingEntry?.status === "RUNNING") {
+        vmLog.cyan("spawner", `Stopping existing agent for task ${taskId} (PID: ${existingEntry.pid}) before re-dispatch`);
+        // Unregister first to prevent exit handler from interfering with new spawn
+        reg.unregister(taskId);
+        const connector = resolveConnector(existingEntry.connectorName);
+        try {
+            await connector.stop(existingEntry);
+        }
+        catch (err) {
+            vmLog.warn("spawner", `Error stopping old agent for ${taskId}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+}
+/**
+ * Helper: Attempt to reserve slot; if no capacity, enqueue and return early.
+ */
+function reserveSlotOrEnqueue(reg, params, ctx) {
+    if (!reg.reserveSlot(params.taskId)) {
+        vmLog.warn("spawner", `No capacity for task ${params.taskId}, enqueuing`);
+        ctx.queue.enqueue(params);
+        return false;
+    }
+    return true;
+}
+/**
+ * Main spawn pipeline — orchestrates the full agent lifecycle.
+ * Uses slot reservation to prevent over-allocation during async pipeline.
+ */
+export async function spawnAgent(params, ctx) {
+    const reg = getRegistry(ctx.agentSlots);
+    // Guard: if dispatch queue is paused (billing cooldown), skip spawn entirely
+    if (ctx.queue.isPaused()) {
+        vmLog.dim("spawner", `Spawn skipped — queue paused (billing cooldown) for task ${params.taskId}`);
+        return;
+    }
+    // Guard: if a spawn is already in flight for this taskId, skip to prevent
+    // dual-path race conditions (e.g. advance + dispatch arriving concurrently)
+    if (checkDuplicateSpawn(reg, params.taskId)) {
+        return;
+    }
+    // Stop-and-replace: if an agent is already running for this taskId
+    // (e.g. column advance re-dispatch while old agent still alive),
+    // stop the old agent first to prevent two agents in the same worktree.
+    await stopExistingAgent(reg, params.taskId);
+    // 1. Reserve slot (atomic capacity check)
+    if (!reserveSlotOrEnqueue(reg, params, ctx)) {
+        return;
+    }
+    // Emit eager heartbeat so the browser shows the slot as reserved immediately
+    // (not waiting for the full spawn pipeline to complete)
+    const cliCfg = getConfig();
+    ctx.socketClient.emitCliHeartbeat({
+        cliId: cliCfg.cliId ?? "unknown",
+        status: "CONNECTED",
+        name: cliCfg.cliName ?? "CLI",
+        agentSlots: ctx.agentSlots,
+        activeAgents: reg.getProvisionedCount(),
+        runningAgents: reg.getActiveCount(),
+    });
+    try {
+        const projectSlug = params.projectSlug ?? "default";
+        const taskSlug = params.taskSlug ?? params.taskId;
+        const taskBranch = params.taskBranch ??
+            (params.workflowBaseBranch
+                ? `${params.workflowBaseBranch}/${taskSlug}`
+                : taskSlug);
+        // Pull and prepare skill
+        const skillName = params.skillSlug ?? DEFAULT_SKILL_NAME;
+        const skill = await pullSkill(skillName, ctx.restClient);
+        // Resolve connector (always VM now)
+        const connector = resolveConnector(ctx.agentType);
+        // VM connector handles everything: boot VM, clone, checkout, workspace, spawn
+        const vmSpawnParams = {
+            taskId: params.taskId,
+            projectId: params.projectId,
+            orgId: params.orgId,
+            workingDir: "/workspace",
+            mcpConfigPath: "/workspace/.claude/mcp_config.json",
+            skillName: skill?.name ?? skillName,
+            prompt: params.taskCommand,
+            repoUrl: params.repoUrl,
+            taskBranch,
+            workflowBaseBranch: params.workflowBaseBranch,
+            skill: skill ? { name: skill.name, files: skill.files } : undefined,
+            taskContext: {
+                type: "task",
+                taskId: params.taskId,
+                taskBranch,
+                parentBranch: params.workflowBaseBranch ?? null,
+                projectSlug,
+                taskSlug,
+                repoUrl: params.repoUrl ?? null,
+                ...(params.metadata ?? {}),
+            },
+        };
+        const result = await connector.start(vmSpawnParams);
+        // Confirm slot, register agent (use workingDir, add vmId)
+        reg.confirmSlot(params.taskId, {
+            taskId: params.taskId,
+            pid: result.pid,
+            process: result.process,
+            connectorName: connector.name,
+            workingDir: "/workspace",
+            orgId: params.orgId,
+            startedAt: new Date().toISOString(),
+            status: "RUNNING",
+            vmId: result.vmId,
+        });
+        // Emit agent:status + heartbeat
+        ctx.socketClient.emitAgentStatus({
+            agentId: params.taskId,
+            status: "RUNNING",
+            projectId: params.projectId,
+        });
+        ctx.socketClient.emitCliHeartbeat({
+            cliId: cliCfg.cliId ?? "unknown",
+            status: "CONNECTED",
+            name: cliCfg.cliName ?? "CLI",
+            agentSlots: ctx.agentSlots,
+            activeAgents: reg.getProvisionedCount(),
+            runningAgents: reg.getActiveCount(),
+        });
+        vmLog.info("spawner", `Agent spawned for task ${params.taskId} (PID: ${result.pid}, connector: ${connector.name}, vmId: ${result.vmId ?? "none"})`);
+        // Attach process handlers (exit + error) with auto-cycle
+        const boundSpawnAgent = (p) => spawnAgent(p, ctx);
+        attachProcessHandlers(result.process, {
+            taskId: params.taskId,
+            projectId: params.projectId,
+            registry: reg,
+            socketClient: ctx.socketClient,
+            restClient: ctx.restClient,
+            queue: ctx.queue,
+            spawnAgentFn: boundSpawnAgent,
+            label: "spawner",
+            agentSlots: ctx.agentSlots,
+            sessionId: result.vmId,
+        });
+    }
+    catch (err) {
+        // Release reservation on failure
+        reg.releaseSlot(params.taskId);
+        throw err;
+    }
+}
+/**
+ * Stop a specific agent by taskId.
+ */
+export async function stopAgent(taskId, ctx) {
+    const reg = getRegistry(ctx.agentSlots);
+    const entry = reg.getByTaskId(taskId);
+    if (!entry)
+        return;
+    // Unregister first to prevent the exit handler from double-emitting
+    reg.unregister(taskId);
+    const connector = resolveConnector(entry.connectorName);
+    await connector.stop(entry);
+}
+/**
+ * Graceful shutdown of all running agents.
+ * Clears queue, unregisters first (prevents exit handler race), then sends SIGTERM,
+ * waits up to 10s, then SIGKILL survivors.
+ */
+export async function stopAllAgents(ctx) {
+    const reg = getRegistry(ctx.agentSlots);
+    // Clear all idle windows and their timers
+    for (const [agentId, idleState] of idleWindows) {
+        clearTimeout(idleState.timer);
+        ctx.socketClient.socket.off("workflow:message", idleState.messageHandler);
+        vmLog.dim("spawner", `Cleared idle window for step ${agentId} at shutdown`);
+    }
+    idleWindows.clear();
+    // Clear queue first to prevent new spawns during shutdown
+    const queueSize = ctx.queue.size();
+    ctx.queue.clear();
+    if (queueSize > 0) {
+        vmLog.cyan("spawner", `Cleared ${queueSize} queued dispatches at shutdown`);
+    }
+    const allAgents = reg.getAll();
+    if (allAgents.length === 0)
+        return;
+    vmLog.cyan("spawner", `Stopping ${allAgents.length} running agent(s)...`);
+    // Unregister all first to prevent exit handlers from double-emitting
+    for (const entry of allAgents) {
+        reg.unregister(entry.taskId);
+    }
+    const stopPromises = allAgents.map(async (entry) => {
+        const connector = resolveConnector(entry.connectorName);
+        try {
+            await connector.stop(entry);
+        }
+        catch (err) {
+            vmLog.warn("spawner", `Error stopping agent ${entry.taskId}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        ctx.socketClient.emitAgentStatus({
+            agentId: entry.taskId,
+            status: "COMPLETED",
+        });
+    });
+    await Promise.all(stopPromises);
+    vmLog.info("spawner", "All agents stopped");
+}
+/**
+ * Register the task:dispatch Socket.io handler on the CLI socket.
+ */
+export function registerDispatchHandler(socket, orgId, ctx) {
+    socket.on("task:dispatch", (payload) => {
+        const result = TaskDispatchSchema.safeParse(payload);
+        if (!result.success) {
+            vmLog.warn("spawner", `Invalid task:dispatch payload: ${result.error.issues.map((i) => i.message).join(", ")}`);
+            return;
+        }
+        const dispatchParams = {
+            ...result.data,
+            orgId,
+        };
+        // Diagnostic: log received dispatch params to trace command resolution issues
+        const taskCommandPreview = result.data.taskCommand
+            ? `"${result.data.taskCommand.slice(0, 80)}..."`
+            : "MISSING";
+        vmLog.cyan("spawner", `task:dispatch received for ${result.data.taskId} — taskCommand: ${taskCommandPreview}, skillSlug: ${result.data.skillSlug ?? "MISSING"}`);
+        // Fire-and-forget — never await full agent lifecycle
+        spawnAgent(dispatchParams, ctx).catch((err) => {
+            try {
+                vmLog.error("spawner", `Failed to spawn agent for task ${result.data.taskId}: ${err instanceof Error ? err.message : String(err)}`);
+                ctx.socketClient.emitAgentStatus({
+                    agentId: result.data.taskId,
+                    status: "ERROR",
+                });
+            }
+            catch (error_) {
+                vmLog.error("spawner", `Failed to emit error status: ${error_ instanceof Error ? error_.message : String(error_)}`);
+            }
+        });
+    });
+    return { spawnAgent: (params) => spawnAgent(params, ctx) };
+}
+/**
+ * Register the task:resume Socket.io handler on the CLI socket (Story 6.4).
+ */
+export function registerResumeHandler(socket, orgId, ctx) {
+    socket.on("task:resume", (payload) => {
+        const result = TaskResumePayloadSchema.safeParse(payload);
+        if (!result.success) {
+            vmLog.warn("resume", `Invalid task:resume payload: ${result.error.issues.map((i) => i.message).join(", ")}`);
+            return;
+        }
+        const data = result.data;
+        const reg = getRegistry(ctx.agentSlots);
+        // Fire-and-forget — never await full resume lifecycle
+        handleResume({
+            taskId: data.taskId,
+            projectId: data.projectId,
+            orgId,
+            response: data.response,
+            skillSlug: data.skillSlug,
+            taskSlug: data.taskSlug,
+            projectSlug: data.projectSlug,
+            taskBranch: data.taskBranch,
+            repoUrl: data.repoUrl,
+        }, {
+            restClient: ctx.restClient,
+            socketClient: ctx.socketClient,
+            agentType: ctx.agentType,
+            agentSlots: ctx.agentSlots,
+            registry: reg,
+            queue: ctx.queue,
+        }).catch((err) => {
+            vmLog.error("resume", `Failed to resume agent for task ${data.taskId}: ${err instanceof Error ? err.message : String(err)}`);
+            ctx.socketClient.emitAgentStatus({
+                agentId: data.taskId,
+                status: "ERROR",
+            });
+        });
+    });
+}
+/**
+ * Helper: Check slot state for workflow step agent and reserve if needed.
+ * Returns true if slot was reserved; false if duplicate/no capacity.
+ */
+function checkAndReserveWorkflowSlot(reg, agentId) {
+    const existingEntry = reg.getByTaskId(agentId);
+    // If RUNNING, skip duplicate dispatch
+    if (existingEntry?.status === "RUNNING") {
+        vmLog.dim("workflow-dispatch", `Agent already running for step ${agentId}, skipping duplicate dispatch`);
+        return false;
+    }
+    // If pending reservation, skip to prevent race conditions
+    if (reg.hasPendingReservation(agentId)) {
+        vmLog.dim("workflow-dispatch", `Spawn already in flight for step ${agentId}, skipping duplicate`);
+        return false;
+    }
+    // If IDLE, unregister to free the slot for a fresh reserve
+    if (existingEntry?.status === "IDLE") {
+        reg.unregister(agentId);
+    }
+    // Try to reserve (only if not already reserved)
+    if (!existingEntry || existingEntry.status === "IDLE") {
+        if (!reg.reserveSlot(agentId)) {
+            vmLog.warn("workflow-dispatch", `No capacity for step ${agentId}, skipping`);
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * Helper: Handle error exit for workflow step agent (cleanup, emit status).
+ */
+function handleWorkflowStepErrorExit(code, agentId, params, reg, ctx, messageHandler, boundSpawnAgent) {
+    ctx.socketClient.socket.off("workflow:message", messageHandler);
+    const entry = reg.getByTaskId(agentId);
+    if (entry) {
+        entry.status = "ERROR";
+        reg.unregister(agentId);
+    }
+    // Destroy container on error (no idle window, no snapshot save)
+    void (async () => {
+        try {
+            const { getVmManager } = await import("../vm/vm-manager-facade.js");
+            await getVmManager().destroySession(agentId);
+        }
+        catch {
+            /* best effort */
+        }
+    })();
+    const cliCfgErr = getConfig();
+    ctx.socketClient.emitCliHeartbeat({
+        cliId: cliCfgErr.cliId ?? "unknown",
+        status: "CONNECTED",
+        name: cliCfgErr.cliName ?? "CLI",
+        agentSlots: ctx.agentSlots,
+        activeAgents: reg.getProvisionedCount(),
+        runningAgents: reg.getActiveCount(),
+    });
+    ctx.socketClient.emitAgentStatus({
+        agentId,
+        status: "ERROR",
+        projectId: params.projectId,
+    });
+    vmLog.dim("workflow-dispatch", `Agent for step ${agentId} exited with error (code: ${code}), container destroyed`);
+    ctx.queue.drainNext({ spawnAgent: boundSpawnAgent }).catch(() => { });
+}
+/**
+ * Helper: Setup idle window timeout with message handler and auto-drain on expiry.
+ * On timeout: auto-save code + save session snapshot → destroy container → emit timeout.
+ */
+function setupIdleWindowTimeout(agentId, messageHandler, idleState, params, reg, ctx, boundSpawnAgent) {
+    return setTimeout(() => {
+        // Guard: if agent was already resumed, skip cleanup
+        if (idleState.resumed) {
+            vmLog.dim("workflow-dispatch", `Idle timeout fired for step ${agentId} but agent already resumed, skipping`);
+            return;
+        }
+        // Free slot FIRST (synchronously), then do async snapshot/cleanup.
+        // This ensures board tasks can dispatch immediately, even if
+        // snapshot save or container destroy is slow.
+        idleWindows.delete(agentId);
+        ctx.socketClient.socket.off("workflow:message", messageHandler);
+        reg.unregister(agentId);
+        ctx.socketClient.emitWorkflowAgentTimeout({
+            workflowId: params.workflowId,
+            stepId: params.stepId,
+        });
+        const cliCfg = getConfig();
+        ctx.socketClient.emitCliHeartbeat({
+            cliId: cliCfg.cliId ?? "unknown",
+            status: "CONNECTED",
+            name: cliCfg.cliName ?? "CLI",
+            agentSlots: ctx.agentSlots,
+            activeAgents: reg.getProvisionedCount(),
+            runningAgents: reg.getActiveCount(),
+        });
+        vmLog.dim("workflow-dispatch", `Idle window expired for step ${agentId} (slot freed)`);
+        // Drain queue immediately — slot is free now
+        ctx.queue.drainNext({ spawnAgent: boundSpawnAgent }).catch(() => { });
+        // Async: save snapshot + destroy container (best-effort, non-blocking)
+        void (async () => {
+            try {
+                const { getVmManager } = await import("../vm/vm-manager-facade.js");
+                const sm = getVmManager();
+                const session = sm.getSessionByTaskId(agentId);
+                if (session) {
+                    const { autoSaveCode, createSessionSnapshot } = await import("../vm/session-snapshot.js");
+                    await autoSaveCode(session.containerId, session.id, session.gitCredentials);
+                    const snapshot = await createSessionSnapshot(session);
+                    if (snapshot) {
+                        ctx.socketClient.socket.emit("workflow:step:snapshot", {
+                            orgId: params.orgId,
+                            workflowId: params.workflowId,
+                            stepId: params.stepId,
+                            snapshot,
+                        });
+                        vmLog.cyan("workflow-dispatch", `Session snapshot uploaded for step ${agentId}`);
+                    }
+                    await sm.destroySession(agentId);
+                }
+            }
+            catch (saveErr) {
+                vmLog.warn("workflow-dispatch", `Failed to save snapshot on idle timeout: ${saveErr instanceof Error ? saveErr.message : String(saveErr)}`);
+                try {
+                    const { getVmManager } = await import("../vm/vm-manager-facade.js");
+                    await getVmManager().destroySession(agentId);
+                }
+                catch {
+                    /* best effort */
+                }
+            }
+        })();
+    }, IDLE_WINDOW_MS);
+}
+/**
+ * Spawn an agent for a workflow step dispatch (Story 6b-7).
+ * Similar to spawnAgent but uses workflow context for MCP config and step command as prompt.
+ * After agent exits (code 0), enters a 5-minute idle window for follow-up messages.
+ */
+async function spawnWorkflowStepAgent(params, ctx) {
+    const reg = getRegistry(ctx.agentSlots);
+    // Use stepId as the agent identifier (like taskId for task agents)
+    const agentId = params.stepId;
+    // 1. Reserve slot (if not already reserved from idle window resume)
+    if (!checkAndReserveWorkflowSlot(reg, agentId)) {
+        return;
+    }
+    let messageHandlerRef = null;
+    let slotWasReserved = false;
+    try {
+        slotWasReserved = true;
+        // Pull and prepare skill
+        const skillName = params.skillSlug ?? DEFAULT_SKILL_NAME;
+        const skill = await pullSkill(skillName, ctx.restClient);
+        // Resolve connector (always VM now)
+        const connector = resolveConnector(ctx.agentType);
+        // Build prompt: base command + optional conversation history
+        let prompt = params.stepCommand ?? params.stepTitle;
+        if (params.conversationHistory) {
+            prompt = `${prompt}\n\n## Conversation History\n\n${params.conversationHistory}`;
+        }
+        // VM connector handles everything: boot VM, clone, checkout, workspace, spawn
+        const vmSpawnParams = {
+            taskId: agentId,
+            projectId: params.projectId,
+            orgId: params.orgId,
+            workingDir: "/workspace",
+            mcpConfigPath: "/workspace/.claude/mcp_config.json",
+            skillName: skill?.name ?? skillName,
+            prompt,
+            repoUrl: params.repoUrl,
+            taskBranch: params.baseBranch,
+            workflowBaseBranch: params.sourceBranch,
+            skill: skill ? { name: skill.name, files: skill.files } : undefined,
+            workflowContext: {
+                workflowId: params.workflowId,
+                stepId: params.stepId,
+            },
+        };
+        // Join workflow room for message streaming
+        ctx.socketClient.socket.emit("join:workflow", params.workflowId);
+        // If snapshot available, fetch it and use resumeWithSnapshot for --continue.
+        // With --continue, Claude Code already has the full session context.
+        // The -p prompt should be ONLY the user's latest message, not stepCommand + history.
+        let result;
+        if (params.hasSnapshot && connector.resumeWithSnapshot) {
+            // For --continue, extract the user's latest message for -p.
+            // The session snapshot already has the full conversation context.
+            let snapshotPrompt;
+            if (params.conversationHistory) {
+                // History format: "USER: content\n\nASSISTANT: content\n\n..."
+                const lines = params.conversationHistory.split("\n\n");
+                const lastUserLine = lines
+                    .reverse()
+                    .find((l) => l.startsWith("USER: "));
+                if (lastUserLine) {
+                    snapshotPrompt = lastUserLine.replace(/^USER: /, "");
+                }
+            }
+            // If no conversation history (e.g. auto-retry dispatch), use generic continue.
+            // Do NOT pass stepCommand — the snapshot already has the task context.
+            vmSpawnParams.prompt =
+                snapshotPrompt ?? "Continue your work from where you left off.";
+            vmLog.cyan("workflow-dispatch", `Fetching session snapshot for step ${agentId}`);
+            const snapshotData = await new Promise((resolve) => {
+                const timeout = setTimeout(() => resolve(null), 10_000);
+                ctx.socketClient.socket.emit("workflow:step:snapshot:fetch", { workflowId: params.workflowId, stepId: params.stepId }, (data) => {
+                    clearTimeout(timeout);
+                    resolve(data);
+                });
+            });
+            if (snapshotData?.snapshot) {
+                vmLog.cyan("workflow-dispatch", `Snapshot received (${(snapshotData.snapshot.length / 1024).toFixed(0)}KB), restoring with --continue`);
+                vmSpawnParams.sessionSnapshotBase64 = snapshotData.snapshot;
+                result = await connector.resumeWithSnapshot(vmSpawnParams);
+            }
+            else {
+                vmLog.warn("workflow-dispatch", `Snapshot fetch failed for step ${agentId}, falling back to fresh start`);
+                result = await connector.start(vmSpawnParams);
+            }
+        }
+        else {
+            result = await connector.start(vmSpawnParams);
+        }
+        // Register in agent registry (overwrite if resuming from idle)
+        reg.confirmSlot(agentId, {
+            taskId: agentId,
+            pid: result.pid,
+            process: result.process,
+            connectorName: connector.name,
+            workingDir: "/workspace",
+            orgId: params.orgId,
+            startedAt: new Date().toISOString(),
+            status: "RUNNING",
+            vmId: result.vmId,
+        });
+        // 7. Emit agent:status(RUNNING) + immediate heartbeat so browser
+        // shows the agent as provisioned right away (not waiting for next 30s tick)
+        ctx.socketClient.emitAgentStatus({
+            agentId,
+            status: "RUNNING",
+            projectId: params.projectId,
+        });
+        const cliCfg = getConfig();
+        ctx.socketClient.emitCliHeartbeat({
+            cliId: cliCfg.cliId ?? "unknown",
+            status: "CONNECTED",
+            name: cliCfg.cliName ?? "CLI",
+            agentSlots: ctx.agentSlots,
+            activeAgents: reg.getProvisionedCount(),
+            runningAgents: reg.getActiveCount(),
+        });
+        vmLog.info("workflow-dispatch", `Agent spawned for step ${agentId} (PID: ${result.pid}, connector: ${connector.name})`);
+        // 8. Register workflow:message listener for user messages
+        let messageHandlerConsumed = false;
+        const messageHandler = (payload) => {
+            if (payload.workflowId !== params.workflowId)
+                return;
+            if (payload.role !== "USER")
+                return;
+            if (messageHandlerConsumed)
+                return;
+            // Check if agent is in idle window — resume with user message
+            const idleState = idleWindows.get(agentId);
+            if (idleState) {
+                // Set resumed flag BEFORE clearTimeout — prevents race where timeout
+                // callback fires concurrently during async resume
+                idleState.resumed = true;
+                messageHandlerConsumed = true;
+                vmLog.cyan("workflow-dispatch", `Resuming idle agent for step ${agentId} with user message`);
+                clearTimeout(idleState.timer);
+                // Remove THIS handler before resume spawns a new one (prevents duplicates)
+                ctx.socketClient.socket.off("workflow:message", messageHandler);
+                idleWindows.delete(agentId);
+                // Resume: spawn fresh agent with conversation context
+                resumeWorkflowStepAgent(agentId, payload.content, idleState.lastAssistantContent, params, ctx).catch((err) => {
+                    try {
+                        vmLog.error("workflow-dispatch", `Failed to resume agent for step ${agentId}: ${err instanceof Error ? err.message : String(err)}`);
+                    }
+                    catch {
+                        // Best-effort logging
+                    }
+                });
+                return;
+            }
+            // Agent is running in one-shot mode — can't write to stdin
+            // Notify user via system message so wizard-chat shows feedback
+            ctx.socketClient.socket.emit("workflow:message", {
+                orgId: params.orgId,
+                workflowId: params.workflowId,
+                stepId: params.stepId,
+                conversationId: params.conversationId ?? "",
+                messageId: randomUUID(),
+                content: "Agent is processing — your message will be handled when the current step completes.",
+                role: "SYSTEM",
+                timestamp: new Date().toISOString(),
+            });
+            vmLog.warn("workflow-dispatch", `Agent running in one-shot mode for step ${agentId}, message will be handled on next idle cycle`);
+        };
+        ctx.socketClient.socket.on("workflow:message", messageHandler);
+        messageHandlerRef = messageHandler;
+        // 9. Attach workflow process handlers with idle window on exit
+        const boundSpawnAgent = (p) => spawnAgent(p, ctx);
+        attachWorkflowProcessHandlers(result.process, {
+            taskId: agentId,
+            projectId: params.projectId,
+            registry: reg,
+            socketClient: ctx.socketClient,
+            restClient: ctx.restClient,
+            queue: ctx.queue,
+            spawnAgentFn: boundSpawnAgent,
+            label: "workflow-dispatch",
+            agentSlots: ctx.agentSlots,
+            sessionId: result.vmId,
+            workflowId: params.workflowId,
+            stepId: params.stepId,
+            conversationId: params.conversationId ?? agentId,
+            onExit: (code, accumulatedContent) => {
+                // On error exit, clean up immediately — no idle window
+                if (code !== 0) {
+                    handleWorkflowStepErrorExit(code, agentId, params, reg, ctx, messageHandler, boundSpawnAgent);
+                    return;
+                }
+                // If user already approved/advanced while agent was running,
+                // skip idle window — destroy container and free slot immediately.
+                if (dismissedWhileRunning.has(agentId)) {
+                    dismissedWhileRunning.delete(agentId);
+                    vmLog.cyan("workflow-dispatch", `Agent for step ${agentId} exited — dismissed while running, saving code before destroy`);
+                    ctx.socketClient.socket.off("workflow:message", messageHandler);
+                    reg.unregister(agentId);
+                    void (async () => {
+                        try {
+                            const { getVmManager } = await import("../vm/vm-manager-facade.js");
+                            const sm = getVmManager();
+                            const session = sm.getSessionByTaskId(agentId);
+                            if (session) {
+                                const { autoSaveCode } = await import("../vm/session-snapshot.js");
+                                await autoSaveCode(session.containerId, session.id, session.gitCredentials);
+                            }
+                            await sm.destroySession(agentId);
+                        }
+                        catch {
+                            /* best effort */
+                        }
+                    })();
+                    const cliDismiss = getConfig();
+                    ctx.socketClient.emitCliHeartbeat({
+                        cliId: cliDismiss.cliId ?? "unknown",
+                        status: "CONNECTED",
+                        name: cliDismiss.cliName ?? "CLI",
+                        agentSlots: ctx.agentSlots,
+                        activeAgents: reg.getProvisionedCount(),
+                        runningAgents: reg.getActiveCount(),
+                    });
+                    ctx.queue.drainNext({ spawnAgent: boundSpawnAgent }).catch(() => { });
+                    return;
+                }
+                // Success exit: enter 5-minute idle window
+                const entry = reg.getByTaskId(agentId);
+                if (entry) {
+                    entry.status = "IDLE";
+                }
+                const idleUntil = new Date(Date.now() + IDLE_WINDOW_MS).toISOString();
+                ctx.socketClient.emitWorkflowAgentIdle({
+                    workflowId: params.workflowId,
+                    stepId: params.stepId,
+                    idleUntil,
+                });
+                // Emit fresh heartbeat so browser sees agent as provisioned during idle
+                const cliConfig = getConfig();
+                ctx.socketClient.emitCliHeartbeat({
+                    cliId: cliConfig.cliId ?? "unknown",
+                    status: "CONNECTED",
+                    name: cliConfig.cliName ?? "CLI",
+                    agentSlots: ctx.agentSlots,
+                    activeAgents: reg.getProvisionedCount(),
+                    runningAgents: reg.getActiveCount(),
+                });
+                vmLog.cyan("workflow-dispatch", `Agent for step ${agentId} entering idle window until ${idleUntil} (slot provisioned)`);
+                // Create idle state object first so timeout and messageHandler share
+                // the same `resumed` flag via object reference
+                const idleState = {
+                    timer: null,
+                    spawnParams: vmSpawnParams,
+                    connector,
+                    messageHandler,
+                    workflowId: params.workflowId,
+                    stepId: params.stepId,
+                    conversationId: params.conversationId ?? agentId,
+                    stepCommand: params.stepCommand,
+                    stepTitle: params.stepTitle,
+                    projectId: params.projectId,
+                    repoUrl: params.repoUrl,
+                    projectSlug: params.projectSlug,
+                    lastAssistantContent: accumulatedContent,
+                    resumed: false,
+                };
+                idleState.timer = setupIdleWindowTimeout(agentId, messageHandler, idleState, params, reg, ctx, boundSpawnAgent);
+                idleWindows.set(agentId, idleState);
+            },
+        });
+    }
+    catch (err) {
+        // Clean up message listener if it was registered
+        if (messageHandlerRef) {
+            ctx.socketClient.socket.off("workflow:message", messageHandlerRef);
+        }
+        // Only release if we reserved (not resuming from idle)
+        if (slotWasReserved) {
+            reg.releaseSlot(agentId);
+        }
+        throw err;
+    }
+}
+/**
+ * Resume a workflow step agent from idle window with a new user message.
+ * Uses `claude --continue` in the same container for full context preservation.
+ * Falls back to fresh spawn with conversation history if container is dead.
+ */
+async function resumeWorkflowStepAgent(agentId, userMessage, lastAssistantContent, originalParams, ctx) {
+    // Try --continue in the same container (container stays alive during idle window)
+    const { getVmManager } = await import("../vm/vm-manager-facade.js");
+    const sm = getVmManager();
+    const session = sm.getSessionByTaskId(agentId);
+    if (session && session.status === "RUNNING") {
+        vmLog.cyan("workflow-dispatch", `Resuming step ${agentId} with --continue in existing container ${session.id}`);
+        // Use connector.resume() which handles MCP restart + --continue
+        const connector = resolveConnector(ctx.agentType);
+        const vmSpawnParams = {
+            taskId: agentId,
+            projectId: originalParams.projectId,
+            orgId: originalParams.orgId,
+            workingDir: "/workspace",
+            mcpConfigPath: "/workspace/.claude/mcp_config.json",
+            skillName: DEFAULT_SKILL_NAME,
+            prompt: userMessage,
+            repoUrl: originalParams.repoUrl,
+            taskBranch: originalParams.baseBranch,
+            workflowBaseBranch: originalParams.sourceBranch,
+            workflowContext: {
+                workflowId: originalParams.workflowId,
+                stepId: originalParams.stepId,
+            },
+        };
+        const result = await connector.resume(vmSpawnParams);
+        // Re-register in agent registry
+        const reg = getRegistry(ctx.agentSlots);
+        reg.confirmSlot(agentId, {
+            taskId: agentId,
+            pid: result.pid,
+            process: result.process,
+            connectorName: connector.name,
+            workingDir: "/workspace",
+            orgId: originalParams.orgId,
+            startedAt: new Date().toISOString(),
+            status: "RUNNING",
+            vmId: result.vmId,
+        });
+        ctx.socketClient.emitAgentStatus({
+            agentId,
+            status: "RUNNING",
+            projectId: originalParams.projectId,
+        });
+        const cliCfg = getConfig();
+        ctx.socketClient.emitCliHeartbeat({
+            cliId: cliCfg.cliId ?? "unknown",
+            status: "CONNECTED",
+            name: cliCfg.cliName ?? "CLI",
+            agentSlots: ctx.agentSlots,
+            activeAgents: reg.getProvisionedCount(),
+            runningAgents: reg.getActiveCount(),
+        });
+        // Re-attach workflow process handlers with new idle window
+        const boundSpawnAgent = (p) => spawnAgent(p, ctx);
+        let newMessageHandlerConsumed = false;
+        const newMessageHandler = (payload) => {
+            if (payload.workflowId !== originalParams.workflowId)
+                return;
+            if (payload.role !== "USER")
+                return;
+            if (newMessageHandlerConsumed)
+                return;
+            const newIdleState = idleWindows.get(agentId);
+            if (newIdleState) {
+                newIdleState.resumed = true;
+                newMessageHandlerConsumed = true;
+                clearTimeout(newIdleState.timer);
+                ctx.socketClient.socket.off("workflow:message", newMessageHandler);
+                idleWindows.delete(agentId);
+                resumeWorkflowStepAgent(agentId, payload.content, newIdleState.lastAssistantContent, originalParams, ctx).catch((err) => {
+                    vmLog.error("workflow-dispatch", `Failed to resume: ${err instanceof Error ? err.message : String(err)}`);
+                });
+            }
+        };
+        ctx.socketClient.socket.on("workflow:message", newMessageHandler);
+        attachWorkflowProcessHandlers(result.process, {
+            taskId: agentId,
+            projectId: originalParams.projectId,
+            registry: reg,
+            socketClient: ctx.socketClient,
+            restClient: ctx.restClient,
+            queue: ctx.queue,
+            spawnAgentFn: boundSpawnAgent,
+            label: "workflow-dispatch",
+            agentSlots: ctx.agentSlots,
+            sessionId: result.vmId,
+            workflowId: originalParams.workflowId,
+            stepId: originalParams.stepId,
+            conversationId: originalParams.conversationId ?? agentId,
+            onExit: (code, accumulatedContent) => {
+                if (code !== 0) {
+                    handleWorkflowStepErrorExit(code, agentId, originalParams, reg, ctx, newMessageHandler, boundSpawnAgent);
+                    return;
+                }
+                // Re-enter idle window
+                const entry = reg.getByTaskId(agentId);
+                if (entry)
+                    entry.status = "IDLE";
+                const idleUntil = new Date(Date.now() + IDLE_WINDOW_MS).toISOString();
+                ctx.socketClient.emitWorkflowAgentIdle({
+                    workflowId: originalParams.workflowId,
+                    stepId: originalParams.stepId,
+                    idleUntil,
+                });
+                const cliResume = getConfig();
+                ctx.socketClient.emitCliHeartbeat({
+                    cliId: cliResume.cliId ?? "unknown",
+                    status: "CONNECTED",
+                    name: cliResume.cliName ?? "CLI",
+                    agentSlots: ctx.agentSlots,
+                    activeAgents: reg.getProvisionedCount(),
+                    runningAgents: reg.getActiveCount(),
+                });
+                vmLog.cyan("workflow-dispatch", `Agent for step ${agentId} re-entering idle window until ${idleUntil} (slot provisioned)`);
+                const resumeIdleState = {
+                    timer: null,
+                    spawnParams: vmSpawnParams,
+                    connector,
+                    messageHandler: newMessageHandler,
+                    workflowId: originalParams.workflowId,
+                    stepId: originalParams.stepId,
+                    conversationId: originalParams.conversationId ?? agentId,
+                    stepCommand: originalParams.stepCommand,
+                    stepTitle: originalParams.stepTitle,
+                    projectId: originalParams.projectId,
+                    repoUrl: originalParams.repoUrl,
+                    projectSlug: originalParams.projectSlug,
+                    lastAssistantContent: accumulatedContent,
+                    resumed: false,
+                };
+                resumeIdleState.timer = setupIdleWindowTimeout(agentId, newMessageHandler, resumeIdleState, originalParams, reg, ctx, boundSpawnAgent);
+                idleWindows.set(agentId, resumeIdleState);
+            },
+        });
+        return;
+    }
+    // Fallback: container is dead — fresh start with conversation history
+    vmLog.warn("workflow-dispatch", `Container dead for step ${agentId}, falling back to fresh spawn with history`);
+    const historyParts = [];
+    if (lastAssistantContent) {
+        historyParts.push(`ASSISTANT: ${lastAssistantContent}`);
+    }
+    historyParts.push(`USER: ${userMessage}`);
+    const conversationHistory = historyParts.join("\n\n");
+    await spawnWorkflowStepAgent({
+        ...originalParams,
+        conversationHistory,
+    }, ctx);
+}
+/**
+ * Register the workflow:step:dispatch Socket.io handler on the CLI socket (Story 6b-7).
+ */
+export function registerWorkflowStepDispatchHandler(socket, orgId, ctx) {
+    // Remove any existing listeners to prevent handler stacking on reconnect
+    socket.removeAllListeners("workflow:step:dispatch");
+    socket.on("workflow:step:dispatch", (payload) => {
+        const result = WorkflowStepDispatchPayloadSchema.safeParse(payload);
+        if (!result.success) {
+            vmLog.warn("workflow-dispatch", `Invalid workflow:step:dispatch payload: ${result.error.issues.map((i) => i.message).join(", ")}`);
+            return;
+        }
+        const data = result.data;
+        const stepCommandPreview = data.stepCommand
+            ? `"${data.stepCommand.slice(0, 80)}..."`
+            : "MISSING";
+        vmLog.cyan("workflow-dispatch", `workflow:step:dispatch for ${data.stepId} — stepCommand: ${stepCommandPreview}, hasSnapshot: ${data.hasSnapshot ?? false}, skillSlug: ${data.skillSlug ?? "MISSING"}`);
+        // Fire-and-forget — never await full agent lifecycle
+        spawnWorkflowStepAgent({
+            stepId: data.stepId,
+            workflowId: data.workflowId,
+            projectId: data.projectId,
+            orgId,
+            skillSlug: data.skillSlug,
+            stepCommand: data.stepCommand,
+            stepTitle: data.stepTitle,
+            conversationId: data.conversationId,
+            repoUrl: data.repoUrl,
+            projectSlug: data.projectSlug,
+            workflowSlug: data.workflowSlug,
+            baseBranch: data.baseBranch,
+            sourceBranch: data.sourceBranch,
+            conversationHistory: data.conversationHistory,
+            hasSnapshot: data.hasSnapshot,
+        }, ctx).catch((err) => {
+            try {
+                vmLog.error("workflow-dispatch", `Failed to spawn agent for step ${data.stepId}: ${err instanceof Error ? err.message : String(err)}`);
+                ctx.socketClient.emitAgentStatus({
+                    agentId: data.stepId,
+                    status: "ERROR",
+                });
+            }
+            catch (error_) {
+                vmLog.error("workflow-dispatch", `Failed to emit error status: ${error_ instanceof Error ? error_.message : String(error_)}`);
+            }
+        });
+    });
+}
+/**
+ * Register workflow:agent:dismiss handler — Cloud tells CLI to clear idle window.
+ * Called when user advances to next step after approving deliverables.
+ */
+export function registerWorkflowAgentDismissHandler(socket, ctx) {
+    socket.removeAllListeners("workflow:agent:dismiss");
+    socket.on("workflow:agent:dismiss", (payload) => {
+        // Validate payload shape (minimal — just need stepId)
+        if (!payload || typeof payload !== "object")
+            return;
+        const data = payload;
+        const stepId = data.stepId;
+        if (typeof stepId !== "string")
+            return;
+        const agentId = stepId; // In workflow dispatch, agentId === stepId
+        const idleState = idleWindows.get(agentId);
+        if (!idleState) {
+            // Agent might still be RUNNING (dismiss arrived before idle window).
+            // Mark it so onExit skips the idle window and destroys immediately.
+            const reg = getRegistry(ctx.agentSlots);
+            const entry = reg.getByTaskId(agentId);
+            if (entry?.status === "RUNNING") {
+                dismissedWhileRunning.add(agentId);
+                vmLog.cyan("workflow-dispatch", `workflow:agent:dismiss for step ${agentId} — agent still running, will skip idle on exit`);
+            }
+            else {
+                vmLog.dim("workflow-dispatch", `workflow:agent:dismiss for step ${agentId} — no idle window and not running, skipping`);
+            }
+            return;
+        }
+        // Set resumed flag to prevent timeout callback from firing
+        idleState.resumed = true;
+        clearTimeout(idleState.timer);
+        ctx.socketClient.socket.off("workflow:message", idleState.messageHandler);
+        idleWindows.delete(agentId);
+        const reg = getRegistry(ctx.agentSlots);
+        reg.unregister(agentId);
+        // Save code before destroying container (preserves agent's work for next step)
+        void (async () => {
+            try {
+                const { getVmManager } = await import("../vm/vm-manager-facade.js");
+                const sm = getVmManager();
+                const session = sm.getSessionByTaskId(agentId);
+                if (session) {
+                    const { autoSaveCode } = await import("../vm/session-snapshot.js");
+                    await autoSaveCode(session.containerId, session.id, session.gitCredentials);
+                }
+                await sm.destroySession(agentId);
+            }
+            catch {
+                /* best effort */
+            }
+        })();
+        // Emit fresh heartbeat so browser sees slot freed
+        const cliConfig = getConfig();
+        ctx.socketClient.emitCliHeartbeat({
+            cliId: cliConfig.cliId ?? "unknown",
+            status: "CONNECTED",
+            name: cliConfig.cliName ?? "CLI",
+            agentSlots: ctx.agentSlots,
+            activeAgents: reg.getProvisionedCount(),
+            runningAgents: reg.getActiveCount(),
+        });
+        vmLog.cyan("workflow-dispatch", `Idle agent for step ${agentId} dismissed (step advanced, container destroyed, slot freed)`);
+    });
+}
+//# sourceMappingURL=agent-spawner.js.map