@telora/daemon 0.12.33

package/dist/spawner.js

@@ -0,0 +1,734 @@
+/**
+ * Claude Code spawner - manages spawning and tracking agent processes.
+ *
+ * Spawns agents at delivery level with full context including:
+ * - Product info (name, vision, description)
+ * - Delivery details (name, description, acceptance criteria, tech context)
+ * - All context groups and tasks within the delivery
+ *
+ * Each agent runs in an isolated git worktree created from the integration branch.
+ * On successful completion, the agent's branch is merged into integration.
+ */
+import { spawn } from 'node:child_process';
+import { mkdirSync, existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { runGitSync } from './git-types.js';
+import { updateSession, createSession, getDeliveryContext, fetchEffectiveWorkflow, getResolvedTransitionBlockForDelivery, reportGitState } from './supabase.js';
+import { buildSpawnEnvironment } from './spawn-environment.js';
+import { sanitizeGitSegment } from './git-utils.js';
+import { createWorktree, removeWorktree, syncIntegrationWithMain } from './git.js';
+import { recordSessionCompleted, recordActivity } from './heartbeat.js';
+import { getStageByName } from './workflow-engine.js';
+import { StreamJsonParser, sendMessage, buildStreamJsonArgs, stripClaudeCodeEnvVars, createLogStream } from '@telora/daemon-core';
+import { CompletionDetector } from './completion-detector.js';
+import { buildDeliveryPrompt } from './prompt-builder.js';
+import { handleAgentCompletion } from './completion-handler.js';
+import { formatEventForLog } from '@telora/daemon-core';
+import { ActivityTracker } from './activity-tracker.js';
+// Running agents map: sessionId -> RunningAgent
+const runningAgents = new Map();
+// Resource governor (optional, injected by StrategyEngine)
+let governor = null;
+/** Inject the resource governor for global concurrency limiting. */
+export function initGovernor(gov) {
+    governor = gov;
+}
+/**
+ * Get map of running agents.
+ */
+export function getRunningAgents() {
+    return runningAgents;
+}
+/**
+ * Safely send a signal to a process, ignoring errors if the process has already exited.
+ */
+function safeSendSignal(pid, signal) {
+    try {
+        process.kill(pid, signal);
+    }
+    catch (e) {
+        console.debug(`[spawner] safeSendSignal(${pid}, ${signal}) failed (process may have exited):`, e.message);
+    }
+}
+/**
+ * Safely close a writable stdin stream, ignoring errors if already closed.
+ */
+function safeCloseStdin(stdin) {
+    try {
+        stdin.end();
+    }
+    catch (e) {
+        console.debug('[spawner] safeCloseStdin failed (stdin may already be closed):', e.message);
+    }
+}
+/**
+ * Build Claude Code CLI arguments for stream-json I/O.
+ *
+ * Uses the shared base args from daemon-core, then appends daemon-specific flags.
+ */
+function buildClaudeCodeArgs(config) {
+    const args = buildStreamJsonArgs({ mcpConfigPath: config.mcpConfigPath });
+    // Skip user-level settings (hooks etc.) that can block headless execution
+    args.push('--setting-sources', 'project,local');
+    console.log(`  Stream-JSON mode (structured I/O)`);
+    // Agent Teams always enabled -- strategy-level execution model
+    args.push('--teammate-mode', 'in-process');
+    console.log(`  + Agent Teams (in-process teammates)`);
+    return args;
+}
+/**
+ * Set up per-agent timeout enforcement with warning at 80% and escalating shutdown.
+ *
+ * Returns a `timedOut` accessor function (closure over mutable state).
+ */
+function setupTimeoutEnforcement(config, runningAgent, deliveryName, sessionId) {
+    let timedOut = false;
+    const timeoutMs = config.sessionTimeoutMs;
+    if (timeoutMs <= 0) {
+        return { getTimedOut: () => timedOut };
+    }
+    // Warning at 80% of timeout -- send warning via stdin
+    const warningMs = Math.floor(timeoutMs * 0.8);
+    runningAgent.warningTimer = setTimeout(() => {
+        const remaining = Math.ceil((timeoutMs - warningMs) / 60000);
+        console.warn(`[timeout] Agent for "${deliveryName}" at 80% of timeout limit. ` +
+            `Sending warning via stdin. ~${remaining} min remaining.`);
+        sendMessage(runningAgent.stdin, `WARNING: You have approximately ${remaining} minutes remaining before the session ` +
+            `is terminated. Please wrap up your current work, commit changes, and prepare to exit.`);
+    }, warningMs);
+    // Hard timeout -- escalating shutdown: message -> close stdin -> SIGTERM -> SIGKILL
+    runningAgent.timeoutTimer = setTimeout(() => {
+        timedOut = true;
+        console.error(`[timeout] Agent for "${deliveryName}" exceeded ${timeoutMs / 60000} min timeout. ` +
+            `Sending shutdown message...`);
+        runningAgent.streamState = 'shutting_down';
+        sendMessage(runningAgent.stdin, `TIMEOUT: Session time limit reached. Stop all work immediately, commit any changes, and exit now.`);
+        scheduleTimeoutEscalation(runningAgent, deliveryName, sessionId);
+    }, timeoutMs);
+    return { getTimedOut: () => timedOut };
+}
+/**
+ * Schedule escalating shutdown steps after the initial timeout message:
+ * stdin close -> SIGTERM -> SIGKILL
+ */
+function scheduleTimeoutEscalation(agent, deliveryName, sessionId) {
+    // Close stdin after a short grace period to signal EOF
+    setTimeout(() => safeCloseStdin(agent.stdin), 10000);
+    // SIGTERM after stdin close grace period
+    setTimeout(() => {
+        if (!runningAgents.has(sessionId))
+            return;
+        console.error(`[timeout] Agent for "${deliveryName}" did not exit after stdin close. Sending SIGTERM...`);
+        safeSendSignal(agent.pid, 'SIGTERM');
+    }, 20000);
+    // SIGKILL as absolute last resort
+    setTimeout(() => {
+        if (!runningAgents.has(sessionId))
+            return;
+        console.error(`[timeout] Agent for "${deliveryName}" still running. Sending SIGKILL...`);
+        safeSendSignal(agent.pid, 'SIGKILL');
+    }, 30000);
+}
+/**
+ * Fetch the guard directive for a delivery, if one exists.
+ * When a delivery resumes after a transition block is resolved,
+ * the directive template is injected into the agent prompt.
+ * Returns null if no directive is found or on any error.
+ */
+async function fetchGuardDirective(deliveryId) {
+    try {
+        const resolvedBlock = await getResolvedTransitionBlockForDelivery(deliveryId);
+        if (!resolvedBlock?.directive_template)
+            return null;
+        console.log(`  Injecting guard directive from block ${resolvedBlock.block.id} (path: ${resolvedBlock.block.decision_path})`);
+        return resolvedBlock.directive_template;
+    }
+    catch (e) {
+        console.debug(`[spawner] Guard directive lookup failed for delivery ${deliveryId} (non-fatal):`, e.message);
+        return null;
+    }
+}
+/**
+ * Generate branch name for delivery work.
+ */
+function generateBranchName(role, deliveryName) {
+    const sanitizedRoleName = sanitizeGitSegment(role.name);
+    const sanitizedDeliveryName = sanitizeGitSegment(deliveryName);
+    return `agent/${sanitizedRoleName}/${sanitizedDeliveryName}`;
+}
+/**
+ * Spawn a Claude Code agent to work on a delivery.
+ *
+ * The agent runs in an isolated git worktree created from the integration branch.
+ * On successful completion, the agent's changes are merged back to integration.
+ */
+export async function spawnAgentForDelivery(config, deliveryId, role, strategyId) {
+    // Get full delivery context — failures are caught and skipped (retried next cycle)
+    let context;
+    try {
+        context = await getDeliveryContext(deliveryId);
+    }
+    catch (err) {
+        console.error(`Error fetching context for delivery ${deliveryId}:`, err.message);
+        return; // Will be retried next polling cycle
+    }
+    if (!context) {
+        console.error(`Failed to get context for delivery ${deliveryId}`);
+        return;
+    }
+    // Fetch effective workflow (cached for this session's lifetime)
+    let workflow;
+    try {
+        workflow = await fetchEffectiveWorkflow(deliveryId);
+    }
+    catch (err) {
+        console.error(`Error fetching workflow for delivery ${deliveryId}:`, err.message);
+        return; // Will be retried next polling cycle
+    }
+    const branchName = generateBranchName(role, context.delivery.name);
+    // Ensure log directory exists with restrictive permissions (owner-only)
+    if (!existsSync(config.logDir)) {
+        mkdirSync(config.logDir, { recursive: true, mode: 0o700 });
+    }
+    // Check for resolved transition block directive (when resuming after human routing)
+    const guardDirective = await fetchGuardDirective(deliveryId);
+    // Build prompt with full delivery context (+ optional guard directive)
+    const prompt = buildDeliveryPrompt(role, context, guardDirective);
+    // Log file paths
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const stdoutPath = join(config.logDir, `${branchName.replace(/\//g, '-')}-${timestamp}.stdout.log`);
+    const stderrPath = join(config.logDir, `${branchName.replace(/\//g, '-')}-${timestamp}.stderr.log`);
+    // Create session in database — failures are caught and skipped
+    let session;
+    try {
+        const codingStageForSession = getStageByName(workflow, 'coding');
+        session = await createSession({
+            organizationId: context.delivery.organization_id,
+            roleId: role.id,
+            issueId: null, // No single issue - working on whole delivery
+            deliveryId,
+            branchName,
+            workflowStageId: codingStageForSession?.id ?? null,
+        });
+    }
+    catch (err) {
+        console.error(`Error creating session for delivery "${context.delivery.name}":`, err.message);
+        return; // Will be retried next polling cycle
+    }
+    recordActivity();
+    console.log(`Spawning agent for delivery "${context.delivery.name}"`);
+    console.log(`  Role: ${role.name}`);
+    console.log(`  Session: ${session.id}`);
+    console.log(`  Branch: ${branchName}`);
+    console.log(`  Workflow: ${workflow.id} (${workflow.stages.map(s => s.name).join(' -> ')})`);
+    console.log(`  Context Groups/Items: ${context.contextGroups.length}`);
+    // Sync integration branch with main before creating worktree
+    try {
+        const syncResult = await syncIntegrationWithMain(config);
+        if (syncResult.success) {
+            console.log(`  Synced integration with main before worktree creation`);
+        }
+        else {
+            console.warn(`  Could not sync integration with main: ${syncResult.error}`);
+            // Continue anyway — stale code is better than not spawning
+        }
+    }
+    catch (err) {
+        console.warn(`  Sync failed (continuing): ${err instanceof Error ? err.message : String(err)}`);
+    }
+    // Create worktree for this agent (branches from integration)
+    let worktreePath;
+    try {
+        worktreePath = await createWorktree(config, branchName);
+        console.log(`  Worktree: ${worktreePath}`);
+        reportGitState(deliveryId, 'worktree_created', branchName).catch(err => console.warn('[spawner] reportGitState worktree_created failed:', err.message));
+    }
+    catch (err) {
+        console.error(`Failed to create worktree for ${branchName}:`, err instanceof Error ? err.message : String(err));
+        await updateSession(session.id, {
+            status: 'failed',
+            exit_reason: 'Failed to create worktree',
+            ended_at: new Date().toISOString(),
+        });
+        return;
+    }
+    // Build Claude Code arguments and spawn environment
+    const args = buildClaudeCodeArgs(config);
+    const spawnEnv = buildSpawnEnvironment(config, {
+        orgId: config.organizationId,
+        strategyId,
+        deliveryId,
+        sessionId: session.id,
+    });
+    // Update session to starting
+    await updateSession(session.id, {
+        status: 'starting',
+        started_at: new Date().toISOString(),
+        stdout_path: stdoutPath,
+        stderr_path: stderrPath,
+    });
+    // Open log files with restrictive permissions (owner-only read/write)
+    const stdoutLogStream = createLogStream(stdoutPath);
+    const stderrStream = createLogStream(stderrPath);
+    // Raw NDJSON stream log for all agents
+    const jsonlPath = join(config.logDir, `${branchName.replace(/\//g, '-')}-${timestamp}.stream.jsonl`);
+    const jsonlStream = createLogStream(jsonlPath);
+    // Acquire governor slot (if governor is configured)
+    if (governor) {
+        try {
+            await governor.acquireSlot('strategy');
+        }
+        catch (err) {
+            console.warn(`[spawner] Governor denied slot for "${context.delivery.name}":`, err.message);
+            await updateSession(session.id, {
+                status: 'failed',
+                exit_reason: 'Governor denied slot',
+                ended_at: new Date().toISOString(),
+            });
+            removeWorktree(config.repoPath, worktreePath, {
+                branchName,
+                integrationBranch: config.integrationBranch,
+                deliveryName: context.delivery.name,
+                mergeSucceeded: false,
+            });
+            return;
+        }
+    }
+    // Spawn Claude Code — stdin is always piped for stream-json prompt delivery
+    const proc = spawn(config.claudeCodePath, args, {
+        cwd: worktreePath,
+        env: spawnEnv,
+        stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    // Track running agent — declared before parser setup so closures can reference it
+    const streamParser = new StreamJsonParser();
+    const completionDetector = new CompletionDetector();
+    const runningAgent = {
+        sessionId: session.id,
+        roleId: role.id,
+        roleName: role.name,
+        strategyId,
+        deliveryId,
+        deliveryName: context.delivery.name,
+        workflow,
+        branchName,
+        worktreePath,
+        repoPath: config.repoPath,
+        pid: proc.pid,
+        startedAt: new Date(),
+        stdoutPath,
+        stderrPath,
+        enableTeams: true,
+        stdin: proc.stdin,
+        streamParser,
+        streamState: 'starting',
+    };
+    runningAgents.set(session.id, runningAgent);
+    // Wire up stream parsing, logging, and event tracking
+    const activityTracker = attachStreamHandlers({
+        proc, streamParser, completionDetector, runningAgent,
+        deliveryId, deliveryName: context.delivery.name, branchName,
+        stdoutLogStream, jsonlStream,
+    });
+    // Send the initial prompt via stdin as stream-json
+    sendMessage(proc.stdin, prompt);
+    // Stderr always pipes directly to log file
+    proc.stderr?.pipe(stderrStream);
+    // Set up per-agent timeout enforcement
+    const { getTimedOut } = setupTimeoutEnforcement(config, runningAgent, context.delivery.name, session.id);
+    // Update session with PID
+    await updateSession(session.id, {
+        status: 'running',
+        pid: proc.pid,
+    });
+    // Handle process exit and error — delegates to completion-handler module
+    attachProcessHandlers({
+        proc, config, context: context, runningAgent, workflow,
+        branchName, worktreePath, deliveryId,
+        sessionId: session.id, completionDetector, activityTracker,
+        stdoutLogStream, stderrStream, jsonlStream,
+        getTimedOut,
+    });
+}
+/**
+ * Attach stream parser, logging, activity tracking, and completion detection
+ * event handlers to a spawned agent process.
+ */
+function attachStreamHandlers(params) {
+    const { proc, streamParser, completionDetector, runningAgent, deliveryId, deliveryName, branchName, stdoutLogStream, jsonlStream } = params;
+    streamParser.attach(proc.stdout);
+    completionDetector.attach(streamParser);
+    const activityTracker = new ActivityTracker(runningAgent.sessionId);
+    activityTracker.attach(streamParser);
+    // Raw NDJSON log
+    streamParser.on('event', (event) => {
+        jsonlStream.write(JSON.stringify(event) + '\n');
+    });
+    // Human-readable log
+    streamParser.on('event', (event) => {
+        const line = formatEventForLog(event);
+        if (line)
+            stdoutLogStream.write(line + '\n');
+    });
+    // Session state tracking
+    streamParser.on('init', (event) => {
+        runningAgent.claudeSessionId = event.session_id;
+        runningAgent.streamState = 'active';
+        console.log(`  Session initialized (model: ${event.model}, tools: ${event.tools.length})`);
+        reportGitState(deliveryId, 'worktree_active', branchName).catch(err => console.warn('[spawner] reportGitState worktree_active failed:', err.message));
+    });
+    streamParser.on('teammate', (event) => {
+        if (event.subtype === 'teammate_spawned') {
+            console.log(`  [team] Teammate spawned: ${event.agent_name}`);
+        }
+        else if (event.subtype === 'teammate_completed') {
+            const status = event.is_error ? 'FAILED' : 'completed';
+            console.log(`  [team] Teammate ${status}: ${event.agent_name}`);
+        }
+        const state = completionDetector.getState();
+        runningAgent.activeTeammateCount = state.activeTeammateCount;
+        runningAgent.activeTeammates = state.activeTeammates;
+    });
+    streamParser.on('result', (result) => {
+        const cost = result.total_cost_usd?.toFixed(4) ?? '?';
+        console.log(`  [result] ${result.is_error ? 'ERROR' : 'Success'}: ${result.num_turns} turns, $${cost}`);
+    });
+    streamParser.on('error', (err, line) => {
+        console.warn(`  [stream-json] Parse error: ${err.message} — line: ${line.slice(0, 200)}`);
+    });
+    completionDetector.on('complete', (info) => {
+        console.log(`Agent for "${deliveryName}" completed: ` +
+            `${info.turnCount} turns, $${info.totalCostUsd.toFixed(4)}, ` +
+            `all teammates done: ${info.allTeammatesComplete}`);
+        runningAgent.streamState = 'idle';
+        initiateGracefulShutdown(runningAgent, deliveryName);
+    });
+    completionDetector.on('idle', (info) => {
+        console.warn(`Agent for "${deliveryName}" idle for ${info.idleDurationMs / 1000}s ` +
+            `with ${info.activeTeammateCount} active teammates`);
+    });
+    return activityTracker;
+}
+/**
+ * Attach process close and error handlers to a spawned agent.
+ */
+function attachProcessHandlers(params) {
+    const { proc, config, context, runningAgent, workflow, branchName, worktreePath, deliveryId, sessionId, completionDetector, activityTracker, stdoutLogStream, stderrStream, jsonlStream, getTimedOut, } = params;
+    const codingStage = getStageByName(workflow, 'coding');
+    const currentStageId = codingStage?.id;
+    proc.on('close', async (code, signal) => {
+        governor?.releaseSlot('strategy');
+        try {
+            await activityTracker.finalFlush();
+        }
+        catch (err) {
+            console.warn('[spawner] activityTracker.finalFlush failed:', err.message);
+        }
+        handleAgentCompletion(code, signal, {
+            config,
+            context,
+            runningAgent,
+            workflow,
+            branchName,
+            currentStageId,
+            timedOut: getTimedOut(),
+            timeoutMs: config.sessionTimeoutMs,
+            sessionId,
+            deliveryId,
+            completionDetector,
+            stdoutLogStream,
+            stderrStream,
+            jsonlStream,
+            runningAgents,
+        });
+    });
+    proc.on('error', async (err) => {
+        console.error(`Agent for "${context.delivery.name}" error:`, err.message);
+        governor?.releaseSlot('strategy');
+        if (runningAgent.warningTimer)
+            clearTimeout(runningAgent.warningTimer);
+        if (runningAgent.timeoutTimer)
+            clearTimeout(runningAgent.timeoutTimer);
+        completionDetector?.destroy();
+        runningAgents.delete(sessionId);
+        removeWorktree(config.repoPath, worktreePath, {
+            branchName,
+            integrationBranch: config.integrationBranch,
+            deliveryName: context.delivery.name,
+            mergeSucceeded: false,
+        });
+        await updateSession(sessionId, {
+            status: 'failed',
+            exit_reason: 'Agent process error',
+            ended_at: new Date().toISOString(),
+        });
+    });
+}
+/**
+ * Initiate graceful shutdown for an agent session.
+ *
+ * Sends a wrap-up message via stdin, waits for the process to exit,
+ * and escalates to SIGTERM/SIGKILL if needed.
+ */
+function initiateGracefulShutdown(agent, deliveryName) {
+    const GRACE_PERIOD_MS = 60000; // 60s for agent to wrap up
+    const ESCALATION_STEP_MS = 10000; // 10s between escalation steps
+    // Send wrap-up message
+    sendMessage(agent.stdin, 'All work is complete. Please commit any remaining changes, clean up, and exit.');
+    // Flat escalation chain using absolute offsets from now
+    // Step 1: Close stdin after grace period
+    const graceTimer = setTimeout(() => {
+        if (!runningAgents.has(agent.sessionId))
+            return;
+        console.warn(`[shutdown] Agent for "${deliveryName}" did not exit within grace period. Closing stdin...`);
+        safeCloseStdin(agent.stdin);
+    }, GRACE_PERIOD_MS);
+    // Step 2: SIGTERM after grace period + one escalation step
+    setTimeout(() => {
+        if (!runningAgents.has(agent.sessionId))
+            return;
+        console.warn(`[shutdown] Agent for "${deliveryName}" did not exit after stdin close. Sending SIGTERM...`);
+        safeSendSignal(agent.pid, 'SIGTERM');
+    }, GRACE_PERIOD_MS + ESCALATION_STEP_MS);
+    // Step 3: SIGKILL after grace period + two escalation steps
+    setTimeout(() => {
+        if (!runningAgents.has(agent.sessionId))
+            return;
+        console.error(`[shutdown] Agent for "${deliveryName}" still running. Sending SIGKILL...`);
+        safeSendSignal(agent.pid, 'SIGKILL');
+    }, GRACE_PERIOD_MS + ESCALATION_STEP_MS * 2);
+    // Clean up timer if process exits before grace period
+    const checkExit = setInterval(() => {
+        if (!runningAgents.has(agent.sessionId)) {
+            clearTimeout(graceTimer);
+            clearInterval(checkExit);
+        }
+    }, 1000);
+}
+/**
+ * Terminate a running agent.
+ * Sends a shutdown message via stdin, then escalates to SIGTERM/SIGKILL.
+ */
+export function terminateAgent(sessionId) {
+    const agent = runningAgents.get(sessionId);
+    if (!agent)
+        return false;
+    // Clear timeout timers since we're manually terminating
+    if (agent.warningTimer)
+        clearTimeout(agent.warningTimer);
+    if (agent.timeoutTimer)
+        clearTimeout(agent.timeoutTimer);
+    try {
+        // Send shutdown message, then escalate with flat setTimeout chain
+        agent.streamState = 'shutting_down';
+        sendMessage(agent.stdin, 'Session is being terminated. Commit your work and exit immediately.');
+        // Step 1: Close stdin after 5s
+        setTimeout(() => safeCloseStdin(agent.stdin), 5000);
+        // Step 2: SIGTERM after 10s (5s after stdin close)
+        setTimeout(() => {
+            if (!runningAgents.has(sessionId))
+                return;
+            safeSendSignal(agent.pid, 'SIGTERM');
+        }, 10000);
+        return true;
+    }
+    catch (err) {
+        console.error(`Failed to terminate agent ${sessionId}:`, err instanceof Error ? err.message : String(err));
+        return false;
+    }
+}
+/**
+ * Terminate all running agents.
+ */
+export function terminateAllAgents() {
+    for (const [sessionId] of runningAgents) {
+        terminateAgent(sessionId);
+    }
+}
+/**
+ * Check if an agent is running for a session.
+ */
+export function isAgentRunning(sessionId) {
+    return runningAgents.has(sessionId);
+}
+/**
+ * Get count of running agents.
+ */
+export function getRunningAgentCount() {
+    return runningAgents.size;
+}
+// ── Merge Conflict Resolution Agent ──────────────────────────────────
+/** Timeout for the resolution agent (10 minutes). */
+const RESOLUTION_AGENT_TIMEOUT_MS = 10 * 60 * 1000;
+/**
+ * Spawn a short-lived, single-purpose Claude Code agent for merge conflict resolution.
+ *
+ * Used when no active team exists for a strategy but merge conflicts need resolution.
+ * The agent receives a focused prompt with conflict details, resolves in the existing
+ * worktree, and exits. No session DB record, no streaming, no team mode.
+ */
+export async function spawnResolutionAgent(params) {
+    const { config, worktreePath, branchName, integrationBranch, conflictFiles, strategyDescription } = params;
+    const prompt = [
+        `You are resolving merge conflicts in a git worktree.`,
+        ``,
+        `**Worktree:** ${worktreePath}`,
+        `**Branch:** ${branchName}`,
+        `**Merge source:** origin/${integrationBranch}`,
+        ``,
+        `**Conflicted files:**`,
+        ...conflictFiles.map(f => `- ${f}`),
+        ``,
+        `**Strategy context:** ${strategyDescription}`,
+        ``,
+        `**Instructions:**`,
+        `1. Open each conflicted file and resolve the conflict markers (<<<<<<< / ======= / >>>>>>>)`,
+        `2. Stage each resolved file with: git add <file>`,
+        `3. Commit the merge resolution: git commit --no-edit`,
+        `4. Run: npm run build && npm test`,
+        `5. If build or test fails, fix the issues, commit, and re-run until passing`,
+        ``,
+        `Do NOT run git merge --abort. Your goal is to produce a clean merge commit that passes build and tests.`,
+        `Follow the coding standards in CLAUDE.md.`,
+    ].join('\n');
+    const args = [
+        '--print',
+        '--dangerously-skip-permissions',
+        '--setting-sources', 'project,local',
+        prompt,
+    ];
+    // Build a clean environment (strip Claude Code session vars)
+    const spawnEnv = stripClaudeCodeEnvVars(process.env);
+    console.log(`[spawner] Spawning resolution agent for branch ${branchName} (${conflictFiles.length} conflicts)`);
+    return new Promise((resolve) => {
+        const proc = spawn(config.claudeCodePath, args, {
+            cwd: worktreePath,
+            env: spawnEnv,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        // Close stdin immediately -- prompt is passed as CLI arg
+        proc.stdin?.end();
+        // Timeout with escalating shutdown
+        const timeout = setTimeout(() => {
+            console.warn(`[spawner] Resolution agent timed out after ${RESOLUTION_AGENT_TIMEOUT_MS / 1000}s, killing`);
+            try {
+                process.kill(proc.pid, 'SIGTERM');
+            }
+            catch { /* ignore */ }
+            setTimeout(() => {
+                try {
+                    process.kill(proc.pid, 'SIGKILL');
+                }
+                catch { /* ignore */ }
+            }, 10000);
+        }, RESOLUTION_AGENT_TIMEOUT_MS);
+        proc.on('close', (code) => {
+            clearTimeout(timeout);
+            // Verify resolution by checking for remaining unmerged files
+            const unmergedResult = runGitSync(['diff', '--name-only', '--diff-filter=U'], worktreePath);
+            const unmergedFiles = unmergedResult.success
+                ? unmergedResult.output.split('\n').filter(Boolean)
+                : [];
+            if (unmergedFiles.length === 0) {
+                console.log(`[spawner] Resolution agent succeeded for branch ${branchName} (exit code: ${code})`);
+                resolve({ success: true });
+            }
+            else {
+                const msg = `Conflicts remain in: ${unmergedFiles.join(', ')}`;
+                console.warn(`[spawner] Resolution agent failed for branch ${branchName}: ${msg}`);
+                resolve({ success: false, error: msg });
+            }
+        });
+        proc.on('error', (err) => {
+            clearTimeout(timeout);
+            console.error(`[spawner] Resolution agent spawn error: ${err.message}`);
+            resolve({ success: false, error: `Spawn error: ${err.message}` });
+        });
+    });
+}
+// ── Stale Agent Process Detection ────────────────────────────────────
+/**
+ * Check if a process is alive. Returns false if the process doesn't exist
+ * or is a zombie on Linux.
+ */
+export function isProcessAlive(pid) {
+    // Check if PID exists
+    try {
+        process.kill(pid, 0);
+    }
+    catch (e) {
+        console.debug(`[spawner] isProcessAlive(${pid}): process not found (ESRCH):`, e.message);
+        return false;
+    }
+    // On Linux, check for zombie state via /proc/{pid}/status
+    if (process.platform === 'linux') {
+        try {
+            const status = readFileSync(`/proc/${pid}/status`, 'utf-8');
+            const stateMatch = status.match(/^State:\s+(\S)/m);
+            if (stateMatch && stateMatch[1] === 'Z') {
+                return false; // Zombie — won't produce an exit event
+            }
+        }
+        catch (e) {
+            console.debug(`[spawner] isProcessAlive(${pid}): /proc read failed, treating as dead:`, e.message);
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * Check all running agents for PID liveness.
+ *
+ * If an agent's process has disappeared (OOM kill, external kill -9, etc.)
+ * without firing a 'close' event, clean up the agent entry and update the
+ * session in the database.
+ *
+ * Guards against double-cleanup by checking runningAgents.has() before acting.
+ */
+export async function checkAgentLiveness(config) {
+    if (runningAgents.size === 0)
+        return;
+    // Snapshot keys to avoid mutating the map while iterating
+    const entries = [...runningAgents.entries()];
+    for (const [sessionId, agent] of entries) {
+        // Guard: agent may have been cleaned up by a normal exit event since we started
+        if (!runningAgents.has(sessionId))
+            continue;
+        if (isProcessAlive(agent.pid))
+            continue;
+        // PID is gone — stale agent detected
+        const runtime = Math.round((Date.now() - agent.startedAt.getTime()) / 1000);
+        console.error(`[liveness] Stale agent detected: "${agent.deliveryName}" ` +
+            `(session: ${sessionId}, PID: ${agent.pid}, runtime: ${runtime}s). ` +
+            `Process disappeared — possible OOM or external kill.`);
+        // Clear timeout timers
+        if (agent.warningTimer)
+            clearTimeout(agent.warningTimer);
+        if (agent.timeoutTimer)
+            clearTimeout(agent.timeoutTimer);
+        // Remove from tracking map
+        runningAgents.delete(sessionId);
+        // Update session in database
+        try {
+            await updateSession(sessionId, {
+                status: 'failed',
+                exit_reason: 'Process disappeared — possible OOM or external kill',
+                ended_at: new Date().toISOString(),
+            });
+        }
+        catch (err) {
+            console.error(`[liveness] Failed to update session ${sessionId}:`, err.message);
+        }
+        // Record session completion for heartbeat counters
+        recordSessionCompleted(0, 0);
+        // Clean up worktree (safety guards in removeWorktree protect uncommitted work)
+        // Use agent.repoPath (captured at spawn time) so multi-product agents clean up in the correct repo
+        removeWorktree(agent.repoPath, agent.worktreePath, {
+            branchName: agent.branchName,
+            integrationBranch: config.integrationBranch,
+            deliveryName: agent.deliveryName,
+            mergeSucceeded: false,
+        });
+    }
+}
+//# sourceMappingURL=spawner.js.map