@methodts/runtime 0.1.0

package/dist/sessions/pool.js

@@ -0,0 +1,991 @@
+// SPDX-License-Identifier: Apache-2.0
+import { randomUUID } from 'node:crypto';
+import { execSync } from 'node:child_process';
+import { join, resolve } from 'node:path';
+import { createPrintSession } from './print-session.js';
+import { createCognitiveSession } from './cognitive-provider.js';
+import { createRuntimeToolProvider } from './runtime-tools.js';
+import { createSessionChannels } from './channels.js';
+import { installScopeHook } from './scope-hook.js';
+import { createAgentEventAdapter } from '../event-bus/agent-event-adapter.js';
+import { CognitiveEventBusSink as CognitiveSink } from './cognitive-sink.js';
+const DEFAULT_MAX_SESSIONS = 10;
+const DEFAULT_MAX_DEPTH = 3;
+const DEFAULT_MAX_AGENTS = 10;
+const DEFAULT_STALE_TIMEOUT_MS = 30 * 60 * 1000; // 30 minutes
+const DEFAULT_KILL_TIMEOUT_MS = 60 * 60 * 1000; // 60 minutes
+const WORKTREE_DIR = '.claude/worktrees';
+// PRD 007: Fallback nickname word list
+const NICKNAME_WORDS = [
+    'alpha', 'bravo', 'cedar', 'drift', 'ember', 'flux', 'grain', 'haze',
+    'iris', 'jade', 'kite', 'lumen', 'mist', 'nova', 'opal', 'prism',
+    'quartz', 'ridge', 'spark', 'tide', 'umbra', 'vale', 'wave', 'xenon',
+    'yield', 'zinc',
+];
+// PRD 007: Method short names for methodology-derived nicknames
+const METHOD_SHORT_NAMES = {
+    'M1-COUNCIL': 'council',
+    'M1-IMPL': 'impl',
+    'M1-PLAN': 'plan',
+    'M1-REVIEW': 'review',
+    'M1-MDES': 'mdes',
+    'M2-ORCH': 'orch',
+    'M3-TMP': 'tmp',
+};
+/**
+ * Create a session pool that manages multiple Claude Code PTY sessions.
+ *
+ * The pool enforces a maximum session count and provides a uniform interface
+ * for creating, prompting, inspecting, and killing sessions.
+ *
+ * PRD 006: Sessions now track parent-child chains with budget enforcement.
+ */
+export function createPool(options) {
+    const maxSessions = options?.maxSessions ?? DEFAULT_MAX_SESSIONS;
+    const fsProvider = options?.fsProvider;
+    const eventBus = options?.eventBus;
+    const cognitiveSink = options?.cognitiveSink;
+    const sessions = new Map();
+    const sessionMetadata = new Map();
+    const sessionWorkdirs = new Map();
+    const sessionChains = new Map();
+    const sessionChannels = new Map();
+    const sessionWorktrees = new Map();
+    const sessionStaleConfigs = new Map();
+    const sessionStaleFlags = new Map();
+    const sessionNicknames = new Map(); // sessionId → nickname
+    const sessionPurposes = new Map(); // sessionId → purpose
+    const activeNicknames = new Set(); // uniqueness guard
+    // PRD 010: Original workdir per session (pre-worktree) for retro placement
+    const sessionOriginalWorkdirs = new Map();
+    // PRD 012: Per-session diagnostics trackers
+    const sessionDiagnostics = new Map();
+    // PRD 012 Phase 4: Session mode tracking
+    const sessionModes = new Map();
+    // PRD 033: Cognitive SSE sink registration — allows promptStream to receive cognitive events
+    const cognitiveSSESinks = new Map();
+    // OBS-19: Waiting-for-sub-agent state (set externally; PTY auto-detection removed in PRD 028 C-4)
+    const sessionWaitingFor = new Map(); // sessionId → what it's waiting for
+    // Pool-level counters
+    let totalSpawned = 0;
+    const startedAt = new Date();
+    let nicknameWordIndex = 0;
+    const methodNicknameCounts = new Map(); // method-short → next sequence
+    /**
+     * PRD 007: Generate a unique nickname for a session.
+     * Priority: explicit > methodology-derived > fallback word list.
+     */
+    function generateNickname(explicit, metadata) {
+        // 1. Explicit nickname — use if unique
+        if (explicit) {
+            const candidate = explicit.toLowerCase().replace(/[^a-z0-9-]/g, '');
+            if (candidate && !activeNicknames.has(candidate)) {
+                return candidate;
+            }
+            // If collision, append sequence number
+            for (let i = 2; i < 100; i++) {
+                const suffixed = `${candidate}-${i}`;
+                if (!activeNicknames.has(suffixed))
+                    return suffixed;
+            }
+        }
+        // 2. Methodology-derived: if metadata has methodology_session_id, try to extract method
+        if (metadata?.methodology_session_id) {
+            const msid = String(metadata.methodology_session_id);
+            // Try to match known method patterns
+            for (const [methodId, shortName] of Object.entries(METHOD_SHORT_NAMES)) {
+                if (msid.includes(methodId) || msid.toLowerCase().includes(shortName)) {
+                    const count = (methodNicknameCounts.get(shortName) ?? 0) + 1;
+                    methodNicknameCounts.set(shortName, count);
+                    const candidate = `${shortName}-${count}`;
+                    if (!activeNicknames.has(candidate))
+                        return candidate;
+                }
+            }
+        }
+        // 3. Fallback word list
+        for (let attempts = 0; attempts < NICKNAME_WORDS.length; attempts++) {
+            const candidate = NICKNAME_WORDS[nicknameWordIndex % NICKNAME_WORDS.length];
+            nicknameWordIndex++;
+            if (!activeNicknames.has(candidate))
+                return candidate;
+        }
+        // Last resort: word + counter
+        const base = NICKNAME_WORDS[nicknameWordIndex % NICKNAME_WORDS.length];
+        nicknameWordIndex++;
+        for (let i = 2; i < 100; i++) {
+            const candidate = `${base}-${i}`;
+            if (!activeNicknames.has(candidate))
+                return candidate;
+        }
+        // Absolute fallback
+        return `agent-${totalSpawned + 1}`;
+    }
+    function getChain(sessionId) {
+        return sessionChains.get(sessionId) ?? {
+            parent_session_id: null,
+            depth: 0,
+            children: [],
+            budget: { max_depth: DEFAULT_MAX_DEPTH, max_agents: DEFAULT_MAX_AGENTS, agents_spawned: 0 },
+        };
+    }
+    /**
+     * Find the root session of a chain and return its shared budget reference.
+     * Budget is tracked at the root — all agents in a chain share the same budget.
+     */
+    function getRootBudget(sessionId) {
+        const chain = sessionChains.get(sessionId);
+        if (!chain)
+            return null;
+        // Walk up to root
+        let currentId = sessionId;
+        let current = chain;
+        while (current.parent_session_id) {
+            const parent = sessionChains.get(current.parent_session_id);
+            if (!parent)
+                break;
+            currentId = current.parent_session_id;
+            current = parent;
+        }
+        return current.budget;
+    }
+    /**
+     * PRD 010: Handle session death — previously detached PTY watcher and generated auto-retro.
+     * PTY watcher removed in PRD 028 C-4. Function retained for call-site symmetry.
+     */
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    function handleSessionDeath(_sessionId, _reason) {
+        // PTY watcher removed in PRD 028 C-4. Auto-retro via watcher observations no longer applies.
+        // Future: print-mode retro generation can be added here if needed.
+    }
+    // ── LLM provider resolution for cognitive-agent mode ────────
+    async function resolveProvider(providerName, config) {
+        switch (providerName ?? 'anthropic') {
+            case 'anthropic': {
+                const { anthropicProvider } = await import('@methodts/pacta-provider-anthropic');
+                return anthropicProvider({ model: config.model, toolProvider: config.toolProvider });
+            }
+            case 'ollama': {
+                const { ollamaProvider } = await import('@methodts/pacta-provider-ollama');
+                const provider = ollamaProvider({
+                    baseUrl: config.baseUrl ?? process.env.OLLAMA_BASE_URL ?? 'http://chobits:11434',
+                    model: config.model,
+                });
+                await provider.init();
+                return provider;
+            }
+            default:
+                throw new Error(`Unknown LLM provider: ${providerName}`);
+        }
+    }
+    return {
+        async create({ workdir, initialPrompt, spawnArgs, metadata, parentSessionId, depth, budget, isolation, timeout_ms, nickname, purpose, persistent, spawn_delay_ms, mode, allowed_paths, scope_mode, session_id, provider_type, cognitive_config, cognitive_patterns, llm_provider, llm_config, experiment_id, run_id }) {
+            // Count active (non-dead) sessions toward the limit
+            const activeSessions = [...sessions.values()].filter((s) => s.status !== 'dead').length;
+            if (activeSessions >= maxSessions) {
+                throw new Error(`Session pool full — maximum ${maxSessions} active sessions`);
+            }
+            // Determine chain properties
+            const effectiveDepth = depth ?? 0;
+            const effectiveBudget = {
+                max_depth: budget?.max_depth ?? DEFAULT_MAX_DEPTH,
+                max_agents: budget?.max_agents ?? DEFAULT_MAX_AGENTS,
+                agents_spawned: budget?.agents_spawned ?? 0,
+            };
+            // If this is a child session, inherit and validate budget from parent
+            if (parentSessionId) {
+                const parentChain = sessionChains.get(parentSessionId);
+                if (parentChain) {
+                    // Use parent's budget as the source of truth (shared budget across chain)
+                    const rootBudget = getRootBudget(parentSessionId) ?? parentChain.budget;
+                    // Depth check
+                    if (effectiveDepth >= rootBudget.max_depth) {
+                        throw new Error(JSON.stringify({
+                            error: 'DEPTH_EXCEEDED',
+                            message: `Depth limit exceeded: depth ${effectiveDepth} >= max_depth ${rootBudget.max_depth}. Cannot spawn deeper.`,
+                            budget: rootBudget,
+                        }));
+                    }
+                    // Agent count check
+                    if (rootBudget.agents_spawned >= rootBudget.max_agents) {
+                        throw new Error(JSON.stringify({
+                            error: 'BUDGET_EXHAUSTED',
+                            message: `Agent budget exceeded: ${rootBudget.agents_spawned}/${rootBudget.max_agents} agents spawned. Increase budget or complete existing work.`,
+                            budget: rootBudget,
+                        }));
+                    }
+                    // Increment the root budget's agent count
+                    rootBudget.agents_spawned++;
+                    // Copy current root budget values for the child
+                    effectiveBudget.max_depth = rootBudget.max_depth;
+                    effectiveBudget.max_agents = rootBudget.max_agents;
+                    effectiveBudget.agents_spawned = rootBudget.agents_spawned;
+                }
+            }
+            const sessionId = session_id ?? randomUUID();
+            // PRD 007: Generate and register nickname
+            const assignedNickname = generateNickname(nickname, metadata);
+            activeNicknames.add(assignedNickname);
+            // PRD 006 Component 2: Worktree isolation
+            const effectiveIsolation = isolation ?? 'shared';
+            let worktreePath = null;
+            let worktreeBranch = null;
+            let effectiveWorkdir = workdir;
+            if (effectiveIsolation === 'worktree') {
+                worktreeBranch = `worktree-${sessionId.substring(0, 8)}`;
+                const worktreeRelDir = join(WORKTREE_DIR, sessionId.substring(0, 8));
+                worktreePath = resolve(workdir, worktreeRelDir);
+                try {
+                    execSync(`git worktree add "${worktreeRelDir}" -b "${worktreeBranch}"`, { cwd: workdir, stdio: 'pipe' });
+                    effectiveWorkdir = worktreePath;
+                }
+                catch (e) {
+                    throw new Error(`Worktree creation failed: ${e.message}`);
+                }
+            }
+            const worktreeInfo = {
+                isolation: effectiveIsolation,
+                worktree_path: worktreePath,
+                worktree_branch: worktreeBranch,
+                metals_available: effectiveIsolation !== 'worktree',
+            };
+            // PRD 014: Scope enforcement — determine effective mode and install hook
+            const effectiveAllowedPaths = allowed_paths ?? [];
+            const envScopeDefault = process.env.SCOPE_ENFORCEMENT_DEFAULT;
+            const validatedEnvDefault = (envScopeDefault === 'enforce' || envScopeDefault === 'warn') ? envScopeDefault : 'enforce';
+            let effectiveScopeMode = scope_mode ?? validatedEnvDefault;
+            if (effectiveAllowedPaths.length > 0) {
+                if (effectiveIsolation !== 'worktree' && effectiveScopeMode === 'enforce') {
+                    // PRD 014: Worktree fallback — can't install hook in shared mode
+                    console.warn(`[PRD 014] allowed_paths provided without worktree isolation — falling back to mode 'warn'. Pre-commit hook requires isolation: 'worktree'.`);
+                    effectiveScopeMode = 'warn';
+                }
+                if (effectiveScopeMode === 'enforce' && worktreePath) {
+                    // Install pre-commit hook in the worktree
+                    const hookResult = installScopeHook(worktreePath, sessionId, effectiveAllowedPaths);
+                    if (hookResult.error) {
+                        console.warn(`[PRD 014] Scope hook installation warning: ${hookResult.error}`);
+                    }
+                }
+                // Store scope constraint in metadata for PTY watcher (Phase 2)
+                const existingMetadata = metadata ?? {};
+                metadata = {
+                    ...existingMetadata,
+                    allowed_paths: effectiveAllowedPaths,
+                    scope_mode: effectiveScopeMode,
+                };
+            }
+            // PRD 006 Component 4: Stale detection config
+            // PRD 011: persistent sessions skip stale detection entirely
+            const staleConfig = persistent ? null : {
+                stale_timeout_ms: timeout_ms ?? DEFAULT_STALE_TIMEOUT_MS,
+                kill_timeout_ms: (timeout_ms ? timeout_ms * 2 : DEFAULT_KILL_TIMEOUT_MS),
+            };
+            // PRD 033: Determine session mode from provider_type (default: print)
+            const effectiveMode = provider_type === 'cognitive-agent' ? 'cognitive-agent' : 'print';
+            // PRD 012: Staggered spawn — delay before spawning process
+            if (spawn_delay_ms && spawn_delay_ms > 0) {
+                await new Promise(r => setTimeout(r, spawn_delay_ms));
+            }
+            let session;
+            // PRD-057 / S2 §6 / C5: if a SessionProviderFactory was supplied at pool
+            // construction, delegate the "how does a prompt actually execute" part
+            // to the factory. Otherwise fall back to the built-in print + cognitive
+            // paths. Both paths set up the cognitive SSE sink in the same way when
+            // applicable so `promptStream` behavior is identical.
+            if (options?.providerFactory) {
+                let sseSink = null;
+                if (effectiveMode === 'cognitive-agent') {
+                    cognitiveSSESinks.set(sessionId, (cb) => { sseSink = cb; });
+                }
+                const sessionCognitiveSink = (effectiveMode === 'cognitive-agent' && experiment_id && run_id && eventBus)
+                    ? new CognitiveSink(eventBus, { sessionId, experimentId: experiment_id, runId: run_id })
+                    : cognitiveSink;
+                const factoryOptions = {
+                    sessionId,
+                    mode: effectiveMode,
+                    workdir: effectiveWorkdir,
+                    allowedTools: spawnArgs,
+                    allowedPaths: effectiveAllowedPaths,
+                    metadata,
+                    onEvent: (event) => {
+                        // Forward to active SSE stream (if any) and emit cognitive
+                        // events onto the bus for PRD 041 experiment tracing.
+                        sseSink?.(event);
+                        if (eventBus && effectiveMode === 'cognitive-agent') {
+                            eventBus.emit({
+                                version: 1,
+                                domain: 'session',
+                                type: `session.cognitive.${event.type}`,
+                                severity: 'info',
+                                sessionId,
+                                payload: event,
+                                source: 'runtime/sessions/pool',
+                            });
+                        }
+                    },
+                    cognitiveConfig: cognitive_config,
+                    cognitiveSink: sessionCognitiveSink,
+                };
+                const handle = await options.providerFactory.createSession(factoryOptions);
+                // The factory returns a handle structurally compatible with
+                // PtySession; cast once here — every method the pool invokes is
+                // guaranteed present by the PtySessionHandle contract.
+                session = handle;
+            }
+            else if (effectiveMode === 'cognitive-agent') {
+                // PRD 033: Cognitive agent session — runs reasoning cycle internally
+                const { createProviderAdapter } = await import('@methodts/pacta');
+                const tools = createRuntimeToolProvider(effectiveWorkdir);
+                const model = llm_config?.model ?? (typeof metadata?.model === 'string' ? metadata.model : undefined);
+                const agentProvider = await resolveProvider(llm_provider, { model, baseUrl: llm_config?.baseUrl, toolProvider: tools });
+                const adapter = createProviderAdapter(agentProvider, {
+                    pactTemplate: { mode: { type: 'oneshot' }, budget: { maxOutputTokens: 4096 } },
+                });
+                // Mutable SSE sink — set by promptStream(), cleared on completion.
+                // Allows cognitive events to flow to both the event bus and the active SSE stream.
+                let sseSink = null;
+                cognitiveSSESinks.set(sessionId, (cb) => { sseSink = cb; });
+                // PRD 041: Create a per-session CognitiveSink with experiment context so that
+                // ExperimentEventSink can route emitted RuntimeEvents to the correct JSONL file.
+                // Falls back to the pool-level sink when no experiment context is present.
+                const sessionCognitiveSink = (experiment_id && run_id && eventBus)
+                    ? new CognitiveSink(eventBus, { sessionId, experimentId: experiment_id, runId: run_id })
+                    : cognitiveSink;
+                session = createCognitiveSession({
+                    id: sessionId,
+                    workdir: effectiveWorkdir,
+                    adapter,
+                    tools,
+                    cognitiveSink: sessionCognitiveSink,
+                    config: {
+                        name: cognitive_config?.name,
+                        patterns: cognitive_patterns,
+                        maxCycles: cognitive_config?.maxCycles,
+                        workspaceCapacity: cognitive_config?.workspaceCapacity,
+                        confidenceThreshold: cognitive_config?.confidenceThreshold,
+                        stagnationThreshold: cognitive_config?.stagnationThreshold,
+                        interventionBudget: cognitive_config?.interventionBudget,
+                    },
+                    initialPrompt: initialPrompt ?? undefined,
+                    onEvent: (event) => {
+                        // Forward to active SSE stream (if any)
+                        sseSink?.(event);
+                        // Route cognitive cycle events through the event bus
+                        if (eventBus) {
+                            eventBus.emit({
+                                version: 1,
+                                domain: 'session',
+                                type: `session.cognitive.${event.type}`,
+                                severity: 'info',
+                                sessionId,
+                                payload: event,
+                                source: 'runtime/sessions/cognitive-provider',
+                            });
+                        }
+                    },
+                });
+            }
+            else {
+                // Default: print-mode session (claude --print)
+                const DEFAULT_SYSTEM_PROMPT_SUFFIX = [
+                    'When producing diagrams, flowcharts, or architecture visualizations, use GlyphJS ui: fenced code blocks instead of ASCII art.',
+                    'Available components: ui:flowchart, ui:callout, ui:table, ui:architecture, ui:timeline, ui:graph, ui:sequence, ui:tabs, ui:steps, ui:kpi, ui:mindmap.',
+                    'Use proper markdown tables (| col | col |) instead of ASCII-aligned columns.',
+                    'Example: ```ui:flowchart\\nnodes:\\n  - id: a\\n    label: Start\\nedges:\\n  - from: a\\n    to: b\\n```',
+                ].join(' ');
+                const userSystemPrompt = typeof metadata?.append_system_prompt === 'string' ? metadata.append_system_prompt : '';
+                const effectiveSystemPrompt = userSystemPrompt
+                    ? `${userSystemPrompt}\n\n${DEFAULT_SYSTEM_PROMPT_SUFFIX}`
+                    : DEFAULT_SYSTEM_PROMPT_SUFFIX;
+                session = createPrintSession({
+                    id: sessionId,
+                    workdir: effectiveWorkdir,
+                    initialPrompt: initialPrompt ?? undefined,
+                    maxBudgetUsd: typeof metadata?.max_budget_usd === 'number' ? metadata.max_budget_usd : undefined,
+                    appendSystemPrompt: effectiveSystemPrompt,
+                    permissionMode: process.env.PRINT_PERMISSION_MODE ?? 'bypassPermissions',
+                    model: typeof metadata?.model === 'string' ? metadata.model : undefined,
+                    spawnArgs,
+                    onEvent: eventBus ? createAgentEventAdapter(eventBus, sessionId, metadata?.project_id ?? 'unknown') : undefined,
+                });
+            }
+            sessions.set(sessionId, session);
+            sessionModes.set(sessionId, effectiveMode);
+            sessionWorkdirs.set(sessionId, effectiveWorkdir);
+            if (metadata) {
+                sessionMetadata.set(sessionId, metadata);
+            }
+            sessionWorktrees.set(sessionId, worktreeInfo);
+            if (staleConfig) {
+                sessionStaleConfigs.set(sessionId, staleConfig);
+            }
+            sessionStaleFlags.set(sessionId, false);
+            sessionNicknames.set(sessionId, assignedNickname);
+            if (purpose) {
+                sessionPurposes.set(sessionId, purpose);
+            }
+            // Record chain info
+            const chainInfo = {
+                parent_session_id: parentSessionId ?? null,
+                depth: effectiveDepth,
+                children: [],
+                budget: effectiveBudget,
+            };
+            sessionChains.set(sessionId, chainInfo);
+            // Register as child of parent
+            if (parentSessionId) {
+                const parentChain = sessionChains.get(parentSessionId);
+                if (parentChain) {
+                    parentChain.children.push(sessionId);
+                }
+            }
+            // PRD 008: Create channels (legacy — retained for getChannels() compatibility)
+            const channels = createSessionChannels();
+            sessionChannels.set(sessionId, channels);
+            // PRD 026 Phase 3: session.spawned emitted via eventBus only (appendMessage removed)
+            if (eventBus) {
+                eventBus.emit({
+                    version: 1,
+                    domain: 'session',
+                    type: 'session.spawned',
+                    severity: 'info',
+                    sessionId,
+                    payload: {
+                        session_id: sessionId,
+                        parent_session_id: parentSessionId ?? null,
+                        depth: effectiveDepth,
+                        mode: effectiveMode,
+                        workdir,
+                        nickname,
+                    },
+                    source: 'runtime/sessions/pool',
+                });
+            }
+            // PRD 010: Track original workdir (pre-worktree) for auto-retro placement
+            sessionOriginalWorkdirs.set(sessionId, workdir);
+            totalSpawned++;
+            return { sessionId, nickname: assignedNickname, status: session.status, chain: chainInfo, worktree: worktreeInfo, mode: effectiveMode };
+        },
+        async prompt(sessionId, prompt, timeoutMs, settleDelayMs) {
+            const session = sessions.get(sessionId);
+            if (!session) {
+                throw new Error(`Session not found: ${sessionId}`);
+            }
+            if (session.status === 'dead') {
+                throw new Error(`Session ${sessionId} is dead — cannot send prompt`);
+            }
+            const result = await session.sendPrompt(prompt, timeoutMs, settleDelayMs);
+            // PRD 012: Record settle overhead for this prompt
+            const tracker = sessionDiagnostics.get(sessionId);
+            if (tracker && !result.timedOut) {
+                tracker.recordPromptCompletion();
+            }
+            // Read printMetadata in-place after sendPrompt resolves (same tick — no race)
+            const printSession = session;
+            const metadata = printSession.printMetadata ?? null;
+            return { output: result.output, timedOut: result.timedOut, metadata };
+        },
+        async promptStream(sessionId, prompt, onEvent, timeoutMs) {
+            const session = sessions.get(sessionId);
+            if (!session) {
+                throw new Error(`Session not found: ${sessionId}`);
+            }
+            if (session.status === 'dead') {
+                throw new Error(`Session ${sessionId} is dead — cannot send prompt`);
+            }
+            // PRD 033: Register SSE sink for cognitive sessions so cycle events flow to SSE
+            const setSink = cognitiveSSESinks.get(sessionId);
+            if (setSink)
+                setSink(onEvent);
+            try {
+                let result;
+                if (typeof session.sendPromptStream === 'function') {
+                    // Use the streaming path — emits incremental text chunks
+                    result = await session.sendPromptStream(prompt, (chunk) => {
+                        onEvent({ type: 'text', content: chunk });
+                    }, timeoutMs);
+                }
+                else {
+                    // Fallback: non-streaming path (subscribes to onOutput for single emit)
+                    const unsubscribe = session.onOutput((data) => {
+                        if (data.startsWith('\n[print-mode]'))
+                            return;
+                        onEvent({ type: 'text', content: data });
+                    });
+                    try {
+                        result = await session.sendPrompt(prompt, timeoutMs);
+                    }
+                    finally {
+                        unsubscribe();
+                    }
+                }
+                // Cognitive sessions emit their own 'done' event via the SSE sink —
+                // skip the pool's redundant done to avoid overwriting metadata with nulls.
+                const isCognitive = cognitiveSSESinks.has(sessionId);
+                if (!isCognitive) {
+                    // Read printMetadata and map to response shape (same as non-streaming endpoint)
+                    const printSession = session;
+                    const raw = printSession.printMetadata ?? null;
+                    const metadata = raw ? {
+                        cost_usd: raw.total_cost_usd,
+                        num_turns: raw.num_turns,
+                        duration_ms: raw.duration_ms,
+                        stop_reason: raw.stop_reason,
+                        input_tokens: raw.usage.input_tokens,
+                        output_tokens: raw.usage.output_tokens,
+                        cache_read_tokens: raw.usage.cache_read_input_tokens,
+                        cache_write_tokens: raw.usage.cache_creation_input_tokens,
+                    } : null;
+                    // Send done event with full response + mapped metadata
+                    onEvent({
+                        type: 'done',
+                        output: result.output,
+                        metadata,
+                        timed_out: result.timedOut,
+                    });
+                }
+            }
+            catch (err) {
+                onEvent({
+                    type: 'error',
+                    error: err.message,
+                });
+            }
+            finally {
+                // Clear the cognitive SSE sink to avoid leaking callbacks
+                if (setSink)
+                    setSink(null);
+            }
+        },
+        status(sessionId) {
+            const session = sessions.get(sessionId);
+            if (!session) {
+                throw new Error(`Session not found: ${sessionId}`);
+            }
+            // OBS-19: Override status to 'waiting' when session is waiting for a sub-agent
+            const waitingFor = sessionWaitingFor.get(sessionId) ?? null;
+            const effectiveStatus = (waitingFor && session.status === 'ready') ? 'waiting' : session.status;
+            // PRD 012: Build diagnostics snapshot with stall classification
+            const tracker = sessionDiagnostics.get(sessionId);
+            let diagnostics = null;
+            if (tracker) {
+                diagnostics = tracker.snapshot();
+                // Classify stall reason for stale or idle sessions
+                const isStale = sessionStaleFlags.get(sessionId) ?? false;
+                if (isStale || (effectiveStatus === 'ready' && session.promptCount > 0)) {
+                    // Check if other sessions are also slow (for resource_contention classification)
+                    const otherSessionsSlow = [...sessionDiagnostics.entries()].some(([otherId, otherTracker]) => {
+                        if (otherId === sessionId)
+                            return false;
+                        const otherSnap = otherTracker.snapshot();
+                        return otherSnap.time_to_first_output_ms !== null && otherSnap.time_to_first_output_ms > 10_000;
+                    });
+                    diagnostics.stall_reason = tracker.classifyStall(otherSessionsSlow);
+                }
+            }
+            return {
+                sessionId,
+                nickname: sessionNicknames.get(sessionId) ?? sessionId.substring(0, 8),
+                purpose: sessionPurposes.get(sessionId) ?? null,
+                status: effectiveStatus,
+                queueDepth: session.queueDepth,
+                metadata: sessionMetadata.get(sessionId),
+                promptCount: session.promptCount,
+                lastActivityAt: session.lastActivityAt,
+                workdir: sessionWorkdirs.get(sessionId) ?? '',
+                chain: getChain(sessionId),
+                worktree: sessionWorktrees.get(sessionId) ?? {
+                    isolation: 'shared', worktree_path: null, worktree_branch: null, metals_available: true,
+                },
+                stale: sessionStaleFlags.get(sessionId) ?? false,
+                waiting_for: waitingFor,
+                mode: sessionModes.get(sessionId) ?? 'print',
+                diagnostics,
+            };
+        },
+        kill(sessionId, worktreeAction) {
+            const session = sessions.get(sessionId);
+            if (!session) {
+                throw new Error(`Session not found: ${sessionId}`);
+            }
+            // PRD 010: Detach watcher and generate auto-retro before killing
+            handleSessionDeath(sessionId, 'killed');
+            session.kill();
+            // PRD 006 Component 2: Handle worktree cleanup
+            let worktreeCleaned = false;
+            const wtInfo = sessionWorktrees.get(sessionId);
+            if (wtInfo && wtInfo.isolation === 'worktree' && wtInfo.worktree_path) {
+                const action = worktreeAction ?? 'keep';
+                const originalWorkdir = resolve(wtInfo.worktree_path, '..', '..', '..');
+                if (action === 'discard') {
+                    try {
+                        execSync(`git worktree remove "${wtInfo.worktree_path}" --force`, {
+                            cwd: originalWorkdir, stdio: 'pipe',
+                        });
+                        if (wtInfo.worktree_branch) {
+                            execSync(`git branch -D "${wtInfo.worktree_branch}"`, {
+                                cwd: originalWorkdir, stdio: 'pipe',
+                            });
+                        }
+                        worktreeCleaned = true;
+                    }
+                    catch {
+                        // Worktree cleanup failure is non-fatal
+                    }
+                }
+                else if (action === 'merge') {
+                    try {
+                        if (wtInfo.worktree_branch) {
+                            execSync(`git merge "${wtInfo.worktree_branch}" --no-edit`, {
+                                cwd: originalWorkdir, stdio: 'pipe',
+                            });
+                        }
+                        execSync(`git worktree remove "${wtInfo.worktree_path}" --force`, {
+                            cwd: originalWorkdir, stdio: 'pipe',
+                        });
+                        worktreeCleaned = true;
+                    }
+                    catch {
+                        // Merge failure is non-fatal — worktree preserved for manual merge
+                    }
+                }
+                // action === 'keep': leave worktree on disk
+            }
+            // PRD 026 Phase 3: session.killed emitted via eventBus only (appendMessage removed)
+            if (eventBus) {
+                eventBus.emit({
+                    version: 1,
+                    domain: 'session',
+                    type: 'session.killed',
+                    severity: 'info',
+                    sessionId,
+                    payload: {
+                        session_id: sessionId,
+                        killed_by: 'api',
+                        worktree_action: worktreeAction ?? 'keep',
+                        worktree_cleaned: worktreeCleaned,
+                    },
+                    source: 'runtime/sessions/pool',
+                });
+            }
+            return { sessionId: session.id, killed: true, worktree_cleaned: worktreeCleaned };
+        },
+        list() {
+            return [...sessions.entries()].map(([sessionId, session]) => {
+                // OBS-19: Override status to 'waiting' when session is waiting for a sub-agent
+                const waitingFor = sessionWaitingFor.get(sessionId) ?? null;
+                const effectiveStatus = (waitingFor && session.status === 'ready') ? 'waiting' : session.status;
+                // PRD 012: Include diagnostics snapshot
+                const tracker = sessionDiagnostics.get(sessionId);
+                const diagnostics = tracker ? tracker.snapshot() : null;
+                return {
+                    sessionId,
+                    nickname: sessionNicknames.get(sessionId) ?? sessionId.substring(0, 8),
+                    purpose: sessionPurposes.get(sessionId) ?? null,
+                    status: effectiveStatus,
+                    queueDepth: session.queueDepth,
+                    metadata: sessionMetadata.get(sessionId),
+                    promptCount: session.promptCount,
+                    lastActivityAt: session.lastActivityAt,
+                    workdir: sessionWorkdirs.get(sessionId) ?? '',
+                    chain: getChain(sessionId),
+                    worktree: sessionWorktrees.get(sessionId) ?? {
+                        isolation: 'shared', worktree_path: null, worktree_branch: null, metals_available: true,
+                    },
+                    stale: sessionStaleFlags.get(sessionId) ?? false,
+                    waiting_for: waitingFor,
+                    mode: sessionModes.get(sessionId) ?? 'print',
+                    diagnostics,
+                };
+            });
+        },
+        getChannels(sessionId) {
+            const channels = sessionChannels.get(sessionId);
+            if (!channels) {
+                throw new Error(`Session not found: ${sessionId}`);
+            }
+            return channels;
+        },
+        getSession(sessionId) {
+            const session = sessions.get(sessionId);
+            if (!session) {
+                throw new Error(`Session not found: ${sessionId}`);
+            }
+            return session;
+        },
+        poolStats() {
+            const allSessions = [...sessions.values()];
+            const active = allSessions.filter((s) => s.status !== 'dead').length;
+            const dead = allSessions.filter((s) => s.status === 'dead').length;
+            return {
+                totalSpawned,
+                startedAt,
+                maxSessions,
+                activeSessions: active,
+                deadSessions: dead,
+            };
+        },
+        removeDead(ttlMs) {
+            let removed = 0;
+            for (const [sessionId, session] of sessions.entries()) {
+                if (session.status === 'dead') {
+                    // Use lastActivityAt as the "died at" timestamp (it's the last activity before death)
+                    if (Date.now() - session.lastActivityAt.getTime() > ttlMs) {
+                        const nick = sessionNicknames.get(sessionId);
+                        if (nick)
+                            activeNicknames.delete(nick);
+                        sessions.delete(sessionId);
+                        sessionMetadata.delete(sessionId);
+                        sessionWorkdirs.delete(sessionId);
+                        sessionModes.delete(sessionId);
+                        sessionChains.delete(sessionId);
+                        sessionChannels.delete(sessionId);
+                        sessionWorktrees.delete(sessionId);
+                        sessionStaleConfigs.delete(sessionId);
+                        sessionStaleFlags.delete(sessionId);
+                        sessionNicknames.delete(sessionId);
+                        sessionPurposes.delete(sessionId);
+                        sessionOriginalWorkdirs.delete(sessionId);
+                        sessionWaitingFor.delete(sessionId);
+                        sessionDiagnostics.delete(sessionId);
+                        removed++;
+                    }
+                }
+            }
+            return removed;
+        },
+        /**
+         * PRD 006 Component 4: Check all sessions for staleness.
+         * - Sessions inactive > stale_timeout_ms → marked stale, 'stale' event emitted
+         * - Sessions inactive > kill_timeout_ms → auto-killed
+         * Returns lists of newly-stale and newly-killed session IDs.
+         */
+        checkStale() {
+            const now = Date.now();
+            const staleIds = [];
+            const killedIds = [];
+            for (const [sessionId, session] of sessions.entries()) {
+                if (session.status === 'dead')
+                    continue;
+                const config = sessionStaleConfigs.get(sessionId);
+                if (!config)
+                    continue;
+                const inactiveMs = now - session.lastActivityAt.getTime();
+                const isStale = sessionStaleFlags.get(sessionId) ?? false;
+                // Auto-kill: inactive beyond kill timeout
+                if (inactiveMs >= config.kill_timeout_ms) {
+                    handleSessionDeath(sessionId, 'stale');
+                    session.kill();
+                    // PRD 026 Phase 3: session.stale emitted via eventBus only (appendMessage removed)
+                    if (eventBus) {
+                        eventBus.emit({
+                            version: 1,
+                            domain: 'session',
+                            type: 'session.stale',
+                            severity: 'warning',
+                            sessionId,
+                            payload: {
+                                session_id: sessionId,
+                                inactive_ms: inactiveMs,
+                                action: 'auto_killed',
+                            },
+                            source: 'runtime/sessions/pool',
+                        });
+                    }
+                    killedIds.push(sessionId);
+                    sessionStaleFlags.set(sessionId, true);
+                    continue;
+                }
+                // Mark stale: inactive beyond stale timeout (but not yet killed)
+                if (inactiveMs >= config.stale_timeout_ms && !isStale) {
+                    sessionStaleFlags.set(sessionId, true);
+                    // PRD 026 Phase 3: session.stale emitted via eventBus only (appendMessage removed)
+                    if (eventBus) {
+                        eventBus.emit({
+                            version: 1,
+                            domain: 'session',
+                            type: 'session.stale',
+                            severity: 'warning',
+                            sessionId,
+                            payload: {
+                                session_id: sessionId,
+                                inactive_ms: inactiveMs,
+                                action: 'marked_stale',
+                                kill_in_ms: config.kill_timeout_ms - inactiveMs,
+                            },
+                            source: 'runtime/sessions/pool',
+                        });
+                    }
+                    staleIds.push(sessionId);
+                }
+            }
+            return { stale: staleIds, killed: killedIds };
+        },
+        childPids() {
+            const pids = [];
+            for (const [, session] of sessions.entries()) {
+                if (session.status !== 'dead' && session.pid !== null) {
+                    pids.push(session.pid);
+                }
+            }
+            return pids;
+        },
+        setObservationHook(_hook) {
+            // PTY watcher removed in PRD 028 C-4. Observation hook is now a no-op.
+        },
+        restoreSession(snapshot) {
+            const sid = snapshot.sessionId;
+            // Duplicate restore — silently skip if session already exists
+            if (sessions.has(sid)) {
+                return;
+            }
+            // Build a minimal PtySession stub that is compatible with pool operations.
+            // The stub does not spawn a process — it is a placeholder for recovered state.
+            // Sending a prompt creates a real print session under the hood (recovered mode).
+            let status = 'ready';
+            let promptCount = snapshot.promptCount;
+            let lastActivityAt = new Date();
+            let transcript = '';
+            const outputSubscribers = new Set();
+            const exitCallbacks = [];
+            let lastMetadata = null;
+            const stubSession = {
+                id: sid,
+                get pid() { return null; },
+                get status() { return status; },
+                set status(s) { status = s; },
+                get queueDepth() { return 0; },
+                get promptCount() { return promptCount; },
+                set promptCount(n) { promptCount = n; },
+                get lastActivityAt() { return lastActivityAt; },
+                set lastActivityAt(d) { lastActivityAt = d; },
+                get transcript() { return transcript; },
+                onOutput(cb) {
+                    outputSubscribers.add(cb);
+                    return () => { outputSubscribers.delete(cb); };
+                },
+                onExit(cb) {
+                    exitCallbacks.push(cb);
+                },
+                sendPrompt(prompt, _timeoutMs, _settleDelayMs) {
+                    if (status === 'dead') {
+                        return Promise.reject(new Error(`Session ${sid} is dead — cannot send prompt`));
+                    }
+                    // Lazy upgrade: replace stub with real print session on first prompt
+                    const real = createPrintSession({
+                        id: sid,
+                        workdir: snapshot.workdir,
+                        recovered: true,
+                        model: typeof snapshot.metadata?.model === 'string' ? snapshot.metadata.model : undefined,
+                        onEvent: eventBus ? createAgentEventAdapter(eventBus, sid, snapshot.metadata?.project_id ?? 'unknown') : undefined,
+                    });
+                    // Migrate subscribers
+                    for (const sub of outputSubscribers) {
+                        real.onOutput(sub);
+                    }
+                    for (const cb of exitCallbacks) {
+                        real.onExit(cb);
+                    }
+                    // Replace in pool map
+                    sessions.set(sid, real);
+                    return real.sendPrompt(prompt, _timeoutMs, _settleDelayMs);
+                },
+                sendPromptStream(prompt, onChunk, _timeoutMs) {
+                    if (status === 'dead') {
+                        return Promise.reject(new Error(`Session ${sid} is dead — cannot send prompt`));
+                    }
+                    // Lazy upgrade: replace stub with real print session on first prompt (streaming)
+                    const real = createPrintSession({
+                        id: sid,
+                        workdir: snapshot.workdir,
+                        recovered: true,
+                        model: typeof snapshot.metadata?.model === 'string' ? snapshot.metadata.model : undefined,
+                        onEvent: eventBus ? createAgentEventAdapter(eventBus, sid, snapshot.metadata?.project_id ?? 'unknown') : undefined,
+                    });
+                    for (const sub of outputSubscribers) {
+                        real.onOutput(sub);
+                    }
+                    for (const cb of exitCallbacks) {
+                        real.onExit(cb);
+                    }
+                    sessions.set(sid, real);
+                    if (typeof real.sendPromptStream === 'function') {
+                        return real.sendPromptStream(prompt, onChunk, _timeoutMs);
+                    }
+                    return real.sendPrompt(prompt, _timeoutMs);
+                },
+                resize(_cols, _rows) { },
+                kill() {
+                    status = 'dead';
+                    outputSubscribers.clear();
+                    for (const cb of exitCallbacks) {
+                        try {
+                            cb(0);
+                        }
+                        catch { /* non-fatal */ }
+                    }
+                },
+                interrupt() { return false; },
+                get adaptiveSettle() { return null; },
+                get printMetadata() { return lastMetadata; },
+            };
+            // Hydrate all internal Maps
+            sessions.set(sid, stubSession);
+            sessionWorkdirs.set(sid, snapshot.workdir);
+            sessionModes.set(sid, snapshot.mode);
+            sessionNicknames.set(sid, snapshot.nickname);
+            activeNicknames.add(snapshot.nickname);
+            if (snapshot.purpose) {
+                sessionPurposes.set(sid, snapshot.purpose);
+            }
+            if (snapshot.metadata) {
+                sessionMetadata.set(sid, snapshot.metadata);
+            }
+            sessionChains.set(sid, {
+                parent_session_id: snapshot.parentSessionId ?? null,
+                depth: snapshot.depth,
+                children: [],
+                budget: { max_depth: DEFAULT_MAX_DEPTH, max_agents: DEFAULT_MAX_AGENTS, agents_spawned: 0 },
+            });
+            sessionWorktrees.set(sid, {
+                isolation: snapshot.isolation,
+                worktree_path: null,
+                worktree_branch: null,
+                metals_available: snapshot.isolation !== 'worktree',
+            });
+            sessionStaleFlags.set(sid, false);
+            sessionChannels.set(sid, createSessionChannels());
+            // Note: totalSpawned is NOT incremented — restored sessions don't count as newly spawned.
+        },
+        cleanupStaleCognitiveSessions() {
+            const killed = [];
+            for (const [sessionId] of sessions.entries()) {
+                if (sessionModes.get(sessionId) === 'cognitive-agent') {
+                    const session = sessions.get(sessionId);
+                    if (session && session.status !== 'dead') {
+                        session.kill();
+                        killed.push(sessionId);
+                        if (eventBus) {
+                            eventBus.emit({
+                                version: 1,
+                                domain: 'session',
+                                type: 'session.killed',
+                                severity: 'info',
+                                sessionId,
+                                payload: {
+                                    session_id: sessionId,
+                                    killed_by: 'startup_recovery',
+                                    reason: 'cognitive sessions are in-memory only and cannot survive a restart',
+                                },
+                                source: 'runtime/sessions/pool',
+                            });
+                        }
+                    }
+                }
+            }
+            return { killed };
+        },
+    };
+}
+//# sourceMappingURL=pool.js.map