@creativeintelligence/abbie 0.1.0

package/dist/lib/runner.js

@@ -0,0 +1,1034 @@
+/**
+ * Runner/Supervisor process for agent sessions.
+ *
+ * This module implements the "runner" pattern:
+ * - Runner owns the agent child process
+ * - Captures stdout/stderr to log files
+ * - Updates session status on process exit
+ * - Writes canonical *-result.json envelope
+ * - Writes legacy exit/output files for compatibility
+ *
+ * This avoids the broken pattern of:
+ * - detached + unref (CLI exits, close handler dies)
+ * - bun -e inline watcher scripts (syntax issues)
+ */
+import { spawn, spawnSync } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { createReadStream, createWriteStream, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync, } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { SessionArtifactStore } from "./session-artifacts.js";
+import { buildSessionResult } from "./session-result.js";
+function normalizeNonEmpty(value) {
+    const next = value?.trim();
+    return next ? next : undefined;
+}
+function resolveSharedPackagesRoot() {
+    return process.env.LNITTMAN_PACKAGES_ROOT || "/Users/luke/Developer/packages";
+}
+function readFileUtf8IfExists(path) {
+    try {
+        if (!existsSync(path))
+            return "";
+        return readFileSync(path, "utf-8");
+    }
+    catch {
+        return "";
+    }
+}
+async function loadBraintrustTracingModule() {
+    const fallbackPath = pathToFileURL(join(resolveSharedPackagesRoot(), "evals", "dist", "tracing.js")).href;
+    const candidates = ["@lnittman/evals/tracing", fallbackPath];
+    for (const candidate of candidates) {
+        try {
+            const mod = await import(candidate);
+            if (typeof mod?.createBraintrustLogger === "function") {
+                return mod;
+            }
+        }
+        catch {
+            // Try next candidate.
+        }
+    }
+    return null;
+}
+async function traceSessionRunToBraintrust(input) {
+    const apiKey = normalizeNonEmpty(process.env.BRAINTRUST_API_KEY);
+    if (!apiKey)
+        return undefined;
+    const projectName = normalizeNonEmpty(process.env.BRAINTRUST_PROJECT_NAME) ||
+        normalizeNonEmpty(process.env.AGENTS_PROJECT) ||
+        normalizeNonEmpty(input.session.project);
+    if (!projectName)
+        return undefined;
+    const tracing = await loadBraintrustTracingModule();
+    if (!tracing)
+        return undefined;
+    const logger = tracing.createBraintrustLogger({
+        apiKey,
+        appUrl: normalizeNonEmpty(process.env.BRAINTRUST_APP_URL),
+        projectName,
+    });
+    if (!logger)
+        return undefined;
+    const promptContent = readFileUtf8IfExists(input.config.promptPath);
+    const traceId = normalizeNonEmpty(input.session.trace_id) || normalizeNonEmpty(process.env.AGENTS_TRACE_ID);
+    const span = logger.startSpan({
+        name: "abbie.session.run",
+        event: {
+            input: {
+                goal: input.session.goal,
+                prompt: promptContent,
+            },
+            metadata: {
+                agent: input.config.agent,
+                artifactsCount: input.artifacts.length,
+                cwd: input.session.cwd,
+                endedAt: input.endedAt,
+                exitCode: input.exitCode,
+                issue: input.session.issue,
+                model: input.config.model ?? null,
+                outputPath: input.config.outputPath,
+                project: input.session.project,
+                promptPath: input.config.promptPath,
+                resultPath: input.config.resultPath,
+                sessionId: input.config.sessionId,
+                startedAt: input.session.started_at,
+                status: input.status,
+                traceId: traceId ?? null,
+            },
+        },
+    });
+    span.log({
+        ...(input.status === "failed" && input.outputContent.trim().length > 0
+            ? { error: input.outputContent }
+            : {}),
+        output: {
+            artifacts: input.artifacts,
+            raw: input.outputContent,
+        },
+    });
+    span.end();
+    await span.flush();
+    const traceUrl = await span.permalink();
+    await logger.flush();
+    return traceUrl;
+}
+/**
+ * Wait for a write stream to finish/close safely.
+ * Handles: already finished, close without finish, destroyed, errors.
+ */
+function waitForStream(stream) {
+    return new Promise((resolve, reject) => {
+        // Already done
+        if (stream.destroyed || stream.writableFinished) {
+            resolve();
+            return;
+        }
+        let settled = false;
+        const settle = (err) => {
+            if (settled)
+                return;
+            settled = true;
+            stream.removeListener("finish", onFinish);
+            stream.removeListener("close", onClose);
+            stream.removeListener("error", onError);
+            if (err)
+                reject(err);
+            else
+                resolve();
+        };
+        const onFinish = () => settle();
+        const onClose = () => settle(); // close without finish = still done
+        const onError = (err) => settle(err);
+        stream.once("finish", onFinish);
+        stream.once("close", onClose);
+        stream.once("error", onError);
+    });
+}
+/**
+ * Parse runner config from environment.
+ */
+export function parseRunnerConfig(env = process.env) {
+    const sessionId = env.AGENTS_RUNNER_SESSION_ID;
+    const sessionPath = env.AGENTS_RUNNER_SESSION_PATH;
+    const promptPath = env.AGENTS_RUNNER_PROMPT_PATH;
+    const outputPath = env.AGENTS_RUNNER_OUTPUT_PATH;
+    const resultPathFromEnv = env.AGENTS_RUNNER_RESULT_PATH;
+    const stdoutPath = env.AGENTS_RUNNER_STDOUT_PATH;
+    const stderrPath = env.AGENTS_RUNNER_STDERR_PATH;
+    const agent = env.AGENTS_RUNNER_AGENT;
+    const model = env.AGENTS_RUNNER_MODEL;
+    if (!sessionId || !sessionPath || !promptPath || !outputPath || !agent) {
+        return null;
+    }
+    const defaultResultPath = join(dirname(outputPath), `${sessionId}-result.json`);
+    return {
+        sessionId,
+        sessionPath,
+        promptPath,
+        outputPath,
+        resultPath: resultPathFromEnv || defaultResultPath,
+        stdoutPath: stdoutPath || outputPath.replace(/\.json$/, "-stdout.log"),
+        stderrPath: stderrPath || outputPath.replace(/\.json$/, "-stderr.log"),
+        agent,
+        model: model || undefined,
+    };
+}
+/**
+ * Write JSON atomically (write to .tmp, then rename).
+ */
+function writeJsonAtomic(path, data) {
+    const tmpPath = `${path}.tmp`;
+    writeFileSync(tmpPath, JSON.stringify(data, null, 2));
+    renameSync(tmpPath, path);
+}
+/**
+ * Update session file atomically.
+ */
+function updateSession(sessionPath, updates) {
+    try {
+        const session = JSON.parse(readFileSync(sessionPath, "utf-8"));
+        Object.assign(session, updates);
+        writeJsonAtomic(sessionPath, session);
+        return session;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Get agent spawn configuration.
+ */
+function getAgentSpawnConfig(config, _cwd) {
+    const { agent, sessionId, model } = config;
+    switch (agent) {
+        case "claude": {
+            // Claude Code 2.1.50+ has a bug where -p (print/pipe) mode hangs
+            // indefinitely in all non-interactive contexts (stdin pipe, positional
+            // arg, heredoc). The process connects to the API but never produces
+            // output. Interactive mode works fine.
+            //
+            // Workaround: use `pi` as a relay when available. Pi's -p flag works
+            // correctly and can target Claude models via --provider anthropic.
+            // Falls back to direct claude -p if pi is not installed (may hang).
+            // Locate pi binary: try PATH resolution first, then known NVM location
+            const piPathFromWhich = spawnSync("which", ["pi"], { stdio: "pipe", encoding: "utf-8" });
+            const piPath = piPathFromWhich.status === 0
+                ? piPathFromWhich.stdout.trim()
+                : join(homedir(), ".nvm", "versions", "node", "v22.22.0", "bin", "pi");
+            const usePiRelay = existsSync(piPath);
+            if (usePiRelay) {
+                // Relay through pi: reliable non-interactive mode
+                const piArgs = [
+                    "--no-extensions",
+                    "--provider", "anthropic",
+                    "--model", model || "claude-sonnet-4-20250514",
+                    "-p",
+                ];
+                return {
+                    command: piPath,
+                    args: piArgs,
+                    env: {
+                        PI_SESSION_ID: sessionId,
+                        AGENTS_SESSION_ID: sessionId,
+                    },
+                    useStdin: true,
+                };
+            }
+            // Direct claude fallback (may hang in 2.1.50+)
+            const claudeSessionId = randomUUID();
+            const claudePath = join(homedir(), ".local", "bin", "claude");
+            return {
+                command: claudePath,
+                args: [
+                    "-p",
+                    "--dangerously-skip-permissions",
+                    "--output-format",
+                    "text",
+                    "--session-id",
+                    claudeSessionId,
+                ],
+                env: { CLAUDE_SESSION_ID: sessionId },
+                useStdin: true,
+            };
+        }
+        case "codex": {
+            const codexPath = join(homedir(), ".local", "bin", "codex");
+            const codexArgs = [
+                "exec",
+                "-",
+                "--dangerously-bypass-approvals-and-sandbox",
+                "--skip-git-repo-check",
+            ];
+            if (model) {
+                codexArgs.push("--model", model);
+            }
+            // Note: codex 0.98.0's `-o` (--output-last-message) doesn't reliably
+            // write the response file. Instead we capture stdout like all other agents.
+            return {
+                command: codexPath,
+                args: codexArgs,
+                env: { CODEX_SESSION_ID: sessionId },
+                useStdin: true,
+            };
+        }
+        case "copilot": {
+            // Copilot needs prompt via -p flag, not stdin
+            const promptContent = readFileSync(config.promptPath, "utf-8").trim();
+            const copilotArgs = ["-p", promptContent, "--yolo", "--stream", "off"];
+            if (model) {
+                copilotArgs.push("--model", model);
+            }
+            return {
+                command: "copilot",
+                args: copilotArgs,
+                env: { COPILOT_SESSION_ID: sessionId },
+                useStdin: false,
+            };
+        }
+        case "gemini": {
+            // Gemini needs prompt via -p flag, not stdin
+            const promptContent = readFileSync(config.promptPath, "utf-8").trim();
+            const geminiArgs = ["-p", promptContent];
+            if (model) {
+                geminiArgs.push("-m", model);
+            }
+            return {
+                command: "gemini",
+                args: geminiArgs,
+                env: { GEMINI_SESSION_ID: sessionId },
+                useStdin: false,
+            };
+        }
+        case "pi": {
+            // Pi needs prompt via -p flag, not stdin.
+            // Run with extensions disabled to avoid user-local extension crashes
+            // leaking into orchestrated agent sessions.
+            const promptContent = readFileSync(config.promptPath, "utf-8").trim();
+            const piArgs = ["--no-extensions"];
+            if (model) {
+                piArgs.push("--model", model);
+            }
+            else {
+                // Stable default for environments where pi's built-in default model
+                // may not be entitled.
+                piArgs.push("--provider", "google", "--model", "gemini-2.5-flash-lite");
+            }
+            piArgs.push("-p", promptContent);
+            return {
+                command: "pi",
+                args: piArgs,
+                env: { PI_SESSION_ID: sessionId },
+                useStdin: false,
+            };
+        }
+        case "opencode": {
+            // OpenCode supports run subcommand with JSON output
+            const promptContent = readFileSync(config.promptPath, "utf-8").trim();
+            const opencodeArgs = ["run", promptContent, "--format", "json"];
+            if (model) {
+                opencodeArgs.push("-m", model);
+            }
+            return {
+                command: "opencode",
+                args: opencodeArgs,
+                env: { OPENCODE_SESSION_ID: sessionId },
+                useStdin: false,
+            };
+        }
+        case "droid": {
+            // Factory Droid uses -m for message mode
+            const promptContent = readFileSync(config.promptPath, "utf-8").trim();
+            const droidArgs = ["-m", promptContent];
+            if (model) {
+                droidArgs.push("--model", model);
+            }
+            return {
+                command: "droid",
+                args: droidArgs,
+                env: { DROID_SESSION_ID: sessionId },
+                useStdin: false,
+            };
+        }
+        default:
+            throw new Error(`Unknown agent type: ${agent}`);
+    }
+}
+/**
+ * Strip ANSI escape codes and terminal control characters from a string.
+ * Preserves newlines and tabs but removes everything else that would break JSON serialization.
+ */
+function stripControlChars(str) {
+    // Remove ANSI escape sequences (CSI, OSC, etc.)
+    const esc = "\u001b";
+    const bell = "\u0007";
+    const controlChars = "[\\x00-\\x08\\x0b\\x0c\\x0e-\\x1f\\x7f]";
+    let cleaned = str.replace(new RegExp(`${esc}\\[[0-9;]*[A-Za-z]`, "g"), "");
+    cleaned = cleaned.replace(new RegExp(`${esc}\\][^${bell}]*${bell}`, "g"), ""); // OSC sequences
+    cleaned = cleaned.replace(new RegExp(`${esc}[()][AB012]`, "g"), ""); // Character set selection
+    cleaned = cleaned.replace(new RegExp(`${esc}[\\x20-\\x2f][\\x30-\\x7e]`, "g"), "");
+    // Remove remaining control chars (except \n \r \t)
+    cleaned = cleaned.replace(new RegExp(controlChars, "g"), "");
+    return cleaned;
+}
+/**
+ * Clean agent output: remove leading bullet markers and strip terminal control characters.
+ */
+function cleanAgentOutput(outputPath) {
+    if (!existsSync(outputPath))
+        return;
+    try {
+        const raw = readFileSync(outputPath, "utf-8");
+        let cleaned = stripControlChars(raw);
+        // Remove leading copilot-style bullet markers
+        cleaned = cleaned.replace(/^\s*(?:●|○|•)\s*/, "");
+        if (cleaned !== raw) {
+            writeFileSync(outputPath, cleaned);
+        }
+    }
+    catch {
+        // Best-effort cleanup
+    }
+}
+function isGitRepo(cwd) {
+    const result = spawnSync("git", ["-C", cwd, "rev-parse", "--is-inside-work-tree"], {
+        stdio: ["ignore", "pipe", "ignore"],
+        encoding: "utf-8",
+    });
+    return result.status === 0 && result.stdout.trim() === "true";
+}
+function parseGitFileList(stdout) {
+    return stdout
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0);
+}
+function collectGitArtifacts(cwd, startCommitSha) {
+    if (!isGitRepo(cwd))
+        return [];
+    const files = new Set();
+    const diffArgs = startCommitSha
+        ? ["-C", cwd, "diff", "--name-only", "--relative", startCommitSha]
+        : ["-C", cwd, "diff", "--name-only", "--relative"];
+    const diffResult = spawnSync("git", diffArgs, {
+        stdio: ["ignore", "pipe", "ignore"],
+        encoding: "utf-8",
+    });
+    if (diffResult.status === 0) {
+        for (const file of parseGitFileList(diffResult.stdout)) {
+            files.add(file);
+        }
+    }
+    const untrackedResult = spawnSync("git", ["-C", cwd, "ls-files", "--others", "--exclude-standard"], {
+        stdio: ["ignore", "pipe", "ignore"],
+        encoding: "utf-8",
+    });
+    if (untrackedResult.status === 0) {
+        for (const file of parseGitFileList(untrackedResult.stdout)) {
+            files.add(file);
+        }
+    }
+    return Array.from(files).sort();
+}
+function buildResultEnvelope(input) {
+    return buildSessionResult({
+        sessionId: input.config.sessionId,
+        agent: input.config.agent,
+        status: input.status,
+        exitCode: input.exitCode,
+        startedAt: input.session.started_at,
+        endedAt: input.endedAt,
+        rawOutput: input.rawOutput,
+        artifacts: input.artifacts,
+        traceUrl: input.traceUrl,
+    });
+}
+function readCopilotFailureDiagnostic(startedAtIso) {
+    const logsDir = join(homedir(), ".copilot", "logs");
+    if (!existsSync(logsDir))
+        return "";
+    let entries = [];
+    try {
+        entries = readdirSync(logsDir)
+            .filter((name) => name.endsWith(".log") && name.startsWith("process-"))
+            .map((name) => {
+            const path = join(logsDir, name);
+            const mtimeMs = statSync(path).mtimeMs;
+            return { path, mtimeMs };
+        })
+            .sort((a, b) => b.mtimeMs - a.mtimeMs)
+            .slice(0, 5);
+    }
+    catch {
+        return "";
+    }
+    if (entries.length === 0)
+        return "";
+    const startedAtMs = Date.parse(startedAtIso);
+    for (const entry of entries) {
+        if (Number.isFinite(startedAtMs) && entry.mtimeMs < startedAtMs - 60_000) {
+            continue;
+        }
+        try {
+            const content = readFileSync(entry.path, "utf-8");
+            const lines = content
+                .split(/\r?\n/)
+                .map((line) => line.trim())
+                .filter(Boolean);
+            if (lines.length === 0)
+                continue;
+            const signalLines = lines.filter((line) => line.includes("Error loading models") ||
+                line.includes("Failed to list models") ||
+                line.includes("OAuth authentication failed") ||
+                line.includes("requires authentication"));
+            const selected = signalLines.length > 0 ? signalLines.slice(-4) : lines.slice(-4);
+            if (selected.length === 0)
+                continue;
+            return [
+                "copilot exited without output.",
+                `diagnostic source: ${entry.path}`,
+                ...selected,
+            ].join("\n");
+        }
+        catch {
+            // Try next candidate
+        }
+    }
+    return "";
+}
+/**
+ * Run the agent as a supervised child process.
+ * This function is called by the runner process.
+ */
+export async function runAgent(config) {
+    const { sessionPath, promptPath, outputPath, resultPath, stdoutPath, stderrPath, agent } = config;
+    const artifactStore = new SessionArtifactStore();
+    // Read session to get cwd
+    let session;
+    try {
+        session = JSON.parse(readFileSync(sessionPath, "utf-8"));
+    }
+    catch (err) {
+        console.error(`Failed to read session: ${err}`);
+        const endedAt = new Date().toISOString();
+        writeJsonAtomic(resultPath, buildSessionResult({
+            sessionId: config.sessionId,
+            agent: config.agent,
+            status: "failed",
+            exitCode: 1,
+            startedAt: endedAt,
+            endedAt,
+            rawOutput: "",
+            artifacts: [],
+        }));
+        return 1;
+    }
+    const cwd = session.cwd;
+    // Ensure output directories exist (including stderr which may differ)
+    try {
+        mkdirSync(dirname(outputPath), { recursive: true });
+        mkdirSync(dirname(resultPath), { recursive: true });
+        mkdirSync(dirname(stdoutPath), { recursive: true });
+        mkdirSync(dirname(stderrPath), { recursive: true });
+    }
+    catch (err) {
+        console.error(`Failed to create output directories: ${err}`);
+        updateSession(sessionPath, { status: "failed", exit_code: 1 });
+        const endedAt = new Date().toISOString();
+        writeJsonAtomic(resultPath, buildResultEnvelope({
+            config,
+            session,
+            status: "failed",
+            exitCode: 1,
+            endedAt,
+            rawOutput: "",
+            artifacts: [],
+        }));
+        return 1;
+    }
+    // Get spawn configuration
+    let spawnConfig;
+    try {
+        spawnConfig = getAgentSpawnConfig(config, cwd);
+    }
+    catch (err) {
+        console.error(`Failed to get agent spawn config: ${err}`);
+        updateSession(sessionPath, { status: "failed", exit_code: 1 });
+        const endedAt = new Date().toISOString();
+        writeJsonAtomic(resultPath, buildResultEnvelope({
+            config,
+            session,
+            status: "failed",
+            exitCode: 1,
+            endedAt,
+            rawOutput: "",
+            artifacts: collectGitArtifacts(cwd, session.start_commit_sha),
+        }));
+        return 1;
+    }
+    // Ensure PATH includes user bin directories
+    const localBin = join(homedir(), ".local", "bin");
+    const pathWithLocalBin = process.env.PATH?.includes(localBin)
+        ? process.env.PATH
+        : `${localBin}:${process.env.PATH ?? ""}`;
+    // Update session to running with our PID (runner PID is stable)
+    updateSession(sessionPath, {
+        status: "running",
+        pid: process.pid,
+        runner_pid: process.pid,
+    });
+    // Emit session:started progress event (best-effort, non-blocking)
+    const traceIdForLifecycle = process.env.AGENTS_TRACE_ID;
+    if (traceIdForLifecycle) {
+        import("@abbie/sdk/convex")
+            .then(({ api: cbApi, getHttpClient }) => getHttpClient().mutation(cbApi.contextBus.publish, {
+            traceId: traceIdForLifecycle,
+            sessionId: config.sessionId,
+            project: process.env.AGENTS_PROJECT || session.project,
+            type: "progress",
+            title: "session:started",
+            content: JSON.stringify({
+                agent,
+                goal: session.goal,
+                cwd,
+            }),
+        }))
+            .catch(() => {
+            // Best-effort
+        });
+    }
+    return new Promise((resolve) => {
+        // Track if promise is already settled (for race conditions)
+        let settled = false;
+        const settleWith = (code) => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(code);
+        };
+        // Helper: best-effort kill agent (process group if available)
+        const tryKill = (pid, signal) => {
+            try {
+                process.kill(pid, signal);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        };
+        const tryKillGroup = (pgid, signal) => {
+            // Negative PID targets the process group on POSIX; not supported on Windows.
+            if (process.platform === "win32")
+                return false;
+            try {
+                process.kill(-pgid, signal);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        };
+        let child;
+        // Forward termination signals to the agent so `abbie session stop` doesn't orphan it.
+        // Install handlers BEFORE spawning to avoid races where the runner dies before forwarding.
+        let requestedSignal = null;
+        let signalForwarded = false;
+        let killEscalationScheduled = false;
+        const forwardIfPossible = () => {
+            if (signalForwarded || !requestedSignal)
+                return;
+            const pid = child?.pid;
+            if (!pid)
+                return;
+            signalForwarded = true;
+            // Best-effort: signal the entire agent process group first, then the PID.
+            tryKillGroup(pid, requestedSignal);
+            tryKill(pid, requestedSignal);
+            // Escalate if the agent doesn't exit promptly.
+            if (!killEscalationScheduled) {
+                killEscalationScheduled = true;
+                const killDelayMs = 5000;
+                const killTimer = setTimeout(() => {
+                    if (settled || child?.exitCode !== null)
+                        return;
+                    tryKillGroup(pid, "SIGKILL");
+                    tryKill(pid, "SIGKILL");
+                }, killDelayMs);
+                killTimer.unref();
+            }
+        };
+        const requestStop = (signal) => {
+            if (requestedSignal)
+                return;
+            requestedSignal = signal;
+            // Mark session as stopped early so other tools reflect intent.
+            updateSession(sessionPath, { status: "stopped" });
+            forwardIfPossible();
+        };
+        process.once("SIGTERM", () => requestStop("SIGTERM"));
+        process.once("SIGINT", () => requestStop("SIGINT"));
+        // Spawn the agent. `detached: true` makes the agent its own process group leader (PGID=PID),
+        // allowing us to reliably kill the whole subtree (agent + grandchildren) via `kill(-pid)`.
+        child = spawn(spawnConfig.command, spawnConfig.args, {
+            cwd,
+            env: {
+                ...process.env,
+                ...spawnConfig.env,
+                // Unset CLAUDECODE so spawned claude sessions don't refuse to start
+                // (Claude Code blocks nested sessions unless this env var is cleared)
+                CLAUDECODE: undefined,
+                PATH: pathWithLocalBin,
+                AGENTS_SESSION_ID: config.sessionId,
+                AGENTS_PROJECT: session.project,
+                AGENTS_TRACE_ID: session.trace_id || "",
+            },
+            detached: true,
+            stdio: spawnConfig.useStdin ? ["pipe", "pipe", "pipe"] : ["ignore", "pipe", "pipe"],
+        });
+        // CRITICAL: Attach error handler IMMEDIATELY after spawn, before any pid check.
+        // This catches ENOENT, EACCES, and other spawn failures.
+        child.once("error", (err) => {
+            console.error(`Spawn error: ${err}`);
+            updateSession(sessionPath, { status: "failed", exit_code: 1 });
+            const endedAt = new Date().toISOString();
+            writeJsonAtomic(resultPath, buildResultEnvelope({
+                config,
+                session,
+                status: "failed",
+                exitCode: 1,
+                endedAt,
+                rawOutput: String(err),
+                artifacts: collectGitArtifacts(cwd, session.start_commit_sha),
+            }));
+            settleWith(1);
+        });
+        // Check for immediate spawn failure (synchronous)
+        // Note: The 'error' handler above catches async spawn failures
+        if (!child.pid) {
+            // Spawn failed synchronously - error handler will fire shortly
+            // Don't resolve here - let the error handler do it
+            return;
+        }
+        // Update session with actual agent PID (also PGID on POSIX due to detached: true)
+        updateSession(sessionPath, { agent_pid: child.pid });
+        // If a stop signal arrived before spawn completed, forward it now that we have a PID.
+        forwardIfPossible();
+        // Create streams with error handlers
+        let promptStream;
+        let stdoutStream;
+        let stderrStream;
+        let outputStream;
+        // Helper to handle stream errors - mark session failed but don't kill child
+        const handleStreamError = (streamName) => (err) => {
+            console.error(`${streamName} stream error: ${err.message}`);
+            // Don't fail session here - let child exit handler determine final status
+        };
+        // Pipe stdin from prompt file if needed
+        if (spawnConfig.useStdin && child.stdin) {
+            try {
+                promptStream = createReadStream(promptPath);
+                promptStream.on("error", (err) => {
+                    console.error(`Prompt stream error: ${err.message}`);
+                    // Can't read prompt - kill the child
+                    tryKillGroup(child.pid, "SIGTERM");
+                    tryKill(child.pid, "SIGTERM");
+                });
+                promptStream.pipe(child.stdin);
+            }
+            catch (err) {
+                console.error(`Failed to create prompt stream: ${err}`);
+                tryKillGroup(child.pid, "SIGTERM");
+                tryKill(child.pid, "SIGTERM");
+            }
+        }
+        // Capture stdout to file (and to output for non-codex agents)
+        try {
+            stdoutStream = createWriteStream(stdoutPath);
+            stdoutStream.on("error", handleStreamError("stdout"));
+            child.stdout?.pipe(stdoutStream);
+        }
+        catch (err) {
+            console.error(`Failed to create stdout stream: ${err}`);
+        }
+        // Capture stdout as agent output (response file)
+        try {
+            outputStream = createWriteStream(outputPath);
+            outputStream.on("error", handleStreamError("output"));
+            child.stdout?.pipe(outputStream);
+        }
+        catch (err) {
+            console.error(`Failed to create output stream: ${err}`);
+        }
+        // Capture stderr to file
+        try {
+            stderrStream = createWriteStream(stderrPath);
+            stderrStream.on("error", handleStreamError("stderr"));
+            child.stderr?.pipe(stderrStream);
+        }
+        catch (err) {
+            console.error(`Failed to create stderr stream: ${err}`);
+        }
+        // Handle process exit
+        child.on("close", async (code, signal) => {
+            const exitCode = code ?? (signal ? 1 : 0);
+            const endedAt = new Date().toISOString();
+            // Wrap entire handler in try/finally to ensure we always resolve
+            try {
+                // Wait for all streams to finish writing before checking output
+                // Only wait for streams that were successfully created
+                try {
+                    const streamWaits = [];
+                    if (stdoutStream)
+                        streamWaits.push(waitForStream(stdoutStream));
+                    if (stderrStream)
+                        streamWaits.push(waitForStream(stderrStream));
+                    if (outputStream)
+                        streamWaits.push(waitForStream(outputStream));
+                    if (streamWaits.length > 0) {
+                        await Promise.all(streamWaits);
+                    }
+                }
+                catch (streamErr) {
+                    console.error(`Stream flush error: ${streamErr}`);
+                }
+                // Write exit info (wrapped in try/catch)
+                try {
+                    const exitPath = outputPath.replace(/\.json$/, "-exit.json");
+                    const exitInfo = {
+                        exitCode,
+                        signal,
+                        endedAt,
+                    };
+                    writeJsonAtomic(exitPath, exitInfo);
+                }
+                catch (exitErr) {
+                    console.error(`Failed to write exit info: ${exitErr}`);
+                }
+                // Clean agent output: strip control chars and bullet markers
+                cleanAgentOutput(outputPath);
+                let outputContent = "";
+                if (existsSync(outputPath)) {
+                    outputContent = readFileSync(outputPath, "utf-8");
+                }
+                // Fallback: surface stderr if stdout payload is empty.
+                if (outputContent.trim().length === 0 && existsSync(stderrPath)) {
+                    const stderrContent = readFileSync(stderrPath, "utf-8").trim();
+                    if (stderrContent.length > 0) {
+                        outputContent = stderrContent;
+                    }
+                }
+                // Copilot often exits with code 1 and empty stdio when auth/model lookup fails.
+                // Bubble a readable diagnostic from ~/.copilot/logs into the result envelope.
+                if (outputContent.trim().length === 0 && agent === "copilot") {
+                    const diagnostic = readCopilotFailureDiagnostic(session.started_at);
+                    if (diagnostic) {
+                        outputContent = diagnostic;
+                    }
+                }
+                // Determine final status (wrapped in try/catch)
+                let status = "failed";
+                try {
+                    // If user stopped the session (via runner signal handler or external write), preserve "stopped".
+                    let currentStatus;
+                    try {
+                        currentStatus = JSON.parse(readFileSync(sessionPath, "utf-8"))
+                            .status;
+                    }
+                    catch {
+                        // Best-effort only
+                    }
+                    if (currentStatus === "stopped" || requestedSignal) {
+                        status = "stopped";
+                    }
+                    else {
+                        const hasOutput = outputContent.trim().length > 0;
+                        status = exitCode === 0 && hasOutput ? "completed" : "failed";
+                    }
+                }
+                catch (readErr) {
+                    console.error(`Failed to check output: ${readErr}`);
+                }
+                const artifacts = collectGitArtifacts(cwd, session.start_commit_sha);
+                const braintrustConfigured = Boolean(normalizeNonEmpty(process.env.BRAINTRUST_API_KEY));
+                const braintrustProject = normalizeNonEmpty(process.env.BRAINTRUST_PROJECT_NAME) ||
+                    normalizeNonEmpty(process.env.AGENTS_PROJECT) ||
+                    normalizeNonEmpty(session.project) ||
+                    null;
+                let braintrustTraceUrl;
+                try {
+                    braintrustTraceUrl = await traceSessionRunToBraintrust({
+                        artifacts,
+                        config,
+                        endedAt,
+                        exitCode,
+                        outputContent,
+                        session,
+                        status,
+                    });
+                }
+                catch (traceErr) {
+                    const message = traceErr instanceof Error ? traceErr.message : String(traceErr);
+                    console.error(`Braintrust trace logging failed: ${message}`);
+                }
+                if (braintrustTraceUrl) {
+                    updateSession(sessionPath, { trace_url: braintrustTraceUrl });
+                }
+                const sessionResult = buildResultEnvelope({
+                    config,
+                    session,
+                    status,
+                    exitCode,
+                    endedAt,
+                    rawOutput: outputContent,
+                    artifacts,
+                    traceUrl: braintrustTraceUrl,
+                });
+                // Write canonical result envelope.
+                writeJsonAtomic(resultPath, sessionResult);
+                // Update session status
+                updateSession(sessionPath, {
+                    status,
+                    exit_code: exitCode,
+                    ...(braintrustTraceUrl ? { trace_url: braintrustTraceUrl } : {}),
+                });
+                try {
+                    artifactStore.markComplete(config.sessionId, {
+                        status,
+                        exitCode,
+                        outputPath,
+                    });
+                }
+                catch {
+                    // Best-effort: active session files remain source of truth.
+                }
+                // Publish session output as artifact to contextBus (continuity substrate).
+                // Best-effort: never block exit.
+                const traceId = process.env.AGENTS_TRACE_ID;
+                if (traceId && status === "completed") {
+                    try {
+                        const outputForContext = sessionResult.output.raw.trim();
+                        if (outputForContext) {
+                            // Truncate to contextBus recommended limit (~2KB content)
+                            const maxContent = 2000;
+                            const content = outputForContext.length > maxContent
+                                ? `${outputForContext.slice(0, maxContent - 50)}\n\n[truncated — full output at ${outputPath}]`
+                                : outputForContext;
+                            // Extract structured summary from output
+                            const filesModified = [
+                                ...new Set(outputForContext.match(/(?:^|\s)(?:created?|modif(?:ied|y)|edited?|updated?|wrote|deleted?)\s+[`'"]*([^\s`'"]+\.\w{1,6})[`'":]*/gim) || []),
+                            ]
+                                .map((m) => m.replace(/^.*?([^\s`'"]+\.\w{1,6}).*$/, "$1"))
+                                .slice(0, 20);
+                            const hasOutputContract = /\{[\s\S]*"status"[\s\S]*"confidence"[\s\S]*\}/.test(outputForContext.slice(-500));
+                            const { api: cbApi, getHttpClient } = await import("@abbie/sdk/convex");
+                            await getHttpClient().mutation(cbApi.contextBus.publish, {
+                                traceId,
+                                sessionId: config.sessionId,
+                                project: process.env.AGENTS_PROJECT || session.project,
+                                type: "artifact",
+                                title: session.goal ? session.goal.slice(0, 200) : `${agent} session output`,
+                                content,
+                                metadata: {
+                                    agent,
+                                    project: session.project,
+                                    sessionId: config.sessionId,
+                                    outputPath,
+                                    exitCode,
+                                    filesModified: filesModified.length > 0 ? filesModified : artifacts.slice(0, 20),
+                                    hasOutputContract,
+                                    resultPath,
+                                    braintrustConfigured,
+                                    braintrustProject,
+                                    braintrustTraceCaptured: Boolean(braintrustTraceUrl),
+                                    ...(braintrustTraceUrl ? { traceUrl: braintrustTraceUrl } : {}),
+                                },
+                            });
+                        }
+                    }
+                    catch {
+                        // Best-effort: contextBus publish must never prevent session completion
+                    }
+                }
+                // Update Convex session with terminal status + metadata (best-effort)
+                if (traceId) {
+                    try {
+                        const { getHttpClient, api } = await import("@abbie/sdk/convex");
+                        const client = getHttpClient();
+                        // Read output excerpt for metadata
+                        let outputExcerpt = "";
+                        const raw = sessionResult.output.raw.trim();
+                        outputExcerpt = raw.length > 500 ? raw.slice(0, 500) : raw;
+                        // Read prompt excerpt
+                        let promptExcerpt = "";
+                        if (existsSync(config.promptPath)) {
+                            const raw = readFileSync(config.promptPath, "utf-8").trim();
+                            promptExcerpt = raw.length > 500 ? raw.slice(0, 500) : raw;
+                        }
+                        await client.mutation(api.sessions.update, {
+                            sessionId: config.sessionId,
+                            status: status,
+                            endedAt: Date.now(),
+                            ...(braintrustTraceUrl ? { traceUrl: braintrustTraceUrl } : {}),
+                            metadata: {
+                                outputExcerpt,
+                                promptExcerpt,
+                                exitCode,
+                                resultPath,
+                                artifacts: artifacts.slice(0, 50),
+                                outputTruncated: sessionResult.output.truncated,
+                                braintrustConfigured,
+                                braintrustProject,
+                                braintrustTraceCaptured: Boolean(braintrustTraceUrl),
+                                ...(braintrustTraceUrl
+                                    ? { trace_url: braintrustTraceUrl, traceUrl: braintrustTraceUrl }
+                                    : {}),
+                            },
+                        });
+                    }
+                    catch {
+                        // Best-effort: daemon backup sync handles this
+                    }
+                }
+                // Emit session lifecycle event (completed/failed/stopped)
+                if (traceId) {
+                    try {
+                        const { api: cbApi, getHttpClient } = await import("@abbie/sdk/convex");
+                        await getHttpClient().mutation(cbApi.contextBus.publish, {
+                            traceId,
+                            sessionId: config.sessionId,
+                            project: process.env.AGENTS_PROJECT || session.project,
+                            type: "progress",
+                            title: `session:${status}`,
+                            content: JSON.stringify({ agent, exitCode, status }),
+                        });
+                    }
+                    catch {
+                        // Best-effort
+                    }
+                }
+            }
+            finally {
+                // Always resolve, even if something above threw
+                settleWith(exitCode);
+            }
+        });
+    });
+}
+/**
+ * Main entry point for runner process.
+ * Called by `abbie session run <sessionId>`.
+ *
+ * Returns the exit code. The caller (CLI command) should set process.exitCode
+ * rather than calling process.exit() directly, to allow streams to flush.
+ */
+export async function runnerMain() {
+    const config = parseRunnerConfig();
+    if (!config) {
+        console.error("Runner config not found in environment");
+        return 1;
+    }
+    const exitCode = await runAgent(config);
+    return exitCode;
+}