@creativeintelligence/abbie 0.1.0

package/src/lib/runner.ts

@@ -0,0 +1,1223 @@
+/**
+ * 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 { type ChildProcess, spawn, spawnSync } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import {
+  createReadStream,
+  createWriteStream,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  statSync,
+  type WriteStream,
+  writeFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { pathToFileURL } from "node:url";
+import type { ActiveSession, AgentType } from "./active-sessions.js";
+import { SessionArtifactStore } from "./session-artifacts.js";
+import { buildSessionResult, type SessionResult } from "./session-result.js";
+
+/**
+ * Runner configuration passed via environment.
+ */
+export interface RunnerConfig {
+  sessionId: string;
+  sessionPath: string;
+  promptPath: string;
+  outputPath: string;
+  resultPath: string;
+  stdoutPath: string;
+  stderrPath: string;
+  agent: AgentType;
+  model?: string;
+}
+
+/**
+ * Exit info written to exit.json.
+ */
+export interface ExitInfo {
+  exitCode: number | null;
+  signal: NodeJS.Signals | null;
+  endedAt: string;
+}
+
+interface BraintrustSpanLike {
+  end(args?: { endTime?: number }): number;
+  flush(): Promise<void>;
+  log(event: {
+    error?: unknown;
+    input?: unknown;
+    metadata?: Record<string, unknown>;
+    output?: unknown;
+  }): void;
+  permalink(): Promise<string>;
+}
+
+interface BraintrustLoggerLike {
+  flush(): Promise<void>;
+  startSpan(args?: {
+    event?: {
+      error?: unknown;
+      input?: unknown;
+      metadata?: Record<string, unknown>;
+      output?: unknown;
+    };
+    name?: string;
+  }): BraintrustSpanLike;
+}
+
+interface BraintrustTracingModuleLike {
+  createBraintrustLogger: (projectNameOrConfig: {
+    apiKey?: string;
+    appUrl?: string;
+    projectName: string;
+  } | string) => BraintrustLoggerLike | null;
+}
+
+function normalizeNonEmpty(value?: string | null): string | undefined {
+  const next = value?.trim();
+  return next ? next : undefined;
+}
+
+function resolveSharedPackagesRoot(): string {
+  return process.env.LNITTMAN_PACKAGES_ROOT || "/Users/luke/Developer/packages";
+}
+
+function readFileUtf8IfExists(path: string): string {
+  try {
+    if (!existsSync(path)) return "";
+    return readFileSync(path, "utf-8");
+  } catch {
+    return "";
+  }
+}
+
+async function loadBraintrustTracingModule(): Promise<BraintrustTracingModuleLike | null> {
+  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 as BraintrustTracingModuleLike;
+      }
+    } catch {
+      // Try next candidate.
+    }
+  }
+
+  return null;
+}
+
+async function traceSessionRunToBraintrust(input: {
+  artifacts: string[];
+  config: RunnerConfig;
+  endedAt: string;
+  exitCode: number | null;
+  outputContent: string;
+  session: ActiveSession;
+  status: SessionResult["status"];
+}): Promise<string | undefined> {
+  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: WriteStream): Promise<void> {
+  return new Promise((resolve, reject) => {
+    // Already done
+    if (stream.destroyed || stream.writableFinished) {
+      resolve();
+      return;
+    }
+
+    let settled = false;
+    const settle = (err?: Error) => {
+      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: Error) => settle(err);
+
+    stream.once("finish", onFinish);
+    stream.once("close", onClose);
+    stream.once("error", onError);
+  });
+}
+
+/**
+ * Parse runner config from environment.
+ */
+export function parseRunnerConfig(env: NodeJS.ProcessEnv = process.env): RunnerConfig | null {
+  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 as AgentType;
+  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: string, data: unknown): void {
+  const tmpPath = `${path}.tmp`;
+  writeFileSync(tmpPath, JSON.stringify(data, null, 2));
+  renameSync(tmpPath, path);
+}
+
+/**
+ * Update session file atomically.
+ */
+function updateSession(sessionPath: string, updates: Partial<ActiveSession>): ActiveSession | null {
+  try {
+    const session: ActiveSession = 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: RunnerConfig,
+  _cwd: string,
+): { command: string; args: string[]; env: Record<string, string>; useStdin: boolean } {
+  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: string): string {
+  // 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"),
+    "", // Other escape sequences
+  );
+  // 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: string): void {
+  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: string): boolean {
+  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: string): string[] {
+  return stdout
+    .split("\n")
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0);
+}
+
+function collectGitArtifacts(cwd: string, startCommitSha?: string): string[] {
+  if (!isGitRepo(cwd)) return [];
+
+  const files = new Set<string>();
+
+  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: {
+  config: RunnerConfig;
+  session: ActiveSession;
+  status: SessionResult["status"];
+  exitCode: number | null;
+  endedAt: string;
+  rawOutput: string;
+  artifacts?: string[];
+  traceUrl?: string;
+}): SessionResult {
+  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: string): string {
+  const logsDir = join(homedir(), ".copilot", "logs");
+  if (!existsSync(logsDir)) return "";
+
+  let entries: { path: string; mtimeMs: number }[] = [];
+  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: RunnerConfig): Promise<number> {
+  const { sessionPath, promptPath, outputPath, resultPath, stdoutPath, stderrPath, agent } = config;
+  const artifactStore = new SessionArtifactStore();
+
+  // Read session to get cwd
+  let session: ActiveSession;
+  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: ReturnType<typeof getAgentSpawnConfig>;
+  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" as const,
+          title: "session:started",
+          content: JSON.stringify({
+            agent,
+            goal: session.goal,
+            cwd,
+          }),
+        }),
+      )
+      .catch(() => {
+        // Best-effort
+      });
+  }
+
+  return new Promise<number>((resolve) => {
+    // Track if promise is already settled (for race conditions)
+    let settled = false;
+    const settleWith = (code: number) => {
+      if (settled) return;
+      settled = true;
+      resolve(code);
+    };
+
+    // Helper: best-effort kill agent (process group if available)
+    const tryKill = (pid: number, signal: NodeJS.Signals) => {
+      try {
+        process.kill(pid, signal);
+        return true;
+      } catch {
+        return false;
+      }
+    };
+
+    const tryKillGroup = (pgid: number, signal: NodeJS.Signals) => {
+      // 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: ChildProcess | undefined;
+
+    // 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: NodeJS.Signals | null = 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: NodeJS.Signals) => {
+      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: ReturnType<typeof createReadStream> | undefined;
+    let stdoutStream: WriteStream | undefined;
+    let stderrStream: WriteStream | undefined;
+    let outputStream: WriteStream | undefined;
+
+    // Helper to handle stream errors - mark session failed but don't kill child
+    const handleStreamError = (streamName: string) => (err: Error) => {
+      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: Promise<void>[] = [];
+          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: 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: SessionResult["status"] = "failed";
+        try {
+          // If user stopped the session (via runner signal handler or external write), preserve "stopped".
+          let currentStatus: ActiveSession["status"] | undefined;
+          try {
+            currentStatus = JSON.parse(readFileSync(sessionPath, "utf-8"))
+              .status as ActiveSession["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: string | undefined;
+        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 as "completed" | "stopped" | "failed",
+              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" as const,
+              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(): Promise<number> {
+  const config = parseRunnerConfig();
+
+  if (!config) {
+    console.error("Runner config not found in environment");
+    return 1;
+  }
+
+  const exitCode = await runAgent(config);
+  return exitCode;
+}