@creativeintelligence/abbie 0.1.4 → 0.1.5

package/src/lib/active-sessions.ts

@@ -1,1486 +0,0 @@
-import { execSync, spawn, spawnSync } from "node:child_process";
-import { randomBytes } from "node:crypto";
-import {
-  existsSync,
-  mkdirSync,
-  readdirSync,
-  readFileSync,
-  renameSync,
-  unlinkSync,
-  writeFileSync,
-} from "node:fs";
-import { homedir } from "node:os";
-import { join } from "node:path";
-import {
-  findProjectPath,
-  getConfigEnvironment,
-  getPromptEnhancements,
-  type LoadedConfig,
-  loadConfigFromPath,
-} from "./config-loader.js";
-import { getContractTemplate } from "./contracts.js";
-import { getDeviceId } from "./device.js";
-import { createEvent, EventStore, generateSessionId } from "./events.js";
-import {
-  type ReinjectMode,
-  type SessionArtifactStatus,
-  SessionArtifactStore,
-} from "./session-artifacts.js";
-import { getSessionLogPaths, readSessionResult, type SessionResult } from "./session-result.js";
-import { AGENTS, Agent, type AgentType, DEFAULT_AGENT, isValidAgent } from "./types.js";
-
-/**
- * Generate a trace ID for event correlation.
- * Format: tr_{24 hex chars} (e.g., tr_a1b2c3d4e5f6a1b2c3d4e5f6)
- */
-export function generateTraceId(): string {
-  return `tr_${randomBytes(12).toString("hex")}`;
-}
-
-/**
- * Get or create a trace ID from environment or generate new.
- */
-export function getOrCreateTraceId(explicit?: string): string {
-  if (explicit) return explicit;
-  if (process.env.AGENTS_TRACE_ID) return process.env.AGENTS_TRACE_ID;
-  return generateTraceId();
-}
-
-// Re-export from types.ts for backwards compatibility
-export { Agent, type AgentType, AGENTS, isValidAgent, DEFAULT_AGENT };
-
-/**
- * Deprecated alias for backwards compatibility.
- */
-export type ActiveAgentType = AgentType;
-
-/**
- * Active session state stored on disk.
- */
-export interface ActiveSession {
-  session_id: string;
-  agent: AgentType;
-  project: string;
-  goal: string;
-  issue?: string;
-  cwd: string;
-  /**
-   * Runner PID (supervisor process).
-   *
-   * Historical note: `pid` used to be overwritten by the runner with the agent PID,
-   * which made stop semantics ambiguous. `pid` is now intended to remain the runner PID.
-   */
-  pid: number;
-  /** Runner PID (explicit field for clarity) */
-  runner_pid?: number;
-  /**
-   * Agent PID (child process).
-   *
-   * On POSIX systems the runner spawns the agent with `detached: true`, so `agent_pid`
-   * is also the agent process group ID (PGID). This allows killing the whole tree via
-   * `process.kill(-agent_pid, signal)`.
-   */
-  agent_pid?: number;
-  started_at: string;
-  status: "running" | "completed" | "failed" | "stopped";
-  exit_code?: number;
-  prompt_path?: string;
-  output_path?: string;
-  result_path?: string;
-  stdout_path?: string;
-  stderr_path?: string;
-  /** Read-only mode - no writes allowed */
-  read_only?: boolean;
-  /** Trace ID for event correlation */
-  trace_id?: string;
-  /** Braintrust trace URL when available */
-  trace_url?: string;
-  /** Parent session that spawned this one */
-  parent_session_id?: string;
-  /** Tmux pane ID when spawned in terminal mode */
-  pane_id?: string;
-  /** How this session was spawned */
-  spawn_mode?: "terminal" | "headless" | "nvim-terminal";
-  /** Nvim server address for legacy nvim-terminal sessions. */
-  nvim_server_addr?: string;
-  /** Git HEAD sha captured at session start (for file provenance tracking) */
-  start_commit_sha?: string;
-}
-
-/**
- * Options for starting a session.
- */
-export interface StartSessionOptions {
-  agent: AgentType;
-  project: string;
-  goal: string;
-  issue?: string;
-  cwd?: string;
-  /** Path to prompt file (instead of goal string) */
-  promptFile?: string;
-  /** Read-only mode - inject contract forbidding writes */
-  readOnly?: boolean;
-  /** Explicit trace ID (defaults to AGENTS_TRACE_ID or generates new) */
-  traceId?: string;
-  /** Parent session ID for hierarchy tracking */
-  parentSessionId?: string;
-  /** Prior session IDs to include as prompt context */
-  reuseSessionIds?: string[];
-  /** Reinject mode for prior session artifacts */
-  reinjectMode?: ReinjectMode;
-  /** Override default model for the agent */
-  model?: string;
-  /** If true, inject recent file_activity from contextBus as prior context (default: true) */
-  autoContext?: boolean;
-  /** If true, use runner pattern and block until complete */
-  awaitCompletion?: boolean;
-  /** If true, spawn as headless subprocess (no tmux window). Default: false (terminal mode). */
-  headless?: boolean;
-  /** Tmux session name for terminal mode. Defaults to "abbie" to avoid hijacking personal sessions. */
-  tmuxSession?: string;
-  /** Skill names to route the agent toward (injected as <skill> blocks) */
-  skills?: string[];
-}
-
-/**
- * Result from starting a session.
- */
-export interface StartSessionResult {
-  session_id: string;
-  pid: number;
-  prompt_path: string;
-  output_path: string;
-  result_path: string;
-  status: "spawned" | "failed";
-  error?: string;
-  /** Trace ID for event correlation */
-  trace_id: string;
-  /** Whether session is read-only */
-  read_only: boolean;
-}
-
-/** Best-effort git rev-parse HEAD in a directory. Returns undefined if not a git repo. */
-function getHeadSha(cwd: string): string | undefined {
-  try {
-    return execSync("git rev-parse HEAD", { cwd, timeout: 3000, stdio: "pipe" }).toString().trim();
-  } catch {
-    return undefined;
-  }
-}
-
-/**
- * Active session manager - spawns and tracks running agents.
- */
-export class ActiveSessionManager {
-  private basePath: string;
-  private promptsPath: string;
-  private eventStore: EventStore;
-  private artifactStore: SessionArtifactStore;
-
-  constructor(basePath?: string) {
-    this.basePath = basePath || join(homedir(), ".abbie", "active-sessions");
-    this.promptsPath = join(homedir(), ".abbie", "prompts");
-    this.eventStore = new EventStore();
-    this.artifactStore = new SessionArtifactStore();
-
-    if (!existsSync(this.basePath)) {
-      mkdirSync(this.basePath, { recursive: true });
-    }
-    if (!existsSync(this.promptsPath)) {
-      mkdirSync(this.promptsPath, { recursive: true });
-    }
-  }
-
-  /**
-   * Expand tilde in path to home directory.
-   */
-  private expandTilde(path: string): string {
-    if (path.startsWith("~/")) {
-      return join(homedir(), path.slice(2));
-    }
-    if (path === "~") {
-      return homedir();
-    }
-    return path;
-  }
-
-  /**
-   * Start a new agent session using the runner/supervisor pattern.
-   *
-   * The runner pattern ensures reliable session completion:
-   * - For --await mode: Runner runs in foreground, we wait for it
-   * - For background mode: Runner is detached, handles its own lifecycle
-   *
-   * The runner:
-   * - Owns the agent child process
-   * - Captures stdout/stderr to log files
-   * - Updates session status on process exit
-   * - Writes result.json atomically
-   */
-  async start(options: StartSessionOptions): Promise<StartSessionResult> {
-    // Resolve working directory - use config if cwd not provided
-    let rawCwd = options.cwd;
-    let loadedConfig: LoadedConfig | undefined;
-
-    if (!rawCwd) {
-      // Try to find project path from config
-      const projectPath = findProjectPath(options.project);
-      if (projectPath) {
-        rawCwd = projectPath;
-        loadedConfig = loadConfigFromPath(projectPath);
-      } else {
-        rawCwd = process.cwd();
-      }
-    } else {
-      // Load config from provided cwd
-      loadedConfig = loadConfigFromPath(rawCwd);
-    }
-
-    const cwd = this.expandTilde(rawCwd);
-    const sessionId = generateSessionId(options.project);
-    const traceId = getOrCreateTraceId(options.traceId);
-    const readOnly = options.readOnly ?? false;
-    const reinjectMode: ReinjectMode = options.reinjectMode ?? "off";
-    const reuseSessionIds = options.reuseSessionIds ?? [];
-    const reinjectionContext = this.artifactStore.buildReinjectionContext(
-      reuseSessionIds,
-      reinjectMode,
-    );
-
-    // Get config-derived values
-    const configEnv = loadedConfig ? getConfigEnvironment(loadedConfig.config) : {};
-    const promptEnhancements = loadedConfig ? getPromptEnhancements(loadedConfig) : "";
-
-    // Prepare prompt file
-    const promptPath = join(this.promptsPath, `${sessionId}.md`);
-    const { outputPath, resultPath, stdoutPath, stderrPath } = getSessionLogPaths(
-      sessionId,
-      this.promptsPath,
-    );
-
-    // Auto-context: fetch recent file_activity from contextBus (opt-out via --no-auto-context)
-    const fileProvenance =
-      options.autoContext !== false ? await this.getFileProvenanceContext(options.project) : "";
-
-    if (options.promptFile && existsSync(options.promptFile)) {
-      // Copy prompt file - optionally prepend read-only contract, config, and awareness
-      let content = readFileSync(options.promptFile, "utf-8");
-      if (readOnly) {
-        content = this.prependReadOnlyContract(content);
-      }
-      const awareness = this.getWorkspaceAwareness(cwd, sessionId);
-      if (awareness) {
-        content = `${awareness}${content}`;
-      }
-      if (fileProvenance) {
-        content = `${fileProvenance}${content}`;
-      }
-      if (reinjectionContext) {
-        content = `${reinjectionContext}${content}`;
-      }
-      if (promptEnhancements) {
-        content = `${promptEnhancements}\n${content}`;
-      }
-      const skillRouting = this.buildSkillRouting(options.skills);
-      if (skillRouting) {
-        content = `${content}\n${skillRouting}`;
-      }
-      writeFileSync(promptPath, content);
-    } else {
-      // Build prompt from goal with workspace awareness
-      const awareness = this.getWorkspaceAwareness(cwd, sessionId);
-      const prompt = this.buildPrompt(
-        options,
-        readOnly,
-        promptEnhancements,
-        awareness,
-        reinjectionContext,
-        fileProvenance,
-      );
-      writeFileSync(promptPath, prompt);
-    }
-
-    // Capture HEAD sha at spawn time for file provenance tracking
-    const startCommitSha = getHeadSha(cwd);
-
-    // Create session record BEFORE spawning runner
-    const session: ActiveSession = {
-      session_id: sessionId,
-      agent: options.agent,
-      project: options.project,
-      goal: options.goal,
-      issue: options.issue,
-      cwd,
-      pid: 0, // Will be updated by runner
-      started_at: new Date().toISOString(),
-      status: "running",
-      prompt_path: promptPath,
-      output_path: outputPath,
-      result_path: resultPath,
-      stdout_path: stdoutPath,
-      stderr_path: stderrPath,
-      read_only: readOnly,
-      trace_id: traceId,
-      parent_session_id: options.parentSessionId,
-      start_commit_sha: startCommitSha,
-    };
-
-    this.saveSession(session);
-    this.saveSessionArtifactStart(session);
-
-    // Best-effort Convex write for immediate visibility (daemon backup in 5s)
-    this.writeSessionToStore(session).catch(() => {});
-
-    // Log event
-    this.eventStore.append(
-      createEvent.sessionStart(sessionId, options.agent, {
-        project: options.project,
-        issue: options.issue,
-        worktree: cwd,
-      }),
-    );
-
-    // Determine spawn mode: terminal (default) or headless.
-    // --await always runs headless in foreground.
-    const useHeadless = options.headless || options.awaitCompletion;
-
-    const localBin = join(homedir(), ".local", "bin");
-    const pathWithLocalBin = process.env.PATH?.includes(localBin)
-      ? process.env.PATH
-      : `${localBin}:${process.env.PATH ?? ""}`;
-    const agentsPath = join(localBin, "abbie");
-    const sessionPath = join(this.basePath, `${sessionId}.json`);
-
-    // Load user secrets (API keys) if not already in environment.
-    const secretsEnv: Record<string, string> = {};
-    const secretsFile = join(homedir(), ".config", "zsh", "secrets", "env.zsh");
-    if (existsSync(secretsFile)) {
-      try {
-        const content = readFileSync(secretsFile, "utf-8");
-        for (const line of content.split("\n")) {
-          const match = line.match(/^\s*export\s+([A-Z_][A-Z0-9_]*)=["']?([^"'\n]*)["']?\s*$/);
-          if (match?.[1] && !process.env[match[1]]) {
-            secretsEnv[match[1]] = match[2];
-          }
-        }
-      } catch {
-        // Best-effort: secrets loading should never block session start
-      }
-    }
-
-    const runnerEnvShared: Record<string, string> = {
-      ...secretsEnv,
-      ...configEnv,
-      PATH: pathWithLocalBin,
-      AGENTS_RUNNER_SESSION_ID: sessionId,
-      AGENTS_RUNNER_SESSION_PATH: sessionPath,
-      AGENTS_RUNNER_PROMPT_PATH: promptPath,
-      AGENTS_RUNNER_OUTPUT_PATH: outputPath,
-      AGENTS_RUNNER_RESULT_PATH: resultPath,
-      AGENTS_RUNNER_STDOUT_PATH: stdoutPath,
-      AGENTS_RUNNER_STDERR_PATH: stderrPath,
-      AGENTS_RUNNER_AGENT: options.agent,
-      AGENTS_RUNNER_MODEL: options.model || "",
-      AGENTS_SESSION_ID: sessionId,
-      AGENTS_PROJECT: options.project,
-      AGENTS_TRACE_ID: traceId,
-    };
-
-    const runnerEnv = {
-      ...process.env,
-      ...runnerEnvShared,
-    };
-
-    if (!useHeadless) {
-      // TERMINAL MODE: spawn runner in a tmux window.
-      try {
-        const { newWindow, getPaneId, isRunning, listSessions } = await import("./tmux/bridge.js");
-        const { ensureManagedSession } = await import("./managed-session.js");
-
-        const tmuxSession = options.tmuxSession
-          ? options.tmuxSession
-          : await ensureManagedSession();
-
-        if (options.tmuxSession) {
-          const running = await isRunning();
-          const sessions = running ? await listSessions() : [];
-          const exists = sessions.some((s) => s.name === tmuxSession);
-          if (!exists) {
-            await new Promise<void>((resolve, reject) => {
-              const proc = spawn(
-                "tmux",
-                ["new-session", "-d", "-s", tmuxSession, "-n", "_abbie", "-c", homedir()],
-                { stdio: ["ignore", "ignore", "ignore"] },
-              );
-              proc.on("close", (code) => {
-                if (code === 0) resolve();
-                else reject(new Error(`Failed to create tmux session: ${tmuxSession}`));
-              });
-              proc.on("error", reject);
-            });
-          }
-        }
-
-        const launchScript = join(this.promptsPath, `${sessionId}-runner-launch.sh`);
-        const launchScriptContent = this.buildRunnerLaunchScript({
-          cwd,
-          agentsPath,
-          sessionId,
-          env: runnerEnvShared,
-        });
-        writeFileSync(launchScript, launchScriptContent, { mode: 0o755 });
-
-        const windowName = `${options.project}-${options.agent}-${sessionId.slice(-4)}`;
-        const command = `bash ${this.shellEscape(launchScript)}`;
-        await newWindow({ name: windowName, cwd, command, session: tmuxSession });
-
-        const paneId = await getPaneId(windowName, 0, tmuxSession);
-        session.spawn_mode = "terminal";
-        session.pane_id = paneId ?? undefined;
-        this.saveSession(session);
-
-        return {
-          session_id: sessionId,
-          pid: 0,
-          prompt_path: promptPath,
-          output_path: outputPath,
-          result_path: resultPath,
-          status: "spawned",
-          trace_id: traceId,
-          read_only: readOnly,
-        };
-      } catch (tmuxError) {
-        // tmux unavailable - fall through to headless.
-        const errMsg = (tmuxError as Error).message;
-        if (
-          !errMsg.includes("ENOENT") &&
-          !errMsg.includes("not found") &&
-          !errMsg.includes("no server")
-        ) {
-          session.status = "failed";
-          this.saveSession(session);
-          this.markSessionArtifactComplete(sessionId, {
-            status: "failed",
-            outputPath,
-          });
-          return {
-            session_id: sessionId,
-            pid: 0,
-            prompt_path: promptPath,
-            output_path: outputPath,
-            result_path: resultPath,
-            status: "failed",
-            error: `Terminal spawn failed: ${errMsg}`,
-            trace_id: traceId,
-            read_only: readOnly,
-          };
-        }
-      }
-    }
-
-    // HEADLESS MODE (--headless, --await, or tmux fallback)
-    session.spawn_mode = "headless";
-    this.saveSession(session);
-
-    try {
-      if (options.awaitCompletion) {
-        // AWAIT MODE: spawn runner in foreground and wait.
-        const runner = spawn(agentsPath, ["session", "run", sessionId], {
-          cwd,
-          env: runnerEnv,
-          stdio: ["ignore", "pipe", "pipe"],
-        });
-
-        if (!runner.pid) {
-          throw new Error("Failed to spawn runner process");
-        }
-
-        session.pid = runner.pid;
-        session.runner_pid = runner.pid;
-        this.saveSession(session);
-
-        const exitCode = await new Promise<number>((resolve) => {
-          runner.on("close", (code) => {
-            resolve(code ?? 1);
-          });
-          runner.on("error", () => {
-            resolve(1);
-          });
-        });
-
-        const finalSession = this.get(sessionId);
-        const finalPid = finalSession?.pid ?? runner.pid;
-
-        if (finalSession) {
-          if (finalSession.status === "completed") {
-            this.eventStore.append(
-              createEvent.complete(sessionId, options.agent, {
-                summary: "Session completed",
-                artifacts: [],
-                duration_ms: Date.now() - new Date(session.started_at).getTime(),
-              }),
-            );
-          } else if (finalSession.status === "failed") {
-            this.eventStore.append({
-              type: "session:failed",
-              session_id: sessionId,
-              agent: options.agent,
-              data: { reason: `Exit code ${exitCode}` },
-            });
-          }
-
-          this.markSessionArtifactComplete(sessionId, {
-            status:
-              finalSession.status === "completed"
-                ? "completed"
-                : finalSession.status === "stopped"
-                  ? "stopped"
-                  : "failed",
-            exitCode: finalSession.exit_code ?? exitCode,
-            outputPath: finalSession.output_path || outputPath,
-          });
-        }
-
-        return {
-          session_id: sessionId,
-          pid: finalPid,
-          prompt_path: promptPath,
-          output_path: outputPath,
-          result_path: resultPath,
-          status: "spawned",
-          trace_id: traceId,
-          read_only: readOnly,
-        };
-      }
-
-      // BACKGROUND MODE: spawn detached runner and return immediately.
-      const runner = spawn(agentsPath, ["session", "run", sessionId], {
-        cwd,
-        env: runnerEnv,
-        stdio: ["ignore", "ignore", "ignore"],
-        detached: true,
-      });
-
-      if (!runner.pid) {
-        throw new Error("Failed to spawn runner process");
-      }
-
-      session.pid = runner.pid;
-      session.runner_pid = runner.pid;
-      this.saveSession(session);
-      runner.unref();
-
-      return {
-        session_id: sessionId,
-        pid: runner.pid,
-        prompt_path: promptPath,
-        output_path: outputPath,
-        result_path: resultPath,
-        status: "spawned",
-        trace_id: traceId,
-        read_only: readOnly,
-      };
-    } catch (error) {
-      session.status = "failed";
-      this.saveSession(session);
-      this.markSessionArtifactComplete(sessionId, {
-        status: "failed",
-        outputPath,
-      });
-
-      return {
-        session_id: sessionId,
-        pid: 0,
-        prompt_path: promptPath,
-        output_path: outputPath,
-        result_path: resultPath,
-        status: "failed",
-        error: (error as Error).message,
-        trace_id: traceId,
-        read_only: readOnly,
-      };
-    }
-  }
-
-  /**
-   * Wait for a session to complete.
-   *
-   * With the runner pattern, the runner process writes canonical result.json.
-   * This method polls for that result envelope and returns it when available.
-   *
-   * Note: For --await mode, prefer using start({ awaitCompletion: true })
-   * which blocks on the runner directly instead of polling.
-   */
-  async await(
-    sessionId: string,
-    options?: {
-      pollIntervalMs?: number;
-      timeoutMs?: number;
-    },
-  ): Promise<{
-    status: "completed" | "failed" | "stopped" | "timeout";
-    output?: SessionResult;
-    error?: string;
-  }> {
-    const pollIntervalMs = Math.max(100, options?.pollIntervalMs ?? 1000);
-    const timeoutMs = options?.timeoutMs ?? 0; // 0 = no timeout (wait forever)
-    const startTime = Date.now();
-
-    const sleep = (ms: number) =>
-      new Promise<void>((resolve) => {
-        setTimeout(resolve, ms);
-      });
-
-    while (true) {
-      // Check timeout if configured
-      if (timeoutMs > 0 && Date.now() - startTime >= timeoutMs) {
-        return { status: "timeout", error: `Timed out after ${timeoutMs}ms` };
-      }
-
-      const session = this.get(sessionId);
-      if (!session) {
-        return { status: "failed", error: `Session not found: ${sessionId}` };
-      }
-
-      const resultPath =
-        session.result_path || getSessionLogPaths(sessionId, this.promptsPath).resultPath;
-      const result = readSessionResult(resultPath);
-      if (result) {
-        this.markSessionArtifactComplete(sessionId, {
-          status: result.status,
-          exitCode: result.exitCode ?? undefined,
-          outputPath: session.output_path,
-        });
-        return { status: result.status, output: result };
-      }
-
-      if (session.status !== "running") {
-        const normalizedStatus: "completed" | "failed" | "stopped" =
-          session.status === "completed"
-            ? "completed"
-            : session.status === "stopped"
-              ? "stopped"
-              : "failed";
-        const outputPath = session.output_path;
-        const artifactStatus: SessionArtifactStatus =
-          session.status === "completed"
-            ? "completed"
-            : session.status === "stopped"
-              ? "stopped"
-              : "failed";
-        this.markSessionArtifactComplete(sessionId, {
-          status: artifactStatus,
-          exitCode: session.exit_code,
-          outputPath,
-        });
-
-        return {
-          status: normalizedStatus,
-          error: `Result file not found: ${resultPath}`,
-        };
-      }
-
-      // Still running - check if runner/presentation process is alive.
-      let dead = false;
-      const runnerPid = session.runner_pid ?? session.pid;
-      if (runnerPid > 0 && !this.isProcessRunning(runnerPid)) {
-        dead = true;
-      } else if (
-        session.spawn_mode === "terminal" &&
-        runnerPid <= 0 &&
-        session.pane_id &&
-        !this.isTmuxPaneAlive(session.pane_id)
-      ) {
-        dead = true;
-      }
-
-      if (dead) {
-        // Process/pane died without updating status - mark as failed
-        await sleep(500); // Give a moment for file writes to flush
-        const updatedSession = this.get(sessionId);
-        if (updatedSession && updatedSession.status === "running") {
-          updatedSession.status = "failed";
-          this.saveSession(updatedSession);
-          this.markSessionArtifactComplete(sessionId, {
-            status: "failed",
-            exitCode: updatedSession.exit_code,
-            outputPath: updatedSession.output_path,
-          });
-        }
-        continue; // Loop will catch the updated status
-      }
-
-      await sleep(pollIntervalMs);
-    }
-  }
-
-  /**
-   * Get session by ID.
-   */
-  get(sessionId: string): ActiveSession | undefined {
-    const sessionPath = join(this.basePath, `${sessionId}.json`);
-    if (!existsSync(sessionPath)) {
-      return undefined;
-    }
-    return JSON.parse(readFileSync(sessionPath, "utf-8"));
-  }
-
-  /**
-   * List all active sessions.
-   */
-  list(options?: { status?: ActiveSession["status"]; project?: string }): ActiveSession[] {
-    const sessions: ActiveSession[] = [];
-
-    if (!existsSync(this.basePath)) {
-      return sessions;
-    }
-
-    const files = readdirSync(this.basePath).filter((f) => f.endsWith(".json"));
-
-    for (const file of files) {
-      const session: ActiveSession = JSON.parse(readFileSync(join(this.basePath, file), "utf-8"));
-
-      // Check if process is still running.
-      if (session.status === "running") {
-        if (session.pid > 0 && !this.isProcessRunning(session.pid)) {
-          // Headless runner died without updating status
-          session.status = "failed";
-          this.saveSession(session);
-          this.markSessionArtifactComplete(session.session_id, {
-            status: "failed",
-            exitCode: session.exit_code,
-            outputPath: session.output_path,
-          });
-        } else if (
-          session.spawn_mode === "terminal" &&
-          session.pane_id &&
-          !this.isTmuxPaneAlive(session.pane_id)
-        ) {
-          // Terminal pane is gone — agent died without mark-done
-          session.status = "failed";
-          this.saveSession(session);
-          this.markSessionArtifactComplete(session.session_id, {
-            status: "failed",
-            exitCode: session.exit_code,
-            outputPath: session.output_path,
-          });
-        }
-      }
-
-      // Apply filters
-      if (options?.status && session.status !== options.status) continue;
-      if (options?.project && session.project !== options.project) continue;
-
-      sessions.push(session);
-    }
-
-    return sessions.sort(
-      (a, b) => new Date(b.started_at).getTime() - new Date(a.started_at).getTime(),
-    );
-  }
-
-  /**
-   * Get all sessions spawned by a parent session.
-   */
-  getChildren(parentSessionId: string): ActiveSession[] {
-    return this.list().filter((session) => session.parent_session_id === parentSessionId);
-  }
-
-  /**
-   * Stop a running session.
-   */
-  stop(sessionId: string, signal: NodeJS.Signals = "SIGTERM"): boolean {
-    const session = this.get(sessionId);
-    if (!session) {
-      return false;
-    }
-
-    if (session.status !== "running") {
-      return false;
-    }
-
-    try {
-      const runnerPid = session.runner_pid ?? session.pid;
-      const agentPid = session.agent_pid;
-
-      const tryKill = (pid: number, sig: NodeJS.Signals) => {
-        if (pid <= 0) return false;
-        try {
-          process.kill(pid, sig);
-          return true;
-        } catch {
-          return false;
-        }
-      };
-
-      const tryKillGroup = (pgid: number, sig: NodeJS.Signals) => {
-        // Negative PID targets the process group on POSIX; not supported on Windows.
-        if (pgid <= 0) return false;
-        if (process.platform === "win32") return false;
-        try {
-          process.kill(-pgid, sig);
-          return true;
-        } catch {
-          return false;
-        }
-      };
-
-      // Runner-first stop path: signal runner PID / process group.
-      const killedRunner =
-        runnerPid > 0 ? tryKillGroup(runnerPid, signal) || tryKill(runnerPid, signal) : false;
-      const killedAgent =
-        agentPid !== undefined
-          ? tryKillGroup(agentPid, signal) || tryKill(agentPid, signal)
-          : false;
-
-      // Legacy fallback for pre-runner terminal sessions that never recorded a runner PID.
-      let signaledLegacy = false;
-      if (!killedRunner && !killedAgent && session.spawn_mode === "terminal" && session.pane_id) {
-        this.killPaneProcesses(session.pane_id, signal);
-        signaledLegacy = true;
-      }
-
-      if (!killedRunner && !killedAgent && !signaledLegacy) {
-        return false;
-      }
-
-      session.status = "stopped";
-      this.saveSession(session);
-      this.markSessionArtifactComplete(sessionId, {
-        status: "stopped",
-        exitCode: session.exit_code,
-        outputPath: session.output_path,
-      });
-
-      // Best-effort Convex update
-      this.updateSessionInStore(sessionId, "stopped").catch(() => {});
-
-      this.eventStore.append(
-        createEvent.complete(sessionId, session.agent, {
-          summary: "Session stopped by user",
-          artifacts: [],
-          duration_ms: Date.now() - new Date(session.started_at).getTime(),
-        }),
-      );
-
-      return true;
-    } catch {
-      return false;
-    }
-  }
-
-  /**
-   * Kill processes running inside a tmux pane.
-   * Used only as a legacy fallback for pre-runner terminal sessions.
-   */
-  private killPaneProcesses(paneId: string, signal: NodeJS.Signals = "SIGTERM"): void {
-    try {
-      // Get the shell PID running in the pane
-      const result = spawnSync("tmux", ["display-message", "-p", "-t", paneId, "#{pane_pid}"], {
-        stdio: ["ignore", "pipe", "ignore"],
-      });
-      if (result.status !== 0 || !result.stdout) return;
-
-      const shellPid = parseInt(result.stdout.toString().trim(), 10);
-      if (Number.isNaN(shellPid) || shellPid <= 0) return;
-
-      // Find all child processes of the shell (the agent and its children)
-      const psResult = spawnSync("pgrep", ["-P", String(shellPid)], {
-        stdio: ["ignore", "pipe", "ignore"],
-      });
-      if (psResult.status !== 0 || !psResult.stdout) return;
-
-      const childPids = psResult.stdout
-        .toString()
-        .trim()
-        .split("\n")
-        .map((p) => parseInt(p, 10))
-        .filter((p) => !Number.isNaN(p) && p > 0);
-
-      // Kill each child process group (agent spawns sub-processes)
-      for (const pid of childPids) {
-        try {
-          // Try killing the process group first (catches agent child processes)
-          process.kill(-pid, signal);
-        } catch {
-          try {
-            process.kill(pid, signal);
-          } catch {
-            // Process already gone
-          }
-        }
-      }
-    } catch {
-      // Best-effort fallback only.
-    }
-  }
-
-  /**
-   * Get events for a session.
-   */
-  getEvents(sessionId: string): ReturnType<EventStore["readSession"]> {
-    return this.eventStore.readSession(sessionId);
-  }
-
-  /**
-   * Clean up completed/failed sessions older than N days.
-   */
-  cleanup(daysOld: number = 7): number {
-    const cutoff = Date.now() - daysOld * 24 * 60 * 60 * 1000;
-    const sessions = this.list();
-    let cleaned = 0;
-
-    for (const session of sessions) {
-      if (session.status === "running") continue;
-
-      const sessionAge = new Date(session.started_at).getTime();
-      if (sessionAge < cutoff) {
-        this.deleteSession(session.session_id);
-        cleaned++;
-      }
-    }
-
-    return cleaned;
-  }
-
-  private shellEscape(value: string): string {
-    return `'${value.replace(/'/g, `'\\''`)}'`;
-  }
-
-  private buildRunnerLaunchScript(input: {
-    cwd: string;
-    agentsPath: string;
-    sessionId: string;
-    env: Record<string, string>;
-  }): string {
-    const lines = ["#!/usr/bin/env bash", "set -euo pipefail", `cd ${this.shellEscape(input.cwd)}`];
-
-    for (const [key, value] of Object.entries(input.env)) {
-      if (!/^[A-Z_][A-Z0-9_]*$/.test(key)) continue;
-      lines.push(`export ${key}=${this.shellEscape(String(value))}`);
-    }
-
-    lines.push(
-      `exec ${this.shellEscape(input.agentsPath)} session run ${this.shellEscape(input.sessionId)}`,
-    );
-    return `${lines.join("\n")}\n`;
-  }
-
-  /**
-   * Build prompt for agent.
-   */
-  /**
-   * Build workspace awareness context from other active sessions in the same cwd.
-   */
-  private getWorkspaceAwareness(cwd: string, excludeSessionId: string): string {
-    const sessions = this.list();
-    const siblings = sessions.filter(
-      (s) => s.cwd === cwd && s.session_id !== excludeSessionId && s.status === "running",
-    );
-
-    if (siblings.length === 0) return "";
-
-    const lines = siblings.map((s) => {
-      const agent = s.agent || "unknown";
-      const goal = s.goal ? `: ${s.goal.slice(0, 120)}` : "";
-      return `  - ${s.session_id} (${agent})${goal}`;
-    });
-
-    return `<workspace_awareness>
-Other active sessions in this workspace:
-${lines.join("\n")}
-
-Coordinate via context bus (traceId-scoped append-only log).
-Avoid editing the same files simultaneously. Check git status before committing.
-</workspace_awareness>
-
-`;
-  }
-
-  /**
-   * Fetch recent file_activity entries from contextBus for auto-context injection.
-   * Returns XML block listing files changed by prior sessions in this project.
-   */
-  private async getFileProvenanceContext(project: string): Promise<string> {
-    try {
-      const { getHttpClient, api } = await import("@creativeintelligence/sdk/convex");
-      const client = getHttpClient();
-      const entries = await client.query(api.contextBus.readByProject, {
-        project,
-        type: "file_activity",
-        since: Date.now() - 24 * 60 * 60 * 1000, // last 24h
-        limit: 10,
-      });
-
-      if (!entries || entries.length === 0) return "";
-
-      const lines: string[] = [];
-      for (const entry of entries) {
-        const meta = entry.metadata as Record<string, unknown> | undefined;
-        const agent = meta?.agent ?? "unknown";
-        const sessionId = entry.sessionId ?? "unknown";
-        let changes: Array<{ status: string; file: string }> = [];
-        try {
-          changes = JSON.parse(entry.content);
-        } catch {
-          continue;
-        }
-        if (changes.length === 0) continue;
-
-        lines.push(`  <session agent="${agent}" id="${sessionId}">`);
-        for (const c of changes.slice(0, 20)) {
-          lines.push(`    <file status="${c.status}">${c.file}</file>`);
-        }
-        if (changes.length > 20) {
-          lines.push(`    <!-- +${changes.length - 20} more files -->`);
-        }
-        lines.push("  </session>");
-      }
-
-      if (lines.length === 0) return "";
-
-      return `<file_provenance project="${project}" window="24h">
-Recent file changes by other agent sessions in this project:
-${lines.join("\n")}
-</file_provenance>
-
-`;
-    } catch {
-      return ""; // Best-effort: skip if Convex unavailable
-    }
-  }
-
-  private buildPrompt(
-    options: StartSessionOptions,
-    readOnly: boolean,
-    configEnhancements?: string,
-    awarenessContext?: string,
-    reinjectionContext?: string,
-    fileProvenanceContext?: string,
-  ): string {
-    const issueRef = options.issue ? `\nIssue: ${options.issue}` : "";
-    const readOnlyContract = readOnly ? this.getReadOnlyContract() : "";
-    const configBlock = configEnhancements ? `${configEnhancements}\n` : "";
-    const awareness = awarenessContext || "";
-    const reinjection = reinjectionContext || "";
-    const provenance = fileProvenanceContext || "";
-    const skillRouting = this.buildSkillRouting(options.skills);
-
-    return `${readOnlyContract}${configBlock}${awareness}${provenance}${reinjection}<session>
-Project: ${options.project}${issueRef}
-</session>
-${skillRouting}
-<goal>
-${options.goal}
-</goal>
-
-<exploration>
-Before implementing, explore the codebase:
-1. Run \`layer .\` to understand architecture
-2. Run \`outline\` on relevant directories to map code structure
-3. Use \`--callers\` and \`--callees\` to trace dependencies
-</exploration>
-
-<verification>
-After implementation:
-1. Run \`verify --format=summary\` to check tests
-2. Ensure no type errors
-3. Commit with descriptive message${options.issue ? ` referencing ${options.issue}` : ""}
-</verification>
-
-<output_contract>
-Conclude your work naturally — summarize what was done, the current state, and what comes next.
-
-If this session will be consumed by another agent or skill (not a human), also include this structured JSON at the END of your response for machine parsing:
-${readOnly ? getContractTemplate("exploration") : getContractTemplate("implementation")}
-
-When in doubt, write for a human reader first, then append the JSON block.
-</output_contract>
-`;
-  }
-
-  /**
-   * Build skill blocks that inject the full SKILL.md content so the spawned
-   * agent can actually follow the skill's decision trees, workflows, and patterns.
-   * The primary skill (first -s flag) is injected in full as the priority workflow.
-   * Supplementary skills are injected as available reference patterns.
-   */
-  private buildSkillRouting(skills?: string[]): string {
-    if (!skills || skills.length === 0) return "";
-
-    const skillsDir = join(homedir(), ".abbie", "skills");
-    const primary = skills[0];
-    const supplementary = skills.slice(1);
-
-    // Helper: read SKILL.md, strip YAML frontmatter, return body
-    const readSkillBody = (name: string): string | null => {
-      const skillPath = join(skillsDir, name, "SKILL.md");
-      if (!existsSync(skillPath)) return null;
-      const content = readFileSync(skillPath, "utf-8");
-      // Strip YAML frontmatter (---\n...\n---)
-      return content.replace(/^---\n[\s\S]*?\n---\n*/, "").trim();
-    };
-
-    const blocks: string[] = [];
-
-    // Primary skill: full content injection as priority workflow
-    const primaryBody = readSkillBody(primary);
-    if (primaryBody) {
-      blocks.push(`<skill name="${primary}" role="primary">
-Follow this skill as your priority workflow. Use its decision trees, patterns, and concrete values to guide your work.
-
-${primaryBody}
-</skill>`);
-    } else {
-      blocks.push(`<skill name="${primary}" role="primary">
-Invoke the \`${primary}\` skill to guide your workflow. (SKILL.md not found — use your knowledge of this skill.)
-</skill>`);
-    }
-
-    // Supplementary skills: full content as reference patterns
-    for (const name of supplementary) {
-      const body = readSkillBody(name);
-      if (body) {
-        blocks.push(`<skill name="${name}" role="supplementary">
-Available as a reference pattern. Use when relevant to your task.
-
-${body}
-</skill>`);
-      }
-    }
-
-    return blocks.join("\n\n") + "\n";
-  }
-
-  /**
-   * Get read-only contract to prepend to prompts.
-   */
-  private getReadOnlyContract(): string {
-    return `<read_only_contract>
-CRITICAL: This is a READ-ONLY session. You MUST NOT:
-- Create, modify, or delete any files
-- Run commands that modify state (git commit, npm install, etc.)
-- Make any changes to the filesystem
-
-You MAY:
-- Read files and explore the codebase
-- Run read-only commands (git status, git log, ls, cat, etc.)
-- Analyze code and provide recommendations
-- Generate output/analysis in your response
-
-If asked to make changes, explain what changes would be needed but DO NOT execute them.
-Violation of this contract will cause session termination.
-</read_only_contract>
-
-`;
-  }
-
-  /**
-   * Prepend read-only contract to existing content.
-   */
-  private prependReadOnlyContract(content: string): string {
-    return this.getReadOnlyContract() + content;
-  }
-
-  // NOTE: handleExit is no longer used - the runner handles exit status.
-  // Exit handling is now in src/lib/runner.ts
-
-  // =========================================================================
-  // Store Integration (best-effort Convex writes + async reads)
-  // =========================================================================
-
-  /**
-   * Write session to Convex store (best-effort, non-blocking).
-   * Called at session start for immediate Convex visibility.
-   */
-  private async writeSessionToStore(session: ActiveSession): Promise<void> {
-    try {
-      const { getHttpClient, api } = await import("@creativeintelligence/sdk/convex");
-      const client = getHttpClient();
-      await client.mutation(api.sessions.create, {
-        sessionId: session.session_id,
-        agent: session.agent as "claude" | "codex" | "copilot" | "gemini",
-        project: session.project,
-        goal: session.goal,
-        issue: session.issue,
-        status: session.status === "running" ? "running" : "spawned",
-        pid: session.pid > 0 ? session.pid : undefined,
-        cwd: session.cwd,
-        deviceId: getDeviceId(),
-        parentSessionId: session.parent_session_id,
-        traceId: session.trace_id,
-        traceUrl: session.trace_url,
-        promptPath: session.prompt_path,
-        outputPath: session.output_path,
-        startCommitSha: session.start_commit_sha,
-        metadata: {
-          readOnly: session.read_only,
-          spawnMode: session.spawn_mode,
-          resultPath: session.result_path,
-          stdoutPath: session.stdout_path,
-          stderrPath: session.stderr_path,
-        },
-      });
-    } catch {
-      // Best-effort: daemon picks it up within 5s
-    }
-  }
-
-  /**
-   * Update session status in Convex store (best-effort, non-blocking).
-   */
-  private async updateSessionInStore(
-    sessionId: string,
-    status: string,
-    metadata?: Record<string, unknown>,
-  ): Promise<void> {
-    try {
-      const { getHttpClient, api } = await import("@creativeintelligence/sdk/convex");
-      const client = getHttpClient();
-      await client.mutation(api.sessions.update, {
-        sessionId,
-        status: status as "completed" | "stopped" | "failed" | "running",
-        endedAt: ["completed", "stopped", "failed"].includes(status) ? Date.now() : undefined,
-        metadata,
-      });
-    } catch {
-      // Best-effort: daemon picks it up within 5s
-    }
-  }
-
-  /**
-   * Get session by ID from Convex store with local fallback.
-   */
-  async getAsync(sessionId: string): Promise<ActiveSession | undefined> {
-    try {
-      const { getHttpClient, api } = await import("@creativeintelligence/sdk/convex");
-      const client = getHttpClient();
-      const storeSession = await client.query(api.sessions.get, { sessionId });
-      if (storeSession) {
-        return this.storeSessionToActive(
-          storeSession as unknown as Parameters<typeof this.storeSessionToActive>[0],
-        );
-      }
-    } catch {
-      // Fall through to local
-    }
-    return this.get(sessionId);
-  }
-
-  /**
-   * List sessions from Convex store with local fallback.
-   */
-  async listAsync(options?: {
-    status?: ActiveSession["status"];
-    project?: string;
-    limit?: number;
-  }): Promise<ActiveSession[]> {
-    try {
-      const { getHttpClient, api } = await import("@creativeintelligence/sdk/convex");
-      const client = getHttpClient();
-      const deviceId = getDeviceId();
-      const storeSessions = await client.query(api.sessions.list, {
-        status: options?.status,
-        project: options?.project,
-        deviceId,
-        limit: options?.limit ?? 50,
-      });
-
-      if (storeSessions.length > 0) {
-        const sessions = storeSessions.map((s) =>
-          this.storeSessionToActive(
-            s as unknown as Parameters<typeof this.storeSessionToActive>[0],
-          ),
-        );
-        // PID liveness sweep for running sessions
-        for (const session of sessions) {
-          if (
-            session.status === "running" &&
-            session.pid > 0 &&
-            !this.isProcessRunning(session.pid)
-          ) {
-            session.status = "failed";
-          }
-        }
-        return sessions;
-      }
-    } catch {
-      // Fall through to local
-    }
-    return this.list(options);
-  }
-
-  /**
-   * Get active sessions from Convex store with local fallback.
-   */
-  async getActiveAsync(): Promise<ActiveSession[]> {
-    try {
-      const { getHttpClient, api } = await import("@creativeintelligence/sdk/convex");
-      const client = getHttpClient();
-      const deviceId = getDeviceId();
-      const storeSessions = await client.query(api.sessions.getActive, { deviceId });
-
-      if (storeSessions.length > 0) {
-        const sessions = storeSessions.map((s) =>
-          this.storeSessionToActive(
-            s as unknown as Parameters<typeof this.storeSessionToActive>[0],
-          ),
-        );
-        // PID liveness sweep
-        for (const session of sessions) {
-          if (
-            session.status === "running" &&
-            session.pid > 0 &&
-            !this.isProcessRunning(session.pid)
-          ) {
-            session.status = "failed";
-            this.updateSessionInStore(session.session_id, "failed").catch(() => {});
-          }
-        }
-        return sessions;
-      }
-    } catch {
-      // Fall through to local
-    }
-    return this.list({ status: "running" });
-  }
-
-  /**
-   * Convert store Session to ActiveSession format.
-   */
-  private storeSessionToActive(s: {
-    sessionId: string;
-    agent: string;
-    project: string;
-    goal?: string;
-    issue?: string;
-    status: string;
-    pid?: number;
-    cwd: string;
-    startedAt: number;
-    traceId?: string;
-    traceUrl?: string;
-    parentSessionId?: string;
-    promptPath?: string;
-    outputPath?: string;
-    metadata?: Record<string, unknown>;
-  }): ActiveSession {
-    const meta = (s.metadata ?? {}) as Record<string, unknown>;
-    return {
-      session_id: s.sessionId,
-      agent: s.agent as AgentType,
-      project: s.project,
-      goal: s.goal ?? "",
-      issue: s.issue,
-      cwd: s.cwd,
-      pid: s.pid ?? 0,
-      started_at: new Date(s.startedAt).toISOString(),
-      status: s.status === "spawned" ? "running" : (s.status as ActiveSession["status"]),
-      prompt_path: s.promptPath,
-      output_path: s.outputPath,
-      result_path: (meta.resultPath as string | undefined) ?? undefined,
-      stdout_path: (meta.stdoutPath as string | undefined) ?? undefined,
-      stderr_path: (meta.stderrPath as string | undefined) ?? undefined,
-      trace_id: s.traceId,
-      trace_url: s.traceUrl,
-      parent_session_id: s.parentSessionId,
-      read_only: meta.readOnly as boolean | undefined,
-      spawn_mode: meta.spawnMode as "terminal" | "headless" | "nvim-terminal" | undefined,
-    };
-  }
-
-  /**
-   * Save session to disk.
-   */
-  private saveSession(session: ActiveSession): void {
-    const sessionPath = join(this.basePath, `${session.session_id}.json`);
-    const tmpPath = `${sessionPath}.tmp`;
-    writeFileSync(tmpPath, JSON.stringify(session, null, 2));
-    renameSync(tmpPath, sessionPath);
-  }
-
-  private saveSessionArtifactStart(session: ActiveSession): void {
-    try {
-      this.artifactStore.saveStart({
-        sessionId: session.session_id,
-        agent: session.agent,
-        project: session.project,
-        status: session.status,
-        startedAt: session.started_at,
-        issue: session.issue,
-        traceId: session.trace_id,
-        goal: session.goal,
-        promptPath: session.prompt_path,
-        outputPath: session.output_path,
-      });
-    } catch {
-      // Best-effort: active session files remain source of truth.
-    }
-  }
-
-  private markSessionArtifactComplete(
-    sessionId: string,
-    opts: {
-      status: SessionArtifactStatus;
-      exitCode?: number;
-      outputPath?: string;
-    },
-  ): void {
-    try {
-      this.artifactStore.markComplete(sessionId, {
-        status: opts.status,
-        exitCode: opts.exitCode,
-        outputPath: opts.outputPath,
-      });
-    } catch {
-      // Best-effort: active session files remain source of truth.
-    }
-  }
-
-  /**
-   * Delete session from disk.
-   */
-  private deleteSession(sessionId: string): void {
-    const sessionPath = join(this.basePath, `${sessionId}.json`);
-    if (existsSync(sessionPath)) {
-      unlinkSync(sessionPath);
-    }
-  }
-
-  /**
-   * Check if a process is running.
-   */
-  private isProcessRunning(pid: number): boolean {
-    if (pid <= 0) return false;
-    try {
-      process.kill(pid, 0);
-      return true;
-    } catch {
-      return false;
-    }
-  }
-
-  /**
-   * Check if a tmux pane is still alive.
-   * Uses list-panes which returns exit 1 for nonexistent targets
-   * (display-message returns 0 even for dead panes).
-   */
-  private isTmuxPaneAlive(paneId: string): boolean {
-    const result = spawnSync("tmux", ["list-panes", "-t", paneId], {
-      stdio: ["ignore", "ignore", "ignore"],
-    });
-    return result.status === 0;
-  }
-}
-
-/**
- * Singleton instance.
- */
-let _manager: ActiveSessionManager | undefined;
-
-export function getActiveSessionManager(): ActiveSessionManager {
-  if (!_manager) {
-    _manager = new ActiveSessionManager();
-  }
-  return _manager;
-}