kantban-cli 0.1.6 → 0.1.8

package/dist/commands/pipeline.js

@@ -1,13 +1,26 @@
-import { execFile, execSync } from 'node:child_process';
-import { mkdirSync, writeFileSync, readFileSync, unlinkSync, existsSync } from 'node:fs';
+import { spawn, execSync } from 'node:child_process';
+import { mkdirSync, writeFileSync, readFileSync, unlinkSync, existsSync, appendFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { PipelineOrchestrator } from '../lib/orchestrator.js';
 import { RalphLoop } from '../lib/ralph-loop.js';
+import { RunMemory } from '../lib/run-memory.js';
 import { EventQueue } from '../lib/event-queue.js';
 import { PipelineWsClient } from '../lib/ws-client.js';
-import { generateMcpConfig, cleanupMcpConfig } from '../lib/mcp-config.js';
+import { generateMcpConfig, generateGateProxyMcpConfig, cleanupMcpConfig, cleanupGateProxyConfigs } from '../lib/mcp-config.js';
 import { PipelineLogger } from '../lib/logger.js';
+import { composeLightPrompt, parseLightResponse } from '../lib/light-call.js';
+import { composeAdvisorPrompt, parseAdvisorResponse } from '../lib/advisor.js';
+import { composeStuckDetectionPrompt, parseStuckDetectionResponse } from '../lib/stuck-detector.js';
+import { cleanupWorktree } from '../lib/worktree.js';
+import { spawnReaper, killReaper } from '../lib/reaper.js';
+import { StreamJsonParser } from '../lib/stream-parser.js';
+import { parseGateConfig, resolveGatesForColumn, parseTimeout } from '../lib/gate-config.js';
+import { GateSnapshotStore } from '../lib/gate-snapshot.js';
+import { runGates } from '../lib/gate-runner.js';
+import { PipelineCostTracker } from '../lib/cost-tracker.js';
+import { composeReplannerPrompt, parseReplannerResponse } from '../lib/replanner.js';
+import { PipelineEventEmitter } from '../lib/event-emitter.js';
 function parseArgs(args) {
     const positional = [];
     let once = false;
@@ -75,6 +88,11 @@ function parseArgs(args) {
         }
     }
     const boardId = positional[0] ?? '';
+    const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+    if (boardId && !UUID_RE.test(boardId)) {
+        console.error(`Error: invalid board ID "${boardId}" — expected UUID`);
+        process.exit(1);
+    }
     if (!boardId) {
         console.error(`Usage: kantban pipeline <board-id> [flags]
 
@@ -103,8 +121,8 @@ function pidFilePath(boardId) {
 }
 function writePidFile(boardId) {
     const dir = pidDir(boardId);
-    mkdirSync(dir, { recursive: true });
-    writeFileSync(pidFilePath(boardId), String(process.pid));
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    writeFileSync(pidFilePath(boardId), String(process.pid), { mode: 0o600 });
 }
 function removePidFile(boardId) {
     try {
@@ -114,6 +132,51 @@ function removePidFile(boardId) {
         /* already removed */
     }
 }
+// ---------------------------------------------------------------------------
+// Child PID manifest helpers — tracks spawned child PIDs on disk for orphan
+// cleanup by the watchdog reaper or next-startup cleanup.
+// ---------------------------------------------------------------------------
+function childManifestPath(boardId) {
+    return join(pidDir(boardId), 'children.pid');
+}
+function appendChildPid(boardId, pid) {
+    const dir = pidDir(boardId);
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    appendFileSync(childManifestPath(boardId), `${String(pid)}\n`, { mode: 0o600 });
+}
+function removeChildPid(boardId, pid) {
+    const manifestPath = childManifestPath(boardId);
+    try {
+        const contents = readFileSync(manifestPath, 'utf-8');
+        const pids = contents.split('\n').filter(l => l.trim() !== '' && l.trim() !== String(pid));
+        writeFileSync(manifestPath, pids.length > 0 ? pids.join('\n') + '\n' : '', { mode: 0o600 });
+    }
+    catch {
+        /* manifest doesn't exist or unreadable — nothing to remove */
+    }
+}
+function readChildManifest(boardId) {
+    try {
+        const contents = readFileSync(childManifestPath(boardId), 'utf-8');
+        return contents
+            .split('\n')
+            .map(l => l.trim())
+            .filter(l => l !== '')
+            .map(Number)
+            .filter(n => !isNaN(n) && n > 0);
+    }
+    catch {
+        return [];
+    }
+}
+function removeChildManifest(boardId) {
+    try {
+        unlinkSync(childManifestPath(boardId));
+    }
+    catch {
+        /* already removed */
+    }
+}
 /**
  * Kill any orphaned pipeline processes from a previous run.
  * Reads the stale PID file, kills that process tree, then removes the file.
@@ -141,9 +204,46 @@ function cleanupOrphanedProcesses(boardId) {
         }
         removePidFile(boardId);
     }
-    // 2. Kill orphaned claude -p processes with kantban-pipeline MCP configs
+    // 1.5. Kill children from the PID manifest (more targeted than grep)
+    const manifestPids = readChildManifest(boardId);
+    if (manifestPids.length > 0) {
+        for (const pid of manifestPids) {
+            try {
+                process.kill(pid, 0); // test if alive
+                process.kill(pid, 'SIGTERM');
+            }
+            catch {
+                // already dead
+            }
+        }
+        console.log(`Killed ${String(manifestPids.length)} orphaned child process(es) from manifest`);
+        removeChildManifest(boardId);
+    }
+    // 1.6. Kill stale reaper if still running
+    const staleReaperPath = join(pidDir(boardId), 'reaper.pid');
+    try {
+        if (existsSync(staleReaperPath)) {
+            const reaperPid = parseInt(readFileSync(staleReaperPath, 'utf-8').trim(), 10);
+            if (reaperPid && !isNaN(reaperPid)) {
+                try {
+                    process.kill(reaperPid, 0);
+                    process.kill(reaperPid, 'SIGTERM');
+                    console.log(`Killed stale reaper (PID ${String(reaperPid)})`);
+                }
+                catch {
+                    // already dead
+                }
+            }
+            unlinkSync(staleReaperPath);
+        }
+    }
+    catch {
+        // can't read reaper PID — not critical
+    }
+    // 2. Kill orphaned claude -p processes with THIS BOARD's MCP configs
     try {
-        const out = execSync(`ps aux | grep 'claude.*-p.*kantban-pipeline' | grep -v grep | awk '{print $2}'`, { encoding: 'utf-8', timeout: 5000 }).trim();
+        const boardDir = pidDir(boardId).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        const out = execSync(`ps aux | grep 'claude.*-p' | grep '${boardDir}' | grep -v grep | awk '{print $2}'`, { encoding: 'utf-8', timeout: 5000 }).trim();
         if (out) {
             const pids = out.split('\n').filter(Boolean);
             for (const pid of pids) {
@@ -169,37 +269,126 @@ function cleanupOrphanedProcesses(boardId) {
 // the group (e.g. on crash) takes all children down with it.
 // ---------------------------------------------------------------------------
 const activeChildProcesses = new Set();
+let currentBoardId = '';
 const CLAUDE_TIMEOUT_MS = 60 * 60 * 1000; // 1 hour max per invocation
 async function invokeClaudeP(prompt, options) {
-    const args = ['-p', prompt, '--mcp-config', options.mcpConfigPath, '--dangerously-skip-permissions'];
+    const args = ['-p', prompt, '--dangerously-skip-permissions', '--output-format', 'stream-json', '--verbose'];
+    // MCP config — omit for toolless invocations
+    if (options.includeMcpConfig !== false && options.mcpConfigPath) {
+        args.push('--mcp-config', options.mcpConfigPath);
+    }
     if (options.model)
         args.push('--model', options.model);
-    if (options.maxBudgetUsd)
-        args.push('--max-turns', String(Math.ceil(options.maxBudgetUsd * 10)));
+    if (options.maxTurns) {
+        args.push('--max-turns', String(options.maxTurns));
+    }
+    else if (options.maxBudgetUsd !== undefined && options.maxBudgetUsd !== null) {
+        args.push('--max-turns', String(Math.max(1, Math.ceil(options.maxBudgetUsd * 10))));
+    }
     if (options.worktree)
         args.push('--worktree', options.worktree);
+    // Tool scoping flags
+    if (options.tools !== undefined) {
+        args.push('--tools', options.tools);
+    }
+    if (options.allowedTools?.length) {
+        args.push('--allowedTools', ...options.allowedTools);
+    }
+    if (options.disallowedTools?.length) {
+        args.push('--disallowedTools', ...options.disallowedTools);
+    }
     return new Promise((resolve) => {
-        const child = execFile('claude', args, {
-            maxBuffer: 50 * 1024 * 1024, // 50MB
-            timeout: CLAUDE_TIMEOUT_MS,
-        }, (err, stdout) => {
-            activeChildProcesses.delete(child);
-            if (err) {
-                const execErr = err;
-                if (execErr.code === 'ENOENT') {
-                    resolve({ exitCode: 127, output: 'Error: "claude" command not found. Ensure Claude Code CLI is installed and on PATH.' });
-                    return;
-                }
-                const exitCode = typeof execErr.code === 'number'
-                    ? execErr.code
-                    : (execErr.killed ? 137 : 1);
-                resolve({ exitCode, output: stdout || err.message || '' });
+        const child = spawn('claude', args, {
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        activeChildProcesses.add(child);
+        if (child.pid && currentBoardId)
+            appendChildPid(currentBoardId, child.pid);
+        const parser = new StreamJsonParser();
+        parser.on('error', (err) => {
+            process.stderr.write(`[stream-parser] ${err.message}\n`);
+        });
+        let lastOutput = '';
+        let tokensIn = 0;
+        let tokensOut = 0;
+        parser.on('event', (event) => {
+            // Capture final result metadata
+            if (event.type === 'result') {
+                const usage = event.usage;
+                tokensIn += usage?.input_tokens ?? 0;
+                tokensOut += usage?.output_tokens ?? 0;
+                if (typeof event.result === 'string')
+                    lastOutput = event.result;
             }
-            else {
-                resolve({ exitCode: 0, output: stdout });
+            // Forward to stream callback if provided
+            options.onStreamEvent?.(event);
+        });
+        child.stdout?.on('data', (chunk) => {
+            parser.feed(chunk.toString());
+        });
+        // Capture stderr for error diagnostics
+        let stderr = '';
+        child.stderr?.on('data', (chunk) => {
+            stderr += chunk.toString();
+        });
+        // Close stdin immediately (we pass prompt via -p flag)
+        child.stdin?.end();
+        // Set up timeout
+        let killTimer;
+        const timeoutHandle = setTimeout(() => {
+            try {
+                child.kill('SIGTERM');
             }
+            catch { /* already dead */ }
+            // Escalate to SIGKILL if process doesn't exit within 5s
+            killTimer = setTimeout(() => {
+                if (!resolved) {
+                    try {
+                        child.kill('SIGKILL');
+                    }
+                    catch { /* already dead */ }
+                }
+            }, 5000);
+        }, CLAUDE_TIMEOUT_MS);
+        let resolved = false;
+        child.on('close', (code) => {
+            if (resolved)
+                return;
+            resolved = true;
+            clearTimeout(timeoutHandle);
+            if (killTimer)
+                clearTimeout(killTimer);
+            activeChildProcesses.delete(child);
+            if (child.pid && currentBoardId)
+                removeChildPid(currentBoardId, child.pid);
+            parser.flush();
+            resolve({
+                exitCode: code ?? 1,
+                output: lastOutput || stderr,
+                toolCallCount: parser.getToolCallCount(),
+                tokensIn,
+                tokensOut,
+            });
+        });
+        child.on('error', (err) => {
+            if (resolved)
+                return;
+            resolved = true;
+            clearTimeout(timeoutHandle);
+            if (killTimer)
+                clearTimeout(killTimer);
+            activeChildProcesses.delete(child);
+            if (child.pid && currentBoardId)
+                removeChildPid(currentBoardId, child.pid);
+            parser.flush();
+            resolve({
+                exitCode: 1,
+                output: err.message,
+                toolCallCount: parser.getToolCallCount(),
+                tokensIn,
+                tokensOut,
+            });
         });
-        activeChildProcesses.add(child);
     });
 }
 function killAllChildProcesses() {
@@ -246,25 +435,31 @@ Before proceeding:
 Press Ctrl+C to cancel, or re-run with --yes to skip this warning.
 `);
 }
-async function waitForConfirmation() {
+function waitForConfirmation() {
     return new Promise((resolve) => {
+        // Non-TTY (piped input) — read from stdin instead of rejecting
         process.stdout.write('Continue? [y/N] ');
         process.stdin.setEncoding('utf8');
         process.stdin.once('data', (data) => {
             const answer = data.trim().toLowerCase();
             resolve(answer === 'y' || answer === 'yes');
         });
-        // If stdin is not a TTY (piped), reject
-        if (!process.stdin.isTTY) {
-            resolve(false);
-        }
+        // If stdin ends without data (empty pipe), default to no
+        process.stdin.once('end', () => resolve(false));
     });
 }
 // ---------------------------------------------------------------------------
 // runPipeline — main entry point
 // ---------------------------------------------------------------------------
 export async function runPipeline(client, args) {
+    // Handle subcommands
+    if (args[0] === 'init') {
+        const { runPipelineInit } = await import('./pipeline-init.js');
+        await runPipelineInit();
+        return;
+    }
     const opts = parseArgs(args);
+    currentBoardId = opts.boardId;
     // Safety confirmation
     if (!opts.yes && !opts.dryRun) {
         printSafetyWarning();
@@ -274,6 +469,30 @@ export async function runPipeline(client, args) {
             return;
         }
     }
+    // Validate gate file
+    const gateFilePath = join(process.cwd(), 'pipeline.gates.yaml');
+    let gateConfig;
+    if (!existsSync(gateFilePath)) {
+        console.error(`Error: pipeline.gates.yaml not found in ${process.cwd()}`);
+        console.error('Run "kantban pipeline init" to generate a starter gate file.');
+        process.exit(1);
+    }
+    try {
+        const gateYaml = readFileSync(gateFilePath, 'utf-8');
+        gateConfig = parseGateConfig(gateYaml);
+        console.log(`Gate config loaded: ${gateConfig.default.length} default gate(s)`);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        console.error(`Error: Invalid pipeline.gates.yaml: ${message}`);
+        process.exit(1);
+    }
+    // Create cost tracker if budget is configured
+    const costTracker = gateConfig.settings?.budget
+        ? new PipelineCostTracker(crypto.randomUUID(), gateConfig.settings.budget)
+        : undefined;
+    // Gate snapshot store — per-ticket gate history for gutter detection and advisor
+    const gateSnapshotStore = new GateSnapshotStore();
     // Resolve project ID
     let projectId = process.env['KANTBAN_PROJECT_ID'] ?? '';
     if (!projectId) {
@@ -294,28 +513,171 @@ export async function runPipeline(client, args) {
     const logBaseDir = join(homedir(), '.kantban', 'pipelines');
     const logger = new PipelineLogger(logBaseDir, opts.boardId);
     logger.pruneOldLogs(opts.logRetention);
+    // Declared early so closures in deps can capture it by reference before initialization
+    let runMemory = null;
+    // Stable session ID for all pipeline events in this run
+    const pipelineSessionId = crypto.randomUUID();
+    const eventEmitter = new PipelineEventEmitter(client.baseUrl, projectId, client.token, opts.boardId, pipelineSessionId);
     // Wire up OrchestratorDeps
     const deps = {
         fetchBoardScope: (boardId) => client.get(`/projects/${projectId}/pipeline-context`, { boardId }),
         fetchColumnScope: (columnId) => client.get(`/projects/${projectId}/pipeline-context`, { columnId }),
-        startLoop: (ticketId, columnId, config) => {
+        startLoop: async (ticketId, columnId, config) => {
             // Apply CLI overrides
             const effectiveConfig = {
                 ...config,
                 ...(opts.maxIterations !== null && { maxIterations: opts.maxIterations }),
                 ...(opts.maxBudget !== null && { maxBudgetUsd: opts.maxBudget }),
-                ...(opts.model !== null && { modelPreference: opts.model }),
+                ...(opts.model !== null && { model: opts.model }),
             };
+            // Capture run memory ref before async work so closures below see the same instance
+            const mem = runMemory;
+            // Resolve column name once upfront so we can select the right MCP config.
+            // This also pre-warms cachedColumnName for onPostIterationGates below.
+            const colScopeForName = await client.get(`/projects/${projectId}/pipeline-context`, { columnId });
+            const resolvedColumnName = colScopeForName.column.name;
+            // Choose MCP config: gate-proxy variant when gates are configured for this column,
+            // global variant otherwise.
+            const columnGates = resolveGatesForColumn(gateConfig, resolvedColumnName);
+            const effectiveMcpConfigPath = columnGates.length > 0
+                ? generateGateProxyMcpConfig(client.baseUrl, client.token, opts.boardId, gateFilePath, columnId, resolvedColumnName, projectId)
+                : mcpConfigPath;
             const loopDeps = {
                 fetchTicketContext: (tid) => client.get(`/projects/${projectId}/pipeline-context`, { ticketId: tid }),
                 fetchColumnContext: (cid) => client.get(`/projects/${projectId}/pipeline-context`, { columnId: cid }),
                 fetchFingerprint: (tid) => client.getFingerprint(projectId, tid),
                 invokeClaudeP,
-                mcpConfigPath,
+                mcpConfigPath: effectiveMcpConfigPath,
                 projectId,
                 log: (msg) => {
                     logger.orchestrator(`[${ticketId}] ${msg}`);
                 },
+                // Run memory enrichment — inject accumulated discoveries into each iteration prompt
+                fetchRunMemoryContent: mem
+                    ? async () => {
+                        const content = await mem.getContent();
+                        const lines = content.split('\n');
+                        if (lines.length > 500) {
+                            return lines.slice(-500).join('\n');
+                        }
+                        return content;
+                    }
+                    : undefined,
+                // Lookahead enrichment — fetch next-column prompt doc so agent can anticipate exit criteria
+                fetchLookaheadDocument: effectiveConfig.lookaheadColumnId
+                    ? async () => {
+                        const colScope = await client.get(`/projects/${projectId}/pipeline-context`, { columnId: effectiveConfig.lookaheadColumnId });
+                        if (!colScope.prompt_document)
+                            return undefined;
+                        return { title: colScope.prompt_document.title, content: colScope.prompt_document.content };
+                    }
+                    : undefined,
+                // Pipeline event emission — forward stream/session events to WS for browser delivery
+                onStreamEvent: deps.emitPipelineEvent
+                    ? (event, context) => {
+                        deps.emitPipelineEvent({
+                            type: 'pipeline:stream',
+                            payload: {
+                                boardId: opts.boardId,
+                                ticketId: context.ticketId,
+                                columnId: context.columnId,
+                                runId: context.runId,
+                                sessionId: pipelineSessionId,
+                                event: event,
+                            },
+                        });
+                    }
+                    : undefined,
+                onSessionStart: deps.emitPipelineEvent
+                    ? (meta) => {
+                        deps.emitPipelineEvent({
+                            type: 'pipeline:session-start',
+                            payload: {
+                                boardId: opts.boardId,
+                                ticketId,
+                                columnId,
+                                runId: meta.runId,
+                                sessionId: pipelineSessionId,
+                                model: meta.model,
+                                invocationType: 'heavy',
+                                iteration: meta.iteration,
+                            },
+                        });
+                    }
+                    : undefined,
+                onSessionEnd: (meta) => {
+                    // Cost tracking — always active
+                    costTracker?.record({
+                        ticketId,
+                        columnId,
+                        model: effectiveConfig.model ?? 'default',
+                        tokensIn: meta.tokensIn,
+                        tokensOut: meta.tokensOut,
+                        type: 'heavy',
+                    });
+                    // Pipeline event emission — only when WS client is connected
+                    if (deps.emitPipelineEvent) {
+                        deps.emitPipelineEvent({
+                            type: 'pipeline:session-end',
+                            payload: {
+                                boardId: opts.boardId,
+                                runId: meta.runId,
+                                exitReason: null,
+                                tokensIn: meta.tokensIn,
+                                tokensOut: meta.tokensOut,
+                                toolCallCount: meta.toolCallCount,
+                                durationMs: meta.durationMs,
+                            },
+                        });
+                    }
+                },
+            };
+            // Wire checkpoint callback when setFieldValue is available
+            if (deps.setFieldValue) {
+                effectiveConfig.onCheckpoint = async (tid, checkpoint) => {
+                    try {
+                        await deps.setFieldValue(tid, 'loop_checkpoint', checkpoint);
+                    }
+                    catch {
+                        // Fire-and-forget
+                    }
+                };
+            }
+            // Wire stuck detection — invokes a lightweight LLM to classify trajectory mid-run
+            if (effectiveConfig.stuckDetection) {
+                effectiveConfig.invokeStuckDetection = async (input) => {
+                    const prompt = composeStuckDetectionPrompt(input);
+                    const { exitCode, output } = await invokeClaudeP(prompt, {
+                        mcpConfigPath,
+                        model: 'haiku',
+                        maxBudgetUsd: 0.01,
+                        tools: '',
+                        includeMcpConfig: false,
+                    });
+                    if (exitCode !== 0) {
+                        throw new Error(`Stuck detection call failed (exit ${String(exitCode)})`);
+                    }
+                    return parseStuckDetectionResponse(output);
+                };
+            }
+            // Wire post-iteration gate runner — runs all gates after each Claude invocation
+            // resolvedColumnName is already fetched above — no per-iteration API call needed.
+            effectiveConfig.onPostIterationGates = async (tid, iteration) => {
+                const gates = resolveGatesForColumn(gateConfig, resolvedColumnName);
+                if (gates.length === 0) {
+                    // No gates — return a synthetic all-pass snapshot
+                    return gateSnapshotStore.record(tid, iteration, []);
+                }
+                const runOpts = {};
+                if (gateConfig.settings?.cwd)
+                    runOpts.cwd = gateConfig.settings.cwd;
+                if (gateConfig.settings?.env)
+                    runOpts.env = gateConfig.settings.env;
+                if (gateConfig.settings?.total_timeout) {
+                    runOpts.totalTimeoutMs = parseTimeout(gateConfig.settings.total_timeout);
+                }
+                const results = await runGates(gates, runOpts);
+                return gateSnapshotStore.record(tid, iteration, results);
             };
             const loop = new RalphLoop(ticketId, columnId, effectiveConfig, loopDeps);
             // Track active loops for graceful shutdown
@@ -325,13 +687,133 @@ export async function runPipeline(client, args) {
             });
         },
         createComment: (ticketId, body) => client.post(`/projects/${projectId}/tickets/${ticketId}/comments`, { body }),
-        createSignal: (ticketId, body) => client.post(`/projects/${projectId}/tickets/${ticketId}/signals`, { body }),
+        createSignal: (ticketId, body) => client.post(`/projects/${projectId}/signals`, {
+            scopeType: 'ticket',
+            scopeId: ticketId,
+            content: body,
+        }),
+        createColumnSignal: (columnId, body) => client.post(`/projects/${projectId}/signals`, {
+            scopeType: 'column',
+            scopeId: columnId,
+            content: body,
+        }),
         claimTicket: (ticketId) => client.claimTicket(projectId, ticketId),
         fetchBlockedTickets: (ticketId) => client.get(`/projects/${projectId}/tickets/${ticketId}/blocked-tickets`),
         hasUnresolvedBlockers: async (ticketId) => {
             const blockers = await client.get(`/projects/${projectId}/tickets/${ticketId}/unresolved-blockers`);
             return blockers.length > 0;
         },
+        dispatchLightCall: async (ticketId, columnId) => {
+            // Fetch minimal context for light call (parallel)
+            const [ticketCtx, colScope, boardScope] = await Promise.all([
+                client.get(`/projects/${projectId}/pipeline-context`, { ticketId }),
+                client.get(`/projects/${projectId}/pipeline-context`, { columnId }),
+                client.get(`/projects/${projectId}/pipeline-context`, { boardId: opts.boardId }),
+            ]);
+            const lightCtx = {
+                ticketId,
+                ticketNumber: ticketCtx.ticket.ticket_number,
+                ticketTitle: ticketCtx.ticket.title,
+                ...(ticketCtx.ticket.description ? { ticketDescription: ticketCtx.ticket.description } : {}),
+                columnName: colScope.column.name,
+                fieldValues: ticketCtx.field_values,
+                toolPrefix: colScope.tool_prefix,
+                projectId,
+                ...(colScope.transition_rules ? { transitionRules: colScope.transition_rules } : {}),
+                ...(boardScope.columns && boardScope.columns.length > 0 && {
+                    availableColumns: boardScope.columns.map((col) => ({ id: col.id, name: col.name })),
+                }),
+            };
+            const prompt = composeLightPrompt(lightCtx);
+            logger.orchestrator(`[${ticketId}] Light call: composing prompt for column "${colScope.column.name}"`);
+            const { exitCode, output, tokensIn, tokensOut } = await invokeClaudeP(prompt, {
+                mcpConfigPath,
+                model: 'haiku',
+                maxBudgetUsd: 0.01,
+                maxTurns: 3,
+                tools: '', // Strip all built-in tools
+                includeMcpConfig: false, // No MCP tools either
+            });
+            costTracker?.record({ ticketId, columnId, model: 'haiku', tokensIn, tokensOut, type: 'light' });
+            if (exitCode !== 0) {
+                throw new Error(`Light call exited with code ${exitCode}: ${output.slice(0, 200)}`);
+            }
+            const response = parseLightResponse(output);
+            logger.orchestrator(`[${ticketId}] Light call result: ${response.action} — ${response.reason}`);
+            return response;
+        },
+        // Advisor invocation — recovers from failure exits (stalled/error/max_iterations)
+        invokeAdvisor: async (input) => {
+            const prompt = composeAdvisorPrompt(input);
+            logger.orchestrator(`[${input.ticketId}] Advisor: invoking for ${input.exitReason}`);
+            const { exitCode, output, tokensIn, tokensOut } = await invokeClaudeP(prompt, {
+                mcpConfigPath,
+                model: 'haiku',
+                maxBudgetUsd: 0.01,
+                tools: '',
+                includeMcpConfig: false,
+            });
+            costTracker?.record({ ticketId: input.ticketId, columnId: '', model: 'haiku', tokensIn, tokensOut, type: 'advisor' });
+            if (exitCode !== 0) {
+                throw new Error(`Advisor call exited with code ${exitCode}: ${output.slice(0, 200)}`);
+            }
+            const response = parseAdvisorResponse(output);
+            logger.orchestrator(`[${input.ticketId}] Advisor: ${response.action} — ${response.reason}`);
+            return response;
+        },
+        // Field value management — used for debt items, checkpoint writes, and escalation metadata
+        setFieldValue: async (ticketId, fieldName, value) => {
+            await client.put(`/projects/${projectId}/tickets/${ticketId}/field-values`, {
+                values: { [fieldName]: value },
+            });
+        },
+        getFieldValues: async (ticketId) => {
+            const ctx = await client.get(`/projects/${projectId}/pipeline-context`, { ticketId });
+            return ctx.field_values;
+        },
+        // Ticket management for advisor actions (ESCALATE, SPLIT_TICKET)
+        moveTicketToColumn: async (ticketId, columnId, handoff) => {
+            await client.patch(`/projects/${projectId}/tickets/${ticketId}/move`, {
+                column_id: columnId,
+                handoff,
+            });
+        },
+        createTickets: async (parentTicketId, specs) => {
+            const ids = [];
+            for (const spec of specs) {
+                const result = await client.post(`/projects/${projectId}/tickets`, { title: spec.title, description: spec.description, parent_id: parentTicketId });
+                ids.push(result.id);
+            }
+            return ids;
+        },
+        archiveTicket: async (ticketId) => {
+            await client.post(`/projects/${projectId}/tickets/${ticketId}/archive`, {});
+        },
+        // Run memory append — closure captures runMemory by reference (set after initialization)
+        appendRunMemory: (section, content) => runMemory ? runMemory.append(section, content) : Promise.resolve(),
+        cleanupWorktree: (name) => cleanupWorktree(name),
+        // Pipeline event emission — wsClient captured by reference (set later before any loops run)
+        emitPipelineEvent: (event) => {
+            wsClient?.send(event);
+        },
+        boardId: opts.boardId,
+        eventEmitter,
+        costTracker,
+        gateSnapshotStore,
+        invokeReplanner: async (state) => {
+            const prompt = composeReplannerPrompt(state);
+            const { exitCode, output, tokensIn, tokensOut } = await invokeClaudeP(prompt, {
+                mcpConfigPath,
+                model: 'haiku',
+                maxBudgetUsd: 0.01,
+                tools: '',
+                includeMcpConfig: false,
+            });
+            costTracker?.record({ ticketId: 'replanner', columnId: 'pipeline', model: 'haiku', tokensIn, tokensOut, type: 'orchestrator' });
+            if (exitCode !== 0)
+                throw new Error(`Replanner failed`);
+            return parseReplannerResponse(output);
+        },
     };
     // Create orchestrator
     const orchestrator = new PipelineOrchestrator(opts.boardId, projectId, deps);
@@ -346,12 +828,54 @@ export async function runPipeline(client, args) {
         console.error(`Error: Failed to initialize pipeline: ${message}`);
         console.error('Check that the board exists, has pipeline columns configured, and the API is reachable.');
         cleanupMcpConfig(mcpConfigPath);
+        cleanupGateProxyConfigs(pidDir(opts.boardId));
         process.exit(1);
     }
     const columnIds = orchestrator.pipelineColumnIds;
+    // Initialize run memory if any pipeline column has run_memory enabled
+    try {
+        for (const colId of columnIds) {
+            const colScope = await client.get(`/projects/${projectId}/pipeline-context`, { columnId: colId });
+            if (colScope.agent_config?.run_memory) {
+                // Fetch board name for the run memory document title
+                const boardScope = await client.get(`/projects/${projectId}/pipeline-context`, { boardId: opts.boardId });
+                // Resolve a space to store the run memory document — use first available space
+                const spaces = await client.get(`/projects/${projectId}/spaces`);
+                const spaceId = spaces[0]?.id;
+                if (!spaceId) {
+                    logger.orchestrator('Run memory: no spaces found in project — skipping run memory');
+                    console.warn('Warning: Run memory requires at least one document space in the project — skipping.');
+                    break;
+                }
+                runMemory = new RunMemory(opts.boardId, boardScope.board.name, {
+                    createDocument: async (content, title) => {
+                        const result = await client.post(`/projects/${projectId}/spaces/${spaceId}/documents`, { title, content });
+                        return result.id;
+                    },
+                    getDocument: async (docId) => {
+                        const doc = await client.get(`/projects/${projectId}/documents/${docId}`);
+                        return doc.content;
+                    },
+                    updateDocument: async (docId, content) => {
+                        await client.patch(`/projects/${projectId}/documents/${docId}`, { content });
+                    },
+                });
+                await runMemory.initialize();
+                logger.orchestrator(`Run memory initialized (doc=${runMemory.documentId ?? 'none'})`);
+                console.log(`Run memory enabled (document: ${runMemory.documentId ?? 'none'})`);
+                break;
+            }
+        }
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        logger.orchestrator(`Run memory init failed (non-fatal): ${msg}`);
+        console.error(`Warning: Run memory initialization failed: ${msg}`);
+    }
     if (columnIds.length === 0) {
         console.log('No pipeline columns found (columns need has_prompt=true and type !== "done").');
         cleanupMcpConfig(mcpConfigPath);
+        cleanupGateProxyConfigs(pidDir(opts.boardId));
         return;
     }
     console.log(`Discovered ${String(columnIds.length)} pipeline column(s).`);
@@ -372,6 +896,7 @@ export async function runPipeline(client, args) {
         console.log(`MCP config:     ${mcpConfigPath}`);
         console.log('\n[Dry run -- no agents started]');
         cleanupMcpConfig(mcpConfigPath);
+        cleanupGateProxyConfigs(pidDir(opts.boardId));
         return;
     }
     // --- Live mode ---
@@ -383,10 +908,15 @@ export async function runPipeline(client, args) {
         shutdownInProgress = true;
         console.log(`\nReceived ${signal}. Shutting down gracefully...`);
         logger.orchestrator(`Shutdown initiated (${signal})`);
-        wsClient?.stop();
         if (rescanTimer)
             clearInterval(rescanTimer);
         eventQueue?.stop();
+        // Notify browser clients that the pipeline is stopping (before closing WS)
+        wsClient?.send({ type: 'pipeline:stopped', payload: { boardId: opts.boardId } });
+        // Give the WS a moment to flush the stop notification
+        await new Promise(r => setTimeout(r, 200));
+        await eventEmitter.close();
+        wsClient?.stop();
         for (const loop of activeRalphLoops) {
             loop.stop();
         }
@@ -400,14 +930,39 @@ export async function runPipeline(client, args) {
             console.error(`Warning: ${String(activeChildProcesses.size)} child process(es) did not exit. Sending SIGKILL...`);
             for (const child of activeChildProcesses) {
                 try {
-                    if (child.pid)
-                        process.kill(-child.pid, 'SIGKILL');
+                    if (child.pid) {
+                        try {
+                            process.kill(-child.pid, 'SIGKILL');
+                        }
+                        catch {
+                            try {
+                                child.kill('SIGKILL');
+                            }
+                            catch { /* already dead */ }
+                        }
+                    }
+                    else {
+                        try {
+                            child.kill('SIGKILL');
+                        }
+                        catch { /* already dead */ }
+                    }
+                }
+                catch {
+                    // Process already exited
                 }
-                catch { /* ignore */ }
             }
         }
+        // Print cost report
+        if (costTracker) {
+            console.log('\n--- Pipeline Cost Report ---');
+            console.log(costTracker.generateReport(gateConfig.settings?.pricing));
+        }
         cleanupMcpConfig(mcpConfigPath);
+        cleanupGateProxyConfigs(pidDir(opts.boardId));
+        killReaper(reaperPidPath);
         removePidFile(opts.boardId);
+        removeChildManifest(opts.boardId);
         logger.orchestrator('Shutdown complete');
         console.log('Pipeline stopped.');
         process.exit(0);
@@ -424,11 +979,28 @@ export async function runPipeline(client, args) {
             process.exit(1);
         });
     });
+    process.on('SIGHUP', () => {
+        shutdown('SIGHUP').catch((err) => {
+            console.error('Error during shutdown:', err);
+            process.exit(1);
+        });
+    });
     // Clean up orphaned processes from a previous run before starting
     cleanupOrphanedProcesses(opts.boardId);
     // Write PID file
     writePidFile(opts.boardId);
     logger.orchestrator(`PID file written: ${String(process.pid)}`);
+    // Spawn watchdog reaper — kills children if orchestrator dies unexpectedly
+    const reaperPidPath = join(pidDir(opts.boardId), 'reaper.pid');
+    const reaperProcess = spawnReaper({
+        orchestratorPid: process.pid,
+        manifestPath: childManifestPath(opts.boardId),
+        pidFilePath: pidFilePath(opts.boardId),
+        reaperPidPath,
+        mcpConfigPath,
+        pipelineDir: pidDir(opts.boardId),
+    });
+    logger.orchestrator(`Watchdog reaper spawned (PID ${String(reaperProcess.pid ?? 'unknown')})`);
     // Set up event queue and WS client
     let eventQueue = null;
     let wsClient = null;
@@ -446,8 +1018,6 @@ export async function runPipeline(client, args) {
         boardId: opts.boardId,
         projectId,
         onEvent: (wsEvent) => {
-            // Log ALL WS events for debugging
-            logger.orchestrator(`WS raw event: ${wsEvent.type} payload=${JSON.stringify(wsEvent.payload)}`);
             // Map WS events to pipeline events
             const payload = wsEvent.payload;
             // ticket:moved and ticket:created nest the id inside payload.ticket
@@ -458,6 +1028,17 @@ export async function runPipeline(client, args) {
             // ticket:created has payload.columnId; ticket:moved has the new column in ticket.column_id
             const columnId = (typeof payload['columnId'] === 'string' ? payload['columnId'] : null) ??
                 (ticket && typeof ticket['column_id'] === 'string' ? ticket['column_id'] : null);
+            // Handle firing constraint changes — refresh constraint caches
+            if (wsEvent.type === 'firing_constraint:created' ||
+                wsEvent.type === 'firing_constraint:updated' ||
+                wsEvent.type === 'firing_constraint:deleted') {
+                logger.orchestrator(`WS event: ${wsEvent.type} — refreshing constraint caches`);
+                void orchestrator.refreshConstraints().catch((err) => {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    logger.orchestrator(`Constraint cache refresh failed: ${msg}`);
+                });
+                return;
+            }
             if (!ticketId)
                 return;
             const eventType = wsEvent.type;
@@ -510,11 +1091,23 @@ export async function runPipeline(client, args) {
         logger.orchestrator('Once mode: waiting for loops to complete');
         // Poll until no active loops or queued work remain
         await waitForAllLoops(orchestrator);
+        // Print cost report
+        if (costTracker) {
+            console.log('\n--- Pipeline Cost Report ---');
+            console.log(costTracker.generateReport(gateConfig.settings?.pricing));
+        }
+        // Notify browser clients that the pipeline has finished
+        wsClient.send({ type: 'pipeline:stopped', payload: { boardId: opts.boardId } });
+        await new Promise(r => setTimeout(r, 200));
         // Cleanup
+        await eventEmitter.close();
         wsClient.stop();
         eventQueue.stop();
         cleanupMcpConfig(mcpConfigPath);
+        cleanupGateProxyConfigs(pidDir(opts.boardId));
+        killReaper(reaperPidPath);
         removePidFile(opts.boardId);
+        removeChildManifest(opts.boardId);
         logger.orchestrator('Once mode complete. Exiting.');
         console.log('All loops complete. Pipeline exiting.');
     }
@@ -568,7 +1161,7 @@ async function waitForAllLoops(orchestrator, timeoutMs = 4 * 60 * 60 * 1000) {
             return;
         }
         await new Promise((resolve) => setTimeout(resolve, 1000));
-        if (activeRalphLoops.size === 0 && orchestrator.activeLoopCount === 0 && !orchestrator.hasQueuedWork) {
+        if (activeRalphLoops.size === 0 && orchestrator.activeLoopCount === 0 && !orchestrator.hasActiveQueuedWork) {
             consecutiveIdle++;
         }
         else {