@os-eco/overstory-cli 0.8.2 → 0.8.4

package/src/runtimes/codex.ts

@@ -2,10 +2,10 @@
 // Implements the AgentRuntime contract for the OpenAI `codex` CLI.
 //
 // Key differences from Claude/Pi adapters:
-// - Headless: `codex exec` exits on completion (no persistent TUI)
+// - Interactive: `codex` (without `exec`) stays alive in tmux for orchestration
 // - Instruction file: AGENTS.md (not .claude/CLAUDE.md)
 // - No hooks: Codex uses OS-level sandbox (Seatbelt/Landlock)
-// - Events: NDJSON stream to stdout (parsed for token usage)
+// - One-shot calls still use `codex exec` (buildPrintCommand)
 
 import { mkdir } from "node:fs/promises";
 import { dirname, join } from "node:path";
@@ -22,9 +22,9 @@ import type {
 /**
  * Codex runtime adapter.
  *
- * Implements AgentRuntime for the OpenAI `codex` CLI. Codex agents run in
- * headless mode (`codex exec`) — they process a task and exit, rather than
- * maintaining a persistent TUI like Claude Code or Pi.
+ * Implements AgentRuntime for the OpenAI `codex` CLI. Tmux-spawned Codex
+ * agents run in interactive mode (`codex`) so sessions stay alive and can be
+ * nudged via tmux.
  *
  * Security is enforced via Codex's OS-level sandbox (Seatbelt on macOS,
  * Landlock on Linux) rather than hook-based guards. The `--full-auto` flag
@@ -40,11 +40,17 @@ export class CodexRuntime implements AgentRuntime {
 	/** Relative path to the instruction file within a worktree. */
 	readonly instructionPath = "AGENTS.md";
 
+	/**
+	 * Anthropic aliases used by overstory manifests that Codex CLI does not
+	 * accept as --model values.
+	 */
+	private static readonly MANIFEST_ALIASES = new Set(["sonnet", "opus", "haiku"]);
+
 	/**
 	 * Build the shell command string to spawn a Codex agent in a tmux pane.
 	 *
-	 * Uses `codex exec` (headless mode) with `--full-auto` for workspace-write
-	 * sandbox + automatic approvals, and `--json` for NDJSON event output.
+	 * Uses interactive `codex` with `--full-auto` for workspace-write sandbox +
+	 * automatic approvals.
 	 *
 	 * The prompt directs the agent to read AGENTS.md for its full instructions.
 	 * If `appendSystemPrompt` or `appendSystemPromptFile` is provided, the
@@ -56,7 +62,12 @@ export class CodexRuntime implements AgentRuntime {
 	 * @returns Shell command string suitable for tmux new-session -c
 	 */
 	buildSpawnCommand(opts: SpawnOpts): string {
-		let cmd = `codex exec --full-auto --json --model ${opts.model}`;
+		// When model comes from default manifest aliases (sonnet/opus/haiku),
+		// omit --model so Codex uses the user's configured default model.
+		let cmd = "codex --full-auto";
+		if (!CodexRuntime.MANIFEST_ALIASES.has(opts.model)) {
+			cmd += ` --model ${opts.model}`;
+		}
 
 		if (opts.appendSystemPromptFile) {
 			// Read role definition from file at shell expansion time — avoids tmux
@@ -128,11 +139,7 @@ export class CodexRuntime implements AgentRuntime {
 	}
 
 	/**
-	 * Codex exec is headless — always ready.
-	 *
-	 * Unlike Claude Code and Pi which maintain persistent TUI sessions,
-	 * `codex exec` starts processing immediately and exits on completion.
-	 * No TUI readiness detection is needed.
+	 * Codex interactive startup is treated as ready once a pane exists.
 	 *
 	 * @param _paneContent - Captured tmux pane content (unused)
 	 * @returns Always `{ phase: "ready" }`
@@ -144,9 +151,7 @@ export class CodexRuntime implements AgentRuntime {
 	/**
 	 * Codex does not require beacon verification/resend.
 	 *
-	 * The beacon verification loop exists because Claude Code's TUI sometimes
-	 * swallows the initial Enter during late initialization. Codex exec is
-	 * headless — it processes the prompt immediately with no TUI startup delay.
+	 * Codex accepts startup input reliably once spawned.
 	 */
 	requiresBeaconVerification(): boolean {
 		return false;
@@ -225,4 +230,9 @@ export class CodexRuntime implements AgentRuntime {
 	buildEnv(model: ResolvedModel): Record<string, string> {
 		return model.env ?? {};
 	}
+
+	/** Codex does not produce transcript files. */
+	getTranscriptDir(_projectRoot: string): string | null {
+		return null;
+	}
 }

package/src/runtimes/copilot.ts

@@ -223,4 +223,9 @@ export class CopilotRuntime implements AgentRuntime {
 	buildEnv(model: ResolvedModel): Record<string, string> {
 		return model.env ?? {};
 	}
+
+	/** Copilot does not produce transcript files. */
+	getTranscriptDir(_projectRoot: string): string | null {
+		return null;
+	}
 }

package/src/runtimes/gemini.ts

@@ -232,4 +232,9 @@ export class GeminiRuntime implements AgentRuntime {
 	buildEnv(model: ResolvedModel): Record<string, string> {
 		return model.env ?? {};
 	}
+
+	/** Gemini does not produce transcript files. */
+	getTranscriptDir(_projectRoot: string): string | null {
+		return null;
+	}
 }

package/src/runtimes/pi.ts

@@ -245,4 +245,9 @@ export class PiRuntime implements AgentRuntime {
 	buildEnv(model: ResolvedModel): Record<string, string> {
 		return model.env ?? {};
 	}
+
+	/** Pi uses RPC — no transcript files. */
+	getTranscriptDir(_projectRoot: string): string | null {
+		return null;
+	}
 }

package/src/runtimes/registry.test.ts

@@ -117,4 +117,40 @@ describe("getRuntime", () => {
 		expect(runtime).toBeInstanceOf(GeminiRuntime);
 		expect(runtime.id).toBe("gemini");
 	});
+
+	describe("capability routing", () => {
+		it("resolves capability-specific runtime from config", () => {
+			const config = {
+				runtime: { default: "claude", capabilities: { builder: "gemini" } },
+			} as unknown as OverstoryConfig;
+			const runtime = getRuntime(undefined, config, "builder");
+			expect(runtime).toBeInstanceOf(GeminiRuntime);
+			expect(runtime.id).toBe("gemini");
+		});
+
+		it("falls back to default when capability has no override", () => {
+			const config = {
+				runtime: { default: "codex", capabilities: { builder: "gemini" } },
+			} as unknown as OverstoryConfig;
+			const runtime = getRuntime(undefined, config, "scout");
+			expect(runtime).toBeInstanceOf(CodexRuntime);
+			expect(runtime.id).toBe("codex");
+		});
+
+		it("explicit name overrides capability routing", () => {
+			const config = {
+				runtime: { default: "claude", capabilities: { builder: "gemini" } },
+			} as unknown as OverstoryConfig;
+			const runtime = getRuntime("copilot", config, "builder");
+			expect(runtime).toBeInstanceOf(CopilotRuntime);
+			expect(runtime.id).toBe("copilot");
+		});
+
+		it("works when capabilities is undefined", () => {
+			const config = { runtime: { default: "claude" } } as OverstoryConfig;
+			const runtime = getRuntime(undefined, config, "coordinator");
+			expect(runtime).toBeInstanceOf(ClaudeRuntime);
+			expect(runtime.id).toBe("claude");
+		});
+	});
 });

package/src/runtimes/registry.ts

@@ -20,24 +20,54 @@ const runtimes = new Map<string, () => AgentRuntime>([
 	["sapling", () => new SaplingRuntime()],
 ]);
 
+/**
+ * Return all registered runtime adapter instances.
+ *
+ * Used by callers that need to enumerate all runtimes (e.g. to build a
+ * dynamic list of known instruction file paths from each runtime's
+ * `instructionPath` property).
+ *
+ * @returns Array of one fresh instance per registered runtime.
+ */
+export function getAllRuntimes(): AgentRuntime[] {
+	return [
+		new ClaudeRuntime(),
+		new CodexRuntime(),
+		new PiRuntime(),
+		new CopilotRuntime(),
+		new GeminiRuntime(),
+		new SaplingRuntime(),
+	];
+}
+
 /**
  * Resolve a runtime adapter by name.
  *
  * Lookup order:
  * 1. Explicit `name` argument (if provided)
- * 2. `config.runtime.default` (if config is provided)
- * 3. `"claude"` (hardcoded fallback)
+ * 2. `config.runtime.capabilities[capability]` (if capability provided)
+ * 3. `config.runtime.default` (if config is provided)
+ * 4. `"claude"` (hardcoded fallback)
  *
  * Special cases:
  * - Pi runtime receives `config.runtime.pi` for model alias expansion.
  *
  * @param name - Runtime name to resolve (e.g. "claude"). Omit to use config default.
  * @param config - Overstory config for reading the default runtime.
+ * @param capability - Agent capability (e.g. "coordinator", "builder") for per-capability routing.
  * @throws {Error} If the resolved runtime name is not registered.
  * @returns A fresh AgentRuntime instance.
  */
-export function getRuntime(name?: string, config?: OverstoryConfig): AgentRuntime {
-	const runtimeName = name ?? config?.runtime?.default ?? "claude";
+export function getRuntime(
+	name?: string,
+	config?: OverstoryConfig,
+	capability?: string,
+): AgentRuntime {
+	const capabilityRuntime =
+		capability && config?.runtime?.capabilities
+			? config.runtime.capabilities[capability]
+			: undefined;
+	const runtimeName = name ?? capabilityRuntime ?? config?.runtime?.default ?? "claude";
 
 	// Pi runtime needs config for model alias expansion.
 	if (runtimeName === "pi") {

package/src/runtimes/sapling.ts

@@ -695,4 +695,9 @@ export class SaplingRuntime implements AgentRuntime {
 
 		return env;
 	}
+
+	/** Sapling uses NDJSON event streaming — no transcript files. */
+	getTranscriptDir(_projectRoot: string): string | null {
+		return null;
+	}
 }

package/src/runtimes/types.ts

@@ -184,6 +184,15 @@ export interface AgentRuntime {
 	 */
 	parseTranscript(path: string): Promise<TranscriptSummary | null>;
 
+	/**
+	 * Return the directory containing session transcript files for this runtime,
+	 * or null if transcript discovery is not supported.
+	 *
+	 * @param projectRoot - Absolute path to the project root
+	 * @returns Absolute path to the transcript directory, or null
+	 */
+	getTranscriptDir(projectRoot: string): string | null;
+
 	/**
 	 * Build runtime-specific environment variables for model/provider routing.
 	 * Claude Code uses ANTHROPIC_API_KEY; Codex uses OPENAI_API_KEY; Pi passes

package/src/types.ts

@@ -97,6 +97,11 @@ export interface OverstoryConfig {
 	runtime?: {
 		/** Default runtime adapter name (default: "claude"). */
 		default: string;
+		/**
+		 * Per-capability runtime overrides. Maps capability names (e.g. "coordinator", "builder")
+		 * to runtime adapter names. Lookup chain: explicit --runtime flag > capabilities[cap] > default > "claude".
+		 */
+		capabilities?: Partial<Record<string, string>>;
 		/**
 		 * Runtime adapter for headless one-shot AI calls (--print mode).
 		 * Used by merge/resolver.ts and watchdog/triage.ts.
@@ -343,6 +348,8 @@ export interface OverlayConfig {
 	trackerName?: string; // "seeds" or "beads"
 	/** Quality gate commands for the agent overlay. Falls back to defaults if undefined. */
 	qualityGates?: QualityGate[];
+	/** Relative path to the instruction file within the worktree (runtime-specific). Defaults to .claude/CLAUDE.md. */
+	instructionPath?: string;
 }
 
 // === Merge Queue ===