qlogicagent 2.13.4 → 2.13.5

package/dist/runtime/infra/agent-process.js

@@ -0,0 +1,1318 @@
+/**
+ * Agent Process Manager — CC tmux-aligned subprocess isolation.
+ *
+ * Spawns team member agents as independent child processes, each with:
+ *   - Own cwd (set to worktree path for git isolation)
+ *   - Own stdin/stdout JSON-RPC transport
+ *   - Own memory + tool context (no shared process.cwd)
+ *   - Lifecycle tracking (PID, health, abort)
+ *
+ * CC does this via tmux split-pane + `claudeagent-id ...` commands.
+ * We spawn `node dist/cli.js` as child processes with JSON-RPC stdio.
+ *
+ * Reference: claude-code-haha/src/utils/swarm/spawnMultiAgent.ts
+ * Reference: claude-code-haha/src/utils/swarm/spawnUtils.ts
+ */
+import { spawn, execFile } from "node:child_process";
+import { createInterface } from "node:readline";
+import { resolve, join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { createServer } from "node:net";
+import { createWriteStream, mkdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { ACP_MAX_SPAWN_RETRIES, ACP_RETRY_BACKOFF_BASE, ACP_RUNTIME_RESTART_MAX, ACP_RUNTIME_RESTART_BACKOFF_BASE, } from "../config/tunable-defaults.js";
+import { AcpProtocolAdapter, asAuthRequiredError } from "./acp-protocol-adapter.js";
+import { createAcpHostHandler } from "./acp-host-handler.js";
+import { AcpUsageTracker } from "./acp-usage-tracker.js";
+import { ACP_BACKENDS } from "./acp-detector.js";
+import { buildAgentRpcMeta } from "../../protocol/wire/index.js";
+let rpcIdCounter = 1;
+function buildRpcRequest(method, params) {
+    return { jsonrpc: "2.0", id: rpcIdCounter++, method, params, meta: buildAgentRpcMeta(method) };
+}
+// ── Env Var Forwarding (CC spawnUtils parity) ───────────────
+/** Environment variables forwarded to child agents (CC getEnvVarInheritanceList parity). */
+const FORWARDED_ENV_KEYS = [
+    "NODE_ENV",
+    "HOME",
+    "PATH",
+    "TERM",
+    // LLM config
+    "OPENAI_API_KEY",
+    "OPENAI_BASE_URL",
+    "ANTHROPIC_API_KEY",
+    "ANTHROPIC_BASE_URL",
+    // llmrouter model catalog — without these a member subprocess cannot reach the
+    // catalog ("无法连接 llmrouter 模型目录") and fails its first turn. Forward the
+    // parent's catalog config so the member resolves models with the same access.
+    "QLOGIC_LLMROUTER_BASE_URL",
+    "QLOGIC_LLMROUTER_ACCESS_TOKEN",
+    "QLOGIC_LLMROUTER_USER_ID",
+    "QLOGIC_LLMROUTER_INFERENCE_KEY",
+    "QLOGIC_LLMROUTER_EMBEDDING_MODEL",
+    "QLOGIC_LLMROUTER_EMBEDDING_DIMENSIONS",
+    // Proxy
+    "HTTP_PROXY",
+    "HTTPS_PROXY",
+    "NO_PROXY",
+    "http_proxy",
+    "https_proxy",
+    "no_proxy",
+];
+function buildChildEnv(config) {
+    const env = {};
+    // Forward selected env vars from parent
+    for (const key of FORWARDED_ENV_KEYS) {
+        if (process.env[key]) {
+            env[key] = process.env[key];
+        }
+    }
+    // NOTE: config.provider/model/apiKey/baseUrl are intentionally NOT mirrored into
+    // env. Internal children consume them as standing session config (pushed via
+    // session/set_config_option after session/new) — the env mirror was a dead
+    // channel nothing read, masquerading as provider pass-through.
+    // Agent identity
+    env.QLOGICAGENT_MEMBER_ID = config.memberId;
+    env.QLOGICAGENT_MEMBER_NAME = config.name;
+    if (config.agentType)
+        env.QLOGICAGENT_AGENT_TYPE = config.agentType;
+    // Merge user-provided env
+    if (config.env)
+        Object.assign(env, config.env);
+    return env;
+}
+/**
+ * Build LLM-related environment variables for an external ACP teammate.
+ *
+ * Priority chain:
+ *   1. Per-agent override (AgentConfig.apiKey / baseUrl)
+ *   2. Gateway proxy mode (all requests through shared gateway)
+ *   3. Inherit from qlogicagent's own env
+ *
+ * Handles the asymmetry between agents that support base URL override
+ * (can redirect to gateway) vs those that don't (only API key forwarding).
+ */
+export function buildLlmEnvForTeammate(agentId, agentConfig, gatewayUrl) {
+    const env = {};
+    const backend = ACP_BACKENDS[agentId];
+    const apiKeyEnvVar = backend?.apiKeyEnvVar;
+    const baseUrlEnvVar = backend?.baseUrlEnvVar;
+    const supportsBaseUrl = backend?.supportsBaseUrlOverride ?? false;
+    // 1. Per-agent override (highest priority)
+    if (agentConfig?.apiKey && apiKeyEnvVar) {
+        env[apiKeyEnvVar] = agentConfig.apiKey;
+    }
+    if (agentConfig?.baseUrl && baseUrlEnvVar && supportsBaseUrl) {
+        env[baseUrlEnvVar] = agentConfig.baseUrl;
+    }
+    // 2. Gateway proxy mode — inject if agent supports base URL and no per-agent baseUrl override
+    if (gatewayUrl && supportsBaseUrl && baseUrlEnvVar && !agentConfig?.baseUrl) {
+        env[baseUrlEnvVar] = gatewayUrl;
+    }
+    // 3. Inherit — already handled by buildChildEnv() forwarding FORWARDED_ENV_KEYS
+    // No additional work needed here.
+    // Merge per-agent custom env vars
+    if (agentConfig?.env) {
+        Object.assign(env, agentConfig.env);
+    }
+    return env;
+}
+// ── Error Classification & Retry ────────────────────────────
+/** Fault severity levels for ACP agent errors. */
+export const ACP_FAULT_LEVEL = {
+    /** Unrecoverable — agent binary missing, permission denied, etc. */
+    FATAL: "fatal",
+    /** Retriable — spawn timeout, handshake timeout, transient crash. */
+    RETRIABLE: "retriable",
+    /** Warning — non-critical issue (e.g. degraded capabilities). */
+    WARN: "warn",
+};
+const MAX_SPAWN_RETRIES = ACP_MAX_SPAWN_RETRIES;
+const RETRY_BACKOFF_BASE = ACP_RETRY_BACKOFF_BASE;
+const RUNTIME_RESTART_MAX = ACP_RUNTIME_RESTART_MAX;
+const RUNTIME_RESTART_BACKOFF_BASE = ACP_RUNTIME_RESTART_BACKOFF_BASE;
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Terminate a process AND all its descendants. On Windows, child.kill() ends only the direct
+ * process, orphaning grandchildren — e.g. kimi-cli (a Python launcher) leaves its interpreter
+ * subprocesses running, which pile up across spawns and bog the machine (slow cold starts →
+ * ACP handshake timeouts). `taskkill /T` reaps the whole tree; POSIX falls back to SIGTERM→SIGKILL.
+ */
+function killProcessTree(child, pid) {
+    if (process.platform === "win32" && typeof pid === "number" && pid > 0) {
+        try {
+            execFile("taskkill", ["/PID", String(pid), "/T", "/F"], () => { });
+            return;
+        }
+        catch { /* fall through to signal kill */ }
+    }
+    try {
+        child.kill("SIGTERM");
+        setTimeout(() => { try {
+            child.kill("SIGKILL");
+        }
+        catch { /* already gone */ } }, 10_000);
+    }
+    catch { /* already gone */ }
+}
+// ── Agent Process Manager ───────────────────────────────────
+/**
+ * Manages a pool of child agent processes.
+ * Each child is a `qlogicagent` subprocess using JSON-RPC over stdio.
+ */
+export class AgentProcessManager {
+    processes = new Map();
+    callbacks;
+    cliBinaryPath;
+    mcpBridgeScriptPath;
+    constructor(callbacks = {}) {
+        this.callbacks = callbacks;
+        // Resolve binary path: use the same dist/cli.js from our own package
+        const packageRoot = resolve(join(import.meta.url.startsWith("file://")
+            ? new URL(import.meta.url).pathname.replace(/^\/([A-Z]:)/, "$1")
+            : process.cwd(), "..", // from dist/ or src/ go up
+        ".."));
+        this.cliBinaryPath = join(packageRoot, "dist", "cli.js");
+        this.mcpBridgeScriptPath = join(packageRoot, "dist", "runtime", "infra", "mcp-bridge-server.js");
+    }
+    // ── Q-1 Structured Logging ──────────────────────────────
+    /** Format: [ISO] [level] [agent:id] [phase] message */
+    slog(level, agentId, phase, message) {
+        const ts = new Date().toISOString();
+        const line = `[${ts}] [${level}] [agent:${agentId}] [${phase}] ${message}`;
+        if (level === "warn") {
+            this.callbacks.log?.warn(line);
+        }
+        else {
+            this.callbacks.log?.info(line);
+        }
+    }
+    /** Spawn a child agent process in the given cwd. */
+    async spawn(config) {
+        if (this.processes.has(config.memberId)) {
+            throw new Error(`Agent process "${config.memberId}" already spawned`);
+        }
+        const log = this.callbacks.log;
+        const env = buildChildEnv(config);
+        const handle = {
+            memberId: config.memberId,
+            name: config.name,
+            pid: -1,
+            cwd: config.cwd,
+            state: "starting",
+            startedAt: Date.now(),
+        };
+        // ── ACP External Agent Path ─────────────────────────────
+        if (config.external) {
+            return this.spawnAcpAgentWithRetry(config, handle, env);
+        }
+        // ── Internal Agent Path (original) ──────────────────────
+        const args = [this.cliBinaryPath];
+        if (config.verbose)
+            args.push("--verbose");
+        this.slog("info", config.memberId, "spawn", `spawning ${config.name} in ${config.cwd}`);
+        const child = spawn(process.execPath, args, {
+            cwd: config.cwd,
+            env,
+            stdio: ["pipe", "pipe", "pipe"],
+            // Prevent child from keeping parent alive
+            detached: false,
+        });
+        handle.pid = child.pid ?? -1;
+        const pendingRpc = new Map();
+        this.processes.set(config.memberId, { handle, child, pendingRpc });
+        // Parse child stdout as line-delimited JSON-RPC
+        const rl = createInterface({ input: child.stdout, crlfDelay: Number.POSITIVE_INFINITY });
+        rl.on("line", (line) => {
+            const trimmed = line.trim();
+            if (!trimmed)
+                return;
+            try {
+                const msg = JSON.parse(trimmed);
+                const hasId = "id" in msg;
+                const hasMethod = "method" in msg && typeof msg.method === "string";
+                // Request FROM child TO parent (host) — e.g. session/request_permission.
+                if (hasId && hasMethod) {
+                    this.handleChildHostRequest(config.memberId, msg);
+                    return;
+                }
+                // Response to a pending request we sent.
+                if (hasId) {
+                    const pending = pendingRpc.get(msg.id);
+                    if (pending) {
+                        clearTimeout(pending.timer);
+                        pendingRpc.delete(msg.id);
+                        const resp = msg;
+                        if (resp.error) {
+                            pending.reject(new Error(resp.error.message));
+                        }
+                        else {
+                            pending.resolve(resp.result);
+                        }
+                    }
+                    return;
+                }
+                // Notification from child — translate ACP session/update to internal turn.* form
+                // so captureChildProgress + onNotification see the same shape as the legacy path.
+                if (hasMethod) {
+                    const translated = AcpProtocolAdapter.translateNotification(msg.method, msg.params);
+                    const method = translated?.method ?? msg.method;
+                    const params = translated?.params ?? msg.params;
+                    this.captureChildProgress(config.memberId, method, params);
+                    this.callbacks.onNotification?.(config.memberId, method, params);
+                }
+            }
+            catch {
+                this.slog("warn", config.memberId, "parse", `invalid JSON: ${trimmed.slice(0, 200)}`);
+            }
+        });
+        // Capture stderr for diagnostics
+        if (child.stderr) {
+            const errRl = createInterface({ input: child.stderr, crlfDelay: Number.POSITIVE_INFINITY });
+            errRl.on("line", (line) => {
+                this.callbacks.log?.debug?.(`[${new Date().toISOString()}] [debug] [agent:${config.memberId}] [stderr] ${line}`);
+            });
+        }
+        // Handle process exit
+        child.on("exit", (code, signal) => {
+            const prev = handle.state;
+            if (prev !== "killed") {
+                handle.state = code === 0 ? "completed" : "failed";
+            }
+            handle.endedAt = Date.now();
+            if (code !== 0 && !handle.error) {
+                handle.error = `Process exited with code ${code} (signal: ${signal})`;
+            }
+            // Reject all pending RPCs
+            for (const [id, pending] of pendingRpc) {
+                clearTimeout(pending.timer);
+                pending.reject(new Error(`Agent process exited (code=${code})`));
+                pendingRpc.delete(id);
+            }
+            this.callbacks.onStateChange?.(config.memberId, handle.state);
+            this.callbacks.onExit?.(config.memberId, code, signal);
+            this.slog("info", config.memberId, "exit", `exited (code=${code}, signal=${signal})`);
+        });
+        child.on("error", (err) => {
+            handle.state = "failed";
+            handle.error = err.message;
+            handle.endedAt = Date.now();
+            this.callbacks.onStateChange?.(config.memberId, "failed");
+            this.slog("warn", config.memberId, "error", err.message);
+        });
+        this.callbacks.onStateChange?.(config.memberId, "starting");
+        // ACP handshake: initialize (declare the qlogicagent extension capability) + register a
+        // session, so the child runs the standard session/prompt path and emits session/update.
+        // thread.turn is retired for the parent→child wire.
+        try {
+            await this.sendRpc(config.memberId, "initialize", {
+                protocolVersion: 1,
+                clientInfo: { name: "qlogicagent-team-leader", version: "1.0.0" },
+                clientCapabilities: { qlogicagent: { version: 1, events: true, methods: true, orchestration: true } },
+            }, 15_000);
+            const childSessionId = randomUUID();
+            // Carry the member's standing context (persona + parent memory) as a
+            // session-level appendSystemPrompt so every turn inherits it. The child's
+            // assembleSystemPrompt already appends config.appendSystemPrompt — no
+            // child-side change needed.
+            const sessionNewParams = { sessionId: childSessionId, cwd: config.cwd };
+            if (config.systemPrompt)
+                sessionNewParams._meta = { appendSystemPrompt: config.systemPrompt };
+            await this.sendRpc(config.memberId, "session/new", sessionNewParams, 15_000);
+            handle.sessionId = childSessionId;
+            // Standing LLM config: same wire any ACP host uses to provision a session.
+            // A standalone child cannot self-provision (no llmrouter directory, empty
+            // registry) — its turns resolve from this explicit session config. Failures
+            // here are config-gate failures and fail the spawn like the handshake.
+            const llmOptions = [
+                ["provider", config.provider],
+                ["model", config.model],
+                ["apiKey", config.apiKey],
+                ["baseUrl", config.baseUrl],
+            ];
+            for (const [option, value] of llmOptions) {
+                if (!value)
+                    continue;
+                await this.sendRpc(config.memberId, "session/set_config_option", { sessionId: childSessionId, option, value }, 15_000);
+            }
+            handle.state = "ready";
+            this.callbacks.onStateChange?.(config.memberId, "ready");
+            this.slog("info", config.memberId, "handshake", `initialized (pid=${handle.pid}, session=${childSessionId})`);
+        }
+        catch (err) {
+            handle.state = "failed";
+            handle.error = `Initialize handshake failed: ${err instanceof Error ? err.message : String(err)}`;
+            handle.endedAt = Date.now();
+            this.callbacks.onStateChange?.(config.memberId, "failed");
+            this.kill(config.memberId);
+            throw new Error(handle.error);
+        }
+        return handle;
+    }
+    /**
+     * Send a task to a child agent via ACP session/prompt.
+     * Returns the JSON-RPC result (content/usage carried on the response).
+     */
+    async sendTask(memberId, prompt, options) {
+        const entry = this.processes.get(memberId);
+        if (!entry)
+            throw new Error(`No agent process: ${memberId}`);
+        // Members are reused across turns by the external-agent pool, so the accumulated result text
+        // from the previous turn must be cleared — otherwise turn N returns turns 1..N concatenated.
+        entry.handle.resultText = "";
+        entry.handle.state = "running";
+        this.callbacks.onStateChange?.(memberId, "running");
+        try {
+            let result;
+            // Route through ACP adapter for external agents
+            if (entry.acpAdapter) {
+                const sessionId = entry.handle.sessionId ?? "default";
+                const response = await entry.acpAdapter.sendPrompt(entry.child, sessionId, prompt, options?.timeout ?? 300_000);
+                // In standard ACP, content is delivered via session/update notifications
+                // during prompt execution. The response only has stopReason + usage.
+                // The resultText is accumulated by the notification handler (turn.delta).
+                const text = entry.handle.resultText ?? "";
+                // Track usage from prompt response
+                if (response.usage && entry.usageTracker) {
+                    entry.usageTracker.onPromptResponseUsage(response.usage);
+                }
+                result = { content: text, stopReason: response.stopReason };
+            }
+            else {
+                // Internal agent: standard ACP session/prompt. Content streams via session/update
+                // (turn.delta) and is accumulated into handle.resultText by captureChildProgress;
+                // the response carries only { stopReason, usage? }. Mirror the external-agent shape
+                // so callers see a uniform { content, stopReason } regardless of transport.
+                const sessionId = options?.sessionId ?? entry.handle.sessionId ?? "default";
+                const r = await this.sendRpc(memberId, "session/prompt", {
+                    sessionId,
+                    prompt: [{ type: "text", text: prompt }],
+                }, options?.timeout ?? 300_000);
+                const text = entry.handle.resultText ?? "";
+                const stopReason = r && typeof r.stopReason === "string" ? r.stopReason : undefined;
+                result = { content: text, stopReason };
+            }
+            entry.handle.state = "completed";
+            entry.handle.endedAt = Date.now();
+            this.callbacks.onStateChange?.(memberId, "completed");
+            return result;
+        }
+        catch (err) {
+            entry.handle.state = "failed";
+            entry.handle.error = err instanceof Error ? err.message : String(err);
+            entry.handle.endedAt = Date.now();
+            this.callbacks.onStateChange?.(memberId, "failed");
+            throw err;
+        }
+    }
+    /** Send a raw JSON-RPC request to a child. */
+    async sendRpc(memberId, method, params, timeoutMs = 30_000) {
+        const entry = this.processes.get(memberId);
+        if (!entry)
+            throw new Error(`No agent process: ${memberId}`);
+        const req = buildRpcRequest(method, params);
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                entry.pendingRpc.delete(req.id);
+                reject(new Error(`RPC timeout: ${method} (${timeoutMs}ms)`));
+            }, timeoutMs);
+            entry.pendingRpc.set(req.id, { resolve, reject, timer });
+            try {
+                entry.child.stdin.write(`${JSON.stringify(req)}\n`);
+            }
+            catch (err) {
+                clearTimeout(timer);
+                entry.pendingRpc.delete(req.id);
+                reject(err instanceof Error ? err : new Error(String(err)));
+            }
+        });
+    }
+    /**
+     * Send a long-running task to a child agent with heartbeat keepalive.
+     *
+     * Unlike `sendTask()` (which blocks for up to 5 minutes), this method:
+     *   1. Dispatches the task via ACP `session/prompt`
+     *   2. Periodically sends `ping` RPCs to detect child liveness
+     *   3. Supports very long execution times (hours/days) for async work
+     *      like video generation, batch processing, etc.
+     *
+     * The child is expected to emit `turn.delta` / `turn.progress`
+     * notifications during long work. If no response to ping within
+     * `pingTimeout`, the task is considered failed.
+     */
+    async sendTaskAsync(memberId, prompt, options) {
+        const entry = this.processes.get(memberId);
+        if (!entry)
+            throw new Error(`No agent process: ${memberId}`);
+        entry.handle.state = "running";
+        this.callbacks.onStateChange?.(memberId, "running");
+        const sessionId = options?.sessionId ?? entry.handle.sessionId ?? "default";
+        const promptParams = {
+            sessionId,
+            prompt: [{ type: "text", text: prompt }],
+        };
+        const pingInterval = options?.pingInterval ?? 60_000;
+        const pingTimeout = options?.pingTimeout ?? 10_000;
+        const totalTimeout = options?.timeout ?? 0;
+        const startedAt = Date.now();
+        // Send the task (no timeout on the RPC itself — we'll manage liveness via ping)
+        const taskRpcTimeout = totalTimeout > 0 ? totalTimeout : 24 * 60 * 60 * 1000; // 24h max
+        const taskPromise = this.sendRpc(memberId, "session/prompt", promptParams, taskRpcTimeout);
+        // Start heartbeat ping loop
+        const pingTimer = setInterval(async () => {
+            // Check total timeout
+            if (totalTimeout > 0 && Date.now() - startedAt > totalTimeout) {
+                clearInterval(pingTimer);
+                entry.handle.state = "failed";
+                entry.handle.error = "Task timed out";
+                entry.handle.endedAt = Date.now();
+                this.callbacks.onStateChange?.(memberId, "failed");
+                return;
+            }
+            try {
+                await this.sendRpc(memberId, "ping", undefined, pingTimeout);
+            }
+            catch {
+                // Ping failed — child may be dead or unresponsive.
+                // Don't immediately kill; the task RPC promise will resolve/reject
+                // when the child process exits.
+                this.slog("warn", entry.handle.memberId, "heartbeat", "ping failed");
+            }
+        }, pingInterval);
+        try {
+            const result = await taskPromise;
+            clearInterval(pingTimer);
+            entry.handle.state = "completed";
+            entry.handle.endedAt = Date.now();
+            // Content was accumulated into handle.resultText from session/update (turn.delta);
+            // the standard ACP response carries only { stopReason, usage? }.
+            this.callbacks.onStateChange?.(memberId, "completed");
+            return result;
+        }
+        catch (err) {
+            clearInterval(pingTimer);
+            entry.handle.state = "failed";
+            entry.handle.error = err instanceof Error ? err.message : String(err);
+            entry.handle.endedAt = Date.now();
+            this.callbacks.onStateChange?.(memberId, "failed");
+            throw err;
+        }
+    }
+    /**
+     * Ping a child agent to check liveness.
+     *
+     * Q-2 protocol alignment:
+     * - Internal agents: JSON-RPC `ping` request (guaranteed to respond).
+     * - ACP agents: Send `notifications/ping` notification, then wait for
+     *   `$/alive` notification back. Falls back to `sendRpc("ping")` if
+     *   `$/alive` is not received (some ACP agents may support RPC ping).
+     */
+    async ping(memberId, timeoutMs = 5_000) {
+        const entry = this.processes.get(memberId);
+        if (!entry)
+            return false;
+        if (entry.acpAdapter) {
+            // ACP path: notification-based liveness check
+            // Send a ping notification (no response expected)
+            try {
+                const msg = JSON.stringify({
+                    jsonrpc: "2.0",
+                    method: "notifications/ping",
+                    params: { timestamp: Date.now() },
+                }) + "\n";
+                entry.child.stdin?.write(msg);
+            }
+            catch {
+                return false;
+            }
+            // Wait for $/alive notification or any activity within timeout
+            const before = entry.handle.lastActivityAt ?? 0;
+            const deadline = Date.now() + timeoutMs;
+            while (Date.now() < deadline) {
+                await new Promise((r) => setTimeout(r, 500));
+                if ((entry.handle.lastActivityAt ?? 0) > before)
+                    return true;
+            }
+            // Fallback: try RPC ping (some agents may respond)
+            try {
+                await this.sendRpc(memberId, "ping", undefined, Math.min(timeoutMs, 3_000));
+                return true;
+            }
+            catch {
+                return false;
+            }
+        }
+        // Internal agent: standard RPC ping
+        try {
+            await this.sendRpc(memberId, "ping", undefined, timeoutMs);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Get the runtime status of a child agent process.
+     * Includes real-time media generation progress if available.
+     */
+    getStatus(memberId) {
+        const entry = this.processes.get(memberId);
+        if (!entry)
+            return null;
+        const { handle } = entry;
+        const alive = handle.state === "starting" || handle.state === "ready" || handle.state === "running";
+        const runningFor = alive ? Date.now() - handle.startedAt : undefined;
+        const idleFor = handle.lastActivityAt && alive
+            ? Math.round((Date.now() - handle.lastActivityAt) / 1000)
+            : undefined;
+        return {
+            alive,
+            state: handle.state,
+            runningFor,
+            resultText: handle.resultText,
+            error: handle.error,
+            mediaProgress: handle.mediaProgress,
+            lastToolCall: handle.lastToolCall,
+            idleFor,
+        };
+    }
+    /**
+     * Auto-capture structured progress from child notifications.
+     * This is the key mechanism that allows the parent to know:
+     *   - Which provider task ID the child is polling (for video/3D/TTS)
+     *   - Real progress percentage
+     *   - What the child is currently doing (which tool, what delta text)
+     */
+    /**
+     * Respond to a request the child agent makes to the parent (host) over ACP —
+     * e.g. session/request_permission. Sub-agents run autonomously under the parent,
+     * so tool-permission requests are auto-approved.
+     */
+    handleChildHostRequest(memberId, msg) {
+        const entry = this.processes.get(memberId);
+        const stdin = entry?.child.stdin;
+        if (!stdin?.writable)
+            return;
+        const reply = (body) => {
+            try {
+                stdin.write(`${JSON.stringify({ jsonrpc: "2.0", id: msg.id, ...body })}\n`);
+            }
+            catch { /* child gone */ }
+        };
+        if (msg.method === "session/request_permission") {
+            reply({ result: { optionId: "allow" } });
+            return;
+        }
+        reply({ error: { code: -32601, message: `Method not found: ${msg.method}` } });
+    }
+    captureChildProgress(memberId, method, params) {
+        const entry = this.processes.get(memberId);
+        if (!entry)
+            return;
+        const { handle } = entry;
+        handle.lastActivityAt = Date.now();
+        switch (method) {
+            case "turn.media_progress": {
+                const p = params;
+                if (p && typeof p.taskId === "string") {
+                    handle.mediaProgress = {
+                        taskId: p.taskId,
+                        mediaType: p.mediaType ?? "unknown",
+                        percent: typeof p.percent === "number" ? p.percent : 0,
+                        status: p.status ?? "unknown",
+                        provider: p.provider,
+                        updatedAt: Date.now(),
+                    };
+                }
+                break;
+            }
+            case "turn.tool_call": {
+                const p = params;
+                if (p && typeof p.name === "string") {
+                    handle.lastToolCall = p.name;
+                }
+                break;
+            }
+            case "turn.delta": {
+                const p = params;
+                if (p && typeof p.text === "string") {
+                    // Keep only last 200 chars for status display
+                    const text = p.text;
+                    handle.resultText = `${handle.resultText ?? ""}${text}`;
+                    handle.lastDelta = text.slice(-200);
+                }
+                break;
+            }
+            case "turn.tool_result": {
+                // Tool completed — clear media progress if it was from a media tool
+                const p = params;
+                if (p && handle.mediaProgress && handle.mediaProgress.percent >= 100) {
+                    handle.mediaProgress = undefined;
+                }
+                break;
+            }
+        }
+    }
+    /**
+     * Spawn an external ACP agent with retry logic.
+     * Retries up to MAX_SPAWN_RETRIES times with exponential backoff.
+     */
+    async spawnAcpAgentWithRetry(config, handle, env) {
+        let lastError = null;
+        for (let attempt = 0; attempt <= MAX_SPAWN_RETRIES; attempt++) {
+            try {
+                // On retry, clean up previous failed attempt
+                if (attempt > 0) {
+                    this.processes.delete(config.memberId);
+                    handle.state = "starting";
+                    handle.error = undefined;
+                    handle.endedAt = undefined;
+                    const backoff = RETRY_BACKOFF_BASE * attempt; // 3s, 6s
+                    this.slog("info", config.memberId, "spawn", `retry ${attempt}/${MAX_SPAWN_RETRIES} after ${backoff}ms`);
+                    await sleep(backoff);
+                }
+                return await this.spawnAcpAgent(config, handle, env);
+            }
+            catch (err) {
+                lastError = err instanceof Error ? err : new Error(String(err));
+                // Non-retryable failures (e.g. the agent needs login) won't heal by retrying — surface
+                // the actionable message immediately instead of spending 3 attempts on it.
+                if (lastError.retryable === false) {
+                    handle.state = "failed";
+                    handle.error = lastError.message;
+                    handle.endedAt = Date.now();
+                    this.callbacks.onStateChange?.(config.memberId, "failed");
+                    throw lastError;
+                }
+                this.slog("warn", config.memberId, "spawn", `attempt ${attempt + 1} failed: ${lastError.message}`);
+            }
+        }
+        // All retries exhausted
+        handle.state = "failed";
+        handle.error = `ACP spawn failed after ${MAX_SPAWN_RETRIES + 1} attempts: ${lastError?.message}`;
+        handle.endedAt = Date.now();
+        this.callbacks.onStateChange?.(config.memberId, "failed");
+        throw new Error(handle.error);
+    }
+    /**
+     * Spawn an external ACP agent process.
+     * Uses the ACP protocol adapter for lifecycle management.
+     */
+    async spawnAcpAgent(config, handle, env) {
+        const log = this.callbacks.log;
+        const ext = config.external;
+        // Merge ACP-specific env
+        if (ext.env)
+            Object.assign(env, ext.env);
+        const acpArgs = [...ext.acpArgs];
+        this.slog("info", config.memberId, "spawn", `spawning ACP ${config.name} via ${ext.cliPath} ${acpArgs.join(" ")}`);
+        const child = spawn(ext.cliPath, acpArgs, {
+            cwd: config.cwd,
+            env,
+            stdio: ["pipe", "pipe", "pipe"],
+            detached: false,
+        });
+        handle.pid = child.pid ?? -1;
+        const pendingRpc = new Map();
+        const acpAdapter = new AcpProtocolAdapter();
+        const usageTracker = new AcpUsageTracker();
+        // ── IPC server for MCP bridge tool calls ──────────────────
+        const { server: ipcServer, pipePath: ipcPath } = this.createMcpIpcServer(config.memberId);
+        env.QLOGICAGENT_PARENT_RPC = ipcPath;
+        // ── Stderr log file ──────────────────────────────────────
+        let stderrStream;
+        if (this.callbacks.sessionDir) {
+            try {
+                mkdirSync(this.callbacks.sessionDir, { recursive: true });
+                stderrStream = createWriteStream(join(this.callbacks.sessionDir, `${config.memberId}.stderr.log`), { flags: "a" });
+            }
+            catch { /* best-effort */ }
+        }
+        // External-agent host handler: serves reverse-RPC (permission auto-allow + fs + terminal),
+        // confined to the agent cwd. Terminals are reaped on detach/kill via disposeAll().
+        const hostHandler = createAcpHostHandler({
+            cwd: config.cwd,
+            requestPermission: this.callbacks.onPermissionRequest
+                ? (params) => this.callbacks.onPermissionRequest(config.memberId, params)
+                : undefined,
+        });
+        this.processes.set(config.memberId, { handle, child, pendingRpc, acpAdapter, usageTracker, ipcServer, ipcPath, stderrStream, hostHandler });
+        // Attach ACP protocol adapter to child stdio
+        acpAdapter.attach(child, (method, params) => {
+            // Track usage from ACP notifications
+            if (method === "usage_update") {
+                usageTracker.onUsageUpdate(params);
+            }
+            // Translate ACP notifications to internal format
+            const translated = AcpProtocolAdapter.translateNotification(method, params);
+            if (translated) {
+                this.captureChildProgress(config.memberId, translated.method, translated.params);
+                this.callbacks.onNotification?.(config.memberId, translated.method, translated.params);
+            }
+            else {
+                // Forward raw for unrecognized notifications
+                this.captureChildProgress(config.memberId, method, params);
+                this.callbacks.onNotification?.(config.memberId, method, params);
+            }
+        }, hostHandler);
+        // Capture stderr for diagnostics + file
+        if (child.stderr) {
+            const errRl = createInterface({ input: child.stderr, crlfDelay: Number.POSITIVE_INFINITY });
+            errRl.on("line", (line) => {
+                this.callbacks.log?.debug?.(`[${new Date().toISOString()}] [debug] [agent:${config.memberId}] [stderr] ${line}`);
+                stderrStream?.write(`${new Date().toISOString()} ${line}\n`);
+            });
+        }
+        // Handle process exit (with runtime restart for RETRIABLE crashes)
+        child.on("exit", (code, signal) => {
+            acpAdapter.detach();
+            hostHandler.disposeAll();
+            const prev = handle.state;
+            // ── Runtime crash auto-restart ────────────────────────
+            if (prev !== "killed" && prev !== "completed" && code !== 0) {
+                const entry = this.processes.get(config.memberId);
+                const restartCount = entry?.runtimeRestartCount ?? 0;
+                if (restartCount < RUNTIME_RESTART_MAX) {
+                    const backoff = RUNTIME_RESTART_BACKOFF_BASE * (2 ** restartCount); // 5s, 10s, 20s
+                    this.slog("warn", config.memberId, "crash", `crashed (code=${code}), restarting ${restartCount + 1}/${RUNTIME_RESTART_MAX} after ${backoff}ms`);
+                    this.callbacks.onNotification?.(config.memberId, "agents.error", {
+                        agentId: config.memberId,
+                        phase: "runtime",
+                        error: `Process crashed (code=${code}, signal=${signal}), restarting`,
+                        retriesLeft: RUNTIME_RESTART_MAX - restartCount - 1,
+                    });
+                    setTimeout(() => {
+                        this.attemptRuntimeRestart(config, env, restartCount + 1).catch((err) => {
+                            this.slog("warn", config.memberId, "restart", `failed: ${err instanceof Error ? err.message : String(err)}`);
+                        });
+                    }, backoff);
+                    return; // Don't mark as failed yet — restart in progress
+                }
+            }
+            if (prev !== "killed") {
+                handle.state = code === 0 ? "completed" : "failed";
+            }
+            handle.endedAt = Date.now();
+            if (code !== 0 && !handle.error) {
+                handle.error = `ACP process exited with code ${code} (signal: ${signal})`;
+            }
+            this.callbacks.onStateChange?.(config.memberId, handle.state);
+            this.callbacks.onExit?.(config.memberId, code, signal);
+            this.slog("info", config.memberId, "exit", `ACP exited (code=${code}, signal=${signal})`);
+        });
+        child.on("error", (err) => {
+            acpAdapter.detach();
+            hostHandler.disposeAll();
+            handle.state = "failed";
+            handle.error = err.message;
+            handle.endedAt = Date.now();
+            this.callbacks.onStateChange?.(config.memberId, "failed");
+            this.callbacks.onNotification?.(config.memberId, "agents.error", {
+                agentId: config.memberId,
+                phase: "spawn",
+                error: err.message,
+                retriesLeft: 0,
+            });
+            this.slog("warn", config.memberId, "error", err.message);
+        });
+        this.callbacks.onStateChange?.(config.memberId, "starting");
+        // Perform ACP initialize handshake
+        try {
+            const initResult = await acpAdapter.initialize(child);
+            handle.state = "ready";
+            handle.supportsResume = initResult.agentCapabilities.loadSession === true;
+            this.callbacks.onStateChange?.(config.memberId, "ready");
+            this.slog("info", config.memberId, "handshake", `ACP initialized (protocol=${initResult.protocolVersion}, loadSession=${handle.supportsResume}, pid=${handle.pid})`);
+            // Create ACP session with MCP servers and system prompt
+            try {
+                const sessionOpts = {
+                    cwd: config.cwd,
+                };
+                // Auto-inject MCP bridge server if we have an IPC path
+                const mcpServers = [...(config.mcpServers ?? [])];
+                const entry = this.processes.get(config.memberId);
+                const mcpCapabilities = initResult.agentCapabilities.mcpCapabilities;
+                const supportsStdioMcp = mcpCapabilities?.stdio === true;
+                if (entry?.ipcPath && supportsStdioMcp) {
+                    mcpServers.push({
+                        name: "qlogicagent-tools",
+                        command: process.execPath,
+                        args: [this.mcpBridgeScriptPath],
+                        env: {
+                            QLOGICAGENT_PARENT_RPC: entry.ipcPath,
+                            QLOGICAGENT_SESSION_ID: config.memberId,
+                        },
+                    });
+                }
+                if (mcpServers.length > 0)
+                    sessionOpts.mcpServers = mcpServers;
+                if (config.systemPrompt)
+                    sessionOpts.systemPrompt = config.systemPrompt;
+                const sessionResult = await acpAdapter.createSession(child, sessionOpts);
+                handle.sessionId = sessionResult.sessionId;
+                this.slog("info", config.memberId, "session", `session created (id=${sessionResult.sessionId})`);
+            }
+            catch (err) {
+                // Session creation is FATAL: ACP requires a session before any prompt. Swallowing it let
+                // the turn run with a bogus "default" sessionId, so the agent rejected the prompt with a
+                // misleading "Invalid params" — hiding the real cause, commonly an auth/config gate. Two
+                // patterns: (1) the agent rejects session/new with an auth error directly (kimi: -32000 +
+                // authMethods); (2) it advertises authMethods at *initialize* then fails session/new
+                // generically (hermes: "hermes-setup" + -32603 "No LLM provider configured"). Both are
+                // non-retryable — asAuthRequiredError(err, initAuthMethods) surfaces the actionable
+                // message + authMethods (retryable=false) so the spawn layer stops, instead of burning
+                // 3 retries / hiding the cause.
+                const e = err instanceof Error ? err : new Error(String(err));
+                const initAuthMethods = (initResult.authMethods ?? []);
+                const authErr = asAuthRequiredError(e, initAuthMethods);
+                this.slog("warn", config.memberId, "session", `session creation failed: ${(authErr ?? e).message}`);
+                throw authErr ?? e;
+            }
+            // Start heartbeat monitoring for external ACP agents
+            this.startHeartbeat(config.memberId, (hungId) => {
+                this.slog("warn", hungId, "heartbeat", "hang detected — force-killing");
+                this.callbacks.onNotification?.(hungId, "agents.error", {
+                    agentId: hungId,
+                    phase: "heartbeat",
+                    error: `Agent ${config.name} stopped responding (${AgentProcessManager.MAX_MISSED_BEATS} missed heartbeats)`,
+                    retriesLeft: 0,
+                });
+                this.kill(hungId);
+            });
+        }
+        catch (err) {
+            const e = err instanceof Error ? err : new Error(String(err));
+            // Auth-required (and other non-retryable) failures carry retryable=false + a ready-to-show
+            // message ("Authentication required. Run `kimi login` …"); don't bury those under the
+            // generic "ACP handshake failed" prefix, and forward the agent's authMethods to the UI.
+            const nonRetryable = e.retryable === false;
+            const authMethods = e.authMethods;
+            handle.state = "failed";
+            handle.error = nonRetryable ? e.message : `ACP handshake failed: ${e.message}`;
+            handle.endedAt = Date.now();
+            acpAdapter.detach();
+            hostHandler.disposeAll();
+            this.callbacks.onStateChange?.(config.memberId, "failed");
+            this.callbacks.onNotification?.(config.memberId, "agents.error", {
+                agentId: config.memberId,
+                phase: "handshake",
+                error: handle.error,
+                retriesLeft: 0,
+                ...(authMethods ? { authMethods } : {}),
+            });
+            this.kill(config.memberId);
+            throw e;
+        }
+        return handle;
+    }
+    /** Kill a specific child agent process. */
+    kill(memberId) {
+        const entry = this.processes.get(memberId);
+        if (!entry)
+            return;
+        this.stopHeartbeat(memberId);
+        entry.handle.state = "killed";
+        entry.handle.endedAt = Date.now();
+        entry.acpAdapter?.detach();
+        entry.hostHandler?.disposeAll();
+        // Close IPC server & stderr stream
+        try {
+            entry.ipcServer?.close();
+        }
+        catch { /* ignore */ }
+        try {
+            entry.stderrStream?.end();
+        }
+        catch { /* ignore */ }
+        // Reap the WHOLE process tree, not just the direct child — external CLIs like kimi-cli
+        // (a Python launcher) spawn grandchildren that child.kill() would orphan on Windows.
+        killProcessTree(entry.child, entry.handle.pid);
+        this.callbacks.onStateChange?.(memberId, "killed");
+        this.slog("info", memberId, "kill", `killed (pid=${entry.handle.pid})`);
+    }
+    /** Kill all child processes and clean up. */
+    killAll() {
+        for (const memberId of this.processes.keys()) {
+            this.kill(memberId);
+        }
+    }
+    /** Get the handle for a specific member. */
+    getHandle(memberId) {
+        return this.processes.get(memberId)?.handle;
+    }
+    /** Get all handles. */
+    getAllHandles() {
+        return [...this.processes.values()].map(p => p.handle);
+    }
+    /** Whether a member's process is still spawned and usable (for pool reuse across turns). */
+    isAlive(memberId) {
+        const entry = this.processes.get(memberId);
+        if (!entry)
+            return false;
+        if (entry.child.killed || entry.child.exitCode !== null)
+            return false;
+        return entry.handle.state !== "killed" && entry.handle.state !== "failed";
+    }
+    /** Get usage tracker for an ACP agent (returns null for internal agents). */
+    getUsageTracker(memberId) {
+        return this.processes.get(memberId)?.usageTracker ?? null;
+    }
+    // ── MCP IPC Server ────────────────────────────────────────
+    /**
+     * Create a named-pipe IPC server for MCP bridge tool-call proxying.
+     * External agents' MCP bridge servers connect here to proxy tool calls
+     * back to qlogicagent.
+     */
+    createMcpIpcServer(memberId) {
+        const slug = memberId.replace(/[^a-zA-Z0-9-]/g, "-");
+        const pipePath = process.platform === "win32"
+            ? `\\\\.\\pipe\\qlogicagent-mcp-${slug}-${Date.now()}`
+            : join(tmpdir(), `qlogicagent-mcp-${slug}-${Date.now()}.sock`);
+        const server = createServer((socket) => {
+            let buffer = "";
+            socket.on("data", (chunk) => {
+                buffer += chunk.toString();
+                let nl;
+                while ((nl = buffer.indexOf("\n")) !== -1) {
+                    const line = buffer.slice(0, nl).trim();
+                    buffer = buffer.slice(nl + 1);
+                    if (!line)
+                        continue;
+                    this.handleMcpIpcMessage(memberId, line, socket);
+                }
+            });
+        });
+        server.listen(pipePath);
+        server.on("error", (err) => {
+            this.slog("warn", memberId, "mcp-ipc", `server error: ${err.message}`);
+        });
+        return { server, pipePath };
+    }
+    /** Handle a single JSON-RPC message from the MCP bridge IPC connection. */
+    handleMcpIpcMessage(memberId, line, socket) {
+        let msg;
+        try {
+            msg = JSON.parse(line);
+        }
+        catch {
+            return; // ignore malformed
+        }
+        if (msg.method === "mcp.toolCall" && msg.id !== undefined) {
+            const tool = typeof msg.params?.tool === "string" ? msg.params.tool : "";
+            const args = msg.params?.arguments ?? {};
+            if (!this.callbacks.onMcpToolCall) {
+                const resp = JSON.stringify({ jsonrpc: "2.0", id: msg.id, error: { code: -32601, message: "No onMcpToolCall handler" } }) + "\n";
+                try {
+                    socket.write(resp);
+                }
+                catch { /* socket gone */ }
+                return;
+            }
+            this.callbacks.onMcpToolCall(memberId, tool, args)
+                .then((result) => {
+                const resp = JSON.stringify({ jsonrpc: "2.0", id: msg.id, result }) + "\n";
+                try {
+                    socket.write(resp);
+                }
+                catch { /* socket gone */ }
+            })
+                .catch((err) => {
+                const resp = JSON.stringify({
+                    jsonrpc: "2.0",
+                    id: msg.id,
+                    error: { code: -32603, message: err instanceof Error ? err.message : String(err) },
+                }) + "\n";
+                try {
+                    socket.write(resp);
+                }
+                catch { /* socket gone */ }
+            });
+        }
+        else if (msg.id !== undefined) {
+            // Unknown method
+            const resp = JSON.stringify({ jsonrpc: "2.0", id: msg.id, error: { code: -32601, message: `Unknown IPC method: ${msg.method}` } }) + "\n";
+            try {
+                socket.write(resp);
+            }
+            catch { /* socket gone */ }
+        }
+    }
+    // ── Runtime Crash Restart ─────────────────────────────────
+    /**
+     * Attempt to restart a crashed ACP agent.
+     * Re-spawns the child process prepping the same config and env,
+     * then re-runs ACP handshake.
+     */
+    async attemptRuntimeRestart(config, env, restartCount) {
+        const log = this.callbacks.log;
+        const existing = this.processes.get(config.memberId);
+        // Clean up old entry but preserve IPC server & stderr stream
+        const ipcServer = existing?.ipcServer;
+        const ipcPath = existing?.ipcPath;
+        const stderrStream = existing?.stderrStream;
+        this.processes.delete(config.memberId);
+        try {
+            const handle = {
+                memberId: config.memberId,
+                name: config.name,
+                pid: -1,
+                cwd: config.cwd,
+                state: "starting",
+                startedAt: Date.now(),
+            };
+            const ext = config.external;
+            const acpArgs = [...ext.acpArgs];
+            // Ensure IPC path is set for MCP bridge
+            if (ipcPath)
+                env.QLOGICAGENT_PARENT_RPC = ipcPath;
+            const child = spawn(ext.cliPath, acpArgs, {
+                cwd: config.cwd,
+                env,
+                stdio: ["pipe", "pipe", "pipe"],
+                detached: false,
+            });
+            handle.pid = child.pid ?? -1;
+            const pendingRpc = new Map();
+            const acpAdapter = new AcpProtocolAdapter();
+            const usageTracker = new AcpUsageTracker();
+            const hostHandler = createAcpHostHandler({
+                cwd: config.cwd,
+                requestPermission: this.callbacks.onPermissionRequest
+                    ? (params) => this.callbacks.onPermissionRequest(config.memberId, params)
+                    : undefined,
+            });
+            this.processes.set(config.memberId, {
+                handle, child, pendingRpc, acpAdapter, usageTracker,
+                ipcServer, ipcPath, stderrStream, hostHandler,
+                runtimeRestartCount: restartCount,
+            });
+            // Re-attach ACP adapter
+            acpAdapter.attach(child, (method, params) => {
+                if (method === "usage_update") {
+                    usageTracker.onUsageUpdate(params);
+                }
+                const translated = AcpProtocolAdapter.translateNotification(method, params);
+                if (translated) {
+                    this.captureChildProgress(config.memberId, translated.method, translated.params);
+                    this.callbacks.onNotification?.(config.memberId, translated.method, translated.params);
+                }
+                else {
+                    this.captureChildProgress(config.memberId, method, params);
+                    this.callbacks.onNotification?.(config.memberId, method, params);
+                }
+            }, hostHandler);
+            if (child.stderr) {
+                const errRl = createInterface({ input: child.stderr, crlfDelay: Number.POSITIVE_INFINITY });
+                errRl.on("line", (line) => {
+                    this.callbacks.log?.debug?.(`[${new Date().toISOString()}] [debug] [agent:${config.memberId}] [stderr] ${line}`);
+                    stderrStream?.write(`${new Date().toISOString()} ${line}\n`);
+                });
+            }
+            // Re-wire exit handler (recursive for further restarts)
+            child.on("exit", (code, signal) => {
+                acpAdapter.detach();
+                hostHandler.disposeAll();
+                const prev = handle.state;
+                if (prev !== "killed" && prev !== "completed" && code !== 0) {
+                    const entry = this.processes.get(config.memberId);
+                    const rc = entry?.runtimeRestartCount ?? restartCount;
+                    if (rc < RUNTIME_RESTART_MAX) {
+                        const backoff = RUNTIME_RESTART_BACKOFF_BASE * (2 ** rc);
+                        this.slog("warn", config.memberId, "crash", `crashed again (code=${code}), restart ${rc + 1}/${RUNTIME_RESTART_MAX}`);
+                        this.callbacks.onNotification?.(config.memberId, "agents.error", {
+                            agentId: config.memberId,
+                            phase: "runtime",
+                            error: `Process crashed (code=${code}), restarting`,
+                            retriesLeft: RUNTIME_RESTART_MAX - rc - 1,
+                        });
+                        setTimeout(() => {
+                            this.attemptRuntimeRestart(config, env, rc + 1).catch((err) => {
+                                this.slog("warn", config.memberId, "restart", `failed: ${err instanceof Error ? err.message : String(err)}`);
+                            });
+                        }, backoff);
+                        return;
+                    }
+                }
+                if (prev !== "killed") {
+                    handle.state = code === 0 ? "completed" : "failed";
+                }
+                handle.endedAt = Date.now();
+                if (code !== 0 && !handle.error) {
+                    handle.error = `ACP process exited with code ${code} (signal: ${signal})`;
+                }
+                this.callbacks.onStateChange?.(config.memberId, handle.state);
+                this.callbacks.onExit?.(config.memberId, code, signal);
+            });
+            child.on("error", (err) => {
+                acpAdapter.detach();
+                hostHandler.disposeAll();
+                handle.state = "failed";
+                handle.error = err.message;
+                handle.endedAt = Date.now();
+                this.callbacks.onStateChange?.(config.memberId, "failed");
+            });
+            this.callbacks.onStateChange?.(config.memberId, "starting");
+            // Re-handshake
+            const initResult = await acpAdapter.initialize(child);
+            handle.state = "ready";
+            handle.supportsResume = initResult.agentCapabilities.loadSession === true;
+            this.callbacks.onStateChange?.(config.memberId, "ready");
+            this.slog("info", config.memberId, "restart", `ACP restarted (attempt=${restartCount}, protocol=${initResult.protocolVersion}, loadSession=${handle.supportsResume}, pid=${handle.pid})`);
+            // Build MCP server list for session creation
+            const mcpServers = [...(config.mcpServers ?? [])];
+            if (ipcPath) {
+                mcpServers.push({
+                    name: "qlogicagent-tools",
+                    command: process.execPath,
+                    args: [this.mcpBridgeScriptPath],
+                    env: { QLOGICAGENT_PARENT_RPC: ipcPath, QLOGICAGENT_SESSION_ID: config.memberId },
+                });
+            }
+            // D-1: Try session/resume if the agent supports it and we have a previous session
+            try {
+                if (handle.supportsResume && handle.sessionId) {
+                    const resumeResult = await acpAdapter.resumeSession(child, handle.sessionId, {
+                        cwd: config.cwd,
+                        mcpServers: mcpServers.length > 0 ? mcpServers : undefined,
+                    });
+                    handle.sessionId = resumeResult.sessionId;
+                    this.slog("info", config.memberId, "session", `session resumed (id=${handle.sessionId})`);
+                }
+                else {
+                    // Fallback: create new session (optionally with summary)
+                    const sessionOpts = {
+                        cwd: config.cwd,
+                    };
+                    if (mcpServers.length > 0)
+                        sessionOpts.mcpServers = mcpServers;
+                    if (config.systemPrompt)
+                        sessionOpts.systemPrompt = config.systemPrompt;
+                    const sessionResult = await acpAdapter.createSession(child, sessionOpts);
+                    handle.sessionId = sessionResult.sessionId;
+                    this.slog("info", config.memberId, "session", `new session on restart (id=${handle.sessionId})`);
+                }
+            }
+            catch {
+                this.slog("warn", config.memberId, "session", "session re-creation failed on restart");
+            }
+            this.startHeartbeat(config.memberId, (hungId) => {
+                this.slog("warn", hungId, "heartbeat", "hang detected — force-killing");
+                this.callbacks.onNotification?.(hungId, "agents.error", {
+                    agentId: hungId,
+                    phase: "heartbeat",
+                    error: `Agent ${config.name} stopped responding`,
+                    retriesLeft: 0,
+                });
+                this.kill(hungId);
+            });
+        }
+        catch (err) {
+            // Restart failed — mark as terminal failure
+            const entry = this.processes.get(config.memberId);
+            if (entry) {
+                entry.handle.state = "failed";
+                entry.handle.error = `Runtime restart failed: ${err instanceof Error ? err.message : String(err)}`;
+                entry.handle.endedAt = Date.now();
+            }
+            this.callbacks.onStateChange?.(config.memberId, "failed");
+            this.callbacks.onNotification?.(config.memberId, "agents.error", {
+                agentId: config.memberId,
+                phase: "runtime",
+                error: `Restart failed after ${restartCount} attempts: ${err instanceof Error ? err.message : String(err)}`,
+                retriesLeft: 0,
+            });
+        }
+    }
+    /** Get IPC pipe path for a member's MCP bridge. */
+    getMcpIpcPath(memberId) {
+        return this.processes.get(memberId)?.ipcPath;
+    }
+    // ── Heartbeat & Hang Detection ────────────────────────────
+    heartbeatTimers = new Map();
+    missedBeats = new Map();
+    /** Heartbeat interval (ms). */
+    static HEARTBEAT_INTERVAL = 30_000;
+    /** Number of missed heartbeats before force-kill. */
+    static MAX_MISSED_BEATS = 3;
+    /**
+     * Start heartbeat monitoring for a running agent.
+     * Sends periodic ping RPCs; after MAX_MISSED_BEATS consecutive failures,
+     * the agent is force-killed and marked as "hang".
+     */
+    startHeartbeat(memberId, onHang) {
+        this.stopHeartbeat(memberId);
+        this.missedBeats.set(memberId, 0);
+        const timer = setInterval(async () => {
+            const entry = this.processes.get(memberId);
+            if (!entry || entry.handle.state === "completed" || entry.handle.state === "failed" || entry.handle.state === "killed") {
+                this.stopHeartbeat(memberId);
+                return;
+            }
+            const alive = await this.ping(memberId, 10_000);
+            if (alive) {
+                this.missedBeats.set(memberId, 0);
+                return;
+            }
+            const missed = (this.missedBeats.get(memberId) ?? 0) + 1;
+            this.missedBeats.set(memberId, missed);
+            this.slog("warn", memberId, "heartbeat", `missed (${missed}/${AgentProcessManager.MAX_MISSED_BEATS})`);
+            if (missed >= AgentProcessManager.MAX_MISSED_BEATS) {
+                this.slog("warn", memberId, "heartbeat", "hang detected, force-killing");
+                this.stopHeartbeat(memberId);
+                entry.handle.error = `Hang detected: ${missed} consecutive heartbeat failures`;
+                this.kill(memberId);
+                onHang?.(memberId);
+            }
+        }, AgentProcessManager.HEARTBEAT_INTERVAL);
+        this.heartbeatTimers.set(memberId, timer);
+    }
+    /** Stop heartbeat monitoring for an agent. */
+    stopHeartbeat(memberId) {
+        const timer = this.heartbeatTimers.get(memberId);
+        if (timer) {
+            clearInterval(timer);
+            this.heartbeatTimers.delete(memberId);
+        }
+        this.missedBeats.delete(memberId);
+    }
+    /** Get missed heartbeat count for an agent. */
+    getMissedBeats(memberId) {
+        return this.missedBeats.get(memberId) ?? 0;
+    }
+    /** Get count of active (non-terminal) processes. */
+    activeCount() {
+        return [...this.processes.values()].filter(p => p.handle.state === "starting" || p.handle.state === "ready" || p.handle.state === "running").length;
+    }
+    /** Remove a terminated process from tracking. */
+    remove(memberId) {
+        const entry = this.processes.get(memberId);
+        if (!entry)
+            return;
+        this.stopHeartbeat(memberId);
+        if (entry.handle.state === "running" || entry.handle.state === "starting" || entry.handle.state === "ready") {
+            this.kill(memberId);
+        }
+        this.processes.delete(memberId);
+    }
+    /** Clean up all processes. */
+    dispose() {
+        for (const memberId of this.heartbeatTimers.keys()) {
+            this.stopHeartbeat(memberId);
+        }
+        // Close all IPC servers and stderr streams before killing
+        for (const entry of this.processes.values()) {
+            try {
+                entry.ipcServer?.close();
+            }
+            catch { /* ignore */ }
+            try {
+                entry.stderrStream?.end();
+            }
+            catch { /* ignore */ }
+        }
+        this.killAll();
+        this.processes.clear();
+    }
+}